Merge PR #224 updates into prose cleanup

packages/session-persistence/session-persistence-jsonl/README.md

@@ -29,4 +29,4 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 ## Write path
 
-The plugin generalizes the example `session-jsonl.ts`: it subscribes to `session/created` (capture the header; persist a fork's seed once), `session/event` (snapshot each event when buffering — the live `session.events` object is mutable), and `session/flush`/dispose (drain the write-behind buffer through `append`). A per-session write cursor means a resumed session never re-appends already-stored events. Existing live sessions are seeded on plugin apply (HMR does not replay `session/created`). All backend operations for one session are serialized, and disposal awaits quiescence (every init + final drain) before returning, so no write lands after teardown.
+The plugin generalizes the example `session-jsonl.ts`: it subscribes to `session/created` (capture the header; persist a fork's seed once), `session/event` (copy each already-frozen event into the persistence-owned write-behind buffer), and `session/flush`/dispose (drain that buffer through `append`). A per-session write cursor means a resumed session never re-appends already-stored events. Existing live sessions are seeded on plugin apply (HMR does not replay `session/created`). All backend operations for one session are serialized, and disposal awaits quiescence (every init + final drain) before returning, so no write lands after teardown.

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -4,7 +4,7 @@ import { appendFile, mkdtemp, mkdir, rm, readFile, writeFile, readdir, stat } fr
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { encodeSegment, logPath, scanLog, sessionDir } from '../src/format.ts'
 import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
@@ -13,6 +13,13 @@ import { runCoordinatorContract, type CoordinatorFixture } from '../../session-p
 let root: string
 const dirs: string[] = []
 
+type MutableSessionHeader = { -readonly [K in keyof SessionHeader]: SessionHeader[K] }
+
+/** Test-only mutable view used to verify that backends detach returned/caller metadata. */
+function mutableHeader(header: SessionHeader): MutableSessionHeader {
+  return header
+}
+
 async function freshRoot(): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-'))
   dirs.push(dir)
@@ -250,7 +257,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     const loaded = await ctx.sessionPersistence.load(m.id)
     // A consumer mutates the returned meta's cwd. The backend's stored pathing
     // metadata must be unaffected, so a later append still finds the right log.
-    loaded.meta.cwd = '/evil'
+    mutableHeader(loaded.meta).cwd = '/evil'
     await ctx.sessionPersistence.append(m.id, [
       { type: 'turn/start', seq: 6, time: 9, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
       { type: 'turn/end', seq: 7, time: 10, data: { turn: 2, reason: { kind: 'completed' } } },
@@ -415,7 +422,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
     const m = meta('create-snap', '/orig')
     const p = ctx.sessionPersistence.create(m)
     // Mutate the caller's meta object immediately after calling create.
-    m.cwd = '/mutated'
+    mutableHeader(m).cwd = '/mutated'
     await p
     await ctx.sessionPersistence.append(SessionId('create-snap'), oneTurnLog())
     // The log materialized under the ORIGINAL cwd, not the mutated one.

packages/session-persistence/session-persistence-sqlite/README.md

@@ -27,4 +27,4 @@ interface Config {
 
 ## Write path
 
-Like the JSONL backend, the plugin also installs the `session/event` → buffer → `session/flush` drain: it snapshots each event when buffered (the live `session.events` object is mutable), persists a fork's seed once on `session/created`, keeps a per-session write cursor so a resumed session never re-appends stored events, and seeds existing live sessions on apply (HMR does not replay `session/created`). Dispose awaits every in-flight init + final drain and then closes the database, so no write lands after teardown.
+Like the JSONL backend, the plugin also installs the `session/event` → buffer → `session/flush` drain: it copies each already-frozen event into a persistence-owned buffer, persists a fork's seed once on `session/created`, keeps a per-session write cursor so a resumed session never re-appends stored events, and seeds existing live sessions on apply (HMR does not replay `session/created`). Dispose awaits every in-flight init + final drain and then closes the database, so no write lands after teardown.

packages/session-persistence/session-persistence/README.md

@@ -17,7 +17,7 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 
 - **Append-only; a crashed turn is closed, not truncated.** Committed events (at or below a flushed `turn/end`) are never rewritten. A crash can leave an unclosed final turn whose events are real and possibly large; `load` preserves them and durably appends synthetic closers (an error `tool/result` per unanswered `tool-call`, then `step/end?`+`turn/end {interrupted}`) to balance the log and keep the rehydrated history a valid provider transcript. Only a never-fully-written torn tail fragment is discarded.
 - **Contiguous seq.** `load` rejects a `seq` gap/parse error in the MIDDLE of the log; `append`'s first `seq` must equal the stored next-seq.
-- **JSON-serializable data.** `append` rejects non-serializable `event.data`; backends snapshot each event when buffering (the live `session.events` object is mutable).
+- **JSON-serializable data.** `append` materializes each direct/replay batch through the shared one-pass lossless-JSON boundary. Live `Session` events are already deep-frozen, but the write coordinator still copies each event into a persistence-owned buffer.
 - **Durability.** `append` returns only once the batch is durable.
 
 ## The write coordinator

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -1,18 +1,45 @@
 /**
- * The backend-agnostic write-path orchestration shared by every first-party {@link
- * SessionPersistence} backend.
+ * The backend-agnostic write-path orchestration shared by every first-party
+ * {@link SessionPersistence} backend.
+ *
+ * Every durable backend needs the same orchestration: the in-memory bookkeeping
+ * (the per-id state, the write-behind buffers, the per-id serialization chains,
+ * the per-session init promises), the `session/event` → buffer → `session/flush`
+ * drain, lazy materialization, crash-tail repair on load, the four
+ * `session/created` adoption cases (new / HMR-adopt / collision /
+ * ownerless-claim), and dispose-time quiescence. Only the STORAGE primitives are
+ * backend-specific (file bytes for `dsh-session-persistence-jsonl`, `node:sqlite`
+ * rows for `dsh-session-persistence-sqlite`). {@link PersistenceCoordinator} owns
+ * the orchestration; a backend supplies the storage primitives as a small
+ * {@link PersistenceBackend} hook object.
+ *
+ * The abstract {@link SessionPersistence} service's public API is independent of
+ * this: a backend IS a `SessionPersistence` (its four public methods delegate to
+ * a coordinator it composes), so a third-party backend MAY implement the service
+ * directly without using the coordinator at all.
+ *
+ * See the write-coordinator RFC (docs/rfc/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md)
+ * for the design rationale (composition over inheritance, the opaque torn marker).
+ *
  * @module @deepseek-ai/dsh-session-persistence/coordinator
  */
 
 import { Context } from 'cordis'
-import { interruptedTurnClosers, SESSION_FORMAT_VERSION } from '@deepseek-ai/dsh-session'
+import { interruptedTurnClosers, SESSION_FORMAT_VERSION, snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
-import { assertSerializable, seedCoversPrefix } from './index.ts'
+import { seedCoversPrefix } from './index.ts'
 
 /**
- * A stored session's durable prefix as read back from a backend: its {@link SessionHeader},
- * the preserved (seq-contiguous, parseable) event prefix, and an OPAQUE `tornMarker` that is
- * present iff a never-committed torn tail must be truncated before further writes.
+ * A stored session's durable prefix as read back from a backend: its
+ * {@link SessionHeader}, the preserved (seq-contiguous, parseable) event prefix,
+ * and an OPAQUE `tornMarker` that is present iff a never-committed torn tail must
+ * be truncated before further writes.
+ *
+ * The coordinator NEVER inspects `tornMarker`'s value — it only tests
+ * `!== undefined` (is there a tail to repair?) and passes the value back to
+ * {@link PersistenceBackend.commitRepair}. Each backend chooses its own marker
+ * type: the JSONL backend uses the byte offset to truncate to, the SQLite
+ * backend uses the seq to delete from (both happen to be `number`).
  */
 export interface StoredPrefix<TornMarker = unknown> {
   meta: SessionHeader
@@ -85,11 +112,16 @@ interface SessionState {
   /** The next seq the backend expects to append (the stored log length). */
   cursor: number
   /**
-   * Whether the backend has physically written this session (a JSONL file / SQLite row
-   * exists). `create()` registers state LAZILY — cursor 0, materialized false, nothing on disk
-   * — so an empty session leaves no artifact and the FIRST `appendBatch` writes the header +
-   * its events in one transaction (the "a row exists ⇔ it has events" invariant `list` relies
-   * on; a separate up-front materialize could crash leaving a row with zero events).
+   * Whether the backend has physically written this session (a JSONL file /
+   * SQLite row exists). `create()` registers state LAZILY — cursor 0,
+   * materialized false, nothing on disk — so an empty session leaves no
+   * artifact and the FIRST `appendBatch` writes the header + its events in ONE
+   * transaction (the "a row exists ⇔ it has events" invariant `list`
+   * relies on; a separate up-front materialize could crash leaving a row with
+   * zero events). The flag is the only signal that distinguishes a session
+   * registered-but-never-written from one durably present, which the reclaim
+   * path needs (an abandoned id with no artifact AND no buffered events is free
+   * to reuse; a materialized one is a real collision).
    */
   materialized: boolean
   /**
@@ -154,14 +186,18 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register a new session's metadata (lazy: no physical write until the first
    * {@link append}). Rejects if the id is already tracked or already persisted.
-   * @param meta - the immutable header (id, version, cwd, lineage) to record; snapshotted at call time.
+   * @param meta - the header (id, version, cwd, lineage) to record; materialized
+   *   as a detached lossless-JSON snapshot at call time.
    */
   create(meta: SessionHeader): Promise<void> {
     // Snapshot the metadata at call time: the op runs later (behind the
     // per-session chain) and the snapshot is stored as the lazy state, so keeping
     // the caller's object by reference would let a later mutation of `id`/`cwd`
     // register under one key but materialize under a different path/header.
-    const snapshot: SessionHeader = { ...meta }
+    const snapshot = snapshotJsonValue(meta)
+    if (snapshot === undefined) {
+      return Promise.reject(new TypeError('session metadata must be losslessly JSON-serializable'))
+    }
     return this.serialize(snapshot.id, () => this.createCore(snapshot))
   }
 
@@ -180,22 +216,25 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     this.states.set(meta.id, { meta, cursor: 0, materialized: false })
   }
 
-  // `async` so the synchronous validate/clone below reject (not throw) per the
-  // Promise<void> contract — callers use `await expect(...).rejects`.
+  // `async` so synchronous materialization failures below reject (not throw) per
+  // the Promise<void> contract — callers use `await expect(...).rejects`.
   /**
    * Durably persist a batch of events. Honors the append-only and contiguous-seq
    * contracts; rejects non-JSON-serializable `event.data`.
    * @param id - the session the batch belongs to.
-   * @param events - the contiguous batch to persist, in seq order; deep-cloned at call time.
+   * @param events - the contiguous batch to persist, in seq order; materialized
+   *   as a detached lossless-JSON snapshot at call time.
    */
   async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
-    // Validate serializability BEFORE cloning so a bad event surfaces the typed
-    // error rather than an opaque DataCloneError from structuredClone.
-    assertSerializable(events)
-    // Deep-snapshot the batch HERE, before the op waits behind the per-session chain: a caller
-    // that mutates a live array (e.g. session.events) — or an event inside it — before the op
-    // runs would otherwise have those changes persisted.
-    const batch = events.map(e => structuredClone(e))
+    // Validate and deep-snapshot the complete batch HERE, in one traversal,
+    // before the op waits behind the per-session chain. A check followed by
+    // structuredClone would reread accessors and could sanitize an exotic value
+    // into an apparently valid record; the single-pass materializer makes the
+    // checked value exactly the value persisted.
+    const batch = snapshotJsonValue(events)
+    if (batch === undefined) {
+      throw new TypeError('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
+    }
     return this.serialize(id, () => this.appendCore(id, batch))
   }
 
@@ -235,9 +274,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const { meta, events, tornMarker } = stored
     this.assertVersion(meta)
 
-    // Crash-recovery: if the log ended mid-turn (real, preserved events but no closing
-    // turn/end), close it durably DURING load so disk, the returned log, and the cursor all
-    // agree.
+    // Crash-recovery: if the log ended mid-turn (real, preserved events but no
+    // closing turn/end), close it durably DURING load so disk, the returned log,
+    // and the cursor all agree. The interrupted turn's real events are preserved,
+    // never truncated (a turn can be huge — the session-persistence RFC); only a
+    // never-fully-written torn tail fragment is discarded.
     const closers = interruptedTurnClosers(events)
     const balanced = [...events, ...closers]
 
@@ -253,7 +294,12 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     return { meta, events: balanced }
   }
 
-  // NOTE: there is deliberately no coordinator `list()`.
+  // NOTE: there is deliberately no coordinator `list()`. Listing needs none of
+  // the coordinator's orchestration (no per-id serialization, no cursor, no
+  // in-memory state) — it is a pure read of stored metadata. A backend's public
+  // `list()` IS the {@link PersistenceBackend.list} hook (one method); routing it
+  // through the coordinator would only forward to that same hook, so the
+  // coordinator stays out of the listing path entirely.
 
   // --- per-id serialization + adoption helpers ---
 
@@ -298,9 +344,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     // promise so flush/dispose can await it (onCreated is async).
     ctx.on('session/created', (session) => { void this.initFor(session) })
 
-    // Snapshot + buffer every event (the live object is mutable; clone so a later
-    // in-place mutation cannot rewrite a buffered event). Serializability is
-    // guaranteed at the source (Session.append), so structuredClone is safe.
+    // Session emits an owned frozen event. Keep a persistence-owned copy anyway
+    // so the write-behind queue owns exactly the record it will flush rather than
+    // retaining a product-layer record by identity. Serializability is guaranteed
+    // at the source, so structuredClone is safe.
     ctx.on('session/event', (session, event) => {
       let buffer = this.buffers.get(session)
       if (!buffer) this.buffers.set(session, buffer = [])
@@ -351,12 +398,13 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     const existing = this.inits.get(session)
     if (existing) return existing
     // Snapshot the seed SYNCHRONOUSLY — initFor runs inside the `session/created`
-    // emit, before any later `append` adds non-seed events. A clone freezes it
-    // against later mutation of the live event objects.
+    // emit, before any later append invalidates the public array snapshot. Events
+    // are already frozen; cloning gives persistence independent ownership.
     const seed = session.events.map(e => structuredClone(e))
     const p = this.onCreated(session, seed)
-    // Attach a no-op rejection handler so a failing init does not surface as an unhandled
-    // rejection if no flush observes `p` before it rejects.
+    // Attach a no-op rejection handler so a failing init does not surface as an
+    // unhandled rejection if no flush observes `p` before it rejects. The REAL
+    // error is still delivered: flush/dispose await the same `p` from the map.
     p.catch(() => { /* observed by flush/dispose via the stored promise */ })
     this.inits.set(session, p)
     return p
@@ -377,6 +425,15 @@ export class PersistenceCoordinator<TornMarker = unknown> {
 
   /**
    * On session/created: sync the backend's in-memory state to a live Session.
+   *
+   * Cases, by whether this backend tracks the id and whether an artifact exists:
+   *   1. Already tracked → no-op (or claim ownerless state if the seed matches,
+   *      or reclaim a truly-abandoned id, else reject as a collision).
+   *   2. Not tracked, an artifact EXISTS at this cwd and is a seq-aligned PREFIX
+   *      of the live events → ADOPT it (HMR/reload), persisting any live suffix.
+   *   3. Not tracked, an artifact EXISTS but is NOT a prefix → REJECT (collision).
+   *   4. Not tracked and NO artifact → a genuinely new session: register meta
+   *      (lazy) and persist its seed once.
    */
   private async onCreated(session: Session, seed: readonly SessionEvent[]): Promise<void> {
     const id = session.header.id
@@ -386,7 +443,16 @@ export class PersistenceCoordinator<TornMarker = unknown> {
       /* v8 ignore next -- initFor dedupes per session object; same-object re-entry can't occur */
       if (tracked.owner === session) return
       if (tracked.owner === undefined) {
-        // Ownerless state from the public create()/load() API.
+        // Ownerless state from the public create()/load() API. The FIRST live
+        // session claims it — but ONLY if BOTH the cwd scope and the seed match.
+        // The cwd guard mirrors case-2's cwd-scoped loadLive(): a same-id
+        // ownerless artifact at a DIFFERENT cwd is a collision, not a claim
+        // (claiming it would append the live cwd's events under the stored
+        // header's cwd, the exact cross-cwd corruption the loadLive scope
+        // prevents). The seed guard then ensures the live events reproduce the
+        // persisted prefix (else a fresh, unrelated session reusing the id would
+        // have its seq 0..cursor-1 events filtered as already-written and
+        // grafted on).
         if (tracked.meta.cwd !== session.header.cwd) {
           throw new Error(`session "${id}" is already persisted at a different cwd (persisted: ${String(tracked.meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`)
         }
@@ -460,8 +526,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   }
 
   private async flush(session: Session): Promise<void> {
-    // Wait for the session's init (onCreated) so the state/cursor and any fork-seed persistence
-    // are in place before draining.
+    // Wait for the session's init (onCreated) so the state/cursor and any
+    // fork-seed persistence are in place before draining. Awaiting the same
+    // promise initFor stored also surfaces an init failure (e.g. a collision)
+    // here, where the caller of session/flush observes it.
     await this.inits.get(session)
     // Serialize the WHOLE drain (read cursor → append → splice) on the per-session
     // chain so two concurrent flushes cannot both read the same cursor and
@@ -473,7 +541,10 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   private async drain(session: Session): Promise<void> {
     const buffer = this.buffers.get(session)
     if (!buffer?.length) return
-    // Copy WITHOUT removing: the buffer is the only durable-pending copy of these events.
+    // Copy WITHOUT removing: the buffer is the only durable-pending copy of these
+    // events. Drain it only AFTER the append commits; events pushed during the
+    // await sit past batch.length and survive the prefix splice, so a
+    // retry/dispose re-drains the rest.
     const batch = buffer.slice()
     const state = this.states.get(session.header.id)
     // Only append events at or beyond the write cursor (a resumed session's seed

packages/session-persistence/session-persistence/src/index.ts

@@ -1,12 +1,28 @@
 /**
- * The durable session-persistence seam (`ctx.sessionPersistence`): an abstract service
- * defining what a persistence backend does — durably store, reload, and list sessions —
- * without saying how.
+ * The durable session-persistence seam (`ctx.sessionPersistence`): an abstract
+ * service defining WHAT a persistence backend does — durably store, reload,
+ * and list sessions — without saying HOW. Implementations subclass
+ * {@link SessionPersistence} and register themselves as the
+ * `sessionPersistence` service; `@deepseek-ai/dsh-session-persistence-jsonl`
+ * (an append-only JSONL log per session) is the first and
+ * `@deepseek-ai/dsh-session-persistence-sqlite` (`node:sqlite`, one row per
+ * event) is a second that validates the seam is backend-agnostic by passing
+ * the same `runPersistenceContract` suite. Further backends swap in an object
+ * store or a remote service without touching the consumers (the write-path
+ * plugin, the agent-loop resume seam).
+ *
+ * The persisted unit IS the existing {@link SessionEvent} — there is no
+ * parallel "persisted message" type the log must be converted to and from
+ * (faithful to the event-sourced model: the log is the single source of
+ * truth). Metadata that is NOT replayable conversation state (format version,
+ * cwd, lineage, seed boundary) travels separately as {@link SessionHeader},
+ * which is owned by `dsh-session` and re-exported here.
+ *
  * @module @deepseek-ai/dsh-session-persistence
  */
 
 import { Context, Service } from 'cordis'
-import { isJsonValue } from '@deepseek-ai/dsh-session'
+import { snapshotJsonValue } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 
 // Re-export the metadata vocabulary so consumers import it from the seam.
@@ -23,10 +39,12 @@ declare module 'cordis' {
 }
 
 /**
- * Whether a live session's seed reproduces a persisted prefix exactly. Backends use this
- * collision check to distinguish a legitimate resume/HMR rebind from a different live session
- * reusing an existing session id.
+ * Whether a live session's seed reproduces a persisted prefix exactly. Backends
+ * use this collision check to distinguish a legitimate resume/HMR rebind from a
+ * different live session reusing an existing session id.
  *
+ * The comparison includes the full event payload, not just seq/type/time, so a
+ * mutated seed cannot be grafted onto a durable log with the same envelope.
  * @param seed - the live session's creation-time event snapshot.
  * @param prefix - the persisted prefix the seed must reproduce.
  * @returns `true` when the prefix fits within the seed and every event matches by JSON text.
@@ -40,23 +58,46 @@ export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly
 }
 
 /**
- * Reject non-JSON-serializable event data before a backend serializes a batch.
- * Live session appends already enforce this; persistence append paths also
- * accept replay/fork batches that may bypass a live session instance.
- * @param events - the batch to validate; throws naming the offending event's type and seq.
+ * Reject a batch that is not wholly losslessly JSON-serializable. Live session
+ * appends already enforce this; persistence append paths also accept replay or
+ * direct batches that may bypass a live session instance. Validation uses the
+ * same one-pass materializer as the coordinator, so getters are read once.
+ * @param events - the complete event batch to validate.
  */
 export function assertSerializable(events: readonly SessionEvent[]): void {
-  for (const event of events) {
-    if (!isJsonValue(event.data)) {
-      throw new Error(`event "${event.type}" carries non-JSON-serializable data (seq ${event.seq})`)
-    }
+  const snapshot = snapshotJsonValue(events)
+  if (snapshot === undefined) {
+    throw new Error('session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data')
   }
 }
 
 /**
- * Abstract durable session-persistence service. Subclass, implement the abstract methods, and
- * load the subclass as a plugin — it registers as `ctx.sessionPersistence` (one implementation
- * per context; loading a second throws, cordis' standard duplicate-service behavior).
+ * Abstract durable session-persistence service. Subclass, implement the
+ * abstract methods, and load the subclass as a plugin — it registers as
+ * `ctx.sessionPersistence` (one implementation per context; loading a second
+ * throws, cordis' standard duplicate-service behavior).
+ *
+ * Contracts every implementation MUST honor (a DB backend asserts them inside
+ * a transaction; a file backend appends at EOF):
+ *
+ * - **Append-only; a crashed turn is closed, not truncated.** Committed events
+ *   — those at or below a flushed `turn/end` — are never rewritten. A crash can
+ *   leave an unclosed final turn whose events are real (and possibly large);
+ *   {@link load} preserves them and closes the orphaned turn with synthetic
+ *   boundary events (see {@link load}). Only a never-fully-written torn tail
+ *   fragment is discarded.
+ * - **Contiguous seq.** A persisted log is contiguous: `events[i].seq === i`.
+ *   {@link load} rejects a parse error or a `seq` gap in the COMMITTED region
+ *   (unloadable); {@link append}'s first event `seq` MUST equal the backend's
+ *   stored next-seq (after `load` has balanced any interrupted turn).
+ * - **JSON-serializable events.** `SessionEventMap` is merge-extensible, so
+ *   {@link append} materializes each complete batch through the shared
+ *   lossless-JSON boundary before buffering it. The public `session.events`
+ *   view is immutable, but persistence still snapshots direct/replay callers at
+ *   this independent trust boundary.
+ * - **Durability.** {@link append} returns only once the batch is durable
+ *   (the file backend fsyncs; a DB commits). {@link create} MAY defer the
+ *   physical write until the first {@link append} (lazy materialization).
  */
 export abstract class SessionPersistence extends Service {
   constructor(ctx: Context) {
@@ -84,10 +125,26 @@ export abstract class SessionPersistence extends Service {
   abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
 
   /**
-   * Reload a session: its {@link SessionHeader} plus the event log up to the last durable
-   * checkpoint. Returns `meta` AND `events` so the live session is reconstructed with its
-   * `cwd`/lineage, not just its log.
+   * Reload a session: its {@link SessionHeader} plus the event log up to the last
+   * durable checkpoint. Returns `meta` AND `events` so the live session is
+   * reconstructed with its `cwd`/lineage, not just its log.
    *
+   * The loop only flushes at `turn/end`, so a crash can leave a durable log
+   * whose final turn never closed: real, fully-written events sit after the last
+   * `turn/end`. Those events are PRESERVED — a single turn can be huge in a
+   * long-horizon task, so truncating it would destroy real work — and `load`
+   * CLOSES the orphaned turn by durably appending the minimal synthetic boundary
+   * events: an error `tool/result` for every `tool-call` the crash left
+   * unanswered (so the rehydrated history is a valid provider transcript — a
+   * dangling assistant tool-call is otherwise rejected), then a `step/end` if a
+   * step was open, then a `turn/end` carrying the `{ kind: 'interrupted' }`
+   * reason. The returned `events` therefore end on a balanced `turn/end` and are
+   * immediately usable as a session seed. Only a never-fully-written TORN tail
+   * fragment (a half-written final record) is discarded. Returned events are
+   * contiguous (`events[i].seq === i`); a parse error or a `seq` gap in the
+   * COMMITTED region (at or before the last real `turn/end`) makes the session
+   * unloadable (reject). Rejects an unknown format `version`. See the session-persistence RFC for
+   * the crash-recovery contract.
    * @param id - the persisted session to reload.
    * @returns the header plus the event log, ending on a balanced `turn/end` —
    *   immediately usable as a session seed.

packages/session-persistence/session-persistence/tests/contract.ts

@@ -237,7 +237,7 @@ export function runPersistenceContract(name: string, make: () => Promise<Contrac
           const events = [
             { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: bad } },
           ] as unknown as SessionEvent[]
-          await expect(persistence.append(mi.id, events)).rejects.toThrow(/user\/message/)
+          await expect(persistence.append(mi.id, events)).rejects.toThrow(/losslessly JSON-serializable/)
         }
       } finally {
         await dispose()

packages/session-persistence/session-persistence/tests/coordinator-contract.ts

@@ -119,14 +119,15 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
-    it('snapshot-on-buffer: mutating an event after session/event does not corrupt the persisted copy', async () => {
+    it('source-frozen events cannot be mutated after buffering and persist unchanged', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)
       try {
         const session = ctx.sessions.create(SessionId('mutate'), { meta: { cwd: WORK } })
         const ev = session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-        // Mutate the live event object AFTER it was buffered by session/event.
-        ;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
+        expect(() => {
+          ;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
+        }).toThrow(TypeError)
         session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
         session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
         await ctx.parallel('session/flush', session)

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -143,6 +143,17 @@ describe('SessionPersistence service registration', () => {
     expect(loaded.events).toHaveLength(6)
     await fiber.dispose()
   })
+
+  it('rejects non-JSON session metadata before registering lazy state', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence)
+    const invalid = { ...meta('invalid-meta'), createdAt: 1n as unknown as number }
+
+    await expect(ctx.sessionPersistence.create(invalid))
+      .rejects.toThrow('session metadata must be losslessly JSON-serializable')
+    await fiber.dispose()
+  })
 })
 
 describe('shared persistence helpers', () => {
@@ -172,10 +183,10 @@ describe('shared persistence helpers', () => {
     expect(() => { assertSerializable(oneTurnLog()) }).not.toThrow()
   })
 
-  it('rejects non-JSON-serializable event data with type and seq context', () => {
+  it('rejects a batch containing non-JSON-serializable event data', () => {
     const bad = [
       { type: 'user/message', seq: 0, time: 1, data: { content: 1n } },
     ] as unknown as SessionEvent[]
-    expect(() => { assertSerializable(bad) }).toThrow(/"user\/message".*seq 0/)
+    expect(() => { assertSerializable(bad) }).toThrow(/batch is not losslessly JSON-serializable/)
   })
 })