peeksafe 0.0.0-stage → 0.1.0

package/src/stats.ts

@@ -0,0 +1,1579 @@
+/**
+ * stats.ts: the statistical core of peeksafe, implemented from scratch.
+ *
+ * Nothing here calls a library. Every function is a pure function of numbers so
+ * it can be checked against closed-form or hand-computed values in test/.
+ *
+ * Contents:
+ *   special functions   logGamma, logBeta, erf, normalCdf, normalQuantile, ibeta
+ *   estimation          wilsonInterval, betaPosterior, betaCredibleInterval
+ *   effect size         diffInterval (Newcombe hybrid score), cohensH
+ *   testing             twoProportionZTest, fisherExact2x2, sprtDecision
+ *   correction          bhCorrect, ebhCorrect
+ *   evidence            twoSampleLogE, pairedLogE, probabilityMoved
+ *   planning            sampleSizeTwoProportion, samplesForEvidence, mcnemarSamplesForEvidence
+ *
+ * **Domain discipline.** Every entry point that can be handed nonsense
+ * (successes > trials, a negative count, a probability outside [0,1]) throws a
+ * `PeeksafeError` with code `PEEKSAFE_E_STAT_DOMAIN` rather than returning NaN
+ * or a plausible-looking number. Returning `Infinity` is reserved for questions
+ * whose honest answer is "no finite sample size will do", see
+ * `sampleSizeTwoProportion`.
+ */
+import {
+  PeeksafeError,
+  requireCounts,
+  requireOpenProbability,
+  requireProbability,
+} from "./errors.js";
+
+/* ────────────────────────── special functions ────────────────────────── */
+
+const LANCZOS = [
+  676.5203681218851, -1259.1392167224028, 771.32342877765313, -176.61502916214059,
+  12.507343278686905, -0.13857109526572012, 9.9843695780195716e-6, 1.5056327351493116e-7,
+];
+
+/** Lanczos approximation to log Γ(x), x > 0. ~15 significant digits. */
+export function logGamma(x: number): number {
+  if (x < 0.5) {
+    // reflection: Γ(x)Γ(1-x) = π / sin(πx)
+    return Math.log(Math.PI / Math.abs(Math.sin(Math.PI * x))) - logGamma(1 - x);
+  }
+  const z = x - 1;
+  let a = 0.99999999999980993;
+  for (let i = 0; i < LANCZOS.length; i++) a += LANCZOS[i]! / (z + i + 1);
+  const t = z + LANCZOS.length - 0.5;
+  return 0.5 * Math.log(2 * Math.PI) + (z + 0.5) * Math.log(t) - t + Math.log(a);
+}
+
+export const logBeta = (a: number, b: number): number =>
+  logGamma(a) + logGamma(b) - logGamma(a + b);
+
+/** Series expansion of the regularized lower incomplete gamma P(a,x), x < a+1. */
+function gammaPSeries(a: number, x: number): number {
+  let term = 1 / a;
+  let sum = term;
+  for (let n = 1; n < 500; n++) {
+    term *= x / (a + n);
+    sum += term;
+    if (Math.abs(term) < Math.abs(sum) * 1e-17) break;
+  }
+  return sum * Math.exp(-x + a * Math.log(x) - logGamma(a));
+}
+
+/** Lentz continued fraction for the regularized upper incomplete gamma Q(a,x). */
+function gammaQContinued(a: number, x: number): number {
+  const TINY = 1e-300;
+  let b = x + 1 - a;
+  let cf = 1 / TINY;
+  let d = 1 / b;
+  let h = d;
+  for (let i = 1; i < 500; i++) {
+    const an = -i * (i - a);
+    b += 2;
+    d = an * d + b;
+    if (Math.abs(d) < TINY) d = TINY;
+    cf = b + an / cf;
+    if (Math.abs(cf) < TINY) cf = TINY;
+    d = 1 / d;
+    const del = d * cf;
+    h *= del;
+    if (Math.abs(del - 1) < 1e-16) break;
+  }
+  return Math.exp(-x + a * Math.log(x) - logGamma(a)) * h;
+}
+
+/** Regularized lower incomplete gamma P(a,x), accurate to ~1e-15. */
+export function gammaP(a: number, x: number): number {
+  if (x <= 0) return 0;
+  return x < a + 1 ? gammaPSeries(a, x) : 1 - gammaQContinued(a, x);
+}
+
+/**
+ * erf(x) = sign(x)·P(½, x²).
+ * Built on the incomplete gamma rather than a rational fit: the usual 7-digit
+ * approximation is visible in a p-value and we compare p-values to thresholds.
+ */
+export function erf(x: number): number {
+  if (x === 0) return 0;
+  const p = gammaP(0.5, x * x);
+  return x > 0 ? p : -p;
+}
+
+/** Φ(x): standard normal CDF. */
+export const normalCdf = (x: number): number => 0.5 * (1 + erf(x / Math.SQRT2));
+
+/** Φ⁻¹(p): Acklam's inverse normal CDF, refined by one Halley step. */
+export function normalQuantile(p: number): number {
+  if (p <= 0) return -Infinity;
+  if (p >= 1) return Infinity;
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1,
+  ];
+  const cc = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783,
+  ];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+  const pl = 0.02425;
+  let x: number;
+  if (p < pl) {
+    const q = Math.sqrt(-2 * Math.log(p));
+    x =
+      (((((cc[0]! * q + cc[1]!) * q + cc[2]!) * q + cc[3]!) * q + cc[4]!) * q + cc[5]!) /
+      ((((d[0]! * q + d[1]!) * q + d[2]!) * q + d[3]!) * q + 1);
+  } else if (p <= 1 - pl) {
+    const q = p - 0.5;
+    const r = q * q;
+    x =
+      ((((((a[0]! * r + a[1]!) * r + a[2]!) * r + a[3]!) * r + a[4]!) * r + a[5]!) * q) /
+      (((((b[0]! * r + b[1]!) * r + b[2]!) * r + b[3]!) * r + b[4]!) * r + 1);
+  } else {
+    const q = Math.sqrt(-2 * Math.log(1 - p));
+    x =
+      -(((((cc[0]! * q + cc[1]!) * q + cc[2]!) * q + cc[3]!) * q + cc[4]!) * q + cc[5]!) /
+      ((((d[0]! * q + d[1]!) * q + d[2]!) * q + d[3]!) * q + 1);
+  }
+  // One Halley refinement against our own Φ. Skipped in the far tails, where
+  // exp(x²/2) overflows to Infinity and the refinement returns NaN, the
+  // Acklam value is already good to ~1e-9 there.
+  const half = (x * x) / 2;
+  if (half > 300) return x;
+  const e = normalCdf(x) - p;
+  const u = e * Math.sqrt(2 * Math.PI) * Math.exp(half);
+  const refined = x - u / (1 + (x * u) / 2);
+  return Number.isFinite(refined) ? refined : x;
+}
+
+/**
+ * Smallest magnitude a Lentz denominator is allowed to take.
+ *
+ * The recurrence divides by both running terms, so a coefficient that lands on
+ * zero would produce an infinity that never recovers. Clamping to a tiny
+ * non-zero value instead is the standard remedy and costs nothing in accuracy.
+ */
+const LENTZ_FLOOR = 1e-30;
+
+/** Keep a Lentz denominator away from zero. */
+const awayFromZero = (v: number): number => (Math.abs(v) < LENTZ_FLOOR ? LENTZ_FLOOR : v);
+
+/**
+ * The continued fraction for the regularized incomplete beta.
+ *
+ * The fraction itself is Abramowitz & Stegun 26.5.8; it is evaluated by the
+ * modified Lentz algorithm (Lentz 1976, as amended by Thompson & Barnett 1986),
+ * which advances the numerator and denominator convergents together so the
+ * fraction can be truncated as soon as one factor is within tolerance of 1.
+ *
+ * Both are published mathematics rather than anybody's source code, and this is
+ * written from the recurrence: the even and odd coefficients below are A&S
+ * 26.5.8 verbatim, and the loop is the textbook Lentz update. See NOTICE.
+ */
+function betaContinuedFraction(a: number, b: number, x: number): number {
+  const sum = a + b;
+  const aUp = a + 1;
+  const aDown = a - 1;
+
+  // Lentz starts from the zeroth convergent and multiplies in one factor per
+  // half-step; `frac` is the running value, `cTerm` and `dTerm` the convergents.
+  let cTerm = 1;
+  let dTerm = 1 / awayFromZero(1 - (sum * x) / aUp);
+  let frac = dTerm;
+
+  for (let j = 1; j <= 300; j++) {
+    const twoJ = 2 * j;
+
+    // even coefficient d_{2j}
+    const even = (j * (b - j) * x) / ((aDown + twoJ) * (a + twoJ));
+    dTerm = 1 / awayFromZero(1 + even * dTerm);
+    cTerm = awayFromZero(1 + even / cTerm);
+    frac *= dTerm * cTerm;
+
+    // odd coefficient d_{2j+1}
+    const odd = (-(a + j) * (sum + j) * x) / ((a + twoJ) * (aUp + twoJ));
+    dTerm = 1 / awayFromZero(1 + odd * dTerm);
+    cTerm = awayFromZero(1 + odd / cTerm);
+    const step = dTerm * cTerm;
+    frac *= step;
+
+    // Converged once a half-step multiplies the fraction by 1 to float64.
+    if (Math.abs(step - 1) < 3e-16) break;
+  }
+  return frac;
+}
+
+/** Regularized incomplete beta Iₓ(a,b) = P(Beta(a,b) ≤ x). */
+export function ibeta(a: number, b: number, x: number): number {
+  if (!(a > 0) || !(b > 0) || !Number.isFinite(a) || !Number.isFinite(b) || !Number.isFinite(x)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "ibeta: need finite a > 0, b > 0 and finite x",
+      {
+        detail: { a, b, x },
+      },
+    );
+  }
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  const front = Math.exp(a * Math.log(x) + b * Math.log(1 - x) - logBeta(a, b));
+  return x < (a + 1) / (a + b + 2)
+    ? (front * betaContinuedFraction(a, b, x)) / a
+    : 1 -
+        (Math.exp(b * Math.log(1 - x) + a * Math.log(x) - logBeta(b, a)) *
+          betaContinuedFraction(b, a, 1 - x)) /
+          b;
+}
+
+/* ─────────────────────────────── estimation ──────────────────────────── */
+
+export interface Interval {
+  low: number;
+  high: number;
+  point: number;
+  /**
+   * How many observations the interval rests on, when the producer knows.
+   * `0` means the interval is vacuous and `point` is a placeholder, not an
+   * estimate, check it before printing the point as a number.
+   */
+  observations?: number;
+}
+
+/**
+ * Wilson score interval for a binomial proportion.
+ * Correct at the boundaries (0/n and n/n) where Wald is degenerate, which is
+ * exactly where eval cases live.
+ */
+export function wilsonInterval(successes: number, n: number, z = 1.959963984540054): Interval {
+  requireCounts(successes, n, "wilsonInterval");
+  // No data is not "p = 0.5". The interval is the whole line and the point
+  // estimate is NaN-free only because callers must check `n`, which is why
+  // `n` is echoed back in `observations`.
+  if (n === 0) return { low: 0, high: 1, point: 0.5, observations: 0 };
+  const p = successes / n;
+  const z2 = z * z;
+  const denom = 1 + z2 / n;
+  const centre = (p + z2 / (2 * n)) / denom;
+  const margin = (z / denom) * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+  return {
+    low: Math.max(0, centre - margin),
+    high: Math.min(1, centre + margin),
+    point: p,
+    observations: n,
+  };
+}
+
+export interface BetaPosterior {
+  alpha: number;
+  beta: number;
+  mean: number;
+  mode: number;
+  variance: number;
+  sd: number;
+  n: number;
+  successes: number;
+}
+
+/** Conjugate Beta posterior for a per-case latent success probability. */
+export function betaPosterior(
+  successes: number,
+  failures: number,
+  prior: { alpha: number; beta: number } = { alpha: 1, beta: 1 },
+): BetaPosterior {
+  requireCounts(successes, successes + failures, "betaPosterior");
+  if (!(prior.alpha > 0) || !(prior.beta > 0)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "betaPosterior: prior parameters must be positive",
+      {
+        detail: { prior },
+      },
+    );
+  }
+  const alpha = prior.alpha + successes;
+  const beta = prior.beta + failures;
+  const s = alpha + beta;
+  return {
+    alpha,
+    beta,
+    mean: alpha / s,
+    mode: alpha > 1 && beta > 1 ? (alpha - 1) / (s - 2) : alpha / s,
+    variance: (alpha * beta) / (s * s * (s + 1)),
+    sd: Math.sqrt((alpha * beta) / (s * s * (s + 1))),
+    n: successes + failures,
+    successes,
+  };
+}
+
+/** Inverse of the Beta CDF by bisection on ibeta (monotone, so this is exact to 1e-10). */
+export function betaQuantile(alpha: number, beta: number, q: number): number {
+  if (!(alpha > 0) || !(beta > 0) || !Number.isFinite(alpha) || !Number.isFinite(beta)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "betaQuantile: alpha and beta must be finite and positive",
+      {
+        detail: { alpha, beta, q },
+      },
+    );
+  }
+  if (q <= 0) return 0;
+  if (q >= 1) return 1;
+  let lo = 0,
+    hi = 1;
+  for (let i = 0; i < 200; i++) {
+    const mid = (lo + hi) / 2;
+    if (ibeta(alpha, beta, mid) < q) lo = mid;
+    else hi = mid;
+    if (hi - lo < 1e-12) break;
+  }
+  return (lo + hi) / 2;
+}
+
+/**
+ * Student-t quantile, from the Beta inverse CDF.
+ *
+ * Needed because the cluster-robust suite interval has a *small* number of
+ * degrees of freedom, one per case family, not one per case, and at 39 df the
+ * difference between t and z is already 3.2% of the half-width. Using z there
+ * would reintroduce, in miniature, exactly the too-narrow-interval bug that
+ * clustering exists to fix.
+ *
+ * The identity is the standard one: for T ~ t_ν and t > 0,
+ *   P(|T| > t) = I_x(ν/2, ½)  with  x = ν/(ν + t²)
+ * so inverting `ibeta` in x inverts the t CDF. Exact to the ~1e-10 of
+ * `betaQuantile`, and it degenerates to `normalQuantile` as ν → ∞.
+ */
+export function tQuantile(p: number, df: number): number {
+  if (!Number.isFinite(p) || p <= 0 || p >= 1) {
+    throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `tQuantile: p must be in (0,1), got ${p}`, {
+      detail: { p, df },
+    });
+  }
+  if (!Number.isFinite(df) || df <= 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `tQuantile: df must be finite and positive, got ${df}`,
+      {
+        detail: { p, df },
+      },
+    );
+  }
+  if (p === 0.5) return 0;
+  if (p < 0.5) return -tQuantile(1 - p, df);
+  // Past this the Beta inversion loses to floating point long before the normal
+  // approximation is wrong by anything a reader could see.
+  if (df > 1e7) return normalQuantile(p);
+  const twoSidedTail = 2 * (1 - p);
+  const x = betaQuantile(df / 2, 0.5, twoSidedTail);
+  if (!(x > 0)) return Infinity;
+  return Math.sqrt((df * (1 - x)) / x);
+}
+
+/** Equal-tailed credible interval of a Beta posterior. */
+export function betaCredibleInterval(post: BetaPosterior, level = 0.95): Interval {
+  const tail = (1 - level) / 2;
+  return {
+    low: betaQuantile(post.alpha, post.beta, tail),
+    high: betaQuantile(post.alpha, post.beta, 1 - tail),
+    point: post.mean,
+  };
+}
+
+/** P(a < θ < b) under a Beta posterior. */
+export function betaMassBetween(post: BetaPosterior, a: number, b: number): number {
+  requireProbability(a, "a", "betaMassBetween");
+  requireProbability(b, "b", "betaMassBetween");
+  if (a > b) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `betaMassBetween: need a ≤ b, got [${a}, ${b}]`,
+      {
+        detail: { a, b },
+      },
+    );
+  }
+  return ibeta(post.alpha, post.beta, b) - ibeta(post.alpha, post.beta, a);
+}
+
+/* ─────────────────────────────── effect size ─────────────────────────── */
+
+/**
+ * Newcombe's hybrid-score interval for a difference of proportions (p₂ − p₁).
+ * Built from the two Wilson intervals, so it stays inside [-1,1] and behaves at
+ * the boundaries. This is the "effect size with a CI" that replaces "-4.5%".
+ */
+export function diffInterval(
+  s1: number,
+  n1: number,
+  s2: number,
+  n2: number,
+  z = 1.959963984540054,
+): Interval {
+  requireCounts(s1, n1, "diffInterval(arm 1)");
+  requireCounts(s2, n2, "diffInterval(arm 2)");
+  // With an empty arm there is no difference to estimate. Saying so beats
+  // reporting `p2 − 0` as if the missing arm had scored zero.
+  if (n1 === 0 || n2 === 0) return { low: -1, high: 1, point: 0, observations: 0 };
+  const w1 = wilsonInterval(s1, n1, z);
+  const w2 = wilsonInterval(s2, n2, z);
+  const p1 = n1 > 0 ? s1 / n1 : 0;
+  const p2 = n2 > 0 ? s2 / n2 : 0;
+  const lower = p2 - p1 - Math.sqrt((p2 - w2.low) ** 2 + (w1.high - p1) ** 2);
+  const upper = p2 - p1 + Math.sqrt((w2.high - p2) ** 2 + (p1 - w1.low) ** 2);
+  return {
+    low: Math.max(-1, lower),
+    high: Math.min(1, upper),
+    point: p2 - p1,
+    observations: n1 + n2,
+  };
+}
+
+/** Cohen's h, the scale-free effect size for proportions (arcsine transform). */
+export function cohensH(p1: number, p2: number): number {
+  requireProbability(p1, "p1", "cohensH");
+  requireProbability(p2, "p2", "cohensH");
+  return 2 * Math.asin(Math.sqrt(p2)) - 2 * Math.asin(Math.sqrt(p1));
+}
+
+/* ──────────────────────────────── testing ───────────────────────────── */
+
+export interface TestResult {
+  statistic: number;
+  p: number;
+}
+
+/** Pooled two-proportion z-test, two-sided. */
+export function twoProportionZTest(s1: number, n1: number, s2: number, n2: number): TestResult {
+  requireCounts(s1, n1, "twoProportionZTest(arm 1)");
+  requireCounts(s2, n2, "twoProportionZTest(arm 2)");
+  if (n1 === 0 || n2 === 0) return { statistic: 0, p: 1 };
+  const p1 = s1 / n1,
+    p2 = s2 / n2;
+  const pool = (s1 + s2) / (n1 + n2);
+  const se = Math.sqrt(pool * (1 - pool) * (1 / n1 + 1 / n2));
+  if (se === 0) return { statistic: 0, p: 1 };
+  const z = (p2 - p1) / se;
+  return { statistic: z, p: 2 * (1 - normalCdf(Math.abs(z))) };
+}
+
+const logChoose = (n: number, k: number): number =>
+  logGamma(n + 1) - logGamma(k + 1) - logGamma(n - k + 1);
+
+/**
+ * Fisher's exact test on a 2×2 table [[a,b],[c,d]], two-sided by the
+ * sum-of-small-probabilities convention. Exact, which matters because eval
+ * cases are run 8 to 30 times, not 8000.
+ */
+export function fisherExact2x2(a: number, b: number, cc: number, d: number): TestResult {
+  for (const [name, v] of [
+    ["a", a],
+    ["b", b],
+    ["c", cc],
+    ["d", d],
+  ] as const) {
+    if (!Number.isInteger(v) || v < 0) {
+      throw new PeeksafeError(
+        "PEEKSAFE_E_STAT_DOMAIN",
+        `fisherExact2x2: cell ${name} must be a non-negative integer, got ${v}`,
+        {
+          detail: { a, b, c: cc, d },
+        },
+      );
+    }
+  }
+  const r1 = a + b,
+    r2 = cc + d,
+    c1 = a + cc,
+    n = r1 + r2;
+  if (n === 0) return { statistic: 1, p: 1 };
+  const logP = (x: number) => logChoose(r1, x) + logChoose(r2, c1 - x) - logChoose(n, c1);
+  const pObs = Math.exp(logP(a));
+  const lo = Math.max(0, c1 - r2),
+    hi = Math.min(r1, c1);
+  let p = 0;
+  for (let x = lo; x <= hi; x++) {
+    const px = Math.exp(logP(x));
+    if (px <= pObs * (1 + 1e-7)) p += px;
+  }
+  const oddsRatio = b * cc === 0 ? Infinity : (a * d) / (b * cc);
+  return { statistic: oddsRatio, p: Math.min(1, p) };
+}
+
+/* ──────────────────────────────── SPRT ──────────────────────────────── */
+
+export type SprtDecision = "ACCEPT_H0" | "ACCEPT_H1" | "CONTINUE";
+
+export interface SprtResult {
+  decision: SprtDecision;
+  logLR: number;
+  upper: number;
+  lower: number;
+  /** How far through the [lower, upper] corridor we are: -1 = H0 wall, +1 = H1 wall. */
+  progress: number;
+}
+
+export interface SprtOpts {
+  successes: number;
+  trials: number;
+  /** null hypothesis success probability (e.g. the baseline rate) */
+  p0: number;
+  /** alternative worth detecting (e.g. baseline − minimum detectable regression) */
+  p1: number;
+  alpha?: number;
+  beta?: number;
+}
+
+/**
+ * Wald's Sequential Probability Ratio Test for a Bernoulli stream.
+ *
+ * logLR = s·log(p₁/p₀) + (n−s)·log((1−p₁)/(1−p₀))
+ * accept H₁ when logLR ≥ log((1−β)/α); accept H₀ when logLR ≤ log(β/(1−α)).
+ *
+ * The whole point: it is evaluated after *every* batch, so a case that is
+ * obviously fine (or obviously broken) stops consuming samples immediately.
+ */
+export function sprtDecision(opts: SprtOpts): SprtResult {
+  const { successes: s, trials: n, p0, p1 } = opts;
+  requireCounts(s, n, "sprtDecision");
+  requireProbability(p0, "p0", "sprtDecision");
+  requireProbability(p1, "p1", "sprtDecision");
+  const alpha = opts.alpha ?? 0.05;
+  const beta = opts.beta ?? 0.1;
+  // The two walls are `log((1-beta)/alpha)` and `log(beta/(1-alpha))`, and
+  // these were the arguments nothing checked. An alpha at or above 1 makes the
+  // second one the log of a negative number, so `lower` came back NaN, every
+  // comparison against it was false, and the test reported CONTINUE for ever
+  // against a wall that is not a number. An alpha of 0 puts `upper` at
+  // Infinity, which no evidence ever crosses. Open at both ends: an error rate
+  // of 0 is a test that never decides and one of 1 is a test that always does.
+  requireOpenProbability(alpha, "alpha", "sprtDecision");
+  requireOpenProbability(beta, "beta", "sprtDecision");
+  const e = 1e-12;
+  const cl = (x: number) => Math.min(1 - e, Math.max(e, x));
+  const q0 = cl(p0),
+    q1 = cl(p1);
+  const logLR = s * Math.log(q1 / q0) + (n - s) * Math.log((1 - q1) / (1 - q0));
+  const upper = Math.log((1 - beta) / alpha);
+  const lower = Math.log(beta / (1 - alpha));
+  const decision: SprtDecision =
+    logLR >= upper ? "ACCEPT_H1" : logLR <= lower ? "ACCEPT_H0" : "CONTINUE";
+  const progress = logLR >= 0 ? logLR / upper : -(logLR / lower);
+  return { decision, logLR, upper, lower, progress: Math.max(-1, Math.min(1, progress)) };
+}
+
+/**
+ * The exponent that tilts the likelihood ratio into a martingale at rate `p`:
+ * the one `h != 0` with `E_p[λ^h] = 1`, where `λ` is the per-trial likelihood
+ * ratio. Wald's operating characteristic is a closed form in it.
+ *
+ * `g(h) = p·r₁^h + (1−p)·r₀^h − 1` is convex with `g(0) = 0` and
+ * `g'(0) = E_p[log λ]`, the drift, so the second root sits on the side opposite
+ * the drift's sign and bisection finds it. `h` is exactly −1 at `p1` and exactly
+ * +1 at `p0`, which is what pins the OC to `1 − β` and `α` there.
+ *
+ * Returns ±Infinity when the bracket reaches 2^20 without finding a root. That
+ * is exactly `p = 0` or `p = 1`, where one outcome is impossible so the test
+ * cannot be wrong about which wall it reaches. The cap is safe for the rest
+ * because the operating characteristic has saturated to 1 or 0 to machine
+ * precision long before `|h|` gets there, so the ±Infinity branch returns the
+ * answer the bisection would have.
+ */
+function sprtTilt(p: number, logR1: number, logR0: number, drift: number): number {
+  const g = (h: number) => p * Math.exp(h * logR1) + (1 - p) * Math.exp(h * logR0) - 1;
+  const side = drift > 0 ? -1 : 1;
+  let hi = 1;
+  while (hi <= 1 << 20 && !(g(side * hi) > 0)) hi *= 2;
+  if (!(g(side * hi) > 0)) return side * Infinity;
+  let lo = 0;
+  for (let i = 0; i < 200 && hi - lo > Math.max(1e-16, hi * 1e-16); i++) {
+    const mid = (lo + hi) / 2;
+    if (g(side * mid) > 0) hi = mid;
+    else lo = mid;
+  }
+  return (side * (lo + hi)) / 2;
+}
+
+/**
+ * Expected sample number for Wald's SPRT under a true rate p (Wald's
+ * approximation).
+ *
+ * `(L₁·log A + (1−L₁)·log B) / E_p[log λ]`, where `L₁` is the probability of
+ * finishing at the H₁ wall. Exactness here is about `L₁` and not about the
+ * result: the formula treats the test as stopping exactly on a wall, where a
+ * real one overshoots it, so the answer under-states the true expected sample
+ * number. `L₁` is Wald's operating characteristic in exact form,
+ * `(1 − B^h) / (A^h − B^h)` at the tilt `h` above, rather than the
+ * textbook three-point interpolation: both the numerator and the drift have to
+ * change sign at the same rate, and an interpolation that misses that rate by
+ * even a little returns a *negative* number of runs. The version this replaces
+ * interpolated `L₁` as `(p − p1)/(p0 − p1)`, which rises from 0 at `p1` to 1 at
+ * `p0` where the OC falls from `1 − β` to `α`, so it matched neither hypothesis
+ * and came out negative over most of the corridor. Every caller here tests the
+ * result for `> 0` and falls back to `maxTrials`, so a case landing in the
+ * corridor was priced at the per-case cap: a 9/30 baseline, whose posterior
+ * median sits above its own rate, costs 32 runs and was quoted at 96.
+ * `test/exports.test.ts` pins both the positivity and that case.
+ */
+export function sprtExpectedN(p: number, p0: number, p1: number, alpha = 0.05, beta = 0.1): number {
+  requireProbability(p, "p", "sprtExpectedN");
+  requireProbability(p0, "p0", "sprtExpectedN");
+  requireProbability(p1, "p1", "sprtExpectedN");
+  // Same two walls as `sprtDecision`, and the same gap. The consequence here is
+  // quieter and worse: an alpha at or above 1 makes `B` the log of a negative
+  // number and the quotient NaN, and an alpha of 0 sends `A` to Infinity.
+  // `plan.ts` and `frontier.ts` both gate on `Number.isFinite(raw) && raw > 0`
+  // and quote `maxTrials` when that fails, which both answers do, so a plan
+  // built on an out-of-range error rate priced every case at the per-case cap
+  // and reported it as a budget, with nothing to say it was not a real answer.
+  requireOpenProbability(alpha, "alpha", "sprtExpectedN");
+  requireOpenProbability(beta, "beta", "sprtExpectedN");
+  const A = Math.log((1 - beta) / alpha);
+  const B = Math.log(beta / (1 - alpha));
+  const logR1 = Math.log(p1 / p0);
+  const logR0 = Math.log((1 - p1) / (1 - p0));
+  const drift = p * logR1 + (1 - p) * logR0;
+  const second = p * logR1 * logR1 + (1 - p) * logR0 * logR0;
+  // p0 === p1 leaves every trial uninformative, so the drift and the curvature
+  // are both 0 and no number of runs ends the test.
+  if (second === 0) return Infinity;
+  // `A === B` is `alpha + beta === 1`: both walls sit at a log likelihood ratio
+  // of 0, which is where the test starts, so it decides before it has seen
+  // anything and the expected sample number is 0. The general form is
+  // `(L1·(A − B) + B) / drift`, which is 0 whatever `L1` is, but it computes
+  // `L1` as `(1 − B^h) / (A^h − B^h)`, a genuine 0/0 here, and so returned NaN
+  // for in-domain error rates: (0.5, 0.5) and (0.25, 0.75) both landed on it.
+  // The neighbouring configurations already converge to 0 from both sides.
+  // Only the pairs where both logs round to exactly 0 were affected, which is
+  // why this survived the error-rate guards above.
+  if (A === B) return 0;
+  // The ASN is 0/0 where the tilt vanishes, and that limit is the one place
+  // Wald's formula needs a different expression. What decides whether the
+  // quotient is really 0/0 is the *tilt*, not the drift: near the zero
+  // `h = −2·drift / second`, and `second` scales with the square of the gap
+  // between the hypotheses, so one fixed threshold on `|drift|` means a
+  // different threshold on `h` for every pair of them. A guard of
+  // `|drift| < 1e-6` covered the whole corridor of any pair closer together
+  // than about an `mde` of 1e-3, including the two hypotheses themselves, where
+  // `h` is exactly −1 and +1 and the general form reproduces Wald's endpoint
+  // values rather than merely approaching them: for (0.5, 0.4999) it returned
+  // 1.37x Wald's value at `p1` and 1.63x at `p0`, which is the one property
+  // this function is documented to preserve. Scaling by `second` fires on a
+  // vanishing tilt instead.
+  //
+  // The constant is a minimax between the two forms. The limit is first order
+  // in the tilt, so its error is of order `|h|` and wants the threshold small;
+  // the general form differences exponentials that vanish with the drift, twice
+  // over, so its error grows as `|h|` shrinks and wants it large. They cross
+  // near 3e-4: `test/exports.test.ts` walks the band in tilt across every pair
+  // it checks and pins the gap either side of the seam under 2e-3.
+  if (2 * Math.abs(drift) < 3e-4 * second) return (-A * B) / second;
+  const h = sprtTilt(p, logR1, logR0, drift);
+  return (sprtAcceptH1(h, A, B, drift) * (A - B) + B) / drift;
+}
+
+/**
+ * Wald's operating characteristic at the tilt `h`: the probability the test
+ * finishes at the H₁ wall, `(1 − B^h) / (A^h − B^h)`.
+ *
+ * `A` and `B` arrive as logs, and `|h|` reaches the hundreds for a rate far
+ * outside the two hypotheses, so the two powers are evaluated relative to
+ * whichever of them is largest. Written as plain `exp`, a tilt of −662, which is
+ * p = 0.0025 against p₀ = 0.999 and p₁ = 0.99, overflows `B^h` to Infinity and
+ * the ratio comes back NaN; `expectedSequentialSamples` and
+ * `typicalObservationsPerCase` both test the result for `> 0`, so a NaN there
+ * silently prices the case at `maxTrials`.
+ */
+function sprtAcceptH1(h: number, A: number, B: number, drift: number): number {
+  // No tilt exists at p = 0 or p = 1: one outcome is impossible, so the drift
+  // never reverses and the wall it reaches is certain.
+  if (!Number.isFinite(h)) return drift > 0 ? 1 : 0;
+  const a = h * A;
+  const b = h * B;
+  const m = Math.max(0, a, b);
+  return (Math.exp(-m) - Math.exp(b - m)) / (Math.exp(a - m) - Math.exp(b - m));
+}
+
+/* ───────────────────── multiple-comparison correction ────────────────── */
+
+export interface BhResult {
+  /** rejected[i] === true ⇒ case i is a discovery at FDR ≤ q */
+  rejected: boolean[];
+  /** BH-adjusted p-values (monotone step-up), aligned with the input order */
+  adjusted: number[];
+  /** the largest raw p-value that was rejected, or 0 if none */
+  cutoff: number;
+  discoveries: number;
+}
+
+/**
+ * Benjamini-Hochberg FDR control.
+ * With 200 cases at α=0.05 you expect ~10 false alarms per clean run; BH is why
+ * a green suite stays green.
+ */
+export function bhCorrect(pvalues: number[], q = 0.05): BhResult {
+  // A NaN here does not throw, it silently corrupts the sort and therefore the
+  // whole step-up, so it is caught rather than propagated.
+  for (let i = 0; i < pvalues.length; i++) {
+    requireProbability(pvalues[i]!, `p[${i}]`, "bhCorrect");
+  }
+  requireProbability(q, "q", "bhCorrect");
+  const m = pvalues.length;
+  const rejected = new Array<boolean>(m).fill(false);
+  const adjusted = new Array<number>(m).fill(1);
+  if (m === 0) return { rejected, adjusted, cutoff: 0, discoveries: 0 };
+  const order = pvalues.map((p, i) => ({ p, i })).sort((a, b) => a.p - b.p);
+  let kMax = -1;
+  for (let k = 0; k < m; k++) if (order[k]!.p <= ((k + 1) / m) * q) kMax = k;
+  for (let k = 0; k <= kMax; k++) rejected[order[k]!.i] = true;
+  // step-up monotone adjustment: q(k) = min_{j ≥ k} ( m/j · p(j) )
+  let running = 1;
+  for (let k = m - 1; k >= 0; k--) {
+    running = Math.min(running, (m / (k + 1)) * order[k]!.p);
+    adjusted[order[k]!.i] = Math.min(1, running);
+  }
+  return {
+    rejected,
+    adjusted,
+    cutoff: kMax >= 0 ? order[kMax]!.p : 0,
+    discoveries: kMax + 1,
+  };
+}
+
+/**
+ * Log marginal likelihood of s successes in n Bernoulli trials when the rate
+ * carries a Beta(a,b) prior, the beta-binomial, minus the C(n,s) term (which
+ * cancels in every ratio we take).
+ */
+export function logMarginalBetaBinomial(s: number, n: number, a: number, b: number): number {
+  // `s` may be fractional here, the planner evaluates the mean trajectory, so
+  // this checks the range rather than integrality.
+  if (!Number.isFinite(s) || !Number.isFinite(n) || s < 0 || n < 0 || s > n) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `logMarginalBetaBinomial: need 0 ≤ s ≤ n, got ${s}/${n}`,
+      {
+        detail: { s, n },
+      },
+    );
+  }
+  if (!(a > 0) || !(b > 0) || !Number.isFinite(a) || !Number.isFinite(b)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "logMarginalBetaBinomial: prior parameters must be finite and positive",
+      {
+        detail: { a, b },
+      },
+    );
+  }
+  return logBeta(a + s, b + n - s) - logBeta(a, b);
+}
+
+/**
+ * A prior concentration, which multiplies a rate to make Beta shapes. Every
+ * caller floors the product, so a non-positive concentration does not
+ * produce a bad shape, it produces a floored Beta and a plausible number
+ * from a prior nobody asked for.
+ */
+function requireConcentration(k: number, name: string, where: string): void {
+  if (!(k > 0) || !Number.isFinite(k)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `${where}: ${name} must be finite and positive`,
+      {
+        detail: { [name]: k },
+      },
+    );
+  }
+}
+
+// Below 1 a shape piles alternative mass onto 0 or 1, which pushed type I error past alpha for thin baselines.
+const ALT_SHAPE_FLOOR = 1;
+
+/**
+ * A **two-sample e-value** for "the candidate is worse than the baseline".
+ *
+ * The one-sample alternative, test the candidate against the baseline's point
+ * estimate, quietly assumes the baseline rate is known. It is not: it came
+ * from 24 noisy runs, and a baseline that got lucky manufactures regressions
+ * that were never there.
+ *
+ * So the null keeps the baseline's uncertainty: p ~ Beta(1+s_b, 1+f_b), and the
+ * alternative is the same amount of information centred `mde` lower. The ratio
+ * of the two marginal likelihoods is a Bayes factor, and a Bayes factor between
+ * two joint distributions of the same sequence is a non-negative martingale
+ * with mean 1 under the null's own marginal, here the shared rate drawn from
+ * the uniform prior. At a fixed rate the mean can exceed 1, so the frequentist
+ * type I error is checked exactly in `test/error-control.test.ts` instead.
+ */
+export function twoSampleLogE(
+  candidateSuccesses: number,
+  candidateTrials: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  /**
+   * Concentration of the alternative prior. Low values spread the alternative
+   * over "anything materially worse", which is what actually happens when a
+   * change breaks a case, it rarely lands exactly `mde` below.
+   */
+  altConcentration = 8,
+): number {
+  // The central evidence primitive, and the one every verdict rests on, so it
+  // gets the same domain discipline as everything else in this file rather
+  // than turning `5 successes in 3 trials` into a plausible-looking Bayes
+  // factor. (Found in adversarial review; it was the one function that skipped
+  // the contract its own module header states.)
+  requireCounts(candidateSuccesses, candidateTrials, "twoSampleLogE(candidate)");
+  requireCounts(baselineSuccesses, baselineTrials, "twoSampleLogE(baseline)");
+  // Open, not closed: `requireProbability` here accepted an mde of 0 and 1,
+  // which `gate`, `shouldStop`, `makePlan` and `twoSamplePriors` all refuse, so
+  // the primitive was looser than every entry point that calls it.
+  requireOpenProbability(mde, "mde", "twoSampleLogE");
+  requireConcentration(altConcentration, "altConcentration", "twoSampleLogE");
+  const a0 = 1 + baselineSuccesses;
+  const b0 = 1 + baselineTrials - baselineSuccesses;
+  const kappa = a0 + b0;
+  const shifted = Math.min(0.995, Math.max(0.005, a0 / kappa - mde));
+  const k1 = altConcentration;
+  const a1 = Math.max(ALT_SHAPE_FLOOR, k1 * shifted);
+  const b1 = Math.max(ALT_SHAPE_FLOOR, k1 * (1 - shifted));
+  const logE =
+    logMarginalBetaBinomial(candidateSuccesses, candidateTrials, a1, b1) -
+    logMarginalBetaBinomial(candidateSuccesses, candidateTrials, a0, b0);
+  return atOrAboveBaseline(candidateSuccesses / candidateTrials, baselineSuccesses, baselineTrials)
+    ? Math.min(0, logE)
+    : logE;
+}
+
+/**
+ * The alternative is wider than the null, so the Bayes factor alone also grows
+ * for a candidate far ABOVE its baseline: 96/96 against 30/60 scored e^19.5 and
+ * gate certified that improvement as a regression. A candidate observed at or
+ * above the baseline's rate is therefore held to e ≤ 1. Lowering an e-value
+ * never breaks one, so every guarantee above still holds.
+ */
+const atOrAboveBaseline = (
+  candidateRate: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+): boolean => baselineTrials > 0 && candidateRate >= baselineSuccesses / baselineTrials;
+
+/**
+ * e-BH, Benjamini-Hochberg for **e-values** (Wang & Ramdas).
+ *
+ * Why this exists: a p-value computed after optional stopping is not a
+ * p-value. The likelihood ratio a sequential test accumulates *is* a valid
+ * e-value under H₀ (it is a non-negative martingale, so Ville's inequality
+ * gives P(sup LR ≥ 1/α) ≤ α), and it stays valid if you keep sampling, which
+ * is exactly what peeksafe does to confirm a flagged case.
+ *
+ * Reject the k largest e-values where k* = max{ k : e₍ₖ₎ ≥ m / (q·k) }.
+ * Controls FDR at q under *arbitrary* dependence between cases.
+ */
+export interface EbhResult {
+  rejected: boolean[];
+  discoveries: number;
+  /** the e-value a case had to beat, given how many discoveries were made */
+  threshold: number;
+}
+
+export function ebhCorrect(evalues: number[], q = 0.05): EbhResult {
+  for (let i = 0; i < evalues.length; i++) {
+    const e = evalues[i]!;
+    if (!Number.isFinite(e) || e < 0) {
+      throw new PeeksafeError(
+        "PEEKSAFE_E_STAT_DOMAIN",
+        `ebhCorrect: e[${i}] must be finite and ≥ 0, got ${e}`,
+        {
+          detail: { index: i, value: e },
+          hint: "an e-value is a non-negative random variable with mean ≤ 1 under the null; Infinity and NaN corrupt the ranking",
+        },
+      );
+    }
+  }
+  requireProbability(q, "q", "ebhCorrect");
+  const m = evalues.length;
+  const rejected = new Array<boolean>(m).fill(false);
+  if (m === 0) return { rejected, discoveries: 0, threshold: Infinity };
+  const order = evalues.map((e, i) => ({ e, i })).sort((a, b) => b.e - a.e);
+  let kStar = 0;
+  for (let k = 1; k <= m; k++) if (order[k - 1]!.e >= m / (q * k)) kStar = k;
+  for (let k = 0; k < kStar; k++) rejected[order[k]!.i] = true;
+  return { rejected, discoveries: kStar, threshold: kStar > 0 ? m / (q * kStar) : m / q };
+}
+
+/** The e-value a case must reach to be certain of rejection whatever the others do. */
+export const ebhSoloThreshold = (m: number, q = 0.05): number => m / q;
+
+/* ──────────────────────────────── planning ──────────────────────────── */
+
+/**
+ * Fixed-N sample size per arm for detecting a `delta` drop from `p0` at the
+ * given error rates. This is the "naive approach" peeksafe is measured against.
+ *
+ * Returns **Infinity** when the effect is one the case cannot suffer, a case
+ * whose baseline rate is 10% cannot lose 15 points, and no number of samples
+ * will find a drop that is arithmetically impossible. The old version clamped
+ * `p1` to 1e-6 and answered "44 runs", which is a plausible-looking lie
+ * and exactly the sort of thing a budget planner must not do.
+ */
+export function sampleSizeTwoProportion(
+  p0: number,
+  delta: number,
+  alpha = 0.05,
+  beta = 0.1,
+): number {
+  requireProbability(p0, "p0", "sampleSizeTwoProportion");
+  // Checked before the Infinity branch, so the same error rate is refused
+  // whatever the effect. An alpha of 1 sets `zA` to Φ⁻¹(0.5) = 0, which drops
+  // the type I error term out of the formula and answers a run count for a
+  // design with no error control in it. This is the comparator the README
+  // measures peeksafe against, so a plausible number here understates what the
+  // naive design costs.
+  requireOpenProbability(alpha, "alpha", "sampleSizeTwoProportion");
+  requireOpenProbability(beta, "beta", "sampleSizeTwoProportion");
+  if (delta <= 0 || delta >= p0) return Infinity;
+  const p1 = p0 - delta;
+  const pbar = (p0 + p1) / 2;
+  const zA = normalQuantile(1 - alpha / 2);
+  const zB = normalQuantile(1 - beta);
+  const n =
+    (zA * Math.sqrt(2 * pbar * (1 - pbar)) + zB * Math.sqrt(p0 * (1 - p0) + p1 * (1 - p1))) ** 2 /
+    (delta * delta);
+  return Math.ceil(n);
+}
+
+/** Shannon entropy in bits of a Bernoulli(p), used as a raw instability signal. */
+export function bernoulliEntropy(p: number): number {
+  requireProbability(p, "p", "bernoulliEntropy");
+  return p <= 0 || p >= 1 ? 0 : -(p * Math.log2(p) + (1 - p) * Math.log2(1 - p));
+}
+
+/* ═══════════════════ power economics: what will this cost? ════════════════
+ *
+ * Everything below exists to answer one question before any money is spent:
+ * "given this baseline, how many runs does detecting an `mde`-point drop take,
+ * and are there cases where the answer is *no number*?"
+ */
+
+/** log of the Beta(a,b) density at p. */
+export function logBetaPdf(p: number, a: number, b: number): number {
+  requireProbability(p, "p", "logBetaPdf");
+  if (p <= 0 || p >= 1) {
+    // density is 0 or ∞ at the boundary depending on the shape; the planner
+    // only ever evaluates strictly inside, so clamp rather than return ±∞.
+    p = Math.min(1 - 1e-12, Math.max(1e-12, p));
+  }
+  return (a - 1) * Math.log(p) + (b - 1) * Math.log(1 - p) - logBeta(a, b);
+}
+
+/** The two prior shapes `twoSampleLogE` compares. Exposed so the planner can
+ *  reason about the *limit* of the evidence, not just its value at some n. */
+export function twoSamplePriors(
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  altConcentration = 8,
+): { nullPrior: { a: number; b: number }; altPrior: { a: number; b: number } } {
+  requireCounts(baselineSuccesses, baselineTrials, "twoSamplePriors");
+  // The floor below is what makes an unguarded concentration dangerous rather
+  // than merely wrong: at `altConcentration <= 0` both shapes collapse onto it
+  // and the caller gets a decision from Beta(1, 1) instead of an error.
+  // `twoSampleLogE` guarded itself and this did not, so the same option threw
+  // on `evidence: 'bayes'` and silently moved the verdict on `'universal'`.
+  requireConcentration(altConcentration, "altConcentration", "twoSamplePriors");
+  // `mde` was the same gap one argument over, and the clamp below hides it the
+  // same way: `Math.min(0.995, Math.max(0.005, ...))` turns a negative mde into
+  // an alternative centred *above* the baseline, so asking to detect a drop of
+  // -15 points returned evidence rather than a refusal. The endpoints are out
+  // too, because mde is an effect and not a rate: a drop of 0 is one every
+  // design answers "no" to for reasons that look like a ceiling problem.
+  requireOpenProbability(mde, "mde", "twoSamplePriors");
+  const a0 = 1 + baselineSuccesses;
+  const b0 = 1 + baselineTrials - baselineSuccesses;
+  const kappa = a0 + b0;
+  const shifted = Math.min(0.995, Math.max(0.005, a0 / kappa - mde));
+  return {
+    nullPrior: { a: a0, b: b0 },
+    altPrior: {
+      a: Math.max(ALT_SHAPE_FLOOR, altConcentration * shifted),
+      b: Math.max(ALT_SHAPE_FLOOR, altConcentration * (1 - shifted)),
+    },
+  };
+}
+
+/**
+ * The **evidence ceiling** of the unpaired two-sample e-value.
+ *
+ * This is the single most useful number the planner has, and it is not
+ * obvious: the two-sample Bayes factor does *not* grow without bound in the
+ * number of candidate runs. Both marginals are the same binomial likelihood
+ * under different priors, so by Laplace approximation
+ *
+ *     log m_a(s, n) = n·h(p̂) + log f_a(p̂) + ½log(2π p̂(1−p̂)/n) + O(1/n)
+ *
+ * and every term except `log f(p̂)` is common to numerator and denominator.
+ * The ratio therefore converges to the **prior density ratio at the observed
+ * rate**:
+ *
+ *     lim_{n→∞} log E  =  log f_alt(p) − log f_null(p)
+ *
+ * Consequences `gate` and `makePlan` report directly:
+ *   - a case whose ceiling sits below the e-BH bar `m/(q·k)` is **undetectable
+ *     at any budget**: buying more candidate runs cannot certify it;
+ *   - the remedy is more *baseline* runs, which sharpen f_null and raise the
+ *     ceiling, that is the amortised baseline, quantified;
+ *   - the paired design (`pairedLogE`) has no such ceiling, because its null is
+ *     an exact point mass at ½ rather than an estimated prior.
+ */
+export function evidenceCeilingLogE(
+  pTrue: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  altConcentration = 8,
+): number {
+  requireProbability(pTrue, "pTrue", "evidenceCeilingLogE");
+  const { nullPrior, altPrior } = twoSamplePriors(
+    baselineSuccesses,
+    baselineTrials,
+    mde,
+    altConcentration,
+  );
+  const ceiling =
+    logBetaPdf(pTrue, altPrior.a, altPrior.b) - logBetaPdf(pTrue, nullPrior.a, nullPrior.b);
+  return atOrAboveBaseline(pTrue, baselineSuccesses, baselineTrials)
+    ? Math.min(0, ceiling)
+    : ceiling;
+}
+
+/**
+ * The **rate** at which the evidence ceiling grows in baseline runs: the
+ * Kullback-Leibler divergence `KL(p_b ‖ p)` in nats, with the *baseline* rate
+ * as the first argument.
+ *
+ * This is not the obvious direction, and getting it the wrong way round gives a
+ * materially different number (at 85% losing 15 points: 0.0611 the right way,
+ * 0.0720 the wrong way). It falls out of the Laplace expansion of the null
+ * prior's own density, see `evidenceCeilingAsymptotic`.
+ */
+export function evidenceCeilingSlope(pBaseline: number, pCandidate: number): number {
+  requireProbability(pBaseline, "pBaseline", "evidenceCeilingSlope");
+  requireProbability(pCandidate, "pCandidate", "evidenceCeilingSlope");
+  const a = Math.min(1 - 1e-12, Math.max(1e-12, pBaseline));
+  const b = Math.min(1 - 1e-12, Math.max(1e-12, pCandidate));
+  return a * Math.log(a / b) + (1 - a) * Math.log((1 - a) / (1 - b));
+}
+
+/**
+ * The evidence ceiling in closed form, to O(1/n_b).
+ *
+ * `evidenceCeilingLogE` evaluates the exact prior density ratio. This says what
+ * that ratio *is*, as a function of the baseline size, and it is the useful
+ * form because it inverts:
+ *
+ *     ceiling(n_b) ≈ n_b · KL(p̄_b ‖ p) + log f_alt(p) + ½·log(2π p̄_b(1−p̄_b)/n_b)
+ *
+ * The leading term comes from Stirling on the null prior's normaliser:
+ * `f_null` is a Beta posterior, its log density at `p` is
+ * `−n_b·KL(p̄_b ‖ p) − ½log(2π p̄_b(1−p̄_b)/n_b) + O(1/n_b)`, and the alternative
+ * prior does not move with `n_b` at all.
+ *
+ * Two consequences that are the practical point of the whole ceiling result:
+ *
+ *  - **the ceiling grows linearly in baseline runs**, at a rate that is a
+ *    property of the case's pass rate and the MDE and of nothing else;
+ *  - so the baseline size a case needs to be detectable at all is roughly
+ *    `log(m/q) / KL(p̄_b ‖ p̄_b − δ)`, an O(1) formula where `plan.ts` searches.
+ *    It is a *lower* bound: the two lower-order terms are negative at realistic
+ *    `n_b`, so the honest quote is that rule of thumb plus about 20%, and
+ *    `makePlan` keeps reporting the exact search.
+ *
+ * Matches `evidenceCeilingLogE` to better than 0.1% for `n_b ≥ 240`; checked in
+ * `test/paper.test.ts`.
+ */
+export function evidenceCeilingAsymptotic(
+  baselineSuccesses: number,
+  baselineTrials: number,
+  pTrue: number,
+  mde: number,
+  altConcentration = 8,
+): number {
+  requireCounts(baselineSuccesses, baselineTrials, "evidenceCeilingAsymptotic");
+  requireProbability(pTrue, "pTrue", "evidenceCeilingAsymptotic");
+  if (baselineTrials === 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "evidenceCeilingAsymptotic: needs at least one baseline trial",
+      {
+        detail: { baselineTrials },
+        hint: "with no baseline there is no null to be uncertain about; use evidenceCeilingLogE, which handles the prior directly",
+      },
+    );
+  }
+  // The expansion is a Laplace approximation around an *interior* rate. A
+  // baseline of all passes or all failures has none, and the ½·log(2π p̄(1−p̄)/n)
+  // term goes to −∞, which came back as a finite-looking -Infinity rather than
+  // an error. `evidenceCeilingLogE` handles those cases exactly; this does not.
+  if (baselineSuccesses === 0 || baselineSuccesses === baselineTrials) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `evidenceCeilingAsymptotic: the expansion needs an interior baseline rate, got ${baselineSuccesses}/${baselineTrials}`,
+      {
+        detail: { baselineSuccesses, baselineTrials },
+        hint: "use evidenceCeilingLogE, which evaluates the prior density ratio exactly and is defined at the boundary",
+      },
+    );
+  }
+  // Around the observed baseline rate s/n, with n the baseline trial count. The
+  // null prior is Beta(1+s, 1+n−s), so its shape parameters minus one are
+  // exactly (s, n−s) and the Stirling expansion closes on s/n, shifting to the
+  // posterior mean (s+1)/(n+2) instead leaves a residual that does *not* vanish.
+  const pBar = baselineSuccesses / baselineTrials;
+  const n = baselineTrials;
+  const { altPrior } = twoSamplePriors(baselineSuccesses, baselineTrials, mde, altConcentration);
+  return (
+    n * evidenceCeilingSlope(pBar, pTrue) +
+    logBetaPdf(pTrue, altPrior.a, altPrior.b) +
+    0.5 * Math.log((2 * Math.PI * pBar * (1 - pBar)) / n)
+  );
+}
+
+/**
+ * The two-sample log e-value along the **mean trajectory**: the value it takes
+ * when the candidate scores exactly its expected `pTrue·n` successes in `n`
+ * runs. Fractional successes are legal, the beta-binomial marginal is a ratio
+ * of Beta functions, which is defined on the reals.
+ *
+ * This is a plug-in for E[log E], not E[log E] itself. `expectedLogEExact`
+ * computes the true expectation by summing over the binomial.
+ */
+export function expectedLogE(
+  pTrue: number,
+  n: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  altConcentration = 8,
+): number {
+  requireProbability(pTrue, "pTrue", "expectedLogE");
+  if (!(n >= 0) || !Number.isFinite(n)) {
+    throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", "expectedLogE: n must be finite and ≥ 0", {
+      detail: { n },
+    });
+  }
+  const { nullPrior: n0, altPrior: a1 } = twoSamplePriors(
+    baselineSuccesses,
+    baselineTrials,
+    mde,
+    altConcentration,
+  );
+  const s = pTrue * n;
+  const logE =
+    logBeta(a1.a + s, a1.b + n - s) -
+    logBeta(a1.a, a1.b) -
+    (logBeta(n0.a + s, n0.b + n - s) - logBeta(n0.a, n0.b));
+  return n > 0 && atOrAboveBaseline(pTrue, baselineSuccesses, baselineTrials)
+    ? Math.min(0, logE)
+    : logE;
+}
+
+/** E[log E] computed exactly, by summing over every binomial outcome. O(n). */
+export function expectedLogEExact(
+  pTrue: number,
+  n: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  altConcentration = 8,
+): number {
+  requireProbability(pTrue, "pTrue", "expectedLogEExact");
+  if (!Number.isInteger(n) || n < 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "expectedLogEExact: n must be a non-negative integer",
+      { detail: { n } },
+    );
+  }
+  let acc = 0;
+  for (let s = 0; s <= n; s++) {
+    const logW =
+      logGamma(n + 1) -
+      logGamma(s + 1) -
+      logGamma(n - s + 1) +
+      s * Math.log(Math.max(1e-300, pTrue)) +
+      (n - s) * Math.log(Math.max(1e-300, 1 - pTrue));
+    acc +=
+      Math.exp(logW) *
+      twoSampleLogE(s, n, baselineSuccesses, baselineTrials, mde, altConcentration);
+  }
+  return acc;
+}
+
+/**
+ * Smallest number of candidate runs whose mean-trajectory log e-value clears
+ * `logThreshold`. Returns **Infinity** when the ceiling is below the threshold
+ *, the honest answer to "how many runs would it take", when the answer is
+ * that no number of runs will do.
+ */
+export function samplesForEvidence(
+  pTrue: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  logThreshold: number,
+  maxN = 100_000,
+  altConcentration = 8,
+): number {
+  const ceiling = evidenceCeilingLogE(
+    pTrue,
+    baselineSuccesses,
+    baselineTrials,
+    mde,
+    altConcentration,
+  );
+  if (!(ceiling > logThreshold)) return Infinity;
+  const f = (n: number) =>
+    expectedLogE(pTrue, n, baselineSuccesses, baselineTrials, mde, altConcentration);
+  // exponential search then bisection; f is monotone in n below the ceiling
+  let hi = 1;
+  while (hi < maxN && f(hi) < logThreshold) hi *= 2;
+  if (f(hi) < logThreshold) return Infinity;
+  let lo = Math.floor(hi / 2);
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (f(mid) >= logThreshold) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}
+
+/* ──────────────── the always-valid two-sample e-value ───────────────────
+ *
+ * `twoSampleLogE` has mean 1 averaged over the shared rate, not at every fixed
+ * rate. This one is valid at every rate by construction (universal inference,
+ * Wasserman, Ramdas and Balakrishnan 2020): the numerator is a single joint
+ * distribution of baseline and candidate, the uniform mixture for the baseline
+ * followed by the same alternative `twoSampleLogE` uses for the candidate, and
+ * the denominator is the largest likelihood any null rate pair gives the data.
+ * For every null pair the numerator over that pair's likelihood is a test
+ * martingale, and the maximum only lowers it, so Ville's inequality holds.
+ *
+ * It equals `twoSampleLogE` times the uniform mixture of all the data over its
+ * maximum likelihood, so it is never larger, and the price is roughly
+ * ½·log(runs) of evidence. Blocked designs (Turner, Ly and Grünwald's 2x2
+ * e-values) avoid that price but need both arms in every block; a stored
+ * baseline followed by candidate-only runs gives them nothing to work with.
+ */
+
+const xlogy = (x: number, y: number): number => (x === 0 ? 0 : x * Math.log(y));
+const logLik = (s: number, n: number, p: number): number => xlogy(s, p) + xlogy(n - s, 1 - p);
+
+/** Largest log likelihood of the data under the null "candidate rate ≥ baseline rate". */
+function logNullSup(cs: number, cn: number, bs: number, bn: number): number {
+  const pb = bs / bn;
+  const pc = cn > 0 ? cs / cn : 1;
+  return pc >= pb
+    ? logLik(bs, bn, pb) + logLik(cs, cn, pc)
+    : logLik(bs + cs, bn + cn, (bs + cs) / (bn + cn));
+}
+
+/**
+ * The two-sample e-value for "the candidate is worse than the baseline", valid
+ * at every pair of rates and at any stopping time. Same arguments as
+ * `twoSampleLogE`, which it never exceeds.
+ */
+export function universalTwoSampleLogE(
+  candidateSuccesses: number,
+  candidateTrials: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+  mde: number,
+  altConcentration = 8,
+): number {
+  requireCounts(candidateSuccesses, candidateTrials, "universalTwoSampleLogE(candidate)");
+  requireCounts(baselineSuccesses, baselineTrials, "universalTwoSampleLogE(baseline)");
+  if (baselineTrials === 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "universalTwoSampleLogE: needs at least one baseline trial",
+      {
+        detail: { baselineTrials },
+      },
+    );
+  }
+  const { altPrior } = twoSamplePriors(baselineSuccesses, baselineTrials, mde, altConcentration);
+  const logQ =
+    logBeta(1 + baselineSuccesses, 1 + baselineTrials - baselineSuccesses) +
+    logMarginalBetaBinomial(candidateSuccesses, candidateTrials, altPrior.a, altPrior.b);
+  return logQ - logNullSup(candidateSuccesses, candidateTrials, baselineSuccesses, baselineTrials);
+}
+
+/**
+ * An upper bound on `universalTwoSampleLogE` over every future candidate run
+ * count, for a candidate observed at rate `pTrue`. It plays the part
+ * `evidenceCeilingLogE` plays for the default statistic.
+ *
+ * The alternative's marginal is at most the candidate's maximum likelihood, and
+ * the pooled likelihood ratio is at most `n_b · KL(p̂_b ‖ pTrue)`, so the bound
+ * is the baseline's mixture over its maximum likelihood plus that term.
+ */
+export function universalCeilingLogE(
+  pTrue: number,
+  baselineSuccesses: number,
+  baselineTrials: number,
+): number {
+  requireProbability(pTrue, "pTrue", "universalCeilingLogE");
+  requireCounts(baselineSuccesses, baselineTrials, "universalCeilingLogE");
+  if (baselineTrials === 0) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      "universalCeilingLogE: needs at least one baseline trial",
+      {
+        detail: { baselineTrials },
+      },
+    );
+  }
+  const pb = baselineSuccesses / baselineTrials;
+  const occam =
+    logBeta(1 + baselineSuccesses, 1 + baselineTrials - baselineSuccesses) -
+    logLik(baselineSuccesses, baselineTrials, pb);
+  if (pTrue >= pb) return occam;
+  const p = Math.max(1e-12, pTrue);
+  return occam + baselineTrials * (xlogy(pb, pb / p) + xlogy(1 - pb, (1 - pb) / (1 - p)));
+}
+
+/* ─────────────────── paired (matched) comparison, McNemar ────────────────
+ *
+ * Run the candidate and the baseline on the *same* input and the *same* seed
+ * and you get matched pairs. Concordant pairs (both pass, both fail) carry no
+ * information about a difference; the discordant ones do, and under the null
+ * "nothing changed" the direction of a discordance is an exact coin flip.
+ *
+ * That exactness is the whole prize. The unpaired e-value has to keep the
+ * baseline's own uncertainty inside its null, which is what caps its evidence.
+ * The paired null is θ = ½, not estimated, not shrunk, *exact* by
+ * exchangeability, so the paired e-value grows linearly in the number of
+ * discordant pairs and has no ceiling.
+ */
+
+export interface PairedCounts {
+  /** both arms passed */
+  bothPass: number;
+  /** baseline passed, candidate failed, the direction that indicates a regression */
+  worse: number;
+  /** candidate passed, baseline failed */
+  better: number;
+  /** both arms failed */
+  bothFail: number;
+}
+
+export const discordant = (p: PairedCounts): number => p.worse + p.better;
+
+/**
+ * Phi coefficient of the 2×2 pair table, how well the pairing actually
+ * coupled the two arms. 0 means the seeds bought nothing (the arms are
+ * independent and you may as well not have paired); 1 means perfect coupling.
+ * This is the number the variance-reduction claim has to be measured against,
+ * not assumed.
+ */
+export function pairPhi(p: PairedCounts): number {
+  const { bothPass: a, worse: b, better: cc, bothFail: d } = p;
+  for (const [name, v] of [
+    ["bothPass", a],
+    ["worse", b],
+    ["better", cc],
+    ["bothFail", d],
+  ] as const) {
+    if (!Number.isInteger(v) || v < 0) {
+      throw new PeeksafeError(
+        "PEEKSAFE_E_STAT_DOMAIN",
+        `pairPhi: ${name} must be a non-negative integer, got ${v}`,
+        {
+          detail: { counts: p },
+        },
+      );
+    }
+  }
+  const n = a + b + cc + d;
+  if (n === 0) return 0;
+  const den = Math.sqrt((a + b) * (cc + d) * (a + cc) * (b + d));
+  return den === 0 ? 0 : (a * d - b * cc) / den;
+}
+
+/**
+ * A **paired e-value** for "the candidate is worse".
+ *
+ * Null: each discordant pair points the wrong way with probability at most ½.
+ * Alternative: it points the wrong way with probability θ ~ Beta centred on
+ * `thetaAlt`, truncated to θ > ½. Every θ in that support gives a likelihood
+ * ratio against ½ that is a supermartingale whenever the true probability is
+ * ½ or less, so the mixture is an e-value valid under optional stopping for a
+ * candidate that is unchanged or better, not only for one that is unchanged.
+ */
+export function pairedLogE(
+  worse: number,
+  discordantPairs: number,
+  thetaAlt = 0.75,
+  concentration = 6,
+): number {
+  requireCounts(worse, discordantPairs, "pairedLogE");
+  requireProbability(thetaAlt, "thetaAlt", "pairedLogE");
+  requireConcentration(concentration, "concentration", "pairedLogE");
+  if (discordantPairs === 0) return 0;
+  const a1 = Math.max(0.35, concentration * thetaAlt);
+  const b1 = Math.max(0.35, concentration * (1 - thetaAlt));
+  return logUpperHalfMarginal(worse, discordantPairs, a1, b1) - discordantPairs * Math.log(0.5);
+}
+
+// The marginal of `w` in `d` under Beta(a, b) restricted to (½, 1]: P(θ > ½ | a, b) is I_½(b, a).
+function logUpperHalfMarginal(w: number, d: number, a: number, b: number): number {
+  return (
+    logBeta(a + w, b + d - w) +
+    Math.log(ibeta(b + d - w, a + w, 0.5)) -
+    logBeta(a, b) -
+    Math.log(ibeta(b, a, 0.5))
+  );
+}
+
+/**
+ * The discordance model a paired plan runs on.
+ *
+ * With probability `rho` the two arms see the same random draw and a
+ * discordance can only occur inside the (p_c, p_b) gap, always in the "worse"
+ * direction. With probability 1−rho they are independent and discordances go
+ * both ways. `rho` is *measured* from a pilot (see `pairPhi`), not assumed.
+ */
+export function pairedDiscordance(
+  pBaseline: number,
+  mde: number,
+  rho: number,
+): { rate: number; theta: number } {
+  requireProbability(pBaseline, "pBaseline", "pairedDiscordance");
+  requireProbability(rho, "rho", "pairedDiscordance");
+  // Checked last and checked here because it was the one argument that was not:
+  // an mde of -0.5 put the candidate above 1, which came back as a discordance
+  // rate of -0.36 and a theta of 1.194, both impossible, neither an error. An
+  // mde is an effect rather than a rate, so the endpoints are out too, which is
+  // where gate, makePlan and evaluatePoint already draw the line.
+  requireOpenProbability(mde, "mde", "pairedDiscordance");
+  const pc = Math.max(0, pBaseline - mde);
+  const coupledWorse = pBaseline - pc;
+  const indepWorse = pBaseline * (1 - pc);
+  const indepBetter = pc * (1 - pBaseline);
+  const worse = rho * coupledWorse + (1 - rho) * indepWorse;
+  const better = (1 - rho) * indepBetter;
+  const rate = worse + better;
+  return { rate, theta: rate === 0 ? 0.5 : worse / rate };
+}
+
+/**
+ * Expected number of **pairs** for the paired e-value to clear `logThreshold`.
+ * One pair costs one candidate run plus one baseline run, so the caller must
+ * double it before comparing with `samplesForEvidence`. Even so it usually
+ * wins, and unlike the unpaired design it never returns Infinity for a real
+ * effect.
+ */
+export function mcnemarSamplesForEvidence(
+  pBaseline: number,
+  mde: number,
+  rho: number,
+  logThreshold: number,
+  maxPairs = 100_000,
+  concentration = 6,
+): number {
+  requireConcentration(concentration, "concentration", "mcnemarSamplesForEvidence");
+  // Every comparison below is a `<` against `logThreshold`, and a NaN loses all
+  // of them: the doubling loop exited on its first test, the Infinity guard did
+  // not fire, and the bisection returned its own starting point. The answer
+  // came back as one pair, where the same design at a real 15pt effect needs
+  // 172. `samplesForEvidence` writes its guard negated and so refuses instead.
+  if (!Number.isFinite(logThreshold)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `mcnemarSamplesForEvidence: logThreshold must be finite, got ${logThreshold}`,
+      {
+        detail: { logThreshold },
+        hint: "this is a log e-value bar, such as Math.log(ebhSoloThreshold(m, fdr))",
+      },
+    );
+  }
+  const { rate, theta } = pairedDiscordance(pBaseline, mde, rho);
+  if (rate <= 0 || theta <= 0.5) return Infinity;
+  const a1 = Math.max(0.35, concentration * theta);
+  const b1 = Math.max(0.35, concentration * (1 - theta));
+  const f = (n: number) =>
+    logUpperHalfMarginal(n * rate * theta, n * rate, a1, b1) - n * rate * Math.log(0.5);
+  let hi = 1;
+  while (hi < maxPairs && f(hi) < logThreshold) hi *= 2;
+  if (f(hi) < logThreshold) return Infinity;
+  let lo = Math.floor(hi / 2);
+  while (hi - lo > 1) {
+    const mid = Math.floor((lo + hi) / 2);
+    if (f(mid) >= logThreshold) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}
+
+/* ───────────────────────── screening statistic ───────────────────────── */
+
+/**
+ * P(p_candidate ≤ p_baseline − mde) under independent Beta posteriors, the
+ * posterior probability that a case *moved*, given whatever handful of runs it
+ * has so far.
+ *
+ * This is the screening score: cheap (one quadrature over `ibeta`), needs only
+ * 3 to 4 candidate runs to be informative, and orders cases by where the
+ * expensive sequential test can actually pay. It is deliberately **not** a
+ * decision, screening decides where to spend, the e-value decides what is
+ * true, and the FDR guarantee is unaffected by which cases you chose to look
+ * at (e-BH is valid under arbitrary dependence, including a data-dependent
+ * choice of which cases to sample further).
+ */
+export function probabilityMoved(
+  baselineSuccesses: number,
+  baselineTrials: number,
+  candidateSuccesses: number,
+  candidateTrials: number,
+  mde: number,
+  nodes = 256,
+): number {
+  requireCounts(baselineSuccesses, baselineTrials, "probabilityMoved(baseline)");
+  requireCounts(candidateSuccesses, candidateTrials, "probabilityMoved(candidate)");
+  // Both were unchecked. A negative mde answered the probability of a rise, and
+  // a node count below 1 skipped the quadrature and answered 0, "did not move".
+  // Checked before the early return so the first call of a loop refuses too.
+  requireOpenProbability(mde, "mde", "probabilityMoved");
+  if (!Number.isInteger(nodes) || nodes < 1) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `probabilityMoved: nodes must be a positive integer, got ${nodes}`,
+      {
+        detail: { nodes },
+      },
+    );
+  }
+  if (candidateTrials === 0) return 0;
+  const a0 = 1 + baselineSuccesses,
+    b0 = 1 + baselineTrials - baselineSuccesses;
+  const a1 = 1 + candidateSuccesses,
+    b1 = 1 + candidateTrials - candidateSuccesses;
+  // Simpson's rule on ∫ f_b(x) · F_c(x − mde) dx over (0,1)
+  const m = nodes % 2 === 0 ? nodes : nodes + 1;
+  const h = 1 / m;
+  let acc = 0;
+  for (let i = 0; i <= m; i++) {
+    const x = Math.min(1 - 1e-9, Math.max(1e-9, i * h));
+    const w = i === 0 || i === m ? 1 : i % 2 === 1 ? 4 : 2;
+    const fb = Math.exp(logBetaPdf(x, a0, b0));
+    const fc = x - mde <= 0 ? 0 : ibeta(a1, b1, Math.min(1, x - mde));
+    acc += w * fb * fc;
+  }
+  return Math.min(1, Math.max(0, (acc * h) / 3));
+}