@tangle-network/agent-eval 0.117.1 → 0.118.0

package/dist/contract/index.d.ts

@@ -1,39 +1,3584 @@
-import { S as Scenario, M as MutableSurface, D as DispatchContext, b as JudgeConfig, c as SurfaceProposer, G as Gate, L as LabeledScenarioStore, C as CampaignResult, d as GateDecision } from '../types-BSw1rOUB.js';
-export { e as CampaignAggregates, f as CampaignArtifactWriter, g as CampaignCellResult, h as CampaignCostMeter, i as CampaignTraceWriter, j as CodeSurface, k as Dispatch, l as GateContext, m as GateResult, n as GenerationCandidate, o as GenerationRecord, a as JudgeDimension, J as JudgeScore, p as Mutator, O as OptimizationProposer, q as OptimizerConfig, r as SessionScript } from '../types-BSw1rOUB.js';
-import { L as LoopProvenanceRecord, P as PowerPreflight, R as RunEvalOptions } from '../provenance-DpjwyseI.js';
-export { A as AxisEvidence, a as AxisVerdict, B as BuildEvidenceVectorOptions, D as DefaultProductionGateOptions, E as EvidenceVector, b as EvolutionaryProposerOptions, H as HeldOutGateOptions, O as ObjectiveSource, c as ParetoSignificanceGateOptions, d as PromotionObjective, e as PromotionPolicy, f as buildEvidenceVector, g as composeGate, h as defaultProductionGate, i as evolutionaryProposer, j as heldOutGate, p as paretoPolicy, k as paretoSignificanceGate, r as runEval } from '../provenance-DpjwyseI.js';
-import { R as RunOptimizationOptions, a as RunImprovementLoopResult } from '../gepa-eESocoDi.js';
-export { G as GepaProposerOptions, b as REFERENCE_EQUIVALENCE_INPUT_LIMITS, c as REFERENCE_EQUIVALENCE_JUDGE_VERSION, d as ReferenceEquivalenceJudgeInput, e as ReferenceEquivalenceJudgeOptions, f as ReferenceEquivalenceJudgeResult, g as ReferenceEquivalenceScenario, h as RunCampaignOptions, i as RunImprovementLoopOptions, j as createReferenceEquivalenceJudge, k as gepaProposer, r as runCampaign, l as runImprovementLoop, m as runReferenceEquivalenceJudge } from '../gepa-eESocoDi.js';
-export { c as AnalystFinding, C as ChatClient, p as CreateChatClientOpts, V as createChatClient } from '../policy-edit-wG9uFEFm.js';
-import { C as CampaignStorage } from '../storage-DrX3v_5B.js';
-export { f as fsCampaignStorage, i as inMemoryCampaignStorage } from '../storage-DrX3v_5B.js';
-export { D as DeploymentOutcome, F as FileSystemOutcomeStore, a as FileSystemOutcomeStoreOptions, I as InMemoryOutcomeStore, b as OutcomeStore } from '../outcome-store-rnXLEqSn.js';
-import { HostedTenant, EvalRunCellScore, EvalRunGenerationSnapshot, EvalRunEvent, TraceSpanEvent } from '../hosted/index.js';
-import { b as CostLedgerSummary, d as CostReceipt, C as CostLedger } from '../cost-ledger-DWy3XdJc.js';
-import { R as RunRecord, a as RunSplitTag } from '../run-record-BDH49H2E.js';
-import { I as InsightReport } from '../insight-report-DY4nDW9Q.js';
-export { C as CostProvenanceSummary, F as FailureClusterInsight, a as InterRaterInsight, J as JudgeInsight, L as LiftInsight, O as OutcomeCorrelationInsight, R as Recommendation, b as ReleaseSummary, S as ScalarDistribution } from '../insight-report-DY4nDW9Q.js';
-export { D as DefaultAnalystRegistryOptions, c as buildDefaultAnalystRegistry } from '../default-registry-DaK8b3fv.js';
-import { A as AnalyzeRunsOptions } from '../analyze-runs--2x39HZ7.js';
-export { a as analyzeRuns } from '../analyze-runs--2x39HZ7.js';
-export { C as CodeAgentSessionDiagnostic, a as CodeAgentSessionIntakeOptions, b as CodeAgentSessionIntakeResult, c as CodeAgentSessionMetrics, d as CodeAgentSessionSource, P as ParsedCodeAgentJsonl, f as fromClaudeCodeSession, e as fromCodexSession, g as fromKimiCodeSession, h as fromOpenCodeSession, i as fromPiSession, j as fromPigraphSession, p as parseCodeAgentJsonl } from '../code-agent-session-CjZsVd19.js';
-import '../llm-client-qoDd18Qz.js';
-import '../errors-oeQrLqXC.js';
-import '../raw-provider-sink-C46HDghv.js';
-import '../statistics-KUnG73jH.js';
-import '../judge-calibration-7C-IDmKr.js';
-import '../types-BkfcQnxV.js';
-import '@tangle-network/tcloud';
-import '../dataset-NENEzRgk.js';
-import '../store-DGqD0Pyo.js';
-import '../schema-B3Q3l9Z_.js';
-import '../store-C1YxJDEK.js';
-import '@tangle-network/agent-interface';
-import '../summary-report-C5bKFfm-.js';
-import '../failure-cluster-DOAcSJ87.js';
-import '@ax-llm/ax';
-import '../kind-factory-ClZmO25A.js';
-import 'zod';
+import { AxFunction, AxAIService } from '@ax-llm/ax';
+import { z } from 'zod';
+
+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;
+}
+
+interface Scenario$1 {
+    id: string;
+    persona: string;
+    label: string;
+    thesis: string;
+    dimensions: string[];
+    turns: Turn[];
+    artifactChecks: ArtifactCheck[];
+    systemPromptAppend?: string;
+}
+interface Turn {
+    user: string;
+    expectedBehaviors: string[];
+    adversarial?: boolean;
+    feedbackType?: 'correction' | 'rejection' | 'vague' | 'contradictory' | 'escalation';
+}
+interface ArtifactCheck {
+    type: 'vault_file_exists' | 'vault_file_contains' | 'block_extracted' | 'code_valid' | 'generation_produced' | 'tool_created' | string;
+    target: string;
+    contains?: string;
+    minCount?: number;
+    description: string;
+}
+interface TurnResult {
+    turnIndex: number;
+    userMessage: string;
+    agentResponse: string;
+    durationMs: number;
+    blocksExtracted: {
+        type: string;
+        title: string;
+    }[];
+    containsCode: boolean;
+    containsToolCall: boolean;
+}
+interface CollectedArtifacts {
+    vaultFiles: {
+        path: string;
+        content: string;
+    }[];
+    blocksExtracted: {
+        type: string;
+        fields: Record<string, string>;
+    }[];
+    codeBlocks: {
+        language: string;
+        code: string;
+    }[];
+    toolCalls: string[];
+}
+interface JudgeInput {
+    scenario: Scenario$1;
+    turns: TurnResult[];
+    artifacts: CollectedArtifacts;
+    /** Shared ledger for paid built-in judges. Direct calls default to an uncapped ledger. */
+    costLedger?: CostLedger;
+    costPhase?: string;
+    costTags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Exact maximum provider attempts configured on the supplied TCloud client. */
+    tcloudMaximumAttempts?: number;
+}
+
+/**
+ * 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;
+}
+type CreateChatClientOpts = RouterTransportOpts | CliBridgeTransportOpts | DirectProviderTransportOpts | SandboxSdkTransportOpts | MockTransportOpts;
+interface BaseTransportOpts {
+    defaultModel?: string;
+    /** Total provider attempts. Required for opaque transports used in capped runs. */
+    maximumAttempts?: number;
+}
+interface RouterTransportOpts extends BaseTransportOpts {
+    transport: 'router';
+    baseUrl?: string;
+    apiKey: string;
+}
+interface CliBridgeTransportOpts extends BaseTransportOpts {
+    transport: 'cli-bridge';
+    baseUrl?: string;
+    bearer?: string;
+}
+interface DirectProviderTransportOpts extends BaseTransportOpts {
+    transport: 'direct-provider';
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * Sandbox-SDK transport. Provided as a thin pass-through: the caller
+ * supplies a callable that mimics LlmClient.chat() against an already-
+ * configured Sandbox handle. We don't import the SDK here to keep
+ * agent-eval dep-free of @tangle-network/sandbox.
+ */
+interface SandboxSdkTransportOpts extends BaseTransportOpts {
+    transport: 'sandbox-sdk';
+    chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Mock transport for tests. The handler receives the request and returns
+ * whatever the test wants. No retries, no JSON-schema degrade.
+ */
+interface MockTransportOpts extends BaseTransportOpts {
+    transport: 'mock';
+    handler: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Build a ChatClient bound to a specific transport. The returned client
+ * is safe to share across analysts in a single registry run.
+ */
+declare function createChatClient(opts: CreateChatClientOpts): ChatClient;
+
+/**
+ * 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;
+}
+/**
+ * The discriminator the registry uses to pass the right input.
+ * `custom` is the escape hatch — analysts that need something else
+ * (e.g. an embedding cache, a partner SDK handle) read it from
+ * `AnalystRunInputs.custom[<analyst id>]`.
+ */
+type AnalystInputKind = 'trace-store' | 'artifact-dir' | 'run-record' | 'judge-input' | 'custom';
+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 AnalystRequirements {
+    /** Min number of shots / samples the analyst needs to produce signal. */
+    min_shots?: number;
+    /** Capabilities the runtime must supply (e.g. ['network', 'gpu']). */
+    capabilities?: string[];
+}
+/**
+ * What's passed to every analyst call. The registry resolves which
+ * field the analyst's `inputKind` selects and asserts it's present.
+ */
+interface AnalystRunInputs {
+    traceStore?: TraceAnalysisStore;
+    artifactDir?: string;
+    runRecord?: RunRecord;
+    judgeInput?: JudgeInput;
+    /** Keyed by analyst id; populated by callers that registered custom analysts. */
+    custom?: Record<string, unknown>;
+}
+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;
+}
+/**
+ * The minimal contract. Concrete analysts can refine `TInput` so
+ * implementations stay type-safe (e.g. a trace analyst's `TInput` is
+ * `TraceAnalysisStore`); the registry passes the right field from
+ * `AnalystRunInputs` based on `inputKind`.
+ */
+interface Analyst<TInput = unknown> {
+    /** Stable identifier — appears in finding_id, telemetry, and registry exclusion lists. */
+    readonly id: string;
+    /** Human-readable. One sentence. */
+    readonly description: string;
+    readonly inputKind: AnalystInputKind;
+    readonly cost: AnalystCost;
+    readonly requires?: AnalystRequirements;
+    /** Bump on breaking changes to claim wording or area so old finding_ids don't collide. */
+    readonly version: string;
+    analyze(input: TInput, ctx: AnalystContext): Promise<AnalystFinding[]>;
+}
+interface AnalystRunSummary {
+    analyst_id: string;
+    status: 'ok' | 'skipped' | 'failed';
+    /** Why skipped — missing input, budget exceeded, capability unmet. */
+    reason?: string;
+    findings_count: number;
+    latency_ms: number;
+    cost_usd: number;
+    /** When `status='failed'`: the error class + message, never the full stack. */
+    error?: {
+        class: string;
+        message: string;
+    };
+}
+interface AnalystRunResult {
+    run_id: string;
+    correlation_id: string;
+    started_at: string;
+    ended_at: string;
+    findings: AnalystFinding[];
+    per_analyst: AnalystRunSummary[];
+    /** Total LLM cost in USD across all analysts in this registry.run(). */
+    total_cost_usd: number;
+}
+/**
+ * Events emitted by `AnalystRegistry.runStream(...)` in real time as
+ * the registry executes. UIs subscribe via `for await (const ev of
+ * registry.runStream(...))`; `registry.run(...)` is a thin collector
+ * over the same stream, so the two surfaces share their invariants.
+ *
+ * Per-finding events are intentionally omitted — analyzers are batch
+ * operations (an Ax actor returns the full `findings:json[]` at the
+ * end of the responder), so streaming inside one analyst would only
+ * emit partial JSON consumers can't render. The kind-completion event
+ * is the right granularity; subscribers wanting per-finding rendering
+ * iterate `event.findings` themselves.
+ */
+type AnalystRunEvent = {
+    type: 'run-started';
+    run_id: string;
+    correlation_id: string;
+    started_at: string;
+    /** The ordered list of analyst ids the registry will run. */
+    analyst_ids: ReadonlyArray<string>;
+} | {
+    type: 'analyst-skipped';
+    summary: AnalystRunSummary;
+} | {
+    type: 'analyst-started';
+    analyst_id: string;
+    started_at: string;
+} | {
+    type: 'analyst-completed';
+    /** `summary.status` is `'ok'` for clean completion or `'failed'` for thrown analysts. */
+    summary: AnalystRunSummary;
+    findings: ReadonlyArray<AnalystFinding>;
+} | {
+    type: 'run-completed';
+    result: AnalystRunResult;
+};
+
+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;
+}
+
+/**
+ * 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;
+}
+/** 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';
+/** 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'>>;
+}
+
+/**
+ * `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;
+
+/**
+ * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
+ * scenarios → dispatch → artifacts → judges → aggregates, with full
+ * reproducibility (seed + manifest hash), cell-level resumability, bootstrap
+ * CIs, and the `LabeledScenarioStore` capture flywheel.
+ *
+ * Improvement loops (optimizer / gate / autoOnPromote) ride on top of this
+ * primitive but live in `presets/run-improvement-loop.ts`. This file keeps
+ * the core orchestrator minimal — Phase 1 of the Pass A track.
+ */
+
+interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
+    scenarios: TScenario[];
+    dispatch: DispatchFn<TScenario, TArtifact>;
+    /**
+     * Stable identity for the dispatch behavior, included in the manifest/cache
+     * key. Set this when the same function name can run different models,
+     * prompts, tools, or external config.
+     */
+    dispatchRef?: string;
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    /** Required for reproducibility. Default 42. */
+    seed?: number;
+    /** Per-scenario replicates for CI bands. Default 1; raise to 5+ for
+     *  bootstrap-tight intervals on critical eval. */
+    reps?: number;
+    /** When true (default), completed cells are cached by
+     *  (manifestHash, scenarioId, rep, generation). Re-runs skip cached cells. */
+    resumable?: boolean;
+    /** Optional store — when present, every artifact + judge score is captured
+     *  with the configured `captureSource`. Capture is default ON; pass `'off'`
+     *  to disable. */
+    labeledStore?: LabeledScenarioStore | 'off';
+    captureSource?: 'production-trace' | 'eval-run' | 'manual' | 'red-team' | 'synthetic';
+    captureSourceVersionHash?: string;
+    /** Hard spend cap. Each paid call reserves its enforced maximum before dispatch. */
+    costCeiling?: number;
+    /** Shared spend account. Improvement loops pass one ledger through every
+     *  campaign so the ceiling and returned total are run-wide. */
+    costLedger?: CostLedger;
+    /** Attribution label for receipts recorded by this campaign. */
+    costPhase?: string;
+    /** Max concurrent cells. Default 2. */
+    maxConcurrency?: number;
+    /**
+     * Per-cell dispatch deadline in ms. A `dispatch` that neither resolves nor
+     * rejects within this window is a hang (a stalled model request, an
+     * exhausted runtime resource, a backend that never closes its stream). When
+     * set, the cell's `ctx.signal` is aborted and the cell is recorded as a LOUD
+     * error (`dispatch exceeded <N>ms`) so the campaign proceeds and the failure
+     * is visible — instead of one wedged cell silently hanging the whole run (and
+     * every loop/CI job above it) forever. `undefined`/`0` = unbounded (legacy).
+     */
+    dispatchTimeoutMs?: number;
+    /** Required: where artifacts + traces land. A bare name (not an absolute path)
+     *  resolves to the shared `~/.tangle/traces/<repo>/runs/<name>` root so run
+     *  bundles never pollute a repo working tree. Pass an absolute path to override. */
+    runDir: string;
+    /** Subject repo for the shared run-dir root (defaults to the CWD basename).
+     *  Only consulted when `runDir` is a bare name. */
+    repo?: string;
+    /** Tracing posture. Default is the substrate's `FileSystemTraceStore` rooted
+     *  at `<runDir>/traces/`. `'off'` disables capture entirely — substrate
+     *  refuses this when the caller wires `autoOnPromote !== 'none'`. */
+    tracing?: 'on' | 'off';
+    /**
+     * Per-cell usage expectation — the early, fine-grained sibling of the
+     * batch `assertRealBackend` guard. A cell that produced an artifact (no
+     * error) but reported `costUsd === 0` AND zero tokens is a stub: the
+     * dispatch never reported LLM activity via `ctx.cost`. Modes:
+     *   - `'warn'` (default) — log the offending cell loudly, keep going.
+     *   - `'assert'` — throw `BackendIntegrityError` on the first such cell
+     *     (fail-fast; recommended for CI campaigns expecting real LLM calls).
+     *   - `'off'` — no check (replay / deterministic-only / offline analysis).
+     */
+    expectUsage?: 'assert' | 'warn' | 'off';
+    /** Test seam — override the wall clock for deterministic tests. */
+    now?: () => Date;
+    /** Test seam — override per-cell trace writer factory. */
+    buildTraceWriter?: (cellId: string, dir: string) => CampaignTraceWriter;
+    /** Storage backend for run/cell dirs, the resumability cache, artifacts,
+     *  and trace spans. Default: the Node filesystem (`fsCampaignStorage`).
+     *  Pass `inMemoryCampaignStorage()` to run in a filesystem-less runtime
+     *  (Cloudflare Workers, Deno, edge) — the `CampaignResult` is still
+     *  produced; artifacts/traces just aren't persisted to disk. */
+    storage?: CampaignStorage;
+    /**
+     * Optional per-cell placement strategy. Returns an opaque string the
+     * substrate forwards as `ctx.placement` to the Dispatch — placement-aware
+     * Dispatches (e.g. `httpDispatch` from `/adapters/http`) use it to route
+     * each cell to the right worker, region, or sandbox. When unset, every
+     * cell receives `ctx.placement = undefined` and behaves identically to
+     * the in-process case.
+     *
+     * @example
+     *   cellPlacement: ({ scenario }) => scenario.tags?.includes('eu') ? 'eu-west' : 'us-east'
+     */
+    cellPlacement?: (input: {
+        scenario: TScenario;
+        rep: number;
+        generation?: number;
+    }) => string | undefined;
+}
+/**
+ * Core campaign orchestrator: fan scenarios through dispatch, score with judges, aggregate bootstrap CIs, and persist reproducible `CampaignResult` records.
+ */
+declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
+
+/**
+ * `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>>;
+
+/**
+ * `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;
+
+/**
+ * `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[];
+}
+
+/**
+ * `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>>;
+
+declare const REFERENCE_EQUIVALENCE_JUDGE_VERSION = "reference-equivalence-judge-v1-2026-07-13";
+declare const REFERENCE_EQUIVALENCE_INPUT_LIMITS: {
+    readonly userRequest: 8000;
+    readonly expectedAnswer: 32000;
+    readonly candidateOutput: 32000;
+};
+interface ReferenceEquivalenceScenario extends Scenario {
+    userRequest: string;
+    expectedAnswer: string;
+}
+interface ReferenceEquivalenceJudgeInput {
+    userRequest: string;
+    expectedAnswer: string;
+    candidateOutput: string;
+}
+interface ReferenceEquivalenceJudgeOptions {
+    /** Injected transport. No implicit provider or credentials are selected. */
+    chat: ChatClient;
+    /** Falls back to the ChatClient's default model. */
+    model?: string;
+    /** Used only by the direct-call adapter. */
+    signal?: AbortSignal;
+    /** Optional receipt destination for direct calls; campaigns supply their own. */
+    costLedger?: CostLedger;
+}
+interface ReferenceEquivalenceJudgeResult extends LlmCallMetadata {
+    kind: 'reference-equivalence';
+    version: string;
+    score: number;
+    rationale: string;
+}
+/** Build the campaign-native expected-answer judge. */
+declare function createReferenceEquivalenceJudge(options: ReferenceEquivalenceJudgeOptions): JudgeConfig<string, ReferenceEquivalenceScenario>;
+/** Direct-call adapter over the campaign judge for product callers. */
+declare function runReferenceEquivalenceJudge(input: ReferenceEquivalenceJudgeInput, options: ReferenceEquivalenceJudgeOptions): Promise<ReferenceEquivalenceJudgeResult>;
+
+/**
+ * `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;
+
+/**
+ * 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>;
+
+/**
+ * Pareto frontier — multi-objective optimization over candidate runs.
+ *
+ * Lifted from ADC pareto.ts and blueprint-agent frontier.ts. When you're
+ * trading off (cost, latency, quality) or (passRate, tokenBudget,
+ * ttfb), you rarely have a single "winner" — you have a set of
+ * non-dominated candidates. This module exposes:
+ *
+ *   - `paretoFrontier`: filter a set of candidates to the non-dominated ones
+ *   - `dominates`: does A dominate B across all objectives?
+ *
+ * Each objective is declared with a direction: 'maximize' (higher=better)
+ * or 'minimize' (lower=better). Candidates are any object; pass an
+ * `objective(candidate)` accessor.
+ */
+type Direction = 'maximize' | 'minimize';
+
+interface 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;
+}
+
+/**
+ * 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>;
+
+/**
+ * OutcomeStore — deployment outcomes attached to Run IDs.
+ *
+ * Outcomes arrive asynchronously from production telemetry after the
+ * eval run completed: user ratings, retention flags, conversion events,
+ * revenue, support-ticket rate, anything a product team can measure.
+ * The store is a peer to TraceStore — separate lifecycle, same runId
+ * foreign key.
+ *
+ * The whole point of this module is to make the meta-eval correlation
+ * question computable: `correlate(evalMetric, outcomeMetric) → r, ρ, n, CI`.
+ */
+interface DeploymentOutcome {
+    runId: string;
+    capturedAt: number;
+    /** Numeric outcomes keyed by name — retention_7d, csat, revenue_usd, etc. */
+    metrics: Record<string, number>;
+    /** Dimensions for stratified analysis — cohort, region, user_segment. */
+    labels?: Record<string, string>;
+    /** Free-form provenance (source system, pipeline version). */
+    source?: string;
+}
+interface OutcomeFilter {
+    runIds?: string[];
+    since?: number;
+    until?: number;
+    label?: {
+        key: string;
+        value: string;
+    };
+    source?: string;
+}
+interface OutcomeStore {
+    append(outcome: DeploymentOutcome): Promise<void>;
+    /** All outcomes attached to this run (a single run can have many — multiple
+     *  capture windows over deployment time). */
+    forRun(runId: string): Promise<DeploymentOutcome[]>;
+    list(filter?: OutcomeFilter): Promise<DeploymentOutcome[]>;
+}
+declare class InMemoryOutcomeStore implements OutcomeStore {
+    private items;
+    append(outcome: DeploymentOutcome): Promise<void>;
+    forRun(runId: string): Promise<DeploymentOutcome[]>;
+    list(filter?: OutcomeFilter): Promise<DeploymentOutcome[]>;
+}
+interface FileSystemOutcomeStoreOptions {
+    dir: string;
+    maxBytes?: number;
+}
+declare class FileSystemOutcomeStore implements OutcomeStore {
+    private dir;
+    private maxBytes;
+    private memo?;
+    private loaded;
+    constructor(options: FileSystemOutcomeStoreOptions);
+    private ensureDir;
+    append(outcome: DeploymentOutcome): Promise<void>;
+    private load;
+    forRun(runId: string): Promise<DeploymentOutcome[]>;
+    list(filter?: OutcomeFilter): Promise<DeploymentOutcome[]>;
+}
+
+/**
+ * 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.
+ */
+
+/** 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;
+}
+
+/**
+ * # 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 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;
+}
+
+/**
+ * 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;
+}
 
 /**
  * # `selfImprove()` - the one-call improvement loop.
@@ -392,6 +3937,348 @@ interface DefinedAgentEval<TScenario extends Scenario, TArtifact> {
  */
 declare function defineAgentEval<TScenario extends Scenario, TArtifact>(defaults: DefineAgentEvalOptions<TScenario, TArtifact>): DefinedAgentEval<TScenario, TArtifact>;
 
