Skip to content

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

feat(workspace): Fuse file candidates before span projection (#251)

Buseong Kimf6c411226fa0
diff --git a/src/graph/workspace.ts b/src/graph/workspace.ts
index 3a811327..d371586f 100644
--- a/src/graph/workspace.ts
+++ b/src/graph/workspace.ts
@@ -37,8 +37,16 @@ import {
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 { fileFirstRoundRobin } from "../ask/file-selection.js";
+import {
+ ask,
+ type AskHit,
+ type AskRankingMetadata,
+ type AskResult,
+} from "../ask/ask.js";
+import {
+ fileFirstRoundRobin,
+ roundRobinQueues,
+} from "../ask/file-selection.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";
@@ -183,6 +191,8 @@ export interface FederateAskOptions {
/** Narrow to one child (`repoA`) or a sub-scope within it (`repoA/backend`).
* A prefix matching NO child throws, listing the repos. */
in?: string;
+ /** @internal File-level child RRF plus an exact workspace baseline top lock. */
+ fileTopLock?: boolean;
}
interface ChildRun {
@@ -194,6 +204,11 @@ interface ChildRun {
/** Same, but over name+path ONLY (body dropped) — the match-STRENGTH signal.
* A body-only incidental collision has `coverageStrong === 0`. */
coverageStrong: number;
+ /** Exact baseline top-hit coverage used only to compute the workspace top lock. */
+ baselineCoverage: number;
+ baselineCoverageStrong: number;
+ /** Present only for the internal file-aware path. */
+ ranking?: AskRankingMetadata;
}
// STRONG_FLOOR / HIGH_FLOOR (a child federates if its top hit matched a
@@ -230,6 +245,7 @@ export function federateAsk(
): AskResult {
const wg = loadWorkspaceGraphs(root, override);
const limit = opts.limit ?? 8;
+ const fileTopLock = opts.fileTopLock ?? true;
// `--in` scopes to a single child (and, past the first segment, a sub-scope
// within it). A prefix naming no known child at all is a caller mistake.
@@ -263,12 +279,24 @@ export function federateAsk(
// The parent owns the final cross-repo ranking. Selecting inside each
// child would be undone by fusion and could truncate a hybrid list.
fileFirst: false,
+ fileComplement: fileTopLock,
+ includeRankingMetadata: fileTopLock,
});
} catch {
continue; // corrupt child, or a sub-scope --in matching nothing here
}
if (r.hits.length === 0) continue;
- runs.push({ child, hits: r.hits, coverage: r.coverage ?? 0, coverageStrong: r.coverageStrong ?? 0 });
+ const topGroup = r.ranking?.groups[0];
+ runs.push({
+ child,
+ hits: r.hits,
+ coverage: topGroup?.coverage ?? r.coverage ?? 0,
+ coverageStrong: topGroup?.coverageStrong ?? r.coverageStrong ?? 0,
+ baselineCoverage: r.ranking?.baselineCoverage ?? r.coverage ?? 0,
+ baselineCoverageStrong:
+ r.ranking?.baselineCoverageStrong ?? r.coverageStrong ?? 0,
+ ranking: r.ranking,
+ });
}
// Cross-child participation gate on match STRENGTH, not a lenient ratio.
@@ -289,9 +317,197 @@ export function federateAsk(
// every run (there is at most one) survives, matching a standalone child ask.
const gatedOut: { scope: string; bestId: string }[] = [];
const survivors: ChildRun[] = [];
+ const baselineSurvivors: ChildRun[] = [];
for (const run of runs) {
- if (onlyChild || run.coverageStrong >= STRONG_FLOOR || run.coverage >= HIGH_FLOOR) survivors.push(run);
- else gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, run.hits[0].pointer) });
+ const baselineEligible =
+ onlyChild ||
+ run.baselineCoverageStrong >= STRONG_FLOOR ||
+ run.baselineCoverage >= HIGH_FLOOR;
+ const fileEligible =
+ onlyChild ||
+ run.coverageStrong >= STRONG_FLOOR ||
+ run.coverage >= HIGH_FLOOR;
+ if (baselineEligible) baselineSurvivors.push(run);
+ // Distributed file evidence may admit a child, but the exact baseline
+ // top lock must never resurrect a child that the final stream calls gated
+ // out. The production survivor set is therefore the union of both gates;
+ // baselineSurvivors remains the strict baseline subset used only to choose the
+ // locked pointer.
+ if (baselineEligible || fileEligible) survivors.push(run);
+ else {
+ const best = run.ranking?.groups[0]?.hits[0] ?? run.hits[0];
+ gatedOut.push({ scope: run.child, bestId: prefixPointer(run.child, best.pointer) });
+ }
+ }
+
+ if (fileTopLock) {
+ type WorkspaceGroup = {
+ key: string;
+ child: string;
+ hits: AskHit[];
+ baselineHits: AskHit[];
+ };
+ const qualifyHit = (
+ child: string,
+ hit: AskHit,
+ score = hit.score,
+ scope = hit.scope ? `${child}/${hit.scope}` : child,
+ ): AskHit => ({
+ ...hit,
+ score,
+ scope,
+ pointer: prefixPointer(child, hit.pointer),
+ });
+ const sameHit = (a: AskHit, b: AskHit): boolean =>
+ a.kind === b.kind && a.pointer === b.pointer && a.title === b.title;
+
+ // Baseline workspace stream: reproduce the all-span RRF exactly so the
+ // final lock owns the same concrete pointer and fused score as the baseline.
+ const baselineDocs: ScopedDoc[] = [];
+ const baselineBack = new Map<
+ string,
+ { child: string; group: string; hit: AskHit }
+ >();
+ for (const run of baselineSurvivors) {
+ const entries = run.ranking?.baseline ?? run.hits.map((hit, index) => ({
+ group: `singleton:${index}`,
+ hit,
+ }));
+ entries.forEach((entry, index) => {
+ // Keep the legacy id shape so equal-score baseline ties remain exact.
+ const id = `${run.child} ${index}`;
+ const scope = entry.hit.scope
+ ? `${run.child}/${entry.hit.scope}`
+ : run.child;
+ baselineDocs.push({ id, scope, score: entry.hit.score });
+ baselineBack.set(id, {
+ child: run.child,
+ group: `${run.child}\0${entry.group}`,
+ hit: entry.hit,
+ });
+ });
+ }
+ const baselineFused = fuseScopes(baselineDocs);
+ const baselineTopRanked = baselineFused.ranked[0];
+ const baselineTopBack = baselineTopRanked
+ ? baselineBack.get(baselineTopRanked.id)
+ : undefined;
+ const baselineTop = baselineTopRanked && baselineTopBack
+ ? qualifyHit(
+ baselineTopBack.child,
+ baselineTopBack.hit,
+ baselineTopRanked.score,
+ baselineTopRanked.scope,
+ )
+ : undefined;
+
+ // File-aware workspace stream: exactly one leader per child/file (concepts stay
+ // singleton groups) participates in RRF. Span queues remain in a side map
+ // and cannot consume reciprocal-rank positions.
+ const fileDocs: ScopedDoc[] = [];
+ const fileBack = new Map<string, WorkspaceGroup>();
+ for (const run of survivors) {
+ const groups = run.ranking?.groups ?? run.hits.map((hit, index) => ({
+ key: `singleton:${index}`,
+ hits: [hit],
+ baselineHits: [hit],
+ coverage: 0,
+ coverageStrong: 0,
+ }));
+ groups.forEach((group, index) => {
+ const leader = group.hits[0];
+ if (!leader) return;
+ const id = `${run.child} file ${String(index).padStart(8, "0")}`;
+ const scope = leader.scope ? `${run.child}/${leader.scope}` : run.child;
+ const key = `${run.child}\0${group.key}`;
+ fileDocs.push({ id, scope, score: leader.score });
+ fileBack.set(id, {
+ key,
+ child: run.child,
+ hits: group.hits,
+ baselineHits: group.baselineHits ?? [leader],
+ });
+ });
+ }
+ const fileFused = fuseScopes(fileDocs);
+ const rankedGroups: WorkspaceGroup[] = fileFused.ranked.flatMap((ranked) => {
+ const group = fileBack.get(ranked.id);
+ if (!group) return [];
+ return [{
+ ...group,
+ // These spans are projections of one cross-child file document. Keep
+ // their public score on that same RRF scale; child-local tail scores are
+ // not comparable after workspace fusion and downstream re-sorting would
+ // otherwise silently undo the file ordering.
+ hits: group.hits.map((hit) =>
+ qualifyHit(
+ group.child,
+ hit,
+ ranked.score,
+ hit.scope ? `${group.child}/${hit.scope}` : group.child,
+ ),
+ ),
+ baselineHits: group.baselineHits.map((hit) => qualifyHit(group.child, hit)),
+ }];
+ });
+
+ let projectedGroups = rankedGroups;
+ if (baselineTop && baselineTopBack) {
+ const key = baselineTopBack.group;
+ const existing = rankedGroups.find((group) => group.key === key);
+ const baselineQueue = existing?.baselineHits ?? [baselineTop];
+ const projectedScore = existing?.hits[0]?.score ?? baselineTop.score;
+ const locked: WorkspaceGroup = existing
+ ? {
+ ...existing,
+ hits: [
+ baselineTop,
+ ...baselineQueue
+ .filter((hit) => !sameHit(hit, baselineTop))
+ .map((hit) => ({ ...hit, score: projectedScore })),
+ ],
+ }
+ : {
+ key,
+ child: baselineTopBack.child,
+ hits: [baselineTop],
+ baselineHits: [baselineTop],
+ };
+ projectedGroups = [
+ locked,
+ ...rankedGroups.filter((group) => group.key !== key),
+ ];
+ }
+
+ const hits = roundRobinQueues(
+ projectedGroups.map((group) => group.hits),
+ limit,
+ );
+ const unmatched = [...fileFused.alsoMatched, ...gatedOut];
+ const note = coverageNote(wg);
+ const result: AskResult = {
+ query,
+ mode: hits.length ? "lexical" : "empty",
+ hits,
+ };
+ if (hits.length) {
+ const lockedScope = baselineTop?.scope;
+ const federated = [
+ ...new Set([
+ ...(lockedScope ? [lockedScope] : []),
+ ...fileFused.federated,
+ ]),
+ ];
+ const federatedSet = new Set(federated);
+ result.scopes = {
+ federated,
+ alsoMatched: unmatched.filter((match) => !federatedSet.has(match.scope)),
+ };
+ } else {
+ result.note = `no matching nodes across ${wg.loaded.length} workspace repo(s) — try different words, or \`graft build\` at a child`;
+ }
+ if (note) result.note = result.note ? `${result.note}\n${note}` : note;
+ return result;
}
// Fuse the survivors' scope lists (within-child fusion is left untouched —
diff --git a/test/workspace.test.ts b/test/workspace.test.ts
index 3f71db21..89430bb5 100644
--- a/test/workspace.test.ts
+++ b/test/workspace.test.ts
@@ -127,7 +127,11 @@ test("workspace ask applies file-first selection after cross-repo fusion", async
});
try {
await buildWorkspace(p);
- const r = federateAsk(p, undefined, "quartz", { limit: 8, graphRank: false });
+ const r = federateAsk(p, undefined, "quartz", {
+ limit: 8,
+ graphRank: false,
+ fileTopLock: false,
+ });
const files = r.hits.map((hit) => hit.pointer.replace(/:L\d+-L\d+$/, ""));
const firstPass = [...new Set(files)];
@@ -144,6 +148,154 @@ test("workspace ask applies file-first selection after cross-repo fusion", async
}
});
+test("default file-aware fusion locks the exact workspace top before projecting span queues", async () => {
+ const p = workspaceFx({
+ repoA: {
+ "a.ts":
+ `export function quartzAlphaA() { return "quartz"; }\n` +
+ `export function quartzBetaA() { return "quartz"; }\n` +
+ `export function quartzGammaA() { return "quartz"; }\n`,
+ "b.ts": `export function quartzOmegaB() { return "quartz"; }\n`,
+ },
+ repoB: {
+ "a.ts":
+ `export function quartzAlphaC() { return "quartz"; }\n` +
+ `export function quartzBetaC() { return "quartz"; }\n`,
+ "d.ts": `export function quartzOmegaD() { return "quartz"; }\n`,
+ },
+ });
+ try {
+ await buildWorkspace(p);
+ const baseline = federateAsk(p, undefined, "quartz", {
+ limit: 8,
+ graphRank: false,
+ fileTopLock: false,
+ });
+ const a5 = federateAsk(p, undefined, "quartz", {
+ limit: 8,
+ graphRank: false,
+ source: true,
+ });
+ const explicitA5 = federateAsk(p, undefined, "quartz", {
+ limit: 8,
+ graphRank: false,
+ source: true,
+ fileTopLock: true,
+ });
+
+ assert.deepEqual(
+ a5,
+ explicitA5,
+ "the workspace default route is exactly the explicit file-aware configuration",
+ );
+
+ assert.deepEqual(
+ {
+ kind: a5.hits[0].kind,
+ title: a5.hits[0].title,
+ pointer: a5.hits[0].pointer,
+ score: a5.hits[0].score,
+ scope: a5.hits[0].scope,
+ },
+ {
+ kind: baseline.hits[0].kind,
+ title: baseline.hits[0].title,
+ pointer: baseline.hits[0].pointer,
+ score: baseline.hits[0].score,
+ scope: baseline.hits[0].scope,
+ },
+ "the parent lock reproduces the exact pre-file-RRF workspace top",
+ );
+
+ const files = a5.hits.map((hit) => hit.pointer.replace(/:L\d+-L\d+$/, ""));
+ const firstDuplicate = files.findIndex(
+ (file, index) => files.indexOf(file) !== index,
+ );
+ assert.equal(firstDuplicate, 4, "all four child/file documents emit before a tail span");
+ assert.equal(new Set(files.slice(0, firstDuplicate)).size, 4);
+ assert.ok(files.includes("repoA/a.ts"));
+ assert.ok(files.includes("repoB/a.ts"), "same relative paths in different children remain distinct");
+ assert.ok(files.slice(firstDuplicate).includes("repoA/a.ts"));
+ assert.ok(files.slice(firstDuplicate).includes("repoB/a.ts"));
+ const repoBTailScores = a5.hits
+ .filter((hit) => hit.pointer.replace(/:L\d+-L\d+$/, "") === "repoB/a.ts")
+ .map((hit) => hit.score);
+ assert.ok(repoBTailScores.length > 1, "fixture reaches a non-locked queue tail");
+ assert.equal(
+ new Set(repoBTailScores).size,
+ 1,
+ "every projected span in a non-locked file keeps the same cross-child RRF score",
+ );
+ const federated = new Set(a5.scopes?.federated ?? []);
+ assert.ok(
+ a5.scopes?.alsoMatched.every((match) => !federated.has(match.scope)),
+ "a locked or otherwise federated scope is never also reported as gated out",
+ );
+ assert.ok(
+ a5.hits.filter((hit) => hit.kind === "symbol").every((hit) => hit.code?.includes("function")),
+ "source mode inlines both file leaders and queue tails",
+ );
+ } finally {
+ rmSync(p, { recursive: true, force: true });
+ }
+});
+
+test("file-union admission preserves the workspace baseline top-lock survivor set", async () => {
+ const p = workspaceFx({
+ repoStrong: {
+ "strong.ts": `export function alphaBetaGamma() { return "alpha beta gamma"; }\n`,
+ },
+ repoDistributed: {
+ "distributed.ts":
+ `export function neutralOne() { return "alpha"; }\n` +
+ `export function neutralTwo() { return "beta"; }\n` +
+ `export function neutralThree() { return "gamma"; }\n`,
+ },
+ });
+ try {
+ await buildWorkspace(p);
+ const baseline = federateAsk(p, undefined, "alpha beta gamma", {
+ limit: 8,
+ graphRank: false,
+ fileTopLock: false,
+ });
+ assert.ok(baseline.hits.every((hit) => hit.scope?.startsWith("repoStrong")));
+ assert.ok(baseline.scopes?.alsoMatched.some((match) => match.scope === "repoDistributed"));
+
+ const a5 = federateAsk(p, undefined, "alpha beta gamma", {
+ limit: 8,
+ graphRank: false,
+ });
+ assert.deepEqual(
+ {
+ title: a5.hits[0].title,
+ pointer: a5.hits[0].pointer,
+ score: a5.hits[0].score,
+ scope: a5.hits[0].scope,
+ },
+ {
+ title: baseline.hits[0].title,
+ pointer: baseline.hits[0].pointer,
+ score: baseline.hits[0].score,
+ scope: baseline.hits[0].scope,
+ },
+ "the lock is computed from the original baseline participation gate",
+ );
+ assert.ok(
+ a5.hits.some((hit) => hit.scope?.startsWith("repoDistributed")),
+ "file union may admit a newly coherent child into ranks below the lock",
+ );
+ assert.ok(!a5.scopes?.alsoMatched.some((match) => match.scope === "repoDistributed"));
+ const excluded = new Set(a5.scopes?.alsoMatched.map((match) => match.scope) ?? []);
+ assert.ok(
+ a5.hits.every((hit) => !excluded.has(hit.scope?.split("/")[0] ?? "")),
+ "the baseline top lock never resurrects a child reported as gated out",
+ );
+ } finally {
+ rmSync(p, { recursive: true, force: true });
+ }
+});
+
test("ask inside a single child = standalone (no federation scopes)", async () => {
const p = workspaceFx(REPOS);
await buildWorkspace(p);
@@ -250,6 +402,17 @@ test("federated ask: a junk-body-token child is gated out of the ranking, into a
assert.ok(!titles.some((t) => t.startsWith("renderPanel")), `junk hit must NOT federate:\n${titles.join("\n")}`);
assert.ok(r.hits.every((h) => h.scope!.startsWith("repoA")), "only repoA federates");
assert.deepEqual(r.scopes?.alsoMatched.map((m) => m.scope), ["repoB"], "junk child reported in alsoMatched");
+ const a5 = federateAsk(p, undefined, "invoice total tax breakdown", {
+ limit: 8,
+ fileTopLock: true,
+ });
+ assert.ok(a5.hits.some((hit) => hit.title.startsWith("invoiceTotalTaxBreakdown")));
+ assert.ok(!a5.hits.some((hit) => hit.title.startsWith("renderPanel")));
+ assert.deepEqual(
+ a5.scopes?.alsoMatched.map((match) => match.scope),
+ ["repoB"],
+ "file-aware ranking gates on fresh top-file coverage instead of stale metadata",
+ );
rmSync(p, { recursive: true, force: true });
});