@nanonets/graft 0.12.1 → 0.15.0

package/dist/ask/ask.js

@@ -22,8 +22,10 @@ import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
 import { assertPrefixIndexed, pathUnderPrefix, scopeLabel, scopeOf, scopesHereClause, scopesOfGraph, } from "../graph/scopes.js";
 import { normalizePathPrefix } from "../util/paths.js";
 import { resolveSymbol } from "../graph/traverse.js";
-import { rankScopesAndFuse } from "./fuse.js";
-import { personalizedPageRank } from "./graphrank.js";
+import { combineComparableScopes, rankScopesAndFuse, } from "./fuse.js";
+import { rankFilesBounded, } from "./file-rank.js";
+import { fileFirstRoundRobin, roundRobinQueues } from "./file-selection.js";
+import { personalizedPageRank, personalizedPageRankPrepared, preparePageRankPartitions, } from "./graphrank.js";
 import { readSourceFile } from "../util/source.js";
 import { counts, tokenize } from "./index-file.js";
 /** Max source lines to inline per hit — a definition longer than this is
@@ -140,6 +142,25 @@ function bm25(query, doc, idf, dl, avgdl) {
     }
     return s;
 }
+/** Exact query terms awarded by the existing lexical fields. Bounded ranking uses
+ * presence only: raw name/path/BM25 magnitudes cannot enter the file residual. */
+function matchedLexicalTerms(query, name, path, body) {
+    const terms = new Set();
+    for (const term of query.keys())
+        if (name.has(term) || path.has(term) || body.has(term))
+            terms.add(term);
+    return terms;
+}
+/** NAME-only query terms behind file-level strong coverage. This intentionally
+ * mirrors {@link strongShare}'s plural folding while excluding file nodes at
+ * the call site. */
+function matchedStrongTerms(query, name) {
+    const terms = new Set();
+    for (const term of query.keys())
+        if (hasTerm(name, term))
+            terms.add(term);
+    return terms;
+}
 // ── Structural intent ──────────────────────────────────────────────────────
 const INCOMING = /\b(caller|callers|calls?\s+into|who\s+calls|what\s+calls|called\s+by|used\s+by|uses)\b/;
 const OUTGOING = /\b(callee|callees|what\s+does\s+\w+\s+call|calls\s+what|imports?|depends\s+on)\b/;
@@ -282,7 +303,18 @@ function matchedIdfShare(q, fields, idf, dfltIdf) {
     }
     return total > 0 ? matched / total : 0;
 }
-function lexical(query, corpus, limit, graphRank, inPrefix) {
+/** Normalized query-term IDF mass used by file-level union coverage. Presence
+ * comes from the exact term-contribution maps, so plural folding cannot
+ * manufacture evidence that the lexical scorer did not award. */
+function normalizedQueryWeights(q, idf, dfltIdf) {
+    let total = 0;
+    for (const t of q.keys())
+        total += idf.get(t) ?? dfltIdf;
+    if (total <= 0)
+        return new Map();
+    return new Map([...q.keys()].map((term) => [term, (idf.get(term) ?? dfltIdf) / total]));
+}
+function lexical(query, corpus, limit, graphRank, inPrefix, fileFirst = true, fileComplement = false, fileTopLock = false, includeRankingMetadata = false) {
     // Binary query terms: a word repeated in a pasted issue body counts once, so a
     // ranty description can't linearly amplify an incidental word.
     const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));
@@ -382,6 +414,10 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
     // Parallel to matchedOf, but over NAME+PATH only (body dropped) — the
     // match-strength signal exported as `coverageStrong`.
     const matchedStrongOf = new Map();
+    // Final listwise selection groups code hits by exact source path. Concepts
+    // use singleton pseudo-groups so they remain ordinary ranked candidates
+    // without masquerading as every file listed in their sources.
+    const selectionGroupOf = new Map();
     // ── Concepts (prose nodes; not in the wiring graph) ──
     const conceptHits = [];
     let maxConcept = 0;
@@ -399,6 +435,10 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
             };
             matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));
             matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path field
+            // A concept is one singleton partition even if two source entries reuse
+            // the same slug; include its stable encounter index to prevent accidental
+            // grouping by frontmatter alone.
+            selectionGroupOf.set(hit, `concept:${c.slug}:${conceptHits.length}`);
             conceptHits.push(hit);
         }
     }
