@aiwg/cli 2026.9.21 → 2026.10.0

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

@@ -0,0 +1,571 @@
+import { createTelemetryContext, randomTelemetryIds } from '../telemetry/context.js';
+import { DECISION_TELEMETRY_SCHEMA_VERSION } from '../telemetry/types.js';
+import { recordDecisionSpanMetrics } from '../telemetry/metrics.js';
+import { championChallengerEligibilityProblems, compareEnsembleKeys, ensembleContractDigest, pairedThresholdsDigest, validateChampionChallenger, validateEnsembleIntegrityReport, validateEnsemblePolicy, } from './contract.js';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { assertDecisionResultWriterVersion } from '../validate.js';
+import { aggregateEnsembleResults } from './aggregate.js';
+import { buildEnsembleIntegrityReport } from './report.js';
+import { resolveDriftResponse } from './drift.js';
+export class EnsembleRuntimeError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'EnsembleRuntimeError';
+    }
+}
+export async function executeDecisionEnsemble(policyInput, options) {
+    const validated = validateEnsemblePolicy(policyInput, {
+        hostCeilings: options.hostCeilings,
+        calibrationPins: options.calibrationPins,
+    });
+    const { policy, digest: policyDigest, budget } = validated;
+    if (options.enabled !== true || policy.mode === 'disabled') {
+        emitEnsembleSpan(options.telemetry, options.now, {
+            'aiwg.ensemble.id': policy.id,
+            'aiwg.ensemble.version': policy.version,
+            'aiwg.ensemble.mode': policy.mode,
+            'aiwg.ensemble.status': 'disabled',
+            'aiwg.ensemble.members': policy.members.length,
+        });
+        return {
+            status: 'disabled',
+            reason: options.enabled === true ? 'policy-disabled' : 'disabled',
+            policyDigest,
+            budget,
+            aggregate: null,
+            memberResults: [],
+            retainedResults: {},
+            actuals: { attempts: 0, tokens: 0, costMicros: 0, unknownUsageSamples: 0 },
+        };
+    }
+    if (!options.authorizeMember) {
+        throw new EnsembleRuntimeError('ensemble member authorization callback is required before dispatch', 'member-authorization-missing');
+    }
+    for (const member of [...policy.members].sort((a, b) => compareEnsembleKeys(a.id, b.id))) {
+        if (await options.authorizeMember(member) !== true) {
+            throw new EnsembleRuntimeError(`ensemble member ${member.id} failed security/privacy/capability authorization`, 'member-disallowed');
+        }
+    }
+    const now = options.now ?? Date.now;
+    const deadlineEpochMs = now() + budget.effective.deadlineMs;
+    const deadline = createDeadlineSignal(options.signal, budget.effective.deadlineMs, options.delay);
+    const signal = deadline.signal;
+    const tasks = canonicalSamples(policy);
+    const retainedResults = {};
+    let actualAttempts = 0;
+    let actualTokens = 0;
+    let actualCostMicros = 0;
+    let unknownUsageSamples = 0;
+    let inFlightAttempts = 0;
+    let inFlightTokens = 0;
+    let inFlightCostMicros = 0;
+    const dispatchedMembers = new Set();
+    let exhausted = false;
+    const reservations = new Map(budget.reservations.map(item => [`${item.memberId}:${item.sampleIndex}`, item]));
+    try {
+        const memberResults = await runBounded(tasks, budget.effective.concurrency, async ({ member, sampleIndex }) => {
+            if (signal.aborted || now() >= deadlineEpochMs)
+                return syntheticMemberResult(policy, member, sampleIndex, 'timeout', retainedResults);
+            if (exhausted)
+                return syntheticMemberResult(policy, member, sampleIndex, 'budget-exhausted', retainedResults);
+            // Reserve before dispatch against what is already spent plus every in-flight reservation.
+            const reservation = reservations.get(`${member.id}:${sampleIndex}`);
+            if (!reservation
+                || (!dispatchedMembers.has(member.id) && dispatchedMembers.size + 1 > budget.effective.members)
+                || actualAttempts + inFlightAttempts + reservation.attempts > budget.effective.attempts
+                || actualTokens + inFlightTokens + reservation.tokens > budget.effective.tokens
+                || actualCostMicros + inFlightCostMicros + reservation.costMicros > budget.effective.costMicros) {
+                exhausted = true;
+                return syntheticMemberResult(policy, member, sampleIndex, 'budget-exhausted', retainedResults);
+            }
+            dispatchedMembers.add(member.id);
+            inFlightAttempts += reservation.attempts;
+            inFlightTokens += reservation.tokens;
+            inFlightCostMicros += reservation.costMicros;
+            let settled = false;
+            /** Moves the reservation into actual spend. Without trusted usage the full reserved bound is charged. */
+            const settle = (usage, unknownUsage = usage === undefined) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (unknownUsage)
+                    unknownUsageSamples += 1;
+                usage ??= reservation;
+                inFlightAttempts -= reservation.attempts;
+                inFlightTokens -= reservation.tokens;
+                inFlightCostMicros -= reservation.costMicros;
+                actualAttempts += usage.attempts;
+                actualTokens += usage.tokens;
+                actualCostMicros += usage.costMicros;
+            };
+            let result;
+            try {
+                result = await dispatchWithDeadline(options.dispatch({
+                    policy, policyDigest, member: structuredClone(member), sampleIndex,
+                    invocationId: `${options.invocationId}:${member.id}:${sampleIndex}`, deadlineEpochMs, signal,
+                    limits: { attempts: reservation.attempts, tokens: reservation.tokens, costMicros: reservation.costMicros },
+                }), signal);
+            }
+            catch (error) {
+                // A timed-out or rejected dispatch may still have spent its reservation; it is never refunded.
+                settle();
+                const reason = signal.aborted || now() >= deadlineEpochMs || (error instanceof EnsembleRuntimeError && error.reason === 'timeout')
+                    ? 'timeout' : 'dispatch-error';
+                if (reason === 'timeout')
+                    exhausted = true;
+                return syntheticMemberResult(policy, member, sampleIndex, reason, retainedResults);
+            }
+            try {
+                assertDecisionResultWriterVersion(result);
+                if (result.kind !== 'DecisionResult')
+                    throw new EnsembleRuntimeError('ensemble member must return a DecisionResult', 'invalid-output');
+            }
+            catch {
+                settle();
+                return syntheticMemberResult(policy, member, sampleIndex, 'invalid-output', retainedResults);
+            }
+            const attempts = result.spec.attempts.length;
+            const reportedTokens = result.spec.attempts.reduce((sum, attempt) => sum + (attempt.usage.inputTokens ?? 0) + (attempt.usage.outputTokens ?? 0), 0);
+            // Null token usage is unknown, not zero: charge at least the sample's full token reservation.
+            const unknownTokens = result.spec.attempts.some(attempt => attempt.usage.inputTokens === null || attempt.usage.outputTokens === null);
+            const tokens = unknownTokens ? Math.max(reportedTokens, reservation.tokens) : reportedTokens;
+            const cost = resultCostMicros(policy, result);
+            if (cost === null) {
+                settle({ attempts: Math.max(attempts, reservation.attempts), tokens: Math.max(tokens, reservation.tokens), costMicros: reservation.costMicros }, true);
+                exhausted = true;
+                return syntheticMemberResult(policy, member, sampleIndex, 'unknown-cost', retainedResults, result);
+            }
+            settle({ attempts, tokens, costMicros: cost }, unknownTokens);
+            if (attempts > member.fallbackDepth + 1) {
+                return syntheticMemberResult(policy, member, sampleIndex, 'fallback-depth-exceeded', retainedResults, result);
+            }
+            if (attempts > reservation.attempts || tokens > reservation.tokens || cost > reservation.costMicros
+                || actualAttempts > budget.effective.attempts || actualTokens > budget.effective.tokens
+                || actualCostMicros > budget.effective.costMicros || now() > deadlineEpochMs) {
+                exhausted = true;
+                return syntheticMemberResult(policy, member, sampleIndex, 'budget-exhausted', retainedResults, result);
+            }
+            return memberResultFromDecision(member, sampleIndex, result, retainedResults);
+        });
+        const aggregate = aggregateEnsembleResults(policy, memberResults, {
+            hostCeilings: options.hostCeilings,
+            calibrationPins: options.calibrationPins,
+        });
+        emitEnsembleSpan(options.telemetry, options.now, {
+            'aiwg.ensemble.id': policy.id,
+            'aiwg.ensemble.version': policy.version,
+            'aiwg.ensemble.mode': policy.mode,
+            'aiwg.ensemble.status': 'completed',
+            'aiwg.ensemble.members': policy.members.length,
+            'aiwg.ensemble.disagreement_bps': aggregate.disagreement.valueBps,
+            'aiwg.ensemble.outcome': aggregate.outcome.disposition,
+            'aiwg.budget.attempts.planned': budget.demand.attempts,
+            'aiwg.budget.attempts.actual': actualAttempts,
+            'aiwg.budget.tokens.actual': actualTokens,
+            'aiwg.budget.cost_micros.actual': actualCostMicros,
+            'aiwg.budget.unknown_usage_samples': unknownUsageSamples,
+        });
+        return { status: 'completed', reason: 'completed', policyDigest, budget, aggregate, memberResults, retainedResults,
+            actuals: { attempts: actualAttempts, tokens: actualTokens, costMicros: actualCostMicros, unknownUsageSamples } };
+    }
+    finally {
+        deadline.cancel();
+    }
+}
+export function championChallengerInputSetDigest(items) {
+    return ensembleContractDigest(items.map(item => ({
+        id: item.id,
+        inputDigest: ensembleContractDigest(item.input),
+        ...(item.slice ? { slice: item.slice } : {}),
+    })).sort((a, b) => compareEnsembleKeys(a.id, b.id)));
+}
+export function championChallengerShadowBaseline(recordInput, shadow) {
+    const { record } = validateChampionChallenger(recordInput);
+    const items = new Set(shadow.receipts.map(receipt => receipt.itemId));
+    if (shadow.status !== 'completed' || shadow.receipts.length !== record.inputSet.itemCount || items.size !== shadow.receipts.length) {
+        throw new EnsembleRuntimeError('a shadow baseline needs one completed receipt per frozen input item', 'shadow-incomplete');
+    }
+    return {
+        ...shadowBaselineIdentity(record),
+        pairedDeltasDigest: pairedDeltasDigest(shadow.pairedDeltas),
+        receiptsDigest: ensembleContractDigest([...shadow.receipts].sort((a, b) => compareEnsembleKeys(a.itemId, b.itemId))),
+    };
+}
+function shadowBaselineIdentity(record) {
+    return {
+        kind: 'decision-champion-challenger-shadow/v1',
+        recordId: record.id,
+        inputSetDigest: record.inputSet.digest,
+        thresholdsDigest: record.preregistration.thresholdsDigest,
+        championIdentityDigest: record.champion.identityDigest,
+        challengerIdentityDigest: record.challenger.identityDigest,
+    };
+}
+function pairedDeltasDigest(deltas) {
+    return ensembleContractDigest(deltas.map(item => ({ metric: item.metric, delta: item.delta, pairs: item.pairs }))
+        .sort((a, b) => compareEnsembleKeys(a.metric, b.metric)));
+}
+/** The alias's current revision: the event with the highest revision. */
+function currentAliasEvent(history) {
+    return history.reduce((latest, event) => !latest || event.revision > latest.revision ? event : latest, undefined);
+}
+export async function runChampionChallengerShadow(recordInput, options) {
+    const { record, digest } = validateChampionChallenger(recordInput, {
+        ...(options.eligibility ? { eligibility: options.eligibility } : {}),
+        ...(options.aliasHistory ? { aliasHistory: options.aliasHistory } : {}),
+    });
+    if (options.enabled !== true) {
+        emitEnsembleSpan(options.telemetry, options.now, {
+            'aiwg.ensemble.champion_challenger.id': record.id,
+            'aiwg.ensemble.champion_challenger.status': 'disabled',
+            'aiwg.ensemble.alias': record.alias,
+        });
+        return { status: 'disabled', recordDigest: digest, pairedDeltas: [], receipts: [] };
+    }
+    if (options.items.length !== record.inputSet.itemCount || championChallengerInputSetDigest(options.items) !== record.inputSet.digest) {
+        throw new EnsembleRuntimeError('shadow input set does not match the immutable champion/challenger record', 'input-set-mismatch');
+    }
+    const signal = options.signal ?? new AbortController().signal;
+    const pairs = [];
+    for (const item of options.items) {
+        const before = ensembleContractDigest(item.input);
+        const [champion, challenger] = await Promise.all([
+            options.evaluate({ role: 'champion', rolePin: structuredClone(record.champion), item: structuredClone(item),
+                invocationId: `${options.invocationId}:${item.id}:champion`, signal }),
+            options.evaluate({ role: 'challenger', rolePin: structuredClone(record.challenger), item: structuredClone(item),
+                invocationId: `${options.invocationId}:${item.id}:challenger`, signal }),
+        ]);
+        const after = ensembleContractDigest(item.input);
+        if (before !== after || champion.inputDigest !== before || challenger.inputDigest !== before) {
+            throw new EnsembleRuntimeError('champion and challenger must evaluate identical immutable inputs', 'input-mutated');
+        }
+        pairs.push({ item, champion, challenger });
+    }
+    const pairedDeltas = record.pairedMetrics.map(threshold => observationDelta(threshold.metric, pairs));
+    emitEnsembleSpan(options.telemetry, options.now, {
+        'aiwg.ensemble.champion_challenger.id': record.id,
+        'aiwg.ensemble.champion_challenger.status': 'completed',
+        'aiwg.ensemble.alias': record.alias,
+        'aiwg.ensemble.role': 'paired-shadow',
+        'aiwg.ensemble.pairs': pairs.length,
+    });
+    return {
+        status: 'completed',
+        recordDigest: digest,
+        pairedDeltas,
+        receipts: pairs.map(pair => ({ itemId: pair.item.id, champion: pair.champion.receiptDigest, challenger: pair.challenger.receiptDigest })),
+    };
+}
+export function pinChampionForRun(recordInput, runId) {
+    const { record } = validateChampionChallenger(recordInput);
+    return {
+        runId,
+        alias: record.alias,
+        aliasRevision: record.champion.aliasRevision,
+        identityDigest: record.champion.identityDigest,
+        actualModel: record.champion.actualModel,
+    };
+}
+export function promoteChampionChallenger(input) {
+    const aliasHistory = input.gateway.aliasHistory(input.record.alias);
+    const { record, digest } = validateChampionChallenger(input.record, { eligibility: input.eligibility, aliasHistory });
+    // The gateway promotes D09's stored record, so that is the one that must have been validated.
+    const stored = input.gateway.promotionEligibility(record.eligibilityId);
+    if (!stored || canonicalJson(stored) !== canonicalJson(input.eligibility)) {
+        throw new EnsembleRuntimeError('supplied eligibility does not match the D09 stored promotion eligibility', 'promotion-eligibility-mismatch');
+    }
+    const current = currentAliasEvent(aliasHistory);
+    if (!current || current.kind === 'retired' || current.revision !== record.champion.aliasRevision
+        || current.actualIdentityDigest !== record.champion.identityDigest) {
+        throw new EnsembleRuntimeError('alias no longer holds the champion this record pins', 'promotion-stale-champion');
+    }
+    if (aliasHistory.some(event => event.promotionEligibilityId === record.eligibilityId)) {
+        throw new EnsembleRuntimeError(`promotion eligibility ${record.eligibilityId} was already used`, 'promotion-replayed');
+    }
+    const report = validateEnsembleIntegrityReport(input.integrityReport);
+    // Never trust the supplied report's findings, flags or decision: rebuild it from the trusted
+    // record, D09 eligibility and alias history, and require the exact same canonical report.
+    const rebuilt = buildEnsembleIntegrityReport({
+        record, integrity: report.integrity, eligibility: input.eligibility, aliasHistory,
+        pairedDeltas: report.pairedDeltas.map(item => ({ metric: item.metric, delta: item.delta, pairs: item.pairs })),
+    });
+    if (canonicalJson(rebuilt) !== canonicalJson(report)) {
+        throw new EnsembleRuntimeError('integrity report does not match the report rebuilt from the trusted record', 'promotion-report-mismatch');
+    }
+    const problems = championChallengerEligibilityProblems(record, input.eligibility);
+    if (report.decision !== 'PROMOTE' || report.subject.id !== record.id
+        || report.subject.digest !== digest || report.subject.eligibilityId !== record.eligibilityId
+        || input.eligibility.eligible !== true || problems.length > 0) {
+        throw new EnsembleRuntimeError('promotion requires eligible D09 state, verified eval-integrity and a pinned rollback target', 'promotion-gate');
+    }
+    if (ensembleContractDigest(report.integrity) !== record.evaluationIntegrityReport.digest) {
+        throw new EnsembleRuntimeError('integrity fields do not match the record\'s pinned evaluation-integrity report digest', 'promotion-integrity-binding');
+    }
+    const pairedBaseline = report.integrity.paired_baseline;
+    const baseline = pairedBaseline && typeof pairedBaseline === 'object' ? pairedBaseline.championChallengerShadow : null;
+    const { receiptsDigest, ...boundFields } = (baseline && typeof baseline === 'object' ? baseline : {});
+    if (canonicalJson(boundFields) !== canonicalJson({ ...shadowBaselineIdentity(record), pairedDeltasDigest: pairedDeltasDigest(report.pairedDeltas) })
+        || typeof receiptsDigest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(receiptsDigest)) {
+        throw new EnsembleRuntimeError('paired deltas are not bound to a completed shadow run for this record', 'promotion-shadow-unbound');
+    }
+    const event = input.gateway.promoteAlias(record.eligibilityId, input.at);
+    if (!event || event.kind !== 'promoted' || event.alias !== record.alias || event.promotionEligibilityId !== record.eligibilityId
+        || event.actualIdentityDigest !== record.challenger.identityDigest || event.actualModel !== record.challenger.actualModel
+        || event.revision !== current.revision + 1) {
+        throw new EnsembleRuntimeError('D09 gateway returned a promotion event that does not move the alias from the pinned champion to this record\'s challenger; inspect alias history', 'promotion-event-mismatch');
+    }
+    emitEnsembleSpan(input.telemetry, input.now, {
+        'aiwg.ensemble.champion_challenger.id': record.id,
+        'aiwg.ensemble.alias': record.alias,
+        'aiwg.ensemble.promotion': 'promoted',
+        'aiwg.ensemble.rollback_revision': record.rollbackTarget.aliasRevision,
+    });
+    return event;
+}
+export function rollbackChampionForNewRuns(input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9:._/@-]{2,127}$/.test(input.approvalReference)) {
+        throw new EnsembleRuntimeError('rollback requires a non-empty valid approval reference', 'rollback-approval-reference');
+    }
+    const aliasHistory = input.gateway.aliasHistory(input.record.alias);
+    const { record } = validateChampionChallenger(input.record, { aliasHistory });
+    // Only undo this record's own promotion: the alias's current revision must be the promoted
+    // challenger, and the revision it replaced must be the pinned champion (the rollback target).
+    const current = currentAliasEvent(aliasHistory);
+    const replaced = current && currentAliasEvent(aliasHistory.filter(event => event.revision < current.revision));
+    if (!current || current.kind !== 'promoted' || current.alias !== record.alias || current.promotionEligibilityId !== record.eligibilityId
+        || current.actualIdentityDigest !== record.challenger.identityDigest || current.actualModel !== record.challenger.actualModel) {
+        throw new EnsembleRuntimeError('rollback requires the alias to currently hold this record\'s promoted challenger', 'rollback-not-promoted');
+    }
+    if (!replaced || replaced.revision !== record.rollbackTarget.aliasRevision || replaced.actualIdentityDigest !== record.rollbackTarget.identityDigest) {
+        throw new EnsembleRuntimeError('rollback requires the promotion to have directly replaced the pinned champion', 'rollback-champion-mismatch');
+    }
+    const event = input.gateway.rollbackAlias(record.alias, record.rollbackTarget.aliasRevision, input.approvalReference, input.at);
+    emitEnsembleSpan(input.telemetry, input.now, {
+        'aiwg.ensemble.champion_challenger.id': record.id,
+        'aiwg.ensemble.alias': record.alias,
+        'aiwg.ensemble.rollback': 'restored-champion',
+        'aiwg.ensemble.rollback_revision': record.rollbackTarget.aliasRevision,
+    });
+    return event;
+}
+export async function executeDriftResponse(policyInput, signal, handlers = {}, telemetry, now) {
+    const decision = resolveDriftResponse(policyInput, signal);
+    if (decision.response) {
+        const handler = handlers[decision.response];
+        if (!handler)
+            throw new EnsembleRuntimeError(`drift response ${decision.response} has no registered handler`, 'drift-handler-missing');
+        await handler(decision);
+    }
+    emitEnsembleSpan(telemetry, now, {
+        'aiwg.ensemble.drift.signal_id': decision.signalId,
+        'aiwg.ensemble.drift.source': decision.source,
+        'aiwg.ensemble.drift.metric': decision.metric,
+        'aiwg.ensemble.drift.state': decision.state,
+        'aiwg.ensemble.drift.response': decision.response,
+        'aiwg.drift.value': signal.source === 'alias-drift' ? 1 : signal.valueBps,
+    });
+    return { decision, executed: decision.response };
+}
+function createDeadlineSignal(parent, deadlineMs, delay) {
+    const controller = new AbortController();
+    const timer = new AbortController();
+    const abort = () => { if (!controller.signal.aborted)
+        controller.abort(); };
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    const wait = delay ?? defaultDelay;
+    void wait(deadlineMs, timer.signal).then(abort, () => undefined);
+    return {
+        signal: controller.signal,
+        cancel: () => {
+            timer.abort();
+            parent?.removeEventListener('abort', abort);
+        },
+    };
+}
+function defaultDelay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timeout);
+            reject(new Error('cancelled'));
+        }, { once: true });
+    });
+}
+function dispatchWithDeadline(result, signal) {
+    if (signal.aborted)
+        return Promise.reject(new EnsembleRuntimeError('ensemble dispatch deadline exceeded', 'timeout'));
+    return Promise.race([result, new Promise((_, reject) => {
+            signal.addEventListener('abort', () => reject(new EnsembleRuntimeError('ensemble dispatch deadline exceeded', 'timeout')), { once: true });
+        })]);
+}
+function canonicalSamples(policy) {
+    return [...policy.members].sort((a, b) => compareEnsembleKeys(a.id, b.id))
+        .flatMap(member => Array.from({ length: member.samples }, (_, sampleIndex) => ({ member, sampleIndex })));
+}
+async function runBounded(items, concurrency, task) {
+    const output = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (next < items.length) {
+            const index = next++;
+            output[index] = await task(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return output;
+}
+function memberResultFromDecision(member, sampleIndex, result, retainedResults) {
+    const digest = ensembleContractDigest(result);
+    retainedResults[digest] = structuredClone(result);
+    return {
+        memberId: member.id,
+        sampleIndex,
+        status: result.spec.status === 'success' ? 'succeeded' : result.spec.status === 'abstained' ? 'abstained' : 'failed',
+        resultDigest: digest,
+        value: result.spec.status === 'success' ? result.spec.value ?? null : null,
+        distribution: result.spec.status === 'success' ? result.spec.uncertainty?.distribution ?? null : null,
+        uncertaintyProfile: result.spec.status === 'success' ? result.spec.uncertainty?.profile ?? null : null,
+    };
+}
+function syntheticMemberResult(policy, member, sampleIndex, reason, retainedResults, source) {
+    const failureReason = syntheticFailureReason(reason);
+    const result = source ? structuredClone(source) : {
+        apiVersion: 'decision.aiwg.io/v1alpha1',
+        kind: 'DecisionResult',
+        metadata: { id: `${policy.id}:${member.id}:${sampleIndex}`, version: policy.version, description: reason },
+        spec: {
+            decision: member.definition,
+            ruleset: member.definition,
+            binding: member.binding,
+            alias: member.id,
+            runId: policy.id,
+            invocationId: `${policy.id}:${member.id}:${sampleIndex}`,
+            status: 'error',
+            reason: failureReason,
+            uncertainty: null,
+            attempts: [syntheticAttempt(member, failureReason)],
+        },
+    };
+    const { value: _value, uncertainty: _uncertainty, ...spec } = result.spec;
+    return memberResultFromDecision(member, sampleIndex, {
+        ...result,
+        spec: { ...spec, status: 'error', reason: failureReason, uncertainty: null },
+    }, retainedResults);
+}
+function syntheticAttempt(member, reason) {
+    return {
+        ordinal: 1,
+        adapter: member.adapter.id,
+        adapterVersion: member.adapter.version,
+        requestedModel: member.model.requested,
+        actualModel: null,
+        subagent: null,
+        status: 'error',
+        reason,
+        durationMs: 0,
+        usage: { inputTokens: null, outputTokens: null, costUsd: null },
+        requestId: null,
+    };
+}
+function syntheticFailureReason(reason) {
+    if (reason === 'timeout')
+        return 'timeout';
+    if (reason === 'invalid-output')
+        return 'invalid-output';
+    if (reason === 'dispatch-error')
+        return 'service-error';
+    return 'budget-exhausted';
+}
+function resultCostMicros(policy, result) {
+    let cost = 0;
+    for (const attempt of result.spec.attempts) {
+        if (attempt.usage.costUsd === null) {
+            if (policy.ceilings.unknownCost.rule === 'reject')
+                return null;
+            cost += policy.ceilings.unknownCost.boundMicrosPerAttempt;
+        }
+        else {
+            cost += Math.round(attempt.usage.costUsd * 1_000_000);
+        }
+    }
+    return cost;
+}
+function observationDelta(metric, pairs) {
+    const key = metricKey(metric);
+    const deltas = pairs.map(pair => {
+        const champion = pair.champion[key];
+        const challenger = pair.challenger[key];
+        return champion === null || challenger === null ? null : challenger - champion;
+    }).filter((value) => value !== null && Number.isFinite(value));
+    return {
+        metric,
+        delta: deltas.length ? round(deltas.reduce((sum, value) => sum + value, 0) / deltas.length) : null,
+        pairs: deltas.length,
+    };
+}
+function metricKey(metric) {
+    if (metric === 'risk-coverage')
+        return 'riskCoverage';
+    if (metric === 'latency')
+        return 'latencyMs';
+    if (metric === 'cost')
+        return 'costMicros';
+    return metric;
+}
+function round(value) { return Math.round(value * 1e12) / 1e12; }
+function emitEnsembleSpan(telemetry, nowInput, attributes) {
+    if (!telemetry?.hook && !telemetry?.metrics)
+        return;
+    const now = nowInput ?? Date.now;
+    const at = now();
+    const context = telemetryContext(telemetry.traceId);
+    const clean = Object.fromEntries(Object.entries(attributes).filter(([, value]) => value === null || ['string', 'number', 'boolean'].includes(typeof value)));
+    const span = {
+        schemaVersion: DECISION_TELEMETRY_SCHEMA_VERSION,
+        name: 'decision.workflow',
+        context,
+        parentSpanId: telemetry.parentSpanId ?? null,
+        startTimeUnixMs: at,
+        endTimeUnixMs: at,
+        status: 'ok',
+        attributes: clean,
+        provenance: Object.fromEntries(Object.keys(clean).map(key => [key, 'client-derived'])),
+        links: [],
+        events: [],
+    };
+    try {
+        if (telemetry.metrics)
+            recordDecisionSpanMetrics(span, telemetry.metrics);
+    }
+    catch { /* observability never controls runtime */ }
+    try {
+        void telemetry.hook?.emit(span);
+    }
+    catch { /* observability never controls runtime */ }
+}
+function telemetryContext(traceId) {
+    try {
+        return createTelemetryContext({
+            traceId: () => traceId ?? randomTelemetryIds.traceId(),
+            spanId: () => randomTelemetryIds.spanId(),
+        });
+    }
+    catch {
+        return createTelemetryContext(randomTelemetryIds);
+    }
+}
+export function preregisterChampionChallengerThresholds(record) {
+    return {
+        ...record,
+        preregistration: {
+            ...record.preregistration,
+            thresholdsDigest: pairedThresholdsDigest(record.pairedMetrics),
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/decision/ensemble-study/artifacts.js

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { admitEntry, DEFAULT_ENTRY_LIMITS } from '../entry.js';
+import { heldoutDigest } from '../heldout/contract.js';
+const schemas = { analysis: 'D17StudyAnalysis', splits: 'D17StudySplits', gold: 'D17StudyGold',
+    review: 'D17StudyReview', guide: 'D17StudyGuide', report: 'D17StudyReport',
+    nativeTemplates: 'D17StudyNativeTemplates', dryRun: 'D17StudyDryRun',
+    // Staged D09 calibration (#2611): new schema versions; the v1 diagnostic schemas are unchanged.
+    analysisV2: 'D17StudyAnalysis.v2', dryRunV2: 'D17StudyDryRun.v2', reportV2: 'D17StudyReport.v2',
+    calibration: 'D17StudyCalibration' };
+const here = dirname(fileURLToPath(import.meta.url));
+const schemaDir = [resolve(here, '../../../schemas/decision'), resolve(here, '../../../../schemas/decision')]
+    .find(directory => existsSync(resolve(directory, 'D17StudyProtocol.v1.schema.json')));
+if (!schemaDir)
+    throw new Error('D17 artifact schema directory is unavailable');
+const readSchema = (name) => JSON.parse(readFileSync(resolve(schemaDir, `${/\.v[0-9]+$/.test(name) ? name : `${name}.v1`}.schema.json`), 'utf8'));
+const ajv = new Ajv2020({ strict: true });
+ajv.addSchema(readSchema('D17StudyProtocol'));
+ajv.addSchema(readSchema('DecisionEnsembleAggregate'));
+ajv.addSchema(readSchema('DecisionEnsembleIntegrityReport'));
+const calibrationSchema = readSchema('D17StudyCalibration');
+ajv.addSchema(calibrationSchema);
+const validators = Object.fromEntries(Object.entries(schemas).map(([name, schema]) => [name,
+    name === 'calibration' ? ajv.getSchema(calibrationSchema.$id) : ajv.compile(readSchema(schema))]));
+const limits = { ...DEFAULT_ENTRY_LIMITS, serializedBytes: 8_388_608, properties: 100000, entries: 150000,
+    arrayLength: 1800, memoryBytes: 33_554_432 };
+const reportLimits = { ...limits, serializedBytes: 33_554_432, properties: 500000, entries: 1000000, memoryBytes: 134_217_728 };
+/** Closed, bounded preparation artifacts; gold remains local and separate from provider input. */
+export function validateD17Artifact(name, value) {
+    admitEntry(value, name === 'report' || name === 'reportV2' ? reportLimits : limits);
+    if (!validators[name]?.(value))
+        throw new Error(`D17 invalid ${name} artifact`);
+    if (name === 'splits') {
+        const manifest = value;
+        const ids = new Set(), inputs = new Set(), families = new Map();
+        for (const [split, group] of Object.entries(manifest.splits)) {
+            if (heldoutDigest(group.members) !== group.digest)
+                throw new Error('D17 split digest mismatch');
+            for (const row of group.members) {
+                if (ids.has(row.id) || inputs.has(row.inputDigest) || !/^[0-9a-f]{64}$/.test(row.id)
+                    || families.has(row.familyId) && families.get(row.familyId) !== split)
+                    throw new Error('D17 split isolation');
+                ids.add(row.id);
+                inputs.add(row.inputDigest);
+                families.set(row.familyId, split);
+            }
+            for (const slice of ['direct-facts', 'multi-fact', 'negation', 'authority']) {
+                if (group.members.filter(row => row.slice === slice).length !== group.count / 4)
+                    throw new Error('D17 slice quota');
+            }
+        }
+    }
+    if (name === 'gold') {
+        const gold = value;
+        if (Object.keys(gold.labels).some(id => !Object.hasOwn(gold.worlds, id)))
+            throw new Error('D17 gold membership');
+        if (Object.keys(gold.worlds).some(id => !Object.hasOwn(gold.labels, id)))
+            throw new Error('D17 gold membership');
+    }
+    if (name === 'review') {
+        const review = value;
+        if (new Set(review.assessments.map(row => row.assessmentId)).size !== 88)
+            throw new Error('D17 review IDs');
+        for (const [stage, count] of [['development', 40], ['blind-test', 40], ['delayed-repeat', 8]]) {
+            const rows = review.assessments.filter(row => row.stage === stage);
+            const framing = stage === 'development' ? 'A fictional archive records this world.'
+                : 'The following is an imaginary station log.';
+            if (rows.length !== count || new Set(rows.map(row => row.rowId)).size !== count
+                || rows.some(row => !/^[0-9a-f]{64}$/.test(row.rowId) || typeof row.payload !== 'string' || !row.payload.startsWith(framing)
+                    || heldoutDigest({ payload: row.payload }) !== row.inputDigest)) {
+                throw new Error('D17 review sample');
+            }
+            for (const slice of ['direct-facts', 'multi-fact', 'negation', 'authority']) {
+                if (rows.filter(row => row.slice === slice).length !== count / 4)
+                    throw new Error('D17 review slice quota');
+            }
+        }
+        const testIds = new Set(review.assessments.filter(row => row.stage === 'blind-test').map(row => row.rowId));
+        if (review.assessments.some(row => row.stage === 'delayed-repeat' && !testIds.has(row.rowId)))
+            throw new Error('D17 review repeat');
+    }
+}
+//# sourceMappingURL=artifacts.js.map