peeksafe 0.0.0-stage → 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,108 @@
+/**
+ * errors.ts: one error class, stable codes, structured detail.
+ *
+ * Nothing in peeksafe throws a bare string. Every code below is thrown
+ * somewhere in `src/` and is part of the public contract: a caller may branch
+ * on `err.code` and we will not repurpose one.
+ */
+export type PeeksafeErrorCode = "PEEKSAFE_E_CONFIG" | "PEEKSAFE_E_CASE_DUPLICATE" | "PEEKSAFE_E_SUITE_EMPTY" | "PEEKSAFE_E_BASELINE_MISSING" | "PEEKSAFE_E_STAT_DOMAIN";
+export interface PeeksafeErrorOptions {
+    detail?: Record<string, unknown>;
+    /** what the operator should actually do about it */
+    hint?: string;
+    cause?: unknown;
+}
+export declare class PeeksafeError extends Error {
+    readonly code: PeeksafeErrorCode;
+    readonly detail: Record<string, unknown>;
+    readonly hint?: string;
+    constructor(code: PeeksafeErrorCode, message: string, opts?: PeeksafeErrorOptions);
+    /** Stable JSON shape, for logs and CI artifacts. */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        hint?: string;
+        detail: Record<string, unknown>;
+    };
+    static is(e: unknown): e is PeeksafeError;
+}
+/**
+ * Domain guard for the statistics. Every function in `stats.ts` that can be
+ * handed nonsense (successes > trials, a negative count, an MDE larger than the
+ * baseline rate) routes through here rather than returning NaN.
+ */
+export declare function requireCounts(successes: number, trials: number, where: string): void;
+/**
+ * A probability that must be strictly inside (0,1), a rate, an effect size, an
+ * error budget. `requireProbability` allows the endpoints, which is right for a
+ * *rate* and wrong for an *effect*: an MDE of 0 asks for a zero-point drop to be
+ * detected, which every design answers "no" to for reasons that look like a
+ * ceiling problem and are not.
+ */
+export declare function requireOpenProbability(p: number, name: string, where: string): void;
+/**
+ * A configuration number that must be finite and strictly positive.
+ *
+ * Shared by `gate` and `shouldStop` so the two entry points cannot drift on
+ * what they accept. They did drift: `gate` rejected a non-positive
+ * `altConcentration` and `shouldStop` passed it through to a prior floor, so
+ * the same options object was a refusal through one door and a verdict through
+ * the other.
+ */
+export declare function requirePositiveConfig(v: number, name: string, where: string): void;
+/**
+ * The largest `altConcentration` the default statistic accepts at a verdict.
+ *
+ * Its error control is computed rather than proven, and a concentrated
+ * alternative is the one known way it exceeds alpha at a rate inside the
+ * checked range: 1.04 times alpha at 32 (`test/error-control.test.ts`). At 16
+ * the worst checked cell is 0.91 of alpha.
+ */
+export declare const MAX_ALT_CONCENTRATION = 16;
+/**
+ * `altConcentration` for a verdict: finite and positive, and at most
+ * `MAX_ALT_CONCENTRATION` under the default `bayes` statistic. `universal` is
+ * valid at every rate by construction, so it takes any positive value.
+ */
+export declare function requireAltConcentration(v: number, evidence: string, where: string): void;
+/**
+ * The error rates of a Wald SPRT, run by `sprtDecision` or priced by a
+ * planner: each strictly between 0 and 1, and summing to less than 1.
+ *
+ * At `alpha + beta >= 1` Wald's walls meet or cross, so the test decides
+ * before it has seen a run. `sprtExpectedN` answered a small positive number
+ * there, and a plan at `alpha: 0.6, beta: 0.5` priced every case at
+ * `minTrials` with nothing to say the design had no error control left.
+ */
+export declare function requireErrorRates(alpha: number, beta: number, where: string): void;
+/**
+ * `runsPerCaseCeiling`: finite and at least one run. The planners search up to
+ * eight times it, and at NaN or 0 that search never ran, so every case came
+ * back undecidable with a reason that blamed the evidence bar.
+ */
+export declare function requireRunCeiling(v: number, where: string): void;
+/**
+ * The batch grid a plan prices the gate on: `minTrials` and `batchSize`
+ * positive integers, `maxTrials` an integer at least `minTrials`. A NaN bound
+ * or a zero batch made the typical bill NaN, and a cap under the minimum
+ * priced every case at the cap.
+ */
+export declare function requireTrialGrid(cfg: {
+    minTrials: number;
+    maxTrials: number;
+    batchSize: number;
+}, where: string): void;
+/** The four cells of a pair table, each a non-negative integer. */
+export declare function requirePairedCounts(p: {
+    bothPass: number;
+    worse: number;
+    better: number;
+    bothFail: number;
+}, where: string): void;
+export declare function requireProbability(p: number, name: string, where: string): void;
+/** Case ids, each at most once: a repeated id is planned twice and inflates the suite size the bar is set from. */
+export declare function requireUniqueCaseIds(cases: readonly {
+    id: string;
+}[], where: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,192 @@
+/**
+ * errors.ts: one error class, stable codes, structured detail.
+ *
+ * Nothing in peeksafe throws a bare string. Every code below is thrown
+ * somewhere in `src/` and is part of the public contract: a caller may branch
+ * on `err.code` and we will not repurpose one.
+ */
+export class PeeksafeError extends Error {
+    code;
+    detail;
+    hint;
+    constructor(code, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = "PeeksafeError";
+        this.code = code;
+        this.detail = opts.detail ?? {};
+        this.hint = opts.hint;
+    }
+    /** Stable JSON shape, for logs and CI artifacts. */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            ...(this.hint ? { hint: this.hint } : {}),
+            detail: this.detail,
+        };
+    }
+    static is(e) {
+        return e instanceof PeeksafeError;
+    }
+}
+/**
+ * Domain guard for the statistics. Every function in `stats.ts` that can be
+ * handed nonsense (successes > trials, a negative count, an MDE larger than the
+ * baseline rate) routes through here rather than returning NaN.
+ */
+export function requireCounts(successes, trials, where) {
+    if (!Number.isFinite(successes) || !Number.isFinite(trials)) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: counts must be finite`, {
+            detail: { successes, trials, where },
+        });
+    }
+    if (!Number.isInteger(successes) || !Number.isInteger(trials)) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: counts must be integers`, {
+            detail: { successes, trials, where },
+        });
+    }
+    if (trials < 0 || successes < 0 || successes > trials) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: need 0 ≤ successes ≤ trials, got ${successes}/${trials}`, { detail: { successes, trials, where } });
+    }
+}
+/**
+ * A probability that must be strictly inside (0,1), a rate, an effect size, an
+ * error budget. `requireProbability` allows the endpoints, which is right for a
+ * *rate* and wrong for an *effect*: an MDE of 0 asks for a zero-point drop to be
+ * detected, which every design answers "no" to for reasons that look like a
+ * ceiling problem and are not.
+ */
+export function requireOpenProbability(p, name, where) {
+    if (!Number.isFinite(p) || p <= 0 || p >= 1) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: ${name} must be strictly between 0 and 1, got ${p}`, {
+            detail: { [name]: p, where },
+        });
+    }
+}
+/**
+ * A configuration number that must be finite and strictly positive.
+ *
+ * Shared by `gate` and `shouldStop` so the two entry points cannot drift on
+ * what they accept. They did drift: `gate` rejected a non-positive
+ * `altConcentration` and `shouldStop` passed it through to a prior floor, so
+ * the same options object was a refusal through one door and a verdict through
+ * the other.
+ */
+export function requirePositiveConfig(v, name, where) {
+    if (!Number.isFinite(v) || v <= 0) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: ${name} must be finite and positive, got ${v}`, {
+            detail: { [name]: v, where },
+        });
+    }
+}
+/**
+ * The largest `altConcentration` the default statistic accepts at a verdict.
+ *
+ * Its error control is computed rather than proven, and a concentrated
+ * alternative is the one known way it exceeds alpha at a rate inside the
+ * checked range: 1.04 times alpha at 32 (`test/error-control.test.ts`). At 16
+ * the worst checked cell is 0.91 of alpha.
+ */
+export const MAX_ALT_CONCENTRATION = 16;
+/**
+ * `altConcentration` for a verdict: finite and positive, and at most
+ * `MAX_ALT_CONCENTRATION` under the default `bayes` statistic. `universal` is
+ * valid at every rate by construction, so it takes any positive value.
+ */
+export function requireAltConcentration(v, evidence, where) {
+    requirePositiveConfig(v, "altConcentration", where);
+    if (evidence === "bayes" && v > MAX_ALT_CONCENTRATION) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: altConcentration must be at most ${MAX_ALT_CONCENTRATION} with the default statistic, got ${v}`, {
+            detail: { altConcentration: v, max: MAX_ALT_CONCENTRATION, evidence, where },
+            hint: "Use evidence: 'universal' for a more concentrated alternative, or check the rates with typeOneError.",
+        });
+    }
+}
+/**
+ * The error rates of a Wald SPRT, run by `sprtDecision` or priced by a
+ * planner: each strictly between 0 and 1, and summing to less than 1.
+ *
+ * At `alpha + beta >= 1` Wald's walls meet or cross, so the test decides
+ * before it has seen a run. `sprtExpectedN` answered a small positive number
+ * there, and a plan at `alpha: 0.6, beta: 0.5` priced every case at
+ * `minTrials` with nothing to say the design had no error control left.
+ */
+export function requireErrorRates(alpha, beta, where) {
+    requireOpenProbability(alpha, "alpha", where);
+    requireOpenProbability(beta, "beta", where);
+    if (alpha + beta >= 1) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: alpha + beta must be under 1, got ${alpha} + ${beta}`, {
+            detail: { alpha, beta, where },
+            hint: "a test with alpha + beta >= 1 does no better than ignoring the data",
+        });
+    }
+}
+/**
+ * `runsPerCaseCeiling`: finite and at least one run. The planners search up to
+ * eight times it, and at NaN or 0 that search never ran, so every case came
+ * back undecidable with a reason that blamed the evidence bar.
+ */
+export function requireRunCeiling(v, where) {
+    if (!(v >= 1) || !Number.isFinite(v)) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: runsPerCaseCeiling must be finite and at least 1, got ${v}`, {
+            detail: { runsPerCaseCeiling: v, where },
+        });
+    }
+}
+/**
+ * The batch grid a plan prices the gate on: `minTrials` and `batchSize`
+ * positive integers, `maxTrials` an integer at least `minTrials`. A NaN bound
+ * or a zero batch made the typical bill NaN, and a cap under the minimum
+ * priced every case at the cap.
+ */
+export function requireTrialGrid(cfg, where) {
+    const { minTrials, maxTrials, batchSize } = cfg;
+    const detail = { minTrials, maxTrials, batchSize, where };
+    for (const [name, v] of [
+        ["minTrials", minTrials],
+        ["batchSize", batchSize],
+    ]) {
+        if (!Number.isInteger(v) || v < 1) {
+            throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: ${name} must be a positive integer, got ${v}`, { detail });
+        }
+    }
+    if (!Number.isInteger(maxTrials) || maxTrials < minTrials) {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: maxTrials must be an integer ≥ minTrials, got ${maxTrials} vs ${minTrials}`, {
+            detail,
+            hint: "the typical bill is clamped to [minTrials, maxTrials]; a cap under the minimum prices a gate that stops before it starts",
+        });
+    }
+}
+/** The four cells of a pair table, each a non-negative integer. */
+export function requirePairedCounts(p, where) {
+    for (const name of ["bothPass", "worse", "better", "bothFail"]) {
+        const v = p[name];
+        if (!Number.isInteger(v) || v < 0) {
+            throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: ${name} must be a non-negative integer, got ${v}`, {
+                detail: { [name]: v, where },
+            });
+        }
+    }
+}
+export function requireProbability(p, name, where) {
+    if (!Number.isFinite(p) || p < 0 || p > 1) {
+        throw new PeeksafeError("PEEKSAFE_E_STAT_DOMAIN", `${where}: ${name} must be in [0,1], got ${p}`, {
+            detail: { [name]: p, where },
+        });
+    }
+}
+/** Case ids, each at most once: a repeated id is planned twice and inflates the suite size the bar is set from. */
+export function requireUniqueCaseIds(cases, where) {
+    const seen = new Set();
+    for (const c of cases) {
+        if (seen.has(c.id)) {
+            throw new PeeksafeError("PEEKSAFE_E_CASE_DUPLICATE", `${where}: duplicate case id ${c.id}`, {
+                detail: { id: c.id, where },
+                hint: "a case listed twice is priced twice and counted twice in the suite size; dedupe the case list before calling",
+            });
+        }
+        seen.add(c.id);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/evidence.d.ts

@@ -0,0 +1,15 @@
+/**
+ * evidence.ts: which two-sample e-value a decision uses, and its ceiling.
+ *
+ * `bayes` is `twoSampleLogE`, the default: more evidence per run, with error
+ * control checked numerically rather than proven. `universal` is
+ * `universalTwoSampleLogE`: valid at every rate by construction, with less
+ * evidence per run. README, "What that guarantee rests on", has the numbers.
+ */
+export type Evidence = "bayes" | "universal";
+export declare function requireEvidence(evidence: unknown, where: string): asserts evidence is Evidence;
+export declare const logEvidence: (evidence: Evidence, cs: number, cn: number, bs: number, bn: number, mde: number, altConcentration: number) => number;
+export declare const toEvalue: (logE: number) => number;
+/** The most evidence a candidate at rate `p` could ever reach against this baseline. */
+export declare const ceilingLogEvidence: (evidence: Evidence, p: number, bs: number, bn: number, mde: number, altConcentration: number) => number;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAE7C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAU9F;AAED,eAAO,MAAM,WAAW,aACZ,QAAQ,MACd,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACL,MAAM,oBACO,MAAM,KACvB,MAGuD,CAAC;AAG3D,eAAO,MAAM,QAAQ,SAAU,MAAM,KAAG,MAGvC,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,aACnB,QAAQ,KACf,MAAM,MACL,MAAM,MACN,MAAM,OACL,MAAM,oBACO,MAAM,KACvB,MAGwD,CAAC"}

package/dist/evidence.js

@@ -0,0 +1,30 @@
+/**
+ * evidence.ts: which two-sample e-value a decision uses, and its ceiling.
+ *
+ * `bayes` is `twoSampleLogE`, the default: more evidence per run, with error
+ * control checked numerically rather than proven. `universal` is
+ * `universalTwoSampleLogE`: valid at every rate by construction, with less
+ * evidence per run. README, "What that guarantee rests on", has the numbers.
+ */
+import { PeeksafeError } from "./errors.js";
+import { evidenceCeilingLogE, twoSampleLogE, universalCeilingLogE, universalTwoSampleLogE, } from "./stats.js";
+export function requireEvidence(evidence, where) {
+    if (evidence !== "bayes" && evidence !== "universal") {
+        throw new PeeksafeError("PEEKSAFE_E_CONFIG", `${where}: evidence must be 'bayes' or 'universal', got ${String(evidence)}`, {
+            detail: { evidence },
+        });
+    }
+}
+export const logEvidence = (evidence, cs, cn, bs, bn, mde, altConcentration) => evidence === "universal"
+    ? universalTwoSampleLogE(cs, cn, bs, bn, mde, altConcentration)
+    : twoSampleLogE(cs, cn, bs, bn, mde, altConcentration);
+// exp() of a large logE overflows, and e-BH cannot rank an infinite entry; the largest double keeps the order.
+export const toEvalue = (logE) => {
+    const e = Math.exp(logE);
+    return Number.isFinite(e) ? e : Number.MAX_VALUE;
+};
+/** The most evidence a candidate at rate `p` could ever reach against this baseline. */
+export const ceilingLogEvidence = (evidence, p, bs, bn, mde, altConcentration) => evidence === "universal"
+    ? universalCeilingLogE(p, bs, bn)
+    : evidenceCeilingLogE(p, bs, bn, mde, altConcentration);
+//# sourceMappingURL=evidence.js.map

package/dist/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAIpB,MAAM,UAAU,eAAe,CAAC,QAAiB,EAAE,KAAa;IAC9D,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QACrD,MAAM,IAAI,aAAa,CACrB,mBAAmB,EACnB,GAAG,KAAK,kDAAkD,MAAM,CAAC,QAAQ,CAAC,EAAE,EAC5E;YACE,MAAM,EAAE,EAAE,QAAQ,EAAE;SACrB,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,QAAkB,EAClB,EAAU,EACV,EAAU,EACV,EAAU,EACV,EAAU,EACV,GAAW,EACX,gBAAwB,EAChB,EAAE,CACV,QAAQ,KAAK,WAAW;IACtB,CAAC,CAAC,sBAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,gBAAgB,CAAC;IAC/D,CAAC,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC;AAE3D,+GAA+G;AAC/G,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAU,EAAE;IAC/C,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;AACnD,CAAC,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,QAAkB,EAClB,CAAS,EACT,EAAU,EACV,EAAU,EACV,GAAW,EACX,gBAAwB,EAChB,EAAE,CACV,QAAQ,KAAK,WAAW;IACtB,CAAC,CAAC,oBAAoB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;IACjC,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/frontier.d.ts

@@ -0,0 +1,271 @@
+/**
+ * frontier.ts: what *is* certifiable at coding-agent prices, and how.
+ *
+ * ## Why this module exists
+ *
+ * At $1 a run a 200-case suite at a 15-point MDE is $1,320 a pull request, so
+ * peeksafe is not a per-PR gate for a coding-agent benchmark at that size. That
+ * is true and it is half an answer. The other half, the one a
+ * buyer actually needs, is **which configurations *are* affordable**, and
+ * nobody had drawn it.
+ *
+ * A configuration is a point in five dimensions:
+ *
+ *     suite size m  ×  MDE δ  ×  design  ×  screening  ×  baseline runs n_b
+ *
+ * and it is usable only if it is *both* affordable and **certifiable**. Those
+ * are different constraints, and a plan that conflates them quotes the wrong
+ * numbers. Cheap is easy: run fewer cases. Cheap *and able to decide anything* is
+ * the hard part, because `evidenceCeilingLogE` says a case whose unpaired
+ * ceiling sits under the e-BH bar cannot be certified at any budget, and the
+ * bar `m/q` moves with the suite size, so shrinking the suite raises the
+ * ceiling's odds *and* lowers the bar at the same time. That interaction is not
+ * something you can eyeball.
+ *
+ * ## The cost model, and the term the plan was missing
+ *
+ * `plan.ts` prices an observation at one number, `costPerRunUsd`. That is wrong
+ * in two ways at coding-agent prices, and both matter:
+ *
+ *  1. **Grading is not free.** An LLM judge is a model call; a coding-agent
+ *     grader is a test suite in a container. So
+ *
+ *         cost(observation) = costPerRunUsd + costPerGradeUsd
+ *
+ *     and the second term is the *only* one a cheap proxy grader can reduce.
+ *     When `costPerGradeUsd` is 0, which is the default,
+ *     matching this package's own free graders, a proxy screen saves exactly
+ *     nothing, and this module says so instead of offering it as an economy.
+ *
+ *  2. **The baseline is not free either, and it is not amortised over
+ *     infinity.** The README calls the baseline "amortised, you pay it once on
+ *     main". At $0.002 a run that is a rounding error. At $1 a run, a 200-case
+ *     suite with a 240-run baseline is 48,000 runs, **$48,000**, and spread
+ *     over a hundred pull requests it is still $480 each, which is larger than
+ *     everything else in the bill put together. The unpaired design's evidence
+ *     ceiling is bought with baseline runs, so *the amortised baseline is the
+ *     dominant cost of the unpaired design at coding-agent prices*, and the
+ *     paired design's headline advantage is not variance reduction. It is that
+ *     it does not need to buy a ceiling.
+ *
+ * ## What this module will not do
+ *
+ * It will not recommend a screened configuration whose **recall cost has not
+ * been measured**. Screening is the largest cost lever available and it is paid
+ * for in missed regressions, which the caller supplies as `screenRecall`
+ * against planted ground truth, and until someone has, the honest price of a
+ * screened plan is unknown rather than low.
+ */
+export type FrontierDesign = "unpaired" | "paired";
+/**
+ * What the screening pass grades with.
+ *  - `none`      every case goes straight to the sequential test
+ *  - `expensive` the screen pays the real grader for its k runs per case
+ *  - `proxy`     the screen ranks on a cheap deterministic grader, so its runs
+ *                cost `costPerRunUsd` and no grade. Sound, a screen chooses
+ *                where to spend and cannot falsely certify, but it ranks on an
+ *                effect attenuated by Youden's J, so it costs
+ *                power, and the power is what has to be measured.
+ */
+export type FrontierScreen = "none" | "expensive" | "proxy";
+/**
+ * Which bill the budget is checked against. Three, because they are three
+ * genuinely different questions, and answering one while quoting another
+ * misprices the plan.
+ *
+ *  `'typical'`, a pull request that changed nothing. Almost every pull request
+ *  is this one. Budget from it and a genuine regression overruns and comes
+ *  back uncertified, which is a survivable failure.
+ *
+ *  `'certify-all'`, every case regressed by exactly the MDE and every one had
+ *  to be certified. It was once called "the ceiling", and
+ *  it is **not** an upper bound: at a large MDE against a sharp baseline,
+ *  certifying a real regression is *cheaper* than clearing a case that did not
+ *  move, so this bill can come in under the typical one. The arithmetic was
+ *  never wrong; the word "ceiling" was.
+ *
+ *  `'ceiling'`, every case the screen kept runs to the per-case cap
+ *  (`maxTrials` observations). The gate cannot spend more than that by
+ *  construction, so nothing can overrun it. This is the basis to use when the
+ *  gate must return a verdict rather than a deferral, and it changes which
+ *  *design* wins: paired costs two runs an observation and loses the typical
+ *  basis by construction, while on the ceiling basis, and whenever the
+ *  baseline cannot be amortised, it wins outright.
+ */
+export type FrontierBasis = "typical" | "certify-all" | "ceiling";
+export interface FrontierAxes {
+    cases: number[];
+    /** in probability units, e.g. 0.15 for 15 points */
+    mdes: number[];
+    baselineRuns: number[];
+    designs: FrontierDesign[];
+    screens: FrontierScreen[];
+    /** screening runs per case; only consulted for screens other than `none` */
+    screenRuns: number[];
+}
+export declare const DEFAULT_AXES: FrontierAxes;
+export interface FrontierConfig {
+    /** the budget one pull request may spend */
+    budgetUsd: number;
+    /** which bill the budget is checked against */
+    basis: FrontierBasis;
+    /** USD to execute the agent once on one case */
+    costPerRunUsd: number;
+    /**
+     * USD to *grade* one output with the real grader. Zero for this package's own
+     * graders; a model call or a container run for anything real. This is the
+     * only term a proxy grader can reduce.
+     */
+    costPerGradeUsd: number;
+    /** the pass rate a typical case sits at, used for every power calculation */
+    baselineRate: number;
+    /** suite-level false discovery rate */
+    fdr: number;
+    /** measured pair coupling in [0,1] */
+    pairCoupling: number;
+    /**
+     * How many pull requests one recorded baseline is spread over before it is
+     * re-recorded. The README's "amortised" claim is exactly this number, and it
+     * had never been written down.
+     */
+    amortisePrs: number;
+    /**
+     * Baseline runs per case the *paired* design needs. The paired e-value's null
+     * is a point mass, so the stored baseline is not part of its validity and
+     * does not set a ceiling; here it is only the baseline bill, since a paired
+     * typical bill is priced in pairs to settle. A short one is enough, and that
+     * asymmetry is most of why the paired design wins at these prices.
+     */
+    pairedBaselineRuns: number;
+    /** fraction of cases a screen carries through to the expensive test */
+    screenKeepFraction: number;
+    /** past this many runs for one case, call it unaffordable regardless of budget */
+    runsPerCaseCeiling: number;
+    /**
+     * Measured recall of the screen, per screen kind. `null` means nobody has
+     * measured it, and a configuration using that screen will be reported but
+     * never *recommended*.
+     */
+    screenRecall: {
+        expensive: number | null;
+        proxy: number | null;
+    };
+    /** free text saying where `screenRecall` came from; printed next to it */
+    screenRecallSource: string;
+    /** the sequential design being priced; match the stopping rule you actually run */
+    alpha: number;
+    beta: number;
+    minTrials: number;
+    maxTrials: number;
+    batchSize: number;
+    nullQuantile: number;
+    /** the `futilityConfidence` `shouldStopPaired` runs at; unset takes its default */
+    futilityConfidence?: number;
+}
+export declare const DEFAULT_FRONTIER: FrontierConfig;
+/** A cost broken into the three things a pull request actually pays for. */
+export interface FrontierCost {
+    screenRuns: number;
+    screenUsd: number;
+    testRuns: number;
+    testUsd: number;
+    /** baseline runs charged to *this* pull request after amortisation */
+    baselineRunsAmortised: number;
+    baselineUsd: number;
+    totalUsd: number;
+}
+export interface FrontierPoint {
+    cases: number;
+    mde: number;
+    baselineRuns: number;
+    design: FrontierDesign;
+    screen: FrontierScreen;
+    /** 0 when `screen` is `none` */
+    screenRunsPerCase: number;
+    /** how many cases the screen carries through */
+    keep: number;
+    /** e-BH solo bar, in logs */
+    barLogE: number;
+    /** unpaired evidence ceiling at this baseline size, in logs. −∞ is not used;
+     *  the paired design has no ceiling and this field is `null` for it. */
+    ceilingLogE: number | null;
+    feasible: boolean;
+    /** why not, when not. Never empty when `feasible` is false. */
+    infeasibleBecause: string | null;
+    /** observations per case to certify a case that really regressed */
+    certifyObservations: number;
+    /** observations per case on a pull request that changed nothing */
+    typicalObservations: number;
+    /**
+     * The per-case run cap this configuration needs. A `shouldStop` `maxTrials`
+     * below it stops cases short with reason `budget`, however much money is left.
+     */
+    requiresMaxRuns: number;
+    /** true when `requiresMaxRuns` exceeds the gate's configured cap */
+    exceedsGateCap: boolean;
+    /** a pull request that changed nothing, the number to budget from */
+    typical: FrontierCost;
+    /** every case regressed by exactly the MDE and had to be certified. A scenario, not a bound. */
+    certifyAll: FrontierCost;
+    /** every kept case ran to the per-case cap, the bill nothing can exceed */
+    ceiling: FrontierCost;
+    /** whichever of the three the configured `basis` selects, what the budget is checked against */
+    basisCostUsd: number;
+    withinBudget: boolean;
+    /** measured recall of this configuration's screen; null when unmeasured */
+    screenRecall: number | null;
+    /** true when this configuration may be *recommended*, not merely reported */
+    recommendable: boolean;
+    /** why it is reported but not recommendable */
+    caveat: string | null;
+}
+/** $1.00, but $0.0021 rather than $0.00, a per-run price rounds to nothing. */
+export declare const fmtRate: (x: number) => string;
+/**
+ * Observations per case on a pull request where nothing moved, clamped onto the
+ * gate's own batch grid.
+ */
+export declare function typicalObservationsPerCase(rate: number, mde: number, cfg: FrontierConfig, baselineRuns: number): number;
+export declare function evaluatePoint(cases: number, mde: number, baselineRuns: number, design: FrontierDesign, screen: FrontierScreen, screenRunsPerCase: number, cfg: FrontierConfig): FrontierPoint;
+/** Every point in the swept space, feasible or not. */
+export declare function enumerateFrontier(cfg: FrontierConfig, axes?: FrontierAxes): FrontierPoint[];
+export interface FrontierCell {
+    cases: number;
+    mde: number;
+    /** the cheapest recommendable configuration that certifies this cell */
+    best: FrontierPoint;
+    /** the cheapest configuration ignoring the recommendable rule, when it differs */
+    cheapestReported: FrontierPoint | null;
+}
+export interface FrontierResult {
+    config: FrontierConfig;
+    axes: FrontierAxes;
+    /** everything swept */
+    points: FrontierPoint[];
+    /** feasible, within budget, and recommendable */
+    affordable: FrontierPoint[];
+    /**
+     * The frontier proper: the (cases, mde) cells that are achievable within
+     * budget and not dominated by another achievable cell, i.e. no other cell
+     * has at least as many cases *and* an MDE at least as tight.
+     */
+    frontier: FrontierCell[];
+    /** cheapest feasible configuration overall, whether or not it fits */
+    cheapestFeasible: FrontierPoint | null;
+    /** the smallest budget at which anything at all becomes recommendable */
+    minimumViableBudgetUsd: number | null;
+    headline: string;
+}
+export declare function computeFrontier(cfg: FrontierConfig, axes?: FrontierAxes): FrontierResult;
+/**
+ * Where the money goes, for one configuration. Printed under the frontier
+ * because the shares are the actual finding: at coding-agent prices the
+ * unpaired design's amortised baseline is usually the largest line, and it is
+ * the one the README used to call free.
+ */
+export declare function costShares(p: FrontierPoint, basis?: FrontierBasis): {
+    screen: number;
+    test: number;
+    baseline: number;
+};
+//# sourceMappingURL=frontier.d.ts.map

package/dist/frontier.d.ts.map

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