Commit b9d7a50

* `halfLife` {number} The EWMA half-life in number of samples. When set to

a value greater than 0, the histogram tracks an exponentially weighted

moving average and standard deviation, accessible via

`histogram.ewmaMean` and `histogram.ewmaStddev`. After `halfLife`

recordings, a value's influence has decayed to 50%. **Default:** `0`

(disabled).

* `threshold` {number} An SLO threshold value. When set together with

`halfLife`, the histogram tracks a smoothed error rate for values

exceeding this threshold, accessible via `histogram.ewmaErrorRate` and

`histogram.burnRate()`. **Default:** `0` (disabled).

### `histogram.cliffsD(other)`

<!-- YAML

added: REPLACEME

-->

* `other` {Histogram} The histogram to compare against.

* Returns: {number} A value between -1.0 and 1.0.

Computes [Cliff's delta][], a non-parametric effect size measure. Returns

the probability that a random value from this histogram exceeds a random

value from `other`, minus the reverse probability. A value of 1 means every

value in this histogram exceeds every value in `other`; -1 means the

opposite; 0 means no tendency in either direction.

### `histogram.cohensD(other)`

<!-- YAML

added: REPLACEME

-->

* `other` {Histogram} The histogram to compare against.

* Returns: {number} The effect size.

Computes [Cohen's d][] effect size, the standardized difference between the

means of this histogram and `other`, using the pooled standard deviation.

Positive values indicate this histogram has a higher mean. By convention,

|d| < 0.2 is a small effect, 0.5 is medium, and 0.8 or greater is large.

Both histograms must have at least 2 recorded values; otherwise returns 0.

### `histogram.ewmaMean`

<!-- YAML

added: REPLACEME

-->

* Type: {number}

The exponentially weighted moving average of recorded values. Only active

when the histogram was created with a `halfLife` option greater than 0.

Returns `0` when EWMA is disabled or no values have been recorded.

### `histogram.ewmaStddev`

<!-- YAML

added: REPLACEME

-->

* Type: {number}

The exponentially weighted moving standard deviation. Only active when the

histogram was created with a `halfLife` option greater than 0. Returns `0`

when EWMA is disabled or no values have been recorded.

### `histogram.ewmaErrorRate`

<!-- YAML

added: REPLACEME

-->

* Type: {number}

The EWMA-smoothed probability of a recorded value exceeding the configured

`threshold`. Only active when the histogram was created with both `halfLife`

and `threshold` options. Returns `0` when not enabled or no values have been

recorded.

### `histogram.burnRate(sloTarget)`

<!-- YAML

added: REPLACEME

-->

* `sloTarget` {number} The SLO target as a fraction between 0 and 1

(exclusive). For example, `0.999` for a 99.9% SLO.

* Returns: {number}

Returns the SLO burn rate: `ewmaErrorRate / (1 - sloTarget)`. A burn rate

of 1 means the error budget will be exactly exhausted over the SLO window.

A burn rate greater than 1 means it is being consumed faster than allowed.

Requires the histogram to have been created with both `halfLife` and

`threshold` options.

```js

const { createHistogram } = require('node:perf_hooks');

// Track latency with a 200ms SLO threshold, half-life of 100 samples

const h = createHistogram({ halfLife: 100, threshold: 200_000_000 });

// ... record latency values ...

// Check burn rate against a 99.9% SLO

const rate = h.burnRate(0.999);

if (rate > 1) {

console.log(`SLO burn rate: ${rate.toFixed(2)}x — error budget depleting`);

}

```

### `histogram.mannWhitneyTest(other)`

<!-- YAML

added: REPLACEME

-->

* `other` {Histogram} The histogram to compare against.

* Returns: {Object}

* `uStatistic` {number} The Mann-Whitney U statistic.

* `zScore` {number} The z-score (normal approximation).

* `pValue` {number} Two-tailed p-value.

Performs a [Mann-Whitney U test][] comparing whether this histogram tends to

produce larger or smaller values than `other`. Unlike `welchTest()`, this is a

non-parametric test that makes no assumptions about the shape of the

distributions. Uses the normal approximation with tie correction for the

p-value.

### `histogram.percentileCI(percentile[, options])`

<!-- YAML

added: REPLACEME

-->

* `percentile` {number} A percentile value in the range (0, 100].

* `options` {Object}

* `confidence` {number} The confidence level for the interval, between

0 and 1 (exclusive). **Default:** `0.95`.

* Returns: {Object}

* `value` {number} The point estimate (same as `histogram.percentile()`).

* `lower` {number} The lower bound of the confidence interval.

* `upper` {number} The upper bound of the confidence interval.

Returns a confidence interval for the given percentile using the exact

binomial method. With fewer samples, the interval will be wider, reflecting

the greater uncertainty in the percentile estimate. Requires at least 2

recorded values; with fewer than 2, `lower` and `upper` will equal `value`.

```js

const { createHistogram } = require('node:perf_hooks');

const h = createHistogram();

for (let i = 0; i < 1000; i++) {

h.record(Math.floor(Math.random() * 100));

}

const ci = h.percentileCI(99);

console.log(ci.value); // The p99 point estimate

console.log(ci.lower); // The lower bound (95% confidence)

console.log(ci.upper); // The upper bound (95% confidence)

```

### `histogram.welchTest(other[, options])`

<!-- YAML

added: REPLACEME

-->

* `other` {Histogram} The histogram to compare against.

* `options` {Object}

* `confidence` {number} Confidence level for the interval, between 0 and 1.

**Default:** `0.95`.

* Returns: {Object}

* `tStatistic` {number} The Welch t-statistic.

* `degreesOfFreedom` {number} Welch-Satterthwaite degrees of freedom.

* `pValue` {number} Two-tailed p-value.

* `confidenceInterval` {Object}

* `lower` {number} Lower bound of the confidence interval on the

difference of means.

* `upper` {number} Upper bound.

Performs [Welch's t-test][] comparing the means of this histogram and `other`.

The p-value indicates the probability of observing a difference at least this

extreme under the null hypothesis that the two distributions have the same

mean. Both histograms must have at least 2 recorded values; otherwise the

result has `pValue` 1 and `tStatistic` 0.

### SLO burn rate monitoring

```js

const { createHistogram } = require('node:perf_hooks');

// Track latency with EWMA (half-life 100 samples) and a 200ms SLO threshold

const latency = createHistogram({

halfLife: 100,

threshold: 200_000_000, // 200ms in nanoseconds

});

// Record request latencies...

// Smoothed error rate: probability of exceeding the threshold

console.log(`Error rate: ${(latency.ewmaErrorRate * 100).toFixed(2)}%`);

// Burn rate against a 99.9% SLO

// >1 means the error budget is depleting faster than allowed

const rate = latency.burnRate(0.999);

console.log(`Burn rate: ${rate.toFixed(2)}x`);

// EWMA mean and stddev track the smoothed latency

console.log(`EWMA latency: ${latency.ewmaMean.toFixed(0)}ns`);

console.log(`EWMA stddev: ${latency.ewmaStddev.toFixed(0)}ns`);

```

### Benchmark comparison with Welch's t-test

```js

const { createHistogram } = require('node:perf_hooks');

const baseline = createHistogram();

const candidate = createHistogram();

// Record operation rates from the old and new builds...

const result = baseline.welchTest(candidate);

const improvement = ((candidate.mean - baseline.mean) / baseline.mean * 100);

console.log(`Improvement: ${improvement.toFixed(2)}%`);

console.log(`p-value: ${result.pValue.toFixed(6)}`);

console.log(`95% CI: [${result.confidenceInterval.lower.toFixed(2)}, ` +

`${result.confidenceInterval.upper.toFixed(2)}]`);

if (result.pValue < 0.05) {

const d = baseline.cohensD(candidate);

console.log(`Statistically significant (Cohen's d = ${d.toFixed(4)})`);

}

```

### Effect size with Cliff's delta

```js

const { createHistogram } = require('node:perf_hooks');

const before = createHistogram();

const after = createHistogram();

// Record latencies before and after a change...

const delta = before.cliffsD(after);

// A delta > 0: before tends to produce larger values (improvement)

// A delta < 0: after tends to produce larger values (regression)

console.log(`Cliff's delta: ${delta.toFixed(4)}`);

```

[Cliff's delta]: https://en.wikipedia.org/wiki/Effect_size#Cliff's_delta

[Cohen's d]: https://en.wikipedia.org/wiki/Effect_size#Cohen's_d

[Mann-Whitney U test]: https://en.wikipedia.org/wiki/Mann%E2%80%93Whitney_U_test

[Welch's t-test]: https://en.wikipedia.org/wiki/Welch%27s_t-test