@ijfw/memory-server 1.3.0

package/src/memory/search.js

@@ -0,0 +1,431 @@
+/**
+ * Memory search -- D-Pillar / D0 (IJFW v1.3.0).
+ *
+ * Tiered pipeline:
+ *   Hot   -- linear regex over markdown files (always available; the existing
+ *            v1.2 path). Used both as the source for FTS5 auto-index and as
+ *            the graceful-degradation fallback when FTS5 is unavailable or
+ *            returns no hits.
+ *   Warm  -- FTS5 over <repoRoot>/.ijfw/index/memory.db (porter unicode61).
+ *            Auto-indexes from the file list when the index is empty.
+ *            Synonym expansion via shared compute/synonyms.js so coding
+ *            shorthand ("db" -> "database", "auth" -> "authentication") fires
+ *            the same way as on the compute tier.
+ *
+ * Public surface preserved: searchMemory(q, files, limit) -> Array<result>
+ * (synchronous) so the dashboard /api/memory/search handler keeps working
+ * with no caller-side change. We achieve this by lazily resolving the
+ * better-sqlite3 driver via a top-level await at module load and using its
+ * synchronous open() inside searchMemory.
+ *
+ * Result-array decorations (non-enumerable):
+ *   - synonym_matches  -- { token: [expansions] } when expansion fired
+ *   - tier             -- 'warm-fts5' | 'hot-linear' | 'hot-linear-empty-fts5'
+ * Legacy callers see no shape change because Object.keys() on an array
+ * yields only the indices.
+ *
+ * Zero new deps. better-sqlite3 already ships from Phase 1.
+ */
+
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve, normalize, isAbsolute } from 'node:path';
+
+import { expandQuery } from '../compute/synonyms.js';
+
+const MAX_RESULTS  = 50;
+const SNIPPET_HALF = 60;
+const DB_FILENAME = 'memory.db';
+const INDEX_DIR_NAME = 'index';
+const IJFW_DIR_NAME = '.ijfw';
+
+// --- Driver bootstrap (top-level await; resolves once at module load) -----
+
+let DRIVER = null;
+try {
+  const mod = await import('better-sqlite3');
+  const Database = mod.default || mod;
+  DRIVER = { kind: 'better-sqlite3', Database };
+} catch {
+  DRIVER = null;
+}
+
+// Resolve migration modules synchronously at module load via top-level
+// await. Replayed inside searchMemory's sync path. Keep in lockstep with
+// ./migrations/.
+const MEMORY_MIGRATIONS = await loadMemoryMigrationsSync();
+
+async function loadMemoryMigrationsSync() {
+  const v1 = await import('./migrations/001-fts5-init.js');
+  const v2 = await import('./migrations/002-tier-semantic.js');
+  const v3 = await import('./migrations/003-stale-candidate.js');
+  return [
+    { version: v1.VERSION, description: v1.DESCRIPTION, up: v1.up },
+    { version: v2.VERSION, description: v2.DESCRIPTION, up: v2.up },
+    { version: v3.VERSION, description: v3.DESCRIPTION, up: v3.up },
+  ].sort((a, b) => a.version - b.version);
+}
+
+function highestMigrationVersion() {
+  if (!MEMORY_MIGRATIONS.length) return 0;
+  return MEMORY_MIGRATIONS[MEMORY_MIGRATIONS.length - 1].version;
+}
+
+// --- Snippet helper ---------------------------------------------------------
+
+function snippet(body, pattern) {
+  const idx = body.search(pattern);
+  if (idx === -1) return body.slice(0, 120).trim();
+  const start = Math.max(0, idx - SNIPPET_HALF);
+  const end   = Math.min(body.length, idx + SNIPPET_HALF + pattern.source.length);
+  let s = body.slice(start, end).replace(/\s+/g, ' ').trim();
+  if (start > 0)             s = '...' + s;
+  if (end < body.length)     s = s + '...';
+  return s;
+}
+
+// --- Hot tier (legacy linear regex; preserved for fallback) -----------------
+
+function searchLinear(q, files, limit) {
+  if (!q || !q.trim() || !files.length) return [];
+
+  const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let pattern;
+  try {
+    pattern = new RegExp(escaped, 'gi');
+  } catch {
+    return [];
+  }
+
+  const results = [];
+
+  for (const f of files) {
+    let body = '';
+    try {
+      body = existsSync(f.path) ? readFileSync(f.path, 'utf8') : '';
+    } catch { /* skip */ }
+
+    const titleMatches = (f.title.match(pattern) || []).length;
+    const bodyMatches  = (body.match(pattern) || []).length;
+    const total        = titleMatches + bodyMatches;
+    if (total === 0) continue;
+
+    pattern.lastIndex = 0;
+    const score = titleMatches * 3 + bodyMatches;
+
+    results.push({
+      path:     f.path,
+      relpath:  f.relpath,
+      title:    f.title,
+      snippet:  snippet(body, pattern),
+      score,
+    });
+
+    pattern.lastIndex = 0;
+    if (results.length >= limit * 2) break;
+  }
+
+  results.sort((a, b) => b.score - a.score);
+  return results.slice(0, limit);
+}
+
+// --- Warm tier (FTS5; synchronous via cached driver) ------------------------
+
+function resolveProjectRoot(raw) {
+  const v = raw || process.env.IJFW_PROJECT_DIR || process.cwd();
+  if (typeof v !== 'string' || !v) return null;
+  const abs = resolve(v);
+  const norm = normalize(abs);
+  if (!isAbsolute(norm)) return null;
+  return norm;
+}
+
+function dbPathFor(root) {
+  return join(root, IJFW_DIR_NAME, INDEX_DIR_NAME, DB_FILENAME);
+}
+
+function resolveIndexRoot(files) {
+  if (process.env.IJFW_PROJECT_DIR) return resolveProjectRoot(process.env.IJFW_PROJECT_DIR);
+  if (files && files.length > 0) {
+    for (const f of files) {
+      if (typeof f.path !== 'string') continue;
+      // Match both POSIX and Windows path separators around .ijfw segment.
+      const m = f.path.match(/[\\/]\.ijfw[\\/]/);
+      if (m) return f.path.slice(0, m.index);
+    }
+  }
+  return resolveProjectRoot(process.cwd());
+}
+
+function openMemoryDbSync(root) {
+  if (!DRIVER) return null;
+  if (!root) return null;
+
+  const filename = dbPathFor(root);
+  try {
+    const dir = dirname(filename);
+    if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const db = new DRIVER.Database(filename);
+    db.__ijfw_filename = filename;
+
+    try { db.exec('PRAGMA journal_mode = WAL'); } catch { /* default fine */ }
+    try { db.exec('PRAGMA synchronous = NORMAL'); } catch { /* default fine */ }
+    try { db.exec('PRAGMA busy_timeout = 5000'); } catch { /* default fine */ }
+
+    return db;
+  } catch {
+    return null;
+  }
+}
+
+function readUserVersion(db) {
+  try {
+    const row = db.prepare('PRAGMA user_version').get();
+    if (!row) return 0;
+    return Number(row.user_version ?? row.USER_VERSION ?? 0);
+  } catch {
+    return 0;
+  }
+}
+
+function runMemoryMigrationsSync(db, currentVersion, targetVersion) {
+  if (currentVersion >= targetVersion) return currentVersion;
+  for (const m of MEMORY_MIGRATIONS) {
+    if (m.version <= currentVersion || m.version > targetVersion) continue;
+    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');
+    } catch (err) {
+      try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+      throw err;
+    }
+  }
+  return targetVersion;
+}
+
+function autoIndex(db, files) {
+  let n = 0;
+  const txfn = db.transaction((batch) => {
+    const stmt = db.prepare(
+      'INSERT INTO memory_entries (body, source, session_id, created_at) VALUES (?, ?, ?, ?)'
+    );
+    for (const item of batch) {
+      stmt.run(item.body, item.source, null, item.created_at);
+      n++;
+    }
+  });
+
+  const batch = [];
+  const now = Date.now();
+  for (const f of files) {
+    if (typeof f.path !== 'string') continue;
+    if (!existsSync(f.path)) continue;
+    let body;
+    try { body = readFileSync(f.path, 'utf8'); } catch { continue; }
+    if (!body) continue;
+    batch.push({ body, source: f.relpath || f.path, created_at: now });
+  }
+  if (batch.length === 0) return 0;
+  try { txfn.immediate(batch); } catch { /* one bad batch should not abort the search */ }
+  return n;
+}
+
+// FTS5 search joined to the content table. When tier_semantic is provided,
+// the join filters rows by the D1 axis (working/episodic/semantic/
+// procedural/procedural_candidate). When undefined, all tiers return --
+// preserves the pre-D1 default. tier_semantic is a defensive enum check
+// inside this module; the SQL itself uses parameter binding so the value
+// can never form an injection vector.
+const VALID_TIER_SEMANTIC = new Set([
+  'working', 'episodic', 'semantic', 'procedural', 'procedural_candidate',
+]);
+
+function searchFts5(db, query, k, tier_semantic, include_stale) {
+  const limit = Math.min(Math.max(1, parseInt(k, 10) || 10), 1000);
+  const tierFilter = tier_semantic && VALID_TIER_SEMANTIC.has(tier_semantic);
+  // D4 GA-B2 retrieval guard: exclude rows with stale_candidate >= 1 by
+  // default; opt-in via include_stale=true (mirrors compute/fts5.js search).
+  // Pre-v3 dbs (no stale_candidate column) silently drop the WHERE filter
+  // so older callers and fixture dbs keep working.
+  const hasStaleCol = hasMemoryStaleColumn(db);
+  const staleClause = (!include_stale && hasStaleCol)
+    ? ' AND COALESCE(t.stale_candidate, 0) = 0'
+    : '';
+  const sql = `
+    SELECT t.id, t.body, t.source, t.session_id, t.created_at, t.tier_semantic,
+           bm25(memory_entries_fts) AS rank
+      FROM memory_entries_fts f
+      JOIN memory_entries t ON t.id = f.rowid
+     WHERE memory_entries_fts MATCH ?
+       ${tierFilter ? 'AND t.tier_semantic = ?' : ''}${staleClause}
+     ORDER BY rank ASC
+     LIMIT ?`;
+  return tierFilter
+    ? db.prepare(sql).all(query, tier_semantic, limit)
+    : db.prepare(sql).all(query, limit);
+}
+
+// Cache PRAGMA table_info lookups per-db so repeated search() calls don't
+// re-scan the schema. WeakMap keyed on the db handle gives us automatic
+// cleanup when the db is closed.
+const __memoryColumnCache = new WeakMap();
+function hasMemoryStaleColumn(db) {
+  let perDb = __memoryColumnCache.get(db);
+  if (!perDb) {
+    perDb = new Map();
+    __memoryColumnCache.set(db, perDb);
+  }
+  if (perDb.has('stale_candidate')) return perDb.get('stale_candidate');
+  let present = false;
+  try {
+    const rows = db.prepare(`PRAGMA table_info(memory_entries)`).all();
+    present = rows.some(r => String(r.name) === 'stale_candidate');
+  } catch { /* missing table -> treat column as absent */ }
+  perDb.set('stale_candidate', present);
+  return present;
+}
+
+function ftsRowToResult(row, fileBySource) {
+  const src = row.source || '';
+  const meta = fileBySource.get(src) || null;
+  const path = (meta && meta.path) || src;
+  const relpath = (meta && meta.relpath) || src;
+  const title = (meta && meta.title) || src.split('/').pop() || src;
+  const score = 100 - Number(row.rank || 0);
+  const text = String(row.body || '');
+  const snip = text.slice(0, 200).replace(/\s+/g, ' ').trim();
+  // tier_semantic surfaced per result so callers building tier-aware
+  // dashboards / consolidation views can read it without a separate
+  // lookup. Pre-D1 rows return 'working' from the column DEFAULT.
+  const tier_semantic = row.tier_semantic || 'working';
+  return { path, relpath, title, snippet: snip, score, tier_semantic };
+}
+
+function rowCount(db) {
+  try {
+    const row = db.prepare('SELECT COUNT(*) AS n FROM memory_entries').get();
+    return row ? Number(row.n) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// --- Public API -------------------------------------------------------------
+
+/**
+ * Search memory files for query string.
+ *
+ * Tries FTS5 (auto-indexes if empty) with synonym expansion, falls back to
+ * linear regex on empty/miss/error. Stays synchronous to preserve the
+ * existing public contract.
+ *
+ * D1 (tier_semantic) filter:
+ *   The fourth argument may be either an `options` object or a tier string
+ *   (legacy positional shorthand). Recognised:
+ *     - { tier_semantic: 'working' | 'episodic' | 'semantic'
+ *                       | 'procedural' | 'procedural_candidate' | undefined }
+ *     - undefined (default) returns all tiers -- pre-D1 behaviour preserved.
+ *   When the tier filter is set the warm-tier search restricts results;
+ *   the hot-linear fallback is unfiltered (D1 does not yet write tier
+ *   metadata into the markdown surface).
+ *
+ * @param {string} q
+ * @param {Array<{path,relpath,title,preview}>} files
+ * @param {number} limit
+ * @param {object|undefined} options
+ * @returns {Array<{path,relpath,title,snippet,score,tier_semantic}>}
+ */
+export function searchMemory(q, files, limit = MAX_RESULTS, options) {
+  if (!q || !q.trim() || !files || files.length === 0) return [];
+
+  // Normalise options. Allow undefined / { tier_semantic, include_stale } /
+  // a bare string (treated as the tier_semantic value) for ergonomic call
+  // sites. include_stale defaults to false -- D4 GA-B2 retrieval guard.
+  let tier_semantic;
+  let include_stale = false;
+  if (typeof options === 'string') {
+    tier_semantic = options;
+  } else if (options && typeof options === 'object') {
+    tier_semantic = options.tier_semantic;
+    include_stale = options.include_stale === true;
+  }
+
+  const { expanded, synonym_matches, applied } = expandQuery(q);
+
+  let warmHits = null;
+  let warmEmpty = false;
+  let db = null;
+
+  try {
+    const root = resolveIndexRoot(files);
+    db = openMemoryDbSync(root);
+
+    if (db) {
+      const target = highestMigrationVersion();
+      const current = readUserVersion(db);
+      if (current < target) {
+        runMemoryMigrationsSync(db, current, target);
+      } else if (current > target) {
+        // Newer schema -- refuse rather than downgrade. Legacy fallback.
+        try { db.close(); } catch { /* ignore */ }
+        db = null;
+      }
+
+      if (db) {
+        if (rowCount(db) === 0 && files.length > 0) {
+          autoIndex(db, files);
+        }
+        const ftsQuery = applied ? expanded : q;
+        let rows;
+        try {
+          rows = searchFts5(db, ftsQuery, limit, tier_semantic, include_stale);
+        } catch {
+          try { rows = searchFts5(db, q, limit, tier_semantic, include_stale); } catch { rows = []; }
+        }
+        if (rows.length > 0) {
+          const fileBySource = new Map();
+          for (const f of files) {
+            if (f.relpath) fileBySource.set(f.relpath, f);
+            if (f.path) fileBySource.set(f.path, f);
+          }
+          warmHits = rows.map(r => ftsRowToResult(r, fileBySource));
+        } else {
+          warmEmpty = true;
+        }
+      }
+    }
+  } catch {
+    warmHits = null;
+  } finally {
+    if (db) { try { db.close(); } catch { /* ignore */ } }
+  }
+
+  let results;
+  if (warmHits && warmHits.length > 0) {
+    results = warmHits.slice(0, limit);
+  } else if (tier_semantic) {
+    // Tier filter active and warm tier has no matches -- the hot-linear
+    // tier doesn't carry tier metadata so it can't honour the filter.
+    // Returning [] here keeps the contract honest ("only matching tier").
+    results = [];
+  } else {
+    results = searchLinear(q, files, limit);
+  }
+
+  Object.defineProperty(results, 'synonym_matches', {
+    value: applied ? synonym_matches : {},
+    enumerable: false,
+  });
+  Object.defineProperty(results, 'tier', {
+    value: warmHits && warmHits.length > 0
+      ? 'warm-fts5'
+      : (warmEmpty ? 'hot-linear-empty-fts5' : 'hot-linear'),
+    enumerable: false,
+  });
+  return results;
+}

package/src/memory/staleness.js

@@ -0,0 +1,237 @@
+// IJFW v1.3.0 -- D4 memory-side 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) + GA real fix-wave finding F2.
+//
+// PROBLEM (pre-F2): mcp-server/src/compute/staleness.js only mutates the
+// COMPUTE store (`raw` + `compiled` tables in compute.db). The memory store
+// has its own `memory_entries.stale_candidate` column (memory migration 003)
+// and the memory search filter excludes flagged rows by default, but
+// production never WRITES to that column. Memory rows that should be flagged
+// stale by the dream cycle's BFS propagation never get flagged in practice;
+// the column + filter are dead infrastructure.
+//
+// FIX: this module mirrors the compute-side `propagateStale` shape but
+// operates on `memory_entries`. It is invoked by
+// `mcp-server/src/dream/staleness-wiring.js` AFTER `propagateStale` runs
+// against the compute db, so a single supersession event flags BOTH
+// stores in the same dream cycle.
+//
+// The COMPUTE kg graph is the single source of truth for entity relations
+// (per architecture: memory.indexEntry fires `autoIndexGraphFromMemoryBody`
+// against the SAME compute kg). Memory propagation walks the same BFS
+// surface but resolves matching rows by literal substring against
+// `memory_entries.body`, mirroring `compute.staleness.js`'s name-pattern
+// approach.
+//
+// Read-only access to compute kg: this module accepts a SECOND db handle
+// (`computeDb`) opened by the caller. We never write the compute db here;
+// we only walk kg_nodes + kg_edges to discover the BFS frontier. Writes
+// land on `memory_entries.stale_candidate` only.
+//
+// Locking: caller holds .graph-write.lock for the dream cycle (per
+// staleness-wiring.js header). This module performs reads against compute
+// kg + writes against memory; the lock keeps concurrent kg writers out
+// while we walk.
+
+const DEFAULT_DEPTH_CAP = 2;
+const DEFAULT_WEIGHT_THRESHOLD = 0.5;
+const DEFAULT_EDGE_KINDS = ['co_occurs'];
+const DEFAULT_STALE_VALUE = 1;
+
+/**
+ * propagateStaleMemory(memDb, computeDb, supersededNodeId, options) -> envelope
+ *
+ * Walk the COMPUTE kg graph from `supersededNodeId` (BFS, weight + depth
+ * gated per D-PILLAR-SPEC §2). For every reachable node (excluding the
+ * start node by default), find `memory_entries` rows whose `body` mentions
+ * the node's name and flip their `stale_candidate` column to `staleValue`.
+ *
+ * options:
+ *   weight_threshold (number, default 0.5)
+ *   depth_cap        (integer, default 2)
+ *   edge_kinds       (string[], default ['co_occurs'])
+ *   stale_value      (integer, default 1)
+ *   include_start    (boolean, default false)
+ *
+ * Returns:
+ *   {
+ *     flagged_count: number,            // memory_entries rows flipped
+ *     reached_nodes: [{id,kind,name,depth,redacted}],
+ *     edge_weights_sampled: number[],
+ *     depth_distribution: {1:n, 2:n},
+ *     traversal_path: number[],
+ *     weight_threshold: number,
+ *     depth_cap: number,
+ *   }
+ */
+export function propagateStaleMemory(memDb, computeDb, supersededNodeId, options = {}) {
+  if (!memDb || typeof memDb.prepare !== 'function') {
+    throw new Error('propagateStaleMemory: memDb handle is invalid.');
+  }
+  if (!computeDb || typeof computeDb.prepare !== 'function') {
+    throw new Error('propagateStaleMemory: computeDb handle is invalid.');
+  }
+  const startId = Number(supersededNodeId);
+  if (!Number.isFinite(startId) || startId <= 0) {
+    throw new Error(`propagateStaleMemory: 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 in compute kg.
+  const startNode = computeDb.prepare(
+    `SELECT id, kind, name, redacted FROM kg_nodes WHERE id = ?`
+  ).get(startId);
+  if (!startNode) {
+    return emptyEnvelope();
+  }
+
+  // BFS over the compute kg (read-only).
+  const visited = new Map();
+  visited.set(startNode.id, { node: startNode, depth: 0 });
+  const traversalPath = [startNode.id];
+  const edgeWeightsSampled = [];
+
+  const placeholders = edgeKinds.map(() => '?').join(', ');
+  const queryNeighbours = computeDb.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 = computeDb.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));
+        if (!nrow.redacted) next.push(otherId);
+      }
+    }
+    frontier = next;
+  }
+
+  // Build the set of names to flag against memory_entries.
+  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);
+    }
+  }
+
+  // Defence: if the memory schema predates migration 003, the column
+  // doesn't exist; degrade silently rather than throw. (Production callers
+  // run migrations before opening; tests that bypass openDb may not.)
+  if (!hasStaleCandidateColumn(memDb)) {
+    return {
+      flagged_count: 0,
+      reached_nodes: reachedNodes,
+      edge_weights_sampled: edgeWeightsSampled,
+      depth_distribution: depthDist,
+      traversal_path: traversalPath,
+      weight_threshold: weightThreshold,
+      depth_cap: depthCap,
+    };
+  }
+
+  let flagged = 0;
+  if (namesToFlag.length > 0) {
+    const updateMem = memDb.prepare(
+      `UPDATE memory_entries SET stale_candidate = ? ` +
+      `WHERE COALESCE(stale_candidate, 0) < ? AND body LIKE ?`
+    );
+
+    const txWrap = (typeof memDb.transaction === 'function')
+      ? memDb.transaction(() => doFlag())
+      : (typeof memDb.txn === 'function' ? memDb.txn(() => doFlag()) : null);
+
+    function doFlag() {
+      for (const name of namesToFlag) {
+        const pattern = `%${escapeLike(name)}%`;
+        const info = updateMem.run(staleValue, staleValue, pattern);
+        flagged += Number(info.changes || 0);
+      }
+    }
+
+    if (typeof txWrap === 'function') txWrap();
+    else doFlag();
+  }
+
+  return {
+    flagged_count: flagged,
+    reached_nodes: reachedNodes,
+    edge_weights_sampled: edgeWeightsSampled,
+    depth_distribution: depthDist,
+    traversal_path: traversalPath,
+    weight_threshold: weightThreshold,
+    depth_cap: depthCap,
+  };
+}
+
+// LIKE escape -- mirrors compute.staleness.js.
+function escapeLike(s) {
+  return String(s).replace(/[\\%_]/g, '\\$&');
+}
+
+function hasStaleCandidateColumn(db) {
+  try {
+    const rows = db.prepare(`PRAGMA table_info(memory_entries)`).all();
+    return rows.some(r => String(r.name) === 'stale_candidate');
+  } catch {
+    return false;
+  }
+}
+
+function emptyEnvelope() {
+  return {
+    flagged_count: 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,
+  hasStaleCandidateColumn,
+};
+
+export default { propagateStaleMemory };