@aroman22/codegraph-vba-darwin-arm64 1.5.1 → 1.6.0

package/lib/dist/db/index.js

@@ -40,6 +40,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DATABASE_FILENAME = exports.DatabaseConnection = void 0;
 exports.getDatabasePath = getDatabasePath;
+exports.removeDatabaseFiles = removeDatabaseFiles;
 const sqlite_adapter_1 = require("./sqlite-adapter");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -196,6 +197,100 @@ class DatabaseConnection {
         const stats = fs.statSync(this.dbPath);
         return stats.size;
     }
+    /**
+     * Size of the `-wal` sidecar file in bytes. 0 when it doesn't exist (non-WAL
+     * journal mode, in-memory DB, or no write since the last checkpoint+reset).
+     */
+    getWalSizeBytes() {
+        if (!this.dbPath || this.dbPath === ':memory:')
+            return 0;
+        try {
+            return fs.statSync(`${this.dbPath}-wal`).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /** Current `wal_autocheckpoint` interval in pages (0 = disabled). */
+    getWalAutocheckpoint() {
+        const v = this.db.pragma('wal_autocheckpoint', { simple: true });
+        const n = Number(v);
+        return Number.isFinite(n) ? n : 0;
+    }
+    /**
+     * Set the connection's `wal_autocheckpoint` interval (pages; 0 disables).
+     * Bulk indexing defers checkpoints entirely (#1231): the default 1000-page
+     * auto-checkpoint re-writes hot B-tree/FTS pages into the main DB file over
+     * and over — measured at ~95% of ALL disk I/O during a bulk index, and the
+     * difference between 45s and 19+ minutes on HDD-class storage. During
+     * deferral a {@link WalCheckpointValve} bounds WAL growth off-thread.
+     */
+    setWalAutocheckpoint(pages) {
+        this.db.pragma(`wal_autocheckpoint = ${Math.max(0, Math.floor(pages))}`);
+    }
+    /**
+     * `PRAGMA wal_checkpoint(PASSIVE)` on a worker thread with its own
+     * connection. PASSIVE never blocks the writer, and running it off-thread
+     * means the main thread — and the #850 watchdog heartbeat — keep turning
+     * even when the backfill is minutes of I/O on slow storage (a synchronous
+     * checkpoint that exceeds the watchdog's 60s window gets a healthy index
+     * SIGKILLed — observed in the #1231 repro).
+     *
+     * Returns SQLite's checkpoint result row — `log === checkpointed` with
+     * `busy === 0` means the ENTIRE WAL was backfilled, so the writer's next
+     * commit restarts the WAL from the top and the file stops growing. The
+     * WAL valve needs that signal because a WAL file's SIZE never shrinks:
+     * after the first wrap, raw file size says nothing about the un-backfilled
+     * backlog. Best-effort: returns null on any failure (including worker
+     * threads being unavailable — a potentially minutes-long checkpoint must
+     * never run inline on the main thread).
+     */
+    async checkpointWalPassive() {
+        if (!this.dbPath || this.dbPath === ':memory:') {
+            try {
+                const row = this.db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get();
+                return row ? { busy: Number(row.busy), log: Number(row.log), checkpointed: Number(row.checkpointed) } : null;
+            }
+            catch {
+                return null;
+            }
+        }
+        try {
+            const { Worker } = await Promise.resolve().then(() => __importStar(require('node:worker_threads')));
+            const workerSource = `
+        const { workerData, parentPort } = require('node:worker_threads');
+        let row = null;
+        try {
+          const { DatabaseSync } = require('node:sqlite');
+          const db = new DatabaseSync(workerData.dbPath);
+          try { row = db.prepare('PRAGMA wal_checkpoint(PASSIVE)').get(); } catch {}
+          try { db.close(); } catch {}
+        } catch {}
+        parentPort.postMessage({ row });
+      `;
+            return await new Promise((resolve) => {
+                let settled = false;
+                const finish = (row) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(row ? { busy: Number(row.busy), log: Number(row.log), checkpointed: Number(row.checkpointed) } : null);
+                };
+                try {
+                    const worker = new Worker(workerSource, { eval: true, workerData: { dbPath: this.dbPath } });
+                    worker.once('message', (m) => { void worker.terminate(); finish(m?.row ?? null); });
+                    worker.once('error', () => { void worker.terminate(); finish(null); });
+                    worker.once('exit', () => finish(null));
+                }
+                catch {
+                    finish(null);
+                }
+            });
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Optimize database (vacuum and analyze)
      */
@@ -204,8 +299,8 @@ class DatabaseConnection {
         this.db.exec('ANALYZE');
     }
     /**
-     * Lightweight, non-blocking maintenance to run after bulk writes
-     * (indexAll, sync). Two operations:
+     * Lightweight maintenance to run after bulk writes (indexAll, sync).
+     * Two operations:
      *
      *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
      *     tables whose row counts changed materially since the last
@@ -217,21 +312,85 @@ class DatabaseConnection {
      *     unboundedly between automatic checkpoints (auto-fires at 1000
      *     pages by default; large indexAll runs blow past that).
      *
-     * Both operations are silently swallowed on failure — they're a
-     * best-effort optimization, never load-bearing for correctness.
+     * Runs on a WORKER THREAD with its own connection: on a multi-GB index
+     * these pragmas are minutes of synchronous IO (a 95k-file kernel index
+     * left a 593MB WAL whose checkpoint alone blew the #850 watchdog's 60s
+     * window and got a COMPLETED index SIGKILLed at the finish line). WAL
+     * checkpointing from a second connection is standard SQLite; `PRAGMA
+     * optimize` persists its statistics in sqlite_stat tables, so the main
+     * connection benefits the same. The main thread just awaits a message,
+     * so the event loop — and the watchdog heartbeat — keep turning.
+     *
+     * Everything is silently swallowed on failure — best-effort
+     * optimization, never load-bearing for correctness. If worker threads
+     * are unavailable, falls back to a bounded in-line `PRAGMA optimize`
+     * and SKIPS the checkpoint (the final close() checkpoints after the
+     * CLI has already disarmed its watchdog).
      */
-    runMaintenance() {
-        try {
-            this.db.exec('PRAGMA optimize');
-        }
-        catch {
-            // ignore
+    async runMaintenance() {
+        // In-memory / test databases: nothing worth a worker round-trip.
+        if (!this.dbPath || this.dbPath === ':memory:') {
+            try {
+                this.db.exec('PRAGMA optimize');
+            }
+            catch { /* ignore */ }
+            try {
+                this.db.exec('PRAGMA wal_checkpoint(PASSIVE)');
+            }
+            catch { /* ignore */ }
+            return;
         }
+        await this.runPragmasOffThread(['PRAGMA analysis_limit=1000', 'PRAGMA optimize', 'PRAGMA wal_checkpoint(PASSIVE)'], 
+        // Worker threads unavailable — bounded in-line fallback, no checkpoint.
+        ['PRAGMA analysis_limit=1000', 'PRAGMA optimize']);
+    }
+    /**
+     * Run pragmas on a worker thread against its own connection to this DB
+     * (shared machinery for {@link runMaintenance} and
+     * {@link checkpointWalPassive}). Each pragma is individually best-effort;
+     * the whole call is best-effort. `inlineFallback` (if any) runs on THIS
+     * connection only when worker threads are unavailable — keep it to pragmas
+     * that are safe to run synchronously on the main thread.
+     */
+    async runPragmasOffThread(pragmas, inlineFallback = []) {
+        try {
+            const { Worker } = await Promise.resolve().then(() => __importStar(require('node:worker_threads')));
+            const workerSource = `
+        const { workerData, parentPort } = require('node:worker_threads');
         try {
-            this.db.exec('PRAGMA wal_checkpoint(PASSIVE)');
+          const { DatabaseSync } = require('node:sqlite');
+          const db = new DatabaseSync(workerData.dbPath);
+          for (const p of workerData.pragmas) { try { db.exec(p); } catch {} }
+          try { db.close(); } catch {}
+        } catch {}
+        parentPort.postMessage('done');
+      `;
+            await new Promise((resolve) => {
+                let settled = false;
+                const finish = () => {
+                    if (!settled) {
+                        settled = true;
+                        resolve();
+                    }
+                };
+                try {
+                    const worker = new Worker(workerSource, { eval: true, workerData: { dbPath: this.dbPath, pragmas } });
+                    worker.once('message', () => { void worker.terminate(); finish(); });
+                    worker.once('error', () => { void worker.terminate(); finish(); });
+                    worker.once('exit', finish);
+                }
+                catch {
+                    finish();
+                }
+            });
         }
         catch {
-            // ignore (e.g., not in WAL mode)
+            for (const p of inlineFallback) {
+                try {
+                    this.db.exec(p);
+                }
+                catch { /* ignore */ }
+            }
         }
     }
     /**
@@ -287,10 +446,48 @@ function statInode(p) {
  * Default database filename
  */
 exports.DATABASE_FILENAME = 'codegraph.db';
+/**
+ * SQLite's sidecar files in WAL mode — the write-ahead log and its shared-memory
+ * index. They sit beside the main DB file and are removed alongside it when the
+ * database is discarded (see `removeDatabaseFiles`).
+ */
+const WAL_SIDECAR_SUFFIXES = ['-wal', '-shm'];
 /**
  * Get the default database path for a project
  */
 function getDatabasePath(projectRoot) {
     return path.join((0, directory_1.getCodeGraphDir)(projectRoot), exports.DATABASE_FILENAME);
 }
+/**
+ * Delete a database file and its WAL sidecars (`-wal`/`-shm`).
+ *
+ * This is how a FULL re-index discards an existing database — rather than
+ * opening the old graph and DELETE-ing every row. On a large or pre-fix
+ * poisoned index (e.g. an old graph that scanned an ignored gitlink corpus into
+ * ~1.6M nodes with a multi-GB WAL, #1065) the per-row `nodes_fts` delete-trigger
+ * churn blocks the main thread long enough to trip the #850 liveness watchdog
+ * before indexing even starts, so the rebuild could never recover the bad state
+ * (#1067). Unlinking is O(1) regardless of DB size and also reclaims the disk
+ * the bloated WAL would otherwise keep.
+ *
+ * POSIX removes the directory entry even while another process (a daemon/MCP
+ * server) still holds the file open; that holder heals via `reopenIfReplaced`
+ * (#925). On Windows a live holder can make the unlink fail with EBUSY/EPERM —
+ * that is thrown for the caller to surface ("stop the other process and retry").
+ * The `-wal`/`-shm` sidecars are best-effort: SQLite recreates them on the next
+ * open, so a leftover sidecar is harmless.
+ */
+function removeDatabaseFiles(dbPath) {
+    // The main DB file first — its removal is the operation that must succeed (or
+    // report why it couldn't). force:true treats an already-missing file as done.
+    fs.rmSync(dbPath, { force: true });
+    for (const suffix of WAL_SIDECAR_SUFFIXES) {
+        try {
+            fs.rmSync(dbPath + suffix, { force: true });
+        }
+        catch {
+            // A sidecar still held/locked is harmless — SQLite rebuilds it on open.
+        }
+    }
+}
 //# sourceMappingURL=index.js.map

package/lib/dist/db/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"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"}

package/lib/dist/db/migrations.d.ts

@@ -7,7 +7,7 @@ import { SqliteDatabase } from './sqlite-adapter';
 /**
  * Current schema version
  */
-export declare const CURRENT_SCHEMA_VERSION = 6;
+export declare const CURRENT_SCHEMA_VERSION = 9;
 /**
  * Migration definition
  */

package/lib/dist/db/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;GAEG;AACH,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,IAAI,CAAC;CAClC;AAqED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAU5D;AAWD;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAiB3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAG1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,cAAc,GAAG,SAAS,EAAE,CAKpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,GACjB,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAU3E"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;GAEG;AACH,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,IAAI,CAAC;CAClC;AAqJD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,cAAc,GAAG,MAAM,CAU5D;AAWD;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAiB3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,GAAG,OAAO,CAG1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,cAAc,GAAG,SAAS,EAAE,CAKpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,cAAc,GACjB,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAU3E"}

package/lib/dist/db/migrations.js

@@ -14,7 +14,7 @@ exports.getMigrationHistory = getMigrationHistory;
 /**
  * Current schema version
  */
-exports.CURRENT_SCHEMA_VERSION = 6;
+exports.CURRENT_SCHEMA_VERSION = 9;
 /**
  * All migrations in order
  *
@@ -70,13 +70,90 @@ const migrations = [
     },
     {
         version: 6,
-        description: 'Add nodes.metadata — persisted extractor annotations for first-class symbol metadata',
+        description: 'Dedup duplicate edge rows and add a UNIQUE identity index so INSERT OR IGNORE actually dedups (#1034)',
         up: (db) => {
+            // `insertEdge` has always used `INSERT OR IGNORE`, but the edges table had
+            // no UNIQUE constraint, so nothing conflicted and byte-identical rows
+            // accumulated whenever two passes emitted the same edge. Collapse each
+            // identity group to its lowest id, then add the constraint that makes
+            // `OR IGNORE` keep its promise. IFNULL folds nullable line/col so
+            // coordinate-less edges dedup too (SQLite treats each NULL as distinct) —
+            // and it MUST match the GROUP BY exactly, or the index creation would
+            // fail on a pair the DELETE left behind. Idempotent: the index is
+            // `IF NOT EXISTS` and the DELETE is a no-op once the table is unique.
             db.exec(`
-        ALTER TABLE nodes ADD COLUMN metadata TEXT;
+        DELETE FROM edges
+        WHERE id NOT IN (
+          SELECT MIN(id) FROM edges
+          GROUP BY source, target, kind, IFNULL(line, -1), IFNULL(col, -1)
+        );
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_edges_identity
+          ON edges(source, target, kind, IFNULL(line, -1), IFNULL(col, -1));
       `);
         },
     },
+    {
+        version: 7,
+        description: 'Add name_segment_vocab — prose-word → symbol-name lookup for the prompt hook’s graph-derived gate',
+        up: (db) => {
+            // DDL only — instant on any size database (the row-churn hazards of #1067
+            // don't apply). The table starts EMPTY on migrated databases; `sync`
+            // detects that over a populated graph and backfills batched+yielding
+            // (CodeGraph.rebuildNameSegmentVocab), and any full index rebuilds it
+            // from scratch. Keep the definition in lockstep with schema.sql.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS name_segment_vocab (
+          segment TEXT NOT NULL,
+          name TEXT NOT NULL,
+          PRIMARY KEY (segment, name)
+        ) WITHOUT ROWID;
+      `);
+        },
+    },
+    {
+        version: 8,
+        description: 'Track attempted-but-unresolvable refs as status=failed so sync can retry them when a changed file adds a matching symbol (#1240)',
+        up: (db) => {
+            // DDL only — instant on any size database. No backfill needed: rows are
+            // only ever queried by name_tail once they carry status='failed', and
+            // both fields are written together by markReferencesFailed. Legacy rows
+            // (all 'pending' after this migration) are orphans from interrupted runs
+            // that the #1187 sweep grinds down on the next sync, marking survivors
+            // failed with their tails as it goes. The tail index is partial: on a
+            // healthy index the pending set is empty and the failed set is the only
+            // population worth indexing. Keep the definitions in lockstep with
+            // schema.sql. ALTER TABLE has no IF NOT EXISTS, so guard each column for
+            // idempotency — a database created from current schema.sql already has
+            // both (matters when migrations are re-run from an older recorded
+            // version, as the v6 regression test does).
+            const cols = db.prepare('PRAGMA table_info(unresolved_refs)').all();
+            const hasColumn = (name) => cols.some((c) => c.name === name);
+            if (!hasColumn('status')) {
+                db.exec("ALTER TABLE unresolved_refs ADD COLUMN status TEXT NOT NULL DEFAULT 'pending'");
+            }
+            if (!hasColumn('name_tail')) {
+                db.exec("ALTER TABLE unresolved_refs ADD COLUMN name_tail TEXT NOT NULL DEFAULT ''");
+            }
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_unresolved_status ON unresolved_refs(status);
+        CREATE INDEX IF NOT EXISTS idx_unresolved_failed_tail ON unresolved_refs(name_tail) WHERE status = 'failed';
+      `);
+        },
+    },
+    {
+        version: 9,
+        description: 'Add nodes.metadata — persisted extractor annotations for first-class symbol metadata (VBA fork)',
+        up: (db) => {
+            // Fork migration re-stacked above upstream's v6–v8. ALTER TABLE has no
+            // IF NOT EXISTS, so guard the column for idempotency — a database created
+            // from the current schema.sql already has it (matters when migrations are
+            // re-run from an older recorded version). Keep in lockstep with schema.sql.
+            const cols = db.prepare('PRAGMA table_info(nodes)').all();
+            if (!cols.some((c) => c.name === 'metadata')) {
+                db.exec('ALTER TABLE nodes ADD COLUMN metadata TEXT');
+            }
+        },
+    },
 ];
 /**
  * Get the current schema version from the database

package/lib/dist/db/migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"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"}

package/lib/dist/db/queries.d.ts

@@ -4,7 +4,7 @@
  * Prepared statements for CRUD operations on the knowledge graph.
  */
 import { SqliteDatabase } from './sqlite-adapter';
-import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, GraphStats, SearchOptions, SearchResult } from '../types';
+import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, Language, GraphStats, SearchOptions, SearchResult } from '../types';
 /**
  * Query builder for the knowledge graph database
  */
@@ -14,6 +14,8 @@ export declare class QueryBuilder {
     private nodeCache;
     private readonly maxCacheSize;
     private stmts;
+    private segmentedNames;
+    private static readonly MAX_SEGMENTED_NAMES;
     constructor(db: SqliteDatabase);
     /** Set the normalized project-name tokens used to down-weight non-discriminative
      * query words in path scoring (#720). Called once when the project opens. */
@@ -24,6 +26,12 @@ export declare class QueryBuilder {
      * Insert a new node
      */
     insertNode(node: Node): void;
+    /** Which node kinds contribute their name to the segment vocabulary — the
+     *  single gate shared by insertNode, updateNode, and the rebuild page query
+     *  (getDistinctNodeNames), so the write paths can't drift apart. */
+    private isSegmentableKind;
+    /** Write `name`'s segments into name_segment_vocab (idempotent). */
+    private insertNameSegments;
     /**
      * Insert multiple nodes in a transaction
      */
@@ -40,6 +48,44 @@ export declare class QueryBuilder {
      * Delete all nodes for a file
      */
     deleteNodesByFile(filePath: string): void;
+    /** Wipe the segment vocabulary. A full index calls this at its start; the
+     *  node write path repopulates it as files (re-)index, so the end state is
+     *  exactly the current names with no orphan rows. */
+    clearNameSegmentVocab(): void;
+    /** True when the vocab has no rows — an index built before the table existed.
+     *  `sync` uses this to heal such databases (see rebuildNameSegmentVocabFrom). */
+    isNameSegmentVocabEmpty(): boolean;
+    /** One page of distinct segmentable node names, for batched vocab rebuilds
+     *  (file basenames and import specifiers are excluded from the vocab — see
+     *  insertNode). */
+    getDistinctNodeNames(limit: number, offset: number): string[];
+    /** Insert segments for a batch of names in one transaction (vocab heal path). */
+    insertNameSegmentsBatch(names: string[]): void;
+    /**
+     * Names whose segments cover at least `minWords` distinct PROMPT WORDS —
+     * the co-occurrence probe behind the prompt hook's medium tier: the words
+     * "state" and "machine" both being segments of `OrderStateMachine` is strong
+     * evidence the prompt names that symbol in prose. Ordered by coverage.
+     *
+     * Takes (segment variant → original word) pairs and folds variants back to
+     * their word INSIDE the SQL: a name matching both `service` and `services`
+     * counts ONE word, not two. Counting raw variants let plural-variant pairs
+     * of a single word tie with genuine two-word matches and — because ORDER
+     * BY/LIMIT run here, before any JS-side re-check — crowd a real match past
+     * the LIMIT on vocab-heavy repos (#1146).
+     */
+    getSegmentCoOccurrence(variants: Array<{
+        segment: string;
+        word: string;
+    }>, minWords: number, limit: number): Array<{
+        name: string;
+        matches: number;
+    }>;
+    /** How many distinct names each segment appears in — the rarity signal that
+     *  separates a discriminative word ("checkout") from a ubiquitous one ("state"). */
+    getSegmentNameCounts(segments: string[]): Map<string, number>;
+    /** Names containing the given segment (rare-single-word tier). */
+    getNamesForSegment(segment: string, limit: number): string[];
     /**
      * Get a node by ID
      */
@@ -152,10 +198,32 @@ export declare class QueryBuilder {
      * Get all nodes in the database
      */
     getAllNodes(): Node[];
+    /**
+     * Stream nodes of one language whose `decorators` JSON array contains
+     * `decorator`. The LIKE on the JSON text is a cheap index-free pre-filter
+     * (a decorator name can appear as a substring of another), so callers must
+     * still exact-check `node.decorators.includes(decorator)`. Exists so the
+     * kotlin expect/actual synthesizer never materializes the whole node table
+     * the way `getAllNodes().filter(...)` did — that array alone OOM'd Node's
+     * default heap on a 2M-node graph (#1212).
+     */
+    iterateNodesByLanguageWithDecorator(language: Language, decorator: string): IterableIterator<Node>;
+    /**
+     * Distinct languages present in the files table. One indexed aggregate —
+     * lets the dynamic-edge synthesizers skip passes for languages the project
+     * doesn't contain at all (a Kotlin pass has no work on a pure-C repo), so
+     * their cost is zero rather than a full-graph scan that finds nothing (#1212).
+     */
+    getDistinctFileLanguages(): Set<string>;
     /**
      * Get nodes by exact name match (uses idx_nodes_name index)
      */
     getNodesByName(name: string): Node[];
+    /**
+     * Nodes whose name starts with `prefix`, by index range scan (a LIKE would
+     * skip idx_nodes_name under SQLite's default case-insensitive LIKE).
+     */
+    getNodesByNamePrefix(prefix: string, limit?: number): Node[];
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
@@ -251,6 +319,17 @@ export declare class QueryBuilder {
      * about the target symbol.
      */
     getVbaCallStubs(): Node[];
+    /**
+     * Find VBA reference-stub candidate nodes for `resolveVbaReferenceStubs`
+     * (issue #78).
+     *
+     * A VBA reference-stub is a `class` node whose `metadata.synthesizedBy`
+     * starts with `vba-` and is targeted by a `references` edge from a VBA
+     * module. These synthetic nodes are created by the extractor for
+     * cross-file type references (`Dim x As MyEnum`) but may not have been
+     * resolved to the real type node during the main resolution pass.
+     */
+    getVbaReferenceStubs(): Node[];
     /**
      * Repoint an edge's `target` + `metadata` in place, leaving all other
      * columns (source, kind, line, col, provenance) untouched. Used by
@@ -315,6 +394,8 @@ export declare class QueryBuilder {
     getCrossFileIncomingEdgesWithTarget(filePath: string): Array<Edge & {
         targetName: string;
         targetKind: NodeKind;
+        sourceFilePath: string;
+        sourceLanguage: Language;
     }>;
     /**
      * Insert or update a file record
@@ -362,12 +443,18 @@ export declare class QueryBuilder {
      */
     getUnresolvedReferences(): UnresolvedReference[];
     /**
-     * Get the count of unresolved references without loading them into memory
+     * Get the count of PENDING (never-attempted) references without loading
+     * them into memory. Rows marked status='failed' — attempted by a completed
+     * pass, no match — are excluded: they are not outstanding work, only retry
+     * candidates for the #1240 sweep, so they must not trip the #1187 orphan
+     * sweep or the `status` pending-refs warning.
      */
     getUnresolvedReferencesCount(): number;
     /**
-     * Get a batch of unresolved references using LIMIT/OFFSET pagination.
-     * Used to process references in bounded memory chunks.
+     * Get a batch of PENDING unresolved references using LIMIT/OFFSET
+     * pagination. Used to process references in bounded memory chunks; failed
+     * rows are excluded so the batched drain loop terminates once every row
+     * has been attempted.
      */
     getUnresolvedReferencesBatch(offset: number, limit: number): UnresolvedReference[];
     /**
@@ -378,6 +465,13 @@ export declare class QueryBuilder {
      * Get all distinct node names (lightweight — just name strings for pre-filtering)
      */
     getAllNodeNames(): string[];
+    /**
+     * Stream the distinct node names one row at a time — the incremental
+     * counterpart to {@link getAllNodeNames} for callers that need to yield
+     * to the event loop mid-scan (resolver cache warm-up on multi-million-node
+     * indexes). Fresh statement per call: the iterator holds an open cursor.
+     */
+    iterateNodeNames(): IterableIterator<string>;
     /**
      * Get unresolved references scoped to specific file paths.
      * Uses the idx_unresolved_file_path index for efficient lookup.
@@ -400,6 +494,35 @@ export declare class QueryBuilder {
         referenceName: string;
         referenceKind: string;
     }>): void;
+    /**
+     * Mark refs a completed resolution pass could not resolve as status='failed'
+     * instead of deleting them (#1240). Failed rows are invisible to the pending
+     * count/batch readers (so drain loops and the #1187 orphan sweep still
+     * terminate) but stay queryable by name_tail so a later sync can retry them
+     * when a changed file introduces a symbol that could satisfy them. name_tail
+     * is (re)written here so rows inserted before the v8 migration get their
+     * tail the first time they're attempted.
+     */
+    markReferencesFailed(refs: Array<{
+        fromNodeId: string;
+        referenceName: string;
+        referenceKind: string;
+    }>): void;
+    /**
+     * Failed refs whose name tail matches one of the given symbol names — the
+     * candidates a sync should retry after files carrying those names changed
+     * (#1240). Names matching more than `perNameCeiling` failed refs are
+     * skipped entirely: at that population a name is external/builtin noise
+     * (`get`, `map`, …) that one new definition won't resolve — the same
+     * rationale as resolution's AMBIGUOUS_NAME_CEILING (#999) — and retrying an
+     * arbitrary subset would be both wasted work and incoherent coverage.
+     */
+    getRetryableFailedReferences(names: string[], perNameCeiling?: number): UnresolvedReference[];
+    /**
+     * Distinct node names present in the given files — the symbol names a sync
+     * pass uses to look up retryable failed refs after those files changed.
+     */
+    getNodeNamesByFiles(filePaths: string[]): string[];
     /**
      * Lightweight (nodes, edges) count snapshot. Used around an index/sync
      * run to compute true additions across extraction + resolution +