@mxalbert/context-mode 2.0.0

package/build/db-base.d.ts

@@ -0,0 +1,250 @@
+/**
+ * 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 type DatabaseConstructor from "better-sqlite3";
+import type { Database as DatabaseInstance } from "better-sqlite3";
+/**
+ * Explicit interface for cached prepared statements that accept varying
+ * parameter counts. better-sqlite3's generic `Statement` collapses under
+ * `ReturnType` to a single-param signature, so we define our own.
+ */
+export interface PreparedStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+    iterate(...params: unknown[]): IterableIterator<unknown>;
+}
+/**
+ * Wraps a bun:sqlite Database to provide better-sqlite3-compatible API.
+ * Bridges: .pragma(), multi-statement .exec(), .get() null→undefined.
+ */
+export declare class BunSQLiteAdapter {
+    #private;
+    constructor(rawDb: any);
+    pragma(source: string): any;
+    exec(sql: string): any;
+    prepare(sql: string): any;
+    transaction(fn: (...args: any[]) => any): any;
+    close(): void;
+}
+/**
+ * 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 declare class NodeSQLiteAdapter {
+    #private;
+    constructor(rawDb: any);
+    pragma(source: string): any;
+    exec(sql: string): any;
+    prepare(sql: string): any;
+    transaction(fn: (...args: any[]) => any): any;
+    close(): void;
+}
+/**
+ * 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 declare function nodeSqliteHasFts5(DatabaseSync: any): boolean;
+/**
+ * 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 declare function hasModernSqlite(versionsOverride?: NodeJS.ProcessVersions, bunOverride?: unknown): boolean;
+/**
+ * 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 declare function loadDatabase(): typeof DatabaseConstructor;
+/**
+ * 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 declare function applyWALPragmas(db: DatabaseInstance, env?: NodeJS.ProcessEnv): void;
+/**
+ * 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 declare function resolveMmapSizeFromEnv(env?: NodeJS.ProcessEnv): number | null;
+/**
+ * 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 declare function cleanOrphanedWALFiles(dbPath: string): void;
+/**
+ * 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 declare function deleteDBFiles(dbPath: string): void;
+/**
+ * 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 declare function closeDB(db: DatabaseInstance): void;
+/**
+ * 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 declare function defaultDBPath(prefix?: string): string;
+/**
+ * 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 declare function isTransientSqliteError(err: unknown): boolean;
+/**
+ * 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 declare function withRetry<T>(fn: () => T, delays?: number[]): T;
+/**
+ * Detect SQLite corruption errors that warrant a rename-and-recreate.
+ * Matches SQLITE_CORRUPT, SQLITE_NOTADB, and their human-readable equivalents.
+ */
+export declare function isSQLiteCorruptionError(msg: string): boolean;
+/**
+ * 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 declare function renameCorruptDB(dbPath: string): void;
+/**
+ * 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 declare const DB_LOG_PREFIX = "[context-mode:db]";
+/**
+ * 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 declare function logDbError(op: string, err: unknown, detail?: string, now?: number): void;
+/**
+ * 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 declare function resetDbErrorLogForTests(): void;
+/**
+ * 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 declare function getRecentDbErrorCountForTests(): number;
+export declare abstract class SQLiteBase {
+    #private;
+    /**
+     * 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: string);
+    /** Called once after WAL pragmas are applied. Subclasses run CREATE TABLE/VIRTUAL TABLE here. */
+    protected abstract initSchema(): void;
+    /** Called once after schema init. Subclasses compile and cache their prepared statements here. */
+    protected abstract prepareStatements(): void;
+    /** Raw database instance — available to subclasses only. */
+    protected get db(): DatabaseInstance;
+    /** The path this database was opened from. */
+    get dbPath(): string;
+    /** Close the database connection without deleting files. */
+    close(): void;
+    protected withRetry<T>(fn: () => T): T;
+    /**
+     * Close the connection and delete all associated DB files (main, WAL, SHM).
+     * Call on process exit or at end of session lifecycle.
+     */
+    cleanup(): void;
+}