Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
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.tsindex 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.tsindex 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}`,+ );+});