@afokapu/atdd-bun 0.6.2 → 0.7.0

package/planner-schemas/telemetry-plan.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Telemetry Tracking-Plan Item Schema",
+  "description": "Validates one concrete telemetry tracking-plan file under telemetry/<theme>/<artifact>/{kind}.{plane}[.{measure}].json. Local shape only: path mirroring, kind/plane/measure coherence with the file name, wagon ownership resolution and acceptance linkage are cross-artifact validator concerns (src/telemetry-plan.ts).",
+  "$comment": "Shipped by the telemetry profile (planner_telemetry_plan). The capability is deliberately inert until a repository adopts it: no telemetry/ root and no acceptance telemetry declaration means no findings. `signal` in acceptance.schema.json keeps the executable bar (signal.metric + signal.threshold); the descriptive arrays it also carries are superseded by the acceptance `telemetry` block and by this registry, and are not renamed here — that migration is a separate, documented step.",
+  "type": "object",
+  "required": ["id", "version", "logical_artifact", "kind", "plane", "owner", "purpose", "acceptances", "properties"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^telemetry:(event|trace|metric|log):(ui|ux|be|nw|db|st|tm|sc|au|fn|if):[a-z][a-z0-9-]*:[a-z][a-z0-9-]*(?::(latency|duration|throughput|error_rate|success_rate|count|size|age|staleness|freshness))?$",
+      "description": "Concrete telemetry URN: telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}]. Must mirror the file's path and name; the validator checks that coherence."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
+      "description": "SemVer core for this item's contract. Changing properties, required or forbidden_properties is a contract change and must bump it."
+    },
+    "logical_artifact": {
+      "type": "string",
+      "pattern": "^telemetry:[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$",
+      "description": "The stable architectural identity of the observable outcome: telemetry:{theme}:{artifact}. Not an exporter event. Must be owned by exactly one wagon's produce[] telemetry entry."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["event", "trace", "metric", "log"]
+    },
+    "plane": {
+      "type": "string",
+      "enum": ["ui", "ux", "be", "nw", "db", "st", "tm", "sc", "au", "fn", "if"]
+    },
+    "measure": {
+      "type": "string",
+      "enum": ["latency", "duration", "throughput", "error_rate", "success_rate", "count", "size", "age", "staleness", "freshness"],
+      "description": "Required for metric items (and only metric items); must match the measure segment of the file name and of the id."
+    },
+    "instrument": {
+      "type": "string",
+      "enum": ["counter", "gauge", "histogram", "summary"],
+      "description": "Metric instrument type per the telemetry kind vocabulary."
+    },
+    "unit": {
+      "type": "string",
+      "description": "Unit of measure for metric items (ms, s, bytes, percent, count)."
+    },
+    "owner": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The wagon slug that owns the logical artifact. The validator checks it equals the wagon whose produce[] declares the logical artifact."
+    },
+    "purpose": {
+      "type": "string",
+      "minLength": 20,
+      "description": "The question this item answers. A tracking plan is read by people deciding what to alert and dashboard on; an item that cannot state its question is not planned."
+    },
+    "acceptances": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^acc:[A-Za-z0-9._:-]+$",
+        "description": "Acceptance URNs that require this item. Each must resolve to a declared acceptance in the plan."
+      }
+    },
+    "properties": {
+      "type": "object",
+      "description": "The fields this item may carry, by name. `required` names must all appear here.",
+      "additionalProperties": {
+        "$ref": "#/definitions/property"
+      }
+    },
+    "required": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Property names that must be present on every emission."
+    },
+    "forbidden_properties": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Property names that must never be attached to this item (raw payloads, secrets, prompts)."
+    },
+    "dimensions": {
+      "type": "array",
+      "description": "Metric labels. Every dimension declares cardinality; high cardinality is forbidden for metrics — use an event, log or trace property instead.",
+      "items": {
+        "type": "object",
+        "required": ["name", "cardinality"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {"type": "string", "minLength": 1},
+          "cardinality": {"type": "string", "enum": ["low", "medium", "high"]}
+        }
+      }
+    },
+    "timing": {
+      "type": "array",
+      "description": "Critical timing semantics a telemetry test bound to this item must exercise: post-commit (emitted only after the transaction commits), absent-after-rollback (never emitted when the transaction rolls back), correlation-across-async (correlation context continues across an async handoff). Declaring a semantic is what makes it testable; a test that cannot exercise it should not claim the item.",
+      "items": {"type": "string", "enum": ["post-commit", "absent-after-rollback", "correlation-across-async"]}
+    }
+  },
+  "definitions": {
+    "property": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["string", "integer", "number", "boolean"]
+        },
+        "classification": {
+          "type": "string",
+          "enum": ["internal", "external", "pii"],
+          "description": "Who may see the value. PII forces a justification nobody has to reconstruct later."
+        },
+        "cardinality": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Distinct-value volume. High cardinality is legal in event, log and trace properties where justified; never as a metric label."
+        },
+        "allowed_values": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"type": ["string", "number", "boolean"]},
+          "description": "Closed vocabulary for this property."
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/relationships.yaml

