Skip to content

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

perf(context): synthesize concept batches in parallel, and cut them on path hashes (#521)

Alex Matthewsff56c78ec2f1
diff --git a/src/cli.ts b/src/cli.ts
index 7c093eeb..5c82ed36 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -445,6 +445,11 @@ grouped(program.command("build"), GROUP.setup)
.option("--deep", "run the LLM pass: concept nodes (graft/*.md) + per-symbol summary/crux")
.option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py"); an extension with no parser is ignored with a warning that lists the supported set')
.option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")
+ .option(
+ "--synth-concurrency <n>",
+ "concept synthesis batches in flight at once during --deep (default 4). Separate from -j: " +
+ "each synthesis call carries a whole batch of summaries, not one file",
+ )
.option("--no-reuse", "re-parse every file instead of replaying unchanged ones from the extraction cache")
.option("--lsp", "add compiler-grade call edges via a language server if one is installed (opt-in, slower; e.g. rust-analyzer, clangd)")
.option("--allow-partial", "with --deep: exit 0 even when some files' summaries failed (default: a degraded meaning tier exits 1)")
@@ -493,6 +498,7 @@ grouped(program.command("build"), GROUP.setup)
reuse?: boolean;
lsp?: boolean;
allowPartial?: boolean;
+ synthConcurrency?: string;
includeDir?: string[];
onlyDir?: string[];
followSubmodules?: boolean;
@@ -517,6 +523,11 @@ grouped(program.command("build"), GROUP.setup)
console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);
process.exit(1);
}
+ const synthConcurrency = opts.synthConcurrency ? Math.max(1, Number(opts.synthConcurrency)) : undefined;
+ if (opts.synthConcurrency && !Number.isFinite(synthConcurrency)) {
+ console.error(`✗ --synth-concurrency must be a number, got "${opts.synthConcurrency}"`);
+ process.exit(1);
+ }
warnUnsupportedExtensions(opts.extensions);
// Persisted BEFORE the build itself runs, so this invocation's walks (and
// every later no-flag build / hooks refresh) see it identically — the
@@ -600,6 +611,7 @@ grouped(program.command("build"), GROUP.setup)
deep: !!deep,
extensions: opts.extensions,
concurrency,
+ synthConcurrency,
childConfig: cliConfig(),
override: buildGlobalDir,
includeDirs: opts.includeDir,
@@ -617,6 +629,7 @@ grouped(program.command("build"), GROUP.setup)
const c = await engine.init(dir, {
extensions: opts.extensions,
onlyDirs,
+ synthConcurrency,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "summarize" ? "reading" : "writing"} concepts ${index + 1}/${total}: ${file.slice(0, 40).padEnd(40)}`,
diff --git a/src/context/batches.ts b/src/context/batches.ts
new file mode 100644
index 00000000..c4dd1075
--- /dev/null
+++ b/src/context/batches.ts
@@ -0,0 +1,145 @@
+/**
+ * How the concept pass cuts its synthesis batches, and what each one is cached under.
+ *
+ * Every batch is one LLM call, and its result is cached under a key derived from the
+ * files the call saw. So a boundary that moves is a re-synthesis — a metered call the
+ * user pays for again — which makes the cut rule, not the call itself, the thing that
+ * decides what a `--deep` build costs after an edit.
+ *
+ * The cut is a function of the file PATHS: a batch ends at the first file whose own
+ * path hash matches a mask, never at a size. Cut by running size, one summary growing
+ * by a sentence moves every later boundary, every later batch lands on a different set
+ * of files, and so every later key changes and the next build re-synthesizes most of
+ * the graph. Sizes are consulted in exactly two places, neither of which is a
+ * boundary: the stride (how many files to expect per batch) and a batch that
+ * overshoots the budget anyway, which is cut inside itself.
+ */
+import { contentHash } from "../util/id.js";
+import type { FileSummary } from "../ai/synthesize.js";
+
+/** Char budget of summary text per synthesis call (keeps each call in-context). */
+export const BATCH_CHAR_BUDGET = 48_000;
+
+/**
+ * Smallest share of the stride a batch may be cut at: a mask hit sooner than this is
+ * ignored, so a lucky pair of adjacent paths cannot turn a repo into one call per two
+ * files. An eighth keeps a stray hit to one small batch in a long tail of them,
+ * without moving a well-behaved boundary at all.
+ */
+const BATCH_MIN_SHARE = 1 / 8;
+
+/** One synthesis call: the batch of summaries it sees, and the key it is cached under. */
+export interface SynthesisBatch {
+ files: FileSummary[];
+ /** Stable key for this batch: its files and their content hashes. */
+ key: string;
+}
+
+/**
+ * The batches phase 2 calls, in the order the merge consumes them. `summaries` is
+ * expected path-sorted, which is what makes the plan reproducible.
+ *
+ * Exported together with their cache keys because those keys are the phase's whole
+ * cost model: a boundary that moves is a re-synthesis. How these keys survive an edit
+ * is what the batching tests pin down.
+ */
+export function planSynthesis(summaries: FileSummary[], hashByPath: ReadonlyMap<string, string>): SynthesisBatch[] {
+ return batchSummaries(summaries).map((files) => ({ files, key: batchKey(files, hashByPath) }));
+}
+
+/**
+ * Cut the per-file summaries into batches, each under `budget` unless it is a single
+ * file too big for one.
+ *
+ * A batch ENDS at the first file whose own path hash matches a mask, past a small
+ * floor (see {@link BATCH_MIN_SHARE}) — so the end of a batch is decided by the files
+ * inside it and by nothing else, and an edit to one file cannot move a boundary it is
+ * not part of.
+ */
+export function batchSummaries(files: FileSummary[], budget: number = BATCH_CHAR_BUDGET): FileSummary[][] {
+ if (files.length === 0) return [];
+ const stride = filesPerBatch(files, budget);
+ const minFiles = Math.max(1, Math.round(stride * BATCH_MIN_SHARE));
+ const batches: FileSummary[][] = [];
+ let cur: FileSummary[] = [];
+ let size = 0;
+ for (const f of files) {
+ cur.push(f);
+ size += summaryChars(f);
+ if (cur.length >= minFiles && isBoundary(f.path, stride)) {
+ batches.push(...withinBudget(cur, size, budget));
+ cur = [];
+ size = 0;
+ }
+ }
+ if (cur.length > 0) batches.push(...withinBudget(cur, size, budget));
+ return batches;
+}
+
+/** Chars a file costs its batch: its label, its summary, and the blank line the
+ * synthesizer's prompt puts between entries. */
+function summaryChars(f: FileSummary): number {
+ return f.path.length + f.summary.length + 8;
+}
+
+/**
+ * Files to aim for per batch: as many as fit in roughly one budget's worth of summary
+ * text, rounded DOWN to a power of two.
+ *
+ * The mean is the one statistic that can size a batch across repos whose summaries
+ * differ in length by an order of magnitude. The power of two is what makes it safe
+ * to derive from a number that moves: editing one summary of n shifts the mean by
+ * ~1/n, and the ladder is wide enough that a shift that small cannot re-stride —
+ * while re-striding is the one change that does move every boundary, so it should
+ * take a real change in the repo to happen.
+ */
+function filesPerBatch(files: FileSummary[], budget: number): number {
+ const total = files.reduce((n, f) => n + summaryChars(f), 0);
+ const mean = Math.max(1, Math.round(total / files.length));
+ return 2 ** Math.floor(Math.log2(Math.max(1, Math.floor(budget / mean))));
+}
+
+/** Does a batch end here? One path in `stride` does, by its own hash. */
+function isBoundary(path: string, stride: number): boolean {
+ if (stride <= 1) return true;
+ return parseInt(contentHash(path).slice(-8), 16) % stride === 0;
+}
+
+/** A batch that outgrew the budget on its own is cut by size, greedily. Overshooting
+ * takes a longer gap between two mask hits than the stride asks for, so it is the
+ * tail rather than the rule — and it is cut inside that one batch, which is why a
+ * split is a local edit and not a re-plan. A single file over the budget is left
+ * whole: the synthesizer truncates its input either way, and half a file is not a
+ * batch. */
+function withinBudget(batch: FileSummary[], size: number, budget: number): FileSummary[][] {
+ return size <= budget || batch.length < 2 ? [batch] : batchBySize(batch, budget);
+}
+
+/** Greedily pack file summaries into batches under a char budget (≥1 file each). */
+function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {
+ const batches: FileSummary[][] = [];
+ let cur: FileSummary[] = [];
+ let size = 0;
+ for (const f of files) {
+ const len = summaryChars(f);
+ if (cur.length > 0 && size + len > budget) {
+ batches.push(cur);
+ cur = [];
+ size = 0;
+ }
+ cur.push(f);
+ size += len;
+ }
+ if (cur.length > 0) batches.push(cur);
+ return batches;
+}
+
+/** Stable key for a batch: its files and their content hashes. */
+function batchKey(batch: FileSummary[], hashByPath: ReadonlyMap<string, string>): string {
+ return contentHash(
+ batch
+ .map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)
+ .sort()
+ .join("\n"),
+ );
+}
diff --git a/src/context/build.ts b/src/context/build.ts
index 957289c5..779bb856 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -6,7 +6,9 @@
* 2. Summarize each file to prose (one LLM call per file, cached by content hash).
* 3. Synthesize a CURATED node set from the labeled summaries (the synthesizer
* decides granularity: subsystems, notable files, and concepts). This is
- * one LLM call per batch of summaries; batches are cached by content.
+ * one LLM call per batch of summaries; the batches are independent, so they
+ * run concurrently, and each is cached by content. Where the batches are cut,
+ * and why that decides what the next build costs, is `./batches.ts`.
* 4. Resolve node names → slugs and links → edges; attribute each node to its
* source files so staleness stays exact.
* 5. Write one markdown file per node (preserving human notes) + a manifest.
@@ -23,6 +25,7 @@ import { readFollowNestedRepos, readFollowSubmodules, readIncludeDirs } from "..
import type { Summarizer } from "../ai/summarize.js";
import { LlmFailureGate } from "../ai/failure.js";
import type { FileSummary, SynthNode, Synthesizer } from "../ai/synthesize.js";
+import { planSynthesis, type SynthesisBatch } from "./batches.js";
import {
CACHE_DIR,
MANIFEST_VERSION,
@@ -47,8 +50,13 @@ export const CODE_EXTENSIONS = [
".cs", ".swift", ".sql", ".sh", ".proto",
];
-/** Char budget of summary text per synthesis call (keeps each call in-context). */
-const BATCH_CHAR_BUDGET = 48_000;
+/**
+ * Synthesis calls in flight at once. Small on purpose, and separate from phase 1's
+ * `-j`: there each call is one small file summary, here each is a whole batch of
+ * summaries — a long, expensive request, of which a big repo has a handful rather
+ * than hundreds.
+ */
+const DEFAULT_SYNTH_CONCURRENCY = 4;
export interface BuildProgress {
phase: "summarize" | "synthesize" | "write";
@@ -72,6 +80,9 @@ export interface BuildOptions {
synthesizer: Synthesizer;
/** Files summarized in parallel during phase 1. Default 8. Raised via `graft build -j`. */
concurrency?: number;
+ /** Synthesis batches synthesized in parallel during phase 2. Default
+ * {@link DEFAULT_SYNTH_CONCURRENCY}. Raised via `graft build --synth-concurrency`. */
+ synthConcurrency?: number;
onProgress?: (info: BuildProgress) => void;
}
@@ -85,10 +96,12 @@ export interface BuildResult {
links: number;
errors: string[];
/** Files whose summary call failed, and files never attempted once the pass gave
- * up — reported as data so the CLI can exit non-zero without reading messages (#127). */
+ * up — reported as data so the CLI can exit non-zero without reading messages (#127).
+ * A unit is a file in phase 1 and a whole batch of them in phase 2, and the
+ * counts cover both: the failure gate is shared. */
failedFiles: number;
skippedFiles: number;
- /** Why the summarize phase stopped early, when it did. */
+ /** Why the LLM passes stopped early, when they did. */
fatal?: string;
}
@@ -143,6 +156,14 @@ interface NodeDraft {
links: Map<string, NodeLink>; // "to|relation" → link
}
+/** What one synthesis batch ended up contributing, for the per-batch log line. */
+interface BatchOutcome {
+ nodes: SynthNode[];
+ /** Served from the cache, so no call was made for it. */
+ cached: boolean;
+ state: "ok" | "failed" | "skipped";
+}
+
export async function buildContext(dir: string, opts: BuildOptions): Promise<BuildResult> {
const root = resolve(dir);
const outDir = contextDirFor(root, opts.contextDir);
@@ -241,35 +262,86 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
.filter((w): w is FileWork & { summary: string } => Boolean(w.summary))
.map((w) => ({ path: w.rel, summary: w.summary }))
.sort((a, b) => a.path.localeCompare(b.path));
- const batches = batchBySize(summarized, BATCH_CHAR_BUDGET);
+ const batches = planSynthesis(summarized, hashByPath);
result.batches = batches.length;
- const synthNodes: SynthNode[] = [];
- for (let b = 0; b < batches.length; b++) {
- opts.onProgress?.({ phase: "synthesize", index: b, total: batches.length, file: `batch ${b + 1}` });
- const key = batchKey(batches[b], hashByPath);
- let nodes = cache.synth[key];
+ /**
+ * One batch's synthesis, cached and failure-gated exactly as phase 1 is: a cache
+ * hit is served even once the gate has closed (it costs nothing), only the call
+ * is skipped.
+ */
+ async function synthesizeBatch(batch: SynthesisBatch, b: number): Promise<BatchOutcome> {
+ let nodes = cache.synth[batch.key];
// An empty array is a miss, not a hit: caching [] made a silent empty
// synthesis permanent, the same trap #177 closed for the meaning pass (#129).
- const cached = Array.isArray(nodes) && nodes.length > 0;
- if (!cached) {
- nodes = await opts.synthesizer.synthesize(batches[b]);
- if (nodes.length > 0) cache.synth[key] = nodes;
- else delete cache.synth[key];
+ if (Array.isArray(nodes) && nodes.length > 0) return { nodes, cached: true, state: "ok" };
+ if (gate.stopped) {
+ gate.skip();
+ return { nodes: [], cached: false, state: "skipped" };
}
- const links = nodes.reduce((n, node) => n + node.links.length, 0);
- console.error(
- ` synthesis batch ${b + 1}/${batches.length}: ${nodes.length} nodes, ${links} links${cached ? " (cached)" : ""}`,
- );
- synthNodes.push(...nodes);
+ try {
+ nodes = await opts.synthesizer.synthesize(batch.files);
+ } catch (err) {
+ // Recorded, not thrown. A provider that has stopped serving fails every
+ // batch the same way, so the gate turns the first of those into a loud
+ // fatal and the rest into skipped calls, and the CLI already reports a
+ // concept pass with errors as a degraded meaning tier. Rethrowing instead
+ // would write no graph at all and leave the synthesis cache unsaved, so the
+ // next run would re-synthesize every batch that did work.
+ const message = errMsg(err);
+ result.errors.push(`synthesis batch ${b + 1}/${batches.length}: ${message}`);
+ gate.record(message);
+ return { nodes: [], cached: false, state: "failed" };
+ }
+ if (nodes.length > 0) cache.synth[batch.key] = nodes;
+ else delete cache.synth[batch.key];
+ gate.succeeded();
+ return { nodes, cached: false, state: "ok" };
}
+
+ // A batch is an independent unit of work — its call sees only its own summaries,
+ // and nothing is merged until every call is in (phase 3) — so the batches run
+ // concurrently, the way phase 1's per-file calls already do. The slow part is
+ // the round-trip, and a big repo otherwise serializes every one of them.
+ //
+ // Results are collected in BATCH order, whatever order the calls finish in.
+ // That is what makes this safe: the merge below is order-sensitive (first name
+ // registered wins, longest summary wins), so consuming batches as they completed
+ // would make the graph a function of network timing, and two builds of the same
+ // repo could disagree.
+ let synthesized = 0;
+ const outcomes = await mapWithConcurrency(batches, Math.max(1, opts.synthConcurrency ?? DEFAULT_SYNTH_CONCURRENCY), async (batch, b): Promise<BatchOutcome> => {
+ const outcome = await synthesizeBatch(batch, b);
+ // Reported on completion, like the crux pass (`graph/enrich.ts`): with several
+ // calls in flight the next batch is not the one that is running, so `index`
+ // counts finished batches and `file` names the one that just landed. The CLI
+ // prints them as one overwritten line, which only reads as progress if the
+ // counter never goes backwards.
+ opts.onProgress?.({ phase: "synthesize", index: synthesized++, total: batches.length, file: `batch ${b + 1}` });
+ return outcome;
+ });
+
+ // One log line per batch, in batch order: printed as the calls land it would
+ // report which call was fastest, which is noise on a run whose output does not
+ // depend on how the calls interleaved.
+ const synthNodes: SynthNode[] = [];
+ for (const [b, out] of outcomes.entries()) {
+ const links = out.nodes.reduce((n, node) => n + node.links.length, 0);
+ const note = out.cached ? " (cached)" : out.state === "failed" ? " (failed)" : out.state === "skipped" ? " (skipped)" : "";
+ console.error(` synthesis batch ${b + 1}/${batches.length}: ${out.nodes.length} nodes, ${links} links${note}`);
+ synthNodes.push(...out.nodes);
+ }
+ // The gate is shared with phase 1, so these counts now cover both LLM passes.
+ result.failedFiles = gate.failed;
+ result.skippedFiles = gate.skipped;
+ result.fatal = gate.fatal;
+
// Drop cache entries for batches we no longer produce, so it can't grow forever.
// Skip empty arrays so a failed batch is retried on the next --deep, not frozen.
cache.synth = Object.fromEntries(
- batches.flatMap((batch) => {
- const k = batchKey(batch, hashByPath);
- const v = cache.synth[k];
- return v && v.length > 0 ? [[k, v] as [string, SynthNode[]]] : [];
+ batches.flatMap(({ key }) => {
+ const v = cache.synth[key];
+ return v && v.length > 0 ? [[key, v] as [string, SynthNode[]]] : [];
}),
);
saveCache(outDir, cache);
@@ -373,35 +445,6 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
return result;
}
-/** Greedily pack file summaries into batches under a char budget (≥1 file each). */
-function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {
- const batches: FileSummary[][] = [];
- let cur: FileSummary[] = [];
- let size = 0;
- for (const f of files) {
- const len = f.path.length + f.summary.length + 8;
- if (cur.length > 0 && size + len > budget) {
- batches.push(cur);
- cur = [];
- size = 0;
- }
- cur.push(f);
- size += len;
- }
- if (cur.length > 0) batches.push(cur);
- return batches;
-}
-
-/** Stable key for a batch: its files and their content hashes. */
-function batchKey(batch: FileSummary[], hashByPath: Map<string, string>): string {
- return contentHash(
- batch
- .map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)
- .sort()
- .join("\n"),
- );
-}
-
function registerName(table: Map<string, string>, name: string, slug: string): void {
const key = name.trim().toLowerCase();
if (key && !table.has(key)) table.set(key, slug);
diff --git a/src/engine.ts b/src/engine.ts
index 01216cf8..74270a12 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -31,6 +31,8 @@ export interface InitOptions {
extensions?: string[];
/** Repo-relative directory prefixes to limit the concept pass (`--only-dir`). */
onlyDirs?: string[];
+ /** Max concept synthesis batches in flight at once. Default 4. */
+ synthConcurrency?: number;
/** Progress callback for long builds. */
onProgress?: (info: BuildProgress) => void;
}
@@ -66,6 +68,7 @@ export class Graft {
contextDir: this.cfg.contextDir,
extensions: opts.extensions,
onlyDirs: opts.onlyDirs,
+ synthConcurrency: opts.synthConcurrency,
model: this.modelLabel(),
summarizer: this.summarizer(),
synthesizer: this.synthesizer(),
diff --git a/src/graph/workspace-cli.ts b/src/graph/workspace-cli.ts
index 09755639..f428fe6c 100644
--- a/src/graph/workspace-cli.ts
+++ b/src/graph/workspace-cli.ts
@@ -29,6 +29,8 @@ export interface WorkspaceBuildOptions {
deep: boolean;
extensions?: string[];
concurrency?: number;
+ /** Max concept synthesis batches in flight per child (default 4). */
+ synthConcurrency?: number;
/** Provider/model/key config for child builds — WITHOUT any contextDir
* override, so each child writes to its own `<child>/graft/`. */
childConfig: EngineConfig;
@@ -70,7 +72,7 @@ export async function runWorkspaceBuild(root: string, opts: WorkspaceBuildOption
patchBuildConfig(childDir, childConfigPatch);
}
const engine = new Graft({ ...opts.childConfig, contextDir: undefined });
- if (opts.deep) await engine.init(childDir, { extensions: opts.extensions });
+ if (opts.deep) await engine.init(childDir, { extensions: opts.extensions, synthConcurrency: opts.synthConcurrency });
const g = await engine.graph(childDir, { llm: opts.deep, concurrency: opts.concurrency });
console.log(`✓ ${childName}/: ${g.nodes} nodes, ${g.edges} edges, ${g.cards} cards [${g.languages.join(", ")}]`);
for (const e of g.errors) console.error(`✗ ${childName}/: ${e}`);
diff --git a/test/context-batch-stability.test.ts b/test/context-batch-stability.test.ts
new file mode 100644
index 00000000..87239f9f
--- /dev/null
+++ b/test/context-batch-stability.test.ts
@@ -0,0 +1,215 @@
+/**
+ * Where the concept pass cuts its synthesis batches, and what that costs
+ * (`src/context/batches.ts`).
+ *
+ * Every batch is cached under a key derived from the files it holds, so a boundary
+ * that moves is a re-synthesis — a metered LLM call the user pays for again. Cut by
+ * running size (which is what this replaces) one summary growing by a few hundred
+ * characters moved every later boundary, so the next build after any edit
+ * re-synthesized most of the graph. These tests pin the property that replaced it:
+ * the plan is a function of the file PATHS, so only the batches around a change can
+ * move.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildContext } from "../src/context/build.js";
+import { BATCH_CHAR_BUDGET, planSynthesis, type SynthesisBatch } from "../src/context/batches.js";
+import { contentHash } from "../src/util/id.js";
+import { tmpRepo, PassthroughSummarizer } from "./helpers.js";
+import type { FileSummary, Synthesizer } from "../src/index.js";
+
+const FILES = 200;
+/** Summary length per file. ~2k is what a real per-file summary runs to, and it
+ * puts the stride at 16 files, so a 200-file repo is a dozen-odd batches. */
+const SUMMARY_CHARS = 2000;
+/** How much one edited file's summary changes by. Deliberately MORE than one file's
+ * summary: under a size-driven cut, a change smaller than that cannot move a
+ * boundary at all, and a test that cannot tell the two rules apart is not a guard
+ * against the regression. */
+const EDIT_CHARS = SUMMARY_CHARS + 2500;
+
+function fileBody(i: number, chars = SUMMARY_CHARS): string {
+ return `export const v${i} = ${i};\n// ${"x".repeat(chars)}\n`;
+}
+
+/** A repo of numbered files, so the path-sorted order is the numeric order. */
+function makeRepo(tag: string, count = FILES): string {
+ const dir = tmpRepo(tag);
+ mkdirSync(join(dir, "src"), { recursive: true });
+ for (let i = 0; i < count; i++) {
+ writeFileSync(join(dir, "src", `mod-${String(i).padStart(3, "0")}.ts`), fileBody(i));
+ }
+ return dir;
+}
+
+/** The plan for a repo as it stands: cache key → the paths in that batch. */
+function planOf(dir: string): Map<string, string[]> {
+ const summaries: FileSummary[] = [];
+ const hashByPath = new Map<string, string>();
+ for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {
+ const rel = `src/${name}`;
+ const code = readFileSync(join(dir, rel), "utf8");
+ summaries.push({ path: rel, summary: code });
+ hashByPath.set(rel, contentHash(code));
+ }
+ return new Map(planSynthesis(summaries, hashByPath).map((b: SynthesisBatch) => [b.key, b.files.map((f) => f.path)]));
+}
+
+/**
+ * The invariant: re-planning is LOCAL. A batch's files only change if a boundary
+ * appeared or disappeared next to the change, so the batches whose keys move are
+ * the one the change lands in and the two either side of it — and nothing further
+ * out. A size-driven cut breaks this for every batch after the change; a rule that
+ * re-strides on a changed mean breaks it for all of them.
+ *
+ * `touched` may or may not exist in `before` (a removal, an insertion), so the
+ * batches it can disturb are found by bracketing its place in the path order.
+ */
+function assertLocalReplan(before: Map<string, string[]>, after: Map<string, string[]>, touched: string): void {
+ const order = [...before.keys()];
+ const lastBefore = [...order].reverse().find((k) => before.get(k)![before.get(k)!.length - 1] < touched);
+ const at = lastBefore === undefined ? 0 : order.indexOf(lastBefore);
+ const near = order.slice(Math.max(0, at - 1), at + 2);
+ const neighbourhood = new Set(near.flatMap((k) => before.get(k)!));
+
+ const invalidated = order.filter((k) => !after.has(k));
+ const fresh = [...after.keys()].filter((k) => !before.has(k));
+ for (const k of invalidated) {
+ assert.ok(near.includes(k), `${invalidated.length} batches were invalidated, outside the ones holding ${touched}`);
+ }
+ for (const k of fresh) {
+ for (const path of after.get(k)!) {
+ assert.ok(
+ neighbourhood.has(path) || path === touched,
+ `${path} landed in a new batch well away from ${touched}`,
+ );
+ }
+ }
+ assert.ok(
+ invalidated.length + fresh.length <= 3,
+ `one change at ${touched} moved ${invalidated.length + fresh.length} of ${order.length} batches; ` +
+ `a size-driven cut moves the rest`,
+ );
+}
+
+const chars = (batch: SynthesisBatch): number =>
+ batch.files.reduce((n, f) => n + f.path.length + f.summary.length + 8, 0);
+
+test("a one-file edit re-plans only the batch that holds it", () => {
+ const dir = makeRepo("batch-edit");
+ try {
+ const before = planOf(dir);
+ assert.ok(before.size >= 8, `need several batches for this to say anything, got ${before.size}`);
+
+ // One rewritten file, whose summary is a good deal longer than it was.
+ const touched = "src/mod-100.ts";
+ writeFileSync(join(dir, touched), fileBody(100, EDIT_CHARS));
+
+ const after = planOf(dir);
+ assertLocalReplan(before, after, touched);
+ assert.equal(
+ [...before.keys()].filter((k) => !after.has(k)).length,
+ 1,
+ "a summary that changed must not disturb the batch after it, or the next one either",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("adding a file re-plans only the batches around it", () => {
+ const dir = makeRepo("batch-add");
+ try {
+ const before = planOf(dir);
+ // Sorts between mod-100 and mod-101, so a size-driven cut would push every
+ // boundary after it along — which is the cost this removes.
+ const added = "src/mod-100z.ts";
+ writeFileSync(join(dir, added), fileBody(0));
+
+ assertLocalReplan(before, planOf(dir), added);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("removing a file re-plans only the batches around it", () => {
+ const dir = makeRepo("batch-remove");
+ try {
+ const before = planOf(dir);
+ const gone = "src/mod-042.ts";
+ rmSync(join(dir, gone));
+
+ assertLocalReplan(before, planOf(dir), gone);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("every batch stays under the char budget unless it is one oversized file", () => {
+ const dir = makeRepo("batch-budget");
+ try {
+ const summaries: FileSummary[] = [];
+ const hashByPath = new Map<string, string>();
+ for (const name of readdirSync(join(dir, "src")).sort((a, b) => a.localeCompare(b))) {
+ const rel = `src/${name}`;
+ summaries.push({ path: rel, summary: readFileSync(join(dir, rel), "utf8") });
+ hashByPath.set(rel, "h");
+ }
+ for (const batch of planSynthesis(summaries, hashByPath)) {
+ assert.ok(
+ batch.files.length === 1 || chars(batch) <= BATCH_CHAR_BUDGET,
+ `a ${batch.files.length}-file batch of ${chars(batch)} chars is over the ${BATCH_CHAR_BUDGET} budget`,
+ );
+ }
+ // One file bigger than the whole budget is its own batch rather than a
+ // truncated neighbour's problem.
+ const huge: FileSummary[] = [...summaries, { path: "src/huge.ts", summary: "x".repeat(BATCH_CHAR_BUDGET * 2) }];
+ const plan = planSynthesis(huge, new Map([["src/huge.ts", "h"]]));
+ const hugeBatch = plan.find((b) => b.files.some((f) => f.path === "src/huge.ts"));
+ assert.ok(hugeBatch, "the oversized file must still be synthesized");
+ assert.ok(
+ hugeBatch.files.every((f) => f.path === "src/huge.ts" || chars(hugeBatch) <= BATCH_CHAR_BUDGET),
+ "an oversized file must not drag neighbours over the budget",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("a re-build after a one-file edit re-synthesizes one batch, not the graph", async () => {
+ const dir = makeRepo("batch-e2e");
+ let calls = 0;
+ const synthesizer: Synthesizer = {
+ async synthesize(files) {
+ calls++;
+ return files.map((f) => ({ name: f.path, type: "file", summary: "s", sources: [f.path], links: [] }));
+ },
+ };
+ const orig = console.error;
+ console.error = () => {};
+ try {
+ const first = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
+ assert.ok(first.batches >= 8, `need several batches for this to say anything, got ${first.batches}`);
+ const cold = calls;
+ assert.equal(cold, first.batches);
+
+ calls = 0;
+ const warm = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
+ assert.equal(calls, 0, "an unchanged repo spends nothing");
+ assert.equal(warm.batches, first.batches);
+
+ calls = 0;
+ writeFileSync(join(dir, "src", "mod-100.ts"), fileBody(100, EDIT_CHARS));
+ const after = await buildContext(dir, { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer });
+ assert.equal(after.batches, first.batches);
+ assert.ok(
+ calls >= 1 && calls <= 2,
+ `one edited file of ${first.batches} batches cost ${calls} synthesis calls; it must cost its own batch`,
+ );
+ } finally {
+ console.error = orig;
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/test/context-synth-concurrency.test.ts b/test/context-synth-concurrency.test.ts
new file mode 100644
index 00000000..8c30694d
--- /dev/null
+++ b/test/context-synth-concurrency.test.ts
@@ -0,0 +1,200 @@
+/**
+ * The concept pass synthesizes its batches CONCURRENTLY (phase 2 of
+ * `context/build.ts`). A batch is an independent unit of work — its call sees only
+ * its own summaries, and the merge waits for every call — so the calls overlap
+ * while the graph they produce has to stay indistinguishable from the serial one.
+ *
+ * These tests pin that with a synthesizer that answers OUT OF ORDER (the first call
+ * is the slowest), which is exactly what an implementation that merged batches as
+ * their calls landed would get wrong: same nodes, same slugs, same bytes, but a
+ * first-wins tie broken by network timing instead of by batch order.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { buildContext, type BuildProgress } from "../src/context/build.js";
+import { tmpRepo, PassthroughSummarizer } from "./helpers.js";
+import type { FileSummary, SynthNode, Synthesizer } from "../src/index.js";
+
+/** A repo big enough to be cut into several synthesis batches (1 file each). */
+const BATCHES = 6;
+
+/** One file per batch: two of them overshoot the char budget together. */
+function makeRepo(tag: string): string {
+ const dir = tmpRepo(tag);
+ mkdirSync(join(dir, "src"), { recursive: true });
+ for (let i = 0; i < BATCHES; i++) {
+ writeFileSync(join(dir, "src", `m${i}.ts`), `export const m${i} = 1;\n// ${"x".repeat(30_000)}\n`);
+ }
+ return dir;
+}
+
+/**
+ * The nodes one batch contributes. Batch 0 and batch 1 both claim a `Shared` node
+ * with DIFFERENT types, which is the merge's one first-wins tie: whichever batch
+ * is merged first decides the type that lands on disk.
+ */
+function nodesFor(batch: number, files: FileSummary[]): SynthNode[] {
+ const sources = files.map((f) => f.path);
+ const nodes: SynthNode[] = [{ name: `Batch ${batch}`, type: "file", summary: `batch ${batch}`, sources, links: [] }];
+ if (batch <= 1) {
+ nodes.push({ name: "Shared", type: batch === 0 ? "system" : "api", summary: `shared from batch ${batch}`, sources, links: [] });
+ }
+ return nodes;
+}
+
+/**
+ * Answers in reverse batch order — the first call started is the last to land — and
+ * records both the completion order and the high-water mark of calls in flight, so
+ * a test can show the calls really did overlap.
+ */
+class ReverseSynthesizer implements Synthesizer {
+ readonly completionOrder: number[] = [];
+ peakInFlight = 0;
+ private inFlight = 0;
+ private started = 0;
+
+ constructor(private readonly stepMs: number) {}
+
+ async synthesize(files: FileSummary[]): Promise<SynthNode[]> {
+ // `mapWithConcurrency` hands each worker the next batch the moment it starts, so
+ // the call order is the batch order.
+ const batch = this.started++;
+ this.inFlight++;
+ this.peakInFlight = Math.max(this.peakInFlight, this.inFlight);
+ try {
+ await sleep(this.stepMs * (BATCHES - batch));
+ this.completionOrder.push(batch);
+ return nodesFor(batch, files);
+ } finally {
+ this.inFlight--;
+ }
+ }
+}
+
+/** Every file under `dir`, as `relpath → sha256`, for a byte-for-byte comparison. */
+function snapshot(dir: string): Map<string, string> {
+ const out = new Map<string, string>();
+ const walk = (d: string): void => {
+ for (const entry of readdirSync(d, { withFileTypes: true })) {
+ const full = join(d, entry.name);
+ if (entry.isDirectory()) walk(full);
+ else out.set(relative(dir, full).split("\\").join("/"), createHash("sha256").update(readFileSync(full)).digest("hex"));
+ }
+ };
+ walk(dir);
+ return out;
+}
+
+function opts(synthesizer: Synthesizer, extra: Record<string, unknown> = {}) {
+ return { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer, ...extra };
+}
+
+test("batches synthesize in parallel and the graph is byte-identical to a serial run", async () => {
+ const serialDir = makeRepo("synth-serial");
+ const parallelDir = makeRepo("synth-parallel");
+ const quiet = () => {};
+ const orig = console.error;
+ console.error = quiet;
+ try {
+ const serial = new ReverseSynthesizer(5);
+ const parallel = new ReverseSynthesizer(5);
+ const a = await buildContext(serialDir, opts(serial, { synthConcurrency: 1, onProgress: quiet }));
+ const b = await buildContext(parallelDir, opts(parallel, { synthConcurrency: BATCHES, onProgress: quiet }));
+
+ assert.equal(a.batches, BATCHES);
+ assert.equal(b.batches, BATCHES);
+ assert.equal(serial.peakInFlight, 1, "synthConcurrency: 1 must not overlap calls");
+ assert.ok(parallel.peakInFlight > 1, `expected overlapping calls, peak was ${parallel.peakInFlight}`);
+ assert.deepEqual(
+ parallel.completionOrder,
+ [...parallel.completionOrder].sort((x, y) => y - x),
+ "the stand-in must land out of batch order, or the run proves nothing",
+ );
+
+ const expected = snapshot(join(serialDir, "graft"));
+ const actual = snapshot(join(parallelDir, "graft"));
+ assert.deepEqual([...actual.keys()].sort(), [...expected.keys()].sort());
+ for (const [file, hash] of expected) {
+ assert.equal(actual.get(file), hash, `${file} differs between the serial and parallel runs`);
+ }
+ } finally {
+ console.error = orig;
+ rmSync(serialDir, { recursive: true, force: true });
+ rmSync(parallelDir, { recursive: true, force: true });
+ }
+});
+
+test("a first-wins tie is broken by batch order, not by which call landed first", async () => {
+ const dir = makeRepo("synth-order");
+ const orig = console.error;
+ console.error = () => {};
+ try {
+ const synth = new ReverseSynthesizer(5);
+ const r = await buildContext(dir, opts(synth, { synthConcurrency: BATCHES }));
+ assert.ok(r.nodes >= BATCHES);
+ // Batch 0 lands last under the stand-in above, so this is batch 0's type only
+ // if the merge consumes the results in batch order.
+ const shared = readFileSync(join(dir, "graft", "shared.md"), "utf8");
+ assert.match(shared, /^type: system$/m);
+ assert.doesNotMatch(shared, /^type: api$/m);
+ } finally {
+ console.error = orig;
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("the failure gate stops issuing synthesis calls once the provider is fatal", async () => {
+ const dir = makeRepo("synth-gate");
+ let calls = 0;
+ const synthesizer: Synthesizer = {
+ async synthesize() {
+ calls++;
+ throw new Error("429 insufficient_quota");
+ },
+ };
+ const logged: string[] = [];
+ const orig = console.error;
+ console.error = (...args: unknown[]) => {
+ logged.push(args.map(String).join(" "));
+ };
+ try {
+ // 2 in flight, so the gate is fatal long before the last four batches run.
+ const r = await buildContext(dir, opts(synthesizer, { synthConcurrency: 2 }));
+ assert.ok(r.fatal, "a spent quota must end the pass");
+ assert.match(r.fatal, /quota/);
+ assert.equal(r.nodes, 0);
+ assert.equal(r.errors.length, calls, "every issued call is reported as an error");
+ assert.ok(calls < r.batches, `the gate must stop issuing calls: ${calls} of ${r.batches} were made`);
+ assert.ok(logged.some((l) => /synthesis batch 1\/\d+: 0 nodes, 0 links \(failed\)/.test(l)));
+ assert.ok(logged.some((l) => /\(skipped\)/.test(l)), "a batch the gate skipped is labelled, not silently empty");
+ } finally {
+ console.error = orig;
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("synthesis progress climbs monotonically under concurrency", async () => {
+ const dir = makeRepo("synth-progress");
+ const progress: BuildProgress[] = [];
+ const orig = console.error;
+ console.error = () => {};
+ try {
+ await buildContext(dir, opts(new ReverseSynthesizer(5), {
+ synthConcurrency: BATCHES,
+ onProgress: (info: BuildProgress) => progress.push(info),
+ }));
+ const synth = progress.filter((p) => p.phase === "synthesize");
+ assert.equal(synth.length, BATCHES, "one report per batch, however they interleave");
+ // The CLI overwrites one line with these, so a counter that went backwards
+ // would read as the pass rewinding itself.
+ assert.deepEqual(synth.map((p) => p.index), [...synth.map((p) => p.index)].sort((x, y) => x - y));
+ for (const p of synth) assert.equal(p.total, BATCHES);
+ } finally {
+ console.error = orig;
+ rmSync(dir, { recursive: true, force: true });
+ }
+});