moflo 4.9.36 → 4.10.0

package/bin/lib/get-backend.mjs

@@ -0,0 +1,306 @@
+/**
+ * Pure-JS factory for moflo.db low-level SQL handles — JS twin of the
+ * `openDaemonDatabase` factory in `src/cli/memory/daemon-backend.ts`. Every
+ * `bin/` script that opens `.moflo/moflo.db` MUST go through {@link openBackend}
+ * so the engine choice stays consistent with the rest of the runtime.
+ *
+ * Backend selection: always `node:sqlite` (Phase 5 / #1084 — sql.js has been
+ * deleted from the package). The `resolveBackend()` shim is retained because
+ * a handful of tests still pass an explicit `backend` option; it now validates
+ * the value but only honours `'node-sqlite'`.
+ *
+ * Engine surface — the handle exposes the **sql.js low-level Statement API**
+ * because every existing bin/ caller was written against it (db.prepare/
+ * stmt.bind/step/getAsObject/free/run, db.run/exec, db.export-via-save,
+ * db.close). For `node:sqlite`, the adapter emulates `stmt.bind()/step()/
+ * getAsObject()` via `StatementSync.iterate()` so callers don't refactor
+ * their loops.
+ *
+ * Persistence semantics:
+ *   - node:sqlite — writes through the OS file handle under WAL; `save()` is
+ *     a no-op kept for API parity. WAL pragmas (`journal_mode=WAL`,
+ *     `synchronous=NORMAL`, `busy_timeout=15000`) are set on first open per
+ *     Phase 0 spike (#1079) and Phase 1 backend (#1080).
+ *
+ * @module bin/lib/get-backend
+ */
+
+// MUST come before any direct/transitive `node:sqlite` import below — the
+// node:sqlite module fires ExperimentalWarning exactly once per process on
+// first load, and once it fires there's no way to scrub it from stderr.
+import './suppress-sqlite-warning.mjs';
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { memoryDbPath } from './moflo-paths.mjs';
+
+export const BACKEND_NODE_SQLITE = 'node-sqlite';
+
+/**
+ * Resolve the configured backend. Phase 5 (#1084) deleted the sql.js path,
+ * so this always returns `node-sqlite`. The `opts.backend` parameter is kept
+ * for API compatibility — anything else throws so a stale caller asking for
+ * sql.js surfaces a clear error rather than silently dropping to the wrong
+ * engine.
+ *
+ * @param {{ backend?: string }} [opts]
+ * @returns {'node-sqlite'}
+ */
+export function resolveBackend(opts = {}) {
+  if (opts.backend && opts.backend !== BACKEND_NODE_SQLITE) {
+    throw new Error(
+      `Unknown backend "${opts.backend}". moflo only supports "node-sqlite"; ` +
+      `sql.js was retired in Phase 5 (#1084).`,
+    );
+  }
+  return BACKEND_NODE_SQLITE;
+}
+
+function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Open a low-level SQL backend handle. Defaults to `.moflo/moflo.db` under
+ * `projectRoot`; pass `opts.dbPath` to point at a different file (used by
+ * migrations that touch sibling DBs).
+ *
+ * @param {string} projectRoot
+ * @param {{
+ *   backend?: 'node-sqlite',
+ *   create?: boolean,
+ *   readOnly?: boolean,
+ *   dbPath?: string,
+ * }} [opts]
+ * @returns {Promise<object>} backend handle (see module doc)
+ */
+export async function openBackend(projectRoot, opts = {}) {
+  const dbPath = opts.dbPath || memoryDbPath(projectRoot);
+  resolveBackend(opts); // throws on stale sql.js callers
+  ensureDir(dbPath);
+  return openNodeSqlite(dbPath, opts);
+}
+
+// ---------------------------------------------------------------------------
+// node:sqlite adapter — the only backend as of Phase 5 (#1084)
+// ---------------------------------------------------------------------------
+
+// Module-scope guard so we only fire the network-FS warning once per path
+// per process — the indexer + daemon + bin/ scripts all open the same DB and
+// we don't want N copies of the same message in one session.
+const _networkFsWarnedPaths = new Set();
+
+async function openNodeSqlite(dbPath, opts) {
+  const { DatabaseSync } = await import('node:sqlite');
+  const readOnly = opts.readOnly === true;
+  const db = new DatabaseSync(dbPath, { readOnly });
+  if (!readOnly) {
+    // Close the handle on any PRAGMA failure — node:sqlite opens forgivingly
+    // (even non-SQLite files succeed in the constructor) and a PRAGMA that
+    // throws later would otherwise leak the file handle across processes
+    // (visible on Windows as EPERM on subsequent rmdir of the parent).
+    try {
+      // WAL trinity validated by Phase 0 spike (#1079) and Phase 1 backend.
+      // busy_timeout MUST be set BEFORE journal_mode=WAL — the WAL pragma
+      // briefly takes an EXCLUSIVE lock, and concurrent openers (parallel
+      // doctor probes, indexer subprocess, daemon bridge init) otherwise hit
+      // "database is locked" with no retry budget. See #1097.
+      // 15000ms — sized for the consumer-smoke worst case where a
+      // background indexer holds a write lock for 5–8s during its first
+      // full-tree pass after `npm install`. See daemon-backend.ts twin for
+      // the full rationale (#1098).
+      db.exec('PRAGMA busy_timeout = 15000');
+      db.exec('PRAGMA journal_mode = WAL');
+      db.exec('PRAGMA synchronous = NORMAL');
+      // Phase 4 / #1083 — network-FS detection. SQLite's POSIX advisory locks
+      // and WAL shared-memory both fail silently on NFS/SMB; the engine falls
+      // back to a non-WAL journal mode rather than erroring. Read journal_mode
+      // back and warn if it isn't `wal`.
+      if (dbPath !== ':memory:') warnIfNotWal(db, dbPath);
+    } catch (err) {
+      try { db.close(); } catch { /* already-dead handle */ }
+      throw err;
+    }
+  }
+  return wrapNodeSqlite(db, dbPath);
+}
+
+/**
+ * Read `journal_mode` back after we requested WAL. If the engine returned a
+ * different mode (`delete`, `truncate`, `persist`, `memory`, `off`), the
+ * underlying filesystem doesn't support WAL's shared-memory sidecar — a
+ * strong signal that POSIX advisory locks are also unreliable. Surface a
+ * one-line stderr warning naming the path so the user knows to move the
+ * project off the network mount. Deduped per (path, process).
+ *
+ * Exported so the test in `tests/bin/get-backend.test.ts` can drive a real
+ * non-WAL handle through the same probe (a local-disk DB will always come
+ * back as WAL, so we can't trigger the warning by simply opening a DB).
+ *
+ * @param {object} db node:sqlite DatabaseSync handle
+ * @param {string} dbPath
+ */
+export function warnIfNotWal(db, dbPath) {
+  if (_networkFsWarnedPaths.has(dbPath)) return;
+  let mode;
+  try {
+    const stmt = db.prepare('PRAGMA journal_mode');
+    const row = stmt.get();
+    mode = String(row?.journal_mode ?? '').toLowerCase();
+  } catch {
+    // Probe must never break the open path — silent failure is acceptable
+    // because the WAL pragma above already either took effect or didn't.
+    return;
+  }
+  if (mode && mode !== 'wal') {
+    _networkFsWarnedPaths.add(dbPath);
+    process.stderr.write(
+      `[moflo] WARNING: SQLite journal_mode=${mode} on ${dbPath} (WAL not active). ` +
+      `If this directory is on NFS/SMB or another network filesystem, POSIX ` +
+      `advisory locks are unreliable and concurrent moflo processes can corrupt ` +
+      `the database. Move the project to a local disk to restore multi-process safety.\n`
+    );
+  }
+}
+
+/** @internal — test hook only (resets the dedupe set). */
+export function _resetNetworkFsWarnings() {
+  _networkFsWarnedPaths.clear();
+}
+
+function wrapNodeSqlite(db, dbPath) {
+  // node:sqlite has no `db.changes` field, so the rowsModified probe is a
+  // tiny prepared statement reused across calls — preparing on every probe
+  // would dominate the indexer's tight write loops.
+  let changesStmt = null;
+  const getChanges = () => {
+    if (!changesStmt) changesStmt = db.prepare('SELECT changes() AS c');
+    const row = changesStmt.get();
+    return Number(row?.c ?? 0);
+  };
+
+  // Per-connection prepare cache for `db.run(sql, params)` calls — without
+  // this the indexer's bulk-DELETE loop (index-guidance:698,699,717) allocates
+  // a fresh StatementSync per row, churning the engine's compile cache.
+  const runStmtCache = new Map();
+  const runWithParams = (sql, params) => {
+    let s = runStmtCache.get(sql);
+    if (!s) {
+      s = db.prepare(sql);
+      runStmtCache.set(sql, s);
+    }
+    s.run(...params);
+  };
+
+  return {
+    kind: BACKEND_NODE_SQLITE,
+    prepare: (sql) => wrapNodeSqliteStmt(db.prepare(sql)),
+    run: (sql, params) => {
+      if (params && params.length > 0) runWithParams(sql, params);
+      else db.exec(sql);
+    },
+    exec: (sql) => execAsRowsNodeSqlite(db, sql),
+    getRowsModified: getChanges,
+    save: () => {
+      // node:sqlite persists incrementally via WAL — explicit save is a no-op.
+      // Callers can still invoke `save()` unconditionally; the API parity
+      // matters more than micro-optimising one call away.
+    },
+    close: () => {
+      changesStmt = null;
+      runStmtCache.clear();
+      db.close();
+    },
+    _raw: db,
+  };
+}
+
+/**
+ * Heuristic match for multi-statement SQL: `;` followed by anything
+ * substantive. node:sqlite's `db.prepare()` does NOT throw on multi-statement
+ * input — it silently parses the first statement only and drops the rest,
+ * which is the worst possible failure mode for DDL batches like
+ * `CREATE TABLE a; CREATE INDEX i; CREATE TABLE b;`. Detect and route
+ * multi-stmt SQL to `db.exec()` (which runs every statement).
+ */
+function isMultiStatement(sql) {
+  const trimmed = sql.trimEnd();
+  const semi = trimmed.indexOf(';');
+  if (semi === -1) return false;
+  return /\S/.test(trimmed.slice(semi + 1));
+}
+
+/**
+ * Adapt node:sqlite to sql.js's `db.exec(sql)` return shape:
+ * `[{ columns: string[], values: any[][] }]`. The bin scripts use this for
+ * single-statement queries that return rows (`PRAGMA integrity_check` in
+ * `db-repair.mjs`, `SELECT COUNT(*)` in `index-guidance.mjs`) and for
+ * multi-statement DDL batches (controller `ensureSchema`).
+ */
+function execAsRowsNodeSqlite(db, sql) {
+  // Multi-statement DDL: db.exec() runs every statement. Matches sql.js's
+  // exec() contract — DDL batches return `[]` (no row results to surface).
+  if (isMultiStatement(sql)) {
+    db.exec(sql);
+    return [];
+  }
+  let stmt;
+  try {
+    stmt = db.prepare(sql);
+  } catch {
+    db.exec(sql);
+    return [];
+  }
+  const rows = stmt.all();
+  if (rows.length === 0) return [];
+  const columns = Object.keys(rows[0]);
+  const values = rows.map((r) => columns.map((c) => r[c]));
+  return [{ columns, values }];
+}
+
+function wrapNodeSqliteStmt(stmt) {
+  // sql.js statements are stateful (bind → step* → free); node:sqlite's
+  // StatementSync is stateless (each call takes its own params). The shim
+  // captures the pending params and lazily opens an iterator on first
+  // `step()`, releasing the iterator on `free()` so the next `bind()`+
+  // `step()` cycle starts cleanly.
+  let pendingParams = null;
+  let iter = null;
+  let currentRow = null;
+  return {
+    bind: (params) => {
+      pendingParams = params && params.length > 0 ? params : null;
+      iter = null;
+      currentRow = null;
+    },
+    step: () => {
+      if (!iter) {
+        iter = pendingParams ? stmt.iterate(...pendingParams) : stmt.iterate();
+      }
+      const next = iter.next();
+      if (next.done) {
+        currentRow = null;
+        return false;
+      }
+      currentRow = next.value;
+      return true;
+    },
+    getAsObject: () => currentRow || {},
+    run: (params) => {
+      if (params && params.length > 0) stmt.run(...params);
+      else stmt.run();
+    },
+    free: () => {
+      // sql.js's `Statement.free()` finalises the underlying statement;
+      // node:sqlite has no per-statement finalize (StatementSync is GC'd
+      // when the Database closes). The wrapper's `free()` instead resets
+      // the iteration state so the next `bind()`+`step()` cycle starts
+      // cleanly. Functional parity with sql.js callers despite the
+      // different underlying lifecycle.
+      iter = null;
+      currentRow = null;
+      pendingParams = null;
+    },
+  };
+}