@@ -81,6 +81,11 @@ nodes:
   - coder.bun.security-sql-injection
   - coder.bun.station-master-interlocking-routing
   - coder.bun.station-master-journey-routing
+  - coder.bun.telemetry-forbidden-properties
+  - coder.bun.telemetry-implementation-binding
+  - coder.bun.telemetry-raw-string-emit
+  - coder.bun.telemetry-source-binding
+  - coder.bun.telemetry-vendor-sdk
   - coder.bun.wagon-honours-its-contract
   - coder.htmx.fragment-escapes-interpolation
   - coder.htmx.swap-no-inline-handler
@@ -220,6 +225,10 @@ nodes:
   - planner.steps.linguistic-patterns
   - planner.steps.sequence
   - planner.subject.invariants
+  - planner.telemetry.acceptance-decision
+  - planner.telemetry.logical-ownership
+  - planner.telemetry.metric-cardinality
+  - planner.telemetry.tracking-plan-schema
   - planner.theme.definition
   - planner.theme.must-be-canonical
   - planner.theme.theme-zero-mandatory
@@ -310,7 +319,12 @@ nodes:
   - tester.bun.security-input
   - tester.bun.smoke-no-collaborator-substitution
   - tester.bun.smoke-observable-assertion
+  - tester.bun.telemetry-captured-sink
   - tester.bun.telemetry-emit
+  - tester.bun.telemetry-identity-assertion
+  - tester.bun.telemetry-required-item-coverage
+  - tester.bun.telemetry-test-binding
+  - tester.bun.telemetry-timing-semantics
   - tester.bun.test-carries-urn-identity
   - tester.bun.test-imports-bun-test
   - tester.bun.test-isolation-no-live-state
@@ -5012,3 +5026,163 @@ edges:
     target_ref: atdd-bun.planner.identity-required
     type: enables
     origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the tracking-plan tree is the versioned realization of the telemetry URN-to-filesystem mapping
