knodin 0.5.1 → 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";
@@ -796,7 +799,7 @@ const FLOW_MAX_ENTRIES = 200;
 const flowsCache = new Map();
 const fileToFlowLookupCache = new Map();
 const FILE_TO_FLOW_LOOKUP_CACHE_LIMIT = 8;
-// R18: opt-in ANN (RECKON_ANN=1). An in-memory HNSW index over a repo's
+// R18: opt-in ANN (KNODIN_ANN=1). An in-memory HNSW index over a repo's
 // embeddings, built lazily on first ANN query and cached per repo + invalidated
 // by indexGeneration exactly like mapCache/flowsCache — so a reindex rebuilds it
 // and close() drops it. Holds NO stored state (no schema bump, nothing to
@@ -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 = [];
@@ -4814,7 +4884,7 @@ export function parseSimpleNameFromUniqueId(uniqueId) {
 export async function indexDbtManifestFile(content, _absolutePath, relativePath, repoPath, db) {
     try {
         const manifest = JSON.parse(content);
-        const dbtDir = path.join(repoPath, ".reckon/dbt");
+        const dbtDir = path.join(repoPath, ".knodin/dbt");
         await fs.promises.mkdir(dbtDir, { recursive: true });
         const assets = [];
         // 1. Process nodes (models, seeds, tests)
@@ -4951,9 +5021,9 @@ export async function indexDbtManifestFile(content, _absolutePath, relativePath,
         db.run("BEGIN TRANSACTION;");
         try {
             // Clear out any previous records associated with this dbt manifest or virtual paths
-            deleteSymbolsMatchingPath(db, ".reckon/dbt/%");
-            db.run("DELETE FROM \"references\" WHERE callerFile LIKE '.reckon/dbt/%'");
-            db.run("DELETE FROM dependencies WHERE fromFile LIKE '.reckon/dbt/%'");
+            deleteSymbolsMatchingPath(db, ".knodin/dbt/%");
+            db.run("DELETE FROM \"references\" WHERE callerFile LIKE '.knodin/dbt/%'");
+            db.run("DELETE FROM dependencies WHERE fromFile LIKE '.knodin/dbt/%'");
             deleteSymbolsForFile(db, relativePath);
             db.run('DELETE FROM "references" WHERE callerFile = ?', [relativePath]);
             db.run("DELETE FROM dependencies WHERE fromFile = ?", [relativePath]);
@@ -4971,7 +5041,7 @@ export async function indexDbtManifestFile(content, _absolutePath, relativePath,
 			`);
             for (const asset of assets) {
                 const safeId = asset.unique_id.replace(/[/\\]/g, "_");
-                const virtualFilePath = `.reckon/dbt/${safeId}.sql`;
+                const virtualFilePath = `.knodin/dbt/${safeId}.sql`;
                 const absVirtualPath = path.join(repoPath, virtualFilePath);
                 let code = asset.sqlCode;
                 if (!code) {
@@ -4990,7 +5060,7 @@ export async function indexDbtManifestFile(content, _absolutePath, relativePath,
                 for (const depId of asset.depends_on_nodes) {
                     const depAsset = assetMap.get(depId);
                     const safeDepId = depId.replace(/[/\\]/g, "_");
-                    const depVirtualFilePath = `.reckon/dbt/${safeDepId}.sql`;
+                    const depVirtualFilePath = `.knodin/dbt/${safeDepId}.sql`;
                     insertDep.run(virtualFilePath, depVirtualFilePath, "dbt-lineage");
                     const depSimpleName = depAsset ? depAsset.name : parseSimpleNameFromUniqueId(depId);
                     insertRef.run(asset.name, virtualFilePath, depSimpleName, depVirtualFilePath, 1, 1);
@@ -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");
@@ -5247,7 +5318,7 @@ const MAX_EMBEDDING_BATCH_SIZE = 32;
 // every symbol without turning source preparation into an unbounded memory sink.
 const EMBEDDING_SOURCE_CACHE_MAX_BYTES = 64 * 1024 * 1024;
 function embeddingBatchSize() {
-    const raw = process.env.RECKON_EMBEDDING_BATCH_SIZE;
+    const raw = process.env.KNODIN_EMBEDDING_BATCH_SIZE;
     if (raw === undefined)
         return DEFAULT_EMBEDDING_BATCH_SIZE;
     const parsed = Number(raw);
@@ -5829,11 +5900,11 @@ const WATCHED_FRESHNESS_LEASE_MS = 60_000;
 const FRESHNESS_FALLBACK_FILE_BOUND = 50000;
 /**
  * The non-git fallback's file bound, overridable with
- * `RECKON_FRESHNESS_FILE_BOUND` for repos where even a stat sweep of the
+ * `KNODIN_FRESHNESS_FILE_BOUND` for repos where even a stat sweep of the
  * indexed set is too much to pay per query.
  */
 function freshnessFallbackBound() {
-    const raw = process.env.RECKON_FRESHNESS_FILE_BOUND;
+    const raw = process.env.KNODIN_FRESHNESS_FILE_BOUND;
     if (raw !== undefined) {
         const parsed = Number.parseInt(raw, 10);
         if (Number.isFinite(parsed) && parsed >= 0)
@@ -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) {
@@ -6336,9 +6416,9 @@ async function getOrInitDb(repoPath, options = {}) {
                 dbPath = ":memory:";
             }
             else {
-                const knodinDir = path.join(normalizedPath, ".reckon");
+                const knodinDir = path.join(normalizedPath, ".knodin");
                 await fs.promises.mkdir(knodinDir, { recursive: true });
-                // Ensure .reckon is in .gitignore
+                // Ensure .knodin is in .gitignore
                 try {
                     const gitignorePath = path.join(normalizedPath, ".gitignore");
                     let gitignoreContent = "";
@@ -6346,11 +6426,11 @@ async function getOrInitDb(repoPath, options = {}) {
                         gitignoreContent = await fs.promises.readFile(gitignorePath, "utf-8");
                     }
                     const lines = gitignoreContent.split("\n").map((l) => l.trim());
-                    if (!lines.includes(".reckon") &&
-                        !lines.includes(".reckon/") &&
-                        !lines.includes("/.reckon")) {
+                    if (!lines.includes(".knodin") &&
+                        !lines.includes(".knodin/") &&
+                        !lines.includes("/.knodin")) {
                         const prefix = gitignoreContent.length > 0 && !gitignoreContent.endsWith("\n") ? "\n" : "";
-                        await fs.promises.appendFile(gitignorePath, `${prefix}\n# knodin\n.reckon\n`);
+                        await fs.promises.appendFile(gitignorePath, `${prefix}\n# knodin\n.knodin\n`);
                     }
                 }
                 catch (e) {
@@ -6401,7 +6481,7 @@ async function getOrInitDb(repoPath, options = {}) {
             // an unknown response shape, preserving C9's precision-first rule. v21
             // adds source-only LWR/Experience Bundle topology and must revisit its
             // newly indexable JSON files.
-            const RECKON_SCHEMA_VERSION = 21;
+            const KNODIN_SCHEMA_VERSION = 21;
             // Highest version whose upgrade needs the stored data REBUILT. Versions
             // above it migrate in place, so an upgrade costs a DELETE rather than a
             // full re-index + re-embed (~40 min of CPU on an 18k-symbol corpus).
@@ -6411,7 +6491,7 @@ async function getOrInitDb(repoPath, options = {}) {
             const needsMcpBackfill = storedVersion < 17;
             // v13 -> v14 purges embeddings orphaned while the FK cascade was inert.
             // Runs after the CREATE TABLEs below, since the table must exist.
-            const needsOrphanPurge = storedVersion < RECKON_SCHEMA_VERSION;
+            const needsOrphanPurge = storedVersion < KNODIN_SCHEMA_VERSION;
             if (storedVersion < LAST_REBUILD_SCHEMA_VERSION) {
                 db.run("DROP TRIGGER IF EXISTS after_symbol_insert;");
                 db.run("DROP TRIGGER IF EXISTS after_symbol_delete;");
@@ -6426,8 +6506,8 @@ async function getOrInitDb(repoPath, options = {}) {
                 db.run("DROP TABLE IF EXISTS mcp_tools;");
                 db.run("DROP TABLE IF EXISTS api_contracts;");
             }
-            if (storedVersion < RECKON_SCHEMA_VERSION) {
-                db.run(`PRAGMA user_version = ${RECKON_SCHEMA_VERSION};`);
+            if (storedVersion < KNODIN_SCHEMA_VERSION) {
+                db.run(`PRAGMA user_version = ${KNODIN_SCHEMA_VERSION};`);
             }
             db.run(`
 				CREATE TABLE IF NOT EXISTS symbols (
@@ -6712,15 +6792,15 @@ async function getFederatedRepos(repoPath) {
     const repos = [resolvedRepoPath];
     // Federation is EXPLICIT by default: a repo is treated as standalone unless it
     // is told otherwise, so results never silently depend on what else happens to
-    // live next to it. Two opt-in signals, read from `.reckon/federation.json`
+    // live next to it. Two opt-in signals, read from `.knodin/federation.json`
     // ({ "repos"?: string[], "autoDiscover"?: boolean }):
     //   • repos        — sibling paths (relative to this repo) to federate to.
     //   • autoDiscover — scan the parent directory for already-indexed siblings.
-    // autoDiscover can also be forced with RECKON_AUTO_FEDERATE=1. Without either
+    // autoDiscover can also be forced with KNODIN_AUTO_FEDERATE=1. Without either
     // signal, knodin federates to exactly the repos listed in `repos` (possibly
     // none) and nothing else.
-    let autoDiscover = process.env.RECKON_AUTO_FEDERATE === "1" || process.env.RECKON_AUTO_FEDERATE === "true";
-    const configPath = path.join(resolvedRepoPath, ".reckon/federation.json");
+    let autoDiscover = process.env.KNODIN_AUTO_FEDERATE === "1" || process.env.KNODIN_AUTO_FEDERATE === "true";
+    const configPath = path.join(resolvedRepoPath, ".knodin/federation.json");
     if (fs.existsSync(configPath)) {
         try {
             const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
@@ -6744,7 +6824,7 @@ async function getFederatedRepos(repoPath) {
         return repos;
     }
     // Auto-discovery (opt-in): siblings in the parent directory that knodin has
-    // already indexed (i.e. have a .reckon/db.sqlite). Under test the DB is
+    // already indexed (i.e. have a .knodin/db.sqlite). Under test the DB is
     // in-memory, so no repo has that on-disk marker; it would only ever match
     // repos a *production* run indexed elsewhere on the machine, so test
     // federation is driven purely by in-process `dbInstances` — skip the disk
@@ -6761,7 +6841,7 @@ async function getFederatedRepos(repoPath) {
                 if (siblingPath === resolvedRepoPath)
                     continue;
                 const isAlreadyIndexed = dbInstances.has(path.resolve(siblingPath)) ||
-                    (!isTest && fs.existsSync(path.join(siblingPath, ".reckon", "db.sqlite")));
+                    (!isTest && fs.existsSync(path.join(siblingPath, ".knodin", "db.sqlite")));
                 if (isAlreadyIndexed) {
                     repos.push(siblingPath);
                 }
@@ -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;
@@ -8643,7 +8731,7 @@ function renderCommunityPage(community, map) {
     lines.push("");
     return lines.join("\n");
 }
-/** Renders `.reckon/wiki/index.md`: repo path, community table, one link per page. */
+/** Renders `.knodin/wiki/index.md`: repo path, community table, one link per page. */
 function renderWikiIndex(resolvedRepoPath, map, slugs) {
     const lines = [];
     lines.push("# knodin Wiki", "");
@@ -8681,14 +8769,14 @@ function writeWikiPageIfChanged(dirPath, relFile, content, force, written, skipp
     written.push(relFile);
 }
 /**
- * Generates the graph wiki (R5): `.reckon/wiki/index.md` + one page per
+ * Generates the graph wiki (R5): `.knodin/wiki/index.md` + one page per
  * `map()` community. Reuses `engine.map(, "standard")` for community/hub/bridge/edge
  * data — no community-detection logic is duplicated here.
  */
 async function writeWiki(engine, repoPath, force) {
     const resolvedRepoPath = path.resolve(repoPath);
     const map = await engine.map(repoPath, "standard");
-    const wikiDir = path.join(resolvedRepoPath, ".reckon", "wiki");
+    const wikiDir = path.join(resolvedRepoPath, ".knodin", "wiki");
     fs.mkdirSync(wikiDir, { recursive: true });
     // Slugify community names into unique page filenames (lowercase, hyphenated).
     const slugs = new Map();
@@ -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,
@@ -9651,7 +9777,7 @@ export function createEngine() {
             // repair and timestamp drift before reporting it. Reuse an active DB in
             // long-lived processes, or open the existing local DB read-only.
             const activeDb = dbInstances.get(resolved);
-            const diskDbPath = path.join(resolved, ".reckon", "db.sqlite");
+            const diskDbPath = path.join(resolved, ".knodin", "db.sqlite");
             const db = activeDb ??
                 (fs.existsSync(diskDbPath) ? new Database(diskDbPath, { readonly: true }) : null);
             const verifiedAt = new Date().toISOString();
@@ -10057,7 +10183,7 @@ export function createEngine() {
                 // Repair partial current-schema databases before normal initialization,
                 // whose reconciliation queries require these columns. ALTER preserves all
                 // healthy index_state rows; the reconciler then refreshes their snapshots.
-                const diskDbPath = path.join(resolved, ".reckon", "db.sqlite");
+                const diskDbPath = path.join(resolved, ".knodin", "db.sqlite");
                 if (fs.existsSync(diskDbPath)) {
                     const activeDb = dbInstances.get(resolved);
                     const schemaDb = activeDb ?? new Database(diskDbPath);
@@ -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;
@@ -10551,7 +10921,7 @@ export function createEngine() {
                 // full-corpus graph. Keep the opt-in ANN path for unfiltered searches;
                 // filtered requests use the exact default over only eligible rows.
                 if (ann.annEnabled() && !hasFilters) {
-                    // R18 OPT-IN ANN PATH (RECKON_ANN=1). Build/reuse an in-memory HNSW for
+                    // R18 OPT-IN ANN PATH (KNODIN_ANN=1). Build/reuse an in-memory HNSW for
                     // this repo and query it instead of computing cosine over every row. The
                     // exact scan below stays the DEFAULT at every corpus size; this path only
                     // engages behind the env flag, until a measured >=95% top-10 recall gate
@@ -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 = {}) {
@@ -12933,7 +13280,7 @@ export function createEngine() {
             for (const rel of wouldChange) {
                 const abs = path.resolve(resolvedRepoPath, rel);
                 const content = newContents.get(rel);
-                const tmp = path.join(path.dirname(abs), `.${path.basename(abs)}.reckon-rename-${process.pid}-${Date.now()}.tmp`);
+                const tmp = path.join(path.dirname(abs), `.${path.basename(abs)}.knodin-rename-${process.pid}-${Date.now()}.tmp`);
                 fs.writeFileSync(tmp, content, "utf-8");
                 fs.renameSync(tmp, abs);
             }
@@ -13018,7 +13365,7 @@ export function createEngine() {
             statusCache.clear();
             flowsCache.clear();
             fileToFlowLookupCache.clear();
-            gitChurnCache.clear();
+            clearGitHistorySignalCache();
             annIndexCache.clear();
             searchMetadataCache.clear();
             searchCommunityLookupCache.clear();