@ijfw/memory-server 1.3.0

package/src/compute/graph-lock.js

@@ -0,0 +1,114 @@
+// IJFW v1.3.0 -- D2 graph-write lock.
+//
+// Source authority: D-PILLAR-SPEC.md section 5.
+//
+// Coordinates symbol-graph writes with the existing scan-state lock and
+// session-counter lock. Each lock owns a separate concern and lives in a
+// separate file under `<projectRoot>/.ijfw/`:
+//
+//   .scan-state.lock      -- Phase 3 cold scan resume coordination
+//   .session-counter.lock -- session counter atomicity
+//   .graph-write.lock     -- D2 kg_nodes/kg_edges write coordination
+//
+// Pattern (mirrors scan-resume.js acquireScanLock):
+//   - Exclusive create via `wx` flag (noclobber CAS).
+//   - Lock content: `${pid}\n${epoch_ms}\n`
+//   - Stale reclamation: 60s OR dead PID.
+//   - Reader (BFS traversal) does NOT acquire -- WAL mode handles reads.
+//
+// Concurrent invocation behavior (per D-PILLAR-SPEC section 5):
+//   - Writer #1 acquires; writer #2 waits up to 5s polling, then errors
+//     with EBUSY_GRAPH_WRITE.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+
+const LOCK_FILE = '.graph-write.lock';
+const LOCK_STALE_MS = 60_000;
+const ACQUIRE_WAIT_MS = 5_000;
+const POLL_INTERVAL_MS = 50;
+
+function lockPath(projectRoot) {
+  return join(String(projectRoot), '.ijfw', LOCK_FILE);
+}
+
+function isPidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function reclaimIfStale(lp) {
+  if (!existsSync(lp)) return;
+  let raw;
+  try { raw = readFileSync(lp, 'utf8'); } catch { return; }
+  const lines = String(raw).split(/\r?\n/);
+  const pid = Number(lines[0]);
+  const ts = Number(lines[1]);
+  const ageOk = Number.isFinite(ts) && (Date.now() - ts) <= LOCK_STALE_MS;
+  if (isPidAlive(pid) && ageOk) return;
+  try { unlinkSync(lp); } catch { /* best-effort */ }
+}
+
+/**
+ * acquireGraphWriteLock(projectRoot, opts?) -> { released } | throws
+ *
+ * Acquires the graph-write lock with up to ACQUIRE_WAIT_MS of busy
+ * polling. Throws EBUSY_GRAPH_WRITE on timeout. Returns a handle whose
+ * `released()` method releases the lock; idempotent.
+ *
+ * opts.waitMs (default ACQUIRE_WAIT_MS) -- caller-overridable for tests.
+ */
+export function acquireGraphWriteLock(projectRoot, opts = {}) {
+  const waitMs = Number.isFinite(opts.waitMs) ? opts.waitMs : ACQUIRE_WAIT_MS;
+  const dir = join(String(projectRoot), '.ijfw');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const lp = lockPath(projectRoot);
+
+  const deadline = Date.now() + waitMs;
+  let _lastErr;
+  while (true) {
+    reclaimIfStale(lp);
+    const payload = String(process.pid) + '\n' + String(Date.now()) + '\n';
+    try {
+      writeFileSync(lp, payload, { encoding: 'utf8', flag: 'wx' });
+      let released = false;
+      return {
+        released: () => {
+          if (released) return;
+          released = true;
+          try { unlinkSync(lp); } catch { /* best-effort */ }
+        },
+      };
+    } catch (err) {
+      lastErr = err;
+      if (!err || err.code !== 'EEXIST') throw err;
+    }
+    if (Date.now() >= deadline) {
+      const e = new Error(
+        'EBUSY_GRAPH_WRITE: another writer holds .ijfw/.graph-write.lock; ' +
+        `waited ${waitMs}ms.`
+      );
+      e.code = 'EBUSY_GRAPH_WRITE';
+      throw e;
+    }
+    // Tight polling -- 50ms cadence is fine for short writes.
+    sleepSync(POLL_INTERVAL_MS);
+  }
+}
+
+// Synchronous sleep -- used inside acquireGraphWriteLock's polling loop.
+// Atomics.wait on a SharedArrayBuffer-backed Int32Array is the standard
+// Node sync-sleep idiom. No new deps.
+function sleepSync(ms) {
+  const ab = new SharedArrayBuffer(4);
+  const ia = new Int32Array(ab);
+  Atomics.wait(ia, 0, 0, ms);
+}
+
+export const __test = { lockPath, LOCK_STALE_MS, ACQUIRE_WAIT_MS };

