d365fo-mcp 1.15.0 → 1.16.1

package/dist/bridge/bridgeAdapter.d.ts

@@ -22,7 +22,7 @@
  */
 import type { BridgeClient } from './bridgeClient.js';
 import type { BridgeAttempt } from './bridgeFailure.js';
-import type { BridgeSmartTableResult } from './bridgeTypes.js';
+import type { BridgeCompletionResult, BridgeSmartTableResult } from './bridgeTypes.js';
 /** Standard MCP tool response shape */
 export interface ToolResult {
     content: Array<{
@@ -538,7 +538,39 @@ export declare function tryBridgeSecurityArtifact(bridge: BridgeClient | undefin
 export declare function tryBridgeMenuItem(bridge: BridgeClient | undefined, name: string, itemType?: string): Promise<ToolResult | null>;
 export declare function tryBridgeTableExtensions(bridge: BridgeClient | undefined, baseTableName: string): Promise<ToolResult | null>;
 export declare function tryBridgeCompletion(bridge: BridgeClient | undefined, symbolName: string, prefix?: string, ancestors?: string[]): Promise<ToolResult | null>;
+/**
+ * One line of a member list — NAME first, always.
+ *
+ * This used to print the signature INSTEAD of the name whenever a signature
+ * existed, which made a member unidentifiable the moment the signature was
+ * wrong. It is sometimes wrong: the bridge's extractor hands back the line
+ * preceding the body when a macro sits between the doc block and the signature,
+ * so `SysQuery.range` was listed as `#ISOCountryRegionCodes`. Filtering runs on
+ * the NAME, so asking for prefix "range" returned "1 member" that appeared to be
+ * something else entirely — and a member list that renders a public API as
+ * another string argues the API does not exist. An eval run concluded exactly
+ * that and worked around a method that was there all along.
+ *
+ * The signature is still shown, as detail, and only when it plausibly belongs to
+ * this member. Fixing the extractor is a separate, C#-side change; this makes the
+ * output honest either way.
+ */
+declare function memberLine(m: {
+    name: string;
+    signature?: string;
+}): string;
+declare function formatCompletion(r: BridgeCompletionResult, prefix?: string): string;
 export declare function tryBridgeCocExtensions(bridge: BridgeClient | undefined, baseClassName: string, methodName?: string): Promise<ToolResult | null>;
 export declare function tryBridgeEventHandlers(bridge: BridgeClient | undefined, targetName: string, eventName?: string, handlerType?: string): Promise<ToolResult | null>;
 export declare function tryBridgeApiUsageCallers(bridge: BridgeClient | undefined, apiName: string, limit?: number): Promise<ToolResult | null>;
+/**
+ * Internals exposed for tests only. `formatCompletion` renders a member list,
+ * and a member list that cannot be trusted to name its members is worse than no
+ * list at all — see tests/bridge/completionMemberLine.test.ts.
+ */
+export declare const __testing: {
+    formatCompletion: typeof formatCompletion;
+    memberLine: typeof memberLine;
+};
+export {};
 //# sourceMappingURL=bridgeAdapter.d.ts.map

package/dist/bridge/bridgeAdapter.js

@@ -758,7 +758,23 @@ export async function tryBridgeSearch(bridge, query, objectType, maxResults = 50
         if (!sr)
             return null;
         // Splice in exact matches the bridge's truncated window missed (#15).
-        const bridgeHits = sr.results ?? [];
+        //
+        // …but first, honour the type filter the caller asked for, because the bridge
+        // does not always honour it. Its C#-side type map has no entry for every AOT
+        // kind — `report` is one — and an unmapped type runs the query UNFILTERED, so
+        // `search(type="report")` answered with tables and queries and looked
+        // authoritative doing it ("Cust" returned six tables). A report reached the
+        // caller only when the SQLite exact-name splice happened to carry one, which
+        // is why the failure looked intermittent rather than total.
+        //
+        // Only the BRIDGE's hits are filtered. The spliced exact and custom matches
+        // are deliberately allowed to differ in type — a `table-extension` is a
+        // wanted answer to a `type="table"` search for the table it extends — and
+        // filtering those too would delete that behaviour.
+        const rawBridgeHits = sr.results ?? [];
+        const bridgeHits = objectType && objectType !== 'all'
+            ? rawBridgeHits.filter(r => r.type === objectType)
+            : rawBridgeHits;
         const known = new Set(bridgeHits.map(r => `${r.name.toLowerCase()}\0${r.type}`));
         const spliced = [];
         for (const cand of opts?.exactMatches ?? []) {
@@ -2437,6 +2453,30 @@ export async function tryBridgeCompletion(bridge, symbolName, prefix, ancestors)
         return null;
     }
 }
+/**
+ * One line of a member list — NAME first, always.
+ *
+ * This used to print the signature INSTEAD of the name whenever a signature
+ * existed, which made a member unidentifiable the moment the signature was
+ * wrong. It is sometimes wrong: the bridge's extractor hands back the line
+ * preceding the body when a macro sits between the doc block and the signature,
+ * so `SysQuery.range` was listed as `#ISOCountryRegionCodes`. Filtering runs on
+ * the NAME, so asking for prefix "range" returned "1 member" that appeared to be
+ * something else entirely — and a member list that renders a public API as
+ * another string argues the API does not exist. An eval run concluded exactly
+ * that and worked around a method that was there all along.
+ *
+ * The signature is still shown, as detail, and only when it plausibly belongs to
+ * this member. Fixing the extractor is a separate, C#-side change; this makes the
+ * output honest either way.
+ */
+function memberLine(m) {
+    const sig = m.signature?.trim();
+    const belongs = sig && new RegExp(`\\b${m.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`, 'i').test(sig);
+    if (belongs)
+        return `\`${sig}\``;
+    return sig ? `**${m.name}** _(signature unavailable)_` : `**${m.name}**`;
+}
 function formatCompletion(r, prefix) {
     let members = r.members;
     if (prefix) {
@@ -2458,8 +2498,9 @@ function formatCompletion(r, prefix) {
         const inheritedCount = methodMembers.filter(m => m.inheritedFrom).length;
         out += `## Methods (${methodMembers.length})\n`;
         for (const m of methodMembers) {
-            const body = m.signature ? `\`${m.signature}\`` : m.name;
-            out += m.inheritedFrom ? `- ${body} _(inherited from ${m.inheritedFrom})_\n` : `- ${body}\n`;
+            out += m.inheritedFrom
+                ? `- ${memberLine(m)} _(inherited from ${m.inheritedFrom})_\n`
+                : `- ${memberLine(m)}\n`;
         }
         if (inheritedCount > 0) {
             out += `\n> ${inheritedCount} of these are inherited — callable on ${r.symbolName}, but ` +
@@ -2602,4 +2643,10 @@ function formatApiUsageCallers(r) {
     }
     return out;
 }
+/**
+ * Internals exposed for tests only. `formatCompletion` renders a member list,
+ * and a member list that cannot be trusted to name its members is worse than no
+ * list at all — see tests/bridge/completionMemberLine.test.ts.
+ */
+export const __testing = { formatCompletion, memberLine };
 //# sourceMappingURL=bridgeAdapter.js.map

package/dist/cli/commands/bpCatalog.js

@@ -18,7 +18,7 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { settingByPath } from '../../config/settings.js';
 import { findPackagesRoot } from '../../utils/packagesRoot.js';
 import { commandExists, runExe } from '../exec.js';
@@ -243,7 +243,10 @@ async function refreshCatalog(target, deps) {
             return;
         }
     }
-    p.log.step(`Refreshing BP moniker catalog (${target.label}, ${basename(source.packagesPath)})…`);
+    // No packages path in this line: the script's own report opens with the
+    // full path, and the tail of it ('PackagesLocalDirectory') identified
+    // nothing on a box with several installs.
+    p.log.step(`Refreshing BP moniker catalog (${target.label})…`);
     // Extract beside the real catalog, not over it. The script writes its output
     // in one go with no staging of its own, so pointing it straight at the live
     // file means a partial run destroys a good catalog before anything can judge

package/dist/knowledge/kernelEnums.js

@@ -50,6 +50,33 @@ const ENTRIES = [
             'Integer', 'List', 'RString', 'Real', 'Record', 'String', 'Time',
             'UserType', 'UtcDateTime', 'VarArg', 'VarString', 'Void',
         ] },
+    // What Box::yesNo/confirm/okCancel answer with. Found by the knowledge audit,
+    // which reported "DialogButton does not exist in the symbol index" for a topic
+    // whose call shape had already compiled in an xppc probe — the same
+    // absent-from-the-AOT-is-not-absent trap this module exists for. Values are the
+    // ones shipped code actually uses, counted over 30,000 AxClass/AxForm files:
+    // Yes 602, No 561, Cancel 154, Ok 129, YesToAll 7, NoToAll 6.
+    { name: 'DialogButton', values: ['Cancel', 'No', 'NoToAll', 'Ok', 'Yes', 'YesToAll'] },
+    // Added 2026-08-31 after an eval run tripped over AccessType and MenuItemType:
+    // validate_code(mode="references") called both hard ERRORS on code that
+    // compiles, and with GROUNDING_ENFORCE on it would have REFUSED the write —
+    // the exact failure this module was created to prevent. That both were absent
+    // was the signal that the list had never been derived from anything, so it is
+    // now checked by `npm run oracle:kernel-enums`, which finds every `Name::Value`
+    // in shipped X++ with no AOT element behind it. Values below are what the
+    // product itself writes, counted by that audit, not recalled.
+    { name: 'MenuItemType', values: ['Action', 'Display', 'Output'] },
+    { name: 'AccessType', values: ['Add', 'Correction', 'Delete', 'Edit', 'NoAccess', 'View'] },
+    { name: 'AccessRight', values: ['Add', 'Correction', 'Delete', 'Edit', 'NoAccess', 'View'] },
+    { name: 'SortOrder', values: ['Ascending', 'Descending'] },
+    // QueryBuildDataSource.joinMode(). Reported by a second eval run, through the
+    // static-member rule rather than the declared-type one — the two rules did not
+    // share the kernel-name exemption, so the same fact was a warning in one place
+    // and an error in the other.
+    { name: 'JoinMode', values: ['ExistsJoin', 'InnerJoin', 'NoExistsJoin', 'OuterJoin'] },
+    // The argument to an `unchecked(...)` block. Only these two members exist —
+    // DBSchemaDrift and Deadlock read plausibly and are not real (xppc-verified).
+    { name: 'Uncheck', values: ['TableSecurityPermission', 'XDS'] },
     { name: 'TableScope', values: ['CurrentTableOnly', 'IncludeBaseTables', 'IncludeDerivedTables'] },
     { name: 'ConcurrencyModel', values: ['Auto', 'Optimistic', 'Pessimistic'] },
     { name: 'StatementType', values: ['Delete', 'Insert', 'Select', 'Update'] },

package/dist/metadata/symbolIndex.d.ts

@@ -36,6 +36,35 @@ export interface ExtensionMetadataRecord {
     eventSubscriptions?: string[];
     model: string;
 }
+/**
+ * Construction-time switches for the deferred file_path index builds.
+ *
+ * The defaults describe the long-running server: build in the background, treat
+ * anything over 200 MB as big enough to be worth a thread. A one-shot CLI wants
+ * the opposite of both — see scripts/build-database.ts.
+ */
+export interface XppSymbolIndexOptions {
+    /**
+     * Dispatch large index builds to a worker thread (default true).
+     *
+     * Set false in one-shot scripts. A worker writes through a SECOND connection to
+     * the same file, which cannot coexist with `locking_mode = EXCLUSIVE` on the
+     * writer — the build script takes that lock and the worker (or the writer,
+     * depending on who gets there first) fails with SQLITE_BUSY. Blocking the event
+     * loop, the reason the worker exists at all, costs a CLI nothing.
+     */
+    backgroundIndexBuilds?: boolean;
+    /**
+     * Skip the file_path index builds during construction; the caller runs
+     * ensureFilePathIndexes() itself once its bulk load is done (default false).
+     *
+     * Building them up front makes a bulk load maintain two extra B-trees per row,
+     * and on a full rebuild the work is thrown away by clear() anyway.
+     */
+    deferFilePathIndexes?: boolean;
+    /** Byte size at which a DB is "large" enough to hand its index build to a worker. */
+    largeDbThresholdBytes?: number;
+}
 export declare class XppSymbolIndex {
     db: Database;
     labelsDb: Database;
@@ -54,12 +83,16 @@ export declare class XppSymbolIndex {
     private suggestionNamesCache;
     private symbolsByTermCache;
     private perConnStmtCache;
+    private backgroundIndexBuilds;
+    private deferFilePathIndexes;
+    private largeDbThresholdBytes;
+    private pendingIndexWorkers;
     /**
      * Directory holding the metadata databases. Sibling marker files (the blob-download
      * note, the last-build record) live here so they travel with the index they describe.
      */
     get dataDir(): string;
-    constructor(dbPath: string, labelsDbPath?: string);
+    constructor(dbPath: string, labelsDbPath?: string, options?: XppSymbolIndexOptions);
     /**
      * Returns the next read-only connection from the pool (round-robin).
      * Falls back to the main writer connection when the pool is empty
@@ -69,11 +102,20 @@ export declare class XppSymbolIndex {
      * to benefit from read-pool parallelism and per-connection stmt caching.
      */
     getReadDb(): Database;
+    /** True while a background file_path index build is still running. */
+    hasPendingIndexBuilds(): boolean;
     /**
      * Close and drain all read-pool connections.
      * Must be called before setting locking_mode = EXCLUSIVE on the writer
      * connection (e.g. in build scripts) — SQLite cannot grant EXCLUSIVE while
      * any other connection (even read-only, even in-process) holds a shared lock.
+     *
+     * The read pool is NOT the only other connection this class opens: an index
+     * build dispatched to a worker holds a writer connection to the same file, and
+     * this method cannot drain it (worker shutdown is asynchronous; this is not).
+     * Callers that take an EXCLUSIVE lock must construct with
+     * `backgroundIndexBuilds: false` so no such worker ever exists — the warning
+     * below is the tripwire for the ones that forget.
      */
     closeReadPool(): void;
     /**
@@ -150,11 +192,19 @@ export declare class XppSymbolIndex {
      * build is instant and runs here; on a large existing DB it is handed to a
      * worker thread, and until it finishes those deletes simply stay as slow as
      * they are today.
+     *
+     * Public because build scripts defer it (see XppSymbolIndexOptions) and run it
+     * themselves after their bulk load, with the worker dispatch turned off.
      */
-    private ensureFilePathIndexes;
+    ensureFilePathIndexes(): void;
     /**
      * Build one index on a separate thread so the main event loop keeps serving.
-     * WAL mode allows the worker's write to proceed alongside main-thread readers.
+     *
+     * The worker opens its OWN write connection to the same file, so this is only
+     * legal while the database stays in WAL mode and no one takes an EXCLUSIVE lock
+     * on it for the duration — both guaranteed by the caller (ensureFilePathIndexes
+     * checks the journal mode, and build scripts opt out of workers entirely).
+     *
      * Best-effort: a failure leaves the index absent, which is exactly the state
      * the server ran in before, so it is logged and never thrown.
      */

package/dist/metadata/symbolIndex.js

@@ -77,6 +77,15 @@ export class XppSymbolIndex {
     // Per-connection prepared-statement cache.  Prepared statements are bound to
     // their originating connection and cannot be shared across connections.
     perConnStmtCache = new WeakMap();
+    // See XppSymbolIndexOptions. Held as fields so ensureFilePathIndexes() reads the
+    // same answer whether it runs from the constructor or from a build script later.
+    backgroundIndexBuilds;
+    deferFilePathIndexes;
+    largeDbThresholdBytes;
+    // Index-build workers still running. closeReadPool() cannot drain these (it only
+    // owns the read pool), so track them to warn about the EXCLUSIVE-lock race and to
+    // tear them down in close().
+    pendingIndexWorkers = new Set();
     /**
      * Directory holding the metadata databases. Sibling marker files (the blob-download
      * note, the last-build record) live here so they travel with the index they describe.
@@ -84,8 +93,11 @@ export class XppSymbolIndex {
     get dataDir() {
         return path.dirname(this.dbPath);
     }
-    constructor(dbPath, labelsDbPath) {
+    constructor(dbPath, labelsDbPath, options = {}) {
         this.dbPath = dbPath;
+        this.backgroundIndexBuilds = options.backgroundIndexBuilds !== false;
+        this.deferFilePathIndexes = options.deferFilePathIndexes === true;
+        this.largeDbThresholdBytes = options.largeDbThresholdBytes ?? 200 * 1024 * 1024;
         // Ensure database directory exists
         const dbDir = path.dirname(dbPath);
         if (!fs.existsSync(dbDir)) {
@@ -167,13 +179,29 @@ export class XppSymbolIndex {
             return this.db;
         return this.readPool[this.readPoolRR++ % this.readPool.length];
     }
+    /** True while a background file_path index build is still running. */
+    hasPendingIndexBuilds() {
+        return this.pendingIndexWorkers.size > 0;
+    }
     /**
      * Close and drain all read-pool connections.
      * Must be called before setting locking_mode = EXCLUSIVE on the writer
      * connection (e.g. in build scripts) — SQLite cannot grant EXCLUSIVE while
      * any other connection (even read-only, even in-process) holds a shared lock.
+     *
+     * The read pool is NOT the only other connection this class opens: an index
+     * build dispatched to a worker holds a writer connection to the same file, and
+     * this method cannot drain it (worker shutdown is asynchronous; this is not).
+     * Callers that take an EXCLUSIVE lock must construct with
+     * `backgroundIndexBuilds: false` so no such worker ever exists — the warning
+     * below is the tripwire for the ones that forget.
      */
     closeReadPool() {
+        if (this.pendingIndexWorkers.size > 0) {
+            console.error(`[SymbolIndex] closeReadPool() with ${this.pendingIndexWorkers.size} background index ` +
+                `build(s) still running — these hold their own write connections and will contend ` +
+                `with locking_mode = EXCLUSIVE. Construct with { backgroundIndexBuilds: false }.`);
+        }
         for (const conn of this.readPool) {
             try {
                 conn.close();
@@ -709,7 +737,9 @@ export class XppSymbolIndex {
       CREATE INDEX IF NOT EXISTS idx_md_define ON macro_defines(define_name);
       CREATE INDEX IF NOT EXISTS idx_md_model ON macro_defines(model);
     `);
-        this.ensureFilePathIndexes();
+        if (!this.deferFilePathIndexes) {
+            this.ensureFilePathIndexes();
+        }
     }
     /**
      * The `labels` indexes that exist purely to accelerate reads, keyed by name so
@@ -810,6 +840,9 @@ export class XppSymbolIndex {
      * build is instant and runs here; on a large existing DB it is handed to a
      * worker thread, and until it finishes those deletes simply stay as slow as
      * they are today.
+     *
+     * Public because build scripts defer it (see XppSymbolIndexOptions) and run it
+     * themselves after their bulk load, with the worker dispatch turned off.
      */
     ensureFilePathIndexes() {
         const missing = (db, indexName) => !db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?`).get(indexName);
@@ -819,7 +852,7 @@ export class XppSymbolIndex {
             if (dbFile === ':memory:')
                 return false;
             try {
-                return fs.statSync(dbFile).size > 200 * 1024 * 1024;
+                return fs.statSync(dbFile).size > this.largeDbThresholdBytes;
             }
             catch {
                 return false;
@@ -861,7 +894,12 @@ export class XppSymbolIndex {
         // .label.txt (813 on a default build), so building them is instant and needs
         // neither the deferral nor the worker dispatch the per-label table needed.
         for (const item of work) {
-            if (isLarge(item.dbFile)) {
+            // A worker writes through its own connection, which only works while the
+            // database is in WAL mode and nothing holds an EXCLUSIVE lock. Build scripts
+            // switch to journal_mode = MEMORY and take that lock, so the journal mode is
+            // checked here rather than assumed — off WAL the only safe build is inline.
+            const inWal = item.db.pragma('journal_mode', { simple: true }) === 'wal';
+            if (isLarge(item.dbFile) && this.backgroundIndexBuilds && inWal) {
                 this.buildIndexInWorker(item.dbFile, item.sql, item.name);
             }
             else {
@@ -871,7 +909,12 @@ export class XppSymbolIndex {
     }
     /**
      * Build one index on a separate thread so the main event loop keeps serving.
-     * WAL mode allows the worker's write to proceed alongside main-thread readers.
+     *
+     * The worker opens its OWN write connection to the same file, so this is only
+     * legal while the database stays in WAL mode and no one takes an EXCLUSIVE lock
+     * on it for the duration — both guaranteed by the caller (ensureFilePathIndexes
+     * checks the journal mode, and build scripts opt out of workers entirely).
+     *
      * Best-effort: a failure leaves the index absent, which is exactly the state
      * the server ran in before, so it is logged and never thrown.
      */
@@ -880,6 +923,7 @@ export class XppSymbolIndex {
             const worker = new Worker(new URL('./buildIndexWorker.js', import.meta.url), {
                 workerData: { dbPath, sql, indexName },
             });
+            this.pendingIndexWorkers.add(worker);
             // unref() so a pending index build never keeps the process alive on exit.
             worker.unref();
             worker.once('message', (msg) => {
@@ -889,9 +933,14 @@ export class XppSymbolIndex {
                 else {
                     console.error(`[SymbolIndex] Background build of ${indexName} failed: ${msg.error}`);
                 }
+                this.pendingIndexWorkers.delete(worker);
                 void worker.terminate();
             });
-            worker.once('error', e => console.error(`[SymbolIndex] ${indexName} worker error: ${e}`));
+            worker.once('error', e => {
+                this.pendingIndexWorkers.delete(worker);
+                console.error(`[SymbolIndex] ${indexName} worker error: ${e}`);
+            });
+            worker.once('exit', () => this.pendingIndexWorkers.delete(worker));
         }
         catch (e) {
             console.error(`[SymbolIndex] Could not start ${indexName} worker: ${e}`);
@@ -3836,6 +3885,14 @@ export class XppSymbolIndex {
             console.error(`[SymbolIndex] Final labels FTS flush failed: ${e}`);
             this._labelsFtsTimer = null;
         }
+        // Background index builds hold their own write connection to the same file;
+        // leaving one running past close() writes into a database the owner considers
+        // shut. terminate() is async and best-effort — we do not await it, we only stop
+        // the build from outliving us.
+        for (const worker of this.pendingIndexWorkers) {
+            void worker.terminate();
+        }
+        this.pendingIndexWorkers.clear();
         // Drain read pools first — writer close will fail on WAL if readers hold a lock.
         this.closeReadPool();
         this.stmtCache.clear();

package/dist/scripts/build-database.js

@@ -1208,6 +1208,15 @@ var XppSymbolIndex = class _XppSymbolIndex {
   // Per-connection prepared-statement cache.  Prepared statements are bound to
   // their originating connection and cannot be shared across connections.
   perConnStmtCache = /* @__PURE__ */ new WeakMap();
+  // See XppSymbolIndexOptions. Held as fields so ensureFilePathIndexes() reads the
+  // same answer whether it runs from the constructor or from a build script later.
+  backgroundIndexBuilds;
+  deferFilePathIndexes;
+  largeDbThresholdBytes;
+  // Index-build workers still running. closeReadPool() cannot drain these (it only
+  // owns the read pool), so track them to warn about the EXCLUSIVE-lock race and to
+  // tear them down in close().
+  pendingIndexWorkers = /* @__PURE__ */ new Set();
   /**
    * Directory holding the metadata databases. Sibling marker files (the blob-download
    * note, the last-build record) live here so they travel with the index they describe.
@@ -1215,8 +1224,11 @@ var XppSymbolIndex = class _XppSymbolIndex {
   get dataDir() {
     return path.dirname(this.dbPath);
   }
-  constructor(dbPath, labelsDbPath) {
+  constructor(dbPath, labelsDbPath, options = {}) {
     this.dbPath = dbPath;
+    this.backgroundIndexBuilds = options.backgroundIndexBuilds !== false;
+    this.deferFilePathIndexes = options.deferFilePathIndexes === true;
+    this.largeDbThresholdBytes = options.largeDbThresholdBytes ?? 200 * 1024 * 1024;
     const dbDir = path.dirname(dbPath);
     if (!fs2.existsSync(dbDir)) {
       fs2.mkdirSync(dbDir, { recursive: true });
@@ -1281,13 +1293,29 @@ var XppSymbolIndex = class _XppSymbolIndex {
     if (this.readPool.length === 0) return this.db;
     return this.readPool[this.readPoolRR++ % this.readPool.length];
   }
+  /** True while a background file_path index build is still running. */
+  hasPendingIndexBuilds() {
+    return this.pendingIndexWorkers.size > 0;
+  }
   /**
    * Close and drain all read-pool connections.
    * Must be called before setting locking_mode = EXCLUSIVE on the writer
    * connection (e.g. in build scripts) — SQLite cannot grant EXCLUSIVE while
    * any other connection (even read-only, even in-process) holds a shared lock.
+   *
+   * The read pool is NOT the only other connection this class opens: an index
+   * build dispatched to a worker holds a writer connection to the same file, and
+   * this method cannot drain it (worker shutdown is asynchronous; this is not).
+   * Callers that take an EXCLUSIVE lock must construct with
+   * `backgroundIndexBuilds: false` so no such worker ever exists — the warning
+   * below is the tripwire for the ones that forget.
    */
   closeReadPool() {
+    if (this.pendingIndexWorkers.size > 0) {
+      console.error(
+        `[SymbolIndex] closeReadPool() with ${this.pendingIndexWorkers.size} background index build(s) still running \u2014 these hold their own write connections and will contend with locking_mode = EXCLUSIVE. Construct with { backgroundIndexBuilds: false }.`
+      );
+    }
     for (const conn of this.readPool) {
       try {
         conn.close();
@@ -1766,7 +1794,9 @@ var XppSymbolIndex = class _XppSymbolIndex {
       CREATE INDEX IF NOT EXISTS idx_md_define ON macro_defines(define_name);
       CREATE INDEX IF NOT EXISTS idx_md_model ON macro_defines(model);
     `);
-    this.ensureFilePathIndexes();
+    if (!this.deferFilePathIndexes) {
+      this.ensureFilePathIndexes();
+    }
   }
   /**
    * The `labels` indexes that exist purely to accelerate reads, keyed by name so
@@ -1860,13 +1890,16 @@ var XppSymbolIndex = class _XppSymbolIndex {
    * build is instant and runs here; on a large existing DB it is handed to a
    * worker thread, and until it finishes those deletes simply stay as slow as
    * they are today.
+   *
+   * Public because build scripts defer it (see XppSymbolIndexOptions) and run it
+   * themselves after their bulk load, with the worker dispatch turned off.
    */
   ensureFilePathIndexes() {
     const missing = (db, indexName) => !db.prepare(`SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = ?`).get(indexName);
     const isLarge = (dbFile) => {
       if (dbFile === ":memory:") return false;
       try {
-        return fs2.statSync(dbFile).size > 200 * 1024 * 1024;
+        return fs2.statSync(dbFile).size > this.largeDbThresholdBytes;
       } catch {
         return false;
       }
@@ -1898,7 +1931,8 @@ var XppSymbolIndex = class _XppSymbolIndex {
       });
     }
     for (const item of work) {
-      if (isLarge(item.dbFile)) {
+      const inWal = item.db.pragma("journal_mode", { simple: true }) === "wal";
+      if (isLarge(item.dbFile) && this.backgroundIndexBuilds && inWal) {
         this.buildIndexInWorker(item.dbFile, item.sql, item.name);
       } else {
         item.db.exec(item.sql);
@@ -1907,7 +1941,12 @@ var XppSymbolIndex = class _XppSymbolIndex {
   }
   /**
    * Build one index on a separate thread so the main event loop keeps serving.
-   * WAL mode allows the worker's write to proceed alongside main-thread readers.
+   *
+   * The worker opens its OWN write connection to the same file, so this is only
+   * legal while the database stays in WAL mode and no one takes an EXCLUSIVE lock
+   * on it for the duration — both guaranteed by the caller (ensureFilePathIndexes
+   * checks the journal mode, and build scripts opt out of workers entirely).
+   *
    * Best-effort: a failure leaves the index absent, which is exactly the state
    * the server ran in before, so it is logged and never thrown.
    */
@@ -1916,6 +1955,7 @@ var XppSymbolIndex = class _XppSymbolIndex {
       const worker = new Worker(new URL("./buildIndexWorker.js", import.meta.url), {
         workerData: { dbPath, sql, indexName }
       });
+      this.pendingIndexWorkers.add(worker);
       worker.unref();
       worker.once("message", (msg) => {
         if (msg.ok) {
@@ -1923,9 +1963,14 @@ var XppSymbolIndex = class _XppSymbolIndex {
         } else {
           console.error(`[SymbolIndex] Background build of ${indexName} failed: ${msg.error}`);
         }
+        this.pendingIndexWorkers.delete(worker);
         void worker.terminate();
       });
-      worker.once("error", (e) => console.error(`[SymbolIndex] ${indexName} worker error: ${e}`));
+      worker.once("error", (e) => {
+        this.pendingIndexWorkers.delete(worker);
+        console.error(`[SymbolIndex] ${indexName} worker error: ${e}`);
+      });
+      worker.once("exit", () => this.pendingIndexWorkers.delete(worker));
     } catch (e) {
       console.error(`[SymbolIndex] Could not start ${indexName} worker: ${e}`);
     }
@@ -4601,6 +4646,10 @@ Point the installation at a drive with room (a full index needs several GB): re-
       console.error(`[SymbolIndex] Final labels FTS flush failed: ${e}`);
       this._labelsFtsTimer = null;
     }
+    for (const worker of this.pendingIndexWorkers) {
+      void worker.terminate();
+    }
+    this.pendingIndexWorkers.clear();
     this.closeReadPool();
     this.stmtCache.clear();
     try {
@@ -7140,7 +7189,10 @@ async function buildDatabase() {
   console.log(kv("Labels DB", shortPath(OUTPUT_LABELS_DB)));
   console.log(kv("VACUUM", EXTRACT_MODE === "all" || FORCE_VACUUM ? c.green("enabled") : c.dim("disabled (incremental build)")));
   console.log("");
-  const symbolIndex = new XppSymbolIndex(OUTPUT_DB, OUTPUT_LABELS_DB);
+  const symbolIndex = new XppSymbolIndex(OUTPUT_DB, OUTPUT_LABELS_DB, {
+    backgroundIndexBuilds: false,
+    deferFilePathIndexes: true
+  });
   const extractManifestCustomModels = readExtractedCustomModels(INPUT_PATH);
   if (extractManifestCustomModels !== void 0) {
     symbolIndex.setNonMicrosoftModels(extractManifestCustomModels);
@@ -7345,6 +7397,11 @@ async function buildDatabase() {
     console.log("");
     log.info("Skipping label indexing (INCLUDE_LABELS=false)");
   }
+  console.log("");
+  log.step("Building file_path indexes...");
+  const filePathIdxStart = Date.now();
+  symbolIndex.ensureFilePathIndexes();
+  log.ok(`file_path indexes built in ${((Date.now() - filePathIdxStart) / 1e3).toFixed(2)}s`);
   if (SKIP_FTS) {
     console.log("");
     log.info("Skipping WAL conversion (database will be finalized by build-fts step)");