@afokapu/atdd-bun 0.1.0

package/detectors/bun_interlocking_coverage/atdd.implementation.yaml

@@ -0,0 +1,27 @@
+schema_version: 1.1.0
+kind: implementation
+subtype: validator
+implementation_id: bun_interlocking_coverage
+targets_workspace: atdd.workspace.bun
+contract_version: 1.1.0
+# Bun/TS realization of the core python `interlocking_coverage.py` detector, mirroring
+# convex.workspace.runtime's convex_interlocking_coverage 1:1 — four strict
+# tester.bun.interlocking-* rule_ids from ONE implementation (Core FAMILY pattern).
+#
+# TESTER PERSONA. This family reads the declared route space (plan/**) and the consumer's
+# TEST files, and never reports on source. It is registered in
+# conformance/test_persona_scoping.py's tester set for exactly that reason — the coder
+# side of interlocking is bun_interlocking_infrastructure.
+realizes_convention:
+- tester.bun.interlocking-route-coverage
+- tester.bun.interlocking-production-runner-used
+- tester.bun.interlocking-smoke-coverage-for-station-master
+- tester.bun.interlocking-trace-binds-declared-route
+emits_rule_ids:
+- tester.bun.interlocking-route-coverage
+- tester.bun.interlocking-production-runner-used
+- tester.bun.interlocking-smoke-coverage-for-station-master
+- tester.bun.interlocking-trace-binds-declared-route
+- tester.bun.interlocking-train-sequence-is-exercised
+entrypoint: detect.mjs
+report: detect.mjs

package/detectors/bun_interlocking_coverage/checks/_map.json

@@ -0,0 +1,7 @@
+{
+  "interlocking_route_coverage": "tester.bun.interlocking-route-coverage",
+  "interlocking_production_runner": "tester.bun.interlocking-production-runner-used",
+  "interlocking_smoke_coverage": "tester.bun.interlocking-smoke-coverage-for-station-master",
+  "interlocking_trace_binds": "tester.bun.interlocking-trace-binds-declared-route",
+  "interlocking_train_sequence": "tester.bun.interlocking-train-sequence-is-exercised"
+}

package/detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+// Check: tester.bun.interlocking-production-runner-used  (disposition: strict, severity 1)
+//
+// A test that exercises an interlocking MUST drive the production runtime objects — InterlockingRunner
+// (route resolution) and TrainRunner (linear execution), core afokapu/atdd#1251 — and MUST NOT
+// substitute a mock/spy/hand-built resolver for them. Bun mirror of core
+// tester.interlocking.production-runner-used. Scans `e2e/**/*.ts` interlocking tests.
+import {
+  parseJsonEnv,
+  readText,
+  findConsumerRoots,
+  interlockingFiles,
+  e2eFiles,
+  parseInterlocking,
+  interlockingTokenSet,
+  isInterlockingTest,
+  tokenCovered,
+  maskComments,
+  lineOfIndex,
+  lineAt,
+  PROD_INTERLOCKING,
+  PROD_TRAIN,
+  FORBIDDEN_PATTERNS,
+  rel,
+  mk,
+  writeReport,
+} from "../_shared/interlocking.mjs";
+
+const RULE = "tester.bun.interlocking-production-runner-used";
+const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
+const violations = [];
+
+for (const scanRoot of roots) {
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const records = interlockingFiles(croot)
+      .map((f) => parseInterlocking(readText(f)))
+      .filter(Boolean);
+    const tokens = interlockingTokenSet(records);
+
+    for (const file of e2eFiles(croot)) {
+      const raw = readText(file);
+      const text = maskComments(raw);
+      if (!isInterlockingTest(text, tokens)) continue;
+      const r = rel(file, croot);
+
+      for (const [label, pat] of FORBIDDEN_PATTERNS) {
+        const m = pat.exec(text);
+        if (m) {
+          const line = lineOfIndex(text, m.index);
+          violations.push(
+            mk(
+              RULE,
+              r,
+              line,
+              0,
+              `interlocking test "${r}" substitutes the production runner (${label}); drive ` +
+                `InterlockingRunner -> TrainRunner directly instead`,
+              lineAt(raw, line),
+            ),
+          );
+        }
+      }
+
+      const missing = [PROD_INTERLOCKING, PROD_TRAIN].filter((sym) => !tokenCovered(sym, text));
+      if (missing.length) {
+        violations.push(
+          mk(
+            RULE,
+            r,
+            1,
+            0,
+            `interlocking test "${r}" does not reference the production runner(s) ${missing.join(", ")}; ` +
+              `it must exercise the real InterlockingRunner -> TrainRunner path (core afokapu/atdd#1251)`,
+            "",
+          ),
+        );
+      }
+    }
+  }
+}
+
+writeReport(violations);