+/**
+ * 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'>>;
+}
+
+/**
+ * AnalystRegistry — orchestrate N analysts against one run.
+ *
+ * Owns three responsibilities and only three:
+ *   1. Registration — ids must be unique; bad registrations fail loudly
+ *      at register-time, not run-time.
+ *   2. Routing — each analyst declares its `inputKind`; the registry
+ *      picks the matching field from AnalystRunInputs and skips the
+ *      analyst with a logged reason if it's missing.
+ *   3. Isolation — one analyst's exception MUST NOT stop other analysts.
+ *      Failed analysts produce zero findings + a 'failed' summary row.
+ *
+ * Cross-cutting concerns (telemetry, error → finding conversion, cost
+ * ingestion, storage rotation) live in `AnalystHooks`. Budget shaping
+ * (equal split vs weighted vs custom) lives in `BudgetPolicy`. Both
+ * have sensible defaults; consumers override only what they need.
+ */
+
+interface AnalystHooks {
+    /** Before analyze() — last chance to mutate ctx (e.g. inject tags, override budget). */
+    onBeforeAnalyze?(args: {
+        analyst: Analyst;
+        ctx: AnalystContext;
+        runId: string;
+    }): void | Promise<void>;
+    /** After every analyst (ok | failed | skipped). Use for telemetry, ingestion, rotation. */
+    onAfterAnalyze?(args: {
+        analyst: Analyst;
+        summary: AnalystRunSummary;
+        findings: AnalystFinding[];
+        runId: string;
+    }): void | Promise<void>;
+    /**
+     * On analyst exception. Hook MAY return findings to convert the
+     * error into structured findings; the summary still reports 'failed'.
+     * Return void to keep the default empty-findings behavior.
+     */
+    onError?(args: {
+        analyst: Analyst;
+        error: Error;
+        runId: string;
+    }): AnalystFinding[] | undefined | Promise<AnalystFinding[] | undefined>;
+    /** Once after registry.run() completes. Use for final aggregation, persistence. */
+    onComplete?(args: {
+        result: AnalystRunResult;
+    }): void | Promise<void>;
+}
+interface BudgetPolicy {
+    /** Overall USD cap across the registry.run(). */
+    totalUsd?: number;
+    /** Per-analyst weight for the default allocator. Missing ids get weight 1. */
+    weights?: Record<string, number>;
+    /**
+     * Custom allocator — receives the analyst, remaining/total budget, and
+     * the count of analysts that will run. Returns the per-analyst budget
+     * (or undefined to leave it uncapped). Overrides weights when set.
+     */
+    allocate?: (args: {
+        analyst: Analyst;
+        totalUsd: number | undefined;
+        remainingUsd: number | undefined;
+        runningCount: number;
+    }) => number | undefined;
+}
+interface AnalystRegistryOptions {
+    /** Shared chat client passed to every LLM analyst via AnalystContext. */
+    chat?: ChatClient;
+    /** Logger callback. Defaults to a no-op. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Hooks invoked around analyze() — observability + customization seam. */
+    hooks?: AnalystHooks;
+    /** Default budget when run() doesn't override. */
+    defaultBudget?: BudgetPolicy;
+}
+interface RegistryRunOpts {
+    /** Restrict to a subset of registered analysts by id. */
+    only?: string[];
+    /** Skip these analysts even if registered. Useful for cheap iteration. */
+    skip?: string[];
+    /** Budget policy — totalUsd + optional weights/allocator. Falls back to options.defaultBudget. */
+    budget?: BudgetPolicy;
+    /** Wall-clock cap. Analysts SHOULD honor `ctx.deadlineMs`. */
+    timeoutMs?: number;
+    /** Abort signal — forwarded into every analyst's context. */
+    signal?: AbortSignal;
+    /** Tags echoed into AnalystContext.tags — useful for tracking environment/version in findings. */
+    tags?: Record<string, string>;
+    /**
+     * Prior-run findings made available as retrieval context to every
+     * analyst via `ctx.priorFindings`. The registry forwards the slice
+     * whose `analyst_id` matches each registered analyst so a kind sees
+     * only its own history. Pass `{ '*': findings }` to broadcast to
+     * every analyst (useful for cross-kind chaining where the improvement
+     * analyst consumes upstream failure findings).
+     */
+    priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+}
+declare class AnalystRegistry {
+    private readonly analysts;
+    private readonly options;
+    constructor(options?: AnalystRegistryOptions);
+    register(analyst: Analyst): void;
+    list(): ReadonlyArray<{
+        id: string;
+        description: string;
+        version: string;
+        cost: Analyst['cost'];
+    }>;
+    run(runId: string, inputs: AnalystRunInputs, runOpts?: RegistryRunOpts): Promise<AnalystRunResult>;
+    /**
+     * Streaming counterpart to `run()`. Emits `AnalystRunEvent` values
+     * in real time — `run-started`, then per-analyst `skipped` /
+     * `started` / `completed`, then a terminal `run-completed` whose
+     * payload is the full `AnalystRunResult`. UIs use this to render
+     * progress; persistence consumers use `run()` and read the result.
+     *
+     * Hooks (`onBeforeAnalyze` / `onAfterAnalyze` / `onError` /
+     * `onComplete`) fire as before — streaming is additive, not a hook
+     * replacement.
+     */
+    runStream(runId: string, inputs: AnalystRunInputs, runOpts?: RegistryRunOpts): AsyncGenerator<AnalystRunEvent, void, void>;
+    private selectAnalysts;
+    private routeInput;
+}
+
+/**
+ * `buildDefaultAnalystRegistry` — the canonical analyst suite, so consumers
+ * stop hand-wiring `new AnalystRegistry()` + per-kind `createTraceAnalystKind`.
+ *
+ * The deterministic `behavioralAnalyst` is ALWAYS registered (it needs no
+ * model and is model-agnostic by construction). The agentic RLM kinds are
+ * registered only when an `ai` service is supplied — so a caller with no LLM
+ * still gets the full behavioral/efficiency diagnosis, and the substrate's
+ * "any model (including no model)" guarantee holds at the suite level.
+ */
+
+interface DefaultAnalystRegistryOptions {
+    /** Ax service for the agentic RLM kinds. Omit → only the deterministic analyst. */
+    ai?: AxAIService;
+    /** Model for the agentic kinds (falls back to the ai service default). */
+    model?: string;
+    /** Which agentic kinds to register when `ai` is present. Default = the shipped suite. */
+    kinds?: readonly TraceAnalystKindSpec[];
+    /** Set false to omit the deterministic behavioral analyst (default: include). */
+    includeBehavioral?: boolean;
+    /** Forwarded to the AnalystRegistry constructor (signal, tags, priorFindings). */
+    registry?: AnalystRegistryOptions;
+}
+declare function buildDefaultAnalystRegistry(opts?: DefaultAnalystRegistryOptions): AnalystRegistry;
+
+/**
+ * # `analyzeRuns()` — turn a set of agent runs into an actionable decision packet.
+ *
+ * Wires the substrate's statistical, calibration, clustering, Pareto, and
+ * release-confidence primitives into one `InsightReport`. Two top-level
+ * entry points use this function:
+ *
+ *   - `selfImprove()` calls it on the campaign output to attach a packet
+ *     to every run.
+ *   - Consumers with observed `RunRecord[]` (production traces, gold
+ *     corpora, approve/reject tables) call it directly via `analyzeRuns()`
+ *     for analysis without a closed loop.
+ *
+ * Every section is opt-in based on what the input data supports — the
+ * function never invents signal. If runs carry no judge scores, `judges`
+ * is empty. If there's no baseline/candidate split, `lift` is undefined.
+ * If no `analyst` is wired, `failureClusters` is undefined.
+ *
+ * The `recommendations` array is the human-readable layer; everything
+ * else is the evidence backing each recommendation.
+ */
+
+interface AnalyzeRunsOptions {
+    /** The runs to analyze. */
+    runs: RunRecord[];
+    /** Which split to score against when reading composite from RunOutcome.
+     *  Default: holdout when ANY run has a `holdoutScore`, else search. */
+    split?: 'search' | 'holdout' | 'auto';
+    /** Pairwise analysis configuration. When both `baselineCandidateId` and
+     *  `candidateCandidateId` are present, lift is computed on paired
+     *  (experimentId, seed) tuples shared between the two sides. */
+    baselineCandidateId?: string;
+    candidateCandidateId?: string;
+    /** Canary scenarios — checked against every run's raw output for
+     *  holdout contamination. */
+    canaryScenarios?: DatasetScenario[];
+    /** Analyst registry for failure clustering. When omitted, the
+     *  `failureClusters` section is left undefined. */
+    analyst?: AnalystRegistry;
+    /** Downstream outcome metric per run (e.g. engagement rate, approval
+     *  rate, downstream pass rate). When present, the report includes
+     *  `outcomeCorrelation` + a simple linear reward model fit. */
+    outcomeSignal?: {
+        metric: string;
+        valueByRunId: Record<string, number>;
+    };
+    /** Multi-rater feedback for inter-rater agreement. Each entry is one
+     *  rater's score for one run. Two or more raters → kappa + disagreement
+     *  triage list. */
+    raterScores?: Array<{
+        runId: string;
+        rater: string;
+        score: number;
+    }>;
+    /** Number of histogram bins for distributional summaries. Default 12. */
+    histogramBins?: number;
+    /** Decision threshold — the smallest composite lift the caller cares
+     *  about. Used by the recommendations engine to call ship vs hold.
+     *  Default 0.02. */
+    decisionThreshold?: number;
+    /** Optional prior-period runs. When set, the report includes
+     *  `priorPeriodComparison` with per-metric Welch-CI deltas and
+     *  recommendations fire on statistically significant regressions.
+     *  The two windows do NOT have to share scenarios — the comparison
+     *  is two-sample unpaired (the substrate's `lift` field uses paired
+     *  bootstrap on shared (experimentId, seed) tuples; this is the
+     *  shape for "this week vs last week" rather than "candidate vs
+     *  baseline within a campaign"). */
+    baselineRuns?: RunRecord[];
+    /** Human-readable label for the baseline window, e.g. "vs prior 7
+     *  days", "vs v3.1 release". Surfaces in recommendations + UI. */
+    baselineLabel?: string;
+}
+interface SummarizeExecutionOptions {
+    runs: RunRecord[];
+    histogramBins?: number;
+}
+interface ExecutionReport {
+    execution: ExecutionInsight;
+    costProvenance: CostProvenanceSummary;
+}
+/** Summarize runtime facts without interpreting task quality or promotion readiness. */
+declare function summarizeExecution(opts: SummarizeExecutionOptions): ExecutionReport;
+declare function analyzeRuns(opts: AnalyzeRunsOptions): Promise<InsightReport>;
+
 /**
  * # `intake/run-record-dir` — load a directory or file of `RunRecord`s.
  *
@@ -736,6 +4623,92 @@ interface PartitionByAuthoringModelResult {
  */
 declare function partitionRunsByAuthoringModel(runs: RunRecord[], index: AgentTraceIndex): PartitionByAuthoringModelResult;
 
