peeksafe 0.0.0-stage → 0.1.0

package/dist/stats.js

@@ -0,0 +1,1245 @@
+/**
+ * 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) {
+    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, b) => logGamma(a) + logGamma(b) - logGamma(a + b);
+/** Series expansion of the regularized lower incomplete gamma P(a,x), x < a+1. */
+function gammaPSeries(a, x) {
+    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, x) {
+    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, x) {
+    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) {
+    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) => 0.5 * (1 + erf(x / Math.SQRT2));
+/** Φ⁻¹(p): Acklam's inverse normal CDF, refined by one Halley step. */
+export function normalQuantile(p) {
+    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;
+    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) => (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, b, x) {
+    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, b, x) {
+    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;
+}
+/**
+ * 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, n, z = 1.959963984540054) {
+    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,
+    };
+}
+/** Conjugate Beta posterior for a per-case latent success probability. */
+export function betaPosterior(successes, failures, prior = { alpha: 1, beta: 1 }) {
+    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, beta, q) {
+    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, df) {
+    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, level = 0.95) {
+    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, a, b) {
+    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, n1, s2, n2, z = 1.959963984540054) {
+    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, p2) {
+    requireProbability(p1, "p1", "cohensH");
+    requireProbability(p2, "p2", "cohensH");
+    return 2 * Math.asin(Math.sqrt(p2)) - 2 * Math.asin(Math.sqrt(p1));
+}
+/** Pooled two-proportion z-test, two-sided. */
+export function twoProportionZTest(s1, n1, s2, n2) {
+    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, k) => 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, b, cc, d) {
+    for (const [name, v] of [
+        ["a", a],
+        ["b", b],
+        ["c", cc],
+        ["d", d],
+    ]) {
+        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) => 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) };
+}
+/**
+ * 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) {
+    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) => 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 = 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, logR1, logR0, drift) {
+    const g = (h) => 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, p0, p1, alpha = 0.05, beta = 0.1) {
+    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, A, B, drift) {
+    // 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));
+}
+/**
+ * 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, q = 0.05) {
+    // 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(m).fill(false);
+    const adjusted = new Array(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, n, a, b) {
+    // `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, name, where) {
+    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, candidateTrials, baselineSuccesses, baselineTrials, mde, 
+/**
+ * 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) {
+    // 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, baselineSuccesses, baselineTrials) => baselineTrials > 0 && candidateRate >= baselineSuccesses / baselineTrials;
+export function ebhCorrect(evalues, q = 0.05) {
+    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(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, q = 0.05) => 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, delta, alpha = 0.05, beta = 0.1) {
+    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) {
+    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, a, b) {
+    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, baselineTrials, mde, altConcentration = 8) {
+    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, baselineSuccesses, baselineTrials, mde, altConcentration = 8) {
+    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, pCandidate) {
+    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, baselineTrials, pTrue, mde, altConcentration = 8) {
+    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, n, baselineSuccesses, baselineTrials, mde, altConcentration = 8) {
+    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, n, baselineSuccesses, baselineTrials, mde, altConcentration = 8) {
+    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, baselineSuccesses, baselineTrials, mde, logThreshold, maxN = 100_000, altConcentration = 8) {
+    const ceiling = evidenceCeilingLogE(pTrue, baselineSuccesses, baselineTrials, mde, altConcentration);
+    if (!(ceiling > logThreshold))
+        return Infinity;
+    const f = (n) => 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, y) => (x === 0 ? 0 : x * Math.log(y));
+const logLik = (s, n, p) => xlogy(s, p) + xlogy(n - s, 1 - p);
+/** Largest log likelihood of the data under the null "candidate rate ≥ baseline rate". */
+function logNullSup(cs, cn, bs, bn) {
+    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, candidateTrials, baselineSuccesses, baselineTrials, mde, altConcentration = 8) {
+    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, baselineSuccesses, baselineTrials) {
+    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)));
+}
+export const discordant = (p) => 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) {
+    const { bothPass: a, worse: b, better: cc, bothFail: d } = p;
+    for (const [name, v] of [
+        ["bothPass", a],
+        ["worse", b],
+        ["better", cc],
+        ["bothFail", d],
+    ]) {
+        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, discordantPairs, thetaAlt = 0.75, concentration = 6) {
+    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, d, a, b) {
+    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, mde, rho) {
+    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, mde, rho, logThreshold, maxPairs = 100_000, concentration = 6) {
+    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) => 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, baselineTrials, candidateSuccesses, candidateTrials, mde, nodes = 256) {
+    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));
+}
+//# sourceMappingURL=stats.js.map