@tangle-network/agent-eval 0.173.3 → 0.175.0

package/dist/statistical-heldout-Cqb73yE9.d.ts

@@ -0,0 +1,1127 @@
+import { a as RunRecord } from "./run-record-DTv1MdjK.js";
+import { a as PairedPromotionDecision, d as PairedBootstrapResult, i as PairedMcNemarEvidence, r as PairedDecisionStatistic, t as PairedDecisionMethod, u as PairedBootstrapOptions } from "./paired-promotion-decision-CGzg0cI_.js";
+import { R as Scenario, b as GenerationRecord, h as GateContext, p as Gate, v as GateResult, w as JudgeScore } from "./types-BJz2CPTM.js";
+//#region src/statistics/paired-binary.d.ts
+/** A binomial proportion estimate with a confidence interval. */
+interface ProportionInterval {
+  /** Point estimate successes / n (0 when n = 0). */
+  estimate: number;
+  /** Lower bound, clamped to [0, 1]. */
+  lower: number;
+  /** Upper bound, clamped to [0, 1]. */
+  upper: number;
+}
+/**
+ * Wilson score interval for a binomial proportion. Correct at small n and near
+ * 0/1, where the normal (Wald) approximation produces bounds outside [0, 1] and
+ * understates coverage. Use this for any pass-rate / hit-rate / realness-rate
+ * CI — the continuous `confidenceInterval` assumes the wrong distribution for a
+ * proportion. `n = 0 ⇒ {0, 0, 0}`.
+ */
+declare function wilson(successes: number, n: number, confidence?: number): ProportionInterval;
+/**
+ * Are these per-item outcomes binary (every value exactly 0 or 1)?
+ *
+ * The discriminator a promotion gate needs before choosing a paired statistic.
+ * On binary outcomes the paired delta vector lives in {-1, 0, +1} and is
+ * normally dominated by zeros (both arms solve, or both arms miss, most items),
+ * so its MEDIAN is pinned at exactly 0 no matter how large the real shift in
+ * success rate is — and a bootstrap CI on that median collapses to [0, 0].
+ * A gate keying on `ci.low > threshold` is then structurally unable to see
+ * either a gain or a regression. Detect this shape and switch to the
+ * paired-binary estimators ({@link mcnemar}, {@link pairedRiskDifference})
+ * instead of silently answering "no" forever.
+ *
+ * Empty input is NOT binary: there is no evidence of the outcome's shape, and
+ * defaulting an empty vector into the binary branch would pick a statistic on
+ * no data at all.
+ *
+ * NOT the right discriminator for a gate. It recognises the literal {0, 1}
+ * encoding and nothing else, so a pass/fail dimension emitted on 0-100 — which
+ * judges in this codebase do routinely — reads as non-binary, and a single
+ * partial-credit score in an otherwise pass/fail vector flips it to false while
+ * leaving the median just as blind. Gates want {@link pairedBinaryScale} (any
+ * two-point encoding). This predicate remains for callers that specifically
+ * mean "literally 0/1".
+ */
+declare function isBinaryOutcomeVector(values: ArrayLike<number>): boolean;
+/** Result of a McNemar paired-binary significance test. */
+interface McNemarResult {
+  /** Total paired observations. */
+  n: number;
+  /** Discordant pairs (b + c) — the only ones that carry signal. */
+  nDiscordant: number;
+  /** Pairs where treatment succeeded and control failed ("newly correct"). */
+  b: number;
+  /** Pairs where control succeeded and treatment failed ("newly wrong"). */
+  c: number;
+  /** Continuity-corrected chi-square statistic (reference; exact p drives the call). */
+  statistic: number;
+  /** Two-sided p-value. Exact (binomial sign test on discordant pairs). */
+  pValue: number;
+}
+/**
+ * McNemar's test for paired binary outcomes — the correct significance test for
+ * "does treatment change the success rate vs control on the SAME items". Only
+ * discordant pairs (one arm right, the other wrong) carry information; concordant
+ * pairs are uninformative, so a paired t-test / two-proportion z-test on the raw
+ * rates is wrong here. The p-value is exact: under H0 the b "treatment-wins" are
+ * Binomial(b + c, 0.5), so the two-sided p is the doubled binomial tail — correct
+ * at the small discordant counts typical of eval runs (no continuity-corrected
+ * chi-square approximation needed, though it is returned as `statistic` for
+ * reference). Inputs are paired 0/1 (or boolean) arrays, control first to match
+ * the module's (before, after) convention. Throws on unequal lengths.
+ */
+declare function mcnemar(control: ArrayLike<number | boolean>, treatment: ArrayLike<number | boolean>): McNemarResult;
+/** A paired binary effect size (treatment rate − control rate) with a CI. */
+interface RiskDifferenceResult {
+  /** Total paired observations. */
+  n: number;
+  /** Discordant pairs: treatment-win count. */
+  b: number;
+  /** Discordant pairs: control-win count. */
+  c: number;
+  /** Paired risk difference p(treatment) − p(control) = (b − c) / n. */
+  riskDifference: number;
+  /** Lower bound of the CI, clamped to [-1, 1]. */
+  lower: number;
+  /** Upper bound of the CI, clamped to [-1, 1]. */
+  upper: number;
+  /** Confidence level used. */
+  confidence: number;
+}
+/**
+ * Paired risk difference (the effect-size companion to {@link mcnemar}): the
+ * change in success rate p(treatment) − p(control) on matched items, which for
+ * paired binary data equals (b − c) / n. The CI uses the paired variance from
+ * the discordant counts, not the independent-samples formula (which overstates
+ * the interval by ignoring the pairing). Inputs are paired 0/1 (or boolean)
+ * arrays, control first. Throws on unequal lengths.
+ *
+ * REPORTING ONLY — do NOT decide a promotion on this interval. The CI is a Wald
+ * normal approximation, which badly UNDERCOVERS when only a handful of pairs are
+ * discordant: at n = 3 with b = 2, c = 0 it returns [0.133, 1.000], excluding 0,
+ * while McNemar's exact test on the same data gives p = 0.50. A gate keying on
+ * `lower > 0` would promote noise. Use {@link pairedRiskDifferenceExact}, whose
+ * interval is dual to the exact test by construction, for any decision.
+ */
+declare function pairedRiskDifference(control: ArrayLike<number | boolean>, treatment: ArrayLike<number | boolean>, confidence?: number): RiskDifferenceResult;
+/** A paired binary effect size with an EXACT interval and the exact test that
+ *  bounds it — one object so a caller cannot read the estimate without the
+ *  significance it is entitled to. */
+interface ExactRiskDifferenceResult {
+  /** Total paired observations. */
+  n: number;
+  /** Discordant pairs: treatment-win count. */
+  b: number;
+  /** Discordant pairs: control-win count. */
+  c: number;
+  /** Discordant pairs (b + c) — the only ones carrying information. */
+  nDiscordant: number;
+  /** Paired risk difference p(treatment) − p(control) = (b − c) / n. */
+  riskDifference: number;
+  /** Exact conditional CI lower bound. 0 when there are no discordant pairs. */
+  lower: number;
+  /** Exact conditional CI upper bound. 0 when there are no discordant pairs. */
+  upper: number;
+  /** Confidence level used. */
+  confidence: number;
+  /** McNemar's exact two-sided p-value on the same discordant counts. */
+  pValue: number;
+}
+/**
+ * Paired risk difference with the EXACT CONDITIONAL interval — the estimator a
+ * promotion gate may decide on.
+ *
+ * Conditional on the number of discordant pairs m = b + c, the treatment-win
+ * count b is Binomial(m, π) with π = P(treatment wins | discordant), and the
+ * risk difference is an exact reparameterisation: RD = (2π − 1)·m/n. So a
+ * Clopper-Pearson exact interval for π maps straight onto RD. This buys the
+ * property the Wald interval in {@link pairedRiskDifference} does not have:
+ *
+ *   **`lower > 0` ⟺ McNemar's exact test rejects at α = 1 − confidence.**
+ *
+ * Clopper-Pearson excludes π = 0.5 exactly when the two-sided exact binomial
+ * test of π = 0.5 rejects, and that test IS {@link mcnemar}'s p-value — so the
+ * interval and the test can never disagree, and a gate keyed on `lower` cannot
+ * promote what the exact test refuses. The exact p is returned in the same
+ * object so the two are impossible to compute apart.
+ *
+ * The interval is conservative (exact intervals over-cover; conditioning on m
+ * discards the concordant pairs' information about m itself). That is the
+ * correct direction for a promotion gate: it refuses more often, never less.
+ *
+ * With m = 0 there are no discordant pairs and π is not identified: the result
+ * is the degenerate [0, 0] with p = 1. That is NOT evidence of equivalence —
+ * callers must treat a zero-width interval as "cannot decide", not as "no
+ * difference". Inputs are paired 0/1 (or boolean) arrays, control first.
+ * Throws on unequal lengths.
+ */
+declare function pairedRiskDifferenceExact(control: ArrayLike<number | boolean>, treatment: ArrayLike<number | boolean>, confidence?: number): ExactRiskDifferenceResult;
+/** A paired binary effect size with an interval that is valid at a NONZERO
+ *  margin — the estimator a noninferiority decision may be made on. */
+interface ScoreRiskDifferenceResult {
+  /** Total paired observations. */
+  n: number;
+  /** Discordant pairs: treatment-win count. */
+  b: number;
+  /** Discordant pairs: control-win count. */
+  c: number;
+  /** Discordant pairs (b + c). */
+  nDiscordant: number;
+  /** Paired risk difference p(treatment) − p(control) = (b − c) / n. */
+  riskDifference: number;
+  /** Score-interval lower bound on the population risk difference. */
+  lower: number;
+  /** Score-interval upper bound on the population risk difference. */
+  upper: number;
+  /** Confidence level used. */
+  confidence: number;
+}
+/**
+ * Paired risk difference with TANGO'S (1998) SCORE INTERVAL — the estimator a
+ * promotion gate may decide on **at a nonzero margin**.
+ *
+ * {@link pairedRiskDifferenceExact} conditions on the observed discordant count
+ * `m = b + c`, builds a Clopper-Pearson interval for the win share among those
+ * `m` pairs, and multiplies by the observed `m/n`. That is exact for testing
+ * RD = 0 — it is dual to McNemar — but it is NOT a confidence interval for the
+ * population risk difference at a nonzero margin, because the sampling
+ * variability of `m/n` itself is discarded. The gap is not academic: with the
+ * production caller's `pairedDeltaThreshold: -0.05`, a process whose true risk
+ * difference sits exactly on that margin clears a nominal-95 % `lower > margin`
+ * check 24.75 % of the time at n = 40 and 43.95 % at n = 76 (2000 replicates
+ * each) when the conditional interval decides.
+ *
+ * Tango's interval inverts the score test of RD = delta, which estimates the
+ * nuisance loss rate under each hypothesised delta instead of fixing it at the
+ * observed value, so `m` contributes its own uncertainty. It is the method
+ * `ratesci::scorepairci` uses for paired risk-difference noninferiority, and it
+ * is not conditional, so it stays valid as the margin moves away from zero.
+ *
+ * The bounds are found by bisecting `tangoScore(delta) = ±z` — the score is
+ * monotone decreasing in delta, so each crossing is unique. Inputs are paired
+ * 0/1 (or boolean) arrays, control first. Throws on unequal lengths.
+ */
+declare function pairedRiskDifferenceScore(control: ArrayLike<number | boolean>, treatment: ArrayLike<number | boolean>, confidence?: number): ScoreRiskDifferenceResult;
+/**
+ * The common positive level `s` such that EVERY value across both paired arms is
+ * exactly 0 or `s` — i.e. the outcome is pass/fail, whatever encoding it arrived
+ * in. Returns null when the outcomes are not two-point, when the two arms use
+ * different levels, or when no positive value was observed at all (all-zero
+ * arms: the level is not identified, and there is nothing to decide anyway).
+ *
+ * This is the scale-aware successor to {@link isBinaryOutcomeVector}, which only
+ * recognises literal {0, 1}. Judges in this codebase emit dimensions on 0-100 as
+ * well as [0,1] (see `detectScale` in `campaign/gates/statistical-heldout.ts`),
+ * so a pass/fail dimension routinely arrives as {0, 100} and a {0,1}-only test
+ * silently sends it down the median path that cannot see it. Any positive level
+ * is accepted, not just 1 and 100: for a two-point {0, s} outcome the mean paired
+ * delta is exactly s·(b − c)/n, so the binary estimators apply after dividing by
+ * s and rescaling the result back into the caller's native units.
+ *
+ * Non-finite values ⇒ null: an unusable outcome must not be classified as a
+ * clean pass/fail shape.
+ */
+declare function pairedBinaryScale(before: ArrayLike<number>, after: ArrayLike<number>): number | null;
+/**
+ * Unbiased pass@k for code generation (Chen et al. 2021, "Evaluating Large
+ * Language Models Trained on Code"). Given `n` independent samples for one
+ * problem of which `c` pass, the probability that at least one of a random k of
+ * them passes is 1 − C(n−c, k) / C(n, k). Estimating pass@k as "did any of the
+ * first k pass" is biased high at small n; this is the variance-reduced estimator
+ * averaged implicitly over all k-subsets. Average the per-problem values across
+ * the suite for the corpus pass@k. Computed in the numerically stable product
+ * form. Requires 1 ≤ k ≤ n and 0 ≤ c ≤ n.
+ */
+declare function passAtK(n: number, c: number, k: number): number;
+//#endregion
+//#region src/statistics/sequential-eprocess.d.ts
+interface EProcessOptions {
+  /** Type-I error budget. The process decides when wealth ≥ 1/alpha
+   *  (Ville's inequality). Default 0.05. */
+  alpha?: number;
+  /** Truncation bound on the predictable bet λ ∈ [0, maxBet]. Must satisfy
+   *  maxBet < 1/nullMean so every wealth factor stays strictly positive.
+   *  Default 0.5. */
+  maxBet?: number;
+  /** The null boundary m₀ for H0: E[x] ≤ m₀ on x ∈ [0,1]. Default 0.5
+   *  (the paired-delta encoding x = (d+1)/2 maps "no effect" to 1/2).
+   *  A pre-registered minEffect shifts this — see `sequentialPairedGate`. */
+  nullMean?: number;
+  /** Continue a process from a `state()` snapshot taken before a restart.
+   *  The snapshot never supplies the parameters: `alpha`, `maxBet`, and
+   *  `nullMean` resolve from this options object exactly as for a fresh
+   *  process, and a snapshot recorded under different parameters is refused
+   *  (`ValidationError`) — re-deciding the same stream under new parameters
+   *  would reopen optional stopping. A snapshot whose fields are not
+   *  mutually consistent (tampered or truncated) is refused the same way. */
+  resume?: EProcessState;
+}
+interface EProcessStep {
+  /** Current wealth W_n — the e-value against H0 after n observations. */
+  wealth: number;
+  /** Observations consumed so far. */
+  n: number;
+  /** True from the first n where W_n ≥ 1/alpha onward (sticky). */
+  decided: boolean;
+}
+/**
+ * Complete snapshot of an e-process. Together with the parameters it is
+ * sufficient to continue the process after a restart: `sumX` and `varSum`
+ * are the running sums the next bet is computed from, so a process rebuilt
+ * from a snapshot produces the same wealth sequence and decision as one that
+ * was never interrupted. Plain data: a JSON round-trip preserves it
+ * (`decidedAtN` is undefined, and therefore omitted, until decided).
+ */
+interface EProcessState extends EProcessStep {
+  alpha: number;
+  maxBet: number;
+  nullMean: number;
+  /** The decision boundary 1/alpha. */
+  threshold: number;
+  /** Observation count at the first threshold crossing; undefined until decided. */
+  decidedAtN?: number;
+  /** Σ x_i over the n observations consumed. */
+  sumX: number;
+  /** Σ (x_i − μ̂_i)² over the n observations consumed, μ̂_i the shrunk running
+   *  mean after observation i. */
+  varSum: number;
+}
+interface EProcess {
+  /** Consume one observation x ∈ [0,1]. Throws on non-finite / out-of-range
+   *  input — a silent clamp would corrupt the type-I guarantee. */
+  update(x: number): EProcessStep;
+  state(): EProcessState;
+}
+/**
+ * Betting test-martingale for bounded observations — the e-process core of
+ * anytime-valid sequential testing (Waudby-Smith & Ramdas, "Estimating means
+ * of bounded random variables by betting", JRSS-B 2024).
+ *
+ * Observations x_i ∈ [0,1]; H0: E[x] ≤ m₀ (`nullMean`, default 1/2). Wealth
+ *
+ *   W_t = Π_{i≤t} (1 + λ_i (x_i − m₀)),  W_0 = 1
+ *
+ * with the truncated GROW-style plug-in bet computed from PRIOR observations:
+ *
+ *   λ_i = clamp((μ̂_{i−1} − m₀) / (σ̂²_{i−1} + (μ̂_{i−1} − m₀)²), 0, maxBet)
+ *
+ * where μ̂/σ̂² are the shrunk running estimates μ̂_t = (1/2 + Σx_i)/(t+1),
+ * σ̂²_t = (1/4 + Σ(x_i − μ̂_i)²)/(t+1).
+ *
+ * PREDICTABILITY INVARIANT (load-bearing): λ_i is a function of x_1..x_{i−1}
+ * ONLY — it may never see x_i. With λ_i ≥ 0 predictable, each factor has
+ * E[1 + λ_i(x_i − m₀) | past] ≤ 1 under H0, so W is a nonnegative
+ * supermartingale and Ville's inequality gives P(∃t: W_t ≥ 1/α) ≤ α — the
+ * type-I guarantee holds at ANY data-dependent stopping time. λ_1 is always 0
+ * (no prior evidence), so the first observation never moves wealth.
+ *
+ * `decided` latches at the first crossing W_t ≥ 1/α and never un-latches;
+ * wealth keeps updating after the crossing (the e-process remains valid), but
+ * the decision time is the first crossing.
+ */
+declare function eProcess(opts?: EProcessOptions): EProcess;
+//#endregion
+//#region src/pareto.d.ts
+/**
+ * Pareto frontier — multi-objective optimization over candidate runs.
+ *
+ * Lifted from ADC pareto.ts and blueprint-agent frontier.ts. When you're
+ * trading off (cost, latency, quality) or (passRate, tokenBudget,
+ * ttfb), you rarely have a single "winner" — you have a set of
+ * non-dominated candidates. This module exposes:
+ *
+ *   - `paretoFrontier`: filter a set of candidates to the non-dominated ones
+ *   - `dominates`: does A dominate B across all objectives?
+ *
+ * Each objective is declared with a direction: 'maximize' (higher=better)
+ * or 'minimize' (lower=better). Candidates are any object; pass an
+ * `objective(candidate)` accessor.
+ */
+type Direction = 'maximize' | 'minimize';
+interface Objective<T> {
+  /** Stable label used in reports. */
+  name: string;
+  direction: Direction;
+  value: (candidate: T) => number;
+}
+interface ParetoResult<T> {
+  frontier: T[];
+  dominated: T[];
+  /** Index map: frontier[i] dominates each of dominatedBy[i]. */
+  dominanceMap: Array<{
+    dominator: T;
+    dominated: T[];
+  }>;
+}
+/** Does candidate A weakly dominate B — strictly better on at least one objective and no worse on any? */
+declare function dominates<T>(a: T, b: T, objectives: Objective<T>[]): boolean;
+/**
+ * Compute the non-dominated frontier. Candidates with NaN/Infinity on any
+ * objective are excluded (can't rank them). A candidate enters the frontier
+ * iff no other candidate dominates it.
+ */
+declare function paretoFrontier<T>(candidates: T[], objectives: Objective<T>[]): ParetoResult<T>;
+//#endregion
+//#region src/campaign/gates/promotion-policy.d.ts
+/** Where an objective's per-cell scalar comes from. `composite` reads the
+ *  judge's composite; `dimension` reads a named per-dimension score. */
+type ObjectiveSource = {
+  kind: 'composite';
+} | {
+  kind: 'dimension';
+  dimension: string;
+};
+interface PromotionObjective {
+  /** Stable label used in reports + `contributingGates`. */
+  name: string;
+  source: ObjectiveSource;
+  /** 'maximize' (quality dims) or 'minimize' (error/risk/length dims). Orients
+   *  the paired delta so a positive bootstrap always means "candidate better". */
+  direction: Direction;
+  /** The good-direction paired-delta CI lower bound must EXCEED this to count
+   *  as a significant gain on this axis. Interpreted in the judge's native
+   *  scale. Default 0 (⇒ "confidently better"). */
+  gainThreshold?: number;
+  /** A floor breach (regression) is declared when the good-direction CI lower
+   *  bound is below −floorTolerance, or when the exact small-sample test proves
+   *  a drop past it. When omitted it auto-scales off observed magnitudes
+   *  (0.05 on [0,1], 5 on 0-100), matching `dimensionRegressions`. */
+  floorTolerance?: number;
+}
+/** Per-axis verdict from the good-direction paired bootstrap. */
+type AxisVerdict = 'improved' | 'regressed' | 'flat' | 'few_runs';
+interface AxisEvidence {
+  name: string;
+  source: ObjectiveSource;
+  direction: Direction;
+  /** Paired bootstrap on the GOOD-DIRECTION delta (oriented by `direction`):
+   *  a positive value means the candidate is better on this axis.
+   *
+   *  DIAGNOSTIC on a pass/fail axis: there the verdict is decided on Tango's
+   *  score interval instead, because a percentile bootstrap over a three-atom
+   *  delta lattice is not a valid interval at the nonzero margin `floorTolerance`
+   *  and `gainThreshold` create. `ci` carries the interval that decided. */
+  bootstrap: PairedBootstrapResult;
+  /** Which paired statistic `bootstrap.low`/`.high` bracket. `'mean'` unless the
+   *  caller asked for the median — on a pass/fail axis the median and its whole
+   *  CI are pinned at 0 by tie domination and can see neither a gain nor a
+   *  regression. `bootstrap.median` still carries the median point estimate. */
+  bootstrapStatistic: 'median' | 'mean';
+  /** The interval the axis verdict was actually decided on, good-direction and
+   *  in the axis's native units. */
+  ci: {
+    low: number;
+    high: number;
+  };
+  /** Which estimator produced `ci`. */
+  decisionStatistic: PairedDecisionStatistic;
+  /** McNemar's exact evidence on a pass/fail axis; null otherwise. */
+  mcnemar: PairedMcNemarEvidence | null;
+  /** `ci` has zero width — no evidence in either direction, so the axis is
+   *  neither improved nor regressed however the point estimate sits. */
+  indeterminate: boolean;
+  /** Paired observations contributing to this axis. */
+  n: number;
+  minimumRequired: number;
+  decisionMethod: PairedDecisionMethod;
+  gainThreshold: number;
+  floorTolerance: number;
+  verdict: AxisVerdict;
+}
+interface EvidenceVector {
+  /** One entry per objective — NOTHING averaged across axes. */
+  axes: AxisEvidence[];
+  /** Smallest paired n across axes that produced observations — the binding
+   *  evidence-sufficiency constraint. 0 when no axis produced observations. */
+  minN: number;
+  /** Aggregate per-side cost from the gate context (a constraint input, not a
+   *  CI axis — see the module header). */
+  cost: {
+    candidate: number;
+    baseline: number;
+  };
+}
+/** A promotion strategy: a pure function from the evidence vector to a verdict.
+ *  Many policies can run over the same `EvidenceVector` and disagree — that's
+ *  the point (competing strategies, shared evidence). */
+type PromotionPolicy = (ev: EvidenceVector) => GateResult;
+interface BuildEvidenceVectorOptions {
+  /** Minimum paired observations before an axis can claim significance; below
+   *  it the axis is `few_runs`. The exact small-sample test may require more
+   *  observations at the selected confidence. */
+  minProductiveRuns?: number;
+  /** Confidence level for every axis bootstrap. Default 0.95. */
+  confidence?: number;
+  /** Bootstrap resamples. Default 2000. */
+  resamples?: number;
+  /** Fixed bootstrap seed for a deterministic, reproducible verdict. Default 1337. */
+  seed?: number;
+  /** Paired statistic every axis CI is computed on. Default `'mean'` — see
+   *  {@link DECISION_PAIRED_DELTA_STATISTIC} for why the median is not. */
+  statistic?: 'mean' | 'median';
+}
+/**
+ * The Evidence Bus. For each objective, pair candidate vs baseline by full
+ * cellId and bootstrap a CI on the good-direction paired delta. Reuses the
+ * exact `pairHoldout` + `pairedBootstrap` machinery the held-out gate uses, so
+ * a single source of truth governs pairing granularity + scale handling.
+ */
+declare function buildEvidenceVector<TArtifact, TScenario extends Scenario>(ctx: GateContext<TArtifact, TScenario>, objectives: PromotionObjective[], opts?: BuildEvidenceVectorOptions): EvidenceVector;
+/**
+ * The default strategy: symmetric multi-objective Pareto significance. Ship iff
+ * the candidate weakly dominates the baseline at the confidence level — no axis
+ * credibly worse AND ≥1 axis credibly better. Floor breach on any axis → hold
+ * (anti-Goodhart, dominates everything). Insufficient evidence on any axis →
+ * need_more_work. Statistically equivalent → hold (never ship noise).
+ */
+declare const paretoPolicy: PromotionPolicy;
+interface ParetoSignificanceGateOptions extends BuildEvidenceVectorOptions {
+  /** The objective vector. Every axis is both a gain source and a safety floor. */
+  objectives: PromotionObjective[];
+  /** Strategy applied to the evidence vector. Default `paretoPolicy`. Override
+   *  to run a stricter/looser strategy over the SAME bus (competing policies). */
+  policy?: PromotionPolicy;
+  /** Override the gate name in reports. */
+  name?: string;
+}
+/**
+ * Wrap the bus + a policy as a `Gate`. Plugs into the existing
+ * `runImprovementLoop({ gate })` slot and composes via `composeGate`; default
+ * loop behavior is unchanged because consumers opt in by passing this gate.
+ */
+declare function paretoSignificanceGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(options: ParetoSignificanceGateOptions): Gate<TArtifact, TScenario>;
+//#endregion
+//#region src/campaign/gates/power-preflight.d.ts
+/**
+ * Power preflight — "can this budget detect the effect you are hunting?"
+ *
+ * The failure it prevents (measured, twice): a live prompt-improvement campaign ran
+ * 333 sandbox cells over 5.6 hours and produced a +0.08 holdout lift the ship gate
+ * (paired bootstrap, CI.low > 0.05) could not distinguish from zero — because at
+ * that holdout size and worker variance the MINIMUM DETECTABLE lift was larger than
+ * any effect a prompt change plausibly produces. The budget was spent learning what
+ * a 30-second calculation on the baseline cells already knew. No eval framework we
+ * know of surfaces this; every underpowered improvement run everywhere ends in an
+ * uninformative "hold".
+ *
+ * Model: the ship rule is `CI.low(paired Δ) > deltaThreshold`. Approximating the
+ * bootstrap CI as normal, `CI.low ≈ effect − z·sd_Δ/√n`, so the smallest shippable
+ * true effect is `MDE = deltaThreshold + z·sd_Δ/√n`. The paired-delta SD is unknown
+ * before the candidate exists; we bound it by the zero-correlation case
+ * `sd_Δ ≤ √2·sd_baseline` — a CONSERVATIVE (upper) MDE, which is the correct
+ * direction for a warning. Pairing is per cell (`scenario:rep`), so reps multiply n.
+ *
+ * Standalone by design: feed it any baseline composites (a `gate:'none'` run, a
+ * live-proof table) BEFORE budgeting the real search; `selfImprove` also attaches
+ * it to every result and warns when the run was structurally unable to ship.
+ */
+interface PowerPreflightOptions {
+  /** Per-cell baseline composites on the HOLDOUT scenarios (one per scenario:rep cell). */
+  baselineComposites: number[];
+  /** Paired observations the budgeted comparison will produce
+   *  (holdout scenarios × reps). Defaults to `baselineComposites.length`. */
+  pairedN?: number;
+  /** The ship gate's effect-size threshold. Default 0.05 (defaultProductionGate). */
+  deltaThreshold?: number;
+  /** CI confidence the gate uses. Default 0.95. */
+  confidence?: number;
+  /** True when the holdout is scored by the SAME judge/scorer family as the gate
+   *  (selfImprove's default composition — one judge scores everything). Under a
+   *  shared channel, raising paired n reduces only the IDIOSYNCRATIC noise share;
+   *  systematic judge bias is untouched, so the MDE here is a lower bound and the
+   *  only full debiaser is an independent second scoring channel
+   *  (recursive-self-improvement S1c, closed form in EXP-023 P0). Default false. */
+  sharedScorerChannel?: boolean;
+}
+interface PowerPreflight {
+  /** Paired observations the comparison will have. */
+  n: number;
+  /** Baseline per-cell composite standard deviation (the variance the effect must beat). */
+  sd: number;
+  /** Minimum detectable lift: the smallest TRUE effect the gate could ship at this budget. */
+  mde: number;
+  /** Baseline holdout composite mean. */
+  baselineMean: number;
+  /** Headroom to a perfect 1.0 composite (the largest achievable lift on a [0,1] judge). */
+  headroom: number;
+  /** True when even the largest achievable effect (headroom) is below the MDE —
+   *  the run is structurally unable to ship regardless of proposal quality.
+   *  Only asserted for [0,1]-scaled judges (see `scaleAssumed`). */
+  underpowered: boolean;
+  /** True when composites look [0,1]-scaled; headroom/underpowered are only
+   *  meaningful under that convention (0-100 judges get mde/sd/n but no verdict). */
+  scaleAssumed: boolean;
+  deltaThreshold: number;
+  confidence: number;
+  /** Set when the holdout shares the gate's scoring channel: more cells cannot
+   *  buy back systematic judge bias — treat the MDE as a lower bound. */
+  sharedChannelCaveat?: string;
+  /** One actionable sentence for humans and logs. */
+  recommendation: string;
+}
+/** Estimate the minimum detectable lift a paired-holdout improvement run can
+ *  ship at a given budget, from the baseline holdout composites — call it BEFORE
+ *  spending a search to learn whether the effect you are hunting is even
+ *  observable at this holdout size and worker variance. */
+declare function powerPreflight(opts: PowerPreflightOptions): PowerPreflight;
+//#endregion
+//#region src/paired-arms.d.ts
+/** One arm observation of one work item. Structural on purpose: callers
+ *  project their own record type (e.g. a `RunRecord`) into this shape. */
+interface PairedArmRow {
+  /** Matching key — rows sharing a `pairKey` across both arms form pairs
+   *  (typically the task/scenario/seed identity). */
+  pairKey: string;
+  /** Rep identity within a `pairKey` (e.g. a seed or rep number). Required on
+   *  every row of a `pairKey` that has more than one rep in either arm; reps
+   *  then pair only on exact (`pairKey`, `repKey`) match, never on outcome
+   *  content. Optional when each arm has at most one rep of the item. */
+  repKey?: string;
+  /** Arm label this row was produced under. */
+  arm: string;
+  /** Binary outcome; omit when the comparison has no pass/fail notion. */
+  pass?: boolean;
+  /** Named numeric measurements (score, cost, latency, …). */
+  metrics?: Record<string, number>;
+}
+interface PairArmsOptions {
+  /** Arm treated as the control side of every pair. */
+  baselineArm: string;
+  /** Arm treated as the treatment side of every pair. */
+  treatmentArm: string;
+}
+/** One matched (baseline, treatment) observation of the same work item. */
+interface MatchedPair {
+  pairKey: string;
+  /** 0-based position of this pair within its `pairKey`, ordered by sorted
+   *  `repKey` (always 0 for a single-rep item). The rep identity itself is on
+   *  the rows (`baseline.repKey` / `treatment.repKey`). */
+  repIndex: number;
+  baseline: PairedArmRow;
+  treatment: PairedArmRow;
+}
+interface PairArmsResult {
+  /** Matched pairs, ordered by (`pairKey`, `repIndex`). */
+  pairs: MatchedPair[];
+  /** Baseline rows left without a treatment counterpart — reported, never
+   *  silently dropped. */
+  unpairedBaseline: PairedArmRow[];
+  /** Treatment rows left without a baseline counterpart. */
+  unpairedTreatment: PairedArmRow[];
+}
+/**
+ * Match rows across two arms into (baseline, treatment) pairs by `pairKey`.
+ *
+ * A `pairKey` with at most one row per arm pairs directly, no `repKey`
+ * needed. A `pairKey` with multiple reps in either arm requires `repKey` on
+ * every one of its rows, and reps pair only on exact (`pairKey`, `repKey`)
+ * match — pairing is keyed purely on row identity, never on outcome content
+ * (outcome-keyed matching deflates discordant counts and biases McNemar), and
+ * is therefore independent of input order. Reps whose `repKey` has no
+ * counterpart in the other arm, and items present in only one arm, land in
+ * the unpaired lists — reported, never truncated.
+ *
+ * Fail-loud: throws when either named arm has zero rows (an unknown arm
+ * name would otherwise read as "everything unpaired"), when the two arm
+ * names are equal, when a multi-rep `pairKey` has a row without `repKey`, or
+ * when a (`pairKey`, arm) group repeats a `repKey` (the match would be
+ * ambiguous).
+ */
+declare function pairArms(rows: readonly PairedArmRow[], opts: PairArmsOptions): PairArmsResult;
+/** Paired pass/fail comparison over the pairs where BOTH sides carry `pass`. */
+interface PairedCorrectness {
+  /** Discordant pairs where the treatment passed and the baseline failed. */
+  b10: number;
+  /** Discordant pairs where the baseline passed and the treatment failed. */
+  b01: number;
+  /** Exact McNemar significance over the paired outcomes (`b === b10`, `c === b01`). */
+  mcnemar: McNemarResult;
+  /** Paired effect size: p(treatment) − p(baseline) with a paired-variance CI. */
+  riskDifference: RiskDifferenceResult;
+}
+/** Paired delta summary for one named metric (delta = treatment − baseline). */
+interface PairedMetricDelta {
+  name: string;
+  /** Pairs where BOTH sides carry a finite value for this metric. */
+  n: number;
+  /** Pairs where at least one side does not carry the metric. */
+  nMissing: number;
+  /** Median paired delta, or null when `n === 0`. */
+  medianDelta: number | null;
+  /** Mean paired delta, or null when `n === 0`. */
+  meanDelta: number | null;
+  /** Bootstrap CI on the paired delta (`pairedBootstrap`); null when
+   *  `n === 0` — a zero-width [0, 0] interval on no data would read as a
+   *  measured tight null. */
+  bootstrapCi: PairedBootstrapResult | null;
+  /** Wilcoxon signed-rank test on the paired deltas; null when `n === 0`. */
+  wilcoxon: {
+    w: number;
+    p: number;
+  } | null;
+}
+interface ComparePairedArmsOptions extends PairArmsOptions {
+  /** Metrics to compare. Default: every metric name observed on any matched
+   *  pair, sorted. A name that appears on no pair is still reported (with
+   *  `n = 0`) so a misspelled metric is visible instead of vanishing. */
+  metricNames?: string[];
+  /** Passed through to `pairedBootstrap` — set `seed` for reproducible CIs. */
+  bootstrap?: PairedBootstrapOptions;
+}
+interface PairedArmsComparison {
+  nPairs: number;
+  nUnpairedBaseline: number;
+  nUnpairedTreatment: number;
+  /** null when no matched pair carries `pass` on both sides — a pass/fail
+   *  verdict over rows that never measured pass/fail would be fabricated. */
+  correctness: PairedCorrectness | null;
+  metricDeltas: PairedMetricDelta[];
+}
+/**
+ * Full matched-pair arm comparison: pair via {@link pairArms}, then compose
+ * the paired estimators from `statistics` over the matched pairs.
+ *
+ * Correctness uses only the pairs where both sides carry `pass` (`mcnemar.n`
+ * is that subset's size); each metric uses only the pairs where both sides
+ * carry a finite value for it, with the remainder counted in `nMissing`.
+ * Deltas are treatment − baseline throughout.
+ *
+ * Fail-loud: inherits {@link pairArms}'s unknown-arm throw, and throws on a
+ * non-finite metric value — silently treating corrupt telemetry as "metric
+ * absent" would misreport it as missing coverage.
+ */
+declare function comparePairedArms(rows: readonly PairedArmRow[], opts: ComparePairedArmsOptions): PairedArmsComparison;
+interface MatchedRunRecordPair {
+  pairKey: string;
+  repKey: string;
+  baseline: RunRecord;
+  treatment: RunRecord;
+}
+interface PairRunRecordsResult {
+  pairs: MatchedRunRecordPair[];
+  unpairedBaseline: RunRecord[];
+  unpairedTreatment: RunRecord[];
+}
+/**
+ * Pair two RunRecord arms by the identity of the evaluated work:
+ * `(experimentId, scenarioId, seed)`.
+ *
+ * Falling back to array order, candidate id, or experiment id can compare
+ * different tasks and fabricate lift. Duplicate identities throw.
+ */
+declare function pairRunRecords(baselineRuns: readonly RunRecord[], treatmentRuns: readonly RunRecord[]): PairRunRecordsResult;
+//#endregion
+//#region src/pre-registration.d.ts
+/**
+ * Pre-registered hypotheses — declare what you're testing BEFORE the
+ * run, check it AFTER. Prevents p-hacking, optional stopping, and the
+ * "we ran until it looked good" failure mode.
+ *
+ * Manifest is a plain JSON-friendly object. Sign it with a content hash
+ * + timestamp; the registered record becomes immutable. Post-run,
+ * evaluate the manifest against observed results — the library refuses
+ * to let you re-interpret a different metric as the declared one.
+ *
+ * A signed manifest is a portable record: it is written once and verified
+ * later, possibly by a different release. `algo` names the digest scheme it
+ * was signed under, and verification selects the encoder by that field, so a
+ * manifest signed by an earlier release still verifies.
+ */
+interface HypothesisManifest {
+  id: string;
+  /** Human prose — goes into the audit trail. */
+  hypothesis: string;
+  /** Metric the hypothesis claims to move. */
+  metric: string;
+  /** 'increase' = candidate should score higher than baseline; 'decrease' = lower. */
+  direction: 'increase' | 'decrease';
+  /** Minimum effect size to count (same units as the metric). */
+  minEffect: number;
+  /** Alpha threshold. */
+  alpha: number;
+  /** Target statistical power at which sample size was pre-computed. */
+  power: number;
+  /** Declared N per arm before running. */
+  preRegisteredN: number;
+  /** ISO8601 timestamp the manifest was registered. */
+  registeredAt: string;
+  /** Optional identifiers to tie into the trace corpus. */
+  baselineLabel?: string;
+  candidateLabel?: string;
+}
+/**
+ * Identifier for the hashing scheme used to produce `contentHash`.
+ *
+ * Both schemes are sha256 hex over the manifest with `contentHash` and `algo`
+ * stripped, and differ only in how that manifest is serialized:
+ *
+ * - `'sha256-rfc8785'` — RFC 8785 canonical JSON. What {@link signManifest}
+ *   emits.
+ * - `'sha256-content'` — key-sorted `JSON.stringify`. Read-only: manifests
+ *   signed by an earlier release carry it, or carry no `algo` at all, and
+ *   {@link verifyManifest} still verifies them.
+ */
+type SignedManifestAlgo = 'sha256-content' | 'sha256-rfc8785';
+interface SignedManifest extends HypothesisManifest {
+  /** sha256 hex of canonicalized manifest (everything except contentHash and algo). */
+  contentHash: string;
+  /**
+   * Algorithm string describing how `contentHash` was produced.
+   *
+   * Optional on the type so serialized manifests without it still parse,
+   * but ALWAYS populated by {@link signManifest}. Consumers that want to
+   * enforce a known algorithm should reject manifests where this field
+   * is missing or unrecognized.
+   */
+  algo?: SignedManifestAlgo;
+}
+interface HypothesisResult {
+  manifest: SignedManifest;
+  observedN: number;
+  observedEffect: number;
+  observedPValue: number;
+  /** True iff the observed effect hits the pre-declared direction with
+   *  magnitude ≥ minEffect AND p < alpha. */
+  confirmed: boolean;
+  /** Enumerated reasons the hypothesis was rejected (each a machine-tag). */
+  rejectionReasons: Array<'wrong_direction' | 'effect_too_small' | 'not_significant' | 'undersampled'>;
+  notes?: string;
+}
+/**
+ * SHA-256 hex (full 64 chars) over the RFC 8785 canonical JSON encoding of
+ * `obj` — the package's one identity scheme, shared with `ledger-core`.
+ *
+ * Values canonical JSON cannot represent faithfully — `undefined`, `NaN`,
+ * class instances, cycles — are refused rather than coerced, because a
+ * coercion maps two distinct records onto one digest.
+ *
+ * Named `hashJson` to disambiguate from `prompt-registry.ts`'s `hashContent`,
+ * which takes a string input and returns a truncated 12-char prompt id.
+ *
+ * @example
+ *   const hash = await hashJson({ id: '1', kind: 'spec' })
+ *   // 'a3f1...' (64 hex chars)
+ */
+declare function hashJson<T>(obj: T): Promise<string>;
+/**
+ * Digest of a manifest under its own declared scheme, with `contentHash` and
+ * `algo` stripped. Synchronous, so a caller that must fail before consuming an
+ * observation does not have to await. Throws on an `algo` this release does
+ * not know — an unverifiable manifest must not read as a valid one.
+ */
+declare function manifestContentDigest(manifest: SignedManifest): string;
+/**
+ * Sign a manifest with a SHA-256 content hash over its RFC 8785 canonical
+ * JSON, with `contentHash` and `algo` stripped, and stamp the scheme in
+ * `algo` so a later reader knows which encoder to verify with.
+ */
+declare function signManifest(m: HypothesisManifest): Promise<SignedManifest>;
+/**
+ * Verify that a signed manifest has not been tampered with, under the scheme
+ * the manifest itself declares.
+ */
+declare function verifyManifest(m: SignedManifest): Promise<boolean>;
+/**
+ * Evaluate a pre-registered hypothesis against observed results.
+ * Mechanical — no re-interpretation permitted.
+ */
+declare function evaluateHypothesis(manifest: SignedManifest, observed: {
+  n: number;
+  effect: number;
+  pValue: number;
+}): Promise<HypothesisResult>;
+//#endregion
+//#region src/campaign/gates/sequential.d.ts
+type SequentialDecision = 'promote' | 'continue' | 'undecided-at-maxN';
+interface SequentialObservation {
+  decision: SequentialDecision;
+  /** Current e-value (the betting wealth) against H0. */
+  eValue: number;
+  /** Paired deltas consumed so far. */
+  n: number;
+  /** Names the decision basis. For 'undecided-at-maxN' it states explicitly
+   *  that exhausting the budget is NOT evidence of no effect. */
+  reason: string;
+}
+interface SequentialPairedGateOptions {
+  /** Type-I budget. With `preRegistration` bound this MUST match
+   *  `manifest.alpha` (conflict throws). Default 0.05. */
+  alpha?: number;
+  /** Minimum paired deltas before a promote may fire. The stopping rule is
+   *  "first n ≥ minN with e-value ≥ 1/alpha" — still a valid stopping time.
+   *  Default 5. */
+  minN?: number;
+  /** Pre-registered observation budget. Required unless `preRegistration`
+   *  supplies it via `preRegisteredN` (conflict throws). */
+  maxN?: number;
+  /** Bet truncation forwarded to `eProcess`. Default 0.5. */
+  maxBet?: number;
+  /** Bound on |delta| in the judge's native scale; deltas are mapped to
+   *  x = (d/scale + 1)/2 ∈ [0,1]. A delta outside ±scale throws (use
+   *  `detectScale` to pick 1 vs 100 BEFORE streaming). Default 1. */
+  scale?: number;
+  /** Seed for the data-independent shuffle of paired deltas in `decide(ctx)`
+   *  (exchangeability guard). Default 1337. */
+  shuffleSeed?: number;
+  /** Bind the pre-registered hypothesis. Verified (content hash) at
+   *  construction; alpha/maxN/direction/minEffect come FROM the manifest. */
+  preRegistration?: SignedManifest;
+  /** Override the gate name in reports. */
+  name?: string;
+  /** Continue the observe-stream from a `state()` snapshot taken before a
+   *  restart. The gate's parameters still resolve from this options object
+   *  (and the manifest); the snapshot must have been recorded under the same
+   *  alpha, maxBet, and null boundary, and its decision must be one this
+   *  configuration could have reached at its n, or construction throws.
+   *  `decide(ctx)` is unaffected — it always runs on a fresh stream. */
+  resume?: SequentialStreamState;
+}
+/** Snapshot of one observe-stream: the e-process state plus the gate's own
+ *  decision, which applies `minN` and `maxN` on top of the core latch. A
+ *  gate rebuilt with `resume` from this value continues exactly where the
+ *  snapshot was taken. */
+type SequentialStreamState = EProcessState & {
+  decision: SequentialDecision;
+};
+interface SequentialPairedGate<TArtifact = unknown, TScenario extends Scenario = Scenario> extends Gate<TArtifact, TScenario> {
+  /** Streaming entry point: feed one paired per-scenario delta
+   *  (candidate − baseline, native scale). Each gate instance carries ONE
+   *  observe-stream; `decide(ctx)` runs on its own fresh stream and never
+   *  consumes or advances this one. 'promote' is sticky; observing past the
+   *  pre-registered maxN throws (extending a finished stream after seeing
+   *  the result reopens optional stopping — start a NEW pre-registered
+   *  test). */
+  observe(delta: number): SequentialObservation;
+  /** Read-only snapshot of the observe-stream. Pass it back as
+   *  `resume` to continue the stream after a restart. */
+  state(): SequentialStreamState;
+}
+/**
+ * Anytime-valid sequential paired gate. Conforms to the existing `Gate`
+ * contract (`decide(ctx)` consumes candidate vs baseline judge scores via
+ * `pairHoldout` — same pairing granularity as the fixed-n gates: full cellId,
+ * never scenarioId) and adds a streaming `observe(delta)` entry for campaigns
+ * that score cells incrementally and want to stop mid-stream.
+ *
+ * Decision mapping onto the substrate's five-valued `GateDecision`:
+ *   - 'promote'            → 'ship'
+ *   - 'continue'           → 'need_more_work' (stream ended before maxN with
+ *                            the e-value undecided — more reps could decide)
+ *   - 'undecided-at-maxN'  → 'hold', with the reason stating it is NOT
+ *                            evidence of no effect (never a silent default)
+ */
+declare function sequentialPairedGate<TArtifact = unknown, TScenario extends Scenario = Scenario>(options: SequentialPairedGateOptions): SequentialPairedGate<TArtifact, TScenario>;
+interface SequentialDecideOptions {
+  /** Type-I budget for the early-stop evidence. Default 0.05. */
+  alpha?: number;
+  /** Minimum paired deltas before a stop may fire. Default 5. */
+  minN?: number;
+  /** Bet truncation forwarded to `eProcess`. Default 0.5. */
+  maxBet?: number;
+  /** Bound on |per-scenario composite delta|. Default 1. */
+  scale?: number;
+}
+interface SequentialDecideFn {
+  (args: {
+    history: GenerationRecord[];
+  }): {
+    stop: boolean;
+    reason?: string;
+  };
+  /** Read-only snapshot of the accumulated e-process (observability + tests). */
+  state(): EProcessState;
+}
+/**
+ * `SurfaceProposer.decide` adapter — stops the optimization loop the moment
+ * the e-process decides the loop has produced a real improvement, instead of
+ * always running `maxGenerations`.
+ *
+ * Stream: for each generation g ≥ 1, the per-scenario composite deltas of
+ * generation g's top candidate vs the generation-0 top candidate (the
+ * incumbent the loop set out to beat), paired by scenarioId. H0: no proposed
+ * surface improves any scenario's expected composite over the incumbent —
+ * under it every delta has conditional mean ≤ 0 and the e-process is valid.
+ * Once wealth ≥ 1/alpha the loop stops and hands the winner to the promotion
+ * gate (which re-scores on HELD-OUT data — this adapter only spends the
+ * exploration budget, it never promotes).
+ *
+ * Honesty caveats: (1) the incumbent's scores are measured once and shared
+ * across all generations' deltas, so type-I control is exact only insofar as
+ * those scores approximate the incumbent's true per-scenario means (more reps
+ * → tighter); (2) an UNDECIDED process never stops the loop — absence of a
+ * crossing is NOT evidence of no effect, so the loop simply runs its normal
+ * course. Calling the adapter repeatedly with a growing history consumes each
+ * generation exactly once (re-feeding an already-seen record would double-count
+ * evidence).
+ */
+declare function sequentialDecide(options?: SequentialDecideOptions): SequentialDecideFn;
+//#endregion
+//#region src/campaign/gates/statistical-heldout.d.ts
+interface PairedHoldout {
+  /** Baseline scalar per paired cell (same order as `after`/`cellIds`). */
+  before: number[];
+  /** Candidate scalar per paired cell. */
+  after: number[];
+  /** The full cellIds (`scenario:rep`) that paired, in order. */
+  cellIds: string[];
+}
+/**
+ * Pair candidate vs baseline holdout observations by FULL cellId. `select`
+ * pulls the scalar from a cell's judge reports (composite, or a named
+ * dimension); a cell contributes the mean of `select` across its judges. Cells
+ * whose scenario is not in `scenarioIds`, or where `select` is undefined for
+ * every judge on either side, are skipped on BOTH sides so the arrays stay
+ * paired. Throws when the two maps disagree on which holdout cells exist — a
+ * load-bearing invariant: the baseline + winner holdout campaigns run the same
+ * scenarios with the same seed base, so their cellIds MUST align; a mismatch
+ * means a silent pairing bug, not a soft fallback.
+ */
+declare function pairHoldout(candidate: Map<string, Record<string, JudgeScore>>, baseline: Map<string, Record<string, JudgeScore>>, scenarioIds: Set<string>, select: (s: JudgeScore) => number | undefined): PairedHoldout;
+interface HeldoutSignificance {
+  paired: PairedHoldout;
+  /**
+   * The paired bootstrap on the requested statistic (MEAN by default — see the
+   * tie note on `heldoutSignificance`).
+   *
+   * DIAGNOSTIC, not necessarily the interval the verdict keyed on. On a
+   * two-point (pass/fail) outcome the decision routes to Tango's score interval
+   * instead, because a percentile bootstrap of the mean over a three-atom
+   * lattice is not a valid interval at a nonzero margin. Read
+   * `decision.low`/`decision.high` for the interval that actually decided, and
+   * `decisionStatistic` for which one it is.
+   */
+  bootstrap: PairedBootstrapResult;
+  /** The MEDIAN paired-delta bootstrap, reported as a diagnostic. When many
+   *  scenarios are tied (both sides solve them), the median is pinned near 0
+   *  regardless of the mean lift — comparing the two exposes tie-domination. */
+  medianBootstrap: PairedBootstrapResult;
+  /**
+   * The full promotion decision: which estimator the outcome's shape admits,
+   * the interval it produced, McNemar's exact veto on the two-point path, and
+   * whether the interval was zero-width (no evidence in either direction). The
+   * single source of `significant`.
+   */
+  decision: PairedPromotionDecision;
+  /** Which paired estimator the verdict was decided on. */
+  decisionStatistic: PairedDecisionStatistic;
+  /** McNemar's exact evidence on the two-point path; null otherwise. */
+  mcnemar: PairedMcNemarEvidence | null;
+  /** Fraction of paired observations that are exact ties (|delta| < 1e-9). A
+   *  high tie fraction is WHY a median-based gate would have missed a real lift;
+   *  it is the observability the tie fix adds. */
+  tieFraction: number;
+  /** n paired observations. */
+  n: number;
+  /** Effective minimum after applying the bootstrap's hard statistical floor. */
+  minimumRequired: number;
+  /** Statistical method that carried the decision. */
+  decisionMethod: PairedDecisionMethod;
+  /** Exact one-sided p-value on the small-sample path; otherwise null. */
+  pValue: number | null;
+  /** True iff n >= minimumRequired, the DECIDING interval has nonzero width,
+   *  its lower bound clears the threshold, and McNemar's exact test does not
+   *  veto at a non-negative threshold. */
+  significant: boolean;
+  /** Set when n < minimumRequired — too little evidence to claim significance. */
+  fewRuns: boolean;
+}
+interface HeldoutSignificanceOptions {
+  deltaThreshold?: number;
+  minProductiveRuns?: number;
+  confidence?: number;
+  resamples?: number;
+  /** Fixed by default for a deterministic, reproducible gate verdict. */
+  seed?: number;
+  statistic?: 'mean' | 'median';
+}
+/**
+ * Significance of the held-out composite lift: ship only when the lower bound
+ * of the interval the outcome's shape ADMITS exceeds `deltaThreshold` (default
+ * 0 ⇒ "confidently positive"). Interpret `deltaThreshold` in the judge's native
+ * scale.
+ *
+ * The decision is delegated whole to {@link decidePairedPromotion}, the one
+ * copy of the rule (`src/paired-promotion-decision.ts`), which `HeldOutGate`
+ * also calls. That module's header carries the measurements; the short version
+ * is three guards a bare `bootstrap.low > threshold` does not have:
+ *
+ *   - a two-point (pass/fail) outcome decides on Tango's SCORE interval, the
+ *     only paired-binary construction that stays valid at a nonzero margin;
+ *   - McNemar's exact test VETOES at any non-negative threshold;
+ *   - a ZERO-WIDTH interval is refused rather than promoted, in either
+ *     direction — [0,0] clears every negative threshold and [g,g] clears every
+ *     threshold below g, and both are an absence of evidence, not a result.
+ *
+ * Measured on this function before those guards landed, at a nominal 5 %:
+ * 14.60 % false promotion at n = 40 on a paired-binary noninferiority boundary,
+ * and 88.50 % at n = 6 under a bounded asymmetric null whose true mean paired
+ * delta is exactly 0.
+ *
+ * At small n, where the percentile bootstrap is descriptive only, a
+ * pre-registered exact sign test still carries the bootstrap path.
+ */
+declare function heldoutSignificance(paired: PairedHoldout, opts?: HeldoutSignificanceOptions): HeldoutSignificance;
+interface DimensionRegression {
+  dimension: string;
+  /** Paired bootstrap on (candidate − baseline). DIAGNOSTIC on a pass/fail
+   *  dimension, where `ci` carries the interval that decided instead. */
+  bootstrap: PairedBootstrapResult;
+  /** Which paired statistic `bootstrap.low` is the lower bound of. `'mean'`
+   *  unless the caller asked for the median. `bootstrap.median` still carries
+   *  the median point estimate either way. */
+  bootstrapStatistic: 'median' | 'mean';
+  /** The interval `regressed` was decided on, in the dimension's native units. */
+  ci: {
+    low: number;
+    high: number;
+  };
+  /** Which estimator produced `ci`. */
+  decisionStatistic: PairedDecisionStatistic;
+  /** McNemar's exact evidence on a pass/fail dimension; null otherwise. */
+  mcnemar: PairedMcNemarEvidence | null;
+  /** `ci` has zero width — no evidence in either direction. */
+  indeterminate: boolean;
+  /** True iff the candidate may have regressed this dimension by more than
+   *  tolerance: the lower bound of the DECIDING interval on (candidate −
+   *  baseline) is below −tolerance, OR the exact small-sample test proves a drop
+   *  past tolerance. */
+  regressed: boolean;
+  tolerance: number;
+  n: number;
+}
+/** Detect the native scale of a set of scores: 0-100 when any magnitude clears
+ *  1.5, else [0,1]. Used to auto-scale the regression tolerance so a default
+ *  expressed for [0,1] is not silently a no-op on a 0-100 dimension. */
+declare function detectScale(values: number[]): 1 | 100;
+/** Per-critical-dimension regression guard. For each dimension, pair the
+ *  candidate vs baseline values by full cellId and bootstrap the paired delta;
+ *  a dimension is "regressed" when the CI lower bound < −tolerance (conservative
+ *  — blocks if the credible worst case exceeds tolerance, which is the right
+ *  posture for safety dimensions like `hallucination_free`). When `tolerance`
+ *  is omitted it auto-scales: 0.05 on [0,1], 5 on 0-100.
+ *
+ *  The interval comes from {@link decidePairedPromotion}, so a pass/fail
+ *  dimension is judged on Tango's score interval rather than a percentile
+ *  bootstrap of the mean — `tolerance` is a NONZERO margin, and the bootstrap
+ *  is not a valid interval at one. That matters most here because this guard
+ *  fails OPEN by construction: `tolerance` is positive, so an interval pinned at
+ *  [0,0] never satisfies `low < −tolerance` and a real regression on a safety
+ *  dimension would be reported as `regressed: false`. On the median it fails the
+ *  same way for the same reason — when most pairs tie, which is automatic for a
+ *  pass/fail dimension on {0,1} and on the 0-100 encoding `detectScale` exists
+ *  to support, the median CI collapses to [0,0]. Pass `statistic: 'median'` to
+ *  restore the pre-0.134 behaviour. */
+declare function dimensionRegressions(candidate: Map<string, Record<string, JudgeScore>>, baseline: Map<string, Record<string, JudgeScore>>, scenarioIds: Set<string>, criticalDimensions: string[], opts?: {
+  tolerance?: number;
+  confidence?: number;
+  resamples?: number;
+  seed?: number;
+  /** Paired statistic the CI is computed on. Default `'mean'` — see
+   *  {@link DECISION_PAIRED_DELTA_STATISTIC} for why the median is not. */
+  statistic?: 'mean' | 'median';
+}): DimensionRegression[];
+//#endregion
+export { paretoSignificanceGate as $, PairArmsOptions as A, PowerPreflight as B, hashJson as C, ComparePairedArmsOptions as D, verifyManifest as E, PairedCorrectness as F, BuildEvidenceVectorOptions as G, powerPreflight as H, PairedMetricDelta as I, ParetoSignificanceGateOptions as J, EvidenceVector as K, comparePairedArms as L, PairRunRecordsResult as M, PairedArmRow as N, MatchedPair as O, PairedArmsComparison as P, paretoPolicy as Q, pairArms as R, evaluateHypothesis as S, signManifest as T, AxisEvidence as U, PowerPreflightOptions as V, AxisVerdict as W, PromotionPolicy as X, PromotionObjective as Y, buildEvidenceVector as Z, sequentialPairedGate as _, pairedRiskDifference as _t, detectScale as a, EProcessOptions as at, SignedManifest as b, passAtK as bt, pairHoldout as c, eProcess as ct, SequentialDecision as d, ProportionInterval as dt, Objective as et, SequentialObservation as f, RiskDifferenceResult as ft, sequentialDecide as g, pairedBinaryScale as gt, SequentialStreamState as h, mcnemar as ht, PairedHoldout as i, EProcess as it, PairArmsResult as j, MatchedRunRecordPair as k, SequentialDecideFn as l, ExactRiskDifferenceResult as lt, SequentialPairedGateOptions as m, isBinaryOutcomeVector as mt, HeldoutSignificance as n, dominates as nt, dimensionRegressions as o, EProcessState as ot, SequentialPairedGate as p, ScoreRiskDifferenceResult as pt, ObjectiveSource as q, HeldoutSignificanceOptions as r, paretoFrontier as rt, heldoutSignificance as s, EProcessStep as st, DimensionRegression as t, ParetoResult as tt, SequentialDecideOptions as u, McNemarResult as ut, HypothesisManifest as v, pairedRiskDifferenceExact as vt, manifestContentDigest as w, SignedManifestAlgo as x, wilson as xt, HypothesisResult as y, pairedRiskDifferenceScore as yt, pairRunRecords as z };
+//# sourceMappingURL=statistical-heldout-Cqb73yE9.d.ts.map