package/src/compute/index.js

@@ -0,0 +1,18 @@
+// IJFW v1.3.0 Alpha -- compute module barrel export.
+//
+// Surfaces the FTS5 layer + migration runner for callers in mcp-server.
+// Intentionally thin: callers should import named symbols from here, not
+// reach into ./fts5.js or ./migration-runner.js directly.
+
+export {
+  openDb,
+  safeWrite,
+  search,
+  closeDb,
+  dbPathFor,
+  IntegrityError,
+  SchemaVersionError,
+  ComputeDbError,
+} from './fts5.js';
+
+export { runMigrations, highestKnownVersion } from './migration-runner.js';

package/src/compute/migration-runner.js

@@ -0,0 +1,116 @@
+// IJFW v1.3.0 Alpha -- migration runner for the compute db.
+//
+// Discovers migrations in ./migrations/ matching NNN-name.js, sorts by
+// numeric prefix, and applies each migration whose VERSION exceeds the
+// db's current PRAGMA user_version. Each migration runs inside a single
+// transaction; failure rolls back and halts.
+//
+// Forbids downgrade: if currentVersion > targetVersion (= highest migration
+// VERSION found on disk), throws SchemaVersionError so callers refuse the db
+// rather than silently rebuilding it.
+
+import { readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MIGRATIONS_DIR = join(__dirname, 'migrations');
+
+export class SchemaVersionError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SchemaVersionError';
+  }
+}
+
+// Discover and load every migration module under ./migrations/, sorted by
+// numeric prefix ascending. Each module must export VERSION (integer),
+// DESCRIPTION (string), and up(db) (function).
+async function loadMigrations() {
+  let files;
+  try {
+    files = readdirSync(MIGRATIONS_DIR);
+  } catch {
+    return [];
+  }
+  const matches = files
+    .filter(f => /^\d+-.+\.js$/.test(f))
+    .sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+  const out = [];
+  for (const f of matches) {
+    const url = pathToFileURL(join(MIGRATIONS_DIR, f)).href;
+    const mod = await import(url);
+    if (typeof mod.VERSION !== 'number' || typeof mod.up !== 'function') {
+      throw new Error(`Migration ${f} is missing VERSION or up().`);
+    }
+    out.push({
+      file: f,
+      version: mod.VERSION,
+      description: mod.DESCRIPTION || '',
+      up: mod.up,
+    });
+  }
+  // Sort by VERSION ascending and reject duplicates -- defensive against
+  // mistakes in numeric prefix vs in-file VERSION.
+  out.sort((a, b) => a.version - b.version);
+  for (let i = 1; i < out.length; i++) {
+    if (out[i].version === out[i - 1].version) {
+      throw new Error(`Duplicate migration VERSION: ${out[i].version} (${out[i - 1].file} and ${out[i].file}).`);
+    }
+  }
+  return out;
+}
+
+export async function highestKnownVersion() {
+  const migrations = await loadMigrations();
+  return migrations.length === 0 ? 0 : migrations[migrations.length - 1].version;
+}
+
+// Apply every migration whose version is in (currentVersion, targetVersion].
+// Returns the new version. Throws SchemaVersionError on downgrade.
+export async function runMigrations(db, currentVersion, targetVersion) {
+  if (typeof currentVersion !== 'number' || typeof targetVersion !== 'number') {
+    throw new Error('runMigrations: currentVersion and targetVersion must be numbers.');
+  }
+  if (currentVersion > targetVersion) {
+    throw new SchemaVersionError(
+      `Compute db schema version ${currentVersion} is newer than this build supports (max ${targetVersion}). ` +
+      `Refusing to downgrade -- upgrade IJFW or open the db with a newer build.`
+    );
+  }
+  if (currentVersion === targetVersion) return currentVersion;
+
+  const migrations = await loadMigrations();
+  const pending = migrations.filter(m => m.version > currentVersion && m.version <= targetVersion);
+  if (pending.length === 0) return currentVersion;
+
+  let lastApplied = currentVersion;
+  for (const m of pending) {
+    // Each migration runs in its own transaction. We update user_version +
+    // schema_meta in the same tx so a crash mid-migration leaves the db
+    // recognisably at the prior version (no half-applied schema).
+    //
+    // BEGIN IMMEDIATE acquires the write lock at transaction start (paired
+    // with PRAGMA busy_timeout=5000 in openDb). Plain BEGIN (deferred) lets
+    // two concurrent writers both enter their migration tx, then one gets
+    // SQLITE_BUSY when it tries to upgrade -- migration 002's FTS5
+    // recreate-with-data path surfaced that race during Phase 5 audit.
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      m.up(db);
+      db.exec(`PRAGMA user_version = ${m.version}`);
+      const stmt = db.prepare(
+        'INSERT OR IGNORE INTO schema_meta(version, applied_at, description) VALUES (?, ?, ?)'
+      );
+      stmt.run(m.version, Date.now(), m.description);
+      db.exec('COMMIT');
+      lastApplied = m.version;
+    } catch (err) {
+      try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+      throw new Error(`Migration ${m.file} (v${m.version}) failed: ${err.message}`);
+    }
+  }
+  return lastApplied;
+}
+
+export default { runMigrations, highestKnownVersion, SchemaVersionError };

