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): unify scope participation gate — single-graph fusion uses the match-strength gate, not the lenient ratio
Shrish Dwivedi62d7466603e7
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 65cf4eb8..9c7b56ae 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -345,7 +345,7 @@ function hasTerm(f: Map<string, number>, t: string): boolean {* a `kind:"file"` node contributes zero strength: its `name` is a basename (a* path component), not a symbol name, so a file whose basename happens to share* a query word is not a strong match. */-function strongShare(+export function strongShare(q: Map<string, number>,node: NodeV1,doc: { name: Map<string, number> },@@ -543,6 +543,20 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea}return out;},+ // The participation gate's match-STRENGTH signal, evaluated once per+ // scope on that scope's raw-lex top doc — same `strongShare`/+ // `matchedIdfShare` functions and per-scope idf `lex` (above) just+ // computed, so this reads the SAME strength `federateAsk` gates on+ // (see fuse.ts's STRONG_FLOOR/HIGH_FLOOR).+ strength: (s, id) => {+ const d = docsById.get(id);+ const si = idfOf.get(s);+ if (!d || !si) return { coverage: 0, coverageStrong: 0 };+ return {+ coverage: matchedIdfShare(q, [d.name, d.path, d.body], si.idf, si.dflt),+ coverageStrong: strongShare(q, d.n, d, si.idf, si.dflt),+ };+ },walk: (s, seeds) =>graphRank? personalizedPageRank(graph!, seeds, {diff --git a/src/ask/fuse.ts b/src/ask/fuse.tsindex 6d3583a9..8040779f 100644--- a/src/ask/fuse.ts+++ b/src/ask/fuse.ts@@ -11,11 +11,17 @@* with RRF — rank positions are comparable across corpora where raw scores* are not, so the tiny scope's best hit lands next to the huge scope's best.*- * Soft federation: a scope whose best score is far below the global best- * (< {@link PARTICIPATION_RATIO} ×) is probably an incidental word collision,- * not a second home for the query — it is left out of the fused order and- * reported in `alsoMatched` instead, so the output can say "also matched:- * docs/ — narrow with --in docs/" rather than diluting the pack.+ * 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 fused order+ * and reported in `alsoMatched` instead, so the output can say "also matched:+ * docs/ — narrow with --in docs/" rather than diluting the pack. The REAL+ * participation gate — used by both `rankScopesAndFuse` here and `federateAsk`+ * (workspace federation) — is the match-STRENGTH signal in {@link+ * STRONG_FLOOR}/{@link HIGH_FLOOR}: a scope's top hit must have matched a+ * query term in a NAME/PATH field, or have broad enough overall coverage to be+ * real even body-only. `fuseScopes`'s own {@link PARTICIPATION_RATIO} gate is+ * a separate, cruder ratio check that still runs internally as a+ * post-normalization safety net, not the primary defense.*//** One scored document, attributed to the ranking scope (path prefix, "" =@@ -44,9 +50,34 @@ export interface FusionResult {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. */+ * 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: ScopedDoc, b: ScopedDoc): number {@@ -137,6 +168,14 @@ export interface ScopeRankOps {/** Lexical scores for the scope's own docs (positive entries only),* computed against the scope's OWN corpus statistics. */lex(scope: string): Map<string, number>;+ /** The match-STRENGTH signal for the participation gate, evaluated at one+ * doc id within `scope` (always called on that scope's raw-lex top doc):+ * `coverage` is the idf-weighted matched share over name+path+body;+ * `coverageStrong` is the same over NAME only, with file-kind nodes+ * contributing zero (see `strongShare` in `src/ask/ask.ts`, the function+ * this must be backed by). Computed against the scope's own per-scope idf,+ * same as `lex`. */+ strength(scope: string, id: string): { coverage: number; coverageStrong: number };/** 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>;@@ -144,22 +183,23 @@ export interface ScopeRankOps {/*** Multi-scope orchestration for `ask`'s symbol ranking: for each scope, score- * lexically, gate by soft federation on the RAW lexical scores, walk the- * scope's subgraph, blend exactly like the single-scope path (`lexN ++ * lexically, gate by match STRENGTH (not a lenient ratio), 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.+ * The gate is the SAME two-floor signal `federateAsk` (workspace federation,+ * `src/graph/workspace.ts`) uses: a scope participates iff its top hit's+ * `coverageStrong` ≥ {@link STRONG_FLOOR} OR its `coverage` ≥+ * {@link HIGH_FLOOR}. It is evaluated here, on each scope's raw-lex top doc,+ * BEFORE normalization/walk/blend — gated-out scopes never enter the+ * walk/blend/fuse pipeline at all, they go straight to `alsoMatched` with+ * their best raw-lex doc id. (`fuseScopes`'s own internal ratio gate still+ * runs on the survivors' already-normalized input afterward, but since every+ * survivor's blended top is ~1.0 by construction, that gate is now just a+ * no-op safety net rather than the real gate — the real gate is this one.)*/export function rankScopesAndFuse(scopes: string[],@@ -167,18 +207,14 @@ export function rankScopesAndFuse(graphWeight: number,rescueFloor: number,): FusionResult {- // Pass 1: lexical scoring only, per scope — cheap, and needed up front to- // compute the global raw best the gate compares against.+ // Pass 1: lexical scoring only, per scope.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;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[] = [];@@ -195,7 +231,8 @@ export function rankScopesAndFuse(}if (maxLex <= 0) continue; // no positive-scoring doc — contributes nothing- if (maxLex < gate) {+ const { coverage, coverageStrong } = ops.strength(scope, bestId);+ if (coverageStrong < STRONG_FLOOR && coverage < HIGH_FLOOR) {alsoMatched.push({ scope, bestId });continue; // excluded from fusion — no walk, no blend}diff --git a/src/graph/workspace.ts b/src/graph/workspace.tsindex 69908b13..659f3f60 100644--- a/src/graph/workspace.ts+++ b/src/graph/workspace.ts@@ -34,7 +34,7 @@ import { edgeWalk, resolveSymbol, type Direction } from "./traverse.js";import { wiringPath } from "./write.js";import type { GraphV1 } from "./types.js";import { ask, type AskHit, type AskResult } from "../ask/ask.js";-import { fuseScopes, type ScopedDoc } from "../ask/fuse.js";+import { fuseScopes, STRONG_FLOOR, HIGH_FLOOR, type ScopedDoc } from "../ask/fuse.js";import { grepGraph, type GrepGroup, type GrepResult } from "../search/grep.js";import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";import { savingsFooter, type Savings } from "../context/savings.js";@@ -185,19 +185,13 @@ interface ChildRun {coverageStrong: number;}-/** A child federates if a query term hit a NAME/PATH field at all (any strength- * ≥ this) — 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. */-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 the prior 0.25×best 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). */-const HIGH_FLOOR = 0.5;+// STRONG_FLOOR / HIGH_FLOOR (a child federates if its top hit matched a+// query term in a NAME/PATH field ≥ STRONG_FLOOR, OR its overall name+path++// body coverage is broad enough to be real even body-only, ≥ HIGH_FLOOR) are+// defined ONCE in `../ask/fuse.js` and imported here — `rankScopesAndFuse`+// (single-graph multi-scope, `src/ask/fuse.ts`) gates on the exact same two+// floors, so the two paths that solve the identical "a weak scope must not+// federate beside a strong one" problem can never drift apart again./*** Federated `ask` across a workspace: run each child's own per-scope askdiff --git a/test/ask-fusion.test.ts b/test/ask-fusion.test.tsindex b476f084..2521a6ec 100644--- a/test/ask-fusion.test.ts+++ b/test/ask-fusion.test.ts@@ -10,6 +10,8 @@ import {rankScopesAndFuse,RRF_K,PARTICIPATION_RATIO,+ STRONG_FLOOR,+ HIGH_FLOOR,type ScopedDoc,type ScopeRankOps,} from "../src/ask/fuse.js";@@ -23,6 +25,8 @@ function scopeDocs(scope: string, scores: number[]): ScopedDoc[] {test("fusion constants match the spec", () => {assert.equal(RRF_K, 60);assert.equal(PARTICIPATION_RATIO, 0.25);+ assert.equal(STRONG_FLOOR, 0.1);+ assert.equal(HIGH_FLOOR, 0.5);});test("10-doc scope vs 2-doc scope: top-6 of the fused order contains both scopes' best", () => {@@ -104,20 +108,28 @@ test("deterministic under input shuffle, including score ties", () => {}});-// ── 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 {+// ── rankScopesAndFuse: the participation gate is the SAME two-floor+// match-STRENGTH signal `federateAsk` (workspace federation) uses — a scope+// participates iff its top hit's `coverageStrong` (name-only, file-kind-+// excluded idf share) ≥ STRONG_FLOOR OR its `coverage` (name+path+body idf+// share) ≥ HIGH_FLOOR. Gated-out scopes go to `alsoMatched`. This is NOT the+// old `PARTICIPATION_RATIO` (0.25 × raw-lexical-best) ratio — Task 5's+// investigation proved that ratio "far too lenient, leaks junk, worsens as+// corpus grows" for exactly this reason: a body-only incidental collision's+// raw lexical score can clear 0.25× of another scope's best even though it+// never matched a name/path field at all. These drive `rankScopesAndFuse` end+// to end (through its `lex`/`strength`/`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, ratio-based) gate still+// passes its tests — that gate is now just a no-op safety net once real+// scopes have already survived this one. ────────────────────────────────────++/** Scope "a": five docs with a real raw-lex spread (best = 10), always a+ * strong (name-matched) hit. Scope "b": one doc whose raw score is fixed but+ * whose match-strength (`coverage`/`coverageStrong`) is the probe knob — the+ * exact signal the real gate checks, decoupled from the raw-lex ratio the old+ * (buggy) gate used. No graph walk (PR rescue isn't what's under test). */+function makeOps(bStrength: { coverage: number; coverageStrong: number }): ScopeRankOps {const aLex = new Map([["a1", 10],["a2", 8],@@ -125,20 +137,20 @@ function makeOps(bRaw: number): ScopeRankOps {["a4", 4],["a5", 2],]);- const bLex = new Map([["b1", bRaw]]);+ const bLex = new Map([["b1", 3]]); // raw score irrelevant to the new gatereturn {lex: (s) => (s === "a" ? new Map(aLex) : new Map(bLex)),+ strength: (s) => (s === "a" ? { coverage: 1, coverageStrong: 1 } : bStrength),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");+test("rankScopesAndFuse: a scope with ONLY a body-token match (coverageStrong 0, coverage below HIGH_FLOOR) is excluded from ranked and reported in alsoMatched", () => {+ // b's top hit never matched a name/path field (coverageStrong = 0) and its+ // overall coverage (0.3) is well under HIGH_FLOOR (0.5) — an incidental+ // body-comment collision, same shape as the monorepo junk/ repro.+ const r = rankScopesAndFuse(["a", "b"], makeOps({ coverage: 0.3, coverageStrong: 0 }), 0.5, 0.05);+ assert.deepEqual(r.federated, ["a"], "b must not federate on a body-only, sub-floor match");assert.deepEqual(r.alsoMatched, [{ scope: "b", bestId: "b1" }]);assert.ok(r.ranked.every((d) => d.scope === "a"),@@ -151,10 +163,9 @@ test("rankScopesAndFuse: a scope with one weak RAW-lex match (ratio « 0.25) is);});-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");+test("rankScopesAndFuse: positive — a scope with a real NAME/PATH match (coverageStrong ≥ STRONG_FLOOR) federates", () => {+ const r = rankScopesAndFuse(["a", "b"], makeOps({ coverage: 0.2, coverageStrong: STRONG_FLOOR }), 0.5, 0.05);+ assert.deepEqual([...r.federated].sort(), ["a", "b"], "b federates at exactly the strength gate");assert.deepEqual(r.alsoMatched, []);assert.ok(r.ranked.some((d) => d.id === "b1"),@@ -162,8 +173,15 @@ test("rankScopesAndFuse: inverse — a scope whose RAW-lex ratio meets the gate);});-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);+test("rankScopesAndFuse: recall valve — body-only (coverageStrong 0) but BROAD (coverage ≥ HIGH_FLOOR) still federates", () => {+ const r = rankScopesAndFuse(["a", "b"], makeOps({ coverage: HIGH_FLOOR, coverageStrong: 0 }), 0.5, 0.05);+ assert.deepEqual([...r.federated].sort(), ["a", "b"], "a broad body-only match still federates via HIGH_FLOOR");+ assert.deepEqual(r.alsoMatched, []);+ assert.ok(r.ranked.some((d) => d.id === "b1"));+});++test("formatAsk: 'also matched … --in …' actually renders for a scope gated out on match strength", () => {+ const fusion = rankScopesAndFuse(["a", "b"], makeOps({ coverage: 0.3, coverageStrong: 0 }), 0.5, 0.05);const hits: AskHit[] = fusion.ranked.map((d) => ({kind: "symbol",title: d.id,diff --git a/test/ask.test.ts b/test/ask.test.tsindex b8bc3812..78549d25 100644--- a/test/ask.test.ts+++ b/test/ask.test.ts@@ -328,6 +328,87 @@ test("ask on a multi-scope repo: top hits federate both scopes, labeled, with a}});+/** Cross-seam repro (final-review bug): a monorepo-shaped single-graph repo+ * with two marker-carrying sub-scopes — `api/` has REAL symbols named for the+ * query terms; `junk/` has NO such symbol, only a body comment repeating ONE+ * of the two query terms ("gateway", never "timeout") — an incidental+ * single-token collision: `coverageStrong` 0 (no name/path match, file-kind+ * node) and `coverage` well under `HIGH_FLOOR` (the missing term's absence+ * dominates the idf-weighted share) — NOT a case the broad-coverage recall+ * valve is meant to rescue, which requires BOTH terms to appear somewhere.+ * The repetition is load-bearing: it inflates junk's RAW bm25 score to ~34%+ * of api's raw best — ABOVE the OLD `0.25 × raw-lexical-best` ratio gate+ * (the exact gate Task 5 proved "far too lenient, leaks junk" for workspace+ * federation) — so pre-fix, `rankScopesAndFuse` let `junk/` federate beside+ * `api/`'s genuine hits and RRF's rank-only math floated it to rank #2;+ * post-fix, the match-STRENGTH gate (same as `federateAsk`) correctly excludes+ * it regardless of the raw ratio. */+function crossSeamMonorepoFixture(): string {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-crossseam-"));+ mkdirSync(join(dir, "api"), { recursive: true });+ mkdirSync(join(dir, "junk"), { recursive: true });+ writeFileSync(join(dir, "api", "package.json"), `{ "name": "api", "version": "1.0.0" }\n`);+ writeFileSync(join(dir, "junk", "package.json"), `{ "name": "junk", "version": "1.0.0" }\n`);+ writeFileSync(+ join(dir, "api", "gateway.ts"),+ `/** Thrown when the upstream call exceeds the deadline. */\n` ++ `export class GatewayTimeout extends Error {\n` ++ ` constructor(public readonly ms: number) {\n` ++ ` super(\`gateway timeout after \${ms}ms\`);\n` ++ ` }\n` ++ `}\n\n` ++ `export function callUpstream(ms: number): void {\n` ++ ` if (ms > 5000) throw new GatewayTimeout(ms);\n` ++ `}\n\n` ++ `export function retryUpstream(attempts: number): void {\n` ++ ` for (let i = 0; i < attempts; i++) callUpstream(1000);\n` ++ `}\n\n` ++ `export class UpstreamClient {\n` ++ ` send(payload: string): string {\n return payload;\n }\n` ++ ` close(): void {}\n` ++ `}\n\n` ++ `export function buildClient(): UpstreamClient {\n return new UpstreamClient();\n}\n`,+ );+ writeFileSync(+ join(dir, "junk", "widget.ts"),+ `// gateway gateway gateway gateway gateway gateway gateway gateway gateway\n` ++ `// gateway gateway gateway gateway gateway gateway gateway gateway gateway\n` ++ `// gateway gateway gateway gateway gateway gateway gateway gateway gateway\n` ++ `// unrelated helper widget — nothing to do with upstream call handling at all.\n` ++ `export class Widget {\n` ++ ` render(): string {\n return "widget";\n }\n` ++ ` resize(w: number, h: number): void {}\n` ++ `}\n\n` ++ `export class Panel {\n layout(): void {}\n}\n\n` ++ `export function makeWidget(): Widget {\n return new Widget();\n}\n\n` ++ `export function makePanel(): Panel {\n return new Panel();\n}\n`,+ );+ return dir;+}++test("cross-seam fix: a monorepo scope with only a body-comment collision is gated to alsoMatched, not ranked ahead of the genuine scope", async () => {+ const dir = crossSeamMonorepoFixture();+ try {+ await buildGraph(dir);+ const r = ask(dir, "gateway timeout", { limit: 10 });+ assert.ok(+ !r.hits.some((h) => h.scope === "junk"),+ `junk/ must not appear in the ranked hits at all, got: ${r.hits.map((h) => `[${h.scope}] ${h.title}`).join(", ")}`,+ );+ assert.ok(r.hits.some((h) => h.scope === "api"), "api/'s genuine hits still rank");+ assert.ok(r.scopes, "fusion telemetry present");+ assert.ok(+ r.scopes!.alsoMatched.some((m) => m.scope === "junk"),+ "junk/ must be reported in alsoMatched instead",+ );+ const out = formatAsk(r);+ assert.match(out, /also matched: junk\/ — narrow with --in junk\//, `expected an alsoMatched footer, got:\n${out}`);+ assert.doesNotMatch(out, /\[junk\/\]/, "no junk/-labeled hit anywhere in the rendered output");+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+// ── `--in <path-prefix>`: filter docs before scoring ────────────────────────/** `prefix/docA.ts` + `prefix-sibling/docB.ts` — a plain `path.startsWith`