autotel-schema 0.1.0

package/src/diff.ts

@@ -0,0 +1,282 @@
+/**
+ * Snapshot diffing — the CI gate that catches breaking changes to your trace
+ * surface before they ship.
+ *
+ * "If you wouldn't ship a rename to your public API without a changelog, don't
+ * do it to your traces." This module is what makes that enforceable: classify
+ * every change between two snapshots as breaking, additive, or neutral, and let
+ * CI fail on the breaking ones.
+ */
+
+import type { ContractSnapshot, SnapshotAttribute } from './snapshot.js';
+
+export type ChangeKind = 'breaking' | 'additive' | 'neutral';
+
+export 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';
+
+export interface SnapshotChange {
+  kind: ChangeKind;
+  type: ChangeType;
+  /** Span the change applies to (`*` = common attributes / contract-wide). */
+  span: string;
+  attribute?: string;
+  message: string;
+}
+
+export interface SnapshotDiff {
+  service: string;
+  previousVersion: string;
+  nextVersion: string;
+  breaking: SnapshotChange[];
+  additive: SnapshotChange[];
+  neutral: SnapshotChange[];
+}
+
+/**
+ * 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: Record<
+  string,
+  { kind: ChangeKind; type: ChangeType }
+> = {
+  '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: ChangeType,
+  attribute: string,
+  prev: SnapshotAttribute,
+  next: SnapshotAttribute,
+): string {
+  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: SnapshotDiff,
+  change: SnapshotChange,
+): void {
+  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: SnapshotDiff,
+  span: string,
+  attribute: string,
+  prev: SnapshotAttribute,
+  next: SnapshotAttribute,
+): void {
+  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`,
+    });
+  }
+
+  // Enum: removing a permitted value can break a producer that still emits it.
+  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: SnapshotDiff,
+  span: string,
+  prev: Record<string, SnapshotAttribute>,
+  next: Record<string, SnapshotAttribute>,
+): void {
+  for (const [key, prevAttr] of Object.entries(prev)) {
+    const nextAttr = next[key];
+    if (!nextAttr) {
+      // A removed attribute whose replacement is named is a documented
+      // migration (still breaking — but reported as such with the pointer).
+      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];
+      // Always `attribute_added` (the event is "new attribute"); severity rides
+      // on `kind` — a new *required* attribute breaks existing producers.
+      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.
+ */
+export function diffSnapshots(
+  previous: ContractSnapshot,
+  next: ContractSnapshot,
+): SnapshotDiff {
+  const diff: SnapshotDiff = {
+    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. */
+export function hasBreakingChanges(diff: SnapshotDiff): boolean {
+  return diff.breaking.length > 0;
+}
+
+/** Markdown rendering of a diff — for CI logs and PR comments. */
+export function formatDiff(diff: SnapshotDiff): string {
+  const lines: string[] = [ 
+    `# Telemetry contract diff: ${diff.service} ${diff.previousVersion} → ${diff.nextVersion}`,
+    ''];
+  const section = (title: string, changes: SnapshotChange[]) => {
+    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');
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * autotel-schema — your telemetry surface as a typed, versioned contract.
+ *
+ * When the primary reader of your telemetry is an agent, your span names and
+ * attribute keys are a **public API**. `defineContract()` makes that surface
+ * explicit and versionable; `validateSpan` / `SchemaValidationSpanProcessor`
+ * check live spans against it; `diffSnapshots` / `hasBreakingChanges` catch
+ * breaking trace-surface changes before they ship; `highCardinalityKeys` feeds
+ * a redaction allow-list so the fields most useful to an agent reader survive.
+ *
+ * The contract model is dependency-free and side-effect-free — safe to import
+ * anywhere (browser, edge, CLI) without pulling in the OpenTelemetry SDK.
+ */
+
+export {
+  SCHEMA_ATTRS,
+  SNAPSHOT_SPEC,
+} from './attrs.js';
+export type { SchemaAttributeKey } from './attrs.js';
+
+export {
+  ATTRIBUTE_TYPES,
+  STABILITIES,
+  defineContract,
+  resolveAttributeSpec,
+  allowsAdditionalAttributes,
+} from './contract.js';
+export type {
+  AttributeType,
+  Stability,
+  AttributeSpec,
+  SpanSpec,
+  TelemetryContract,
+} from './contract.js';
+
+export {
+  contractToSnapshot,
+  serializeSnapshot,
+  parseSnapshot,
+} from './snapshot.js';
+export type {
+  SnapshotAttribute,
+  SnapshotSpan,
+  ContractSnapshot,
+} from './snapshot.js';
+
+export {
+  validateSpan,
+  hasErrors,
+  formatViolation,
+} from './validate.js';
+export type {
+  ViolationSeverity,
+  ViolationCode,
+  SchemaViolation,
+  SpanShape,
+  ValidateOptions,
+} from './validate.js';
+
+export {
+  SchemaValidationSpanProcessor,
+  createSchemaValidationProcessor,
+} from './processor.js';
+export type {
+  ReadableSpanLike,
+  SpanLike,
+  OtelContext,
+  SpanProcessorLike,
+  SchemaProcessorMode,
+  SchemaValidationProcessorOptions,
+} from './processor.js';
+
+export {
+  diffSnapshots,
+  hasBreakingChanges,
+  formatDiff,
+} from './diff.js';
+export type {
+  ChangeKind,
+  ChangeType,
+  SnapshotChange,
+  SnapshotDiff,
+} from './diff.js';
+
+export {
+  highCardinalityKeys,
+  isHighCardinalityKey,
+} from './redaction.js';

package/src/processor.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { defineContract, type TelemetryContract } from './contract.js';
+import {
+  createSchemaValidationProcessor,
+  SchemaValidationSpanProcessor,
+} from './processor.js';
+import type { SchemaViolation } from './validate.js';
+
+const contract: TelemetryContract = defineContract({
+  service: 'checkout',
+  version: '1.0.0',
+  spans: {
+    'checkout.charge': {
+      attributes: { 'payment.amount_cents': { type: 'number', required: true } },
+    },
+  },
+});
+
+function endSpan(p: SchemaValidationSpanProcessor, name: string, attributes: Record<string, unknown>) {
+  p.onEnd({ name, attributes });
+}
+
+describe('SchemaValidationSpanProcessor', () => {
+  it('collects violations via onViolation in silent mode', () => {
+    const seen: SchemaViolation[] = [];
+    const p = createSchemaValidationProcessor({
+      contract,
+      mode: 'silent',
+      enabledInProduction: true,
+      onViolation: (v) => seen.push(v),
+    });
+    endSpan(p, 'checkout.charge', {}); // missing required
+    expect(seen).toHaveLength(1);
+    expect(seen[0].code).toBe('missing_required');
+    expect(p.totalViolations).toBe(1);
+  });
+
+  it('throws on the first error in throw mode', () => {
+    const p = createSchemaValidationProcessor({ contract, mode: 'throw', enabledInProduction: true });
+    expect(() => endSpan(p, 'checkout.charge', {})).toThrowError(/contract violation/);
+  });
+
+  it('does not throw for a conformant span', () => {
+    const p = createSchemaValidationProcessor({ contract, mode: 'throw', enabledInProduction: true });
+    expect(() => endSpan(p, 'checkout.charge', { 'payment.amount_cents': 1 })).not.toThrow();
+  });
+
+  it('warns through the injected sink, deduplicated within the interval', () => {
+    const onWarn = vi.fn();
+    const p = createSchemaValidationProcessor({
+      contract,
+      mode: 'warn',
+      enabledInProduction: true,
+      onWarn,
+      warnIntervalMs: 60_000,
+    });
+    endSpan(p, 'checkout.charge', {});
+    endSpan(p, 'checkout.charge', {}); // identical violation → throttled
+    expect(onWarn).toHaveBeenCalledTimes(1);
+  });
+
+  it('is disabled in production unless opted in', () => {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+      const p = createSchemaValidationProcessor({ contract, mode: 'throw' });
+      expect(() => endSpan(p, 'checkout.charge', {})).not.toThrow();
+      expect(p.totalViolations).toBe(0);
+    } finally {
+      process.env.NODE_ENV = prev;
+    }
+  });
+});

package/src/processor.ts

@@ -0,0 +1,152 @@
+/**
+ * Runtime contract enforcement as an OpenTelemetry SpanProcessor.
+ *
+ * Wire it into `init({ spanProcessors: [...] })` and every span your service
+ * emits is validated against the contract as it ends. In development a typo'd
+ * or undeclared attribute surfaces immediately instead of silently drifting
+ * the public telemetry API out from under the agents reading it.
+ *
+ * Fail-open by construction: a bug in validation must never break the app or
+ * lose a span. Off in production by default (validation belongs in CI and dev),
+ * but `enabledInProduction` is there if you want a sampled canary in prod.
+ */
+
+import { validateSpan, type SchemaViolation, type ValidateOptions } from './validate.js';
+import type { TelemetryContract } from './contract.js';
+
+/** Minimal ReadableSpan shape — matches OTel without a hard SDK dependency. */
+export interface ReadableSpanLike {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+
+export interface SpanLike {
+  spanContext(): { traceId: string; spanId: string };
+}
+
+/** Opaque parent context — matches OTel SpanProcessor without importing it. */
+export type OtelContext = unknown;
+
+export interface SpanProcessorLike {
+  onStart(span: SpanLike, parentContext: OtelContext): void;
+  onEnd(span: ReadableSpanLike): void;
+  shutdown(): Promise<void>;
+  forceFlush(): Promise<void>;
+}
+
+/** How the processor reacts to a contract violation. */
+export type SchemaProcessorMode = 'warn' | 'throw' | 'silent';
+
+export interface SchemaValidationProcessorOptions extends ValidateOptions {
+  contract: TelemetryContract;
+  /**
+   * `warn` (default): log each distinct violation once per interval.
+   * `throw`: throw on the first error-severity violation — for tests/CI only.
+   * `silent`: collect via `onViolation` without logging.
+   */
+  mode?: SchemaProcessorMode;
+  /** Called for every violation, before mode handling. */
+  onViolation?: (violation: SchemaViolation, span: ReadableSpanLike) => void;
+  /** Override the warn sink (defaults to `console.warn`). */
+  onWarn?: (message: string) => void;
+  /** Run even when `NODE_ENV === 'production'`. Default `false`. */
+  enabledInProduction?: boolean;
+  /** Throttle window for repeated identical warnings (ms). Default 60s. */
+  warnIntervalMs?: number;
+}
+
+const DEFAULT_WARN_INTERVAL_MS = 60_000;
+
+function isProduction(): boolean {
+  return process.env.NODE_ENV === 'production';
+}
+
+/**
+ * Validates each ending span against a {@link TelemetryContract}. Bounded,
+ * deduplicated warnings; fail-open on any internal error.
+ */
+export class SchemaValidationSpanProcessor implements SpanProcessorLike {
+  private readonly opts: SchemaValidationProcessorOptions;
+  private readonly enabled: boolean;
+  private readonly warnIntervalMs: number;
+  private readonly lastWarnAt = new Map<string, number>();
+  private violationCount = 0;
+
+  constructor(opts: SchemaValidationProcessorOptions) {
+    this.opts = opts;
+    this.enabled = opts.enabledInProduction === true || !isProduction();
+    this.warnIntervalMs = opts.warnIntervalMs ?? DEFAULT_WARN_INTERVAL_MS;
+  }
+
+  /** Number of violations seen since startup (across all spans). */
+  get totalViolations(): number {
+    return this.violationCount;
+  }
+
+  onStart(_span: SpanLike, _parentContext: OtelContext): void {
+    // no-op — validation happens once the span is complete
+  }
+
+  onEnd(span: ReadableSpanLike): void {
+    if (!this.enabled) return;
+    let violations: SchemaViolation[];
+    try {
+      // Validation itself is fail-open: a bug here must never break export.
+      violations = validateSpan(
+        { name: span.name, attributes: span.attributes },
+        this.opts.contract,
+        { strictSpanNames: this.opts.strictSpanNames },
+      );
+    } catch {
+      return;
+    }
+    // Mode handling runs outside the fail-open guard so `throw` mode propagates.
+    for (const violation of violations) {
+      this.violationCount++;
+      this.opts.onViolation?.(violation, span);
+      this.handle(violation);
+    }
+  }
+
+  private handle(violation: SchemaViolation): void {
+    const mode = this.opts.mode ?? 'warn';
+    if (mode === 'silent') return;
+    if (mode === 'throw' && violation.severity === 'error') {
+      throw new Error(
+        `autotel-schema: contract violation (${violation.code}) on span "${violation.spanName}": ${violation.message}`,
+      );
+    }
+    this.maybeWarn(violation);
+  }
+
+  private maybeWarn(violation: SchemaViolation): void {
+    const key = `${violation.code}:${violation.spanName}:${violation.attribute ?? ''}`;
+    const now = Date.now();
+    const last = this.lastWarnAt.get(key) ?? 0;
+    if (now - last < this.warnIntervalMs) return;
+    this.lastWarnAt.set(key, now);
+    const suffix = violation.suggestion
+      ? ` (did you mean "${violation.suggestion}"?)`
+      : '';
+    const message = `autotel-schema [${violation.severity}] ${violation.code} on "${violation.spanName}"${violation.attribute ? `.${violation.attribute}` : ''}: ${violation.message}${suffix}`;
+    if (this.opts.onWarn) {
+      this.opts.onWarn(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  async forceFlush(): Promise<void> {
+    // nothing buffered — validation is synchronous in onEnd
+  }
+
+  async shutdown(): Promise<void> {
+    this.lastWarnAt.clear();
+  }
+}
+
+export function createSchemaValidationProcessor(
+  opts: SchemaValidationProcessorOptions,
+): SchemaValidationSpanProcessor {
+  return new SchemaValidationSpanProcessor(opts);
+}

package/src/redaction.ts

@@ -0,0 +1,64 @@
+/**
+ * Cardinality posture helpers.
+ *
+ * The old cardinality rule — "keep unique-value counts down" — was a constraint
+ * invented because dashboards have pixels and a graph with 10k series is
+ * unreadable to a human. An agent does not look at the graph; it reads the
+ * spans. A high-cardinality field (the user id, the sender domain, the request
+ * id) is then the single most useful attribute on a trace when the agent is
+ * chasing one specific failure.
+ *
+ * So the contract lets you mark attributes `highCardinality: true` as a
+ * deliberate signal, and this module turns that into a *protect list*: the keys
+ * a redactor or span-name normalizer must NOT strip, even when an aggressive
+ * default would otherwise drop them.
+ */
+
+import type { TelemetryContract } from './contract.js';
+
+/**
+ * Every attribute key in the contract flagged `highCardinality: true`, across
+ * both common and per-span attributes. Feed this into a redaction/normalization
+ * allow-list so the fields most useful to an agent reader survive.
+ *
+ * @example
+ * ```ts
+ * import { init } from 'autotel';
+ * import { highCardinalityKeys } from 'autotel-schema';
+ * import { contract } from './telemetry.contract';
+ *
+ * init({
+ *   service: 'checkout',
+ *   // keep user.id / request.id intact even under the strict redactor
+ *   attributeRedactor: { allowKeys: highCardinalityKeys(contract), preset: 'strict' },
+ * });
+ * ```
+ */
+export function highCardinalityKeys(contract: TelemetryContract): string[] {
+  const keys = new Set<string>();
+  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {
+    if (spec.highCardinality) keys.add(key);
+  }
+  for (const spanSpec of Object.values(contract.spans)) {
+    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {
+      if (spec.highCardinality) keys.add(key);
+    }
+  }
+  return [...keys].toSorted();
+}
+
+/**
+ * Predicate form of {@link highCardinalityKeys} — `true` when `key` is declared
+ * high-cardinality anywhere in the contract. Useful inside a custom
+ * `spanNameNormalizer` or redactor callback.
+ */
+export function isHighCardinalityKey(
+  contract: TelemetryContract,
+  key: string,
+): boolean {
+  if (contract.commonAttributes?.[key]?.highCardinality) return true;
+  for (const spanSpec of Object.values(contract.spans)) {
+    if (spanSpec.attributes?.[key]?.highCardinality) return true;
+  }
+  return false;
+}