docs: tighten prose audit after master retarget

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

@@ -23,10 +23,10 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 - **Lazy materialization.** `create(meta)` writes nothing; the `.jsonl` (header + first batch) is written atomically (temp-write + `fsync` + rename) on the first `append`. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`.
-- **Crash recovery — close, don't truncate.** A crash can leave a log whose final turn never closed (real events after the last `turn/end`). `load` PRESERVES those events (a turn can be huge — they are real work) and closes the orphaned turn by durably appending synthetic boundary events: an error `tool/result` for every `tool-call` the crash left unanswered (the loop logs the assistant message before running the tools, so a mid-tool crash leaves dangling calls — and `deriveMessages()` would replay an assistant tool-call with no result, which providers reject), then a `step/end` if a step was open, then `turn/end {kind:'interrupted'}`, returning a balanced log. Only a never-fully-written **torn tail fragment** (a final line with no newline / unparseable) is `ftruncate`d away before the closers are written. See [session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md).
+- **Crash recovery — close, don't truncate.** `load` preserves valid events from an interrupted final turn, appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md), and removes only an incomplete final line.
 - **Contiguous-seq.** `load` rejects a mid-log parse error or `seq` gap (unloadable); `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
 - **Format version.** Only the current `SESSION_FORMAT_VERSION` (v0) is supported; `load` rejects any other version. While the harness is unreleased the on-disk format is pre-release/unstable: a breaking format change is absorbed at v0 (no bump until the first tagged release) and non-current logs are rejected — there is no migration (no persisted user data to preserve).
 
 ## 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` (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.
+The plugin buffers frozen session events and drains them on flush or disposal. A per-session cursor prevents resumed sessions from re-appending stored events, and live sessions are seeded when the plugin loads. Operations for one session are serialized; disposal waits for initialization and the final drain so no write lands after teardown.

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

@@ -8,13 +8,13 @@ A SQLite durable session-persistence backend — a second `SessionPersistence` i
 
 Each `SessionEvent` maps 1:1 onto a row in an `events` table `(session_id, seq, type, time, data, source_event_seqs, surface_op)` — `data` is the event payload as JSON text, so the row shape is the event verbatim (including `assistant/chunk`, keeping `seq` contiguous). The two `TEXT` columns `source_event_seqs` and `surface_op` are nullable; they store the event's optional surface-metadata fields (see [session surface](../../../docs/rfc/implemented/architecture/2026-06-18-session-surface.md)). Out-of-log metadata (`SessionHeader`) lives in a `sessions` row. A `sessions` row is written only by the first `append` — its existence is the lazy-materialization signal (`list` reports exactly the sessions that have a row), so no separate column is needed.
 
