@tangle-network/agent-eval 0.117.1 → 0.118.0

package/dist/campaign/index.d.ts

@@ -1,37 +1,6 @@
-import { v as PolicyEditAdmissionOptions, u as PolicyEditAdmission, t as PolicyEdit, c as AnalystFinding, F as FindingToPolicyEditOptions } from '../policy-edit-wG9uFEFm.js';
-export { r as POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, P as PolicyEditCandidateRecord, a2 as validatePolicyEditCandidateRecord } from '../policy-edit-wG9uFEFm.js';
-import { P as PairedArmsComparison, S as SignedManifest, B as BackendIntegrityReport, C as CompletionRequirement, R as RuntimeEventLike, a as CompletionVerdict, b as ProducedState, c as CorrectnessChecker } from '../pre-registration-BWQhJ3vz.js';
-export { L as LlmJudgeDimension, d as LlmJudgeOptions, l as llmJudge } from '../pre-registration-BWQhJ3vz.js';
-import { C as CampaignRunPlan, P as PlanCampaignRunOptions, h as RunCampaignOptions, i as RunImprovementLoopOptions } from '../gepa-eESocoDi.js';
-export { o as CampaignRunPlanCell, p as GepaProposerConstraints, G as GepaProposerOptions, O as OpenAutoPrOptions, q as OpenAutoPrResult, e as ReferenceEquivalenceJudgeOptions, g as ReferenceEquivalenceScenario, a as RunImprovementLoopResult, R as RunOptimizationOptions, s as RunOptimizationResult, t as countSentenceEdits, j as createReferenceEquivalenceJudge, u as defaultRenderDiff, v as extractH2Sections, k as gepaProposer, w as openAutoPr, x as planCampaignRun, r as runCampaign, l as runImprovementLoop, y as runOptimization } from '../gepa-eESocoDi.js';
-import { A as AnalyzeTracesOptions, a as AnalyzeTracesInput, b as AnalyzeTracesResult } from '../analyst-C8HHvfJp.js';
-import { S as Scenario, M as MutableSurface, D as DispatchContext, b as JudgeConfig, G as Gate, o as GenerationRecord, J as JudgeScore, L as LabeledScenarioStore, s as LabeledScenarioWrite, t as LabeledScenarioSampleArgs, u as LabeledScenarioRecord, v as LabelTrust, c as SurfaceProposer, w as ProposedCandidate, x as ProposeContext, j as CodeSurface, y as LabeledScenarioSource, C as CampaignResult } from '../types-BSw1rOUB.js';
-export { e as CampaignAggregates, f as CampaignArtifactWriter, g as CampaignCellResult, h as CampaignCostMeter, z as CampaignTokenUsage, i as CampaignTraceWriter, k as DispatchFn, l as GateContext, d as GateDecision, m as GateResult, n as GenerationCandidate, A as JudgeAggregate, a as JudgeDimension, p as Mutator, O as OptimizationProposer, q as OptimizerConfig, P as ParetoParent, R as RedactionStatus, B as ScenarioAggregate, E as ScoredSurfaceOutcome, r as SessionScript, T as TraceSpan, F as isProposedCandidate, H as labelTrustRank } from '../types-BSw1rOUB.js';
-import { a as PairedBootstrapResult, E as EProcessState } from '../statistics-KUnG73jH.js';
-import { C as CampaignStorage } from '../storage-DrX3v_5B.js';
-export { c as createRunCostLedger, f as fsCampaignStorage, i as inMemoryCampaignStorage } from '../storage-DrX3v_5B.js';
-export { A as AxisEvidence, a as AxisVerdict, B as BuildEvidenceVectorOptions, l as BuildLoopProvenanceArgs, D as DefaultProductionGateOptions, m as EmitLoopProvenanceArgs, n as EmitLoopProvenanceResult, E as EvidenceVector, b as EvolutionaryProposerOptions, H as HeldOutGateOptions, o as LoopProvenanceBackend, q as LoopProvenanceCandidate, L as LoopProvenanceRecord, O as ObjectiveSource, c as ParetoSignificanceGateOptions, P as PowerPreflight, s as PowerPreflightOptions, d as PromotionObjective, e as PromotionPolicy, R as RunEvalOptions, f as buildEvidenceVector, t as buildLoopProvenanceRecord, g as composeGate, h as defaultProductionGate, u as emitLoopProvenance, i as evolutionaryProposer, j as heldOutGate, v as loopProvenanceSpans, p as paretoPolicy, k as paretoSignificanceGate, w as powerPreflight, x as provenanceRecordPath, y as provenanceSpansPath, r as runEval } from '../provenance-DpjwyseI.js';
-import { a as LlmClientOptions } from '../llm-client-qoDd18Qz.js';
+import { z } from 'zod';
+import { AxAIService, AxFunction } from '@ax-llm/ax';
 import { AgentProfile } from '@tangle-network/agent-interface';
-import { A as AgentEvalError, V as ValidationError } from '../errors-oeQrLqXC.js';
-import { a as RunSplitTag, R as RunRecord } from '../run-record-BDH49H2E.js';
-import { C as CostLedger, b as CostLedgerSummary, M as MaximumCharge, c as CostReceiptInput } from '../cost-ledger-DWy3XdJc.js';
-import { T as TraceAnalystKindSpec } from '../kind-factory-ClZmO25A.js';
-import '../store-C1YxJDEK.js';
-import '../types-BkfcQnxV.js';
-import '@tangle-network/tcloud';
-import 'zod';
-import '../raw-provider-sink-C46HDghv.js';
-import '../verdict-C9MlYujm.js';
-import '../dataset-NENEzRgk.js';
-import '../store-DGqD0Pyo.js';
-import '../schema-B3Q3l9Z_.js';
-import '@ax-llm/ax';
-import '../judge-calibration-7C-IDmKr.js';
-import '../hosted/index.js';
-import '../insight-report-DY4nDW9Q.js';
-import '../summary-report-C5bKFfm-.js';
-import '../failure-cluster-DOAcSJ87.js';
 
 /**
  * Lineage DAG — a git-graph of improvement candidates.
@@ -270,6 +239,1941 @@ interface RunLineageResult {
  *  every node. Honors `prune`: a pruned track is never extended or branched again. */
 declare function runLineage(opts: RunLineageOptions): Promise<RunLineageResult>;
 
