syncstaff-mcp 0.2.3

package/dist/lib/index/resolve.js

@@ -0,0 +1,280 @@
+/**
+ * Turning an import specifier into a file in this repository, or admitting it
+ * cannot be done.
+ *
+ * Resolution is where a dependency graph either earns trust or quietly loses
+ * it. Every specifier that cannot be resolved is a fork: guess, and the graph
+ * grows an edge that may not exist; drop it silently, and the graph claims a
+ * completeness it does not have. Both produce a graph that looks finished.
+ *
+ * So there is no third option here — every specifier ends up either resolved
+ * to a real indexed path or recorded as unresolved with a reason. `external`
+ * is not a failure and is tracked separately: a bare "node:fs" or "@scope/pkg"
+ * is correctly outside the repository, and filing it next to genuine
+ * resolution failures would bury the ones worth looking at.
+ */
+import { ruleGoverns } from "./aliases.js";
+/**
+ * Extension candidates, in the order TypeScript itself would try them.
+ *
+ * `.js` first is deliberate and counter-intuitive. This codebase is ESM
+ * TypeScript, where `import "./db.js"` refers to `db.ts` on disk — the
+ * specifier names the emitted file, not the source. A resolver that tried
+ * `.ts` first would still land correctly here, but one that does not
+ * understand the rewrite at all resolves nothing in the entire repository.
+ */
+const EXTENSION_CANDIDATES = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+const INDEX_CANDIDATES = EXTENSION_CANDIDATES.map((extension) => `index${extension}`);
+/**
+ * Python candidates, kept separate and applied only to Python importers.
+ *
+ * Not merged into the lists above, because a differential oracle holds this
+ * resolver to the TypeScript compiler's own answers: we may resolve fewer
+ * specifiers than `tsc`, never a different file. A global `.py` candidate could
+ * bind a TypeScript `./foo` to `foo.py` where the compiler binds nothing, which
+ * is precisely the class of invented edge that gate exists to catch.
+ */
+const PYTHON_EXTENSIONS = [".py", ".pyi"];
+const PYTHON_INDEX_CANDIDATES = ["__init__.py", "__init__.pyi"];
+const isPython = (path) => PYTHON_EXTENSIONS.some((extension) => path.endsWith(extension));
+/**
+ * Directories an absolute Python import is resolved against.
+ *
+ * `import pydantic_core.core_schema` names a module, not a path: it is looked
+ * up from whichever directory is on the import path, which for a repository is
+ * the parent of the outermost package. A package is a directory holding
+ * `__init__.py`, so walking up from each one until the chain breaks gives the
+ * roots — `pydantic-core/python/pydantic_core/__init__.py` yields the root
+ * `pydantic-core/python`.
+ *
+ * Cached against the identity of the `known` set. It is the same set for every
+ * specifier in an index build, and rebuilding it per call would turn resolution
+ * into a repeated full scan of the repository.
+ */
+const importRootCache = new WeakMap();
+function pythonImportRoots(known) {
+    const cached = importRootCache.get(known);
+    if (cached)
+        return cached;
+    const packages = new Set();
+    for (const path of known) {
+        for (const index of PYTHON_INDEX_CANDIDATES) {
+            if (path.endsWith(`/${index}`))
+                packages.add(path.slice(0, path.length - index.length - 1));
+        }
+    }
+    // The repository root is always a candidate: a flat script layout has no
+    // packages at all and still imports its siblings by bare name.
+    const roots = new Set([""]);
+    for (const directory of packages) {
+        let current = directory;
+        for (;;) {
+            const parent = current.includes("/") ? current.slice(0, current.lastIndexOf("/")) : "";
+            if (parent && packages.has(parent)) {
+                current = parent;
+                continue;
+            }
+            roots.add(parent);
+            break;
+        }
+    }
+    const list = [...roots];
+    importRootCache.set(known, list);
+    return list;
+}
+/**
+ * Try the alias rules that govern `fromPath`, longest prefix first.
+ *
+ * Returns undefined when no rule matches — the caller then treats the
+ * specifier as external, which is the right answer for a real package.
+ *
+ * Returns `unresolved` in two cases worth distinguishing. A rule matched but
+ * no candidate exists on disk: the alias is configured and the target is
+ * missing, which is a broken import rather than a package. And a rule matched
+ * with SEVERAL candidates present: TypeScript would pick by its own ordering
+ * rules, and picking here would be a guess dressed as a fact. Naming both is
+ * more useful than choosing one, because the ambiguity is the finding.
+ */
+function resolveAlias(specifier, fromPath, known, aliases) {
+    // Rules arrive sorted longest-prefix-first. Among rules that match, prefer
+    // the one whose scope is deepest: web/tsconfig.json governs web/ more
+    // specifically than a root config does.
+    const matching = aliases
+        .filter((rule) => ruleGoverns(rule, fromPath))
+        .filter((rule) => rule.wildcard ? specifier.startsWith(rule.prefix) : specifier === rule.prefix.replace(/\/$/, ""));
+    if (matching.length === 0)
+        return undefined;
+    const best = matching.reduce((a, b) => b.scope.length > a.scope.length || (b.scope.length === a.scope.length && b.prefix.length > a.prefix.length)
+        ? b
+        : a);
+    const suffix = best.wildcard ? specifier.slice(best.prefix.length) : "";
+    const hits = [];
+    for (const target of best.targets) {
+        const base = normalize(suffix ? `${target}/${suffix}` : target);
+        const hit = firstExisting(base, known);
+        if (hit && !hits.includes(hit))
+            hits.push(hit);
+    }
+    if (hits.length === 1)
+        return { kind: "internal", path: hits[0], via: "alias" };
+    if (hits.length > 1) {
+        return {
+            kind: "unresolved",
+            reason: `"${specifier}" is ambiguous under ${best.source}: matches ${hits.join(" and ")}`,
+        };
+    }
+    return {
+        kind: "unresolved",
+        reason: `"${specifier}" matches an alias in ${best.source} but no indexed file exists at ${best.targets.join(" or ")}`,
+    };
+}
+/** The first indexed file for a base path, trying it bare then by extension. */
+function firstExisting(base, known) {
+    if (known.has(base))
+        return base;
+    const dot = base.lastIndexOf(".");
+    const slash = base.lastIndexOf("/");
+    if (dot > slash) {
+        const stem = base.slice(0, dot);
+        for (const extension of EXTENSION_CANDIDATES) {
+            if (known.has(`${stem}${extension}`))
+                return `${stem}${extension}`;
+        }
+    }
+    for (const extension of EXTENSION_CANDIDATES) {
+        if (known.has(`${base}${extension}`))
+            return `${base}${extension}`;
+    }
+    for (const index of INDEX_CANDIDATES) {
+        if (known.has(`${base}/${index}`))
+            return `${base}/${index}`;
+    }
+    return null;
+}
+/** POSIX-normalise "a/./b" and "a/b/../c" without touching the filesystem. */
+function normalize(path) {
+    const parts = [];
+    for (const segment of path.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (parts.length === 0)
+                return path; // escapes the root; leave it alone
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    return parts.join("/");
+}
+function dirnameOf(path) {
+    const slash = path.lastIndexOf("/");
+    return slash < 0 ? "" : path.slice(0, slash);
+}
+/**
+ * Bind a dotted Python module name to a file.
+ *
+ * `a.b.c` is tried against every import root as `a/b/c.py` and then as the
+ * package `a/b/c/__init__.py`. If neither exists the last segment may be a
+ * symbol rather than a module — `from a.b import c` where `c` is a class in
+ * `a/b.py` — so the trailing segment is dropped and the parent retried.
+ *
+ * Returns undefined rather than `unresolved` when nothing matches, because at
+ * that point "external" is the honest answer: `import logging` looks exactly
+ * like `import mypackage` and only the file listing can tell them apart.
+ */
+export function resolvePythonModule(specifier, known, options = {}) {
+    const segments = specifier.split(".").filter(Boolean);
+    if (!segments.length)
+        return undefined;
+    const roots = pythonImportRoots(known);
+    // Full path first, then the parent module — a longer match is more specific
+    // and should win over treating the tail as a symbol.
+    const attempts = options.parentFallback === false ? [segments] : [segments, segments.slice(0, -1)];
+    for (const parts of attempts) {
+        if (!parts.length)
+            continue;
+        const relative = parts.join("/");
+        for (const root of roots) {
+            const base = root ? `${root}/${relative}` : relative;
+            for (const extension of PYTHON_EXTENSIONS) {
+                const candidate = `${base}${extension}`;
+                if (known.has(candidate))
+                    return { kind: "internal", path: candidate, via: "extension" };
+            }
+            for (const index of PYTHON_INDEX_CANDIDATES) {
+                const candidate = `${base}/${index}`;
+                if (known.has(candidate))
+                    return { kind: "internal", path: candidate, via: "directory-index" };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve one specifier as written in `fromPath`.
+ *
+ * `known` is the set of indexed repo-root-relative paths — the resolver only
+ * ever claims an edge to a file the index actually saw. That is what keeps the
+ * graph closed: an edge can never point somewhere the index cannot describe.
+ */
+export function resolveSpecifier(specifier, fromPath, known, aliases = []) {
+    const trimmed = specifier.trim();
+    if (!trimmed)
+        return { kind: "unresolved", reason: "empty specifier" };
+    // A bare specifier is usually a package — but not if a config renamed a
+    // local directory to look like one. Aliases are checked before concluding
+    // "external", because concluding it wrongly deletes every internal edge in
+    // an application that uses them.
+    if (!trimmed.startsWith(".") && !trimmed.startsWith("/")) {
+        const aliased = resolveAlias(trimmed, fromPath, known, aliases);
+        if (aliased)
+            return aliased;
+        // `import a.b.c` is a module path, not a package name, so a Python importer
+        // gets one more chance before this is filed as external. Without it every
+        // absolute import in a Python repository is discarded: pydantic declares
+        // 2,652 imports and this resolver bound none of them.
+        if (isPython(fromPath)) {
+            const dotted = resolvePythonModule(trimmed, known);
+            if (dotted)
+                return dotted;
+        }
+        return { kind: "external", module: trimmed };
+    }
+    const base = trimmed.startsWith("/")
+        ? normalize(trimmed.slice(1))
+        : normalize(`${dirnameOf(fromPath)}/${trimmed}`);
+    if (known.has(base))
+        return { kind: "internal", path: base, via: "exact" };
+    // "./db.js" naming db.ts: strip the emitted extension and try the sources.
+    const dot = base.lastIndexOf(".");
+    const slash = base.lastIndexOf("/");
+    if (dot > slash) {
+        const stem = base.slice(0, dot);
+        for (const extension of EXTENSION_CANDIDATES) {
+            const candidate = `${stem}${extension}`;
+            if (known.has(candidate))
+                return { kind: "internal", path: candidate, via: "extension" };
+        }
+    }
+    // The Python parser normalises `from . import x` and `from ..pkg import y`
+    // into path form (`./x`, `../pkg`), so relative Python imports arrive here
+    // already looking like paths. They failed for one reason: `.py` was not a
+    // candidate extension and `__init__.py` was not a directory index.
+    const extensions = isPython(fromPath) ? [...EXTENSION_CANDIDATES, ...PYTHON_EXTENSIONS] : EXTENSION_CANDIDATES;
+    const indexes = isPython(fromPath) ? [...INDEX_CANDIDATES, ...PYTHON_INDEX_CANDIDATES] : INDEX_CANDIDATES;
+    for (const extension of extensions) {
+        const candidate = `${base}${extension}`;
+        if (known.has(candidate))
+            return { kind: "internal", path: candidate, via: "extension" };
+    }
+    for (const index of indexes) {
+        const candidate = `${base}/${index}`;
+        if (known.has(candidate))
+            return { kind: "internal", path: candidate, via: "directory-index" };
+    }
+    // A relative specifier that matches nothing indexed. Could be a file the
+    // index skipped, a path alias this resolver does not implement, or a broken
+    // import. All three are worth surfacing and none are worth guessing at.
+    return { kind: "unresolved", reason: `no indexed file matches "${specifier}" from ${fromPath}` };
+}

package/dist/lib/index/semantic.js

@@ -0,0 +1,381 @@
+import { byCodeUnit } from "./order.js";
+import { defaultVectorCache, documentText } from "./vector-cache.js";
+const rrfK = 60;
+const symbolRrfK = 180;
+/**
+ * Small on purpose, and it is the constant that decides whether topology can
+ * rescue anything.
+ *
+ * At k=240 and weight 0.5 a graph-only file scored 0.5/240 = 0.0021 while a
+ * lexical hit sitting at rank 50 scored 1/110 = 0.0091 — four times higher. No
+ * file could enter the answer on topology alone however well connected it was
+ * to the seeds, so the leg could only re-order files the query had already
+ * found. Measured on Playwright: 302 graph-ranked results, none of them
+ * introduced by the graph, and a recall effect of +0.006 that came entirely
+ * from reshuffling.
+ *
+ * The obvious fix — raise the weight, lower k to ~80 — is wrong for a subtler
+ * reason. RRF flattens as k grows: at k=80 all twenty expansion hits land
+ * between 0.0125 and 0.0101, a 24% spread, so the whole expansion arrives at
+ * the serve threshold together. That floods rather than rescues, and the
+ * degree ranking still decides nothing.
+ *
+ * A small k makes the leg's own ordering matter. At k=6, weight 0.075:
+ *
+ *   rank 0   0.0125   clears a rank-50 lexical hit (0.0091) — can rescue
+ *   rank 2   0.0094   marginal
+ *   rank 5   0.0068   below the threshold
+ *   rank 19  0.0030   irrelevant, but still contributes on agreement
+ *
+ * So roughly the top two neighbours can enter on topology alone, and which two
+ * is decided by seed rank, edge kind and inverse degree. That is what puts the
+ * hub defence under load: if `1/sqrt(degree)` is too shallow, a utils barrel
+ * takes those slots on every query and the failure is immediate and visible.
+ */
+const graphRrfK = 6;
+/** Co-change has a query-conditioned ranking, so its top neighbours may rescue a weak lexical hit. */
+const cochangeRrfK = 6;
+/** Conservative default from the sealed retrieval comparison: vector evidence is useful for recall, but should not outrank concrete lexical evidence by itself. */
+export const DEFAULT_VECTOR_WEIGHT = 0.65;
+/**
+ * Scaled against `graphRrfK` so a top neighbour lands just above a weak lexical
+ * hit and the fifth lands well below it. See the note there — the pair is one
+ * calibration, not two knobs.
+ */
+export const DEFAULT_GRAPH_WEIGHT = 0.075;
+/** Conservative starting weight; the benchmark must earn making this default-on. */
+export const DEFAULT_COCHANGE_WEIGHT = 0.075;
+const cosine = (a, b) => {
+    let dot = 0, aa = 0, bb = 0;
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+        dot += a[i] * b[i];
+        aa += a[i] ** 2;
+        bb += b[i] ** 2;
+    }
+    return aa && bb ? dot / Math.sqrt(aa * bb) : 0;
+};
+/** Fuse independent ranked legs without pretending their raw scores share a scale. */
+export function fuseRetrieval(legs, limit = 10, weights = {}) {
+    const byId = new Map();
+    for (const leg of legs) {
+        const legK = leg.name === "symbol" ? symbolRrfK : leg.name === "graph" ? graphRrfK : leg.name === "cochange" ? cochangeRrfK : rrfK;
+        const weight = weights[leg.name]
+            ?? (leg.name === "vector" ? DEFAULT_VECTOR_WEIGHT
+                : leg.name === "graph" ? DEFAULT_GRAPH_WEIGHT
+                    : leg.name === "cochange" ? DEFAULT_COCHANGE_WEIGHT
+                        : 1);
+        leg.hits.forEach((hit, rank) => {
+            const current = byId.get(hit.page.page_id) ?? {
+                page: hit.page, score: 0, agreement: 0, leg_ranks: {}, raw_scores: {}, leg_statuses: {}, embedder_ids: {},
+            };
+            current.score += weight / (rank + legK);
+            current.agreement += 1;
+            current.leg_ranks[leg.name] = rank;
+            current.raw_scores[leg.name] = hit.raw_score ?? hit.score;
+            if (leg.status)
+                current.leg_statuses[leg.name] = leg.status;
+            if (leg.embedder_id)
+                current.embedder_ids[leg.name] = leg.embedder_id;
+            byId.set(hit.page.page_id, current);
+        });
+    }
+    return [...byId.values()].sort((a, b) => b.score - a.score || b.agreement - a.agreement || byCodeUnit(a.page.page_id, b.page.page_id)).slice(0, limit);
+}
+/**
+ * The raw-score floor for the vector leg (R4.5).
+ *
+ * A cosine leg always returns a ranked list, even for a query about something
+ * the corpus does not contain — the nearest neighbours of an off-topic
+ * question are simply the least-unrelated pages, and they enter fusion at
+ * rank 0 looking exactly like a confident hit. R4.5 is explicit that the floor
+ * must apply to the RAW retriever score, because a fused RRF score sits above
+ * any floor for every hit by construction.
+ *
+ * Set where an unrelated pair lands rather than where a good match does: with
+ * a signed-hash embedder unrelated documents cluster near zero, so this admits
+ * weak-but-real overlap and rejects noise. It is a judgement call, not a
+ * fitted value, and it is the number to revisit first if the vector leg turns
+ * out to contribute nothing.
+ */
+const DEFAULT_MIN_RAW_SCORE = 0.12;
+export async function vectorSearch(pages, query, embedder, limit = 10, timeoutMs = 250, minRawScore = DEFAULT_MIN_RAW_SCORE, cacheContext) {
+    try {
+        const queryVector = await Promise.race([
+            (embedder.embedQuery ?? embedder.embed).call(embedder, query),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("embedding timeout")), timeoutMs)),
+        ]);
+        const documentVectors = cacheContext
+            ? await (cacheContext.cache ?? defaultVectorCache).documentVectors(cacheContext.fingerprint, pages, embedder)
+            : null;
+        const embedDocument = embedder.embedDocument ?? embedder.embed;
+        const hits = await Promise.all(pages.map(async (page) => ({
+            page,
+            score: cosine(queryVector, documentVectors?.get(page.page_id) ?? await embedDocument.call(embedder, documentText(page))),
+        })));
+        return {
+            name: "vector",
+            status: hits.length ? (embedder.id ? "ok" : "keyless") : (embedder.id ? "ok" : "keyless"),
+            ...(embedder.id ? { embedder_id: embedder.id } : {}),
+            hits: hits
+                // Rank first, then floor. Filtering before the sort would be
+                // equivalent here, but R4.5 says rank position for RRF is unaffected
+                // by the floor, and keeping the order in that sentence makes the
+                // property obvious rather than incidental.
+                .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+                .filter((hit) => hit.score >= minRawScore)
+                .slice(0, limit),
+        };
+    }
+    catch (error) {
+        const timeout = error instanceof Error && error.message === "embedding timeout";
+        return {
+            name: "vector",
+            status: timeout ? "timeout" : "error",
+            ...(embedder.id ? { embedder_id: embedder.id } : {}),
+            error: timeout ? "embedding timeout" : "embedding failed",
+            hits: [],
+        };
+    }
+}
+/**
+ * Run a small routed query set against one document-vector pass.
+ *
+ * The query variants are deliberately fused inside the vector leg. Treating
+ * each variant as a separate top-level leg would over-count agreement and let
+ * a three-variant query outweigh lexical evidence merely because it had more
+ * strings. Averaging rank-reciprocal scores keeps this leg on the same scale
+ * as the single-query vector baseline, while the maximum raw cosine remains
+ * available for floors and diagnostics.
+ */
+export async function vectorSearchMulti(pages, queries, embedder, limit = 10, timeoutMs = 250, minRawScore = DEFAULT_MIN_RAW_SCORE, cacheContext) {
+    const variants = [...new Set(queries.map((query) => query.trim()).filter(Boolean))].slice(0, 4);
+    if (variants.length <= 1) {
+        return vectorSearch(pages, variants[0] ?? "", embedder, limit, timeoutMs, minRawScore, cacheContext);
+    }
+    let documentVectors = null;
+    try {
+        documentVectors = cacheContext
+            ? await (cacheContext.cache ?? defaultVectorCache).documentVectors(cacheContext.fingerprint, pages, embedder)
+            : null;
+        const embedDocument = embedder.embedDocument ?? embedder.embed;
+        const uncachedDocuments = documentVectors
+            ? null
+            : await Promise.all(pages.map((page) => embedDocument.call(embedder, documentText(page))));
+        const queryResults = await Promise.all(variants.map(async (query) => {
+            try {
+                const queryVector = await Promise.race([
+                    (embedder.embedQuery ?? embedder.embed).call(embedder, query),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("embedding timeout")), timeoutMs)),
+                ]);
+                const hits = await Promise.all(pages.map(async (page, index) => ({
+                    page,
+                    score: cosine(queryVector, documentVectors?.get(page.page_id) ?? uncachedDocuments[index]),
+                })));
+                return {
+                    status: "ok",
+                    hits: hits
+                        .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+                        .filter((hit) => hit.score >= minRawScore)
+                        .slice(0, limit),
+                };
+            }
+            catch (error) {
+                const timeout = error instanceof Error && error.message === "embedding timeout";
+                return { status: timeout ? "timeout" : "error", hits: [] };
+            }
+        }));
+        const successful = queryResults.filter((result) => result.status === "ok");
+        if (!successful.length) {
+            const status = queryResults.some((result) => result.status === "timeout") ? "timeout" : "error";
+            return {
+                name: "vector",
+                status,
+                ...(embedder.id ? { embedder_id: embedder.id } : {}),
+                error: status === "timeout" ? "embedding timeout" : "embedding failed",
+                hits: [],
+            };
+        }
+        const byPage = new Map();
+        for (const result of successful) {
+            result.hits.forEach((hit, rank) => {
+                const current = byPage.get(hit.page.page_id) ?? { page: hit.page, score: 0, raw_score: hit.score };
+                current.score += 1 / (variants.length * (rank + rrfK));
+                current.raw_score = Math.max(current.raw_score, hit.score);
+                byPage.set(hit.page.page_id, current);
+            });
+        }
+        return {
+            name: "vector",
+            status: embedder.id ? "ok" : "keyless",
+            ...(embedder.id ? { embedder_id: embedder.id } : {}),
+            hits: [...byPage.values()]
+                .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+                .slice(0, limit),
+        };
+    }
+    catch (error) {
+        return {
+            name: "vector",
+            status: "error",
+            ...(embedder.id ? { embedder_id: embedder.id } : {}),
+            error: "embedding failed",
+            hits: [],
+        };
+    }
+}
+/** How far past `limit` to look when chunk hits will collapse into fewer files. */
+const CHUNK_OVERFETCH = 4;
+/**
+ * Reduce chunk hits to one hit per file, keeping each file's best chunk.
+ *
+ * Max-passage aggregation: the vector leg scores spans, but everything after
+ * it — fusion, delivery, the gold set — speaks in files. Collapsing here keeps
+ * that boundary in one place, so a chunk id can never escape into a response
+ * or be compared against file-level gold.
+ *
+ * A file's score is its best chunk rather than its mean: a long file with one
+ * highly relevant function is a good answer, and averaging would punish it for
+ * the other twenty functions that are irrelevant to this query.
+ */
+function collapseToFiles(leg, canonical, limit) {
+    if (!leg.hits.some((hit) => hit.page.page_type === "chunk"))
+        return leg;
+    const scoresByPath = new Map();
+    for (const hit of leg.hits) {
+        const list = scoresByPath.get(hit.page.target_path) ?? [];
+        list.push(hit.score);
+        scoresByPath.set(hit.page.target_path, list);
+    }
+    const best = new Map();
+    for (const hit of leg.hits) {
+        const path = hit.page.target_path;
+        const scores = scoresByPath.get(path) ?? [hit.score];
+        // Correct the lottery-ticket effect. A file split into many chunks gets
+        // many independent draws at a high score, and the expected maximum of N
+        // draws rises with N — so taking the raw max ranked files by how large
+        // they were, not how relevant. Measured: files opened before reaching gold
+        // were unchanged in number but roughly twice the size.
+        //
+        // The correction is the Gumbel form for the expected maximum of N samples,
+        // scaled by this file's own spread, so there is no constant to fit: one
+        // chunk gets no correction at all, and a file only keeps a high rank if its
+        // best chunk beats what its own variance would produce by chance.
+        const mean = scores.reduce((sum, value) => sum + value, 0) / scores.length;
+        const variance = scores.reduce((sum, value) => sum + (value - mean) ** 2, 0) / scores.length;
+        const expectedMax = Math.sqrt(2 * Math.log(Math.max(scores.length, 1))) * Math.sqrt(variance);
+        const adjusted = hit.score - expectedMax;
+        const existing = best.get(path);
+        if (existing && existing.score >= adjusted)
+            continue;
+        // Rank as the file, but remember which chunk won. Delivery needs the span
+        // to hand back a fragment instead of the whole file, and dropping it here
+        // is what made the chunker's precision unrecoverable downstream.
+        const file = canonical?.get(path) ?? hit.page;
+        best.set(path, {
+            // The chunk's own text travels with its bounds. Taking the file page's
+            // body here would deliver the whole file under a span label, which is the
+            // exact cost the span exists to avoid.
+            page: hit.page.span ? { ...file, span: hit.page.span, body: hit.page.body } : file,
+            score: adjusted,
+        });
+    }
+    return {
+        ...leg,
+        hits: [...best.values()]
+            .sort((a, b) => b.score - a.score || byCodeUnit(a.page.page_id, b.page.page_id))
+            .slice(0, limit),
+    };
+}
+/**
+ * Run every available leg and fuse them by rank.
+ *
+ * This was a lexical-first cascade (R4.7), skipping the vector leg when the
+ * lexical leg looked confident. That requirement is withdrawn: the gate stopped
+ * firing once pages carried file text, and the leg it declined to run is worth
+ * more recall than the latency it saved. See the note at the removal site.
+ */
+export async function cascadeRetrieval(lexical, pages, query, embedder, options = {}) {
+    const limit = options.limit ?? 10;
+    const extra = options.symbolLeg ? [options.symbolLeg] : [];
+    options.onLeg?.(lexical);
+    for (const leg of extra)
+        options.onLeg?.(leg);
+    if (!embedder) {
+        // Still expand. The graph leg does not need an embedder — it needs seeds,
+        // and the lexical and symbol legs have already produced them. Returning
+        // here skipped stage two entirely whenever vectors were off.
+        options.onLeg?.({ name: "vector", status: "absent", hits: [] });
+        const noVector = { symbol: options.symbolWeight, graph: options.graphWeight, cochange: options.cochangeWeight };
+        return refuseWithGraph([lexical, ...extra], fuseRetrieval([lexical, ...extra], limit, noVector), limit, options, noVector);
+    }
+    // R4.7's confidence gate used to skip the vector leg when lexical looked sure
+    // of itself. It is gone, for two reasons.
+    //
+    // It stopped firing. Confidence was `1 - second/top`, needing a 4:1 gap
+    // between the top two BM25 scores. That was reachable when a page was a
+    // structural card of a few dozen tokens; once pages carried the file's own
+    // text every page gained matchable content, scores compressed, and the gate
+    // went silent — 389 of 389 benchmark instances ran the vector leg, across
+    // four corpora, without a single skip.
+    //
+    // And skipping was the wrong trade anyway. The vector leg is worth +0.0574
+    // recall on holdout with a CI clearing zero, so declining to run it bought
+    // latency at the cost of accuracy. Recalibrating the threshold would have
+    // restored a saving nobody should want.
+    // Chunks are scored, files are ranked. Ask for more than `limit` because
+    // several chunks of one file can occupy the head of the list and collapse
+    // into a single hit; taking `limit` first would silently return fewer files
+    // than requested for exactly the files the leg is most confident about.
+    const chunked = pages.some((page) => page.page_type === "chunk");
+    const vector = collapseToFiles(await (options.vectorQueries?.length
+        ? vectorSearchMulti(pages, options.vectorQueries, embedder, chunked ? limit * CHUNK_OVERFETCH : limit, 250, DEFAULT_MIN_RAW_SCORE, options.fingerprint ? { fingerprint: options.fingerprint, cache: options.vectorCache } : undefined)
+        : vectorSearch(pages, query, embedder, chunked ? limit * CHUNK_OVERFETCH : limit, 250, DEFAULT_MIN_RAW_SCORE, options.fingerprint ? { fingerprint: options.fingerprint, cache: options.vectorCache } : undefined)), options.canonicalPages, limit);
+    options.onLeg?.(vector);
+    const weights = { vector: options.vectorWeight, symbol: options.symbolWeight, graph: options.graphWeight, cochange: options.cochangeWeight };
+    const seeded = fuseRetrieval([lexical, vector, ...extra], limit, weights);
+    return refuseWithGraph([lexical, vector, ...extra], seeded, limit, options, weights);
+}
+/**
+ * Stage two of two: expand the ranking along compiler-resolved edges and into
+ * the members of the directories it matched, then fuse those expansions back in
+ * as further legs.
+ *
+ * The graph is exact where the other legs are probabilistic — it knows who
+ * imports what — but it cannot be a parallel leg, because RRF fuses ranked
+ * lists and the graph produces edges from a seed, not a ranking from a query.
+ * So it runs on the output of the first fuse and the result is fused again.
+ *
+ * A file that both matched the query and sits one hop from another match gains
+ * on agreement, which is what RRF already does well. A file the query never
+ * mentioned can still enter on topology alone, which is the point: that is the
+ * load-bearing dependency nobody thought to search for.
+ */
+function refuseWithGraph(legs, seeded, limit, options, weights) {
+    // Every expander reads the *same* first-pass ranking and they are fused back
+    // in one call. Chaining them — expanding the graph, refusing, then expanding
+    // co-change over the result — would let the graph leg choose the co-change
+    // leg's seeds, so a topological neighbour would drag in everything its own
+    // history touches. Two expansions of one ranking is a wider net; an expansion
+    // of an expansion is a second hop nobody measured.
+    const expansions = [];
+    const run = (name, expand) => {
+        if (!expand)
+            return;
+        const leg = expand(seeded);
+        // `null` is "there was nothing to traverse", which is not the same as
+        // "traversed and found nothing" — a run file has to be able to tell a leg
+        // that was deliberately not consulted from one that came back empty.
+        if (!leg) {
+            options.onLeg?.({ name, status: "absent", hits: [] });
+            return;
+        }
+        options.onLeg?.(leg);
+        if (leg.hits.length)
+            expansions.push(leg);
+    };
+    run("graph", options.expandFromSeeds);
+    run("cochange", options.expandFromCoChange);
+    if (!expansions.length)
+        return seeded;
+    return fuseRetrieval([...legs, ...expansions], limit, weights);
+}