homegraph 1.2.0 → 1.5.0

package/dist/index.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HomeGraph = exports.MCPServer = exports.LockUnavailableError = exports.FileWatcher = exports.MemoryMonitor = exports.throttle = exports.debounce = exports.processInBatches = exports.FileLock = exports.Mutex = exports.defaultLogger = exports.silentLogger = exports.getLogger = exports.setLogger = exports.ConfigError = exports.VectorError = exports.SearchError = exports.DatabaseError = exports.ParseError = exports.FileError = exports.HomeGraphError = exports.loadAllGrammars = exports.loadGrammarsForLanguages = exports.initGrammars = exports.getSupportedLanguages = exports.isGrammarLoaded = exports.isLanguageSupported = exports.detectLanguage = exports.HOMEGRAPH_DIR = exports.findNearestHomeGraphRoot = exports.isInitialized = exports.getHomeGraphDir = exports.QueryBuilder = exports.DatabaseConnection = exports.getDatabasePath = void 0;
 const path = __importStar(require("path"));
 const db_1 = require("./db");
+const wal_valve_1 = require("./db/wal-valve");
 const queries_1 = require("./db/queries");
 const directory_1 = require("./directory");
 const extraction_1 = require("./extraction");
@@ -58,6 +59,9 @@ const sync_1 = require("./sync");
 const extraction_version_1 = require("./extraction/extraction-version");
 const directory_2 = require("./directory");
 const query_utils_1 = require("./search/query-utils");
+const identifier_segments_1 = require("./search/identifier-segments");
+const cooperative_yield_1 = require("./resolution/cooperative-yield");
+const resolver_pool_1 = require("./resolution/resolver-pool");
 const version_1 = require("./mcp/version");
 // Re-export types for consumers
 __exportStar(require("./types"), exports);
