mirror-mind 0.0.1 → 0.33.0

package/ts/src/db/schema.ts

@@ -0,0 +1,432 @@
+// Fresh-database schema DDL — the TS core's first slice of schema custody
+// (CV22.DS6.TS1).
+//
+// This is a structural port of Python's `SCHEMA`
+// (`src/memory/db/schema.py`), comments rewritten to English per CV0. Every
+// `CREATE TABLE`/`CREATE INDEX`/`CREATE VIRTUAL TABLE`/`CREATE TRIGGER`
+// statement here must stay a faithful structural match of the Python source:
+// same tables, columns, types, defaults, primary keys, foreign keys, indexes
+// (including partial predicates), CHECK constraints, and the `memories_fts`
+// FTS5 external-content configuration and its shadow triggers.
+// `ts/src/db/schema.test.ts` proves this structurally (not textually — see
+// `schemaInventory.ts`) against a snapshot committed from the Python side.
+//
+// Scope boundary: this module owns DDL only. It does NOT run migrations or
+// seed `_migrations` bookkeeping (CV22.DS6.TS2). Its two callers compose it
+// AFTER `runMigrations`, the order Python's `get_connection` used on every
+// open: `bootstrapDatabase` for a new file, and migrate-on-open's slow path
+// for an existing one (CV22.DS10.TS5 handoff review, B1). That is how a
+// database older than an object only this DDL creates, such as
+// `_ext_bindings`, still gets it. `createSchema` is safe to call against an
+// already-populated database (every statement is `IF NOT EXISTS`) and safe to
+// call twice.
+//
+// The `identity` table's `layer`/`key` enumeration comments are preserved
+// verbatim from the Python source (translated word-for-word, not paraphrased)
+// — they are the de facto documentation of the identity taxonomy that prompt
+// composition depends on.
+
+import type { WritableDatabase } from "./database.ts";
+
+export const SCHEMA = `
+CREATE TABLE IF NOT EXISTS conversations (
+    id TEXT PRIMARY KEY,
+    title TEXT,
+    started_at TEXT NOT NULL,
+    ended_at TEXT,
+    interface TEXT NOT NULL,
+    persona TEXT,
+    journey TEXT,
+    summary TEXT,
+    tags TEXT,
+    metadata TEXT
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+    id TEXT PRIMARY KEY,
+    conversation_id TEXT NOT NULL REFERENCES conversations(id),
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    token_count INTEGER,
+    metadata TEXT
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+    id TEXT PRIMARY KEY,
+    conversation_id TEXT REFERENCES conversations(id),
+    memory_type TEXT NOT NULL,
+    layer TEXT NOT NULL DEFAULT 'ego',
+    title TEXT NOT NULL,
+    content TEXT NOT NULL,
+    context TEXT,
+    journey TEXT,
+    persona TEXT,
+    tags TEXT,
+    created_at TEXT NOT NULL,
+    relevance_score REAL DEFAULT 1.0,
+    embedding BLOB,
+    metadata TEXT,
+    last_accessed_at TEXT,
+    use_count INTEGER NOT NULL DEFAULT 0,
+    readiness_state TEXT NOT NULL DEFAULT 'observed'
+);
+
+CREATE TABLE IF NOT EXISTS conversation_embeddings (
+    conversation_id TEXT PRIMARY KEY REFERENCES conversations(id),
+    summary_embedding BLOB
+);
+
+CREATE TABLE IF NOT EXISTS runtime_sessions (
+    session_id TEXT PRIMARY KEY,
+    conversation_id TEXT REFERENCES conversations(id),
+    interface TEXT,
+    mirror_active INTEGER NOT NULL DEFAULT 0,
+    persona TEXT,
+    journey TEXT,
+    hook_injected INTEGER NOT NULL DEFAULT 0,
+    active INTEGER NOT NULL DEFAULT 1,
+    started_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    closed_at TEXT,
+    metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_runtime_sessions_conversation ON runtime_sessions(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_runtime_sessions_active ON runtime_sessions(active);
+
+CREATE TABLE IF NOT EXISTS builder_refinement_stories (
+    id TEXT PRIMARY KEY,
+    journey TEXT NOT NULL,
+    display_code TEXT NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT,
+    status TEXT NOT NULL DEFAULT 'draft',
+    position INTEGER NOT NULL DEFAULT 0,
+    source TEXT NOT NULL DEFAULT 'manual',
+    provenance TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    pulled_at TEXT,
+    closed_at TEXT,
+    CHECK(status IN ('draft', 'open', 'active', 'closed', 'parked'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_builder_refinement_stories_journey_status
+    ON builder_refinement_stories(journey, status, position, updated_at);
+CREATE UNIQUE INDEX IF NOT EXISTS ux_builder_refinement_stories_journey_display_code
+    ON builder_refinement_stories(journey, display_code);
+
+CREATE TABLE IF NOT EXISTS builder_change_requests (
+    id TEXT PRIMARY KEY,
+    journey TEXT NOT NULL,
+    display_code TEXT NOT NULL,
+    refinement_story_id TEXT REFERENCES builder_refinement_stories(id),
+    title TEXT NOT NULL,
+    body TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'captured',
+    position INTEGER NOT NULL DEFAULT 0,
+    source TEXT NOT NULL DEFAULT 'manual',
+    provenance TEXT,
+    outcome_notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    completed_at TEXT,
+    CHECK(status IN (
+        'captured', 'planned', 'active', 'implemented', 'validated',
+        'done', 'parked', 'rejected', 'promoted'
+    ))
+);
+
+CREATE INDEX IF NOT EXISTS idx_builder_change_requests_story_status
+    ON builder_change_requests(journey, refinement_story_id, status, position, updated_at);
+CREATE INDEX IF NOT EXISTS idx_builder_change_requests_journey_status
+    ON builder_change_requests(journey, status, updated_at);
+CREATE UNIQUE INDEX IF NOT EXISTS ux_builder_change_requests_journey_display_code
+    ON builder_change_requests(journey, display_code);
+
+CREATE TABLE IF NOT EXISTS builder_refinement_cursors (
+    journey TEXT PRIMARY KEY,
+    active_refinement_story_id TEXT REFERENCES builder_refinement_stories(id),
+    active_change_request_id TEXT REFERENCES builder_change_requests(id),
+    last_refinement_event TEXT,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS memory_access_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    memory_id TEXT NOT NULL REFERENCES memories(id),
+    accessed_at TEXT NOT NULL,
+    access_context TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_conversation ON messages(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(memory_type);
+CREATE INDEX IF NOT EXISTS idx_memories_layer ON memories(layer);
+CREATE INDEX IF NOT EXISTS idx_memories_journey ON memories(journey);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+CREATE INDEX IF NOT EXISTS idx_access_log_memory ON memory_access_log(memory_id);
+
+-- Column order intentionally does NOT match src/memory/db/schema.py's literal
+-- text. On a real fresh Python database, migrations run before SCHEMA:
+-- migration 003_create_tasks creates this table without scheduled_at/time_hint,
+-- then 004_tasks_temporal_fields ALTER TABLE ADD COLUMNs them afterward, which
+-- always appends at the end regardless of where they appear in schema.py's
+-- aspirational inline text (SCHEMA's own CREATE TABLE IF NOT EXISTS never
+-- fires for tasks in practice, since migrations already created it). This
+-- order matches the true output of Python's actual bootstrap path, proven by
+-- CV22.DS6.TS1's structural-parity test against a real fresh Python database.
+CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    journey TEXT,
+    title TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'todo',
+    due_date TEXT,
+    stage TEXT,
+    context TEXT,
+    source TEXT NOT NULL DEFAULT 'manual',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    completed_at TEXT,
+    metadata TEXT,
+    scheduled_at TEXT,
+    time_hint TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_tasks_journey ON tasks(journey);
+CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_due_date ON tasks(due_date);
+
+CREATE TABLE IF NOT EXISTS identity (
+    id TEXT PRIMARY KEY,
+    layer TEXT NOT NULL,              -- 'self', 'ego', 'user', 'organization', 'persona', 'journey', 'journey_path'
+    key TEXT NOT NULL,                -- 'soul', 'behavior', 'identity', 'principles', or persona_id
+    content TEXT NOT NULL,            -- prompt content (markdown/text)
+    version TEXT DEFAULT '1.0.0',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    metadata TEXT,
+    parent_journey TEXT,             -- journey hierarchy, first-class (CV22.DS6.US2); mirrored in metadata JSON during the transition
+    UNIQUE(layer, key)
+);
+CREATE INDEX IF NOT EXISTS idx_identity_parent_journey ON identity(parent_journey) WHERE parent_journey IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS journey_mutation_receipts (
+    request_id TEXT PRIMARY KEY,
+    request_digest TEXT NOT NULL,
+    source_version TEXT NOT NULL,
+    result_version TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    journey_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS identity_integrations (
+    id TEXT PRIMARY KEY,
+    layer TEXT NOT NULL,
+    key TEXT NOT NULL,
+    content TEXT NOT NULL,
+    source TEXT NOT NULL DEFAULT 'soul_mode',
+    origin TEXT,
+    conversation_id TEXT REFERENCES conversations(id),
+    journal_id TEXT REFERENCES memories(id),
+    created_at TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'active',
+    metadata TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_identity_integrations_target
+    ON identity_integrations(layer, key, created_at);
+CREATE INDEX IF NOT EXISTS idx_identity_integrations_status
+    ON identity_integrations(status);
+
+CREATE TABLE IF NOT EXISTS attachments (
+    id TEXT PRIMARY KEY,
+    journey_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    content TEXT NOT NULL,
+    content_type TEXT NOT NULL DEFAULT 'markdown',
+    tags TEXT,
+    embedding BLOB,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_attachments_journey ON attachments(journey_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_attachments_journey_name ON attachments(journey_id, name);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    title,
+    content,
+    context,
+    content=memories,
+    content_rowid=rowid
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_fts_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, title, content, context)
+    VALUES (NEW.rowid, NEW.title, NEW.content, COALESCE(NEW.context, ''));
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_fts_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, title, content, context)
+    VALUES ('delete', OLD.rowid, OLD.title, OLD.content, COALESCE(OLD.context, ''));
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_fts_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, title, content, context)
+    VALUES ('delete', OLD.rowid, OLD.title, OLD.content, COALESCE(OLD.context, ''));
+    INSERT INTO memories_fts(rowid, title, content, context)
+    VALUES (NEW.rowid, NEW.title, NEW.content, COALESCE(NEW.context, ''));
+END;
+
+CREATE TABLE IF NOT EXISTS identity_descriptors (
+    layer        TEXT NOT NULL,
+    key          TEXT NOT NULL,
+    descriptor   TEXT NOT NULL,
+    generated_at TEXT NOT NULL,
+    PRIMARY KEY (layer, key)
+);
+
+CREATE TABLE IF NOT EXISTS consolidations (
+    id TEXT PRIMARY KEY,
+    action TEXT NOT NULL,            -- 'merge' | 'identity_update' | 'shadow_candidate'
+    proposal TEXT NOT NULL,          -- LLM-generated proposal (full markdown text)
+    result TEXT,                     -- content actually written (accepted as-is or user-edited)
+    source_memory_ids TEXT NOT NULL, -- JSON array of Memory.id values
+    target_layer TEXT,               -- 'ego', 'self', 'shadow' (for identity_update)
+    target_key TEXT,                 -- 'behavior', 'soul', etc. (for identity_update)
+    rationale TEXT,                  -- one-sentence LLM rationale for the chosen action
+    status TEXT NOT NULL DEFAULT 'pending', -- 'pending' | 'accepted' | 'rejected'
+    created_at TEXT NOT NULL,
+    reviewed_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_consolidations_status ON consolidations(status);
+CREATE INDEX IF NOT EXISTS idx_consolidations_created ON consolidations(created_at);
+
+CREATE TABLE IF NOT EXISTS llm_calls (
+    id TEXT PRIMARY KEY,
+    role TEXT NOT NULL,
+    model TEXT NOT NULL,
+    prompt TEXT NOT NULL,
+    response TEXT NOT NULL,
+    prompt_tokens INTEGER,
+    completion_tokens INTEGER,
+    latency_ms INTEGER,
+    cost_usd REAL,
+    conversation_id TEXT REFERENCES conversations(id),
+    session_id TEXT,
+    called_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_llm_calls_conversation ON llm_calls(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_llm_calls_role ON llm_calls(role);
+CREATE INDEX IF NOT EXISTS idx_llm_calls_called_at ON llm_calls(called_at);
+
+CREATE TABLE IF NOT EXISTS operation_runs (
+    id TEXT PRIMARY KEY,
+    operation_id TEXT NOT NULL,
+    status TEXT NOT NULL,
+    outcome TEXT,
+    parameters_json TEXT NOT NULL,
+    summary_json TEXT,
+    result_json TEXT,
+    error TEXT,
+    started_at TEXT NOT NULL,
+    completed_at TEXT,
+    created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_operation_runs_operation ON operation_runs(operation_id);
+CREATE INDEX IF NOT EXISTS idx_operation_runs_started ON operation_runs(started_at);
+CREATE INDEX IF NOT EXISTS idx_operation_runs_status ON operation_runs(status);
+
+CREATE TABLE IF NOT EXISTS operation_run_events (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL REFERENCES operation_runs(id) ON DELETE CASCADE,
+    sequence INTEGER NOT NULL,
+    kind TEXT NOT NULL,
+    message TEXT NOT NULL,
+    details_json TEXT,
+    created_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_operation_run_events_run
+    ON operation_run_events(run_id, sequence);
+
+CREATE TABLE IF NOT EXISTS exploratory_stories (
+    id TEXT PRIMARY KEY,
+    journey TEXT NOT NULL,
+    title TEXT,
+    status TEXT NOT NULL DEFAULT 'active',
+    current_story TEXT,
+    narrative_summary TEXT,
+    last_story_card TEXT,
+    attractors_json TEXT,
+    experiment_proposal_json TEXT,
+    builder_handoff_json TEXT,
+    source_conversations_json TEXT,
+    artifact_dir TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    promoted_at TEXT,
+    archived_at TEXT,
+    CHECK(status IN ('active', 'archived', 'promoted'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_exploratory_stories_journey
+    ON exploratory_stories(journey, updated_at);
+CREATE INDEX IF NOT EXISTS idx_exploratory_stories_status
+    ON exploratory_stories(status);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_exploratory_stories_one_active_per_journey
+    ON exploratory_stories(journey)
+    WHERE status = 'active';
+
+-- Extension subsystem bookkeeping.
+--
+-- _ext_migrations tracks which SQL migration files have been applied per
+-- extension. The checksum guards against in-place edits to an applied
+-- migration: the runner refuses to skip or replay a file whose contents
+-- changed since it was first applied.
+--
+-- _ext_bindings maps an extension's capabilities to integration targets
+-- (typically a persona). The Mirror Mode context dispatcher reads this
+-- table after persona resolution to decide which extension providers to
+-- invoke. See docs/product/extensions/binding-model.md.
+CREATE TABLE IF NOT EXISTS _ext_migrations (
+    extension_id TEXT NOT NULL,
+    filename     TEXT NOT NULL,
+    checksum     TEXT NOT NULL,
+    applied_at   TEXT NOT NULL,
+    PRIMARY KEY (extension_id, filename)
+);
+
+CREATE TABLE IF NOT EXISTS _ext_bindings (
+    extension_id  TEXT NOT NULL,
+    capability_id TEXT NOT NULL,
+    target_kind   TEXT NOT NULL,    -- 'persona' | 'journey' | 'global'
+    target_id     TEXT,             -- NULL only when target_kind = 'global'
+    created_at    TEXT NOT NULL,
+    PRIMARY KEY (extension_id, capability_id, target_kind, target_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_ext_bindings_target
+    ON _ext_bindings(target_kind, target_id);
+`;
+
+/**
+ * Create the fresh-database schema on `db`. Idempotent — every statement is
+ * `IF NOT EXISTS` — so calling this against an already-populated database is
+ * a safe no-op that leaves existing data untouched, and calling it twice in a
+ * row is not an error.
+ *
+ * Scope: DDL only. Does not run migrations, does not seed `_migrations`
+ * bookkeeping (CV22.DS6.TS2), does not apply locking or connection pragmas
+ * (CV22.DS6.TS3) — see the module comment.
+ */
+export function createSchema(db: WritableDatabase): void {
+  db.exec(SCHEMA);
+}