package/detectors/bun_interlocking_coverage/checks/interlocking_route_coverage.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+// Check: tester.bun.interlocking-route-coverage  (disposition: strict, severity 1)
+//
+// Every admissible route declared in an interlocking's guarded route space (the `routes:` of
+// plan/_trains/_interlockings/**/*.yaml, core afokapu/atdd#1248) MUST have at least one e2e test that
+// exercises it — referenced by its routeId or resolved trainId in an `e2e/**/*.ts` test. An admissible
+// route with no covering e2e test is a silent-green route-control branch. Bun mirror of core
+// tester.interlocking.route-coverage.
+import {
+  parseJsonEnv,
+  readText,
+  findConsumerRoots,
+  interlockingFiles,
+  e2eFiles,
+  parseInterlocking,
+  isRouteCovered,
+  maskComments,
+  rel,
+  mk,
+  writeReport,
+} from "../_shared/interlocking.mjs";
+
+const RULE = "tester.bun.interlocking-route-coverage";
+const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
+const violations = [];
+
+for (const scanRoot of roots) {
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const records = interlockingFiles(croot)
+      .map((f) => ({ file: f, rec: parseInterlocking(readText(f)) }))
+      .filter((x) => x.rec);
+    const e2eTexts = e2eFiles(croot).map((f) => maskComments(readText(f)));
+
+    for (const { file, rec } of records) {
+      for (const route of rec.routes) {
+        if (isRouteCovered(route, e2eTexts)) continue;
+        const cat =
+          route.category !== null
+            ? `category "${route.category}"`
+            : "uncategorised";
+        violations.push(
+          mk(
+            RULE,
+            rel(file, croot),
+            route.line,
+            0,
+            `admissible route "${route.routeId}" of interlocking "${rec.interlockingId}" (${cat}, ` +
+              `resolves to train "${route.trainId}") has no e2e test exercising it; add an e2e/**/*.ts ` +
+              `test that references the routeId or trainId and drives it through InterlockingRunner -> TrainRunner`,
+            route.sourceLine.trim(),
+          ),
+        );
+      }
+    }
+  }
+}
+
+writeReport(violations);

