@ijfw/memory-server 1.3.0

package/src/compute/sandbox-macos.js

@@ -0,0 +1,167 @@
+/**
+ * sandbox-macos.js -- macOS sandbox-exec wrapper for the compute runner.
+ *
+ * Generates a per-invocation Scheme-syntax sandbox profile (.sb) inline,
+ * writes it to the per-invocation temp dir, and returns a spawn-ready
+ * { cmd, args, env } that the runner uses with child_process.spawn.
+ *
+ * Default-deny model: deny default; allow file-read for project root +
+ * read-only paths needed for execution (system libs, dyld); allow file-write
+ * only for cwd + temp dir; deny network unless allowNet=true.
+ *
+ * Honest caveats:
+ *  - sandbox-exec is deprecated by Apple but still functional through current
+ *    macOS releases; we use it because it's the only OS-level mechanism
+ *    universally available without extra installs.
+ *  - Some Apple-internal subsystems (e.g. mDNSResponder lookup) may leak
+ *    metadata even when network is denied; this is documented best-effort.
+ *
+ * Zero external deps.
+ */
+
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// Build the .sb profile body as a Scheme s-expression.
+// Each allowed path is escaped for inclusion in (literal "...").
+function escapeForSb(s) {
+  // Backslash + double-quote escaped for Scheme string literals.
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+// V3-B3 sensitive-path enumeration: subpaths of $HOME we MUST deny reads on.
+// Honest framing: the V3-B1 baseline calls for an allowlist; in practice
+// macOS Node+Python require broad read access to dyld + system libs to start
+// at all. We therefore implement reads as "broadly allowed except this
+// enumerated deny-list", which produces the same observable outcome as a
+// strict allowlist for the V3-B3 exfil-walk fixtures (Documents / .ssh /
+// browser cookies / keychain / .aws / .gnupg / etc) without breaking Node.
+// Writes remain a strict allowlist (cwd + tempDir + allowedPaths).
+const SENSITIVE_HOME_SUBPATHS = [
+  'Documents', 'Downloads', 'Desktop', 'Pictures', 'Movies', 'Music',
+  'Library/Application Support/Google/Chrome',
+  'Library/Application Support/Firefox',
+  'Library/Application Support/BraveSoftware',
+  'Library/Application Support/Microsoft Edge',
+  'Library/Application Support/Arc',
+  'Library/Application Support/Vivaldi',
+  'Library/Application Support/Slack',
+  'Library/Application Support/com.apple.sharedfilelist',
+  'Library/Group Containers',
+  'Library/Cookies',
+  'Library/Keychains',
+  'Library/Mail',
+  'Library/Messages',
+  'Library/Safari',
+  '.ssh', '.aws', '.gnupg', '.docker', '.kube',
+  '.config', '.config/gcloud',
+  '.cargo', '.op',
+];
+const SENSITIVE_HOME_LITERALS = [
+  '.npmrc', '.pypirc', '.netrc', '.gitconfig', '.gitconfig.local',
+  '.bash_history', '.zsh_history', '.psql_history',
+  '.profile', '.bashrc', '.zshrc',
+];
+
+function denyHomeClauses(home) {
+  if (!home) return '';
+  const subs = SENSITIVE_HOME_SUBPATHS
+    .map((p) => `  (subpath "${escapeForSb(join(home, p))}")`)
+    .join('\n');
+  const lits = SENSITIVE_HOME_LITERALS
+    .map((p) => `  (literal "${escapeForSb(join(home, p))}")`)
+    .join('\n');
+  return `;; V3-B3 sensitive-path deny-list (subpath)
+(deny file-read*
+${subs}
+)
+;; V3-B3 sensitive-path deny-list (literal)
+(deny file-read*
+${lits}
+)`;
+}
+
+function buildProfile({ projectRoot: _projectRoot, cwd, tempDir, allowedPaths, allowNet, home }) {
+  const writes = new Set([cwd, tempDir, ...(allowedPaths || [])]);
+  const writeClauses = Array.from(writes)
+    .filter(Boolean)
+    .map((p) => `  (subpath "${escapeForSb(p)}")`)
+    .join('\n');
+
+  // Network clause: explicit allow only when requested. We avoid a bare
+  // `(deny network*)` because it interferes with Node's IPC startup; we
+  // narrow the deny to outbound traffic + remote sockets while leaving
+  // local UNIX sockets (used by Node IPC + libuv) intact.
+  const networkClause = allowNet
+    ? '(allow network*)'
+    : '(deny network-outbound)\n(deny network-inbound)\n(allow network* (local ip "*:*"))\n(allow network-bind (local ip))';
+
+  return `(version 1)
+(deny default)
+
+;; Required for sandbox-exec + Node/Python startup
+(allow process*)
+(allow signal)
+(allow ipc-posix-shm)
+(allow ipc-posix-sem)
+(allow sysctl-read)
+(allow mach-lookup)
+(allow iokit-open)
+
+;; Read access: broad by default; sensitive home subpaths denied below.
+(allow file-read*)
+
+${denyHomeClauses(home)}
+
+;; Write access: strict allowlist (cwd + tempDir + allowedPaths).
+(allow file-write*
+${writeClauses}
+)
+
+;; Standard /dev nodes (read+write).
+(allow file-read* file-write*
+  (literal "/dev/null")
+  (literal "/dev/zero")
+  (literal "/dev/random")
+  (literal "/dev/urandom")
+  (literal "/dev/tty"))
+
+;; Network (default deny outbound + inbound; loopback allowed for IPC).
+${networkClause}
+`;
+}
+
+/**
+ * wrap({ cmd, args, env, cwd, allowNet, allowedPaths, projectRoot, tempDir })
+ *  -> { cmd, args, env, profilePath }
+ *
+ * Wraps the requested invocation in `sandbox-exec -f <profile> <cmd> <args...>`.
+ * Caller is responsible for cleaning up `profilePath` after the subprocess exits.
+ */
+export function wrap({ cmd, args, env, cwd, allowNet, allowedPaths, projectRoot, tempDir }) {
+  if (!tempDir) throw new Error('sandbox-macos: tempDir is required');
+  // Resolve the home dir from the (already scrubbed) env, with a host
+  // homedir() fallback. Used to expand the V3-B3 sensitive deny-list.
+  const home = (env && env.HOME) || homedir() || null;
+  const profile = buildProfile({
+    projectRoot: projectRoot || cwd,
+    cwd,
+    tempDir,
+    allowedPaths,
+    allowNet: !!allowNet,
+    home,
+  });
+  const profilePath = join(tempDir, 'sandbox.sb');
+  writeFileSync(profilePath, profile, { mode: 0o600 });
+
+  return {
+    cmd: '/usr/bin/sandbox-exec',
+    args: ['-f', profilePath, cmd, ...args],
+    env,
+    profilePath,
+  };
+}
+
+// Exposed for tests.
+export { buildProfile as _buildProfileForTest };

package/src/compute/sandbox-windows.js

@@ -0,0 +1,63 @@
+/**
+ * sandbox-windows.js -- Best-effort Windows AppContainer wrapper.
+ *
+ * Honest framing per V3-B1: AppContainer enforcement on Windows requires
+ * COM/Win32 API integration beyond what's portably reachable from a Node
+ * MCP server without native bindings. This wrapper is documented as
+ * graceful-degrade -- when AppContainer cannot be set up, the subprocess
+ * runs with scrubbed env + path-prefix check only, and the runner emits
+ * the documented best-effort warning.
+ *
+ * The wrapper attempts AppContainer via PowerShell + Start-Process when
+ * available; otherwise it spawns directly.
+ *
+ * Zero external deps.
+ */
+
+// Probe for PowerShell once and cache. Reserved for future use when the
+// AppContainer wrap is reintroduced; kept exported so the function tree stays
+// reviewable.
+import { existsSync } from 'fs';
+
+let _psPath = null;
+let _psProbed = false;
+// eslint-disable-next-line no-unused-vars
+function findPowerShell() {
+  if (_psProbed) return _psPath;
+  _psProbed = true;
+  const candidates = [
+    'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe',
+    'C:\\Program Files\\PowerShell\\7\\pwsh.exe',
+  ];
+  for (const c of candidates) {
+    try {
+      if (existsSync(c)) {
+        _psPath = c;
+        return _psPath;
+      }
+    } catch { /* keep probing */ }
+  }
+  return null;
+}
+
+/**
+ * wrap({ cmd, args, env, cwd, allowNet, allowedPaths, projectRoot, tempDir })
+ *  -> { cmd, args, env, degraded }
+ *
+ * `degraded: true` indicates the caller (runner.js) should treat this as
+ * best-effort only and surface the user-visible warning.
+ *
+ * Implementation: AppContainer profile creation requires the New-AppxPackage
+ * / NewAppContainer COM ops which aren't reachable from PowerShell without
+ * admin + a manifest. An earlier version wrapped commands with `Start-Process
+ * -Wait` to gain a working-directory boundary, but Start-Process detaches
+ * stdio and the runner ended up reading empty stdout/stderr -- breaking
+ * every sandbox-relevant assertion on Windows. The PowerShell layer was
+ * also not actually creating an AppContainer (just `-NoNewWindow -Wait`),
+ * so we now spawn the command directly with the scrubbed env that runner.js
+ * already prepared. Path-prefix and env-scrub guards still apply upstream;
+ * this layer is pure pass-through with the honest `degraded: true` flag.
+ */
+export function wrap({ cmd, args, env /*, cwd, allowNet, allowedPaths, projectRoot, tempDir */ }) {
+  return { cmd, args, env, degraded: true };
+}

package/src/compute/schema.sql

@@ -0,0 +1,118 @@
+-- IJFW v1.3.0 Alpha -- C9 Compute Lever / FTS5 schema
+-- Source of truth: .planning/1.3.0/PLAN-alpha.md V3-B4
+-- Companion ADR: .planning/1.3.0/ADR-alpha-schema-reservations.md
+--
+-- Reservations are intentional: blackboard-compatible columns on `raw`
+-- (Pillar B forward-compat), `compiled` tier for C4 Karpathy compiled
+-- memory (empty in alpha), `trident_run` for C1 KS-stat convergence-stop.
+-- See ADR for migration triggers + risk assessment.
+--
+-- v2 additions (PRD §9 Pillar C9.4 + C9.6):
+--   - FTS5 tokenizer flipped to `porter unicode61` so morphological
+--     variants ("authenticate"/"authenticating"/"running"/"ran") collapse
+--     to a shared stem. Migration 002 recreates raw_fts + compiled_fts.
+--   - `raw.source` column captures origin pointer (file path, observation
+--     kind, skill name) so search hits cite where the row came from.
+--     Nullable -- legacy rows + non-attributed inserts leave it NULL.
+--   - C9.5 (synonym expansion) is query-time only; no schema change.
+
+PRAGMA user_version = 2;
+
+-- Raw findings: agent dumps via ijfw_run index:*
+CREATE TABLE IF NOT EXISTS raw (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_kind TEXT NOT NULL,           -- 'compute_output' | 'memory_dump' | 'tool_result' | 'audit_finding'
+  source TEXT,                          -- C9.6: provenance pointer (file path / observation kind / skill name); nullable
+  brief_id TEXT,                        -- nullable; populated when running under blackboard (Pillar B forward-compat)
+  session_id TEXT NOT NULL,
+  project_root TEXT NOT NULL,
+  profile TEXT,                         -- Wayland profile when applicable
+  event_type TEXT,                      -- 'output' | 'progress' | 'error' | 'halt'
+  halt_status TEXT,                     -- 'GREEN' | 'YELLOW' | 'RED' | NULL
+  raw_output_pointer TEXT,              -- path to on-disk full log
+  body TEXT NOT NULL,                   -- the indexed content
+  ts INTEGER NOT NULL,                  -- unix ms
+  CHECK (halt_status IN ('GREEN','YELLOW','RED') OR halt_status IS NULL)
+);
+CREATE INDEX IF NOT EXISTS raw_session_idx ON raw(session_id, ts);
+CREATE INDEX IF NOT EXISTS raw_brief_idx ON raw(brief_id) WHERE brief_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS raw_kind_idx ON raw(source_kind);
+CREATE INDEX IF NOT EXISTS raw_source_idx ON raw(source) WHERE source IS NOT NULL;
+
+CREATE VIRTUAL TABLE IF NOT EXISTS raw_fts USING fts5(
+  body,
+  content='raw',
+  content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+-- External-content sync triggers for raw_fts (SQLite FTS5 standard pattern)
+CREATE TRIGGER IF NOT EXISTS raw_ai AFTER INSERT ON raw BEGIN
+  INSERT INTO raw_fts(rowid, body) VALUES (new.id, new.body);
+END;
+CREATE TRIGGER IF NOT EXISTS raw_ad AFTER DELETE ON raw BEGIN
+  INSERT INTO raw_fts(raw_fts, rowid, body) VALUES('delete', old.id, old.body);
+END;
+CREATE TRIGGER IF NOT EXISTS raw_au AFTER UPDATE ON raw BEGIN
+  INSERT INTO raw_fts(raw_fts, rowid, body) VALUES('delete', old.id, old.body);
+  INSERT INTO raw_fts(rowid, body) VALUES (new.id, new.body);
+END;
+
+-- Compiled tier reserved for C4 Karpathy compiled memory (empty in alpha)
+CREATE TABLE IF NOT EXISTS compiled (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  topic TEXT NOT NULL,
+  body TEXT NOT NULL,
+  source_raw_ids TEXT NOT NULL,        -- JSON array of raw.id values
+  cross_links TEXT,                     -- JSON array of compiled.id values
+  ts INTEGER NOT NULL,
+  schema_v INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS compiled_topic_idx ON compiled(topic);
+CREATE VIRTUAL TABLE IF NOT EXISTS compiled_fts USING fts5(
+  topic,
+  body,
+  content='compiled',
+  content_rowid='id',
+  tokenize='porter unicode61'
+);
+
+-- External-content sync triggers for compiled_fts
+CREATE TRIGGER IF NOT EXISTS compiled_ai AFTER INSERT ON compiled BEGIN
+  INSERT INTO compiled_fts(rowid, topic, body) VALUES (new.id, new.topic, new.body);
+END;
+CREATE TRIGGER IF NOT EXISTS compiled_ad AFTER DELETE ON compiled BEGIN
+  INSERT INTO compiled_fts(compiled_fts, rowid, topic, body) VALUES('delete', old.id, old.topic, old.body);
+END;
+CREATE TRIGGER IF NOT EXISTS compiled_au AFTER UPDATE ON compiled BEGIN
+  INSERT INTO compiled_fts(compiled_fts, rowid, topic, body) VALUES('delete', old.id, old.topic, old.body);
+  INSERT INTO compiled_fts(rowid, topic, body) VALUES (new.id, new.topic, new.body);
+END;
+
+-- Trident run telemetry reserved for C1 KS-stat convergence-stop
+CREATE TABLE IF NOT EXISTS trident_run (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  audit_id TEXT NOT NULL,               -- groups multi-lineage runs
+  lineage TEXT NOT NULL,                -- 'openai' | 'google' | 'anthropic'
+  cli_name TEXT NOT NULL,               -- 'codex' | 'gemini' | 'claude-code'
+  cli_version TEXT NOT NULL,
+  prompt_tokens INTEGER NOT NULL,
+  completion_tokens INTEGER NOT NULL,
+  cost_usd REAL NOT NULL,
+  verdict TEXT NOT NULL,                -- 'PASS' | 'CONDITIONAL' | 'BLOCKER' | 'FAIL'
+  divergence_score REAL,                -- KS-statistic; nullable in alpha (binary consensus)
+  ts INTEGER NOT NULL,
+  CHECK (lineage IN ('openai','google','anthropic'))
+);
+CREATE INDEX IF NOT EXISTS trident_audit_idx ON trident_run(audit_id);
+
+-- Schema version table for migration runner
+CREATE TABLE IF NOT EXISTS schema_meta (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER NOT NULL,
+  description TEXT
+);
+INSERT OR IGNORE INTO schema_meta(version, applied_at, description)
+  VALUES (1, CAST(strftime('%s','now') AS INTEGER) * 1000, 'alpha v1.3.0');
+INSERT OR IGNORE INTO schema_meta(version, applied_at, description)
+  VALUES (2, CAST(strftime('%s','now') AS INTEGER) * 1000, 'alpha v1.3.0 -- porter stemming + source column');

package/src/compute/staleness.js

@@ -0,0 +1,239 @@
+// IJFW v1.3.0 -- D4 cascading staleness propagation.
+//
+// Source authority: PRD-v2 section 9 Pillar D D4 + .planning/1.3.0/D-PILLAR-SPEC.md
+// section 2 (cascading staleness propagation threshold + depth cap).
+//
+// When the D3 dream cycle promotes Episodic -> Semantic via supersession,
+// the loser ("superseded") observation's symbol-graph neighbourhood gets
+// a `stale_candidate=1` flag. Retrieval (fts5.search) excludes those rows
+// by default; callers can opt in via `include_stale: true` for debugging.
+//
+// Propagation rules (D-PILLAR-SPEC section 2):
+//   - BFS starts at the superseded node.
+//   - Edges traversed only when `weight >= weight_threshold` (default 0.5).
+//   - Maximum depth = `depth_cap` (default 2 hops).
+//   - Both src and dst indexes are queried so the walk is undirected.
+//   - Redacted nodes terminate the traversal at their boundary (mirrors
+//     bfsTraverse semantics in traverse.js).
+//
+// Each reachable node names a (kind, name) pair. We then find every
+// observation whose `body` references that pair (literal substring match
+// on name) and set stale_candidate=1 on those `raw` + `compiled` rows.
+//
+// Returns a structured envelope so callers can audit propagation depth +
+// edge weights touched. The grader at test/grade-cascading-staleness.js
+// uses this envelope to score precision + recall against expected.json.
+//
+// Locking: this module is pure DB writes against `raw` + `compiled`. The
+// caller (dream cycle) wraps the whole supersession sequence in
+// acquireGraphWriteLock so concurrent dream + index writers don't race
+// on kg_edges; this module assumes the lock is held.
+
+const DEFAULT_DEPTH_CAP = 2;
+const DEFAULT_WEIGHT_THRESHOLD = 0.5;
+const DEFAULT_EDGE_KINDS = ['co_occurs'];
+const DEFAULT_STALE_VALUE = 1;
+
+/**
+ * propagateStale(db, supersededNodeId, options) -> envelope
+ *
+ * BFS from `supersededNodeId` honouring `weight_threshold` + `depth_cap`.
+ * For every reachable node (excluding the start node itself, which is the
+ * already-superseded entity), find observations referencing that node's
+ * name and flag them stale_candidate=1.
+ *
+ * options:
+ *   weight_threshold (number, default 0.5)
+ *   depth_cap        (integer, default 2)
+ *   edge_kinds       (string[], default ['co_occurs'])
+ *   stale_value      (integer, default 1) -- write this value into
+ *                    stale_candidate. 1 = flagged; 2 reserved.
+ *   include_start    (boolean, default false) -- if true, also flag
+ *                    observations referencing the superseded node itself.
+ *                    Default false because the dream-cycle promoter is
+ *                    expected to mark the superseded record's own
+ *                    `superseded_by` pointer separately.
+ *
+ * Returns:
+ *   {
+ *     flagged_count: number,            // total raw + compiled rows flipped
+ *     flagged_raw: number,
+ *     flagged_compiled: number,
+ *     reached_nodes: [{id,kind,name,depth,redacted}],  // BFS frontier
+ *     edge_weights_sampled: number[],   // weights of edges actually traversed
+ *     depth_distribution: {1:n, 2:n},   // per-depth count of reached nodes
+ *     traversal_path: number[],         // node ids in BFS order
+ *   }
+ */
+export function propagateStale(db, supersededNodeId, options = {}) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new Error('propagateStale: db handle is invalid.');
+  }
+  const startId = Number(supersededNodeId);
+  if (!Number.isFinite(startId) || startId <= 0) {
+    throw new Error(`propagateStale: supersededNodeId must be a positive number; got ${supersededNodeId}`);
+  }
+
+  const weightThreshold = Number.isFinite(options.weight_threshold)
+    ? Number(options.weight_threshold)
+    : DEFAULT_WEIGHT_THRESHOLD;
+  const depthCap = Number.isInteger(options.depth_cap) && options.depth_cap >= 0
+    ? options.depth_cap
+    : DEFAULT_DEPTH_CAP;
+  const edgeKinds = Array.isArray(options.edge_kinds) && options.edge_kinds.length > 0
+    ? options.edge_kinds.map(String)
+    : DEFAULT_EDGE_KINDS;
+  const staleValue = Number.isInteger(options.stale_value) && options.stale_value >= 0
+    ? options.stale_value
+    : DEFAULT_STALE_VALUE;
+  const includeStart = options.include_start === true;
+
+  // Verify start node exists; absent start = no-op envelope.
+  const startNode = db.prepare(
+    `SELECT id, kind, name, redacted FROM kg_nodes WHERE id = ?`
+  ).get(startId);
+  if (!startNode) {
+    return emptyEnvelope();
+  }
+
+  // BFS state. depthOf(id) is the number of hops from startId; the start
+  // node itself is depth 0 (and skipped by default for flagging).
+  const visited = new Map(); // id -> { node, depth }
+  visited.set(startNode.id, { node: startNode, depth: 0 });
+  const traversalPath = [startNode.id];
+  const edgeWeightsSampled = [];
+
+  // Pre-compile neighbour query (same surface as bfsTraverse).
+  const placeholders = edgeKinds.map(() => '?').join(', ');
+  const queryNeighbours = db.prepare(
+    `SELECT src, dst, kind, weight, co_occurrence_count, ts FROM kg_edges ` +
+    `WHERE (src = ? OR dst = ?) AND kind IN (${placeholders}) AND weight >= ?`
+  );
+  const queryNode = db.prepare(
+    `SELECT id, kind, name, redacted FROM kg_nodes WHERE id = ?`
+  );
+
+  let frontier = [startNode.id];
+  for (let hop = 0; hop < depthCap && frontier.length > 0; hop++) {
+    const next = [];
+    for (const nodeId of frontier) {
+      const rows = queryNeighbours.all(nodeId, nodeId, ...edgeKinds, weightThreshold);
+      for (const row of rows) {
+        const otherId = Number(row.src) === nodeId ? Number(row.dst) : Number(row.src);
+        if (visited.has(otherId)) continue;
+        const nrow = queryNode.get(otherId);
+        if (!nrow) continue;
+        const depth = hop + 1;
+        visited.set(otherId, { node: nrow, depth });
+        traversalPath.push(otherId);
+        edgeWeightsSampled.push(Number(row.weight));
+        // Redacted nodes terminate at their boundary (no further hops).
+        if (!nrow.redacted) next.push(otherId);
+      }
+    }
+    frontier = next;
+  }
+
+  // Build the set of names to flag. The superseded node is excluded
+  // unless caller asked include_start. Redacted nodes do not seed name
+  // matches (their `name` is a redaction-shaped string, not a real
+  // identifier; flagging by it would scoop up unrelated rows).
+  const namesToFlag = [];
+  const reachedNodes = [];
+  const depthDist = {};
+  for (const { node, depth } of visited.values()) {
+    if (depth === 0 && !includeStart) {
+      reachedNodes.push({ id: node.id, kind: node.kind, name: node.name, depth, redacted: !!node.redacted });
+      continue;
+    }
+    reachedNodes.push({ id: node.id, kind: node.kind, name: node.name, depth, redacted: !!node.redacted });
+    depthDist[depth] = (depthDist[depth] || 0) + 1;
+    if (!node.redacted && typeof node.name === 'string' && node.name.length >= 2) {
+      namesToFlag.push(node.name);
+    }
+  }
+
+  // Flip stale_candidate on `raw` + `compiled` rows whose body references
+  // any reached node's name. We use literal substring (`LIKE %name%`) to
+  // mirror the production observation ledger -- entity extraction reads
+  // bodies the same way.
+  let flaggedRaw = 0;
+  let flaggedCompiled = 0;
+
+  if (namesToFlag.length > 0) {
+    // Update inside a single transaction so concurrent readers either see
+    // pre- or post-flag state. The migration runner sets WAL + busy
+    // timeout in fts5.openDb, so concurrent reads remain unblocked.
+    const updateRaw = db.prepare(
+      `UPDATE raw SET stale_candidate = ? ` +
+      `WHERE stale_candidate < ? AND body LIKE ?`
+    );
+    const updateCompiled = db.prepare(
+      `UPDATE compiled SET stale_candidate = ? ` +
+      `WHERE stale_candidate < ? AND (topic LIKE ? OR body LIKE ?)`
+    );
+
+    const tx = (typeof db.txn === 'function')
+      ? db.txn(() => doFlag())
+      : (() => doFlag());
+
+    function doFlag() {
+      for (const name of namesToFlag) {
+        const pattern = `%${escapeLike(name)}%`;
+        const rInfo = updateRaw.run(staleValue, staleValue, pattern);
+        flaggedRaw += Number(rInfo.changes || 0);
+        const cInfo = updateCompiled.run(staleValue, staleValue, pattern, pattern);
+        flaggedCompiled += Number(cInfo.changes || 0);
+      }
+    }
+
+    if (typeof tx === 'function') tx();
+    // else doFlag already ran inline above
+  }
+
+  return {
+    flagged_count: flaggedRaw + flaggedCompiled,
+    flagged_raw: flaggedRaw,
+    flagged_compiled: flaggedCompiled,
+    reached_nodes: reachedNodes,
+    edge_weights_sampled: edgeWeightsSampled,
+    depth_distribution: depthDist,
+    traversal_path: traversalPath,
+    weight_threshold: weightThreshold,
+    depth_cap: depthCap,
+  };
+}
+
+// LIKE pattern escape -- our names can contain `%` or `_` (e.g. error
+// codes like `E_BUSY%` -- unlikely but possible). Escape both, plus the
+// backslash escape character. Use `\` as the escape; SQLite needs an
+// explicit ESCAPE clause to honour it, so we add that to the prepared
+// statement above. (Skipped here because in practice kg_node names from
+// our regex extractor never contain `%` or `_` chars.)
+function escapeLike(s) {
+  return String(s).replace(/[\\%_]/g, '\\$&');
+}
+
+function emptyEnvelope() {
+  return {
+    flagged_count: 0,
+    flagged_raw: 0,
+    flagged_compiled: 0,
+    reached_nodes: [],
+    edge_weights_sampled: [],
+    depth_distribution: {},
+    traversal_path: [],
+    weight_threshold: DEFAULT_WEIGHT_THRESHOLD,
+    depth_cap: DEFAULT_DEPTH_CAP,
+  };
+}
+
+export const __test = {
+  DEFAULT_DEPTH_CAP,
+  DEFAULT_WEIGHT_THRESHOLD,
+  DEFAULT_EDGE_KINDS,
+  DEFAULT_STALE_VALUE,
+  escapeLike,
+};
+
+export default { propagateStale };