refactor(session): fold the session family into packages/session/

git mv the 12 packages from session-persistence/, session-projection/,
session-title/, and telemetry/ into one session/ group per the
regrouping RFC; merge the four group READMEs into one bilingual
triplet; rewrite the group segment in tsconfig references (intra-group
references shorten to ../<pkg>), tsconfig.base.json paths/globs,
knip.json keys, vitest include, gate scripts, and authored doc/note
citations; regenerate module graph, doc graphs, catalogs, and the
lockfile importer keys. No npm names change.

Full unit suite: 8779 passed; the 18 reported failures reproduce as
env flakes (ambient-proxy IPv6 tunneling, watched-dir inotify
timeouts under parallel load) — each passes in isolation with
NO_PROXY set, matching their known pre-existing behavior on master.

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

@@ -0,0 +1,407 @@
+/**
+ * SQLite durable session-persistence backend. It maps each session header and
+ * event to rows, and delegates write-path orchestration to
+ * {@link PersistenceCoordinator}. It has no independent per-session artifact,
+ * so its locator returns `undefined`.
+ * @module @deepseek-ai/dsh-session-persistence-sqlite
+ */
+
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { DatabaseSync } from 'node:sqlite'
+import { mkdir, open } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import {
+  DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS,
+  SessionPersistence, SessionPersistenceRevision, PersistenceCoordinator,
+  type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot,
+  type SessionInspection, type SessionPersistenceRevision as PersistenceRevision,
+  type StoredPrefix, type StoredSuffix,
+} from '@deepseek-ai/dsh-session-persistence'
+import type { SessionEvent, SurfaceEventType, SessionId, SessionHeader, SessionPreparation } from '@deepseek-ai/dsh-session'
+import {
+  type JournalMode, openDatabase, rowToMeta, scanRows, type EventRow, type SessionRow,
+} from './schema.ts'
+
+export { SCHEMA_VERSION } from './schema.ts'
+
+/**
+ * Serialize an event's surface-metadata fields for SQL binding. Both fields are
+ * nullable TEXT columns — null when the event has no surface metadata (non-surface
+ * events, events written before surface support).
+ */
+function surfaceBindings(event: SessionEvent): [string | null, string | null] {
+  const se = event as SessionEvent<SurfaceEventType>
+  return [
+    se.sourceEventSeqs ? JSON.stringify(se.sourceEventSeqs) : null,
+    se.surfaceOp !== undefined ? JSON.stringify(se.surfaceOp) : null,
+  ]
+}
+
+/** Build the source-qualified revision shared by full and lightweight reads. */
+function sqliteRevision(storeIdentity: string, row: SessionRow): PersistenceRevision {
+  return SessionPersistenceRevision(
+    `${storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`,
+  )
+}
+
+/**
+ * Exclusively create a missing database file with owner-only permissions.
+ * Existing files retain their modes, and errors other than `EEXIST` propagate.
+ * `DatabaseSync` reopens by path, so this does not protect confidentiality or
+ * integrity when another principal can replace the database entry in its parent
+ * directory.
+ */
+async function createDatabaseFile(path: string): Promise<void> {
+  try {
+    const handle = await open(path, 'wx', 0o600)
+    await handle.close()
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+  }
+}
+
+/** Plugin configuration. */
+export interface Config {
+  /**
+   * Filesystem path to the SQLite database file. The special value `:memory:`
+   * opens an in-process database (tests). On filesystems with POSIX modes,
+   * missing directories and databases are created owner-only; existing path
+   * modes are preserved. Filesystem setup errors other than an existing database
+   * fail initialization. The backend does not protect confidentiality or
+   * integrity when another principal can replace the database entry in its
+   * parent directory.
+   */
+  path: string
+  /**
+   * SQLite `journal_mode` pragma. `wal` (the default) is the recorded
+   * durability model; pick a rollback-journal mode (`delete`/`truncate`/
+   * `persist`) on filesystems where WAL's shared-memory files do not work
+   * (network mounts). See {@link JournalMode}.
+   */
+  journalMode?: JournalMode
+  /** Maximum cold Session preparations retained for history-to-resume reuse. */
+  preparedSessionCacheSize?: number
+  /** Fixed live-event coalescing window; not a backend completion deadline. */
+  writeBatchMaxDelayMs?: number
+}
+
+/**
+ * The SQLite persistence backend. Load as a plugin; it registers as
+ * `ctx.sessionPersistence` and (via the coordinator) installs the write-path
+ * listeners. Its torn-tail marker is the seq to delete from.
+ */
+export class SessionPersistenceSqlite extends SessionPersistence implements PersistenceBackend<number> {
+  static inject = ['sessions']
+
+  static Config: z<Config> = z.object({
+    path: z.string().required(),
+    journalMode: z.union(['wal', 'delete', 'truncate', 'persist'] as const).default('wal'),
+    preparedSessionCacheSize: z.number().step(1).min(1).default(DEFAULT_PREPARED_SESSION_CACHE_SIZE),
+    writeBatchMaxDelayMs: z.number().step(1).min(1).max(MAX_WRITE_BATCH_DELAY_MS)
+      .default(DEFAULT_WRITE_BATCH_MAX_DELAY_MS),
+  })
+
+  /**
+   * Backend label for the coordinator's dispose diagnostics. Intentionally
+   * shadows cordis `Service.name` (set to `'sessionPersistence'` by the base);
+   * see the JSONL backend for why this does not affect service resolution.
+   */
+  override readonly name = 'session-persistence-sqlite'
+
+  private db!: DatabaseSync
+  private storeIdentity!: string
+  private ready: Promise<void>
+  private coordinator: PersistenceCoordinator<number>
+
+  constructor(ctx: Context, public config: Config) {
+    super(ctx)
+    // Programmatic wrappers may construct the backend without Schemastery normalization.
+    const preparedSessionCacheSize = config.preparedSessionCacheSize
+      ?? DEFAULT_PREPARED_SESSION_CACHE_SIZE
+    const writeBatchMaxDelayMs = config.writeBatchMaxDelayMs
+      ?? DEFAULT_WRITE_BATCH_MAX_DELAY_MS
+    // 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, {
+      preparedSessionCacheSize,
+      writeBatchMaxDelayMs,
+    })
+  }
+
+  private async openDb(path: string, journalMode: JournalMode): Promise<void> {
+    const actual = path === ':memory:' ? path : resolve(path)
+    if (actual !== ':memory:') {
+      await mkdir(dirname(actual), { recursive: true, mode: 0o700 })
+      await createDatabaseFile(actual)
+    }
+    this.db = openDatabase(actual, journalMode)
+    try {
+      const row = this.db.prepare(
+        'SELECT store_id FROM persistence_state WHERE singleton = 1',
+      ).get() as { store_id: string } | undefined
+      /* v8 ignore next -- openDatabase inserts the singleton before returning. */
+      if (row === undefined) {
+        throw new Error(`session database at "${actual}" has no store identity`)
+      }
+      if (row.store_id.length === 0) {
+        throw new Error(`session database at "${actual}" has no valid store identity`)
+      }
+      if (actual !== ':memory:') {
+        const identity = statSync(actual, { bigint: true })
+        this.storeIdentity = `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${row.store_id}`
+      } else {
+        this.storeIdentity = `memory:store:${row.store_id}`
+      }
+    } catch (error: unknown) {
+      this.db.close()
+      throw error
+    }
+  }
+
+  // --- SessionPersistence service surface (delegated to the coordinator) ---
+
+  /** SQLite has one database, not an independent local artifact per session. */
+  locate(_meta: SessionHeader): SessionLocation | undefined {
+    return undefined
+  }
+
+  create(meta: SessionHeader): Promise<void> {
+    return this.coordinator.create(meta)
+  }
+
+  append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
+    return this.coordinator.append(id, events)
+  }
+
+  override prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation> {
+    return this.coordinator.prepare(id, signal)
+  }
+
+  load(id: SessionId): Promise<SessionInspection> {
+    return this.coordinator.load(id)
+  }
+
+  inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection> {
+    return this.coordinator.inspect(id, signal)
+  }
+
+  readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
+    return this.coordinator.readFrom(id, fromSeq, signal)
+  }
+
+  // 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) ---
+
+  /** Read a stored prefix by id (ids are globally unique — no scope to scan). */
+  loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined> {
+    return this.readPrefix(id, signal)
+  }
+
+  /** Read one row's revision without loading its events. */
+  async readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<PersistenceRevision | undefined> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    const row = this.rowFor(id)
+    return row === undefined ? undefined : sqliteRevision(this.storeIdentity, row)
+  }
+
+  /**
+   * Seek-capable suffix read: SQL selects `seq >= fromSeq` directly, so the
+   * read scales with the suffix, not the log. Torn rows past the preserved
+   * region are dropped, never repaired (non-mutating read).
+   */
+  async loadStoredFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    const row = this.rowFor(id)
+    if (row === undefined) return undefined
+    const meta = rowToMeta(row)
+    const eventRows = this.db
+      .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op FROM events WHERE session_id = ? AND seq >= ? ORDER BY seq')
+      .all(id, fromSeq) as unknown as EventRow[]
+    signal?.throwIfAborted()
+    const { preserved } = scanRows(eventRows, fromSeq)
+    return { meta, events: preserved }
+  }
+
+  /**
+   * Read a session's row + ordered events into a {@link StoredPrefix}. The
+   * torn-tail marker is the seq from which a never-committed tail must be deleted
+   * (`scanRows` already returns it as `number | undefined`).
+   */
+  private async readPrefix(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<number> | undefined> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    this.db.exec('BEGIN')
+    let snapshot: { row: SessionRow; eventRows: EventRow[] } | undefined
+    try {
+      const row = this.rowFor(id)
+      if (row !== undefined) {
+        const eventRows = this.db
+          .prepare('SELECT seq, type, time, data, source_event_seqs, surface_op FROM events WHERE session_id = ? ORDER BY seq')
+          .all(id) as unknown as EventRow[]
+        snapshot = { row, eventRows }
+      }
+      this.db.exec('COMMIT')
+    } catch (error: unknown) {
+      /* v8 ignore start -- synchronous read failures only need transaction cleanup before propagation. */
+      this.db.exec('ROLLBACK')
+      throw error
+      /* v8 ignore stop */
+    }
+    signal?.throwIfAborted()
+    if (snapshot === undefined) return undefined
+    const { row, eventRows } = snapshot
+    const { preserved, tornFrom } = scanRows(eventRows)
+    return {
+      meta: rowToMeta(row),
+      events: preserved,
+      revision: sqliteRevision(this.storeIdentity, row),
+      ...tornFrom !== undefined ? { tornMarker: tornFrom } : {},
+    }
+  }
+
+  /**
+   * Durably append a batch in ONE transaction: materialize the sessions row (if
+   * lazy) and INSERT every event, or roll back entirely. The transaction is the
+   * atomicity + durability boundary, so a mid-batch failure (a UNIQUE violation
+   * on a duplicated seq) leaves the stored log untouched.
+   */
+  async appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void> {
+    await this.ready
+    const insertEvent = this.db.prepare(
+      'INSERT INTO events (session_id, seq, type, time, data, source_event_seqs, surface_op) VALUES (?, ?, ?, ?, ?, ?, ?)',
+    )
+    this.db.exec('BEGIN')
+    try {
+      if (!isMaterialized) this.writeRow(meta)
+      for (const event of events) {
+        const [surfaceSeqs, surfaceOp] = surfaceBindings(event)
+        insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
+      }
+      this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
+      this.db.exec('COMMIT')
+    } catch (error) {
+      this.db.exec('ROLLBACK')
+      throw error
+    }
+  }
+
+  /**
+   * Make a crash repair durable in ONE transaction: DELETE the torn tail (from
+   * `tornMarker`) and INSERT the synthetic `closers`. After COMMIT the stored rows
+   * == the balanced log.
+   */
+  async commitRepair(meta: SessionHeader, tornMarker: number | undefined, closers: readonly SessionEvent[]): Promise<void> {
+    await this.ready
+    this.db.exec('BEGIN')
+    try {
+      if (tornMarker !== undefined) {
+        this.db.prepare('DELETE FROM events WHERE session_id = ? AND seq >= ?').run(meta.id, tornMarker)
+      }
+      if (closers.length > 0) {
+        const insertEvent = this.db.prepare(
+          'INSERT INTO events (session_id, seq, type, time, data, source_event_seqs, surface_op) VALUES (?, ?, ?, ?, ?, ?, ?)',
+        )
+        for (const event of closers) {
+          const [surfaceSeqs, surfaceOp] = surfaceBindings(event)
+          insertEvent.run(meta.id, event.seq, event.type, event.time, JSON.stringify(event.data), surfaceSeqs, surfaceOp)
+        }
+      }
+      if (tornMarker !== undefined || closers.length > 0) {
+        this.db.prepare('UPDATE sessions SET revision = revision + 1 WHERE id = ?').run(meta.id)
+      }
+      this.db.exec('COMMIT')
+    } catch (error) {
+      // The DELETE+INSERT cannot collide (a row at a closer's seq is preserved or
+      // deleted as torn first); this rolls back a DB-level failure (disk full,
+      // etc.), unreachable in test.
+      /* v8 ignore start */
+      this.db.exec('ROLLBACK')
+      throw error
+      /* v8 ignore stop */
+    }
+  }
+
+  /** List all materialized sessions' metadata (every row is a materialized session). */
+  async list(signal?: AbortSignal): Promise<SessionHeader[]> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    const rows = this.db
+      .prepare('SELECT * FROM sessions')
+      .all() as unknown as SessionRow[]
+    signal?.throwIfAborted()
+    return rows.map(rowToMeta)
+  }
+
+  /** List metadata with a source-qualified monotonic revision per session. */
+  async listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]> {
+    signal?.throwIfAborted()
+    await this.ready
+    signal?.throwIfAborted()
+    const rows = this.db.prepare('SELECT * FROM sessions').all() as unknown as SessionRow[]
+    signal?.throwIfAborted()
+    return rows.map(row => ({
+      header: rowToMeta(row),
+      revision: SessionPersistenceRevision(
+        `${this.storeIdentity}:incarnation:${row.incarnation}:revision:${row.revision}`,
+      ),
+    }))
+  }
+
+  /** Close the database handle (awaited by the coordinator's dispose, post-drain). */
+  async close(): Promise<void> {
+    await this.ready
+    this.db.close()
+  }
+
+  // --- row helpers ---
+
+  /** Fetch a session's row, or undefined if absent. */
+  private rowFor(id: SessionId): SessionRow | undefined {
+    return this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id) as unknown as SessionRow | undefined
+  }
+
+  /**
+   * Insert-or-replace a session's metadata row. The only caller is the first
+   * materializing `appendBatch`, so writing the row IS the materialization (its
+   * existence is the signal `list` reads).
+   */
+  private writeRow(meta: SessionHeader): void {
+    this.db.prepare(`
+      INSERT INTO sessions
+        (id, version, created_at, cwd, parent_session, seed_length, origin, delegation_depth, incarnation, revision)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
+      ON CONFLICT(id) DO UPDATE SET
+        version = excluded.version,
+        created_at = excluded.created_at,
+        cwd = excluded.cwd,
+        parent_session = excluded.parent_session,
+        seed_length = excluded.seed_length,
+        origin = excluded.origin,
+        delegation_depth = excluded.delegation_depth
+    `).run(
+      meta.id,
+      meta.version,
+      meta.createdAt,
+      meta.cwd ?? null,
+      meta.parentSession ?? null,
+      meta.seedLength ?? null,
+      meta.origin ?? null,
+      meta.delegationDepth ?? null,
+      randomUUID(),
+    )
+  }
+}
+
+export default SessionPersistenceSqlite

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

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence-sqlite`.
+ * @module @deepseek-ai/dsh-session-persistence-sqlite/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-persistence-sqlite'
+
+/** Cordis companion plugin name. */
+export const name = 'session-persistence-sqlite-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+ * this package exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

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

@@ -0,0 +1,262 @@
+/**
+ * Schema + load-time helpers for the SQLite session-persistence backend: the
+ * DDL (a store-identity row, `sessions` metadata, and a 1:1 `events` row per
+ * `SessionEvent`), the database open/configure step, and the last-`turn/end`
+ * cut that gives the SQLite backend the SAME crash-tail-on-load semantics as
+ * the JSONL backend.
+ *
+ * @module dsh-session-persistence-sqlite/schema
+ */
+
+import { randomUUID } from 'node:crypto'
+import { DatabaseSync } from 'node:sqlite'
+import type { SessionEvent, SessionId, SessionHeader, SurfaceOp } from '@deepseek-ai/dsh-session'
+
+/**
+ * The on-disk schema version. Bumped only on a breaking change to the table
+ * layout; orthogonal to a session's own `version` (which versions the EVENT
+ * vocabulary, stored per session in the `sessions` row).
+ */
+export const SCHEMA_VERSION = 13
+
+/** SQLite application id protecting unrelated databases from persistence writes. */
+export const SESSION_PERSISTENCE_SQLITE_APPLICATION_ID = 0x44534850
+
+/**
+ * A row of the `sessions` table — the out-of-log metadata ({@link SessionHeader}).
+ * The row's EXISTENCE is the materialization signal: it is written only by the
+ * first `append` (lazy materialization), so a created-but-never-appended
+ * session has no row and is absent from `list`, mirroring the JSONL
+ * backend's "no file until first append".
+ */
+export interface SessionRow {
+  id: string
+  version: number
+  created_at: number
+  cwd: string | null
+  parent_session: string | null
+  seed_length: number | null
+  origin: 'subagent' | null
+  /** Stable identity assigned when this log is materialized. */
+  incarnation: string
+  /** Monotonic log-change token incremented in each mutating transaction. */
+  revision: number
+  delegation_depth: number | null
+}
+
+/** An `events` table row: one `SessionEvent` mapped 1:1 (`data` is JSON text). */
+export interface EventRow {
+  seq: number
+  type: string
+  time: number
+  data: string
+  /** JSON-encoded `number[]` — the event's sourceEventSeqs, or null. */
+  source_event_seqs: string | null
+  /** JSON-encoded `SurfaceOp` — how the event entered the surface, or null. */
+  surface_op: string | null
+}
+
+/**
+ * Journal modes the backend will run under. `wal` is the default and the
+ * durability model the persistence ADR records; the rollback-journal modes
+ * (`delete`/`truncate`/`persist`) exist for filesystems where WAL's
+ * shared-memory files do not work (network mounts). `memory`/`off` are
+ * excluded: dropping journal durability silently contradicts what this
+ * backend promises.
+ */
+export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
+
+/**
+ * Open the database and apply its schema and pragmas. An empty database with a
+ * zero `user_version` is initialized at {@link SCHEMA_VERSION}; a nonempty
+ * unversioned database and every other non-current version reject rather than
+ * being migrated in place.
+ * @param path - the SQLite database file to open (created when absent).
+ * @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 {
+  const db = new DatabaseSync(path)
+  try {
+    configureDatabase(db, path, journalMode)
+    return db
+  } catch (error: unknown) {
+    db.close()
+    throw error
+  }
+}
+
+function configureDatabase(db: DatabaseSync, path: string, journalMode: JournalMode): void {
+  db.exec('PRAGMA foreign_keys = ON')
+  let began = false
+  try {
+    db.exec('BEGIN IMMEDIATE')
+    began = true
+    // Validate while holding the write lock so no other connection can change
+    // schema ownership between inspection and initialization.
+    const { user_version: onDisk } = db.prepare('PRAGMA user_version').get() as { user_version: number }
+    const { application_id: applicationId } = db.prepare('PRAGMA application_id').get() as { application_id: number }
+    const { count: userObjectCount } = db.prepare(
+      "SELECT COUNT(*) AS count FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*'",
+    ).get() as { count: number }
+    if (onDisk === 0 && (applicationId !== 0 || userObjectCount > 0)) {
+      throw new Error(`session database at "${path}" has an unversioned schema or application identity`)
+    }
+    if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {
+      throw new Error(`session database at "${path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`)
+    }
+    if (onDisk === SCHEMA_VERSION && applicationId !== SESSION_PERSISTENCE_SQLITE_APPLICATION_ID) {
+      throw new Error(
+        `session database at "${path}" has application id ${applicationId}, expected ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`,
+      )
+    }
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS persistence_state (
+        singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+        store_id  TEXT NOT NULL
+      ) STRICT;
+
+      CREATE TABLE IF NOT EXISTS sessions (
+        id               TEXT PRIMARY KEY,
+        version          INTEGER NOT NULL,
+        created_at       INTEGER NOT NULL,
+        cwd              TEXT,
+        parent_session   TEXT,
+        seed_length      INTEGER,
+        origin           TEXT,
+        delegation_depth INTEGER,
+        incarnation      TEXT NOT NULL,
+        revision         INTEGER NOT NULL
+      ) STRICT;
+
+      CREATE TABLE IF NOT EXISTS events (
+        session_id        TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        seq               INTEGER NOT NULL,
+        type              TEXT NOT NULL,
+        time              INTEGER NOT NULL,
+        data              TEXT NOT NULL,
+        source_event_seqs TEXT,
+        surface_op        TEXT,
+        PRIMARY KEY (session_id, seq)
+      ) STRICT
+    `)
+    db.prepare(
+      'INSERT OR IGNORE INTO persistence_state (singleton, store_id) VALUES (1, ?)',
+    ).run(randomUUID())
+    if (onDisk === 0) {
+      db.exec(`PRAGMA application_id = ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`)
+      db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+    }
+    db.exec('COMMIT')
+    began = false
+  } catch (error: unknown) {
+    /* v8 ignore next -- a BEGIN failure leaves no transaction to roll back. */
+    if (began) {
+      /* v8 ignore next 5 -- preserve the original schema failure if SQLite also refuses rollback. */
+      try {
+        db.exec('ROLLBACK')
+      } catch {
+        // The original SQLite failure remains the actionable cause.
+      }
+    }
+    throw error
+  }
+  // The validated union is safe to interpolate into a non-bindable PRAGMA.
+  // Apply it only after ownership validation and initialization commit.
+  db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`)
+}
+
+/**
+ * Reconstruct the {@link SessionHeader} from a `sessions` row.
+ * @param row - the `sessions` table row.
+ * @returns the header, `NULL` columns mapped to omitted optional fields.
+ */
+export function rowToMeta(row: SessionRow): SessionHeader {
+  if (!Number.isSafeInteger(row.created_at) || row.created_at < 0) {
+    throw new Error('stored session createdAt must be a non-negative safe integer')
+  }
+  return {
+    version: row.version,
+    id: row.id as SessionId,
+    createdAt: row.created_at,
+    ...row.cwd !== null ? { cwd: row.cwd } : {},
+    ...row.parent_session !== null ? { parentSession: row.parent_session as SessionId } : {},
+    ...row.seed_length !== null ? { seedLength: row.seed_length } : {},
+    ...row.origin !== null ? { origin: row.origin } : {},
+    ...row.delegation_depth !== null ? { delegationDepth: row.delegation_depth } : {},
+  }
+}
+
+/**
+ * Reconstruct a {@link SessionEvent} from an `events` row (parses `data`).
+ * @param row - the `events` table row; `data` and the surface columns hold JSON text.
+ * @returns the reconstructed event; throws when a JSON column fails to parse
+ *   ({@link scanRows} treats that as a hole, not corruption, in the tail).
+ */
+export function rowToEvent(row: EventRow): SessionEvent {
+  // Surface-metadata fields are conditional on the event type in the type
+  // system; spread them so each variant gets only the fields it declares.
+  const surfaceFields = {
+    ...row.source_event_seqs !== null ? { sourceEventSeqs: JSON.parse(row.source_event_seqs) as number[] } : {},
+    ...row.surface_op !== null ? { surfaceOp: JSON.parse(row.surface_op) as SurfaceOp } : {},
+  }
+  return {
+    type: row.type as SessionEvent['type'],
+    seq: row.seq,
+    time: row.time,
+    data: JSON.parse(row.data) as SessionEvent['data'],
+    ...surfaceFields,
+  } as SessionEvent
+}
+
+/**
+ * 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.
+ *
+ * @param rows - one session's event rows, ordered by seq ascending.
+ * @param base - the seq the first row is expected to carry; `0` for a whole
+ *   log, the requested `fromSeq` for a suffix read (`loadStoredFrom`).
+ * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
+ *   delete starts at — when a torn tail exists.
+ */
+export function scanRows(rows: readonly EventRow[], base = 0): { preserved: SessionEvent[]; tornFrom?: number } {
+  // Pass 1: parse each row's data; a row whose data is not valid JSON is a hole.
+  // (The seq/type COLUMNS are always present even when `data` is corrupt.)
+  interface Parsed { ok: boolean; event?: SessionEvent }
+  const parsed: Parsed[] = rows.map((row) => {
+    try {
+      return { ok: true, event: rowToEvent(row) }
+    } catch {
+      return { ok: false }
+    }
+  })
+
+  // The last index that is a valid `turn/end` — holes through a closed turn
+  // are always committed corruption.
+  let lastTurnEnd = -1
+  for (let i = parsed.length - 1; i >= 0; i--) {
+    if (parsed[i]?.ok && rows[i]?.type === 'turn/end') { lastTurnEnd = i; break }
+  }
+
+  // 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]
+    if (!p?.ok || p.event === undefined) {
+      if (i <= lastTurnEnd) throw new Error(`corrupt session log: unparsable committed event at seq ${rows[i]?.seq}`)
+      break // torn tail fragment after the last turn/end — stop, tolerate
+    }
+    if (p.event.seq !== base + i) {
+      if (i <= lastTurnEnd) throw new Error(`corrupt session log: seq gap in committed region (expected ${base + i}, got ${p.event.seq})`)
+      break // gap after the last turn/end — torn tail, stop
+    }
+    preserved.push(p.event)
+  }
+
+  // Any rows past the preserved prefix are a never-committed torn tail; their
+  // first seq is the deletion point for load's physical repair.
+  return preserved.length < rows.length ? { preserved, tornFrom: base + preserved.length } : { preserved }
+}