package/detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+// Check: tester.bun.interlocking-smoke-coverage-for-station-master  (disposition: strict, severity 1)
+//
+// Every EXPOSED Station Master action of an interlocking (entrypoint.exposed:true with an actions
+// entry, core afokapu/atdd#1248) MUST have a smoke test that drives the action through the real
+// entrypoint -> Station Master -> InterlockingRunner -> TrainRunner path (#1251). Internal
+// (exposed:false) interlockings have no Station Master action and are OUT OF SCOPE. Bun mirror of
+// core tester.interlocking.smoke-coverage-for-station-master. The enforced minimum smoke signature is
+// an `e2e/**/*.ts` file referencing the action name AND a Station Master reference AND both runners.
+import {
+  parseJsonEnv,
+  readText,
+  findConsumerRoots,
+  interlockingFiles,
+  e2eFiles,
+  parseInterlocking,
+  tokenCovered,
+  maskComments,
+  lineOf,
+  STATION_MASTER,
+  PROD_INTERLOCKING,
+  PROD_TRAIN,
+  rel,
+  mk,
+  writeReport,
+} from "../_shared/interlocking.mjs";
+
+const RULE = "tester.bun.interlocking-smoke-coverage-for-station-master";
+const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
+const violations = [];
+
+function actionSmokeCovered(action, e2eTexts) {
+  return e2eTexts.some(
+    (t) =>
+      tokenCovered(action, t) && STATION_MASTER.test(t) && t.includes(PROD_INTERLOCKING) && t.includes(PROD_TRAIN),
+  );
+}
+
+for (const scanRoot of roots) {
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const records = interlockingFiles(croot)
+      .map((f) => ({ file: f, rec: parseInterlocking(readText(f)) }))
+      .filter((x) => x.rec);
+    const e2eTexts = e2eFiles(croot).map((f) => maskComments(readText(f)));
+
+    for (const { file, rec } of records) {
+      if (!rec.exposed) continue;
+      for (const action of rec.actions) {
+        if (actionSmokeCovered(action, e2eTexts)) continue;
+        const [line, src] = lineOf(rec.rawText, new RegExp("^\\s*-\\s*['\"]?" + action + "['\"]?\\s*$"));
+        violations.push(
+          mk(
+            RULE,
+            rel(file, croot),
+            line,
+            0,
+            `exposed Station Master action "${action}" of interlocking "${rec.interlockingId}" has no smoke ` +
+              `test reaching the Station Master and driving InterlockingRunner -> TrainRunner; add an e2e smoke ` +
+              `test (strict: exposed actions are critical user-facing routes)`,
+            src.trim(),
+          ),
+        );
+      }
+    }
+  }
+}
+
+writeReport(violations);

package/detectors/bun_interlocking_coverage/checks/interlocking_trace_binds.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+// Check: tester.bun.interlocking-trace-binds-declared-route  (disposition: strict, severity 1)
+//
+// A test that asserts on the runtime trace emitted by interlocking execution MUST bind that trace back
+// to the source interlocking declaration — it must assert EVERY required trace field so the executed
+// route is traceable to the YAML it came from (core afokapu/atdd#1248/#1251). Bun mirror of core
+// tester.interlocking.trace-binds-declared-route. Required TS trace fields: interlockingId, routeId,
+// selectedTrainId, routeCategory, routeCategoryDigit, guardId, resolutionStrategy, resolutionReason.
+import {
+  parseJsonEnv,
+  readText,
+  findConsumerRoots,
+  interlockingFiles,
+  e2eFiles,
+  parseInterlocking,
+  interlockingTokenSet,
+  isInterlockingTest,
+  maskComments,
+  lineOfIndex,
+  lineAt,
+  TRACE_OBJECT,
+  REQUIRED_TRACE_FIELDS,
+  rel,
+  mk,
+  writeReport,
+} from "../_shared/interlocking.mjs";
+
+const RULE = "tester.bun.interlocking-trace-binds-declared-route";
+const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
+const violations = [];
+
+for (const scanRoot of roots) {
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const records = interlockingFiles(croot)
+      .map((f) => parseInterlocking(readText(f)))
+      .filter(Boolean);
+    const tokens = interlockingTokenSet(records);
+
+    for (const file of e2eFiles(croot)) {
+      const raw = readText(file);
+      const text = maskComments(raw);
+      if (!isInterlockingTest(text, tokens)) continue;
+      const m = TRACE_OBJECT.exec(text);
+      if (!m) continue; // not a trace-binding test.
+      const missing = REQUIRED_TRACE_FIELDS.filter(([, pat]) => !pat.test(text)).map(([label]) => label);
+      if (!missing.length) continue;
+      const line = lineOfIndex(text, m.index);
+      violations.push(
+        mk(
+          RULE,
+          rel(file, croot),
+          line,
+          0,
+          `interlocking trace test "${rel(file, croot)}" does not bind the declared route: missing required ` +
+            `trace field(s) ${missing.join(", ")} (core afokapu/atdd#1251 trace must record interlockingId/` +
+            `routeId/selectedTrainId/routeCategory/routeCategoryDigit/guardId/resolutionStrategy/resolutionReason)`,
+          lineAt(raw, line),
+        ),
+      );
+    }
+  }
+}
+
+writeReport(violations);

