knodin 0.11.0 → 0.12.1

package/dist/src/engine/index.js

@@ -826,6 +826,97 @@ function freshnessMechanismFor(repoPath, policy) {
 // Bumped whenever any repo is (re)indexed, so cached community-detection results
 // below can be invalidated cheaply instead of recomputed on every call.
 export const KNODIN_SCHEMA_VERSION = 24;
+/**
+ * Reciprocal Rank Fusion's smoothing constant. Was written as a bare `60` at
+ * each use site; named so the ranking formula can be read and changed in one
+ * place. Adjacent ranks differ by roughly 0.00026 at this k, which is the unit
+ * every other ranking weight has to be reasoned about in.
+ */
+const RRF_K = 60;
+/**
+ * How hard graph centrality pulls on ranking, as a fraction of one full RRF
+ * component.
+ *
+ * Semantic similarity alone ranks a minutes-old duplicate above the
+ * implementation it duplicates: the duplicate is short and made almost entirely
+ * of the query's own words, while the canonical version is diluted by a real
+ * body. The searcher then reads their own new leaf as evidence that nothing
+ * existed (KNODIN-15). Community and degree data was already in the graph and
+ * already in the output; it simply was not weighted into ranking.
+ *
+ * 0.05 caps the boost at `0.05 / (RRF_K + 1)` ≈ 0.00082, about three rank
+ * positions. That is deliberately modest, because the opposite failure is
+ * equally real and lands on the same symbols: a *seam* is by definition a
+ * well-documented symbol with no callers, and those are already the hardest
+ * things to retrieve (KNODIN-28, KNODIN-30). A large centrality weight would
+ * bury them to fix this, trading one silent miss for another. So a connected
+ * implementation climbs past neighbours it is scoring near, and does not
+ * override a decisively stronger semantic match.
+ *
+ * Zero-in-degree symbols are excluded from the centrality ranking rather than
+ * ranked last, so an uncalled symbol is never *penalised* — it only forgoes a
+ * boost it has no evidence for.
+ */
+const CENTRALITY_RRF_WEIGHT = 0.05;
+/**
+ * The live ranking weights, exported so a benchmark can record which values
+ * produced its numbers.
+ *
+ * Comparing two ranking runs whose constants differed is not a measurement, and
+ * the difference is invisible unless the run writes them down. Reading them here
+ * rather than copying them into the benchmark keeps that record from going stale
+ * the first time someone tunes a weight.
+ */
+/**
+ * How hard a partial (OR) lexical match pulls, as a fraction of one full RRF
+ * component, and how many of them are considered.
+ *
+ * The weight buys a statable property: at 0.75 a top-ranked partial match
+ * contributes `0.75 / (RRF_K + 1)` ≈ 0.0123, which is enough to lift a symbol
+ * sitting around semantic rank 90 above an unsupported semantic rank 1. So
+ * lexical evidence can rescue a symbol the embedder under-ranked, and cannot
+ * resurrect one the embedder judged irrelevant. At 1.0 the loose channel becomes
+ * a full peer of semantic similarity and wins from arbitrarily deep, which is
+ * over-correction.
+ *
+ * The limit is a separate lever and conflating the two is how this gets
+ * mistuned. RRF has a floor — the hundredth partial match still scores
+ * `w / (RRF_K + 100)` — so an unbounded channel gives a meaningful shove to a
+ * hundred symbols at once on any query full of common words. Truncating raises
+ * the per-item floor slightly while applying it to under a third as many rows,
+ * which is the trade that actually reduces noise.
+ *
+ * Both are starting points measured against `benchmarks/evaluations/c103-prose-retrieval`,
+ * not settled constants. Re-run it before changing either.
+ */
+const LOOSE_LEXICAL_RRF_WEIGHT = 0.75;
+/**
+ * How many query words the quorum check will probe, one bounded FTS query each.
+ *
+ * The check exists because a single incidental token match is not evidence, and
+ * this index cannot tell the difference on its own: FTS5 here has no stemming
+ * and does not split identifiers, so "validations" misses "validation" and
+ * `SessionAuthenticator` is one opaque token. The cap keeps a pathologically
+ * long query from turning into a pathological number of probes; beyond it the
+ * leading words decide, which is where the discriminating terms usually are.
+ */
+const LEXICAL_QUORUM_TOKEN_CAP = 8;
+const LOOSE_LEXICAL_LIMIT = 30;
+/**
+ * The live ranking weights, exported so a benchmark can record which values
+ * produced its numbers.
+ *
+ * Comparing two ranking runs whose constants differed is not a measurement, and
+ * the difference is invisible unless the run writes them down. Reading them here
+ * rather than copying them into the benchmark keeps that record from going stale
+ * the first time someone tunes a weight.
+ */
+export const RANKING_CONSTANTS = {
+    rrfK: RRF_K,
+    centralityWeight: CENTRALITY_RRF_WEIGHT,
+    looseLexicalWeight: LOOSE_LEXICAL_RRF_WEIGHT,
+    looseLexicalLimit: LOOSE_LEXICAL_LIMIT,
+};
 const LAST_REBUILD_SCHEMA_VERSION = 24;
 let indexGeneration = 0;
 const resourceReachabilityCache = new Map();
@@ -1631,12 +1722,76 @@ function createLanguageMemo() {
         return name;
     };
 }
