autotel-schema 2.0.4 → 3.0.0

package/dist/processor-BPp_DewZ.js

@@ -0,0 +1,635 @@
+//#region src/scenario.ts
+/**
+* Parse a cardinality shorthand: `'exactly 1'`, `'at least 1'`, `'at most 3'`,
+* `'0..1'`, `'2..'`. A canonical {@link Cardinality} passes through.
+*/
+function parseCardinality(input) {
+	if (typeof input !== "string") {
+		assert$1(Number.isInteger(input.min) && input.min >= 0, `cardinality min must be a non-negative integer, got ${input.min}`);
+		assert$1(input.max === void 0 || Number.isInteger(input.max) && input.max >= input.min, `cardinality max must be >= min, got ${input.max}`);
+		return input;
+	}
+	const exact = /^exactly (\d+)$/.exec(input);
+	if (exact) return {
+		min: Number(exact[1]),
+		max: Number(exact[1])
+	};
+	const atLeast = /^at least (\d+)$/.exec(input);
+	if (atLeast) return { min: Number(atLeast[1]) };
+	const atMost = /^at most (\d+)$/.exec(input);
+	if (atMost) return {
+		min: 0,
+		max: Number(atMost[1])
+	};
+	const range = /^(\d+)\.\.(\d*)$/.exec(input);
+	if (range) {
+		const min = Number(range[1]);
+		const max = range[2] === "" ? void 0 : Number(range[2]);
+		assert$1(max === void 0 || max >= min, `cardinality "${input}" has max < min`);
+		return {
+			min,
+			max
+		};
+	}
+	throw new Error(`autotel-schema: unparseable cardinality "${input}" (expected "exactly N", "at least N", "at most N", or "N..M")`);
+}
+function assert$1(condition, message) {
+	if (!condition) throw new Error(`autotel-schema: ${message}`);
+}
+const COMPLETION_MODES = [
+	"root-span-closed",
+	"terminal-event",
+	"externally-reconciled"
+];
+/**
+* Structural validation for one scenario declaration. Called by
+* `defineContract()` so a malformed scenario throws at module load.
+*/
+function validateScenarioSpec(name, spec) {
+	const scope = `scenario "${name}"`;
+	assert$1(spec.completion && typeof spec.completion === "object", `${scope} must declare a completion boundary`);
+	assert$1(COMPLETION_MODES.includes(spec.completion.mode), `${scope} has invalid completion mode "${spec.completion.mode}"`);
+	const budget = spec.completion.mode === "externally-reconciled" ? spec.completion.reconciliationDeadlineMs : spec.completion.observationBudgetMs;
+	assert$1(typeof budget === "number" && Number.isFinite(budget) && budget > 0, `${scope} completion budget must be a positive number of milliseconds`);
+	switch (spec.completion.mode) {
+		case "terminal-event":
+			assert$1(typeof spec.completion.event === "string" && spec.completion.event.length > 0, `${scope} terminal-event completion must declare a non-empty event`);
+			break;
+	}
+	assert$1(spec.events && typeof spec.events === "object" && Object.keys(spec.events).length > 0, `${scope} must declare at least one event`);
+	for (const [event, eventSpec] of Object.entries(spec.events)) {
+		if (eventSpec.cardinality !== void 0) try {
+			parseCardinality(eventSpec.cardinality);
+		} catch (error) {
+			throw new Error(`autotel-schema: ${scope} event "${event}": ${error.message}`);
+		}
+		if (eventSpec.status !== void 0) assert$1(eventSpec.status === "ok" || eventSpec.status === "error", `${scope} event "${event}" has invalid status "${eventSpec.status}"`);
+	}
+	for (const [from, to] of [...spec.edges ?? [], ...spec.optionalEdges ?? []]) assert$1(from in spec.events && to in spec.events, `${scope} edge ["${from}", "${to}"] references an undeclared event — declare both endpoints in events`);
+}
+/** Whether the scenario's completion boundary has closed for these spans. */
+function isScenarioClosed(spec, spans) {
+	const { completion } = spec;
+	switch (completion.mode) {
+		case "externally-reconciled": return false;
+		case "root-span-closed": return spans.some((s) => !s.parentSpanId);
+		case "terminal-event": return spans.some((s) => s.name === completion.event);
+	}
+}
+/** True when `span` has an ancestor named `ancestorName` within `byId`. */
+function hasAncestorNamed(span, ancestorName, byId) {
+	const seen = /* @__PURE__ */ new Set();
+	let parentId = span.parentSpanId;
+	while (parentId && !seen.has(parentId)) {
+		seen.add(parentId);
+		const parent = byId.get(parentId);
+		if (!parent) return false;
+		if (parent.name === ancestorName) return true;
+		parentId = parent.parentSpanId;
+	}
+	return false;
+}
+/**
+* Pure three-state evaluation of collected spans against a scenario.
+*
+* Definitive at any time (no closure needed): an unexpected error status, a
+* `max` cardinality exceeded. Meaningful only after closure: a missing event,
+* a `min` cardinality not reached, a missing required edge.
+*/
+function evaluateScenario(spec, spans, options) {
+	const name = options?.name ?? "scenario";
+	const closed = options?.closed ?? isScenarioClosed(spec, spans);
+	const violations = [];
+	const additions = [];
+	const countByName = /* @__PURE__ */ new Map();
+	for (const span of spans) countByName.set(span.name, (countByName.get(span.name) ?? 0) + 1);
+	for (const span of spans) if (span.status === "error" && spec.events[span.name]?.status !== "error") violations.push({
+		code: "unexpected_error",
+		event: span.name,
+		message: `"${span.name}" ended with status error, which the scenario does not declare`
+	});
+	for (const [event, eventSpec] of Object.entries(spec.events)) {
+		const { min, max } = parseCardinality(eventSpec.cardinality ?? { min: 1 });
+		const count = countByName.get(event) ?? 0;
+		if (max !== void 0 && count > max) violations.push({
+			code: "cardinality_violation",
+			event,
+			message: `"${event}" observed ${count}×, contract allows at most ${max}`
+		});
+		if (closed && count < min) violations.push({
+			code: count === 0 ? "missing_event" : "cardinality_violation",
+			event,
+			message: count === 0 ? `"${event}" was not observed and the completion boundary has closed` : `"${event}" observed ${count}×, contract requires at least ${min}`
+		});
+	}
+	if (closed) {
+		const byId = /* @__PURE__ */ new Map();
+		for (const span of spans) byId.set(span.spanId, span);
+		for (const [from, to] of spec.edges ?? []) if (!spans.some((s) => s.name === to && hasAncestorNamed(s, from, byId))) violations.push({
+			code: "missing_edge",
+			edge: [from, to],
+			message: `no "${to}" span has ancestor "${from}"`
+		});
+	}
+	for (const [event, count] of [...countByName.entries()].toSorted()) if (!(event in spec.events)) additions.push({
+		code: "undeclared_event",
+		event,
+		count,
+		message: `"${event}" observed ${count}× but not declared — additive, consider adding it to the scenario`
+	});
+	return {
+		scenario: name,
+		outcome: violations.length > 0 ? "non-conformant" : closed ? "conformant" : "incomplete",
+		closed,
+		violations,
+		additions,
+		spans: [...spans]
+	};
+}
+/**
+* Poll `getSpans` until the scenario's completion boundary closes, a
+* definitive violation appears (fail fast), or the observation budget is
+* spent — then evaluate.
+*
+* The observation budget bounds how long *this checker* waits; it is not a
+* statement that the operation is allowed to take that long. Express a
+* business deadline as its own assertion on the returned spans.
+*
+* An `externally-reconciled` boundary never closes in-process: the check
+* evaluates the current snapshot once and reports `incomplete` unless a
+* definitive violation is already present.
+*/
+async function checkScenario(spec, getSpans, options) {
+	const name = options?.name;
+	if (spec.completion.mode === "externally-reconciled") return evaluateScenario(spec, await getSpans(), { name });
+	const budgetMs = options?.budgetMs ?? spec.completion.observationBudgetMs;
+	const pollIntervalMs = options?.pollIntervalMs ?? 25;
+	assert$1(Number.isFinite(budgetMs) && budgetMs > 0, "checkScenario budgetMs must be a positive number of milliseconds");
+	assert$1(Number.isFinite(pollIntervalMs) && pollIntervalMs >= 0, "checkScenario pollIntervalMs must be a non-negative number of milliseconds");
+	const deadline = Date.now() + budgetMs;
+	let lastResult = evaluateScenario(spec, [], { name });
+	for (;;) {
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) return lastResult;
+		let timeout;
+		let next;
+		try {
+			next = await Promise.race([Promise.resolve().then(getSpans).then((spans) => ({
+				kind: "spans",
+				spans
+			})), new Promise((resolve) => {
+				timeout = setTimeout(() => resolve({ kind: "timeout" }), remainingMs);
+			})]);
+		} finally {
+			if (timeout !== void 0) clearTimeout(timeout);
+		}
+		if (next.kind === "timeout") return lastResult;
+		const { spans } = next;
+		const result = evaluateScenario(spec, spans, { name });
+		lastResult = result;
+		if (result.closed || result.outcome === "non-conformant") return result;
+		const waitMs = Math.min(pollIntervalMs, deadline - Date.now());
+		if (waitMs <= 0) return result;
+		await new Promise((resolve) => setTimeout(resolve, waitMs));
+	}
+}
+/** Human-readable summary of a scenario result, for assertion messages. */
+function formatScenarioResult(result) {
+	const lines = [`scenario "${result.scenario}": ${result.outcome}${result.closed ? "" : " (completion boundary did not close)"}`];
+	for (const v of result.violations) lines.push(`  ✗ ${v.message}`);
+	for (const a of result.additions) lines.push(`  + ${a.message}`);
+	return lines.join("\n");
+}
+/**
+* Draft a scenario contract from repeated controlled runs (record → propose →
+* commit). Events stable across every run become required with their observed
+* cardinality; variable ones get a range and a review note. The draft is a
+* starting point for human curation, not a finished contract.
+*/
+function proposeScenario(runs, options) {
+	assert$1(runs.length > 0, "proposeScenario needs at least one recorded run");
+	for (const [index, run] of runs.entries()) assert$1(run.length > 0, `proposeScenario run ${index + 1} has no recorded spans`);
+	const name = options?.name ?? "scenario";
+	const notes = [];
+	const total = runs.length;
+	const names = /* @__PURE__ */ new Set();
+	const countsPerRun = runs.map((run) => {
+		const counts = /* @__PURE__ */ new Map();
+		for (const span of run) {
+			names.add(span.name);
+			counts.set(span.name, (counts.get(span.name) ?? 0) + 1);
+		}
+		return counts;
+	});
+	const events = {};
+	for (const event of [...names].toSorted()) {
+		const counts = countsPerRun.map((c) => c.get(event) ?? 0);
+		const min = Math.min(...counts);
+		const max = Math.max(...counts);
+		const seenIn = counts.filter((c) => c > 0).length;
+		events[event] = { cardinality: min === max ? `exactly ${min}` : {
+			min,
+			max
+		} };
+		notes.push(min === max ? `${event}: exactly ${min} (${seenIn}/${total} runs)` : `${event}: ${min}..${max} (${seenIn}/${total} runs) — review: variable`);
+		if (runs.some((run) => run.some((s) => s.name === event && s.status === "error"))) notes.push(`${event}: observed with status error — review: expected?`);
+	}
+	const edgeRuns = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		const byId = new Map(run.map((s) => [s.spanId, s]));
+		const pairs = /* @__PURE__ */ new Set();
+		for (const span of run) {
+			const parent = span.parentSpanId ? byId.get(span.parentSpanId) : void 0;
+			if (parent) pairs.add(`${parent.name}${span.name}`);
+		}
+		for (const pair of pairs) edgeRuns.set(pair, (edgeRuns.get(pair) ?? 0) + 1);
+	}
+	const edges = [];
+	const optionalEdges = [];
+	for (const [pair, seen] of [...edgeRuns.entries()].toSorted()) {
+		const [from, to] = pair.split("\0");
+		if (seen === total) edges.push([from, to]);
+		else {
+			optionalEdges.push([from, to]);
+			notes.push(`edge ${from} → ${to}: ${seen}/${total} runs — proposed optional`);
+		}
+	}
+	let completion;
+	const lastNames = /* @__PURE__ */ new Set();
+	let maxMakespanMs = 0;
+	let hasTiming = true;
+	for (const run of runs) {
+		let last;
+		let start = Number.POSITIVE_INFINITY;
+		let end = 0;
+		for (const span of run) {
+			if (span.startTimeMs === void 0 || span.durationMs === void 0) {
+				hasTiming = false;
+				break;
+			}
+			const spanEnd = span.startTimeMs + span.durationMs;
+			start = Math.min(start, span.startTimeMs);
+			if (spanEnd >= end) {
+				end = spanEnd;
+				last = span;
+			}
+		}
+		if (!hasTiming) break;
+		if (last) lastNames.add(last.name);
+		maxMakespanMs = Math.max(maxMakespanMs, end - start);
+	}
+	const observationBudgetMs = hasTiming ? Math.max(1e3, Math.ceil(maxMakespanMs * 3)) : 3e4;
+	if (hasTiming && lastNames.size === 1) {
+		const [event] = [...lastNames];
+		completion = {
+			mode: "terminal-event",
+			event,
+			observationBudgetMs
+		};
+		notes.push(`completion: terminal-event "${event}" (last to end in all ${total} runs), budget ${observationBudgetMs}ms (3× slowest observed run)`);
+	} else {
+		completion = {
+			mode: "root-span-closed",
+			observationBudgetMs
+		};
+		notes.push(hasTiming ? `completion: root-span-closed (last-ending span varies: ${[...lastNames].toSorted().join(", ")}), budget ${observationBudgetMs}ms` : `completion: root-span-closed, budget ${observationBudgetMs}ms (default — no timing data recorded)`);
+	}
+	const scenario = {
+		description: `Proposed from ${total} recorded run${total === 1 ? "" : "s"} of ${name} — review before committing`,
+		completion,
+		events,
+		...edges.length > 0 ? { edges } : {},
+		...optionalEdges.length > 0 ? { optionalEdges } : {}
+	};
+	validateScenarioSpec(name, scenario);
+	return {
+		scenario,
+		notes
+	};
+}
+
+//#endregion
+//#region src/contract.ts
+/**
+* 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.
+*/
+const ATTRIBUTE_TYPES = [
+	"string",
+	"number",
+	"boolean",
+	"string[]",
+	"number[]",
+	"boolean[]"
+];
+const STABILITIES = [
+	"stable",
+	"experimental",
+	"deprecated"
+];
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;
+function assert(condition, message) {
+	if (!condition) throw new Error(`autotel-schema: ${message}`);
+}
+function validateAttribute(scope, key, spec) {
+	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 !== void 0 || spec.deprecatedReason !== void 0, `${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 },
+*       },
+*     },
+*   },
+* });
+* ```
+*/
+function defineContract(contract) {
+	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);
+	for (const [name, spec] of Object.entries(contract.scenarios ?? {})) validateScenarioSpec(name, 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.
+*/
+function resolveAttributeSpec(contract, spanName, key) {
+	return contract.spans[spanName]?.attributes?.[key] ?? contract.commonAttributes?.[key];
+}
+/** Whether attributes outside the declared set are tolerated for a span. */
+function allowsAdditionalAttributes(contract, spanName) {
+	return contract.spans[spanName]?.additionalAttributes ?? contract.additionalAttributes ?? false;
+}
+
+//#endregion
+//#region src/validate.ts
+/**
+* Pure span-vs-contract validation. No SDK, no side effects — the same engine
+* the runtime processor ({@link ./processor}) and any test harness can call.
+*/
+/** `'empty[]'` is a distinct marker: an empty array satisfies any array type. */
+function actualType(value) {
+	if (typeof value === "string") return "string";
+	if (typeof value === "number") return "number";
+	if (typeof value === "boolean") return "boolean";
+	if (Array.isArray(value)) {
+		const first = value.find((v) => v !== null && v !== void 0);
+		if (first === void 0) return "empty[]";
+		if (typeof first === "string") return "string[]";
+		if (typeof first === "number") return "number[]";
+		if (typeof first === "boolean") return "boolean[]";
+	}
+	return "unknown";
+}
+function typeMatches(expected, value) {
+	const actual = actualType(value);
+	if (actual === "unknown") return false;
+	if (actual === "empty[]") return expected.endsWith("[]");
+	return actual === expected;
+}
+/** Levenshtein distance — small, allocation-light, good enough for key typos. */
+function editDistance(a, b) {
+	const m = a.length;
+	const n = b.length;
+	if (m === 0) return n;
+	if (n === 0) return m;
+	let prev = Array.from({ length: n + 1 }, (_, i) => i);
+	let curr = Array.from({ length: n + 1 });
+	for (let i = 1; i <= m; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+		}
+		[prev, curr] = [curr, prev];
+	}
+	return prev[n];
+}
+/**
+* Closest declared key to `key`, when one is within a small edit distance.
+* Turns "you emitted an attribute I don't know" into "did you mean `user.id`?".
+*/
+function nearestKey(key, candidates) {
+	let best;
+	let bestDistance = Infinity;
+	const threshold = Math.max(1, Math.floor(key.length / 4) + 1);
+	for (const candidate of candidates) {
+		const d = editDistance(key, candidate);
+		if (d < bestDistance && d <= threshold) {
+			best = candidate;
+			bestDistance = d;
+		}
+	}
+	return best;
+}
+function declaredKeysFor(contract, spanName) {
+	return [...Object.keys(contract.spans[spanName]?.attributes ?? {}), ...Object.keys(contract.commonAttributes ?? {})];
+}
+function checkValue(spanName, key, value, spec, out) {
+	if (!typeMatches(spec.type, value)) {
+		out.push({
+			code: "type_mismatch",
+			severity: "error",
+			spanName,
+			attribute: key,
+			message: `attribute "${key}" should be ${spec.type} but got ${actualType(value)}`
+		});
+		return;
+	}
+	if (spec.enum && (typeof value === "string" || typeof value === "number") && !spec.enum.includes(value)) out.push({
+		code: "enum_violation",
+		severity: "error",
+		spanName,
+		attribute: key,
+		message: `attribute "${key}" value ${JSON.stringify(value)} is not one of ${JSON.stringify(spec.enum)}`
+	});
+	if (spec.stability === "deprecated") {
+		const hint = spec.replacedBy ? ` — use "${spec.replacedBy}" instead` : spec.deprecatedReason ? ` — ${spec.deprecatedReason}` : "";
+		out.push({
+			code: "deprecated_attribute",
+			severity: "warning",
+			spanName,
+			attribute: key,
+			message: `attribute "${key}" is deprecated${hint}`,
+			suggestion: spec.replacedBy
+		});
+	}
+}
+/**
+* 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.
+*/
+function validateSpan(span, contract, options = {}) {
+	const out = [];
+	const spanSpec = contract.spans[span.name];
+	if (!spanSpec) {
+		if (options.strictSpanNames) out.push({
+			code: "unknown_span",
+			severity: "warning",
+			spanName: span.name,
+			message: `span "${span.name}" is not declared in the contract`
+		});
+		return out;
+	}
+	const required = [...Object.entries(spanSpec.attributes ?? {}), ...Object.entries(contract.commonAttributes ?? {})].filter(([, spec]) => spec.required);
+	for (const [key] of required) if (!(key in span.attributes)) out.push({
+		code: "missing_required",
+		severity: "error",
+		spanName: span.name,
+		attribute: key,
+		message: `required attribute "${key}" is missing`
+	});
+	const allowExtra = allowsAdditionalAttributes(contract, span.name);
+	const declared = allowExtra ? [] : declaredKeysFor(contract, span.name);
+	for (const [key, value] of Object.entries(span.attributes)) {
+		if (value === null || value === void 0) continue;
+		const spec = resolveAttributeSpec(contract, span.name, key);
+		if (!spec) {
+			if (!allowExtra) out.push({
+				code: "unknown_attribute",
+				severity: "warning",
+				spanName: span.name,
+				attribute: key,
+				message: `attribute "${key}" is not declared on span "${span.name}"`,
+				suggestion: nearestKey(key, declared)
+			});
+			continue;
+		}
+		checkValue(span.name, key, value, spec, out);
+	}
+	return out;
+}
+/** `true` when any violation is `error` severity. */
+function hasErrors(violations) {
+	return violations.some((v) => v.severity === "error");
+}
+/** One-line human/agent-readable rendering of a violation. */
+function formatViolation(v) {
+	const where = v.attribute ? `${v.spanName}.${v.attribute}` : v.spanName;
+	const suffix = v.suggestion ? ` (did you mean "${v.suggestion}"?)` : "";
+	return `[${v.severity}] ${v.code} @ ${where}: ${v.message}${suffix}`;
+}
+
+//#endregion
+//#region src/processor.ts
+/**
+* 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.
+*/
+const DEFAULT_WARN_INTERVAL_MS = 6e4;
+function isProduction() {
+	return process.env.NODE_ENV === "production";
+}
+/**
+* Validates each ending span against a {@link TelemetryContract}. Bounded,
+* deduplicated warnings; fail-open on any internal error.
+*/
+var SchemaValidationSpanProcessor = class {
+	opts;
+	enabled;
+	warnIntervalMs;
+	lastWarnAt = /* @__PURE__ */ new Map();
+	violationCount = 0;
+	constructor(opts) {
+		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() {
+		return this.violationCount;
+	}
+	onStart(_span, _parentContext) {}
+	onEnd(span) {
+		if (!this.enabled) return;
+		let violations;
+		try {
+			violations = validateSpan({
+				name: span.name,
+				attributes: span.attributes
+			}, this.opts.contract, { strictSpanNames: this.opts.strictSpanNames });
+		} catch {
+			return;
+		}
+		for (const violation of violations) {
+			this.violationCount++;
+			this.opts.onViolation?.(violation, span);
+			this.handle(violation);
+		}
+	}
+	handle(violation) {
+		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);
+	}
+	maybeWarn(violation) {
+		const key = `${violation.code}:${violation.spanName}:${violation.attribute ?? ""}`;
+		const now = Date.now();
+		if (now - (this.lastWarnAt.get(key) ?? 0) < 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() {}
+	async shutdown() {
+		this.lastWarnAt.clear();
+	}
+};
+function createSchemaValidationProcessor(opts) {
+	return new SchemaValidationSpanProcessor(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 };
+//# sourceMappingURL=processor-BPp_DewZ.js.map