Skip to content

armgit / Ix

Public Imported from GitHub
0

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

98.8 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { execFileSync } from "node:child_process";

import { ingestFiles, ingestPathSingleFlight } from "../commands/ingest.js";
import { acquireMapLock, takeMapRerun } from "../single-flight.js";
import { ingestMtimeCachePath, ingestRebuildPath, ingestSymbolsJournalPath, ingestSymbolsPath, loadConfig } from "../config.js";
import { workspaceIdForPath } from "../system.js";
import { ensureWorkspaceRegistered } from "../bootstrap.js";
import { FakeBackend } from "./helpers/fake-backend.js";
import { runWithSignal } from "../../client/run-signal.js";
import { loadIngestBaseline } from "../ingest-baseline.js";
import { loadIngestSymbols } from "../ingest-symbols.js";
import { detectStaleFiles } from "../stale.js";
import { renderStatusLlm } from "../commands/status.js";

/**
 * Integration tests that drive `ingestFiles` end to end against a fake backend.
 *
 * They exist because that function is where every mechanical defect in Ix#560
 * and Ix#568 lived, and none of them were reachable from a unit test. The
 * decision tables were extracted (`perFileAction`, `drainInPasses`,
 * `createDrainGate`) and each extraction immediately caught a bug -- but the
 * WIRING between them stayed untested, and that is where the next one appeared
 * every time: a counter fed from the wrong place, a list the deadline diverted
 * to, a probe that treated proof as a failure.
 *
 * Nothing is mocked. `ingestFiles` builds its own `IxClient` from
 * `getEndpoint()`, which reads `IX_ENDPOINT`, so a real HTTP server on a
 * loopback port is the whole seam -- and the request log it keeps is exactly
 * the thing the PRs' measurements were about.
 *
 * What these catch, verified by restoring the bugs and watching them go red:
 *
 *   - removing the cutoff entirely (the pre-#560 fan-out);
 *   - the drain stopping on the first pass that placed nothing, which strands
 *     every good patch between two clusters of bad ones;
 *   - the stitch marker being cleared by a failure that is not proof, which is
 *     the #568 stacking itself.
 *
 * What they do NOT catch, and are not the right tool for: the finer stopping
 * rules inside `drainInPasses` -- two-empty-passes versus three, and the
 * direction flip. Those need a held set shaped precisely, which at this level
 * means contorting a fixture until it happens to produce one. They are
 * mutation-validated directly in `commit-breaker.test.ts`, and that division is
 * deliberate: coarse wiring here, decision tables there.
 */

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
  // machine each takes about a second, comfortably inside vitest's 5s default,
  // which is why this file went in without an explicit timeout. Under the full
  // suite's parallelism that is not true: measured on `main`, the Ix#560 case
  // exceeded 5s and failed in 1 of 4 full `ix-cli` runs here, and in 3 of 3
  // when the heavier repo-root suite was running. A timeout that fires only
  // under load reads as a real regression on whichever CI leg was busiest, so
  // it is set from the work these tests actually do rather than inherited.
  vi.setConfig({ testTimeout: 30_000, hookTimeout: 30_000 });

  let home: string;
  let repo: string;
  let backend: FakeBackend;
  // The sentinel for `backend`, in the same spirit as the `""` reset that
  // `home` and `repo` get. `backend` cannot use `undefined` as its own: it is
  // read as a plain `FakeBackend` at ~35 call sites in the tests below, and
  // widening the type to make teardown honest would put a narrowing burden on
  // every one of them. So the freshness lives beside it instead. False means
  // "`backend` does not refer to THIS test's fake" -- either the first test
  // has not constructed one yet, or a `beforeEach` threw before it got there.
  let backendIsCurrent = false;
  const saved: Record<string, string | undefined> = {};

  /**
   * Write `count` trivially-parseable TypeScript files, in a KNOWN order.
   *
   * The `git init` + `git add` is load-bearing, not decoration. Discovery
   * prefers `git ls-files`, which sorts; with no repo it falls back to
   * `walkFiles`, which yields raw `readdirSync` order -- lexicographic on NTFS,
   * hash order on ext4 and APFS. The fixtures below are named for WHERE the
   * poison sits, and off Windows they would have quietly degenerated into the
   * scattered case on two of the five CI legs. The both-ends shape is the only
   * one that reproduces the drain's first-empty-pass bug, so losing it there
   * would have left that mutation uncaught precisely where nobody runs the
   * suite by hand.
   */
  function fixture(count: number): void {
    mkdirSync(join(repo, "src"), { recursive: true });
    for (let i = 0; i < count; i++) {
      const name = `m${String(i).padStart(3, "0")}.ts`;
      writeFileSync(
        join(repo, "src", name),
        `export function f${i}(): number { return ${i}; }\n`,
        "utf8",
      );
    }
    execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
  }

  /** The order discovery will actually walk — asserted, never assumed. */
  // The same flags `tryGitLsFiles` passes, not a bare `ls-files`. The two
  // agree only while `fixture()` stages everything; one unstaged file or a
  // `.gitignore` and this would validate a list discovery does not use. The
  // both-ends fixture is the only one that reproduces the drain's
  // first-empty-pass bug, so a premise check that quietly stopped matching
  // would retire that case with nothing going red.
  function discoveryOrder(): string[] {
    return execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard"], {
      cwd: repo,
      encoding: "utf8",
    })
      .split("\n")
      .filter(Boolean);
  }

  beforeEach(async () => {
    // realpath'd, because discovery canonicalises and the workspace root does
    // not. `discoverIngestFilePaths` runs `realpathSync.native` over every file
    // it finds while `workspaceRoot` stays exactly the string handed in, so the
    // moment the two disagree `toWorkspaceRelative` gives up and emits an
    // ESCAPING path. On the two macos-14 legs `os.tmpdir()` is `/var/folders/...`
    // for a real `/private/var/folders/...`, so every fixture's source_uri and
    // patch id there was `../../../private/var/...` rather than `src/m000.ts` --
    // a materially different payload on a third of the matrix, and a trap for
    // the first assertion that ever touches a uri. Windows junctions do it too.
    // `ingest-discovery.test.ts:105` already carries this fix and its reason.
    // THIS is what makes the teardown correct. The guards down there are the
    // decorative half, and an earlier version of this comment had it backwards.
    //
    // All three are describe-scoped and `afterEach` never reset them, so from
    // the second test onward they held the PREVIOUS test's values. A
    // `beforeEach` that throws anywhere in the setup then left the teardown
    // asserting against the previous test's already-stopped fake and calling
    // `rmSync` on its already-deleted paths -- a silent no-op under
    // `force: true`, so nothing went red. Clearing here is the only reason
    // each test's teardown sees its own state.
    //
    // (A throw in `mkdtempSync` itself leaks nothing, since no directory got
    // made. The leak that WAS reachable came from `realpathSync` throwing
    // after one existed, and the split assignment below is what closes it.)
    //
    // `""` rather than `undefined`, because typing these as `string |
    // undefined` costs a non-null assertion at forty use sites for no extra
    // safety -- and `rmSync("")` is a no-op on Node 26, checked, where
    // `rmSync(undefined)` throws ERR_INVALID_ARG_TYPE.
    //
    // Cleared FIRST, then set immediately after the construction it describes,
    // so the window in which `backendIsCurrent` is false is exactly the window
    // in which `backend` is stale. A statement inserted above the assignment
    // that throws now leaves the flag false and the teardown skips rather than
    // asserting against the previous test's fake and passing vacuously.
    // Constructing first is still the better position -- keep it first -- but
    // it is no longer the only thing standing between that edit and a silent
    // pass.
    backendIsCurrent = false;
    home = "";
    repo = "";
    backend = new FakeBackend();
    backendIsCurrent = true;
    // Two steps each, deliberately. `realpathSync(mkdtempSync(...))` leaves
    // nothing in `home` if the OUTER call throws -- and the directory exists
    // by then, so the `if (home)` cleanup below skips a tree that is already
    // on disk. Assigning the created path first means the variable always
    // names whatever was created, resolved or not.
    home = mkdtempSync(join(tmpdir(), "ix-ingest-home-"));
    // `.native`, as discovery canonicalises: on Windows the temp dir is an 8.3
    // name (RUNNER~1) that plain realpathSync keeps and `.native` expands, so
    // paths built from `repo` would not match the ones ingest records.
    home = realpathSync.native(home);
    repo = mkdtempSync(join(tmpdir(), "ix-ingest-repo-"));
    repo = realpathSync.native(repo);
    const endpoint = await backend.start();

    // HOME *and* USERPROFILE: `os.homedir()` reads the latter on Windows, so
    // redirecting only HOME leaves the run writing its mtime cache and
    // baselines into the developer's real ~/.ix.
    // Saved AND cleared. Recording them was not enough: every one of these is
    // read straight from the environment, so a developer who has exported
    // `IX_COMMIT_FAILURE_LIMIT=0` -- the value the CLI's own failure banner
    // tells users to set -- turns the cutoff off and makes the bounded-request
    // assertions meaningless, and `IX_COMMIT_HTTP_MAX_FILES=1` breaks the
    // one-bulk assertion outright.
    for (const k of [
      "HOME",
      "USERPROFILE",
      "IX_ENDPOINT",
      "IX_LOCK_DIR",
      "IX_COMMIT_FAILURE_LIMIT",
      "IX_COMMIT_HTTP_MAX_FILES",
      "IX_COMMIT_CONCURRENCY",
      "IX_COMMIT_CONFLICT_RETRIES",
      "IX_COMMIT_TRANSIENT_RETRY_MS",
      "IX_STITCH_COOLDOWN_MS",
      "IX_STITCH_WAIT_MS",
      "IX_MAP_DEADLINE_MS",
      "IX_PARSE_STREAM_CHUNK",
    ]) {
      saved[k] = process.env[k];
      delete process.env[k];
    }
    process.env.HOME = home;
    process.env.USERPROFILE = home;
    process.env.IX_ENDPOINT = endpoint;
    process.env.IX_LOCK_DIR = join(home, "locks");
  });

  /**
   * Remove a temp tree without letting one failure strand the next. `rmSync`
   * with `force` suppresses ENOENT only; EBUSY and EPERM still throw, and on
   * Windows they are ordinary -- a handle under `IX_LOCK_DIR` is enough. The
   * leak is reported rather than raised, because failing the teardown here
   * would mask whatever the test itself was failing on.
   */
  const removeTree = (dir: string): void => {
    if (!dir) return;
    try {
      rmSync(dir, { recursive: true, force: true });
    } catch (err) {
      process.stderr.write(`ingest-files teardown: could not remove ${dir}: ${String(err)}\n`);
    }
  };

  afterEach(async () => {
    try {
      // Every request the run made was one this fake actually implements. If
      // the ingest path grows an endpoint, this fails once with its name,
      // rather than ten tests passing against a fake that agreed with
      // everything.
      // Guarded on freshness, not on existence. `backend` is typed
      // non-nullable and holds the PREVIOUS test's fake after the first one,
      // so an `!== undefined` test here would be true in precisely the case
      // worth catching -- a `beforeEach` that threw above the assignment --
      // and would assert against the wrong object and pass.
      //
      // Be clear about what this flag is and is not. It is DORMANT: nothing
      // between the reset and the assignment can throw today, so replacing it
      // with `true` leaves the suite green, and no test covers it. What it
      // buys over the `!== undefined` it replaced is not coverage but
      // correctness WHEN it fires -- the old guard was dormant AND could not
      // have worked, since the stale fake is never `undefined`. Verified by
      // running both forms against a `beforeEach` that throws above the
      // assignment: the old one asserted twice against the first test's fake,
      // the new one skipped.
      if (backendIsCurrent) {
        expect(backend.unknownPaths, "endpoints the fake does not implement").toEqual([]);
      }
    } finally {
      // In a `finally`, because the assertion above threw straight past all of
      // this -- in exactly the case it exists for. The server stayed listening
      // (an open handle that can stop the vitest worker exiting, turning one
      // named failure into a job timeout), both temp trees leaked, and
      // `HOME`/`USERPROFILE`/`IX_ENDPOINT` stayed pointed at the fixture. Worse,
      // `saved` is shared across the describe, so the next `beforeEach`
      // snapshotted those polluted values and the file's final restore wrote
      // the fixture `HOME` back into the process.
      // And the steps do not share fate. Env first, because it is the one that
      // leaks OUT of this file: a `stop()` that REJECTS would otherwise skip it
      // and leave the whole process pointed at a deleted fixture home. Note
      // what this does NOT buy -- on a hook timeout the hook promise is rejected
      // from outside while the `await` is still pending, so no `finally` here
      // runs at all. That case is handled where it has to be, by making
      // `stop()` unable to hang. The stop is guarded on the same freshness
      // flag: a `beforeEach` that threw above the construction leaves
      // `backend` pointing at the previous test's fake, which its own
      // teardown already stopped. A throw in the `mkdtempSync` calls is a
      // different case and needs no guard of its own -- `start()` runs below
      // them, so the fake was constructed but never listened, and `stop()`
      // returns at its own `if (!this.server)`.
      for (const [k, v] of Object.entries(saved)) {
        if (v === undefined) delete process.env[k];
        else process.env[k] = v;
      }
      try {
        if (backendIsCurrent) await backend.stop();
      } finally {
        // FIRST, and before anything that can throw. The flag means
        // "constructed by the `beforeEach` for the test now running" rather
        // than "constructed at some point": without clearing it, it stays
        // `true` forever after the first test, and a file- or project-level
        // `beforeEach` added later that throws BEFORE this describe's own
        // would find it set and assert against the stale fake -- the bug,
        // through the one door the flag does not otherwise cover.
        //
        // It sat below the two removals and shared their fate, which was the
        // same mistake the outer `finally` above exists to avoid: `rmSync`
        // suppresses only ENOENT, so one EBUSY on Windows -- a lock file under
        // `IX_LOCK_DIR`, a `.git` handle -- skipped it AND the second removal.
        backendIsCurrent = false;
        // Separately, for the same reason. `removeTree` swallows per
        // directory so `home` failing cannot strand `repo`, and so a teardown
        // error cannot replace an in-flight `unknownPaths` failure and hide
        // which endpoint was unimplemented.
        //
        // The `if` inside guards exactly one case: `mkdtempSync` itself threw,
        // so nothing was created and the variable still holds the `""` from
        // the reset above. Every other failure leaves it naming a real
        // directory, which is why the assignment is split from the
        // `realpathSync` that follows it. Not a stale path from a previous
        // test -- the reset covers that, and `rmSync("")` is a no-op anyway.
        removeTree(home);
        removeTree(repo);
      }
    }
  });

  const run = () =>
    ingestFiles(repo, { format: "text", force: true, suppressOutput: true, printSummary: false });

  /**
   * A run that ends fatally. Under `suppressOutput` a fatal commit outcome is
   * raised rather than printed, so the caller sees it -- the assertion is on
   * the message and on what the backend was actually asked to do.
   */
  const runFatal = async (): Promise<string> => {
    try {
      await run();
    } catch (err) {
      return String(err);
    }
    throw new Error("expected the ingest to end fatally");
  };

  it("bounds the requests to a backend that refuses everything (Ix#560)", async () => {
    // The bug: one failed bulk became one doomed request per patch, each
    // waiting out its own timeout, against the database that is the reason
    // they fail. `main` sends 1 + N; the cutoff stops the fan-out after
    // IX_COMMIT_FAILURE_LIMIT and bounds the drain that follows.
    fixture(30);
    backend.refuseEverything = true;

    const message = await runFatal();

    expect(message, "every patch is accounted for, none silently dropped").toContain("30 of 30");
    expect(message).toContain("See the cutoff above");
    expect(backend.commitCount, "well under main's 31").toBeLessThan(25);
    expect(backend.commitCount, "and it still tried").toBeGreaterThan(1);
  });

  it("strands nothing a healthy backend would have taken (Ix#560)", async () => {
    // The invariant the whole drain design exists for, and the one four
    // successive stopping rules got wrong: on a backend refusing PARTICULAR
    // patches, the error count must equal the number of bad patches exactly.
    // Anything higher is a committable patch reported as failed without ever
    // being sent -- and since the mtime baseline is not written on a run with
    // commit errors, the next map repeats it forever.
    fixture(30);
    backend.poison = ["m005.ts", "m006.ts", "m007.ts", "m008.ts", "m009.ts"];

    const summary = await run();

    expect(summary.commitErrors).toBe(5);
    expect(summary.patchesApplied).toBe(25);
  });

  it("strands nothing when the bad patches sit at the very start", async () => {
    // The leading-cluster shape. The fan-out trips before anything succeeds,
    // so the drain has no evidence the backend is alive and must not guess
    // from a single empty pass.
    fixture(30);
    backend.poison = ["m000.ts", "m001.ts", "m002.ts", "m003.ts", "m004.ts", "m005.ts"];
    expect(discoveryOrder()[0], "the poison must actually come first").toContain("m000.ts");

    const summary = await run();

    expect(summary.commitErrors).toBe(6);
    expect(summary.patchesApplied).toBe(24);
  });

  it("strands nothing when bad patches sit at BOTH ends of the held set", async () => {
    // The shape that defeats every simpler stopping rule, and the reason the
    // drain samples three positions rather than one or two.
    //
    // Poison at the start trips the fan-out, so the held set is everything
    // after it -- good files in the middle, poison again at the tail. The drain
    // walks from the far end first, so its opening pass runs straight into the
    // trailing cluster, spends its whole budget and places NOTHING. A rule that
    // reads that as "the backend is dead" hands back every good patch between
    // the two clusters, unsent; and because the mtime baseline is never written
    // on a run with commit errors, the next map reproduces it exactly.
    fixture(30);
    backend.poison = [
      "m000.ts",
      "m001.ts",
      "m002.ts",
      "m003.ts",
      "m004.ts",
      "m005.ts",
      "m024.ts",
      "m025.ts",
      "m026.ts",
      "m027.ts",
      "m028.ts",
      "m029.ts",
    ];
    // The premise, checked rather than assumed: poison first and last.
    const order = discoveryOrder();
    expect(order[0]).toContain("m000.ts");
    expect(order[order.length - 1]).toContain("m029.ts");

    const summary = await run();

    expect(summary.commitErrors, "exactly the poison, nothing else").toBe(12);
    expect(summary.patchesApplied, "every file between the clusters").toBe(18);
  });

  it("pins the unbounded replay of a 409 that names every patch as landed", async () => {
    // Those patches are confirmed in the graph by the server's own body, so
    // re-sending them is bookkeeping -- but nothing bounded it: the full-landed
    // branch returns before its shouldStop check, so the whole chunk went out
    // one at a time behind the global mutex with no way to stop.
    fixture(30);
    backend.bulk409AllLanded = true;

    const summary = await run();

    expect(summary.patchesApplied, "confirmed landed, so not errors").toBe(30);
    expect(summary.commitErrors).toBe(0);

    // PINNED, not endorsed. On a HEALTHY backend the replay re-sends all 30 one
    // at a time even though the 409 body already named them as landed -- the
    // Ix#495 shape, and provably unnecessary work. Skipping them outright needs
    // a revision for `onCommitted` that the 409 does not carry, so it is left
    // as a known residue rather than guessed at. This number failing is the
    // signal that someone changed it deliberately.
    expect(backend.singleCount, "known residue: one re-send per confirmed patch").toBe(30);
  });

  it("bounds the replay, and counts it applied, when the re-sends fail too", async () => {
    // The case that could actually run away, and the one the previous test
    // cannot distinguish: there the healthy backend accepts every re-send, so
    // `patchesApplied` reaches 30 whether or not the 409's ids are credited.
    // Here every re-send is refused.
    //
    // Two things have to hold. The patches are still APPLIED -- the server's
    // own 409 said it holds them, so counting a failed re-send as a commit
    // error would report writes the graph has as missing and suppress the mtime
    // baseline over them. And the replay has to STOP: the full-landed branch
    // returns before its `shouldStop` check, so nothing else bounds it, and it
    // would otherwise send all 30 one at a time behind the global mutex.
    fixture(30);
    backend.bulk409AllLanded = true;
    backend.refuseReplays = true;

    const summary = await run();

    expect(summary.commitErrors, "confirmed landed, so not errors").toBe(0);
    expect(summary.patchesApplied).toBe(30);
    expect(backend.singleCount, "bounded by the failure limit, not one per patch").toBeLessThan(15);
  });

  it("counts a plan-mismatch 409's patches as landed (Ix-memory#273)", async () => {
    // The backend says every patch of the bulk is already committed, under a
    // different grouping, and names them -- without the "partially committed"
    // text the partial-commit handling used to key on. Every re-send is refused
    // here, so the only way to zero commit errors is to credit the 409's ids.
    fixture(30);
    backend.bulk409PlanMismatch = true;
    backend.refuseReplays = true;

    const summary = await run();

    expect(summary.commitErrors, "confirmed landed, so not errors").toBe(0);
    expect(summary.patchesApplied).toBe(30);
    // Never re-bulked: the same set would land on the same refused group.
    expect(backend.bulkCount).toBe(1);
  });

  it("refuses a second stitch to a backend still running the last one (Ix#568)", async () => {
    // The marker is written when a stitch STARTS and removed only on proof
    // nothing is running. A 500 is not proof -- ArangoDB keeps executing the
    // join -- so the next run must not start another.
    fixture(4);
    backend.stitchStatus = 500;

    const first = await run();
    expect(backend.stitchCount, "the first run does stitch").toBe(1);
    expect(first.stitchSkipped).toBeUndefined();

    const second = await run();

    expect(backend.stitchCount, "and the second does not").toBe(1);
    expect(second.stitchSkippedRule).toBe("cooling");
    expect(second.stitchSkipped).toContain("may still be running");
  });

  it("stitches again once the cooldown is disabled", async () => {
    // The refusal message tells the user IX_STITCH_COOLDOWN_MS=0 releases it,
    // so that has to be true of a cooldown already on disk.
    fixture(4);
    backend.stitchStatus = 500;
    await run();
    expect(backend.stitchCount).toBe(1);

    process.env.IX_STITCH_COOLDOWN_MS = "0";
    try {
      const second = await run();
      expect(backend.stitchCount).toBe(2);
      expect(second.stitchSkipped).toBeUndefined();
    } finally {
      delete process.env.IX_STITCH_COOLDOWN_MS;
    }
  });

  it("an ingest's reads are not cut off by the read deadline (CL-15)", async () => {
    // `ix ingest` passes no deadline, and an incremental run reads each changed
    // file's previous patch (GET /v1/patches/:id) only after discovery and the
    // parse, which on a real repo take minutes. A read deadline counted from
    // the client's creation would fail every one of those reads.
    const graph = new FakeBackend({ semantics: "head" });
    process.env.IX_ENDPOINT = await graph.start();
    try {
      fixture(5);
      await ingestFiles(repo, { format: "json", suppressOutput: true, printSummary: false });
      writeFileSync(join(repo, "src", "m000.ts"), "export function g0(): number { return 0; }\n", "utf8");
      graph.resetRequests();
      process.env.IX_READ_DEADLINE_MS = "1";
      const summary = await ingestFiles(repo, { format: "json", suppressOutput: true, printSummary: false });
      expect(summary.patchesApplied).toBe(1);
      expect(graph.unknownPaths).toEqual([]);
    } finally {
      delete process.env.IX_READ_DEADLINE_MS;
      await graph.stop();
    }
  });

  it("blames the clock for the clock's losses, not the backend", async () => {
    // The cutoff and the run deadline both abandon patches, and three separate
    // review rounds found them attributed to each other -- the run telling the
    // user to raise IX_MAP_DEADLINE_MS for patches the cutoff had deliberately
    // withheld, or the reverse. They are tracked in separate lists precisely so
    // this message can be right.
    //
    // The deadline is fired by the BACKEND, after a known number of commit
    // requests, rather than by a wall-clock timeout. A timeout here measured
    // discovery and parsing, not the commit phase -- on this machine the first
    // commit did not land for ~700ms, so a 420ms budget never reached the code
    // under test at all, and on a faster machine the same test would have
    // asserted the opposite branch.
    fixture(30);
    backend.refuseEverything = true;
    backend.abortAfterCommits = 3;

    const message = await (async () => {
      try {
        await ingestFiles(repo, {
          format: "text",
          force: true,
          suppressOutput: true,
          printSummary: false,
          deadlineSignal: backend.deadlineSignal,
        });
        return "";
      } catch (err) {
        return String(err);
      }
    })();

    // Exactly three requests reached the backend, so the abort landed where it
    // was aimed and the rest were stopped before they left.
    expect(backend.commitCount).toBe(3);
    // The clock's losses are reported as the clock's, and every patch is
    // accounted for. An earlier revision reported them as the cutoff's --
    // "sending them one at a time would have added load to a backend that is
    // already the reason they fail" -- for patches the cutoff never touched.
    expect(message).toContain("ran out of time");
    expect(message).toContain("30 file patches");
    expect(message).not.toContain("added load");
  });

  it("treats an `ix mcp` run's abort as the run deadline (CL-14)", async () => {
    // The same shape as the case above, but the deadline arrives the way a
    // timed-out MCP tool call delivers it: as the run signal, with no
    // `deadlineSignal` passed. The client saw it; the commit loop did not, so
    // the ingest kept sending per-file commits that the aborted signal failed
    // at once and blamed them on the backend.
    fixture(30);
    backend.refuseEverything = true;
    backend.abortAfterCommits = 3;

    const message = await runWithSignal(backend.deadlineSignal, async () => {
      try {
        await ingestFiles(repo, { format: "text", force: true, suppressOutput: true, printSummary: false });
        return "";
      } catch (err) {
        return String(err);
      }
    });

    expect(backend.commitCount).toBe(3);
    expect(message).toContain("ran out of time");
    expect(message).not.toContain("added load");
  });

  it("counts a lost base-rev race as an error on the CUTOFF DRAIN too", async () => {
    // A backend can answer 200 and still have written nothing: `BaseRevMismatch`
    // means it read the latest rev outside the transaction and the rev moved
    // before the commit ran. `onBulkCommitted` and the per-file path both guard
    // that; the cutoff drain added for Ix#571 did not, and counted the whole
    // chunk as applied.
    //
    // Why that is worse than a wrong number: `commitErrors` staying at zero is
    // exactly the condition `persistIngestBaselineIfClean` requires, so the run
    // writes an mtime baseline for files the graph never received and every
    // later incremental map skips them as unchanged. Silent, and recoverable
    // only with `--force`.
    //
    // Reaching an ACCEPTED drain took three tries, each of which measured the
    // wrong thing until `acceptedBulks()` was added to check the premise --
    // see `refuseUntilDrain`. The sequence this produces is:
    //
    //   BULK:30 => 500     the opening bulk, refused
    //   one:1   => 500     x5, refused, which trips the cutoff
    //   BULK:25 => 200     the drain, ACCEPTED -- the request under test
    fixture(30);
    backend.refuseUntilDrain = true;

    const clean = await run();
    // The premise, checked rather than assumed: a drain bulk was accepted, and
    // it is what placed the patches.
    expect(backend.acceptedBulks(), "the drain bulk must be ACCEPTED").toBe(1);
    expect(clean.patchesApplied, "the drain placed the held patches").toBe(25);

    // Same fixture, same refusals, same `--force` re-ingest. The ONLY thing
    // that changes is the status the accepted drain answers with.
    backend.resetRequests();
    backend.mismatchOnDrainBulk = true;
    const message = await runFatal();

    // Nothing landed, so the run must say so and end fatally. Without the
    // guard the 25 patches the backend declined to write are counted as
    // applied, the run reports the same 5 errors as the clean case, exits 0 --
    // and `runFatal` fails with "expected the ingest to end fatally", which is
    // this test's real assertion.
    expect(message).toContain("30 of 30");
  });

  it("re-ingests everything once when the baseline names another extractor", async () => {
    // `ix map` skips files by mtime and source hash, and neither sees an
    // extractor bump, so the baseline records the extractor and a change
    // forces one full re-ingest. Asserted through the notice and the stored
    // name: this fake answers no source hashes, so its DB-reset guard makes
    // every incremental run look forced anyway.
    fixture(3);
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const stored = () =>
      JSON.parse(readFileSync(ingestMtimeCachePath(repo), "utf8")) as { extractor?: string };
    const notices = (): string[] =>
      stderr.mock.calls.map(([chunk]) => String(chunk)).filter(c => c.includes("[extractor changed]"));
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    try {
      await incremental();
      const current = stored().extractor;
      expect(current, "a clean run records its extractor").toMatch(/^tree-sitter\//);
      expect(notices(), "a first run has no baseline to compare").toEqual([]);

      writeFileSync(ingestMtimeCachePath(repo), JSON.stringify({ ...stored(), extractor: "tree-sitter/0.1" }));
      await incremental();
      expect(notices()).toEqual([expect.stringContaining(`tree-sitter/0.1 -> ${current}`)]);
      expect(stored().extractor).toBe(current);

      await incremental();
      expect(notices(), "the new name was recorded, so it happens once").toHaveLength(1);

      const { extractor: _dropped, ...unrecorded } = stored();
      writeFileSync(ingestMtimeCachePath(repo), JSON.stringify(unrecorded));
      await incremental();
      expect(notices()[1], "a baseline from before this was recorded").toContain(`unrecorded -> ${current}`);

      writeFileSync(ingestMtimeCachePath(repo), JSON.stringify({ ...stored(), extractor: "tree-sitter/0.1" }));
      await ingestFiles(repo, { format: "text", lang: "typescript", suppressOutput: true, printSummary: false });
      expect(stored().extractor, "a --lang run must not vouch for the other languages").toBe("tree-sitter/0.1");

      writeFileSync(join(repo, "root.ts"), "export const r = 1;\n", "utf8");
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
      await incremental();
      writeFileSync(ingestMtimeCachePath(repo), JSON.stringify({ ...stored(), extractor: "tree-sitter/0.1" }));
      await ingestFiles(join(repo, "root.ts"), { format: "text", suppressOutput: true, printSummary: false });
      expect(stored().extractor, "a single-file run must not vouch for the rest").toBe("tree-sitter/0.1");
    } finally {
      stderr.mockRestore();
    }
  });

  it("resumes an extractor re-ingest that was cut short instead of starting over", async () => {
    // The re-ingest an extractor change forces takes about twice a first map,
    // and an editor hook with a timeout can cut it short. The baseline is only
    // written by a run that finishes, so without recorded progress every later
    // run started over -- and could be cut short at the same point, forever.
    fixture(30);
    backend.rememberHashes = true;
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const stored = () =>
      JSON.parse(readFileSync(ingestMtimeCachePath(repo), "utf8")) as { extractor?: string };
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    try {
      await incremental();
      const current = stored().extractor;
      writeFileSync(ingestMtimeCachePath(repo), JSON.stringify({ ...stored(), extractor: "tree-sitter/0.1" }));

      // Cut short: three files' patches never land, so the run cannot finish.
      backend.resetRequests();
      backend.poison = ["m007.ts", "m015.ts", "m023.ts"];
      await incremental().catch(() => undefined);
      expect(stored().extractor, "an unfinished re-ingest must not vouch for the new extractor").toBe("tree-sitter/0.1");
      expect(existsSync(ingestRebuildPath(repo)), "what landed is recorded").toBe(true);

      backend.resetRequests();
      backend.poison = [];
      await incremental();
      const notices = stderr.mock.calls.map(([chunk]) => String(chunk)).filter(c => c.includes("[extractor changed]"));
      expect(notices.at(-1)).toContain("Resuming the re-ingest: 27 of 30 files already done.");
      expect(backend.acceptedPatches(), "only the three that never landed are sent again").toBe(3);
      expect(stored().extractor).toBe(current);
      expect(existsSync(ingestRebuildPath(repo)), "a finished re-ingest leaves no progress behind").toBe(false);
    } finally {
      stderr.mockRestore();
    }
  });

  it("keeps a deletion it could not clean up in the baseline, so the next run retries it", async () => {
    // A failed hash lookup with deletions pending drops them for this run. The
    // baseline it then wrote came from the files still on disk, so it no
    // longer named the deleted file: no later run could find it deleted, and
    // its nodes stayed in the graph for good.
    fixture(3);
    backend.rememberHashes = true;
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const baselineFiles = () =>
      Object.keys((JSON.parse(readFileSync(ingestMtimeCachePath(repo), "utf8")) as { files: Record<string, number> }).files);
    const deleted = join(repo, "src", "m001.ts");

    await incremental();
    expect(baselineFiles()).toContain(deleted);

    rmSync(deleted);
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    backend.failSourceHashes = true;
    await incremental();

    expect(baselineFiles(), "the skipped deletion is still pending").toContain(deleted);
    expect(baselineFiles()).toEqual(expect.arrayContaining([join(repo, "src", "m000.ts"), join(repo, "src", "m002.ts")]));
  });

  it("names a file whose parse runs past the budget, ingests the rest, and retries it until it lands", async () => {
    // About 2.5 s of parsing, under the 1 MB cap, against a 1 s budget.
    // Whichever gives up first -- the worker's own check or the pool's
    // backstop at twice the budget --
    // the file must be named, not folded silently into "unparsed".
    fixture(3);
    const calls = Array.from({ length: 60_000 }, (_, i) => `  foo(${i});`);
    writeFileSync(join(repo, "src", "huge.ts"), [`import { foo } from './m000';`, "export function big() {", ...calls, "}"].join("\n"), "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const saved = process.env.IX_PARSE_BUDGET_MS;
    process.env.IX_PARSE_BUDGET_MS = "1000";
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    try {
      const summary = await ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });

      expect(summary.parseTimeouts).toEqual(["src/huge.ts"]);
      expect(backend.acceptedPatches(), "the other three still land").toBe(3);
      expect(stderr.mock.calls.map(([c]) => String(c)).join("")).toContain("src/huge.ts");

      // Skipped, not settled: it used to be recorded clean, so every later run
      // skipped it as unchanged while status called the graph current.
      const huge = join(repo, "src", "huge.ts");
      const stored = loadIngestBaseline(repo)!;
      expect(stored.files.has(huge), "not recorded as ingested").toBe(false);
      expect(stored.parseTimeouts).toEqual(["src/huge.ts"]);
      expect(stored.pendingFiles).toEqual([]);
      const status = detectStaleFiles(repo);
      expect(status.parseTimeouts).toEqual(["src/huge.ts"]);
      expect(status.staleFiles, "named once, as a timeout").toBe(0);
      const llm = renderStatusLlm("ok", "x", status);
      expect(llm[0]).toContain("parse_timeouts=1");
      expect(llm[0]).toContain("stale=true");

      // With the budget off, the next run parses it and the warning goes.
      process.env.IX_PARSE_BUDGET_MS = "0";
      expect(backend.sourceUris).not.toContain("src/huge.ts");
      const next = await ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
      expect(next.parseTimeouts).toEqual([]);
      expect(backend.sourceUris, "retried, not skipped as unchanged").toContain("src/huge.ts");
      expect(loadIngestBaseline(repo)!.files.get(huge)).toBe(statSync(huge).mtimeMs);
      expect(loadIngestBaseline(repo)!.parseTimeouts).toEqual([]);
      expect(detectStaleFiles(repo).parseTimeouts).toEqual([]);
    } finally {
      stderr.mockRestore();
      if (saved === undefined) delete process.env.IX_PARSE_BUDGET_MS;
      else process.env.IX_PARSE_BUDGET_MS = saved;
    }
  });

  describe("a file the backend has never seen is an incremental change", () => {
    // A new file has no source hash on the backend, so `knownHashes` came back
    // empty and the whole repository took the first-ingest path: every file
    // re-read, re-parsed and re-sent to add one.
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const stage = () => execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });

    beforeEach(() => {
      fixture(16);
      backend.rememberHashes = true;
    });

    it("adding one file sends one patch", async () => {
      await incremental();
      writeFileSync(join(repo, "src", "added.ts"), "export const added = 1;\n", "utf8");
      stage();
      backend.resetRequests();

      const summary = await incremental();

      expect(backend.acceptedPatches(), "patches on the wire").toBe(1);
      expect(backend.commitCount).toBe(1);
      expect(summary.filesSkippedAsUnchanged).toBe(16);
      expect(summary.filesDiscovered).toBe(17);
    });

    it("adding one Python file sends one patch", async () => {
      // Until IN-10 a new file outside the index-prescan languages forced the
      // whole-repository pass. The symbol table covers every language, so a
      // new Python file takes the incremental path like a TypeScript one.
      await incremental();
      writeFileSync(join(repo, "src", "added.py"), "def added():\n    return 1\n", "utf8");
      stage();
      backend.resetRequests();

      const summary = await incremental();

      expect(backend.acceptedPatches(), "patches on the wire").toBe(1);
      expect(backend.commitCount).toBe(1);
      expect(summary.filesSkippedAsUnchanged).toBe(16);
      expect(summary.filesDiscovered).toBe(17);
    });

    it("an empty file that gains content sends one patch", async () => {
      writeFileSync(join(repo, "src", "empty.ts"), "", "utf8");
      stage();
      await incremental();
      writeFileSync(join(repo, "src", "empty.ts"), "export const filled = 1;\n", "utf8");
      backend.resetRequests();

      const summary = await incremental();

      expect(backend.acceptedPatches()).toBe(1);
      expect(summary.filesSkippedAsUnchanged).toBe(16);
    });

    it("a file that shrinks under the size cap sends one patch", async () => {
      writeFileSync(join(repo, "src", "big.ts"), `export const big = "${"x".repeat(1024 * 1024)}";\n`, "utf8");
      stage();
      await incremental();
      writeFileSync(join(repo, "src", "big.ts"), "export const big = 'small';\n", "utf8");
      backend.resetRequests();

      const summary = await incremental();

      expect(backend.acceptedPatches()).toBe(1);
      expect(summary.filesSkippedAsUnchanged).toBe(16);
    });

    it("a wiped backend still re-sends everything", async () => {
      await incremental();
      writeFileSync(join(repo, "src", "added.ts"), "export const added = 1;\n", "utf8");
      stage();
      backend.rememberHashes = false;
      backend.resetRequests();

      await incremental();

      expect(backend.acceptedPatches(), "the DB-reset guard empties the baseline").toBe(17);
    });
  });

  describe("a changed file the backend answers Idempotent is reported, not marked clean (F-01)", () => {
    // A revert sends the patch id the backend committed for the original
    // bytes. The shipped backend replays any id it has seen, so it answers
    // `Idempotent`, writes nothing, and the graph keeps the edit -- while the
    // CLI used to count the patch as applied, record the file as clean, and
    // let `ix status` say the graph was up to date.
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const target = () => join(repo, "src", "m003.ts");
    let tick = Date.now();
    /** Write and give the file an mtime no earlier write can share. */
    const write = (text: string) => {
      writeFileSync(target(), text, "utf8");
      tick += 10_000;
      utimesSync(target(), new Date(tick), new Date(tick));
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    };
    const stored = () => loadIngestBaseline(repo)!;
    let stderr: ReturnType<typeof vi.spyOn>;
    const warnings = (): string[] =>
      stderr.mock.calls.map((call: unknown[]) => String(call[0])).filter((c: string) => c.includes("Graph is unverified"));

    beforeEach(() => {
      fixture(16);
      stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
      // Earlier tests in this file end runs that set it.
      process.exitCode = undefined;
    });
    afterEach(() => {
      stderr.mockRestore();
      process.exitCode = undefined;
    });

    const revert = async () => {
      const original = readFileSync(target(), "utf8");
      await incremental();
      write("export function f3(): number { return 33; }\n");
      await incremental();
      write(original);
      backend.resetRequests();
      return incremental();
    };

    it("a revert on a backend without BEW-03 is named and stays dirty", async () => {
      backend.semantics = "legacy";

      const summary = await revert();

      expect(backend.commitCount, "the revert was sent").toBeGreaterThan(0);
      expect(summary.replayedChanges).toEqual(["src/m003.ts"]);
      expect(warnings().join("")).toContain("src/m003.ts");
      expect(process.exitCode, "a warning, not a failure").not.toBe(1);
      expect(stored().replayedFiles).toEqual(["src/m003.ts"]);
      expect(stored().files.get(target()), "kept dirty for the next run").not.toBe(statSync(target()).mtimeMs);

      const status = detectStaleFiles(repo);
      expect(status.replayedFiles).toEqual(["src/m003.ts"]);
      expect(renderStatusLlm("ok", "x", status)[0]).toContain("stale=true");

      // The next run tries again rather than calling the file unchanged.
      backend.resetRequests();
      const next = await incremental();
      expect(next.filesSkippedAsUnchanged).toBe(15);
      expect(next.replayedChanges).toEqual(["src/m003.ts"]);
    });

    it("a revert on a backend with BEW-03 is applied and nothing is reported", async () => {
      backend.semantics = "head";

      const summary = await revert();

      expect(summary.replayedChanges).toEqual([]);
      expect(warnings()).toEqual([]);
      expect(stored().replayedFiles).toEqual([]);
      expect(stored().files.get(target())).toBe(statSync(target()).mtimeMs);
    });

    it("a restored file on a backend without BEW-03 is named", async () => {
      backend.semantics = "legacy";
      const original = readFileSync(target(), "utf8");
      await incremental();
      rmSync(target());
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
      await incremental();
      write(original);

      const summary = await incremental();

      expect(summary.replayedChanges).toEqual(["src/m003.ts"]);
    });

    it("an unchanged file answered Idempotent is not reported", async () => {
      // --force re-sends every file; replays of unchanged content are fine.
      backend.semantics = "legacy";
      await incremental();

      const summary = await ingestFiles(repo, { format: "text", force: true, suppressOutput: true, printSummary: false });

      expect(summary.idempotentPatches).toBeGreaterThan(0);
      expect(summary.replayedChanges).toEqual([]);
    });
  });

  describe("one failing file does not stop the baseline", () => {
    // The baseline used to be written only by a clean run. One unreadable file
    // then meant no run ever recorded anything again: every map re-read the
    // whole workspace, and deleted files were never retracted.
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const stage = () => execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const stored = () => loadIngestBaseline(repo)!;
    let stderr: ReturnType<typeof vi.spyOn>;
    beforeEach(() => {
      stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    });
    afterEach(() => {
      stderr.mockRestore();
      process.exitCode = undefined;
    });

    it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
      "records every other file and retracts a deletion while one file is unreadable",
      async () => {
        fixture(3);
        // The graph model: a deletion reconciles through /v1/patches/:id and
        // /v1/entity/:id, which only it serves.
        backend.semantics = "head";
        const broken = join(repo, "src", "m000.ts");
        const deleted = join(repo, "src", "m001.ts");
        await incremental();
        const before = stored().files.get(broken);

        writeFileSync(broken, "export const changed = 1;\n", "utf8");
        rmSync(deleted);
        stage(); // before the chmod: git cannot read the file either
        execFileSync("chmod", ["000", broken]);
        backend.resetRequests();
        try {
          const summary = await incremental();
          expect(summary.parseErrors, "the unreadable file is an error").toBeGreaterThan(0);
        } finally {
          execFileSync("chmod", ["644", broken]);
        }

        const files = stored().files;
        expect(files.has(deleted), "the deletion was retracted and recorded").toBe(false);
        expect(backend.sourceUris).toContain("src/m001.ts");
        expect(files.get(join(repo, "src", "m002.ts")), "a settled file is recorded").toBeDefined();
        expect(files.get(broken), "the failed file keeps its old mtime").toBe(before);

        // Readable again: the next run sends it, and only it.
        backend.resetRequests();
        await incremental();
        expect(backend.acceptedPatches()).toBe(1);
        expect(stored().files.get(broken)).toBe(statSync(broken).mtimeMs);
      },
    );

    it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
      "a new file that fails is pending: retried, and ix status does not call the graph current",
      async () => {
        // A new file has no previous mtime to keep, so it dropped out of the
        // baseline while `lastIngestAt` moved past its mtime, and status
        // judged it current.
        fixture(3);
        await incremental();
        const added = join(repo, "src", "added.ts");
        writeFileSync(added, "export const added = 1;\n", "utf8");
        stage();
        execFileSync("chmod", ["000", added]);
        try {
          await incremental();
        } finally {
          execFileSync("chmod", ["644", added]);
        }

        expect(stored().files.has(added)).toBe(false);
        expect(stored().pendingFiles).toEqual(["src/added.ts"]);
        const status = detectStaleFiles(repo);
        expect(status.staleFiles).toBe(1);
        expect(status.sampleChangedFiles).toEqual(["src/added.ts"]);
        expect(renderStatusLlm("ok", "x", status)[0]).toContain("stale=true");

        // The next run sends it and clears the list.
        await incremental();
        expect(stored().files.get(added)).toBe(statSync(added).mtimeMs);
        expect(stored().pendingFiles).toEqual([]);
        expect(detectStaleFiles(repo).staleFiles).toBe(0);
      },
    );

    it("a failed lookup is not a reset", async () => {
      fixture(3);
      backend.rememberHashes = true;
      await incremental();
      backend.failSourceHashes = true;
      backend.resetRequests();

      const summary = await incremental();

      expect(summary.filesSkippedAsUnchanged, "still incremental").toBe(3);
      expect(backend.commitCount).toBe(0);
    });

    it("leaves no temp file beside the baseline", async () => {
      fixture(2);
      await incremental();
      const dir = join(home, ".ix");
      expect(existsSync(ingestMtimeCachePath(repo))).toBe(true);
      expect(execFileSync("ls", ["-a", dir], { encoding: "utf8" })).not.toMatch(/\.tmp/);
    });
  });

  describe("ix ingest coalesces with a map or ingest of the same workspace", () => {
    // It used to exit 1 with "run this again", which an editor hook or an MCP
    // client that ingests after every edit reported as a failed ingest, while
    // `ix map` in the same spot coalesces and exits 0.
    let stdout: ReturnType<typeof vi.spyOn>;
    let stderr: ReturnType<typeof vi.spyOn>;
    beforeEach(() => {
      stdout = vi.spyOn(console, "log").mockImplementation(() => undefined);
      stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
      process.exitCode = undefined;
    });
    afterEach(() => {
      stdout.mockRestore();
      stderr.mockRestore();
      process.exitCode = undefined;
      delete process.env.IX_MAP_COALESCE_EXIT_CODE;
    });
    const written = (spy: ReturnType<typeof vi.spyOn>) =>
      spy.mock.calls.map((call: unknown[]) => String(call[0])).join("");

    it("exits 0, asks the holder for a rerun, and prints JSON a client can parse", async () => {
      fixture(1);
      const held = acquireMapLock(repo, "test");
      try {
        expect(held).not.toBeNull();
        backend.resetRequests();
        await ingestPathSingleFlight(join(repo, "src"), { format: "json" });

        expect(process.exitCode, "a coalesce is not a failure").toBeUndefined();
        expect(backend.commitCount, "nothing ran beside the holder").toBe(0);
        expect(JSON.parse(written(stdout))).toEqual({ coalesced: true, workspace: repo });
        expect(takeMapRerun(repo), "the holder is asked to run once more").toBe(true);
      } finally {
        held?.release();
      }
    });

    it("honours IX_MAP_COALESCE_EXIT_CODE, as ix map does", async () => {
      fixture(1);
      const held = acquireMapLock(repo, "test");
      try {
        process.env.IX_MAP_COALESCE_EXIT_CODE = "75";
        await ingestPathSingleFlight(repo, { format: "text" });
        expect(process.exitCode).toBe(75);
        expect(written(stderr)).toContain("Another ix map or ix ingest is running");
      } finally {
        held?.release();
      }
    });

    it("a holding ingest re-runs for the one that coalesced, so its edit lands", async () => {
      fixture(3);
      await ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
      const first = join(repo, "src", "m000.ts");
      const second = join(repo, "src", "m002.ts");
      writeFileSync(first, "export const first = 1;\n", "utf8");
      writeFileSync(second, "export const second = 2;\n", "utf8");

      // The lock is taken before the first await, so the second call finds it
      // held whatever the scheduling.
      const holder = ingestPathSingleFlight(first, { format: "json" });
      const waiter = ingestPathSingleFlight(second, { format: "json" });
      await Promise.all([holder, waiter]);

      expect(process.exitCode).toBeUndefined();
      const files = loadIngestBaseline(repo)!.files;
      expect(files.get(second), "the coalesced run's file was ingested").toBe(statSync(second).mtimeMs);
      expect(files.get(first)).toBe(statSync(first).mtimeMs);
      const after = acquireMapLock(repo, "after");
      expect(after, "the lock was let go").not.toBeNull();
      after?.release();
    });
  });

  it("counts files tree-sitter parsed with errors, and still ingests them", async () => {
    fixture(2);
    writeFileSync(join(repo, "src", "broken.ts"), "export function ok() { return 1; }\nexport function bad( {\n", "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });

    const summary = await run();

    expect(summary.filesWithParseErrors).toBe(1);
    expect(backend.acceptedPatches()).toBe(3);
  });

  it("counts a file over the size limit in the summary, so ix map can say so", async () => {
    fixture(2);
    writeFileSync(join(repo, "src", "huge.ts"), `export const big = "${"x".repeat(1024 * 1024 + 10)}";\n`, "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });

    const summary = await run();

    expect(summary.filesTooLarge).toBe(1);
    expect(summary.filesTooLargePaths).toEqual(["src/huge.ts"]);
    expect(summary.patchesApplied).toBe(2);
  });

  it("ingests only the languages --lang names, and keeps the rest of the baseline", async () => {
    fixture(3);
    writeFileSync(join(repo, "src", "tool.py"), "def tool():\n    return 1\n", "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const baselineFiles = () =>
      Object.keys((JSON.parse(readFileSync(ingestMtimeCachePath(repo), "utf8")) as { files: Record<string, number> }).files);

    await ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const everything = baselineFiles();
    expect(everything).toHaveLength(4);

    backend.resetRequests();
    const summary = await ingestFiles(repo, { format: "text", force: true, lang: "py", suppressOutput: true, printSummary: false });
    expect(summary.filesDiscovered, "only the Python file is in scope").toBe(1);
    expect(backend.acceptedPatches()).toBe(1);
    expect(baselineFiles().sort(), "the TypeScript files keep their entries").toEqual([...everything].sort());
  });

  it("names a missing path rather than failing with a bare ENOENT", async () => {
    await expect(
      ingestFiles(join(repo, "no-such-dir"), { format: "text", suppressOutput: true, printSummary: false }),
    ).rejects.toThrow(/^Path not found: /);
  });

  it("sends workspace-relative uris when the path it is given is a symlink", async () => {
    // Discovery canonicalises every file with realpath; the root has to be
    // canonical too, or every source_uri comes out as `../<real dir>/src/x.ts`
    // (macOS /tmp -> /private/tmp, Windows 8.3 names, any symlinked checkout).
    fixture(2);
    const link = `${repo}-link`;
    symlinkSync(repo, link, "dir");
    try {
      await ingestFiles(link, { format: "text", force: true, suppressOutput: true, printSummary: false });
    } finally {
      rmSync(link, { force: true });
    }
    expect(backend.sourceUris.length).toBeGreaterThan(0);
    expect([...new Set(backend.sourceUris)].sort()).toEqual(["src/m000.ts", "src/m001.ts"]);
  });

  it("re-sends commits that lost the base-rev race to another writer", async () => {
    // Two `ix map` runs against one backend: each commit that lands moves the
    // rev under the other's in-flight commit, which is answered 200
    // BaseRevMismatch and writes nothing. Those used to be counted as failed
    // and left for the next run -- a third of the repo missing and exit 1.
    fixture(30);
    backend.loseBaseRevRaces = 3;

    const summary = await run();

    expect(summary.commitErrors, "every lost race was re-sent and landed").toBe(0);
    expect(summary.patchesApplied).toBe(30);
    expect(backend.bulkCount, "the same bulk, sent until it won").toBe(4);
    expect(backend.singleCount, "a lost race is not a reason to fan out").toBe(0);
  });

  it("still reports a race it keeps losing, after the retries", async () => {
    fixture(12);
    process.env.IX_COMMIT_BASE_REV_RETRIES = "2";
    backend.loseBaseRevRaces = 1_000;
    try {
      const message = await runFatal().catch((err: unknown) => String(err));
      expect(message).toMatch(/12 of 12|failed to commit/);
    } finally {
      delete process.env.IX_COMMIT_BASE_REV_RETRIES;
    }
  });

  it("commits a healthy repo in one bulk, with no per-file fan-out", async () => {
    fixture(12);

    const summary = await run();

    expect(summary.commitErrors).toBe(0);
    expect(summary.patchesApplied).toBe(12);
    expect(backend.bulkCount).toBe(1);
    expect(backend.singleCount, "the fan-out is for failures only").toBe(0);
  });

  describe("commit retries and the database probe (IN-19C)", () => {
    let stderr: ReturnType<typeof vi.spyOn>;
    const written = (): string => stderr.mock.calls.map((call: unknown[]) => String(call[0])).join("");
    const sequence = (): string[] =>
      backend.requests.filter(r => r.path !== "/v1/stitch").map(r => `${r.path} ${r.code}`);
    beforeEach(() => {
      stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    });
    afterEach(() => {
      stderr.mockRestore();
      process.exitCode = undefined;
    });

    it("re-sends a bulk the backend answered 503, and lands everything with no fan-out", async () => {
      fixture(12);
      backend.transientCommitFailures = [{ status: 503, retryAfter: "0" }];

      const summary = await run();

      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(12);
      expect(sequence()).toEqual(["/v1/patches/bulk 503", "/v1/patches/bulk 200"]);
      expect(backend.singleCount, "no per-file fallback").toBe(0);
    });

    it("still re-sends a 503 bulk with IX_COMMIT_CONFLICT_RETRIES=0: that knob is for conflicts only", async () => {
      fixture(4);
      process.env.IX_COMMIT_CONFLICT_RETRIES = "0";
      backend.transientCommitFailures = [{ status: 503, retryAfter: "0" }];

      const summary = await run();

      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(4);
      expect(sequence()).toEqual(["/v1/patches/bulk 503", "/v1/patches/bulk 200"]);
    });

    it("sends the bulk once with IX_COMMIT_TRANSIENT_RETRY_MS=0, then falls back per file as before", async () => {
      fixture(4);
      process.env.IX_COMMIT_TRANSIENT_RETRY_MS = "0";
      backend.transientCommitFailures = [{ status: 503, retryAfter: "0" }];

      const summary = await run();

      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(4);
      expect(sequence()).toEqual([
        "/v1/patches/bulk 503",
        "/v1/patch 200",
        "/v1/patch 200",
        "/v1/patch 200",
        "/v1/patch 200",
      ]);
    });

    it("trips at once when the backend reports its database down and says so, while the commits still decide the exit", async () => {
      fixture(30);
      backend.databaseDown = true;

      const message = await runFatal();

      expect(message).toContain("30 of 30");
      expect(backend.healthRequests, "the probe asked").toBeGreaterThan(0);
      // Tripped on the first per-file failure, so the fan-out holds the rest.
      // The held patches are still sent afterwards, as on main, so the exit
      // code comes from their failures, not from the health answer -- and the
      // drain's failure budget still bounds them below one request per file.
      expect(backend.bulkCount, "the held set was re-sent").toBeGreaterThan(1);
      expect(backend.singleCount).toBeLessThan(30);
      const banner = written();
      expect(banner).toContain("cannot reach its database (ArangoDB)");
      expect(banner).not.toContain("still passes");
    });

    it("asks about the database before waiting out a 503 on the first bulk", async () => {
      fixture(30);
      backend.databaseDown = true;
      backend.databaseDownCommitStatus = 503;
      const started = Date.now();

      await runFatal();

      // Asked after the first 503, not after the backoff: the database is
      // down, so the bulk is not retried and the chunk goes to the cutoff
      // rather than the per-file fallback. The held set is then still sent,
      // so the commits, not the probe, decide the exit.
      expect(Date.now() - started, "no transient backoff").toBeLessThan(5_000);
      expect(backend.healthRequests, "the probe asked").toBeGreaterThan(0);
      expect(backend.singleCount).toBeLessThan(30);
      const banner = written();
      expect(banner).toContain("cannot reach its database (ArangoDB)");
    });

    it("a health answer that wrongly says the database is down does not fail a run whose commits land", async () => {
      fixture(30);
      backend.healthSaysDatabaseDown = true;
      backend.transientCommitFailures = [{ status: 503, retryAfter: "0" }];

      const summary = await run();

      expect(backend.healthRequests, "the probe asked, and was told 'unreachable'").toBeGreaterThan(0);
      expect(summary.commitErrors, "the held patches were sent and landed").toBe(0);
      expect(summary.patchesApplied).toBe(30);
      expect(process.exitCode ?? 0).toBe(0);
      // Every patch landed, so no cutoff banner: it would tell the user the
      // graph is "partly updated" and to re-run, which is false.
      expect(written()).not.toContain("kept failing");
      expect(written()).not.toContain("partly updated");
    });

    it("does not trip on a 5xx from the current-revision fallback (an older backend proves nothing)", async () => {
      fixture(30);
      backend.databaseDown = true;
      backend.healthReportsDatabase = false;

      await runFatal();

      expect(backend.revisionRequests).toBeGreaterThan(0);
      expect(written()).not.toContain("cannot reach its database (ArangoDB)");
    });

    it("changes nothing on a backend that refuses every commit while its database is reachable", async () => {
      fixture(30);
      backend.refuseEverything = true;

      const message = await runFatal();

      expect(backend.healthRequests, "the probe asked").toBeGreaterThan(0);
      expect(message).toContain("30 of 30");
      // The streak, not the probe, tripped it: five per-file failures, as before.
      expect(backend.singleCount).toBeGreaterThanOrEqual(5);
      expect(backend.commitCount, "well under main's 31").toBeLessThan(25);
      expect(written()).toContain("`ix doctor` still passes");
    });

    it("does not call a graph wiped under it 'unchanged' when nothing lands", async () => {
      // A baseline from an earlier map, then a backend that holds none of it:
      // the DB-reset guard fires, as it does after `ix reset` from another dir.
      fixture(8);
      const incremental = () =>
        ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
      await incremental();
      backend.refuseEverything = true;

      let message = "";
      try {
        await incremental();
      } catch (err) {
        message = String(err);
      }

      expect(message, "still fatal").toContain("8 of 8");
      const out = `${written()}\n${message}`;
      expect(out).toContain("kept failing");
      expect(out).not.toContain("unchanged");
      expect(out).toContain("this workspace's graph is still empty");
    });

    it("does not call it 'unchanged' after a first map that committed nothing, below the cutoff", async () => {
      fixture(2);
      backend.refuseEverything = true;
      let message = "";
      try {
        await ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
      } catch (err) {
        message = String(err);
      }
      expect(message).toContain("committed nothing");
      expect(message).not.toContain("unchanged");
      expect(message).toContain("still empty");
    });

    it("does not call the workspace's graph empty when a scoped run with no local baseline commits nothing", async () => {
      // `ix ingest <new file>` in a repo mapped from another HOME or machine:
      // no local baseline, and the lookup covers that one file only, so an
      // empty answer says nothing about the rest of the graph.
      fixture(2);
      backend.refuseEverything = true;
      let message = "";
      try {
        await ingestFiles(join(repo, "src", "m000.ts"), { format: "text", suppressOutput: true, printSummary: false });
      } catch (err) {
        message = String(err);
      }
      expect(message).toContain("committed nothing");
      expect(message).not.toContain("still empty");
      expect(message).toContain("may now be stale");
    });
  });

  describe("a patch that deletes (IN-04)", () => {
    const incremental = () =>
      ingestFiles(repo, { format: "text", suppressOutput: true, printSummary: false });
    const perFile = () => backend.requests.filter(r => r.path === "/v1/patch").length;
    /** Map two files, then drop `g` from one of them: its patch carries a DeleteNode. */
    const removeAFunction = async (): Promise<void> => {
      backend.semantics = "head";
      mkdirSync(join(repo, "src"), { recursive: true });
      writeFileSync(join(repo, "src", "a.ts"), "export function f(): number { return 1; }\nexport function g(): number { return 2; }\n", "utf8");
      writeFileSync(join(repo, "src", "b.ts"), "export const b = 1;\n", "utf8");
      execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
      await incremental();
      writeFileSync(join(repo, "src", "a.ts"), "export function f(): number { return 1; }\n", "utf8");
      backend.resetRequests();
      await incremental();
    };

    it("goes through the bulk route on a backend that applies bulk deletes", async () => {
      backend.releaseVersion = "1.0.32";
      await removeAFunction();
      expect(backend.lastOps.get("src/a.ts")?.some(op => op.type === "DeleteNode"), "the patch deletes").toBe(true);
      expect(backend.bulkCount).toBe(1);
      expect(perFile()).toBe(0);
    });

    it("goes to /v1/patch on its own on a backend that reports no release, or an older one", async () => {
      backend.releaseVersion = null;
      await removeAFunction();
      expect(backend.lastOps.get("src/a.ts")?.some(op => op.type === "DeleteNode"), "the patch deletes").toBe(true);
      expect(perFile()).toBe(1);
    });

    it("goes to /v1/patch on its own on a release before the one that applies bulk deletes", async () => {
      backend.releaseVersion = "1.0.31";
      await removeAFunction();
      expect(perFile()).toBe(1);
    });

    // An external package node is keyed by the workspace, not the file, so
    // every caller writes the same one. One caller dropping its call deleted
    // the node and every other caller's edge to it, though their files had
    // not changed.
    it("a file that stops calling a package function leaves the other callers' edges", async () => {
      backend.semantics = "head";
      backend.releaseVersion = "1.0.32";
      mkdirSync(join(repo, "R"), { recursive: true });
      const calls = (fn: string) => `${fn} <- function(x) {\n  dplyr::filter(x)\n}\n`;
      writeFileSync(join(repo, "R", "a.R"), calls("fa"), "utf8");
      writeFileSync(join(repo, "R", "b.R"), calls("fb"), "utf8");
      execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
      await incremental();
      const edgeNames = () => backend.graphSignature().edges
        .map(line => line.split(" "))
        .filter(([, , , predicate]) => predicate === "CALLS")
        .map(([, src, dst]) => `${backend.nodeName(src!)} -> ${backend.nodeName(dst!)}`)
        .sort();
      expect(edgeNames()).toEqual(["fa[function] -> filter[function]", "fb[function] -> filter[function]"]);

      writeFileSync(join(repo, "R", "a.R"), "fa <- function(x) {\n  x\n}\n", "utf8");
      await incremental();

      expect(edgeNames()).toEqual(["fb[function] -> filter[function]"]);
    });
  });

  describe("bulk requests bounded by size (IN-05)", () => {
    // More than one parse batch, so what the first batch learns has a later
    // batch to hold for.
    //
    // The batches are 50 files here (IX_PARSE_STREAM_CHUNK), not the default
    // 500, and every count below is a tenth of what a 500-file batch needs: the
    // files, the batches and the backend's cap. These tests used to write,
    // `git add`, read and parse 560 to 1,100 files each. That costs well under
    // a second on Linux and macOS, but on the 4-core windows-2022 runner, with
    // the rest of the suite running beside it, it took from seven to more than
    // thirty seconds, and timed out. The work was all per file, and none of it
    // is what these tests check: the batch boundaries, the ops per request and
    // the 413s are the same at a tenth of the size. The backend refuses a bulk
    // over 30 ops; at 7 ops a file that is 4 files a request. (The variable
    // is cleared and restored around every test by the describe above.)
    const tooLarge = () => backend.requests.filter(r => r.path === "/v1/patches/bulk" && r.code === 413).length;
    const smallBatches = (): void => { process.env.IX_PARSE_STREAM_CHUNK = "50"; };
    const saved = process.env.IX_COMMIT_MAX_OPS;
    afterEach(() => {
      if (saved === undefined) delete process.env.IX_COMMIT_MAX_OPS;
      else process.env.IX_COMMIT_MAX_OPS = saved;
    });

    // 56 files, two parse batches: 50, then 6. At 7 ops a file the second
    // batch is 42 ops, over the cap at the default bounds, so it is refused
    // too unless the run kept what the first batch learned.
    it("learns the size from the first 413 that suggests one, and is refused no more that run", async () => {
      smallBatches();
      fixture(56);
      backend.maxBulkOps = 30;
      backend.suggestMaxPatches = true;

      const summary = await run();

      expect(tooLarge()).toBe(1);
      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(56);
      expect(backend.singleCount, "no per-file fallback").toBe(0);
      // Both batches were sent in bounded requests. Without the learned size,
      // the second batch goes out as one 6-patch request and is refused.
      const accepted = backend.requests.filter(r => r.path === "/v1/patches/bulk" && r.code !== 413);
      expect(Math.max(...accepted.map(r => r.patches))).toBeLessThanOrEqual(Math.floor(30 / 7));
    });

    it("halves on a 413 that suggests nothing, and later batches start at the learned size", async () => {
      // Three parse batches: 50, 50, then 10.
      smallBatches();
      fixture(110);
      backend.maxBulkOps = 30;

      const summary = await run();

      // A few halvings in the first batch only (50, 25, 12, 6 refused; 3
      // fits); bisecting each batch afresh was more than twice as many.
      expect(tooLarge()).toBeGreaterThan(0);
      expect(tooLarge()).toBeLessThanOrEqual(4);
      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(110);
    });

    it("keeps its op budget after a 413 for bytes: one large file does not shrink the requests after it", async () => {
      // 60 ordinary files and one whose patch is large for its op count (a
      // 60,000-character identifier). The body cap fits that one file alone,
      // and all 60 others together, but not all 61. Learning an op budget from
      // that 413 halved it on every bisection that still held the large file,
      // until the files after it went a few per request.
      fixture(60);
      writeFileSync(
        join(repo, "src", "big.ts"),
        `export function ${"n".repeat(60_000)}(): number { return 1; }\n`,
        "utf8",
      );
      execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
      backend.maxBulkBytes = 255_000;

      const summary = await run();

      const bulks = backend.requests.filter(r => r.path === "/v1/patches/bulk");
      expect(tooLarge()).toBe(1);
      expect(bulks.length, "the refused request, then the large file and the rest").toBe(3);
      expect(Math.max(...bulks.filter(r => r.code !== 413).map(r => r.patches))).toBe(60);
      expect(summary.commitErrors).toBe(0);
      expect(summary.patchesApplied).toBe(61);
      expect(backend.singleCount, "no per-file fallback").toBe(0);
    });

    it("is never refused when IX_COMMIT_MAX_OPS keeps every request under the cap", async () => {
      smallBatches();
      fixture(110);
      backend.maxBulkOps = 30;
      process.env.IX_COMMIT_MAX_OPS = "30";

      const summary = await run();

      expect(tooLarge()).toBe(0);
      expect(summary.patchesApplied).toBe(110);
    });
  });

  // ── Which workspace a path belongs to ─────────────────────────────────
  //
  // `ix ingest <path>` used to treat the path as its own workspace root: `ix
  // ingest src/a.ts` in a mapped repo registered `repo/src` as a second
  // workspace, sent `a.ts` instead of `src/a.ts` under that workspace's id,
  // and from then on every read under `src/` resolved to the hollow one.

  /** Register `roots` in the config by hand, so no ingest has run yet. */
  const register = (...roots: Array<{ root: string; isDefault?: boolean }>): void => {
    mkdirSync(join(home, ".ix"), { recursive: true });
    writeFileSync(join(home, ".ix", "config.yaml"), [
      "endpoint: http://localhost:8090",
      "format: text",
      "workspaces:",
      ...roots.flatMap(({ root, isDefault }) => [
        `  - workspace_id: "${workspaceIdForPath(root)}"`,
        `    workspace_name: ${root.split(/[\\/]/).pop()}`,
        `    root_path: ${root}`,
        `    default: ${isDefault === true}`,
      ]),
      "",
    ].join("\n"));
  };
  const registered = () =>
    (loadConfig().workspaces ?? []).map(w => ({ root: w.root_path, id: w.workspace_id, isDefault: w.default }));
  const sent = () => backend.sourceUris.map((uri, i) => ({ uri, workspaceId: backend.sourceWorkspaceIds[i] }));
  const quiet = { format: "text", suppressOutput: true, printSummary: false } as const;

  it("ingests a file or subdirectory inside a registered workspace into THAT workspace", async () => {
    fixture(2);
    mkdirSync(join(repo, "src", "util"), { recursive: true });
    writeFileSync(join(repo, "src", "util", "u.ts"), "export const u = 1;\n", "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    // Registered, but deliberately NOT the default: a stray registration
    // became the default whenever none was set.
    register({ root: repo, isDefault: false });
    const before = registered();
    const repoId = workspaceIdForPath(repo);

    await ingestFiles(join(repo, "src", "m001.ts"), { ...quiet, force: true });
    expect(sent()).toEqual([{ uri: "src/m001.ts", workspaceId: repoId }]);

    backend.sourceUris.length = 0;
    backend.sourceWorkspaceIds.length = 0;
    await ingestFiles(join(repo, "src", "util"), { ...quiet, force: true });
    expect(sent()).toEqual([{ uri: "src/util/u.ts", workspaceId: repoId }]);

    expect(registered(), "no workspace registered, and the default left alone").toEqual(before);
  });

  it("uses the git root for a path in a repository nobody has registered", async () => {
    fixture(2);
    await ingestFiles(join(repo, "src"), { ...quiet, force: true });

    expect(registered(), "registered, and the default since none existed").toEqual([{ root: repo, id: workspaceIdForPath(repo), isDefault: true }]);
    expect([...new Set(sent().map(s => `${s.workspaceId} ${s.uri}`))].sort()).toEqual([
      `${workspaceIdForPath(repo)} src/m000.ts`,
      `${workspaceIdForPath(repo)} src/m001.ts`,
    ]);
  });

  it("ingests a loose FILE under its directory's id but registers nothing", async () => {
    // `repo` here is a plain directory: no `fixture()`, so no `git init`.
    const outside = join(repo, "loose");
    mkdirSync(outside, { recursive: true });
    writeFileSync(join(outside, "x.ts"), "export const x = 1;\n", "utf8");
    const configPath = join(home, ".ix", "config.yaml");
    const before = existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined;

    await ingestFiles(join(outside, "x.ts"), { ...quiet, force: true });

    expect(sent()).toEqual([{ uri: "x.ts", workspaceId: workspaceIdForPath(outside) }]);
    expect(registered()).toEqual([]);
    expect(existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined).toBe(before);
  });

  it("a coalesced rerun for a loose FILE ingest does not register the file's directory either", async () => {
    // The holder's rerun widens a loose file to its whole directory once that
    // directory has a baseline; registering it would make the directory readable.
    const outside = join(repo, "loose");
    mkdirSync(outside, { recursive: true });
    const first = join(outside, "x.ts");
    const second = join(outside, "y.ts");
    writeFileSync(first, "export const x = 1;\n", "utf8");
    // The directory was ingested once and its registration since dropped from
    // config.yaml by hand: unregistered, but it keeps its baseline.
    await ingestFiles(outside, quiet);
    register();
    expect(registered()).toEqual([]);
    expect(loadIngestBaseline(outside), "the loose directory has a baseline, so the rerun covers all of it").not.toBeNull();
    writeFileSync(first, "export const x = 2;\n", "utf8");
    writeFileSync(second, "export const y = 2;\n", "utf8");
    const configPath = join(home, ".ix", "config.yaml");
    const before = existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined;
    const stdout = vi.spyOn(console, "log").mockImplementation(() => undefined);
    try {
      // The lock is taken before the first await, so the waiter coalesces.
      const holder = ingestPathSingleFlight(first, { format: "json" });
      const waiter = ingestPathSingleFlight(second, { format: "json" });
      await Promise.all([holder, waiter]);
    } finally {
      stdout.mockRestore();
    }

    expect(loadIngestBaseline(outside)!.files.get(second), "the rerun ran").toBe(statSync(second).mtimeMs);
    expect(registered()).toEqual([]);
    expect(existsSync(configPath) ? readFileSync(configPath, "utf8") : undefined).toBe(before);
  });

  it("registers a loose DIRECTORY after a successful ingest, but never as the default", async () => {
    const outside = join(repo, "loose");
    mkdirSync(outside, { recursive: true });
    writeFileSync(join(outside, "x.ts"), "export const x = 1;\n", "utf8");

    await ingestFiles(outside, { ...quiet, force: true });

    expect(registered()).toEqual([{ root: outside, id: workspaceIdForPath(outside), isDefault: false }]);
    expect(sent()).toEqual([{ uri: "x.ts", workspaceId: workspaceIdForPath(outside) }]);
  });

  it("a git-repo ingest that set the default stays the default through a later map's registration", async () => {
    fixture(2);
    await ingestFiles(join(repo, "src", "m000.ts"), { ...quiet, force: true });
    // `ix map` registers through bootstrap -> ensureWorkspaceRegistered first.
    ensureWorkspaceRegistered(repo);
    expect(registered()).toEqual([{ root: repo, id: workspaceIdForPath(repo), isDefault: true }]);
  });

  it("an explicit --root ingest of a non-repository directory may become the default", async () => {
    const outside = join(repo, "rooted");
    mkdirSync(outside, { recursive: true });
    writeFileSync(join(outside, "x.ts"), "export const x = 1;\n", "utf8");

    await ingestFiles(outside, { ...quiet, force: true, root: outside });

    expect(registered()).toEqual([{ root: realpathSync.native(outside), id: workspaceIdForPath(realpathSync.native(outside)), isDefault: true }]);
  });

  it("leaves an existing default workspace the only default", async () => {
    fixture(2);
    const other = join(repo, "..", `${repo.split(/[\\/]/).pop()}-default`);
    mkdirSync(other, { recursive: true });
    register({ root: realpathSync.native(other), isDefault: true });

    await ingestFiles(join(repo, "src"), { ...quiet, force: true });

    expect(registered().filter(w => w.isDefault).map(w => w.root)).toEqual([realpathSync.native(other)]);
    expect(registered().map(w => w.root)).toContain(repo);
  });

  it("leaves everything outside a subdirectory run alone: deletions, baseline, extractor, stitch", async () => {
    fixture(2);
    mkdirSync(join(repo, "lib"), { recursive: true });
    writeFileSync(join(repo, "lib", "l0.ts"), "export const l0 = 0;\n", "utf8");
    writeFileSync(join(repo, "lib", "l1.ts"), "export const l1 = 1;\n", "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    backend.rememberHashes = true;
    type Stored = { files: Record<string, number>; extractor?: string; lastIngestAt: string };
    const stored = () => JSON.parse(readFileSync(ingestMtimeCachePath(repo), "utf8")) as Stored;

    await ingestFiles(repo, quiet);
    // An older extractor on record: a full run would re-ingest everything and
    // record the new name; a run over `src/` has vouched for none of `lib/`.
    writeFileSync(ingestMtimeCachePath(repo), JSON.stringify({ ...stored(), extractor: "tree-sitter/0.1" }));
    const baselineBefore = stored();
    const deleted = join(repo, "lib", "l0.ts");
    expect(Object.keys(baselineBefore.files)).toContain(deleted);

    // Gone from disk, so a run over the whole root would delete it. A run over
    // `src/` must not: it says nothing about `lib/`. (Were it attempted, the
    // reconcile's `GET /v1/patches/...` would land in `unknownPaths`.)
    rmSync(deleted);
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    backend.resetRequests();
    backend.sourceUris.length = 0;
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    try {
      // --force, so nothing is skipped as unchanged: on the whole root that
      // is exactly the run that re-registers the stitch.
      await ingestFiles(join(repo, "src"), { ...quiet, force: true });
    } finally {
      stderr.mockRestore();
    }

    expect([...new Set(backend.sourceUris)].sort()).toEqual(["src/m000.ts", "src/m001.ts"]);
    expect(backend.stitchCount, "a slice of the repo is not its registration").toBe(0);
    const after = stored();
    expect(after.files[deleted], "the deletion is the next full map's").toBe(baselineBefore.files[deleted]);
    expect(after.files[join(repo, "lib", "l1.ts")]).toBe(baselineBefore.files[join(repo, "lib", "l1.ts")]);
    expect(Object.keys(after.files).sort()).toEqual(Object.keys(baselineBefore.files).sort());
    expect(after.extractor, "the rest of the workspace keeps its extractor").toBe("tree-sitter/0.1");
    expect(after.lastIngestAt, "the last full ingest is still the last full ingest").toBe(baselineBefore.lastIngestAt);
    expect(existsSync(ingestRebuildPath(repo)), "no whole-workspace rebuild is started").toBe(false);
  });

  it("resolves a scoped run's edges against the whole workspace, not just the scope", async () => {
    // `src/a.ts` imports `lib/b.ts`. A run over `src/` re-sends a.ts's patch,
    // and resolving it against `src/` alone dropped the import edge from it.
    mkdirSync(join(repo, "src"), { recursive: true });
    mkdirSync(join(repo, "lib"), { recursive: true });
    writeFileSync(join(repo, "lib", "b.ts"), "export function b(): number { return 1; }\n", "utf8");
    writeFileSync(join(repo, "src", "a.ts"), "import { b } from '../lib/b';\nexport function a(): number { return b(); }\n", "utf8");
    execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const edges = () => (backend.lastOps.get("src/a.ts") ?? [])
      .filter(op => op.type === "UpsertEdge")
      .map(op => `${String(op.predicate)} ${String(op.dst)}`)
      .sort();

    await ingestFiles(repo, { ...quiet, force: true });
    const full = edges();
    expect(full.some(e => e.startsWith("IMPORTS ")), "the fixture has an import edge to lose").toBe(true);

    backend.lastOps.clear();
    await ingestFiles(join(repo, "src"), { ...quiet, force: true });
    expect(edges()).toEqual(full);
  });

  it("does not resolve a scoped run against a stale symbol-table entry for a file outside the scope", async () => {
    // The table is trusted for a file the baseline calls mtime-clean, but a
    // scoped run never stats the files outside its scope, so it vouched for an
    // edited `lib/b.ts` with the symbols it had before the edit.
    // Real commit semantics, so the incremental run has hashes to compare.
    backend.semantics = "head";
    mkdirSync(join(repo, "src"), { recursive: true });
    mkdirSync(join(repo, "lib"), { recursive: true });
    writeFileSync(join(repo, "lib", "b.ts"), "export function helper(): number { return 1; }\n", "utf8");
    writeFileSync(join(repo, "src", "a.ts"), "import { helper } from '../lib/b';\nexport function caller(): number { return helper(); }\n", "utf8");
    execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const edges = () => (backend.lastOps.get("src/a.ts") ?? [])
      .filter(op => op.type === "UpsertEdge")
      .map(op => `${String(op.predicate)} ${String(op.dst)}`)
      .sort();

    await ingestFiles(repo, quiet);
    const resolved = edges();

    // `helper` is gone from lib/b.ts; a.ts still calls it. Only src/ is re-mapped.
    writeFileSync(join(repo, "lib", "b.ts"), "export function renamed(): number { return 1; }\n", "utf8");
    writeFileSync(join(repo, "src", "a.ts"), "import { helper } from '../lib/b';\nexport function caller(): number { return helper() + 1; }\n", "utf8");
    backend.lastOps.clear();
    await ingestFiles(join(repo, "src"), quiet);
    const scoped = edges();

    // What a fresh map of the edited workspace says about a.ts.
    backend.lastOps.clear();
    await ingestFiles(repo, { ...quiet, force: true });
    const fresh = edges();

    expect(resolved, "the fixture's call resolved to lib/b.ts at first").not.toEqual(fresh);
    expect(scoped).toEqual(fresh);
  });

  it("keeps other languages' symbol-table entries on a --lang run", async () => {
    // The table was pruned to the run's resolution paths, which `--lang`
    // filters, so every other language was dropped and re-parsed next map.
    mkdirSync(join(repo, "src"), { recursive: true });
    writeFileSync(join(repo, "src", "a.ts"), "export function a(): number { return 1; }\n", "utf8");
    writeFileSync(join(repo, "src", "b.py"), "def b():\n    return 1\n", "utf8");
    execFileSync("git", ["init", "-q"], { cwd: repo, stdio: "ignore" });
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    const tableFiles = () =>
      Object.keys((JSON.parse(readFileSync(ingestSymbolsPath(repo), "utf8")) as { files: Record<string, unknown> }).files).sort();

    await ingestFiles(repo, quiet);
    expect(tableFiles()).toEqual(["src/a.ts", "src/b.py"]);

    writeFileSync(join(repo, "src", "b.py"), "def b():\n    return 2\n", "utf8");
    await ingestFiles(repo, { ...quiet, lang: "py" });
    expect(tableFiles()).toEqual(["src/a.ts", "src/b.py"]);
  });

  it("writes the symbol table only when an entry changed, and then only the change", async () => {
    // It was rewritten in full on every run that parsed anything.
    fixture(20);
    const table = () => readFileSync(ingestSymbolsPath(repo), "utf8");
    const journal = ingestSymbolsJournalPath(repo);

    await ingestFiles(repo, quiet);
    const written = table();
    const writtenAt = statSync(ingestSymbolsPath(repo)).mtimeMs;
    expect(Object.keys((JSON.parse(written) as { files: object }).files)).toHaveLength(20);
    expect(existsSync(journal)).toBe(false);

    // Nothing changed: an incremental run and a forced re-parse of every file
    // leave both files as they were.
    await ingestFiles(repo, quiet);
    await ingestFiles(repo, { ...quiet, force: true });
    expect(table()).toBe(written);
    expect(statSync(ingestSymbolsPath(repo)).mtimeMs).toBe(writtenAt);
    expect(existsSync(journal)).toBe(false);

    // One file changed: the table stays, and the journal carries that entry.
    writeFileSync(join(repo, "src", "m007.ts"), "export function f7(): number { return 70; }\nexport const g7 = 1;\n", "utf8");
    await ingestFiles(repo, quiet);
    expect(table()).toBe(written);
    const lines = readFileSync(journal, "utf8").trim().split("\n").map(l => JSON.parse(l) as { k?: string });
    expect(lines.slice(1).map(l => l.k)).toEqual(["src/m007.ts"]);

    // And what the next run loads is the change, with every other entry.
    const loaded = loadIngestSymbols(repo, (JSON.parse(written) as { extractor: string }).extractor);
    expect(loaded.size).toBe(20);
    expect(JSON.stringify(loaded.get("src/m007.ts")?.summary)).toContain("g7");

    // Unchanged again: nothing more is appended.
    const journalText = readFileSync(journal, "utf8");
    await ingestFiles(repo, quiet);
    expect(readFileSync(journal, "utf8")).toBe(journalText);
  });

  it("writes no baseline from a subdirectory run when the workspace has none", async () => {
    // One written from `src/` alone would report the whole graph complete.
    fixture(2);
    mkdirSync(join(repo, "lib"), { recursive: true });
    writeFileSync(join(repo, "lib", "l0.ts"), "export const l0 = 0;\n", "utf8");
    execFileSync("git", ["add", "-A"], { cwd: repo, stdio: "ignore" });
    register({ root: repo, isDefault: true });

    await ingestFiles(join(repo, "src"), { ...quiet, force: true });

    expect(existsSync(ingestMtimeCachePath(repo))).toBe(false);
    expect(existsSync(ingestMtimeCachePath(join(repo, "src")))).toBe(false);
  });

  it("keeps a member repo's own workspace id, inside a registered system or on its own", async () => {
    // `repo` is the plain folder holding two independently cloned repos.
    for (const member of ["alpha", "beta"]) {
      mkdirSync(join(repo, member), { recursive: true });
      writeFileSync(join(repo, member, `${member}.ts`), `export const ${member} = 1;\n`, "utf8");
      execFileSync("git", ["init", "-q"], { cwd: join(repo, member), stdio: "ignore" });
      execFileSync("git", ["add", "-A"], { cwd: join(repo, member), stdio: "ignore" });
    }
    const alpha = join(repo, "alpha");
    const alphaId = workspaceIdForPath(alpha);

    // Standalone: nothing registered, so the member's git root -- exactly
    // what `ix map` inside it produces.
    await ingestFiles(join(alpha, "alpha.ts"), { ...quiet, force: true });
    expect(sent()).toEqual([{ uri: "alpha.ts", workspaceId: alphaId }]);
    expect(registered().map(w => w.root)).toEqual([alpha]);

    // Inside the registered system: the system's workspace, with the uri the
    // co-ingest gave the file and, still, the member's own id.
    register({ root: repo, isDefault: true });
    backend.sourceUris.length = 0;
    backend.sourceWorkspaceIds.length = 0;
    await ingestFiles(join(alpha, "alpha.ts"), { ...quiet, force: true });
    expect(sent()).toEqual([{ uri: "alpha/alpha.ts", workspaceId: alphaId }]);
    expect(registered().map(w => w.root)).toEqual([repo]);
  });
  describe("QA-07: behaviours the matrix was missing", () => {
    const incremental = () =>
      ingestFiles(repo, { format: "json", suppressOutput: true, printSummary: false });
    const git = (...args: string[]) => execFileSync("git", args, { cwd: repo, stdio: "ignore" });

    // Guard: ingest.ts `deletedPatches.push(...)` for a path that left the tree.
    it("a file renamed between runs sends a tombstone for the old path and a patch for the new", async () => {
      backend.semantics = "head";
      backend.releaseVersion = "1.0.32";
      mkdirSync(join(repo, "src"), { recursive: true });
      writeFileSync(join(repo, "src", "a.ts"), "export function fa(): number { return 1; }\n", "utf8");
      writeFileSync(join(repo, "src", "b.ts"), "export function fb(): number { return 2; }\n", "utf8");
      git("init", "-q");
      git("add", "-A");
      await incremental();
      expect(backend.graphSignature().nodes.some(n => n.includes("a.ts"))).toBe(true);

      git("mv", "src/a.ts", "src/c.ts");
      backend.resetRequests();
      backend.sourceUris.length = 0;
      await incremental();

      expect(backend.sourceUris.filter(u => u === "src/a.ts"), "one patch for the old path").toHaveLength(1);
      expect(backend.sourceUris.filter(u => u === "src/c.ts"), "one patch for the new path").toHaveLength(1);
      expect(backend.sourceUris, "an untouched file is not re-sent").not.toContain("src/b.ts");

      const oldOps = backend.lastOps.get("src/a.ts")!;
      expect(oldOps.length).toBeGreaterThan(0);
      expect(oldOps.every(op => op.type === "DeleteNode" || op.type === "DeleteEdge"), "the tombstone only deletes").toBe(true);
      expect(oldOps.some(op => op.type === "DeleteNode"), "and removes nodes").toBe(true);
      expect(backend.lastOps.get("src/c.ts")!.some(op => op.type === "UpsertNode")).toBe(true);

      const names = backend.graphSignature().nodes.join("\n");
      expect(names).not.toContain("a.ts");
      expect(names).toContain("c.ts");

      // Head semantics: the incremental graph is the one a fresh map builds.
      const incrementalGraph = backend.graphSignature();
      const fresh = new FakeBackend({ semantics: "head" });
      const endpoint = process.env.IX_ENDPOINT;
      process.env.IX_ENDPOINT = await fresh.start();
      try {
        await ingestFiles(repo, { format: "json", force: true, suppressOutput: true, printSummary: false });
        expect(incrementalGraph).toEqual(fresh.graphSignature());
      } finally {
        process.env.IX_ENDPOINT = endpoint;
        await fresh.stop();
      }
    });

    // The failing-capable proof for the walk is the walkFiles case in
    // ingest-discovery.test.ts: discoverSourceFiles' canonical dedupe hides a
    // walk that follows the link at this level. This is the end-to-end run.
    for (const mode of ["git", "no-git"] as const) {
      it(`a directory symlink to its parent ends the run with each file sent once (${mode})`, async () => {
        fixture(3);
        try {
          symlinkSync("..", join(repo, "src", "up"), "dir");
        } catch {
          return; // no permission to symlink — nothing to assert
        }
        if (mode === "no-git") rmSync(join(repo, ".git"), { recursive: true, force: true });
        else git("add", "-A");

        await incremental();

        for (const n of ["m000", "m001", "m002"]) {
          expect(backend.sourceUris.filter(u => u === `src/${n}.ts`), n).toHaveLength(1);
        }
        expect(backend.sourceUris.some(u => u.includes("up/"))).toBe(false);
      });
    }

    it("a .ts file with NUL bytes and invalid UTF-8 does not stop the ingest", async () => {
      fixture(3);
      // Escapes only: no raw NUL in this source.
      writeFileSync(
        join(repo, "src", "bin.ts"),
        Buffer.concat([
          Buffer.from("export function before(): number { return 1; }\n"),
          Buffer.from([0x00, 0x00, 0xff, 0xfe, 0xc3, 0x28]),
          Buffer.from("\nexport function after(): number { return 2; }\n"),
        ]),
      );
      git("add", "-A");

      const summary = await incremental();

      for (const n of ["m000", "m001", "m002"]) {
        expect(backend.sourceUris, n).toContain(`src/${n}.ts`);
      }
      // Observed today: it lands AND is counted in filesWithParseErrors. Either
      // alone is acceptable; neither is a silent drop.
      const landed = backend.sourceUris.includes("src/bin.ts");
      const counted = summary.parseErrors + summary.filesWithParseErrors > 0;
      expect(landed || counted, "bin.ts landed or was counted as a parse error").toBe(true);
    });

    // Guards the id inputs: a run-varying value in workspaceIdForPath
    // (system.ts) or computePatchId (core-ingestion patch-builder.ts) turns it
    // red. It cannot see a dropped .sort(): both runs discover the same files
    // in the same order, so an unsorted list is still the same list twice.
    it("two fresh ingests of one tree send byte-identical patch ids and ops", async () => {
      fixture(30);
      for (let i = 0; i < 30; i += 3) {
        const target = (i + 1) % 30;
        writeFileSync(
          join(repo, "src", `m${String(i).padStart(3, "0")}.ts`),
          `import { f${target} } from "./m${String(target).padStart(3, "0")}.js";\n` +
            `export function f${i}(): number { return f${target}() + ${i}; }\n`,
          "utf8",
        );
      }
      git("add", "-A");
      const snapshot = (b: FakeBackend) =>
        [...b.lastOps.keys()].sort().map(uri => [uri, b.lastPatchIds.get(uri), JSON.stringify(b.lastOps.get(uri))]);

      await incremental();
      const first = snapshot(backend);
      expect(first).toHaveLength(30);
      expect(first.every(([, id]) => typeof id === "string" && id.length > 0)).toBe(true);

      const second = new FakeBackend();
      const homeB = realpathSync.native(mkdtempSync(join(tmpdir(), "ix-ingest-home-b-")));
      const keep = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE, IX_ENDPOINT: process.env.IX_ENDPOINT, IX_LOCK_DIR: process.env.IX_LOCK_DIR };
      try {
        process.env.IX_ENDPOINT = await second.start();
        process.env.HOME = homeB;
        process.env.USERPROFILE = homeB;
        process.env.IX_LOCK_DIR = join(homeB, "locks");
        await incremental();
        expect(snapshot(second)).toEqual(first);
      } finally {
        for (const [k, v] of Object.entries(keep)) {
          if (v === undefined) delete process.env[k]; else process.env[k] = v;
        }
        await second.stop();
        removeTree(homeB);
      }
    });
  });
});