@afokapu/atdd-bun 0.1.0

package/conventions/coder.bun/coder.bun.interlocking-does-not-carry-cargo.convention.yaml

@@ -0,0 +1,53 @@
+schema_version: 1.1.0
+rule_id: coder.bun.interlocking-does-not-carry-cargo
+kind: rule
+status: active
+name: Cargo stays inside TrainRunner execution; interlocking does not carry it and wagons stay clean (Bun)
+statement: >-
+  Cargo is the artifact data plane carried by TrainRunner between wagons inside a selected train. An
+  `InterlockingRunner` MUST NOT reference or mutate Cargo, MUST NOT store `artifact_urn -> artifact_data`
+  runtime values, and MUST NOT route on mid-train Cargo state; and Bun wagons (`src/<wagon>/wagon.ts`)
+  MUST NOT import interlocking code. This is the Bun-stack realization of the agnostic core obligation
+  `coder.train.interlocking-does-not-carry-cargo` (core afokapu/atdd#1251); the JS detector that enforces
+  it is the atdd.workspace.bun implementation referenced below.
+implementation:
+  type: validator
+  ref: coder.bun.interlocking-does-not-carry-cargo
+content:
+  summary: >-
+    An agnostic "Cargo boundary" obligation, rendered for the Bun application. The JS realization scans
+    each InterlockingRunner-defining module under `src/trains/**` and flags a `Cargo` reference, a
+    `cargo[...] = ...` mutation, or an `artifact_urn` literal; and scans each `src/<wagon>/wagon.ts`
+    and flags an import of interlocking code. Member of the `bun_interlocking_infrastructure` FAMILY
+    detector (checks/interlocking_no_cargo.mjs).
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251 — Cargo boundary. Allowed: the interlocking reads the initial
+    action/inputs/state before execution and a completed TrainResult only at a declared route boundary;
+    TrainRunner passes Cargo between wagons; wagons read and return artifact objects. Forbidden: the
+    interlocking reads or mutates Cargo during train execution, stores artifact_urn -> artifact_data
+    values, or routes on mid-train Cargo state; Cargo selecting train variants; wagons importing
+    interlocking code. WHICH modules are scanned and HOW the Cargo touches are recognized is the
+    per-stack detector's concern (comments are masked; a string `artifact_urn` literal is still detected).
+  fix_hint: |
+    Keep Cargo inside TrainRunner. The InterlockingRunner reads only initial action/inputs/state and a
+    declared-boundary TrainResult; it never references Cargo, mutates a cargo mapping, or stores
+    artifact_urn values. Wagons import their own dependencies, never InterlockingRunner. This rule is
+    `strict`: a newly introduced Cargo touch (or a wagon importing interlocking) is not suppressible and
+    fails CI.
+  exceptions:
+    - The production `TrainRunner` module legitimately constructs and carries Cargo; only
+      InterlockingRunner-defining modules are scanned for Cargo bleed.
+metadata:
+  aliases:
+    - BUN-INTERLOCKING-NO-CARGO-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: cargo_boundary
+    text: >-
+      the rule that Cargo (artifact data plane) stays inside TrainRunner execution; the InterlockingRunner
+      must not reference/mutate Cargo or store artifact_urn values, and wagons must not import it.

package/conventions/coder.bun/coder.bun.interlocking-resolution-model-exists.convention.yaml

@@ -0,0 +1,61 @@
+schema_version: 1.1.0
+rule_id: coder.bun.interlocking-resolution-model-exists
+kind: rule
+status: active
+name: Interlocking route resolution returns structured metadata, not a bare trainId (Bun)
+statement: >-
+  An `InterlockingRunner.resolveTrain(...)` MUST resolve a structured `InterlockingResolution` model
+  carrying the route metadata — not a bare `trainId` string. The model MUST define the fields
+  `interlockingId`, `routeId`, `trainId`, `trainPath`, `category`, `guardId`, `resolutionStrategy`, and
+  `reason`. This is the Bun-stack realization of the agnostic core obligation
+  `coder.train.interlocking-resolution-model-exists` (core afokapu/atdd#1251); the JS detector that
+  enforces it is the atdd.workspace.bun implementation referenced below.
+implementation:
+  type: validator
+  ref: coder.bun.interlocking-resolution-model-exists
+content:
+  summary: >-
+    An agnostic "structured route resolution" obligation, rendered for the Bun application. The JS
+    realization scans `src/trains/**/*.ts`: when an `InterlockingRunner` exposes `resolveTrain`, an
+    `InterlockingResolution` type/interface/class defining the eight required fields MUST exist;
+    otherwise the route is resolved as a bare trainId. Member of the `bun_interlocking_infrastructure`
+    FAMILY detector (checks/interlocking_resolution_model.mjs).
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251 suggests the resolution model. For the Bun/TS stack:
+
+        export interface InterlockingResolution {
+          interlockingId: string; routeId: string; trainId: string; trainPath: string;
+          category: string; guardId: string; resolutionStrategy: string; reason: string;
+        }
+
+    A bare trainId string loses the routeId, guardId, category, resolutionStrategy, trainPath, and
+    the human-readable reason needed for trace and projection equivalence. Category agreement is
+    judged against the target train's `category` FIELD, never a digit parsed out of the identity
+    validation. WHICH runtime files are inspected and HOW the model fields are recognized is the
+    per-stack detector's concern (Bun: collecting the InterlockingResolution property names).
+  fix_hint: |
+    Define the structured model and return it from resolveTrain:
+
+      return {
+        interlockingId, routeId, trainId, trainPath,
+        category, guardId, resolutionStrategy, reason,
+      };
+
+    This rule is `strict`: a resolveTrain backed only by a bare trainId is not suppressible and fails CI.
+  exceptions:
+    - Applies only when an `InterlockingRunner` with a `resolveTrain` method is present (a missing
+      runner/method is the separate `coder.bun.interlocking-runner-exists` concern).
+metadata:
+  aliases:
+    - BUN-INTERLOCKING-RESOLUTION-MODEL-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: interlocking_resolution_model
+    text: >-
+      the `InterlockingResolution` structure returned by resolveTrain, carrying interlockingId, routeId,
+      trainId, trainPath, category, guardId, resolutionStrategy, reason.

package/conventions/coder.bun/coder.bun.interlocking-runner-exists.convention.yaml

@@ -0,0 +1,64 @@
+schema_version: 1.1.0
+rule_id: coder.bun.interlocking-runner-exists
+kind: rule
+status: active
+name: InterlockingRunner route-control layer exists with a resolveTrain entry point (Bun)
+statement: >-
+  When a consumer Bun application declares guarded interlocking routes (a `JOURNEY_MAP` entry that is an
+  `{interlockingId, path}` route object in the Station Master composition root `server.ts`), the
+  consumer runtime MUST ship an `InterlockingRunner` route-control layer — a `class InterlockingRunner`
+  defined under `src/trains/**` that exposes a `resolveTrain(...)` entry point. This is the
+  Bun-stack realization of the agnostic core obligation `coder.train.interlocking-runner-exists`
+  (core afokapu/atdd#1251, Part of #1246); the zero-dependency JS detector that enforces it is the
+  atdd.workspace.bun implementation referenced below.
+implementation:
+  type: validator
+  ref: coder.bun.interlocking-runner-exists
+content:
+  summary: >-
+    An agnostic "the InterlockingRunner runtime exists" obligation, rendered for the Bun application. The
+    JS realization scans the consumer's `src/trains/**/*.ts` runtime and flags a consumer that
+    declares an interlocking route (a JOURNEY_MAP route object) but ships no `InterlockingRunner` class,
+    or ships one that lacks a `resolveTrain` method. Member of the `bun_interlocking_infrastructure`
+    FAMILY detector (checks/interlocking_runner_exists.mjs).
+  normative_text: |
+    Core runtime spec afokapu/atdd#1251: an interlocking is executable only as a route-control component.
+    Its entry point is `InterlockingRunner.resolveTrain(action, inputs, state)`, which evaluates guarded
+    routes and resolves exactly one admissible train before delegation. A Bun consumer that declares
+    interlocking routes without this class — or with a class that has no resolveTrain — has no
+    route-control layer at all. WHICH runtime files are inspected and HOW the class/method are recognized
+    is the per-stack detector's concern (Bun: a regex-over-source scan of the `src/trains/**`
+    selector plus the `server.ts` JOURNEY_MAP).
+  fix_hint: |
+    Add the route-control layer:
+
+      // src/trains/interlocking.ts
+      export class InterlockingRunner {
+        constructor(private readonly interlockingYamlPath: string) {}
+        resolveTrain(action: string, inputs: Record<string, unknown>, state?: unknown): InterlockingResolution { ... }
+      }
+
+    This rule is `strict`: a newly introduced interlocking route without an InterlockingRunner +
+    resolveTrain is not suppressible and fails CI.
+  exceptions:
+    - A pure direct-train consumer (no interlocking route object in JOURNEY_MAP and no InterlockingRunner
+      class) carries no obligation and is not flagged.
+    - Generated and vendored trees (`_generated/`, `node_modules/`, `dist/`, `build/`, `.next/`) are never scanned.
+metadata:
+  aliases:
+    - BUN-INTERLOCKING-RUNNER-EXISTS-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+  core_design_refs:
+    - afokapu/atdd#1246
+    - afokapu/atdd#1251
+terms:
+  - term_id: interlocking_runner
+    text: >-
+      a `class InterlockingRunner` under `src/trains/` exposing `resolveTrain(...)`; the route-control
+      component that selects one admissible train and delegates execution to TrainRunner.
+  - term_id: journey_map
+    text: >-
+      the `JOURNEY_MAP` action->route mapping in `server.ts`; values are either a direct trainId
+      string or an `{interlockingId, path}` route object.

package/conventions/coder.bun/coder.bun.journey-runner-boundary.convention.yaml

@@ -0,0 +1,55 @@
+schema_version: 1.1.0
+rule_id: coder.bun.journey-runner-boundary
+kind: rule
+status: active
+name: JourneyRunner composes interlockings without executing trains or wagons (Bun)
+statement: >-
+  A Bun consumer that declares one or more journey topology documents under plan/_journeys/ MUST ship
+  a JourneyRunner under src/trains/**. JourneyRunner is the continuation-control layer above
+  InterlockingRunner: it MUST read and parse the declared journey topology, MUST reference
+  InterlockingRunner for routing decisions, MUST NOT construct an InterlockingRunner from a hardcoded
+  literal path, and MUST NOT bypass
+  that boundary by referencing TrainRunner directly, importing wagon modules, calling runTrain(...),
+  looping over train.sequence as an executor, or carrying/mutating Cargo. InterlockingRunner continues
+  to select exactly one train and delegate that train to TrainRunner; JourneyRunner only decides which
+  interlocking is entered next according to the declared journey topology.
+implementation:
+  type: validator
+  ref: coder.bun.journey-runner-boundary
+content:
+  summary: >-
+    Enforces the Bun runtime boundary introduced by planner journey topology. Presence of
+    plan/_journeys/**/*.yaml enables the obligation. The family detector looks for class
+    JourneyRunner under src/trains/**, requires evidence that the runtime reads and parses a journey
+    declaration, requires it to reference InterlockingRunner, rejects literal InterlockingRunner
+    construction, and rejects direct TrainRunner/wagon/Cargo execution patterns.
+  normative_text: |
+    The intended call model is:
+
+        Station Master
+          -> JourneyRunner
+               -> InterlockingRunner.resolve/execute(...)
+                    -> TrainRunner.execute(selectedTrainId, ...)
+               -> inspect declared continuation/terminal
+               -> next InterlockingRunner ...
+
+    JourneyRunner owns continuation control, never the train step loop. InterlockingRunner owns local
+    route selection, never cross-interlocking topology. TrainRunner remains the only wagon-step executor.
+  fix_hint: |
+    Add a JourneyRunner under src/trains/ that reads the supplied journey declaration and delegates
+    each routing decision to InterlockingRunner using declaration-derived values. Remove literal
+    InterlockingRunner paths, direct TrainRunner calls, wagon imports, Cargo handling, runTrain(...)
+    calls, and train.sequence executor loops from JourneyRunner.
+  exceptions:
+    - Consumers with no plan/_journeys topology carry no JourneyRunner obligation.
+metadata:
+  aliases:
+    - BUN-JOURNEY-RUNNER-BOUNDARY-001
+  severity: 4
+  disposition: strict
+  introduced_in: 0.1.0
+terms:
+  - term_id: journey_runner
+    text: the runtime continuation-control layer that traverses declared journey topology between interlockings.
+  - term_id: boundary
+    text: JourneyRunner -> InterlockingRunner -> TrainRunner; each layer owns only its declared responsibility.

package/conventions/coder.bun/coder.bun.layer-naming.convention.yaml

@@ -0,0 +1,41 @@
+schema_version: 1.1.0
+rule_id: coder.bun.layer-naming
+kind: rule
+status: active
+name: Feature modules name their architectural layer
+statement: >-
+  A module inside a `features/` or `wagons/` tree MUST name its architectural layer — either by filename
+  (`domain.ts`, `application.ts`, `api.ts`, …) or by living in a directory named for the layer. Bun
+  realization mirroring `coder.convex.layer-naming`; core obligation `coder.backend.code-is-organized`.
+terms:
+- term_id: layer_declaration
+  text: >-
+    how a module names its layer: either the filename (domain.ts, api.ts) or a directory named
+    for the layer. Both accepted, because a nested Bun repo is idiomatic.
+- term_id: feature_tree
+  text: >-
+    a path under `features/` or `wagons/` — the only place this rule applies.
+content:
+  summary: >-
+    Flags a feature-tree module whose path carries no layer directory and whose basename is not a layer
+    filename.
+  normative_text: |
+    ADDED TO THE MIRROR, and worth flagging: the Convex sibling accepts only the FILENAME form, because its function tree is flat. A full-stack Bun repo commonly nests (`features/orders/domain/total.ts`), so accepting only filenames would refuse the idiomatic layout. This realization accepts BOTH.
+    The obligation is unchanged: a reader should know a file's role before opening it, and the layering rules need something to read.
+  fix_hint: |
+    Either rename the file to its layer, or move it into the layer directory it belongs to.
+  exceptions:
+  - Test files and vendored/build directories are never scanned.
+  - Bare npm specifiers resolve outside the project graph and are not layer-checked.
+  - A file carrying no layer segment is outside these rules rather than in violation of them.
+metadata:
+  aliases:
+  # Mirrored rule-for-rule from coder.convex.layer-naming
+  # Core obligation: coder.backend.code-is-organized
+  - BUN-LAYER-NAMING-001
+  severity: 2
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_clean_architecture_detector

package/conventions/coder.bun/coder.bun.logging-console.convention.yaml

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: coder.bun.logging-console
+kind: rule
+status: active
+name: No console logging in application source
+statement: >-
+  Application source MUST NOT call `console.log` / `info` / `warn` / `error` / `debug` / `trace` / `dir`.
+  Stack-neutral obligation, RE-REALIZED for Bun: the python-pytest sibling walks the AST for a bare
+  `print(...)`; the Bun equivalent is `console.*`. Realized by `bun_security_hygiene_detector` (core alias
+  LOGGING-PRINT-001).
+terms:
+- term_id: unlevelled_output
+  text: >-
+    a `console.*` call: no level, no timestamp, no request correlation. In a full-stack app the
+    same module may write to the operator's stdout or the user's devtools.
+- term_id: structured_logger
+  text: >-
+    the project logger that owns levels, timestamps and correlation.
+content:
+  summary: >-
+    Scans source with strings and comments MASKED, so `console.log` inside a comment or a string literal
+    never trips the rule.
+  normative_text: |
+    The obligation is the same as the Python one but the consequence is sharper. A Bun server writes `console.log` straight to stdout with no level, no timestamp and no request correlation, so production logs become a single unfilterable stream — and in a full-stack app the same module may run on the server AND in the browser, where `console` output reaches the user's devtools instead of the operator's.
+    `console.error` is included: it is still unlevelled and uncorrelated, and being on stderr does not make it queryable.
+  fix_hint: |
+    Route through the logger, which owns levels, timestamps and correlation:
+
+      console.log("processing", order.id);                 // wrong
+      logger.info("processing order", { orderId: order.id }); // right
+  exceptions:
+  - Occurrences inside comments or string literals are masked and never flagged.
+  - Test files and vendored/build directories are excluded.
+  - A CLI whose stdout IS its user interface should scope itself out via the consumer scope map.
+metadata:
+  aliases:
+  # LOGGING-PRINT-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - LOGGING-PRINT-001
+  severity: 2
+  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
+  # AST for constructs this stack does not have. Same obligation, new detector.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.logging-structured.convention.yaml

@@ -0,0 +1,49 @@
+schema_version: 1.1.0
+rule_id: coder.bun.logging-structured
+kind: rule
+status: active
+name: Log calls carry a structured context object
+statement: >-
+  A logger call MUST NOT pass only a bare string; it MUST carry a context object. Stack-neutral
+  obligation, RE-REALIZED for Bun: the receiver names and log methods carry over from the python-pytest
+  sibling `coder.logging.structured`, but the argument shape does not — a JS logger takes a context OBJECT
+  where the Python one takes `extra=` or kwargs. Realized by `bun_security_hygiene_detector` (core alias
+  LOGGING-STRUCTURED-001).
+terms:
+- term_id: context_object
+  text: >-
+    the second argument carrying the fields a line will be searched by. A JS logger takes an
+    object where a Python one takes `extra=`.
+- term_id: bare_string_log
+  text: >-
+    a logger call whose only argument is a string literal. Greppable and nothing more, at the
+    one moment it matters.
+content:
+  summary: >-
+    Flags a call on a logger receiver (`logger` / `log` / `_logger` / `_log` / `LOG`) whose sole argument
+    is a string literal.
+  normative_text: |
+    A log line's value is realised at exactly one moment: when someone is searching for it during an incident. A bare string can only be grepped; a line carrying `{ orderId, userId }` can be filtered, grouped and joined to a trace.
+    The rule asks only that SOME context is attached — it cannot judge whether the right fields were chosen. The useful discipline is to ask what you would filter by at 3am and put that in the object.
+  fix_hint: |
+    Attach the fields the line would be searched by:
+
+      logger.info("order processed");                              // wrong
+      logger.info("order processed", { orderId, userId, ms });      // right
+  exceptions:
+  - A call already passing a second argument is not flagged.
+  - Non-logger receivers are out of scope.
+  - Disposition is `suppress-and-clean`, matching the Python sibling: a ratchet holds existing lines flat.
+metadata:
+  aliases:
+  # LOGGING-STRUCTURED-001 is the SHARED core alias, also carried by the agnostic node and its
+  # python-pytest realization.
+  - LOGGING-STRUCTURED-001
+  severity: 2
+  # RE-REALIZED, not ported: the python-pytest sibling inspects a Python
+  # AST for constructs this stack does not have. Same obligation, new detector.
+  disposition: suppress-and-clean
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_security_hygiene_detector

package/conventions/coder.bun/coder.bun.quality-comments.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.1.0
+rule_id: coder.bun.quality-comments
+kind: rule
+status: active
+name: TypeScript files carry at least a 10% comment ratio
+statement: >-
+  Every TypeScript/TSX file MUST have a comment ratio of at least 10% of non-blank lines. Stack-neutral
+  obligation, NATIVE BUN detector transcribed from the python-pytest sibling `coder.refactor.quality-
+  comments-typescript` and verified numerically identical. Realized by `bun_ts_metrics_detector` (core
+  alias REFACTOR-QUALITY-COMMENTS-TS-001).
+terms:
+- term_id: comment_ratio
+  text: >-
+    comment lines over non-blank lines, counting line comments, block comments and `*`
+    continuations.
+- term_id: floor_against_absence
+  text: >-
+    what this rule is. It cannot tell a good comment from a bad one; it catches the file that
+    documents nothing.
+content:
+  summary: >-
+    Counts line comments, block comments and continuation lines beginning `*` against all non-blank lines.
+  normative_text: |
+    A ratio is a blunt instrument for a quality that is not quantitative, and it is used here for one narrow reason: a file with NO comments at all is common and is almost always a file whose non-obvious decisions were never written down. Ten percent is low enough that any file with a real header and a few explanatory lines clears it.
+    The rule cannot tell a good comment from a bad one. It is a floor against absence, not a measure of quality, and it should not be read as encouragement to restate code in prose.
+  fix_hint: |
+    Explain the decisions the code cannot state: why this approach over the obvious one, what invariant the block maintains, which upstream constraint forces the shape. In a Bun + htmx file the GREEN header already contributes several lines toward the ratio.
+  exceptions:
+  - Blank lines are excluded from both numerator and denominator.
+  - Continuation lines beginning `*` inside a block comment count as comment lines.
+  - Test files and vendored/build directories are outside the scan.
+metadata:
+  aliases:
+  # REFACTOR-QUALITY-COMMENTS-TS-001 is the SHARED core alias, also carried by the agnostic node and by
+  # its python-pytest realization. One obligation, two detectors, two runtimes.
+  - REFACTOR-QUALITY-COMMENTS-TS-001
+  severity: 2
+  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
+  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.quality-mi.convention.yaml

@@ -0,0 +1,47 @@
+schema_version: 1.1.0
+rule_id: coder.bun.quality-mi
+kind: rule
+status: active
+name: TypeScript files keep a maintainability index of at least 20
+statement: >-
+  Every TypeScript/TSX file MUST score at least 20 on the approximate SEI maintainability index. Stack-
+  neutral obligation, NATIVE BUN detector transcribed from the python-pytest sibling
+  `coder.refactor.quality-mi-typescript` — the Halstead volume, the log terms and the comment term are the
+  same formula, verified identical to ten decimal places. Realized by `bun_ts_metrics_detector` (core
+  alias REFACTOR-QUALITY-MI-TS-001).
+terms:
+- term_id: maintainability_index
+  text: >-
+    the approximate SEI composite: 171 - 5.2*ln(V) - 0.23*avgCC - 16.2*ln(LOC) +
+    50*sin(sqrt(2.4*CM)), clamped to 0..100.
+- term_id: halstead_volume
+  text: >-
+    V — a regex-approximated operator/operand count standing in for the file's information
+    content. No AST, no external library.
+content:
+  summary: >-
+    MI = 171 - 5.2*ln(V) - 0.23*avgCC - 16.2*ln(LOC) + 50*sin(sqrt(2.4*CM)), clamped to 0..100, where V is
+    a regex-approximated Halstead volume, avgCC the average decision density per function, and CM the
+    comment ratio. No AST, no external library.
+  normative_text: |
+    MI is a composite, and that is the point: a file can pass every per-function threshold and still be unmaintainable through sheer accumulated size and operator density. MI is the only rule here that judges the FILE rather than its parts.
+    It is an approximation and is treated as one — the threshold of 20 is set low enough that a score below it indicates a file nobody should be asked to modify, not a file that is merely imperfect.
+  fix_hint: |
+    Split the file. MI falls fastest with the log of line count, so extracting a cohesive half into its own module raises both halves at once. Adding comments also raises the score, but comment density is a weaker term than size and should not be used as the remedy.
+  exceptions:
+  - Files that produce zero code lines after comment stripping score 100 and never fail.
+  - The score is clamped to the 0..100 range.
+  - Test files and vendored/build directories are outside the scan.
+metadata:
+  aliases:
+  # REFACTOR-QUALITY-MI-TS-001 is the SHARED core alias, also carried by the agnostic node and by
+  # its python-pytest realization. One obligation, two detectors, two runtimes.
+  - REFACTOR-QUALITY-MI-TS-001
+  severity: 2
+  # `strict`, matching the python-pytest sibling exactly. A repo adopting this on an
+  # existing codebase records a ratchet baseline rather than lowering the threshold.
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_ts_metrics_detector

package/conventions/coder.bun/coder.bun.runtime-executes-the-declaration.convention.yaml

@@ -0,0 +1,104 @@
+schema_version: 1.1.0
+rule_id: coder.bun.runtime-executes-the-declaration
+kind: rule
+# DRAFT, and the word is load-bearing. The obligation is authored and its validator
+# exists and is tested, but it is realized by `scan_execution()` which the gated
+# `scan_root()` deliberately does not call. Shipping it `active` would claim an
+# enforcement that never runs — a rule that says it checks and does not. It becomes
+# `active` in the same change that wires the check into the gate.
+status: active
+name: The runtime executes the declared route space rather than transcribing it
+statement: >-
+  A consumer that declares guarded interlocking routes MUST have a runtime that READS the
+  declaration it is given. An `InterlockingRunner` constructed with an interlocking YAML path MUST
+  load that path and resolve from what it read; a `TrainRunner` MUST take the wagon order from the
+  train definition. A runtime that stores the path and returns hardcoded values satisfies every
+  text-level rule in this package and is not executing the plan — it is transcribing it.
+terms:
+- term_id: loads_the_declaration
+  text: >-
+    some module under the runtime selector reads a file — `yaml.safe_load`, `json.load`,
+    `open(...)`, `.read_text(...)`. Checked across the whole runtime surface rather than per
+    module, because a correct implementation may delegate loading to a sibling loader.
+- term_id: transcription
+  text: >-
+    a runtime whose resolution fields and wagon order are literals that happen to match the
+    declaration. It agrees with the plan at the moment it is written and cannot disagree
+    detectably afterwards, because nothing compares them at runtime.
+- term_id: unreachable_route
+  text: >-
+    a declared `route_id` that appears nowhere in a runtime which does not load the declaration.
+    A data-driven runtime serves every declared route by construction and mentions none of them as
+    literals, so this is only ever evaluated against a transcribing runtime.
+- term_id: disposition_rationale
+  text: >-
+    advisory because NO consumer satisfies it today, including this package's own fixtures until
+    the commit that introduced this node. The measurement below was TAKEN, not recalled.
+  values:
+    measured_2026_09_07: >-
+      A Bun consumer was built from scratch in this stack's idiom to establish the read
+      vocabulary, because the python heuristic (yaml.safe_load / read_text) matches NOTHING a
+      compliant Bun runtime does — porting it blind would have reported every Bun consumer as
+      plan-blind. Verified: the compliant consumer is silent, a transcribing one fires naming the
+      literals it restated, and a query-loading one that reads nothing and states nothing stays
+      silent.
+    measurement_target: a Bun consumer repo built for the experiment
+    escalate_when: >-
+      Consumer runtimes load their declarations and the check has been wired into
+      gates/interlocking-binding.gate.yaml. Enabling it is a GATE change; the detector is staged
+      (`scan_execution`) and deliberately not called from `scan_root`.
+content:
+  summary: >-
+    The obligation that makes "the train YAML is the source of truth" true of the RUNTIME and not
+    merely of the text. Every other rule in this package closes a correspondence between literals
+    in the code and literals in the plan; none asks whether the code ever reads it.
+  normative_text: |
+    FOUND BY RUNNING THIS PACKAGE AGAINST A REAL CONSUMER, which is the only way it could have been
+    found. A consumer whose InterlockingRunner stored `interlocking_yaml_path` and returned a
+    hardcoded InterlockingResolution, and whose TrainRunner kept a literal train_id -> wagons map,
+    was fully compliant. Three divergences between plan and runtime were then introduced:
+
+      a declared route the runtime cannot resolve   -> nothing fired
+      a wagon sequence contradicting the runtime    -> nothing fired
+      the entire plan/ directory deleted            -> only bilateral binding, because the
+                                                       runtime's literals became undeclared
+
+    The application kept dispatching in all three cases. That is the definition of a plan that is
+    not executable.
+
+    WHY A TRANSCRIBING RUNTIME IS WORSE THAN AN ABSENT ONE. An absent runtime fails loudly the
+    first time anything runs. A transcribing one agrees with the declaration on the day it is
+    written and diverges silently ever after — the plan is edited, the runtime is not, and every
+    check still passes because each still contains the same literals it always did.
+  fix_hint: |
+    Load the declaration and resolve from it:
+
+      def _declaration(self):
+          return yaml.safe_load(Path(self._path).read_text(encoding="utf-8")) or {}
+
+      def route_by_id(self, route_id):
+          for route in self._declaration().get("routes") or []:
+              if route.get("route_id") == route_id:
+                  return _Route(route)
+
+    Resolve through a `route_by_id`-style accessor rather than filtering inline: bilateral
+    binding's provenance scan traces a resolution kwarg back through such an accessor to the
+    loaded route space, and cannot trace an inline filter — which it reports as undecidable
+    rather than passing silently.
+  exceptions:
+  - A consumer that declares no interlocking route space carries no obligation.
+  - A runtime that loads the declaration is never checked for route literals; it serves every
+    declared route by construction, and flagging the absent literal would punish the correct
+    implementation for being correct.
+metadata:
+  aliases:
+  - BUN-RUNTIME-EXECUTES-001
+  severity: 2
+  disposition: advisory
+  introduced_in: 0.1.0
+  core_design_refs:
+  - afokapu/atdd#1248
+  - afokapu/atdd#1251
+implementation:
+  type: validator
+  ref: coder.bun.runtime-executes-the-declaration

package/conventions/coder.bun/coder.bun.runtime-server-is-bun-serve.convention.yaml

@@ -0,0 +1,64 @@
+schema_version: 1.1.0
+rule_id: coder.bun.runtime-server-is-bun-serve
+kind: rule
+status: active
+name: The HTTP server is Bun.serve, not a node-compat framework
+statement: >-
+  A full-stack Bun application MUST serve HTTP with `Bun.serve` and MUST NOT construct a server with
+  Express, Fastify, Koa or `node:http`/`node:https` `createServer`. `Bun.serve` is the only server in
+  this stack with access to Bun's native routing, WebSocket upgrade, streaming and `HTMLRewriter` —
+  the last of which is how htmx fragments are transformed server-side. This is the Bun-stack
+  realization of the agnostic "the application uses its runtime's native primitives rather than a
+  compatibility shim" obligation, enforced by the `bun_fullstack_detector` family implementation on
+  `atdd.workspace.bun`.
+terms:
+- term_id: foreign_server
+  text: >-
+    `express()`, `fastify(`, `new Koa(`, `http.createServer(`, `https.createServer(` or a bare
+    `createServer(` — any construction that puts a node-compat HTTP server in front of the app.
+- term_id: node_compat_path
+  text: >-
+    Bun's Node.js compatibility layer. It works, which is exactly why this drift is silent: the app
+    runs, the tests pass, and the stack has quietly become "Node with a faster interpreter".
+content:
+  summary: >-
+    A "the server is Bun.serve" obligation. The realization is a zero-dependency Bun detector that
+    scans source with strings and comments MASKED (so a framework name inside a migration note or an
+    error message never trips it) and flags any foreign server construction.
+  normative_text: |
+    This is not a taste rule, and it is the load-bearing one for the stack decision itself. Running
+    Express under Bun keeps the entire npm middleware dependency surface, forfeits the native
+    primitives, and — most consequentially — invalidates the deployment story that motivated the move:
+    `bun run server.ts`, no bundle step, no `node_modules` at runtime. Once one route is served by a
+    foreign framework, the middleware ecosystem follows it, and the migration silently stops halfway.
+    For htmx specifically the cost is concrete rather than philosophical: `HTMLRewriter` is a streaming
+    HTML transformer available only through the Bun server, and it is the natural place to assemble and
+    post-process fragments.
+  fix_hint: |
+    Replace the framework server with the native one:
+
+      const app = express();                       // ✗ node-compat path
+      app.get("/orders", (req, res) => …);
+      app.listen(3000);
+
+      Bun.serve({                                   // ✓ native
+        port: 3000,
+        routes: { "/orders": (req) => new Response(renderOrders(), htmlHeaders) },
+      });
+
+    Middleware becomes plain function composition around the handler. `strict` — the rule exists to
+    hold the stack decision, so it is not suppressible.
+  exceptions:
+  - A `createServer(` call that is not an HTTP server (a test double, an unrelated factory) is a known
+    imprecision of the name-based match; rename it or scope it out via the consumer scope map.
+  - Test files are excluded — spinning a throwaway server in a test is not an application server.
+  - Names appearing inside strings or comments are masked and never flagged.
+metadata:
+  aliases:
+  - BUN-NATIVE-SERVER-001
+  severity: 2
+  disposition: strict
+  introduced_in: 0.1.0
+implementation:
+  type: validator
+  ref: bun_fullstack_detector