Merge remote-tracking branch 'origin/master' into session-query-search

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/module-graph.md
#	packages/session-persistence/session-persistence-jsonl/README.md
#	packages/session-persistence/session-persistence-jsonl/src/index.ts
#	packages/session-persistence/session-persistence-sqlite/README.md
#	packages/session-persistence/session-persistence-sqlite/src/index.ts
#	packages/session-persistence/session-persistence-sqlite/src/schema.ts
#	packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
#	packages/session-persistence/session-persistence/README.md
#	packages/session-persistence/session-persistence/src/coordinator.ts
#	packages/session-persistence/session-persistence/tests/persistence.spec.ts
#	packages/session-query/session-query/README.md

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

@@ -1,19 +1,7 @@
 /**
- * SQLite durable session-persistence backend (`@deepseek-ai/dsh-session-persistence-sqlite`).
- *
- * A SECOND {@link SessionPersistence} implementation, built to validate that the
- * abstract seam + the shared `runPersistenceContract` suite are genuinely
- * backend-agnostic: the same append-only / contiguous-seq / lazy-materialization
- * / interrupted-turn-close-on-load semantics the JSONL backend expresses over
- * file bytes, expressed here over `node:sqlite` rows. Each `SessionEvent` maps
- * 1:1 onto a row `(session_id, seq, type, time, data, source_event_seqs, surface_op)`.
- *
- * Like the JSONL backend it supplies ONLY the storage primitives (the
- * {@link PersistenceBackend} hooks below — INSERT/DELETE/SELECT inside
- * transactions); all the write-path orchestration lives in the backend-agnostic
- * {@link PersistenceCoordinator} this class composes. The stateful public
- * {@link SessionPersistence} methods delegate to the coordinator.
- *
+ * SQLite durable session-persistence backend. It maps each session header and
+ * event to rows, and delegates write-path orchestration to
+ * {@link PersistenceCoordinator}.
  * @module @deepseek-ai/dsh-session-persistence-sqlite
  */
 
@@ -27,7 +15,7 @@ import {
   SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
   type PersistenceBackend, type SessionPersistenceSnapshot, type StoredPrefix,
 } from '@deepseek-ai/dsh-session-persistence'