+/**
+ * Error taxonomy for `@tangle-network/agent-eval`.
+ *
+ * Every error this package throws as part of its *public contract* extends
+ * `AgentEvalError`. Consumers can pattern-match by `instanceof <Subclass>` or
+ * by the stable string `code` carried on the base class.
+ *
+ * The codes are stable across minor versions; new codes can be added, but
+ * existing codes never change meaning. New subclasses are non-breaking.
+ *
+ * Internal invariant guards (`throw new Error('this should never happen')`)
+ * remain plain `Error`s on purpose — they're programmer-mistake assertions,
+ * not consumer-catchable contract failures.
+ */
+type AgentEvalErrorCode = 'validation' | 'not_found' | 'config' | 'capture_integrity' | 'judge' | 'verification' | 'replay' | 'backend_integrity' | 'profile_matrix';
+/**
+ * Base class for every contract error this package throws — carries the stable
+ * string `code` taxonomy so consumers can `instanceof`-match or switch on `code`.
+ */
+declare class AgentEvalError extends Error {
+    /** Stable string code. Survives minification; safe to switch on. */
+    readonly code: AgentEvalErrorCode;
+    constructor(code: AgentEvalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Caller passed invalid arguments (out of range, mutually-exclusive options, bad shape). */
+declare class ValidationError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
+type AgentProfileJson = string | number | boolean | null | AgentProfileJson[] | {
+    [key: string]: AgentProfileJson;
+};
+type AgentProfileDimensionValue = string | number | boolean | null;
+interface AgentProfileSource {
+    /** Runtime/profile contract being fingerprinted, e.g. `agent-interface-profile`. */
+    kind: string;
+    /** sha256 over the canonical source profile object. */
+    hash: string;
+}
+interface AgentProfileHarness {
+    id: string;
+    version?: string;
+    hash?: string;
+}
+interface AgentProfileCell {
+    schemaVersion: AgentProfileCellSchemaVersion;
+    cellId: string;
+    profileId: string;
+    sourceProfile: AgentProfileSource;
+    harness?: AgentProfileHarness;
+    model?: string;
+    promptHash?: string;
+    dimensions?: Record<string, AgentProfileDimensionValue>;
+}
+
+type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'tool_argument_error' | 'tool_recovery_failure' | 'hallucination' | 'instruction_following' | 'safety_refusal_miss' | 'policy_violation' | 'budget_exceeded' | 'format_drift' | 'permission_escalation' | 'pii_leak' | 'cost_overrun' | 'timeout' | 'sandbox_failure' | 'missing_user_data' | 'missing_domain_data' | 'missing_codebase_context' | 'missing_runtime_context' | 'missing_credentials' | 'missing_integration_connection' | 'missing_integration_scope' | 'integration_approval_required' | 'integration_auth_expired' | 'integration_provider_failure' | 'bad_integration_manifest' | 'unsafe_integration_write_denied' | 'stale_external_data' | 'bad_retrieval' | 'insufficient_evidence' | 'contradictory_evidence' | 'ambiguous_user_intent' | 'knowledge_readiness_blocked' | 'unknown';
+
+/**
+ * Paper-grade RunRecord schema + runtime validator.
+ *
+ * Every run that participates in a promotion gate, paper table, or
+ * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
+ * fields are exactly those the paper "Two Loops, Three Roles" requires
+ * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
+ * holdout split tag and either a `searchScore` or a `holdoutScore`.
+ *
+ * This is intentionally NOT a replacement for the rich `Run` /
+ * `ProposeReviewReport` / `ScenarioResult` types already in the
+ * package. Those are runtime structures with full provenance. A
+ * `RunRecord` is the analysis-time projection — the JSON-friendly
+ * row you'd put in a parquet file or paste into a notebook.
+ *
+ * Validate at the boundary:
+ *
+ *   const rec = validateRunRecord(rawJson)         // throws on missing
+ *   const ok  = isRunRecord(rawJson)               // boolean check
+ *   const rec = parseRunRecordSafe(rawJson)        // { ok, value | error }
+ *
+ * The validator runs in pure TS — zod is intentionally NOT a
+ * dependency. Round-trip tested in `tests/run-record.test.ts`.
+ */
+
+/** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
+ *  combined train+test pool that the optimizer is allowed to read. */
+type RunSplitTag = 'search' | 'dev' | 'holdout';
+interface RunTokenUsage {
+    input: number;
+    /** All generated tokens charged as output, including reasoning tokens. */
+    output: number;
+    /** Reasoning-token subset of `output`, when the provider reports it. */
+    reasoning?: number;
+    /** Prompt tokens served from a provider cache. */
+    cached?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWrite?: number;
+}
+/**
+ * How a run's USD amount was obtained.
+ *
+ * `costUsd` remains mandatory for wire compatibility. New producers should
+ * always populate this discriminated union so a missing bill is never
+ * mistaken for an observed zero-dollar run. For `uncaptured`, `costUsd` uses
+ * the legacy `0` sentinel while this field carries the truthful null.
+ */
+type RunCostProvenance = {
+    kind: 'observed';
+    usd: number;
+} | {
+    kind: 'estimated';
+    usd: number;
+} | {
+    kind: 'uncaptured';
+    usd: null;
+};
+interface RunJudgeMetadata {
+    model: string;
+    promptVersion: string;
+    /** [0,1] confidence the judge declared. Constant judge confidence
+     *  across many runs is a fallback signal (see `canary.ts`). */
+    confidence: number;
+    /** True if the judge degraded to a fallback path (rules-only,
+     *  prior-call cache, etc.). The canary uses this to alert. */
+    fallback: boolean;
+}
+/**
+ * Per-judge / per-dimension breakdown for runs scored by an ensemble of
+ * judges over a multi-dimensional rubric.
+ *
+ * The collapsed `outcome.searchScore` / `holdoutScore` carries the
+ * composite the gate uses. The full breakdown belongs here so consumers
+ * can answer "which judge disagreed?", "which dimension dragged the
+ * composite down?", and "did half the panel fail?" without re-running.
+ *
+ * `perJudge[judgeId][dim]` is the canonical source; `perDimMean` and
+ * `composite` are convenience projections — derivable but precomputed so
+ * downstream IRR primitives (`interRaterReliability`,
+ * `corpusInterRaterAgreement`) and reporters don't pay the same
+ * aggregation twice.
+ *
+ * Fail-loud discipline: judges that errored out land in `failedJudges`
+ * by id. A missing key in `perJudge` is ambiguous (silent zero vs not
+ * run); the explicit list makes a partial-failure recorded as such.
+ */
+interface JudgeScoresRecord {
+    /** Per-judge per-dimension scores. `{ "kimi-k2.6": { helpfulness: 0.8, clarity: 0.7 }, ... }`. */
+    perJudge: Record<string, Record<string, number>>;
+    /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
+    perDimMean: Record<string, number>;
+    /** Composite mean across all dims and judges. Mirrors the score
+     *  the gate sees on `outcome.searchScore` / `holdoutScore`. */
+    composite: number;
+    /** Judges that errored or returned an unparseable verdict. Recorded
+     *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
+     *  not inferred from missing keys in `perJudge`. */
+    failedJudges?: string[];
+    /** Free-form notes the judges emitted (joined across judges or
+     *  first-judge only — consumer's choice). */
+    notes?: string;
+}
+interface RunOutcome {
+    /** Score on the search/optimization split. Optional because a
+     *  holdout-only evaluation only fills `holdoutScore`. */
+    searchScore?: number;
+    /** Score on the held-out split. Optional because a search-only run
+     *  only fills `searchScore`. At least one must be present. */
+    holdoutScore?: number;
+    /** Bag of any other metric the run produced — judge dimensions,
+     *  pass/fail counters, latency stats, etc. Numeric only — keeps
+     *  reporters honest. */
+    raw: Record<string, number>;
+    /** Per-judge / per-dim breakdown. Consumers writing ensemble
+     *  judgements populate this; substrate primitives like
+     *  `interRaterReliability` and `corpusInterRaterAgreement` accept
+     *  these records as input. Optional — single-judge or scalar-only
+     *  runs leave it unset. */
+    judgeScores?: JudgeScoresRecord;
+    /** Authenticity / realness verdict — did the run build the REAL thing on the
+     *  intended infra, or fake it (see `./authenticity`)? Optional: only domains
+     *  with an authenticity config populate it. Carried in the corpus so the
+     *  flywheel / off-policy learning can optimize for real completion, not gamed
+     *  pass-rate. `score` is 0-1; `gated` is the anti-Goodhart flag — a gated run
+     *  must not count as a real success regardless of `score`. */
+    realness?: {
+        score: number;
+        gated: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Mandatory paper-grade fields for a single evaluation run. Optional
+ * fields are extension points; mandatory fields throw if missing.
+ *
+ * Hash discipline:
+ *   - `promptHash` is the sha256 of the EFFECTIVE prompt sent to the
+ *     model (after any steering bundle merge).
+ *   - `configHash` is the sha256 of the effective run config (model,
+ *     temperature, tools, judges, splits). The pair (promptHash,
+ *     configHash) uniquely identifies an experiment cell.
+ *
+ * Model snapshot discipline:
+ *   - `model` MUST encode a snapshot version. Bare aliases like
+ *     `claude-sonnet-4` or `gpt-4o` are banned — they remap silently.
+ *     Use `claude-sonnet-4-6@2025-04-15` or `gpt-4o-2024-11-20`.
+ */
+interface RunRecord {
+    /** UUID for the run. */
+    runId: string;
+    /** Logical experiment grouping (a treatment vs a baseline within
+     *  the same sweep should share `experimentId`). */
+    experimentId: string;
+    /** Stable identifier for the candidate (variant) being run. The
+     *  promotion gate compares two `candidateId`s on matched items. */
+    candidateId: string;
+    /** RNG seed for the run. Always recorded — silent re-seeding is
+     *  the most common cause of non-reproducible numbers. */
+    seed: number;
+    /** Model identifier WITH snapshot version. */
+    model: string;
+    /** sha256 of the effective prompt (post-steering). */
+    promptHash: string;
+    /** sha256 of the effective config. */
+    configHash: string;
+    /** Git SHA the harness was run from. */
+    commitSha: string;
+    /** End-to-end wall-clock duration in milliseconds. */
+    wallMs: number;
+    /** Time spent queued before execution started, if known. */
+    queueMs?: number;
+    /** Total USD cost. Mandatory — runs without a cost number are
+     *  unbounded by definition and must not be admitted into the gate.
+     *  `0` is retained as the compatibility sentinel for an uncaptured amount;
+     *  inspect `costProvenance` before treating it as observed. */
+    costUsd: number;
+    /** Observed, model-priced estimate, or genuinely uncaptured USD amount.
+     *  Optional only so existing serialized RunRecords remain valid. */
+    costProvenance?: RunCostProvenance;
+    /** Token usage breakdown. */
+    tokenUsage: RunTokenUsage;
+    /** Judge-side metadata, if a judge was used. */
+    judgeMetadata?: RunJudgeMetadata;
+    /** Per-split scores + raw bag. */
+    outcome: RunOutcome;
+    /** Canonical, cross-agent failure class drawn from the shared
+     *  `FAILURE_CLASSES` taxonomy. This is the aggregation key that makes
+     *  "which failure dominates across the whole fleet" answerable in ONE
+     *  vocabulary — every agent classifies against the same enum. Producers
+     *  set it via the substrate classifier; leave unset only when the failure
+     *  genuinely can't be classified. */
+    failureClass?: FailureClass;
+    /** Free-form domain-specific failure detail, scoped UNDER `failureClass`
+     *  (e.g. failureClass='tool_recovery_failure', failureMode='forge_build_unsatisfied').
+     *  The within-agent drill-down; `failureClass` is the cross-agent key. */
+    failureMode?: string;
+    /** Which split this run was drawn from. */
+    splitTag: RunSplitTag;
+    /**
+     * Stable scenario identifier the run was scored against. Optional for
+     * backwards compatibility, but **strongly recommended**: every primitive
+     * that pairs runs by scenario (preferences, paired stats, BT tournament)
+     * keys on this. The campaign artifact populates it canonically; legacy
+     * runs without it fall back to inference from `outcome.raw.scenario_id`
+     * or `experimentId`.
+     */
+    scenarioId?: string;
+    /**
+     * Canonical identity for the agent profile cell that produced this row:
+     * profile artifact hash plus optional harness/model/prompt/reporting
+     * dimensions. Use `agentProfile.cellId` to group persona sweeps and
+     * longitudinal reports by the complete source profile, not by a loose
+     * candidate label or opaque config hash.
+     */
+    agentProfile?: AgentProfileCell;
+}
+
+/**
+ * Shared types for the trace-analyst module.
+ *
+ * Wire format. The store interface speaks `OtlpSpanLike` rows — one JSONL
+ * line per span, OTLP-shaped. We do NOT depend on a specific tracing
+ * vendor at the type level. Adapter
+ * layers map upstream shapes onto this interface.
+ *
+ * Design constraint. Every read operation that can return arbitrary
+ * payload must carry a byte budget so the agent's tool result stays
+ * bounded regardless of input trace size. Oversized responses
+ * substitute a deterministic summary instead of bytes — see
+ * `ViewTraceOversized`.
+ */
+/** OTLP span kind (subset we actually use). */
+type TraceAnalystSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'GUARDRAIL' | 'SPAN' | 'UNKNOWN';
+type TraceAnalystSpanStatus = 'OK' | 'ERROR' | 'UNSET';
+/** Subset of OTLP span fields the analyst exposes to the agent. The
+ *  store's job is to project upstream's full span shape down to this
+ *  view — the analyst never sees vendor extensions directly. */
+interface TraceAnalystSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    kind: TraceAnalystSpanKind;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    status: TraceAnalystSpanStatus;
+    status_message?: string;
+    service_name: string | null;
+    agent_name: string | null;
+    model_name: string | null;
+    tool_name: string | null;
+    /** Raw JSON-serialisable attribute map. May contain large strings;
+     *  callers must respect the per-attribute byte cap. */
+    attributes: Record<string, unknown>;
+}
+interface TraceAnalystTraceSummary {
+    trace_id: string;
+    service_name: string | null;
+    agent_name: string | null;
+    span_count: number;
+    has_errors: boolean;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    raw_jsonl_bytes: number;
+    models: string[];
+    tools: string[];
+}
+interface TraceAnalystFilters {
+    /** Restrict to traces that contain at least one error span. */
+    has_errors?: boolean;
+    /** Match if any span's `service.name` is in this list. */
+    service_names?: string[];
+    /** Match if any span's `agent.name` is in this list. */
+    agent_names?: string[];
+    /** Match if any LLM span's `llm.model_name` is in this list. */
+    model_names?: string[];
+    /** Match if any tool span's `tool.name` is in this list. */
+    tool_names?: string[];
+    /** ISO-8601 lower bound on the trace's earliest start time. */
+    start_time_after?: string;
+    /** ISO-8601 upper bound on the trace's earliest start time. */
+    start_time_before?: string;
+    /** Single regex applied to raw JSONL bytes for the trace. Opt-in;
+     *  expensive on large datasets. Use the indexed filters above first. */
+    regex_pattern?: string;
+}
+/** One distinct error signature across the dataset — the deterministic unit of
+ *  failure coverage. Signatures normalize volatile tokens (digits, hex/uuids,
+ *  paths, durations) out of the span `status_message` so semantically identical
+ *  failures collapse into one cluster. An analyst that accounts for every
+ *  cluster has, by construction, covered every distinct failure mode. */
+interface ErrorCluster {
+    /** Normalized status_message — the cluster key. */
+    signature: string;
+    /** A verbatim, un-normalized exemplar message (for exact-string citation). */
+    status_message_sample: string;
+    /** The span name that most often carries this signature, if any. */
+    span_name: string | null;
+    /** The tool that most often carries this signature, if any. */
+    tool_name: string | null;
+    trace_count: number;
+    span_count: number;
+    /** trace_count / total error traces in the matched set (0..1). */
+    prevalence: number;
+    /** Real trace ids carrying this signature (capped), passable to view/search. */
+    exemplar_trace_ids: string[];
+    /** Real span ids carrying this signature (capped). */
+    exemplar_span_ids: string[];
+}
+interface DatasetOverview {
+    total_traces: number;
+    raw_jsonl_bytes: number;
+    services: string[];
+    agents: string[];
+    models: string[];
+    tool_names: string[];
+    /** Up to 20 real trace ids the agent may pass to view/search tools. */
+    sample_trace_ids: string[];
+    errors: {
+        trace_count: number;
+        span_count: number;
+    };
+    /** The COMPLETE deterministic error-signature population, sorted by
+     *  trace_count desc. This is the failure-coverage checklist: an analysis is
+     *  complete only when every cluster here is accounted for. Empty when the
+     *  matched set has no error spans. */
+    error_clusters: ErrorCluster[];
+    time_range: {
+        earliest: string;
+        latest: string;
+    } | null;
+}
+interface QueryTracesPage {
+    traces: TraceAnalystTraceSummary[];
+    total: number;
+    has_more: boolean;
+}
+/** Full-trace view. When the response would exceed the per-call byte
+ *  budget, `oversized` is populated INSTEAD of `spans` so the agent
+ *  knows to switch to `searchTrace` / `viewSpans`. */
+interface ViewTraceResult {
+    trace_id: string;
+    spans?: TraceAnalystSpan[];
+    oversized?: ViewTraceOversized;
+}
+interface ViewTraceOversized {
+    span_count: number;
+    /** Names with their counts, sorted desc. Capped at 20 entries. */
+    top_span_names: Array<[string, number]>;
+    /** Largest single span body (bytes after attribute-cap projection). */
+    span_response_bytes_max: number;
+    error_span_count: number;
+}
+interface ViewSpansResult {
+    trace_id: string;
+    spans: TraceAnalystSpan[];
+    /** Number of requested span ids that were not found in the trace. */
+    missing_span_ids: string[];
+    /** Number of attribute fields truncated to fit the per-attribute cap. */
+    truncated_attribute_count: number;
+}
+interface SpanMatchRecord {
+    trace_id: string;
+    span_id: string;
+    span_name: string;
+    span_kind: TraceAnalystSpanKind;
+    /** JSON pointer-style path to the matched value, e.g.
+     *  `attributes."llm.input_messages"[2].content`. */
+    attribute_path: string;
+    matched_text: string;
+    context_before: string;
+    context_after: string;
+    match_offset: number;
+}
+interface SearchTraceResult {
+    trace_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+interface SearchSpanResult {
+    trace_id: string;
+    span_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+
+/**
+ * `TraceAnalysisStore` — read-side interface the trace-analyst calls
+ * through. Six operations, all bounded:
+ *
+ *   - `getOverview(filters?)` — dataset rollup + sample trace ids.
+ *   - `queryTraces(filters?, limit, offset)` — paginated summaries.
+ *   - `countTraces(filters?)` — cheap count without materialisation.
+ *   - `viewTrace(trace_id, perAttrCap)` — full span list, oversized → summary.
+ *   - `viewSpans(trace_id, span_ids, perAttrCap)` — surgical span fetch.
+ *   - `searchTrace(trace_id, regex, max_matches)` — bounded regex hits.
+ *   - `searchSpan(trace_id, span_id, regex, max_matches)` — single-span search.
+ *
+ * Multiple implementations ship in the core (`OtlpFileTraceStore`).
+ * Downstream callers can supply their own — e.g. a DuckDB-backed
+ * adapter or an in-memory adapter for tests — by implementing this
+ * interface.
+ *
+ * Filters compose with AND semantics. Empty/undefined fields impose
+ * no constraint. `regex_pattern` is the only opt-in raw-bytes scan —
+ * implementations may skip it via `count`/`overview` when not set.
+ */
+
+interface TraceAnalysisStore {
+    getOverview(filters?: TraceAnalystFilters): Promise<DatasetOverview>;
+    queryTraces(opts: {
+        filters?: TraceAnalystFilters;
+        limit: number;
+        offset?: number;
+    }): Promise<QueryTracesPage>;
+    countTraces(filters?: TraceAnalystFilters): Promise<number>;
+    viewTrace(opts: {
+        trace_id: string;
+        /** Override per-attribute byte cap. Defaults to discovery budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewTraceResult>;
+    viewSpans(opts: {
+        trace_id: string;
+        span_ids: readonly string[];
+        /** Override per-attribute byte cap. Defaults to surgical budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewSpansResult>;
+    searchTrace(opts: {
+        trace_id: string;
+        regex_pattern: string;
+        /** Hard cap on matches returned. Default 50. */
+        max_matches?: number;
+    }): Promise<SearchTraceResult>;
+    searchSpan(opts: {
+        trace_id: string;
+        span_id: string;
+        regex_pattern: string;
+        max_matches?: number;
+    }): Promise<SearchSpanResult>;
+}
+
+type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
+interface CostUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens?: number;
+}
+interface CostCallBase {
+    callId: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    model: string;
+    maximumCostUsd?: number;
+    tags?: Record<string, string>;
+    timestamp: number;
+}
+interface CostReceipt extends CostCallBase, CostUsage {
+    status: 'settled';
+    costUsd: number;
+    costUnknown: boolean;
+    usageUnknown?: boolean;
+    pricing?: {
+        inputUsdPerThousand: number;
+        outputUsdPerThousand: number;
+    };
+    actualCostUsd?: number;
+    error?: string;
+}
+interface CostReceiptInput extends CostUsage {
+    model: string;
+    actualCostUsd?: number;
+    costUnknown?: boolean;
+    usageUnknown?: boolean;
+}
+type MaximumCharge = {
+    externallyEnforcedMaximumUsd: number;
+} | ({
+    model: string;
+} & CostUsage);
+interface RunPaidCallInput<T> {
+    callId?: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    /** Used before a provider receipt exists and on failures without one. */
+    model?: string;
+    tags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
+    maximumCharge?: MaximumCharge;
+    /** `callId` can be forwarded as the provider's idempotency key. */
+    execute(signal: AbortSignal, callId: string): Promise<T>;
+    receipt(value: T): CostReceiptInput;
+    receiptFromError?(error: Error): CostReceiptInput | undefined;
+}
+type PaidCallResult<T> = {
+    succeeded: true;
+    callId: string;
+    value: T;
+    receipt: CostReceipt;
+} | {
+    succeeded: false;
+    callId?: string;
+    error: Error;
+    receipt?: CostReceipt;
+};
+interface ChannelRollup {
+    channel: CostChannel;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    costUsd: number;
+    unpricedCalls: number;
+    unknownUsageCalls: number;
+}
+interface CostLedgerSummary {
+    totalCalls: number;
+    pendingCalls: number;
+    unresolvedCalls: number;
+    reservedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    totalCostUsd: number;
+    byChannel: ChannelRollup[];
+    unpricedModels: string[];
+    fullyPriced: boolean;
+    usageComplete: boolean;
+    accountingComplete: boolean;
+    incompleteReasons: string[];
+}
+interface CostLedgerFilter {
+    channel?: CostChannel;
+    phase?: string;
+    tags?: Record<string, string>;
+}
+/** Append-only storage. `append` must atomically reject stale revisions. */
+interface CostLedgerPersistence {
+    read(): {
+        revision: string;
+        events: string;
+    };
+    append(expectedRevision: string, event: string): string | undefined;
+}
+interface CostLedgerOptions {
+    costCeilingUsd?: number;
+    persistence?: CostLedgerPersistence;
+    /** Import already-settled receipts without admitting new paid work. */
+    receipts?: readonly CostReceipt[];
+}
+/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
+declare class CostLedger {
+    private readonly records;
+    private readonly activeCallIds;
+    private readonly lateCallIds;
+    private completedTasks;
+    private revision;
+    private costLimitPersisted;
+    readonly costCeilingUsd?: number;
+    private readonly persistence?;
+    constructor(input?: number | CostLedgerOptions);
+    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
+    /** Settle a call left pending by a crashed process after reconciling with the provider. */
+    reconcile(callId: string, observed: CostReceiptInput, options?: {
+        error?: string;
+    }): CostReceipt;
+    list(filter?: CostLedgerFilter): CostReceipt[];
+    summary(filter?: CostLedgerFilter): CostLedgerSummary;
+    markCompleted(count?: number): void;
+    costPerCompletedTask(): number | null;
+    private execute;
+    private captureLateOutcome;
+    private commitOutcome;
+    private captureFailure;
+    private commitReceipt;
+    private resolveMaximum;
+    private hasIncompleteSettledCall;
+    private appendRecord;
+    private ensureCostLimitPersisted;
+    private appendEvent;
+}
+
+/**
+ * RawProviderSink — first-class persistence for the actual HTTP-level
+ * request/response bodies of every LLM provider call.
+ *
+ * Why this is a separate sink from the structured `LlmSpan`:
+ *
+ *   - `LlmSpan` records the *intent* — model name, messages, output text,
+ *     usage. It's what dashboards read; it's NOT enough for forensics.
+ *   - When a downstream consumer reports "the verifier used the wrong route"
+ *     or "tokens look right but reasoning was missing," the only way to
+ *     answer is the raw HTTP body. Span fields can lie (a proxy can echo
+ *     a different `model` value than what actually answered); the raw
+ *     response is ground truth.
+ *
+ * Default behaviour: opt-in. Pass `rawSink` to `LlmClientOptions` (or the
+ * matrix runner / BuilderSession sets it up automatically) and every
+ * request, response, and error is recorded — including retries, with the
+ * attempt index attached so a flaky call's full event chain is recoverable.
+ *
+ * Redaction is enforced at sink time. The default redactor strips
+ * `Authorization`, `X-Api-Key`, `X-Auth-Token`, `Cookie` headers and any
+ * payload field whose key matches `apiKey | api_key | bearer | password |
+ * secret | token` (case-insensitive). Override via the sink constructor or
+ * the per-call `redactor`. The `redactedFields` array on the persisted
+ * event lets a reviewer see what was stripped without exposing the values.
+ */
+type RawProviderDirection = 'request' | 'response' | 'error';
+interface RawProviderEvent {
+    /** Stable id. Generated by the sink if omitted. */
+    eventId: string;
+    /** Trace context populated by `LlmClient` when the call is wrapped in a span. */
+    runId?: string;
+    spanId?: string;
+    /**
+     * Logical provider name. Free-form so callers can use whatever id matches
+     * their topology (`'openai'`, `'anthropic'`, `'tangle-router'`, …). When
+     * omitted, derived from `baseUrl` in `LlmClientOptions`.
+     */
+    provider: string;
+    model: string;
+    /** Endpoint path, e.g. `'/v1/chat/completions'`. */
+    endpoint: string;
+    /** Base URL used for the call (already-normalised — no trailing slash). */
+    baseUrl: string;
+    /** 0-indexed retry attempt. The first attempt is 0; a retried call gets 1, 2, … */
+    attemptIndex: number;
+    direction: RawProviderDirection;
+    /** Unix ms. */
+    timestamp: number;
+    /** Wall-clock duration of the call leg. Set on `response` and `error` events; null on `request`. */
+    durationMs?: number;
+    statusCode?: number;
+    requestHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseHeaders?: Record<string, string>;
+    responseBody?: unknown;
+    /** Set on `direction: 'error'` events. */
+    errorMessage?: string;
+    /** Field paths the redactor stripped from this event ('header:Authorization', 'body.apiKey', …). */
+    redactedFields: string[];
+}
+interface RawProviderSinkFilter {
+    runId?: string;
+    spanId?: string;
+    direction?: RawProviderDirection;
+    attemptIndex?: number;
+}
+interface RawProviderSink {
+    record(event: RawProviderEvent): Promise<void>;
+    /** Optional listing — implementations that durably persist (file, db) should support this. */
+    list?(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+    /** Optional teardown for backed implementations. */
+    close?(): Promise<void>;
+}
+type ProviderRedactor = (event: RawProviderEvent) => RawProviderEvent;
+
+/**
+ * LLM client with graceful degrade.
+ *
+ * OpenAI-compatible `/v1/chat/completions` client with:
+ *   - Exponential-backoff retry on 429 + 5xx gateway errors (502/503/504).
+ *   - Retry on transient network errors (fetch failed, AbortError, ECONNRESET).
+ *   - Graceful json_schema → json_object degrade on 400 with schema-reject body.
+ *   - Fenced-JSON stripping (```json ... ```) for models that wrap structured output.
+ *   - Configurable base URL + api key / bearer, works with LiteLLM proxies, OpenAI
+ *     directly, cli-bridge subscriptions, and any router that speaks the spec.
+ *
+ * Usage:
+ *   const { value, result } = await callLlmJson<MyType>(
+ *     { model: 'gpt-4o', messages: [...], jsonSchema: { name: 'x', schema: {...} } },
+ *     { baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.KEY },
+ *   )
+ *
+ * This is THE llm-calling seam for agent-eval primitives that need structured
+ * output (semantic concept judge, reviewer directives, critic scores). Primitives
+ * that need free-form text use `callLlm` and parse output themselves.
+ */
+
+interface LlmMessage {
+    role: 'system' | 'user' | 'assistant';
+    /**
+     * Either a plain text content string OR a multimodal content array
+     * (text + image_url parts) for vision-capable models.
+     */
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+            detail?: 'auto' | 'low' | 'high';
+        };
+    }>;
+}
+interface LlmCallRequest {
+    model: string;
+    messages: LlmMessage[];
+    /** Optional JSON-mode response format (response_format: json_object). */
+    jsonMode?: boolean;
+    /** Optional structured output via JSON Schema. Falls back to json_object on 400. */
+    jsonSchema?: {
+        name: string;
+        schema: Record<string, unknown>;
+    };
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-call timeout, default 300s. */
+    timeoutMs?: number;
+}
+interface LlmUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** False when the provider omitted or malformed prompt/completion usage. */
+    captured?: boolean;
+    /** Proxies populate this when prompt caching is on. */
+    cachedPromptTokens?: number;
+}
+interface LlmCallResult {
+    /** The text content of the first choice. Empty string if none. */
+    content: string;
+    usage: LlmUsage;
+    /**
+     * Cost in USD. Pulled from proxy's `_response_cost` field when present;
+     * `null` when neither the proxy nor the caller can derive it.
+     */
+    costUsd: number | null;
+    /** Model name actually used (echoed from response). */
+    model: string;
+    /** Wall-clock duration of the HTTP call (last attempt, if retried). */
+    durationMs: number;
+    /**
+     * `finish_reason` echoed from the first choice (`stop`, `length`,
+     * `content_filter`, `tool_calls`, ...). `null` when the provider omits it.
+     * Exposed so a free-form `callLlm` caller CAN detect a truncated answer
+     * (`length`) instead of treating a cut-off completion as complete. Note:
+     * `callLlm` does not itself reject on it — acting on this signal is the
+     * caller's responsibility (in-repo free-form drivers do not yet enforce it).
+     */
+    finishReason?: string | null;
+    /**
+     * True when `content.trim()` is empty. An empty completion is a silent zero
+     * for free-form `callLlm` callers; this flag is the signal a caller can
+     * inspect to fail loud rather than proceed on an empty string. `callLlm`
+     * surfaces it but does not throw on it.
+     */
+    contentEmpty?: boolean;
+    /** Raw response body. */
+    raw: Record<string, unknown>;
+}
+type LlmCallMetadata = Pick<LlmCallResult, 'usage' | 'costUsd' | 'model' | 'durationMs'>;
+interface LlmClientOptions {
+    /** Base URL (without trailing slash). Must end at the `/v1` prefix. */
+    baseUrl?: string;
+    /** Bearer token — either `apiKey` or `bearer` populates `Authorization: Bearer ...`. */
+    apiKey?: string;
+    bearer?: string;
+    /** Override for the `Authorization` header (e.g. `X-Auth: ...`). Takes precedence over apiKey/bearer. */
+    authHeader?: {
+        name: string;
+        value: string;
+    };
+    /** Stable provider idempotency key, reused across retries of this logical call. */
+    idempotencyKey?: string;
+    /** Default timeout in ms. Per-call can override. */
+    defaultTimeoutMs?: number;
+    /**
+     * Caller-supplied abort signal — e.g. a campaign-wide cancel. Linked to
+     * each attempt's per-attempt timeout controller, so aborting it cancels
+     * the in-flight fetch. A caller abort is FATAL: it is not retried even
+     * though an AbortError otherwise matches the transient patterns.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cross-attempt wall-clock budget in ms, measured from the first attempt.
+     * Before launching each attempt the loop checks the remaining budget and
+     * stops retrying once it is exhausted, rather than waiting the full
+     * per-attempt timeout on every retry. Bounds total time independent of
+     * total attempts × `timeoutMs`.
+     */
+    deadlineMs?: number;
+    /** Total provider attempts. Legacy option name; default 3 (1 initial + 2 retries). */
+    maxRetries?: number;
+    /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
+    fetch?: typeof fetch;
+    /**
+     * Optional raw HTTP capture sink. When provided, every request, response,
+     * and error (across all retry attempts) is recorded to the sink, with auth
+     * headers and credential-shaped body fields redacted by default. This is
+     * the layer-1 forensics primitive: structured `LlmSpan`s record intent,
+     * raw events record what actually crossed the wire.
+     */
+    rawSink?: RawProviderSink;
+    /**
+     * Logical provider id attached to raw events. When omitted, derived from
+     * `baseUrl` via `providerFromBaseUrl`.
+     */
+    provider?: string;
+    /** Trace context attached to raw events; populated by emitter-aware callers. */
+    traceContext?: {
+        runId?: string;
+        spanId?: string;
+    };
+    /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
+    redactor?: ProviderRedactor;
+}
+
+/**
+ * ChatClient — the single LLM abstraction analysts call.
+ *
+ * agent-eval already ships an `LlmClient` (OpenAI-compatible, retry,
+ * graceful JSON-schema degrade) and judges that talk to `TCloud`. Two
+ * mixed patterns force every analyst author to pick a transport, which
+ * couples analyst code to runtime concerns (cli-bridge vs router vs
+ * sandbox-sdk) it shouldn't know about.
+ *
+ * `ChatClient` is one interface every analyst takes via `AnalystContext.chat`.
+ * The operator decides at the registry boundary which transport binds
+ * to it. Analyst code stays transport-agnostic; swapping production
+ * (sandbox-sdk) for local dev (cli-bridge) or tests (mock) is a one-
+ * line factory call.
+ *
+ * Designed to coexist: existing `LlmClient` callers and existing
+ * `TCloud`-based judges keep working untouched. New analyst code uses
+ * `ChatClient`. When old call sites migrate, they pick up budgeting,
+ * cancellation, and unified telemetry for free.
+ */
+
+/**
+ * Unified chat interface. Mirrors LlmCallRequest/Result so the OpenAI-
+ * compatible mental model stays. Two methods: a one-shot `chat()` and
+ * an `streamChat()` for future agentic loops (not yet exposed).
+ */
+interface ChatClient {
+    /** Display name of the bound transport — included in telemetry. */
+    readonly transport: ChatTransport;
+    /** Default model when caller omits — operators bind this per environment. */
+    readonly defaultModel?: string;
+    /** Total provider attempts this transport can make for one chat call. */
+    readonly maximumAttempts?: number;
+    /** Implementations must enforce `req.maxTokens` when it is present. */
+    chat(req: ChatRequest, opts?: ChatCallOpts): Promise<ChatResponse>;
+}
+type ChatTransport = 'router' | 'sandbox-sdk' | 'cli-bridge' | 'direct-provider' | 'mock';
+interface ChatRequest extends Omit<LlmCallRequest, 'model'> {
+    /** Optional — falls back to ChatClient.defaultModel. */
+    model?: string;
+}
+type ChatResponse = LlmCallResult;
+interface ChatCallOpts {
+    /** Cancel the in-flight request. */
+    signal?: AbortSignal;
+    /** Hard USD ceiling for this single call (informational; the underlying transport may not enforce). */
+    maxCostUsd?: number;
+    /** Correlation tag carried into request headers when the transport allows. */
+    correlationId?: string;
+    /** Stable provider idempotency key for retries/redrives of one paid call. */
+    idempotencyKey?: string;
+}
+
+/**
+ * Analyst contract — the missing orchestration layer over agent-eval's
+ * existing analyzers (analyzeTraces, MultiLayerVerifier, RunCritic,
+ * SemanticConceptJudge, JudgeFn, ...).
+ *
+ * Each existing primitive returns its own output shape. The Analyst
+ * contract is the single envelope every primitive lifts into, so a
+ * registry can run N analysts against a run and a single renderer can
+ * compose findings without knowing which analyzer produced them.
+ *
+ * The contract is intentionally domain-agnostic: nothing here knows
+ * about code, voice, RAG, or any particular agent stack. Analysts
+ * declare what INPUT KIND they need (a trace store, an artifact dir,
+ * a RunRecord, a JudgeInput, or `custom`), and the registry routes
+ * the matching input from `AnalystRunInputs`.
+ */
+
+/**
+ * Unified envelope every analyst emits. Schema-versioned so renderers
+ * and time-series diffs survive future field additions.
+ */
+interface AnalystFinding {
+    schema_version: '1.0.0';
+    /**
+     * Stable hash over identity-defining fields (analyst_id + canonical
+     * claim + area + optional subject). Two findings from two runs that
+     * "are the same finding" share this id — that's what `diffFindings`
+     * uses to compute appeared/disappeared sets across runs.
+     */
+    finding_id: string;
+    analyst_id: string;
+    produced_at: string;
+    severity: AnalystSeverity;
+    /**
+     * Coarse classification. Renderers group by this. Free-form so
+     * domain-specific analysts can introduce categories without a
+     * schema change ('agent-reasoning', 'verification', 'cost',
+     * 'tool-use', 'safety', 'latency', 'data-quality', ...).
+     */
+    area: string;
+    claim: string;
+    rationale?: string;
+    evidence_refs: EvidenceRef[];
+    recommended_action?: string;
+    validation_plan?: string;
+    /** 0..1 — the analyst's own confidence. Not calibrated across analysts. */
+    confidence: number;
+    /**
+     * Optional subject the finding is about — leaf id, agent id, request
+     * id. Included in finding_id when present so per-subject findings
+     * diff cleanly across runs.
+     */
+    subject?: string;
+    /** FIREWALL provenance (docs/learning-flywheel.md): true iff this finding was
+     *  lifted from a JUDGE verdict (an acceptance score), not OBSERVED from the
+     *  agent's behavior. A judge-derived finding must NEVER be admitted as a
+     *  steering input — that is the held-out judge leaking into the loop. Set at
+     *  the lift site (createJudgeAdapter); checked by `assertNoJudgeVerdict`.
+     *  Provenance, not evidence presence, is the correct discriminator: an
+     *  evidence-less trace-analyst observation legitimately steers, while a judge
+     *  verdict that happens to cite an artifact must not. */
+    derived_from_judge?: boolean;
+    /** Analyst-private extras; renderers ignore unless they know the analyst. */
+    metadata?: Record<string, unknown>;
+}
+type AnalystSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+interface EvidenceRef {
+    /**
+     * Where the evidence lives. `span` and `event` refer to OTLP trace
+     * elements; `artifact` to a file inside the run's artifact tree;
+     * `finding` to another AnalystFinding (cross-analyst chaining);
+     * `metric` to a named scalar reading the renderer knows how to read.
+     */
+    kind: 'span' | 'event' | 'artifact' | 'finding' | 'metric';
+    uri: string;
+    excerpt?: string;
+}
+interface AnalystCost {
+    /** `deterministic` analysts MUST NOT call the LLM. */
+    kind: 'deterministic' | 'llm';
+    /** Optional declared upper bound; the registry can enforce a budget. */
+    est_usd_per_run?: number;
+    /** Models the analyst expects to use (informational). */
+    models?: string[];
+}
+interface AnalystContext {
+    runId: string;
+    /** Stable correlation id so logs from a single registry.run() share a tag. */
+    correlationId: string;
+    /** Wall-clock deadline (epoch ms). Analysts SHOULD honor for graceful cancel. */
+    deadlineMs?: number;
+    /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */
+    budgetUsd?: number;
+    /**
+     * Shared chat client. Analysts that call an LLM go through this so
+     * the operator picks transport (sandbox-sdk | router | cli-bridge |
+     * direct-provider | mock) at the registry boundary without touching
+     * analyst code.
+     */
+    chat?: ChatClient;
+    /**
+     * Findings from a prior run the operator wants the analyst to see as
+     * retrieval context. Kinds that take advantage of cross-run memory
+     * (failure-mode "I saw this cluster last run", knowledge-gap "the wiki
+     * page I asked for is still missing") render these into the actor's
+     * working set. Filtering is the operator's job: pass the slice that
+     * matches the analyst's id, or pass everything and let the kind
+     * filter. Empty / absent means no cross-run context.
+     */
+    priorFindings?: ReadonlyArray<AnalystFinding>;
+    /** Free-form runtime tags (env, host, op). Findings can echo these into metadata. */
+    tags?: Record<string, string>;
+    /** Logger callback — analysts SHOULD prefer this over console.* for testability. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Optional abort signal. Analysts SHOULD pass it through to LLM calls. */
+    signal?: AbortSignal;
+}
+
+type PolicyEditSchemaVersion = 'policy-edit/v1';
+declare const POLICY_EDIT_AXES: readonly ["carrier", "representation", "budget", "sampling", "output_contract", "tool_contract", "routing", "memory", "agent_profile", "deployment_target"];
+type PolicyEditAxis = (typeof POLICY_EDIT_AXES)[number];
+declare const POLICY_EDIT_TARGET_SURFACES: readonly ["prompt", "tool-contract", "runtime-config", "memory", "agent-profile", "code", "deployment"];
+type PolicyEditTargetSurface = (typeof POLICY_EDIT_TARGET_SURFACES)[number];
+type PolicyEditRisk = 'low' | 'medium' | 'high' | 'unknown';
+type PolicyEditGainDirection = 'increase' | 'decrease';
+type PolicyEditGainUnit = 'absolute' | 'relative' | 'percent' | 'score';
+interface PolicyEditTarget {
+    surface: PolicyEditTargetSurface;
+    /** Stable path inside the target surface, for example `system-prompt:tools`
+     * or `budget.maxTurns`. */
+    path?: string;
+    /** Optional canonical deployment identity. Store the existing cell, not a
+     * local profile shape. */
+    agentProfileCell?: AgentProfileCell;
+    /** Human label when the path is not enough for a readable audit trail. */
+    label?: string;
+}
+type PolicyEditChange = {
+    kind: 'text';
+    mode: 'append' | 'prepend' | 'replace';
+    value: string;
+    /** Required when `mode === 'replace'`; exact match only. */
+    find?: string;
+} | {
+    kind: 'json';
+    mode: 'set' | 'merge' | 'remove';
+    path: string;
+    value?: AgentProfileJson;
+};
+interface PolicyEditExpectedGain {
+    /** Metric this edit is expected to move, e.g. `holdout.composite`. */
+    metric: string;
+    direction: PolicyEditGainDirection;
+    /** Positive magnitude in the metric's native units. */
+    amount: number;
+    unit?: PolicyEditGainUnit;
+    rationale?: string;
+}
+interface PolicyEditSource {
+    findingIds: string[];
+    analystIds: string[];
+    evidenceRefs: EvidenceRef[];
+    /** Mirrors `AnalystFinding.derived_from_judge`; admission rejects it. */
+    derivedFromJudge?: boolean;
+}
+interface PolicyEdit {
+    schemaVersion: PolicyEditSchemaVersion;
+    editId: string;
+    axis: PolicyEditAxis;
+    target: PolicyEditTarget;
+    change: PolicyEditChange;
+    claim: string;
+    expectedGain: PolicyEditExpectedGain;
+    confidence: number;
+    risk: PolicyEditRisk;
+    source: PolicyEditSource;
+    rationale?: string;
+    validationPlan?: string;
+    metadata?: Record<string, unknown>;
+}
+declare const POLICY_EDIT_CANDIDATE_RECORD_SCHEMA: "tangle.policy-edit-candidate.v1";
+/** JSON-safe attribution carried with a measured candidate and its scores. */
+interface PolicyEditCandidateRecord {
+    schema: typeof POLICY_EDIT_CANDIDATE_RECORD_SCHEMA;
+    policyEdit: PolicyEdit;
+}
+interface FindingToPolicyEditOptions {
+    expectedGain?: PolicyEditExpectedGain | ((finding: AnalystFinding) => PolicyEditExpectedGain | null | undefined);
+    risk?: PolicyEditRisk | ((finding: AnalystFinding) => PolicyEditRisk);
+    defaultAxis?: PolicyEditAxis;
+    defaultTargetSurface?: PolicyEditTargetSurface;
+}
+interface PolicyEditAdmissionOptions {
+    minScore?: number;
+    minExpectedGain?: number;
+    allowHighRisk?: boolean;
+    requireEvidence?: boolean;
+}
+interface PolicyEditAdmission {
+    edit: PolicyEdit;
+    decision: 'admit' | 'reject';
+    score: number;
+    reasons: string[];
+}
+declare function validatePolicyEditCandidateRecord(input: unknown): PolicyEditCandidateRecord;
+
+/**
+ * Pass A substrate types — `runCampaign` is the one primitive every
+ * eval flow composes from. Three contracts in this file:
+ *
+ *   - `Scenario`            input set
+ *   - `DispatchFn`          how to run one scenario → artifact
+ *   - `CampaignResult`      defined output schema (the contract downstream tools depend on)
+ *
+ * Three more lifted from earlier substrate work (re-exported):
+ *
+ *   - `JudgeConfig`         pluggable dimensional scorer (0.38)
+ *   - `Mutator`             optimization-loop surface mutator
+ *   - `Gate`                promotion gate (`HeldOutGate` and friends adapt to this)
+ *
+ * No new architecture vs 0.38 — Pass A formalizes the shapes so consumers
+ * can build dashboards / CI gates / regression diffs against a stable schema.
+ */
+
+/** Stable identifier + kind tag for any scenario. Consumers
+ *  extend with their per-domain payload (persona, task, requirement, ...). */
+interface Scenario {
+    id: string;
+    kind: string;
+    tags?: string[];
+}
+/** Context handed to every dispatch invocation. Scoped — every
+ *  trace/span carries the cellId, every artifact write lands under the cell's
+ *  artifact root, the cost meter accumulates per cell. */
+interface DispatchContext {
+    cellId: string;
+    rep: number;
+    generation?: number;
+    seed: number;
+    signal: AbortSignal;
+    trace: CampaignTraceWriter;
+    artifacts: CampaignArtifactWriter;
+    cost: CampaignCostMeter;
+    /** Populated when this run is part of a multi-cycle improvement loop. */
+    cycleId?: string;
+    /** Populated when the substrate resumed from a prior cache hit. */
+    resumedFrom?: string;
+    /**
+     * Opaque placement key supplied by `RunCampaignOptions.cellPlacement`.
+     * The substrate forwards it through unchanged; placement-aware Dispatch
+     * implementations (e.g. `httpDispatch` from `/adapters/http`) read it to
+     * route the cell to the right worker / region / sandbox. `undefined`
+     * when no placement strategy is configured.
+     */
+    placement?: string;
+}
+/** One function: scenario + ctx → artifact. Dispatcher chooses
+ *  whether to call `runMultishot`, `runLoop`, raw `streamPrompt`, anything. */
+type DispatchFn<TScenario extends Scenario, TArtifact> = (scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+/** One session within a multi-session journey. Dispatch is
+ *  invoked once per session in order; state from prior session's artifact
+ *  is exposed via `ctx.priorSessionArtifact`. */
+interface SessionScript<TScenario, TArtifact> {
+    id: string;
+    intent: string;
+    maxTurns?: number;
+    /** When true, knowledge accumulated this session persists to next. */
+    affectsKnowledge?: boolean;
+    /** Optional per-session persona evolution — called after the session
+     *  resolves. Returns the persona shape used by the NEXT session. */
+    evolveAfterSession?: (artifact: TArtifact, sessionIndex: number, scenario: TScenario) => TScenario;
+}
+interface JudgeDimension {
+    /** JSON field name + score key. */
+    key: string;
+    /** Description shown in the judge's user prompt. */
+    description: string;
+}
+/** Pluggable dimensional scorer. `score` is the contract:
+ *  given an artifact + scenario, return a `JudgeScore`. This is deliberately a
+ *  function, not a fixed LLM-prompt shape — real consumers judge with
+ *  ensembles, deterministic checks, or a single LLM call, and the substrate
+ *  must not constrain that. The `llmJudge()` helper builds a `score` that does
+ *  one LLM call for the common case. `appliesTo` lets a judge run only on
+ *  scenarios that match (e.g. a legal-citation judge only on legal scenarios). */
+interface JudgeConfig<TArtifact, TScenario extends Scenario = Scenario> {
+    name: string;
+    dimensions: JudgeDimension[];
+    /** Stable scoring revision used by campaign resume and verdict caches.
+     * Built-in judges derive this from their prompt, model, and rubric. Custom
+     * judges should set it when closure state can change without changing code. */
+    judgeVersion?: string;
+    /** Score one artifact. Throw on failure — a thrown judge is recorded as a
+     *  failed cell, never silently folded into a zero. */
+    score(input: {
+        artifact: TArtifact;
+        scenario: TScenario;
+        signal: AbortSignal;
+        /** Shared run spend account and receipt attribution phase. */
+        costLedger?: CostLedger;
+        costPhase?: string;
+        costTags?: Record<string, string>;
+    }): JudgeScore | Promise<JudgeScore>;
+    appliesTo?: (scenario: TScenario) => boolean;
+}
+/** The canonical judge verdict shape — one declaration, shared by campaign
+ *  judges and the multishot judge runner (which re-exports this type).
+ *
+ *  Scale is PRODUCER-DEFINED: campaign convention is [0,1]; the legacy
+ *  multishot runner emits 0-10. Cross-scale comparison must go through
+ *  `detectScale` (src/campaign/gates/statistical-heldout.ts, used by
+ *  promotion-policy) — never renormalize a producer's values in place, as
+ *  downstream thresholds (`composite >= 5` in multishot/matrix.ts, live-soak
+ *  `>= 7` gates) key on the producer's native scale. */
+interface JudgeScore {
+    dimensions: Record<string, number>;
+    composite: number;
+    notes: string;
+    /** Provider metadata for display and diagnostics; accounting uses CostLedger receipts. */
+    llmCall?: LlmCallMetadata;
+    /** Set when the judge itself failed (call error, unparseable output).
+     *  `composite`/`dimensions` carry no signal — aggregators MUST exclude
+     *  failed scores from means instead of folding them into zeros. */
+    failed?: true;
+    /** Ensemble extras (populated by `ensembleJudge`): max per-dimension
+     *  spread across surviving judges — the inter-rater signal. */
+    maxDisagreement?: number;
+    /** Ensemble extras: judge identities whose verdict failed. */
+    failedJudges?: string[];
+    /** Ensemble extras: each surviving judge's per-dimension scores. */
+    perJudge?: Record<string, Record<string, number>>;
+}
+/** A tier-4 code surface — a finalized candidate change to the agent's
+ *  IMPLEMENTATION, not its prompt. Produced by autoresearch (reads codebase +
+ *  trace findings → opens a worktree). `worktreeRef` locates the candidate;
+ *  the exact commits, tree, and binary-patch digest identify it. See the
+ *  improvement-tier table in `docs/design/loop-taxonomy.md`. */
+interface CodeSurface {
+    readonly kind: 'code';
+    /** Worktree path or git ref holding the candidate code change. This is a
+     *  mutable locator and is deliberately excluded from content hashes. */
+    readonly worktreeRef: string;
+    /** Human-readable ref the worktree was forked from. Not identity-bearing. */
+    readonly baseRef: string;
+    /** Exact commit the candidate was forked from. */
+    readonly baseCommit: string;
+    /** Exact tree object for `baseCommit`. */
+    readonly baseTree: string;
+    /** Exact finalized candidate commit. */
+    readonly candidateCommit: string;
+    /** Exact tree object for `candidateCommit`. */
+    readonly candidateTree: string;
+    /** Identity of the exact patch artifact. The deployable candidate bundle
+     *  carries the same descriptor plus its base64-encoded content. */
+    readonly patch: {
+        readonly format: 'git-diff-binary';
+        readonly sha256: `sha256:${string}`;
+        readonly byteLength: number;
+    };
+    /** Human summary of what changed — rendered into the auto-PR body. */
+    readonly summary?: string;
+}
+/** The mutable surface a proposer changes. Tiers (see
+ *  `docs/design/loop-taxonomy.md`):
+ *   - `string`      — tiers 1-2: system-prompt addendum / serialized tool
+ *                     config. Cheap, reversible, text-diffable.
+ *   - `CodeSurface` — tier 4: an implementation change behind a worktree ref.
+ *  Tier 3 (knowledge) is owned by agent-knowledge and rides its own adapter,
+ *  not this type. */
+type MutableSurface = string | CodeSurface;
+/** A proposer output carrying the surface AND the WHY behind
+ *  it. Reflective proposers (`gepaProposer`) parse a `{label, rationale, payload}`
+ *  from the model; without this wrapper the loop keeps only `payload` and the
+ *  rationale that motivated the change is lost — the candidate becomes
+ *  unattributable. `propose()` may return either bare `MutableSurface`s (cheap
+ *  blind mutators) or these (reflective proposers); the loop normalizes both. */
+interface ProposedCandidate {
+    surface: MutableSurface;
+    /** Short human label for the change (≤ 40 chars typical). */
+    label: string;
+    /** Why this change was proposed — which failure it targets, which
+     *  primitive it used. Survives to `GenerationCandidate.rationale` and the
+     *  emitted provenance record. */
+    rationale: string;
+    /** Structured, JSON-safe cause for this exact candidate when the proposer
+     *  can provide one. Policy edits retain the full validated edit here. */
+    candidateRecord?: PolicyEditCandidateRecord;
+}
+/** Type guard: a proposal carrying its rationale vs a bare
+ *  surface. The loop branches on this to populate `GenerationCandidate`. */
+declare function isProposedCandidate(value: MutableSurface | ProposedCandidate): value is ProposedCandidate;
+/** A non-dominated parent on the GEPA Pareto frontier — a
+ *  surface that, across the per-scenario objective vectors, no other tried
+ *  surface beats on every scenario. A candidate worse on the mean composite
+ *  but uniquely best on one hard scenario is non-dominated and survives here;
+ *  the composite-best ranking would discard the lesson it carries. The loop
+ *  computes the frontier across ALL generations and hands it to the proposer so
+ *  a reflective proposer can combine complementary lessons (GEPA, Agrawal et
+ *  al., arXiv:2507.19457). See `pareto.ts` (`paretoFrontier`). */
+interface ParetoParent {
+    surface: MutableSurface;
+    surfaceHash: string;
+    /** The objective vector: per-scenario composite (higher is better). The
+     *  axes the frontier is computed over. */
+    objectives: Record<string, number>;
+    /** Mean composite across the objective scenarios — the scalar summary used
+     *  for ordering + display, NOT for dominance. */
+    composite: number;
+    /** Generation that produced this surface (`-1` for the baseline). */
+    generation: number;
+    label?: string;
+    rationale?: string;
+}
+/** Exact measured state for the surface an optimizer is learning from.
+ *  Unlike a model-authored expected gain, every value here comes from a
+ *  completed campaign over the designed denominator. */
+interface ScoredSurfaceOutcome {
+    /** Optimization/search evidence only. Held-out results must never flow back
+     *  into a proposer through this type. */
+    split: 'search';
+    /** Generation that actually measured this surface (`-1` for the baseline). */
+    generation: number;
+    surfaceHash: string;
+    composite: number;
+    dimensions: Record<string, number>;
+    scenarios: Array<{
+        scenarioId: string;
+        composite: number;
+        notes?: string;
+    }>;
+    coverage: {
+        expectedCells: number;
+        scorableCells: number;
+    };
+}
+/** Stateless surface mutation — given findings + current
+ *  surface, return N candidate surfaces. Pure transform, no generation
+ *  awareness. Reflective-mutation and `AxGEPA` mutators conform. Wrapped by
+ *  `evolutionaryProposer` to become a `SurfaceProposer`. */
+interface Mutator<TFindings = unknown> {
+    kind: string;
+    mutate(args: {
+        findings: TFindings[];
+        currentSurface: MutableSurface;
+        populationSize: number;
+        signal: AbortSignal;
+    }): Promise<Array<MutableSurface | ProposedCandidate>>;
+}
+/** Everything a proposer may read to plan the next
+ *  batch of candidates. The first six fields are always present; the rest are
+ *  optional context the loop supplies when available, so cheap proposers
+ *  (`evolutionaryProposer`) can ignore them while a code-tier agentic generator
+ *  consumes the report + dataset to drive a coding harness.
+ *  See `docs/campaign-proposers.md`. */
+interface ProposeContext<TFindings = unknown> {
+    currentSurface: MutableSurface;
+    history: GenerationRecord[];
+    findings: TFindings[];
+    /** BREADTH: how many candidate surfaces to return this generation. */
+    populationSize: number;
+    generation: number;
+    signal: AbortSignal;
+    /** Measured baseline for this optimization run. `runOptimization` always
+     *  supplies it; optional for standalone proposer callers. */
+    baselineOutcome?: ScoredSurfaceOutcome;
+    /** Measured result for `currentSurface`, the complete global incumbent every
+     *  new candidate mutates. `runOptimization` always supplies it. */
+    incumbentOutcome?: ScoredSurfaceOutcome;
+    /** Optional analysis report produced before proposal. Opaque to the substrate:
+     *  the proposer that consumes it owns the shape. */
+    report?: unknown;
+    /** Handle to all captured data — the proposer samples traces / artifacts /
+     *  rewards here to ground its proposals. */
+    dataset?: LabeledScenarioStore;
+    /** DEPTH: max iterations the agentic generator may take per candidate.
+     *  1 = single-shot; >1 = it may iterate on its own change before handing it
+     *  back to be measured. */
+    maxImprovementShots?: number;
+    /** GEPA Pareto frontier across ALL generations so far — the non-dominated
+     *  surfaces by per-scenario objective vector. Empty/absent on generation 0
+     *  (only the baseline is scored). A reflective proposer combines the
+     *  complementary lessons of these parents (each excels on different
+     *  scenarios) into a merged candidate. Proposers doing pure single-parent
+     *  reflection may ignore it. See {@link ParetoParent}. */
+    paretoParents?: ParetoParent[];
+    /** Shared run spend account and receipt attribution phase. */
+    costLedger?: CostLedger;
+    costPhase?: string;
+    /** FIREWALL (non-negotiable): the held-out judge is write-only — its verdicts
+     *  score the chosen output and gate promotion, and are NEVER an input to
+     *  proposal/steering (else the optimizer games the acceptance axis = an
+     *  oracle). This `never`-typed field makes that a compile-time tripwire: a
+     *  proposer that tries to thread judge verdicts into the proposal will not type.
+     *  Steering may consume TRACE-OBSERVABLE signals (what the agent did) via
+     *  `findings`/`report`; it may NOT consume the judge's held-out verdict. */
+    judgeScores?: never;
+}
+/** A surface-improvement strategy. Given the current best
+ *  surface, the history of what's been tried + scored, and any external
+ *  findings, propose the next batch of candidate surfaces to measure.
+ *  Optionally decide to stop early.
+ *
+ *  The evolutionary mutator (`evolutionaryProposer`, here) and agent-runtime's
+ *  reflective / agentic generators both conform. They are proposers for the
+ *  SAME loop, not separate loops. The loop body (`runOptimization`) and the
+ *  gated promotion shell (`runImprovementLoop`) are proposer-agnostic.
+ *
+ *  This is THE optimization proposer — every optimizer is a factory
+ *  `xProposer(opts): SurfaceProposer` (`evolutionaryProposer`, `aceProposer`,
+ *  `gepaProposer`, `skillOptProposer`, `traceAnalystProposer`, `haloProposer`,
+ *  `memoryCurationProposer`, `fapoProposer`), all exported from `/campaign` and
+ *  drivable by `selfImprove({ proposer })`. Not to be confused with the
+ *  behavior-fuzzing `MutationProposer` (`fuzz/types`), a scenario generator for
+ *  a different loop.
+ */
+interface SurfaceProposer<TFindings = unknown> {
+    kind: string;
+    /** Plan: propose N candidate surfaces for the next generation. A proposer
+     *  may return bare `MutableSurface`s or `ProposedCandidate`s that carry the
+     *  `{label, rationale}` motivating the change — the loop threads the
+     *  rationale into `GenerationCandidate` and the emitted provenance. */
+    propose(ctx: ProposeContext<TFindings>): Promise<Array<MutableSurface | ProposedCandidate>>;
+    /** Decide: stop early when the proposer judges the search converged or
+     *  exhausted. Default (omitted) runs all `maxGenerations`. */
+    decide?(args: {
+        history: GenerationRecord[];
+    }): {
+        stop: boolean;
+        reason?: string;
+    };
+}
+/** Optional vocabulary alias. The loop is the optimizer; this object is the
+ * proposer inside that loop. */
+type OptimizationProposer<TFindings = unknown> = SurfaceProposer<TFindings>;
+interface OptimizerConfigBase {
+    populationSize: number;
+    maxGenerations: number;
+    surfaceExtractor: (profile: unknown) => MutableSurface;
+}
+interface OptimizerConfig extends OptimizerConfigBase {
+    proposer: SurfaceProposer;
+}
+/** Five-valued verdict taxonomy (MOSS-paper alignment). */
+type GateDecision = 'ship' | 'hold' | 'need_more_work' | 'model_ceiling' | 'arch_ceiling';
+interface GateContext<TArtifact, TScenario extends Scenario> {
+    candidateArtifacts: Map<string, TArtifact>;
+    baselineArtifacts?: Map<string, TArtifact>;
+    /** Candidate (winner) judge scores, keyed by cellId. */
+    judgeScores: Map<string, Record<string, JudgeScore>>;
+    /** Baseline judge scores, keyed by cellId. SEPARATE from `judgeScores` —
+     *  baseline + candidate share cellIds (same scenarios), so a single map
+     *  cannot represent both. A gate computing a holdout delta MUST read
+     *  candidate from `judgeScores` and baseline from here. */
+    baselineJudgeScores?: Map<string, Record<string, JudgeScore>>;
+    /** Neutralized-arm judge scores, keyed by cellId — the winner surface with its
+     *  content footprint-matched-blanked (via a `neutralize` fn). Same scenarios as
+     *  `judgeScores`. Present ONLY when `runImprovementLoop` was given a `neutralize`
+     *  function. A placebo gate (`neutralizationGate`) compares this arm's lift
+     *  against the candidate's to reject decorative wins (lift from footprint, not
+     *  content). Undefined otherwise. */
+    neutralizedJudgeScores?: Map<string, Record<string, JudgeScore>>;
+    /** Neutralized-arm artifacts, keyed by cellId. Present alongside
+     *  `neutralizedJudgeScores`. */
+    neutralizedArtifacts?: Map<string, TArtifact>;
+    scenarios: TScenario[];
+    cost: {
+        candidate: number;
+        baseline: number;
+    };
+    /** Shared run spend account and receipt attribution phase. */
+    costLedger?: CostLedger;
+    costPhase?: string;
+    signal: AbortSignal;
+}
+interface GateResult {
+    decision: GateDecision;
+    reasons: string[];
+    contributingGates: Array<{
+        name: string;
+        passed: boolean;
+        detail: unknown;
+    }>;
+    delta?: number;
+}
+/** Composable promotion gate. */
+interface Gate<TArtifact = unknown, TScenario extends Scenario = Scenario> {
+    name: string;
+    decide(ctx: GateContext<TArtifact, TScenario>): Promise<GateResult>;
+}
+/** Scoped trace writer handed to each dispatch — every span
+ *  auto-tagged with the cellId so traces filter cleanly. */
+interface CampaignTraceWriter {
+    span(name: string, attributes?: Record<string, unknown>): TraceSpan;
+    flush(): Promise<void>;
+}
+interface TraceSpan {
+    end(attributes?: Record<string, unknown>): void;
+    setAttribute(key: string, value: unknown): void;
+}
+/** Scoped artifact writer — `write(path, content)` lands under
+ *  `<runDir>/<cellId>/<path>`. */
+interface CampaignArtifactWriter {
+    write(path: string, content: string | Uint8Array): Promise<string>;
+    writeJson(path: string, value: unknown): Promise<string>;
+}
+/** Token usage accumulated for a cell. Aliased to the canonical `RunTokenUsage`
+ *  (run-record.ts, same package) so a cell maps onto a `RunRecord` for the
+ *  backend-integrity guard with ONE source of truth — a field added to
+ *  `RunTokenUsage` is a compile error here, not a silent drift. */
+type CampaignTokenUsage = RunTokenUsage;
+/** Cell-scoped paid-call entry point. The dispatch places every paid operation
+ *  inside `runPaidCall`; the returned provider result supplies one receipt with
+ *  cost, tokens, and resolved model. Calls made outside this method are not
+ *  admitted or captured. */
+interface CampaignCostMeter {
+    /** The only paid-call path. Returns a typed result; callers must inspect it. */
+    runPaidCall<T>(input: Omit<RunPaidCallInput<T>, 'channel' | 'phase' | 'tags'> & {
+        channel?: CostChannel;
+    }): Promise<PaidCallResult<T>>;
+}
+/** Source tag — required on every store write. Used by the
+ *  default training-source filter (production-trace samples NOT used as
+ *  training scenarios unless explicitly opted in). */
+type LabeledScenarioSource = 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
+type RedactionStatus = 'raw' | 'redacted-pii' | 'redacted-secrets' | 'fully-redacted';
+/** How much a label can be trusted to evaluate against — the gold-admission
+ *  gate. Strictly ordered: a record qualifies for a `minTrust` filter when its
+ *  trust rank is >= the requested rank.
+ *
+ *   - `unverified`      — label is a heuristic (e.g. raw outcome success/fail).
+ *                          Fine as corpus; MUST NOT enter a gold set that lift
+ *                          numbers are computed against.
+ *   - `verified-signal` — an external signal confirmed the outcome (PR merged,
+ *                          tests green, user did not retry, downstream check).
+ *   - `human-rated`     — a human explicitly rated or corrected the artifact.
+ *
+ *  Absent on a write ⇒ treated as `unverified` (fail-closed: a writer must
+ *  explicitly assert trust to make a record gold-eligible — it never happens
+ *  by accident). */
+type LabelTrust = 'unverified' | 'verified-signal' | 'human-rated';
+/** Ordinal rank for a label-trust tier; absent ⇒ `unverified` (rank 0). */
+declare function labelTrustRank(trust: LabelTrust | undefined): number;
+/** Required-provenance write. The store rejects writes that
+ *  lack provenance — a default-on flywheel without provenance is the
+ *  data-poisoning vector flagged in the alignment review. */
+interface LabeledScenarioWrite<TScenario extends Scenario = Scenario, TArtifact = unknown> {
+    scenario: TScenario;
+    artifact: TArtifact;
+    judgeScores: Record<string, JudgeScore>;
+    source: LabeledScenarioSource;
+    sourceVersionHash: string;
+    capturedAt: string;
+    redactionStatus: RedactionStatus;
+    /** Gold-admission trust tier. Absent ⇒ `unverified` (fail-closed): the
+     *  record is corpus, never gold. A writer must explicitly assert
+     *  `verified-signal` or `human-rated` to make it eligible for a gold
+     *  sample. See {@link LabelTrust}. */
+    labelTrust?: LabelTrust;
+    /** Optional per-source rate-limit bucket key (e.g., the tenant id). */
+    rateLimitBucket?: string;
+}
+interface LabeledScenarioRecord<TScenario extends Scenario = Scenario, TArtifact = unknown> extends LabeledScenarioWrite<TScenario, TArtifact> {
+    /** Stable hash of (scenario.id, source, capturedAt, sourceVersionHash). */
+    recordHash: string;
+    /** Substrate-assigned split — train if captured before the campaign's
+     *  `temporalCutoff`, test if after. Explicit override allowed via filter. */
+    split: 'train' | 'test';
+}
+interface LabeledScenarioSampleArgs {
+    count: number;
+    /** REQUIRED — substrate refuses to sample without an explicit split. */
+    split: 'train' | 'test';
+    /** REQUIRED — only records captured before this timestamp are returned.
+     *  Enforces temporal split discipline (test scenarios captured AFTER train
+     *  cannot enter the training pool). */
+    capturedBefore: string;
+    filter?: {
+        kind?: string;
+        source?: LabeledScenarioSource | LabeledScenarioSource[];
+        minComposite?: number;
+        maxComposite?: number;
+        /** Gold gate: only records whose trust rank is >= this tier are
+         *  returned. `sample({ split: 'test', minTrust: 'verified-signal' })` is
+         *  the canonical "give me the gold set" call. Absent ⇒ no trust gate
+         *  (corpus-level read). */
+        minTrust?: LabelTrust;
+    };
+}
+interface LabeledScenarioStore {
+    observe(write: LabeledScenarioWrite): Promise<void>;
+    sample(args: LabeledScenarioSampleArgs): Promise<LabeledScenarioRecord[]>;
+    size(): Promise<{
+        train: number;
+        test: number;
+        bySource: Record<string, number>;
+        /** Count by trust tier — tells the flywheel how much gold it has
+         *  accumulated vs. raw corpus. */
+        byTrust: Record<LabelTrust, number>;
+    }>;
+}
+interface CampaignCellResult<TArtifact> {
+    /** Manifest that produced this cell. Resumability refuses to reuse a cell
+     *  whose manifest differs from the current run. */
+    manifestHash?: string;
+    cellId: string;
+    scenarioId: string;
+    rep: number;
+    generation?: number;
+    artifact: TArtifact;
+    judgeScores: Record<string, JudgeScore>;
+    costUsd: number;
+    /** True when at least one priced receipt used the model table instead of a provider bill. */
+    costEstimated?: boolean;
+    /** Exact durable receipts required to reuse this cached result. */
+    costCallIds?: string[];
+    /** Agent-call token usage committed by `ctx.cost.runPaidCall`.
+     *  `{ input: 0, output: 0 }` when no paid agent call was recorded. */
+    tokenUsage: CampaignTokenUsage;
+    /** Concrete model from the latest committed agent receipt. Consumed by
+     *  `buildRunRecord` to pin the model when the declared profile uses a
+     *  runtime-resolved sentinel. */
+    resolvedModel?: string;
+    durationMs: number;
+    seed: number;
+    cached: boolean;
+    error?: string;
+}
+interface JudgeAggregate {
+    mean: number;
+    stdev: number;
+    ci95: [number, number];
+    n: number;
+}
+interface ScenarioAggregate {
+    meanComposite: number;
+    ci95: [number, number];
+    n: number;
+}
+interface GenerationRecord {
+    generationIndex: number;
+    candidates: GenerationCandidate[];
+    promoted: string[];
+}
+/** One scored candidate surface in a generation. `dimensions` + `scenarios`
+ *  let a reflective proposer ground its next proposal on WHICH
+ *  dimensions the candidate is weakest on and WHICH scenarios it best/worst
+ *  handled — the evidence a blind `Mutator` cannot see. */
+interface GenerationCandidate {
+    surfaceHash: string;
+    composite: number;
+    ci95: [number, number];
+    /** Exact surface this candidate mutated. */
+    parentSurfaceHash?: string;
+    /** Measured search-split composite of the exact parent surface. */
+    parentComposite?: number;
+    /** Candidate composite minus its parent's composite. Present only when the
+     *  candidate completed the designed denominator. */
+    observedDeltaFromParent?: number;
+    /** Whether this candidate had a scorable result for every designed campaign
+     *  cell and was therefore eligible for ranking, promotion, and Pareto
+     *  selection. Older externally-authored records may omit this field; loop
+     *  records always populate it. */
+    eligibleForPromotion?: boolean;
+    /** Exact denominator receipt for selection eligibility. Scores stay
+     *  descriptive: an incomplete candidate is retained with its observed score
+     *  and errors instead of receiving an invented penalty. */
+    coverage?: {
+        expectedCells: number;
+        scorableCells: number;
+        unscorableCells: Array<{
+            cellId: string;
+            reason: string;
+        }>;
+    };
+    /** Mean score per judge dimension across all cells (scenarios × reps ×
+     *  judges that reported the dimension). */
+    dimensions: Record<string, number>;
+    /** Per-scenario composite (mean over reps + judges), plus the judge's
+     *  free-form `notes` for that scenario — the "why it scored low" evidence a
+     *  reflective proposer grounds its next edit on. Keep `notes` GENERALIZABLE
+     *  (which checks/lines/dimensions failed and how), NOT case-specific ground
+     *  truth: leaking expected answers into the prompt is memorization, and the
+     *  held-out gate would reject it anyway. */
+    scenarios: Array<{
+        scenarioId: string;
+        composite: number;
+        notes?: string;
+    }>;
+    /** Proposer-supplied short label for the change. Present when the proposer
+     *  returned a `ProposedCandidate`; absent for bare-surface mutators. */
+    label?: string;
+    /** Proposer-supplied rationale — WHY this candidate was proposed. The
+     *  "because rationale Z" the audit requires to survive to the result.
+     *  Present when the proposer returned a `ProposedCandidate`. */
+    rationale?: string;
+    /** Exact structured cause threaded from the proposer, when available. */
+    candidateRecord?: PolicyEditCandidateRecord;
+}
+interface CampaignAggregates {
+    byJudge: Record<string, JudgeAggregate>;
+    byScenario: Record<string, ScenarioAggregate>;
+    /** Canonical campaign accounting, including worker and judge calls. */
+    cost: CostLedgerSummary;
+    /** Compatibility alias of `cost.totalCostUsd`. */
+    totalCostUsd: number;
+    cellsExecuted: number;
+    cellsSkipped: number;
+    cellsCached: number;
+    cellsFailed: number;
+}
+interface CampaignResult<TArtifact = unknown, TScenario extends Scenario = Scenario> {
+    /** sha256(scenarios, judges, dispatch source ref, optimizer config, seed). Stable identity for reruns. */
+    manifestHash: string;
+    seed: number;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    cells: Array<CampaignCellResult<TArtifact>>;
+    aggregates: CampaignAggregates;
+    optimization?: {
+        generations: GenerationRecord[];
+        winnerSurfaceHash?: string;
+    };
+    gate?: GateResult;
+    prUrl?: string;
+    runDir: string;
+    artifactsByPath: Record<string, string>;
+    /** Substrate strips the input scenarios to id+kind for the result manifest;
+     *  consumers needing full payload look it up via the original input. The
+     *  type parameter `TScenario` is propagated for downstream consumers that
+     *  want narrowed types when extending `CampaignResult`. */
+    scenarios: Array<Pick<TScenario, 'id' | 'kind'>>;
+}
+
+/**
+ * `llmJudge` — the single-LLM-call bridge that turns a rubric prompt into a
+ * canonical campaign `JudgeConfig`.
+ *
+ * The `JudgeConfig` contract (src/campaign/types.ts) is deliberately a
+ * function, not a fixed LLM-prompt shape: real consumers judge with
+ * ensembles, deterministic checks, or one LLM call. `ensembleJudge`
+ * (src/judge-panel.ts) covers the multi-model case; `buildAgreementJudge`
+ * (src/campaign/distillation) covers the pure-comparator case. `llmJudge`
+ * covers the common single-call case the `JudgeConfig` doc-comment names:
+ * one model call against `prompt`, parsed into the canonical `JudgeScore`
+ * (`{ dimensions, composite, notes }`) on the campaign [0,1] scale.
+ *
+ * Transport is injected as a `ChatClient` (src/analyst/chat-client.ts) — the
+ * substrate's transport-agnostic LLM seam — so the judge stays decoupled from
+ * router-vs-sandbox-vs-cli-bridge and is unit-testable with the `mock`
+ * transport. The composite is computed by `weightedComposite` (the same
+ * sum-normalized weighting `ensembleJudge` uses), so a lift is attributable to
+ * the dimension scores, not to a bespoke reducer.
+ *
+ * Fail-loud throughout: an unparseable model response throws `JudgeParseError`;
+ * a response missing a declared dimension throws; an out-of-range score throws.
+ * A thrown judge is recorded by the campaign engine as a failed cell, never
+ * folded into a silent zero.
+ */
+
+/** A rubric dimension as a bare key or the full `{ key, description }` shape. A
+ *  bare string uses the key as its own description. */
+type LlmJudgeDimension = string | JudgeDimension;
+interface LlmJudgeOptions<TArtifact, TScenario extends Scenario = Scenario> {
+    /** The injected LLM transport. One `chat()` call per `score()`. Required —
+     *  there is no default route, so a misconfigured judge fails at construction,
+     *  never silently against the free-tier router. */
+    chat: ChatClient;
+    /** Rubric dimensions the model scores. Each becomes a `[0,1]` field of the
+     *  returned `JudgeScore.dimensions`. Defaults to a single `quality` dimension. */
+    dimensions?: LlmJudgeDimension[];
+    /** Model id. Falls back to `chat.defaultModel`; one of the two MUST resolve. */
+    model?: string;
+    /** Explicit scoring revision for opaque transport or renderer changes. */
+    judgeVersion?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Composite weights forwarded to `weightedComposite`: a partial map selects
+     *  AND weights exactly the named dimensions. Omit for a uniform mean. */
+    weights?: Record<string, number>;
+    /** Scale the model is prompted to score on, normalized into `[0,1]`:
+     *   - `'unit'`  (default): the model returns `[0,1]` directly.
+     *   - `'ten'`:  the model returns `[0,10]`; divided by 10 here.
+     *  The prompt is annotated with the expected range either way. */
+    scale?: 'unit' | 'ten';
+    /** Run this judge only on matching scenarios (mirrors `JudgeConfig.appliesTo`). */
+    appliesTo?: (scenario: TScenario) => boolean;
+    /** Render the artifact + scenario into the user message. Default:
+     *  pretty-printed JSON of `{ scenario, artifact }`. */
+    renderUser?: (input: {
+        artifact: TArtifact;
+        scenario: TScenario;
+    }) => string;
+    /** Strict runtime contract; its JSON Schema is sent to the provider. */
+    costLedger?: CostLedger;
+    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>;
+
+interface ReferenceEquivalenceScenario extends Scenario {
+    userRequest: string;
+    expectedAnswer: string;
+}
+interface ReferenceEquivalenceJudgeOptions {
+    /** Injected transport. No implicit provider or credentials are selected. */
+    chat: ChatClient;
+    /** Falls back to the ChatClient's default model. */
+    model?: string;
+    /** Used only by the direct-call adapter. */
+    signal?: AbortSignal;
+    /** Optional receipt destination for direct calls; campaigns supply their own. */
+    costLedger?: CostLedger;
+}
+/** Build the campaign-native expected-answer judge. */
+declare function createReferenceEquivalenceJudge(options: ReferenceEquivalenceJudgeOptions): JudgeConfig<string, ReferenceEquivalenceScenario>;
+
+interface AnalyzeTracesInput {
+    /** The user-facing question. Domain framing belongs here, not in the
+     *  actor description. */
+    question: string;
+}
+interface AnalyzeTracesResult {
+    /** The responder's prose answer. */
+    answer: string;
+    /** Bulleted findings extracted from the responder's structured output. */
+    findings: string[];
+    /** Per-actor-turn snapshots captured via `actorTurnCallback`. */
+    turns: AnalyzeTracesTurnSnapshot[];
+    /** Total turns the actor took. */
+    turnCount: number;
+    /** Token usage by role. */
+    usage: TraceAnalystUsage;
+    /** Full system + assistant + tool message log by role. */
+    chatLog: TraceAnalystChatLog;
+    /** Prompt version that produced this run. */
+    actorPromptVersion: string;
+}
+interface TraceAnalystUsage {
+    actor: TraceAnalystUsageEntry[];
+    responder: TraceAnalystUsageEntry[];
+}
+interface TraceAnalystUsageEntry {
+    [key: string]: unknown;
+}
+interface TraceAnalystChatLog {
+    actor: TraceAnalystChatMessage[];
+    responder: TraceAnalystChatMessage[];
+}
+interface TraceAnalystChatMessage {
+    [key: string]: unknown;
+}
+interface AnalyzeTracesTurnSnapshot {
+    turn: number;
+    isError: boolean;
+    /** The JS code the actor produced for this turn. */
+    code: string;
+    /** The formatted action-log entry the actor sees on the next turn. */
+    output: string;
+    /** Provider thought (when `actorOptions.showThoughts` is true and the
+     *  provider returns it). */
+    thought?: string;
+}
+interface AnalyzeTracesOptions {
+    /** Trace data source. Pass either an OTLP-JSONL path or a custom store. */
+    source: string | TraceAnalysisStore;
+    /** Caller-provided AxAIService. */
+    ai: AxAIService;
+    /** Model id forwarded to actor + responder. */
+    model?: string;
+    /** Recursion depth. 0 = no sub-agent dispatch. Default 1. */
+    maxDepth?: number;
+    /** Maximum actor turns. Default 12. */
+    maxTurns?: number;
+    /** Maximum parallel sub-agent calls in batched llmQuery. Default 2. */
+    maxParallelSubagents?: number;
+    /** Override the actor description. */
+    actorDescription?: string;
+    /** Override the subagent description. */
+    subagentDescription?: string;
+    /** Per-turn observability hook. */
+    onTurn?: (turn: AnalyzeTracesTurnSnapshot) => void | Promise<void>;
+    /** Override max runtime characters per turn. Default 6000. */
+    maxRuntimeChars?: number;
+    /** When set, every turn's snapshot is appended to this JSONL file
+     *  immediately. If the analyst crashes mid-loop (provider 503,
+     *  network error, validator reject) the partial reasoning is still
+     *  on disk. Replay the file with the responder afterward to recover
+     *  evidence. */
+    progressLogPath?: string;
+}
+
 /**
  * Make the trace-analyst's OWN prompt a GEPA-optimizable surface.
  *
@@ -377,6 +2281,210 @@ interface FailureModeRecallJudgeOptions {
  */
 declare function failureModeRecallJudge(opts?: FailureModeRecallJudgeOptions): JudgeConfig<AnalystArtifact, AnalystScenario>;
 
+/**
+ * `openAutoPr` — thin shell-out helper for the `runImprovementLoop` preset's
+ * `autoOnPromote: 'pr'` mode. Substitutes for the per-product PR-opening
+ * code consumers duplicated 4 times. The PR body includes the campaign's
+ * manifest hash, gate verdict, and scorecard summary so reviewers can see
+ * exactly what was promoted + why.
+ *
+ * NOT a deploy mechanism — this only OPENS a PR. The human reviews + merges.
+ * The Shape B (`autoOnPromote: 'config'`) live-runtime-mutation path is
+ * deferred to Pass B with the full shadow / canary / rollback stack.
+ */
+
+interface OpenAutoPrOptions<TArtifact, TScenario extends Scenario> {
+    /** Campaign result to attach to the PR. */
+    result: CampaignResult<TArtifact, TScenario>;
+    /** Gate verdict explaining the promotion. Substrate refuses to open a PR
+     *  when `gate.decision !== 'ship'` — fails loud. */
+    gate: GateResult;
+    /** Promoted surface diff — typically the new system prompt addendum or
+     *  full profile diff. Substrate writes it as the PR body. */
+    promotedDiff: string;
+    /** GH owner/repo target (e.g., `tangle-network/gtm-agent`). */
+    ghOwner: string;
+    ghRepo: string;
+    /** Branch name for the PR. Default `auto/<manifestHash[:12]>`. */
+    branch?: string;
+    /** PR title. Default includes manifest hash. */
+    title?: string;
+    /** Whether to actually open the PR or just dry-run. Default reads
+     *  `GH_AUTO_PR_TOKEN` env — present = open, absent = dry-run. */
+    dryRun?: boolean;
+    /** Test seam — substitute `gh pr create` invocation. */
+    ghExec?: (args: string[]) => {
+        stdout: string;
+        stderr: string;
+        status: number;
+    };
+}
+interface OpenAutoPrResult {
+    opened: boolean;
+    prUrl?: string;
+    dryRun: boolean;
+    reason: string;
+}
+/**
+ * Open a GitHub PR for a gate-approved surface promotion, attaching the manifest hash, gate verdict, and diff as the PR body.
+ */
+declare function openAutoPr<TArtifact, TScenario extends Scenario>(options: OpenAutoPrOptions<TArtifact, TScenario>): OpenAutoPrResult;
+
+interface ContinuousAgreement {
+    /** Cohen's κ_w with quadratic weights, computed on raw [0,1] scores. */
+    weightedKappa: number;
+    /** ICC(2,1): two-way random effects, absolute agreement, single rater. */
+    icc: number;
+    /** Pearson product-moment correlation (averaged over rater pairs if N>2). */
+    pearson: number;
+    /** Spearman rank correlation (averaged over rater pairs if N>2). */
+    spearman: number;
+    /** 95% bootstrap percentile CIs over items. */
+    ci: {
+        icc: [number, number];
+        weightedKappa: [number, number];
+    };
+    /** Number of complete items (no NaN across raters). */
+    n: number;
+    /** Number of raters. */
+    raters: number;
+}
+
+interface PairedBootstrapResult {
+    /** Number of paired observations. */
+    n: number;
+    /** Median of paired deltas (after − before). */
+    median: number;
+    /** Mean of paired deltas. */
+    mean: number;
+    /** Lower bound of the bootstrap CI on the chosen statistic. */
+    low: number;
+    /** Upper bound of the bootstrap CI on the chosen statistic. */
+    high: number;
+    /** Confidence level used (e.g. 0.95). */
+    confidence: number;
+    /** Number of bootstrap resamples used. */
+    resamples: number;
+}
+/** Result of a McNemar paired-binary significance test. */
+interface McNemarResult {
+    /** Total paired observations. */
+    n: number;
+    /** Discordant pairs (b + c) — the only ones that carry signal. */
+    nDiscordant: number;
+    /** Pairs where treatment succeeded and control failed ("newly correct"). */
+    b: number;
+    /** Pairs where control succeeded and treatment failed ("newly wrong"). */
+    c: number;
+    /** Continuity-corrected chi-square statistic (reference; exact p drives the call). */
+    statistic: number;
+    /** Two-sided p-value. Exact (binomial sign test on discordant pairs). */
+    pValue: number;
+}
+/** A paired binary effect size (treatment rate − control rate) with a CI. */
+interface RiskDifferenceResult {
+    /** Total paired observations. */
+    n: number;
+    /** Discordant pairs: treatment-win count. */
+    b: number;
+    /** Discordant pairs: control-win count. */
+    c: number;
+    /** Paired risk difference p(treatment) − p(control) = (b − c) / n. */
+    riskDifference: number;
+    /** Lower bound of the CI, clamped to [-1, 1]. */
+    lower: number;
+    /** Upper bound of the CI, clamped to [-1, 1]. */
+    upper: number;
+    /** Confidence level used. */
+    confidence: number;
+}
+interface EProcessStep {
+    /** Current wealth W_n — the e-value against H0 after n observations. */
+    wealth: number;
+    /** Observations consumed so far. */
+    n: number;
+    /** True from the first n where W_n ≥ 1/alpha onward (sticky). */
+    decided: boolean;
+}
+interface EProcessState extends EProcessStep {
+    alpha: number;
+    maxBet: number;
+    nullMean: number;
+    /** The decision boundary 1/alpha. */
+    threshold: number;
+    /** Observation count at the first threshold crossing; undefined until decided. */
+    decidedAtN?: number;
+}
+
+/**
+ * Matched-pair arm comparison — "did the treatment arm beat the baseline arm
+ * on the SAME work items?"
+ *
+ * An arm A/B over run records is only trustworthy when it is PAIRED: the same
+ * task/scenario/seed evaluated under both arms, compared item-by-item, so
+ * inter-item difficulty variance cancels instead of masquerading as an arm
+ * effect. This module owns the two error-prone steps every consumer otherwise
+ * hand-rolls:
+ *
+ *   1. Pairing — matching rows across arms by `pairKey` (and by `repKey`
+ *      within multi-rep items), with leftovers REPORTED rather than silently
+ *      dropped (a silently unbalanced pairing biases every paired statistic
+ *      downstream). Pairing never keys on outcome content: matching reps by
+ *      their outcomes deflates discordant-pair counts and makes McNemar
+ *      anti-conservative, so reps pair only by (`pairKey`, `repKey`) identity.
+ *   2. Composition — feeding the matched pairs to the correct paired
+ *      estimators that already live in `statistics`: `mcnemar` +
+ *      `pairedRiskDifference` for pass/fail, `pairedBootstrap` +
+ *      `wilcoxonSignedRank` for continuous metrics. No statistic is
+ *      re-implemented here.
+ *
+ * The row shape is deliberately structural — callers project a `RunRecord`
+ * (or any record) into `{ pairKey, arm, pass?, metrics? }`. Arm names are
+ * caller-supplied parameters; the module ships no domain literal.
+ */
+
+/** Paired pass/fail comparison over the pairs where BOTH sides carry `pass`. */
+interface PairedCorrectness {
+    /** Discordant pairs where the treatment passed and the baseline failed. */
+    b10: number;
+    /** Discordant pairs where the baseline passed and the treatment failed. */
+    b01: number;
+    /** Exact McNemar significance over the paired outcomes (`b === b10`, `c === b01`). */
+    mcnemar: McNemarResult;
+    /** Paired effect size: p(treatment) − p(baseline) with a paired-variance CI. */
+    riskDifference: RiskDifferenceResult;
+}
+/** Paired delta summary for one named metric (delta = treatment − baseline). */
+interface PairedMetricDelta {
+    name: string;
+    /** Pairs where BOTH sides carry a finite value for this metric. */
+    n: number;
+    /** Pairs where at least one side does not carry the metric. */
+    nMissing: number;
+    /** Median paired delta; NaN when `n === 0` (no data ≠ measured zero). */
+    medianDelta: number;
+    /** Mean paired delta; NaN when `n === 0`. */
+    meanDelta: number;
+    /** Bootstrap CI on the paired delta (`pairedBootstrap`); null when
+     *  `n === 0` — a zero-width [0, 0] interval on no data would read as a
+     *  measured tight null. */
+    bootstrapCi: PairedBootstrapResult | null;
+    /** Wilcoxon signed-rank test on the paired deltas; null when `n === 0`. */
+    wilcoxon: {
+        w: number;
+        p: number;
+    } | null;
+}
+interface PairedArmsComparison {
+    nPairs: number;
+    nUnpairedBaseline: number;
+    nUnpairedTreatment: number;
+    /** null when no matched pair carries `pass` on both sides — a pass/fail
+     *  verdict over rows that never measured pass/fail would be fabricated. */
+    correctness: PairedCorrectness | null;
+    metricDeltas: PairedMetricDelta[];
+}
+
 /** Whether one candidate attempt produced a usable executable outcome. */
 type CrossSurfaceAttemptCompleteness = 'complete' | 'missing' | 'invalid';
 /** One independently proposed change on one caller-defined surface. */
@@ -636,19 +2744,208 @@ interface CrossSurfaceInteractionReport<TRow extends CrossSurfaceTaskRow = Cross
     pairwise: CrossSurfacePairwiseEntry[];
     selections: CrossSurfaceSelections;
 }
-
+
+/**
+ * Task-paired comparison and deterministic selection for independently
+ * proposed agent surfaces. Unlike factorial cell-mean attribution, every
+ * benefit, regression, and interaction remains attached to its task row.
+ */
+
+/**
+ * Build the complete cross-surface evidence matrix and derive all three frozen
+ * candidates. The task/candidate/component orders are part of the input so
+ * neither insertion order nor an after-the-fact tie-break can change a result.
+ */
+declare function analyzeCrossSurfaceInteractions<TRow extends CrossSurfaceTaskRow>(input: AnalyzeCrossSurfaceInteractionsInput<TRow>): CrossSurfaceInteractionReport<TRow>;
+
+/**
+ * `CampaignStorage` — the filesystem seam `runCampaign` writes through
+ * (run/cell dirs, the resumability cache, per-cell artifacts, trace spans).
+ *
+ * The default (`fsCampaignStorage`) is the Node filesystem — identical
+ * behavior to the inline `node:fs` calls it replaces, so existing CLI
+ * consumers are unaffected. `inMemoryCampaignStorage` keeps everything in a
+ * `Map`, so the substrate runs in environments WITHOUT a filesystem
+ * (Cloudflare Workers, Deno Deploy, other edge runtimes) — the campaign
+ * still produces its `CampaignResult` (cells + aggregates) in memory;
+ * artifacts/traces simply aren't persisted to disk.
+ *
+ * Paths are opaque keys to the in-memory adapter — it does not parse them,
+ * so the same `join(...)`-built paths work unchanged across both adapters.
+ */
+interface CampaignStorage {
+    /** Ensure a directory exists (recursive). No-op for in-memory. */
+    ensureDir(dir: string): void;
+    /** Does this path exist (as a written file or an ensured dir)? */
+    exists(path: string): boolean;
+    /** Read a UTF-8 file; `undefined` when missing or unreadable. */
+    read(path: string): string | undefined;
+    /** Write a file (string or bytes). Parent dir is assumed ensured. */
+    write(path: string, content: string | Uint8Array): void;
+    /** Append only when the current UTF-8 byte length matches `expectedBytes`.
+     * Returns the new length, or undefined when another writer won. */
+    append?(path: string, content: string, expectedBytes: number): number | undefined;
+}
+/** Node-filesystem storage — the default. Lazily requires `node:fs` so the
+ *  module imports cleanly in non-Node runtimes (where the caller passes
+ *  `inMemoryCampaignStorage` instead and never constructs this).
+ *
+ *  `createRequire(import.meta.url)` is the ESM-native lazy require — a bare
+ *  `require` is a ReferenceError under `"type": "module"`, which is exactly
+ *  the shape this package publishes. */
+declare function fsCampaignStorage(): CampaignStorage;
+/** In-memory storage for filesystem-less runtimes. Artifacts + trace spans
+ *  live in a `Map` for the duration of the run; the `CampaignResult` is
+ *  fully populated, but nothing is persisted to disk. */
+declare function inMemoryCampaignStorage(): CampaignStorage;
+/** Open the durable spend account stored beside a logical run. */
+declare function createRunCostLedger(input: {
+    storage: CampaignStorage;
+    runDir: string;
+    costCeilingUsd?: number;
+}): CostLedger;
+
+/**
+ * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
+ * scenarios → dispatch → artifacts → judges → aggregates, with full
+ * reproducibility (seed + manifest hash), cell-level resumability, bootstrap
+ * CIs, and the `LabeledScenarioStore` capture flywheel.
+ *
+ * Improvement loops (optimizer / gate / autoOnPromote) ride on top of this
+ * primitive but live in `presets/run-improvement-loop.ts`. This file keeps
+ * the core orchestrator minimal — Phase 1 of the Pass A track.
+ */
+
+interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
+    scenarios: TScenario[];
+    dispatch: DispatchFn<TScenario, TArtifact>;
+    /**
+     * Stable identity for the dispatch behavior, included in the manifest/cache
+     * key. Set this when the same function name can run different models,
+     * prompts, tools, or external config.
+     */
+    dispatchRef?: string;
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    /** Required for reproducibility. Default 42. */
+    seed?: number;
+    /** Per-scenario replicates for CI bands. Default 1; raise to 5+ for
+     *  bootstrap-tight intervals on critical eval. */
+    reps?: number;
+    /** When true (default), completed cells are cached by
+     *  (manifestHash, scenarioId, rep, generation). Re-runs skip cached cells. */
+    resumable?: boolean;
+    /** Optional store — when present, every artifact + judge score is captured
+     *  with the configured `captureSource`. Capture is default ON; pass `'off'`
+     *  to disable. */
+    labeledStore?: LabeledScenarioStore | 'off';
+    captureSource?: 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
+    captureSourceVersionHash?: string;
+    /** Hard spend cap. Each paid call reserves its enforced maximum before dispatch. */
+    costCeiling?: number;
+    /** Shared spend account. Improvement loops pass one ledger through every
+     *  campaign so the ceiling and returned total are run-wide. */
+    costLedger?: CostLedger;
+    /** Attribution label for receipts recorded by this campaign. */
+    costPhase?: string;
+    /** Max concurrent cells. Default 2. */
+    maxConcurrency?: number;
+    /**
+     * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
+     * rejects within this window is a hang (a stalled model request, an
+     * exhausted runtime resource, a backend that never closes its stream). When
+     * set, the cell's `ctx.signal` is aborted and the cell is recorded as a LOUD
+     * error (`dispatch exceeded <N>ms`) so the campaign proceeds and the failure
+     * is visible — instead of one wedged cell silently hanging the whole run (and
+     * every loop/CI job above it) forever. `undefined`/`0` = unbounded (legacy).
+     */
+    dispatchTimeoutMs?: number;
+    /** Required: where artifacts + traces land. A bare name (not an absolute path)
+     *  resolves to the shared `~/.tangle/traces/<repo>/runs/<name>` root so run
+     *  bundles never pollute a repo working tree. Pass an absolute path to override. */
+    runDir: string;
+    /** Subject repo for the shared run-dir root (defaults to the CWD basename).
+     *  Only consulted when `runDir` is a bare name. */
+    repo?: string;
+    /** Tracing posture. Default is the substrate's `FileSystemTraceStore` rooted
+     *  at `<runDir>/traces/`. `'off'` disables capture entirely — substrate
+     *  refuses this when the caller wires `autoOnPromote !== 'none'`. */
+    tracing?: 'on' | 'off';
+    /**
+     * Per-cell usage expectation — the early, fine-grained sibling of the
+     * batch `assertRealBackend` guard. A cell that produced an artifact (no
+     * error) but reported `costUsd === 0` AND zero tokens is a stub: the
+     * dispatch never reported LLM activity via `ctx.cost`. Modes:
+     *   - `'warn'` (default) — log the offending cell loudly, keep going.
+     *   - `'assert'` — throw `BackendIntegrityError` on the first such cell
+     *     (fail-fast; recommended for CI campaigns expecting real LLM calls).
+     *   - `'off'` — no check (replay / deterministic-only / offline analysis).
+     */
+    expectUsage?: 'assert' | 'warn' | 'off';
+    /** Test seam — override the wall clock for deterministic tests. */
+    now?: () => Date;
+    /** Test seam — override per-cell trace writer factory. */
+    buildTraceWriter?: (cellId: string, dir: string) => CampaignTraceWriter;
+    /** Storage backend for run/cell dirs, the resumability cache, artifacts,
+     *  and trace spans. Default: the Node filesystem (`fsCampaignStorage`).
+     *  Pass `inMemoryCampaignStorage()` to run in a filesystem-less runtime
+     *  (Cloudflare Workers, Deno, edge) — the `CampaignResult` is still
+     *  produced; artifacts/traces just aren't persisted to disk. */
+    storage?: CampaignStorage;
+    /**
+     * Optional per-cell placement strategy. Returns an opaque string the
+     * substrate forwards as `ctx.placement` to the Dispatch — placement-aware
+     * Dispatches (e.g. `httpDispatch` from `/adapters/http`) use it to route
+     * each cell to the right worker, region, or sandbox. When unset, every
+     * cell receives `ctx.placement = undefined` and behaves identically to
+     * the in-process case.
+     *
+     * @example
+     *   cellPlacement: ({ scenario }) => scenario.tags?.includes('eu') ? 'eu-west' : 'us-east'
+     */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
+}
 /**
- * Task-paired comparison and deterministic selection for independently
- * proposed agent surfaces. Unlike factorial cell-mean attribution, every
- * benefit, regression, and interaction remains attached to its task row.
+ * Core campaign orchestrator: fan scenarios through dispatch, score with judges, aggregate bootstrap CIs, and persist reproducible `CampaignResult` records.
  */
-
+declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
+interface CampaignRunPlanCell {
+    cellId: string;
+    scenarioId: string;
+    rep: number;
+    seed: number;
+    cachePath: string;
+    status: 'cached' | 'run';
+    reason?: 'missing' | 'manifest-mismatch' | 'cell-mismatch' | 'corrupt' | 'resumable-off';
+}
+interface CampaignRunPlan {
+    manifestHash: string;
+    totalCells: number;
+    cellsCached: number;
+    cellsToRun: number;
+    cells: CampaignRunPlanCell[];
+}
+interface PlanCampaignRunOptions<TScenario extends Scenario, TArtifact> {
+    scenarios: TScenario[];
+    dispatch?: DispatchFn<TScenario, TArtifact>;
+    dispatchRef?: string;
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    runDir: string;
+    /** Subject repo for the shared run-dir root (see RunCampaignOptions.repo). */
+    repo?: string;
+    storage?: CampaignStorage;
+}
 /**
- * Build the complete cross-surface evidence matrix and derive all three frozen
- * candidates. The task/candidate/component orders are part of the input so
- * neither insertion order nor an after-the-fact tie-break can change a result.
+ * 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 analyzeCrossSurfaceInteractions<TRow extends CrossSurfaceTaskRow>(input: AnalyzeCrossSurfaceInteractionsInput<TRow>): CrossSurfaceInteractionReport<TRow>;
+declare function planCampaignRun<TScenario extends Scenario, TArtifact>(opts: PlanCampaignRunOptions<TScenario, TArtifact>): CampaignRunPlan;
 
 type EvalFixtureValidationMode = 'vitest' | 'none';
 interface EvalFixtureFile {
@@ -710,6 +3007,185 @@ declare function loadEvalFixtureScenarios(evalsDir: string, options?: LoadEvalFi
  */
 declare function planEvalFixtureRun<TArtifact = unknown>(options: PlanEvalFixtureRunOptions<TArtifact>): EvalFixtureRunPlan;
 
+/**
+ * Compose multiple `Gate` implementations — every gate must pass for the
+ * composite to ship. Closes the alignment reviewer's "default-only
+ * heldOutGate + costGate would happily promote a reward-hacked prompt"
+ * concern by making safety gates first-class composable defaults.
+ */
+
+/** Compose gates — all must `ship` for the composite to `ship`. First
+ *  non-ship verdict short-circuits the composite verdict, but ALL gates run
+ *  (so the result records every gate's reason — useful for diagnostics). */
+declare function composeGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(...gates: Array<Gate<TArtifact, TScenario>>): Gate<TArtifact, TScenario>;
+
+/**
+ * Dataset — versioned, sliceable, content-hashed scenario collection.
+ *
+ * Scenarios stop being ephemeral arrays and become first-class
+ * artifacts. Every Dataset carries:
+ *   - content hash (sha256 over canonicalized scenario array)
+ *   - provenance (contributor, createdAt, sourceUrl)
+ *   - split labels (train | dev | test | holdout)
+ *   - difficulty tiers (easy | medium | hard | extreme)
+ *   - tags (free-form, per-scenario)
+ *
+ * `Dataset.slice({ difficulty, split, holdout, seed })` returns a
+ * deterministic, reproducible subset. Holdout slices are locked: you
+ * can read them but `mutate` throws, which prevents "oh I'll just
+ * tweak that one scenario" contamination drift.
+ */
+type DatasetSplit = 'train' | 'dev' | 'test' | 'holdout';
+type DatasetDifficulty = 'easy' | 'medium' | 'hard' | 'extreme';
+interface DatasetScenario {
+    id: string;
+    /** Arbitrary payload; the framework doesn't interpret it. */
+    payload: unknown;
+    split?: DatasetSplit;
+    difficulty?: DatasetDifficulty;
+    /** Canary token that MUST NOT round-trip through a correct agent output. */
+    canary?: string;
+    /**
+     * Behavioral-canary forbidden pattern. A string OR a serialized regex
+     * (`/.../flags`) that the agent under test MUST NOT emit. Used by
+     * {@link import('./canary').checkBehavioralCanary | checkBehavioralCanary},
+     * which inverts the contamination-style semantic: presence in the
+     * agent output is a LEAK / failure, not a positive signal.
+     *
+     * Falls back to {@link canary} when omitted.
+     */
+    forbiddenPattern?: string;
+    tags?: Record<string, string>;
+}
+
+/**
+ * Red-team battery — adversarial scenario corpus with per-category
+ * scorers.
+ *
+ * Every scenario is a `DatasetScenario` with a `redTeam: {...}` payload
+ * that declares: category, expected refusal, attack surface. Scorers
+ * inspect the agent's output + trajectory and return a PASS/FAIL per
+ * category. Aggregated via `redTeamReport`.
+ *
+ * The built-in corpus is intentionally conservative — 40 cases
+ * covering the most-seen attack patterns. Extend via `extendCorpus`.
+ */
+
+type RedTeamCategory = 'prompt_injection_direct' | 'prompt_injection_indirect' | 'jailbreak_persona' | 'jailbreak_dan' | 'pii_leak' | 'permission_escalation' | 'data_exfil' | 'policy_override';
+interface RedTeamPayload {
+    category: RedTeamCategory;
+    /** The hostile input the agent sees. */
+    input: string;
+    /**
+     * What a safe agent should do: "refuse" means explicit refusal,
+     * "ignore" means process benignly without executing the attack.
+     */
+    expected: 'refuse' | 'ignore';
+    /** Substring(s) that MUST NOT appear in output. */
+    forbiddenStrings?: string[];
+    /** Tool names the agent MUST NOT call for this scenario. */
+    forbiddenTools?: string[];
+}
+interface RedTeamCase extends DatasetScenario {
+    payload: RedTeamPayload;
+}
+
+/**
+ * `defaultProductionGate` — composes the substrate's existing safety
+ * primitives (red-team / reward-hacking / canary / heldout) into a single
+ * Gate.decide shape. Closes the alignment + Anthropic-SI reviewers' "safety
+ * primitives are off the critical path" blocker.
+ *
+ * The composition is opinionated — when consumers wire `runImprovementLoop`,
+ * THIS gate is the default. Consumers can still pass a custom gate to
+ * override; the recommended pattern is to compose THIS gate with whatever
+ * extra domain-specific gates they need (`composeGate(defaultProductionGate(...), customGate)`).
+ */
+
+interface DefaultProductionGateOptions {
+    /** Required: scenarios held out from training; substrate compares
+     *  candidate-on-holdout vs baseline-on-holdout. */
+    holdoutScenarios: Scenario[];
+    /** Minimum held-out lift the **paired-bootstrap CI lower bound** must clear
+     *  to ship — NOT a point estimate. Default 0 ⇒ "confidently positive at the
+     *  confidence level". Interpreted in the judge's native composite scale (set
+     *  e.g. 2 for a 0-100 rubric to require a ≥2-point significant gain). */
+    deltaThreshold?: number;
+    /** Confidence level for the held-out + dimension bootstraps. Default 0.95. */
+    confidence?: number;
+    /** Bootstrap resamples. Default 2000. */
+    bootstrapResamples?: number;
+    /** Fixed bootstrap seed for a deterministic verdict. Default 1337. */
+    bootstrapSeed?: number;
+    /** Minimum paired holdout observations (scenarios × reps) before a
+     *  significance claim is allowed; below it the gate HOLDS with `few_runs`
+     *  rather than reading a degenerate CI. Default 3. */
+    minProductiveRuns?: number;
+    /** Ship statistic for the held-out significance test. Default `'mean'`
+     *  (tie-robust — see `heldoutSignificance`). Pass `'median'` for
+     *  outlier-robustness at the cost of tie-blindness. */
+    heldoutStatistic?: 'mean' | 'median';
+    /** Critical judge dimensions that must NOT significantly regress even when
+     *  the net composite rises (anti-Goodhart). The gate HOLDS if any listed
+     *  dimension's paired-delta CI lower bound < −`regressionTolerance`. E.g.
+     *  `['hallucination_free']` for a legal agent. */
+    criticalDimensions?: string[];
+    /** Tolerance for the per-dimension regression guard, in the dimension's
+     *  native scale. When omitted it auto-scales off observed magnitudes:
+     *  0.05 on [0,1], 5 on 0-100. */
+    regressionTolerance?: number;
+    /** Total $ budget for ALL cells in this campaign — including baseline + candidate.
+     *  Composite verdict refuses to ship when spend exceeded budget. */
+    budgetUsd?: number;
+    /** Red-team cases to probe candidate outputs against. When omitted the
+     *  substrate uses `DEFAULT_RED_TEAM_CORPUS`. Provide a domain-specific
+     *  battery for tighter coverage. */
+    redTeamBattery?: RedTeamCase[];
+    /** Run records (oldest-first) needed for the reward-hacking detector.
+     *  Substrate populates from prior production-loop generations. */
+    recentRuns?: RunRecord[];
+    /** When true, the gate refuses to ship if the reward-hacking detector
+     *  fires at the `gaming` severity. Default true. */
+    blockOnRewardHackingGaming?: boolean;
+}
+/**
+ * Opinionated production gate composing held-out significance, red-team, reward-hacking, and canary checks into a single `Gate.decide` decision.
+ */
+declare function defaultProductionGate<TArtifact, TScenario extends Scenario>(options: DefaultProductionGateOptions): Gate<TArtifact, TScenario>;
+
+/**
+ * @module
+ * Composable held-out promotion gate backed by paired bootstrap confidence.
+ *
+ * Pair by full `scenario:rep` cellId, bootstrap the paired candidate-minus-
+ * baseline delta, and ship only when CI.low strictly clears the threshold with
+ * at least `minProductiveRuns` paired observations.
+ *
+ * Use when you want held-out significance as ONE of N composed gates instead
+ * of the full `defaultProductionGate` stack (which adds critical-dimension
+ * regression + reward-hacking guards on top).
+ */
+
+interface HeldOutGateOptions<TScenario extends Scenario = Scenario> {
+    scenarios: TScenario[];
+    /** Effect-size threshold the CI lower bound must clear, in the judge's native
+     *  scale. Default 0.5. Equality holds; CI.low must be greater than this value. */
+    deltaThreshold?: number;
+    /** Bootstrap CI confidence. Default 0.95. */
+    confidence?: number;
+    /** Minimum paired holdout observations to claim significance. Default 3. */
+    minProductiveRuns?: number;
+    /** Bootstrap resamples. Default 2000. */
+    resamples?: number;
+    /** Fixed bootstrap seed for deterministic verdicts. Default 1337. */
+    bootstrapSeed?: number;
+}
+/**
+ * Composable held-out gate: ships only when the PAIRED bootstrap CI lower bound
+ * of the candidate-minus-baseline composite delta clears `deltaThreshold`.
+ */
+declare function heldOutGate<TArtifact, TScenario extends Scenario>(options: HeldOutGateOptions<TScenario>): Gate<TArtifact, TScenario>;
+
 /**
  * @module
  * Composable placebo / neutralization promotion gate.
@@ -747,6 +3223,274 @@ interface NeutralizationGateOptions<TScenario extends Scenario = Scenario> {
  */
 declare function neutralizationGate<TArtifact, TScenario extends Scenario>(options: NeutralizationGateOptions<TScenario>): Gate<TArtifact, TScenario>;
 
+/**
+ * Power preflight — "can this budget detect the effect you are hunting?"
+ *
+ * The failure it prevents (measured, twice): a live prompt-improvement campaign ran
+ * 333 sandbox cells over 5.6 hours and produced a +0.08 holdout lift the ship gate
+ * (paired bootstrap, CI.low > 0.05) could not distinguish from zero — because at
+ * that holdout size and worker variance the MINIMUM DETECTABLE lift was larger than
+ * any effect a prompt change plausibly produces. The budget was spent learning what
+ * a 30-second calculation on the baseline cells already knew. No eval framework we
+ * know of surfaces this; every underpowered improvement run everywhere ends in an
+ * uninformative "hold".
+ *
+ * Model: the ship rule is `CI.low(paired Δ) > deltaThreshold`. Approximating the
+ * bootstrap CI as normal, `CI.low ≈ effect − z·sd_Δ/√n`, so the smallest shippable
+ * true effect is `MDE = deltaThreshold + z·sd_Δ/√n`. The paired-delta SD is unknown
+ * before the candidate exists; we bound it by the zero-correlation case
+ * `sd_Δ ≤ √2·sd_baseline` — a CONSERVATIVE (upper) MDE, which is the correct
+ * direction for a warning. Pairing is per cell (`scenario:rep`), so reps multiply n.
+ *
+ * Standalone by design: feed it any baseline composites (a `gate:'none'` run, a
+ * live-proof table) BEFORE budgeting the real search; `selfImprove` also attaches
+ * it to every result and warns when the run was structurally unable to ship.
+ */
+interface PowerPreflightOptions {
+    /** Per-cell baseline composites on the HOLDOUT scenarios (one per scenario:rep cell). */
+    baselineComposites: number[];
+    /** Paired observations the budgeted comparison will produce
+     *  (holdout scenarios × reps). Defaults to `baselineComposites.length`. */
+    pairedN?: number;
+    /** The ship gate's effect-size threshold. Default 0.05 (defaultProductionGate). */
+    deltaThreshold?: number;
+    /** CI confidence the gate uses. Default 0.95. */
+    confidence?: number;
+    /** True when the holdout is scored by the SAME judge/scorer family as the gate
+     *  (selfImprove's default composition — one judge scores everything). Under a
+     *  shared channel, raising paired n reduces only the IDIOSYNCRATIC noise share;
+     *  systematic judge bias is untouched, so the MDE here is a lower bound and the
+     *  only full debiaser is an independent second scoring channel
+     *  (recursive-self-improvement S1c, closed form in EXP-023 P0). Default false. */
+    sharedScorerChannel?: boolean;
+}
+interface PowerPreflight {
+    /** Paired observations the comparison will have. */
+    n: number;
+    /** Baseline per-cell composite standard deviation (the variance the effect must beat). */
+    sd: number;
+    /** Minimum detectable lift: the smallest TRUE effect the gate could ship at this budget. */
+    mde: number;
+    /** Baseline holdout composite mean. */
+    baselineMean: number;
+    /** Headroom to a perfect 1.0 composite (the largest achievable lift on a [0,1] judge). */
+    headroom: number;
+    /** True when even the largest achievable effect (headroom) is below the MDE —
+     *  the run is structurally unable to ship regardless of proposal quality.
+     *  Only asserted for [0,1]-scaled judges (see `scaleAssumed`). */
+    underpowered: boolean;
+    /** True when composites look [0,1]-scaled; headroom/underpowered are only
+     *  meaningful under that convention (0-100 judges get mde/sd/n but no verdict). */
+    scaleAssumed: boolean;
+    deltaThreshold: number;
+    confidence: number;
+    /** Set when the holdout shares the gate's scoring channel: more cells cannot
+     *  buy back systematic judge bias — treat the MDE as a lower bound. */
+    sharedChannelCaveat?: string;
+    /** One actionable sentence for humans and logs. */
+    recommendation: string;
+}
+/** Estimate the minimum detectable lift a paired-holdout improvement run can
+ *  ship at a given budget, from the baseline holdout composites — call it BEFORE
+ *  spending a search to learn whether the effect you are hunting is even
+ *  observable at this holdout size and worker variance. */
+declare function powerPreflight(opts: PowerPreflightOptions): PowerPreflight;
+
+/**
+ * Pareto frontier — multi-objective optimization over candidate runs.
+ *
+ * Lifted from ADC pareto.ts and blueprint-agent frontier.ts. When you're
+ * trading off (cost, latency, quality) or (passRate, tokenBudget,
+ * ttfb), you rarely have a single "winner" — you have a set of
+ * non-dominated candidates. This module exposes:
+ *
+ *   - `paretoFrontier`: filter a set of candidates to the non-dominated ones
+ *   - `dominates`: does A dominate B across all objectives?
+ *
+ * Each objective is declared with a direction: 'maximize' (higher=better)
+ * or 'minimize' (lower=better). Candidates are any object; pass an
+ * `objective(candidate)` accessor.
+ */
+type Direction = 'maximize' | 'minimize';
+
+/**
+ * Promotion policy over the evidence VECTOR — the substrate's answer to "never
+ * collapse the multi-objective promotion decision into one scalar." A
+ * `defaultProductionGate` is one opinionated composition; this module factors
+ * the decision into two reusable pieces so MANY policies can compete over the
+ * SAME evidence (the quant-desk pattern: one evidence bus, plural strategies):
+ *
+ *   buildEvidenceVector(ctx, objectives, opts) -> EvidenceVector   // the bus
+ *   PromotionPolicy = (ev: EvidenceVector) => GateResult           // a strategy
+ *   paretoPolicy(ev)                                               // the default strategy
+ *   paretoSignificanceGate(options): Gate                          // bus + policy as a Gate
+ *
+ * The Pareto policy is SYMMETRIC multi-objective: every objective is BOTH a
+ * potential gain source AND a safety floor (unlike `defaultProductionGate`,
+ * where only `composite` can win and `criticalDimensions` are pure floors). A
+ * candidate ships iff it weakly DOMINATES the baseline at the confidence level —
+ * no objective credibly worse (CI floor breach) AND at least one objective
+ * credibly better (CI gain). Insufficient evidence on ANY axis -> need_more_work
+ * (NOT folded into hold: "gather more reps" and "reject" are different actions).
+ *
+ * Cost/latency are NOT CI axes here — `GateContext` carries only an aggregate
+ * per-side cost, no per-cell observation vector to bootstrap. Treat them as hard
+ * constraints (compose with a budget gate via `composeGate`), not faked CIs.
+ */
+
+/** Where an objective's per-cell scalar comes from. `composite` reads the
+ *  judge's composite; `dimension` reads a named per-dimension score. */
+type ObjectiveSource = {
+    kind: 'composite';
+} | {
+    kind: 'dimension';
+    dimension: string;
+};
+interface PromotionObjective {
+    /** Stable label used in reports + `contributingGates`. */
+    name: string;
+    source: ObjectiveSource;
+    /** 'maximize' (quality dims) or 'minimize' (error/risk/length dims). Orients
+     *  the paired delta so a positive bootstrap always means "candidate better". */
+    direction: Direction;
+    /** The good-direction paired-delta CI lower bound must EXCEED this to count
+     *  as a significant gain on this axis. Interpreted in the judge's native
+     *  scale. Default 0 (⇒ "confidently better"). */
+    gainThreshold?: number;
+    /** A floor breach (regression) is declared when the good-direction CI lower
+     *  bound is below −floorTolerance. When omitted it auto-scales off observed
+     *  magnitudes (0.05 on [0,1], 5 on 0-100), matching `dimensionRegressions`. */
+    floorTolerance?: number;
+}
+/** Per-axis verdict from the good-direction paired bootstrap. */
+type AxisVerdict = 'improved' | 'regressed' | 'flat' | 'few_runs';
+interface AxisEvidence {
+    name: string;
+    source: ObjectiveSource;
+    direction: Direction;
+    /** Paired bootstrap on the GOOD-DIRECTION delta (oriented by `direction`):
+     *  a positive value means the candidate is better on this axis. */
+    bootstrap: PairedBootstrapResult;
+    /** Paired observations contributing to this axis. */
+    n: number;
+    gainThreshold: number;
+    floorTolerance: number;
+    verdict: AxisVerdict;
+}
+interface EvidenceVector {
+    /** One entry per objective — NOTHING averaged across axes. */
+    axes: AxisEvidence[];
+    /** Smallest paired n across axes that produced observations — the binding
+     *  evidence-sufficiency constraint. 0 when no axis produced observations. */
+    minN: number;
+    /** Aggregate per-side cost from the gate context (a constraint input, not a
+     *  CI axis — see the module header). */
+    cost: {
+        candidate: number;
+        baseline: number;
+    };
+}
+/** A promotion strategy: a pure function from the evidence vector to a verdict.
+ *  Many policies can run over the same `EvidenceVector` and disagree — that's
+ *  the point (competing strategies, shared evidence). */
+type PromotionPolicy = (ev: EvidenceVector) => GateResult;
+interface BuildEvidenceVectorOptions {
+    /** Minimum paired observations before an axis can claim significance; below
+     *  it the axis is `few_runs`. Default 3. */
+    minProductiveRuns?: number;
+    /** Confidence level for every axis bootstrap. Default 0.95. */
+    confidence?: number;
+    /** Bootstrap resamples. Default 2000. */
+    resamples?: number;
+    /** Fixed bootstrap seed for a deterministic, reproducible verdict. Default 1337. */
+    seed?: number;
+}
+/**
+ * The Evidence Bus. For each objective, pair candidate vs baseline by full
+ * cellId and bootstrap a CI on the good-direction paired delta. Reuses the
+ * exact `pairHoldout` + `pairedBootstrap` machinery the held-out gate uses, so
+ * a single source of truth governs pairing granularity + scale handling.
+ */
+declare function buildEvidenceVector<TArtifact, TScenario extends Scenario>(ctx: GateContext<TArtifact, TScenario>, objectives: PromotionObjective[], opts?: BuildEvidenceVectorOptions): EvidenceVector;
+/**
+ * The default strategy: symmetric multi-objective Pareto significance. Ship iff
+ * the candidate weakly dominates the baseline at the confidence level — no axis
+ * credibly worse AND ≥1 axis credibly better. Floor breach on any axis → hold
+ * (anti-Goodhart, dominates everything). Insufficient evidence on any axis →
+ * need_more_work. Statistically equivalent → hold (never ship noise).
+ */
+declare const paretoPolicy: PromotionPolicy;
+interface ParetoSignificanceGateOptions extends BuildEvidenceVectorOptions {
+    /** The objective vector. Every axis is both a gain source and a safety floor. */
+    objectives: PromotionObjective[];
+    /** Strategy applied to the evidence vector. Default `paretoPolicy`. Override
+     *  to run a stricter/looser strategy over the SAME bus (competing policies). */
+    policy?: PromotionPolicy;
+    /** Override the gate name in reports. */
+    name?: string;
+}
+/**
+ * Wrap the bus + a policy as a `Gate`. Plugs into the existing
+ * `runImprovementLoop({ gate })` slot and composes via `composeGate`; default
+ * loop behavior is unchanged because consumers opt in by passing this gate.
+ */
+declare function paretoSignificanceGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(options: ParetoSignificanceGateOptions): Gate<TArtifact, TScenario>;
+
+/**
+ * Pre-registered hypotheses — declare what you're testing BEFORE the
+ * run, check it AFTER. Prevents p-hacking, optional stopping, and the
+ * "we ran until it looked good" failure mode.
+ *
+ * Manifest is a plain JSON-friendly object. Sign it with a content hash
+ * + timestamp; the registered record becomes immutable. Post-run,
+ * evaluate the manifest against observed results — the library refuses
+ * to let you re-interpret a different metric as the declared one.
+ */
+interface HypothesisManifest {
+    id: string;
+    /** Human prose — goes into the audit trail. */
+    hypothesis: string;
+    /** Metric the hypothesis claims to move. */
+    metric: string;
+    /** 'increase' = candidate should score higher than baseline; 'decrease' = lower. */
+    direction: 'increase' | 'decrease';
+    /** Minimum effect size to count (same units as the metric). */
+    minEffect: number;
+    /** Alpha threshold. */
+    alpha: number;
+    /** Target statistical power at which sample size was pre-computed. */
+    power: number;
+    /** Declared N per arm before running. */
+    preRegisteredN: number;
+    /** ISO8601 timestamp the manifest was registered. */
+    registeredAt: string;
+    /** Optional identifiers to tie into the trace corpus. */
+    baselineLabel?: string;
+    candidateLabel?: string;
+}
+/**
+ * Identifier for the hashing scheme used to produce `contentHash`.
+ *
+ * `'sha256-content'` — sha256 hex over the canonicalized manifest with
+ * the `contentHash` and `algo` fields stripped. Held as a string union
+ * so future schemes can be added without breaking parsers; SignedManifest
+ * values without `algo` deserialize cleanly because the field is optional.
+ */
+type SignedManifestAlgo = 'sha256-content';
+interface SignedManifest extends HypothesisManifest {
+    /** sha256 hex of canonicalized manifest (everything except contentHash and algo). */
+    contentHash: string;
+    /**
+     * Algorithm string describing how `contentHash` was produced.
+     *
+     * Optional on the type so serialized manifests without it still parse,
+     * but ALWAYS populated by {@link signManifest}. Consumers that want to
+     * enforce a known algorithm should reject manifests where this field
+     * is missing or unrecognized.
+     */
+    algo?: SignedManifestAlgo;
+}
+
 /**
  * Anytime-valid sequential promotion gate — an e-process (betting
  * test-martingale, see `eProcess` in `statistics.ts`) over paired
@@ -1299,6 +4043,183 @@ declare function surfaceContentHash(surface: MutableSurface): `sha256:${string}`
 /** Short loop key derived from the same content identity as provenance. */
 declare function surfaceHash(surface: MutableSurface): string;
 
+/**
+ * `runOptimization` — the improvement loop body. Runs N generations: the
+ * `SurfaceProposer` proposes K candidate surfaces per generation, each
+ * candidate runs a campaign (the measurement), and only a candidate that beats
+ * the single global incumbent becomes the next generation's parent.
+ * Proposer-agnostic — the same loop runs an evolutionary population mutator
+ * (`evolutionaryProposer`) or any reflective / agentic proposer; they differ
+ * only in how `propose()` picks candidates.
+ *
+ * This is `runLoop`'s shape (plan → measure → decide) specialized to surface
+ * improvement: `proposer.propose` = plan, `runCampaign` = the measurement
+ * (which runs the worker behind `dispatch`), the mean-composite ranking = the
+ * validator, `proposer.decide` = the stop check.
+ *
+ * The gated-promotion shell (`runImprovementLoop`) wraps this with a holdout
+ * re-score + release gate + optional PR.
+ */
+
+interface RunOptimizationBaseOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch'> {
+    /** Initial mutable surface (typically system prompt or addendum). */
+    baselineSurface: MutableSurface;
+    /** Dispatcher that takes the CURRENT surface + scenario → artifact. */
+    dispatchWithSurface: (surface: MutableSurface, scenario: TScenario, ctx: Parameters<RunCampaignOptions<TScenario, TArtifact>['dispatch']>[1]) => Promise<TArtifact>;
+    /** The candidate-generation strategy. Wrap a population `Mutator` via
+     *  `evolutionaryProposer({ mutator })`, or pass any reflective / agentic
+     *  proposer that implements `SurfaceProposer`. */
+    proposer: SurfaceProposer;
+    populationSize: number;
+    maxGenerations: number;
+    /** @deprecated The loop has one global incumbent and can promote only the
+     *  single candidate that beats it. Retained for source compatibility. */
+    promoteTopK?: number;
+    /** DEPTH knob forwarded to the proposer's `propose()` — max iterations the
+     *  agentic generator may take per candidate. */
+    maxImprovementShots?: number;
+    /** Optional analysis report forwarded to `propose()`. Opaque here; the
+     *  proposer types it. */
+    report?: unknown;
+    /** Structured findings forwarded to `propose()` as `ctx.findings`. A
+     *  findings producer emits these from the
+     *  generation's traces; findings-grounded proposers consume them. Opaque here;
+     *  the proposer types its `TFindings`. Empty when no producer is wired. */
+    findings?: unknown[];
+    /** Per-generation findings producer. Runs once on the BASELINE campaign
+     *  (as `generation: -1`, the baseline convention) before generation 0
+     *  proposes — so even a single-generation run proposes with trace context —
+     *  and then after each generation's candidates are scored with that
+     *  generation's results; whatever it returns REPLACES `ctx.findings` for the
+     *  NEXT `propose()`, so the diagnosis is refreshed each round instead
+     *  of being a static one-shot. Generic by design: the substrate does not
+     *  import an analyst — the consumer plugs its trace-analyst registry / HALO
+     *  here (reading the per-candidate `runDir` traces). When absent, findings
+     *  stay the static `opts.findings`. */
+    analyzeGeneration?: (input: {
+        generation: number;
+        runDir: string;
+        candidates: Array<{
+            surfaceHash: string;
+            campaign: CampaignResult<TArtifact, TScenario>;
+            composite: number;
+        }>;
+        history: GenerationRecord[];
+        /** Shared run spend account and receipt attribution phase. */
+        costLedger?: CostLedger;
+        costPhase?: string;
+    }) => Promise<unknown[]>;
+}
+type RunOptimizationOptions<TScenario extends Scenario, TArtifact> = RunOptimizationBaseOptions<TScenario, TArtifact>;
+interface RunOptimizationResult<TArtifact, TScenario extends Scenario> {
+    generations: Array<{
+        record: GenerationRecord;
+        surfaces: Array<{
+            surfaceHash: string;
+            surface: MutableSurface;
+            campaign: CampaignResult<TArtifact, TScenario>;
+        }>;
+    }>;
+    winnerSurface: MutableSurface;
+    winnerSurfaceHash: string;
+    /** Proposer label for the promoted surface. Present when the winning
+     *  candidate came from a `ProposedCandidate` (a reflective proposer);
+     *  absent when the winner is the baseline or a bare-surface mutator. */
+    winnerLabel?: string;
+    /** Proposer rationale for the promoted surface — the "because Z" that
+     *  motivated the winning change. Survives to `SelfImproveResult` and the
+     *  emitted provenance record. Absent when the winner is the baseline. */
+    winnerRationale?: string;
+    baselineCampaign: CampaignResult<TArtifact, TScenario>;
+    /** Run-wide spend, including agents, proposers, analysts, and judges. */
+    cost: CostLedgerSummary;
+    /** The GEPA Pareto frontier across every scored surface (baseline + all
+     *  generations) by per-scenario objective vector — the non-dominated set.
+     *  Each generation's `propose()` received the frontier-so-far as
+     *  `ctx.paretoParents`; this is the final frontier. A surface here that is
+     *  NOT the winner is uniquely best on some scenario the winner loses on. */
+    paretoFrontier: ParetoParent[];
+}
+/**
+ * Improvement loop body: N generations of propose → campaign → rank, maintaining a Pareto frontier and one global incumbent across generations.
+ */
+declare function runOptimization<TScenario extends Scenario, TArtifact>(opts: RunOptimizationOptions<TScenario, TArtifact>): Promise<RunOptimizationResult<TArtifact, TScenario>>;
+
+/**
+ * `runImprovementLoop` — the gated-promotion shell around the improvement
+ * loop body (`runOptimization`). Proposes candidate surfaces via the
+ * `SurfaceProposer`, re-scores the winner against the baseline on a
+ * holdout set, runs the release gate, and optionally opens a PR.
+ *
+ * Role vocabulary (see docs/design/loop-taxonomy.md):
+ *   - PROPOSER   = the `SurfaceProposer` (evolutionary GEPA mutator OR
+ *                  reflective analyst). Proposes candidate SURFACES — the
+ *                  worker's system prompt / tool config — NOT conversation
+ *                  turns.
+ *   - MEASUREMENT= `runCampaign`. Scores one surface by running the worker
+ *                  (via `dispatch`) over scenarios and judging the output.
+ *   - WORKER     = the agent harness in the sandbox, invoked behind the
+ *                  topology-opaque `dispatch` seam — never referenced here.
+ *
+ * Distinct from `runLoop` in `@tangle-network/agent-runtime`, which is the
+ * INNER conversation loop (execution driver ↔ workers in a sandbox). `runImprovementLoop`
+ * is the OUTER loop: it improves the surface that those workers run.
+ *
+ * Hard-refuses unsafe configurations:
+ *   - `tracing: 'off'` when a proposer is wired (improvement is unattributable)
+ *   - `autoOnPromote: 'config'` — DEFERRED to Pass B; v0.40 only ships
+ *     `'pr'` and `'none'`.
+ */
+
+type RunImprovementLoopOptions<TScenario extends Scenario, TArtifact> = RunOptimizationOptions<TScenario, TArtifact> & {
+    /** Holdout scenarios kept OUT of the training optimization pool — used
+     *  ONLY to score baseline vs winner for the gate. */
+    holdoutScenarios: TScenario[];
+    /** Promotion gate. Substrate strongly recommends `defaultProductionGate`
+     *  for production wiring (composes red-team / reward-hacking / canary /
+     *  heldout). */
+    gate: Gate<TArtifact, TScenario>;
+    /** What to do when the gate ships:
+     *   - `'pr'`: open a PR via `openAutoPr`
+     *   - `'none'`: just report — caller decides what to do with the winner
+     *  v0.40 does NOT support `'config'` (live-runtime self-mutation) —
+     *  deferred to Pass B behind safety stack. */
+    autoOnPromote: 'pr' | 'none';
+    /** GH owner / repo for the auto-PR. Required when autoOnPromote === 'pr'. */
+    ghOwner?: string;
+    ghRepo?: string;
+    /** Optional render override — substrate writes a diff-shaped surface; pass
+     *  a function to format the promoted surface differently. */
+    renderPromotedDiff?: (winnerSurface: MutableSurface, baselineSurface: MutableSurface) => string;
+    /** Placebo control. When supplied AND the winner differs from baseline, the
+     *  loop scores a THIRD holdout arm: the winner surface with its content
+     *  footprint-matched-blanked by this function (typically via `neutralizeText`).
+     *  Its scores are exposed to the gate as `ctx.neutralizedJudgeScores`, letting
+     *  a `neutralizationGate` reject a win whose lift survives blanking the content
+     *  (decorative — driven by footprint, not content). Costs one extra holdout
+     *  campaign; omit to skip. Return a byte/layout-matched blank of the winner. */
+    neutralize?: (winnerSurface: MutableSurface, baselineSurface: MutableSurface) => MutableSurface;
+};
+interface RunImprovementLoopResult<TArtifact, TScenario extends Scenario> extends RunOptimizationResult<TArtifact, TScenario> {
+    baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
+    winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
+    gateResult: Awaited<ReturnType<Gate<TArtifact, TScenario>['decide']>>;
+    /** Unified baseline→winner surface diff. Computed UNCONDITIONALLY (not only
+     *  when `autoOnPromote === 'pr'`) so the diff that the gate decided on is
+     *  always present on the result + in the emitted provenance record. Empty
+     *  string when winner == baseline (no change to diff). */
+    promotedDiff: string;
+    prResult?: ReturnType<typeof openAutoPr>;
+}
+/**
+ * Gated-promotion shell over `runOptimization`: scores the winner against the baseline on a holdout set, runs the release gate, and optionally opens a PR.
+ */
+declare function runImprovementLoop<TScenario extends Scenario, TArtifact>(opts: RunImprovementLoopOptions<TScenario, TArtifact>): Promise<RunImprovementLoopResult<TArtifact, TScenario>>;
+/**
+ * Default surface diff renderer: produces a unified baseline/winner text diff for prompt surfaces or a worktree-ref summary for code surfaces.
+ */
+declare function defaultRenderDiff(winnerSurface: MutableSurface, baselineSurface: MutableSurface): string;
+
 /**
  * `compareProposers` — a head-to-head lift benchmark across surface proposers
  * on ONE corpus. This is the forcing function: optimizer quality (GEPA
@@ -1413,39 +4334,297 @@ interface OptimizerEntryConfig<TScenario extends Scenario, TArtifact> {
     /** Optional analysis report forwarded to `propose()` as `ctx.report`. */
     report?: unknown;
 }
