@afokapu/atdd-bun 0.10.57 → 0.10.59

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_journeys/create-world-pack.yaml

@@ -0,0 +1,18 @@
+schema_version: 1.0.0
+journey_id: journey:create-world-pack
+title: Create World Pack
+status: draft
+entrypoint:
+  interlocking_id: interlocking:source-corpus-admission
+  exposed: true
+  actions:
+  - create_world
+  reason: null
+  surfaces:
+  - backend
+continuations: []
+terminals:
+- from:
+    interlocking_id: interlocking:source-corpus-admission
+    route_id: refuse
+  outcome: unsupported source refused

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_journeys/play-world-scenario.yaml

@@ -0,0 +1,24 @@
+schema_version: 1.0.0
+journey_id: journey:play-world-scenario
+title: Play World Scenario
+status: draft
+entrypoint:
+  interlocking_id: interlocking:scenario-compilation
+  exposed: true
+  actions:
+  - create_scenario
+  reason: null
+  surfaces:
+  - backend
+continuations:
+- from:
+    interlocking_id: interlocking:scenario-compilation
+    route_id: compile
+  artifact: world:scenario:package
+  to:
+    interlocking_id: interlocking:play-turn-routing
+terminals:
+- from:
+    interlocking_id: interlocking:scenario-compilation
+    route_id: refuse
+  outcome: invalid Scenario refused

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_journeys/replay-world-session.yaml

@@ -0,0 +1,18 @@
+schema_version: 1.0.0
+journey_id: journey:replay-world-session
+title: Replay World Session
+status: draft
+entrypoint:
+  interlocking_id: interlocking:session-replay
+  exposed: true
+  actions:
+  - replay_session
+  reason: null
+  surfaces:
+  - backend
+continuations: []
+terminals:
+- from:
+    interlocking_id: interlocking:session-replay
+    route_id: replay
+  outcome: recorded session replayed

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_trains/_interlockings/scenario-compilation.yaml

@@ -0,0 +1,14 @@
+interlocking_id: interlocking:scenario-compilation
+entrypoint:
+  exposed: true
+  actions:
+    - create_scenario
+route_resolution:
+  strategy: fail_on_multiple_match
+routes:
+  - route_id: compile
+    train_id: train:scenario:compile
+    train_path: plan/_trains/train:scenario:compile.yaml
+    guard:
+      id: guard:compile
+      input: scenario

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_trains/_interlockings/session-replay.yaml

@@ -0,0 +1,14 @@
+interlocking_id: interlocking:session-replay
+entrypoint:
+  exposed: true
+  actions:
+    - replay_session
+route_resolution:
+  strategy: fail_on_multiple_match
+routes:
+  - route_id: replay
+    train_id: train:session:replay
+    train_path: plan/_trains/train:session:replay.yaml
+    guard:
+      id: guard:replay
+      input: replay

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/plan/_trains/_interlockings/source-corpus-admission.yaml

@@ -0,0 +1,14 @@
+interlocking_id: interlocking:source-corpus-admission
+entrypoint:
+  exposed: true
+  actions:
+    - create_world
+route_resolution:
+  strategy: fail_on_multiple_match
+routes:
+  - route_id: refuse
+    train_id: train:source:refuse
+    train_path: plan/_trains/train:source:refuse.yaml
+    guard:
+      id: guard:refuse
+      input: source

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/src/server.ts

