@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/decision/telemetry/debug-sidecar.js

@@ -0,0 +1,152 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'node:crypto';
+import { validateDebugCapturePolicy } from './retention.js';
+import { validateDecisionLifecyclePolicy } from '../lifecycle.js';
+/** Opaque reference and ciphertext only; never serialize plaintext into a receipt or audit event. */
+export class DecisionDebugSidecar {
+    policy;
+    backend;
+    resolveKey;
+    authorize;
+    clock;
+    constructor(policy, backend, resolveKey, authorize, lifecycle, clock = Date.now) {
+        this.policy = policy;
+        this.backend = backend;
+        this.resolveKey = resolveKey;
+        this.authorize = authorize;
+        this.clock = clock;
+        if (!validateDebugCapturePolicy(policy))
+            throw new Error('Debug capture authorization required');
+        validateDecisionLifecyclePolicy(lifecycle);
+        const rule = lifecycle.surfaces['debug-sidecar'];
+        if (rule.classification !== policy.classification || rule.retentionMs !== policy.ttlMs
+            || rule.deletion !== 'erase' || rule.export !== 'denied') {
+            throw new Error('Debug capture lifecycle policy mismatch');
+        }
+    }
+    async capture(scope, plaintext) {
+        if (!scope || !await this.authorize(scope, 'capture'))
+            throw new Error('Debug capture denied');
+        const now = this.clock();
+        if (!Number.isSafeInteger(now) || now < 0 || !Number.isSafeInteger(now + this.policy.ttlMs))
+            throw new Error('Debug capture clock invalid');
+        const id = randomUUID();
+        const nonce = randomBytes(12);
+        const key = await this.key();
+        let ciphertext;
+        let tag;
+        try {
+            const cipher = createCipheriv('aes-256-gcm', key, nonce);
+            cipher.setAAD(Buffer.from(`${id}:${scope}:${now + this.policy.ttlMs}`));
+            ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+            tag = cipher.getAuthTag();
+        }
+        finally {
+            key.fill(0);
+        }
+        // Audit must succeed before content is persisted. An audit failure never opens capture.
+        await this.audit('capture', id, scope);
+        try {
+            await this.backend.put({ id, scope, expiresAt: now + this.policy.ttlMs, nonce, ciphertext, tag });
+        }
+        catch {
+            throw new Error('Debug sidecar storage failed');
+        }
+        return id;
+    }
+    async read(scope, id) {
+        if (!scope || !await this.authorize(scope, 'read'))
+            throw new Error('Debug read denied');
+        const record = await this.get(id);
+        if (!record || record.scope !== scope)
+            return null;
+        if (this.clock() >= record.expiresAt) {
+            await this.audit('expire', id, scope);
+            await this.erase(id);
+            return null;
+        }
+        await this.audit('read', id, scope);
+        const key = await this.key();
+        try {
+            const decipher = createDecipheriv('aes-256-gcm', key, record.nonce);
+            decipher.setAAD(Buffer.from(`${id}:${scope}:${record.expiresAt}`));
+            decipher.setAuthTag(record.tag);
+            return Buffer.concat([decipher.update(record.ciphertext), decipher.final()]);
+        }
+        catch {
+            throw new Error('Debug sidecar integrity check failed');
+        }
+        finally {
+            key.fill(0);
+        }
+    }
+    async delete(scope, id) {
+        if (!scope || !await this.authorize(scope, 'delete'))
+            throw new Error('Debug deletion denied');
+        const record = await this.get(id);
+        if (!record || record.scope !== scope)
+            return;
+        await this.audit('delete', id, scope);
+        await this.erase(id);
+    }
+    /** Evict expired ciphertext even when nobody reads it. The backend must return
+     * only scoped records; each candidate is checked again before erasure. */
+    async sweepExpired(scope) {
+        if (!scope || !await this.authorize(scope, 'delete'))
+            throw new Error('Debug expiry sweep denied');
+        const now = this.clock();
+        let records;
+        try {
+            records = await this.backend.listExpired(scope, now);
+        }
+        catch {
+            throw new Error('Debug sidecar storage failed');
+        }
+        let deleted = 0;
+        for (const candidate of records) {
+            const record = await this.get(candidate.id);
+            if (!record || record.scope !== scope || now < record.expiresAt)
+                continue;
+            await this.audit('expire', record.id, scope);
+            await this.erase(record.id);
+            deleted++;
+        }
+        return deleted;
+    }
+    async get(id) {
+        try {
+            return await this.backend.get(id);
+        }
+        catch {
+            throw new Error('Debug sidecar storage failed');
+        }
+    }
+    async erase(id) {
+        try {
+            await this.backend.delete(id);
+        }
+        catch {
+            throw new Error('Debug sidecar deletion failed');
+        }
+    }
+    async audit(operation, id, scope) {
+        try {
+            await this.backend.audit({ operation, id, scope });
+        }
+        catch {
+            throw new Error('Debug access audit failed');
+        }
+    }
+    async key() {
+        let resolved;
+        try {
+            resolved = await this.resolveKey(this.policy.encryption.keyReference);
+        }
+        catch {
+            throw new Error('Debug encryption key unavailable');
+        }
+        if (resolved.length !== 32)
+            throw new Error('Debug encryption key invalid');
+        return Buffer.from(resolved);
+    }
+}
+//# sourceMappingURL=debug-sidecar.js.map

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