-import type { Session, SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
+import type { SessionEvent, SurfaceEventType, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import {
   type JournalMode, openDatabase, rowToMeta, scanRows, type EventRow, type SessionRow,
 } from './schema.ts'
@@ -91,10 +79,8 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
 
   constructor(ctx: Context, public config: Config) {
     super(ctx)
-    // Open the database asynchronously (the parent directory may need creating);
-    // every hook awaits `ready` first. Opening synchronously would force a sync
-    // mkdir and block plugin apply. schemastery (static Config) has already
-    // filled `journalMode`; the cast records that runtime fact.
+    // Open asynchronously so directory creation does not block plugin apply;
+    // every storage hook awaits the same readiness promise.
     this.ready = this.openDb(config.path, (config as Required<Config>).journalMode)
     this.coordinator = new PersistenceCoordinator<number>(this.ctx, this)
   }
@@ -140,18 +126,8 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
     return this.coordinator.load(id)
   }
 
-  // `list` is BOTH the public service method and the PersistenceBackend hook —
-  // one method (the SELECT below). The coordinator adds no orchestration for
-  // listing, so routing it through the coordinator would just recurse. Defined
-  // once, in the "PersistenceBackend hooks" section.
-
-  /**
-   * The per-session init promises, exposed for white-box tests that await a
-   * specific session's onCreated (there is no public API to await one init).
-   */
-  get inits(): Map<Session, Promise<void>> {
-    return this.coordinator.inits
-  }
+  // One method serves both public `list` and the backend hook; delegating it to
+  // the coordinator would call this hook recursively.
 
   // --- PersistenceBackend hooks (the SQLite storage primitives) ---
 

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -60,23 +60,11 @@ export interface EventRow {
 export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
 
 /**
- * Open the database at `path` and apply the schema + pragmas. `foreign_keys`
- * makes `ON DELETE CASCADE` drop a session's events with its row; the
- * `journal_mode` pragma is set from the plugin's `journalMode` config (`wal`
- * default — the durability model the ADR records; the row shape maps 1:1
- * onto `SessionEvent`; opencode runs this exact shape on SQLite/WAL).
- *
- * The table-layout version is persisted in SQLite's `PRAGMA user_version` and
- * checked on open: a fresh database (user_version 0) is stamped with the
- * current {@link SCHEMA_VERSION}; an existing database whose version is NOT the
- * current one (written by a different, incompatible build — older or newer) is
- * REJECTED rather than opened against a layout this build does not understand.
- * There are no migrations: an incompatible layout is rejected. The current
- * persistence-state row carries an immutable random store id, the sessions row
- * carries every header field plus its monotonic snapshot revision, and the
- * events row carries the complete surface metadata.
+ * Open the database and apply its schema and pragmas. A zero `user_version` is
+ * stamped with {@link SCHEMA_VERSION}; every other non-current version rejects
+ * rather than being migrated in place.
  * @param path - the SQLite database file to open (created when absent).
- * @param journalMode - the journal pragma to apply — a closed in-code union, validated by the plugin Config.
+ * @param journalMode - validated journal pragma.
  * @returns the open handle with pragmas applied and all three tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
@@ -92,8 +80,7 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
 
 function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalMode): void {
   db.exec('PRAGMA foreign_keys = ON')
-  // journalMode is a closed in-code union (validated by the plugin Config), not
-  // user-controlled SQL — safe to interpolate (PRAGMA takes no bound params).
+  // The validated union is safe to interpolate into a non-bindable PRAGMA.
   db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
   // `PRAGMA user_version` always returns exactly one row { user_version }.
   const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
@@ -101,9 +88,7 @@ function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalM
     throw new Error(`session database at "${path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`)
   }
   if (onDisk === 0) {
-    // Fresh (or pre-versioning) database: stamp the current layout version.
-    // PRAGMA does not accept bound parameters, so interpolate the integer
-    // constant (SCHEMA_VERSION is a trusted in-code number, not user input).
+    // Stamp fresh or pre-versioning databases.
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
   }
   db.exec(`
@@ -179,28 +164,11 @@ export function rowToEvent(row: EventRow): SessionEvent {
 }
 
 /**
- * The preserved prefix of an ordered event-row list (mirrors the JSONL
- * backend's `scanLog`): the longest prefix of complete, seq-contiguous,
- * parseable rows, PLUS the seq from which a never-committed torn tail must be
- * deleted (or `undefined` if the whole list is intact).
+ * Find the preserved prefix of ordered event rows. Fully written rows in an
+ * interrupted final turn remain in the prefix. The first unparsable row or seq
+ * gap after the last `turn/end` marks a tolerated torn tail; the same hole in
+ * the committed region rejects.
  *
- * A crash can leave a durable log whose final turn never closed: real,
- * fully-written rows sit after the last `turn/end`. Those are PRESERVED — a
- * single turn can be huge in a long-horizon task, so truncating it would
- * destroy real work; the backend closes the orphaned open turn with a synthetic
- * `turn/end {kind:'interrupted'}` on load (the session-persistence RFC). The ONLY thing excluded is
- * a torn trailing fragment — a row whose `data` never parses, or a seq gap —
- * AFTER the last committed `turn/end`; that bounds the preserved region and its
- * seq is returned as `tornFrom` so `load` can physically delete it.
- *
- * The last `turn/end` is computed from the `type` COLUMN (never parsing tail
- * `data`), so a malformed `data` in an uncommitted tail row is discarded rather
- * than making the session unloadable. A parse error or seq gap AT OR BEFORE the
- * last committed `turn/end` is committed-data corruption and throws.
- *
- * This relies on the session-log invariant that every event lives inside a turn
- * (`Session.append` enforces it): only the final turn can be open, so the
- * preserved tail is at most one unclosed turn.
  * @param rows - one session's event rows, ordered by seq ascending.
  * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
  *   delete starts at — when a torn tail exists.
@@ -224,12 +192,8 @@ export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]
     if (parsed[i]?.ok && rows[i]?.type === 'turn/end') { lastTurnEnd = i; break }
   }
 
-  // Walk the longest PREFIX of complete, seq-contiguous, parseable rows
-  // (row i has seq === i). This includes the fully-written rows of an
-  // interrupted final turn AFTER the last turn/end — real work, never
-  // truncated. The walk stops at the first hole:
-  //   - at or before the last committed turn/end → committed corruption (throw);
-  //   - after it (or no committed turn/end) → tolerated torn tail (stop).
+  // Preserve the contiguous prefix, including a complete interrupted turn;
+  // holes through the last committed boundary throw, while later holes stop.
   const preserved: SessionEvent[] = []
   for (let i = 0; i < rows.length; i++) {
     const p = parsed[i]