@@ -375,26 +379,74 @@ class HomeGraph {
             catch {
                 return { success: false, filesIndexed: 0, filesSkipped: 0, filesErrored: 0, nodesCreated: 0, edgesCreated: 0, errors: [{ message: 'Could not acquire file lock - another process may be indexing', severity: 'error' }], durationMs: 0 };
             }
+            const freshDb = this.queries.getNodeAndEdgeCount().nodes === 0;
+            const fastInit = process.env.HOMEGRAPH_NO_FAST_INIT !== '1' && freshDb;
+            if (fastInit) {
+                try {
+                    this.db.getDb().pragma('journal_mode = MEMORY');
+                    this.db.getDb().pragma('synchronous = OFF');
+                }
+                catch { /* keep WAL */ }
+            }
+            const deferWal = !fastInit && process.env.HOMEGRAPH_NO_WAL_DEFER !== '1' && this.db.getJournalMode() === 'wal';
+            let walValve = null;
+            let priorAutocheckpoint = 1000;
+            let restoreAutocheckpoint = false;
+            if (deferWal) {
+                priorAutocheckpoint = this.db.getWalAutocheckpoint();
+                this.db.setWalAutocheckpoint(0);
+                walValve = new wal_valve_1.WalCheckpointValve(this.db, (0, wal_valve_1.resolveWalValveMb)(process.env.HOMEGRAPH_WAL_VALVE_MB, this.db.getDbFileSizeBytes()), undefined, options.verbose ? (m) => console.log(`[wal-valve] ${m}`) : undefined);
+                walValve.start();
+            }
             try {
                 const before = this.queries.getNodeAndEdgeCount();
-                const result = await this.orchestrator.indexAll(options.onProgress, options.signal, options.verbose);
-                // Re-detect frameworks now that the index is populated. The resolver
-                // is constructed with createResolver() before any files exist, so
-                // framework resolvers whose detect() consults the indexed file list
-                // (e.g. UIKit/SwiftUI scanning for imports, swift-objc-bridge looking
-                // for both Swift and ObjC files) all return false on that initial pass
-                // and silently drop themselves. Re-initializing here gives them a
-                // chance to see the actual project before resolution runs.
+                try {
+                    this.queries.setMetadata('index_state', 'indexing');
+                }
+                catch { /* metadata is advisory */ }
+                try {
+                    this.queries.clearNameSegmentVocab();
+                }
+                catch { /* vocab is advisory — never fail an index over it */ }
+                this.db.beginBulkNodeLoad();
+                if (freshDb)
+                    this.db.beginBulkParseLoad();
+                let result;
+                try {
+                    result = await this.orchestrator.indexAll(options.onProgress, options.signal, options.verbose, walValve ? () => walValve.backpressure() : undefined, freshDb ? { dbPath: this.db.getPath(), fastInit } : null);
+                }
+                finally {
+                    if (freshDb) {
+                        const tIdx = Date.now();
+                        await this.db.endBulkParseLoad();
+                        if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                            console.error(`[phase-timing] parse-index-rebuild: ${Date.now() - tIdx}ms`);
+                    }
+                    const tFts = Date.now();
+                    this.db.endBulkNodeLoad();
+                    if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                        console.error(`[phase-timing] fts-rebuild: ${Date.now() - tFts}ms`);
+                }
+                if (walValve)
+                    await walValve.foldNow();
                 if (result.success && result.filesIndexed > 0) {
                     this.resolver.initialize();
-                    // Cross-file finalization (e.g. NestJS RouterModule prefixes). Runs
-                    // before resolution so updated names show up in subsequent reads.
                     this.resolver.runPostExtract();
                 }
-                // Resolve references to create call/import/extends edges
                 if (result.success && result.filesIndexed > 0) {
-                    // Get count without loading all refs into memory
                     const unresolvedCount = this.queries.getUnresolvedReferencesCount();
+                    if (fastInit && unresolvedCount >= (0, resolver_pool_1.minRefsForPool)()) {
+                        try {
+                            this.db.getDb().pragma('synchronous = NORMAL');
+                            this.db.getDb().pragma('journal_mode = WAL');
+                            priorAutocheckpoint = this.db.getWalAutocheckpoint();
+                            this.db.setWalAutocheckpoint(0);
+                            restoreAutocheckpoint = true;
+                            walValve = new wal_valve_1.WalCheckpointValve(this.db, undefined, undefined, options.verbose ? (m) => console.log(`[wal-valve] ${m}`) : undefined);
+                            walValve.start();
+                        }
+                        catch { /* keep current mode; resolution still works sequentially */ }
+                    }
                     options.onProgress?.({
                         phase: 'resolving',
                         current: 0,
@@ -406,34 +458,28 @@ class HomeGraph {
                             current,
                             total,
                         });
-                    });
-                    // Second pass: chained calls whose method lives on a supertype the
-                    // receiver conforms to (protocol-extension / inherited / default-
-                    // interface). Needs the implements/extends edges the main pass just
-                    // built, so it runs after resolution (#750).
+                    }, (done, totalPasses) => {
+                        options.onProgress?.({
+                            phase: 'linking',
+                            current: done,
+                            total: totalPasses,
+                        });
+                    }, walValve ? () => walValve.backpressure() : undefined);
                     await this.resolver.resolveChainedCallsViaConformance();
-                    // Same lifecycle for `this.<member>` callback registrations whose
-                    // member is inherited from a supertype (#808).
                     await this.resolver.resolveDeferredThisMemberRefs();
                 }
-                // Refresh planner stats + checkpoint the WAL after bulk writes.
-                // Cheap and non-blocking; never load-bearing for correctness.
                 if (result.success && result.filesIndexed > 0) {
-                    this.db.runMaintenance();
+                    if (walValve) {
+                        walValve.stop();
+                        await walValve.drain();
+                    }
+                    await this.db.runMaintenance();
                 }
-                // The orchestrator only sees extraction-phase counts; resolution and
-                // synthesizer edges (often >50% of the graph on JVM repos) come later.
-                // Recompute against the DB so the CLI summary reports the true totals.
                 if (result.success && result.filesIndexed > 0) {
                     const after = this.queries.getNodeAndEdgeCount();
                     result.nodesCreated = after.nodes - before.nodes;
                     result.edgesCreated = after.edges - before.edges;
                 }