package/detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+// tester.bun.interlocking-train-sequence-is-exercised (GATED — was staged)
+//
+// The tester half of the executes-the-declaration pair. Route coverage proves WHICH
+// train a route selects and trace binding proves the run is attributable to its
+// route; both are statements about SELECTION. A train whose wagon sequence is wrong
+// is selected correctly and runs the wrong thing.
+//
+// STAGED, exactly as the python sibling is: this is a ROOT-level entry point, not a
+// file under checks/, so the gated family runner (detect.mjs) never collects it. No
+// consumer satisfies the rule yet and wiring it into a blocking gate would escalate
+// an advisory concern silently. Enabling it is a gate change, not a build.
+//
+// Demonstrated before being written: on a consumer whose TrainRunner genuinely reads
+// the train definition, replacing a train's entire `sequence:` in the plan left its
+// suite green. The runtime obeyed the new plan; no test looked.
+import {
+  parseJsonEnv, readText, findConsumerRoots, interlockingFiles, e2eFiles,
+  parseInterlocking, tokenCovered, rel, mk,
+} from "../_shared/interlocking.mjs";
+import { writeFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const RULE_SEQUENCE = "tester.bun.interlocking-train-sequence-is-exercised";
+
+// A line that ASSERTS AN ORDER: names the executed sequence AND compares it.
+// Merely touching the word is not asserting the order — `expect(trace.steps)` alone
+// says nothing about what ran, and counting it would repeat the over-broad trigger
+// that has now been fixed three times in this family.
+const SEQUENCE_ASSERTION =
+  /^[^\n]*\b(?:expect|assert)\b[^\n]*\b(?:steps|sequence|wagons)\b[^\n]*(?:==|toEqual|toStrictEqual|deepEqual)/m;
+
+export function assertsASequence(text) {
+  return SEQUENCE_ASSERTION.test(text);
+}
+
+export function trainsReachableFromRoutes(records) {
+  // `trainId`, not `train_id`. The planner YAML is snake_case and stack-neutral, but
+  // this provider's parseInterlocking normalises each route to camelCase. Reading the
+  // YAML field name here returned an EMPTY train set, so the check passed on every
+  // tree by having nothing to check — a vacuous green that looked like a clean port.
+  // Caught by asking what the silent run had actually examined.
+  const out = new Set();
+  for (const rec of records) for (const r of rec.routes || []) if (r.trainId) out.add(r.trainId);
+  return out;
+}
+
+export function trainSequenceCovered(trainId, texts) {
+  return texts.some((t) => tokenCovered(trainId, t) && assertsASequence(t));
+}
+
+// Does the plan actually DECLARE a wagon sequence for this train?
+//
+// The rule asks whether a declared sequence is exercised. Where the plan declares no
+// sequence — the train artifact is absent, or carries no `sequence:` — there is
+// nothing a test could assert, so this is NOT_APPLICABLE, not a failure. Firing there
+// reported "no test asserts the wagon SEQUENCE" about a sequence that does not exist,
+// and a route pointing at a missing train is the binding family's concern
+// (declared_route_not_runtime_resolvable), not this one.
+export function declaresASequence(croot, trainId) {
+  const found = [];
+  (function rec(dir) {
+    let entries;
+    try { entries = readdirSync(dir).sort(); } catch { return; }
+    for (const name of entries) {
+      const full = join(dir, name);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) { if (name !== "_interlockings") rec(full); continue; }
+      if (/\.ya?ml$/.test(name)) found.push(full);
+    }
+  })(join(croot, "plan"));
+  for (const f of found) {
+    const text = readText(f);
+    if (!text.includes(trainId)) continue;
+    if (/^\s*sequence:\s*$/m.test(text) || /^\s*sequence:\s*\[/m.test(text)) return true;
+  }
+  return false;
+}
+
+export function scanExecution(scanRoot) {
+  const violations = [];
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const records = interlockingFiles(croot).map((f) => parseInterlocking(readText(f))).filter(Boolean);
+    if (!records.length) continue;
+    const files = e2eFiles(croot).map((f) => ({ file: f, text: readText(f) }));
+    const texts = files.map((x) => x.text);
+    const anchor = files.length ? rel(files[0].file, croot) : "e2e/";
+    for (const trainId of [...trainsReachableFromRoutes(records)].sort()) {
+      if (!declaresASequence(croot, trainId)) continue;   // nothing declared to exercise
+      if (trainSequenceCovered(trainId, texts)) continue;
+      violations.push(
+        mk(RULE_SEQUENCE, anchor, 1, 0,
+          `declared train "${trainId}" is selected by a route but no test asserts the wagon ` +
+          `SEQUENCE it executes; reorder or empty its definition and the suite stays green`,
+          ""),
+      );
+    }
+  }
+  return violations;
+}
+
+// Runnable on its own so the obligation is exercisable code, not a paragraph.
+if (import.meta.main ?? process.argv[1]?.endsWith("interlocking_train_sequence.mjs")) {
+  const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
+  const out = roots.flatMap((r) => scanExecution(r));
+  const rp = process.env.ATDD_VIOLATIONS_REPORT;
+  if (rp) writeFileSync(rp, JSON.stringify({ violations: out }, null, 2), "utf8");
+  process.stderr.write(`bun-interlocking-sequence: ${out.length} violation(s)\n`);
+}