+/**
+ * Node types a `//` line can carry across the grammars this indexes. They
+ * disagree on the name, so matching one of them is not enough on its own — see
+ * `isLineComment` below, which also requires the `//` prefix.
+ */
+const LINE_COMMENT_NODE_TYPES = new Set(["comment", "line_comment", "hash_comment"]);
+/**
+ * Repo-relative files that reference `symbol` and are test files, read from raw
+ * reference rows rather than from resolved callers.
+ *
+ * Resolved callers cannot answer this. A call inside an anonymous callback --
+ * `it("...", () => { target() })`, which is how essentially all test code is
+ * written -- has no enclosing NAMED symbol, so it is stored with a null
+ * `callerSymbol` and every caller-resolution path drops it. Measured on this
+ * repository: 29,158 of 31,467 references from test files (92.7%) have a null
+ * caller, against 390 of 18,399 (2.1%) from production files. So a coverage
+ * question answered from callers is roughly 93% blind in exactly the files it is
+ * asking about, and reported `untested: true` for 642 symbols that have tests
+ * (KNODIN-36).
+ *
+ * The reference row itself carries `callerFile`, which is all this question
+ * needs. Attributing the call to the file instead would be the other repair, and
+ * `call-graph.spec.ts` deliberately forbids it: a file path must never appear as
+ * a caller. So the fix belongs here, at the question, not in the graph.
+ *
+ * Shared by `explain`'s `untested`, `tests_for`, and `detectKnowledgeGaps` so the
+ * definition of "covered by a test" cannot drift between them.
+ */
+function testCallerFilesFor(db, symbol, relativeFile) {
+    const statement = db.query('SELECT DISTINCT callerFile FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL)');
+    const rows = statement.all(symbol, relativeFile);
+    statement.finalize();
+    return rows.map((row) => row.callerFile).filter((file) => isTestFilePath(file));
+}
 /** Clean up and format comment/docstring blocks in JavaScript/TypeScript. */
 function getPrecedingComment(node) {
     let target = node;
     while (target.parent && target.parent.startPosition.row === target.startPosition.row) {
         target = target.parent;
     }
+    // Only decorators and modifiers may sit between a doc comment and the thing
+    // it documents. The walk used to step over ANY five siblings looking for a
+    // comment, so a symbol with no doc comment of its own adopted whichever
+    // comment preceded a nearby earlier symbol — attaching prose to a symbol it
+    // was never written about, in both the embedding input and the FTS `summary`
+    // column.
+    //
+    // That is not a corner case. Measured on this repository before the fix, 857
+    // of 1,329 documented symbols under `src/` — 64% — shared summary text with
+    // another symbol, and spot checks showed plain misattribution rather than
+    // genuine repetition: an interface carrying a neighbouring function's
+    // docstring, two unrelated types sharing a third symbol's sentence. Prose
+    // retrieval matching that text then returns the wrong symbol confidently,
+    // which is the same class of failure as the truncation above and strictly
+    // worse: absent prose loses a hit, misattributed prose manufactures one.
+    //
+    // Stopping at the first non-skippable node is the whole fix. A row-adjacency
+    // check was tried alongside it and removed: decorators are children of the
+    // declaration in some grammars and siblings in others, so "directly above"
+    // is not portable, and it silently dropped the doc comment of every
+    // decorated class. The walk already refuses to cross a declaration, which is
+    // what the misattribution needed.
+    const SKIPPABLE_BEFORE_DOC = new Set([
+        "decorator",
+        "export",
+        "default",
+        "async",
+        "abstract",
+        "declare",
+    ]);
     let prev = target.previousSibling;
     let count = 0;
     while (prev && count < 5) {
@@ -1646,6 +1801,8 @@ function getPrecedingComment(node) {
             prev.type === "line_comment") {
             break;
         }
+        if (!SKIPPABLE_BEFORE_DOC.has(prev.type))
+            return null;
         prev = prev.previousSibling;
         count++;
     }
@@ -1654,6 +1811,48 @@ function getPrecedingComment(node) {
             prev.type === "hash_comment" ||
             prev.type === "block_comment" ||
             prev.type === "line_comment")) {
+        // Walk back over a run of consecutive `//` lines and rejoin them.
+        //
+        // tree-sitter gives every `//` line its OWN comment node, so `prev` is the
+        // LAST line of a block, and the `split("\n")` below could never fire for
+        // this style. Every multi-line `//` doc comment in every indexed
+        // repository was therefore truncated to its final line before it reached
+        // the embedding or the FTS index — silently, since a one-line summary
+        // looks perfectly well-formed.
+        //
+        // That is a retrieval defect, not a cosmetic one: the first line of a doc
+        // comment is usually the sentence that says what the thing is for, which
+        // is exactly what a capability question matches on. `/* */` blocks are a
+        // single node and were never affected, so the damage was invisible in any
+        // codebase that preferred them.
+        //
+        // Adjacency is required: a blank line or any code between two comment
+        // nodes ends the block, so a stray earlier comment is not absorbed.
+        // Keyed on the `//` PREFIX rather than on one node type. The surrounding
+        // checks accept `comment`, `line_comment`, `hash_comment` and
+        // `block_comment` because grammars disagree about the name, and an
+        // earlier version of this rejoin tested `type === "comment"` alone — so
+        // in any grammar that calls a `//` line `line_comment`, multi-line
+        // comments went on being truncated to their last line while appearing
+        // fixed everywhere else. The prefix is the thing that actually decides
+        // whether a node is one line of a multi-line run.
+        const isLineComment = (node) => LINE_COMMENT_NODE_TYPES.has(node.type) && node.text.trim().startsWith("//");
+        if (isLineComment(prev)) {
+            const lines = [];
+            let line = prev;
+            while (line &&
+                isLineComment(line) &&
+                // Consecutive source lines, and nothing but whitespace between them.
+                (lines.length === 0 || line.endPosition.row + 1 === prev.startPosition.row)) {
+                lines.unshift(line.text.trim());
+                prev = line;
+                line = line.previousSibling;
+            }
+            return lines
+                .map((entry) => entry.replace(/^\/\/+\s*/, ""))
+                .join("\n")
+                .trim();
+        }
         let text = prev.text.trim();
         if (text.startsWith("/*")) {
             text = text
@@ -6988,6 +7187,34 @@ function repairPathsAffectTypeScriptDi(db, repoPath, repairPaths) {
 // measurements.
 const DEFAULT_EMBEDDING_BATCH_SIZE = 1;
 const MAX_EMBEDDING_BATCH_SIZE = 32;
+/**
+ * Total characters embedded per symbol.
+ *
+ * A `EMBEDDING_SOURCE_BUDGET` capping the source body inside this was tried and
+ * reverted. It looked like a win — the diluted implementation's similarity rose
+ * 0.163 to 0.212 against its own fresh duplicate — but that was measured on the
+ * suite's bag-of-words test embedder, and re-measuring on the real MiniLM model
+ * across two body shapes, three query phrasings and both budgets showed the cap
+ * never changes the winner in any of the twelve configurations. Its apparent
+ * benefit came from the fixture: `fillerBody` emitted forty copies of one line,
+ * and truncating identical lines removes a redundancy bag-of-words punishes and
+ * a transformer largely ignores. On realistic varied code the cap is neutral to
+ * slightly negative.
+ *
+ * The general lesson, which cost a forced re-embed to learn: a short document
+ * made almost entirely of query tokens beats a long one under cosine
+ * similarity, and no reweighting of a single vector's inputs changes that.
+ * KNODIN-15's remedy is a non-similarity signal — graph degree, in the rank
+ * fusion — not the representation.
+ */
+const EMBEDDING_INPUT_BUDGET = 1000;
+/**
+ * The text embedded for one symbol: what it is called, what kind of thing it
+ * is, what its docstring says it does, and then its body.
+ */
+function embeddingInputFor(symbol, source) {
+    return `Name: ${symbol.name}\nKind: ${symbol.kind}\nSummary: ${symbol.summary || ""}\nSource:\n${source}`.slice(0, EMBEDDING_INPUT_BUDGET);
+}
 // A full embedding pass can touch many symbols per source file. Keep only a
 // bounded LRU of split lines so large repositories avoid re-reading a file for
 // every symbol without turning source preparation into an unbounded memory sink.
@@ -7182,10 +7409,7 @@ async function indexEmbeddings(db, repoPath, progress, signal) {
                 throwIfAborted(signal);
                 const prepared = missing.slice(offset, offset + batchSize).map((sym) => {
                     const source = sourceForEmbedding(sym.filePath, sym.startLine, sym.endLine);
-                    return {
-                        symbol: sym,
-                        text: `Name: ${sym.name}\nKind: ${sym.kind}\nSummary: ${sym.summary || ""}\nSource:\n${source}`.slice(0, 1000),
-                    };
+                    return { symbol: sym, text: embeddingInputFor(sym, source) };
                 });
                 const generated = await embedPreparedBatch(prepared, onModelProgress);
                 throwIfAborted(signal);
@@ -8004,50 +8228,6 @@ const freshnessChecks = new Map();
  * deterministic, rather than in wall-clock milliseconds, which is flaky.
  */
 const freshnessStats = { probes: 0, reconciles: 0, cacheHits: 0 };
-/** Read HEAD without spawning Git. `null` means this is not a Git checkout;
- * `undefined` means Git metadata exists but could not be resolved safely. */
-function readGitHeadFast(repoPath) {
-    const marker = path.join(repoPath, ".git");
-    if (!fs.existsSync(marker))
-        return null;
-    try {
-        const markerStat = fs.statSync(marker);
-        const gitDir = markerStat.isDirectory()
-            ? marker
-            : path.resolve(repoPath, fs
-                .readFileSync(marker, "utf8")
-                .trim()
-                .replace(/^gitdir:\s*/, ""));
-        const head = fs.readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
-        if (/^[a-f0-9]{40}$/i.test(head))
-            return head.toLowerCase();
-        const refPrefix = "ref: ";
-        const ref = head.startsWith(refPrefix) ? head.slice(refPrefix.length).trim() : "";
-        if (!ref)
-            return undefined;
-        let commonDir = gitDir;
-        const commonMarker = path.join(gitDir, "commondir");
-        if (fs.existsSync(commonMarker))
-            commonDir = path.resolve(gitDir, fs.readFileSync(commonMarker, "utf8").trim());
-        for (const base of [gitDir, commonDir]) {
-            const loose = path.join(base, ref);
-            if (fs.existsSync(loose))
-                return fs.readFileSync(loose, "utf8").trim().toLowerCase();
-        }
-        const packed = path.join(commonDir, "packed-refs");
-        if (!fs.existsSync(packed))
-            return undefined;
-        return fs
-            .readFileSync(packed, "utf8")
-            .split("\n")
-            .find((line) => line.endsWith(` ${ref}`))
-            ?.split(" ", 1)[0]
-            ?.toLowerCase();
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Paths the live watcher for `repoPath` currently has registered, flattened to
  * repo-relative form. Empty when no watcher is running (test mode, or after
@@ -8272,15 +8452,20 @@ async function ensureIndexFresh(repoPath, db) {
     // 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.
+    //
+    // The lease used to be paired with a spawn-free HEAD read, so a leased
+    // answer could still be invalidated by a commit. Once git-backed repos took
+    // `lease = 0` that read became unreachable — it was called only when `.git`
+    // was absent, which was its own first bail-out — and the term it fed was
+    // inert. Both are gone (KNODIN-16); a lease is now reached only where there
+    // is no HEAD to check.
     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) {
+    if (cached && Date.now() - cached.at < lease) {
         freshnessStats.cacheHits++;
         return cached.staleness;
     }
@@ -12292,7 +12477,20 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 })
                 : [];
             const allBlastFiles = Array.from(new Set(allCallers.map((c) => c.filePath)));
-            const untested = !allCallers.some((c) => isTestFilePath(c.filePath));
+            // Asked of raw reference rows, not of resolved callers: a test that calls
+            // this symbol from inside an anonymous `it(...)` callback has no caller
+            // symbol and is invisible to `allCallers` (KNODIN-36). `untested: true`
+            // is a positive assertion with no zero-count to invite doubt, so it has
+            // to be answered from the evidence that actually exists.
+            // Three values, not two. Without the defining repository's database this
+            // question cannot be answered, and the previous fallback -- guessing from
+            // resolved callers -- is precisely the collapse that made this field
+            // wrong in the first place: it turned "cannot tell" into a confident
+            // `true`. `untested` is now simply absent when the evidence is absent,
+            // so a caller reading it gets a fact or nothing, never a guess.
+            const untested = targetDb
+                ? testCallerFilesFor(targetDb, primaryDef.name, primaryDef.filePath).length === 0
+                : undefined;
             const minimal = detailLevel === "minimal";
             const cap = minimal ? 25 : 200;
             const truncated = allCallers.length > cap ||
@@ -14447,9 +14645,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         .split(/\s+/)
                         .filter((word) => word.length >= 4)
                         .map((word) => `"${word}"`);
-                    const runFts = (separator) => {
-                        if (tokens.length === 0)
-                            return [];
+                    const runFtsMatch = (match) => {
                         try {
                             const statement = repo.db.query(`
 								SELECT symbolId FROM symbols_fts
@@ -14458,7 +14654,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
 								LIMIT 100
 							`);
                             const ids = statement
-                                .all(tokens.join(separator))
+                                .all(match)
                                 .map(({ symbolId }) => symbolId)
                                 .filter((id) => allowedIds.has(id));
                             statement.finalize();
@@ -14469,8 +14665,43 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             return [];
                         }
                     };
+                    const runFts = (separator) => tokens.length === 0 ? [] : runFtsMatch(tokens.join(separator));
+                    const runFtsTokens = (subset) => subset.length === 0 ? [] : runFtsMatch(subset.join(" OR "));
                     const and = measurePerfPhaseSync("fts", () => runFts(" "));
-                    const or = tokens.length > 1 ? measurePerfPhaseSync("fts", () => runFts(" OR ")) : and;
+                    // The OR set, restricted to candidates matching at least two of the
+                    // query's words.
+                    //
+                    // A single incidental token match is not evidence. FTS5 here has no
+                    // stemming and does not split identifiers, so for "session
+                    // authentication and token validations" the class that actually does
+                    // the work matches NOTHING — its docstring says "sessions" and
+                    // "validation" — while a handler whose docstring happens to contain
+                    // "session" matches once and collects the full partial-match credit.
+                    // Fusing that put the caller above the implementation it calls.
+                    //
+                    // Requiring a quorum keeps the signal that matters (a symbol echoing
+                    // several of the query's words) and drops the one that misleads. It
+                    // costs one bounded FTS query per token, which is why it is capped.
+                    const or = measurePerfPhaseSync("fts", () => {
+                        if (tokens.length < 2)
+                            return and;
+                        const loose = runFts(" OR ");
+                        if (loose.length === 0)
+                            return loose;
+                        const hits = new Map();
+                        for (const token of tokens.slice(0, LEXICAL_QUORUM_TOKEN_CAP)) {
+                            for (const id of runFtsTokens([token])) {
+                                hits.set(id, (hits.get(id) ?? 0) + 1);
+                            }
+                        }
+                        // No fallback when nothing clears the bar. An earlier version
+                        // returned the unfiltered set in that case, which reinstated the
+                        // exact failure the quorum exists to prevent — and did so
+                        // precisely in the small-corpus situation where one weak match is
+                        // most likely to be the only one. A lexical channel with nothing
+                        // trustworthy to say should say nothing.
+                        return loose.filter((id) => (hits.get(id) ?? 0) >= 2);
+                    });
                     const lexicalSeeds = or
                         .map((id) => snapshot.rowById.get(id))
                         .filter((row) => row !== undefined)
@@ -14526,6 +14757,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             // 1. Generate query embedding once
             const queryVec = await generateMeasuredEmbedding(query, true);
             const rankedCandidates = [];
+            // Inbound reference counts for the centrality term. Computed once for the
+            // federation rather than per repo, and only on the route that actually
+            // fuses ranks — the structural and exact-match routes above return before
+            // here and must keep their deterministic ordering.
+            //
+            // Not wrapped in a perf phase: the phase keys are a closed set that the
+            // instrumentation contract asserts on, and adding one to measure a fix
+            // would change what that contract describes.
+            const referenceDegree = computeResolvedReferenceDegree(allRepos, formatPath);
             let totalMatches = 0;
             for (const repo of allRepos) {
                 const db = repo.db;
@@ -14574,12 +14814,35 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 }
                 // Sort by semantic score descending
                 const sortedSemantics = semanticMatches.sort((a, b) => b.score - a.score);
-                const semanticScoresAreTied = sortedSemantics.length > 1 &&
-                    sortedSemantics.every((item) => item.score === sortedSemantics[0]?.score);
                 // 3. Reuse the lexical and bounded-graph ranks computed before query inference.
+                //
+                // Both operators are fused, as separate channels. The selection used to
+                // be `semanticScoresAreTied ? or : and`, and semantic scores are never
+                // all bit-identical under a real embedding model — so the OR set was
+                // computed on every query and then discarded on every query.
+                //
+                // That made the AND clause the entire lexical channel, and for a query
+                // phrased as prose the AND clause is empty: it demands one symbol
+                // containing every surviving query word, function words included.
+                // Nothing matches, so `ftsPart` was zero for every candidate and
+                // "hybrid search" was pure vector search with a centrality nudge. The
+                // docstring's BM25 evidence existed the whole time, in the OR set that
+                // was thrown away (KNODIN-30).
+                //
+                // Fusing both rather than falling back from one to the other avoids a
+                // discontinuity triggered by corpus contents rather than query intent:
+                // with a fallback, one incidental symbol matching every word would flip
+                // the channel from a broad candidate set to a single row, silently.
+                //
+                // `and ⊆ or` by construction — same tokens, narrower operator — so an
+                // AND match collects BOTH terms while an OR-only match collects one.
+                // The precision bonus falls out of that containment exactly, with no
+                // extra machinery to express or tune.
                 const lexical = lexicalRanks.get(repo.path);
-                const baseLexical = semanticScoresAreTied ? lexical?.or : lexical?.and;
-                const ftsMatches = [...new Set(baseLexical ?? [])].filter((id) => allowedIds.has(id));
+                const strictMatches = [...new Set(lexical?.and ?? [])].filter((id) => allowedIds.has(id));
+                const looseMatches = [...new Set(lexical?.or ?? [])]
+                    .filter((id) => allowedIds.has(id))
+                    .slice(0, LOOSE_LEXICAL_LIMIT);
                 // Rank mappings for Reciprocal Rank Fusion (RRF)
                 const semanticRankMap = new Map();
                 const semanticById = new Map();
@@ -14587,19 +14850,57 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     semanticRankMap.set(item.id, idx + 1);
                     semanticById.set(item.id, item);
                 });
-                const ftsRankMap = new Map();
-                ftsMatches.forEach((id, idx) => {
-                    ftsRankMap.set(id, idx + 1);
+                const strictRankMap = new Map();
+                strictMatches.forEach((id, idx) => {
+                    strictRankMap.set(id, idx + 1);
+                });
+                const looseRankMap = new Map();
+                looseMatches.forEach((id, idx) => {
+                    looseRankMap.set(id, idx + 1);
                 });
+                // Rank the matched candidates that anything actually depends on, most
+                // depended-upon first. Symbols with no inbound references are left out
+                // entirely rather than ranked last — see CENTRALITY_RRF_WEIGHT.
+                const centralityRankMap = new Map();
+                {
+                    const connected = [];
+                    for (const id of new Set([
+                        ...semanticRankMap.keys(),
+                        ...strictRankMap.keys(),
+                        ...looseRankMap.keys(),
+                    ])) {
+                        const row = semanticById.get(id)?.row ?? snapshot.rowById.get(id);
+                        if (!row)
+                            continue;
+                        const inDegree = referenceDegree.get(`${formatPath(repo.path, row.filePath)}::${row.name}`)
+                            ?.inDegree ?? 0;
+                        if (inDegree > 0)
+                            connected.push({ id, inDegree });
+                    }
+                    connected.sort((a, b) => b.inDegree - a.inDegree || a.id - b.id);
+                    connected.forEach((item, idx) => {
+                        centralityRankMap.set(item.id, idx + 1);
+                    });
+                }
                 // Perform Reciprocal Rank Fusion (RRF)
                 const topRrf = measurePerfPhaseSync("fusion", () => {
-                    const allMatchedIds = new Set([...semanticRankMap.keys(), ...ftsRankMap.keys()]);
+                    const allMatchedIds = new Set([
+                        ...semanticRankMap.keys(),
+                        ...strictRankMap.keys(),
+                        ...looseRankMap.keys(),
+                    ]);
                     const rrfResults = Array.from(allMatchedIds).map((id) => {
                         const semRank = semanticRankMap.get(id);
-                        const ftsRank = ftsRankMap.get(id);
-                        const semPart = semRank !== undefined ? 1 / (60 + semRank) : 0;
-                        const ftsPart = ftsRank !== undefined ? 1 / (60 + ftsRank) : 0;
-                        return { id, rrfScore: semPart + ftsPart };
+                        const strictRank = strictRankMap.get(id);
+                        const looseRank = looseRankMap.get(id);
+                        const centralityRank = centralityRankMap.get(id);
+                        const semPart = semRank !== undefined ? 1 / (RRF_K + semRank) : 0;
+                        const strictPart = strictRank !== undefined ? 1 / (RRF_K + strictRank) : 0;
+                        const loosePart = looseRank !== undefined ? LOOSE_LEXICAL_RRF_WEIGHT * (1 / (RRF_K + looseRank)) : 0;
+                        const centralityPart = centralityRank !== undefined
+                            ? CENTRALITY_RRF_WEIGHT * (1 / (RRF_K + centralityRank))
+                            : 0;
+                        return { id, rrfScore: semPart + strictPart + loosePart + centralityPart };
                     });
                     // Sort by RRF score descending and take top N
                     return rrfResults.sort((a, b) => b.rrfScore - a.rrfScore).slice(0, candidateLimit);
@@ -14775,6 +15076,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 ...(impactOptions.mode !== "file" ? ["impact"] : []),
             ]);
             let selectedTarget;
+            let targetResolution;
             if (target && symbolPatterns.has(pattern)) {
                 const resolved = resolveSymbolRows(db, primary.path, target, selector);
                 if (resolved.ambiguity)
@@ -14804,6 +15106,26 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         ambiguity: resolved.ambiguity,
                     };
                 selectedTarget = resolved.selected;
+                // Graph health and target resolution are separate axes. A healthy,
+                // fresh graph answering `count: 0` for a misspelled symbol was
+                // byte-identical to one answering for real dead code, and the
+                // freshness stamp made the typo read as an authoritative negative
+                // (KNODIN-28). Say which of the two happened.
+                //
+                // `resolveSymbolRows` only sees the primary database, so a symbol
+                // defined in a federated repo must be checked before it is called
+                // missing — otherwise cross-repo queries would report every target
+                // as a typo.
+                targetResolution = resolved.selected
+                    ? "resolved"
+                    : allRepos.some((r) => {
+                        const stmt = r.db.query("SELECT filePath FROM symbols WHERE name = ? LIMIT 1");
+                        const row = stmt.get(target);
+                        stmt.finalize();
+                        return row != null;
+                    })
+                        ? "resolved"
+                        : "not-found";
             }
             const finish = (rows, extra = {}) => {
                 for (const row of rows) {
@@ -14822,6 +15144,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     count: rows.length,
                     results: rows.slice(0, cap),
                     ...(rows.length > cap ? { hasMore: true } : {}),
+                    ...(targetResolution ? { targetResolution } : {}),
                     ...extra,
                 };
             };
@@ -15004,26 +15327,41 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const refs = pattern === "callers_of"
                         ? findCallersFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null)
                         : findCalleesFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null);
-                    const seen = new Set();
+                    // One row per caller symbol, but carrying every call site it has.
+                    // Collapsing to the first line lost the rest and made `count`
+                    // read as a call-site count (KNODIN-29).
+                    const byCaller = new Map();
                     const rows = [];
+                    let callSiteCount = 0;
                     for (const r of refs) {
                         const file = formatPath(r.repoPath || defRepo, r.filePath);
                         const key = `${r.symbol}|${file}`;
-                        if (seen.has(key))
+                        callSiteCount++;
+                        const existing = byCaller.get(key);
+                        if (existing) {
+                            if (r.lineNumber !== undefined && !existing.callSiteLines?.includes(r.lineNumber))
+                                existing.callSiteLines?.push(r.lineNumber);
                             continue;
-                        seen.add(key);
+                        }
                         const rr = (r.repoPath ? allRepos.find((x) => x.path === r.repoPath) : primary)?.db
                             .query("SELECT * FROM symbols WHERE name = ? AND filePath = ? LIMIT 1")
                             .get(r.symbol, r.filePath);
-                        rows.push({
+                        const row = {
                             symbol: r.symbol,
                             file,
                             line: r.lineNumber,
                             kind: r.kind ?? "call",
+                            callSiteLines: r.lineNumber !== undefined ? [r.lineNumber] : [],
                             ...(rr ? { identity: symbolIdentity(r.repoPath || defRepo, rr) } : {}),
-                        });
+                        };
+                        byCaller.set(key, row);
+                        rows.push(row);
                     }
-                    return finish(rows);
+                    for (const row of rows) {
+                        row.callSiteLines?.sort((a, b) => a - b);
+                        row.line = row.callSiteLines?.[0] ?? row.line;
+                    }
+                    return finish(rows, { callSiteCount });
                 }
                 case "imports_of": {
                     const stmt = db.query("SELECT DISTINCT toFile, kind FROM dependencies WHERE fromFile = ?");
@@ -15162,6 +15500,60 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         seen.add(key);
                         rows.push({ symbol: r.symbol, file, line: r.lineNumber });
                     }
+                    // Resolved callers miss almost every real test. A call inside an
+                    // anonymous `it(...)` callback has no enclosing named symbol, so it
+                    // carries a null `callerSymbol` and `findCallersFederated` drops it
+                    // (92.7% of this repository's test-file references, against 2.1% of
+                    // production ones). Reading the raw rows recovers them (KNODIN-36).
+                    //
+                    // These rows carry no caller name because there genuinely is none,
+                    // and inventing one -- the file path, or the enclosing `describe`
+                    // title -- would put a non-symbol in a `symbol` field that
+                    // `call-graph.spec.ts` explicitly forbids. `symbol` is therefore
+                    // omitted and the file and line carry the answer, which is what the
+                    // question asked for anyway: which test covers this.
+                    for (const repo of allRepos) {
+                        if (defFile && repo.path !== defRepo)
+                            continue;
+                        // MIN(line) grouped by file, not DISTINCT(file, line). The rows are
+                        // deduped by file below, so a plain DISTINCT would leave SQLite free
+                        // to hand back whichever line its query plan reached first when a
+                        // test file references the symbol more than once -- a value that can
+                        // change between runs and plans, which is a flaky test waiting to be
+                        // written. The first reference is both stable and the more useful
+                        // one to report.
+                        // With no defining file the file filter is dropped rather than bound
+                        // to "", which would degrade the clause to `calleeFile IS NULL` and
+                        // silently discard every reference that does carry a file -- turning
+                        // "I do not know where this is defined" into "it is defined nowhere",
+                        // and under-reporting coverage for exactly the symbols we know least
+                        // about (ADR 008). findCallersFederated omits the filter in the same
+                        // situation; these two must not disagree.
+                        const anonymous = defFile
+                            ? (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL) AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target, defFile);
+                                stmt.finalize();
+                                return out;
+                            })()
+                            : (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target);
+                                stmt.finalize();
+                                return out;
+                            })();
+                        for (const row of anonymous) {
+                            const file = formatPath(repo.path, row.callerFile);
+                            if (!isTestFilePath(file))
+                                continue;
+                            const key = `|${file}`;
+                            if (seen.has(key))
+                                continue;
+                            seen.add(key);
+                            rows.push({ file, line: row.line });
+                        }
+                    }
+                    rows.sort((a, b) => (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0));
                     return finish(rows);
                 }
                 case "rename_preview": {