@@ -412,9 +452,36 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
     };
     const docsById = new Map(symbolDocs.map((d) => [d.n.id, d]));
     const symbolHits = [];
+    const baselineSymbolHits = [];
+    const baselineHitById = new Map();
+    const fileQueueHitsByGroup = new Map();
+    const baselineQueueHitsByGroup = new Map();
+    const fileGroups = [];
+    const needsFileQueues = fileComplement && (fileTopLock || includeRankingMetadata);
+    const makeSymbolHit = (id, hitScore, scope) => {
+        const n = byId.get(id);
+        if (!n)
+            return null;
+        const hit = {
+            kind: "symbol",
+            title: `${n.name} · ${n.kind}`,
+            pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+            snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+            score: hitScore,
+            ...(scope === undefined ? {} : { scope }),
+        };
+        const d = docsById.get(id);
+        matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
+        matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);
+        selectionGroupOf.set(hit, `file:${n.path}`);
+        return hit;
+    };
+    const symbolTitle = (id) => {
+        const n = byId.get(id);
+        return n ? `${n.name} · ${n.kind}` : id;
+    };
     // The single-vs-multi-scope branch keys on `scopesOfGraph` ONLY: one scope
-    // (or no graph) takes the existing path below completely untouched — that
-    // branch is a byte-level regression guarantee for single-scope repos.
+    // (or no graph) keeps the original local scoring path.
     const scopes = graph ? scopesOfGraph(graph) : null;
     let scopeMeta;
     // The BM25 length prior, corpus-global like `idf`/`dfltIdf` above. Hoisted out
@@ -427,6 +494,18 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
         : symbolDocs.length
             ? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
             : 0;
