agentic-qe 3.14.0 → 3.14.1

package/dist/domains/chaos-resilience/diagnosis/scorer.js

@@ -0,0 +1,128 @@
+const ratio = (numerator, denominator) => denominator === 0 ? 0 : numerator / denominator;
+function wilson95(successes, total) {
+    if (total === 0)
+        return [0, 0];
+    const z = 1.96;
+    const p = successes / total;
+    const denominator = 1 + (z * z) / total;
+    const center = (p + (z * z) / (2 * total)) / denominator;
+    const margin = (z / denominator) * Math.sqrt((p * (1 - p) / total) + (z * z) / (4 * total * total));
+    return [Math.max(0, center - margin), Math.min(1, center + margin)];
+}
+export function scoreAgentFaultDetector(corpus, detector, topK = 3) {
+    const diagnoses = new Map();
+    for (const item of corpus.cases)
+        diagnoses.set(item.caseId, runDetector(detector, item.caseId, item.detectorInput));
+    const cases = corpus.cases.map((item) => {
+        const diagnosis = diagnoses.get(item.caseId);
+        const truth = item.heldOut.truth;
+        const top = diagnosis.candidates[0];
+        const injected = truth.faultType !== 'none';
+        const predictedFault = Boolean(top && top.faultType !== 'none');
+        return {
+            caseId: item.caseId,
+            faultType: truth.faultType,
+            boundary: truth.boundary,
+            faultInjected: injected,
+            signalObserved: diagnosis.signalObserved,
+            detected: injected ? predictedFault : !predictedFault,
+            typeCorrect: top?.faultType === truth.faultType,
+            componentLocalized: top?.componentId === truth.componentId,
+            spanLocalized: top?.spanId === truth.spanId,
+            jointCorrect: top?.faultType === truth.faultType && top?.componentId === truth.componentId,
+            recovered: item.detectorInput.structured.spans.some((span) => span.recovered),
+            taskSucceeded: item.detectorInput.structured.terminalOutcome === 'completed',
+            abstained: diagnosis.status === 'abstained',
+        };
+    });
+    const faulty = corpus.cases.filter((item) => item.heldOut.truth.faultType !== 'none');
+    const clean = corpus.cases.filter((item) => item.heldOut.truth.faultType === 'none');
+    const faultyScores = cases.filter((item) => item.faultInjected);
+    const cleanScores = cases.filter((item) => !item.faultInjected);
+    const predictedClean = corpus.cases.filter((item) => diagnoses.get(item.caseId)?.candidates[0]?.faultType === 'none');
+    const trueCleanPredictions = predictedClean.filter((item) => item.heldOut.truth.faultType === 'none');
+    const typeTopKCorrect = faulty.filter((item) => diagnoses.get(item.caseId)?.candidates
+        .slice(0, topK).some((candidate) => candidate.faultType === item.heldOut.truth.faultType)).length;
+    const parsed = [...diagnoses.values()].filter((item) => item.status !== 'parse-error').length;
+    const abstained = [...diagnoses.values()].filter((item) => item.status === 'abstained').length;
+    return {
+        detectorId: detector.id,
+        corpusId: corpus.manifest.corpusId,
+        support: cases.length,
+        noFault: {
+            precision: ratio(trueCleanPredictions.length, predictedClean.length),
+            recall: ratio(cleanScores.filter((item) => item.typeCorrect).length, clean.length),
+            falsePositiveRate: ratio(cleanScores.filter((item) => !item.typeCorrect).length, clean.length),
+        },
+        faultRecall: ratio(faultyScores.filter((item) => item.detected).length, faulty.length),
+        typeTop1: ratio(faultyScores.filter((item) => item.typeCorrect).length, faulty.length),
+        typeTopK: ratio(typeTopKCorrect, faulty.length),
+        componentTop1: ratio(faultyScores.filter((item) => item.componentLocalized).length, faulty.length),
+        exactSpanTop1: ratio(faultyScores.filter((item) => item.spanLocalized).length, faulty.length),
+        jointTop1: ratio(faultyScores.filter((item) => item.jointCorrect).length, faulty.length),
+        parseRate: ratio(parsed, cases.length),
+        abstentionRate: ratio(abstained, cases.length),
+        meanLatencyMs: ratio([...diagnoses.values()].reduce((sum, item) => sum + item.latencyMs, 0), cases.length),
+        totalTokens: [...diagnoses.values()].reduce((sum, item) => sum + (item.tokens ?? 0), 0),
+        totalCost: [...diagnoses.values()].reduce((sum, item) => sum + (item.cost ?? 0), 0),
+        uncertainty: { method: 'wilson-95', faultRecall: wilson95(faultyScores.filter((item) => item.detected).length, faulty.length) },
+        byFault: slice(corpus, cases, (index) => corpus.cases[index].heldOut.truth.faultType),
+        byBoundary: slice(corpus, cases, (index) => corpus.cases[index].heldOut.truth.boundary),
+        cases,
+    };
+}
+function slice(corpus, scores, key) {
+    const groups = new Map();
+    scores.forEach((score, index) => groups.set(key(index), [...(groups.get(key(index)) ?? []), score]));
+    return Object.fromEntries([...groups.entries()].map(([name, items]) => [name, {
+            support: items.length,
+            detected: items.filter((item) => item.detected).length,
+            typeTop1: items.filter((item) => item.typeCorrect).length,
+            componentTop1: items.filter((item) => item.componentLocalized).length,
+            jointTop1: items.filter((item) => item.jointCorrect).length,
+            abstentions: items.filter((item) => item.abstained).length,
+        }]));
+}
+export function qualifyAgentFaultDetector(report) {
+    const failures = [];
+    if (report.noFault.falsePositiveRate > 0.1)
+        failures.push('no-fault false-positive rate exceeds 10%');
+    if (report.typeTop1 < 0.5)
+        failures.push('fault-type top-1 accuracy is below 50%');
+    if (report.jointTop1 < 0.5)
+        failures.push('joint type/location accuracy is below 50%');
+    if (report.parseRate < 1)
+        failures.push('detector did not parse every frozen case');
+    for (const critical of ['corrupted-tool-output', 'guardrail-bypass']) {
+        const score = report.cases.find((item) => item.faultType === critical);
+        if (score && !score.typeCorrect && !score.abstained) {
+            failures.push(`${critical} must be diagnosed correctly or explicitly abstained`);
+        }
+    }
+    return { passed: failures.length === 0, failures };
+}
+function runDetector(detector, caseId, input) {
+    try {
+        const result = detector.diagnose(caseId, input);
+        const validStatus = ['diagnosed', 'abstained', 'parse-error'].includes(result.status);
+        const validCandidates = Array.isArray(result.candidates)
+            && result.candidates.every((item) => Number.isFinite(item.confidence)
+                && item.confidence >= 0 && item.confidence <= 1);
+        if (result.caseId !== caseId || !validStatus || !validCandidates
+            || !Number.isFinite(result.latencyMs) || result.latencyMs < 0) {
+            throw new Error('Detector returned an invalid diagnosis envelope');
+        }
+        return result;
+    }
+    catch (error) {
+        return {
+            caseId,
+            status: 'parse-error',
+            candidates: [],
+            signalObserved: false,
+            latencyMs: 0,
+            reason: error instanceof Error ? error.message : 'Detector failed',
+        };
+    }
+}
+//# sourceMappingURL=scorer.js.map

