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/tests/sqlite.spec.ts

@@ -14,6 +14,19 @@ import { runCoordinatorContract, type CoordinatorFixture } from '../../session-p
 const dirs: string[] = []
 afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
 
+async function expectParallelFlushError(promise: Promise<unknown>, message: RegExp): Promise<void> {
+  try {
+    await promise
+  } catch (error) {
+    expect(error).toBeInstanceOf(AggregateError)
+    const [cause] = (error as AggregateError).errors as unknown[]
+    expect(cause).toBeInstanceOf(Error)
+    expect((cause as Error).message).toMatch(message)
+    return
+  }
+  throw new Error('expected parallel flush to reject')
+}
+
 async function freshDbPath(): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-sqlite-'))
   dirs.push(dir)
@@ -28,8 +41,7 @@ async function backend(path = ':memory:'): Promise<{ ctx: Context; dispose: () =
   return { ctx, dispose: () => fiber.dispose() }
 }
 
-// The payoff: the SAME backend-agnostic contract the JSONL backend runs, now
-// proving the SQLite backend satisfies identical semantics.
+// Run the same backend-agnostic contract as JSONL to pin identical semantics.
 runPersistenceContract('sqlite', async () => {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -40,11 +52,8 @@ runPersistenceContract('sqlite', async () => {
   }
 })
 
-// Run the shared coordinator orchestration suite against the real SQLite backend.
-// A FILE-backed db (not :memory:) is the shared storage scope so two mounted
-// instances see the same rows (HMR/reload). `corruptTail` INSERTs a row past the
-// committed seq whose `data` is invalid JSON — a never-committed torn tail that
-// drives the coordinator's commitRepair-with-tornMarker branch over real db rows.
+// A file-backed database lets two mounts share rows across reload. `corruptTail` inserts invalid
+// JSON past the committed seq, exercising coordinator repair against real database rows.
 runCoordinatorContract('sqlite', async (): Promise<CoordinatorFixture> => {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-sqlite-coord-'))
   const path = join(dir, 'sessions.db')
@@ -66,9 +75,9 @@ runCoordinatorContract('sqlite', async (): Promise<CoordinatorFixture> => {
 })
 
 describe('scanRows', () => {
-  // scanRows works off EventRows (data is a JSON string column); build them from
-  // SessionEvents so the unit tests read in terms of the event vocabulary. Surface
-  // fields are serialized to their nullable columns so a round trip is faithful.
+  // scanRows works off EventRows (data is a JSON string column); build them from SessionEvents
+  // so the unit tests read in terms of the event vocabulary. Surface metadata is serialized to
+  // its nullable columns so the conversion remains faithful.
   const rows = (events: SessionEvent[]): EventRow[] =>
     events.map((e) => {
       const se = e as SessionEvent<SurfaceEventType>
@@ -256,11 +265,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
   })
 
   it('rejects a sibling v3 database (the merge-collided version) rather than opening it against missing columns', async () => {
-    // Two unmerged branches each shipped a DISTINCT layout under user_version 3
-    // (one added only `seed_length`, the other only the surface columns). The
-    // the current build rejects every older layout; an on-disk v3 is ambiguous and is missing at least one
-    // of this build's columns, so it MUST be rejected, not opened. Stamp a v3
-    // database and confirm the version check refuses it.
+    // Version 3 identified two incompatible sibling layouts, so it is always rejected.
     const path = await freshDbPath()
     openDatabase(path, 'wal').close() // creates + stamps user_version = SCHEMA_VERSION
     const db = openDatabase(path, 'wal')
@@ -277,11 +282,9 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
     await b1.ctx.sessionPersistence.append(m.id, oneTurnLog()) // committed: seqs 0..5
     await b1.dispose()
 
-    // Hand-insert a torn tail row (seq 6, no closing turn/end) whose `data` is
-    // invalid JSON. The contract: only a parse error in the COMMITTED region is
-    // unloadable; a torn tail must be discarded. scanRows finds the last
-    // turn/end on the seq+type columns (never parsing tail `data`), so the
-    // unparsable row after it bounds the preserved prefix and is deleted by load.
+    // A torn row after the last committed turn has invalid JSON. `scanRows` locates the boundary
+    // from seq/type columns without parsing the tail, preserves the committed prefix, and load
+    // deletes the row; invalid JSON inside the committed region would remain fatal.
     const db = openDatabase(path, 'wal')
     db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, 6, ?, 7, ?)')
       .run(m.id, 'turn/start', '{not valid json')
@@ -473,7 +476,7 @@ describe('SessionPersistenceSqlite: edge cases', () => {
     }, { inject: ['sessions'] }))
     session.append('turn/start', { turn: 9, trigger: { kind: 'message', source: { kind: 'user' } } })
     await ctx.plugin(SessionPersistenceSqlite, { path })
-    await expect(ctx.parallel('session/flush', session)).rejects.toThrow(/id collision/)
+    await expectParallelFlushError(ctx.parallel('session/flush', session), /id collision/)
     await ctx.fiber.dispose()
   })
 })