+    source_ref: planner.telemetry.tracking-plan-schema
+    strength: important
+    target_ref: planner.wagon.telemetry-filesystem
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "a tracking-plan item's path mirrors its concrete telemetry identity"
+    source_ref: planner.telemetry.tracking-plan-schema
+    strength: important
+    target_ref: planner.artifact-naming.path-mirrors-identity
+    type: follows
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "wagon produce[] telemetry entries are the ownership declarations items resolve against"
+    source_ref: planner.telemetry.logical-ownership
+    strength: important
+    target_ref: planner.wagon.produce-consume-artifacts
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the disposition decision governs the telemetry URNs an acceptance may declare
+    source_ref: planner.telemetry.acceptance-decision
+    strength: important
+    target_ref: planner.acceptance.signal-telemetry-naming
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "metric measures and dimensions inherit the naming rule's cardinality discipline"
+    source_ref: planner.telemetry.metric-cardinality
+    strength: important
+    target_ref: planner.acceptance.signal-telemetry-naming
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: "a source Telemetry: reference resolves against the tracking-plan registry"
+    source_ref: coder.bun.telemetry-source-binding
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: only telemetry an acceptance has decided and the plan declares may be emitted by name
+    source_ref: coder.bun.telemetry-raw-string-emit
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: start_to_start
+    reason: vendor SDKs stay in infrastructure adapters as framework imports stay out of domain
+    source_ref: coder.bun.telemetry-vendor-sdk
+    strength: important
+    target_ref: coder.bun.commons-domain-no-framework-import
+    type: runs_alongside
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the forbidden-property list comes from the tracking-plan item
+    source_ref: coder.bun.telemetry-forbidden-properties
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the binding obligation runs on the same header the source rule resolves
+    source_ref: coder.bun.telemetry-implementation-binding
+    strength: important
+    target_ref: coder.bun.telemetry-source-binding
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: required items come from acceptance decisions
+    source_ref: coder.bun.telemetry-implementation-binding
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: a bound test must point at the acceptance whose decision requires the item
+    source_ref: tester.bun.telemetry-test-binding
+    strength: important
+    target_ref: planner.telemetry.acceptance-decision
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: the captured-sink obligation carries the emission assertion into the telemetry profile
+    source_ref: tester.bun.telemetry-captured-sink
+    strength: important
+    target_ref: tester.bun.telemetry-emit
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: exact identity extends the emission assertion from any-call to the named item
+    source_ref: tester.bun.telemetry-identity-assertion
+    strength: important
+    target_ref: tester.bun.telemetry-emit
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: telemetry items follow the acceptance-has-test discipline
+    source_ref: tester.bun.telemetry-required-item-coverage
+    strength: important
+    target_ref: traceability.plan.executable-acceptance-has-test
+    type: requires
+    origin: "@afokapu/atdd-bun"
+  - confidence: 1
+    constraint: mandatory
+    control: internal
+    foundation: finish_to_start
+    reason: timing semantics are declared on the tracking-plan item
+    source_ref: tester.bun.telemetry-timing-semantics
+    strength: important
+    target_ref: planner.telemetry.tracking-plan-schema
+    type: requires
+    origin: "@afokapu/atdd-bun"

package/src/enforce.ts

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { topologyFor } from "./topology";
 
