autotel-schema 12.0.0 → 13.0.0

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_snapshot = require('./snapshot-BJmrOlMK.cjs');
-const require_processor = require('./processor-C9NmN0wQ.cjs');
+const require_processor = require('./processor-DQvVwsvP.cjs');
 const require_diff = require('./diff.cjs');
 
 //#region src/completeness.ts
@@ -356,6 +356,7 @@ exports.AGENT_SECURITY_TELEMETRY_CONTRACT = AGENT_SECURITY_TELEMETRY_CONTRACT;
 exports.ATTRIBUTE_TYPES = require_processor.ATTRIBUTE_TYPES;
 exports.GENAI_COMPLETENESS_FIELDS = GENAI_COMPLETENESS_FIELDS;
 exports.SCHEMA_ATTRS = require_snapshot.SCHEMA_ATTRS;
+exports.SCHEMA_VIOLATION_ATTRS = require_processor.SCHEMA_VIOLATION_ATTRS;
 exports.SNAPSHOT_SPEC = require_snapshot.SNAPSHOT_SPEC;
 exports.STABILITIES = require_processor.STABILITIES;
 exports.SchemaValidationSpanProcessor = require_processor.SchemaValidationSpanProcessor;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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-B9GL_E28.cjs";
 import { A as validateScenarioSpec, C as ScenarioViolationCode, D as isScenarioClosed, E as formatScenarioResult, F as ViolationCode, I as ViolationSeverity, L as formatViolation, M as EmittedSpan, N as SchemaViolation, O as parseCardinality, P as ValidateOptions, R as hasErrors, S as ScenarioViolation, T as evaluateScenario, _ as ScenarioOutcome, a as SpanSpec, b as ScenarioSpan, c as allowsAdditionalAttributes, d as Cardinality, f as CheckScenarioOptions, g as ScenarioEventSpec, h as ScenarioAddition, i as STABILITIES, j as EmittedAttributeValue, k as proposeScenario, l as defineContract, m as EvaluateScenarioOptions, n as AttributeSpec, o as Stability, p as CompletionBoundary, r as AttributeType, s as TelemetryContract, t as ATTRIBUTE_TYPES, u as resolveAttributeSpec, v as ScenarioProposal, w as checkScenario, x as ScenarioSpec, y as ScenarioResult, z as validateSpan } from "./contract-CfOaZcD0.cjs";
-import { OtelContext, ReadableSpanLike, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor } from "./processor.cjs";
+import { OtelContext, ReadableSpanLike, SCHEMA_VIOLATION_ATTRS, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor } from "./processor.cjs";
 //#region src/completeness.d.ts
 /** The ten fields a GenAI trace is scored on. */
 declare const GENAI_COMPLETENESS_FIELDS: readonly ["llm_input", "llm_output", "model_name", "token_usage", "cost_usd", "latency_per_span", "tool_call_args", "tool_call_results", "span_tree", "span_count"];
@@ -99,4 +99,4 @@ declare function isHighCardinalityKey(contract: TelemetryContract, key: string):
  */
 declare const AGENT_SECURITY_TELEMETRY_CONTRACT: TelemetryContract;
 //#endregion
