autotel-schema 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# autotel-schema
+
+> A typed, versioned contract for your telemetry surface. Declare the spans and attributes your service emits, validate live spans against the contract, and diff it across commits to catch breaking trace changes before release.
+
+When the main reader of your telemetry is an **agent**, your span names and attribute keys are a **public API**. Rename `fast_path_hit` to `fast_path_taken` in a refactor and you break the prompts and alerts that mention it. No compiler catches the change, because to the compiler these are strings in a JSON blob.
+
+`autotel-schema` makes that surface explicit, typed, and versionable. With [`autotel-pact`](../autotel-pact) it forms autotel's observability-contract pair. Both use telemetry to answer a contract question:
+
+- **`autotel-schema`** (this package): the telemetry contract you emit (span names + attributes)
+- [`autotel-pact`](../autotel-pact): evidence that contracted interactions actually ran
+
+An optional adjacent package, [`autotel-message-contract`](../autotel-message-contract), extends the idea beyond telemetry to serialized payload compatibility. It runs at test time and needs no runtime observability.
+
+The contract model is **dependency-free and side-effect-free**, so you can import it anywhere (browser, edge, CLI) without pulling in the OpenTelemetry SDK.
+
+## Install
+
+```bash
+pnpm add autotel-schema
+# autotel is an optional peer dependency
+```
+
+## 1. Declare the contract
+
+```ts
+import { defineContract } from 'autotel-schema';
+
+export const contract = defineContract({
+  service: 'checkout',
+  version: '1.2.0', // semver of the *contract*, not the app
+  commonAttributes: {
+    'user.id': { type: 'string', highCardinality: true, description: 'Authenticated user' },
+  },
+  spans: {
+    'checkout.charge': {
+      description: 'Charge a payment method',
+      attributes: {
+        'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
+        'payment.amount_cents': { type: 'number', required: true },
+      },
+    },
+  },
+});
+```
+
+`defineContract()` validates structure (semver, attribute types, deprecations) when the module loads and freezes the result, so a malformed contract throws at startup rather than at runtime.
+
+## 2. Validate live spans
+
+Add the span processor to your OpenTelemetry setup. It validates each ending span against the contract with bounded, deduplicated warnings. It is **fail-open**: a bug in validation cannot break your export. In production it stays off unless you opt in.
+
+```ts
+import { createSchemaValidationProcessor } from 'autotel-schema/processor';
+import { contract } from './telemetry.contract';
+
+const processor = createSchemaValidationProcessor({
+  contract,
+  mode: 'warn', // 'warn' (default) | 'throw' (tests/CI) | 'silent' (collect via onViolation)
+  strictSpanNames: true, // also flag spans not in the contract
+});
+// register `processor` with your TracerProvider
+```
+
+Or validate a span shape directly (e.g. in a unit test):
+
+```ts
+import { validateSpan, hasErrors, formatViolation } from 'autotel-schema';
+
+const violations = validateSpan(
+  { name: 'checkout.charge', attributes: { 'payment.provider': 'bitcoin' } },
+  contract,
+);
+// → [missing_required payment.amount_cents, enum_violation payment.provider]
+if (hasErrors(violations)) violations.forEach((v) => console.error(formatViolation(v)));
+```
+
+Violation codes: `missing_required`, `type_mismatch`, `enum_violation`, `unknown_attribute` (with a "did you mean?" suggestion via edit distance), and `unknown_span`.
+
+## 3. Gate breaking changes in CI
+
+Snapshot the contract, commit the baseline, and diff it on every PR. A removed span or a tightened type is **breaking**; a new span or attribute is **additive**.
+
+```ts
+import { contractToSnapshot, serializeSnapshot } from 'autotel-schema';
+import { writeFileSync } from 'node:fs';
+import { contract } from './telemetry.contract';
+
+writeFileSync('telemetry.snapshot.json', serializeSnapshot(contractToSnapshot(contract)));
+```
+
+Then in CI, with the bundled `autotel-schema` CLI:
+
+```bash
+# regenerate the current snapshot, then:
+autotel-schema check telemetry.baseline.json telemetry.current.json
+# exits 1 with a markdown diff if any breaking change is found
+autotel-schema diff  telemetry.baseline.json telemetry.current.json --json
+```
+
+Programmatically:
+
+```ts
+import { diffSnapshots, hasBreakingChanges, formatDiff } from 'autotel-schema/diff';
+
+const diff = diffSnapshots(baseline, current);
+if (hasBreakingChanges(diff)) throw new Error(formatDiff(diff));
+```
+
+## 4. Protect high-cardinality keys from redaction
+
+The old "keep cardinality down" rule exists because dashboards have pixels. An agent reads the spans rather than scanning a graph, and a high-cardinality field like a user id or request id is often the one attribute that pins down a single failure. Mark those `highCardinality: true` and feed them to your redactor as a **protect list**:
+
+```ts
+import { init } from 'autotel';
+import { highCardinalityKeys } from 'autotel-schema';
+import { contract } from './telemetry.contract';
+
+init({
+  service: 'checkout',
+  attributeRedactor: { allowKeys: highCardinalityKeys(contract), preset: 'strict' },
+});
+```
+
+## What this is / isn't
+
+- **Is**: a contract for your telemetry surface: span names, attribute keys, types, enums, stability, and breaking-vs-additive evolution.
+- **Isn't**: a contract for application message payloads (use [`autotel-message-contract`](../autotel-message-contract)) or evidence that interactions ran (use [`autotel-pact`](../autotel-pact)). It does not require the OpenTelemetry SDK. The processor works against structural span types.
+
+## License
+
+MIT © Jag Reehal

