@afokapu/atdd-bun 0.1.0

package/src/planner-kernel.ts

@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+export type PlanKind = "wagon" | "feature" | "wmbt" | "acceptance" | "train" | "interlocking" | "journey" | "contract";
+export type PlanFinding = { rule_id: string; file: string; evidence: string };
+export type PlanArtifact = { kind: PlanKind; id: string; file: string; data: Record<string, unknown> };
+export type PlanGraph = { artifacts: PlanArtifact[]; findings: PlanFinding[] };
+
+const typedKinds: Record<string, PlanKind> = { wagon: "wagon", feature: "feature", wmbt: "wmbt", acc: "acceptance", train: "train", interlocking: "interlocking", journey: "journey", contract: "contract" };
+const id = (value: unknown) => typeof value === "string" ? value : "";
+const finding = (rule_id: string, file: string, evidence: string): PlanFinding => ({ rule_id, file, evidence });
+
+async function walk(root: string): Promise<string[]> {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  return (await Promise.all(entries.map(async entry => {
+    const path = join(root, entry.name);
+    return entry.isDirectory() ? walk(path) : entry.isFile() && /\.(?:yaml|yml|json)$/.test(entry.name) ? [path] : [];
+  }))).flat().sort();
+}
+
+function kindOf(data: Record<string, unknown>, path: string): PlanKind | null {
+  if (id(data.journey_id)) return "journey";
+  if (id(data.interlocking_id)) return "interlocking";
+  const urn = id(data.urn); if (urn) { const prefix = urn.split(":", 1)[0]; return typedKinds[prefix] ?? null; }
+  if (id(data.train_id)) return "train";
+  if (Array.isArray(data.participants) && Array.isArray(data.routes)) return "interlocking";
+  if ("wagon" in data) return "wagon";
+  if ("$id" in data && id(data.$id).startsWith("contract:")) return "contract";
+  return null;
+}
+
+function artifactId(kind: PlanKind, data: Record<string, unknown>): string {
+  if (kind === "wagon") return id(data.urn) || (id(data.wagon) ? `wagon:${id(data.wagon)}` : "");
+  if (kind === "train") return id(data.train_id) || id(data.urn);
+  if (kind === "contract") return id(data.$id);
+  if (kind === "interlocking") return id(data.interlocking_id);
+  if (kind === "journey") return id(data.journey_id);
+  return id(data.urn) || id(data.id);
+}
+
+function values(value: unknown): unknown[] { return Array.isArray(value) ? value : value && typeof value === "object" ? Object.values(value as Record<string, unknown>) : []; }
+function typedRefs(value: unknown): string[] {
+  if (typeof value === "string") return [...value.matchAll(/\b(?:wagon|feature|wmbt|acc|train|interlocking|journey|contract):[a-z][a-z0-9-]*(?::[A-Za-z0-9._-]+)*/g)].map(match => match[0]);
+  if (!value || typeof value !== "object") return [];
+  return Object.values(value as Record<string, unknown>).flatMap(typedRefs);
+}
+
+function structuralRefs(artifact: PlanArtifact): string[] {
+  const data = artifact.data, out: string[] = [];
+  const add = (value: unknown) => { if (typeof value === "string" && /^(?:wagon|feature|wmbt|acc|train|interlocking|journey|contract):/.test(value)) out.push(value); };
+  if (artifact.kind === "wagon") for (const feature of values(data.features)) add(feature && typeof feature === "object" ? (feature as Record<string, unknown>).urn : feature);
+  if (artifact.kind === "feature") { add(data.wagon); for (const wmbt of values(data.wmbts)) add(wmbt); }
+  if (artifact.kind === "train") { const source = data.source_interlocking; if (source && typeof source === "object") add((source as Record<string, unknown>).interlocking_id); for (const participant of values(data.participants)) add(participant); for (const step of values(data.sequence)) if (step && typeof step === "object") { add((step as Record<string, unknown>).from); add((step as Record<string, unknown>).to); } }
+  if (artifact.kind === "interlocking") { for (const life of values(data.lifelines)) add(life && typeof life === "object" ? (life as Record<string, unknown>).ref : life); for (const message of values(data.messages)) if (message && typeof message === "object") { const record = message as Record<string, unknown>; add(record.from); add(record.to); for (const wmbt of values(record.wmbt_refs)) add(wmbt); } for (const route of values(data.routes)) if (route && typeof route === "object") add((route as Record<string, unknown>).train_id); }
+  if (artifact.kind === "journey") {
+    const entrypoint = data.entrypoint; if (entrypoint && typeof entrypoint === "object") add((entrypoint as Record<string, unknown>).interlocking_id);
+    for (const continuation of values(data.continuations)) if (continuation && typeof continuation === "object") { const record = continuation as Record<string, unknown>; const from = record.from, to = record.to; if (from && typeof from === "object") add((from as Record<string, unknown>).interlocking_id); if (to && typeof to === "object") add((to as Record<string, unknown>).interlocking_id); }
+    for (const terminal of values(data.terminals)) if (terminal && typeof terminal === "object") { const from = (terminal as Record<string, unknown>).from; if (from && typeof from === "object") add((from as Record<string, unknown>).interlocking_id); }
+  }
+  return out;
+}
+
+/** Load plan artifacts with Bun's native YAML parser. It is read-only and deliberately
+ * excludes authoring/session/store behavior from ATDD core. */
+export async function loadPlan(root = process.cwd()): Promise<PlanGraph> {
+  const absolute = resolve(root), plan = join(absolute, "plan"), artifacts: PlanArtifact[] = [], findings: PlanFinding[] = [];
+  for (const path of await walk(plan)) {
+    const file = relative(absolute, path).replaceAll("\\", "/");
+    try {
+      const text = await readFile(path, "utf8"); const data = path.endsWith(".json") ? JSON.parse(text) : Bun.YAML.parse(text);
+      if (!data || typeof data !== "object" || Array.isArray(data)) continue;
+      const record = data as Record<string, unknown>, kind = kindOf(record, file); if (!kind) continue;
+      const artifact = artifactId(kind, record); if (!artifact) { findings.push(finding("planner.kernel.identity-required", file, `${kind} artifact has no canonical identity`)); continue; }
+      artifacts.push({ kind, id: artifact, file, data: record });
+      if (kind === "wmbt") for (const acceptance of values(record.acceptances)) {
+        if (!acceptance || typeof acceptance !== "object") { findings.push(finding("planner.kernel.acceptance-well-formed", file, "acceptance must be an object")); continue; }
+        const identity = (acceptance as { identity?: { urn?: unknown } }).identity; const acceptanceId = identity && typeof identity === "object" ? id((identity as { urn?: unknown }).urn) : "";
+        if (!acceptanceId.startsWith("acc:")) findings.push(finding("planner.kernel.acceptance-well-formed", file, "embedded acceptance has no acc: identity.urn"));
+        else artifacts.push({ kind: "acceptance", id: acceptanceId, file, data: acceptance as Record<string, unknown> });
+      }
+    } catch (error) { findings.push(finding("planner.kernel.parse", file, `could not parse artifact: ${String(error)}`)); }
+  }
+  return { artifacts, findings };
+}
+
+/** Validate the closed artifact graph: identity uniqueness, typed references, train
+ * wagon members, interlocking participants/routes, journey topology references, and WMBT acceptance ownership. */
+export async function validatePlan(root = process.cwd()): Promise<PlanGraph> {
+  const graph = await loadPlan(root), byId = new Map<string, PlanArtifact[]>();
+  for (const artifact of graph.artifacts) byId.set(artifact.id, [...(byId.get(artifact.id) ?? []), artifact]);
+  for (const [artifact, owners] of byId) if (owners.length > 1) graph.findings.push(finding("planner.kernel.identity-unique", owners[0].file, `${artifact} is declared by ${owners.map(owner => owner.file).join(", ")}`));
+  const known = new Set(byId.keys());
+  for (const artifact of graph.artifacts) {
+    const references = structuralRefs(artifact);
+    for (const reference of new Set(references)) if (!known.has(reference) && !reference.startsWith("contract:")) graph.findings.push(finding("planner.kernel.reference-resolves", artifact.file, `${artifact.id} references undeclared ${reference}`));
+    if (artifact.kind === "train") for (const wagon of values(artifact.data.wagons)) { const reference = `wagon:${id(wagon)}`; if (id(wagon) && !known.has(reference)) graph.findings.push(finding("planner.kernel.train-wagon-resolves", artifact.file, `${artifact.id} lists undeclared ${reference}`)); }
+    if (artifact.kind === "interlocking") for (const participant of [...values(artifact.data.participants), ...values(artifact.data.lifelines).map(value => value && typeof value === "object" ? (value as Record<string, unknown>).ref : value)]) { const reference = id(participant); if (reference.startsWith("wagon:") && !known.has(reference)) graph.findings.push(finding("planner.kernel.interlocking-participant-resolves", artifact.file, `${artifact.id} lists undeclared ${reference}`)); }
+  }
+  return graph;
+}
+
+export function traceabilityPlan(graph: PlanGraph): Array<{ from: string; to: string; relation: string }> {
+  const links: Array<{ from: string; to: string; relation: string }> = [];
+  for (const artifact of graph.artifacts) {
+    if (artifact.kind === "wmbt") for (const acceptance of graph.artifacts.filter(other => other.kind === "acceptance" && other.file === artifact.file)) links.push({ from: artifact.id, to: acceptance.id, relation: "defines" });
+    for (const reference of new Set(structuralRefs(artifact))) links.push({ from: artifact.id, to: reference, relation: "references" });
+    if (artifact.kind === "train") for (const wagon of values(artifact.data.wagons)) if (id(wagon)) links.push({ from: artifact.id, to: `wagon:${id(wagon)}`, relation: "orders" });
+  }
+  return links;
+}

