Histogram Quantiles With Real Error Bounds

Computes a quantile from histogram buckets and returns the interpolation's actual uncertainty instead of a false point value.

THE SILENT FAILURE. 'p99 latency is 250ms' is almost always wrong, and wrong in a direction nobody checks. Histogram quantiles are INTERPOLATED between bucket boundaries, so if the p99 falls in a bucket spanning 250 to 500ms the reported value is an assumption, not a measurement. If it falls in the overflow bucket the true value is unbounded above, and the dashboard prints a specific number anyway.

Worse, AVERAGING PERCENTILES ACROSS INSTANCES IS MEANINGLESS. The mean of three p99s is not the p99, yet almost every multi-instance dashboard computes exactly that, and the result is confidently wrong and always too low. Nothing errors. The graph is smooth. The SLO looks met.

It returns the estimate WITH the bucket's lower and upper bound, so the caller sees the real uncertainty. When the quantile lands in the overflow bucket it REFUSES to interpolate and says the value is unbounded above -- inventing a number there is the bug. Merging histograms is the correct way to aggregate, so it is provided and made the obvious path, and averaging precomputed quantiles is a function that refuses and explains why. A cumulative histogram whose counts are not monotonic is corrupt input, not data to interpolate, and is refused. Every quantile reports the sample count behind it, because a p99 from twelve observations is noise wearing a precise-looking number.

A REAL BUG FOUND BEFORE RELEASE: a single bucket open at BOTH ends is simultaneously the first and last bucket, so it satisfied both open-edge exceptions and produced 'p99: unbounded (> -Infinityms)'. Now refused.

VERIFIED: 72 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function averagePrecomputedQuantiles(_precomputedQuantileValues: number[]): never;
  export function formatQuantile(result: QuantileResult, options: FormatQuantileOptions = {}): string;
  export function mergeHistograms(histograms: Histogram[]): Histogram;
  export function computeQuantile(histogram: Histogram, quantile: number): QuantileResult;
  export function assertValidQuantile(quantile: number): void;
  export function validateCumulativeHistogram(histogram: CumulativeHistogram): void;
  export function validateNonCumulativeHistogram(histogram: NonCumulativeHistogram): void;
  export function validateHistogram(histogram: Histogram): void;

  export type Histogram = CumulativeHistogram | NonCumulativeHistogram;
  export type QuantileResult = BoundedQuantileEstimate | UnboundedQuantileEstimate;