@tangle-network/agent-eval 0.23.1 → 0.25.0

package/dist/reporting.d.ts

@@ -1,295 +1,10 @@
-import { D as DatasetSplit, c as DatasetManifest, a as DatasetScenario } from './dataset-B9qvlm_o.js';
-import { C as GateDecision, A as ActionableSideInfo, m as MultiShotTrialResult } from './summary-report-Ce1r4EYo.js';
-export { Y as GainDistributionBin, Z as GainDistributionFigureSpec, _ as GainDistributionOptions, a3 as ParetoFigureSpec, a4 as ParetoPoint, a5 as RESEARCH_REPORT_HARD_PAIR_FLOOR, H as ResearchReport, a6 as ResearchReportCandidate, a7 as ResearchReportDecision, a8 as ResearchReportMethodology, F as ResearchReportOptions, a9 as ResearchReportRecommendation, aa as SummaryTable, ab as SummaryTableOptions, ac as SummaryTableRow, ah as gainHistogram, ai as paretoChart, al as researchReport, an as summaryTable } from './summary-report-Ce1r4EYo.js';
-import { R as RunRecord, a as RunSplitTag } from './run-record-DNiOMBrZ.js';
-export { c as InterimReleaseConfidence, d as InterimReleaseConfidenceInput, P as PairedEvalueOptions, e as PairedEvalueSequence, f as PairedEvalueStep, R as RubricOutcomePair, g as RubricPredictiveValidityInput, h as RubricPredictiveValidityReport, i as RubricRanking, S as SequentialDecision, j as evaluateInterimReleaseConfidence, p as pairedEvalueSequence, r as rubricPredictiveValidity } from './sequential-DgU2mFsE.js';
-import './store-u47QaJ9G.js';
-
-/**
- * Release confidence gate.
- *
- * This is the production-facing composition layer over the lower-level
- * primitives:
- *   - Dataset manifests prove corpus/version coverage.
- *   - RunRecord rows prove reproducible search/holdout outcomes.
- *   - Multi-shot trace evidence carries turn counts and ASI diagnostics.
- *   - HeldOutGate decisions remain the paired promotion authority.
- *
- * The gate is intentionally pure and conservative. Missing declared evidence
- * fails closed instead of being treated as a neutral zero.
- */
-
-type ReleaseConfidenceStatus = 'pass' | 'warn' | 'fail';
-type ReleaseConfidenceAxisName = 'corpus' | 'quality' | 'generalization' | 'diagnostics' | 'efficiency';
-interface ReleaseTraceEvidence {
-    scenarioId: string;
-    candidateId?: string;
-    split?: RunSplitTag;
-    score?: number;
-    ok?: boolean;
-    turnCount?: number;
-    costUsd?: number;
-    durationMs?: number;
-    failureMode?: string;
-    asi?: ActionableSideInfo[];
-    metadata?: Record<string, unknown>;
-}
-interface ReleaseConfidenceThresholds {
-    /** Require a Dataset manifest or explicit scenarios. Default true. */
-    requireCorpus?: boolean;
-    minScenarioCount?: number;
-    minSearchRuns?: number;
-    minHoldoutRuns?: number;
-    /** Require at least one holdout scenario/run. Default true. */
-    requireHoldout?: boolean;
-    minPassRate?: number;
-    minMeanScore?: number;
-    /** Search mean may exceed holdout mean by at most this much. */
-    maxOverfitGap?: number;
-    maxMeanCostUsd?: number;
-    maxP95WallMs?: number;
-    /** Low-score/failed rows must carry ASI. Default true. */
-    requireAsiForFailures?: boolean;
-    /** Score below this is considered a failure for ASI coverage. Default 0.5. */
-    failureScoreThreshold?: number;
-}
-interface ReleaseConfidenceInput {
-    target: string;
-    candidateId?: string;
-    baselineId?: string;
-    dataset?: DatasetManifest;
-    scenarios?: readonly DatasetScenario[];
-    runs?: readonly RunRecord[];
-    traces?: readonly ReleaseTraceEvidence[];
-    gateDecision?: GateDecision | null;
-    thresholds?: ReleaseConfidenceThresholds;
-}
-interface ReleaseConfidenceAxis {
-    name: ReleaseConfidenceAxisName;
-    status: ReleaseConfidenceStatus;
-    score: number;
-    detail: string;
-}
-interface ReleaseConfidenceIssue {
-    axis: ReleaseConfidenceAxisName;
-    severity: 'critical' | 'warning';
-    code: string;
-    detail: string;
-}
-interface ReleaseConfidenceMetrics {
-    scenarioCount: number;
-    searchRuns: number;
-    holdoutRuns: number;
-    passRate: number;
-    meanScore: number;
-    searchMeanScore: number;
-    holdoutMeanScore: number;
-    overfitGap: number;
-    meanCostUsd: number;
-    p95WallMs: number;
-    failedRows: number;
-    failuresWithAsi: number;
-    singleShotTraces: number;
-    multiShotTraces: number;
-    splitCounts: Record<DatasetSplit, number>;
-    domainCounts: Record<string, number>;
-    failureModeCounts: Record<string, number>;
-    responsibleSurfaceCounts: Record<string, number>;
-}
-interface ReleaseConfidenceScorecard {
-    target: string;
-    candidateId: string | null;
-    baselineId: string | null;
-    status: ReleaseConfidenceStatus;
-    promote: boolean;
-    axes: ReleaseConfidenceAxis[];
-    issues: ReleaseConfidenceIssue[];
-    metrics: ReleaseConfidenceMetrics;
-    dataset: DatasetManifest | null;
-    gateDecision: GateDecision | null;
-    summary: string;
-}
-declare function releaseTraceEvidenceFromMultiShotTrials(trials: readonly MultiShotTrialResult[]): ReleaseTraceEvidence[];
-declare function evaluateReleaseConfidence(input: ReleaseConfidenceInput): ReleaseConfidenceScorecard;
-declare function assertReleaseConfidence(input: ReleaseConfidenceInput): ReleaseConfidenceScorecard;
-
-/**
- * Paper-grade paired statistics for held-out promotion gates.
- *
- * The promotion gate (`HeldOutGate`) needs three things:
- *
- *   1. A bootstrap confidence interval on the per-item paired delta
- *      (`pairedBootstrap`). Median delta is the headline number; the
- *      CI lower bound is what the gate checks against `pairedDeltaThreshold`.
- *   2. A non-parametric significance test on the paired deltas
- *      (`pairedWilcoxon` — re-export of `wilcoxonSignedRank` under the
- *      paper-style name).
- *   3. False-discovery-rate correction across simultaneously-tested
- *      candidate variants (`bhAdjust` — re-export of `benjaminiHochberg`).
- *
- * Why a separate file: every existing primitive lives in `statistics.ts`
- * (general) or `power-analysis.ts` (correction). Paired-bootstrap is
- * paired-only, paper-grade, and load-bearing for the promotion gate.
- * Putting it next to `statistics.ts` would require editing that file;
- * the brief forbids that. New file, new exports, no surface change.
- */
-interface PairedBootstrapResult {
-    /** Number of paired observations (after dropping unequal lengths is rejected). */
-    n: number;
-    /** Median of paired deltas (after − before). */
-    median: number;
-    /** Mean of paired deltas. */
-    mean: number;
-    /** Lower bound of the bootstrap CI on the median delta. */
-    low: number;
-    /** Upper bound of the bootstrap CI on the median delta. */
-    high: number;
-    /** Confidence level used (e.g. 0.95). */
-    confidence: number;
-    /** Number of bootstrap resamples used. */
-    resamples: number;
-}
-interface PairedBootstrapOptions {
-    /** Confidence level. Default 0.95. */
-    confidence?: number;
-    /** Bootstrap resample count. Default 2000. */
-    resamples?: number;
-    /** Statistic to bootstrap. Default 'median'. */
-    statistic?: 'median' | 'mean';
-    /** Deterministic seed. If omitted, uses Math.random(). */
-    seed?: number;
-}
-/**
- * Paired bootstrap on (after - before) deltas. Returns a CI on the
- * chosen statistic (median by default). Pairs are resampled with
- * replacement. The lower bound is what the promotion gate checks: if
- * `low > pairedDeltaThreshold`, the gain is real at the chosen
- * confidence level.
- *
- * Throws on unequal sample sizes — caller must align pairs upstream.
- */
-declare function pairedBootstrap(before: number[], after: number[], opts?: PairedBootstrapOptions): PairedBootstrapResult;
-/**
- * Paper-style alias for `wilcoxonSignedRank`. The signed-rank test on
- * paired deltas is the standard non-parametric significance test for
- * "candidate beats baseline on matched items." Use alongside the
- * bootstrap CI: bootstrap gives effect size, Wilcoxon gives p.
- */
-declare function pairedWilcoxon(before: number[], after: number[]): {
-    w: number;
-    p: number;
-};
-/**
- * Paper-style alias for `benjaminiHochberg`. Use to correct p-values
- * across multiple candidate-vs-baseline comparisons run in the same
- * promotion sweep. Returns BH-adjusted q-values and significance at
- * the requested FDR (default 0.05).
- */
-declare function bhAdjust(pValues: number[], fdr?: number): {
-    qValues: number[];
-    significant: boolean[];
-};
-
-interface RenderReleaseReportOptions {
-    title?: string;
-    runs?: readonly RunRecord[];
-    comparator?: string;
-    traceAnalystFindings?: readonly string[];
-    nextActions?: readonly string[];
-}
-declare function renderReleaseReport(scorecard: ReleaseConfidenceScorecard, options?: RenderReleaseReportOptions): string;
-
-/**
- * Bootstrap-CI promotion gate.
- *
- * In any iterative-improvement loop (GEPA, prompt evolution, dataset
- * curation), the question is "did this generation actually improve, or are
- * we celebrating noise?". With small N and noisy outcomes, point-estimate
- * deltas lie. Bootstrap confidence intervals tell the operator whether the
- * delta is real before code or prompts get promoted.
- *
- * This module is pure functions — no I/O, no model calls. Easy to unit-test
- * and to compose into any verdict gate.
- *
- * Default gate:
- *   - Bootstrap mean baseline vs candidate (1k resamples).
- *   - Compute the delta distribution; pass if the lower CI bound > 0.
- *   - Tunable confidence (default 95%) and resample count.
- *
- * Verdict semantics intentionally match the existing `experiments.jsonl`
- * vocabulary:
- *   - ADVANCE: candidate's CI lower bound > baseline mean (real win)
- *   - KEEP:    overlap, but candidate point estimate >= baseline (neutral)
- *   - REVERT:  candidate's CI upper bound < baseline mean (real regression)
- *   - INCONCLUSIVE: not enough samples or CI straddles zero with no signal
- */
-type Verdict = 'ADVANCE' | 'KEEP' | 'REVERT' | 'INCONCLUSIVE';
-interface BootstrapResult {
-    baselineMean: number;
-    candidateMean: number;
-    /** candidateMean - baselineMean, point estimate. */
-    delta: number;
-    /** Lower bound of the (1 - alpha) CI on the delta. */
-    ciLower: number;
-    /** Upper bound of the (1 - alpha) CI on the delta. */
-    ciUpper: number;
-    /** Number of bootstrap resamples used. */
-    iterations: number;
-    alpha: number;
-    verdict: Verdict;
-}
-interface BootstrapOptions {
-    /** Confidence level alpha (default 0.05 → 95% CI). */
-    alpha?: number;
-    /** Number of resamples (default 1000). */
-    iterations?: number;
-    /**
-     * Minimum total samples (baseline + candidate) below which we always
-     * return INCONCLUSIVE — bootstrap with too few samples is meaningless.
-     * Default 6 (combined).
-     */
-    minTotalSamples?: number;
-    /** RNG seed for reproducibility. Default: Math.random. */
-    seed?: number;
-}
-/**
- * Compute the bootstrap CI on (candidateMean - baselineMean) and a verdict.
- *
- * Uses simple percentile bootstrap on the difference of resampled means.
- * That's the standard non-parametric primitive — no distributional
- * assumptions, robust to skew, easy to reason about.
- */
-declare function bootstrapCi(baseline: number[], candidate: number[], options?: BootstrapOptions): BootstrapResult;
-/**
- * Judge-replay promotion gate.
- *
- * The cheap inner-loop judge that drives an evolution run is by definition
- * fast and noisy. When you're about to promote a winning variant to the
- * canonical default, you want a STRONGER judge (a more expensive model, a
- * human grader, a separately-trained reward model) to confirm the win
- * generalises beyond the inner loop.
- *
- * This helper takes raw winner + baseline outputs, scores both through the
- * stronger judge, and applies `bootstrapCi`. ADVANCE means the stronger
- * judge agrees the winner is real with the configured confidence. Doesn't
- * matter what shape your "output" is — pass a string, an object, anything
- * the judge can read.
- */
-interface JudgeReplayGateArgs<TOutput> {
-    baselineOutputs: TOutput[];
-    candidateOutputs: TOutput[];
-    /** Stronger judge — async to allow LLM calls. Return a 0..N scalar score. */
-    judge: (output: TOutput) => Promise<number> | number;
-    alpha?: number;
-    iterations?: number;
-    /** RNG seed for reproducibility. */
-    seed?: number;
-    /** Maximum concurrent judge calls. Default 4. */
-    judgeConcurrency?: number;
-}
-declare function judgeReplayGate<TOutput>(args: JudgeReplayGateArgs<TOutput>): Promise<BootstrapResult & {
-    baselineSamples: number;
-    candidateSamples: number;
-}>;
-
-export { type BootstrapOptions, type BootstrapResult, type JudgeReplayGateArgs, type PairedBootstrapOptions, type PairedBootstrapResult, type ReleaseConfidenceAxis, type ReleaseConfidenceAxisName, type ReleaseConfidenceInput, type ReleaseConfidenceIssue, type ReleaseConfidenceMetrics, type ReleaseConfidenceScorecard, type ReleaseConfidenceStatus, type ReleaseConfidenceThresholds, type ReleaseTraceEvidence, type RenderReleaseReportOptions, type Verdict, assertReleaseConfidence, bhAdjust, bootstrapCi, evaluateReleaseConfidence, judgeReplayGate, pairedBootstrap, pairedWilcoxon, releaseTraceEvidenceFromMultiShotTrials, renderReleaseReport };
+export { R as RubricOutcomePair, a as RubricPredictiveValidityInput, b as RubricPredictiveValidityReport, c as RubricRanking, r as rubricPredictiveValidity } from './rubric-predictive-validity-C0uDYwG6.js';
+export { B as BootstrapOptions, a as BootstrapResult, J as JudgeReplayGateArgs, P as PairedBootstrapOptions, b as PairedBootstrapResult, R as ReleaseConfidenceAxis, c as ReleaseConfidenceAxisName, d as ReleaseConfidenceInput, e as ReleaseConfidenceIssue, f as ReleaseConfidenceMetrics, g as ReleaseConfidenceScorecard, h as ReleaseConfidenceStatus, i as ReleaseConfidenceThresholds, j as ReleaseTraceEvidence, k as RenderReleaseReportOptions, V as Verdict, l as assertReleaseConfidence, m as bhAdjust, n as bootstrapCi, o as evaluateReleaseConfidence, p as judgeReplayGate, q as pairedBootstrap, r as pairedWilcoxon, s as releaseTraceEvidenceFromMultiShotTrials, t as renderReleaseReport } from './release-report-BNgMdqPF.js';
+export { I as InterimReleaseConfidence, a as InterimReleaseConfidenceInput, P as PairedEvalueOptions, b as PairedEvalueSequence, c as PairedEvalueStep, S as SequentialDecision, e as evaluateInterimReleaseConfidence, p as pairedEvalueSequence } from './sequential-Dgz1n51-.js';
+export { C as GainDistributionBin, F as GainDistributionFigureSpec, H as GainDistributionOptions, J as ParetoFigureSpec, K as ParetoPoint, L as RESEARCH_REPORT_HARD_PAIR_FLOOR, N as ResearchReport, O as ResearchReportCandidate, Q as ResearchReportDecision, U as ResearchReportMethodology, W as ResearchReportOptions, X as ResearchReportRecommendation, Y as SummaryTable, Z as SummaryTableOptions, _ as SummaryTableRow, $ as gainHistogram, a0 as paretoChart, a1 as researchReport, a2 as summaryTable } from './summary-report-C7VPYEj2.js';
+import './run-record-CqzahIbx.js';
+import './errors-BZ9sTdz7.js';
+import './outcome-store-D6KWmYvj.js';
+import './dataset-CiK_3LDr.js';
+import './failure-cluster-C2EGSDiT.js';
+import './store-Db2Bv8Cf.js';