package/ts/src/db/schemaInventory.ts

@@ -0,0 +1,225 @@
+// Canonical, cross-language schema inventory for the TS custody-transfer
+// contract (CV22.DS6.TS1).
+//
+// Independent TypeScript implementation of `src/memory/db/schema_inventory.py`
+// — see that module's docstring for the full contract: why parity is proven
+// structurally (not by comparing raw `sqlite_master.sql` text, since CV0
+// rewrites DDL comments to English while the frozen Python DDL keeps its
+// historical mixed-language comments), and why FTS5-internal shadow tables
+// (`<virtual-table>_data`/`_idx`/`_docsize`/`_config`/`_content`) are excluded
+// (their internal shape is a SQLite-library-version implementation detail,
+// not part of our DDL contract).
+//
+// The two implementations must produce byte-identical canonical output for
+// equivalent schemas: `schemaInventorySnapshot.ts` is a snapshot committed
+// from the Python side, and `schema.test.ts` asserts a TS-created database's
+// inventory (via this module) equals it.
+
+import type { Database } from "./database.ts";
+
+export interface ColumnInventory {
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+}
+
+export interface ForeignKeyInventory {
+  table: string;
+  from: string;
+  to: string;
+  on_update: string;
+  on_delete: string;
+  match: string;
+}
+
+export interface TableInventory {
+  columns: ColumnInventory[];
+  foreign_keys: ForeignKeyInventory[];
+  sql: string | null;
+}
+
+export interface IndexInventory {
+  table: string;
+  unique: number;
+  columns: string[];
+  sql: string | null;
+}
+
+export interface TriggerInventory {
+  table: string;
+  sql: string | null;
+}
+
+export interface SchemaInventory {
+  tables: Record<string, TableInventory>;
+  indexes: Record<string, IndexInventory>;
+  triggers: Record<string, TriggerInventory>;
+}
+
+// Tables that are custody-transfer scope boundaries, not part of the TS1 DDL
+// contract:
+//   - `_migrations`: bookkeeping for the migration engine (CV22.DS6.TS2). A
+//     fresh Python database has it (via `run_migrations`); a TS1
+//     `createSchema()` fresh database intentionally does not yet.
+//   - `sqlite_sequence`: SQLite's own AUTOINCREMENT bookkeeping table.
+const EXCLUDED_TABLES = new Set(["_migrations", "sqlite_sequence"]);
+
+const FTS_SHADOW_SUFFIXES = ["_data", "_idx", "_docsize", "_config", "_content"];
+
+/**
+ * Strip SQL comments and collapse whitespace, preserving string literals.
+ * Also strips whitespace immediately before `,`/`)` — the shape SQLite's own
+ * `ALTER TABLE ADD COLUMN` produces when it textually splices a new column
+ * definition into a table's stored `CREATE TABLE` text. Must stay
+ * behaviorally identical to `memory.db.schema_inventory.normalize_sql`
+ * (Python) — keep the two in lockstep.
+ */
+export function normalizeSql(sql: string | null): string | null {
+  if (sql === null) return null;
+  const out: string[] = [];
+  let inString = false;
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const ch = sql[i];
+    if (inString) {
+      out.push(ch);
+      if (ch === "'") {
+        if (i + 1 < n && sql[i + 1] === "'") {
+          out.push(sql[i + 1] as string);
+          i += 2;
+          continue;
+        }
+        inString = false;
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === "'") {
+      inString = true;
+      out.push(ch);
+      i += 1;
+      continue;
+    }
+    if (ch === "-" && i + 1 < n && sql[i + 1] === "-") {
+      const newline = sql.indexOf("\n", i);
+      i = newline === -1 ? n : newline;
+      continue;
+    }
+    if (ch === "/" && i + 1 < n && sql[i + 1] === "*") {
+      const end = sql.indexOf("*/", i + 2);
+      i = end === -1 ? n : end + 2;
+      continue;
+    }
+    out.push(ch as string);
+    i += 1;
+  }
+  const collapsed = out.join("").replace(/\s+/g, " ").trim();
+  return collapsed.replace(/\s+([,)])/g, "$1");
+}
+
+interface SqliteMasterRow {
+  type: string;
+  name: string;
+  tbl_name: string;
+  sql: string | null;
+}
+
+function virtualTableNames(objects: readonly SqliteMasterRow[]): Set<string> {
+  return new Set(
+    objects
+      .filter((row) => row.type === "table" && (row.sql ?? "").startsWith("CREATE VIRTUAL TABLE"))
+      .map((row) => row.name),
+  );
+}
+
+function isFtsShadowTable(name: string, virtualTables: ReadonlySet<string>): boolean {
+  for (const vt of virtualTables) {
+    for (const suffix of FTS_SHADOW_SUFFIXES) {
+      if (name === `${vt}${suffix}`) return true;
+    }
+  }
+  return false;
+}
+
+function tableInventory(db: Database, name: string, sql: string | null): TableInventory {
+  const columns = (
+    db.prepare(`PRAGMA table_info("${name}")`).all() as Record<string, unknown>[]
+  ).map((row) => ({
+    name: row.name as string,
+    type: row.type as string,
+    notnull: row.notnull as number,
+    dflt_value: (row.dflt_value as string | null) ?? null,
+    pk: row.pk as number,
+  }));
+  const foreignKeys = (
+    db.prepare(`PRAGMA foreign_key_list("${name}")`).all() as Record<string, unknown>[]
+  )
+    .map(
+      (row): ForeignKeyInventory => ({
+        table: row.table as string,
+        from: row.from as string,
+        to: row.to as string,
+        on_update: row.on_update as string,
+        on_delete: row.on_delete as string,
+        match: row.match as string,
+      }),
+    )
+    .sort((a, b) =>
+      a.table === b.table ? a.from.localeCompare(b.from) : a.table.localeCompare(b.table),
+    );
+  return { columns, foreign_keys: foreignKeys, sql: normalizeSql(sql) };
+}
+
+function indexInventory(
+  db: Database,
+  name: string,
+  table: string,
+  sql: string | null,
+): IndexInventory {
+  const columns = (
+    db.prepare(`PRAGMA index_info("${name}")`).all() as Record<string, unknown>[]
+  ).map((row) => row.name as string);
+  const listRows = db.prepare(`PRAGMA index_list("${table}")`).all() as Record<string, unknown>[];
+  const listRow = listRows.find((row) => row.name === name);
+  const unique = listRow ? Number(listRow.unique) : 0;
+  return { table, unique, columns, sql: normalizeSql(sql) };
+}
+
+/**
+ * Build the canonical, cross-language schema inventory for `db`. See the
+ * module comment (and the Python counterpart) for what is included/excluded
+ * and why.
+ */
+export function buildSchemaInventory(db: Database): SchemaInventory {
+  const objects = db
+    .prepare(
+      "SELECT type, name, tbl_name, sql FROM sqlite_master WHERE type IN ('table', 'index', 'trigger')",
+    )
+    .all() as unknown as SqliteMasterRow[];
+  const virtualTables = virtualTableNames(objects);
+
+  const tables: Record<string, TableInventory> = {};
+  const indexes: Record<string, IndexInventory> = {};
+  const triggers: Record<string, TriggerInventory> = {};
+
+  for (const row of objects) {
+    // An index or trigger belonging to an excluded table (e.g. the autoindex
+    // SQLite creates for `_migrations`' non-INTEGER PRIMARY KEY) must not
+    // dangle in the inventory once its owning table is excluded.
+    if (EXCLUDED_TABLES.has(row.tbl_name)) continue;
+    if (row.type === "table") {
+      if (EXCLUDED_TABLES.has(row.name) || row.name.startsWith("sqlite_")) continue;
+      if (isFtsShadowTable(row.name, virtualTables)) continue;
+      tables[row.name] = tableInventory(db, row.name, row.sql);
+    } else if (row.type === "index") {
+      indexes[row.name] = indexInventory(db, row.name, row.tbl_name, row.sql);
+    } else if (row.type === "trigger") {
+      triggers[row.name] = { table: row.tbl_name, sql: normalizeSql(row.sql) };
+    }
+  }
+
+  return { tables, indexes, triggers };
+}