@tangle-network/agent-eval 0.173.2 → 0.174.0

package/dist/provenance-CRY67X50.d.ts

@@ -1,1995 +0,0 @@
-import { c as CostLedgerHandle, f as CostLedgerSummary, m as CostReceipt, o as CostLedger, p as CostProvenance } from "./cost-ledger-DbQdN3nO.js";
-import { a as RunRecord } from "./run-record-DTv1MdjK.js";
-import { _ as ProposalFinding } from "./types-DN2WdT5S.js";
-import { p as ChatClient } from "./types-gvRsyJLh.js";
-import { B as ScoredSurfaceOutcome, C as JudgeDimension, H as SurfaceProposer, N as ParetoParent, R as Scenario, S as JudgeConfig, _ as GateDecision, a as CampaignResult, b as GenerationRecord, c as CampaignTraceWriter, d as DispatchContext, f as DispatchFn, g as GateContribution, j as MutableSurface, k as LabeledScenarioStore, p as Gate, r as CampaignCellResult, v as GateResult, y as GenerationCandidate } from "./types-Ba5UQyVD.js";
-import { m as LedgerTrustedHeadRemoval, p as LedgerTrustedHead } from "./index-D-UdhAmg.js";
-import { r as LedgerHash } from "./canonical-CFpojCN5.js";
-import { _ as ExternalTextCandidate, g as ExternalOptimizerWireCounts, o as ExternalOptimizerEvaluationObservation } from "./external-optimizer-contracts-CQCpyrIL.js";
-import { r as DatasetScenario, t as Dataset } from "./dataset-DQqhOCPt.js";
-import { g as TraceSpanEvent, t as HostedClient } from "./client-DlqdbM7n.js";
-import { z } from "zod";
-//#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.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/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/presets/compare-optimization-methods.d.ts
-/** Shared campaign settings applied to every optimization method. */
-type OptimizationMethodRunOptions<TScenario extends Scenario, TArtifact> = Omit<RunCampaignOptions<TScenario, TArtifact>, 'costCeiling' | 'costLedger' | 'dispatch' | 'judges' | 'runDir' | 'scenarios' | 'seed'>;
-/** Cost reported by a method or by final test scoring. */
-interface ComparisonCost {
-  /** 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[];
-}
-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;
-  };
-  /** Optimization spend reported by the method. Excludes final test scoring. */
-  optimizationCost: ComparisonCost;
-  /** Optimization duration reported by the method. Excludes final test scoring. */
-  durationMs?: number;
-  /** Exact external implementation and run identity, when reported by the method. */
-  provenance?: OptimizationMethodProvenance;
-  /** Paired final-test values used to compute lift and its interval. */
-  scenarioScores: Array<{
-    scenarioId: string;
-    baselineComposite: number;
-    winnerComposite: number;
-    lift: number;
-  }>;
-  winnerSurface: MutableSurface;
-  /** 1-based, by descending lift. */
-  rank: number;
-}
-interface OptimizationMethodPairwise {
-  /** Higher-ranked method. */
-  a: string;
-  b: string;
-  /** Mean per-scenario untouched-test delta (a − b). */
-  deltaMean: number;
-  low: number;
-  high: number;
-  /** `a` if the CI clears 0, `b` if it is entirely negative, else `'tie'`. */
-  favored: string;
-}
-interface OptimizationMethodComparison {
-  /** Sorted by descending lift; `rank` set accordingly. */
-  scores: OptimizationMethodScore[];
-  best: OptimizationMethodScore;
-  /** Best vs each other method, using simultaneous paired-bootstrap intervals. */
-  pairwise: OptimizationMethodPairwise[];
-  testScenarioIds: string[];
-  /** Sum of the costs reported by every optimization method. */
-  optimizationCost: ComparisonCost;
-  /** Baseline and distinct winner scoring on the final test partition. */
-  testCost: ComparisonCost;
-  /** Optimization plus final test scoring. */
-  totalCost: ComparisonCost;
-  /** Caller-requested simultaneous coverage across all reported contrasts. */
-  confidence: number;
-  /** Bonferroni-adjusted confidence used for each bootstrap interval. */
-  intervalConfidence: number;
-  /** Method-vs-baseline plus all possible method-vs-method contrasts. */
-  comparisonCount: number;
-  /** Deterministic bootstrap and campaign seed. */
-  seed: number;
-  /** Bootstrap draws used for each interval. */
-  resamples: number;
-  /** Agent runs averaged within each test scenario before resampling scenarios. */
-  reps: number;
-  /** 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>;
-/** Keep the cost fields a custom optimization method must report. */
-declare function costFromLedgerSummary(summary: CostLedgerSummary): ComparisonCost;
-/** Preserve every optimizer token class while keeping total input and output explicit. */
-declare function optimizationTokenUsageFromSummary(summary: CostLedgerSummary, receipts: readonly CostReceipt[]): OptimizationTokenUsage | undefined;
-/** 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/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/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
-export { readExternalOptimizerObservationArtifact as $, SearchLedger as $t, CanaryOptions as A, RunEvalOptions as An, SearchHistoryCoverageRow as At, OptimizationMethodResult as B, CacheIssueReason as Bn, OpenSearchLedgerOptions as Bt, RedTeamReport as C, CrowdedFrontierParentOptions as Cn, GepaCandidatePopulationCandidate as Ct, CanaryAlert as D, OpenAutoPrOptions as Dn, CreateSearchHistoryReceiptInput as Dt, scoreRedTeamOutput as E, crowdedFrontierParent as En, readGepaCandidatePopulationArtifact as Et, OptimizationMethod as F, runCampaign as Fn, assertSearchHistoryMatchesReplay as Ft, combineComparisonCosts as G, cellCachePath as Gn, SearchCandidateLineage as Gt, OptimizationMethodScore as H, readCachedCell as Hn, SearchArtifactRef as Ht, OptimizationMethodComparison as I, CampaignRunPlan as In, createSearchHistoryReceipt as It, optimizationTokenUsageFromSummary as J, fsCampaignStorage as Jn, SearchCandidateSlotClosedEvent as Jt, compareOptimizationMethods as K, CampaignStorage as Kn, SearchCandidateRegisteredEvent as Kt, OptimizationMethodInput as L, CampaignRunPlanCell as Ln, searchHistoryCoverageRow as Lt, runCanaries as M, CampaignCellFailureReceipt as Mn, SearchHistoryReceipt as Mt, CompareOptimizationMethodsOptions as N, CampaignCellRetryPolicy as Nn, SearchHistoryRequiredError as Nt, CanaryEvaluation as O, OpenAutoPrResult as On, SearchHistoryAuditSummary as Ot, ComparisonCost as P, RunCampaignOptions as Pn, assertCompleteSearchHistory as Pt, ExternalOptimizerSubmittedCandidate as Q, SearchFailureReason as Qt, OptimizationMethodPairwise as R, PlanCampaignRunOptions as Rn, verifySearchHistoryReceipt as Rt, RedTeamFinding as S, validateSearchLedgerEvent as Sn, GepaCandidatePopulationArtifact as St, redTeamReport as T, ParentSelector as Tn, GepaCandidateSelectionScore as Tt, OptimizationPackageSource as U, CellScheduleSlot as Un, SearchAttemptAccounting as Ut, OptimizationMethodRunOptions as V, CacheRead as Vn, SearchAccountingAudit as Vt, OptimizationTokenUsage as W, buildCellSchedule as Wn, SearchCandidateDecidedEvent as Wt, ExternalOptimizerObservationArtifact as X, SearchCompletedEvent as Xt, ExternalOptimizerExecutionSummary as Y, inMemoryCampaignStorage as Yn, SearchCandidateSurface as Yt, ExternalOptimizerObservationSummary as Z, SearchCostAccounting as Zt, provenanceSpansPath as _, SearchSurfaceKind as _n, SearchLedgerBinding as _t, LoopProvenanceBackend as a, SearchLedgerTrustedHeadMode as an, quotaExhaustedUntil as at, RedTeamCase as b, SearchTokenAccounting as bn, SearchRunIdentity as bt, LoopProvenanceOptimizationMethod as c, SearchOperationRecordedEvent as cn, RunImprovementLoopResult as ct, campaignMeasurementDigest as d, SearchPlannedEvent as dn, RunOptimizationOptions as dt, SearchLedgerAppendResult as en, LlmJudgeDimension as et, canonicalDigest as f, SearchPlannedOperation as fn, RunOptimizationResult as ft, provenanceRecordPath as g, SearchSurfaceEvidence as gn, SearchExecutionIdentity as gt, loopProvenanceSpans as h, SearchSurfaceEffect as hn, ProposedSearchCandidate as ht, LoopProvenanceArgsFromResult as i, SearchLedgerReplay as in, isTransientTransportFailure as it, CanaryReport as j, runEval as jn, SearchHistoryPolicy as jt, CanaryKind as k, openAutoPr as kn, SearchHistoryCoverage as kt, LoopProvenanceRecord as l, SearchPlan as ln, runImprovementLoop as lt, loopProvenanceArgsFromResult as m, SearchSourceRef as mn, MeasuredSearchCandidate as mt, EmitLoopProvenanceArgs as n, SearchLedgerEvent as nn, llmJudge as nt, LoopProvenanceCandidate as o, SearchModelIdentity as on, transientDispatchFailure as ot, emitLoopProvenance as p, SearchPlannedTask as pn, runOptimization as pt, costFromLedgerSummary as q, createRunCostLedger as qn, SearchCandidateSlot as qt, EmitLoopProvenanceResult as r, SearchLedgerHash as rn, TransientFailureOptions as rt, LoopProvenanceEvidence as s, SearchOperationKind as sn, RunImprovementLoopOptions as st, BuildLoopProvenanceArgs as t, SearchLedgerEntry as tn, LlmJudgeOptions as tt, buildLoopProvenanceRecord as u, SearchPlanExtendedEvent as un, PremeasuredOptimizationBaseline as ut, verifyLoopProvenanceRecord as v, SearchTaskAttemptedEvent as vn, SearchRecorder as vt, redTeamDataset as w, ParentSelectionContext as wn, GepaCandidatePopulationSummary as wt, RedTeamCategory as x, openSearchLedger as xn, recordCandidatePopulationSearch as xt, DEFAULT_RED_TEAM_CORPUS as y, SearchTaskOutcome as yn, SearchRecorderOptions as yt, OptimizationMethodProvenance as z, planCampaignRun as zn, FileSearchLedger as zt };
-//# sourceMappingURL=provenance-CRY67X50.d.ts.map