@aiwg/cli 2026.9.21 → 2026.10.0

package/dist/src/gates/evaluate.js

@@ -0,0 +1,719 @@
+import { qualificationIntegrityAllowlistProblems } from '../decision/qualification/release.js';
+import { artifactDigest } from '../decision/validate.js';
+import { evaluatePredicate } from '../decision/predicates.js';
+import { clopperPearsonInterval } from './stats/clopper-pearson.js';
+import { wilsonScoreInterval } from './stats/binomial.js';
+import { pairedMeanDifferenceBootstrap } from './stats/bootstrap.js';
+import { PairedDifferenceError } from './stats/error.js';
+import { pairedBinaryDifferenceInterval, pairedNonInferiority } from './stats/paired.js';
+import { GateRegistry, authoredGatePacksOf, gateProvidersOf, resolveGateBinding } from './registry.js';
+import { GATE_PROVIDER_DEFAULT_TIMEOUT_MS, GATE_PROVIDER_MAX_OUTPUT_BYTES, deriveIsolatedSeed, isLoaderIssuedProvider, runIsolatedProviderSync, sealProviderSection, } from './providers/loader.js';
+import { qualifyGateParameter } from './types.js';
+export class GateEvaluationError extends Error {
+    constructor(message) { super(message); this.name = 'GateEvaluationError'; }
+}
+const RANK = { PROMOTE: 0, HOLD: 1, ROLLBACK: 2 };
+/** Shared outcome lattice. The maximum never upgrades any component. */
+export function maxOutcome(...outcomes) {
+    return outcomes.reduce((worst, outcome) => (RANK[outcome] > RANK[worst] ? outcome : worst), 'PROMOTE');
+}
+/**
+ * Per-gate outcome from its own status: `pass` promotes, `fail` takes the
+ * gate's `onFail`, `insufficient` takes `onInsufficient` (always HOLD by load
+ * validation; ROLLBACK needs an observed blocking failure). Shortfalls never PROMOTE.
+ */
+export function gateStatusOutcome(status, gate) {
+    if (status === 'pass')
+        return 'PROMOTE';
+    if (status === 'fail')
+        return gate.onFail;
+    return gate.onInsufficient ?? 'HOLD';
+}
+/** Binds an integrity report for evaluation. The digest is re-derived on every use; a forged copy is refused. */
+export function sealUpstream(metadata) {
+    return { metadata, digest: artifactDigest(metadata) };
+}
+/**
+ * Seals trusted holdout inputs for evaluation. The seal covers
+ * `{frozenDigest, firstAccessedAt}` and is re-derived by `evaluateGates` on
+ * every use, following the HeldoutFrozen seal (`readHeldoutFrozen` checks
+ * `frozen.digest === heldoutDigest(frozen.bundle)`): a spread-copied or edited
+ * record is refused. The seal is an unkeyed integrity digest, not an
+ * authenticity proof, so the holdout inputs are trusted caller inputs built from
+ * verified HeldoutFrozen and access records (verification of the frozen record
+ * itself is tracked in #2833). `frozenDigest` is the binding digest in the frozen record.
+ */
+export function sealGateHoldout(input) {
+    const payload = { frozenDigest: input.frozenDigest, firstAccessedAt: input.firstAccessedAt };
+    return { ...payload, digest: artifactDigest(payload) };
+}
+const fail = (message) => { throw new GateEvaluationError(message); };
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+function supportOf(observation) {
+    const n = observation?.n;
+    return typeof n === 'number' && Number.isSafeInteger(n) && n >= 0 ? n : null;
+}
+function poolObservations(kind, observations) {
+    if (!observations.length)
+        return null;
+    if (kind === 'proportion') {
+        let n = 0;
+        let events = 0;
+        for (const observation of observations) {
+            if (supportOf(observation) === null || typeof observation.events !== 'number'
+                || !Number.isSafeInteger(observation.events) || observation.events < 0)
+                return null;
+            if (observation.events > observation.n)
+                return null;
+            n += observation.n;
+            events += observation.events;
+        }
+        return { n, events };
+    }
+    if (kind === 'paired') {
+        const total = { both: 0, candidateOnly: 0, baselineOnly: 0, neither: 0 };
+        let n = 0;
+        for (const observation of observations) {
+            const cells = isRecord(observation?.paired)
+                ? ['both', 'candidateOnly', 'baselineOnly', 'neither'].map(key => observation.paired[key])
+                : [];
+            if (supportOf(observation) === null || cells.length !== 4
+                || cells.some(cell => !Number.isSafeInteger(cell) || cell < 0)) {
+                return null;
+            }
+            const [both, candidateOnly, baselineOnly, neither] = cells;
+            // The counted support must equal the cell sums; a disagreement is unknown, fail closed.
+            if (observation.n !== both + candidateOnly + baselineOnly + neither)
+                return null;
+            n += observation.n;
+            total.both += both;
+            total.candidateOnly += candidateOnly;
+            total.baselineOnly += baselineOnly;
+            total.neither += neither;
+        }
+        return { n, paired: total };
+    }
+    if (kind === 'scalar') {
+        let n = 0;
+        let weighted = 0;
+        for (const observation of observations) {
+            if (supportOf(observation) === null || typeof observation.value !== 'number' || !Number.isFinite(observation.value))
+                return null;
+            n += observation.n;
+            weighted += observation.n * observation.value;
+        }
+        return n === 0 ? null : { n, value: weighted / n };
+    }
+    if (kind === 'differences') {
+        const differences = [];
+        let n = 0;
+        for (const observation of observations) {
+            if (supportOf(observation) === null || !Array.isArray(observation.differences)
+                || observation.differences.some(value => typeof value !== 'number' || !Number.isFinite(value)))
+                return null;
+            if (observation.n !== observation.differences.length)
+                return null;
+            n += observation.n;
+            differences.push(...observation.differences);
+        }
+        return { n, differences };
+    }
+    if (kind === 'evidence') {
+        const available = observations.flatMap(observation => observation?.available ?? []);
+        if (observations.some(observation => !Array.isArray(observation?.available)))
+            return null;
+        return { available };
+    }
+    return null;
+}
+function seriesFor(gate, pack, metrics) {
+    if (gate.metric === undefined)
+        return null;
+    const declared = pack.resolved.spec.metrics[gate.metric.name];
+    if (declared === undefined || declared.provider !== gate.metric.provider)
+        return null;
+    return metrics.providers[gate.metric.provider]?.metrics[gate.metric.name] ?? null;
+}
+function metricKindOf(gate, pack) {
+    if (gate.metric === undefined)
+        return '';
+    return pack.resolved.spec.metrics[gate.metric.name]?.kind ?? '';
+}
+function expandScope(gate, kind, series, slices) {
+    const mode = gate.scope.mode;
+    if (mode === 'all')
+        return [{ slice: null, observation: series?.pooled ?? null }];
+    if (mode === 'pooled') {
+        const observations = (gate.scope.slices ?? []).map(slice => series?.bySlice[slice] ?? null);
+        if (observations.some(observation => observation === null)) {
+            return [{ slice: null, observation: null }];
+        }
+        return [{ slice: null, observation: poolObservations(kind, observations) }];
+    }
+    const excluded = new Set(gate.scope.except ?? []);
+    const names = mode === 'each' ? slices.filter(slice => !excluded.has(slice)) : (gate.scope.slices ?? []);
+    return names.map(slice => ({ slice, observation: series?.bySlice[slice] ?? null }));
+}
+function pairedCells(observation) {
+    if (!isRecord(observation?.paired))
+        return null;
+    const cells = ['both', 'candidateOnly', 'baselineOnly', 'neither'].map(key => observation.paired[key]);
+    if (cells.some(cell => !Number.isSafeInteger(cell) || cell < 0))
+        return null;
+    const [both, candidateOnly, baselineOnly, neither] = cells;
+    return { both, candidateOnly, baselineOnly, neither };
+}
+/**
+ * Resolve a literal-or-parameter gate number against the binding's
+ * preregistered values. Null when a `{param}` reference has no resolved
+ * value: callers hold as `parameter-missing`, never promote.
+ */
+function resolveGateNumber(value, packId, parameters) {
+    if (value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return value;
+    if (value !== null && typeof value === 'object' && typeof value.param === 'string') {
+        const resolved = parameters[qualifyGateParameter(packId, value.param)];
+        return typeof resolved === 'number' ? resolved : null;
+    }
+    return null;
+}
+function evaluateObservation(gate, observation, context) {
+    const { packId, parameters, metrics, upstream, nowMs, slice, slices } = context;
+    const base = { slice, n: supportOf(observation) };
+    const minimumN = gate.minimumN === undefined ? 0 : resolveGateNumber(gate.minimumN, packId, parameters);
+    // Evidence gates observe attestations, not counted support; upstream and predicate
+    // gates read the ceiling and the whole document. None of them take an n.
+    if (gate.kind !== 'upstream-ceiling' && gate.kind !== 'predicate' && gate.kind !== 'evidence') {
+        if (observation === null || observation === undefined)
+            return { ...base, status: 'insufficient', reason: 'metric-missing' };
+        if (base.n === null)
+            return { ...base, status: 'insufficient', reason: 'support-unknown' };
+        if (minimumN === null)
+            return { ...base, status: 'insufficient', reason: 'parameter-missing' };
+        if (base.n < minimumN)
+            return { ...base, status: 'insufficient', reason: 'below-minimum-n' };
+    }
+    const thresholdValue = () => {
+        if (gate.threshold?.value !== undefined)
+            return gate.threshold.value;
+        if (gate.threshold?.param !== undefined) {
+            const value = parameters[qualifyGateParameter(packId, gate.threshold.param)];
+            return typeof value === 'number' ? value : null;
+        }
+        return null;
+    };
+    switch (gate.kind) {
+        case 'minimum-n': {
+            const target = gate.minimumN === undefined ? null : resolveGateNumber(gate.minimumN, packId, parameters);
+            if (target === null) {
+                return { ...base, status: 'insufficient', reason: 'parameter-missing',
+                    statistic: { method: 'support-count' } };
+            }
+            const passed = base.n >= target;
+            return { ...base, status: passed ? 'pass' : 'insufficient', reason: passed ? 'support-met' : 'below-minimum-n',
+                statistic: { method: 'support-count' } };
+        }
+        case 'interval-bound': {
+            const events = observation?.events;
+            if (typeof events !== 'number' || !Number.isSafeInteger(events) || events < 0) {
+                return { ...base, status: 'insufficient', reason: 'events-unknown', events: null };
+            }
+            if (events > base.n)
+                return { ...base, status: 'insufficient', reason: 'events-exceed-n', events };
+            const target = thresholdValue();
+            if (target === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing', events };
+            const method = gate.statistic?.method ?? 'wilson';
+            const levelBps = resolveGateNumber(gate.statistic?.levelBps, packId, parameters);
+            if (levelBps === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing', events };
+            let lower;
+            let upper;
+            try {
+                if (method === 'clopper-pearson') {
+                    ({ lower, upper } = clopperPearsonInterval({ events, n: base.n, levelBps }));
+                }
+                else {
+                    [lower, upper] = wilsonScoreInterval({ events, n: base.n, levelBps });
+                }
+            }
+            catch (error) {
+                if (error instanceof PairedDifferenceError) {
+                    return { ...base, status: 'insufficient', reason: 'statistic-invalid', events };
+                }
+                throw error;
+            }
+            const lowerBps = Math.max(0, Math.floor(lower * 10000));
+            const upperBps = Math.min(10000, Math.ceil(upper * 10000));
+            const estimateBps = Math.round(events / base.n * 10000);
+            const passed = gate.statistic?.bound === 'upper' ? upperBps <= target : lowerBps >= target;
+            return { ...base, status: passed ? 'pass' : 'fail', reason: passed ? 'bound-within-threshold' : 'bound-breaches-threshold',
+                events, statistic: { method, levelBps, lowerBps, upperBps, estimateBps },
+                threshold: { op: gate.threshold?.op, ...(gate.threshold?.value !== undefined
+                        ? { value: gate.threshold.value } : { param: gate.threshold?.param }), resolved: target } };
+        }
+        case 'paired-difference': {
+            const cells = pairedCells(observation);
+            if (cells === null)
+                return { ...base, status: 'insufficient', reason: 'paired-unknown' };
+            if (base.n !== cells.both + cells.candidateOnly + cells.baselineOnly + cells.neither) {
+                return { ...base, status: 'insufficient', reason: 'observation-mismatch' };
+            }
+            const method = gate.statistic?.method ?? 'newcombe';
+            const levelBps = resolveGateNumber(gate.statistic?.levelBps, packId, parameters);
+            if (levelBps === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing' };
+            let interval;
+            try {
+                interval = pairedBinaryDifferenceInterval({ counts: cells, levelBps, method: method === 'tango' ? 'tango' : 'newcombe-10' });
+            }
+            catch (error) {
+                if (error instanceof PairedDifferenceError)
+                    return { ...base, status: 'insufficient', reason: 'paired-invalid' };
+                throw error;
+            }
+            const mode = gate.statistic?.mode ?? 'non-inferiority';
+            const margin = gate.statistic?.marginBps ?? 0;
+            const statistic = { method, levelBps, lowerBps: interval.lowerBps, upperBps: interval.upperBps,
+                estimateBps: interval.estimateBps };
+            const threshold = { op: 'gte', resolved: margin };
+            if (mode === 'non-inferiority') {
+                const verdict = pairedNonInferiority({ interval, marginBps: margin });
+                if (verdict.decision === 'insufficient')
+                    return { ...base, status: 'insufficient', reason: 'paired-invalid', statistic, threshold };
+                const passed = verdict.decision === 'non-inferior';
+                return { ...base, status: passed ? 'pass' : 'fail',
+                    reason: passed ? 'lower-bound-at-or-above-margin' : 'lower-bound-below-margin', statistic, threshold };
+            }
+            const passed = interval.lowerBps > margin;
+            return { ...base, status: passed ? 'pass' : 'fail',
+                reason: passed ? 'lower-bound-above-margin' : 'lower-bound-at-or-below-margin', statistic, threshold };
+        }
+        case 'bootstrap-bound': {
+            const differences = observation?.differences;
+            if (!Array.isArray(differences))
+                return { ...base, status: 'insufficient', reason: 'differences-unknown' };
+            if (differences.length !== base.n)
+                return { ...base, status: 'insufficient', reason: 'observation-mismatch' };
+            const target = thresholdValue();
+            if (target === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing' };
+            const levelBps = resolveGateNumber(gate.statistic?.levelBps, packId, parameters);
+            if (levelBps === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing' };
+            let interval;
+            try {
+                interval = pairedMeanDifferenceBootstrap({ differences, levelBps,
+                    seed: gate.statistic?.seed, resamples: gate.statistic?.resamples,
+                    bounds: gate.statistic?.bounds });
+            }
+            catch (error) {
+                if (error instanceof PairedDifferenceError)
+                    return { ...base, status: 'insufficient', reason: 'statistic-invalid' };
+                throw error;
+            }
+            const passed = gate.statistic?.bound === 'upper' ? interval.upperBps <= target : interval.lowerBps >= target;
+            return { ...base, status: passed ? 'pass' : 'fail', reason: passed ? 'bound-within-threshold' : 'bound-breaches-threshold',
+                statistic: { method: 'bootstrap', levelBps, lowerBps: interval.lowerBps,
+                    upperBps: interval.upperBps, estimateBps: interval.estimateBps },
+                threshold: { op: gate.threshold?.op, ...(gate.threshold?.value !== undefined
+                        ? { value: gate.threshold.value } : { param: gate.threshold?.param }), resolved: target } };
+        }
+        case 'count-max':
+        case 'count-min': {
+            const events = observation?.events;
+            if (typeof events !== 'number' || !Number.isSafeInteger(events) || events < 0) {
+                return { ...base, status: 'insufficient', reason: 'events-unknown', events: null };
+            }
+            if (events > base.n)
+                return { ...base, status: 'insufficient', reason: 'events-exceed-n', events };
+            const target = thresholdValue();
+            if (target === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing', events };
+            const passed = gate.kind === 'count-max' ? events <= target : events >= target;
+            return { ...base, status: passed ? 'pass' : 'fail', reason: passed ? 'count-within-threshold' : 'count-breaches-threshold',
+                events, statistic: { method: 'exact-count' },
+                threshold: { op: gate.threshold?.op, ...(gate.threshold?.value !== undefined
+                        ? { value: gate.threshold.value } : { param: gate.threshold?.param }), resolved: target } };
+        }
+        case 'value-threshold': {
+            const value = observation?.value;
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                return { ...base, status: 'insufficient', reason: 'value-unknown' };
+            }
+            const target = thresholdValue();
+            if (target === null)
+                return { ...base, status: 'insufficient', reason: 'parameter-missing' };
+            const passed = gate.threshold?.op === 'lte' ? value <= target : value >= target;
+            return { ...base, status: passed ? 'pass' : 'fail', reason: passed ? 'value-within-threshold' : 'value-breaches-threshold',
+                statistic: { method: 'exact-value' },
+                threshold: { op: gate.threshold?.op, ...(gate.threshold?.value !== undefined
+                        ? { value: gate.threshold.value } : { param: gate.threshold?.param }), resolved: target } };
+        }
+        case 'evidence': {
+            const available = observation?.available;
+            if (!Array.isArray(available))
+                return { ...base, status: 'insufficient', reason: 'evidence-unknown' };
+            for (const id of gate.evidence?.required ?? []) {
+                const entry = available.find(candidate => candidate?.id === id);
+                if (entry === undefined)
+                    return { ...base, status: 'insufficient', reason: 'evidence-missing', statistic: { method: 'evidence-present' } };
+                if (entry.passed !== true) {
+                    return { ...base, status: 'fail', reason: 'evidence-failed', statistic: { method: 'evidence-present' } };
+                }
+                if (entry.expiresAt !== undefined && entry.expiresAt !== null) {
+                    const expiry = Date.parse(entry.expiresAt);
+                    if (!Number.isFinite(expiry) || expiry <= nowMs) {
+                        return { ...base, status: 'fail', reason: 'evidence-expired', statistic: { method: 'evidence-present' } };
+                    }
+                }
+            }
+            return { ...base, status: 'pass', reason: 'evidence-present', statistic: { method: 'evidence-present' } };
+        }
+        case 'predicate': {
+            let value = 'unknown';
+            try {
+                value = evaluatePredicate(gate.predicate, { metrics, parameters, slices }, {});
+            }
+            catch {
+                value = 'unknown';
+            }
+            if (value === true)
+                return { ...base, status: 'pass', reason: 'predicate-true', statistic: { method: 'predicate' } };
+            if (value === false)
+                return { ...base, status: 'fail', reason: 'predicate-false', statistic: { method: 'predicate' } };
+            return { ...base, status: 'insufficient', reason: 'predicate-unknown', statistic: { method: 'predicate' } };
+        }
+        case 'upstream-ceiling': {
+            if (upstream === null)
+                return { ...base, status: 'insufficient', reason: 'upstream-missing',
+                    statistic: { method: 'upstream-integrity' } };
+            const problems = qualificationIntegrityAllowlistProblems(upstream.metadata);
+            if (!problems.length) {
+                return { ...base, status: 'pass', reason: 'upstream-clean', statistic: { method: 'upstream-integrity' } };
+            }
+            const compromised = problems.includes('compromised')
+                || upstream.metadata.release_gate?.decision === 'ROLLBACK'
+                || upstream.metadata.integrity_state === 'compromised';
+            return { ...base, status: 'fail', reason: compromised ? 'upstream-compromised' : 'upstream-allowlist',
+                statistic: { method: 'upstream-integrity' } };
+        }
+    }
+}
+function digestRecordsOrFail(records, providerId) {
+    try {
+        return artifactDigest(records);
+    }
+    catch {
+        return fail(`metric provider ${providerId} records are not digestible`);
+    }
+}
+function serializeRecordsOrFail(records, providerId) {
+    try {
+        const serialized = JSON.stringify(records);
+        if (typeof serialized !== 'string')
+            throw new Error('unserializable');
+        return serialized;
+    }
+    catch {
+        return fail(`metric provider ${providerId} records are not JSON-serializable`);
+    }
+}
+function rerunProviderOrFail(provider, args, providerId) {
+    // C2: execute only the registry's loader-issued provider. The runner makes
+    // its own copy of the loader-captured bytes, re-digests exactly the bytes it
+    // sends to the sandbox and refuses unless they match the pinned digest.
+    // Caller-supplied runtime objects (snapshot paths, digests) are never used.
+    if (!isLoaderIssuedProvider(provider)) {
+        return fail(`metric provider ${providerId} was not issued by the bundle loader: refusing to re-run it`);
+    }
+    try {
+        return runIsolatedProviderSync(provider, {
+            mode: 'invoke', recordsJson: args.recordsJson, clockMs: args.clockMs, seed: args.seed,
+            expectedCodeDigest: args.codeDigest,
+        }, { timeoutMs: args.timeoutMs, maxOutputBytes: GATE_PROVIDER_MAX_OUTPUT_BYTES }).result;
+    }
+    catch (error) {
+        return fail(`metric provider ${providerId} re-run failed: ${error instanceof Error ? error.message : 'unknown'}`);
+    }
+}
+function upstreamOutcome(upstream) {
+    if (upstream === null)
+        return { ceiling: 'HOLD', problems: ['upstream-ceiling-missing'] };
+    const problems = qualificationIntegrityAllowlistProblems(upstream.metadata);
+    const release = upstream.metadata.release_gate?.decision;
+    const compromised = problems.includes('compromised')
+        || release === 'ROLLBACK'
+        || upstream.metadata.integrity_state === 'compromised';
+    if (compromised)
+        return { ceiling: 'ROLLBACK', problems };
+    if (problems.length || release === 'HOLD')
+        return { ceiling: 'HOLD', problems };
+    return { ceiling: 'PROMOTE', problems };
+}
+/**
+ * Pure, deterministic gate evaluation. The binding is resolved internally
+ * against the registry: pack pins (authored + composed digests), provider pins
+ * and parameters are re-derived, so no caller-supplied resolution is accepted.
+ * Precondition violations (untrusted digests, provider pin mismatches,
+ * missing trusted holdout inputs, frozen-after-holdout bindings) throw before
+ * any gate runs, so failure paths never discard completed results. Per-gate
+ * shortfalls report `insufficient`, which never promotes.
+ *
+ * Interval levels are two-sided confidence levels applied to one-sided bounds:
+ * the reported bound is the one-sided edge of a two-sided interval, which is
+ * conservative (wider) relative to a one-sided interval at the same level.
+ */
+export function evaluateGates(input) {
+    const { binding, registry, trustedBindingDigest, holdout, metrics, upstream, now } = input;
+    if ('resolved' in input
+        && input.resolved !== undefined) {
+        fail('caller-supplied gate resolution is not accepted: pass the binding and registry');
+    }
+    if (!(registry instanceof GateRegistry))
+        fail('a GateRegistry is required for internal resolution');
+    if (input.floors === undefined) {
+        fail('project floors are required: pass resolveProjectFloors(config) or \'none-explicit-opt-out\' with a documented reason');
+    }
+    const floors = input.floors === 'none-explicit-opt-out' ? undefined : input.floors;
+    // Reserve before dispatch: resolve and fully validate the binding (pins,
+    // providers, parameters, slices) before any gate observes any metric. The
+    // resolution runs through the pure `resolveGateBinding` over a standalone
+    // snapshot of the registry's authored packs: no overridable `GateRegistry`
+    // instance method is called for anything security-relevant, so a subclass
+    // that overrides `resolveBinding` (or a duck-typed `{resolveBinding}`)
+    // cannot empty gates, loosen parameters or forge digests.
+    const resolved = resolveGateBinding(binding, authoredGatePacksOf(registry), gateProvidersOf(registry), floors);
+    const { packs, parameters } = resolved;
+    // 1:1 pins<->packs: the pin list and the resolved packs must match exactly.
+    if (packs.length !== binding.spec.packs.length)
+        fail('binding pins do not match resolved packs 1:1');
+    for (const pack of packs) {
+        // Recompute the authored digest: the stored pin is never trusted on its own.
+        if (artifactDigest(pack.authored) !== pack.digest) {
+            fail(`pack digest mismatch for ${pack.authored.metadata.id}`);
+        }
+        // Recompute the composed digest from the evaluator's own pure composition
+        // (`resolveGateBinding` above): registry-provided resolved bytes and
+        // digests are never trusted.
+        if (artifactDigest(pack.resolved) !== pack.resolvedDigest) {
+            fail(`composed pack digest mismatch for ${pack.authored.metadata.id}`);
+        }
+        const pin = binding.spec.packs.find(candidate => candidate.id === pack.authored.metadata.id);
+        if (pin === undefined || pin.version !== pack.authored.metadata.version
+            || pin.digest !== pack.digest || pin.resolvedDigest !== pack.resolvedDigest) {
+            fail(`pack pin mismatch for ${pack.authored.metadata.id}`);
+        }
+    }
+    // Every metric section consumed must be pinned; an unpinned section is
+    // refused rather than evaluated. Null version/digests never match. Bundle
+    // sections (#2831 rework) additionally carry the trusted code digest and
+    // the input-records digest sealed by the host: the section code digest must
+    // match the binding pin (verified above against the loaded provider), never
+    // a provider-declared field on its own. Sections covered by an isolated
+    // re-run are reproduced below and their caller-asserted values ignored, so
+    // a missing caller section is tolerated only with runtime coverage.
+    const runtimeById = new Map((input.providerRuntime?.providers ?? []).map(provider => [provider.id, provider]));
+    const runtimeCovers = (id) => runtimeById.has(id) && input.providerRuntime?.records[id] !== undefined;
+    for (const pin of binding.spec.metricProviders) {
+        const section = metrics.providers[pin.id];
+        if (section === undefined && runtimeCovers(pin.id))
+            continue;
+        if (section === undefined || section.version !== pin.version || section.sourceDigest !== pin.sourceDigest) {
+            fail(`metric provider pin mismatch for ${pin.id}`);
+        }
+        const pinnedCode = pin.codeDigest;
+        const sectionCode = section.codeDigest;
+        const sectionRecords = section.recordsDigest;
+        if (typeof pinnedCode === 'string') {
+            if (sectionCode !== pinnedCode)
+                fail(`metric provider pin mismatch for ${pin.id}`);
+            if (typeof sectionRecords !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(sectionRecords)) {
+                fail(`metric provider pin mismatch for ${pin.id}`);
+            }
+        }
+        else if (sectionCode !== undefined) {
+            fail(`metric provider pin mismatch for ${pin.id}`);
+        }
+    }
+    for (const id of Object.keys(metrics.providers)) {
+        if (!binding.spec.metricProviders.some(pin => pin.id === id)) {
+            fail(`metric provider ${id} is not pinned by the binding`);
+        }
+    }
+    if (upstream !== null && artifactDigest(upstream.metadata) !== upstream.digest) {
+        fail('upstream integrity digest does not match its report');
+    }
+    // Omitting the upstream record must never downgrade a bound ceiling to
+    // HOLD: when the resolved binding observes any upstream-ceiling gate
+    // (including the default floor's), evaluation without a sealed upstream is
+    // refused here in the evaluator, not just at the CLI.
+    if (upstream === null
+        && packs.some(pack => pack.resolved.spec.gates.some(gate => gate.kind === 'upstream-ceiling'))) {
+        fail('evaluation requires a sealed upstream record: the binding observes an upstream-ceiling gate');
+    }
+    const nowMs = Date.parse(now);
+    if (!Number.isFinite(nowMs))
+        fail('evaluation timestamp is not a valid date-time');
+    if (artifactDigest(binding) !== trustedBindingDigest)
+        fail('binding digest does not match its trusted pin');
+    // Holdout freeze is enforced from the REQUIRED sealed holdout record, never
+    // from binding fields (which the study author controls). The seal is
+    // re-derived here: `frozenDigest` and `firstAccessedAt` come only from a
+    // `sealGateHoldout` record whose digest matches its content.
+    if (holdout === undefined || holdout === null)
+        fail('trusted holdout inputs are required for evaluation');
+    const sealed = holdout;
+    if (typeof sealed.digest !== 'string'
+        || artifactDigest({ frozenDigest: sealed.frozenDigest, firstAccessedAt: sealed.firstAccessedAt }) !== sealed.digest) {
+        fail('holdout record seal does not match its content');
+    }
+    if (sealed.frozenDigest !== trustedBindingDigest)
+        fail('binding digest does not match the frozen record digest');
+    const frozenDigest = sealed.frozenDigest;
+    const firstAccessedAt = sealed.firstAccessedAt;
+    if (firstAccessedAt !== null && typeof firstAccessedAt !== 'string') {
+        fail('trusted holdout first-access time must be a date-time or null');
+    }
+    // Null access is allowed only when the binding declares no held-out split:
+    // a split binding with a null record would disable the freeze check.
+    const declaresSplit = binding.spec.splitDigest !== undefined
+        || binding.spec.corpusDigest !== undefined || binding.spec.goldDigest !== undefined;
+    if (firstAccessedAt === null && declaresSplit) {
+        fail('holdout record reports no access but the binding declares held-out data');
+    }
+    const frozenAt = Date.parse(binding.spec.frozenAt);
+    if (!Number.isFinite(frozenAt))
+        fail('binding freeze timestamp is not a valid date-time');
+    if (frozenAt > nowMs)
+        fail('binding freezes after the evaluation timestamp');
+    if (firstAccessedAt !== null) {
+        const accessedAt = Date.parse(firstAccessedAt);
+        if (!Number.isFinite(accessedAt))
+            fail('holdout access timestamp is not a valid date-time');
+        if (frozenAt >= accessedAt)
+            fail('binding froze at or after holdout access: evaluation refused');
+        if (accessedAt > nowMs)
+            fail('holdout access timestamp is after the evaluation timestamp');
+    }
+    // Records binding (P4): every bundle-provider pin is reproduced by an
+    // isolated re-run of the pinned provider over records digesting to the
+    // pin's records digest, and the re-run output replaces the caller-asserted
+    // section. Without runtime coverage the section cannot be reproduced and
+    // evaluation refuses (fail closed, including the file path).
+    const effectiveProviders = { ...metrics.providers };
+    for (const pin of binding.spec.metricProviders) {
+        const pinnedCode = pin.codeDigest;
+        if (typeof pinnedCode !== 'string')
+            continue;
+        const pinnedRecords = pin.recordsDigest;
+        const snapshot = runtimeById.get(pin.id) ?? fail(`metric provider ${pin.id} requires an isolated re-run`
+            + ' over its pinned records: caller-asserted metrics cannot reproduce provider output');
+        const records = input.providerRuntime?.records[pin.id] ?? fail(`metric provider ${pin.id} requires an isolated re-run`
+            + ' over its pinned records: caller-asserted metrics cannot reproduce provider output');
+        const registered = gateProvidersOf(registry).get(pin.id);
+        if (registered.version !== pin.version || registered.sourceDigest !== pin.sourceDigest
+            || registered.codeDigest !== pinnedCode
+            || snapshot.version !== pin.version || snapshot.sourceDigest !== pin.sourceDigest
+            || snapshot.codeDigest !== pinnedCode) {
+            fail(`metric provider pin mismatch for ${pin.id}`);
+        }
+        if (!Array.isArray(records))
+            fail(`metric provider ${pin.id} records must be an array`);
+        const actualRecordsDigest = digestRecordsOrFail(records, pin.id);
+        if (actualRecordsDigest !== pinnedRecords) {
+            fail(`metric provider ${pin.id} records do not match the pinned records digest`);
+        }
+        const recordsJson = serializeRecordsOrFail(records, pin.id);
+        const reproduced = rerunProviderOrFail(registered, {
+            recordsJson, clockMs: nowMs, seed: deriveIsolatedSeed(pinnedCode, pinnedRecords),
+            timeoutMs: input.providerRuntime?.timeoutMs ?? GATE_PROVIDER_DEFAULT_TIMEOUT_MS,
+            codeDigest: pinnedCode,
+        }, pin.id);
+        try {
+            effectiveProviders[pin.id] = sealProviderSection(registered, records, reproduced);
+        }
+        catch (error) {
+            fail(`metric provider ${pin.id} re-run failed: ${error instanceof Error ? error.message : 'unknown'}`);
+        }
+    }
+    const effectiveMetrics = { ...metrics, providers: effectiveProviders };
+    const gateEvidence = [];
+    for (const pack of packs) {
+        for (const gate of pack.resolved.spec.gates) {
+            const kind = metricKindOf(gate, pack);
+            const series = seriesFor(gate, pack, effectiveMetrics);
+            const targets = gate.kind === 'upstream-ceiling' || gate.kind === 'predicate'
+                ? [{ slice: null, observation: null }]
+                : expandScope(gate, kind, series, binding.spec.slices);
+            if (!targets.length) {
+                // Unreachable through resolveBinding (vacuous scopes are load errors),
+                // but a zero-target gate must never PROMOTE vacuously.
+                gateEvidence.push({
+                    gateId: gate.id, kind: gate.kind,
+                    scope: { mode: gate.scope.mode, ...(gate.scope.slices === undefined ? {} : { slices: [...gate.scope.slices] }) },
+                    slice: null, n: null, status: 'insufficient', outcome: gate.onInsufficient ?? 'HOLD',
+                    reasons: [`${gate.id}:no-evaluation-targets`],
+                });
+                continue;
+            }
+            for (const target of targets) {
+                const evaluation = evaluateObservation(gate, target.observation, { packId: pack.authored.metadata.id, parameters, metrics: effectiveMetrics, upstream, nowMs,
+                    slice: target.slice, slices: binding.spec.slices });
+                // Upstream-ceiling gates mirror the upstream verdict exactly: compromise
+                // rolls back, allowlist problems hold, clean promotes. The gate's own
+                // onFail never escalates (or softens) the trusted verdict.
+                const outcome = gate.kind === 'upstream-ceiling' && evaluation.status === 'fail'
+                    ? upstreamOutcome(upstream).ceiling
+                    : gateStatusOutcome(evaluation.status, gate);
+                gateEvidence.push({
+                    gateId: gate.id, kind: gate.kind,
+                    scope: { mode: gate.scope.mode, ...(gate.scope.slices === undefined ? {} : { slices: [...gate.scope.slices] }) },
+                    slice: evaluation.slice, n: evaluation.n,
+                    ...(evaluation.events === undefined ? {} : { events: evaluation.events }),
+                    ...(evaluation.statistic === undefined ? {} : { statistic: evaluation.statistic }),
+                    ...(evaluation.threshold === undefined ? {} : { threshold: evaluation.threshold }),
+                    status: evaluation.status,
+                    outcome,
+                    reasons: [`${gate.id}:${evaluation.reason}`],
+                });
+            }
+        }
+    }
+    const packOutcome = maxOutcome(...gateEvidence.map(entry => entry.outcome));
+    const { ceiling: upstreamCeiling, problems: upstreamProblems } = upstreamOutcome(upstream);
+    const bindingCeiling = binding.spec.ceiling ?? 'PROMOTE';
+    const decision = maxOutcome(packOutcome, upstreamCeiling, bindingCeiling);
+    const body = {
+        apiVersion: binding.apiVersion,
+        kind: 'GateReport',
+        metadata: { id: binding.metadata.id, version: binding.metadata.version,
+            description: `GateReport for ${binding.metadata.id}` },
+        binding: { id: binding.metadata.id, version: binding.metadata.version, digest: trustedBindingDigest },
+        packs: packs.map(pack => ({ id: pack.authored.metadata.id, version: pack.authored.metadata.version,
+            digest: pack.digest, resolvedDigest: pack.resolvedDigest })),
+        metricProviders: binding.spec.metricProviders.map(pin => ({ ...pin })),
+        metricsDigest: artifactDigest(effectiveMetrics),
+        floors: input.floors === 'none-explicit-opt-out'
+            ? { mode: 'opt-out' }
+            : { mode: 'applied', digest: artifactDigest(input.floors) },
+        holdout: { digest: sealed.digest, frozenDigest, firstAccessedAt },
+        gateEvidence,
+        references: binding.spec.references.map(reference => ({
+            name: reference.name, kind: reference.kind, observed: effectiveMetrics.references?.[reference.name] !== undefined,
+        })),
+        upstream: upstream === null ? null : {
+            decision: upstreamCeiling,
+            reasons: upstreamProblems.map(problem => `upstream:${problem}`),
+            digest: upstream.digest,
+        },
+        ceilings: { packOutcome, upstreamCeiling, bindingCeiling },
+        decision,
+        evaluatedAt: now,
+        ...(input.attestation === undefined ? {} : { attestation: input.attestation }),
+    };
+    return { ...body, digest: artifactDigest(body) };
+}
+//# sourceMappingURL=evaluate.js.map