package/detectors/bun_interlocking_coverage/detect.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+// FAMILY validator: bun_interlocking_coverage
+// Runs each member check (checks/*.mjs) VERBATIM as a subprocess and merges their
+// RAW v1.1 reports into one — ONE implementation realizing a family of rule_ids
+// (the Core pattern; see frontend.workspace.runtime's families).
+//
+// Members are spawned with `process.execPath`, which under this provider IS the
+// bun binary, so a member may be authored as .mjs OR .ts with no build step.
+// Files whose name begins with `_` are skipped: they are shared helpers, not
+// checks. (The node-runtime families have no such convention because each of
+// their checks re-implements its own walker; this provider factors the walk into
+// lib/scan.mjs instead.)
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const reportPath = process.env.ATDD_VIOLATIONS_REPORT;
+if (!reportPath) {
+  process.stderr.write("family: ATDD_VIOLATIONS_REPORT not set\n");
+  process.exit(2);
+}
+const checks = readdirSync(join(here, "checks"))
+  .filter((f) => (f.endsWith(".mjs") || f.endsWith(".ts")) && !f.startsWith("_"))
+  .sort();
+const td = mkdtempSync(join(tmpdir(), "atdd-bun-ilc-"));
+const out = [];
+for (const c of checks) {
+  const rep = join(td, c + ".json");
+  try {
+    execFileSync(process.execPath, [join(here, "checks", c)], {
+      env: { ...process.env, ATDD_VIOLATIONS_REPORT: rep },
+      stdio: ["ignore", "ignore", "inherit"],
+    });
+  } catch {
+    /* a member may exit non-zero; still try to read its report */
+  }
+  try {
+    out.push(...JSON.parse(readFileSync(rep, "utf8")).violations);
+  } catch {}
+}
+writeFileSync(reportPath, JSON.stringify({ violations: out }, null, 2), "utf8");
+process.stderr.write("family bun_interlocking_coverage: " + out.length + " violation(s)\n");
+process.exit(0);

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/e2e/interlockings/match-resolution/routes.test.ts