package/dist/reporting.js

@@ -5,12 +5,14 @@ import {
   judgeReplayGate,
   releaseTraceEvidenceFromMultiShotTrials,
   renderReleaseReport
-} from "./chunk-7EAUOUQS.js";
+} from "./chunk-RAF443UI.js";
 import {
-  evaluateInterimReleaseConfidence,
-  pairedEvalueSequence,
   rubricPredictiveValidity
-} from "./chunk-AXHNWLIX.js";
+} from "./chunk-YRZ4M5GS.js";
+import {
+  evaluateInterimReleaseConfidence,
+  pairedEvalueSequence
+} from "./chunk-NU65VQ7M.js";
 import {
   RESEARCH_REPORT_HARD_PAIR_FLOOR,
   bhAdjust,
@@ -20,8 +22,10 @@ import {
   paretoChart,
   researchReport,
   summaryTable
-} from "./chunk-IOXMGMHQ.js";
-import "./chunk-6M774GY6.js";
+} from "./chunk-2A5XJB43.js";
+import "./chunk-I4MBDTY5.js";
+import "./chunk-4F5DQN55.js";
+import "./chunk-NG236HPC.js";
 import "./chunk-PZ5AY32C.js";
 export {
   RESEARCH_REPORT_HARD_PAIR_FLOOR,

package/dist/{eval-campaign-Ds5QljIh.d.ts → researcher-BPT8x_NT.d.ts}

@@ -1,8 +1,9 @@
-import { C as GateDecision, F as ResearchReportOptions, H as ResearchReport } from './summary-report-Ce1r4EYo.js';
-import { R as RunRecord, a as RunSplitTag, b as RunTokenUsage, c as RunJudgeMetadata } from './run-record-DNiOMBrZ.js';
-import { R as RawProviderSink, P as ProviderRedactor, a as RunIntegrityExpectations, b as RunIntegrityReport } from './integrity-Cr5YodSY.js';
-import { T as TraceEmitter, R as RunCompleteHook } from './emitter-B2XqDKFU.js';
-import { T as TraceStore } from './store-u47QaJ9G.js';
+import { A as AgentEvalError, C as CaptureIntegrityError } from './errors-BZ9sTdz7.js';
+import { R as RawProviderSink, P as ProviderRedactor, a as RunIntegrityExpectations, b as RunIntegrityReport } from './integrity-DK2EBVZC.js';
+import { a as RunSplitTag, b as RunTokenUsage, c as RunJudgeMetadata, R as RunRecord } from './run-record-CqzahIbx.js';
+import { W as ResearchReportOptions, N as ResearchReport, a3 as GateDecision } from './summary-report-C7VPYEj2.js';
+import { T as TraceEmitter, R as RunCompleteHook } from './emitter-DP_cSSiw.js';
+import { T as TraceStore } from './store-Db2Bv8Cf.js';
 
 /**
  * LLM client with graceful degrade.
@@ -81,7 +82,7 @@ interface LlmCallResult {
     /** Raw response body. */
     raw: Record<string, unknown>;
 }
