@mxalbert/context-mode 2.0.0

package/build/db-base.js

@@ -0,0 +1,756 @@
+/**
+ * db-base — Reusable SQLite infrastructure for context-mode packages.
+ *
+ * Provides lazy-loading of better-sqlite3, WAL pragma setup, prepared
+ * statement caching interface, and DB file cleanup helpers. Both
+ * ContentStore and SessionDB build on top of these primitives.
+ */
+import { createRequire } from "node:module";
+import { existsSync, unlinkSync, renameSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// ─────────────────────────────────────────────────────────
+// bun:sqlite adapter (#45)
+// ─────────────────────────────────────────────────────────
+/**
+ * Wraps a bun:sqlite Database to provide better-sqlite3-compatible API.
+ * Bridges: .pragma(), multi-statement .exec(), .get() null→undefined.
+ */
+export class BunSQLiteAdapter {
+    #raw;
+    constructor(rawDb) {
+        this.#raw = rawDb;
+    }
+    pragma(source) {
+        const stmt = this.#raw.prepare(`PRAGMA ${source}`);
+        const rows = stmt.all();
+        if (!rows || rows.length === 0)
+            return undefined;
+        // Multi-row pragmas (table_xinfo, etc.) → return array
+        if (rows.length > 1)
+            return rows;
+        // Single-row: extract scalar value (e.g. journal_mode = "wal")
+        const values = Object.values(rows[0]);
+        return values.length === 1 ? values[0] : rows[0];
+    }
+    exec(sql) {
+        // bun:sqlite .exec() is single-statement only.
+        // Split multi-statement SQL respecting string literals (don't split on ; inside quotes).
+        let current = "";
+        let inString = null;
+        for (let i = 0; i < sql.length; i++) {
+            const ch = sql[i];
+            if (inString) {
+                current += ch;
+                if (ch === inString)
+                    inString = null;
+            }
+            else if (ch === "'" || ch === '"') {
+                current += ch;
+                inString = ch;
+            }
+            else if (ch === ";") {
+                const trimmed = current.trim();
+                if (trimmed)
+                    this.#raw.prepare(trimmed).run();
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+        const trimmed = current.trim();
+        if (trimmed)
+            this.#raw.prepare(trimmed).run();
+        return this;
+    }
+    prepare(sql) {
+        const stmt = this.#raw.prepare(sql);
+        return {
+            run: (...args) => stmt.run(...args),
+            get: (...args) => {
+                const r = stmt.get(...args);
+                return r === null ? undefined : r;
+            },
+            all: (...args) => stmt.all(...args),
+            iterate: (...args) => stmt.iterate(...args),
+        };
+    }
+    transaction(fn) {
+        return this.#raw.transaction(fn);
+    }
+    close() {
+        this.#raw.close();
+    }
+}
+// ─────────────────────────────────────────────────────────
+// node:sqlite adapter (#228)
+// ─────────────────────────────────────────────────────────
+/**
+ * Wraps node:sqlite's DatabaseSync to provide better-sqlite3-compatible API.
+ * Bridges: .pragma(), .transaction(). Everything else is passthrough.
+ * Eliminates native addon SIGSEGV on Linux (nodejs/node#62515).
+ */
+export class NodeSQLiteAdapter {
+    #raw; // DatabaseSync instance
+    constructor(rawDb) {
+        this.#raw = rawDb;
+    }
+    pragma(source) {
+        // "journal_mode = WAL" → PRAGMA journal_mode = WAL
+        // "table_xinfo(session_events)" → PRAGMA table_xinfo(session_events)
+        // "wal_checkpoint(TRUNCATE)" → PRAGMA wal_checkpoint(TRUNCATE)
+        const stmt = this.#raw.prepare(`PRAGMA ${source}`);
+        const rows = stmt.all();
+        if (!rows || rows.length === 0)
+            return undefined;
+        if (rows.length > 1)
+            return rows;
+        const values = Object.values(rows[0]);
+        return values.length === 1 ? values[0] : rows[0];
+    }
+    exec(sql) {
+        // node:sqlite's exec() supports multi-statement natively
+        this.#raw.exec(sql);
+        return this;
+    }
+    prepare(sql) {
+        const stmt = this.#raw.prepare(sql);
+        return {
+            run: (...args) => stmt.run(...args),
+            get: (...args) => stmt.get(...args),
+            all: (...args) => stmt.all(...args),
+            iterate: (...args) => {
+                // node:sqlite uses Symbol.iterator on StatementSync, not .iterate()
+                // Check if iterate exists, otherwise use Symbol.iterator
+                if (typeof stmt.iterate === 'function') {
+                    return stmt.iterate(...args);
+                }
+                // Fallback: use all() to create an iterator
+                const rows = stmt.all(...args);
+                return rows[Symbol.iterator]();
+            },
+        };
+    }
+    transaction(fn) {
+        // node:sqlite has no transaction() method — manual BEGIN/COMMIT/ROLLBACK
+        return (...args) => {
+            this.#raw.exec("BEGIN");
+            try {
+                const result = fn(...args);
+                this.#raw.exec("COMMIT");
+                return result;
+            }
+            catch (err) {
+                this.#raw.exec("ROLLBACK");
+                throw err;
+            }
+        };
+    }
+    close() {
+        this.#raw.close();
+    }
+}
+// ─────────────────────────────────────────────────────────
+// Lazy loader
+// ─────────────────────────────────────────────────────────
+let _Database = null;
+/**
+ * Probe whether the supplied node:sqlite DatabaseSync constructor links a
+ * SQLite build that includes the FTS5 module. Some Node.js Linux builds
+ * (e.g. v22.14.0 on Ubuntu) ship node:sqlite without FTS5 even though the
+ * import succeeds, which silently breaks ctx_search/ctx_batch_execute and
+ * the doctor's FTS5 check (issue #461).
+ *
+ * Returns true only when a `CREATE VIRTUAL TABLE … USING fts5(x)` statement
+ * succeeds. Always returns false on any failure (constructor throw, missing
+ * module, etc.) so the caller can fall through to better-sqlite3, whose
+ * bundled SQLite always ships with FTS5.
+ */
+export function nodeSqliteHasFts5(DatabaseSync) {
+    let probe = null;
+    try {
+        probe = new DatabaseSync(":memory:");
+        probe.exec("CREATE VIRTUAL TABLE __fts5_probe USING fts5(x)");
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            probe?.close();
+        }
+        catch { /* probe never opened or already closed */ }
+    }
+}
+/**
+ * Returns true when the current runtime ships a built-in SQLite binding:
+ * - Bun has `bun:sqlite` always
+ * - Node has `node:sqlite` since 22.5 (no flag since 22.13)
+ *
+ * Mirrors the helper in hooks/ensure-deps.mjs:61. Exported so the platform
+ * gate in loadDatabase() can be unit-tested without spawning a child
+ * process. `versionsOverride` and `bunOverride` are injection points for
+ * tests — production callers pass nothing.
+ *
+ * Widening the gate from `process.platform === "linux"` to this helper is
+ * required for Node 26 on macOS arm64 (#551): Node 26 removed
+ * `info.This()` from V8 PropertyCallbackInfo, breaking better-sqlite3
+ * 12.9.0's native compile. Using node:sqlite sidesteps the native addon
+ * entirely on every platform that has it.
+ */
+export function hasModernSqlite(versionsOverride, bunOverride) {
+    const bun = bunOverride !== undefined ? bunOverride : globalThis.Bun;
+    if (typeof bun !== "undefined" && bun !== null)
+        return true;
+    const versions = versionsOverride ?? process.versions;
+    const [majorStr, minorStr] = (versions.node ?? "0.0.0").split(".");
+    const major = Number(majorStr);
+    const minor = Number(minorStr);
+    if (!Number.isFinite(major) || !Number.isFinite(minor))
+        return false;
+    return major > 22 || (major === 22 && minor >= 5);
+}
+/**
+ * Lazy-load the SQLite driver for the current runtime.
+ * Bun → bun:sqlite via BunSQLiteAdapter (issue #45).
+ * Modern Node (>= 22.5) → node:sqlite via NodeSQLiteAdapter when it ships FTS5 (#228, #461, #551).
+ * Other Node (or modern Node without FTS5) → better-sqlite3 (native addon).
+ */
+export function loadDatabase() {
+    if (!_Database) {
+        const require = createRequire(import.meta.url);
+        if (globalThis.Bun) {
+            // Bun runtime — use bun:sqlite directly.
+            // Array.join() prevents esbuild from resolving the specifier at bundle time.
+            const BunDB = require(["bun", "sqlite"].join(":")).Database;
+            _Database = function BunDatabaseFactory(path, opts) {
+                const raw = new BunDB(path, {
+                    readonly: opts?.readonly,
+                    create: true,
+                });
+                const adapter = new BunSQLiteAdapter(raw);
+                // Propagate busy_timeout — better-sqlite3 does this via constructor
+                // option but bun:sqlite does not, so we set it via pragma (#243)
+                if (opts?.timeout) {
+                    adapter.pragma(`busy_timeout = ${opts.timeout}`);
+                }
+                return adapter;
+            };
+        }
+        else if (hasModernSqlite()) {
+            // Any Node >= 22.5 — try node:sqlite to avoid the native addon path
+            // entirely. Historically this was Linux-only (avoiding the Linux
+            // SIGSEGV per nodejs/node#62515, #228), but Node 26 also broke
+            // better-sqlite3's native compile on macOS arm64 by removing
+            // V8 `info.This()` (#551). The built-in `node:sqlite` ships its
+            // own SQLite, so it sidesteps both issues at once.
+            //
+            // Probe FTS5 support before committing — some Node builds ship
+            // node:sqlite without FTS5, which would silently break ctx_search
+            // (#461). The probe runs at most once per process (cached via
+            // _Database below), so the cost of an in-memory DatabaseSync is
+            // negligible.
+            let DatabaseSync = null;
+            try {
+                // Array.join() prevents esbuild from resolving the specifier at bundle time
+                // (mirrors the bun:sqlite branch above).
+                ({ DatabaseSync } = require(["node", "sqlite"].join(":")));
+            }
+            catch {
+                DatabaseSync = null;
+            }
+            if (DatabaseSync && nodeSqliteHasFts5(DatabaseSync)) {
+                _Database = function NodeDatabaseFactory(path, opts) {
+                    const raw = new DatabaseSync(path, {
+                        readOnly: opts?.readonly ?? false,
+                    });
+                    const adapter = new NodeSQLiteAdapter(raw);
+                    // Propagate busy_timeout — node:sqlite's DatabaseSync constructor
+                    // silently ignores `{ timeout }` (unlike better-sqlite3's native
+                    // C++ constructor), so we set it via PRAGMA, mirroring the Bun
+                    // branch above. Without this, the default is 0 and the first
+                    // write contention surfaces as immediate `SQLITE_BUSY`/`database
+                    // is locked` — defeating the 30s grace `withRetry()` is built
+                    // around. See issue #642 and ADR-0001 (multi-writer contract).
+                    if (opts?.timeout) {
+                        adapter.pragma(`busy_timeout = ${opts.timeout}`);
+                    }
+                    return adapter;
+                };
+            }
+            else {
+                // node:sqlite missing or built without FTS5 — fall through to
+                // better-sqlite3. Trade-off: on Node 26 + macOS this may now hit
+                // the V8 ABI break (#551). A visible crash on the rare
+                // unstable build is preferable to silent "no such module: fts5"
+                // on every ctx_search call.
+                _Database = require("better-sqlite3");
+            }
+        }
+        else {
+            // Old Node (< 22.5) without bun:sqlite — fall back to better-sqlite3.
+            _Database = require("better-sqlite3");
+        }
+    }
+    return _Database;
+}
+// ─────────────────────────────────────────────────────────
+// WAL setup
+// ─────────────────────────────────────────────────────────
+/**
+ * Apply WAL mode and NORMAL synchronous pragma to a database instance.
+ * Should be called immediately after opening a new database connection.
+ *
+ * WAL mode provides:
+ * - Concurrent readers while a write is in progress
+ * - Dramatically faster writes (no full-page sync on each commit)
+ * NORMAL synchronous is safe under WAL and avoids an extra fsync per
+ * transaction.
+ *
+ * v1.0.187 — mmap_size is OPT-IN (upstream #992/#905; PRs #1030/#1056):
+ * a default 256MB mmap over DB files that are shared across processes
+ * turns transient resource pressure into SQLITE_IOERR ("disk I/O error")
+ * on otherwise-healthy disks. The pragma is now applied ONLY when
+ * CONTEXT_MODE_DB_MMAP_SIZE (bytes) is set to a valid non-negative
+ * integer; when unset, mmap_size is NOT touched at all (SQLite default).
+ */
+export function applyWALPragmas(db, env = process.env) {
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    // Memory-map the DB file for read-heavy FTS5 search workloads — opt-in
+    // only (see docblock above). Falls back gracefully on platforms where
+    // mmap is unavailable or restricted.
+    const mmapSize = resolveMmapSizeFromEnv(env);
+    if (mmapSize !== null) {
+        try {
+            db.pragma(`mmap_size = ${mmapSize}`);
+        }
+        catch { /* unsupported runtime */ }
+    }
+    // NOTE: `locking_mode = EXCLUSIVE` is intentionally NOT applied here.
+    // ALL DBs built on this helper — ContentStore (FTS5 shared knowledge
+    // base) AND SessionDB (per-project events) — are multi-writer-safe by
+    // contract. WAL + busy_timeout + the withRetry() wrapper below handle
+    // SQLITE_BUSY natively. EXCLUSIVE locking is opt-out, never opt-in
+    // from a base class shared by multi-writer consumers.
+    // See docs/adr/0001-sessiondb-multi-writer.md for the v1.0.130 ADR.
+}
+/**
+ * Parse the opt-in mmap size (bytes) from CONTEXT_MODE_DB_MMAP_SIZE.
+ * Returns null when the variable is unset, empty, or not a non-negative
+ * integer — callers must then skip the mmap_size pragma entirely so the
+ * SQLite default applies.
+ *
+ * Exported so the opt-in contract is unit-testable without mutating
+ * process.env at call sites.
+ */
+export function resolveMmapSizeFromEnv(env = process.env) {
+    const raw = env.CONTEXT_MODE_DB_MMAP_SIZE;
+    if (raw === undefined || raw === null)
+        return null;
+    const trimmed = String(raw).trim();
+    if (trimmed === "")
+        return null;
+    const n = Number(trimmed);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0)
+        return null;
+    return n;
+}
+// ─────────────────────────────────────────────────────────
+// DB file helpers
+// ─────────────────────────────────────────────────────────
+/**
+ * Remove orphaned WAL/SHM files when the main DB file doesn't exist.
+ * On Windows, stale -wal/-shm files from crashed processes cause
+ * "file is not a database" errors when creating a fresh DB.
+ */
+export function cleanOrphanedWALFiles(dbPath) {
+    if (!existsSync(dbPath)) {
+        for (const suffix of ["-wal", "-shm"]) {
+            try {
+                unlinkSync(dbPath + suffix);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/**
+ * Delete all three SQLite files for a given db path (main, WAL, SHM).
+ * Silently ignores individual deletion errors so a partial cleanup
+ * does not abort the rest.
+ */
+export function deleteDBFiles(dbPath) {
+    for (const suffix of ["", "-wal", "-shm"]) {
+        try {
+            unlinkSync(dbPath + suffix);
+        }
+        catch {
+            // ignore — file may not exist
+        }
+    }
+}
+/**
+ * Safely close a database connection. Swallows errors so callers can
+ * always call this in a finally/cleanup path without try/catch.
+ *
+ * v1.0.187 — the close-time `wal_checkpoint(TRUNCATE)` was REMOVED
+ * (upstream #992/#905; PRs #1030/#1056/#880). A TRUNCATE checkpoint is a
+ * *cross-process mutation*: when a hook/CLI/statusline process still holds
+ * the same DB, the checkpoint races its WAL readers/writers and surfaces
+ * as SQLITE_IOERR ("disk I/O error") on healthy disks. SQLite already
+ * performs a best-effort (non-destructive) checkpoint inside close();
+ * the only sidecar cleanup this layer does is cleanOrphanedWALFiles,
+ * which deletes -wal/-shm when the main DB file is absent.
+ */
+export function closeDB(db) {
+    try {
+        db.close();
+    }
+    catch {
+        // ignore
+    }
+}
+// ─────────────────────────────────────────────────────────
+// Default path helper
+// ─────────────────────────────────────────────────────────
+/**
+ * Return the default per-process DB path for context-mode databases.
+ * Uses the OS temp directory and embeds the current PID so multiple
+ * server instances never share a file.
+ */
+export function defaultDBPath(prefix = "context-mode") {
+    return join(tmpdir(), `${prefix}-${process.pid}.db`);
+}
+// ─────────────────────────────────────────────────────────
+// Retry helper
+// ─────────────────────────────────────────────────────────
+/**
+ * Build a single searchable signature string from an arbitrary thrown
+ * value. Covers the shapes SQLite drivers actually throw:
+ * - Error with `code` (better-sqlite3 / node:sqlite SqliteError): code + message
+ * - Plain Error / string (bun:sqlite): message text
+ * - Non-Error objects with `code` and/or `message` properties
+ */
+function errorSignature(err) {
+    if (err instanceof Error) {
+        const code = err.code;
+        return typeof code === "string" ? `${code} ${err.message}` : err.message;
+    }
+    if (typeof err === "string")
+        return err;
+    if (err !== null && typeof err === "object") {
+        const code = err.code;
+        const message = err.message;
+        const parts = [
+            typeof code === "string" ? code : "",
+            typeof message === "string" ? message : "",
+        ].filter(Boolean);
+        return parts.length > 0 ? parts.join(" ") : String(err);
+    }
+    return String(err);
+}
+/**
+ * Transient SQLite errors that warrant a retry (v1.0.187, upstream
+ * #992/#905; PRs #1030/#1056/#880):
+ * - SQLITE_BUSY / "database is locked" — writer contention; the existing
+ *   busy_timeout + backoff contract.
+ * - SQLITE_IOERR / "disk I/O error" — frequently TRANSIENT on healthy
+ *   disks (mmap pressure, checkpoint races, AV/EDR scans). Treating it
+ *   as fatal turned recoverable blips into user-visible failures.
+ *
+ * Corruption signatures (SQLITE_CORRUPT / SQLITE_NOTADB / "file is not a
+ * database") are deliberately NOT retried — see isSQLiteCorruptionError.
+ * Non-Error throw shapes ({ code } objects, strings) are classified the
+ * same way as Errors via errorSignature().
+ */
+export function isTransientSqliteError(err) {
+    const sig = errorSignature(err);
+    return (sig.includes("SQLITE_BUSY") ||
+        sig.includes("database is locked") ||
+        sig.includes("SQLITE_IOERR") ||
+        /disk i\/o error/i.test(sig));
+}
+/**
+ * Retry a DB operation with exponential backoff on transient SQLite
+ * errors: SQLITE_BUSY ("database is locked") and SQLITE_IOERR
+ * ("disk I/O error"). Retries up to 3 times with delays: 100ms, 500ms,
+ * 2000ms. If all retries fail, throws a descriptive error.
+ * Pass custom delays for testing (e.g., [0, 0, 0] to skip waits).
+ */
+export function withRetry(fn, delays = [100, 500, 2000]) {
+    let lastError;
+    for (let attempt = 0; attempt <= delays.length; attempt++) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (!isTransientSqliteError(err)) {
+                throw err;
+            }
+            lastError = err instanceof Error ? err : new Error(errorSignature(err));
+            if (attempt < delays.length) {
+                const delay = delays[attempt];
+                const start = Date.now();
+                while (Date.now() - start < delay) { /* busy-wait for sync retry */ }
+            }
+        }
+    }
+    throw new Error(`SQLITE_BUSY/SQLITE_IOERR: transient SQLite error after ${delays.length} retries. ` +
+        `Original error: ${lastError?.message}`);
+}
+// ─────────────────────────────────────────────────────────
+// Corrupt DB recovery (#244)
+// ─────────────────────────────────────────────────────────
+/**
+ * Detect SQLite corruption errors that warrant a rename-and-recreate.
+ * Matches SQLITE_CORRUPT, SQLITE_NOTADB, and their human-readable equivalents.
+ */
+export function isSQLiteCorruptionError(msg) {
+    return (msg.includes("SQLITE_CORRUPT") ||
+        msg.includes("SQLITE_NOTADB") ||
+        msg.includes("database disk image is malformed") ||
+        msg.includes("file is not a database"));
+}
+/**
+ * Rename a corrupt DB and its WAL/SHM files so a fresh DB can be created.
+ * Best-effort — individual rename failures are silently ignored.
+ */
+export function renameCorruptDB(dbPath) {
+    const ts = Date.now();
+    for (const suffix of ["", "-wal", "-shm"]) {
+        try {
+            renameSync(dbPath + suffix, `${dbPath}${suffix}.corrupt-${ts}`);
+        }
+        catch { /* file may not exist */ }
+    }
+}
+// ─────────────────────────────────────────────────────────
+// DB error logging (v1.0.187)
+// ─────────────────────────────────────────────────────────
+/**
+ * Stable log prefix for swallowed DB failures. Neither db-base.ts nor
+ * session/db.ts has a host logger, so failures that were previously
+ * silent (best-effort schema migrations, read paths returning []/"" on
+ * error) go to stderr via console.error under this prefix.
+ */
+export const DB_LOG_PREFIX = "[context-mode:db]";
+/** Same op + code + message is logged at most once per window. */
+const DB_LOG_INTERVAL_MS = 30_000;
+/** Cap on the dedupe table so a high-cardinality error source can't grow it unbounded. */
+const DB_LOG_MAX_KEYS = 256;
+const _recentDbErrors = new Map();
+/**
+ * Extract the SQLite error code (e.g. "SQLITE_IOERR") from an arbitrary
+ * thrown value, or "" when absent. better-sqlite3 and node:sqlite set
+ * `code` on SqliteError; bun:sqlite encodes it in the message instead.
+ */
+function extractErrorCode(err) {
+    if (err instanceof Error) {
+        const code = err.code;
+        return typeof code === "string" ? code : "";
+    }
+    if (err !== null && typeof err === "object") {
+        const code = err.code;
+        return typeof code === "string" ? code : "";
+    }
+    return "";
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    if (err !== null && typeof err === "object") {
+        const message = err.message;
+        if (typeof message === "string" && message)
+            return message;
+    }
+    return String(err);
+}
+/**
+ * Log a swallowed DB failure to stderr with the stable
+ * `[context-mode:db]` prefix: operation name, error code, error message,
+ * and (when OPENCODE_DEBUG is set) the stack. The same op + code +
+ * message combination is rate-limited to one line per ~30s to avoid log
+ * storms from hot retry loops or batch scans. Logging must never throw.
+ *
+ * `detail` (e.g. a DB path) is optional context appended to the line and
+ * included in the dedupe key so different files don't suppress each
+ * other's diagnostics.
+ */
+export function logDbError(op, err, detail, now = Date.now()) {
+    try {
+        const code = extractErrorCode(err);
+        const message = errorMessage(err);
+        const detailSuffix = detail ? ` (${detail})` : "";
+        const dedupeKey = `${op}|${code}|${message}${detailSuffix}`;
+        const last = _recentDbErrors.get(dedupeKey);
+        if (last !== undefined && now - last < DB_LOG_INTERVAL_MS)
+            return;
+        _recentDbErrors.set(dedupeKey, now);
+        if (_recentDbErrors.size > DB_LOG_MAX_KEYS) {
+            // A burst of >256 distinct errors inside one window can exceed the
+            // cap. First free genuinely expired keys, then HARD-evict the oldest
+            // entries (Map preserves insertion order) until the cap is restored —
+            // the table can never exceed DB_LOG_MAX_KEYS, and keys still within
+            // the cap keep their normal dedupe semantics.
+            for (const [key, ts] of _recentDbErrors) {
+                if (now - ts >= DB_LOG_INTERVAL_MS)
+                    _recentDbErrors.delete(key);
+            }
+            while (_recentDbErrors.size > DB_LOG_MAX_KEYS) {
+                const oldestKey = _recentDbErrors.keys().next().value;
+                if (oldestKey === undefined)
+                    break;
+                _recentDbErrors.delete(oldestKey);
+            }
+        }
+        const debugRaw = process.env.OPENCODE_DEBUG;
+        const debug = debugRaw !== undefined && debugRaw !== "" && debugRaw !== "0" && debugRaw !== "false";
+        const stack = debug && err instanceof Error && err.stack ? `\n${err.stack}` : "";
+        const codePart = code ? ` [${code}]` : "";
+        console.error(`${DB_LOG_PREFIX} ${op}${codePart}: ${message}${detailSuffix}${stack}`);
+    }
+    catch {
+        // logging must never break the caller
+    }
+}
+/**
+ * Clear the log-dedupe table. Test-only: lets a test observe the first
+ * emission for a given op regardless of what earlier tests logged.
+ */
+export function resetDbErrorLogForTests() {
+    _recentDbErrors.clear();
+}
+/**
+ * Number of keys currently tracked in the log-dedupe table. Test-only:
+ * lets a test pin the DB_LOG_MAX_KEYS hard-cap (the table must never grow
+ * past the cap even under a burst of distinct errors inside one window).
+ */
+export function getRecentDbErrorCountForTests() {
+    return _recentDbErrors.size;
+}
+// ─────────────────────────────────────────────────────────
+// Base class
+// ─────────────────────────────────────────────────────────
+/**
+ * SQLiteBase — minimal base class that handles open/close/cleanup lifecycle.
+ *
+ * Subclasses call `super(dbPath)` to open the database with WAL pragmas
+ * applied, then implement `initSchema()` and `prepareStatements()`.
+ *
+ * The `db` getter exposes the raw `DatabaseInstance` to subclasses only.
+ */
+/**
+ * Track all live DatabaseInstance objects so we can close them on process exit.
+ * Prevents better-sqlite3 segfaults caused by V8 garbage-collecting Database
+ * objects after the native addon context is already torn down.
+ *
+ * Uses a global symbol so the set and exit handler survive vitest's module
+ * re-imports within the same fork process (ESM isolate mode clears
+ * module-level state but globalThis persists).
+ */
+// v1.0.130 — symbol name bumped because the value type reverted from
+// Map<DatabaseInstance, string> (v1.0.128 lockfile pairing) back to
+// Set<DatabaseInstance>. A persistent global slot from a v1.0.128 or
+// v1.0.129 module would deserialize as the wrong shape and crash the
+// exit hook iteration.
+const _kLiveDBs = Symbol.for("__context_mode_live_dbs_v3__");
+const _liveDBs = (() => {
+    const g = globalThis;
+    if (!g[_kLiveDBs]) {
+        g[_kLiveDBs] = new Set();
+        process.on("exit", () => {
+            for (const db of g[_kLiveDBs]) {
+                closeDB(db);
+            }
+            g[_kLiveDBs].clear();
+        });
+    }
+    return g[_kLiveDBs];
+})();
+export class SQLiteBase {
+    #dbPath;
+    #db;
+    /**
+     * Open (or create) a SQLite DB at `dbPath`.
+     *
+     * v1.0.130 — multi-writer is the contract. ALL SQLiteBase consumers
+     * (SessionDB, ContentStore) may open the same on-disk dbPath from
+     * multiple processes simultaneously — that is the legitimate multi-
+     * window UX shape and the WAL handles it natively. SQLITE_BUSY on
+     * write contention is absorbed by `withRetry()` below (busy_timeout
+     * = 30000ms inside `new Database(...)`).
+     *
+     * v1.0.128 introduced a single-writer guard here as a defense against
+     * #560. That defense was an over-correction — the actual root causes
+     * of #560 were #559 (zombie MCP child accumulation) and #561 (Pi
+     * misdetection writing to the wrong DB path), both fixed in v1.0.128
+     * + v1.0.129. The single-writer guard broke legitimate multi-window
+     * users; v1.0.130 rolls it out. See
+     * docs/adr/0001-sessiondb-multi-writer.md and the v1.0.130 INVARIANT
+     * block in tests/util/db-base-platform-gate.test.ts for the
+     * regression-proof anchor (source-pin + behavioural).
+     */
+    constructor(dbPath) {
+        const Database = loadDatabase();
+        this.#dbPath = dbPath;
+        cleanOrphanedWALFiles(dbPath);
+        let db;
+        try {
+            db = new Database(dbPath, { timeout: 30000 });
+            applyWALPragmas(db);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isSQLiteCorruptionError(msg)) {
+                // Surface the corruption + quarantine instead of silently swapping
+                // the file — users lose session history here and deserve a trace.
+                logDbError("SQLiteBase.open", err, dbPath);
+                renameCorruptDB(dbPath);
+                cleanOrphanedWALFiles(dbPath);
+                try {
+                    db = new Database(dbPath, { timeout: 30000 });
+                    applyWALPragmas(db);
+                }
+                catch (retryErr) {
+                    throw new Error(`Failed to create fresh DB after renaming corrupt file: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+                }
+            }
+            else {
+                throw err;
+            }
+        }
+        this.#db = db;
+        _liveDBs.add(this.#db);
+        this.initSchema();
+        this.prepareStatements();
+    }
+    /** Raw database instance — available to subclasses only. */
+    get db() {
+        return this.#db;
+    }
+    /** The path this database was opened from. */
+    get dbPath() {
+        return this.#dbPath;
+    }
+    /** Close the database connection without deleting files. */
+    close() {
+        _liveDBs.delete(this.#db);
+        closeDB(this.#db);
+    }
+    withRetry(fn) {
+        return withRetry(fn);
+    }
+    /**
+     * Close the connection and delete all associated DB files (main, WAL, SHM).
+     * Call on process exit or at end of session lifecycle.
+     */
+    cleanup() {
+        _liveDBs.delete(this.#db);
+        closeDB(this.#db);
+        deleteDBFiles(this.#dbPath);
+    }
+}