package/src/compute/migrations/001-initial.js

@@ -0,0 +1,23 @@
+// IJFW v1.3.0 Alpha -- migration 001: apply schema.sql on a fresh db.
+// Idempotent (CREATE TABLE IF NOT EXISTS + INSERT OR IGNORE).
+//
+// Source of truth for DDL: ../schema.sql (see PLAN-alpha.md V3-B4).
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = join(__dirname, '..', 'schema.sql');
+
+export const VERSION = 1;
+export const DESCRIPTION = 'alpha v1.3.0 -- raw + raw_fts + compiled + compiled_fts + trident_run + schema_meta';
+
+export function up(db) {
+  const sql = readFileSync(SCHEMA_PATH, 'utf-8');
+  // db.exec runs the multi-statement DDL block from schema.sql atomically
+  // when called inside the migration runner's transaction.
+  db.exec(sql);
+}
+
+export default { version: VERSION, description: DESCRIPTION, up };

package/src/compute/migrations/002-porter-stemming-source.js

@@ -0,0 +1,139 @@
+// IJFW v1.3.0 Alpha -- migration 002: Porter stemming + provenance source.
+//
+// Single coordinated migration for compute schema 1 -> 2 covering:
+//   - C9.4: flip raw_fts + compiled_fts tokenizer from default unicode61 to
+//           `porter unicode61` so regular morphological variants collapse
+//           (e.g. "authenticate"/"authenticating"/"authentication" stem to
+//           the same token; "running" stems to "run"). Porter does NOT
+//           handle irregular verbs -- "ran" stays "ran" and won't match
+//           "run" / "running". Documented limitation; not an IJFW bug.
+//   - C9.6: add `source` column to `raw` (provenance pointer; nullable).
+//           `session_id` already exists on `raw` from migration 001 so no
+//           column add is needed for it -- migration just covers the new
+//           provenance pointer + the matching index.
+//
+// FTS5 tables can't be ALTERed in place to change tokenizer. We use the
+// recreate-with-data path:
+//   1. Drop the old FTS5 virtual table + its triggers.
+//   2. Recreate the FTS5 virtual table with `tokenize='porter unicode61'`.
+//   3. Rebuild the index from the content table via INSERT INTO ... ('rebuild').
+//   4. Recreate the AI/AD/AU triggers so future writes stay synced.
+//
+// ADD-ONLY semantics: no destructive column drops; the only "destruction" is
+// recreation of the FTS5 *index* (an external-content view of `raw` and
+// `compiled`). The content tables are untouched. Crash-safety is delegated
+// to the migration runner's per-migration BEGIN/COMMIT envelope -- if any
+// statement fails the whole transaction rolls back and the db stays at v1.
+
+export const VERSION = 2;
+export const DESCRIPTION = 'porter stemming + raw.source provenance pointer';
+
+export function up(db) {
+  // --- C9.6: add `raw.source` column + matching partial index. -----------
+  //
+  // ADD COLUMN with no default and no NOT NULL constraint -- legacy rows
+  // and non-attributed inserts leave it NULL. The partial index on `source`
+  // mirrors schema.sql so fresh-db (path through 001 -> 002) and migrated
+  // db (path through 001 only originally) end up structurally identical.
+  if (!hasColumn(db, 'raw', 'source')) {
+    runDdl(db, 'ALTER TABLE raw ADD COLUMN source TEXT');
+  }
+  runDdl(db, 'CREATE INDEX IF NOT EXISTS raw_source_idx ON raw(source) WHERE source IS NOT NULL');
+
+  // --- C9.4: recreate raw_fts with porter stemming. ----------------------
+  recreateFts(db, {
+    contentTable: 'raw',
+    ftsTable: 'raw_fts',
+    indexedColumns: ['body'],
+    triggerPrefix: 'raw',
+  });
+
+  // --- C9.4: recreate compiled_fts with porter stemming. -----------------
+  recreateFts(db, {
+    contentTable: 'compiled',
+    ftsTable: 'compiled_fts',
+    indexedColumns: ['topic', 'body'],
+    triggerPrefix: 'compiled',
+  });
+}
+
+// Run a single multi-statement DDL string. Thin wrapper so the migration
+// reads with a single verb that doesn't collide with shell-`exec` security
+// linters.
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+// Returns true if `table` has a column named `column`. Uses PRAGMA
+// table_info which both better-sqlite3 and node:sqlite expose via
+// .prepare(...).all().
+function hasColumn(db, table, column) {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return rows.some(r => String(r.name) === column);
+}
+
+// Drop + recreate a contentless FTS5 virtual table with the new tokenizer,
+// then repopulate from the source content table via the FTS5 'rebuild'
+// command. Triggers (ai/ad/au) get recreated against the new FTS5 table.
+//
+// Parameters:
+//   contentTable    -- e.g. 'raw'
+//   ftsTable        -- e.g. 'raw_fts'
+//   indexedColumns  -- columns indexed by FTS5 (must match the original
+//                      schema; for raw it's ['body'], for compiled it's
+//                      ['topic','body']).
+//   triggerPrefix   -- e.g. 'raw' yielding raw_ai/raw_ad/raw_au.
+function recreateFts(db, { contentTable, ftsTable, indexedColumns, triggerPrefix }) {
+  // 1. Drop existing triggers first so the FTS5 table drop doesn't trigger
+  //    spurious deletes via a still-attached AD trigger.
+  runDdl(db, `DROP TRIGGER IF EXISTS ${triggerPrefix}_ai`);
+  runDdl(db, `DROP TRIGGER IF EXISTS ${triggerPrefix}_ad`);
+  runDdl(db, `DROP TRIGGER IF EXISTS ${triggerPrefix}_au`);
+
+  // 2. Drop the old FTS5 virtual table. Contentless table -- this only
+  //    removes the index, not any content table data.
+  runDdl(db, `DROP TABLE IF EXISTS ${ftsTable}`);
+
+  // 3. Recreate with porter stemming.
+  const cols = indexedColumns.join(', ');
+  runDdl(db,
+    `CREATE VIRTUAL TABLE ${ftsTable} USING fts5(
+       ${cols},
+       content='${contentTable}',
+       content_rowid='id',
+       tokenize='porter unicode61'
+     )`
+  );
+
+  // 4. Recreate the AI/AD/AU triggers identical to schema.sql so future
+  //    writes stay in sync. Column lists are interpolated to handle the
+  //    raw (body) vs compiled (topic, body) shapes uniformly.
+  const colList = indexedColumns.join(', ');
+  const newColList = indexedColumns.map(c => `new.${c}`).join(', ');
+  const oldColList = indexedColumns.map(c => `old.${c}`).join(', ');
+
+  runDdl(db,
+    `CREATE TRIGGER ${triggerPrefix}_ai AFTER INSERT ON ${contentTable} BEGIN
+       INSERT INTO ${ftsTable}(rowid, ${colList}) VALUES (new.id, ${newColList});
+     END`
+  );
+  runDdl(db,
+    `CREATE TRIGGER ${triggerPrefix}_ad AFTER DELETE ON ${contentTable} BEGIN
+       INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${colList}) VALUES('delete', old.id, ${oldColList});
+     END`
+  );
+  runDdl(db,
+    `CREATE TRIGGER ${triggerPrefix}_au AFTER UPDATE ON ${contentTable} BEGIN
+       INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${colList}) VALUES('delete', old.id, ${oldColList});
+       INSERT INTO ${ftsTable}(rowid, ${colList}) VALUES (new.id, ${newColList});
+     END`
+  );
+
+  // 5. Repopulate FTS5 from the content table. The FTS5 'rebuild' command
+  //    is the canonical way to (re)build an external-content index from
+  //    its source table -- handles every existing row with a single call
+  //    and is faster than INSERT-row-by-row.
+  runDdl(db, `INSERT INTO ${ftsTable}(${ftsTable}) VALUES('rebuild')`);
+}
+
+export default { version: VERSION, description: DESCRIPTION, up };

