# Epic 2: Session Lifecycle (Finite State Machine + Projection Layer)

**status:** proposed
**date:** 08.05.2026 (May)
**scope:** `:core:sessions` (depends on `:core:events`)

---

## context

With a stable event log (Epic 1 complete), Correx now needs a structured runtime abstraction that turns raw events into meaningful execution units.

A session is the primary unit of work in the system:

* it represents a single interactive or automated workflow
* it evolves over time through events
* it must be reconstructible from the event log (replayable state)

Without a session layer, events remain unstructured history with no execution semantics.

---

## goal

Introduce a **deterministic session lifecycle system** built on top of events:

> a finite state machine + projection model that reconstructs session state from the event stream

---

## scope (what IS included)

### 1. session model

Define `Session` as a projection, not stored state:

* `sessionId`
* `status`
* `createdAt`
* `updatedAt`
* derived metadata (optional: stage, counters, flags)

Session state is **derived from events only**, never mutated directly.

---

### 2. session states (FSM)

Define explicit lifecycle states:

* `CREATED`
* `ACTIVE`
* `PAUSED`
* `COMPLETED`
* `FAILED`
* `REPLAYED` (optional diagnostic state)

Transitions are strictly event-driven.

---

### 3. session events (from Epic 1)

Introduce interpretation layer over existing events:

* `SessionStarted`
* `SessionPaused`
* `SessionResumed`
* `SessionCompleted`
* `SessionFailed`

These are stored in `:core:events`, not duplicated.

---

### 4. session projection builder

Implement:

> `SessionProjector`

Responsibilities:

* consumes ordered `EventEnvelope` stream
* rebuilds current session state
* applies deterministic reduction logic

Rules:

* pure function behavior (events → state)
* no side effects
* replay-safe

---

### 5. transition rules (FSM logic)

Define strict rules:

* invalid transitions must be rejected during projection validation
* transitions are derived from event sequences, not external mutation
* last valid state wins (replay consistency rule)

Example:

* `CREATED → ACTIVE` allowed
* `ACTIVE → COMPLETED` allowed
* `COMPLETED → ACTIVE` invalid (ignored or flagged)

---

### 6. session repository

Provide abstraction:

* `getSession(sessionId): Session`
* `getAllSessions()`
* `rebuild(sessionId)` (replay from events)

Backed entirely by `EventStore`.

---

### 7. minimal runtime behavior (no orchestration yet)

Session layer only:

* no kernel execution
* no tool execution
* no transitions engine
* no approvals

It is purely **state interpretation over events**

---

### 8. test coverage

* session reconstruction from event stream
* invalid transition detection
* replay determinism (same events → same session state)
* multi-event lifecycle correctness
* empty session handling

---

## explicit exclusions

Epic 2 does NOT include:

* workflow graph / transitions engine (`:core:transitions`)
* approval system (`:core:approvals`)
* tool execution (`:core:tools`)
* inference or routing
* context compression
* orchestration kernel

---

## consequences

### positive

* introduces first meaningful domain abstraction over events
* enables reasoning about execution lifecycle
* provides foundation for orchestration layer
* makes replay human-interpretable (not just raw logs)
* isolates state interpretation logic from persistence

### negative

* introduces FSM complexity early in system lifecycle
* requires strict discipline to avoid state mutation leaks
* projection correctness becomes critical dependency for all higher layers
* may require refactoring if event types evolve significantly

---

## rationale

Events alone are insufficient for system reasoning.

A session layer is required to:

> translate raw event history into structured execution semantics

This is the first step from:

* “log of facts”
  to
* “interpretable system state”

---

## status

Epic 2 becomes valid only after:

* Epic 1 is complete ✔
* EventStore contract is stable ✔
* replay guarantees are verified ✔

It is the **first domain layer built on top of the event system**, and the first step toward orchestration.