/**
 * `runOptimization` — the improvement loop body. Runs N generations: the
 * `SurfaceProposer` proposes K candidate surfaces per generation, each
 * candidate runs a campaign (the measurement), top-scoring promote to the
 * next generation. Proposer-agnostic — the same loop runs an evolutionary
 * population mutator (`evolutionaryProposer`) or any reflective / agentic
 * proposer; they differ only in how `propose()` picks candidates.
 *
 * This is `runLoop`'s shape (plan → measure → decide) specialized to surface
 * improvement: `proposer.propose` = plan, `runCampaign` = the measurement
 * (which runs the worker behind `dispatch`), the mean-composite ranking = the
 * validator, `proposer.decide` = the stop check.
 *
 * The gated-promotion shell (`runImprovementLoop`) wraps this with a holdout
 * re-score + release gate + optional PR.
 */
import { type RunCampaignOptions } from '../run-campaign';
import { type CampaignResult, type GenerationRecord, type MutableSurface, type ParetoParent, type Scenario, type SurfaceProposer } from '../types';
export interface RunOptimizationBaseOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch'> {
    /** Initial mutable surface (typically system prompt or addendum). */
    baselineSurface: MutableSurface;
    /** Dispatcher that takes the CURRENT surface + scenario → artifact. */
    dispatchWithSurface: (surface: MutableSurface, scenario: TScenario, ctx: Parameters<RunCampaignOptions<TScenario, TArtifact>['dispatch']>[1]) => Promise<TArtifact>;
    /** The candidate-generation strategy. Wrap a population `Mutator` via
     *  `evolutionaryProposer({ mutator })`, or pass any reflective / agentic
     *  proposer that implements `SurfaceProposer`. */
    proposer: SurfaceProposer;
    populationSize: number;
    maxGenerations: number;
    /** How many top-scoring candidates carry to the next generation. Default 2. */
    promoteTopK?: number;
    /** DEPTH knob forwarded to the proposer's `propose()` — max iterations the
     *  agentic generator may take per candidate. */
    maxImprovementShots?: number;
    /** Optional analysis report forwarded to `propose()`. Opaque here; the
     *  proposer types it. */
    report?: unknown;
    /** Structured findings forwarded to `propose()` as `ctx.findings`. A
     *  findings producer emits these from the
     *  generation's traces; findings-grounded proposers consume them. Opaque here;
     *  the proposer types its `TFindings`. Empty when no producer is wired. */
    findings?: unknown[];
    /** Per-generation findings producer. After each
     *  generation's candidates are scored, this is called with that generation's
     *  results; whatever it returns REPLACES `ctx.findings` for the NEXT
     *  generation's `propose()`, so the diagnosis is refreshed each round instead
     *  of being a static one-shot. Generic by design: the substrate does not
     *  import an analyst — the consumer plugs its trace-analyst registry / HALO
     *  here (reading the per-candidate `runDir` traces). When absent, findings
     *  stay the static `opts.findings`. */
    analyzeGeneration?: (input: {
        generation: number;
        runDir: string;
        candidates: Array<{
            surfaceHash: string;
            campaign: CampaignResult<TArtifact, TScenario>;
            composite: number;
        }>;
        history: GenerationRecord[];
    }) => Promise<unknown[]>;
}
export type RunOptimizationOptions<TScenario extends Scenario, TArtifact> = RunOptimizationBaseOptions<TScenario, TArtifact>;
export interface RunOptimizationResult<TArtifact, TScenario extends Scenario> {
    generations: Array<{
        record: GenerationRecord;
        surfaces: Array<{
            surfaceHash: string;
            surface: MutableSurface;
            campaign: CampaignResult<TArtifact, TScenario>;
        }>;
    }>;
    winnerSurface: MutableSurface;
    winnerSurfaceHash: string;
    /** Proposer label for the promoted surface. Present when the winning
     *  candidate came from a `ProposedCandidate` (a reflective proposer);
     *  absent when the winner is the baseline or a bare-surface mutator. */
    winnerLabel?: string;
    /** Proposer rationale for the promoted surface — the "because Z" that
     *  motivated the winning change. Survives to `SelfImproveResult` and the
     *  emitted provenance record. Absent when the winner is the baseline. */
    winnerRationale?: string;
    baselineCampaign: CampaignResult<TArtifact, TScenario>;
    /** The GEPA Pareto frontier across every scored surface (baseline + all
     *  generations) by per-scenario objective vector — the non-dominated set.
     *  Each generation's `propose()` received the frontier-so-far as
     *  `ctx.paretoParents`; this is the final frontier. A surface here that is
     *  NOT the winner is uniquely best on some scenario the winner loses on. */
    paretoFrontier: ParetoParent[];
}
export declare function runOptimization<TScenario extends Scenario, TArtifact>(opts: RunOptimizationOptions<TScenario, TArtifact>): Promise<RunOptimizationResult<TArtifact, TScenario>>;
export declare function surfaceHash(surface: MutableSurface): string;
//# sourceMappingURL=run-optimization.d.ts.map