-export type Profile = "traceability" | "topology" | "docs" | "planner" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
+export type Profile = "traceability" | "topology" | "docs" | "planner" | "telemetry" | "coder" | "tester" | "security" | "architecture" | "metrics" | "runtime" | "interlocking" | "htmx" | "design" | "all";
 
 export type Violation = {
   rule_id: string;
@@ -27,6 +27,7 @@ const profiles: Record<Exclude<Profile, "all">, string[]> = {
   topology: ["atdd_topology"],
   docs: ["planner_docs_capability"],
   planner: ["planner_plan_integrity", "planner_schema_validation", "planner_static_validators", "atdd_topology"],
+  telemetry: ["planner_telemetry_plan", "bun_telemetry_code", "bun_telemetry_test"],
   coder: ["bun_green_traceability_detector", "bun_clean_architecture_detector", "bun_ts_metrics_detector", "bun_fullstack_detector", "bun_design_system_detector", "bun_responsive_detector", "atdd_topology"],
   tester: ["bun_tester_discipline_detector", "htmx_e2e_detector", "atdd_topology"],
   security: ["bun_security_hygiene_detector"],

package/src/index.ts

@@ -5,6 +5,8 @@ export type { DocumentationCheck, DocumentationDeclaration, DocumentationRender,
 export { loadPlan, traceabilityPlan, validatePlan } from "./planner-kernel";
 export type { PlanArtifact, PlanFinding, PlanGraph, PlanKind } from "./planner-kernel";
 export { validateStaticPlannerConventions } from "./planner-validators";
+export { validateTelemetryPlan, loadTelemetryFiles, telemetryDecisionOf, CONCRETE_URN } from "./telemetry-plan";
+export type { TelemetryPlanItem, TelemetryFile } from "./telemetry-plan";
 export { PLANNER_SCHEMA_RULE_ID, validatePlannerSchemas } from "./planner-schema-validator";
 export { defaultHookPolicy, hookEvents, hooksStatus, installHooks, runHook, uninstallHooks } from "./hooks";
 export type { HookEvent, HookPolicy } from "./hooks";

package/src/telemetry-plan.ts

@@ -0,0 +1,223 @@
+import Ajv, { type ValidateFunction } from "ajv";
+import addFormats from "ajv-formats";
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { loadPlan, type PlanFinding } from "./planner-kernel";
+import { topologyFor } from "./topology";
+
+/** The telemetry tracking-plan validator: the plan-side half of the telemetry profile.
+ *
+ * A tracking plan is the versioned source of truth for what a repository observes. The
+ * telemetry/ tree declares concrete items (event / trace / metric / log per plane); wagons
+ * own the logical artifacts they realize; every acceptance makes an explicit decision —
+ * `required` (with items that must resolve into the tree) or `not-applicable` (with a
+ * rationale). The capability is inert until adopted: no telemetry root and no acceptance
+ * telemetry declaration means no findings, so upgrading the package changes nothing for a
+ * repository that has not opted in. */
+
+const KINDS = ["event", "trace", "metric", "log"] as const;
+const PLANES = ["ui", "ux", "be", "nw", "db", "st", "tm", "sc", "au", "fn", "if"] as const;
+const MEASURES = ["latency", "duration", "throughput", "error_rate", "success_rate", "count", "size", "age", "staleness", "freshness"] as const;
+const SEGMENT = "[a-z][a-z0-9-]*";
+export const CONCRETE_URN = new RegExp(`^telemetry:(?:${KINDS.join("|")}):(?:${PLANES.join("|")}):${SEGMENT}:${SEGMENT}(?::(?:${MEASURES.join("|")}))?$`);
+const FILE_NAME = new RegExp(`^(event|trace|metric|log)\\.(${PLANES.join("|")})(?:\\.(${MEASURES.join("|")}))?\\.json$`);
+const SEGMENT_PATTERN = new RegExp(`^${SEGMENT}$`);
+const schemaFile = join(resolve(import.meta.dir, ".."), "planner-schemas", "telemetry-plan.schema.json");
+
+export type TelemetryPlanItem = { file: string; data: Record<string, unknown> };
+/** One file under the telemetry root: its place in the tree, its parsed body, or why it would not parse. */
+export type TelemetryFile = { file: string; segments: string[]; data: Record<string, unknown> | null; error?: string };
+
+const finding = (rule_id: string, file: string, evidence: string): PlanFinding => ({ rule_id, file, evidence });
+const text = (value: unknown): string => (typeof value === "string" ? value : "");
+const records = (value: unknown): Array<Record<string, unknown>> => (Array.isArray(value) ? value.filter(entry => entry && typeof entry === "object" && !Array.isArray(entry)) : []);
+
+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);
+    // `_generated` trees are derived material, never authored plan items — same exclusion the
+    // plan kernel applies under plan/.
+    if (entry.isDirectory() && entry.name === "_generated") return [];
+    return entry.isDirectory() ? walk(path) : entry.isFile() && entry.name.endsWith(".json") ? [path] : [];
+  }))).flat().sort();
+}
+
+async function itemValidator(): Promise<ValidateFunction> {
+  const ajv = new Ajv({ allErrors: true, allowUnionTypes: true, strict: false });
+  addFormats(ajv);
+  return ajv.compile(JSON.parse(await readFile(schemaFile, "utf8")));
+}
+
+/** Wagon ownership of logical telemetry artifacts, from produce[].telemetry entries (string or list). */
+function telemetryOwners(wagons: Array<{ id: string; data: Record<string, unknown> }>): Map<string, string[]> {
+  const owners = new Map<string, string[]>();
+  for (const wagon of wagons) {
+    const slug = text(wagon.data.wagon) || wagon.id.replace(/^wagon:/, "");
+    for (const entry of records(wagon.data.produce)) {
+      const declared = entry.telemetry;
+      for (const value of Array.isArray(declared) ? declared.map(text) : [text(declared)]) {
+        if (value) owners.set(value, [...(owners.get(value) ?? []), slug]);
+      }
+    }
+  }
+  return owners;
+}
+
+/** The acceptance's telemetry decision: disposition plus the concrete URNs it lists, any shape. */
+export function telemetryDecisionOf(acceptance: { id: string; data: Record<string, unknown> }): { disposition: string; urns: string[] } {
+  const decision = acceptance.data.telemetry;
+  if (!decision || typeof decision !== "object" || Array.isArray(decision)) return { disposition: "", urns: [] };
+  const record = decision as Record<string, unknown>;
+  return {
+    disposition: text(record.disposition),
+    urns: ["events", "metrics", "traces", "logs"].flatMap(key => (Array.isArray(record[key]) ? record[key] : []).map(text)).filter(Boolean),
+  };
+}
+
+/** Load the tracking plan: the adoption gate, every file under the telemetry root (parsed or
+ * not), and every acceptance's telemetry decision. Shared by the plan-side validator and both
+ * code- and test-side detectors, so all of them judge the same registry. */
+export async function loadTelemetryFiles(root = process.cwd()): Promise<{ adopted: boolean; files: TelemetryFile[]; requiredIds: Set<string>; decisions: Map<string, { disposition: string; urns: string[]; file: string }> }> {
+  const absolute = resolve(root), topology = await topologyFor(absolute);
+  const telemetryRoot = join(absolute, topology.telemetryRoot);
+  const plan = await loadPlan(absolute);
+  const acceptances = plan.artifacts.filter(artifact => artifact.kind === "acceptance");
+  // Adoption is a positive act: create the telemetry root, or let any acceptance declare a telemetry
+  // decision. Until then the capability is inert — an upgraded package must not fail an unadopting repo.
+  const adopted = existsSync(telemetryRoot) || acceptances.some(acceptance => acceptance.data.telemetry !== undefined);
+  const decisions = new Map<string, { disposition: string; urns: string[]; file: string }>();
+  const requiredIds = new Set<string>();
+  for (const acceptance of acceptances) {
+    const decision = telemetryDecisionOf(acceptance);
+    decisions.set(acceptance.id, { ...decision, file: acceptance.file });
+    if (decision.disposition === "required") for (const urn of decision.urns) requiredIds.add(urn);
+  }
+  const files: TelemetryFile[] = [];
+  for (const path of await walk(telemetryRoot)) {
+    const file = relative(absolute, path).replaceAll("\\", "/");
+    const segments = relative(telemetryRoot, path).replaceAll("\\", "/").split("/");
+    try {
+      const data: unknown = JSON.parse(await readFile(path, "utf8"));
+      if (!data || typeof data !== "object" || Array.isArray(data)) { files.push({ file, segments, data: null, error: "tracking-plan item must be a JSON object" }); continue; }
+      files.push({ file, segments, data: data as Record<string, unknown> });
+    } catch (error) {
+      files.push({ file, segments, data: null, error: `could not parse tracking-plan item: ${String(error)}` });
+    }
+  }
+  return { adopted, files, requiredIds, decisions };
+}
+
+export async function validateTelemetryPlan(root = process.cwd()): Promise<PlanFinding[]> {
+  const absolute = resolve(root), topology = await topologyFor(absolute);
+  const { adopted, files } = await loadTelemetryFiles(absolute);
+  if (!adopted) return [];
+
+  const findings: PlanFinding[] = [], validate = await itemValidator(), items: TelemetryPlanItem[] = [], byId = new Map<string, TelemetryPlanItem>();
+
+  for (const entry of files) {
+    const { file, segments } = entry;
+    const name = segments.at(-1) ?? "", match = FILE_NAME.exec(name);
+    if (segments.length !== 3 || !match || !SEGMENT_PATTERN.test(segments[0]) || !SEGMENT_PATTERN.test(segments[1])) {
+      findings.push(finding("planner.telemetry.tracking-plan-schema", file, `tracking-plan files live at ${topology.telemetryRoot}/<theme>/<artifact>/{event|trace|metric|log}.<plane>[.<measure>].json; found ${file}`));
+      continue;
+    }
+    if (!entry.data) {
+      findings.push(finding("planner.telemetry.tracking-plan-schema", file, entry.error ?? "tracking-plan item must be a JSON object"));
+      continue;
+    }
+    const record = entry.data;
+    if (!validate(record)) {
+      for (const error of validate.errors ?? []) findings.push(finding(
+        "planner.telemetry.tracking-plan-schema", file,
+        `${file} violates telemetry-plan.schema.json: ${error.instancePath || "/"} ${error.message ?? error.keyword}`,
+      ));
+    }
+    items.push({ file, data: record });
+
+    // Path mirrors identity: the file's place in the tree is the authority for id, logical artifact,
+    // kind, plane and measure. A renamed file or a hand-edited id cannot drift apart silently.
+    const [theme, artifact] = segments, kind = match[1], plane = match[2], measure = match[3] ?? null;
+    if (text(record.kind) !== kind) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `kind '${text(record.kind) || "<missing>"}' does not match file name ${name}`));
+    if (text(record.plane) !== plane) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `plane '${text(record.plane) || "<missing>"}' does not match file name ${name}`));
+    if (kind === "metric") {
+      if (!measure) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `metric items carry a measure segment: metric.<plane>.<measure>.json (found ${name})`));
+      else if (text(record.measure) && text(record.measure) !== measure) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `measure '${text(record.measure)}' does not match file name ${name}`));
+    } else if (measure) {
+      findings.push(finding("planner.telemetry.tracking-plan-schema", file, `only metric items carry a measure segment (found ${name})`));
+    }
+    const expectedId = `telemetry:${kind}:${plane}:${theme}:${artifact}${measure ? `:${measure}` : ""}`;
+    if (text(record.id) !== expectedId) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `id '${text(record.id) || "<missing>"}' does not mirror its path; expected '${expectedId}'`));
+    const expectedLogical = `telemetry:${theme}:${artifact}`;
+    if (text(record.logical_artifact) !== expectedLogical) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `logical_artifact '${text(record.logical_artifact) || "<missing>"}' does not mirror its path; expected '${expectedLogical}'`));
+    const declared = record.properties && typeof record.properties === "object" && !Array.isArray(record.properties) ? Object.keys(record.properties as Record<string, unknown>) : [];
+    for (const name of (Array.isArray(record.required) ? record.required : []).map(text)) {
+      if (name && !declared.includes(name)) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `required property '${name}' is not declared in properties`));
+    }
+    const id = text(record.id), previous = byId.get(id);
+    if (id && previous) findings.push(finding("planner.telemetry.tracking-plan-schema", file, `concrete telemetry '${id}' is declared by both ${previous.file} and ${file}`));
+    else if (id) byId.set(id, { file, data: record });
+  }
+
+  const plan = await loadPlan(absolute);
+  const acceptances = plan.artifacts.filter(artifact => artifact.kind === "acceptance");
+
+  // Every concrete item resolves to exactly one wagon-owned logical artifact, and owner names that wagon.
+  const owners = telemetryOwners(plan.artifacts.filter(artifact => artifact.kind === "wagon"));
+  for (const item of items) {
+    const logical = text(item.data.logical_artifact);
+    if (!logical) continue; // the schema finding already names it
+    const owning = owners.get(logical) ?? [];
+    if (!owning.length) findings.push(finding("planner.telemetry.logical-ownership", item.file, `logical artifact ${logical} is produced by no wagon; declare it in exactly one wagon's produce[] telemetry`));
+    else if (owning.length > 1) findings.push(finding("planner.telemetry.logical-ownership", item.file, `logical artifact ${logical} is produced by wagons ${owning.join(", ")}`));
+    else if (text(item.data.owner) && text(item.data.owner) !== owning[0]) findings.push(finding("planner.telemetry.logical-ownership", item.file, `owner '${text(item.data.owner)}' does not match the owning wagon '${owning[0]}'`));
+  }
+
+  // Every acceptance makes an explicit decision; required items resolve into the tracking plan, and the
+  // plan's references back out of the tree resolve to declared acceptances.
+  const registryIds = new Set(items.map(item => text(item.data.id)).filter(Boolean));
+  const acceptanceIds = new Set(acceptances.map(acceptance => acceptance.id));
+  for (const acceptance of acceptances) {
+    const block = acceptance.data.telemetry;
+    if (!block || typeof block !== "object" || Array.isArray(block)) {
+      findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${acceptance.id} declares no telemetry decision; declare telemetry: { disposition: required, events: [...] } or telemetry: { disposition: not-applicable, rationale: ... }`));
+      continue;
+    }
+    const { disposition, urns } = telemetryDecisionOf(acceptance);
+    if (disposition === "required") {
+      if (!urns.length) findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${acceptance.id} is disposition: required but declares no telemetry items`));
+      for (const urn of urns) {
+        if (!urn) { findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${acceptance.id} declares an empty telemetry item`)); continue; }
+        if (!CONCRETE_URN.test(urn)) findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${urn} is not a concrete telemetry URN telemetry:{kind}:{plane}:{theme}:{artifact}[:{measure}]`));
+        else if (!registryIds.has(urn)) findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${urn} has no tracking-plan entry under ${topology.telemetryRoot}/`));
+      }
+    } else if (disposition === "not-applicable") {
+      const rationale = text((block as Record<string, unknown>).rationale).trim();
+      if (rationale.length < 20) findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${acceptance.id} is disposition: not-applicable without a rationale (at least 20 characters)`));
+    } else {
+      findings.push(finding("planner.telemetry.acceptance-decision", acceptance.file, `${acceptance.id} telemetry.disposition must be required or not-applicable, found '${disposition || "<missing>"}'`));
+    }
+  }
+  for (const item of items) {
+    for (const reference of (Array.isArray(item.data.acceptances) ? item.data.acceptances : []).map(text)) {
+      if (reference && !acceptanceIds.has(reference)) findings.push(finding("planner.telemetry.acceptance-decision", item.file, `${text(item.data.id) || item.file} references undeclared acceptance ${reference}`));
+    }
+  }
+
+  // High-cardinality identifiers are forbidden as metric labels; they belong in event, log and trace
+  // properties where the plan justifies them.
+  for (const item of items) {
+    if (text(item.data.kind) !== "metric") continue;
+    const properties = item.data.properties && typeof item.data.properties === "object" && !Array.isArray(item.data.properties) ? item.data.properties as Record<string, Record<string, unknown>> : {};
+    for (const dimension of records(item.data.dimensions)) {
+      const name = text(dimension.name);
+      if (!name) continue;
+      if (text(dimension.cardinality) === "high") findings.push(finding("planner.telemetry.metric-cardinality", item.file, `${text(item.data.id)} dimension '${name}' is high-cardinality; carry the identifier in an event, log or trace property instead`));
+      else if (properties[name] && text(properties[name].cardinality) === "high") findings.push(finding("planner.telemetry.metric-cardinality", item.file, `${text(item.data.id)} dimension '${name}' names a property declared cardinality: high`));
+    }
+  }
+
+  return findings;
+}

package/src/topology.ts

@@ -2,13 +2,14 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 
-export type Topology = { planRoot: string; sourceRoot: string; testRoot: string; e2eRoot: string };
+export type Topology = { planRoot: string; sourceRoot: string; testRoot: string; e2eRoot: string; telemetryRoot: string };
 
 export const defaultTopology: Topology = {
   planRoot: "plan",
   sourceRoot: "src/wagons",
   testRoot: "tests/wagons",
   e2eRoot: "e2e",
+  telemetryRoot: "telemetry",
 };
 
 const configuredKeys: Array<[keyof Topology, string]> = [
@@ -16,6 +17,7 @@ const configuredKeys: Array<[keyof Topology, string]> = [
   ["sourceRoot", "source_root"],
   ["testRoot", "test_root"],
   ["e2eRoot", "e2e_root"],
+  ["telemetryRoot", "telemetry_root"],
 ];
 
 function safeRelative(value: unknown): string | null {