@zuvia-software-solutions/code-mapper 2.3.12 → 2.4.1

package/dist/mcp/local/local-backend.js

@@ -6,7 +6,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { execFileSync } from 'child_process';
-import { openDb, closeDb, getNode, findNodesByName, findNodesByFile, rawQuery, searchVector, countEmbeddings, searchFTS, queryChunked } from '../../core/db/adapter.js';
+import { openDb, closeDb, getNode, findNodesByName, findNodesByFile, rawQuery, countEmbeddings, searchFTS, queryChunked, findRefsBySymbol, searchFileWords } from '../../core/db/adapter.js';
 import { toNodeId, assertEdgeType } from '../../core/db/schema.js';
 import * as queries from '../../core/db/queries.js';
 import { refreshFiles, refreshEmbeddings } from '../../core/incremental/refresh.js';
@@ -55,6 +55,10 @@ export class LocalBackend {
     refreshLocks = new Map();
     /** Per-repo tsgo LSP service instances for live semantic enrichment */
     tsgoServices = new Map();
+    /** Per-repo in-memory embedding cache: nodeId → Float32Array (256-dim) */
+    embeddingCaches = new Map();
+    /** Per-repo in-memory NL embedding cache: includes source text for match_reason */
+    nlEmbeddingCaches = new Map();
     /** Get (or lazily start) a tsgo LSP service for a repo. Returns null if unavailable. */
     async getTsgo(repo) {
         const existing = this.tsgoServices.get(repo.id);
@@ -80,6 +84,128 @@ export class LocalBackend {
         const dbPath = path.join(handle.storagePath, 'index.db');
         return openDb(dbPath);
     }
+    /** Load all embeddings into memory for fast vector search */
+    loadEmbeddingCache(repoId) {
+        try {
+            const db = this.getDb(repoId);
+            const rows = db.prepare('SELECT nodeId, embedding FROM embeddings').all();
+            if (rows.length === 0) {
+                this.embeddingCaches.delete(repoId);
+                return;
+            }
+            const dims = rows[0].embedding.byteLength / 4;
+            const nodeIds = [];
+            const matrix = new Float32Array(rows.length * dims);
+            const norms = new Float32Array(rows.length);
+            for (let i = 0; i < rows.length; i++) {
+                const row = rows[i];
+                nodeIds.push(row.nodeId);
+                const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+                matrix.set(vec, i * dims);
+                // Pre-compute norm for fast cosine similarity
+                let norm = 0;
+                for (let d = 0; d < dims; d++)
+                    norm += vec[d] * vec[d];
+                norms[i] = Math.sqrt(norm);
+            }
+            this.embeddingCaches.set(repoId, { nodeIds, matrix, norms });
+        }
+        catch (err) {
+            console.error(`Code Mapper: Failed to load embedding cache: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    /** Search embeddings in memory — O(N) dot products, no disk I/O */
+    searchEmbeddingsInMemory(repoId, queryVec, limit = 10, maxDistance = 0.5) {
+        const cache = this.embeddingCaches.get(repoId);
+        if (!cache || cache.nodeIds.length === 0)
+            return [];
+        const dims = queryVec.length;
+        const results = [];
+        // Pre-compute query norm
+        let qNorm = 0;
+        for (let d = 0; d < dims; d++)
+            qNorm += queryVec[d] * queryVec[d];
+        qNorm = Math.sqrt(qNorm);
+        if (qNorm === 0)
+            return [];
+        for (let i = 0; i < cache.nodeIds.length; i++) {
+            const offset = i * dims;
+            let dot = 0;
+            for (let d = 0; d < dims; d++)
+                dot += queryVec[d] * cache.matrix[offset + d];
+            const similarity = dot / (qNorm * cache.norms[i]);
+            const distance = 1 - similarity;
+            if (distance < maxDistance) {
+                results.push({ nodeId: cache.nodeIds[i], distance });
+            }
+        }
+        results.sort((a, b) => a.distance - b.distance);
+        return results.slice(0, limit);
+    }
+    /** Load NL embeddings into memory for fast conceptual search */
+    loadNlEmbeddingCache(repoId) {
+        try {
+            const db = this.getDb(repoId);
+            let rows;
+            try {
+                rows = db.prepare('SELECT nodeId, embedding, text FROM nl_embeddings').all();
+            }
+            catch {
+                return;
+            } // table might not exist
+            if (rows.length === 0) {
+                this.nlEmbeddingCaches.delete(repoId);
+                return;
+            }
+            const dims = rows[0].embedding.byteLength / 4;
+            const nodeIds = [];
+            const texts = [];
+            const matrix = new Float32Array(rows.length * dims);
+            const norms = new Float32Array(rows.length);
+            for (let i = 0; i < rows.length; i++) {
+                const row = rows[i];
+                nodeIds.push(row.nodeId);
+                texts.push(row.text);
+                const vec = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+                matrix.set(vec, i * dims);
+                let norm = 0;
+                for (let d = 0; d < dims; d++)
+                    norm += vec[d] * vec[d];
+                norms[i] = Math.sqrt(norm);
+            }
+            this.nlEmbeddingCaches.set(repoId, { nodeIds, texts, matrix, norms });
+        }
+        catch { /* NL embeddings not available */ }
+    }
+    /** Search NL embeddings in memory, returns match_reason text */
+    searchNlEmbeddingsInMemory(repoId, queryVec, limit = 10, maxDistance = 0.5) {
+        const cache = this.nlEmbeddingCaches.get(repoId);
+        if (!cache || cache.nodeIds.length === 0)
+            return [];
+        const dims = queryVec.length;
+        const results = [];
+        let qNorm = 0;
+        for (let d = 0; d < dims; d++)
+            qNorm += queryVec[d] * queryVec[d];
+        qNorm = Math.sqrt(qNorm);
+        if (qNorm === 0)
+            return [];
+        const cacheDims = cache.matrix.length / cache.nodeIds.length;
+        for (let i = 0; i < cache.nodeIds.length; i++) {
+            const offset = i * cacheDims;
+            let dot = 0;
+            const minDims = Math.min(dims, cacheDims);
+            for (let d = 0; d < minDims; d++)
+                dot += queryVec[d] * cache.matrix[offset + d];
+            const similarity = dot / (qNorm * cache.norms[i]);
+            const distance = 1 - similarity;
+            if (distance < maxDistance) {
+                results.push({ nodeId: cache.nodeIds[i], distance, text: cache.texts[i] });
+            }
+        }
+        results.sort((a, b) => a.distance - b.distance);
+        return results.slice(0, limit);
+    }
     /** Hard ceiling — beyond this, incremental is unreliable, warn prominently */
     static MAX_INCREMENTAL_FILES = 200;
     /** Start file system watcher for a repo to detect source changes */
@@ -188,6 +314,9 @@ export class LocalBackend {
             const db = this.getDb(repo.id);
             const hasEmb = (repo.stats?.embeddings ?? 0) > 0;
             await refreshEmbeddings(db, dirtyFiles, hasEmb);
+            // Reload embedding cache after refresh
+            if (hasEmb)
+                this.loadEmbeddingCache(repo.id);
         }
         catch (err) {
             watcher.inject(dirtyFiles);
@@ -206,10 +335,22 @@ export class LocalBackend {
     async init() {
         await this.refreshRepos();
         // Start file watchers for incremental refresh
+        let anyEmbeddings = false;
         for (const [id, handle] of this.repos) {
             this.startWatcher(id, handle);
-            // Seed watcher with changes that happened while the server was down
             this.seedWatcherFromGit(id, handle);
+            // Load embedding caches into memory for fast vector search
+            if ((handle.stats?.embeddings ?? 0) > 0) {
+                this.loadEmbeddingCache(id);
+                anyEmbeddings = true;
+            }
+            this.loadNlEmbeddingCache(id); // NL cache loaded regardless (cheap, may not exist)
+        }
+        // Pre-warm MLX embedder so first query has zero model-load latency
+        if (anyEmbeddings) {
+            import('../../core/embeddings/embedder.js').then(({ initEmbedder }) => {
+                initEmbedder().catch(() => { });
+            }).catch(() => { });
         }
         return this.repos.size > 0;
     }
@@ -518,6 +659,9 @@ export class LocalBackend {
                 const end = d.endLine || 0;
                 const isSmall = end > 0 && start > 0 && (end - start) < 10;
                 lines.push(`  ${sig} — ${d.type} @ ${this.shortPath(d.filePath)}:${start || '?'}${mod}`);
+                if (d.match_reason) {
+                    lines.push(`    _"${d.match_reason}"_`);
+                }
                 if (isSmall && d.content) {
                     const src = String(d.content).trim();
                     if (src.length < 500) {
@@ -597,6 +741,9 @@ export class LocalBackend {
                 renderFlows(2);
             }
         }
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: Results ranked by BM25 keyword + semantic + refs + file-content signals. Natural language queries may miss code using different terminology. If results seem incomplete, try specific identifiers or `grep -rn "keyword" --include="*.ts"` for exhaustive search._');
         return lines.join('\n');
     }
     formatContextAsText(result) {
@@ -702,6 +849,10 @@ export class LocalBackend {
                 lines.push(`  ${p.name} (step ${p.step_index}/${p.step_count})`);
             }
         }
+        // Guidance footer for agents
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: Callers are from graph edges + refs index. For widely-used symbols, verify completeness with `grep -rn "symbolName(" --include="*.ts"`. Outgoing calls may miss dynamic dispatch or reflection._');
         return lines.join('\n');
     }
     formatImpactAsText(result) {
@@ -748,6 +899,9 @@ export class LocalBackend {
             lines.push('');
             lines.push(`### Modules: ${mods.map((m) => `${m.name} (${m.hits} ${m.impact})`).join(' | ')}`);
         }
+        lines.push('');
+        lines.push('---');
+        lines.push('_Note: d=1 callers include graph edges + refs index. Indirect deps through dynamic dispatch, config, or type-only references may not appear. For critical changes, verify d=1 with `grep -rn "symbolName" --include="*.ts"`._');
         return lines.join('\n');
     }
     formatDetectChangesAsText(result) {
@@ -918,15 +1072,24 @@ export class LocalBackend {
         // Enrich semantic query with task_context/goal for better embeddings
         const semanticQuery = [searchQuery, params.goal, params.task_context]
             .filter(Boolean).join(' — ');
-        // Step 1: Hybrid search (BM25 + semantic in parallel)
-        // BM25 uses raw query (keyword matching); semantic uses enriched query (better embedding)
+        // Step 0: Query expansion via nearest-neighbor embeddings
+        // "double charging" → finds "idempotencyKey" nearby → BM25 now searches for it
+        const { expandQuery } = await import('../../core/search/query-expansion.js');
+        const nnExpansionTerms = await this.expandQueryViaNearestNeighbors(repo, semanticQuery);
+        const expandedSearchQuery = nnExpansionTerms.length > 0
+            ? expandQuery(searchQuery, nnExpansionTerms)
+            : searchQuery;
+        // Step 1: Four-signal search in parallel
+        // BM25 uses expanded query; semantic uses enriched query; refs + file_words use raw query
         const searchLimit = processLimit * maxSymbolsPerProcess;
-        const [bm25Results, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
+        const [bm25Results, semanticResults, nlSemanticResults, refsResults, fileWordsResults] = await Promise.all([
+            this.bm25Search(repo, expandedSearchQuery, searchLimit),
             this.semanticSearch(repo, semanticQuery, searchLimit),
+            this.nlSemanticSearch(repo, searchQuery, searchLimit),
+            Promise.resolve(this.refsSearch(repo, searchQuery, searchLimit)),
+            Promise.resolve(this.fileWordsSearch(repo, searchQuery, searchLimit)),
         ]);
-        // Step 2: Weighted RRF merge (single implementation — no duplication)
-        // BM25 now returns symbol-level results with nodeId, name, type
+        // Step 2: Weighted RRF merge (5 signals)
         const bm25ForRRF = bm25Results.map((r, i) => ({
             nodeId: String(r.nodeId ?? ''),
             name: String(r.name ?? ''),
@@ -943,7 +1106,71 @@ export class LocalBackend {
             ...(r.startLine != null ? { startLine: r.startLine } : {}),
             ...(r.endLine != null ? { endLine: r.endLine } : {}),
         }));
-        const rrfMerged = mergeWithRRF(bm25ForRRF, semanticForRRF, { limit: searchLimit });
+        // Refs and file_words use BM25-compatible format for RRF
+        const refsForRRF = refsResults.map((r, i) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), type: String(r.type ?? 'File'),
+            filePath: String(r.filePath ?? ''), score: 1.0, rank: i + 1,
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        const fileWordsForRRF = fileWordsResults.map((r, i) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), type: String(r.type ?? 'File'),
+            filePath: String(r.filePath ?? ''), score: 1.0, rank: i + 1,
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        // NL semantic results get high weight — proven 100% recall on conceptual queries
+        const nlForRRF = nlSemanticResults.map((r) => ({
+            nodeId: String(r.nodeId ?? ''), name: String(r.name ?? ''), label: String(r.type ?? ''),
+            filePath: String(r.filePath ?? ''), distance: Number(r.distance ?? 1),
+            ...(r.startLine != null ? { startLine: r.startLine } : {}),
+            ...(r.endLine != null ? { endLine: r.endLine } : {}),
+        }));
+        // Merge code + NL semantic into one semantic list (best of both worlds)
+        const combinedSemantic = [...semanticForRRF, ...nlForRRF]
+            .sort((a, b) => a.distance - b.distance)
+            .filter((r, i, arr) => arr.findIndex(x => x.nodeId === r.nodeId) === i) // dedupe by nodeId
+            .slice(0, searchLimit);
+        let rrfMerged = mergeWithRRF(bm25ForRRF, combinedSemantic, { limit: searchLimit });
+        // Store NL match reasons for display
+        const nlMatchReasons = new Map();
+        for (const r of nlSemanticResults) {
+            if (r.match_reason && !nlMatchReasons.has(r.nodeId)) {
+                nlMatchReasons.set(r.nodeId, r.match_reason);
+            }
+        }
+        // Merge refs + fileWords into the RRF results (lower weight)
+        if (refsForRRF.length > 0 || fileWordsForRRF.length > 0) {
+            const supplemental = mergeWithRRF(refsForRRF, fileWordsForRRF.map((r) => ({
+                nodeId: r.nodeId, name: r.name, label: r.type, filePath: r.filePath, distance: 0.5,
+                ...(r.startLine != null ? { startLine: r.startLine } : {}),
+                ...(r.endLine != null ? { endLine: r.endLine } : {}),
+            })), { limit: searchLimit });
+            // Add supplemental results not already in main merge
+            const mainIds = new Set(rrfMerged.map(r => r.nodeId || r.filePath));
+            for (const s of supplemental) {
+                const key = s.nodeId || s.filePath;
+                if (!mainIds.has(key)) {
+                    rrfMerged.push({ ...s, score: s.score * 0.5 }); // lower weight for supplemental
+                    mainIds.add(key);
+                }
+            }
+            rrfMerged.sort((a, b) => b.score - a.score);
+            rrfMerged = rrfMerged.slice(0, searchLimit);
+        }
+        // Step 2b: Ripgrep fallback when all signals return sparse results
+        if (rrfMerged.length < 3) {
+            const rgResults = this.ripgrepFallback(repo, searchQuery, 10);
+            for (const rg of rgResults) {
+                if (!rrfMerged.some(m => m.filePath === rg.filePath)) {
+                    rrfMerged.push({
+                        filePath: rg.filePath, score: 0.01, rank: rrfMerged.length + 1,
+                        sources: ['bm25'], nodeId: rg.nodeId, name: rg.name, label: rg.type,
+                        startLine: rg.startLine, endLine: rg.endLine,
+                    });
+                }
+            }
+        }
         // Build lookup from original search data (keyed by both nodeId and filePath for cross-referencing)
         const searchDataMap = new Map();
         for (const r of bm25Results) {
@@ -957,13 +1184,22 @@ export class LocalBackend {
             if (!searchDataMap.has(key))
                 searchDataMap.set(key, r);
         }
-        let merged = rrfMerged.map(rrf => ({
-            score: rrf.score,
-            data: searchDataMap.get(rrf.nodeId ?? '') ?? searchDataMap.get(rrf.filePath) ?? {
+        for (const r of nlSemanticResults) {
+            const key = r.nodeId || r.filePath;
+            if (!searchDataMap.has(key))
+                searchDataMap.set(key, r);
+        }
+        let merged = rrfMerged.map(rrf => {
+            const data = searchDataMap.get(rrf.nodeId ?? '') ?? searchDataMap.get(rrf.filePath) ?? {
                 name: rrf.name ?? rrf.filePath.split('/').pop(), type: rrf.label ?? 'File',
                 filePath: rrf.filePath, nodeId: rrf.nodeId,
-            },
-        }));
+            };
+            // Attach NL match reason if available
+            const reason = nlMatchReasons.get(rrf.nodeId ?? '') ?? nlMatchReasons.get(data.nodeId ?? '');
+            if (reason)
+                data.match_reason = reason;
+            return { score: rrf.score, data };
+        });
         // Filter noise: remove test files, config files, docs from results by default
         merged = merged.filter(item => {
             const fp = String(item.data.filePath ?? '').toLowerCase();
@@ -1341,25 +1577,34 @@ export class LocalBackend {
      */
     async semanticSearch(repo, query, limit) {
         try {
-            // Check if embeddings exist before loading the model (avoids heavy model init when embeddings are off)
-            const semDb = this.getDb(repo.id);
-            const embCount = countEmbeddings(semDb);
-            if (embCount === 0)
-                return [];
+            // Use in-memory cache if available (10-100x faster than SQLite scan)
+            const cache = this.embeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0) {
+                // Fallback: check DB directly
+                const checkDb = this.getDb(repo.id);
+                const embCount = countEmbeddings(checkDb);
+                if (embCount === 0)
+                    return [];
+                // Load cache on demand
+                this.loadEmbeddingCache(repo.id);
+                if (!this.embeddingCaches.get(repo.id))
+                    return [];
+            }
             const { DEFAULT_MAX_SEMANTIC_DISTANCE } = await import('../../core/search/types.js');
             const { embedQuery } = await import('../../core/embeddings/embedder.js');
             const queryVec = await embedQuery(query);
-            // Brute-force cosine search via adapter (fast enough for <200K vectors at 256 dims)
-            const vecResults = searchVector(semDb, queryVec, limit, DEFAULT_MAX_SEMANTIC_DISTANCE);
+            // In-memory cosine search — no disk I/O
+            const vecResults = this.searchEmbeddingsInMemory(repo.id, queryVec, limit, DEFAULT_MAX_SEMANTIC_DISTANCE);
             if (vecResults.length === 0)
                 return [];
             // Batch metadata fetch
+            const metaDb = this.getDb(repo.id);
             const vecNodeIds = vecResults.map(r => r.nodeId);
             const distanceMap = new Map();
             for (const r of vecResults) {
                 distanceMap.set(r.nodeId, r.distance);
             }
-            const metaNodes = queries.findNodesByIds(semDb, vecNodeIds);
+            const metaNodes = queries.findNodesByIds(metaDb, vecNodeIds);
             return metaNodes.map(node => ({
                 nodeId: node.id,
                 name: node.name,
@@ -1375,6 +1620,185 @@ export class LocalBackend {
             return [];
         }
     }
+    /**
+     * NL semantic search: embed query with bge-small, search NL descriptions.
+     * Returns match_reason (the NL text that matched) for agent transparency.
+     */
+    async nlSemanticSearch(repo, query, limit) {
+        try {
+            const cache = this.nlEmbeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0)
+                return [];
+            const { nlEmbed } = await import('../../core/embeddings/nl-embedder.js');
+            const queryVec = await nlEmbed(query);
+            const vecResults = this.searchNlEmbeddingsInMemory(repo.id, queryVec, limit, 0.5);
+            if (vecResults.length === 0)
+                return [];
+            // Fetch node metadata
+            const metaDb = this.getDb(repo.id);
+            const seen = new Set();
+            const results = [];
+            for (const r of vecResults) {
+                if (seen.has(r.nodeId))
+                    continue;
+                seen.add(r.nodeId);
+                const node = getNode(metaDb, toNodeId(r.nodeId));
+                if (node) {
+                    results.push({
+                        nodeId: r.nodeId,
+                        name: node.name,
+                        type: node.label,
+                        filePath: node.filePath,
+                        distance: r.distance,
+                        startLine: node.startLine,
+                        endLine: node.endLine,
+                        match_reason: r.text, // The NL text that matched — shown to agents
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Refs-based search: find symbols referenced in files that contain the query identifiers.
+     * Bridges the gap between graph edges (incomplete) and grep (complete for exact names).
+     */
+    refsSearch(repo, query, limit) {
+        try {
+            const db = this.getDb(repo.id);
+            // Tokenize query into potential identifier names
+            const tokens = query.match(/\b[a-zA-Z_]\w{2,}\b/g) || [];
+            if (tokens.length === 0)
+                return [];
+            const seen = new Set();
+            const results = [];
+            for (const token of tokens) {
+                const refs = findRefsBySymbol(db, token, 50);
+                for (const ref of refs) {
+                    if (seen.has(ref.filePath))
+                        continue;
+                    seen.add(ref.filePath);
+                    // Find the best symbol in this file
+                    const fileNodes = findNodesByFile(db, ref.filePath);
+                    const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                    if (bestNode) {
+                        results.push({
+                            nodeId: bestNode.id,
+                            name: bestNode.name,
+                            type: bestNode.label,
+                            filePath: bestNode.filePath,
+                            startLine: bestNode.startLine,
+                            endLine: bestNode.endLine,
+                            refsScore: -results.length, // rank by order found
+                        });
+                    }
+                    if (results.length >= limit)
+                        break;
+                }
+                if (results.length >= limit)
+                    break;
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * File-words FTS search: find files whose content contains conceptual terms,
+     * then return the best symbol from each file. Bridges NL → code gap.
+     */
+    fileWordsSearch(repo, query, limit) {
+        try {
+            const db = this.getDb(repo.id);
+            const fileResults = searchFileWords(db, query, limit);
+            if (fileResults.length === 0)
+                return [];
+            const results = [];
+            for (const fr of fileResults) {
+                const fileNodes = findNodesByFile(db, fr.filePath);
+                const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                if (bestNode) {
+                    results.push({
+                        nodeId: bestNode.id,
+                        name: bestNode.name,
+                        type: bestNode.label,
+                        filePath: bestNode.filePath,
+                        startLine: bestNode.startLine,
+                        endLine: bestNode.endLine,
+                        fileWordsScore: fr.score,
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Query expansion via embedding nearest neighbors: embed the query,
+     * find 5 closest symbols, extract their names as BM25 expansion terms.
+     */
+    async expandQueryViaNearestNeighbors(repo, query) {
+        try {
+            const cache = this.embeddingCaches.get(repo.id);
+            if (!cache || cache.nodeIds.length === 0)
+                return [];
+            const { embedQuery } = await import('../../core/embeddings/embedder.js');
+            const queryVec = await embedQuery(query);
+            const neighbors = this.searchEmbeddingsInMemory(repo.id, queryVec, 5, 0.7);
+            // Extract symbol names from nodeIds (format: "Label:filePath:name")
+            return neighbors.map(n => {
+                const parts = n.nodeId.split(':');
+                return parts[parts.length - 1] || '';
+            }).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Ripgrep fallback: when all search signals return sparse results,
+     * grep the repo for query terms to find any relevant files.
+     */
+    ripgrepFallback(repo, query, limit) {
+        try {
+            const words = query.split(/\s+/).filter(w => w.length > 2).slice(0, 3);
+            if (words.length === 0)
+                return [];
+            const pattern = words.join('|');
+            const output = execFileSync('rg', ['-l', '-i', '--max-count', '1', pattern, '.'], {
+                cwd: repo.repoPath, encoding: 'utf-8', timeout: 3000,
+            });
+            const db = this.getDb(repo.id);
+            const results = [];
+            const files = output.trim().split('\n').filter(Boolean).slice(0, limit);
+            for (const f of files) {
+                const relPath = f.replace(/^\.\//, '');
+                const fileNodes = findNodesByFile(db, relPath);
+                const bestNode = fileNodes.find(n => n.label !== 'File') || fileNodes[0];
+                if (bestNode) {
+                    results.push({
+                        nodeId: bestNode.id,
+                        name: bestNode.name,
+                        type: bestNode.label,
+                        filePath: bestNode.filePath,
+                        startLine: bestNode.startLine,
+                        endLine: bestNode.endLine,
+                        matched_by: 'ripgrep',
+                    });
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
     async executeSql(repoName, query) {
         const repo = await this.resolveRepo(repoName);
         return this.sqlQuery(repo, { query });
@@ -1758,6 +2182,32 @@ export class LocalBackend {
                 // tsgo reference lookup failed — non-fatal, graph results still available
             }
         }
+        // Supplement callers from refs table (catches callers the graph missed)
+        try {
+            const refCallers = findRefsBySymbol(db, sym.name, 200);
+            const knownFiles = new Set(incomingRows.map(r => r.filePath));
+            let refsAdded = 0;
+            for (const ref of refCallers) {
+                if (ref.filePath === sym.filePath)
+                    continue; // skip self-file
+                if (knownFiles.has(ref.filePath))
+                    continue; // already have a caller from this file
+                const enclosing = this.findNodeAtPosition(db, ref.filePath, ref.line);
+                if (!enclosing)
+                    continue; // no symbol at this line (e.g. import statement)
+                knownFiles.add(ref.filePath); // mark AFTER finding a valid node
+                incomingRows.push({
+                    relType: 'CALLS', uid: '', name: enclosing.name, filePath: ref.filePath,
+                    kind: enclosing.label, startLine: ref.line, reason: 'refs-index',
+                });
+                refsAdded++;
+            }
+            if (process.env['CODE_MAPPER_VERBOSE'])
+                console.error(`Code Mapper: refs supplement for '${sym.name}': ${refsAdded} added from ${refCallers.length} refs`);
+        }
+        catch (err) {
+            console.error(`Code Mapper: refs supplement failed: ${err instanceof Error ? err.message : err}`);
+        }
         // Outgoing refs — exclude generic method names that produce false positives at low confidence
         const GENERIC_NAMES_EXCLUDE = new Set(['has', 'get', 'set', 'add', 'remove', 'delete', 'close', 'stop', 'clear', 'reset', 'toString', 'valueOf', 'push', 'pop', 'entries', 'keys', 'values']);
         let outgoingRows = [];
@@ -2095,10 +2545,44 @@ export class LocalBackend {
                 logQueryError('rename:read-ref', e);
             }
         }
-        // Step 3: Text search for refs the graph might have missed
-        let astSearchEdits = 0;
+        // Step 3a: Refs table lookup (instant, covers most cases the graph missed)
+        let refsEdits = 0;
         const graphFiles = new Set([sym.filePath, ...allIncoming.map(r => r.filePath)].filter(Boolean));
-        // Simple text search across the repo for the old name (in files not already covered by graph)
+        try {
+            const refsDb = this.getDb(repo.id);
+            const refsForName = findRefsBySymbol(refsDb, oldName, 500);
+            for (const ref of refsForName) {
+                const normalizedFile = ref.filePath.replace(/\\/g, '/');
+                if (graphFiles.has(normalizedFile))
+                    continue;
+                graphFiles.add(normalizedFile); // mark so ripgrep doesn't re-process
+                try {
+                    const content = await fs.readFile(assertSafePath(normalizedFile), 'utf-8');
+                    const lines = content.split('\n');
+                    const regex = new RegExp(`\\b${oldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+                    for (let i = 0; i < lines.length; i++) {
+                        const searchLine = lines[i];
+                        if (!searchLine)
+                            continue;
+                        regex.lastIndex = 0;
+                        if (regex.test(searchLine)) {
+                            regex.lastIndex = 0;
+                            addEdit(normalizedFile, i + 1, searchLine.trim(), searchLine.replace(regex, new_name).trim(), 'refs');
+                            refsEdits++;
+                        }
+                    }
+                }
+                catch (e) {
+                    logQueryError('rename:refs-read', e);
+                }
+            }
+        }
+        catch (e) {
+            logQueryError('rename:refs', e);
+        }
+        // Step 3b: Ripgrep text search for anything refs + graph missed
+        let astSearchEdits = 0;
+        // Simple text search across the repo for the old name (in files not already covered)
         try {
             const { execFileSync } = await import('child_process');
             const rgArgs = [
@@ -2163,9 +2647,11 @@ export class LocalBackend {
             files_affected: allChanges.length,
             total_edits: totalEdits,
             graph_edits: graphEdits,
+            refs_edits: refsEdits,
             text_search_edits: astSearchEdits,
             changes: allChanges,
             applied: !dry_run,
+            _note: 'Rename uses graph edges + refs index + ripgrep. Always review changes before applying. String literals, comments, and dynamic references (e.g. obj[methodName]) need manual review.',
         };
     }
     async impact(repo, params) {
@@ -2242,6 +2728,32 @@ export class LocalBackend {
                 }
             }
         }
+        // Supplement d=1 callers from refs table (catches callers the graph missed)
+        if (direction === 'upstream') {
+            try {
+                const targetName = sym.name;
+                const d1FromRefs = findRefsBySymbol(db, targetName, 200);
+                for (const ref of d1FromRefs) {
+                    if (ref.filePath === sym.filePath)
+                        continue;
+                    const refNode = this.findNodeAtPosition(db, ref.filePath, ref.line);
+                    if (refNode && !seenIds.has(refNode.name + ':' + ref.filePath)) {
+                        // Find the actual node ID for this position
+                        const fullNodes = findNodesByFile(db, ref.filePath);
+                        const match = fullNodes.find(n => n.name === refNode.name && n.startLine != null && n.startLine <= ref.line + 1 && (n.endLine ?? 9999) >= ref.line + 1);
+                        if (match && !seenIds.has(match.id) && !startIds.some(s => s === match.id)) {
+                            seenIds.add(match.id);
+                            mergedNodes.push({
+                                id: match.id, name: match.name, label: match.label,
+                                filePath: match.filePath, depth: 1,
+                                relationType: 'CALLS', confidence: 0.8,
+                            });
+                        }
+                    }
+                }
+            }
+            catch { /* refs table may not exist */ }
+        }
         const impacted = mergedNodes;
         const truncated = anyTruncated;
         const grouped = {};