package/dist/domains/chaos-resilience/diagnosis/types.d.ts

@@ -0,0 +1,171 @@
+export declare const AGENT_FAULT_TRACE_SCHEMA_VERSION: "1.0.0";
+export declare const AGENT_FAULT_CORPUS_SCHEMA_VERSION: "1.0.0";
+export type AgentRuntimeBoundary = 'tool' | 'model-context' | 'guardrail' | 'inter-agent' | 'control';
+export type AgentRuntimeFaultType = 'none' | 'tool-unavailable' | 'tool-timeout' | 'corrupted-tool-output' | 'context-truncation' | 'delegation-timeout' | 'agent-misroute' | 'delegation-loop' | 'guardrail-bypass';
+export type TraceSpanKind = 'run' | 'agent' | 'delegation' | 'tool' | 'model' | 'guardrail';
+export type TraceSpanStatus = 'ok' | 'error' | 'timeout' | 'cancelled';
+export interface SanitizedTraceSpan {
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly componentId: string;
+    readonly kind: TraceSpanKind;
+    readonly startOffsetMs: number;
+    readonly durationMs: number;
+    readonly status: TraceSpanStatus;
+    readonly signalCode?: string;
+    readonly inputBytes: number;
+    readonly outputBytes: number;
+    readonly inputHash: string;
+    readonly outputHash: string;
+    readonly intendedDestination?: string;
+    readonly actualDestination?: string;
+    readonly policyRef?: string;
+    readonly expectedDecision?: 'allow' | 'deny';
+    readonly actualDecision?: 'allow' | 'deny';
+    readonly retry?: number;
+    readonly recovered?: boolean;
+}
+export interface SanitizedExecutionTrace {
+    readonly schemaVersion: typeof AGENT_FAULT_TRACE_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly harnessRevision: string;
+    readonly terminalOutcome: 'completed' | 'failed' | 'cancelled';
+    readonly spans: readonly SanitizedTraceSpan[];
+}
+export interface StructuredTraceView {
+    readonly schemaVersion: typeof AGENT_FAULT_TRACE_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly terminalOutcome: SanitizedExecutionTrace['terminalOutcome'];
+    readonly spans: readonly SanitizedTraceSpan[];
+}
+export interface AgentFaultDetectorInput {
+    readonly trace: SanitizedExecutionTrace;
+    readonly structured: StructuredTraceView;
+    readonly cleanReference?: StructuredTraceView;
+}
+export interface AgentFaultInjectionManifest {
+    readonly schemaVersion: typeof AGENT_FAULT_CORPUS_SCHEMA_VERSION;
+    readonly caseId: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly sourceRevision: string;
+    readonly environmentDigest: string;
+    readonly seed: number;
+    readonly target: {
+        readonly boundary: AgentRuntimeBoundary;
+        readonly componentId: string;
+        readonly spanId: string;
+    };
+    readonly parameters: Readonly<Record<string, string | number | boolean>>;
+    readonly expectedObservableSignal: string;
+    readonly cleanup: {
+        readonly required: boolean;
+        readonly state: 'not-required' | 'verified';
+        readonly witness: string;
+    };
+}
+export interface AgentFaultGroundTruth {
+    readonly faultType: AgentRuntimeFaultType;
+    readonly boundary: AgentRuntimeBoundary;
+    readonly componentId: string;
+    readonly spanId: string;
+}
+export interface AgentFaultCorpusCase {
+    readonly caseId: string;
+    readonly cleanReferenceId?: string;
+    readonly detectorInput: AgentFaultDetectorInput;
+    /** Held outside detectorInput. Callers must not pass this object to detectors. */
+    readonly heldOut: {
+        readonly manifest: AgentFaultInjectionManifest;
+        readonly truth: AgentFaultGroundTruth;
+    };
+}
+export interface AgentFaultCorpusManifest {
+    readonly schemaVersion: typeof AGENT_FAULT_CORPUS_SCHEMA_VERSION;
+    readonly corpusId: string;
+    readonly sourceRevision: string;
+    readonly harnessRevision: string;
+    readonly caseCount: number;
+    readonly casesDigest: string;
+    readonly mixedFaults: 'out-of-scope';
+    readonly detectorInputExcludes: readonly string[];
+}
+export interface AgentFaultCorpus {
+    readonly manifest: AgentFaultCorpusManifest;
+    readonly cases: readonly AgentFaultCorpusCase[];
+}
+export interface RankedFaultCandidate {
+    readonly faultType: AgentRuntimeFaultType;
+    readonly boundary: AgentRuntimeBoundary;
+    readonly componentId: string;
+    readonly spanId: string;
+    readonly confidence: number;
+}
+export interface AgentFaultDiagnosis {
+    readonly caseId: string;
+    readonly status: 'diagnosed' | 'abstained' | 'parse-error';
+    readonly candidates: readonly RankedFaultCandidate[];
+    readonly signalObserved: boolean;
+    readonly latencyMs: number;
+    readonly tokens?: number;
+    readonly cost?: number;
+    readonly reason?: string;
+}
+export interface AgentFaultDetector {
+    readonly id: string;
+    diagnose(caseId: string, input: AgentFaultDetectorInput): AgentFaultDiagnosis;
+}
+export interface AgentFaultCaseScore {
+    readonly caseId: string;
+    readonly faultType: AgentRuntimeFaultType;
+    readonly boundary: AgentRuntimeBoundary;
+    readonly faultInjected: boolean;
+    readonly signalObserved: boolean;
+    readonly detected: boolean;
+    readonly typeCorrect: boolean;
+    readonly componentLocalized: boolean;
+    readonly spanLocalized: boolean;
+    readonly jointCorrect: boolean;
+    readonly recovered: boolean;
+    readonly taskSucceeded: boolean;
+    readonly abstained: boolean;
+}
+export interface AgentFaultSliceScore {
+    readonly support: number;
+    readonly detected: number;
+    readonly typeTop1: number;
+    readonly componentTop1: number;
+    readonly jointTop1: number;
+    readonly abstentions: number;
+}
+export interface AgentFaultScoreReport {
+    readonly detectorId: string;
+    readonly corpusId: string;
+    readonly support: number;
+    readonly noFault: {
+        readonly precision: number;
+        readonly recall: number;
+        readonly falsePositiveRate: number;
+    };
+    readonly faultRecall: number;
+    readonly typeTop1: number;
+    readonly typeTopK: number;
+    readonly componentTop1: number;
+    readonly exactSpanTop1: number;
+    readonly jointTop1: number;
+    readonly parseRate: number;
+    readonly abstentionRate: number;
+    readonly meanLatencyMs: number;
+    readonly totalTokens: number;
+    readonly totalCost: number;
+    readonly uncertainty: {
+        readonly method: 'wilson-95';
+        readonly faultRecall: readonly [number, number];
+    };
+    readonly byFault: Readonly<Record<string, AgentFaultSliceScore>>;
+    readonly byBoundary: Readonly<Record<string, AgentFaultSliceScore>>;
+    readonly cases: readonly AgentFaultCaseScore[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/domains/chaos-resilience/diagnosis/types.js

@@ -0,0 +1,3 @@
+export const AGENT_FAULT_TRACE_SCHEMA_VERSION = '1.0.0';
+export const AGENT_FAULT_CORPUS_SCHEMA_VERSION = '1.0.0';
+//# sourceMappingURL=types.js.map

package/dist/domains/chaos-resilience/index.d.ts

@@ -10,4 +10,5 @@ export { ChaosEngineerService, type ChaosEngineerConfig, } from './services/chao
 export { LoadTesterService, type LoadTesterConfig, } from './services/load-tester';
 export { PerformanceProfilerService, type PerformanceProfilerConfig, } from './services/performance-profiler';
 export type { ChaosExperiment, Hypothesis, MetricExpectation, Tolerance, SteadyStateDefinition, SteadyStateProbe, FaultInjection, FaultType, FaultTarget, FaultParameters, BlastRadius, RollbackPlan, RollbackTrigger, RollbackStep, ExperimentSchedule, ExperimentResult, ExperimentStatus, FaultResult, MetricSnapshot, Incident, LoadTest, LoadTestType, LoadTestTarget, LoadProfile, VirtualUserConfig, LoadScenario, LoadStep, LoadAssertion, LoadTestResult, LoadTestSummary, TimelinePoint, LoadTestError, AssertionResult, TrafficSample, SampledRequest, RecoveryTestResult, RecoveryEvent, FailoverTestResult, FailoverStep, CircuitBreakerTestOptions, CircuitBreakerTestResult, RateLimitTestResult, RateLimitResponse, ServiceArchitecture, ServiceDefinition, ServiceDependency, ChaosSuiteReport, LoadTestSuiteReport, PerformanceBottleneck, ResilienceAssessment, ResilienceWeakness, ResilienceRecommendation, ResilienceDashboard, ResilienceIssue, IChaosEngineeringService, ILoadTestingService, IResilienceTestingService, IChaosResilienceCoordinator, IChaosExperimentRepository, IExperimentResultRepository, ILoadTestRepository, ILoadTestResultRepository, ChaosExperimentStartedEvent, ChaosExperimentCompletedEvent, FaultInjectedEvent, LoadTestCompletedEvent, ResilienceIssueDetectedEvent, } from './interfaces';
+export * from './diagnosis/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/domains/chaos-resilience/index.js

@@ -18,4 +18,5 @@ export { ChaosResilienceCoordinator, } from './coordinator.js';
 export { ChaosEngineerService, } from './services/chaos-engineer.js';
 export { LoadTesterService, } from './services/load-tester.js';
 export { PerformanceProfilerService, } from './services/performance-profiler.js';
+export * from './diagnosis/index.js';
 //# sourceMappingURL=index.js.map

package/dist/domains/index.d.ts

@@ -16,6 +16,7 @@ export * as SecurityCompliance from './security-compliance/interfaces';
 export * as ContractTesting from './contract-testing/interfaces';
 export * as VisualAccessibility from './visual-accessibility/interfaces';
 export * as ChaosResilience from './chaos-resilience/interfaces';
+export * as AgentFaultDiagnosis from './chaos-resilience/diagnosis/index';
 export * as LearningOptimization from './learning-optimization/interfaces';
 export * as EnterpriseIntegration from './enterprise-integration/interfaces';
 //# sourceMappingURL=index.d.ts.map

package/dist/domains/index.js

@@ -18,6 +18,7 @@ export * as SecurityCompliance from './security-compliance/interfaces.js';
 export * as ContractTesting from './contract-testing/interfaces.js';
 export * as VisualAccessibility from './visual-accessibility/interfaces.js';
 export * as ChaosResilience from './chaos-resilience/interfaces.js';
+export * as AgentFaultDiagnosis from './chaos-resilience/diagnosis/index.js';
 export * as LearningOptimization from './learning-optimization/interfaces.js';
 export * as EnterpriseIntegration from './enterprise-integration/interfaces.js';
 //# sourceMappingURL=index.js.map

package/dist/early-exit/early-exit-controller.d.ts

@@ -5,7 +5,7 @@
  * This module implements the main controller that orchestrates early exit testing,
  * combining quality signal calculation, decision making, and speculative execution.
  */
-import { EarlyExitConfig, EarlyExitDecision, TestLayer, TestPyramidResult, LayerResult, SpeculativeResult, QualitySignal, EarlyExitMetrics } from './types';
+import { EarlyExitConfig, EarlyExitDecision, TestLayer, TestPyramidResult, LayerResult, SpeculativeResult, QualitySignal, EarlyExitMetrics, ShadowCalibrationContext } from './types';
 /**
  * Layer executor function type
  */
@@ -18,6 +18,7 @@ export interface EarlyExitEvents {
     onLayerComplete?: (layer: TestLayer, result: LayerResult, signal: QualitySignal) => void;
     onDecision?: (decision: EarlyExitDecision, layer: number) => void;
     onEarlyExit?: (exitLayer: number, decision: EarlyExitDecision) => void;
+    onCandidateExit?: (exitLayer: number, decision: EarlyExitDecision) => void;
     onSpeculationComplete?: (speculations: SpeculativeResult[]) => void;
     onComplete?: (result: TestPyramidResult) => void;
 }
@@ -71,7 +72,8 @@ export declare class EarlyExitController {
      * @param executor - Function to execute a single layer
      * @returns Complete test pyramid result with early exit information
      */
-    runWithEarlyExit(layers: TestLayer[], executor: LayerExecutor): Promise<TestPyramidResult>;
+    runWithEarlyExit(layers: TestLayer[], executor: LayerExecutor, calibrationContext?: ShadowCalibrationContext): Promise<TestPyramidResult>;
+    private createShadowResult;
     /**
      * Execute a single test layer
      */

package/dist/early-exit/early-exit-controller.js

@@ -6,11 +6,20 @@
  * combining quality signal calculation, decision making, and speculative execution.
  */
 import { DEFAULT_EXIT_CONFIG, } from './types.js';
+import { createHash } from 'node:crypto';
 import { calculateQualitySignal } from './quality-signal.js';
 import { CoherenceEarlyExit } from './early-exit-decision.js';
 import { SpeculativeExecutor } from './speculative-executor.js';
 import { getUnifiedMemory } from '../kernel/unified-memory.js';
 import { toErrorMessage } from '../shared/error-utils.js';
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
 // ============================================================================
 // Early Exit Controller Class
 // ============================================================================
@@ -82,11 +91,12 @@ export class EarlyExitController {
      * @param executor - Function to execute a single layer
      * @returns Complete test pyramid result with early exit information
      */
-    async runWithEarlyExit(layers, executor) {
+    async runWithEarlyExit(layers, executor, calibrationContext) {
         const startTime = Date.now();
         const results = [];
         let exitDecision = null;
         let previousSignal;
+        let shadowCandidate = null;
         // Execute layers until early exit or completion
         for (let i = 0; i < layers.length; i++) {
             const layer = layers[i];
@@ -107,6 +117,10 @@ export class EarlyExitController {
             }
             // Emit layer complete event
             this.events.onLayerComplete?.(layer, layerResult, signal);
+            // The first candidate is the pre-registered counterfactual. The full run
+            // remains authoritative and later signals cannot rewrite that decision.
+            if (shadowCandidate)
+                continue;
             // Check for early exit
             exitDecision = this.earlyExit.shouldExit(signal, i);
             // Emit decision event
@@ -115,23 +129,32 @@ export class EarlyExitController {
                 this.logDecision(exitDecision, i, signal);
             }
             if (exitDecision.canExit) {
-                // Emit early exit event
-                this.events.onEarlyExit?.(i, exitDecision);
                 // Generate speculative predictions for remaining layers
                 const skippedLayers = layers.slice(i + 1);
                 let speculations = [];
                 if (exitDecision.enableSpeculation && skippedLayers.length > 0) {
                     const batch = await this.speculator.speculate(exitDecision, skippedLayers);
                     speculations = batch.predictions;
-                    // Optionally verify some speculations
-                    if (this.config.verificationLayers > 0) {
+                    // Enforced mode may sample verification layers. Shadow mode executes
+                    // every remaining layer exactly once below.
+                    if (this.config.mode === 'enforced' && this.config.verificationLayers > 0) {
                         speculations = await this.speculator.verify(speculations, skippedLayers, (verifyLayer) => executor(verifyLayer));
                     }
                     // Emit speculation complete event
                     this.events.onSpeculationComplete?.(speculations);
                 }
-                const totalDuration = Date.now() - startTime;
                 const computeSavings = this.estimateComputeSavings(i, layers);
+                if (this.config.mode !== 'enforced') {
+                    shadowCandidate = {
+                        layer: i, decision: exitDecision, speculations,
+                        estimatedSavings: computeSavings, signal,
+                    };
+                    this.events.onCandidateExit?.(i, exitDecision);
+                    continue;
+                }
+                // Emit an actual early exit only in explicitly enforced mode.
+                this.events.onEarlyExit?.(i, exitDecision);
+                const totalDuration = Date.now() - startTime;
                 const result = this.createPyramidResult(results, true, i, exitDecision, speculations, skippedLayers.length, totalDuration, computeSavings, signal);
                 // Update metrics
                 this.updateMetrics(result);
@@ -143,13 +166,67 @@ export class EarlyExitController {
         // Completed all layers without early exit
         const totalDuration = Date.now() - startTime;
         const finalSignal = previousSignal || this.createDefaultSignal();
-        const result = this.createPyramidResult(results, false, layers.length - 1, exitDecision || this.createDefaultDecision(layers.length - 1), [], 0, totalDuration, 0, finalSignal);
+        const result = shadowCandidate
+            ? this.createShadowResult(results, shadowCandidate, totalDuration, finalSignal, calibrationContext)
+            : this.createPyramidResult(results, false, layers.length - 1, exitDecision || this.createDefaultDecision(layers.length - 1), [], 0, totalDuration, 0, finalSignal);
         // Update metrics
         this.updateMetrics(result);
         // Emit complete event
         this.events.onComplete?.(result);
         return result;
     }
+    createShadowResult(layers, candidate, totalDuration, finalSignal, context) {
+        const contextBound = context !== undefined && Object.values(context).every(value => typeof value === 'string' && value.trim().length > 0);
+        const prefixFailed = layers.slice(0, candidate.layer + 1).some(layer => layer.failedTests > 0);
+        const speculativeOutcomes = candidate.speculations.map(result => result.predicted);
+        const predictedVerdict = prefixFailed || speculativeOutcomes.includes('fail')
+            ? 'fail'
+            : speculativeOutcomes.includes('flaky') ? 'inconclusive' : 'pass';
+        const fullRunVerdict = layers.some(layer => layer.failedTests > 0) ? 'fail' : 'pass';
+        const firstMissed = layers.slice(candidate.layer + 1).find(layer => layer.failedTests > 0);
+        const result = this.createPyramidResult(layers, false, candidate.layer, candidate.decision, candidate.speculations, 0, totalDuration, 0, finalSignal);
+        const receiptPayload = {
+            evidenceClass: contextBound ? 'EXECUTED' : 'INCONCLUSIVE',
+            candidateExitLayer: candidate.layer,
+            candidateSignal: {
+                lambda: candidate.signal.lambda,
+                lambdaPrev: candidate.signal.lambdaPrev,
+                boundaryConcentration: candidate.signal.boundaryConcentration,
+                flags: candidate.signal.flags,
+                timestamp: candidate.signal.timestamp.toISOString(),
+            },
+            thresholds: {
+                minLambdaForExit: this.config.minLambdaForExit,
+                minLambdaStability: this.config.minLambdaStability,
+                maxBoundaryConcentration: this.config.maxBoundaryConcentration,
+                minConfidence: this.config.minConfidence,
+            },
+            predictedLayers: candidate.speculations.map(prediction => ({
+                layerIndex: prediction.layerIndex,
+                layerType: prediction.layerType,
+                outcome: prediction.predicted,
+                confidence: prediction.confidence,
+                evidenceClass: 'PREDICTED',
+            })),
+            predictedVerdict,
+            fullRunVerdict,
+            falsePass: predictedVerdict === 'pass' && fullRunVerdict === 'fail',
+            falseFail: predictedVerdict === 'fail' && fullRunVerdict === 'pass',
+            ...(firstMissed ? { firstMissedFailure: {
+                    layerIndex: firstMissed.layerIndex,
+                    layerType: firstMissed.layerType,
+                    failedTests: firstMissed.failedTests,
+                } } : {}),
+            estimatedSavings: candidate.estimatedSavings,
+            actualSavings: 0,
+            ...(contextBound ? { context: { ...context } } : {}),
+        };
+        result.shadowCalibration = deepFreeze({
+            ...receiptPayload,
+            receiptId: createHash('sha256').update(JSON.stringify(receiptPayload)).digest('hex'),
+        });
+        return result;
+    }
     /**
      * Execute a single test layer
      */
@@ -263,6 +340,7 @@ export class EarlyExitController {
             speculationAccuracy: 0,
             falsePositiveRate: 0,
             falseNegativeRate: 0,
+            shadowCandidateCount: 0,
         };
     }
     /**
@@ -291,6 +369,16 @@ export class EarlyExitController {
         // Update speculation accuracy
         const speculatorStats = this.speculator.getAccuracyStats();
         this.executionMetrics.speculationAccuracy = speculatorStats.accuracy;
+        if (result.shadowCalibration) {
+            const previousCount = this.executionMetrics.shadowCandidateCount;
+            const falsePasses = this.executionMetrics.falsePositiveRate * previousCount
+                + Number(result.shadowCalibration.falsePass);
+            const falseFails = this.executionMetrics.falseNegativeRate * previousCount
+                + Number(result.shadowCalibration.falseFail);
+            this.executionMetrics.shadowCandidateCount++;
+            this.executionMetrics.falsePositiveRate = falsePasses / this.executionMetrics.shadowCandidateCount;
+            this.executionMetrics.falseNegativeRate = falseFails / this.executionMetrics.shadowCandidateCount;
+        }
     }
     /**
      * Set event handlers

package/dist/early-exit/index.d.ts

@@ -29,7 +29,7 @@
  *
  * @module early-exit
  */
-export type { TestLayerType, TestLayer, LayerResult, TestResult, QualitySignal, ExitReason, EarlyExitDecision, EarlyExitConfig, PredictedOutcome, SpeculativeResult, SpeculativeBatch, TestPyramidResult, EarlyExitMetrics, } from './types';
+export type { TestLayerType, TestLayer, LayerResult, TestResult, QualitySignal, ExitReason, EarlyExitDecision, EarlyExitConfig, PredictedOutcome, SpeculativeResult, SpeculativeBatch, TestPyramidResult, EarlyExitMetrics, ShadowCalibrationContext, ShadowCalibrationResult, } from './types';
 export { DEFAULT_EXIT_CONFIG, AGGRESSIVE_EXIT_CONFIG, CONSERVATIVE_EXIT_CONFIG, QualityFlags, } from './types';
 export { calculateQualitySignal, calculateLambdaStability, calculateConfidence, countQualityPartitions, createQualitySignal, isStableForExit, } from './quality-signal';
 export { CoherenceEarlyExit, createEarlyExit, createAggressiveEarlyExit, createConservativeEarlyExit, createCustomEarlyExit, } from './early-exit-decision';

package/dist/early-exit/speculative-executor.js

@@ -82,6 +82,7 @@ export class SpeculativeExecutor {
                 const actualOutcome = this.determineOutcome(actual);
                 const verifiedPrediction = {
                     ...prediction,
+                    evidenceClass: 'EXECUTED',
                     verified: true,
                     actual: actualOutcome,
                     correct: prediction.predicted === actualOutcome,
@@ -94,6 +95,7 @@ export class SpeculativeExecutor {
                 // Verification failed - keep original prediction unverified
                 verified.push({
                     ...prediction,
+                    evidenceClass: 'INCONCLUSIVE',
                     verified: false,
                     reasoning: `${prediction.reasoning} (verification failed: ${error instanceof Error ? error.message : 'unknown error'})`,
                 });
@@ -139,6 +141,7 @@ export class SpeculativeExecutor {
             }
         }
         return {
+            evidenceClass: 'PREDICTED',
             predicted: predictedOutcome,
             confidence: Math.round(adjustedConfidence * 1000) / 1000,
             verified: false,

package/dist/early-exit/types.d.ts

@@ -143,6 +143,8 @@ export interface EarlyExitDecision {
  * Configuration for early exit behavior
  */
 export interface EarlyExitConfig {
+    /** Shadow executes all layers; enforced permits a qualified early stop. */
+    mode?: 'shadow' | 'enforced';
     /** Target exit layer (0-indexed) - exit after this layer if conditions met */
     exitLayer: number;
     /** Minimum lambda value required for early exit (0-100 scale) */
@@ -182,6 +184,8 @@ export type PredictedOutcome = 'pass' | 'fail' | 'flaky';
  * Result of speculative prediction
  */
 export interface SpeculativeResult {
+    /** Predictions and executions are never interchangeable evidence. */
+    evidenceClass: 'PREDICTED' | 'EXECUTED' | 'INCONCLUSIVE';
     /** Predicted outcome */
     predicted: PredictedOutcome;
     /** Confidence in prediction (0-1) */
@@ -240,6 +244,51 @@ export interface TestPyramidResult {
     finalSignal: QualitySignal;
     /** Early exit decision details */
     decision: EarlyExitDecision;
+    /** Full-run counterfactual evidence when the controller is calibrating. */
+    shadowCalibration?: ShadowCalibrationResult;
+}
+export interface ShadowCalibrationContext {
+    revision: string;
+    environment: string;
+    featureSchemaVersion: string;
+    heuristicVersion: string;
+}
+export interface ShadowCalibrationResult {
+    receiptId: string;
+    evidenceClass: 'EXECUTED' | 'INCONCLUSIVE';
+    candidateExitLayer: number;
+    candidateSignal: {
+        lambda: number;
+        lambdaPrev: number;
+        boundaryConcentration: number;
+        flags: number;
+        timestamp: string;
+    };
+    thresholds: {
+        minLambdaForExit: number;
+        minLambdaStability: number;
+        maxBoundaryConcentration: number;
+        minConfidence: number;
+    };
+    predictedLayers: Array<{
+        layerIndex: number;
+        layerType: TestLayerType;
+        outcome: PredictedOutcome;
+        confidence: number;
+        evidenceClass: 'PREDICTED';
+    }>;
+    predictedVerdict: 'pass' | 'fail' | 'inconclusive';
+    fullRunVerdict: 'pass' | 'fail';
+    falsePass: boolean;
+    falseFail: boolean;
+    firstMissedFailure?: {
+        layerIndex: number;
+        layerType: TestLayerType;
+        failedTests: number;
+    };
+    estimatedSavings: number;
+    actualSavings: 0;
+    context?: ShadowCalibrationContext;
 }
 /**
  * Metrics for early exit system performance
@@ -267,5 +316,7 @@ export interface EarlyExitMetrics {
     falsePositiveRate: number;
     /** False negative rate (didn't exit when should have) */
     falseNegativeRate: number;
+    /** Candidate exits observed while full execution remained authoritative. */
+    shadowCandidateCount: number;
 }
 //# sourceMappingURL=types.d.ts.map