trajectories 0.0.0 → 0.1.1

package/legacy/src/db.ts

@@ -0,0 +1,2254 @@
+import { Database } from "bun:sqlite";
+import type { DiscoveryCheckpoint, DiscoverySummary } from "./discovery.js";
+import type { ScanResult } from "./types.js";
+import { ensurePrivateDatabase, ensurePrivateFile } from "./private-storage.js";
+import { isMemoryStorePath } from "./writer-lease.js";
+import {
+  CREATE_TABLES_SQL,
+  DERIVE_COUNTERS,
+  INDEXABLE_TITLE_SQL,
+  REPAIR_EMBEDDING_METADATA_TRIGGERS_SQL,
+  SCHEMA_VERSION,
+  TITLES_FTS_REBUILD_SQL,
+  V2_MIGRATION_SQL, V3_MIGRATION_SQL, V4_MIGRATION_SQL,
+  PARENTAGE_MIGRATION_SQL, INGEST_CURSORS_SQL, INGEST_DIAGNOSTICS_SQL,
+  FTS_REBUILD_MIGRATION_SQL,
+} from "./schema.js";
+import { ledgerId, nativeId } from "./identity.js";
+import { echoCount, echoExcludedBatchIds, echoExcludedIds } from "./filter.js";
+import { capDiagnosticSample, mergeIngestDiagnosticAggregates } from "./diagnostics.js";
+import {
+  extendSessionHash,
+  hashSessionRecords,
+  SESSION_HASH_VERSION,
+} from "./session-hash.js";
+import {
+  type SessionParentage,
+  EMPTY_SESSION_PARENTAGE,
+  extractSessionParentage,
+  mergeParentage,
+  parentageEquals,
+} from "./parentage.js";
+import {
+  embed,
+  getEmbeddingProvider,
+  getRecordEmbeddingText,
+  serializeEmbedding,
+} from "./embeddings.js";
+import type {
+  CanonicalDbRecord,
+  DiagnosticsSummary,
+  DiscoveredSession,
+  IngestCursor,
+  IngestDiagnosticAggregate,
+  IngestDiagnosticRecord,
+  IngestQueueEntry,
+  QueryResult,
+  ScanOutcome,
+  SessionRecord,
+  SourceCoverageRow,
+  TombstoneMode,
+  TombstoneRecord,
+} from "./types.js";
+import {
+  DEFAULT_PRESSURE_STATE,
+  type AdaptivePressureState,
+} from "./pressure.js";
+import {
+  allSessions,
+  compatibleEmbeddingCount,
+  countRecords,
+  countSessions,
+  lastSessions,
+  queryHybrid,
+  queryLexical,
+  querySemantic,
+  sessionById,
+  sessionRecords,
+} from "./reader.js";
+
+/** A staged coverage payload that could not be vouched for. Names the stage
+ * identity so the operator can find the row; thrown inside the ingest
+ * transaction, so the pass aborts instead of fabricating coverage. */
+export class StagedDiagnosticsParseError extends Error {
+  constructor(
+    readonly key: readonly [string, string, string],
+    readonly cause: unknown,
+  ) {
+    super(
+      `Staged diagnostics for ${key[0]}/${key[1]}/${key[2]} are not a valid ` +
+        `diagnostics aggregate${cause instanceof Error ? `: ${cause.message}` : ""}`,
+    );
+    this.name = "StagedDiagnosticsParseError";
+  }
+}
+
+/**
+ * The deletion verb was pointed at an id this store does not hold. A tombstone
+ * for a session that was never ingested would be an exclusion rule, not a
+ * deletion — a different mechanism with different consequences, and one this
+ * store deliberately does not have.
+ */
+export class SessionNotFoundError extends Error {
+  readonly code = "SESSION_NOT_FOUND";
+  constructor(readonly sessionId: string) {
+    super(`No session ${sessionId} in this store; nothing to delete.`);
+    this.name = "SessionNotFoundError";
+  }
+}
+
+/**
+ * A writer open that was told not to initialize a store (`requireExisting`) and
+ * found nothing to open.
+ *
+ * `ledger delete` opens this way, because a deletion has nothing to act on when
+ * the path holds no Ledger store and an empty database conjured for it would be
+ * an artifact nobody asked for. The refusal happens before any PRAGMA or DDL
+ * touches the file, and the connection itself is opened with creation disabled,
+ * so a store that vanished between the verb's classification and this open is
+ * neither created nor adopted.
+ */
+export class StoreNotInitializedError extends Error {
+  readonly code = "STORE_NOT_INITIALIZED";
+  constructor(readonly path: string) {
+    super(`No store at ${path}: the file is missing, empty, or not a Ledger store.`);
+    this.name = "StoreNotInitializedError";
+  }
+}
+
+/**
+ * A write tried to admit a session the user deleted. Thrown by the store's own
+ * write boundary (`saveSession`, `appendSessionRecords`, `commitStagedIngest`,
+ * `insertRecordEmbeddings`) rather than only by the ingest planner, so a racing
+ * writer, a library caller, or a staged promotion that outlived the deletion
+ * cannot put a tombstoned session back.
+ */
+export class TombstonedSessionError extends Error {
+  readonly code = "SESSION_TOMBSTONED";
+  constructor(readonly sessionId: string) {
+    super(
+      `Session ${sessionId} was deleted by the user; this store does not re-admit it. ` +
+        `The tombstone is the record of that deletion (session_tombstones).`,
+    );
+    this.name = "TombstonedSessionError";
+  }
+}
+
+/** What one `tombstoneSession` call did, beyond the row it wrote or found. */
+export interface TombstoneOutcome {
+  tombstone: TombstoneRecord;
+  /** True when this call wrote the tombstone; false when it already existed. */
+  created: boolean;
+  /** True when this call carried an existing `suppress` tombstone to `hard`. */
+  escalated: boolean;
+  /** Records removed from the store by this call: hard mode only, else 0. */
+  recordsRemoved: number;
+}
+
+/**
+ * What one ingest commit did: which write path it took (`inserted`/`updated` by
+ * whole-session replacement, `appended` by continuation), whether the pass only
+ * staged a replacement that a later chunk will promote, and whether it had to
+ * hand the session to a cold rebuild.
+ */
+export interface IngestCommitOutcome {
+  inserted: boolean;
+  updated: boolean;
+  deduped: boolean;
+  appended: number;
+  staged?: boolean;
+  deferred?: boolean;
+  deferReason?: string;
+  historicalRecordsHashed: number;
+}
+
+function isDiagnosticAggregate(value: unknown): value is IngestDiagnosticAggregate {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as Partial<IngestDiagnosticAggregate>;
+  return (
+    typeof entry.code === "string" &&
+    typeof entry.occurrenceCount === "number" &&
+    Number.isSafeInteger(entry.occurrenceCount) &&
+    entry.occurrenceCount >= 0 &&
+    (entry.sample === undefined || entry.sample === null || typeof entry.sample === "string") &&
+    (entry.firstSeenAt === undefined || typeof entry.firstSeenAt === "string")
+  );
+}
+
+export class TrajectoryDb {
+  private db: Database;
+  readonly path: string;
+
+  /**
+   * Open the store as a writer — creating and migrating it, as every writer verb
+   * does — unless `requireExisting` is set, which is `delete`'s open: a writer
+   * that must not create or adopt a store. That variant disables file creation on
+   * the connection and checks the shape before any PRAGMA or DDL runs, so a
+   * missing, empty, or foreign file is refused with `StoreNotInitializedError`
+   * and nothing is written into it.
+   *
+   * `initialize: false` is the parent handle after the bounded preparation child
+   * succeeded: never migrate or repair synchronously on the supervising event
+   * loop. Private-storage checks still run, but they must not create a missing
+   * primary file in either of those modes.
+   */
+  constructor(path: string = "ledger.sqlite", options: { initialize?: boolean; requireExisting?: boolean } = {}) {
+    this.path = path;
+    const requireExisting = options.requireExisting === true;
+    const skipInit = options.initialize === false;
+    if (!isMemoryStorePath(path)) {
+      if (requireExisting || skipInit) {
+        ensurePrivateFile(path, false);
+        for (const suffix of ["-wal", "-shm", "-journal"]) ensurePrivateFile(path + suffix, false);
+      } else {
+        ensurePrivateDatabase(path);
+      }
+    }
+    this.db = requireExisting
+      ? TrajectoryDb.openExisting(path)
+      : new Database(path, { readwrite: true, create: !skipInit });
+    try {
+      if (requireExisting) this.init(true);
+      else if (skipInit) {
+        this.db.run("PRAGMA busy_timeout = 0");
+        this.db.run("PRAGMA foreign_keys = ON");
+        if (this.getSchemaVersion() !== SCHEMA_VERSION) throw new Error("Prepared database schema version changed; retry sync");
+      } else this.init();
+      if (!isMemoryStorePath(path) && !requireExisting && !skipInit) ensurePrivateDatabase(path);
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
+  }
+
+  /**
+   * Open a writable connection that never creates the file. SQLite wants an
+   * explicit access mode for that (`create: false` alone is a misuse), and a
+   * missing file surfaces as the same typed refusal as an uninitialized one:
+   * from the caller's side both answers are "there is no store here".
+   */
+  private static openExisting(path: string): Database {
+    try {
+      return new Database(path, { readwrite: true, create: false });
+    } catch {
+      throw new StoreNotInitializedError(path);
+    }
+  }
+
+  private init(requireExisting = false): void {
+    // Read the shape first, before any connection setting or DDL: a store that
+    // must not be initialized has to be refused while the file is still
+    // untouched, and `PRAGMA journal_mode = WAL` alone already writes to it.
+    if (requireExisting) {
+      const version =
+        this.db.query<{ user_version: number }, []>("PRAGMA user_version;").get()?.user_version ?? 0;
+      const hasSessions = !!this.db
+        .query<{ name: string }, []>(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name='sessions' LIMIT 1;",
+        )
+        .get();
+      if (version === 0 && !hasSessions) throw new StoreNotInitializedError(this.path);
+    }
+
+    this.db.run("PRAGMA busy_timeout = 15000;");
+    this.db.run("PRAGMA journal_mode = WAL;");
+    // Chunk transactions stay fully durable. Keep SQLite's conservative
+    // checkpoint window explicit; the scheduled maintenance child also
+    // performs a deadline-bound passive checkpoint before the one-shot exits.
+    this.db.run("PRAGMA wal_autocheckpoint = 1000;");
+    this.db.run("PRAGMA foreign_keys = ON;");
+
+    const userVersion =
+      this.db
+        .query<{ user_version: number }, []>("PRAGMA user_version;")
+        .get()?.user_version ?? 0;
+
+    const hasTables = !!this.db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='sessions' LIMIT 1;",
+      )
+      .get();
+
+    // The tables this store already holds, read before any DDL below creates
+    // the ones this build needs. A counter that names its rules is a claim
+    // about a derivation, and what that derivation produces has to be in the
+    // store already; creating the tables first would erase the evidence.
+    const heldTables = new Set(
+      this.db
+        .query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type = 'table';")
+        .all()
+        .map((row) => row.name),
+    );
+
+    if (userVersion === 0 && !hasTables) {
+      // A killed preparation child must leave an empty retryable store, never
+      // a half-created sessions table with user_version=0 that looks foreign.
+      this.db.transaction(() => {
+        this.db.run(CREATE_TABLES_SQL);
+        this.configureFtsAutomerge();
+        this.db.run(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+      }).immediate();
+    } else if (userVersion < SCHEMA_VERSION) {
+      if (userVersion === 0 && hasTables) {
+        throw new Error(
+          `Database schema version ${userVersion} is older than required schema version ${SCHEMA_VERSION}. Database migrations are not yet implemented; please re-build the database.`,
+        );
+      }
+      this.migrate(userVersion);
+    } else if (userVersion > SCHEMA_VERSION) {
+      throw new Error(
+        `Database schema version ${userVersion} is newer than supported schema version ${SCHEMA_VERSION}.`,
+      );
+    } else {
+      this.db.run(CREATE_TABLES_SQL);
+    }
+
+    // Experimental v4 databases can contain obsolete trigger definitions.
+    // Repair only these owned triggers without replaying the identity migration.
+    this.db.transaction(() => {
+      this.db.run(REPAIR_EMBEDDING_METADATA_TRIGGERS_SQL);
+    })();
+
+    this.detectDeriveCounters(hasTables, heldTables);
+  }
+
+  /**
+   * Record this build's derive-rule counters, raising a re-derivation flag for
+   * every derived index the store holds under other rules.
+   *
+   * Open-time and unconditional, the shape Wake's `open_conn` uses
+   * (`db.rs#L176-L196`): a stored counter that contradicts this build's gets its
+   * flag, and the next pass that holds the writer lease re-derives it. Whether a
+   * store that records *nothing* — one written before the counter existed —
+   * also counts as pending is the counter's own call (`flagsWhenUnrecorded`: the
+   * FTS projection re-derives, the deferred vectors lane only records). A store
+   * that did not exist before this open is derived by the current rules by
+   * construction, so it records the counters and no flag; that is what keeps a
+   * fresh store from re-deriving what it has just written.
+   *
+   * A *newer* counter is stamped down rather than refused. The fence for a
+   * format this build does not understand is the read gate
+   * (`classifyReadStore`): a writer can restore an index to its own rules —
+   * `records` is canonical, so re-deriving is lossless in either direction —
+   * while a reader can only serve what it understands. An older build's pass
+   * over a newer store therefore costs one re-derivation, and the newer build's
+   * next pass costs one more; neither can lose canonical data.
+   *
+   * A counter that *matches* is checked against its outputs (the tables the
+   * rules derive): a store that records the current rule but is missing what
+   * the rule produces was not derived by it, so the flag is raised there too.
+   * The matching value is left in place — it is not the counter that is wrong,
+   * the derivation it claims is unfinished — and the next pass completes it.
+   */
+  private detectDeriveCounters(storeExisted: boolean, heldTables: ReadonlySet<string>): void {
+    const readFormat = this.db.query<{ value: string }, [string]>(
+      "SELECT value FROM schema_meta WHERE key = ?;",
+    );
+    const stamp = this.db.prepare(
+      "INSERT OR REPLACE INTO schema_meta (key, value) VALUES (?, ?)",
+    );
+    this.db.transaction(() => {
+      for (const counter of DERIVE_COUNTERS) {
+        const stored = readFormat.get(counter.format)?.value ?? null;
+        if (stored === counter.current) {
+          // The value claims a derivation under these rules; a matched counter
+          // whose output is gone is that claim without its evidence — the store
+          // cannot have been derived by these rules, whatever it records.
+          if (storeExisted && counter.outputs.some((table) => !heldTables.has(table))) {
+            stamp.run(counter.flag, "1");
+          }
+          continue;
+        }
+        if (storeExisted && (stored !== null || counter.flagsWhenUnrecorded)) {
+          stamp.run(counter.flag, "1");
+        }
+        stamp.run(counter.format, counter.current);
+      }
+    })();
+  }
+
+  private configureFtsAutomerge(): void {
+    // Pin SQLite's conservative default instead of inheriting an arbitrary
+    // database-level setting. Deeper catch-up compaction remains isolated in
+    // the deadline-bound maintenance child on idle scheduled passes.
+    this.db.run("INSERT INTO records_fts(records_fts, rank) VALUES ('automerge', 4)");
+    // The title index gets the same pinned policy rather than the table-level
+    // default it would otherwise inherit: one policy for both indexes, so a
+    // future change to it cannot reach one and miss the other.
+    this.db.run("INSERT INTO titles_fts(titles_fts, rank) VALUES ('automerge', 4)");
+  }
+
+  /**
+   * v10 → v11: rebuild `records_fts`. The index is derived — `records` is the
+   * authoritative side — so the rebuild discards the old table and repopulates
+   * it through the same projection ingest writes, and re-derives the index
+   * layout from that content.
+   *
+   * The projection is whole-table on purpose: `records` is what the echo filter
+   * reads, so the filter's set is recomputed here — the derivation is also what
+   * a *rule* change runs, and a set carried over from the previous rules would
+   * be exactly what a rule change must not keep. The fresh set then removes its
+   * rows from the freshly built index, which is what puts the rebuild on the
+   * same footing as ingest: there, the same decision wrote the set and skipped
+   * the FTS row; here, it rewrites the set and deletes what it names. The gate
+   * below checks the arithmetic either way.
+   */
+  private rebuildRecordsFts(): void {
+    this.db.run(FTS_REBUILD_MIGRATION_SQL);
+    const excluded = echoExcludedIds(this.db);
+    this.db.run("DELETE FROM records_echo;");
+    if (excluded.size > 0) {
+      // The ids are held as JSON and joined through the primary key: one probe
+      // per excluded record, never a scan of `records`.
+      this.db.run(
+        `INSERT INTO records_echo (record_id, session_id)
+         SELECT r.id, r.session_id FROM records r JOIN json_each(?) e ON r.id = e.value;`,
+        [JSON.stringify([...excluded])],
+      );
+    }
+    this.db.run("DELETE FROM records_fts WHERE record_id IN (SELECT record_id FROM records_echo);");
+    verifyRecordsFtsRebuild(this.db);
+  }
+
+  /**
+   * The title index's re-derivation: discard, recreate, repopulate from
+   * `sessions.title`, gate — the same increment as `records_fts`, for the same
+   * reason. The index is derived from a canonical column, so a rebuild is also
+   * the repair: a row the drift left behind comes back and a row no session
+   * backs goes away, where editing the table in place could do neither.
+   *
+   * The maintenance triggers live on `sessions` rather than on this table, so
+   * dropping and recreating it leaves them in place; a store written before the
+   * index existed gets both from `CREATE_TABLES_SQL` at writer open, and the
+   * population follows here on the same open's pass.
+   */
+  private rebuildTitlesFts(): void {
+    this.db.run(TITLES_FTS_REBUILD_SQL);
+    verifyTitlesFtsRebuild(this.db);
+  }
+
+  /** Whether the store is waiting for its one-shot FTS re-derivation. */
+  needsFtsReindex(): boolean {
+    return !!this.db
+      .query<{ key: string }, []>(
+        "SELECT key FROM schema_meta WHERE key = 'fts_reindex' LIMIT 1;",
+      )
+      .get();
+  }
+
+  /**
+   * Run the store's pending FTS re-derivation: the derive-rule counter's
+   * one-shot, taken by a pass that holds the writer lease. Returns whether
+   * there was work, so the caller can account for the wall time. Both derived
+   * indexes are this build's — `records_fts` (with the echo filter's set) and
+   * `titles_fts` — because the counter names the *rules*, and one rule version
+   * is one derivation.
+   *
+   * The rebuild is the v11 migration's increment exactly — drop, recreate,
+   * re-project from canonical `records` — which is the whole contrast with
+   * Wake: its `force_reindex` re-parses every session file
+   * (`scanner.rs#L179`, `#L281`, `#L439-L441`), because a file is the only place
+   * its units exist. Ledger keeps the canonical records in the store, so the
+   * re-derivation is one SQL statement over data that is already local: no
+   * source file is opened, no `ingest_cursors` row moves, and the queued or
+   * staged rebuild machinery (`ingest_queue`, `ingest_staged_*`, #49 D1's
+   * livelock path) is not entered at all.
+   *
+   * Vectors are untouched by construction, not by care: neither index has a
+   * foreign key into `records_embeddings`, and this transaction only ever names
+   * `records`, `records_fts`, `records_echo`, `titles_fts` and `sessions`.
+   *
+   * One transaction, flag clear included. An interrupted pass — a crash, or a
+   * failure in either index's own gates — rolls the whole increment back,
+   * leaving the previous indexes and the flag exactly as they were, so the next
+   * pass retries from a consistent state. Wake clears the flag after its scan
+   * (`scanner.rs#L439-L441`), which leaves a window where the flag is clear and
+   * the index is not what it names; here the two cannot disagree.
+   */
+  reindexFts(): boolean {
+    if (!this.needsFtsReindex()) return false;
+    this.db.transaction(() => {
+      this.rebuildRecordsFts();
+      this.rebuildTitlesFts();
+      this.configureFtsAutomerge();
+      this.db.run("DELETE FROM schema_meta WHERE key = 'fts_reindex';");
+    })();
+    return true;
+  }
+
+  private migrate(fromVersion: number): void {
+    const hasColumn = (table: string, name: string) =>
+      this.db.query<{ name: string }, []>(`PRAGMA table_info(${table})`).all().some((c) => c.name === name);
+    const hadParentage = hasColumn("sessions", "parent_session_id");
+    // The two unmerged branches used v4 differently. Shape, not an id prefix,
+    // distinguishes PR2's scoped v4 from PR6's native-id v4/v5 databases.
+    const needsIdentity = fromVersion < 4 || (fromVersion <= 5 && hadParentage);
+    this.db.run("PRAGMA foreign_keys = OFF;");
+    try {
+      this.db.transaction(() => {
+        if (fromVersion < 2) this.db.run(V2_MIGRATION_SQL);
+        if (fromVersion < 3) this.db.run(V3_MIGRATION_SQL);
+        if (!hadParentage) this.db.run(PARENTAGE_MIGRATION_SQL);
+        this.db.run(INGEST_CURSORS_SQL);
+        this.db.run(INGEST_DIAGNOSTICS_SQL);
+        if (!hasColumn("sessions", "content_hash_version")) {
+          this.db.run("ALTER TABLE sessions ADD COLUMN content_hash_version INTEGER NOT NULL DEFAULT 1");
+        }
+        if (needsIdentity) {
+          this.db.run("UPDATE sessions SET parent_session_id = source || ':' || parent_session_id WHERE parent_session_id IS NOT NULL");
+          this.db.run("UPDATE ingest_cursors SET session_id = source || ':' || session_id WHERE session_id IS NOT NULL");
+          this.db.run(V4_MIGRATION_SQL);
+        }
+        this.db.run("UPDATE sessions SET parent_session_id = NULL WHERE parent_session_id = id");
+        for (const [column, type] of [
+          ["file_identity", "TEXT"], ["prefix_hash", "TEXT"],
+          ["checkpoint_version", "INTEGER"], ["line_count", "INTEGER"],
+          ["tail_offset", "INTEGER"], ["tail_hash", "TEXT"],
+        ] as const) {
+          if (!hasColumn("ingest_cursors", column)) this.db.run(`ALTER TABLE ingest_cursors ADD COLUMN ${column} ${type}`);
+        }
+        // v13 renames the coverage status literal root_not_directory ->
+        // root_wrong_shape (file-kind roots make the old name a lie). SQLite
+        // bakes CHECK constraints into the table DDL, so stores created at v12
+        // reject the new literal; source_coverage is disposable per-pass state,
+        // so the migration drops and recreates it instead of rewriting rows.
+        if (fromVersion < 13) this.db.run("DROP TABLE IF EXISTS source_coverage");
+        // v14 reserved `source_discovery`; v15 adds `session_tombstones`. Both
+        // arrive from the same idempotent CREATE_TABLES_SQL rather than a
+        // numbered diff: a store at 13 (neither table) or 14 (discovery only)
+        // picks up whichever table it lacks and lands at 15. An already-v15
+        // store (tombstones present, discovery possibly missing) is accepted on
+        // the equal-version path, which also runs this DDL. Existing tombstones
+        // are never dropped; a table this statement does not know is left alone.
+        this.db.run(CREATE_TABLES_SQL);
+        if (!hasColumn("ingest_queue", "native_json")) {
+          this.db.run("ALTER TABLE ingest_queue ADD COLUMN native_json TEXT");
+        }
+        // Older releases predate the staged coverage column; the table itself
+        // may only exist once CREATE_TABLES_SQL has run.
+        if (!hasColumn("ingest_staged_sessions", "diagnostics_json")) {
+          this.db.run("ALTER TABLE ingest_staged_sessions ADD COLUMN diagnostics_json TEXT");
+        }
+        // v16 preserves per-record native lineage in managed conversations.
+        // Historical rows remain unknown; a session id or payload is not proof
+        // of the native origin of a record in a conversation that switched.
+        for (const column of ["native_session_id", "binding_id"]) {
+          if (!hasColumn("records", column)) this.db.run(`ALTER TABLE records ADD COLUMN ${column} TEXT`);
+        }
+        // v11 rebuilds the derived FTS index: drop it and repopulate from
+        // `records`, which is the side the read path trusts. The post-copy gates
+        // run inside this transaction, so a mismatch leaves the store at v10
+        // with its old index intact rather than half-rebuilt.
+        if (fromVersion < 11) this.rebuildRecordsFts();
+        // v12 adds `source_coverage` and nothing else, so the CREATE_TABLES_SQL
+        // above is its whole migration: the table arrives empty, and no row is
+        // fabricated for a source no pass has scanned yet.
+        this.configureFtsAutomerge();
+        if (this.db.query("PRAGMA foreign_key_check").all().length) {
+          throw new Error("Migration would leave dangling record or embedding references");
+        }
+        this.db.run(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+      })();
+    } finally {
+      this.db.run("PRAGMA foreign_keys = ON;");
+    }
+    // Databases that already carry the parentage schema were backfilled by the
+    // migration that introduced it. Re-reading every historical transcript on
+    // an unrelated later schema upgrade defeats the one-shot wall boundary.
+    if (!hadParentage) this.backfillSessionParentage();
+  }
+
+  hasSession(id: string, contentHash?: string): boolean {
+    if (contentHash) {
+      const row = this.db
+        .query<{ id: string }, [string, string]>(
+          "SELECT id FROM sessions WHERE id = ? AND content_hash = ? LIMIT 1",
+        )
+        .get(id, contentHash);
+      return !!row;
+    }
+    const row = this.db
+      .query<{ id: string }, [string]>(
+        "SELECT id FROM sessions WHERE id = ? LIMIT 1",
+      )
+      .get(id);
+    return !!row;
+  }
+
+  getSessionByContentHash(contentHash: string): SessionRecord | null {
+    return (
+      this.db
+        .query<SessionRecord, [string]>(
+          "SELECT * FROM sessions WHERE content_hash = ? LIMIT 1",
+        )
+        .get(contentHash) ?? null
+    );
+  }
+
+  getSessionBySourcePath(sourcePath: string): SessionRecord | null {
+    return (
+      this.db
+        .query<SessionRecord, [string]>(
+          "SELECT * FROM sessions WHERE source_path = ? LIMIT 1",
+        )
+        .get(sourcePath) ?? null
+    );
+  }
+
+  getIngestCursor(
+    source: string,
+    listingId: string,
+    sourcePath: string,
+  ): IngestCursor | null {
+    return (
+      this.db
+        .query<IngestCursor, [string, string, string]>(
+          `SELECT * FROM ingest_cursors
+           WHERE source = ? AND listing_id = ? AND source_path = ? LIMIT 1`,
+        )
+        .get(source, listingId, sourcePath) ?? null
+    );
+  }
+
+  getIngestSession(cursor: IngestCursor): SessionRecord | null {
+    return this.getStagedIngestSession(cursor) ?? (cursor.session_id ? this.sessionRowById(cursor.session_id) : null);
+  }
+
+  private getStagedIngestSession(cursor: IngestCursor): SessionRecord | null {
+    const row = this.db.query<{ session_json: string }, [string, string, string]>(
+      "SELECT session_json FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?",
+    ).get(cursor.source, cursor.listing_id, cursor.source_path);
+    return row ? JSON.parse(row.session_json) as SessionRecord : null;
+  }
+
+  upsertIngestCursor(cursor: IngestCursor): void {
+    this.db.run(
+      `INSERT INTO ingest_cursors (
+        source, listing_id, source_path, session_id, mtime, size,
+        bytes_ingested, record_count, status, updated_at, file_identity, prefix_hash,
+        checkpoint_version, line_count, tail_offset, tail_hash
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(source, listing_id, source_path) DO UPDATE SET
+        session_id = excluded.session_id,
+        mtime = excluded.mtime,
+        size = excluded.size,
+        bytes_ingested = excluded.bytes_ingested,
+        record_count = excluded.record_count,
+        status = excluded.status,
+        updated_at = excluded.updated_at,
+        file_identity = excluded.file_identity,
+        prefix_hash = excluded.prefix_hash,
+        checkpoint_version = excluded.checkpoint_version,
+        line_count = excluded.line_count,
+        tail_offset = excluded.tail_offset,
+        tail_hash = excluded.tail_hash`,
+      [
+        cursor.source,
+        cursor.listing_id,
+        cursor.source_path,
+        cursor.session_id,
+        cursor.mtime,
+        cursor.size,
+        cursor.bytes_ingested,
+        cursor.record_count,
+        cursor.status,
+        cursor.updated_at,
+        cursor.file_identity ?? null,
+        cursor.prefix_hash ?? null,
+        cursor.checkpoint_version ?? null,
+        cursor.line_count ?? null,
+        cursor.tail_offset ?? null,
+        cursor.tail_hash ?? null,
+      ],
+    );
+  }
+
+  getDiscoveryCheckpoints(): Record<string, DiscoveryCheckpoint> {
+    return Object.fromEntries(this.db.query<DiscoveryCheckpoint, []>(
+      "SELECT * FROM source_discovery ORDER BY source",
+    ).all().map(row => [row.source, { ...row, degraded: Boolean(row.degraded) }]));
+  }
+
+  /** No checkpoint advances unless every item in that page was admitted. */
+  admitDiscovery(result: ScanResult, needsIngest: (item: DiscoveredSession) => boolean, stamp: Date): void {
+    this.db.transaction(() => {
+      this.recordSourceCoverage(result.outcomes, stamp);
+      for (const item of result.sessions) {
+        if (needsIngest(item)) this.enqueueIngest(item, stamp.toISOString());
+        else this.removeQueuedIngest(item);
+      }
+      const upsert = this.db.query(`INSERT INTO source_discovery
+        (source, root_key, cursor, status, degraded, last_completed_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(source) DO UPDATE SET root_key=excluded.root_key, cursor=excluded.cursor,
+          status=excluded.status, degraded=excluded.degraded,
+          last_completed_at=excluded.last_completed_at, updated_at=excluded.updated_at`);
+      for (const row of result.discovery ?? []) {
+        upsert.run(row.source, row.root_key, row.cursor, row.status, Number(row.degraded),
+          row.last_completed_at, stamp.toISOString());
+      }
+    }).immediate();
+  }
+
+  getDiscoverySummary(): DiscoverySummary | null { return readDiscoverySummary(this.db); }
+
+  enqueueIngest(item: Pick<IngestQueueEntry, "source" | "id" | "path" | "updatedAt" | "title" | "sizeBytes" | "native">, now = new Date().toISOString()): void {
+    this.db.run(
+      `INSERT INTO ingest_queue (
+        source, listing_id, source_path, source_updated_at, title, size_bytes, native_json, enqueued_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(source, listing_id, source_path) DO UPDATE SET
+        source_updated_at = excluded.source_updated_at,
+        title = excluded.title,
+        size_bytes = excluded.size_bytes,
+        native_json = excluded.native_json,
+        attempt_count = CASE
+          WHEN ingest_queue.source_updated_at IS NOT excluded.source_updated_at
+            OR ingest_queue.size_bytes IS NOT excluded.size_bytes
+            OR ingest_queue.native_json IS NOT excluded.native_json THEN 0
+          ELSE ingest_queue.attempt_count END,
+        next_attempt_at = CASE
+          WHEN ingest_queue.source_updated_at IS NOT excluded.source_updated_at
+            OR ingest_queue.size_bytes IS NOT excluded.size_bytes
+            OR ingest_queue.native_json IS NOT excluded.native_json THEN NULL
+          ELSE ingest_queue.next_attempt_at END,
+        last_attempt_at = CASE
+          WHEN ingest_queue.source_updated_at IS NOT excluded.source_updated_at
+            OR ingest_queue.size_bytes IS NOT excluded.size_bytes
+            OR ingest_queue.native_json IS NOT excluded.native_json THEN NULL
+          ELSE ingest_queue.last_attempt_at END,
+        last_outcome = CASE
+          WHEN ingest_queue.source_updated_at IS NOT excluded.source_updated_at
+            OR ingest_queue.size_bytes IS NOT excluded.size_bytes
+            OR ingest_queue.native_json IS NOT excluded.native_json THEN NULL
+          ELSE ingest_queue.last_outcome END`,
+      [item.source, item.id, item.path, item.updatedAt ?? null, item.title ?? null, item.sizeBytes ?? null,
+        item.native ? JSON.stringify(item.native) : null, now],
+    );
+  }
+
+  getQueuedIngest(limit: number, now = new Date().toISOString()): IngestQueueEntry[] {
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("queue limit must be a positive safe integer");
+    return this.db.query<IngestQueueEntry & { native_json: string | null }, [string, number]>(
+      `SELECT source, listing_id AS id, source_path AS path,
+        source_updated_at AS updatedAt, title, size_bytes AS sizeBytes,
+        attempt_count, next_attempt_at, last_attempt_at, last_outcome, native_json
+       FROM ingest_queue
+       WHERE next_attempt_at IS NULL OR next_attempt_at <= ?
+       ORDER BY enqueued_at ASC, coalesce(source_updated_at, '') DESC, source, listing_id
+       LIMIT ?`,
+    ).all(now, limit).map(({ native_json, ...item }) => native_json === null
+      ? item : { ...item, native: JSON.parse(native_json) as DiscoveredSession["native"] });
+  }
+
+  getQueuedIngestLanes(
+    limit: number,
+    freshLimit: number,
+    freshCutoff: string,
+    now = new Date().toISOString(),
+  ): { items: IngestQueueEntry[]; fresh: number; backlog: number } {
+    if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("queue limit must be a positive safe integer");
+    if (!Number.isSafeInteger(freshLimit) || freshLimit < 0 || freshLimit > limit) {
+      throw new Error("fresh queue limit must be between zero and the queue limit");
+    }
+    const columns = `source, listing_id AS id, source_path AS path,
+      source_updated_at AS updatedAt, title, size_bytes AS sizeBytes,
+      attempt_count, next_attempt_at, last_attempt_at, last_outcome, native_json`;
+    const fresh = this.db.query<IngestQueueEntry & { native_json: string | null }, [string, string, number]>(
+      `SELECT ${columns} FROM ingest_queue
+       WHERE (next_attempt_at IS NULL OR next_attempt_at <= ?) AND source_updated_at >= ?
+       ORDER BY source_updated_at DESC, enqueued_at ASC, source, listing_id
+       LIMIT ?`,
+    ).all(now, freshCutoff, limit);
+    const backlog = this.db.query<IngestQueueEntry & { native_json: string | null }, [string, string, number]>(
+      `SELECT ${columns} FROM ingest_queue
+       WHERE (next_attempt_at IS NULL OR next_attempt_at <= ?)
+         AND (source_updated_at IS NULL OR source_updated_at < ?)
+       ORDER BY enqueued_at ASC, coalesce(source_updated_at, '') DESC, source, listing_id
+       LIMIT ?`,
+    ).all(now, freshCutoff, limit);
+    const chosenFresh = fresh.slice(0, freshLimit);
+    const chosenBacklog = backlog.slice(0, limit - chosenFresh.length);
+    const spillFresh = fresh.slice(chosenFresh.length, chosenFresh.length + limit - chosenFresh.length - chosenBacklog.length);
+    const items = [...chosenFresh, ...chosenBacklog, ...spillFresh].map(({ native_json, ...item }) => native_json === null
+      ? item : { ...item, native: JSON.parse(native_json) as DiscoveredSession["native"] });
+    return { items, fresh: chosenFresh.length + spillFresh.length, backlog: chosenBacklog.length };
+  }
+
+  removeQueuedIngest(item: Pick<DiscoveredSession, "source" | "id" | "path">): void {
+    this.db.run(
+      "DELETE FROM ingest_queue WHERE source = ? AND listing_id = ? AND source_path = ?",
+      [item.source, item.id, item.path],
+    );
+  }
+
+  markQueuedIngestProgress(
+    item: Pick<DiscoveredSession, "source" | "id" | "path">,
+    outcome: string,
+    now = new Date().toISOString(),
+  ): void {
+    this.db.run(
+      `UPDATE ingest_queue SET attempt_count = 0, next_attempt_at = NULL,
+        last_attempt_at = ?, last_outcome = ?
+       WHERE source = ? AND listing_id = ? AND source_path = ?`,
+      [now, outcome, item.source, item.id, item.path],
+    );
+  }
+
+  markQueuedIngestRetry(
+    item: Pick<DiscoveredSession, "source" | "id" | "path">,
+    outcome: string,
+    nextAttemptAt: string,
+    now = new Date().toISOString(),
+  ): void {
+    this.db.run(
+      `UPDATE ingest_queue SET attempt_count = attempt_count + 1, next_attempt_at = ?,
+        last_attempt_at = ?, last_outcome = ?
+       WHERE source = ? AND listing_id = ? AND source_path = ?`,
+      [nextAttemptAt, now, outcome, item.source, item.id, item.path],
+    );
+  }
+
+  getIngestQueueSummary(now = new Date().toISOString()): { total: number; eligible: number; retrying: number } {
+    return this.db.query<{ total: number; eligible: number; retrying: number }, [string, string]>(
+      `SELECT count(*) AS total,
+        coalesce(sum(next_attempt_at IS NULL OR next_attempt_at <= ?), 0) AS eligible,
+        coalesce(sum(next_attempt_at > ?), 0) AS retrying
+       FROM ingest_queue`,
+    ).get(now, now)!;
+  }
+
+  getAdaptivePressureState(): AdaptivePressureState {
+    const state = this.db.query<AdaptivePressureState, []>(
+      "SELECT scale_permille, calm_runs, last_severity FROM ingest_runtime_state WHERE id = 1",
+    ).get();
+    return state && Number.isSafeInteger(state.scale_permille) && state.scale_permille >= 250 && state.scale_permille <= 1000 &&
+      Number.isSafeInteger(state.calm_runs) && state.calm_runs >= 0 &&
+      ["unavailable", "calm", "constrained", "critical"].includes(state.last_severity)
+      ? state : { ...DEFAULT_PRESSURE_STATE };
+  }
+
+  setAdaptivePressureState(state: AdaptivePressureState, now = new Date().toISOString()): void {
+    this.db.run(
+      `INSERT INTO ingest_runtime_state (id, scale_permille, calm_runs, last_severity, updated_at)
+       VALUES (1, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET scale_permille = excluded.scale_permille,
+         calm_runs = excluded.calm_runs, last_severity = excluded.last_severity,
+         updated_at = excluded.updated_at`,
+      [state.scale_permille, state.calm_runs, state.last_severity, now],
+    );
+  }
+
+  hasRecord(id: string): boolean {
+    const row = this.db
+      .query<{ id: string }, [string]>(
+        "SELECT id FROM records WHERE id = ? LIMIT 1",
+      )
+      .get(id);
+    return !!row;
+  }
+
+  getSession(id: string): SessionRecord | null {
+    return sessionById(this.db, id);
+  }
+
+  getAllSessions(): SessionRecord[] {
+    return allSessions(this.db);
+  }
+
+  getLastSessions(options?: {
+    limit?: number;
+    source?: string;
+  }): SessionRecord[] {
+    return lastSessions(this.db, options);
+  }
+
+  getChildSessions(parentSessionId: string): SessionRecord[] {
+    return this.db
+      .query<SessionRecord, [string]>(
+        `SELECT * FROM sessions s WHERE s.parent_session_id = ?
+           AND NOT EXISTS (SELECT 1 FROM session_tombstones t WHERE t.session_id = s.id)
+         ORDER BY started_at ASC, id ASC`,
+      )
+      .all(parentSessionId);
+  }
+
+  getSessionLineage(sessionId: string): SessionRecord[] {
+    const chain: SessionRecord[] = [];
+    const seen = new Set<string>();
+    let current = this.getSession(sessionId);
+    while (current && !seen.has(current.id)) {
+      seen.add(current.id);
+      chain.push(current);
+      if (!current.parent_session_id) break;
+      current = this.getSession(current.parent_session_id);
+    }
+    return chain;
+  }
+
+  updateSessionParentage(sessionId: string, parentage: SessionParentage): boolean {
+    const existing = this.getSession(sessionId);
+    if (!existing) return false;
+    // Fresh source-backed metadata can correct an earlier edge even on a hash hit.
+    const next = mergeParentage({ ...parentage }, parentageOf(existing));
+    if (next.parent_session_id === sessionId) next.parent_session_id = null;
+    if (parentageEquals(parentageOf(existing), next)) return false;
+    this.db.run(
+      `UPDATE sessions SET
+        parent_session_id = ?, parent_tool_use_id = ?,
+        agent_nickname = ?, thread_role = ?
+       WHERE id = ?`,
+      [
+        next.parent_session_id,
+        next.parent_tool_use_id,
+        next.agent_nickname,
+        next.thread_role,
+        sessionId,
+      ],
+    );
+    return true;
+  }
+
+  backfillSessionParentage(): { scanned: number; updated: number } {
+    const sessions = this.getAllSessions();
+    let updated = 0;
+    for (const session of sessions) {
+      const extracted = extractSessionParentage(session.source, session.source_path, {
+        sessionId: nativeId(session.source, session.id),
+        onDiagnostic: (diagnostic) => console.warn(JSON.stringify({ type: "parentage_warning", ...diagnostic })),
+      });
+      if (extracted.parent_session_id) extracted.parent_session_id = ledgerId(session.source, extracted.parent_session_id);
+      if (extracted.parent_session_id === session.id) extracted.parent_session_id = null;
+      if (parentageEquals(extracted, EMPTY_SESSION_PARENTAGE)) continue;
+      if (this.updateSessionParentage(session.id, extracted)) updated++;
+    }
+    return { scanned: sessions.length, updated };
+  }
+
+  getSessionCount(): number {
+    return countSessions(this.db);
+  }
+
+  getRecordCount(): number {
+    return countRecords(this.db);
+  }
+
+  /** Store-wide diagnostics coverage, ordered by occurrences then code. */
+  getDiagnosticsSummary(): DiagnosticsSummary {
+    return readDiagnosticsSummary(this.db);
+  }
+
+  /** Diagnostics stored for one ledger session, ordered by code. */
+  getSessionDiagnostics(sessionId: string): IngestDiagnosticRecord[] {
+    return this.db
+      .query<IngestDiagnosticRecord, [string]>(
+        `SELECT session_id, source, code, occurrence_count, sample, first_seen_at, last_seen_at
+         FROM ingest_diagnostics WHERE session_id = ? ORDER BY code ASC`,
+      )
+      .all(sessionId);
+  }
+
+  /**
+   * Store this pass's verdict for every source it scanned: one row per outcome,
+   * replacing whatever the previous pass wrote — including a source that stopped
+   * being listable, so a stored success never outlives the scan that saw it.
+   * `first_seen_at` is deliberately not rewritten: the row keeps the first time
+   * this store saw the source, which is what makes coverage age readable.
+   *
+   * Called by the lease-holding passes (`sync`, `build`, `watch`) once per scan,
+   * with the complete outcome set: the write is the pass's, not the scan's, so a
+   * budget-truncated pass still reports what it saw and `scan` persists nothing.
+   * One transaction for the whole set, so readers see a pass's rows together.
+   */
+  recordSourceCoverage(outcomes: readonly ScanOutcome[], now: Date = new Date()): void {
+    if (outcomes.length === 0) return;
+    const updatedAt = now.toISOString();
+    const upsert = this.db.prepare(
+      `INSERT INTO source_coverage (source, root, status, discovered, detail, first_seen_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(source) DO UPDATE SET
+         root = excluded.root,
+         status = excluded.status,
+         discovered = excluded.discovered,
+         detail = excluded.detail,
+         updated_at = excluded.updated_at`,
+    );
+    this.db.transaction(() => {
+      for (const outcome of outcomes) {
+        upsert.run(
+          outcome.source,
+          outcome.root,
+          outcome.status,
+          outcome.discovered,
+          outcome.detail ?? null,
+          updatedAt,
+          updatedAt,
+        );
+      }
+    })();
+  }
+
+  /** Stored per-source coverage in source order; empty until a pass scans. */
+  /** Compact coverage signal for the sync summary; null pre-coverage table. */
+  getSourceCoverageSummary(): SourceCoverageSummary | null {
+    const hasTable = !!this.db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='source_coverage' LIMIT 1;",
+      )
+      .get();
+    return hasTable ? readSourceCoverageSummary(this.db) : null;
+  }
+
+  getSourceCoverage(): SourceCoverageRow[] {
+    return readSourceCoverage(this.db);
+  }
+
+  getSessionRecords(sessionId: string): CanonicalDbRecord[] {
+    return sessionRecords(this.db, sessionId);
+  }
+
+  /**
+   * Delete one session at the user's explicit request, and record the deletion.
+   *
+   * This method is the whole mechanism's only write, and the only way a
+   * tombstone can come into existence: no ingest path, scan, sync pass, or
+   * absence-of-file condition reaches it. That is the load-bearing half of
+   * "source truncation is not authorization to erase captured evidence"
+   * (`AGENTS.md`) — a vanished or shortened source is evidence about a source,
+   * never an instruction to delete, and the only thing that can produce a
+   * tombstone is a user naming a session.
+   *
+   * `suppress` (the default) leaves the store canonical: not one canonical or
+   * derived row is removed or rewritten. What changes is that every serving path
+   * stops resolving the session (reader.ts) and every admission path refuses to
+   * re-create it (ingest.ts, plus the store-boundary guards). The records stay
+   * because they are the evidence this store captured; a deletion must not be
+   * the one write in the system that destroys what an adapter already
+   * attributed, and the audit row is more useful beside the rows it names than
+   * instead of them. `hard` carries the same deletion through to the content:
+   * records, vectors, echo markers, titles, diagnostics, and any pending staged
+   * replacement go in this same transaction, and only the tombstone is left.
+   *
+   * One transaction either way. `suppress` writes exactly one row, so a crash
+   * leaves it present or absent; `hard` removes the content and writes the row
+   * together, so no reader can catch a store where the records are gone and the
+   * source is still free to re-admit the session — Wake's ordering, whose
+   * `remove_sessions` writes the tombstone in the same transaction as its
+   * deletes (`crates/wake-core/src/db.rs#L537-L571`).
+   *
+   * Repeat calls are idempotent and never rewrite the audit: a second
+   * `suppress`, or a `hard` on an already-`hard` row, reports the existing
+   * deletion and changes nothing. A `hard` on a `suppress` row is the one
+   * escalation — the same deletion carried further, so `deleted_at` and `reason`
+   * keep naming the moment and the account the user first gave.
+   */
+  tombstoneSession(
+    sessionId: string,
+    options: { reason: string; hard?: boolean; now?: Date },
+  ): TombstoneOutcome {
+    const reason = options.reason.trim();
+    if (!reason) {
+      // The audit row is the mechanism's record of why; an unexplained deletion
+      // is a hole in it. The CLI refuses earlier, with a usage error.
+      throw new Error("a tombstone needs a reason: the deletion's account is what the row preserves");
+    }
+    return this.db.transaction((): TombstoneOutcome => {
+      const existing = this.tombstoneRow(sessionId);
+      if (existing) {
+        if (existing.mode === "hard" || options.hard !== true) {
+          return { tombstone: existing, created: false, escalated: false, recordsRemoved: 0 };
+        }
+        this.db.run("UPDATE session_tombstones SET mode = 'hard' WHERE session_id = ?", [sessionId]);
+        this.clearAdmissionState(sessionId, existing.source, existing.native_id);
+        return {
+          tombstone: { ...existing, mode: "hard" },
+          created: false,
+          escalated: true,
+          recordsRemoved: this.removeSessionContent(sessionId),
+        };
+      }
+
+      // A tombstone needs no session row to remain meaningful (a `hard` deletion
+      // removes it), but it does need one to arise: see SessionNotFoundError.
+      const session = this.sessionRowById(sessionId);
+      if (!session) throw new SessionNotFoundError(sessionId);
+      const nativeIdValue = nativeId(session.source, sessionId);
+      const tombstone: TombstoneRecord = {
+        session_id: sessionId,
+        source: session.source,
+        native_id: nativeIdValue,
+        source_path: session.source_path ?? null,
+        mode: options.hard === true ? "hard" : "suppress",
+        reason,
+        record_count: session.record_count,
+        deleted_at: (options.now ?? new Date()).toISOString(),
+      };
+      this.db.run(
+        `INSERT INTO session_tombstones (
+          session_id, source, native_id, source_path, mode, reason, record_count, deleted_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+        [tombstone.session_id, tombstone.source, tombstone.native_id, tombstone.source_path,
+          tombstone.mode, tombstone.reason, tombstone.record_count, tombstone.deleted_at],
+      );
+      this.clearAdmissionState(sessionId, tombstone.source, nativeIdValue);
+      return {
+        tombstone,
+        created: true,
+        escalated: false,
+        recordsRemoved: tombstone.mode === "hard" ? this.removeSessionContent(sessionId) : 0,
+      };
+    }).immediate();
+  }
+
+  /**
+   * The serving axis: a tombstone by the Ledger session id every read verb
+   * resolves sessions with. Null for a session that was never deleted,
+   * including one this store has never held.
+   */
+  getTombstone(sessionId: string): TombstoneRecord | null {
+    return this.tombstoneRow(sessionId);
+  }
+
+  /**
+   * The admission axis: a tombstone a *listing* names before it has been read.
+   *
+   * Two lookups, because a listing id and a session's native id are not the same
+   * string in this store. The first is the direct one — the listing id *is* the
+   * session's native id (hermes and other listing-keyed sources, and any source
+   * that names the session after its file). The second uses evidence the store
+   * already keeps: a cursor that was ingested into a session now tombstoned is
+   * that session's own record of the listing it came from, which is what makes
+   * the axis hold for a source that keys rollouts by filename while the session
+   * inside carries its own id — measured on the production store, 1,724 of 2,681
+   * cursors name a listing id that differs from the session's native part, so the
+   * direct lookup alone would miss most real listings.
+   *
+   * Ledger declines to derive the second axis from the *path* (Wake's
+   * `file_path`): a path is not listing identity here (db.ts's
+   * `getLiveIngestSession`), and blocking on it would refuse every other listing
+   * a shared store keeps in one file. A cursor is listing identity, by
+   * construction — it is keyed by `(source, listing_id, source_path)`.
+   */
+  tombstoneForListing(item: Pick<DiscoveredSession, "source" | "id">): TombstoneRecord | null {
+    const direct = this.db
+      .query<TombstoneRecord, [string, string]>(
+        "SELECT * FROM session_tombstones WHERE source = ? AND native_id = ? LIMIT 1",
+      )
+      .get(item.source, item.id);
+    if (direct) return direct;
+    return (
+      this.db
+        .query<TombstoneRecord, [string, string]>(
+          `SELECT t.* FROM session_tombstones t
+           JOIN ingest_cursors c ON c.session_id = t.session_id
+           WHERE c.source = ? AND c.listing_id = ? LIMIT 1`,
+        )
+        .get(item.source, item.id) ?? null
+    );
+  }
+
+  /** Every tombstone, newest deletion first — the audit readout, not a search. */
+  listTombstones(): TombstoneRecord[] {
+    return this.db
+      .query<TombstoneRecord, []>(
+        "SELECT * FROM session_tombstones ORDER BY deleted_at DESC, session_id ASC",
+      )
+      .all();
+  }
+
+  private tombstoneRow(sessionId: string): TombstoneRecord | null {
+    return (
+      this.db
+        .query<TombstoneRecord, [string]>("SELECT * FROM session_tombstones WHERE session_id = ? LIMIT 1")
+        .get(sessionId) ?? null
+    );
+  }
+
+  /**
+   * The writer's own view of a session row, tombstones included. The read path's
+   * `getSession` hides a tombstoned session, which is exactly what serving
+   * means; the writer instead has to see the row it is about to refuse, replace,
+   * or remove — a hidden row would read as "absent" and send ingest down its
+   * cold-start path against a session that is still there.
+   */
+  private sessionRowById(id: string): SessionRecord | null {
+    return this.db.query<SessionRecord, [string]>("SELECT * FROM sessions WHERE id = ? LIMIT 1").get(id) ?? null;
+  }
+
+  /** Refuse a write that would admit a session the user deleted. */
+  private assertTombstoneFree(sessionId: string): void {
+    if (this.tombstoneRow(sessionId)) throw new TombstonedSessionError(sessionId);
+  }
+
+  /**
+   * Close the admission surfaces a tombstone opens: queued admissions for the
+   * listings that fed this session, and any pending staged replacement of it.
+   *
+   * None of them can be admitted now (the planner's listing check and the
+   * store's guards both refuse), so they are removed rather than left for a
+   * worker to refuse — and a staged replacement holds the session's records,
+   * which a `hard` deletion must not leave behind. The queue is matched both by
+   * the listing id the tombstone's native id names and by the listings its
+   * cursors name, which is the same pair of axes admission uses
+   * (`tombstoneForListing`); a source that holds several listings in one path
+   * keeps the rows of the listings that did not feed this session.
+   */
+  private clearAdmissionState(sessionId: string, source: string, nativeIdValue: string): void {
+    this.db.run("DELETE FROM ingest_staged_sessions WHERE replaced_session_id = ?", [sessionId]);
+    this.db.run(
+      `DELETE FROM ingest_queue
+       WHERE (source = ? AND listing_id = ?)
+          OR listing_id IN (SELECT listing_id FROM ingest_cursors WHERE session_id = ?)`,
+      [source, nativeIdValue, sessionId],
+    );
+  }
+
+  /**
+   * A `hard` deletion: the session's content, in this transaction, children
+   * first. The explicit deletes are not redundant with the foreign keys on
+   * `records` — the same reason `trg_sessions_diagnostics_delete` exists: a
+   * writer that never enabled them must still leave nothing behind. The title
+   * row goes with the session row through the trigger on `sessions`
+   * (`TITLES_FTS_TRIGGERS_SQL`), which is also what keeps the title index's
+   * rebuild gate's parity claim true. `ingest_cursors` is deliberately left
+   * alone: it is the evidence the listing axis reads, and it holds no content.
+   */
+  private removeSessionContent(sessionId: string): number {
+    this.db.run("DELETE FROM records_fts WHERE session_id = ?", [sessionId]);
+    this.db.run("DELETE FROM records_echo WHERE session_id = ?", [sessionId]);
+    this.db.run("DELETE FROM records_embeddings WHERE session_id = ?", [sessionId]);
+    this.db.run("DELETE FROM ingest_diagnostics WHERE session_id = ?", [sessionId]);
+    const removed = this.db.run("DELETE FROM records WHERE session_id = ?", [sessionId]).changes;
+    this.db.run("DELETE FROM sessions WHERE id = ?", [sessionId]);
+    return removed;
+  }
+
+  /**
+   * Save one full session normalization. `diagnostics` follows the same
+   * replacement rule as {@link commitIngest}: when supplied, this session's
+   * stored rows become exactly that aggregate, including the empty case.
+   */
+  saveSession(
+    session: SessionRecord,
+    records: CanonicalDbRecord[],
+    diagnostics?: readonly IngestDiagnosticAggregate[],
+  ): { inserted: boolean; updated: boolean; deduped: boolean } {
+    // One immediate transaction for the whole write: the deletion check, the
+    // dedupe read, and the rows it decides on. A tombstone committed by another
+    // writer between a check outside the transaction and the write inside it
+    // would otherwise land *under* the tombstone — the session's rows rewritten
+    // while the deletion's `record_count` spoke of a generation that no longer
+    // exists. Taking the write lock first is what makes the check the verdict
+    // rather than a guess about a store that may already have changed; a nested
+    // call (commitIngest's own transaction) joins it as a savepoint.
+    return this.db.transaction((): { inserted: boolean; updated: boolean; deduped: boolean } => {
+      this.assertTombstoneFree(session.id);
+      const existing = this.getSession(session.id);
+      if (existing) {
+        if (existing.content_hash === session.content_hash) {
+          // Content deduplication must not freeze a renamed or relocated session.
+          this.db.run(
+            `UPDATE sessions SET source_path = ?, title = ?, cwd = ?, model = ?,
+              started_at = ?, ended_at = ?, updated_at = ? WHERE id = ?`,
+            [session.source_path, session.title, session.cwd, session.model,
+              session.started_at, session.ended_at, session.updated_at, session.id],
+          );
+          this.updateSessionParentage(session.id, parentageOf(session));
+          // The records are unchanged, but a fresh normalization still owns this
+          // session's coverage: a finding that stopped occurring disappears.
+          if (diagnostics) this.writeIngestDiagnostics(session.id, session.source, diagnostics);
+          return { inserted: false, updated: false, deduped: true };
+        }
+        // Content updated -> replace records
+        this.db.run("DELETE FROM records_fts WHERE session_id = ?", [
+          session.id,
+        ]);
+        this.db.run("DELETE FROM records WHERE session_id = ?", [session.id]);
+        this.db.run(
+          `UPDATE sessions SET
+            source = ?, source_path = ?, content_hash = ?, content_hash_version = ?, title = ?, cwd = ?,
+            model = ?, started_at = ?, ended_at = ?, record_count = ?, updated_at = ?,
+            parent_session_id = ?, parent_tool_use_id = ?,
+            agent_nickname = ?, thread_role = ?
+           WHERE id = ?`,
+          [
+            session.source,
+            session.source_path,
+            session.content_hash,
+            session.content_hash_version ?? 1,
+            session.title,
+            session.cwd,
+            session.model,
+            session.started_at,
+            session.ended_at,
+            records.length,
+            session.updated_at,
+            session.parent_session_id ?? null,
+            session.parent_tool_use_id ?? null,
+            session.agent_nickname ?? null,
+            session.thread_role ?? null,
+            session.id,
+          ],
+        );
+        this.insertRecordsInternal(session.id, session.source, records);
+        if (diagnostics) this.writeIngestDiagnostics(session.id, session.source, diagnostics);
+        return { inserted: false, updated: true, deduped: false };
+      }
+
+      // New session
+      this.db.run(
+        `INSERT INTO sessions (
+          id, source, source_path, content_hash, content_hash_version, title, cwd, model,
+          started_at, ended_at, record_count, created_at, updated_at,
+          parent_session_id, parent_tool_use_id, agent_nickname, thread_role
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          session.id,
+          session.source,
+          session.source_path,
+          session.content_hash,
+          session.content_hash_version ?? 1,
+          session.title,
+          session.cwd,
+          session.model,
+          session.started_at,
+          session.ended_at,
+          records.length,
+          session.created_at,
+          session.updated_at,
+          session.parent_session_id ?? null,
+          session.parent_tool_use_id ?? null,
+          session.agent_nickname ?? null,
+          session.thread_role ?? null,
+        ],
+      );
+      this.insertRecordsInternal(session.id, session.source, records);
+      if (diagnostics) this.writeIngestDiagnostics(session.id, session.source, diagnostics);
+      return { inserted: true, updated: false, deduped: false };
+    }).immediate();
+  }
+
+  appendSessionRecords(
+    sessionId: string,
+    records: CanonicalDbRecord[],
+  ): { appended: number; deferred: boolean; historicalRecordsHashed: number; reason?: string } {
+    // The same one-transaction rule as `saveSession`: the deletion check, the
+    // per-record dedupe reads, and the append they authorize are one immediate
+    // transaction, so a tombstone cannot land between the verdict and the write
+    // (a nested call — commitIngest's transaction — joins it as a savepoint).
+    return this.db.transaction(
+      (): { appended: number; deferred: boolean; historicalRecordsHashed: number; reason?: string } => {
+        this.assertTombstoneFree(sessionId);
+        const session = this.getSession(sessionId);
+        if (!session) return { appended: 0, deferred: true, historicalRecordsHashed: 0, reason: "session_missing" };
+
+        const existingHash = this.db.query<{ record_hash: string }, [string]>(
+          "SELECT record_hash FROM records WHERE id = ?",
+        );
+        const fresh: CanonicalDbRecord[] = [];
+        for (const record of records) {
+          const previous = existingHash.get(record.id);
+          if (previous?.record_hash === record.record_hash) continue;
+          // Correcting an already committed record invalidates an append-only hash
+          // state. Preserve the live generation and rebuild it out of process.
+          if (previous) {
+            return { appended: 0, deferred: true, historicalRecordsHashed: 0, reason: "record_replacement" };
+          }
+          fresh.push(record);
+        }
+        if (fresh.length === 0) return { appended: 0, deferred: false, historicalRecordsHashed: 0 };
+        if ((session.content_hash_version ?? 1) !== SESSION_HASH_VERSION) {
+          return { appended: 0, deferred: true, historicalRecordsHashed: 0, reason: "legacy_session_hash" };
+        }
+
+        const now = new Date().toISOString();
+        let endedAt = session.ended_at;
+        for (const record of fresh) {
+          const ts = record.source_timestamp ?? record.record_timestamp;
+          if (ts && (!endedAt || ts > endedAt)) endedAt = ts;
+        }
+        const contentHash = extendSessionHash(session.content_hash, fresh);
+
+        this.insertRecordsInternal(sessionId, session.source, fresh);
+        this.db.run(
+          `UPDATE sessions SET
+            content_hash = ?, content_hash_version = ?, ended_at = ?, record_count = ?, updated_at = ?
+           WHERE id = ?`,
+          [contentHash, SESSION_HASH_VERSION, endedAt, session.record_count + fresh.length, now, sessionId],
+        );
+        return { appended: fresh.length, deferred: false, historicalRecordsHashed: 0 };
+      },
+    ).immediate();
+  }
+
+  /**
+   * Publish one normalization result. `opts.diagnostics` aggregates the library
+   * diagnostics of the records being published: a commit that publishes a whole
+   * session replaces the session's rows with it (an empty aggregate clears
+   * them), while a partial stage merges it into the staged replacement and an
+   * append leaves existing rows alone — coverage always reflects the most
+   * recent whole-file normalization, and appended content is not re-counted.
+   */
+  commitIngest(
+    session: SessionRecord,
+    records: CanonicalDbRecord[],
+    cursor: IngestCursor,
+    append = false,
+    complete = true,
+    opts: { diagnostics?: readonly IngestDiagnosticAggregate[] } = {},
+  ): IngestCommitOutcome {
+    return this.db.transaction(() => {
+      const staged = this.getStagedIngestSession(cursor);
+      const live = !append ? this.getLiveIngestSession(session, cursor) : null;
+      if (staged || (!append && live && (!complete || live.id !== session.id))) {
+        return this.commitStagedIngest(session, records, cursor, append, complete, staged, opts);
+      }
+      const result = append
+        ? { inserted: false, updated: false, deduped: false, ...this.appendSessionRecords(session.id, records) }
+        : { ...this.saveSession(session, records), appended: 0, deferred: false, historicalRecordsHashed: 0 };
+      if (result.deferred) {
+        this.deferIngestRebuild({ ...cursor, session_id: session.id });
+        return { ...result, deferReason: result.reason };
+      }
+      const stored = this.getSession(session.id);
+      this.upsertIngestCursor({ ...cursor, session_id: session.id, record_count: stored?.record_count ?? 0 });
+      // Only a pass that normalized the whole source describes the whole record
+      // set; a bounded prefix pass would claim coverage it never observed.
+      if (opts.diagnostics && !append && complete) {
+        this.writeIngestDiagnostics(session.id, cursor.source, opts.diagnostics);
+      }
+      return result;
+    }).immediate();
+  }
+
+  /**
+   * Replace one session's diagnostics rows with an observed aggregate. Counts
+   * are rewritten, never summed, so re-importing identical content is
+   * idempotent; a code that stops occurring disappears and `first_seen_at`
+   * survives while it keeps occurring. An empty aggregate clears stale rows and
+   * touches nothing else.
+   */
+  private writeIngestDiagnostics(
+    sessionId: string,
+    source: string,
+    diagnostics: readonly IngestDiagnosticAggregate[],
+  ): void {
+    // Nothing observed: one statement clears stale rows, no read and no write.
+    if (!diagnostics.length) {
+      this.db.run("DELETE FROM ingest_diagnostics WHERE session_id = ?", [sessionId]);
+      return;
+    }
+    const now = new Date().toISOString();
+    const firstSeen = new Map(
+      this.db
+        .query<{ code: string; first_seen_at: string }, [string]>(
+          "SELECT code, first_seen_at FROM ingest_diagnostics WHERE session_id = ?",
+        )
+        .all(sessionId)
+        .map((row) => [row.code, row.first_seen_at] as const),
+    );
+    const insert = this.db.prepare(
+      `INSERT INTO ingest_diagnostics (
+        session_id, code, source, occurrence_count, sample, first_seen_at, last_seen_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    );
+    this.db.transaction(() => {
+      this.db.run("DELETE FROM ingest_diagnostics WHERE session_id = ?", [sessionId]);
+      for (const diagnostic of diagnostics) {
+        insert.run(
+          sessionId,
+          diagnostic.code,
+          source,
+          diagnostic.occurrenceCount,
+          // Public callers can hand over an unbounded message; the stored sample
+          // stays bounded and code-point safe here too.
+          capDiagnosticSample(diagnostic.sample ?? ""),
+          firstSeen.get(diagnostic.code) ?? diagnostic.firstSeenAt ?? now,
+          now,
+        );
+      }
+    })();
+  }
+
+  /** Diagnostics carried by a staged replacement, if any chunk recorded them. */
+  private getStagedDiagnostics(key: [string, string, string]): IngestDiagnosticAggregate[] | undefined {
+    const row = this.db.query<{ diagnostics_json: string | null }, typeof key>(
+      "SELECT diagnostics_json FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?",
+    ).get(...key);
+    if (!row?.diagnostics_json) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(row.diagnostics_json);
+    } catch (cause) {
+      // Fail closed with the stage identity attached: the caller is inside
+      // the ingest transaction, so this aborts the pass rather than
+      // fabricating coverage from a value nobody can vouch for.
+      throw new StagedDiagnosticsParseError(key, cause);
+    }
+    if (!Array.isArray(parsed) || !parsed.every(isDiagnosticAggregate)) {
+      throw new StagedDiagnosticsParseError(key, null);
+    }
+    return parsed as IngestDiagnosticAggregate[];
+  }
+
+  deferIngestRebuild(cursor: IngestCursor): void {
+    this.db.transaction(() => {
+      this.db.run(
+        "DELETE FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?",
+        [cursor.source, cursor.listing_id, cursor.source_path],
+      );
+      this.upsertIngestCursor({
+        ...cursor,
+        bytes_ingested: 0,
+        record_count: 0,
+        status: "pending",
+        prefix_hash: null,
+        line_count: 0,
+        tail_offset: null,
+        tail_hash: null,
+      });
+    })();
+  }
+
+  // A source path is not listing identity: shared stores (e.g. hermes) hold many
+  // distinct listings at ONE source_path, so a path match alone must never
+  // authorize deleting another listing's session. Replacement identity is
+  // resolved from evidence: the incoming id, then the cursor that already
+  // claims this exact listing key, and only as a legacy fallback an unclaimed
+  // row that is this listing's own native projection. `cursor` is the incoming
+  // generation's cursor, so its own session_id is the NEW id and is deliberately
+  // not treated as evidence of the prior committed owner.
+  private getLiveIngestSession(session: SessionRecord, cursor: IngestCursor): SessionRecord | null {
+    const direct = this.sessionRowById(session.id);
+    if (direct) return direct;
+    // A stored claim authorizes replacement only while the claimed session is
+    // still this listing's own projection. Multi-file groups (claude-code) let
+    // several listings share one canonical id; a claim resolving to a session
+    // stored at another path names another listing's projection, not a
+    // predecessor of this one.
+    const owner = this.getIngestCursor(cursor.source, cursor.listing_id, cursor.source_path)?.session_id;
+    if (owner && owner !== session.id) {
+      const claimed = this.sessionRowById(owner);
+      if (claimed && claimed.source === cursor.source && claimed.source_path === cursor.source_path) {
+        return claimed;
+      }
+    }
+    // Pre-cursor rows only. An unclaimed path peer counts as this listing's
+    // prior projection only when its id is exactly the one this listing's
+    // native id produces (listing-keyed stores such as hermes/deepagents key
+    // the listing by the native session id). Any other row is absent evidence
+    // and must not authorize deleting another listing, even when it is the
+    // only unclaimed candidate at the path.
+    return this.db.query<SessionRecord, [string, string, string]>(
+      `SELECT s.* FROM sessions s
+       WHERE s.source = ? AND s.source_path = ? AND s.id = ?
+         AND NOT EXISTS (SELECT 1 FROM ingest_cursors c WHERE c.session_id = s.id)
+       LIMIT 1`,
+    ).get(cursor.source, cursor.source_path, ledgerId(cursor.source, cursor.listing_id)) ?? null;
+  }
+
+  private commitStagedIngest(
+    session: SessionRecord,
+    records: CanonicalDbRecord[],
+    cursor: IngestCursor,
+    append: boolean,
+    complete: boolean,
+    previous: SessionRecord | null,
+    opts: { diagnostics?: readonly IngestDiagnosticAggregate[] } = {},
+  ): IngestCommitOutcome {
+    // A staged replacement is still an admission: it writes the session row and
+    // its records when it promotes, so the deletion's verdict is taken here too
+    // — inside the same transaction that would have promoted it.
+    this.assertTombstoneFree(session.id);
+    const key: [string, string, string] = [cursor.source, cursor.listing_id, cursor.source_path];
+    const live = this.getLiveIngestSession(session, cursor);
+    // A changed source generation invalidates only the pending replacement, so
+    // its staged chunks never contribute coverage to the new generation.
+    const carried = append ? this.getStagedDiagnostics(key) : undefined;
+    if (!append) {
+      this.db.run("DELETE FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?", key);
+      previous = null;
+    }
+    const fallback = previous ?? live;
+    const staged: SessionRecord = {
+      ...session,
+      created_at: live?.created_at ?? session.created_at,
+      ...mergeParentage(parentageOf(session), fallback ? parentageOf(fallback) : EMPTY_SESSION_PARENTAGE),
+    };
+    if (staged.parent_session_id === staged.id) staged.parent_session_id = null;
+    for (const record of records) {
+      const ts = record.source_timestamp ?? record.record_timestamp;
+      if (ts && (!staged.started_at || ts < staged.started_at)) staged.started_at = ts;
+      if (ts && (!staged.ended_at || ts > staged.ended_at)) staged.ended_at = ts;
+    }
+    this.db.run(
+      `INSERT INTO ingest_staged_sessions (source, listing_id, source_path, replaced_session_id, session_json) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(source, listing_id, source_path) DO UPDATE SET session_json = excluded.session_json`,
+      [...key, live?.id ?? session.id, JSON.stringify(staged)],
+    );
+    const insert = this.db.prepare(
+      `INSERT INTO ingest_staged_records (
+        source, listing_id, source_path, id, record_type, source_order_id, component_index,
+        content_hash, record_hash, canonical_json
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(source, listing_id, source_path, id) DO UPDATE SET
+         record_type = excluded.record_type, source_order_id = excluded.source_order_id,
+         component_index = excluded.component_index, content_hash = excluded.content_hash,
+         record_hash = excluded.record_hash, canonical_json = excluded.canonical_json
+       WHERE record_hash != excluded.record_hash`,
+    );
+    let appended = 0;
+    for (const record of records) {
+      appended += insert.run(...key, record.id, record.record_type, record.source_order_id,
+        record.component_index, record.content_hash, record.record_hash, JSON.stringify(record)).changes;
+    }
+    staged.record_count = this.db.query<{ count: number }, typeof key>(
+      "SELECT COUNT(*) AS count FROM ingest_staged_records WHERE source = ? AND listing_id = ? AND source_path = ?",
+    ).get(...key)!.count;
+    staged.updated_at = cursor.updated_at;
+
+    let historicalRecordsHashed = 0;
+    if (complete) {
+      let hash = hashSessionRecords(staged.source, staged.id, []);
+      const rows = this.db.query<Pick<CanonicalDbRecord, "id" | "record_type" | "source_order_id" | "component_index" | "content_hash">, typeof key>(
+        `SELECT id, record_type, source_order_id, component_index, content_hash FROM ingest_staged_records
+         WHERE source = ? AND listing_id = ? AND source_path = ? ORDER BY source_order_id, component_index, id`,
+      );
+      for (const record of rows.iterate(...key)) {
+        hash = extendSessionHash(hash, [record]);
+        historicalRecordsHashed++;
+      }
+      staged.content_hash = hash;
+      staged.content_hash_version = SESSION_HASH_VERSION;
+      this.promoteStagedIngest(staged, key);
+      this.db.run("DELETE FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?", key);
+      // The promotion publishes a complete replacement. Coverage is the union of
+      // every chunk that produced a stage entry, or the fresh whole-file
+      // aggregate when this pass normalized the source itself; with neither, the
+      // promotion clears the predecessor's stale rows rather than keeping them.
+      const coverage = mergeIngestDiagnosticAggregates(carried, opts.diagnostics);
+      if (coverage) this.writeIngestDiagnostics(staged.id, key[0], coverage);
+    } else {
+      const pending = mergeIngestDiagnosticAggregates(carried, opts.diagnostics);
+      this.db.run(
+        `UPDATE ingest_staged_sessions SET session_json = ?, diagnostics_json = ?
+         WHERE source = ? AND listing_id = ? AND source_path = ?`,
+        [JSON.stringify(staged), pending ? JSON.stringify(pending) : null, ...key],
+      );
+    }
+    // While a replacement is only staged, the cursor keeps claiming the still
+    // live owner: writing the staged id here would transiently unclaim it and
+    // destroy prior-owner evidence if staging were cancelled or restarted.
+    this.upsertIngestCursor({
+      ...cursor,
+      session_id: complete ? staged.id : (live?.id ?? staged.id),
+      record_count: staged.record_count,
+    });
+    return { inserted: complete && !live, updated: complete && !!live, deduped: false, appended,
+      staged: !complete, deferred: false, historicalRecordsHashed };
+  }
+
+  private promoteStagedIngest(session: SessionRecord, key: [string, string, string]): void {
+    const previousId = this.db.query<{ replaced_session_id: string }, typeof key>(
+      "SELECT replaced_session_id FROM ingest_staged_sessions WHERE source = ? AND listing_id = ? AND source_path = ?",
+    ).get(...key)!.replaced_session_id;
+    // Ownership can change after a stage is created, including across restart.
+    // Recheck the current projection and other listing claims in this transaction
+    // before deleting the predecessor captured by the stage.
+    const previous = this.sessionRowById(previousId);
+    // Legacy stages were selected by path and their cursors pointed at the
+    // incoming generation. Require surviving listing evidence, not that old
+    // stage's predecessor field, before deleting a possibly unrelated row.
+    const owner = this.getIngestCursor(...key)?.session_id;
+    const ownsPrevious = owner === previousId || previousId === ledgerId(key[0], key[1]);
+    const otherClaim = this.db.query<{ present: number }, [string, string, string, string]>(
+      `SELECT 1 AS present FROM ingest_cursors WHERE session_id = ?
+       AND NOT (source = ? AND listing_id = ? AND source_path = ?) LIMIT 1`,
+    ).get(previousId, ...key);
+    if (previousId !== session.id && ownsPrevious && previous?.source === key[0] &&
+        previous.source_path === key[2] && !otherClaim) {
+      this.db.run("DELETE FROM records_fts WHERE session_id = ?", [previousId]);
+      this.db.run("DELETE FROM ingest_diagnostics WHERE session_id = ?", [previousId]);
+      this.db.run("DELETE FROM sessions WHERE id = ?", [previousId]);
+    }
+    this.db.run("DELETE FROM records_fts WHERE session_id = ?", [session.id]);
+    this.db.run("DELETE FROM records WHERE session_id = ?", [session.id]);
+    // The rows described records that this promotion replaces; they are stale
+    // until the promotion writes the coverage of the new generation.
+    this.db.run("DELETE FROM ingest_diagnostics WHERE session_id = ?", [session.id]);
+    this.db.run(
+      `INSERT INTO sessions (
+        id, source, source_path, content_hash, content_hash_version, title, cwd, model, started_at, ended_at,
+        record_count, created_at, updated_at, parent_session_id, parent_tool_use_id, agent_nickname, thread_role
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         source = excluded.source, source_path = excluded.source_path, content_hash = excluded.content_hash,
+         content_hash_version = excluded.content_hash_version,
+         title = excluded.title, cwd = excluded.cwd, model = excluded.model, started_at = excluded.started_at,
+         ended_at = excluded.ended_at, record_count = excluded.record_count, updated_at = excluded.updated_at,
+         parent_session_id = excluded.parent_session_id, parent_tool_use_id = excluded.parent_tool_use_id,
+         agent_nickname = excluded.agent_nickname, thread_role = excluded.thread_role`,
+      [session.id, session.source, session.source_path, session.content_hash, session.content_hash_version ?? 1,
+        session.title, session.cwd,
+        session.model, session.started_at, session.ended_at, session.record_count, session.created_at,
+        session.updated_at, session.parent_session_id ?? null, session.parent_tool_use_id ?? null,
+        session.agent_nickname ?? null, session.thread_role ?? null],
+    );
+    // Iterate the durable replacement; never materialize a session's full payload history.
+    const rows = this.db.query<{ canonical_json: string }, typeof key>(
+      `SELECT canonical_json FROM ingest_staged_records WHERE source = ? AND listing_id = ? AND source_path = ?
+       ORDER BY source_order_id, component_index`,
+    );
+    let batch: CanonicalDbRecord[] = [];
+    for (const row of rows.iterate(...key)) {
+      batch.push(JSON.parse(row.canonical_json) as CanonicalDbRecord);
+      if (batch.length === 256) {
+        this.insertRecordsInternal(session.id, session.source, batch);
+        batch = [];
+      }
+    }
+    if (batch.length) this.insertRecordsInternal(session.id, session.source, batch);
+  }
+
+  private insertRecordsInternal(
+    sessionId: string,
+    sourceType: string,
+    records: CanonicalDbRecord[],
+  ): void {
+    const insertRecordStmt = this.db.prepare(
+      `INSERT OR REPLACE INTO records (
+        id, session_id, source_type, native_session_id, binding_id, record_type, stable_source_record_id,
+        source_identity_kind, source_order_id, component_index, record_timestamp,
+        source_timestamp, content, tool_call_id, tool_name, tool_arguments_json,
+        tool_result_json, tool_result_ok, record_json, content_hash, record_hash
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    const insertFtsStmt = this.db.prepare(
+      `INSERT INTO records_fts (
+        record_id, session_id, source_type, record_type, content,
+        tool_name, tool_arguments, tool_result
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    const insertEchoStmt = this.db.prepare(
+      "INSERT OR REPLACE INTO records_echo (record_id, session_id) VALUES (?, ?)",
+    );
+
+    // Canonical first, whole batch: the echo filter classifies a tool *result*
+    // through its call, and that call may be a row the batch itself carries, so
+    // the batch has to be readable in `records` before the index is asked.
+    for (const r of records) {
+      insertRecordStmt.run(
+        r.id,
+        sessionId,
+        sourceType === "managed" ? r.source_type : sourceType,
+        r.native_session_id ?? null,
+        r.binding_id ?? null,
+        r.record_type,
+        r.stable_source_record_id,
+        r.source_identity_kind,
+        r.source_order_id,
+        r.component_index,
+        r.record_timestamp,
+        r.source_timestamp,
+        r.content,
+        r.tool_call_id,
+        r.tool_name,
+        r.tool_arguments_json,
+        r.tool_result_json,
+        r.tool_result_ok,
+        r.record_json,
+        r.content_hash,
+        r.record_hash,
+      );
+    }
+
+    // The self-referential echo filter (filter.ts): a lookup of Ledger itself
+    // is canonical data but not searchable material, so it never reaches the
+    // index. Same rule as the re-derivation's — and for a result whose call
+    // landed in an earlier batch, the same store lookup the re-derivation
+    // performs, so the two derivations cannot disagree. The id lands in the
+    // filter's derived set instead, which is what keeps the index and the set
+    // one decision: the status count and the parity gate both read it back.
+    const { excluded, callIds } = echoExcludedBatchIds(this.db, sessionId, records);
+
+    if (callIds.size > 0) {
+      // A result can be committed before its call (the source order is the
+      // source's, and the batch that carried the result had no lookup to pair
+      // it with), which left its index row behind. The call arriving now takes
+      // it back in the same transaction: the committed rows pairing these call
+      // ids leave the index and join the derived set. Rows of this batch are
+      // touched too — the delete matches nothing yet and the insert is
+      // idempotent with the loop below — so arrival order cannot decide what
+      // the pair derives to.
+      const ids = JSON.stringify([...callIds]);
+      const pairedResults = `SELECT r.id FROM records r
+         WHERE r.session_id = ? AND r.record_type = 'tool'
+           AND r.tool_call_id IN (SELECT value FROM json_each(?))`;
+      this.db.run(`DELETE FROM records_fts WHERE record_id IN (${pairedResults})`, [sessionId, ids]);
+      this.db.run(
+        `INSERT OR REPLACE INTO records_echo (record_id, session_id)
+         SELECT r.id, r.session_id FROM records r
+          WHERE r.session_id = ? AND r.record_type = 'tool'
+            AND r.tool_call_id IN (SELECT value FROM json_each(?))`,
+        [sessionId, ids],
+      );
+    }
+
+    for (const r of records) {
+      if (excluded.has(r.id)) {
+        insertEchoStmt.run(r.id, sessionId);
+        continue;
+      }
+
+      // Extract tool arguments / tool result text for FTS indexing
+      const toolArgs = r.tool_arguments_json ?? "";
+      const toolRes = r.tool_result_json ?? (r.record_type === "tool" ? r.content : "");
+
+      insertFtsStmt.run(
+        r.id,
+        sessionId,
+        sourceType === "managed" ? r.source_type : sourceType,
+        r.record_type,
+        r.content ?? "",
+        r.tool_name ?? "",
+        toolArgs,
+        toolRes ?? "",
+      );
+    }
+  }
+
+  query(
+    queryText: string,
+    options?: { limit?: number; source?: string; mode?: "lexical" },
+  ): QueryResult;
+  query(
+    queryText: string,
+    options: { limit?: number; source?: string; mode: "semantic" | "hybrid" },
+  ): Promise<QueryResult>;
+  query(
+    queryText: string,
+    options?: { limit?: number; source?: string; mode?: "lexical" | "semantic" | "hybrid" },
+  ): QueryResult | Promise<QueryResult>;
+  query(
+    queryText: string,
+    options: { limit?: number; source?: string; mode?: "lexical" | "semantic" | "hybrid" } = {},
+  ): QueryResult | Promise<QueryResult> {
+    if (options.mode === "semantic") {
+      return this.querySemantic(queryText, options);
+    }
+    if (options.mode === "hybrid") {
+      return this.queryHybrid(queryText, options);
+    }
+    return this.queryLexical(queryText, options);
+  }
+
+  queryLexical(
+    queryText: string,
+    options: { limit?: number; source?: string } = {},
+  ): QueryResult {
+    return queryLexical(this.db, queryText, options);
+  }
+
+  /**
+   * The writer handle may embed what the store is missing before it asks: a
+   * library caller querying this store expects the vectors it can afford to
+   * compute, while the read path (TrajectoryReader) never writes and reports
+   * `fallback_reason: "embeddings_unavailable"` instead.
+   */
+  private async ensureQueryEmbeddings(): Promise<void> {
+    if (compatibleEmbeddingCount(this.db) === 0 && this.getRecordCount() > 0) {
+      await this.backfillEmbeddings();
+    }
+  }
+
+  async querySemantic(
+    queryText: string,
+    options: { limit?: number; source?: string } = {},
+  ): Promise<QueryResult> {
+    await this.ensureQueryEmbeddings();
+    return querySemantic(this.db, queryText, options);
+  }
+
+  async queryHybrid(
+    queryText: string,
+    options: { limit?: number; source?: string } = {},
+  ): Promise<QueryResult> {
+    await this.ensureQueryEmbeddings();
+    return queryHybrid(this.db, queryText, options);
+  }
+
+  insertRecordEmbeddings(
+    records: Array<{
+      recordId: string;
+      sessionId: string;
+      embedding: Float32Array;
+      createdAt?: string;
+      provider?: string;
+      dim?: number;
+    }>,
+  ): void {
+    if (records.length === 0) return;
+    const now = new Date().toISOString();
+    const insertStmt = this.db.prepare(
+      `INSERT OR REPLACE INTO records_embeddings (record_id, session_id, embedding, provider, dim, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    );
+
+    // The vector lane's own admission check, inside the transaction that writes
+    // it: a deleted session gets no new vectors (and, in `suppress` mode, keeps
+    // none of its own either — serving filters them out through their session).
+    // The batch may span sessions, so the refusal names the one that was deleted
+    // rather than dropping the rows silently; the backfill below never asks for a
+    // tombstoned session.
+    this.db.transaction(() => {
+      const sessionIds = [...new Set(records.map((record) => record.sessionId))];
+      const tombstoned = this.db
+        .query<TombstoneRecord, [string]>(
+          `SELECT * FROM session_tombstones WHERE session_id IN (SELECT value FROM json_each(?)) LIMIT 1`,
+        )
+        .get(JSON.stringify(sessionIds));
+      if (tombstoned) throw new TombstonedSessionError(tombstoned.session_id);
+      for (const r of records) {
+        insertStmt.run(
+          r.recordId,
+          r.sessionId,
+          serializeEmbedding(r.embedding),
+          r.provider ?? "all-MiniLM-L6-v2",
+          r.dim ?? 384,
+          r.createdAt ?? now,
+        );
+      }
+    }).immediate();
+  }
+
+  async embedSessionRecords(
+    sessionId: string,
+    records: CanonicalDbRecord[],
+  ): Promise<number> {
+    const toEmbed: Array<{ recordId: string; text: string }> = [];
+    for (const r of records) {
+      const text = getRecordEmbeddingText(r);
+      if (text) {
+        toEmbed.push({ recordId: r.id, text });
+      }
+    }
+
+    if (toEmbed.length === 0) return 0;
+
+    const texts = toEmbed.map((item) => item.text);
+    const vectors = await embed(texts);
+    const provider = getEmbeddingProvider();
+
+    const now = new Date().toISOString();
+    const payload = toEmbed.map((item, i) => ({
+      recordId: item.recordId,
+      sessionId,
+      embedding: vectors[i],
+      createdAt: now,
+      provider: provider.name,
+      dim: provider.dimension,
+    }));
+
+    this.insertRecordEmbeddings(payload);
+    return payload.length;
+  }
+
+  async backfillEmbeddings(
+    options: { limit?: number; batchSize?: number; verbose?: boolean } = {},
+  ): Promise<{ processed: number; embedded: number }> {
+    const provider = getEmbeddingProvider();
+    const batchSize = options.batchSize ?? 32;
+    const limitClause = options.limit ? `LIMIT ${options.limit}` : "";
+
+    interface UnembeddedRow {
+      id: string;
+      session_id: string;
+      record_type: string;
+      content: string | null;
+      tool_name: string | null;
+      tool_arguments_json: string | null;
+      tool_result_json: string | null;
+    }
+
+    const rows = this.db
+      .query<UnembeddedRow, [string, number]>(
+        `SELECT r.id, r.session_id, r.record_type, r.content, r.tool_name, r.tool_arguments_json, r.tool_result_json
+         FROM records r
+         LEFT JOIN records_embeddings e
+           ON e.record_id = r.id AND e.provider = ? AND e.dim = ?
+         WHERE e.record_id IS NULL
+           AND NOT EXISTS (SELECT 1 FROM session_tombstones t WHERE t.session_id = r.session_id)
+         ORDER BY r.rowid ASC
+         ${limitClause}`,
+      )
+      .all(provider.name, provider.dimension);
+
+    if (rows.length === 0) {
+      return { processed: 0, embedded: 0 };
+    }
+
+    let embeddedCount = 0;
+    for (let i = 0; i < rows.length; i += batchSize) {
+      const chunk = rows.slice(i, i + batchSize);
+      const toEmbed: Array<{ recordId: string; sessionId: string; text: string }> = [];
+      for (const r of chunk) {
+        const text = getRecordEmbeddingText(r);
+        if (text) {
+          toEmbed.push({ recordId: r.id, sessionId: r.session_id, text });
+        }
+      }
+
+      if (toEmbed.length > 0) {
+        const texts = toEmbed.map((item) => item.text);
+        const vectors = await provider.embed(texts);
+        const now = new Date().toISOString();
+        const payload = toEmbed.map((item, idx) => ({
+          recordId: item.recordId,
+          sessionId: item.sessionId,
+          embedding: vectors[idx],
+          createdAt: now,
+          provider: provider.name,
+          dim: provider.dimension,
+        }));
+        this.insertRecordEmbeddings(payload);
+        embeddedCount += payload.length;
+      }
+    }
+
+    return { processed: rows.length, embedded: embeddedCount };
+  }
+
+  getEmbeddingCount(): number {
+    return (
+      this.db
+        .query<{ count: number }, []>(
+          "SELECT count(*) AS count FROM records_embeddings;",
+        )
+        .get()?.count ?? 0
+    );
+  }
+
+  /** Stored vectors of any provider; observational and never loads a model. */
+  hasStoredSessionEmbeddings(sessionId: string): boolean {
+    return !!this.db.query<{ present: number }, [string]>(
+      "SELECT EXISTS(SELECT 1 FROM records_embeddings WHERE session_id = ?) AS present",
+    ).get(sessionId)?.present;
+  }
+
+  hasSessionEmbeddings(sessionId: string): boolean {
+    const provider = getEmbeddingProvider();
+    const row = this.db
+      .query<{ count: number }, [string, string, number]>(
+        "SELECT count(*) AS count FROM records_embeddings WHERE session_id = ? AND provider = ? AND dim = ? LIMIT 1;",
+      )
+      .get(sessionId, provider.name, provider.dimension);
+    return (row?.count ?? 0) > 0;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  getSchemaVersion(): number {
+    return (
+      this.db
+        .query<{ user_version: number }, []>("PRAGMA user_version;")
+        .get()?.user_version ?? 0
+    );
+  }
+}
+
+function parentageOf(session: SessionRecord): SessionParentage {
+  return {
+    parent_session_id: session.parent_session_id ?? null,
+    parent_tool_use_id: session.parent_tool_use_id ?? null,
+    agent_nickname: session.agent_nickname ?? null,
+    thread_role: session.thread_role ?? null,
+  };
+}
+
+/**
+ * The v11 rebuild's post-copy gates, both fatal inside the migration
+ * transaction: a failure aborts the migration and leaves the store at v10 with
+ * its previous index rather than committing a half-rebuilt one.
+ *
+ * The parity count cannot see a table that answers `MATCH` while its internal
+ * structures disagree with the content it holds, so FTS5's own
+ * `integrity-check` follows it. The count is deliberately count-only: the
+ * projection is one row per record the echo filter keeps, so a rowid-set
+ * comparison would test the same fact more expensively — it is the recorded
+ * tighten if the projection ever stops being a whole-table repopulation.
+ *
+ * The echo set is the third term because the projection is no longer one row
+ * per record: `records - excluded` is what the index must hold. A store that
+ * predates the filter's table excludes nothing (the honest reading: no
+ * derivation under these rules has run), and an excluded id that no longer
+ * backs a record would make the count a lie — the foreign key already forbids
+ * one, so the check is what catches a writer that ran without them on. Module
+ * scope rather than a method so the gates can be driven directly against a
+ * doctored store: that same property leaves both branches unreachable through a
+ * store that was merely written, healthy or not.
+ */
+export function verifyRecordsFtsRebuild(db: Database): void {
+  const parity = db
+    .query<{ records: number; indexed: number }, []>(
+      `SELECT (SELECT COUNT(*) FROM records) AS records,
+              (SELECT COUNT(*) FROM records_fts) AS indexed;`,
+    )
+    .get();
+  const excluded = echoCount(db) ?? 0;
+  if (!parity || parity.records - excluded !== parity.indexed) {
+    throw new Error(
+      `records_fts rebuild parity check failed: records=${parity?.records ?? 0} excluded=${excluded} indexed=${parity?.indexed ?? 0}`,
+    );
+  }
+  const orphans = db
+    .query<{ count: number }, []>(
+      `SELECT COUNT(*) AS count FROM records_echo e
+       WHERE NOT EXISTS (SELECT 1 FROM records r WHERE r.id = e.record_id);`,
+    )
+    .get();
+  if (orphans && orphans.count > 0) {
+    throw new Error(
+      `records_echo integrity check failed: ${orphans.count} excluded ids no longer back a record`,
+    );
+  }
+  try {
+    db.run("INSERT INTO records_fts(records_fts) VALUES('integrity-check');");
+  } catch (error) {
+    throw new Error(
+      `records_fts rebuild integrity check failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+/**
+ * The title index's rebuild gate, fatal inside the same transaction the
+ * records index's gate guards.
+ *
+ * Parity here is exact rather than subtracted: the index holds one row per
+ * session the store has a title for, so the count against
+ * `sessions WHERE title != ''` (the repopulation's own predicate) is the whole
+ * claim. The orphan check is the one thing a virtual table cannot enforce for
+ * itself — no foreign key reaches into `titles_fts` — so a row whose session is
+ * gone is caught here; the maintenance trigger is what keeps a healthy store
+ * from ever producing one. FTS5's `integrity-check` follows for the same reason
+ * it follows `records_fts`'s count: a table can answer `MATCH` while its
+ * internal structures disagree with the content it holds.
+ *
+ * Module scope rather than a method so the gate can be driven directly against
+ * a doctored store: that property leaves its failure branches unreachable
+ * through a store that was merely written, healthy or not.
+ */
+export function verifyTitlesFtsRebuild(db: Database): void {
+  const parity = db
+    .query<{ indexable: number; indexed: number }, []>(
+      `SELECT (SELECT COUNT(*) FROM sessions WHERE ${INDEXABLE_TITLE_SQL}) AS indexable,
+              (SELECT COUNT(*) FROM titles_fts) AS indexed;`,
+    )
+    .get();
+  if (!parity || parity.indexable !== parity.indexed) {
+    throw new Error(
+      `titles_fts rebuild parity check failed: sessions with a title=${parity?.indexable ?? 0} indexed=${parity?.indexed ?? 0}`,
+    );
+  }
+  const orphans = db
+    .query<{ count: number }, []>(
+      `SELECT COUNT(*) AS count FROM titles_fts t
+       WHERE NOT EXISTS (SELECT 1 FROM sessions s WHERE s.id = t.session_id);`,
+    )
+    .get();
+  if (orphans && orphans.count > 0) {
+    throw new Error(
+      `titles_fts integrity check failed: ${orphans.count} indexed titles no longer back a session`,
+    );
+  }
+  try {
+    db.run("INSERT INTO titles_fts(titles_fts) VALUES('integrity-check');");
+  } catch (error) {
+    throw new Error(
+      `titles_fts rebuild integrity check failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+/**
+ * Summarize stored diagnostics through any handle, including the read-only
+ * connection a status probe uses. Callers that may face an unmigrated store
+ * must confirm the table exists first.
+ */
+export function readDiagnosticsSummary(db: Database): DiagnosticsSummary {
+  const total = db
+    .query<{ sessions: number; occurrences: number }, []>(
+      `SELECT COUNT(DISTINCT session_id) AS sessions, COALESCE(SUM(occurrence_count), 0) AS occurrences
+       FROM ingest_diagnostics`,
+    )
+    .get()!;
+  const byCode = db
+    .query<DiagnosticsSummary["byCode"][number], []>(
+      `SELECT code, COUNT(DISTINCT session_id) AS sessions, COALESCE(SUM(occurrence_count), 0) AS occurrences
+       FROM ingest_diagnostics GROUP BY code ORDER BY occurrences DESC, code ASC`,
+    )
+    .all();
+  return { totalSessions: total.sessions, totalOccurrences: total.occurrences, byCode };
+}
+
+/**
+ * Read stored per-source coverage in source order through any handle, including
+ * the read-only connection a status probe uses. Callers that may face an
+ * unmigrated store must confirm the table exists first.
+ */
+export function readSourceCoverage(db: Database): SourceCoverageRow[] {
+  return db
+    .query<SourceCoverageRow, []>(
+      `SELECT source, root, status, discovered, detail, first_seen_at, updated_at
+       FROM source_coverage ORDER BY source ASC`,
+    )
+    .all();
+}
+
+export interface SourceCoverageSummary {
+  /** Sources whose last scan verdict is anything other than `listable`. */
+  degraded: number;
+  /** Rows present — one per source the recorded passes have scanned. */
+  total: number;
+  /** Oldest `updated_at` across rows: the least-recently-rescanned source. */
+  oldest_updated_at: string;
+}
+
+/**
+ * Compact coverage signal for the search/sync robot envelopes: how many
+ * sources are degraded at their last scan, over how many recorded, plus the
+ * staleness floor. Null when no pass has recorded coverage yet (or the store
+ * predates the table), so the envelopes simply omit the field.
+ */
+export function readSourceCoverageSummary(db: Database): SourceCoverageSummary | null {
+  const row = db
+    .query<{ degraded: number; total: number; oldest_updated_at: string }, []>(
+      `SELECT
+         SUM(CASE WHEN status <> 'listable' THEN 1 ELSE 0 END) AS degraded,
+         COUNT(*) AS total,
+         MIN(updated_at) AS oldest_updated_at
+       FROM source_coverage`,
+    )
+    .get();
+  if (!row || row.total === 0) return null;
+  return { degraded: row.degraded ?? 0, total: row.total, oldest_updated_at: row.oldest_updated_at };
+}
+
+/** Read-only and version-tolerant: pre-v14 or never-scanned stores are unknown. */
+export function readDiscoverySummary(db: Database): DiscoverySummary | null {
+  if (!db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='source_discovery'").get()) return null;
+  const row = db.query<DiscoverySummary, []>(`SELECT COUNT(*) AS total_sources,
+    COALESCE(SUM(cursor IS NOT NULL), 0) AS pending_sources,
+    COALESCE(SUM(status = 'unknown' OR degraded = 1), 0) AS unknown_sources,
+    COALESCE(SUM(status = 'exhausted'), 0) AS exhausted_sources,
+    CASE WHEN COUNT(last_completed_at) = COUNT(*) THEN MIN(last_completed_at) ELSE NULL END AS oldest_completed_at
+    FROM source_discovery`).get();
+  return row?.total_sources ? row : null;
+}