epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,491 @@
+---
+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.