@ijfw/memory-server 1.3.0

package/src/memory/fts5.js

@@ -0,0 +1,349 @@
+// IJFW v1.3.0 -- D-Pillar / D0 memory FTS5 layer.
+//
+// Per-project SQLite db at <projectRoot>/.ijfw/index/memory.db with FTS5
+// virtual table mirroring `memory_entries`. This is the warm tier of the
+// memory pipeline (hot = markdown files; warm = FTS5; cold = vectors).
+// Schema is owned by ./schema.sql and applied via ./migration-runner.js.
+//
+// Mirrors src/compute/fts5.js patterns:
+//   - WAL journal mode for concurrent readers
+//   - PRAGMA busy_timeout = 5000 + BEGIN IMMEDIATE for racing writers
+//   - PRAGMA quick_check post-write enforces integrity
+//
+// Security model (D-PILLAR-SPEC §12, real fix-wave C3):
+//   indexEntry runs `redactSecrets()` over `entry.body` AND `entry.source`
+//   BEFORE the INSERT. The scrub is the security gate that ensures secret-
+//   shaped tokens are never persisted in `memory_entries`, the FTS index,
+//   or fed forward into the D2 graph layer. Default on; opt out only via
+//   IJFW_INGEST_SCRUB=0 for local debugging. Source is scrubbed because
+//   while file paths are typical, callers may pass arbitrary text-of-origin
+//   strings (chat title, tool result label, etc.) that could include keys.
+//
+// Public surface is intentionally narrow:
+//   - openDb(projectRoot)       -> handle
+//   - indexEntry(db, entry)     -> { id }
+//   - searchFts5(db, q, k)      -> [{id, body, source, session_id, created_at, rank}]
+//   - closeDb(db)
+//
+// Driver loader uses better-sqlite3 (already a hard dep in package.json).
+
+import { existsSync, mkdirSync } from 'fs';
+import { join, resolve, normalize, isAbsolute, dirname } from 'path';
+import {
+  runMigrations,
+  highestKnownVersion,
+  SchemaVersionError,
+} from './migration-runner.js';
+import { autoIndexGraphFromMemoryBody } from '../compute/graph-auto-index.js';
+import { redactSecrets } from '../redactor.js';
+
+// D-PILLAR-SPEC §12 ingest scrub gate. Default-on; the only escape hatch
+// is the IJFW_INGEST_SCRUB=0 env var, used for local debugging only and
+// never a shipping posture. Read on every indexEntry so test harnesses
+// can flip it without re-importing.
+function ingestScrubEnabled() {
+  return process.env.IJFW_INGEST_SCRUB !== '0';
+}
+
+export { SchemaVersionError };
+
+export class MemoryDbError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MemoryDbError';
+  }
+}
+
+export class MemoryIntegrityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MemoryIntegrityError';
+  }
+}
+
+const DB_FILENAME = 'memory.db';
+const INDEX_DIR_NAME = 'index';
+const IJFW_DIR_NAME = '.ijfw';
+
+// Thin wrapper around the sqlite driver's multi-statement runner so call
+// sites stay uniform between better-sqlite3 and any future shim.
+function runSql(db, sql) {
+  const fn = db.exec.bind(db);
+  return fn(sql);
+}
+
+// --- Driver loader -----------------------------------------------------------
+//
+// Shipping path: better-sqlite3. Already pinned by package.json so this is
+// a hot path. We do NOT duplicate the node:sqlite escape hatch from
+// src/compute/fts5.js -- the compute tier owns the dev-only fallback; the
+// memory tier is shipping-only.
+
+async function loadDriver() {
+  const mod = await import('better-sqlite3');
+  const Database = mod.default || mod;
+  return {
+    kind: 'better-sqlite3',
+    open(filename) {
+      const db = new Database(filename);
+      // BEGIN IMMEDIATE invariant: write transactions must acquire RESERVED
+      // at txn start, not at first INSERT. Paired with busy_timeout=5000
+      // below this converts racing writers from a SQLITE_BUSY explosion
+      // into a clean queue. Phase 5 caught this on the compute side; the
+      // memory tier ships with it correct from day one.
+      db.txn = (fn) => {
+        const wrapped = db.transaction(fn);
+        if (wrapped && typeof wrapped.immediate === 'function') {
+          return wrapped.immediate;
+        }
+        return (...args) => {
+          runSql(db, 'BEGIN IMMEDIATE');
+          try {
+            const r = fn(...args);
+            runSql(db, 'COMMIT');
+            return r;
+          } catch (err) {
+            try { runSql(db, 'ROLLBACK'); } catch { /* ignore */ }
+            throw err;
+          }
+        };
+      };
+      return db;
+    },
+  };
+}
+
+// --- Path resolution ---------------------------------------------------------
+
+function resolveProjectRoot(projectRoot) {
+  const raw = projectRoot || process.env.IJFW_PROJECT_DIR || process.cwd();
+  if (typeof raw !== 'string' || !raw) {
+    throw new MemoryDbError('Project root must be a non-empty string.');
+  }
+  const abs = resolve(raw);
+  const norm = normalize(abs);
+  if (!isAbsolute(norm)) {
+    throw new MemoryDbError(`Project root resolves to non-absolute path: ${raw}`);
+  }
+  return norm;
+}
+
+export function dbPathFor(projectRoot) {
+  const root = resolveProjectRoot(projectRoot);
+  return join(root, IJFW_DIR_NAME, INDEX_DIR_NAME, DB_FILENAME);
+}
+
+function ensureDbDir(filename) {
+  const dir = dirname(filename);
+  if (dir && !existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+// --- Public API --------------------------------------------------------------
+
+// Open or create the per-project memory db. On a fresh file, applies every
+// migration up to highestKnownVersion(). On an existing file, refuses to
+// operate if user_version is higher than this build supports.
+export async function openDb(projectRoot) {
+  const filename = dbPathFor(projectRoot);
+  ensureDbDir(filename);
+
+  const driver = await loadDriver();
+  const db = driver.open(filename);
+  db.__ijfw_driver = driver.kind;
+  db.__ijfw_filename = filename;
+
+  try { runSql(db, 'PRAGMA journal_mode = WAL'); } catch { /* default fine */ }
+  try { runSql(db, 'PRAGMA synchronous = NORMAL'); } catch { /* default fine */ }
+  try { runSql(db, 'PRAGMA busy_timeout = 5000'); } catch { /* default fine */ }
+
+  const target = await highestKnownVersion();
+  const current = readUserVersion(db);
+
+  if (current > target) {
+    db.close();
+    throw new SchemaVersionError(
+      `Memory db schema version ${current} at ${filename} is newer than this build supports (max ${target}). ` +
+      `Refusing to downgrade.`
+    );
+  }
+  if (current < target) {
+    await runMigrations(db, current, target);
+  }
+  return db;
+}
+
+function readUserVersion(db) {
+  const row = db.prepare('PRAGMA user_version').get();
+  if (!row) return 0;
+  return Number(row.user_version ?? row.USER_VERSION ?? 0);
+}
+
+// Insert one row into memory_entries inside a BEGIN IMMEDIATE transaction,
+// then run PRAGMA quick_check on the whole db. Throws MemoryIntegrityError
+// on anything other than 'ok'. Returns { id } of the inserted row.
+//
+// Caller passes { body, source?, session_id? }. created_at is set here
+// (unix ms) so callers don't have to remember the convention.
+export function indexEntry(db, entry) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new MemoryDbError('indexEntry: db handle is invalid.');
+  }
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new MemoryDbError('indexEntry: entry must be a plain object.');
+  }
+  if (typeof entry.body !== 'string' || entry.body.length === 0) {
+    throw new MemoryDbError('indexEntry: entry.body must be a non-empty string.');
+  }
+  // D-PILLAR-SPEC §12 ingest scrub gate. Replace `body` and `source`
+  // with their redacted forms BEFORE the INSERT, so the FTS index, the
+  // graph auto-index pass below, and any downstream reader only ever
+  // see scrubbed text. After this branch `entry` is unchanged for the
+  // caller; we work off a local copy.
+  const scrub = ingestScrubEnabled();
+  const safeBody = scrub ? redactSecrets(entry.body) : entry.body;
+  const safeSource = entry.source != null
+    ? (scrub ? redactSecrets(String(entry.source)) : String(entry.source))
+    : null;
+  const row = {
+    body: safeBody,
+    source: safeSource,
+    session_id: entry.session_id != null ? String(entry.session_id) : null,
+    created_at: typeof entry.created_at === 'number' ? entry.created_at : Date.now(),
+  };
+
+  let inserted;
+  const tx = db.txn(() => {
+    const stmt = db.prepare(
+      'INSERT INTO memory_entries (body, source, session_id, created_at) VALUES (?, ?, ?, ?)'
+    );
+    const info = stmt.run(row.body, row.source, row.session_id, row.created_at);
+    inserted = {
+      id: info && info.lastInsertRowid != null ? Number(info.lastInsertRowid) : null,
+    };
+    const qc = db.prepare('PRAGMA quick_check').get();
+    const status = qc && (qc.quick_check ?? qc.QUICK_CHECK);
+    if (status !== 'ok') {
+      throw new MemoryIntegrityError(
+        `PRAGMA quick_check failed after insert into memory_entries: ${status || '(no result)'}.`
+      );
+    }
+  });
+  tx();
+
+  // GA-B3: fire D2 graph auto-population on memory ingest. The graph
+  // lives in the compute db at the same projectRoot, so we open compute
+  // on demand. Async-but-fire-and-forget: the indexEntry contract stays
+  // synchronous (callers don't see a Promise), and a graph failure never
+  // affects ingest correctness. Tests that need to await the auto-index
+  // promise can read __lastAutoIndexPromise (set below for diagnostic
+  // visibility only).
+  try {
+    const ts = row.created_at;
+    const sessionId = row.session_id;
+    const body = row.body;
+    const p = autoIndexGraphFromMemoryBody({ memoryDb: db, body, sessionId, ts })
+      .catch(() => null);
+    __lastAutoIndexPromise = p;
+  } catch {
+    // never throw out of indexEntry due to auto-index
+  }
+
+  return inserted;
+}
+
+// Diagnostic hook for tests -- holds the most recent auto-index promise
+// from indexEntry so end-to-end tests can `await __getLastAutoIndexPromise()`
+// before asserting on graph state. Production callers do not read this.
+let __lastAutoIndexPromise = null;
+export function __getLastAutoIndexPromise() {
+  return __lastAutoIndexPromise;
+}
+
+// FTS5 search against memory_entries_fts. Returns top-k content rows with
+// a `rank` column (bm25; lower is better). Empty/whitespace queries return
+// an empty array. Caller is responsible for sanitising user-supplied
+// queries (FTS5 syntax errors throw -- caught and reported here).
+//
+// opts.include_stale (D4 GA-B2): when false (default), rows with
+// stale_candidate >= 1 are excluded so cascading-staleness flags actually
+// gate retrieval. When true, all rows return (debug + grader path).
+// Pre-v3 dbs (no stale_candidate column) silently drop the WHERE filter
+// so back-compat is preserved.
+export function searchFts5(db, query, k = 10, opts = {}) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new MemoryDbError('searchFts5: db handle is invalid.');
+  }
+  if (typeof query !== 'string' || query.trim().length === 0) {
+    return [];
+  }
+  const limit = Math.min(Math.max(1, parseInt(k, 10) || 10), 1000);
+  const includeStale = opts && opts.include_stale === true;
+  const hasStaleCol = tableHasColumn(db, 'memory_entries', 'stale_candidate');
+  const staleClause = (!includeStale && hasStaleCol)
+    ? ' AND COALESCE(t.stale_candidate, 0) = 0'
+    : '';
+  const sql = `
+    SELECT t.id, t.body, t.source, t.session_id, t.created_at,
+           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 ?${staleClause}
+     ORDER BY rank ASC
+     LIMIT ?`;
+  try {
+    return db.prepare(sql).all(query, limit);
+  } catch (err) {
+    throw new MemoryDbError(`searchFts5 failed: ${err.message}`);
+  }
+}
+
+// Cached PRAGMA table_info lookups per-db so repeated calls don't re-scan.
+const __memTableInfoCache = new WeakMap();
+function tableHasColumn(db, table, column) {
+  let perDb = __memTableInfoCache.get(db);
+  if (!perDb) {
+    perDb = new Map();
+    __memTableInfoCache.set(db, perDb);
+  }
+  const key = `${table}.${column}`;
+  if (perDb.has(key)) return perDb.get(key);
+  let present = false;
+  try {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    present = rows.some(r => String(r.name) === column);
+  } catch { /* missing table -> treat column as absent */ }
+  perDb.set(key, present);
+  return present;
+}
+
+// Total row count -- cheap helper used by callers that want to decide
+// whether the index is empty (and thus needs an auto-rebuild from hot tier).
+export function rowCount(db) {
+  if (!db || typeof db.prepare !== 'function') return 0;
+  try {
+    const row = db.prepare('SELECT COUNT(*) AS n FROM memory_entries').get();
+    return row ? Number(row.n) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// Clean close. Tolerates double-close.
+export function closeDb(db) {
+  if (!db) return;
+  try { db.close(); } catch { /* already closed or driver-specific noop */ }
+}
+
+export default {
+  openDb,
+  indexEntry,
+  searchFts5,
+  rowCount,
+  closeDb,
+  dbPathFor,
+  MemoryDbError,
+  MemoryIntegrityError,
+  SchemaVersionError,
+};

package/src/memory/migration-runner.js

@@ -0,0 +1,116 @@
+// IJFW v1.3.0 -- migration runner for the memory db.
+//
+// Mirrors src/compute/migration-runner.js shape so future structural
+// alignment between the two tiers stays trivial. The memory db has its
+// OWN user_version sequence -- it does not share state with the compute
+// db at <projectRoot>/.ijfw/index/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
+// BEGIN IMMEDIATE transaction (per the Phase 5 fix that landed in the
+// compute migration runner -- racing writers must serialise via the
+// RESERVED lock at txn start instead of upgrading mid-txn).
+
+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(`Memory migration ${f} is missing VERSION or up().`);
+    }
+    out.push({
+      file: f,
+      version: mod.VERSION,
+      description: mod.DESCRIPTION || '',
+      up: mod.up,
+    });
+  }
+  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 memory 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(
+      `Memory 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) {
+    // BEGIN IMMEDIATE acquires the write lock at transaction start. Plain
+    // BEGIN (deferred) lets two concurrent writers both enter their migration
+    // tx and then the loser gets SQLITE_BUSY when it tries to upgrade. The
+    // compute migration runner caught this in Phase 5; the memory runner
+    // ships with the fix in place from day one.
+    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 { /* nothing */ }
+      throw new Error(`Memory migration ${m.file} (v${m.version}) failed: ${err.message}`);
+    }
+  }
+  return lastApplied;
+}
+
+export default { runMigrations, highestKnownVersion, SchemaVersionError };

package/src/memory/migrations/001-fts5-init.js

@@ -0,0 +1,26 @@
+// IJFW v1.3.0 -- memory migration 001: apply schema.sql on a fresh memory db.
+//
+// Idempotent (CREATE TABLE IF NOT EXISTS + INSERT OR IGNORE). Runs inside
+// the migration runner's BEGIN IMMEDIATE transaction so a crash mid-apply
+// rolls back to user_version 0.
+//
+// Source of truth for DDL: ../schema.sql.
+
+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 = 'memory v1.3.0 -- memory_entries + memory_entries_fts (porter unicode61)';
+
+export function up(db) {
+  const sql = readFileSync(SCHEMA_PATH, 'utf-8');
+  // The sqlite driver 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/memory/migrations/002-tier-semantic.js

@@ -0,0 +1,60 @@
+// IJFW v1.3.0 -- memory migration 002: 4-tier semantic axis (D1).
+//
+// Source authority: PRD-v2 §9 Pillar D D1 + .planning/1.3.0/D-PILLAR-SPEC.md §1
+// (tier promotion rules).
+//
+// Adds `tier_semantic` column ORTHOGONAL to existing tier_access (hot/warm/cold
+// in the storage layer). Two axes, both queryable:
+//   - tier_access    : hot=md files / warm=this FTS5 db / cold=vectors (deferred)
+//   - tier_semantic  : working / episodic / semantic / procedural
+//
+// ADD-ONLY semantics. Default 'working' protects every legacy row -- existing
+// memory_entries pre-D1 are by definition session-bound observations, which is
+// the exact definition of Working in D-PILLAR-SPEC §1. Promotion to other
+// tiers happens via tier-promotion.js (separate module, not this migration).
+//
+// CREATE INDEX on (tier_semantic, created_at) so the search filter
+// `WHERE tier_semantic = ? ORDER BY created_at DESC` is index-served at
+// any scale.
+//
+// Crash safety: migration runner wraps the whole up() in BEGIN IMMEDIATE.
+// If ALTER TABLE or CREATE INDEX fails the txn rolls back and user_version
+// stays at 1.
+
+export const VERSION = 2;
+export const DESCRIPTION = 'memory v1.3.0 -- tier_semantic axis (working/episodic/semantic/procedural)';
+
+export function up(db) {
+  // ALTER TABLE ADD COLUMN with a TEXT DEFAULT is constant-time in SQLite
+  // (writes the default into the schema, not into existing rows). Legacy
+  // rows on read return 'working'. Composite index supports tier-filtered
+  // scans without a table rewrite.
+  if (!hasColumn(db, 'memory_entries', 'tier_semantic')) {
+    runDdl(db, `ALTER TABLE memory_entries ADD COLUMN tier_semantic TEXT DEFAULT 'working'`);
+  }
+
+  // Composite index (tier_semantic, created_at) supports the canonical
+  // tier-filtered scan: pick a tier, sort by recency. SQLite uses the
+  // index for both the equality filter and the ORDER BY.
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS memory_entries_tier_semantic_idx ` +
+    `ON memory_entries(tier_semantic, created_at)`
+  );
+}
+
+// runDdl -- thin wrapper so the migration reads with a single verb that
+// mirrors compute/migrations/002. Runs multi-statement DDL inside the
+// migration runner's BEGIN IMMEDIATE transaction.
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+// hasColumn -- defensive check so an out-of-band re-application doesn't
+// trip ADD COLUMN's "duplicate column" error. Mirrors the helper in
+// compute/migrations/002-porter-stemming-source.js.
+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/memory/migrations/003-stale-candidate.js