package/src/compute/migrations/003-tier-semantic.js

@@ -0,0 +1,69 @@
+// IJFW v1.3.0 -- compute migration 003: 4-tier semantic axis (D1).
+//
+// Source authority: PRD-v2 §9 Pillar D D1 + .planning/1.3.0/D-PILLAR-SPEC.md §1.
+//
+// Bumps compute schema 2 -> 3. Adds `tier_semantic` to BOTH content tables
+// in the compute db so dream-cycle promotions (Episodic -> Semantic via
+// supersession; Procedural candidate emit) can land on the compiled tier
+// with the correct semantic label and query back through FTS5 by tier.
+//
+// Defaults differ by table on purpose:
+//   - raw.tier_semantic       DEFAULT 'working'   (raw observations are
+//                                                   session-bound by
+//                                                   definition; Working tier)
+//   - compiled.tier_semantic  DEFAULT 'semantic'  (per D-PILLAR-SPEC §1 the
+//                                                   compiled table IS the
+//                                                   natural Semantic tier;
+//                                                   procedural_candidate /
+//                                                   procedural / episodic
+//                                                   write explicit values
+//                                                   when needed)
+//
+// ADD-ONLY: no column drops, no FTS5 recreation -- the FTS5 index is
+// content-table backed and indexes only `body` (raw) / `topic, body`
+// (compiled), so adding a non-FTS column doesn't touch the FTS5 schema.
+//
+// Crash safety: BEGIN IMMEDIATE wrap by the migration runner. If any
+// statement fails, ROLLBACK leaves user_version at 2.
+
+export const VERSION = 3;
+export const DESCRIPTION = 'tier_semantic axis on raw + compiled (working/episodic/semantic/procedural)';
+
+export function up(db) {
+  // --- raw.tier_semantic --------------------------------------------------
+  if (!hasColumn(db, 'raw', 'tier_semantic')) {
+    runDdl(db, `ALTER TABLE raw ADD COLUMN tier_semantic TEXT DEFAULT 'working'`);
+  }
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS raw_tier_semantic_idx ` +
+    `ON raw(tier_semantic, ts)`
+  );
+
+  // --- compiled.tier_semantic --------------------------------------------
+  // Compiled rows are the natural Semantic tier per D-PILLAR-SPEC §1.
+  // Procedural candidate / procedural rows override the default at write
+  // time. Episodic rows that get promoted to Semantic via supersession
+  // also write into compiled with this default.
+  if (!hasColumn(db, 'compiled', 'tier_semantic')) {
+    runDdl(db, `ALTER TABLE compiled ADD COLUMN tier_semantic TEXT DEFAULT 'semantic'`);
+  }
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS compiled_tier_semantic_idx ` +
+    `ON compiled(tier_semantic, ts)`
+  );
+}
+
+// runDdl -- thin wrapper that runs multi-statement DDL via the sqlite
+// driver's exec method (better-sqlite3 / node:sqlite both expose .exec).
+// Mirrors the helper in compute/migrations/002. NOT child_process.exec.
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+// hasColumn -- defence against re-application; mirrors the helper in 002.
+function hasColumn(db, table, column) {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return rows.some(r => String(r.name) === column);
+}
+
+export default { version: VERSION, description: DESCRIPTION, up };