@@ -0,0 +1,85 @@
+import { JourneyRunner } from "./trains/journey.ts";
+import { UnavailableWagonError, type WagonHandlerRegistry } from "./trains/runner.ts";
+
+type StationRoute = Readonly<{ journeyId: string; path: string; interlockingId: string }>;
+
+export const JOURNEY_MAP: Readonly<Record<string, StationRoute>> = {
+  create_world: {
+    journeyId: "journey:create-world-pack",
+    path: "plan/_journeys/create-world-pack.yaml",
+    interlockingId: "interlocking:source-corpus-admission",
+  },
+  create_scenario: {
+    journeyId: "journey:play-world-scenario",
+    path: "plan/_journeys/play-world-scenario.yaml",
+    interlockingId: "interlocking:scenario-compilation",
+  },
+  replay_session: {
+    journeyId: "journey:replay-world-session",
+    path: "plan/_journeys/replay-world-session.yaml",
+    interlockingId: "interlocking:session-replay",
+  },
+};
+
+const unavailableWagonHandlers: WagonHandlerRegistry = {};
+
+// Source admission is the one composition with production handlers; it reports what it refused.
+function sourceWagonHandlers(supported: boolean) {
+  let refusal: string | undefined;
+  return {
+    handlers: {
+      "train:source:refuse": () => {
+        if (!supported) refusal = "UNSUPPORTED_SOURCE_FORMAT";
+        return { refused: !supported };
+      },
+    } as WagonHandlerRegistry,
+    result: () => (refusal ? { refusal } : { admitted: true }),
+  };
+}
+
+/** Production Station Master entrypoint for declared runtime journey actions. */
+export async function executeAction(action: keyof typeof JOURNEY_MAP, inputs: Record<string, unknown>) {
+  const mapping = JOURNEY_MAP[action];
+  if (!mapping) throw new Error(`Station Master action is not declared: ${action}`);
+  const sourceRun = action === "create_world"
+    ? sourceWagonHandlers(Boolean((inputs.source as { required_supported?: boolean } | undefined)?.required_supported))
+    : undefined;
+  try {
+    const execution = await new JourneyRunner(mapping.path).execute(action, inputs, {
+      initialArtifacts: action === "create_world" ? { "world:source:submission": inputs.source_submission } : {},
+      handlers: sourceRun?.handlers ?? unavailableWagonHandlers,
+      // Semantic continuations stay explicit deployment work; source remains bounded.
+      continueOnContinuation: false,
+    });
+    return sourceRun ? { ...execution, source: sourceRun.result() } : execution;
+  } catch (error) {
+    if (error instanceof UnavailableWagonError)
+      return Object.freeze({
+        disposition: "INCOMPLETE_CONTINUATION" as const,
+        status: error.status,
+        trainId: error.trainId,
+        wagon: error.wagon,
+      });
+    throw error;
+  }
+}
+
+/** HTTP-shaped Station Master for source admission. */
+export async function stationMaster(command: { submission: { id: string }; supported: boolean }): Promise<Response> {
+  const execution = await executeAction("create_world", {
+    source: { required_supported: command.supported },
+    source_submission: command.submission,
+  });
+  if ("disposition" in execution)
+    return Response.json(execution, { status: execution.status });
+  const sourceResult = "source" in execution ? execution.source : undefined;
+  const refused = Boolean(sourceResult && typeof sourceResult === "object" && "refusal" in sourceResult);
+  return Response.json(sourceResult, {
+    status: refused ? 422 : 201,
+    headers: {
+      "x-journey-disposition": "TERMINAL",
+      "x-train-output-artifact": execution.terminal.artifact,
+      "x-train-wagons": execution.wagons.join(","),
+    },
+  });
+}

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/src/trains/interlocking.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { TrainRunner, type ExecutedTrain, type WagonHandlerRegistry } from "./runner.ts";
+
+export type InterlockingResolution = Readonly<{
+  interlockingId: string;
+  routeId: string;
+  trainId: string;
+  trainPath: string;
+  category: string;
+  guardId: string;
+  resolutionStrategy: string;
+  reason: string;
+}>;
+export type InterlockedExecution = Readonly<{ resolution: InterlockingResolution; executed: ExecutedTrain }>;
+
+type Route = Readonly<{ route_id: string; train_id: string; train_path: string; guard: Readonly<{ id: string; input: string }> }>;
+
+/** Resolves one route from the parsed declaration without transcribing route or train values. */
+export class InterlockingRunner {
+  constructor(private readonly interlockingYamlPath: string) {}
+
+  async resolveTrain(action: string, inputs: Record<string, unknown>): Promise<InterlockingResolution> {
+    const declared = Bun.YAML.parse(readFileSync(this.interlockingYamlPath, "utf8")) as {
+      interlocking_id: string;
+      entrypoint: { actions: readonly string[] };
+      route_resolution: { strategy: string };
+      routes: readonly Route[];
+    };
+    if (!declared.entrypoint.actions.includes(action))
+      throw new Error(`action ${action} is not declared by ${declared.interlocking_id}`);
+    const matching = declared.routes.filter((route) => Boolean(inputs[route.guard.input]));
+    if (matching.length !== 1)
+      throw new Error(`${declared.interlocking_id} ${declared.route_resolution.strategy} selected ${matching.length} routes`);
+    const selected = matching[0]!;
+    return Object.freeze({
+      interlockingId: declared.interlocking_id,
+      routeId: selected.route_id,
+      trainId: selected.train_id,
+      trainPath: selected.train_path,
+      category: "declared",
+      resolutionStrategy: declared.route_resolution.strategy,
+      guardId: selected.guard.id,
+      reason: `guard ${selected.guard.id} held`,
+    });
+  }
+
+  /** Selects exactly one declared train, then delegates its wagon execution. */
+  async execute(
+    action: string,
+    inputs: Record<string, unknown>,
+    initialArtifacts: Record<string, unknown>,
+    handlers: WagonHandlerRegistry,
+  ): Promise<InterlockedExecution> {
+    const selected = await this.resolveTrain(action, inputs);
+    // Selection occurs once and the selected YAML path determines execution.
+    return Object.freeze({
+      resolution: selected,
+      executed: await new TrainRunner(selected.trainPath, handlers).execute(
+        selected,
+        initialArtifacts,
+      ),
+    });
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/src/trains/journey.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { InterlockingRunner } from "./interlocking.ts";
+import type { ExecutedTrain, WagonHandlerRegistry } from "./runner.ts";
+
+type Transition = Readonly<{
+  from: Readonly<{ interlocking_id: string; route_id: string }>;
+  to?: Readonly<{ interlocking_id: string }>;
+  artifact?: string;
+  outcome?: string;
+}>;
+type JourneyDeclaration = Readonly<{
+  entrypoint: Readonly<{ interlocking_id: string; actions: readonly string[] }>;
+  continuations: readonly Transition[];
+  terminals: readonly Transition[];
+}>;
+type ExecutionContext = Readonly<{
+  initialArtifacts: Record<string, unknown>;
+  handlers: WagonHandlerRegistry;
+  continueOnContinuation?: boolean;
+}>;
+export type JourneyExecution = ExecutedTrain & Readonly<{ journey: Readonly<Record<string, unknown>> }>;
+
+const pathFor = (interlockingId: string) =>
+  `plan/_trains/_interlockings/${interlockingId.replace("interlocking:", "")}.yaml`;
+
+/** Delegates each declared journey boundary to InterlockingRunner. */
+export class JourneyRunner {
+  constructor(private readonly journeyYamlPath: string) {}
+
+  /** Executes each declared route until the journey reaches one declared terminal. */
+  async execute(action: string, inputs: Record<string, unknown>, context: ExecutionContext): Promise<JourneyExecution> {
+    const declared = Bun.YAML.parse(readFileSync(this.journeyYamlPath, "utf8")) as JourneyDeclaration;
+    if (!declared?.entrypoint?.interlocking_id || !declared.entrypoint.actions?.includes(action))
+      throw new Error(`invalid journey entrypoint: ${this.journeyYamlPath}`);
+    let current = declared.entrypoint.interlocking_id;
+    let seed = context.initialArtifacts;
+    const traversed = [] as string[];
+    for (let hops = 0; hops < 32; hops++) {
+      const path = pathFor(current);
+      const run = await new InterlockingRunner(path).execute(action, inputs, seed, context.handlers);
+      const key = `${run.resolution.interlockingId}/${run.resolution.routeId}`;
+      traversed.push(run.resolution.interlockingId);
+      const continuation = declared.continuations.find(
+        (item) => item.from.interlocking_id === run.resolution.interlockingId && item.from.route_id === run.resolution.routeId,
+      );
+      const terminal = declared.terminals.find(
+        (item) => item.from.interlocking_id === run.resolution.interlockingId && item.from.route_id === run.resolution.routeId,
+      );
+      if (terminal) return Object.freeze({
+        ...run.executed,
+        journey: Object.freeze({ terminal, outcome: terminal.outcome, interlockings: Object.freeze(traversed) }),
+      });
+      if (continuation && !context.continueOnContinuation)
+        // Deployment composition can stop at a declared boundary without fabricating its successor.
+        return Object.freeze({
+          ...run.executed,
+          journey: Object.freeze({ continuation, interlockings: Object.freeze(traversed) }),
+        });
+      if (continuation) {
+        if (!continuation.to?.interlocking_id || !continuation.artifact)
+          throw new Error(`invalid journey continuation at ${key}`);
+        current = continuation.to.interlocking_id;
+        // The next train receives only the planner-declared handoff from the prior execution.
+        seed = { [continuation.artifact]: run.executed.terminal.value };
+        continue;
+      }
+      throw new Error(`journey route is not declared as a continuation or terminal: ${key}`);
+    }
+    throw new Error(`journey continuation limit exceeded: ${this.journeyYamlPath}`);
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/clean/journey_station_master_production_shape/src/trains/runner.ts

@@ -0,0 +1,28 @@
+export type ExecutedTrain = Readonly<{
+  selectedTrainId: string;
+  terminal: Readonly<{ artifact: string; value: unknown }>;
+  wagons: readonly string[];
+}>;
+export type WagonHandlerRegistry = Readonly<Record<string, (seed: Record<string, unknown>) => unknown>>;
+
+/** A declared wagon whose handler this deployment has not composed. */
+export class UnavailableWagonError extends Error {
+  readonly status = 202;
+  constructor(readonly trainId: string, readonly wagon: string) {
+    super(`wagon ${wagon} of ${trainId} is unavailable`);
+  }
+}
+
+export class TrainRunner {
+  constructor(private readonly trainPath: string, private readonly handlers: WagonHandlerRegistry) {}
+  async execute(resolution: Readonly<{ trainId: string }>, seed: Record<string, unknown>): Promise<ExecutedTrain> {
+    const wagon = this.trainPath.replace(/^plan\/_trains\/|\.yaml$/g, "");
+    const handler = this.handlers[wagon];
+    if (!handler) throw new UnavailableWagonError(resolution.trainId, wagon);
+    return Object.freeze({
+      selectedTrainId: resolution.trainId,
+      terminal: Object.freeze({ artifact: `${wagon}:result`, value: handler(seed) }),
+      wagons: Object.freeze([wagon]),
+    });
+  }
+}

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

@@ -0,0 +1,8 @@
+// Phase: SMOKE
+import { expect, test } from "bun:test";
+import { dispatch } from "../../server";
+
+test("resolve_match traverses the exported journey dispatch", () => {
+  const result = dispatch("resolve_match", { voted: true }, { handlers: {}, seed: {} });
+  expect(result.selectedTrainId).toBe("train:match:nominal");
+});

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_mediated_direct_business/plan/_trains/_interlockings/match.yaml

@@ -0,0 +1,9 @@
+interlocking_id: interlocking:match
+entrypoint:
+  exposed: true
+  actions:
+    - resolve_match
+routes:
+  - route_id: nominal
+    train_id: train:match:nominal
+    train_path: plan/_trains/train:match:nominal.yaml

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_mediated_direct_business/server.ts

@@ -0,0 +1,21 @@
+import { JourneyRunner } from "./src/trains/journey";
+import { InterlockingRunner } from "./src/trains/interlocking";
+import { TrainRunner } from "./src/trains/runner";
+
+export const JOURNEY_MAP = {
+  resolve_match: { journeyId: "journey:match", path: "plan/_journeys/match.yaml" },
+};
+
+// The production chain is importable and even exercised by a module-local helper, but the
+// exported action returns business data directly instead of the JourneyRunner execution.
+const runner = new InterlockingRunner("plan/_trains/_interlockings/match.yaml");
+function inertProductionHelper(action: string, inputs: object, context: { handlers: object; seed: object }) {
+  const resolution = runner.resolveTrain(action, inputs);
+  return new TrainRunner(resolution.trainPath, context.handlers).execute(resolution, context.seed);
+}
+
+export function dispatch(_action: keyof typeof JOURNEY_MAP, _inputs: object, _context: { handlers: object; seed: object }) {
+  void JourneyRunner;
+  void inertProductionHelper;
+  return { selectedTrainId: "train:match:nominal" };
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_mediated_direct_business/src/trains/interlocking.ts

@@ -0,0 +1,12 @@
+import { TrainRunner } from "./runner";
+
+export class InterlockingRunner {
+  constructor(private readonly interlockingPath: string) {}
+  resolveTrain(_action: string, _inputs: object) {
+    return { routeId: "nominal", trainId: "train:match:nominal", trainPath: "plan/_trains/train:match:nominal.yaml" };
+  }
+  execute(action: string, inputs: object, context: { handlers: object; seed: object }) {
+    const resolution = this.resolveTrain(action, inputs);
+    return new TrainRunner(resolution.trainPath, context.handlers).execute(resolution, context.seed);
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_mediated_direct_business/src/trains/journey.ts

@@ -0,0 +1,8 @@
+import { InterlockingRunner } from "./interlocking";
+
+export class JourneyRunner {
+  constructor(private readonly journeyPath: string) {}
+  execute(action: string, inputs: object, context: { handlers: object; seed: object }) {
+    return new InterlockingRunner(this.journeyPath).execute(action, inputs, context);
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_mediated_direct_business/src/trains/runner.ts

@@ -0,0 +1,6 @@
+export class TrainRunner {
+  constructor(private readonly trainPath: string, private readonly handlers: object = {}) {}
+  execute(resolution: { trainId: string }, seed: object) {
+    return { selectedTrainId: resolution.trainId, trainPath: this.trainPath, handlers: this.handlers, seed };
+  }
+}

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

@@ -0,0 +1,8 @@
+// Phase: SMOKE
+import { expect, test } from "bun:test";
+import { dispatch } from "../../server";
+
+test("resolve_match traverses the exported journey dispatch", () => {
+  const result = dispatch("resolve_match", { voted: true }, { handlers: {}, seed: {} });
+  expect(result.selectedTrainId).toBe("train:match:nominal");
+});

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_test_local_lookalike/plan/_trains/_interlockings/match.yaml

@@ -0,0 +1,9 @@
+interlocking_id: interlocking:match
+entrypoint:
+  exposed: true
+  actions:
+    - resolve_match
+routes:
+  - route_id: nominal
+    train_id: train:match:nominal
+    train_path: plan/_trains/train:match:nominal.yaml

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_test_local_lookalike/server.ts

@@ -0,0 +1,11 @@
+import { JourneyRunner } from "./src/trains/journey.test";
+
+export const JOURNEY_MAP = {
+  resolve_match: { journeyId: "journey:match", path: "plan/_journeys/match.yaml" },
+};
+
+// Identical to the clean dispatch except that JourneyRunner resolves to a test-local module.
+export function dispatch(action: keyof typeof JOURNEY_MAP, inputs: object, context: { handlers: object; seed: object }) {
+  const mapping = JOURNEY_MAP[action];
+  return new JourneyRunner(mapping.path).execute(action, inputs, context);
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_test_local_lookalike/src/trains/interlocking.ts

@@ -0,0 +1,12 @@
+import { TrainRunner } from "./runner";
+
+export class InterlockingRunner {
+  constructor(private readonly interlockingPath: string) {}
+  resolveTrain(_action: string, _inputs: object) {
+    return { routeId: "nominal", trainId: "train:match:nominal", trainPath: "plan/_trains/train:match:nominal.yaml" };
+  }
+  execute(action: string, inputs: object, context: { handlers: object; seed: object }) {
+    const resolution = this.resolveTrain(action, inputs);
+    return new TrainRunner(resolution.trainPath, context.handlers).execute(resolution, context.seed);
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_test_local_lookalike/src/trains/journey.test.ts

@@ -0,0 +1,8 @@
+import { InterlockingRunner } from "./interlocking";
+
+export class JourneyRunner {
+  constructor(private readonly journeyPath: string) {}
+  execute(action: string, inputs: object, context: { handlers: object; seed: object }) {
+    return new InterlockingRunner(this.journeyPath).execute(action, inputs, context);
+  }
+}

package/detectors/bun_interlocking_coverage/fixtures/dirty/journey_test_local_lookalike/src/trains/runner.ts

@@ -0,0 +1,6 @@
+export class TrainRunner {
+  constructor(private readonly trainPath: string, private readonly handlers: object = {}) {}
+  execute(resolution: { trainId: string }, seed: object) {
+    return { selectedTrainId: resolution.trainId, trainPath: this.trainPath, handlers: this.handlers, seed };
+  }
+}

package/detectors/bun_interlocking_infrastructure/checks/interlocking_station_routing.mjs

@@ -16,6 +16,7 @@ import {
   mk,
   writeReport,
 } from "../_shared/interlocking.mjs";
+import { provenJourneyActions } from "../../../lib/journey-chain.mjs";
 
 const RULE = "coder.bun.station-master-interlocking-routing";
 const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
@@ -37,6 +38,10 @@ for (const scanRoot of roots) {
     const text = readText(app);
     const jm = journeyMap(text);
     if (!jm.hasInterlocking) continue; // pure direct-train Station Master carries no obligation.
+    // A journey-mediated Station Master delegates to the runners through JourneyRunner; when an exported
+    // action provably returns JourneyRunner -> InterlockingRunner -> TrainRunner execution (bound
+    // imports, live returns, no overrides), it need not reference the lower runners itself.
+    if (provenJourneyActions(text, app, croot).length > 0) continue;
 
     const line = jm.interlockingLine || 1;
     if (!referencesToken(text, "InterlockingRunner")) {

package/detectors/bun_interlocking_infrastructure/checks/journey_station_routing.mjs

@@ -15,6 +15,7 @@ import {
   maskComments,
   PLAN_ROOT,
 } from "../_shared/interlocking.mjs";
+import { provenJourneyActions } from "../../../lib/journey-chain.mjs";
 
 const RULE = "coder.bun.station-master-journey-routing";
 const roots = parseJsonEnv("ATDD_SCAN_ROOTS", []);
@@ -98,7 +99,10 @@ for (const scanRoot of roots) {
       "journey-station-unlinked: exposed journeys exist but Station Master never references JourneyRunner",
       lineAt(text, 1),
     ));
-    if (referencesToken(text, "JourneyRunner") && !dispatchInvokesMappedJourneyRunner(text)) violations.push(mk(
+    // Any exported action (not only `dispatch`) may carry the mapped JourneyRunner execution, provided
+    // the whole chain is proven on the AST (lib/journey-chain.mjs).
+    if (referencesToken(text, "JourneyRunner") && !dispatchInvokesMappedJourneyRunner(text) &&
+      provenJourneyActions(text, app, croot).length === 0) violations.push(mk(
       RULE,
       appPath,
       1,