@aiwg/cli 2026.9.19 → 2026.9.21

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

@@ -0,0 +1,164 @@
+// Free-form adapter/model/version strings require an explicit deployment allowlist.
+// Merely bounding their length does not prevent a short user ID or body canary
+// from becoming a metric label.
+const DYNAMIC_DIMENSIONS = new Set(['aiwg.adapter.id', 'aiwg.adapter.version', 'gen_ai.request.model', 'gen_ai.response.model']);
+const FIXED_DIMENSIONS = {
+    'aiwg.decision.status': ['success', 'abstained', 'error', 'unsupported', 'cancelled', 'completed', 'review', 'failed', 'succeeded', 'not-sent'],
+    'aiwg.decision.reason': ['none', 'invalid-input', 'invalid-definition', 'digest-mismatch', 'unauthorized',
+        'data-boundary-denied', 'unsupported-capability', 'executor-unavailable', 'invalid-output', 'low-confidence',
+        'missing-confidence', 'confidence-profile-mismatch', 'insufficient-information', 'timeout', 'network-transient',
+        'rate-limited', 'overloaded', 'service-error', 'authentication', 'invalid-request', 'budget-exhausted',
+        'cancelled', 'persistence-error', 'replay-mismatch', 'execution-uncertain', 'batch-record-unavailable', 'no-match', 'conflicting-outcomes', 'evaluation-failed',
+        'context-plan-stale', 'context-unqualified'],
+    'aiwg.acceptance.disposition': ['act', 'review', 'reject', 'fallback'],
+    'aiwg.batch.mode': ['native', 'single', 'emulated'],
+    // Compile-layer (D30) and result-layer (D15) cache layers share one bounded vocabulary.
+    'aiwg.cache.layer': ['definition-compilation', 'adapter-compilation', 'provider-prefix', 'invocation-replay',
+        'semantic-result', 'result'],
+    // Provider-prefix statuses, compile-cache outcomes, and every D15 result-cache event.
+    'aiwg.cache.result': ['hit', 'miss', 'stale', 'unknown', 'bypass', 'rejected', 'unsupported', 'single-flight', 'invalidation'],
+    'aiwg.cache.reason': ['verified-hit', 'cold-fill', 'cache-disabled', 'store-rejected', 'provider-report',
+        'documented-unsupported', 'policy-bypass', 'unreported'],
+    'aiwg.review.status': ['pending', 'approved', 'denied', 'escalated', 'expired'],
+    'aiwg.usage.cost_provenance': ['provider-fact', 'client-derived', 'estimate', 'unknown'],
+    'aiwg.admission.decision': ['admit', 'defer', 'reject'],
+    'aiwg.admission.reason': ['admitted', 'disabled', 'cancelled', 'deadline-exceeded', 'concurrency', 'requests-per-minute',
+        'tokens-per-second', 'attempts', 'batch-size', 'cost', 'unknown-cost', 'queue-full', 'queue-timeout', 'invalid-estimate',
+        'request-too-large', 'too-many-items', 'retained-work', 'unknown-retained-work', 'retry-after', 'circuit-open',
+        'unconfigured-provider'],
+    'aiwg.breaker.status': ['closed', 'open', 'half-open'],
+};
+/** Only fixed metric names are accepted; caller-controlled names would defeat cardinality limits. */
+const METRIC_NAMES = new Set([
+    'decision.throughput', 'decision.duration', 'decision.attempts', 'decision.retries',
+    'decision.fallbacks', 'decision.errors', 'decision.queue_delay', 'decision.coverage',
+    'decision.abstention', 'decision.review', 'decision.cost_usd',
+    'decision.input_tokens', 'decision.output_tokens', 'decision.cache', 'decision.drift',
+    'decision.cache_saved_input_tokens', 'decision.cache_saved_output_tokens',
+    'decision.cache_saved_latency_ms', 'decision.cache_saved_cost_usd',
+    'decision.admission', 'decision.throttles', 'decision.breaker_transitions',
+]);
+/** Record operational metrics without using result IDs or answer-level batch usage. */
+export function recordDecisionSpanMetrics(span, metrics) {
+    const attributes = span.attributes;
+    const record = (name, value) => { metrics.record(name, value, attributes); };
+    if (span.name === 'decision.workflow') {
+        record('decision.throughput', 1);
+        record('decision.duration', Math.max(0, span.endTimeUnixMs - span.startTimeUnixMs));
+        if (span.status === 'error')
+            record('decision.errors', 1);
+    }
+    if (span.name === 'decision.attempt' || span.name === 'decision.batch.request') {
+        record('decision.attempts', 1);
+        if (typeof attributes['aiwg.retry.delay_ms'] === 'number')
+            record('decision.retries', 1);
+        if (attributes['aiwg.route.fallback'] === true)
+            record('decision.fallbacks', 1);
+        if (span.status === 'error')
+            record('decision.errors', 1);
+        // Batch usage belongs to the request span only. Never sum linked answer spans.
+        const accounted = span.name === 'decision.batch.request'
+            ? attributes['aiwg.usage.scope'] === 'shared-request'
+            : attributes['aiwg.batch.id'] === undefined;
+        if (accounted)
+            for (const [key, name] of [
+                ['gen_ai.usage.input_tokens', 'decision.input_tokens'],
+                ['gen_ai.usage.output_tokens', 'decision.output_tokens'],
+                ['aiwg.usage.cost_usd', 'decision.cost_usd'],
+            ]) {
+                const value = attributes[key];
+                if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+                    record(name, value);
+            }
+    }
+    if (span.name === 'decision.review')
+        record('decision.review', 1);
+    // Result-layer cache events are counted once, from the D15 service sink below.
+    if (span.name === 'decision.cache' && attributes['aiwg.cache.layer'] !== 'result')
+        record('decision.cache', 1);
+    if (span.name === 'decision.admit') {
+        record('decision.admission', 1);
+        if (attributes['aiwg.admission.decision'] !== 'admit')
+            record('decision.throttles', 1);
+        const delay = attributes['aiwg.queue.delay_ms'];
+        if (typeof delay === 'number' && Number.isFinite(delay) && delay >= 0)
+            record('decision.queue_delay', delay);
+        for (const event of span.events)
+            if (event.name === 'breaker.transition')
+                record('decision.breaker_transitions', 1);
+    }
+    if (span.name === 'decision.accept') {
+        const disposition = attributes['aiwg.acceptance.disposition'];
+        if (disposition === 'act')
+            record('decision.coverage', 1);
+        if (disposition === 'reject')
+            record('decision.abstention', 1);
+    }
+    const drift = attributes['aiwg.drift.value'];
+    if (typeof drift === 'number' && Number.isFinite(drift) && drift >= 0)
+        record('decision.drift', drift);
+}
+/**
+ * Feed one D15 result-cache event into the D14 metric pipeline. Only the event name
+ * becomes a dimension; the operation ID and reason never do. Savings are recorded for
+ * hits only, labelled as estimates, and null usage or cost is skipped, never zeroed.
+ */
+export function recordResultCacheMetrics(event, metrics) {
+    const dimensions = { 'aiwg.cache.layer': 'result', 'aiwg.cache.result': event.event };
+    metrics.record('decision.cache', 1, dimensions);
+    if (event.event !== 'hit' || !event.saved)
+        return;
+    const estimated = { ...dimensions, 'aiwg.usage.cost_provenance': 'estimate' };
+    for (const [value, name] of [
+        [event.saved.inputTokens, 'decision.cache_saved_input_tokens'],
+        [event.saved.outputTokens, 'decision.cache_saved_output_tokens'],
+        [event.saved.latencyMs, 'decision.cache_saved_latency_ms'],
+        [event.saved.costUsd, 'decision.cache_saved_cost_usd'],
+    ]) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            metrics.record(name, value, estimated);
+    }
+}
+/** A `DecisionResultCache` telemetry sink that records metrics and then forwards the event. */
+export function resultCacheMetricsSink(metrics, next) {
+    return event => {
+        try {
+            recordResultCacheMetrics(event, metrics);
+        }
+        catch { /* metrics cannot change a decision */ }
+        next?.(event);
+    };
+}
+export class BoundedDecisionMetrics {
+    capacity;
+    maximumDimensionValues;
+    points = [];
+    approvedDimensions;
+    constructor(capacity = 1_000, maximumDimensionValues = 100, trustedDimensionValues = {}) {
+        this.capacity = capacity;
+        this.maximumDimensionValues = maximumDimensionValues;
+        if (!Number.isSafeInteger(capacity) || capacity < 1 || !Number.isSafeInteger(maximumDimensionValues) || maximumDimensionValues < 1
+            || Object.entries(trustedDimensionValues).some(([key, values]) => !DYNAMIC_DIMENSIONS.has(key)
+                || !Array.isArray(values) || values.length > capacity
+                || values.some(value => typeof value !== 'string' || value.length < 1 || value.length > 64))) {
+            throw new Error('Invalid metric bounds');
+        }
+        this.approvedDimensions = Object.fromEntries(Object.entries(trustedDimensionValues)
+            .map(([key, values]) => [key, [...values]]));
+    }
+    record(name, value, attributes) {
+        if (!METRIC_NAMES.has(name) || !Number.isFinite(value) || this.points.length >= this.capacity)
+            return false;
+        const dimensions = Object.fromEntries(Object.entries(attributes).filter(([key, dimension]) => typeof dimension === 'string'
+            && (FIXED_DIMENSIONS[key]?.includes(dimension) === true
+                || DYNAMIC_DIMENSIONS.has(key) && this.approvedDimensions[key]?.includes(dimension) === true)));
+        const signature = JSON.stringify(dimensions);
+        const distinct = new Set(this.points.filter(point => point.name === name).map(point => JSON.stringify(point.dimensions)));
+        if (!distinct.has(signature) && distinct.size >= this.maximumDimensionValues)
+            return false;
+        this.points.push({ name, value, dimensions });
+        return true;
+    }
+    snapshot() { return structuredClone(this.points); }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/decision/telemetry/otlp-http.js

@@ -0,0 +1,183 @@
+import { lookup } from 'node:dns/promises';
+import { request } from 'node:https';
+import { BlockList, isIP } from 'node:net';
+import { sanitizedTelemetryExport } from './redaction.js';
+/** Metadata-only OTLP/HTTP JSON sink. Credential headers and redirects are never accepted. */
+export class DecisionOtlpHttpSink {
+    endpoint;
+    maxPayloadBytes;
+    transport;
+    constructor(options) {
+        const endpoint = new URL(options.endpoint);
+        if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password || endpoint.search || endpoint.hash
+            || !endpoint.pathname.endsWith('/v1/traces'))
+            throw new TypeError('OTLP endpoint must be credential-free HTTPS /v1/traces');
+        // DNS resolution and rebinding still require a separately qualified transport.
+        // Literal and local-only names cannot be mistaken for approved public collectors.
+        const host = endpoint.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        if (isIP(host) || host === 'localhost' || host.endsWith('.localhost')) {
+            throw new TypeError('OTLP collector requires a qualified DNS hostname');
+        }
+        if (!Number.isSafeInteger(options.maxPayloadBytes) || options.maxPayloadBytes < 1)
+            throw new TypeError('Invalid OTLP payload bound');
+        this.endpoint = endpoint.href;
+        this.maxPayloadBytes = options.maxPayloadBytes;
+        // Native HTTPS connects to the validated address, not a second DNS lookup.
+        // Injected transports are for controlled tests only; they do not enforce DNS policy.
+        this.transport = options.fetch ?? pinnedHttpsFetch;
+    }
+    async export(trace, signal) {
+        const safe = sanitizedTelemetryExport(trace);
+        const payload = JSON.stringify({ resourceSpans: [{ scopeSpans: [{ scope: { name: 'aiwg.decision', version: '1' },
+                            spans: safe.spans.map(toOtlpSpan) }] }] });
+        if (Buffer.byteLength(payload, 'utf8') > this.maxPayloadBytes)
+            throw new Error('OTLP payload exceeds configured bound');
+        let response;
+        try {
+            response = await this.transport(this.endpoint, { method: 'POST', redirect: 'manual', signal,
+                headers: { 'content-type': 'application/json' }, body: payload });
+        }
+        catch {
+            // DNS, TLS and injected transport errors may contain private hostnames,
+            // paths or payloads. Diagnostics must report failure without echoing them.
+            throw new Error('OTLP transport failed');
+        }
+        if (!response.ok)
+            throw new Error(`OTLP exporter returned HTTP ${response.status}`);
+        if (!response.body)
+            return;
+        // OTLP/HTTP may acknowledge a request while rejecting some spans. Never
+        // echo collector response text; it can contain arbitrary sensitive data.
+        const reader = response.body.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 4096)
+                    throw new Error('OTLP response exceeds configured inspection bound');
+                chunks.push(value);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'OTLP response exceeds configured inspection bound')
+                throw error;
+            throw new Error('OTLP response read failed');
+        }
+        finally {
+            reader.releaseLock();
+        }
+        if (size === 0)
+            return;
+        let body;
+        try {
+            body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new Error('OTLP collector returned an invalid response');
+        }
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            throw new Error('OTLP collector returned an invalid response');
+        const partial = body.partialSuccess;
+        if (partial === undefined)
+            return;
+        if (!partial || typeof partial !== 'object' || Array.isArray(partial))
+            throw new Error('OTLP collector returned an invalid response');
+        const rejected = partial.rejectedSpans;
+        if (rejected !== undefined && rejected !== 0 && rejected !== '0') {
+            // Unknown or non-zero values cannot be treated as a complete export.
+            throw new Error('OTLP collector partially rejected spans');
+        }
+        if (partial.errorMessage)
+            throw new Error('OTLP collector reported partial success');
+    }
+}
+// Reject non-global IPv4 space, including documentation, benchmarking and multicast.
+// IPv6 is allowlisted to global unicast; mapped IPv4 and local transition ranges fail closed.
+const forbiddenV4 = new BlockList();
+for (const [address, prefix] of [
+    ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+    ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+    ['192.88.99.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15],
+    ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
+])
+    forbiddenV4.addSubnet(address, prefix);
+export function isPublicCollectorAddress(address) {
+    if (isIP(address) === 4)
+        return !forbiddenV4.check(address, 'ipv4');
+    // Exclude IPv4-mapped addresses and translation/tunneling ranges even if
+    // their embedded IPv4 address looks public.
+    if (isIP(address) === 6)
+        return /^2[0-9a-f]{3}:/i.test(address)
+            && !/^2001:(?:0:|db8:)/i.test(address) && !/^2002:/i.test(address);
+    return false;
+}
+export async function resolvePublicCollectorAddress(host, resolver = name => lookup(name, { all: true, verbatim: true })) {
+    const addresses = await resolver(host);
+    if (!addresses.length || addresses.some(({ address, family }) => isIP(address) !== family || !isPublicCollectorAddress(address))) {
+        throw new Error('OTLP collector DNS includes a non-public address');
+    }
+    return addresses[0];
+}
+function pinnedHttpsFetch(input, options) {
+    const endpoint = new URL(input instanceof Request ? input.url : input);
+    return new Promise((resolve, reject) => {
+        // Node's HTTPS request performs TLS verification against the original hostname.
+        // A fresh DNS resolution is validated for each connection; no connection pool
+        // survives to bypass this policy on subsequent exports.
+        const req = request(endpoint, {
+            method: 'POST', agent: false, headers: { 'content-type': 'application/json' },
+            lookup: (host, _opts, callback) => {
+                void resolvePublicCollectorAddress(host).then(({ address, family }) => callback(null, address, family), error => callback(error, '', 4));
+            },
+        }, response => {
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > 4096) {
+                    req.destroy(new Error('OTLP response exceeds configured inspection bound'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('end', () => resolve(new Response([204, 205, 304].includes(response.statusCode ?? 0) ? null : Buffer.concat(chunks), { status: response.statusCode ?? 502 })));
+            response.on('error', reject);
+        });
+        req.on('error', reject);
+        const signal = options?.signal;
+        if (signal?.aborted) {
+            req.destroy(signal.reason);
+            return;
+        }
+        signal?.addEventListener('abort', () => req.destroy(new Error('OTLP export aborted')), { once: true });
+        req.end(options?.body);
+    });
+}
+function toOtlpAttribute(key, value) {
+    if (typeof value === 'boolean')
+        return { key, value: { boolValue: value } };
+    if (typeof value === 'number')
+        return { key, value: Number.isSafeInteger(value)
+                ? { intValue: String(value) } : { doubleValue: value } };
+    return { key, value: { stringValue: value === null ? 'unknown' : value } };
+}
+function toOtlpSpan(span) {
+    return {
+        traceId: span.context.traceId, spanId: span.context.spanId,
+        ...(span.parentSpanId ? { parentSpanId: span.parentSpanId } : {}),
+        name: span.name,
+        startTimeUnixNano: String(Math.trunc(span.startTimeUnixMs * 1_000_000)),
+        endTimeUnixNano: String(Math.trunc(span.endTimeUnixMs * 1_000_000)),
+        attributes: Object.entries(span.attributes).map(([key, value]) => toOtlpAttribute(key, value)),
+        links: span.links.map(link => ({ traceId: link.traceId, spanId: link.spanId,
+            attributes: Object.entries(link.attributes ?? {}).map(([key, value]) => toOtlpAttribute(key, value)) })),
+        events: span.events.map(event => ({ name: event.name, timeUnixNano: String(Math.trunc(event.timeUnixMs * 1_000_000)),
+            attributes: Object.entries(event.attributes).map(([key, value]) => toOtlpAttribute(key, value)) })),
+        status: { code: span.status === 'error' ? 2 : span.status === 'ok' ? 1 : 0 },
+    };
+}
+//# sourceMappingURL=otlp-http.js.map

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

@@ -0,0 +1,93 @@
+const PROTECTED_KEY = /(?:state|question|prompt|response|answer(?:\.body)?|authorization|api[_-]?key|credential|vault|secret|reasoning|cookie|token(?!s?$))/i;
+const CONTROL = /[\u0000-\u001f\u007f]/g;
+const SAFE_EVENT_NAMES = new Set(['retry.scheduled', 'attempt.terminated', 'breaker.transition']);
+// Only schema-declared metadata may cross the telemetry boundary. A syntactically
+// plausible custom key can still carry body text or PII in its value.
+const SAFE_ATTRIBUTE_KEYS = new Set(`
+  aiwg.run.id aiwg.invocation.id aiwg.workflow.status aiwg.evaluation.count
+  aiwg.decision.id aiwg.decision.version aiwg.decision.alias aiwg.decision.status aiwg.decision.reason
+  aiwg.ruleset.id aiwg.ruleset.version aiwg.binding.id aiwg.binding.version
+  aiwg.adapter.id aiwg.adapter.version aiwg.attempt.ordinal aiwg.attempt.count
+  aiwg.attempt.duration_ms aiwg.attempt.termination aiwg.retry.delay_ms
+  aiwg.acceptance.policy_version aiwg.acceptance.disposition aiwg.acceptance.reason
+  aiwg.calibration.compatibility_state aiwg.calibration.compatibility_action
+  aiwg.calibration.artifact_id aiwg.calibration.artifact_digest aiwg.calibration.alias_revision
+  aiwg.calibration.reason_count aiwg.route.reason aiwg.route.fallback aiwg.primitive.count
+  aiwg.validation.outcome aiwg.persistence.result aiwg.cache.source aiwg.cache.layer
+  aiwg.cache.result aiwg.cache.version aiwg.cache.saved_tokens aiwg.cache.expires_at_ms
+  aiwg.cache.reason aiwg.cache.preparation_ms aiwg.cache.invalidation_reason
+  aiwg.batch.id aiwg.batch.mode aiwg.batch.plan_digest aiwg.batch.partition_id
+  aiwg.batch.item_count aiwg.batch.result_count aiwg.job.id
+  aiwg.job.operation aiwg.job.status aiwg.job.revision aiwg.job.item_count aiwg.job.unknown_count
+  aiwg.review.id aiwg.operator_decision.event_id
+  aiwg.review.status aiwg.review.event aiwg.review.revision aiwg.effect_receipt.id
+  aiwg.provider.request_id aiwg.provider.request_id_source aiwg.remote.execution
+  aiwg.usage.cost_usd aiwg.usage.cost_provenance aiwg.usage.scope aiwg.link.state
+  aiwg.link.tombstone aiwg.queue.delay_ms aiwg.drift.value
+  aiwg.admission.decision aiwg.admission.reason aiwg.admission.estimated_tokens aiwg.admission.estimated_cost_usd
+  aiwg.admission.retry_after_ms aiwg.queue.active aiwg.queue.queued aiwg.retry.pressure
+  aiwg.breaker.status aiwg.breaker.from aiwg.breaker.to
+  aiwg.projection.mode aiwg.projection.outcome aiwg.projection.reason aiwg.projection.field_count
+  aiwg.projection.incomplete_context aiwg.projection.automatic_action_allowed
+  gen_ai.request.model gen_ai.response.model gen_ai.usage.input_tokens
+  gen_ai.usage.output_tokens http.response.status_code
+`.trim().split(/\s+/));
+for (const prefix of ['aiwg.definition', 'aiwg.policy', 'aiwg.calibration']) {
+    for (const suffix of ['id', 'version', 'digest'])
+        SAFE_ATTRIBUTE_KEYS.add(`${prefix}.${suffix}`);
+}
+// Declared keys whose names match PROTECTED_KEY but carry only fixed metadata.
+// `aiwg.link.state` is the deletion tombstone marker; dropping it would turn an
+// explicit tombstone into an unexplained link in exports.
+const PROTECTED_KEY_EXEMPTIONS = new Set(['gen_ai.response.model', 'http.response.status_code', 'aiwg.link.state']);
+export const DEFAULT_ATTRIBUTE_VALUE_LIMIT = 256;
+export function sanitizeOpaqueValue(value, maximum = DEFAULT_ATTRIBUTE_VALUE_LIMIT) {
+    return value.replace(CONTROL, '').slice(0, maximum);
+}
+export function sanitizeAttributes(attributes, options = {}) {
+    const output = {};
+    for (const [key, original] of Object.entries(attributes)) {
+        if (!SAFE_ATTRIBUTE_KEYS.has(key)
+            || (PROTECTED_KEY.test(key) && !PROTECTED_KEY_EXEMPTIONS.has(key))
+            || (options.publicExport && key === 'aiwg.provider.request_id')
+            || options.canaries?.some(canary => canary && key.toLowerCase().includes(canary.toLowerCase())))
+            continue;
+        let value = original;
+        if (typeof value === 'string') {
+            const lowered = value.toLowerCase();
+            if (options.canaries?.some(canary => canary.length > 0 && lowered.includes(canary.toLowerCase())))
+                continue;
+            value = sanitizeOpaqueValue(value, options.maximumValueLength);
+        }
+        output[key] = value;
+    }
+    return output;
+}
+export function sanitizedTelemetryExport(trace, options = {}) {
+    const spans = trace.spans.map(span => {
+        const attributes = sanitizeAttributes(span.attributes, { publicExport: !options.includeInternalRequestIds, canaries: options.canaries });
+        return {
+            ...span, attributes,
+            // Tracestate is a vendor-defined free-form string, not needed for export;
+            // do not copy it into a disclosure even if a caller supplied one.
+            context: { traceId: span.context.traceId, spanId: span.context.spanId, traceFlags: span.context.traceFlags },
+            provenance: Object.fromEntries(Object.entries(span.provenance).filter(([key]) => Object.hasOwn(attributes, key))),
+            events: span.events.filter(event => SAFE_EVENT_NAMES.has(event.name)).map(event => ({ ...event,
+                attributes: sanitizeAttributes(event.attributes, { publicExport: true, canaries: options.canaries }) })),
+            links: span.links.map(link => ({ ...link, ...(link.attributes ? { attributes: sanitizeAttributes(link.attributes, { publicExport: true, canaries: options.canaries }) } : {}) })),
+        };
+    });
+    const tombstones = trace.tombstones?.map(tombstone => ({
+        ...tombstone,
+        opaqueId: options.canaries?.some(canary => canary && tombstone.opaqueId.toLowerCase().includes(canary.toLowerCase()))
+            ? 'redacted' : sanitizeOpaqueValue(tombstone.opaqueId),
+        reason: options.canaries?.some(canary => canary && tombstone.reason.toLowerCase().includes(canary.toLowerCase()))
+            ? 'redacted' : sanitizeOpaqueValue(tombstone.reason),
+    }));
+    return { ...trace, spans, ...(tombstones ? { tombstones } : {}) };
+}
+export function scanTelemetryCanaries(value, canaries) {
+    const serialized = JSON.stringify(value).toLowerCase();
+    return canaries.filter(canary => canary.length > 0 && serialized.includes(canary.toLowerCase()));
+}
+//# sourceMappingURL=redaction.js.map

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

@@ -0,0 +1,109 @@
+import { DECISION_LIFECYCLE_VERSION, validateDecisionLifecyclePolicy } from '../lifecycle.js';
+export function validateDebugCapturePolicy(policy) {
+    if (!policy)
+        return null;
+    if (!policy.explicitlyAuthorized || !policy.encryption.enabled || !policy.encryption.keyReference
+        || !policy.accessAudit.enabled || !policy.accessAudit.sinkReference || !policy.deletionEnabled
+        || !Number.isSafeInteger(policy.ttlMs) || policy.ttlMs <= 0
+        || !['confidential', 'restricted'].includes(policy.classification)
+        || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(policy.encryption.keyReference)
+        || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(policy.accessAudit.sinkReference))
+        throw new Error('Sensitive debug capture policy is incomplete');
+    return structuredClone(policy);
+}
+/** Lifecycle surfaces whose content telemetry retains or links to. */
+export const TELEMETRY_LIFECYCLE_SURFACES = [
+    'trace', 'debug-sidecar', 'export', 'review', 'job', 'cache', 'evaluation',
+];
+/**
+ * Derive telemetry retention from the common `decision-lifecycle/v1` policy (M09).
+ * TTLs come from the lifecycle surfaces; linked records use the shortest linked-surface TTL.
+ * Legal hold is true only while an authorized lifecycle hold for a telemetry surface is active.
+ */
+export function telemetryRetentionFromLifecyclePolicy(policy, holds = [], now = Date.now()) {
+    validateDecisionLifecyclePolicy(policy);
+    if (!Number.isSafeInteger(now) || now < 0 || !Array.isArray(holds))
+        throw new Error('Invalid telemetry retention policy');
+    const surfaces = policy.surfaces;
+    const legalHold = holds.some(hold => Number.isSafeInteger(hold?.expiresAt) && hold.expiresAt > now
+        && Array.isArray(hold.scope) && hold.scope.some(surface => TELEMETRY_LIFECYCLE_SURFACES.includes(surface)));
+    const retention = {
+        traceTtlMs: surfaces.trace.retentionMs,
+        debugSidecarTtlMs: surfaces['debug-sidecar'].retentionMs,
+        exportTtlMs: surfaces.export.retentionMs,
+        linkedRecordTtlMs: Math.min(surfaces.review.retentionMs, surfaces.job.retentionMs, surfaces.cache.retentionMs, surfaces.evaluation.retentionMs),
+        deletionEnabled: true,
+        tombstonesEnabled: true,
+        legalHold,
+        lifecycleVersion: DECISION_LIFECYCLE_VERSION,
+    };
+    validateRetentionPolicy(retention);
+    return retention;
+}
+export function validateRetentionPolicy(policy) {
+    const ttls = [policy.traceTtlMs, policy.debugSidecarTtlMs, policy.exportTtlMs, policy.linkedRecordTtlMs];
+    if (ttls.some(ttl => !Number.isSafeInteger(ttl) || ttl <= 0) || !policy.deletionEnabled || !policy.tombstonesEnabled)
+        throw new Error('Invalid telemetry retention policy');
+}
+export function deleteTelemetryReference(trace, referenceType, opaqueId, reason, policy, now = Date.now()) {
+    validateRetentionPolicy(policy);
+    if (policy.legalHold)
+        throw new Error('Telemetry deletion prohibited by legal hold');
+    if (!opaqueId || !reason)
+        throw new Error('Deletion requires an opaque reference and reason');
+    const tombstone = { referenceType, opaqueId, deletedAtUnixMs: now, reason: reason.slice(0, 128) };
+    const spans = trace.spans.map(span => ({
+        ...span,
+        links: span.links.map(link => link.attributes && Object.values(link.attributes).includes(opaqueId)
+            ? { ...link, attributes: { 'aiwg.link.state': 'deleted', 'aiwg.link.tombstone': opaqueId } }
+            : link),
+    }));
+    return { ...trace, spans, tombstones: [...(trace.tombstones ?? []), tombstone] };
+}
+/** Reapply trace TTL after backup/restore before making restored content queryable. */
+export function restoreTelemetryTrace(trace, policy, now = Date.now()) {
+    validateRetentionPolicy(policy);
+    if (policy.legalHold || trace.spans.length === 0)
+        return structuredClone(trace);
+    const createdAt = Math.min(...trace.spans.map(span => span.startTimeUnixMs));
+    if (now - createdAt <= policy.traceTtlMs)
+        return structuredClone(trace);
+    return {
+        schemaVersion: trace.schemaVersion,
+        traceId: trace.traceId,
+        spans: [],
+        tombstones: [...(trace.tombstones ?? []), {
+                referenceType: 'trace', opaqueId: trace.traceId, deletedAtUnixMs: now, reason: 'expired during restore',
+            }],
+    };
+}
+const ORPHAN_REFERENCE = {
+    review: 'review', job: 'job', cache: 'cache', evaluation: 'evaluation',
+};
+/**
+ * Tombstone links whose target span can no longer be resolved, for example after
+ * the linked trace expired, was deleted, or was never exported. An orphan becomes
+ * an explicit `orphaned` link state plus a tombstone, never a dangling reference
+ * that a later record could silently reuse. Targets inside the same trace resolve
+ * locally; `resolves` answers for every other target.
+ */
+export function tombstoneOrphanedLinks(trace, resolves, now = Date.now()) {
+    const local = new Set(trace.spans.map(span => `${span.context.traceId}:${span.context.spanId}`));
+    const tombstones = structuredClone(trace.tombstones ?? []);
+    const spans = structuredClone(trace.spans).map(span => ({
+        ...span,
+        links: span.links.map(link => {
+            const state = link.attributes?.['aiwg.link.state'];
+            const opaqueId = `${link.traceId}:${link.spanId}`;
+            if (state === 'deleted' || state === 'orphaned' || local.has(opaqueId) || resolves(link))
+                return link;
+            if (!tombstones.some(tombstone => tombstone.opaqueId === opaqueId)) {
+                tombstones.push({ referenceType: ORPHAN_REFERENCE[link.relationship] ?? 'trace', opaqueId,
+                    deletedAtUnixMs: now, reason: 'orphaned link' });
+            }
+            return { ...link, attributes: { 'aiwg.link.state': 'orphaned', 'aiwg.link.tombstone': opaqueId } };
+        }),
+    }));
+    return { ...trace, spans, tombstones };
+}
+//# sourceMappingURL=retention.js.map