knodin 0.10.8 → 0.12.0

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,48 @@ 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"]);
 /** 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 +1773,8 @@ function getPrecedingComment(node) {
             prev.type === "line_comment") {
             break;
         }
+        if (!SKIPPABLE_BEFORE_DOC.has(prev.type))
+            return null;
         prev = prev.previousSibling;
         count++;
     }
@@ -1654,6 +1783,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 +7159,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 +7381,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 +8200,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 +8424,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;
     }
@@ -14447,9 +14604,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 +14613,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 +14624,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 +14716,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 +14773,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 +14809,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 +15035,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 +15065,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 +15103,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 +15286,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 = ?");

package/dist/src/engine/parse-pool.js

@@ -147,10 +147,27 @@ class PoolRun {
         return this.buckets.get(bestKey)?.pop() ?? null;
     }
     attach(slot) {
-        slot.handle.onMessage((response) => this.onResponse(slot, response));
-        slot.handle.onError((error) => this.onSlotFailure(slot, error.message));
-        slot.handle.onExit((code) => {
-            if (slot.inFlight)
+        // Bind these listeners to the handle they were registered on, not just to
+        // the slot. `PoolWorkerHandle` offers no listener removal, so a replaced
+        // worker's listeners stay live and still close over the slot — whose
+        // `.handle` is by then the replacement. A crashed worker's inevitable late
+        // `exit` therefore re-entered `onSlotFailure` and terminated its OWN
+        // replacement, cancelling the one documented retry and leaving the lane
+        // dead; on a one-worker pool that dropped the whole run to inline parsing
+        // (KNODIN-20). Mirrors the `pending.child !== child` guard the MCP
+        // supervisor already carries.
+        const handle = slot.handle;
+        const current = () => slot.handle === handle;
+        handle.onMessage((response) => {
+            if (current())
+                this.onResponse(slot, response);
+        });
+        handle.onError((error) => {
+            if (current())
+                this.onSlotFailure(slot, error.message);
+        });
+        handle.onExit((code) => {
+            if (current() && slot.inFlight)
                 this.onSlotFailure(slot, `worker exited with code ${code}`);
         });
     }