@mark1russell7/rigor-bench 0.2.13 → 0.2.15

package/build/index.d.ts

@@ -1,5 +1,5 @@
 import { a as checkPairedTime, i as caseRatios, n as CaseRatio, o as firstArm, r as PairedTime, t as Arm } from "./paired.js";
-import { BootstrapOptions, Comparison, Interval } from "@mark1russell7/rigor-statistics";
+import { BootstrapOptions, Comparison as Comparison$1, Interval } from "@mark1russell7/rigor-statistics";
 /** One value of one build on one case. The value is finite and 0 or more. */
 interface BudgetRound {
   /** The name of the case: one input of the bench. */
@@ -124,239 +124,6 @@ export declare function budgetLookSpend(looks: readonly BudgetLook[]): number;
  * - The field `fails` is true only for the outcome `beyond`. Tell a final `cannot decide` to the reader of the run.
  */
 export declare function budgetLooksVerdict(rounds: readonly BudgetRound[], aa: readonly BudgetRound[], options: BudgetLooksOptions): BudgetLooksVerdict;
-/** One time of the control in one group. */
-interface ControlRow {
-  /** The name of the group: a run, or a shard of one run. */
-  readonly group: string;
-  /** The name of a class of work. The same key in two groups names equal work, so a ratio of the two measures the load. */
-  readonly key: string;
-  /** The time. It is finite and more than 0. */
-  readonly value: number;
-  /** This field is true when the run stopped the case at `value`. Thus the real time is at least `value`. */
-  readonly censored?: boolean;
-}
-/** The options of `controlFactor`. */
-interface ControlOptions {
-  /** The group that the factors compare with. Without it, the base of each key is the median of that key over the groups. */
-  readonly base?: string;
-  /** The least number of keys in a factor. A group with fewer keys has no factor. The default is 5. */
-  readonly minPairs?: number;
-}
-/** The counts of one group, with or without a factor. */
-interface GroupCounts {
-  readonly group: string;
-  /** The number of keys that the factor reads. */
-  readonly pairs: number;
-  /** The number of keys that this function left out because a time of the key was censored. The factor reads low when this count is not 0. */
-  readonly censored: number;
-  /** The number of keys of this group that have no time to compare with, so no ratio reads them. */
-  readonly unshared: number;
-}
-/** The factor of one group. */
-interface MeasuredFactor extends GroupCounts {
-  /** The median ratio of the times of this group over the base. A factor of 1.6 means that this group took 1.6 times as long. */
-  readonly factor: number;
-  /** The quartiles of the ratios. A wide spread means that one factor does not explain the load. */
-  readonly low: number;
-  readonly high: number;
-}
-/** A group with too few usable keys. It has no factor, and the other groups keep theirs. */
-interface NoFactor extends GroupCounts {
-  readonly factor: undefined;
-  /** The reason that this group has no factor. */
-  readonly reason: string;
-}
-/** The result of one group. Read `factor` first: a group with too few usable keys has no factor. */
-type GroupFactor = MeasuredFactor | NoFactor;
-/** The factors of a run, with the base that they use. */
-interface ControlFactors {
-  /** The base group, or undefined when the base of each key is its median over the groups. */
-  readonly base: string | undefined;
-  readonly factors: readonly GroupFactor[];
-}
-/**
- * This function gives the load factor of each group from the times of a control.
- *
- * With `base`, a factor compares the keys that a group shares with that group. Without it, a factor compares each time with the median of its key over the groups.
- * A key names a class of work, so equal keys in two groups mean equal work. Each group has at most one row for a key.
- *
- * A censored time is only a lower limit, so no ratio reads it, and the result counts those keys. A run stops its slowest cases, so a factor reads low when `censored` is not 0.
- *
- * A group with too few usable keys gets an entry with no factor and its reason, so the other groups keep their factors. This function refuses a result where no group has a factor.
- */
-export declare function controlFactor(rows: readonly ControlRow[], options?: ControlOptions): ControlFactors;
-/** The format name of a ladder. It changes when a reader of an older form cannot read the data. */
-export declare const LADDER_FORMAT = "rigor-ladder/1";
-/** One dimension of a ladder, for example tenants or nodes. */
-interface LadderDimension {
-  readonly name: string;
-  /** What one unit of the dimension is, in plain words. */
-  readonly describe: string;
-}
-/** A budget on the median of each case, for example the time of a read. A record gives rounds and an A/A arm. */
-interface MedianBudget {
-  readonly kind: "median";
-  readonly measure: string;
-  /** The unit of the limit and of the values. */
-  readonly unit: string;
-  /** The largest median that the budget permits. */
-  readonly limit: number;
-  /** The largest difference between the medians of the two arms. A larger difference makes the run too noisy. */
-  readonly maxDifference: number;
-  /** The level of the interval of each median. The default is 0.95. */
-  readonly caseLevel?: number;
-}
-/** A budget on the share of failed trials, for example failed requests. A record gives failures and trials. */
-interface RateBudget {
-  readonly kind: "rate";
-  readonly measure: string;
-  /** The largest share of failures that the budget permits, from 0 to 1. */
-  readonly limit: number;
-}
-/** A budget on the largest value of a set of drills, for example the writes that a restore lost. One bad drill is `beyond`. */
-interface WorstBudget {
-  readonly kind: "worst";
-  readonly measure: string;
-  readonly unit: string;
-  /** The largest value that the budget permits in any drill. */
-  readonly limit: number;
-  /** The number of drills that a verdict needs, 1 or more. With fewer, the budget is `cannot decide`. */
-  readonly minDrills: number;
-}
-/**
- * A budget on a high quantile, for example the p99 of a read. A record gives the values. The verdict is the distribution-free
- * interval of the quantile against the limit. A p99 needs 368 independent values at the level 0.95: refer to `quantileSamples`.
- * Successive times of one run can follow each other. Space them apart, or give one value for each run.
- *
- * The evidence can also hold `censored`: a lower bound for each arrival with no reply, and for each arrival that was not
- * sent. The bound is the time that the arrival waited. The true value is that bound or more, with no upper limit. Thus the
- * low end of the interval reads the bounds, and the high end reads each censored value as `Infinity`. A `beyond` stays
- * provable from the bounds alone. A `within` needs real replies up to the upper rank of the interval.
- */
-interface QuantileBudget {
-  readonly kind: "quantile";
-  readonly measure: string;
-  /** The unit of the limit and of the values. */
-  readonly unit: string;
-  /** The quantile, more than 0 and less than 1, for example 0.99. */
-  readonly quantile: number;
-  /** The largest quantile that the budget permits. */
-  readonly limit: number;
-  /** The level of the interval. The default is 0.95. */
-  readonly level?: number;
-}
-/** One budget of a rung. */
-type RungBudget = MedianBudget | QuantileBudget | RateBudget | WorstBudget;
-/** One rung of a ladder. */
-interface Rung {
-  /** The name of the rung, unique in the ladder. */
-  readonly name: string;
-  /** The size of the rung in each dimension that it names. */
-  readonly at: Readonly<Record<string, number>>;
-  readonly budgets: readonly RungBudget[];
-  /** The name of the automatic test that holds the rung. */
-  readonly test: string;
-  /** True when a gate holds the rung: the verdict fails when the rung is not `within`. */
-  readonly locked?: boolean;
-}
-/** The ladder of one subject. The rungs go from the smallest to the largest. */
-interface Ladder {
-  readonly format: typeof LADDER_FORMAT;
-  /** The product or the service that the ladder is for. */
-  readonly subject: string;
-  readonly dimensions: readonly LadderDimension[];
-  readonly rungs: readonly Rung[];
-}
-/** The measured evidence for one budget. Its `kind` is the kind of the budget. */
-type RungEvidence = {
-  readonly kind: "median";
-  readonly measure: string;
-  readonly rounds: readonly BudgetRound[];
-  readonly aa: readonly BudgetRound[];
-} | {
-  readonly kind: "quantile";
-  readonly measure: string;
-  readonly values: readonly number[];
-  readonly censored?: readonly number[];
-} | {
-  readonly kind: "rate";
-  readonly measure: string;
-  readonly failures: number;
-  readonly trials: number;
-} | {
-  readonly kind: "worst";
-  readonly measure: string;
-  readonly values: readonly number[];
-};
-/** One run of the test of a rung. */
-interface RungRecord {
-  /** The name of the rung. */
-  readonly rung: string;
-  /** The commit that the run measured. */
-  readonly commit: string;
-  /** The time of the run, as an ISO 8601 string. */
-  readonly at: string;
-  /** What the run did for real, for example "2 processes" or "a restore from a real backup". */
-  readonly real: readonly string[];
-  /** What the run made up, for example "90 % of the tenants as data at rest". An empty list states that nothing was synthetic. */
-  readonly synthetic: readonly string[];
-  readonly evidence: readonly RungEvidence[];
-}
-/** The verdict of one budget of a rung. */
-interface BudgetResult {
-  readonly measure: string;
-  readonly outcome: BudgetOutcome;
-  /** The reason of the outcome, in one sentence, with the numbers. */
-  readonly reason: string;
-}
-/** The verdict of one rung. */
-interface RungVerdict {
-  readonly rung: string;
-  readonly test: string;
-  readonly locked: boolean;
-  readonly outcome: BudgetOutcome;
-  /** The reason of the outcome, in one sentence. */
-  readonly reason: string;
-  readonly budgets: readonly BudgetResult[];
-  /** The commit of the record, or undefined when the rung has no record. */
-  readonly commit: string | undefined;
-  readonly real: readonly string[];
-  readonly synthetic: readonly string[];
-}
-/** The verdict of a ladder. */
-interface LadderVerdict {
-  readonly subject: string;
-  /** The highest rung with each rung up to it `within`, or undefined when the first rung is not `within`. */
-  readonly held: string | undefined;
-  /** The first rung that is not `within`, or undefined when each rung is `within`. */
-  readonly next: string | undefined;
-  /** True when a locked rung is not `within`. A rung with no result is not held, so `cannot decide` fails too. */
-  readonly failed: boolean;
-  /** The reason of `failed`, in one sentence. */
-  readonly reason: string;
-  readonly rungs: readonly RungVerdict[];
-}
-/** The options of a ladder verdict. */
-interface LadderOptions {
-  /** The time of the verdict, as an ISO 8601 string. It is an input, so that a verdict is the same at each read. */
-  readonly now: string;
-  /** The largest age of a record, in days. An older record gives `cannot decide`. The default accepts any age. */
-  readonly maxAgeDays?: number;
-}
-/**
- * This function gives each problem of a ladder as data, or an empty list. A ladder needs a subject, one dimension or more,
- * and one rung or more. Names are unique. Each rung names a test and has budgets. From one rung to the next, each dimension
- * that the two rungs name grows.
- */
-export declare function checkLadder(ladder: Ladder): readonly string[];
-/** This function gives the verdict of one rung from its record. With no record, the rung is `cannot decide`. */
-export declare function rungVerdict(rung: Rung, record: RungRecord | undefined, options: LadderOptions): RungVerdict;
-/**
- * This function gives the verdict of a ladder from the records of its rungs. It uses the newest record of each rung, so an
- * older pass does not hide a newer failure. A rung high up does not count when a rung below it is not `within`. It throws
- * a `RangeError` for a ladder with problems, because a verdict on a bad ladder has no meaning. See `checkLadder`.
- */
-export declare function ladderVerdict(ladder: Ladder, records: readonly RungRecord[], options: LadderOptions): LadderVerdict;
 /**
  * The two kinds of an A/A band.
  * - The band `case` holds the ratio of one A/A case. It is wide, so it finds only a large change.
@@ -498,7 +265,7 @@ interface TimeVerdict {
    * The counts of the cases out of the band, or undefined without a band.
    * The comparison uses the value `1 + log(ratio)` of each case and the noise of the band, so its two sides are the ends of the band.
    */
-  readonly comparison: Comparison | undefined;
+  readonly comparison: Comparison$1 | undefined;
   /** The facts of the pooled band. The verdict has this field only with the option `pool`. */
   readonly pool?: PoolFacts;
   /** The noise cap. The verdict has this field only with the option `noiseCap`. */
@@ -698,6 +465,551 @@ interface RunPairs {
  * It balances the records of each pair with `balanceOrders` first. It refuses an `aaPair` that the run does not have.
  */
 export declare function armVerdicts(run: RunPairs, aaPair: string, options?: VerdictOptions): Record<string, TimeVerdict>;
+/** The three results of a gate. */
+type GateOutcome = "pass" | "block" | "no read";
+/** The fields of a case that a gate reads. The cases of `limitVerdict`, `budgetVerdict` and the verdict of this file have them. */
+interface GateCaseOutcome {
+  readonly case: string;
+  readonly outcome: LimitOutcome;
+}
+/** The result of a gate, with the cases that make it. */
+interface Gate {
+  readonly outcome: GateOutcome;
+  /** The reason of the result, in one sentence. */
+  readonly reason: string;
+  /** The cases with the outcome `beyond`. */
+  readonly blocks: readonly string[];
+  /** The cases with the outcome `cannot decide`. */
+  readonly noRead: readonly string[];
+}
+/**
+ * This function gives the gate of a list of case outcomes.
+ * - The result is "block" when a case is `beyond`.
+ * - The result is "pass" when each case is `within`.
+ * - Each other result is "no read", and so is a list with no cases. A caller does not count "no read" as a pass.
+ */
+export declare function gateOf(cases: readonly GateCaseOutcome[]): Gate;
+/** The word of a case for the claim "not slower by more than the margin". The word "not slower" is apart from `same` of `timeVerdict`. */
+type NotSlowerRead = "not slower" | "slower" | "no read";
+/** The looks of `notSlowerVerdict`: the rounds in each job. The level of the family has an equal share at each look. */
+export declare const GATE_LOOKS: readonly number[];
+/** The options of `notSlowerVerdict`. */
+interface NotSlowerOptions {
+  /** The margin of each case on a log scale: a number, or a function of the name of the case. */
+  readonly margin: number | ((name: string) => number);
+  /** The chance of a false "not slower", and apart from it the chance of a false "slower", over the family and all looks. The default is 0.05. */
+  readonly level?: number;
+  /** The looks: even whole numbers in rising order. The default is `GATE_LOOKS`. */
+  readonly looks?: readonly number[];
+  /** The count of jobs that each need the bound. The default is 2, because more rounds do not remove a difference between jobs. */
+  readonly jobs?: number;
+}
+/** The read of one case in one job, at one look. */
+interface GateJobRead {
+  readonly job: string;
+  /** The pairs of rounds that the look uses. Below the rounds of the look, the job has not reached the look. */
+  readonly rounds: number;
+  /** The count of pairs with a difference below the margin. */
+  readonly below: number;
+  /** The count of pairs with a difference above the margin. */
+  readonly above: number;
+  /** The one-sided p of the sign test of the claim "the median difference is below the margin". */
+  readonly notSlower: number;
+  /** The one-sided p of the sign test of the claim "the median difference is above the margin". */
+  readonly slower: number;
+  /** The median of the differences, or undefined when the job has not reached the look. */
+  readonly centre: number | undefined;
+}
+/** The verdict of one case. */
+interface CaseGate extends GateCaseOutcome {
+  readonly read: NotSlowerRead;
+  readonly margin: number;
+  /** The rounds of the look that decides the case, or undefined when the case has no outcome. */
+  readonly look: number | undefined;
+  /** The reads of each job, at the look that decides the case, or else at the last look that a job reached. */
+  readonly jobs: readonly GateJobRead[];
+  /** The reason of the outcome, in one sentence. */
+  readonly reason: string;
+}
+/** The gate of the claim "not slower by more than the margin", with the facts that it uses. */
+interface NotSlowerVerdict extends Gate {
+  readonly level: number;
+  readonly looks: readonly number[];
+  /** The count of jobs that each need the bound. */
+  readonly need: number;
+  readonly cases: readonly CaseGate[];
+  /** The cases with no outcome that can have another look. The list is empty when the verdict is final. */
+  readonly more: readonly BudgetMore[];
+}
+/**
+ * This function gives the gate of the claim "the candidate is not slower than the A/A arm by more than the margin" for each
+ * case. A one-sided bound answers the claim. Thus a case with its whole interval under the margin reads "not slower", also
+ * when its interval holds 1.
+ *
+ * - In each job, the sign test compares the median of the differences with the margin. It uses no random numbers.
+ * - A case reads in `jobs` jobs or more: `partialConjunction` joins the p of each job, with no condition on how they depend.
+ * - The level is for the family. Each look has `level / looks` of it, and `holm` corrects each look over all cases.
+ * - The first look with an outcome decides a case. Later rounds do not change it. Each look uses the first rounds of a job.
+ * - The result is "block" when a case reads "slower", and "pass" when each case reads "not slower".
+ * - Each other result is "no read". The field `more` gives the next look of each case. After the last look, the caller adds jobs.
+ *
+ * The level needs independent rounds. Rounds with a shared cause, for example a slow computer for one job, do not have it.
+ * A job that a caller adds after the last look is one more look, and the level does not count it.
+ */
+export declare function notSlowerVerdict(jobs: readonly JobRecords[], options: NotSlowerOptions): NotSlowerVerdict;
+/** One time of the control in one group. */
+interface ControlRow {
+  /** The name of the group: a run, or a shard of one run. */
+  readonly group: string;
+  /** The name of a class of work. The same key in two groups names equal work, so a ratio of the two measures the load. */
+  readonly key: string;
+  /** The time. It is finite and more than 0. */
+  readonly value: number;
+  /** This field is true when the run stopped the case at `value`. Thus the real time is at least `value`. */
+  readonly censored?: boolean;
+}
+/** The options of `controlFactor`. */
+interface ControlOptions {
+  /** The group that the factors compare with. Without it, the base of each key is the median of that key over the groups. */
+  readonly base?: string;
+  /** The least number of keys in a factor. A group with fewer keys has no factor. The default is 5. */
+  readonly minPairs?: number;
+}
+/** The counts of one group, with or without a factor. */
+interface GroupCounts {
+  readonly group: string;
+  /** The number of keys that the factor reads. */
+  readonly pairs: number;
+  /** The number of keys that this function left out because a time of the key was censored. The factor reads low when this count is not 0. */
+  readonly censored: number;
+  /** The number of keys of this group that have no time to compare with, so no ratio reads them. */
+  readonly unshared: number;
+}
+/** The factor of one group. */
+interface MeasuredFactor extends GroupCounts {
+  /** The median ratio of the times of this group over the base. A factor of 1.6 means that this group took 1.6 times as long. */
+  readonly factor: number;
+  /** The quartiles of the ratios. A wide spread means that one factor does not explain the load. */
+  readonly low: number;
+  readonly high: number;
+}
+/** A group with too few usable keys. It has no factor, and the other groups keep theirs. */
+interface NoFactor extends GroupCounts {
+  readonly factor: undefined;
+  /** The reason that this group has no factor. */
+  readonly reason: string;
+}
+/** The result of one group. Read `factor` first: a group with too few usable keys has no factor. */
+type GroupFactor = MeasuredFactor | NoFactor;
+/** The factors of a run, with the base that they use. */
+interface ControlFactors {
+  /** The base group, or undefined when the base of each key is its median over the groups. */
+  readonly base: string | undefined;
+  readonly factors: readonly GroupFactor[];
+}
+/**
+ * This function gives the load factor of each group from the times of a control.
+ *
+ * With `base`, a factor compares the keys that a group shares with that group. Without it, a factor compares each time with the median of its key over the groups.
+ * A key names a class of work, so equal keys in two groups mean equal work. Each group has at most one row for a key.
+ *
+ * A censored time is only a lower limit, so no ratio reads it, and the result counts those keys. A run stops its slowest cases, so a factor reads low when `censored` is not 0.
+ *
+ * A group with too few usable keys gets an entry with no factor and its reason, so the other groups keep their factors. This function refuses a result where no group has a factor.
+ */
+export declare function controlFactor(rows: readonly ControlRow[], options?: ControlOptions): ControlFactors;
+/** The format name of a ladder. It changes when a reader of an older form cannot read the data. */
+export declare const LADDER_FORMAT = "rigor-ladder/1";
+/** One dimension of a ladder, for example tenants or nodes. */
+interface LadderDimension {
+  readonly name: string;
+  /** What one unit of the dimension is, in plain words. */
+  readonly describe: string;
+}
+/** A budget on the median of each case, for example the time of a read. A record gives rounds and an A/A arm. */
+interface MedianBudget {
+  readonly kind: "median";
+  readonly measure: string;
+  /** The unit of the limit and of the values. */
+  readonly unit: string;
+  /** The largest median that the budget permits. */
+  readonly limit: number;
+  /** The largest difference between the medians of the two arms. A larger difference makes the run too noisy. */
+  readonly maxDifference: number;
+  /** The level of the interval of each median. The default is 0.95. */
+  readonly caseLevel?: number;
+}
+/** A budget on the share of failed trials, for example failed requests. A record gives failures and trials. */
+interface RateBudget {
+  readonly kind: "rate";
+  readonly measure: string;
+  /** The largest share of failures that the budget permits, from 0 to 1. */
+  readonly limit: number;
+}
+/** A budget on the largest value of a set of drills, for example the writes that a restore lost. One bad drill is `beyond`. */
+interface WorstBudget {
+  readonly kind: "worst";
+  readonly measure: string;
+  readonly unit: string;
+  /** The largest value that the budget permits in any drill. */
+  readonly limit: number;
+  /** The number of drills that a verdict needs, 1 or more. With fewer, the budget is `cannot decide`. */
+  readonly minDrills: number;
+}
+/**
+ * A budget on a high quantile, for example the p99 of a read. A record gives the values. The verdict is the distribution-free
+ * interval of the quantile against the limit. A p99 needs 368 independent values at the level 0.95: refer to `quantileSamples`.
+ * Successive times of one run can follow each other. Space them apart, or give one value for each run.
+ *
+ * The evidence can also hold `censored`: a lower bound for each arrival with no reply, and for each arrival that was not
+ * sent. The bound is the time that the arrival waited. The true value is that bound or more, with no upper limit. Thus the
+ * low end of the interval reads the bounds, and the high end reads each censored value as `Infinity`. A `beyond` stays
+ * provable from the bounds alone. A `within` needs real replies up to the upper rank of the interval.
+ */
+interface QuantileBudget {
+  readonly kind: "quantile";
+  readonly measure: string;
+  /** The unit of the limit and of the values. */
+  readonly unit: string;
+  /** The quantile, more than 0 and less than 1, for example 0.99. */
+  readonly quantile: number;
+  /** The largest quantile that the budget permits. */
+  readonly limit: number;
+  /** The level of the interval. The default is 0.95. */
+  readonly level?: number;
+}
+/** One budget of a rung. */
+type RungBudget = MedianBudget | QuantileBudget | RateBudget | WorstBudget;
+/** One rung of a ladder. */
+interface Rung {
+  /** The name of the rung, unique in the ladder. */
+  readonly name: string;
+  /** The size of the rung in each dimension that it names. */
+  readonly at: Readonly<Record<string, number>>;
+  readonly budgets: readonly RungBudget[];
+  /** The name of the automatic test that holds the rung. */
+  readonly test: string;
+  /** True when a gate holds the rung: the verdict fails when the rung is not `within`. */
+  readonly locked?: boolean;
+}
+/** The ladder of one subject. The rungs go from the smallest to the largest. */
+interface Ladder {
+  readonly format: typeof LADDER_FORMAT;
+  /** The product or the service that the ladder is for. */
+  readonly subject: string;
+  readonly dimensions: readonly LadderDimension[];
+  readonly rungs: readonly Rung[];
+}
+/** The measured evidence for one budget. Its `kind` is the kind of the budget. */
+type RungEvidence = {
+  readonly kind: "median";
+  readonly measure: string;
+  readonly rounds: readonly BudgetRound[];
+  readonly aa: readonly BudgetRound[];
+} | {
+  readonly kind: "quantile";
+  readonly measure: string;
+  readonly values: readonly number[];
+  readonly censored?: readonly number[];
+} | {
+  readonly kind: "rate";
+  readonly measure: string;
+  readonly failures: number;
+  readonly trials: number;
+} | {
+  readonly kind: "worst";
+  readonly measure: string;
+  readonly values: readonly number[];
+};
+/** One run of the test of a rung. */
+interface RungRecord {
+  /** The name of the rung. */
+  readonly rung: string;
+  /** The commit that the run measured. */
+  readonly commit: string;
+  /** The time of the run, as an ISO 8601 string. */
+  readonly at: string;
+  /** What the run did for real, for example "2 processes" or "a restore from a real backup". */
+  readonly real: readonly string[];
+  /** What the run made up, for example "90 % of the tenants as data at rest". An empty list states that nothing was synthetic. */
+  readonly synthetic: readonly string[];
+  readonly evidence: readonly RungEvidence[];
+}
+/** The verdict of one budget of a rung. */
+interface BudgetResult {
+  readonly measure: string;
+  readonly outcome: BudgetOutcome;
+  /** The reason of the outcome, in one sentence, with the numbers. */
+  readonly reason: string;
+}
+/** The verdict of one rung. */
+interface RungVerdict {
+  readonly rung: string;
+  readonly test: string;
+  readonly locked: boolean;
+  readonly outcome: BudgetOutcome;
+  /** The reason of the outcome, in one sentence. */
+  readonly reason: string;
+  readonly budgets: readonly BudgetResult[];
+  /** The commit of the record, or undefined when the rung has no record. */
+  readonly commit: string | undefined;
+  readonly real: readonly string[];
+  readonly synthetic: readonly string[];
+}
+/** The verdict of a ladder. */
+interface LadderVerdict {
+  readonly subject: string;
+  /** The highest rung with each rung up to it `within`, or undefined when the first rung is not `within`. */
+  readonly held: string | undefined;
+  /** The first rung that is not `within`, or undefined when each rung is `within`. */
+  readonly next: string | undefined;
+  /** True when a locked rung is not `within`. A rung with no result is not held, so `cannot decide` fails too. */
+  readonly failed: boolean;
+  /** The reason of `failed`, in one sentence. */
+  readonly reason: string;
+  readonly rungs: readonly RungVerdict[];
+}
+/** The options of a ladder verdict. */
+interface LadderOptions {
+  /** The time of the verdict, as an ISO 8601 string. It is an input, so that a verdict is the same at each read. */
+  readonly now: string;
+  /** The largest age of a record, in days. An older record gives `cannot decide`. The default accepts any age. */
+  readonly maxAgeDays?: number;
+}
+/**
+ * This function gives each problem of a ladder as data, or an empty list. A ladder needs a subject, one dimension or more,
+ * and one rung or more. Names are unique. Each rung names a test and has budgets. From one rung to the next, each dimension
+ * that the two rungs name grows.
+ */
+export declare function checkLadder(ladder: Ladder): readonly string[];
+/** This function gives the verdict of one rung from its record. With no record, the rung is `cannot decide`. */
+export declare function rungVerdict(rung: Rung, record: RungRecord | undefined, options: LadderOptions): RungVerdict;
+/**
+ * This function gives the verdict of a ladder from the records of its rungs. It uses the newest record of each rung, so an
+ * older pass does not hide a newer failure. A rung high up does not count when a rung below it is not `within`. It throws
+ * a `RangeError` for a ladder with problems, because a verdict on a bad ladder has no meaning. See `checkLadder`.
+ */
+export declare function ladderVerdict(ladder: Ladder, records: readonly RungRecord[], options: LadderOptions): LadderVerdict;
+/** One value of one measure, for one entry and one input. */
+interface MeasureRow {
+  /** The name of the measure. */
+  readonly measure: string;
+  /** The name of the entry: a real strategy or a control. */
+  readonly group: string;
+  /** The name of the input. Equal keys in two groups name equal work, so the two values make a pair. */
+  readonly key: string;
+  /** The value. It is finite. No test reads the value of a censored row. */
+  readonly value: number;
+  /** This field is true when the entry did not finish this input, for example over its budget. */
+  readonly censored?: boolean;
+  /** The way that the value was made, for example a sample or a full count. Two ways in one measure do not compare. */
+  readonly method?: string;
+  /** The family of the input. A key has one stratum in all its rows. Rows without a stratum make one group. */
+  readonly stratum?: string;
+}
+/** A measure with no control yet: the reason and the date of the control. */
+interface NoControl {
+  /** The reason that the measure has no control at this time. */
+  readonly because: string;
+  /** The date of the control, as `YYYY-MM-DD`. A date before `asOf` gives the finding `control-late`. */
+  readonly until: string;
+}
+/** The rule of one measure. */
+interface MeasureRule {
+  readonly measure: string;
+  /** The direction of a better value. */
+  readonly sense: "higher" | "lower";
+  /** The controls made to win this measure. Each one is in `controls` of the options. */
+  readonly controls: readonly string[];
+  /** The measures that a control of this measure is to lose. Each one has its own rule. */
+  readonly partners: readonly string[];
+  /** The smallest median paired difference that counts. Without it, only the test decides, and the output says so. It has no default. */
+  readonly resolution?: number;
+  /** The reason and the date, for a rule with no controls. */
+  readonly noControl?: NoControl;
+}
+/** The options of `checkMeasures`. */
+interface MeasureCheckOptions {
+  readonly rules: readonly MeasureRule[];
+  /** Each group that is a control. Each other group is a real entry. */
+  readonly controls: readonly string[];
+  /** The date of the check, as `YYYY-MM-DD`. The caller gives it, so the function stays pure. */
+  readonly asOf: string;
+  /** The level of each family of tests. The default is 0.05. */
+  readonly alpha?: number;
+}
+/** One test: `better` beats `other` on the keys that the two finished. */
+interface Comparison {
+  readonly better: string;
+  readonly other: string;
+  readonly stratum: string | undefined;
+  /** The keys that both finished. */
+  readonly shared: number;
+  /** The shared keys with different values. The test reads only these. */
+  readonly n: number;
+  readonly ties: number;
+  /** The keys where `better` has the better value. */
+  readonly wins: number;
+  /** The keys where `other` has the better value. */
+  readonly losses: number;
+  /** The median paired difference over the shared keys, with ties. A positive value favours `better`. */
+  readonly medianDifference: number;
+  /** The p of the sign test. */
+  readonly p: number;
+  /** The p after the Holm correction. */
+  readonly adjusted: number;
+  /** The size of the Holm family. */
+  readonly family: number;
+  /** The least count of untied keys with the power to pass in this family. */
+  readonly needs: number;
+  /** This field is true when `n` is under `needs`. Such a test beats nothing. */
+  readonly tooFew: boolean;
+  /** This field is true when the shared keys reach `needs` and ties took them under it. So the two read as equal, not as unread. */
+  readonly tied: boolean;
+  /** The test passes, and the median difference is over the resolution when the measure has one. */
+  readonly beats: boolean;
+}
+/** The read of one control on one measure and one stratum. */
+interface ControlRead {
+  readonly measure: string;
+  readonly control: string;
+  readonly stratum: string | undefined;
+  /**
+   * The state of the read. `wins`: no real entry with enough pairs beats the control. `beaten`: a real entry beats it.
+   * `too-few`: no real entry has enough shared keys. `no-rows`: no real entry shares a finished key with it.
+   */
+  readonly status: "wins" | "beaten" | "too-few" | "no-rows";
+  /** The real entries with fewer winning keys than the control. It is a plain count with no test. */
+  readonly aheadOf: number;
+  /** One test for each real entry: `better` is the real entry, and `other` is the control. */
+  readonly comparisons: readonly Comparison[];
+  /** The real entries that the control beats by test on this stratum. */
+  readonly beatsEntries: number;
+  /** The tests of the control against the real entries that have power on this stratum. */
+  readonly of: number;
+  /** One test for each real entry: `better` is the control, and `other` is the real entry. This family is apart from `comparisons`. */
+  readonly against: readonly Comparison[];
+}
+/** The counts of one entry on one measure and one stratum. */
+interface EntryCount {
+  readonly group: string;
+  readonly stratum: string | undefined;
+  readonly finished: number;
+  readonly censored: number;
+}
+/** The read of the spread of one measure on one stratum, over the pairs of real entries. */
+interface SpreadRead {
+  readonly stratum: string | undefined;
+  /** The pairs of real entries that share a finished key. */
+  readonly pairs: number;
+  /** The pairs with a test that passes in one direction. */
+  readonly separated: number;
+  /** The pairs with too few shared keys for the test. A pair that ties on enough keys does not count here. */
+  readonly tooFew: number;
+  /** The largest absolute median paired difference of a pair. */
+  readonly widest: number | undefined;
+}
+/** The result of one control and one partner on one stratum. */
+interface PartnerRead {
+  readonly partner: string;
+  /**
+   * `lost`: a real entry beats the control at the level divided by the count of partners. Each partner is one more chance to clear the control.
+   * `not-lost`: no real entry does. `too-few`: no test has the power at that level. `no-rows`: nothing to read.
+   */
+  readonly status: "lost" | "not-lost" | "too-few" | "no-rows";
+}
+/** The result of one control on its measure and one stratum, with its partners. */
+interface GuardRead {
+  readonly control: string;
+  readonly stratum: string | undefined;
+  readonly status: ControlRead["status"];
+  readonly partners: readonly PartnerRead[];
+}
+/** The read of one measure. */
+interface MeasureCheck {
+  readonly measure: string;
+  readonly sense: "higher" | "lower";
+  /** `test only`: a measure with no resolution. `test and resolution`: a measure with one. */
+  readonly basis: "test only" | "test and resolution";
+  /** The only method of the rows. It is undefined when the rows give none. */
+  readonly method: string | undefined;
+  /** This field is true when the rows mix methods. The check then has no read of the measure. */
+  readonly mixed: boolean;
+  readonly guards: readonly GuardRead[];
+  readonly spread: readonly SpreadRead[];
+  readonly entries: readonly EntryCount[];
+  /** The partners that the rule names. */
+  readonly partners: readonly string[];
+  /** The reason and the date, for a measure with no control. */
+  readonly open: NoControl | undefined;
+}
+/** The kind of a finding. Each finding fails a gate. */
+type MeasureFindingKind = "uncaught" | "weak-control" | "censored-win" | "no-spread" | "too-few" | "mixed-method" | "no-rule" | "no-rows" | "no-control" | "control-late";
+/** One finding of the check, with the numbers behind it. */
+interface MeasureFinding {
+  readonly kind: MeasureFindingKind;
+  readonly measure: string;
+  readonly stratum?: string | undefined;
+  readonly control?: string;
+  /** The count of the partners of the rule, for a finding about the partners of a control. */
+  readonly partners?: number;
+  /** The finding in plain words, with its numbers. */
+  readonly text: string;
+  /** The tests behind the finding. */
+  readonly comparisons: readonly Comparison[];
+}
+/** The result of `checkMeasures`. */
+interface MeasureChecks {
+  /** The level of each family of tests. */
+  readonly alpha: number;
+  readonly measures: readonly MeasureCheck[];
+  /** Each read of a control, on its own measures and on their partners. */
+  readonly reads: readonly ControlRead[];
+  readonly findings: readonly MeasureFinding[];
+}
+/** What a page says about the win of one entry on one measure. */
+interface WinClaim {
+  /** This field is true only when a control was read on this measure and this entry beats each control on it. A win by another entry does not count. */
+  readonly alone: boolean;
+  /** The partners that a winning control loses. When this entry does not beat a control that does not win, or with no read of a control, all partners of the rule. */
+  readonly show: readonly string[];
+  /** This field is true when this entry does not beat a control on this measure and beats it on no partner. The win then reads the same as the trick. The status of the control does not change this. */
+  readonly likeControl: boolean;
+  /** The censored keys of this entry and of each control that it does not beat. A page shows them beside the win. */
+  readonly censored: {
+    readonly entry: number;
+    readonly controls: readonly {
+      readonly control: string;
+      readonly censored: number;
+    }[];
+  };
+  /** The reason and the date, for a measure with no control. */
+  readonly open: NoControl | undefined;
+}
+/**
+ * This function reads the controls and the spread of each measure of a bench.
+ *
+ * - A control wins a measure when no real entry beats it on the keys that both finished. A tie counts for the control.
+ * - A real entry beats a control when the Holm-corrected sign test passes and the median paired difference is over the resolution.
+ * - One Holm family holds the tests of one control on one measure over all real entries and all strata.
+ * - One more Holm family holds the tests of one control against the real entries, with the same need and resolution. A control that beats none of them is weak.
+ * - One Holm family holds the tests of the spread of one measure over all pairs of real entries and all strata.
+ * - A test with fewer untied keys than `signTestPower` needs for that family reads `tooFew` and beats nothing.
+ * - A test with enough shared keys and too few untied keys is `tied`. The two entries read as equal, so a constant measure is `no-spread` and not `too-few`.
+ * - A control loses a partner only at the level divided by the count of its partners. One passed partner clears `uncaught`, so each partner is one more chance.
+ *
+ * The function throws a `RangeError` for a value that is not finite, a repeat of measure, group and key, or a key in two strata.
+ * It also throws one for rules that contradict each other.
+ * The rules, the controls and the date are stated, so the result depends only on the arguments.
+ */
+export declare function checkMeasures(rows: readonly MeasureRow[], options: MeasureCheckOptions): MeasureChecks;
+/**
+ * This function tells what a page says about the win of one real entry on one measure.
+ * The claim is about this entry: only this entry beating the control, on this measure or on a partner, clears the entry. A win by another entry clears nothing.
+ * With a stratum, the function reads that stratum. Without one, it reads the rows with no stratum.
+ * The function throws a `RangeError` for a measure with no read and for an entry that the rows do not hold.
+ */
+export declare function winClaim(check: MeasureChecks, measure: string, entry: string, stratum?: string): WinClaim;
 /** The options of a power test. */
 interface PowerOptions {
   /** The count of the cases of the candidate and of the A/A arm. */
@@ -760,5 +1072,5 @@ interface Rounds {
  * keeps the work.
  */
 export declare function timeRounds(arms: Readonly<Record<Arm, () => number>>, options: RoundsOptions): Rounds;
-export { type Arm, type Balanced, type Band, type BandKind, type BandOptions, type BudgetLook, type BudgetLooksOptions, type BudgetLooksVerdict, type BudgetMore, type BudgetOptions, type BudgetOutcome, type BudgetResult, type BudgetRound, type BudgetVerdict, type CaseBudget, type CaseInterval, type CaseLimit, type CaseRatio, type ControlFactors, type ControlOptions, type ControlRow, type GroupCounts, type GroupFactor, type JobLimitVerdict, type JobRecords, type JobVerdict, type Ladder, type LadderDimension, type LadderOptions, type LadderVerdict, type LimitOptions, type LimitOutcome, type LimitVerdict, type MeasuredFactor, type MedianBudget, type NoFactor, type NoiseCheck, type PairedTime, type PoolFacts, type PoolOptions, type PooledJob, type PooledLimitVerdict, type PooledRecords, type PooledVerdict, type Power, type PowerOptions, type QuantileBudget, type RateBudget, type Rounds, type RoundsOptions, type RunPairs, type Rung, type RungBudget, type RungEvidence, type RungRecord, type RungVerdict, type TimeOutcome, type TimeVerdict, type VerdictOptions, type VerdictRule, type WorstBudget, caseRatios, checkPairedTime, firstArm };
+export { type Arm, type Balanced, type Band, type BandKind, type BandOptions, type BudgetLook, type BudgetLooksOptions, type BudgetLooksVerdict, type BudgetMore, type BudgetOptions, type BudgetOutcome, type BudgetResult, type BudgetRound, type BudgetVerdict, type CaseBudget, type CaseGate, type CaseInterval, type CaseLimit, type CaseRatio, type Comparison, type ControlFactors, type ControlOptions, type ControlRead, type ControlRow, type EntryCount, type Gate, type GateCaseOutcome, type GateJobRead, type GateOutcome, type GroupCounts, type GroupFactor, type GuardRead, type JobLimitVerdict, type JobRecords, type JobVerdict, type Ladder, type LadderDimension, type LadderOptions, type LadderVerdict, type LimitOptions, type LimitOutcome, type LimitVerdict, type MeasureCheck, type MeasureCheckOptions, type MeasureChecks, type MeasureFinding, type MeasureFindingKind, type MeasureRow, type MeasureRule, type MeasuredFactor, type MedianBudget, type NoControl, type NoFactor, type NoiseCheck, type NotSlowerOptions, type NotSlowerRead, type NotSlowerVerdict, type PairedTime, type PartnerRead, type PoolFacts, type PoolOptions, type PooledJob, type PooledLimitVerdict, type PooledRecords, type PooledVerdict, type Power, type PowerOptions, type QuantileBudget, type RateBudget, type Rounds, type RoundsOptions, type RunPairs, type Rung, type RungBudget, type RungEvidence, type RungRecord, type RungVerdict, type SpreadRead, type TimeOutcome, type TimeVerdict, type VerdictOptions, type VerdictRule, type WinClaim, type WorstBudget, caseRatios, checkPairedTime, firstArm };
 //# sourceMappingURL=index.d.ts.map