@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/decision/telemetry/runtime.js

@@ -0,0 +1,310 @@
+import { extractTraceContext, transportTraceContext } from './context.js';
+import { mapAdmissionEvidence, mapDecisionAttempt, mapDecisionResult, mapRulesetResult } from './mapping.js';
+import { DecisionTraceBuilder, recordBatchReceiptTrace } from './trace.js';
+import { recordDecisionSpanMetrics } from './metrics.js';
+import { sanitizeAttributes } from './redaction.js';
+// Keyed by the per-invocation telemetry object, which request snapshots copy by reference.
+const TRACES = new WeakMap();
+const USAGE_KEYS = ['gen_ai.usage.input_tokens', 'gen_ai.usage.output_tokens', 'aiwg.usage.cost_usd',
+    'aiwg.usage.cost_provenance', 'aiwg.provider.request_id', 'aiwg.provider.request_id_source'];
+/**
+ * Records metadata-only spans while one evaluator invocation runs. Spans carry
+ * live start/end times, are buffered in start order and flushed once after the
+ * terminal result. Every failure disables the trace; none reaches the decision.
+ */
+export class DecisionRuntimeTrace {
+    telemetry;
+    now;
+    builder;
+    root;
+    validate;
+    batchSpans = new Map();
+    disabled = false;
+    constructor(telemetry, now) {
+        this.telemetry = telemetry;
+        this.now = now;
+        this.builder = new DecisionTraceBuilder(telemetry.ids, now);
+        this.root = this.builder.startSpan('decision.workflow', telemetry.parent ? { parent: telemetry.parent } : {});
+    }
+    /** Start the root span and bind the trace to a request copy. Invalid ID sources disable telemetry. */
+    static begin(request) {
+        if (!request.telemetry)
+            return { request, trace: null };
+        try {
+            const telemetry = { ...request.telemetry };
+            const trace = new DecisionRuntimeTrace(telemetry, request.now ?? Date.now);
+            TRACES.set(telemetry, trace);
+            return { request: { ...request, telemetry }, trace };
+        }
+        catch {
+            return { request, trace: null };
+        }
+    }
+    /** W3C traceparent of the workflow span, for durable receipts created by this invocation. */
+    get traceParent() {
+        return this.disabled ? undefined : transportTraceContext(this.root.context).traceparent;
+    }
+    validated(rejected) {
+        this.guard(() => {
+            if (this.validate)
+                return;
+            const outcome = rejected ? 'rejected' : 'accepted';
+            this.validate = this.builder.startSpan('decision.validate', { parent: this.root.context,
+                startTimeUnixMs: this.root.startTimeUnixMs,
+                attributes: { 'aiwg.validation.outcome': outcome }, provenance: { 'aiwg.validation.outcome': 'client-derived' } });
+            this.builder.endSpan(this.validate, rejected ? 'error' : 'ok');
+        });
+    }
+    startAttempt(alias, target, ordinal, fallback = false) {
+        return this.guard(() => {
+            // Known before dispatch, so an attempt whose outcome is never observed still names its route.
+            const attributes = { 'aiwg.decision.alias': alias, 'aiwg.adapter.id': target.adapter,
+                'aiwg.adapter.version': target.adapterVersion, 'gen_ai.request.model': target.model,
+                'aiwg.attempt.ordinal': ordinal, 'aiwg.route.fallback': fallback };
+            return this.open(this.builder.startSpan('decision.attempt', { parent: this.root.context, attributes,
+                provenance: Object.fromEntries(Object.keys(attributes).map(key => [key, 'client-derived'])) }), ordinal);
+        });
+    }
+    endAttempt(handle, attempt) {
+        this.guard(() => {
+            if (!handle)
+                return;
+            const mapped = mapDecisionAttempt(attempt);
+            this.builder.annotate(handle.span, mapped.attributes, mapped.provenance);
+            if (attempt.termination)
+                handle.span.events.push({ name: 'attempt.terminated', timeUnixMs: this.now(),
+                    attributes: { 'aiwg.attempt.termination': attempt.termination } });
+            this.builder.endSpan(handle.span, attempt.status === 'success' ? 'ok' : 'error');
+        });
+    }
+    /**
+     * Open the live D05 `decision.admit` span for one admission decision. A granted
+     * lease stays open until release, so breaker transitions caused by the attempt
+     * land inside the span; a rejection or deferral closes it at once. Evidence is
+     * metadata-only by contract: principal and workspace IDs never reach the span.
+     */
+    startAdmission(alias, adapterId, startedAtMs, evidence) {
+        const handle = this.guard(() => {
+            const mapped = mapAdmissionEvidence(evidence);
+            return { closed: false, span: this.builder.startSpan('decision.admit', { parent: this.root.context, startTimeUnixMs: startedAtMs,
+                    attributes: { ...mapped.attributes, 'aiwg.decision.alias': alias, 'aiwg.adapter.id': adapterId },
+                    provenance: { ...mapped.provenance, 'aiwg.decision.alias': 'client-derived', 'aiwg.adapter.id': 'client-derived' } }) };
+        });
+        if (evidence.decision !== 'admit')
+            this.endAdmission(handle, evidence);
+        return handle;
+    }
+    /** Close an admission span once; later calls are ignored. */
+    endAdmission(handle, evidence) {
+        this.guard(() => {
+            if (!handle || handle.closed)
+                return;
+            handle.closed = true;
+            for (const change of evidence.breakerTransitions ?? []) {
+                handle.span.events.push({ name: 'breaker.transition', timeUnixMs: this.now(),
+                    attributes: { 'aiwg.breaker.from': change.from, 'aiwg.breaker.to': change.to } });
+            }
+            this.builder.endSpan(handle.span, evidence.decision === 'admit' ? 'ok' : evidence.decision === 'reject' ? 'error' : 'unset');
+        });
+    }
+    /** Record one D10 projection step, under its attempt span when there is one. */
+    projected(alias, parent, startedAtMs, result) {
+        this.guard(() => {
+            const attributes = { 'aiwg.decision.alias': alias, 'aiwg.projection.mode': result.mode,
+                'aiwg.projection.outcome': result.outcome };
+            if (result.reason)
+                attributes['aiwg.projection.reason'] = result.reason;
+            if (result.fieldCount !== undefined)
+                attributes['aiwg.projection.field_count'] = result.fieldCount;
+            if (result.incompleteContext !== undefined)
+                attributes['aiwg.projection.incomplete_context'] = result.incompleteContext;
+            if (result.automaticActionAllowed !== undefined) {
+                attributes['aiwg.projection.automatic_action_allowed'] = result.automaticActionAllowed;
+            }
+            const span = this.builder.startSpan('decision.project', { parent: (parent?.span ?? this.root).context,
+                startTimeUnixMs: startedAtMs, attributes,
+                provenance: Object.fromEntries(Object.keys(attributes).map(key => [key, 'client-derived'])) });
+            this.builder.endSpan(span, result.outcome === 'allowed' ? 'ok' : 'error');
+        });
+    }
+    retryScheduled(handle, delayMs) {
+        this.guard(() => {
+            if (!handle)
+                return;
+            this.builder.annotate(handle.span, { 'aiwg.retry.delay_ms': delayMs }, { 'aiwg.retry.delay_ms': 'client-derived' });
+            handle.span.events.push({ name: 'retry.scheduled', timeUnixMs: this.now(), attributes: { 'aiwg.retry.delay_ms': delayMs } });
+        });
+    }
+    /** Open the shared request span before dispatch; its context is what the transport receives. */
+    startBatch(aliases, groupId, ordinal) {
+        return this.guard(() => {
+            const span = this.builder.startSpan('decision.batch.request', { parent: this.root.context,
+                attributes: { 'aiwg.batch.id': groupId, 'aiwg.batch.mode': 'native', 'aiwg.batch.item_count': aliases.length,
+                    'aiwg.attempt.ordinal': ordinal },
+                provenance: { 'aiwg.batch.id': 'client-derived', 'aiwg.batch.mode': 'client-derived',
+                    'aiwg.batch.item_count': 'client-derived', 'aiwg.attempt.ordinal': 'client-derived' } });
+            for (const alias of aliases)
+                this.batchSpans.set(alias, [...this.batchSpans.get(alias) ?? [], span]);
+            return this.open(span, ordinal);
+        });
+    }
+    /**
+     * Close one batch plan. A durable receipt is the accounting authority and is
+     * bridged through `recordBatchReceiptTrace`; without one, shared usage comes
+     * from the single transport response. A replayed receipt dispatched nothing
+     * here, so it only links back to the trace that created it.
+     */
+    finishBatch(handles, receipt) {
+        this.guard(() => {
+            if (receipt && handles.length === 0) {
+                this.linkOrigin(receipt.traceParent, 'batch', { 'aiwg.batch.id': receipt.batchId });
+                return;
+            }
+            if (receipt) {
+                recordBatchReceiptTrace(this.builder, receipt, this.root.context, new Map(handles.map(handle => [handle.ordinal, handle.span])));
+                return;
+            }
+            for (const handle of handles) {
+                if (!handle.response || handle.span.status !== 'unset')
+                    continue;
+                const answers = handle.response.answers.map(answer => answer.observation);
+                const requestIds = [...new Set(answers.map(answer => answer.requestId).filter((id) => id !== null))];
+                const models = [...new Set(answers.map(answer => answer.actualModel).filter((model) => model !== null))];
+                this.builder.recordBatchUsage(handle.span, String(handle.span.attributes['aiwg.batch.id']), handle.response.sharedUsage, { requestId: requestIds.length === 1 ? requestIds[0] : null, actualModel: models.length === 1 ? models[0] : null }, { accountingKey: handle.span.context.spanId });
+                this.builder.endSpan(handle.span, answers.every(answer => answer.status === 'success') ? 'ok' : 'error');
+            }
+        });
+    }
+    /** Link the workflow to the trace that created a durable receipt this invocation is replaying. */
+    linkOrigin(traceParent, relationship, attributes) {
+        this.guard(() => {
+            const origin = traceParent ? extractTraceContext({ traceparent: traceParent }) : null;
+            if (!origin || (origin.traceId === this.root.context.traceId && origin.spanId === this.root.context.spanId)
+                || this.root.links.some(link => link.traceId === origin.traceId && link.spanId === origin.spanId))
+                return;
+            this.root.links.push({ traceId: origin.traceId, spanId: origin.spanId, relationship,
+                ...(Object.keys(attributes).length ? { attributes: sanitizeAttributes(attributes) } : {}) });
+        });
+    }
+    /** Record normalize/accept for one finished evaluation, linked to any shared batch request. */
+    decided(result) {
+        this.guard(() => {
+            const batches = this.batchSpans.get(result.spec.alias) ?? [];
+            const links = batches.map((span) => ({ traceId: span.context.traceId, spanId: span.context.spanId,
+                relationship: 'batch' }));
+            result.spec.attempts.forEach((attempt, index) => {
+                const request = batches[index];
+                // Native answers without a request span from this invocation are replayed evidence, not new work.
+                if (attempt.batch?.mode !== 'native' || !request)
+                    return;
+                const mapped = withoutUsage(mapDecisionAttempt(attempt));
+                const span = this.builder.startSpan('decision.attempt', { parent: this.root.context,
+                    startTimeUnixMs: request.startTimeUnixMs, links: [links[index]],
+                    attributes: { ...mapped.attributes, 'aiwg.decision.alias': result.spec.alias, 'aiwg.usage.scope': 'batch-answer' },
+                    provenance: { ...mapped.provenance, 'aiwg.decision.alias': 'client-derived', 'aiwg.usage.scope': 'client-derived' } });
+                this.builder.endSpan(span, attempt.status === 'success' ? 'ok' : 'error', request.endTimeUnixMs);
+            });
+            const mapped = mapDecisionResult(result);
+            const normalize = this.builder.startSpan('decision.normalize', { parent: this.root.context, links,
+                attributes: mapped.attributes, provenance: mapped.provenance });
+            this.builder.endSpan(normalize, result.spec.reason === 'invalid-output' ? 'error' : 'ok');
+            const accept = this.builder.startSpan('decision.accept', { parent: this.root.context, links,
+                attributes: mapped.attributes, provenance: mapped.provenance });
+            this.builder.endSpan(accept, result.spec.status === 'error' || result.spec.status === 'cancelled' ? 'error' : 'ok');
+        });
+    }
+    /** Close the workflow and flush. Exporter and metric failures are isolated per span. */
+    async finish(result) {
+        if (this.disabled)
+            return;
+        let spans;
+        try {
+            const failed = result.spec.status === 'error' || result.spec.status === 'cancelled';
+            const mapped = mapRulesetResult(result);
+            this.builder.annotate(this.root, mapped.attributes, mapped.provenance);
+            if (result.spec.cache?.disposition === 'cache-hit') {
+                // Historical attempts are evidence, not attempts by this caller. Emitting
+                // their provider usage again would double-count tokens and fabricate work.
+                this.builder.annotate(this.root, { 'aiwg.invocation.id': result.spec.cache.callerInvocationId,
+                    'aiwg.cache.layer': 'result', 'aiwg.cache.result': 'hit' }, { 'aiwg.invocation.id': 'client-derived',
+                    'aiwg.cache.layer': 'client-derived', 'aiwg.cache.result': 'client-derived' });
+                const hit = this.builder.startSpan('decision.cache', { parent: this.root.context,
+                    attributes: { 'aiwg.cache.layer': 'result', 'aiwg.cache.result': 'hit' },
+                    provenance: { 'aiwg.cache.layer': 'client-derived', 'aiwg.cache.result': 'client-derived' } });
+                this.builder.endSpan(hit, 'ok');
+            }
+            else {
+                this.validated(result.spec.reason === 'invalid-input' || result.spec.reason === 'invalid-definition');
+                // A span still open here never observed its outcome, e.g. an uncertain remote dispatch.
+                for (const span of this.builder.openSpans()) {
+                    if (span === this.root)
+                        continue;
+                    this.builder.annotate(span, { 'aiwg.decision.reason': result.spec.reason }, { 'aiwg.decision.reason': 'client-derived' });
+                    this.builder.endSpan(span, 'error');
+                }
+                const compose = this.builder.startSpan('decision.compose', { parent: this.root.context,
+                    attributes: mapped.attributes, provenance: mapped.provenance });
+                this.builder.endSpan(compose, failed ? 'error' : 'ok');
+                if (result.spec.status === 'review') {
+                    const review = this.builder.startSpan('decision.review', { parent: this.root.context,
+                        attributes: { 'aiwg.decision.reason': result.spec.reason }, provenance: { 'aiwg.decision.reason': 'client-derived' } });
+                    this.builder.endSpan(review, 'ok');
+                }
+                const persist = this.builder.startSpan('decision.persist', { parent: this.root.context,
+                    attributes: { 'aiwg.persistence.result': result.spec.reason === 'persistence-error' ? 'failed' : 'persisted' },
+                    provenance: { 'aiwg.persistence.result': 'client-derived' } });
+                this.builder.endSpan(persist, result.spec.reason === 'persistence-error' ? 'error' : 'ok');
+            }
+            this.builder.endSpan(this.root, failed ? 'error' : 'ok');
+            spans = this.builder.build().spans;
+        }
+        catch {
+            // Observability must never alter, reject, or mask the authoritative result.
+            return;
+        }
+        finally {
+            this.disabled = true;
+        }
+        if (this.telemetry.metrics)
+            for (const span of spans) {
+                try {
+                    recordDecisionSpanMetrics(span, this.telemetry.metrics);
+                }
+                catch { /* metrics cannot change a decision */ }
+            }
+        for (const span of spans) {
+            try {
+                await this.telemetry.hook.emit(span);
+            }
+            catch { /* isolate individual exporter failures */ }
+        }
+    }
+    open(span, ordinal) {
+        return { span, ordinal, traceContext: transportTraceContext(span.context) };
+    }
+    guard(record) {
+        if (this.disabled)
+            return undefined;
+        try {
+            return record();
+        }
+        catch {
+            this.disabled = true;
+            return undefined;
+        }
+    }
+}
+/** The live trace bound to this evaluator request, if telemetry is configured and healthy. */
+export function runtimeTraceOf(request) {
+    return request.telemetry ? TRACES.get(request.telemetry) ?? null : null;
+}
+function withoutUsage(mapping) {
+    const attributes = { ...mapping.attributes };
+    const provenance = { ...mapping.provenance };
+    for (const key of USAGE_KEYS) {
+        delete attributes[key];
+        delete provenance[key];
+    }
+    return { attributes, provenance };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/decision/telemetry/trace.js

@@ -0,0 +1,158 @@
+import { createTelemetryContext } from './context.js';
+import { sanitizeAttributes, sanitizeOpaqueValue } from './redaction.js';
+import { DECISION_TELEMETRY_SCHEMA_VERSION } from './types.js';
+export class DecisionTraceBuilder {
+    ids;
+    now;
+    spans = [];
+    batchUsage = new Set();
+    root;
+    constructor(ids, now = Date.now) {
+        this.ids = ids;
+        this.now = now;
+    }
+    startSpan(name, options = {}) {
+        const parent = options.parent ?? this.root;
+        const context = createTelemetryContext(this.ids, parent);
+        if (!this.root)
+            this.root = context;
+        const attributes = sanitizeAttributes(options.attributes ?? {});
+        const span = {
+            schemaVersion: DECISION_TELEMETRY_SCHEMA_VERSION, name, context,
+            parentSpanId: parent?.spanId ?? null,
+            startTimeUnixMs: options.startTimeUnixMs ?? this.now(), endTimeUnixMs: options.startTimeUnixMs ?? this.now(),
+            status: 'unset', attributes,
+            provenance: Object.fromEntries(Object.entries(options.provenance ?? {}).filter(([key]) => Object.hasOwn(attributes, key))),
+            links: structuredClone(options.links ?? []), events: [],
+        };
+        this.spans.push(span);
+        return span;
+    }
+    /** Merge allowlisted metadata into a recorded span; unknown or protected keys are dropped. */
+    annotate(span, attributes, provenance = {}) {
+        const safe = sanitizeAttributes(attributes);
+        Object.assign(span.attributes, safe);
+        for (const [key, value] of Object.entries(provenance))
+            if (Object.hasOwn(safe, key))
+                span.provenance[key] = value;
+    }
+    /** Spans that were started but not yet ended, in start order. */
+    openSpans() {
+        return this.spans.filter(span => span.status === 'unset');
+    }
+    endSpan(span, status = 'ok', endTimeUnixMs = this.now()) {
+        span.endTimeUnixMs = Math.max(span.startTimeUnixMs, endTimeUnixMs);
+        span.status = status;
+    }
+    /** Shared provider usage belongs to exactly one batch request span. */
+    recordBatchUsage(span, batchId, usage, provider = {}, options = {}) {
+        if (span.name !== 'decision.batch.request')
+            throw new Error('Batch usage can only be recorded on a batch request span');
+        const accountingKey = options.accountingKey ?? batchId;
+        if (this.batchUsage.has(accountingKey))
+            throw new Error(`Batch usage already recorded: ${accountingKey}`);
+        this.batchUsage.add(accountingKey);
+        span.attributes['aiwg.batch.id'] = batchId;
+        span.attributes['gen_ai.usage.input_tokens'] = usage.inputTokens;
+        span.attributes['gen_ai.usage.output_tokens'] = usage.outputTokens;
+        span.attributes['aiwg.usage.cost_usd'] = usage.costUsd;
+        span.attributes['aiwg.usage.scope'] = 'shared-request';
+        span.attributes['aiwg.provider.request_id'] = provider.requestId === null || provider.requestId === undefined
+            ? null : sanitizeOpaqueValue(provider.requestId, 128);
+        span.attributes['gen_ai.response.model'] = provider.actualModel === null || provider.actualModel === undefined
+            ? null : sanitizeOpaqueValue(provider.actualModel, 128);
+        for (const key of ['gen_ai.usage.input_tokens', 'gen_ai.usage.output_tokens']) {
+            span.provenance[key] = span.attributes[key] === null ? 'unknown' : 'provider-fact';
+        }
+        span.provenance['aiwg.usage.cost_usd'] = span.attributes['aiwg.usage.cost_usd'] === null
+            ? 'unknown' : (options.costProvenance ?? 'provider-fact');
+        span.provenance['aiwg.provider.request_id'] = provider.requestId === null || provider.requestId === undefined ? 'unknown' : 'provider-fact';
+        span.provenance['gen_ai.response.model'] = provider.actualModel === null || provider.actualModel === undefined ? 'unknown' : 'provider-fact';
+    }
+    build() {
+        if (!this.root)
+            throw new Error('Cannot build an empty decision trace');
+        return { schemaVersion: DECISION_TELEMETRY_SCHEMA_VERSION, traceId: this.root.traceId, spans: structuredClone(this.spans) };
+    }
+}
+/**
+ * Emit transport-attempt spans from the durable accounting authority. Each
+ * consumed provider attempt owns its usage exactly once, including failed
+ * retry/fallback attempts. Per-answer allocations remain off these spans.
+ *
+ * `started` holds live `decision.batch.request` spans keyed by attempt ordinal.
+ * The evaluator opens them before dispatch, so the propagated `traceparent`
+ * and the live start time belong to the span that later receives the receipt's
+ * accounting. Attempts without a live span are reconstructed from the receipt.
+ */
+export function recordBatchReceiptTrace(builder, receipt, parent, started = new Map()) {
+    const spans = [];
+    for (const attempt of receipt.attempts) {
+        const live = started.get(attempt.ordinal);
+        if (attempt.status === 'not-sent') {
+            // Nothing crossed the transport, so no usage belongs to this span.
+            if (live) {
+                builder.annotate(live, { 'aiwg.decision.status': attempt.status }, { 'aiwg.decision.status': 'client-derived' });
+                builder.endSpan(live, 'error', attempt.completedAtEpochMs ?? receipt.updatedAtEpochMs);
+            }
+            continue;
+        }
+        const cost = batchCost(attempt.cost);
+        const attributes = {
+            'aiwg.batch.id': receipt.batchId,
+            'aiwg.batch.plan_digest': receipt.plan.planDigest,
+            'aiwg.batch.partition_id': receipt.plan.partitionId,
+            'aiwg.batch.item_count': receipt.questionIds.length,
+            'aiwg.batch.result_count': receipt.answerReferences.length,
+            'aiwg.attempt.ordinal': attempt.ordinal,
+            'aiwg.adapter.id': attempt.adapterId,
+            'aiwg.adapter.version': attempt.adapterVersion,
+            'gen_ai.request.model': attempt.requestedModel,
+            'aiwg.decision.status': attempt.status,
+            'aiwg.route.fallback': attempt.fallbackFromAttemptOrdinal !== null,
+        };
+        const provenance = Object.fromEntries(Object.keys(attributes).map(key => [key, 'client-derived']));
+        const span = live ?? builder.startSpan('decision.batch.request', {
+            parent, startTimeUnixMs: attempt.dispatchedAtEpochMs ?? receipt.createdAtEpochMs,
+        });
+        builder.annotate(span, attributes, provenance);
+        builder.recordBatchUsage(span, receipt.batchId, {
+            inputTokens: attempt.usage.inputTokens,
+            outputTokens: attempt.usage.outputTokens,
+            costUsd: cost.amountUsd,
+        }, { requestId: attempt.providerRequestId, actualModel: attempt.actualModel }, {
+            accountingKey: `${receipt.batchId}:${attempt.ordinal}`,
+            costProvenance: cost.provenance,
+        });
+        builder.endSpan(span, attempt.status === 'succeeded' ? 'ok' : 'error', attempt.completedAtEpochMs ?? attempt.dispatchedAtEpochMs ?? receipt.updatedAtEpochMs);
+        spans.push(span);
+    }
+    return spans;
+}
+function batchCost(cost) {
+    switch (cost.kind) {
+        case 'provider-authoritative': return { amountUsd: cost.amountMicros / 1_000_000, provenance: 'provider-fact' };
+        case 'client-derived': return { amountUsd: cost.amountMicros / 1_000_000, provenance: 'client-derived' };
+        case 'bounded-unknown':
+        case 'unknown': return { amountUsd: null, provenance: 'unknown' };
+    }
+}
+export function estimatedUsageAllocation(total, weights, method, version) {
+    if (!Number.isSafeInteger(total) || total < 0 || weights.length === 0 || weights.some(weight => !Number.isFinite(weight) || weight < 0))
+        throw new Error('Invalid usage allocation input');
+    const sum = weights.reduce((left, right) => left + right, 0);
+    if (sum <= 0 || !method || !version)
+        throw new Error('Usage allocation requires positive weights and versioned method');
+    const raw = weights.map(weight => total * weight / sum);
+    const values = raw.map(Math.floor);
+    let remainder = total - values.reduce((left, right) => left + right, 0);
+    const order = raw.map((value, index) => ({ index, fraction: value - values[index] }))
+        .sort((left, right) => right.fraction - left.fraction || left.index - right.index);
+    for (let index = 0; index < remainder; index += 1)
+        values[order[index].index] += 1;
+    remainder = total - values.reduce((left, right) => left + right, 0);
+    if (remainder !== 0)
+        throw new Error('Usage allocation did not reconcile');
+    return values.map(value => ({ value, provenance: 'estimate', method, version }));
+}
+//# sourceMappingURL=trace.js.map

package/dist/src/decision/telemetry/types.js

@@ -0,0 +1,3 @@
+/** OpenTelemetry-compatible, dependency-free decision telemetry contract. */
+export const DECISION_TELEMETRY_SCHEMA_VERSION = 'decision-telemetry/v1';
+//# sourceMappingURL=types.js.map

package/dist/src/decision/validate.js

@@ -41,6 +41,12 @@ function getValidators() {
     if (validators)
         return validators;
     const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+    const admissionSchema = JSON.parse(readFileSync(resolve(schemaRoot(), 'DecisionAdmissionEvidence.v1.schema.json'), 'utf8'));
+    const contextEvidenceSchema = JSON.parse(readFileSync(resolve(schemaRoot(), 'DecisionContextEvidence.v1.schema.json'), 'utf8'));
+    const providerPrefixSchema = JSON.parse(readFileSync(resolve(schemaRoot(), 'DecisionProviderPrefixEvidence.v1.schema.json'), 'utf8'));
+    ajv.addSchema(admissionSchema);
+    ajv.addSchema(contextEvidenceSchema);
+    ajv.addSchema(providerPrefixSchema);
     validators = new Map();
     for (const [kind, filename] of Object.entries(schemaFiles)) {
         const schema = JSON.parse(readFileSync(resolve(schemaRoot(), filename), 'utf8'));
@@ -103,6 +109,83 @@ export function assertDecisionWriterVersion(value, semantic) {
         throw new DecisionValidationError(`${semantic} requires ${DECISION_API_VERSION_STRUCTURED}`);
     }
 }
+/**
+ * Result evidence that exists only in the v1alpha2 DecisionResult and RulesetResult
+ * schemas, with the contract addition that owns each field. v1alpha1 results never
+ * carry these fields; writers must label any result that does as v1alpha2.
+ */
+export const DECISION_RESULT_V1ALPHA2_FIELDS = [
+    { field: 'batchResult', scope: 'decision', owner: 'D07', semantic: 'batch-receipt' },
+    { field: 'batch', scope: 'attempt', owner: 'D04', semantic: 'batch-provenance' },
+    { field: 'admission', scope: 'attempt', owner: 'D05', semantic: 'admission-evidence' },
+    { field: 'context', scope: 'decision', owner: 'D06', semantic: 'context-evidence' },
+    { field: 'context', scope: 'ruleset', owner: 'D06', semantic: 'context-evidence' },
+    { field: 'contextFailure', scope: 'ruleset', owner: 'D06', semantic: 'context-evidence' },
+    { field: 'providerPrefix', scope: 'attempt', owner: 'D30', semantic: 'provider-prefix-evidence' },
+    { field: 'acceptance', scope: 'decision', owner: 'D08', semantic: 'acceptance-uncertainty' },
+    { field: 'calibrationCompatibility', scope: 'decision', owner: 'D09', semantic: 'calibration-pin' },
+    { field: 'cache', scope: 'ruleset', owner: 'D15', semantic: 'result-cache-receipt' },
+    { field: 'projection', scope: 'ruleset', owner: 'D10', semantic: 'projection-opt-out' },
+];
+/** JSON paths of every v1alpha2-only field present in a DecisionResult or RulesetResult. */
+export function decisionResultV1Alpha2Fields(value) {
+    const found = [];
+    const spec = (document) => {
+        const inner = document && typeof document === 'object' ? document.spec : undefined;
+        return inner && typeof inner === 'object' && !Array.isArray(inner) ? inner : undefined;
+    };
+    const visitDecision = (document, path) => {
+        const decision = spec(document);
+        if (!decision)
+            return;
+        for (const entry of DECISION_RESULT_V1ALPHA2_FIELDS) {
+            if (entry.scope === 'decision' && Object.hasOwn(decision, entry.field))
+                found.push(`${path}.spec.${entry.field}`);
+        }
+        if (!Array.isArray(decision.attempts))
+            return;
+        decision.attempts.forEach((attempt, index) => {
+            if (!attempt || typeof attempt !== 'object')
+                return;
+            for (const entry of DECISION_RESULT_V1ALPHA2_FIELDS) {
+                if (entry.scope === 'attempt' && Object.hasOwn(attempt, entry.field))
+                    found.push(`${path}.spec.attempts[${index}].${entry.field}`);
+            }
+        });
+    };
+    const kind = value && typeof value === 'object' ? value.kind : undefined;
+    if (kind === 'DecisionResult')
+        visitDecision(value, '$');
+    if (kind === 'RulesetResult') {
+        const ruleset = spec(value);
+        for (const entry of DECISION_RESULT_V1ALPHA2_FIELDS) {
+            if (entry.scope === 'ruleset' && ruleset && Object.hasOwn(ruleset, entry.field))
+                found.push(`$.spec.${entry.field}`);
+        }
+        const evaluations = ruleset?.evaluations;
+        if (evaluations && typeof evaluations === 'object' && !Array.isArray(evaluations)) {
+            for (const [alias, evaluation] of Object.entries(evaluations))
+                visitDecision(evaluation, `$.spec.evaluations.${alias}`);
+        }
+    }
+    return found;
+}
+/**
+ * Writer gate for every runtime DecisionResult/RulesetResult writer, including
+ * invocation receipt payloads. A result that carries v1alpha2-only evidence must be
+ * labelled v1alpha2; a v1alpha1 label on such a result is rejected before validation.
+ */
+export function assertDecisionResultWriterVersion(value) {
+    const kind = value && typeof value === 'object' ? value.kind : undefined;
+    if (kind !== 'DecisionResult' && kind !== 'RulesetResult') {
+        throw new DecisionValidationError('Result writer accepts only DecisionResult or RulesetResult documents');
+    }
+    const fields = decisionResultV1Alpha2Fields(value);
+    if (fields.length && value.apiVersion !== DECISION_API_VERSION_STRUCTURED) {
+        throw new DecisionValidationError(`${kind} carrying ${fields.join(', ')} requires ${DECISION_API_VERSION_STRUCTURED}`);
+    }
+    validateDecisionDocument(value);
+}
 /** A rollback reader may inspect v1alpha2, but cannot execute or rewrite it. */
 export function readDecisionDocumentForRollback(value, mode) {
     validateDecisionDocument(value);
@@ -121,12 +204,50 @@ function deepFreeze(value) {
         deepFreeze(child);
     Object.freeze(value);
 }
+/**
+ * Compiled caller-schema validators, keyed by the sha256 of the schema's
+ * canonical JSON, so equal content shares a validator and different content
+ * never does. Each miss compiles a detached clone in a fresh Ajv instance, so
+ * later mutation of the caller's object or another schema's `$id` cannot leak
+ * into a cached entry. Bounded LRU; failed compiles are never cached.
+ */
+const SCHEMA_CACHE_LIMIT = 256;
+const strictSchemaDigests = new Map();
+const permissiveValidators = new Map();
+function schemaDigest(schema) {
+    try {
+        return createHash('sha256').update(canonicalJson(schema)).digest('hex');
+    }
+    catch {
+        return null;
+    } // Not canonical JSON (for example an undefined member): compile uncached.
+}
+/** Only a cacheable (canonical JSON) schema needs a private copy. */
+function detached(schema, digest) {
+    return digest === null ? schema : structuredClone(schema);
+}
+function cached(cache, digest, build) {
+    if (digest !== null) {
+        const hit = cache.get(digest);
+        if (hit !== undefined) {
+            cache.delete(digest);
+            cache.set(digest, hit);
+            return hit;
+        }
+    }
+    const value = build();
+    if (digest !== null) {
+        cache.set(digest, value);
+        if (cache.size > SCHEMA_CACHE_LIMIT)
+            cache.delete(cache.keys().next().value);
+    }
+    return value;
+}
 export function validateAgainstSchema(schema, value, label) {
-    assertLocalSchema(schema, label);
-    const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+    const digest = assertLocalSchema(schema, label);
     let validate;
     try {
-        validate = ajv.compile(schema);
+        validate = cached(permissiveValidators, digest, () => new Ajv2020({ strict: false, allErrors: true, validateFormats: false }).compile(detached(schema, digest)));
     }
     catch (error) {
         throw new DecisionValidationError(`${label} is not a supported local draft 2020-12 schema: ${errorMessage(error)}`);
@@ -182,6 +303,9 @@ export function validateBinding(binding, ruleset) {
     }
     for (const [alias, evaluation] of Object.entries(binding.spec.evaluations)) {
         for (const target of evaluation.targets) {
+            if (target.acceptance.mode === 'primitive-policy' && binding.apiVersion !== DECISION_API_VERSION_STRUCTURED) {
+                throw new DecisionValidationError(`${alias} primitive-aware acceptance requires ${DECISION_API_VERSION_STRUCTURED}`);
+            }
             if (target.retry.maxDelayMs < target.retry.initialDelayMs) {
                 throw new DecisionValidationError(`${alias} retry maxDelayMs must be >= initialDelayMs`);
             }
@@ -267,13 +391,19 @@ function assertLocalSchema(schema, label) {
         stack.delete(value);
     };
     visit(schema, new Set(), 0);
+    // The structural walk above runs on every call; only the strict compile is cached.
+    const digest = schemaDigest(schema);
     try {
-        new Ajv2020({ strictSchema: true, strictTypes: false, strictTuples: false,
-            strictRequired: false, validateFormats: false }).compile(schema);
+        cached(strictSchemaDigests, digest, () => {
+            new Ajv2020({ strictSchema: true, strictTypes: false, strictTuples: false,
+                strictRequired: false, validateFormats: false }).compile(detached(schema, digest));
+            return true;
+        });
     }
     catch (error) {
         throw new DecisionValidationError(`${label} uses an unsupported schema construct: ${errorMessage(error)}`);
     }
+    return digest;
 }
 function assertPredicateAliases(predicate, aliases) {
     if ('all' in predicate)