assertledger 1.1.1 → 1.3.0

package/docs/reference.md

@@ -14,6 +14,9 @@ For a first run, use `assertledger doctor .` and the [Git qualification guide](g
 ```sh
 assertledger init . --dry-run --json
 assertledger init . --json
+assertledger setup . --client codex --dry-run --json
+assertledger setup . --client codex --write --json
+assertledger demo --allow-unsafe-execution --json
 assertledger audit . --json
 assertledger analyze . --json
 assertledger schema verification-request --json
@@ -310,20 +313,21 @@ caller decide whether the capability exists. The server resolves repository root
 confines them to the server process's current working directory by default. Programmatic operators
 may supply a different `allowedRepositoryRoots` allowlist.
 
-The doctor pair accepts a strict `{ "root": "..." }` input and returns the existing
-`repository-init-result` contract. It is read-only in both the default and operator-enabled server;
+The doctor pair accepts a strict `{ "root": "...", "exclude": ["..."] }` input, where the optional
+`exclude` entry names follow the [repository initialization](repository-init.md) exclusion rules,
+and returns the existing `repository-init-result` contract. It is read-only in both the default and operator-enabled server;
 enabling unsafe execution does not change doctor behavior. Dynamic runtime and client diagnostics
 remain outside this static readiness result.
 
-`doctor_runtime` accepts the same strict root input and returns the separate
-[runtime diagnostic contract](runtime-doctor.md). `check` accepts the
+`doctor_runtime` accepts only the strict root input and returns the separate
+[runtime diagnostic contract](runtime-doctor.md), v2 for a generated Bun configuration. `check` accepts the
 [high-level Git options](git-regression.md), without a permission field, and returns the existing
 evidence manifest. The operator's capability is required for both tools.
 
 ## Continuous integration
 
 Run `pnpm check` on every change. The included GitHub Actions workflow runs this gate on Node.js 22
-and 24 on Ubuntu, Windows and macOS. A separate matrix installs and exercises the packed artifact
+and 24 with Bun 1.4.2 on Ubuntu, Windows and macOS. A separate matrix installs and exercises the packed artifact
 on Ubuntu and Windows with Node.js 22.15.0 and 24. On Ubuntu, the gate also runs the real-daemon
 [container isolation](container-isolation.md) suite. A CI job that executes campaigns must
 also treat `trusted-local` as `UNSANDBOXED`: use an isolated runner without secrets or host

package/docs/repository-init.md

@@ -11,6 +11,20 @@ assertledger init . --json
 assertledger audit . --json
 ```
 
+To initialize and install a project-local read-only agent connection through one preflight, use:
+
+```sh
+assertledger setup . --client codex --dry-run --json
+assertledger setup . --client codex --write --json
+```
+
+`setup` previews by default. It composes the existing `init` and `connect` checks and refuses the
+whole operation before its first managed-file write if either side is blocked or conflicting. Use
+`--client claude-code` for Claude Code. It does not authorize execution, reload a client, or prove
+repository behavior. If a new connection conflict appears after init, rollback removes only regular
+init files created by this setup call whose bytes still equal the plan. A regenerated or changed
+file is preserved and reported under `PARTIAL_FAILURE` with exit code 5.
+
 The dry run emits the exact canonical bytes and SHA-256 digests that a subsequent write plans to
 use. Writes use a same-directory temporary file followed by an atomic rename. A second run returns
 `UNCHANGED` without rewriting matching files. A missing lock or a stale, structurally valid lock
@@ -22,13 +36,45 @@ plausible test frameworks, composite shell scripts, contradictory overrides, and
 adapter configurations return `CONFLICT`. Multiple CI providers are only sorted evidence and do not
 block initialization.
 
+The static inventory walks the filesystem, not the Git index, and never follows or copies a
+symbolic link: a link inside it returns `CONFLICT` with `UNSUPPORTED_REPOSITORY_SYMLINK` and writes
+nothing. It always skips entries named `.git`, `.testforge`, and `node_modules`, at any depth.
+When a local-only entry holds a link that no campaign needs, the operator can declare its name:
+
+```sh
+assertledger doctor . --exclude .claude --exclude .omx --json
+assertledger init . --exclude .claude --exclude .omx --json
+```
+
+Each `--exclude` value is one portable entry name without separators; every file or directory with
+that name is skipped at any depth. Anything else returns `CONFLICT` with
+`INVALID_REPOSITORY_EXCLUDE`. The declared names are written to `repository.exclude` beside the
+defaults. `init` and `doctor` without `--exclude`, `analyze` and runtime doctor's configuration check
+then reuse that list from a valid `assertledger.config.json`; an unreadable or invalid file leaves
+only the defaults, which widens the inventory. A configured entry that contains a separator matches
+nothing, as in a verification request. An explicit list, including an empty MCP `exclude` array,
+replaces the configured one, so a different declaration never silently widens or narrows the
+inventory: it fails closed, for example with `CONFIG_CONFLICT`, or with
+`UNSUPPORTED_REPOSITORY_SYMLINK` when a narrower list exposes a link again. Links outside the declared names stay fail-closed.
+
+The configured list governs only these static diagnostics and the evidence digests of
+`assertledger.lock.json`; it produces no campaign evidence. `audit`, a campaign's repository copy and
+its manifest `repositoryDigest` keep their own exclusions: the defaults, plus the verification
+request's `repository.exclude` for a campaign. `audit` therefore still refuses a linked local-only
+entry, and a request must declare the same names to leave it out of its copy; a committed
+configuration can never remove files from campaign evidence. Declaring a name is an operator decision
+recorded in a reviewable file, not a sandbox.
+
 Files at or below the managed `candidateRoots` are deliberately excluded from framework inference,
 evidence, built-in control tests, and repository-change comparison. Candidate generation therefore
 cannot silently redefine initialization facts or invalidate an otherwise unchanged lock.
 
-The built-in ready adapter is currently `node-test`. Bun, pytest, Vitest, and Jest can be detected,
-but initialization returns `BLOCKED` with `OFFICIAL_ADAPTER_UNAVAILABLE` unless the operator supplies
-an existing structured adapter configuration:
+The built-in ready adapters are `node-test` and `bun-test`. Bun initialization writes v2 config,
+lock, and result contracts; Node initialization stays v1. Bun's static plan does not qualify the
+installed runtime. Run runtime doctor and use a v3 verification request before claiming campaign
+evidence. Pytest, Vitest, and Jest can be detected, but initialization returns `BLOCKED` with
+`OFFICIAL_ADAPTER_UNAVAILABLE` unless the operator supplies an existing structured adapter
+configuration:
 
 ```sh
 assertledger init . --adapter-config integrations/my-adapter.json --json
@@ -37,8 +83,8 @@ assertledger init . --adapter-config integrations/my-adapter.json --json
 The adapter document is parsed through the public adapter contract and is operator-owned. Its
 executable is recorded as argv but is not resolved or executed by `init`. This is not an official
 adapter endorsement and does not reduce the later `trusted-local` execution boundary.
-`node-test` adapters are accepted only for the `node:test` framework; every other framework requires
-an operator-owned `testforge-command` adapter.
+`node-test` adapters are accepted only for `node:test`; `bun-test` adapters are accepted only for
+`bun:test`. Pytest, Vitest, and Jest require an operator-owned `testforge-command` adapter.
 
 All detections and evidence digests come from one byte snapshot. Immediately before returning or
 writing managed files, initialization rechecks the in-scope inventory and every evidence byte. A
@@ -54,7 +100,6 @@ Exit codes are `0` for `CREATED`, `UNCHANGED`, or `WOULD_CREATE`; `3` for `BLOCK
 ambiguity, invalid overrides, conflicts, or contract validation; `5` for unexpected I/O; and `64`
 for CLI usage errors.
 
-The public `repository-init-config.v1`, `repository-init-lock.v1`, and
-`repository-init-result.v1` contracts contain no timestamps, absolute repository roots, environment
+The public v1 and v2 initialization contracts contain no timestamps, absolute repository roots, environment
 values, worlds, or candidates. The lock binds normalized detections and sorted evidence digests; it
 does not authenticate the detector, repository, adapter, or later execution evidence.

package/docs/runtime-doctor.md

@@ -23,20 +23,23 @@ configuration inspection or executable probes. Unknown flags, repeated flags, an
 
 ## What it checks
 
-Version 1.0 supports the generated official `node:test` adapter. It fails closed for other
-frameworks and operator-supplied adapters. In order, it checks:
+Version 1.0 supports the generated official `node:test` adapter. Version 2.0 supports the
+generated official `bun:test` adapter on the qualified Bun 1.4.2 revision. Both fail closed for
+other frameworks and operator-supplied adapters. In order, they check:
 
 1. explicit trusted-local authorization;
 2. a current AssertLedger configuration and evidence lock;
-3. the supported generated `node:test` adapter;
-4. a stable Node.js executable at version 22.15 or newer;
-5. availability of Node's built-in `node:test` module;
+3. the supported generated adapter;
+4. a stable Node.js executable at version 22.15 or newer, or the exact Bun 1.4.2 revision;
+5. availability of the runner's built-in test module;
 6. permission to create, write, and clean up an operating-system temporary workspace;
 7. controlled reporter discovery, liveness, and attribution probes.
 
 The final probes use disposable synthetic tests. One assertion failure must be attributed to the
 candidate; a generic throw with a nested assertion cause must remain a process crash and must not
-be attributed. Malformed reporter output, missing discovery, cleanup failure, timeout, or process
+be attributed. The Bun probes also check its owned `assertSame` helper against a plain throw,
+a caught assertion, an operand error, and a native `expect` failure. Malformed reporter output,
+missing discovery, cleanup failure, timeout, or process
 failure blocks readiness. AssertLedger does not write to the repository during runtime doctor.
 
 ## Result contract
@@ -44,15 +47,15 @@ failure blocks readiness. AssertLedger does not write to the repository during r
 The SDK exposes the same strict additive contract:
 
 ```ts
-import { AssertLedger, parseRuntimeDoctorResult } from "assertledger";
+import { AssertLedger, parseVersionedRuntimeDoctorResult } from "assertledger";
 
 const result = await new AssertLedger().doctorRuntime(repositoryRoot, {
   allowUnsafeExecution: true,
 });
-parseRuntimeDoctorResult(result);
+parseVersionedRuntimeDoctorResult(result);
 ```
 
-`schemaVersion` is `1.0.0`. Each check has `PASS`, `BLOCKED`, or `LIMITATION`, a stable reason code
+`schemaVersion` is `1.0.0` for Node and `2.0.0` for Bun. Each check has `PASS`, `BLOCKED`, or `LIMITATION`, a stable reason code
 when relevant, a concise summary, and a safe next action. The top-level status is `READY` only when
 every supported runtime boundary passes. JSON results contain no subprocess output, environment
 values, credentials, or repository source.

package/integrations/bun/assertions.d.mts

@@ -0,0 +1,4 @@
+export declare function assertSame(actual: unknown, expected: unknown): void;
+
+/** @internal Identifies an error instance issued by this helper. */
+export declare function isAssertSameFailure(error: unknown): boolean;

package/integrations/bun/assertions.mjs

@@ -0,0 +1,25 @@
+const ASSERTION_ERROR_NAME = "AssertLedgerBunAssertionError";
+const ASSERTION_ERROR_MESSAGE = "AssertLedger assertSame failed";
+const issuedErrors = new WeakSet();
+const addIssuedError = WeakSet.prototype.add.bind(issuedErrors);
+const hasIssuedError = WeakSet.prototype.has.bind(issuedErrors);
+
+class AssertLedgerBunAssertionError extends Error {
+  constructor() {
+    super(ASSERTION_ERROR_MESSAGE);
+    this.name = ASSERTION_ERROR_NAME;
+  }
+}
+
+export function assertSame(actual, expected) {
+  if (!Object.is(actual, expected)) {
+    const error = new AssertLedgerBunAssertionError();
+    addIssuedError(error);
+    throw error;
+  }
+}
+
+/** @internal Identifies an error instance issued by this helper. */
+export function isAssertSameFailure(error) {
+  return typeof error === "object" && error !== null && hasIssuedError(error);
+}

package/integrations/bun/driver.d.mts

@@ -0,0 +1,27 @@
+export interface BunInstrumentedResult {
+  protocolVersion: "1.0.0";
+  outcome:
+    | "PASS"
+    | "ASSERTION_FAILURE"
+    | "PROCESS_CRASH"
+    | "TIMEOUT"
+    | "INFRA_ERROR"
+    | "NO_TEST_DISCOVERED";
+  testsDiscovered: number;
+  candidateTestsDiscovered: number;
+  attributed: boolean;
+}
+
+export type BunTestEvent =
+  | { kind: "found"; id: string; file: string }
+  | { kind: "end"; id: string; status: "pass" | "fail"; owned: boolean }
+  | { kind: "hook-error" };
+
+export function classifyBunInstrumentedEvidence(
+  events: readonly BunTestEvent[] | undefined,
+  junit: { tests: number; failures: number; skipped: number } | undefined,
+  baseFiles: ReadonlySet<string>,
+  candidateFiles: ReadonlySet<string>,
+  exitCode: number | null,
+  operationalError?: boolean,
+): BunInstrumentedResult;

package/integrations/bun/driver.mjs

@@ -0,0 +1,383 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const RESULT_VERSION = "1.0.0";
+const BUN_REVISION = "1.4.2+744846f84";
+const MAX_REPORT_BYTES = 8 * 1024 * 1024;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "gu");
+const PRELOAD_SOURCE_PATH = fileURLToPath(new URL("./preload.mjs", import.meta.url));
+
+function report(outcome, testsDiscovered = 0, candidateTestsDiscovered = 0, attributed = false) {
+  return {
+    protocolVersion: RESULT_VERSION,
+    outcome,
+    testsDiscovered,
+    candidateTestsDiscovered,
+    attributed,
+  };
+}
+
+function infrastructureFailure(reason) {
+  console.error(`BUN_TEST_INFRA_ERROR:${reason}`);
+  return report("INFRA_ERROR");
+}
+
+function normalizeRelativeFile(value) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.startsWith("-") ||
+    path.isAbsolute(value)
+  )
+    return undefined;
+  const normalized = path.normalize(value);
+  if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) return undefined;
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function normalizeAbsoluteFile(value, root) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) return undefined;
+  const relative = path.relative(root, path.resolve(value));
+  return normalizeRelativeFile(relative);
+}
+
+function strictInteger(value) {
+  if (typeof value !== "string" || !/^(0|[1-9][0-9]*)$/u.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function parseJunitSummary(xml) {
+  if (
+    typeof xml !== "string" ||
+    !xml.startsWith('<?xml version="1.0" encoding="UTF-8"?>') ||
+    !xml.trimEnd().endsWith("</testsuites>") ||
+    xml.includes("<!DOCTYPE")
+  )
+    return undefined;
+  const root = xml.match(/<testsuites\b([^>]*)>/u);
+  if (root === null) return undefined;
+  const attributes = new Map();
+  const matches = [...root[1].matchAll(/\s+([A-Za-z][A-Za-z0-9-]*)="([^"]*)"/gu)];
+  if (root[1].replace(/\s+([A-Za-z][A-Za-z0-9-]*)="([^"]*)"/gu, "").trim() !== "") {
+    return undefined;
+  }
+  for (const match of matches) {
+    if (attributes.has(match[1])) return undefined;
+    attributes.set(match[1], match[2]);
+  }
+  if (attributes.get("name") !== "bun test") return undefined;
+  const tests = strictInteger(attributes.get("tests"));
+  const failures = strictInteger(attributes.get("failures"));
+  const skipped = strictInteger(attributes.get("skipped"));
+  if (
+    tests === undefined ||
+    failures === undefined ||
+    skipped === undefined ||
+    failures > tests ||
+    skipped > tests
+  ) {
+    return undefined;
+  }
+  return { tests, failures, skipped };
+}
+
+function parseEvents(content, root, allowedFiles, evidenceKey) {
+  if (!content.endsWith("\n")) return undefined;
+  const lines = content.trimEnd().split("\n");
+  if (lines.length === 1 && lines[0] === "") return [];
+  const events = [];
+  for (const line of lines) {
+    let envelope;
+    try {
+      envelope = JSON.parse(line);
+    } catch {
+      return undefined;
+    }
+    if (
+      typeof envelope !== "object" ||
+      envelope === null ||
+      Array.isArray(envelope) ||
+      Object.keys(envelope).sort().join(",") !== "event,mac" ||
+      typeof envelope.mac !== "string" ||
+      !/^[0-9a-f]{64}$/u.test(envelope.mac)
+    )
+      return undefined;
+    const expectedMac = createHmac("sha256", evidenceKey)
+      .update(JSON.stringify(envelope.event))
+      .digest();
+    if (!timingSafeEqual(expectedMac, Buffer.from(envelope.mac, "hex"))) return undefined;
+    const value = envelope.event;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return undefined;
+    }
+    if (value.kind === "hook-error") {
+      if (Object.keys(value).join(",") !== "kind") return undefined;
+      events.push({ kind: "hook-error" });
+      continue;
+    }
+    if (typeof value.id !== "string" || !/^[0-9a-f-]{36}$/u.test(value.id)) {
+      return undefined;
+    }
+    if (value.kind === "found") {
+      if (Object.keys(value).sort().join(",") !== "file,id,kind") return undefined;
+      const file = normalizeAbsoluteFile(value.file, root);
+      if (file === undefined || !allowedFiles.has(file)) return undefined;
+      events.push({ kind: "found", id: value.id, file });
+    } else if (value.kind === "end") {
+      if (value.status !== "pass" && value.status !== "fail") return undefined;
+      const expectedKeys = value.status === "pass" ? "id,kind,status" : "id,kind,owned,status";
+      if (Object.keys(value).sort().join(",") !== expectedKeys) return undefined;
+      if (value.status === "fail" && typeof value.owned !== "boolean") return undefined;
+      events.push({ kind: "end", id: value.id, status: value.status, owned: value.owned ?? false });
+    } else return undefined;
+  }
+  return events;
+}
+
+export function classifyBunInstrumentedEvidence(
+  events,
+  junit,
+  baseFiles,
+  candidateFiles,
+  exitCode,
+  operationalError = false,
+) {
+  if (
+    events === undefined ||
+    junit === undefined ||
+    exitCode === null ||
+    junit.skipped !== 0 ||
+    operationalError ||
+    events.some((event) => event.kind === "hook-error")
+  ) {
+    return infrastructureFailure("INCOMPLETE_CONTROLLED_REPORT");
+  }
+  const found = new Map();
+  const ended = new Map();
+  for (const event of events) {
+    if (event.kind === "found") {
+      if (found.has(event.id)) return infrastructureFailure("DUPLICATE_TEST_ID");
+      found.set(event.id, event.file);
+    } else {
+      if (!found.has(event.id)) return infrastructureFailure("UNMATCHED_TEST_END");
+      if (ended.has(event.id)) return infrastructureFailure("DUPLICATE_TEST_END");
+      ended.set(event.id, event);
+    }
+  }
+  const completed = [...ended.values()];
+  if (found.size === 0 || found.size !== ended.size || completed.length !== junit.tests) {
+    return infrastructureFailure("TEST_COUNT_MISMATCH");
+  }
+  const files = new Set(found.values());
+  if ([...baseFiles].some((file) => !files.has(file))) {
+    return infrastructureFailure("BASE_TEST_FILE_NOT_STARTED");
+  }
+  if ([...files].some((file) => !baseFiles.has(file) && !candidateFiles.has(file))) {
+    return infrastructureFailure("UNEXPECTED_TEST_FILE");
+  }
+  const failures = completed.filter((entry) => entry.status === "fail");
+  if (failures.length !== junit.failures || (exitCode === 0) !== (junit.failures === 0)) {
+    return infrastructureFailure("BUN_STATUS_MISMATCH");
+  }
+  const candidateIds = completed
+    .filter((entry) => candidateFiles.has(found.get(entry.id)))
+    .map((entry) => entry.id);
+  if (exitCode === 0) {
+    return candidateFiles.size > 0 && candidateIds.length === 0
+      ? report("NO_TEST_DISCOVERED", completed.length, 0, false)
+      : report("PASS", completed.length, candidateIds.length, candidateFiles.size > 0);
+  }
+  const candidateFailures = failures.filter((entry) => candidateFiles.has(found.get(entry.id)));
+  const baseFailures = failures.filter((entry) => baseFiles.has(found.get(entry.id)));
+  if (baseFailures.length > 0 || candidateIds.length === 0) {
+    return report("PROCESS_CRASH", completed.length, candidateIds.length, false);
+  }
+  const attributed =
+    candidateFailures.length > 0 &&
+    failures.length === candidateFailures.length &&
+    candidateFailures.every((entry) => entry.owned);
+  return report(
+    attributed ? "ASSERTION_FAILURE" : "PROCESS_CRASH",
+    completed.length,
+    candidateIds.length,
+    attributed,
+  );
+}
+
+async function readBoundedRegularFile(file, root) {
+  const details = await lstat(file);
+  if (!details.isFile() || details.size > MAX_REPORT_BYTES) throw new Error("INVALID_REPORT_FILE");
+  const resolved = await realpath(file);
+  const relative = path.relative(root, resolved);
+  if (
+    relative === "" ||
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error("REPORT_PATH_ESCAPE");
+  }
+  return readFile(file, "utf8");
+}
+
+async function installHelper(helperSource, root) {
+  const packageRoot = path.join(root, "node_modules", "assertledger");
+  await mkdir(packageRoot, { recursive: true });
+  await writeFile(path.join(packageRoot, "bun.mjs"), helperSource, { flag: "wx" });
+  await writeFile(
+    path.join(packageRoot, "preload.mjs"),
+    await readFile(PRELOAD_SOURCE_PATH, "utf8"),
+    { flag: "wx" },
+  );
+  await writeFile(
+    path.join(packageRoot, "package.json"),
+    `${JSON.stringify({ name: "assertledger", type: "module", exports: { "./bun": "./bun.mjs" } }, null, 2)}\n`,
+    { flag: "wx" },
+  );
+}
+
+async function runBun(executable, files, junitFile, root, evidenceKey) {
+  const exactPath = (file) => `./${file.replaceAll(path.sep, "/")}`;
+  const childEnvironment = { ...process.env };
+  delete childEnvironment.TESTFORGE_RESULT_FILE;
+  delete childEnvironment.TESTFORGE_CANDIDATE_FILES;
+  delete childEnvironment.ASSERTLEDGER_BUN_EVENTS_FILE;
+  childEnvironment.ASSERTLEDGER_BUN_ROOT = root;
+  const child = spawn(
+    executable,
+    [
+      "test",
+      "--max-concurrency=1",
+      "--retry=0",
+      "--preload",
+      "./node_modules/assertledger/preload.mjs",
+      "--reporter=junit",
+      `--reporter-outfile=${junitFile}`,
+      ...files.map(exactPath),
+    ],
+    {
+      cwd: root,
+      env: childEnvironment,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+    },
+  );
+  let keyDeliveryError = false;
+  child.stdio[4].on("error", () => {
+    keyDeliveryError = true;
+  });
+  child.stdio[4].end(evidenceKey);
+  let outputBytes = 0;
+  let overflow = false;
+  let stderr = "";
+  let evidenceBytes = 0;
+  const evidenceChunks = [];
+  const collect = (chunk) => {
+    outputBytes += chunk.length;
+    if (outputBytes > MAX_OUTPUT_BYTES) {
+      overflow = true;
+      child.kill();
+    }
+  };
+  child.stdout.on("data", collect);
+  child.stderr.on("data", (chunk) => {
+    collect(chunk);
+    if (!overflow) stderr += chunk.toString("utf8");
+  });
+  child.stdio[3].on("data", (chunk) => {
+    evidenceBytes += chunk.length;
+    if (evidenceBytes > MAX_REPORT_BYTES) {
+      overflow = true;
+      child.kill();
+    } else {
+      evidenceChunks.push(chunk);
+    }
+  });
+  const exitCode = await new Promise((resolve) => {
+    child.once("error", () => resolve(null));
+    child.once("close", (code) => resolve(code));
+  });
+  const plainStderr = stderr.replace(ANSI_SGR, "");
+  const operationalError =
+    plainStderr.includes("Unhandled error between tests") ||
+    /(?:^|\r?\n)\s*[1-9][0-9]*\s+errors?\s*(?:\r?\n|$)/u.test(plainStderr);
+  return {
+    exitCode: overflow || keyDeliveryError ? null : exitCode,
+    operationalError,
+    eventContent: overflow ? undefined : Buffer.concat(evidenceChunks).toString("utf8"),
+  };
+}
+
+async function main() {
+  const root = await realpath(process.cwd());
+  const [executable, helperSourcePath, ...baseTests] = process.argv.slice(2);
+  if (
+    !path.isAbsolute(executable ?? "") ||
+    !path.isAbsolute(helperSourcePath ?? "") ||
+    baseTests.length === 0
+  ) {
+    throw new Error("INVALID_ARGUMENTS");
+  }
+  const revision = spawnSync(executable, ["--revision"], {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    timeout: 5_000,
+    maxBuffer: MAX_OUTPUT_BYTES,
+  });
+  if (revision.status !== 0 || revision.stderr !== "" || revision.stdout.trim() !== BUN_REVISION) {
+    throw new Error("UNSUPPORTED_BUN_REVISION");
+  }
+  const candidates = JSON.parse(process.env.TESTFORGE_CANDIDATE_FILES ?? "[]");
+  if (!Array.isArray(candidates)) throw new Error("INVALID_CANDIDATES");
+  const normalizedBase = baseTests.map(normalizeRelativeFile);
+  const normalizedCandidates = candidates.map(normalizeRelativeFile);
+  if ([...normalizedBase, ...normalizedCandidates].some((file) => file === undefined)) {
+    throw new Error("INVALID_PATH");
+  }
+  const files = [...normalizedBase, ...normalizedCandidates];
+  if (new Set(files).size !== files.length) throw new Error("DUPLICATE_TEST_FILE");
+  await installHelper(await readFile(helperSourcePath, "utf8"), root);
+  const junitFile = path.join(root, `__assertledger_bun_junit_${randomUUID()}.xml`);
+  const evidenceKey = randomBytes(32);
+  const execution = await runBun(
+    executable,
+    [...baseTests, ...candidates],
+    junitFile,
+    root,
+    evidenceKey,
+  );
+  let outcome;
+  try {
+    const junitContent = await readBoundedRegularFile(junitFile, root);
+    const allowed = new Set(files);
+    outcome = classifyBunInstrumentedEvidence(
+      execution.eventContent === undefined
+        ? undefined
+        : parseEvents(execution.eventContent, root, allowed, evidenceKey),
+      parseJunitSummary(junitContent),
+      new Set(normalizedBase),
+      new Set(normalizedCandidates),
+      execution.exitCode,
+      execution.operationalError,
+    );
+  } catch {
+    outcome = infrastructureFailure("MISSING_OR_INVALID_REPORT");
+  }
+  process.stdout.write(`${JSON.stringify(outcome)}\n`);
+  process.exitCode = outcome.outcome === "PASS" ? 0 : 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : "UNKNOWN_DRIVER_ERROR");
+    process.stdout.write(`${JSON.stringify(report("INFRA_ERROR"))}\n`);
+    process.exitCode = 1;
+  });
+}