@tangle-network/agent-eval 1.0.17 → 1.0.19

package/dist/index-D4lT7aFu.d.ts

@@ -0,0 +1,3649 @@
+import { f as CostReceiptInput, h as MaximumCharge, m as CustomTokenPricing, o as CostLedgerHandle, p as CostUsage } from "./cost-ledger-Czro9wmo.js";
+import { c as ValidationError, t as AgentEvalError } from "./errors-E9I2hldP.js";
+import { l as AgentProfileJson, r as AgentProfileCell } from "./agent-profile-cell-3kYxUsK2.js";
+import { h as RunStatus, o as FailureClass, r as BudgetSpec } from "./schema-CkIvnmLU.js";
+import { a as RunRecord, c as RunSplitTag } from "./run-record-D2BFMPGl.js";
+import { i as AnalystFinding, m as EvidenceRef } from "./types-B9s9Xo5_.js";
+import { H as LlmUsage, M as LlmCallRequest, N as LlmCallResult, P as LlmChargeBounds, c as JudgeFn, f as ProductClientConfig, nt as ServedModelCheck, x as ChatClient } from "./types-0KglnQ9o.js";
+import "./statistical-heldout-C-tgpUuu.js";
+import { l as PairedBootstrapOptions, o as PairedPromotionDecisionOptions, t as PairedDecisionMethod, u as PairedBootstrapResult } from "./paired-promotion-decision-BDnqepZ1.js";
+import "./promotion-gate-DOkgJcLW.js";
+import "./index-BPmj-_ta.js";
+import { S as JudgeConfig, w as JudgeScore } from "./types-wDBk14lj.js";
+import { s as TraceStore } from "./store-CMs5wGXP.js";
+import { t as AgentProfile } from "./agent-profile-CPv4tENR.js";
+import { r as DatasetScenario, t as Dataset } from "./dataset-DThC1S6G.js";
+import { t as DefaultVerdict } from "./verdict-D_qiBQ6_.js";
+import { n as Layer } from "./multi-layer-verifier-lM4aVN78.js";
+import "./summary-report-0La5vejY.js";
+import "./analyze-runs-pJ4fhnYg.js";
+import { o as TraceEmitter } from "./emitter-mAXC5PSN.js";
+import { t as HarnessAssertion } from "./sandbox-harness-K3LuyORm.js";
+import "./define-agent-eval-D_DQMH04.js";
+import "./default-registry-BbXr18AT.js";
+import "./exact-types-CaLLU1Pz.js";
+import "./systemone-CpDppX8s.js";
+import "./engine-rfV8Ff8V.js";
+import "./registry-Ck7w-rr5.js";
+import "./index-AmfM3usI.js";
+import { d as Trajectory, f as TrajectoryStep } from "./tool-waste-CUASoTtk.js";
+import "./types-DsuOcYsE.js";
+import { B as ControlRuntimeConfig, H as ControlSeverity, R as ControlEvalResult, a as FeedbackLabel, v as ProposedSideEffect, z as ControlRunResult } from "./feedback-trajectory-P37ju-gW.js";
+import "./store-tool-spans-BgwVHXma.js";
+import "./researcher-CLnNJ7Or.js";
+import "./index-HuSMvqR2.js";
+import { SpanKind } from "@tangle-network/agent-trace-contract";
+declare class CostCeilingReachedError extends ValidationError {
+  constructor(ceilingUsd: number, committedUsd: number, requestedUsd: number, phase: string, actor: string);
+}
+declare class CostAccountingIncompleteError extends ValidationError {}
+interface CostResult {
+  costUsd: number;
+  costUnknown: boolean;
+}
+declare function costForUsage(model: string, usage: CostUsage): CostResult;
+/** Price token counts with caller-supplied per-million rates. */
+declare function costForTokenPricing(pricing: CustomTokenPricing, usage: Pick<CostUsage, 'inputTokens' | 'outputTokens' | 'cachedTokens' | 'cacheWriteTokens'>): number;
+declare function maximumChargeForLlmRequest(request: Pick<LlmCallRequest, 'model' | 'messages' | 'jsonSchema' | 'tools' | 'toolChoice' | 'maxTokens' | 'thinking'>, options?: LlmChargeBounds): MaximumCharge | undefined;
+/** Convert a provider result into the canonical paid-call receipt input.
+ * The receipt is JSON-clean: absent optional fields are omitted, never carried
+ * as explicit-undefined keys. Receipts cross JSON boundaries (the external
+ * optimizer's loopback proxy validates them with `assertJsonValue`), where an
+ * explicit-undefined value is rejected as non-serializable. */
+declare function costReceiptFromLlm(result: LlmCallResult, customTokenPricing?: CustomTokenPricing): CostReceiptInput;
+/** Structured-response failures retain their completed provider receipt. */
+declare function costReceiptFromLlmError(error: Error, customTokenPricing?: CustomTokenPricing): CostReceiptInput | undefined;
+declare class LlmCallError extends AgentEvalError {
+  readonly status: number;
+  readonly body: string;
+  readonly model: string;
+  constructor(message: string, status: number, body: string, model: string);
+}
+/** A provider response completed and incurred measurable usage, but its content
+ *  could not satisfy the caller's response contract. The response envelope is
+ *  retained so accounting can commit the receipt before the error propagates. */
+declare class LlmResponseError extends AgentEvalError {
+  readonly result: LlmCallResult;
+  constructor(message: string, result: LlmCallResult, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Strip a ```json / ``` code fence if the model emitted one.
+ * Idempotent for naked JSON. Some models (claude-code via router, certain
+ * deepseek models) wrap output even under json_object.
+ */
+declare function stripFencedJson(raw: string): string;
+/**
+ * True when an error is a transient transport/network fault worth retrying,
+ * as opposed to a deterministic failure (4xx schema reject, JSON parse) that
+ * a retry cannot fix. Inspects `LlmCallError.status`, then the error's
+ * name/message/code, then recurses into `error.cause` — undici nests the
+ * real socket fault one or more levels under `.cause`.
+ *
+ * This is the retry classifier for the package: `callLlm` and
+ * `withJudgeRetry` both route through it, so connection failures are treated
+ * consistently across transports.
+ */
+declare function isTransientLlmError(err: unknown): boolean;
+/** Mann–Whitney ROC area: ties count half; no observed member of either class means unknown. */
+declare function rocAuc(scores: number[], labels: number[]): number | null;
+/**
+ * Nearest-rank distribution summary for measurement paths (gates, dashboards,
+ * load harnesses): min/p50/p90/p95/p99/max + mean + sample stddev + a 95%
+ * Student-t CI on the mean. Consolidates the former @repo/shared
+ * distribution-stats: identical nearest-rank percentiles, with the CI now the
+ * exact t critical value for any df (the retired implementation capped its
+ * table at df 30 and fell back to 1.96).
+ */
+interface SampleDistribution {
+  min: number;
+  p50: number;
+  p90: number;
+  p95: number;
+  p99: number;
+  max: number;
+  mean: number;
+  stddev?: number;
+  ci95Low?: number;
+  ci95High?: number;
+  n: number;
+  values: number[];
+}
+interface DistributionSummaryOptions {
+  lowerBound?: number;
+}
+/**
+ * Nearest-rank percentile on an arbitrary sample, `percentile` on a 0-100
+ * scale — the same rule `summarizeDistribution` applies, exposed for a single
+ * percentile the summary struct does not carry (e.g. p99.9). Returns NaN for
+ * an empty sample; callers that need a numeric floor guard it.
+ */
+declare function percentileNearestRank(values: number[], percentile: number): number;
+declare function summarizeDistribution(values: number[], options?: DistributionSummaryOptions): SampleDistribution;
+/** Standardized effect sizes; undefined effects remain null. */
+/** Independent Cohen's d, oriented b − a; null below two samples or for an unbounded effect. */
+declare function cohensD(a: number[], b: number[]): number | null;
+/** Paired Cohen's dz; constant nonzero deltas have no finite standardized effect. */
+declare function pairedCohensDz(before: number[], after: number[]): number | null;
+type CliffsMagnitude = 'negligible' | 'small' | 'medium' | 'large';
+/** Cliff's delta, oriented after − before; empty samples return zero. */
+declare function cliffsDelta(before: number[], after: number[]): number;
+/** Romano magnitude thresholds for the absolute Cliff's delta. */
+declare function interpretCliffs(delta: number): CliffsMagnitude;
+/** Two-sided normal tail, evaluated without subtracting a near-one CDF. */
+declare function normalTwoSidedPValue(z: number): number;
+/** Two-sided Student-t tail, preserving small tail probabilities. */
+declare function studentTTwoSidedPValue(t: number, df: number): number;
+/** Pearson statistic for a 2x2 table; empty or fixed margins have statistic zero. */
+declare function chiSquared(a: number, b: number, c: number, d: number): number;
+/** One-degree-of-freedom chi-squared survival probability. */
+declare function chiSquaredPValue(statistic: number): number;
+/** Fisher two-sided probability: sum all fixed-margin tables no likelier than the observed table. */
+declare function fisherExactTwoSided(a: number, b: number, c: number, d: number): number;
+/** Fisher when any expected count is below five; otherwise Pearson's chi-squared tail. */
+declare function twoByTwoPValue(a: number, b: number, c: number, d: number): number;
+interface LinearRegressionResult {
+  slope: number;
+  rSquared: number;
+  slopePValue: number | null;
+}
+/** Centered least-squares slope; null p-value means no slope test was possible. */
+declare function linearRegressionSlope(points: readonly {
+  x: number;
+  y: number;
+}[]): LinearRegressionResult;
+interface SampleSummaryOptions {
+  confidence?: number;
+  seed?: number;
+  resamples?: number;
+}
+interface SampleSummary {
+  n: number;
+  median: number;
+  mean: number;
+  stddev: number;
+  q1: number;
+  q3: number;
+  iqr: number;
+  min: number;
+  max: number;
+  range: number;
+  cv: number | null;
+  skewness: number | null;
+  kurtosis: number | null;
+  mad: number;
+  outliers: number[];
+  medianInterval: {
+    low: number;
+    high: number;
+    confidence: number;
+    resamples: number;
+  } | null;
+}
+/** Interpolated sample median; an empty population has no measured median. */
+declare function sampleMedian(values: readonly number[]): number | null;
+/** Descriptive facts, not stability policy or a significance test. */
+declare function summarizeSample(values: readonly number[], options?: SampleSummaryOptions): SampleSummary | null;
+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;
+}
+type PolicyEditInit = Omit<PolicyEdit, 'schemaVersion' | 'editId'> & {
+  schemaVersion?: PolicyEditSchemaVersion;
+  editId?: string;
+};
+interface FindingToPolicyEditOptions {
+  expectedGain?: PolicyEditExpectedGain | ((finding: AnalystFinding) => PolicyEditExpectedGain | null | undefined);
+  risk?: PolicyEditRisk | ((finding: AnalystFinding) => PolicyEditRisk);
+  defaultAxis?: PolicyEditAxis;
+  defaultTargetSurface?: PolicyEditTargetSurface;
+}
+interface PolicyEditAdmissionOptions {
+  minScore?: number;
+  minExpectedGain?: number;
+  allowHighRisk?: boolean;
+  requireEvidence?: boolean;
+}
+interface PolicyEditAdmission {
+  edit: PolicyEdit;
+  decision: 'admit' | 'reject';
+  score: number;
+  reasons: string[];
+}
+declare function makePolicyEditCandidateRecord(edit: PolicyEdit): PolicyEditCandidateRecord;
+/**
+ * Capability-headroom gate — "can this task set even SEE the capability
+ * you're about to A/B?"
+ *
+ * A capability A/B (grant one arm a tool, a skill, extra context — anything)
+ * can only detect the capability on tasks the capability-ABSENT baseline
+ * FAILS. A task the baseline already passes is saturated: the treatment arm
+ * has no headroom to demonstrate anything, and averaging saturated tasks into
+ * the comparison dilutes a real effect toward a false null. Calibrate before
+ * measuring: run the baseline arm first, classify every task's headroom, and
+ * refuse to run the comparison when no task has a gap.
+ *
+ * Fail-closed on unknown outcomes: a baseline run whose outcome could not be
+ * determined (infra loss, unverified, missing) NEVER counts as a failure —
+ * treating "couldn't tell" as "failed" would manufacture headroom out of
+ * telemetry gaps and launder infra noise into a treatment effect.
+ *
+ * Domain-free by construction: the capability under test never appears here.
+ * Callers decide what the baseline arm lacks; this module only classifies
+ * baseline outcomes per task.
+ */
+/** One baseline-arm (capability-absent) observation of one task. */
+interface HeadroomInput {
+  /** Stable task identity; multiple rows per task are multiple baseline reps. */
+  taskId: string;
+  /** Baseline outcome. 'unknown' = the outcome could not be determined —
+   *  distinct from 'fail' and never counted as one. */
+  baselineOutcome: 'pass' | 'fail' | 'unknown';
+}
+/** Headroom classification for one task.
+ *  - 'gap': the baseline fails it — the comparison can see the capability here.
+ *  - 'saturated': the baseline already passes it — no headroom.
+ *  - 'unknown': every baseline outcome is unknown — fail-closed, not a gap. */
+type HeadroomClass = 'gap' | 'saturated' | 'unknown';
+interface TaskHeadroom {
+  taskId: string;
+  /** Total baseline observations for this task (known + unknown). */
+  n: number;
+  /** Observations with a known ('pass' | 'fail') outcome — the evidence the
+   *  classification actually rests on. A large `n` with a small `nKnown`
+   *  means the headroom verdict is thin, not well-replicated. */
+  nKnown: number;
+  /** Pass rate over KNOWN outcomes only; NaN when every outcome is unknown
+   *  (no data ≠ measured zero). */
+  baselinePassRate: number;
+  headroom: HeadroomClass;
+}
+interface CapabilityHeadroomOptions {
+  /** A task counts as 'gap' when its baseline pass rate is ≤ this. Default 0
+   *  (the baseline must fail every known rep). Must be in [0, 1) — a
+   *  threshold of 1 would classify a fully-saturated task as a gap. */
+  keepThreshold?: number;
+}
+interface CapabilityHeadroomResult {
+  /** Per-task classification, sorted by `taskId`. */
+  tasks: TaskHeadroom[];
+  summary: {
+    tasksWithGap: number;
+    tasksSaturated: number;
+    tasksUnknown: number;
+    /** Total unknown-outcome reps across ALL tasks (including tasks that
+     *  still classified via their known reps) — the size of the telemetry
+     *  hole behind the classifications. */
+    repsUnknown: number;
+  };
+}
+/**
+ * Classify every task's baseline headroom from capability-absent baseline
+ * outcomes.
+ *
+ * A task is 'gap' when it has ≥ 1 known outcome and its pass rate over known
+ * outcomes is ≤ `keepThreshold`; 'saturated' when the rate exceeds the
+ * threshold; 'unknown' when every outcome is unknown. Unknown reps never
+ * count toward the rate in either direction (fail-closed — see the module
+ * doc), and evidence strength stays visible: each task reports `nKnown`
+ * alongside `n`, and the summary totals the unknown reps in `repsUnknown`.
+ * Throws on empty input, an out-of-range `keepThreshold`, or an
+ * unrecognized outcome value (rows are often projected from untyped records).
+ */
+declare function capabilityHeadroom(rows: readonly HeadroomInput[], opts?: CapabilityHeadroomOptions): CapabilityHeadroomResult;
+interface AssertCapabilityHeadroomOptions {
+  /** Minimum tasks classified 'gap' for the comparison to proceed. Default 1. */
+  minTasksWithGap?: number;
+}
+/**
+ * The go/no-go guard: throws when fewer than `minTasksWithGap` tasks have
+ * baseline headroom — i.e. the benchmark cannot see the capability, so any
+ * comparison run on it would measure noise. Call between the baseline
+ * calibration run and the treatment run.
+ */
+declare function assertCapabilityHeadroom(result: CapabilityHeadroomResult, opts?: AssertCapabilityHeadroomOptions): void;
+/**
+ * Cost tracker — token + USD accounting per scenario and per run.
+ *
+ * Adapted from generic usage-event accounting. Every
+ * optimizer needs to know "is the quality gain worth the cost delta?",
+ * and every dashboard needs dollars-per-completed-task. MODEL_PRICING
+ * from metrics.ts stays authoritative for estimate math; this module
+ * adds the aggregation + per-scenario roll-up that was duplicated
+ * across 4 verticals.
+ */
+interface TokenSpec {
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens?: number;
+  reasoningTokens?: number;
+}
+interface CostEntry extends TokenSpec {
+  scenarioId: string;
+  model: string;
+  /** Override estimate with an observed cost (e.g. from provider response). */
+  actualCostUsd?: number;
+  timestamp: number;
+  /** Free-form tags (variant id, round #, etc.). */
+  tags?: Record<string, string>;
+}
+interface ScenarioCost {
+  scenarioId: string;
+  entries: CostEntry[];
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCachedTokens: number;
+  totalCostUsd: number;
+  /** Pass flag — set by consumer via markOutcome; used for cost-per-completed-task. */
+  completed?: boolean;
+}
+declare class CostTracker {
+  private byScenario;
+  record(entry: Omit<CostEntry, 'timestamp'> & {
+    timestamp?: number;
+  }): CostEntry;
+  markOutcome(scenarioId: string, completed: boolean): void;
+  /**
+   * Convenience: record + markOutcome in one call from a
+   * `{ usage, verdict }`-shaped response (starter-foundry's
+   * `invokeMetaJudge` returns this shape; consumers that wrap any
+   * judge/critic can follow the same convention).
+   *
+   * `usage.model` must be present in `MODEL_PRICING` for cost math to
+   * populate; otherwise totalCostUsd stays at 0 for the entry but
+   * tokens still aggregate.
+   */
+  recordVerdict(verdict: {
+    usage?: {
+      inputTokens: number;
+      outputTokens: number;
+      model: string;
+      cachedTokens?: number;
+      reasoningTokens?: number;
+    };
+    verdict?: 'pass' | 'fail' | 'borderline' | string;
+  }, scenarioId: string, tags?: Record<string, string>): CostEntry | null;
+  get(scenarioId: string): ScenarioCost | undefined;
+  list(): ScenarioCost[];
+  summary(): CostSummary;
+}
+interface CostSummary {
+  scenarioCount: number;
+  completedCount: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCostUsd: number;
+  avgCostPerScenarioUsd: number;
+  /** Total USD / completed scenarios — null when nothing completed. */
+  costPerCompletedTaskUsd: number | null;
+}
+type DetectorSeverity = 'info' | 'warn' | 'critical';
+/** A normalized step a detector folds over. Fields are optional; each detector reads only what it
+ *  needs (repeated-action → `actionFingerprint`; no-progress → `stateFingerprint` + `score`;
+ *  error-streak → `status`). */
+interface DetectorEvent {
+  /** Fingerprint of the action/tool-call this step took (caller pre-hashes). */
+  readonly actionFingerprint?: string;
+  /** Fingerprint of observable state AFTER this step. */
+  readonly stateFingerprint?: string;
+  /** Score after this step (the score-flat half of no-progress). */
+  readonly score?: number;
+  /** Whether this step errored. */
+  readonly status?: 'ok' | 'error';
+  /** Free-form label carried into the signal evidence (e.g. the tool name). */
+  readonly label?: string;
+}
+interface DetectorSignal {
+  readonly detector: string;
+  readonly severity: DetectorSeverity;
+  readonly failureClass?: FailureClass;
+  readonly reason: string;
+  /** Consecutive matching steps at the moment the signal fired. */
+  readonly streak: number;
+  readonly evidence?: Record<string, unknown>;
+}
+interface StreamingDetector {
+  readonly id: string;
+  /** Current streak (consecutive matching steps) — for telemetry/introspection between observes. */
+  readonly streak: number;
+  /** Fold one event; return a signal when the threshold trips, else null. */
+  observe(event: DetectorEvent): DetectorSignal | null;
+  /** Clear all state. */
+  reset(): void;
+}
+interface RepeatedActionOptions {
+  /** Signal once the same action fingerprint repeats this many CONSECUTIVE steps (default 3).
+   *  `<= 0` disables the signal (the streak is still tracked, for telemetry). */
+  readonly maxRepeated?: number;
+  readonly severity?: DetectorSeverity;
+  /** Failure class to stamp on the signal (default `tool_recovery_failure`). */
+  readonly failureClass?: FailureClass;
+}
+/** Same action fingerprint N consecutive steps = a stuck loop (the #1 long-horizon failure mode). */
+declare function repeatedActionDetector(opts?: RepeatedActionOptions): StreamingDetector;
+interface ErrorStreakOptions {
+  /** Signal once this many CONSECUTIVE steps errored (default 3). `<= 0` disables. */
+  readonly maxErrors?: number;
+  readonly severity?: DetectorSeverity;
+  readonly failureClass?: FailureClass;
+}
+/** N consecutive tool errors = the worker is hammering a broken approach. */
+declare function errorStreakDetector(opts?: ErrorStreakOptions): StreamingDetector;
+/** Fold one event through many detectors at once; returns every signal that fired this step. The
+ *  natural shape for an online pipe watching with a whole panel of detectors. */
+declare function observeAll(detectors: ReadonlyArray<StreamingDetector>, event: DetectorEvent): DetectorSignal[];
+/**
+ * Toolchain error-count extractor.
+ *
+ * Given stderr/stdout from a compiler or test runner, count the number
+ * of reported errors/failures. Patterns are deliberately narrow —
+ * unknown stderr returns `null` rather than zero so callers can
+ * distinguish "no errors" from "different toolchain, couldn't parse".
+ *
+ * All patterns are anchored to the start of a line and use bounded
+ * character classes to avoid catastrophic backtracking on pathological
+ * inputs.
+ *
+ * Add new toolchains by appending to {@link ERROR_COUNT_PATTERNS};
+ * order matters only in the sense that the first matching pattern wins.
+ */
+interface ErrorCountPattern {
+  /** Stable identifier for logging + tests. */
+  name: string;
+  /** Must be global (`g` flag) — the extractor counts matches. */
+  regex: RegExp;
+  /** Optional post-processing to extract a count from a single captured match. */
+  transform?: (match: RegExpMatchArray) => number;
+}
+declare const ERROR_COUNT_PATTERNS: ErrorCountPattern[];
+interface ExtractOptions {
+  /** Restrict to named patterns — default: all patterns. */
+  only?: string[];
+  /** Additional patterns to consider BEFORE the built-in list. */
+  extra?: ErrorCountPattern[];
+}
+interface ExtractResult {
+  /** Total count of matched errors, or null when no pattern matched. */
+  count: number | null;
+  /** Name of the pattern that matched, or null. */
+  matched: string | null;
+  /** Original matches for callers that want to surface specifics. */
+  samples: string[];
+}
+/**
+ * Try each pattern in order; return the first with matches.
+ *
+ * Returning `null` (instead of zero) on no-match is deliberate — a
+ * callsite that greps for "typescript errors" on cargo output should
+ * NOT treat that as "zero TS errors" because the toolchain is wrong.
+ */
+declare function extractErrorCount(text: string, opts?: ExtractOptions): ExtractResult;
+type KnowledgeRequirementCategory = 'user_specific' | 'company_specific' | 'domain_specific' | 'codebase_specific' | 'market_specific' | 'regulatory' | 'tool_api' | 'credential_or_secret' | 'runtime_environment' | 'preference' | 'historical_context';
+type KnowledgeAcquisitionMode = 'ask_user' | 'search_web' | 'query_connector' | 'inspect_repo' | 'run_command' | 'infer_low_confidence' | 'not_available';
+type KnowledgeImportance = 'blocking' | 'high' | 'medium' | 'low';
+type KnowledgeFreshness = 'static' | 'monthly' | 'weekly' | 'daily' | 'realtime';
+type KnowledgeSensitivity = 'public' | 'private' | 'secret';
+type KnowledgeFallbackPolicy = 'block' | 'ask' | 'continue_with_caveat' | 'use_default';
+interface KnowledgeRequirement {
+  id: string;
+  description: string;
+  requiredFor: string[];
+  category: KnowledgeRequirementCategory;
+  acquisitionMode: KnowledgeAcquisitionMode;
+  importance: KnowledgeImportance;
+  freshness: KnowledgeFreshness;
+  sensitivity: KnowledgeSensitivity;
+  confidenceNeeded: number;
+  currentConfidence: number;
+  evidenceIds: string[];
+  fallbackPolicy: KnowledgeFallbackPolicy;
+  /**
+   * ISO timestamp after which this requirement must be treated as stale.
+   * Stale requirements score as missing even when they still have evidence.
+   */
+  validUntil?: string;
+  /** ISO timestamp for the last source-grounding or human verification pass. */
+  lastVerifiedAt?: string;
+  metadata?: Record<string, unknown>;
+}
+interface KnowledgeBundle {
+  taskId: string;
+  requirements: KnowledgeRequirement[];
+  evidenceIds: string[];
+  claimIds: string[];
+  wikiPageIds: string[];
+  userAnswers: Record<string, string>;
+  missing: KnowledgeRequirement[];
+  readinessScore: number;
+  metadata?: Record<string, unknown>;
+}
+type KnowledgeRecommendedAction = 'run_agent' | 'ask_user' | 'collect_web_data' | 'query_connectors' | 'inspect_repo' | 'build_domain_wiki' | 'continue_with_caveat' | 'abort_or_rescope';
+interface KnowledgeReadinessReport {
+  taskId: string;
+  readinessScore: number;
+  blockingMissingRequirements: KnowledgeRequirement[];
+  nonBlockingGaps: KnowledgeRequirement[];
+  recommendedAction: KnowledgeRecommendedAction;
+  bundle: KnowledgeBundle;
+  severity: ControlSeverity;
+  reason: string;
+}
+interface UserQuestion {
+  id: string;
+  question: string;
+  reason: string;
+  requirementId: string;
+  importance: KnowledgeImportance;
+  answerType: 'free_text' | 'select_one' | 'multi_select' | 'file_upload' | 'credential' | 'url';
+  defaultIfSkipped?: string;
+  impactIfUnknown: string;
+  options?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface DataAcquisitionPlan {
+  id: string;
+  requirementIds: string[];
+  mode: Exclude<KnowledgeAcquisitionMode, 'not_available' | 'infer_low_confidence'> | 'build_domain_wiki';
+  description: string;
+  priority: KnowledgeImportance;
+  expectedEvidenceIds?: string[];
+  questions?: UserQuestion[];
+  metadata?: Record<string, unknown>;
+}
+interface LeaderboardRow {
+  /** Group key — the agent-profile cellId by default, else a caller dimension. */
+  key: string;
+  /** Display label: `harness · model` when the profile carries them, else the key. */
+  label: string;
+  harness?: string;
+  model?: string;
+  rank: number;
+  /** Measured runs in this group. */
+  n: number;
+  passRate: number;
+  passRateCi95: [number, number];
+  /** Observability rollup — means over the group; null when no run reported it. */
+  meanCostUsd: number | null;
+  meanTokensIn: number | null;
+  meanTokensOut: number | null;
+  meanWallMs: number | null;
+}
+interface LeaderboardOptions {
+  /** Per-run pass predicate — the benchmark defines what "passed" means (real-build
+   *  hit-rate, test-pass, etc.). The leaderboard owns only the grouping + stats. */
+  passed: (record: RunRecord) => boolean;
+  /** Group key. Default: the agent-profile cellId (harness × model × dimensions),
+   *  so persona/harness/model sweeps separate without parsing labels. */
+  groupBy?: (record: RunRecord) => string;
+}
+/**
+ * Group `records`, compute pass-rate + Wilson CI + cost/token/latency means per
+ * group, and rank by pass-rate (cost as the tiebreaker — cheaper wins a tie).
+ * Pure projection: no I/O, deterministic, safe to call on any RunRecord[].
+ */
+declare function leaderboard(records: RunRecord[], opts: LeaderboardOptions): LeaderboardRow[];
+interface PairedDeltaTestOptions extends PairedBootstrapOptions {
+  /** Smallest candidate-minus-baseline delta that counts as improvement. Default 0. */
+  threshold?: number;
+  /** Caller-required paired observations. The exact test may impose a higher minimum. */
+  minPairs?: number;
+}
+interface PairedDeltaTestResult {
+  bootstrap: PairedBootstrapResult;
+  method: 'bootstrap-ci' | 'exact-sign';
+  /** Exact one-sided p-value below the bootstrap minimum; otherwise null. */
+  pValue: number | null;
+  /** Effective observation minimum after accounting for confidence. */
+  minimumPairs: number;
+  sufficient: boolean;
+  /**
+   * The bootstrap interval has zero width (or is non-finite), so it carries no
+   * information about how far the estimate could be wrong and cannot support a
+   * decision in either direction. See {@link pairedDeltaTest}.
+   */
+  indeterminate: boolean;
+  significant: boolean;
+}
+/** Smallest all-positive sample that can clear a one-sided exact sign test. */
+declare function minimumPairsForPairedDeltaTest(confidence?: number): number;
+/**
+ * Tests whether a paired candidate-minus-baseline delta clears a threshold.
+ *
+ * At 20 or more pairs, the percentile bootstrap lower bound carries the
+ * decision. Below that point the interval is descriptive only, so the function
+ * switches to a pre-registered one-sided exact sign test. The exact path is
+ * deliberately conservative: it requires both a point estimate above the
+ * threshold and enough consistently positive paired differences.
+ *
+ * ## A zero-width interval is never significant
+ *
+ * When every paired delta is identical the resample distribution is a point
+ * mass and the interval collapses: `[0, 0]` when all pairs tie, `[g, g]` on n
+ * identical deltas of g. Neither says the effect is certain — both say the
+ * sample carries no information about how far the estimate could be wrong, and
+ * `low > threshold` then answers on the point estimate alone. It fails in both
+ * directions: `[0, 0]` clears every NEGATIVE threshold, which is how a
+ * tie-dominated pass/fail comparison laundered a regression into a
+ * noninferiority pass, and `[g, g]` clears every threshold below g with no
+ * spread behind it. Under a bounded asymmetric null whose true mean paired
+ * delta is exactly 0 — 2 % of pairs dropping by 1.0, the rest gaining 0.0204 —
+ * every sample that misses the drop is exactly that shape, and deciding on
+ * `low > 0` promoted 65.65 % of samples at n = 20 against a nominal 5 %.
+ *
+ * So `indeterminate` is reported and `significant` is false whenever the
+ * interval has zero width, on BOTH paths: at small n the exact sign test is a
+ * test of the MEDIAN and a zero-spread sample is precisely where it stops
+ * saying anything about the mean the caller is thresholding.
+ *
+ * `threshold` may be negative — that is a noninferiority margin, and it is the
+ * regime the zero-width hole is worst in. For a two-point (pass/fail) outcome
+ * the percentile bootstrap is not a valid interval at a nonzero margin at all;
+ * use {@link decidePairedPromotion}, which routes those to Tango's score
+ * interval, rather than thresholding this function's bootstrap directly.
+ */
+declare function pairedDeltaTest(before: number[], after: number[], options?: PairedDeltaTestOptions): PairedDeltaTestResult;
+/**
+ * Deterministic held-out partitioning over stable ids.
+ *
+ * A promotion gate's paired-delta math needs a fixed partition: the same
+ * scenario id lands in the same bucket forever, regardless of when it ran or
+ * which loop emitted the record — otherwise the gate has nothing paired to
+ * compare against. Picking one global split per run is wrong: every run then
+ * stamps either ALL search or ALL holdout, and no id is ever observed on both
+ * sides. Per-id deterministic hashing fixes that.
+ *
+ * Two consumers hand-roll this (agent-builder's `deterministicSplit` and the
+ * frontier persona-splitter). The substrate already has a 3-way benchmark
+ * `deterministicSplit` in `./benchmarks`; this is the generic, validated batch
+ * partitioner: it takes a list of ids, splits them by a stable FNV-1a hash, and
+ * fails loud when the inputs can't support a trustworthy held-out comparison
+ * (duplicate ids, or a holdout set below the significance floor).
+ */
+interface PartitionHeldOutOptions {
+  /** Partition seed. Bumping it reshuffles every assignment — do that only when
+   *  the corpus/policy changes meaningfully so old and new records can't pair.
+   *  Default 'held-out-v1'. */
+  seed?: string;
+  /** Fraction routed to the held-out bucket, in (0, 1). Default 0.5. */
+  holdoutFraction?: number;
+  /**
+   * Minimum held-out ids required for the split to be admissible. Below this,
+   * a paired comparison has too few observations to be significant, so the
+   * partition throws rather than hand back an underpowered holdout. Default 1
+   * (only the empty-holdout degenerate case is rejected). Raise it to enforce
+   * real statistical power. */
+  minHoldout?: number;
+  /** Same floor for the search side. Default 1. */
+  minSearch?: number;
+}
+interface HeldOutPartition {
+  /** Ids the optimizer is allowed to read/optimize against. */
+  search: string[];
+  /** Ids reserved for gated, held-out evaluation. */
+  holdout: string[];
+  seed: string;
+  holdoutFraction: number;
+}
+/**
+ * Partition a list of stable ids into disjoint `search` / `holdout` sets by a
+ * deterministic hash. Fail-loud:
+ *   - empty input throws,
+ *   - duplicate ids throw (a dup would be observed on both sides, double-counting),
+ *   - a holdout (or search) set below its floor throws (underpowered comparison).
+ *
+ * Order within each bucket follows the input order, so the result is stable and
+ * reproducible.
+ */
+declare function partitionHeldOut(ids: string[], options?: PartitionHeldOutOptions): HeldOutPartition;
+interface TrainSelectionTestOptions<T> {
+  /** Partition seed. Bumping it reshuffles every unit. Default 'train-selection-test-v1'. */
+  seed?: string;
+  /** Share of units routed to selection, in (0, 1). Default 0.25. */
+  selectionFraction?: number;
+  /** Share of units routed to test, in (0, 1). Default 0.25. */
+  testFraction?: number;
+  /**
+   * The independent unit an item samples, such as the task a fresh run repeats.
+   * Every item of one unit lands in the same partition, so a final test never
+   * scores a unit the optimizer read. Default: the item id.
+   */
+  unitOf?: (item: T) => string;
+  /** Minimum items per partition. Defaults 1, 1 and 1. */
+  minTrain?: number;
+  minSelection?: number;
+  minTest?: number;
+}
+interface TrainSelectionTestPartition<T> {
+  /** Items an optimizer may learn from. */
+  train: T[];
+  /** Items an optimizer may use to accept candidates and stop. */
+  selection: T[];
+  /** Items reserved for the final comparison. */
+  test: T[];
+  seed: string;
+  selectionFraction: number;
+  testFraction: number;
+}
+interface ProductBenchmarkExportOptions {
+  /** Source eval run directories, each containing a `records.jsonl` of RunRecord rows. */
+  readonly runDirs: readonly string[];
+  /** Destination directory for the bundle (manifest + records + materialized source runs). */
+  readonly outDir: string;
+  readonly projectId: string;
+  readonly benchmarkId: string;
+  /** Repo-relative path of the product's canonical agent profile source. */
+  readonly agentProfilePath: string;
+  /** Pass threshold applied when a row carries no explicit `outcome.raw.pass`. Default 0.7. */
+  readonly passThreshold?: number;
+  /**
+   * First scenario tag. Defaults to `projectId` with a trailing `-agent`
+   * stripped (`tax-agent` → `tax`), matching the product exporters.
+   */
+  readonly scenarioTagPrefix?: string;
+  /** Profile id used when a row has no `agentProfile.profileId`. Defaults to the row's arm id. */
+  readonly fallbackProfileId?: string;
+  /** Arm mutable surfaces recorded in the manifest. Defaults to the full superset. */
+  readonly mutableSurfaces?: readonly string[];
+  /**
+   * Copy each run dir into `<outDir>/source-runs/` and record
+   * bundle-relative artifact paths (portable, self-contained). When false,
+   * artifacts keep absolute paths into the original run dirs. Default true.
+   */
+  readonly materializeSourceRuns?: boolean;
+  /**
+   * Override split classification for a row. Return undefined to fall back
+   * to the default (`outcome.raw.safety === 1` → safety, then splitTag).
+   */
+  readonly classifySplit?: (record: RunRecord) => ProductBenchmarkSplit | undefined;
+  /** Recovers a tool-call count when the row's raw bag carries none (e.g. from turn artifacts). */
+  readonly toolCallFallback?: (record: RunRecord, runDir: string) => number;
+  /** Backend version recorded per row. Defaults to the cwd package.json's `@tangle-network/sandbox` range. */
+  readonly backendVersion?: string;
+  /**
+   * Explicit substrate versions for the manifest, merged over what the cwd
+   * package.json / node_modules resolve. Use when a substrate package is not
+   * installed where the export runs — the validator refuses an `'unknown'`
+   * version, so provide the real one rather than shipping the sentinel.
+   */
+  readonly substrate?: Partial<ProductBenchmarkManifest['substrate']>;
+}
+interface ProductBenchmarkSingleRunExportOptions extends Omit<ProductBenchmarkExportOptions, 'runDirs'> {
+  readonly runDir: string;
+}
+interface ProductBenchmarkExportResult {
+  readonly manifestPath: string;
+  readonly recordsPath: string;
+  readonly records: number;
+}
+/** Repo identity from the exporting process's cwd. `'unknown'` values are flagged by `validateProductBenchmarkRun`. */
+declare function productBenchmarkRepoIdentity(): ProductBenchmarkManifest['repo'];
+/** Single-run convenience wrapper over `exportProductBenchmarkRuns`. */
+declare function exportProductBenchmark(options: ProductBenchmarkSingleRunExportOptions): ProductBenchmarkExportResult;
+/**
+ * Export one or more product eval run dirs into a validated product
+ * benchmark bundle at `outDir`. Both the manifest and every record are
+ * run through the contract validators before anything is written.
+ */
+declare function exportProductBenchmarkRuns(options: ProductBenchmarkExportOptions): ProductBenchmarkExportResult;
+declare const productBenchmarkSplits: readonly ["practice", "dev", "holdout", "safety", "sentinel"];
+type ProductBenchmarkSplit = (typeof productBenchmarkSplits)[number];
+interface ProductBenchmarkRepoRef {
+  readonly url: string;
+  readonly commit: string;
+  readonly branch: string;
+}
+interface ProductBenchmarkSubstrateVersions {
+  readonly agentEval: string;
+  readonly agentRuntime: string;
+  readonly agentInterface: string;
+  readonly sandbox: string;
+  readonly agentBench?: string;
+}
+interface ProductBenchmarkProfileRef {
+  readonly id: string;
+  readonly profileHash: string;
+  readonly agentProfilePath: string;
+}
+interface ProductBenchmarkArm {
+  readonly id: string;
+  readonly profileId: string;
+  readonly mutableSurfaces: readonly string[];
+  readonly policyAxes: Record<string, unknown>;
+}
+interface ProductBenchmarkScenario {
+  readonly id: string;
+  readonly split: ProductBenchmarkSplit;
+  readonly tags: readonly string[];
+  readonly sourceAllowedForSynthesis: boolean;
+}
+interface ProductBenchmarkBudgets {
+  readonly maxUsd: number;
+  readonly maxCells: number;
+  readonly maxWallMs: number;
+}
+interface ProductBenchmarkManifest {
+  readonly schemaVersion: 1;
+  readonly projectId: string;
+  readonly benchmarkId: string;
+  readonly repo: ProductBenchmarkRepoRef;
+  readonly substrate: ProductBenchmarkSubstrateVersions;
+  readonly profiles: readonly ProductBenchmarkProfileRef[];
+  readonly arms: readonly ProductBenchmarkArm[];
+  readonly scenarios: readonly ProductBenchmarkScenario[];
+  readonly budgets: ProductBenchmarkBudgets;
+  readonly expectedArtifactDir: string;
+}
+interface ProductBenchmarkValidationReport {
+  readonly manifestPath: string;
+  readonly recordsPath: string;
+  readonly records: number;
+  /** Manifest repo fields that are empty or the `'unknown'` export sentinel. */
+  readonly repoFailures: readonly string[];
+  /** Manifest substrate versions that are empty or the `'unknown'` export
+   *  sentinel — a bundle without substrate identity is not reproducible. */
+  readonly substrateFailures: readonly string[];
+  readonly projects: readonly string[];
+  readonly benchmarks: readonly string[];
+  readonly arms: readonly string[];
+  readonly scenarios: readonly string[];
+  readonly passed: number;
+  readonly failed: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd: number;
+  readonly wallMs: number;
+  readonly integrityFailures: readonly string[];
+  readonly missingArtifacts: readonly string[];
+}
+declare function readProductBenchmarkManifest(path: string): ProductBenchmarkManifest;
+/**
+ * Fail-loud gate over a bundle directory: locates the manifest + records,
+ * runs `validateProductBenchmarkRun`, and throws with every repo,
+ * integrity, and artifact failure listed. Returns the report when clean.
+ */
+declare function assertProductBenchmarkRun(runDir: string): ProductBenchmarkValidationReport;
+interface RuntimeTrajectoryHookEvent {
+  id: string;
+  runId: string;
+  scenarioId?: string;
+  target: string;
+  phase: string;
+  timestamp: number;
+  stepIndex?: number;
+  parentId?: string;
+  payload?: unknown;
+  metadata?: Record<string, unknown>;
+}
+interface RuntimeTrajectoryRecord {
+  id?: string;
+  scenarioId?: string;
+  splitTag?: RunSplitTag;
+  runtimeEvents?: unknown;
+  [key: string]: unknown;
+}
+interface RuntimeTrajectoryRunRecord {
+  runId: string;
+  scenarioId?: string;
+  splitTag: RunSplitTag;
+}
+interface RuntimeTrajectoryEvidenceSummary {
+  recordCount: number;
+  recordWithRuntimeEventsCount: number;
+  runtimeRunCount: number;
+  lifecycleEventCount: number;
+  defaultedSplitCount: number;
+}
+interface RuntimeTrajectoryEvidenceProjection {
+  runs: RuntimeTrajectoryRunRecord[];
+  events: RuntimeTrajectoryHookEvent[];
+  summary: RuntimeTrajectoryEvidenceSummary;
+  diagnostics: string[];
+}
+interface ProjectRuntimeTrajectoryEvidenceOptions<TRecord extends RuntimeTrajectoryRecord = RuntimeTrajectoryRecord> {
+  records: TRecord[];
+  defaultSplitTag?: RunSplitTag;
+  recordIdOf?: (record: TRecord, index: number) => string | undefined;
+  scenarioIdOf?: (record: TRecord, index: number) => string | undefined;
+}
+declare function projectRuntimeTrajectoryEvidence<TRecord extends RuntimeTrajectoryRecord>(options: ProjectRuntimeTrajectoryEvidenceOptions<TRecord>): RuntimeTrajectoryEvidenceProjection;
+type SynthesisReason = 'high-variance' | 'undersampled' | 'failure-cluster' | 'difficulty-gap';
+interface SynthesisTarget {
+  reason: SynthesisReason;
+  description: string;
+  /** Existing scenarios that are closest to the gap; caller feeds these to
+   *  their LLM proposer as few-shot examples. */
+  neighbors: DatasetScenario[];
+  /** Suggested direction — e.g. "harder variants", "edge cases of X", "failure class Y". */
+  direction: string;
+  /** Priority score — higher = more information-dense gap. 0..1. */
+  priority: number;
+}
+interface ActiveLearningOptions {
+  /** Minimum scenarios per difficulty band to count as "covered". */
+  minPerBand?: number;
+  /** Variance threshold above which a scenario's dimension is "unstable". */
+  varianceThreshold?: number;
+  /** Max synthesis targets returned. */
+  topK?: number;
+}
+declare function proposeSynthesisTargets(dataset: Dataset, traceStore: TraceStore, options?: ActiveLearningOptions): Promise<SynthesisTarget[]>;
+/**
+ * `runBoundedProcess` — run one command under a wall-clock bound and return
+ * what it produced, leaving no descendant behind.
+ *
+ * The child leads its own process group (`detached` on every non-win32
+ * platform), so a deadline or an abort kills the group with
+ * `process.kill(-pid, 'SIGKILL')` rather than only the shell that was
+ * spawned. That distinction is the whole point of this module: `sh -c
+ * 'solver & wait'` puts the real work in a grandchild, and a kill aimed at
+ * the shell alone leaves that grandchild running, holding the stdout and
+ * stderr pipes open. `close` then never fires, so the deadline produces no
+ * result the caller can observe and the descendant outlives the run.
+ *
+ * Two further guarantees the caller depends on:
+ *
+ *   - A killed run never reports success. A SIGKILLed child can still close
+ *     with exit code 0, so a run killed by the deadline or by an abort has
+ *     its exit code forced non-zero.
+ *   - A run always resolves. If a grandchild escaped the group and still
+ *     holds the pipes, the result is delivered {@link KILL_DRAIN_MS} after
+ *     the kill instead of waiting on a `close` that will not come.
+ *
+ * The captured output is bounded. Once the cap is reached the streams are
+ * still drained — the child needs its pipes read to reach `close` — but the
+ * bytes are discarded and `outputTruncated` is set.
+ */
+/** Wall-clock bound applied when the caller names none. */
+declare const DEFAULT_BOUNDED_PROCESS_TIMEOUT_MS: number;
+interface BoundedProcessInput {
+  /**
+   * The command line, interpreted by a shell unless `shell` is `false`. When
+   * {@link BoundedProcessInput.args} is present this is a program path
+   * instead, and no shell reads it.
+   */
+  command: string;
+  /**
+   * Argument vector for `command`, delivered to the program as separate
+   * argv entries with no shell between them.
+   *
+   * This is the form to use whenever an argument carries text the caller did
+   * not author — a script body, a path, a pattern. Without it, `interpreter
+   * -flag <script>` can only be expressed by quoting the script into a
+   * shell string, and a quoting bug there is a command injection rather than
+   * a wrong answer. Each entry arrives verbatim, so there is nothing to
+   * quote: `{ command: 'bash', args: ['-n', '-c', body] }` parses `body`
+   * whatever shell metacharacters it holds.
+   *
+   * Two limits are the platform's, not this module's. A NUL byte in an entry
+   * cannot be passed to a process at all, and is reported as a `runnerError`
+   * rather than thrown. A lone surrogate is encoded to UTF-8 as U+FFFD, and a
+   * non-string entry from an untypechecked caller is coerced with `String()`,
+   * so an entry is verbatim exactly when it is a string a UTF-8 argv can hold.
+   *
+   * A shell cannot interpret an argument vector, so `args` and a truthy
+   * `shell` are contradictory. Passing both spawns nothing and reports
+   * `runnerError`.
+   */
+  args?: string[];
+  /**
+   * Text written to the child's standard input. The stream is closed after
+   * the write, so a command that reads until end-of-file sees exactly this
+   * payload and then EOF.
+   *
+   * The child's stdin is closed whether or not this field is present. A pipe
+   * nobody closes is a hang: a command that reads stdin waits for bytes that
+   * never arrive until the deadline kills it, which reads downstream as a
+   * slow command rather than as a caller that forgot to send input.
+   *
+   * The payload is written as UTF-8 and is otherwise verbatim: a NUL byte,
+   * a newline, a quote and a backslash all arrive as themselves, because
+   * nothing parses this text. The one platform limit is the one `args`
+   * already states — a lone surrogate is encoded as U+FFFD, since no UTF-8
+   * stream can carry it.
+   *
+   * A child that exits before reading breaks the pipe. That is the child's
+   * behaviour, not a runner failure, so the run still settles on the child's
+   * own exit code, and the undelivered payload is reported in `runnerError`
+   * with the `stdin not delivered:` prefix. Whether a SMALL payload to a
+   * command that ignores stdin reports this is a race — the write may land in
+   * the pipe buffer before the child exits — so the flag is a statement about
+   * delivery, never about the command. It is not a race for the case that
+   * matters: a payload larger than the pipe buffer that the child never
+   * drains cannot be delivered, and reports every time.
+   */
+  stdin?: string;
+  /**
+   * Shell that interprets `command`. `true` (the default) uses the platform
+   * default — `/bin/sh` on POSIX, `cmd.exe` on Windows. A string names the
+   * shell binary, e.g. `'bash'`, which is required for a bash-only construct
+   * such as `[[ ]]` or `$BASH_VERSION`. `false` executes `command` directly
+   * as a program path with no arguments. Ignored — and refused when truthy —
+   * once {@link BoundedProcessInput.args} is present.
+   */
+  shell?: boolean | string;
+  /** Working directory. The parent's cwd is inherited when omitted. */
+  cwd?: string;
+  /**
+   * Environment for the child. How it combines with the parent environment
+   * is decided by {@link BoundedProcessInput.envMode}.
+   */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * `'merge'` (the default) layers `env` on top of `process.env`, so the
+   * child sees every variable this process has plus the named ones.
+   * `'replace'` passes exactly `env` and nothing else, which is what a
+   * grader needs when the claim under test is about the variables the
+   * command could read. `PATH` is not re-added under `'replace'`, and a
+   * command that must find a binary on `PATH` names `PATH` itself.
+   *
+   * With no `PATH` in the child environment the two forms do NOT search the
+   * same directories, so a caller under `'replace'` that names no `PATH` gets
+   * a resolution that depends on which form it picked. The shell form execs
+   * the shell, which applies its own compiled-in default; the argv form
+   * reaches `execvp`, which falls back to `confstr(_CS_PATH)`. Measured on
+   * Linux/glibc: `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`
+   * against `/bin:/usr/bin`, so a binary in `/usr/local/bin` resolves on the
+   * shell form and reports ENOENT on the argv form. Name `PATH` and both
+   * forms search exactly what was named.
+   */
+  envMode?: 'merge' | 'replace';
+  /** Wall-clock bound in ms. Defaults to 10 minutes. */
+  timeoutMs?: number;
+  /**
+   * Cap on captured stdout+stderr. Reaching it truncates the captured text
+   * and sets `outputTruncated`; it never kills the process. Defaults to
+   * 16 MiB.
+   */
+  maxOutputBytes?: number;
+  /**
+   * Kills the process group when it aborts, the same way the deadline does.
+   * A signal that is already aborted when `runBoundedProcess` is called
+   * prevents the spawn entirely — nothing runs.
+   */
+  signal?: AbortSignal;
+}
+interface BoundedProcessResult {
+  /**
+   * The process actually started. False when nothing ran at all: an
+   * already-aborted signal, `args` with a truthy `shell`, an argument the
+   * platform refuses, or a program that does not exist.
+   *
+   * This is the field to branch on, never the text of `runnerError`. A caller
+   * deciding whether a run produced an outcome at all is asking exactly this,
+   * and asking it here is type-checked rather than held by a wording
+   * convention.
+   */
+  spawned: boolean;
+  /**
+   * The `stdin` payload reached the child in full. True whenever the caller
+   * supplied none, because nothing could fail to arrive.
+   *
+   * False means the command ran on partial input, which is a fact about the
+   * answer it produced: a checksum over a truncated payload is a wrong answer,
+   * not a failed run. `spawned` stays true and `exitCode` stays the child's.
+   */
+  stdinDelivered: boolean;
+  /**
+   * Exit code. Forced non-zero whenever `killedByTimeout` or
+   * `killedBySignal` is set, because a SIGKILLed child can close with 0 and
+   * a killed run must never read as a pass.
+   */
+  exitCode: number;
+  /** Captured stdout, truncated at `maxOutputBytes`. */
+  stdout: string;
+  /**
+   * Captured stderr, truncated at `maxOutputBytes`. A runner-side failure is
+   * reported in `runnerError`, not appended here; the caller decides whether
+   * the command's own stderr and the runner's diagnosis belong together.
+   */
+  stderr: string;
+  /** Wall-clock duration in ms, measured across the whole call. */
+  wallMs: number;
+  /** The wall-clock bound was reached and the process group was killed. */
+  killedByTimeout: boolean;
+  /** `signal` aborted and the process group was killed. */
+  killedBySignal: boolean;
+  /** `maxOutputBytes` was reached and later output was discarded. */
+  outputTruncated: boolean;
+  /**
+   * Human-readable diagnosis of a runner-side failure, in one of three shapes:
+   *
+   *   - `not spawned:` — the caller's own bug, such as `args` with a truthy
+   *     `shell`, or an already-aborted signal. No retry helps.
+   *   - `stdin not delivered:` — the command ran and exited on its own, and
+   *     the stdin payload did not reach it in full because the child closed
+   *     the pipe first.
+   *   - anything else — the process could not be spawned (a missing binary, a
+   *     NUL byte in an argument).
+   *
+   * Absent when the command ran and read everything it was sent, however it
+   * exited. The prefixes are for a person reading a log; code reads `spawned`
+   * and `stdinDelivered`, which say the same things and are type-checked.
+   */
+  runnerError?: string;
+}
+declare function runBoundedProcess(input: BoundedProcessInput): Promise<BoundedProcessResult>;
+/**
+ * CommandRunner — abstract subprocess execution surface.
+ *
+ * Layers in a {@link MultiLayerVerifier} that need to invoke external
+ * tools (compilers, test runners, package managers) call out via this
+ * interface rather than directly using `child_process`. Two reasons:
+ *
+ *   1. **Sandbox interchangeability.** A run that targets a sandbox box
+ *      (via SDK-specific Box.exec) and a run that targets the host both
+ *      satisfy this same contract. The harness doesn't care which.
+ *   2. **Testability.** Tests inject a fake runner and assert on calls
+ *      without spawning real subprocesses.
+ *
+ * agent-eval ships only the local implementation (host-process). Sandbox
+ * implementations live with their consumer because they depend on
+ * SDK-specific Box / Sandbox types that don't belong in this package.
+ */
+interface RunCommandInput {
+  /** Executable name, looked up via PATH unless absolute. */
+  cmd: string;
+  /** Argument vector, NOT shell-interpolated. Each element passed to argv. */
+  argv: string[];
+  /** Working directory. Defaults to runner's notion of cwd if omitted. */
+  cwd?: string;
+  /**
+   * Wall-clock cap in ms. The runner SHOULD return `timedOut: true` when
+   * exceeded; callers MAY treat status null + timedOut as "killed."
+   *
+   * Omitting it does NOT mean unbounded: {@link localCommandRunner} then
+   * applies {@link LOCAL_COMMAND_RUNNER_DEFAULT_CAP_MS}. A command that
+   * legitimately runs longer than that names its own `capMs`; it is never
+   * killed silently, because a run stopped by the bound comes back with
+   * `timedOut: true` and `status: null`.
+   */
+  capMs?: number;
+  /** Env overrides merged on top of the runner's base environment. */
+  env?: Record<string, string>;
+  /** Optional stdin payload. */
+  stdin?: string;
+}
+interface RunCommandResult {
+  /** Exit code, or null when the process couldn't start / was killed. */
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  timedOut: boolean;
+  /** Non-fatal runner-side error (binary missing, signal, etc.). */
+  runnerError?: string;
+}
+interface DirEntry {
+  name: string;
+  isDirectory: boolean;
+  isFile: boolean;
+  /** File size in bytes. `null` for directories (not stat'd). */
+  sizeBytes: number | null;
+}
+interface CommandRunner {
+  /** Identifier for telemetry + logs. Open-ended literal-union for new runners. */
+  readonly name: string;
+  /** Execute a command in the runner's environment. */
+  run(input: RunCommandInput): Promise<RunCommandResult>;
+  /** True iff `<name>` resolves on the runner's PATH. */
+  hasBin(name: string): Promise<boolean>;
+  /** True iff the given path exists in the runner's filesystem. */
+  fileExists(path: string): Promise<boolean>;
+  /** Read a file. Returns `null` if missing or unreadable. */
+  readFile(path: string): Promise<string | null>;
+  /** List a directory. Returns `[]` if unreadable / missing. */
+  readDir(path: string): Promise<DirEntry[]>;
+}
+declare const localCommandRunner: CommandRunner;
+/**
+ * Walk a personas directory and return every file matching the convention
+ * `NN-slug.{yaml,yml,json,md}`. Sorted by filename so the numeric prefix
+ * gives stable persona ordering for reproducibility. Consumers filter
+ * through `include` / `exclude`.
+ */
+interface DiscoverPersonasOptions {
+  /**
+   * Regex applied to filenames. Files that don't match are skipped.
+   * Default: `^[0-9]{2}-.+\.(yaml|yml|json|md)$`.
+   */
+  pattern?: RegExp;
+  /**
+   * Filenames (or basenames) to skip. Use this to exclude WIP / archived
+   * personas without removing the file.
+   */
+  exclude?: readonly string[];
+  /**
+   * If set, return only personas whose basename contains one of these
+   * substrings (post-pattern filter).
+   */
+  include?: readonly string[];
+  /** Recurse into subdirectories. Default false. */
+  recursive?: boolean;
+}
+interface DiscoveredPersona {
+  /** Absolute file path. */
+  path: string;
+  /** Filename without directory. */
+  filename: string;
+  /** Filename without extension — the conventional persona id. */
+  id: string;
+}
+declare function discoverPersonas(dir: string, opts?: DiscoverPersonasOptions): Promise<DiscoveredPersona[]>;
+/** Verdict for one candidate relative to its parent. ITERATE is the neutral
+ *  "keep collecting reps / no parent to compare against" state. */
+type ExperimentVerdict = 'KEEP' | 'ITERATE' | 'NOISE' | 'REGRESSION';
+/** A single repetition of a candidate run, carrying the score the verdict is
+ *  computed on plus any free-form per-rep metrics the consumer wants kept. */
+interface ExperimentRep {
+  /** 0-indexed repetition number. */
+  rep: number;
+  /** The score this rep is judged on (same scale as the thresholds). */
+  score: number;
+  /** ISO timestamp the rep completed. */
+  timestamp: string;
+  /** Stable execution/run identity that produced this score. */
+  runId?: string;
+  /** Mechanically resolvable trace, artifact, metric, or finding evidence. */
+  evidence?: EvidenceRef[];
+  /** Whether this rep passed the consumer's own gate — folded into `passRate`. */
+  passed?: boolean;
+  /** Free-form numeric metrics retained for later analysis. */
+  metrics?: Record<string, number>;
+}
+interface ExperimentStats {
+  median: number;
+  mean: number;
+  min: number;
+  max: number;
+  /** Inter-quartile range of the rep scores. */
+  iqr: number;
+  /** Population standard deviation of the rep scores. */
+  stddev: number;
+  /** Fraction of reps with `passed === true`, over reps that set `passed`.
+   *  null when no rep declared a pass/fail outcome. */
+  passRate: number | null;
+  /** Number of reps. */
+  n: number;
+  /** True when the sample is tight enough to trust for a verdict. */
+  stable: boolean;
+}
+interface ImprovementThresholds {
+  /** medianDelta strictly above this ⇒ KEEP. Default 5. */
+  keepThreshold?: number;
+  /** medianDelta strictly below the negative of this ⇒ REGRESSION. Default 5. */
+  regressionThreshold?: number;
+  /** iqr at or above this ⇒ unstable. Default 10. */
+  iqrUnstableAbove?: number;
+  /** stddev at or above this ⇒ unstable. Default Infinity (iqr-only stability). */
+  stddevUnstableAbove?: number;
+  /** Reps required on BOTH candidate and parent before a verdict is rendered.
+   *  Default 3. */
+  minRepsForVerdict?: number;
+}
+interface ImprovementVerdictResult {
+  verdict: ExperimentVerdict;
+  /** candidate.median − parent.median; null when no parent or insufficient reps. */
+  medianDelta: number | null;
+  /** Human-readable reason for the verdict — for dashboards and logs. */
+  reason: string;
+}
+interface Verification {
+  pass: boolean;
+  score?: number;
+  failingLayers?: string[];
+  details?: unknown;
+}
+interface Review {
+  observations: string;
+  diagnosis: string;
+  nextShotInstruction: string;
+  shouldContinue: boolean;
+  confidence: number;
+}
+interface ReviewMemoryEntry extends Review {
+  shot: number;
+  timestamp: number;
+  verification: {
+    pass: boolean;
+    score?: number;
+    failingLayers?: string[];
+  };
+}
+interface ProposeInput<State> {
+  shot: number;
+  goal: string;
+  state: State;
+  priorReview: Review | null;
+  abortSignal: AbortSignal;
+  emitter?: TraceEmitter;
+}
+interface ProposeOutput<State, Summary = unknown> {
+  state: State;
+  traceSummary?: Summary;
+}
+interface ReviewInput<State, Summary = unknown> {
+  shot: number;
+  goal: string;
+  state: State;
+  verification: Verification;
+  traceSummary: Summary | undefined;
+  memory: ReviewMemoryEntry[];
+}
+type ProposeFn<State, Summary = unknown> = (input: ProposeInput<State>) => Promise<ProposeOutput<State, Summary>>;
+type VerifyFn<State> = (state: State) => Promise<Verification>;
+type ReviewFn<State, Summary = unknown> = (input: ReviewInput<State, Summary>) => Promise<Review>;
+interface ReviewMemoryStore {
+  load(): Promise<ReviewMemoryEntry[]>;
+  append(entry: ReviewMemoryEntry): Promise<void>;
+}
+interface ProposeReviewConfig<State, Summary = unknown> {
+  goal: string;
+  initialState: State;
+  propose: ProposeFn<State, Summary>;
+  verify: VerifyFn<State>;
+  review: ReviewFn<State, Summary>;
+  /** Hard shot cap. Default 10. */
+  maxShots?: number;
+  /** Wall-clock cap in ms. Default 10 min. */
+  maxWallMs?: number;
+  /**
+   * If the reviewer returns confidence ≤ floor on `confidenceFloorWindow`
+   * consecutive shots, terminate early. Default floor 0.3, window 2.
+   * Set window to 0 or floor to <0 to disable.
+   */
+  confidenceFloor?: number;
+  confidenceFloorWindow?: number;
+  /** Defaults to an in-memory store if omitted. */
+  memory?: ReviewMemoryStore;
+  /** If provided, emit a Run + per-shot spans. */
+  store?: TraceStore;
+  scenarioId?: string;
+  projectId?: string;
+  variantId?: string;
+  /**
+   * Used when the reviewer soft-fails on shot 1 (no prior instruction to
+   * fall back to). Default is a generic "inspect failures and fix".
+   */
+  fallbackInstruction?: string;
+}
+interface ProposeReviewShot<State, Summary = unknown> {
+  shot: number;
+  state: State;
+  verification: Verification;
+  traceSummary: Summary | undefined;
+  review: Review;
+  reviewAvailable: boolean;
+  reviewError?: string;
+  durationMs: number;
+}
+interface ProposeReviewReport<State, Summary = unknown> {
+  runId: string | null;
+  completed: boolean;
+  shots: ProposeReviewShot<State, Summary>[];
+  finalState: State;
+  finalVerification: Verification;
+  failureClass?: FailureClass;
+  wallMs: number;
+  score: number;
+}
+declare function inMemoryReviewStore(initial?: ReviewMemoryEntry[]): ReviewMemoryStore;
+declare function jsonlReviewStore(path: string): ReviewMemoryStore;
+declare function runProposeReview<State, Summary = unknown>(config: ProposeReviewConfig<State, Summary>): Promise<ProposeReviewReport<State, Summary>>;
+type LlmJsonCall = (req: {
+  system: string;
+  user: string;
+}) => Promise<unknown>;
+interface LlmReviewerConfig<State, Summary = unknown> {
+  callJson: LlmJsonCall;
+  renderState?: (state: State) => string;
+  renderTraceSummary?: (summary: Summary | undefined) => string;
+  /** Appended to the default system prompt. */
+  systemPromptAddendum?: string;
+}
+declare function createLlmReviewer<State, Summary = unknown>(cfg: LlmReviewerConfig<State, Summary>): ReviewFn<State, Summary>;
+interface TrialTrace {
+  /** Stable id for the trial — surfaces in the prompt for grounding. */
+  id: string;
+  /** Score the trial received on its primary metric. */
+  score: number;
+  /** Candidate inputs the agent was given (e.g., the fixture or scenario). */
+  inputName?: string;
+  /**
+   * Goldens / expectations this trial was tested against, with whether each
+   * was matched. The reflection prompt quotes the missed ones specifically.
+   */
+  expectations?: Array<{
+    id: string;
+    phrase: string;
+    matched: boolean;
+  }>;
+  /** Free-form text — what the agent actually emitted (e.g., findings, plan). */
+  emitted?: string;
+  /** The judge's free-form note on WHY this trial scored low — the failure
+   *  evidence the reflection targets. Should be a generalizable pattern (which
+   *  checks/lines/dimensions failed, and how), never case-specific ground
+   *  truth (that would teach memorization, not capability). */
+  failureNote?: string;
+  /** Optional structured metrics (recall, precision, cost, latency). */
+  metrics?: Record<string, number>;
+}
+interface ReflectionContext {
+  /** What is being mutated — appears in the system prompt for orientation. */
+  target: string;
+  /** Current variant's payload — JSON-serialised for the prompt. */
+  parentPayload: unknown;
+  /** Best-performing trials this generation. */
+  topTrials: TrialTrace[];
+  /** Worst-performing trials this generation — the missed-golden source. */
+  bottomTrials: TrialTrace[];
+  /** How many children the mutator should propose. */
+  childCount: number;
+  /** Optional: domain-specific mutation primitives the model can pick from. */
+  mutationPrimitives?: string[];
+}
+/**
+ * Build the LLM-ready reflection prompt. Output is plain text — pass it as
+ * the user message. The system message should be small and stable (e.g.
+ * "Output ONLY a JSON object matching the schema below.").
+ */
+declare function buildReflectionPrompt(ctx: ReflectionContext): string;
+interface ReflectionProposal {
+  label: string;
+  rationale: string;
+  payload: unknown;
+}
+/**
+ * Parse the model's JSON response back into proposals. Tolerates markdown
+ * fences and surrounding prose. Returns at most `maxProposals`.
+ */
+declare function parseReflectionResponse(raw: string, maxProposals?: number): ReflectionProposal[];
+/**
+ * Backing persistence for `EvalTraceStore`. The in-memory store is the default;
+ * the JSONL file store appends one validated `RunRecord` per line. Both keep an
+ * append order so `getBest` / `compareRuns` are reproducible.
+ */
+interface RunRecordBackend {
+  append(record: RunRecord): Promise<void>;
+  load(): Promise<RunRecord[]>;
+}
+/**
+ * JSONL-backed store at `path`, one `RunRecord` per line. Malformed lines fail
+ * loud on load (a corrupt corpus must not silently shrink the analysis set);
+ * pass `skipInvalid` only for forensics on a known-bad file.
+ */
+declare function jsonlRunRecordBackend(path: string, opts?: {
+  skipInvalid?: boolean;
+}): RunRecordBackend;
+interface ModelPreflight {
+  /** The model id as supplied by the caller. */
+  model: string;
+  /** Membership in the `{baseUrl}/models` served set. */
+  listed: boolean;
+  /**
+   * The router reached a provider for this model. `null` when `probe` was not
+   * requested. True on a 2xx, and also when the provider answered by
+   * exhausting its reasoning budget — that proves reachability while leaving
+   * identity unproven (see `budgetExhausted`).
+   */
+  served: boolean | null;
+  /** HTTP status of the probe. `null` when not probed. */
+  status: number | null;
+  /** Probe body's `error.message` when present, else `null`. */
+  detail: string | null;
+  /**
+   * The probe died on the token budget rather than on the model. Identity is
+   * unproven, not refuted: raise `probeMaxTokens` to resolve it.
+   */
+  budgetExhausted: boolean;
+  /**
+   * Identity of the model that answered the probe, compared against `model`.
+   * `null` when the model was not probed or the probe failed.
+   */
+  substitution: ServedModelCheck | null;
+}
+/** One check Agent Eval asks the caller's endpoint to perform. */
+type ModelEndpointCheck = {
+  readonly kind: 'list-models';
+} | {
+  readonly kind: 'probe';
+  readonly model: string;
+  /** Output-token budget the probe completion may bill. */
+  readonly maxOutputTokens: number;
+};
+/**
+ * Caller-owned request into the model endpoint. The caller binds the base URL
+ * and the credential and returns the raw `Response`; a `list-models` request
+ * answers with an OpenAI-compatible `{ data: [{ id }] }` body, and a `probe`
+ * request answers with one minimal chat completion for `model`.
+ */
+type ModelEndpointRequest = (check: ModelEndpointCheck) => Promise<Response>;
+interface PreflightModelsOptions {
+  /** Caller-owned endpoint request. Agent Eval issues no provider HTTP itself. */
+  request: ModelEndpointRequest;
+  /** Model ids to check. */
+  models: string[];
+  /** When true, additionally spend a small chat probe per model. Default false. */
+  probe?: boolean;
+  /**
+   * Output-token budget per probe. Default `PROBE_MAX_TOKENS`. Lowering it
+   * below the reasoning floor makes healthy reasoning models report
+   * `budgetExhausted` instead of proving their identity.
+   */
+  probeMaxTokens?: number;
+}
+interface PreflightOutcome {
+  succeeded: boolean;
+  value: ModelPreflight[] | null;
+  error: string | null;
+}
+/**
+ * Check that `models` are reachable on the router. Returns a typed outcome —
+ * a network failure yields `{ succeeded: false, error }`, never a throw and
+ * never a partial result silently reported as success. No retries, no
+ * fallbacks.
+ *
+ * The membership check (one GET) always runs. When `probe` is true, each model
+ * additionally gets a small chat probe so a model that is listed but
+ * unconfigured (a 401 `model_not_found` from the router) is caught.
+ */
+declare function preflightModels(opts: PreflightModelsOptions): Promise<PreflightOutcome>;
+/**
+ * ModelSeats — the program's model seating chart.
+ *
+ * One object names which model fills each role in an eval program: the worker
+ * under evaluation, the judge panel, the analyst, the reflection/driver model,
+ * and the verifier. Re-tiering an entire program (economy ↔ frontier) is one
+ * swapped object instead of a hunt through call sites.
+ *
+ * Wiring points — consumers thread seats; this module implements none of them
+ * (those files belong to other surfaces):
+ *  - `judges`     → `ensembleJudge({ models: seats.judges, … })` (src/judge-panel.ts)
+ *                   and the `JudgeConfig`s handed to `makeEvalTools({ judges })`
+ *                   (src/eval-tools.ts).
+ *  - `reflection` → the model configured by a custom `SurfaceProposer` or
+ *                   external optimization engine.
+ *  - `worker`     → the dispatch model the agent itself calls — the model an
+ *                   `AgentProfile` declares.
+ *  - `analyst`    → the LLM behind `analyzeRuns` / analyst-registry kinds.
+ *  - `verifier`   → completion-verifier / objective-checker model.
+ *  - campaign cells thread `judges` + driver models the same way; that wiring
+ *    lands with the campaign surface, not here.
+ *
+ * `resolveSeat` is the only read path: an unset seat with no explicit fallback
+ * throws — a model id is a budget decision, never a silent default.
+ */
+interface ModelSeats {
+  /** The model under evaluation — what the agent itself dispatches with. */
+  worker?: string;
+  /** Judge-panel model ids — thread into `ensembleJudge({ models })`. */
+  judges?: string[];
+  /** Analyst model — `analyzeRuns` / analyst-registry LLM calls. */
+  analyst?: string;
+  /** Reflection or candidate-generation model. */
+  reflection?: string;
+  /** Verifier model — completion/objective checking. */
+  verifier?: string;
+}
+type SeatName = keyof ModelSeats;
+/**
+ * Tier presets — plain data, swap or spread freely.
+ *
+ * A preset names REQUESTED ids, and a requested id is NOT a guarantee of
+ * family, of provider, or of liveness. A routing gateway can accept any id
+ * below and answer from a different model on HTTP 200, with only the response
+ * body's `model` field betraying the swap. The served assertion is the
+ * guarantee: gate a run on `assertModelsServed({ probe: true })` and assert
+ * `assertServedModel` per call. `assertCrossFamily` over these ids proves the
+ * configuration is diverse; only `assertCrossFamilyServed` over the ids that
+ * ANSWERED proves the run was.
+ *
+ * `economy` names ids a live router probe answered from the provider their
+ * name implies, so the judge trio spanned three provider families (deepseek /
+ * zhipu / google) as configured and, at that probe, as served. A preset is
+ * only as good as its last probe: ids go dead and start resolving elsewhere
+ * without notice, so re-probe rather than trusting this list.
+ *
+ * `frontier` is deliberately EMPTY: entitled frontier ids vary per router
+ * account, and a hardcoded claude/gpt-5 id 401s on keys that lack it. Supply
+ * your own: `{ ...seatPresets.frontier, worker: '<your-frontier-id>', … }` —
+ * `resolveSeat` throws on every seat you haven't filled.
+ */
+declare const seatPresets: Record<'economy' | 'frontier', ModelSeats>;
+/**
+ * Read one seat. Blank strings and empty arrays count as unset (env-var
+ * plumbing produces them); malformed values (non-string seat, non-array or
+ * blank-entry `judges`) throw `ValidationError`. When the seat is unset, an
+ * explicit `fallback` is returned (`[fallback]` for `judges` — a one-model
+ * panel); without one, `SeatUnsetError`.
+ */
+declare function resolveSeat(seats: ModelSeats, seat: 'judges', fallback?: string): string[];
+declare function resolveSeat(seats: ModelSeats, seat: Exclude<SeatName, 'judges'>, fallback?: string): string;
+declare function resolveSeat(seats: ModelSeats, seat: SeatName, fallback?: string): string | string[];
+/**
+ * Versioned prompt registry.
+ *
+ * Every prompt used in an eval run is registered with an explicit version.
+ * Reports include the content hash so A/B compares are rigorous: if the
+ * hash changes between two reports, the prompt actually changed; if it
+ * matches, the variance is elsewhere.
+ *
+ * Hash is SHA-256(content), truncated to 12 hex chars for readability.
+ * Uses the Web Crypto API (works in Workers, Node 22+, browsers).
+ */
+interface PromptHandle {
+  /** Stable human-readable id, e.g. 'browser.system' */
+  id: string;
+  /** Caller-chosen version string, e.g. 'v3' or '2026-04-20' */
+  version: string;
+  /** SHA-256 of content, 12-hex-char prefix */
+  hash: string;
+  /** Full prompt body */
+  content: string;
+}
+declare class PromptRegistry {
+  private readonly entries;
+  /**
+   * Register a prompt. Re-registering the same id+version with DIFFERENT
+   * content throws — versions are immutable. Re-registering with the SAME
+   * content is a no-op (idempotent).
+   */
+  register(id: string, version: string, content: string): Promise<PromptHandle>;
+  /** Look up a registered prompt. Throws if unknown — no implicit defaults. */
+  get(id: string, version: string): PromptHandle;
+  /** Return all versions of an id, newest-first (lex-descending on version). */
+  listVersions(id: string): PromptHandle[];
+  /** Snapshot the whole registry — useful for including in reports. */
+  list(): PromptHandle[];
+  /** Verify a hash against registered content. Returns null if not found. */
+  verifyHash(id: string, version: string, expectedHash: string): boolean | null;
+}
+/** SHA-256(content) → first 12 hex chars. Stable across runtimes. */
+declare function hashContent(content: string): Promise<string>;
+/**
+ * Reference replay — score an agent against withheld historical outcomes.
+ *
+ * This is the generic version of the public-audit replay pattern:
+ * run a candidate system on an old task, keep the reference answers hidden
+ * until after execution, then score recall/precision and gate promotion
+ * across train/dev/test/holdout splits.
+ */
+type ReferenceReplaySplit = 'train' | 'dev' | 'test' | 'holdout';
+interface ReferenceReplayItem {
+  id: string;
+  title: string;
+  description?: string;
+  severity?: string;
+  tags?: string[];
+  weight?: number;
+}
+interface ReferenceReplayCandidate {
+  id: string;
+  title: string;
+  description?: string;
+  severity?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface ReferenceReplayMatch {
+  scenarioId: string;
+  referenceId: string;
+  candidateId: string | null;
+  score: number;
+  matched: boolean;
+  weight: number;
+  reason: string;
+}
+interface ReferenceReplayScenarioScore {
+  scenarioId: string;
+  split: ReferenceReplaySplit;
+  matched: number;
+  total: number;
+  falsePositives: number;
+  matchedWeight: number;
+  totalWeight: number;
+  precision: number;
+  recall: number;
+  f1: number;
+  matches: ReferenceReplayMatch[];
+}
+interface ReferenceReplayAggregate {
+  matched: number;
+  total: number;
+  falsePositives: number;
+  matchedWeight: number;
+  totalWeight: number;
+  precision: number;
+  recall: number;
+  f1: number;
+  weightedRecall: number;
+}
+interface ReferenceReplayScore {
+  scenarios: ReferenceReplayScenarioScore[];
+  aggregate: ReferenceReplayAggregate;
+  bySplit: Partial<Record<ReferenceReplaySplit, ReferenceReplayAggregate>>;
+}
+interface ReferenceReplayCaseRun<Input = unknown> {
+  caseId: string;
+  split: ReferenceReplaySplit;
+  input: Input;
+  metadata?: Record<string, unknown>;
+  references: ReferenceReplayItem[];
+  candidates: ReferenceReplayCandidate[];
+  score: ReferenceReplayScenarioScore;
+  durationMs: number;
+  error?: string;
+}
+interface ReferenceReplayRun<Input = unknown> {
+  id: string;
+  variantId?: string;
+  startedAt: number;
+  completedAt: number;
+  durationMs: number;
+  cases: ReferenceReplayCaseRun<Input>[];
+  score: ReferenceReplayScore;
+  metadata?: Record<string, unknown>;
+}
+interface SteeringRolePrompt {
+  system?: string;
+  append?: string;
+}
+interface SteeringBundle {
+  id: string;
+  coderPrompt?: string;
+  continuePrompt?: string;
+  reviewerPrompts?: Record<string, string>;
+  skills?: string[];
+  rolePrompts?: Record<string, SteeringRolePrompt>;
+  metadata?: Record<string, unknown>;
+}
+interface RunScore {
+  success: number;
+  goalProgress: number;
+  repoGroundedness: number;
+  driftPenalty: number;
+  toolUseQuality: number;
+  patchQuality: number;
+  testReality: number;
+  finalGate: number;
+  reviewerBlockers: number;
+  costUsd: number;
+  wallSeconds: number;
+  notes?: string[];
+}
+type RunScoreWeights = Omit<RunScore, 'notes'>;
+declare function aggregateRunScore(score: RunScore, weights?: Partial<RunScoreWeights>): number;
+declare function clamp01(value: number): number;
+type SteeringOptimizerBackend = 'pairwise';
+interface SteeringOptimizationRow {
+  variantId: string;
+  scenarioId: string;
+  bundle: SteeringBundle;
+  score: RunScore;
+  metadata?: Record<string, unknown>;
+}
+interface SteeringOptimizationSelector {
+  backend: SteeringOptimizerBackend;
+  signature?: string;
+  labels?: string[];
+  rationale?: string;
+}
+interface SteeringOptimizationResult {
+  backend: SteeringOptimizerBackend;
+  recommendedVariantId: string;
+  rationale: string;
+  rankings: Array<{
+    variantId: string;
+    mean: number;
+    runs: number;
+  }>;
+  selector?: SteeringOptimizationSelector;
+  skipped?: boolean;
+}
+interface SteeringOptimizerConfig {
+  weights?: Partial<RunScoreWeights>;
+}
+/**
+ * Rank already-evaluated steering variants.
+ *
+ * Model-backed candidate generation belongs to the official GEPA campaign
+ * integration. This class only performs the deterministic selection it owns.
+ */
+declare class PairwiseSteeringOptimizer {
+  optimize(rows: SteeringOptimizationRow[], config?: SteeringOptimizerConfig): SteeringOptimizationResult;
+}
+type CounterfactualMutation = {
+  kind: 'swap-model';
+  at: number;
+  newModel: string;
+} | {
+  kind: 'swap-tool-result';
+  at: number;
+  newResult: unknown;
+} | {
+  kind: 'truncate-after';
+  at: number;
+} | {
+  kind: 'inject-system-message';
+  at: number;
+  content: string;
+} | {
+  kind: 'custom';
+  at: number;
+  describe: string;
+  apply: (step: TrajectoryStep) => TrajectoryStep;
+};
+interface CounterfactualContext {
+  originalRunId: string;
+  originalTrajectory: Trajectory;
+  /** Steps up to (but not including) the mutation point — the prefix the
+   *  replayed agent inherits as its prior conversation/tool history. */
+  prefix: TrajectoryStep[];
+  mutation: CounterfactualMutation;
+  /** Pre-applied mutation on the step at `mutation.at`. Consumers use this
+   *  as the FIRST step the replayed agent emits (they decide whether to
+   *  re-emit it or continue from there). */
+  mutatedStep: TrajectoryStep;
+}
+interface CounterfactualResult {
+  counterfactualRunId: string;
+  originalRunId: string;
+  mutation: CounterfactualMutation;
+  /** Structured delta summary — caller can extend via scoring. */
+  delta: {
+    originalOutcomeScore: number | null;
+    counterfactualOutcomeScore: number | null;
+    deltaScore: number | null;
+  };
+}
+interface CounterfactualRunner {
+  /**
+   * Execute the agent from `ctx.prefix` with the mutation applied.
+   * MUST emit spans into the provided emitter so they become part of
+   * the counterfactual run. MUST call emitter.endRun() with a verdict.
+   */
+  executeFrom: (ctx: CounterfactualContext, emitter: TraceEmitter) => Promise<void>;
+}
+/** One commit's measurement of one (scenario, profile) cell. */
+interface ScorecardEntry {
+  commitSha: string;
+  /** ISO timestamp the entry was recorded. */
+  timestamp: string;
+  /** Per-seed (or per-rep) scores for this cell at this commit. */
+  scores: number[];
+  /** Median of `scores` — the cell's headline score for the commit. */
+  composite: number;
+  /** Per-dimension means, when the runs carried a judge breakdown. */
+  perDimension?: Record<string, number>;
+  /** RunRecord ids folded into this entry — provenance. */
+  runIds: string[];
+}
+/** A (scenario, profile) cell and its commit-ordered score timeline. */
+interface ScorecardCell {
+  scenarioId: string;
+  profileHash: string;
+  /** Model id — denormalised from the profile for readable filtering. */
+  model: string;
+  timeline: ScorecardEntry[];
+}
+/** The folded scorecard: every cell, plus the profile definitions by hash. */
+interface Scorecard {
+  cells: ScorecardCell[];
+  /** Profile definitions seen — keeps the scorecard self-describing. */
+  profiles: Record<string, AgentProfile>;
+}
+/** One append-only log line — a single cell's entry for a single commit. */
+interface ScorecardLogLine {
+  scenarioId: string;
+  profileHash: string;
+  model: string;
+  profile: AgentProfile;
+  entry: ScorecardEntry;
+}
+interface RecordRunsOptions {
+  /** The profile that produced these runs — keys the cell. */
+  profile: AgentProfile;
+  commitSha: string;
+  /** Defaults to `new Date().toISOString()`. */
+  timestamp?: string;
+}
+/**
+ * Fold a benchmark's `RunRecord[]` into per-cell scorecard log lines — one
+ * line per scenario the runs cover. All runs are attributed to the single
+ * `profile` in `opts` (the harness ran them under it); the cell key is
+ * `(scenarioId, agentProfileHash(profile))`.
+ */
+declare function recordRuns(runs: RunRecord[], opts: RecordRunsOptions): ScorecardLogLine[];
+/** Record runs and append them to the log in one call. Returns the lines. */
+declare function recordRunsToScorecard(logPath: string, runs: RunRecord[], opts: RecordRunsOptions): ScorecardLogLine[];
+/**
+ * Fold the JSONL log into a queryable `Scorecard`. A missing file yields an
+ * empty scorecard; a malformed line is skipped — a corrupt append never
+ * breaks the read. Each cell's timeline is sorted chronologically.
+ */
+declare function loadScorecard(logPath: string): Scorecard;
+type CellVerdict = 'improved' | 'regressed' | 'flat' | 'new';
+interface ScorecardCellDiff {
+  scenarioId: string;
+  profileHash: string;
+  model: string;
+  verdict: CellVerdict;
+  /** Composite of the latest entry. */
+  current: number;
+  /** Composite of the comparison entry — `null` when `verdict === 'new'`. */
+  baseline: number | null;
+  /** `current − baseline` — `null` when new. */
+  delta: number | null;
+  /** Cohen's d of current vs baseline samples — `null` when new or n < 2. */
+  cohensD: number | null;
+  /** Welch's t-test p-value — `null` when new or n < 2. */
+  pValue: number | null;
+  currentCommit: string;
+  baselineCommit: string | null;
+}
+interface ScorecardDiff {
+  cells: ScorecardCellDiff[];
+  summary: {
+    improved: number;
+    regressed: number;
+    flat: number;
+    new: number;
+  };
+}
+interface DiffScorecardOptions {
+  /** Compare each cell against this commit instead of its immediate predecessor. */
+  baselineCommit?: string;
+  /** |Cohen's d| at/above which a move counts as real. Default 0.5. */
+  minEffect?: number;
+  /** p-value at/below which a move is significant. Default 0.05. */
+  maxP?: number;
+  /**
+   * |delta| at/above which a move counts when statistics are unavailable
+   * (a cell with fewer than 2 samples on either side). Default 0.05.
+   */
+  minDelta?: number;
+}
+/**
+ * Compare the latest entry of every cell against its predecessor (or against
+ * `baselineCommit`) and classify the move. A move is `improved`/`regressed`
+ * only when it clears both the effect-size and significance gates; otherwise
+ * `flat`. Cells with no prior entry are `new`.
+ */
+declare function diffScorecard(scorecard: Scorecard, opts?: DiffScorecardOptions): ScorecardDiff;
+/**
+ * Render a scorecard diff as a human-readable report — the block a feature
+ * PR prints. Regressions are listed first; flat cells are summarised, not
+ * enumerated.
+ */
+declare function formatScorecardDiff(diff: ScorecardDiff): string;
+/**
+ * Minimal structural span the checker reads. The eval-side `Span`
+ * (trace/schema) and the output of {@link contractSpansFromOtlp} satisfy it.
+ */
+interface ContractSpan {
+  spanId?: string;
+  parentSpanId?: string | null;
+  name?: string;
+  /** Eval kinds (`tool`, `llm`, ...) or contract kinds (`TOOL`, `LLM`, ...). */
+  kind?: string;
+  startedAt?: number;
+  endedAt?: number;
+  status?: string;
+  error?: string;
+  /** Typed field on eval-side ToolSpans; OTLP flattenings drop it (see
+   *  {@link contractSpanToolName}). */
+  toolName?: string;
+  /** Typed field on eval-side LlmSpans. */
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  /** Typed field on eval-side ToolSpans. */
+  args?: unknown;
+  /** False when the source observed the call but did not capture its arguments. */
+  argsCaptured?: boolean;
+  attributes?: Record<string, unknown>;
+}
+/**
+ * The run a `run` rule reads. The eval-side `Run` satisfies it. When no run is
+ * passed, the checker derives it from the trace's single root span; a trace
+ * with no unique root leaves the run unknown and every `run` rule fails.
+ */
+interface ContractRun {
+  status?: string;
+  startedAt?: number;
+  endedAt?: number;
+}
+/** JSON-safe RegExp form — what the builder normalizes RegExp matchers to. */
+interface SerializedRegex {
+  $regex: string;
+  flags: string;
+}
+/** Matches when the value equals one of the listed strings. */
+interface OneOfMatcher {
+  oneOf: string[];
+}
+type TextMatcher = string | RegExp | SerializedRegex | OneOfMatcher;
+/**
+ * Proposition over one span. All specified fields must match (AND); `not`
+ * must NOT match. At least one field is required — an empty predicate would
+ * match every span and is rejected.
+ *
+ * `kind` compares against the span's contract kind (`TOOL`, `LLM`, `AGENT`,
+ * ...), resolved by agent-trace-contract's classifier, so eval kinds
+ * (`tool`, `llm`) and OTLP spans that declare no kind are read the same way.
+ *
+ * `tool` resolves through {@link contractSpanToolName}; `model` through the
+ * typed `model` field and the gen_ai model attributes.
+ *
+ * `attr` values match by strict equality, or regex-test when the value is a
+ * RegExp/SerializedRegex and the attribute is a string. Structured attribute
+ * values need `custom`, or an `argument` rule for tool arguments.
+ */
+interface SpanPredicate {
+  name?: TextMatcher;
+  tool?: TextMatcher;
+  model?: TextMatcher;
+  kind?: SpanKind;
+  attr?: Record<string, unknown>;
+  not?: SpanPredicate;
+  custom?: (span: ContractSpan) => boolean;
+  /** Stamped by the builder when `custom` is present. Survives JSON while
+   *  the function does not, so evaluation of a deserialized contract throws
+   *  instead of silently dropping the check. */
+  requiresCustom?: true;
+}
+declare const ORDER_MODES: readonly ["start-order", "finish-before-start", "all-occurrences"];
+type OrderMode = (typeof ORDER_MODES)[number];
+declare const ARGUMENT_OCCURRENCES: readonly ["first", "last", "any", "all"];
+type ArgumentOccurrence = (typeof ARGUMENT_OCCURRENCES)[number];
+declare const ARGUMENT_TYPES: readonly ["string", "number", "boolean", "object", "array", "null"];
+type ArgumentType = (typeof ARGUMENT_TYPES)[number];
+type ArgumentCheck = {
+  op: 'exists';
+} | {
+  op: 'equals';
+  value: unknown;
+} | {
+  op: 'oneOf';
+  values: unknown[];
+} | {
+  op: 'type';
+  type: ArgumentType;
+};
+/** A tool whose calls change state outside the run. */
+interface RetryWrite {
+  tool: string;
+  /** RFC 6901 JSON Pointer to the idempotency key in the call's arguments.
+   *  Without it, a repeated call of this tool always fails. */
+  idempotencyKey?: string;
+}
+interface RunChecks {
+  /** The run's status is `completed` and its end time is recorded. A failed
+   *  or aborted run fails this check. */
+  requireCompleted?: boolean;
+  /** The run's status must be one of these. */
+  allowedStatuses?: RunStatus[];
+  /** End minus start, in milliseconds. An unknown duration fails. */
+  maxDurationMs?: number;
+}
+type ContractRule = {
+  kind: 'always' | 'never' | 'eventually';
+  label: string;
+  p: SpanPredicate;
+} | {
+  kind: 'precedes';
+  label: string;
+  a: SpanPredicate;
+  b: SpanPredicate;
+  order?: OrderMode;
+} | {
+  kind: 'neverUnless';
+  label: string;
+  p: SpanPredicate;
+  prior: SpanPredicate;
+  order?: OrderMode;
+} | {
+  kind: 'atMost';
+  label: string;
+  p: SpanPredicate;
+  max: number;
+} | {
+  kind: 'tokensAtMost';
+  label: string;
+  p: SpanPredicate;
+  max: number;
+} | ({
+  kind: 'run';
+  label: string;
+} & RunChecks) | {
+  kind: 'argument';
+  label: string;
+  p: SpanPredicate;
+  /** RFC 6901 JSON Pointer into the call's arguments; `''` is the whole value. */
+  pointer: string;
+  check: ArgumentCheck;
+  /** Which matching calls must satisfy the check. Default `all`. */
+  occurrence?: ArgumentOccurrence;
+} | {
+  /**
+   * The tools the harness offered the model (the OTel GenAI
+   * `gen_ai.tool.definitions` attribute) are recorded, every tool call is
+   * one of them, and, when `declared` is set, every offered tool is
+   * declared. A trace that records no offered tools fails: what the
+   * harness enforced is unknown.
+   */
+  kind: 'toolsOffered';
+  label: string;
+  declared?: string[];
+} | {
+  /**
+   * A tool called again with the same arguments repeats its side effect.
+   * A repeated `reads` call passes; a repeated `writes` call passes only
+   * when every call carries the same idempotency key; a repeated call of
+   * any other tool fails, because its side effect is unknown.
+   */
+  kind: 'retrySafe';
+  label: string;
+  reads?: string[];
+  writes?: RetryWrite[];
+};
+/** One legitimate alternate path. The contract passes only when the base
+ *  rules pass and at least one alternative passes completely. */
+interface ContractAlternative {
+  id: string;
+  rules: ContractRule[];
+}
+/** Serializable plain object — `traceContract(name)....build()` output. */
+interface TraceContract {
+  name: string;
+  /** What the contract protects, for reports and `explainTraceContract`. */
+  description?: string;
+  /** Evaluate only the span matching `root` and its descendants. Exactly one
+   *  span must match; zero or several make every rule an error. */
+  scope?: {
+    root: SpanPredicate;
+  };
+  rules: ContractRule[];
+  alternatives?: ContractAlternative[];
+}
+type ContractStatus = 'pass' | 'fail' | 'error';
+interface ContractViolation {
+  rule: string;
+  spanId?: string;
+  detail: string;
+}
+/** What happened to one rule. `error` means it could not be evaluated. */
+interface ContractRuleExecution {
+  rule: string;
+  /** Set for rules inside `alternatives`. */
+  alternative?: string;
+  status: ContractStatus;
+  violations: number;
+  error?: string;
+}
+interface ContractVerdict extends DefaultVerdict {
+  /** Contract name — keys this verdict in multi-contract reports. */
+  contract: string;
+  status: ContractStatus;
+  /** `status === 'pass'`. */
+  valid: boolean;
+  /** Fraction of rules that passed, in [0, 1]. An errored rule is not a pass. */
+  score: number;
+  /** 0|1 per evaluated base rule, keyed by label, plus `anyOf` when the
+   *  contract has alternatives. Errored rules are absent, never 0. */
+  scores: Record<string, number>;
+  violations: ContractViolation[];
+  ruleExecutions: ContractRuleExecution[];
+  /** Why rules errored, one line per errored rule or scope failure. */
+  errors: string[];
+}
+interface ContractCheckResult {
+  verdicts: ContractVerdict[];
+  /** `error` if any verdict errored, else `fail` if any failed, else `pass`. */
+  status: ContractStatus;
+  allValid: boolean;
+}
+interface EvaluateTraceContractOptions {
+  /** The run `run` rules read. Ignored under `scope`, where the scope root is the run. */
+  run?: ContractRun;
+}
+interface OrderOptions {
+  order?: OrderMode;
+}
+interface ArgumentRuleOptions {
+  pointer: string;
+  check: ArgumentCheck;
+  occurrence?: ArgumentOccurrence;
+}
+declare class TraceContractBuilder {
+  private readonly name;
+  private readonly rules;
+  private readonly alternativeList;
+  private scopeRoot;
+  constructor(name: string);
+  /** Every span in the trace must satisfy `p`. */
+  always(p: SpanPredicate, label?: string): this;
+  /** No span in the trace may satisfy `p`. */
+  never(p: SpanPredicate, label?: string): this;
+  /** At least one span in the trace must satisfy `p`. */
+  eventually(p: SpanPredicate, label?: string): this;
+  /** Both `a` and `b` must occur, with `a` first under `options.order`
+   *  (default `start-order`). For "every `b` needs an earlier `a`, and a run
+   *  without `b` passes", use {@link neverUnless}. */
+  precedes(a: SpanPredicate, b: SpanPredicate, label?: string, options?: OrderOptions): this;
+  /** Every `p`-match needs an earlier `prior`-match; a run without `p` passes. */
+  neverUnless(p: SpanPredicate, prior: SpanPredicate, label?: string, options?: OrderOptions): this;
+  /** At most `max` spans may satisfy `p`. */
+  atMost(p: SpanPredicate, max: number, label?: string): this;
+  /** Spans satisfying `p` may use at most `max` input+output tokens in total. */
+  tokensAtMost(p: SpanPredicate, max: number, label?: string): this;
+  /** Terminal status and duration of the run. */
+  run(checks: RunChecks, label?: string): this;
+  /** A JSON Pointer check on the arguments of calls matching `p`. */
+  argument(p: SpanPredicate, options: ArgumentRuleOptions, label?: string): this;
+  /** The trace records the tools offered to the model, every call is one of
+   *  them, and, with `declared`, every offered tool is declared. */
+  toolsOffered(declared?: string[], label?: string): this;
+  /** No call repeats a side effect that is not proven safe to repeat. */
+  retrySafe(options: {
+    reads?: string[];
+    writes?: RetryWrite[];
+  }, label?: string): this;
+  /** Evaluate only the subtree rooted at the one span matching `root`. */
+  scope(root: SpanPredicate): this;
+  /** A named alternate path; at least one alternative must pass completely. */
+  alternative(id: string, define: (branch: TraceContractBuilder) => TraceContractBuilder): this;
+  build(): TraceContract;
+  private where;
+  private add;
+}
+declare function traceContract(name: string): TraceContractBuilder;
+/**
+ * Evaluate one contract over a span sequence. Pure and synchronous — works on
+ * `Span[]` from a TraceStore, `contractSpansFromOtlp` output, or any array
+ * satisfying `ContractSpan`. Throws
+ * `ValidationError` for a malformed contract; a rule that cannot be evaluated
+ * is reported as `error` in the verdict instead.
+ */
+declare function evaluateTraceContract(contract: TraceContract, spans: readonly ContractSpan[], options?: EvaluateTraceContractOptions): ContractVerdict;
+/**
+ * Evaluate many contracts over one span sequence. Throws on an empty
+ * contract list — `allValid: true` over zero contracts is a silent pass.
+ */
+declare function checkTraceContracts(spans: readonly ContractSpan[], contracts: readonly TraceContract[], options?: EvaluateTraceContractOptions): ContractCheckResult;
+/** Plain-language statement of everything a contract checks, one rule per line. */
+declare function explainTraceContract(contract: TraceContract): string;
+interface ToolArgumentSpec {
+  tool: string;
+  /** RFC 6901 JSON Pointer into the call's arguments; `''` is the whole value. */
+  pointer: string;
+  /** Which calls must satisfy the check. Default `all`. */
+  occurrence?: ArgumentOccurrence;
+  /** Exactly one of `exists`, `equals`, `oneOf`, `type`. */
+  exists?: true;
+  equals?: unknown;
+  oneOf?: unknown[];
+  type?: ArgumentType;
+}
+interface ToolsSpec {
+  /** Each must be called at least once. */
+  required?: string[];
+  /** None may be called. */
+  forbidden?: string[];
+  /** Every tool call must name one of these; a call without a name fails. */
+  allowed?: string[];
+  /** Ceiling on tool calls of any name. */
+  maxCalls?: number;
+  /** Ceiling per tool name. */
+  maxCallsPerTool?: Record<string, number>;
+  /** Each tool is called, and each comes before the next under `orderMode`. */
+  requiredOrder?: string[];
+  /** Default `start-order`. */
+  orderMode?: OrderMode;
+  arguments?: ToolArgumentSpec[];
+  /** The trace records the tools the harness offered the model
+   *  (`gen_ai.tool.definitions`), every call is one of them, and, with
+   *  `allowed`, every offered tool is allowed. */
+  enforced?: true;
+}
+interface RetriesSpec {
+  /** Tools that change nothing outside the run: repeating a call is safe. */
+  reads?: string[];
+  /** Tools that change state outside the run: a repeated call must carry one
+   *  idempotency key. Any other tool called twice with the same arguments fails. */
+  writes?: RetryWrite[];
+}
+interface LlmSpec {
+  maxCalls?: number;
+  /** Input plus output tokens across LLM calls; an unrecorded count fails. */
+  maxTotalTokens?: number;
+  /** Every LLM call must name one of these models; a call without one fails. */
+  allowedModels?: string[];
+}
+/** The checks one path carries: the base contract or one alternative. */
+interface PathSpec {
+  run?: RunChecks;
+  tools?: ToolsSpec;
+  llm?: LlmSpec;
+  retries?: RetriesSpec;
+  /** Low-level rules in their serialized form. */
+  rules?: ContractRule[];
+}
+interface AlternativeSpec extends PathSpec {
+  id: string;
+}
+interface TraceContractSpec extends PathSpec {
+  name: string;
+  description?: string;
+  /** Check only the one span matching `root` and its descendants: one
+   *  sub-agent (`{ "kind": "AGENT", "name": "researcher" }`) or one search
+   *  node (`{ "attr": { "agent.branch.id": "n7" } }`). */
+  scope?: {
+    root: SpanPredicate;
+  };
+  /** At least one alternative must pass completely, as well as the base checks. */
+  alternatives?: {
+    anyOf: AlternativeSpec[];
+  };
+}
+/**
+ * Parse and compile a declarative contract. Throws `ValidationError` naming
+ * the path of the first problem: an unknown key, a wrong type, an unknown
+ * status, or a contract that checks nothing.
+ */
+declare function compileTraceContractSpec(input: unknown): TraceContract;
+interface ContractLintFinding {
+  /** `error`: the contract can never pass, or contradicts itself.
+   *  `warning`: the contract works but likely does not say what was meant. */
+  level: 'error' | 'warning';
+  code: string;
+  path: string;
+  message: string;
+}
+/**
+ * Find contradictions and likely mistakes in a declarative contract. Parses
+ * strictly first, so a malformed spec throws instead of linting.
+ */
+declare function lintTraceContractSpec(input: unknown): ContractLintFinding[];
+interface ActionExecutionPolicy {
+  allowedTypes?: string[];
+  blockedTypes?: string[];
+  alwaysRequireApprovalTypes?: string[];
+  autoApproveTypes?: string[];
+  requireApprovalForExternalSideEffects?: boolean;
+  requireApprovalAboveCostUsd?: number;
+  maxActionCostUsd?: number;
+  remainingBudgetUsd?: number;
+  expectedOutcomeRequired?: boolean;
+  killCriteriaRequired?: boolean;
+}
+interface ActionPolicyDecision {
+  allowed: boolean;
+  blocked: boolean;
+  requiresApproval: boolean;
+  reasons: string[];
+  label?: FeedbackLabel;
+}
+declare function evaluateActionPolicy(action: ProposedSideEffect, policy?: ActionExecutionPolicy, options?: {
+  createdAt?: string;
+}): ActionPolicyDecision;
+interface CanaryLeak {
+  scenarioId: string;
+  canary: string;
+  runId?: string;
+  evidence: string;
+}
+declare function checkCanaries(output: string, scenarios: DatasetScenario[]): CanaryLeak[];
+type DeployFamily = 'frontend-static' | 'nextjs' | 'remix' | 'fullstack-ts';
+interface DeployRunResult {
+  ok: boolean;
+  /** Stdout/stderr tail surfaced as evidence. Bounded in caller. */
+  output?: string;
+  /** Wall-clock duration of the build command. */
+  durationMs?: number;
+  /** Path to artifact directory the runner expects (dist/, .next/, build/, etc). */
+  artifactDir?: string;
+  /** True iff artifactDir contains the family's expected entry point. */
+  artifactValid?: boolean;
+}
+interface DeployRunner {
+  /** Run the production build. The runner owns command + cwd. */
+  run(): Promise<DeployRunResult>;
+}
+interface DeployGateLayerInput {
+  /** Build the runner per call. */
+  runner: () => DeployRunner | Promise<DeployRunner>;
+  /** Family hint — for logging, surfaced in diagnostics. */
+  family?: DeployFamily;
+  /** Layer name. Default `deploy`. */
+  name?: string;
+  /** Layer dependencies — default `['build']`. */
+  dependsOn?: string[];
+  /** Weight in blendedScore. Default 1. */
+  weight?: number;
+  /** Cap (ms). Default 120s — prod builds are slower than dev. */
+  capMs?: number;
+  /** When true, treat artifactValid=false as a fail (default true). */
+  requireArtifact?: boolean;
+}
+/**
+ * Build a deploy gate layer that runs the production build and verifies
+ * the artifact. Pass: ok && artifactValid. Score: 1.0 (pass) or 0 (fail).
+ *
+ * For families where artifact-validation isn't applicable (e.g. a
+ * server-rendered build that prints a manifest), set `requireArtifact:
+ * false` and rely on the runner's own ok signal.
+ */
+declare function deployGateLayer<Env = unknown>(input: DeployGateLayerInput): Layer<Env>;
+interface ViteDeployRunnerInput {
+  /** Workdir to build. The runner cd's here. */
+  workdir: string;
+  /**
+   * Function to run a shell command in `workdir`. Same shape as
+   * agent-eval's CommandRunner.run for compositional reuse.
+   */
+  exec: (cmd: string, opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+  }) => Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  }>;
+  /**
+   * Function to test whether a path exists in the workdir. Inject
+   * `(p) => existsSync(join(workdir, p))` for host runs.
+   */
+  exists: (relativePath: string) => boolean | Promise<boolean>;
+  /** Build command. Default `npm run build`. */
+  buildCommand?: string;
+  /** Artifact directory to validate. Default `dist`. */
+  artifactDir?: string;
+  /** Entry-point file under artifactDir. Default `index.html`. */
+  artifactEntry?: string;
+  /** Per-build cap (ms). Default 90s. */
+  timeoutMs?: number;
+}
+/**
+ * Canonical runner for `frontend-static` family — runs the build script,
+ * validates `<artifactDir>/<artifactEntry>` exists. Use as the `runner:`
+ * factory for {@link deployGateLayer}.
+ */
+declare function viteDeployRunner(input: ViteDeployRunnerInput): DeployRunner;
+interface WranglerDeployRunnerInput {
+  workdir: string;
+  exec: (cmd: string, opts?: {
+    cwd?: string;
+    timeoutMs?: number;
+  }) => Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  }>;
+  exists: (relativePath: string) => boolean | Promise<boolean>;
+  /** Build command. Default `npm run build`. */
+  buildCommand?: string;
+  /** Wrangler dry-run command. Default `npx wrangler deploy --dry-run --outdir dist`. */
+  dryRunCommand?: string;
+  /** Per-step cap (ms). Default 120s. */
+  timeoutMs?: number;
+}
+/**
+ * Canonical runner for the `fullstack-ts` family on Cloudflare Workers
+ * (Remix / React Router v7 / Hono on Workers). Detects wrangler.toml or
+ * wrangler.jsonc in the workdir, builds, then `wrangler deploy --dry-run`
+ * to catch missing bindings, syntax errors in wrangler config, and
+ * import-time crashes that don't surface in `tsc`.
+ *
+ * No wrangler config = skip with "no wrangler" evidence (not a failure
+ * — the gate caller decides whether to require deploy validation).
+ */
+declare function wranglerDeployRunner(input: WranglerDeployRunnerInput): DeployRunner;
+/**
+ * Hidden-criteria grading firewall — grade an agent on criteria it never saw.
+ *
+ * A trustworthy benchmark splits every scenario's data by WHERE each field is
+ * allowed to flow, then proves the held-out / judge-only fields never reach the
+ * agent during the run. The coding bench expresses this with four destinations
+ * (prompt / develop-against / held-out suite / rubric); this module lifts the
+ * domain-FREE core out of it so research, legal, tax, content — any domain —
+ * can declare the same routing and get the same firewall enforcement and the
+ * same held-out-weighted composite, plugging in its OWN grader.
+ *
+ * Two reusable pieces, both domain-agnostic:
+ *
+ *   1. FIELD ROUTING BY DESTINATION. A scenario declares each field's
+ *      `FieldDestination`; `assertNoHiddenLeak` is a pure checker that throws if
+ *      a grading-only or judge-only field's value appears in what reaches the
+ *      agent. The domain decides which fields exist and where they go — the
+ *      substrate only enforces "hidden stays hidden".
+ *
+ *   2. HIDDEN-CRITERIA GRADING. The domain supplies its own grader
+ *      `(artifact, hiddenCriteria) => { passRate, total }` — the coding
+ *      node-test executor is ONE such grader a consumer plugs in; the substrate
+ *      bakes in NO node/test/TS/exec/regex. `gradeOnHidden` runs that grader
+ *      behind the firewall and `blendHeldout` composes its pass rate with a
+ *      judge score into the final number the leaderboard ranks on.
+ *
+ * Shape mirrors `treatment-gate`/`authenticity`: pure predicates and pure
+ * composition over already-computed values, fail-loud, with the
+ * "which field / which weight / which grader" decisions left as parameters and
+ * no domain literal anywhere in the module.
+ *
+ * Lives next to `test-graded-scenario` and `partition-held-out` — it is a
+ * scorecard/grading concept that makes sense without a running agent loop.
+ */
+/**
+ * Where one scenario field is allowed to flow. The firewall guarantee is keyed
+ * on this tag, not on a field name — a domain can have any number of fields per
+ * destination.
+ *
+ *   - `agent-visible`   reaches the agent's context during the run (the prompt,
+ *                       the task statement — what the agent reads to act).
+ *   - `develop-against` seeded into the agent's environment during the run so it
+ *                       can iterate (a visible example/test/reference). The
+ *                       agent MAY read it — that is intentional (real TDD). Not
+ *                       a leak: it is example-grade, not the grading criteria.
+ *   - `grading-only`    the hidden criteria. Used ONLY at grading, after the run
+ *                       — the held-out suite / answer key / hidden requirements.
+ *                       Must NEVER reach the agent context. This is what makes a
+ *                       good score un-memorizable.
+ *   - `judge-only`      grading context for the judge only (rubric anchors,
+ *                       design intent). Lives with the judge, never in the agent
+ *                       context.
+ */
+type FieldDestination = 'agent-visible' | 'develop-against' | 'grading-only' | 'judge-only';
+/**
+ * A scenario's fields routed by destination. The domain owns the field set
+ * (`TFields` — a record of its named fields to their string-renderable values)
+ * and declares one `FieldDestination` per field. `routeFields` builds this from
+ * a domain's `(value, destination)` map; the firewall reads it.
+ */
+interface RoutedField {
+  /** The field's name — for diagnostics only. */
+  name: string;
+  /** The field's value as it would be rendered into text. The firewall compares
+   *  this against the agent context, so a domain that ships structured data
+   *  passes a stable string projection (e.g. JSON) of the hidden value. */
+  value: string;
+  destination: FieldDestination;
+}
+/** A single detected leak: a hidden field whose value appears in the agent context. */
+interface HiddenLeak {
+  field: string;
+  destination: FieldDestination;
+}
+interface NoLeakOptions {
+  /** Minimum hidden-value length to check. A hidden value shorter than this is
+   *  skipped — a one-word or empty hidden field would substring-match innocuous
+   *  prose and is not meaningful evidence of a leak. Default 12. */
+  minMatchLength?: number;
+}
+/**
+ * The FIREWALL. Throws `ValidationError` if any `grading-only`/`judge-only`
+ * field's value is found inside `agentContext` — the exact text that reaches the
+ * agent during the run (its prompt, its seeded files concatenated, whatever the
+ * caller assembled). `agent-visible` and `develop-against` fields are never
+ * checked: they are meant to be there.
+ *
+ * Substring containment is the check: it is domain-free and catches the failure
+ * that matters — a hidden answer key, held-out case, or rubric anchor pasted
+ * into the prompt. Returns the routed fields on success so a caller can chain.
+ */
+declare function assertNoHiddenLeak(fields: readonly RoutedField[], agentContext: string, opts?: NoLeakOptions): readonly RoutedField[];
+/** What a hidden-criteria grader reports. `passRate = passed / total` over the
+ *  hidden checks; `total === 0` means the criteria never ran (e.g. the artifact
+ *  did not even load) — an honest zero, never a spurious pass. */
+interface HiddenGradeResult {
+  /** Hidden checks that passed. */
+  passed: number;
+  /** Total hidden checks attempted. 0 when the criteria could not run at all. */
+  total: number;
+  /** `passed / total`, or 0 when `total === 0`. The PRIMARY correctness score. */
+  passRate: number;
+  /** Free-form provenance the caller may record (runner output, reason for 0). */
+  notes?: string;
+}
+/**
+ * The domain's grader: given the agent's artifact and the HIDDEN criteria,
+ * return a pass rate. This is the ONE seam a non-coding domain implements — the
+ * coding node-test executor is a single implementation of it; a legal grader
+ * checks the brief against hidden required holdings, a research grader checks an
+ * answer against held-out facts, a tax grader runs hidden return assertions.
+ * The substrate calls it ONLY at grading time, behind the firewall.
+ *
+ * `THidden` is the domain's hidden-criteria payload (the held-out suite, the
+ * answer key, the hidden requirements) — opaque to the substrate.
+ */
+type HiddenCriteriaGrader<TArtifact, THidden> = (artifact: TArtifact, hiddenCriteria: THidden, signal?: AbortSignal) => Promise<HiddenGradeResult> | HiddenGradeResult;
+/** Weights for the held-out / judge blend. Must be finite and non-negative;
+ *  they are renormalized to sum to 1 so a caller can pass any positive ratio. */
+interface BlendWeights {
+  /** Weight on the hidden-criteria pass rate (the primary, ungameable score). */
+  heldout: number;
+  /** Weight on the judge's quality composite (the secondary style/quality score). */
+  judge: number;
+}
+/** The input shape a judge's `score` receives — exactly `JudgeConfig.score`'s
+ *  argument: the artifact, plus any scenario/signal fields the judge carries.
+ *  `withHeldoutBlend` only reads `artifact`; the rest rides through. */
+interface JudgeScoreInput<TArtifact> {
+  artifact: TArtifact;
+  /** Pass-through for the judge's extra input fields (scenario, signal). */
+  [key: string]: unknown;
+}
+/**
+ * Compose the PRIMARY hidden-criteria pass rate with the SECONDARY judge
+ * composite into the single score the leaderboard ranks on. Weights are
+ * renormalized, so a solution that fails the hidden criteria is capped low no
+ * matter how the judge felt about its style, while a stylistically-mediocre but
+ * CORRECT solution still earns the bulk of the points. Both inputs are clamped
+ * to [0,1] — a judge on a non-unit scale must be normalized by the caller first.
+ */
+declare function blendHeldout(heldoutPassRate: number, judgeScore: number, weights?: BlendWeights): number;
+/**
+ * Minimal backend-config shape the assertion reads. Consumers may pass richer
+ * types — only these five fields are inspected.
+ */
+interface BackendDescriptor {
+  /** Backend route — e.g. `'tcloud' | 'cli-bridge' | 'sandbox' | 'direct-provider'`;
+   *  free-form for consumer extensibility. */
+  kind: string;
+  /** Resolved base URL. Compared lexically (trailing slash stripped). */
+  baseUrl: string;
+  /** Model id (with snapshot suffix). Compared lexically. */
+  model: string;
+  /** Optional provider override. Compared when both set; flagged when only
+   *  one side sets it. */
+  provider?: string;
+  /** Bearer token. Values are NEVER compared (security) — only that EITHER
+   *  both are set OR both are empty. Mismatched presence is a divergence. */
+  apiKey?: string;
+}
+interface AssertSingleBackendOptions {
+  /** When true, ANY field divergence fails. When false (default), only
+   *  `kind` / `baseUrl` / `provider` / `apiKeyPresence` divergence throws —
+   *  a different judge `model` on the same route is allowed (the legal
+   *  pattern: a cheaper judge model). */
+  strict?: boolean;
+  agentLabel?: string;
+  judgeLabel?: string;
+}
+type SingleBackendField = 'kind' | 'baseUrl' | 'model' | 'provider' | 'apiKeyPresence';
+interface SingleBackendDivergence {
+  field: SingleBackendField;
+  agent: string | undefined;
+  judge: string | undefined;
+}
+interface SingleBackendReport {
+  /** True when agent + judge agree per the configured strictness. */
+  ok: boolean;
+  /** Every divergence detected (includes `model` even when non-blocking). */
+  divergences: ReadonlyArray<SingleBackendDivergence>;
+}
+/**
+ * Throw `SingleBackendError` when the agent and judge backends diverge in a
+ * way that would re-route the judge through a different backend than the
+ * agent. Returns the report so callers can log it in either case.
+ */
+declare function assertSingleBackend(agent: BackendDescriptor, judge: BackendDescriptor, opts?: AssertSingleBackendOptions): SingleBackendReport;
+interface IntentMatchInput {
+  /** The full natural-language prompt the agent was handed. */
+  userRequest: string;
+  /** Top-level source files from the agent's workdir. */
+  sourceFiles: Array<{
+    path: string;
+    content: string;
+  }>;
+  /** Rendered HTML the preview returned, when available. */
+  servedHtml?: string;
+  /** Optional metadata to inject (id, vertical, difficulty). */
+  artifactLabel?: string;
+  artifactDescription?: string;
+}
+interface IntentMatchResult {
+  kind: 'intent-match';
+  version: string;
+  /** 0..1 — 1 = unmistakably the right app, 0 = unrelated to the brief. */
+  score: number;
+  /** One-sentence rationale citing concrete evidence (file or HTML). */
+  evidence: string;
+  durationMs: number;
+  costUsd: number | null;
+  available: boolean;
+  error?: string;
+}
+interface IntentMatchOptions {
+  /** Caller-owned transport. Required: agent-eval executes no paid model. */
+  chat: ChatClient;
+  model?: string;
+  timeoutMs?: number;
+  maxTokens?: number;
+  maxSourceChars?: number;
+  maxPerFileChars?: number;
+  maxHtmlChars?: number;
+  /** Endpoint rates used when the transport reports no billed amount. */
+  pricing?: CustomTokenPricing;
+  costLedger?: CostLedgerHandle;
+  costPhase?: string;
+  costTags?: Record<string, string>;
+  signal?: AbortSignal;
+}
+/**
+ * Run the intent-match judge. Soft-fails to available=false on error.
+ */
+declare function runIntentMatchJudge(input: IntentMatchInput, options: IntentMatchOptions): Promise<IntentMatchResult>;
+/** One judge's verdict. `perDimension: null` ⇒ that judge call failed (threw or
+ *  returned malformed output) — recorded, never folded into a zero. */
+interface JudgeVerdict<D extends string = string> {
+  /** Judge identity (typically the model id) — the `perJudge` / `failedJudges` key. */
+  model: string;
+  /** Per-dimension scores, or `null` when the judge failed. */
+  perDimension: Record<D, number> | null;
+  /** Optional one-line rationale; the first non-empty one becomes the aggregate's. */
+  rationale?: string;
+  /** Optional reported cost, committed by the caller's CostLedger. */
+  costUsd?: number;
+  /** Optional provider usage, committed by the caller's CostLedger. */
+  usage?: LlmUsage;
+  /** Optional per-dimension reasoning/evidence. Carried through to
+   *  `EnsembleAggregate.verdicts` verbatim — never folded into the math. */
+  detail?: Partial<Record<D, {
+    reasoning?: string;
+    evidence?: string;
+  }>>;
+}
+/** The aggregated ensemble result. */
+interface EnsembleAggregate<D extends string = string> {
+  /** Mean over SURVIVING judges, per dimension (absent-everywhere ⇒ 0). */
+  perDimension: Record<D, number>;
+  /** Weighted mean of `perDimension` (uniform unless `weights` given). */
+  composite: number;
+  /** Each surviving judge's clamped per-dimension scores, for trace drill-down. */
+  perJudge: Record<string, Record<D, number>>;
+  /** Max over dimensions of (max − min) across survivors — the inter-rater signal. */
+  maxDisagreement: number;
+  /** Models whose verdict was null (failed). */
+  failedJudges: string[];
+  /** First non-empty survivor rationale, or `'llm-judge'`. */
+  rationale: string;
+  /** The input verdicts, verbatim — drill-down to raw scores, `detail`
+   *  reasoning/evidence, and per-verdict cost without re-running judges. */
+  verdicts: JudgeVerdict<D>[];
+}
+/**
+ * Reduce per-judge verdicts to one aggregate. Generic over the rubric: pass the
+ * stable-ordered `dimensionKeys` the judges scored.
+ *
+ * - Per-dimension score = mean over surviving judges (out-of-range clamped to [0,1]).
+ * - `composite` = `weightedComposite` of `perDimension`. No `weights` ⇒ uniform
+ *   over every dimension. A partial `weights` map selects AND weights exactly the
+ *   named dimensions (others excluded from the composite) — the substrate's
+ *   sum-normalized weighting, not re-implemented here.
+ * - Throws if `verdicts` or `dimensionKeys` is empty, or if every judge failed.
+ */
+declare function aggregateJudgeVerdicts<D extends string>(verdicts: readonly JudgeVerdict<D>[], dimensionKeys: readonly D[], weights?: Partial<Record<D, number>>): EnsembleAggregate<D>;
+/**
+ * Wrap a single judge LLM call with retry, optional fallback-model
+ * rotation, exponential backoff, and a typed `JudgeRetryOutcome`. Callers
+ * MUST inspect `succeeded` before using `value`; on failure the library
+ * returns `value: null` rather than substituting a default, so a judge
+ * abort cannot silently corrupt a downstream composite.
+ *
+ * Reporting contract: callers ship `TrialResult.judgeSucceeded = succeeded`
+ * and `TrialResult.judgeAttempts = attempts` so `aggregateTrialsByMode`
+ * with `mode: 'exclude-failed'` drops the trial.
+ */
+/** Retry policy for judge LLM calls. */
+interface JudgeRetryPolicy {
+  /** Max attempts per model. Default 3 (one initial + two retries). */
+  maxAttempts?: number;
+  /** Per-attempt timeout in ms. Default 300_000. */
+  timeoutMs?: number;
+  /**
+   * Models to try, in order. The first model is the primary; subsequent
+   * models are fallbacks invoked only when ALL retries on the previous
+   * model have been exhausted. Example: `['claude-code/sonnet', 'kimi-code/k2p6']`
+   * runs claude-code up to maxAttempts times, then falls back to kimi.
+   * If omitted, the caller's judge function controls model selection and
+   * the retries apply to that single model.
+   */
+  models?: readonly string[];
+  /** Exponential backoff function, default `attempt → min(500 * 2^attempt, 16_000)`. */
+  backoffMs?: (attempt: number) => number;
+  /**
+   * Predicate deciding whether an error should trigger a retry. Defaults to
+   * `isTransientLlmError` — the package-wide classifier shared with
+   * `callLlm` — which retries aborts/timeouts, network faults, HTTP/2
+   * transport faults, and any `LlmCallError` with status in {429,502,503,504}.
+   * JSON-parse and schema-rejection errors are NOT retriable (the model
+   * needs prompt adjustment, not another shot).
+   */
+  isRetryable?: (err: unknown) => boolean;
+}
+/** Outcome of a wrapped judge invocation. */
+interface JudgeRetryOutcome<T> {
+  /** The judge's returned value when `succeeded === true`. */
+  value: T | null;
+  /** True iff one of the attempts completed without throwing. */
+  succeeded: boolean;
+  /** Total attempts made across all models. */
+  attempts: number;
+  /** Which model the successful attempt used (when succeeded). */
+  modelUsed?: string;
+  /** Last error captured when `succeeded === false`. */
+  error?: Error;
+  /** Per-attempt error log for forensics. */
+  attemptErrors: Array<{
+    attempt: number;
+    model: string;
+    error: string;
+  }>;
+}
+/**
+ * Wrap a judge call with retry + fallback-model + typed outcome semantics.
+ *
+ * The `judgeFn` signature is `(model: string, signal: AbortSignal) => Promise<T>`.
+ * The signal will be aborted at `timeoutMs`. Callers should pass the signal
+ * to their underlying fetch/SDK call so the abort actually fires.
+ *
+ * Returns a typed outcome — callers MUST inspect `succeeded` before using
+ * `value`. The library refuses to default to a silent zero score because a
+ * synthetic zero is indistinguishable from a real low score downstream.
+ */
+declare function withJudgeRetry<T>(judgeFn: (model: string, signal: AbortSignal) => Promise<T>, policy?: JudgeRetryPolicy): Promise<JudgeRetryOutcome<T>>;
+interface EnsembleJudgeOptions<D extends string> {
+  /** Judge name — becomes the returned `JudgeConfig.name`. */
+  name: string;
+  /** Rubric dimensions every model scores. Keys of the verdict's `perDimension`. */
+  dimensions: D[];
+  /** Judge model ids — one `scoreWith` call per entry. List a model twice to
+   *  sample it twice (votes are suffix-keyed `model#2` so none overwrite). */
+  models: string[];
+  /** Explicit scoring revision for closure state not visible in the static panel config. */
+  judgeVersion?: string;
+  /**
+   * Score the artifact with one model. Throw (or reject) on failure — the
+   * panel records that model as a failed judge; it is never folded into a
+   * zero. Verdict scores are clamped to [0,1] by the reducer.
+   */
+  scoreWith: (model: string, input: {
+    artifact: unknown;
+    scenario?: unknown;
+    signal: AbortSignal;
+  }) => Promise<JudgeVerdict<D>>;
+  /** Recover usage from a failed provider response when its error retains one. */
+  receiptFromError?: (error: Error, model: string) => CostReceiptInput | undefined;
+  /** Used by direct score calls; campaigns supply their run ledger in score(). */
+  costLedger?: CostLedgerHandle;
+  /** Required per model when the shared ledger has a dollar cap. */
+  maximumCharge?: MaximumCharge | ((model: string) => MaximumCharge);
+  /**
+   * Per-model retry policy, applied via `withJudgeRetry`. The panel's
+   * `models` list drives the fan-out, so `retry.models` (the fallback
+   * rotation) is overridden to each panel model in turn.
+   */
+  retry?: JudgeRetryPolicy;
+  /** Enforce `assertCrossFamily` over `models` at construction. Default true.
+   *  Opt out only for deliberate single-family panels (e.g. self-consistency
+   *  sampling of one model).
+   *
+   *  Construction-time only, over the REQUESTED ids: it cannot see a gateway
+   *  that answers several ids from one provider. `scoreWith` owns the served
+   *  side — check the id the provider echoed with `assertServedModel`
+   *  (./integrity/served-model) inside your judge call. */
+  crossFamily?: boolean;
+  /** Composite weights forwarded to `aggregateJudgeVerdicts`: a partial map
+   *  selects AND weights exactly the named dimensions. Omit for uniform. */
+  weights?: Partial<Record<D, number>>;
+}
+/**
+ * Build a campaign-shaped `JudgeConfig` whose `score()` runs every panel
+ * model in parallel and reduces the surviving verdicts to one canonical
+ * `JudgeScore` in [0,1].
+ *
+ * Failure semantics: a model whose `scoreWith` throws (or exhausts `retry`)
+ * lands in `failedJudges` and is excluded from the means. When EVERY model
+ * fails, `aggregateJudgeVerdicts` throws — the campaign engine records a
+ * failed cell instead of averaging a fabricated zero.
+ */
+declare function ensembleJudge<D extends string>(opts: EnsembleJudgeOptions<D>): JudgeConfig<unknown>;
+/**
+ * Keyword-coverage judge — baseline complement to the semantic concept
+ * judge.
+ *
+ * Where {@link runSemanticConceptJudge} uses an LLM to read source code
+ * and decide whether a concept is REALLY implemented (not just
+ * keyword-mentioned), this judge does the cheap, deterministic version:
+ * fetch the served preview, concatenate every linked CSS/JS asset, and
+ * substring-match each expected concept's keywords against the
+ * concatenated haystack. Optional `requiredElement` selector adds a
+ * structural gate so "supply counter" can require an actual `<input>` or
+ * `<table>`, not just a comment containing the word.
+ *
+ * Use both judges. Keyword coverage is a fast 0-cost gate — a stub page
+ * with the right keywords passes here, fails the semantic judge. Score
+ * divergence between the two is itself a signal: high keyword coverage
+ * + low semantic = "the agent slapped the right words on the right
+ * scaffold but didn't wire any of it up."
+ *
+ * Pure functions, soft-fail on fetch error, no LLM dependency.
+ */
+interface KeywordConceptSpec {
+  name: string;
+  keywords: string[];
+  /**
+   * Optional CSS selector that must match in the HTML for the concept
+   * to count as present. Tiny subset:
+   *   - `tag`               (e.g. `form`)
+   *   - `tag[attr="value"]` (e.g. `input[type="number"]`)
+   *   - `tag[attr]`         (presence only)
+   * Anything more complex is rejected with `null` (treated as
+   * "unenforced", not "failed").
+   */
+  requiredElement?: string;
+}
+interface KeywordCoverageFinding {
+  concept: string;
+  found: boolean;
+  matchedKeywords: string[];
+  /** True iff the optional requiredElement selector matched; null when no selector. */
+  requiredElementPresent: boolean | null;
+}
+interface KeywordCoverageResult {
+  /** 0..1 share of concepts satisfied. */
+  score: number;
+  presentCount: number;
+  totalCount: number;
+  findings: KeywordCoverageFinding[];
+  durationMs: number;
+  /** Total bytes assembled across html + linked assets. */
+  totalAssembledBytes: number;
+  /** Soft-failure reason if the audit couldn't run. */
+  error?: string;
+}
+interface KeywordCoverageOptions {
+  /** Override fetch implementation — for tests. */
+  fetch?: typeof fetch;
+  /** Per-asset fetch timeout (default 3s). */
+  assetTimeoutMs?: number;
+  /** Initial-HTML fetch timeout (default 5s). */
+  htmlTimeoutMs?: number;
+}
+/**
+ * Score expected concepts against an already-fetched HTML payload + any
+ * pre-fetched CSS/JS assets. Use when the runner has the bytes in hand
+ * and doesn't want a fresh HTTP round-trip — e.g. sandbox runtime where
+ * the preview content was fetched via curl from inside the container.
+ */
+declare function runKeywordCoverageJudge(html: string, expectedConcepts: ReadonlyArray<KeywordConceptSpec>, assets?: ReadonlyArray<string>): KeywordCoverageResult;
+/**
+ * URL-fetch flavor — GET the preview, parallel-fetch every linked
+ * stylesheet + script (with bounded timeouts, soft-fail individually),
+ * then score via {@link runKeywordCoverageJudge}.
+ */
+declare function runKeywordCoverageJudgeUrl(previewUrl: string, expectedConcepts: ReadonlyArray<KeywordConceptSpec>, options?: KeywordCoverageOptions): Promise<KeywordCoverageResult>;
+interface OracleObservation {
+  /** Final observable text output from the agent (response, page snapshot, stdout). */
+  text?: string;
+  /** Final URL — for browser-style scenarios. */
+  url?: string;
+  /** Any structured JSON the agent produced. */
+  json?: unknown;
+  /** Free-form context used by custom oracles. */
+  context?: Record<string, unknown>;
+}
+interface OracleResult {
+  id: string;
+  pass: boolean;
+  detail: string;
+  evidence?: string;
+}
+interface Oracle {
+  id: string;
+  check(obs: OracleObservation): OracleResult;
+}
+declare function jsonShape(expected: Record<string, unknown>): Oracle;
+/** Extends the substrate verdict spine: `valid` = every oracle passed (and
+ *  at least one ran); `score` = ratio of oracles passed; `scores` = per-
+ *  oracle 0|1 keyed by oracle id. */
+interface OracleReport extends DefaultVerdict {
+  results: OracleResult[];
+  passCount: number;
+  failCount: number;
+}
+/** Run all oracles against one observation and aggregate. */
+declare function evaluateOracles(obs: OracleObservation, oracles: Oracle[]): OracleReport;
+/** A serializable law for one scalar draw. */
+type PairedValueLaw = {
+  kind: 'point';
+  value: number;
+} | {
+  kind: 'atoms';
+  atoms: ReadonlyArray<{
+    value: number;
+    probability: number;
+  }>;
+} | {
+  kind: 'normal';
+  mean: number;
+  sd: number;
+};
+interface PairedPromotionAlternativeCell {
+  /** Probability of this cell. The cells' probabilities sum to 1. */
+  probability: number;
+  /** Pass/fail outcome of each arm in this cell. Required by every call whose
+   *  `outcome` is `'pass'`; ignored otherwise. */
+  pass?: {
+    control: boolean;
+    treatment: boolean;
+  };
+  /** Law of the candidate-minus-baseline delta on the continuous scale, given
+   *  this cell. A tie is `{ kind: 'point', value: 0 }`. */
+  delta: PairedValueLaw;
+}
+interface PairedPromotionAlternative {
+  /** The registered joint law: the cell is drawn first, then the delta given
+   *  the cell, so pass/fail and delta are dependent exactly as registered. */
+  cells: ReadonlyArray<PairedPromotionAlternativeCell>;
+  /**
+   * Law of the control arm's value on the continuous scale; the candidate is
+   * control plus delta. Default `{ kind: 'point', value: 0 }`. The mean and
+   * median bootstraps read only the deltas, so the baseline changes nothing
+   * there; it matters only when a `'delta'` call infers its shape from the
+   * observed values (see `continuous` on {@link PairedPromotionDecisionOptions}).
+   */
+  baseline?: PairedValueLaw;
+}
+interface PairedPromotionPowerCall {
+  /** What the call reads from each simulated pair: `'delta'` gives it
+   *  `(control, control + delta)` on the continuous scale, `'pass'` gives it
+   *  each arm's pass/fail as `0` or `options.binaryScale ?? 1`. */
+  outcome: 'delta' | 'pass';
+  /** The call's options, exactly as the caller will run it. `minPairs`
+   *  defaults to the simulated n, the value a gate seals; a caller-supplied
+   *  value is kept, and one above n refuses every simulation. A `'pass'` call
+   *  must declare `binaryScale`: the simulation never declares one on the
+   *  caller's behalf, because a declared scale routes an all-zero sample to
+   *  the score interval where an inferred one refuses it. */
+  options: PairedPromotionDecisionOptions;
+}
+interface PairedPromotionPowerOptions {
+  /** Total paired episodes, ties included. */
+  n: number;
+  alternative: PairedPromotionAlternative;
+  /** Every call must return `promote: true` for a simulation to count as a
+   *  promotion. At least one call. */
+  calls: ReadonlyArray<PairedPromotionPowerCall>;
+  /** Simulated data sets. Default 1000. */
+  simulations?: number;
+  /** PRNG seed for the simulated draws (not the bootstrap's seed, which each
+   *  call carries in its own options). Default 1. */
+  seed?: number;
+}
+interface PairedPromotionCallRates {
+  outcome: 'delta' | 'pass';
+  /** Fraction of simulations in which this call alone promoted. */
+  promote: number;
+  /** Fractions of simulations in which each refusal channel fired. */
+  insufficient: number;
+  indeterminate: number;
+  exactTestVetoes: number;
+  /** Fraction in which the call was sufficient, determinate, not vetoed, and
+   *  still did not clear its threshold. */
+  hold: number;
+  /** Fraction of simulations decided by each method; the regime the call
+   *  actually ran in at this n. */
+  methods: Partial<Record<PairedDecisionMethod, number>>;
+}
+interface PairedPromotionPowerResult {
+  n: number;
+  simulations: number;
+  seed: number;
+  /** Fraction of simulations in which every call promoted: the joint power. */
+  power: number;
+  /** Monte Carlo standard error of `power`. */
+  standardError: number;
+  /** Wilson 95% interval on `power`. */
+  low: number;
+  high: number;
+  /** Fraction in which at least one call refused (insufficient, indeterminate
+   *  or vetoed); the rest of the non-promotions are holds. */
+  refuse: number;
+  hold: number;
+  /** Per-call rates, in the order the calls were supplied. */
+  calls: PairedPromotionCallRates[];
+}
+interface RequiredPairsForPairedPromotionOptions {
+  /** Target joint power. Default 0.8. */
+  target?: number;
+  alternative: PairedPromotionAlternative;
+  calls: ReadonlyArray<PairedPromotionPowerCall>;
+  /** Smallest n to consider. Default 1. */
+  minPairs?: number;
+  /** Largest n to consider; the scan stops there with `n: null` if the target
+   *  is never reached. Default 200. */
+  maxPairs?: number;
+  simulations?: number;
+  seed?: number;
+}
+interface RequiredPairsForPairedPromotionResult {
+  target: number;
+  /** First n scanned whose estimated joint power reaches the target, or null
+   *  when no n up to `maxPairs` does. Descriptive only: power is not monotone
+   *  in n on the exact and discrete routes, the scan reads one noisy estimate
+   *  per n, and the first crossing of many is biased low. Read the curve. */
+  n: number | null;
+  /**
+   * The conservative choice, which a preregistration should prefer: the first
+   * scanned n whose Wilson lower bound reaches the target AND whose
+   * independent confirmation (a second simulation at that n on a fresh seed,
+   * `confirmation` below) also has its lower bound at or above the target. The
+   * confirmation is what keeps the 95 % coverage: a scan over many n gives
+   * Monte Carlo noise many chances to push one bound across, so the scan's own
+   * bound selects a candidate and never certifies it. Never set while `n` is
+   * null. Null when not reached by `maxPairs`.
+   */
+  nAtLowerBound: number | null;
+  /** The independent simulation at `nAtLowerBound`; null when not reached. */
+  confirmation: PairedPromotionPowerResult | null;
+  /** Every n scanned, in order, with its scan estimate; candidates whose
+   *  confirmation failed are in `rejected`. The scan stops at `nAtLowerBound`
+   *  when that is reached, else at `maxPairs`. */
+  curve: PairedPromotionPowerResult[];
+  /** Candidates the scan's bound selected and the confirmation refused. */
+  rejected: PairedPromotionPowerResult[];
+}
+/**
+ * Joint power of the configured calls at `n` under the registered alternative:
+ * the fraction of simulated data sets on which every call promotes.
+ */
+declare function pairedPromotionPower(options: PairedPromotionPowerOptions): PairedPromotionPowerResult;
+/**
+ * First n at which {@link pairedPromotionPower} reaches the target, scanning
+ * every n from `minPairs` upward. Both the point-estimate answer and the
+ * confirmed lower-bound answer are returned; the scan runs until the latter is
+ * reached (so the curve past `n` is retained) or `maxPairs` is exhausted. A
+ * candidate selected by the scan's bound is certified only by an independent
+ * simulation at that n on a different seed; a candidate that fails it is
+ * recorded and the scan continues.
+ */
+declare function requiredPairsForPairedPromotion(options: RequiredPairsForPairedPromotionOptions): RequiredPairsForPairedPromotionResult;
+/**
+ * Treatment-applied gate — "did the treatment's tool actually fire this run?"
+ *
+ * A tool-treatment A/B (mount a search provider, a browser, a code-exec
+ * sandbox, a retrieval MCP — anything one arm gets and the other doesn't) only
+ * means something on the treatment arm if that arm actually EXERCISED the tool.
+ * A treatment run that never called the mounted tool is not a weak data point
+ * — it is a NON-data-point: the manipulation never happened, so the run cannot
+ * speak to the treatment and must be excluded from the objective, the same way
+ * an infra-tainted run is excluded.
+ *
+ * This is the manipulation/validity precondition that protects the paired A/B
+ * tests downstream (`mcnemar`, `pairedRiskDifference`): they must only ever see
+ * runs where the treatment was applied, or they measure noise and report it as
+ * an effect.
+ *
+ * Shape mirrors `authenticity`'s `gateRealness`: a pure predicate over already-
+ * computed signals, with explicit fail-open/fail-closed discipline. It is not a
+ * trace parser — the tool-call telemetry it reads is the deterministic
+ * `toolHistogram` that `computeTraceMetrics(spans)` already produces (OTLP
+ * tool-name extraction via `TOOL_NAME_ATTR_KEYS`), or the `ToolSpan[]` a
+ * `toolSpans(store, runId)` query returns. The gate never re-derives either.
+ *
+ * General by construction:
+ *   - The "which tool counts as the treatment" decision is a `matches` PARAMETER
+ *     — a `(toolName: string) => boolean`. There is no `search`/`web`/`fetch`
+ *     literal anywhere in this module; a search A/B passes its own matcher.
+ *   - The "is THIS run a treatment arm (vs a control)" decision is the caller's
+ *     policy and stays at the call site. The gate only answers the narrower,
+ *     domain-free question: "given this run's telemetry, did a matching tool
+ *     fire?" — so it generalizes to any tool-treatment, not search.
+ *
+ * Fail-open on telemetry absence: when NO tool calls were captured at all
+ * (`sum(toolHistogram) === 0`), the gate cannot distinguish "the agent used no
+ * tools" from "this harness's tool calls weren't recorded". Quarantining on a
+ * telemetry gap would silently delete real runs, so the default is
+ * applied=true / gated=false. Pass `failOpenWhenNoTelemetry: false` to flip to
+ * fail-closed for harnesses where tool capture is guaranteed.
+ */
+/** A tool-name matcher: does this tool name belong to the treatment under test?
+ *  The caller supplies it — the substrate ships no `search` (or any) literal. */
+type ToolMatcher = (toolName: string) => boolean;
+interface TreatmentGateInput {
+  /** Tool-call counts by tool name — exactly `computeTraceMetrics(spans).toolHistogram`.
+   *  The gate consumes this; it does not parse spans itself. */
+  toolHistogram: Readonly<Record<string, number>>;
+  /** Which tool names count as the treatment firing. A parameter, never baked in. */
+  matches: ToolMatcher;
+}
+interface TreatmentGateOptions {
+  /** When the histogram is empty (no tool telemetry captured), treat the run as
+   *  applied rather than quarantining it. Default true — a telemetry gap must
+   *  never be mistaken for "treatment not applied". Set false only when tool
+   *  capture is guaranteed for this harness. */
+  failOpenWhenNoTelemetry?: boolean;
+}
+interface TreatmentGate {
+  /** True iff the treatment's tool is considered to have fired this run. False
+   *  ONLY when telemetry was present and no matching call appears. */
+  applied: boolean;
+  /** Objective-exclusion flag, parallel to `outcome.realness.gated`: a gated run
+   *  is dropped from the objective denominator and reported as
+   *  treatment-not-applied (like infra-loss). `gated === !applied`. */
+  gated: boolean;
+  reason?: string;
+  /** How many recorded tool calls matched the treatment matcher. */
+  matchedCalls: number;
+  /** Total recorded tool calls (`sum(toolHistogram)`) — 0 means no telemetry. */
+  observedTools: number;
+}
+/**
+ * Core predicate. Gated (treatment-not-applied) ONLY when telemetry was
+ * captured AND zero matching calls appear; an empty histogram fails open.
+ */
+declare function gateTreatmentApplied(input: TreatmentGateInput, opts?: TreatmentGateOptions): TreatmentGate;
+/**
+ * Canonical JSON (RFC 8785): object keys sorted recursively, so two
+ * semantically equal values produce byte-identical output regardless of key
+ * insertion order. Throws `LedgerCanonicalizationError` on any value with no
+ * faithful JSON form — see `ledger-core/canonical`.
+ */
+declare function canonicalJson(value: unknown): string;
+/** Hex sha-256 over `canonicalJson(value)`. The content address used by the
+ *  verdict cache and report attestation. Equals `hashCanonical(value)` with
+ *  the `sha256:` prefix removed. */
+declare function contentHash(value: unknown): string;
+/** Pluggable verdict store. Sync or async on both legs — `cachedJudge`
+ *  awaits the results either way. */
+interface VerdictCacheStore {
+  get(key: string): Promise<JudgeScore | undefined> | JudgeScore | undefined;
+  set(key: string, score: JudgeScore): Promise<void> | void;
+}
+/**
+ * JSONL-file-backed store: the full file is loaded into an in-memory index at
+ * construction; every `set` appends one line synchronously (durable before
+ * the verdict is returned). A corrupt or malformed line throws at load with
+ * file:line — a skipped line would silently re-judge (cost) or, worse, mask
+ * a half-written file that needs operator attention.
+ */
+declare function fileVerdictCache(path: string): VerdictCacheStore;
+/**
+ * Strong, generically-useful baseline ROLES — the top zone of an `AgentProfile`
+ * before any domain layer. A product composes one of these with its own
+ * environment description (its sandbox) and its domain guidance, which lives in
+ * the product repo (not here): a profile is `<baseline role> + <environment> +
+ * <domain sections>`. Domain strength is NOT generalized into the substrate —
+ * it is lifted here only once ≥2 products genuinely reuse it.
+ *
+ * Three roles cover the common shapes:
+ *   - `engineerRole`   — builds + verifies real artifacts in a sandbox. Distilled
+ *                        from agent-runtime's `coderProfile` doctrine (minimal
+ *                        correct change, run the checks, fix the root cause,
+ *                        never weaken a test or hide an error).
+ *   - `researcherRole` — gathers from real sources and grounds every claim
+ *                        (cite or mark inferred; never fabricate).
+ *   - `generalistRole` — a strong default: helpful, grounded, verify-before-assert.
+ *
+ * All three are verification-first and domain-agnostic. They describe HOW a
+ * capable IC operates, not WHAT domain it works in.
+ */
+/** Senior-IC engineer operating in a sandbox — produces real artifacts and
+ *  verifies them before declaring done. The shared operator foundation for any
+ *  file-producing, tool-using product agent. */
+declare const engineerRole: string;
+/** Researcher who grounds every claim in real sources — gathers, cites, and
+ *  distinguishes verified fact from inference. */
+declare const researcherRole: string;
+/** Strong general-purpose default — helpful, grounded, verifies before asserting. */
+declare const generalistRole: string;
+/** The named baseline roles, for selection by key (e.g. from a product config). */
+declare const BASELINE_ROLES: {
+  readonly engineer: string;
+  readonly researcher: string;
+  readonly generalist: string;
+};
+type BaselineRoleKey = keyof typeof BASELINE_ROLES;
+declare namespace index_d_exports {
+  export { AgentProfileSection, BASELINE_ROLES, BaselineRoleKey, ProfileSkill, PromptProfile, applyDomainPatch, baselineProfile, baselineProfileFromRole, engineerRole, generalistRole, prodProfile, profileToSurface, renderProfile, researcherRole, sectionHash };
+}
+/** A named, addressable region of the system prompt. `evolvable` marks whether
+ *  the self-improvement loop is allowed to patch its body; fixed scaffolding
+ *  (e.g. a compliance preamble) sets `evolvable: false`. */
+interface AgentProfileSection {
+  id: string;
+  title: string;
+  body: string;
+  evolvable: boolean;
+}
+/** A skill the agent can invoke. `triggers` are the phrases/conditions that
+ *  should activate it; `scriptsDir` points at its executable scripts when the
+ *  skill ships code (mirrors Harvey's `skills/<name>/scripts/`). */
+interface ProfileSkill {
+  name: string;
+  description: string;
+  triggers: string[];
+  scriptsDir?: string;
+}
+/** The structured system prompt. The first four fields are fixed scaffolding;
+ *  `domain` is the evolvable surface the loop optimizes. */
+interface PromptProfile {
+  role: string;
+  environment: string;
+  toolConventions: string;
+  skills: ProfileSkill[];
+  domain: AgentProfileSection[];
+}
+/**
+ * Emit the sectioned system prompt in fixed order: role text, then
+ * `## Environment`, `## Tool conventions`, `## Skills` (each skill as
+ * `### <name>` + description + triggers), `## Domain guidance` (each section as
+ * `### <title>` + body). The order is load-bearing — the loop diffs rendered
+ * text, and reordering would make every candidate look like a full rewrite.
+ */
+declare function renderProfile(p: PromptProfile): string;
+/** The string `MutableSurface` the self-improvement loop scores — a profile
+ *  renders to exactly the text a candidate is graded on. */
+declare function profileToSurface(p: PromptProfile): string;
+/**
+ * The fixed-scaffolding baseline: a `role`/`environment`/`toolConventions`
+ * profile with the stock skill roster and NO domain guidance. The
+ * production profile is this plus shipped domain sections.
+ */
+declare function baselineProfile(args: {
+  role: string;
+  environment?: string;
+  toolConventions?: string;
+  skills?: ProfileSkill[];
+}): PromptProfile;
+/**
+ * Baseline from one of the strong generic roles (`'engineer' | 'researcher' |
+ * 'generalist'`) — the common case: pick a role foundation, optionally override
+ * the environment to describe THIS product's sandbox, then layer domain via
+ * `prodProfile`. Domain guidance stays in the product repo; this only supplies
+ * the generically-useful role + stock scaffolding.
+ */
+declare function baselineProfileFromRole(role: BaselineRoleKey, args?: {
+  environment?: string;
+  toolConventions?: string;
+  skills?: ProfileSkill[];
+}): PromptProfile;
+/** The production profile: the baseline scaffolding plus the domain sections
+ *  shipped after self-improvement. Differs from the baseline ONLY in `domain`
+ *  (and any skills the caller layered into the baseline) — the role,
+ *  environment, and tool conventions are carried through unchanged. */
+declare function prodProfile(baseline: PromptProfile, shipped: AgentProfileSection[]): PromptProfile;
+/**
+ * Section-scoped edit — replace the body of ONE domain section by id, leaving
+ * every other section byte-identical. This is how the loop targets a single
+ * evolvable surface. Throws on an unknown section id (a patch that hits no
+ * section is a silent no-op otherwise — fail loud). Throws when the targeted
+ * section is `evolvable: false`.
+ */
+declare function applyDomainPatch(p: PromptProfile, sectionId: string, newBody: string): PromptProfile;
+/**
+ * Content hash of a single section — its loop identity. Delegates to the
+ * campaign provenance `surfaceContentHash` (the same helper the loop's
+ * provenance record uses for full surfaces), so a section hash is byte-for-byte
+ * comparable with the `sha256:`-prefixed content hashes that record carries.
+ * Two sections that render identically (same title + body) share a hash; the
+ * `id` and `evolvable` flag are excluded — they are routing metadata, not
+ * content.
+ */
+declare function sectionHash(section: AgentProfileSection): string;
+declare class BudgetBreachError extends AgentEvalError {
+  dimension: keyof BudgetSpec;
+  limit: number;
+  attempted: number;
+  constructor(dimension: keyof BudgetSpec, limit: number, attempted: number);
+}
+declare class BudgetGuard {
+  private consumed;
+  private emitter;
+  private budget;
+  private startedAt;
+  constructor(emitter: TraceEmitter, budget: BudgetSpec, now?: () => number);
+  /** Record consumption. Throws `BudgetBreachError` if any dimension exceeds its cap. */
+  charge(delta: Partial<Record<keyof BudgetSpec, number>>, spanId?: string): Promise<void>;
+  /** Convenience: advance wall-clock budget based on elapsed wall time. */
+  tickWall(nowMs: number, spanId?: string): Promise<void>;
+  get state(): Record<keyof BudgetSpec, number>;
+}
+/**
+ * ProductClient — configurable HTTP client for exercising any agent's APIs.
+ *
+ * Routes are config, not hardcoded. Each agent provides its own RouteMap.
+ *
+ * @deprecated A one-product REST client does not belong in the generic
+ * substrate. Moves to the product repo in the next major
+ * (tangle-network/agent-runtime#694); vendor it if you construct it directly.
+ */
+declare class ProductClient {
+  private baseUrl;
+  private routes;
+  private cookies;
+  private timeoutMs;
+  constructor(config: ProductClientConfig);
+  private route;
+  /**
+   * Single HTTP boundary for every JSON request. Aborts after `timeoutMs`,
+   * checks `res.ok` BEFORE parsing, and throws `${method} ${path} failed:
+   * HTTP ${status} — ${body}` on a non-ok response so a 4xx/5xx error body
+   * can never be parsed as a success shape. Callers inspect the resolved
+   * value only after a successful return.
+   */
+  private request;
+  /**
+   * Read a required collection field. A missing/non-array field is a contract
+   * violation (wrong route, drift, partial body) — surface it loud instead of
+   * masking it as a healthy empty set. A genuinely empty `[]` passes through.
+   */
+  private requireArray;
+  signup(name: string, email: string, password: string): Promise<{
+    userId: string;
+  }>;
+  login(email: string, password: string): Promise<void>;
+  createWorkspace(name: string, type?: string): Promise<string>;
+  createThread(workspaceId: string): Promise<string>;
+  chat(workspaceId: string, threadId: string, content: string, _opts?: {
+    blockPatterns?: RegExp[];
+  }): Promise<{
+    text: string;
+    blocks: {
+      type: string;
+      title: string;
+    }[];
+  }>;
+  getTasks(workspaceId: string): Promise<{
+    id: string;
+    title: string;
+    status: string;
+    priority: string;
+  }[]>;
+  getEvents(workspaceId: string): Promise<{
+    id: string;
+    title: string;
+    type: string;
+  }[]>;
+  getApprovals(workspaceId: string): Promise<{
+    id: string;
+    title: string;
+    status: string;
+    type: string;
+  }[]>;
+  getVaultTree(workspaceId: string): Promise<string[]>;
+  approveAction(workspaceId: string, id: string): Promise<void>;
+  rejectAction(workspaceId: string, id: string, reason: string): Promise<void>;
+  getGenerations(workspaceId: string): Promise<{
+    id: string;
+    type: string;
+    prompt: string;
+  }[]>;
+  /** Generic GET for custom routes */
+  get(path: string): Promise<Record<string, unknown>>;
+  /** Generic POST for custom routes */
+  post(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Generic PATCH for custom routes */
+  patch(path: string, body: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+declare function runAgentControlLoop<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(config: ControlRuntimeConfig<TState, TAction, TActionResult, TEval>): Promise<ControlRunResult<TState, TAction, TActionResult, TEval>>;
+declare function objectiveEval(input: Omit<ControlEvalResult, 'objective'>): ControlEvalResult;
+declare function subjectiveEval(input: Omit<ControlEvalResult, 'objective'>): ControlEvalResult;
+interface ScoreKnowledgeReadinessOptions {
+  taskId: string;
+  requirements: KnowledgeRequirement[];
+  evidenceIds?: string[];
+  claimIds?: string[];
+  wikiPageIds?: string[];
+  userAnswers?: Record<string, string>;
+  metadata?: Record<string, unknown>;
+  now?: Date;
+}
+declare function scoreKnowledgeReadiness(options: ScoreKnowledgeReadinessOptions): KnowledgeReadinessReport;
+declare function blockingKnowledgeEval(report: KnowledgeReadinessReport, options?: {
+  id?: string;
+  minimumScore?: number;
+  emitter?: TraceEmitter;
+}): ControlEvalResult;
+declare function knowledgeReadinessTracePayload(report: KnowledgeReadinessReport, options?: {
+  passed?: boolean;
+  minimumScore?: number;
+}): Record<string, unknown>;
+declare function userQuestionsForKnowledgeGaps(gaps: KnowledgeRequirement[]): UserQuestion[];
+declare function acquisitionPlansForKnowledgeGaps(gaps: KnowledgeRequirement[]): DataAcquisitionPlan[];
+interface TokenPrice {
+  input: number;
+  output: number;
+}
+/** Per-1K token pricing for exact model ids. */
+declare const MODEL_PRICING: Record<string, TokenPrice>;
+/** Resolve pricing for a model id: exact table, then family fallback.
+ *  Returns null when the id matches nothing (caller decides — never a
+ *  silent-zero masquerading as a real $0 cost). */
+declare function resolveModelPricing(model: string): TokenPrice | null;
+/** True when `model` has known pricing (exact or family). Lets cost-aware
+ *  callers distinguish a real $0 from an unpriced model. */
+declare function isModelPriced(model: string): boolean;
+/** Estimate token count from string length (chars / 4 approximation) */
+declare function estimateTokens(text: string): number;
+/** Calculate cost in USD from token counts and model. Unknown models warn
+ *  once (not a silent zero) and return 0 so callers that ignore pricing keep
+ *  working; cost-sensitive callers should gate on {@link isModelPriced}. */
+declare function estimateCost(inputTokens: number, outputTokens: number, model: string): number;
+interface AntiSlopConfig {
+  /** Domain label — appears in the DimensionJudgeScore output */
+  domain?: string;
+  /** Case-insensitive substrings that must not appear. Each occurrence = penalty. */
+  bannedPhrases?: string[];
+  /** Regexes matching opening formulas to penalize (e.g. /^great question/i). */
+  bannedOpenings?: RegExp[];
+  /** Regexes matching hedges (e.g. /i could be wrong/i). Ratio of hedged sentences drives score. */
+  hedgingPatterns?: RegExp[];
+  /** Regexes matching apology padding. */
+  apologyPatterns?: RegExp[];
+  /** Fraction of sentences that can be duplicates before penalty (default 0.15 = 15%). */
+  repetitionThreshold?: number;
+  /** Min output length in chars; below this the turn is deemed too terse. */
+  minLength?: number;
+  /** Max output length in chars; above this the turn is deemed too verbose. */
+  maxLength?: number;
+  /** How heavily each violation class reduces the score (default 1). */
+  penaltyWeights?: Partial<Record<SlopCategory, number>>;
+}
+type SlopCategory = 'banned_phrase' | 'banned_opening' | 'hedging' | 'apology' | 'repetition' | 'length';
+/** Create a reusable Judge function from an anti-slop config. */
+declare function createAntiSlopJudge(config?: AntiSlopConfig): JudgeFn;
+interface AntiSlopIssue {
+  category: SlopCategory;
+  detail: string;
+  example?: string;
+}
+interface AntiSlopReport {
+  /** 0–10 score; 10 is clean, lower values mean more slop. */
+  score: number;
+  issues: AntiSlopIssue[];
+  /** Count of each category for programmatic aggregation. */
+  counts: Record<SlopCategory, number>;
+}
+/**
+ * Pure function — analyze one or more outputs against the config. Exposed
+ * separately so consumers can build their own reporters on top.
+ */
+declare function analyzeAntiSlop(outputs: string[], config: Omit<Required<AntiSlopConfig>, 'domain'> & {
+  penaltyWeights: Record<SlopCategory, number>;
+}): AntiSlopReport;
+declare function assertHttpOk(name: string, res: Response): HarnessAssertion;
+declare function assertStatus(name: string, actual: string, expected: string | string[]): HarnessAssertion;
+declare function assertExists(name: string, value: unknown): HarnessAssertion;
+declare function assertLatencyUnder(name: string, actualMs: number, targetMs: number): HarnessAssertion;
+declare function assertContains(name: string, actual: string, expected: string): HarnessAssertion;
+declare function assertNotContains(name: string, actual: string, forbidden: string): HarnessAssertion;
+declare function assertEventCount(name: string, count: number, min: number, max?: number): HarnessAssertion;
+declare function assertHasField(name: string, obj: Record<string, unknown>, field: string): HarnessAssertion;
+export { KeywordConceptSpec as $, PolicyEditCandidateRecord as $i, TrialTrace as $n, exportProductBenchmark as $r, ArgumentCheck as $t, contentHash as A, summarizeDistribution as Aa, DetectorSignal as Ai, SteeringOptimizationResult as An, localCommandRunner as Ar, assertNoHiddenLeak as At, PairedPromotionPowerOptions as B, costForTokenPricing as Ba, ScenarioCost as Bi, PromptHandle as Bn, RuntimeTrajectoryEvidenceSummary as Br, CanaryLeak as Bt, runAgentControlLoop as C, CliffsMagnitude as Ca, UserQuestion as Ci, recordRuns as Cn, DiscoverPersonasOptions as Cr, FieldDestination as Ct, index_d_exports as D, pairedCohensDz as Da, ExtractResult as Di, CounterfactualResult as Dn, DirEntry as Dr, JudgeScoreInput as Dt, BudgetGuard as E, interpretCliffs as Ea, ExtractOptions as Ei, CounterfactualMutation as En, CommandRunner as Er, HiddenLeak as Et, gateTreatmentApplied as F, LlmResponseError as Fa, observeAll as Fi, clamp01 as Fn, ActiveLearningOptions as Fr, ViteDeployRunnerInput as Ft, pairedPromotionPower as G, TaskHeadroom as Gi, seatPresets as Gn, ProductBenchmarkManifest as Gr, ContractLintFinding as Gt, PairedValueLaw as H, CostAccountingIncompleteError as Ha, CapabilityHeadroomOptions as Hi, hashContent as Hn, RuntimeTrajectoryRecord as Hr, ActionExecutionPolicy as Ht, PairedPromotionAlternative as I, costReceiptFromLlm as Ia, repeatedActionDetector as Ii, SteeringBundle as In, SynthesisTarget as Ir, WranglerDeployRunnerInput as It, OracleObservation as J, FindingToPolicyEditOptions as Ji, preflightModels as Jn, assertProductBenchmarkRun as Jr, lintTraceContractSpec as Jt, requiredPairsForPairedPromotion as K, assertCapabilityHeadroom as Ki, ModelEndpointCheck as Kn, ProductBenchmarkSplit as Kr, TraceContractSpec as Kt, PairedPromotionAlternativeCell as L, costReceiptFromLlmError as La, CostEntry as Li, ReferenceReplayCaseRun as Ln, proposeSynthesisTargets as Lr, deployGateLayer as Lt, TreatmentGate as M, isTransientLlmError as Ma, RepeatedActionOptions as Mi, RunScore as Mn, BoundedProcessResult as Mr, DeployGateLayerInput as Mt, TreatmentGateInput as N, stripFencedJson as Na, StreamingDetector as Ni, RunScoreWeights as Nn, DEFAULT_BOUNDED_PROCESS_TIMEOUT_MS as Nr, DeployRunResult as Nt, VerdictCacheStore as O, SampleDistribution as Oa, extractErrorCount as Oi, CounterfactualRunner as On, RunCommandInput as Or, NoLeakOptions as Ot, TreatmentGateOptions as P, LlmCallError as Pa, errorStreakDetector as Pi, aggregateRunScore as Pn, runBoundedProcess as Pr, DeployRunner as Pt, jsonShape as Q, PolicyEditAxis as Qi, ReflectionProposal as Qn, ProductBenchmarkSingleRunExportOptions as Qr, traceContract as Qt, PairedPromotionCallRates as R, maximumChargeForLlmRequest as Ra, CostSummary as Ri, ReferenceReplayRun as Rn, ProjectRuntimeTrajectoryEvidenceOptions as Rr, viteDeployRunner as Rt, subjectiveEval as S, twoByTwoPValue as Sa, KnowledgeSensitivity as Si, loadScorecard as Sn, ImprovementVerdictResult as Sr, BlendWeights as St, BudgetBreachError as T, cohensD as Ta, ErrorCountPattern as Ti, CounterfactualContext as Tn, discoverPersonas as Tr, HiddenGradeResult as Tt, RequiredPairsForPairedPromotionOptions as U, CostCeilingReachedError as Ua, CapabilityHeadroomResult as Ui, ModelSeats as Un, RuntimeTrajectoryRunRecord as Ur, ActionPolicyDecision as Ut, PairedPromotionPowerResult as V, costForUsage as Va, AssertCapabilityHeadroomOptions as Vi, PromptRegistry as Vn, RuntimeTrajectoryHookEvent as Vr, checkCanaries as Vt, RequiredPairsForPairedPromotionResult as W, HeadroomInput as Wi, resolveSeat as Wn, projectRuntimeTrajectoryEvidence as Wr, evaluateActionPolicy as Wt, OracleResult as X, PolicyEditAdmission as Xi, jsonlRunRecordBackend as Xn, ProductBenchmarkExportOptions as Xr, checkTraceContracts as Xt, OracleReport as Y, PolicyEdit as Yi, RunRecordBackend as Yn, readProductBenchmarkManifest as Yr, explainTraceContract as Yt, evaluateOracles as Z, PolicyEditAdmissionOptions as Zi, ReflectionContext as Zn, ProductBenchmarkExportResult as Zr, evaluateTraceContract as Zt, blockingKnowledgeEval as _, chiSquaredPValue as _a, KnowledgeFreshness as _i, ScorecardDiff as _n, jsonlReviewStore as _r, AssertSingleBackendOptions as _t, assertHttpOk as a, PolicyEditRisk as aa, TrainSelectionTestPartition as ai, ContractStatus as an, ProposeOutput as ar, EnsembleJudgeOptions as at, userQuestionsForKnowledgeGaps as b, normalTwoSidedPValue as ba, KnowledgeRequirement as bi, diffScorecard as bn, ExperimentStats as br, SingleBackendReport as bt, assertStatus as c, PolicyEditTarget as ca, PairedDeltaTestResult as ci, RetryWrite as cn, Review as cr, JudgeRetryPolicy as ct, MODEL_PRICING as d, SampleSummary as da, LeaderboardOptions as di, CellVerdict as dn, ReviewMemoryEntry as dr, JudgeVerdict as dt, PolicyEditChange as ea, exportProductBenchmarkRuns as ei, ContractCheckResult as en, buildReflectionPrompt as er, KeywordCoverageFinding as et, estimateCost as f, SampleSummaryOptions as fa, LeaderboardRow as fi, DiffScorecardOptions as fn, ReviewMemoryStore as fr, aggregateJudgeVerdicts as ft, acquisitionPlansForKnowledgeGaps as g, chiSquared as ga, KnowledgeBundle as gi, ScorecardCellDiff as gn, inMemoryReviewStore as gr, runIntentMatchJudge as gt, resolveModelPricing as h, LinearRegressionResult as ha, KnowledgeAcquisitionMode as hi, ScorecardCell as hn, createLlmReviewer as hr, IntentMatchResult as ht, assertHasField as i, PolicyEditInit as ia, TrainSelectionTestOptions as ii, ContractSpan as in, ProposeInput as ir, runKeywordCoverageJudgeUrl as it, fileVerdictCache as j, rocAuc as ja, ErrorStreakOptions as ji, SteeringOptimizationRow as jn, BoundedProcessInput as jr, blendHeldout as jt, canonicalJson as k, percentileNearestRank as ka, DetectorEvent as ki, PairwiseSteeringOptimizer as kn, RunCommandResult as kr, RoutedField as kt, analyzeAntiSlop as l, PolicyEditTargetSurface as la, minimumPairsForPairedDeltaTest as li, SpanPredicate as ln, ReviewFn as lr, withJudgeRetry as lt, isModelPriced as m, summarizeSample as ma, DataAcquisitionPlan as mi, Scorecard as mn, VerifyFn as mr, IntentMatchOptions as mt, assertEventCount as n, PolicyEditGainDirection as na, HeldOutPartition as ni, ContractRuleExecution as nn, LlmReviewerConfig as nr, KeywordCoverageResult as nt, assertLatencyUnder as o, PolicyEditSchemaVersion as oa, partitionHeldOut as oi, ContractVerdict as on, ProposeReviewConfig as or, ensembleJudge as ot, estimateTokens as p, sampleMedian as pa, leaderboard as pi, RecordRunsOptions as pn, Verification as pr, IntentMatchInput as pt, Oracle as q, capabilityHeadroom as qi, ModelEndpointRequest as qn, ProductBenchmarkValidationReport as qr, compileTraceContractSpec as qt, assertExists as r, PolicyEditGainUnit as ra, PartitionHeldOutOptions as ri, ContractRun as rn, ProposeFn as rr, runKeywordCoverageJudge as rt, assertNotContains as s, PolicyEditSource as sa, PairedDeltaTestOptions as si, OrderMode as sn, ProposeReviewReport as sr, JudgeRetryOutcome as st, assertContains as t, PolicyEditExpectedGain as ta, productBenchmarkRepoIdentity as ti, ContractRule as tn, parseReflectionResponse as tr, KeywordCoverageOptions as tt, createAntiSlopJudge as u, makePolicyEditCandidateRecord as ua, pairedDeltaTest as ui, TraceContract as un, ReviewInput as ur, EnsembleAggregate as ut, knowledgeReadinessTracePayload as v, fisherExactTwoSided as va, KnowledgeImportance as vi, ScorecardEntry as vn, runProposeReview as vr, BackendDescriptor as vt, ProductClient as w, cliffsDelta as wa, ERROR_COUNT_PATTERNS as wi, recordRunsToScorecard as wn, DiscoveredPersona as wr, HiddenCriteriaGrader as wt, objectiveEval as x, studentTTwoSidedPValue as xa, KnowledgeRequirementCategory as xi, formatScorecardDiff as xn, ImprovementThresholds as xr, assertSingleBackend as xt, scoreKnowledgeReadiness as y, linearRegressionSlope as ya, KnowledgeReadinessReport as yi, ScorecardLogLine as yn, ExperimentRep as yr, SingleBackendDivergence as yt, PairedPromotionPowerCall as z, CostResult as za, CostTracker as zi, ReferenceReplaySplit as zn, RuntimeTrajectoryEvidenceProjection as zr, wranglerDeployRunner as zt };
+//# sourceMappingURL=index-D4lT7aFu.d.ts.map