@@ -0,0 +1,21 @@
+// End-to-end route coverage — exercises EVERY admissible route through the production runners.
+import { InterlockingRunner } from "../../../convex/trains/interlocking";
+import { TrainRunner } from "../../../convex/trains/runner";
+
+function runner() {
+  return new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+}
+
+test("nominal-all-voted resolves the standard train", () => {
+  const resolution = runner().resolveTrain("resolve_match", { allPlayersVoted: true });
+  expect(resolution.routeId).toBe("nominal-all-voted");
+  expect(resolution.trainId).toBe("train:match:match-resolution-standard");
+  new TrainRunner(resolution.trainId).execute({});
+});
+
+test("alternate-timeout resolves the timeout train", () => {
+  const resolution = runner().resolveTrain("resolve_match", { timerExpired: true });
+  expect(resolution.routeId).toBe("alternate-timeout");
+  expect(resolution.trainId).toBe("train:match:match-resolution-timeout");
+  new TrainRunner(resolution.trainId).execute({});
+});

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/e2e/interlockings/match-resolution/trace.test.ts

@@ -0,0 +1,17 @@
+// Trace-binding e2e test — asserts EVERY required binding field, tying the run to its declaration.
+import { InterlockingRunner } from "../../../convex/trains/interlocking";
+import { TrainRunner } from "../../../convex/trains/runner";
+
+test("alternate-timeout trace binds the declared route", () => {
+  const runner = new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+  const resolution = runner.resolveTrain("resolve_match", { timerExpired: true });
+  const result: any = new TrainRunner(resolution.trainId).execute({});
+  const trace = result.trace;
+  expect(trace.interlockingId).toBe("interlocking:match-resolution");
+  expect(trace.routeId).toBe("alternate-timeout");
+  expect(trace.selectedTrainId).toBe("train:match:match-resolution-timeout");
+  expect(trace.routeCategory).toBe("alternate");
+  expect(trace.guardId).toBe("guard:timer-expires");
+  expect(trace.resolutionStrategy).toBe("fail_on_multiple_match");
+  expect(trace.resolutionReason).toBeTruthy();
+});

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/e2e/smoke/resolve-match.smoke.test.ts

@@ -0,0 +1,13 @@
+// Station Master smoke test for the exposed resolve_match action — drives the real entrypoint ->
+// Station Master -> InterlockingRunner -> TrainRunner path.
+import { StationMaster } from "../../convex/app";
+import { InterlockingRunner } from "../../convex/trains/interlocking";
+import { TrainRunner } from "../../convex/trains/runner";
+
+test("resolve_match smoke reaches the Station Master", () => {
+  const stationMaster = new StationMaster();
+  const result: any = stationMaster.handleAction("resolve_match", { allPlayersVoted: true });
+  expect(stationMaster.interlockingRunner).toBeInstanceOf(InterlockingRunner);
+  expect(stationMaster.trainRunner).toBeInstanceOf(TrainRunner);
+  expect(result.selectedTrainId).toBe("train:match:match-resolution-standard");
+});

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/plan/_trains/_interlockings/match-resolution.yaml

@@ -0,0 +1,51 @@
+# Interlocking route space (core afokapu/atdd#1248). Two admissible routes; each requires a covering
+# e2e test. entrypoint.exposed:true -> the resolve_match action requires a smoke test.
+schema_version: 1.0.0
+interlocking_id: interlocking:match-resolution
+title: Match resolution route interlocking
+status: checked
+
+entrypoint:
+  surfaces: [backend]
+  exposed: true
+  actions:
+    - resolve_match
+  reason: null
+
+route_resolution:
+  strategy: fail_on_multiple_match
+
+routes:
+  - route_id: nominal-all-voted
+    priority: 1
+    projection:
+      expected_sequence_digest: "d285d26427cb21fedb4c5b56edc673743f6d63c85686bdeb37f5e8c5ed4736d8"
+    category: nominal
+    guard_ref: guard:all-voted
+    train_id: train:match:match-resolution-standard
+    train_path: plan/_trains/train:match:match-resolution-standard.yaml
+  - route_id: alternate-timeout
+    priority: 2
+    projection:
+      expected_sequence_digest: "417c29734ac10c6a6c9a59dc3c568011aa9bdf4bc46e753f351657679d791672"
+    category: alternate
+    guard_ref: guard:timer-expires
+    train_id: train:match:match-resolution-timeout
+    train_path: plan/_trains/train:match:match-resolution-timeout.yaml
+
+theme: match-resolution
+lifelines:
+  - ref: user:actor
+  - ref: wagon:match-resolution
+messages:
+  - id: msg:match-resolution-request
+    kind: boundary
+    from: user:actor
+    to: wagon:match-resolution
+    intent: The actor requests Match Resolution
+    payload:
+      contract: match-resolution:request-v1
+
+source:
+  path: official/atdd.workspace.bun/implementations/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/plan/_trains/_interlockings/match-resolution.yaml
+  content_digest: "8bc1d15141bd8d3a33ffc144a4014f727eb6ee85ccf637ba0303c0750bad4999"

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_route_coverage/e2e/interlockings/match-resolution/routes.test.ts