-export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type Cardinality, type ChangeKind, type ChangeType, type CheckScenarioOptions, type CompletenessOptions, type CompletenessResult, type CompletenessVerdict, type CompletionBoundary, type ContractSnapshot, type EmittedAttributeValue, type EmittedSpan, type EvaluateScenarioOptions, type FieldScore, GENAI_COMPLETENESS_FIELDS, type GenAiCompletenessField, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, type ScenarioAddition, type ScenarioEventSpec, type ScenarioOutcome, type ScenarioProposal, type ScenarioResult, type ScenarioSpan, type ScenarioSpec, type ScenarioViolation, type ScenarioViolationCode, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };
+export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type Cardinality, type ChangeKind, type ChangeType, type CheckScenarioOptions, type CompletenessOptions, type CompletenessResult, type CompletenessVerdict, type CompletionBoundary, type ContractSnapshot, type EmittedAttributeValue, type EmittedSpan, type EvaluateScenarioOptions, type FieldScore, GENAI_COMPLETENESS_FIELDS, type GenAiCompletenessField, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SCHEMA_VIOLATION_ATTRS, SNAPSHOT_SPEC, STABILITIES, type ScenarioAddition, type ScenarioEventSpec, type ScenarioOutcome, type ScenarioProposal, type ScenarioResult, type ScenarioSpan, type ScenarioSpec, type ScenarioViolation, type ScenarioViolationCode, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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-DenUg42T.js";
 import { A as validateScenarioSpec, C as ScenarioViolationCode, D as isScenarioClosed, E as formatScenarioResult, F as ViolationCode, I as ViolationSeverity, L as formatViolation, M as EmittedSpan, N as SchemaViolation, O as parseCardinality, P as ValidateOptions, R as hasErrors, S as ScenarioViolation, T as evaluateScenario, _ as ScenarioOutcome, a as SpanSpec, b as ScenarioSpan, c as allowsAdditionalAttributes, d as Cardinality, f as CheckScenarioOptions, g as ScenarioEventSpec, h as ScenarioAddition, i as STABILITIES, j as EmittedAttributeValue, k as proposeScenario, l as defineContract, m as EvaluateScenarioOptions, n as AttributeSpec, o as Stability, p as CompletionBoundary, r as AttributeType, s as TelemetryContract, t as ATTRIBUTE_TYPES, u as resolveAttributeSpec, v as ScenarioProposal, w as checkScenario, x as ScenarioSpec, y as ScenarioResult, z as validateSpan } from "./contract-CfOaZcD0.js";
-import { OtelContext, ReadableSpanLike, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor } from "./processor.js";
+import { OtelContext, ReadableSpanLike, SCHEMA_VIOLATION_ATTRS, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor } from "./processor.js";
 //#region src/completeness.d.ts
 /** The ten fields a GenAI trace is scored on. */
 declare const GENAI_COMPLETENESS_FIELDS: readonly ["llm_input", "llm_output", "model_name", "token_usage", "cost_usd", "latency_per_span", "tool_call_args", "tool_call_results", "span_tree", "span_count"];
@@ -99,4 +99,4 @@ declare function isHighCardinalityKey(contract: TelemetryContract, key: string):
  */
 declare const AGENT_SECURITY_TELEMETRY_CONTRACT: TelemetryContract;
 //#endregion