-                // Stamp the index with the engine that built it, so `homegraph status`
-                // and `homegraph upgrade` can recommend a re-index when the running
-                // engine produces richer extraction than the one on disk. Only on a
-                // real full index — a sync touches a subset, so it must NOT advance the
-                // extraction stamp (the bulk would still be stale). See extraction-version.ts.
                 if (result.success && result.filesIndexed > 0) {
                     try {
                         this.queries.setMetadata('indexed_with_version', version_1.HomeGraphPackageVersion);
@@ -448,9 +494,54 @@ class HomeGraph {
                         result.errors.push({ message: ohosBinding.message, severity: 'warning', code: ohosBinding.code });
                     }
                 }
+                try {
+                    if (!result.success) {
+                        this.queries.setMetadata('index_state', 'failed');
+                    }
+                    else {
+                        const accounted = result.filesIndexed + result.filesSkipped + result.filesErrored;
+                        const discovered = result.filesDiscovered;
+                        const shortfall = discovered !== undefined ? discovered - accounted : 0;
+                        if (discovered !== undefined && shortfall > 0) {
+                            this.queries.setMetadata('index_state', 'partial');
+                            this.queries.setMetadata('index_files_discovered', String(discovered));
+                            this.queries.setMetadata('index_files_accounted', String(accounted));
+                            result.errors.push({
+                                message: `Index is missing ${shortfall} of ${discovered} discovered files (indexed ${result.filesIndexed}, skipped ${result.filesSkipped}, errored ${result.filesErrored}). The index is PARTIAL — re-run \`homegraph index\`.`,
+                                severity: 'warning',
+                                code: 'index_partial',
+                            });
+                        }
+                        else {
+                            this.queries.setMetadata('index_state', 'complete');
+                            if (discovered !== undefined) {
+                                this.queries.setMetadata('index_files_discovered', String(discovered));
+                                this.queries.setMetadata('index_files_accounted', String(accounted));
+                            }
+                        }
+                    }
+                }
+                catch { /* metadata is advisory — never fail an index over it */ }
                 return result;
             }
             finally {
+                if (walValve) {
+                    walValve.stop();
+                    await walValve.drain();
+                }
+                if (deferWal || restoreAutocheckpoint) {
+                    try {
+                        this.db.setWalAutocheckpoint(priorAutocheckpoint);
+                    }
+                    catch { /* connection may be closing */ }
+                }
+                if (fastInit) {
+                    try {
+                        this.db.getDb().pragma('synchronous = NORMAL');
+                        this.db.getDb().pragma('journal_mode = WAL');
+                    }
+                    catch { /* connection may be closing */ }
+                }
                 this.fileLock.release();
             }
         });