@@ -0,0 +1,77 @@
+import { sanitizedTelemetryExport } from './redaction.js';
+export class BoundedDecisionTraceExporter {
+    sink;
+    options;
+    queue = [];
+    draining = null;
+    stopped = false;
+    diagnostics = [];
+    constructor(sink, options) {
+        this.sink = sink;
+        this.options = options;
+        if (!Number.isSafeInteger(options.capacity) || options.capacity < 1 || !Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1
+            || !Number.isSafeInteger(options.maximumTraceBytes ?? 65_536) || (options.maximumTraceBytes ?? 65_536) < 1
+            || !Number.isSafeInteger(options.maximumDiagnostics ?? 100) || (options.maximumDiagnostics ?? 100) < 1) {
+            throw new Error('Invalid exporter bounds');
+        }
+    }
+    /** Never awaits the sink and never changes a decision result. */
+    offer(trace) {
+        if (this.stopped || this.queue.length >= this.options.capacity) {
+            this.record('dropped', this.stopped ? 'exporter stopped' : 'queue capacity reached');
+            return false;
+        }
+        try {
+            const sanitized = sanitizedTelemetryExport(trace, { canaries: this.options.canaries });
+            const encoded = JSON.stringify(sanitized);
+            if (Buffer.byteLength(encoded, 'utf8') > (this.options.maximumTraceBytes ?? 65_536)) {
+                this.record('dropped', 'trace exceeds configured byte bound');
+                return false;
+            }
+            this.queue.push(sanitized);
+            this.drain();
+            return true;
+        }
+        catch {
+            this.record('dropped', 'invalid telemetry trace');
+            return false;
+        }
+    }
+    async shutdown() {
+        this.stopped = true;
+        await (this.drain() ?? this.draining);
+    }
+    record(type, detail) {
+        const containsCanary = this.options.canaries?.some(canary => canary && detail.toLowerCase().includes(canary.toLowerCase()));
+        this.diagnostics.push({ type, atUnixMs: Date.now(), detail: containsCanary ? 'redacted exporter diagnostic' : detail.slice(0, 256) });
+        const maximum = this.options.maximumDiagnostics ?? 100;
+        if (this.diagnostics.length > maximum)
+            this.diagnostics.splice(0, this.diagnostics.length - maximum);
+    }
+    drain() {
+        if (this.draining)
+            return null;
+        this.draining = (async () => {
+            while (this.queue.length > 0) {
+                const trace = this.queue.shift();
+                const controller = new AbortController();
+                let timeout;
+                const deadline = new Promise((_, reject) => {
+                    timeout = setTimeout(() => { controller.abort(); reject(new Error('telemetry export timed out')); }, this.options.timeoutMs);
+                });
+                try {
+                    await Promise.race([this.sink.export(trace, controller.signal), deadline]);
+                }
+                catch (error) {
+                    this.record(controller.signal.aborted ? 'timeout' : 'failed', error instanceof Error ? error.message : 'export failed');
+                }
+                finally {
+                    if (timeout)
+                        clearTimeout(timeout);
+                }
+            }
+        })().finally(() => { this.draining = null; });
+        return this.draining;
+    }
+}
+//# sourceMappingURL=exporter.js.map

