492 lines
7.9 KiB
Markdown
492 lines
7.9 KiB
Markdown
---
|
||
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.
|