autotel-schema 0.1.0

package/dist/diff-BQPh72vY.d.cts

@@ -0,0 +1,89 @@
+import { o as Stability, r as AttributeType, s as TelemetryContract } from "./contract-DGjxR9nb.cjs";
+
+//#region src/attrs.d.ts
+/**
+ * Wire constants for the schema contract — the keys autotel-schema reads from
+ * and stamps onto spans. Dependency-free so CLI, browser, and edge code can
+ * share the exact same strings the runtime uses.
+ */
+/**
+ * Resource/span attributes that announce the contract to a reader. Stamping
+ * `telemetry.schema.version` means an agent following a trace knows *which*
+ * version of your public telemetry API it is looking at — the difference
+ * between "confidently correct" and "confidently wrong" after a rename.
+ */
+declare const SCHEMA_ATTRS: {
+  /** The service this contract describes (mirrors `service.name`). */readonly SERVICE: "telemetry.schema.service"; /** Semver of the telemetry contract that produced this span. */
+  readonly VERSION: "telemetry.schema.version";
+};
+type SchemaAttributeKey = (typeof SCHEMA_ATTRS)[keyof typeof SCHEMA_ATTRS];
+/** Snapshot file spec marker — bump only on a breaking snapshot format change. */
+declare const SNAPSHOT_SPEC: "autotel-schema-snapshot/v1";
+//#endregion
+//#region src/snapshot.d.ts
+/** Flattened, fully-resolved attribute record in a snapshot. */
+interface SnapshotAttribute {
+  type: AttributeType;
+  stability: Stability;
+  required: boolean;
+  highCardinality: boolean;
+  enum?: readonly (string | number)[];
+  replacedBy?: string;
+  description?: string;
+}
+interface SnapshotSpan {
+  stability: Stability;
+  additionalAttributes: boolean;
+  description?: string;
+  attributes: Record<string, SnapshotAttribute>;
+}
+/** Canonical, comparable representation of a {@link TelemetryContract}. */
+interface ContractSnapshot {
+  spec: typeof SNAPSHOT_SPEC;
+  service: string;
+  version: string;
+  commonAttributes: Record<string, SnapshotAttribute>;
+  spans: Record<string, SnapshotSpan>;
+}
+/**
+ * Produce a deterministic, JSON-serializable snapshot from a contract. Keys are
+ * sorted so two snapshots of the same logical contract are byte-identical —
+ * important for clean `git diff`s and stable CI comparisons.
+ */
+declare function contractToSnapshot(contract: TelemetryContract): ContractSnapshot;
+/** Pretty, deterministic JSON for writing a snapshot to disk. */
+declare function serializeSnapshot(snapshot: ContractSnapshot): string;
+/** Parse and structurally validate a snapshot read from disk. */
+declare function parseSnapshot(json: string): ContractSnapshot;
+//#endregion
+//#region src/diff.d.ts
+type ChangeKind = 'breaking' | 'additive' | 'neutral';
+type ChangeType = 'span_removed' | 'span_added' | 'attribute_removed' | 'attribute_added' | 'type_changed' | 'required_added' | 'required_removed' | 'enum_value_removed' | 'enum_value_added' | 'stability_downgraded' | 'stability_advanced' | 'deprecated' | 'replacement_documented';
+interface SnapshotChange {
+  kind: ChangeKind;
+  type: ChangeType;
+  /** Span the change applies to (`*` = common attributes / contract-wide). */
+  span: string;
+  attribute?: string;
+  message: string;
+}
+interface SnapshotDiff {
+  service: string;
+  previousVersion: string;
+  nextVersion: string;
+  breaking: SnapshotChange[];
+  additive: SnapshotChange[];
+  neutral: SnapshotChange[];
+}
+/**
+ * Diff two snapshots, classifying every change. The `breaking` array is what a
+ * CI gate keys off; `hasBreakingChanges()` is the convenience predicate.
+ */
+declare function diffSnapshots(previous: ContractSnapshot, next: ContractSnapshot): SnapshotDiff;
+/** `true` when the diff contains at least one breaking change. */
+declare function hasBreakingChanges(diff: SnapshotDiff): boolean;
+/** Markdown rendering of a diff — for CI logs and PR comments. */
+declare function formatDiff(diff: SnapshotDiff): string;
+//#endregion
+export { diffSnapshots as a, ContractSnapshot as c, contractToSnapshot as d, parseSnapshot as f, SchemaAttributeKey as g, SNAPSHOT_SPEC as h, SnapshotDiff as i, SnapshotAttribute as l, SCHEMA_ATTRS as m, ChangeType as n, formatDiff as o, serializeSnapshot as p, SnapshotChange as r, hasBreakingChanges as s, ChangeKind as t, SnapshotSpan as u };
+//# sourceMappingURL=diff-BQPh72vY.d.cts.map

