syncstaff-mcp 0.2.3

package/dist/lib/index/pipeline.js

@@ -0,0 +1,527 @@
+import { answerRetrieval } from "./delivery.js";
+import { verifyCandidates } from "./verification.js";
+import { createTransformersEmbedder } from "./transformers-embedder.js";
+import { buildLexicalIndex, routeQuery, vocabularyWeightFromEnv } from "./lexical.js";
+import { cascadeRetrieval } from "./semantic.js";
+import { searchSymbols } from "./symbols.js";
+import { buildDependencyGraph } from "./graph.js";
+import { buildSymbolTable, resolveCallEdges } from "./symbols.js";
+import { byCodeUnit } from "./order.js";
+/** Parse the local rollout switch. Unknown values fail closed to stable. */
+export function retrievalModeFromEnv(value = process.env.KEEL_RETRIEVAL_MODE) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized === "candidate" || normalized === "shadow" ? normalized : "stable";
+}
+const VERIFICATION_CANDIDATE_MULTIPLIER = 3;
+const MIN_VERIFIED_CANDIDATES = 3;
+const MAX_ITERATION_CANDIDATES = 100;
+/** Candidate headroom: how far past the served limit the legs retrieve. */
+const CANDIDATE_POOL_MULTIPLIER = 5;
+const MAX_RELATED_PATHS = 8;
+/** How many of the first-pass hits are used as expansion seeds. */
+const GRAPH_SEED_COUNT = 5;
+/** Ceiling on what one expansion may add, so topology cannot flood the pool. */
+const GRAPH_EXPANSION_LIMIT = 20;
+/**
+ * A call edge is stronger evidence than an import edge.
+ *
+ * Importing a module says this file depends on it; calling a function in it
+ * says this file exercises it. Both are real, and the second is closer to what
+ * "you will need to change this too" means.
+ */
+const GRAPH_EDGE_WEIGHT = { call: 1, import: 0.6 };
+/** How many first-pass files can seed the historical co-change expansion. */
+const COCHANGE_SEED_COUNT = 5;
+/** Ceiling on what historical coupling may add to the candidate pool. */
+const COCHANGE_EXPANSION_LIMIT = 20;
+/**
+ * Ignore the very top historical neighbours: broad hubs are often co-touched
+ * for repository plumbing and otherwise displace query-specific candidates.
+ * The cutoff is deliberately conservative; deeper ranked neighbours retain
+ * the hidden-coupling signal while the lexical leg remains the source of the
+ * initial candidate set.
+ */
+const COCHANGE_MIN_RELATED_RANK = 2;
+/**
+ * Topology is useful only after retrieval has found a concrete anchor.
+ *
+ * A vector neighbour is deliberately not enough: cosine similarity is a
+ * recall signal, not proof that a file is connected to the request. Requiring
+ * either a symbol hit, a high-information lexical signal, or two independent
+ * lexical terms keeps graph expansion from turning an off-topic vector result
+ * into a confident-looking dependency walk.
+ */
+const GRAPH_HIGH_CONFIDENCE_SEEDS = 5;
+const hasHighConfidenceSeed = (path, lexicalHits, symbolHits) => {
+    if (symbolHits.some((hit) => hit.path === path))
+        return true;
+    const lexicalRank = lexicalHits.findIndex((hit) => hit.page.target_path === path);
+    if (lexicalRank < 0 || lexicalRank >= GRAPH_HIGH_CONFIDENCE_SEEDS)
+        return false;
+    const hit = lexicalHits[lexicalRank];
+    return (hit.signal_kinds ?? []).some((kind) => kind === "phrase" || kind === "path" || kind === "identifier")
+        || hit.matched_terms.length >= 2;
+};
+/**
+ * Languages whose topology is allowed to move the ranking.
+ *
+ * Two-stage fusion was adopted on a measurement, not on an argument: +0.0223
+ * recall, CI [0.0116, 0.0330], on TypeScript. The same experiment ran on Python
+ * and failed all three criteria that had been locked before it — the CI lower
+ * bound fell below zero, precision missed its 12% floor, and net rescues stalled
+ * at +1. Precision did not *degrade*; it stayed pinned at 7.0%. The leg simply
+ * never established that it was worth running.
+ *
+ * The resolver that produces those Python edges is not what failed and is not
+ * what this gates. Blast radius, `sync_impact`, lease widening and the codemap
+ * all consume them. What failed was fusing them into a *ranking*, and that is
+ * the only thing switched off here.
+ *
+ * A corpus is rarely one language, so the gate is per edge rather than per
+ * repository: a TypeScript file in a mixed tree keeps the topology that was
+ * measured, and a Python file contributes nothing to the ranking either way.
+ */
+const GRAPH_RANKING_LANGUAGES = new Set(["typescript"]);
+const evidenceSnippets = (page, terms) => {
+    const wanted = terms.map((term) => term.toLowerCase()).filter(Boolean);
+    const lines = page.content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    const matching = lines.filter((line) => {
+        const lower = line.toLowerCase();
+        return wanted.some((term) => lower.includes(term));
+    });
+    const source = matching.length ? matching : lines;
+    return [...new Set(source)].slice(0, 3).map((line) => line.slice(0, 320));
+};
+const relatedPathsFor = (path, index, graph, calls) => {
+    const related = [];
+    for (const edge of graph.edges) {
+        if (edge.from === path)
+            related.push({ path: edge.to, relation: "imports", evidence: `${path} imports ${edge.names.join(", ") || "this module"}` });
+        if (edge.to === path)
+            related.push({ path: edge.from, relation: "imported_by", evidence: `${edge.from} imports this file` });
+    }
+    for (const edge of calls.edges) {
+        if (edge.from === path && edge.to !== path)
+            related.push({ path: edge.to, relation: "calls", evidence: `${path} calls ${edge.symbol}()` });
+        if (edge.to === path && edge.from !== path)
+            related.push({ path: edge.from, relation: "called_by", evidence: `${edge.from} calls ${edge.symbol}()` });
+    }
+    const filename = path.split("/").pop() ?? path;
+    const stem = filename.replace(/\.(?:test|spec)\.[^.]+$/, "").replace(/\.[^.]+$/, "");
+    if (stem) {
+        const directory = path.slice(0, Math.max(0, path.length - filename.length));
+        for (const file of index.files) {
+            const candidate = file.path.split("/").pop() ?? file.path;
+            if (file.path === path || !file.path.startsWith(directory))
+                continue;
+            if (candidate.startsWith(`${stem}.test.`) || candidate.startsWith(`${stem}.spec.`)) {
+                related.push({ path: file.path, relation: "test_sibling", evidence: `${file.path} tests ${path}` });
+            }
+        }
+    }
+    const rank = new Map([["called_by", 0], ["calls", 1], ["imported_by", 2], ["imports", 3], ["test_sibling", 4]]);
+    const unique = new Map();
+    for (const item of related)
+        unique.set(`${item.relation}\0${item.path}`, item);
+    return [...unique.values()]
+        .sort((a, b) => (rank.get(a.relation) - rank.get(b.relation)) || byCodeUnit(a.path, b.path))
+        .slice(0, MAX_RELATED_PATHS);
+};
+/** One client-side call from a natural-language question to an actionable answer. */
+export async function retrieve(pages, query, options = {}) {
+    const retrievalMode = options.retrievalMode ?? retrievalModeFromEnv();
+    if (retrievalMode === "shadow") {
+        const [stable, candidate] = await Promise.all([
+            retrieve(pages, query, {
+                ...options,
+                retrievalMode: "stable",
+                coChangeIndex: undefined,
+                onShadowComparison: undefined,
+            }),
+            retrieve(pages, query, {
+                ...options,
+                retrievalMode: "candidate",
+                onShadowComparison: undefined,
+            }),
+        ]);
+        const stablePaths = stable.results.map((result) => result.page.target_path);
+        const candidatePaths = candidate.results.map((result) => result.page.target_path);
+        const stableSet = new Set(stablePaths);
+        const candidateSet = new Set(candidatePaths);
+        await options.onShadowComparison?.({
+            stable_paths: stablePaths,
+            candidate_paths: candidatePaths,
+            candidate_only: candidatePaths.filter((path) => !stableSet.has(path)).length,
+            stable_only: stablePaths.filter((path) => !candidateSet.has(path)).length,
+        });
+        return stable;
+    }
+    const limit = options.limit ?? 10;
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const excludedCount = options.excludePaths?.size ?? 0;
+    const requestedPool = offset + limit + excludedCount;
+    // Fetch more candidates than we serve. Without headroom the pool is exactly
+    // the response: every candidate retrieved is delivered, so the fusion,
+    // symbol and verification legs can only reorder the lexical top-N and can
+    // never rescue a file lexical ranked just past the cut. It also made every
+    // delivery-layer filter a no-op, because there was nothing to promote into
+    // the slot a filtered candidate vacated.
+    const candidateLimit = Math.min(MAX_ITERATION_CANDIDATES, Math.max(limit * (options.verify ? VERIFICATION_CANDIDATE_MULTIPLIER : 1) * CANDIDATE_POOL_MULTIPLIER, requestedPool));
+    // Chunks exist only so the vector leg can read a whole file. Letting them
+    // into BM25 would index every oversized file several times over, changing
+    // document frequencies and doc lengths for the entire corpus — the lexical
+    // leg must be byte-identical to its pre-chunking behaviour or the two legs
+    // cannot be told apart in a result.
+    const searchablePages = pages.filter((page) => page.page_type !== "chunk");
+    const lexicalIndex = options.lexicalIndex ?? buildLexicalIndex(searchablePages);
+    const configuredVocabularyWeight = options.lexicalVocabularyWeight ?? vocabularyWeightFromEnv();
+    const lexicalVocabularyWeight = retrievalMode === "stable" ? 0 : configuredVocabularyWeight;
+    const lexical = lexicalIndex.searchMulti(query, { limit: candidateLimit, vocabularyWeight: lexicalVocabularyWeight });
+    const lexicalLeg = { name: "lexical", status: "ok", hits: lexical.hits.map((hit) => ({ page: hit.page, score: hit.score })) };
+    const pagesByPath = new Map(pages.filter((page) => page.page_type === "file").map((page) => [page.target_path, page]));
+    // The vector leg reads chunks where a file has them and the file page where
+    // it does not, so a small file is never embedded twice.
+    const chunkedPaths = new Set(pages.filter((page) => page.page_type === "chunk").map((page) => page.target_path));
+    const vectorPages = pages.filter((page) => page.page_type === "chunk" || !chunkedPaths.has(page.target_path));
+    // Kept, not just ranked. These are the symbols the request implicated, and
+    // R9.1 verifies candidates *against them* — so the names have to survive the
+    // leg that found them rather than being reduced to scores.
+    const queryPlan = retrievalMode === "stable" || !options.queryRouting ? undefined : routeQuery(query);
+    const symbolQueries = queryPlan?.symbol_queries ?? [query];
+    const symbolHits = options.symbolIndex
+        ? (() => {
+            const bySymbol = new Map();
+            for (const symbolQuery of symbolQueries) {
+                for (const hit of searchSymbols(options.symbolIndex, symbolQuery, { limit: 20, maxFiles: 8 })) {
+                    const key = `${hit.path}\0${hit.symbol}`;
+                    const current = bySymbol.get(key) ?? { path: hit.path, symbol: hit.symbol, score: 0, matched_terms: new Set() };
+                    current.score = Math.max(current.score, hit.score);
+                    hit.matched_terms.forEach((term) => current.matched_terms.add(term));
+                    bySymbol.set(key, current);
+                }
+            }
+            return [...bySymbol.values()]
+                .map((hit) => ({ ...hit, matched_terms: [...hit.matched_terms].sort(byCodeUnit) }))
+                .sort((a, b) => b.score - a.score || byCodeUnit(a.path, b.path) || byCodeUnit(a.symbol, b.symbol))
+                .slice(0, 20);
+        })()
+        : [];
+    const symbolLeg = options.symbolIndex
+        ? {
+            name: "symbol",
+            status: "ok",
+            hits: symbolHits.flatMap((hit) => {
+                const page = pagesByPath.get(hit.path);
+                return page ? [{ page, score: hit.score, raw_score: hit.score }] : [];
+            }),
+        }
+        : undefined;
+    // `undefined` means "no preference", not "no vector leg" — see RetrievalOptions.
+    // Do not initialize the default model when the caller supplied an explicit
+    // embedder (including `null` to disable vectors). Explicit local providers
+    // must pay only for their own model, and tests/benchmarks should not load an
+    // unrelated Transformers model once per query.
+    //
+    // The default model is also opt-in even when the caller expresses no
+    // preference: loading ~200-300MB of ONNX weights on every retrieve() call
+    // is exactly the duplicate-memory cost tsk_01M1MQ01E1D7JSEHFVE2RCK8DJ
+    // flagged across concurrent agent processes. KEEL_RETRIEVAL_SEMANTIC=1
+    // opts back in; lexical + symbol stays the default high-precision path.
+    const semanticOptIn = process.env.KEEL_RETRIEVAL_SEMANTIC === "1";
+    const embedder = options.embedder === undefined
+        ? (semanticOptIn ? await createTransformersEmbedder() : null)
+        : options.embedder;
+    /**
+     * Stage two of the two-stage fusion: what is connected to the current best
+     * guesses.
+     *
+     * Scored by three things multiplied together.
+     *
+     * Seed rank — a neighbour of the top hit is better evidence than a neighbour
+     * of the fifth.
+     *
+     * Edge kind — calls outrank imports, because exercising a symbol is closer to
+     * needing to change it than merely depending on the module.
+     *
+     * **Inverse degree** — and this one is load-bearing. A logger, a types
+     * barrel, or a shared util sits one hop from most of the repository, so
+     * without a penalty it would surface on every query and drown the actual
+     * request. Dividing by the square root of degree means a file connected to
+     * four hundred others must be reached from many independent seeds before it
+     * outranks one connected to three. This is the mechanism that decides whether
+     * topological fusion helps or invents a new way to ruin the ranking.
+     */
+    const expandFromSeeds = (graph, calls, byPath, rankable) => {
+        // Filtered once, before anything is counted. Degree is the inverse penalty
+        // that decides whether a well-connected file can flood the expansion, so it
+        // has to be computed over the same edges the ranking may traverse — a file
+        // penalised for imports that can never reach it would be scored on a graph
+        // it is not being ranked in.
+        //
+        // On a TypeScript-only corpus every edge survives this and the arm is
+        // byte-identical to the one that measured +0.0223. That is the point: a
+        // gate that perturbs the configuration it protects has swapped one
+        // unmeasured setup for another.
+        const eligible = (edge) => rankable.has(edge.from) && rankable.has(edge.to);
+        const importEdges = graph.edges.filter(eligible);
+        const callEdges = calls.edges.filter(eligible);
+        const degree = new Map();
+        const bump = (path) => degree.set(path, (degree.get(path) ?? 0) + 1);
+        for (const edge of importEdges) {
+            bump(edge.from);
+            bump(edge.to);
+        }
+        for (const edge of callEdges) {
+            bump(edge.from);
+            bump(edge.to);
+        }
+        const neighboursOf = (path) => {
+            const out = [];
+            for (const edge of importEdges) {
+                if (edge.from === path)
+                    out.push({ path: edge.to, weight: GRAPH_EDGE_WEIGHT.import });
+                else if (edge.to === path)
+                    out.push({ path: edge.from, weight: GRAPH_EDGE_WEIGHT.import });
+            }
+            for (const edge of callEdges) {
+                if (edge.from === path && edge.to !== path)
+                    out.push({ path: edge.to, weight: GRAPH_EDGE_WEIGHT.call });
+                else if (edge.to === path && edge.from !== path)
+                    out.push({ path: edge.from, weight: GRAPH_EDGE_WEIGHT.call });
+            }
+            return out;
+        };
+        return (seeds) => {
+            // Nothing rankable to traverse — a Python-only corpus, say. Report the
+            // leg as absent rather than as an empty success, so a run file records
+            // that topology was deliberately not consulted instead of implying it
+            // was consulted and found nothing.
+            if (!importEdges.length && !callEdges.length)
+                return null;
+            const confidentSeeds = seeds.filter((seed) => hasHighConfidenceSeed(seed.page.target_path, lexical.hits, symbolHits));
+            // Never let a weak vector neighbour become a graph seed. Returning null
+            // is observable as an absent leg, which keeps the answer honest about
+            // whether topology was actually consulted.
+            if (confidentSeeds.length === 0)
+                return null;
+            const scores = new Map();
+            confidentSeeds.slice(0, GRAPH_SEED_COUNT).forEach((seed, rank) => {
+                const seedWeight = 1 / (rank + 1);
+                for (const neighbour of neighboursOf(seed.page.target_path)) {
+                    const connectedness = Math.sqrt(Math.max(1, degree.get(neighbour.path) ?? 1));
+                    scores.set(neighbour.path, (scores.get(neighbour.path) ?? 0) + (seedWeight * neighbour.weight) / connectedness);
+                }
+            });
+            const hits = [...scores]
+                .flatMap(([path, score]) => {
+                const page = byPath.get(path);
+                return page ? [{ page, score, raw_score: score }] : [];
+            })
+                .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+                .slice(0, GRAPH_EXPANSION_LIMIT);
+            return { name: "graph", status: "ok", hits };
+        };
+    };
+    /**
+     * Expand only from files the current query already surfaced. Historical
+     * coupling has no query opinion of its own, so it cannot invent a result
+     * from a popular file or from a repository-wide hotspot. The co-change
+     * index is local and cutoff-bound; only its bounded pair evidence crosses
+     * into this in-memory ranking callback.
+     */
+    const cochangeIndex = retrievalMode === "candidate" ? options.coChangeIndex : undefined;
+    const cochangeExpander = cochangeIndex
+        ? (seeds) => {
+            const scores = new Map();
+            seeds.slice(0, COCHANGE_SEED_COUNT).forEach((seed, rank) => {
+                const seedWeight = 1 / (rank + 1);
+                for (const [relatedRank, related] of cochangeIndex
+                    .related(seed.page.target_path, COCHANGE_EXPANSION_LIMIT)
+                    .entries()) {
+                    if (relatedRank < COCHANGE_MIN_RELATED_RANK)
+                        continue;
+                    if (!cochangeIndex.files.has(related.path))
+                        continue;
+                    const current = scores.get(related.path) ?? { score: 0, co_change_count: 0 };
+                    current.score += related.score * seedWeight;
+                    current.co_change_count += related.co_change_count;
+                    scores.set(related.path, current);
+                }
+            });
+            const hits = [...scores]
+                .flatMap(([path, evidence]) => {
+                const page = pagesByPath.get(path);
+                return page ? [{ page, score: evidence.score, raw_score: evidence.score }] : [];
+            })
+                .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+                .slice(0, COCHANGE_EXPANSION_LIMIT);
+            return { name: "cochange", status: "ok", hits };
+        }
+        : undefined;
+    const graphArtifacts = options.symbolIndex
+        ? { graph: buildDependencyGraph(options.symbolIndex), calls: resolveCallEdges(options.symbolIndex, buildSymbolTable(options.symbolIndex)) }
+        : undefined;
+    // The index's own answer, not a guess from the file extension. A backend
+    // registers the language it parsed a file as, so this stays correct when a
+    // new backend is added and cannot drift from what actually produced the edges.
+    const graphRankablePaths = new Set((options.symbolIndex?.files ?? [])
+        .filter((file) => file.language !== null && GRAPH_RANKING_LANGUAGES.has(file.language))
+        .map((file) => file.path));
+    const outcomes = new Map();
+    const fused = await cascadeRetrieval(lexicalLeg, vectorPages, query, embedder, {
+        canonicalPages: pagesByPath,
+        // Ablation switch. A corpus measured for the first time has no pre-graph
+        // baseline to compare against, and producing one from an older build would
+        // confound the comparison with everything else that changed in between —
+        // the same reason KEEL_CHUNK exists.
+        ...(graphArtifacts && process.env.KEEL_NO_GRAPH !== "1" && process.env.CHARTER_NO_GRAPH !== "1"
+            ? { expandFromSeeds: expandFromSeeds(graphArtifacts.graph, graphArtifacts.calls, pagesByPath, graphRankablePaths) }
+            : {}),
+        ...(cochangeExpander ? { expandFromCoChange: cochangeExpander } : {}),
+        limit: candidateLimit,
+        ...(queryPlan && queryPlan.semantic_queries.length > 1 ? { vectorQueries: queryPlan.semantic_queries } : {}),
+        vectorWeight: options.vectorWeight,
+        vectorCache: options.vectorCache,
+        symbolLeg,
+        // A supplied cache is enough to enable document-vector lookup. The cache
+        // keys by embedder and summary identity, so a symbolic index fingerprint is
+        // optional for callers that provide only retrieval pages.
+        fingerprint: options.symbolIndex?.fingerprint ?? (options.vectorCache ? "retrieval-pages" : undefined),
+        onLeg: (leg) => outcomes.set(leg.name, {
+            status: leg.status ?? "ok",
+            hits: leg.hits.length,
+            ...(leg.embedder_id ? { embedder_id: leg.embedder_id } : {}),
+            ...(leg.error ? { error: leg.error } : {}),
+        }),
+    });
+    // R9.1: verify the widened pool, rather than asking the checker to invent
+    // candidates. Delivery narrows to the evidence-backed subset only when the
+    // run produced enough promotions to stand alone; otherwise the full ranking
+    // remains intact with its verification caveat.
+    const visibleFused = options.excludePaths
+        ? fused.filter((hit) => !options.excludePaths.has(hit.page.target_path))
+        : fused;
+    const verdicts = await verifyFused(visibleFused, symbolHits, options.verify);
+    const candidates = visibleFused.map((hit) => {
+        const verdict = verdicts.byPath.get(hit.page.target_path);
+        const lexicalEvidence = lexical.hits.find((candidate) => candidate.page.page_id === hit.page.page_id);
+        const symbolEvidence = symbolHits.filter((candidate) => candidate.path === hit.page.target_path);
+        const symbols = symbolEvidence.map((candidate) => candidate.symbol);
+        const matchedTerms = [...new Set([
+                ...(lexicalEvidence?.matched_terms ?? []),
+                ...symbolEvidence.flatMap((candidate) => candidate.matched_terms),
+            ])].sort();
+        const snippets = evidenceSnippets(hit.page, matchedTerms.length ? matchedTerms : symbols);
+        const agreement = hit.agreement ?? 1;
+        const confidence = verdict || (agreement >= 2 && symbols.length > 0)
+            ? "high"
+            : agreement >= 2 || symbols.length > 0 || (hit.leg_ranks.lexical ?? Number.POSITIVE_INFINITY) <= 2
+                ? "medium"
+                : "low";
+        const relatedPaths = graphArtifacts ? relatedPathsFor(hit.page.target_path, options.symbolIndex, graphArtifacts.graph, graphArtifacts.calls) : [];
+        const signalKinds = lexicalEvidence?.signal_kinds ?? [];
+        return {
+            page: hit.page,
+            score: hit.score,
+            verified: Boolean(verdict),
+            ...(verdict ? { evidence: verdict.evidence, relation: verdict.relation } : {}),
+            reason: verdict
+                // Says which symbol, and on how many call sites — a promotion the reader
+                // can check rather than take on trust (R9.2).
+                ? `compiler-verified: ${verdict.relation} ${verdict.symbol} (${verdict.evidence.length} call site${verdict.evidence.length === 1 ? "" : "s"})`
+                : hit.agreement > 1
+                    ? `${Object.keys(hit.leg_ranks).sort().join("/")} agreement`
+                    : `${Object.keys(hit.leg_ranks)[0] ?? "unknown"} retrieval`,
+            snippets,
+            ...(matchedTerms.length ? { matched_terms: matchedTerms } : {}),
+            ...(symbols.length ? { symbols: [...new Set(symbols)].sort() } : {}),
+            confidence,
+            ...(signalKinds.length ? { signal_kinds: signalKinds } : {}),
+            ...(relatedPaths.length ? { related_paths: relatedPaths } : {}),
+            // Carried, not recomputed. Dropping these here is what made "which legs
+            // ran" unanswerable from an answer — see DeliveryCandidate.leg_ranks.
+            leg_ranks: hit.leg_ranks,
+            // Carried for the same reason as leg_ranks, and it was missed when they
+            // were. The fused score is a function of rank alone — a top hit with
+            // three-leg agreement lands near 0.0247 whether the query found exactly
+            // the right file or nothing relevant — so no threshold on it can tell a
+            // good answer from a hopeless one. Only a raw BM25 or cosine value can,
+            // and 41.7% of benchmark instances never reach gold while paying for ten
+            // files. Deciding to return none of them needs this field.
+            raw_scores: hit.raw_scores,
+            agreement: hit.agreement,
+            leg_statuses: hit.leg_statuses,
+            embedder_ids: hit.embedder_ids,
+        };
+    });
+    const answerCandidates = verdicts.serveVerified
+        ? candidates.filter((candidate) => candidate.verified)
+        : candidates;
+    const answer = answerRetrieval(query, answerCandidates, {
+        limit,
+        offset,
+        excludePaths: options.excludePaths,
+        leasedPaths: options.leasedPaths,
+    });
+    return {
+        ...answer,
+        leg_outcomes: Object.fromEntries(outcomes),
+        ...(verdicts.report ? { verification: verdicts.report } : {}),
+    };
+}
+/**
+ * Ask the checker which fused candidates genuinely reference the implicated
+ * symbols, within the R9.3 budget.
+ *
+ * Returns no report at all when verification was not requested, so an answer
+ * never carries a `verification` field claiming a pass that nobody asked for.
+ * When it *was* requested and could not run, or did not produce enough
+ * promotions to stand alone, the report says so and every candidate stays
+ * unverified — the ranking is returned unchanged, with the caveat attached.
+ */
+async function verifyFused(fused, symbolHits, verify) {
+    const byPath = new Map();
+    if (!verify)
+        return { byPath, serveVerified: false };
+    if (fused.length === 0 || symbolHits.length === 0) {
+        return { byPath, serveVerified: false, report: { ran: false, caveat: "no implicated symbols to verify against", elapsed_ms: 0, promoted: 0 } };
+    }
+    // Every candidate against every implicated symbol: the checker builds its
+    // program once, so the cost is in the parse, not in the pairs.
+    const candidates = fused.flatMap((hit) => symbolHits.map((symbol) => ({ path: hit.page.target_path, symbol: symbol.symbol, declared_in: symbol.path })));
+    const result = await verifyCandidates(verify.root, candidates, { budgetMs: verify.budgetMs });
+    if (!result.verified) {
+        return { byPath, serveVerified: false, report: { ran: false, caveat: result.caveat, elapsed_ms: result.elapsed_ms, promoted: 0 } };
+    }
+    for (const candidate of result.candidates) {
+        if (!candidate.verified || !candidate.relation)
+            continue;
+        const existing = byPath.get(candidate.path);
+        // A page can reference several implicated symbols. Keep the best-evidenced
+        // one, preferring a reference over a declaration: "this file calls it" is
+        // the more useful answer to "where do I edit".
+        const better = !existing ||
+            (existing.relation !== "references" && candidate.relation === "references") ||
+            (existing.relation === candidate.relation && candidate.evidence.length > existing.evidence.length);
+        if (better)
+            byPath.set(candidate.path, { symbol: candidate.symbol, relation: candidate.relation, evidence: candidate.evidence });
+    }
+    const promoted = byPath.size;
+    if (promoted < MIN_VERIFIED_CANDIDATES) {
+        return {
+            byPath: new Map(),
+            serveVerified: false,
+            report: {
+                ran: true,
+                caveat: `checker promoted only ${promoted} candidate${promoted === 1 ? "" : "s"}; retaining the full unverified ranking`,
+                elapsed_ms: result.elapsed_ms,
+                promoted,
+            },
+        };
+    }
+    return {
+        byPath,
+        serveVerified: true,
+        report: { ran: true, caveat: null, elapsed_ms: result.elapsed_ms, promoted },
+    };
+}