package/dist/cli.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const require_snapshot = require('./snapshot-CyWGJaJT.cjs');
+const require_diff = require('./diff.cjs');
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+
+//#region src/cli.ts
+/**
+* autotel-schema CLI — the CI gate for your telemetry's public API.
+*
+*   autotel-schema diff <baseline.json> <current.json>   # classify changes
+*   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking
+*
+* Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.
+* Commit the baseline; regenerate `current` in CI; gate the merge on `check`.
+*/
+function parseArgs(argv) {
+	const positional = [];
+	let json = false;
+	for (const arg of argv) if (arg === "--json") json = true;
+	else if (arg === "-h" || arg === "--help") positional.unshift("help");
+	else positional.push(arg);
+	return {
+		command: positional[0],
+		baseline: positional[1],
+		current: positional[2],
+		json
+	};
+}
+const USAGE = `autotel-schema — treat your trace surface like a versioned public API
+
+Usage:
+  autotel-schema diff  <baseline.json> <current.json> [--json]
+  autotel-schema check <baseline.json> <current.json> [--json]
+
+Commands:
+  diff    Print every change (breaking / additive / neutral). Always exits 0.
+  check   Like diff, but exits 1 if any breaking change is found (CI gate).
+
+Snapshots are produced with serializeSnapshot(contractToSnapshot(contract)).`;
+function loadDiff(baseline, current) {
+	return require_diff.diffSnapshots(require_snapshot.parseSnapshot((0, node_fs.readFileSync)(baseline, "utf8")), require_snapshot.parseSnapshot((0, node_fs.readFileSync)(current, "utf8")));
+}
+function emit(diff, json) {
+	if (json) console.log(JSON.stringify(diff, null, 2));
+	else console.log(require_diff.formatDiff(diff));
+}
+function run(argv) {
+	const { command, baseline, current, json } = parseArgs(argv);
+	if (!command || command === "help") {
+		console.log(USAGE);
+		return command ? 0 : 1;
+	}
+	if (command !== "diff" && command !== "check") {
+		console.error(`autotel-schema: unknown command "${command}"\n\n${USAGE}`);
+		return 1;
+	}
+	if (!baseline || !current) {
+		console.error("autotel-schema: both <baseline.json> and <current.json> are required\n");
+		console.error(USAGE);
+		return 1;
+	}
+	let diff;
+	try {
+		diff = loadDiff(baseline, current);
+	} catch (error) {
+		console.error(`autotel-schema: ${error instanceof Error ? error.message : String(error)}`);
+		return 1;
+	}
+	emit(diff, json);
+	if (command === "check" && require_diff.hasBreakingChanges(diff)) {
+		console.error(`\nautotel-schema: ${diff.breaking.length} breaking change(s) to the telemetry contract. Bump the contract major version and update the committed snapshot.`);
+		return 1;
+	}
+	return 0;
+}
+const entry = process.argv[1] ? node_path.default.basename(process.argv[1]) : "";
+if (entry === "autotel-schema" || entry === "cli.js" || entry === "cli.cjs") process.exit(run(process.argv.slice(2)));
+
+//#endregion
+exports.run = run;
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.cjs","names":["diffSnapshots","parseSnapshot","formatDiff","hasBreakingChanges","path"],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * autotel-schema CLI — the CI gate for your telemetry's public API.\n *\n *   autotel-schema diff <baseline.json> <current.json>   # classify changes\n *   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking\n *\n * Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.\n * Commit the baseline; regenerate `current` in CI; gate the merge on `check`.\n */\n\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { parseSnapshot } from './snapshot.js';\nimport {\n  diffSnapshots,\n  formatDiff,\n  hasBreakingChanges,\n  type SnapshotDiff,\n} from './diff.js';\n\ninterface Parsed {\n  command: string | undefined;\n  baseline: string | undefined;\n  current: string | undefined;\n  json: boolean;\n}\n\nfunction parseArgs(argv: string[]): Parsed {\n  const positional: string[] = [];\n  let json = false;\n  for (const arg of argv) {\n    if (arg === '--json') json = true;\n    else if (arg === '-h' || arg === '--help') positional.unshift('help');\n    else positional.push(arg);\n  }\n  return {\n    command: positional[0],\n    baseline: positional[1],\n    current: positional[2],\n    json,\n  };\n}\n\nconst USAGE = `autotel-schema — treat your trace surface like a versioned public API\n\nUsage:\n  autotel-schema diff  <baseline.json> <current.json> [--json]\n  autotel-schema check <baseline.json> <current.json> [--json]\n\nCommands:\n  diff    Print every change (breaking / additive / neutral). Always exits 0.\n  check   Like diff, but exits 1 if any breaking change is found (CI gate).\n\nSnapshots are produced with serializeSnapshot(contractToSnapshot(contract)).`;\n\nfunction loadDiff(baseline: string, current: string): SnapshotDiff {\n  const prev = parseSnapshot(readFileSync(baseline, 'utf8'));\n  const next = parseSnapshot(readFileSync(current, 'utf8'));\n  return diffSnapshots(prev, next);\n}\n\nfunction emit(diff: SnapshotDiff, json: boolean): void {\n  if (json) {\n    console.log(JSON.stringify(diff, null, 2));\n  } else {\n    console.log(formatDiff(diff));\n  }\n}\n\nexport function run(argv: string[]): number {\n  const { command, baseline, current, json } = parseArgs(argv);\n\n  if (!command || command === 'help') {\n    console.log(USAGE);\n    return command ? 0 : 1;\n  }\n\n  if (command !== 'diff' && command !== 'check') {\n    console.error(`autotel-schema: unknown command \"${command}\"\\n\\n${USAGE}`);\n    return 1;\n  }\n\n  if (!baseline || !current) {\n    console.error('autotel-schema: both <baseline.json> and <current.json> are required\\n');\n    console.error(USAGE);\n    return 1;\n  }\n\n  let diff: SnapshotDiff;\n  try {\n    diff = loadDiff(baseline, current);\n  } catch (error) {\n    console.error(\n      `autotel-schema: ${error instanceof Error ? error.message : String(error)}`,\n    );\n    return 1;\n  }\n\n  emit(diff, json);\n\n  if (command === 'check' && hasBreakingChanges(diff)) {\n    console.error(\n      `\\nautotel-schema: ${diff.breaking.length} breaking change(s) to the telemetry contract. ` +\n        `Bump the contract major version and update the committed snapshot.`,\n    );\n    return 1;\n  }\n  return 0;\n}\n\n// Only auto-run when invoked directly as the binary, not when imported in tests.\n// Match the basename so a repo path containing \"autotel-schema\" can't trigger it.\nconst entry = process.argv[1] ? path.basename(process.argv[1]) : '';\nif (entry === 'autotel-schema' || entry === 'cli.js' || entry === 'cli.cjs') {\n  process.exit(run(process.argv.slice(2)));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAS,UAAU,MAAwB;CACzC,MAAM,aAAuB,CAAC;CAC9B,IAAI,OAAO;CACX,KAAK,MAAM,OAAO,MAChB,IAAI,QAAQ,UAAU,OAAO;MACxB,IAAI,QAAQ,QAAQ,QAAQ,UAAU,WAAW,QAAQ,MAAM;MAC/D,WAAW,KAAK,GAAG;CAE1B,OAAO;EACL,SAAS,WAAW;EACpB,UAAU,WAAW;EACrB,SAAS,WAAW;EACpB;CACF;AACF;AAEA,MAAM,QAAQ;;;;;;;;;;;AAYd,SAAS,SAAS,UAAkB,SAA+B;CAGjE,OAAOA,2BAFMC,yDAA2B,UAAU,MAAM,CAEhC,GADXA,yDAA2B,SAAS,MAAM,CACzB,CAAC;AACjC;AAEA,SAAS,KAAK,MAAoB,MAAqB;CACrD,IAAI,MACF,QAAQ,IAAI,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC;MAEzC,QAAQ,IAAIC,wBAAW,IAAI,CAAC;AAEhC;AAEA,SAAgB,IAAI,MAAwB;CAC1C,MAAM,EAAE,SAAS,UAAU,SAAS,SAAS,UAAU,IAAI;CAE3D,IAAI,CAAC,WAAW,YAAY,QAAQ;EAClC,QAAQ,IAAI,KAAK;EACjB,OAAO,UAAU,IAAI;CACvB;CAEA,IAAI,YAAY,UAAU,YAAY,SAAS;EAC7C,QAAQ,MAAM,oCAAoC,QAAQ,OAAO,OAAO;EACxE,OAAO;CACT;CAEA,IAAI,CAAC,YAAY,CAAC,SAAS;EACzB,QAAQ,MAAM,wEAAwE;EACtF,QAAQ,MAAM,KAAK;EACnB,OAAO;CACT;CAEA,IAAI;CACJ,IAAI;EACF,OAAO,SAAS,UAAU,OAAO;CACnC,SAAS,OAAO;EACd,QAAQ,MACN,mBAAmB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC1E;EACA,OAAO;CACT;CAEA,KAAK,MAAM,IAAI;CAEf,IAAI,YAAY,WAAWC,gCAAmB,IAAI,GAAG;EACnD,QAAQ,MACN,qBAAqB,KAAK,SAAS,OAAO,kHAE5C;EACA,OAAO;CACT;CACA,OAAO;AACT;AAIA,MAAM,QAAQ,QAAQ,KAAK,KAAKC,kBAAK,SAAS,QAAQ,KAAK,EAAE,IAAI;AACjE,IAAI,UAAU,oBAAoB,UAAU,YAAY,UAAU,WAChE,QAAQ,KAAK,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC"}

