tea-session

Append-only session records, deterministic replay, materialized state, branches, approval/grant journals, and storage contracts for tea-rs.

The package is tea-session; Rust code imports it as tea_session. Its normal dependency graph is Tokio-free and contains no model provider, tool executor, JSON Schema compiler, filesystem, process, network, database, or wall-clock implementation.

Source of truth and replay

Canonical Protocol 1.0 RecordEnvelope values are authoritative. SessionReducer requires:

• one SessionCreated record at sequence zero;
• contiguous session-local SessionSequence values;
• one session ID and globally unique record/message/tool-call/approval IDs;
• matching assistant tool declarations, policy/approval ordering, tool terminals, and tool-result messages;
• valid checkpoint, interruption, cancellation, compaction, and branch references.

MaterializedSessionState is a rebuildable projection. It exposes the active transcript and configuration, pending approvals, tool recovery state, run terminals, checkpoints, compaction provenance, branch summaries, and active branch. Reducer failures never partially mutate incremental state.

Branches and recovery

A branch-aware session places its root branchId on SessionCreated. BranchCreated clones the source projection at a durable record in source ancestry; ActiveBranchChanged selects it. Forks never rewrite source records or the parent leaf. Fork points with pending approvals or incomplete tool calls are rejected to avoid duplicating uncertain external effects.

Existing Protocol 1.0 logs without a root branch remain replayable as legacy unbranched sessions.

Started tools interrupted before a terminal result remain explicitly uncertain with execution target and idempotency. Non-idempotent work is never replayed by this crate. Provider streams become interrupted run state rather than invented completed messages.

Store and policy journals

SessionStore is object-safe and returns project-owned boxed futures without exposing Tokio. InMemorySessionStore is the semantic reference implementation used to verify storage adapters such as tea-session-sqlite.

An AppendTransaction is all-or-nothing:

• canonical appends use expected session sequence;
• typed approval/grant journals use an independent fact-count revision;
• rich approval snapshots validate canonical approval/tool/profile/time context;
• a grant issued by AllowSession is committed with the matching rich resolution;
• revocation appends an immutable revoked grant rather than updating authorization in place.

Active non-revoked grants can be read from one session snapshot or queried by actor across sessions. Grants remain policy candidates only; this crate cannot make them override a deny.

JSON archive

SessionArchive is a versioned interchange/diagnostic format, not a concurrent store. Decoding rejects duplicate keys and oversized collections, preserves protocol compatibility errors, and preflights complete canonical replay and typed journals before one create transaction. Import never merges or renumbers records and cannot leave partial state.

SQLite persistence and schema management belong to tea-session-sqlite; this crate supplies the storage contract, replay semantics, catalog projection, and recovery state. Retention/deletion policy and automatic replay of uncertain external work are host responsibilities and are not performed by this crate.