package/dist/diff-BQPh72vY.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-BQPh72vY.d.cts","names":[],"sources":["../src/attrs.ts","../src/snapshot.ts","../src/diff.ts"],"mappings":";;;;;;AAYA;;;;;AAOA;;;cAPa,YAAA;EAOmE,6EAFtE,OAAA,8BAKwD;EAAA,SALxD,OAAA;AAAA;AAAA,KAEE,kBAAA,WAA6B,YAAA,eAA2B,YAAY;;cAGnE,aAAA;;;AAHb;AAAA,UCHiB,iBAAA;EACf,IAAA,EAAM,aAAA;EACN,SAAA,EAAW,SAAS;EACpB,QAAA;EACA,eAAA;EACA,IAAA;EACA,UAAA;EACA,WAAA;AAAA;AAAA,UAGe,YAAA;EACf,SAAA,EAAW,SAAA;EACX,oBAAA;EACA,WAAA;EACA,UAAA,EAAY,MAAA,SAAe,iBAAA;AAAA;;UAIZ,gBAAA;EACf,IAAA,SAAa,aAAA;EACb,OAAA;EACA,OAAA;EACA,gBAAA,EAAkB,MAAA,SAAe,iBAAA;EACjC,KAAA,EAAO,MAAA,SAAe,YAAA;AAAA;;;;AAhBX;AAGb;iBA0CgB,kBAAA,CACd,QAAA,EAAU,iBAAA,GACT,gBAAgB;;iBAgCH,iBAAA,CAAkB,QAA0B,EAAhB,gBAAgB;;iBAK5C,aAAA,CAAc,IAAA,WAAe,gBAAgB;;;KC/FjD,UAAA;AAAA,KAEA,UAAA;AAAA,UAeK,cAAA;EACf,IAAA,EAAM,UAAA;EACN,IAAA,EAAM,UAAU;;EAEhB,IAAA;EACA,SAAA;EACA,OAAA;AAAA;AAAA,UAGe,YAAA;EACf,OAAA;EACA,eAAA;EACA,WAAA;EACA,QAAA,EAAU,cAAA;EACV,QAAA,EAAU,cAAA;EACV,OAAA,EAAS,cAAA;AAAA;;;;;iBAqKK,aAAA,CACd,QAAA,EAAU,gBAAA,EACV,IAAA,EAAM,gBAAA,GACL,YAAA;;iBAwCa,kBAAA,CAAmB,IAAkB,EAAZ,YAAY;ADrOxC;AAAA,iBC0OG,UAAA,CAAW,IAAkB,EAAZ,YAAY"}

package/dist/diff-D7qkNn0-.d.ts

@@ -0,0 +1,89 @@
+import { o as Stability, r as AttributeType, s as TelemetryContract } from "./contract-DGjxR9nb.js";
+
+//#region src/attrs.d.ts
+/**
+ * Wire constants for the schema contract — the keys autotel-schema reads from
+ * and stamps onto spans. Dependency-free so CLI, browser, and edge code can
+ * share the exact same strings the runtime uses.
+ */
+/**
+ * Resource/span attributes that announce the contract to a reader. Stamping
+ * `telemetry.schema.version` means an agent following a trace knows *which*
+ * version of your public telemetry API it is looking at — the difference
+ * between "confidently correct" and "confidently wrong" after a rename.
+ */
+declare const SCHEMA_ATTRS: {
+  /** The service this contract describes (mirrors `service.name`). */readonly SERVICE: "telemetry.schema.service"; /** Semver of the telemetry contract that produced this span. */
+  readonly VERSION: "telemetry.schema.version";
+};
+type SchemaAttributeKey = (typeof SCHEMA_ATTRS)[keyof typeof SCHEMA_ATTRS];
+/** Snapshot file spec marker — bump only on a breaking snapshot format change. */
+declare const SNAPSHOT_SPEC: "autotel-schema-snapshot/v1";
+//#endregion
+//#region src/snapshot.d.ts
+/** Flattened, fully-resolved attribute record in a snapshot. */
+interface SnapshotAttribute {
+  type: AttributeType;
+  stability: Stability;
+  required: boolean;
+  highCardinality: boolean;
+  enum?: readonly (string | number)[];
+  replacedBy?: string;
+  description?: string;
+}
+interface SnapshotSpan {
+  stability: Stability;
+  additionalAttributes: boolean;
+  description?: string;
+  attributes: Record<string, SnapshotAttribute>;
+}
+/** Canonical, comparable representation of a {@link TelemetryContract}. */
+interface ContractSnapshot {
+  spec: typeof SNAPSHOT_SPEC;
+  service: string;
+  version: string;
+  commonAttributes: Record<string, SnapshotAttribute>;
+  spans: Record<string, SnapshotSpan>;
+}
+/**
+ * Produce a deterministic, JSON-serializable snapshot from a contract. Keys are
+ * sorted so two snapshots of the same logical contract are byte-identical —
+ * important for clean `git diff`s and stable CI comparisons.
+ */
+declare function contractToSnapshot(contract: TelemetryContract): ContractSnapshot;
+/** Pretty, deterministic JSON for writing a snapshot to disk. */
+declare function serializeSnapshot(snapshot: ContractSnapshot): string;
+/** Parse and structurally validate a snapshot read from disk. */
+declare function parseSnapshot(json: string): ContractSnapshot;
+//#endregion
+//#region src/diff.d.ts
+type ChangeKind = 'breaking' | 'additive' | 'neutral';
+type ChangeType = 'span_removed' | 'span_added' | 'attribute_removed' | 'attribute_added' | 'type_changed' | 'required_added' | 'required_removed' | 'enum_value_removed' | 'enum_value_added' | 'stability_downgraded' | 'stability_advanced' | 'deprecated' | 'replacement_documented';
+interface SnapshotChange {
+  kind: ChangeKind;
+  type: ChangeType;
+  /** Span the change applies to (`*` = common attributes / contract-wide). */
+  span: string;
+  attribute?: string;
+  message: string;
+}
+interface SnapshotDiff {
+  service: string;
+  previousVersion: string;
+  nextVersion: string;
+  breaking: SnapshotChange[];
+  additive: SnapshotChange[];
+  neutral: SnapshotChange[];
+}
+/**
+ * Diff two snapshots, classifying every change. The `breaking` array is what a
+ * CI gate keys off; `hasBreakingChanges()` is the convenience predicate.
+ */
+declare function diffSnapshots(previous: ContractSnapshot, next: ContractSnapshot): SnapshotDiff;
+/** `true` when the diff contains at least one breaking change. */
+declare function hasBreakingChanges(diff: SnapshotDiff): boolean;
+/** Markdown rendering of a diff — for CI logs and PR comments. */
+declare function formatDiff(diff: SnapshotDiff): string;
+//#endregion
+export { diffSnapshots as a, ContractSnapshot as c, contractToSnapshot as d, parseSnapshot as f, SchemaAttributeKey as g, SNAPSHOT_SPEC as h, SnapshotDiff as i, SnapshotAttribute as l, SCHEMA_ATTRS as m, ChangeType as n, formatDiff as o, serializeSnapshot as p, SnapshotChange as r, hasBreakingChanges as s, ChangeKind as t, SnapshotSpan as u };
+//# sourceMappingURL=diff-D7qkNn0-.d.ts.map