package/dist/cli.d.cts

@@ -0,0 +1,14 @@
+//#region src/cli.d.ts
+/**
+ * autotel-schema CLI — the CI gate for your telemetry's public API.
+ *
+ *   autotel-schema diff <baseline.json> <current.json>   # classify changes
+ *   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking
+ *
+ * Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.
+ * Commit the baseline; regenerate `current` in CI; gate the merge on `check`.
+ */
+declare function run(argv: string[]): number;
+//#endregion
+export { run };
+//# sourceMappingURL=cli.d.cts.map

package/dist/cli.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.cts","names":[],"sources":["../src/cli.ts"],"mappings":";AAsEA;;;;AAAkC;;;;;AAAlC,iBAAgB,GAAA,CAAI,IAAc"}

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+//#region src/cli.d.ts
+/**
+ * autotel-schema CLI — the CI gate for your telemetry's public API.
+ *
+ *   autotel-schema diff <baseline.json> <current.json>   # classify changes
+ *   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking
+ *
+ * Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.
+ * Commit the baseline; regenerate `current` in CI; gate the merge on `check`.
+ */
+declare function run(argv: string[]): number;
+//#endregion
+export { run };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../src/cli.ts"],"mappings":";AAsEA;;;;AAAkC;;;;;AAAlC,iBAAgB,GAAA,CAAI,IAAc"}

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { n as parseSnapshot } from "./snapshot-h8pb_Up_.js";
+import { diffSnapshots, formatDiff, hasBreakingChanges } from "./diff.js";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/cli.ts
+/**
+* autotel-schema CLI — the CI gate for your telemetry's public API.
+*
+*   autotel-schema diff <baseline.json> <current.json>   # classify changes
+*   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking
+*
+* Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.
+* Commit the baseline; regenerate `current` in CI; gate the merge on `check`.
+*/
+function parseArgs(argv) {
+	const positional = [];
+	let json = false;
+	for (const arg of argv) if (arg === "--json") json = true;
+	else if (arg === "-h" || arg === "--help") positional.unshift("help");
+	else positional.push(arg);
+	return {
+		command: positional[0],
+		baseline: positional[1],
+		current: positional[2],
+		json
+	};
+}
+const USAGE = `autotel-schema — treat your trace surface like a versioned public API
+
+Usage:
+  autotel-schema diff  <baseline.json> <current.json> [--json]
+  autotel-schema check <baseline.json> <current.json> [--json]
+
+Commands:
+  diff    Print every change (breaking / additive / neutral). Always exits 0.
+  check   Like diff, but exits 1 if any breaking change is found (CI gate).
+
+Snapshots are produced with serializeSnapshot(contractToSnapshot(contract)).`;
+function loadDiff(baseline, current) {
+	return diffSnapshots(parseSnapshot(readFileSync(baseline, "utf8")), parseSnapshot(readFileSync(current, "utf8")));
+}
+function emit(diff, json) {
+	if (json) console.log(JSON.stringify(diff, null, 2));
+	else console.log(formatDiff(diff));
+}
+function run(argv) {
+	const { command, baseline, current, json } = parseArgs(argv);
+	if (!command || command === "help") {
+		console.log(USAGE);
+		return command ? 0 : 1;
+	}
+	if (command !== "diff" && command !== "check") {
+		console.error(`autotel-schema: unknown command "${command}"\n\n${USAGE}`);
+		return 1;
+	}
+	if (!baseline || !current) {
+		console.error("autotel-schema: both <baseline.json> and <current.json> are required\n");
+		console.error(USAGE);
+		return 1;
+	}
+	let diff;
+	try {
+		diff = loadDiff(baseline, current);
+	} catch (error) {
+		console.error(`autotel-schema: ${error instanceof Error ? error.message : String(error)}`);
+		return 1;
+	}
+	emit(diff, json);
+	if (command === "check" && hasBreakingChanges(diff)) {
+		console.error(`\nautotel-schema: ${diff.breaking.length} breaking change(s) to the telemetry contract. Bump the contract major version and update the committed snapshot.`);
+		return 1;
+	}
+	return 0;
+}
+const entry = process.argv[1] ? path.basename(process.argv[1]) : "";
+if (entry === "autotel-schema" || entry === "cli.js" || entry === "cli.cjs") process.exit(run(process.argv.slice(2)));
+
+//#endregion
+export { run };
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * autotel-schema CLI — the CI gate for your telemetry's public API.\n *\n *   autotel-schema diff <baseline.json> <current.json>   # classify changes\n *   autotel-schema check <baseline.json> <current.json>  # exit 1 on breaking\n *\n * Both operate on snapshot JSON produced by `serializeSnapshot(contractToSnapshot(contract))`.\n * Commit the baseline; regenerate `current` in CI; gate the merge on `check`.\n */\n\nimport { readFileSync } from 'node:fs';\nimport path from 'node:path';\nimport { parseSnapshot } from './snapshot.js';\nimport {\n  diffSnapshots,\n  formatDiff,\n  hasBreakingChanges,\n  type SnapshotDiff,\n} from './diff.js';\n\ninterface Parsed {\n  command: string | undefined;\n  baseline: string | undefined;\n  current: string | undefined;\n  json: boolean;\n}\n\nfunction parseArgs(argv: string[]): Parsed {\n  const positional: string[] = [];\n  let json = false;\n  for (const arg of argv) {\n    if (arg === '--json') json = true;\n    else if (arg === '-h' || arg === '--help') positional.unshift('help');\n    else positional.push(arg);\n  }\n  return {\n    command: positional[0],\n    baseline: positional[1],\n    current: positional[2],\n    json,\n  };\n}\n\nconst USAGE = `autotel-schema — treat your trace surface like a versioned public API\n\nUsage:\n  autotel-schema diff  <baseline.json> <current.json> [--json]\n  autotel-schema check <baseline.json> <current.json> [--json]\n\nCommands:\n  diff    Print every change (breaking / additive / neutral). Always exits 0.\n  check   Like diff, but exits 1 if any breaking change is found (CI gate).\n\nSnapshots are produced with serializeSnapshot(contractToSnapshot(contract)).`;\n\nfunction loadDiff(baseline: string, current: string): SnapshotDiff {\n  const prev = parseSnapshot(readFileSync(baseline, 'utf8'));\n  const next = parseSnapshot(readFileSync(current, 'utf8'));\n  return diffSnapshots(prev, next);\n}\n\nfunction emit(diff: SnapshotDiff, json: boolean): void {\n  if (json) {\n    console.log(JSON.stringify(diff, null, 2));\n  } else {\n    console.log(formatDiff(diff));\n  }\n}\n\nexport function run(argv: string[]): number {\n  const { command, baseline, current, json } = parseArgs(argv);\n\n  if (!command || command === 'help') {\n    console.log(USAGE);\n    return command ? 0 : 1;\n  }\n\n  if (command !== 'diff' && command !== 'check') {\n    console.error(`autotel-schema: unknown command \"${command}\"\\n\\n${USAGE}`);\n    return 1;\n  }\n\n  if (!baseline || !current) {\n    console.error('autotel-schema: both <baseline.json> and <current.json> are required\\n');\n    console.error(USAGE);\n    return 1;\n  }\n\n  let diff: SnapshotDiff;\n  try {\n    diff = loadDiff(baseline, current);\n  } catch (error) {\n    console.error(\n      `autotel-schema: ${error instanceof Error ? error.message : String(error)}`,\n    );\n    return 1;\n  }\n\n  emit(diff, json);\n\n  if (command === 'check' && hasBreakingChanges(diff)) {\n    console.error(\n      `\\nautotel-schema: ${diff.breaking.length} breaking change(s) to the telemetry contract. ` +\n        `Bump the contract major version and update the committed snapshot.`,\n    );\n    return 1;\n  }\n  return 0;\n}\n\n// Only auto-run when invoked directly as the binary, not when imported in tests.\n// Match the basename so a repo path containing \"autotel-schema\" can't trigger it.\nconst entry = process.argv[1] ? path.basename(process.argv[1]) : '';\nif (entry === 'autotel-schema' || entry === 'cli.js' || entry === 'cli.cjs') {\n  process.exit(run(process.argv.slice(2)));\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA4BA,SAAS,UAAU,MAAwB;CACzC,MAAM,aAAuB,CAAC;CAC9B,IAAI,OAAO;CACX,KAAK,MAAM,OAAO,MAChB,IAAI,QAAQ,UAAU,OAAO;MACxB,IAAI,QAAQ,QAAQ,QAAQ,UAAU,WAAW,QAAQ,MAAM;MAC/D,WAAW,KAAK,GAAG;CAE1B,OAAO;EACL,SAAS,WAAW;EACpB,UAAU,WAAW;EACrB,SAAS,WAAW;EACpB;CACF;AACF;AAEA,MAAM,QAAQ;;;;;;;;;;;AAYd,SAAS,SAAS,UAAkB,SAA+B;CAGjE,OAAO,cAFM,cAAc,aAAa,UAAU,MAAM,CAEhC,GADX,cAAc,aAAa,SAAS,MAAM,CACzB,CAAC;AACjC;AAEA,SAAS,KAAK,MAAoB,MAAqB;CACrD,IAAI,MACF,QAAQ,IAAI,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC;MAEzC,QAAQ,IAAI,WAAW,IAAI,CAAC;AAEhC;AAEA,SAAgB,IAAI,MAAwB;CAC1C,MAAM,EAAE,SAAS,UAAU,SAAS,SAAS,UAAU,IAAI;CAE3D,IAAI,CAAC,WAAW,YAAY,QAAQ;EAClC,QAAQ,IAAI,KAAK;EACjB,OAAO,UAAU,IAAI;CACvB;CAEA,IAAI,YAAY,UAAU,YAAY,SAAS;EAC7C,QAAQ,MAAM,oCAAoC,QAAQ,OAAO,OAAO;EACxE,OAAO;CACT;CAEA,IAAI,CAAC,YAAY,CAAC,SAAS;EACzB,QAAQ,MAAM,wEAAwE;EACtF,QAAQ,MAAM,KAAK;EACnB,OAAO;CACT;CAEA,IAAI;CACJ,IAAI;EACF,OAAO,SAAS,UAAU,OAAO;CACnC,SAAS,OAAO;EACd,QAAQ,MACN,mBAAmB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAC1E;EACA,OAAO;CACT;CAEA,KAAK,MAAM,IAAI;CAEf,IAAI,YAAY,WAAW,mBAAmB,IAAI,GAAG;EACnD,QAAQ,MACN,qBAAqB,KAAK,SAAS,OAAO,kHAE5C;EACA,OAAO;CACT;CACA,OAAO;AACT;AAIA,MAAM,QAAQ,QAAQ,KAAK,KAAK,KAAK,SAAS,QAAQ,KAAK,EAAE,IAAI;AACjE,IAAI,UAAU,oBAAoB,UAAU,YAAY,UAAU,WAChE,QAAQ,KAAK,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC"}

package/dist/contract-DGjxR9nb.d.cts

@@ -0,0 +1,123 @@
+//#region src/contract.d.ts
+/**
+ * Telemetry contract model.
+ *
+ * The premise: when the primary reader of your telemetry is an agent, your
+ * span names and attribute keys are a **public API**. Renaming `fast_path_hit`
+ * to `fast_path_taken` in a refactor PR silently breaks every prompt that
+ * mentions it — there is no compiler to catch it, because to the compiler these
+ * are just strings in a JSON blob.
+ *
+ * `defineContract()` makes that surface explicit, typed, and versionable: you
+ * declare which spans your service emits and which attributes live on them,
+ * then validate live spans against it ({@link ./validate}) and diff it across
+ * commits to catch breaking changes before they ship ({@link ./diff}).
+ *
+ * This module is dependency-free and side-effect-free by design — safe to
+ * import anywhere (browser, edge, CLI) without pulling in the OpenTelemetry SDK.
+ */
+/** Scalar and array attribute types permitted on a span (OTLP value shapes). */
+type AttributeType = 'string' | 'number' | 'boolean' | 'string[]' | 'number[]' | 'boolean[]';
+declare const ATTRIBUTE_TYPES: readonly AttributeType[];
+/**
+ * Lifecycle of a span or attribute, mirroring how the OpenTelemetry semantic
+ * conventions stage their own surface. `stable` is a promise to agent readers
+ * that the name will not change without a major contract bump.
+ */
+type Stability = 'stable' | 'experimental' | 'deprecated';
+declare const STABILITIES: readonly Stability[];
+/** Declaration for a single attribute key on a span. */
+interface AttributeSpec {
+  /** OTLP value shape. Validated at runtime against the emitted value. */
+  type: AttributeType;
+  /** Lifecycle stage. Defaults to `stable`. */
+  stability?: Stability;
+  /** When `true`, the attribute must be present on every matching span. */
+  required?: boolean;
+  /** Human/agent-facing description of what the attribute means. */
+  description?: string;
+  /**
+   * Marks an attribute as intentionally high-cardinality (user id, sender
+   * domain, request id). For an agent reader these are the single most useful
+   * fields on a trace, so {@link ./redaction.highCardinalityKeys} surfaces them
+   * as a *protect* list — telling redactors/normalizers NOT to strip them.
+   */
+  highCardinality?: boolean;
+  /** Closed set of permitted values. Reported as `enum_violation` if exceeded. */
+  enum?: readonly (string | number)[];
+  /** Set when `stability: 'deprecated'`; explains what to use instead. */
+  replacedBy?: string;
+  /** Free-text note shown alongside deprecation warnings. */
+  deprecatedReason?: string;
+}
+/** Declaration for a single span name your service emits. */
+interface SpanSpec {
+  /** Human/agent-facing description of when this span is produced. */
+  description?: string;
+  /** Lifecycle stage. Defaults to `stable`. */
+  stability?: Stability;
+  /** Attributes specific to this span, keyed by attribute name. */
+  attributes?: Record<string, AttributeSpec>;
+  /**
+   * When `true`, attributes not declared here are allowed without an
+   * `unknown_attribute` violation. Defaults to the contract-level setting.
+   */
+  additionalAttributes?: boolean;
+}
+/** The full telemetry contract for one service. */
+interface TelemetryContract {
+  /** `service.name` this contract describes. */
+  service: string;
+  /**
+   * Semver of the *contract itself* (not the app). Bumped when the trace
+   * surface changes; surfaced to readers as the `telemetry.schema.version`
+   * resource attribute via {@link ./attrs.SCHEMA_ATTRS}.
+   */
+  version: string;
+  /** Spans this service emits, keyed by span name. */
+  spans: Record<string, SpanSpec>;
+  /** Attributes permitted on *any* span (e.g. `user.id`, `tenant.id`). */
+  commonAttributes?: Record<string, AttributeSpec>;
+  /**
+   * Default for `SpanSpec.additionalAttributes` when a span does not set it.
+   * Defaults to `false` (declared-only — the stricter, agent-friendlier mode).
+   */
+  additionalAttributes?: boolean;
+}
+/**
+ * Validate and freeze a telemetry contract. Throws on structural mistakes
+ * (bad semver, unknown attribute type, deprecation with no replacement) so the
+ * contract fails loudly at module load, not silently at runtime.
+ *
+ * @example
+ * ```ts
+ * export const contract = defineContract({
+ *   service: 'checkout',
+ *   version: '1.2.0',
+ *   commonAttributes: {
+ *     'user.id': { type: 'string', highCardinality: true, description: 'Authenticated user' },
+ *   },
+ *   spans: {
+ *     'checkout.charge': {
+ *       description: 'Charge a payment method',
+ *       attributes: {
+ *         'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
+ *         'payment.amount_cents': { type: 'number', required: true },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineContract(contract: TelemetryContract): TelemetryContract;
+/**
+ * Resolve the effective attribute spec for `key` on `spanName`: span-specific
+ * attributes win over common attributes. Returns `undefined` when the key is
+ * declared nowhere.
+ */
+declare function resolveAttributeSpec(contract: TelemetryContract, spanName: string, key: string): AttributeSpec | undefined;
+/** Whether attributes outside the declared set are tolerated for a span. */
+declare function allowsAdditionalAttributes(contract: TelemetryContract, spanName: string): boolean;
+//#endregion
+export { SpanSpec as a, allowsAdditionalAttributes as c, STABILITIES as i, defineContract as l, AttributeSpec as n, Stability as o, AttributeType as r, TelemetryContract as s, ATTRIBUTE_TYPES as t, resolveAttributeSpec as u };
+//# sourceMappingURL=contract-DGjxR9nb.d.cts.map

package/dist/contract-DGjxR9nb.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-DGjxR9nb.d.cts","names":[],"sources":["../src/contract.ts"],"mappings":";;AAmBA;;;;AAAyB;AAQzB;;;;AAAoD;AAcpD;;;;AAAqB;AAErB;;KAxBY,aAAA;AAAA,cAQC,eAAA,WAA0B,aAAa;AAgBR;AAO5C;;;;AAP4C,KAFhC,SAAA;AAAA,cAEC,WAAA,WAAsB,SAAS;;UAO3B,aAAA;EAMf;EAJA,IAAA,EAAM,aAAA;EAaN;EAXA,SAAA,GAAY,SAAS;EAerB;EAbA,QAAA;EAegB;EAbhB,WAAA;EAiBe;;;;;;EAVf,eAAA;EAgBmB;EAdnB,IAAA;EAYA;EAVA,UAAA;EAYA;EAVA,gBAAA;AAAA;;UAIe,QAAA;EAWK;EATpB,WAAA;EAagC;EAXhC,SAAA,GAAY,SAAA;EAqBU;EAnBtB,UAAA,GAAa,MAAA,SAAe,aAAA;EAqBM;;;;EAhBlC,oBAAA;AAAA;;UAIe,iBAAA;EAUO;EARtB,OAAA;EAUmB;;;;AAKC;EATpB,OAAA;EA0E4B;EAxE5B,KAAA,EAAO,MAAA,SAAe,QAAA;EAwEsD;EAtE5E,gBAAA,GAAmB,MAAA,SAAe,aAAA;EAsEL;;;AAA+C;EAjE5E,oBAAA;AAAA;;;;;;;;;AA0Gc;AAQhB;;;;;;;;AAEkB;;;;;;;;iBAnDF,cAAA,CAAe,QAAA,EAAU,iBAAA,GAAoB,iBAAiB;;;;;;iBAqC9D,oBAAA,CACd,QAAA,EAAU,iBAAA,EACV,QAAA,UACA,GAAA,WACC,aAAa;;iBAQA,0BAAA,CACd,QAAA,EAAU,iBAAiB,EAC3B,QAAA"}

package/dist/contract-DGjxR9nb.d.ts

@@ -0,0 +1,123 @@
+//#region src/contract.d.ts
+/**
+ * Telemetry contract model.
+ *
+ * The premise: when the primary reader of your telemetry is an agent, your
+ * span names and attribute keys are a **public API**. Renaming `fast_path_hit`
+ * to `fast_path_taken` in a refactor PR silently breaks every prompt that
+ * mentions it — there is no compiler to catch it, because to the compiler these
+ * are just strings in a JSON blob.
+ *
+ * `defineContract()` makes that surface explicit, typed, and versionable: you
+ * declare which spans your service emits and which attributes live on them,
+ * then validate live spans against it ({@link ./validate}) and diff it across
+ * commits to catch breaking changes before they ship ({@link ./diff}).
+ *
+ * This module is dependency-free and side-effect-free by design — safe to
+ * import anywhere (browser, edge, CLI) without pulling in the OpenTelemetry SDK.
+ */
+/** Scalar and array attribute types permitted on a span (OTLP value shapes). */
+type AttributeType = 'string' | 'number' | 'boolean' | 'string[]' | 'number[]' | 'boolean[]';
+declare const ATTRIBUTE_TYPES: readonly AttributeType[];
+/**
+ * Lifecycle of a span or attribute, mirroring how the OpenTelemetry semantic
+ * conventions stage their own surface. `stable` is a promise to agent readers
+ * that the name will not change without a major contract bump.
+ */
+type Stability = 'stable' | 'experimental' | 'deprecated';
+declare const STABILITIES: readonly Stability[];
+/** Declaration for a single attribute key on a span. */
+interface AttributeSpec {
+  /** OTLP value shape. Validated at runtime against the emitted value. */
+  type: AttributeType;
+  /** Lifecycle stage. Defaults to `stable`. */
+  stability?: Stability;
+  /** When `true`, the attribute must be present on every matching span. */
+  required?: boolean;
+  /** Human/agent-facing description of what the attribute means. */
+  description?: string;
+  /**
+   * Marks an attribute as intentionally high-cardinality (user id, sender
+   * domain, request id). For an agent reader these are the single most useful
+   * fields on a trace, so {@link ./redaction.highCardinalityKeys} surfaces them
+   * as a *protect* list — telling redactors/normalizers NOT to strip them.
+   */
+  highCardinality?: boolean;
+  /** Closed set of permitted values. Reported as `enum_violation` if exceeded. */
+  enum?: readonly (string | number)[];
+  /** Set when `stability: 'deprecated'`; explains what to use instead. */
+  replacedBy?: string;
+  /** Free-text note shown alongside deprecation warnings. */
+  deprecatedReason?: string;
+}
+/** Declaration for a single span name your service emits. */
+interface SpanSpec {
+  /** Human/agent-facing description of when this span is produced. */
+  description?: string;
+  /** Lifecycle stage. Defaults to `stable`. */
+  stability?: Stability;
+  /** Attributes specific to this span, keyed by attribute name. */
+  attributes?: Record<string, AttributeSpec>;
+  /**
+   * When `true`, attributes not declared here are allowed without an
+   * `unknown_attribute` violation. Defaults to the contract-level setting.
+   */
+  additionalAttributes?: boolean;
+}
+/** The full telemetry contract for one service. */
+interface TelemetryContract {
+  /** `service.name` this contract describes. */
+  service: string;
+  /**
+   * Semver of the *contract itself* (not the app). Bumped when the trace
+   * surface changes; surfaced to readers as the `telemetry.schema.version`
+   * resource attribute via {@link ./attrs.SCHEMA_ATTRS}.
+   */
+  version: string;
+  /** Spans this service emits, keyed by span name. */
+  spans: Record<string, SpanSpec>;
+  /** Attributes permitted on *any* span (e.g. `user.id`, `tenant.id`). */
+  commonAttributes?: Record<string, AttributeSpec>;
+  /**
+   * Default for `SpanSpec.additionalAttributes` when a span does not set it.
+   * Defaults to `false` (declared-only — the stricter, agent-friendlier mode).
+   */
+  additionalAttributes?: boolean;
+}
+/**
+ * Validate and freeze a telemetry contract. Throws on structural mistakes
+ * (bad semver, unknown attribute type, deprecation with no replacement) so the
+ * contract fails loudly at module load, not silently at runtime.
+ *
+ * @example
+ * ```ts
+ * export const contract = defineContract({
+ *   service: 'checkout',
+ *   version: '1.2.0',
+ *   commonAttributes: {
+ *     'user.id': { type: 'string', highCardinality: true, description: 'Authenticated user' },
+ *   },
+ *   spans: {
+ *     'checkout.charge': {
+ *       description: 'Charge a payment method',
+ *       attributes: {
+ *         'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
+ *         'payment.amount_cents': { type: 'number', required: true },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineContract(contract: TelemetryContract): TelemetryContract;
+/**
+ * Resolve the effective attribute spec for `key` on `spanName`: span-specific
+ * attributes win over common attributes. Returns `undefined` when the key is
+ * declared nowhere.
+ */
+declare function resolveAttributeSpec(contract: TelemetryContract, spanName: string, key: string): AttributeSpec | undefined;
+/** Whether attributes outside the declared set are tolerated for a span. */
+declare function allowsAdditionalAttributes(contract: TelemetryContract, spanName: string): boolean;
+//#endregion
+export { SpanSpec as a, allowsAdditionalAttributes as c, STABILITIES as i, defineContract as l, AttributeSpec as n, Stability as o, AttributeType as r, TelemetryContract as s, ATTRIBUTE_TYPES as t, resolveAttributeSpec as u };
+//# sourceMappingURL=contract-DGjxR9nb.d.ts.map

package/dist/contract-DGjxR9nb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-DGjxR9nb.d.ts","names":[],"sources":["../src/contract.ts"],"mappings":";;AAmBA;;;;AAAyB;AAQzB;;;;AAAoD;AAcpD;;;;AAAqB;AAErB;;KAxBY,aAAA;AAAA,cAQC,eAAA,WAA0B,aAAa;AAgBR;AAO5C;;;;AAP4C,KAFhC,SAAA;AAAA,cAEC,WAAA,WAAsB,SAAS;;UAO3B,aAAA;EAMf;EAJA,IAAA,EAAM,aAAA;EAaN;EAXA,SAAA,GAAY,SAAS;EAerB;EAbA,QAAA;EAegB;EAbhB,WAAA;EAiBe;;;;;;EAVf,eAAA;EAgBmB;EAdnB,IAAA;EAYA;EAVA,UAAA;EAYA;EAVA,gBAAA;AAAA;;UAIe,QAAA;EAWK;EATpB,WAAA;EAagC;EAXhC,SAAA,GAAY,SAAA;EAqBU;EAnBtB,UAAA,GAAa,MAAA,SAAe,aAAA;EAqBM;;;;EAhBlC,oBAAA;AAAA;;UAIe,iBAAA;EAUO;EARtB,OAAA;EAUmB;;;;AAKC;EATpB,OAAA;EA0E4B;EAxE5B,KAAA,EAAO,MAAA,SAAe,QAAA;EAwEsD;EAtE5E,gBAAA,GAAmB,MAAA,SAAe,aAAA;EAsEL;;;AAA+C;EAjE5E,oBAAA;AAAA;;;;;;;;;AA0Gc;AAQhB;;;;;;;;AAEkB;;;;;;;;iBAnDF,cAAA,CAAe,QAAA,EAAU,iBAAA,GAAoB,iBAAiB;;;;;;iBAqC9D,oBAAA,CACd,QAAA,EAAU,iBAAA,EACV,QAAA,UACA,GAAA,WACC,aAAa;;iBAQA,0BAAA,CACd,QAAA,EAAU,iBAAiB,EAC3B,QAAA"}