peeksafe 0.1.0 → 0.3.0

package/src/plan.ts

@@ -32,15 +32,18 @@
  * it.
  */
 
-import { type BaselineStat, baselineNullRate, type CaseRef } from "./baseline.js";
+import type { BaselineStat, CaseRef } from "./baseline.js";
 import {
   PeeksafeError,
+  requireCounts,
   requireErrorRates,
   requireOpenProbability,
   requireProbability,
+  requireRunCeiling,
+  requireTrialGrid,
+  requireUniqueCaseIds,
 } from "./errors.js";
 import {
-  betaQuantile,
   ebhSoloThreshold,
   evidenceCeilingLogE,
   mcnemarSamplesForEvidence,
@@ -48,8 +51,8 @@ import {
   pairPhi,
   sampleSizeTwoProportion,
   samplesForEvidence,
-  sprtExpectedN,
 } from "./stats.js";
+import { shouldStop, shouldStopPaired } from "./stop.js";
 
 export interface PlanConfig {
   /** the drop we want to be able to detect, in probability units (0.15 = 15 points) */
@@ -74,14 +77,14 @@ export interface PlanConfig {
   /** beyond this many runs for one case we stop calling it "affordable" */
   runsPerCaseCeiling: number;
   /**
-   * Which design the *expected* bill is priced for. A paired observation is two
-   * runs, so this doubles `typicalRuns`.
+   * Which design the *expected* bill and the screening pass are priced for. A
+   * paired observation is two runs, and a paired case's observation count is
+   * the pairs `shouldStopPaired` takes to settle it at its coupling; an
+   * unpaired case's is the runs `shouldStop` takes to stop it.
    *
-   * `undefined` means "price the design this plan recommends", which is the
-   * only self-consistent answer: `makePlan` recommends pairing whenever more
-   * than a quarter of the suite has an unpaired evidence ceiling under the bar,
-   * and quoting the *unpaired* bill underneath that recommendation would price
-   * a design nobody runs.
+   * `undefined` prices each case at its own `PlanCase.design`, and a case with
+   * none at the suite's `recommendedDesign`. Setting it prices every case at
+   * that one design.
    */
   design?: "unpaired" | "paired";
 
@@ -96,6 +99,13 @@ export interface PlanConfig {
   maxTrials: number;
   batchSize: number;
   nullQuantile: number;
+  /**
+   * The `futilityConfidence` you run `shouldStop` and `shouldStopPaired` at.
+   * The expected bill counts the runs or pairs a case takes to stop at this
+   * level, so a higher one prices more. `undefined` takes the stopping rules'
+   * own default.
+   */
+  futilityConfidence?: number;
 }
 
 export const DEFAULT_PLAN: PlanConfig = {
@@ -157,6 +167,13 @@ export interface PlanCase {
    * "undetectable" verdict.
    */
   baselineRunsNeeded: number | null;
+  /**
+   * Expected runs this case costs in a pull request in which nothing moved, at
+   * the design the expected bill prices it at: `config.design`, else `design`,
+   * else the suite's `recommendedDesign` (unpaired when `planCase` is called on
+   * its own). The cases of a plan sum to `totals.typicalRuns`; 0 with no baseline.
+   */
+  typicalRuns: number;
   /** what a fixed-N two-proportion design would spend per arm, for comparison */
   fixedNPerArm: number;
   reason: string;
@@ -197,7 +214,11 @@ export interface PlanTotals {
    * over-predicts what the gate actually spends by 5 to 8×, and the numbers below
    * predict it to within about 10% when checked against real runs.
    */
-  /** 1 unpaired, 2 paired, what one observation costs in runs */
+  /**
+   * What one observation of the expected bill costs in runs, averaged over its
+   * cases: 1 when every case runs unpaired, 2 when every case is paired, and in
+   * between for a suite that mixes the two.
+   */
   runsPerObservation: number;
   /** expected *runs* (not observations) for a pull request in which nothing moved */
   typicalRuns: number;
@@ -218,7 +239,13 @@ export interface Plan {
   pairedOnly: PlanCase[];
   /** cases whose baseline rate is too low to lose `mde` points at all */
   impossible: PlanCase[];
-  /** the design the recommendation names, and the one `expectedCostUsd` prices */
+  /**
+   * The design the recommendation names: paired when more than a quarter of
+   * the suite is `PAIRED_ONLY` or most decidable cases' own `design` is
+   * paired. `expectedCostUsd` prices each case at
+   * its own `design` and falls back to this one only for a case with none,
+   * unless `config.design` fixes one design for the whole suite.
+   */
   recommendedDesign: "unpaired" | "paired";
   /** the cheapest design that decides every decidable case */
   recommendation: string;
@@ -286,12 +313,31 @@ function baselineRunsToClear(
   return hi;
 }
 
+function requirePrices(cfg: PlanConfig, where: string): void {
+  if (!(cfg.costPerRunUsd >= 0) || !(cfg.msPerRun >= 0)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_CONFIG",
+      `${where}: costPerRunUsd and msPerRun must be ≥ 0`,
+      {
+        detail: { costPerRunUsd: cfg.costPerRunUsd, msPerRun: cfg.msPerRun },
+      },
+    );
+  }
+}
+
 export function planCase(
   c: CaseRef,
   b: BaselineStat | undefined,
   cfg: PlanConfig,
   m: number,
 ): PlanCase {
+  // Exported on its own, so it refuses what makePlan refuses before calling it: unchecked, a -5/60 baseline was IMPOSSIBLE and a price of -1 billed -$152.
+  if (b) requireCounts(b.successes, b.trials, `planCase(${c.id}).baseline`);
+  requireErrorRates(cfg.alpha, cfg.beta, "planCase");
+  requirePrices(cfg, "planCase");
+  // The expected bill walks the batch grid at the stopping rule's level; a zero batch never ends.
+  requireTrialGrid(cfg, "planCase");
+  requireSettleConfidence(cfg, "planCase");
   const barLogE = Math.log(ebhSoloThreshold(m, cfg.fdr));
   const trials = b?.trials ?? 0;
   const successes = b?.successes ?? 0;
@@ -319,6 +365,7 @@ export function planCase(
       detectability: "IMPOSSIBLE",
       design: null,
       baselineRunsNeeded: null,
+      typicalRuns: 0,
       reason: "no baseline: nothing to compare against, record one first",
     };
   }
@@ -332,6 +379,8 @@ export function planCase(
       detectability: "IMPOSSIBLE",
       design: null,
       baselineRunsNeeded: null,
+      // Undecidable, but the gate still runs it until it stops, so the expected bill pays for it.
+      typicalRuns: typicalCaseRuns(b, cfg.design ?? "unpaired", cfg, m),
       reason:
         `baseline rate ${(rate * 100).toFixed(0)}% cannot lose ${(cfg.mde * 100).toFixed(0)} points, ` +
         `the effect is arithmetically impossible, not merely expensive`,
@@ -407,23 +456,40 @@ export function planCase(
     detectability,
     design,
     baselineRunsNeeded,
+    typicalRuns: typicalCaseRuns(b, cfg.design ?? design ?? "unpaired", cfg, m),
     reason,
   };
 }
 
+// Each design is counted under the rule that stops it: an unpaired case in the runs `shouldStop` takes, a paired one in the pairs `shouldStopPaired` takes.
+function typicalCaseRuns(
+  b: BaselineStat | undefined,
+  design: "unpaired" | "paired",
+  cfg: PlanConfig,
+  m: number,
+): number {
+  if (!b || b.trials === 0) return 0;
+  const rate = b.successes / b.trials;
+  return design === "paired"
+    ? 2 * expectedSettlePairs(rate, cfg.pairCoupling, cfg.mde, m, cfg)
+    : expectedStopRuns(b, rate, m, cfg);
+}
+
 /**
- * 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.
+ * Expected total samples for the sequential design: per case, the exact
+ * expected runs `shouldStop` takes to stop it when its candidate passes at
+ * `trueRate`, in a suite of `cases.length`, on the gate's own batch grid
+ * (`expectedStopRuns`). At the default rate this is the figure the plan bills
+ * an unpaired case at, `PlanCase.typicalRuns`.
  *
- * 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
+ * that did not regress never gets there; it stops as futile or settled in a
+ * few batches. 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.
+ * `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: Array<CaseRef>,
@@ -432,30 +498,204 @@ export function expectedSequentialSamples(
   trueRate: (caseId: string, b: BaselineStat) => number = (_id, b) =>
     b.trials > 0 ? b.successes / b.trials : 0,
 ): { samples: number; perCase: Map<string, number> } {
+  requireTrialGrid(cfg, "expectedSequentialSamples");
+  // Checked here so a bad value is refused under this name, not under the stopping rule's.
+  requireOpenProbability(cfg.mde, "mde", "expectedSequentialSamples");
+  requireOpenProbability(cfg.fdr, "fdr", "expectedSequentialSamples");
+  requireSettleConfidence(cfg, "expectedSequentialSamples");
+  // A repeated id was added to `samples` once per listing but kept once in `perCase`, so the two disagreed.
+  requireUniqueCaseIds(cases, "expectedSequentialSamples");
   const perCase = new Map<string, number>();
   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;
+    // Wald's figure fell back to the cap on a NaN rate; the dynamic program would answer NaN.
+    requireProbability(p, "trueRate", "expectedSequentialSamples");
+    const runs = expectedStopRuns(b, p, cases.length, cfg);
+    perCase.set(c.id, runs);
+    total += runs;
   }
   return { samples: total, perCase };
 }
 
+type TrialGrid = Pick<PlanConfig, "minTrials" | "maxTrials" | "batchSize">;
+
+/** Refuses a set `futilityConfidence` outside (0, 1), where the settle bar is 0 or Infinity. */
+export function requireSettleConfidence(
+  cfg: Pick<PlanConfig, "futilityConfidence">,
+  where: string,
+): void {
+  if (cfg.futilityConfidence !== undefined) {
+    requireOpenProbability(cfg.futilityConfidence, "futilityConfidence", where);
+  }
+}
+
+// The frontier prices the same paired cell once per baseline and screen, so a sweep would rerun one program dozens of times.
+const settlePairsMemo = new Map<string, number>();
+// Every case of a suite that shares a baseline, and every planCase call makePlan makes, runs the same program.
+const stopRunsMemo = new Map<string, number>();
+
+/**
+ * Expected pairs `shouldStopPaired` takes to stop a paired case that did not
+ * move, at coupling `rho`, checked at `minTrials` and then every `batchSize`
+ * pairs up to `maxTrials`, in a suite of `suiteSize`. Exact, as
+ * `expectedStopRuns` is: the decision depends only on the worse and better
+ * counts at a given pair count, so a dynamic program carries their joint
+ * distribution from one check to the next. Rounded up to a whole pair.
+ */
+export function expectedSettlePairs(
+  rate: number,
+  rho: number,
+  mde: number,
+  suiteSize: number,
+  cfg: TrialGrid & Pick<PlanConfig, "fdr" | "futilityConfidence">,
+): number {
+  const key = [
+    rate,
+    rho,
+    mde,
+    suiteSize,
+    cfg.fdr,
+    cfg.futilityConfidence,
+    cfg.minTrials,
+    cfg.maxTrials,
+    cfg.batchSize,
+  ].join("|");
+  const known = settlePairsMemo.get(key);
+  if (known !== undefined) return known;
+  const options = {
+    suiteSize,
+    mde,
+    fdr: cfg.fdr,
+    futilityConfidence: cfg.futilityConfidence,
+  };
+  // Unmoved arms disagree each way only when uncoupled: (1 - rho) p (1 - p).
+  const each = (1 - rho) * rate * (1 - rate);
+  const same = 1 - 2 * each;
+  // live[w * (top + 1) + b]: probability of w worse and b better pairs with the case still running.
+  let live = new Float64Array([1]);
+  // Mass under 1e-18 is dropped so the square stays as small as the spread of the counts; it cannot move the rounded answer.
+  let top = 0;
+  let n = 0;
+  let expected = 0;
+  for (let step = cfg.minTrials; ; step = Math.min(cfg.batchSize, cfg.maxTrials - n)) {
+    for (let i = 0; i < step; i++) {
+      const side = top + 2;
+      const next = new Float64Array(side * side);
+      for (let w = 0; w <= top; w++) {
+        for (let b = 0; b <= top; b++) {
+          const q = live[w * (top + 1) + b]!;
+          if (q === 0) continue;
+          next[w * side + b]! += q * same;
+          next[(w + 1) * side + b]! += q * each;
+          next[w * side + b + 1]! += q * each;
+        }
+      }
+      let reach = 0;
+      for (let at = 0; at < next.length; at++) {
+        if (next[at]! < 1e-18) next[at] = 0;
+        else reach = Math.max(reach, Math.floor(at / side), at % side);
+      }
+      live = new Float64Array((reach + 1) * (reach + 1));
+      for (let w = 0; w <= reach; w++) {
+        for (let b = 0; b <= reach; b++) live[w * (reach + 1) + b] = next[w * side + b]!;
+      }
+      top = reach;
+      n++;
+    }
+    let running = 0;
+    for (let w = 0; w <= top; w++) {
+      for (let b = 0; b <= top; b++) {
+        const at = w * (top + 1) + b;
+        const q = live[at]!;
+        if (q === 0) continue;
+        const counts = { bothPass: n - w - b, worse: w, better: b, bothFail: 0 };
+        if (n >= cfg.maxTrials || shouldStopPaired(counts, options).stop) {
+          expected += q * n;
+          live[at] = 0;
+        } else {
+          running += q;
+        }
+      }
+    }
+    if (running === 0) break;
+  }
+  // Float residue must not push an exact whole number up a pair.
+  const pairs = Math.ceil(expected - 1e-9);
+  if (settlePairsMemo.size >= 1024) settlePairsMemo.clear();
+  settlePairsMemo.set(key, pairs);
+  return pairs;
+}
+
+/**
+ * Expected runs `shouldStop` takes to stop an unpaired case whose candidate
+ * passes at `rate`, checked at `minTrials` and then every `batchSize` runs up
+ * to `maxTrials`, in a suite of `suiteSize`. Exact rather than simulated:
+ * the decision depends on the candidate only through its counts, so a dynamic
+ * program carries the distribution of the success count from one check to the
+ * next. Rounded up to a whole run; an expectation is not a grid point.
+ */
+export function expectedStopRuns(
+  baseline: BaselineStat,
+  rate: number,
+  suiteSize: number,
+  cfg: TrialGrid & Pick<PlanConfig, "mde" | "fdr" | "futilityConfidence">,
+): number {
+  const key = [
+    baseline.successes,
+    baseline.trials,
+    rate,
+    suiteSize,
+    cfg.mde,
+    cfg.fdr,
+    cfg.futilityConfidence,
+    cfg.minTrials,
+    cfg.maxTrials,
+    cfg.batchSize,
+  ].join("|");
+  const known = stopRunsMemo.get(key);
+  if (known !== undefined) return known;
+  const options = {
+    suiteSize,
+    mde: cfg.mde,
+    fdr: cfg.fdr,
+    futilityConfidence: cfg.futilityConfidence,
+  };
+  // live[k]: probability of k successes in n runs with the case still running.
+  let live = new Float64Array([1]);
+  let n = 0;
+  let expected = 0;
+  for (let step = cfg.minTrials; ; step = Math.min(cfg.batchSize, cfg.maxTrials - n)) {
+    for (let i = 0; i < step; i++) {
+      const next = new Float64Array(live.length + 1);
+      for (let k = 0; k < live.length; k++) {
+        next[k]! += live[k]! * (1 - rate);
+        next[k + 1]! += live[k]! * rate;
+      }
+      live = next;
+    }
+    n += step;
+    let running = 0;
+    for (let k = 0; k <= n; k++) {
+      if (live[k] === 0) continue;
+      if (n >= cfg.maxTrials || shouldStop({ successes: k, trials: n }, baseline, options).stop) {
+        expected += live[k]! * n;
+        live[k] = 0;
+      } else {
+        running += live[k]!;
+      }
+    }
+    if (running === 0) break;
+  }
+  // Float residue must not push an exact whole number up a run.
+  const runs = Math.ceil(expected - 1e-9);
+  if (stopRunsMemo.size >= 1024) stopRunsMemo.clear();
+  stopRunsMemo.set(key, runs);
+  return runs;
+}
+
 /**
  * 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
@@ -485,20 +725,17 @@ export function makePlan(
   // 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");
+  requireSettleConfidence(cfg, "makePlan");
+  requireRunCeiling(cfg.runsPerCaseCeiling, "makePlan");
+  requireTrialGrid(cfg, "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 },
-      },
-    );
-  }
+  // `gate` refuses a repeated id; planned, it was priced twice and counted twice in the suite size the bar is set from.
+  requireUniqueCaseIds(cases, "makePlan");
+  requirePrices(cfg, "makePlan");
 
   const m = cases.length;
   const planned = cases.map((c) => {
@@ -529,13 +766,25 @@ export function makePlan(
   );
 
   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 pairedDesignCount = decidableAny.filter((p) => p.design === "paired").length;
+  // The recommendation string reads these same two flags, so it cannot drift from the design it names.
+  const manyPairedOnly = pairedOnlyCount > cases.length * 0.25;
+  const mostlyPaired = pairedDesignCount * 2 > decidableAny.length;
   const recommendedDesign: "unpaired" | "paired" =
     cfg.design ??
-    (decidableAny.length > 0 && pairedOnlyCount > cases.length * 0.25 ? "paired" : "unpaired");
-  const runsPerObservation = recommendedDesign === "paired" ? 2 : 1;
+    (decidableAny.length > 0 && (manyPairedOnly || mostlyPaired) ? "paired" : "unpaired");
+  // Per case, like `bestRuns`: one suite-wide design billed a mixed suite as if every case ran it.
+  const runsPerObs = (p: PlanCase) =>
+    (cfg.design ?? p.design ?? recommendedDesign) === "paired" ? 2 : 1;
+  // `planCase` cannot see the suite, so a case with no design was priced unpaired there.
+  for (const p of planned) {
+    if (p.design === null && runsPerObs(p) === 2) {
+      const b = baseline.get(p.caseId);
+      p.typicalRuns = typicalCaseRuns(b, "paired", { ...cfg, pairCoupling: p.pairCoupling }, m);
+    }
+  }
+  // `screenRuns` counts observations, so each case's pass costs its own design's runs.
+  const screenPassRuns = planned.reduce((a, p) => a + cfg.screenRuns * runsPerObs(p), 0);
 
   // 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
@@ -550,21 +799,32 @@ export function makePlan(
   // 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 screenedRuns = screenPassRuns + 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;
+  // Both counts are *observations*. A paired observation is two runs, the
+  // candidate and the reference revision on the same seed, and so is a paired
+  // screening run. Each case is counted under the rule that stops it
+  // (`PlanCase.typicalRuns`): a paired one in pairs to settle, an unpaired one
+  // in the runs `shouldStop` takes. Wald's SPRT figure, used for both before,
+  // runs a different rule, ignores the coupling and the suite size, and
+  // mispriced cases either way.
+  const priced = planned.filter((p) => (baseline.get(p.caseId)?.trials ?? 0) > 0).length;
+  const typicalObservations = planned.reduce((a, p) => a + p.typicalRuns / runsPerObs(p), 0);
+  const typicalRuns = planned.reduce((a, p) => a + p.typicalRuns, 0);
+  const runsPerObservation =
+    typicalObservations > 0
+      ? typicalRuns / typicalObservations
+      : recommendedDesign === "paired"
+        ? 2
+        : 1;
+  const meanTypical = priced > 0 ? typicalRuns / priced : 0;
   const typicalScreenedRuns = Math.ceil(
-    (m * cfg.screenRuns + Math.ceil(m * screenContinueFraction) * meanTypical) * runsPerObservation,
+    screenPassRuns + Math.ceil(m * screenContinueFraction) * meanTypical,
   );
 
   const totals: PlanTotals = {
@@ -604,8 +864,12 @@ export function makePlan(
     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)`
+        ? (manyPairedOnly
+            ? `pair the runs: ${pairedOnly.length}/${m} cases have an unpaired evidence ceiling under the bar, so no candidate budget can decide them`
+            : `pair the runs: ${pairedDesignCount}/${decidableAny.length} decidable cases are cheaper paired than against the stored baseline`) +
+          (cfg.design === undefined
+            ? ` (the costs below price each case at its own design, two runs an observation where it is paired)`
+            : ` (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)})`
@@ -699,10 +963,32 @@ export function affordabilityGrid(
 ): AffordabilityCell[] {
   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.
+  // `makePlan` refuses it, so one options object must not price here and fail there.
   requireOpenProbability(cfg.nullQuantile, "nullQuantile", "affordabilityGrid");
+  // makePlan refuses both; unchecked, an fdr of 2 priced a grid cheaper than one at 0.05.
+  requireOpenProbability(cfg.fdr, "fdr", "affordabilityGrid");
+  requireSettleConfidence(cfg, "affordabilityGrid");
+  requireTrialGrid(cfg, "affordabilityGrid");
+  if (!(cfg.costPerRunUsd >= 0)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_CONFIG",
+      `affordabilityGrid: costPerRunUsd must be ≥ 0, got ${cfg.costPerRunUsd}`,
+      {
+        detail: { costPerRunUsd: cfg.costPerRunUsd },
+      },
+    );
+  }
+  for (const m of caseCounts) {
+    if (!Number.isInteger(m) || m < 1) {
+      throw new PeeksafeError(
+        "PEEKSAFE_E_CONFIG",
+        `affordabilityGrid: every case count must be a positive integer, got ${m}`,
+        {
+          detail: { cases: m },
+        },
+      );
+    }
+  }
   // 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
@@ -749,13 +1035,16 @@ export function affordabilityGrid(
       // 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);
+      // Each design is counted under the rule that stops it, as `makePlan` does; Wald's SPRT figure ignores the coupling and the suite size.
       const perCaseTypical =
-        Number.isFinite(rawN) && rawN > 0
-          ? Math.min(cfg.maxTrials, Math.max(cfg.minTrials, Math.ceil(rawN)))
-          : cfg.maxTrials;
+        runsPerObs === 2
+          ? expectedSettlePairs(baselineRate, cfg.pairCoupling, mde, m, cfg)
+          : expectedStopRuns(
+              { caseId: "typical", successes: s, trials: baselineTrials },
+              baselineRate,
+              m,
+              { ...cfg, mde },
+            );
       // 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(

package/src/rand.ts

@@ -20,7 +20,7 @@
  * 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";
+import { PeeksafeError, requireProbability } from "./errors.js";
 
 export interface Rand {
   (): number;
@@ -75,11 +75,27 @@ export function hash32(s: string): number {
 }
 
 export function makeRand(seed: number | string): Rand {
-  const s = typeof seed === "string" ? hash32(seed) : seed >>> 0;
-  const base = lcg(s === 0 ? 1 : s);
+  // `>>> 0` folded NaN, Infinity, 1.5 and 2^32 onto 0, and the old 0-to-1 remap put seed 1 there too.
+  if (typeof seed === "number" && !(Number.isInteger(seed) && seed >= 0 && seed < 0x100000000)) {
+    throw new PeeksafeError(
+      "PEEKSAFE_E_STAT_DOMAIN",
+      `makeRand: a numeric seed must be an integer in [0, 2^32), got ${seed}`,
+      {
+        detail: { seed },
+        hint: "pass a string to key a stream by name; it is hashed with hash32",
+      },
+    );
+  }
+  const s = typeof seed === "string" ? hash32(seed) : seed;
+  // Hull-Dobell: an odd increment and a multiplier of 1 mod 4 give a full period from every seed, 0 included.
+  const base = lcg(s);
   const next = (() => mix32(Math.floor(base() * 0x100000000)) / 0x100000000) as Rand;
 
-  next.bernoulli = (p: number) => next() < p;
+  // `next() < p` is false for every draw at NaN, so a rate that failed to compute simulated a case that never passes.
+  next.bernoulli = (p: number) => {
+    requireProbability(p, "p", "rand.bernoulli");
+    return next() < p;
+  };
 
   next.int = (n: number) => {
     if (!Number.isInteger(n) || n < 1) {