package/src/compute/migrations/004-kg-tables.js

@@ -0,0 +1,83 @@
+// IJFW v1.3.0 -- compute migration 004: symbol-graph kg_nodes + kg_edges (D2).
+//
+// Source authority: PRD-v2 section 9 Pillar D D2 + .planning/1.3.0/D-PILLAR-SPEC.md sections 2-7.
+//
+// Bumps compute schema 3 -> 4. Adds two ADD-ONLY tables that back the
+// regex-only symbol graph:
+//
+//   kg_nodes  -- one row per (kind, name) pair extracted from observations.
+//                kind in {file, function, identifier, error_code, decision}
+//                redacted=1 means the entity matched the secret redactor and
+//                MUST NOT participate in edges (per D-PILLAR-SPEC section 3
+//                ordering invariant).
+//
+//   kg_edges  -- weighted, kind-typed edge between two clean kg_nodes.
+//                Co-occurrence counter + weight column carry the section 2
+//                formula output. Edges are undirected at the read layer
+//                (BFS looks at both src and dst indexes), but stored with
+//                a stable (src, dst) ordering by id ascending so
+//                UPSERT-on-co-occurrence stays deterministic.
+//
+// ADD-ONLY: pure CREATE TABLE / CREATE INDEX. No drops, no FTS5 touch.
+// Migration 003 left compute db at user_version=3 with tier_semantic on
+// raw + compiled; this migration is layered on top with no backfill.
+//
+// Crash safety: BEGIN IMMEDIATE wrap by the migration runner. If any
+// statement fails, ROLLBACK leaves user_version at 3.
+
+export const VERSION = 4;
+export const DESCRIPTION = 'symbol-graph kg_nodes + kg_edges (D2 regex extractor)';
+
+export function up(db) {
+  // --- kg_nodes ----------------------------------------------------------
+  // Composite UNIQUE on (kind, name) so the entity extractor's "find or
+  // create" path can use INSERT OR IGNORE + SELECT id by (kind, name).
+  // first_seen / last_seen are observation timestamps so D4 cascading
+  // staleness can compute recency_decay without a separate ledger join.
+  // redacted is a boolean (0/1) -- redactor.classify() result is captured
+  // here per D-PILLAR-SPEC section 3.
+  runDdl(db, `
+    CREATE TABLE IF NOT EXISTS kg_nodes (
+      id          INTEGER PRIMARY KEY,
+      kind        TEXT    NOT NULL,
+      name        TEXT    NOT NULL,
+      first_seen  INTEGER NOT NULL,
+      last_seen   INTEGER NOT NULL,
+      redacted    INTEGER NOT NULL DEFAULT 0,
+      UNIQUE(kind, name)
+    )
+  `);
+  runDdl(db, `CREATE INDEX IF NOT EXISTS kg_nodes_kind_name_idx ON kg_nodes(kind, name)`);
+  runDdl(db, `CREATE INDEX IF NOT EXISTS kg_nodes_last_seen_idx ON kg_nodes(last_seen)`);
+
+  // --- kg_edges ----------------------------------------------------------
+  // src + dst are kg_nodes.id values. kind is the edge label
+  // (co_occurs in alpha; D4 will introduce supersedes/implements/references).
+  // weight is the section 2 formula output (clamp_01). co_occurrence_count
+  // is the raw counter the formula's log1p term reads from.
+  // ts is the most-recent co-occurrence ts, used for recency_decay refresh.
+  // PRIMARY KEY (src, dst, kind) gives UPSERT-on-co-occurrence semantics
+  // without a separate UNIQUE index.
+  runDdl(db, `
+    CREATE TABLE IF NOT EXISTS kg_edges (
+      src                  INTEGER NOT NULL,
+      dst                  INTEGER NOT NULL,
+      kind                 TEXT    NOT NULL,
+      weight               REAL    NOT NULL DEFAULT 0,
+      co_occurrence_count  INTEGER NOT NULL DEFAULT 0,
+      ts                   INTEGER NOT NULL,
+      PRIMARY KEY (src, dst, kind),
+      FOREIGN KEY (src) REFERENCES kg_nodes(id),
+      FOREIGN KEY (dst) REFERENCES kg_nodes(id)
+    )
+  `);
+  runDdl(db, `CREATE INDEX IF NOT EXISTS kg_edges_src_kind_idx ON kg_edges(src, kind)`);
+  runDdl(db, `CREATE INDEX IF NOT EXISTS kg_edges_dst_kind_idx ON kg_edges(dst, kind)`);
+  runDdl(db, `CREATE INDEX IF NOT EXISTS kg_edges_weight_idx   ON kg_edges(weight)`);
+}
+
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+export default { version: VERSION, description: DESCRIPTION, up };