package/dist/diff-D7qkNn0-.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-D7qkNn0-.d.ts","names":[],"sources":["../src/attrs.ts","../src/snapshot.ts","../src/diff.ts"],"mappings":";;;;;;AAYA;;;;;AAOA;;;cAPa,YAAA;EAOmE,6EAFtE,OAAA,8BAKwD;EAAA,SALxD,OAAA;AAAA;AAAA,KAEE,kBAAA,WAA6B,YAAA,eAA2B,YAAY;;cAGnE,aAAA;;;AAHb;AAAA,UCHiB,iBAAA;EACf,IAAA,EAAM,aAAA;EACN,SAAA,EAAW,SAAS;EACpB,QAAA;EACA,eAAA;EACA,IAAA;EACA,UAAA;EACA,WAAA;AAAA;AAAA,UAGe,YAAA;EACf,SAAA,EAAW,SAAA;EACX,oBAAA;EACA,WAAA;EACA,UAAA,EAAY,MAAA,SAAe,iBAAA;AAAA;;UAIZ,gBAAA;EACf,IAAA,SAAa,aAAA;EACb,OAAA;EACA,OAAA;EACA,gBAAA,EAAkB,MAAA,SAAe,iBAAA;EACjC,KAAA,EAAO,MAAA,SAAe,YAAA;AAAA;;;;AAhBX;AAGb;iBA0CgB,kBAAA,CACd,QAAA,EAAU,iBAAA,GACT,gBAAgB;;iBAgCH,iBAAA,CAAkB,QAA0B,EAAhB,gBAAgB;;iBAK5C,aAAA,CAAc,IAAA,WAAe,gBAAgB;;;KC/FjD,UAAA;AAAA,KAEA,UAAA;AAAA,UAeK,cAAA;EACf,IAAA,EAAM,UAAA;EACN,IAAA,EAAM,UAAU;;EAEhB,IAAA;EACA,SAAA;EACA,OAAA;AAAA;AAAA,UAGe,YAAA;EACf,OAAA;EACA,eAAA;EACA,WAAA;EACA,QAAA,EAAU,cAAA;EACV,QAAA,EAAU,cAAA;EACV,OAAA,EAAS,cAAA;AAAA;;;;;iBAqKK,aAAA,CACd,QAAA,EAAU,gBAAA,EACV,IAAA,EAAM,gBAAA,GACL,YAAA;;iBAwCa,kBAAA,CAAmB,IAAkB,EAAZ,YAAY;ADrOxC;AAAA,iBC0OG,UAAA,CAAW,IAAkB,EAAZ,YAAY"}

package/dist/diff.cjs