@@ -489,20 +580,41 @@ class HomeGraph {
             catch {
                 return { filesChecked: 0, filesAdded: 0, filesModified: 0, filesRemoved: 0, nodesUpdated: 0, durationMs: 0 };
             }
+            const deferWal = process.env.HOMEGRAPH_NO_WAL_DEFER !== '1' && this.db.getJournalMode() === 'wal';
+            let walValve = null;
+            let priorAutocheckpoint = 1000;
+            if (deferWal) {
+                priorAutocheckpoint = this.db.getWalAutocheckpoint();
+                this.db.setWalAutocheckpoint(0);
+                walValve = new wal_valve_1.WalCheckpointValve(this.db, (0, wal_valve_1.resolveWalValveMb)(process.env.HOMEGRAPH_WAL_VALVE_MB, this.db.getDbFileSizeBytes()), undefined, options.verbose ? (m) => console.log(`[wal-valve] ${m}`) : undefined);
+                walValve.start();
+            }
             try {
-                const result = await this.orchestrator.sync(options.onProgress);
-                // Cross-file finalization (e.g. NestJS RouterModule prefixes). Run on
-                // every sync that touched files so edits to `app.module.ts` propagate
-                // to controllers in unchanged files. The pass is idempotent and cheap
-                // (regex over *.module.ts only).
+                const vocabWasEmpty = (() => {
+                    try {
+                        return this.queries.isNameSegmentVocabEmpty();
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+                const result = await this.orchestrator.sync(options.onProgress, options.paths);
+                if (walValve)
+                    await walValve.foldNow();
                 if (result.filesAdded > 0 || result.filesModified > 0) {
                     this.resolver.runPostExtract();
                 }
-                // Resolve references if files were updated
-                if (result.filesAdded > 0 || result.filesModified > 0) {
+                else if (result.filesRemoved > 0) {
+                    this.resolver.clearCaches();
+                }
+                const filesChanged = result.filesAdded > 0 || result.filesModified > 0;
+                const backpressure = walValve ? () => walValve.backpressure() : undefined;
+                if (filesChanged) {
                     if (result.changedFilePaths) {
-                        // Scope resolution to changed files (git fast path — bounded set)
+                        const tRefLoad = Date.now();
                         const unresolvedRefs = this.queries.getUnresolvedReferencesByFiles(result.changedFilePaths);
+                        if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                            console.error(`[phase-timing] sync-ref-load: ${Date.now() - tRefLoad}ms (${unresolvedRefs.length} refs)`);
                         options.onProgress?.({
                             phase: 'resolving',
                             current: 0,
@@ -515,9 +627,25 @@ class HomeGraph {
                                 total,
                             });
                         });
+                        const tRetry = Date.now();
+                        const retryable = this.queries.getRetryableFailedReferences(this.queries.getNodeNamesByFiles(result.changedFilePaths));
+                        if (retryable.length > 0) {
+                            options.onProgress?.({
+                                phase: 'resolving',
+                                current: 0,
+                                total: retryable.length,
+                            });
+                            await this.resolver.resolveAndPersistListYielding(retryable);
+                            options.onProgress?.({
+                                phase: 'resolving',
+                                current: retryable.length,
+                                total: retryable.length,
+                            });
+                        }
+                        if (process.env.HOMEGRAPH_SYNTH_TIMINGS)
+                            console.error(`[phase-timing] sync-failed-ref-retry: ${Date.now() - tRetry}ms (${retryable.length} refs)`);
                     }
                     else {
-                        // No git info — use batched resolution to avoid OOM
                         const unresolvedCount = this.queries.getUnresolvedReferencesCount();
                         options.onProgress?.({
                             phase: 'resolving',
@@ -530,23 +658,62 @@ class HomeGraph {
                                 current,
                                 total,
                             });
-                        });
+                        }, (done, totalPasses) => {
+                            options.onProgress?.({
+                                phase: 'linking',
+                                current: done,
+                                total: totalPasses,
+                            });
+                        }, backpressure);
                     }
-                    // Second pass: chained calls whose method lives on a supertype the
-                    // receiver conforms to (protocol-extension / inherited). Needs the
-                    // implements/extends edges built above (#750).
+                }
+                const orphanCount = this.queries.getUnresolvedReferencesCount();
+                if (orphanCount > 0) {
+                    options.onProgress?.({
+                        phase: 'resolving',
+                        current: 0,
+                        total: orphanCount,
+                    });
+                    await this.resolveReferencesBatched((current, total) => {
+                        options.onProgress?.({
+                            phase: 'resolving',
+                            current,
+                            total,
+                        });
+                    }, (done, totalPasses) => {
+                        options.onProgress?.({
+                            phase: 'linking',
+                            current: done,
+                            total: totalPasses,
+                        });
+                    }, backpressure);
+                }
+                if (filesChanged || orphanCount > 0) {
                     await this.resolver.resolveChainedCallsViaConformance();
-                    // Same lifecycle for `this.<member>` callback registrations whose
-                    // member is inherited from a supertype (#808).
                     await this.resolver.resolveDeferredThisMemberRefs();
                 }
-                // Refresh planner stats + checkpoint the WAL after bulk writes.
-                if (result.filesAdded > 0 || result.filesModified > 0 || result.filesRemoved > 0) {
-                    this.db.runMaintenance();
+                if (filesChanged || result.filesRemoved > 0 || orphanCount > 0) {
+                    await this.db.runMaintenance();
+                }
+                try {
+                    if (vocabWasEmpty && this.queries.getNodeAndEdgeCount().nodes > 0) {
+                        await this.rebuildNameSegmentVocab();
+                    }
                 }
+                catch { /* vocab is advisory — never fail a sync over it */ }
                 return result;
             }
             finally {
+                if (walValve) {
+                    walValve.stop();
+                    await walValve.drain();
+                }
+                if (deferWal) {
+                    try {
+                        this.db.setWalAutocheckpoint(priorAutocheckpoint);
+                    }
+                    catch { /* connection may be closing */ }
+                }
                 this.fileLock.release();
             }
         });
