autotel-schema 0.1.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "autotel-schema",
+  "version": "0.1.0",
+  "description": "Your telemetry surface as a typed, versioned contract — declare the spans and attributes your service emits, validate live spans against them, and diff the surface across commits to catch breaking trace changes before they ship.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./processor": {
+      "types": "./dist/processor.d.ts",
+      "import": "./dist/processor.js",
+      "require": "./dist/processor.cjs"
+    },
+    "./diff": {
+      "types": "./dist/diff.d.ts",
+      "import": "./dist/diff.js",
+      "require": "./dist/diff.cjs"
+    }
+  },
+  "bin": {
+    "autotel-schema": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "autotel",
+    "opentelemetry",
+    "observability",
+    "telemetry-contract",
+    "schema",
+    "span-validation",
+    "semantic-conventions",
+    "breaking-change-detection",
+    "agent-observability"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "peerDependencies": {
+    "autotel": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "autotel": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-schema"
+  },
+  "bugs": {
+    "url": "https://github.com/jagreehal/autotel/issues"
+  },
+  "homepage": "https://github.com/jagreehal/autotel/tree/main/packages/autotel-schema#readme"
+}

package/src/attrs.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+export const SCHEMA_ATTRS = {
+  /** The service this contract describes (mirrors `service.name`). */
+  SERVICE: 'telemetry.schema.service',
+  /** Semver of the telemetry contract that produced this span. */
+  VERSION: 'telemetry.schema.version',
+} as const;
+
+export type SchemaAttributeKey = (typeof SCHEMA_ATTRS)[keyof typeof SCHEMA_ATTRS];
+
+/** Snapshot file spec marker — bump only on a breaking snapshot format change. */
+export const SNAPSHOT_SPEC = 'autotel-schema-snapshot/v1' as const;