package/bin/lib/incremental-write.mjs

@@ -66,16 +66,30 @@ export function computeContentListHash(files) {
 }
 
 /**
- * Load `key → content` for every active row in the namespace.
+ * Load `key → content` for every active row in the namespace, optionally
+ * scoped to keys starting with `keyPrefix` (one doc's chunks at a time —
+ * lets per-file indexers like `index-guidance.mjs` content-diff without
+ * loading every chunk across every file).
+ *
  * @param {object} db - sql.js Database
  * @param {string} namespace
+ * @param {string} [keyPrefix] — when set, restricts the scan to `key LIKE '<prefix>%'`.
+ *   The same prefix scopes the orphan sweep in {@link applyIncrementalChunks}.
  * @returns {Map<string,string>}
  */
-export function loadExistingContent(db, namespace) {
-  const stmt = db.prepare(
-    `SELECT key, content FROM memory_entries WHERE namespace = ? AND status = 'active'`,
-  );
-  stmt.bind([namespace]);
+export function loadExistingContent(db, namespace, keyPrefix) {
+  const stmt = keyPrefix
+    ? db.prepare(
+        `SELECT key, content FROM memory_entries WHERE namespace = ? AND key LIKE ? AND status = 'active'`,
+      )
+    : db.prepare(
+        `SELECT key, content FROM memory_entries WHERE namespace = ? AND status = 'active'`,
+      );
+  if (keyPrefix) {
+    stmt.bind([namespace, `${keyPrefix}%`]);
+  } else {
+    stmt.bind([namespace]);
+  }
   const map = new Map();
   while (stmt.step()) {
     const row = stmt.getAsObject();
@@ -95,11 +109,17 @@ export function loadExistingContent(db, namespace) {
  * @param {object} [opts]
  * @param {boolean} [opts.serialize=true] - JSON.stringify metadata/tags before
  *   writing. Set false when callers already pass strings.
+ * @param {string} [opts.keyPrefix] — when set, the existing-content load AND
+ *   the orphan sweep are restricted to keys matching `<prefix>%`. Use this
+ *   when processing a single file's chunks at a time (e.g. index-guidance.mjs
+ *   iterates files independently) — without it the sweep would delete every
+ *   chunk from every OTHER file as an orphan on each call.
  * @returns {{inserted:number, updated:number, unchanged:number, removed:number}}
  */
 export function applyIncrementalChunks(db, namespace, chunks, opts = {}) {
   const serialize = opts.serialize !== false;
-  const existing = loadExistingContent(db, namespace);
+  const keyPrefix = opts.keyPrefix;
+  const existing = loadExistingContent(db, namespace, keyPrefix);
   const newKeys = new Set();
   let inserted = 0;
   let updated = 0;

package/bin/lib/moflo-paths.mjs

@@ -1,16 +1,19 @@
 /**
- * Pure-JS counterpart to src/cli/services/moflo-paths.ts.
+ * Pure-JS counterpart to src/cli/services/moflo-paths.ts and the
+ * findProjectRoot helper in src/cli/services/project-root.ts.
  *
  * Lives in bin/lib because session-start-launcher.mjs and other bin/ scripts
  * run before any TS compilation has happened — they can't import the .ts
- * source. The TS version is the canonical programmatic API; this version
- * exposes the same path constants + helpers.
+ * source. The TS versions are the canonical programmatic API; this file
+ * exposes the same path constants + helpers and MUST stay algorithmically
+ * identical (see tests/system/project-root-twin.test.ts).
  *
  * Per #851, the legacy `.claude-flow/` rename + `.swarm/memory.db` byte-copy
  * helpers no longer ship: the version-bump-gated cherry-pick lives entirely
  * in the launcher and the TS service `cli/services/cherry-pick-learnings.ts`.
  */
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve } from 'node:path';
 
 export const MOFLO_DIR = '.moflo';
 export const MEMORY_DB_FILE = 'moflo.db';
@@ -57,3 +60,60 @@ export function memoryDbCandidatePaths(projectRoot) {
     join(projectRoot, '.claude', LEGACY_MEMORY_DB_FILE),
   ];
 }
+
+/**
+ * Resolve the project root the same way the TS bridge does. Every bin/
+ * script that touches `.moflo/moflo.db` (or any sibling state under
+ * `.moflo/`) MUST go through this so its writes land on the SAME file the
+ * bridge reads from.
+ *
+ * Algorithmic twin of `src/cli/services/project-root.ts:findProjectRoot()`
+ * and `src/cli/memory/bridge-core.ts:getProjectRoot()`. See those files for
+ * the canonical algorithm comment.
+ *
+ * @param {{ cwd?: string; honorEnv?: boolean }} [opts]
+ * @returns {string} absolute project root
+ */
+export function findProjectRoot(opts) {
+  const honorEnv = opts?.honorEnv !== false;
+  if (honorEnv && process.env.CLAUDE_PROJECT_DIR) {
+    return process.env.CLAUDE_PROJECT_DIR;
+  }
+  const startDir = opts?.cwd ?? process.cwd();
+  const start = resolve(startDir);
+  const fsRoot = parse(start).root;
+
+  // High-priority pass: memory markers + CLAUDE.md/package.json pair.
+  let dir = start;
+  while (dir !== fsRoot) {
+    if (basename(dir) === 'node_modules') {
+      dir = dirname(dir);
+      continue;
+    }
+    if (existsSync(join(dir, '.moflo', 'moflo.db'))) return dir;
+    if (existsSync(join(dir, '.swarm', 'memory.db'))) return dir;
+    if (existsSync(join(dir, 'CLAUDE.md')) && existsSync(join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Low-priority pass: bare package.json or .git.
+  dir = start;
+  while (dir !== fsRoot) {
+    if (basename(dir) === 'node_modules') {
+      dir = dirname(dir);
+      continue;
+    }
+    if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, '.git'))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return startDir;
+}

package/bin/lib/suppress-sqlite-warning.mjs

@@ -0,0 +1,57 @@
+/**
+ * Filter out Node's `(node:NNN) ExperimentalWarning: SQLite is an experimental
+ * feature and might change at any time` line that fires once per process the
+ * first time `node:sqlite` is loaded.
+ *
+ * Why we suppress: moflo committed to node:sqlite as the only backend in
+ * Phase 5 (#1084). The warning is informational from Node's perspective but
+ * actively harmful for us because:
+ *   1. It lands on stderr → the consumer-smoke harness's 200-char stderr
+ *      tails (`recordExit`) get filled with the warning prefix, hiding the
+ *      real failure message behind it (#1098 — `Memory Access Functional`
+ *      failures looked like ExperimentalWarning failures in CI logs).
+ *   2. It appears in every consumer's `flo doctor` / `flo memory init` /
+ *      `flo daemon start` invocation, polluting their terminal output for
+ *      something they can't act on.
+ *
+ * Implementation: replace `process.emitWarning` with a thin filter ONLY for
+ * the SQLite warning. Every other warning passes through unchanged — we
+ * specifically don't want to broadly mute `--no-warnings`-style suppression
+ * because that would also hide e.g. import-attributes ExperimentalWarning
+ * which IS something we'd want to know about.
+ *
+ * The filter is idempotent: re-importing the module is a no-op. Must run
+ * BEFORE the first `import 'node:sqlite'` anywhere in the process tree;
+ * called from `bin/cli.js`, `bin/lib/get-backend.mjs`, and the daemon-
+ * backend module loader.
+ *
+ * @module bin/lib/suppress-sqlite-warning
+ */
+
+const INSTALLED = Symbol.for('moflo.suppressSqliteWarning.installed');
+
+function shouldSuppress(message) {
+  if (typeof message === 'string') {
+    return message.includes('SQLite is an experimental feature');
+  }
+  if (message && typeof message === 'object') {
+    return typeof message.message === 'string' && message.message.includes('SQLite is an experimental feature');
+  }
+  return false;
+}
+
+if (!globalThis[INSTALLED]) {
+  globalThis[INSTALLED] = true;
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = function (warning, ...args) {
+    // Two emit signatures: (message, type, code, ctor) and (message, options).
+    // Inspect both `warning` and `args[0]` (which is `type` in the legacy
+    // form or `options.type` in the new form) before deciding.
+    if (shouldSuppress(warning)) return;
+    const typeArg = typeof args[0] === 'string'
+      ? args[0]
+      : (args[0] && typeof args[0] === 'object' ? args[0].type : undefined);
+    if (typeArg === 'ExperimentalWarning' && typeof warning === 'string' && warning.includes('SQLite')) return;
+    return originalEmitWarning.apply(this, [warning, ...args]);
+  };
+}

package/bin/migrations/knowledge-purge.mjs

@@ -15,9 +15,9 @@
  * @module bin/migrations/knowledge-purge
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { existsSync } from 'fs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 import { hasMigrationRun } from '../lib/migrations.mjs';
 import { MIGRATED_FROM_KNOWLEDGE } from './lib/markers.mjs';
 
@@ -44,11 +44,10 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { purged: 0, skipped: 0 };
 
-  // Lazy-load sql.js — keeps the manifest-stamped no-op path off the WASM
-  // init cost (~30ms cold).
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  // Lazy-load via the backend factory — keeps the manifest-stamped no-op
+  // path off the WASM init cost (~30ms cold). Engine selection lives in
+  // openBackend() (default: node:sqlite as of #1083 Phase 4).
+  const db = await openBackend(projectRoot, { create: false });
 
   const knowledgeStmt = db.prepare(
     `SELECT id, key, status FROM memory_entries
@@ -101,7 +100,7 @@ export async function run(projectRoot) {
     deleteStmt.free();
   }
 
-  if (purged > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (purged > 0) db.save();
   db.close();
   return { purged, skipped };
 }

package/bin/migrations/knowledge-to-learnings.mjs

@@ -10,11 +10,10 @@
  * @module bin/migrations/knowledge-to-learnings
  */
 
-import { existsSync, readFileSync } from 'fs';
-import { writeFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { randomBytes } from 'crypto';
-import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
 import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
 import { MIGRATED_FROM_KNOWLEDGE } from './lib/markers.mjs';
 
 export const name = 'knowledge-to-learnings';
@@ -45,11 +44,10 @@ export async function run(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { rowsMigrated: 0, rowsSkipped: 0 };
 
-  // Lazy-load sql.js — top-level await would pay ~30ms WASM init even on the
-  // no-op fast-path where the manifest already records this migration as done.
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  const db = new SQL.Database(readFileSync(dbPath));
+  // Lazy-load via the backend factory — top-level await would pay the engine
+  // init cost even on the no-op fast-path where the manifest already records
+  // this migration as done.
+  const db = await openBackend(projectRoot, { create: false });
 
   const sourceStmt = db.prepare(
     `SELECT id, key, content, type, metadata, tags, embedding, embedding_dimensions,
@@ -119,7 +117,7 @@ export async function run(projectRoot) {
     insertStmt.free();
   }
 
-  if (migrated > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  if (migrated > 0) db.save();
   db.close();
   return { rowsMigrated: migrated, rowsSkipped: skipped };
 }

package/bin/migrations/purge-doc-entries.mjs

@@ -0,0 +1,52 @@
+/**
+ * Migration: hard-delete every legacy `doc-*` whole-document entry from the
+ * guidance namespace. The chunker no longer writes these (#1053 S4) — audit
+ * found zero production readers, they duplicated chunk semantic territory,
+ * and they ate ~13% of search slots on every query without unique signal.
+ *
+ * Idempotent: re-runs are no-ops because there will be no `doc-*` rows left.
+ *
+ * @module bin/migrations/purge-doc-entries
+ */
+
+import { existsSync } from 'fs';
+import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
+
+export const name = 'purge-doc-entries';
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{purged:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { purged: 0 };
+
+  // Lazy-load via the backend factory — keeps the manifest-stamped no-op
+  // path off the WASM init cost (~30ms cold). Engine selection lives in
+  // openBackend() (default: node:sqlite as of #1083 Phase 4).
+  const db = await openBackend(projectRoot, { create: false });
+
+  // Scope: every namespace, since both `flo memory index-guidance` and
+  // `bin/index-guidance.mjs` historically wrote doc-* across whatever
+  // namespace the entry was scoped to (default for guidance: `guidance`).
+  // Conservative — match the prefix only, never sweep user-stored keys
+  // that happen to start with "doc".
+  const countStmt = db.prepare(`SELECT COUNT(*) AS cnt FROM memory_entries WHERE key LIKE 'doc-%'`);
+  countStmt.step();
+  const beforeCount = Number(countStmt.getAsObject().cnt ?? 0);
+  countStmt.free();
+
+  if (beforeCount === 0) {
+    db.close();
+    return { purged: 0 };
+  }
+
+  db.run(`DELETE FROM memory_entries WHERE key LIKE 'doc-%'`);
+  const purged = db.getRowsModified?.() ?? beforeCount;
+
+  if (purged > 0) db.save();
+  db.close();
+  return { purged };
+}