autotel-schema 0.2.0 → 2.0.0

package/src/index.ts

@@ -1,88 +0,0 @@
-/**
- * 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

@@ -1,74 +0,0 @@
-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

@@ -1,152 +0,0 @@
-/**
- * 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

@@ -1,64 +0,0 @@
-/**
- * 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;
-}

package/src/snapshot.test.ts

@@ -1,88 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { defineContract, type TelemetryContract } from './contract.js';
-import {
-  diffSnapshots,
-  formatDiff,
-  hasBreakingChanges,
-} from './diff.js';
-import { highCardinalityKeys, isHighCardinalityKey } from './redaction.js';
-import {
-  contractToSnapshot,
-  parseSnapshot,
-  serializeSnapshot,
-} from './snapshot.js';
-
-const v1: TelemetryContract = defineContract({
-  service: 'checkout',
-  version: '1.0.0',
-  commonAttributes: { 'user.id': { type: 'string', highCardinality: true } },
-  spans: {
-    'checkout.charge': {
-      attributes: {
-        'payment.provider': { type: 'string', required: true },
-      },
-    },
-  },
-});
-
-describe('snapshot round-trip', () => {
-  it('is deterministic regardless of key insertion order', () => {
-    const reordered = defineContract({
-      version: '1.0.0',
-      service: 'checkout',
-      spans: {
-        'checkout.charge': {
-          attributes: { 'payment.provider': { type: 'string', required: true } },
-        },
-      },
-      commonAttributes: { 'user.id': { type: 'string', highCardinality: true } },
-    });
-    expect(serializeSnapshot(contractToSnapshot(v1))).toBe(
-      serializeSnapshot(contractToSnapshot(reordered)),
-    );
-  });
-
-  it('serializes and parses back', () => {
-    const snap = contractToSnapshot(v1);
-    expect(parseSnapshot(serializeSnapshot(snap))).toEqual(snap);
-  });
-
-  it('rejects an unknown snapshot spec', () => {
-    expect(() => parseSnapshot('{"spec":"nope/v9","service":"x","version":"1.0.0"}')).toThrowError(
-      /unexpected snapshot spec/,
-    );
-  });
-});
-
-describe('diffSnapshots', () => {
-  it('classifies a removed span as breaking', () => {
-    const v2 = defineContract({ ...v1, version: '2.0.0', spans: {} });
-    const diff = diffSnapshots(contractToSnapshot(v1), contractToSnapshot(v2));
-    expect(hasBreakingChanges(diff)).toBe(true);
-    expect(diff.breaking.some((c) => c.type === 'span_removed')).toBe(true);
-    expect(formatDiff(diff)).toMatch(/1\.0\.0 → 2\.0\.0/);
-  });
-
-  it('classifies a new span as additive, not breaking', () => {
-    const v2 = defineContract({
-      ...v1,
-      version: '1.1.0',
-      spans: {
-        ...v1.spans,
-        'checkout.refund': { attributes: {} },
-      },
-    });
-    const diff = diffSnapshots(contractToSnapshot(v1), contractToSnapshot(v2));
-    expect(hasBreakingChanges(diff)).toBe(false);
-    expect(diff.additive.some((c) => c.type === 'span_added')).toBe(true);
-  });
-});
-
-describe('redaction helpers', () => {
-  it('collects high-cardinality keys across common + span attributes', () => {
-    expect(highCardinalityKeys(v1)).toEqual(['user.id']);
-    expect(isHighCardinalityKey(v1, 'user.id')).toBe(true);
-    expect(isHighCardinalityKey(v1, 'payment.provider')).toBe(false);
-  });
-});

package/src/snapshot.ts

@@ -1,119 +0,0 @@
-/**
- * Snapshots — the serializable form of a contract that gets committed and
- * diffed across versions. Checking a snapshot into the repo turns "did this
- * refactor rename a span?" into a reviewable line in a PR instead of a silent
- * break the agent reader discovers at 3am.
- */
-
-import { SNAPSHOT_SPEC } from './attrs.js';
-import type {
-  AttributeSpec,
-  AttributeType,
-  Stability,
-  TelemetryContract,
-} from './contract.js';
-
-/** Flattened, fully-resolved attribute record in a snapshot. */
-export interface SnapshotAttribute {
-  type: AttributeType;
-  stability: Stability;
-  required: boolean;
-  highCardinality: boolean;
-  enum?: readonly (string | number)[];
-  replacedBy?: string;
-  description?: string;
-}
-
-export interface SnapshotSpan {
-  stability: Stability;
-  additionalAttributes: boolean;
-  description?: string;
-  attributes: Record<string, SnapshotAttribute>;
-}
-
-/** Canonical, comparable representation of a {@link TelemetryContract}. */
-export interface ContractSnapshot {
-  spec: typeof SNAPSHOT_SPEC;
-  service: string;
-  version: string;
-  commonAttributes: Record<string, SnapshotAttribute>;
-  spans: Record<string, SnapshotSpan>;
-}
-
-function normalizeAttribute(spec: AttributeSpec): SnapshotAttribute {
-  const out: SnapshotAttribute = {
-    type: spec.type,
-    stability: spec.stability ?? 'stable',
-    required: spec.required ?? false,
-    highCardinality: spec.highCardinality ?? false,
-  };
-  if (spec.enum) out.enum = [...spec.enum];
-  if (spec.replacedBy) out.replacedBy = spec.replacedBy;
-  if (spec.description) out.description = spec.description;
-  return out;
-}
-
-function sortRecord<T>(record: Record<string, T>): Record<string, T> {
-  const out: Record<string, T> = {};
-  for (const key of Object.keys(record).toSorted()) {
-    out[key] = record[key];
-  }
-  return out;
-}
-
-/**
- * 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.
- */
-export function contractToSnapshot(
-  contract: TelemetryContract,
-): ContractSnapshot {
-  const commonAttributes: Record<string, SnapshotAttribute> = {};
-  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {
-    commonAttributes[key] = normalizeAttribute(spec);
-  }
-
-  const spans: Record<string, SnapshotSpan> = {};
-  for (const [name, spanSpec] of Object.entries(contract.spans)) {
-    const attributes: Record<string, SnapshotAttribute> = {};
-    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {
-      attributes[key] = normalizeAttribute(spec);
-    }
-    const span: SnapshotSpan = {
-      stability: spanSpec.stability ?? 'stable',
-      additionalAttributes:
-        spanSpec.additionalAttributes ?? contract.additionalAttributes ?? false,
-      attributes: sortRecord(attributes),
-    };
-    if (spanSpec.description) span.description = spanSpec.description;
-    spans[name] = span;
-  }
-
-  return {
-    spec: SNAPSHOT_SPEC,
-    service: contract.service,
-    version: contract.version,
-    commonAttributes: sortRecord(commonAttributes),
-    spans: sortRecord(spans),
-  };
-}
-
-/** Pretty, deterministic JSON for writing a snapshot to disk. */
-export function serializeSnapshot(snapshot: ContractSnapshot): string {
-  return JSON.stringify(snapshot, null, 2) + '\n';
-}
-
-/** Parse and structurally validate a snapshot read from disk. */
-export function parseSnapshot(json: string): ContractSnapshot {
-  const data = JSON.parse(json) as ContractSnapshot;
-  if (data.spec !== SNAPSHOT_SPEC) {
-    throw new Error(
-      `autotel-schema: unexpected snapshot spec "${data.spec}" (expected "${SNAPSHOT_SPEC}")`,
-    );
-  }
-  if (typeof data.service !== 'string' || typeof data.version !== 'string') {
-    throw new Error('autotel-schema: snapshot is missing service/version');
-  }
-  return data;
-}

