@tangle-network/agent-eval 0.128.2 → 0.130.0

package/dist/skillopt-optimization-method-B7wX7XkF.d.ts

@@ -0,0 +1,1739 @@
+import { a as RunRecord } from "./run-record-CnZu_gjl.js";
+import { s as TraceStore } from "./store-CT9YIIve.js";
+import { c as CostLedgerHandle, f as CostLedgerSummary, o as CostLedger, p as CostReceipt, y as CustomTokenPricing } from "./cost-ledger-Dye6jCgg.js";
+import { n as LlmCallMetadata } from "./llm-client-B_nIBlYo.js";
+import { A as ChatClient } from "./types-DGsxbAEd.js";
+import { f as PairedBootstrapResult } from "./statistics-Cmj6nynr.js";
+import { C as JudgeDimension, H as SurfaceProposer, N as ParetoParent, R as Scenario, S as JudgeConfig, _ as GateDecision, a as CampaignResult, b as GenerationRecord, c as CampaignTraceWriter, d as DispatchContext, f as DispatchFn, g as GateContribution, h as GateContext, i as CampaignCostMeter, j as MutableSurface, k as LabeledScenarioStore, o as CampaignScenarioIdentity, p as Gate, r as CampaignCellResult, v as GateResult, y as GenerationCandidate } from "./types-k9tZGKUg.js";
+import { a as DatasetScenario, t as Dataset } from "./dataset-BvtnC8Dc.js";
+import { t as DetectRewardHackingInput } from "./reward-hacking-eAnOsynk.js";
+import { g as TraceSpanEvent, t as HostedClient } from "./client-C97NMzqi.js";
+import { z } from "zod";
+//#region src/llm-judge.d.ts
+/** A rubric dimension as a bare key or the full `{ key, description }` shape. A
+ *  bare string uses the key as its own description. */
+type LlmJudgeDimension = string | JudgeDimension;
+interface LlmJudgeOptions<TArtifact, TScenario extends Scenario = Scenario> {
+  /** The injected LLM transport. One `chat()` call per `score()`. Required —
+   *  there is no default route, so a misconfigured judge fails at construction,
+   *  never silently against the free-tier router. */
+  chat: ChatClient;
+  /** Rubric dimensions the model scores. Each becomes a `[0,1]` field of the
+   *  returned `JudgeScore.dimensions`. Defaults to a single `quality` dimension. */
+  dimensions?: LlmJudgeDimension[];
+  /** Model id. Falls back to `chat.defaultModel`; one of the two MUST resolve. */
+  model?: string;
+  /** Explicit scoring revision for opaque transport or renderer changes. */
+  judgeVersion?: string;
+  temperature?: number;
+  maxTokens?: number;
+  /** Composite weights forwarded to `weightedComposite`: a partial map selects
+   *  AND weights exactly the named dimensions. Omit for a uniform mean. */
+  weights?: Record<string, number>;
+  /** Scale the model is prompted to score on, normalized into `[0,1]`:
+   *   - `'unit'`  (default): the model returns `[0,1]` directly.
+   *   - `'ten'`:  the model returns `[0,10]`; divided by 10 here.
+   *  The prompt is annotated with the expected range either way. */
+  scale?: 'unit' | 'ten';
+  /** Run this judge only on matching scenarios (mirrors `JudgeConfig.appliesTo`). */
+  appliesTo?: (scenario: TScenario) => boolean;
+  /** Render the artifact + scenario into the user message. Default:
+   *  pretty-printed JSON of `{ scenario, artifact }`. */
+  renderUser?: (input: {
+    artifact: TArtifact;
+    scenario: TScenario;
+  }) => string;
+  /** Strict runtime contract; its JSON Schema is sent to the provider. */
+  costLedger?: CostLedgerHandle;
+  responseSchema?: {
+    name: string;
+    schema: z.ZodObject;
+  };
+}
+/**
+ * Build a campaign-shaped `JudgeConfig` whose `score()` makes ONE LLM call
+ * against `prompt` and reduces the model's per-dimension scores to a canonical
+ * `JudgeScore` in `[0,1]`.
+ *
+ * The model is instructed to return JSON `{ "dimensions": { <key>: <number>, … },
+ * "notes": "…" }`; the helper strips fenced JSON, validates every declared
+ * dimension is present and in range, normalizes by `scale`, and composites via
+ * `weightedComposite`.
+ */
+declare function llmJudge<TArtifact = unknown, TScenario extends Scenario = Scenario>(name: string, prompt: string, opts: LlmJudgeOptions<TArtifact, TScenario>): JudgeConfig<TArtifact, TScenario>;
+//#endregion
+//#region src/reference-equivalence-judge.d.ts
+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?: CostLedgerHandle;
+}
+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>;
+//#endregion
+//#region src/campaign/auto-pr.d.ts
+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;
+//#endregion
+//#region src/campaign/coverage.d.ts
+/** Reject campaign designs whose denominator cannot be identified exactly. */
+declare function assertCampaignDesign<TScenario extends Scenario>(scenarios: readonly TScenario[], reps: number): void;
+/** Redacted but independently verifiable identity of one complete scenario. */
+declare function campaignScenarioIdentity<TScenario extends Scenario>(scenario: TScenario): CampaignScenarioIdentity & Pick<TScenario, 'id' | 'kind'>;
+/** Canonical split identity reconstructed from redacted scenario identities. */
+declare function campaignSplitDigestFromIdentities(scenarios: readonly CampaignScenarioIdentity[], reps: number): `sha256:${string}`;
+/** Canonical identity of the exact scenario payloads and replicate count. */
+declare function campaignSplitDigest<TScenario extends Scenario>(scenarios: readonly TScenario[], reps: number): `sha256:${string}`;
+/** Refuse a campaign whose retained task identities contradict its split digest. */
+declare function assertCampaignSplitIdentity(scenarios: readonly CampaignScenarioIdentity[], reps: number, splitDigest: string): void;
+//#endregion
+//#region src/campaign/external-optimizer-contracts.d.ts
+interface ExternalOptimizerRunnerCommand {
+  command?: string;
+  args?: readonly string[];
+  env?: NodeJS.ProcessEnv;
+}
+type ExternalOptimizerResumeMode = 'never' | 'if-compatible' | 'required';
+type ExternalTextCandidate = string | Record<string, string>;
+interface ExternalTextEvaluationRequest {
+  candidate: ExternalTextCandidate;
+  exampleId: string;
+}
+interface ExternalOptimizerModelBudget {
+  /** Maximum optimizer-model spend, independent of task-evaluation spend. */
+  maxCostUsd: number;
+  /** Network attempts, including provider retries. */
+  maxRequests: number;
+  /** Reject a request body above this byte count. */
+  maxRequestBytes: number;
+  /** Reject a provider response above this byte count. */
+  maxResponseBytes: number;
+  /** Reject a request asking the provider for more output tokens. */
+  maxOutputTokensPerRequest: number;
+  /** Rates used to estimate cost when the provider omits a valid `usage.cost`. */
+  pricing: CustomTokenPricing;
+  /** Per-provider-request deadline. Default: 300,000 ms. */
+  requestTimeoutMs?: number;
+}
+//#endregion
+//#region src/campaign/storage.d.ts
+/**
+ * `CampaignStorage` — the filesystem seam `runCampaign` writes through
+ * (run/cell dirs, the resumability cache, per-cell artifacts, trace spans).
+ *
+ * The default (`fsCampaignStorage`) is the Node filesystem — identical
+ * behavior to the inline `node:fs` calls it replaces, so existing CLI
+ * consumers are unaffected. `inMemoryCampaignStorage` keeps everything in a
+ * `Map`, so the substrate runs in environments WITHOUT a filesystem
+ * (Cloudflare Workers, Deno Deploy, other edge runtimes) — the campaign
+ * still produces its `CampaignResult` (cells + aggregates) in memory;
+ * artifacts/traces simply aren't persisted to disk.
+ *
+ * Paths are opaque keys to the in-memory adapter — it does not parse them,
+ * so the same `join(...)`-built paths work unchanged across both adapters.
+ */
+interface CampaignStorage {
+  /** Ensure a directory exists (recursive). No-op for in-memory. */
+  ensureDir(dir: string): void;
+  /** Does this path exist (as a written file or an ensured dir)? */
+  exists(path: string): boolean;
+  /** Read a UTF-8 file; `undefined` when missing or unreadable. */
+  read(path: string): string | undefined;
+  /** Write a file (string or bytes). Parent dir is assumed ensured. */
+  write(path: string, content: string | Uint8Array): void;
+  /** Append only when the current UTF-8 byte length matches `expectedBytes`.
+   * Returns the new length, or undefined when another writer won. */
+  append(path: string, content: string, expectedBytes: number): number | undefined;
+}
+/** Node-filesystem storage — the default. Lazily requires `node:fs` so the
+ *  module imports cleanly in non-Node runtimes (where the caller passes
+ *  `inMemoryCampaignStorage` instead and never constructs this).
+ *
+ *  `createRequire(import.meta.url)` is the ESM-native lazy require — a bare
+ *  `require` is a ReferenceError under `"type": "module"`, which is exactly
+ *  the shape this package publishes. */
+declare function fsCampaignStorage(): CampaignStorage;
+/** In-memory storage for filesystem-less runtimes. Artifacts + trace spans
+ *  live in a `Map` for the duration of the run; the `CampaignResult` is
+ *  fully populated, but nothing is persisted to disk. */
+declare function inMemoryCampaignStorage(): CampaignStorage;
+/** Open the durable spend account stored beside a logical run. */
+declare function createRunCostLedger(input: {
+  storage: CampaignStorage;
+  runDir: string;
+  costCeilingUsd?: number;
+}): CostLedger;
+//#endregion
+//#region src/campaign/run-campaign.d.ts
+interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
+  scenarios: TScenario[];
+  dispatch: DispatchFn<TScenario, TArtifact>;
+  /** Abort active dispatches when the owning operation is cancelled. */
+  signal?: AbortSignal;
+  /**
+   * 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?: CostLedgerHandle;
+  /** Attribution label for receipts recorded by this campaign. */
+  costPhase?: string;
+  /** Additional immutable receipt tags supplied by an owning workflow. */
+  costTags?: Readonly<Record<string, string>>;
+  /** Max concurrent cells. Default 2. */
+  maxConcurrency?: number;
+  /**
+   * Stop after the first dispatch or judge error. The failed cell is persisted
+   * before active sibling cells are aborted and drained, then the campaign
+   * rejects with the exact error thrown by that dispatch or judge.
+   * Default false preserves the normal behavior of returning failed cells and
+   * continuing the remaining schedule.
+   */
+  abortOnCellError?: boolean;
+  /**
+   * 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. A dispatch that stops is recorded
+   * as an error (`dispatch exceeded <N>ms`). A dispatch that ignores
+   * cancellation rejects the campaign without publishing incomplete cost data.
+   * `undefined`/`0` means unbounded.
+   */
+  dispatchTimeoutMs?: number;
+  /**
+   * Time allowed for an aborted dispatch and its paid calls to stop before the
+   * campaign rejects without producing a result. Default 5 seconds.
+   */
+  dispatchShutdownTimeoutMs?: 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;
+}
+/** Durable `<cell>/failure-receipt.json` written before a failed cell can
+ * trigger campaign-wide cancellation. The cell records dispatch measurements;
+ * `cost` covers every settled agent and judge call attributed to this exact run
+ * attempt. */
+interface CampaignCellFailureReceipt<TArtifact = unknown> {
+  schemaVersion: 1;
+  runAttemptId: string;
+  recordedAt: string;
+  failure: {
+    stage: 'dispatch' | 'judge';
+    judge?: string;
+    error: {
+      name: string;
+      message: string;
+      stack?: string;
+    };
+  };
+  cell: CampaignCellResult<TArtifact>;
+  cost: CostLedgerSummary;
+}
+/**
+ * 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;
+  splitDigest: `sha256:${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;
+//#endregion
+//#region src/campaign/presets/compare-optimization-methods.d.ts
+/** Shared campaign settings applied to every optimization method. */
+type OptimizationMethodRunOptions<TScenario extends Scenario, TArtifact> = Omit<RunCampaignOptions<TScenario, TArtifact>, 'costCeiling' | 'costLedger' | 'dispatch' | 'judges' | 'runDir' | 'scenarios' | 'seed'>;
+/** Cost reported by a method or by final test scoring. */
+interface ComparisonCost {
+  totalCostUsd: number;
+  accountingComplete: boolean;
+  incompleteReasons: string[];
+}
+interface OptimizationPackageSource {
+  kind: 'package';
+  /** Whether package identity was inspected or supplied by caller code. */
+  evidence: 'observed' | 'declared';
+  package: string;
+  version: string;
+  sourceUrl?: string;
+  revision?: string;
+  /** SHA-256 of all installed module files observed before the run. */
+  sourceSha256?: string;
+}
+interface OptimizationModuleSource {
+  module: string;
+  sourceSha256: string;
+}
+interface OptimizationPythonRuntime {
+  implementation: string;
+  version: string;
+}
+interface OptimizationTokenUsage {
+  /** All input tokens, including cache reads and cache creation. */
+  inputTokens: number;
+  /** Input tokens served from a provider cache. */
+  cachedInputTokens?: number;
+  /** Input tokens used to create or write a provider cache entry. */
+  cacheWriteInputTokens?: number;
+  outputTokens: number;
+  /** Reasoning tokens included in `outputTokens`. */
+  reasoningTokens?: number;
+  totalTokens: number;
+  calls: number;
+}
+interface OptimizationMethodProvenance {
+  /** External optimizer package. */
+  source: OptimizationPackageSource;
+  /** Python bridge package that invoked the optimizer. */
+  bridge?: OptimizationPackageSource;
+  /** Custom engine modules imported by the optimizer. */
+  modules?: OptimizationModuleSource[];
+  /** Python implementation used by the bridge process. */
+  python?: OptimizationPythonRuntime;
+  /** Exact model identifier configured for optimizer-owned model calls. */
+  optimizerModel?: string;
+  runId: string;
+  /** Content identity shared by compatible resumptions. */
+  compatibleRunId?: string;
+  resumed: boolean;
+  evaluationCount: number;
+  artifactDir: string;
+  tokenUsage?: OptimizationTokenUsage;
+}
+/** Shared inputs for one optimization method. Final test data is absent. */
+interface OptimizationMethodInput<TScenario extends Scenario, TArtifact> {
+  /** Surface every method starts from. */
+  readonly baselineSurface: MutableSurface;
+  /** Evidence used to author or fit candidates. */
+  readonly trainScenarios: readonly TScenario[];
+  /** Data used for candidate acceptance, early stopping, and model selection. */
+  readonly selectionScenarios: readonly TScenario[];
+  /** Runs one scenario with a candidate surface. */
+  readonly dispatchWithSurface: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+  /** Scores artifacts produced by `dispatchWithSurface`. */
+  readonly judges: readonly JudgeConfig<TArtifact, TScenario>[];
+  /** Method-specific artifacts are written below this directory. */
+  readonly runDir: string;
+  readonly seed: number;
+  /** Shared defaults for every method. A method may override them explicitly. */
+  readonly runOptions: Readonly<OptimizationMethodRunOptions<TScenario, TArtifact>>;
+  /** Durable spend account shared by every method and final scoring. */
+  readonly costLedger: CostLedgerHandle;
+}
+interface OptimizationMethodResult {
+  /** Surface selected without using the final test partition. */
+  winnerSurface: MutableSurface;
+  /** Optimization spend. Excludes final test scoring. */
+  cost: ComparisonCost;
+  /** Optimization duration. Excludes final test scoring. */
+  durationMs?: number;
+  /** Exact external implementation and run identity, when the method uses one. */
+  provenance?: OptimizationMethodProvenance;
+}
+/** A complete optimization method, including candidate generation and selection. */
+interface OptimizationMethod<TScenario extends Scenario = Scenario, TArtifact = unknown> {
+  /** Unique, trimmed display name. Its normalized form must also be unique. */
+  name: string;
+  optimize: (input: OptimizationMethodInput<TScenario, TArtifact>) => Promise<OptimizationMethodResult>;
+}
+interface OptimizationMethodScore {
+  name: string;
+  /** Mean final-test composite of the baseline (identical across methods). */
+  baselineComposite: number;
+  /** Mean final-test composite of this method's selected surface. */
+  winnerComposite: number;
+  /** Mean per-scenario final-test lift (winner minus baseline). */
+  lift: number;
+  /** Simultaneous paired-bootstrap interval for per-scenario lift.
+   *  `low > 0` excludes zero after adjustment for all reported contrasts. */
+  liftCi: {
+    low: number;
+    high: number;
+  };
+  /** Optimization spend reported by the method. Excludes final test scoring. */
+  optimizationCost: ComparisonCost;
+  /** Optimization duration reported by the method. Excludes final test scoring. */
+  durationMs?: number;
+  /** Exact external implementation and run identity, when reported by the method. */
+  provenance?: OptimizationMethodProvenance;
+  /** Paired final-test values used to compute lift and its interval. */
+  scenarioScores: Array<{
+    scenarioId: string;
+    baselineComposite: number;
+    winnerComposite: number;
+    lift: number;
+  }>;
+  winnerSurface: MutableSurface;
+  /** 1-based, by descending lift. */
+  rank: number;
+}
+interface OptimizationMethodPairwise {
+  /** Higher-ranked method. */
+  a: string;
+  b: string;
+  /** Mean per-scenario untouched-test delta (a − b). */
+  deltaMean: number;
+  low: number;
+  high: number;
+  /** `a` if the CI clears 0, `b` if it is entirely negative, else `'tie'`. */
+  favored: string;
+}
+interface OptimizationMethodComparison {
+  /** Sorted by descending lift; `rank` set accordingly. */
+  scores: OptimizationMethodScore[];
+  best: OptimizationMethodScore;
+  /** Best vs each other method, using simultaneous paired-bootstrap intervals. */
+  pairwise: OptimizationMethodPairwise[];
+  testScenarioIds: string[];
+  /** Sum of the costs reported by every optimization method. */
+  optimizationCost: ComparisonCost;
+  /** Baseline and distinct winner scoring on the final test partition. */
+  testCost: ComparisonCost;
+  /** Optimization plus final test scoring. */
+  totalCost: ComparisonCost;
+  /** Caller-requested simultaneous coverage across all reported contrasts. */
+  confidence: number;
+  /** Bonferroni-adjusted confidence used for each bootstrap interval. */
+  intervalConfidence: number;
+  /** Method-vs-baseline plus all possible method-vs-method contrasts. */
+  comparisonCount: number;
+  /** Deterministic bootstrap and campaign seed. */
+  seed: number;
+  /** Bootstrap draws used for each interval. */
+  resamples: number;
+  /** Agent runs averaged within each test scenario before resampling scenarios. */
+  reps: number;
+}
+interface CompareOptimizationMethodsOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch' | 'judges' | 'scenarios'> {
+  methods: OptimizationMethod<TScenario, TArtifact>[];
+  baselineSurface: MutableSurface;
+  /** Evidence used by every optimizer to author or fit candidates. */
+  trainScenarios: TScenario[];
+  /** Candidate acceptance, early-stopping, and optimizer-selection data. */
+  selectionScenarios: TScenario[];
+  /** Untouched final comparison data. Never passed to an optimization method. */
+  testScenarios: TScenario[];
+  /** Scores a surface on a scenario. The methods and final test share this function. */
+  dispatchWithSurface: (surface: MutableSurface, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+  judges: JudgeConfig<TArtifact, TScenario>[];
+  /** Bootstrap resamples for the lift intervals. Default is at least 2000 and
+   *  rises when the requested simultaneous confidence needs finer tails. */
+  resamples?: number;
+  /** Shared defaults for each method's train and selection campaigns. */
+  optimizationRunOptions?: OptimizationMethodRunOptions<TScenario, TArtifact>;
+  /** Number of optimization methods to run concurrently. Default 1. */
+  optimizationConcurrency?: number;
+  /** Simultaneous confidence across method-vs-baseline and method-vs-method contrasts.
+   *  Each bootstrap interval is Bonferroni-adjusted. Default 0.95. */
+  confidence?: number;
+  /** Shared spend limit across every method's optimizer and evaluation calls plus final scoring. */
+  costCeiling?: number;
+}
+/**
+ * Compare complete optimization methods on disjoint train, selection, and final test data.
+ */
+declare function compareOptimizationMethods<TScenario extends Scenario, TArtifact>(opts: CompareOptimizationMethodsOptions<TScenario, TArtifact>): Promise<OptimizationMethodComparison>;
+/** Keep the cost fields a custom optimization method must report. */
+declare function costFromLedgerSummary(summary: CostLedgerSummary): ComparisonCost;
+/** Preserve every optimizer token class while keeping total input and output explicit. */
+declare function optimizationTokenUsageFromSummary(summary: CostLedgerSummary, receipts: readonly CostReceipt[]): OptimizationTokenUsage | undefined;
+//#endregion
+//#region src/campaign/external-text-evaluation.d.ts
+interface ExternalOptimizationExample {
+  id: string;
+  data: unknown;
+}
+interface ExternalTextEvaluationResponse {
+  score: number;
+  info: {
+    scenarioId: string;
+    dimensions: Record<string, number>;
+    notes?: string;
+    artifact?: unknown;
+  };
+}
+//#endregion
+//#region src/campaign/external-text-optimization-contract.d.ts
+interface ExternalTextOptimizerContext {
+  readonly runId: string;
+  readonly name: string;
+  readonly objective: string;
+  readonly evaluationId: string;
+  readonly background?: string;
+  readonly seedCandidate: ExternalTextCandidate;
+  readonly trainSet: readonly ExternalOptimizationExample[];
+  readonly selectionSet: readonly ExternalOptimizationExample[];
+  readonly maxEvaluations: number;
+  readonly seed: number;
+  /** Stable directory for optimizer checkpoints from compatible attempts. */
+  readonly stateDir: string;
+  readonly restoreRequested: boolean;
+  readonly artifactDir: string;
+  readonly signal: AbortSignal;
+  /** Record every optimizer-owned paid call through this attributed account. */
+  readonly cost: CampaignCostMeter;
+  readonly evaluate: (request: ExternalTextEvaluationRequest) => Promise<ExternalTextEvaluationResponse>;
+}
+interface ExternalTextOptimizerResult {
+  bestCandidate: ExternalTextCandidate;
+  resumed: boolean;
+  costAccounting: {
+    kind: 'metered';
+  } | {
+    kind: 'no-paid-work';
+  } | {
+    kind: 'external';
+    reason: string;
+  };
+}
+/**
+ * Configuration for adapting another text optimizer.
+ *
+ * `run` owns search. Agent Eval owns split isolation, bounded candidate
+ * evaluation, exact cost collection, provenance, and final comparison.
+ */
+interface ExternalTextOptimizationMethodConfig<TScenario extends Scenario, TArtifact = unknown> {
+  name: string;
+  source: Omit<OptimizationPackageSource, 'evidence'>;
+  objective: string;
+  evaluationId: string;
+  background?: string;
+  maxEvaluations: number;
+  /** Hard limit for calls made through `context.cost`. Use 0 for no paid work. */
+  maxOptimizerCostUsd: number;
+  /** Abort `context.signal` after this duration. Default: 30 minutes. */
+  timeoutMs?: number;
+  /** Default: `never`. Compatible runs reuse one state directory. */
+  resume?: ExternalOptimizerResumeMode;
+  maxCandidateChars?: number;
+  maxEvidenceChars?: number;
+  describeScenario?: (scenario: TScenario) => unknown;
+  describeArtifact?: (artifact: TArtifact, scenario: TScenario) => unknown;
+  run: (context: ExternalTextOptimizerContext) => Promise<ExternalTextOptimizerResult>;
+}
+//#endregion
+//#region src/campaign/external-text-optimization.d.ts
+/**
+ * Adapt a third-party text optimizer without reimplementing its search.
+ *
+ * The callback never receives final test cases. Calls to `evaluate` are
+ * counted before execution and stop at `maxEvaluations`.
+ */
+declare function externalTextOptimizationMethod<TScenario extends Scenario, TArtifact>(config: ExternalTextOptimizationMethodConfig<TScenario, TArtifact>): OptimizationMethod<TScenario, TArtifact>;
+//#endregion
+//#region src/campaign/gates/compose.d.ts
+/** Compose gates — all must `ship` for the composite to `ship`. First
+ *  non-ship verdict short-circuits the composite verdict, but ALL gates run
+ *  (so the result records every gate's reason — useful for diagnostics). */
+declare function composeGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(...gates: Array<Gate<TArtifact, TScenario>>): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/canary.d.ts
+type CanaryKind = 'silent_judge_fallback' | 'judge_calibration_drift' | 'distribution_shift';
+type CanarySeverity = 'info' | 'warn' | 'error';
+interface CanaryAlert {
+  kind: CanaryKind;
+  severity: CanarySeverity;
+  message: string;
+  /** Numbers that informed the decision — drop straight into a
+   *  dashboard / paper figure. */
+  evidence: Record<string, unknown>;
+}
+interface CanaryReport {
+  alerts: CanaryAlert[];
+  /** Per-kind summary count. */
+  counts: Record<CanaryKind, number>;
+  /** Whether each enabled detector had enough observations to run. */
+  evaluations: CanaryEvaluation[];
+}
+interface CanaryEvaluation {
+  kind: CanaryKind;
+  status: 'evaluated' | 'not_evaluated';
+  observations: number;
+  reason?: string;
+}
+interface CanaryOptions {
+  /**
+   * Silent-fallback detection.
+   * - `constant`: confidence value treated as the fallback signal.
+   *   Default 0.30 (matches the soft-fail default in
+   *   `propose-review.ts`).
+   * - `consecutiveThreshold`: trip the alert after this many
+   *   consecutive runs at `constant` (or `fallback === true`).
+   *   Default 3.
+   */
+  silentFallback?: {
+    constant?: number;
+    consecutiveThreshold?: number;
+    /** Floating-point tolerance when comparing against `constant`. */
+    epsilon?: number;
+  };
+  /**
+   * Calibration-drift detection.
+   * - `historyWindow`: number of past runs (oldest-first) treated as
+   *   the historical baseline. Default 50.
+   * - `recentWindow`: number of recent runs (newest-first) compared
+   *   against history. Default 20.
+   * - `ksAlpha`: alpha for the KS statistic vs critical value.
+   *   Default 0.05.
+   * - `minRecent`: minimum recent runs required to even attempt the
+   *   check. Default 10.
+   */
+  calibrationDrift?: {
+    historyWindow?: number;
+    recentWindow?: number;
+    ksAlpha?: number;
+    minRecent?: number;
+  };
+  /**
+   * Distribution-shift detection.
+   * - `category`: function that maps a run to a categorical bucket.
+   *   Required to enable this canary; if omitted the chi-square check
+   *   is skipped entirely.
+   * - `chiSquareAlpha`: alpha. Default 0.05.
+   * - `historyWindow`, `recentWindow`, `minRecent`: like above.
+   */
+  distributionShift?: {
+    category: (run: RunRecord) => string | null;
+    chiSquareAlpha?: number;
+    historyWindow?: number;
+    recentWindow?: number;
+    minRecent?: number;
+  };
+}
+/**
+ * Run all configured canaries against a chronological run list.
+ * Runs MUST be sorted oldest-to-newest by the caller — the order of
+ * the input is used to define "recent" vs "historical" windows.
+ */
+declare function runCanaries(runs: RunRecord[], opts?: CanaryOptions): CanaryReport;
+//#endregion
+//#region src/red-team.d.ts
+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[]>;
+//#endregion
+//#region src/campaign/gates/default-production-gate.d.ts
+type DefaultProductionGateCheck = 'dimension-regression' | 'budget' | 'red-team' | 'reward-hacking' | 'canary';
+type DefaultProductionRewardHackingOptions = Omit<DetectRewardHackingInput, 'runs' | 'truthOf'> & {
+  truthOf: NonNullable<DetectRewardHackingInput['truthOf']>;
+};
+interface DefaultProductionGateOptions {
+  /** Required: scenarios held out from training; substrate compares
+   *  candidate-on-holdout vs baseline-on-holdout. */
+  holdoutScenarios: Scenario[];
+  /** Minimum held-out lift the **paired-bootstrap CI lower bound** must clear
+   *  to ship — NOT a point estimate. Default 0 ⇒ "confidently positive at the
+   *  confidence level". Interpreted in the judge's native composite scale (set
+   *  e.g. 2 for a 0-100 rubric to require a ≥2-point significant gain). */
+  deltaThreshold?: number;
+  /** Confidence level for the held-out + dimension bootstraps. Default 0.95. */
+  confidence?: number;
+  /** Bootstrap resamples. Default 2000. */
+  bootstrapResamples?: number;
+  /** Fixed bootstrap seed for a deterministic verdict. Default 1337. */
+  bootstrapSeed?: number;
+  /** Minimum paired holdout observations (scenarios × reps) before a
+   *  significance claim is allowed; below it the gate HOLDS with `few_runs`
+   *  rather than reading a degenerate CI. Default 3. */
+  minProductiveRuns?: number;
+  /** Ship statistic for the held-out significance test. Default `'mean'`
+   *  (tie-robust — see `heldoutSignificance`). Pass `'median'` for
+   *  outlier-robustness at the cost of tie-blindness. */
+  heldoutStatistic?: 'mean' | 'median';
+  /** Critical judge dimensions that must NOT significantly regress even when
+   *  the net composite rises (anti-Goodhart). The gate HOLDS if any listed
+   *  dimension's paired-delta CI lower bound < −`regressionTolerance`. E.g.
+   *  `['hallucination_free']` for a legal agent. */
+  criticalDimensions?: string[];
+  /** Tolerance for the per-dimension regression guard, in the dimension's
+   *  native scale. When omitted it auto-scales off observed magnitudes:
+   *  0.05 on [0,1], 5 on 0-100. */
+  regressionTolerance?: number;
+  /** Total $ budget for the complete improvement run. Requires
+   *  `GateContext.costLedger`; missing or incomplete accounting holds. */
+  budgetUsd?: number;
+  /** Static artifact-screening cases. Only `expected: 'ignore'` cases without
+   *  tool assertions are valid because this check does not dispatch case inputs
+   *  or observe tool calls. */
+  redTeamBattery?: RedTeamCase[];
+  /** Shared run history, oldest first. Supplying history does not enable either
+   *  monitoring check; configure `rewardHacking` and/or `canary` explicitly. */
+  recentRuns?: RunRecord[];
+  /** Enable reward-hacking monitoring with a caller-owned independent truth channel. */
+  rewardHacking?: DefaultProductionRewardHackingOptions;
+  /** Enable canary monitoring. Pass `{}` to use the canary defaults. */
+  canary?: CanaryOptions;
+  /** Optional checks that must be evaluated even when their normal input is
+   *  absent. Configuring a check's input also makes that check required.
+   *  Missing evidence always records `not_evaluated`; required unevaluated
+   *  checks hold the release decision. Held-out significance is always required. */
+  requiredChecks?: DefaultProductionGateCheck[];
+}
+/**
+ * Opinionated production gate composing held-out significance, red-team, reward-hacking, and canary checks into a single `Gate.decide` decision.
+ */
+declare function defaultProductionGate<TArtifact, TScenario extends Scenario>(options: DefaultProductionGateOptions): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/gates/heldout-gate.d.ts
+interface HeldOutGateOptions<TScenario extends Scenario = Scenario> {
+  scenarios: TScenario[];
+  /** Effect-size threshold the CI lower bound must clear, in the judge's native
+   *  scale. Default 0.5. Equality holds; CI.low must be greater than this value. */
+  deltaThreshold?: number;
+  /** Bootstrap CI confidence. Default 0.95. */
+  confidence?: number;
+  /** Minimum paired holdout observations to claim significance. Default 3. */
+  minProductiveRuns?: number;
+  /** Bootstrap resamples. Default 2000. */
+  resamples?: number;
+  /** Fixed bootstrap seed for deterministic verdicts. Default 1337. */
+  bootstrapSeed?: number;
+}
+/**
+ * Composable held-out gate: ships only when the PAIRED bootstrap CI lower bound
+ * of the candidate-minus-baseline composite delta clears `deltaThreshold`.
+ */
+declare function heldOutGate<TArtifact, TScenario extends Scenario>(options: HeldOutGateOptions<TScenario>): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/gates/power-preflight.d.ts
+/**
+ * Power preflight — "can this budget detect the effect you are hunting?"
+ *
+ * The failure it prevents (measured, twice): a live prompt-improvement campaign ran
+ * 333 sandbox cells over 5.6 hours and produced a +0.08 holdout lift the ship gate
+ * (paired bootstrap, CI.low > 0.05) could not distinguish from zero — because at
+ * that holdout size and worker variance the MINIMUM DETECTABLE lift was larger than
+ * any effect a prompt change plausibly produces. The budget was spent learning what
+ * a 30-second calculation on the baseline cells already knew. No eval framework we
+ * know of surfaces this; every underpowered improvement run everywhere ends in an
+ * uninformative "hold".
+ *
+ * Model: the ship rule is `CI.low(paired Δ) > deltaThreshold`. Approximating the
+ * bootstrap CI as normal, `CI.low ≈ effect − z·sd_Δ/√n`, so the smallest shippable
+ * true effect is `MDE = deltaThreshold + z·sd_Δ/√n`. The paired-delta SD is unknown
+ * before the candidate exists; we bound it by the zero-correlation case
+ * `sd_Δ ≤ √2·sd_baseline` — a CONSERVATIVE (upper) MDE, which is the correct
+ * direction for a warning. Pairing is per cell (`scenario:rep`), so reps multiply n.
+ *
+ * Standalone by design: feed it any baseline composites (a `gate:'none'` run, a
+ * live-proof table) BEFORE budgeting the real search; `selfImprove` also attaches
+ * it to every result and warns when the run was structurally unable to ship.
+ */
+interface PowerPreflightOptions {
+  /** Per-cell baseline composites on the HOLDOUT scenarios (one per scenario:rep cell). */
+  baselineComposites: number[];
+  /** Paired observations the budgeted comparison will produce
+   *  (holdout scenarios × reps). Defaults to `baselineComposites.length`. */
+  pairedN?: number;
+  /** The ship gate's effect-size threshold. Default 0.05 (defaultProductionGate). */
+  deltaThreshold?: number;
+  /** CI confidence the gate uses. Default 0.95. */
+  confidence?: number;
+  /** True when the holdout is scored by the SAME judge/scorer family as the gate
+   *  (selfImprove's default composition — one judge scores everything). Under a
+   *  shared channel, raising paired n reduces only the IDIOSYNCRATIC noise share;
+   *  systematic judge bias is untouched, so the MDE here is a lower bound and the
+   *  only full debiaser is an independent second scoring channel
+   *  (recursive-self-improvement S1c, closed form in EXP-023 P0). Default false. */
+  sharedScorerChannel?: boolean;
+}
+interface PowerPreflight {
+  /** Paired observations the comparison will have. */
+  n: number;
+  /** Baseline per-cell composite standard deviation (the variance the effect must beat). */
+  sd: number;
+  /** Minimum detectable lift: the smallest TRUE effect the gate could ship at this budget. */
+  mde: number;
+  /** Baseline holdout composite mean. */
+  baselineMean: number;
+  /** Headroom to a perfect 1.0 composite (the largest achievable lift on a [0,1] judge). */
+  headroom: number;
+  /** True when even the largest achievable effect (headroom) is below the MDE —
+   *  the run is structurally unable to ship regardless of proposal quality.
+   *  Only asserted for [0,1]-scaled judges (see `scaleAssumed`). */
+  underpowered: boolean;
+  /** True when composites look [0,1]-scaled; headroom/underpowered are only
+   *  meaningful under that convention (0-100 judges get mde/sd/n but no verdict). */
+  scaleAssumed: boolean;
+  deltaThreshold: number;
+  confidence: number;
+  /** Set when the holdout shares the gate's scoring channel: more cells cannot
+   *  buy back systematic judge bias — treat the MDE as a lower bound. */
+  sharedChannelCaveat?: string;
+  /** One actionable sentence for humans and logs. */
+  recommendation: string;
+}
+/** Estimate the minimum detectable lift a paired-holdout improvement run can
+ *  ship at a given budget, from the baseline holdout composites — call it BEFORE
+ *  spending a search to learn whether the effect you are hunting is even
+ *  observable at this holdout size and worker variance. */
+declare function powerPreflight(opts: PowerPreflightOptions): PowerPreflight;
+//#endregion
+//#region src/pareto.d.ts
+/**
+ * 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;
+}>;
+//#endregion
+//#region src/campaign/gates/promotion-policy.d.ts
+/** Where an objective's per-cell scalar comes from. `composite` reads the
+ *  judge's composite; `dimension` reads a named per-dimension score. */
+type ObjectiveSource = {
+  kind: 'composite';
+} | {
+  kind: 'dimension';
+  dimension: string;
+};
+interface PromotionObjective {
+  /** Stable label used in reports + `contributingGates`. */
+  name: string;
+  source: ObjectiveSource;
+  /** 'maximize' (quality dims) or 'minimize' (error/risk/length dims). Orients
+   *  the paired delta so a positive bootstrap always means "candidate better". */
+  direction: Direction;
+  /** The good-direction paired-delta CI lower bound must EXCEED this to count
+   *  as a significant gain on this axis. Interpreted in the judge's native
+   *  scale. Default 0 (⇒ "confidently better"). */
+  gainThreshold?: number;
+  /** A floor breach (regression) is declared when the good-direction CI lower
+   *  bound is below −floorTolerance. When omitted it auto-scales off observed
+   *  magnitudes (0.05 on [0,1], 5 on 0-100), matching `dimensionRegressions`. */
+  floorTolerance?: number;
+}
+/** Per-axis verdict from the good-direction paired bootstrap. */
+type AxisVerdict = 'improved' | 'regressed' | 'flat' | 'few_runs';
+interface AxisEvidence {
+  name: string;
+  source: ObjectiveSource;
+  direction: Direction;
+  /** Paired bootstrap on the GOOD-DIRECTION delta (oriented by `direction`):
+   *  a positive value means the candidate is better on this axis. */
+  bootstrap: PairedBootstrapResult;
+  /** Paired observations contributing to this axis. */
+  n: number;
+  gainThreshold: number;
+  floorTolerance: number;
+  verdict: AxisVerdict;
+}
+interface EvidenceVector {
+  /** One entry per objective — NOTHING averaged across axes. */
+  axes: AxisEvidence[];
+  /** Smallest paired n across axes that produced observations — the binding
+   *  evidence-sufficiency constraint. 0 when no axis produced observations. */
+  minN: number;
+  /** Aggregate per-side cost from the gate context (a constraint input, not a
+   *  CI axis — see the module header). */
+  cost: {
+    candidate: number;
+    baseline: number;
+  };
+}
+/** A promotion strategy: a pure function from the evidence vector to a verdict.
+ *  Many policies can run over the same `EvidenceVector` and disagree — that's
+ *  the point (competing strategies, shared evidence). */
+type PromotionPolicy = (ev: EvidenceVector) => GateResult;
+interface BuildEvidenceVectorOptions {
+  /** Minimum paired observations before an axis can claim significance; below
+   *  it the axis is `few_runs`. Default 3. */
+  minProductiveRuns?: number;
+  /** Confidence level for every axis bootstrap. Default 0.95. */
+  confidence?: number;
+  /** Bootstrap resamples. Default 2000. */
+  resamples?: number;
+  /** Fixed bootstrap seed for a deterministic, reproducible verdict. Default 1337. */
+  seed?: number;
+}
+/**
+ * The Evidence Bus. For each objective, pair candidate vs baseline by full
+ * cellId and bootstrap a CI on the good-direction paired delta. Reuses the
+ * exact `pairHoldout` + `pairedBootstrap` machinery the held-out gate uses, so
+ * a single source of truth governs pairing granularity + scale handling.
+ */
+declare function buildEvidenceVector<TArtifact, TScenario extends Scenario>(ctx: GateContext<TArtifact, TScenario>, objectives: PromotionObjective[], opts?: BuildEvidenceVectorOptions): EvidenceVector;
+/**
+ * The default strategy: symmetric multi-objective Pareto significance. Ship iff
+ * the candidate weakly dominates the baseline at the confidence level — no axis
+ * credibly worse AND ≥1 axis credibly better. Floor breach on any axis → hold
+ * (anti-Goodhart, dominates everything). Insufficient evidence on any axis →
+ * need_more_work. Statistically equivalent → hold (never ship noise).
+ */
+declare const paretoPolicy: PromotionPolicy;
+interface ParetoSignificanceGateOptions extends BuildEvidenceVectorOptions {
+  /** The objective vector. Every axis is both a gain source and a safety floor. */
+  objectives: PromotionObjective[];
+  /** Strategy applied to the evidence vector. Default `paretoPolicy`. Override
+   *  to run a stricter/looser strategy over the SAME bus (competing policies). */
+  policy?: PromotionPolicy;
+  /** Override the gate name in reports. */
+  name?: string;
+}
+/**
+ * Wrap the bus + a policy as a `Gate`. Plugs into the existing
+ * `runImprovementLoop({ gate })` slot and composes via `composeGate`; default
+ * loop behavior is unchanged because consumers opt in by passing this gate.
+ */
+declare function paretoSignificanceGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(options: ParetoSignificanceGateOptions): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/optimizer-model.d.ts
+type OptimizerModelBudget = ExternalOptimizerModelBudget;
+/** One metered OpenAI-compatible model connection shared by official optimizers. */
+interface OpenAICompatibleOptimizerModel {
+  model: string;
+  baseUrl: string;
+  apiKey: string;
+  budget: OptimizerModelBudget;
+}
+//#endregion
+//#region src/campaign/gepa-optimization-method.d.ts
+/** Shared settings for one bounded GEPA engine invocation. */
+interface GepaEngineOptions {
+  /** GEPA engine name. GEPA validates names available in its Python runtime. */
+  engine: string;
+  /** Required cap for this engine's own model or CLI spend. */
+  maxProposerCostUsd: number;
+  /** Maximum concurrent evaluations inside this engine. Default: 1. */
+  maxConcurrency?: number;
+  /** Stop the engine after it reaches this score. */
+  stopAtScore?: number;
+  /** Isolate agent-based engines. Default: true. */
+  sandbox?: boolean;
+  /**
+   * JSON-safe configuration for the registered GEPA engine.
+   * Python callables and class instances cannot cross the process boundary.
+   */
+  engineConfig?: Record<string, unknown>;
+}
+/** One independently budgeted GEPA engine invocation. */
+interface GepaEngineRun extends GepaEngineOptions {
+  /** Maximum callback evaluations this engine may consume. */
+  maxEvaluations: number;
+}
+/** An engine in an adaptive run. All engines share the recipe evaluation limit. */
+type GepaAdaptiveEngineRun = GepaEngineOptions;
+/**
+ * A direct mapping to a GEPA optimization recipe.
+ *
+ * GEPA owns every search and composition operation represented here. Tangle
+ * supplies the candidate, data, execution callback, judges, and budgets.
+ */
+type GepaOptimizationRecipe = {
+  kind: 'engine';
+  run: GepaEngineRun;
+} | {
+  kind: 'sequential';
+  runs: readonly GepaEngineRun[];
+} | {
+  kind: 'adaptive-sequential';
+  runs: readonly GepaAdaptiveEngineRun[];
+  /** One evaluation budget shared by every adaptive stage. */
+  maxEvaluations: number;
+  /** Switch engines after this many evaluations without improvement. */
+  plateauEvaluations: number;
+  patience?: number;
+  minEvaluationsPerStage?: number;
+  improvementEpsilon?: number;
+  cycle?: boolean;
+  maxSwitches?: number;
+  maxConcurrency?: number;
+} | {
+  kind: 'best-of';
+  runs: readonly GepaEngineRun[];
+  maxWorkers?: number;
+} | {
+  kind: 'vote';
+  runs: readonly GepaEngineRun[];
+  maxWorkers?: number;
+} | {
+  kind: 'omni';
+  explore: readonly GepaEngineRun[];
+  continueWith: GepaEngineRun;
+  maxWorkers?: number;
+};
+/** The command that runs the Python GEPA bridge. */
+type GepaRunnerCommand = ExternalOptimizerRunnerCommand;
+interface GepaOptimizationMethodConfig<TScenario extends Scenario, TArtifact = unknown> {
+  /** Unique comparison-method name. Default identifies the GEPA recipe. */
+  name?: string;
+  /** A direct GEPA recipe. */
+  recipe: GepaOptimizationRecipe;
+  /** Plain-language goal shown to the external optimizer. */
+  objective: string;
+  /** Stable identity for the dispatch, judges, model settings, and scoring logic. */
+  evaluationId: string;
+  /** Optional bounded context about the surface and task. */
+  background?: string;
+  /**
+   * Public dotted Python modules imported before GEPA resolves engine names.
+   * Each module should call GEPA's official `register_engine()` API at import.
+   */
+  engineModules?: readonly string[];
+  /** Reject external candidates longer than this. Default: 200,000 characters. */
+  maxCandidateChars?: number;
+  /** Reject serialized score evidence longer than this. Default: 100,000 characters. */
+  maxEvidenceChars?: number;
+  /** End the bridge process after this many milliseconds. Default: 30 minutes. */
+  timeoutMs?: number;
+  /**
+   * OpenAI-compatible model used by standard GEPA reflection.
+   * Calls pass through Agent Eval's local model proxy. Every recipe engine must
+   * be `gepa` when this is set.
+   */
+  optimizer?: OpenAICompatibleOptimizerModel;
+  /**
+   * Decide what the external optimizer may read for a train or selection case.
+   * The returned value must be JSON-serializable. The final comparison cases
+   * are not accepted by this API and cannot be serialized here.
+   */
+  describeScenario?: (scenario: TScenario) => unknown;
+  /** Optional bounded artifact evidence returned to GEPA after each evaluation. */
+  describeArtifact?: (artifact: TArtifact, scenario: TScenario) => unknown;
+  /** Default: `never`. Compatible runs resume only when explicitly enabled. */
+  resume?: ExternalOptimizerResumeMode;
+  /**
+   * Required for resumable direct GEPA runs because upstream state uses Python
+   * pickle. Enable only for state created locally in a directory you control.
+   */
+  trustResumeState?: boolean;
+  runner?: GepaRunnerCommand;
+}
+/**
+ * Turn an optional GEPA installation into an `OptimizationMethod`.
+ *
+ * GEPA receives only serialized train and selection cases. The caller's final
+ * test partition stays inside `compareOptimizationMethods`, which invokes this
+ * method without a test-set field. The local callback routes every candidate
+ * evaluation through the same dispatch and judges used by other methods.
+ */
+declare function gepaOptimizationMethod<TScenario extends Scenario, TArtifact>(config: GepaOptimizationMethodConfig<TScenario, TArtifact>): OptimizationMethod<TScenario, TArtifact>;
+//#endregion
+//#region src/campaign/presets/run-eval.d.ts
+interface RunEvalOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'runDir'> {
+  runDir: string;
+}
+/**
+ * Simplest evaluation preset: run scenarios through dispatch, score with judges, and return a `CampaignResult` — no optimizer, no gate, no PR.
+ */
+declare function runEval<TScenario extends Scenario, TArtifact>(opts: RunEvalOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
+//#endregion
+//#region src/campaign/presets/run-optimization.d.ts
+interface PremeasuredOptimizationBaseline<TArtifact, TScenario extends Scenario> {
+  /** Hash of the exact surface that produced `campaign`. */
+  surfaceHash: string;
+  /** Complete prior measurement reused by identity, including artifactsByPath. */
+  campaign: CampaignResult<TArtifact, TScenario>;
+}
+interface RunOptimizationBaseOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch'> {
+  /** Initial mutable surface (typically system prompt or addendum). */
+  baselineSurface: MutableSurface;
+  /**
+   * Complete prior measurement of `baselineSurface`. When present,
+   * `runOptimization` validates its surface, scenario split, seed, reps, and
+   * normal campaign coverage, then skips the baseline campaign entirely — no
+   * dispatch or resumability-cache lookup. Candidate campaigns still run
+   * normally. Prior spend remains in the imported campaign aggregates and is
+   * not added again to this continuation's CostLedger.
+   */
+  premeasuredBaseline?: PremeasuredOptimizationBaseline<TArtifact, TScenario>;
+  /** 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. */
+  proposer: SurfaceProposer;
+  populationSize: number;
+  maxGenerations: number;
+  /** Candidate campaigns run at once. Default 1. Total concurrent cells are
+   *  bounded by candidateConcurrency * maxConcurrency. */
+  candidateConcurrency?: 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 | null;
+    }>;
+    history: GenerationRecord[];
+    /** Shared run spend account and receipt attribution phase. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+  }) => Promise<unknown[]>;
+  /**
+   * Optional override for how the WINNER is selected among coverage-complete
+   * candidates (and how the incumbent bar is set). Returns a lexicographic rank
+   * key — each element higher-is-better; candidates are ranked by descending key
+   * (`compareRankKeys`) and the top must STRICTLY beat the incumbent's key to
+   * promote. Defaults to `[campaignMeanComposite(campaign)]`, i.e. the historical
+   * scalar-mean ranking (single-element key ⇒ identical behavior).
+   *
+   * A binary-with-replicates consumer (e.g. swe-arena, whose ship-gate counts an
+   * instance resolved only when EVERY replicate resolved) passes a fail-closed
+   * key built from the SAME reduction its gate uses, so winner-selection and the
+   * ship-gate rank on the identical metric and can never invert — the selector
+   * cannot promote a flaky per-cell-mean candidate the gate would reject over a
+   * fail-closed candidate the gate would accept. Only the winner CHOICE changes;
+   * the descriptive `composite` (mean) on every record and the Pareto objective
+   * vectors are untouched, so proposer diversity and reporting are unaffected.
+   */
+  selectionRankKey?: (campaign: CampaignResult<TArtifact, TScenario>) => number[];
+}
+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>>;
+//#endregion
+//#region src/campaign/presets/run-improvement-loop.d.ts
+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[];
+  /** Holdout policy. Default `'measured'`: baseline + winner are re-scored on
+   *  `holdoutScenarios` and the gate decides on that held-out comparison.
+   *  `'deferred'`: the improvement-set (search) campaigns run exactly as usual,
+   *  but ZERO holdout cells are dispatched, the gate is forced to `'hold'`, and
+   *  the result + provenance record carry `holdout: 'deferred'` with NO
+   *  held-out lift — for callers that measure the held-out comparison in a
+   *  separate later run instead of faking a static holdout scenario and
+   *  recording a meaningless lift. */
+  holdout?: 'measured' | 'deferred';
+  /** 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
+   *  Live-runtime self-mutation is intentionally unsupported. */
+  autoOnPromote: 'pr' | 'none';
+  /** GH owner / repo for the auto-PR. Required when autoOnPromote === 'pr'. */
+  ghOwner?: string;
+  ghRepo?: 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>;
+  neutralizedOnHoldout?: CampaignResult<TArtifact, TScenario>;
+  neutralizedSurface?: MutableSurface;
+  gateResult: Awaited<ReturnType<Gate<TArtifact, TScenario>['decide']>>;
+  /** Present iff the loop ran with `holdout: 'deferred'`. When set,
+   *  `baselineOnHoldout`/`winnerOnHoldout` are the shared EMPTY campaign (zero
+   *  cells dispatched) and the gate verdict is the forced `'hold'`. */
+  holdout?: 'deferred';
+  /** 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>>;
+//#endregion
+//#region src/campaign/provenance.d.ts
+interface LoopProvenanceCandidate {
+  /** Generation index this candidate was proposed in. */
+  generation: number;
+  /** 16-char loop-identity fingerprint (matches `GenerationCandidate.surfaceHash`). */
+  surfaceHash: string;
+  /** Full sha256 content hash — byte-identical-verifiable. */
+  contentHash: string;
+  /** Exact scored rows that produced this candidate's search result. */
+  campaignDigest: `sha256:${string}`;
+  /** Proposer label, when the proposer returned a `ProposedCandidate`. */
+  label?: string;
+  /** Proposer rationale — the "because Z". When the proposer returned a bare
+   *  surface (blind mutator) this is absent. */
+  rationale?: string;
+  /** Exact complete incumbent this candidate mutated. */
+  parentSurfaceHash: string;
+  /** Search-split composite of the exact parent. */
+  parentComposite: number;
+  /** Search-split composite change relative to the exact parent. */
+  observedDeltaFromParent?: number;
+  /** Whether the candidate completed every designed cell and could be selected. */
+  eligibleForPromotion: boolean;
+  /** Designed-denominator receipt retained even for incomplete candidates. */
+  coverage: NonNullable<GenerationCandidate['coverage']>;
+  /** Mean composite this candidate scored on the search split, or null when unscorable. */
+  composite: number | null;
+  /** Whether this candidate was promoted out of its generation. */
+  promoted: boolean;
+}
+interface LoopProvenanceBackend {
+  /** `assertRealBackend`-grade verdict over the worker call records. */
+  verdict: 'real' | 'mixed' | 'stub';
+  /** Number of worker LLM calls captured (the audit's "worker call count"). */
+  workerCallCount: number;
+  /** Distinct model ids observed across worker calls. */
+  models: string[];
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCostUsd: number;
+}
+interface LoopProvenanceEvidence {
+  search: {
+    splitDigest: `sha256:${string}`;
+    baselineCampaignDigest: `sha256:${string}`;
+  };
+  holdout: {
+    splitDigest: `sha256:${string}`;
+    baselineCampaignDigest: `sha256:${string}`;
+    winnerCampaignDigest: `sha256:${string}`;
+    neutralized?: {
+      contentHash: `sha256:${string}`;
+      campaignDigest: `sha256:${string}`;
+      composite: number;
+      lift: number;
+    };
+  };
+  costReceiptsDigest: `sha256:${string}`;
+}
+interface LoopProvenanceOptimizationMethod {
+  name: string;
+  cost: ComparisonCost;
+  durationMs?: number;
+  provenance?: OptimizationMethodProvenance;
+}
+/**
+ * The durable provenance record. Aligns to the hosted `EvalRunEvent` path but
+ * ADDS the rationale + the explicit baseline→candidate diff (both omitted from
+ * the bare hosted event) + backend provenance.
+ */
+interface LoopProvenanceRecord {
+  schema: 'tangle.loop-provenance';
+  /** SHA-256 over the canonical record with this field omitted. */
+  recordDigest: `sha256:${string}`;
+  runId: string;
+  runDir: string;
+  timestamp: string;
+  /** Baseline + winner surface content hashes — distinguishable, byte-verifiable. */
+  baselineContentHash: string;
+  winnerContentHash: string;
+  /** Proposer label/rationale for the promoted change. Absent ⇒ winner == baseline. */
+  winnerLabel?: string;
+  winnerRationale?: string;
+  /** The explicit baseline→winner unified diff the gate decided on. */
+  diff: string;
+  /** Every candidate across every generation, with its rationale and structured cause. */
+  candidates: LoopProvenanceCandidate[];
+  /** Complete external method identity and spend, when one authored the candidate. */
+  optimizationMethod?: LoopProvenanceOptimizationMethod;
+  /** Exact campaign, split, surface, and receipt identities behind every summary. */
+  evidence: LoopProvenanceEvidence;
+  /** Baseline composite on the search split that generated the candidates. */
+  baselineSearchComposite: number;
+  /** The gate verdict — decision + reasons + contributing gates + delta. */
+  gate: {
+    decision: GateDecision;
+    reasons: string[];
+    delta?: number;
+    contributingGates: GateContribution[];
+  };
+  /** Present iff the loop ran with `holdout: 'deferred'` — the held-out
+   *  comparison was intentionally not measured in this run, so the holdout
+   *  composites and `heldOutLift` are ABSENT rather than recorded as a
+   *  meaningless 0. */
+  holdout?: 'deferred';
+  /** baseline-on-holdout composite mean. Absent when `holdout === 'deferred'`. */
+  baselineHoldoutComposite?: number;
+  /** winner-on-holdout composite mean. Absent when `holdout === 'deferred'`. */
+  winnerHoldoutComposite?: number;
+  /** winnerHoldout - baselineHoldout — RECOMPUTABLE from this record. Absent
+   *  when `holdout === 'deferred'` (no held-out measurement ran). */
+  heldOutLift?: number;
+  /** Backend provenance: stub-vs-real verdict + worker call count + models. */
+  backend: LoopProvenanceBackend;
+  totalCostUsd: number;
+  totalDurationMs: number;
+}
+interface BuildLoopProvenanceArgs<TArtifact, TScenario extends Scenario> {
+  runId: string;
+  runDir: string;
+  timestamp: string;
+  baselineSurface: MutableSurface;
+  winnerSurface: MutableSurface;
+  winnerLabel?: string;
+  winnerRationale?: string;
+  /** Exact baseline campaign on the search split. */
+  baselineSearchCampaign: CampaignResult<TArtifact, TScenario>;
+  /** Per-generation candidate records straight off the loop result. */
+  generations: Array<{
+    generationIndex: number;
+    candidates: GenerationCandidate[];
+    promoted: string[];
+    /** Surfaces measured this generation, keyed by surface hash so the content
+     *  hash can be computed and the loop identity rechecked from real bytes. */
+    surfaces: Array<{
+      surfaceHash: string;
+      surface: MutableSurface;
+      campaign: CampaignResult<TArtifact, TScenario>;
+    }>;
+  }>;
+  gate: GateResult;
+  /** Holdout policy the loop ran with. `'deferred'` ⇒ the holdout campaigns
+   *  below are the shared empty campaign and the record omits the holdout
+   *  composites + `heldOutLift`. Default `'measured'`. */
+  holdout?: 'measured' | 'deferred';
+  baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
+  winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
+  neutralizedSurface?: MutableSurface;
+  neutralizedOnHoldout?: CampaignResult<TArtifact, TScenario>;
+  /** Settled run-wide receipts — agent calls are the source for backend provenance. */
+  costReceipts: ReadonlyArray<CostReceipt>;
+  totalCostUsd: number;
+  totalDurationMs: number;
+  optimizationMethod?: LoopProvenanceOptimizationMethod;
+}
+interface LoopProvenanceArgsFromResult<TArtifact, TScenario extends Scenario> {
+  runId: string;
+  runDir: string;
+  timestamp: string;
+  baselineSurface: MutableSurface;
+  result: RunImprovementLoopResult<TArtifact, TScenario>;
+  costReceipts: ReadonlyArray<CostReceipt>;
+  totalCostUsd: number;
+  totalDurationMs: number;
+}
+/** One translation from a completed improvement loop into durable evidence. */
+declare function loopProvenanceArgsFromResult<TArtifact, TScenario extends Scenario>(input: LoopProvenanceArgsFromResult<TArtifact, TScenario>): BuildLoopProvenanceArgs<TArtifact, TScenario>;
+/** Build the durable provenance record from a completed loop result. */
+declare function buildLoopProvenanceRecord<TArtifact, TScenario extends Scenario>(args: BuildLoopProvenanceArgs<TArtifact, TScenario>): LoopProvenanceRecord;
+/** Digest the exact campaign fields that can affect a measured comparison. */
+declare function campaignMeasurementDigest<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): `sha256:${string}`;
+/** Recompute and validate the self-addressed durable record. */
+declare function verifyLoopProvenanceRecord(record: LoopProvenanceRecord): LoopProvenanceRecord;
+declare function canonicalDigest(value: unknown): `sha256:${string}`;
+/**
+ * Build the loop's OTLP-ingestable spans from a provenance record. One root
+ * span per loop (`tangle.runId`), one span per generation, one span per
+ * candidate (carrying its surfaceHash + label), and one span for the gate
+ * decision (carrying reasons + delta + lift). Candidate + gate spans pivot on
+ * the same `tangle.runId` / `tangle.generation` attributes `/adapters/otel`
+ * reads, so the hosted collector reconstructs the full tree.
+ *
+ * Times are synthesized monotonically off a single base so the span tree is
+ * orderable; the substrate does not retain per-candidate wall-clock starts.
+ */
+declare function loopProvenanceSpans(record: LoopProvenanceRecord, opts?: {
+  baseTimeMs?: number;
+}): TraceSpanEvent[];
+/** Canonical durable paths under the run dir. */
+declare function provenanceRecordPath(runDir: string): string;
+/**
+ * Canonical path for the durable OTLP spans JSONL file under a loop run directory.
+ */
+declare function provenanceSpansPath(runDir: string): string;
+interface EmitLoopProvenanceResult {
+  record: LoopProvenanceRecord;
+  spans: TraceSpanEvent[];
+  /** Absolute paths the record + spans were written to, when storage persists. */
+  recordPath: string;
+  spansPath: string;
+}
+interface EmitLoopProvenanceArgs<TArtifact, TScenario extends Scenario> extends BuildLoopProvenanceArgs<TArtifact, TScenario> {
+  /** Storage the record + spans are written through. */
+  storage: CampaignStorage;
+  /** When set, the spans are also shipped to the hosted `/v1/ingest/traces`
+   *  endpoint so the collector receives the full loop, not just `cost.*`. */
+  hostedClient?: HostedClient;
+}
+/**
+ * Build the provenance record + OTel spans and persist them durably under the
+ * run dir (and ship spans to a hosted collector when one is wired). Returns
+ * both artifacts so the caller can assert on / re-derive from them.
+ *
+ * Fail-loud: the durable write throws on storage failure (a swallowed write is
+ * exactly the "emitted but lost" failure this closes). The hosted span ship is
+ * the one best-effort leg — its failure is logged, not thrown, so an offline
+ * collector never fails the loop (the durable artifact is the source of truth).
+ */
+declare function emitLoopProvenance<TArtifact, TScenario extends Scenario>(args: EmitLoopProvenanceArgs<TArtifact, TScenario>): Promise<EmitLoopProvenanceResult>;
+//#endregion
+//#region src/campaign/skillopt-optimization-method.d.ts
+interface SkillOptTrainerConfig {
+  epochs: number;
+  batchSize: number;
+  accumulation?: number;
+  editBudget?: number;
+  minEditBudget?: number;
+  analystWorkers?: number;
+  minibatchSize?: number;
+  mergeBatchSize?: number;
+  maxAnalystRounds?: number;
+  evaluationWorkers?: number;
+  learningRateSchedule?: 'constant' | 'linear' | 'cosine' | 'autonomous';
+  learningRateControl?: 'fixed' | 'autonomous' | 'none';
+  updateMode?: 'patch' | 'rewrite_from_suggestions' | 'full_rewrite_minibatch';
+  failureOnly?: boolean;
+  useSlowUpdate?: boolean;
+  useMetaSkill?: boolean;
+  /**
+   * Additional flat SkillOpt trainer settings. Tangle overwrites data,
+   * output, split, seed, validation, and activation settings.
+   */
+  overrides?: Record<string, unknown>;
+}
+type SkillOptRunnerCommand = ExternalOptimizerRunnerCommand;
+interface SkillOptOptimizationMethodConfig<TScenario extends Scenario, TArtifact = unknown> {
+  name?: string;
+  /** Goal included with every described train and selection case. */
+  objective: string;
+  background?: string;
+  /** Stable identity for the dispatch, judges, model settings, and scoring logic. */
+  evaluationId: string;
+  trainer: SkillOptTrainerConfig;
+  /**
+   * OpenAI-compatible model connection and hard limits for SkillOpt's own
+   * optimizer calls.
+   */
+  optimizer: OpenAICompatibleOptimizerModel;
+  /** Hard cap on candidate-case callback requests. */
+  maxEvaluations: number;
+  /** Scores at or above this value count as hard successes. Default: 1. */
+  hardScoreThreshold?: number;
+  maxCandidateChars?: number;
+  /** Maximum serialized scenario plus evaluation evidence. Default: 100,000. */
+  maxEvidenceChars?: number;
+  timeoutMs?: number;
+  describeScenario?: (scenario: TScenario) => unknown;
+  describeArtifact?: (artifact: TArtifact, scenario: TScenario) => unknown;
+  resume?: ExternalOptimizerResumeMode;
+  runner?: SkillOptRunnerCommand;
+}
+/** Run Microsoft's SkillOpt trainer as a complete optimization method. */
+declare function skillOptOptimizationMethod<TScenario extends Scenario, TArtifact>(config: SkillOptOptimizationMethodConfig<TScenario, TArtifact>): OptimizationMethod<TScenario, TArtifact>;
+//#endregion
+export { Objective as $, optimizationTokenUsageFromSummary as $t, RunEvalOptions as A, CanarySeverity as At, OptimizerModelBudget as B, ComparisonCost as Bt, RunImprovementLoopOptions as C, ReferenceEquivalenceJudgeResult as Cn, scoreRedTeamOutput as Ct, RunOptimizationOptions as D, LlmJudgeDimension as Dn, CanaryKind as Dt, PremeasuredOptimizationBaseline as E, runReferenceEquivalenceJudge as En, CanaryEvaluation as Et, GepaOptimizationMethodConfig as F, ExternalTextOptimizerContext as Ft, ObjectiveSource as G, OptimizationMethodProvenance as Gt, AxisVerdict as H, OptimizationMethodComparison as Ht, GepaOptimizationRecipe as I, ExternalTextOptimizerResult as It, PromotionPolicy as J, OptimizationMethodScore as Jt, ParetoSignificanceGateOptions as K, OptimizationMethodResult as Kt, GepaRunnerCommand as L, ExternalOptimizationExample as Lt, GepaAdaptiveEngineRun as M, composeGate as Mt, GepaEngineOptions as N, externalTextOptimizationMethod as Nt, RunOptimizationResult as O, LlmJudgeOptions as On, CanaryOptions as Ot, GepaEngineRun as P, ExternalTextOptimizationMethodConfig as Pt, Direction as Q, costFromLedgerSummary as Qt, gepaOptimizationMethod as R, ExternalTextEvaluationResponse as Rt, verifyLoopProvenanceRecord as S, ReferenceEquivalenceJudgeOptions as Sn, redTeamReport as St, runImprovementLoop as T, createReferenceEquivalenceJudge as Tn, CanaryAlert as Tt, BuildEvidenceVectorOptions as U, OptimizationMethodInput as Ut, AxisEvidence as V, OptimizationMethod as Vt, EvidenceVector as W, OptimizationMethodPairwise as Wt, paretoPolicy as X, OptimizationTokenUsage as Xt, buildEvidenceVector as Y, OptimizationPackageSource as Yt, paretoSignificanceGate as Z, compareOptimizationMethods as Zt, emitLoopProvenance as _, OpenAutoPrResult as _n, RedTeamCategory as _t, BuildLoopProvenanceArgs as a, planCampaignRun as an, scalarScore as at, provenanceRecordPath as b, REFERENCE_EQUIVALENCE_JUDGE_VERSION as bn, RedTeamReport as bt, LoopProvenanceArgsFromResult as c, createRunCostLedger as cn, powerPreflight as ct, LoopProvenanceEvidence as d, assertCampaignDesign as dn, DefaultProductionGateCheck as dt, CampaignCellFailureReceipt as en, ParetoResult as et, LoopProvenanceOptimizationMethod as f, assertCampaignSplitIdentity as fn, DefaultProductionGateOptions as ft, canonicalDigest as g, OpenAutoPrOptions as gn, RedTeamCase as gt, campaignMeasurementDigest as h, campaignSplitDigestFromIdentities as hn, DEFAULT_RED_TEAM_CORPUS as ht, skillOptOptimizationMethod as i, RunCampaignOptions as in, paretoFrontierWithCrowding as it, runEval as j, runCanaries as jt, runOptimization as k, llmJudge as kn, CanaryReport as kt, LoopProvenanceBackend as l, fsCampaignStorage as ln, HeldOutGateOptions as lt, buildLoopProvenanceRecord as m, campaignSplitDigest as mn, defaultProductionGate as mt, SkillOptRunnerCommand as n, CampaignRunPlanCell as nn, dominates as nt, EmitLoopProvenanceArgs as o, runCampaign as on, PowerPreflight as ot, LoopProvenanceRecord as p, campaignScenarioIdentity as pn, DefaultProductionRewardHackingOptions as pt, PromotionObjective as q, OptimizationMethodRunOptions as qt, SkillOptTrainerConfig as r, PlanCampaignRunOptions as rn, paretoFrontier as rt, EmitLoopProvenanceResult as s, CampaignStorage as sn, PowerPreflightOptions as st, SkillOptOptimizationMethodConfig as t, CampaignRunPlan as tn, crowdingDistance as tt, LoopProvenanceCandidate as u, inMemoryCampaignStorage as un, heldOutGate as ut, loopProvenanceArgsFromResult as v, openAutoPr as vn, RedTeamFinding as vt, RunImprovementLoopResult as w, ReferenceEquivalenceScenario as wn, toolNamesForRun as wt, provenanceSpansPath as x, ReferenceEquivalenceJudgeInput as xn, redTeamDataset as xt, loopProvenanceSpans as y, REFERENCE_EQUIVALENCE_INPUT_LIMITS as yn, RedTeamPayload as yt, OpenAICompatibleOptimizerModel as z, CompareOptimizationMethodsOptions as zt };
+//# sourceMappingURL=skillopt-optimization-method-B7wX7XkF.d.ts.map