moflo 4.9.37 → 4.10.0

package/bin/index-guidance.mjs

@@ -25,25 +25,15 @@
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
 import { resolve, relative, dirname, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
-import { mofloResolveURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath } from './lib/moflo-paths.mjs';
+import { memoryDbPath, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
+import { applyIncrementalChunks } from './lib/incremental-write.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { createProcessManager } from './lib/process-manager.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 
 // Locate the moflo package root (for bundled guidance that ships with moflo)
@@ -181,14 +171,7 @@ function ensureDbDir() {
 
 async function getDb() {
   ensureDbDir();
-  const SQL = await initSqlJs();
-  let db;
-  if (existsSync(DB_PATH)) {
-    const buffer = readFileSync(DB_PATH);
-    db = new SQL.Database(buffer);
-  } else {
-    db = new SQL.Database();
-  }
+  const db = await openBackend(projectRoot, { create: true });
 
   // Ensure table exists with unique constraint
   db.run(`
@@ -221,12 +204,7 @@ async function getDb() {
 }
 
 function saveDb(db) {
-  const data = db.export();
-  writeFileSync(DB_PATH, Buffer.from(data));
-}
-
-function generateId() {
-  return `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  db.save();
 }
 
 function hashContent(content) {
@@ -239,39 +217,6 @@ function hashContent(content) {
   return hash.toString(16);
 }
 
-function storeEntry(db, key, content, metadata = {}, tags = []) {
-  const now = Date.now();
-  const id = generateId();
-  const metaJson = JSON.stringify(metadata);
-  const tagsJson = JSON.stringify(tags);
-
-  db.run(`
-    INSERT OR REPLACE INTO memory_entries
-    (id, key, namespace, content, metadata, tags, created_at, updated_at, status)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active')
-  `, [id, key, NAMESPACE, content, metaJson, tagsJson, now, now]);
-
-  return true;
-}
-
-function deleteByPrefix(db, prefix) {
-  db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key LIKE ?`, [NAMESPACE, `${prefix}%`]);
-}
-
-function getEntryHash(db, key) {
-  const stmt = db.prepare('SELECT metadata FROM memory_entries WHERE key = ? AND namespace = ?');
-  stmt.bind([key, NAMESPACE]);
-  const entry = stmt.step() ? stmt.getAsObject() : null;
-  stmt.free();
-  if (entry?.metadata) {
-    try {
-      const meta = JSON.parse(entry.metadata);
-      return meta.contentHash;
-    } catch { /* ignore */ }
-  }
-  return null;
-}
-
 // #1053 S4: doc-* entries retired. Doc-level skip check now reads
 // docContentHash off chunk-0 (every chunk carries it).
 function getDocHashFromChunkZero(db, chunkPrefix) {
@@ -564,10 +509,9 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const stats = statSync(filePath);
     const relativePath = '/' + relative(projectRoot, filePath).replace(/\\/g, '/');
 
-    // Delete old chunks for this file before re-indexing.
-    // #1053 S4: also delete any legacy doc-* row (one-time cleanup if a
-    // pre-S4 install left one behind for this prefix).
-    deleteByPrefix(db, chunkPrefix);
+    // #1053 S4: drop any legacy doc-* row left over from a pre-S4 install.
+    // The chunker stopped emitting these and the audit found zero production
+    // readers; safe one-time cleanup as part of the per-doc re-index.
     db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, docKey]);
 
     // #1053 S4: Chunker no longer writes doc-* entries. Audit found zero
@@ -580,6 +524,8 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const chunks = chunkMarkdown(content, fileName);
 
     if (chunks.length === 0) {
+      // No chunks generated → sweep any stragglers from a prior run and exit.
+      db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key LIKE ?`, [NAMESPACE, `${chunkPrefix}-%`]);
       return { docKey, status: 'indexed', chunks: 0 };
     }
 
@@ -587,21 +533,17 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const hierarchy = buildHierarchy(chunks, chunkPrefix);
     const siblings = chunks.map((_, i) => `${chunkPrefix}-${i}`);
 
-    for (let i = 0; i < chunks.length; i++) {
-      const chunk = chunks[i];
+    // #1057: route chunk writes through applyIncrementalChunks so an
+    // unchanged chunk (~95% of the time when only one section of a doc
+    // edited) keeps its embedding column. Pre-#1057 this loop used raw
+    // INSERT OR REPLACE after a blanket deleteByPrefix — every re-index
+    // wiped every chunk's embedding and forced build-embeddings to
+    // re-vectorise the whole doc on every save. See
+    // feedback_indexer_preserve_embeddings.md.
+    const chunkRows = chunks.map((chunk, i) => {
       const chunkKey = `${chunkPrefix}-${i}`;
-
-      // Build prev/next links
       const prevChunk = i > 0 ? `${chunkPrefix}-${i - 1}` : null;
       const nextChunk = i < chunks.length - 1 ? `${chunkPrefix}-${i + 1}` : null;
-
-      // #1053 S5: dropped extractOverlapContext + preamble wrapping. The
-      // preambles were a workaround for missing traversal — once memory_get_neighbors
-      // is wired (S2), prevChunk/nextChunk metadata + a real call is the
-      // alternative path. Saved ~25-30% bloat per chunk on disk and in
-      // embeddings.
-
-      // Get hierarchical relationships
       const hierInfo = hierarchy[chunkKey];
 
       const chunkMetadata = {
@@ -646,16 +588,25 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
       // #1053 S5: title heading + chunk body. No prev/next preamble.
       const searchableContent = `# ${chunk.title}\n\n${chunk.content}`;
 
-      // Store chunk with full metadata
-      storeEntry(
-        db,
-        chunkKey,
-        searchableContent,
-        chunkMetadata,
-        [keyPrefix, 'chunk', `level-${chunk.level}`, chunk.title.toLowerCase().replace(/[^a-z0-9]+/g, '-'), ...extraTags]
-      );
+      return {
+        key: chunkKey,
+        content: searchableContent,
+        metadata: chunkMetadata,
+        tags: [
+          keyPrefix,
+          'chunk',
+          `level-${chunk.level}`,
+          chunk.title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+          ...extraTags,
+        ],
+      };
+    });
 
-      debug(`  Stored chunk ${i}: ${chunk.title} (${chunk.content.length} chars, prev=${!!prevChunk}, next=${!!nextChunk})`);
+    const counts = applyIncrementalChunks(db, NAMESPACE, chunkRows, {
+      keyPrefix: `${chunkPrefix}-`,
+    });
+    if (verbose) {
+      debug(`  Doc ${docKey}: inserted=${counts.inserted} updated=${counts.updated} unchanged=${counts.unchanged} removed=${counts.removed}`);
     }
 
     return { docKey, status: 'indexed', chunks: chunks.length };

package/bin/index-patterns.mjs

@@ -28,23 +28,13 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
-import { mofloResolveURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
+import { memoryDbPath, MOFLO_DIR, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
 import { createProcessManager } from './lib/process-manager.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const NAMESPACE = 'patterns';
 const DB_PATH = memoryDbPath(projectRoot);
@@ -76,16 +66,9 @@ function ensureDbDir() {
 async function getDb() {
   ensureDbDir();
   // Lazy: hash-cache-match and no-source-files early-exits in main() never
-  // reach this, and the sql.js wasm cold-load is ~400ms otherwise wasted.
-  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
-  const SQL = await initSqlJs();
-  let db;
-  if (existsSync(DB_PATH)) {
-    const buffer = readFileSync(DB_PATH);
-    db = new SQL.Database(buffer);
-  } else {
-    db = new SQL.Database();
-  }
+  // reach this, and the backend cold-load (sql.js wasm ~400ms, node:sqlite
+  // WAL init ~20ms) is otherwise wasted on the no-op path.
+  const db = await openBackend(projectRoot, { create: true });
   db.run(`
     CREATE TABLE IF NOT EXISTS memory_entries (
       id TEXT PRIMARY KEY,
@@ -114,8 +97,7 @@ async function getDb() {
 }
 
 function saveDb(db) {
-  const data = db.export();
-  writeFileSync(DB_PATH, Buffer.from(data));
+  db.save();
 }
 
 function countNamespace(db) {

package/bin/index-tests.mjs

@@ -26,24 +26,13 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 import { resolve, dirname, relative, basename, extname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync, execFileSync, spawn } from 'child_process';
-import { mofloResolveURL } from './lib/moflo-resolve.mjs';
-import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
+import { memoryDbPath, MOFLO_DIR, findProjectRoot } from './lib/moflo-paths.mjs';
+import { openBackend } from './lib/get-backend.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-function findProjectRoot() {
-  let dir = process.cwd();
-  const root = resolve(dir, '/');
-  while (dir !== root) {
-    if (existsSync(resolve(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
-
 const projectRoot = findProjectRoot();
 const NAMESPACE = 'tests';
 const DB_PATH = memoryDbPath(projectRoot);
@@ -87,14 +76,7 @@ function ensureDbDir() {
 
 async function getDb() {
   ensureDbDir();
-  const SQL = await initSqlJs();
-  let db;
-  if (existsSync(DB_PATH)) {
-    const buffer = readFileSync(DB_PATH);
-    db = new SQL.Database(buffer);
-  } else {
-    db = new SQL.Database();
-  }
+  const db = await openBackend(projectRoot, { create: true });
 
   db.run(`
     CREATE TABLE IF NOT EXISTS memory_entries (
@@ -124,8 +106,7 @@ async function getDb() {
 }
 
 function saveDb(db) {
-  const data = db.export();
-  writeFileSync(DB_PATH, Buffer.from(data));
+  db.save();
 }
 
 function countNamespace(db) {

package/bin/lib/db-repair.mjs

@@ -24,20 +24,9 @@
  * the DB and BEFORE the embeddings migration / soft-delete purge / ephemeral
  * purge — those all swallow corruption errors and silently no-op.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { memoryDbPath } from './moflo-paths.mjs';
-
-let _initSqlJs = null;
-
-async function loadSqlJs() {
-  if (_initSqlJs) return _initSqlJs;
-  // sql.js is a hard dependency of moflo (see top-level package.json);
-  // resolving it from the consumer's node_modules works because the launcher
-  // runs from the consumer cwd.
-  const mod = await import('sql.js');
-  _initSqlJs = mod.default || mod;
-  return _initSqlJs;
-}
+import { openBackend } from './get-backend.mjs';
 
 function isOk(execResult) {
   const rows = execResult?.[0]?.values ?? [];
@@ -63,18 +52,9 @@ export async function repairMemoryDbIfCorrupt(projectRoot) {
   const dbPath = memoryDbPath(projectRoot);
   if (!existsSync(dbPath)) return { repaired: false, errors: 0 };
 
-  let initSql;
-  try {
-    initSql = await loadSqlJs();
-  } catch {
-    return { repaired: false, errors: 0 };
-  }
-
   let db = null;
   try {
-    const SQL = await initSql();
-    const data = readFileSync(dbPath);
-    db = new SQL.Database(data);
+    db = await openBackend(projectRoot, { create: false });
 
     const before = db.exec('PRAGMA integrity_check');
     if (isOk(before)) {
@@ -89,8 +69,7 @@ export async function repairMemoryDbIfCorrupt(projectRoot) {
       return { repaired: false, errors, persistent: true };
     }
 
-    const out = Buffer.from(db.export());
-    writeFileSync(dbPath, out);
+    db.save();
     return { repaired: true, errors };
   } catch {
     return { repaired: false, errors: 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;
+    },
+  };
+}