assertledger 1.4.0 → 1.5.0

package/examples/orchestration/workspace/packages/leaf/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@public/leaf",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "bun ../../task.mjs build",
+    "check": "bun ../../task.mjs check",
+    "fail": "bun ../../task.mjs fail"
+  }
+}

package/examples/orchestration/workspace/packages/leaf/verdict.txt

@@ -0,0 +1 @@
+initial

package/examples/orchestration/workspace/pnpm-lock.yaml

@@ -0,0 +1,170 @@
+---
+lockfileVersion: '9.0'
+
+importers:
+
+  .:
+    configDependencies: {}
+    packageManagerDependencies:
+      pnpm:
+        specifier: 12.9.1
+        version: 12.9.1
+
+packages:
+
+  '@pnpm/exe.android-arm64@12.9.1':
+    resolution: {integrity: sha512-Hgm1XdqMTfBC8PdGLL+NjZWv4xyi7D6XNrN9fb24XGYlyTBmUtdCefKnCLmHujShRD8BEO1zqM30SNcKBDLysw==}
+    cpu: [arm64]
+    os: [android]
+
+  '@pnpm/exe.android-x64@12.9.1':
+    resolution: {integrity: sha512-WDGCe6jZRVZP3RC/q6hOkZylkPkIQIi1/GcrR/d/YzbihhAHXCczrk+UYnV5TgbsEnAYO7Cx+2rX3nfhHvy24w==}
+    cpu: [x64]
+    os: [android]
+
+  '@pnpm/exe.darwin-arm64@12.9.1':
+    resolution: {integrity: sha512-+7iiEEBgYN9szPWUnAuN6eOVMTI6Hrki5bcuC9n9xl9tTnT53Tpxpo45Hml+W4IrAU0d+Tmd0sPnVIbX59PD6w==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@pnpm/exe.darwin-x64@12.9.1':
+    resolution: {integrity: sha512-SK7TxJiR12GbJZGffRFHItkc+Mx+99v6xMMJ9/X//8NwWV1wo17a2bwfGI8qZpl17YwsrmPEFOOqhzE1GIlrtQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@pnpm/exe.freebsd-x64@12.9.1':
+    resolution: {integrity: sha512-4AjLk6uvTs2iO6wMit2hcxJ2M32xb7OV5SNFk+w6G8/NzcjcMB7ENEpyeXyLiP0kcnp8uaCGUct2NfrLCJ35eQ==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@pnpm/exe.linux-arm64-musl@12.9.1':
+    resolution: {integrity: sha512-dZL2ES1ckDWM9v+EtxoOklZ0WNdtayooi9iLiDUubopudX3zXPNR2mlrxBRgjbDgECOndQen2SmyxL5eZiBuKw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-arm64@12.9.1':
+    resolution: {integrity: sha512-cx+uF6xqwEtm7B8NV+1ve0xBg9gcuzQZ5R+0WgOWvKG/h978UljS6BgWs1ipIGuGgUdeVhm3PKmBltXIcczLXA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-ppc64@12.9.1':
+    resolution: {integrity: sha512-MpjPsy4XR17zAtLziQZfsN+wveWa/bUJggZtwfo3+SuyRmXnSvVkFD4+v8/3RTWyYaM6mwLUTjZDJ+g3urL+ew==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-riscv64@12.9.1':
+    resolution: {integrity: sha512-Oo67TKqqH+Bno+L6X7Xyorwp1QG82zKIkL0vbo1x2kcPTDiyPbdM+d6lIs4+hzeB1KHT5FDoGzZj2dad7Ft+eg==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-s390x@12.9.1':
+    resolution: {integrity: sha512-QAD5FRCdW36HfD58BV7DoDm6z8yv+GgSqcUV1+ERwYjpVQuG6ZTpf5o0x3KDas8eTLIW7MLYVdDdlAurWeArEg==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-x64-musl@12.9.1':
+    resolution: {integrity: sha512-mQDhBsGqcTkrLQM4q5igmRFcr6EAl4UM/FGawY+0CWGcqPpUmYUvDy9LHy80xxkHIWVJ886gvvso2XOjfav1Jw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-x64@12.9.1':
+    resolution: {integrity: sha512-+M5N74hM4fc87AAckxx/UIW+dUnWf2eko+HchJs/NZUxehLhekNyMI/GNaNXlvd+kWR+97XXBD51XRkkNiUtrA==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.win32-arm64@12.9.1':
+    resolution: {integrity: sha512-mI28C2wxobrDi6x1OYhBRyG10hnDq/4sEIyy5RzoX6LB4kLuv6K/d25HOpMwlW20cuM4M72k9NZpOdcmUxMbEA==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@pnpm/exe.win32-x64@12.9.1':
+    resolution: {integrity: sha512-SWoDMT0oD7NrDSIoPpkKD09D9fAQKNjwFZ3lezlCUhAfXxMv70zsfrNT2/P+GoCK2kefXF9OysUZkH1l5vvvfA==}
+    cpu: [x64]
+    os: [win32]
+
+  pnpm@12.9.1:
+    resolution: {integrity: sha512-BrBV//XNINwSeB3hc87TMQzglRvy7GICEaFgRdVETVyTpmMhB2TvKaZTphBFm6A2jw50+E2AxUcjz5Wq57wNbQ==}
+    engines: {node: '>=18.*'}
+    hasBin: true
+
+snapshots:
+
+  '@pnpm/exe.android-arm64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.android-x64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.darwin-arm64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.darwin-x64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.freebsd-x64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-arm64-musl@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-arm64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-ppc64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-riscv64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-s390x@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-x64-musl@12.9.1':
+    optional: true
+
+  '@pnpm/exe.linux-x64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.win32-arm64@12.9.1':
+    optional: true
+
+  '@pnpm/exe.win32-x64@12.9.1':
+    optional: true
+
+  pnpm@12.9.1:
+    optionalDependencies:
+      '@pnpm/exe.android-arm64': 12.9.1
+      '@pnpm/exe.android-x64': 12.9.1
+      '@pnpm/exe.darwin-arm64': 12.9.1
+      '@pnpm/exe.darwin-x64': 12.9.1
+      '@pnpm/exe.freebsd-x64': 12.9.1
+      '@pnpm/exe.linux-arm64': 12.9.1
+      '@pnpm/exe.linux-arm64-musl': 12.9.1
+      '@pnpm/exe.linux-ppc64': 12.9.1
+      '@pnpm/exe.linux-riscv64': 12.9.1
+      '@pnpm/exe.linux-s390x': 12.9.1
+      '@pnpm/exe.linux-x64': 12.9.1
+      '@pnpm/exe.linux-x64-musl': 12.9.1
+      '@pnpm/exe.win32-arm64': 12.9.1
+      '@pnpm/exe.win32-x64': 12.9.1
+
+---
+lockfileVersion: '9.0'
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+importers:
+  .: {}
+  packages/leaf: {}
+  packages/app:
+    dependencies:
+      '@public/leaf':
+        specifier: workspace:*
+        version: link:../leaf

package/examples/orchestration/workspace/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - packages/*

package/examples/orchestration/workspace/task.mjs

@@ -0,0 +1,23 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { complete } from "./completion.mjs";
+const kind = process.argv[2];
+const name = JSON.parse(readFileSync("package.json", "utf8")).name;
+const task = `${name}#${kind}`;
+const emit = (event) =>
+  appendFileSync(
+    process.env.ASSERTLEDGER_QUALIFICATION_TRACE,
+    `${JSON.stringify({ nonce: process.env.ASSERTLEDGER_QUALIFICATION_NONCE, task, event })}\n`,
+  );
+emit("start");
+if (kind === "fail" && name === "@public/leaf") {
+  emit("fail");
+  complete(7);
+  process.exit(7);
+}
+if (kind === "build") {
+  mkdirSync("dist", { recursive: true });
+  const verdict = readFileSync("verdict.txt", "utf8");
+  writeFileSync("dist/result.txt", verdict);
+  writeFileSync("dist/manifest.txt", "required-output\n");
+}
+emit("finish");

package/examples/orchestration/workspace/turbo.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalEnv": ["PATH"],
+  "globalPassThroughEnv": [
+    "ASSERTLEDGER_QUALIFICATION_TRACE",
+    "ASSERTLEDGER_QUALIFICATION_NONCE",
+    "ASSERTLEDGER_QUALIFICATION_CACHE",
+    "ASSERTLEDGER_QUALIFICATION_RESULT_FILE"
+  ],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "$TURBO_ROOT$/task.mjs",
+        "$TURBO_ROOT$/completion.mjs",
+        "!dist/**",
+        "!.turbo/**",
+        "!node_modules/**",
+        "verdict.txt"
+      ],
+      "outputs": ["dist/**"]
+    },
+    "check": {
+      "cache": false,
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "$TURBO_ROOT$/task.mjs",
+        "$TURBO_ROOT$/completion.mjs",
+        "!dist/**",
+        "!.turbo/**",
+        "!node_modules/**"
+      ],
+      "outputs": []
+    },
+    "fail": { "dependsOn": ["^fail"], "cache": false, "outputs": [] }
+  }
+}

package/examples/orchestration/workspace/wrapper.mjs

@@ -0,0 +1,45 @@
+import { appendFileSync, readFileSync, writeFileSync } from "node:fs";
+import { complete, execute } from "./completion.mjs";
+import { failCommandArgs, wrapperCommandArgs } from "./commands.mjs";
+const faults = JSON.parse(readFileSync("faults.json", "utf8"));
+const emit = (task, event) =>
+  appendFileSync(
+    process.env.ASSERTLEDGER_QUALIFICATION_TRACE,
+    `${JSON.stringify({ nonce: process.env.ASSERTLEDGER_QUALIFICATION_NONCE, task, event })}\n`,
+  );
+const layer = process.argv[2] ?? "terminal";
+emit(layer, "start");
+if (layer === "seed") {
+  writeFileSync("success-receipt.json", JSON.stringify({ exitCode: 0 }));
+  emit(layer, "finish");
+  process.exit(0);
+}
+let status;
+if (layer === "orchestrator") {
+  if (faults.omitStage || faults.staleResult) status = 0;
+  else {
+    emit("mandatory-stage", "start");
+    emit("mandatory-stage", "finish");
+    status = execute(
+      process.env.PUBLIC_TURBO_EXECUTABLE,
+      failCommandArgs({
+        emptySelection: faults.emptySelection,
+        cacheDirectory: process.env.ASSERTLEDGER_QUALIFICATION_CACHE,
+      }),
+      "leaf",
+    );
+    if (faults.swallow) status = 0;
+    if (faults.trailingMask) {
+      // A subsequent successful command replaces the failing command's status.
+      status = execute(process.execPath, ["-e", "process.exit(0)"], "trailing");
+    }
+  }
+} else if (faults.staleResult) {
+  // A prior success is deliberately seeded by a separate, ordered action.
+  status = JSON.parse(readFileSync("success-receipt.json", "utf8")).exitCode;
+} else {
+  status = execute(process.execPath, wrapperCommandArgs(import.meta.filename), "orchestrator");
+}
+emit(layer, status === 0 ? "finish" : "fail");
+complete(status);
+process.exit(status);

package/integrations/bun/driver.d.mts

@@ -17,9 +17,38 @@ export type BunTestEvent =
   | { kind: "end"; id: string; status: "pass" | "fail"; owned: boolean }
   | { kind: "hook-error" };
 
+/** The JUnit totals; `timeouts` counts the tests Bun failed with a TimeoutError. */
+export interface BunJunitSummary {
+  tests: number;
+  failures: number;
+  skipped: number;
+  timeouts?: number;
+}
+
+export type BunDesignatedEvent =
+  | { kind: "found"; id: string; file: string; designated: boolean }
+  | { kind: "end"; id: string; status: "pass" | "fail"; owned: boolean }
+  | { kind: "registered"; designated: number; file: string }
+  | { kind: "hook-error" };
+
+export function classifyBunDesignatedLoad(
+  events: readonly BunDesignatedEvent[] | undefined,
+  junit: BunJunitSummary | undefined,
+  designatedCount: number,
+  exitCode: number | null,
+  operationalError: boolean,
+): BunInstrumentedResult;
+
+export function classifyBunDesignatedRun(
+  events: readonly BunDesignatedEvent[] | undefined,
+  junit: BunJunitSummary | undefined,
+  exitCode: number | null,
+  operationalError: boolean,
+): BunInstrumentedResult;
+
 export function classifyBunInstrumentedEvidence(
   events: readonly BunTestEvent[] | undefined,
-  junit: { tests: number; failures: number; skipped: number } | undefined,
+  junit: BunJunitSummary | undefined,
   baseFiles: ReadonlySet<string>,
   candidateFiles: ReadonlySet<string>,
   exitCode: number | null,

package/integrations/bun/driver.mjs

@@ -83,10 +83,13 @@ function parseJunitSummary(xml) {
   ) {
     return undefined;
   }
-  return { tests, failures, skipped };
+  // Bun reports a per-test timeout as a TimeoutError failure, even when the callback threw later.
+  const timeouts = [...xml.matchAll(/<failure\b[^>]*\btype="TimeoutError"/gu)].length;
+  if (timeouts > failures) return undefined;
+  return { tests, failures, skipped, timeouts };
 }
 
-function parseEvents(content, root, allowedFiles, evidenceKey) {
+function parseEvents(content, root, allowedFiles, evidenceKey, designated = false) {
   if (!content.endsWith("\n")) return undefined;
   const lines = content.trimEnd().split("\n");
   if (lines.length === 1 && lines[0] === "") return [];
@@ -120,14 +123,26 @@ function parseEvents(content, root, allowedFiles, evidenceKey) {
       events.push({ kind: "hook-error" });
       continue;
     }
+    if (value.kind === "registered") {
+      if (!designated || Object.keys(value).sort().join(",") !== "designated,file,kind") {
+        return undefined;
+      }
+      const file = normalizeAbsoluteFile(value.file, root);
+      if (file === undefined || !allowedFiles.has(file) || !Number.isSafeInteger(value.designated))
+        return undefined;
+      events.push({ kind: "registered", file, designated: value.designated });
+      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 expectedKeys = designated ? "designated,file,id,kind" : "file,id,kind";
+      if (Object.keys(value).sort().join(",") !== expectedKeys) return undefined;
+      if (designated && typeof value.designated !== "boolean") return undefined;
       const file = normalizeAbsoluteFile(value.file, root);
       if (file === undefined || !allowedFiles.has(file)) return undefined;
-      events.push({ kind: "found", id: value.id, file });
+      events.push({ kind: "found", id: value.id, file, designated: value.designated === true });
     } 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";
@@ -157,6 +172,8 @@ export function classifyBunInstrumentedEvidence(
   ) {
     return infrastructureFailure("INCOMPLETE_CONTROLLED_REPORT");
   }
+  // A test Bun timed out is never assertion evidence, whatever its callback threw afterwards.
+  if (junit.timeouts > 0) return infrastructureFailure("BUN_TEST_TIMEOUT");
   const found = new Map();
   const ended = new Map();
   for (const event of events) {
@@ -209,6 +226,131 @@ export function classifyBunInstrumentedEvidence(
   );
 }
 
+/**
+ * Loads designated files without registering a test. Success proves that each file and every module
+ * it imports evaluate in this world and that each designated test is registered exactly once.
+ */
+export function classifyBunDesignatedLoad(
+  events,
+  junit,
+  designatedCount,
+  exitCode,
+  operationalError,
+) {
+  if (
+    events === undefined ||
+    exitCode !== 0 ||
+    operationalError ||
+    (junit !== undefined && junit.tests !== 0) ||
+    events.some((event) => event.kind !== "registered")
+  ) {
+    return infrastructureFailure("DESIGNATED_LOAD_INCOMPLETE");
+  }
+  for (let index = 0; index < designatedCount; index += 1) {
+    const matches = events.filter((event) => event.designated === index).length;
+    if (matches === 0) return report("NO_TEST_DISCOVERED", events.length, 0, false);
+    if (matches > 1) return infrastructureFailure("DESIGNATED_TEST_AMBIGUOUS");
+  }
+  if (events.some((event) => event.designated < -1 || event.designated >= designatedCount)) {
+    return infrastructureFailure("DESIGNATED_TEST_INDEX_INVALID");
+  }
+  return report("PASS", events.length, 0, false);
+}
+
+/**
+ * Runs exactly one designated test. Only its owned assertion failure, with the expected first line
+ * when one is declared, is an assertion; no matching test is never a failure.
+ */
+export function classifyBunDesignatedRun(events, junit, exitCode, operationalError) {
+  if (
+    events === undefined ||
+    junit === undefined ||
+    exitCode === null ||
+    operationalError ||
+    events.some((event) => event.kind === "hook-error" || event.kind === "registered")
+  ) {
+    return infrastructureFailure("INCOMPLETE_CONTROLLED_REPORT");
+  }
+  // A test Bun timed out is never assertion evidence, whatever its callback threw afterwards.
+  if (junit.timeouts > 0) return infrastructureFailure("BUN_TEST_TIMEOUT");
+  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);
+    } 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);
+    }
+  }
+  if (found.size !== ended.size || found.size !== junit.tests - junit.skipped) {
+    return infrastructureFailure("TEST_COUNT_MISMATCH");
+  }
+  if (found.size === 0) {
+    return junit.failures === 0 && exitCode !== 0
+      ? report("NO_TEST_DISCOVERED", 0, 0, false)
+      : infrastructureFailure("BUN_STATUS_MISMATCH");
+  }
+  if ([...found.values()].some((event) => !event.designated)) {
+    return infrastructureFailure("UNEXPECTED_TEST");
+  }
+  if (found.size !== 1) return infrastructureFailure("DESIGNATED_TEST_AMBIGUOUS");
+  const [end] = ended.values();
+  const failed = end.status === "fail";
+  if (junit.failures !== (failed ? 1 : 0) || (exitCode === 0) === failed) {
+    return infrastructureFailure("BUN_STATUS_MISMATCH");
+  }
+  if (!failed) return report("PASS", 1, 1, true);
+  return end.owned ? report("ASSERTION_FAILURE", 1, 1, true) : report("PROCESS_CRASH", 1, 1, false);
+}
+
+function escapeRegularExpression(value) {
+  return value.replace(/[\\^$.*+?()[\]{}|/-]/gu, "\\$&");
+}
+
+/** Validates a designated selection against the files the driver was asked to load or run. */
+function parseDesignatedSelection(value, files) {
+  if (value === undefined) return undefined;
+  const selection = JSON.parse(value);
+  const validTest = (test) =>
+    typeof test === "object" &&
+    test !== null &&
+    Object.keys(test).sort().join(",") === "file,path" &&
+    normalizeRelativeFile(test.file) !== undefined &&
+    Array.isArray(test.path) &&
+    test.path.length > 0 &&
+    test.path.every((name) => typeof name === "string" && name.length > 0);
+  const fileSet = (tests) => [...new Set(tests.map((test) => normalizeRelativeFile(test.file)))];
+  const sameFiles = (tests) =>
+    JSON.stringify(fileSet(tests).sort()) === JSON.stringify([...files].sort());
+  if (
+    selection?.mode === "run" &&
+    Object.keys(selection).sort().join(",") === "expectedFailure,mode,test,testTimeoutMs" &&
+    validTest(selection.test) &&
+    (selection.expectedFailure === null || typeof selection.expectedFailure === "string") &&
+    (selection.testTimeoutMs === null ||
+      (Number.isSafeInteger(selection.testTimeoutMs) &&
+        selection.testTimeoutMs >= 1 &&
+        selection.testTimeoutMs <= 3_600_000)) &&
+    sameFiles([selection.test])
+  ) {
+    return selection;
+  }
+  if (
+    selection?.mode === "load" &&
+    Object.keys(selection).sort().join(",") === "mode,tests" &&
+    Array.isArray(selection.tests) &&
+    selection.tests.length > 0 &&
+    selection.tests.every(validTest) &&
+    sameFiles(selection.tests)
+  ) {
+    return selection;
+  }
+  throw new Error("INVALID_DESIGNATED_SELECTION");
+}
+
 async function readBoundedRegularFile(file, root) {
   const details = await lstat(file);
   if (!details.isFile() || details.size > MAX_REPORT_BYTES) throw new Error("INVALID_REPORT_FILE");
@@ -241,12 +383,13 @@ async function installHelper(helperSource, root) {
   );
 }
 
-async function runBun(executable, files, junitFile, root, evidenceKey) {
+async function runBun(executable, files, junitFile, root, evidenceKey, extraArguments = []) {
   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;
+  delete childEnvironment.ASSERTLEDGER_BUN_RESULT_FILE;
   childEnvironment.ASSERTLEDGER_BUN_ROOT = root;
   const child = spawn(
     executable,
@@ -258,6 +401,7 @@ async function runBun(executable, files, junitFile, root, evidenceKey) {
       "./node_modules/assertledger/preload.mjs",
       "--reporter=junit",
       `--reporter-outfile=${junitFile}`,
+      ...extraArguments,
       ...files.map(exactPath),
     ],
     {
@@ -343,9 +487,17 @@ async function main() {
   }
   const files = [...normalizedBase, ...normalizedCandidates];
   if (new Set(files).size !== files.length) throw new Error("DUPLICATE_TEST_FILE");
+  const selection = parseDesignatedSelection(process.env.ASSERTLEDGER_BUN_DESIGNATED, files);
+  if (selection !== undefined && normalizedCandidates.length > 0) {
+    throw new Error("INVALID_DESIGNATED_SELECTION");
+  }
   await installHelper(await readFile(helperSourcePath, "utf8"), root);
   const junitFile = path.join(root, `__assertledger_bun_junit_${randomUUID()}.xml`);
   const evidenceKey = randomBytes(32);
+  if (selection !== undefined) {
+    await runDesignated(executable, baseTests, files, selection, junitFile, root, evidenceKey);
+    return;
+  }
   const execution = await runBun(
     executable,
     [...baseTests, ...candidates],
@@ -370,7 +522,64 @@ async function main() {
   } catch {
     outcome = infrastructureFailure("MISSING_OR_INVALID_REPORT");
   }
-  process.stdout.write(`${JSON.stringify(outcome)}\n`);
+  await emit(outcome);
+}
+
+async function runDesignated(
+  executable,
+  testFiles,
+  files,
+  selection,
+  junitFile,
+  root,
+  evidenceKey,
+) {
+  const pattern =
+    selection.mode === "run"
+      ? [
+          `--test-name-pattern=^${escapeRegularExpression(selection.test.path.join(" "))}$`,
+          ...(selection.testTimeoutMs === null ? [] : [`--timeout=${selection.testTimeoutMs}`]),
+        ]
+      : [];
+  const execution = await runBun(executable, testFiles, junitFile, root, evidenceKey, pattern);
+  let outcome;
+  try {
+    let junit;
+    try {
+      junit = parseJunitSummary(await readBoundedRegularFile(junitFile, root));
+    } catch (error) {
+      // A load registers no test, so Bun writes no report; a run must always have one.
+      if (selection.mode === "run" || error?.code !== "ENOENT") throw error;
+    }
+    // No registration or no matching test leaves the signed channel empty.
+    const events =
+      execution.eventContent === undefined
+        ? undefined
+        : execution.eventContent === ""
+          ? []
+          : parseEvents(execution.eventContent, root, new Set(files), evidenceKey, true);
+    outcome =
+      selection.mode === "run"
+        ? classifyBunDesignatedRun(events, junit, execution.exitCode, execution.operationalError)
+        : classifyBunDesignatedLoad(
+            events,
+            junit,
+            selection.tests.length,
+            execution.exitCode,
+            execution.operationalError,
+          );
+  } catch {
+    outcome = infrastructureFailure("MISSING_OR_INVALID_REPORT");
+  }
+  await emit(outcome);
+}
+
+/** Prints the report and, inside a container, also writes it where the engine reads it back. */
+async function emit(outcome) {
+  const body = `${JSON.stringify(outcome)}\n`;
+  const resultFile = process.env.ASSERTLEDGER_BUN_RESULT_FILE;
+  if (resultFile !== undefined) await writeFile(resultFile, body, { flag: "wx" });
+  process.stdout.write(body);
   process.exitCode = outcome.outcome === "PASS" ? 0 : 1;
 }