@4da/mcp-server 6.0.1 → 6.1.0

package/dist/db.js

@@ -2,59 +2,67 @@
 /**
  * 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 { fileURLToPath } from "node:url";
-import { dirname } from "node:path";
-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;
 }
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
 import { dbRecoveryNote, readDbRecoveredMarker, readEngineBlockMarker } from "./freshness-markers.js";
 /**
  * Resolve the database path by checking multiple locations in priority order:
  * 1. FOURDA_DB_PATH env var
- * 2. data/4da.db relative to cwd (development)
- * 3. data/4da.db relative to project root (mcp-4da-server is inside project root)
- * 4. Platform-specific Tauri app data dirs (production)
- * 5. Final fallback: data/4da.db relative to cwd
+ * 2. data/4da.db relative to cwd: the desktop app's development database,
+ *    when the server is started in a checkout of the app's repository
+ * 3. The deployed desktop app's database (desktopAppDbPaths)
+ * 4. Otherwise the standalone database (standaloneDbPath), created on first use
+ *
+ * Until 6.0.2 a step between 2 and 3 looked for data/4da.db two directories
+ * above this file, which found the app's database while this server was the
+ * app repository's mcp-4da-server/ folder. Since the server moved to its own
+ * repository (6.0.1) that resolves to node_modules/@4da/ or to the folder
+ * holding a clone, never to an app database, so it was removed.
  */
 function getDefaultDbPath() {
     // 1. Environment variable (highest priority)
     if (process.env.FOURDA_DB_PATH) {
         return process.env.FOURDA_DB_PATH;
     }
-    // 2. Relative to cwd (development)
+    // 2. Relative to cwd (the app repository's development database)
     const cwdPath = path.resolve(process.cwd(), "data", "4da.db");
     if (fs.existsSync(cwdPath)) {
         return cwdPath;
     }
-    // 3. Relative to project root (mcp-4da-server is inside project root)
-    const projectRootPath = path.resolve(__dirname, "..", "..", "data", "4da.db");
-    if (fs.existsSync(projectRootPath)) {
-        return projectRootPath;
-    }
-    // 4. The desktop app's own database, where the deployed app keeps it.
+    // 3. The desktop app's own database, where the deployed app keeps it.
     for (const appDataPath of desktopAppDbPaths()) {
         if (fs.existsSync(appDataPath))
             return appDataPath;
     }
-    // 5. No desktop database: the standalone database, in the user's data dir.
+    // 4. No desktop database: the standalone database, in the user's data dir.
     return standaloneDbPath();
 }
 /**
@@ -96,13 +104,60 @@ 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. SQLite reports these as SQLITE_NOTADB ("file is not
+ * a database") and SQLITE_CORRUPT ("database disk image is malformed").
+ */
+export function isUnreadableDbError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_NOTADB" || code === "SQLITE_CORRUPT")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /file is not a database|database disk image is malformed/i.test(message);
+}
+/**
+ * What to tell the user about an unreadable database. Every tool call used to
+ * answer with the bare SQLite text ("file is not a database"), with no way
+ * out. Nothing is deleted or moved automatically: the desktop app's database
+ * can be the user's whole corpus, and the standalone one holds their recorded
+ * decisions and agent memory.
+ */
+export function unreadableDbMessage(absolutePath, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const isStandaloneFile = path.resolve(absolutePath) === path.resolve(standaloneDbPath());
+    const remedy = isStandaloneFile
+        ? "It is this server's standalone database: move it aside (keep it if it holds decisions or agent " +
+            "memory you want) and the next call creates a new one."
+        : process.env.FOURDA_DB_PATH
+            ? "FOURDA_DB_PATH points at it: point it at a valid 4DA database, or unset it to use the default."
+            : "If it is the 4DA desktop app's database, start the app, which checks its database on startup. " +
+                "Do not delete it: it may be your only copy of the app's data.";
+    return (`The 4DA database at ${absolutePath} cannot be read (${detail}): the file is damaged or is not ` +
+        `a SQLite database. ${remedy} Run \`npx @4da/mcp-server --doctor\` for details.`);
 }
 /** Marker table written into every standalone database. */
 const STANDALONE_MARKER = "mcp_standalone";
@@ -193,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
@@ -200,6 +264,8 @@ export const DEPENDENCY_GROUP_QUERY = "SELECT DISTINCT package_name, language, p
 export class FourDADatabase {
     db;
     _isStandalone = false;
+    /** Absolute path of the open database file. */
+    dbPath;
     constructor(dbPath) {
         const resolvedPath = dbPath || getDefaultDbPath();
         // Resolve path - if relative, resolve from cwd
@@ -214,34 +280,64 @@ export class FourDADatabase {
                 fs.mkdirSync(dir, { recursive: true });
             }
         }
+        let opened = null;
+        let standalone = isNew;
         try {
-            this.db = new Database(absolutePath, { readonly: false }); // Need write for feedback
-            this.db.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
+            // the open, and on Windows each leaked handle also keeps the file locked
+            // against the move-aside the message below suggests.
+            try {
+                opened?.close();
+            }
+            catch {
+                // Nothing to close when the open itself failed.
+            }
+            if (error instanceof SqliteUnavailableError)
+                throw error;
             throw new Error(isNativeBindingError(error)
                 ? nativeBindingMessage(error)
-                : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
+                : isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open 4DA database at ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`);
         }
+        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'")
@@ -261,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.
      *
@@ -269,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
@@ -294,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");
@@ -302,8 +459,10 @@ export class FourDADatabase {
                 if (integrityStatus !== "ok") {
                     return {
                         valid: false,
-                        error: `Database integrity check failed: ${integrityStatus}. `
-                            + "The database file may be corrupt. Try deleting data/4da.db and restarting 4DA.",
+                        // It used to say "Try deleting data/4da.db": a path that is not
+                        // where the app keeps its database, and advice that destroys the
+                        // user's only copy of it.
+                        error: unreadableDbMessage(absolutePath, new Error(`integrity check failed: ${integrityStatus}`)),
                     };
                 }
             }
@@ -322,8 +481,9 @@ export class FourDADatabase {
         catch (error) {
             return {
                 valid: false,
-                error: `Failed to open database at ${absolutePath}: `
-                    + (error instanceof Error ? error.message : String(error)),
+                error: isUnreadableDbError(error)
+                    ? unreadableDbMessage(absolutePath, error)
+                    : `Failed to open database at ${absolutePath}: ` + (error instanceof Error ? error.message : String(error)),
             };
         }
         finally {
@@ -336,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;
@@ -345,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();
     }
     // ===========================================================================
@@ -860,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})`);
@@ -878,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}`);
     }
     /**
@@ -1226,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;