@@ -0,0 +1,60 @@
+// IJFW v1.3.0 -- memory migration 003: stale_candidate guard column (D4 wiring).
+//
+// Source authority: PRD-v2 section 9 Pillar D D4 + .planning/1.3.0/D-PILLAR-SPEC.md
+// section 2 (cascading staleness propagation) + GA fix-wave finding GA-B2.
+//
+// Adds the `stale_candidate` column to memory_entries so the D4 cascading
+// staleness propagation can flag entries whose semantic neighbourhood has
+// been superseded. Memory-side search filters stale rows by default,
+// mirroring the compute-side filter that landed in compute migration 005.
+//
+// Column semantics (identical to compute migration 005):
+//   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:
+//   memory_entries_stale_candidate_idx -- partial index on stale_candidate > 0
+//                                          so the search() WHERE filter is
+//                                          fast on the common case (most
+//                                          rows fresh).
+//
+// ADD-ONLY: no column drops, no FTS5 touch. The FTS5 mirror is content-
+// table backed and indexes only `body`, so adding a non-FTS column never
+// touches 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 = 'memory v1.3.0 -- stale_candidate guard column (D4 retrieval suppression)';
+
+export function up(db) {
+  if (!hasColumn(db, 'memory_entries', 'stale_candidate')) {
+    runDdl(db, `ALTER TABLE memory_entries ADD COLUMN stale_candidate INTEGER DEFAULT 0`);
+  }
+  runDdl(db,
+    `CREATE INDEX IF NOT EXISTS memory_entries_stale_candidate_idx ` +
+    `ON memory_entries(stale_candidate) WHERE stale_candidate > 0`
+  );
+}
+
+// runDdl -- thin wrapper that runs multi-statement DDL via the sqlite
+// driver's .exec method. Mirrors helpers in earlier migrations.
+function runDdl(db, sql) {
+  return db.exec(sql);
+}
+
+// hasColumn -- defence against re-application; mirrors helper from 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 };