@aiwg/cli 2026.9.24 → 2026.10.1

package/dist/src/decision/context-pruning.js

@@ -0,0 +1,847 @@
+import { ContextBudgetManager } from '../metrics/context-budget.js';
+import { sha256 } from './compile-cache/identity.js';
+import { admitEntry } from './entry.js';
+import { PairedDifferenceError, pairedBinaryDifferenceInterval, pairedMeanDifferenceBootstrap, pairedNonInferiority, } from './qualification/quality.js';
+export const CONTEXT_PRUNING_PROTECTED_POLICY_VERSION = 'decision-context-protected/v1';
+export const CONTEXT_PRUNING_CANDIDATE_SCHEMA = 'decision-context-candidate/v1';
+export const CONTEXT_PRUNING_RECEIPT_SCHEMA = 'decision-context-pruning-receipt/v1';
+export const CONTEXT_PRUNING_PREREGISTRATION_SCHEMA = 'decision-context-pruning-preregistration/v1';
+export const CONTEXT_PRUNING_EVALUATION_REPORT_SCHEMA = 'decision-context-pruning-evaluation-report/v1';
+/**
+ * Clock-skew allowance for `holdoutAccessedAt` attestations: the recorder that stamps holdout access and the
+ * evaluator that builds the report may disagree by up to five minutes. An attestation later than the
+ * evaluation clock plus this allowance is a future attestation and is rejected.
+ */
+export const CONTEXT_PRUNING_HOLDOUT_CLOCK_SKEW_MS = 5 * 60 * 1_000;
+export const CONTEXT_PRUNING_QUALITY_METRICS = [
+    'downstream-task-success',
+    'requirement-coverage',
+    'factual-coverage',
+    'citation-accuracy',
+    'human-preference',
+];
+export class ContextPruningError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'ContextPruningError';
+    }
+}
+const SHA = /^sha256:[0-9a-f]{64}$/;
+const SOURCE_TO_REASON = {
+    system: 'system-rule',
+    developer: 'developer-rule',
+    project: 'project-rule',
+    'security-policy': 'security-policy',
+    user: 'current-user-requirement',
+    approval: 'action-approval',
+    blocker: 'unresolved-blocker',
+    provenance: 'provenance-required',
+    citation: 'citation-required',
+    artifact: 'artifact-pin',
+    'test-evidence': 'test-gate-evidence',
+    'open-decision': 'open-decision-evidence',
+};
+const VALID_SOURCE_KINDS = new Set([
+    'system', 'developer', 'project', 'security-policy', 'user', 'approval', 'blocker',
+    'provenance', 'citation', 'artifact', 'test-evidence', 'open-decision', 'retrieved',
+    'memory', 'tool-output', 'ordinary',
+]);
+const VALID_PROTECTED_REASONS = new Set([
+    'system-rule', 'developer-rule', 'project-rule', 'security-policy', 'current-user-requirement',
+    'explicit-mention', 'unresolved-blocker', 'action-approval', 'artifact-pin', 'version-pin',
+    'digest-pin', 'provenance-required', 'citation-required', 'test-gate-evidence',
+    'open-decision-evidence', 'protected-dependency', 'external-evaluation-denied', 'local-only',
+    'restricted-data', 'legal-policy',
+]);
+export function contextPruningDigest(value) {
+    return sha256(value);
+}
+/** Order-independent digest of the frozen evaluation pairs: sorted (pairId, slice) tuples. */
+export function contextPruningPairSetDigest(pairs) {
+    const tuples = pairs.map(pair => [pair.pairId, pair.slice])
+        .sort(([a, sa], [b, sb]) => a < b ? -1 : a > b ? 1 : sa < sb ? -1 : sa > sb ? 1 : 0);
+    return contextPruningDigest({ schemaVersion: 'decision-context-pruning-pair-set/v1', pairs: tuples });
+}
+/** Identity of one pilot run over an ordered candidate set, optionally tied to an evaluation pair. */
+export function contextPruningRunId(pairId, candidates) {
+    return contextPruningDigest({
+        schemaVersion: 'decision-context-pruning-run-id/v1',
+        pairId,
+        candidates: candidates.map(candidate => contextPruningDigest(candidate)),
+    });
+}
+/** Order-independent digest of a receipt set, for anchoring the evaluated receipts separately from the report. */
+export function contextPruningReceiptSetDigest(receipts) {
+    return contextPruningDigest({
+        schemaVersion: 'decision-context-pruning-receipt-set/v1',
+        receipts: receipts.map(receipt => receipt.receiptDigest).sort(),
+    });
+}
+export function classifyContextPruningCandidate(candidate) {
+    validateContextPruningCandidate(candidate);
+    const reasons = new Set();
+    const mapped = SOURCE_TO_REASON[candidate.source.kind];
+    if (mapped)
+        reasons.add(mapped);
+    for (const hint of candidate.protectedHints)
+        reasons.add(hint);
+    if (candidate.dataPolicy.externalEvaluation === 'denied')
+        reasons.add('external-evaluation-denied');
+    if (candidate.dataPolicy.localOnly)
+        reasons.add('local-only');
+    if (candidate.dataPolicy.legalAction === 'requires-review')
+        reasons.add('legal-policy');
+    if (candidate.sensitivity === 'restricted')
+        reasons.add('restricted-data');
+    const sorted = [...reasons].sort();
+    const policy = {
+        version: CONTEXT_PRUNING_PROTECTED_POLICY_VERSION,
+        sourceRules: SOURCE_TO_REASON,
+        dataPolicy: ['externalEvaluation', 'localOnly', 'legalAction'],
+        sensitivity: ['restricted'],
+        protectedHints: [...VALID_PROTECTED_REASONS].sort(),
+    };
+    return {
+        schemaVersion: CONTEXT_PRUNING_PROTECTED_POLICY_VERSION,
+        itemId: candidate.itemId,
+        protected: sorted.length > 0,
+        reasons: sorted,
+        policyDigest: contextPruningDigest(policy),
+    };
+}
+export function classifyContextPruningCandidates(candidates) {
+    const byId = uniqueCandidates(candidates);
+    const classifications = new Map();
+    for (const candidate of candidates)
+        classifications.set(candidate.itemId, classifyContextPruningCandidate(candidate));
+    const protectedQueue = candidates.filter(candidate => classifications.get(candidate.itemId).protected)
+        .map(candidate => candidate.itemId);
+    for (let index = 0; index < protectedQueue.length; index++) {
+        const item = byId.get(protectedQueue[index]);
+        for (const dependencyId of item.dependencies) {
+            const dependency = byId.get(dependencyId);
+            if (!dependency)
+                throw new ContextPruningError(`unknown context dependency '${dependencyId}'`, 'semantic');
+            const current = classifications.get(dependencyId);
+            if (current.reasons.includes('protected-dependency'))
+                continue;
+            classifications.set(dependencyId, {
+                ...current,
+                protected: true,
+                reasons: [...new Set([...current.reasons, 'protected-dependency'])].sort(),
+            });
+            protectedQueue.push(dependencyId);
+        }
+    }
+    return classifications;
+}
+export function planContextPruningEvaluations(candidates, questions) {
+    return planContextPruningEvaluationRun(candidates, questions).jobs;
+}
+export function planContextPruningEvaluationRun(candidates, questions) {
+    const byId = uniqueCandidates(candidates);
+    const classifications = classifyContextPruningCandidates(candidates);
+    const exclusions = [...classifications.values()]
+        .filter(classification => classification.protected)
+        .map(classification => ({ itemId: classification.itemId, reasons: [...classification.reasons].sort() }));
+    const excluded = new Set(exclusions.map(item => item.itemId));
+    const groups = new Map();
+    for (const question of questions) {
+        if (!question.id || !question.itemId || !question.subject || !['relevance', 'disposition', 'omission-risk'].includes(question.kind)) {
+            throw new ContextPruningError('invalid context pruning question', 'schema');
+        }
+        const candidate = byId.get(question.itemId);
+        if (!candidate)
+            throw new ContextPruningError(`unknown context item '${question.itemId}'`, 'semantic');
+        if (excluded.has(candidate.itemId))
+            continue;
+        const subject = pruningSubject(candidate);
+        if (question.subject !== subject)
+            throw new ContextPruningError('question subject must be the context item subject', 'semantic');
+        const key = `${question.itemId}\0${question.batchKey ?? 'default'}`;
+        const group = groups.get(key) ?? [];
+        group.push(question);
+        groups.set(key, group);
+    }
+    const jobs = [...groups.entries()].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([, group]) => {
+        const candidate = byId.get(group[0].itemId);
+        const subject = pruningSubject(candidate);
+        if (group.some(question => question.itemId !== candidate.itemId || question.subject !== subject)) {
+            throw new ContextPruningError('unrelated context chunks cannot share a native batch', 'semantic');
+        }
+        return {
+            subject,
+            itemId: candidate.itemId,
+            state: { candidateDigest: contextPruningDigest(candidate), itemId: candidate.itemId, locator: candidate.locator },
+            questions: [...group].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+            contextQuestion: {
+                id: `context-pruning:${candidate.itemId}:${group[0].batchKey ?? 'default'}`,
+                subject,
+                compatibilityKey: `context-pruning:${candidate.itemId}:${group[0].batchKey ?? 'default'}`,
+                entry: { candidateDigest: contextPruningDigest(candidate), questions: group.map(question => question.kind).sort() },
+            },
+        };
+    });
+    return { jobs, exclusions };
+}
+export function applyContextPruningPilot(input) {
+    validatePolicy(input.policy);
+    if (input.pairId !== undefined && (typeof input.pairId !== 'string' || !input.pairId)) {
+        throw new ContextPruningError('pairId must be a non-empty string', 'invalid-input');
+    }
+    const pairId = input.pairId ?? null;
+    const now = input.now ?? (() => new Date().toISOString());
+    const baseline = input.candidates.map(candidate => candidate.itemId);
+    const evidence = new Map((input.evidence ?? []).map(item => [item.itemId, item]));
+    const disabledReason = input.monitoringRegression ? 'drift-or-monitoring-regression'
+        : input.policy.mode === 'disabled' ? 'configured-disabled' : null;
+    const mode = disabledReason ? 'deterministic-fallback' : input.policy.mode;
+    const classifications = classifyContextPruningCandidates(input.candidates);
+    const runId = contextPruningRunId(pairId, input.candidates);
+    const deterministicBaseline = input.budget === undefined ? null
+        : computeContextBudgetManagerBaseline(input.candidates, input.budget);
+    const deterministicDrops = new Set(deterministicBaseline?.droppedItemIds ?? []);
+    const receipts = input.candidates.map(candidate => {
+        validateContextPruningCandidate(candidate);
+        const classification = classifications.get(candidate.itemId);
+        const itemEvidence = evidence.get(candidate.itemId);
+        const fallbackAction = deterministicDrops.has(candidate.itemId) ? 'drop' : 'keep';
+        const decision = decideContextAction(candidate, classification, input.policy, itemEvidence, disabledReason, fallbackAction);
+        return buildContextPruningReceipt(candidate, classification, decision, now(), runId, pairId);
+    });
+    return {
+        schemaVersion: 'decision-context-pruning-run/v1',
+        runId,
+        pairId,
+        mode,
+        baselineItemIds: baseline,
+        // A distinct array: callers that mutate one list cannot silently alter the other.
+        downstreamItemIds: [...baseline],
+        receipts,
+        disabledReason,
+        deterministicBaseline,
+    };
+}
+/**
+ * Validates a receipt's shape and self-digest. When the run's candidate envelopes are supplied, it also
+ * re-derives the run identity and the protected-item classification and refuses any mismatch, so a
+ * relabelled receipt with a recomputed digest, or a receipt from another run, is rejected.
+ */
+export function validateContextPruningReceipt(receipt, candidates) {
+    requirePlain(receipt, 'receipt');
+    if (receipt.schemaVersion !== CONTEXT_PRUNING_RECEIPT_SCHEMA || !receipt.itemId || !receipt.locator
+        || typeof receipt.runId !== 'string' || !SHA.test(receipt.runId)
+        || !(receipt.pairId === null || (typeof receipt.pairId === 'string' && receipt.pairId))
+        || !SHA.test(receipt.originalDigest) || !Number.isSafeInteger(receipt.originalTokenEstimate) || receipt.originalTokenEstimate < 0
+        || !['keep', 'drop', 'truncate', 'summarize'].includes(receipt.proposedAction)
+        || !['keep', 'drop', 'truncate', 'summarize'].includes(receipt.appliedAction)
+        || !(receipt.decisionReceiptDigest === null || SHA.test(receipt.decisionReceiptDigest))
+        || !receipt.reversibleReference || receipt.reversibleReference.originalDigest !== receipt.originalDigest
+        || !receipt.reversibleReference.locator || !receipt.reversibleReference.restorationPath
+        || !SHA.test(receipt.receiptDigest)) {
+        throw new ContextPruningError('invalid pruning receipt', 'schema');
+    }
+    if ((receipt.proposedAction === 'truncate' || receipt.proposedAction === 'summarize')
+        && receipt.reason === 'accepted-evidence' && receipt.reversibleReference.transformation === null) {
+        throw new ContextPruningError('transformed receipts require a reversible artifact reference', 'semantic');
+    }
+    if (receipt.reversibleReference.transformation !== null
+        && receipt.reversibleReference.transformation.sourceDigest !== receipt.originalDigest) {
+        throw new ContextPruningError('transformation source digest must match the original context item', 'semantic');
+    }
+    const { receiptDigest, ...payload } = receipt;
+    if (receiptDigest !== contextPruningDigest(payload))
+        throw new ContextPruningError('pruning receipt digest mismatch', 'semantic');
+    if (candidates !== undefined) {
+        const candidate = candidates.find(item => item.itemId === receipt.itemId);
+        if (!candidate || receipt.runId !== contextPruningRunId(receipt.pairId, candidates)
+            || receipt.originalDigest !== candidate.contentDigest || receipt.locator !== candidate.locator
+            || receipt.originalTokenEstimate !== candidate.tokenEstimate) {
+            throw new ContextPruningError('pruning receipt is not bound to the evaluated run', 'semantic');
+        }
+        const derived = classifyContextPruningCandidates(candidates).get(candidate.itemId);
+        if (contextPruningDigest(derived) !== contextPruningDigest(receipt.classification)) {
+            throw new ContextPruningError('pruning receipt classification does not match the candidate envelope', 'semantic');
+        }
+        // A protected item is never proposed for, or subjected to, a destructive action by this pilot.
+        if (derived.protected && (receipt.proposedAction !== 'keep' || receipt.appliedAction !== 'keep')) {
+            throw new ContextPruningError('pruning receipt classification does not match its protected action', 'semantic');
+        }
+    }
+    return receipt;
+}
+export function createContextPruningPreregistration(input) {
+    const payload = { schemaVersion: CONTEXT_PRUNING_PREREGISTRATION_SCHEMA, ...input };
+    return validateContextPruningPreregistration({ ...payload, digest: contextPruningDigest(payload) });
+}
+export function validateContextPruningPreregistration(value) {
+    requirePlain(value, 'preregistration');
+    const t = value.thresholds;
+    const ci = t?.confidenceInterval;
+    const metrics = Array.isArray(t?.qualityMetrics) ? t.qualityMetrics : [];
+    const slices = Array.isArray(t?.slices) ? t.slices : [];
+    const bootstrapTail = ci && Number.isSafeInteger(ci.bootstrapResamples) && Number.isSafeInteger(ci.levelBps)
+        ? Math.floor(ci.bootstrapResamples * (10_000 - ci.levelBps) / 20_000) : 0;
+    if (value.schemaVersion !== CONTEXT_PRUNING_PREREGISTRATION_SCHEMA || !value.id
+        || !Number.isFinite(Date.parse(value.registeredAt))
+        || typeof value.pairSetDigest !== 'string' || !SHA.test(value.pairSetDigest)
+        || !t || t.protectedRetentionBps !== 10_000 || !ci
+        // pairedBinaryDifferenceInterval accepts only levels strictly between 5000 and 9999.
+        || !Number.isSafeInteger(ci.levelBps) || ci.levelBps <= 5_000 || ci.levelBps >= 9_999
+        || !['newcombe-10', 'tango'].includes(ci.binaryMethod) || ci.boundedMethod !== 'percentile-bootstrap'
+        || !Number.isSafeInteger(ci.bootstrapSeed) || ci.bootstrapSeed < 0 || ci.bootstrapSeed > 0xffff_ffff
+        || !Number.isSafeInteger(ci.bootstrapResamples) || ci.bootstrapResamples > 1_000_000 || bootstrapTail < 5
+        || metrics.length !== CONTEXT_PRUNING_QUALITY_METRICS.length
+        || new Set(metrics.map(item => item?.metric)).size !== metrics.length
+        || metrics.some(item => !CONTEXT_PRUNING_QUALITY_METRICS.includes(item?.metric) || !['binary', 'bounded'].includes(item.scale))
+        || slices.length === 0 || new Set(slices).size !== slices.length
+        || slices.some(slice => typeof slice !== 'string' || !slice.trim())
+        || !Number.isSafeInteger(t.minimumOverallN) || t.minimumOverallN < 2
+        || !Number.isSafeInteger(t.minimumSliceN) || t.minimumSliceN < 1
+        || !Number.isSafeInteger(t.minimumZeroVarianceN) || t.minimumZeroVarianceN < 2
+        || !Number.isSafeInteger(t.minimumProtectedN) || t.minimumProtectedN < 2
+        || (t.powerRule !== null && (typeof t.powerRule !== 'string' || !t.powerRule.trim()))
+        || !Number.isSafeInteger(t.qualityNonInferiorityMarginBps) || t.qualityNonInferiorityMarginBps > 0
+        || t.qualityNonInferiorityMarginBps < -10_000
+        || !Number.isSafeInteger(t.positiveTotalTokenTarget) || t.positiveTotalTokenTarget <= 0
+        || !Number.isFinite(t.positiveTotalCostTargetUsd) || t.positiveTotalCostTargetUsd <= 0) {
+        throw new ContextPruningError('invalid context pruning preregistration', 'schema');
+    }
+    const { digest, ...payload } = value;
+    if (digest !== contextPruningDigest(payload))
+        throw new ContextPruningError('preregistration digest mismatch', 'semantic');
+    return value;
+}
+/**
+ * Builds the paired evaluation report. `trustedPreregistrationDigest` must come from a separately anchored
+ * record made before holdout access (as evaluatePreregisteredBinaryBenchmark requires): a caller-created
+ * preregistration cannot attest itself. A report without a recorded holdout access time cannot PROMOTE.
+ * A holdout access attested later than the evaluation clock plus CONTEXT_PRUNING_HOLDOUT_CLOCK_SKEW_MS
+ * is rejected as a future attestation.
+ */
+export function buildContextPruningEvaluationReport(input) {
+    const preregistration = validateContextPruningPreregistration(input.preregistration);
+    if (typeof input.trustedPreregistrationDigest !== 'string' || !SHA.test(input.trustedPreregistrationDigest)
+        || preregistration.digest !== input.trustedPreregistrationDigest) {
+        throw new ContextPruningError('preregistration is not anchored to the trusted digest', 'semantic');
+    }
+    const holdoutAccessedAt = input.holdoutAccessedAt;
+    const holdoutAtMs = holdoutAccessedAt === null ? NaN : Date.parse(holdoutAccessedAt);
+    if (holdoutAccessedAt !== null && (typeof holdoutAccessedAt !== 'string' || !Number.isFinite(holdoutAtMs)
+        || holdoutAtMs <= Date.parse(preregistration.registeredAt))) {
+        throw new ContextPruningError('holdout access must be recorded after preregistration', 'semantic');
+    }
+    if (Number.isFinite(holdoutAtMs)) {
+        const evaluationNowMs = (input.evaluationNow ?? Date.now)();
+        // Fail closed: an unknown evaluation time cannot vouch for the attestation.
+        if (!Number.isFinite(evaluationNowMs) || holdoutAtMs - evaluationNowMs > CONTEXT_PRUNING_HOLDOUT_CLOCK_SKEW_MS) {
+            throw new ContextPruningError('future holdout access attestation is rejected', 'semantic');
+        }
+    }
+    validateIntegrity(input.integrity);
+    const thresholds = preregistration.thresholds;
+    validateMetrics(input.metrics, preregistration);
+    const metrics = input.metrics;
+    if (contextPruningPairSetDigest(metrics.pairs) !== preregistration.pairSetDigest) {
+        throw new ContextPruningError('evaluated pair set does not match the preregistered pair set', 'semantic');
+    }
+    const findings = new Set();
+    const missing = new Set(input.missingInputs ?? []);
+    if (holdoutAccessedAt === null)
+        findings.add('holdout-access-unrecorded');
+    const sliceSupport = Object.fromEntries(thresholds.slices.map(slice => [slice, 0]));
+    for (const pair of metrics.pairs)
+        sliceSupport[pair.slice] += 1;
+    if (metrics.pairs.length < thresholds.minimumOverallN)
+        findings.add('insufficient-overall-sample');
+    for (const slice of thresholds.slices) {
+        if (sliceSupport[slice] < thresholds.minimumSliceN)
+            findings.add(`insufficient-slice:${slice}`);
+    }
+    const protectedRetention = deriveProtectedRetention(input.pruningRuns, metrics.pairs, input.trustedReceiptSetDigest);
+    if (protectedRetention.bps === null)
+        findings.add('insufficient-protected-receipts');
+    else if (protectedRetention.bps !== metrics.protectedRetentionBps) {
+        throw new ContextPruningError('protected retention does not reconcile with the pruning receipts', 'semantic');
+    }
+    if (metrics.protectedRetentionBps < 10_000 || (protectedRetention.bps !== null && protectedRetention.bps < 10_000)) {
+        findings.add('protected-retention-breach');
+    }
+    // A full retention rate on too few protected items is not evidence: the count comes from validated receipts.
+    if (protectedRetention.protectedItems < thresholds.minimumProtectedN)
+        findings.add('insufficient-protected-sample');
+    const quality = thresholds.qualityMetrics.map(({ metric, scale }) => evaluateQualityMetric(metric, scale, metrics.quality.find(item => item.metric === metric), metrics.pairs, preregistration));
+    for (const result of quality) {
+        for (const slice of thresholds.slices) {
+            if (result.sliceSupport[slice] < thresholds.minimumSliceN)
+                findings.add(`insufficient-quality-slice:${result.metric}:${slice}`);
+        }
+        if (result.missingPairs > 0)
+            findings.add(`quality-outcomes-incomplete:${result.metric}`);
+        if (result.decision === 'not-non-inferior') {
+            findings.add('quality-non-inferiority-failed');
+            findings.add(`quality-non-inferiority-failed:${result.metric}`);
+            if (result.harm) {
+                findings.add('quality-harm');
+                findings.add(`quality-harm:${result.metric}`);
+            }
+            else {
+                findings.add(`quality-non-inferiority-inconclusive:${result.metric}`);
+            }
+        }
+        else if (result.decision === 'insufficient' && result.n === 0) {
+            findings.add(`quality-metric-missing:${result.metric}`);
+        }
+        else if (result.decision === 'insufficient' && result.n < thresholds.minimumOverallN) {
+            findings.add(`insufficient-quality-sample:${result.metric}`);
+        }
+        else if (result.decision === 'insufficient' && result.missingPairs === 0 && result.scale === 'bounded'
+            && result.interval !== null && result.interval.lowerBps === result.interval.upperBps
+            && result.n < thresholds.minimumZeroVarianceN) {
+            // A conclusive-sized read withheld for lack of variability evidence: a zero-width bounded
+            // interval below the preregistered zero-variance support.
+            findings.add(`insufficient-quality-support:${result.metric}`);
+        }
+        else if (result.decision === 'insufficient') {
+            // Interval construction failed, the verdict was unreadable, or a passing
+            // verdict was withheld for omitted pairs: adequate n is not evidence.
+            findings.add(`insufficient-quality-evidence:${result.metric}`);
+        }
+    }
+    const providerSavings = providerUsageSavings(metrics.providerUsage);
+    const estimatorSavings = { totalTokens: totalSavings(metrics.estimatorUsage, 'total') };
+    if (providerSavings.totalTokens < 0 || providerSavings.uncachedTokens < 0
+        || (providerSavings.costUsd !== null && providerSavings.costUsd < 0)) {
+        findings.add('negative-net-economics');
+    }
+    if (providerSavings.totalTokens < thresholds.positiveTotalTokenTarget
+        || providerSavings.uncachedTokens < thresholds.positiveTotalTokenTarget)
+        findings.add('provider-token-target-not-met');
+    if (estimatorSavings.totalTokens < thresholds.positiveTotalTokenTarget)
+        findings.add('estimator-token-target-not-met');
+    if (providerSavings.costUsd === null)
+        findings.add('provider-cost-unknown');
+    else if (providerSavings.costUsd < thresholds.positiveTotalCostTargetUsd)
+        findings.add('provider-cost-target-not-met');
+    if (input.integrity.integrity_state !== 'verified')
+        findings.add('integrity-not-verified');
+    const upstreamDecision = input.integrity.release_gate.decision;
+    if (upstreamDecision === 'ROLLBACK')
+        findings.add('upstream-rollback');
+    if (upstreamDecision === 'HOLD')
+        findings.add('upstream-hold');
+    for (const name of missing)
+        findings.add(`missing-input:${name}`);
+    // Automatic rollback triggers from the D26 rollout plan: protected miss, demonstrated quality harm, negative
+    // economics. An inconclusive non-inferiority result (no evidence of harm) holds instead.
+    const rollback = upstreamDecision === 'ROLLBACK' || findings.has('protected-retention-breach')
+        || findings.has('quality-harm') || findings.has('negative-net-economics');
+    const decision = rollback ? 'ROLLBACK' : upstreamDecision === 'HOLD' || findings.size > 0 ? 'HOLD' : 'PROMOTE';
+    const advisory = [...findings].some(item => item.startsWith('insufficient-') || item.startsWith('quality-metric-missing:')
+        || item.startsWith('missing-input:') || item.startsWith('quality-outcomes-incomplete:')
+        || item.startsWith('quality-non-inferiority-inconclusive:')
+        || item === 'holdout-access-unrecorded' || item === 'provider-cost-unknown')
+        ? 'INSUFFICIENT EVIDENCE' : null;
+    const payload = {
+        schemaVersion: CONTEXT_PRUNING_EVALUATION_REPORT_SCHEMA,
+        preregistration,
+        holdoutAccessedAt,
+        integrity: input.integrity,
+        metrics,
+        derived: { sampleN: metrics.pairs.length, sliceSupport, quality, providerSavings, estimatorSavings, protectedRetention },
+        missingInputs: [...missing].sort(),
+        findings: [...findings].sort(),
+        upstreamDecision,
+        decision,
+        advisory,
+    };
+    return { ...payload, digest: contextPruningDigest(payload) };
+}
+function evaluateQualityMetric(metric, scale, outcomes, recordedPairs, preregistration) {
+    const { confidenceInterval: ci, minimumOverallN, minimumZeroVarianceN, qualityNonInferiorityMarginBps, slices } = preregistration.thresholds;
+    const pairs = outcomes?.pairs ?? [];
+    const sliceOf = new Map(recordedPairs.map(pair => [pair.pairId, pair.slice]));
+    const sliceSupport = Object.fromEntries(slices.map(slice => [slice, 0]));
+    for (const pair of pairs)
+        sliceSupport[sliceOf.get(pair.pairId)] += 1;
+    // validateMetrics guarantees outcome pair IDs are a unique subset of the recorded pairs.
+    const missingPairs = recordedPairs.length - pairs.length;
+    const result = (interval, decision) => ({
+        metric, scale, n: pairs.length, missingPairs,
+        harm: decision === 'not-non-inferior' && interval !== null
+            && (interval.upperBps < 0 || interval.estimateBps < qualityNonInferiorityMarginBps),
+        sliceSupport, interval, decision,
+    });
+    if (pairs.length < minimumOverallN)
+        return result(null, 'insufficient');
+    let interval;
+    try {
+        if (scale === 'binary') {
+            const counts = { both: 0, candidateOnly: 0, baselineOnly: 0, neither: 0 };
+            for (const pair of pairs) {
+                if (pair.candidate === 1 && pair.baseline === 1)
+                    counts.both++;
+                else if (pair.candidate === 1)
+                    counts.candidateOnly++;
+                else if (pair.baseline === 1)
+                    counts.baselineOnly++;
+                else
+                    counts.neither++;
+            }
+            interval = pairedBinaryDifferenceInterval({ counts, levelBps: ci.levelBps, method: ci.binaryMethod });
+        }
+        else {
+            interval = pairedMeanDifferenceBootstrap({
+                differences: pairs.map(pair => pair.candidate - pair.baseline), levelBps: ci.levelBps,
+                seed: ci.bootstrapSeed, resamples: ci.bootstrapResamples, bounds: [-1, 1],
+            });
+        }
+    }
+    catch (error) {
+        if (error instanceof PairedDifferenceError)
+            return result(null, 'insufficient');
+        throw error;
+    }
+    const verdict = pairedNonInferiority({ interval, marginBps: qualityNonInferiorityMarginBps });
+    // A regression visible in the reported outcomes still fails; omitted pairs can only withhold a pass.
+    if (verdict.decision === 'non-inferior' && missingPairs > 0)
+        return result(interval, 'insufficient');
+    // A zero-width bounded interval carries no variability evidence: identical pairs at a small n are
+    // inconclusive, so a would-be pass needs the preregistered zero-variance support first. Only passes
+    // are withheld here; demonstrated harm still rolls back through the verdict below.
+    if (verdict.decision === 'non-inferior' && scale === 'bounded'
+        && interval.lowerBps === interval.upperBps && pairs.length < minimumZeroVarianceN) {
+        return result(interval, 'insufficient');
+    }
+    return result(interval, verdict.decision);
+}
+function deriveProtectedRetention(runs, pairs, trustedReceiptSetDigest) {
+    const pairIds = new Set(pairs.map(pair => pair.pairId));
+    if (!Array.isArray(runs) || runs.length !== pairIds.size || new Set(runs.map(run => run?.pairId)).size !== runs.length
+        || runs.some(run => !run || !pairIds.has(run.pairId) || !Array.isArray(run.candidates) || !Array.isArray(run.receipts))) {
+        throw new ContextPruningError('pruning runs must cover every evaluated pair exactly once', 'invalid-input');
+    }
+    const allReceipts = runs.flatMap(run => run.receipts);
+    if (typeof trustedReceiptSetDigest !== 'string' || !SHA.test(trustedReceiptSetDigest)
+        || contextPruningReceiptSetDigest(allReceipts) !== trustedReceiptSetDigest) {
+        throw new ContextPruningError('evaluated receipt set does not match the trusted receipt-set digest', 'semantic');
+    }
+    let protectedItems = 0;
+    let retained = 0;
+    for (const run of runs) {
+        uniqueCandidates(run.candidates);
+        const itemIds = run.receipts.map((receipt) => receipt?.itemId);
+        if (new Set(itemIds).size !== itemIds.length || itemIds.length !== run.candidates.length) {
+            throw new ContextPruningError('pruning receipts are not bound to the evaluated run candidates', 'semantic');
+        }
+        for (const receipt of run.receipts) {
+            if (receipt?.pairId !== run.pairId)
+                throw new ContextPruningError('pruning receipt is not bound to the evaluated run', 'semantic');
+            validateContextPruningReceipt(receipt, run.candidates);
+            if (!receipt.classification.protected)
+                continue;
+            protectedItems++;
+            if (receipt.proposedAction === 'keep' && receipt.appliedAction === 'keep')
+                retained++;
+        }
+    }
+    return { protectedItems, retained, bps: protectedItems === 0 ? null : Math.floor(retained * 10_000 / protectedItems) };
+}
+function pruningSubject(candidate) {
+    return `context-item:${candidate.itemId}`;
+}
+function decideContextAction(candidate, classification, policy, evidence, disabledReason, fallbackAction) {
+    if (classification.protected)
+        return { proposedAction: 'keep', appliedAction: 'keep',
+            mode: disabledReason ? 'deterministic-fallback' : policy.mode,
+            reason: 'protected-item', decisionReceiptDigest: null, transformation: null };
+    const fallback = (reason) => deterministicFallback(fallbackAction, reason);
+    if (disabledReason)
+        return fallback(disabledReason === 'configured-disabled' ? 'disabled' : 'drift-or-monitoring-regression');
+    if (policy.mode === 'disabled')
+        return fallback('disabled');
+    if (!evidence || evidence.itemId !== candidate.itemId || evidence.subject !== pruningSubject(candidate))
+        return fallback('invalid-evidence');
+    if (evidence.status === 'cancelled')
+        return fallback('cancelled');
+    if (evidence.status === 'incomplete')
+        return fallback('incomplete-state');
+    if (evidence.status === 'uncalibrated')
+        return fallback('uncalibrated');
+    if (evidence.status === 'drifted')
+        return fallback('drift-or-monitoring-regression');
+    if (evidence.status === 'failed')
+        return fallback('evaluation-failed');
+    if (policy.modelIdentityDigest === null || policy.calibrationDigest === null
+        || evidence.modelIdentityDigest === undefined || evidence.calibrationDigest === undefined
+        || evidence.modelIdentityDigest !== policy.modelIdentityDigest || evidence.calibrationDigest !== policy.calibrationDigest) {
+        return fallback('drift-or-monitoring-regression');
+    }
+    const confidenceBps = evidence.confidenceBps;
+    const marginBps = evidence.marginBps;
+    if (evidence.status !== 'success' || evidence.disagreement || evidence.proposedAction === undefined
+        || typeof confidenceBps !== 'number' || typeof marginBps !== 'number'
+        || !Number.isSafeInteger(confidenceBps) || !Number.isSafeInteger(marginBps)
+        || confidenceBps < policy.minimumConfidenceBps || marginBps < policy.minimumMarginBps
+        || evidence.calibrated !== true || !evidence.decisionReceiptDigest || !SHA.test(evidence.decisionReceiptDigest)) {
+        return fallback(evidence.status === 'uncertain' ? 'uncertain-evidence' : 'invalid-evidence');
+    }
+    const proposed = evidence.proposedAction;
+    if (!policy.allowedDestructiveActions.includes(proposed) && proposed !== 'keep')
+        return fallback('policy-denied-action');
+    if ((proposed === 'truncate' || proposed === 'summarize') && !validTransformation(evidence.transformation, proposed, candidate.contentDigest)) {
+        return fallback('unsupported-transformation');
+    }
+    return {
+        proposedAction: proposed,
+        appliedAction: 'keep',
+        mode: policy.mode,
+        reason: policy.mode === 'shadow' && proposed !== 'keep' ? 'shadow-only' : 'accepted-evidence',
+        decisionReceiptDigest: evidence.decisionReceiptDigest,
+        transformation: evidence.transformation ?? null,
+    };
+}
+function deterministicFallback(action, reason) {
+    return {
+        proposedAction: action,
+        appliedAction: 'keep',
+        mode: 'deterministic-fallback',
+        reason: reason === 'disabled' ? 'disabled'
+            : ['invalid-evidence', 'uncertain-evidence', 'uncalibrated', 'incomplete-state', 'cancelled', 'evaluation-failed',
+                'drift-or-monitoring-regression', 'unsupported-transformation', 'policy-denied-action'].includes(reason)
+                ? reason : 'prior-deterministic-fallback',
+        decisionReceiptDigest: null,
+        transformation: null,
+    };
+}
+function buildContextPruningReceipt(candidate, classification, decision, createdAt, runId, pairId) {
+    const transformation = decision.transformation ?? null;
+    const payload = {
+        schemaVersion: CONTEXT_PRUNING_RECEIPT_SCHEMA,
+        runId,
+        pairId,
+        itemId: candidate.itemId,
+        locator: candidate.locator,
+        originalDigest: candidate.contentDigest,
+        originalTokenEstimate: candidate.tokenEstimate,
+        classification,
+        proposedAction: decision.proposedAction,
+        appliedAction: decision.appliedAction,
+        mode: decision.mode,
+        reason: decision.reason,
+        decisionReceiptDigest: decision.decisionReceiptDigest,
+        reversibleReference: {
+            locator: candidate.locator,
+            originalDigest: candidate.contentDigest,
+            restorationPath: candidate.locator,
+            transformation,
+        },
+        createdAt,
+    };
+    return validateContextPruningReceipt({ ...payload, receiptDigest: contextPruningDigest(payload) });
+}
+function validTransformation(value, action, sourceDigest) {
+    return Boolean(value && value.action === action && value.qualityCheck === 'passed'
+        && value.sourceDigest === sourceDigest && value.locator && SHA.test(value.digest));
+}
+export function computeContextBudgetManagerBaseline(candidates, config) {
+    const manager = new ContextBudgetManager(process.cwd(), config);
+    for (const candidate of candidates) {
+        validateContextPruningCandidate(candidate);
+        // ContextBudgetManager sizes item text itself; sizing the digest string would understate real content.
+        if (candidate.content === undefined) {
+            throw new ContextPruningError(`ContextBudgetManager baseline requires host-owned content for '${candidate.itemId}'`, 'invalid-input');
+        }
+        // The envelope priority is passed as ContextBudgetManager similarity; the manager derives its own priority.
+        manager.addItem(candidate.itemId, candidate.content, sourceTypeForBudget(candidate), candidate.priority);
+    }
+    const result = manager.degrade();
+    // ContextBudgetManager spares only source type 'system'; protected (and dependency-protected) items are
+    // retained here so the drop list can be applied as the fallback without removing protected context.
+    const classifications = classifyContextPruningCandidates(candidates);
+    const isProtected = (id) => classifications.get(id).protected;
+    const byId = new Map([...result.kept, ...result.dropped].map(item => [item.id, item]));
+    const droppedIds = new Set(result.dropped.filter(item => !isProtected(item.id)).map(item => item.id));
+    // Re-adding protected items can exceed the manager's target, so continue its own rule (ascending priority,
+    // never system items) over the remaining unprotected items until the target is met or none remain.
+    const target = Math.floor(manager.contextBudget * manager.getConfig().warningThreshold);
+    let current = candidates.reduce((sum, candidate) => sum + (droppedIds.has(candidate.itemId) ? 0 : byId.get(candidate.itemId).tokens), 0);
+    const remaining = candidates.map(candidate => byId.get(candidate.itemId))
+        .filter(item => !droppedIds.has(item.id) && !isProtected(item.id) && item.source.type !== 'system')
+        .sort((a, b) => a.priority - b.priority);
+    for (const item of remaining) {
+        if (current <= target)
+            break;
+        droppedIds.add(item.id);
+        current -= item.tokens;
+    }
+    const kept = candidates.map(candidate => byId.get(candidate.itemId)).filter(item => !droppedIds.has(item.id));
+    const dropped = candidates.map(candidate => byId.get(candidate.itemId)).filter(item => droppedIds.has(item.id));
+    return {
+        source: 'ContextBudgetManager',
+        usage: {
+            inputTokens: kept.reduce((sum, item) => sum + item.tokens, 0),
+            cachedInputTokens: null,
+            outputTokens: 0,
+            costUsd: null,
+        },
+        keptItemIds: kept.map(item => item.id).sort(),
+        droppedItemIds: dropped.map(item => item.id).sort(),
+        protectedRetainedItemIds: result.dropped.filter(item => isProtected(item.id)).map(item => item.id).sort(),
+        tokensFreed: dropped.reduce((sum, item) => sum + item.tokens, 0),
+        withinBudget: current <= target,
+    };
+}
+function validateContextPruningCandidate(candidate) {
+    requirePlain(candidate, 'candidate');
+    if (candidate.schemaVersion !== CONTEXT_PRUNING_CANDIDATE_SCHEMA || !candidate.itemId || !candidate.locator
+        || !SHA.test(candidate.contentDigest) || !candidate.source || !VALID_SOURCE_KINDS.has(candidate.source.kind) || !candidate.source.addedAt
+        || !Number.isFinite(Date.parse(candidate.source.addedAt))
+        || (candidate.content !== undefined && contextPruningDigest(candidate.content) !== candidate.contentDigest)
+        || !Number.isSafeInteger(candidate.tokenEstimate) || candidate.tokenEstimate < 0
+        || !Number.isFinite(candidate.priority) || candidate.priority < 0 || candidate.priority > 1
+        || !['verified', 'untrusted'].includes(candidate.trust)
+        || !['public', 'internal', 'confidential', 'restricted'].includes(candidate.sensitivity)
+        || !Array.isArray(candidate.dependencies) || new Set(candidate.dependencies).size !== candidate.dependencies.length
+        || candidate.dependencies.some(value => typeof value !== 'string' || !value)
+        || !Array.isArray(candidate.protectedHints) || new Set(candidate.protectedHints).size !== candidate.protectedHints.length
+        || candidate.protectedHints.some(reason => !VALID_PROTECTED_REASONS.has(reason))
+        || !candidate.taskSubject || !candidate.dataPolicy
+        || !['allowed', 'denied'].includes(candidate.dataPolicy.externalEvaluation)
+        || typeof candidate.dataPolicy.localOnly !== 'boolean'
+        || !['none', 'requires-review'].includes(candidate.dataPolicy.legalAction)) {
+        throw new ContextPruningError('invalid context candidate', 'schema');
+    }
+    try {
+        admitEntry(candidate);
+    }
+    catch {
+        throw new ContextPruningError('context candidate failed admission', 'schema');
+    }
+}
+function validatePolicy(policy) {
+    if (!['disabled', 'shadow', 'advisory'].includes(policy.mode)
+        || !Number.isSafeInteger(policy.minimumConfidenceBps) || policy.minimumConfidenceBps < 0 || policy.minimumConfidenceBps > 10_000
+        || !Number.isSafeInteger(policy.minimumMarginBps) || policy.minimumMarginBps < 0 || policy.minimumMarginBps > 10_000
+        || !Array.isArray(policy.allowedDestructiveActions)
+        || policy.allowedDestructiveActions.some(action => !['keep', 'drop', 'truncate', 'summarize'].includes(action))
+        || (policy.calibrationDigest !== null && !SHA.test(policy.calibrationDigest))
+        || (policy.modelIdentityDigest !== null && !SHA.test(policy.modelIdentityDigest))) {
+        throw new ContextPruningError('invalid context pruning policy', 'schema');
+    }
+}
+function validateIntegrity(integrity) {
+    if (!integrity || typeof integrity !== 'object' || !integrity.release_gate
+        || !['PROMOTE', 'HOLD', 'ROLLBACK'].includes(integrity.release_gate.decision)
+        || typeof integrity.integrity_state !== 'string') {
+        throw new ContextPruningError('invalid eval-integrity metadata', 'schema');
+    }
+}
+const isCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+function validateMetrics(metrics, preregistration) {
+    requirePlain(metrics, 'metrics');
+    const slices = new Set(preregistration.thresholds.slices);
+    const pairs = Array.isArray(metrics.pairs) ? metrics.pairs : null;
+    const pairIds = new Set(pairs?.map(pair => pair?.pairId));
+    if (!pairs || pairIds.size !== pairs.length
+        || pairs.some(pair => !pair || typeof pair.pairId !== 'string' || !pair.pairId || !slices.has(pair.slice))) {
+        throw new ContextPruningError('pair records must have unique IDs and preregistered slices', 'schema');
+    }
+    const scales = new Map(preregistration.thresholds.qualityMetrics.map(item => [item.metric, item.scale]));
+    const quality = Array.isArray(metrics.quality) ? metrics.quality : null;
+    if (!quality || new Set(quality.map(item => item?.metric)).size !== quality.length
+        || quality.some(item => !item || !scales.has(item.metric) || !Array.isArray(item.pairs))) {
+        throw new ContextPruningError('quality outcomes must name each preregistered metric at most once', 'schema');
+    }
+    for (const item of quality) {
+        const scale = scales.get(item.metric);
+        const seen = new Set();
+        for (const pair of item.pairs) {
+            const inRange = (value) => typeof value === 'number' && Number.isFinite(value)
+                && (scale === 'binary' ? value === 0 || value === 1 : value >= 0 && value <= 1);
+            if (!pair || !pairIds.has(pair.pairId) || seen.has(pair.pairId) || !inRange(pair.baseline) || !inRange(pair.candidate)) {
+                throw new ContextPruningError(`quality outcome for '${item.metric}' is out of range or not reconciled with the pair records`, 'schema');
+            }
+            seen.add(pair.pairId);
+        }
+    }
+    if (!isCount(metrics.protectedRetentionBps) || metrics.protectedRetentionBps > 10_000
+        || metrics.sharedStateAccounting !== 'not-applicable'
+        || !usageAccounting(metrics.providerUsage, 'provider') || !usageAccounting(metrics.estimatorUsage, 'estimator')
+        || !isCount(metrics.totalCalls) || !metrics.latencyMs
+        || [metrics.latencyMs.p50, metrics.latencyMs.p95, metrics.latencyMs.p99]
+            .some(value => value !== null && (!Number.isFinite(value) || value < 0))) {
+        throw new ContextPruningError('invalid context pruning metrics', 'schema');
+    }
+    const cache = metrics.promptCache;
+    for (const arm of ['baseline', 'prunedDownstream']) {
+        const reported = cache?.[arm];
+        const usage = metrics.providerUsage[arm];
+        // Cache credit is never a caller assertion: it must match provider-reported usage for the same arm.
+        if (!reported || !isCount(reported.hits) || !isCount(reported.misses) || !isCount(reported.cachedInputTokens)
+            || reported.cachedInputTokens !== usage.cachedInputTokens
+            || (reported.cachedInputTokens > 0 && reported.hits === 0)) {
+            throw new ContextPruningError(`prompt-cache usage for '${arm}' does not reconcile with provider usage`, 'semantic');
+        }
+    }
+}
+const USAGE_ARMS = ['baseline', 'prunedDownstream', 'decisionCalls', 'fallbackCalls', 'transformationCalls'];
+function usage(value, source) {
+    return Boolean(value) && isCount(value.inputTokens) && isCount(value.outputTokens)
+        && (source === 'provider'
+            ? isCount(value.cachedInputTokens) && value.cachedInputTokens <= value.inputTokens
+            : value.cachedInputTokens === null)
+        && (value.costUsd === null || (Number.isFinite(value.costUsd) && value.costUsd >= 0));
+}
+function usageAccounting(value, source) {
+    return Boolean(value) && typeof value === 'object'
+        && Object.keys(value).sort().join() === [...USAGE_ARMS].sort().join()
+        && USAGE_ARMS.every(arm => usage(value[arm], source));
+}
+/** Baseline arm minus every pruned-arm call (downstream, decision, fallback, transformation). */
+function totalSavings(value, basis) {
+    const tokens = (item) => item.inputTokens + item.outputTokens
+        - (basis === 'uncached' ? item.cachedInputTokens ?? 0 : 0);
+    return tokens(value.baseline) - USAGE_ARMS.filter(arm => arm !== 'baseline').reduce((sum, arm) => sum + tokens(value[arm]), 0);
+}
+function providerUsageSavings(value) {
+    const costs = USAGE_ARMS.map(arm => value[arm].costUsd);
+    return {
+        totalTokens: totalSavings(value, 'total'),
+        uncachedTokens: totalSavings(value, 'uncached'),
+        costUsd: costs.some(cost => cost === null) ? null
+            : value.baseline.costUsd - USAGE_ARMS.filter(arm => arm !== 'baseline').reduce((sum, arm) => sum + value[arm].costUsd, 0),
+        cachedInputTokensDelta: value.prunedDownstream.cachedInputTokens - value.baseline.cachedInputTokens,
+    };
+}
+function sourceTypeForBudget(candidate) {
+    if (candidate.source.kind === 'system' || candidate.source.kind === 'developer' || candidate.source.kind === 'project')
+        return 'system';
+    if (candidate.source.kind === 'user')
+        return 'user';
+    if (candidate.protectedHints.includes('explicit-mention'))
+        return 'at-mention';
+    return 'auto';
+}
+function uniqueCandidates(candidates) {
+    const byId = new Map(candidates.map(candidate => [candidate.itemId, candidate]));
+    if (byId.size !== candidates.length)
+        throw new ContextPruningError('candidate item IDs must be unique', 'semantic');
+    for (const candidate of candidates)
+        validateContextPruningCandidate(candidate);
+    for (const candidate of candidates) {
+        for (const dependencyId of candidate.dependencies) {
+            if (!byId.has(dependencyId))
+                throw new ContextPruningError(`unknown context dependency '${dependencyId}'`, 'semantic');
+        }
+    }
+    return byId;
+}
+function requirePlain(value, label) {
+    if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new ContextPruningError(`${label} must be a plain object`, 'schema');
+    }
+}
+//# sourceMappingURL=context-pruning.js.map