-export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type Cardinality, type ChangeKind, type ChangeType, type CheckScenarioOptions, type CompletenessOptions, type CompletenessResult, type CompletenessVerdict, type CompletionBoundary, type ContractSnapshot, type EmittedAttributeValue, type EmittedSpan, type EvaluateScenarioOptions, type FieldScore, GENAI_COMPLETENESS_FIELDS, type GenAiCompletenessField, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, type ScenarioAddition, type ScenarioEventSpec, type ScenarioOutcome, type ScenarioProposal, type ScenarioResult, type ScenarioSpan, type ScenarioSpec, type ScenarioViolation, type ScenarioViolationCode, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };
+export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, type AttributeSpec, type AttributeType, type Cardinality, type ChangeKind, type ChangeType, type CheckScenarioOptions, type CompletenessOptions, type CompletenessResult, type CompletenessVerdict, type CompletionBoundary, type ContractSnapshot, type EmittedAttributeValue, type EmittedSpan, type EvaluateScenarioOptions, type FieldScore, GENAI_COMPLETENESS_FIELDS, type GenAiCompletenessField, type OtelContext, type ReadableSpanLike, SCHEMA_ATTRS, SCHEMA_VIOLATION_ATTRS, SNAPSHOT_SPEC, STABILITIES, type ScenarioAddition, type ScenarioEventSpec, type ScenarioOutcome, type ScenarioProposal, type ScenarioResult, type ScenarioSpan, type ScenarioSpec, type ScenarioViolation, type ScenarioViolationCode, type SchemaAttributeKey, type SchemaProcessorMode, type SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, type SchemaViolation, type SnapshotAttribute, type SnapshotChange, type SnapshotDiff, type SnapshotSpan, type SpanLike, type SpanProcessorLike, type SpanSpec, type Stability, type TelemetryContract, type ValidateOptions, type ViolationCode, type ViolationSeverity, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as SNAPSHOT_SPEC, i as SCHEMA_ATTRS, n as parseSnapshot, r as serializeSnapshot, t as contractToSnapshot } from "./snapshot-BFIxChH0.js";
-import { _ as validateScenarioSpec, a as validateSpan, c as allowsAdditionalAttributes, d as checkScenario, f as evaluateScenario, g as proposeScenario, h as parseCardinality, i as hasErrors, l as defineContract, m as isScenarioClosed, n as createSchemaValidationProcessor, o as ATTRIBUTE_TYPES, p as formatScenarioResult, r as formatViolation, s as STABILITIES, t as SchemaValidationSpanProcessor, u as resolveAttributeSpec } from "./processor-Cn0HNUvw.js";
+import { _ as proposeScenario, a as hasErrors, c as STABILITIES, d as resolveAttributeSpec, f as checkScenario, g as parseCardinality, h as isScenarioClosed, i as formatViolation, l as allowsAdditionalAttributes, m as formatScenarioResult, n as SchemaValidationSpanProcessor, o as validateSpan, p as evaluateScenario, r as createSchemaValidationProcessor, s as ATTRIBUTE_TYPES, t as SCHEMA_VIOLATION_ATTRS, u as defineContract, v as validateScenarioSpec } from "./processor-PQss56h3.js";
 import { diffSnapshots, formatDiff, hasBreakingChanges } from "./diff.js";
 
 //#region src/completeness.ts
@@ -351,4 +351,4 @@ const AGENT_SECURITY_TELEMETRY_CONTRACT = defineContract({
 });
 
 //#endregion
-export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, GENAI_COMPLETENESS_FIELDS, SCHEMA_ATTRS, SNAPSHOT_SPEC, STABILITIES, SchemaValidationSpanProcessor, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };
+export { AGENT_SECURITY_TELEMETRY_CONTRACT, ATTRIBUTE_TYPES, GENAI_COMPLETENESS_FIELDS, SCHEMA_ATTRS, SCHEMA_VIOLATION_ATTRS, SNAPSHOT_SPEC, STABILITIES, SchemaValidationSpanProcessor, allowsAdditionalAttributes, checkScenario, contractToSnapshot, createSchemaValidationProcessor, defineContract, diffSnapshots, evaluateScenario, formatCompleteness, formatDiff, formatScenarioResult, formatViolation, hasBreakingChanges, hasErrors, highCardinalityKeys, isHighCardinalityKey, isScenarioClosed, parseCardinality, parseSnapshot, proposeScenario, resolveAttributeSpec, scoreGenAiCompleteness, serializeSnapshot, validateScenarioSpec, validateSpan };

package/dist/{processor-C9NmN0wQ.cjs → processor-DQvVwsvP.cjs}

@@ -566,6 +566,20 @@ function formatViolation(v) {
 * but `enabledInProduction` is there if you want a sampled canary in prod.
 */
 const DEFAULT_WARN_INTERVAL_MS = 6e4;
+/**
+* How many violation codes a single span carries.
+*
+* The count attribute stays exact, so trimming the list loses detail but never
+* misleads about scale. Without a cap, one span against a wide contract could
+* carry hundreds of strings into every exporter downstream.
+*/
+const MAX_STAMPED_CODES = 20;
+/** Attributes written onto a span carrying contract violations. */
+const SCHEMA_VIOLATION_ATTRS = {
+	count: "autotel.schema.violations",
+	severity: "autotel.schema.violation.severity",
+	codes: "autotel.schema.violation.codes"
+};
 function isProduction() {
 	return process.env.NODE_ENV === "production";
 }
@@ -600,12 +614,30 @@ var SchemaValidationSpanProcessor = class {
 		} catch {
 			return;
 		}
+		if (this.opts.stampViolations) this.stamp(span, violations);
 		for (const violation of violations) {
 			this.violationCount++;
 			this.opts.onViolation?.(violation, span);
 			this.handle(violation);
 		}
 	}