+    // Populated only for bounded file ranking. The baseline path pays no allocation
+    // or matched-term tracking cost, and their scalar lexical path remains exact.
+    const rawLexicalById = new Map();
+    const matchedTermsById = new Map();
+    const matchedStrongTermsById = new Map();
+    const fileQueryWeights = fileComplement
+        ? normalizedQueryWeights(q, idf, dfltIdf)
+        : new Map();
+    const spanStart = (span) => {
+        const match = span.match(/^L(\d+)-L\d+$/);
+        return match ? Number(match[1]) : Number.POSITIVE_INFINITY;
+    };
     if (scopes && scopes.length > 1) {
         // ── Multi-scope repo: partition by sub-project and walk each subgraph
         // separately — so the big scope can't drown the small one — but score every
@@ -434,14 +513,25 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
         // can be ordered by score. Same scoring functions and blend as the
         // single-scope path; the combination itself lives in fuse.ts. ──
         const byScope = new Map();
+        const scopeById = new Map();
         for (const d of symbolDocs) {
             const s = scopeOf(d.n.path, scopes).prefix;
+            scopeById.set(d.n.id, s);
             const list = byScope.get(s);
             if (list)
                 list.push(d);
             else
                 byScope.set(s, [d]);
         }
+        // Lazily build every scope's PageRank topology in one node/edge pass. The
+        // old nodeFilter path rebuilt the full repo adjacency once per matching
+        // scope; on large multi-project repos that turned one query into hundreds
+        // of full graph scans before the participation gate could run. Waiting for
+        // the first walk keeps no-match and graphRank:false queries edge-scan free.
+        let pageRankByScope;
+        let collapsedComponents = [];
+        let collapsedComponentById;
+        let collapsedFileByRepresentative;
         const fusion = rankScopesAndFuse([...byScope.keys()].sort(), {
             lex: (s) => {
                 const docs = byScope.get(s);
@@ -453,12 +543,20 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
                 // per-scope now; the statistics are global.
                 const out = new Map();
                 for (const { n, name, path, body } of docs) {
+                    const factor = testFactor(n.path);
                     const total = (score(q, name, idf) * 3 +
                         score(q, path, idf) * 2 +
                         bm25(q, body, idf, bodyLen(body), avgBodyLen)) *
-                        testFactor(n.path);
-                    if (total > 0)
+                        factor;
+                    if (total > 0) {
                         out.set(n.id, total);
+                        if (fileComplement) {
+                            rawLexicalById.set(n.id, total);
+                            matchedTermsById.set(n.id, matchedLexicalTerms(q, name, path, body));
+                            if (n.kind !== "file")
+                                matchedStrongTermsById.set(n.id, matchedStrongTerms(q, name));
+                        }
+                    }
                 }
                 return out;
             },
@@ -470,35 +568,121 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
                         return true;
                 return false;
             }),
-            walk: (s, seeds) => graphRank
-                ? personalizedPageRank(graph, seeds, {
-                    nodeFilter: (id) => {
-                        const path = byId.get(id)?.path ?? "";
-                        return scopeOf(path, scopes).prefix === s && (!inPrefix || pathUnderPrefix(path, inPrefix));
-                    },
-                })
-                : new Map(),
+            walk: (s, seeds) => {
+                if (!graphRank)
+                    return new Map();
+                pageRankByScope ??= preparePageRankPartitions(graph, (id) => scopeById.get(id));
+                const topology = pageRankByScope?.get(s);
+                return topology
+                    ? personalizedPageRankPrepared(topology, seeds)
+                    : new Map();
+            },
             rankFactor: (_s, id) => testFactor(byId.get(id)?.path ?? ""),
+            collapseCandidates: fileComplement
+                ? (candidates) => {
+                    collapsedComponents = [...candidates];
+                    collapsedComponentById = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+                    const fileCandidates = candidates.map((candidate) => {
+                        const n = byId.get(candidate.id);
+                        const rawLexical = rawLexicalById.get(candidate.id) ?? 0;
+                        return {
+                            id: candidate.id,
+                            file: n?.path ?? "",
+                            kind: n?.kind === "file" ? "file" : "symbol",
+                            rawLexical,
+                            lexical: candidate.lexical,
+                            graph: candidate.graph,
+                            rankFactor: candidate.rankFactor,
+                            baselineScore: candidate.score,
+                            baselineTieKey: symbolTitle(candidate.id),
+                            matchedTerms: matchedTermsById.get(candidate.id) ?? new Set(),
+                            matchedStrongTerms: matchedStrongTermsById.get(candidate.id) ?? new Set(),
+                            eligible: Boolean(n && n.kind !== "file" && rawLexical > 0),
+                            spanStart: n ? spanStart(n.span) : undefined,
+                        };
+                    });
+                    const rankedFiles = rankFilesBounded(fileCandidates, fileQueryWeights);
+                    collapsedFileByRepresentative = new Map(rankedFiles.map((file) => [file.representative.id, file]));
+                    return rankedFiles.map((file) => {
+                        const component = collapsedComponentById.get(file.representative.id);
+                        return {
+                            id: file.representative.id,
+                            scope: component.scope,
+                            score: file.score,
+                        };
+                    });
+                }
+                : undefined,
         }, GRAPH_WEIGHT, RESCUE_FLOOR);
