@mark1russell7/rigor-bench 0.2.14 → 0.2.16

package/build/index.d.ts

@@ -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.
@@ -698,6 +465,432 @@ 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;
+/** The value at one rank of the ratios of one case, from the largest. */
+interface CaseTail {
+  readonly case: string;
+  /** The value at the rank, or undefined when the rounds do not put the rank above the median. */
+  readonly tail: number | undefined;
+  readonly rounds: number;
+}
+/** The two limits of one case. */
+interface TailLimit {
+  /** The largest median of the ratio `b / a` that the claim permits. */
+  readonly median: number;
+  /** The largest tail of the ratio `b / a` that the claim permits. */
+  readonly tail: number;
+}
+/** The options of `tailFalseFails`. */
+interface TailRuleOptions {
+  /** The limits of all the cases, or a function that gives the limits of one case. */
+  readonly limit: TailLimit | ((caseName: string) => TailLimit);
+  /** The rank of the tail, from the largest. The default 2 reads the second largest ratio, so one slow process cannot move it. */
+  readonly rank?: number;
+}
+/** The options of a tail limit verdict. */
+interface TailLimitOptions extends TailRuleOptions {
+  /**
+   * The largest tail of the A/A arm that lets a run decide. Each row under the tail of the A/A arm passes the tail limit, so
+   * a loud run has no power. This option has no default, because a run with no cap passes each row when it is loud.
+   */
+  readonly aaCap: number;
+  /** The smallest number of A/A cases with a tail. The default is 5. */
+  readonly minimum?: number;
+  /**
+   * The names of the cases that the run must have. A case of this list with no record reads `cannot decide`. Without this
+   * option, the verdict reads only the cases of the candidate, so a run that loses a case can read `within`.
+   */
+  readonly expected?: readonly string[];
+}
+/** The verdict of one case. */
+interface CaseTailLimit extends CaseTail {
+  /** The median ratio of the case: the value `ratio` of `caseRatios`. The value is undefined when the case has no record. */
+  readonly ratio: number | undefined;
+  readonly limit: TailLimit;
+  /** The median is over its limit. */
+  readonly overMedian: boolean;
+  /** The tail is over its limit and over the tail of the A/A arm of the run. */
+  readonly overTail: boolean;
+  readonly outcome: LimitOutcome;
+}
+/** A case that an A/A arm cannot read, with the reason. */
+interface TailGainCase {
+  readonly case: string;
+  /** The reason in one sentence. It names the limit under 1. */
+  readonly reason: string;
+}
+/** The result of `tailFalseFails`. */
+interface TailFalseFails {
+  /** The cases that the rule fails on the A/A arm. Print the count of this list on the gate. */
+  readonly fails: readonly string[];
+  /** The cases with a limit under 1. These cases are not in `fails`, because an A/A pair shows no gain. */
+  readonly gains: readonly TailGainCase[];
+}
+/** A tail limit verdict, with the facts that it uses. */
+interface TailLimitVerdict {
+  readonly outcome: LimitOutcome;
+  /** The reason of the outcome, in one sentence. */
+  readonly reason: string;
+  readonly cases: readonly CaseTailLimit[];
+  /** The largest tail over the cases of the A/A arm, or undefined when that arm has too few cases. */
+  readonly aaTail: number | undefined;
+  readonly aaCap: number;
+  readonly rank: number;
+}
+/**
+ * This function gives the value at one rank of the ratios of each case, from the largest, in the order of `caseRatios`. It
+ * examines the records as `caseRatios` does. A case needs `2 * rank + 1` rounds, so that the value is above the median.
+ */
+export declare function caseTails(records: readonly PairedTime[], rank?: number): CaseTail[];
+/**
+ * This function gives the verdict of the claim "the median and the tail of each case are at most their limits".
+ * - A case is `beyond` when its median is over its limit. It is also `beyond` when its tail is over its limit and over the
+ *   largest tail of the A/A arm of the run.
+ * - A case with too few rounds for the rank is `cannot decide`, unless its median is over its limit.
+ * - A case of `expected` with no record is `cannot decide`.
+ * - The verdict is `beyond` when a case is `beyond`, and `within` when each case is `within`.
+ * - Each case and the verdict are `cannot decide` when the largest tail of the A/A arm is over `aaCap`. The same applies
+ *   when the A/A arm has fewer than `minimum` cases with a tail. This is not a pass, so the caller takes another read.
+ *
+ * With the default rank, a real cost in 1 round cannot fail the tail limit, because 1 round cannot be told from noise. A
+ * cost in 2 rounds or more can fail it. The verdict has no interval, so a limit needs a margin from the spread of earlier
+ * runs.
+ */
+export declare function tailLimitVerdict(candidate: readonly PairedTime[], aa: readonly PairedTime[], options: TailLimitOptions): TailLimitVerdict;
+/**
+ * This function applies the rule of `tailLimitVerdict` to each case of the A/A arm, and gives the cases that fail. Each
+ * case reads the tail of the other cases, because a case cannot be the noise of itself. An arm with one case gives no
+ * failed case.
+ *
+ * A limit under 1 states a gain, and an A/A pair shows no gain. So the A/A arm has no read of that case, and the case goes
+ * in `gains` with that reason. The tail of that case stays in the noise of the other cases. The false fails of a gain limit
+ * come from repeat reads of an unchanged tree against its fixed base.
+ */
+export declare function tailFalseFails(aa: readonly PairedTime[], options: TailRuleOptions): TailFalseFails;
 /** One value of one measure, for one entry and one input. */
 interface MeasureRow {
   /** The name of the measure. */
@@ -980,5 +1173,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 Comparison, type ControlFactors, type ControlOptions, type ControlRead, type ControlRow, type EntryCount, 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 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 };
+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 CaseTail, type CaseTailLimit, 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 TailFalseFails, type TailGainCase, type TailLimit, type TailLimitOptions, type TailLimitVerdict, type TailRuleOptions, type TimeOutcome, type TimeVerdict, type VerdictOptions, type VerdictRule, type WinClaim, type WorstBudget, caseRatios, checkPairedTime, firstArm };
 //# sourceMappingURL=index.d.ts.map