lib: clarify mean in node:bench docs

Signed-off-by: James M Snell <jasnell@gmail.com>
Assisted-by: Opencode
PR-URL: #65631
Reviewed-By: Filip Skokan <panva.ip@gmail.com>

Author: jasnell

doc/api/bench.md

@@ -81,6 +81,22 @@ Calling `context.done()` during a measured sample completes the benchmark after
 that sample. This allows a higher-level tool to treat `samples` as a maximum and
 implement a dynamic sampling policy.
 
+The number of operations can differ between samples. Summary statistics treat
+each sample's `rate` as one equally weighted observation. In particular,
+`summary.mean` is the arithmetic mean of the per-sample rates. It is not the
+pooled throughput calculated as:
+
+```text
+1_000_000_000 * sum(sample.operations) / sum(sample.duration_ns)
+```
+
+The two values can differ when sample durations vary because pooled throughput
+weights each per-sample rate by its duration. A higher-level tool that varies
+batch sizes should choose the aggregation that matches its analysis. It can
+calculate pooled throughput from the raw `samples`; operation counts should be
+summed as `bigint` values because their total can exceed
+`Number.MAX_SAFE_INTEGER` even though each count cannot.
+
 ## Reusable runners
 
 The module-level declaration functions use a shared runner and schedule it
@@ -621,7 +637,8 @@ A completed benchmark result contains:
 * `params` {Object} The canonical parameter metadata.
 * `samples` {Object\[]} The exact measured samples.
 * `summary` {Object}
-  * `mean` {number} The arithmetic mean of per-sample rates.
+  * `mean` {number} The equally weighted arithmetic mean of per-sample rates,
+    not pooled throughput across all operations and durations.
   * `median` {number} The median per-sample rate.
   * `min` {number} The minimum per-sample rate.
   * `max` {number} The maximum per-sample rate.

test/parallel/test-bench-context-control.js

@@ -59,10 +59,21 @@ const { createRunner } = require('node:bench');
       b.done();
     }));
 
+  const variableSamples = [
+    { __proto__: null, duration_ns: 1_000_000_000n, operations: 1 },
+    { __proto__: null, duration_ns: 100_000_000n, operations: 100 },
+  ];
+  const variableCompletion = runner.bench('variable batch', {
+    samples: variableSamples.length,
+  }, common.mustCall((b) => {
+    b.record(variableSamples[b.index]);
+  }, variableSamples.length));
+
   const records = await runner.run().toArray();
-  const [controlled, recorded] = await Promise.all([
+  const [controlled, recorded, variable] = await Promise.all([
     controlledCompletion,
     recordedCompletion,
+    variableCompletion,
   ]);
 
   assert.deepStrictEqual(invocations, [
@@ -80,8 +91,12 @@ const { createRunner } = require('node:bench');
   assert.strictEqual(recorded.samples.length, 1);
   assert.deepStrictEqual(recorded.samples[0].detail,
                          { source: 'worker', value: 1n });
+  assert.deepStrictEqual(variable.samples.map(({ rate }) => rate), [1, 1000]);
+  assert.strictEqual(variable.summary.mean, 500.5);
+  const pooledRate = 1_000_000_000 * 101 / 1_100_000_000;
+  assert.notStrictEqual(variable.summary.mean, pooledRate);
   assert.strictEqual(
-    records.filter(({ type }) => type === 'bench:sample').length, 3);
+    records.filter(({ type }) => type === 'bench:sample').length, 5);
   assert.throws(() => closedContext.start(), { code: 'ERR_INVALID_STATE' });
   assert.throws(() => closedContext.end(1), { code: 'ERR_INVALID_STATE' });
   assert.throws(() => closedContext.record({