@mxalbert/context-mode 2.0.1 → 2.0.3

package/build/store.js

@@ -8,7 +8,7 @@
  * you need EXACT text later — not summaries.
  */
 var _a;
-import { loadDatabase, applyWALPragmas, closeDB, cleanOrphanedWALFiles, withRetry, deleteDBFiles, isSQLiteCorruptionError } from "./db-base.js";
+import { loadDatabase, applyWALPragmas, closeDB, cleanOrphanedWALFiles, withRetry, deleteDBFiles, isSQLiteCorruptionError, logDbError, extractErrorCode, errorMessage } from "./db-base.js";
 import { readFileSync, readdirSync, unlinkSync, existsSync, statSync, openSync, fstatSync, closeSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { tmpdir } from "node:os";
@@ -158,24 +158,30 @@ export function cleanupStaleDBs() {
     catch { /* ignore readdir errors */ }
     return cleaned;
 }
-/**
- * Check if a PID is still alive (not a zombie holding a WAL lock).
- * Returns true if the process exists, false if it's dead.
- */
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Clean up stale per-project content store DBs older than maxAgeDays.
- * Scans the given directory for *.db files and checks mtime.
- * Also detects zombie processes holding WAL locks — if a WAL file exists
- * but the owning PID is dead, the DB files are cleaned up regardless of age.
+ * Scans the given directory for *.db files and unlinks each (plus its
+ * -wal/-shm sidecars) when its EFFECTIVE last-write time — the newer of the
+ * main .db mtime and a non-empty -wal mtime — exceeds the cutoff.
+ *
+ * Why the -wal mtime participates: in WAL mode commits touch only the -wal
+ * file; the main .db mtime advances at checkpoint. A main-only check can
+ * delete an actively-used store that simply hasn't checkpointed within the
+ * window. Conversely, a non-empty -wal older than some threshold is NOT
+ * proof the owning process is dead — a live-but-idle connection (a session
+ * quiet over lunch) is indistinguishable from a crashed process by mtime
+ * alone. The pre-fix heuristic deleted such DBs unconditionally after 1h,
+ * which on macOS unlinks the files under an open connection and surfaces
+ * as disk I/O error (SQLITE_IOERR_VNODE) on every later write — no amount
+ * of retrying recovers an invalidated fd.
+ *
+ * Contract: a -wal can only EXTEND a DB's life (its mtime counts as the
+ * latest write), never shorten it. A WAL never triggers deletion on its
+ * own — the way the old 1-hour zombie rule did — and once the whole DB
+ * (main + non-empty wal) is beyond maxAgeDays, the caller's retention
+ * policy owns the consequences. Callers that cannot tolerate deleting a
+ * possibly-live DB (the per-platform content dir — see getStore() in
+ * src/server.ts) must not call this with a nonzero maxAgeDays.
  */
 export function cleanupStaleContentDBs(contentDir, maxAgeDays) {
     let cleaned = 0;
@@ -187,26 +193,18 @@ export function cleanupStaleContentDBs(contentDir, maxAgeDays) {
         for (const file of files) {
             try {
                 const filePath = join(contentDir, file);
-                const mtime = statSync(filePath).mtimeMs;
-                let shouldClean = mtime < cutoff;
-                // Detect zombie processes holding WAL locks:
-                // If a WAL file exists, try to read the WAL header to extract the PID.
-                // WAL files from dead processes can block new connections.
-                if (!shouldClean) {
-                    const walPath = filePath + "-wal";
-                    if (existsSync(walPath)) {
-                        try {
-                            const walStat = statSync(walPath);
-                            // If WAL file is non-empty and DB hasn't been modified in >1 hour,
-                            // the owning process may be dead — check via mtime staleness
-                            if (walStat.size > 0 && (Date.now() - walStat.mtimeMs) > 3600_000) {
-                                shouldClean = true;
-                            }
-                        }
-                        catch { /* ignore WAL check errors */ }
+                // Effective last-write: newer of main .db and non-empty -wal. A fresh
+                // WAL is evidence of a live (or recently-live) connection — it can
+                // only push the cutoff later, never mark a fresh DB stale.
+                let effectiveMs = statSync(filePath).mtimeMs;
+                try {
+                    const walStat = statSync(filePath + "-wal");
+                    if (walStat.size > 0 && walStat.mtimeMs > effectiveMs) {
+                        effectiveMs = walStat.mtimeMs;
                     }
                 }
-                if (shouldClean) {
+                catch { /* no -wal — main mtime stands */ }
+                if (effectiveMs < cutoff) {
                     for (const suffix of ["", "-wal", "-shm"]) {
                         try {
                             unlinkSync(filePath + suffix);
@@ -302,6 +300,65 @@ function findMinSpan(positionLists) {
     }
     return minSpan;
 }
+// ─────────────────────────────────────────────────────────
+// Store error handling (v2.0.2 — disk-I/O hardening parity with db-base)
+// ─────────────────────────────────────────────────────────
+/**
+ * Prefix for tool-visible ContentStore failures. Store failures used to
+ * surface as the raw driver message — for SQLITE_IOERR exactly
+ * "disk I/O error", with no op, no DB path, no SQLite code, and nothing
+ * in any log (the store layer's catches were all silent). Every store
+ * open/write failure now (a) logs to stderr via db-base's logDbError
+ * (same `[context-mode:db]` prefix, 30s dedupe, 256-key cap) and
+ * (b) rethrows with this prefix plus op, path, and code so the isError
+ * text the MCP client sees is actionable.
+ */
+const STORE_ERROR_PREFIX = "[context-mode:store]";
+/**
+ * Symbol marking Errors that this layer already reported via logDbError
+ * (every storeFailure product carries it). Symbol.for so the flag survives
+ * module re-imports, mirroring db-base's global-symbol pattern.
+ */
+const kDbErrorLogged = Symbol.for("__context_mode_db_error_logged__");
+/** True when `err` was already logged + enriched by an inner store op —
+ *  outer catches must not emit a second line for the same failure. */
+function isDbErrorAlreadyLogged(err) {
+    try {
+        return (typeof err === "object" &&
+            err !== null &&
+            err[kDbErrorLogged] === true);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Log `err` for store operation `op` and return an Error whose message
+ * carries the op, the DB file path, and the SQLite code (when present):
+ * `[context-mode:store] <op> failed on <dbPath>: <message> (<code>)`.
+ * The returned Error preserves the original `.code` and carries a
+ * non-enumerable kDbErrorLogged marker: when it flows through another
+ * storeFailure call (e.g. a failed stale re-index surfacing through an
+ * outer wrapper) it is returned as-is, so one underlying failure produces
+ * exactly one `[context-mode:db]` line, under the op that owns it.
+ * `base` replaces `<message>` for callers that must preserve an existing
+ * wrap message (the corruption delete-and-recreate retry). Callers throw
+ * the result. Logging goes through db-base's logDbError (stderr), never
+ * console.log, and logging itself never throws.
+ */
+function storeFailure(op, err, dbPath, base) {
+    if (isDbErrorAlreadyLogged(err))
+        return err;
+    logDbError(op, err, dbPath);
+    const message = errorMessage(err);
+    const code = extractErrorCode(err);
+    const codeSuffix = code ? ` (${code})` : "";
+    const enriched = new Error(`${STORE_ERROR_PREFIX} ${op} failed on ${dbPath}: ${base ?? message}${codeSuffix}`);
+    if (code)
+        enriched.code = code;
+    Object.defineProperty(enriched, kDbErrorLogged, { value: true, enumerable: false });
+    return enriched;
+}
 export class ContentStore {
     #db;
     #dbPath;
@@ -367,31 +424,55 @@ export class ContentStore {
         this.#dbPath =
             dbPath ?? join(tmpdir(), `context-mode-${process.pid}.db`);
         cleanOrphanedWALFiles(this.#dbPath);
+        // One open attempt: create the connection and apply WAL pragmas.
+        // Wrapped in withRetry below so a transient SQLITE_IOERR / "disk I/O
+        // error" on open is retried with the same exponential backoff as
+        // SQLITE_BUSY (db-base, v1.0.187 hardening). Corruption signatures are
+        // never retried by withRetry — they rethrow for the recovery path.
+        const openOnce = () => {
+            const db = new Database(this.#dbPath, { timeout: 30000 });
+            applyWALPragmas(db);
+            return db;
+        };
         let db;
         try {
-            db = new Database(this.#dbPath, { timeout: 30000 });
-            applyWALPragmas(db);
+            db = withRetry(openOnce);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (isSQLiteCorruptionError(msg)) {
+                // Surface the corruption + delete-and-recreate instead of silently
+                // swapping the file — users lose indexed content and deserve a trace.
+                logDbError("store.open", err, this.#dbPath);
                 deleteDBFiles(this.#dbPath);
                 cleanOrphanedWALFiles(this.#dbPath);
                 try {
-                    db = new Database(this.#dbPath, { timeout: 30000 });
-                    applyWALPragmas(db);
+                    db = withRetry(openOnce);
                 }
                 catch (retryErr) {
-                    throw new Error(`Failed to create fresh DB after deleting corrupt file: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`);
+                    // Preserve the existing corruption-retry wrap message, enriched
+                    // with op + path + code so the tool error is never bare.
+                    throw storeFailure("store.open", retryErr, this.#dbPath, `Failed to create fresh DB after deleting corrupt file: ${errorMessage(retryErr)}`);
                 }
             }
             else {
-                throw err;
+                // Transient-retry exhaustion or a non-transient open failure —
+                // either way the caller gets op + path + code, and stderr gets a
+                // [context-mode:db] line (deduped).
+                throw storeFailure("store.open", err, this.#dbPath);
             }
         }
         this.#db = db;
-        this.#initSchema();
-        this.#prepareStatements();
+        try {
+            this.#initSchema();
+            this.#prepareStatements();
+        }
+        catch (err) {
+            // The connection is already open here, so there is no retry contract
+            // for schema init — but the failure must not be silent: log the
+            // [context-mode:db] line and rethrow with op + path + code context.
+            throw storeFailure("store.initSchema", err, this.#dbPath);
+        }
     }
     /** Delete this session's DB files. Call on process exit. */
     cleanup() {
@@ -781,7 +862,16 @@ export class ContentStore {
         // Stale detection: store file_path + SHA-256 for file-backed sources
         const filePath = path ?? undefined;
         const contentHash = filePath ? createHash("sha256").update(text).digest("hex") : undefined;
-        return withRetry(() => this.#insertChunks(chunks, label, text, filePath, contentHash, attribution));
+        // withRetry absorbs transient SQLITE_BUSY/SQLITE_IOERR with exponential
+        // backoff; on exhaustion the failure is logged ([context-mode:db]) and
+        // rethrown with op + path + code so the tool error is never a bare
+        // "disk I/O error".
+        try {
+            return withRetry(() => this.#insertChunks(chunks, label, text, filePath, contentHash, attribution));
+        }
+        catch (err) {
+            throw storeFailure("store.index", err, this.#dbPath);
+        }
     }
     // ── Index Directory (#687) ──
     /**
@@ -836,10 +926,25 @@ export class ContentStore {
      */
     indexPlainText(content, source, linesPerChunk = 20, attribution, maxChunkBytes = MAX_CHUNK_BYTES) {
         if (!content || content.trim().length === 0) {
-            return this.#insertChunks([], source, "", undefined, undefined, attribution);
+            // Empty fast path still writes to the DB (a 0-chunk source row for
+            // dedup bookkeeping), so it gets the same retry + failure-context
+            // contract as the regular write path instead of bypassing both.
+            // indexJSON("") and its 0-chunk fallbacks delegate to this method,
+            // which routes them through the same contract.
+            try {
+                return withRetry(() => this.#insertChunks([], source, "", undefined, undefined, attribution));
+            }
+            catch (err) {
+                throw storeFailure("store.indexPlainText", err, this.#dbPath);
+            }
         }
         const chunks = this.#chunkPlainText(content, linesPerChunk, maxChunkBytes);
-        return withRetry(() => this.#insertChunks(chunks.map((c) => ({ ...c, hasCode: false })), source, content, undefined, undefined, attribution));
+        try {
+            return withRetry(() => this.#insertChunks(chunks.map((c) => ({ ...c, hasCode: false })), source, content, undefined, undefined, attribution));
+        }
+        catch (err) {
+            throw storeFailure("store.indexPlainText", err, this.#dbPath);
+        }
     }
     // ── Index JSON ──
     /**
@@ -865,7 +970,12 @@ export class ContentStore {
         if (chunks.length === 0) {
             return this.indexPlainText(content, source, undefined, attribution, maxChunkBytes);
         }
-        return withRetry(() => this.#insertChunks(chunks, source, content, undefined, undefined, attribution));
+        try {
+            return withRetry(() => this.#insertChunks(chunks, source, content, undefined, undefined, attribution));
+        }
+        catch (err) {
+            throw storeFailure("store.indexJSON", err, this.#dbPath);
+        }
     }
     // ── Shared DB Insertion ──
     /**
@@ -970,7 +1080,12 @@ export class ContentStore {
             stmt = this.#stmtSearchPorter;
             params = [sanitized, limit];
         }
-        return withRetry(() => this.#mapSearchRows(stmt.all(...params)));
+        try {
+            return withRetry(() => this.#mapSearchRows(stmt.all(...params)));
+        }
+        catch (err) {
+            throw storeFailure("store.search", err, this.#dbPath);
+        }
     }
     // ── Trigram Search (Layer 2) ──
     searchTrigram(query, limit = 3, source, mode = "AND", contentType, sourceMatchMode = "like") {
@@ -999,7 +1114,12 @@ export class ContentStore {
             stmt = this.#stmtSearchTrigram;
             params = [sanitized, limit];
         }
-        return withRetry(() => this.#mapSearchRows(stmt.all(...params)));
+        try {
+            return withRetry(() => this.#mapSearchRows(stmt.all(...params)));
+        }
+        catch (err) {
+            throw storeFailure("store.searchTrigram", err, this.#dbPath);
+        }
     }
     // ── Fuzzy Correction (Layer 3) ──
     fuzzyCorrect(query) {
@@ -1014,7 +1134,17 @@ export class ContentStore {
             return cached;
         }
         const maxDist = maxEditDistance(word.length);
-        const candidates = this.#stmtFuzzyVocab.all(word.length - maxDist, word.length + maxDist);
+        let candidates;
+        try {
+            // The vocab lookup is a read whose raw driver errors used to
+            // propagate unclassified through the search fallback — same retry +
+            // [context-mode:db] logging + op/path/code context as the rest of
+            // the store.
+            candidates = withRetry(() => this.#stmtFuzzyVocab.all(word.length - maxDist, word.length + maxDist));
+        }
+        catch (err) {
+            throw storeFailure("store.fuzzyCorrect", err, this.#dbPath);
+        }
         let bestWord = null;
         let bestDist = maxDist + 1;
         let exactMatch = false;
@@ -1176,7 +1306,16 @@ export class ContentStore {
      */
     #refreshStaleSources() {
         this.lastRefreshCount = 0;
-        const sources = this.#db.prepare("SELECT label, file_path, content_hash, indexed_at FROM sources WHERE file_path IS NOT NULL").all();
+        let sources;
+        try {
+            // Staleness scan is a read, but it runs ahead of every search — a
+            // transient IOERR here gets the same retry, and exhaustion the same
+            // op/path/code context, as the write paths.
+            sources = withRetry(() => this.#db.prepare("SELECT label, file_path, content_hash, indexed_at FROM sources WHERE file_path IS NOT NULL").all());
+        }
+        catch (err) {
+            throw storeFailure("store.refreshStaleSources", err, this.#dbPath);
+        }
         for (const src of sources) {
             try {
                 if (!existsSync(src.file_path))
@@ -1216,20 +1355,46 @@ export class ContentStore {
                 this.index({ content: newContent, path: src.file_path, source: src.label });
                 this.lastRefreshCount++;
             }
-            catch {
-                // Graceful degradation — never break search for stale detection
+            catch (err) {
+                // Graceful degradation — never break search for stale detection.
+                // But the failure (a failed re-index write, a vanished file) is no
+                // longer silent. Errors already enriched by an inner store op carry
+                // the kDbErrorLogged marker: their [context-mode:db] line was
+                // already emitted under the owning op (e.g. store.index) — logging
+                // again here would emit a second, code-stripped line for the same
+                // failure.
+                if (!isDbErrorAlreadyLogged(err)) {
+                    logDbError("store.refreshStaleSources", err, this.#dbPath);
+                }
             }
         }
     }
     // ── Sources ──
     getSourceMeta(label) {
-        const row = this.#stmtSourceMeta.get(label);
+        // Raw stmt.get() — the ctx_fetch_and_index cache probe (server.ts
+        // fetchOneUrl) runs through here BEFORE any fetch/indexing, so an
+        // IOERR used to reject the whole batch as a bare driver error with
+        // nothing in any log. Same retry + context contract as the writes.
+        let row;
+        try {
+            row = withRetry(() => this.#stmtSourceMeta.get(label));
+        }
+        catch (err) {
+            throw storeFailure("store.getSourceMeta", err, this.#dbPath);
+        }
         if (!row)
             return null;
         return { label: row.label, chunkCount: row.chunk_count, codeChunkCount: row.code_chunk_count, indexedAt: row.indexed_at, filePath: row.file_path ?? null, contentHash: row.content_hash ?? null };
     }
     listSources() {
-        return this.#stmtListSources.all();
+        // ctx_search's no-results path lists sources here — same retry +
+        // context contract as the write paths.
+        try {
+            return withRetry(() => this.#stmtListSources.all());
+        }
+        catch (err) {
+            throw storeFailure("store.listSources", err, this.#dbPath);
+        }
     }
     /**
      * Aggregate snapshot of the persistent content store. Returns total
@@ -1238,9 +1403,15 @@ export class ContentStore {
      * round trip instead of inferring it from snapshot diffs.
      */
     getIndexState() {
-        const row = this.#db
-            .prepare("SELECT COALESCE(SUM(chunk_count), 0) AS total_chunks, COUNT(*) AS total_sources, MAX(indexed_at) AS last_indexed_at FROM sources")
-            .get();
+        let row;
+        try {
+            row = withRetry(() => this.#db
+                .prepare("SELECT COALESCE(SUM(chunk_count), 0) AS total_chunks, COUNT(*) AS total_sources, MAX(indexed_at) AS last_indexed_at FROM sources")
+                .get());
+        }
+        catch (err) {
+            throw storeFailure("store.getIndexState", err, this.#dbPath);
+        }
         return {
             totalChunks: row.total_chunks ?? 0,
             totalSources: row.total_sources ?? 0,
@@ -1252,7 +1423,15 @@ export class ContentStore {
      * Use this for inventory/listing where you need all sections, not search.
      */
     getChunksBySource(sourceId) {
-        const rows = this.#stmtChunksBySource.all(sourceId);
+        let rows;
+        try {
+            // Batch/introspection path (ctx_index directory mode, chunk listing)
+            // — same retry + context contract as the write paths.
+            rows = withRetry(() => this.#stmtChunksBySource.all(sourceId));
+        }
+        catch (err) {
+            throw storeFailure("store.getChunksBySource", err, this.#dbPath);
+        }
         return rows.map((r) => ({
             title: r.title,
             content: r.content,
@@ -1263,23 +1442,41 @@ export class ContentStore {
     }
     // ── Vocabulary ──
     getDistinctiveTerms(sourceId, maxTerms = 40) {
-        const stats = this.#stmtSourceChunkCount.get(sourceId);
+        let stats;
+        try {
+            stats = withRetry(() => this.#stmtSourceChunkCount.get(sourceId));
+        }
+        catch (err) {
+            throw storeFailure("store.getDistinctiveTerms", err, this.#dbPath);
+        }
         if (!stats || stats.chunk_count < 3)
             return [];
         const totalChunks = stats.chunk_count;
         const minAppearances = 2;
         const maxAppearances = Math.max(3, Math.ceil(totalChunks * 0.4));
-        // Stream chunks one at a time to avoid loading all content into memory
-        // Count document frequency (how many sections contain each word)
-        const docFreq = new Map();
-        for (const row of this.#stmtChunkContent.iterate(sourceId)) {
-            const words = new Set(row.content
-                .toLowerCase()
-                .split(/[^\p{L}\p{N}_-]+/u)
-                .filter((w) => w.length >= 3 && !STOPWORDS.has(w)));
-            for (const word of words) {
-                docFreq.set(word, (docFreq.get(word) ?? 0) + 1);
+        // Stream chunks one at a time to avoid loading all content into memory.
+        // Count document frequency (how many sections contain each word).
+        // The whole aggregation is wrapped so a transient IOERR mid-stream
+        // retries from a clean slate — docFreq is rebuilt, never half-populated.
+        const collectDocFreq = () => {
+            const docFreq = new Map();
+            for (const row of this.#stmtChunkContent.iterate(sourceId)) {
+                const words = new Set(row.content
+                    .toLowerCase()
+                    .split(/[^\p{L}\p{N}_-]+/u)
+                    .filter((w) => w.length >= 3 && !STOPWORDS.has(w)));
+                for (const word of words) {
+                    docFreq.set(word, (docFreq.get(word) ?? 0) + 1);
+                }
             }
+            return docFreq;
+        };
+        let docFreq;
+        try {
+            docFreq = withRetry(collectDocFreq);
+        }
+        catch (err) {
+            throw storeFailure("store.getDistinctiveTerms", err, this.#dbPath);
         }
         const filtered = Array.from(docFreq.entries())
             .filter(([, count]) => count >= minAppearances && count <= maxAppearances);
@@ -1317,8 +1514,16 @@ export class ContentStore {
             this.#stmtCleanupChunksTrigram.run(days);
             return this.#stmtCleanupSources.run(days);
         });
-        const info = cleanup(maxAgeDays);
-        return info.changes;
+        // Write path — same transient-IOERR/BUSY retry + failure context as
+        // store.index. better-sqlite3 and the db-base adapters roll the
+        // transaction back on throw, so re-invoking after a retry is safe.
+        try {
+            const info = withRetry(() => cleanup(maxAgeDays));
+            return info.changes;
+        }
+        catch (err) {
+            throw storeFailure("store.cleanupStaleSources", err, this.#dbPath);
+        }
     }
     /** Get DB file size in bytes. */
     getDBSizeBytes() {
@@ -1335,7 +1540,11 @@ export class ContentStore {
             this.#db.exec("INSERT INTO chunks(chunks) VALUES('optimize')");
             this.#db.exec("INSERT INTO chunks_trigram(chunks_trigram) VALUES('optimize')");
         }
-        catch { /* best effort — don't block indexing */ }
+        catch (err) {
+            // Best effort — don't block indexing, but don't stay silent either:
+            // 'optimize' is a write and its failures were previously invisible.
+            logDbError("store.optimizeFTS", err, this.#dbPath);
+        }
     }
     close() {
         this.#optimizeFTS(); // defragment before close