@afokapu/atdd-bun 0.10.54 → 0.10.56

package/detectors/bun_interlocking_binding/checks/interlocking_runtime_executes.mjs

@@ -29,6 +29,7 @@ export const RULE_EXECUTES = "coder.bun.runtime-executes-the-declaration";
 const LOADS_DECLARATION =
   /\breadFileSync\s*\(|\breadFile\s*\(|\bBun\s*\.\s*file\s*\(|\bcreateReadStream\s*\(|\bfs\s*\.\s*promises\s*\.\s*readFile\b/;
 const RESOLVES = /\bInterlockingResolution\b|\bresolveTrain\s*\(/;
+const TRAIN_RUNNER = /\bclass\s+TrainRunner\b/;
 const EXCLUDES = ["node_modules", "dist", "build", ".next", "_generated"];
 const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
 
@@ -159,10 +160,54 @@ export function scanExecution(scanRoot) {
   return violations;
 }
 
+// TrainRunner is the other half of declaration execution. A correctly data-driven
+// InterlockingRunner can select a train while its executor silently ignores that
+// train and returns a hand-written trace. Require the executor itself to read a
+// supplied train declaration, iterate its declared sequence, and feed each wagon's
+// production result into the next call. These deliberately structural checks admit
+// ordinary direct functions (executeWagon/runWagon/runTrain) without prescribing a
+// framework, while rejecting the no-op and literal-trace shapes they replace.
+export function scanTrainRunnerExecution(scanRoot) {
+  const violations = [];
+  for (const croot of findConsumerRoots(scanRoot)) {
+    const trainDeclarations = walk(join(croot, PLAN_ROOT, "_trains"), (f) => /train:.*\.ya?ml$/.test(f));
+    if (!trainDeclarations.length) continue;
+    const rtFiles = walk(join(croot, "src/trains"), (f) => /\.(ts|tsx|mjs|js)$/.test(f))
+      .map((f) => ({ file: f, text: readText(f) }));
+    for (const runner of rtFiles.filter((x) => TRAIN_RUNNER.test(x.text))) {
+      const readsDeclaration = LOADS_DECLARATION.test(runner.text);
+      const usesSuppliedDeclaration = /\b(?:parse|load)(?:Train|Declaration)\s*\(\s*this\.\w*(?:train|declaration|path)\w*\s*\)/i.test(runner.text) ||
+        /\b(?:readFileSync|readFile|Bun\s*\.\s*file)\s*\(\s*this\.\w*(?:train|declaration|path)\w*/i.test(runner.text);
+      const parsesSequence = /\bsequence\b/.test(runner.text);
+      const derivesOrder = /for\s*\(\s*const\s+\w+\s+of\s+\w+\.sequence\s*\)/.test(runner.text);
+      // The reassignment is the key data-flow proof: a production execution call
+      // receives the prior result and its output becomes the next result.
+      const carriesResults = /\b(\w+)\s*=\s*(?:await\s+)?(?:execute|run)\w*\s*\(\s*\w+\s*,\s*\1\s*\)/.test(runner.text);
+      const fabricatesTrace = /\b(?:trace|steps?|sequence)\s*:\s*\[\s*["'`]/.test(maskComments(runner.text));
+      if (readsDeclaration && usesSuppliedDeclaration && parsesSequence && derivesOrder && carriesResults && !fabricatesTrace) continue;
+      const missing = [
+        !readsDeclaration && "read the supplied train declaration",
+        !usesSuppliedDeclaration && "pass its supplied declaration into that parser or reader",
+        !parsesSequence && "parse its sequence",
+        !derivesOrder && "derive ordered iteration from train.sequence",
+        !carriesResults && "carry each production execution result into the next wagon",
+        fabricatesTrace && "avoid fabricating literal trace or step data",
+      ].filter(Boolean).join("; ");
+      const rel = runner.file.startsWith(croot + sep) ? runner.file.slice(croot.length + 1) : runner.file;
+      violations.push({
+        rule_id: RULE_EXECUTES, file: rel, line: 1, col: 0,
+        evidence: `TrainRunner must ${missing}; declaration-selected wagon execution cannot be satisfied by a no-op or transcribed trace`,
+        source_line: "",
+      });
+    }
+  }
+  return violations;
+}
+
 if (import.meta.main ?? process.argv[1]?.endsWith("interlocking_runtime_executes.mjs")) {
   let roots = [];
   try { roots = JSON.parse(process.env.ATDD_SCAN_ROOTS || "[]"); } catch {}
-  const out = roots.flatMap((r) => scanExecution(r));
+  const out = roots.flatMap((r) => [...scanExecution(r), ...scanTrainRunnerExecution(r)]);
   const rp = process.env.ATDD_VIOLATIONS_REPORT;
   if (rp) writeFileSync(rp, JSON.stringify({ violations: out }, null, 2), "utf8");
   process.stderr.write(`bun-executes: ${out.length} violation(s)\n`);

package/detectors/bun_interlocking_binding/detect.mjs

@@ -24,7 +24,7 @@
 import { excludedPath } from "../../lib/scan.mjs";
 import { parseInterlocking as parseInterlockingDoc } from "../../lib/interlocking.mjs";
 import { readFileSync, writeFileSync, statSync, readdirSync } from "node:fs";
-import { scanExecution } from "./checks/interlocking_runtime_executes.mjs";
+import { scanExecution, scanTrainRunnerExecution } from "./checks/interlocking_runtime_executes.mjs";
 import { join, sep, resolve } from "node:path";
 
 const RULE = "coder.bun.interlocking-bilateral-binding";
@@ -544,7 +544,7 @@ function main() {
     // coder.bun.runtime-executes-the-declaration — no longer staged. This family is
     // monolithic rather than checks/-collecting, so it is called here rather than
     // discovered.
-    violations.push(...scanExecution(scanRoot));
+    violations.push(...scanExecution(scanRoot), ...scanTrainRunnerExecution(scanRoot));
   }
   writeFileSync(reportPath, JSON.stringify({ violations }, null, 2), "utf8");
   process.stderr.write(`bun-interlocking-binding: ${violations.length} violation(s)\n`);

package/detectors/bun_interlocking_binding/fixtures/clean/server.ts

@@ -12,8 +12,8 @@ export const JOURNEY_MAP = {
 
 export function dispatch(action: string, inputs: Record<string, unknown>) {
   const mapping = (JOURNEY_MAP as Record<string, unknown>)[action];
-  if (typeof mapping === "string") return new TrainRunner(mapping).execute(inputs);
+  if (typeof mapping === "string") return new TrainRunner(`plan/_trains/${mapping}.yaml`, mapping).execute(inputs);
   const { path } = mapping as { interlockingId: string; path: string };
   const res = new InterlockingRunner(path).resolveTrain(action, inputs);
-  return new TrainRunner(res.trainId).execute(inputs);
+  return new TrainRunner(res.trainPath, res.trainId).execute(inputs);
 }

package/detectors/bun_interlocking_binding/fixtures/clean/src/trains/runner.ts

@@ -1,7 +1,25 @@
-// TrainRunner — the production linear executor the InterlockingRunner delegates to.
+// TrainRunner — reads the selected train declaration and executes its declared wagons in order.
+import { readFileSync } from "node:fs";
+
+type Result = Record<string, unknown>;
+
+function parseTrain(path: string): { sequence: string[] } {
+  const text = readFileSync(path, "utf8");
+  return { sequence: [...text.matchAll(/^\s*-\s*([^#\s]+)\s*$/gm)].map((match) => match[1]) };
+}
+
+function executeWagon(wagon: string, result: Result): Result {
+  return { ...result, [wagon]: "executed" };
+}
+
 export class TrainRunner {
-  constructor(private readonly trainId: string) {}
+  constructor(private readonly trainDeclarationPath: string, private readonly trainId?: string) {}
   execute(inputs: Record<string, unknown>) {
-    return { selectedTrainId: this.trainId, inputs };
+    const train = parseTrain(this.trainDeclarationPath);
+    let result: Result = inputs;
+    for (const wagon of train.sequence) {
+      result = executeWagon(wagon, result);
+    }
+    return { selectedTrainId: this.trainId, result };
   }
 }

package/detectors/bun_interlocking_binding/fixtures/clean_flow_style_actions/server.ts

@@ -12,8 +12,8 @@ export const JOURNEY_MAP = {
 
 export function dispatch(action: string, inputs: Record<string, unknown>) {
   const mapping = (JOURNEY_MAP as Record<string, unknown>)[action];
-  if (typeof mapping === "string") return new TrainRunner(mapping).execute(inputs);
+  if (typeof mapping === "string") return new TrainRunner(`plan/_trains/${mapping}.yaml`, mapping).execute(inputs);
   const { path } = mapping as { interlockingId: string; path: string };
   const res = new InterlockingRunner(path).resolveTrain(action, inputs);
-  return new TrainRunner(res.trainId).execute(inputs);
+  return new TrainRunner(res.trainPath, res.trainId).execute(inputs);
 }

package/detectors/bun_interlocking_binding/fixtures/clean_flow_style_actions/src/trains/runner.ts

@@ -1,7 +1,25 @@
-// TrainRunner — the production linear executor the InterlockingRunner delegates to.
+// TrainRunner — reads the selected train declaration and executes its declared wagons in order.
+import { readFileSync } from "node:fs";
+
+type Result = Record<string, unknown>;
+
+function parseTrain(path: string): { sequence: string[] } {
+  const text = readFileSync(path, "utf8");
+  return { sequence: [...text.matchAll(/^\s*-\s*([^#\s]+)\s*$/gm)].map((match) => match[1]) };
+}
+
+function executeWagon(wagon: string, result: Result): Result {
+  return { ...result, [wagon]: "executed" };
+}
+
 export class TrainRunner {
-  constructor(private readonly trainId: string) {}
+  constructor(private readonly trainDeclarationPath: string, private readonly trainId?: string) {}
   execute(inputs: Record<string, unknown>) {
-    return { selectedTrainId: this.trainId, inputs };
+    const train = parseTrain(this.trainDeclarationPath);
+    let result: Result = inputs;
+    for (const wagon of train.sequence) {
+      result = executeWagon(wagon, result);
+    }
+    return { selectedTrainId: this.trainId, result };
   }
 }

package/detectors/bun_interlocking_coverage/_shared/interlocking.mjs

@@ -7,8 +7,8 @@
 // data (snake_case, plan/_trains/_interlockings/**); the e2e tests are Bun/TS under e2e/**.
 
 import { excludedPath } from "../../../lib/scan.mjs";
-import { readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
-import { join, sep } from "node:path";
+import { existsSync, readFileSync, statSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
 
 export const DEFAULT_EXCLUDES = ["_generated", "node_modules", "dist", "build", ".next"];
 export const PLAN_ROOT = process.env.ATDD_PLAN_ROOT || "plan";
@@ -315,6 +315,185 @@ export function isInterlockingTest(text, tokens) {
   return tokens.some((t) => tokenCovered(t, text));
 }
 
+// Semantic witnesses for the production call model.  Tokens get us to a candidate test; these
+// small, deliberately conservative recognisers decide whether the candidate actually connects
+// `InterlockingRunner.resolveTrain()` to `TrainRunner.execute()` and asserts evidence from that
+// chain.  We keep this in the shared layer so route, runner, trace, smoke, and sequence checks
+// cannot quietly drift back to accepting a different descriptive proxy.
+const ident = "[A-Za-z_$][\\w$]*";
+
+function escaped(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function productionReceivers(text) {
+  const out = new Set();
+  const allocated = new RegExp(`\\b(?:const|let|var)\\s+(${ident})\\s*=\\s*new\\s+${PROD_INTERLOCKING}\\b`, "g");
+  for (const m of text.matchAll(allocated)) out.add(m[1]);
+  const factories = new RegExp(`\\bfunction\\s+(${ident})\\s*\\([^)]*\\)\\s*\\{[\\s\\S]{0,600}?\\breturn\\s+new\\s+${PROD_INTERLOCKING}\\b`, "g");
+  for (const m of text.matchAll(factories)) out.add(`${m[1]}()`);
+  return out;
+}
+
+// [{ resolution, execution }] means an actual resolution value feeds actual train execution.
+// `execution` is null for an unassigned execute result; route/runner proof may assert resolution,
+// while trace and sequence proof require the named execution result.
+export function hasResolvedProductionRunnerImports(text, file, croot) {
+  const imported = new Set();
+  const re = /^\s*import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/gm;
+  for (const match of text.matchAll(re)) {
+    if (!match[2].startsWith(".")) continue;
+    const names = match[1].split(",").map(name => name.trim().split(/\s+as\s+/)[0]);
+    const target = resolve(dirname(file), match[2]);
+    const candidates = [target, `${target}.ts`, `${target}.tsx`, `${target}.js`, `${target}.mjs`, join(target, "index.ts")];
+    const source = candidates.find(candidate => existsSync(candidate) && candidate.startsWith(resolve(croot) + sep) && !/\.(test|spec)\.[cm]?[jt]sx?$/.test(candidate));
+    if (!source) continue;
+    for (const name of names) if (name === PROD_INTERLOCKING || name === PROD_TRAIN) imported.add(name);
+  }
+  return imported.has(PROD_INTERLOCKING) && imported.has(PROD_TRAIN);
+}
+
+export function productionExecutionProofs(text, file, croot) {
+  if (file && croot && !hasResolvedProductionRunnerImports(text, file, croot)) return [];
+  const receivers = productionReceivers(text);
+  const proofs = [];
+  const resolutions = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*([^\\n]{0,240}?)\\.resolveTrain\\s*\\(`, "g");
+  for (const m of text.matchAll(resolutions)) {
+    const [whole, resolution, receiver] = m;
+    const direct = new RegExp(`new\\s+${PROD_INTERLOCKING}\\b`).test(receiver);
+    const named = [...receivers].some((name) => receiver.trim().endsWith(name));
+    if (!direct && !named) continue;
+    const after = text.slice((m.index ?? 0) + whole.length);
+    const execute = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).exec(after);
+    const anonymous = new RegExp(`new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).test(after);
+    if (execute || anonymous) proofs.push({ resolution, execution: execute?.[1] ?? null });
+  }
+  return proofs;
+}
+
+export function assertsExpression(text, expression, expected = null) {
+  const pat = new RegExp(`\\bexpect\\s*\\(\\s*(?:await\\s+)?${expression}\\s*\\)\\s*\\.(?:to(?:Be|BeDefined|Equal|StrictEqual|Contain|ContainEqual|Match|BeTruthy)|not\\.to(?:Be|BeDefined|Equal|StrictEqual|Contain|ContainEqual|Match))\\b([\\s\\S]{0,220})`);
+  const m = pat.exec(text);
+  return Boolean(m && (!expected || tokenCovered(expected, m[0])));
+}
+
+export function hasProductionExecutionProof(text, file, croot) {
+  return productionExecutionProofs(text, file, croot).some(({ resolution, execution }) => {
+    if (assertsExpression(text, `${escaped(resolution)}\\.(?:routeId|trainId|selectedTrainId)`) ||
+      (execution && assertsExpression(text, escaped(execution)))) return true;
+    if (!execution) return false;
+    const trace = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${escaped(execution)}\\.trace\\b`).exec(text)?.[1];
+    return Boolean(trace && REQUIRED_TRACE_FIELDS.some(([field]) => assertsExpression(text, `${escaped(trace)}\\.${field}`)));
+  });
+}
+
+export function routeHasProductionProof(route, text, interlockingId = null, file, croot) {
+  const slug = interlockingId?.replace(/^interlocking:/, "");
+  return productionExecutionProofs(text, file, croot).some(({ resolution, execution }) => {
+    const assertedRoute = assertsExpression(text, `${escaped(resolution)}\\.routeId`, route.routeId);
+    const assertedTrain = assertsExpression(text, `${escaped(resolution)}\\.(?:trainId|selectedTrainId)`, route.trainId);
+    const scoped = !interlockingId || tokenCovered(interlockingId, text) || tokenCovered(slug, text);
+    return (assertedRoute && scoped) || assertedTrain || Boolean(scoped && execution && assertsExpression(text, escaped(execution)) && (tokenCovered(route.routeId, text) || tokenCovered(route.trainId, text)));
+  });
+}
+
+export function traceHasProductionProvenance(text, file, croot) {
+  return productionExecutionProofs(text, file, croot).some(({ execution }) => {
+    if (!execution) return false;
+    const trace = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${escaped(execution)}\\.trace\\b`).exec(text)?.[1];
+    return Boolean(trace);
+  });
+}
+
+export function assertedTraceFields(text, traceName = "trace") {
+  return REQUIRED_TRACE_FIELDS.filter(([field]) => !assertsExpression(text, `${escaped(traceName)}\\.${field}`)).map(([field]) => field);
+}
+
+// A smoke path has a real Station Master call and observes that call's returned value; separately
+// requiring both production runner instances rules out imports used only as lexical decoration.
+export function stationMasterExecutionProof(text, action) {
+  const call = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?${ident}\\.(?:handleAction|dispatch|executeAction)\\s*\\(\\s*["']${escaped(action)}["']`).exec(text);
+  if (!call) return false;
+  const result = call[1];
+  const instanceProof = new RegExp(`\\bexpect\\s*\\(\\s*${ident}\\.(?:interlockingRunner|trainRunner)\\s*\\)\\s*\\.toBeInstanceOf\\s*\\(\\s*(?:${PROD_INTERLOCKING}|${PROD_TRAIN})\\s*\\)`, "g");
+  const seen = new Set([...text.matchAll(instanceProof)].map((m) => m[0].includes(PROD_INTERLOCKING) ? PROD_INTERLOCKING : PROD_TRAIN));
+  return seen.has(PROD_INTERLOCKING) && seen.has(PROD_TRAIN) && assertsExpression(text, `${escaped(result)}(?:\\.[A-Za-z_$][\\w$]*)?`);
+}
+
+function balancedBlock(text, open) {
+  let depth = 0, quote = null;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i], next = text[i + 1];
+    if (quote) {
+      if (c === "\\") { i++; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === "`") { quote = c; continue; }
+    if (c === "/" && next === "/") { i = text.indexOf("\n", i + 2); if (i < 0) return null; continue; }
+    if (c === "/" && next === "*") { const end = text.indexOf("*/", i + 2); if (end < 0) return null; i = end + 1; continue; }
+    if (c === "{") depth++;
+    if (c === "}" && --depth === 0) return text.slice(open + 1, i);
+  }
+  return null;
+}
+
+function exportedActionBody(text, name) {
+  const n = escaped(name);
+  const headers = [
+    new RegExp(`\\bexport\\s+(?:async\\s+)?function\\s+${n}\\s*\\([^)]*\\)\\s*\\{`, "g"),
+    new RegExp(`\\bexport\\s+(?:const|let|var)\\s+${n}\\s*=\\s*(?:async\\s*)?\\([^)]*\\)\\s*=>\\s*\\{`, "g"),
+  ];
+  for (const header of headers) {
+    const match = header.exec(text);
+    if (match) return balancedBlock(text, (match.index ?? 0) + match[0].lastIndexOf("{"));
+  }
+  return null;
+}
+
+function exportedActionReturnsProductionExecution(stationText, action) {
+  const body = exportedActionBody(stationText, action);
+  if (!body) return false;
+  const receivers = productionReceivers(stationText);
+  const resolutions = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*([^\\n]{0,240}?)\\.resolveTrain\\s*\\(`, "g");
+  for (const m of body.matchAll(resolutions)) {
+    const [whole, resolution, receiver] = m;
+    const direct = new RegExp(`new\\s+${PROD_INTERLOCKING}\\b`).test(receiver);
+    const named = [...receivers].some((name) => receiver.trim().endsWith(name));
+    if (!direct && !named) continue;
+    const after = body.slice((m.index ?? 0) + whole.length);
+    const directReturn = new RegExp(`\\breturn\\s+(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).test(after);
+    if (directReturn) return true;
+    const execution = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*(?:await\\s+)?new\\s+${PROD_TRAIN}\\s*\\(\\s*${escaped(resolution)}\\.(?:trainId|selectedTrainId)\\s*\\)\\s*\\.execute\\s*\\(`).exec(after)?.[1];
+    if (execution && new RegExp(`\\breturn\\s+(?:await\\s+)?${escaped(execution)}\\s*;?`).test(after)) return true;
+  }
+  return false;
+}
+
+// HTTP/module entrypoints do not expose a StationMaster instance to the test. The asserted result
+// must therefore come from the SAME exported action the test invokes, and that action's own return
+// path must resolve then execute the selected train. Module-wide runner tokens are not evidence.
+export function stationModuleExecutionProof(text, stationText, action) {
+  if (!stationText) return false;
+  const call = new RegExp(`\\b(?:const|let|var)\\s+(${ident})(?:\\s*:\\s*[^=;\\n]+)?\\s*=\\s*await\\s+(?:${ident}\\.)?(dispatch|handleAction|executeAction)\\s*\\(\\s*["']${escaped(action)}["']`).exec(text);
+  return Boolean(call && assertsExpression(text, `${escaped(call[1])}(?:\\.[A-Za-z_$][\\w$]*)?`) &&
+    exportedActionReturnsProductionExecution(stationText, call[2]));
+}
+
+// Bun's native `expect` vocabulary provides a compact mutation witness: exact ordered equality
+// kills reorder/removal mutants, objectContaining records a handoff edge, and at(-1) observes the
+// final wagon.  All three must be about the TrainRunner result, never a hand-built literal.
+export function hasSequenceMutationProof(text, trainId, file, croot) {
+  return productionExecutionProofs(text, file, croot).some(({ resolution, execution }) => {
+    if (!execution || !assertsExpression(text, `${escaped(resolution)}\\.(?:trainId|selectedTrainId)`, trainId)) return false;
+    const result = escaped(execution);
+    const ordered = new RegExp(`expect\\s*\\(\\s*${result}\\.(?:steps|sequence|wagons)\\s*\\)\\s*\\.to(?:Equal|StrictEqual)\\s*\\(\\s*\\[`, "s").test(text);
+    const handoff = new RegExp(`expect\\s*\\(\\s*${result}\\.(?:steps|sequence|wagons)\\s*\\)\\s*\\.toContainEqual\\s*\\(\\s*expect\\.objectContaining\\s*\\(\\s*\\{[\\s\\S]{0,240}?(?:from|to)\\s*:`, "s").test(text);
+    const finalWagon = new RegExp(`expect\\s*\\(\\s*${result}\\.(?:steps|sequence|wagons)\\s*\\.at\\(\\s*-1\\s*\\)\\s*\\)\\s*\\.to(?:Be|Equal|StrictEqual|Match)`, "s").test(text);
+    return ordered && handoff && finalWagon;
+  });
+}
+
 export function writeReport(violations) {
   const rp = process.env.ATDD_VIOLATIONS_REPORT;
   if (!rp) {

package/detectors/bun_interlocking_coverage/checks/interlocking_production_runner.mjs

@@ -22,6 +22,9 @@ import {
   PROD_INTERLOCKING,
   PROD_TRAIN,
   FORBIDDEN_PATTERNS,
+  hasProductionExecutionProof,
+  stationMasterExecutionProof,
+  stationModuleExecutionProof,
   rel,
   mk,
   writeReport,
@@ -67,16 +70,18 @@ for (const scanRoot of roots) {
         }
       }
 
-      const missing = drivesStationMaster(text) ? [] : [PROD_INTERLOCKING, PROD_TRAIN].filter((sym) => !tokenCovered(sym, text));
-      if (missing.length) {
+      const semantic = hasProductionExecutionProof(text, file, croot) ||
+        records.some((rec) => rec.actions.some((action) => stationMasterExecutionProof(text, action))) ||
+        (drivesStationMaster(text) && records.some((rec) => rec.actions.some((action) => stationModuleExecutionProof(text, station, action))));
+      if (!semantic) {
         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)`,
+            `interlocking test "${r}" has no asserted result flowing from production InterlockingRunner ` +
+              `resolution into TrainRunner execution; imports and route/train literals are discovery only`,
             "",
           ),
         );

package/detectors/bun_interlocking_coverage/checks/interlocking_route_coverage.mjs

@@ -13,7 +13,7 @@ import {
   interlockingFiles,
   e2eFiles,
   parseInterlocking,
-  isRouteCovered,
+  routeHasProductionProof,
   maskComments,
   rel,
   mk,
@@ -30,11 +30,11 @@ for (const scanRoot of roots) {
     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)));
+    const e2eTexts = e2eFiles(croot).map((file) => ({ file, text: maskComments(readText(file)) }));
 
     for (const { file, rec } of records) {
       for (const route of rec.routes) {
-        if (isRouteCovered(route, e2eTexts, rec.interlockingId)) continue;
+        if (e2eTexts.some(({ file, text }) => routeHasProductionProof(route, text, rec.interlockingId, file, croot))) continue;
         if (unbuiltWagons(croot, route.trainId).length) continue;   // pending: a wagon on its train has no source yet
         const cat =
           route.category !== null
@@ -48,7 +48,7 @@ for (const scanRoot of roots) {
             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`,
+              `test whose asserted resolution selects this route/train and flows through InterlockingRunner -> TrainRunner`,
             route.sourceLine.trim(),
           ),
         );

package/detectors/bun_interlocking_coverage/checks/interlocking_smoke_coverage.mjs

@@ -20,10 +20,13 @@ import {
   STATION_MASTER,
   PROD_INTERLOCKING,
   PROD_TRAIN,
+  stationMasterExecutionProof,
+  stationModuleExecutionProof,
   rel,
   mk,
   writeReport,
 } from "../_shared/interlocking.mjs";
+import { join } from "node:path";
 
 const RULE = "tester.bun.interlocking-smoke-coverage-for-station-master";
 const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
@@ -33,10 +36,11 @@ const violations = [];
 // it under the smoke rules (no substituted collaborators, observable outcome). A local E2E that names the action beside
 // the runners is not a smoke and no longer clears the rule (FWS #TzSCGS5ajYhP).
 const SMOKE_PHASE = /^\s*\/\/\s*Phase:\s*SMOKE\b/m;
-function actionSmokeCovered(action, e2eFiles) {
+function actionSmokeCovered(action, e2eFiles, stationModule) {
   return e2eFiles.some(
     ({ raw, text: t }) =>
-      SMOKE_PHASE.test(raw) && tokenCovered(action, t) && STATION_MASTER.test(t) && t.includes(PROD_INTERLOCKING) && t.includes(PROD_TRAIN),
+      SMOKE_PHASE.test(raw) && tokenCovered(action, t) && STATION_MASTER.test(t) && t.includes(PROD_INTERLOCKING) && t.includes(PROD_TRAIN) &&
+        (stationMasterExecutionProof(t, action) || stationModuleExecutionProof(t, stationModule, action)),
   );
 }
 
@@ -46,11 +50,14 @@ for (const scanRoot of roots) {
       .map((f) => ({ file: f, rec: parseInterlocking(readText(f)) }))
       .filter((x) => x.rec);
     const e2eTexts = e2eFiles(croot).map((f) => { const raw = readText(f); return { raw, text: maskComments(raw) }; });
+    const stationModule = ["server.ts", join("src", "server.ts")]
+      .map((name) => readText(join(croot, name)))
+      .find((text) => text && text.includes(PROD_INTERLOCKING) && text.includes(PROD_TRAIN));
 
     for (const { file, rec } of records) {
       if (!rec.exposed) continue;
       for (const action of rec.actions) {
-        if (actionSmokeCovered(action, e2eTexts)) continue;
+        if (actionSmokeCovered(action, e2eTexts, stationModule)) continue;
         const [line, src] = lineOf(rec.rawText, new RegExp("^\\s*-\\s*['\"]?" + action + "['\"]?\\s*$"));
         violations.push(
           mk(

package/detectors/bun_interlocking_coverage/checks/interlocking_trace_binds.mjs

@@ -20,6 +20,8 @@ import {
   lineAt,
   TRACE_OBJECT,
   REQUIRED_TRACE_FIELDS,
+  assertedTraceFields,
+  traceHasProductionProvenance,
   rel,
   mk,
   writeReport,
@@ -42,8 +44,9 @@ for (const scanRoot of roots) {
       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 missing = assertedTraceFields(text);
+      const provenance = traceHasProductionProvenance(text, file, croot);
+      if (!missing.length && provenance) continue;
       const line = lineOfIndex(text, m.index);
       violations.push(
         mk(
@@ -51,9 +54,8 @@ for (const scanRoot of roots) {
           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)`,
+          `interlocking trace test "${rel(file, croot)}" does not bind a production TrainRunner result to the ` +
+            `declared route${missing.length ? `: missing asserted trace field(s) ${missing.join(", ")}` : ""}${!provenance ? "; trace is not derived from InterlockingRunner -> TrainRunner execution" : ""}`,
           lineAt(raw, line),
         ),
       );

package/detectors/bun_interlocking_coverage/checks/interlocking_train_sequence.mjs

@@ -16,22 +16,17 @@
 // suite green. The runtime obeyed the new plan; no test looked.
 import {
   parseJsonEnv, readText, findConsumerRoots, interlockingFiles, e2eFiles,
-  parseInterlocking, tokenCovered, rel, mk, PLAN_ROOT, unbuiltWagons,
+  parseInterlocking, rel, mk, PLAN_ROOT, unbuiltWagons, hasSequenceMutationProof,
 } 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);
+  // Retained as a narrow API for consumers of this module. The train id is intentionally
+  // unavailable here, so it cannot certify coverage; `trainSequenceCovered` below does.
+  return /\bexpect\s*\(\s*[A-Za-z_$][\w$]*\.(?:steps|sequence|wagons)\s*\)\s*\.to(?:Equal|StrictEqual)\s*\(/.test(text);
 }
 
 export function trainsReachableFromRoutes(records) {
@@ -45,8 +40,8 @@ export function trainsReachableFromRoutes(records) {
   return out;
 }
 
-export function trainSequenceCovered(trainId, texts) {
-  return texts.some((t) => tokenCovered(trainId, t) && assertsASequence(t));
+export function trainSequenceCovered(trainId, files, croot) {
+  return files.some(({ file, text }) => hasSequenceMutationProof(text, trainId, file, croot));
 }
 
 // Does the plan actually DECLARE a wagon sequence for this train?
@@ -85,13 +80,13 @@ export function scanExecution(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);
+
     for (const trainId of [...trainsReachableFromRoutes(records)].sort()) {
       // The finding points at the train's own document, where the sequence a test must assert is declared (FWS #fqUGvWHn25mq).
       const declared = declaresASequence(croot, trainId);
       if (!declared) continue;   // nothing declared to exercise
       if (unbuiltWagons(croot, trainId).length) continue;   // pending: a wagon on it has no source yet
-      if (trainSequenceCovered(trainId, texts)) continue;
+      if (trainSequenceCovered(trainId, files, croot)) continue;
       violations.push(
         mk(RULE_SEQUENCE, rel(declared, croot), 1, 0,
           `declared train "${trainId}" is selected by a route but no test asserts the wagon ` +

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/convex/trains/interlocking.ts

@@ -0,0 +1 @@
+export class InterlockingRunner { resolveTrain() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_production_runner/convex/trains/runner.ts

@@ -0,0 +1 @@
+export class TrainRunner { execute() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_route_coverage/convex/trains/interlocking.ts

@@ -0,0 +1 @@
+export class InterlockingRunner { resolveTrain() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_route_coverage/convex/trains/runner.ts

@@ -0,0 +1 @@
+export class TrainRunner { execute() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_smoke_coverage/convex/trains/interlocking.ts

@@ -0,0 +1 @@
+export class InterlockingRunner { resolveTrain() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_smoke_coverage/convex/trains/runner.ts

@@ -0,0 +1 @@
+export class TrainRunner { execute() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_smoke_coverage_module/convex/trains/interlocking.ts

@@ -0,0 +1 @@
+export class InterlockingRunner { resolveTrain() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_smoke_coverage_module/convex/trains/runner.ts

@@ -0,0 +1 @@
+export class TrainRunner { execute() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_trace_binds/convex/trains/interlocking.ts

@@ -0,0 +1 @@
+export class InterlockingRunner { resolveTrain() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/clean/interlocking_trace_binds/convex/trains/runner.ts

@@ -0,0 +1 @@
+export class TrainRunner { execute() { return {}; } }

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/e2e/smoke/resolve-match.smoke.test.ts

@@ -0,0 +1,12 @@
+// Phase: SMOKE
+import { expect, test } from "bun:test";
+import { dispatch } from "../../src/server";
+import { InterlockingRunner } from "../../src/trains/interlocking";
+import { TrainRunner } from "../../src/trains/runner";
+
+test("inert runner helper does not prove functional Station Master dispatch", async () => {
+  const result = await dispatch("resolve_match", { allPlayersVoted: true });
+  expect(result.selectedTrainId).toBe("train:match:match-resolution-standard");
+  expect(InterlockingRunner).toBeDefined();
+  expect(TrainRunner).toBeDefined();
+});

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/plan/_trains/_interlockings/match-resolution.yaml

@@ -0,0 +1,8 @@
+interlocking_id: interlocking:match-resolution
+entrypoint:
+  exposed: true
+  actions:
+    - resolve_match
+routes:
+  - route_id: nominal-all-voted
+    train_id: train:match:match-resolution-standard

package/detectors/bun_interlocking_coverage/fixtures/dirty/interlocking_smoke_coverage_inert_module/src/server.ts

@@ -0,0 +1,13 @@
+import { InterlockingRunner } from "./trains/interlocking";
+import { TrainRunner } from "./trains/runner";
+
+const runner = new InterlockingRunner("plan/_trains/_interlockings/match-resolution.yaml");
+
+async function inertProductionHelper(action: string, inputs: object) {
+  const resolution = runner.resolveTrain(action, inputs);
+  return await new TrainRunner(resolution.trainId).execute({});
+}
+
+export async function dispatch(_action: string, _inputs: object) {
+  return { selectedTrainId: "train:match:match-resolution-standard" };
+}