@@ -0,0 +1,185 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/diff.ts
+/**
+* How every cross-stability transition is classified. Keyed `prev->next` so all
+* six transitions are explicit and auditable — no silent fall-through. Same-
+* stability transitions are absent (no change to report).
+*/
+const STABILITY_TRANSITIONS = {
+	"stable->experimental": {
+		kind: "breaking",
+		type: "stability_downgraded"
+	},
+	"stable->deprecated": {
+		kind: "additive",
+		type: "deprecated"
+	},
+	"experimental->stable": {
+		kind: "neutral",
+		type: "stability_advanced"
+	},
+	"experimental->deprecated": {
+		kind: "additive",
+		type: "deprecated"
+	},
+	"deprecated->stable": {
+		kind: "neutral",
+		type: "stability_advanced"
+	},
+	"deprecated->experimental": {
+		kind: "breaking",
+		type: "stability_downgraded"
+	}
+};
+function stabilityMessage(type, attribute, prev, next) {
+	if (type === "deprecated") return `attribute "${attribute}" was deprecated${next.replacedBy ? ` (use "${next.replacedBy}")` : ""}`;
+	if (type === "stability_downgraded") return `attribute "${attribute}" stability downgraded ${prev.stability} → ${next.stability}`;
+	return `attribute "${attribute}" promoted ${prev.stability} → ${next.stability}`;
+}
+function push(diff, change) {
+	if (change.kind === "breaking") diff.breaking.push(change);
+	else if (change.kind === "additive") diff.additive.push(change);
+	else diff.neutral.push(change);
+}
+function diffAttribute(diff, span, attribute, prev, next) {
+	if (prev.type !== next.type) push(diff, {
+		kind: "breaking",
+		type: "type_changed",
+		span,
+		attribute,
+		message: `attribute "${attribute}" changed type ${prev.type} → ${next.type}`
+	});
+	if (!prev.required && next.required) push(diff, {
+		kind: "breaking",
+		type: "required_added",
+		span,
+		attribute,
+		message: `attribute "${attribute}" became required`
+	});
+	else if (prev.required && !next.required) push(diff, {
+		kind: "additive",
+		type: "required_removed",
+		span,
+		attribute,
+		message: `attribute "${attribute}" is no longer required`
+	});
+	if (prev.enum && next.enum) {
+		const nextSet = new Set(next.enum);
+		const removed = prev.enum.filter((v) => !nextSet.has(v));
+		const prevSet = new Set(prev.enum);
+		const added = next.enum.filter((v) => !prevSet.has(v));
+		if (removed.length > 0) push(diff, {
+			kind: "breaking",
+			type: "enum_value_removed",
+			span,
+			attribute,
+			message: `attribute "${attribute}" dropped enum value(s) ${JSON.stringify(removed)}`
+		});
+		if (added.length > 0) push(diff, {
+			kind: "additive",
+			type: "enum_value_added",
+			span,
+			attribute,
+			message: `attribute "${attribute}" added enum value(s) ${JSON.stringify(added)}`
+		});
+	}
+	if (prev.stability !== next.stability) {
+		const transition = STABILITY_TRANSITIONS[`${prev.stability}->${next.stability}`];
+		if (transition) push(diff, {
+			...transition,
+			span,
+			attribute,
+			message: stabilityMessage(transition.type, attribute, prev, next)
+		});
+	}
+}
+function diffAttributeMaps(diff, span, prev, next) {
+	for (const [key, prevAttr] of Object.entries(prev)) {
+		const nextAttr = next[key];
+		if (!nextAttr) {
+			push(diff, {
+				kind: "breaking",
+				type: prevAttr.replacedBy ? "replacement_documented" : "attribute_removed",
+				span,
+				attribute: key,
+				message: prevAttr.replacedBy ? `attribute "${key}" removed — replaced by "${prevAttr.replacedBy}"` : `attribute "${key}" was removed`
+			});
+			continue;
+		}
+		diffAttribute(diff, span, key, prevAttr, nextAttr);
+	}
+	for (const key of Object.keys(next)) if (!prev[key]) {
+		const added = next[key];
+		push(diff, {
+			kind: added.required ? "breaking" : "additive",
+			type: "attribute_added",
+			span,
+			attribute: key,
+			message: added.required ? `new required attribute "${key}" added` : `new attribute "${key}" added`
+		});
+	}
+}
+/**
+* Diff two snapshots, classifying every change. The `breaking` array is what a
+* CI gate keys off; `hasBreakingChanges()` is the convenience predicate.
+*/
+function diffSnapshots(previous, next) {
+	const diff = {
+		service: next.service,
+		previousVersion: previous.version,
+		nextVersion: next.version,
+		breaking: [],
+		additive: [],
+		neutral: []
+	};
+	diffAttributeMaps(diff, "*", previous.commonAttributes, next.commonAttributes);
+	for (const [name, prevSpan] of Object.entries(previous.spans)) {
+		const nextSpan = next.spans[name];
+		if (!nextSpan) {
+			push(diff, {
+				kind: "breaking",
+				type: "span_removed",
+				span: name,
+				message: `span "${name}" was removed`
+			});
+			continue;
+		}
+		diffAttributeMaps(diff, name, prevSpan.attributes, nextSpan.attributes);
+	}
+	for (const name of Object.keys(next.spans)) if (!previous.spans[name]) push(diff, {
+		kind: "additive",
+		type: "span_added",
+		span: name,
+		message: `new span "${name}" added`
+	});
+	return diff;
+}
+/** `true` when the diff contains at least one breaking change. */
+function hasBreakingChanges(diff) {
+	return diff.breaking.length > 0;
+}
+/** Markdown rendering of a diff — for CI logs and PR comments. */
+function formatDiff(diff) {
+	const lines = [`# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`, ""];
+	const section = (title, changes) => {
+		if (changes.length === 0) return;
+		lines.push(`## ${title} (${changes.length})`, "");
+		for (const c of changes) {
+			const where = c.attribute ? `\`${c.span}.${c.attribute}\`` : `\`${c.span}\``;
+			lines.push(`- ${where}: ${c.message}`);
+		}
+		lines.push("");
+	};
+	section("💥 Breaking", diff.breaking);
+	section("➕ Additive", diff.additive);
+	section("• Neutral", diff.neutral);
+	if (diff.breaking.length === 0 && diff.additive.length === 0 && diff.neutral.length === 0) lines.push("No changes to the telemetry contract.", "");
+	return lines.join("\n");
+}
+
+//#endregion
+exports.diffSnapshots = diffSnapshots;
+exports.formatDiff = formatDiff;
+exports.hasBreakingChanges = hasBreakingChanges;
+//# sourceMappingURL=diff.cjs.map