package/src/planner-schema-validator.ts

@@ -0,0 +1,101 @@
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
+import addFormats from "ajv-formats";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { loadPlan, type PlanArtifact, type PlanFinding } from "./planner-kernel";
+
+type SchemaKind = Extract<PlanArtifact["kind"], "wagon" | "feature" | "wmbt" | "train" | "interlocking" | "journey">;
+
+const schemaFiles: Record<SchemaKind, string> = {
+  wagon: "wagon.schema.json",
+  feature: "feature.schema.json",
+  wmbt: "wmbt.schema.json",
+  train: "train.schema.json",
+  interlocking: "train-interlocking.schema.json",
+  journey: "journey.schema.json",
+};
+const supportingSchemaFiles = ["appendix.schema.json", "acceptance.schema.json"];
+const repositorySchemas = [
+  { file: "plan/_themes.yaml", schema: "theme-registry.schema.json", rule: "planner.theme.must-be-canonical" },
+  { file: "contracts/_contracts.yaml", schema: "contract-registry.schema.json", rule: "planner.contract.registry-coherence" },
+] as const;
+const schemaDirectory = join(resolve(import.meta.dir, ".."), "planner-schemas");
+const ruleId = "atdd-bun.planner.schema";
+
+function ruleFor(kind: SchemaKind, error: ErrorObject): string {
+  if (error.keyword === "pattern" && (
+    (kind === "train" && error.instancePath === "/train_id") ||
+    (kind === "interlocking" && /^\/routes\/\d+\/train_id$/.test(error.instancePath))
+  )) return "planner.train.naming";
+  return ruleId;
+}
+
+function formatError(error: ErrorObject): string {
+  const at = error.instancePath || "/";
+  return at + " " + (error.message ?? error.keyword);
+}
+
+async function validators(): Promise<{ artifacts: Map<SchemaKind, ValidateFunction>; repositories: Map<string, ValidateFunction> }> {
+  const ajv = new Ajv({ allErrors: true, allowUnionTypes: true, strict: false });
+  addFormats(ajv);
+  const files = [...supportingSchemaFiles, ...Object.values(schemaFiles), ...repositorySchemas.map(item => item.schema)];
+  for (const file of files) ajv.addSchema(JSON.parse(await readFile(join(schemaDirectory, file), "utf8")), file);
+  const artifacts = new Map(Object.entries(schemaFiles).map(([kind, file]) => {
+    const validator = ajv.getSchema(file);
+    if (!validator) throw new Error("could not compile planner schema " + file);
+    return [kind as SchemaKind, validator];
+  }));
+  const repositories = new Map(repositorySchemas.map(item => {
+    const validator = ajv.getSchema(item.schema);
+    if (!validator) throw new Error("could not compile planner schema " + item.schema);
+    return [item.schema, validator];
+  }));
+  return { artifacts, repositories };
+}
+
+function repositoryRule(file: string, fallback: string, error: ErrorObject): string {
+  if (file === "plan/_themes.yaml" && (error.instancePath === "/themes" || error.instancePath === "/themes/0" || error.params.missingProperty === "0")) {
+    return "planner.theme.theme-zero-mandatory";
+  }
+  return fallback;
+}
+
+/** Validate every recognized plan artifact against the package-shipped canonical
+ * JSON Schema. Cross-artifact relationships remain planner validator concerns. */
+export async function validatePlannerSchemas(root = process.cwd()): Promise<PlanFinding[]> {
+  const absolute = resolve(root), graph = await loadPlan(absolute);
+  const byKind = await validators();
+  const findings: PlanFinding[] = [];
+  for (const artifact of graph.artifacts) {
+    if (!(artifact.kind in schemaFiles)) continue;
+    const kind = artifact.kind as SchemaKind, validator = byKind.artifacts.get(kind);
+    if (!validator) continue;
+    if (!validator(artifact.data)) {
+      for (const error of validator.errors ?? []) findings.push({
+        rule_id: ruleFor(kind, error),
+        file: artifact.file,
+        evidence: kind + " violates " + schemaFiles[kind] + ": " + formatError(error),
+      });
+    }
+  }
+  for (const item of repositorySchemas) {
+    const path = join(absolute, item.file);
+    if (!existsSync(path)) continue;
+    try {
+      const data = Bun.YAML.parse(await readFile(path, "utf8"));
+      const repositoryValidator = byKind.repositories.get(item.schema);
+      if (!repositoryValidator) throw new Error("could not compile planner schema " + item.schema);
+      if (!repositoryValidator(data)) for (const error of repositoryValidator.errors ?? []) findings.push({
+        rule_id: repositoryRule(item.file, item.rule, error),
+        file: item.file,
+        evidence: item.file + " violates " + item.schema + ": " + formatError(error),
+      });
+    } catch (error) {
+      findings.push({ rule_id: item.rule, file: item.file, evidence: `could not parse ${item.file}: ${String(error)}` });
+    }
+  }
+  return findings;
+}
+
+export { ruleId as PLANNER_SCHEMA_RULE_ID };