package/dist/src/decision/telemetry/file-debug-backend.js

@@ -0,0 +1,112 @@
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SCOPE = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/** Local encrypted-content backend. The caller supplies key resolution and authorization separately. */
+export class FileDebugSidecarBackend {
+    root;
+    constructor(root) {
+        this.root = root;
+        if (!root)
+            throw new Error('Debug storage root required');
+    }
+    path(id) {
+        if (!ID.test(id))
+            throw new Error('Debug reference invalid');
+        return join(this.root, `${id}.json`);
+    }
+    async prepare() {
+        await mkdir(this.root, { recursive: true, mode: 0o700 });
+        const stat = await lstat(this.root);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+            throw new Error('Debug storage root must be a private directory');
+        }
+    }
+    async put(record) {
+        const target = this.path(record.id);
+        if (!SCOPE.test(record.scope))
+            throw new Error('Debug scope invalid');
+        await this.prepare();
+        const temp = join(this.root, `${randomUUID()}.tmp`);
+        const serialized = JSON.stringify({ id: record.id, scope: record.scope, expiresAt: record.expiresAt,
+            nonce: record.nonce.toString('base64'), tag: record.tag.toString('base64'), ciphertext: record.ciphertext.toString('base64') });
+        try {
+            const fd = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                await fd.writeFile(serialized);
+                await fd.sync();
+            }
+            finally {
+                await fd.close();
+            }
+            // Atomic create without replacing a previous reference or following a symlink.
+            await link(temp, target);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    async get(id) {
+        const target = this.path(id);
+        let fd;
+        try {
+            fd = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new Error('Debug content unavailable');
+        }
+        try {
+            const value = JSON.parse(await fd.readFile({ encoding: 'utf8' }));
+            if (value.id !== id || typeof value.scope !== 'string' || !SCOPE.test(value.scope)
+                || !Number.isSafeInteger(value.expiresAt) || typeof value.nonce !== 'string'
+                || typeof value.tag !== 'string' || typeof value.ciphertext !== 'string')
+                throw new Error();
+            return { id, scope: value.scope, expiresAt: value.expiresAt,
+                nonce: Buffer.from(value.nonce, 'base64'), tag: Buffer.from(value.tag, 'base64'),
+                ciphertext: Buffer.from(value.ciphertext, 'base64') };
+        }
+        catch {
+            throw new Error('Debug content invalid');
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    async delete(id) {
+        await rm(this.path(id), { force: true });
+    }
+    async listExpired(scope, before) {
+        if (!SCOPE.test(scope) || !Number.isSafeInteger(before))
+            throw new Error('Debug expiry query invalid');
+        await this.prepare();
+        const records = [];
+        for (const name of await readdir(this.root)) {
+            if (!name.endsWith('.json') || !ID.test(name.slice(0, -5)))
+                continue;
+            const record = await this.get(name.slice(0, -5));
+            if (record?.scope === scope && record.expiresAt <= before)
+                records.push(record);
+        }
+        return records;
+    }
+    async audit(event) {
+        this.path(event.id);
+        if (!SCOPE.test(event.scope) || !['capture', 'read', 'delete', 'expire'].includes(event.operation)) {
+            throw new Error('Debug audit event invalid');
+        }
+        await this.prepare();
+        const fd = await open(join(this.root, 'audit.jsonl'), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+        try {
+            await fd.writeFile(`${JSON.stringify(event)}\n`);
+            await fd.sync();
+        }
+        finally {
+            await fd.close();
+        }
+    }
+}
+//# sourceMappingURL=file-debug-backend.js.map

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

@@ -0,0 +1,13 @@
+export * from './context.js';
+export * from './debug-sidecar.js';
+export * from './file-debug-backend.js';
+export * from './exporter.js';
+export * from './otlp-http.js';
+export * from './mapping.js';
+export * from './metrics.js';
+export * from './redaction.js';
+export * from './retention.js';
+export * from './runtime.js';
+export * from './trace.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,146 @@
+import { sanitizeOpaqueValue } from './redaction.js';
+function put(target, key, value, provenance) {
+    target.attributes[key] = value;
+    target.provenance[key] = value === null ? 'unknown' : provenance;
+}
+export function mapDecisionAttempt(attempt) {
+    const out = { attributes: {}, provenance: {} };
+    put(out, 'aiwg.attempt.ordinal', attempt.ordinal, 'client-derived');
+    put(out, 'aiwg.adapter.id', attempt.adapter, 'client-derived');
+    put(out, 'aiwg.adapter.version', attempt.adapterVersion, 'client-derived');
+    put(out, 'gen_ai.request.model', attempt.requestedModel, 'client-derived');
+    put(out, 'gen_ai.response.model', attempt.actualModel, 'provider-fact');
+    put(out, 'aiwg.decision.status', attempt.status, 'client-derived');
+    put(out, 'aiwg.decision.reason', attempt.reason, 'client-derived');
+    put(out, 'aiwg.attempt.duration_ms', attempt.durationMs, 'client-derived');
+    put(out, 'gen_ai.usage.input_tokens', attempt.usage.inputTokens, 'provider-fact');
+    put(out, 'gen_ai.usage.output_tokens', attempt.usage.outputTokens, 'provider-fact');
+    put(out, 'aiwg.usage.cost_usd', attempt.usage.costUsd, 'provider-fact');
+    put(out, 'aiwg.usage.cost_provenance', attempt.usage.costUsd === null ? 'unknown' : 'provider-fact', 'client-derived');
+    put(out, 'aiwg.provider.request_id', attempt.requestId === null ? null : sanitizeOpaqueValue(attempt.requestId, 128), 'provider-fact');
+    if (attempt.requestIdSource)
+        put(out, 'aiwg.provider.request_id_source', attempt.requestIdSource, 'client-derived');
+    if (attempt.httpStatus !== undefined)
+        put(out, 'http.response.status_code', attempt.httpStatus, 'provider-fact');
+    if (attempt.retryDelayMs !== undefined)
+        put(out, 'aiwg.retry.delay_ms', attempt.retryDelayMs, 'client-derived');
+    if (attempt.termination)
+        put(out, 'aiwg.attempt.termination', attempt.termination, 'client-derived');
+    if (attempt.remoteExecution)
+        put(out, 'aiwg.remote.execution', attempt.remoteExecution, 'unknown');
+    if (attempt.batch) {
+        put(out, 'aiwg.batch.id', attempt.batch.groupId, 'client-derived');
+        put(out, 'aiwg.batch.mode', attempt.batch.mode, 'client-derived');
+    }
+    if (attempt.providerPrefix) {
+        put(out, 'aiwg.cache.layer', 'provider-prefix', 'client-derived');
+        put(out, 'aiwg.cache.result', attempt.providerPrefix.status, 'provider-fact');
+        put(out, 'aiwg.cache.source', attempt.providerPrefix.source, 'client-derived');
+        put(out, 'aiwg.cache.version', attempt.providerPrefix.cacheVersion === null
+            ? null : sanitizeOpaqueValue(attempt.providerPrefix.cacheVersion, 64), 'provider-fact');
+        put(out, 'aiwg.cache.saved_tokens', attempt.providerPrefix.savedInputTokens, 'provider-fact');
+        put(out, 'aiwg.cache.expires_at_ms', attempt.providerPrefix.expiresAtEpochMs, 'provider-fact');
+    }
+    return out;
+}
+/**
+ * Maps any cache layer's metadata-only record. Every value is a fixed enum,
+ * a number or a bounded version string; keys, aliases and identities never appear.
+ */
+export function mapCacheTelemetry(telemetry) {
+    const out = { attributes: {}, provenance: {} };
+    const reported = telemetry.layer === 'provider-prefix' && telemetry.reason === 'provider-report';
+    put(out, 'aiwg.cache.layer', telemetry.layer, 'client-derived');
+    put(out, 'aiwg.cache.result', telemetry.outcome, reported ? 'provider-fact' : 'client-derived');
+    put(out, 'aiwg.cache.reason', telemetry.reason, 'client-derived');
+    put(out, 'aiwg.cache.version', telemetry.version === null ? null : sanitizeOpaqueValue(telemetry.version, 64), reported ? 'provider-fact' : 'client-derived');
+    put(out, 'aiwg.cache.saved_tokens', telemetry.savedTokens, 'provider-fact');
+    put(out, 'aiwg.cache.preparation_ms', telemetry.preparationLatencyMs, 'client-derived');
+    put(out, 'aiwg.cache.expires_at_ms', telemetry.expiresAtEpochMs, reported ? 'provider-fact' : 'client-derived');
+    put(out, 'aiwg.cache.invalidation_reason', telemetry.invalidationReason, 'client-derived');
+    return out;
+}
+/** Admission evidence is metadata-only by contract; no principal or workspace ID reaches a span. */
+export function mapAdmissionEvidence(evidence) {
+    const out = { attributes: {}, provenance: {} };
+    put(out, 'aiwg.admission.decision', evidence.decision, 'client-derived');
+    put(out, 'aiwg.admission.reason', evidence.reason, 'client-derived');
+    put(out, 'aiwg.queue.delay_ms', evidence.queueDelayMs, 'client-derived');
+    put(out, 'aiwg.queue.active', evidence.active, 'client-derived');
+    put(out, 'aiwg.queue.queued', evidence.queued, 'client-derived');
+    put(out, 'aiwg.admission.estimated_tokens', evidence.estimatedTokens, 'estimate');
+    put(out, 'aiwg.admission.estimated_cost_usd', evidence.estimatedCostUsd, 'estimate');
+    put(out, 'aiwg.retry.pressure', evidence.retryPressure, 'client-derived');
+    put(out, 'aiwg.breaker.status', evidence.breakerState, 'client-derived');
+    if (evidence.retryAfterMs !== undefined)
+        put(out, 'aiwg.admission.retry_after_ms', evidence.retryAfterMs, 'client-derived');
+    return out;
+}
+/** Maps lifecycle-only metadata not present on DecisionResult without opening a body. */
+export function mapDecisionLifecycle(metadata) {
+    const out = { attributes: {}, provenance: {} };
+    const pin = (prefix, value) => {
+        put(out, `${prefix}.id`, value?.id ?? null, 'client-derived');
+        put(out, `${prefix}.version`, value?.version ?? null, 'client-derived');
+        put(out, `${prefix}.digest`, value?.digest ?? null, 'client-derived');
+    };
+    pin('aiwg.definition', metadata.definitionPin);
+    pin('aiwg.policy', metadata.policyPin);
+    pin('aiwg.calibration', metadata.calibrationPin);
+    put(out, 'aiwg.route.reason', metadata.routeReason ?? null, 'client-derived');
+    put(out, 'aiwg.route.fallback', metadata.fallback ?? false, 'client-derived');
+    put(out, 'aiwg.primitive.count', metadata.primitiveCount ?? null, 'client-derived');
+    put(out, 'aiwg.validation.outcome', metadata.validationOutcome ?? 'unknown', 'client-derived');
+    put(out, 'aiwg.persistence.result', metadata.persistenceResult ?? 'unknown', 'client-derived');
+    put(out, 'aiwg.cache.source', metadata.cacheSource ?? null, 'client-derived');
+    for (const [key, value] of Object.entries({
+        'aiwg.batch.id': metadata.batchId, 'aiwg.job.id': metadata.jobId, 'aiwg.review.id': metadata.reviewId,
+        'aiwg.effect_receipt.id': metadata.effectReceiptId,
+    }))
+        put(out, key, value ?? null, 'client-derived');
+    return out;
+}
+export function mapDecisionResult(result) {
+    const out = { attributes: {}, provenance: {} };
+    put(out, 'aiwg.run.id', result.spec.runId, 'client-derived');
+    put(out, 'aiwg.invocation.id', result.spec.invocationId, 'client-derived');
+    put(out, 'aiwg.decision.id', result.spec.decision.id, 'client-derived');
+    put(out, 'aiwg.decision.version', result.spec.decision.version, 'client-derived');
+    put(out, 'aiwg.ruleset.id', result.spec.ruleset.id, 'client-derived');
+    put(out, 'aiwg.ruleset.version', result.spec.ruleset.version, 'client-derived');
+    put(out, 'aiwg.binding.id', result.spec.binding.id, 'client-derived');
+    put(out, 'aiwg.binding.version', result.spec.binding.version, 'client-derived');
+    put(out, 'aiwg.decision.alias', result.spec.alias, 'client-derived');
+    put(out, 'aiwg.decision.status', result.spec.status, 'client-derived');
+    put(out, 'aiwg.decision.reason', result.spec.reason, 'client-derived');
+    put(out, 'aiwg.attempt.count', result.spec.attempts.length, 'client-derived');
+    if (result.spec.acceptance) {
+        put(out, 'aiwg.acceptance.policy_version', result.spec.acceptance.policyVersion, 'client-derived');
+        put(out, 'aiwg.acceptance.disposition', result.spec.acceptance.disposition, 'client-derived');
+        put(out, 'aiwg.acceptance.reason', result.spec.acceptance.reason, 'client-derived');
+    }
+    if (result.spec.calibrationCompatibility) {
+        const calibration = result.spec.calibrationCompatibility;
+        put(out, 'aiwg.calibration.compatibility_state', calibration.state, 'client-derived');
+        put(out, 'aiwg.calibration.compatibility_action', calibration.action, 'client-derived');
+        put(out, 'aiwg.calibration.artifact_id', calibration.artifactId, 'client-derived');
+        put(out, 'aiwg.calibration.artifact_digest', calibration.artifactDigest, 'client-derived');
+        put(out, 'aiwg.calibration.alias_revision', calibration.aliasRevision, 'client-derived');
+        put(out, 'aiwg.calibration.reason_count', calibration.reasons.length, 'client-derived');
+    }
+    return out;
+}
+export function mapRulesetResult(result) {
+    const out = { attributes: {}, provenance: {} };
+    put(out, 'aiwg.run.id', result.spec.runId, 'client-derived');
+    put(out, 'aiwg.invocation.id', result.spec.invocationId, 'client-derived');
+    put(out, 'aiwg.ruleset.id', result.spec.ruleset.id, 'client-derived');
+    put(out, 'aiwg.ruleset.version', result.spec.ruleset.version, 'client-derived');
+    put(out, 'aiwg.binding.id', result.spec.binding.id, 'client-derived');
+    put(out, 'aiwg.binding.version', result.spec.binding.version, 'client-derived');
+    put(out, 'aiwg.workflow.status', result.spec.status, 'client-derived');
+    put(out, 'aiwg.decision.reason', result.spec.reason, 'client-derived');
+    put(out, 'aiwg.evaluation.count', Object.keys(result.spec.evaluations).length, 'client-derived');
+    return out;
+}
+//# sourceMappingURL=mapping.js.map