> > > SpecAdr010SessionLifecycleModelDilemma

ADR-010: Session Lifecycle Model Dilemma

Status

Proposed / Draft

Context

SOTER records workflow-board changes as facts in the AnalyticalLedger stream. The system needs a way to group, label, analyze, and replay those events. Earlier designs called these groupings runs; the current concept uses sessions.

The unresolved design question is whether sessions are continuous stream boundaries, explicit capture windows, or retrospective bookmarks over an always-on stream.

The key tension is between ledger integrity and analyst ergonomics. A continuous event stream preserves event-sourcing integrity. A start/stop session model is easier to explain in the UI but risks implying that recording stops outside a session.

Decision

No final decision is accepted yet.

The preferred draft direction is a continuous event stream with named clips or bookmarks. Facts are recorded continuously. Sessions are metadata over time ranges, event ranges, or semantic slices of the stream. They do not own facts and do not create gaps in the ledger.

Rationale

A continuous stream avoids sessionless facts and supports projection rebuilding from the ledger. It also keeps board modifications recordable at all times.

Named clips preserve the user's mental model of a session without making facts disappear between sessions. This fits the analytical ledger model better than a locked board or ad hoc capture window.

The tradeoff is more complex querying and projection slicing. UI language must avoid implying that recording stops. "Stop Session" may need to become language such as "Close Clip", "End Bookmark", or "Finish Analysis Window" depending on the final product vocabulary.

Consequences

Positive

Board modifications can always be recorded.
The ledger remains continuous.
Sessions become metadata over facts rather than containers that own facts.
Projection rebuilding does not depend on missing event windows.

Negative

Querying becomes more complex.
UI language must distinguish stream, session, clip, and bookmark concepts.
Existing run_id assumptions may need migration.
Tests must be rewritten around the chosen lifecycle model.

Neutral or Operational

The final decision affects toolbar actions, ledger payload metadata, projection rebuilding, and E2E workflows.
run_id may become a bookmark ID, stream ID, session label, or compatibility alias.

Alternatives Considered

Strictly Continuous Sessions

Every event belongs to an automatically chained session. This keeps projections simple but does not match the user's expectation of starting and stopping a recording.

True Ad-Hoc Sessions

The board is locked unless a session is active. This avoids sessionless events but creates a restrictive user experience and conflicts with always-recorded ledger semantics.

Continuous Stream with Named Clips

All events go to one stream. Sessions are markers over time ranges or event ranges. This is the preferred draft direction, but it requires more projection and query work.

Migration or Adoption

Before implementation, decide whether existing run_id concepts become bookmark identifiers, stream identifiers, session labels, or compatibility aliases.

Adoption checklist:

align stakeholders on the continuous stream model;
replace UI language that implies recording stops;
define clip/bookmark metadata;
refactor unit and E2E tests around stream plus bookmark behavior;
preserve compatibility for existing payloads that carry run_id.