-        for (const rd of fusion.ranked) {
-            const n = byId.get(rd.id);
-            if (!n)
-                continue;
-            const hit = {
-                kind: "symbol",
-                title: `${n.name} · ${n.kind}`,
-                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
-                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
-                score: rd.score,
-                scope: rd.scope,
-            };
-            const d = docsById.get(rd.id);
-            // Global idf here too, so per-hit coverage means the same thing in a
-            // multi-scope repo as it does in a single-scope one — the escalation
-            // nudge and the hook's coverage gate both read these.
-            matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
-            matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);
-            symbolHits.push(hit);
+        if (needsFileQueues) {
+            const baselineFusion = combineComparableScopes(collapsedComponents.map(({ id, scope, score }) => ({ id, scope, score })));
+            const baselineScoreById = new Map(baselineFusion.ranked.map((ranked) => [ranked.id, ranked.score]));
+            const baselineDisplayOrder = (a, b) => b.score - a.score || symbolTitle(a.id).localeCompare(symbolTitle(b.id));
+            let baselineTopRanked = baselineFusion.ranked[0];
+            for (const ranked of baselineFusion.ranked.slice(1))
+                if (baselineTopRanked && baselineDisplayOrder(ranked, baselineTopRanked) < 0)
+                    baselineTopRanked = ranked;
+            const baselineHitsToBuild = includeRankingMetadata
+                ? [...baselineFusion.ranked].sort(baselineDisplayOrder)
+                : baselineTopRanked
+                    ? [baselineTopRanked]
+                    : [];
+            for (const ranked of baselineHitsToBuild) {
+                const hit = makeSymbolHit(ranked.id, ranked.score, ranked.scope);
+                if (hit) {
+                    baselineSymbolHits.push(hit);
+                    baselineHitById.set(ranked.id, hit);
+                }
+            }
+            for (const ranked of fusion.ranked) {
+                const file = collapsedFileByRepresentative?.get(ranked.id);
+                if (!file)
+                    continue;
+                const materializeFileQueue = () => file.queue.flatMap((member, index) => {
+                    const component = collapsedComponentById?.get(member.id);
+                    if (index > 0) {
+                        const baselineHit = baselineHitById.get(member.id);
+                        if (baselineHit)
+                            return [baselineHit];
+                    }
+                    const hit = makeSymbolHit(member.id, index === 0
+                        ? ranked.score
+                        : baselineScoreById.get(member.id) ?? member.baselineScore, component?.scope ?? ranked.scope);
+                    return hit ? [hit] : [];
+                });
+                const materializeBaselineQueue = () => file.queue.flatMap((member) => {
+                    const hit = makeSymbolHit(member.id, baselineScoreById.get(member.id) ?? member.baselineScore, collapsedComponentById?.get(member.id)?.scope ?? ranked.scope);
+                    return hit ? [hit] : [];
+                });
+                const hits = includeRankingMetadata
+                    ? materializeFileQueue()
+                    : (() => {
+                        const leader = file.queue[0];
+                        if (!leader)
+                            return [];
+                        const hit = makeSymbolHit(leader.id, ranked.score, collapsedComponentById?.get(leader.id)?.scope ?? ranked.scope);
+                        return hit ? [hit] : [];
+                    })();
+                if (hits.length === 0)
+                    continue;
+                const group = {
+                    key: `file:${file.file}`,
+                    hits,
+                    coverage: file.unionCoverage,
+                    coverageStrong: file.unionStrongCoverage,
+                };
+                fileQueueHitsByGroup.set(group.key, materializeFileQueue);
+                baselineQueueHitsByGroup.set(group.key, materializeBaselineQueue);
+                fileGroups.push(group);
+                symbolHits.push(hits[0]);
+            }
+        }
+        else {
+            for (const ranked of fusion.ranked) {
+                const hit = makeSymbolHit(ranked.id, ranked.score, ranked.scope);
+                if (hit)
+                    symbolHits.push(hit);
+            }
         }
         // Label + footer only when federation actually happened (or a scope was
         // gated out and is worth mentioning) — a query matching one scope of a
@@ -516,13 +700,20 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
         for (const { n, name, path, body } of symbolDocs) {
             // Name and path are short identifiers → plain idf-weighted overlap; the body
             // is length-normalized via BM25 so long definitions don't win on bulk.
+            const factor = testFactor(n.path);
             const total = (score(q, name, idf) * 3 +
                 score(q, path, idf) * 2 +
                 bm25(q, body, idf, bodyLen(body), avgBodyLen)) *
-                testFactor(n.path);
+                factor;
             if (total > 0) {
                 lex.set(n.id, total);
                 maxLex = Math.max(maxLex, total);
+                if (fileComplement) {
+                    rawLexicalById.set(n.id, total);
+                    matchedTermsById.set(n.id, matchedLexicalTerms(q, name, path, body));
+                    if (n.kind !== "file")
+                        matchedStrongTermsById.set(n.id, matchedStrongTerms(q, name));
+                }
             }
         }
         // ── Graph-rank: let connectivity to the matched set reorder and rescue ──
