trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/ask/fuse.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Scope-aware ranking for `graft ask`. Pure functions, no fs.
+ *
+ * The problem: lexical + graph scores are corpus-relative. In a multi-scope
+ * repo (a monorepo's `frontend/` + `backend/`, sub-projects under one root),
+ * scoring every node against one pooled corpus lets the biggest sub-project set
+ * the score scale and drown the small one.
+ *
+ * This module solves it by keeping the scope PARTITION — each scope is scored
+ * and walked separately — while making the resulting scores COMPARABLE, so the
+ * combined order can be read straight off the score. Comparability has two
+ * requirements, and both must hold or the order is meaningless:
+ *
+ *   1. shared corpus statistics — the caller scores every scope against the
+ *      repo-wide IDF and length prior (see `ask.ts`), so the same term is worth
+ *      the same everywhere;
+ *   2. a shared normalization denominator — {@link rankScopesAndFuse} divides
+ *      every scope by the best raw score in the REPO, not by each scope's own
+ *      best (see `globalMaxLex` there).
+ *
+ * Issue #117 was the consequence of neither holding. Each scope divided by its
+ * own maximum, so a barely-relevant scope's top hit normalized to ~1.0 exactly
+ * like the genuinely relevant scope's top hit; RRF then fused by RANK, which
+ * discards magnitude outright, so the weak scope's rank-1 tied the strong
+ * scope's rank-1 and displaced its rank-2 — frequently the answer. Measurement
+ * across four repositories and four ecosystems put 73% of missed files in that
+ * bucket. RRF is retained for `federateAsk` (see `graph/workspace.ts`), where
+ * the corpora really are separate repositories and no shared denominator
+ * exists — that is the case rank fusion is for.
+ *
+ * Soft federation: a scope whose top hit is probably an incidental word
+ * collision, not a second home for the query, is left out of the combined order
+ * and reported in `alsoMatched` instead, so the output can say "also matched:
+ * docs/ — narrow with --in docs/" rather than diluting the pack. With
+ * comparable scores that gate is simply {@link PARTICIPATION_RATIO} — a scope
+ * must reach a real share of the best score anywhere in the repo. Under
+ * per-scope normalization that check was vacuous (every scope's top was ~1.0),
+ * which is why a separate match-STRENGTH gate ({@link STRONG_FLOOR}/{@link
+ * HIGH_FLOOR}) had to stand in for it; that signal is still exported and still
+ * used by `federateAsk`, which normalizes per child repo and therefore still
+ * needs it.
+ */
+/** One scored document, attributed to the ranking scope (path prefix, "" =
+ * root) it was scored within. Scores must be per-scope-normalized (each
+ * scope's best ≈ its own ceiling) — fusion compares ranks, not raw scores. */
+export interface ScopedDoc {
+    id: string;
+    scope: string;
+    score: number;
+}
+/** Components preserved until immediately before comparable-scope combination.
+ * Optional ranking experiments can adjust lexical evidence without having to
+ * reconstruct it from the already blended scalar score. */
+export interface ScopeRankCandidate extends ScopedDoc {
+    /** Repo-global-normalized lexical component. */
+    lexical: number;
+    /** Scope-local normalized PPR component. */
+    graph: number;
+    /** Query-aware final multiplier, such as test-file de-ranking. */
+    rankFactor: number;
+}
+export interface FusionResult {
+    /** fused order, best first; carries per-doc scope label + fused score.
+     * Normalized so the top MULTI-scope fused doc is 1 — but the single-scoring-
+     * scope degenerate case passes ORIGINAL (pre-fusion) scores through
+     * unchanged, and those are not guaranteed to fall in [0,1]. */
+    ranked: {
+        id: string;
+        scope: string;
+        score: number;
+    }[];
+    /** scopes that participated in fusion */
+    federated: string[];
+    /** scopes that matched weakly (≥1 scoring doc but below the participation gate) with their best doc */
+    alsoMatched: {
+        scope: string;
+        bestId: string;
+    }[];
+}
+/** RRF smoothing constant — the standard value from the original RRF paper;
+ * high enough that rank 1 vs 2 differ gently rather than by 2×. */
+export declare const RRF_K = 60;
+/** A scope federates only when its best doc scores at least this share of the
+ * global best — below it the match is reported, not fused. Used by
+ * `fuseScopes`'s own internal gate (a post-normalization safety net once a
+ * caller has already applied the real match-strength gate — see
+ * {@link STRONG_FLOOR}/{@link HIGH_FLOOR}). */
+export declare const PARTICIPATION_RATIO = 0.25;
+/** The single source of truth for the cross-scope participation gate shared
+ * by `rankScopesAndFuse` (single-graph multi-scope) and `federateAsk`
+ * (workspace federation, `src/graph/workspace.ts`) — the two paths that solve
+ * the identical "a weak scope must not federate beside a strong one" problem.
+ * They MUST use the same floors so they can never drift into inconsistent
+ * behavior again.
+ *
+ * A scope federates iff its top hit matched a query term in a NAME/PATH field
+ * at all (any strength ≥ `STRONG_FLOOR`) — the primary gate. Well below every
+ * genuine fixture (≥0.45) yet strictly above a body-only collision's 0, so a
+ * real partial-relevance hit on a common/low-idf term is never overcorrected
+ * out. */
+export declare const STRONG_FLOOR = 0.1;
+/** …OR the overall (name+path+body) coverage is broad enough to be real even
+ * body-only. A single incidental body-token collision measures ~0.29 and RISES
+ * with corpus size (0.30+ at 200 nodes) but never approaches this, while a
+ * genuinely broad match clears it. This is why the gate is on absolute,
+ * scale-invariant floors, NOT a raw-lexical-score ratio (which — calibrated for
+ * raw-lexical-SCORE space — was far too lenient in coverage/matched-fraction
+ * space and leaked junk, worsening as the corpus grew). */
+export declare const HIGH_FLOOR = 0.5;
+/**
+ * Partition by scope, rank within scope (input scores are already
+ * per-scope-normalized), gate by soft federation, fuse by RRF:
+ * `fused(id) = Σ 1/(K + rank_in_scope(id))`, then normalized so the top fused
+ * doc is 1. Non-scoring docs (score ≤ 0) are dropped entirely.
+ *
+ * Degenerate cases degrade to current behavior: zero scoring docs → empty
+ * result; exactly one scoring scope → its docs pass through in score order
+ * with their ORIGINAL scores (no RRF re-scoring, no gate) — byte-for-byte the
+ * single-corpus ranking the caller would have produced anyway.
+ */
+export declare function fuseScopes(docs: ScopedDoc[]): FusionResult;
+/**
+ * Combine scopes whose scores are ALREADY comparable (shared corpus statistics
+ * and a shared normalization denominator — see the module header). Same shape
+ * and same gate as {@link fuseScopes}, but the combined order is read straight
+ * off the score instead of from reciprocal rank, because with a common scale
+ * the magnitude is exactly the signal rank fusion would throw away.
+ *
+ * Only {@link rankScopesAndFuse} may call this. `federateAsk` fuses separate
+ * repositories, which have no common denominator, and must keep using
+ * {@link fuseScopes}.
+ */
+export declare function combineComparableScopes(docs: ScopedDoc[]): FusionResult;
+/** The per-scope scoring hooks `rankScopesAndFuse` drives — the caller owns
+ * the actual lexical math and graph walk (they need its corpus state); this
+ * module owns the orchestration so the shape of "rank per scope, then fuse"
+ * lives in one place. */
+export interface ScopeRankOps {
+    /** Lexical scores for the scope's own docs (positive entries only), computed
+     * against the REPO-WIDE corpus statistics. Per-scope statistics would make
+     * the returned numbers incomparable between scopes, which is exactly the
+     * defect in #117 — see the module header. */
+    lex(scope: string): Map<string, number>;
+    /** Does ANY scoring doc in this scope match a query term in its NAME or PATH?
+     *
+     * Serves ONE narrow purpose: suppressing a scope whose entire claim on the
+     * query is prose. Score cannot catch that on its own — BM25 rewards a term
+     * repeated in comments, so a file mentioning "gateway" thirty times in a
+     * banner can outscore the class actually named `GatewayTimeout`.
+     *
+     * Deliberately evaluated over the whole scope, not just its top hit, and as a
+     * presence check rather than a share threshold. Both choices are load-bearing:
+     * a share of the whole query is unreachable for long queries (which is how the
+     * old gate ended up admitting one scope and hiding the rest), and judging a
+     * scope by its single best doc suppressed any scope whose top hit was a file
+     * node — measured at 7.6 points of pooled R@10. */
+    hasIdentifierMatch?(scope: string): boolean;
+    /** Graph walk restricted to the scope's subgraph, seeded by that scope's
+     * lexical scores; returns top-normalized centrality (or an empty map). */
+    walk(scope: string, seeds: Map<string, number>): Map<string, number>;
+    /** Optional query-aware multiplier applied after lexical normalization and
+     * graph blending. Use this for priors (such as test-file de-ranking) that
+     * normalization must not erase. */
+    rankFactor?(scope: string, id: string): number;
+    /** Optional candidate collapse after lexical + graph components are known
+     * but before comparable scopes are gated and combined. File-aware ranking uses this
+     * to supply exactly one real representative per file. The default path omits
+     * the hook and remains byte-identical. */
+    collapseCandidates?(candidates: readonly ScopeRankCandidate[]): readonly ScopedDoc[];
+}
+/**
+ * Multi-scope orchestration for `ask`'s symbol ranking: for each scope, score
+ * lexically (against the repo-wide statistics the caller supplies), walk the
+ * scope's subgraph, blend exactly like the single-scope path (`lexN +
+ * graphWeight·pr`, walk-rescued nodes joining above `rescueFloor`), then
+ * combine the scopes with {@link combineComparableScopes}. A scope with zero
+ * lexical matches contributes nothing (no seeds → no walk → no docs).
+ *
+ * The one thing that differs from the single-scope path: `lexN` divides by
+ * `globalMaxLex`, the best raw lexical score across ALL scopes, rather than by
+ * each scope's own best. That shared denominator is what makes the blended
+ * scores comparable, and therefore what lets the combined order be read off the
+ * score. Dividing per scope — as this did before #117 — pinned every scope's
+ * top hit to ~1.0 regardless of how well it matched, which is the defect.
+ *
+ * Participation is then the {@link PARTICIPATION_RATIO} share check inside
+ * {@link combineComparableScopes}: a scope must reach a real fraction of the
+ * best score anywhere in the repo, else it is reported in `alsoMatched` for
+ * `--in`. The match-STRENGTH floors ({@link STRONG_FLOOR}/{@link HIGH_FLOOR})
+ * are no longer applied here — they existed to stand in for a share check that
+ * per-scope normalization had made vacuous. `federateAsk` still normalizes per
+ * child repo, so it still gates on strength; see `src/graph/workspace.ts`.
+ */
+export declare function rankScopesAndFuse(scopes: string[], ops: ScopeRankOps, graphWeight: number, rescueFloor: number): FusionResult;
+//# sourceMappingURL=fuse.d.ts.map

package/dist/ask/fuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuse.d.ts","sourceRoot":"","sources":["../../src/ask/fuse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;8EAE8E;AAC9E,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;2DAE2D;AAC3D,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B;;;mEAG+D;IAC/D,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACvD,yCAAyC;IACzC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,uGAAuG;IACvG,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAClD;AAED;mEACmE;AACnE,eAAO,MAAM,KAAK,KAAK,CAAC;AAExB;;;;+CAI+C;AAC/C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;;;;;;;;;UAWU;AACV,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC;;;;;;2DAM2D;AAC3D,eAAO,MAAM,UAAU,MAAM,CAAC;AAQ9B;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,YAAY,CA+D1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,YAAY,CAyDvE;AAED;;;yBAGyB;AACzB,MAAM,WAAW,YAAY;IAC3B;;;iDAG6C;IAC7C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;;;;;;;;;;uDAYmD;IACnD,kBAAkB,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C;8EAC0E;IAC1E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrE;;uCAEmC;IACnC,UAAU,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/C;;;8CAG0C;IAC1C,kBAAkB,CAAC,CACjB,UAAU,EAAE,SAAS,kBAAkB,EAAE,GACxC,SAAS,SAAS,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,YAAY,CAqFd"}

package/dist/ask/fuse.js

@@ -0,0 +1,344 @@
+/**
+ * Scope-aware ranking for `graft ask`. Pure functions, no fs.
+ *
+ * The problem: lexical + graph scores are corpus-relative. In a multi-scope
+ * repo (a monorepo's `frontend/` + `backend/`, sub-projects under one root),
+ * scoring every node against one pooled corpus lets the biggest sub-project set
+ * the score scale and drown the small one.
+ *
+ * This module solves it by keeping the scope PARTITION — each scope is scored
+ * and walked separately — while making the resulting scores COMPARABLE, so the
+ * combined order can be read straight off the score. Comparability has two
+ * requirements, and both must hold or the order is meaningless:
+ *
+ *   1. shared corpus statistics — the caller scores every scope against the
+ *      repo-wide IDF and length prior (see `ask.ts`), so the same term is worth
+ *      the same everywhere;
+ *   2. a shared normalization denominator — {@link rankScopesAndFuse} divides
+ *      every scope by the best raw score in the REPO, not by each scope's own
+ *      best (see `globalMaxLex` there).
+ *
+ * Issue #117 was the consequence of neither holding. Each scope divided by its
+ * own maximum, so a barely-relevant scope's top hit normalized to ~1.0 exactly
+ * like the genuinely relevant scope's top hit; RRF then fused by RANK, which
+ * discards magnitude outright, so the weak scope's rank-1 tied the strong
+ * scope's rank-1 and displaced its rank-2 — frequently the answer. Measurement
+ * across four repositories and four ecosystems put 73% of missed files in that
+ * bucket. RRF is retained for `federateAsk` (see `graph/workspace.ts`), where
+ * the corpora really are separate repositories and no shared denominator
+ * exists — that is the case rank fusion is for.
+ *
+ * Soft federation: a scope whose top hit is probably an incidental word
+ * collision, not a second home for the query, is left out of the combined order
+ * and reported in `alsoMatched` instead, so the output can say "also matched:
+ * docs/ — narrow with --in docs/" rather than diluting the pack. With
+ * comparable scores that gate is simply {@link PARTICIPATION_RATIO} — a scope
+ * must reach a real share of the best score anywhere in the repo. Under
+ * per-scope normalization that check was vacuous (every scope's top was ~1.0),
+ * which is why a separate match-STRENGTH gate ({@link STRONG_FLOOR}/{@link
+ * HIGH_FLOOR}) had to stand in for it; that signal is still exported and still
+ * used by `federateAsk`, which normalizes per child repo and therefore still
+ * needs it.
+ */
+/** RRF smoothing constant — the standard value from the original RRF paper;
+ * high enough that rank 1 vs 2 differ gently rather than by 2×. */
+export const RRF_K = 60;
+/** A scope federates only when its best doc scores at least this share of the
+ * global best — below it the match is reported, not fused. Used by
+ * `fuseScopes`'s own internal gate (a post-normalization safety net once a
+ * caller has already applied the real match-strength gate — see
+ * {@link STRONG_FLOOR}/{@link HIGH_FLOOR}). */
+export const PARTICIPATION_RATIO = 0.25;
+/** The single source of truth for the cross-scope participation gate shared
+ * by `rankScopesAndFuse` (single-graph multi-scope) and `federateAsk`
+ * (workspace federation, `src/graph/workspace.ts`) — the two paths that solve
+ * the identical "a weak scope must not federate beside a strong one" problem.
+ * They MUST use the same floors so they can never drift into inconsistent
+ * behavior again.
+ *
+ * A scope federates iff its top hit matched a query term in a NAME/PATH field
+ * at all (any strength ≥ `STRONG_FLOOR`) — the primary gate. Well below every
+ * genuine fixture (≥0.45) yet strictly above a body-only collision's 0, so a
+ * real partial-relevance hit on a common/low-idf term is never overcorrected
+ * out. */
+export const STRONG_FLOOR = 0.1;
+/** …OR the overall (name+path+body) coverage is broad enough to be real even
+ * body-only. A single incidental body-token collision measures ~0.29 and RISES
+ * with corpus size (0.30+ at 200 nodes) but never approaches this, while a
+ * genuinely broad match clears it. This is why the gate is on absolute,
+ * scale-invariant floors, NOT a raw-lexical-score ratio (which — calibrated for
+ * raw-lexical-SCORE space — was far too lenient in coverage/matched-fraction
+ * space and leaked junk, worsening as the corpus grew). */
+export const HIGH_FLOOR = 0.5;
+/** Score-desc, id-asc ordering — the id tiebreak is what makes fusion
+ * deterministic under input shuffle. */
+function byScore(a, b) {
+    return b.score - a.score || a.id.localeCompare(b.id);
+}
+/**
+ * Partition by scope, rank within scope (input scores are already
+ * per-scope-normalized), gate by soft federation, fuse by RRF:
+ * `fused(id) = Σ 1/(K + rank_in_scope(id))`, then normalized so the top fused
+ * doc is 1. Non-scoring docs (score ≤ 0) are dropped entirely.
+ *
+ * Degenerate cases degrade to current behavior: zero scoring docs → empty
+ * result; exactly one scoring scope → its docs pass through in score order
+ * with their ORIGINAL scores (no RRF re-scoring, no gate) — byte-for-byte the
+ * single-corpus ranking the caller would have produced anyway.
+ */
+export function fuseScopes(docs) {
+    const byScope = new Map();
+    for (const d of docs) {
+        if (d.score <= 0)
+            continue;
+        const list = byScope.get(d.scope);
+        if (list)
+            list.push(d);
+        else
+            byScope.set(d.scope, [d]);
+    }
+    for (const list of byScope.values())
+        list.sort(byScore);
+    if (byScope.size === 0)
+        return { ranked: [], federated: [], alsoMatched: [] };
+    if (byScope.size === 1) {
+        const [scope, list] = byScope.entries().next().value;
+        return {
+            ranked: list.map((d) => ({ id: d.id, scope, score: d.score })),
+            federated: [scope],
+            alsoMatched: [],
+        };
+    }
+    // Gate: order scopes by their best doc (desc, scope-name tiebreak), split
+    // into federated (≥ ratio × global best, inclusive) and alsoMatched.
+    const scopesByBest = [...byScope.entries()].sort((a, b) => b[1][0].score - a[1][0].score || a[0].localeCompare(b[0]));
+    const gate = PARTICIPATION_RATIO * scopesByBest[0][1][0].score;
+    const federated = [];
+    const alsoMatched = [];
+    for (const [scope, list] of scopesByBest) {
+        if (list[0].score >= gate)
+            federated.push(scope);
+        else
+            alsoMatched.push({ scope, bestId: list[0].id });
+    }
+    // RRF: each federated scope contributes 1/(K + rank) per doc; an id listed
+    // in more than one scope sums its contributions and is attributed to the
+    // scope where it ranked best.
+    const acc = new Map();
+    for (const scope of federated) {
+        byScope.get(scope).forEach((d, i) => {
+            const contribution = 1 / (RRF_K + i + 1);
+            const prev = acc.get(d.id);
+            if (!prev)
+                acc.set(d.id, { scope, score: contribution, bestRank: i });
+            else {
+                prev.score += contribution;
+                if (i < prev.bestRank) {
+                    prev.scope = scope;
+                    prev.bestRank = i;
+                }
+            }
+        });
+    }
+    let max = 0;
+    for (const e of acc.values())
+        if (e.score > max)
+            max = e.score;
+    const ranked = [...acc.entries()].map(([id, e]) => ({
+        id,
+        scope: e.scope,
+        score: e.score / max,
+    }));
+    ranked.sort((a, b) => b.score - a.score || a.scope.localeCompare(b.scope) || a.id.localeCompare(b.id));
+    return { ranked, federated, alsoMatched };
+}
+/**
+ * Combine scopes whose scores are ALREADY comparable (shared corpus statistics
+ * and a shared normalization denominator — see the module header). Same shape
+ * and same gate as {@link fuseScopes}, but the combined order is read straight
+ * off the score instead of from reciprocal rank, because with a common scale
+ * the magnitude is exactly the signal rank fusion would throw away.
+ *
+ * Only {@link rankScopesAndFuse} may call this. `federateAsk` fuses separate
+ * repositories, which have no common denominator, and must keep using
+ * {@link fuseScopes}.
+ */
+export function combineComparableScopes(docs) {
+    const byScope = new Map();
+    for (const d of docs) {
+        if (d.score <= 0)
+            continue;
+        const list = byScope.get(d.scope);
+        if (list)
+            list.push(d);
+        else
+            byScope.set(d.scope, [d]);
+    }
+    for (const list of byScope.values())
+        list.sort(byScore);
+    if (byScope.size === 0)
+        return { ranked: [], federated: [], alsoMatched: [] };
+    // One scoring scope: pass through untouched. Identical to the single-scope
+    // path by construction — the guarantee that a single-scope repo cannot move.
+    if (byScope.size === 1) {
+        const [scope, list] = byScope.entries().next().value;
+        return {
+            ranked: list.map((d) => ({ id: d.id, scope, score: d.score })),
+            federated: [scope],
+            alsoMatched: [],
+        };
+    }
+    // Gate on a real share of the best score in the repo. This is the same
+    // ratio check `fuseScopes` runs, but here it MEANS something: the scores
+    // being compared share a denominator.
+    const scopesByBest = [...byScope.entries()].sort((a, b) => b[1][0].score - a[1][0].score || a[0].localeCompare(b[0]));
+    const gate = PARTICIPATION_RATIO * scopesByBest[0][1][0].score;
+    const federated = [];
+    const alsoMatched = [];
+    for (const [scope, list] of scopesByBest) {
+        if (list[0].score >= gate)
+            federated.push(scope);
+        else
+            alsoMatched.push({ scope, bestId: list[0].id });
+    }
+    // An id can only belong to one scope (scope is a path prefix), but keep the
+    // defensive max so a duplicate cannot double-count or flip its attribution.
+    const acc = new Map();
+    for (const scope of federated) {
+        for (const d of byScope.get(scope)) {
+            const prev = acc.get(d.id);
+            if (!prev || d.score > prev.score)
+                acc.set(d.id, { scope, score: d.score });
+        }
+    }
+    let max = 0;
+    for (const e of acc.values())
+        if (e.score > max)
+            max = e.score;
+    const ranked = [...acc.entries()].map(([id, e]) => ({
+        id,
+        scope: e.scope,
+        score: max > 0 ? e.score / max : 0,
+    }));
+    ranked.sort((a, b) => b.score - a.score || a.scope.localeCompare(b.scope) || a.id.localeCompare(b.id));
+    return { ranked, federated, alsoMatched };
+}
+/**
+ * Multi-scope orchestration for `ask`'s symbol ranking: for each scope, score
+ * lexically (against the repo-wide statistics the caller supplies), walk the
+ * scope's subgraph, blend exactly like the single-scope path (`lexN +
+ * graphWeight·pr`, walk-rescued nodes joining above `rescueFloor`), then
+ * combine the scopes with {@link combineComparableScopes}. A scope with zero
+ * lexical matches contributes nothing (no seeds → no walk → no docs).
+ *
+ * The one thing that differs from the single-scope path: `lexN` divides by
+ * `globalMaxLex`, the best raw lexical score across ALL scopes, rather than by
+ * each scope's own best. That shared denominator is what makes the blended
+ * scores comparable, and therefore what lets the combined order be read off the
+ * score. Dividing per scope — as this did before #117 — pinned every scope's
+ * top hit to ~1.0 regardless of how well it matched, which is the defect.
+ *
+ * Participation is then the {@link PARTICIPATION_RATIO} share check inside
+ * {@link combineComparableScopes}: a scope must reach a real fraction of the
+ * best score anywhere in the repo, else it is reported in `alsoMatched` for
+ * `--in`. The match-STRENGTH floors ({@link STRONG_FLOOR}/{@link HIGH_FLOOR})
+ * are no longer applied here — they existed to stand in for a share check that
+ * per-scope normalization had made vacuous. `federateAsk` still normalizes per
+ * child repo, so it still gates on strength; see `src/graph/workspace.ts`.
+ */
+export function rankScopesAndFuse(scopes, ops, graphWeight, rescueFloor) {
+    // Pass 1: lexical scoring only, per scope.
+    const lexByScope = new Map();
+    for (const scope of scopes) {
+        const lex = ops.lex(scope);
+        if (lex.size === 0)
+            continue;
+        lexByScope.set(scope, lex);
+    }
+    const alsoMatched = [];
+    const candidatesWithComponents = [];
+    // Per-scope raw best, plus the best raw score anywhere in the repo. That
+    // repo-wide maximum is the shared denominator every scope normalizes by.
+    const meta = new Map();
+    let globalMaxLex = 0;
+    for (const [scope, lex] of lexByScope) {
+        let maxLex = 0, bestId = "";
+        for (const [id, v] of lex)
+            if (v > maxLex || (v === maxLex && id < bestId)) {
+                maxLex = v;
+                bestId = id;
+            }
+        if (maxLex <= 0)
+            continue;
+        meta.set(scope, { lex, maxLex, bestId });
+        if (maxLex > globalMaxLex)
+            globalMaxLex = maxLex;
+    }
+    // Body-only suppression. With a shared denominator a weak scope simply
+    // scores low, so participation is decided on score in
+    // `combineComparableScopes` — no scope is excluded on a share threshold any
+    // more. The single exception is a scope in which NO doc matched a query term
+    // in a name or path while some other scope did: that is the comment-banner
+    // collision (see `hasIdentifierMatch` above), and score cannot separate it
+    // from a real match. Only applied when a genuine identifier match exists
+    // somewhere, so a query that legitimately matches only prose still returns
+    // something.
+    const bodyOnly = new Set();
+    if (ops.hasIdentifierMatch) {
+        const named = new Map();
+        for (const scope of meta.keys())
+            named.set(scope, ops.hasIdentifierMatch(scope));
+        if ([...named.values()].some(Boolean)) {
+            for (const [scope, ok] of named)
+                if (!ok)
+                    bodyOnly.add(scope);
+        }
+    }
+    for (const scope of bodyOnly) {
+        alsoMatched.push({ scope, bestId: meta.get(scope).bestId });
+        meta.delete(scope);
+    }
+    // The denominator must come from the scopes that actually rank, or a
+    // suppressed scope could still set the scale for everyone else.
+    globalMaxLex = 0;
+    for (const { maxLex } of meta.values())
+        if (maxLex > globalMaxLex)
+            globalMaxLex = maxLex;
+    for (const [scope, { lex }] of meta) {
+        const pr = ops.walk(scope, lex);
+        const candidates = new Set(lex.keys());
+        for (const [id, p] of pr)
+            if (p >= rescueFloor)
+                candidates.add(id);
+        for (const id of candidates) {
+            const lexN = globalMaxLex > 0 ? (lex.get(id) ?? 0) / globalMaxLex : 0;
+            const graph = pr.get(id) ?? 0;
+            const rankFactor = ops.rankFactor?.(scope, id) ?? 1;
+            const blended = (lexN + graphWeight * graph) * rankFactor;
+            if (blended > 0) {
+                candidatesWithComponents.push({
+                    id,
+                    scope,
+                    score: blended,
+                    lexical: lexN,
+                    graph,
+                    rankFactor,
+                });
+            }
+        }
+    }
+    const scoped = ops.collapseCandidates
+        ? [...ops.collapseCandidates(candidatesWithComponents)]
+        : candidatesWithComponents.map((candidate) => ({
+            id: candidate.id,
+            scope: candidate.scope,
+            score: candidate.score,
+        }));
+    const combined = combineComparableScopes(scoped);
+    return {
+        ranked: combined.ranked,
+        federated: combined.federated,
+        alsoMatched: [...alsoMatched, ...combined.alsoMatched],
+    };
+}
+//# sourceMappingURL=fuse.js.map

package/dist/ask/fuse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuse.js","sourceRoot":"","sources":["../../src/ask/fuse.ts"],"names":[],"mappings":"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"}

package/dist/ask/graphrank.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Graph-rank re-ranking for `graft ask` — the fix for lexical keyword-collision.
+ *
+ * Pure term-overlap ranking treats every node independently, so a node that
+ * merely shares a word with the query (a window "overlay" widget) can outrank
+ * the node the query is actually about (a scroll-"overlay" config) purely on
+ * word count. The graph knows better: the right node is the one wired into the
+ * cluster of code the query touches.
+ *
+ * This module runs personalized PageRank (random-walk-with-restart) over the
+ * wiring graph, seeded by the lexical scores. Mass concentrates on nodes that
+ * are edge-connected to the matched set; a lexically-matched but structurally
+ * isolated node keeps only its own restart mass and sinks. "Lexical proposes,
+ * graph disposes." Deterministic, $0, no embeddings — a lexical-seed →
+ * graph-rank pipeline, the established alternative to vector search for code.
+ */
+import type { GraphV1 } from "../graph/types.js";
+export interface PageRankOptions {
+    /** Restart probability — the mass that teleports back to the seed set each
+     * step. Higher keeps the walk closer to the seeds. 0.25 is the standard value. */
+    alpha?: number;
+    /** Power-iteration count. 25 is plenty to converge on graphs this size. */
+    iters?: number;
+    /** Restrict the walk to a subgraph: when present, an edge counts only when
+     * BOTH endpoints pass, and only passing ids can hold rank mass or seed
+     * weight. Seeds outside the filter are silently ignored (same as a seed
+     * naming a non-existent node). Omit for the full-graph walk (unchanged
+     * behavior). */
+    nodeFilter?: (id: string) => boolean;
+}
+/** Immutable graph topology consumed by the PageRank iteration. Preparing it
+ * separately lets a multi-scope query partition one large graph once, instead
+ * of rescanning every node and edge for every scope. */
+export interface PageRankTopology {
+    ids: ReadonlySet<string>;
+    adjacency: ReadonlyMap<string, readonly string[]>;
+}
+export type PageRankRunOptions = Pick<PageRankOptions, "alpha" | "iters">;
+/** Build independent PageRank topologies in one node pass and one edge pass.
+ * Edges crossing partitions are excluded, exactly like applying a nodeFilter
+ * for each partition independently. Returning `undefined` omits a node. */
+export declare function preparePageRankPartitions(graph: GraphV1, partitionOfId: (id: string) => string | undefined): Map<string, PageRankTopology>;
+/** Prepare one optionally filtered topology. Kept public for callers/tests that
+ * reuse the same graph across multiple seed sets. */
+export declare function preparePageRankTopology(graph: GraphV1, nodeFilter?: (id: string) => boolean): PageRankTopology;
+/**
+ * Personalized PageRank over the wiring graph.
+ *
+ * `seeds` maps node id → restart weight (a node's lexical score; only positive
+ * weights matter). The graph is treated as UNDIRECTED — for "understand this
+ * area" a callee is as relevant as a caller. Returns a score per node
+ * normalized so the top node is 1; nodes untouched by the walk are absent.
+ *
+ * Edges whose endpoints aren't both real nodes (e.g. an unresolved import
+ * module string) are ignored, so only genuine symbol-to-symbol wiring counts.
+ */
+export declare function personalizedPageRank(graph: GraphV1, seeds: Map<string, number>, opts?: PageRankOptions): Map<string, number>;
+/** Run PageRank on an already prepared topology. This is numerically identical
+ * to {@link personalizedPageRank}; it only removes repeated topology scans. */
+export declare function personalizedPageRankPrepared(topology: PageRankTopology, seeds: Map<string, number>, opts?: PageRankRunOptions): Map<string, number>;
+//# sourceMappingURL=graphrank.d.ts.map

package/dist/ask/graphrank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphrank.d.ts","sourceRoot":"","sources":["../../src/ask/graphrank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,MAAM,WAAW,eAAe;IAC9B;sFACkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;oBAIgB;IAChB,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC;AAED;;wDAEwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACnD;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC;AAkB1E;;2EAE2E;AAC3E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAChD,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAuB/B;AAED;qDACqD;AACrD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GACnC,gBAAgB,CAclB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,IAAI,GAAE,eAAoB,GACzB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAMrB;AAED;+EAC+E;AAC/E,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8CrB"}