@afokapu/atdd-bun 0.6.2 → 0.7.1

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/integrity.ts

@@ -2,7 +2,6 @@ import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { instructionPaths } from "./agent";
-import { concreteProfiles } from "./enforce";
 import { defaultHookPolicy, type HookPolicy } from "./hooks";
 
 /**
@@ -106,6 +105,10 @@ async function checkGenerated(root: string, packageRoot: string): Promise<Integr
   return findings;
 }
 
+/** The operator's explicit profile list, or null when atdd-bun.yaml declares none. Deliberately not enabledProfiles():
+ * its absent-means-all default is right for execution and wrong for deciding whether a policy was ever declared. */
+const explicitProfiles = (config: { profiles?: unknown }): string[] | null => Array.isArray(config.profiles) ? config.profiles.map(String) : null;
+
 /** Names of the policy fields in `current` that are looser than in `base`. */
 export function loosenedPolicy(base: Partial<HookPolicy> & { profiles?: unknown }, current: Partial<HookPolicy> & { profiles?: unknown }): string[] {
   const b = { ...defaultHookPolicy, ...base, worktrees: { ...defaultHookPolicy.worktrees, ...base.worktrees } }, c = { ...defaultHookPolicy, ...current, worktrees: { ...defaultHookPolicy.worktrees, ...current.worktrees } };
@@ -116,20 +119,33 @@ export function loosenedPolicy(base: Partial<HookPolicy> & { profiles?: unknown
   const removed = b.protected_branches.filter(x => !c.protected_branches.includes(x)), added = c.registry_paths.filter(x => !b.registry_paths.includes(x));
   if (removed.length) out.push(`protected_branches drops ${removed.join(", ")}`);
   if (added.length) out.push(`registry_paths adds ${added.join(", ")}`);
-  // Deactivating a profile stops enforcing it; the operator may do it, as a change a human approves.
-  const active = (config: { profiles?: unknown }): string[] => Array.isArray(config.profiles) ? config.profiles.map(String) : concreteProfiles;
-  const dropped = active(base).filter(name => !active(current).includes(name));
+  // Profiles: an absent list runs every profile (enabledProfiles) but governs none. The first explicit list is the
+  // adoption that establishes the governed set, not a drop. From then on, dropping a profile or removing the list
+  // (explicit → implicit → narrower would otherwise be a two-step bypass) is loosening a human approves.
+  const before = explicitProfiles(base), after = explicitProfiles(current);
+  if (before && !after) out.push(`profiles becomes implicit: the explicit list [${before.join(", ")}] was removed`);
+  const dropped = before && after ? before.filter(name => !after.includes(name)) : [];
   if (dropped.length) out.push(`profiles drops ${dropped.join(", ")}`);
   return out;
 }
 
 /** atdd-bun.yaml is not looser than on the branch being merged into. */
 async function checkPolicy(root: string, base?: string, push = process.env.GITHUB_EVENT_NAME === "push"): Promise<IntegrityFinding[]> {
-  const ref = base ?? process.env.ATDD_BASE_REF ?? (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : "origin/HEAD");
-  if ((await git(root, ["rev-parse", "--verify", "--quiet", ref])).code) return [];
-  let against = (await git(root, ["merge-base", "HEAD", ref])).out;
-  // A CI push to the base branch has nothing to merge into: judge the pushed commit against its parent.
-  if (push && against === (await git(root, ["rev-parse", "HEAD"])).out) against = (await git(root, ["rev-parse", "--verify", "--quiet", "HEAD~1"])).out;
+  // On a push, the generated CI passes the pre-push tip (github.event.before) as ATDD_BASE_REF, so a multi-commit push
+  // is judged as a whole: [docs, security] → no list → [docs] in one push cannot read as a first adoption.
+  const ref = base || process.env.ATDD_BASE_REF || (process.env.GITHUB_BASE_REF ? `origin/${process.env.GITHUB_BASE_REF}` : "origin/HEAD");
+  const newBranch = /^0+$/.test(ref), resolved = newBranch ? "" : (await git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])).out;
+  let against: string;
+  // An explicit baseline (the pre-push tip, the merge queue's target) that cannot be resolved fails closed.
+  if (!newBranch && !resolved && (base || process.env.ATDD_BASE_REF)) return [{ file: "atdd-bun.yaml", detail: `cannot resolve the policy baseline ${ref.slice(0, 7)} to judge this change against; fetch it (fetch-depth: 0)`, restore: "git fetch origin && re-run the check" }];
+  if (push) {
+    // A push is judged against the tip it replaced, directly, never a merge base: after a force push the merge base
+    // can predate the policy being removed. A new branch has no previous tip and is judged against its parent.
+    against = resolved && resolved !== (await git(root, ["rev-parse", "HEAD"])).out ? resolved : (await git(root, ["rev-parse", "--verify", "--quiet", "HEAD~1"])).out;
+  } else {
+    if (!resolved) return [];
+    against = (await git(root, ["merge-base", "HEAD", ref])).out;
+  }
   if (!against) return [];
   const read = async (text: string | null) => (text ? Bun.YAML.parse(text) ?? {} : {}) as Partial<HookPolicy>;
   const before = await git(root, ["show", `${against}:atdd-bun.yaml`]), path = join(root, "atdd-bun.yaml");

package/src/setup.ts

@@ -2,6 +2,21 @@ import { ciInit, ciStatus } from "./ci";
 import { hooksStatus, installHooks } from "./hooks";
 import { agentInit, agentStatus } from "./agent";
 import { integrityInit, integrityStatus } from "./integrity";
+import { concreteProfiles } from "./enforce";
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** A new atdd-bun.yaml declares every profile explicitly. An absent list runs every profile but governs none, so
+ * without this a greenfield repository's first `profiles:` line could switch most of them off unreported. A
+ * brownfield repository trims the list before its first commit; after that, dropping one is a reported loosening.
+ * An existing atdd-bun.yaml is never touched. */
+export async function policyInit(root = process.cwd()) {
+  const file = join(root, "atdd-bun.yaml");
+  if (existsSync(file)) return { ok: true, message: `${file} kept` };
+  await writeFile(file, `# Generated by atdd-bun init. The profiles this repository enforces; trim the list before the first commit to\n# adopt gradually. Once committed, removing a profile or the list is reported by the integrity check.\nprofiles: [${concreteProfiles.join(", ")}]\n`);
+  return { ok: true, message: file };
+}
 
 /** Install the package's opt-in local surfaces without touching unrelated
  * workflows or hook paths. Dependency installation itself never calls this. */
@@ -21,5 +36,6 @@ export async function initializeRepository(root = process.cwd(), replace = false
   const existingIntegrity = await integrityStatus(root);
   const integrity = replace || !existingIntegrity.ok ? await integrityInit(root, replace) : existingIntegrity;
   if (!integrity.ok) return { ok: false, message: `integrity test: ${integrity.message}` };
-  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}\nintegrity test: ${integrity.message}` };
+  const policy = await policyInit(root);
+  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}\nintegrity test: ${integrity.message}\npolicy: ${policy.message}` };
 }