package/dist/lib/index/registry.js

@@ -0,0 +1,106 @@
+/**
+ * The language/parser contract for Keel's local index.
+ *
+ * Everything here runs on the agent's machine, beside the checkout, per
+ * inv_01KZWPAM9QCZ0DD7789N55X647 and ADR 002: the central server routes
+ * metadata and never sees code.
+ *
+ * The design principle, stated once because every type below follows from it:
+ *
+ *   A confident wrong answer is worse than an admitted gap.
+ *
+ * Keel already has the counter-example in production. `grep-v1` resolves call
+ * sites by matching a bare symbol name across the repository, so declaring a
+ * TypeScript method named `check` matched a Python comment reading
+ * "# side of the ORPHAN check" and sixteen other files in an unrelated tree.
+ * It reported 38 call sites with no indication that most were noise, the blast
+ * radius came back "wide", and an agent was blocked pending a human decision
+ * that existed only because the analyzer could not tell a call from a comment.
+ *
+ * Nothing here is allowed to do that. Every result carries what produced it
+ * and how much of the input it actually understood, and a file nobody can
+ * parse is reported as unparsed rather than quietly contributing nothing.
+ */
+/**
+ * Which parser handles which file.
+ *
+ * Backends are injected rather than imported. The registry deliberately
+ * depends on no parser: tree-sitter's native bindings need a compiler
+ * toolchain at install time, and this package is meant to be runnable with
+ * `npx` by someone who has never built a native module. A registry that
+ * cannot be constructed without node-gyp would push that cost onto every
+ * consumer, including the ones who only ever wanted lease coordination. So
+ * the packaging decision belongs to whoever assembles the adapter, and this
+ * file states the contract they must satisfy.
+ */
+export class LanguageRegistry {
+    byExtension = new Map();
+    parsers = [];
+    /** Register a backend. Later registrations win, so a host can override. */
+    register(parser) {
+        for (const extension of parser.extensions) {
+            const normalized = extension.toLowerCase();
+            if (!normalized.startsWith(".")) {
+                throw new Error(`extension must include the dot: ${JSON.stringify(extension)}`);
+            }
+            this.byExtension.set(normalized, parser);
+        }
+        this.parsers.push(parser);
+        return this;
+    }
+    parserFor(path) {
+        const dot = path.lastIndexOf(".");
+        if (dot < 0)
+            return undefined;
+        return this.byExtension.get(path.slice(dot).toLowerCase());
+    }
+    supports(path) {
+        return this.parserFor(path) !== undefined;
+    }
+    /**
+     * A stable description of the registered backends, for the fingerprint.
+     * Sorted, because registration order is a property of the host's wiring and
+     * not of the index it produces.
+     */
+    signature() {
+        return [...new Set(this.parsers.map((p) => `${p.id}@${p.version}`))].sort().join(",");
+    }
+    /**
+     * Parse one file, converting any thrown error into a `failed` result.
+     *
+     * Isolation is the point. One unparseable file in a repository of thousands
+     * must cost exactly that file, and a backend that throws on malformed input
+     * — which every real parser eventually does — must not be able to abort an
+     * index build halfway and leave the caller with a partial answer it believes
+     * is complete.
+     */
+    parse(path, source) {
+        const parser = this.parserFor(path);
+        if (!parser) {
+            return {
+                status: "unsupported",
+                imports: [],
+                exports: [],
+                diagnostics: [
+                    { code: "unsupported", message: `no parser registered for ${path.slice(path.lastIndexOf("."))}` },
+                ],
+            };
+        }
+        try {
+            return parser.parse(source, path);
+        }
+        catch (error) {
+            return {
+                status: "failed",
+                imports: [],
+                exports: [],
+                diagnostics: [
+                    {
+                        code: "parser-threw",
+                        message: `${parser.id} threw: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    }
+}