@@ -538,46 +729,226 @@ function lexical(query, corpus, limit, graphRank, inPrefix) {
         for (const [id, p] of pr)
             if (p >= RESCUE_FLOOR)
                 candidates.add(id);
+        const singleCandidates = [];
         for (const id of candidates) {
             const n = byId.get(id);
             if (!n)
                 continue;
-            const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+            const lexical = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+            const graphScore = pr.get(id) ?? 0;
+            const rankFactor = testFactor(n.path);
             // Apply the test penalty after normalization too. Applying it only to the
             // raw lexical score is not enough: if a test is still the strongest raw
             // match, dividing by maxLex restores it to 1.0 and erases the de-rank.
-            const blended = (lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0)) * testFactor(n.path);
-            if (blended <= 0)
+            const baseline = (lexical + GRAPH_WEIGHT * graphScore) * rankFactor;
+            if (baseline <= 0)
                 continue;
-            const hit = {
-                kind: "symbol",
-                title: `${n.name} · ${n.kind}`,
-                // A file node points at the whole file (locator, no span) so `--source`
-                // never inlines an entire file; symbol nodes keep their exact span.
-                pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
-                snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
-                score: blended,
-            };
-            const d = docsById.get(id);
-            matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);
-            matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);
-            symbolHits.push(hit);
+            singleCandidates.push({ id, n, lexical, graph: graphScore, rankFactor, baseline });
+        }
+        const candidateById = fileComplement
+            ? new Map(singleCandidates.map((candidate) => [candidate.id, candidate]))
+            : undefined;
+        const rankedFiles = fileComplement
+            ? rankFilesBounded(singleCandidates.map((candidate) => {
+                const rawLexical = rawLexicalById.get(candidate.id) ?? 0;
+                return {
+                    id: candidate.id,
+                    file: candidate.n.path,
+                    kind: candidate.n.kind === "file" ? "file" : "symbol",
+                    rawLexical,
+                    lexical: candidate.lexical,
+                    graph: candidate.graph,
+                    rankFactor: candidate.rankFactor,
+                    baselineScore: candidate.baseline,
+                    baselineTieKey: symbolTitle(candidate.id),
+                    matchedTerms: matchedTermsById.get(candidate.id) ?? new Set(),
+                    matchedStrongTerms: matchedStrongTermsById.get(candidate.id) ?? new Set(),
+                    eligible: candidate.n.kind !== "file" && rawLexical > 0,
+                    spanStart: spanStart(candidate.n.span),
+                };
+            }), fileQueryWeights)
+            : undefined;
+        if (needsFileQueues && rankedFiles) {
+            const baselineCandidateOrder = (a, b) => b.baseline - a.baseline ||
+                `${a.n.name} · ${a.n.kind}`.localeCompare(`${b.n.name} · ${b.n.kind}`);
+            let baselineTopCandidate = singleCandidates[0];
+            for (const candidate of singleCandidates.slice(1))
+                if (baselineTopCandidate && baselineCandidateOrder(candidate, baselineTopCandidate) < 0)
+                    baselineTopCandidate = candidate;
+            const baselineCandidatesToBuild = includeRankingMetadata
+                ? [...singleCandidates].sort(baselineCandidateOrder)
+                : baselineTopCandidate
+                    ? [baselineTopCandidate]
+                    : [];
+            for (const candidate of baselineCandidatesToBuild) {
+                const hit = makeSymbolHit(candidate.id, candidate.baseline);
+                if (hit) {
+                    baselineSymbolHits.push(hit);
+                    baselineHitById.set(candidate.id, hit);
+                }
+            }
+            for (const file of rankedFiles) {
+                const materializeFileQueue = () => file.queue.flatMap((member, index) => {
+                    if (index > 0) {
+                        const baselineHit = baselineHitById.get(member.id);
+                        if (baselineHit)
+                            return [baselineHit];
+                    }
+                    const hit = makeSymbolHit(member.id, index === 0 ? file.score : member.baselineScore);
+                    return hit ? [hit] : [];
+                });
+                const materializeBaselineQueue = () => file.queue.flatMap((member) => {
+                    const hit = makeSymbolHit(member.id, member.baselineScore);
+                    return hit ? [hit] : [];
+                });
+                const hits = includeRankingMetadata
+                    ? materializeFileQueue()
+                    : (() => {
+                        const leader = file.queue[0];
+                        if (!leader)
+                            return [];
+                        const hit = makeSymbolHit(leader.id, file.score);
+                        return hit ? [hit] : [];
+                    })();
+                if (hits.length === 0)
+                    continue;
+                const group = {
+                    key: `file:${file.file}`,
+                    hits,
+                    coverage: file.unionCoverage,
+                    coverageStrong: file.unionStrongCoverage,
+                };
+                fileQueueHitsByGroup.set(group.key, materializeFileQueue);
+                baselineQueueHitsByGroup.set(group.key, materializeBaselineQueue);
+                fileGroups.push(group);
+                symbolHits.push(hits[0]);
+            }
+        }
+        else if (rankedFiles) {
+            for (const file of rankedFiles) {
+                const candidate = candidateById?.get(file.representative.id);
+                const hit = candidate ? makeSymbolHit(candidate.id, file.score) : null;
+                if (hit)
+                    symbolHits.push(hit);
+            }
+        }
+        else {
+            for (const candidate of singleCandidates) {
+                const hit = makeSymbolHit(candidate.id, candidate.baseline);
+                if (hit)
+                    symbolHits.push(hit);
+            }
         }
     }
     // Concepts and symbols live on comparable 0..~1.5 scales so they merge fairly:
-    // concept scores are normalized to their own max, symbol scores are the
+    // concept scores are normalized to their own max; symbol scores use the
     // lexical-normalized + graph-weighted blend.
     for (const h of conceptHits)
         h.score = maxConcept > 0 ? h.score / maxConcept : 0;
     const scored = [...conceptHits, ...symbolHits];
     scored.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
+    const baselineScored = needsFileQueues
+        ? [...conceptHits, ...baselineSymbolHits].sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
+        : scored;
+    const conceptGroups = conceptHits.map((hit, index) => ({
+        key: selectionGroupOf.get(hit) ?? `concept:${index}`,
+        hits: [hit],
+        coverage: matchedOf.get(hit) ?? 0,
+        coverageStrong: matchedStrongOf.get(hit) ?? 0,
+    }));
+    const unlockedGroups = [...conceptGroups, ...fileGroups].sort((a, b) => b.hits[0].score - a.hits[0].score ||
+        a.hits[0].title.localeCompare(b.hits[0].title));
+    const sameHit = (a, b) => a.kind === b.kind && a.pointer === b.pointer && a.title === b.title;
+    let projectedGroups = unlockedGroups;
+    let lockedGroupKey;
+    if (fileTopLock && fileFirst && baselineScored[0]) {
+        const baselineTop = baselineScored[0];
+        const key = selectionGroupOf.get(baselineTop) ?? "locked:top";
+        lockedGroupKey = key;
+        const existing = unlockedGroups.find((group) => group.key === key);
+        const baselineQueue = includeRankingMetadata || limit > unlockedGroups.length
+            ? baselineQueueHitsByGroup.get(key)?.() ?? baselineScored.filter((hit) => (selectionGroupOf.get(hit) ?? "") === key)
+            : [];
+        const locked = existing
+            ? {
+                ...existing,
+                hits: [
+                    baselineTop,
+                    ...baselineQueue.filter((hit) => !sameHit(hit, baselineTop)),
+                ],
+            }
+            : {
+                key,
+                hits: baselineQueue.length ? baselineQueue : [baselineTop],
+                coverage: matchedOf.get(baselineTop) ?? 0,
+                coverageStrong: matchedStrongOf.get(baselineTop) ?? 0,
+            };
+        projectedGroups = [
+            locked,
+            ...unlockedGroups.filter((group) => group.key !== key),
+        ];
+    }
+    // Ranking always sees the complete candidate universe, but a normal bounded
+    // request usually needs only one leader per file. Materialize secondary span
+    // queues only when the requested output can actually reach a second round.
+    if (fileTopLock &&
+        fileFirst &&
+        !includeRankingMetadata &&
+        limit > projectedGroups.length) {
+        projectedGroups = projectedGroups.map((group) => {
+            if (group.key === lockedGroupKey)
+                return group;
+            const materialize = fileQueueHitsByGroup.get(group.key);
+            return materialize ? { ...group, hits: materialize() } : group;
+        });
+    }
+    // File-aware ranking feeds latent groups to the existing file-first frontier.
+    // Leaders are listed first so every file/concept emits once before any
+    // secondary span; each group's remaining queue retains baseline order.
+    const selected = fileTopLock && fileFirst
+        ? roundRobinQueues(projectedGroups.map((group) => group.hits), limit)
+        : fileFirst
+            ? fileFirstRoundRobin(scored.map((hit, index) => ({
+                group: selectionGroupOf.get(hit) ?? `ungrouped:${index}`,
+                value: hit,
+            })), limit)
+            : scored;
+    const top = selected[0] ?? scored[0];
+    if (fileTopLock && top?.scope && scopeMeta) {
+        scopeMeta = {
+            federated: [...new Set([top.scope, ...scopeMeta.federated])],
+            alsoMatched: scopeMeta.alsoMatched.filter((match) => match.scope !== top.scope),
+        };
+    }
+    const ranking = includeRankingMetadata && needsFileQueues
+        ? {
+            groups: unlockedGroups.slice(0, limit).map((group) => ({
+                ...group,
+                hits: group.hits.slice(0, limit),
+                baselineHits: baselineScored
+                    .filter((hit) => selectionGroupOf.get(hit) === group.key)
+                    .slice(0, limit),
+            })),
+            baseline: baselineScored.slice(0, limit).map((hit, index) => ({
+                group: selectionGroupOf.get(hit) ?? `ungrouped:${index}`,
+                hit,
+            })),
+            baselineCoverage: baselineScored[0]
+                ? matchedOf.get(baselineScored[0]) ?? 0
+                : undefined,
+            baselineCoverageStrong: baselineScored[0]
+                ? matchedStrongOf.get(baselineScored[0]) ?? 0
+                : undefined,
+        }
+        : undefined;
     return {
         query,
         mode: scored.length ? "lexical" : "empty",
-        hits: scored.slice(0, limit),
+        hits: selected.slice(0, limit),
         scopes: scopeMeta,
-        coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,
-        coverageStrong: scored.length && q.size > 0 ? matchedStrongOf.get(scored[0]) ?? 0 : undefined,
+        coverage: top && q.size > 0 ? matchedOf.get(top) ?? 0 : undefined,
+        coverageStrong: top && q.size > 0 ? matchedStrongOf.get(top) ?? 0 : undefined,
+        ...(ranking ? { ranking } : {}),
         // Zero hits on a genuinely multi-scope graph names the scopes that exist,
         // so a query that missed everywhere still tells the caller where to look.
         note: scored.length
@@ -672,6 +1043,12 @@ export function ask(dir, query, opts = {}) {
     const limit = opts.limit ?? 8;
     const corpus = loadCorpus(outDir);
     const graphRank = opts.graphRank ?? true;
+    const fileFirst = opts.fileFirst ?? true;
+    // The production path uses bounded file scoring plus an exact baseline top lock.
+    // Internal/raw callers can still request the baseline by disabling
+    // file-first selection. A top lock is projected only on a file-first list.
+    const fileTopLock = opts.fileTopLock ?? fileFirst;
+    const fileComplement = (opts.fileComplement ?? false) || fileTopLock;
     // Normalized ONCE, up front, and this value used everywhere below
     // (validation, filtering, structural). `ask --in frontend/` must work exactly
     // like `--in frontend` — `scopeLabel`/the footer's own `--in <scope>/`
@@ -689,7 +1066,7 @@ export function ask(dir, query, opts = {}) {
             result = outcome.result;
         }
         else {
-            result = lexical(query, corpus, limit, graphRank, inPrefix);
+            result = lexical(query, corpus, limit, graphRank, inPrefix, fileFirst, fileComplement, fileTopLock, opts.includeRankingMetadata ?? false);
             // A structural-intent query that couldn't be answered structurally still
             // gets a prominent note on the lexical fallback result — never silent.
             if (outcome && "fallthroughNote" in outcome) {
@@ -698,10 +1075,18 @@ export function ask(dir, query, opts = {}) {
         }
     }
     else {
-        result = lexical(query, corpus, limit, graphRank, inPrefix);
+        result = lexical(query, corpus, limit, graphRank, inPrefix, fileFirst, fileComplement, fileTopLock, opts.includeRankingMetadata ?? false);
     }
     if (opts.source) {
         inlineSource(root, result.hits, corpus.graph, opts.full ?? false);
+        if (result.ranking) {
+            const internalHits = [
+                ...result.ranking.groups.flatMap((group) => group.hits),
+                ...result.ranking.groups.flatMap((group) => group.baselineHits ?? []),
+                ...result.ranking.baseline.map((entry) => entry.hit),
+            ];
+            inlineSource(root, [...new Set(internalHits)], corpus.graph, opts.full ?? false);
+        }
         // The pack is truly substitutive only in retriever mode (spans inlined), so
         // the "vs reading whole files" estimate is only honest here.
         result.saved = baselineFor(result.hits, corpus.graph);