knodin 0.6.0 → 0.7.3

package/dist/src/engine/index.js

@@ -20,12 +20,15 @@ import chokidar from "chokidar";
 import Parser from "web-tree-sitter";
 import { readIndexActivity } from "../index-activity.js";
 import { runReadOnlyLspQuery } from "../lsp-readonly.js";
+import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snapshot.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
+import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
 import { beginPerfPhase, measurePerfPhase, measurePerfPhaseSync } from "./perf.js";
 import { isIndexablePath, makeWatchIgnorePredicate } from "./prune.js";
+import { readScipIndex, SCIP_DEFAULT_LIMITS, } from "./scip-import.js";
 import { isIndexableSourcePath } from "./source-policy.js";
 import { Database } from "./sqlite.js";
 import { deleteAllSymbols, deleteSymbolsForFile, deleteSymbolsMatchingPath, ORPHANED_EMBEDDING_PREDICATE, purgeOrphanEmbeddings, } from "./symbol-delete.js";
@@ -3900,6 +3903,73 @@ async function indexLsifDump(absolutePath, _relativePath, repoPath, db) {
         console.error("Error indexing LSIF:", error);
     }
 }
+/** Replace only the optional SCIP tier, preserving native and LSIF facts verbatim. */
+function persistScipFacts(db, repoPath, facts) {
+    const affectedFiles = [...new Set(facts.symbols.map((symbol) => symbol.filePath))].sort();
+    const insertSymbol = db.prepare(`
+		INSERT INTO symbols (name, kind, filePath, startLine, endLine, startCol, endCol, summary)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+	`);
+    const insertReference = db.prepare(`
+		INSERT INTO "references" (callerSymbol, callerFile, calleeSymbol, calleeFile, line, column, kind, confidence)
+		VALUES (?, ?, ?, ?, ?, ?, ?, 1.0)
+	`);
+    const insertDependency = db.prepare(`
+		INSERT INTO dependencies (fromFile, toFile, kind, confidence, sourceEvidence)
+		VALUES (?, ?, 'scip_import', 1.0, ?)
+	`);
+    db.run("BEGIN TRANSACTION;");
+    try {
+        db.run("DELETE FROM symbols WHERE kind LIKE 'SCIP_%'");
+        db.run("DELETE FROM \"references\" WHERE kind LIKE 'scip_%'");
+        db.run("DELETE FROM dependencies WHERE kind = 'scip_import'");
+        for (const symbol of facts.symbols) {
+            insertSymbol.run(symbol.name, symbol.kind, symbol.filePath, symbol.startLine, symbol.endLine, symbol.startCol, symbol.endCol, JSON.stringify({ provenance: "scip", symbol: symbol.symbol }));
+        }
+        const dependencies = new Set();
+        for (const reference of facts.references) {
+            insertReference.run(reference.callerSymbol, reference.callerFile, reference.calleeSymbol, reference.calleeFile, reference.line, reference.column, reference.kind);
+            if (reference.kind === "scip_reference" && reference.callerFile !== reference.calleeFile) {
+                const key = `${reference.callerFile}\0${reference.calleeFile}`;
+                if (!dependencies.has(key)) {
+                    dependencies.add(key);
+                    insertDependency.run(reference.callerFile, reference.calleeFile, JSON.stringify({ provenance: "scip", input: facts.inputPath }));
+                }
+            }
+        }
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
+    }
+    finally {
+        insertSymbol.finalize();
+        insertReference.finalize();
+        insertDependency.finalize();
+    }
+    persistSymbolIdentities(db, repoPath, affectedFiles);
+    return affectedFiles;
+}
+/** Any source refresh makes the previous compiler snapshot stale as a unit. */
+function invalidateScipFacts(db) {
+    const present = db
+        .query("SELECT 1 AS present FROM symbols WHERE kind LIKE 'SCIP_%' LIMIT 1")
+        .get();
+    if (!present)
+        return;
+    db.run("BEGIN TRANSACTION;");
+    try {
+        db.run("DELETE FROM symbols WHERE kind LIKE 'SCIP_%'");
+        db.run("DELETE FROM \"references\" WHERE kind LIKE 'scip_%'");
+        db.run("DELETE FROM dependencies WHERE kind = 'scip_import'");
+        db.run("COMMIT;");
+    }
+    catch (error) {
+        db.run("ROLLBACK;");
+        throw error;
+    }
+}
 async function indexTerraformFile(content, relativePath, _repoPath, db) {
     const symbols = [];
     const references = [];
@@ -5014,6 +5084,7 @@ export async function indexDbtManifestFile(content, _absolutePath, relativePath,
 /** Index a single file's symbols and references into the SQLite database. */
 async function indexFile(absolutePath, relativePath, repoPath, db) {
     try {
+        invalidateScipFacts(db);
         const baseName = path.basename(absolutePath).toLowerCase();
         if (baseName === "manifest.json") {
             const content = fs.readFileSync(absolutePath, "utf-8");
@@ -6112,7 +6183,16 @@ function noteFreshness(repoPath, staleness) {
 async function ensureIndexFresh(repoPath, db) {
     const key = path.resolve(repoPath);
     const cached = freshnessProbes.get(key);
-    const lease = watchQueues.get(key)?.ready ? WATCHED_FRESHNESS_LEASE_MS : FRESHNESS_PROBE_TTL_MS;
+    // A watcher cannot prove that an edit made immediately before this call has
+    // already reached its event queue. Git worktrees therefore take the bounded
+    // porcelain proof on every answer. The long watcher lease remains safe for
+    // non-Git directories, where the watcher is the only new-file signal.
+    const gitBacked = fs.existsSync(path.join(key, ".git"));
+    const lease = gitBacked
+        ? 0
+        : watchQueues.get(key)?.ready
+            ? WATCHED_FRESHNESS_LEASE_MS
+            : FRESHNESS_PROBE_TTL_MS;
     const head = lease === WATCHED_FRESHNESS_LEASE_MS ? readGitHeadFast(key) : null;
     const headUnchanged = head === null || (head !== undefined && head === getMeta(db, "lastIndexedHead"));
     if (cached && Date.now() - cached.at < lease && headUnchanged) {
@@ -6949,6 +7029,41 @@ function queryFileSymbols(db, filePath, repoPath) {
         };
     });
 }
+function publishStructuralSnapshot(repoPath, db) {
+    const indexed = db
+        .query("SELECT filePath FROM index_state ORDER BY filePath")
+        .all();
+    const files = [];
+    for (const { filePath } of indexed) {
+        const absolute = path.resolve(repoPath, filePath);
+        try {
+            const content = fs.readFileSync(absolute);
+            const stat = fs.statSync(absolute);
+            files.push({
+                path: filePath,
+                sizeBytes: content.byteLength,
+                mtimeMs: stat.mtimeMs,
+                contentFingerprint: contentFingerprint(content),
+                symbols: queryFileSymbols(db, filePath, repoPath).map((row) => ({
+                    identity: row.identity ?? null,
+                    symbol: row.symbol ?? "",
+                    kind: row.kind ?? "unknown",
+                    line: row.line ?? 1,
+                    endLine: row.endLine ?? row.line ?? 1,
+                    ...(row.signature ? { signature: row.signature } : {}),
+                    ...(row.visibility ? { visibility: row.visibility } : {}),
+                    ...(row.exported !== undefined ? { exported: row.exported } : {}),
+                    ...(row.parent ? { parent: row.parent } : {}),
+                    evidenceQuality: row.evidenceQuality ?? "parser-grounded",
+                })),
+            });
+        }
+        catch {
+            // Health/freshness reports missing files; snapshots never invent an entry.
+        }
+    }
+    writeStructuralSnapshot(repoPath, files);
+}
 /**
  * Name-level call adjacency from the `references` table — the single SQL +
  * Map-building shared by `shortest_path` (directed) and `traverse` (undirected),
@@ -7643,43 +7758,16 @@ export function calculateASTComplexity(node) {
     traverse(node);
     return score;
 }
-const gitChurnCache = new Map();
-const GIT_CHURN_CACHE_LIMIT = 8;
 /**
  * Count commits touching requested files with the legacy path-specific Git
  * semantics. Results are cached by resolved repository + HEAD, so warm review
  * launches no per-file history processes while preserving existing risk scores.
  */
 export function getGitChurns(filePaths, repoPath) {
-    const resolvedRepoPath = path.resolve(repoPath);
     const requested = [...new Set(filePaths.map((file) => safeReviewFile(file)))];
-    let head = "unborn";
-    try {
-        head = runGit(resolvedRepoPath, ["rev-parse", "--verify", "HEAD"]).trim();
-    }
-    catch {
-        // An unborn repository has no history, so every requested file has zero churn.
-    }
-    const cacheKey = `${resolvedRepoPath}\0${head}`;
-    let counts = gitChurnCache.get(cacheKey);
-    if (!counts) {
-        counts = new Map();
-        setBoundedCache(gitChurnCache, cacheKey, counts, GIT_CHURN_CACHE_LIMIT);
-    }
-    if (head !== "unborn") {
-        for (const file of requested) {
-            if (counts.has(file))
-                continue;
-            try {
-                const output = runGit(resolvedRepoPath, ["log", "--oneline", "--", file]).trim();
-                counts.set(file, output ? output.split("\n").length : 0);
-            }
-            catch {
-                counts.set(file, 0);
-            }
-        }
-    }
-    return new Map(requested.map((file) => [file, counts?.get(file) ?? 0]));
+    const history = collectGitHistorySignals(repoPath, requested);
+    const counts = new Map(history.churn.map((fact) => [fact.file, fact.commitCount]));
+    return new Map(requested.map((file) => [file, counts.get(file) ?? 0]));
 }
 export function getGitChurn(filePath, repoPath) {
     return getGitChurns([filePath], repoPath).get(safeReviewFile(filePath)) ?? 0;
@@ -9097,10 +9185,12 @@ export function createEngine() {
                     changedFiles: reviewChangedFiles(base, repoPath, options, modifiedFiles),
                 };
             });
-            const churnByFile = measurePerfPhaseSync("review_churn", () => getGitChurns(changedFiles, repoPath));
+            const historySignals = measurePerfPhaseSync("review_churn", () => collectGitHistorySignals(repoPath, changedFiles, options.historyLimits));
+            const churnByFile = new Map(historySignals.churn.map((fact) => [fact.file, fact.commitCount]));
             const changedSymbols = new Set();
             const testGaps = new Set();
             const symbolRisks = [];
+            const structuralCentrality = new Map();
             const finishParsing = beginPerfPhase("review_parsing");
             try {
                 for (const filePath of changedFiles) {
@@ -9143,6 +9233,19 @@ export function createEngine() {
                             Array.from(lineSet).some((line) => line >= sym.startLine && line <= sym.endLine);
                         if (isChanged) {
                             changedSymbols.add(sym.name);
+                            const inboundReferences = db
+                                .query('SELECT COUNT(*) AS count FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL)')
+                                .get(sym.name, filePath)?.count ?? 0;
+                            const outboundReferences = db
+                                .query('SELECT COUNT(*) AS count FROM "references" WHERE callerSymbol = ? AND callerFile = ?')
+                                .get(sym.name, filePath)?.count ?? 0;
+                            structuralCentrality.set(`${filePath}\0${sym.name}`, {
+                                symbol: sym.name,
+                                file: filePath,
+                                inboundReferences,
+                                outboundReferences,
+                                totalReferences: inboundReferences + outboundReferences,
+                            });
                             let complexity = 1;
                             if (tree) {
                                 try {
@@ -9214,11 +9317,18 @@ export function createEngine() {
             const unmappedChangedFiles = changedFiles.filter((file) => !mappedSet.has(file));
             const flowsList = Array.from(affectedFlowsSet);
             const gapsList = Array.from(testGaps);
+            const centralityFacts = [...structuralCentrality.values()].sort((a, b) => b.totalReferences - a.totalReferences ||
+                a.file.localeCompare(b.file) ||
+                a.symbol.localeCompare(b.symbol));
             // Minimal detail caps each list so a client LLM isn't handed the full
             // (potentially very large) result; the *Count fields always report the
             // true totals so nothing is silently hidden.
             const MINIMAL_CAP = 25;
             const minimal = detailLevel === "minimal";
+            const signalFiles = minimal ? changedFiles.slice(0, MINIMAL_CAP) : changedFiles;
+            const signalFlows = minimal ? flowsList.slice(0, MINIMAL_CAP) : flowsList;
+            const signalGaps = minimal ? gapsList.slice(0, MINIMAL_CAP) : gapsList;
+            const signalCentrality = minimal ? centralityFacts.slice(0, MINIMAL_CAP) : centralityFacts;
             const truncated = minimal &&
                 (changedFiles.length > MINIMAL_CAP ||
                     mappedChangedFiles.length > MINIMAL_CAP ||
@@ -9238,6 +9348,22 @@ export function createEngine() {
                     : unmappedChangedFiles,
                 unmappedChangedFileCount: unmappedChangedFiles.length,
                 riskScore,
+                signals: {
+                    graphImpact: {
+                        affectedFlows: signalFlows,
+                        changedFiles: signalFiles,
+                        confidence: "exact-indexed-relationships",
+                    },
+                    testGaps: {
+                        facts: signalGaps,
+                        confidence: "indexed-references-and-test-paths",
+                    },
+                    structuralCentrality: {
+                        facts: signalCentrality,
+                        confidence: "exact-indexed-references",
+                    },
+                    history: historySignals,
+                },
                 changedSymbols: minimal ? changedList.slice(0, MINIMAL_CAP) : changedList,
                 changedSymbolCount: changedList.length,
                 affectedFlows: minimal ? flowsList.slice(0, MINIMAL_CAP) : flowsList,
@@ -10311,6 +10437,7 @@ export function createEngine() {
         async index(repoPath, files, clean = false, options) {
             const indexed = [];
             const unchanged = [];
+            let scipReport;
             const progress = createIndexProgressReporter(options?.onProgress);
             progress("starting", 0, "Opening local graph database");
             const db = await getOrInitDb(repoPath, {
@@ -10396,6 +10523,33 @@ export function createEngine() {
                 indexed.push(...collectRepoFiles(repoPath));
                 completionMessage = `${indexed.length.toLocaleString()} repository file(s) are current`;
             }
+            if (options?.scip) {
+                const facts = readScipIndex(repoPath, options.scip);
+                const affectedFiles = persistScipFacts(db, repoPath, facts);
+                progress("finalizing", 0, "Refreshing SCIP identities and semantic embeddings");
+                await indexEmbeddings(db, repoPath, progress);
+                indexGeneration++;
+                const bounds = { ...SCIP_DEFAULT_LIMITS, ...options.scip };
+                scipReport = {
+                    provenance: "scip",
+                    inputPath: facts.inputPath,
+                    bytes: facts.bytes,
+                    files: facts.files,
+                    facts: facts.facts,
+                    languages: facts.languages,
+                    indexers: facts.indexers,
+                    elapsedMs: facts.elapsedMs,
+                    bounds: {
+                        maxBytes: bounds.maxBytes,
+                        maxFiles: bounds.maxFiles,
+                        maxFacts: bounds.maxFacts,
+                        timeoutMs: bounds.timeoutMs,
+                    },
+                };
+                for (const file of affectedFiles)
+                    if (!indexed.includes(file))
+                        indexed.push(file);
+            }
             progress("verifying", 0, "Verifying local graph health", {
                 phaseTotal: 1,
             });
@@ -10431,6 +10585,10 @@ export function createEngine() {
                     recordFreshnessBaseline(repoPath, db);
                 }
                 noteFreshness(repoPath, "fresh");
+                // Test engines use an in-memory graph and must not create untracked
+                // repository artifacts that pollute Git-diff/review fixtures.
+                if (!process.env.VITEST && process.env.NODE_ENV !== "test")
+                    publishStructuralSnapshot(repoPath, db);
             }
             else {
                 freshnessProbes.delete(path.resolve(repoPath));
@@ -10445,6 +10603,7 @@ export function createEngine() {
             return {
                 indexed,
                 unchanged,
+                scip: scipReport,
                 verification: {
                     status: health.status,
                     issueCount,
@@ -10462,6 +10621,7 @@ export function createEngine() {
                 throw new Error("knodin search: invalid testScope");
             const repos = options.federate === false ? [resolvedRepoPath] : await getFederatedRepos(repoPath);
             const allRepos = await Promise.all(repos.map(async (r) => ({ path: r, db: await getOrInitDb(r) })));
+            const searchSnapshots = new Map(allRepos.map((repo) => [repo.path, getSearchMetadataSnapshot(repo.path, repo.db)]));
             // typeof + Number.isFinite rejects undefined/null/NaN alike, so any non-numeric
             // or unset `limit` falls back to the default instead of clamping to 0/1 or
             // propagating NaN into Array.prototype.slice (which silently empties results).
@@ -10503,12 +10663,90 @@ export function createEngine() {
                 return true;
             };
             const formatPath = makePathFormatter(resolvedRepoPath);
+            const retrievalMode = options.retrievalMode ?? "complete";
+            const normalize = (value) => value.toLocaleLowerCase().replace(/[^a-z0-9]/g, "");
+            const hydrateStructural = (matches) => {
+                const fileToCommunityMap = matches.length > 0
+                    ? getSearchCommunityLookup(allRepos, resolvedRepoPath)
+                    : new Map();
+                return matches.map(({ repo, row }) => {
+                    let source = "";
+                    if (options.includeSource !== false)
+                        source = getSourceRange(repo.path, row.filePath, row.startLine, row.endLine, 500);
+                    const callersStmt = repo.db.query(`
+						SELECT DISTINCT callerSymbol FROM "references"
+						WHERE calleeSymbol = ? AND callerSymbol IS NOT NULL AND callerSymbol != ?
+							AND (calleeFile = ? OR calleeFile IS NULL)
+					`);
+                    const directCallers = callersStmt
+                        .all(row.name, row.name, row.filePath)
+                        .map((caller) => caller.callerSymbol)
+                        .sort((a, b) => a.localeCompare(b));
+                    callersStmt.finalize();
+                    const formattedFile = formatPath(repo.path, row.filePath);
+                    return {
+                        identity: symbolIdentity(repo.path, row),
+                        symbol: row.name,
+                        kind: row.kind,
+                        filePath: formattedFile,
+                        similarity: 1,
+                        rrfScore: 1,
+                        source,
+                        belongsToCommunity: fileToCommunityMap.get(formattedFile) || "core-module",
+                        directCallers,
+                    };
+                });
+            };
+            const expandBounded = (seeds) => {
+                const expansionWorkLimit = Math.min(200, Math.max(candidateLimit * 4, 20));
+                const selected = seeds.slice(0, expansionWorkLimit);
+                const seen = new Set(selected.map(({ repo, row }) => `${repo.path}:${row.id}`));
+                let frontier = [...seeds];
+                for (let depth = 0; depth < 2 && frontier.length > 0 && selected.length < expansionWorkLimit; depth++) {
+                    const next = [];
+                    for (const current of frontier) {
+                        const refs = current.repo.db
+                            .query(`SELECT callerSymbol, callerFile, calleeSymbol, calleeFile FROM "references"
+								WHERE (callerSymbol = ? AND callerFile = ?)
+									OR (calleeSymbol = ? AND calleeFile = ?)
+								ORDER BY callerFile, callerSymbol, calleeFile, calleeSymbol
+								LIMIT 200`)
+                            .all(current.row.name, current.row.filePath, current.row.name, current.row.filePath);
+                        const snapshot = searchSnapshots.get(current.repo.path);
+                        for (const ref of refs) {
+                            const fromCaller = ref.callerSymbol === current.row.name && ref.callerFile === current.row.filePath;
+                            const neighborName = fromCaller ? ref.calleeSymbol : ref.callerSymbol;
+                            const neighborFile = fromCaller ? ref.calleeFile : ref.callerFile;
+                            if (!neighborName || !neighborFile)
+                                continue;
+                            for (const row of snapshot.rows) {
+                                if (row.name !== neighborName || !accepts(row))
+                                    continue;
+                                if (neighborFile && row.filePath !== neighborFile)
+                                    continue;
+                                const key = `${current.repo.path}:${row.id}`;
+                                if (seen.has(key))
+                                    continue;
+                                if (seen.size >= expansionWorkLimit)
+                                    break;
+                                seen.add(key);
+                                next.push({ repo: current.repo, row });
+                            }
+                        }
+                    }
+                    next.sort((a, b) => a.repo.path.localeCompare(b.repo.path) ||
+                        a.row.filePath.localeCompare(b.row.filePath) ||
+                        a.row.startLine - b.row.startLine);
+                    selected.push(...next.slice(0, expansionWorkLimit - selected.length));
+                    frontier = next;
+                }
+                return selected;
+            };
             if (options.structural) {
-                const normalize = (value) => value.toLocaleLowerCase().replace(/[^a-z0-9]/g, "");
                 const needle = normalize(query);
                 const matches = allRepos
-                    .flatMap((repo) => getSearchMetadataSnapshot(repo.path, repo.db)
-                    .rows.filter((row) => accepts(row) && normalize(row.name).includes(needle))
+                    .flatMap((repo) => searchSnapshots.get(repo.path).rows
+                    .filter((row) => accepts(row) && normalize(row.name).includes(needle))
                     .map((row) => ({ repo, row })))
                     .sort((left, right) => left.row.name.localeCompare(right.row.name) ||
                     left.row.filePath.localeCompare(right.row.filePath) ||
@@ -10532,8 +10770,140 @@ export function createEngine() {
                     offset,
                     limit: maxResults,
                     hasMore: offset + maxResults < matches.length,
+                    retrieval: { route: ["exact-name"], embeddingsUsed: false },
                 };
             }
+            if (retrievalMode !== "vector-only") {
+                const trimmedQuery = query.trim().replaceAll("\\", "/");
+                const normalizedQuery = normalize(trimmedQuery);
+                const identityQuery = trimmedQuery.startsWith("sym_") ? trimmedQuery : undefined;
+                const pathQuery = trimmedQuery.includes("/") || /\.[A-Za-z0-9]+$/.test(trimmedQuery);
+                const seedMatches = allRepos
+                    .flatMap((repo) => searchSnapshots.get(repo.path).rows
+                    .filter((row) => {
+                    if (!accepts(row))
+                        return false;
+                    if (identityQuery)
+                        return symbolIdentityMatches(symbolIdentity(repo.path, row), identityQuery);
+                    if (pathQuery) {
+                        const candidate = row.filePath.replaceAll("\\", "/");
+                        return candidate === trimmedQuery || candidate.endsWith(`/${trimmedQuery}`);
+                    }
+                    return normalizedQuery.length > 0 && normalize(row.name) === normalizedQuery;
+                })
+                    .map((row) => ({ repo, row })))
+                    .sort((a, b) => a.repo.path.localeCompare(b.repo.path) ||
+                    a.row.filePath.localeCompare(b.row.filePath) ||
+                    a.row.startLine - b.row.startLine);
+                if (seedMatches.length > 0) {
+                    const selected = retrievalMode === "complete" || retrievalMode === "bounded-graph"
+                        ? expandBounded(seedMatches)
+                        : seedMatches;
+                    const pageMatches = selected.slice(offset, offset + maxResults);
+                    return {
+                        results: hydrateStructural(pageMatches),
+                        total: selected.length,
+                        offset,
+                        limit: maxResults,
+                        hasMore: offset + maxResults < selected.length,
+                        retrieval: {
+                            route: retrievalMode === "complete" || retrievalMode === "bounded-graph"
+                                ? [
+                                    identityQuery ? "stable-identity" : pathQuery ? "exact-path" : "exact-name",
+                                    "bounded-graph",
+                                ]
+                                : [identityQuery ? "stable-identity" : pathQuery ? "exact-path" : "exact-name"],
+                            embeddingsUsed: false,
+                        },
+                    };
+                }
+            }
+            const lexicalRanks = new Map();
+            if (retrievalMode !== "vector-only") {
+                for (const repo of allRepos) {
+                    const snapshot = searchSnapshots.get(repo.path);
+                    const allowedIds = new Set(snapshot.rows.filter(accepts).map((row) => row.id));
+                    const tokens = query
+                        .replace(/[^\w\s]/g, " ")
+                        .trim()
+                        .split(/\s+/)
+                        .filter((word) => word.length >= 4)
+                        .map((word) => `"${word}"`);
+                    const runFts = (separator) => {
+                        if (tokens.length === 0)
+                            return [];
+                        try {
+                            const statement = repo.db.query(`
+								SELECT symbolId FROM symbols_fts
+								WHERE symbols_fts MATCH ?
+								ORDER BY bm25(symbols_fts), symbolId
+								LIMIT 100
+							`);
+                            const ids = statement
+                                .all(tokens.join(separator))
+                                .map(({ symbolId }) => symbolId)
+                                .filter((id) => allowedIds.has(id));
+                            statement.finalize();
+                            return ids;
+                        }
+                        catch (error) {
+                            console.error(`FTS query failed for "${query}":`, error);
+                            return [];
+                        }
+                    };
+                    const and = measurePerfPhaseSync("fts", () => runFts(" "));
+                    const or = tokens.length > 1 ? measurePerfPhaseSync("fts", () => runFts(" OR ")) : and;
+                    const lexicalSeeds = or
+                        .map((id) => snapshot.rowById.get(id))
+                        .filter((row) => row !== undefined)
+                        .map((row) => ({ repo, row }));
+                    const structural = expandBounded(lexicalSeeds)
+                        .filter(({ repo: matchRepo }) => matchRepo.path === repo.path)
+                        .map(({ row }) => row.id);
+                    const sufficientSeeds = and
+                        .map((id) => snapshot.rowById.get(id))
+                        .filter((row) => row !== undefined)
+                        .map((row) => ({ repo, row }));
+                    const sufficient = expandBounded(sufficientSeeds)
+                        .filter(({ repo: matchRepo }) => matchRepo.path === repo.path)
+                        .map(({ row }) => row.id);
+                    lexicalRanks.set(repo.path, { and, or, structural, sufficient });
+                }
+                const structurallySufficient = retrievalMode === "complete" &&
+                    !ann.annEnabled() &&
+                    [...lexicalRanks.values()].some((ranks) => ranks.and.length > 0);
+                if (retrievalMode === "lexical-only" ||
+                    retrievalMode === "bounded-graph" ||
+                    structurallySufficient) {
+                    const matches = allRepos.flatMap((repo) => {
+                        const snapshot = searchSnapshots.get(repo.path);
+                        const ranks = lexicalRanks.get(repo.path);
+                        const ids = structurallySufficient
+                            ? ranks?.sufficient
+                            : retrievalMode === "bounded-graph"
+                                ? ranks?.structural
+                                : ranks?.or;
+                        return (ids ?? [])
+                            .map((id) => snapshot.rowById.get(id))
+                            .filter((row) => row !== undefined)
+                            .map((row) => ({ repo, row }));
+                    });
+                    const pageMatches = matches.slice(offset, offset + maxResults);
+                    return {
+                        results: hydrateStructural(pageMatches),
+                        total: matches.length,
+                        offset,
+                        limit: maxResults,
+                        hasMore: offset + maxResults < matches.length,
+                        retrieval: {
+                            route: retrievalMode === "bounded-graph" || structurallySufficient
+                                ? ["lexical", "bounded-graph"]
+                                : ["lexical"],
+                            embeddingsUsed: false,
+                        },
+                    };
+                }
+            }
             // 1. Generate query embedding once
             const queryVec = await generateMeasuredEmbedding(query, true);
             const rankedCandidates = [];
@@ -10542,7 +10912,7 @@ export function createEngine() {
                 const db = repo.db;
                 // 2. Reuse decoded generation-scoped metadata. Cheap metadata-only
                 // filters run before any exact vector score is computed.
-                const snapshot = getSearchMetadataSnapshot(repo.path, db);
+                const snapshot = searchSnapshots.get(repo.path);
                 const allRows = snapshot.rows.filter(accepts);
                 const allowedIds = new Set(allRows.map((row) => row.id));
                 totalMatches += allowedIds.size;
@@ -10587,39 +10957,10 @@ export function createEngine() {
                 const sortedSemantics = semanticMatches.sort((a, b) => b.score - a.score);
                 const semanticScoresAreTied = sortedSemantics.length > 1 &&
                     sortedSemantics.every((item) => item.score === sortedSemantics[0]?.score);
-                // 3. FTS Fallback / Hybrid scoring
-                const ftsMatches = measurePerfPhaseSync("fts", () => {
-                    let matches = [];
-                    try {
-                        const cleanQuery = query.replace(/[^\w\s]/g, " ").trim();
-                        if (cleanQuery) {
-                            // Quote each token so FTS5 treats bare AND/OR/NOT/NEAR as literal search
-                            // words instead of query-syntax operators (which would otherwise throw
-                            // a MATCH syntax error for a query like "NOT authenticated").
-                            const ftsQuery = cleanQuery
-                                .split(/\s+/)
-                                .filter((word) => word.length >= 4)
-                                .map((word) => `"${word}"`)
-                                // With a useful semantic ordering, retain the precise all-token
-                                // FTS signal. When a deterministic/fallback embedder ties every
-                                // candidate, permit partial lexical matches so connective words
-                                // do not reduce ranking to arbitrary insertion order.
-                                .join(semanticScoresAreTied ? " OR " : " ");
-                            const ftsStmt = db.query(`
-							SELECT symbolId FROM symbols_fts WHERE symbols_fts MATCH ? ORDER BY bm25(symbols_fts) LIMIT 100
-						`);
-                            matches = ftsStmt
-                                .all(ftsQuery)
-                                .map((m) => m.symbolId)
-                                .filter((id) => allowedIds.has(id));
-                            ftsStmt.finalize();
-                        }
-                    }
-                    catch (err) {
-                        console.error(`FTS query failed for "${query}":`, err);
-                    }
-                    return matches;
-                });
+                // 3. Reuse the lexical and bounded-graph ranks computed before query inference.
+                const lexical = lexicalRanks.get(repo.path);
+                const baseLexical = semanticScoresAreTied ? lexical?.or : lexical?.and;
+                const ftsMatches = [...new Set(baseLexical ?? [])].filter((id) => allowedIds.has(id));
                 // Rank mappings for Reciprocal Rank Fusion (RRF)
                 const semanticRankMap = new Map();
                 const semanticById = new Map();
@@ -10708,6 +11049,12 @@ export function createEngine() {
                 offset,
                 limit: maxResults,
                 hasMore: offset + maxResults < total,
+                retrieval: {
+                    route: retrievalMode === "vector-only"
+                        ? ["embeddings"]
+                        : ["lexical", "bounded-graph", "embeddings"],
+                    embeddingsUsed: true,
+                },
             };
         },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector = {}, impactOptions = {}, options = {}) {
@@ -13018,7 +13365,7 @@ export function createEngine() {
             statusCache.clear();
             flowsCache.clear();
             fileToFlowLookupCache.clear();
-            gitChurnCache.clear();
+            clearGitHistorySignalCache();
             annIndexCache.clear();
             searchMetadataCache.clear();
             searchCommunityLookupCache.clear();