@afokapu/atdd-bun 0.1.0

package/planner-schemas/train-interlocking.schema.json

@@ -0,0 +1,459 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Train Interlocking Schema",
+  "description": "Schema for a train interlocking: the train-domain route-control artifact. The interlocking YAML is authoritative for the guarded route space; each executable route maps to exactly one typed linear train. Mermaid/SVG/coverage outputs are derived projections, never sources of truth. Core validates shape only; semantic cross-checks (category/train agreement, lifeline resolution, guard-reference existence) and Station Master reachability belong to configured Bun validators.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "interlocking_id",
+    "title",
+    "theme",
+    "status",
+    "source",
+    "entrypoint",
+    "route_resolution",
+    "lifelines",
+    "messages",
+    "routes"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the interlocking schema this document targets. 1.1.0 added the required `entrypoint.surfaces` discriminator (#1818)."
+    },
+    "interlocking_id": {
+      "type": "string",
+      "pattern": "^interlocking:[a-z][a-z0-9-]*$",
+      "description": "Stable interlocking identifier: interlocking:<kebab-case-name>."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Human-readable display name for the interlocking."
+    },
+    "theme": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Kebab-case theme this interlocking belongs to (mirrors train theme semantics)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "checked", "stale"],
+      "description": "Authoring lifecycle state of the interlocking artifact."
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "content_digest"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Canonical path to this interlocking YAML relative to repo root (plan/_trains/_interlockings/<id>.yaml)."
+        },
+        "content_digest": {
+          "type": "string",
+          "description": "sha256 (hex) of the normalized interlocking content, or a placeholder during authoring."
+        }
+      }
+    },
+    "entrypoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["exposed", "actions", "reason", "surfaces"],
+      "description": "Declared reachability surface so extension validators never infer reachability from filenames. Core validates shape only; Station Master reachability is enforced in atdd-extensions#27.",
+      "properties": {
+        "exposed": {
+          "type": "boolean",
+          "description": "Whether this interlocking is reachable via a Station Master action."
+        },
+        "actions": {
+          "type": "array",
+          "description": "Station Master action names (NOT train IDs) that route into this interlocking.",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          }
+        },
+        "reason": {
+          "type": ["string", "null"],
+          "enum": [
+            null,
+            "internal-transition-only",
+            "library-only",
+            "planned-not-exposed"
+          ],
+          "description": "Required when exposed is false; must be null when exposed is true."
+        },
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "enum": ["backend", "frontend"] },
+          "description": "Which consumer surfaces read this route space. Declared, never inferred from the file's path \u2014 selecting documents by path is what corrupted a route registry in atdd-extensions. List-valued because one route space can legitimately serve both sides: a full-stack repo reads the same document from a backend and a frontend consumer, and a scalar would force a false choice. A consumer MUST skip a document whose surfaces omit its own side, which is what lets the backend and frontend paths be unified (#1818). This names which surfaces READ the route space, NOT where output is rendered: a server-resolved, browser-rendered stack such as Bun+HTMX reads it on the server and is therefore [\"backend\"]. Marking such a consumer [\"frontend\"] hands it to the Vite family and was measured at 23 false positives on a real consumer."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "exposed": { "const": true } } },
+          "then": {
+            "properties": {
+              "actions": { "minItems": 1 },
+              "reason": { "const": null }
+            }
+          }
+        },
+        {
+          "if": { "properties": { "exposed": { "const": false } } },
+          "then": {
+            "properties": {
+              "actions": { "maxItems": 0 },
+              "reason": {
+                "type": "string",
+                "enum": [
+                  "internal-transition-only",
+                  "library-only",
+                  "planned-not-exposed"
+                ]
+              }
+            }
+          }
+        }
+      ]
+    },
+    "route_resolution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy"],
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["fail_on_multiple_match", "first_priority"],
+          "description": "Explicit route-resolution strategy. No implicit order-based resolution is allowed. fail_on_multiple_match fails closed when >1 route matches; first_priority picks the lowest unique numeric priority."
+        }
+      }
+    },
+    "lifelines": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Declared participants (sequence-diagram lifelines). Message endpoints must resolve to one of these.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ref"],
+        "properties": {
+          "ref": {
+            "type": "string",
+            "pattern": "^(wagon|user|system):[a-z][a-z0-9-]*$",
+            "description": "Lifeline reference: wagon:<id>, user:<role>, or system:<source>."
+          }
+        }
+      }
+    },
+    "messages": {
+      "type": "array",
+      "description": "Declared messages between lifelines. Carries payload contract identity only, never Cargo runtime data.",
+      "items": { "$ref": "#/definitions/message" }
+    },
+    "fragments": {
+      "type": "array",
+      "description": "Combined fragments (alt/opt) carrying guarded sub-paths.",
+      "items": { "$ref": "#/definitions/fragment" }
+    },
+    "invariants": {
+      "type": "array",
+      "description": "Declarative invariants that must hold across the interlocking.",
+      "items": { "$ref": "#/definitions/invariant" }
+    },
+    "residuals": {
+      "type": "array",
+      "description": "Structural obligations that have no honest flow representation and are discharged by a named validator.",
+      "items": { "$ref": "#/definitions/residual" }
+    },
+    "routes": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Guarded routes. Each executable route maps to exactly one linear train variant whose `category` field (issue #1421) agrees with the route's declared category — no longer a matching identity digit.",
+      "items": { "$ref": "#/definitions/route" }
+    },
+    "category_assessment": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed not-applicable assessments per route category (issue #1554). Every category in the closed set must be ASSESSED: `nominal` always requires one or more routes and can never appear here, while `alternate`, `error` and `exception` are satisfied either by routes or by a typed entry here. This replaces the weaker 'at least one non-nominal route' floor, which a token alternate satisfies while error and exception behaviour go unwritten. Declaring an entry for a category that already carries routes is a contradiction, so a stale assessment cannot outlive the gap it described.",
+      "properties": {
+        "alternate": { "$ref": "#/definitions/category_assessment_entry" },
+        "error": { "$ref": "#/definitions/category_assessment_entry" },
+        "exception": { "$ref": "#/definitions/category_assessment_entry" }
+      }
+    }
+  },
+  "definitions": {
+    "category_assessment_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["basis"],
+      "description": "Why a category carries no route. The basis is drawn from a CLOSED vocabulary — a free-text reason is deliberately not accepted, since a prose escape hatch erodes as it gets copy-pasted onto every category.",
+      "properties": {
+        "basis": {
+          "type": "string",
+          "enum": ["discharged-by-residual", "outcome-cannot-arise", "not-yet-assessed"],
+          "description": "`discharged-by-residual` = the outcome exists but deliberately has no route, and the residual named by `residual_ref` accounts for it (that residual must itself carry a reason, an acceptance_ref and a validator_ref per planner.train.interlocking-structural-residual-explicit, so this discharge is bound, not free). `outcome-cannot-arise` = the category is impossible by construction. `not-yet-assessed` = TRANSITIONAL; the analysis has not been performed and `retires_with` must name the issue that will retire it."
+        },
+        "residual_ref": {
+          "type": "string",
+          "description": "The declared residual that accounts for this category. REQUIRED when basis is `discharged-by-residual` and forbidden otherwise. Must name a residual declared in this interlocking's `residuals` block."
+        },
+        "retires_with": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Issue number that will retire a `not-yet-assessed` basis. REQUIRED when basis is `not-yet-assessed` and forbidden otherwise, so an unassessed category is an owned obligation with a named retirer."
+        }
+      },
+      "allOf": [
+        {
+          "if": {"properties": {"basis": {"const": "discharged-by-residual"}}, "required": ["basis"]},
+          "then": {"required": ["residual_ref"]},
+          "else": {"not": {"required": ["residual_ref"]}}
+        },
+        {
+          "if": {"properties": {"basis": {"const": "not-yet-assessed"}}, "required": ["basis"]},
+          "then": {"required": ["retires_with"]},
+          "else": {"not": {"required": ["retires_with"]}}
+        }
+      ]
+    },
+    "participant_ref": {
+      "type": "string",
+      "pattern": "^(wagon|user|system):[a-z][a-z0-9-]*$"
+    },
+    "wmbt_ref": {
+      "type": "string",
+      "pattern": "^wmbt:[a-z][a-z0-9-]*:[DLPCEMYRK][0-9]{3}$",
+      "description": "Canonical TWO-segment WMBT obligation URN: wmbt:<wagon>:<CATEGORY><NNN> (issue #1546). This is the same grammar wmbt.schema.json and feature.schema.json enforce — the prior one-segment `^wmbt:[a-z][a-z0-9-]*$` form could never name a real WMBT and is REJECTED."
+    },
+    "wmbt_refs": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/wmbt_ref" },
+      "description": "Typed obligation references: the WMBT obligations this surface discharges. Every surface kind carries this so `planner.train.interlocking-wmbt-surface-or-residual` is expressible — before #1546 only `invariant` could name a WMBT, and it did so with a malformed grammar."
+    },
+    "residual_wmbt_refs": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/definitions/wmbt_ref" },
+      "description": "WMBT obligations this residual accounts for, for ROUTE COMPLETENESS ONLY. Same shape as wmbt_refs, deliberately a distinct definition so the weaker semantics are stated where they apply rather than as an ignored sibling of a $ref. Per the #1543 binding rule a structural residual discharges O2 (every modeled route/category has an acceptance at an appropriate phase) and NEVER O1 (every registered train has a resolvable train-level SMOKE) or O3 (every executable WMBT is SMOKE-covered by train or WMBT ownership). A residual declares that an obligation has no honest flow representation, so it asserts the route space is accounted for — never that anything executed. It is NOT SMOKE evidence and must not be counted as such."
+    },
+    "acceptance_urn": {
+      "type": "string",
+      "pattern": "^acc:[a-z0-9][a-z0-9-]*:([DLPCEMYRK][0-9]{3}-(?:UNIT|HTTP|EVENT|WS|E2E|A11Y|VIS|METRIC|JOB|DB|SEC|LOAD|SCRIPT|WIDGET|GOLDEN|BLOC|INTEGRATION|RLS|EDGE|REALTIME|STORAGE|SMOKE)-[0-9]{3}(?:-[a-z0-9-]+)?|[a-z][a-z0-9-]*)$",
+      "description": "Canonical acceptance URN, mirroring the `acc` entry of src/atdd/coach/utils/graph/urn_grammar.yaml: either a WMBT acceptance (acc:<wagon>:<WMBT-id>-<HARNESS>-<NNN>[-<slug>]) or a train acceptance (acc:<train>:<slug>). Replaces the free-slug `acceptance:<slug>` form, which resolved to nothing (issue #1546)."
+    },
+    "message": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "from", "to", "intent", "payload"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^msg:[a-z][a-z0-9-]*$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["boundary", "self", "control"],
+          "description": "boundary = between two distinct lifelines; self = a lifeline to itself; control = a control-flow note."
+        },
+        "from": { "$ref": "#/definitions/participant_ref" },
+        "to": { "$ref": "#/definitions/participant_ref" },
+        "intent": {
+          "type": "string",
+          "minLength": 5
+        },
+        "feature_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^feature:[a-z][a-z0-9-]*$"
+          }
+        },
+        "wmbt_refs": { "$ref": "#/definitions/wmbt_refs" },
+        "payload": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Payload contract identity ONLY. Never carries Cargo runtime contents or artifact_data values.",
+          "properties": {
+            "contract": {
+              "type": ["string", "null"],
+              "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9.-]*$",
+              "description": "Payload contract identity — decided ONCE for #1410: exactly TWO segments in domain:resource form (e.g. match:result), the leaf identity the full contract:<theme>:...:<resource> URN family prefixes. A third colon segment is rejected. Null when there is no payload."
+            },
+            "no_payload_reason": {
+              "type": ["string", "null"],
+              "minLength": 3,
+              "description": "Required (non-null) when contract is null."
+            }
+          },
+          "anyOf": [
+            {
+              "properties": { "contract": { "type": "string" } },
+              "required": ["contract"]
+            },
+            {
+              "properties": { "no_payload_reason": { "type": "string" } },
+              "required": ["no_payload_reason"]
+            }
+          ]
+        }
+      }
+    },
+    "fragment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "guards"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^frag:[a-z][a-z0-9-]*$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["alt", "opt"]
+        },
+        "acceptance_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^acceptance:[a-z][a-z0-9-]*$"
+          }
+        },
+        "wmbt_refs": { "$ref": "#/definitions/wmbt_refs" },
+        "guards": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/definitions/guard" }
+        }
+      }
+    },
+    "guard": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "expression"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^guard:[a-z][a-z0-9-]*$"
+        },
+        "expression": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Declarative, side-effect-free guard expression. Operators: == != < <= > >= and or not exists(field) in. No raw Python eval, no function calls except exists(), no imports/IO/mutation."
+        },
+        "wmbt_refs": { "$ref": "#/definitions/wmbt_refs" }
+      }
+    },
+    "invariant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "expression"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^inv:[a-z][a-z0-9-]*$"
+        },
+        "wmbt_ref": { "$ref": "#/definitions/wmbt_ref" },
+        "expression": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Declarative invariant expression (same grammar as guards)."
+        }
+      }
+    },
+    "residual": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "reason"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^residual:[a-z][a-z0-9-]*$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["structural", "behavioral", "temporal"]
+        },
+        "acceptance_ref": { "$ref": "#/definitions/acceptance_urn" },
+        "wmbt_refs": { "$ref": "#/definitions/residual_wmbt_refs" },
+        "validator_ref": {
+          "type": "string",
+          "description": "Path to the validator that discharges this residual obligation."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 5
+        }
+      }
+    },
+    "route": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "route_id",
+        "category",
+        "priority",
+        "guard_ref",
+        "train_id",
+        "train_path",
+        "projection"
+      ],
+      "properties": {
+        "route_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["nominal", "error", "alternate", "exception"],
+          "description": "The route's variant classification. Judged by comparing it against the `category` FIELD of the target train (planner.train.interlocking-route-category-matches-train-id) — never against a digit parsed out of the identity. The `category_digit` key it replaced is RETIRED (issues #1421, #1440) and is now rejected outright."
+        },
+        "priority": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Numeric priority. Under first_priority resolution, priorities must be unique."
+        },
+        "guard_ref": {
+          "type": "string",
+          "pattern": "^guard:[a-z][a-z0-9-]*$",
+          "description": "Reference to a guard declared in fragments[].guards[]."
+        },
+        "train_id": {
+          "type": "string",
+          "pattern": "^train:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+          "description": "Target linear train this route selects: train:<subject>:<slug>."
+        },
+        "train_path": {
+          "type": "string",
+          "description": "Canonical path to the target train YAML (plan/_trains/<train_id>.yaml)."
+        },
+        "projection": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["expected_sequence_digest"],
+          "properties": {
+            "expected_sequence_digest": {
+              "type": "string",
+              "description": "sha256 (hex) of the normalized route projection (the target train's linear sequence over the projected fields)."
+            },
+            "fields": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["step", "intent", "from", "to", "artifact"]
+              },
+              "description": "Ordered projection fields. Defaults to [step, intent, from, to, artifact] when omitted."
+            }
+          }
+        }
+      }
+    }
+  }
+}