autotel-schema 0.1.0

package/dist/index.cjs

@@ -0,0 +1,63 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_snapshot = require('./snapshot-CyWGJaJT.cjs');
+const require_processor = require('./processor-D93TAXvZ.cjs');
+const require_diff = require('./diff.cjs');
+
+//#region src/redaction.ts
+/**
+* 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' },
+* });
+* ```
+*/
+function highCardinalityKeys(contract) {
+	const keys = /* @__PURE__ */ new Set();
+	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.
+*/
+function isHighCardinalityKey(contract, key) {
+	if (contract.commonAttributes?.[key]?.highCardinality) return true;
+	for (const spanSpec of Object.values(contract.spans)) if (spanSpec.attributes?.[key]?.highCardinality) return true;
+	return false;
+}
+
+//#endregion
+exports.ATTRIBUTE_TYPES = require_processor.ATTRIBUTE_TYPES;
+exports.SCHEMA_ATTRS = require_snapshot.SCHEMA_ATTRS;
+exports.SNAPSHOT_SPEC = require_snapshot.SNAPSHOT_SPEC;
+exports.STABILITIES = require_processor.STABILITIES;
+exports.SchemaValidationSpanProcessor = require_processor.SchemaValidationSpanProcessor;
+exports.allowsAdditionalAttributes = require_processor.allowsAdditionalAttributes;
+exports.contractToSnapshot = require_snapshot.contractToSnapshot;
+exports.createSchemaValidationProcessor = require_processor.createSchemaValidationProcessor;
+exports.defineContract = require_processor.defineContract;
+exports.diffSnapshots = require_diff.diffSnapshots;
+exports.formatDiff = require_diff.formatDiff;
+exports.formatViolation = require_processor.formatViolation;
+exports.hasBreakingChanges = require_diff.hasBreakingChanges;
+exports.hasErrors = require_processor.hasErrors;
+exports.highCardinalityKeys = highCardinalityKeys;
+exports.isHighCardinalityKey = isHighCardinalityKey;
+exports.parseSnapshot = require_snapshot.parseSnapshot;
+exports.resolveAttributeSpec = require_processor.resolveAttributeSpec;
+exports.serializeSnapshot = require_snapshot.serializeSnapshot;
+exports.validateSpan = require_processor.validateSpan;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/redaction.ts"],"sourcesContent":["/**\n * Cardinality posture helpers.\n *\n * The old cardinality rule — \"keep unique-value counts down\" — was a constraint\n * invented because dashboards have pixels and a graph with 10k series is\n * unreadable to a human. An agent does not look at the graph; it reads the\n * spans. A high-cardinality field (the user id, the sender domain, the request\n * id) is then the single most useful attribute on a trace when the agent is\n * chasing one specific failure.\n *\n * So the contract lets you mark attributes `highCardinality: true` as a\n * deliberate signal, and this module turns that into a *protect list*: the keys\n * a redactor or span-name normalizer must NOT strip, even when an aggressive\n * default would otherwise drop them.\n */\n\nimport type { TelemetryContract } from './contract.js';\n\n/**\n * Every attribute key in the contract flagged `highCardinality: true`, across\n * both common and per-span attributes. Feed this into a redaction/normalization\n * allow-list so the fields most useful to an agent reader survive.\n *\n * @example\n * ```ts\n * import { init } from 'autotel';\n * import { highCardinalityKeys } from 'autotel-schema';\n * import { contract } from './telemetry.contract';\n *\n * init({\n *   service: 'checkout',\n *   // keep user.id / request.id intact even under the strict redactor\n *   attributeRedactor: { allowKeys: highCardinalityKeys(contract), preset: 'strict' },\n * });\n * ```\n */\nexport function highCardinalityKeys(contract: TelemetryContract): string[] {\n  const keys = new Set<string>();\n  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {\n    if (spec.highCardinality) keys.add(key);\n  }\n  for (const spanSpec of Object.values(contract.spans)) {\n    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {\n      if (spec.highCardinality) keys.add(key);\n    }\n  }\n  return [...keys].toSorted();\n}\n\n/**\n * Predicate form of {@link highCardinalityKeys} — `true` when `key` is declared\n * high-cardinality anywhere in the contract. Useful inside a custom\n * `spanNameNormalizer` or redactor callback.\n */\nexport function isHighCardinalityKey(\n  contract: TelemetryContract,\n  key: string,\n): boolean {\n  if (contract.commonAttributes?.[key]?.highCardinality) return true;\n  for (const spanSpec of Object.values(contract.spans)) {\n    if (spanSpec.attributes?.[key]?.highCardinality) return true;\n  }\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,oBAAoB,UAAuC;CACzE,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,oBAAoB,CAAC,CAAC,GACtE,IAAI,KAAK,iBAAiB,KAAK,IAAI,GAAG;CAExC,KAAK,MAAM,YAAY,OAAO,OAAO,SAAS,KAAK,GACjD,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,cAAc,CAAC,CAAC,GAChE,IAAI,KAAK,iBAAiB,KAAK,IAAI,GAAG;CAG1C,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,SAAS;AAC5B;;;;;;AAOA,SAAgB,qBACd,UACA,KACS;CACT,IAAI,SAAS,mBAAmB,IAAI,EAAE,iBAAiB,OAAO;CAC9D,KAAK,MAAM,YAAY,OAAO,OAAO,SAAS,KAAK,GACjD,IAAI,SAAS,aAAa,IAAI,EAAE,iBAAiB,OAAO;CAE1D,OAAO;AACT"}

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { a as diffSnapshots, c as ContractSnapshot, d as contractToSnapshot, f as parseSnapshot, g as SchemaAttributeKey, h as SNAPSHOT_SPEC, i as SnapshotDiff, l as SnapshotAttribute, m as SCHEMA_ATTRS, n as ChangeType, o as formatDiff, p as serializeSnapshot, r as SnapshotChange, s as hasBreakingChanges, t as ChangeKind, u as SnapshotSpan } from "./diff-BQPh72vY.cjs";
+import { a as SpanSpec, c as allowsAdditionalAttributes, i as STABILITIES, l as defineContract, n as AttributeSpec, o as Stability, r as AttributeType, s as TelemetryContract, t as ATTRIBUTE_TYPES, u as resolveAttributeSpec } from "./contract-DGjxR9nb.cjs";
+import { a as SchemaValidationSpanProcessor, c as createSchemaValidationProcessor, d as ValidateOptions, f as ViolationCode, g as validateSpan, h as hasErrors, i as SchemaValidationProcessorOptions, l as SchemaViolation, m as formatViolation, n as ReadableSpanLike, o as SpanLike, p as ViolationSeverity, r as SchemaProcessorMode, s as SpanProcessorLike, t as OtelContext, u as SpanShape } from "./processor-CkBkzK6y.cjs";
+
+//#region src/redaction.d.ts
+/**
+ * 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' },
+ * });
+ * ```
+ */
+declare function highCardinalityKeys(contract: TelemetryContract): string[];
+/**
+ * Predicate form of {@link highCardinalityKeys} — `true` when `key` is declared
+ * high-cardinality anywhere in the contract. Useful inside a custom
+ * `spanNameNormalizer` or redactor callback.
+ */
+declare function isHighCardinalityKey(contract: TelemetryContract, key: string): boolean;
+//#endregion
+export { ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type ChangeKind, type ChangeType, type ContractSnapshot, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanShape, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, formatDiff, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, parseSnapshot, resolveAttributeSpec, serializeSnapshot, validateSpan };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/redaction.ts"],"mappings":";;;;;;;AAwDa;;;;;;;;;;;;;;;;iBApBG,mBAAA,CAAoB,QAA2B,EAAjB,iBAAiB;;;;;;iBAkB/C,oBAAA,CACd,QAAA,EAAU,iBAAiB,EAC3B,GAAA"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { a as diffSnapshots, c as ContractSnapshot, d as contractToSnapshot, f as parseSnapshot, g as SchemaAttributeKey, h as SNAPSHOT_SPEC, i as SnapshotDiff, l as SnapshotAttribute, m as SCHEMA_ATTRS, n as ChangeType, o as formatDiff, p as serializeSnapshot, r as SnapshotChange, s as hasBreakingChanges, t as ChangeKind, u as SnapshotSpan } from "./diff-D7qkNn0-.js";
+import { a as SpanSpec, c as allowsAdditionalAttributes, i as STABILITIES, l as defineContract, n as AttributeSpec, o as Stability, r as AttributeType, s as TelemetryContract, t as ATTRIBUTE_TYPES, u as resolveAttributeSpec } from "./contract-DGjxR9nb.js";
+import { a as SchemaValidationSpanProcessor, c as createSchemaValidationProcessor, d as ValidateOptions, f as ViolationCode, g as validateSpan, h as hasErrors, i as SchemaValidationProcessorOptions, l as SchemaViolation, m as formatViolation, n as ReadableSpanLike, o as SpanLike, p as ViolationSeverity, r as SchemaProcessorMode, s as SpanProcessorLike, t as OtelContext, u as SpanShape } from "./processor-CK7LAdaa.js";
+
+//#region src/redaction.d.ts
+/**
+ * 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' },
+ * });
+ * ```
+ */
+declare function highCardinalityKeys(contract: TelemetryContract): string[];
+/**
+ * Predicate form of {@link highCardinalityKeys} — `true` when `key` is declared
+ * high-cardinality anywhere in the contract. Useful inside a custom
+ * `spanNameNormalizer` or redactor callback.
+ */
+declare function isHighCardinalityKey(contract: TelemetryContract, key: string): boolean;
+//#endregion
+export { ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type ChangeKind, type ChangeType, type ContractSnapshot, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanShape, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, formatDiff, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, parseSnapshot, resolveAttributeSpec, serializeSnapshot, validateSpan };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/redaction.ts"],"mappings":";;;;;;;AAwDa;;;;;;;;;;;;;;;;iBApBG,mBAAA,CAAoB,QAA2B,EAAjB,iBAAiB;;;;;;iBAkB/C,oBAAA,CACd,QAAA,EAAU,iBAAiB,EAC3B,GAAA"}

package/dist/index.js

@@ -0,0 +1,43 @@
+import { a as SNAPSHOT_SPEC, i as SCHEMA_ATTRS, n as parseSnapshot, r as serializeSnapshot, t as contractToSnapshot } from "./snapshot-h8pb_Up_.js";
+import { a as validateSpan, c as allowsAdditionalAttributes, i as hasErrors, l as defineContract, n as createSchemaValidationProcessor, o as ATTRIBUTE_TYPES, r as formatViolation, s as STABILITIES, t as SchemaValidationSpanProcessor, u as resolveAttributeSpec } from "./processor-FmvKYllX.js";
+import { diffSnapshots, formatDiff, hasBreakingChanges } from "./diff.js";
+
+//#region src/redaction.ts
+/**
+* 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' },
+* });
+* ```
+*/
+function highCardinalityKeys(contract) {
+	const keys = /* @__PURE__ */ new Set();
+	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.
+*/
+function isHighCardinalityKey(contract, key) {
+	if (contract.commonAttributes?.[key]?.highCardinality) return true;
+	for (const spanSpec of Object.values(contract.spans)) if (spanSpec.attributes?.[key]?.highCardinality) return true;
+	return false;
+}
+
+//#endregion
+export { ATTRIBUTE_TYPES, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, SchemaValidationSpanProcessor, allowsAdditionalAttributes, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, formatDiff, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, parseSnapshot, resolveAttributeSpec, serializeSnapshot, validateSpan };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/redaction.ts"],"sourcesContent":["/**\n * Cardinality posture helpers.\n *\n * The old cardinality rule — \"keep unique-value counts down\" — was a constraint\n * invented because dashboards have pixels and a graph with 10k series is\n * unreadable to a human. An agent does not look at the graph; it reads the\n * spans. A high-cardinality field (the user id, the sender domain, the request\n * id) is then the single most useful attribute on a trace when the agent is\n * chasing one specific failure.\n *\n * So the contract lets you mark attributes `highCardinality: true` as a\n * deliberate signal, and this module turns that into a *protect list*: the keys\n * a redactor or span-name normalizer must NOT strip, even when an aggressive\n * default would otherwise drop them.\n */\n\nimport type { TelemetryContract } from './contract.js';\n\n/**\n * Every attribute key in the contract flagged `highCardinality: true`, across\n * both common and per-span attributes. Feed this into a redaction/normalization\n * allow-list so the fields most useful to an agent reader survive.\n *\n * @example\n * ```ts\n * import { init } from 'autotel';\n * import { highCardinalityKeys } from 'autotel-schema';\n * import { contract } from './telemetry.contract';\n *\n * init({\n *   service: 'checkout',\n *   // keep user.id / request.id intact even under the strict redactor\n *   attributeRedactor: { allowKeys: highCardinalityKeys(contract), preset: 'strict' },\n * });\n * ```\n */\nexport function highCardinalityKeys(contract: TelemetryContract): string[] {\n  const keys = new Set<string>();\n  for (const [key, spec] of Object.entries(contract.commonAttributes ?? {})) {\n    if (spec.highCardinality) keys.add(key);\n  }\n  for (const spanSpec of Object.values(contract.spans)) {\n    for (const [key, spec] of Object.entries(spanSpec.attributes ?? {})) {\n      if (spec.highCardinality) keys.add(key);\n    }\n  }\n  return [...keys].toSorted();\n}\n\n/**\n * Predicate form of {@link highCardinalityKeys} — `true` when `key` is declared\n * high-cardinality anywhere in the contract. Useful inside a custom\n * `spanNameNormalizer` or redactor callback.\n */\nexport function isHighCardinalityKey(\n  contract: TelemetryContract,\n  key: string,\n): boolean {\n  if (contract.commonAttributes?.[key]?.highCardinality) return true;\n  for (const spanSpec of Object.values(contract.spans)) {\n    if (spanSpec.attributes?.[key]?.highCardinality) return true;\n  }\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,oBAAoB,UAAuC;CACzE,MAAM,uBAAO,IAAI,IAAY;CAC7B,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,oBAAoB,CAAC,CAAC,GACtE,IAAI,KAAK,iBAAiB,KAAK,IAAI,GAAG;CAExC,KAAK,MAAM,YAAY,OAAO,OAAO,SAAS,KAAK,GACjD,KAAK,MAAM,CAAC,KAAK,SAAS,OAAO,QAAQ,SAAS,cAAc,CAAC,CAAC,GAChE,IAAI,KAAK,iBAAiB,KAAK,IAAI,GAAG;CAG1C,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,SAAS;AAC5B;;;;;;AAOA,SAAgB,qBACd,UACA,KACS;CACT,IAAI,SAAS,mBAAmB,IAAI,EAAE,iBAAiB,OAAO;CAC9D,KAAK,MAAM,YAAY,OAAO,OAAO,SAAS,KAAK,GACjD,IAAI,SAAS,aAAa,IAAI,EAAE,iBAAiB,OAAO;CAE1D,OAAO;AACT"}

package/dist/processor-CK7LAdaa.d.ts

@@ -0,0 +1,100 @@
+import { s as TelemetryContract } from "./contract-DGjxR9nb.js";
+
+//#region src/validate.d.ts
+/** Severity of a contract violation. `error` = a breaking-shaped problem. */
+type ViolationSeverity = 'error' | 'warning';
+type ViolationCode = 'unknown_span' | 'unknown_attribute' | 'type_mismatch' | 'missing_required' | 'deprecated_attribute' | 'enum_violation';
+/** A single discrepancy between an emitted span and the contract. */
+interface SchemaViolation {
+  code: ViolationCode;
+  severity: ViolationSeverity;
+  spanName: string;
+  /** Attribute key involved, when the violation is attribute-scoped. */
+  attribute?: string;
+  message: string;
+  /** Nearest declared key, for likely typos (`unknown_attribute` only). */
+  suggestion?: string;
+}
+/** Minimal emitted-span shape — avoids a hard dependency on the OTel SDK. */
+interface SpanShape {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+interface ValidateOptions {
+  /** Report `unknown_span` for span names not in the contract. Default `false`. */
+  strictSpanNames?: boolean;
+}
+/**
+ * Validate one emitted span against the contract, returning every discrepancy.
+ * Order is deterministic: required-but-missing first, then per-attribute checks
+ * in attribute insertion order.
+ */
+declare function validateSpan(span: SpanShape, contract: TelemetryContract, options?: ValidateOptions): SchemaViolation[];
+/** `true` when any violation is `error` severity. */
+declare function hasErrors(violations: SchemaViolation[]): boolean;
+/** One-line human/agent-readable rendering of a violation. */
+declare function formatViolation(v: SchemaViolation): string;
+//#endregion
+//#region src/processor.d.ts
+/** Minimal ReadableSpan shape — matches OTel without a hard SDK dependency. */
+interface ReadableSpanLike {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+interface SpanLike {
+  spanContext(): {
+    traceId: string;
+    spanId: string;
+  };
+}
+/** Opaque parent context — matches OTel SpanProcessor without importing it. */
+type OtelContext = unknown;
+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. */
+type SchemaProcessorMode = 'warn' | 'throw' | 'silent';
+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;
+}
+/**
+ * Validates each ending span against a {@link TelemetryContract}. Bounded,
+ * deduplicated warnings; fail-open on any internal error.
+ */
+declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
+  private readonly opts;
+  private readonly enabled;
+  private readonly warnIntervalMs;
+  private readonly lastWarnAt;
+  private violationCount;
+  constructor(opts: SchemaValidationProcessorOptions);
+  /** Number of violations seen since startup (across all spans). */
+  get totalViolations(): number;
+  onStart(_span: SpanLike, _parentContext: OtelContext): void;
+  onEnd(span: ReadableSpanLike): void;
+  private handle;
+  private maybeWarn;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+declare function createSchemaValidationProcessor(opts: SchemaValidationProcessorOptions): SchemaValidationSpanProcessor;
+//#endregion
+export { SchemaValidationSpanProcessor as a, createSchemaValidationProcessor as c, ValidateOptions as d, ViolationCode as f, validateSpan as g, hasErrors as h, SchemaValidationProcessorOptions as i, SchemaViolation as l, formatViolation as m, ReadableSpanLike as n, SpanLike as o, ViolationSeverity as p, SchemaProcessorMode as r, SpanProcessorLike as s, OtelContext as t, SpanShape as u };
+//# sourceMappingURL=processor-CK7LAdaa.d.ts.map

package/dist/processor-CK7LAdaa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor-CK7LAdaa.d.ts","names":[],"sources":["../src/validate.ts","../src/processor.ts"],"mappings":";;;;KAcY,iBAAA;AAAA,KAEA,aAAA;AAAZ;AAAA,UASiB,eAAA;EACf,IAAA,EAAM,aAAA;EACN,QAAA,EAAU,iBAAiB;EAC3B,QAAA;EAHe;EAKf,SAAA;EACA,OAAA;EAJ2B;EAM3B,UAAA;AAAA;;UAIe,SAAA;EACf,IAAA;EACA,UAAA,EAAY,MAAM;AAAA;AAAA,UAGH,eAAA;EATL;EAWV,eAAe;AAAA;;;;;;iBAwHD,YAAA,CACd,IAAA,EAAM,SAAA,EACN,QAAA,EAAU,iBAAA,EACV,OAAA,GAAS,eAAA,GACR,eAAA;;iBA2Da,SAAA,CAAU,UAA6B,EAAjB,eAAe;AAzLrD;AAAA,iBA8LgB,eAAA,CAAgB,CAAkB,EAAf,eAAe;;;;UCvNjC,gBAAA;EACf,IAAA;EACA,UAAA,EAAY,MAAM;AAAA;AAAA,UAGH,QAAA;EACf,WAAA;IAAiB,OAAA;IAAiB,MAAA;EAAA;AAAA;;KAIxB,WAAA;AAAA,UAEK,iBAAA;EACf,OAAA,CAAQ,IAAA,EAAM,QAAA,EAAU,aAAA,EAAe,WAAA;EACvC,KAAA,CAAM,IAAA,EAAM,gBAAA;EACZ,QAAA,IAAY,OAAA;EACZ,UAAA,IAAc,OAAA;AAAA;;KAIJ,mBAAA;AAAA,UAEK,gCAAA,SAAyC,eAAA;EACxD,QAAA,EAAU,iBAAA;EDEoB;;;AAEf;AAwHjB;ECtHE,IAAA,GAAO,mBAAA;;EAEP,WAAA,IAAe,SAAA,EAAW,eAAA,EAAiB,IAAA,EAAM,gBAAA;EDsHvC;ECpHV,MAAA,IAAU,OAAA;EDsHT;ECpHD,mBAAA;EDoHgB;EClHhB,cAAA;AAAA;;;;;cAaW,6BAAA,YAAyC,iBAAA;EAAA,iBACnC,IAAA;EAAA,iBACA,OAAA;EAAA,iBACA,cAAA;EAAA,iBACA,UAAA;EAAA,QACT,cAAA;cAEI,IAAA,EAAM,gCAAA;EDyJmC;EAAA,IClJjD,eAAA;EAIJ,OAAA,CAAQ,KAAA,EAAO,QAAA,EAAU,cAAA,EAAgB,WAAA;EAIzC,KAAA,CAAM,IAAA,EAAM,gBAAA;EAAA,QAqBJ,MAAA;EAAA,QAWA,SAAA;EAiBF,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA;AAAA,iBAKJ,+BAAA,CACd,IAAA,EAAM,gCAAA,GACL,6BAA6B"}

package/dist/processor-CkBkzK6y.d.cts

@@ -0,0 +1,100 @@
+import { s as TelemetryContract } from "./contract-DGjxR9nb.cjs";
+
+//#region src/validate.d.ts
+/** Severity of a contract violation. `error` = a breaking-shaped problem. */
+type ViolationSeverity = 'error' | 'warning';
+type ViolationCode = 'unknown_span' | 'unknown_attribute' | 'type_mismatch' | 'missing_required' | 'deprecated_attribute' | 'enum_violation';
+/** A single discrepancy between an emitted span and the contract. */
+interface SchemaViolation {
+  code: ViolationCode;
+  severity: ViolationSeverity;
+  spanName: string;
+  /** Attribute key involved, when the violation is attribute-scoped. */
+  attribute?: string;
+  message: string;
+  /** Nearest declared key, for likely typos (`unknown_attribute` only). */
+  suggestion?: string;
+}
+/** Minimal emitted-span shape — avoids a hard dependency on the OTel SDK. */
+interface SpanShape {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+interface ValidateOptions {
+  /** Report `unknown_span` for span names not in the contract. Default `false`. */
+  strictSpanNames?: boolean;
+}
+/**
+ * Validate one emitted span against the contract, returning every discrepancy.
+ * Order is deterministic: required-but-missing first, then per-attribute checks
+ * in attribute insertion order.
+ */
+declare function validateSpan(span: SpanShape, contract: TelemetryContract, options?: ValidateOptions): SchemaViolation[];
+/** `true` when any violation is `error` severity. */
+declare function hasErrors(violations: SchemaViolation[]): boolean;
+/** One-line human/agent-readable rendering of a violation. */
+declare function formatViolation(v: SchemaViolation): string;
+//#endregion
+//#region src/processor.d.ts
+/** Minimal ReadableSpan shape — matches OTel without a hard SDK dependency. */
+interface ReadableSpanLike {
+  name: string;
+  attributes: Record<string, unknown>;
+}
+interface SpanLike {
+  spanContext(): {
+    traceId: string;
+    spanId: string;
+  };
+}
+/** Opaque parent context — matches OTel SpanProcessor without importing it. */
+type OtelContext = unknown;
+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. */
+type SchemaProcessorMode = 'warn' | 'throw' | 'silent';
+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;
+}
+/**
+ * Validates each ending span against a {@link TelemetryContract}. Bounded,
+ * deduplicated warnings; fail-open on any internal error.
+ */
+declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
+  private readonly opts;
+  private readonly enabled;
+  private readonly warnIntervalMs;
+  private readonly lastWarnAt;
+  private violationCount;
+  constructor(opts: SchemaValidationProcessorOptions);
+  /** Number of violations seen since startup (across all spans). */
+  get totalViolations(): number;
+  onStart(_span: SpanLike, _parentContext: OtelContext): void;
+  onEnd(span: ReadableSpanLike): void;
+  private handle;
+  private maybeWarn;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+declare function createSchemaValidationProcessor(opts: SchemaValidationProcessorOptions): SchemaValidationSpanProcessor;
+//#endregion
+export { SchemaValidationSpanProcessor as a, createSchemaValidationProcessor as c, ValidateOptions as d, ViolationCode as f, validateSpan as g, hasErrors as h, SchemaValidationProcessorOptions as i, SchemaViolation as l, formatViolation as m, ReadableSpanLike as n, SpanLike as o, ViolationSeverity as p, SchemaProcessorMode as r, SpanProcessorLike as s, OtelContext as t, SpanShape as u };
+//# sourceMappingURL=processor-CkBkzK6y.d.cts.map

package/dist/processor-CkBkzK6y.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor-CkBkzK6y.d.cts","names":[],"sources":["../src/validate.ts","../src/processor.ts"],"mappings":";;;;KAcY,iBAAA;AAAA,KAEA,aAAA;AAAZ;AAAA,UASiB,eAAA;EACf,IAAA,EAAM,aAAA;EACN,QAAA,EAAU,iBAAiB;EAC3B,QAAA;EAHe;EAKf,SAAA;EACA,OAAA;EAJ2B;EAM3B,UAAA;AAAA;;UAIe,SAAA;EACf,IAAA;EACA,UAAA,EAAY,MAAM;AAAA;AAAA,UAGH,eAAA;EATL;EAWV,eAAe;AAAA;;;;;;iBAwHD,YAAA,CACd,IAAA,EAAM,SAAA,EACN,QAAA,EAAU,iBAAA,EACV,OAAA,GAAS,eAAA,GACR,eAAA;;iBA2Da,SAAA,CAAU,UAA6B,EAAjB,eAAe;AAzLrD;AAAA,iBA8LgB,eAAA,CAAgB,CAAkB,EAAf,eAAe;;;;UCvNjC,gBAAA;EACf,IAAA;EACA,UAAA,EAAY,MAAM;AAAA;AAAA,UAGH,QAAA;EACf,WAAA;IAAiB,OAAA;IAAiB,MAAA;EAAA;AAAA;;KAIxB,WAAA;AAAA,UAEK,iBAAA;EACf,OAAA,CAAQ,IAAA,EAAM,QAAA,EAAU,aAAA,EAAe,WAAA;EACvC,KAAA,CAAM,IAAA,EAAM,gBAAA;EACZ,QAAA,IAAY,OAAA;EACZ,UAAA,IAAc,OAAA;AAAA;;KAIJ,mBAAA;AAAA,UAEK,gCAAA,SAAyC,eAAA;EACxD,QAAA,EAAU,iBAAA;EDEoB;;;AAEf;AAwHjB;ECtHE,IAAA,GAAO,mBAAA;;EAEP,WAAA,IAAe,SAAA,EAAW,eAAA,EAAiB,IAAA,EAAM,gBAAA;EDsHvC;ECpHV,MAAA,IAAU,OAAA;EDsHT;ECpHD,mBAAA;EDoHgB;EClHhB,cAAA;AAAA;;;;;cAaW,6BAAA,YAAyC,iBAAA;EAAA,iBACnC,IAAA;EAAA,iBACA,OAAA;EAAA,iBACA,cAAA;EAAA,iBACA,UAAA;EAAA,QACT,cAAA;cAEI,IAAA,EAAM,gCAAA;EDyJmC;EAAA,IClJjD,eAAA;EAIJ,OAAA,CAAQ,KAAA,EAAO,QAAA,EAAU,cAAA,EAAgB,WAAA;EAIzC,KAAA,CAAM,IAAA,EAAM,gBAAA;EAAA,QAqBJ,MAAA;EAAA,QAWA,SAAA;EAiBF,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA;AAAA,iBAKJ,+BAAA,CACd,IAAA,EAAM,gCAAA,GACL,6BAA6B"}