trajectories 0.0.0 → 0.1.2

package/legacy/src/schema.ts

@@ -0,0 +1,829 @@
+/**
+ * The schema version this build writes: `PRAGMA user_version` on every writer
+ * open.
+ *
+ * 14 is reserved for `source_discovery` (PR #52): a store that ran that
+ * unmerged binary is at `user_version` 14 with discovery checkpoints and
+ * without `session_tombstones`. 15 is C7's `session_tombstones`. Both tables
+ * arrive from the same idempotent `CREATE_TABLES_SQL`; existing tombstones
+ * are never dropped.
+ *
+ * 16 adds nullable native-session and binding provenance to `records`.
+ * Writer opens migrate older layouts; read-only opens keep serving readable
+ * older stores without adding these optional columns. C8's `SYNC_STAMP_DDL`
+ * remains a contract only: this build does not install `sync_stamps`.
+ */
+export const SCHEMA_VERSION = 16;
+
+/**
+ * The derive-rule counters: the version of the *rules* a derived index was
+ * produced by, recorded in `schema_meta` beside `SCHEMA_VERSION` rather than as
+ * part of it.
+ *
+ * The distinction is the whole point. A derived index is repairable from
+ * canonical, in-store data, so changing how it is derived must cost one
+ * re-derivation on the next writer pass — not a schema migration that every
+ * older build refuses outright. Wake splits the same way: `FTS_FORMAT` is
+ * compared at open and stamped next to a transient `fts_reindex` flag
+ * (`crates/wake-core/src/db.rs#L128-L136`, `#L176-L196`), while migrations move
+ * `NEWEST_COLUMN`/`NEWEST_TABLE` — the read-only gate, `#L231-L233`,
+ * `#L326-L334` — only when the store's *shape* changes.
+ *
+ * The value is a decimal integer: bump it by one whenever the derivation rules
+ * change, never re-use a value. Both the writer's detection and the read gate
+ * compare numerically, so the ordering stays monotonic in both directions (a
+ * `"10"` is newer than a `"2"`).
+ *
+ * `"1"` is the projection {@link FTS_REPOPULATE_SQL} implements — value for
+ * value what ingest writes (`insertRecordsInternal`, db.ts) and what the v11
+ * rebuild re-projected. `"2"` is that same projection with the self-referential
+ * echo filter applied (filter.ts): the records of an agent asking Ledger itself
+ * are canonical and complete, but no longer searchable material, so both ingest
+ * and the re-derivation leave them out of `records_fts`. `"3"` adds the title
+ * index ({@link TITLES_FTS_DDL}): a session whose title the store holds is
+ * searchable by that title, maintained by the triggers on `sessions` and
+ * re-derived by the same one-shot. The bump is what makes every store written
+ * before a change re-derive itself once on its next writer pass — exactly the
+ * shape change this counter exists to carry.
+ */
+export const FTS_FORMAT = "3";
+
+/**
+ * The embeddings lane's counter: `"1"` is `getRecordEmbeddingText`
+ * (embeddings.ts), the text projection every stored vector was derived from.
+ * Provider identity and dimension are a separate axis, carried per row and
+ * already tracked by `compatibleEmbeddingCount`; this counter names only the
+ * rule that turns a record into the text that is embedded.
+ */
+export const EMBEDDINGS_FORMAT = "1";
+
+/**
+ * One derived index: where its rule version is recorded, the transient flag a
+ * mismatch raises, and what this build derives. Detection, the read gate and
+ * the tests all read this table, so a new derived index is one row here instead
+ * of a fourth special case.
+ */
+export interface DeriveCounter {
+  /** `schema_meta` key holding the rule version the store's data was derived under. */
+  readonly format: string;
+  /** `schema_meta` key set to `"1"` while a re-derivation is pending. */
+  readonly flag: string;
+  /** The rule version this build derives; bump on any rule change. */
+  readonly current: string;
+  /**
+   * Whether a store that records *no* value for this counter — every store
+   * written before the counter existed — counts as pending. True where this
+   * build can execute the re-derivation (the FTS projection: in-store, cheap,
+   * and it repairs drift on the way, which is Wake's stance for an unrecorded
+   * `fts_format`, `db.rs#L176-L196`); false where the re-derivation is deferred
+   * until its lane ships (the vectors lane). An unrecorded counter is not a
+   * *moved* one: the flag names a derivation that contradicts this build's
+   * rules, and a store that names nothing contradicts nothing. Raising it there
+   * would leave every upgraded store carrying a promise no pass in this build
+   * can keep.
+   */
+  readonly flagsWhenUnrecorded: boolean;
+  /**
+   * The tables a derivation under these rules produces. A matched counter
+   * claims its derivation happened, so a store that holds the value and not an
+   * output contradicts itself — the flag is raised for it exactly as a *moved*
+   * counter raises it. Empty where the derivation's output is not a table of
+   * its own (the vectors lane writes rows into `records_embeddings`, a table
+   * every store has carried since before the counter existed).
+   */
+  readonly outputs: readonly string[];
+}
+
+/** In detection order, which is also the order a mismatch is reported in. */
+export const DERIVE_COUNTERS: readonly DeriveCounter[] = [
+  {
+    format: "fts_format",
+    flag: "fts_reindex",
+    current: FTS_FORMAT,
+    flagsWhenUnrecorded: true,
+    // Rule "2" derives the index *and* the echo filter's set (C3), rule "3"
+    // the title index as well: a store whose counter names the current rule
+    // without one of those tables was derived by something that was not this
+    // rule — the indexes it serves and the tables that describe them would
+    // disagree, so the derivation runs again.
+    outputs: ["records_fts", "records_echo", "titles_fts"],
+  },
+  {
+    format: "embeddings_format",
+    flag: "embeddings_rederive",
+    current: EMBEDDINGS_FORMAT,
+    flagsWhenUnrecorded: false,
+    outputs: [],
+  },
+];
+
+/**
+ * The `records_fts` DDL, shared by the fresh-store DDL and the v11 rebuild so
+ * the two cannot drift. v11 adds no column, tokenizer, or option: the increment
+ * is re-deriving the index from `records` through the ingest projection, and
+ * what the cycle-8 measurements (docs/research/2026-09-13-fts-rebuild.md)
+ * support is the rebuild itself — hits identical, cost lower — not any
+ * particular internal layout.
+ */
+export const RECORDS_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS records_fts USING fts5(
+  record_id UNINDEXED,
+  session_id UNINDEXED,
+  source_type UNINDEXED,
+  record_type,
+  content,
+  tool_name,
+  tool_arguments,
+  tool_result,
+  tokenize="porter unicode61"
+)`;
+
+/**
+ * The `records` → `records_fts` projection, value for value what
+ * `insertRecordsInternal` writes at ingest time (filter.ts, "2" of the counter):
+ *
+ * - `record_id`/`session_id`/`source_type`/`record_type` come straight from the
+ *   record row, which the ingest path wrote with the session's own id and
+ *   source for native ingest; managed projections retain each record's native
+ *   source. `records` remains the projection's source of truth in both cases.
+ * - `content`, `tool_name`, and `tool_arguments` index `NULL` as `''`, exactly
+ *   as the ingest path's `?? ""` does.
+ * - `tool_result` prefers `tool_result_json` and falls back to `content` for
+ *   tool records, then to `''` — the fallback that makes a tool record
+ *   searchable by its result text when the adapter carried no result JSON.
+ *
+ * The projection itself is whole-table: the self-referential echo filter is a
+ * rule over canonical fields, so it is applied *to this projection* rather than
+ * inside it (the rebuild removes the filter's rows from the fresh index, db.ts;
+ * ingest simply never writes them). Keeping the SQL whole-table is what makes
+ * the rebuild a repair — it re-projects every record, then drops exactly the
+ * rows the rule names, so an index that drifted in either direction comes back
+ * equal to `records` minus the filter, not merely equal to a claim about it.
+ */
+export const FTS_REPOPULATE_SQL = `
+INSERT INTO records_fts (
+  record_id, session_id, source_type, record_type, content,
+  tool_name, tool_arguments, tool_result
+)
+SELECT
+  id, session_id, source_type, record_type,
+  COALESCE(content, ''),
+  COALESCE(tool_name, ''),
+  COALESCE(tool_arguments_json, ''),
+  COALESCE(tool_result_json, CASE WHEN record_type = 'tool' THEN content END, '')
+FROM records;`;
+
+/**
+ * The v10 → v11 rebuild. The index is derived — `records` is the authoritative
+ * side — so the increment discards the old table and repopulates it, never
+ * editing it in place: a rebuild also repairs an index that had drifted from
+ * `records`, which merging segments in place cannot. The DDL is unchanged, so
+ * nothing but the marker and the re-derived index distinguishes a rebuilt store
+ * on paper: the migration transaction that runs this re-applies automerge and
+ * runs the post-copy gates (db.ts) before `user_version = 11`.
+ */
+export const FTS_REBUILD_MIGRATION_SQL = `
+DROP TABLE IF EXISTS records_fts;
+${RECORDS_FTS_DDL};
+${FTS_REPOPULATE_SQL}
+`;
+
+/**
+ * The title index (format `"3"`): one row per session the store holds a title
+ * for, searched as a session-level lane of its own.
+ *
+ * Standalone rather than a column of `records_fts`, because a title is not a
+ * record: it belongs to the session, it has no record id to point at, and
+ * folding it into the record index would mean either a fake row (inventing a
+ * record that no adapter wrote) or a title indexed once per record of its
+ * session. Wake splits the same way for the same reason, `crates/wake-core/src/db.rs#L126-L130`:
+ * `titles_fts(key UNINDEXED, title)`, the key carried only to find and delete
+ * the row — a session's title is not a transcription message and has no `seq`
+ * to pair with, so it gets its own table instead of a fabricated message.
+ *
+ * `session_id` takes Wake's `key` role: UNINDEXED, present only so maintenance
+ * and joins can reach the row that belongs to one session. The tokenizer is the
+ * record index's (`porter unicode61`) and deliberately not Wake's trigram — C4
+ * is the trigram-free first pass, and the tokenizer decision is C5's
+ * (docs/research/ledger/docs/research/2026-09-16-wake-port-program.md).
+ */
+export const TITLES_FTS_DDL = `CREATE VIRTUAL TABLE IF NOT EXISTS titles_fts USING fts5(
+  session_id UNINDEXED,
+  title,
+  tokenize="porter unicode61"
+)`;
+
+/**
+ * What makes a session's title indexable: a title the store actually holds.
+ * `NULL != ''` is `NULL`, and `NULL` is not true, so this one comparison covers
+ * an absent title as well as an empty one. It is a single constant because the
+ * repopulation, the maintenance triggers, and the rebuild's parity gate must
+ * agree on the set: a gate that counts something other than what the writer
+ * indexes is a gate that cannot hold.
+ */
+export const INDEXABLE_TITLE_SQL = "title != ''";
+
+/** The `sessions` → `titles_fts` projection: value for value what the triggers maintain. */
+export const TITLES_FTS_REPOPULATE_SQL = `
+INSERT INTO titles_fts (session_id, title)
+SELECT id, title FROM sessions WHERE ${INDEXABLE_TITLE_SQL};`;
+
+/**
+ * The title index's whole re-derivation: discard and repopulate, exactly as
+ * `records_fts` is rebuilt — a rebuild is also the repair for an index that
+ * drifted from `sessions`, which deleting the one stale row would not be.
+ * The maintenance triggers live on `sessions`, so they survive this.
+ */
+export const TITLES_FTS_REBUILD_SQL = `
+DROP TABLE IF EXISTS titles_fts;
+${TITLES_FTS_DDL};
+${TITLES_FTS_REPOPULATE_SQL}
+`;
+
+/**
+ * The title index's maintenance, as triggers on `sessions` so every write point
+ * has it and none has to remember it.
+ *
+ * The index is a projection of one canonical column, so the rule keeping it
+ * equal to that column is a predicate rather than a decision — the case where a
+ * trigger is right and a call site is not. `saveSession` writes a title on all
+ * three of its paths, `appendSessionRecords` writes the row without touching
+ * the title, `promoteStagedIngest` deletes the predecessor and upserts the
+ * replacement: a trigger covers all of them, covers whatever a later cycle
+ * adds, and covers a raw connection that bypasses the helpers (foreign keys off
+ * or not) — the reason `sessions` already carries
+ * `trg_sessions_diagnostics_delete`. A deleted session's title row goes with
+ * it, which no foreign key can enforce for a virtual table.
+ *
+ * The update trigger fires only when the title actually changed (`IS NOT`, so
+ * an absent title is compared too) and re-indexes that session's one row by
+ * delete-then-insert — Wake's shape, whose `upsert_session` is the single write
+ * point for the same pair (`db.rs#L1969-L1976`: `DELETE FROM titles_fts WHERE
+ * key = ?` then an insert when the title is not empty). `commitStagedIngest`'s
+ * `INSERT … ON CONFLICT DO UPDATE` takes the update path (and this trigger)
+ * when it changes a title and the insert path when the session is new, so
+ * either arrival lands in the index exactly once. The `DELETE` matches on an
+ * UNINDEXED column, which SQLite resolves with a scan of a table holding one
+ * row per titled session (Wake measures the same scan for the same reason).
+ */
+export const TITLES_FTS_TRIGGERS_SQL = `
+CREATE TRIGGER IF NOT EXISTS trg_sessions_titles_insert
+AFTER INSERT ON sessions
+FOR EACH ROW
+WHEN NEW.title != ''
+BEGIN
+  INSERT INTO titles_fts (session_id, title) VALUES (NEW.id, NEW.title);
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_sessions_titles_update
+AFTER UPDATE OF title ON sessions
+FOR EACH ROW
+WHEN NEW.title IS NOT OLD.title
+BEGIN
+  DELETE FROM titles_fts WHERE session_id = NEW.id;
+  INSERT INTO titles_fts (session_id, title) SELECT NEW.id, NEW.title WHERE NEW.title != '';
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_sessions_titles_delete
+AFTER DELETE ON sessions
+FOR EACH ROW
+BEGIN
+  DELETE FROM titles_fts WHERE session_id = OLD.id;
+END;
+`;
+
+export const CREATE_TABLES_SQL = `
+CREATE TABLE IF NOT EXISTS source_discovery (
+  source TEXT PRIMARY KEY,
+  root_key TEXT NOT NULL,
+  cursor TEXT,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'exhausted', 'unknown')),
+  degraded INTEGER NOT NULL CHECK (degraded IN (0, 1)),
+  last_completed_at TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  content_hash_version INTEGER NOT NULL DEFAULT 1,
+  title TEXT,
+  cwd TEXT,
+  model TEXT,
+  started_at TEXT,
+  ended_at TEXT,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  parent_session_id TEXT,
+  parent_tool_use_id TEXT,
+  agent_nickname TEXT,
+  thread_role TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source);
+CREATE INDEX IF NOT EXISTS idx_sessions_content_hash ON sessions(content_hash);
+CREATE INDEX IF NOT EXISTS idx_sessions_started_at ON sessions(started_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_parent_session_id ON sessions(parent_session_id);
+
+CREATE TABLE IF NOT EXISTS records (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  source_type TEXT NOT NULL,
+  native_session_id TEXT,
+  binding_id TEXT,
+  record_type TEXT NOT NULL,
+  stable_source_record_id TEXT,
+  source_identity_kind TEXT,
+  source_order_id TEXT NOT NULL,
+  component_index INTEGER NOT NULL DEFAULT 0,
+  record_timestamp TEXT,
+  source_timestamp TEXT,
+  content TEXT,
+  tool_call_id TEXT,
+  tool_name TEXT,
+  tool_arguments_json TEXT,
+  tool_result_json TEXT,
+  tool_result_ok INTEGER,
+  record_json TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  record_hash TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_records_session_id ON records(session_id);
+CREATE INDEX IF NOT EXISTS idx_records_record_type ON records(record_type);
+CREATE INDEX IF NOT EXISTS idx_records_source_order ON records(session_id, source_order_id, component_index);
+CREATE INDEX IF NOT EXISTS idx_records_content_hash ON records(content_hash);
+
+${RECORDS_FTS_DDL};
+
+-- The title index (format "3"): a session-level lane beside the record index.
+-- Created for every store on every writer open — an older store gets the empty
+-- table and its maintenance triggers here, and the derive-rule counter's
+-- one-shot fills it on the next pass.
+${TITLES_FTS_DDL};
+
+-- The store's own bookkeeping, not user data: the derive-rule counters
+-- (DERIVE_COUNTERS) and the transient re-derivation flags a mismatch raises.
+-- Kept out of SCHEMA_VERSION on purpose — migrations may add and drop keys here
+-- freely without refusing an older build's read path (Wake keeps the same split
+-- in its own schema_meta, db.rs#L25).
+CREATE TABLE IF NOT EXISTS schema_meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS records_embeddings (
+  record_id TEXT PRIMARY KEY REFERENCES records(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  embedding BLOB NOT NULL,
+  provider TEXT,
+  dim INTEGER,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_records_embeddings_session_id ON records_embeddings(session_id);
+CREATE INDEX IF NOT EXISTS idx_records_embeddings_provider ON records_embeddings(provider, dim);
+
+-- The self-referential echo filter's derived set (filter.ts): the record ids
+-- excluded from records_fts, each with the session that owns it. Derived state
+-- on the same footing as the index — written by the same ingest decision that
+-- skips the FTS row, deleted with its record and its session through the
+-- foreign keys below, and rebuilt from the rule by the index re-derivation —
+-- never part of the records table, so canonical storage stays exactly what the
+-- adapters produced. A store written before this table keeps reading: readers
+-- never need it, and a writer creates it on open.
+CREATE TABLE IF NOT EXISTS records_echo (
+  record_id TEXT PRIMARY KEY REFERENCES records(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE
+);
+
+-- User-initiated deletion (v15): one row per session a user deleted through the
+-- explicit verb (ledger delete), and the only state the mechanism adds. These
+-- rows are canonical, not derived: a tombstone is not a projection of anything,
+-- so no rule can recompute it — it has no derive-rule counter, and the
+-- re-derivation one-shot neither reads nor writes it.
+--
+-- The Ledger session id is the primary key because that is the axis the serving
+-- path knows: every read verb resolves sessions through sessions.id, so one
+-- probe per served row hides the session, while every canonical row it owns (and
+-- every derived artifact it produced) is left exactly where it was. source and
+-- native_id are the axis a re-scan can name *before* it reads anything, which is
+-- what stops a copy of the source at another path from re-admitting the session.
+-- source_path is provenance for the audit and deliberately not an admission key:
+-- a path is not listing identity in this store — shared stores such as hermes
+-- hold many distinct listings at one path (db.ts, getLiveIngestSession) — so
+-- keying admission on it would block every other listing that shares the file.
+--
+-- Wake keeps the same pair for the same reason (crates/wake-core/src/db.rs,
+-- #L76-L80: tombstones(file_path PK, key, deleted_at); #L537-L571: the row is
+-- written in the same transaction as the removal; #L1002-L1018: both axes are
+-- probed). Ledger's axes differ because its identity does: identity.ts keys a
+-- session as source:native-id, stable across copies and content edits, while a
+-- file path is not an identity at all.
+--
+-- mode is the one rewritable column: suppress (the default) closes serving and
+-- admission and leaves every canonical row in place; hard removes the session's
+-- records, vectors, echo markers, titles, diagnostics and staged replacements in
+-- the same transaction, so the tombstone is all that is left of it. record_count
+-- and deleted_at are the deletion event's own facts and are not restamped when a
+-- suppress tombstone is escalated.
+--
+-- No derive-rule counter moves for this table — FTS_FORMAT stays "3": the
+-- records-to-records_fts projection is untouched, and a tombstone is not a rule
+-- over canonical record fields. Hiding by editing the index instead would have
+-- to be re-derived by whoever next changes the rules, and the rebuild's parity
+-- gate (records minus excluded equals indexed, db.ts) would be counting
+-- suppression state as though it were derived data.
+CREATE TABLE IF NOT EXISTS session_tombstones (
+  session_id TEXT PRIMARY KEY,
+  source TEXT NOT NULL,
+  native_id TEXT NOT NULL,
+  source_path TEXT,
+  mode TEXT NOT NULL CHECK (mode IN ('suppress', 'hard')),
+  reason TEXT NOT NULL,
+  record_count INTEGER NOT NULL,
+  deleted_at TEXT NOT NULL
+);
+
+-- The admission axis: every discovered listing probes (source, native id) once
+-- per pass, and deleted sessions accumulate, so the pair carries an index even
+-- though the table starts empty.
+CREATE INDEX IF NOT EXISTS idx_session_tombstones_native
+  ON session_tombstones(source, native_id);
+
+CREATE TABLE IF NOT EXISTS ingest_cursors (
+  source TEXT NOT NULL,
+  listing_id TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  session_id TEXT,
+  mtime TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  bytes_ingested INTEGER NOT NULL,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  file_identity TEXT,
+  prefix_hash TEXT,
+  checkpoint_version INTEGER,
+  line_count INTEGER,
+  tail_offset INTEGER,
+  tail_hash TEXT,
+  PRIMARY KEY (source, listing_id, source_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingest_cursors_session_id ON ingest_cursors(session_id);
+
+CREATE TABLE IF NOT EXISTS ingest_queue (
+  source TEXT NOT NULL,
+  listing_id TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  source_updated_at TEXT,
+  title TEXT,
+  size_bytes INTEGER,
+  native_json TEXT,
+  enqueued_at TEXT NOT NULL,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TEXT,
+  last_attempt_at TEXT,
+  last_outcome TEXT,
+  PRIMARY KEY (source, listing_id, source_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingest_queue_ready
+  ON ingest_queue(next_attempt_at, source_updated_at, enqueued_at);
+
+CREATE TABLE IF NOT EXISTS ingest_runtime_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  scale_permille INTEGER NOT NULL CHECK (scale_permille BETWEEN 250 AND 1000),
+  calm_runs INTEGER NOT NULL CHECK (calm_runs >= 0),
+  last_severity TEXT NOT NULL CHECK (last_severity IN ('unavailable', 'calm', 'constrained', 'critical')),
+  updated_at TEXT NOT NULL
+);
+
+-- Rebuild generations retain canonical records until the replacement is complete.
+-- They are not a raw source archive and are removed when promoted to the live index.
+CREATE TABLE IF NOT EXISTS ingest_staged_sessions (
+  source TEXT NOT NULL,
+  listing_id TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  replaced_session_id TEXT NOT NULL,
+  session_json TEXT NOT NULL,
+  diagnostics_json TEXT,
+  PRIMARY KEY (source, listing_id, source_path)
+);
+
+CREATE TABLE IF NOT EXISTS ingest_staged_records (
+  source TEXT NOT NULL,
+  listing_id TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  id TEXT NOT NULL,
+  record_type TEXT NOT NULL,
+  source_order_id TEXT NOT NULL,
+  component_index INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  record_hash TEXT NOT NULL,
+  canonical_json TEXT NOT NULL,
+  PRIMARY KEY (source, listing_id, source_path, id),
+  FOREIGN KEY (source, listing_id, source_path)
+    REFERENCES ingest_staged_sessions(source, listing_id, source_path) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingest_staged_records_order
+  ON ingest_staged_records(source, listing_id, source_path, source_order_id, component_index);
+
+-- Normalization diagnostics of the records currently committed for a session,
+-- aggregated to one row per code. Upstream emits one diagnostic per record, so
+-- a single corpus can carry thousands of same-code findings; rows stay bounded
+-- by (sessions x codes) instead. A publishing commit replaces its session's
+-- rows, so re-importing identical content is idempotent and codes that stop
+-- occurring disappear. Diagnostic text never carries raw transcript content.
+CREATE TABLE IF NOT EXISTS ingest_diagnostics (
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  code TEXT NOT NULL,
+  source TEXT NOT NULL,
+  occurrence_count INTEGER NOT NULL,
+  sample TEXT,
+  first_seen_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  PRIMARY KEY (session_id, code)
+);
+
+-- A session's findings describe records that are gone once the session is gone.
+-- Enforce that for every writer, including raw connections that never enable
+-- foreign keys, where the cascade above does not fire.
+CREATE TRIGGER IF NOT EXISTS trg_sessions_diagnostics_delete
+AFTER DELETE ON sessions
+FOR EACH ROW
+BEGIN
+  DELETE FROM ingest_diagnostics WHERE session_id = OLD.id;
+END;
+
+-- The title index's maintenance (format "3"): the same argument as the
+-- diagnostics trigger above — a session's title describes a session, and the
+-- index that holds it must follow every writer, not the call sites that
+-- remember to.
+${TITLES_FTS_TRIGGERS_SQL}
+-- What the last lease-holding pass saw of each source. Scan outcomes are
+-- recomputed per scan and were dropped on the floor; this table is the durable
+-- half, so the status verb reports which sources are listable without running a
+-- scan. It is state, not history: one row per source, rewritten in place by
+-- every later pass (last verdict wins, including a source that stops being
+-- listable), no TTL, no counters. first_seen_at is stamped once and survives
+-- while the source keeps being seen, so the row also carries how long the
+-- source has been covered; detail is a scan-outcome detail, capped and free
+-- of store content. status carries the scanner's closed outcome set as a CHECK,
+-- like the runtime state's severity: the set is closed upstream, so a value
+-- outside it must fail at the write instead of surfacing as an unknown status
+-- in a report. v12 adds only this table — no column, index, or migration
+-- statement beyond the DDL, because an earlier store is migrated by running
+-- this same CREATE_TABLES_SQL (db.ts, migrate).
+CREATE TABLE IF NOT EXISTS source_coverage (
+  source TEXT PRIMARY KEY,
+  root TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN (
+    'listable', 'missing_root', 'root_wrong_shape', 'unreadable_root', 'listing_failed'
+  )),
+  discovered INTEGER NOT NULL,
+  detail TEXT,
+  first_seen_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+
+/**
+ * The read contract, as (table, column) pairs. A `null` column means the pair
+ * is satisfied by the table's presence alone — these tables are queried by
+ * name, so an absent one is the gap to name.
+ *
+ * The list is derived from the read path, not from the DDL:
+ *
+ * - **What a read verb names.** `search`/`recent`/`status` join `sessions`
+ *   (including the parentage columns in the hit projection), order by
+ *   `updated_at`/`started_at`/`source_order_id`, MATCH `records_fts`, read
+ *   whole `records` rows (including `record_json`), and score
+ *   `records_embeddings` (`provider`, `dim`, `embedding`).
+ * - **What the row contracts project.** `SELECT *` into `SessionRecord` /
+ *   `CanonicalDbRecord` types every other column below.
+ *
+ * Deliberately absent: `content_hash_version`, optional record provenance
+ * (`native_session_id`, `binding_id`), the ingest tables (cursors,
+ * queue, runtime state, staging, diagnostics — `status` treats diagnostics as
+ * optional coverage), and index presence. No read verb names them, so requiring
+ * them would refuse a store the read path can serve. `records_fts` is required
+ * as a real FTS5 index (its shadow table is the witness), which is a table
+ * check, not an index check.
+ *
+ * The boundary this draws is real, and the migration-fixture test pins it: a
+ * shape written before the parentage columns existed (schema v3 and older)
+ * cannot serve `search` at all — the FTS projection names `s.parent_session_id`
+ * — so it is refused *by name* here instead of dying on a raw `no such column`.
+ * A writer open (`ledger sync`/`ledger build`) migrates it and the reads follow.
+ * `user_version < SCHEMA_VERSION` with these pairs present stays readable and
+ * keeps serving reads (`status` semantics); this gate never migrates.
+ */
+export const REQUIRED_READ_SCHEMA: readonly (readonly [table: string, column: string | null])[] = [
+  // An absent table surfaces from the column walk itself: an empty
+  // `PRAGMA table_info` probe reports the bare table name, so `records` and
+  // `records_embeddings` need no presence pair. The two column-less tables
+  // (`records_fts`, `records_fts_data`) are the ones whose presence pair is
+  // itself the check.
+  ["records", "id"],
+  ["records", "session_id"],
+  ["records", "source_type"],
+  ["records", "record_type"],
+  ["records", "stable_source_record_id"],
+  ["records", "source_identity_kind"],
+  ["records", "source_order_id"],
+  ["records", "component_index"],
+  ["records", "record_timestamp"],
+  ["records", "source_timestamp"],
+  ["records", "content"],
+  ["records", "tool_call_id"],
+  ["records", "tool_name"],
+  ["records", "tool_arguments_json"],
+  ["records", "tool_result_json"],
+  ["records", "tool_result_ok"],
+  ["records", "record_json"],
+  ["records", "content_hash"],
+  ["records", "record_hash"],
+  ["records_embeddings", "record_id"],
+  ["records_embeddings", "session_id"],
+  ["records_embeddings", "embedding"],
+  ["records_embeddings", "provider"],
+  ["records_embeddings", "dim"],
+  ["records_fts", null],
+  // The witness that `records_fts` is really the FTS5 index: only a genuine
+  // FTS5 virtual table has shadow tables, and a plain table with the same name
+  // and columns would pass every column check and then die on `MATCH`. Checked
+  // by presence rather than by matching `sqlite_master.sql` for "USING fts5".
+  ["records_fts_data", null],
+  // No presence pair for `sessions`: a file without that table is refused as a
+  // foreign store before the pair walk runs (a gap could never name it).
+  ["sessions", "id"],
+  ["sessions", "source"],
+  ["sessions", "source_path"],
+  ["sessions", "content_hash"],
+  ["sessions", "title"],
+  ["sessions", "cwd"],
+  ["sessions", "model"],
+  ["sessions", "started_at"],
+  ["sessions", "ended_at"],
+  ["sessions", "record_count"],
+  ["sessions", "created_at"],
+  ["sessions", "updated_at"],
+  ["sessions", "parent_session_id"],
+  ["sessions", "parent_tool_use_id"],
+  ["sessions", "agent_nickname"],
+  ["sessions", "thread_role"],
+];
+
+export const INGEST_DIAGNOSTICS_SQL = `
+CREATE TABLE IF NOT EXISTS ingest_diagnostics (
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  code TEXT NOT NULL,
+  source TEXT NOT NULL,
+  occurrence_count INTEGER NOT NULL,
+  sample TEXT,
+  first_seen_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  PRIMARY KEY (session_id, code)
+);
+
+CREATE TRIGGER IF NOT EXISTS trg_sessions_diagnostics_delete
+AFTER DELETE ON sessions
+FOR EACH ROW
+BEGIN
+  DELETE FROM ingest_diagnostics WHERE session_id = OLD.id;
+END;
+`;
+
+export const V4_MIGRATION_SQL = `
+-- Existing v3 rows used source-native ids as global primary keys. Prefix them
+-- deterministically with the adapter name so independent harnesses cannot
+-- overwrite one another when they reuse the same native session/record ids.
+UPDATE records_embeddings
+SET record_id = (
+      SELECT r.source_type || ':' || r.id FROM records r WHERE r.id = records_embeddings.record_id
+    ),
+    session_id = (
+      SELECT s.source || ':' || s.id FROM sessions s WHERE s.id = records_embeddings.session_id
+    );
+
+-- Session identity is always sessions.source, even when a historical FTS or
+-- record row stored a different source_type. Record ids stay prefixed by the
+-- record's own source_type so they remain stable relative to the record row.
+UPDATE records_fts
+SET record_id = source_type || ':' || record_id,
+    session_id = COALESCE(
+      (SELECT s.source || ':' || s.id FROM sessions s WHERE s.id = records_fts.session_id),
+      source_type || ':' || session_id
+    );
+
+UPDATE records
+SET id = source_type || ':' || id,
+    session_id = COALESCE(
+      (SELECT s.source || ':' || s.id FROM sessions s WHERE s.id = records.session_id),
+      source_type || ':' || session_id
+    );
+
+UPDATE sessions
+SET id = source || ':' || id;
+
+-- Older Gemini backfill used the MiniLM/384 defaults. Repair that known
+-- signature, but preserve other provider identities regardless of dimensions.
+-- Float32 blob length is authoritative for dimensionality, not provider identity.
+UPDATE records_embeddings
+SET dim = length(embedding) / 4,
+    provider = CASE
+      WHEN provider = 'all-MiniLM-L6-v2' AND dim = 384
+        AND length(embedding) / 4 = 768 THEN 'gemini-embedding-2'
+      ELSE provider
+    END;
+`;
+
+export const REPAIR_EMBEDDING_METADATA_TRIGGERS_SQL = `
+DROP TRIGGER IF EXISTS trg_records_embeddings_metadata_insert;
+DROP TRIGGER IF EXISTS trg_records_embeddings_metadata_update;
+
+CREATE TRIGGER trg_records_embeddings_metadata_insert
+AFTER INSERT ON records_embeddings
+FOR EACH ROW
+BEGIN
+  UPDATE records_embeddings
+  SET dim = length(NEW.embedding) / 4,
+      provider = CASE
+        WHEN NEW.provider IS NOT NULL AND NEW.provider != '' THEN NEW.provider
+        WHEN length(NEW.embedding) / 4 = 768 THEN 'gemini-embedding-2'
+        WHEN length(NEW.embedding) / 4 = 384 THEN 'all-MiniLM-L6-v2'
+        ELSE NEW.provider
+      END
+  WHERE record_id = NEW.record_id;
+END;
+
+CREATE TRIGGER trg_records_embeddings_metadata_update
+AFTER UPDATE OF embedding ON records_embeddings
+FOR EACH ROW
+BEGIN
+  UPDATE records_embeddings
+  SET dim = length(NEW.embedding) / 4,
+      provider = CASE
+        WHEN NEW.provider IS NOT NULL AND NEW.provider != '' THEN NEW.provider
+        WHEN length(NEW.embedding) / 4 = 768 THEN 'gemini-embedding-2'
+        WHEN length(NEW.embedding) / 4 = 384 THEN 'all-MiniLM-L6-v2'
+        ELSE NEW.provider
+      END
+  WHERE record_id = NEW.record_id;
+END;
+`;
+
+export const V3_MIGRATION_SQL = `
+ALTER TABLE records_embeddings ADD COLUMN provider TEXT;
+ALTER TABLE records_embeddings ADD COLUMN dim INTEGER;
+UPDATE records_embeddings SET provider = 'all-MiniLM-L6-v2', dim = 384 WHERE provider IS NULL;
+CREATE INDEX IF NOT EXISTS idx_records_embeddings_provider ON records_embeddings(provider, dim);
+`;
+
+export const V2_MIGRATION_SQL = `
+CREATE TABLE IF NOT EXISTS records_embeddings (
+  record_id TEXT PRIMARY KEY REFERENCES records(id) ON DELETE CASCADE,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  embedding BLOB NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_records_embeddings_session_id ON records_embeddings(session_id);
+`;
+
+export const PARENTAGE_MIGRATION_SQL = `
+ALTER TABLE sessions ADD COLUMN parent_session_id TEXT;
+ALTER TABLE sessions ADD COLUMN parent_tool_use_id TEXT;
+ALTER TABLE sessions ADD COLUMN agent_nickname TEXT;
+ALTER TABLE sessions ADD COLUMN thread_role TEXT;
+CREATE INDEX IF NOT EXISTS idx_sessions_parent_session_id ON sessions(parent_session_id);
+`;
+
+export const INGEST_CURSORS_SQL = `
+CREATE TABLE IF NOT EXISTS ingest_cursors (
+  source TEXT NOT NULL,
+  listing_id TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  session_id TEXT,
+  mtime TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  bytes_ingested INTEGER NOT NULL,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  file_identity TEXT,
+  prefix_hash TEXT,
+  checkpoint_version INTEGER,
+  line_count INTEGER,
+  tail_offset INTEGER,
+  tail_hash TEXT,
+  PRIMARY KEY (source, listing_id, source_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingest_cursors_session_id ON ingest_cursors(session_id);
+`;