package/src/planner-validators.ts

@@ -0,0 +1,288 @@
+import { validatePlan, type PlanArtifact, type PlanFinding } from "./planner-kernel";
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+const finding = (rule_id: string, file: string, evidence: string): PlanFinding => ({ rule_id, file, evidence });
+const records = (value: unknown): Record<string, unknown>[] => Array.isArray(value) ? value.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object") : [];
+const text = (value: unknown): string => typeof value === "string" ? value : "";
+const duplicate = (values: string[]) => [...new Set(values.filter((value, index) => value && values.indexOf(value) !== index))];
+const contractIdentity = (value: string) => value.startsWith("contract:") ? value.slice("contract:".length) : value;
+
+async function yamlFiles(root: string): Promise<string[]> {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  return (await Promise.all(entries.map(async entry => entry.isDirectory() ? yamlFiles(join(root, entry.name)) : entry.isFile() && entry.name.endsWith(".yaml") ? [join(root, entry.name)] : []))).flat().sort();
+}
+
+async function trainRegistryFindings(root: string): Promise<PlanFinding[]> {
+  const absolute = resolve(root), registryPath = join(absolute, "plan/_trains.yaml"); if (!existsSync(registryPath)) return [];
+  const registry = Bun.YAML.parse(await readFile(registryPath, "utf8")) as { trains?: Record<string, Record<string, unknown[]>> };
+  const rows = Object.values(registry?.trains ?? {}).flatMap(buckets => Object.values(buckets ?? {}).flat()).filter((row): row is Record<string, unknown> => Boolean(row) && typeof row === "object");
+  const registered = new Set<string>(), findings: PlanFinding[] = [];
+  for (const row of rows) { const path = text(row.path), train = text(row.train_id); if (!path || !train) continue; registered.add(path); if (!existsSync(join(absolute, path))) findings.push(finding("planner.train.registry-coherence", "plan/_trains.yaml", `registry train ${train} points to missing ${path}`)); }
+  const trainRoot = join(absolute, "plan/_trains");
+  for (const path of await yamlFiles(trainRoot)) { const rel = relative(absolute, path).replaceAll("\\", "/"), pieces = relative(trainRoot, path).split(/[\\/]/); if (pieces.some(piece => piece.startsWith("_")) || registered.has(rel)) continue; findings.push(finding("planner.train.registry-coherence", rel, `train document is not registered in plan/_trains.yaml`)); }
+  return findings;
+}
+
+type ContractRegistry = { identities: Set<string>; rows: Record<string, unknown>[]; file: string };
+
+async function contractRegistry(root: string): Promise<ContractRegistry | null> {
+  const file = "contracts/_contracts.yaml", path = join(resolve(root), file);
+  if (!existsSync(path)) return null;
+  try {
+    const data = Bun.YAML.parse(await readFile(path, "utf8")) as { contracts?: unknown };
+    const source = data?.contracts;
+    const rows = Array.isArray(source) ? records(source) : source && typeof source === "object"
+      ? Object.entries(source as Record<string, unknown>).flatMap(([identity, entry]) => entry && typeof entry === "object" && !Array.isArray(entry) ? [{ ...(entry as Record<string, unknown>), identity: text((entry as Record<string, unknown>).identity) || identity }] : [])
+      : [];
+    return { identities: new Set(rows.map(row => text(row.identity)).filter(Boolean)), rows, file };
+  } catch {
+    return null;
+  }
+}
+
+async function themeRegistryFindings(root: string, graph: Awaited<ReturnType<typeof validatePlan>>, registry: ContractRegistry | null): Promise<PlanFinding[]> {
+  const absolute = resolve(root), file = "plan/_themes.yaml", path = join(absolute, file);
+  const declared: Array<{ theme: string; file: string }> = [];
+  for (const artifact of graph.artifacts) {
+    if (artifact.kind === "wagon" || artifact.kind === "interlocking") {
+      const theme = text(artifact.data.theme); if (theme) declared.push({ theme, file: artifact.file });
+    } else if (artifact.kind === "train") {
+      for (const theme of Array.isArray(artifact.data.themes) ? artifact.data.themes.map(text) : []) if (theme) declared.push({ theme, file: artifact.file });
+    }
+  }
+  for (const row of registry?.rows ?? []) { const theme = text(row.theme); if (theme) declared.push({ theme, file: registry?.file ?? file }); }
+  if (!existsSync(path)) return declared.length ? [finding("planner.theme.must-be-canonical", file, "themes are declared but plan/_themes.yaml is absent; add themes: { '0': commons } and repository-defined entries")] : [];
+  try {
+    const doc = Bun.YAML.parse(await readFile(path, "utf8")) as { themes?: unknown };
+    const themes = doc?.themes && typeof doc.themes === "object" && !Array.isArray(doc.themes) ? doc.themes as Record<string, unknown> : {};
+    const values = Object.values(themes).map(text).filter(Boolean);
+    const findings: PlanFinding[] = [];
+    if (themes["0"] !== "commons") findings.push(finding("planner.theme.theme-zero-mandatory", file, "theme index 0 must be the reserved token commons"));
+    for (const name of duplicate(values)) findings.push(finding("planner.theme.must-be-canonical", file, `theme ${name} is declared at more than one index`));
+    const known = new Set(values);
+    for (const item of declared) if (!known.has(item.theme)) findings.push(finding("planner.theme.must-be-canonical", item.file, `theme ${item.theme} is not declared in plan/_themes.yaml`));
+    for (const artifact of graph.artifacts.filter(item => item.kind === "wagon")) {
+      const wagonTheme = text(artifact.data.theme);
+      for (const produced of records(artifact.data.produce)) {
+        const identities = [text(produced.name), text(produced.contract).replace(/^contract:/, ""), text(produced.telemetry).replace(/^telemetry:/, "")].filter(Boolean);
+        for (const identity of identities) {
+          const namespace = identity.split(":", 1)[0];
+          if (!known.has(namespace)) findings.push(finding("planner.artifact-naming.theme-first-identity", artifact.file, `artifact ${identity} begins with undeclared theme ${namespace}`));
+          if (wagonTheme && namespace !== wagonTheme) findings.push(finding("planner.theme.urn-namespace-matches", artifact.file, `artifact ${identity} begins with ${namespace}, but wagon ${text(artifact.data.wagon)} declares theme ${wagonTheme}`));
+        }
+      }
+      for (const consumed of records(artifact.data.consume)) {
+        const identity = text(consumed.name); if (!identity) continue;
+        const namespace = identity.split(":", 1)[0];
+        if (!known.has(namespace)) findings.push(finding("planner.artifact-naming.theme-first-identity", artifact.file, `artifact ${identity} begins with undeclared theme ${namespace}`));
+      }
+    }
+    return findings;
+  } catch {
+    return [finding("planner.theme.must-be-canonical", file, "could not parse plan/_themes.yaml")];
+  }
+}
+
+function contractRegistryFindings(root: string, wagons: PlanArtifact[], registry: ContractRegistry | null): PlanFinding[] {
+  const findings: PlanFinding[] = [], byName = new Map<string, string[]>();
+  for (const wagon of wagons) for (const item of records(wagon.data.consume)) {
+    const name = text(item.name); if (name) byName.set(name, [...(byName.get(name) ?? []), text(wagon.data.wagon)]);
+  }
+  const references: Array<{ contract: string; kind: "produce" | "consume"; name: string; wagon: PlanArtifact; item: Record<string, unknown> }> = [];
+  for (const wagon of wagons) for (const kind of ["produce", "consume"] as const) for (const item of records(wagon.data[kind])) {
+    const contract = text(item.contract), name = text(item.name);
+    if (contract) references.push({ contract, kind, name, wagon, item });
+  }
+  if (references.length && !registry) {
+    for (const reference of references) findings.push(finding("planner.contract.registry-coherence", reference.wagon.file, `${reference.kind} ${reference.name} references ${reference.contract}, but contracts/_contracts.yaml is absent`));
+    return findings;
+  }
+  const registered = registry?.identities ?? new Set<string>();
+  const duplicateIdentities = duplicate((registry?.rows ?? []).map(row => text(row.identity)));
+  for (const identity of duplicateIdentities) findings.push(finding("planner.contract.registry-coherence", registry?.file ?? "contracts/_contracts.yaml", `contract identity ${identity} is declared more than once`));
+  for (const reference of references) if (reference.contract.startsWith("contract:") && !registered.has(contractIdentity(reference.contract))) {
+    findings.push(finding("planner.contract.registry-coherence", reference.wagon.file, `${reference.kind} ${reference.name} references unregistered contract ${reference.contract}`));
+  }
+  for (const row of registry?.rows ?? []) {
+    const identity = text(row.identity), theme = text(row.theme), expected = identity.split(":", 1)[0];
+    if (identity && theme && theme !== expected) findings.push(finding("planner.contract.registry-coherence", registry.file, `contract ${identity} declares theme ${theme}; its identity namespace is ${expected}`));
+    const path = text(row.path); if (path && !existsSync(join(resolve(root), path))) findings.push(finding("planner.contract.registry-coherence", registry.file, `contract ${identity} points to missing ${path}`));
+  }
+  for (const wagon of wagons) for (const produced of records(wagon.data.produce)) {
+    const name = text(produced.name), contract = text(produced.contract), producer = text(wagon.data.wagon);
+    const consumers = (byName.get(name) ?? []).filter(consumer => consumer && consumer !== producer);
+    if (consumers.length && !contract) findings.push(finding("planner.contract.registry-coherence", wagon.file, `produce ${name} has contract null but is consumed cross-wagon by ${consumers.sort().join(", ")}`));
+    if (contract && !consumers.length && text(produced.to || "external") !== "external") findings.push(finding("planner.contract.registry-coherence", wagon.file, `produce ${name} declares ${contract} but has no cross-wagon consumer and is not marked to: external`));
+  }
+  return findings;
+}
+
+
+type JourneyClaim = {
+  kind: "continuation" | "terminal";
+  interlockingId: string;
+  routeId: string;
+  artifact: string;
+  destination: string;
+};
+
+function journeyContinuationFindings(graph: Awaited<ReturnType<typeof validatePlan>>): PlanFinding[] {
+  const interlockings = new Map(graph.artifacts.filter(item => item.kind === "interlocking").map(item => [item.id, item]));
+  const trains = new Map(graph.artifacts.filter(item => item.kind === "train").map(item => [item.id, item]));
+  const findings: PlanFinding[] = [];
+
+  for (const journey of graph.artifacts.filter(item => item.kind === "journey")) {
+    const entrypoint = journey.data.entrypoint && typeof journey.data.entrypoint === "object" ? journey.data.entrypoint as Record<string, unknown> : {};
+    const root = text(entrypoint.interlocking_id);
+    const claims: JourneyClaim[] = [];
+
+    for (const continuation of records(journey.data.continuations)) {
+      const from = continuation.from && typeof continuation.from === "object" ? continuation.from as Record<string, unknown> : {};
+      const to = continuation.to && typeof continuation.to === "object" ? continuation.to as Record<string, unknown> : {};
+      claims.push({
+        kind: "continuation",
+        interlockingId: text(from.interlocking_id),
+        routeId: text(from.route_id),
+        artifact: text(continuation.artifact),
+        destination: text(to.interlocking_id),
+      });
+    }
+    for (const terminal of records(journey.data.terminals)) {
+      const from = terminal.from && typeof terminal.from === "object" ? terminal.from as Record<string, unknown> : {};
+      claims.push({
+        kind: "terminal",
+        interlockingId: text(from.interlocking_id),
+        routeId: text(from.route_id),
+        artifact: "",
+        destination: "",
+      });
+    }
+
+    const claimsByRoute = new Map<string, JourneyClaim[]>();
+    for (const claim of claims) {
+      const key = `${claim.interlockingId}#${claim.routeId}`;
+      claimsByRoute.set(key, [...(claimsByRoute.get(key) ?? []), claim]);
+      const source = interlockings.get(claim.interlockingId);
+      if (!source) {
+        findings.push(finding("planner.journey.continuation-closure", journey.file, `${journey.id} ${claim.kind} source interlocking ${claim.interlockingId || "<missing>"} does not exist`));
+        continue;
+      }
+      const route = records(source.data.routes).find(row => text(row.route_id) === claim.routeId);
+      if (!route) {
+        findings.push(finding("planner.journey.continuation-closure", journey.file, `${journey.id} ${claim.kind} references missing route ${claim.interlockingId}#${claim.routeId || "<missing>"}`));
+        continue;
+      }
+      if (claim.kind === "continuation") {
+        const selectedTrain = text(route.train_id), train = trains.get(selectedTrain);
+        const artifacts = train ? records(train.data.sequence).map(step => text(step.artifact)).filter(Boolean) : [];
+        if (train && claim.artifact && !artifacts.includes(claim.artifact)) findings.push(finding(
+          "planner.journey.continuation-closure",
+          journey.file,
+          `${journey.id} continuation ${claim.interlockingId}#${claim.routeId} waits for ${claim.artifact}, but selected train ${selectedTrain} declares [${artifacts.join(", ")}]`,
+        ));
+        if (claim.destination && !interlockings.has(claim.destination)) findings.push(finding(
+          "planner.journey.continuation-closure",
+          journey.file,
+          `${journey.id} continuation ${claim.interlockingId}#${claim.routeId} targets missing ${claim.destination}`,
+        ));
+      }
+    }
+
+    const reachable = new Set<string>(), queue = root ? [root] : [];
+    while (queue.length) {
+      const interlockingId = queue.shift()!;
+      if (reachable.has(interlockingId)) continue;
+      const interlocking = interlockings.get(interlockingId);
+      if (!interlocking) continue;
+      reachable.add(interlockingId);
+      const routeRows = records(interlocking.data.routes);
+      for (const routeId of duplicate(routeRows.map(route => text(route.route_id)))) findings.push(finding(
+        "planner.journey.continuation-closure",
+        journey.file,
+        `${journey.id} cannot key topology through ${interlockingId}: duplicate route_id ${routeId}`,
+      ));
+      for (const route of routeRows) {
+        const routeId = text(route.route_id), key = `${interlockingId}#${routeId}`, outgoing = claimsByRoute.get(key) ?? [];
+        if (outgoing.length !== 1) findings.push(finding(
+          "planner.journey.continuation-closure",
+          journey.file,
+          `${journey.id} reachable route ${key} must have exactly one continuation or terminal; found ${outgoing.length}`,
+        ));
+        for (const edge of outgoing) if (edge.kind === "continuation" && interlockings.has(edge.destination)) queue.push(edge.destination);
+      }
+    }
+
+    for (const claim of claims) if (claim.interlockingId && interlockings.has(claim.interlockingId) && !reachable.has(claim.interlockingId)) findings.push(finding(
+      "planner.journey.continuation-closure",
+      journey.file,
+      `${journey.id} declares ${claim.kind} from unreachable ${claim.interlockingId}#${claim.routeId}`,
+    ));
+
+    const adjacency = new Map<string, Set<string>>();
+    for (const claim of claims) if (claim.kind === "continuation" && reachable.has(claim.interlockingId) && reachable.has(claim.destination)) {
+      adjacency.set(claim.interlockingId, new Set([...(adjacency.get(claim.interlockingId) ?? []), claim.destination]));
+    }
+    const visiting = new Set<string>(), visited = new Set<string>();
+    let cycle: string[] | null = null;
+    const visit = (node: string, path: string[]): void => {
+      if (cycle || visited.has(node)) return;
+      if (visiting.has(node)) { const start = path.indexOf(node); cycle = [...path.slice(start), node]; return; }
+      visiting.add(node);
+      for (const next of adjacency.get(node) ?? []) visit(next, [...path, node]);
+      visiting.delete(node);
+      visited.add(node);
+    };
+    if (root) visit(root, []);
+    if (cycle) findings.push(finding(
+      "planner.journey.continuation-closure",
+      journey.file,
+      `${journey.id} contains a continuation cycle ${cycle.join(" -> ")}; journey topology is acyclic until explicit loop semantics exist`,
+    ));
+  }
+
+  return findings;
+}
+
+/** Bun realization of the planner validators that depend only on committed plan
+ * artifacts. Runtime/session/GitHub validators deliberately stay outside this package. */
+export async function validateStaticPlannerConventions(root = process.cwd()): Promise<PlanFinding[]> {
+  // Plan-graph integrity is a package guard with its own implementation contract.
+  // This validator emits only the canonical convention ids declared by
+  // planner.static.validators.bun.
+  const graph = await validatePlan(root), findings: PlanFinding[] = [], wagons = graph.artifacts.filter(artifact => artifact.kind === "wagon");
+  const wagonSlugs = new Set(wagons.map(wagon => text(wagon.data.wagon)));
+  const wagonBySlug = new Map(wagons.map(wagon => [text(wagon.data.wagon), wagon]));
+  const wagonIds = wagons.map(wagon => text(wagon.data.wagon));
+  for (const slug of duplicate(wagonIds)) findings.push(finding("planner.wagon.urn", wagonBySlug.get(slug)?.file ?? "plan/", `wagon slug ${slug} is declared more than once`));
+
+  const contractOwners = new Map<string, string[]>(), telemetryOwners = new Map<string, string[]>();
+  for (const wagon of wagons) {
+    const slug = text(wagon.data.wagon), expected = `wagon:${slug}`;
+    if (!slug || wagon.id !== expected) findings.push(finding("planner.wagon.urn-naming", wagon.file, `wagon identity must be ${expected}`));
+    const produced = records(wagon.data.produce), consumed = records(wagon.data.consume);
+    for (const name of duplicate(produced.map(item => text(item.name)))) findings.push(finding("planner.wagon.produce-consume-artifacts", wagon.file, `${expected} produces ${name} more than once`));
+    for (const feature of duplicate(records(wagon.data.features).map(item => text(item.urn)))) findings.push(finding("planner.wagon.features", wagon.file, `${expected} lists feature ${feature} more than once`));
+    for (const item of produced) {
+      const contract = text(item.contract), telemetry = item.telemetry; if (contract) contractOwners.set(contract, [...(contractOwners.get(contract) ?? []), slug]);
+      for (const value of Array.isArray(telemetry) ? telemetry.map(text) : [text(telemetry)]) if (value) telemetryOwners.set(value, [...(telemetryOwners.get(value) ?? []), slug]);
+      const to = text(item.to || "external"); if (to !== "external" && to !== "internal" && (!to.startsWith("wagon:") || !wagonSlugs.has(to.slice(6)))) findings.push(finding("planner.wagon.produce-consume-artifacts", wagon.file, `${expected} produces to invalid destination ${to}`));
+    }
+    for (const item of consumed) {
+      const from = text(item.from); if (!from) continue;
+      if (from.startsWith("wagon:")) { const target = from.slice(6); if (!wagonSlugs.has(target)) findings.push(finding("planner.wagon.produce-consume-artifacts", wagon.file, `${expected} consumes from unknown ${from}`)); else if (target === slug) findings.push(finding("planner.wagon.no-consume-cycle", wagon.file, `${expected} consumes from itself`)); }
+      else if (!from.startsWith("system:") && !from.startsWith("appendix:") && from !== "internal") findings.push(finding("planner.wagon.produce-consume-artifacts", wagon.file, `${expected} has invalid consume source ${from}`));
+    }
+  }
+  const registry = await contractRegistry(root);
+  for (const [contract, owners] of contractOwners) if (owners.length > 1) findings.push(finding("planner.contract.registry-coherence", wagonBySlug.get(owners[0])?.file ?? "plan/", `contract ${contract} is produced by ${owners.join(", ")}`));
+  for (const [telemetry, owners] of telemetryOwners) if (owners.length > 1) findings.push(finding("planner.wagon.telemetry-filesystem", wagonBySlug.get(owners[0])?.file ?? "plan/", `telemetry ${telemetry} is produced by ${owners.join(", ")}`));
+  findings.push(...contractRegistryFindings(root, wagons, registry));
+  findings.push(...await themeRegistryFindings(root, graph, registry));
+  findings.push(...await trainRegistryFindings(root));
+  findings.push(...journeyContinuationFindings(graph));
+
+  return findings;
+}