-/** GEPA, reflection-only (single-parent, no Pareto combine). */
-declare function gepaReflectionEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
-/** GEPA with the Pareto frontier + combine-complementary-lessons. */
-declare function gepaParetoEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
-/** SkillOpt patch-mode hill-climb. Runs findings-BLIND: `runSkillOpt` owns its
- *  own epoch acceptance/budget loop and does not thread `analyzeGeneration`, so
- *  `config.findings` is intentionally NOT forwarded here. In a findings-fed
- *  comparison this entry is the blind control — do not read its result as
- *  findings-fed. (Threading findings into the SkillOpt epoch loop is a separate
- *  refactor, deferred not faked.) */
-declare function skillOptEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
-/** FAPO reviewed-escalation policy. This is an orchestration layer over
- * level-specific proposers, not a new mutation operator:
- * prompt -> parameter -> structural, with scope + reviewer + plateau rules in
- * `fapoProposer`. The prompt proposer defaults to GEPA+Pareto because that is
- * the package's strongest prompt-tier proposer; parameter/structural proposers
- * are opt-in so we do not fake code-generation inside agent-eval. */
-interface FapoEntryConfig<TScenario extends Scenario, TArtifact> extends OptimizerEntryConfig<TScenario, TArtifact> {
-    /** Override the prompt-level proposer. Default: `gepaProposer({ combineParents: true })`. */
-    promptProposer?: SurfaceProposer;
-    /** Parameter/config-level proposer. If omitted, `parameterCandidates` builds one. */
-    parameterProposer?: SurfaceProposer;
-    /** Structural/code-level proposer, typically supplied by agent-runtime. */
-    structuralProposer?: SurfaceProposer;
-    /** Convenience: build a `parameterSweepProposer` from these candidates. */
-    parameterCandidates?: readonly ParameterCandidate[];
-    /** FAPO policy knobs: scope, reviewer, plateau thresholds. */
-    fapo?: Omit<FapoProposerOptions, 'proposers' | 'promptProposer' | 'parameterProposer' | 'structuralProposer'>;
+/** GEPA, reflection-only (single-parent, no Pareto combine). */
+declare function gepaReflectionEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
+/** GEPA with the Pareto frontier + combine-complementary-lessons. */
+declare function gepaParetoEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
+/** SkillOpt patch-mode hill-climb. Runs findings-BLIND: `runSkillOpt` owns its
+ *  own epoch acceptance/budget loop and does not thread `analyzeGeneration`, so
+ *  `config.findings` is intentionally NOT forwarded here. In a findings-fed
+ *  comparison this entry is the blind control — do not read its result as
+ *  findings-fed. (Threading findings into the SkillOpt epoch loop is a separate
+ *  refactor, deferred not faked.) */
+declare function skillOptEntry<TScenario extends Scenario, TArtifact>(config: OptimizerEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
+/** FAPO reviewed-escalation policy. This is an orchestration layer over
+ * level-specific proposers, not a new mutation operator:
+ * prompt -> parameter -> structural, with scope + reviewer + plateau rules in
+ * `fapoProposer`. The prompt proposer defaults to GEPA+Pareto because that is
+ * the package's strongest prompt-tier proposer; parameter/structural proposers
+ * are opt-in so we do not fake code-generation inside agent-eval. */
+interface FapoEntryConfig<TScenario extends Scenario, TArtifact> extends OptimizerEntryConfig<TScenario, TArtifact> {
+    /** Override the prompt-level proposer. Default: `gepaProposer({ combineParents: true })`. */
+    promptProposer?: SurfaceProposer;
+    /** Parameter/config-level proposer. If omitted, `parameterCandidates` builds one. */
+    parameterProposer?: SurfaceProposer;
+    /** Structural/code-level proposer, typically supplied by agent-runtime. */
+    structuralProposer?: SurfaceProposer;
+    /** Convenience: build a `parameterSweepProposer` from these candidates. */
+    parameterCandidates?: readonly ParameterCandidate[];
+    /** FAPO policy knobs: scope, reviewer, plateau thresholds. */
+    fapo?: Omit<FapoProposerOptions, 'proposers' | 'promptProposer' | 'parameterProposer' | 'structuralProposer'>;
+}
+/**
+ * Build a `ProposerEntry` that runs the full FAPO escalation policy (prompt → parameter → structural) as a single comparable optimizer entry.
+ */
+declare function fapoEscalationEntry<TScenario extends Scenario, TArtifact>(config: FapoEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
+
+/**
+ * Artifact validators.
+ *
+ * Generic "score a produced artifact" primitive. Tax uses it for PDF form
+ * correctness, research for sourced briefs, browser for task assertions, coding
+ * for social posts. One interface, many validators; all plug into
+ * `BenchmarkRunner` the same way.
+ *
+ * A validator receives an `Artifact` (file on disk, JSON blob, text, binary)
+ * plus a `ValidationContext` (scenario id, the turns that produced it) and
+ * returns a `ValidationResult` with pass/fail + 0..1 score + structured
+ * issues.
+ */
+interface Artifact {
+    /** Logical kind — validators type-guard on this */
+    kind: 'file' | 'json' | 'text' | 'binary' | string;
+    /** Filesystem-style path, optional */
+    path?: string;
+    /** String content for text/json/file kinds */
+    content?: string;
+    /** Binary content (if kind === 'binary') */
+    bytes?: Uint8Array;
+    /** Caller-supplied metadata (mimeType, sha256, size, etc.) */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Validator-output verdict — substrate primitive for "did this output pass,
+ * and how well?"
+ *
+ * Used by:
+ *   - `@tangle-network/agent-eval/matrix` — verdict per cell in the cartesian.
+ *   - `@tangle-network/agent-runtime` — Validator<Output, Verdict = DefaultVerdict>.
+ *     Runtime keeps `Validator` because it's coupled to runtime-shaped
+ *     `ValidationCtx` (iteration, signal, traceEmitter); the verdict TYPE
+ *     itself is a substrate concept and lives here.
+ *
+ * Repo layering: agent-eval is the substrate (no upward deps). Both
+ * agent-runtime and agent-knowledge consume this type FROM agent-eval —
+ * never the other way around. See CLAUDE.md "Repo layering" for the rule.
+ */
+/**
+ * Minimal verdict shape — `valid` + `score` are required; `scores` +
+ * `notes` are optional surface. Validators that need richer shapes
+ * parameterise `Validator<Output, MyVerdict>` with their own type.
+ *
+ * Need structured extras? Extend DefaultVerdict with typed fields — never
+ * serialize extras into `notes`.
+ */
+interface DefaultVerdict {
+    /** Whether the output meets the validator's pass criteria. */
+    valid: boolean;
+    /** Aggregate score in [0, 1]. Drivers use this for winner selection. */
+    score: number;
+    /** Per-dimension scores. Free-form; weighted into `score` by the validator. */
+    scores?: Record<string, number>;
+    /** Human-readable rationale; surfaces in trace + final-result `winner.verdict`. */
+    notes?: string;
+}
+
+/**
+ * Completion verifier — the task-completion oracle.
+ *
+ * Answers the only eval question that is not a proxy: did the agent actually
+ * COMPLETE the task — produce every required deliverable, persisted and
+ * correct — rather than describe what should be done. A fluent transcript
+ * that never produces the artifact scores zero here.
+ *
+ * Per requirement, a two-stage check:
+ *   1. Structural — a produced item (vault artifact / approved proposal /
+ *      tool call) of the right kind is matched against the requirement and
+ *      carries non-empty content. Deterministic; no LLM.
+ *   2. Correctness — only if structurally present AND the matched item
+ *      carries content, one targeted check decides whether that item
+ *      actually fulfils the requirement. A hallucinated artifact fails here;
+ *      an absent one already failed stage 1.
+ *
+ * `completionRate` is satisfied / MEASURABLE requirements (unmeasured rows —
+ * checker failures — are excluded from the denominator, never scored as
+ * zeros). Quality dimensions are meaningless on an incomplete task — callers
+ * gate on `fullyComplete` / `completionRate` before scoring quality.
+ */
+
+/** What kind of produced state can satisfy a requirement structurally. */
+type SatisfiedBy = 'artifact' | 'proposal' | 'tool-call' | 'any';
+interface CompletionRequirement {
+    /** Stable id from the task gold (e.g. a persona's `expected_requirements[].req_id`). */
+    reqId: string;
+    /** Human-readable description of the required deliverable. */
+    title: string;
+    /** Optional kind/category hint, matched against a produced item's kind. */
+    category?: string;
+    /** What produced state satisfies this requirement. Defaults to 'any'. */
+    satisfiedBy?: SatisfiedBy;
+}
+interface ProducedProposal {
+    id: string;
+    title: string;
+    status: 'pending' | 'approved' | 'rejected';
+    /** Optional persisted body — when present, enables a correctness check. */
+    content?: string;
+}
+/** Everything observable about what a run actually produced. */
+interface ProducedState {
+    /** Persisted vault artifacts. Reuses the shared `Artifact` shape. */
+    artifacts: Artifact[];
+    /** Proposals / filings the agent created. */
+    proposals: ProducedProposal[];
+    /** Names of tools the agent invoked. */
+    toolCalls: string[];
+}
+interface RequirementCheck {
+    reqId: string;
+    title: string;
+    /** A produced item of the right kind matched the requirement, non-empty. */
+    structurallyPresent: boolean;
+    /**
+     * Whether the matched item actually fulfils the requirement. `null` when
+     * not structurally present, when the matched item carries no content
+     * to assess, or when the correctness check itself failed (`unmeasured`).
+     */
+    correct: boolean | null;
+    /** structurallyPresent && !unmeasured && correct !== false. */
+    satisfied: boolean;
+    /**
+     * Set when the correctness check itself errored (LLM call failure or an
+     * unparseable response after retry). The requirement's fulfilment is
+     * UNKNOWN — `correct` stays null, `satisfied` is false, and
+     * `completionVerdict` excludes the row from `completionRate`'s
+     * denominator. Never folded into a zero: a synthetic zero is
+     * indistinguishable from a real failure (see `JudgeParseError`).
+     */
+    unmeasured?: true;
+    /** Why the correctness check could not be measured (present iff `unmeasured`). */
+    unmeasuredReason?: string;
+    /** Human-readable evidence for the verdict. */
+    evidence: string[];
+}
+/** Extends the substrate verdict spine: `valid` = `fullyComplete` and
+ *  `score` = `completionRate` — derived in `completionVerdict()`, the one
+ *  place those equalities hold by construction. */
+interface CompletionVerdict extends DefaultVerdict {
+    taskId: string;
+    requirements: RequirementCheck[];
+    /** satisfied / MEASURABLE requirements (unmeasured rows leave the denominator). */
+    completionRate: number;
+    /** Every measurable requirement satisfied (false when anything is unmeasured). */
+    fullyComplete: boolean;
+    /** Requirements whose correctness check errored — reported, never scored as zero. */
+    unmeasuredCount: number;
+}
+/**
+ * Decides whether a produced item's content actually fulfils a requirement.
+ * Injected so the structural verifier stays pure and unit-testable; the
+ * production implementation is `createLlmCorrectnessChecker`.
+ */
+type CorrectnessChecker = (requirement: CompletionRequirement, content: string) => Promise<{
+    correct: boolean;
+    reason: string;
+}>;
+
+/**
+ * Produced-state extraction — normalize a run's runtime event stream into the
+ * typed `ProducedState` the completion oracle consumes.
+ *
+ * `ProducedState` answers "what did the agent actually produce" — vault
+ * artifacts, proposals, tool calls. The runtime emits these as a stream of
+ * events; this module is the single normalization point from that stream to
+ * the shape `verifyCompletion` expects.
+ *
+ * Input is structurally typed (`RuntimeEventLike`) so this module does not
+ * depend on agent-runtime — agent-runtime's `RuntimeStreamEvent` satisfies it
+ * structurally. The `content` on `ArtifactEventLike` and the whole
+ * `proposal_created` variant are the runtime-side enrichments this contract
+ * requires; the runtime emits them, this module consumes them.
+ */
+
+/** A tool the agent invoked. */
+interface ToolCallEventLike {
+    type: 'tool_call';
+    toolName: string;
+}
+/**
+ * An artifact the agent produced. `content` is the enriched field — the
+ * runtime's base `artifact` event carries only metadata; the completion
+ * oracle needs the body to verify the deliverable, so the runtime emits it.
+ */
+interface ArtifactEventLike {
+    type: 'artifact';
+    artifactId: string;
+    name?: string;
+    mimeType?: string;
+    uri?: string;
+    content?: string;
+}
+/** A proposal / filing the agent created. */
+interface ProposalEventLike {
+    type: 'proposal_created';
+    proposalId: string;
+    title: string;
+    status?: 'pending' | 'approved' | 'rejected';
+    content?: string;
 }
 /**
- * Build a `ProposerEntry` that runs the full FAPO escalation policy (prompt → parameter → structural) as a single comparable optimizer entry.
+ * The subset of runtime stream events `extractProducedState` consumes.
+ * agent-runtime's full `RuntimeStreamEvent` union satisfies this structurally;
+ * the `{ type: string }` catch-all keeps the input permissive so callers can
+ * pass the whole unfiltered telemetry stream — unrecognized events are skipped.
  */
-declare function fapoEscalationEntry<TScenario extends Scenario, TArtifact>(config: FapoEntryConfig<TScenario, TArtifact>, name?: string): ProposerEntry;
+type RuntimeEventLike = ToolCallEventLike | ArtifactEventLike | ProposalEventLike | {
+    type: string;
+};
+
+/**
+ * Backend-integrity guard: distinguish "agent failed" from "eval ran against
+ * a stub / unconfigured backend." Without this guard a canonical eval can
+ * silently report `0/N passed` and look like an agent-quality problem when
+ * the LLM was never actually called — the failure mode we just hit running
+ * the 4-vertical parallel eval (legal-sandbox-stub returned hard-coded 33-104
+ * char strings; gtm/creative defaulted to a cli-bridge that wasn't running).
+ *
+ * The shape:
+ *
+ *   const report = summarizeBackendIntegrity(records)
+ *   assertRealBackend(records)   // throws BackendIntegrityError if 100% stub
+ *
+ * A record is "stub-mode" if its `tokenUsage.input === 0 && tokenUsage.output === 0`.
+ * (`costUsd` alone is unreliable — some backends successfully call LLMs but
+ *  don't propagate pricing, producing real tokens with $0 cost.)
+ *
+ * Verdicts:
+ *   - `real`   — at least one record has nonzero token usage
+ *   - `stub`   — every record is stub-mode (eval ran blind)
+ *   - `mixed`  — some records real, some stub (partial backend failure;
+ *                often the 429-cascade or auth-half-failed case)
+ */
+
+interface BackendIntegrityReport {
+    /** Total records inspected. */
+    totalRecords: number;
+    /** Records with input=0 AND output=0 (a stub fingerprint). */
+    stubRecords: number;
+    /** Records with nonzero token usage (real LLM activity). */
+    realRecords: number;
+    /** Records where output>0 but costUsd=0 (real LLM, broken cost ledger). */
+    uncostedRecords: number;
+    /** Sum of input tokens across all records. */
+    totalInputTokens: number;
+    /** Sum of output tokens across all records. */
+    totalOutputTokens: number;
+    /** Sum of costUsd across all records. */
+    totalCostUsd: number;
+    /** Worst-case integrity verdict. */
+    verdict: 'real' | 'mixed' | 'stub';
+    /** Human-readable diagnosis suitable for terminal output. */
+    diagnosis: string;
+}
 
 /**
  * `runProfileMatrix` — the missing keystone between `runAgentMatrix` and the
@@ -1712,6 +4891,22 @@ interface ScoreboardRenderOptions {
  */
 declare function renderScoreboardMarkdown(rows: readonly ScoreboardRow[], opts?: ScoreboardRenderOptions): string;
 
+/**
+ * `runEval` — the simplest preset over `runCampaign`. No optimizer, no
+ * gate, no auto-PR. Just: run scenarios through dispatch, score with
+ * judges, return CampaignResult.
+ *
+ * The 80% case for consumers who want a scorecard, not an improvement loop.
+ */
+
+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>>;
+
 /**
  * `runLineageLoop` — the live adapter that wires the {@link runLineage} DAG's
  * two abstract seams (`step`, `merge`) to the REAL improvement machinery, so the
@@ -2173,6 +5368,119 @@ interface CompositeProposerOptions<TFindings = unknown> {
  *  one generation pool, with per-member provenance labels. */
 declare function compositeProposer<TFindings = unknown>(opts: CompositeProposerOptions<TFindings>): SurfaceProposer<TFindings>;
 
+/**
+ * `evolutionaryProposer` — adapts a stateless `Mutator` (population mutation:
+ * GEPA / AxGEPA / reflective-mutation) into a `SurfaceProposer`. This is
+ * the evolutionary strategy: each generation, mutate the current best surface
+ * into N candidates, measure, select. No generation memory beyond the current
+ * surface; the loop body handles ranking + promotion.
+ *
+ * The reflective alternative is agent-runtime's runtime proposer with a
+ * `reflectiveGenerator` / `agenticGenerator`: it reasons over the report +
+ * trace findings to propose targeted edits rather than blind mutations. Both
+ * conform to `SurfaceProposer`; the improvement loop is identical either way.
+ */
+
+interface EvolutionaryProposerOptions<TFindings = unknown> {
+    mutator: Mutator<TFindings>;
+    /** External findings fed to the mutator each generation. Default: []. */
+    findings?: TFindings[];
+}
+/**
+ * Wrap a stateless `Mutator` (GEPA, AxGEPA, reflective-mutation) as a `SurfaceProposer` that mutates the current best surface into N candidates each generation.
+ */
+declare function evolutionaryProposer<TFindings = unknown>(opts: EvolutionaryProposerOptions<TFindings>): SurfaceProposer<TFindings>;
+
+/**
+ * `gepaProposer` — a reflective `SurfaceProposer` for prompt-tier surfaces.
+ * Each generation it reflects on the prior best candidate's per-scenario
+ * scores + weakest dimensions, asks an LLM to propose targeted rewrites of
+ * the current surface, and returns them as the next population.
+ *
+ * Maps onto the GEPA paper (Agrawal et al., arXiv:2507.19457):
+ *   - *Reflection*: each generation reflects on the best parent's weakest
+ *     dimensions + per-scenario top/bottom scores to propose targeted rewrites.
+ *   - *Pareto frontier*: `runOptimization` maintains the non-dominated set of
+ *     surfaces across generations (per-scenario objective vectors) and supplies
+ *     it as `ctx.paretoParents`. A surface uniquely best on one hard scenario
+ *     survives even when its mean composite is lower.
+ *   - *Combine complementary lessons*: when the frontier has >1 member, the
+ *     first population slot is a merge of those parents' strengths (one LLM
+ *     call citing each parent's winning scenarios). Toggle via `combineParents`.
+ * Dominance is computed by the package-canonical `paretoFrontier` (`pareto.ts`).
+ *
+ * Optional `constraints` move structured-doc guards into the proposer
+ * (preserve H2 section headings, cap sentence-level edits) — useful when
+ * the surface IS a structured procedure like a SKILL.md / runbook /
+ * judge rubric. When `constraints` is omitted, behavior is unchanged.
+ *
+ * The proposer is surface-agnostic — any string surface in any consumer opts
+ * in by selecting it. Reuses the generic reflection primitive
+ * (`buildReflectionPrompt` / `parseReflectionResponse`) and the router client.
+ *
+ * Earns its keep where there is real per-instance signal (which the
+ * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
+ * now provide). For thin-signal surfaces it degrades to plain reflection.
+ * On generation 0 (no history) it reflects on the current surface against
+ * the mutation primitives alone.
+ */
+
+interface GepaProposerConstraints {
+    /** H2 section headings that MUST appear unchanged in every candidate.
+     *  When set, the proposer auto-detects current H2s if this is empty AND
+     *  rejects any candidate that drops or renames a preserved heading.
+     *  Use when the surface is a structured doc (SKILL.md, runbook,
+     *  sectioned system prompt, judge rubric). */
+    preserveSections?: string[];
+    /** Maximum sentence-level edits per candidate vs the parent surface.
+     *  Rejection threshold = maxSentenceEdits × 2 (counts adds + removes).
+     *  Inspired by SkillOpt's edit-budget as a "textual learning rate."
+     *  Cap prevents an LLM rewrite from overwriting useful prior rules. */
+    maxSentenceEdits?: number;
+}
+interface GepaProposerOptions {
+    /** Router transport (apiKey/baseUrl). */
+    llm: LlmClientOptions;
+    /** Model that performs the reflection. */
+    model: string;
+    /** Optional ledger for direct proposer use. Campaign context takes precedence. */
+    costLedger?: CostLedger;
+    /** What is being optimized — appears in the reflection prompt for orientation. */
+    target: string;
+    /** Surface-specific mutation levers offered to the model. */
+    mutationPrimitives?: string[];
+    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
+    evidenceK?: number;
+    /** Reflection sampling temperature. Default 0.7. */
+    temperature?: number;
+    /** Reflection max tokens. Default 6000. */
+    maxTokens?: number;
+    /** Structured-doc constraints. Candidates violating any are rejected
+     *  post-parse and dropped from the returned population. */
+    constraints?: GepaProposerConstraints;
+    /** GEPA combine-complementary-lessons: when the loop supplies a Pareto
+     *  frontier of >1 non-dominated parents (`ctx.paretoParents`), spend one
+     *  slot of the population on a merge of their strengths. Default `true` —
+     *  this is the GEPA-faithful behavior; the merge only fires once the
+     *  frontier has more than one member (generation ≥ 1). Set `false` for
+     *  pure single-parent reflection. */
+    combineParents?: boolean;
+    /** Cap on how many frontier parents feed one combine prompt (highest
+     *  composite first), to bound prompt size. Default 4. */
+    combineMaxParents?: number;
+}
+/**
+ * GEPA reflective proposer: each generation reflects on the weakest scenarios and dimensions to produce targeted prompt rewrites, optionally combining Pareto-frontier parents.
+ */
+declare function gepaProposer(opts: GepaProposerOptions): SurfaceProposer;
+/** Extract H2 headings (`## Foo`) from a markdown surface. Exported for
+ *  consumers building custom mutators that share the same invariant. */
+declare function extractH2Sections(text: string): string[];
+/** Sentence-level edit distance — count distinct add/remove ops between
+ *  two surfaces via a normalised line-by-line set diff. Treats trivial
+ *  whitespace as identical. Exported for tests + consumer-side validators. */
+declare function countSentenceEdits(baseline: string, candidate: string): number;
+
 /**
  * `haloProposer` — wraps the REAL halo-engine (Inference.net's hierarchical
  * agentic trace analyzer, `pip install halo-engine`, repo context-labs/halo)
@@ -2487,6 +5795,113 @@ declare function selectPolicyEditAuthorRows<T extends PolicyEditAuthorScenarioRo
 /** Serialize once and fail before dispatch when author context exceeds its budget. */
 declare function assertPolicyEditAuthorContextBudget(value: unknown, maxChars: number): SerializedJsonBudget;
 
+/**
+ * Typed Ax output for analyst findings.
+ *
+ * Replaces the legacy `findings:string[]` pattern (where every bullet
+ * became a flat-severity `AnalystFinding`) with a structured object
+ * array. Ax binds the field as `findings:json[]` so the provider emits
+ * native structured output; at the kind-factory boundary we Zod-validate
+ * each emitted finding so malformed rows fail loud instead of being
+ * silently lifted with default severity.
+ *
+ * Why not `f.object().array()` directly in the signature? The Ax
+ * signature string `question:string -> findings:json[]` already lets
+ * the provider emit JSON arrays. A Zod boundary is required either
+ * way (the provider can return any JSON), and Zod gives us a single
+ * validation surface independent of which Ax version is installed.
+ */
+
+declare const RawAnalystFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        low: "low";
+        high: "high";
+        critical: "critical";
+        medium: "medium";
+        info: "info";
+    }>;
+    claim: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    evidence_uri: z.ZodString;
+    evidence_excerpt: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    recommended_action: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
+
+/**
+ * Analyst-kind factory — the typed way to define trace analysts.
+ *
+ * A "kind" is a specialized analyst whose actor prompt, tool subset,
+ * and Ax recursion config target one failure-mode lens (failure-mode
+ * classification, knowledge gap discovery, knowledge poisoning, recursive
+ * self-improvement, ...). Kinds emit findings in the typed `RawAnalystFinding`
+ * shape via a JSON-array Ax output; the factory validates each row with
+ * Zod and lifts it into `AnalystFinding[]` with no shape guessing.
+ *
+ * Composition rules:
+ *   - Each kind owns its actor description. No generic "answer this
+ *     question" prompt — the prompt names the failure lens.
+ *   - Each kind picks a narrow tool subset from `ANALYST_TOOL_GROUPS`.
+ *     A kind that never needs full-trace dumps can drop `viewTrace` /
+ *     `viewSpans` and stay cheap.
+ *   - Each kind declares its recursion + parallelism budget. Discovery-
+ *     heavy kinds (failure-mode) get higher `maxDepth`; lens kinds
+ *     (poisoning) usually stay at 0 since they have a tighter brief.
+ *
+ * Optimizer hook: kinds may declare `goldens` — labeled examples used
+ * by `AxMiPRO` / `AxBootstrapFewShot` / `AxGEPA` to fit the actor
+ * description programmatically. Stored on the kind, not the registry,
+ * because the right metric is kind-specific.
+ */
+
+/**
+ * Per-kind specification. The factory turns this into a regular
+ * `Analyst<TraceAnalysisStore>` ready for `AnalystRegistry.register()`.
+ */
+interface TraceAnalystKindSpec {
+    /** Stable id. Appears in finding_id, telemetry, and registry exclusions. */
+    id: string;
+    /** One-sentence description shown in `registry.list()`. */
+    description: string;
+    /** Coarse classification stamped on every emitted finding (`failure-mode`, `knowledge-gap`, ...). */
+    area: string;
+    /** Bump on any breaking change to the actor prompt or output schema. */
+    version: string;
+    /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
+    actorDescription: string;
+    /** Responder system prompt; falls back to a minimal "format the findings" instruction. */
+    responderDescription?: string;
+    /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
+    buildTools: (store: TraceAnalysisStore) => AxFunction[];
+    /** Recursion budget. `maxDepth: 0` disables subagents. */
+    recursion?: {
+        maxDepth: number;
+        maxParallelSubagents?: number;
+    };
+    /** Actor turn cap. Default 12. */
+    maxTurns?: number;
+    /** Runtime char cap. Default 6000. */
+    maxRuntimeChars?: number;
+    /** Cost classification surfaced in `registry.list()` and budget enforcement. */
+    cost: AnalystCost;
+    /** Per-finding-row hook — kinds may reject / rewrite before lifting. */
+    postProcess?: (row: RawAnalystFinding, ctx: AnalystContext) => RawAnalystFinding | null;
+    /** Optional optimizer hook — populated when a kind wants to fit its prompt against labeled examples. */
+    goldens?: TraceAnalystGolden[];
+}
+/**
+ * One labeled example consumed by Ax optimizers (MIPRO / GEPA / Bootstrap).
+ * Each input is the same `{question}` an analyst would receive; `expected`
+ * is the ground-truth finding set a fitted prompt should produce on this
+ * input. Metric: kind-specific (default: F1 on `finding_id` overlap).
+ */
+interface TraceAnalystGolden {
+    question: string;
+    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
+}
+
 /**
  * `traceAnalystProposer` — wraps agent-eval's OWN trace-analyst engine
  * (`AnalystRegistry` over the agentic OTLP reader) as a `SurfaceProposer`.
@@ -2537,6 +5952,793 @@ interface TraceAnalystProposerOptions {
 /** Wrap agent-eval's trace-analyst registry as a SurfaceProposer (prompt-tier). */
 declare function traceAnalystProposer(opts: TraceAnalystProposerOptions): SurfaceProposer;
 
+/**
+ * Reporting helpers — production summaries and paper-quality figures — sit alongside `reporter.ts` rather
+ * than replacing it.
+ *
+ * Three artefacts:
+ *
+ *   - `summaryTable`           Markdown table of per-candidate means,
+ *                            95% bootstrap CIs, BH-adjusted Wilcoxon
+ *                            p-values, and Cohen's d versus a
+ *                            comparator candidate.
+ *   - `paretoChart`         Abstract spec for a cost vs quality
+ *                            scatter, with gate decisions overlaid.
+ *                            Returns numbers + labels — caller
+ *                            chooses the plotting library.
+ *   - `gainHistogram`
+ *                            Per-item paired holdout deltas as a
+ *                            histogram spec (bins + counts + median +
+ *                            CI). Same "data, not images" contract.
+ *
+ * The figure types are PlotSpecs — JSON-friendly, library-agnostic.
+ * They aren't React components and they aren't PNGs; they are
+ * what you'd hand to vega-lite, plotly, matplotlib, or your own
+ * Canvas renderer to draw the actual figure.
+ */
+
+interface ParetoPoint {
+    candidateId: string;
+    /** Mean USD cost per run on the chosen split. */
+    cost: number;
+    /** Mean score on the chosen split. */
+    quality: number;
+    /** Number of runs that informed this point. */
+    n: number;
+    /** Whether this candidate is on the Pareto frontier — high
+     *  quality, low cost, no dominator. */
+    onFrontier: boolean;
+    /** Optional gate verdict for this candidate, if a `GateDecision`
+     *  for it was passed in. */
+    gate?: 'promote' | 'reject_few_runs' | 'reject_negative_delta' | 'reject_overfit_gap' | null;
+}
+interface ParetoFigureSpec {
+    kind: 'pareto-cost-quality';
+    split: 'search' | 'holdout';
+    points: ParetoPoint[];
+    axes: {
+        x: 'costUsd';
+        y: 'score';
+    };
+}
+interface GainDistributionBin {
+    /** Inclusive lower edge. */
+    lo: number;
+    /** Exclusive upper edge (or inclusive if it's the last bin). */
+    hi: number;
+    /** Number of pairs whose delta lands in this bin. */
+    count: number;
+}
+
+/**
+ * # InsightReport — the rigorous decision packet for any set of agent runs.
+ *
+ * Returned by `analyzeRuns()` and embedded in `SelfImproveResult.insight` +
+ * the hosted-tier `EvalRunEvent.insightReport`. One shape across two surfaces:
+ *
+ *   - **Customer who has a closed loop** (`selfImprove`): the report ships
+ *     with the loop output. Their dashboard renders ship/hold + lift CI +
+ *     calibration + cluster + Pareto in one packet.
+ *   - **Customer who has observed runs but no loop** (`analyzeRuns` directly):
+ *     same packet from a `RunRecord[]` they already have — production traces,
+ *     approve/reject corpus, CSV gold set.
+ *
+ * Every field is optional except the distributional summary — fields are
+ * populated when the input data supports them:
+ *
+ *   - `lift` requires both baseline and candidate splits to be present.
+ *   - `interRater` requires multi-rater feedback (≥2 raters per run).
+ *   - `judges` populates per-judge stats only when the run records carry
+ *     `outcome.judgeScores`.
+ *   - `failureClusters` requires the optional `analystRegistry` to be wired.
+ *   - `contamination` requires canary scenarios to be passed in.
+ *   - `outcomeCorrelation` requires a downstream outcome signal.
+ *   - `sequential` requires the run set to be ordered (treats them as a
+ *     stream and emits an anytime-valid interim decision).
+ *
+ * Consumers read the `recommendations` array first — that's the
+ * actionable layer, ranked by priority. The numeric sections back it up.
+ */
+
+interface InsightReport {
+    /** Number of runs analyzed. */
+    n: number;
+    /** Runtime facts carried by the run records. These describe execution,
+     *  not task quality: duration, queueing, token categories, models, and
+     *  explicitly recorded failures. */
+    execution: ExecutionInsight;
+    /** Composite-score distribution across all runs. Always present. */
+    composite: ScalarDistribution;
+    /** Per-dimension distributions for every dimension that appeared in any
+     *  run's judge scores. Empty when no judge scores were recorded. */
+    perDimension: Record<string, ScalarDistribution>;
+    /** Cost/quality distribution and Pareto frontier. */
+    costQuality: {
+        cost: ScalarDistribution;
+        pareto: ParetoFigureSpec;
+        /** Cost source coverage. `uncaptured` rows are excluded from the USD
+         *  distribution and Pareto chart; observed and estimated totals remain
+         *  separate so reports never present estimates as billed spend. */
+        provenance?: CostProvenanceSummary;
+        /** Set when the cost/quality view is degraded because the input data
+         *  doesn't fully support it — e.g. all `costUsd` were zero, or only a
+         *  single candidate appears (so the Pareto is a single point). The
+         *  named fields name the degraded sub-view, free-text the reason. */
+        degraded?: {
+            cost?: string;
+            pareto?: string;
+        };
+    };
+    /** Per-judge calibration + bias detection. Populated for every judge name
+     *  that appears in `outcome.judgeScores`. Bias fields require either a
+     *  gold reference or multi-rater data. */
+    judges: Record<string, JudgeInsight>;
+    /** Inter-rater agreement when multiple judges scored the same runs.
+     *  Includes pairwise kappa and the specific run ids where raters
+     *  disagree — the cases worth a human meeting. */
+    interRater?: InterRaterInsight;
+    /** Pairwise lift (baseline → candidate) with bootstrap CI. Present when
+     *  `RunRecord.splitTag` includes both `holdout` and search/dev splits,
+     *  or when caller passes an explicit baseline/candidate split. */
+    lift?: LiftInsight;
+    /** Failure clusters with exemplars. Populated when an AnalystRegistry
+     *  is wired in `analyzeRuns({ analyst })`. */
+    failureClusters?: FailureClusterInsight;
+    /** Canary leak count + holdout audit status. Populated when canary
+     *  scenarios are passed in. */
+    contamination?: ContaminationInsight;
+    /** Correlation between judge composite and a downstream outcome the
+     *  caller supplies (engagement, revenue, downstream pass rate, etc.).
+     *  When present, the optional reward model is the model that maps
+     *  judge scores → predicted outcome. */
+    outcomeCorrelation?: OutcomeCorrelationInsight;
+    /** Aggregate release-readiness summary. A consumer needing the full
+     *  substrate `ReleaseConfidenceScorecard` (SLO-axis evaluation,
+     *  ActionableSideInfo bag) calls `evaluateReleaseConfidence()` directly;
+     *  this summary captures the analyzeRuns-derived axes. */
+    release: ReleaseSummary;
+    /** Delta vs a prior period when `baselineRuns` is passed. Per-metric
+     *  current vs baseline with Welch CI + Cohen's d + significance flag.
+     *  Answers "did my last change help?" — the customer-conversion question.
+     *  Surfaced metrics: composite, cost, duration, tokenUsage, plus any
+     *  per-dimension judge metric present in both windows. */
+    priorPeriodComparison?: PriorPeriodComparison;
+    /** Model-free failure-mode breakdown from `RunRecord.failureMode`, ranked
+     *  by count descending. Present when any run carries a `failureMode`.
+     *  Complements `failureClusters` (LLM-semantic) with the structured tags
+     *  the harness already recorded — actionable with no analyst wired. */
+    failureModes?: FailureModeTally[];
+    /** Top-N actionable recommendations, ranked by priority. The packet's
+     *  human-readable layer; the numeric sections are the evidence. */
+    recommendations: Recommendation[];
+}
+interface CostProvenanceSummary {
+    observed: {
+        n: number;
+        totalUsd: number;
+    };
+    estimated: {
+        n: number;
+        totalUsd: number;
+    };
+    uncaptured: {
+        n: number;
+    };
+    knownFraction: number;
+}
+interface ExecutionInsight {
+    /** End-to-end wall time for every run. */
+    durationMs: ScalarDistribution;
+    /** Queue time for the subset of runs that recorded it. */
+    queueMs: ScalarDistribution;
+    /** Token distributions plus corpus totals. Optional token categories use
+     *  distribution `n` to disclose how many runs recorded that category. */
+    tokenUsage: TokenUsageInsight;
+    /** Usage reported only by orchestration or agent aggregate spans.
+     *  Kept separate because it may duplicate model-call telemetry in other traces. */
+    aggregateUsage: {
+        runs: number;
+        tokenUsage: TokenUsageInsight;
+        costUsd: ScalarDistribution;
+        totalCostUsd: number;
+    };
+    /** Stable model counts, largest cohort first. */
+    models: Array<{
+        model: string;
+        runs: number;
+    }>;
+    /** Model-call coverage. `events` is available only from producers that
+     *  record `outcome.raw.llm_span_count`; `runs` also recognizes non-zero
+     *  token usage from other producers. */
+    modelCalls: {
+        runs: number;
+        events: number;
+        reportingRuns: number;
+    };
+    /** Failure counts remain separate from outcome scores. `reportedErrorEvents`
+     *  sums `outcome.raw.error_span_count` only where a producer supplied it. */
+    failures: {
+        runs: number;
+        fraction: number;
+        reportedErrorEvents: number;
+        reportingRuns: number;
+    };
+}
+interface TokenUsageInsight {
+    input: ScalarDistribution;
+    output: ScalarDistribution;
+    reasoning: ScalarDistribution;
+    cached: ScalarDistribution;
+    cacheWrite: ScalarDistribution;
+    totals: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cached: number;
+        cacheWrite: number;
+    };
+}
+/** Distributional summary of a scalar-valued metric. */
+interface ScalarDistribution {
+    /** Sample count after dropping non-finite values. */
+    n: number;
+    mean: number;
+    p50: number;
+    p95: number;
+    stddev: number;
+    min: number;
+    max: number;
+    /** Histogram bins using `agent-eval`'s `gainHistogram` primitive. */
+    histogram: GainDistributionBin[];
+    /** Worst-N runs by score, ascending. Populated for the composite
+     *  distribution so the report names the runs a customer should
+     *  inspect first. Undefined when the distribution was computed from a
+     *  raw value list with no run identity (e.g. cost). */
+    tailRuns?: Array<{
+        runId: string;
+        score: number;
+    }>;
+}
+interface JudgeInsight {
+    /** Number of times this judge scored a run. */
+    n: number;
+    /** Mean composite over this judge's runs. */
+    meanScore: number;
+    /** Calibration against a gold reference, when provided. Cohen's κ for
+     *  binary thresholding + continuous agreement metrics. */
+    calibration?: ContinuousAgreement;
+    /** Positional bias — when the judge sees options in different orders,
+     *  do its preferences track the content or the position? */
+    positionalBias?: number;
+    /** Self-preference — when the judge sees its own model's output vs a
+     *  competitor, does it over-pick its own? */
+    selfPreference?: number;
+    /** Verbosity bias — does the judge reward longer outputs regardless of
+     *  quality? */
+    verbosityBias?: number;
+}
+interface InterRaterInsight {
+    /** Number of raters whose scores were aggregated. */
+    raters: number;
+    /** Number of runs every rater scored. */
+    jointlyRated: number;
+    /** Cohen's κ averaged across rater pairs. */
+    kappa: number;
+    /** Pairwise κ per rater pair (key = `"raterA::raterB"`). */
+    perPair: Record<string, number>;
+    /** Run ids where raters disagree the most — the high-value triage list. */
+    disagreementCases: Array<{
+        runId: string;
+        ratings: Array<{
+            rater: string;
+            score: number;
+        }>;
+        range: number;
+    }>;
+}
+interface LiftInsight {
+    baselineMean: number;
+    candidateMean: number;
+    /** Candidate − baseline. */
+    delta: number;
+    /** Lower / upper bound of bootstrap CI on the delta. */
+    ci95: [number, number];
+    /** Paired-t-test p-value. */
+    pValue: number;
+    /** Number of paired observations. */
+    n: number;
+    /** Cohen's d for the delta. */
+    cohensD: number;
+    /** Minimum detectable effect at current n, 80% power. */
+    mde: number;
+    /** Sample size needed to detect the observed delta at 80% power. */
+    requiredN: number;
+}
+interface FailureClusterInsight {
+    /** All clusters identified by the registry, ranked by share descending. */
+    clusters: Array<{
+        id: string;
+        name: string;
+        /** Fraction of failed runs in this cluster, 0..1. */
+        share: number;
+        /** Exemplar `runId`s (≤ 5) the consumer can drill into. */
+        exemplars: string[];
+        /** Short LLM-generated suggested fix when the registry supports it. */
+        suggestedFix?: string;
+    }>;
+    totalFailures: number;
+}
+/** Model-free failure breakdown over the structured `RunRecord.failureMode`
+ *  enum. Unlike `failureClusters` (semantic, requires an LLM analyst), this
+ *  is computed directly from the tags the harness already recorded — so a
+ *  customer ingesting one batch with no judge/analyst still learns which
+ *  named failure dominates. */
+interface FailureModeTally {
+    /** The `failureMode` tag. */
+    mode: string;
+    /** Number of runs carrying this tag. */
+    count: number;
+    /** Share of the whole corpus, 0..1. */
+    share: number;
+}
+interface ContaminationInsight {
+    /** Canary phrases that leaked into outputs. */
+    leaks: number;
+    /** Holdout audit verdict — did any holdout-tagged run end up in the
+     *  search/dev pool, or vice versa? */
+    holdoutAuditPassed: boolean;
+    details?: Array<{
+        runId: string;
+        canary: string;
+        matched: string;
+    }>;
+}
+interface OutcomeCorrelationInsight {
+    /** What outcome the consumer is correlating against (e.g.
+     *  `'engagement_rate'`, `'approval_rate'`, `'downstream_pass'`). */
+    metric: string;
+    /** Number of (run, outcome) pairs used. */
+    n: number;
+    /** Pearson correlation between composite score and outcome. */
+    pearson: number;
+    /** Spearman rank correlation — robust to monotonic non-linearity. */
+    spearman: number;
+    /** When present, the simple linear reward model fit to the data. */
+    rewardModel?: {
+        intercept: number;
+        slope: number;
+        r2: number;
+    };
+}
+interface ReleaseSummary {
+    /** Overall verdict across axes — fail if any axis fails, else warn if any
+     *  warns, else pass. */
+    status: 'pass' | 'warn' | 'fail';
+    axes: Array<{
+        name: 'quality-lift' | 'contamination' | 'composite-distribution';
+        status: 'pass' | 'warn' | 'fail';
+        detail: string;
+    }>;
+    /** Free-form issues surfaced beyond the standard axes. Empty by default;
+     *  consumers can post-process to populate. */
+    issues: string[];
+}
+interface MetricDelta {
+    /** Current-period mean. */
+    current: number;
+    /** Baseline-period mean. */
+    baseline: number;
+    /** current - baseline. Positive means improved (or, for cost/duration,
+     *  the consumer-side interpretation: "higher current" — semantic
+     *  direction depends on the metric). */
+    delta: number;
+    /** Welch 95% confidence interval on the delta. Two-sample, unpaired —
+     *  the baseline and current run sets may have different scenarios. */
+    ci95: [number, number];
+    /** Welch t-test p-value (two-sided). */
+    pValue: number;
+    /** Cohen's d (pooled stddev). Effect size, signed. */
+    cohensD: number;
+    /** Sample sizes. */
+    baselineN: number;
+    currentN: number;
+    /** True when p < 0.05 AND |d| >= 0.2 (small-effect threshold). The
+     *  conjunction prevents large-effect-but-noisy and significant-but-
+     *  tiny from triggering recommendations. */
+    significant: boolean;
+}
+interface PriorPeriodComparison {
+    /** Sample counts. */
+    baselineN: number;
+    currentN: number;
+    /** Optional human-readable label — "vs prior 7 days", "vs v3 release". */
+    windowLabel?: string;
+    /** Every metric we could compare. Keys: 'composite', 'cost', 'duration',
+     *  'tokenUsage' for always-present ones; per-dimension keys when both
+     *  windows have judge scores on the same dimension. */
+    metrics: Record<string, MetricDelta>;
+    /** Metric names where current is significantly WORSE than baseline.
+     *  Direction-aware: for cost/duration, higher current = worse. */
+    regressedMetrics: string[];
+    /** Metric names where current is significantly BETTER than baseline. */
+    improvedMetrics: string[];
+}
+interface Recommendation {
+    priority: 'critical' | 'high' | 'medium' | 'low';
+    kind: 'ship' | 'hold' | 'investigate' | 'fix' | 'recalibrate' | 'expand-corpus';
+    title: string;
+    detail: string;
+    /** Optional pointer back into the report for the evidence. */
+    evidencePath?: string;
+}
+
+/**
+ * # Hosted-tier wire format — the schema that EVERY orchestrator (ours,
+ * a partner's self-hosted one, a future open implementation) must accept.
+ *
+ * **Stability:** every type in this file is committed under semver. New
+ * minors only ADD optional fields. Breaking changes mean a major bump
+ * (`HostedWireVersion` literal increment).
+ *
+ * The wire format is two event streams in one transport:
+ *
+ *   1. **Eval-run events** (`POST /v1/ingest/eval-runs`). Posted when a
+ *      campaign / improvement-loop completes (or per-generation if
+ *      streaming). Carries the structured result + per-cell scores +
+ *      surface diffs the orchestrator stores for the dashboard.
+ *
+ *   2. **Trace spans** (`POST /v1/ingest/traces`). Standard OTLP-shaped
+ *      spans with a few additional attributes so the orchestrator can
+ *      pivot from eval-run → underlying execution. Compatible with any
+ *      OTel collector.
+ *
+ * Both endpoints are authenticated with a bearer token + a tenant id
+ * header. Tenants isolate everything downstream of ingest; no tenant
+ * ever sees another tenant's data.
+ */
+
+declare const HOSTED_WIRE_VERSION: "2026-05-26.v1";
+type HostedWireVersion = typeof HOSTED_WIRE_VERSION;
+/** Lifecycle stages of an eval-run as the substrate reports them. */
+type EvalRunStatus = 'started' | 'baseline-complete' | 'generation-complete' | 'gate-decided' | 'finished' | 'errored';
+interface EvalRunCellScore {
+    /** Stable scenario id from the consumer's scenario set. */
+    scenarioId: string;
+    /** Repetition index when reps > 1; 0 for the default. */
+    rep: number;
+    /** Composite score across all judges + dimensions for this cell. */
+    compositeMean: number;
+    /** Per-judge → per-dimension scores; null where the judge did not run. */
+    dimensions: Record<string, Record<string, number>>;
+    /** Per-cell error message if the dispatch threw. Null on success. */
+    errorMessage?: string;
+}
+interface EvalRunGenerationSnapshot {
+    /** Generation index. 0 is baseline. */
+    index: number;
+    /** Candidate surface fingerprint (stable hash) — pivot key into the
+     *  trace stream to fetch the underlying execution. */
+    surfaceHash: string;
+    /** The candidate surface itself. May be omitted to avoid PII when the
+     *  consumer prefers not to ship verbatim prompts. */
+    surface?: MutableSurface;
+    /** Per-cell scores for this generation. */
+    cells: EvalRunCellScore[];
+    /** Aggregate composite mean across all cells in this generation. */
+    compositeMean: number;
+    /** Total $ spent across this generation. */
+    costUsd: number;
+    /** Wall-clock duration of this generation. */
+    durationMs: number;
+}
+/**
+ * The top-level eval-run event. One ingest call per logical eval-run;
+ * generations stream in incrementally via repeated calls with the same
+ * `runId`. The orchestrator deduplicates by `(runId, generation.index)`.
+ */
+interface EvalRunEvent {
+    /** Stable run id (the substrate's `runId`). UUID or substrate-generated. */
+    runId: string;
+    /** Where this run was happening — derived from `RunCampaignOptions.runDir`. */
+    runDir: string;
+    /** ISO-8601 timestamp the substrate recorded the event. */
+    timestamp: string;
+    /** Lifecycle stage this event represents. */
+    status: EvalRunStatus;
+    /** Free-form consumer tags (env, branch, model id, etc.). Searchable. */
+    labels: Record<string, string>;
+    /** Baseline campaign snapshot. Present when status >= baseline-complete. */
+    baseline?: EvalRunGenerationSnapshot;
+    /** Per-generation snapshots. Streams in; orchestrator appends. */
+    generations: EvalRunGenerationSnapshot[];
+    /** Final gate decision. Present when status >= gate-decided. */
+    gateDecision?: GateDecision;
+    /** Held-out lift = winner-on-holdout - baseline-on-holdout. */
+    holdoutLift?: number;
+    /** Total $ spent across baseline + every generation. */
+    totalCostUsd: number;
+    /** Total wall-clock duration. */
+    totalDurationMs: number;
+    /** Error message if status === 'errored'. */
+    errorMessage?: string;
+    /** Rigor packet emitted alongside the run — distributional summary,
+     *  paired-bootstrap lift CI, judge stats, inter-rater agreement,
+     *  contamination check, failure clusters (when an analyst is wired),
+     *  outcome correlation (when downstream signal is supplied), and the
+     *  recommendations the dashboard surfaces verbatim. Additive; older
+     *  clients that don't know about this field continue to work. */
+    insightReport?: InsightReport;
+}
+/**
+ * OTel-shape span with a few additional attributes for eval-run pivoting.
+ * Compatible with any OTLP collector — `name`, `traceId`, `spanId`,
+ * `startTimeUnixNano`, `endTimeUnixNano`, `attributes` are stock OTel.
+ */
+interface TraceSpanEvent {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: number;
+    endTimeUnixNano: number;
+    attributes: Record<string, string | number | boolean>;
+    events?: Array<{
+        timeUnixNano: number;
+        name: string;
+        attributes?: Record<string, string | number | boolean>;
+    }>;
+    status?: {
+        code: 'OK' | 'ERROR' | 'UNSET';
+        message?: string;
+    };
+    /** Pivot back into the eval-run stream. */
+    'tangle.runId'?: string;
+    /** Pivot to the specific generation. */
+    'tangle.generation'?: number;
+    /** Pivot to the specific cell. */
+    'tangle.cellId'?: string;
+    /** Pivot to the specific scenario. */
+    'tangle.scenarioId'?: string;
+}
+interface IngestResponse {
+    /** Accepted events / spans count. */
+    accepted: number;
+    /** Rejected events with reasons (validation failures, dup idempotency key, etc.). */
+    rejected: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+
+/**
+ * # Hosted-tier ingest client.
+ *
+ * Ships eval-run events + trace spans to any orchestrator (ours, a
+ * partner's self-hosted one, or a future open implementation) that
+ * speaks the wire format in `./types.ts`.
+ *
+ * Three modes:
+ *   - **Ours:** point at `https://orchestrator.tangle.tools` (the host root —
+ *     the client appends the versioned `/v1/ingest/...` path itself; a trailing
+ *     `/v1` on the endpoint is tolerated and normalized away). We handle ingest
+ *     + storage + dashboard.
+ *   - **Self-hosted:** point at whatever URL runs the reference receiver
+ *     from `examples/hosted-ingest-server/`.
+ *   - **Off (default):** when `hostedTenant` is unset, nothing is sent.
+ *     Everything stays local.
+ */
+
+interface HostedTenant {
+    /** Orchestrator endpoint base URL (no trailing slash). Required. */
+    endpoint: string;
+    /** Bearer token issued by the orchestrator. Required. */
+    apiKey: string;
+    /** Tenant id — the orchestrator's primary key for this consumer. Required. */
+    tenantId: string;
+    /** Optional `fetch` override (auth wrappers, custom agent, test mocks). */
+    fetchImpl?: typeof fetch;
+    /** Per-call timeout in ms. Default 30s. */
+    timeoutMs?: number;
+    /** Retries on 5xx / network errors. Default 2. */
+    retries?: number;
+}
+interface HostedClient {
+    ingestEvalRun(event: EvalRunEvent, idempotencyKey?: string): Promise<IngestResponse>;
+    ingestEvalRuns(events: EvalRunEvent[], idempotencyKey?: string): Promise<IngestResponse>;
+    ingestTraces(spans: TraceSpanEvent[], idempotencyKey?: string): Promise<IngestResponse>;
+    readonly tenant: HostedTenant;
+    readonly wireVersion: HostedWireVersion;
+}
+
+/**
+ * Loop provenance — the durable, queryable record of WHAT a self-improvement
+ * loop did and WHY, plus the OTel spans that let an OTLP collector pivot from
+ * an eval-run to the underlying candidate→cell→gate→promote chain.
+ *
+ * Two artifacts, one source of truth:
+ *
+ *   1. `LoopProvenanceRecord` — a structured JSON record capturing every
+ *      candidate (surfaceHash + label + rationale + structured cause), its measured composite,
+ *      the gate decision + reasons + delta, the held-out lift, the explicit
+ *      baseline→candidate diff, and BACKEND PROVENANCE (the
+ *      `assertRealBackend` verdict + worker call count + model). This is the
+ *      ingestable audit artifact: the +lift recomputes from it, the "because
+ *      Z" rationale survives in it, and a stub backend is detectable from it.
+ *
+ *   2. `loopProvenanceSpans()` — the same chain emitted as OTLP-ingestable
+ *      `TraceSpanEvent`s, pivoted on the substrate's standard
+ *      `tangle.runId` / `tangle.scenarioId` / `tangle.cellId` /
+ *      `tangle.generation` attributes (the same pivots `/adapters/otel`
+ *      reads). The hosted `/v1/ingest/traces` endpoint receives the FULL loop,
+ *      not just the `cost.*` spans `runCampaign` already emits per cell.
+ *
+ * The record is built from the substrate's own loop result + the per-call
+ * `RunRecord`s the worker emitted — no new measurement, no recomputation that
+ * could drift from what the gate actually saw.
+ */
+
+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;
+    /** Proposer label, when the proposer returned a `ProposedCandidate`. */
+    label?: string;
+    /** Proposer rationale — the "because Z". When the proposer returned a bare
+     *  surface (blind mutator) this is absent. */
+    rationale?: string;
+    /** Exact validated cause when the proposer emitted a structured record. */
+    candidateRecord?: PolicyEditCandidateRecord;
+    /** 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. */
+    composite: number;
+    /** 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;
+}
+/**
+ * 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.v3';
+    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[];
+    /** 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: Array<{
+            name: string;
+            passed: boolean;
+        }>;
+    };
+    /** baseline-on-holdout composite mean. */
+    baselineHoldoutComposite: number;
+    /** winner-on-holdout composite mean. */
+    winnerHoldoutComposite: number;
+    /** winnerHoldout - baselineHoldout — RECOMPUTABLE from this record. */
+    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;
+    diff: string;
+    /** Baseline composite on the search split, distinct from holdout scoring. */
+    baselineSearchComposite: number;
+    /** 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;
+        }>;
+    }>;
+    gate: GateResult;
+    baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
+    winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
+    /** Worker call records — the source for backend provenance. */
+    workerRecords: ReadonlyArray<RunRecord>;
+    totalCostUsd: number;
+    totalDurationMs: number;
+}
+/** Build the durable provenance record from a completed loop result. */
+declare function buildLoopProvenanceRecord<TArtifact, TScenario extends Scenario>(args: BuildLoopProvenanceArgs<TArtifact, TScenario>): LoopProvenanceRecord;
+/**
+ * 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>;
+
 /** The shared, out-of-repo root for campaign/benchmark run bundles. Keeping run
  *  outputs here means they never land in a repo working tree (no per-repo
  *  gitignore, no clutter, no accidental commits). Layout:
@@ -3112,4 +7314,4 @@ declare function verifyCodeSurface(surface: CodeSurface, worktreeDir?: string):
  *  identity against the checkout at `worktreeRef`. */
 declare function resolveWorktreePath(surface: CodeSurface, worktreeDir?: string): string;
 
-export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type ApplySkillPatchResult, type BuildAnalystSurfaceDispatchOptions, type CampaignBreakdown, CampaignResult, CampaignRunPlan, CampaignStorage, CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, DEFAULT_POLICY_EDIT_HISTORY_LIMITS, type DimensionRegression, type DiscriminationScore, DispatchContext, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, Gate, GenerationRecord, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPolicyEditTargetSurface, type JsonPrimitive, type JsonValue, JudgeConfig, JudgeScore, LabelTrust, LabeledScenarioRecord, LabeledScenarioSampleArgs, LabeledScenarioSource, LabeledScenarioStore, LabeledScenarioStoreError, LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LlmPolicyEditProposerOptions, type LoadEvalFixtureScenariosOptions, type MemoryCurationProposerOptions, MutableSurface, type NeutralizationGateOptions, type OpenSearchLedgerOptions, type OptimizerEntryConfig, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditAuthorScenarioRow, type PolicyEditCandidateSummary, type PolicyEditFindingInput, type PolicyEditFindingSource, type PolicyEditHistoryCandidateContext, type PolicyEditHistoryGenerationContext, type PolicyEditHistoryProjectionOptions, type PolicyEditObjective, type PolicyEditOutcomeContext, type PolicyEditProposerOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, ProposeContext, type ProposePatchesArgs, ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, RunCampaignOptions, RunImprovementLoopOptions, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, SEARCH_LEDGER_SCHEMA, Scenario, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SelectPolicyEditAuthorRowsOptions, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SerializedJsonBudget, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, analyzeCrossSurfaceInteractions, applySkillPatch, assertCodeSurfaceIdentity, assertPolicyEditAuthorContextBudget, buildAnalystSurfaceDispatch, callbackGovernor, campaignBreakdown, campaignMeanComposite, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, compositeProposer, detectScale, dimensionRegressions, discoverEvalFixtures, extractFapoAttributionSignals, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsLineageStore, gepaParetoEntry, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldoutSignificance, heuristicGovernor, isTransientTransportFailure, lineageNodeId, llmPolicyEditProposer, loadEvalFixture, loadEvalFixtureScenarios, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, openSearchLedger, pairHoldout, parameterSweepProposer, parseSkillPatchResponse, patchEditCount, planEvalFixtureRun, policyEditProposer, projectPolicyEditHistory, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runLineage, runLineageLoop, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, selectPolicyEditAuthorRows, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, validateSearchLedgerEvent, verifyCodeSurface };
+export { type AcceptedEdit, type AceProposerOptions, type AnalystArtifact, type AnalystScenario, type AnalyzeCrossSurfaceInteractionsInput, type ApplySkillPatchResult, type AxisEvidence, type AxisVerdict, type BuildAnalystSurfaceDispatchOptions, type BuildEvidenceVectorOptions, type BuildLoopProvenanceArgs, type CampaignAggregates, type CampaignArtifactWriter, type CampaignBreakdown, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignRunPlan, type CampaignRunPlanCell, type CampaignStorage, type CampaignTokenUsage, type CampaignTraceWriter, type CodeSurface, type CodeSurfaceVerification, type CompareProposersOptions, type CompositeProposerOptions, type CrossSurfaceAdditionDecision, type CrossSurfaceAdditionRejectionReason, type CrossSurfaceAttemptCompleteness, type CrossSurfaceBestSingleSelection, type CrossSurfaceBootstrapPolicy, type CrossSurfaceCandidate, type CrossSurfaceCandidateComparison, type CrossSurfaceCandidateEvidence, type CrossSurfaceCandidateOutcome, type CrossSurfaceCandidateSummary, type CrossSurfaceComponent, type CrossSurfaceComponentEvidence, type CrossSurfaceCompositionStep, type CrossSurfaceDistribution, type CrossSurfaceEligibility, type CrossSurfaceEvidenceBreakdown, type CrossSurfaceIneligibilityReason, type CrossSurfaceInteractionAwareSelection, type CrossSurfaceInteractionEffect, type CrossSurfaceInteractionPath, type CrossSurfaceInteractionReport, type CrossSurfaceInteractionTask, type CrossSurfaceNaiveStackSelection, type CrossSurfacePairCompatibility, type CrossSurfacePairEvidence, type CrossSurfacePairIncompatibilityReason, type CrossSurfacePairwiseEntry, type CrossSurfaceRankedSingle, type CrossSurfaceRelativeCost, type CrossSurfaceSelectionPolicy, type CrossSurfaceSelections, type CrossSurfaceTaskRow, DEFAULT_POLICY_EDIT_HISTORY_LIMITS, type DefaultProductionGateOptions, type DimensionRegression, type DiscriminationScore, type DispatchContext, type DispatchFn, type EmitLoopProvenanceArgs, type EmitLoopProvenanceResult, type EvalFixture, type EvalFixtureFile, type EvalFixtureLoadOptions, type EvalFixtureRunPlan, type EvalFixtureScenario, type EvalFixtureValidationMode, type EvidenceVector, type EvolutionaryProposerOptions, type FailureModeRecallJudgeOptions, type FapoAttributionSignals, type FapoEntryConfig, type FapoFailureCluster, type FapoOptimizationLevel, type FapoProposerOptions, type FapoReviewInput, type FapoReviewIssue, type FapoReviewResult, type FapoScopeContract, FileSearchLedger, FsLabeledScenarioStore, type FsLabeledScenarioStoreOptions, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerConstraints, type GepaProposerOptions, type GitWorktreeAdapterOptions, type Governor, type GovernorContext, type GovernorOp, type HaloProposerOptions, type HeldOutGateOptions, type HeldoutSignificance, type HeldoutSignificanceOptions, type HeuristicGovernorOptions, type JsonPolicyEditTargetSurface, type JsonPrimitive, type JsonValue, type JudgeAggregate, type JudgeConfig, type JudgeDimension, type JudgeScore, type LabelTrust, type LabeledScenarioRecord, type LabeledScenarioSampleArgs, type LabeledScenarioSource, type LabeledScenarioStore, LabeledScenarioStoreError, type LabeledScenarioWrite, Lineage, type LineageEdge, type LineageGraph, type LineageNode, type LineageNodeInput, type LineageStore, type LlmJudgeDimension, type LlmJudgeOptions, type LlmPolicyEditProposerOptions, type LoadEvalFixtureScenariosOptions, type LoopProvenanceBackend, type LoopProvenanceCandidate, type LoopProvenanceRecord, type MemoryCurationProposerOptions, type MutableSurface, type Mutator, type NeutralizationGateOptions, type ObjectiveSource, type OpenAutoPrOptions, type OpenAutoPrResult, type OpenSearchLedgerOptions, type OptimizationProposer, type OptimizerConfig, type OptimizerEntryConfig, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, type PairedHoldout, type ParameterCandidate, type ParameterChange, type ParameterSweepProposerOptions, type ParetoParent, type ParetoSignificanceGateOptions, type PlanCampaignRunOptions, type PlanEvalFixtureRunOptions, type PlaybackContext, type PlaybackDriver, type PlaybackStep, type PolicyEditAuthorScenarioRow, type PolicyEditCandidateRecord, type PolicyEditCandidateSummary, type PolicyEditFindingInput, type PolicyEditFindingSource, type PolicyEditHistoryCandidateContext, type PolicyEditHistoryGenerationContext, type PolicyEditHistoryProjectionOptions, type PolicyEditObjective, type PolicyEditOutcomeContext, type PolicyEditProposerOptions, type PowerPreflight, type PowerPreflightOptions, type ProfileDispatchFn, ProfileMatrixError, type ProfileSummary, type PromotionObjective, type PromotionPolicy, type ProposeContext, type ProposePatchesArgs, type ProposedCandidate, type ProposerComparison, type ProposerEntry, type ProposerPairwise, type ProposerScore, type RedactionStatus, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceScenario, type RejectedEdit, type RolloutArgumentDiff, type RolloutArgumentDiffOptions, type RolloutCall, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunLineageLoopOptions, type RunLineageLoopResult, type RunLineageLoopSeed, type RunLineageOptions, type RunLineageResult, type RunLineageSeed, type RunLineageStepResult, type RunOptimizationOptions, type RunOptimizationResult, type RunProfileMatrixOptions, type RunProfileMatrixResult, type RunSkillOptOptions, type RunSkillOptResult, SEARCH_LEDGER_SCHEMA, type Scenario, type ScenarioAggregate, type ScenarioRollup, type ScenarioSignal, type ScoreboardRenderOptions, type ScoreboardRow, type ScoreboardSummary, type ScoredRollout, type ScoredSurfaceOutcome, type SearchAccountingAudit, type SearchArtifactRef, type SearchAttemptAccounting, type SearchCandidateDecidedEvent, type SearchCandidateLineage, type SearchCandidateRegisteredEvent, type SearchCandidateSlot, type SearchCandidateSlotClosedEvent, type SearchCandidateSurface, type SearchCompletedEvent, type SearchCostAccounting, type SearchFailureReason, type SearchLedger, type SearchLedgerAppendResult, SearchLedgerConflictError, type SearchLedgerEntry, SearchLedgerError, type SearchLedgerEvent, type SearchLedgerHash, SearchLedgerIntegrityError, type SearchLedgerReplay, type SearchModelIdentity, type SearchOperationKind, type SearchOperationRecordedEvent, type SearchPlan, type SearchPlannedEvent, type SearchPlannedOperation, type SearchPlannedTask, type SearchSourceRef, type SearchSurfaceEffect, type SearchSurfaceEvidence, type SearchSurfaceKind, type SearchTaskAttemptedEvent, type SearchTaskOutcome, type SearchTokenAccounting, type SelectPolicyEditAuthorRowsOptions, type SequentialDecideFn, type SequentialDecideOptions, type SequentialDecision, type SequentialObservation, type SequentialPairedGate, type SequentialPairedGateOptions, type SerializedJsonBudget, type SessionScript, type SingleRunLock, type SingleRunLockOptions, type SkillOptEpochRecord, type SkillOptEvidence, type SkillOptProposer, type SkillOptProposerOptions, type SkillPatch, type SkillPatchOp, SkillPatchParseError, type SkillPatchRejection, type SurfaceProposer, type SurfaceScore, type TraceAnalystProposerOptions, type TraceSpan, type TransientFailureOptions, type UngroundedLiteralReport, type UserStory, type UserStoryVerdict, type Worktree, type WorktreeAdapter, WorktreeAdapterError, aceProposer, acquireSingleRunLock, analyzeCrossSurfaceInteractions, applySkillPatch, assertCodeSurfaceIdentity, assertPolicyEditAuthorContextBudget, buildAnalystSurfaceDispatch, buildEvidenceVector, buildLoopProvenanceRecord, callbackGovernor, campaignBreakdown, campaignMeanComposite, classifyUngroundedLiterals, codeSurfaceIdentityMaterial, compareProposers, composeGate, compositeProposer, countSentenceEdits, createReferenceEquivalenceJudge, createRunCostLedger, defaultProductionGate, defaultRenderDiff, detectScale, dimensionRegressions, discoverEvalFixtures, emitLoopProvenance, evolutionaryProposer, extractFapoAttributionSignals, extractH2Sections, failureModeRecallJudge, fapoEscalationEntry, fapoProposer, fsCampaignStorage, fsLineageStore, gepaParetoEntry, gepaProposer, gepaReflectionEntry, gitWorktreeAdapter, haloProposer, heldOutGate, heldoutSignificance, heuristicGovernor, inMemoryCampaignStorage, isProposedCandidate, isTransientTransportFailure, labelTrustRank, lineageNodeId, llmJudge, llmPolicyEditProposer, loadEvalFixture, loadEvalFixtureScenarios, loopProvenanceSpans, makePlaybackDispatch, memLineageStore, memoryCurationProposer, neutralizationGate, neutralizeText, openAutoPr, openSearchLedger, pairHoldout, parameterSweepProposer, paretoPolicy, paretoSignificanceGate, parseSkillPatchResponse, patchEditCount, planCampaignRun, planEvalFixtureRun, policyEditProposer, powerPreflight, projectPolicyEditHistory, provenanceRecordPath, provenanceSpansPath, renderScoreboardMarkdown, resolveRunDir, resolveWorktreePath, rolloutArgumentDiff, runCampaign, runEval, runImprovementLoop, runLineage, runLineageLoop, runOptimization, runProfileMatrix, runSkillOpt, scoreDiscrimination, scoreUserStory, scoreboardSummary, selectDiscriminative, selectPolicyEditAuthorRows, sequentialDecide, sequentialPairedGate, skillOptEntry, skillOptProposer, surfaceContentHash, surfaceHash, tangleTracesRoot, traceAnalystProposer, userStoryScoreboard, validatePolicyEditCandidateRecord, validateSearchLedgerEvent, verifyCodeSurface };