@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/lib/core/migrations/phase-109-nodes-provenance.cjs

@@ -0,0 +1,400 @@
+'use strict';
+/**
+ * Phase 109 nodes-table provenance migration.
+ *
+ * Implements PROVENANCE.md (Plan 108-02) 6 plus 3 fields contract.
+ * Implements TRUTH-STATES.md (Plan 108-03) status_aliases backfill.
+ * Idempotent via identity.key = 'phase_109_migration_v1' sentinel row.
+ *
+ * BEGIN/COMMIT/ROLLBACK transaction wrapper per Phase 87-06 invariant
+ * (node:sqlite has no transaction(fn) higher-order helper).
+ *
+ * Canon Part 8 invariants:
+ *   - Writes only to room.db.
+ *   - Zero Brain queries.
+ *   - Zero remote egress.
+ *   - Sentinel row identity.phase_109_migration_v1 is local-only.
+ *
+ * Migration shape:
+ *   Step 1. ALTER TABLE nodes ADD COLUMN x9 (each duplicate-resilient).
+ *   Step 1. Backfill from properties JSON via json_extract.
+ *   Step 1. status_aliases assumptions backfill to graph nodes.
+ *   Step 1. state_alias_migration memory_event log per migrated row.
+ *   Step 2. Re-create-table-with-NOT-NULL plus CHECK constraints
+ *           (canonical SQLite 12-step recipe) plus 6 new indices.
+ *   Insert sentinel row.
+ *
+ * Exports:
+ *   runMigration(db) -> { applied, sentinelInserted, backfilledAssumptions }
+ *   SENTINEL_KEY (string)
+ */
+
+const SENTINEL_KEY = 'phase_109_migration_v1';
+
+// New columns added to the legacy 3-column nodes table.
+// Order matters: the re-create-table SELECT in tightenSchema relies on this list
+// matching the destination schema column order.
+const NEW_COLUMNS = [
+  // [colName, ALTER TABLE clause]
+  ['source_path', 'TEXT'],
+  ['created_by', 'TEXT'],
+  ['confidence', 'REAL'],
+  ['review_status', "TEXT DEFAULT 'proposed'"],
+  ['created_at', 'INTEGER'],
+  ['last_seen_at', 'INTEGER'],
+  ['source_section', 'TEXT'],
+  ['confirmed_by', 'TEXT'],
+  ['confirmed_at', 'INTEGER'],
+];
+
+// ----- Helpers -----
+
+function tableExists(db, name) {
+  const row = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name=?"
+  ).get(name);
+  return Boolean(row);
+}
+
+function identityHasUpdatedAt(db) {
+  // Existing identity tables (Phase 84-02 memory-ops.cjs:24-29) have 3 columns
+  // including updated_at TEXT NOT NULL. The Phase 108 PROVENANCE.md contract
+  // assumed 2 columns. Detect at runtime so the sentinel insert builds the
+  // correct INSERT statement.
+  const cols = db.prepare("PRAGMA table_info(identity)").all().map((c) => c.name);
+  return cols.includes('updated_at');
+}
+
+function sentinelPresent(db) {
+  if (!tableExists(db, 'identity')) return false;
+  try {
+    const row = db.prepare('SELECT value FROM identity WHERE key = ?').get(SENTINEL_KEY);
+    return Boolean(row && row.value);
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureIdentityTable(db) {
+  // Create identity table compatible with both the 3-column memory-ops shape
+  // (Phase 84-02) and the 2-column PROVENANCE.md spec. We default to the
+  // 3-column shape because that is what real rooms ship with; openRoomDb
+  // composition runs initMemorySchema before this migration so the table
+  // already exists in the canonical 3-column form by the time runMigration
+  // is invoked from production. The CREATE IF NOT EXISTS only fires for
+  // hermetic test fixtures that build identity manually.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS identity (" +
+    "key TEXT PRIMARY KEY, " +
+    "value TEXT NOT NULL, " +
+    "updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP" +
+    ")"
+  );
+}
+
+function addColumnsIdempotent(db) {
+  // PRAGMA table_info gives us existing column names; skip ALTER for any
+  // already present (safe against partial migrations or parallel races).
+  const existing = new Set(db.prepare('PRAGMA table_info(nodes)').all().map((c) => c.name));
+  for (const [col, clause] of NEW_COLUMNS) {
+    if (existing.has(col)) continue;
+    try {
+      db.exec('ALTER TABLE nodes ADD COLUMN ' + col + ' ' + clause);
+    } catch (err) {
+      // Treat duplicate-column as no-op (parallel migration may have raced).
+      if (!/duplicate column name/i.test(err.message)) throw err;
+    }
+  }
+}
+
+function backfillFromProperties(db) {
+  // source_path: prefer properties.source_path, then properties.source_artifact,
+  // then id for Artifact / Section nodes.
+  db.exec(
+    "UPDATE nodes SET source_path = json_extract(properties, '$.source_path') " +
+    "WHERE source_path IS NULL " +
+    "AND json_extract(properties, '$.source_path') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET source_path = json_extract(properties, '$.source_artifact') " +
+    "WHERE source_path IS NULL " +
+    "AND json_extract(properties, '$.source_artifact') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET source_path = id " +
+    "WHERE source_path IS NULL AND type IN ('Artifact', 'Section')"
+  );
+  // Last-resort source_path fallback so the NOT NULL Step 2 constraint is
+  // satisfiable for every legacy row. PROVENANCE.md L125 mandates "sensible
+  // defaults" when JSON fields are missing; we synthesize a path-like handle
+  // from the node id so provenance is at minimum self-referential.
+  db.exec(
+    "UPDATE nodes SET source_path = 'unknown:' || id WHERE source_path IS NULL"
+  );
+
+  // created_at: epoch ms from properties.created (ISO string) or fall back to now.
+  db.exec(
+    "UPDATE nodes SET created_at = CAST(strftime('%s', json_extract(properties, '$.created')) AS INTEGER) * 1000 " +
+    "WHERE created_at IS NULL AND json_extract(properties, '$.created') IS NOT NULL"
+  );
+  db.exec(
+    "UPDATE nodes SET created_at = CAST(strftime('%s', 'now') AS INTEGER) * 1000 WHERE created_at IS NULL"
+  );
+
+  // last_seen_at: same as created_at on first migration (drives stale-marker job later).
+  db.exec('UPDATE nodes SET last_seen_at = created_at WHERE last_seen_at IS NULL');
+
+  // confidence: string enum to REAL; preserve existing REAL / INTEGER values.
+  db.exec(
+    "UPDATE nodes SET confidence = CASE " +
+    "WHEN typeof(json_extract(properties, '$.confidence')) = 'real' THEN json_extract(properties, '$.confidence') " +
+    "WHEN typeof(json_extract(properties, '$.confidence')) = 'integer' THEN json_extract(properties, '$.confidence') " +
+    "WHEN json_extract(properties, '$.confidence') = 'high' THEN 0.8 " +
+    "WHEN json_extract(properties, '$.confidence') = 'medium' THEN 0.5 " +
+    "WHEN json_extract(properties, '$.confidence') = 'low' THEN 0.3 " +
+    "ELSE NULL END " +
+    "WHERE confidence IS NULL"
+  );
+
+  // created_by + review_status defaults for legacy rows.
+  db.exec("UPDATE nodes SET created_by = 'system' WHERE created_by IS NULL");
+  db.exec("UPDATE nodes SET review_status = 'proposed' WHERE review_status IS NULL");
+
+  // source_section from properties.section.
+  db.exec(
+    "UPDATE nodes SET source_section = json_extract(properties, '$.section') " +
+    "WHERE source_section IS NULL AND json_extract(properties, '$.section') IS NOT NULL"
+  );
+
+  // source_section fallback: section nodes use their own id.
+  db.exec(
+    "UPDATE nodes SET source_section = id " +
+    "WHERE source_section IS NULL AND type = 'section'"
+  );
+}
+
+function backfillAssumptionsAsGraphNodes(db) {
+  if (!tableExists(db, 'assumptions')) return 0;
+
+  // Promote each assumptions row to a graph node via status_aliases mapping.
+  // assumptions.id is INTEGER per memory-ops.cjs:65 so we cast to TEXT for the
+  // node id construction. INSERT OR IGNORE makes the operation idempotent if
+  // the migration is re-run somehow (defense in depth on top of sentinel).
+  const insertNodes = db.prepare(
+    "INSERT OR IGNORE INTO nodes " +
+    "(id, type, properties, source_path, created_by, confidence, " +
+    " review_status, created_at, last_seen_at, source_section) " +
+    "SELECT " +
+    "  'assumption:' || CAST(a.id AS TEXT), " +
+    "  'assumption', " +
+    "  json_object(" +
+    "    'claim', a.claim, " +
+    "    'evidence_for', a.evidence_for, " +
+    "    'evidence_against', a.evidence_against, " +
+    "    'legacy_validity', a.validity" +
+    "  ), " +
+    "  COALESCE(a.section, 'unknown'), " +
+    "  'system', " +
+    "  NULL, " +
+    "  CASE a.validity " +
+    "    WHEN 'untested' THEN 'proposed' " +
+    "    WHEN 'supported' THEN 'validated' " +
+    "    WHEN 'contradicted' THEN 'invalidated' " +
+    "    WHEN 'stale' THEN 'stale' " +
+    "  END, " +
+    "  CAST(strftime('%s', a.created_at) AS INTEGER) * 1000, " +
+    "  CAST(strftime('%s', COALESCE(a.last_tested, a.created_at)) AS INTEGER) * 1000, " +
+    "  a.section " +
+    "FROM assumptions a"
+  );
+  insertNodes.run();
+
+  // Log one state_alias_migration memory_event per assumption row.
+  // Phase 108 TRUTH-STATES.md L68 mandates one event per migrated row.
+  const nowMs = Date.now();
+  const insertEvents = db.prepare(
+    "INSERT OR IGNORE INTO nodes " +
+    "(id, type, properties, source_path, created_by, confidence, " +
+    " review_status, created_at, last_seen_at) " +
+    "SELECT " +
+    "  'memory_event:state_alias_migration:' || CAST(a.id AS TEXT), " +
+    "  'memory_event', " +
+    "  json_object(" +
+    "    'event_type', 'state_alias_migration', " +
+    "    'target_node_id', 'assumption:' || CAST(a.id AS TEXT), " +
+    "    'from_validity', a.validity, " +
+    "    'to_review_status', CASE a.validity " +
+    "      WHEN 'untested' THEN 'proposed' " +
+    "      WHEN 'supported' THEN 'validated' " +
+    "      WHEN 'contradicted' THEN 'invalidated' " +
+    "      WHEN 'stale' THEN 'stale' " +
+    "    END" +
+    "  ), " +
+    "  'phase-109-migration', " +
+    "  'system', " +
+    "  NULL, " +
+    "  'confirmed', " +
+    "  ?, ? " +
+    "FROM assumptions a"
+  );
+  insertEvents.run(nowMs, nowMs);
+
+  return db.prepare("SELECT COUNT(*) AS n FROM assumptions").get().n;
+}
+
+function dependentSchemaObjects(db) {
+  // Enumerate every view and trigger that mentions the legacy `nodes` table in
+  // its definition. The SQLite "making other kinds of table schema changes"
+  // recipe (the canonical 12-step procedure) requires these to be dropped
+  // BEFORE the rename-out-of-existence rebuild and recreated AFTER -- otherwise
+  // SQLite re-validates the schema during ALTER TABLE ... RENAME TO, finds the
+  // now-dangling view, and throws "error in view <name>: no such table:
+  // main.nodes". We do not hardcode rs_discoveries; any future view/trigger on
+  // `nodes` is picked up automatically. Drop-then-recreate is idempotent: views
+  // whose sql carries IF NOT EXISTS re-exec cleanly; ones without it are simply
+  // recreated fresh since we dropped them first.
+  const rows = db.prepare(
+    "SELECT type, name, sql FROM sqlite_master " +
+    "WHERE type IN ('view','trigger') AND sql IS NOT NULL " +
+    // \bnodes\b style match: the token "nodes" not immediately followed by an
+    // identifier char (so we do not mistakenly catch nodes_new). SQLite LIKE
+    // has no word boundaries, so over-match a little and trust the recreate to
+    // be a no-op for anything unrelated -- but exclude the obvious nodes_new.
+    "AND sql LIKE '%nodes%' AND sql NOT LIKE '%nodes_new%'"
+  ).all();
+  // Defensive: drop NULL/empty sql rows (autogenerated indexes never appear
+  // here because we filtered type, but be safe).
+  return rows.filter((r) => r && r.name && typeof r.sql === 'string' && r.sql.trim());
+}
+
+function tightenSchemaWithCheckConstraints(db) {
+  // Step 2: re-create-table-with-NOT-NULL plus CHECK constraints.
+  // Canonical SQLite 12-step recipe. foreign_keys is flipped OFF by the caller
+  // (runMigration) OUTSIDE the BEGIN/COMMIT and restored after -- it MUST be off
+  // for this rebuild: DROP TABLE nodes below is the FK PARENT, and the edges->nodes
+  // FK trips "FOREIGN KEY constraint failed" on any room whose edges table has rows
+  // when foreign_keys is ON. (This comment earlier wrongly claimed FK behavior was
+  // unchanged; that only held for fresh rooms with no edges.)
+
+  // Step 2a: capture and drop every view/trigger that depends on `nodes`. Must
+  // happen before DROP TABLE nodes so the schema stays internally consistent
+  // through the rename. Recreated verbatim at the end of this function.
+  const dependents = dependentSchemaObjects(db);
+  for (const obj of dependents) {
+    if (obj.type === 'view') {
+      db.exec('DROP VIEW IF EXISTS "' + obj.name.replace(/"/g, '""') + '"');
+    } else {
+      db.exec('DROP TRIGGER IF EXISTS "' + obj.name.replace(/"/g, '""') + '"');
+    }
+  }
+
+  db.exec(
+    "CREATE TABLE nodes_new (" +
+    "  id TEXT PRIMARY KEY, " +
+    "  type TEXT NOT NULL, " +
+    "  properties TEXT DEFAULT '{}', " +
+    "  source_path TEXT NOT NULL, " +
+    "  created_by TEXT NOT NULL CHECK(created_by IN ('user','larry','import','brain','system')), " +
+    "  confidence REAL, " +
+    "  review_status TEXT NOT NULL DEFAULT 'proposed' " +
+    "    CHECK(review_status IN ('proposed','confirmed','rejected','stale','superseded','needs_evidence','validated','invalidated')), " +
+    "  created_at INTEGER NOT NULL, " +
+    "  last_seen_at INTEGER NOT NULL, " +
+    "  source_section TEXT, " +
+    "  confirmed_by TEXT, " +
+    "  confirmed_at INTEGER" +
+    ")"
+  );
+
+  db.exec(
+    "INSERT INTO nodes_new " +
+    "SELECT id, type, properties, source_path, created_by, confidence, " +
+    "       review_status, created_at, last_seen_at, source_section, " +
+    "       confirmed_by, confirmed_at " +
+    "FROM nodes"
+  );
+  db.exec('DROP TABLE nodes');
+  db.exec('ALTER TABLE nodes_new RENAME TO nodes');
+
+  // Recreate the existing index plus the 6 new ones (mandatory + recommended
+  // per PROVENANCE.md L97-104).
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_review_status ON nodes(review_status)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_source_path ON nodes(source_path)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_created_by ON nodes(created_by)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_created_at ON nodes(created_at)');
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_last_seen_at ON nodes(last_seen_at)');
+  db.exec(
+    'CREATE INDEX IF NOT EXISTS idx_nodes_confirmed_by ON nodes(confirmed_by) ' +
+    'WHERE confirmed_by IS NOT NULL'
+  );
+
+  // Step 2b: recreate the views/triggers we dropped in Step 2a, now that
+  // `nodes` exists again with the tightened schema. The captured `sql` is the
+  // exact CREATE statement from sqlite_master; many carry IF NOT EXISTS which
+  // keeps the recreate idempotent, and any that do not were dropped above so
+  // re-exec is still safe.
+  for (const obj of dependents) {
+    db.exec(obj.sql);
+  }
+}
+
+function insertSentinel(db) {
+  const now = new Date().toISOString();
+  if (identityHasUpdatedAt(db)) {
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value, updated_at) VALUES (?, ?, ?)"
+    ).run(SENTINEL_KEY, now, now);
+  } else {
+    // Fallback for the 2-column PROVENANCE.md spec (legacy / hypothetical).
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value) VALUES (?, ?)"
+    ).run(SENTINEL_KEY, now);
+  }
+}
+
+// ----- Public API -----
+
+/**
+ * Run the Phase 109 nodes-provenance migration. Idempotent.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @returns {{applied: boolean, sentinelInserted: boolean, backfilledAssumptions: number}}
+ */
+function runMigration(db) {
+  ensureIdentityTable(db);
+  if (sentinelPresent(db)) {
+    return { applied: false, sentinelInserted: false, backfilledAssumptions: 0 };
+  }
+  let backfilledAssumptions = 0;
+  // Canonical SQLite 12-step recipe: foreign_keys MUST be OFF for the nodes-table
+  // rebuild (tightenSchemaWithCheckConstraints) because DROP TABLE nodes is the FK
+  // PARENT and trips the edges->nodes FK when edges has rows + foreign_keys is ON.
+  // The PRAGMA is a no-op INSIDE a transaction, so flip it OUTSIDE the BEGIN/COMMIT
+  // and restore after. Fresh rooms (no edges) passed before; legacy rooms WITH edges
+  // failed "FOREIGN KEY constraint failed" (the 2026-06-29 motj-ecosystem heal).
+  db.exec('PRAGMA foreign_keys=OFF');
+  db.exec('BEGIN');
+  try {
+    addColumnsIdempotent(db);
+    backfillFromProperties(db);
+    backfilledAssumptions = backfillAssumptionsAsGraphNodes(db);
+    tightenSchemaWithCheckConstraints(db);
+    // Safety belt (production-data heal): the rebuild preserves node ids, so the
+    // edges->nodes references stay valid; verify ZERO FK violation before committing.
+    const fkViolations = db.prepare('PRAGMA foreign_key_check').all();
+    if (fkViolations.length > 0) {
+      throw new Error('phase-109 migration introduced ' + fkViolations.length + ' FK violation(s); rolling back');
+    }
+    insertSentinel(db);
+    db.exec('COMMIT');
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_rbErr) { /* ignore */ }
+    try { db.exec('PRAGMA foreign_keys=ON'); } catch (_e) { /* restore best-effort */ }
+    throw err;
+  }
+  db.exec('PRAGMA foreign_keys=ON');
+  return { applied: true, sentinelInserted: true, backfilledAssumptions };
+}
+
+module.exports = { runMigration, SENTINEL_KEY };