-declare class LlmCallError extends Error {
+declare class LlmCallError extends AgentEvalError {
     readonly status: number;
     readonly body: string;
     readonly model: string;
@@ -147,10 +148,11 @@ declare function callLlmJson<T = unknown>(req: LlmCallRequest, opts?: LlmClientO
     value: T;
     result: LlmCallResult;
 }>;
-declare class LlmRouteAssertionError extends Error {
-    readonly code: 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider';
+type LlmRouteAssertionReason = 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider';
+declare class LlmRouteAssertionError extends CaptureIntegrityError {
+    readonly reason: LlmRouteAssertionReason;
     readonly baseUrl: string;
-    constructor(message: string, code: 'no_explicit_base_url' | 'base_url_blocked' | 'base_url_not_allowed' | 'no_auth' | 'wrong_provider', baseUrl: string);
+    constructor(message: string, reason: LlmRouteAssertionReason, baseUrl: string);
 }
 interface LlmRouteRequirements {
     /**
@@ -218,143 +220,6 @@ declare class LlmClient {
     }>;
 }
 
-/**
- * Researcher interface — stable hook for an external autonomous-research
- * agent to drive the meta-loop.
- *
- * Implementations live downstream (typically in a private repo that
- * runs the actual LLM). This package ships only the contract + a
- * `NoopResearcher` so consumers can wire the surface without being
- * forced to implement every method up front.
- *
- * The four methods mirror the four stages of the paper "Two Loops,
- * Three Roles":
- *
- *   inspectFailures   — given the observed runs, what failure modes
- *                       are present? (data → diagnosis)
- *   proposeChange     — given diagnosed failure modes, what
- *                       structural changes should we try?
- *                       (diagnosis → plan delta)
- *   applyChange       — fold the proposed deltas into a concrete
- *                       experiment plan against an existing baseline.
- *                       (plan delta → executable plan)
- *   evaluateChange    — run the plan, return runs + the gate verdict.
- *                       (executable plan → verdict)
- *
- * Composition is the discipline: a Researcher implementation MUST
- * keep these four steps separate and inspectable. Conflating
- * "diagnose + propose + run" into a single LLM call defeats the
- * point of the framework — you can't audit which step lied.
- *
- * THIS INTERFACE IS STABLE. Breaking changes require a new module
- * (e.g. `Researcher2`) so existing implementations keep working.
- */
-
-/** A diagnosed failure mode with the run-IDs that exhibit it. */
-interface FailureMode {
-    /** Short machine-readable code. Must be stable across runs of the
-     *  same researcher to enable longitudinal tracking. */
-    code: string;
-    /** Human-readable description for the paper / dashboard. */
-    description: string;
-    evidence: {
-        /** Run IDs (from `RunRecord.runId`) where this failure mode was
-         *  observed. */
-        runIds: string[];
-        /** Number of run samples that informed the diagnosis. */
-        samples: number;
-    };
-}
-/** A single steering change the researcher wants to try. */
-interface SteeringChange {
-    kind: 'reviewer_prompt' | 'skill_add' | 'skill_remove' | 'threshold' | 'budget';
-    /** Implementation-specific payload. Researcher implementations
-     *  define the schema — keep this `unknown` here to avoid coupling
-     *  the public interface to any one researcher's internal model. */
-    payload: unknown;
-    /** Why the researcher proposed this change. Goes into the audit
-     *  trail next to the failure-mode evidence. */
-    rationale: string;
-    /** Optional self-reported expected delta on the headline metric. */
-    expectedDelta?: number;
-}
-/** A single experiment plan, mapped onto the search/holdout splits. */
-interface ExperimentPlan {
-    baselineCandidateId: string;
-    proposedCandidateId: string;
-    changes: SteeringChange[];
-    /** USD ceiling for the entire experiment. The runner must stop
-     *  before exceeding this and report a partial result. */
-    evaluationBudgetUsd: number;
-    /** Item IDs (your dataset keys) for the search vs holdout splits. */
-    splits: {
-        search: string[];
-        holdout: string[];
-    };
-}
-/** Result of running a plan: every run, plus the gate verdict. */
-interface ExperimentResult {
-    plan: ExperimentPlan;
-    runs: RunRecord[];
-    gateDecision: GateDecision;
-}
-/**
- * The researcher loop. Stable, four-step, inspectable.
- *
- *   ┌──────────┐  inspectFailures  ┌──────────┐  proposeChange ┌──────────┐
- *   │   runs   │ ─────────────────▶│ failures │ ──────────────▶│ changes  │
- *   └──────────┘                   └──────────┘                └────┬─────┘
- *                                                                   │
- *                                                                   ▼
- *                              ┌────────────────┐  applyChange ┌────────┐
- *                              │ ExperimentPlan │ ◀────────────│  base  │
- *                              └────────┬───────┘              └────────┘
- *                                       │
- *                       evaluateChange  ▼
- *                              ┌────────────────┐
- *                              │ ExperimentResult│
- *                              └────────────────┘
- */
-interface Researcher {
-    inspectFailures(runs: RunRecord[]): Promise<FailureMode[]>;
-    proposeChange(failures: FailureMode[]): Promise<SteeringChange[]>;
-    applyChange(changes: SteeringChange[], baseline: ExperimentPlan): Promise<ExperimentPlan>;
-    evaluateChange(plan: ExperimentPlan): Promise<ExperimentResult>;
-}
-interface CallbackResearcherOptions {
-    inspectFailures: Researcher['inspectFailures'];
-    proposeChange: Researcher['proposeChange'];
-    applyChange: Researcher['applyChange'];
-    evaluateChange: Researcher['evaluateChange'];
-}
-/**
- * Minimal concrete researcher for tests, scripts, and small integrations.
- * Larger autonomous researchers can still implement `Researcher` directly.
- */
-declare class CallbackResearcher implements Researcher {
-    private readonly callbacks;
-    constructor(callbacks: CallbackResearcherOptions);
-    inspectFailures(runs: RunRecord[]): Promise<FailureMode[]>;
-    proposeChange(failures: FailureMode[]): Promise<SteeringChange[]>;
-    applyChange(changes: SteeringChange[], baseline: ExperimentPlan): Promise<ExperimentPlan>;
-    evaluateChange(plan: ExperimentPlan): Promise<ExperimentResult>;
-}
-/**
- * No-op researcher — fails loud on every method. Use as a placeholder
- * in code paths that wire the interface but don't have an implementation
- * yet. Importantly, this does NOT silently succeed: a no-op researcher
- * that returned empty arrays would muffle the loop's signal that
- * nobody implemented the brain.
- */
-declare class NoopResearcher implements Researcher {
-    private readonly hint;
-    constructor(hint?: string);
-    inspectFailures(_runs: RunRecord[]): Promise<FailureMode[]>;
-    proposeChange(_failures: FailureMode[]): Promise<SteeringChange[]>;
-    applyChange(_changes: SteeringChange[], _baseline: ExperimentPlan): Promise<ExperimentPlan>;
-    evaluateChange(_plan: ExperimentPlan): Promise<ExperimentResult>;
-}
-
 /**
  * EvalCampaign — opinionated matrix runner that wires the four
  * capture-integrity directives by construction.
@@ -570,4 +435,141 @@ interface EvalCampaignResult {
 }
 declare function runEvalCampaign<V>(opts: EvalCampaignOptions<V>): Promise<EvalCampaignResult>;
 
+/**
+ * Researcher interface — stable hook for an external autonomous-research
+ * agent to drive the meta-loop.
+ *
+ * Implementations live downstream (typically in a private repo that
+ * runs the actual LLM). This package ships only the contract + a
+ * `NoopResearcher` so consumers can wire the surface without being
+ * forced to implement every method up front.
+ *
+ * The four methods mirror the four stages of the paper "Two Loops,
+ * Three Roles":
+ *
+ *   inspectFailures   — given the observed runs, what failure modes
+ *                       are present? (data → diagnosis)
+ *   proposeChange     — given diagnosed failure modes, what
+ *                       structural changes should we try?
+ *                       (diagnosis → plan delta)
+ *   applyChange       — fold the proposed deltas into a concrete
+ *                       experiment plan against an existing baseline.
+ *                       (plan delta → executable plan)
+ *   evaluateChange    — run the plan, return runs + the gate verdict.
+ *                       (executable plan → verdict)
+ *
+ * Composition is the discipline: a Researcher implementation MUST
+ * keep these four steps separate and inspectable. Conflating
+ * "diagnose + propose + run" into a single LLM call defeats the
+ * point of the framework — you can't audit which step lied.
+ *
+ * THIS INTERFACE IS STABLE. Breaking changes require a new module
+ * (e.g. `Researcher2`) so existing implementations keep working.
+ */
+
+/** A diagnosed failure mode with the run-IDs that exhibit it. */
+interface FailureMode {
+    /** Short machine-readable code. Must be stable across runs of the
+     *  same researcher to enable longitudinal tracking. */
+    code: string;
+    /** Human-readable description for the paper / dashboard. */
+    description: string;
+    evidence: {
+        /** Run IDs (from `RunRecord.runId`) where this failure mode was
+         *  observed. */
+        runIds: string[];
+        /** Number of run samples that informed the diagnosis. */
+        samples: number;
+    };
+}
+/** A single steering change the researcher wants to try. */
+interface SteeringChange {
+    kind: 'reviewer_prompt' | 'skill_add' | 'skill_remove' | 'threshold' | 'budget';
+    /** Implementation-specific payload. Researcher implementations
+     *  define the schema — keep this `unknown` here to avoid coupling
+     *  the public interface to any one researcher's internal model. */
+    payload: unknown;
+    /** Why the researcher proposed this change. Goes into the audit
+     *  trail next to the failure-mode evidence. */
+    rationale: string;
+    /** Optional self-reported expected delta on the headline metric. */
+    expectedDelta?: number;
+}
+/** A single experiment plan, mapped onto the search/holdout splits. */
+interface ExperimentPlan {
+    baselineCandidateId: string;
+    proposedCandidateId: string;
+    changes: SteeringChange[];
+    /** USD ceiling for the entire experiment. The runner must stop
+     *  before exceeding this and report a partial result. */
+    evaluationBudgetUsd: number;
+    /** Item IDs (your dataset keys) for the search vs holdout splits. */
+    splits: {
+        search: string[];
+        holdout: string[];
+    };
+}
+/** Result of running a plan: every run, plus the gate verdict. */
+interface ExperimentResult {
+    plan: ExperimentPlan;
+    runs: RunRecord[];
+    gateDecision: GateDecision;
+}
+/**
+ * The researcher loop. Stable, four-step, inspectable.
+ *
+ *   ┌──────────┐  inspectFailures  ┌──────────┐  proposeChange ┌──────────┐
+ *   │   runs   │ ─────────────────▶│ failures │ ──────────────▶│ changes  │
+ *   └──────────┘                   └──────────┘                └────┬─────┘
+ *                                                                   │
+ *                                                                   ▼
+ *                              ┌────────────────┐  applyChange ┌────────┐
+ *                              │ ExperimentPlan │ ◀────────────│  base  │
+ *                              └────────┬───────┘              └────────┘
+ *                                       │
+ *                       evaluateChange  ▼
+ *                              ┌────────────────┐
+ *                              │ ExperimentResult│
+ *                              └────────────────┘
+ */
+interface Researcher {
+    inspectFailures(runs: RunRecord[]): Promise<FailureMode[]>;
+    proposeChange(failures: FailureMode[]): Promise<SteeringChange[]>;
+    applyChange(changes: SteeringChange[], baseline: ExperimentPlan): Promise<ExperimentPlan>;
+    evaluateChange(plan: ExperimentPlan): Promise<ExperimentResult>;
+}
+interface CallbackResearcherOptions {
+    inspectFailures: Researcher['inspectFailures'];
+    proposeChange: Researcher['proposeChange'];
+    applyChange: Researcher['applyChange'];
+    evaluateChange: Researcher['evaluateChange'];
+}
+/**
+ * Minimal concrete researcher for tests, scripts, and small integrations.
+ * Larger autonomous researchers can still implement `Researcher` directly.
+ */
+declare class CallbackResearcher implements Researcher {
+    private readonly callbacks;
+    constructor(callbacks: CallbackResearcherOptions);
+    inspectFailures(runs: RunRecord[]): Promise<FailureMode[]>;
+    proposeChange(failures: FailureMode[]): Promise<SteeringChange[]>;
+    applyChange(changes: SteeringChange[], baseline: ExperimentPlan): Promise<ExperimentPlan>;
+    evaluateChange(plan: ExperimentPlan): Promise<ExperimentResult>;
+}
+/**
+ * No-op researcher — fails loud on every method. Use as a placeholder
+ * in code paths that wire the interface but don't have an implementation
+ * yet. Importantly, this does NOT silently succeed: a no-op researcher
+ * that returned empty arrays would muffle the loop's signal that
+ * nobody implemented the brain.
+ */
+declare class NoopResearcher implements Researcher {
+    private readonly hint;
+    constructor(hint?: string);
+    inspectFailures(_runs: RunRecord[]): Promise<FailureMode[]>;
+    proposeChange(_failures: FailureMode[]): Promise<SteeringChange[]>;
+    applyChange(_changes: SteeringChange[], _baseline: ExperimentPlan): Promise<ExperimentPlan>;
+    evaluateChange(_plan: ExperimentPlan): Promise<ExperimentResult>;
+}
+
 export { CallbackResearcher as C, type EvalCampaignOptions as E, type FailedRun as F, type LlmClientOptions as L, NoopResearcher as N, type Researcher as R, type SteeringChange as S, type CallbackResearcherOptions as a, type CampaignFactoryParams as b, type CampaignIntegrityPolicy as c, type CampaignRunContext as d, type CampaignRunOutcome as e, type CampaignRunner as f, type CampaignScenario as g, type CampaignVariant as h, type EvalCampaignResult as i, type ExperimentPlan as j, type ExperimentResult as k, type FailureMode as l, LlmCallError as m, type LlmCallRequest as n, type LlmCallResult as o, LlmClient as p, type LlmMessage as q, runEvalCampaign as r, LlmRouteAssertionError as s, type LlmRouteRequirements as t, type LlmUsage as u, assertLlmRoute as v, callLlm as w, callLlmJson as x, probeLlm as y, stripFencedJson as z };