Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

test(ingest): incremental-equals-fresh harness on a fake backend

KageBinarybdf516581d6a
diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.json
index 2c4cd38a..a5404043 100644
--- a/ix-cli/package-lock.json
+++ b/ix-cli/package-lock.json
@@ -24,6 +24,7 @@
"eslint": "^10.11.0",
"eslint-config-prettier": "^10.1.8",
"eslint-plugin-unused-imports": "^4.4.1",
+ "fast-check": "^4.10.2",
"knip": "^6.38.0",
"prettier": "^3.9.9",
"tsx": "^4.23.15",
@@ -3206,6 +3207,29 @@
"express": ">= 4.11"
}
},
+ "node_modules/fast-check": {
+ "version": "4.10.2",
+ "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-4.10.2.tgz",
+ "integrity": "sha512-iK2f+YrcmoeGqk6fA0ea2bptcu/itMIm4NfEozq6N25+aG6h7s5HZbB/k1aV7b5w5sFLMCbbtRUsTVR+BgC3xw==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/dubzzz"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fast-check"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "pure-rand": "^8.0.0"
+ },
+ "engines": {
+ "node": ">=12.17.0"
+ }
+ },
"node_modules/fast-deep-equal": {
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
@@ -4307,6 +4331,23 @@
"node": ">=6"
}
},
+ "node_modules/pure-rand": {
+ "version": "8.4.2",
+ "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.2.tgz",
+ "integrity": "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "individual",
+ "url": "https://github.com/sponsors/dubzzz"
+ },
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/fast-check"
+ }
+ ],
+ "license": "MIT"
+ },
"node_modules/qified": {
"version": "0.10.1",
"resolved": "https://registry.npmjs.org/qified/-/qified-0.10.1.tgz",
diff --git a/ix-cli/package.json b/ix-cli/package.json
index 669517d0..b22dcd4d 100644
--- a/ix-cli/package.json
+++ b/ix-cli/package.json
@@ -43,6 +43,7 @@
"eslint": "^10.11.0",
"eslint-config-prettier": "^10.1.8",
"eslint-plugin-unused-imports": "^4.4.1",
+ "fast-check": "^4.10.2",
"knip": "^6.38.0",
"prettier": "^3.9.9",
"tsx": "^4.23.15",
diff --git a/ix-cli/src/cli/__tests__/helpers/edit-fixture.ts b/ix-cli/src/cli/__tests__/helpers/edit-fixture.ts
new file mode 100644
index 00000000..8ea9d869
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/helpers/edit-fixture.ts
@@ -0,0 +1,167 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+/**
+ * A small repository as a model, rendered to Python, TypeScript and Java, and
+ * the edits an incremental `ix map` has to survive.
+ *
+ * Shared by the fake-backend equivalence test (`ingest-equivalence.test.ts`)
+ * and meant for the real-backend harness too, so both run the same scenarios.
+ * Each file is a list of functions; each function returns a sum of calls and a
+ * constant. That is enough to produce the edges that matter -- CONTAINS,
+ * DEFINES, IMPORTS and same-file and cross-file CALLS -- and to change any of
+ * them with a one-field edit.
+ */
+
+export type Lang = "py" | "ts" | "java";
+export interface Call { path: string; name: string }
+export interface Fn { name: string; value: number; calls: Call[] }
+/** Workspace-relative path -> functions. A file's language is its extension. */
+export type Repo = Map<string, Fn[]>;
+
+export const langOf = (path: string): Lang =>
+ path.endsWith(".py") ? "py" : path.endsWith(".ts") ? "ts" : "java";
+
+const stem = (path: string): string => path.slice(path.lastIndexOf("/") + 1).replace(/\.[^.]+$/, "");
+
+/** Source text for one file. Imports are derived from the cross-file calls. */
+export function render(path: string, fns: Fn[]): string {
+ const callees = [...new Map(fns.flatMap((f) => f.calls).filter((c) => c.path !== path)
+ .map((c) => [`${c.path}\0${c.name}`, c])).values()];
+ const body = (f: Fn, call: (c: Call) => string): string => [...f.calls.map(call), String(f.value)].join(" + ");
+ switch (langOf(path)) {
+ case "py": {
+ const imports = callees.map((c) => `from ${c.path.replace(/\.py$/, "").replace(/\//g, ".")} import ${c.name}\n`);
+ const defs = fns.map((f) => `def ${f.name}():\n return ${body(f, (c) => `${c.name}()`)}\n`);
+ return [imports.join(""), ...defs].filter(Boolean).join("\n");
+ }
+ case "ts": {
+ const imports = callees.map((c) => `import { ${c.name} } from './${stem(c.path)}';\n`);
+ const defs = fns.map((f) => `export function ${f.name}(): number {\n return ${body(f, (c) => `${c.name}()`)};\n}\n`);
+ return [imports.join(""), ...defs].filter(Boolean).join("\n");
+ }
+ case "java": {
+ // One package, so a cross-file call needs no import: `Util.helper()`.
+ const call = (c: Call) => (c.path === path ? `${c.name}()` : `${stem(c.path)}.${c.name}()`);
+ const defs = fns.map((f) => ` public static int ${f.name}() {\n return ${body(f, call)};\n }\n`);
+ return `package com.ex;\n\npublic class ${stem(path)} {\n${defs.join("\n")}}\n`;
+ }
+ }
+}
+
+/**
+ * Twelve files, four per language. In each language one file is called by the
+ * other three (`util.py`, `math.ts`, `Util.java`) and one calls through a
+ * second file (`app.py -> service.py -> util.py`).
+ */
+export function initialRepo(): Repo {
+ const fn = (name: string, value: number, ...calls: Array<[string, string]>): Fn =>
+ ({ name, value, calls: calls.map(([path, n]) => ({ path, name: n })) });
+ return new Map<string, Fn[]>([
+ ["pkg/util.py", [fn("helper", 1), fn("scale", 2, ["pkg/util.py", "helper"])]],
+ ["pkg/service.py", [fn("run", 3, ["pkg/util.py", "helper"], ["pkg/util.py", "scale"])]],
+ ["pkg/app.py", [fn("main", 4, ["pkg/service.py", "run"])]],
+ ["pkg/models.py", [fn("make", 5, ["pkg/util.py", "helper"])]],
+ ["web/math.ts", [fn("add", 1), fn("mul", 2, ["web/math.ts", "add"])]],
+ ["web/calc.ts", [fn("total", 3, ["web/math.ts", "add"], ["web/math.ts", "mul"])]],
+ ["web/main.ts", [fn("start", 4, ["web/calc.ts", "total"])]],
+ ["web/report.ts", [fn("report", 5, ["web/math.ts", "add"])]],
+ ["src/com/ex/Util.java", [fn("helper", 1), fn("twice", 2, ["src/com/ex/Util.java", "helper"])]],
+ ["src/com/ex/Service.java", [fn("run", 3, ["src/com/ex/Util.java", "helper"])]],
+ ["src/com/ex/App.java", [fn("main", 4, ["src/com/ex/Service.java", "run"])]],
+ ["src/com/ex/Model.java", [fn("build", 5, ["src/com/ex/Util.java", "twice"])]],
+ ]);
+}
+
+export const cloneRepo = (repo: Repo): Repo =>
+ new Map([...repo].map(([p, fns]) => [p, fns.map((f) => ({ ...f, calls: f.calls.map((c) => ({ ...c })) }))]));
+
+export const EDIT_KINDS = [
+ "editBody", "addFunction", "removeFunction", "renameFunction", "addCall", "removeCall",
+ "addFile", "deleteFile", "renameFile", "revert", "deleteThenRestore",
+] as const;
+export type EditKind = (typeof EDIT_KINDS)[number];
+
+/**
+ * One edit. `a` and `b` pick the file and the function, modulo what exists, so
+ * any sequence of edits applies to any state. `path` overrides `a` for
+ * hand-written scenarios.
+ */
+export interface Edit { kind: EditKind; a: number; b: number; path?: string }
+
+let counter = 0;
+const pick = <T>(xs: T[], i: number): T | undefined => (xs.length === 0 ? undefined : xs[i % xs.length]);
+
+/**
+ * Apply one edit. Returns the states to map, in order: one for most edits, two
+ * for `deleteThenRestore`. `history` is every state mapped so far, which
+ * `revert` picks from. `langs` limits which files an edit may touch.
+ */
+export function applyEdit(repo: Repo, edit: Edit, history: Repo[], langs?: Lang[]): Repo[] {
+ const next = cloneRepo(repo);
+ const allPaths = [...next.keys()].sort();
+ const paths = langs ? allPaths.filter((p) => langs.includes(langOf(p))) : allPaths;
+ const path = edit.path ?? pick(paths, edit.a);
+ const fns = path === undefined ? [] : next.get(path) ?? [];
+ const f = pick(fns, edit.b);
+ const newPath = (lang: Lang, base: string) => {
+ const n = ++counter;
+ return lang === "py" ? `pkg/${base}${n}.py` : lang === "ts" ? `web/${base}${n}.ts`
+ : `src/com/ex/${base[0]!.toUpperCase()}${base.slice(1)}${n}.java`;
+ };
+ switch (edit.kind) {
+ case "editBody":
+ if (f) f.value += 1;
+ return [next];
+ case "addFunction":
+ if (path) fns.push({ name: `added${++counter}`, value: 7, calls: [] });
+ return [next];
+ case "removeFunction":
+ if (f && fns.length > 1) fns.splice(fns.indexOf(f), 1);
+ return [next];
+ case "renameFunction":
+ if (f) f.name = `renamed${++counter}`;
+ return [next];
+ case "addCall": {
+ if (!f || !path) return [next];
+ const others = allPaths.filter((p) => p !== path && langOf(p) === langOf(path));
+ const target = pick(others, edit.a + edit.b);
+ const callee = target === undefined ? undefined : pick(next.get(target)!, edit.b);
+ if (target && callee && !f.calls.some((c) => c.path === target && c.name === callee.name)) {
+ f.calls.push({ path: target, name: callee.name });
+ }
+ return [next];
+ }
+ case "removeCall":
+ if (f && f.calls.length > 0) f.calls.splice(edit.b % f.calls.length, 1);
+ return [next];
+ case "addFile": {
+ const choices = langs ?? (["py", "ts", "java"] as Lang[]);
+ const lang = choices[edit.a % choices.length]!;
+ const created = newPath(lang, "extra");
+ const target = pick(allPaths.filter((p) => langOf(p) === lang), edit.b);
+ const callee = target === undefined ? undefined : pick(next.get(target)!, 0);
+ next.set(created, [{ name: `extra${counter}`, value: 1, calls: callee ? [{ path: target!, name: callee.name }] : [] }]);
+ return [next];
+ }
+ case "deleteFile":
+ if (path && allPaths.length > 1) next.delete(path);
+ return [next];
+ case "renameFile": {
+ if (!path) return [next];
+ const moved = newPath(langOf(path), "moved");
+ next.set(moved, next.get(path)!);
+ next.delete(path);
+ // Callers follow the move, as an IDE refactor would.
+ for (const g of [...next.values()].flat()) for (const c of g.calls) if (c.path === path) c.path = moved;
+ return [next];
+ }
+ case "revert":
+ return [cloneRepo(pick(history, edit.a) ?? repo)];
+ case "deleteThenRestore": {
+ if (!path || allPaths.length < 2) return [next];
+ const without = cloneRepo(next);
+ without.delete(path);
+ return [without, next];
+ }
+ }
+}
diff --git a/ix-cli/src/cli/__tests__/helpers/fake-backend.ts b/ix-cli/src/cli/__tests__/helpers/fake-backend.ts
new file mode 100644
index 00000000..1c007929
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/helpers/fake-backend.ts
@@ -0,0 +1,467 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { createServer, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { createHash } from "node:crypto";
+
+type SentPatch = {
+ patchId?: string;
+ source?: { uri?: string; sourceHash?: string; workspaceId?: string };
+ ops?: Array<Record<string, unknown>>;
+};
+
+/** A backend that answers the endpoints an ingest touches, and records them. */
+export class FakeBackend {
+ readonly requests: Array<{ path: string; patches: number; code?: number }> = [];
+ /** `source.uri` of every patch sent in a commit request, accepted or not. */
+ readonly sourceUris: string[] = [];
+ /** `source.workspaceId` beside each of `sourceUris`, in the same order. */
+ readonly sourceWorkspaceIds: Array<string | undefined> = [];
+ /** The ops of the last patch sent for each `source.uri`. */
+ readonly lastOps = new Map<string, Array<Record<string, unknown>>>();
+ /** Paths this fake does not implement. Asserted empty after every test. */
+ readonly unknownPaths: string[] = [];
+
+ private server: Server | undefined;
+ private rev = 0;
+
+ /** Patch-source substrings this backend refuses, whatever else is healthy. */
+ poison: string[] = [];
+ /** Fail every commit, the Ix#560 shape. */
+ refuseEverything = false;
+ /** Refuse re-sends of patches a 409 already confirmed. */
+ refuseReplays = false;
+ /**
+ * Answer the CUTOFF DRAIN's bulk with `BaseRevMismatch`, and nothing else.
+ *
+ * A 200 that wrote nothing: the backend read the latest rev outside the
+ * transaction and it moved before the commit ran. Without a knob the harness
+ * could only ever serve "Ok", so every `status` branch in the three commit
+ * sites was unreachable from any test.
+ *
+ * Aimed at the drain specifically, by shape rather than by counting
+ * requests. The drain is the only bulk that happens AFTER the per-file
+ * fan-out, so "a bulk with at least one single behind it" names it exactly,
+ * and stays right if the number of requests before it ever changes.
+ */
+ mismatchOnDrainBulk = false;
+ /**
+ * Answer this many commits (bulk or single) `BaseRevMismatch` before taking
+ * any: what a second `ix map` committing to the same backend does to this
+ * one. A 200 that wrote nothing, like `mismatchOnDrainBulk`.
+ */
+ loseBaseRevRaces = 0;
+ /**
+ * Refuse the opening bulk and every per-file send, but ACCEPT the drain.
+ *
+ * The only shape that reaches an accepted cutoff drain, and it took three
+ * tries to find because each failed one looked plausible. Poisoning files
+ * does not work: the cutoff holds the patches that FAILED as well as the
+ * untried ones, so the drain carries the poison and is refused. Refusing by
+ * request count does not work either: the cutoff trips on the fifth failure
+ * and the drain follows immediately, so any threshold high enough to produce
+ * five failures is still in force when the drain arrives. Both were measured
+ * at zero accepted bulks in the whole run, via `acceptedBulks()`.
+ *
+ * Refusing by KIND separates them: the opening bulk (no singles behind it)
+ * and every single are refused, which trips the cutoff; the drain is the only
+ * bulk with singles behind it, and it is answered 200 -- so the code that
+ * reads its status is finally reached.
+ */
+ refuseUntilDrain = false;
+ /** Fired after `abortAfterCommits` commit requests, if set. */
+ abortAfterCommits: number | undefined;
+ private readonly aborter = new AbortController();
+
+ /** A run deadline that fires at a known POINT IN THE COMMIT SEQUENCE. */
+ get deadlineSignal(): AbortSignal {
+ return this.aborter.signal;
+ }
+ /** Answer a bulk with 409 naming every patch as already committed. */
+ bulk409AllLanded = false;
+ /** Status for POST /v1/stitch. */
+ stitchStatus = 200;
+ /**
+ * Answer `/v1/source-hashes` with the hashes of patches this fake accepted,
+ * as the real backend does. Off by default: with it off every lookup is
+ * empty, so the DB-reset guard sends each incremental run down the full
+ * path, which the tests written before it rely on.
+ */
+ rememberHashes = false;
+ /** Answer `/v1/source-hashes` with a 500, as a backend under load does. */
+ failSourceHashes = false;
+ private readonly hashes = new Map<string, { workspaceId: string | null; uri: string; hash: string }>();
+
+ /**
+ * Store the graph, with the real backend's commit semantics. Unset, the fake
+ * only counts: every commit is "Ok" and nothing is kept, which is what the
+ * wiring tests were written against. Set, commits go through `commitToGraph`,
+ * modelled on Ix-memory 326d8da (and `scratch/cli-ingest/exp12.mjs`):
+ *
+ * - a bulk commit tombstones every live edge whose source is one of its
+ * patches' (workspace, uri) before it writes (BulkWriteApi
+ * `tombstoneExistingEdges`); `/v1/patch` does not;
+ * - Delete ops tombstone by id, on both routes;
+ * - a patch id seen before is not written again: `/v1/patch` answers
+ * `Idempotent`, and a bulk answers `Idempotent` when every id was seen in
+ * the same request plan, 409 otherwise (BulkWriteApi `completedReplay`);
+ * - `/v1/source-hashes` answers the hash of the head patch, the one with
+ * the highest rev, per (workspace, uri).
+ *
+ * The two modes differ only in what "seen before" means:
+ *
+ * - `legacy`: any id ever committed. This is the backend as shipped, and
+ * why a file reverted to earlier bytes is never re-applied (F-01).
+ * - `head`: only the id that is still the head patch for its (workspace,
+ * uri). An older id is written again and becomes the head (BEW-03).
+ */
+ semantics: "legacy" | "head" | undefined;
+ private readonly nodes = new Map<string, { kind: unknown; name: unknown; live: boolean }>();
+ private readonly edges = new Map<string, {
+ src: unknown; dst: unknown; predicate: unknown; workspaceId: string; uri: string; live: boolean;
+ }>();
+ /** Every committed patch by id, with the rev it last landed at. */
+ private readonly stored = new Map<string, {
+ rev: number; workspaceId: string; uri: string; hash: string | undefined;
+ ops: Array<Record<string, unknown>>; bulkGroup: string | null;
+ }>();
+ /** Head patch id per `${workspaceId}\0${uri}`. */
+ private readonly heads = new Map<string, string>();
+
+ constructor(opts: { semantics?: "legacy" | "head" } = {}) {
+ this.semantics = opts.semantics;
+ }
+
+ /**
+ * The live graph as a sorted, comparable list: nodes as `id kind name`,
+ * edges as `id src dst predicate`. Two backends hold the same graph exactly
+ * when their signatures are equal.
+ */
+ graphSignature(): { nodes: string[]; edges: string[] } {
+ const nodes = [...this.nodes].filter(([, n]) => n.live)
+ .map(([id, n]) => `${id} ${String(n.kind)} ${String(n.name)}`).sort();
+ const edges = [...this.edges].filter(([, e]) => e.live)
+ .map(([id, e]) => `${id} ${String(e.src)} ${String(e.dst)} ${String(e.predicate)}`).sort();
+ return { nodes, edges };
+ }
+
+ /** Names of the live nodes, to make a signature diff readable. */
+ nodeName(id: string): string {
+ const n = this.nodes.get(id);
+ return n ? `${String(n.name)}[${String(n.kind)}]${n.live ? "" : "(deleted)"}` : `<missing ${id.slice(0, 8)}>`;
+ }
+
+ private alreadyCommitted(patchId: string): boolean {
+ const record = this.stored.get(patchId);
+ if (record === undefined) return false;
+ if (this.semantics === "legacy") return true;
+ return this.heads.get(`${record.workspaceId}\0${record.uri}`) === patchId;
+ }
+
+ private applyPatch(patch: SentPatch, sweep: boolean, bulkGroup: string | null): void {
+ const workspaceId = patch.source?.workspaceId ?? "";
+ const uri = patch.source?.uri ?? "";
+ this.rev++;
+ if (sweep) {
+ for (const e of this.edges.values()) {
+ if (e.live && e.uri === uri && e.workspaceId === workspaceId) e.live = false;
+ }
+ }
+ for (const op of patch.ops ?? []) {
+ const id = String(op.id);
+ if (op.type === "UpsertNode") this.nodes.set(id, { kind: op.kind, name: op.name, live: true });
+ else if (op.type === "UpsertEdge") {
+ this.edges.set(id, { src: op.src, dst: op.dst, predicate: op.predicate, workspaceId, uri, live: true });
+ } else if (op.type === "DeleteNode") {
+ const n = this.nodes.get(id);
+ if (n) n.live = false;
+ } else if (op.type === "DeleteEdge") {
+ const e = this.edges.get(id);
+ if (e) e.live = false;
+ }
+ }
+ if (patch.patchId === undefined) return;
+ this.stored.set(patch.patchId, {
+ rev: this.rev, workspaceId, uri, hash: patch.source?.sourceHash, ops: patch.ops ?? [], bulkGroup,
+ });
+ this.heads.set(`${workspaceId}\0${uri}`, patch.patchId);
+ }
+
+ private commitToGraph(path: string, patches: SentPatch[], send: (code: number, payload: unknown) => void): void {
+ if (path === "/v1/patch") {
+ const [patch] = patches;
+ if (patch?.patchId !== undefined && this.alreadyCommitted(patch.patchId)) {
+ return send(200, { rev: this.stored.get(patch.patchId)!.rev, status: "Idempotent" });
+ }
+ if (patch) this.applyPatch(patch, false, null);
+ return send(200, { rev: this.rev, status: "Ok" });
+ }
+ const ids = patches.map((p) => p.patchId ?? "");
+ const group = createHash("sha256").update(ids.join(",")).digest("hex");
+ const done = ids.filter((id) => this.alreadyCommitted(id));
+ if (done.length === 0) {
+ for (const p of patches) this.applyPatch(p, true, group);
+ return send(200, { rev: this.rev, applied: patches.length, status: "Ok" });
+ }
+ if (done.length !== ids.length) {
+ return send(409, {
+ error: `bulk request is partially committed (${done.length}/${ids.length} patch IDs)`,
+ committed_patch_ids: [...done].sort(),
+ });
+ }
+ if (done.some((id) => this.stored.get(id)!.bulkGroup !== group)) {
+ return send(409, { error: "bulk patch IDs were previously committed by a different request plan" });
+ }
+ return send(200, { rev: Math.max(...done.map((id) => this.stored.get(id)!.rev)), applied: 0, status: "Idempotent" });
+ }
+
+ private sourceHashesFromGraph(uris: string[], workspaceIds: string[] | undefined): unknown[] {
+ const wanted = new Set(uris);
+ const rows: unknown[] = [];
+ for (const patchId of this.heads.values()) {
+ const record = this.stored.get(patchId)!;
+ if (!wanted.has(record.uri) || record.hash === undefined) continue;
+ if (workspaceIds?.length && !workspaceIds.includes(record.workspaceId)) continue;
+ rows.push({ workspaceId: record.workspaceId, uri: record.uri, hash: record.hash });
+ }
+ return rows;
+ }
+
+ /** Forget every request so far, so a second run can be measured on its own. */
+ resetRequests(): void {
+ this.requests.splice(0, this.requests.length);
+ }
+
+ get stitchCount(): number {
+ return this.requests.filter((r) => r.path === "/v1/stitch").length;
+ }
+
+ /** Patches in commit requests the backend ACCEPTED. */
+ acceptedPatches(): number {
+ return this.requests
+ .filter(r => (r.path === "/v1/patches/bulk" || r.path === "/v1/patch") && r.code === 200)
+ .reduce((sum, r) => sum + r.patches, 0);
+ }
+
+ /** Bulk commits that the backend ACCEPTED, in order. */
+ acceptedBulks(): number {
+ return this.requests.filter(r => r.path === "/v1/patches/bulk" && r.code === 200).length;
+ }
+
+ get bulkCount(): number {
+ return this.requests.filter((r) => r.path === "/v1/patches/bulk").length;
+ }
+
+ get singleCount(): number {
+ return this.requests.filter((r) => r.path === "/v1/patch").length;
+ }
+
+ get commitCount(): number {
+ return this.bulkCount + this.singleCount;
+ }
+
+ async start(): Promise<string> {
+ this.server = createServer((req, res) => {
+ // Collect and concat, rather than `body += chunk`. Appending a Buffer to
+ // a string decodes each TCP chunk on its own, so a multi-byte character
+ // split across a chunk boundary is corrupted -- and a bulk body for
+ // thirty patches is comfortably big enough to be split. Latent while the
+ // fixtures are ASCII; the first non-ASCII one would make `JSON.parse`
+ // throw and silently route the request down a different branch.
+ const chunks: Buffer[] = [];
+ req.on("data", (c: Buffer) => chunks.push(c));
+ req.on("end", () => this.route(req.url ?? "/", Buffer.concat(chunks).toString("utf8"), res));
+ });
+ await new Promise<void>((resolve, reject) => {
+ // Without the `error` listener a failed bind -- EACCES under a
+ // restrictive sandbox, EADDRNOTAVAIL where loopback is unusual -- never
+ // settles this promise, and surfaces as a beforeEach hook timeout plus an
+ // unhandled 'error' event rather than as the bind error it is.
+ this.server!.once("error", reject);
+ this.server!.listen(0, "127.0.0.1", resolve);
+ });
+ return `http://127.0.0.1:${(this.server!.address() as AddressInfo).port}`;
+ }
+
+ async stop(): Promise<void> {
+ if (!this.server) return;
+ const server = this.server;
+ // `closeAllConnections` first, and a deadline behind it. `close()` waits for
+ // every open socket, so one keep-alive connection the run did not finish
+ // with leaves this pending -- and a hook that never settles takes its
+ // timeout, at which point NEITHER `finally` in the teardown runs and both
+ // temp trees leak anyway. The teardown can only be made safe if this cannot
+ // hang, so the fix belongs here rather than in another `try`.
+ // Not optional-chained: `engines.node` is >=22 and this landed in 18.2.
+ server.closeAllConnections();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const closed = await Promise.race([
+ new Promise<boolean>((resolve) => server.close(() => resolve(true))),
+ new Promise<boolean>((resolve) => {
+ timer = setTimeout(() => resolve(false), 2000);
+ timer.unref?.();
+ }),
+ ]);
+ clearTimeout(timer);
+ if (!closed) {
+ // Not expected to fire, and it never has. `Promise.race` builds its
+ // array eagerly, so `server.close()` runs in the SAME tick as
+ // `closeAllConnections()` above -- the listening handle is gone before
+ // any later turn of the loop, so nothing can connect afterwards, and
+ // every socket that existed has been destroyed. There is no "late
+ // socket" story; an earlier revision of this comment invented one.
+ //
+ // Kept anyway, as a backstop against `close()` simply never calling
+ // back -- a socket wedged in destroy, say. Deliberately a message and
+ // not a throw: the alternative it exists to prevent is a hook that
+ // never settles, which takes the hook timeout and runs NEITHER
+ // `finally` below, leaking both trees and leaving the env pointed at a
+ // deleted home. A leak that announces itself is the better trade.
+ process.stderr.write(
+ "FakeBackend.stop: close() did not call back within 2s; the server handle is being abandoned\n",
+ );
+ }
+ }
+
+ private route(url: string, body: string, res: ServerResponse): void {
+ const path = new URL(url, "http://x").pathname;
+ const send = (code: number, payload: unknown): void => {
+ // Stamp the answer onto the request that produced it. Whether a bulk was
+ // ACCEPTED or refused is the difference between two completely different
+ // code paths in `ingestFiles`, and a test that assumes the wrong one is
+ // measuring nothing -- which is exactly how the drain test below first
+ // went wrong.
+ const last = this.requests[this.requests.length - 1];
+ if (last !== undefined && last.code === undefined) last.code = code;
+ res.writeHead(code, { "Content-Type": "application/json" });
+ res.end(JSON.stringify(payload));
+ };
+
+ if (path === "/v1/patches/bulk" || path === "/v1/patch") {
+ let patches: SentPatch[] = [];
+ try {
+ const parsed = JSON.parse(body) as { patches?: SentPatch[] };
+ patches = parsed.patches ?? [parsed as SentPatch];
+ } catch {
+ /* a body we cannot read is still a request */
+ }
+ this.requests.push({ path, patches: patches.length });
+ for (const { source, ops } of patches) {
+ if (!source?.uri) continue;
+ this.sourceUris.push(source.uri);
+ this.sourceWorkspaceIds.push(source.workspaceId);
+ this.lastOps.set(source.uri, ops ?? []);
+ }
+ if (this.abortAfterCommits !== undefined && this.commitCount >= this.abortAfterCommits) {
+ this.aborter.abort();
+ }
+
+ if (path === "/v1/patch" && this.refuseReplays) {
+ return send(500, { error: "500: already committed" });
+ }
+ if (path === "/v1/patches/bulk" && this.bulk409AllLanded) {
+ const ids = patches.map((p) => p.patchId).filter(Boolean);
+ return send(409, { error: "bulk group partially committed", committed_patch_ids: ids });
+ }
+ // Ahead of the poison check, deliberately. The drain carries the patches
+ // the cutoff held back, which for any fixture that trips the cutoff
+ // includes the poisoned ones -- so the poison branch answered 500 and the
+ // drain never reached the success path at all. A first attempt at this
+ // set the status further down and measured nothing, because no bulk in
+ // the test ever got there.
+ const isDrainBulk = path === "/v1/patches/bulk" && this.singleCount > 0;
+ if (this.loseBaseRevRaces > 0) {
+ this.loseBaseRevRaces--;
+ return send(200, { rev: this.rev, applied: 0, status: "BaseRevMismatch" });
+ }
+ if (this.mismatchOnDrainBulk && isDrainBulk) {
+ // A 200 that wrote NOTHING: the backend read the latest rev outside the
+ // transaction and it moved before the commit ran. `applied: 0` and the
+ // rev deliberately left where it was, because nothing landed.
+ return send(200, { rev: this.rev, applied: 0, status: "BaseRevMismatch" });
+ }
+ const refused =
+ this.refuseEverything ||
+ (this.refuseUntilDrain && !isDrainBulk) ||
+ this.poison.some((p) => body.includes(p));
+ // Answered synchronously. A `commitDelayMs` knob lived here and no test
+ // ever set it -- the deadline test fires off request COUNT instead, which
+ // is what makes it deterministic. Reviving it needs care rather than a
+ // one-liner: `stop()` resolves on `server.close()` without cancelling a
+ // pending timer, so a deferred response outlives the test that armed it
+ // and fires against a closed server.
+ if (refused) return send(500, { error: "500: transaction begin timeout" });
+ if (this.semantics !== undefined) return this.commitToGraph(path, patches, send);
+ this.rev += patches.length || 1;
+ if (this.rememberHashes) {
+ for (const { source } of patches) {
+ if (source?.uri && source.sourceHash) {
+ this.hashes.set(`${source.workspaceId ?? ""}\0${source.uri}`,
+ { workspaceId: source.workspaceId ?? null, uri: source.uri, hash: source.sourceHash });
+ }
+ }
+ }
+ // `status` included, because `PatchCommitResult` declares it required and
+ // the ingest path branches on it. Serving 200s without it left
+ // `result.status` undefined everywhere, so this fake could never produce
+ // an `Idempotent` or `BaseRevMismatch` answer -- the two branches that
+ // decide whether a patch lands in `patchesApplied` or `commitErrors`, and
+ // so whether the mtime baseline is written at all. A regression that
+ // flipped the applied test from "not BaseRevMismatch" to `=== "Ok"` would
+ // have counted zero patches applied against the real backend while every
+ // test here stayed green.
+ send(
+ 200,
+ path === "/v1/patches/bulk"
+ ? { rev: this.rev, applied: patches.length, status: "Ok" }
+ : { rev: this.rev, status: "Ok" },
+ );
+ return;
+ }
+
+ if (path === "/v1/health") return send(200, { status: "ok", version: "1.0.28" });
+ if (path === "/v1/source-hashes") {
+ if (this.failSourceHashes) return send(500, { error: "500: transaction begin timeout" });
+ let uris: string[] = [];
+ let workspaceIds: string[] | undefined;
+ try {
+ ({ uris = [], workspaceIds } = JSON.parse(body) as { uris?: string[]; workspaceIds?: string[] });
+ } catch { /* none */ }
+ if (this.semantics !== undefined) return send(200, this.sourceHashesFromGraph(uris, workspaceIds));
+ if (!this.rememberHashes) return send(200, []);
+ const wanted = new Set(uris);
+ return send(200, [...this.hashes.values()].filter((row) => wanted.has(row.uri)));
+ }
+ if (path.startsWith("/v1/stitch/system/")) return send(200, { systemId: null });
+ // Read by `reconcileRemovedEntities`, which only an incremental run against
+ // a stored graph reaches.
+ if (this.semantics !== undefined && path.startsWith("/v1/patches/")) {
+ const record = this.stored.get(decodeURIComponent(path.slice("/v1/patches/".length)));
+ return record ? send(200, { data: { ops: record.ops } }) : send(404, { error: "404: patch not found" });
+ }
+ if (this.semantics !== undefined && path.startsWith("/v1/entity/")) {
+ const id = decodeURIComponent(path.slice("/v1/entity/".length));
+ const node = this.nodes.get(id);
+ if (!node?.live) return send(404, { error: "404: entity not found" });
+ const edges = [...this.edges]
+ .filter(([, e]) => e.live && (e.src === id || e.dst === id))
+ .map(([edgeId, e]) => ({ id: edgeId, predicate: e.predicate, provenance: { sourceUri: e.uri } }));
+ return send(200, { node: { id, kind: node.kind, name: node.name }, edges });
+ }
+ if (path === "/v1/stitch") {
+ this.requests.push({ path, patches: 0 });
+ if (this.stitchStatus !== 200)
+ return send(this.stitchStatus, { error: "AQL: query timed out" });
+ return send(200, { stitched: 0, systemId: null, edges: [] });
+ }
+ // 404, not `200 {}`. A fake that answers every unrecognised path with a
+ // cheerful empty body cannot fail: product code that starts calling a new
+ // endpoint -- or mistypes an existing one -- gets a success here where the
+ // real backend would 404, and the harness stays green while measuring a
+ // request the backend never served. The path is recorded as well as
+ // refused, so the afterEach names it rather than leaving a stray 404 to be
+ // explained.
+ this.unknownPaths.push(path);
+ return send(404, { error: `404: no such endpoint ${path}` });
+ }
+}
diff --git a/ix-cli/src/cli/__tests__/ingest-equivalence.test.ts b/ix-cli/src/cli/__tests__/ingest-equivalence.test.ts
new file mode 100644
index 00000000..9c53eaef
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/ingest-equivalence.test.ts
@@ -0,0 +1,298 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import fc from "fast-check";
+
+import { ingestFiles } from "../commands/ingest.js";
+import { FakeBackend } from "./helpers/fake-backend.js";
+import { applyEdit, EDIT_KINDS, initialRepo, render, type Edit, type EditKind, type Lang, type Repo } from "./helpers/edit-fixture.js";
+
+// Two parse workers rather than `cpus - 1`. Every ingest starts its own pool
+// and this file runs a few hundred of them; at one worker per core that is
+// over a gigabyte of grammars per run on a large machine.
+vi.mock("node:os", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:os")>();
+ return { ...actual, cpus: () => actual.cpus().slice(0, 3) };
+});
+
+/**
+ * Incremental equals fresh: after any sequence of edits, the graph that
+ * incremental `ix map` runs leave on the backend must equal the graph a fresh
+ * map of the final tree writes into an empty backend.
+ *
+ * Every test drives the real `ingestFiles` (discovery, the worker parse pool,
+ * the commit engine) against `FakeBackend` with `semantics` set, so the fake
+ * stores the graph and answers commits the way Ix-memory does: a bulk commit
+ * sweeps the edges of the files it carries, `/v1/patch` does not, a patch id
+ * seen before is not written again, and `/v1/source-hashes` reports the head
+ * patch. Graphs are compared by `graphSignature()`: live nodes as
+ * `id kind name`, live edges as `id src dst predicate`.
+ *
+ * Each class of defect has a fixed scenario. A class that fails on `main` is
+ * marked `it.fails` with the card that fixes it; that card deletes the marker,
+ * and from then on the test guards the fix. The two properties run random
+ * sequences: one over the edits that are correct today, and one over every
+ * edit, which passes in `head` mode once IN-04, IN-10 and IN-11 have landed.
+ *
+ * The fast-check seed is fixed so a marked test cannot pass by luck. Set
+ * IX_EQUIV_SEED to explore other sequences, and IX_EQUIV_RUNS for more runs.
+ */
+
+type Semantics = "legacy" | "head";
+type Signature = { nodes: string[]; edges: string[] };
+
+const SEED = Number(process.env.IX_EQUIV_SEED ?? 20261002);
+const RUNS = Number(process.env.IX_EQUIV_RUNS ?? 20);
+
+/** Variables `ingestFiles` reads that a developer's shell could have set. */
+const ENV_KEYS = [
+ "HOME", "USERPROFILE", "IX_ENDPOINT", "IX_LOCK_DIR", "IX_HOME", "IX_DEBUG",
+ "IX_COMMIT_FAILURE_LIMIT", "IX_COMMIT_HTTP_MAX_FILES", "IX_COMMIT_CONCURRENCY",
+ "IX_STITCH_COOLDOWN_MS", "IX_STITCH_WAIT_MS", "IX_MAP_DEADLINE_MS",
+] as const;
+
+/**
+ * One working tree, one backend and home for the incremental runs, and a new
+ * backend and home for each reference ingest. The tree lives at the same path
+ * for both, so both compute the same workspace id and patch ids.
+ */
+class World {
+ readonly root = realpathSync.native(mkdtempSync(join(tmpdir(), "ix-equiv-")));
+ readonly repo = join(this.root, "repo");
+ backend!: FakeBackend;
+ private home = "";
+ private endpoint = "";
+ private homes = 0;
+ /** The tree as last written, so `write` touches only what changed. */
+ private onDisk = new Map<string, string>();
+
+ constructor(private readonly semantics: Semantics) {
+ mkdirSync(this.repo);
+ // Discovery prefers `git ls-files`, which keeps the walk order fixed.
+ execFileSync("git", ["init", "-q"], { cwd: this.repo, stdio: "ignore" });
+ }
+
+ async start(): Promise<void> {
+ [this.backend, this.home, this.endpoint] = await this.newBackend();
+ }
+
+ private async newBackend(): Promise<[FakeBackend, string, string]> {
+ const backend = new FakeBackend({ semantics: this.semantics });
+ const home = join(this.root, `home${++this.homes}`);
+ mkdirSync(home);
+ return [backend, home, await backend.start()];
+ }
+
+ /** Make the working tree match `repo`, and stage it so discovery sees it. */
+ write(repo: Repo): void {
+ const want = new Map([...repo].map(([p, fns]) => [p, render(p, fns)]));
+ for (const p of this.onDisk.keys()) if (!want.has(p)) rmSync(join(this.repo, p));
+ for (const [p, text] of want) {
+ if (this.onDisk.get(p) === text) continue;
+ mkdirSync(dirname(join(this.repo, p)), { recursive: true });
+ writeFileSync(join(this.repo, p), text, "utf8");
+ }
+ this.onDisk = want;
+ execFileSync("git", ["add", "-A"], { cwd: this.repo, stdio: "ignore" });
+ }
+
+ private ingestWith(home: string, endpoint: string) {
+ process.env.HOME = home;
+ process.env.USERPROFILE = home;
+ process.env.IX_ENDPOINT = endpoint;
+ process.env.IX_LOCK_DIR = join(home, "locks");
+ return ingestFiles(this.repo, {
+ recursive: true, format: "json", printSummary: false, suppressOutput: true, mapMode: true,
+ });
+ }
+
+ /** An incremental `ix map` against the long-lived backend. */
+ map() {
+ this.backend.resetRequests();
+ return this.ingestWith(this.home, this.endpoint);
+ }
+
+ /** The graph a fresh map of the current tree writes into an empty backend. */
+ async freshSignature(): Promise<Signature> {
+ const [backend, home, endpoint] = await this.newBackend();
+ try {
+ await this.ingestWith(home, endpoint);
+ return backend.graphSignature();
+ } finally {
+ await backend.stop();
+ }
+ }
+
+ async stop(): Promise<void> {
+ try {
+ await this.backend?.stop();
+ } finally {
+ rmSync(this.root, { recursive: true, force: true });
+ }
+ }
+}
+
+/** The lines two signatures disagree on, with edge endpoints named. */
+function signatureDiff(world: World, live: Signature, want: Signature): string {
+ const named = (line: string) => {
+ const [id, src, dst, predicate] = line.split(" ");
+ return `${predicate} ${world.backend.nodeName(src!)} -> ${world.backend.nodeName(dst!)} (${id!.slice(0, 8)})`;
+ };
+ const out: string[] = [];
+ for (const key of ["nodes", "edges"] as const) {
+ const show = key === "edges" ? named : (line: string) => line;
+ const inLive = new Set(live[key]);
+ const inWant = new Set(want[key]);
+ for (const x of live[key]) if (!inWant.has(x)) out.push(`stale ${show(x)}`);
+ for (const x of want[key]) if (!inLive.has(x)) out.push(`missing ${show(x)}`);
+ }
+ return out.join("\n");
+}
+
+/**
+ * Map the initial tree, map again after each edit, then compare the live graph
+ * with a fresh map of the final tree. `check` runs after the last map, before
+ * the comparison.
+ */
+async function runSequence(
+ semantics: Semantics,
+ edits: Edit[],
+ opts: { langs?: Lang[]; check?: (world: World) => void } = {},
+): Promise<void> {
+ const world = new World(semantics);
+ try {
+ await world.start();
+ let repo = initialRepo();
+ const history: Repo[] = [repo];
+ world.write(repo);
+ await world.map();
+ for (const edit of edits) {
+ for (const state of applyEdit(repo, edit, history, opts.langs)) {
+ repo = state;
+ history.push(repo);
+ world.write(repo);
+ await world.map();
+ }
+ }
+ opts.check?.(world);
+ const live = world.backend.graphSignature();
+ const want = await world.freshSignature();
+ expect(signatureDiff(world, live, want), `graph after ${JSON.stringify(edits)} differs from a fresh map`).toBe("");
+ } finally {
+ await world.stop();
+ }
+}
+
+const edit = (kind: EditKind, path?: string, b = 0): Edit => ({ kind, a: 0, b, path });
+
+function property(semantics: Semantics, kinds: readonly EditKind[], langs?: Lang[]): Promise<void> {
+ const edits = fc.array(
+ fc.record({ kind: fc.constantFrom(...kinds), a: fc.nat(60), b: fc.nat(60) }),
+ { minLength: 1, maxLength: 3 },
+ );
+ return fc.assert(
+ fc.asyncProperty(edits, (es) => runSequence(semantics, es, { langs })),
+ { numRuns: RUNS, seed: SEED },
+ );
+}
+
+describe("incremental ix map equals a fresh map (fake backend)", () => {
+ // Generous, because each property is a few hundred real ingests. Each one
+ // takes about 0.2 s here.
+ vi.setConfig({ testTimeout: 300_000 });
+
+ const saved: Record<string, string | undefined> = {};
+ beforeAll(() => {
+ for (const k of ENV_KEYS) {
+ saved[k] = process.env[k];
+ delete process.env[k];
+ }
+ });
+ afterAll(() => {
+ for (const [k, v] of Object.entries(saved)) {
+ if (v === undefined) delete process.env[k];
+ else process.env[k] = v;
+ }
+ });
+
+ it("the harness: two fresh maps of one tree give one graph", async () => {
+ await runSequence("head", []);
+ });
+
+ it("a re-map with nothing changed commits nothing", async () => {
+ // A revert to the first state is a second map of an unchanged tree.
+ await runSequence("head", [{ kind: "revert", a: 0, b: 0 }], {
+ check: (world) => expect(world.backend.commitCount).toBe(0),
+ });
+ });
+
+ it("a body edit to a TypeScript file keeps every edge", async () => {
+ await runSequence("head", [edit("editBody", "web/calc.ts"), edit("addFunction", "web/report.ts")]);
+ });
+
+ // F-03. An edited Python or Java file is resolved against the batch of
+ // changed files alone, so its cross-file CALLS are re-pointed at phantom
+ // module nodes or dropped. TypeScript is spared by the index prescan.
+ it.fails("IN-10: a body edit to a Python or Java file keeps its cross-file edges", async () => {
+ await runSequence("head", [edit("editBody", "pkg/app.py"), edit("editBody", "src/com/ex/App.java")]);
+ });
+
+ // F-07. A new file has no backend hash, so the whole repository takes the
+ // first-ingest path and every file is parsed and sent again.
+ it.fails("IN-01: adding a file sends one patch", async () => {
+ await runSequence("head", [edit("addFile", undefined, 0)], {
+ langs: ["ts"],
+ check: (world) => {
+ const sent = world.backend.requests
+ .filter((r) => r.path === "/v1/patches/bulk" || r.path === "/v1/patch")
+ .reduce((sum, r) => sum + r.patches, 0);
+ expect(sent, "patches on the wire").toBe(1);
+ },
+ });
+ });
+
+ // F-04. Dropping the file's last import removes a node, the patch carries a
+ // DeleteNode, and a delete-bearing patch goes to `/v1/patch`, which does not
+ // sweep: the removed CALLS and IMPORTS edges stay live.
+ it.fails("IN-04: removing a file's last call retires its edges", async () => {
+ await runSequence("head", [edit("removeCall", "web/main.ts")]);
+ });
+
+ // F-03. Files that call a renamed or deleted function are unchanged, so
+ // nothing re-resolves them. Fresh, their calls are unresolved; incremental,
+ // the edges are simply gone, and after a restore they never come back.
+ it.fails("IN-11: renaming a called function re-resolves its callers", async () => {
+ await runSequence("head", [edit("renameFunction", "web/math.ts", 0)]);
+ });
+
+ it.fails("IN-11: restoring a deleted file re-binds its callers", async () => {
+ await runSequence("head", [edit("deleteThenRestore", "web/math.ts")]);
+ });
+
+ it("a revert and a delete-then-restore re-apply, on a backend with BEW-03", async () => {
+ await runSequence("head", [edit("addFunction", "web/main.ts"), { kind: "revert", a: 0, b: 0 }]);
+ await runSequence("head", [edit("deleteThenRestore", "web/main.ts")]);
+ });
+
+ // F-01, on the backend as shipped. The reverted file's patch id was
+ // committed before, so the backend answers Idempotent, writes nothing, and
+ // the graph keeps the edit. BEW-03 fixes it in the backend and IN-02 makes
+ // the CLI report it. This one stays marked: `legacy` is the old backend.
+ it.fails("F-01: a revert is lost on a backend without BEW-03", async () => {
+ await runSequence("legacy", [edit("addFunction", "web/main.ts"), { kind: "revert", a: 0, b: 0 }]);
+ });
+
+ it("random TypeScript edits that add or change code", async () => {
+ await property("head", ["editBody", "addFunction", "addCall", "addFile"], ["ts"]);
+ });
+
+ // The acceptance gate for the F-03 chain: IN-04, IN-10 and IN-11. The last
+ // of them to land deletes this marker.
+ it.fails("IN-11: random edit sequences of every kind", async () => {
+ await property("head", EDIT_KINDS);
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/ingest-files.test.ts b/ix-cli/src/cli/__tests__/ingest-files.test.ts
index b4bfdb36..4ca92700 100644
--- a/ix-cli/src/cli/__tests__/ingest-files.test.ts
+++ b/ix-cli/src/cli/__tests__/ingest-files.test.ts
@@ -1,8 +1,6 @@
// Copyright 2026 Ix Infrastructure Inc.
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createServer, type Server, type ServerResponse } from "node:http";
-import type { AddressInfo } from "node:net";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -11,6 +9,7 @@ import { execFileSync } from "node:child_process";
import { ingestFiles } from "../commands/ingest.js";
import { ingestMtimeCachePath, ingestRebuildPath, loadConfig } from "../config.js";
import { workspaceIdForPath } from "../system.js";
+import { FakeBackend } from "./helpers/fake-backend.js";
/**
* Integration tests that drive `ingestFiles` end to end against a fake backend.
@@ -44,312 +43,6 @@ import { workspaceIdForPath } from "../system.js";
* deliberate: coarse wiring here, decision tables there.
*/
-/** A backend that answers the endpoints an ingest touches, and records them. */
-class FakeBackend {
- readonly requests: Array<{ path: string; patches: number; code?: number }> = [];
- /** `source.uri` of every patch sent in a commit request, accepted or not. */
- readonly sourceUris: string[] = [];
- /** `source.workspaceId` beside each of `sourceUris`, in the same order. */
- readonly sourceWorkspaceIds: Array<string | undefined> = [];
- /** The ops of the last patch sent for each `source.uri`. */
- readonly lastOps = new Map<string, Array<Record<string, unknown>>>();
- /** Paths this fake does not implement. Asserted empty after every test. */
- readonly unknownPaths: string[] = [];
-
- private server: Server | undefined;
- private rev = 0;
-
- /** Patch-source substrings this backend refuses, whatever else is healthy. */
- poison: string[] = [];
- /** Fail every commit, the Ix#560 shape. */
- refuseEverything = false;
- /** Refuse re-sends of patches a 409 already confirmed. */
- refuseReplays = false;
- /**
- * Answer the CUTOFF DRAIN's bulk with `BaseRevMismatch`, and nothing else.
- *
- * A 200 that wrote nothing: the backend read the latest rev outside the
- * transaction and it moved before the commit ran. Without a knob the harness
- * could only ever serve "Ok", so every `status` branch in the three commit
- * sites was unreachable from any test.
- *
- * Aimed at the drain specifically, by shape rather than by counting
- * requests. The drain is the only bulk that happens AFTER the per-file
- * fan-out, so "a bulk with at least one single behind it" names it exactly,
- * and stays right if the number of requests before it ever changes.
- */
- mismatchOnDrainBulk = false;
- /**
- * Answer this many commits (bulk or single) `BaseRevMismatch` before taking
- * any: what a second `ix map` committing to the same backend does to this
- * one. A 200 that wrote nothing, like `mismatchOnDrainBulk`.
- */
- loseBaseRevRaces = 0;
- /**
- * Refuse the opening bulk and every per-file send, but ACCEPT the drain.
- *
- * The only shape that reaches an accepted cutoff drain, and it took three
- * tries to find because each failed one looked plausible. Poisoning files
- * does not work: the cutoff holds the patches that FAILED as well as the
- * untried ones, so the drain carries the poison and is refused. Refusing by
- * request count does not work either: the cutoff trips on the fifth failure
- * and the drain follows immediately, so any threshold high enough to produce
- * five failures is still in force when the drain arrives. Both were measured
- * at zero accepted bulks in the whole run, via `acceptedBulks()`.
- *
- * Refusing by KIND separates them: the opening bulk (no singles behind it)
- * and every single are refused, which trips the cutoff; the drain is the only
- * bulk with singles behind it, and it is answered 200 -- so the code that
- * reads its status is finally reached.
- */
- refuseUntilDrain = false;
- /** Fired after `abortAfterCommits` commit requests, if set. */
- abortAfterCommits: number | undefined;
- private readonly aborter = new AbortController();
-
- /** A run deadline that fires at a known POINT IN THE COMMIT SEQUENCE. */
- get deadlineSignal(): AbortSignal {
- return this.aborter.signal;
- }
- /** Answer a bulk with 409 naming every patch as already committed. */
- bulk409AllLanded = false;
- /** Status for POST /v1/stitch. */
- stitchStatus = 200;
- /**
- * Answer `/v1/source-hashes` with the hashes of patches this fake accepted,
- * as the real backend does. Off by default: with it off every lookup is
- * empty, so the DB-reset guard sends each incremental run down the full
- * path, which the tests written before it rely on.
- */
- rememberHashes = false;
- /** Answer `/v1/source-hashes` with a 500, as a backend under load does. */
- failSourceHashes = false;
- private readonly hashes = new Map<string, { workspaceId: string | null; uri: string; hash: string }>();
-
- /** Forget every request so far, so a second run can be measured on its own. */
- resetRequests(): void {
- this.requests.splice(0, this.requests.length);
- }
-
- get stitchCount(): number {
- return this.requests.filter((r) => r.path === "/v1/stitch").length;
- }
-
- /** Patches in commit requests the backend ACCEPTED. */
- acceptedPatches(): number {
- return this.requests
- .filter(r => (r.path === "/v1/patches/bulk" || r.path === "/v1/patch") && r.code === 200)
- .reduce((sum, r) => sum + r.patches, 0);
- }
-
- /** Bulk commits that the backend ACCEPTED, in order. */
- acceptedBulks(): number {
- return this.requests.filter(r => r.path === "/v1/patches/bulk" && r.code === 200).length;
- }
-
- get bulkCount(): number {
- return this.requests.filter((r) => r.path === "/v1/patches/bulk").length;
- }
-
- get singleCount(): number {
- return this.requests.filter((r) => r.path === "/v1/patch").length;
- }
-
- get commitCount(): number {
- return this.bulkCount + this.singleCount;
- }
-
- async start(): Promise<string> {
- this.server = createServer((req, res) => {
- // Collect and concat, rather than `body += chunk`. Appending a Buffer to
- // a string decodes each TCP chunk on its own, so a multi-byte character
- // split across a chunk boundary is corrupted -- and a bulk body for
- // thirty patches is comfortably big enough to be split. Latent while the
- // fixtures are ASCII; the first non-ASCII one would make `JSON.parse`
- // throw and silently route the request down a different branch.
- const chunks: Buffer[] = [];
- req.on("data", (c: Buffer) => chunks.push(c));
- req.on("end", () => this.route(req.url ?? "/", Buffer.concat(chunks).toString("utf8"), res));
- });
- await new Promise<void>((resolve, reject) => {
- // Without the `error` listener a failed bind -- EACCES under a
- // restrictive sandbox, EADDRNOTAVAIL where loopback is unusual -- never
- // settles this promise, and surfaces as a beforeEach hook timeout plus an
- // unhandled 'error' event rather than as the bind error it is.
- this.server!.once("error", reject);
- this.server!.listen(0, "127.0.0.1", resolve);
- });
- return `http://127.0.0.1:${(this.server!.address() as AddressInfo).port}`;
- }
-
- async stop(): Promise<void> {
- if (!this.server) return;
- const server = this.server;
- // `closeAllConnections` first, and a deadline behind it. `close()` waits for
- // every open socket, so one keep-alive connection the run did not finish
- // with leaves this pending -- and a hook that never settles takes its
- // timeout, at which point NEITHER `finally` in the teardown runs and both
- // temp trees leak anyway. The teardown can only be made safe if this cannot
- // hang, so the fix belongs here rather than in another `try`.
- // Not optional-chained: `engines.node` is >=22 and this landed in 18.2.
- server.closeAllConnections();
- let timer: ReturnType<typeof setTimeout> | undefined;
- const closed = await Promise.race([
- new Promise<boolean>((resolve) => server.close(() => resolve(true))),
- new Promise<boolean>((resolve) => {
- timer = setTimeout(() => resolve(false), 2000);
- timer.unref?.();
- }),
- ]);
- clearTimeout(timer);
- if (!closed) {
- // Not expected to fire, and it never has. `Promise.race` builds its
- // array eagerly, so `server.close()` runs in the SAME tick as
- // `closeAllConnections()` above -- the listening handle is gone before
- // any later turn of the loop, so nothing can connect afterwards, and
- // every socket that existed has been destroyed. There is no "late
- // socket" story; an earlier revision of this comment invented one.
- //
- // Kept anyway, as a backstop against `close()` simply never calling
- // back -- a socket wedged in destroy, say. Deliberately a message and
- // not a throw: the alternative it exists to prevent is a hook that
- // never settles, which takes the hook timeout and runs NEITHER
- // `finally` below, leaking both trees and leaving the env pointed at a
- // deleted home. A leak that announces itself is the better trade.
- process.stderr.write(
- "FakeBackend.stop: close() did not call back within 2s; the server handle is being abandoned\n",
- );
- }
- }
-
- private route(url: string, body: string, res: ServerResponse): void {
- const path = new URL(url, "http://x").pathname;
- const send = (code: number, payload: unknown): void => {
- // Stamp the answer onto the request that produced it. Whether a bulk was
- // ACCEPTED or refused is the difference between two completely different
- // code paths in `ingestFiles`, and a test that assumes the wrong one is
- // measuring nothing -- which is exactly how the drain test below first
- // went wrong.
- const last = this.requests[this.requests.length - 1];
- if (last !== undefined && last.code === undefined) last.code = code;
- res.writeHead(code, { "Content-Type": "application/json" });
- res.end(JSON.stringify(payload));
- };
-
- if (path === "/v1/patches/bulk" || path === "/v1/patch") {
- type SentPatch = {
- patchId?: string;
- source?: { uri?: string; sourceHash?: string; workspaceId?: string };
- ops?: Array<Record<string, unknown>>;
- };
- let patches: SentPatch[] = [];
- try {
- const parsed = JSON.parse(body) as { patches?: SentPatch[] };
- patches = parsed.patches ?? [parsed as SentPatch];
- } catch {
- /* a body we cannot read is still a request */
- }
- this.requests.push({ path, patches: patches.length });
- for (const { source, ops } of patches) {
- if (!source?.uri) continue;
- this.sourceUris.push(source.uri);
- this.sourceWorkspaceIds.push(source.workspaceId);
- this.lastOps.set(source.uri, ops ?? []);
- }
- if (this.abortAfterCommits !== undefined && this.commitCount >= this.abortAfterCommits) {
- this.aborter.abort();
- }
-
- if (path === "/v1/patch" && this.refuseReplays) {
- return send(500, { error: "500: already committed" });
- }
- if (path === "/v1/patches/bulk" && this.bulk409AllLanded) {
- const ids = patches.map((p) => p.patchId).filter(Boolean);
- return send(409, { error: "bulk group partially committed", committed_patch_ids: ids });
- }
- // Ahead of the poison check, deliberately. The drain carries the patches
- // the cutoff held back, which for any fixture that trips the cutoff
- // includes the poisoned ones -- so the poison branch answered 500 and the
- // drain never reached the success path at all. A first attempt at this
- // set the status further down and measured nothing, because no bulk in
- // the test ever got there.
- const isDrainBulk = path === "/v1/patches/bulk" && this.singleCount > 0;
- if (this.loseBaseRevRaces > 0) {
- this.loseBaseRevRaces--;
- return send(200, { rev: this.rev, applied: 0, status: "BaseRevMismatch" });
- }
- if (this.mismatchOnDrainBulk && isDrainBulk) {
- // A 200 that wrote NOTHING: the backend read the latest rev outside the
- // transaction and it moved before the commit ran. `applied: 0` and the
- // rev deliberately left where it was, because nothing landed.
- return send(200, { rev: this.rev, applied: 0, status: "BaseRevMismatch" });
- }
- const refused =
- this.refuseEverything ||
- (this.refuseUntilDrain && !isDrainBulk) ||
- this.poison.some((p) => body.includes(p));
- // Answered synchronously. A `commitDelayMs` knob lived here and no test
- // ever set it -- the deadline test fires off request COUNT instead, which
- // is what makes it deterministic. Reviving it needs care rather than a
- // one-liner: `stop()` resolves on `server.close()` without cancelling a
- // pending timer, so a deferred response outlives the test that armed it
- // and fires against a closed server.
- if (refused) return send(500, { error: "500: transaction begin timeout" });
- this.rev += patches.length || 1;
- if (this.rememberHashes) {
- for (const { source } of patches) {
- if (source?.uri && source.sourceHash) {
- this.hashes.set(`${source.workspaceId ?? ""}\0${source.uri}`,
- { workspaceId: source.workspaceId ?? null, uri: source.uri, hash: source.sourceHash });
- }
- }
- }
- // `status` included, because `PatchCommitResult` declares it required and
- // the ingest path branches on it. Serving 200s without it left
- // `result.status` undefined everywhere, so this fake could never produce
- // an `Idempotent` or `BaseRevMismatch` answer -- the two branches that
- // decide whether a patch lands in `patchesApplied` or `commitErrors`, and
- // so whether the mtime baseline is written at all. A regression that
- // flipped the applied test from "not BaseRevMismatch" to `=== "Ok"` would
- // have counted zero patches applied against the real backend while every
- // test here stayed green.
- send(
- 200,
- path === "/v1/patches/bulk"
- ? { rev: this.rev, applied: patches.length, status: "Ok" }
- : { rev: this.rev, status: "Ok" },
- );
- return;
- }
-
- if (path === "/v1/health") return send(200, { status: "ok", version: "1.0.28" });
- if (path === "/v1/source-hashes") {
- if (this.failSourceHashes) return send(500, { error: "500: transaction begin timeout" });
- if (!this.rememberHashes) return send(200, []);
- let uris: string[] = [];
- try { uris = (JSON.parse(body) as { uris?: string[] }).uris ?? []; } catch { /* none */ }
- const wanted = new Set(uris);
- return send(200, [...this.hashes.values()].filter((row) => wanted.has(row.uri)));
- }
- if (path.startsWith("/v1/stitch/system/")) return send(200, { systemId: null });
- if (path === "/v1/stitch") {
- this.requests.push({ path, patches: 0 });
- if (this.stitchStatus !== 200)
- return send(this.stitchStatus, { error: "AQL: query timed out" });
- return send(200, { stitched: 0, systemId: null, edges: [] });
- }
- // 404, not `200 {}`. A fake that answers every unrecognised path with a
- // cheerful empty body cannot fail: product code that starts calling a new
- // endpoint -- or mistypes an existing one -- gets a success here where the
- // real backend would 404, and the harness stays green while measuring a
- // request the backend never served. The path is recorded as well as
- // refused, so the afterEach names it rather than leaving a stray 404 to be
- // explained.
- this.unknownPaths.push(path);
- return send(404, { error: `404: no such endpoint ${path}` });
- }
-}
-
describe("ingestFiles against a fake backend", () => {
// Every test here runs a REAL ingest -- discovery, a worker-thread parse
// pool, and an HTTP round trip per commit -- against 30 files. On an idle