package/lib/core/migrations/phase-109-session-focus.cjs

@@ -0,0 +1,99 @@
+'use strict';
+// Phase 109 session_focus table migration. Idempotent via identity sentinel.
+// Runs AFTER Plan 109-01 nodes-provenance migration (FK target schema must exist).
+//
+// Parallel-worktree note (Phase 109-02 isolated execution):
+// This migration is authored to run primarily against the post-109-01 nodes
+// schema (12 columns including source_path / created_by / confidence /
+// review_status / created_at / last_seen_at). When 109-01 has not yet run in
+// the same worktree, ensureProvenanceColumns() defensively backfills the
+// missing nodes columns via additive ALTER TABLE so the FK target accepts
+// our test fixtures (which insert with all 9 provenance fields). The 109-01
+// canonical migration will re-add the same columns idempotently when it
+// later runs in the merged trunk; ALTER TABLE ADD COLUMN IF NOT EXISTS
+// semantics (we wrap each in try/catch since SQLite < 3.35 lacks IF NOT
+// EXISTS on ADD COLUMN) keep the operation safe in either order.
+
+const SENTINEL_KEY = 'phase_109_session_focus_v1';
+
+function sentinelPresent(db) {
+  try {
+    const row = db.prepare('SELECT value FROM identity WHERE key = ?').get(SENTINEL_KEY);
+    return Boolean(row && row.value);
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureIdentityTable(db) {
+  // identity table is canonically created by memory-ops.cjs initMemorySchema
+  // with shape (key TEXT PK, value TEXT NOT NULL, updated_at TEXT NOT NULL).
+  // We re-issue CREATE TABLE IF NOT EXISTS as a safety net for callers that
+  // skip initMemorySchema; the IF NOT EXISTS clause makes this a no-op when
+  // memory-ops already created the table.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS identity (" +
+    "key TEXT PRIMARY KEY, " +
+    "value TEXT NOT NULL, " +
+    "updated_at TEXT NOT NULL" +
+    ")"
+  );
+}
+
+// Defensive backfill of 109-01 provenance columns when running in a parallel
+// worktree where 109-01 has not yet executed. Each ADD COLUMN is wrapped in a
+// try/catch so re-runs (when 109-01 has already added the column) are no-ops.
+// This is additive ONLY; it never alters existing column types or drops data.
+function ensureProvenanceColumns(db) {
+  const additions = [
+    "ALTER TABLE nodes ADD COLUMN source_path TEXT",
+    "ALTER TABLE nodes ADD COLUMN created_by TEXT",
+    "ALTER TABLE nodes ADD COLUMN confidence REAL",
+    "ALTER TABLE nodes ADD COLUMN review_status TEXT",
+    "ALTER TABLE nodes ADD COLUMN created_at INTEGER",
+    "ALTER TABLE nodes ADD COLUMN last_seen_at INTEGER",
+    "ALTER TABLE nodes ADD COLUMN source_section TEXT",
+  ];
+  for (const sql of additions) {
+    try {
+      db.exec(sql);
+    } catch (_e) {
+      // Column already exists or table missing; either is acceptable here.
+      // The migration cannot proceed if nodes table is absent; that error
+      // surfaces below at session_focus FK creation time.
+    }
+  }
+}
+
+function runMigration(db) {
+  ensureIdentityTable(db);
+  if (sentinelPresent(db)) {
+    return { applied: false };
+  }
+  // Defensive backfill BEFORE creating session_focus, so the FK target column
+  // set is present whether or not 109-01 has run in this worktree.
+  ensureProvenanceColumns(db);
+  db.exec('BEGIN');
+  try {
+    db.exec(
+      "CREATE TABLE IF NOT EXISTS session_focus ( " +
+      "session_id    TEXT PRIMARY KEY, " +
+      "focus_node_id TEXT NOT NULL, " +
+      "focus_type    TEXT NOT NULL, " +
+      "set_at        INTEGER NOT NULL, " +
+      "set_by        TEXT NOT NULL CHECK(set_by IN ('user','larry','auto-from-jtbd','auto-from-operator','auto-from-state')), " +
+      "FOREIGN KEY (focus_node_id) REFERENCES nodes(id) " +
+      ")"
+    );
+    db.exec("CREATE INDEX IF NOT EXISTS idx_session_focus_set_at ON session_focus(set_at DESC)");
+    const nowIso = new Date().toISOString();
+    db.prepare("INSERT OR REPLACE INTO identity (key, value, updated_at) VALUES (?, ?, ?)").run(SENTINEL_KEY, nowIso, nowIso);
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+  return { applied: true };
+}
+
+module.exports = { runMigration, SENTINEL_KEY };

package/lib/core/migrations/phase-160-nodes-bitemporal.cjs

@@ -0,0 +1,168 @@
+'use strict';
+/**
+ * Phase 160-04 nodes-table bitemporal migration (R7).
+ *
+ * Generalizes the half-built Phase 150.8 edge valid-time pattern to nodes:
+ * adds four bitemporal columns (epoch ms, nullable) to the nodes table and
+ * backfills valid_from from the existing created_at column.
+ *
+ * Authored as the phase-109-nodes-provenance.cjs ANALOG (Canon Part 7 -- the
+ * named additive-idempotent-backfill template): SENTINEL_KEY sentinel-row
+ * idempotency, addColumnsIdempotent with duplicate-column tolerance,
+ * backfillValidFrom, the BEGIN/COMMIT/ROLLBACK wrapper, and additive indices.
+ * Unlike phase-109 this migration needs NO re-create-table step: every new
+ * column is nullable, so a plain duplicate-resilient ALTER TABLE is sufficient
+ * and the existing CHECK-constrained schema is left untouched.
+ *
+ * Idempotent via identity.key = 'phase_160_bitemporal_migration_v1' sentinel
+ * row. Running twice yields no error and an identical schema + data result.
+ *
+ * Canon Part 8 invariants (mirrors the phase-109 invariant):
+ *   - Writes only to room.db.
+ *   - Zero Brain queries.
+ *   - Zero remote egress.
+ *   - Sentinel row identity.phase_160_bitemporal_migration_v1 is local-only.
+ *
+ * Migration shape:
+ *   Step 1. ALTER TABLE nodes ADD COLUMN x4 (each duplicate-resilient):
+ *           valid_from / valid_to / invalidated_at / last_modified_at, all
+ *           INTEGER epoch ms, nullable.
+ *   Step 2. Backfill valid_from = created_at for every existing row; leave
+ *           valid_to / invalidated_at / last_modified_at NULL.
+ *   Step 3. Additive indices on valid_from + invalidated_at.
+ *   Step 4. Insert sentinel row.
+ *
+ * Exports:
+ *   runMigration(db) -> { applied, sentinelInserted }
+ *   SENTINEL_KEY (string)
+ */
+
+const SENTINEL_KEY = 'phase_160_bitemporal_migration_v1';
+
+// New bitemporal columns added to the Phase-109 tightened nodes table. All
+// nullable INTEGER epoch ms, so a plain ALTER TABLE suffices (no re-create).
+const NEW_COLUMNS = [
+  // [colName, ALTER TABLE clause]
+  ['valid_from', 'INTEGER'],
+  ['valid_to', 'INTEGER'],
+  ['invalidated_at', 'INTEGER'],
+  ['last_modified_at', 'INTEGER'],
+];
+
+// ----- Helpers -----
+
+function tableExists(db, name) {
+  const row = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name=?"
+  ).get(name);
+  return Boolean(row);
+}
+
+function identityHasUpdatedAt(db) {
+  // Real rooms ship the 3-column identity table (key/value/updated_at). Detect
+  // at runtime so the sentinel INSERT builds the correct statement -- mirrors
+  // phase-109-nodes-provenance.cjs identityHasUpdatedAt.
+  const cols = db.prepare('PRAGMA table_info(identity)').all().map((c) => c.name);
+  return cols.includes('updated_at');
+}
+
+function sentinelPresent(db) {
+  if (!tableExists(db, 'identity')) return false;
+  try {
+    const row = db.prepare('SELECT value FROM identity WHERE key = ?').get(SENTINEL_KEY);
+    return Boolean(row && row.value);
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureIdentityTable(db) {
+  // Default to the canonical 3-column shape (Phase 84-02 memory-ops). In
+  // production openRoomDb runs initMemorySchema before this migration, so the
+  // table already exists; the CREATE IF NOT EXISTS only fires for hermetic
+  // test fixtures. Mirrors phase-109 ensureIdentityTable.
+  db.exec(
+    "CREATE TABLE IF NOT EXISTS identity (" +
+    "key TEXT PRIMARY KEY, " +
+    "value TEXT NOT NULL, " +
+    "updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP" +
+    ")"
+  );
+}
+
+function addColumnsIdempotent(db) {
+  // PRAGMA table_info gives existing column names; skip ALTER for any already
+  // present (safe against partial migrations or parallel races). Duplicate
+  // column errors are treated as no-ops. Mirrors phase-109 addColumnsIdempotent.
+  const existing = new Set(db.prepare('PRAGMA table_info(nodes)').all().map((c) => c.name));
+  for (const [col, clause] of NEW_COLUMNS) {
+    if (existing.has(col)) continue;
+    try {
+      db.exec('ALTER TABLE nodes ADD COLUMN ' + col + ' ' + clause);
+    } catch (err) {
+      if (!/duplicate column name/i.test(err.message)) throw err;
+    }
+  }
+}
+
+function backfillValidFrom(db) {
+  // valid_from = created_at for every existing row that has not been set.
+  // valid_to / invalidated_at / last_modified_at intentionally stay NULL:
+  // a freshly-migrated row is open-ended (no closure, never modified-since).
+  db.exec(
+    'UPDATE nodes SET valid_from = created_at ' +
+    'WHERE valid_from IS NULL AND created_at IS NOT NULL'
+  );
+}
+
+function addIndices(db) {
+  // Additive indices for point-in-time / supersession queries (Plan 05 helper
+  // + Plan 04 supersession close). IF NOT EXISTS keeps the recreate idempotent.
+  db.exec('CREATE INDEX IF NOT EXISTS idx_nodes_valid_from ON nodes(valid_from)');
+  db.exec(
+    'CREATE INDEX IF NOT EXISTS idx_nodes_invalidated_at ON nodes(invalidated_at) ' +
+    'WHERE invalidated_at IS NOT NULL'
+  );
+}
+
+function insertSentinel(db) {
+  const now = new Date().toISOString();
+  if (identityHasUpdatedAt(db)) {
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value, updated_at) VALUES (?, ?, ?)"
+    ).run(SENTINEL_KEY, now, now);
+  } else {
+    db.prepare(
+      "INSERT OR REPLACE INTO identity (key, value) VALUES (?, ?)"
+    ).run(SENTINEL_KEY, now);
+  }
+}
+
+// ----- Public API -----
+
+/**
+ * Run the Phase 160 nodes-bitemporal migration. Idempotent.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @returns {{applied: boolean, sentinelInserted: boolean}}
+ */
+function runMigration(db) {
+  ensureIdentityTable(db);
+  if (sentinelPresent(db)) {
+    return { applied: false, sentinelInserted: false };
+  }
+  db.exec('BEGIN');
+  try {
+    addColumnsIdempotent(db);
+    backfillValidFrom(db);
+    addIndices(db);
+    insertSentinel(db);
+    db.exec('COMMIT');
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_rbErr) { /* ignore */ }
+    throw err;
+  }
+  return { applied: true, sentinelInserted: true };
+}
+
+module.exports = { runMigration, SENTINEL_KEY };