@@ -0,0 +1,21 @@
+// End-to-end route coverage — exercises EVERY admissible route through the production runners.
+import { InterlockingRunner } from "../../../convex/trains/interlocking";
+import { TrainRunner } from "../../../convex/trains/runner";
+
+function runner() {
+  return new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+}
+
+test("nominal-all-voted resolves the standard train", () => {
+  const resolution = runner().resolveTrain("resolve_match", { allPlayersVoted: true });
+  expect(resolution.routeId).toBe("nominal-all-voted");
+  expect(resolution.trainId).toBe("train:match:match-resolution-standard");
+  new TrainRunner(resolution.trainId).execute({});
+});
+
+test("alternate-timeout resolves the timeout train", () => {
+  const resolution = runner().resolveTrain("resolve_match", { timerExpired: true });
+  expect(resolution.routeId).toBe("alternate-timeout");
+  expect(resolution.trainId).toBe("train:match:match-resolution-timeout");
+  new TrainRunner(resolution.trainId).execute({});
+});

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_route_coverage/e2e/interlockings/match-resolution/trace.test.ts

@@ -0,0 +1,17 @@
+// Trace-binding e2e test — asserts EVERY required binding field, tying the run to its declaration.
+import { InterlockingRunner } from "../../../convex/trains/interlocking";
+import { TrainRunner } from "../../../convex/trains/runner";
+
+test("alternate-timeout trace binds the declared route", () => {
+  const runner = new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+  const resolution = runner.resolveTrain("resolve_match", { timerExpired: true });
+  const result: any = new TrainRunner(resolution.trainId).execute({});
+  const trace = result.trace;
+  expect(trace.interlockingId).toBe("interlocking:match-resolution");
+  expect(trace.routeId).toBe("alternate-timeout");
+  expect(trace.selectedTrainId).toBe("train:match:match-resolution-timeout");
+  expect(trace.routeCategory).toBe("alternate");
+  expect(trace.guardId).toBe("guard:timer-expires");
+  expect(trace.resolutionStrategy).toBe("fail_on_multiple_match");
+  expect(trace.resolutionReason).toBeTruthy();
+});

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_route_coverage/e2e/smoke/resolve-match.smoke.test.ts

@@ -0,0 +1,13 @@
+// Station Master smoke test for the exposed resolve_match action — drives the real entrypoint ->
+// Station Master -> InterlockingRunner -> TrainRunner path.
+import { StationMaster } from "../../convex/app";
+import { InterlockingRunner } from "../../convex/trains/interlocking";
+import { TrainRunner } from "../../convex/trains/runner";
+
+test("resolve_match smoke reaches the Station Master", () => {
+  const stationMaster = new StationMaster();
+  const result: any = stationMaster.handleAction("resolve_match", { allPlayersVoted: true });
+  expect(stationMaster.interlockingRunner).toBeInstanceOf(InterlockingRunner);
+  expect(stationMaster.trainRunner).toBeInstanceOf(TrainRunner);
+  expect(result.selectedTrainId).toBe("train:match:match-resolution-standard");
+});