Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

fix(ask): participation gate applies to raw lexical scores — weak scopes stop federating junk

Shrish Dwivedi30a765a86732
diff --git a/src/ask/fuse.ts b/src/ask/fuse.ts
index e2d3dea7..6d3583a9 100644
--- a/src/ask/fuse.ts
+++ b/src/ask/fuse.ts
@@ -28,7 +28,10 @@ export interface ScopedDoc {
}
export interface FusionResult {
- /** fused order, best first; carries per-doc scope label + fused score in [0,1] */
+ /** 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[];
@@ -141,11 +144,22 @@ export interface ScopeRankOps {
/**
* Multi-scope orchestration for `ask`'s symbol ranking: for each scope, score
- * lexically, walk the scope's subgraph, blend exactly like the single-scope
- * path (`lexN + graphWeight·pr`, both per-scope-normalized; walk-rescued
- * nodes join above `rescueFloor`), then fuse all scopes' blended lists with
+ * lexically, gate by soft federation on the RAW lexical scores, walk the
+ * scope's subgraph, blend exactly like the single-scope path (`lexN +
+ * graphWeight·pr`, both per-scope-normalized; walk-rescued nodes join above
+ * `rescueFloor`), then fuse the surviving scopes' blended lists with
* {@link fuseScopes}. A scope with zero lexical matches contributes nothing
* (no seeds → no walk → no docs).
+ *
+ * The gate MUST run on raw (pre-normalization) lexical scores. `fuseScopes`'s
+ * own gate compares its input scores, but this function's input to
+ * `fuseScopes` is already per-scope-normalized (`lexN`, each scope's own max
+ * → ~1.0) — gating on THAT would make the 0.25×global-best participation gate
+ * vacuous: any scope with even one scoring doc, however weak, normalizes to
+ * the same ceiling as every other scope and always clears it. So the gate is
+ * applied here, before normalization, and gated-out scopes never enter the
+ * walk/blend/fuse pipeline at all — they go straight to `alsoMatched` with
+ * their best RAW-lex doc.
*/
export function rankScopesAndFuse(
scopes: string[],
@@ -153,13 +167,41 @@ export function rankScopesAndFuse(
graphWeight: number,
rescueFloor: number,
): FusionResult {
- const scoped: ScopedDoc[] = [];
+ // Pass 1: lexical scoring only, per scope — cheap, and needed up front to
+ // compute the global raw best the gate compares against.
+ const lexByScope = new Map<string, Map<string, number>>();
+ let globalRawBest = 0;
for (const scope of scopes) {
const lex = ops.lex(scope);
if (lex.size === 0) continue;
- const pr = ops.walk(scope, lex);
+ lexByScope.set(scope, lex);
+ for (const v of lex.values()) if (v > globalRawBest) globalRawBest = v;
+ }
+
+ const gate = PARTICIPATION_RATIO * globalRawBest;
+ const alsoMatched: FusionResult["alsoMatched"] = [];
+ const scoped: ScopedDoc[] = [];
+
+ for (const [scope, lex] of lexByScope) {
+ // Raw best (+ its doc id) for THIS scope, score desc / id asc — same
+ // tiebreak fuseScopes uses, so the reported bestId is deterministic.
let maxLex = 0;
- for (const v of lex.values()) if (v > maxLex) maxLex = v;
+ let bestId = "";
+ for (const [id, v] of lex) {
+ if (v > maxLex || (v === maxLex && id < bestId)) {
+ maxLex = v;
+ bestId = id;
+ }
+ }
+ if (maxLex <= 0) continue; // no positive-scoring doc — contributes nothing
+
+ if (maxLex < gate) {
+ alsoMatched.push({ scope, bestId });
+ continue; // excluded from fusion — no walk, no blend
+ }
+
+ // Pass 2: only surviving scopes pay for the graph walk + blend.
+ 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) {
@@ -168,5 +210,14 @@ export function rankScopesAndFuse(
if (blended > 0) scoped.push({ id, scope, score: blended });
}
}
- return fuseScopes(scoped);
+
+ // fuseScopes's own gate still runs on this (already-survivor, already-
+ // normalized) input — left as-is per its pure-test contract; it's now
+ // effectively a no-op safety net rather than the real gate.
+ const fused = fuseScopes(scoped);
+ return {
+ ranked: fused.ranked,
+ federated: fused.federated,
+ alsoMatched: [...alsoMatched, ...fused.alsoMatched],
+ };
}
diff --git a/test/ask-fusion.test.ts b/test/ask-fusion.test.ts
index 8bfd40a8..b476f084 100644
--- a/test/ask-fusion.test.ts
+++ b/test/ask-fusion.test.ts
@@ -5,7 +5,15 @@
*/
import { test } from "node:test";
import assert from "node:assert/strict";
-import { fuseScopes, RRF_K, PARTICIPATION_RATIO, type ScopedDoc } from "../src/ask/fuse.js";
+import {
+ fuseScopes,
+ rankScopesAndFuse,
+ RRF_K,
+ PARTICIPATION_RATIO,
+ type ScopedDoc,
+ type ScopeRankOps,
+} from "../src/ask/fuse.js";
+import { formatAsk, type AskHit, type AskResult } from "../src/ask/ask.js";
/** A scope's docs with per-scope-normalized-looking scores, best first. */
function scopeDocs(scope: string, scores: number[]): ScopedDoc[] {
@@ -95,3 +103,84 @@ test("deterministic under input shuffle, including score ties", () => {
assert.deepEqual(fuseScopes(shuffled), baseline, "same result regardless of input order");
}
});
+
+// ── rankScopesAndFuse: the participation gate must apply to RAW lexical
+// scores, not the per-scope-normalized blend. `rankScopesAndFuse` normalizes
+// each scope's lexical scores to ITS OWN max before blending, so if the gate
+// were checked on the blended input (as `fuseScopes` sees it), every scope
+// with even one scoring doc would normalize to ~1.0 and the 0.25×global-best
+// gate would never fire. These drive `rankScopesAndFuse` end to end (through
+// its `lex`/`walk` callback seam, the same seam `ask.ts` drives it through)
+// so a regression here is caught even if `fuseScopes`'s own (pure, post-
+// normalization) gate still passes its tests. ──────────────────────────────
+
+/** Scope "a": five docs with a real raw-lex spread (best = 10). Scope "b":
+ * one doc whose raw score is `bRaw` — the probe knob. No graph walk (PR
+ * rescue isn't what's under test). */
+function makeOps(bRaw: number): ScopeRankOps {
+ const aLex = new Map([
+ ["a1", 10],
+ ["a2", 8],
+ ["a3", 6],
+ ["a4", 4],
+ ["a5", 2],
+ ]);
+ const bLex = new Map([["b1", bRaw]]);
+ return {
+ lex: (s) => (s === "a" ? new Map(aLex) : new Map(bLex)),
+ walk: () => new Map(),
+ };
+}
+
+test("rankScopesAndFuse: a scope with one weak RAW-lex match (ratio « 0.25) is excluded from ranked and reported in alsoMatched", () => {
+ // b1 = 0.4, a's raw best = 10 → ratio 0.04, far under the 0.25 gate. Under
+ // the vacuous gate this junk match would normalize to 1.0 (it's its scope's
+ // own max) and federate, fusing at rank ~1-2 by RRF's rank-only math — this
+ // pins that it no longer does.
+ const r = rankScopesAndFuse(["a", "b"], makeOps(0.4), 0.5, 0.05);
+ assert.deepEqual(r.federated, ["a"], "b must not federate on a raw ratio of 0.04");
+ assert.deepEqual(r.alsoMatched, [{ scope: "b", bestId: "b1" }]);
+ assert.ok(
+ r.ranked.every((d) => d.scope === "a"),
+ "b's junk match must not appear anywhere in the fused order",
+ );
+ assert.deepEqual(
+ r.ranked.map((d) => d.id),
+ ["a1", "a2", "a3", "a4", "a5"],
+ "sole surviving scope passes through in raw score order",
+ );
+});
+
+test("rankScopesAndFuse: inverse — a scope whose RAW-lex ratio meets the gate still federates", () => {
+ // b1 = 2.5 = exactly 0.25 × 10 — the gate is inclusive.
+ const r = rankScopesAndFuse(["a", "b"], makeOps(2.5), 0.5, 0.05);
+ assert.deepEqual([...r.federated].sort(), ["a", "b"], "b federates at exactly the raw-lex gate");
+ assert.deepEqual(r.alsoMatched, []);
+ assert.ok(
+ r.ranked.some((d) => d.id === "b1"),
+ "b's doc appears in the fused order",
+ );
+});
+
+test("formatAsk: 'also matched … --in …' actually renders for a scope gated out on raw lex", () => {
+ const fusion = rankScopesAndFuse(["a", "b"], makeOps(0.4), 0.5, 0.05);
+ const hits: AskHit[] = fusion.ranked.map((d) => ({
+ kind: "symbol",
+ title: d.id,
+ pointer: d.id,
+ snippet: "",
+ score: d.score,
+ scope: d.scope,
+ }));
+ const scopes =
+ fusion.federated.length > 1 || fusion.alsoMatched.length > 0
+ ? { federated: fusion.federated, alsoMatched: fusion.alsoMatched }
+ : undefined;
+ const result: AskResult = { query: "weak-scope probe", mode: "lexical", hits, scopes };
+ const out = formatAsk(result);
+ assert.match(
+ out,
+ /also matched: b\/ — narrow with --in b\//,
+ `expected an "also matched" footer line for b/, got:\n${out}`,
+ );
+});