peeksafe 0.0.0-stage → 0.1.0

package/dist/plan.js

@@ -0,0 +1,482 @@
+/**
+ * plan.ts: power economics. What will this cost, and can we even detect it?
+ *
+ * Without a plan, the first sign that a suite cannot be decided is a large bill
+ * and no certified case. This module tells you *before* you spend anything, and it will tell you that the honest answer is
+ * sometimes "you cannot detect this at any price".
+ *
+ * The three numbers that matter, per case:
+ *
+ *  1. **The bar.** e-BH at FDR q over m cases certifies a case on its own only
+ *     once its e-value clears m/q. That is the target the evidence has to hit.
+ *
+ *  2. **The ceiling.** `evidenceCeilingLogE`, the limit of the unpaired
+ *     two-sample e-value as candidate runs go to infinity. Both marginals are
+ *     the same binomial likelihood under different priors, so everything that
+ *     grows with n cancels and the Bayes factor converges to the prior density
+ *     ratio at the observed rate. If the ceiling is under the bar, no number of
+ *     candidate runs will certify the case. This is not a budget problem and no
+ *     budget fixes it: **more baseline runs** fix it, by sharpening the null.
+ *
+ *  3. **The paired alternative.** Re-run the baseline alongside the candidate
+ *     on the same seed and the null becomes an exact point mass at ½ (a
+ *     discordant pair points either way with probability exactly one half under
+ *     "nothing changed"). Nothing is estimated, so nothing caps the evidence:
+ *     the paired e-value grows linearly in discordant pairs. It costs two runs
+ *     per observation and it is still, routinely, the cheaper design, and it
+ *     is the only one that works at all for a case whose ceiling is under the
+ *     bar.
+ *
+ * Everything here is a *plan*: it evaluates the mean trajectory (the candidate
+ * scores exactly its expected successes). Realised sample counts vary around
+ * it.
+ */
+import { baselineNullRate } from "./baseline.js";
+import { PeeksafeError, requireErrorRates, requireOpenProbability, requireProbability, } from "./errors.js";
+import { betaQuantile, ebhSoloThreshold, evidenceCeilingLogE, mcnemarSamplesForEvidence, pairPhi, sampleSizeTwoProportion, samplesForEvidence, sprtExpectedN, } from "./stats.js";
+export const DEFAULT_PLAN = {
+    mde: 0.15,
+    fdr: 0.05,
+    // These three are *assumptions* until you measure them on a real run: cost
+    // and latency from your runner, coupling with `pairPhi` on a pilot.
+    costPerRunUsd: 0.0021,
+    msPerRun: 780,
+    pairCoupling: 0.9,
+    screenRuns: 4,
+    concurrency: 8,
+    runsPerCaseCeiling: 2000,
+    alpha: 0.05,
+    beta: 0.1,
+    minTrials: 8,
+    maxTrials: 96,
+    batchSize: 4,
+    nullQuantile: 0.5,
+};
+const round = (x) => (Number.isFinite(x) ? Math.ceil(x) : Infinity);
+const medianTrials = (ps) => {
+    const xs = ps.map((p) => p.baseline.trials).sort((a, b) => a - b);
+    return xs.length === 0 ? 0 : xs[Math.floor(xs.length / 2)];
+};
+/**
+ * How many baseline runs would lift this case's evidence ceiling over the bar?
+ * The *smallest* such number, holding the baseline *rate* fixed, "if I keep
+ * measuring main at the same quality, how long until this case becomes
+ * decidable at all?"
+ *
+ * Smallest, and not a level the case stays decidable above: the ceiling is a
+ * sawtooth in the baseline size (see the comment in the body), so a baseline a
+ * few runs longer than this can fall back under the bar. Treat it as the floor
+ * it is rather than a promise about a bigger baseline.
+ */
+function baselineRunsToClear(rate, mde, barLogE, cap = 100_000) {
+    const at = (n) => {
+        const s = Math.round(rate * n);
+        return evidenceCeilingLogE(Math.max(1e-6, Math.min(1 - 1e-6, rate - mde)), s, n, mde);
+    };
+    // `at` is not monotone in `n`, so this cannot bisect the way
+    // `samplesForEvidence` does. Holding the rate fixed still forces an integer
+    // success count, so the implied rate jitters around `rate` and the ceiling
+    // drops hard every time the count ticks over: at 99% losing 10 points it
+    // clears the bar at 49 runs, falls back under it at 51, and does not clear
+    // again until 71. Bisecting that returns whichever crossing the doubling
+    // happened to bracket, which is no particular quantity at all; it answered 81
+    // for the README's own case where 75 is enough, and 5 for every case that
+    // needed fewer, because it bisected (4, 8]. Doubling now only bounds the
+    // scan, and never steps past `cap`, so the answer is one this search checked.
+    let hi = 1;
+    while (hi < cap && at(hi) < barLogE)
+        hi = Math.min(cap, hi * 2);
+    if (at(hi) < barLogE)
+        return null;
+    for (let n = 1; n < hi; n++)
+        if (at(n) >= barLogE)
+            return n;
+    return hi;
+}
+export function planCase(c, b, cfg, m) {
+    const barLogE = Math.log(ebhSoloThreshold(m, cfg.fdr));
+    const trials = b?.trials ?? 0;
+    const successes = b?.successes ?? 0;
+    const rate = trials > 0 ? successes / trials : 0;
+    const alt = Math.max(0, rate - cfg.mde);
+    const base = {
+        caseId: c.id,
+        // `suite` groups cases into correlation families. A caller who does not
+        // group them gets one family per case, which is the conservative reading.
+        suite: c.suite ?? c.id,
+        baseline: { successes, trials, rate },
+        alternativeRate: alt,
+        barLogE,
+        fixedNPerArm: sampleSizeTwoProportion(Math.max(1e-6, rate), cfg.mde, cfg.alpha, cfg.beta),
+    };
+    if (trials === 0) {
+        return {
+            ...base,
+            ceilingLogE: 0,
+            unpaired: { runs: Infinity, costUsd: Infinity, wallMs: Infinity },
+            paired: { pairs: Infinity, runs: Infinity, costUsd: Infinity, wallMs: Infinity },
+            pairCoupling: cfg.pairCoupling,
+            detectability: "IMPOSSIBLE",
+            design: null,
+            baselineRunsNeeded: null,
+            reason: "no baseline: nothing to compare against, record one first",
+        };
+    }
+    if (rate <= cfg.mde) {
+        return {
+            ...base,
+            ceilingLogE: 0,
+            unpaired: { runs: Infinity, costUsd: Infinity, wallMs: Infinity },
+            paired: { pairs: Infinity, runs: Infinity, costUsd: Infinity, wallMs: Infinity },
+            pairCoupling: cfg.pairCoupling,
+            detectability: "IMPOSSIBLE",
+            design: null,
+            baselineRunsNeeded: null,
+            reason: `baseline rate ${(rate * 100).toFixed(0)}% cannot lose ${(cfg.mde * 100).toFixed(0)} points, ` +
+                `the effect is arithmetically impossible, not merely expensive`,
+        };
+    }
+    const pTrue = Math.max(1e-6, Math.min(1 - 1e-6, alt));
+    const ceilingLogE = evidenceCeilingLogE(pTrue, successes, trials, cfg.mde);
+    const unpairedRuns = samplesForEvidence(pTrue, successes, trials, cfg.mde, barLogE, cfg.runsPerCaseCeiling * 8);
+    const pairs = mcnemarSamplesForEvidence(rate, cfg.mde, cfg.pairCoupling, barLogE, cfg.runsPerCaseCeiling * 8);
+    const unpaired = {
+        runs: unpairedRuns,
+        costUsd: unpairedRuns * cfg.costPerRunUsd,
+        wallMs: unpairedRuns * cfg.msPerRun,
+    };
+    const paired = {
+        pairs,
+        runs: pairs * 2,
+        costUsd: pairs * 2 * cfg.costPerRunUsd,
+        wallMs: pairs * 2 * cfg.msPerRun,
+    };
+    let detectability;
+    let reason;
+    if (Number.isFinite(unpairedRuns) && unpairedRuns <= cfg.runsPerCaseCeiling) {
+        detectability = "UNPAIRED";
+        reason = `${unpairedRuns} candidate runs against the stored baseline`;
+    }
+    else if (Number.isFinite(pairs) && pairs * 2 <= cfg.runsPerCaseCeiling) {
+        detectability = "PAIRED_ONLY";
+        reason = Number.isFinite(unpairedRuns)
+            ? `unpaired needs ${unpairedRuns} runs (past the ${cfg.runsPerCaseCeiling} ceiling); paired needs ${pairs * 2}`
+            : `unpaired evidence ceiling is e^${ceilingLogE.toFixed(1)}, under the bar e^${barLogE.toFixed(1)}, ` +
+                `no number of candidate runs certifies it. Paired: ${pairs * 2} runs.`;
+    }
+    else if (Number.isFinite(unpairedRuns) || Number.isFinite(pairs)) {
+        detectability = "TOO_EXPENSIVE";
+        reason = `cheapest design needs ${Math.min(unpairedRuns, pairs * 2)} runs, past the ${cfg.runsPerCaseCeiling} ceiling`;
+    }
+    else {
+        detectability = "IMPOSSIBLE";
+        reason = `neither design reaches the bar within ${cfg.runsPerCaseCeiling * 8} runs`;
+    }
+    const baselineRunsNeeded = detectability === "UNPAIRED" ? null : baselineRunsToClear(rate, cfg.mde, barLogE);
+    const design = detectability === "PAIRED_ONLY"
+        ? "paired"
+        : detectability !== "UNPAIRED"
+            ? null
+            : paired.runs < unpaired.runs
+                ? "paired"
+                : "unpaired";
+    return {
+        ...base,
+        ceilingLogE,
+        unpaired,
+        paired,
+        pairCoupling: cfg.pairCoupling,
+        detectability,
+        design,
+        baselineRunsNeeded,
+        reason,
+    };
+}
+/**
+ * Expected total samples for the sequential design, priced under Wald's
+ * expected sample number at a supplied "true" rate per case, and clamped into
+ * the gate's own [minTrials, maxTrials] batch grid.
+ *
+ * This is the number that predicts what the gate will actually spend.
+ * `samplesForEvidence`, the one behind `PlanCase.unpaired.runs`, answers a
+ * different question: how many runs it takes to *certify a regression*. A case
+ * that did not regress never gets there; it hits the H₀ wall in a few batches
+ * and stops. Pricing every case at the certification cost over-predicts the
+ * bill.
+ *
+ * `trueRate` defaults to the case's own baseline rate, i.e. "nothing moved", * which is what almost every pull request looks like.
+ */
+export function expectedSequentialSamples(cases, baseline, cfg, trueRate = (_id, b) => b.trials > 0 ? b.successes / b.trials : 0) {
+    const perCase = new Map();
+    let total = 0;
+    for (const c of cases) {
+        const b = baseline.get(c.id);
+        if (!b || b.trials === 0)
+            continue;
+        const p0 = baselineNullRate(b, cfg.nullQuantile);
+        const p1 = Math.max(0.005, p0 - cfg.mde);
+        const p = Math.max(0, Math.min(1, trueRate(c.id, b)));
+        const raw = sprtExpectedN(p, p0, p1, cfg.alpha, cfg.beta);
+        const n = Number.isFinite(raw) && raw > 0
+            ? Math.min(cfg.maxTrials, Math.max(cfg.minTrials, Math.ceil(raw)))
+            : cfg.maxTrials;
+        // The gate only ever adds whole batches past the minimum, so round the
+        // prediction onto the same grid the gate samples on.
+        const batched = cfg.minTrials + Math.ceil(Math.max(0, n - cfg.minTrials) / cfg.batchSize) * cfg.batchSize;
+        const capped = Math.min(cfg.maxTrials, batched);
+        perCase.set(c.id, capped);
+        total += capped;
+    }
+    return { samples: total, perCase };
+}
+/**
+ * Plan a suite. `pilots` holds a pair table per case from a pilot run of the
+ * paired design, ideally with both arms on the same revision; a case with one
+ * prices pairing at its measured `pairPhi` instead of `cfg.pairCoupling`, so
+ * its `design` is chosen from a coupling the runner actually delivers.
+ */
+export function makePlan(cases, baseline, cfg = DEFAULT_PLAN, pilots = new Map()) {
+    // Open interval: mde = 0 asks for a zero-point drop and fdr = 0 asks for a
+    // bar of Infinity. Both used to be accepted and produce a plan in which
+    // nothing is decidable, for a reason the printed message blamed on the
+    // baseline.
+    requireOpenProbability(cfg.mde, "mde", "makePlan");
+    requireOpenProbability(cfg.fdr, "fdr", "makePlan");
+    // The two error rates the SPRT costing runs on. Left unchecked they reached
+    // `sprtExpectedN`, which answers NaN or Infinity outside (0,1), and both
+    // callers of it here gate on `Number.isFinite(raw) && raw > 0` and quote
+    // `maxTrials` when that fails. So an alpha of 2 produced a complete plan with
+    // every case at the per-case cap and no error anywhere.
+    requireErrorRates(cfg.alpha, cfg.beta, "makePlan");
+    requireProbability(cfg.pairCoupling, "pairCoupling", "makePlan");
+    // Refused by `baselineNullRate` already, but only once a case with a baseline
+    // reaches it, and under that function's name for it, `q`. Checked here so
+    // every planner entry point refuses it the same way and names it.
+    requireOpenProbability(cfg.nullQuantile, "nullQuantile", "makePlan");
+    if (cases.length === 0) {
+        throw new PeeksafeError("PEEKSAFE_E_SUITE_EMPTY", "makePlan: no cases to plan for", {
+            hint: "pass at least one case; makePlan prices a suite, not an empty list",
+        });
+    }
+    if (!(cfg.costPerRunUsd >= 0) || !(cfg.msPerRun >= 0)) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", "makePlan: costPerRunUsd and msPerRun must be ≥ 0", {
+            detail: { costPerRunUsd: cfg.costPerRunUsd, msPerRun: cfg.msPerRun },
+        });
+    }
+    const m = cases.length;
+    const planned = cases.map((c) => {
+        const pilot = pilots.get(c.id);
+        // pairPhi validates the counts, so a malformed pilot is refused even when it sums to 0.
+        const phi = pilot ? pairPhi(pilot) : 0;
+        // An empty pilot measured nothing, so it leaves the configured coupling in place.
+        const measured = pilot && pilot.bothPass + pilot.worse + pilot.better + pilot.bothFail > 0;
+        // A negative phi is noise around independence for a design that couples by construction.
+        const caseCfg = measured ? { ...cfg, pairCoupling: Math.max(0, phi) } : cfg;
+        return planCase(c, baseline.get(c.id), caseCfg, m);
+    });
+    const finite = (x) => (Number.isFinite(x) ? x : 0);
+    const decidableUnpaired = planned.filter((p) => p.detectability === "UNPAIRED");
+    const decidableAny = planned.filter((p) => p.detectability === "UNPAIRED" || p.detectability === "PAIRED_ONLY");
+    const unpairedRuns = decidableUnpaired.reduce((a, p) => a + finite(p.unpaired.runs), 0);
+    const pairedRuns = decidableAny.reduce((a, p) => a + finite(p.paired.runs), 0);
+    // Per case, take the cheaper design that can actually decide it. This is the
+    // number the recommendation and the affordability verdict are built on: a
+    // design that is cheap because it decides nothing is not cheap.
+    const bestRuns = decidableAny.reduce((a, p) => a + Math.min(finite(p.unpaired.runs) || Infinity, finite(p.paired.runs) || Infinity), 0);
+    const pairedOnlyCount = planned.filter((p) => p.detectability === "PAIRED_ONLY").length;
+    // The design the recommendation will name, computed here because the
+    // *expected* bill has to be priced for it. `pairedOnly > 25%` is the same
+    // condition the recommendation string uses; they cannot drift apart.
+    const recommendedDesign = cfg.design ??
+        (decidableAny.length > 0 && pairedOnlyCount > cases.length * 0.25 ? "paired" : "unpaired");
+    const runsPerObservation = recommendedDesign === "paired" ? 2 : 1;
+    // Screening: everything gets `screenRuns`; only the cases the screen ranks as
+    // plausibly moved go on to the sequential test. A clean PR moves nothing, so
+    // in expectation only the FDR-sized tail continues, but a plan must be
+    // conservative, so we budget for the worst realistic case: 10% continue.
+    const screenContinueFraction = 0.1;
+    const screenSelected = Math.ceil(decidableAny.length * screenContinueFraction);
+    const meanBest = decidableAny.length > 0 ? bestRuns / decidableAny.length : 0;
+    // `screenRuns` counts *observations*, and a paired observation is two runs,
+    // so a paired screening pass costs twice what an unpaired one does. Only the
+    // screen term is scaled here: `meanBest` already comes from `paired.runs`,
+    // which is `pairs * 2`. The expected total below reads `screenRuns` the same
+    // way, and when this one did not, the two screened figures in `totals`
+    // disagreed about the price of the same pass.
+    const screenedRuns = m * cfg.screenRuns * runsPerObservation + screenSelected * meanBest;
+    const fixedNRuns = planned.reduce((a, p) => a + finite(p.fixedNPerArm), 0);
+    // The expected cost of a pull request that changed nothing, which is what a
+    // pull request almost always is, and therefore the number a budget should be
+    // set from.
+    // `expectedSequentialSamples` counts *observations*. A paired observation is
+    // two runs, the candidate and the reference revision on the same seed, and
+    // so is a paired screening run.
+    const typical = expectedSequentialSamples(cases, baseline, cfg);
+    const typicalRuns = typical.samples * runsPerObservation;
+    const meanTypical = typical.perCase.size > 0 ? typical.samples / typical.perCase.size : 0;
+    const typicalScreenedRuns = Math.ceil((m * cfg.screenRuns + Math.ceil(m * screenContinueFraction) * meanTypical) * runsPerObservation);
+    const totals = {
+        cases: m,
+        decidableUnpaired: decidableUnpaired.length,
+        decidableBest: decidableAny.length,
+        unpairedRuns,
+        unpairedCostUsd: unpairedRuns * cfg.costPerRunUsd,
+        pairedRuns,
+        pairedCostUsd: pairedRuns * cfg.costPerRunUsd,
+        bestRuns: round(bestRuns),
+        bestCostUsd: round(bestRuns) * cfg.costPerRunUsd,
+        screenedRuns: round(screenedRuns),
+        screenedCostUsd: round(screenedRuns) * cfg.costPerRunUsd,
+        fixedNRuns,
+        fixedNCostUsd: fixedNRuns * cfg.costPerRunUsd,
+        wallMsUnpaired: (unpairedRuns * cfg.msPerRun) / Math.max(1, cfg.concurrency),
+        wallMsPaired: (pairedRuns * cfg.msPerRun) / Math.max(1, cfg.concurrency),
+        wallMsBest: (round(bestRuns) * cfg.msPerRun) / Math.max(1, cfg.concurrency),
+        wallMsScreened: (round(screenedRuns) * cfg.msPerRun) / Math.max(1, cfg.concurrency),
+        screenContinueFraction,
+        runsPerObservation,
+        typicalRuns,
+        typicalCostUsd: typicalRuns * cfg.costPerRunUsd,
+        wallMsTypical: (typicalRuns * cfg.msPerRun) / Math.max(1, cfg.concurrency),
+        typicalScreenedRuns,
+        typicalScreenedCostUsd: typicalScreenedRuns * cfg.costPerRunUsd,
+    };
+    const undecidable = planned.filter((p) => p.detectability === "TOO_EXPENSIVE" || p.detectability === "IMPOSSIBLE");
+    const pairedOnly = planned.filter((p) => p.detectability === "PAIRED_ONLY");
+    const impossible = planned.filter((p) => p.detectability === "IMPOSSIBLE");
+    const recommendation = decidableAny.length === 0
+        ? `nothing is decidable at ${(cfg.mde * 100).toFixed(0)} points against this baseline, record more baseline runs or raise the MDE`
+        : recommendedDesign === "paired"
+            ? `pair the runs: ${pairedOnly.length}/${m} cases have an unpaired evidence ceiling under the bar, so no candidate budget can decide them` +
+                ` (the costs below are priced at two runs an observation, which is what pairing costs)`
+            : totals.screenedCostUsd < totals.bestCostUsd
+                ? `screen first, then run the sequential test on what the screen keeps ` +
+                    `($${totals.screenedCostUsd.toFixed(2)} vs $${totals.bestCostUsd.toFixed(2)})`
+                : `run the sequential test directly`;
+    // The honest cost is the cheapest plan that still decides something. A design
+    // that is free because it certifies nothing is not a cheap design.
+    const ceilingCost = decidableAny.length === 0 ? Infinity : Math.min(totals.screenedCostUsd, totals.bestCostUsd);
+    // The headline is the expected cost; leading with the ceiling over-states the bill.
+    // Mirrors the ceiling's structure, the cheapest plan of its kind, so the two
+    // numbers are roughly comparable. Comparing an unscreened expected cost
+    // with a screened ceiling was the first version of this and it made the
+    // "expected" figure look *larger* than the worst case.
+    const expectedCost = decidableAny.length === 0
+        ? Infinity
+        : Math.min(totals.typicalCostUsd, totals.typicalScreenedCostUsd);
+    const coverage = `${decidableAny.length}/${m} cases`;
+    // "Every case regressed" is not the expensive pull request, and calling it
+    // the worst case put a number below the headline that an operator would
+    // budget from: a 200-case suite on a 12-run baseline read "about $11.42 per
+    // pull request. Worst case ... is $9.16". The sequential test stops a case
+    // the moment it clears the bar, so a suite that really did regress finishes
+    // early, while one that did not move runs its full schedule. When the
+    // all-regressed cost lands under the expected one, say which it is.
+    //
+    // The sentence stops short of naming early stopping as *the* cause, because
+    // there is a second one: both figures are a `min` over two designs, and the
+    // two minima need not select the same design, so the cheaper figure may be
+    // pricing a plan the dearer one is not. Until both sides are made to select
+    // together, the honest claim is only that neither bounds the other.
+    const ceilingNote = !Number.isFinite(ceilingCost)
+        ? ""
+        : ceilingCost >= expectedCost
+            ? ` Worst case, every case regressing at once, is $${ceilingCost.toFixed(2)}.`
+            : ` A pull request in which every case regressed costs less, $${ceilingCost.toFixed(2)}: ` +
+                `the two do not price the same schedule, so neither bounds the other.`;
+    const verdict = !Number.isFinite(expectedCost)
+        ? `undecidable: no design reaches the bar for any case at ${(cfg.mde * 100).toFixed(0)} points with a ${medianTrials(planned)}-run baseline`
+        : expectedCost <= 5
+            ? `affordable: about $${expectedCost.toFixed(2)} per pull request, covering ${coverage}.${ceilingNote}`
+            : expectedCost <= 100
+                ? `viable but not free: about $${expectedCost.toFixed(2)} per pull request covering ${coverage}, worth gating a release on, not every commit.${ceilingNote}`
+                : `not affordable per-PR at $${cfg.costPerRunUsd.toFixed(4)}/run: about $${expectedCost.toFixed(0)} a time for ${coverage}. ` +
+                    `Cut the suite, raise the MDE, or gate nightly instead of per-PR.${ceilingNote}`;
+    return {
+        config: cfg,
+        cases: planned,
+        totals,
+        undecidable,
+        pairedOnly,
+        impossible,
+        recommendedDesign,
+        recommendation,
+        verdict,
+        expectedCostUsd: expectedCost,
+        ceilingCostUsd: ceilingCost,
+    };
+}
+export function affordabilityGrid(baselineRate, baselineTrials, cfg, budgetUsd, caseCounts = [20, 50, 100, 200], mdes = [0.1, 0.15, 0.25, 0.35]) {
+    requireProbability(baselineRate, "baselineRate", "affordabilityGrid");
+    requireErrorRates(cfg.alpha, cfg.beta, "affordabilityGrid");
+    // The typical bill below takes this quantile of the baseline posterior
+    // straight from `betaQuantile`, which answers 0 or 1 for a quantile outside
+    // (0,1) and about 0 for NaN instead of refusing. `makePlan` refuses it.
+    requireOpenProbability(cfg.nullQuantile, "nullQuantile", "affordabilityGrid");
+    // Every other planner entry point refuses a case with no baseline: `planCase`
+    // returns IMPOSSIBLE with "no baseline", `evaluatePoint` throws on
+    // `baselineRuns < 1`, and `gate` throws PEEKSAFE_E_BASELINE_MISSING. This one
+    // checked only the rate, so `baselineTrials: 0` reached `twoSamplePriors` as
+    // 0 successes in 0 trials, whose null prior is Beta(1, 1), and the grid
+    // priced the suite against "every case passes half the time" and reported it
+    // affordable, on a cheaper typical bill than the same call at a real
+    // baseline. A fractional or negative count did reach a refusal, but from
+    // `requireCounts` three frames down, naming a success count the caller never
+    // passed. `test/budget.test.ts` has the figures.
+    if (!Number.isInteger(baselineTrials) || baselineTrials < 1) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `affordabilityGrid: baselineTrials must be a positive integer, got ${baselineTrials}`, {
+            detail: { baselineTrials },
+            hint: 'this grid prices a suite against a recorded baseline; with none the null prior is Beta(1, 1), which reads as "every case passes half the time"',
+        });
+    }
+    const out = [];
+    for (const m of caseCounts) {
+        for (const mde of mdes) {
+            const bar = Math.log(ebhSoloThreshold(m, cfg.fdr));
+            const pTrue = Math.max(1e-6, baselineRate - mde);
+            const s = Math.round(baselineRate * baselineTrials);
+            const perCase = samplesForEvidence(pTrue, s, baselineTrials, mde, bar, 200_000);
+            const pairs = mcnemarSamplesForEvidence(baselineRate, mde, cfg.pairCoupling, bar, 200_000);
+            // the cheaper of the two designs, screened down to a 10% continue rate
+            const best = Math.min(Number.isFinite(perCase) ? perCase : Infinity, pairs * 2);
+            // Which design `best` just picked, needed by both totals below: they have
+            // to price the same screening pass as each other, and `screenRuns` counts
+            // observations, so a paired pass costs two runs an observation. Only the
+            // screen term is scaled, because `best` is already in runs (`pairs * 2`).
+            // When this total left the screen term unscaled it understated a paired
+            // cell by `m * screenRuns` runs, which made `affordable` below answer for
+            // a cheaper ceiling than the one it reports, and made this grid disagree
+            // with `makePlan`'s `screenedRuns` about the price of the same pass.
+            const runsPerObs = Number.isFinite(perCase) && perCase <= pairs * 2 ? 1 : 2;
+            const runs = Number.isFinite(best)
+                ? Math.ceil(m * cfg.screenRuns * runsPerObs + Math.ceil(m * 0.1) * best)
+                : Infinity;
+            const costUsd = runs * cfg.costPerRunUsd;
+            // The ceiling above prices a pull request in which every case regressed.
+            // This prices one in which nothing did, which is what a pull request
+            // almost always is.
+            const p0 = betaQuantile(1 + s, 1 + baselineTrials - s, cfg.nullQuantile);
+            const p1 = Math.max(0.005, p0 - mde);
+            const rawN = sprtExpectedN(baselineRate, p0, p1, cfg.alpha, cfg.beta);
+            const perCaseTypical = Number.isFinite(rawN) && rawN > 0
+                ? Math.min(cfg.maxTrials, Math.max(cfg.minTrials, Math.ceil(rawN)))
+                : cfg.maxTrials;
+            // Priced for the same design as the ceiling above (`runsPerObs`), or the
+            // cell quotes an unpaired price for a plan only pairing can execute.
+            const typicalRuns = Math.ceil((m * cfg.screenRuns + Math.ceil(m * 0.1) * perCaseTypical) * runsPerObs);
+            const typicalCostUsd = typicalRuns * cfg.costPerRunUsd;
+            out.push({
+                cases: m,
+                mde,
+                runs,
+                costUsd,
+                typicalRuns,
+                typicalCostUsd,
+                affordable: costUsd <= budgetUsd,
+                typicallyAffordable: typicalCostUsd <= budgetUsd,
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}

package/dist/rand.d.ts

@@ -0,0 +1,17 @@
+export interface Rand {
+    (): number;
+    /** A single Bernoulli draw at rate `p`. */
+    bernoulli(p: number): boolean;
+    /** A uniform integer in `[0, nExclusive)`. */
+    int(nExclusive: number): number;
+    /** A uniform choice. Throws on an empty array rather than returning undefined. */
+    pick<T>(xs: readonly T[]): T;
+    /** A standard normal draw, via Box-Muller. */
+    normal(): number;
+}
+/** FNV-1a. Used to derive an independent seed per named stream. */
+export declare function hash32(s: string): number;
+export declare function makeRand(seed: number | string): Rand;
+/** A stream keyed by name, reproducible regardless of call order elsewhere. */
+export declare const streamFor: (...parts: Array<string | number>) => Rand;
+//# sourceMappingURL=rand.d.ts.map

package/dist/rand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rand.d.ts","sourceRoot":"","sources":["../src/rand.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,IAAI;IACnB,IAAI,MAAM,CAAC;IACX,2CAA2C;IAC3C,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,8CAA8C;IAC9C,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,kFAAkF;IAClF,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7B,8CAA8C;IAC9C,MAAM,IAAI,MAAM,CAAC;CAClB;AAgCD,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAOxC;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwCpD;AAED,+EAA+E;AAC/E,eAAO,MAAM,SAAS,aAAc,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAAG,IAC1B,CAAC"}

package/dist/rand.js

@@ -0,0 +1,92 @@
+/**
+ * rand.ts: deterministic randomness.
+ *
+ * Everything stochastic in peeksafe (the Monte Carlo checks in `test/`, and any
+ * simulation a caller wants to run) draws from here.
+ *
+ * The generator is a linear congruential generator feeding an integer avalanche.
+ * The LCG alone is not good enough: consecutive outputs of an LCG sit on a
+ * lattice, which visibly biases Bernoulli streams, and a Bernoulli stream is the
+ * only thing this library ever simulates. The mixer decorrelates without adding
+ * a dependency and without losing determinism.
+ *
+ * Both sets of constants are published parameters rather than anybody's source
+ * code, and both are named in NOTICE.
+ *
+ * The exact stream matters. The measurements in the README and in
+ * `test/paper.test.ts` were produced by this generator, so replacing it with a
+ * better one (sfc32, pcg) would change every reported figure. That is a fine
+ * thing to do deliberately, with the numbers re-derived and the README updated.
+ * It is not a fine thing to do by accident, which is why the constants are
+ * spelled out here rather than imported.
+ */
+import { PeeksafeError } from "./errors.js";
+/**
+ * LCG with Knuth's multiplier 1664525 and increment 1013904223, modulo 2^32.
+ *
+ * These are tabulated constants (Knuth, TAOCP vol. 2), reprinted in most
+ * numerical texts. Exact in float64: 2^32 * 1664525 sits under 2^53, so the
+ * product never loses a bit before the mask.
+ */
+function lcg(seed) {
+    let s = seed >>> 0;
+    return () => {
+        s = (s * 1664525 + 1013904223) >>> 0;
+        return s / 0x100000000;
+    };
+}
+/**
+ * 32-bit avalanche: the `lowbias32` multipliers from Chris Wellons' hash
+ * function prospector, which he placed in the public domain. Two rounds of
+ * xor-shift-multiply, chosen by search for low bias rather than derived.
+ */
+function mix32(x) {
+    let h = x >>> 0;
+    h ^= h >>> 16;
+    h = Math.imul(h, 0x7feb352d) >>> 0;
+    h ^= h >>> 15;
+    h = Math.imul(h, 0x846ca68b) >>> 0;
+    h ^= h >>> 16;
+    return h >>> 0;
+}
+/** FNV-1a. Used to derive an independent seed per named stream. */
+export function hash32(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}
+export function makeRand(seed) {
+    const s = typeof seed === "string" ? hash32(seed) : seed >>> 0;
+    const base = lcg(s === 0 ? 1 : s);
+    const next = (() => mix32(Math.floor(base() * 0x100000000)) / 0x100000000);
+    next.bernoulli = (p) => next() < p;
+    next.int = (n) => {
+        if (!Number.isInteger(n) || n < 1) {
+            throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `rand.int: n must be a positive integer, got ${n}`, {
+                detail: { n },
+            });
+        }
+        return Math.floor(next() * n) % n;
+    };
+    // Typed `T`, so it must never hand back `undefined`. Returning `xs[0]` for an
+    // empty array is `undefined` wearing a `T`, which is how a fail-open bug gets
+    // past the type checker.
+    next.pick = (xs) => {
+        if (xs.length === 0) {
+            throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", "rand.pick: cannot pick from an empty array");
+        }
+        return xs[next.int(xs.length)];
+    };
+    next.normal = () => {
+        const u = Math.max(1e-12, next());
+        const v = next();
+        return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+    };
+    return next;
+}
+/** A stream keyed by name, reproducible regardless of call order elsewhere. */
+export const streamFor = (...parts) => makeRand(hash32(parts.join("|")));
+//# sourceMappingURL=rand.js.map

package/dist/rand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rand.js","sourceRoot":"","sources":["../src/rand.ts"],"names":[],"mappings":"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"}