+type CodeAgentSessionSource = 'codex' | 'claude-code' | 'opencode' | 'kimi-code' | 'pi';
+interface ParsedCodeAgentJsonl {
+    entries: unknown[];
+    malformedLines: number;
+}
+interface CodeAgentSessionMetrics {
+    entries: number;
+    userMessages: number;
+    assistantMessages: number;
+    reasoningItems: number;
+    toolCalls: number;
+    toolOutputs: number;
+    toolErrors: number;
+    patchAttempts: number;
+    patchSuccesses: number;
+    patchFailures: number;
+    turnsStarted: number;
+    turnsCompleted: number;
+    turnsAborted: number;
+    contextCompactions: number;
+    prLinks: number;
+    fileSnapshots: number;
+    graphNodes: number;
+    graphEdges: number;
+    actionCandidates: number;
+    verificationReports: number;
+    completionDecisions: number;
+    reliabilityRows: number;
+    reliabilityLift: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    observedCostUsd: number;
+    observedCostCaptured?: boolean;
+    wallMs: number;
+    processScore: number;
+}
+interface CodeAgentSessionDiagnostic {
+    source: CodeAgentSessionSource;
+    sessionId: string;
+    sourcePath?: string;
+    entries: number;
+    malformedLines: number;
+    inferredScore: boolean;
+    hasExplicitTerminalSignal: boolean;
+    hasQualityLabel: boolean;
+    hasTokenUsage: boolean;
+    hasCost: boolean;
+    costKind?: RunCostProvenance['kind'];
+    warnings: string[];
+}
+interface CodeAgentSessionIntakeResult {
+    runs: RunRecord[];
+    diagnostics: CodeAgentSessionDiagnostic[];
+    metrics: CodeAgentSessionMetrics[];
+}
+interface CodeAgentSessionIntakeOptions {
+    entries: unknown[];
+    malformedLines?: number;
+    sourcePath?: string;
+    experimentId?: string;
+    candidateId?: string;
+    seed?: number;
+    splitTag?: RunSplitTag;
+    scenarioId?: string;
+    model?: string;
+    promptHash?: string;
+    configHash?: string;
+    commitSha?: string;
+    score?: number;
+    /** Explicit cost receipt. Use `uncaptured` when the source says dollars
+     *  were not captured; the adapter will not relabel its compatibility $0
+     *  sentinel as observed. When omitted, source-reported cost wins, then a
+     *  token-priced estimate, then uncaptured. */
+    costProvenance?: RunCostProvenance;
+}
+declare function parseCodeAgentJsonl(jsonl: string): ParsedCodeAgentJsonl;
+declare function fromCodexSession(options: CodeAgentSessionIntakeOptions): CodeAgentSessionIntakeResult;
+declare function fromClaudeCodeSession(options: CodeAgentSessionIntakeOptions): CodeAgentSessionIntakeResult;
+declare function fromOpenCodeSession(options: CodeAgentSessionIntakeOptions): CodeAgentSessionIntakeResult;
+declare function fromKimiCodeSession(options: CodeAgentSessionIntakeOptions): CodeAgentSessionIntakeResult;
+declare function fromPiSession(options: CodeAgentSessionIntakeOptions): CodeAgentSessionIntakeResult;
+declare const fromPigraphSession: typeof fromPiSession;
+
 /**
  * # `intake/feedback-table` — multi-rater approve/reject corpus → `RunRecord[]`.
  *
@@ -838,7 +4811,8 @@ declare function fromFeedbackTable(opts: FromFeedbackTableOptions): FromFeedback
  *   - `wallMs` from `endTimeUnixNano - startTimeUnixNano`
  *   - `model` from `gen_ai.request.model` / `llm.model` / `tangle.model`
  *   - cost from `cost.usd` / `gen_ai.usage.cost_usd` / `tangle.cost.usd`
- *   - token usage from `gen_ai.usage.{input,output}_tokens`
+ *   - token usage from model-call input, output, cache-read, and cache-write
+ *     attributes without double-counting aggregate parent spans
  *   - `outcome.searchScore` from `tangle.score` / `eval.score` when
  *     present; `outcome.raw` collects every numeric attribute.
  *
@@ -855,4 +4829,4 @@ interface FromOtelSpansOptions {
 }
 declare function fromOtelSpans(opts: FromOtelSpansOptions): RunRecord[];
 
-export { type AgentEvalAgent, type AgentEvalEvaluateOptions, type AgentEvalImproveOptions, type AgentTraceContributor, type AgentTraceContributorType, type AgentTraceConversation, type AgentTraceFile, type AgentTraceIndex, type AgentTraceRange, type AgentTraceRecord, AnalyzeRunsOptions, type AuthoringProvenance, CampaignResult, CampaignStorage, type DefineAgentEvalOptions, type DefinedAgentEval, DispatchContext, type EvalCellScoreDelta, type EvalDimensionDelta, type EvalGenerationDiff, type EvalReportingSuiteInput, type EvalReportingSuiteOptions, type EvalReportingSuiteResult, type EvalRunDiff, type FeedbackTableMeta, type FeedbackTableRow, type FromFeedbackTableOptions, type FromFeedbackTableResult, type FromOtelSpansOptions, type FromRunRecordDirOptions, type FromRunRecordDirResult, Gate, GateDecision, HostedTenant, InsightReport, JudgeConfig, MutableSurface, type PartitionByAuthoringModelResult, RunEvalOptions, RunImprovementLoopResult, type RunRecordRejection, Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, SelfImproveRunError, SurfaceProposer, defineAgentEval, diffGenerations, diffRunBaselineToWinner, diffRuns, evalReportingSuite, fromFeedbackTable, fromOtelSpans, fromRunRecordDir, parseAgentTrace, partitionRunsByAuthoringModel, selfImprove };
+export { type AgentEvalAgent, type AgentEvalEvaluateOptions, type AgentEvalImproveOptions, type AgentTraceContributor, type AgentTraceContributorType, type AgentTraceConversation, type AgentTraceFile, type AgentTraceIndex, type AgentTraceRange, type AgentTraceRecord, type AnalystFinding, type AnalyzeRunsOptions, type AuthoringProvenance, type AxisEvidence, type AxisVerdict, type BuildEvidenceVectorOptions, type CampaignAggregates, type CampaignArtifactWriter, type CampaignCellResult, type CampaignCostMeter, type CampaignResult, type CampaignStorage, type CampaignTraceWriter, type ChatClient, type CodeAgentSessionDiagnostic, type CodeAgentSessionIntakeOptions, type CodeAgentSessionIntakeResult, type CodeAgentSessionMetrics, type CodeAgentSessionSource, type CodeSurface, type CostProvenanceSummary, type CreateChatClientOpts, type DefaultAnalystRegistryOptions, type DefaultProductionGateOptions, type DefineAgentEvalOptions, type DefinedAgentEval, type DeploymentOutcome, type DispatchFn as Dispatch, type DispatchContext, type EvalCellScoreDelta, type EvalDimensionDelta, type EvalGenerationDiff, type EvalReportingSuiteInput, type EvalReportingSuiteOptions, type EvalReportingSuiteResult, type EvalRunDiff, type EvidenceVector, type EvolutionaryProposerOptions, type ExecutionInsight, type ExecutionReport, type FailureClusterInsight, type FeedbackTableMeta, type FeedbackTableRow, FileSystemOutcomeStore, type FileSystemOutcomeStoreOptions, type FromFeedbackTableOptions, type FromFeedbackTableResult, type FromOtelSpansOptions, type FromRunRecordDirOptions, type FromRunRecordDirResult, type Gate, type GateContext, type GateDecision, type GateResult, type GenerationCandidate, type GenerationRecord, type GepaProposerOptions, type HeldOutGateOptions, type HostedTenant, InMemoryOutcomeStore, type InsightReport, type InterRaterInsight, type JudgeConfig, type JudgeDimension, type JudgeInsight, type JudgeScore, type LiftInsight, type MutableSurface, type Mutator, type ObjectiveSource, type OptimizationProposer, type OptimizerConfig, type OutcomeCorrelationInsight, type OutcomeStore, type ParetoSignificanceGateOptions, type ParsedCodeAgentJsonl, type PartitionByAuthoringModelResult, type PromotionObjective, type PromotionPolicy, REFERENCE_EQUIVALENCE_INPUT_LIMITS, REFERENCE_EQUIVALENCE_JUDGE_VERSION, type Recommendation, type ReferenceEquivalenceJudgeInput, type ReferenceEquivalenceJudgeOptions, type ReferenceEquivalenceJudgeResult, type ReferenceEquivalenceScenario, type ReleaseSummary, type RunCampaignOptions, type RunEvalOptions, type RunImprovementLoopOptions, type RunImprovementLoopResult, type RunRecordRejection, type ScalarDistribution, type Scenario, type SelfImproveBudget, type SelfImproveLlm, type SelfImproveOptions, type SelfImproveProgressEvent, type SelfImproveResult, SelfImproveRunError, type SessionScript, type SummarizeExecutionOptions, type SurfaceProposer, type TokenUsageInsight, analyzeRuns, buildDefaultAnalystRegistry, buildEvidenceVector, composeGate, createChatClient, createReferenceEquivalenceJudge, defaultProductionGate, defineAgentEval, diffGenerations, diffRunBaselineToWinner, diffRuns, evalReportingSuite, evolutionaryProposer, fromClaudeCodeSession, fromCodexSession, fromFeedbackTable, fromKimiCodeSession, fromOpenCodeSession, fromOtelSpans, fromPiSession, fromPigraphSession, fromRunRecordDir, fsCampaignStorage, gepaProposer, heldOutGate, inMemoryCampaignStorage, paretoPolicy, paretoSignificanceGate, parseAgentTrace, parseCodeAgentJsonl, partitionRunsByAuthoringModel, runCampaign, runEval, runImprovementLoop, runReferenceEquivalenceJudge, selfImprove, summarizeExecution };