kami/correx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d8df4a1307d3a6bf882f39b23b222e65f4dc9c8
correx/docs/modules/core-sessions-submodule-spec.md
T

7.9 KiB
Raw Blame History

name, description, depth, links
name description depth links
Core Sessions Submodule Spec Specification for :core:sessions – lifecycle FSM and projection 2
../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

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

7. session states

Mandatory lifecycle states:

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:

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:

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.

Reference in New Issue View Git Blame Copy Permalink