+	/**
+	* Record the violations on the span itself.
+	*
+	* A conforming span is left alone rather than marked with a zero: the
+	* presence of the attribute is what a reader filters on, and stamping every
+	* span would make `autotel.schema.violations` mean nothing while costing
+	* payload on the spans that are fine.
+	*/
+	stamp(span, violations) {
+		if (violations.length === 0) return;
+		try {
+			const worst = violations.some((v) => v.severity === "error") ? "error" : "warning";
+			span.attributes[SCHEMA_VIOLATION_ATTRS.count] = violations.length;
+			span.attributes[SCHEMA_VIOLATION_ATTRS.severity] = worst;
+			span.attributes[SCHEMA_VIOLATION_ATTRS.codes] = violations.slice(0, MAX_STAMPED_CODES).map((v) => v.attribute ? `${v.code}:${v.attribute}` : v.code);
+		} catch {}
+	}
 	handle(violation) {
 		const mode = this.opts.mode ?? "warn";
 		if (mode === "silent") return;
@@ -638,6 +670,12 @@ Object.defineProperty(exports, 'ATTRIBUTE_TYPES', {
     return ATTRIBUTE_TYPES;
   }
 });
+Object.defineProperty(exports, 'SCHEMA_VIOLATION_ATTRS', {
+  enumerable: true,
+  get: function () {
+    return SCHEMA_VIOLATION_ATTRS;
+  }
+});
 Object.defineProperty(exports, 'STABILITIES', {
   enumerable: true,
   get: function () {

package/dist/{processor-Cn0HNUvw.js → processor-PQss56h3.js}

@@ -565,6 +565,20 @@ function formatViolation(v) {
 * but `enabledInProduction` is there if you want a sampled canary in prod.
 */
 const DEFAULT_WARN_INTERVAL_MS = 6e4;
+/**
+* How many violation codes a single span carries.
+*
+* The count attribute stays exact, so trimming the list loses detail but never
+* misleads about scale. Without a cap, one span against a wide contract could
+* carry hundreds of strings into every exporter downstream.
+*/
+const MAX_STAMPED_CODES = 20;
+/** Attributes written onto a span carrying contract violations. */
+const SCHEMA_VIOLATION_ATTRS = {
+	count: "autotel.schema.violations",
+	severity: "autotel.schema.violation.severity",
+	codes: "autotel.schema.violation.codes"
+};
 function isProduction() {
 	return process.env.NODE_ENV === "production";
 }
@@ -599,12 +613,30 @@ var SchemaValidationSpanProcessor = class {
 		} catch {
 			return;
 		}
+		if (this.opts.stampViolations) this.stamp(span, violations);
 		for (const violation of violations) {
 			this.violationCount++;
 			this.opts.onViolation?.(violation, span);
 			this.handle(violation);
 		}
 	}
+	/**
+	* Record the violations on the span itself.
+	*
+	* A conforming span is left alone rather than marked with a zero: the
+	* presence of the attribute is what a reader filters on, and stamping every
+	* span would make `autotel.schema.violations` mean nothing while costing
+	* payload on the spans that are fine.
+	*/
+	stamp(span, violations) {
+		if (violations.length === 0) return;
+		try {
+			const worst = violations.some((v) => v.severity === "error") ? "error" : "warning";
+			span.attributes[SCHEMA_VIOLATION_ATTRS.count] = violations.length;
+			span.attributes[SCHEMA_VIOLATION_ATTRS.severity] = worst;
+			span.attributes[SCHEMA_VIOLATION_ATTRS.codes] = violations.slice(0, MAX_STAMPED_CODES).map((v) => v.attribute ? `${v.code}:${v.attribute}` : v.code);
+		} catch {}
+	}
 	handle(violation) {
 		const mode = this.opts.mode ?? "warn";
 		if (mode === "silent") return;
@@ -631,4 +663,4 @@ function createSchemaValidationProcessor(opts) {
 }
 
 //#endregion
-export { validateScenarioSpec as _, validateSpan as a, allowsAdditionalAttributes as c, checkScenario as d, evaluateScenario as f, proposeScenario as g, parseCardinality as h, hasErrors as i, defineContract as l, isScenarioClosed as m, createSchemaValidationProcessor as n, ATTRIBUTE_TYPES as o, formatScenarioResult as p, formatViolation as r, STABILITIES as s, SchemaValidationSpanProcessor as t, resolveAttributeSpec as u };
+export { proposeScenario as _, hasErrors as a, STABILITIES as c, resolveAttributeSpec as d, checkScenario as f, parseCardinality as g, isScenarioClosed as h, formatViolation as i, allowsAdditionalAttributes as l, formatScenarioResult as m, SchemaValidationSpanProcessor as n, validateSpan as o, evaluateScenario as p, createSchemaValidationProcessor as r, ATTRIBUTE_TYPES as s, SCHEMA_VIOLATION_ATTRS as t, defineContract as u, validateScenarioSpec as v };

package/dist/processor.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_processor = require('./processor-C9NmN0wQ.cjs');
+const require_processor = require('./processor-DQvVwsvP.cjs');
 
+exports.SCHEMA_VIOLATION_ATTRS = require_processor.SCHEMA_VIOLATION_ATTRS;
 exports.SchemaValidationSpanProcessor = require_processor.SchemaValidationSpanProcessor;
 exports.createSchemaValidationProcessor = require_processor.createSchemaValidationProcessor;

package/dist/processor.d.cts

@@ -45,7 +45,30 @@ interface SchemaValidationProcessorOptions extends ValidateOptions {
   enabledInProduction?: boolean;
   /** Throttle window for repeated identical warnings (ms). Default 60s. */
   warnIntervalMs?: number;
+  /**
+   * Write the violations onto the span before it is exported. Default `false`.
+   *
+   * **This is the handoff to anything that reads the span later.** The app
+   * owns the contract, so the app is the only thing that can validate; a
+   * viewer or a backend reading exported spans has no contract and never
+   * can. Marking the span is what lets a violation travel to where someone
+   * will see it.
+   *
+   * Opt-in because it changes what gets exported, and because the attributes
+   * cost payload on every non-conforming span. Turn it on in development, and
+   * in CI if something downstream reads the result.
+   *
+   * Ordering matters: this processor has to run *before* the one that exports,
+   * or the stamp lands after the span has already gone.
+   */
+  stampViolations?: boolean;
 }
+/** Attributes written onto a span carrying contract violations. */
+declare const SCHEMA_VIOLATION_ATTRS: {
+  readonly count: "autotel.schema.violations";
+  readonly severity: "autotel.schema.violation.severity";
+  readonly codes: "autotel.schema.violation.codes";
+};
 /**
  * Validates each ending span against a {@link TelemetryContract}. Bounded,
  * deduplicated warnings; fail-open on any internal error.
@@ -61,6 +84,15 @@ declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
   get totalViolations(): number;
   onStart(_span: SpanLike, _parentContext: OtelContext): void;
   onEnd(span: ReadableSpanLike): void;
+  /**
+   * Record the violations on the span itself.
+   *
+   * A conforming span is left alone rather than marked with a zero: the
+   * presence of the attribute is what a reader filters on, and stamping every
+   * span would make `autotel.schema.violations` mean nothing while costing
+   * payload on the spans that are fine.
+   */
+  private stamp;
   private handle;
   private maybeWarn;
   forceFlush(): Promise<void>;
@@ -68,4 +100,4 @@ declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
 }
 declare function createSchemaValidationProcessor(opts: SchemaValidationProcessorOptions): SchemaValidationSpanProcessor;
 //#endregion
-export { ContextValue, OtelContext, ReadableSpanLike, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor };
+export { ContextValue, OtelContext, ReadableSpanLike, SCHEMA_VIOLATION_ATTRS, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor };

package/dist/processor.d.ts

@@ -45,7 +45,30 @@ interface SchemaValidationProcessorOptions extends ValidateOptions {
   enabledInProduction?: boolean;
   /** Throttle window for repeated identical warnings (ms). Default 60s. */
   warnIntervalMs?: number;
+  /**
+   * Write the violations onto the span before it is exported. Default `false`.
+   *
+   * **This is the handoff to anything that reads the span later.** The app
+   * owns the contract, so the app is the only thing that can validate; a
+   * viewer or a backend reading exported spans has no contract and never
+   * can. Marking the span is what lets a violation travel to where someone
+   * will see it.
+   *
+   * Opt-in because it changes what gets exported, and because the attributes
+   * cost payload on every non-conforming span. Turn it on in development, and
+   * in CI if something downstream reads the result.
+   *
+   * Ordering matters: this processor has to run *before* the one that exports,
+   * or the stamp lands after the span has already gone.
+   */
+  stampViolations?: boolean;
 }
+/** Attributes written onto a span carrying contract violations. */
+declare const SCHEMA_VIOLATION_ATTRS: {
+  readonly count: "autotel.schema.violations";
+  readonly severity: "autotel.schema.violation.severity";
+  readonly codes: "autotel.schema.violation.codes";
+};
 /**
  * Validates each ending span against a {@link TelemetryContract}. Bounded,
  * deduplicated warnings; fail-open on any internal error.
@@ -61,6 +84,15 @@ declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
   get totalViolations(): number;
   onStart(_span: SpanLike, _parentContext: OtelContext): void;
   onEnd(span: ReadableSpanLike): void;
+  /**
+   * Record the violations on the span itself.
+   *
+   * A conforming span is left alone rather than marked with a zero: the
+   * presence of the attribute is what a reader filters on, and stamping every
+   * span would make `autotel.schema.violations` mean nothing while costing
+   * payload on the spans that are fine.
+   */
+  private stamp;
   private handle;
   private maybeWarn;
   forceFlush(): Promise<void>;
@@ -68,4 +100,4 @@ declare class SchemaValidationSpanProcessor implements SpanProcessorLike {
 }
 declare function createSchemaValidationProcessor(opts: SchemaValidationProcessorOptions): SchemaValidationSpanProcessor;
 //#endregion
-export { ContextValue, OtelContext, ReadableSpanLike, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor };
+export { ContextValue, OtelContext, ReadableSpanLike, SCHEMA_VIOLATION_ATTRS, SchemaProcessorMode, SchemaValidationProcessorOptions, SchemaValidationSpanProcessor, SpanLike, SpanProcessorLike, createSchemaValidationProcessor };

package/dist/processor.js

@@ -1,3 +1,3 @@
-import { n as createSchemaValidationProcessor, t as SchemaValidationSpanProcessor } from "./processor-Cn0HNUvw.js";
+import { n as SchemaValidationSpanProcessor, r as createSchemaValidationProcessor, t as SCHEMA_VIOLATION_ATTRS } from "./processor-PQss56h3.js";
 
-export { SchemaValidationSpanProcessor, createSchemaValidationProcessor };
+export { SCHEMA_VIOLATION_ATTRS, SchemaValidationSpanProcessor, createSchemaValidationProcessor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-schema",
-  "version": "12.0.0",
+  "version": "13.0.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",
@@ -44,7 +44,7 @@
   "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
   "license": "Apache-2.0",
   "peerDependencies": {
-    "autotel": "7.1.0"
+    "autotel": "7.2.0"
   },
   "peerDependenciesMeta": {
     "autotel": {