@4da/mcp-server 6.0.2 → 6.2.0

package/dist/db.d.ts

@@ -1,11 +1,29 @@
 /**
  * Database module for 4DA MCP Server
  *
- * Read-only access to the 4DA SQLite database.
- * Only the record_feedback function performs writes.
+ * The desktop app's database (`4da.db`) is opened READ-ONLY
+ * (`{ readonly: true, fileMustExist: true }`) for everything the server reads.
+ * The app owns that file and its migrations: the server never creates or
+ * alters anything in it. It writes rows into exactly the app-owned tables its
+ * tools exist to write (APP_WRITABLE_TABLES: decisions, agent memory, feedback
+ * and interactions, which the app's calibration and decision UI read), through
+ * a separate write connection opened only for those statements (writerFor).
+ *
+ * Everything else the server writes goes to files it owns, under
+ * serverDataDir():
+ * - `cache.db`: registry, OSV and changelog responses (LiveCache).
+ * - `standalone.db`: the standalone database when no app is installed, and
+ *   the fallback for a record the app's schema cannot hold (schema drift).
+ *
+ * Until 6.0.2 the server created a `live_cache` table inside the app's
+ * database (2,774 rows on one machine, 2026-10-07) and added `embedding`
+ * columns to two app tables when an embedding provider was set.
+ */
+import { type SqliteDatabase } from "./sqlite-driver.js";
+/**
+ * Null when a SQLite driver (node:sqlite, or better-sqlite3 with a working
+ * native module) can open a database here; otherwise why not, with the fix.
  */
-import type BetterSqlite3 from "better-sqlite3";
-/** Null when better-sqlite3 can open a database here; otherwise why not, with the fix. */
 export declare function nativeBindingProblem(): string | null;
 import type { RelevantItem, UserContext, FeedbackAction, FeedbackResult } from "./types.js";
 import type { ProjectScanResult } from "./project-scanner.js";