-The repo's `engines.node` is `^22.19.0 || >=24.0.0` (Node 22.19+ or 24+), matching the LTS floor required by the installed Pi adapter dependency; `node:sqlite` itself ships without the `--experimental-sqlite` flag from Node 22.13 (LTS) and 23.4 / 24 (Current) on. The range deliberately excludes Node 23 because that line is non-LTS/EOL and still has flagged runtime features before 23.6. The database opens with `foreign_keys = ON` (so `ON DELETE CASCADE` drops a session's events with its row) and the configured `journal_mode` (default `wal`; pick a rollback-journal mode like `delete` on filesystems where WAL's shared-memory files do not work, e.g. network mounts). The table-layout version is stored in `PRAGMA user_version` and checked on open: a fresh database is stamped with the current `SCHEMA_VERSION`; a database written by any other, incompatible build (a non-current `user_version`, older or newer) is rejected rather than opened against an unknown layout — there is no migration (unreleased software).
+The repository's Node range supports unflagged `node:sqlite`. The database enables foreign keys and uses the configured journal mode (`wal` by default; use a rollback mode where WAL shared-memory files are unsuitable). `PRAGMA user_version` stores the table-layout version; databases with any other version are rejected because this unreleased format has no migrations.
 
 ## Contract semantics over rows
 
 - **Append = a transaction.** `append` runs `BEGIN`/`COMMIT` around the batch: it materializes the `sessions` row (if still lazy) and INSERTs every event, asserting the contiguous-seq contract first (the first event's `seq` must equal the stored next-seq). A mid-batch failure (a UNIQUE violation on a duplicated seq) rolls back entirely, so the stored log and the in-memory cursor stay consistent. (`load()` already balanced the stored log, so `append` never has to repair a crash tail.)
 - **Lazy materialization.** `create()` records intent in memory only — no row is written until the first `append`. A created-but-never-appended session has no `sessions` row, so it is absent from `list()` (which reports exactly the sessions that have a row).
-- **Interrupted-turn close on load.** `load()` reads every stored event ordered by `seq` and finds the longest seq-contiguous, parseable prefix — INCLUDING the real events of an interrupted final turn after the last `turn/end` (the loop only flushes at `turn/end`, so a process killed mid-turn leaves real, fully-written rows past it). A single turn can be huge in a long-horizon task, so those events are **preserved, never truncated**: `load()` CLOSES the orphaned turn by durably appending the minimal synthetic boundary events (an error `tool/result` for every assistant tool call left unanswered, a `step/end` if a step was open, then a `turn/end` carrying `{ kind: 'interrupted' }`), inside one transaction that also DELETEs any never-fully-written torn tail row. `load()` is therefore mutating — after it the stored rows are balanced and the cursor is truthful, so the next `append` continues cleanly. The boundary (last `turn/end`, torn-tail detection) is computed from the `seq`/`type` columns so a malformed `data` in a torn tail row is never parsed (discarded, not unloadable). A parse error or `seq` gap inside the committed region (at or before the last real `turn/end`) makes the session unloadable. A session whose only turn never closed keeps its metadata row and stays present in `list()` — the same as the JSONL backend, whose file likewise survives a first append that never reached `turn/end`.
+- **Interrupted-turn close on load.** `load()` implements the shared [crash-recovery contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md): preserve the valid interrupted turn, append its synthetic closing events in one transaction, and remove only a torn tail row. Committed parse errors or sequence gaps make the session unloadable. Because recovery mutates stored rows, the next append starts from a balanced log and accurate cursor.
 
 ## Configuration (schemastery)
 

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

@@ -1,26 +1,6 @@
 /**
- * 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).
- *
+ * Shared buffering, serialization, adoption, repair, and disposal orchestration
+ * over backend-specific persistence primitives.
  * @module @deepseek-ai/dsh-session-persistence/coordinator
  */
 
@@ -30,16 +10,9 @@ import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-
 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.
- *
- * 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`).
+ * A stored session's header, valid contiguous event prefix, and optional opaque
+ * torn-tail marker. The coordinator only checks marker presence and returns its
+ * value to {@link PersistenceBackend.commitRepair}; each backend owns the type.
  */
 export interface StoredPrefix<TornMarker = unknown> {
   meta: SessionHeader
@@ -111,18 +84,7 @@ interface SessionState {
   meta: SessionHeader
   /** 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). 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).
-   */
+  /** Whether lazy creation has produced a durable artifact. */
   materialized: boolean
   /**
    * The live Session this state was bound to via `onCreated`, if any. State
@@ -166,14 +128,9 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    */
   private chains = new Map<SessionId, Promise<unknown>>()
   /**
-   * Per-session init promise (onCreated). Keyed by the LIVE Session OBJECT, not
-   * its id: a disposed fiber's session can be replaced by a different live
-   * Session reusing the same id (HMR, an ACP reconnect), and an id-keyed cache
-   * would hand the new object the old object's init promise.
-   *
-   * Public (readonly) so a backend can expose it for white-box tests that await
-   * a specific session's init (there is no public API to await one init); the
-   * coordinator itself only ever mutates it internally.
+   * Init promises keyed by live session object, preventing an id-reusing
+   * replacement from inheriting stale initialization. Readonly access supports
+   * backend white-box tests.
    */
   readonly inits = new Map<Session, Promise<void>>()
 
@@ -184,16 +141,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   // --- public surface (the backend's service methods delegate here) ---
 
   /**
-   * 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 header (id, version, cwd, lineage) to record; materialized
-   *   as a detached lossless-JSON snapshot at call time.
+   * Register detached session metadata for lazy creation on the first append.
+   * @param meta - header to snapshot; duplicate tracked or persisted ids reject.
    */
   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.
+    // Snapshot before queueing so caller mutation cannot diverge the key and header.
     const snapshot = snapshotJsonValue(meta)
     if (snapshot === undefined) {
       return Promise.reject(new TypeError('session metadata must be losslessly JSON-serializable'))
@@ -274,32 +226,20 @@ 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. 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.
+    // Preserve complete interrupted events and synthesize only missing closers.
     const closers = interruptedTurnClosers(events)
     const balanced = [...events, ...closers]
 
-    // Make the repair durable (truncate the torn tail + append the synthetic
-    // closers) BEFORE recording state — commitRepair takes `meta` directly, so
-    // there is no state-path ordering dependency (uniform across backends).
+    // Repair storage before publishing coordinator state.
     if (tornMarker !== undefined || closers.length > 0) {
       await this.backend.commitRepair(meta, tornMarker, closers)
     }
-    // The state keeps its OWN copy of the meta; the returned value is separate so
-    // a consumer mutating loaded.meta cannot corrupt the backend's metadata.
+    // Keep coordinator metadata detached from the returned record.
     this.states.set(id, { meta: { ...meta }, cursor: balanced.length, materialized: true })
     return { meta, events: balanced }
   }
 
-  // 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.
+  // Listing is a direct backend read and needs no coordinator state.
 
   // --- per-id serialization + adoption helpers ---
 

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

@@ -1,23 +1,6 @@
 /**
- * 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.
- *
+ * Durable session-persistence seam. Backends store {@link SessionEvent}s plus
+ * separate {@link SessionHeader} metadata.
  * @module @deepseek-ai/dsh-session-persistence
  */
 
@@ -39,12 +22,8 @@ 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.
- *
- * 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.
+ * Check whether a live seed exactly reproduces a durable prefix, including full
+ * payloads. This distinguishes resume/HMR rebinding from an id collision.
  * @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.
@@ -72,32 +51,10 @@ export function assertSerializable(events: readonly SessionEvent[]): void {
 }
 
 /**
- * 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).
+ * Durable append-only session storage. Implementations preserve contiguous,
+ * losslessly JSON-serializable events; {@link append} resolves only after
+ * durability, and {@link load} balances a complete interrupted tail without
+ * rewriting committed events.
  */
 export abstract class SessionPersistence extends Service {
   constructor(ctx: Context) {
@@ -125,29 +82,12 @@ 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.
-   *
-   * 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.
+   * Load a header and balanced contiguous log. A complete interrupted final
+   * turn is preserved and closed with missing tool errors and boundary events;
+   * only a torn final record is discarded. Unknown versions and corruption in
+   * the committed prefix reject.
    * @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.
+   * @returns the header and a log ending on a balanced `turn/end`.
    */
   abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 

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

@@ -16,26 +16,10 @@ import { meta, oneTurnLog, appendLog } from './contract.ts'
  * the suite mounts/disposes backend instances on it and cleans it up at the end.
  */
 export interface CoordinatorFixture {
-  /**
-   * Mount the REAL backend plugin (via `ctx.plugin`, the Loader path) on `ctx`,
-   * over THIS fixture's shared storage scope. Returns the plugin fiber so the
-   * suite can dispose a single instance (HMR/reload) while the storage — and any
-   * still-live session in another fiber — survives. The caller has already
-   * mounted `SessionStore` on `ctx`.
-   */
+  /** Mount a backend over shared fixture storage and return its disposable fiber. */
   mount: (ctx: Context) => Promise<Fiber>
 
-  /**
-   * Inject a NEVER-COMMITTED torn tail into the backend's storage for `id` at
-   * the given `cwd` (the cwd the session was created with): a half-written
-   * record past the committed region (JSONL: a partial line with no newline;
-   * SQLite: a row with invalid `data` JSON past the committed seq). This drives
-   * the coordinator's `loadCore` `tornMarker !== undefined` → `commitRepair`
-   * branch against real storage.
-   *
-   * OMITTED by a backend that structurally has no torn tails (memory): the
-   * torn-tail scenario then self-skips (asserted explicitly in the suite).
-   */
+  /** Inject an uncommitted torn tail; absent for backends that cannot produce one. */
   corruptTail?: (id: SessionId, cwd: string | undefined) => Promise<void>
 
   /** Tear down the storage scope (remove the temp dir / file). */