---
name: "Core Sessions Submodule Spec"
description: "Specification for :core:sessions – lifecycle FSM and projection"
depth: 2
links: ["../index.md", "../architecture/replay-model.md", "./core-module-spec.md"]
---

# :core:sessions module specification

version: 0.1-draft
status: foundational specification

---

# 1. purpose

`:core:sessions` defines the canonical execution lifecycle model for correx sessions.

It is the authoritative subsystem for:

* session lifecycle semantics
* execution ownership
* runtime state transitions
* cancellation semantics
* recovery semantics
* session-scoped coordination
* execution isolation boundaries

A session represents:

* one bounded orchestration lifecycle
* one authoritative execution timeline
* one isolated event stream scope

---

# 2. responsibilities

`:core:sessions` owns:

* session lifecycle FSM
* session identity contracts
* session state semantics
* execution ownership rules
* cancellation semantics
* pause/resume semantics
* recovery semantics
* session projections
* session-scoped concurrency guarantees
* session termination semantics

---

# 3. non-responsibilities

`:core:sessions` MUST NOT own:

* orchestration execution logic
* transition evaluation
* persistence implementations
* websocket session management
* user authentication
* provider lifecycle management
* model execution
* UI session rendering

Implementations belong to other modules.

---

# 4. architectural role

`:core:sessions` acts as:

* execution boundary authority
* lifecycle authority
* session isolation authority
* runtime ownership authority

All workflow execution MUST occur inside a valid session lifecycle.

---

# 5. design principles

## 5.1 sessions are bounded

Sessions are finite execution scopes.

Sessions MUST:

* begin explicitly
* terminate explicitly
* remain replayable
* remain isolated

Infinite implicit execution is forbidden.

---

## 5.2 sessions own orchestration scope

Everything occurring during workflow execution MUST belong to:

* exactly one session

Cross-session mutation is forbidden.

---

## 5.3 lifecycle is deterministic

Session state transitions MUST be:

* explicit
* evented
* replayable
* validated

Hidden lifecycle mutation is forbidden.

---

## 5.4 cancellation is first-class

Cancellation MUST propagate deterministically through:

* orchestration
* inference
* tools
* transitions
* approvals

Zombie execution is forbidden.

---

# 6. session model

## base session contract

```kotlin
sealed interface Session {
    val id: SessionId
    val state: SessionState
    val createdAt: Instant
    val updatedAt: Instant
    val correlationId: CorrelationId
}
```

---

# 7. session states

Mandatory lifecycle states:

```text
CREATED
INITIALIZING
ACTIVE
PAUSED
AWAITING_APPROVAL
CANCELLING
CANCELLED
FAILED
COMPLETED
RECOVERING
```

---

# 8. lifecycle guarantees

## required guarantees

Sessions MUST:

* have exactly one active lifecycle state
* emit events for all state transitions
* terminate deterministically
* preserve replay consistency

---

## forbidden behavior

Forbidden:

* silent state mutation
* implicit recovery
* orphaned execution
* detached execution scopes
* state mutation without events

---

# 9. lifecycle transition rules

Example lifecycle graph:

```text
CREATED
  ↓
INITIALIZING
  ↓
ACTIVE
  ├──→ PAUSED
  ├──→ AWAITING_APPROVAL
  ├──→ FAILED
  ├──→ CANCELLING
  └──→ COMPLETED
```

Recovery paths MUST be explicit.

Invalid transitions MUST fail validation.

---

# 10. session ownership model

A session owns:

* execution scope
* orchestration scope
* workflow scope
* event stream scope
* approval scope
* context synthesis scope

Everything executed within a session MUST reference:

* sessionId
* correlationId

---

# 11. session projections

Mandatory projections:

```text
SessionStateProjection
SessionLifecycleProjection
SessionExecutionProjection
SessionApprovalProjection
SessionFailureProjection
```

Projections MUST remain:

* rebuildable
* disposable
* deterministic

---

# 12. concurrency model

## required guarantees

Within a session:

* execution ordering MUST remain deterministic
* cancellation MUST propagate transitively
* lifecycle transitions MUST be atomic

---

## session isolation

Sessions MUST remain isolated from each other.

Forbidden:

* shared mutable orchestration state
* cross-session context mutation
* shared execution ownership

---

# 13. cancellation semantics

Cancellation MUST:

* emit events
* propagate recursively
* terminate child execution scopes
* interrupt pending orchestration safely

Cancellation MUST support:

* graceful cancellation
* forced termination
* timeout escalation

---

# 14. pause/resume semantics

Paused sessions MUST:

* preserve replay integrity
* preserve event ordering
* suspend active execution safely

Resuming MUST emit explicit lifecycle events.

---

# 15. approval suspension semantics

When awaiting approval:

* execution MUST suspend
* transition scheduling MUST pause
* inference MUST stop

Only approval decisions may resume execution.

---

# 16. recovery semantics

Recovery MUST be event-driven.

Recovery MAY occur after:

* crash
* restart
* provider failure
* infrastructure interruption

Recovery MUST NOT require:

* original process state
* in-memory orchestration state
* active model residency

---

# 17. replay guarantees

Session replay MUST support:

* lifecycle reconstruction
* transition reconstruction
* cancellation reconstruction
* approval reconstruction
* failure reconstruction

Replay MUST deterministically reproduce:

* session state
* projections
* orchestration decisions

---

# 18. observability requirements

`:core:sessions` MUST expose telemetry hooks for:

* lifecycle transitions
* session duration
* cancellation propagation
* failure timelines
* replay reconstruction
* approval waiting time
* execution suspension timing

---

# 19. failure semantics

Session failures MUST:

* emit structured failure events
* preserve historical integrity
* preserve replayability
* preserve partial execution history

Failures MUST NOT:

* corrupt event streams
* bypass lifecycle transitions
* silently terminate execution

---

# 20. timeout semantics

Sessions MAY define:

* execution timeout
* inactivity timeout
* approval timeout
* recovery timeout

Timeout expiration MUST emit lifecycle events.

---

# 21. security boundaries

Sessions define execution isolation boundaries.

Session isolation MUST apply to:

* orchestration
* context synthesis
* approvals
* tools
* inference execution

Unauthorized cross-session access is forbidden.

---

# 22. extension model

Extensions MAY:

* define additional session metadata
* define custom projections
* define lifecycle observers

Extensions MUST NOT:

* bypass lifecycle validation
* mutate session state directly
* bypass cancellation semantics
* introduce hidden execution state

---

# 23. forbidden patterns

Forbidden:

* global orchestration state
* implicit session resurrection
* detached execution
* hidden lifecycle mutation
* orphaned child scopes
* mutable session history
* replay-dependent lifecycle behavior

---

# 24. persistence expectations

Persistence implementations MUST support:

* durable session lifecycle history
* replay-safe reconstruction
* snapshot-compatible recovery
* deterministic session rebuild

Persistence mechanics belong to infrastructure modules.

---

# 25. testing requirements

`:core:sessions` MUST support deterministic testing for:

* lifecycle transitions
* cancellation propagation
* pause/resume behavior
* timeout handling
* recovery flows
* replay reconstruction
* concurrency isolation

---

# 26. philosophy summary

`:core:sessions` exists to provide deterministic execution boundaries around orchestration workflows.

Reliability emerges from:

* explicit lifecycle ownership
* bounded execution
* deterministic cancellation
* replayable state transitions
* isolated execution scopes

not from long-lived mutable runtime state.