@tangle-network/agent-eval 0.117.1 → 0.118.1

package/dist/gepa-eESocoDi.d.ts

@@ -1,642 +0,0 @@
-import { D as DatasetScenario, c as Dataset } from './dataset-NENEzRgk.js';
-import { T as TraceStore } from './store-DGqD0Pyo.js';
-import { C as ChatClient } from './policy-edit-wG9uFEFm.js';
-import { S as Scenario, b as JudgeConfig, C as CampaignResult, m as GateResult, k as DispatchFn, L as LabeledScenarioStore, i as CampaignTraceWriter, o as GenerationRecord, M as MutableSurface, P as ParetoParent, c as SurfaceProposer, G as Gate } from './types-BSw1rOUB.js';
-import { C as CostLedger, b as CostLedgerSummary } from './cost-ledger-DWy3XdJc.js';
-import { L as LlmCallMetadata, a as LlmClientOptions } from './llm-client-qoDd18Qz.js';
-import { C as CampaignStorage } from './storage-DrX3v_5B.js';
-
-/**
- * Pareto frontier — multi-objective optimization over candidate runs.
- *
- * Lifted from ADC pareto.ts and blueprint-agent frontier.ts. When you're
- * trading off (cost, latency, quality) or (passRate, tokenBudget,
- * ttfb), you rarely have a single "winner" — you have a set of
- * non-dominated candidates. This module exposes:
- *
- *   - `paretoFrontier`: filter a set of candidates to the non-dominated ones
- *   - `dominates`: does A dominate B across all objectives?
- *
- * Each objective is declared with a direction: 'maximize' (higher=better)
- * or 'minimize' (lower=better). Candidates are any object; pass an
- * `objective(candidate)` accessor.
- */
-type Direction = 'maximize' | 'minimize';
-interface Objective<T> {
-    /** Stable label used in reports. */
-    name: string;
-    direction: Direction;
-    value: (candidate: T) => number;
-}
-interface ParetoResult<T> {
-    frontier: T[];
-    dominated: T[];
-    /** Index map: frontier[i] dominates each of dominatedBy[i]. */
-    dominanceMap: Array<{
-        dominator: T;
-        dominated: T[];
-    }>;
-}
-/** Does candidate A weakly dominate B — strictly better on at least one objective and no worse on any? */
-declare function dominates<T>(a: T, b: T, objectives: Objective<T>[]): boolean;
-/**
- * Compute the non-dominated frontier. Candidates with NaN/Infinity on any
- * objective are excluded (can't rank them). A candidate enters the frontier
- * iff no other candidate dominates it.
- */
-declare function paretoFrontier<T>(candidates: T[], objectives: Objective<T>[]): ParetoResult<T>;
-/**
- * Weighted-sum scalarisation. Use as a tie-break / single-winner selector
- * when callers don't want to consume a frontier. Each objective contributes
- * its normalised value (0..1 via min-max across the candidate pool) times
- * its weight; missing weights default to 1/N.
- *
- * Direction is honoured automatically — `minimize` axes have their values
- * inverted before scaling so "higher scalar = better" always holds.
- */
-declare function scalarScore<T>(candidates: T[], objectives: Objective<T>[], options?: {
-    weights?: Partial<Record<string, number>>;
-}): Array<{
-    candidate: T;
-    score: number;
-}>;
-/**
- * NSGA-II crowding distance — secondary sort for ties on the frontier.
- *
- * When the Pareto front collapses to a single point (or many candidates tie
- * on dominance), naive selection picks arbitrarily and the population
- * degenerates over generations. NSGA-II preserves diversity by preferring
- * candidates with more empty space around them on the frontier.
- *
- * Returns an array of `{ candidate, distance }` in the SAME order as the
- * input. Higher distance = more isolated = should be preferred when
- * preserving diversity.
- */
-declare function crowdingDistance<T>(candidates: T[], objectives: Objective<T>[]): Array<{
-    candidate: T;
-    distance: number;
-}>;
-/**
- * Pareto frontier with tie-break by crowding distance — the canonical
- * NSGA-II selection step. Returns the frontier sorted by descending crowding
- * distance so callers can `.slice(0, k)` to pick K diverse winners.
- */
-declare function paretoFrontierWithCrowding<T>(candidates: T[], objectives: Objective<T>[]): Array<{
-    candidate: T;
-    distance: number;
-}>;
-
-/**
- * Red-team battery — adversarial scenario corpus with per-category
- * scorers.
- *
- * Every scenario is a `DatasetScenario` with a `redTeam: {...}` payload
- * that declares: category, expected refusal, attack surface. Scorers
- * inspect the agent's output + trajectory and return a PASS/FAIL per
- * category. Aggregated via `redTeamReport`.
- *
- * The built-in corpus is intentionally conservative — 40 cases
- * covering the most-seen attack patterns. Extend via `extendCorpus`.
- */
-
-type RedTeamCategory = 'prompt_injection_direct' | 'prompt_injection_indirect' | 'jailbreak_persona' | 'jailbreak_dan' | 'pii_leak' | 'permission_escalation' | 'data_exfil' | 'policy_override';
-interface RedTeamPayload {
-    category: RedTeamCategory;
-    /** The hostile input the agent sees. */
-    input: string;
-    /**
-     * What a safe agent should do: "refuse" means explicit refusal,
-     * "ignore" means process benignly without executing the attack.
-     */
-    expected: 'refuse' | 'ignore';
-    /** Substring(s) that MUST NOT appear in output. */
-    forbiddenStrings?: string[];
-    /** Tool names the agent MUST NOT call for this scenario. */
-    forbiddenTools?: string[];
-}
-interface RedTeamCase extends DatasetScenario {
-    payload: RedTeamPayload;
-}
-interface RedTeamFinding {
-    scenarioId: string;
-    category: RedTeamCategory;
-    passed: boolean;
-    reason: string;
-    evidence?: string;
-}
-interface RedTeamReport {
-    findings: RedTeamFinding[];
-    passRateByCategory: Record<RedTeamCategory, number>;
-    overallPassRate: number;
-}
-/** Ship a canonical, small corpus. Consumers extend via `extendCorpus`. */
-declare const DEFAULT_RED_TEAM_CORPUS: RedTeamCase[];
-declare function redTeamDataset(extraCases?: RedTeamCase[]): Dataset;
-/**
- * Score a single agent response against the red-team case.
- * `toolCalls` should be the names of tools the agent invoked during the run.
- */
-declare function scoreRedTeamOutput(output: string, toolCalls: string[], rtCase: RedTeamCase): RedTeamFinding;
-/** Aggregate red-team findings into per-category pass rates. */
-declare function redTeamReport(findings: RedTeamFinding[]): RedTeamReport;
-/**
- * Extract the tool-call names from a corpus run — convenience for the
- * common pipeline (run the scenario → score the run).
- */
-declare function toolNamesForRun(store: TraceStore, runId: string): Promise<string[]>;
-
-declare const REFERENCE_EQUIVALENCE_JUDGE_VERSION = "reference-equivalence-judge-v1-2026-07-13";
-declare const REFERENCE_EQUIVALENCE_INPUT_LIMITS: {
-    readonly userRequest: 8000;
-    readonly expectedAnswer: 32000;
-    readonly candidateOutput: 32000;
-};
-interface ReferenceEquivalenceScenario extends Scenario {
-    userRequest: string;
-    expectedAnswer: string;
-}
-interface ReferenceEquivalenceJudgeInput {
-    userRequest: string;
-    expectedAnswer: string;
-    candidateOutput: string;
-}
-interface ReferenceEquivalenceJudgeOptions {
-    /** Injected transport. No implicit provider or credentials are selected. */
-    chat: ChatClient;
-    /** Falls back to the ChatClient's default model. */
-    model?: string;
-    /** Used only by the direct-call adapter. */
-    signal?: AbortSignal;
-    /** Optional receipt destination for direct calls; campaigns supply their own. */
-    costLedger?: CostLedger;
-}
-interface ReferenceEquivalenceJudgeResult extends LlmCallMetadata {
-    kind: 'reference-equivalence';
-    version: string;
-    score: number;
-    rationale: string;
-}
-/** Build the campaign-native expected-answer judge. */
-declare function createReferenceEquivalenceJudge(options: ReferenceEquivalenceJudgeOptions): JudgeConfig<string, ReferenceEquivalenceScenario>;
-/** Direct-call adapter over the campaign judge for product callers. */
-declare function runReferenceEquivalenceJudge(input: ReferenceEquivalenceJudgeInput, options: ReferenceEquivalenceJudgeOptions): Promise<ReferenceEquivalenceJudgeResult>;
-
-/**
- * `openAutoPr` — thin shell-out helper for the `runImprovementLoop` preset's
- * `autoOnPromote: 'pr'` mode. Substitutes for the per-product PR-opening
- * code consumers duplicated 4 times. The PR body includes the campaign's
- * manifest hash, gate verdict, and scorecard summary so reviewers can see
- * exactly what was promoted + why.
- *
- * NOT a deploy mechanism — this only OPENS a PR. The human reviews + merges.
- * The Shape B (`autoOnPromote: 'config'`) live-runtime-mutation path is
- * deferred to Pass B with the full shadow / canary / rollback stack.
- */
-
-interface OpenAutoPrOptions<TArtifact, TScenario extends Scenario> {
-    /** Campaign result to attach to the PR. */
-    result: CampaignResult<TArtifact, TScenario>;
-    /** Gate verdict explaining the promotion. Substrate refuses to open a PR
-     *  when `gate.decision !== 'ship'` — fails loud. */
-    gate: GateResult;
-    /** Promoted surface diff — typically the new system prompt addendum or
-     *  full profile diff. Substrate writes it as the PR body. */
-    promotedDiff: string;
-    /** GH owner/repo target (e.g., `tangle-network/gtm-agent`). */
-    ghOwner: string;
-    ghRepo: string;
-    /** Branch name for the PR. Default `auto/<manifestHash[:12]>`. */
-    branch?: string;
-    /** PR title. Default includes manifest hash. */
-    title?: string;
-    /** Whether to actually open the PR or just dry-run. Default reads
-     *  `GH_AUTO_PR_TOKEN` env — present = open, absent = dry-run. */
-    dryRun?: boolean;
-    /** Test seam — substitute `gh pr create` invocation. */
-    ghExec?: (args: string[]) => {
-        stdout: string;
-        stderr: string;
-        status: number;
-    };
-}
-interface OpenAutoPrResult {
-    opened: boolean;
-    prUrl?: string;
-    dryRun: boolean;
-    reason: string;
-}
-/**
- * Open a GitHub PR for a gate-approved surface promotion, attaching the manifest hash, gate verdict, and diff as the PR body.
- */
-declare function openAutoPr<TArtifact, TScenario extends Scenario>(options: OpenAutoPrOptions<TArtifact, TScenario>): OpenAutoPrResult;
-
-/**
- * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
- * scenarios → dispatch → artifacts → judges → aggregates, with full
- * reproducibility (seed + manifest hash), cell-level resumability, bootstrap
- * CIs, and the `LabeledScenarioStore` capture flywheel.
- *
- * Improvement loops (optimizer / gate / autoOnPromote) ride on top of this
- * primitive but live in `presets/run-improvement-loop.ts`. This file keeps
- * the core orchestrator minimal — Phase 1 of the Pass A track.
- */
-
-interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
-    scenarios: TScenario[];
-    dispatch: DispatchFn<TScenario, TArtifact>;
-    /**
-     * Stable identity for the dispatch behavior, included in the manifest/cache
-     * key. Set this when the same function name can run different models,
-     * prompts, tools, or external config.
-     */
-    dispatchRef?: string;
-    judges?: JudgeConfig<TArtifact, TScenario>[];
-    /** Required for reproducibility. Default 42. */
-    seed?: number;
-    /** Per-scenario replicates for CI bands. Default 1; raise to 5+ for
-     *  bootstrap-tight intervals on critical eval. */
-    reps?: number;
-    /** When true (default), completed cells are cached by
-     *  (manifestHash, scenarioId, rep, generation). Re-runs skip cached cells. */
-    resumable?: boolean;
-    /** Optional store — when present, every artifact + judge score is captured
-     *  with the configured `captureSource`. Capture is default ON; pass `'off'`
-     *  to disable. */
-    labeledStore?: LabeledScenarioStore | 'off';
-    captureSource?: 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
-    captureSourceVersionHash?: string;
-    /** Hard spend cap. Each paid call reserves its enforced maximum before dispatch. */
-    costCeiling?: number;
-    /** Shared spend account. Improvement loops pass one ledger through every
-     *  campaign so the ceiling and returned total are run-wide. */
-    costLedger?: CostLedger;
-    /** Attribution label for receipts recorded by this campaign. */
-    costPhase?: string;
-    /** Max concurrent cells. Default 2. */
-    maxConcurrency?: number;
-    /**
-     * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
-     * rejects within this window is a hang (a stalled model request, an
-     * exhausted runtime resource, a backend that never closes its stream). When
-     * set, the cell's `ctx.signal` is aborted and the cell is recorded as a LOUD
-     * error (`dispatch exceeded <N>ms`) so the campaign proceeds and the failure
-     * is visible — instead of one wedged cell silently hanging the whole run (and
-     * every loop/CI job above it) forever. `undefined`/`0` = unbounded (legacy).
-     */
-    dispatchTimeoutMs?: number;
-    /** Required: where artifacts + traces land. A bare name (not an absolute path)
-     *  resolves to the shared `~/.tangle/traces/<repo>/runs/<name>` root so run
-     *  bundles never pollute a repo working tree. Pass an absolute path to override. */
-    runDir: string;
-    /** Subject repo for the shared run-dir root (defaults to the CWD basename).
-     *  Only consulted when `runDir` is a bare name. */
-    repo?: string;
-    /** Tracing posture. Default is the substrate's `FileSystemTraceStore` rooted
-     *  at `<runDir>/traces/`. `'off'` disables capture entirely — substrate
-     *  refuses this when the caller wires `autoOnPromote !== 'none'`. */
-    tracing?: 'on' | 'off';
-    /**
-     * Per-cell usage expectation — the early, fine-grained sibling of the
-     * batch `assertRealBackend` guard. A cell that produced an artifact (no
-     * error) but reported `costUsd === 0` AND zero tokens is a stub: the
-     * dispatch never reported LLM activity via `ctx.cost`. Modes:
-     *   - `'warn'` (default) — log the offending cell loudly, keep going.
-     *   - `'assert'` — throw `BackendIntegrityError` on the first such cell
-     *     (fail-fast; recommended for CI campaigns expecting real LLM calls).
-     *   - `'off'` — no check (replay / deterministic-only / offline analysis).
-     */
-    expectUsage?: 'assert' | 'warn' | 'off';
-    /** Test seam — override the wall clock for deterministic tests. */
-    now?: () => Date;
-    /** Test seam — override per-cell trace writer factory. */
-    buildTraceWriter?: (cellId: string, dir: string) => CampaignTraceWriter;
-    /** Storage backend for run/cell dirs, the resumability cache, artifacts,
-     *  and trace spans. Default: the Node filesystem (`fsCampaignStorage`).
-     *  Pass `inMemoryCampaignStorage()` to run in a filesystem-less runtime
-     *  (Cloudflare Workers, Deno, edge) — the `CampaignResult` is still
-     *  produced; artifacts/traces just aren't persisted to disk. */
-    storage?: CampaignStorage;
-    /**
-     * Optional per-cell placement strategy. Returns an opaque string the
-     * substrate forwards as `ctx.placement` to the Dispatch — placement-aware
-     * Dispatches (e.g. `httpDispatch` from `/adapters/http`) use it to route
-     * each cell to the right worker, region, or sandbox. When unset, every
-     * cell receives `ctx.placement = undefined` and behaves identically to
-     * the in-process case.
-     *
-     * @example
-     *   cellPlacement: ({ scenario }) => scenario.tags?.includes('eu') ? 'eu-west' : 'us-east'
-     */
-    cellPlacement?: (input: {
-        scenario: TScenario;
-        rep: number;
-        generation?: number;
-    }) => string | undefined;
-}
-/**
- * Core campaign orchestrator: fan scenarios through dispatch, score with judges, aggregate bootstrap CIs, and persist reproducible `CampaignResult` records.
- */
-declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
-interface CampaignRunPlanCell {
-    cellId: string;
-    scenarioId: string;
-    rep: number;
-    seed: number;
-    cachePath: string;
-    status: 'cached' | 'run';
-    reason?: 'missing' | 'manifest-mismatch' | 'cell-mismatch' | 'corrupt' | 'resumable-off';
-}
-interface CampaignRunPlan {
-    manifestHash: string;
-    totalCells: number;
-    cellsCached: number;
-    cellsToRun: number;
-    cells: CampaignRunPlanCell[];
-}
-interface PlanCampaignRunOptions<TScenario extends Scenario, TArtifact> {
-    scenarios: TScenario[];
-    dispatch?: DispatchFn<TScenario, TArtifact>;
-    dispatchRef?: string;
-    judges?: JudgeConfig<TArtifact, TScenario>[];
-    seed?: number;
-    reps?: number;
-    resumable?: boolean;
-    runDir: string;
-    /** Subject repo for the shared run-dir root (see RunCampaignOptions.repo). */
-    repo?: string;
-    storage?: CampaignStorage;
-}
-/**
- * Plan a campaign WITHOUT dispatching: computes the manifest hash and the per-cell
- * run-vs-cached schedule so callers can preview cost and resumability before spending.
- */
-declare function planCampaignRun<TScenario extends Scenario, TArtifact>(opts: PlanCampaignRunOptions<TScenario, TArtifact>): CampaignRunPlan;
-
-/**
- * `runOptimization` — the improvement loop body. Runs N generations: the
- * `SurfaceProposer` proposes K candidate surfaces per generation, each
- * candidate runs a campaign (the measurement), and only a candidate that beats
- * the single global incumbent becomes the next generation's parent.
- * 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.
- */
-
-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;
-    /** @deprecated The loop has one global incumbent and can promote only the
-     *  single candidate that beats it. Retained for source compatibility. */
-    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. Runs once on the BASELINE campaign
-     *  (as `generation: -1`, the baseline convention) before generation 0
-     *  proposes — so even a single-generation run proposes with trace context —
-     *  and then after each generation's candidates are scored with that
-     *  generation's results; whatever it returns REPLACES `ctx.findings` for the
-     *  NEXT `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[];
-        /** Shared run spend account and receipt attribution phase. */
-        costLedger?: CostLedger;
-        costPhase?: string;
-    }) => Promise<unknown[]>;
-}
-type RunOptimizationOptions<TScenario extends Scenario, TArtifact> = RunOptimizationBaseOptions<TScenario, TArtifact>;
-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>;
-    /** Run-wide spend, including agents, proposers, analysts, and judges. */
-    cost: CostLedgerSummary;
-    /** 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[];
-}
-/**
- * Improvement loop body: N generations of propose → campaign → rank, maintaining a Pareto frontier and one global incumbent across generations.
- */
-declare function runOptimization<TScenario extends Scenario, TArtifact>(opts: RunOptimizationOptions<TScenario, TArtifact>): Promise<RunOptimizationResult<TArtifact, TScenario>>;
-
-/**
- * `runImprovementLoop` — the gated-promotion shell around the improvement
- * loop body (`runOptimization`). Proposes candidate surfaces via the
- * `SurfaceProposer`, re-scores the winner against the baseline on a
- * holdout set, runs the release gate, and optionally opens a PR.
- *
- * Role vocabulary (see docs/design/loop-taxonomy.md):
- *   - PROPOSER   = the `SurfaceProposer` (evolutionary GEPA mutator OR
- *                  reflective analyst). Proposes candidate SURFACES — the
- *                  worker's system prompt / tool config — NOT conversation
- *                  turns.
- *   - MEASUREMENT= `runCampaign`. Scores one surface by running the worker
- *                  (via `dispatch`) over scenarios and judging the output.
- *   - WORKER     = the agent harness in the sandbox, invoked behind the
- *                  topology-opaque `dispatch` seam — never referenced here.
- *
- * Distinct from `runLoop` in `@tangle-network/agent-runtime`, which is the
- * INNER conversation loop (execution driver ↔ workers in a sandbox). `runImprovementLoop`
- * is the OUTER loop: it improves the surface that those workers run.
- *
- * Hard-refuses unsafe configurations:
- *   - `tracing: 'off'` when a proposer is wired (improvement is unattributable)
- *   - `autoOnPromote: 'config'` — DEFERRED to Pass B; v0.40 only ships
- *     `'pr'` and `'none'`.
- */
-
-type RunImprovementLoopOptions<TScenario extends Scenario, TArtifact> = RunOptimizationOptions<TScenario, TArtifact> & {
-    /** Holdout scenarios kept OUT of the training optimization pool — used
-     *  ONLY to score baseline vs winner for the gate. */
-    holdoutScenarios: TScenario[];
-    /** Promotion gate. Substrate strongly recommends `defaultProductionGate`
-     *  for production wiring (composes red-team / reward-hacking / canary /
-     *  heldout). */
-    gate: Gate<TArtifact, TScenario>;
-    /** What to do when the gate ships:
-     *   - `'pr'`: open a PR via `openAutoPr`
-     *   - `'none'`: just report — caller decides what to do with the winner
-     *  v0.40 does NOT support `'config'` (live-runtime self-mutation) —
-     *  deferred to Pass B behind safety stack. */
-    autoOnPromote: 'pr' | 'none';
-    /** GH owner / repo for the auto-PR. Required when autoOnPromote === 'pr'. */
-    ghOwner?: string;
-    ghRepo?: string;
-    /** Optional render override — substrate writes a diff-shaped surface; pass
-     *  a function to format the promoted surface differently. */
-    renderPromotedDiff?: (winnerSurface: MutableSurface, baselineSurface: MutableSurface) => string;
-    /** Placebo control. When supplied AND the winner differs from baseline, the
-     *  loop scores a THIRD holdout arm: the winner surface with its content
-     *  footprint-matched-blanked by this function (typically via `neutralizeText`).
-     *  Its scores are exposed to the gate as `ctx.neutralizedJudgeScores`, letting
-     *  a `neutralizationGate` reject a win whose lift survives blanking the content
-     *  (decorative — driven by footprint, not content). Costs one extra holdout
-     *  campaign; omit to skip. Return a byte/layout-matched blank of the winner. */
-    neutralize?: (winnerSurface: MutableSurface, baselineSurface: MutableSurface) => MutableSurface;
-};
-interface RunImprovementLoopResult<TArtifact, TScenario extends Scenario> extends RunOptimizationResult<TArtifact, TScenario> {
-    baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
-    winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
-    gateResult: Awaited<ReturnType<Gate<TArtifact, TScenario>['decide']>>;
-    /** Unified baseline→winner surface diff. Computed UNCONDITIONALLY (not only
-     *  when `autoOnPromote === 'pr'`) so the diff that the gate decided on is
-     *  always present on the result + in the emitted provenance record. Empty
-     *  string when winner == baseline (no change to diff). */
-    promotedDiff: string;
-    prResult?: ReturnType<typeof openAutoPr>;
-}
-/**
- * Gated-promotion shell over `runOptimization`: scores the winner against the baseline on a holdout set, runs the release gate, and optionally opens a PR.
- */
-declare function runImprovementLoop<TScenario extends Scenario, TArtifact>(opts: RunImprovementLoopOptions<TScenario, TArtifact>): Promise<RunImprovementLoopResult<TArtifact, TScenario>>;
-/**
- * Default surface diff renderer: produces a unified baseline/winner text diff for prompt surfaces or a worktree-ref summary for code surfaces.
- */
-declare function defaultRenderDiff(winnerSurface: MutableSurface, baselineSurface: MutableSurface): string;
-
-/**
- * `gepaProposer` — a reflective `SurfaceProposer` for prompt-tier surfaces.
- * Each generation it reflects on the prior best candidate's per-scenario
- * scores + weakest dimensions, asks an LLM to propose targeted rewrites of
- * the current surface, and returns them as the next population.
- *
- * Maps onto the GEPA paper (Agrawal et al., arXiv:2507.19457):
- *   - *Reflection*: each generation reflects on the best parent's weakest
- *     dimensions + per-scenario top/bottom scores to propose targeted rewrites.
- *   - *Pareto frontier*: `runOptimization` maintains the non-dominated set of
- *     surfaces across generations (per-scenario objective vectors) and supplies
- *     it as `ctx.paretoParents`. A surface uniquely best on one hard scenario
- *     survives even when its mean composite is lower.
- *   - *Combine complementary lessons*: when the frontier has >1 member, the
- *     first population slot is a merge of those parents' strengths (one LLM
- *     call citing each parent's winning scenarios). Toggle via `combineParents`.
- * Dominance is computed by the package-canonical `paretoFrontier` (`pareto.ts`).
- *
- * Optional `constraints` move structured-doc guards into the proposer
- * (preserve H2 section headings, cap sentence-level edits) — useful when
- * the surface IS a structured procedure like a SKILL.md / runbook /
- * judge rubric. When `constraints` is omitted, behavior is unchanged.
- *
- * The proposer is surface-agnostic — any string surface in any consumer opts
- * in by selecting it. Reuses the generic reflection primitive
- * (`buildReflectionPrompt` / `parseReflectionResponse`) and the router client.
- *
- * Earns its keep where there is real per-instance signal (which the
- * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
- * now provide). For thin-signal surfaces it degrades to plain reflection.
- * On generation 0 (no history) it reflects on the current surface against
- * the mutation primitives alone.
- */
-
-interface GepaProposerConstraints {
-    /** H2 section headings that MUST appear unchanged in every candidate.
-     *  When set, the proposer auto-detects current H2s if this is empty AND
-     *  rejects any candidate that drops or renames a preserved heading.
-     *  Use when the surface is a structured doc (SKILL.md, runbook,
-     *  sectioned system prompt, judge rubric). */
-    preserveSections?: string[];
-    /** Maximum sentence-level edits per candidate vs the parent surface.
-     *  Rejection threshold = maxSentenceEdits × 2 (counts adds + removes).
-     *  Inspired by SkillOpt's edit-budget as a "textual learning rate."
-     *  Cap prevents an LLM rewrite from overwriting useful prior rules. */
-    maxSentenceEdits?: number;
-}
-interface GepaProposerOptions {
-    /** Router transport (apiKey/baseUrl). */
-    llm: LlmClientOptions;
-    /** Model that performs the reflection. */
-    model: string;
-    /** Optional ledger for direct proposer use. Campaign context takes precedence. */
-    costLedger?: CostLedger;
-    /** What is being optimized — appears in the reflection prompt for orientation. */
-    target: string;
-    /** Surface-specific mutation levers offered to the model. */
-    mutationPrimitives?: string[];
-    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
-    evidenceK?: number;
-    /** Reflection sampling temperature. Default 0.7. */
-    temperature?: number;
-    /** Reflection max tokens. Default 6000. */
-    maxTokens?: number;
-    /** Structured-doc constraints. Candidates violating any are rejected
-     *  post-parse and dropped from the returned population. */
-    constraints?: GepaProposerConstraints;
-    /** GEPA combine-complementary-lessons: when the loop supplies a Pareto
-     *  frontier of >1 non-dominated parents (`ctx.paretoParents`), spend one
-     *  slot of the population on a merge of their strengths. Default `true` —
-     *  this is the GEPA-faithful behavior; the merge only fires once the
-     *  frontier has more than one member (generation ≥ 1). Set `false` for
-     *  pure single-parent reflection. */
-    combineParents?: boolean;
-    /** Cap on how many frontier parents feed one combine prompt (highest
-     *  composite first), to bound prompt size. Default 4. */
-    combineMaxParents?: number;
-}
-/**
- * GEPA reflective proposer: each generation reflects on the weakest scenarios and dimensions to produce targeted prompt rewrites, optionally combining Pareto-frontier parents.
- */
-declare function gepaProposer(opts: GepaProposerOptions): SurfaceProposer;
-/** Extract H2 headings (`## Foo`) from a markdown surface. Exported for
- *  consumers building custom mutators that share the same invariant. */
-declare function extractH2Sections(text: string): string[];
-/** Sentence-level edit distance — count distinct add/remove ops between
- *  two surfaces via a normalised line-by-line set diff. Treats trivial
- *  whitespace as identical. Exported for tests + consumer-side validators. */
-declare function countSentenceEdits(baseline: string, candidate: string): number;
-
-export { type ParetoResult as A, DEFAULT_RED_TEAM_CORPUS as B, type CampaignRunPlan as C, type Direction as D, type RedTeamCategory as E, type RedTeamFinding as F, type GepaProposerOptions as G, type RedTeamPayload as H, type RedTeamReport as I, crowdingDistance as J, dominates as K, paretoFrontier as L, paretoFrontierWithCrowding as M, redTeamDataset as N, type OpenAutoPrOptions as O, type PlanCampaignRunOptions as P, redTeamReport as Q, type RunOptimizationOptions as R, scalarScore as S, scoreRedTeamOutput as T, toolNamesForRun as U, type RunImprovementLoopResult as a, REFERENCE_EQUIVALENCE_INPUT_LIMITS as b, REFERENCE_EQUIVALENCE_JUDGE_VERSION as c, type ReferenceEquivalenceJudgeInput as d, type ReferenceEquivalenceJudgeOptions as e, type ReferenceEquivalenceJudgeResult as f, type ReferenceEquivalenceScenario as g, type RunCampaignOptions as h, type RunImprovementLoopOptions as i, createReferenceEquivalenceJudge as j, gepaProposer as k, runImprovementLoop as l, runReferenceEquivalenceJudge as m, type RedTeamCase as n, type CampaignRunPlanCell as o, type GepaProposerConstraints as p, type OpenAutoPrResult as q, runCampaign as r, type RunOptimizationResult as s, countSentenceEdits as t, defaultRenderDiff as u, extractH2Sections as v, openAutoPr as w, planCampaignRun as x, runOptimization as y, type Objective as z };