package/src/validate.test.ts

@@ -1,100 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { defineContract, type TelemetryContract } from './contract.js';
-import {
-  formatViolation,
-  hasErrors,
-  validateSpan,
-} from './validate.js';
-
-const contract: TelemetryContract = defineContract({
-  service: 'checkout',
-  version: '1.0.0',
-  commonAttributes: { 'user.id': { type: 'string' } },
-  spans: {
-    'checkout.charge': {
-      attributes: {
-        'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
-        'payment.amount_cents': { type: 'number', required: true },
-      },
-    },
-  },
-});
-
-describe('validateSpan', () => {
-  it('passes a fully-conformant span', () => {
-    const v = validateSpan(
-      {
-        name: 'checkout.charge',
-        attributes: { 'payment.provider': 'stripe', 'payment.amount_cents': 999 },
-      },
-      contract,
-    );
-    expect(v).toEqual([]);
-  });
-
-  it('flags a missing required attribute as an error', () => {
-    const v = validateSpan(
-      { name: 'checkout.charge', attributes: { 'payment.provider': 'stripe' } },
-      contract,
-    );
-    expect(v).toHaveLength(1);
-    expect(v[0]).toMatchObject({ code: 'missing_required', attribute: 'payment.amount_cents' });
-    expect(hasErrors(v)).toBe(true);
-  });
-
-  it('flags a wrong type', () => {
-    const v = validateSpan(
-      {
-        name: 'checkout.charge',
-        attributes: { 'payment.provider': 'stripe', 'payment.amount_cents': '999' },
-      },
-      contract,
-    );
-    expect(v.some((x) => x.code === 'type_mismatch')).toBe(true);
-  });
-
-  it('flags an enum violation', () => {
-    const v = validateSpan(
-      {
-        name: 'checkout.charge',
-        attributes: { 'payment.provider': 'bitcoin', 'payment.amount_cents': 1 },
-      },
-      contract,
-    );
-    expect(v.some((x) => x.code === 'enum_violation')).toBe(true);
-  });
-
-  it('warns on an undeclared attribute and suggests a near key', () => {
-    const v = validateSpan(
-      {
-        name: 'checkout.charge',
-        attributes: {
-          'payment.provider': 'stripe',
-          'payment.amount_cents': 1,
-          'payment.providr': 'x', // typo of a declared key
-        },
-      },
-      contract,
-    );
-    const unknown = v.find((x) => x.code === 'unknown_attribute');
-    expect(unknown?.severity).toBe('warning');
-    expect(unknown?.suggestion).toBe('payment.provider');
-  });
-
-  it('ignores unknown spans unless strictSpanNames is set', () => {
-    expect(validateSpan({ name: 'mystery', attributes: {} }, contract)).toEqual([]);
-    const strict = validateSpan({ name: 'mystery', attributes: {} }, contract, {
-      strictSpanNames: true,
-    });
-    expect(strict[0]?.code).toBe('unknown_span');
-  });
-
-  it('formats a violation legibly', () => {
-    const v = validateSpan(
-      { name: 'checkout.charge', attributes: { 'payment.provider': 'stripe' } },
-      contract,
-    );
-    expect(formatViolation(v[0])).toMatch(/\[error\] missing_required @ checkout.charge.payment.amount_cents/);
-  });
-});