@tangle-network/agent-eval 0.173.2 → 0.174.0

package/dist/index-DKXuBPXf.d.ts

@@ -0,0 +1,3840 @@
+import { c as ValidationError, t as AgentEvalError } from "./errors-DEE6u6ot.js";
+import { T as RunPaidCallInput, c as CostLedgerHandle, f as CostLedgerSummary, m as CostReceipt, o as CostLedger, p as CostProvenance } from "./cost-ledger-DbQdN3nO.js";
+import { a as RunRecord, s as RunSplitTag } from "./run-record-DTv1MdjK.js";
+import { _ as ProposalFinding, f as AnalystUsageReceipt, i as AnalystFinding, l as AnalystRunResult, w as TraceAnalysisStore } from "./types-DN2WdT5S.js";
+import { Y as RawProviderSink, it as ServedModelPolicy, p as ChatClient, w as LlmCallMetadata } from "./types-gvRsyJLh.js";
+import { P as PairedArmsComparison } from "./statistical-heldout-Cqb73yE9.js";
+import { d as PairedBootstrapResult } from "./paired-promotion-decision-CGzg0cI_.js";
+import { A as LabeledScenarioWrite, B as ScoredSurfaceOutcome, C as JudgeDimension, D as LabeledScenarioSampleArgs, E as LabeledScenarioRecord, H as SurfaceProposer, N as ParetoParent, O as LabeledScenarioSource, R as Scenario, S as JudgeConfig, T as LabelTrust, _ as GateDecision, a as CampaignResult, b as GenerationRecord, c as CampaignTraceWriter, d as DispatchContext, f as DispatchFn, g as GateContribution, i as CampaignCostMeter, j as MutableSurface, k as LabeledScenarioStore, l as CodeSurface, o as CampaignScenarioIdentity, p as Gate, r as CampaignCellResult, u as ComponentSurface, v as GateResult, y as GenerationCandidate } from "./types-BJz2CPTM.js";
+import { m as LedgerTrustedHeadRemoval, p as LedgerTrustedHead } from "./index-D-UdhAmg.js";
+import { r as LedgerHash } from "./canonical-CFpojCN5.js";
+import { B as ExternalOptimizerModelBudget, E as AnalystIssueExpectation, F as ExternalOptimizerCallbackLimits, J as ExternalOptimizerWireCounts, K as ExternalOptimizerResumeMode, R as ExternalOptimizerEvaluationObservation, V as ExternalOptimizerModelCall, X as ExternalTextEvaluationRequest, Y as ExternalTextCandidate, m as AnalystBenchmarkLabelState, q as ExternalOptimizerRunnerCommand, t as AgentProfile$1, u as AnalystBenchmarkCase } from "./agent-profile-_xPxqVJt.js";
+import { r as DatasetScenario, t as Dataset } from "./dataset-DQqhOCPt.js";
+import { a as CheckerIdentity, n as VerdictCertification, t as DefaultVerdict, x as VerificationStrategySource } from "./verdict-E4eRNf7-.js";
+import { t as DetectRewardHackingInput } from "./reward-hacking-ZXEi9VCq.js";
+import { g as TraceSpanEvent, t as HostedClient } from "./client-vyYQg3bm.js";
+import { AgentProfile } from "@tangle-network/agent-interface";
+import { z } from "zod";
+//#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/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;
+  /** Set false for read-only inspection that must not create the run directory. */
+  ensureRunDir?: boolean;
+}): CostLedger;
+//#endregion
+//#region src/campaign/cell-schedule.d.ts
+declare function buildCellSchedule<TScenario extends Scenario>(scenarios: TScenario[], seed: number, reps: number): Array<{
+  scenario: TScenario;
+  rep: number;
+  cellId: string;
+  cellSeed: number;
+}>;
+type CellScheduleSlot<TScenario extends Scenario> = ReturnType<typeof buildCellSchedule<TScenario>>[number];
+declare function cellCachePath(runDir: string, cellId: string): string;
+//#endregion
+//#region src/campaign/cell-cache.d.ts
+type CacheIssueReason = 'missing' | 'manifest-mismatch' | 'cell-mismatch' | 'missing-cost-provenance' | 'invalid-cost-provenance' | 'invalid-cost-receipts' | 'corrupt';
+type CacheRead<TArtifact> = {
+  status: 'hit';
+  cell: CampaignCellResult<TArtifact>;
+} | {
+  status: 'miss';
+  reason: CacheIssueReason;
+};
+declare function readCachedCell<TArtifact>(args: {
+  storage: CampaignStorage;
+  cachePath: string;
+  cellId: string;
+  manifestHash: string;
+}): CacheRead<TArtifact>;
+//#endregion
+//#region src/campaign/plan-campaign-run.d.ts
+interface CampaignRunPlanCell {
+  cellId: string;
+  scenarioId: string;
+  rep: number;
+  seed: number;
+  cachePath: string;
+  status: 'cached' | 'run' | 'blocked';
+  reason?: CacheIssueReason | 'resumable-off';
+}
+interface CampaignRunPlan {
+  manifestHash: string;
+  splitDigest: `sha256:${string}`;
+  totalCells: number;
+  cellsCached: number;
+  cellsBlocked: 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;
+  /** See RunCampaignOptions.rerunInvalidCachedCells. */
+  rerunInvalidCachedCells?: boolean;
+  runDir: string;
+  /** Subject repo for the shared run-dir root (see RunCampaignOptions.repo). */
+  repo?: string;
+  storage?: CampaignStorage;
+  /** Spend account used to validate cached receipt identities. */
+  costLedger?: CostLedgerHandle;
+  /** Receipt tags used by the campaign that produced the cached cells. */
+  costTags?: Readonly<Record<string, string>>;
+}
+/**
+ * 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/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 explicit cell selection. The campaign manifest and split digest
+   * still describe the complete declared scenario × replicate design; this
+   * only limits the rows executed by this invocation.
+   */
+  cellFilter?: (input: {
+    scenario: TScenario;
+    rep: number;
+  }) => boolean;
+  /**
+   * Reuse a cached cell that has an error instead of dispatching it again.
+   * The default retries failed cells, preserving normal campaign behaviour.
+   */
+  reuseFailedCells?: boolean;
+  /**
+   * Explicitly rerun only cached cells whose saved result is unreadable or
+   * has missing/invalid cost provenance. Valid cached cells remain reusable.
+   * Default false refuses to begin work when any such cache entry exists.
+   */
+  rerunInvalidCachedCells?: 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.
+   * With `cellRetry`, a retryable failure is not an error yet: this abort
+   * fires only when a cell's final attempt fails.
+   */
+  abortOnCellError?: boolean;
+  /**
+   * Opt-in bounded in-run retry of a failed cell. Absent by default: a failed
+   * cell is final on its first attempt. A retried attempt re-runs the SAME
+   * slot — same `cellId`, same `seed`, same cost tags — so the schedule,
+   * manifest, and pairing are unchanged. An attempt that failed because the
+   * campaign was cancelled is never retried.
+   */
+  cellRetry?: CampaignCellRetryPolicy;
+  /**
+   * 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;
+}
+/**
+ * Bounded in-run retry of failed cells. Every attempt dispatches the same
+ * slot and charges the shared cost ledger, so the final cell's `costUsd`,
+ * `tokenUsage`, and `costCallIds` cover all attempts. Each retried attempt
+ * keeps its failure receipt at `<cell>/failure-receipt.attempt-<n>.json`; a
+ * final failed attempt keeps the usual `<cell>/failure-receipt.json`. The
+ * final cell records the retry count as `retryAttempts`. Artifacts and trace
+ * spans written by a later attempt replace those of the retried attempt; the
+ * per-attempt failure receipts are the durable evidence.
+ */
+interface CampaignCellRetryPolicy {
+  /** Total attempts per cell, including the first. A positive safe integer. */
+  attempts: number;
+  /** Decides whether a failed attempt is dispatched again. Receives the
+   *  receipt's `failure` record. `transientDispatchFailure()` is the
+   *  ready-made predicate for infrastructure hiccups (502/503/504, dropped
+   *  streams, admission rejections). */
+  retryable: (failure: CampaignCellFailureReceipt['failure']) => boolean;
+}
+/**
+ * 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>>;
+//#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/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/parent-selection.d.ts
+/** Search state supplied to one parent-selection call. */
+interface ParentSelectionContext {
+  /** Non-dominated scored surfaces across the whole run so far, including the
+   *  baseline (`generation: -1`). Never empty. */
+  readonly frontier: ReadonlyArray<ParetoParent>;
+  /** Measured result of the global incumbent, the promotion bar. Under the
+   *  default `selectionRankKey` the incumbent is always on `frontier`. */
+  readonly incumbent: ScoredSurfaceOutcome;
+  /** Every completed generation so far. */
+  readonly history: ReadonlyArray<GenerationRecord>;
+  /** Index of the generation about to propose. */
+  readonly generation: number;
+}
+/** Chooses the surface the next generation mutates. Returns one frontier
+ *  parent; `runOptimization` refuses a parent it has not measured to
+ *  completion or whose surface does not match its `surfaceHash`. */
+type ParentSelector = (ctx: ParentSelectionContext) => ParetoParent;
+interface CrowdedFrontierParentOptions {
+  /** Integer seed for the per-generation draw. The same seed, frontier, and
+   *  generation index select the same parent. */
+  seed: number;
+}
+/**
+ * NSGA-II crowded tournament selection over the frontier. Each generation
+ * draws two distinct frontier members with a PRNG seeded from `seed` and the
+ * generation index, and keeps the one with the larger crowding distance (more
+ * isolated on the frontier). Boundary parents carry infinite distance, so a
+ * boundary parent always beats an interior one. A tie on distance falls back
+ * to the higher mean composite, then to the smaller surface hash. A frontier
+ * of one member returns that member.
+ */
+declare function crowdedFrontierParent(options: CrowdedFrontierParentOptions): ParentSelector;
+//#endregion
+//#region src/campaign/search-ledger-errors.d.ts
+/** Base error for invalid search-ledger input or operations. */
+declare class SearchLedgerError extends ValidationError {}
+/** Error raised when durable search-ledger data fails an integrity check. */
+declare class SearchLedgerIntegrityError extends SearchLedgerError {}
+/** Error raised when an event identifier is reused with different content. */
+declare class SearchLedgerConflictError extends SearchLedgerError {}
+//#endregion
+//#region src/campaign/search-ledger.d.ts
+declare const SEARCH_LEDGER_SCHEMA: 'tangle.search-ledger.v1';
+type SearchLedgerHash = LedgerHash;
+type SearchSurfaceKind = 'prompt' | 'tool-contract' | 'runtime-config' | 'memory' | 'knowledge' | 'agent-profile' | 'code' | 'deployment';
+/** Content-addressed artifact or receipt. Mutable paths are locators only; the
+ * digest and byte length bind the exact bytes used by the search. */
+interface SearchArtifactRef {
+  role: string;
+  uri: string;
+  sha256: SearchLedgerHash;
+  byteLength: number;
+}
+/** Repository, dataset, or package source pinned to an immutable commit or
+ * content digest. Branches, tags, and bare package versions are rejected. */
+interface SearchSourceRef {
+  uri: string;
+  revision: string;
+}
+interface SearchModelIdentity {
+  provider: string;
+  snapshot: string;
+}
+interface SearchCandidateSurface {
+  surfaceId: string;
+  kind: SearchSurfaceKind;
+  artifact: SearchArtifactRef;
+}
+interface SearchCandidateLineage {
+  /** Existing `LineageNode.id`; this ledger references rather than embeds it. */
+  lineageNodeId: string;
+  parentCandidateIds: string[];
+  generation: number;
+  proposer: string;
+  proposerSource: SearchSourceRef;
+}
+type SearchOperationKind = 'candidate-generation' | 'analysis' | 'selection' | 'judge' | 'other';
+interface SearchPlannedTask {
+  taskId: string;
+  source: SearchSourceRef;
+  benchmark: SearchSourceRef;
+  /** Maximum transport attempts for this task and candidate. Only an explicit
+   * passed/failed outcome satisfies the planned denominator. */
+  maxAttempts: number;
+}
+interface SearchPlannedOperation {
+  operationId: string;
+  kind: SearchOperationKind;
+}
+interface SearchCandidateSlot {
+  slotId: string;
+  /** Planned candidate-generation call that must either produce this slot or
+   * fail before the slot can be closed. Several slots may share one batched call. */
+  generationOperationId: string;
+}
+interface SearchPlan {
+  /** Stable slots and their proposer calls are frozen before search begins. */
+  candidateSlots: SearchCandidateSlot[];
+  /** Every task applies to every successfully registered candidate. */
+  tasks: SearchPlannedTask[];
+  /** Non-task spend slots: proposal, analysis, selection, extra judges, etc. */
+  operations: SearchPlannedOperation[];
+}
+type SearchTokenAccounting = {
+  status: 'known';
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
+} | {
+  status: 'unknown';
+  reason: string;
+};
+type SearchCostAccounting = {
+  status: 'known';
+  usd: number;
+  source: 'provider' | 'pricing-table' | 'free';
+} | {
+  status: 'unknown';
+  /** Known spend may still be a lower bound when one call was unpriced. */
+  knownLowerBoundUsd: number;
+  reason: string;
+};
+interface SearchAttemptAccounting {
+  tokens: SearchTokenAccounting;
+  cost: SearchCostAccounting;
+}
+interface SearchFailureReason {
+  code: string;
+  message: string;
+}
+type SearchTaskOutcome = {
+  status: 'passed';
+  score: number;
+  metrics: Record<string, number>;
+} | {
+  status: 'failed';
+  score: number;
+  metrics: Record<string, number>;
+  failure: SearchFailureReason;
+} | {
+  status: 'errored';
+  metrics: Record<string, number>;
+  error: SearchFailureReason & {
+    retryable: boolean;
+  };
+};
+type SearchSurfaceEffect = {
+  status: 'measured';
+  metric: string;
+  baselineValue: number;
+  candidateValue: number;
+  delta: number;
+} | {
+  status: 'not-measured';
+  reason: string;
+};
+/** Per-attempt proof that a declared candidate surface was or was not active,
+ * plus measured effect when the experiment supports attribution. */
+interface SearchSurfaceEvidence {
+  surfaceId: string;
+  fired: boolean;
+  firingCount: number;
+  effect: SearchSurfaceEffect;
+  evidence: SearchArtifactRef[];
+}
+interface SearchLedgerEventBase {
+  eventId: string;
+  occurredAt: string;
+  artifacts: SearchArtifactRef[];
+}
+interface SearchPlannedEvent extends SearchLedgerEventBase {
+  kind: 'search-planned';
+  plan: SearchPlan;
+}
+/** Additional candidate slots and operations for a search whose length is not
+ * known when it starts. The plan stays the first event and the planned task
+ * denominator stays frozen: extending tasks would retroactively reopen
+ * candidates that already closed theirs. */
+interface SearchPlanExtendedEvent extends SearchLedgerEventBase {
+  kind: 'search-plan-extended';
+  extension: {
+    candidateSlots: SearchCandidateSlot[];
+    operations: SearchPlannedOperation[];
+  };
+}
+interface SearchCandidateRegisteredEvent extends SearchLedgerEventBase {
+  kind: 'candidate-registered';
+  slotId: string;
+  generationOperationId: string;
+  candidateId: string;
+  lineage: SearchCandidateLineage;
+  surfaces: SearchCandidateSurface[];
+}
+interface SearchCandidateSlotClosedEvent extends SearchLedgerEventBase {
+  kind: 'candidate-slot-closed';
+  slotId: string;
+  generationOperationId: string;
+  reason: SearchFailureReason;
+}
+interface SearchTaskAttemptedEvent extends SearchLedgerEventBase {
+  kind: 'task-attempted';
+  candidateId: string;
+  runId: string;
+  attemptIndex: number;
+  task: {
+    taskId: string;
+    source: SearchSourceRef;
+  };
+  identity: {
+    model: SearchModelIdentity;
+    agent: SearchSourceRef;
+    benchmark: SearchSourceRef;
+  };
+  outcome: SearchTaskOutcome;
+  accounting: SearchAttemptAccounting;
+  surfaceEvidence: SearchSurfaceEvidence[];
+}
+interface SearchOperationRecordedEvent extends SearchLedgerEventBase {
+  kind: 'search-operation-recorded';
+  operationId: string;
+  operationKind: SearchOperationKind;
+  execution: {
+    kind: 'model';
+    model: SearchModelIdentity;
+    source: SearchSourceRef;
+  } | {
+    kind: 'deterministic';
+    source: SearchSourceRef;
+  };
+  outcome: {
+    status: 'completed';
+  } | {
+    status: 'partial';
+    failure: SearchFailureReason;
+  } | {
+    status: 'failed';
+    failure: SearchFailureReason;
+  };
+  accounting: SearchAttemptAccounting;
+}
+interface SearchCandidateDecidedEvent extends SearchLedgerEventBase {
+  kind: 'candidate-decided';
+  candidateId: string;
+  decision: {
+    status: 'selected';
+  } | {
+    status: 'rejected';
+    reason: SearchFailureReason;
+  };
+}
+interface SearchCompletedEvent extends SearchLedgerEventBase {
+  kind: 'search-completed';
+  result: {
+    status: 'selected';
+    candidateId: string;
+  } | {
+    status: 'all-rejected';
+    reason: SearchFailureReason;
+  };
+}
+type SearchLedgerEvent = SearchPlannedEvent | SearchPlanExtendedEvent | SearchCandidateRegisteredEvent | SearchCandidateSlotClosedEvent | SearchTaskAttemptedEvent | SearchOperationRecordedEvent | SearchCandidateDecidedEvent | SearchCompletedEvent;
+interface SearchLedgerEntry {
+  schema: typeof SEARCH_LEDGER_SCHEMA;
+  campaignId: string;
+  sequence: number;
+  previousHash: SearchLedgerHash | null;
+  event: SearchLedgerEvent;
+  entryHash: SearchLedgerHash;
+}
+type SearchAccountingAudit = {
+  status: 'known';
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
+  costUsd: number;
+} | {
+  status: 'partial';
+  knownInputTokens: number;
+  knownOutputTokens: number;
+  knownCachedTokens: number;
+  knownCostUsd: number;
+  unknownTokenEventIds: string[];
+  unknownCostEventIds: string[];
+};
+interface SearchLedgerAudit {
+  campaignId: string;
+  eventCount: number;
+  candidateCount: number;
+  closedCandidateSlotCount: number;
+  attemptCount: number;
+  operationCount: number;
+  outcomes: {
+    passed: number;
+    failed: number;
+    errored: number;
+  };
+  operationOutcomes: {
+    completed: number;
+    partial: number;
+    failed: number;
+  };
+  decisions: {
+    selected: number;
+    rejected: number;
+    pending: number;
+  };
+  expected: {
+    candidateSlots: number;
+    taskOutcomes: number;
+    operations: number;
+    missingCandidateSlots: string[];
+    missingTaskOutcomes: string[];
+    missingOperations: string[];
+  };
+  status: 'in-progress' | 'selected' | 'all-rejected';
+  selectedCandidateId: string | null;
+  accounting: SearchAccountingAudit;
+  headHash: SearchLedgerHash | null;
+}
+interface SearchLedgerReplay {
+  entries: SearchLedgerEntry[];
+  plan: SearchPlannedEvent | null;
+  /** Appended plan extensions, in ledger order. The effective plan is the
+   *  first plan event merged with these; `audit.expected` counts the merge. */
+  planExtensions: SearchPlanExtendedEvent[];
+  candidates: SearchCandidateRegisteredEvent[];
+  closedCandidateSlots: SearchCandidateSlotClosedEvent[];
+  attempts: SearchTaskAttemptedEvent[];
+  operations: SearchOperationRecordedEvent[];
+  decisions: SearchCandidateDecidedEvent[];
+  completion: SearchCompletedEvent | null;
+  audit: SearchLedgerAudit;
+}
+interface SearchLedgerAppendResult {
+  entry: SearchLedgerEntry;
+  /** False when the exact event was already durably present. */
+  appended: boolean;
+  replay: SearchLedgerReplay;
+}
+/** Validate and return a canonical copy. Arrays whose order is not semantic are
+ * sorted so retries from different processes produce byte-identical events. */
+declare function validateSearchLedgerEvent(input: unknown): SearchLedgerEvent;
+/**
+ * How this ledger uses its trusted head — the `(sequence, entryHash)` pin kept
+ * in the sibling `<path>.head` file that a hash chain needs to prove entries
+ * were not deleted from the end. `ledger-core/trusted-head.ts` holds the threat
+ * model.
+ *
+ * - `pin` (default): every append records the new head, and a pin that is
+ *   present is verified on every read.
+ * - `require`: additionally refuses to read a non-empty ledger whose pin is
+ *   gone, so deleting the sibling file cannot downgrade the guarantee. Only for
+ *   ledgers written under `pin` from their first entry.
+ * - `off`: chain verification only. Truncation to a valid shorter prefix is
+ *   undetectable.
+ */
+type SearchLedgerTrustedHeadMode = 'pin' | 'require' | 'off';
+interface OpenSearchLedgerOptions {
+  path: string;
+  campaignId: string;
+  trustedHead?: SearchLedgerTrustedHeadMode;
+}
+interface SearchLedger {
+  readonly path: string;
+  readonly campaignId: string;
+  /** Sibling file holding this ledger's trusted head. */
+  readonly trustedHeadPath: string;
+  append(event: SearchLedgerEvent): Promise<SearchLedgerAppendResult>;
+  replay(): Promise<SearchLedgerReplay>;
+  /** The pinned head, or null when this ledger has never been pinned. */
+  trustedHead(): Promise<LedgerTrustedHead | null>;
+  /** Pin the current verified head: how a ledger written under `off`, or one
+   * whose pin file was removed, acquires a pin without rewriting a byte. */
+  pinTrustedHead(): Promise<LedgerTrustedHead>;
+  /** Discard this ledger's pin, reporting what was discarded. Deleting or
+   * rebuilding the ledger file leaves a pin naming history the file no longer
+   * carries, and every later read is refused because that is exactly the
+   * deletion the pin exists to catch; clearing is the supported way to abandon
+   * that history on purpose. It gives up the deletion guarantee for every entry
+   * the pin covered. */
+  clearTrustedHead(): Promise<LedgerTrustedHeadRemoval>;
+}
+/** Open a durable filesystem search ledger. Construction performs no I/O; the
+ * first `append` or `replay` validates the complete existing file. */
+declare function openSearchLedger(options: OpenSearchLedgerOptions): SearchLedger;
+/** Append-only file-backed search ledger with idempotent writes and replay. */
+declare class FileSearchLedger implements SearchLedger {
+  readonly path: string;
+  readonly campaignId: string;
+  readonly trustedHeadPath: string;
+  private readonly trustedHeadMode;
+  private readonly journal;
+  constructor(path: string, campaignId: string, trustedHead?: SearchLedgerTrustedHeadMode);
+  replay(): Promise<SearchLedgerReplay>;
+  append(input: SearchLedgerEvent): Promise<SearchLedgerAppendResult>;
+  trustedHead(): Promise<LedgerTrustedHead | null>;
+  pinTrustedHead(): Promise<LedgerTrustedHead>;
+  clearTrustedHead(): Promise<LedgerTrustedHeadRemoval>;
+}
+//#endregion
+//#region src/campaign/search-history-receipt.d.ts
+declare const SEARCH_HISTORY_RECEIPT_SCHEMA_VERSION: '1.0.0';
+declare const SEARCH_HISTORY_RECEIPT_DIGEST_ALGORITHM: 'rfc8785-sha256';
+/** Bounded projection of the canonical replay audit. Exact ids stay in SearchLedger. */
+interface SearchHistoryAuditSummary {
+  readonly campaignId: string;
+  readonly headHash: SearchLedgerHash | null;
+  readonly status: SearchLedgerAudit['status'];
+  readonly selectedCandidateId: string | null;
+  readonly eventCount: number;
+  readonly candidateCount: number;
+  readonly closedCandidateSlotCount: number;
+  readonly attemptCount: number;
+  readonly operationCount: number;
+  readonly expectedCandidateSlots: number;
+  readonly expectedTaskOutcomes: number;
+  readonly expectedOperations: number;
+  readonly missingCandidateSlots: number;
+  readonly missingTaskOutcomes: number;
+  readonly missingOperations: number;
+  readonly pendingDecisions: number;
+  readonly hasPlan: boolean;
+  readonly hasCompletion: boolean;
+}
+/**
+ * A bounded proof envelope over one canonical SearchLedger replay.
+ *
+ * The content-addressed ledger remains the sole rich history. This receipt binds
+ * its producer/run identity, exact audit digest, bounded completeness summary,
+ * and its own canonical digest. Consumers needing candidate ids, attempts,
+ * failures, accounting gaps, or decisions read and replay the canonical ledger.
+ */
+interface SearchHistoryReceipt {
+  readonly schemaVersion: typeof SEARCH_HISTORY_RECEIPT_SCHEMA_VERSION;
+  readonly kind: 'search-history-receipt';
+  readonly digestAlgorithm: typeof SEARCH_HISTORY_RECEIPT_DIGEST_ALGORITHM;
+  readonly receiptDigest: SearchLedgerHash;
+  /** Stable producer identity, for example an OptimizationMethod name. */
+  readonly producerId: string;
+  /** Concrete optimizer/runtime invocation that produced the ledger. */
+  readonly runId: string;
+  readonly ledger: SearchArtifactRef;
+  /** Digest of the complete SearchLedgerAudit produced by canonical replay. */
+  readonly auditDigest: SearchLedgerHash;
+  readonly summary: SearchHistoryAuditSummary;
+  readonly complete: boolean;
+  readonly incompleteReasons: readonly string[];
+}
+interface CreateSearchHistoryReceiptInput {
+  readonly producerId: string;
+  readonly runId: string;
+  /** Content-addressed canonical SearchLedger JSONL artifact. */
+  readonly ledger: SearchArtifactRef;
+  /** The result returned by SearchLedger.replay(). */
+  readonly replay: SearchLedgerReplay;
+}
+type SearchHistoryPolicy = 'allow-missing' | 'require-complete';
+interface SearchHistoryCoverageRow {
+  readonly producerId: string;
+  readonly status: 'complete' | 'incomplete' | 'missing';
+  readonly reasons: readonly string[];
+  readonly receipt?: SearchHistoryReceipt;
+}
+interface SearchHistoryCoverage {
+  readonly policy: SearchHistoryPolicy;
+  readonly allComplete: boolean;
+  readonly producers: readonly SearchHistoryCoverageRow[];
+}
+declare class SearchHistoryRequiredError extends Error {
+  readonly producerId: string;
+  readonly reasons: readonly string[];
+  constructor(producerId: string, reasons: readonly string[]);
+}
+/** Build a bounded receipt from the projection returned by canonical ledger replay. */
+declare function createSearchHistoryReceipt(input: CreateSearchHistoryReceiptInput): SearchHistoryReceipt;
+/** Verify the bounded receipt. Full ledger bytes are verified by SearchLedger. */
+declare function verifySearchHistoryReceipt(receipt: SearchHistoryReceipt): SearchHistoryReceipt;
+/** Prove that a receipt still describes the exact canonical replay supplied. */
+declare function assertSearchHistoryMatchesReplay(receipt: SearchHistoryReceipt, replay: SearchLedgerReplay): void;
+/** Require a receipt owned by this producer and a terminal, denominator-complete history. */
+declare function assertCompleteSearchHistory(producerId: string, receipt: SearchHistoryReceipt | undefined): asserts receipt is SearchHistoryReceipt;
+/** Classify one producer's history without treating malformed evidence as absence. */
+declare function searchHistoryCoverageRow(producerId: string, receipt: SearchHistoryReceipt | undefined): SearchHistoryCoverageRow;
+//#endregion
+//#region src/campaign/gepa-candidate-population.d.ts
+interface GepaCandidatePopulationSummary {
+  readonly scope: 'gepa-candidate-population';
+  readonly path: string;
+  readonly sha256: `sha256:${string}`;
+  readonly bytes: number;
+  readonly runId: string;
+  readonly candidates: number;
+  readonly bestIndex: number;
+  readonly maxCandidates: number;
+  readonly maxCandidateChars: number;
+  readonly scenarioIds: readonly string[];
+  readonly surfaceKind: 'text' | 'components';
+}
+interface GepaCandidateSelectionScore {
+  readonly scenarioId: string;
+  readonly score: number;
+}
+interface GepaCandidatePopulationCandidate {
+  /** Zero-based index assigned by the exact GEPA result. */
+  readonly index: number;
+  readonly candidate: ExternalTextCandidate;
+  readonly candidateHash: string;
+  readonly candidateDigest: `sha256:${string}`;
+  /** Exact GEPA parent indices. The seed candidate has one null parent. */
+  readonly parentIndices: readonly (number | null)[];
+  /** Null means GEPA had no selection score for this candidate. */
+  readonly aggregateScore: number | null;
+  readonly selectionScores: readonly GepaCandidateSelectionScore[];
+  readonly discoveryEvaluationCount: number;
+}
+interface GepaCandidatePopulationArtifact {
+  readonly summary: GepaCandidatePopulationSummary;
+  readonly runId: string;
+  readonly bestIndex: number;
+  readonly candidates: readonly GepaCandidatePopulationCandidate[];
+}
+/**
+ * Read GEPA's exact candidate graph from the artifact addressed by method provenance.
+ *
+ * The reader checks the supplied digest, declared byte count, run identity,
+ * candidate surfaces, parent graph, selection scores, and configured bounds.
+ * This proves that the bytes match the supplied summary. The caller remains
+ * responsible for obtaining that summary from trusted method provenance.
+ */
+declare function readGepaCandidatePopulationArtifact(input: {
+  summary: GepaCandidatePopulationSummary;
+  storage?: CampaignStorage;
+}): GepaCandidatePopulationArtifact;
+//#endregion
+//#region src/campaign/search-ledger-recording.d.ts
+/** How a search operation executed. The shape the ledger event records. */
+type SearchExecutionIdentity = SearchOperationRecordedEvent['execution'];
+/** Immutable identities the ledger requires and a campaign cannot infer. */
+interface SearchRunIdentity {
+  /** The agent implementation under optimization. */
+  agent: SearchSourceRef;
+  /** The candidate generator: a model call or deterministic code. */
+  proposer: SearchExecutionIdentity;
+  /** The code that plans the search and selects its winner. */
+  search: SearchSourceRef;
+  /** Model the agent runs. Used only for a cell that reported none. */
+  model: SearchModelIdentity;
+}
+interface SearchLedgerBinding {
+  ledger: SearchLedger;
+  identity: SearchRunIdentity;
+}
+/** One proposed candidate, before it is measured. */
+interface ProposedSearchCandidate {
+  surface: MutableSurface;
+  surfaceHash: string;
+  label?: string;
+}
+/** One measured candidate, after its campaign scored. */
+interface MeasuredSearchCandidate<TArtifact> {
+  surface: MutableSurface;
+  surfaceHash: string;
+  cells: ReadonlyArray<CampaignCellResult<TArtifact>>;
+  runDir: string;
+  /** False when the candidate missed a designed cell. */
+  coverageComplete: boolean;
+}
+interface SearchRecorderOptions<TScenario extends Scenario> {
+  binding: SearchLedgerBinding;
+  storage: CampaignStorage;
+  runDir: string;
+  scenarios: ReadonlyArray<TScenario>;
+  reps: number;
+  maxGenerations: number;
+  populationSize: number;
+  /** Identity of the exact campaign design; the task benchmark pin. */
+  splitDigest: `sha256:${string}`;
+  /** Proposer label recorded on every candidate lineage. */
+  proposerLabel: string;
+  costLedger: CostLedgerHandle;
+}
+/**
+ * Recorder for one `runOptimization` run: `open()`, then `recordGeneration()`
+ * and `recordResults()` per generation, then `finish()`.
+ *
+ * Every event id is derived from the run, and an id already durable is not
+ * appended again, so a resumed run continues one ledger instead of conflicting
+ * with its own history.
+ */
+declare class SearchRecorder<TScenario extends Scenario, TArtifact> {
+  private readonly opts;
+  private readonly tasks;
+  private readonly registered;
+  private readonly order;
+  private readonly coverage;
+  private readonly openSlots;
+  private readonly durableEventIds;
+  private lastStampMs;
+  private proposalReceiptCount;
+  private constructor();
+  /** Open the recorder and append the plan. An existing ledger for the same
+   *  run is re-read first, so a resumed run keeps one plan and one lineage. */
+  static open<TScenario extends Scenario, TArtifact>(opts: SearchRecorderOptions<TScenario>): Promise<SearchRecorder<TScenario, TArtifact>>;
+  /**
+   * Record one generation's candidate-generation call and the candidates it
+   * produced. A proposal larger than the planned population extends the plan
+   * with the extra slots; a proposal that fills fewer closes the rest.
+   */
+  recordGeneration(input: {
+    generation: number;
+    parentSurfaceHash: string;
+    candidates: ReadonlyArray<ProposedSearchCandidate>;
+  }): Promise<void>;
+  /** Append one task attempt per designed cell of each candidate campaign. */
+  recordResults(candidates: ReadonlyArray<MeasuredSearchCandidate<TArtifact>>): Promise<void>;
+  /**
+   * Close the search: unreached generations, the selection operation, one
+   * decision per candidate, then the terminal event.
+   *
+   * The terminal event is appended only when canonical replay accounts for the
+   * whole planned denominator. An interrupted or partly unscored search stays
+   * `in-progress` and its receipt reports the exact gap, instead of claiming a
+   * closed search.
+   */
+  finish(input: {
+    winnerSurfaceHash: string;
+    generationsRun: number;
+    runId: string;
+  }): Promise<SearchHistoryReceipt>;
+  /** Bounded receipt over the exact ledger bytes this run produced. */
+  receipt(runId: string): Promise<SearchHistoryReceipt>;
+  /** Read an existing ledger for this run so a resume continues it. */
+  private hydrate;
+  private plan;
+  private registeredSlot;
+  private remember;
+  private recordGenerationOperation;
+  private closeSlot;
+  /** Spend booked to candidate generation since the previous generation. */
+  private proposalAccounting;
+  private cellModel;
+  private proposalArtifact;
+  /** Write one canonical evidence document and return its content address. */
+  private writeArtifact;
+  private append;
+  /** Non-decreasing ISO stamps; the ledger refuses an event that moves back. */
+  private stamp;
+}
+/**
+ * Record an optimizer's own candidate graph into the same ledger.
+ *
+ * A complete optimization method searches inside its own process and reports
+ * one artifact when it finishes: the candidate population, with each
+ * candidate's parents and its score per selection scenario. This turns that
+ * artifact into the canonical event stream, so a first-party method returns
+ * the same `SearchHistoryReceipt` the in-process loop returns, and
+ * `compareOptimizationMethods({ searchHistoryPolicy: 'require-complete' })`
+ * accepts it.
+ *
+ * A candidate the optimizer left unscored on a planned scenario leaves the
+ * planned denominator open, so the receipt reports the gap instead of closing
+ * the search.
+ */
+declare function recordCandidatePopulationSearch<TScenario extends Scenario>(input: {
+  ledger: SearchLedger;
+  storage: CampaignStorage;
+  runDir: string;
+  identity: SearchRunIdentity;
+  population: GepaCandidatePopulationArtifact;
+  /** Scenarios the optimizer selected on. Must cover the population's ids. */
+  scenarios: ReadonlyArray<TScenario>;
+  /** Spend the optimizer booked to its own candidate generation. */
+  generationAccounting: SearchAttemptAccounting;
+  producerId: string;
+  runId: string;
+}): Promise<SearchHistoryReceipt>;
+//#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<ProposalFinding>;
+  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;
+  /** Search or observed-production findings forwarded to candidate generation. */
+  findings?: ReadonlyArray<ProposalFinding>;
+  /** 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<ReadonlyArray<ProposalFinding>>;
+  /**
+   * 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[];
+  /**
+   * Optional policy for which scored surface the next generation MUTATES.
+   * Absent, every generation mutates the global incumbent, so the recorded
+   * `parentSurfaceHash` lineage is a chain. Present, the selector receives the
+   * Pareto frontier so far, the measured incumbent, the generation history,
+   * and the generation index, and returns one frontier parent; the loop hands
+   * that parent to `propose()` as `currentSurface` + `parentOutcome` and
+   * records it as every candidate's `parentSurfaceHash`. Promotion is
+   * unchanged: a candidate still has to beat the incumbent. The loop refuses
+   * a parent it has not measured to completion. `crowdedFrontierParent` is
+   * the provided seeded policy.
+   */
+  selectParent?: ParentSelector;
+  /**
+   * Record this search into a durable `SearchLedger`. The loop emits the plan,
+   * each candidate-generation operation, each candidate registration with its
+   * measured parent, one task attempt per designed cell, one decision per
+   * candidate, and the terminal event, then returns a bounded
+   * `searchHistory` receipt over the exact ledger bytes.
+   *
+   * `identity` declares what the ledger requires and a campaign cannot infer:
+   * immutable revisions for the agent, proposer, and search implementations,
+   * and the model the agent runs when a cell reports none.
+   */
+  searchLedger?: SearchLedgerBinding;
+}
+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>;
+    }>;
+  }>;
+  /** Frozen snapshot of the exact starting surface measured by `baselineCampaign`. */
+  baselineSurface: MutableSurface;
+  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;
+  /** Bounded proof envelope over the canonical search ledger. Present only
+   *  when `searchLedger` was supplied. `complete` is false when the search was
+   *  interrupted or a candidate left a designed cell unscored. */
+  searchHistory?: SearchHistoryReceipt;
+  /** 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. The parent each generation mutates is the incumbent unless `selectParent` draws it from the frontier.
+ */
+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/transient-failure.d.ts
+interface TransientFailureOptions {
+  /**
+   * Treat full-duration timeouts ("timeout after 180000ms") as transient.
+   * Enable on saturated shared infrastructure where queue starvation eats
+   * the clock; leave off when the agent had the resources and simply failed.
+   * Default false.
+   */
+  readonly retryFullDurationTimeouts?: boolean;
+  /** Additional caller-specific transient patterns. */
+  readonly extraPatterns?: readonly RegExp[];
+  /**
+   * The instant a dated quota refusal is measured against. Defaults to `Date.now()`; inject it
+   * to replay a past classification, which is what a retry audit needs.
+   */
+  readonly now?: number;
+}
+/**
+ * The instant a provider says a spent quota works again, or null when the text states none.
+ *
+ * MEASURED (2026-09-01, discovery lab). The codex/ChatGPT backend answered
+ * `You've hit your usage limit. Visit https://chatgpt.com/codex/settings/usage to purchase more
+ * credits or try again at Sep 6th, 2026 8:29 PM.` — a refusal SIX DAYS out. 25 supervised runs met
+ * it. 21 of them retried it 12 times over about 31 minutes and settled with zero children, zero
+ * tokens and zero claims: about 11 hours of one subscription's capacity spent on a wall that had
+ * already told the caller when it would come down.
+ *
+ * The distinction this draws is not "quota" versus "not quota". It is "the provider named a
+ * release time" versus "it did not". A bare 429, or z.ai's `您的账户已达到速率限制`, recovers on
+ * its own in seconds and SHOULD be retried; those return null here and keep their existing
+ * treatment. Only a stated release is terminal, and only until that instant.
+ *
+ * A date with no zone is read in the host's zone, because a CLI renders it in the host's zone.
+ * An unparseable date returns null rather than a guess: a caller that stops dispatching must
+ * never do so on a misread string.
+ *
+ * @param message the provider's error text
+ * @returns the stated release time, or null when the text names none
+ */
+declare function quotaExhaustedUntil(message: string | null | undefined): Date | null;
+/**
+ * True when the error text describes an infrastructure hiccup that should be
+ * retried rather than scored. Empty/undefined input is not transient.
+ */
+declare function isTransientTransportFailure(message: string | null | undefined, opts?: TransientFailureOptions): boolean;
+/**
+ * Ready-made `cellRetry.retryable` predicate: true for a dispatch-stage
+ * failure whose error message `isTransientTransportFailure` classifies as an
+ * infrastructure hiccup. A judge-stage failure is never retried here — the
+ * dispatch already produced an artifact, so re-dispatching would score a
+ * different sample. A per-cell dispatch deadline ("dispatch exceeded <N>ms")
+ * is not transient by default; opt in via `extraPatterns` or
+ * `retryFullDurationTimeouts` when queue starvation eats the clock. A provider refusal that
+ * states its own release time is never retried while that time is in the future
+ * (`quotaExhaustedUntil`).
+ */
+declare function transientDispatchFailure(opts?: TransientFailureOptions): (failure: CampaignCellFailureReceipt['failure']) => boolean;
+//#endregion
+//#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>;
+  /**
+   * How to read a score out of the model's answer.
+   *
+   * `'sampled'` (default) reads the number the model emitted. Discrete grades
+   * tie often, and a tie carries no ranking signal.
+   *
+   * `'expectation'` asks the provider for the log probabilities of the score
+   * token and returns the expected value over the integer grades the model
+   * considered, so two answers that both sample `8` separate by how much mass
+   * sat on `7` and `9`. It requires `scale: 'ten'`: an integer grade is one
+   * token, and a `unit` float is not. `whenUnavailable` decides what happens
+   * when the provider returns no log probabilities, or the grade did not land
+   * in one token: `'fail'` throws, `'sampled'` reads the emitted number and
+   * records `scoringMethod: 'sampled'` on the score.
+   */
+  scoring?: {
+    method: 'sampled';
+  } | {
+    method: 'expectation';
+    whenUnavailable: 'fail' | 'sampled';
+  };
+  /** 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/external-optimizer-observations.d.ts
+interface ExternalOptimizerObservationSummary {
+  scope: 'callback-submitted-candidates';
+  path: string;
+  sha256: `sha256:${string}`;
+  submittedCandidates: number;
+  evaluations: number;
+  refusals: number;
+}
+interface ExternalOptimizerExecutionSummary {
+  scope: 'runtime-model-calls';
+  path: string;
+  sha256: `sha256:${string}`;
+  calls: number;
+  succeeded: number;
+  failed: number;
+}
+interface ExternalOptimizerSubmittedCandidate {
+  /** Exact text or named-component surface submitted to the evaluation callback. */
+  readonly candidate: ExternalTextCandidate;
+  /** Eval's canonical content identity for `candidate`. */
+  readonly candidateHash: string;
+  readonly candidateDigest: `sha256:${string}`;
+  readonly proposalSequence: number;
+  /** Exact observation artifact that proves this candidate was submitted. */
+  readonly provenance: {
+    readonly path: string;
+    readonly sha256: `sha256:${string}`;
+  };
+}
+interface ExternalOptimizerObservationArtifact {
+  readonly summary: ExternalOptimizerObservationSummary;
+  readonly observations: readonly ExternalOptimizerEvaluationObservation[];
+  /** Every distinct callback-submitted candidate in proposal order. */
+  readonly candidates: readonly ExternalOptimizerSubmittedCandidate[];
+}
+/**
+ * Read and verify the exact callback observation artifact addressed by method provenance.
+ *
+ * The reader checks the raw SHA-256, canonical JSONL bytes, sequence, candidate
+ * identities, and summary counts before it returns any candidate.
+ * This proves that the bytes match the supplied summary. The caller remains
+ * responsible for obtaining that summary from trusted provenance.
+ */
+declare function readExternalOptimizerObservationArtifact(input: {
+  summary: ExternalOptimizerObservationSummary;
+  storage?: CampaignStorage;
+}): ExternalOptimizerObservationArtifact;
+//#endregion
+//#region src/campaign/optimization-cost.d.ts
+/** Cost reported by a method or by final test scoring. */
+interface ComparisonCost {
+  /** Known subtotal. Consult `costProvenance` before treating this as total spend. */
+  totalCostUsd: number;
+  /** Exact origin of the total; uncaptured means `totalCostUsd` is only a known subtotal. */
+  costProvenance: CostProvenance;
+  accountingComplete: boolean;
+  incompleteReasons: string[];
+}
+/** Keep the cost fields a custom optimization method must report. */
+declare function costFromLedgerSummary(summary: CostLedgerSummary): ComparisonCost;
+/** Combine method costs without turning one unknown bill into a known total. */
+declare function combineComparisonCosts(entries: ReadonlyArray<{
+  label: string;
+  cost: ComparisonCost;
+}>): ComparisonCost;
+//#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'>;
+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;
+  /** Stable public identity of the execution-owner callback. */
+  optimizerCallRef?: string;
+  runId: string;
+  /** Content identity shared by compatible resumptions. */
+  compatibleRunId?: string;
+  resumed: boolean;
+  /** Whether the run seed reached every external engine configuration. */
+  seedApplied?: boolean;
+  /** Evaluations the local callback metered — the trusted count. */
+  evaluationCount: number;
+  /**
+   * Evaluation total the external optimizer reported from its own counters.
+   * A difference from `evaluationCount` means upstream skipped, cached, or
+   * double-counted work; inspect before trusting upstream-derived budgets.
+   */
+  upstreamReportedEvaluations?: number;
+  artifactDir: string;
+  tokenUsage?: OptimizationTokenUsage;
+  /** Candidates submitted to the callback, per-case scores, and refusals. */
+  observations?: ExternalOptimizerObservationSummary;
+  /** Exact accepted GEPA candidates, parent indices, and selection scores. */
+  gepaCandidatePopulation?: GepaCandidatePopulationSummary;
+  /** Opaque Runtime execution evidence for every invoked optimizer-model call. */
+  modelExecutions?: ExternalOptimizerExecutionSummary;
+  /** Anthropic-endpoint proxy traffic from agent CLI engines, when enabled. */
+  anthropicEndpoint?: ExternalOptimizerWireCounts;
+}
+/** 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;
+  /** Bounded proof envelope over the canonical SearchLedger for this optimization. */
+  searchHistory?: SearchHistoryReceipt;
+}
+/** 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;
+  };
+  /** Search spend reconciled with recorded method calls. 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 method reports reconciled against each method's recorded calls. */
+  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;
+  /** Coverage of every method's canonical search history. */
+  searchHistory: SearchHistoryCoverage;
+}
+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;
+  /**
+   * Missing history is reported by default. Publication-grade or autonomous
+   * callers set `require-complete`, which aborts before the first final-test call.
+   */
+  searchHistoryPolicy?: SearchHistoryPolicy;
+}
+/**
+ * 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>;
+/** 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;
+    /** The optimizer score is a finite protocol value; Eval remains the
+     * authority for whether the underlying cell actually produced a score. */
+    status?: 'scored' | 'failed';
+    error?: {
+      stage: 'dispatch' | 'judge' | 'unknown';
+      message: string;
+    };
+  };
+}
+declare function decodeExternalTextCandidate(candidate: ExternalTextCandidate): MutableSurface;
+//#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/optimizer-model.d.ts
+type OptimizerModelBudget = ExternalOptimizerModelBudget;
+/** One metered model path supplied by the package that owns execution. */
+interface OpenAICompatibleOptimizerModel {
+  model: string;
+  budget: OptimizerModelBudget;
+  /** Caller-owned execution path, such as Runtime's exact AgentProfile adapter. */
+  call: ExternalOptimizerModelCall;
+  /** Stable public identity included in resumable-run compatibility. */
+  callRef: string;
+  /**
+   * Served-model acceptance for every proxied call. Default `'exact'`, which
+   * rejects any substitution with a 502 to the child.
+   * `'allow-within-family'` accepts a different model of the same provider
+   * family; it keeps family-level claims valid and forfeits per-model claims.
+   */
+  servedModelPolicy?: ServedModelPolicy;
+  /**
+   * Also expose this metered model over the Anthropic Messages API
+   * (`POST /v1/messages`) on the loopback proxy. Required for GEPA agent
+   * engines that drive a `claude` CLI subprocess. Agent engines are chatty:
+   * size `budget.maxRequests` for tens of calls per engine run. Default: false.
+   */
+  anthropicEndpoint?: boolean;
+}
+//#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;
+  /** Optional billed-USD stop. Omit when the execution owner reports USD as unknown. */
+  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;
+  /** Candidate-evaluation callback byte limits. Omitted fields use finite defaults. */
+  evaluationCallbackLimits?: Partial<ExternalOptimizerCallbackLimits>;
+  /** 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;
+  /**
+   * Record GEPA's own candidate population into the canonical `SearchLedger`
+   * and return the bounded receipt on the method result, so a comparison run
+   * under `searchHistoryPolicy: 'require-complete'` accepts this method.
+   *
+   * `identity` declares the immutable revisions and the model snapshot the
+   * ledger requires and the bridge does not report. `path` defaults to
+   * `<runDir>/search-ledger.jsonl`.
+   */
+  searchLedger?: {
+    identity: SearchRunIdentity;
+    path?: string;
+  };
+}
+declare function gepaOptimizationMethod<TScenario extends Scenario, TArtifact>(config: GepaOptimizationMethodConfig<TScenario, TArtifact>): OptimizationMethod<TScenario, TArtifact>;
+//#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;
+  /** Candidate-evaluation callback byte limits. Omitted fields use finite defaults. */
+  evaluationCallbackLimits?: Partial<ExternalOptimizerCallbackLimits>;
+  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
+//#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;
+//#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. The exact small-sample test may require
+   *  more observations at the selected confidence. 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. The exact
+   *  small-sample test may require more observations at the selected
+   *  confidence. 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 lower bound of the DECIDING
+ * paired interval on the candidate-minus-baseline composite delta clears
+ * `deltaThreshold` — Tango's score interval on a pass/fail holdout, the mean
+ * bootstrap otherwise. See {@link decidePairedPromotion}.
+ */
+declare function heldOutGate<TArtifact, TScenario extends Scenario>(options: HeldOutGateOptions<TScenario>): Gate<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;
+  /** Proposer-supplied typed attribution, carried unchanged from
+   *  `GenerationCandidate.attribution`. Opaque here; the producer's schema tag
+   *  governs interpretation. */
+  attribution?: Readonly<Record<string, unknown>>;
+  /** 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;
+/** SHA-256 over the RFC 8785 canonical JSON of `value`. Throws
+ * `LedgerCanonicalizationError` for a value with no canonical form. */
+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/analyst-surface.d.ts
+interface TraceAnalystScenario extends Scenario {
+  kind: 'trace-analyst';
+  traceStore: TraceAnalysisStore;
+  labelState: AnalystBenchmarkLabelState;
+  expectedIssues: readonly AnalystIssueExpectation[];
+  labeledEvidence?: AnalystBenchmarkCase['labeledEvidence'];
+}
+interface TraceAnalystArtifact {
+  findings: readonly AnalystFinding[];
+  usage?: AnalystUsageReceipt;
+  run?: AnalystRunResult;
+}
+interface BuildTraceAnalystSurfaceDispatchOptions {
+  analyze(input: {
+    instructions: string;
+    traceStore: TraceAnalysisStore;
+    runId: string;
+    signal: AbortSignal;
+  }): Promise<TraceAnalystArtifact>;
+}
+declare function buildTraceAnalystSurfaceDispatch(options: BuildTraceAnalystSurfaceDispatchOptions): (surface: MutableSurface, scenario: TraceAnalystScenario, context: DispatchContext) => Promise<TraceAnalystArtifact>;
+declare function traceAnalystQualityJudge(): JudgeConfig<TraceAnalystArtifact, TraceAnalystScenario>;
+//#endregion
+//#region src/campaign/cross-surface-types.d.ts
+/** Whether one candidate attempt produced a usable executable outcome. */
+type CrossSurfaceAttemptCompleteness = 'complete' | 'missing' | 'invalid';
+/** One independently proposed change on one caller-defined surface. */
+interface CrossSurfaceComponent {
+  componentId: string;
+  surfaceId: string;
+  /** Explicitly controls whether this component may anchor the best-single arm. */
+  bestSingleEligible: boolean;
+}
+/** Immutable identity for a single candidate or a materialized composition. */
+interface CrossSurfaceCandidate {
+  candidateId: string;
+  componentIds: string[];
+  contentHash: string;
+  artifactBytes: number;
+}
+/** Per-component trace evidence captured during one task attempt. */
+interface CrossSurfaceComponentEvidence {
+  componentId: string;
+  /** null means the trace could not establish whether the component fired. */
+  fired: boolean | null;
+  /** null means the trace could not establish whether the component changed behavior. */
+  effectObserved: boolean | null;
+}
+/**
+ * Canonical per-task input row. Consumers may extend this interface with
+ * receipt, trace, retry, or failure details; the report preserves the original
+ * row object rather than projecting those details away.
+ */
+interface CrossSurfaceTaskRow {
+  taskId: string;
+  candidateId: string;
+  /** Repeated here so every persisted row remains self-describing. */
+  componentIds: string[];
+  completeness: CrossSurfaceAttemptCompleteness;
+  pass: boolean | null;
+  score: number | null;
+  /**
+   * Per-attempt deployment measurements. Every declared metric must have a
+   * known, non-negative value. Proposal, analysis, and selection spend belongs
+   * in the search ledger rather than being spread across task cells.
+   */
+  cost: Record<string, number | null>;
+  componentEvidence: CrossSurfaceComponentEvidence[];
+  /** Required for missing or invalid attempts; forbidden for complete attempts. */
+  rejectReason: string | null;
+}
+interface CrossSurfaceBootstrapPolicy {
+  seed: number;
+  resamples: number;
+  confidence: number;
+}
+/** Predeclared candidate eligibility and composition policy. */
+interface CrossSurfaceSelectionPolicy {
+  minimumFiringTasks: number;
+  minimumEffectTasks: number;
+  requireObservedFiring: boolean;
+  requireObservedEffect: boolean;
+  /** Only named metrics are constrained; all declared metrics are still reported. */
+  maximumMedianCostRatioToBaseline: Record<string, number>;
+  /** A smaller terminal bundle is reported but cannot become the selected arm. */
+  minimumBundleComponents: number;
+}
+interface AnalyzeCrossSurfaceInteractionsInput<TRow extends CrossSurfaceTaskRow = CrossSurfaceTaskRow> {
+  components: readonly CrossSurfaceComponent[];
+  candidates: readonly CrossSurfaceCandidate[];
+  rows: readonly TRow[];
+  baselineCandidateId: string;
+  /** Exact shared task axis and its canonical output order. */
+  taskOrder: readonly string[];
+  /** Canonical materialization order for component sets and the naive stack. */
+  componentOrder: readonly string[];
+  /** Final deterministic tie-break; lower index wins. */
+  candidateOrder: readonly string[];
+  /** Declares every cost key and the order used for cost tie-breaks. */
+  costMetricOrder: readonly string[];
+  bootstrap: CrossSurfaceBootstrapPolicy;
+  selection: CrossSurfaceSelectionPolicy;
+}
+interface CrossSurfaceDistribution {
+  n: number;
+  min: number;
+  median: number;
+  mean: number;
+  max: number;
+  total: number;
+}
+interface CrossSurfaceEvidenceBreakdown {
+  componentId: string;
+  observedTaskIds: string[];
+  notObservedTaskIds: string[];
+  unobservedTaskIds: string[];
+}
+interface CrossSurfaceCandidateEvidence {
+  byComponent: CrossSurfaceEvidenceBreakdown[];
+  allObservedTaskIds: string[];
+  someObservedTaskIds: string[];
+  noneObservedTaskIds: string[];
+  unobservedTaskIds: string[];
+}
+type CrossSurfaceIneligibilityReason = 'missing_attempt' | 'invalid_attempt' | 'baseline_outcome_missing' | 'benefit_not_greater_than_regression' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfaceEligibility {
+  eligible: boolean;
+  reasons: CrossSurfaceIneligibilityReason[];
+}
+interface CrossSurfaceCandidateOutcome {
+  resolvedTaskIds: string[];
+  failedTaskIds: string[];
+  missingTaskIds: string[];
+  invalidTaskIds: string[];
+  benefitTaskIds: string[];
+  regressionTaskIds: string[];
+  comparisonMissingTaskIds: string[];
+  netBenefit: number;
+}
+interface CrossSurfaceCandidateSummary {
+  candidate: CrossSurfaceCandidate;
+  outcome: CrossSurfaceCandidateOutcome;
+  score: CrossSurfaceDistribution | null;
+  costs: Record<string, CrossSurfaceDistribution>;
+  firing: CrossSurfaceCandidateEvidence;
+  effect: CrossSurfaceCandidateEvidence;
+  /** Reuses the package's paired McNemar/risk-difference/bootstrap statistics. */
+  comparisonToBaseline: PairedArmsComparison | null;
+  /** null only for the fixed baseline. */
+  eligibility: CrossSurfaceEligibility | null;
+}
+interface CrossSurfaceRelativeCost {
+  treatmentMedian: number;
+  comparatorMedian: number;
+  medianDelta: number;
+  /** null when the comparator median is zero but the treatment median is not. */
+  medianRatio: number | null;
+}
+interface CrossSurfaceCandidateComparison {
+  comparatorCandidateId: string;
+  treatmentCandidateId: string;
+  winsTaskIds: string[];
+  regressionTaskIds: string[];
+  missingTaskIds: string[];
+  paired: PairedArmsComparison;
+  relativeCost: Record<string, CrossSurfaceRelativeCost>;
+}
+interface CrossSurfacePairEvidence {
+  bothTaskIds: string[];
+  leftOnlyTaskIds: string[];
+  rightOnlyTaskIds: string[];
+  neitherTaskIds: string[];
+  unobservedTaskIds: string[];
+}
+interface CrossSurfaceInteractionTask {
+  taskId: string;
+  /** Composition minus the additive expectation from the baseline and singles. */
+  passInteraction: number | null;
+  scoreInteraction: number | null;
+}
+interface CrossSurfaceInteractionEffect {
+  perTask: CrossSurfaceInteractionTask[];
+  n: number;
+  nMissing: number;
+  meanPassInteraction: number | null;
+  meanScoreInteraction: number | null;
+  passBootstrap: PairedBootstrapResult | null;
+  scoreBootstrap: PairedBootstrapResult | null;
+}
+type CrossSurfacePairIncompatibilityReason = 'constituent_not_ready' | 'pair_incomplete' | 'baseline_regression' | 'interference' | 'no_incremental_resolution' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfacePairCompatibility {
+  compatible: boolean;
+  reasons: CrossSurfacePairIncompatibilityReason[];
+  betterSingleCandidateId: string;
+}
+interface CrossSurfacePairwiseEntry {
+  componentIds: [string, string];
+  singleCandidateIds: [string, string];
+  compositionCandidateId: string;
+  benefitTaskIds: string[];
+  regressionTaskIds: string[];
+  synergyTaskIds: string[];
+  interferenceTaskIds: string[];
+  incrementalVsConstituents: [CrossSurfaceCandidateComparison, CrossSurfaceCandidateComparison];
+  relativeCostToBaseline: Record<string, CrossSurfaceRelativeCost>;
+  firing: CrossSurfacePairEvidence;
+  effect: CrossSurfacePairEvidence;
+  interaction: CrossSurfaceInteractionEffect;
+  compatibility: CrossSurfacePairCompatibility;
+}
+interface CrossSurfaceRankedSingle {
+  rank: number;
+  candidateId: string;
+  componentId: string;
+}
+interface CrossSurfaceBestSingleSelection {
+  candidateId: string;
+  componentId: string;
+  ranking: CrossSurfaceRankedSingle[];
+}
+interface CrossSurfaceNaiveStackSelection {
+  /** Every individually eligible single, stacked in canonical component order. */
+  candidateId: string;
+  componentIds: string[];
+}
+type CrossSurfaceAdditionRejectionReason = 'pair_incompatible' | 'full_bundle_not_evaluated' | 'bundle_incomplete' | 'baseline_regression' | 'no_incremental_resolution' | 'incremental_regression' | 'firing_below_minimum' | 'firing_unobserved' | 'effect_below_minimum' | 'effect_unobserved' | 'cost_limit_exceeded';
+interface CrossSurfaceAdditionDecision {
+  additionCandidateId: string;
+  additionComponentId: string;
+  bundleCandidateId: string | null;
+  incrementalResolutionTaskIds: string[];
+  incrementalRegressionTaskIds: string[];
+  incrementalMedianCost: Record<string, number> | null;
+  eligible: boolean;
+  selected: boolean;
+  reasons: CrossSurfaceAdditionRejectionReason[];
+}
+interface CrossSurfaceCompositionStep {
+  fromCandidateId: string;
+  retainedComponentIds: string[];
+  considered: CrossSurfaceAdditionDecision[];
+  selectedCandidateId: string | null;
+}
+/** One deterministic growth path starting from a compatible two-surface seed. */
+interface CrossSurfaceInteractionPath {
+  seedCandidateId: string;
+  terminalCandidateId: string;
+  terminalComponentIds: string[];
+  qualified: boolean;
+  steps: CrossSurfaceCompositionStep[];
+}
+interface CrossSurfaceInteractionAwareSelection {
+  /** Compatible pair that seeded the selected deterministic growth path. */
+  seedCandidateId: string;
+  /** Candidate reached by the winning path, even if the minimum size is not met. */
+  terminalCandidateId: string;
+  terminalComponentIds: string[];
+  /** null when no path produced a qualifying multi-component bundle. */
+  selectedCandidateId: string | null;
+  qualified: boolean;
+  /** Every compatible pair seed is retained so seed choice cannot hide an interaction. */
+  evaluatedPaths: CrossSurfaceInteractionPath[];
+  /** Convenience alias for the winning path's steps. */
+  steps: CrossSurfaceCompositionStep[];
+}
+interface CrossSurfaceSelections {
+  bestSingle: CrossSurfaceBestSingleSelection | null;
+  naiveStack: CrossSurfaceNaiveStackSelection | null;
+  interactionAware: CrossSurfaceInteractionAwareSelection | null;
+}
+interface CrossSurfaceInteractionReport<TRow extends CrossSurfaceTaskRow = CrossSurfaceTaskRow> {
+  taskIds: string[];
+  componentIds: string[];
+  candidateIds: string[];
+  costMetrics: string[];
+  /** Canonical candidate × task order; no input row is dropped. */
+  rows: TRow[];
+  missingAttempts: TRow[];
+  invalidAttempts: TRow[];
+  candidates: CrossSurfaceCandidateSummary[];
+  pairwise: CrossSurfacePairwiseEntry[];
+  selections: CrossSurfaceSelections;
+}
+//#endregion
+//#region src/campaign/cross-surface-interaction.d.ts
+/**
+ * Build the complete cross-surface evidence matrix and derive all three frozen
+ * candidates. The task/candidate/component orders are part of the input so
+ * neither insertion order nor an after-the-fact tie-break can change a result.
+ */
+declare function analyzeCrossSurfaceInteractions<TRow extends CrossSurfaceTaskRow>(input: AnalyzeCrossSurfaceInteractionsInput<TRow>): CrossSurfaceInteractionReport<TRow>;
+//#endregion
+//#region src/campaign/fixtures.d.ts
+type EvalFixtureValidationMode = 'vitest' | 'none';
+interface EvalFixtureFile {
+  path: string;
+  sha256: string;
+  bytes: number;
+}
+interface EvalFixture {
+  name: string;
+  path: string;
+  promptPath: string;
+  evalPath?: string;
+  packageJsonPath?: string;
+  prompt: string;
+  files: EvalFixtureFile[];
+  fingerprint: string;
+}
+interface EvalFixtureScenario extends Scenario {
+  kind: 'eval-fixture';
+  fixtureName: string;
+  fixturePath: string;
+  promptPath: string;
+  evalPath?: string;
+  packageJsonPath?: string;
+  prompt: string;
+  fingerprint: string;
+}
+interface EvalFixtureLoadOptions {
+  /** `vitest` requires EVAL.ts/EVAL.tsx and package.json type=module. `none` only requires PROMPT.md. */
+  validation?: EvalFixtureValidationMode;
+  /** Extra caller-owned knobs that affect fixture behavior, folded into the fingerprint. */
+  fingerprintConfig?: unknown;
+}
+interface LoadEvalFixtureScenariosOptions extends EvalFixtureLoadOptions {
+  names?: string[];
+}
+interface PlanEvalFixtureRunOptions<TArtifact = unknown> extends Pick<PlanCampaignRunOptions<EvalFixtureScenario, TArtifact>, 'dispatchRef' | 'judges' | 'seed' | 'reps' | 'resumable' | 'runDir'> {
+  evalsDir: string;
+  validation?: EvalFixtureValidationMode;
+  fingerprintConfig?: unknown;
+  names?: string[];
+  storage?: CampaignStorage;
+}
+type EvalFixtureRunPlan = CampaignRunPlan & {
+  fixtures: Array<Pick<EvalFixtureScenario, 'fixtureName' | 'fixturePath' | 'fingerprint'>>;
+};
+/** Walk `evalsDir` and return the relative name of every fixture directory (one containing an exact-case `PROMPT.md`). */
+declare function discoverEvalFixtures(evalsDir: string): string[];
+/**
+ * Load ONE fixture by name: reads `PROMPT.md` (plus `EVAL.ts`/`EVAL.tsx` and `package.json` under
+ * `vitest` validation) and content-fingerprints the full file set for cache identity.
+ */
+declare function loadEvalFixture(evalsDir: string, name: string, options?: EvalFixtureLoadOptions): EvalFixture;
+/** Load fixtures (all discovered, or just `names`) as campaign `Scenario`s tagged `eval-fixture`. */
+declare function loadEvalFixtureScenarios(evalsDir: string, options?: LoadEvalFixtureScenariosOptions): EvalFixtureScenario[];
+/**
+ * Dry-run planner for a fixture campaign: loads the scenarios, delegates to `planCampaignRun`,
+ * and returns the plan plus each fixture's name/path/fingerprint.
+ */
+declare function planEvalFixtureRun<TArtifact = unknown>(options: PlanEvalFixtureRunOptions<TArtifact>): EvalFixtureRunPlan;
+//#endregion
+//#region src/campaign/gates/neutralization-gate.d.ts
+interface NeutralizationGateOptions<TScenario extends Scenario = Scenario> {
+  scenarios: TScenario[];
+  /** Reject when the neutralized (content-blanked, footprint-matched) variant
+   *  reproduces at least this fraction of the candidate's held-out lift. Default
+   *  0.5 — if blanking the content keeps half the lift, the content is decorative.
+   *  Equality rejects: a neutralized lift == threshold·candidateLift is decorative. */
+  maxDecorativeFraction?: number;
+}
+/**
+ * Composable placebo gate: ships only when the candidate's held-out lift is NOT
+ * mostly reproduced by a footprint-matched neutralized variant.
+ */
+declare function neutralizationGate<TArtifact, TScenario extends Scenario>(options: NeutralizationGateOptions<TScenario>): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/grounded-reflection.d.ts
+/**
+ * Evidence grounding for reflective optimizers (GEPA-style revise loops).
+ *
+ * Two failure modes recur when an LLM revises an artifact from raw rollout
+ * traces (first measured in agent-lab R358, where naive reflection REGRESSED
+ * the score 0.375 -> 0.125 before these helpers fixed it):
+ *
+ * 1. The environment often hides WHY a rollout failed - a tool call can
+ *    succeed while an invisible downstream check fails - so the reviser
+ *    cannot see the cause in the transcript. The only reliable signal is the
+ *    field-level difference between what passing and failing rollouts did.
+ *    `rolloutArgumentDiff` computes that difference deterministically so the
+ *    reviser is handed the diff instead of being trusted to derive it.
+ *
+ * 2. Revisers invent plausible-but-wrong literal values ("use 'new'",
+ *    "use 'sent'") that no passing rollout ever used, turning every rollout
+ *    into a failure. `classifyUngroundedLiterals` mechanically detects them,
+ *    separating HARMFUL literals (ones failing rollouts actually used -
+ *    proven damage) from benign illustrations (e.g. a name example like
+ *    'Doe'), so callers can hard-reject the former and merely log the latter.
+ *    Rejecting every ungrounded quoted word is too blunt: it killed a run
+ *    over a surname illustration before the severity split existed.
+ *
+ * Pure data in, data out: no LLM calls, no filesystem, no domain knowledge.
+ */
+/** One tool/action call observed in a rollout: a name plus its arguments. */
+interface RolloutCall {
+  readonly name: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+/** A scored rollout: its calls plus the scalar outcome used to split pass/fail. */
+interface ScoredRollout {
+  /** Caller-meaningful identifier (task id, cell id) used only for reporting. */
+  readonly id: string;
+  /** Scalar outcome in [0, 1]; `passThreshold` splits passing from failing. */
+  readonly score: number;
+  readonly calls: readonly RolloutCall[];
+}
+interface RolloutArgumentDiffOptions {
+  /** Rollouts with `score >= passThreshold` count as passing. Default 1. */
+  readonly passThreshold?: number;
+  /** Max distinct values listed per field per side in the rendered text. Default 4. */
+  readonly maxValuesPerField?: number;
+}
+interface RolloutArgumentDiff {
+  /** Human/LLM-readable per-field diff, one line per field. */
+  readonly text: string;
+  /** Lowercased stringified argument values seen in passing rollouts. */
+  readonly passingValues: ReadonlySet<string>;
+  /** Lowercased stringified argument values seen in failing rollouts. */
+  readonly failingValues: ReadonlySet<string>;
+}
+/**
+ * Deterministic per-field diff of call arguments between passing and failing
+ * rollouts. A field set by failing rollouts but left unset by passing ones is
+ * the classic poison-input signature; a field whose values differ across the
+ * split points at the correct value. Feed `text` to the reviser verbatim.
+ */
+declare function rolloutArgumentDiff(rollouts: readonly ScoredRollout[], opts?: RolloutArgumentDiffOptions): RolloutArgumentDiff;
+interface UngroundedLiteralReport {
+  /** Quoted single-word literals in the text that no passing rollout used. */
+  readonly ungrounded: readonly string[];
+  /** The subset failing rollouts actually used - prescribing these is proven harmful. */
+  readonly harmful: readonly string[];
+}
+/**
+ * Scan revised artifact text for single-quoted single-word literals (the
+ * "use exactly 'new'" pattern) that appear in no passing rollout's argument
+ * values. Multi-word quotes pass (they are prose, not prescriptions).
+ * Callers should reject on `harmful` (with a bounded retry) and at most log
+ * `ungrounded` - see the module header for why the severities differ.
+ */
+declare function classifyUngroundedLiterals(text: string, diff: Pick<RolloutArgumentDiff, 'passingValues' | 'failingValues'>): UngroundedLiteralReport;
+//#endregion
+//#region src/campaign/labeled-store/fs-adapter.d.ts
+interface FsLabeledScenarioStoreOptions {
+  /** Root directory for JSONL files. Created if missing. */
+  root: string;
+  /** Per-source rate limit. When set, writes exceeding the cap are rejected
+   *  with a typed error. Default: no limit. */
+  maxWritesPerMinutePerBucket?: number;
+  /** Test seam — override `Date.now()` for deterministic tests. */
+  now?: () => number;
+}
+/** Typed rejection from a labeled-scenario store (bad provenance, rate limit, invalid sample args) — carries a stable string `code`. */
+declare class LabeledScenarioStoreError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/**
+ * Filesystem `LabeledScenarioStore`: appends one JSONL file per source with provenance and
+ * rate-limit guards. For tests, local dev, and small workloads — high-throughput lands in Turso.
+ */
+declare class FsLabeledScenarioStore implements LabeledScenarioStore {
+  private readonly options;
+  private readonly now;
+  private readonly rateLimits;
+  constructor(options: FsLabeledScenarioStoreOptions);
+  observe(write: LabeledScenarioWrite): Promise<void>;
+  sample(args: LabeledScenarioSampleArgs): Promise<LabeledScenarioRecord[]>;
+  size(): Promise<{
+    train: number;
+    test: number;
+    bySource: Record<string, number>;
+    byTrust: Record<LabelTrust, number>;
+  }>;
+  private assertProvenance;
+  private assertRateLimit;
+  private toRecord;
+  private pathForSource;
+}
+//#endregion
+//#region src/campaign/neutralize.d.ts
+/**
+ * @module
+ * Footprint-matched neutralization — the placebo control for content-vs-footprint
+ * attribution in a promotion gate.
+ *
+ * A promoted surface can raise a held-out score two different ways:
+ *  1. its CONTENT is informative (the thing we want to promote), or
+ *  2. it merely added prompt/mount FOOTPRINT — more bytes, more lines, a longer
+ *     more authoritative-looking prompt — that the model spends attention on
+ *     regardless of what the bytes say.
+ *
+ * A held-out gate proves the candidate beat baseline; it cannot separate (1) from
+ * (2). `neutralizeText` produces a variant that keeps the input's layout and
+ * length while carrying ZERO information, so scoring it isolates the footprint
+ * contribution (2). Feed the neutralized variant's scores to `neutralizationGate`:
+ * any lift it still holds over baseline is decorative, and a candidate whose lift
+ * survives neutralization is rejected however large its raw lift.
+ */
+/**
+ * Blank every non-whitespace character to a 1-byte filler while preserving all
+ * whitespace. Line count, indentation, and word/line lengths are unchanged — so
+ * the neutralized variant has the same layout and (for ASCII) the same byte
+ * footprint as the input, but no readable content. Whitespace is preserved
+ * deliberately: collapsing it would change the token structure and stop the
+ * variant from being a true footprint match.
+ */
+declare function neutralizeText(content: string): string;
+//#endregion
+//#region src/artifact-validator.d.ts
+/**
+ * Artifact validators.
+ *
+ * Generic "score a produced artifact" primitive. Tax uses it for PDF form
+ * correctness, research for sourced briefs, browser for task assertions, coding
+ * for social posts. One interface, many validators.
+ *
+ * A validator receives an `Artifact` (file on disk, JSON blob, text, binary)
+ * plus a `ValidationContext` (scenario id, the turns that produced it) and
+ * returns a `ValidationResult` with pass/fail + 0..1 score + structured
+ * issues.
+ */
+interface Artifact {
+  /** Logical kind — validators type-guard on this */
+  kind: 'file' | 'json' | 'text' | 'binary' | string;
+  /** Filesystem-style path, optional */
+  path?: string;
+  /** String content for text/json/file kinds */
+  content?: string;
+  /** Binary content (if kind === 'binary') */
+  bytes?: Uint8Array;
+  /** Caller-supplied metadata (mimeType, sha256, size, etc.) */
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+//#region src/completion-verifier.d.ts
+/** What kind of produced state can satisfy a requirement structurally. */
+type SatisfiedBy = 'artifact' | 'proposal' | 'tool-call' | 'any';
+interface CompletionRequirement {
+  /** Stable id from the task gold (e.g. a persona's `expected_requirements[].req_id`). */
+  reqId: string;
+  /** Human-readable description of the required deliverable. */
+  title: string;
+  /** Optional kind/category hint, matched against a produced item's kind. */
+  category?: string;
+  /** What produced state satisfies this requirement. Defaults to 'any'. */
+  satisfiedBy?: SatisfiedBy;
+}
+interface TaskGold {
+  taskId: string;
+  requirements: CompletionRequirement[];
+}
+interface ProducedProposal {
+  id: string;
+  title: string;
+  status: 'pending' | 'approved' | 'rejected';
+  /** Optional persisted body — when present, enables a correctness check. */
+  content?: string;
+}
+/** Everything observable about what a run actually produced. */
+interface ProducedState {
+  /** Persisted vault artifacts. Reuses the shared `Artifact` shape. */
+  artifacts: Artifact[];
+  /** Proposals / filings the agent created. */
+  proposals: ProducedProposal[];
+  /** Names of tools the agent invoked. */
+  toolCalls: string[];
+}
+interface RequirementCheck {
+  reqId: string;
+  title: string;
+  /** A produced item of the right kind matched the requirement, non-empty. */
+  structurallyPresent: boolean;
+  /**
+   * Whether the matched item actually fulfils the requirement. `null` when
+   * not structurally present, when the matched item carries no content
+   * to assess, or when the correctness check itself failed (`unmeasured`).
+   */
+  correct: boolean | null;
+  /** structurallyPresent && !unmeasured && correct !== false. */
+  satisfied: boolean;
+  /**
+   * Set when the correctness check itself errored (LLM call failure or an
+   * unparseable response after retry). The requirement's fulfilment is
+   * UNKNOWN — `correct` stays null, `satisfied` is false, and
+   * `completionVerdict` excludes the row from `completionRate`'s
+   * denominator. Never folded into a zero: a synthetic zero is
+   * indistinguishable from a real failure (see `JudgeParseError`).
+   */
+  unmeasured?: true;
+  /** Why the correctness check could not be measured (present iff `unmeasured`). */
+  unmeasuredReason?: string;
+  /** Human-readable evidence for the verdict. */
+  evidence: string[];
+}
+/** Extends the substrate verdict spine: `valid` = `fullyComplete` and
+ *  `score` = `completionRate` — derived in `completionVerdict()`, the one
+ *  place those equalities hold by construction. */
+interface CompletionVerdict extends DefaultVerdict {
+  taskId: string;
+  requirements: RequirementCheck[];
+  /** satisfied / MEASURABLE requirements (unmeasured rows leave the denominator). */
+  completionRate: number;
+  /** Every measurable requirement satisfied (false when anything is unmeasured). */
+  fullyComplete: boolean;
+  /** Requirements whose correctness check errored — reported, never scored as zero. */
+  unmeasuredCount: number;
+}
+/**
+ * Construct a `CompletionVerdict` from the per-requirement checks, deriving
+ * `completionRate` / `fullyComplete` and the spine fields (`valid` =
+ * `fullyComplete`, `score` = `completionRate`) in one place. Throws on zero
+ * requirements — a verdict over nothing is a misconfiguration, mirroring
+ * `verifyCompletion`'s gold-spec guard.
+ */
+declare function completionVerdict(input: {
+  taskId: string;
+  requirements: RequirementCheck[];
+  /** What certified the correctness stage, when anything did. Omitted =
+   *  an uncertified verdict — the honest default for a bare checker. */
+  certification?: VerdictCertification;
+}): CompletionVerdict;
+/**
+ * What a correctness checker declares about itself so the completion
+ * verdict can carry a certification: which strategy member it discharges,
+ * its exact identity, and the steps its answers rest on unverified.
+ */
+interface CorrectnessCheckerAttestation {
+  strategy: VerificationStrategySource;
+  checker: CheckerIdentity;
+  assumptions: string[];
+}
+/**
+ * Decides whether a produced item's content actually fulfils a requirement.
+ * Injected so the structural verifier stays pure and unit-testable; the
+ * production implementation is `createLlmCorrectnessChecker`.
+ *
+ * `attestation` is optional metadata on the function value: a checker that
+ * carries one yields certified completion verdicts; a bare function yields
+ * the same verdict uncertified. A plain arrow function remains a valid
+ * checker.
+ */
+interface CorrectnessChecker {
+  (requirement: CompletionRequirement, content: string): Promise<{
+    correct: boolean;
+    reason: string;
+  }>;
+  attestation?: CorrectnessCheckerAttestation;
+}
+/**
+ * Verify whether a run completed the task. `checkCorrectness` is injected —
+ * `createLlmCorrectnessChecker` for production, a deterministic stub in tests.
+ *
+ * Throws on a gold spec with no requirements: an eval task that requires
+ * nothing is a misconfiguration, not a vacuously-complete task.
+ */
+declare function verifyCompletion(gold: TaskGold, state: ProducedState, checkCorrectness: CorrectnessChecker): Promise<CompletionVerdict>;
+interface LlmCorrectnessCheckerOpts {
+  model?: string;
+  /** Optional ledger for direct use. */
+  costLedger?: CostLedgerHandle;
+  costPhase?: string;
+  costTags?: Record<string, string>;
+  signal?: AbortSignal;
+  /** Max chars of artifact content sent to the checker. */
+  maxContentChars?: number;
+  /**
+   * Checker LLM calls per requirement before giving up (parse failures and
+   * call errors both consume attempts). The failure then surfaces as an
+   * `unmeasured` requirement, never a zero.
+   */
+  maxAttempts?: number;
+  /**
+   * Forensic capture of every checker request/response/error — without it a
+   * checker failure is unauditable (the agent-turn raws never contain the
+   * checker's own calls). Same sink contract as `LlmClient`.
+   */
+  rawSink?: RawProviderSink;
+}
+/**
+ * Production `CorrectnessChecker` — one LLM call per matched artifact,
+ * deterministic (temperature 0), structured JSON out. Judges fulfilment
+ * only: a plan, a gesture, or a description of what should be done does not
+ * fulfil a requirement — the artifact must BE the deliverable.
+ */
+declare function createLlmCorrectnessChecker(chat: ChatClient, opts?: LlmCorrectnessCheckerOpts): CorrectnessChecker;
+//#endregion
+//#region src/produced-state.d.ts
+/** A tool the agent invoked. */
+interface ToolCallEventLike {
+  type: 'tool_call';
+  toolName: string;
+}
+/**
+ * An artifact the agent produced. `content` is the enriched field — the
+ * runtime's base `artifact` event carries only metadata; the completion
+ * oracle needs the body to verify the deliverable, so the runtime emits it.
+ */
+interface ArtifactEventLike {
+  type: 'artifact';
+  artifactId: string;
+  name?: string;
+  mimeType?: string;
+  uri?: string;
+  content?: string;
+}
+/** A proposal / filing the agent created. */
+interface ProposalEventLike {
+  type: 'proposal_created';
+  proposalId: string;
+  title: string;
+  status?: 'pending' | 'approved' | 'rejected';
+  content?: string;
+}
+/**
+ * The subset of runtime stream events `extractProducedState` consumes.
+ * agent-runtime's full `RuntimeStreamEvent` union satisfies this structurally;
+ * the `{ type: string }` catch-all keeps the input permissive so callers can
+ * pass the whole unfiltered telemetry stream — unrecognized events are skipped.
+ */
+type RuntimeEventLike = ToolCallEventLike | ArtifactEventLike | ProposalEventLike | {
+  type: string;
+};
+/**
+ * Normalize a run's runtime event stream into `ProducedState`.
+ *
+ * Pure and total — unrecognized event types are skipped. `toolCalls` is
+ * deduplicated by name in first-seen order (completion cares about a tool's
+ * presence, not its call count). An artifact with neither a name nor a uri
+ * still yields an entry keyed by its `artifactId` so it is never silently
+ * dropped; an artifact with no `content` yields empty content, which the
+ * completion oracle's structural check then rejects on its own.
+ */
+declare function extractProducedState(events: readonly RuntimeEventLike[]): ProducedState;
+//#endregion
+//#region src/integrity/backend-integrity.d.ts
+interface BackendIntegrityReport {
+  /** Total records inspected. */
+  totalRecords: number;
+  /** Records with input=0 AND output=0 (a stub fingerprint). */
+  stubRecords: number;
+  /** Records with nonzero token usage (real LLM activity). */
+  realRecords: number;
+  /** Records where output>0 but costUsd=0 (real LLM, broken cost ledger). */
+  uncostedRecords: number;
+  /** Sum of input tokens across all records. */
+  totalInputTokens: number;
+  /** Sum of output tokens across all records. */
+  totalOutputTokens: number;
+  /** Sum of costUsd across all records. */
+  totalCostUsd: number;
+  /** Worst-case integrity verdict. */
+  verdict: 'real' | 'mixed' | 'stub';
+  /** Human-readable diagnosis suitable for terminal output. */
+  diagnosis: string;
+}
+/**
+ * Error thrown when an integrity assertion fails. Caller can pattern-match
+ * by `code === 'AGENT_EVAL_BACKEND_STUB'` to differentiate from other
+ * errors.
+ */
+declare class BackendIntegrityError extends AgentEvalError {
+  readonly report: BackendIntegrityReport;
+  constructor(message: string, report: BackendIntegrityReport);
+}
+/**
+ * Inspect a batch of RunRecords and return an integrity report. Pure
+ * function — no I/O, no logging. The caller decides what to do with the
+ * verdict (print warning, throw, gate CI, etc.).
+ */
+declare function summarizeBackendIntegrity(records: ReadonlyArray<RunRecord>): BackendIntegrityReport;
+/**
+ * Throw BackendIntegrityError if the verdict is 'stub' — i.e. every record
+ * shows zero LLM activity. Non-strict callers can pass `{ allowMixed: false }`
+ * to also reject mixed verdicts (recommended for CI gates).
+ *
+ * Real backends pass through silently.
+ */
+declare function assertRealBackend(records: ReadonlyArray<RunRecord>, opts?: {
+  allowMixed?: boolean;
+}): BackendIntegrityReport;
+//#endregion
+//#region src/campaign/presets/run-profile-matrix.d.ts
+/** Thrown when the matrix is misconfigured (no profiles, missing resolved model evidence,
+ *  etc.). Distinct from `BackendIntegrityError`,
+ *  which signals a stub backend at run time. */
+declare class ProfileMatrixError extends AgentEvalError {
+  constructor(message: string);
+}
+/** Dispatch for one cell: render `profile` against `scenario`, returning the
+ *  artifact the judges score. Run LLM work through `ctx.cost.runPaidCall` —
+ *  the integrity check depends on its receipt. */
+type ProfileDispatchFn<TScenario extends Scenario, TArtifact> = (profile: AgentProfile$1, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+interface RunProfileMatrixOptions<TScenario extends Scenario, TArtifact> {
+  /** Axis 3 — the agent-under-test configurations. Each is one column. */
+  profiles: AgentProfile$1[];
+  /** Axis 1 — the persona/scenario corpus, run against every profile. */
+  scenarios: TScenario[];
+  /** Renders one (profile, scenario) cell. */
+  dispatch: ProfileDispatchFn<TScenario, TArtifact>;
+  /** The scoring axis. */
+  judges?: JudgeConfig<TArtifact, TScenario>[];
+  /** Where each profile's campaign writes artifacts/traces. One subdir per
+   *  profile. */
+  runDir: string;
+  /** Git SHA the harness ran from — stamped onto every RunRecord (mandatory
+   *  for paper-grade records). */
+  commitSha: string;
+  /** Additional stable identity for dispatch behavior that can change without
+   *  changing `commitSha`, such as a caller-owned executable or remote config. */
+  dispatchRef?: string;
+  /** Logical experiment id shared across the whole matrix so the promotion
+   *  gate can pair profiles on matched scenarios. Default: a hash of the
+   *  profile + scenario ids. */
+  experimentId?: string;
+  /** Which split these runs belong to. Default `'search'`. */
+  splitTag?: RunSplitTag;
+  /** Replicates per (profile, scenario) cell for CI bands. Default 1. */
+  reps?: number;
+  /** Campaign seed (per profile). Default 42. */
+  seed?: number;
+  /**
+   * Backend-integrity posture, enforced AFTER the matrix completes:
+   *   - `'assert'` (default) — throw `BackendIntegrityError` if the run was a
+   *     stub (and, with `allowMixed:false`, if it was mixed).
+   *   - `'warn'` — log the verdict but never throw.
+   *   - `'off'` — skip the guard entirely (only for offline/replay analysis).
+   */
+  integrity?: 'assert' | 'warn' | 'off';
+  /** Forwarded to `assertRealBackend`. Default true (tolerate partial 429
+   *  cascades); set false for strict CI gates. */
+  allowMixed?: boolean;
+  /** Max concurrent cells WITHIN each profile's campaign. Default 2. */
+  maxConcurrency?: number;
+  /** Max profile campaigns in flight. Default 1. Each profile keeps its own
+   *  run directory and cost ceiling; raise this when those resources are independent. */
+  maxProfileConcurrency?: number;
+  /** Cumulative USD cap per profile campaign. */
+  costCeiling?: number;
+  /** Capture flywheel — forwarded to each campaign. */
+  labeledStore?: LabeledScenarioStore | 'off';
+  captureSource?: LabeledScenarioSource;
+  /** Storage backend. Default `fsCampaignStorage`. Pass
+   *  `inMemoryCampaignStorage()` for edge/CF-Worker/test runs. */
+  storage?: CampaignStorage;
+  /** Test seam — override the wall clock. */
+  now?: () => Date;
+  /** Optional persona key per scenario — drives the `byPersona` pivot. When
+   *  unset, `byPersona` is omitted. */
+  personaOf?: (scenario: TScenario) => string;
+  /** Validate every produced RunRecord with `validateRunRecord` (fail-loud).
+   *  Default true — catches bad model snapshots and non-finite judge dims at
+   *  the boundary instead of letting them poison downstream analysis. */
+  validate?: boolean;
+  /** Corpus-by-default: derive the trajectory text (`prompt` + `completion`)
+   *  for each cell from its artifact + scenario. When set, every produced
+   *  record carries `prompt`/`completion` (a `CorpusRecord`) so the run's
+   *  graded trajectories can be appended to the durable RL corpus with no
+   *  side-channel — `appendToCorpus(result.records, path)`. Fail-soft: a
+   *  throwing or undefined-returning extractor just omits the text. */
+  corpusText?: (artifact: TArtifact, scenario: TScenario) => {
+    prompt: string;
+    completion: string;
+  } | undefined;
+  /**
+   * Optional explicit row selection. The matrix identity remains based on the
+   * complete profiles × scenarios × reps design; this invocation executes only
+   * rows accepted by the predicate.
+   */
+  rowFilter?: (input: {
+    profile: AgentProfile$1;
+    scenario: TScenario;
+    rep: number;
+  }) => boolean;
+  /** Stable matrix identity supplied by a persisted profile-matrix plan. */
+  matrixId?: string;
+  /** Reuse cached failed cells. Normal matrix runs retry them by default. */
+  reuseFailedCells?: boolean;
+}
+interface ProfileSummary {
+  profileId: string;
+  profileHash: string;
+  model: string;
+  /** RunRecords produced for this profile (= scenarios × reps). */
+  records: number;
+  /** Mean across scored records, or null when the profile has no task labels. */
+  meanComposite: number | null;
+  /** Total cost, or null when any call's cost was not captured. */
+  totalCostUsd: number | null;
+  costProvenance: CostProvenance;
+  /** Per-profile integrity verdict — surfaces a single profile that ran stub
+   *  even when the matrix as a whole looks real. */
+  integrity: BackendIntegrityReport;
+}
+interface ScenarioRollup {
+  meanComposite: number;
+  n: number;
+}
+interface RunProfileMatrixResult<TArtifact, TScenario extends Scenario> {
+  matrixId: string;
+  experimentId: string;
+  /** One RunRecord per (profile, scenario, rep) cell — the integrity-checked,
+   *  paper-grade output. Feed straight into `analyzeRuns`, `HeldOutGate`,
+   *  scorecards, the hosted wire format. */
+  records: RunRecord[];
+  byProfile: Record<string, ProfileSummary>;
+  byScenario: Record<string, ScenarioRollup>;
+  /** Present only when `personaOf` was supplied. */
+  byPersona?: Record<string, ScenarioRollup>;
+  /** Whole-matrix integrity report (the one `integrity:'assert'` enforces). */
+  integrity: BackendIntegrityReport;
+  /** The raw per-profile campaign results, keyed by profile id. */
+  campaigns: Record<string, CampaignResult<TArtifact, TScenario>>;
+}
+/**
+ * Profile × scenario matrix runner: fan N agent profiles across M scenarios, project each cell to a validated `RunRecord` with real token usage, and enforce the backend-integrity guard before returning.
+ */
+declare function runProfileMatrix<TScenario extends Scenario, TArtifact>(opts: RunProfileMatrixOptions<TScenario, TArtifact>): Promise<RunProfileMatrixResult<TArtifact, TScenario>>;
+//#endregion
+//#region src/campaign/presets/playback.d.ts
+/** One step of a user story — what the user does. The driver interprets
+ *  `payload` (a Playwright selector + action, or a sandbox chat turn). */
+interface PlaybackStep {
+  /** Human-readable action, captured verbatim in the UX narrative. */
+  action: string;
+  /** Driver-specific payload (e.g. `{ selector, fill }` or `{ turn }`). */
+  payload?: Record<string, unknown>;
+}
+/**
+ * A user story = a runnable product journey plus the requirements that define
+ * "this story works". Each requirement is one Jira ticket line. Extends
+ * `Scenario` so a catalog drops straight into `runProfileMatrix({ scenarios })`.
+ */
+interface UserStory extends Scenario {
+  /** Human-readable story title (the ticket headline). */
+  title: string;
+  /** Ordered steps the driver executes. */
+  steps: PlaybackStep[];
+  /** What must hold in the produced state for the story to pass. */
+  requirements: CompletionRequirement[];
+}
+/** Dispatch context plus the profile under test (which cheap model, etc.). */
+interface PlaybackContext extends DispatchContext {
+  profile: AgentProfile;
+}
+/**
+ * Drives the real product through a story and returns the runtime event stream
+ * `extractProducedState` consumes. Implemented by CONSUMERS —
+ * `SandboxPlaybackDriver` (real API / sandbox workspace) and
+ * `PlaywrightPlaybackDriver` (real UI) — because they depend on runtime /
+ * browser infra the substrate must not import. The driver MUST report LLM
+ * usage through `ctx.cost.runPaidCall` so the backend-integrity check sees real
+ * tokens (a run that never reports tokens reads as a stub).
+ */
+interface PlaybackDriver<TStory extends UserStory = UserStory> {
+  run(story: TStory, ctx: PlaybackContext): Promise<readonly RuntimeEventLike[]>;
+}
+/**
+ * Adapt a `PlaybackDriver` into a `runProfileMatrix` dispatch. The artifact the
+ * matrix scores is the `ProducedState` extracted from the driver's event
+ * stream — grade it with `scoreUserStory` (or a judge wrapping it).
+ */
+declare function makePlaybackDispatch<TStory extends UserStory>(driver: PlaybackDriver<TStory>): ProfileDispatchFn<TStory, ProducedState>;
+/** A scored user story — the completion verdict plus its human title. */
+interface UserStoryVerdict extends CompletionVerdict {
+  title: string;
+}
+/**
+ * Score one story's produced state against its requirements. Thin wrapper over
+ * `verifyCompletion` that builds the gold from the story and returns a
+ * per-requirement PASS/FAIL verdict. `checkCorrectness` is injected — a
+ * deterministic stub in tests, `createLlmCorrectnessChecker` in production.
+ */
+declare function scoreUserStory(story: UserStory, state: ProducedState, checkCorrectness: CorrectnessChecker): Promise<UserStoryVerdict>;
+/** One row of the launch scoreboard — story × requirement → PASS/FAIL. */
+interface ScoreboardRow {
+  storyId: string;
+  storyTitle: string;
+  reqId: string;
+  reqTitle: string;
+  status: 'PASS' | 'FAIL';
+  evidence: string[];
+}
+/**
+ * Flatten story verdicts into the per-requirement scoreboard — the literal
+ * Jira tick-off: one row per (story, requirement) with PASS/FAIL and the
+ * evidence behind the verdict.
+ */
+declare function userStoryScoreboard(verdicts: readonly UserStoryVerdict[]): ScoreboardRow[];
+/** Launch-readiness headline counts rolled up from the per-requirement rows. */
+interface ScoreboardSummary {
+  /** Distinct user stories on the board. */
+  stories: number;
+  /** Stories whose every requirement passed. */
+  storiesFullyComplete: number;
+  /** Total (story, requirement) rows. */
+  requirements: number;
+  /** Rows with status PASS. */
+  passed: number;
+  /** Rows with status FAIL. */
+  failed: number;
+  /** passed / requirements; 0 when there are no rows. */
+  passRate: number;
+}
+/** Roll the per-requirement rows up into the launch headline counts. */
+declare function scoreboardSummary(rows: readonly ScoreboardRow[]): ScoreboardSummary;
+interface ScoreboardRenderOptions {
+  /** Document H1. Defaults to a generic playback title. */
+  title?: string;
+  /** Key/value run metadata rendered under the headline (runId, backend, model, date). */
+  meta?: Record<string, string>;
+  /** Max chars of joined evidence shown per row. Default 160. */
+  maxEvidenceChars?: number;
+}
+/**
+ * Render the scoreboard as a launch-readiness Markdown document — the literal
+ * "tick off every user story" artifact: a headline roll-up, the open tickets
+ * (FAIL rows) up top as the launch blockers, then a per-story table of
+ * requirement → PASS/FAIL with the evidence behind each verdict. Pure: same
+ * rows in, same bytes out (no clock/random), so it is safe to snapshot.
+ */
+declare function renderScoreboardMarkdown(rows: readonly ScoreboardRow[], opts?: ScoreboardRenderOptions): string;
+//#endregion
+//#region src/campaign/presets/segmented-profile-matrix.d.ts
+interface ProfileMatrixRow {
+  rowId: string;
+  ordinal: number;
+  profileId: string;
+  scenarioId: string;
+  rep: number;
+}
+interface ProfileMatrixPlan<TScenario extends Scenario, TArtifact> {
+  readonly schemaVersion: 1;
+  readonly matrixId: string;
+  readonly experimentId: string;
+  readonly planDigest: `sha256:${string}`;
+  readonly profiles: readonly AgentProfile$1[];
+  readonly scenarios: readonly TScenario[];
+  readonly judges: readonly JudgeConfig<TArtifact, TScenario>[];
+  readonly reps: number;
+  readonly seed: number;
+  readonly splitTag: NonNullable<RunProfileMatrixOptions<TScenario, TArtifact>['splitTag']>;
+  readonly commitSha: string;
+  /** Stable dispatch implementation/configuration identity used by cell caches. */
+  readonly dispatchRef: string;
+  readonly integrity: NonNullable<RunProfileMatrixOptions<TScenario, TArtifact>['integrity']>;
+  readonly allowMixed: boolean;
+  readonly validate: boolean;
+  readonly personaOf?: (scenario: TScenario) => string;
+  readonly corpusText?: (artifact: TArtifact, scenario: TScenario) => {
+    prompt: string;
+    completion: string;
+  } | undefined;
+  readonly rows: readonly ProfileMatrixRow[];
+}
+interface CreateProfileMatrixPlanOptions<TScenario extends Scenario, TArtifact> extends Pick<RunProfileMatrixOptions<TScenario, TArtifact>, 'profiles' | 'scenarios' | 'judges' | 'commitSha' | 'experimentId' | 'splitTag' | 'reps' | 'seed' | 'integrity' | 'allowMixed' | 'validate' | 'personaOf' | 'corpusText'> {
+  /** Stable dispatch implementation/configuration identity used by cell caches. */
+  dispatchRef: string;
+}
+interface ProfileMatrixCoverage {
+  expected: number;
+  present: number;
+  missing: string[];
+  failed: string[];
+  zeroScore: string[];
+}
+interface RunProfileMatrixSegmentOptions<TScenario extends Scenario, TArtifact> {
+  plan: ProfileMatrixPlan<TScenario, TArtifact>;
+  /** Stable external grant or attempt identity. Reuse it to resume. */
+  segmentId: string;
+  /** Explicit row ids from `plan.rows`; duplicate or unknown rows fail. */
+  rows: readonly (string | ProfileMatrixRow)[];
+  dispatch: ProfileDispatchFn<TScenario, TArtifact>;
+  runDir: string;
+  storage?: CampaignStorage;
+  maxConcurrency?: number;
+  maxProfileConcurrency?: number;
+  costCeiling?: number;
+  labeledStore?: RunProfileMatrixOptions<TScenario, TArtifact>['labeledStore'];
+  captureSource?: RunProfileMatrixOptions<TScenario, TArtifact>['captureSource'];
+  now?: () => Date;
+}
+interface ProfileMatrixSegmentResult<TArtifact, TScenario extends Scenario> {
+  segmentId: string;
+  rowIds: string[];
+  matrix: RunProfileMatrixResult<TArtifact, TScenario>;
+  coverage: ProfileMatrixCoverage;
+}
+interface FinalizeProfileMatrixOptions<TScenario extends Scenario, TArtifact> {
+  plan: ProfileMatrixPlan<TScenario, TArtifact>;
+  runDir: string;
+  storage?: CampaignStorage;
+  maxConcurrency?: number;
+  maxProfileConcurrency?: number;
+  now?: () => Date;
+}
+interface FinalizedProfileMatrixResult<TArtifact, TScenario extends Scenario> extends RunProfileMatrixResult<TArtifact, TScenario> {
+  coverage: ProfileMatrixCoverage;
+}
+declare function createProfileMatrixPlan<TScenario extends Scenario, TArtifact>(opts: CreateProfileMatrixPlanOptions<TScenario, TArtifact>): ProfileMatrixPlan<TScenario, TArtifact>;
+declare function runProfileMatrixSegment<TScenario extends Scenario, TArtifact>(opts: RunProfileMatrixSegmentOptions<TScenario, TArtifact>): Promise<ProfileMatrixSegmentResult<TArtifact, TScenario>>;
+declare function finalizeProfileMatrix<TScenario extends Scenario, TArtifact>(opts: FinalizeProfileMatrixOptions<TScenario, TArtifact>): Promise<FinalizedProfileMatrixResult<TArtifact, TScenario>>;
+//#endregion
+//#region src/campaign/run-dir.d.ts
+/** The shared, out-of-repo root for campaign/benchmark run bundles. Keeping run
+ *  outputs here means they never land in a repo working tree (no per-repo
+ *  gitignore, no clutter, no accidental commits). Layout:
+ *    ~/.tangle/traces/<repo>/runs/<runName>/
+ *  where <repo> disambiguates runs across repos in one place. */
+declare function tangleTracesRoot(): string;
+/** Resolve a campaign `runDir`. An absolute path is honored as-is (the caller
+ *  chose an explicit location). A bare name is placed under the shared home root
+ *  so bundles never pollute a repo working tree — the default the harness should
+ *  compute so callers pass a *name*, not a path. */
+declare function resolveRunDir(runDir: string, repo?: string): string;
+//#endregion
+//#region src/campaign/scenario-selection.d.ts
+/**
+ * Discriminative scenario selection (research claim E2).
+ *
+ * The OR benchmark is SATURATING: run 7 measured ~75% tied holdout cells — most
+ * problems are solved optimally by the baseline AND every candidate, so those
+ * paired cells carry zero signal. A random/balanced holdout split spends its
+ * budget on scenarios that cannot separate candidates.
+ *
+ * This picks the holdout by DISCRIMINATION power instead: a scenario every
+ * candidate scores identically (variance ~0) carries no signal; one where the
+ * scores spread carries the most. We drop fully saturated ties so each paired
+ * holdout cell is spent on a scenario that can actually move a verdict.
+ */
+/** Per-scenario observation: the composite scores each candidate earned on it. */
+interface ScenarioSignal {
+  scenarioId: string;
+  /** Per-candidate composite scores observed for this scenario (>=1 values). */
+  scores: number[];
+}
+interface DiscriminationScore {
+  scenarioId: string;
+  /** Higher = separates candidates more (spread of their scores). */
+  discrimination: number;
+  /** Higher = easier / more-saturated (mean of candidate scores). */
+  meanScore: number;
+  variance: number;
+  /** variance ~0 AND meanScore at/above the ceiling ⇒ a saturated tie, no signal. */
+  tied: boolean;
+}
+/**
+ * Rank scenarios by how well they DISCRIMINATE candidates.
+ *
+ * `discrimination = variance` (spread of the candidate scores) — kept simple on
+ * purpose; the headroom term (`saturationCeiling - meanScore`) only breaks ties
+ * so that, among equally spread scenarios, the one with more room to improve
+ * ranks first. Returned sorted by the deterministic order above.
+ */
+declare function scoreDiscrimination(signals: ScenarioSignal[], opts?: {
+  saturationCeiling?: number;
+}): DiscriminationScore[];
+/**
+ * Select the top-`k` most discriminative scenario ids for a holdout, EXCLUDING
+ * fully saturated ties when enough non-tied scenarios exist (a tie in the
+ * holdout wastes a paired cell).
+ *
+ * Prefers non-tied scenarios; if fewer than `k` non-tied exist, fills with the
+ * least-saturated tied ones (tied scenarios are already ordered least-saturated
+ * first by `meanScore` asc). Deterministic. Throws if `k < 1`. If
+ * `signals.length <= k`, returns all ids in discrimination order.
+ */
+declare function selectDiscriminative(signals: ScenarioSignal[], k: number, opts?: {
+  saturationCeiling?: number;
+}): string[];
+//#endregion
+//#region src/campaign/score-utils.d.ts
+/** Mean composite across cells with complete task-quality evidence.
+ *  Partial judge results remain on their cells but never enter this value.
+ *  A campaign with no complete score has no numeric mean and fails loudly. */
+declare function campaignMeanComposite<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): number;
+/** Compare fixed-length lexicographic rank keys where each element is higher-is-better.
+ *  Returns a positive number when `a` ranks above `b`, negative when below, and
+ *  zero when equal. */
+declare function compareRankKeys(a: readonly number[], b: readonly number[]): number;
+interface CampaignBreakdown {
+  /** Mean score per judge dimension across all cells. */
+  dimensions: Record<string, number>;
+  /** Per-scenario composite (mean over reps + judges) + the judge's free-form
+   *  `notes` for that scenario (the "why" a reflective proposer grounds on) +
+   *  an optional `emitted` excerpt of the candidate's raw output (the "what it
+   *  actually did" a reflective proposer grounds on). */
+  scenarios: Array<{
+    scenarioId: string;
+    composite: number;
+    notes?: string;
+    emitted?: string;
+  }>;
+}
+/** Per-candidate evidence a reflective/patch proposer grounds its next proposal
+ *  on: mean score per judge dimension + per-scenario composite. */
+declare function campaignBreakdown<TArtifact, TScenario extends Scenario>(campaign: CampaignResult<TArtifact, TScenario>): CampaignBreakdown;
+//#endregion
+//#region src/campaign/single-run-lock.d.ts
+/**
+ * Single-run lock for evaluations that share one mutable environment.
+ *
+ * Two concurrent runs against a shared stateful gym silently corrupt each
+ * other: each resets/mutates environment state mid-cell of the other, and
+ * every score from both becomes garbage that LOOKS like worker variance
+ * (agent-lab R357 burned hours on flip-flopping scores before tracing them
+ * to exactly this). The fix is a pid lockfile: refuse to start while a live
+ * holder exists, reclaim stale locks whose pid is gone, release only if the
+ * lock is still ours.
+ *
+ * `alsoCheck` exists because independent runners can guard the same shared
+ * resource with differently named lockfiles; a runner must respect all of
+ * them even though it writes only its own.
+ */
+interface SingleRunLockOptions {
+  /** Lockfile this runner writes (and checks). */
+  readonly lockPath: string;
+  /** Other runners' lockfiles guarding the same resource; checked, never written. */
+  readonly alsoCheck?: readonly string[];
+  /** Install a process 'exit' hook that releases the lock. Default true. */
+  readonly releaseOnExit?: boolean;
+  /** Owner pid recorded in the lockfile metadata. Default process.pid. */
+  readonly pid?: number;
+}
+interface SingleRunLock {
+  /** Remove the lockfile if this process still owns it. Idempotent. */
+  release(): void;
+}
+/**
+ * Acquire the lock or throw naming the live holder. A stale lock (holder pid
+ * no longer running) is reclaimed by one contender. An interrupted reclaim
+ * leaves a marker that fails closed instead of admitting overlapping runs.
+ */
+declare function acquireSingleRunLock(opts: SingleRunLockOptions): SingleRunLock;
+//#endregion
+//#region src/campaign/surface-identity.d.ts
+/** Validate the immutable identity shape; the owning executor verifies the Git objects and patch. */
+declare function assertCodeSurfaceIdentity(surface: unknown): asserts surface is CodeSurface;
+/**
+ * Deterministic identity material for a component surface.
+ *
+ * `canonicalString` orders keys by UTF-16 code unit (RFC 8785), which is a
+ * property of the value alone. The previous material ordered them with
+ * `localeCompare`, which reads the host's collation — so the same surface
+ * could produce two different identities on two machines, and the stored
+ * identity would stop matching a recomputation of the identical surface.
+ */
+declare function componentSurfaceIdentityMaterial(surface: ComponentSurface): string;
+/** Canonical, location-independent identity of a finalized code candidate.
+ *  Commit metadata is excluded: two commits with the same base, final tree,
+ *  and patch bytes are the same executable candidate. */
+declare function codeSurfaceIdentityMaterial(surface: CodeSurface): string;
+/** Full SHA-256 content identity for a prompt or finalized code surface. */
+declare function surfaceContentHash(surface: MutableSurface): `sha256:${string}`;
+/** Short loop key derived from the same content identity as provenance. */
+declare function surfaceHash(surface: MutableSurface): string;
+/** Canonical customer-visible description of the exact before/after surfaces. */
+declare function renderSurfaceDiff(winnerSurface: MutableSurface, baselineSurface: MutableSurface): string;
+/** Bind a campaign cache entry to the exact surface and caller-owned execution revision. */
+declare function surfaceDispatchRef(surface: MutableSurface, executionRef?: string): string;
+//#endregion
+//#region src/campaign/upstream-evaluators.d.ts
+interface PhoenixEvaluationResultLike {
+  score?: number;
+  label?: string;
+  explanation?: string;
+}
+interface PhoenixEvaluatorLike<TRecord extends Record<string, unknown>> {
+  name: string;
+  kind: 'LLM' | 'CODE';
+  optimizationDirection?: 'MAXIMIZE' | 'MINIMIZE' | 'NEUTRAL';
+  evaluate(record: TRecord, context: UpstreamEvaluationContext): Promise<PhoenixEvaluationResultLike>;
+}
+interface AutoevalsScoreLike {
+  name: string;
+  score: number | null;
+  metadata?: Record<string, unknown>;
+}
+type AutoevalsScorerLike<TInput extends Record<string, unknown>> = (input: TInput, context: UpstreamEvaluationContext) => AutoevalsScoreLike | Promise<AutoevalsScoreLike>;
+interface UpstreamEvaluationContext {
+  readonly signal: AbortSignal;
+  readonly callId?: string;
+}
+type PaidEvaluationOptions<TResult> = Pick<RunPaidCallInput<TResult>, 'maximumCharge' | 'receipt' | 'receiptFromError'> & {
+  model: string;
+};
+interface UpstreamJudgeOptions<TScenario extends Scenario> {
+  name?: string;
+  dimension?: string;
+  judgeVersion?: string;
+  appliesTo?: (scenario: TScenario) => boolean;
+  /** Convert the upstream score when its native scale is not higher-is-better. */
+  toComposite?: (score: number) => number;
+}
+declare function phoenixEvaluatorJudge<TRecord extends Record<string, unknown>, TArtifact, TScenario extends Scenario = Scenario>(evaluator: PhoenixEvaluatorLike<TRecord>, options: UpstreamJudgeOptions<TScenario> & {
+  mapInput(input: {
+    artifact: TArtifact;
+    scenario: TScenario;
+  }): TRecord;
+  paidCall?: PaidEvaluationOptions<PhoenixEvaluationResultLike>;
+}): JudgeConfig<TArtifact, TScenario>;
+declare function autoevalsScorerJudge<TInput extends Record<string, unknown>, TArtifact, TScenario extends Scenario = Scenario>(scorer: AutoevalsScorerLike<TInput>, options: UpstreamJudgeOptions<TScenario> & {
+  name: string;
+  mapInput(input: {
+    artifact: TArtifact;
+    scenario: TScenario;
+  }): TInput;
+} & ({
+  kind: 'CODE';
+  paidCall?: never;
+} | {
+  kind: 'LLM';
+  paidCall: PaidEvaluationOptions<AutoevalsScoreLike>;
+})): JudgeConfig<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/worktree/index.d.ts
+type GitOutput = string | Uint8Array;
+type GitEnvironment = Readonly<Record<string, string>>;
+type GitRunner = (args: string[], cwd: string, env?: GitEnvironment) => GitOutput;
+interface Worktree {
+  /** Absolute path to the checked-out worktree directory. */
+  readonly path: string;
+  /** The branch the worktree is on (becomes the PR branch on promotion). */
+  readonly branch: string;
+  /** The ref the worktree was forked from. */
+  readonly baseRef: string;
+  /** Exact commit `baseRef` resolved to before the worktree was created. */
+  readonly baseCommit: string;
+  /** Exact tree object for `baseCommit`. */
+  readonly baseTree: string;
+}
+interface WorktreeAdapter {
+  /** Create an isolated worktree on a fresh branch off `baseRef`. */
+  create(opts: {
+    baseRef: string;
+    label: string;
+  }): Promise<Worktree>;
+  /** Commit pending changes, freeze the exact Git objects + binary patch, and
+   *  verify the worktree still matches that identity. */
+  finalize(worktree: Worktree, summary: string): Promise<CodeSurface>;
+  /** Idempotently remove the worktree and branch. Safe to retry after partial cleanup. */
+  discard(worktree: Worktree): Promise<void>;
+}
+/** Typed failure from a `WorktreeAdapter` operation (create/finalize/discard) — wraps the underlying git error as `cause`. */
+declare class WorktreeAdapterError extends Error {
+  readonly cause?: unknown;
+  constructor(message: string, cause?: unknown);
+}
+interface GitWorktreeAdapterOptions {
+  /** Repo root the worktrees fork from. */
+  repoRoot: string;
+  /** Directory worktrees are created under. Default: `<repoRoot>/.worktrees`. */
+  worktreeDir?: string;
+  /** Branch-name prefix. Default: `improve`. */
+  branchPrefix?: string;
+  /** Test seam — defaults to a real `git` runner. The return value must contain
+   *  stdout verbatim, and runners that execute Git must forward the optional
+   *  environment overrides used to isolate patch generation. */
+  git?: GitRunner;
+}
+interface CodeSurfaceVerification {
+  /** Verified worktree path. */
+  path: string;
+  /** Git's canonical root for the verified checkout. */
+  repoRoot: string;
+  /** Recomputed full content identity. */
+  contentHash: `sha256:${string}`;
+  /** Exact verified binary-patch bytes. Candidate-bundle builders encode this
+   *  directly instead of reproducing Git diff options. */
+  patchBytes: Uint8Array;
+}
+/**
+ * Git-backed `WorktreeAdapter`: creates isolated worktrees on fresh branches, commits agent changes, and discards losers.
+ */
+declare function gitWorktreeAdapter(opts: GitWorktreeAdapterOptions): WorktreeAdapter;
+/** Verify a finalized code surface against its current checkout. This rejects
+ *  dirty/ignored files, moved refs, missing Git objects, raw byte/mode
+ *  mismatches, external symlinks, and submodules. */
+declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string): CodeSurfaceVerification;
+/** Resolve a code candidate for evaluation only after verifying its immutable
+ *  identity against the checkout at `worktreeRef`. */
+declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
+//#endregion
+export { UserStoryVerdict as $, OpenAutoPrOptions as $a, SearchHistoryCoverageRow as $i, campaignMeasurementDigest as $n, OptimizationMethodProvenance as $r, PlanEvalFixtureRunOptions as $t, ScenarioSignal as A, SearchOperationKind as Aa, RunImprovementLoopOptions as Ai, CrossSurfacePairEvidence as An, SkillOptTrainerConfig as Ar, completionVerdict as At, ProfileMatrixRow as B, SearchSurfaceKind as Ba, SearchLedgerBinding as Bi, TraceAnalystScenario as Bn, OptimizerModelBudget as Br, ScoredRollout as Bt, SingleRunLockOptions as C, SearchLedgerAppendResult as Ca, LlmJudgeDimension as Ci, CrossSurfaceInteractionAwareSelection as Cn, assertCampaignSplitIdentity as Co, CanaryKind as Cr, CorrectnessChecker as Ct, campaignMeanComposite as D, SearchLedgerReplay as Da, isTransientTransportFailure as Di, CrossSurfaceInteractionTask as Dn, composeGate as Dr, RequirementCheck as Dt, campaignBreakdown as E, SearchLedgerHash as Ea, TransientFailureOptions as Ei, CrossSurfaceInteractionReport as En, campaignSplitDigestFromIdentities as Eo, runCanaries as Er, ProducedState as Et, CreateProfileMatrixPlanOptions as F, SearchPlannedOperation as Fa, RunOptimizationResult as Fi, CrossSurfaceSelectionPolicy as Fn, GepaOptimizationMethodConfig as Fr, FsLabeledScenarioStoreOptions as Ft, runProfileMatrixSegment as G, validateSearchLedgerEvent as Ga, GepaCandidatePopulationArtifact as Gi, EmitLoopProvenanceResult as Gn, ExternalOptimizationExample as Gr, neutralizationGate as Gt, RunProfileMatrixSegmentOptions as H, SearchTaskOutcome as Ha, SearchRecorderOptions as Hi, traceAnalystQualityJudge as Hn, ExternalTextOptimizationMethodConfig as Hr, classifyUngroundedLiterals as Ht, FinalizeProfileMatrixOptions as I, SearchPlannedTask as Ia, runOptimization as Ii, CrossSurfaceSelections as In, GepaOptimizationRecipe as Ir, LabeledScenarioStoreError as It, PlaybackStep as J, SearchLedgerIntegrityError as Ja, GepaCandidateSelectionScore as Ji, LoopProvenanceCandidate as Jn, CompareOptimizationMethodsOptions as Jr, EvalFixtureLoadOptions as Jt, PlaybackContext as K, SearchLedgerConflictError as Ka, GepaCandidatePopulationCandidate as Ki, LoopProvenanceArgsFromResult as Kn, ExternalTextEvaluationResponse as Kr, EvalFixture as Kt, FinalizedProfileMatrixResult as L, SearchSourceRef as La, MeasuredSearchCandidate as Li, CrossSurfaceTaskRow as Ln, GepaRunnerCommand as Lr, RolloutArgumentDiff as Lt, selectDiscriminative as M, SearchPlan as Ma, runImprovementLoop as Mi, CrossSurfacePairwiseEntry as Mn, GepaAdaptiveEngineRun as Mr, verifyCompletion as Mt, resolveRunDir as N, SearchPlanExtendedEvent as Na, PremeasuredOptimizationBaseline as Ni, CrossSurfaceRankedSingle as Nn, GepaEngineOptions as Nr, neutralizeText as Nt, compareRankKeys as O, SearchLedgerTrustedHeadMode as Oa, quotaExhaustedUntil as Oi, CrossSurfaceNaiveStackSelection as On, SkillOptOptimizationMethodConfig as Or, SatisfiedBy as Ot, tangleTracesRoot as P, SearchPlannedEvent as Pa, RunOptimizationOptions as Pi, CrossSurfaceRelativeCost as Pn, GepaEngineRun as Pr, FsLabeledScenarioStore as Pt, UserStory as Q, crowdedFrontierParent as Qa, SearchHistoryCoverage as Qi, buildLoopProvenanceRecord as Qn, OptimizationMethodPairwise as Qr, LoadEvalFixtureScenariosOptions as Qt, ProfileMatrixCoverage as R, SearchSurfaceEffect as Ra, ProposedSearchCandidate as Ri, BuildTraceAnalystSurfaceDispatchOptions as Rn, gepaOptimizationMethod as Rr, RolloutArgumentDiffOptions as Rt, SingleRunLock as S, SearchLedger as Sa, runReferenceEquivalenceJudge as Si, CrossSurfaceIneligibilityReason as Sn, assertCampaignDesign as So, CanaryEvaluation as Sr, CompletionVerdict as St, CampaignBreakdown as T, SearchLedgerEvent as Ta, llmJudge as Ti, CrossSurfaceInteractionPath as Tn, campaignSplitDigest as To, CanaryReport as Tr, ProducedProposal as Tt, createProfileMatrixPlan as U, SearchTokenAccounting as Ua, SearchRunIdentity as Ui, BuildLoopProvenanceArgs as Un, ExternalTextOptimizerContext as Ur, rolloutArgumentDiff as Ut, ProfileMatrixSegmentResult as V, SearchTaskAttemptedEvent as Va, SearchRecorder as Vi, buildTraceAnalystSurfaceDispatch as Vn, externalTextOptimizationMethod as Vr, UngroundedLiteralReport as Vt, finalizeProfileMatrix as W, openSearchLedger as Wa, recordCandidatePopulationSearch as Wi, EmitLoopProvenanceArgs as Wn, ExternalTextOptimizerResult as Wr, NeutralizationGateOptions as Wt, ScoreboardRow as X, ParentSelectionContext as Xa, CreateSearchHistoryReceiptInput as Xi, LoopProvenanceOptimizationMethod as Xn, OptimizationMethodComparison as Xr, EvalFixtureScenario as Xt, ScoreboardRenderOptions as Y, CrowdedFrontierParentOptions as Ya, readGepaCandidatePopulationArtifact as Yi, LoopProvenanceEvidence as Yn, OptimizationMethod as Yr, EvalFixtureRunPlan as Yt, ScoreboardSummary as Z, ParentSelector as Za, SearchHistoryAuditSummary as Zi, LoopProvenanceRecord as Zn, OptimizationMethodInput as Zr, EvalFixtureValidationMode as Zt, componentSurfaceIdentityMaterial as _, SearchCandidateSlotClosedEvent as _a, ReferenceEquivalenceJudgeInput as _i, CrossSurfaceComponentEvidence as _n, cellCachePath as _o, RedTeamReport as _r, ProposalEventLike as _t, WorktreeAdapterError as a, createSearchHistoryReceipt as aa, compareOptimizationMethods as ai, AnalyzeCrossSurfaceInteractionsInput as an, CampaignCellRetryPolicy as ao, provenanceSpansPath as ar, ProfileDispatchFn as at, surfaceDispatchRef as b, SearchCostAccounting as ba, ReferenceEquivalenceScenario as bi, CrossSurfaceEligibility as bn, fsCampaignStorage as bo, scoreRedTeamOutput as br, extractProducedState as bt, verifyCodeSurface as c, FileSearchLedger as ca, combineComparisonCosts as ci, CrossSurfaceAttemptCompleteness as cn, CampaignRunPlan as co, heldOutGate as cr, RunProfileMatrixOptions as ct, PhoenixEvaluationResultLike as d, SearchArtifactRef as da, ExternalOptimizerObservationArtifact as di, CrossSurfaceCandidate as dn, planCampaignRun as do, DefaultProductionRewardHackingOptions as dr, runProfileMatrix as dt, SearchHistoryPolicy as ea, OptimizationMethodResult as ei, discoverEvalFixtures as en, OpenAutoPrResult as eo, canonicalDigest as er, makePlaybackDispatch as et, PhoenixEvaluatorLike as f, SearchAttemptAccounting as fa, ExternalOptimizerObservationSummary as fi, CrossSurfaceCandidateComparison as fn, CacheIssueReason as fo, defaultProductionGate as fr, BackendIntegrityError as ft, codeSurfaceIdentityMaterial as g, SearchCandidateSlot as ga, REFERENCE_EQUIVALENCE_JUDGE_VERSION as gi, CrossSurfaceComponent as gn, buildCellSchedule as go, RedTeamFinding as gr, ArtifactEventLike as gt, assertCodeSurfaceIdentity as h, SearchCandidateRegisteredEvent as ha, REFERENCE_EQUIVALENCE_INPUT_LIMITS as hi, CrossSurfaceCandidateSummary as hn, CellScheduleSlot as ho, RedTeamCategory as hr, summarizeBackendIntegrity as ht, WorktreeAdapter as i, assertSearchHistoryMatchesReplay as ia, OptimizationTokenUsage as ii, analyzeCrossSurfaceInteractions as in, CampaignCellFailureReceipt as io, provenanceRecordPath as ir, userStoryScoreboard as it, scoreDiscrimination as j, SearchOperationRecordedEvent as ja, RunImprovementLoopResult as ji, CrossSurfacePairIncompatibilityReason as jn, skillOptOptimizationMethod as jr, createLlmCorrectnessChecker as jt, DiscriminationScore as k, SearchModelIdentity as ka, transientDispatchFailure as ki, CrossSurfacePairCompatibility as kn, SkillOptRunnerCommand as kr, TaskGold as kt, AutoevalsScoreLike as l, OpenSearchLedgerOptions as la, costFromLedgerSummary as li, CrossSurfaceBestSingleSelection as ln, CampaignRunPlanCell as lo, DefaultProductionGateCheck as lr, RunProfileMatrixResult as lt, phoenixEvaluatorJudge as m, SearchCandidateLineage as ma, readExternalOptimizerObservationArtifact as mi, CrossSurfaceCandidateOutcome as mn, readCachedCell as mo, RedTeamCase as mr, assertRealBackend as mt, GitWorktreeAdapterOptions as n, SearchHistoryRequiredError as na, OptimizationMethodScore as ni, loadEvalFixtureScenarios as nn, RunEvalOptions as no, loopProvenanceArgsFromResult as nr, scoreUserStory as nt, gitWorktreeAdapter as o, searchHistoryCoverageRow as oa, optimizationTokenUsageFromSummary as oi, CrossSurfaceAdditionDecision as on, RunCampaignOptions as oo, verifyLoopProvenanceRecord as or, ProfileMatrixError as ot, autoevalsScorerJudge as p, SearchCandidateDecidedEvent as pa, ExternalOptimizerSubmittedCandidate as pi, CrossSurfaceCandidateEvidence as pn, CacheRead as po, DEFAULT_RED_TEAM_CORPUS as pr, BackendIntegrityReport as pt, PlaybackDriver as q, SearchLedgerError as qa, GepaCandidatePopulationSummary as qi, LoopProvenanceBackend as qn, decodeExternalTextCandidate as qr, EvalFixtureFile as qt, Worktree as r, assertCompleteSearchHistory as ra, OptimizationPackageSource as ri, planEvalFixtureRun as rn, runEval as ro, loopProvenanceSpans as rr, scoreboardSummary as rt, resolveWorktreePath as s, verifySearchHistoryReceipt as sa, ComparisonCost as si, CrossSurfaceAdditionRejectionReason as sn, runCampaign as so, HeldOutGateOptions as sr, ProfileSummary as st, CodeSurfaceVerification as t, SearchHistoryReceipt as ta, OptimizationMethodRunOptions as ti, loadEvalFixture as tn, openAutoPr as to, emitLoopProvenance as tr, renderScoreboardMarkdown as tt, AutoevalsScorerLike as u, SearchAccountingAudit as ua, ExternalOptimizerExecutionSummary as ui, CrossSurfaceBootstrapPolicy as un, PlanCampaignRunOptions as uo, DefaultProductionGateOptions as ur, ScenarioRollup as ut, renderSurfaceDiff as v, SearchCandidateSurface as va, ReferenceEquivalenceJudgeOptions as vi, CrossSurfaceCompositionStep as vn, CampaignStorage as vo, redTeamDataset as vr, RuntimeEventLike as vt, acquireSingleRunLock as w, SearchLedgerEntry as wa, LlmJudgeOptions as wi, CrossSurfaceInteractionEffect as wn, campaignScenarioIdentity as wo, CanaryOptions as wr, LlmCorrectnessCheckerOpts as wt, surfaceHash as x, SearchFailureReason as xa, createReferenceEquivalenceJudge as xi, CrossSurfaceEvidenceBreakdown as xn, inMemoryCampaignStorage as xo, CanaryAlert as xr, CompletionRequirement as xt, surfaceContentHash as y, SearchCompletedEvent as ya, ReferenceEquivalenceJudgeResult as yi, CrossSurfaceDistribution as yn, createRunCostLedger as yo, redTeamReport as yr, ToolCallEventLike as yt, ProfileMatrixPlan as z, SearchSurfaceEvidence as za, SearchExecutionIdentity as zi, TraceAnalystArtifact as zn, OpenAICompatibleOptimizerModel as zr, RolloutCall as zt };
+//# sourceMappingURL=index-DKXuBPXf.d.ts.map