package/src/register.ts

@@ -0,0 +1,8 @@
+import { expect, test } from "bun:test";
+import { enforce, type EnforcementConfig } from "./enforce";
+
+export function registerEnforcementTest(config: EnforcementConfig = {}): void {
+  test("ATDD Bun enforcement", async () => {
+    expect(await enforce(config)).toEqual([]);
+  });
+}

package/src/release.ts

@@ -0,0 +1,9 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+type Release = { enabled?: boolean; version_source?: string; tag_prefix?: string; require_release_intent?: boolean; release_intent_paths?: string[]; publish_sdk?: boolean };
+const git = async (root: string, args: string[]) => { const child = Bun.spawn({ cmd: ["git", ...args], cwd: root, stdout: "pipe", stderr: "pipe" }); return { code: await child.exited, out: (await new Response(child.stdout).text()).trim() }; };
+const semver = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const cmp = (a: string, b: string) => a.split("-")[0].split(".").map(Number).reduce((r, n, i) => r || Math.sign(n - Number(b.split("-")[0].split(".")[i])), 0);
+async function intentFiles(root: string, folders: string[]) { const files: string[] = []; for (const folder of folders.map(path => path.replace("/**", ""))) { const path = join(root, folder); if (!existsSync(path)) continue; for (const entry of await readdir(path, { withFileTypes: true })) if (entry.isFile()) files.push(join(path, entry.name)); } return files; }
+export async function releaseCheck(root = process.cwd()) { const config = existsSync(join(root, "atdd-bun.yaml")) ? Bun.YAML.parse(await readFile(join(root, "atdd-bun.yaml"), "utf8")) as { release?: Release } : {}; const policy = config.release; if (!policy?.enabled) return { ok: true, message: "release policy disabled" }; const source = policy.version_source ?? "package.json", pkg = JSON.parse(await readFile(join(root, source), "utf8")) as { version?: string }, version = pkg.version ?? ""; if (!semver.test(version)) return { ok: false, message: `invalid SemVer: ${version}` }; const tags = (await git(root, ["tag", "--merged", "HEAD", "--list", `${policy.tag_prefix ?? "v"}*`])).out.split("\n").filter(Boolean).map(tag => tag.replace(policy.tag_prefix ?? "v", "")).filter(tag => semver.test(tag)); const latest = tags.sort(cmp).at(-1); if (latest && cmp(version, latest) <= 0) return { ok: false, message: `version ${version} is not greater than ${latest}` }; const intents = await intentFiles(root, policy.release_intent_paths ?? [".changeset/**", ".release/**"]); const decisions = (await Promise.all(intents.map(file => readFile(file, "utf8")))).flatMap(text => [...text.matchAll(/\b(patch|minor|major|none)\b/g)].map(match => match[1])); if (policy.require_release_intent && decisions.length !== 1) return { ok: false, message: `exactly one release decision required; found ${decisions.length}` }; if (decisions.some(decision => !["patch", "minor", "major", "none"].includes(decision))) return { ok: false, message: "invalid release decision" }; return { ok: true, message: `release ${decisions[0] ?? "none"}: ${version}` }; }