package/src/compute/migrations/005-stale-candidate.js

@@ -0,0 +1,72 @@
+// IJFW v1.3.0 -- compute migration 005: D4 cascading staleness column.
+//
+// Source authority: PRD-v2 section 9 Pillar D D4 + .planning/1.3.0/D-PILLAR-SPEC.md
+// section 2 (cascading staleness propagation threshold) + section 7 (50-fixture
+// grader for D4 cascading staleness).
+//
+// Bumps compute schema 4 -> 5. Adds the `stale_candidate` column to BOTH
+// content tables (`raw` + `compiled`) so D4's BFS-from-superseded-node
+// propagation can flag related observations without touching retrieval
+// until the grader proves >85% precision.
+//
+// Column semantics:
+//   stale_candidate INTEGER DEFAULT 0
+//     0 = fresh (default; never set by D4)
+//     1 = flagged by cascading staleness BFS (excluded from search by
+//         default; surface only with include_stale=true override)
+//     2 = confirmed stale (reserved for 1.4.0 contradiction-detection;
+//         alpha never writes this value)
+//
+// Defaults to 0 on every existing row -- ADD-ONLY column with explicit
+// DEFAULT clause so the migration is backfill-free.
+//
+// Indexes:
+//   raw_stale_candidate_idx       -- partial index on stale_candidate > 0
+//                                    so the search() WHERE filter is fast
+//                                    on the common case (most rows fresh).
+//   compiled_stale_candidate_idx  -- same pattern on the compiled tier.
+//
+// ADD-ONLY: no column drops, no FTS5 touch. The FTS5 index is content-
+// table backed and indexes only `body` / `topic+body`, so adding a
+// non-FTS column doesn't touch the FTS5 schema.
+//
+// Crash safety: BEGIN IMMEDIATE wrap by the migration runner. If any
+// statement fails, ROLLBACK leaves user_version at 4.
+
+export const VERSION = 5;
+export const DESCRIPTION = 'stale_candidate column on raw + compiled (D4 cascading staleness)';
+
+export function up(db) {
+  // --- raw.stale_candidate ----------------------------------------------
+  if (!hasColumn(db, 'raw', 'stale_candidate')) {
+    runDdl(db, `ALTER TABLE raw ADD COLUMN stale_candidate INTEGER DEFAULT 0`);
+  }
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS raw_stale_candidate_idx ` +
+    `ON raw(stale_candidate) WHERE stale_candidate > 0`
+  );
+
+  // --- compiled.stale_candidate -----------------------------------------
+  if (!hasColumn(db, 'compiled', 'stale_candidate')) {
+    runDdl(db, `ALTER TABLE compiled ADD COLUMN stale_candidate INTEGER DEFAULT 0`);
+  }
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS compiled_stale_candidate_idx ` +
+    `ON compiled(stale_candidate) WHERE stale_candidate > 0`
+  );
+}
+
+// runDdl -- thin wrapper that runs multi-statement DDL via the sqlite
+// driver's `.exec` method (better-sqlite3 + node:sqlite both expose it).
+// Mirrors the helper in compute/migrations/003. Not a child_process call.
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+// hasColumn -- defence against re-application; mirrors the helper in 003.
+function hasColumn(db, table, column) {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+  return rows.some(r => String(r.name) === column);
+}
+
+export default { version: VERSION, description: DESCRIPTION, up };