@@ -30,9 +48,17 @@ export declare function desktopAppDbPaths(platform?: NodeJS.Platform, env?: Node
  * in, so agent memory and decisions did not follow the user between projects.
  */
 export declare function standaloneDbPath(): string;
+/**
+ * The directory holding every file this server writes: a per-user data
+ * directory (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp`,
+ * `$XDG_DATA_HOME/4da-mcp`). FOURDA_MCP_HOME overrides it (tests use a temp dir).
+ */
+export declare function serverDataDir(): string;
+/** The server's response cache (registry, OSV, changelogs). Disposable: deleting it costs refetches only. */
+export declare function serverCacheDbPath(): string;
 /**
  * Whether an error says the database file itself is unreadable: not SQLite at
- * all, or damaged. better-sqlite3 reports these as SQLITE_NOTADB ("file is not
+ * all, or damaged. SQLite reports these as SQLITE_NOTADB ("file is not
  * a database") and SQLITE_CORRUPT ("database disk image is malformed").
  */
 export declare function isUnreadableDbError(error: unknown): boolean;
@@ -105,6 +131,20 @@ export declare function dedupeByTitle<T extends {
  * the `is_direct` standalone-schema gap slipped through precisely because the
  * two modes were only ever tested separately.
  */
+/**
+ * The app-owned tables this server is designed to write when the desktop app
+ * is installed: decisions (decision_memory), agent memory (agent_memory) and
+ * feedback (record_feedback -> the app's calibration). Nothing else in the
+ * app's database is ever written, and nothing in it is created or altered.
+ */
+export declare const APP_WRITABLE_TABLES: readonly ["developer_decisions", "agent_memory", "interactions", "feedback"];
+export type AppWritableTable = (typeof APP_WRITABLE_TABLES)[number];
+export interface WriteTarget {
+    raw: SqliteDatabase;
+    /** database = the open (standalone) database; app = the app's table; server_store = fallback on schema drift. */
+    target: "database" | "app" | "server_store";
+    note?: string;
+}
 export declare const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, project_path, is_dev, is_direct FROM project_dependencies";
 /**
  * 4DA Database accessor
@@ -120,6 +160,30 @@ export declare class FourDADatabase {
      * (no pre-existing 4DA desktop app database found).
      */
     get isStandalone(): boolean;
+    /** True for the desktop app's database, which this connection only reads. */
+    get isReadOnly(): boolean;
+    private memoryStore;
+    private appWriter;
+    /**
+     * The connection a record into one of the app-owned tables this server is
+     * designed to write (APP_WRITABLE_TABLES) goes through, and where it lands.
+     *
+     * - Standalone database: the database itself.
+     * - The desktop app's database: a SEPARATE writable connection, opened on
+     *   first use for these statements only (the main connection stays
+     *   read-only), with a busy timeout so a write waits briefly for the app
+     *   instead of failing. Only when the app's table has every column the
+     *   statement names; nothing is ever created or altered in the app's file.
+     * - Schema drift (table or column missing in the app): the record goes to
+     *   this server's own store (standaloneDbPath()) and `note` says so.
+     */
+    writerFor(table: AppWritableTable, columns: readonly string[]): WriteTarget;
+    /**
+     * The server's own store: its standalone database (standaloneDbPath()).
+     * Used for records the app's schema cannot hold (see writerFor). A
+     * standalone database is its own store.
+     */
+    getMemoryStore(): FourDADatabase;
     /**
      * Validate that a database file exists and is a readable SQLite database.
      *
@@ -128,7 +192,7 @@ export declare class FourDADatabase {
      * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
      * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
      * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
-     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * and growing) and, because the SQLite drivers are synchronous, it blocks the event
      * loop — running it on the startup path stalls the MCP stdio handshake until it
      * finishes, so the host's connect timeout can fire and the server looks like it
      * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
@@ -142,9 +206,9 @@ export declare class FourDADatabase {
         deep?: boolean;
     }): DatabaseValidationResult;
     /**
-     * Get the raw better-sqlite3 database instance for custom queries
+     * Get the raw database connection (sqlite-driver.ts) for custom queries
      */
-    getRawDb(): BetterSqlite3.Database;
+    getRawDb(): SqliteDatabase;
     /**
      * Close the database connection
      */
@@ -192,6 +256,7 @@ export declare class FourDADatabase {
     getFreshness(): DataFreshness;
     /** `MAX(sources.last_fetch)`, tolerant of a missing `sources` table (returns null). */
     private safeMaxLastFetch;
+    hasTable(table: string): boolean;
     hasColumn(table: string, column: string): boolean;
     /**
      * Idempotently add a column to a table if it does not already exist.

package/dist/db.js

@@ -2,24 +2,35 @@
 /**
  * Database module for 4DA MCP Server
  *
- * Read-only access to the 4DA SQLite database.
- * Only the record_feedback function performs writes.
+ * The desktop app's database (`4da.db`) is opened READ-ONLY
+ * (`{ readonly: true, fileMustExist: true }`) for everything the server reads.
+ * The app owns that file and its migrations: the server never creates or
+ * alters anything in it. It writes rows into exactly the app-owned tables its
+ * tools exist to write (APP_WRITABLE_TABLES: decisions, agent memory, feedback
+ * and interactions, which the app's calibration and decision UI read), through
+ * a separate write connection opened only for those statements (writerFor).
+ *
+ * Everything else the server writes goes to files it owns, under
+ * serverDataDir():
+ * - `cache.db`: registry, OSV and changelog responses (LiveCache).
+ * - `standalone.db`: the standalone database when no app is installed, and
+ *   the fallback for a record the app's schema cannot hold (schema drift).
+ *
+ * Until 6.0.2 the server created a `live_cache` table inside the app's
+ * database (2,774 rows on one machine, 2026-10-07) and added `embedding`
+ * columns to two app tables when an embedding provider was set.
  */
 import path from "path";
 import * as fs from "fs";
 import * as os from "os";
-import { checkNativeBindings, isNativeBindingError, nativeBindingMessage } from "./native-bindings.js";
-let Database;
-try {
-    Database = (await import("better-sqlite3")).default;
-}
-catch (err) {
-    console.error(`\n  [4DA] ${nativeBindingMessage(err)}\n`);
-    process.exit(1);
-}
-/** Null when better-sqlite3 can open a database here; otherwise why not, with the fix. */
+import { openDatabase, sqliteDriverStatus, SqliteUnavailableError, } from "./sqlite-driver.js";
+import { isNativeBindingError, nativeBindingMessage } from "./native-bindings.js";
+/**
+ * Null when a SQLite driver (node:sqlite, or better-sqlite3 with a working
+ * native module) can open a database here; otherwise why not, with the fix.
+ */
 export function nativeBindingProblem() {
-    return checkNativeBindings(Database);
+    return sqliteDriverStatus().problem;
 }
 import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
@@ -93,17 +104,32 @@ export function desktopAppDbPaths(platform = process.platform, env = process.env
  * in, so agent memory and decisions did not follow the user between projects.
  */
 export function standaloneDbPath() {
+    return path.join(serverDataDir(), "standalone.db");
+}
+/**
+ * The directory holding every file this server writes: a per-user data
+ * directory (`%LOCALAPPDATA%\4da-mcp`, `~/Library/Application Support/4da-mcp`,
+ * `$XDG_DATA_HOME/4da-mcp`). FOURDA_MCP_HOME overrides it (tests use a temp dir).
+ */
+export function serverDataDir() {
+    const override = process.env.FOURDA_MCP_HOME?.trim();
+    if (override)
+        return override;
     const home = os.homedir();
     const base = process.platform === "win32"
         ? process.env.LOCALAPPDATA || path.join(home, "AppData", "Local")
         : process.platform === "darwin"
             ? path.join(home, "Library", "Application Support")
             : process.env.XDG_DATA_HOME || path.join(home, ".local", "share");
-    return path.join(base, "4da-mcp", "standalone.db");
+    return path.join(base, "4da-mcp");
+}
+/** The server's response cache (registry, OSV, changelogs). Disposable: deleting it costs refetches only. */
+export function serverCacheDbPath() {
+    return path.join(serverDataDir(), "cache.db");
 }
 /**
  * Whether an error says the database file itself is unreadable: not SQLite at
- * all, or damaged. better-sqlite3 reports these as SQLITE_NOTADB ("file is not
+ * all, or damaged. SQLite reports these as SQLITE_NOTADB ("file is not
  * a database") and SQLITE_CORRUPT ("database disk image is malformed").
  */
 export function isUnreadableDbError(error) {
@@ -222,6 +248,15 @@ export function dedupeByTitle(items, threshold = 0.6) {
  * the `is_direct` standalone-schema gap slipped through precisely because the
  * two modes were only ever tested separately.
  */
+/**
+ * The app-owned tables this server is designed to write when the desktop app
+ * is installed: decisions (decision_memory), agent memory (agent_memory) and
+ * feedback (record_feedback -> the app's calibration). Nothing else in the
+ * app's database is ever written, and nothing in it is created or altered.
+ */
+export const APP_WRITABLE_TABLES = ["developer_decisions", "agent_memory", "interactions", "feedback"];
+/** How long a write into the app's database waits for the app's own lock. */
+const APP_WRITE_BUSY_TIMEOUT_MS = 3000;
 export const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, project_path, is_dev, is_direct FROM project_dependencies";
 /**
  * 4DA Database accessor
@@ -246,9 +281,26 @@ export class FourDADatabase {
             }
         }
         let opened = null;
+        let standalone = isNew;
         try {
-            opened = new Database(absolutePath, { readonly: false }); // Need write for feedback
-            opened.pragma("journal_mode = WAL");
+            if (isNew) {
+                opened = openDatabase(absolutePath, { readonly: false });
+                opened.pragma("journal_mode = WAL");
+            }
+            else {
+                // An existing file is opened read-only first. Reading the schema here
+                // makes a damaged or non-SQLite file fail now, with the message below.
+                opened = openDatabase(absolutePath, { readonly: true, fileMustExist: true });
+                opened.prepare("SELECT name FROM sqlite_master WHERE type='table' LIMIT 1").all();
+                standalone = detectStandalone(opened);
+                if (standalone) {
+                    // This server's own database: reopen it writable.
+                    opened.close();
+                    opened = null;
+                    opened = openDatabase(absolutePath, { readonly: false, fileMustExist: true });
+                    opened.pragma("journal_mode = WAL");
+                }
+            }
         }
         catch (error) {
             // Close the handle a failed pragma leaves open: every tool call retries
@@ -260,6 +312,8 @@ export class FourDADatabase {
             catch {
                 // Nothing to close when the open itself failed.
             }
+            if (error instanceof SqliteUnavailableError)
+                throw error;
             throw new Error(isNativeBindingError(error)
                 ? nativeBindingMessage(error)
                 : isUnreadableDbError(error)
@@ -268,25 +322,22 @@ export class FourDADatabase {
         }
         this.db = opened;
         this.dbPath = absolutePath;
+        this._isStandalone = standalone;
+        // The desktop app's database: read-only, and nothing below runs against it.
+        if (!standalone)
+            return;
         // Standalone mode: create schema for a brand-new database, and recognise
         // an existing standalone database as one on every later session.
-        if (isNew) {
+        if (isNew)
             this.createMinimalSchema();
-            this._isStandalone = true;
-        }
-        else {
-            this._isStandalone = detectStandalone(this.db);
-        }
-        if (this._isStandalone) {
-            this.db.exec(`CREATE TABLE IF NOT EXISTS ${STANDALONE_MARKER} (created_at TEXT DEFAULT (datetime('now')))`);
-        }
+        this.db.exec(`CREATE TABLE IF NOT EXISTS ${STANDALONE_MARKER} (created_at TEXT DEFAULT (datetime('now')))`);
         // Schema upgrade for standalone databases created before `is_direct` was
         // added to the minimal schema: the full-DB init branch queries that column
         // (DEPENDENCY_GROUP_QUERY), and without it session 2+ of a standalone
         // install throws, gets caught, and silently disables vulnerability_scan /
         // dependency_health / upgrade_planner. Scanner-inserted manifest deps are
-        // direct by definition, so DEFAULT 1 backfills correctly. The desktop
-        // app's database already has the column — no-op there.
+        // direct by definition, so DEFAULT 1 backfills correctly. Standalone
+        // databases only: the desktop app's database is never altered.
         try {
             const hasDepsTable = this.db
                 .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='project_dependencies'")
@@ -306,6 +357,67 @@ export class FourDADatabase {
     get isStandalone() {
         return this._isStandalone;
     }
+    /** True for the desktop app's database, which this connection only reads. */
+    get isReadOnly() {
+        return this.db.readonly;
+    }
+    memoryStore = null;
+    appWriter = null;
+    /**
+     * The connection a record into one of the app-owned tables this server is
+     * designed to write (APP_WRITABLE_TABLES) goes through, and where it lands.
+     *
+     * - Standalone database: the database itself.
+     * - The desktop app's database: a SEPARATE writable connection, opened on
+     *   first use for these statements only (the main connection stays
+     *   read-only), with a busy timeout so a write waits briefly for the app
+     *   instead of failing. Only when the app's table has every column the
+     *   statement names; nothing is ever created or altered in the app's file.
+     * - Schema drift (table or column missing in the app): the record goes to
+     *   this server's own store (standaloneDbPath()) and `note` says so.
+     */
+    writerFor(table, columns) {
+        if (!this.isReadOnly)
+            return { raw: this.db, target: "database" };
+        const missing = columns.filter((c) => !this.hasColumn(table, c));
+        if (missing.length === 0) {
+            if (!this.appWriter?.open) {
+                const writer = openDatabase(this.dbPath, { fileMustExist: true });
+                writer.pragma(`busy_timeout = ${APP_WRITE_BUSY_TIMEOUT_MS}`);
+                this.appWriter = writer;
+            }
+            return { raw: this.appWriter, target: "app" };
+        }
+        const store = this.getMemoryStore();
+        return {
+            raw: store.db,
+            target: "server_store",
+            note: `The desktop app's ${table} table ${this.hasTable(table) ? `has no ${missing.join(", ")} column` : "does not exist"} ` +
+                `in this app version, so this was recorded in the server's own store (${store.dbPath}) instead; the app will not see it. ` +
+                `The server never changes the app's schema.`,
+        };
+    }
+    /**
+     * The server's own store: its standalone database (standaloneDbPath()).
+     * Used for records the app's schema cannot hold (see writerFor). A
+     * standalone database is its own store.
+     */
+    getMemoryStore() {
+        if (!this.isReadOnly)
+            return this;
+        if (!this.memoryStore) {
+            const storePath = standaloneDbPath();
+            if (path.resolve(storePath) === path.resolve(this.dbPath)) {
+                throw new Error(`The server's store ${storePath} is open read-only; it cannot record.`);
+            }
+            const store = new FourDADatabase(storePath);
+            // Rows here reference the app's items and decisions by id; those rows
+            // live in the other file, so foreign keys cannot be enforced here.
+            store.db.pragma("foreign_keys = OFF");
+            this.memoryStore = store;
+        }
+        return this.memoryStore;
+    }
     /**
      * Validate that a database file exists and is a readable SQLite database.
      *
@@ -314,7 +426,7 @@ export class FourDADatabase {
      * By default this runs a CHEAP probe (open + list tables, ~0.1s) which surfaces
      * a missing, locked, or corrupt-header file. It deliberately does NOT run a full
      * `PRAGMA integrity_check`: that is an O(database-size) scan (~11s on a 1.7 GB DB,
-     * and growing) and, because better-sqlite3 is synchronous, it blocks the event
+     * and growing) and, because the SQLite drivers are synchronous, it blocks the event
      * loop — running it on the startup path stalls the MCP stdio handshake until it
      * finishes, so the host's connect timeout can fire and the server looks like it
      * "failed to start". Pass `{ deep: true }` for the full integrity_check on the
@@ -339,7 +451,7 @@ export class FourDADatabase {
         }
         let testDb = null;
         try {
-            testDb = new Database(absolutePath, { readonly: true });
+            testDb = openDatabase(absolutePath, { readonly: true, fileMustExist: true });
             // Deep, opt-in integrity check (slow: full-database scan). Only on --doctor.
             if (opts?.deep) {
                 const integrityResult = testDb.pragma("integrity_check");
@@ -384,7 +496,7 @@ export class FourDADatabase {
         }
     }
     /**
-     * Get the raw better-sqlite3 database instance for custom queries
+     * Get the raw database connection (sqlite-driver.ts) for custom queries
      */
     getRawDb() {
         return this.db;
@@ -393,6 +505,11 @@ export class FourDADatabase {
      * Close the database connection
      */
     close() {
+        this.memoryStore?.close();
+        this.memoryStore = null;
+        if (this.appWriter?.open)
+            this.appWriter.close();
+        this.appWriter = null;
         this.db.close();
     }
     // ===========================================================================
@@ -908,6 +1025,14 @@ export class FourDADatabase {
             return null;
         }
     }
+    hasTable(table) {
+        try {
+            return this.db.pragma(`table_info(${table})`).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
     hasColumn(table, column) {
         try {
             const cols = this.db.pragma(`table_info(${table})`);
@@ -926,6 +1051,9 @@ export class FourDADatabase {
     ensureColumn(table, column, type) {
         if (this.hasColumn(table, column))
             return;
+        if (this.isReadOnly) {
+            throw new Error(`${this.dbPath} is the desktop app's database, which this server never alters (${table}.${column}).`);
+        }
         this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
     }
     /**
@@ -1274,29 +1402,38 @@ export class FourDADatabase {
         };
         const label = relevanceLabel[action];
         try {
-            if (label !== undefined)
+            // Into the app's own interactions/feedback tables (the app's calibration
+            // reads them) through the separate write connection; on schema drift,
+            // into the server's store with a note. See writerFor.
+            if (!this.isReadOnly && label !== undefined)
                 this.ensureFeedbackTable();
-            const insertInteraction = this.db.prepare(`
+            const interactionsTo = this.writerFor("interactions", ["item_id", "action_type", "item_source", "signal_strength", "timestamp"]);
+            const feedbackTo = label !== undefined ? this.writerFor("feedback", ["source_item_id", "relevant"]) : null;
+            if (interactionsTo.target === "server_store" || feedbackTo?.target === "server_store") {
+                this.getMemoryStore().ensureFeedbackTable();
+            }
+            const insertInteraction = interactionsTo.raw.prepare(`
         INSERT INTO interactions (item_id, action_type, item_source, signal_strength, timestamp)
         VALUES (?, ?, ?, ?, datetime('now'))
       `);
-            const write = this.db.transaction(() => {
+            const insertFeedback = feedbackTo?.raw.prepare(`INSERT INTO feedback (source_item_id, relevant) VALUES (?, ?)`);
+            // One short transaction when both rows go to the same file.
+            const write = () => {
                 const r = insertInteraction.run(itemId, action, row.source_type, signalStrength[action]);
-                if (label !== undefined) {
-                    this.db
-                        .prepare(`INSERT INTO feedback (source_item_id, relevant) VALUES (?, ?)`)
-                        .run(itemId, label);
-                }
+                insertFeedback?.run(itemId, label);
                 return r;
-            });
-            const result = write();
+            };
+            const result = feedbackTo && feedbackTo.raw !== interactionsTo.raw ? write() : interactionsTo.raw.transaction(write)();
+            const notes = [interactionsTo.note, feedbackTo?.note].filter((n) => Boolean(n));
+            const where = notes.length > 0 ? ` (${[...new Set(notes)].join(" ")})` : "";
             return {
                 success: true,
-                message: label === undefined
+                message: (label === undefined
                     ? `Recorded ${action} feedback for item ${itemId}`
-                    : `Recorded ${action} feedback for item ${itemId} (relevance label: ${label === 1 ? "relevant" : "not relevant"})`,
+                    : `Recorded ${action} feedback for item ${itemId} (relevance label: ${label === 1 ? "relevant" : "not relevant"})`) + where,
                 interaction_id: result.lastInsertRowid,
                 relevance_label: label === undefined ? null : label === 1,
+                ...(notes.length > 0 ? { _meta: { written_to: "server_store", note: [...new Set(notes)].join(" ") } } : {}),
             };
         }
         catch (error) {

package/dist/doctor.d.ts

@@ -3,7 +3,7 @@
  *
  * Validates that the MCP server can run correctly:
  * 1. Node.js version is sufficient
- * 2. Native bindings (better-sqlite3) load successfully
+ * 2. A SQLite driver opens a database (node:sqlite, else better-sqlite3)
  * 3. Database is found and readable
  * 4. LLM providers are configured (optional)
  *

package/dist/doctor.js

@@ -4,7 +4,7 @@
  *
  * Validates that the MCP server can run correctly:
  * 1. Node.js version is sufficient
- * 2. Native bindings (better-sqlite3) load successfully
+ * 2. A SQLite driver opens a database (node:sqlite, else better-sqlite3)
  * 3. Database is found and readable
  * 4. LLM providers are configured (optional)
  *
@@ -13,7 +13,8 @@
  *   4da-mcp --doctor
  */
 import { existsSync } from "node:fs";
-import { FourDADatabase, nativeBindingProblem } from "./db.js";
+import { FourDADatabase } from "./db.js";
+import { NODE_SQLITE_MIN, sqliteDriverStatus } from "./sqlite-driver.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 export function runDoctor() {
     console.log("\n  4DA MCP Server — Doctor\n");
@@ -32,14 +33,19 @@ export function runDoctor() {
             ? `${nodeVersion} (>= ${nodeRequired} required)`
             : `${nodeVersion} — Node.js ${nodeRequired}+ required`,
     });
-    // 2. Native bindings — opening a database, not just importing the package:
-    // the import succeeds without the compiled module (npm 12 blocking its
-    // install script left none, and this check used to say "loaded").
-    const bindingProblem = nativeBindingProblem();
+    // 2. SQLite driver — opening a database, not just importing a package:
+    // better-sqlite3's import succeeds without its compiled module (npm 12
+    // blocking its install script left none, and this check used to say "loaded").
+    const sqlite = sqliteDriverStatus();
+    const passedOver = sqlite.rejected.map((r) => `${r.name} not used: ${r.reason}`).join("; ");
     checks.push({
-        name: "SQLite native bindings",
-        status: bindingProblem ? "fail" : "pass",
-        detail: bindingProblem ?? "better-sqlite3 opened an in-memory database",
+        name: "SQLite driver",
+        status: sqlite.driver ? "pass" : "fail",
+        detail: !sqlite.driver
+            ? (sqlite.problem ?? "no SQLite driver")
+            : sqlite.driver.name === "node:sqlite"
+                ? `node:sqlite (built into Node ${process.versions.node}) opened an in-memory database`
+                : `better-sqlite3 opened an in-memory database (${passedOver || `node:sqlite needs Node ${NODE_SQLITE_MIN}+`})`,
     });
     // 3. Database discovery — deep integrity_check is appropriate here: --doctor is
     // an explicit, user-invoked diagnostic where a slow full scan is expected. The

package/dist/embeddings.js

@@ -238,12 +238,24 @@ export async function semanticScores(db, table, query, items, config, opts = {})
     if (!queryVec) {
         return { semanticById: new Map(), queryEmbedded: false, embeddedCount: 0, newlyEmbedded: 0, model: tag };
     }
-    // Cache columns are optional and added lazily for databases that predate them.
-    db.ensureColumn(table, "embedding", "BLOB");
-    db.ensureColumn(table, "embedding_model", "TEXT");
-    const rawDb = db.getRawDb();
-    const stored = loadStoredEmbeddings(rawDb, table, items.map((i) => i.id), tag);
-    const updateStmt = rawDb.prepare(`UPDATE ${table} SET embedding = ?, embedding_model = ? WHERE id = ?`);
+    // Cache columns are optional. This server's own database gets them lazily;
+    // the desktop app's database is never altered, so there the cache is used
+    // only when the app's table already has both columns (written through the
+    // separate write connection, see FourDADatabase.writerFor), and vectors are
+    // otherwise computed per call and not stored.
+    const readOnly = db.isReadOnly === true;
+    let cacheDb = null;
+    if (!readOnly) {
+        db.ensureColumn(table, "embedding", "BLOB");
+        db.ensureColumn(table, "embedding_model", "TEXT");
+        cacheDb = db.getRawDb();
+    }
+    else if (db.hasColumn(table, "embedding") && db.hasColumn(table, "embedding_model")) {
+        const to = db.writerFor(table, ["id", "embedding", "embedding_model"]);
+        cacheDb = to.target === "app" ? to.raw : null;
+    }
+    const stored = cacheDb ? loadStoredEmbeddings(db.getRawDb(), table, items.map((i) => i.id), tag) : new Map();
+    const updateStmt = cacheDb?.prepare(`UPDATE ${table} SET embedding = ?, embedding_model = ? WHERE id = ?`);
     const maxNew = opts.maxNewEmbeds ?? DEFAULT_MAX_NEW_EMBEDS;
     const semanticById = new Map();
     let embeddedCount = 0;
@@ -254,7 +266,7 @@ export async function semanticScores(db, table, query, items, config, opts = {})
             vec = await embedText(item.text, config);
             if (vec) {
                 try {
-                    updateStmt.run(vectorToBlob(vec), tag, item.id);
+                    updateStmt?.run(vectorToBlob(vec), tag, item.id);
                 }
                 catch {
                     // Persisting the cache is best-effort; scoring still proceeds.

package/dist/gitignore.js

@@ -116,9 +116,15 @@ export class IgnoreRules {
             if (rule.base && !relPath.startsWith(`${rule.base}/`))
                 continue;
             const local = rule.base ? relPath.slice(rule.base.length + 1) : relPath;
-            if (rule.dirOnly && !isDir && !local.includes("/"))
-                continue;
-            if (!rule.regex.test(local))
+            if (rule.dirOnly && !isDir) {
+                // A `dir/` rule ignores a file only through a directory above it:
+                // `docs/api_reference/*/` matched docs/api_reference/requirements.txt
+                // itself, so langchain's docs requirements were never read.
+                const parent = local.includes("/") ? local.slice(0, local.lastIndexOf("/")) : null;
+                if (parent === null || !rule.regex.test(parent))
+                    continue;
+            }
+            else if (!rule.regex.test(local))
                 continue;
             if (rule.negated)
                 reincludable = true;