kami
9734eec63c
Generated by per-group subagents covering all 52 modules across: core (18), infrastructure (10), apps (5), interfaces (3), plugins (7), testing (9) Documentation format: - AsciiDoc (.adoc) files in docs/modules/<group>/ - PlantUML (.puml) files in docs/diagrams/ - .adoc files reference diagrams via include:: directives Each doc covers: purpose, responsibilities, non-responsibilities, key types, event flow, integration points, invariants, PlantUML diagram, known issues, and open questions.
117 lines
5.1 KiB
Plaintext
117 lines
5.1 KiB
Plaintext
= core-sessions
|
|
|
|
== purpose
|
|
|
|
Defines the session lifecycle model: session creation, status transitions (created → active → paused/completed/failed), and the projection infrastructure for rebuilding session state from events. Sessions are the top-level unit of work in Correx — a single workflow execution that produces artifacts and consumes LLM inference.
|
|
|
|
== responsibilities
|
|
|
|
* Defines `SessionState` (status, timestamps, invalid transition count) and `SessionStatus` enum (CREATED, ACTIVE, PAUSED, COMPLETED, FAILED)
|
|
* Implements `SessionReducer` (interface) and `DefaultSessionReducer` (concrete) — translates session and stage lifecycle events into `SessionState` changes
|
|
* Provides `SessionProjector` — adapts `SessionReducer` into the `Projection<SessionState>` interface for use with the replay infrastructure
|
|
* Provides `DefaultSessionRepository` — rebuilds `Session` (sessionId + state) from events via `EventReplayer`
|
|
* Provides `SessionCounterProjection` / `SessionCounterState` — a simple projection that counts events per session
|
|
* Defines `TransitionResult` sealed interface — models whether a status transition was applied or rejected
|
|
* Defines `ApprovalMode` enum (DENY, PROMPT, AUTO, YOLO) — the approval policy mode for a session
|
|
|
|
== non-responsibilities
|
|
|
|
* Does not produce events — all events are emitted by the kernel (`core:kernel`)
|
|
* Does not manage workflow graphs, transitions, or stage execution
|
|
* Does not interact with inference, tools, or context
|
|
* Does not enforce session lifecycle invariants — it only computes derived state from events
|
|
* Does not handle session persistence or storage
|
|
|
|
== key types
|
|
|
|
=== SessionStatus
|
|
* **kind**: enum
|
|
* **purpose**: lifecycle status of a session
|
|
* **variants**: CREATED, ACTIVE, PAUSED, COMPLETED, FAILED
|
|
|
|
=== SessionState
|
|
* **kind**: data class
|
|
* **purpose**: derived projection state for a session
|
|
* **fields**: status (SessionStatus), createdAt (Instant?), updatedAt (Instant?), invalidTransitions (Int)
|
|
|
|
=== Session
|
|
* **kind**: data class
|
|
* **purpose**: aggregate holding a sessionId and its current derived state
|
|
|
|
=== SessionReducer
|
|
* **kind**: interface
|
|
* **purpose**: reduces a `StoredEvent` into a `SessionState` transition
|
|
|
|
=== DefaultSessionReducer
|
|
* **kind**: class
|
|
* **purpose**: concrete reducer — maps `SessionStartedEvent` → ACTIVE, `SessionPausedEvent` → PAUSED, `SessionCompletedEvent` → COMPLETED, `SessionFailedEvent`/`StageFailedEvent` → FAILED, stage progress events → ACTIVE
|
|
|
|
=== SessionProjector
|
|
* **kind**: class
|
|
* **purpose**: wraps `SessionReducer` as a `Projection<SessionState>` with initial state = CREATED
|
|
|
|
=== DefaultSessionRepository
|
|
* **kind**: class
|
|
* **purpose**: wraps `EventReplayer<SessionState>` to provide `getSession(sessionId)` and `rebuild(sessionId)` returning a `Session`
|
|
|
|
=== TransitionResult
|
|
* **kind**: sealed interface
|
|
* **purpose**: result of attempting a session status transition
|
|
* **variants**: Applied(newState), Rejected
|
|
|
|
=== ApprovalMode
|
|
* **kind**: enum
|
|
* **purpose**: approval policy mode for a session
|
|
* **variants**: DENY (block all), PROMPT (ask user), AUTO (auto-approve), YOLO (skip approval entirely)
|
|
|
|
=== SessionCounterProjection / SessionCounterState
|
|
* **kind**: class / data class
|
|
* **purpose**: trivial projection counting events per session. Likely a diagnostic or testing utility.
|
|
|
|
== event flow
|
|
|
|
*inbound (consumed by reducer):*
|
|
* `SessionStartedEvent` → status becomes ACTIVE, createdAt recorded
|
|
* `SessionPausedEvent` → status becomes PAUSED
|
|
* `SessionResumedEvent` → status becomes ACTIVE
|
|
* `SessionCompletedEvent` → status becomes COMPLETED
|
|
* `SessionFailedEvent` → status becomes FAILED
|
|
* `StageStartedEvent` → status becomes ACTIVE
|
|
* `StageCompletedEvent` → status becomes ACTIVE
|
|
* `StageFailedEvent` → status becomes FAILED
|
|
* `TransitionExecutedEvent` → status becomes ACTIVE
|
|
|
|
*outbound:*
|
|
This module does not emit events. All events are emitted by `core:kernel`.
|
|
|
|
== integration points
|
|
|
|
* `:core:events` — `StoredEvent`, `Projection`, `EventReplayer`, `DefaultStateBuilder`, session event types (`SessionStartedEvent`, etc.), stage event types (`StageStartedEvent`, `StageCompletedEvent`, `StageFailedEvent`, `TransitionExecutedEvent`), identity types
|
|
* `:core:kernel` — uses `DefaultSessionRepository`, `Session`
|
|
|
|
== invariants
|
|
|
|
* `SessionState` is always derived from events via replay. It is never persisted or mutated directly.
|
|
* `createdAt` is set once from the first event's timestamp and never changes.
|
|
* `invalidTransitions` field exists in `SessionState` but is never incremented by `DefaultSessionReducer` — it is always 0.
|
|
* `SessionFailedEvent` and `StageFailedEvent` both map to FAILED status — there is no distinction in the session state between session-level and stage-level failure.
|
|
|
|
== PlantUML diagram
|
|
|
|
[plantuml, core-sessions, "png"]
|
|
----
|
|
include::../../diagrams/core-sessions.puml[]
|
|
----
|
|
|
|
|
|
|
|
|
|
== known issues
|
|
|
|
* `SessionState.invalidTransitions` is declared but never written by `DefaultSessionReducer`. It is always 0. Either it is a placeholder for future use or dead code.
|
|
* `TransitionResult` is defined but unused within the module — no callers in the current codebase reference it.
|
|
|
|
== open questions
|
|
|
|
* None.
|