package/src/setup.ts

@@ -0,0 +1,15 @@
+import { ciInit, ciStatus } from "./ci";
+import { hooksStatus, installHooks } from "./hooks";
+
+/** Install the package's two opt-in local surfaces without touching unrelated
+ * workflows or hook paths. Dependency installation itself never calls this. */
+export async function initializeRepository(root = process.cwd(), replace = false) {
+  const existingHooks = await hooksStatus(root);
+  const hooks = replace || !existingHooks.ok ? await installHooks(root, replace) : existingHooks;
+  if (!hooks.ok) return { ok: false, message: `hooks: ${hooks.message}` };
+
+  const existingCi = await ciStatus(root);
+  const ci = replace || !existingCi.ok ? await ciInit(root, replace) : existingCi;
+  if (!ci.ok) return { ok: false, message: `CI workflow: ${ci.message}` };
+  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}` };
+}

package/templates/github/atdd-bun-release.yml

@@ -0,0 +1,16 @@
+# Optional repository-owned release handoff. Configure credentials and publishing policy in this repository.
+name: ATdd-Bun Release
+on:
+  push:
+    branches: [main, master]
+jobs:
+  atdd-bun-release:
+    needs: []
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run atdd-bun release check
+      # Repository owners may add tag/release/publish steps and credentials here.

package/templates/github/atdd-bun.yml

@@ -0,0 +1,26 @@
+# Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun ci init --replace`.
+name: ATdd-Bun
+on:
+  pull_request:
+  merge_group:
+  push:
+    branches: [main, master]
+jobs:
+  atdd-bun:
+    name: atdd-bun
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run atdd-bun all
+      - run: bun test
+      - run: bun run atdd-bun release check
+      - uses: actions/upload-artifact@v4
+        if: always() && hashFiles('**/atdd-bun*.xml', '**/atdd-bun*.json') != ''
+        with:
+          name: atdd-bun-report
+          path: |
+            **/atdd-bun*.xml
+            **/atdd-bun*.json