/**
 * Causal sweep — WHY did this run fail?
 *
 * Orchestrates the dormant counterfactual primitives into a responsibility
 * report: for each candidate step, run `reps` counterfactual replays per
 * mutation (via `runCounterfactual` — the consumer's `CounterfactualRunner`
 * is the execution seam) and reduce the per-rep score deltas into a mean
 * effect + bootstrap confidence interval (via `confidenceInterval`).
 *
 * Why `reps` is REQUIRED: a single intervention delta is one stochastic
 * draw — LLM re-execution from a prefix is sampled, so one replay cannot
 * distinguish "this step caused the failure" from sampling noise. The
 * signal is the distribution of deltas across reps; the CI over that
 * distribution is what lets a caller say "this step's effect excludes
 * zero" instead of eyeballing a point estimate.
 *
 * Budget discipline: the sweep never silently drops cells. When the
 * remaining budget cannot fund a full `reps`-sized cell, the sweep halts
 * and every step not fully probed is named in `uncovered`.
 */
import { attributeCounterfactuals, type CounterfactualMutation, type CounterfactualRunner } from '../counterfactual';
import type { Span } from '../trace/schema';
import type { TraceStore } from '../trace/store';
import { type TrajectoryStep } from '../trajectory';
/** Stable reference to a trajectory step — carried through reports,
 *  findings, and corpus records so evidence stays addressable. */
export interface StepRef {
    index: number;
    spanId: string;
    kind: Span['kind'];
    name: string;
}
export declare function stepRefOf(step: TrajectoryStep): StepRef;
export interface CausalSweepOptions {
    store: TraceStore;
    /** The failed run to diagnose. Its `outcome.score` is the baseline every
     *  counterfactual delta is measured against. */
    runId: string;
    /** Execution seam — identical contract to `runCounterfactual`: re-runs the
     *  agent from the mutation point and MUST `endRun` with a numeric score. */
    runner: CounterfactualRunner;
    /** Trajectory indices to probe. Default: every llm + tool span — the kinds
     *  the existing `CounterfactualMutation` set targets. */
    candidateSteps?: number[];
    /**
     * Mutations to probe a given step with. Returned mutations MUST target
     * `step.index`. Default probes are the payload-free existing kinds:
     *   - tool span → `swap-tool-result` with `newResult: null` (knockout:
     *     how much did the run depend on this tool's information?)
     *   - llm span → `truncate-after` (re-roll: how much did the realized
     *     turn deviate from the policy's typical continuation?)
     * `swap-model` / `inject-system-message` need consumer payloads, so they
     * are opt-in via this callback.
     */
    mutationsPerStep?: (step: TrajectoryStep) => CounterfactualMutation[];
    /** Replays per (step, mutation) cell. Minimum 2 — see module doc. */
    reps: number;
    /** Hard cap on total counterfactual replays across the whole sweep. */
    budget: number;
    /** Seed for the bootstrap CI resampler. Deterministic default so two
     *  sweeps over the same deltas report identical intervals. */
    ciSeed?: number;
    /** Bootstrap CI confidence level. Default 0.95. */
    ciConfidence?: number;
}
export interface StepResponsibility {
    stepRef: StepRef;
    mutationKind: CounterfactualMutation['kind'];
    /** Mean of per-rep score deltas (counterfactual − original). */
    meanEffect: number;
    /** Bootstrap CI over the per-rep deltas. */
    ci: {
        mean: number;
        lower: number;
        upper: number;
    };
    /** `ci.lower > 0 || ci.upper < 0` — the effect is distinguishable from noise. */
    ciExcludesZero: boolean;
    reps: number;
    /** Raw per-rep deltas — downstream evidence, never re-derived. */
    deltas: number[];
    /** Replay run ids (layer='meta', parentRunId=original) for audit. */
    counterfactualRunIds: string[];
}
export interface CausalResponsibilityReport {
    runId: string;
    originalScore: number;
    /** Ranked by |meanEffect| descending — the blame ordering. */
    steps: StepResponsibility[];
    /** Kind-level aggregate from the existing `attributeCounterfactuals`. */
    byMutationKind: ReturnType<typeof attributeCounterfactuals>;
    replaysUsed: number;
    budget: number;
    /** Steps planned but not fully probed before the budget ran out.
     *  Named, never silent: an absent step is "no effect found"; an
     *  uncovered step is "not measured". */
    uncovered: StepRef[];
}
export declare function causalSweep(opts: CausalSweepOptions): Promise<CausalResponsibilityReport>;
//# sourceMappingURL=causal-sweep.d.ts.map