package/dist/diff.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.cjs","names":[],"sources":["../src/diff.ts"],"sourcesContent":["/**\n * Snapshot diffing — the CI gate that catches breaking changes to your trace\n * surface before they ship.\n *\n * \"If you wouldn't ship a rename to your public API without a changelog, don't\n * do it to your traces.\" This module is what makes that enforceable: classify\n * every change between two snapshots as breaking, additive, or neutral, and let\n * CI fail on the breaking ones.\n */\n\nimport type { ContractSnapshot, SnapshotAttribute } from './snapshot.js';\n\nexport type ChangeKind = 'breaking' | 'additive' | 'neutral';\n\nexport type ChangeType =\n  | 'span_removed'\n  | 'span_added'\n  | 'attribute_removed'\n  | 'attribute_added'\n  | 'type_changed'\n  | 'required_added'\n  | 'required_removed'\n  | 'enum_value_removed'\n  | 'enum_value_added'\n  | 'stability_downgraded'\n  | 'stability_advanced'\n  | 'deprecated'\n  | 'replacement_documented';\n\nexport interface SnapshotChange {\n  kind: ChangeKind;\n  type: ChangeType;\n  /** Span the change applies to (`*` = common attributes / contract-wide). */\n  span: string;\n  attribute?: string;\n  message: string;\n}\n\nexport interface SnapshotDiff {\n  service: string;\n  previousVersion: string;\n  nextVersion: string;\n  breaking: SnapshotChange[];\n  additive: SnapshotChange[];\n  neutral: SnapshotChange[];\n}\n\n/**\n * How every cross-stability transition is classified. Keyed `prev->next` so all\n * six transitions are explicit and auditable — no silent fall-through. Same-\n * stability transitions are absent (no change to report).\n */\nconst STABILITY_TRANSITIONS: Record<\n  string,\n  { kind: ChangeKind; type: ChangeType }\n> = {\n  'stable->experimental': { kind: 'breaking', type: 'stability_downgraded' },\n  'stable->deprecated': { kind: 'additive', type: 'deprecated' },\n  'experimental->stable': { kind: 'neutral', type: 'stability_advanced' },\n  'experimental->deprecated': { kind: 'additive', type: 'deprecated' },\n  'deprecated->stable': { kind: 'neutral', type: 'stability_advanced' },\n  'deprecated->experimental': { kind: 'breaking', type: 'stability_downgraded' },\n};\n\nfunction stabilityMessage(\n  type: ChangeType,\n  attribute: string,\n  prev: SnapshotAttribute,\n  next: SnapshotAttribute,\n): string {\n  if (type === 'deprecated') {\n    return `attribute \"${attribute}\" was deprecated${next.replacedBy ? ` (use \"${next.replacedBy}\")` : ''}`;\n  }\n  if (type === 'stability_downgraded') {\n    return `attribute \"${attribute}\" stability downgraded ${prev.stability} → ${next.stability}`;\n  }\n  return `attribute \"${attribute}\" promoted ${prev.stability} → ${next.stability}`;\n}\n\nfunction push(\n  diff: SnapshotDiff,\n  change: SnapshotChange,\n): void {\n  if (change.kind === 'breaking') diff.breaking.push(change);\n  else if (change.kind === 'additive') diff.additive.push(change);\n  else diff.neutral.push(change);\n}\n\nfunction diffAttribute(\n  diff: SnapshotDiff,\n  span: string,\n  attribute: string,\n  prev: SnapshotAttribute,\n  next: SnapshotAttribute,\n): void {\n  if (prev.type !== next.type) {\n    push(diff, {\n      kind: 'breaking',\n      type: 'type_changed',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" changed type ${prev.type} → ${next.type}`,\n    });\n  }\n\n  if (!prev.required && next.required) {\n    push(diff, {\n      kind: 'breaking',\n      type: 'required_added',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" became required`,\n    });\n  } else if (prev.required && !next.required) {\n    push(diff, {\n      kind: 'additive',\n      type: 'required_removed',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" is no longer required`,\n    });\n  }\n\n  // Enum: removing a permitted value can break a producer that still emits it.\n  if (prev.enum && next.enum) {\n    const nextSet = new Set(next.enum);\n    const removed = prev.enum.filter((v) => !nextSet.has(v));\n    const prevSet = new Set(prev.enum);\n    const added = next.enum.filter((v) => !prevSet.has(v));\n    if (removed.length > 0) {\n      push(diff, {\n        kind: 'breaking',\n        type: 'enum_value_removed',\n        span,\n        attribute,\n        message: `attribute \"${attribute}\" dropped enum value(s) ${JSON.stringify(removed)}`,\n      });\n    }\n    if (added.length > 0) {\n      push(diff, {\n        kind: 'additive',\n        type: 'enum_value_added',\n        span,\n        attribute,\n        message: `attribute \"${attribute}\" added enum value(s) ${JSON.stringify(added)}`,\n      });\n    }\n  }\n\n  if (prev.stability !== next.stability) {\n    const transition =\n      STABILITY_TRANSITIONS[`${prev.stability}->${next.stability}`];\n    if (transition) {\n      push(diff, {\n        ...transition,\n        span,\n        attribute,\n        message: stabilityMessage(transition.type, attribute, prev, next),\n      });\n    }\n  }\n}\n\nfunction diffAttributeMaps(\n  diff: SnapshotDiff,\n  span: string,\n  prev: Record<string, SnapshotAttribute>,\n  next: Record<string, SnapshotAttribute>,\n): void {\n  for (const [key, prevAttr] of Object.entries(prev)) {\n    const nextAttr = next[key];\n    if (!nextAttr) {\n      // A removed attribute whose replacement is named is a documented\n      // migration (still breaking — but reported as such with the pointer).\n      push(diff, {\n        kind: 'breaking',\n        type: prevAttr.replacedBy ? 'replacement_documented' : 'attribute_removed',\n        span,\n        attribute: key,\n        message: prevAttr.replacedBy\n          ? `attribute \"${key}\" removed — replaced by \"${prevAttr.replacedBy}\"`\n          : `attribute \"${key}\" was removed`,\n      });\n      continue;\n    }\n    diffAttribute(diff, span, key, prevAttr, nextAttr);\n  }\n  for (const key of Object.keys(next)) {\n    if (!prev[key]) {\n      const added = next[key];\n      // Always `attribute_added` (the event is \"new attribute\"); severity rides\n      // on `kind` — a new *required* attribute breaks existing producers.\n      push(diff, {\n        kind: added.required ? 'breaking' : 'additive',\n        type: 'attribute_added',\n        span,\n        attribute: key,\n        message: added.required\n          ? `new required attribute \"${key}\" added`\n          : `new attribute \"${key}\" added`,\n      });\n    }\n  }\n}\n\n/**\n * Diff two snapshots, classifying every change. The `breaking` array is what a\n * CI gate keys off; `hasBreakingChanges()` is the convenience predicate.\n */\nexport function diffSnapshots(\n  previous: ContractSnapshot,\n  next: ContractSnapshot,\n): SnapshotDiff {\n  const diff: SnapshotDiff = {\n    service: next.service,\n    previousVersion: previous.version,\n    nextVersion: next.version,\n    breaking: [],\n    additive: [],\n    neutral: [],\n  };\n\n  diffAttributeMaps(diff, '*', previous.commonAttributes, next.commonAttributes);\n\n  for (const [name, prevSpan] of Object.entries(previous.spans)) {\n    const nextSpan = next.spans[name];\n    if (!nextSpan) {\n      push(diff, {\n        kind: 'breaking',\n        type: 'span_removed',\n        span: name,\n        message: `span \"${name}\" was removed`,\n      });\n      continue;\n    }\n    diffAttributeMaps(diff, name, prevSpan.attributes, nextSpan.attributes);\n  }\n  for (const name of Object.keys(next.spans)) {\n    if (!previous.spans[name]) {\n      push(diff, {\n        kind: 'additive',\n        type: 'span_added',\n        span: name,\n        message: `new span \"${name}\" added`,\n      });\n    }\n  }\n\n  return diff;\n}\n\n/** `true` when the diff contains at least one breaking change. */\nexport function hasBreakingChanges(diff: SnapshotDiff): boolean {\n  return diff.breaking.length > 0;\n}\n\n/** Markdown rendering of a diff — for CI logs and PR comments. */\nexport function formatDiff(diff: SnapshotDiff): string {\n  const lines: string[] = [ \n    `# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`,\n    ''];\n  const section = (title: string, changes: SnapshotChange[]) => {\n    if (changes.length === 0) return;\n    lines.push(`## ${title} (${changes.length})`, '');\n    for (const c of changes) {\n      const where = c.attribute ? `\\`${c.span}.${c.attribute}\\`` : `\\`${c.span}\\``;\n      lines.push(`- ${where}: ${c.message}`);\n    }\n    lines.push('');\n  };\n  section('💥 Breaking', diff.breaking);\n  section('➕ Additive', diff.additive);\n  section('• Neutral', diff.neutral);\n  if (\n    diff.breaking.length === 0 &&\n    diff.additive.length === 0 &&\n    diff.neutral.length === 0\n  ) {\n    lines.push('No changes to the telemetry contract.', '');\n  }\n  return lines.join('\\n');\n}\n"],"mappings":"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"}

package/dist/diff.d.cts

@@ -0,0 +1,2 @@
+import { a as diffSnapshots, i as SnapshotDiff, n as ChangeType, o as formatDiff, r as SnapshotChange, s as hasBreakingChanges, t as ChangeKind } from "./diff-BQPh72vY.cjs";
+export { ChangeKind, ChangeType, SnapshotChange, SnapshotDiff, diffSnapshots, formatDiff, hasBreakingChanges };

package/dist/diff.d.ts

@@ -0,0 +1,2 @@
+import { a as diffSnapshots, i as SnapshotDiff, n as ChangeType, o as formatDiff, r as SnapshotChange, s as hasBreakingChanges, t as ChangeKind } from "./diff-D7qkNn0-.js";
+export { ChangeKind, ChangeType, SnapshotChange, SnapshotDiff, diffSnapshots, formatDiff, hasBreakingChanges };

package/dist/diff.js

@@ -0,0 +1,181 @@
+//#region src/diff.ts
+/**
+* How every cross-stability transition is classified. Keyed `prev->next` so all
+* six transitions are explicit and auditable — no silent fall-through. Same-
+* stability transitions are absent (no change to report).
+*/
+const STABILITY_TRANSITIONS = {
+	"stable->experimental": {
+		kind: "breaking",
+		type: "stability_downgraded"
+	},
+	"stable->deprecated": {
+		kind: "additive",
+		type: "deprecated"
+	},
+	"experimental->stable": {
+		kind: "neutral",
+		type: "stability_advanced"
+	},
+	"experimental->deprecated": {
+		kind: "additive",
+		type: "deprecated"
+	},
+	"deprecated->stable": {
+		kind: "neutral",
+		type: "stability_advanced"
+	},
+	"deprecated->experimental": {
+		kind: "breaking",
+		type: "stability_downgraded"
+	}
+};
+function stabilityMessage(type, attribute, prev, next) {
+	if (type === "deprecated") return `attribute "${attribute}" was deprecated${next.replacedBy ? ` (use "${next.replacedBy}")` : ""}`;
+	if (type === "stability_downgraded") return `attribute "${attribute}" stability downgraded ${prev.stability} → ${next.stability}`;
+	return `attribute "${attribute}" promoted ${prev.stability} → ${next.stability}`;
+}
+function push(diff, change) {
+	if (change.kind === "breaking") diff.breaking.push(change);
+	else if (change.kind === "additive") diff.additive.push(change);
+	else diff.neutral.push(change);
+}
+function diffAttribute(diff, span, attribute, prev, next) {
+	if (prev.type !== next.type) push(diff, {
+		kind: "breaking",
+		type: "type_changed",
+		span,
+		attribute,
+		message: `attribute "${attribute}" changed type ${prev.type} → ${next.type}`
+	});
+	if (!prev.required && next.required) push(diff, {
+		kind: "breaking",
+		type: "required_added",
+		span,
+		attribute,
+		message: `attribute "${attribute}" became required`
+	});
+	else if (prev.required && !next.required) push(diff, {
+		kind: "additive",
+		type: "required_removed",
+		span,
+		attribute,
+		message: `attribute "${attribute}" is no longer required`
+	});
+	if (prev.enum && next.enum) {
+		const nextSet = new Set(next.enum);
+		const removed = prev.enum.filter((v) => !nextSet.has(v));
+		const prevSet = new Set(prev.enum);
+		const added = next.enum.filter((v) => !prevSet.has(v));
+		if (removed.length > 0) push(diff, {
+			kind: "breaking",
+			type: "enum_value_removed",
+			span,
+			attribute,
+			message: `attribute "${attribute}" dropped enum value(s) ${JSON.stringify(removed)}`
+		});
+		if (added.length > 0) push(diff, {
+			kind: "additive",
+			type: "enum_value_added",
+			span,
+			attribute,
+			message: `attribute "${attribute}" added enum value(s) ${JSON.stringify(added)}`
+		});
+	}
+	if (prev.stability !== next.stability) {
+		const transition = STABILITY_TRANSITIONS[`${prev.stability}->${next.stability}`];
+		if (transition) push(diff, {
+			...transition,
+			span,
+			attribute,
+			message: stabilityMessage(transition.type, attribute, prev, next)
+		});
+	}
+}
+function diffAttributeMaps(diff, span, prev, next) {
+	for (const [key, prevAttr] of Object.entries(prev)) {
+		const nextAttr = next[key];
+		if (!nextAttr) {
+			push(diff, {
+				kind: "breaking",
+				type: prevAttr.replacedBy ? "replacement_documented" : "attribute_removed",
+				span,
+				attribute: key,
+				message: prevAttr.replacedBy ? `attribute "${key}" removed — replaced by "${prevAttr.replacedBy}"` : `attribute "${key}" was removed`
+			});
+			continue;
+		}
+		diffAttribute(diff, span, key, prevAttr, nextAttr);
+	}
+	for (const key of Object.keys(next)) if (!prev[key]) {
+		const added = next[key];
+		push(diff, {
+			kind: added.required ? "breaking" : "additive",
+			type: "attribute_added",
+			span,
+			attribute: key,
+			message: added.required ? `new required attribute "${key}" added` : `new attribute "${key}" added`
+		});
+	}
+}
+/**
+* Diff two snapshots, classifying every change. The `breaking` array is what a
+* CI gate keys off; `hasBreakingChanges()` is the convenience predicate.
+*/
+function diffSnapshots(previous, next) {
+	const diff = {
+		service: next.service,
+		previousVersion: previous.version,
+		nextVersion: next.version,
+		breaking: [],
+		additive: [],
+		neutral: []
+	};
+	diffAttributeMaps(diff, "*", previous.commonAttributes, next.commonAttributes);
+	for (const [name, prevSpan] of Object.entries(previous.spans)) {
+		const nextSpan = next.spans[name];
+		if (!nextSpan) {
+			push(diff, {
+				kind: "breaking",
+				type: "span_removed",
+				span: name,
+				message: `span "${name}" was removed`
+			});
+			continue;
+		}
+		diffAttributeMaps(diff, name, prevSpan.attributes, nextSpan.attributes);
+	}
+	for (const name of Object.keys(next.spans)) if (!previous.spans[name]) push(diff, {
+		kind: "additive",
+		type: "span_added",
+		span: name,
+		message: `new span "${name}" added`
+	});
+	return diff;
+}
+/** `true` when the diff contains at least one breaking change. */
+function hasBreakingChanges(diff) {
+	return diff.breaking.length > 0;
+}
+/** Markdown rendering of a diff — for CI logs and PR comments. */
+function formatDiff(diff) {
+	const lines = [`# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`, ""];
+	const section = (title, changes) => {
+		if (changes.length === 0) return;
+		lines.push(`## ${title} (${changes.length})`, "");
+		for (const c of changes) {
+			const where = c.attribute ? `\`${c.span}.${c.attribute}\`` : `\`${c.span}\``;
+			lines.push(`- ${where}: ${c.message}`);
+		}
+		lines.push("");
+	};
+	section("💥 Breaking", diff.breaking);
+	section("➕ Additive", diff.additive);
+	section("• Neutral", diff.neutral);
+	if (diff.breaking.length === 0 && diff.additive.length === 0 && diff.neutral.length === 0) lines.push("No changes to the telemetry contract.", "");
+	return lines.join("\n");
+}
+
+//#endregion
+export { diffSnapshots, formatDiff, hasBreakingChanges };
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","names":[],"sources":["../src/diff.ts"],"sourcesContent":["/**\n * Snapshot diffing — the CI gate that catches breaking changes to your trace\n * surface before they ship.\n *\n * \"If you wouldn't ship a rename to your public API without a changelog, don't\n * do it to your traces.\" This module is what makes that enforceable: classify\n * every change between two snapshots as breaking, additive, or neutral, and let\n * CI fail on the breaking ones.\n */\n\nimport type { ContractSnapshot, SnapshotAttribute } from './snapshot.js';\n\nexport type ChangeKind = 'breaking' | 'additive' | 'neutral';\n\nexport type ChangeType =\n  | 'span_removed'\n  | 'span_added'\n  | 'attribute_removed'\n  | 'attribute_added'\n  | 'type_changed'\n  | 'required_added'\n  | 'required_removed'\n  | 'enum_value_removed'\n  | 'enum_value_added'\n  | 'stability_downgraded'\n  | 'stability_advanced'\n  | 'deprecated'\n  | 'replacement_documented';\n\nexport interface SnapshotChange {\n  kind: ChangeKind;\n  type: ChangeType;\n  /** Span the change applies to (`*` = common attributes / contract-wide). */\n  span: string;\n  attribute?: string;\n  message: string;\n}\n\nexport interface SnapshotDiff {\n  service: string;\n  previousVersion: string;\n  nextVersion: string;\n  breaking: SnapshotChange[];\n  additive: SnapshotChange[];\n  neutral: SnapshotChange[];\n}\n\n/**\n * How every cross-stability transition is classified. Keyed `prev->next` so all\n * six transitions are explicit and auditable — no silent fall-through. Same-\n * stability transitions are absent (no change to report).\n */\nconst STABILITY_TRANSITIONS: Record<\n  string,\n  { kind: ChangeKind; type: ChangeType }\n> = {\n  'stable->experimental': { kind: 'breaking', type: 'stability_downgraded' },\n  'stable->deprecated': { kind: 'additive', type: 'deprecated' },\n  'experimental->stable': { kind: 'neutral', type: 'stability_advanced' },\n  'experimental->deprecated': { kind: 'additive', type: 'deprecated' },\n  'deprecated->stable': { kind: 'neutral', type: 'stability_advanced' },\n  'deprecated->experimental': { kind: 'breaking', type: 'stability_downgraded' },\n};\n\nfunction stabilityMessage(\n  type: ChangeType,\n  attribute: string,\n  prev: SnapshotAttribute,\n  next: SnapshotAttribute,\n): string {\n  if (type === 'deprecated') {\n    return `attribute \"${attribute}\" was deprecated${next.replacedBy ? ` (use \"${next.replacedBy}\")` : ''}`;\n  }\n  if (type === 'stability_downgraded') {\n    return `attribute \"${attribute}\" stability downgraded ${prev.stability} → ${next.stability}`;\n  }\n  return `attribute \"${attribute}\" promoted ${prev.stability} → ${next.stability}`;\n}\n\nfunction push(\n  diff: SnapshotDiff,\n  change: SnapshotChange,\n): void {\n  if (change.kind === 'breaking') diff.breaking.push(change);\n  else if (change.kind === 'additive') diff.additive.push(change);\n  else diff.neutral.push(change);\n}\n\nfunction diffAttribute(\n  diff: SnapshotDiff,\n  span: string,\n  attribute: string,\n  prev: SnapshotAttribute,\n  next: SnapshotAttribute,\n): void {\n  if (prev.type !== next.type) {\n    push(diff, {\n      kind: 'breaking',\n      type: 'type_changed',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" changed type ${prev.type} → ${next.type}`,\n    });\n  }\n\n  if (!prev.required && next.required) {\n    push(diff, {\n      kind: 'breaking',\n      type: 'required_added',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" became required`,\n    });\n  } else if (prev.required && !next.required) {\n    push(diff, {\n      kind: 'additive',\n      type: 'required_removed',\n      span,\n      attribute,\n      message: `attribute \"${attribute}\" is no longer required`,\n    });\n  }\n\n  // Enum: removing a permitted value can break a producer that still emits it.\n  if (prev.enum && next.enum) {\n    const nextSet = new Set(next.enum);\n    const removed = prev.enum.filter((v) => !nextSet.has(v));\n    const prevSet = new Set(prev.enum);\n    const added = next.enum.filter((v) => !prevSet.has(v));\n    if (removed.length > 0) {\n      push(diff, {\n        kind: 'breaking',\n        type: 'enum_value_removed',\n        span,\n        attribute,\n        message: `attribute \"${attribute}\" dropped enum value(s) ${JSON.stringify(removed)}`,\n      });\n    }\n    if (added.length > 0) {\n      push(diff, {\n        kind: 'additive',\n        type: 'enum_value_added',\n        span,\n        attribute,\n        message: `attribute \"${attribute}\" added enum value(s) ${JSON.stringify(added)}`,\n      });\n    }\n  }\n\n  if (prev.stability !== next.stability) {\n    const transition =\n      STABILITY_TRANSITIONS[`${prev.stability}->${next.stability}`];\n    if (transition) {\n      push(diff, {\n        ...transition,\n        span,\n        attribute,\n        message: stabilityMessage(transition.type, attribute, prev, next),\n      });\n    }\n  }\n}\n\nfunction diffAttributeMaps(\n  diff: SnapshotDiff,\n  span: string,\n  prev: Record<string, SnapshotAttribute>,\n  next: Record<string, SnapshotAttribute>,\n): void {\n  for (const [key, prevAttr] of Object.entries(prev)) {\n    const nextAttr = next[key];\n    if (!nextAttr) {\n      // A removed attribute whose replacement is named is a documented\n      // migration (still breaking — but reported as such with the pointer).\n      push(diff, {\n        kind: 'breaking',\n        type: prevAttr.replacedBy ? 'replacement_documented' : 'attribute_removed',\n        span,\n        attribute: key,\n        message: prevAttr.replacedBy\n          ? `attribute \"${key}\" removed — replaced by \"${prevAttr.replacedBy}\"`\n          : `attribute \"${key}\" was removed`,\n      });\n      continue;\n    }\n    diffAttribute(diff, span, key, prevAttr, nextAttr);\n  }\n  for (const key of Object.keys(next)) {\n    if (!prev[key]) {\n      const added = next[key];\n      // Always `attribute_added` (the event is \"new attribute\"); severity rides\n      // on `kind` — a new *required* attribute breaks existing producers.\n      push(diff, {\n        kind: added.required ? 'breaking' : 'additive',\n        type: 'attribute_added',\n        span,\n        attribute: key,\n        message: added.required\n          ? `new required attribute \"${key}\" added`\n          : `new attribute \"${key}\" added`,\n      });\n    }\n  }\n}\n\n/**\n * Diff two snapshots, classifying every change. The `breaking` array is what a\n * CI gate keys off; `hasBreakingChanges()` is the convenience predicate.\n */\nexport function diffSnapshots(\n  previous: ContractSnapshot,\n  next: ContractSnapshot,\n): SnapshotDiff {\n  const diff: SnapshotDiff = {\n    service: next.service,\n    previousVersion: previous.version,\n    nextVersion: next.version,\n    breaking: [],\n    additive: [],\n    neutral: [],\n  };\n\n  diffAttributeMaps(diff, '*', previous.commonAttributes, next.commonAttributes);\n\n  for (const [name, prevSpan] of Object.entries(previous.spans)) {\n    const nextSpan = next.spans[name];\n    if (!nextSpan) {\n      push(diff, {\n        kind: 'breaking',\n        type: 'span_removed',\n        span: name,\n        message: `span \"${name}\" was removed`,\n      });\n      continue;\n    }\n    diffAttributeMaps(diff, name, prevSpan.attributes, nextSpan.attributes);\n  }\n  for (const name of Object.keys(next.spans)) {\n    if (!previous.spans[name]) {\n      push(diff, {\n        kind: 'additive',\n        type: 'span_added',\n        span: name,\n        message: `new span \"${name}\" added`,\n      });\n    }\n  }\n\n  return diff;\n}\n\n/** `true` when the diff contains at least one breaking change. */\nexport function hasBreakingChanges(diff: SnapshotDiff): boolean {\n  return diff.breaking.length > 0;\n}\n\n/** Markdown rendering of a diff — for CI logs and PR comments. */\nexport function formatDiff(diff: SnapshotDiff): string {\n  const lines: string[] = [ \n    `# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`,\n    ''];\n  const section = (title: string, changes: SnapshotChange[]) => {\n    if (changes.length === 0) return;\n    lines.push(`## ${title} (${changes.length})`, '');\n    for (const c of changes) {\n      const where = c.attribute ? `\\`${c.span}.${c.attribute}\\`` : `\\`${c.span}\\``;\n      lines.push(`- ${where}: ${c.message}`);\n    }\n    lines.push('');\n  };\n  section('💥 Breaking', diff.breaking);\n  section('➕ Additive', diff.additive);\n  section('• Neutral', diff.neutral);\n  if (\n    diff.breaking.length === 0 &&\n    diff.additive.length === 0 &&\n    diff.neutral.length === 0\n  ) {\n    lines.push('No changes to the telemetry contract.', '');\n  }\n  return lines.join('\\n');\n}\n"],"mappings":"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"}