package/src/cli.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * 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`.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseSnapshot } from './snapshot.js';
+import {
+  diffSnapshots,
+  formatDiff,
+  hasBreakingChanges,
+  type SnapshotDiff,
+} from './diff.js';
+
+interface Parsed {
+  command: string | undefined;
+  baseline: string | undefined;
+  current: string | undefined;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): Parsed {
+  const positional: string[] = [];
+  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: string, current: string): SnapshotDiff {
+  const prev = parseSnapshot(readFileSync(baseline, 'utf8'));
+  const next = parseSnapshot(readFileSync(current, 'utf8'));
+  return diffSnapshots(prev, next);
+}
+
+function emit(diff: SnapshotDiff, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(diff, null, 2));
+  } else {
+    console.log(formatDiff(diff));
+  }
+}
+
+export function run(argv: string[]): number {
+  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: SnapshotDiff;
+  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;
+}
+
+// Only auto-run when invoked directly as the binary, not when imported in tests.
+// Match the basename so a repo path containing "autotel-schema" can't trigger it.
+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)));
+}

package/src/contract.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  allowsAdditionalAttributes,
+  defineContract,
+  resolveAttributeSpec,
+  type TelemetryContract,
+} from './contract.js';
+
+const base: TelemetryContract = {
+  service: 'checkout',
+  version: '1.2.0',
+  commonAttributes: {
+    'user.id': { type: 'string', highCardinality: true },
+  },
+  spans: {
+    'checkout.charge': {
+      attributes: {
+        'payment.provider': { type: 'string', required: true, enum: ['stripe', 'paypal'] },
+        'payment.amount_cents': { type: 'number', required: true },
+      },
+    },
+  },
+};
+
+describe('defineContract', () => {
+  it('accepts and freezes a valid contract', () => {
+    const c = defineContract(base);
+    expect(Object.isFrozen(c)).toBe(true);
+    expect(c.service).toBe('checkout');
+  });
+
+  it('rejects an empty service', () => {
+    expect(() => defineContract({ ...base, service: '' })).toThrowError(/service/);
+  });
+
+  it('rejects a non-semver version', () => {
+    expect(() => defineContract({ ...base, version: 'v1' })).toThrowError(/semver/);
+  });
+
+  it('rejects an unknown attribute type', () => {
+    expect(() =>
+      defineContract({
+        ...base,
+        spans: { 'x.y': { attributes: { k: { type: 'uuid' as never } } } },
+      }),
+    ).toThrow();
+  });
+});
+
+describe('resolveAttributeSpec', () => {
+  it('prefers span-specific over common attributes', () => {
+    expect(resolveAttributeSpec(base, 'checkout.charge', 'payment.provider')?.required).toBe(true);
+    expect(resolveAttributeSpec(base, 'checkout.charge', 'user.id')?.highCardinality).toBe(true);
+    expect(resolveAttributeSpec(base, 'checkout.charge', 'nope')).toBeUndefined();
+  });
+});
+
+describe('allowsAdditionalAttributes', () => {
+  it('defaults to false (declared-only)', () => {
+    expect(allowsAdditionalAttributes(base, 'checkout.charge')).toBe(false);
+  });
+  it('honors span- then contract-level overrides', () => {
+    const loose = { ...base, additionalAttributes: true };
+    expect(allowsAdditionalAttributes(loose, 'checkout.charge')).toBe(true);
+  });
+});

package/src/contract.ts

@@ -0,0 +1,231 @@
+/**
+ * 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). */
+export type AttributeType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'string[]'
+  | 'number[]'
+  | 'boolean[]';
+
+export const ATTRIBUTE_TYPES: readonly AttributeType[] = [
+  'string',
+  'number',
+  'boolean',
+  'string[]',
+  'number[]',
+  'boolean[]',
+];
+
+/**
+ * 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.
+ */
+export type Stability = 'stable' | 'experimental' | 'deprecated';
+
+export const STABILITIES: readonly Stability[] = [
+  'stable',
+  'experimental',
+  'deprecated',
+];
+
+/** Declaration for a single attribute key on a span. */
+export 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. */
+export 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. */
+export 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;
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(`autotel-schema: ${message}`);
+  }
+}
+
+function validateAttribute(
+  scope: string,
+  key: string,
+  spec: AttributeSpec,
+): void {
+  assert(
+    ATTRIBUTE_TYPES.includes(spec.type),
+    `${scope} attribute "${key}" has invalid type "${spec.type}"`,
+  );
+  if (spec.stability) {
+    assert(
+      STABILITIES.includes(spec.stability),
+      `${scope} attribute "${key}" has invalid stability "${spec.stability}"`,
+    );
+  }
+  if (spec.stability === 'deprecated') {
+    assert(
+      spec.replacedBy !== undefined || spec.deprecatedReason !== undefined,
+      `${scope} attribute "${key}" is deprecated but has no replacedBy or deprecatedReason`,
+    );
+  }
+  if (spec.enum) {
+    assert(
+      spec.enum.length > 0,
+      `${scope} attribute "${key}" declares an empty enum`,
+    );
+  }
+}
+
+/**
+ * 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 },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineContract(contract: TelemetryContract): TelemetryContract {
+  assert(
+    typeof contract.service === 'string' && contract.service.length > 0,
+    'contract.service must be a non-empty string',
+  );
+  assert(
+    SEMVER_RE.test(contract.version),
+    `contract.version "${contract.version}" is not valid semver (e.g. "1.2.0")`,
+  );
+  assert(
+    contract.spans && typeof contract.spans === 'object',
+    'contract.spans must be an object',
+  );
+
+  for (const [spanName, spanSpec] of Object.entries(contract.spans)) {
+    if (spanSpec.stability) {
+      assert(
+        STABILITIES.includes(spanSpec.stability),
+        `span "${spanName}" has invalid stability "${spanSpec.stability}"`,
+      );
+    }
+    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {
+      validateAttribute(`span "${spanName}"`, key, spec);
+    }
+  }
+  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {
+    validateAttribute('common', key, spec);
+  }
+
+  return Object.freeze(contract);
+}
+
+/**
+ * Resolve the effective attribute spec for `key` on `spanName`: span-specific
+ * attributes win over common attributes. Returns `undefined` when the key is
+ * declared nowhere.
+ */
+export function resolveAttributeSpec(
+  contract: TelemetryContract,
+  spanName: string,
+  key: string,
+): AttributeSpec | undefined {
+  return (
+    contract.spans[spanName]?.attributes?.[key] ??
+    contract.commonAttributes?.[key]
+  );
+}
+
+/** Whether attributes outside the declared set are tolerated for a span. */
+export function allowsAdditionalAttributes(
+  contract: TelemetryContract,
+  spanName: string,
+): boolean {
+  return (
+    contract.spans[spanName]?.additionalAttributes ??
+    contract.additionalAttributes ??
+    false
+  );
+}