@@ -572,8 +739,8 @@ class HomeGraph {
     watch(options = {}) {
         if (this.watcher?.isActive())
             return true;
-        this.watcher = new sync_1.FileWatcher(this.projectRoot, async () => {
-            const result = await this.sync();
+        this.watcher = new sync_1.FileWatcher(this.projectRoot, async (paths) => {
+            const result = await this.sync({ paths });
             // sync() returns this exact zero-shape iff it failed to acquire the
             // file lock (a real empty sync always has filesChecked > 0 because
             // scanDirectory ran). Surface that to the watcher as a typed error
@@ -660,6 +827,18 @@ class HomeGraph {
     getQueryBuilder() {
         return this.queries;
     }
+    /**
+     * Completeness of the last full index run. `'complete'` is the only good
+     * state. `'indexing'` after the fact means a run was killed mid-index;
+     * `'partial'` means the run finished but silently dropped files;
+     * `'failed'` means it reported failure. `null` = index predates this marker.
+     */
+    getIndexState() {
+        const raw = this.queries.getMetadata('index_state');
+        return raw === 'indexing' || raw === 'complete' || raw === 'partial' || raw === 'failed'
+            ? raw
+            : null;
+    }
     /**
      * Which engine built the current index: the package version + extraction
      * version stamped at the last full `indexAll`. Either field is null for an
@@ -725,12 +904,33 @@ class HomeGraph {
      * Resolve references in batches to keep memory bounded on large codebases.
      * Processes chunks of unresolved refs, persisting results after each batch.
      */
-    async resolveReferencesBatched(onProgress) {
-        return this.resolver.resolveAndPersistBatched(onProgress);
+    async resolveReferencesBatched(onProgress, onSynthesisProgress, backpressure) {
+        return this.resolver.resolveAndPersistBatched(onProgress, undefined, onSynthesisProgress, {
+            dbPath: this.db.getPath(),
+            bulkEdgeLoad: {
+                begin: () => this.db.beginBulkEdgeLoad(),
+                end: () => this.db.endBulkEdgeLoad(),
+            },
+            refIndexLoad: {
+                begin: () => this.db.beginBulkRefLoad(),
+                end: () => this.db.endBulkRefLoad(),
+            },
+            backpressure,
+        });
     }
     /**
      * Get detected frameworks in the project
      */
+    /**
+     * References extracted but never attempted by a resolution pass. Zero on a
+     * healthy index — a completed pass consumes every pending row (resolving it
+     * or parking it as failed, #1240). Non-zero at rest means a pass was
+     * interrupted mid-run (#1187), so some files' call edges are missing; the
+     * next `sync` sweeps them.
+     */
+    getPendingReferenceCount() {
+        return this.queries.getUnresolvedReferencesCount();
+    }
     getDetectedFrameworks() {
         return this.resolver.getDetectedFrameworks();
     }
@@ -752,9 +952,8 @@ class HomeGraph {
         return stats;
     }
     /**
-     * Active SQLite backend for this project's connection (`node-sqlite` — Node's
-     * built-in real-SQLite module). Surfaced via `homegraph status` and the
-     * `homegraph_status` MCP tool alongside the effective journal mode.
+     * Active SQLite backend (`native` = better-sqlite3, or `wasm` fallback).
+     * Surfaced via `homegraph status` / `homegraph_status` with journal mode.
      */
     getBackend() {
         return this.db.getBackend();
@@ -797,6 +996,16 @@ class HomeGraph {
     getNodesByName(name) {
         return this.queries.getNodesByName(name);
     }
+    /**
+     * Nodes whose name CONTAINS `substring` (LIKE scan, ASCII-case-insensitive,
+     * shortest-first). The camel-infix lookup FTS can't do — `profileInfo`
+     * inside `getProfileInfoV2` is one FTS token (#1196).
+     */
+    getNodesByNameSubstring(substring, options = {}) {
+        return this.queries
+            .findNodesByNameSubstring(substring, options)
+            .map((r) => r.node);
+    }
     /**
      * Search nodes by text
      */
@@ -810,6 +1019,178 @@ class HomeGraph {
      * bias, which would otherwise pull overloaded tokens toward whichever stack
      * embeds the project name.
      */
+    /**
+     * Graph-derived prompt matching for the front-load hook's MEDIUM tier:
+     * which indexed symbols do these prose words name? "state machine des
+     * commandes" → `OrderStateMachine`, in any human language whose technical
+     * nouns are Latin script — no keyword list involved.
+     *
+     * Precision comes from the repo's own naming statistics, not vocabulary:
+     * - CO-OCCURRENCE: ≥2 words that are segments of the SAME name ("state" +
+     *   "machine" → OrderStateMachine) is strong evidence and always qualifies.
+     * - RARITY: a single matched word qualifies only when its segment is
+     *   discriminative here (≤ {@link SEGMENT_RARITY_CEILING} distinct names) —
+     *   "checkout" in a shop backend yes, "state" in a react app no.
+     * Every candidate is re-verified against `nodes` before being returned
+     * (vocab rows are proposals; deletions leave orphans by design), so a
+     * returned symbol is guaranteed to exist right now.
+     */
+    getSegmentMatches(words, limit = 6) {
+        if (words.length === 0)
+            return [];
+        // Variant → original word (plural folding), for coverage accounting.
+        const variantToWord = new Map();
+        for (const word of words) {
+            for (const variant of (0, identifier_segments_1.segmentLookupVariants)(word)) {
+                if (!variantToWord.has(variant))
+                    variantToWord.set(variant, word);
+            }
+        }
+        const variants = [...variantToWord.keys()];
+        // Tier A: co-occurrence. The SQL folds variants back to their original
+        // word (#1146), so minWords=2 means two distinct PROMPT WORDS — a name
+        // matching both `service` and `services` can't tie with (or crowd past
+        // the LIMIT) a genuine two-word match. The JS re-check below recomputes
+        // the fold from live segments as the honesty layer.
+        const variantPairs = [...variantToWord.entries()].map(([segment, word]) => ({ segment, word }));
+        const candidates = [];
+        for (const hit of this.queries.getSegmentCoOccurrence(variantPairs, 2, 24)) {
+            const matched = this.wordsMatchingName(hit.name, variantToWord);
+            if (matched.size >= 2)
+                candidates.push({ name: hit.name, matchedWords: matched });
+        }
+        // Tier B: single rare word. Only when co-occurrence found nothing — a
+        // co-occurring name is categorically stronger evidence — and under
+        // stricter rules, because one word is thin: the word must be ≥5 chars
+        // (measured FPs: "this", "typo"); the segment must appear in AT LEAST TWO
+        // names (a concept the codebase is about clusters across names —
+        // CheckoutService/CheckoutController — while a prose coincidence is a
+        // singleton: measured FP "deploy to PRODUCTION" → the one name
+        // matchesNonProductionDir); and the candidate name must have ≥2 segments
+        // (a bare common verb matching a bare function name — "write" → `write` —
+        // is prose coincidence, not the user naming a symbol).
+        if (candidates.length === 0) {
+            const singleWordVariants = variants.filter((v) => variantToWord.get(v).length >= 5);
+            const counts = this.queries.getSegmentNameCounts(singleWordVariants);
+            const rare = [...counts.entries()]
+                .filter(([, n]) => n >= 2 && n <= HomeGraph.SEGMENT_RARITY_CEILING)
+                .sort((a, b) => a[1] - b[1])
+                .slice(0, 2);
+            for (const [variant] of rare) {
+                const word = variantToWord.get(variant);
+                for (const name of this.queries.getNamesForSegment(variant, 12)) {
+                    if ((0, identifier_segments_1.splitIdentifierSegments)(name).length < 2)
+                        continue;
+                    candidates.push({ name, matchedWords: new Set([word]) });
+                }
+            }
+        }
+        // Verify against nodes (the honesty gate) and pick a representative
+        // definition per name. A name whose only nodes are file/import kind has
+        // no real definition to point at — surfacing the import statement instead
+        // reads as a matched symbol but isn't one (#1144) — so it's skipped, the
+        // same way an orphaned vocab row is. (Import names no longer enter the
+        // vocab at write time, but rows written before that exclusion persist
+        // until the next full index.)
+        const out = [];
+        const seen = new Set();
+        candidates.sort((a, b) => b.matchedWords.size - a.matchedWords.size || a.name.length - b.name.length);
+        for (const candidate of candidates) {
+            if (out.length >= limit)
+                break;
+            if (seen.has(candidate.name))
+                continue;
+            seen.add(candidate.name);
+            const nodes = this.queries.getNodesByName(candidate.name);
+            if (nodes.length === 0)
+                continue; // orphaned vocab row — name no longer exists
+            const rep = nodes.find((n) => n.kind !== 'file' && n.kind !== 'import');
+            if (!rep)
+                continue; // no real definition — don't surface an import/file as one
+            out.push({
+                name: candidate.name,
+                kind: rep.kind,
+                filePath: rep.filePath,
+                startLine: rep.startLine ?? 0,
+                matchedWords: [...candidate.matchedWords].sort(),
+            });
+        }
+        return out;
+    }
+    /** A single word ("state") can match hundreds of names in a big repo — that
+     *  is noise, not signal. Ceiling for the single-word tier; co-occurrence is
+     *  exempt because two words on one name is already discriminative. */
+    static SEGMENT_RARITY_CEILING = 25;
+    /** Which of the prompt's original words match `name`'s segments (via
+     *  variants). Segments are recomputed in JS — a name-keyed vocab lookup
+     *  would scan the (segment, name) primary key. */
+    wordsMatchingName(name, variantToWord) {
+        const segments = new Set((0, identifier_segments_1.splitIdentifierSegments)(name));
+        const matched = new Set();
+        for (const [variant, word] of variantToWord) {
+            if (segments.has(variant))
+                matched.add(word);
+        }
+        return matched;
+    }
+    /**
+     * One-shot upgrade heal for callers that open the graph WITHOUT syncing —
+     * concretely the prompt hook, whose MEDIUM tier reads the segment
+     * vocabulary: a database migrated from before the vocab table existed
+     * starts with it empty, and the only other backfill lives inside `sync()`,
+     * which such callers never run (#1142). Returns true when the vocab is
+     * usable (already populated — the overwhelmingly common one-SELECT case —
+     * or healed here); false when it isn't (empty graph, or another process
+     * holds the index lock — that process's own sync heals it).
+     */
+    async healSegmentVocabIfEmpty() {
+        const empty = (() => {
+            try {
+                return this.queries.isNameSegmentVocabEmpty();
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (!empty)
+            return true;
+        if (this.queries.getNodeAndEdgeCount().nodes === 0)
+            return false;
+        return this.indexMutex.withLock(async () => {
+            try {
+                this.fileLock.acquire();
+            }
+            catch {
+                return false; // an index/sync is running — it backfills the vocab itself
+            }
+            try {
+                if (!this.queries.isNameSegmentVocabEmpty())
+                    return true; // raced: healed meanwhile
+                await this.rebuildNameSegmentVocab();
+                return true;
+            }
+            finally {
+                this.fileLock.release();
+            }
+        });
+    }
+    /**
+     * Rebuild the segment vocabulary from the current graph, batched and
+     * yielding — the upgrade-heal path for indexes built before the vocab table
+     * existed. Runs inside the index mutex/lock (sync and
+     * healSegmentVocabIfEmpty hold them).
+     */
+    async rebuildNameSegmentVocab() {
+        const maybeYield = (0, cooperative_yield_1.createYielder)();
+        const BATCH = 2000;
+        for (let offset = 0;; offset += BATCH) {
+            const names = this.queries.getDistinctNodeNames(BATCH, offset);
+            if (names.length === 0)
+                break;
+            this.queries.insertNameSegmentsBatch(names);
+            await maybeYield();
+        }
+    }
     getProjectNameTokens() {
         return this.queries.getProjectNameTokens();
     }