@ac-bench/measure-duration 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,34 @@
+# @ac-bench/measure-duration
+
+How long an operation takes — measured properly, which means enough samples to
+say something, and a warning when the number should not be trusted.
+
+A single timing is noise. This samples adaptively until the distribution
+stabilises, then reports the statistics alongside quality warnings: outliers, a
+slow first run (JIT warm-up), high variance, harness overhead dominating the
+measurement, or simply too few samples.
+
+```ts
+import { durationCase, durationCondition } from "@ac-bench/measure-duration";
+
+durationCondition("array sum", () => {
+  durationCase("for loop", () => {
+    let total = 0;
+    for (const value of values) total += value;
+  });
+
+  durationCase("reduce", () => {
+    values.reduce((total, value) => total + value, 0);
+  });
+});
+```
+
+A _condition_ groups cases that are alternatives to each other; a _case_ is one
+implementation. Build the inputs outside the timed closure — anything inside it
+is measured too.
+
+Also exposes `measureSpawnOverhead` and `calibrateSpawnOverhead` for cases that
+spawn a subprocess per iteration, and re-exports the `beforeAll`/`afterAll`
+hooks from `@ac-bench/core`.
+
+Run suites with the `measure` CLI from `@ac-bench/cli`.

package/dist/_harness-overhead.d.ts

@@ -0,0 +1,36 @@
+import * as z from "zod/mini";
+import { DurationStatistics } from "./_types.js";
+/**
+ * The shape of a case body, which decides what its harness costs.
+ *
+ * `fn.constructor.name === "AsyncFunction"` alone is not a reliable signal — it
+ * misses a plain function returning a promise, which is the common shape for a
+ * case that delegates. What the body actually returned is.
+ */
+export declare const harnessShapeSchema: z.ZodMiniEnum<{
+    "async-function": "async-function";
+    sync: "sync";
+    thenable: "thenable";
+}>;
+export type HarnessShape = z.infer<typeof harnessShapeSchema>;
+export declare const harnessOverheadSchema: z.ZodMiniObject<{
+    shape: z.ZodMiniEnum<{
+        "async-function": "async-function";
+        sync: "sync";
+        thenable: "thenable";
+    }>;
+    medianMs: z.ZodMiniNumber<number>;
+    share: z.ZodMiniNumber<number>;
+    subtracted: z.ZodMiniBoolean<boolean>;
+}, z.core.$strip>;
+export type HarnessOverhead = z.infer<typeof harnessOverheadSchema>;
+/** Fraction of a case's runtime above which its harness dominates the number. */
+export declare const HARNESS_OVERHEAD_DOMINATES = 0.25;
+export declare function detectHarnessShape(runFn: (signal: AbortSignal) => unknown, returned: unknown): HarnessShape;
+/**
+ * Measures a no-op body of `shape` through the identical timed span the real
+ * case is measured through, so what is calibrated is the harness and not the
+ * benchmark.
+ */
+export declare function calibrateHarnessOverhead(shape: HarnessShape, outlierThreshold: number, signal: AbortSignal): Promise<DurationStatistics>;
+//# sourceMappingURL=_harness-overhead.d.ts.map

package/dist/_harness-overhead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_harness-overhead.d.ts","sourceRoot":"","sources":["../src/_harness-overhead.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAG9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;EAI7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,qBAAqB;;;;;;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAK/C,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,EACvC,QAAQ,EAAE,OAAO,GACf,YAAY,CAQd;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,YAAY,EACnB,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,kBAAkB,CAAC,CAa7B"}

package/dist/_harness-overhead.js

@@ -0,0 +1,62 @@
+import { isThenable } from "@ac-kit/core";
+import * as z from "zod/mini";
+import { summarise } from "./_statistics.js";
+/**
+ * The shape of a case body, which decides what its harness costs.
+ *
+ * `fn.constructor.name === "AsyncFunction"` alone is not a reliable signal — it
+ * misses a plain function returning a promise, which is the common shape for a
+ * case that delegates. What the body actually returned is.
+ */
+export const harnessShapeSchema = z.enum([
+    "sync",
+    "async-function",
+    "thenable",
+]);
+export const harnessOverheadSchema = z.object({
+    shape: harnessShapeSchema,
+    medianMs: z.number(),
+    /** Overhead median as a fraction of the case median. */
+    share: z.number(),
+    /** Whether it was removed from the reported samples, or only reported. */
+    subtracted: z.boolean(),
+});
+/** Fraction of a case's runtime above which its harness dominates the number. */
+export const HARNESS_OVERHEAD_DOMINATES = 0.25;
+/** Enough to take a median of something this cheap, and no more. */
+const CALIBRATION_SAMPLES_ = 50;
+export function detectHarnessShape(runFn, returned) {
+    if (!isThenable(returned)) {
+        return "sync";
+    }
+    return runFn.constructor.name === "AsyncFunction"
+        ? "async-function"
+        : "thenable";
+}
+/**
+ * Measures a no-op body of `shape` through the identical timed span the real
+ * case is measured through, so what is calibrated is the harness and not the
+ * benchmark.
+ */
+export async function calibrateHarnessOverhead(shape, outlierThreshold, signal) {
+    const noop = createNoop_(shape);
+    const spans = [];
+    for (let iteration = 0; iteration < CALIBRATION_SAMPLES_; iteration++) {
+        signal.throwIfAborted();
+        const begin = performance.now();
+        await noop();
+        spans.push(performance.now() - begin);
+    }
+    return summarise(spans, outlierThreshold);
+}
+function createNoop_(shape) {
+    switch (shape) {
+        case "sync":
+            return () => undefined;
+        case "async-function":
+            return async () => undefined;
+        case "thenable":
+            return () => Promise.resolve();
+    }
+}
+//# sourceMappingURL=_harness-overhead.js.map

package/dist/_harness-overhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_harness-overhead.js","sourceRoot":"","sources":["../src/_harness-overhead.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC;IACxC,MAAM;IACN,gBAAgB;IAChB,UAAU;CACV,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,kBAAkB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,wDAAwD;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,0EAA0E;IAC1E,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC;AAGH,iFAAiF;AACjF,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C,oEAAoE;AACpE,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC,MAAM,UAAU,kBAAkB,CACjC,KAAuC,EACvC,QAAiB;IAEjB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,eAAe;QAChD,CAAC,CAAC,gBAAgB;QAClB,CAAC,CAAC,UAAU,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC7C,KAAmB,EACnB,gBAAwB,EACxB,MAAmB;IAEnB,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,oBAAoB,EAAE,SAAS,EAAE,EAAE,CAAC;QACvE,MAAM,CAAC,cAAc,EAAE,CAAC;QAExB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,IAAI,EAAE,CAAC;QACb,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,SAAS,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAAC,KAAmB;IACvC,QAAQ,KAAK,EAAE,CAAC;QACf,KAAK,MAAM;YACV,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QAExB,KAAK,gBAAgB;YACpB,OAAO,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;QAE9B,KAAK,UAAU;YACd,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;AACF,CAAC"}

package/dist/_iteration-protocol.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod/mini";
+/**
+ * Measure option set on the one-shot invocation inside a spawned iteration.
+ *
+ * Same registration, same case body, different job: the spawned process must
+ * run the body exactly once instead of entering the sampler, or every iteration
+ * would recursively spawn a whole sampling run of its own.
+ */
+export declare const SINGLE_ITERATION_OPTION = "singleIteration";
+/** Sole argument of {@link iteration-child}, as one JSON argv string. */
+export declare const iterationPayloadSchema: z.ZodMiniObject<{
+    file: z.ZodMiniString<string>;
+    conditionPath: z.ZodMiniArray<z.ZodMiniNumber<number>>;
+    conditionTitles: z.ZodMiniArray<z.ZodMiniString<string>>;
+    caseTitle: z.ZodMiniString<string>;
+}, z.core.$strip>;
+export type IterationPayload = z.infer<typeof iterationPayloadSchema>;
+//# sourceMappingURL=_iteration-protocol.d.ts.map

package/dist/_iteration-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_iteration-protocol.d.ts","sourceRoot":"","sources":["../src/_iteration-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AAEzD,yEAAyE;AACzE,eAAO,MAAM,sBAAsB;;;;;iBAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/_iteration-protocol.js

@@ -0,0 +1,17 @@
+import * as z from "zod/mini";
+/**
+ * Measure option set on the one-shot invocation inside a spawned iteration.
+ *
+ * Same registration, same case body, different job: the spawned process must
+ * run the body exactly once instead of entering the sampler, or every iteration
+ * would recursively spawn a whole sampling run of its own.
+ */
+export const SINGLE_ITERATION_OPTION = "singleIteration";
+/** Sole argument of {@link iteration-child}, as one JSON argv string. */
+export const iterationPayloadSchema = z.object({
+    file: z.string(),
+    conditionPath: z.array(z.number()),
+    conditionTitles: z.array(z.string()),
+    caseTitle: z.string(),
+});
+//# sourceMappingURL=_iteration-protocol.js.map

package/dist/_iteration-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_iteration-protocol.js","sourceRoot":"","sources":["../src/_iteration-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iBAAiB,CAAC;AAEzD,yEAAyE;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACpC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC"}

package/dist/_iteration-source.d.ts

@@ -0,0 +1,64 @@
+import { BenchCaseId } from "@ac-bench/core/runner";
+import { ColdStartPhases, ProcessGroup } from "./_process-execution.js";
+import { SpawnBaselineReport } from "./_spawn-baseline.js";
+import { DurationStatistics } from "./_statistics-schema.js";
+import { DurationCommandCaseOptions } from "./options.js";
+/** Command a case executes once per iteration, with its do-nothing counterpart. */
+export type IterationCommand = {
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Invocation that starts the same program and does nothing, when known. */
+    readonly baselineArgs: readonly string[] | null;
+    readonly capturePhases: boolean;
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+};
+/**
+ * Resolves what to execute for `execution: "per-iteration-process"`.
+ *
+ * The spawned process re-imports the bench file and replays the case identity,
+ * so it must be started by the same interpreter with the same loader flags — a
+ * bench file that only a TypeScript loader can import is the normal case, not
+ * the exception.
+ */
+export declare function iterationProcessCommand(caseId: BenchCaseId): IterationCommand;
+/** Resolves what to execute for a `durationCommandCase`. */
+export declare function commandCaseCommand(command: string, args: readonly string[], options: DurationCommandCaseOptions | undefined): IterationCommand;
+/**
+ * Runs one iteration and returns its wall time.
+ *
+ * @throws {Error} If the process failed, with its stderr tail attached — an
+ *   exit code on its own is undiagnosable, and a failing program is the most
+ *   likely thing to go wrong in this execution mode.
+ */
+export declare function measureIteration(group: ProcessGroup, command: IterationCommand, phases: ColdStartPhases[], signal: AbortSignal): Promise<number>;
+/**
+ * Measures what starting the program costs when it is asked to do nothing.
+ *
+ * Measured once per case rather than once per condition: a condition's cases
+ * routinely spawn different programs, or none at all, and one program's
+ * start-up cost is not another's.
+ *
+ * @param group Owns the spawned processes, so none outlives the case.
+ * @param command What the case executes, including its do-nothing arguments.
+ * @param counts Warm-up and measured invocation counts.
+ * @param signal Cancellation.
+ * @returns Statistics over the measured invocations, or `null` when the case
+ *   declared no do-nothing invocation.
+ */
+export declare function measureSpawnBaseline(group: ProcessGroup, command: IterationCommand, counts: {
+    readonly warmup: number;
+    readonly runs: number;
+}, signal: AbortSignal): Promise<DurationStatistics | null>;
+/**
+ * Assembles the reported baseline block.
+ *
+ * @param command What the case executes.
+ * @param statistics Baseline statistics, or `null` when none was measured.
+ * @param caseMedianMs The case's own median, for the share.
+ * @param subtracted Whether the baseline fed the `adjusted` figure.
+ */
+export declare function spawnBaselineReport(command: IterationCommand, statistics: DurationStatistics | null, caseMedianMs: number, subtracted: boolean): SpawnBaselineReport | null;
+/** Median of each phase, so one cold start's noise does not stand for all. */
+export declare function summariseColdStart(phases: readonly ColdStartPhases[]): ColdStartPhases | null;
+//# sourceMappingURL=_iteration-source.d.ts.map

package/dist/_iteration-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_iteration-source.d.ts","sourceRoot":"","sources":["../src/_iteration-source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EACN,eAAe,EAEf,YAAY,EACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAChD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAkB7E;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,0BAA0B,GAAG,SAAS,GAC7C,gBAAgB,CASlB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,EAAE,EACzB,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CACzC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC1D,MAAM,EAAE,WAAW,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAyBpC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,kBAAkB,GAAG,IAAI,EACrC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,OAAO,GACjB,mBAAmB,GAAG,IAAI,CAW5B;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,SAAS,eAAe,EAAE,GAChC,eAAe,GAAG,IAAI,CAUxB"}

package/dist/_iteration-source.js

@@ -0,0 +1,135 @@
+import { fileURLToPath } from "node:url";
+import { iterationPayloadSchema } from "./_iteration-protocol.js";
+import { summarise } from "./_statistics.js";
+/**
+ * Resolves what to execute for `execution: "per-iteration-process"`.
+ *
+ * The spawned process re-imports the bench file and replays the case identity,
+ * so it must be started by the same interpreter with the same loader flags — a
+ * bench file that only a TypeScript loader can import is the normal case, not
+ * the exception.
+ */
+export function iterationProcessCommand(caseId) {
+    const payload = JSON.stringify(iterationPayloadSchema.parse({
+        file: caseId.file,
+        conditionPath: [...caseId.conditionPath],
+        conditionTitles: [...caseId.conditionTitles],
+        caseTitle: caseId.caseTitle,
+    }));
+    return {
+        command: process.execPath,
+        args: [...process.execArgv, iterationChildPath_(), payload],
+        // Same interpreter and same loader, without the bench file: everything
+        // this execution mode exists to measure, and nothing else.
+        baselineArgs: [...process.execArgv, "-e", ""],
+        capturePhases: true,
+    };
+}
+/** Resolves what to execute for a `durationCommandCase`. */
+export function commandCaseCommand(command, args, options) {
+    return {
+        command,
+        args,
+        baselineArgs: options?.baselineArgs ? [...options.baselineArgs] : null,
+        capturePhases: false,
+        ...(options?.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(options?.env === undefined ? {} : { env: options.env }),
+    };
+}
+/**
+ * Runs one iteration and returns its wall time.
+ *
+ * @throws {Error} If the process failed, with its stderr tail attached — an
+ *   exit code on its own is undiagnosable, and a failing program is the most
+ *   likely thing to go wrong in this execution mode.
+ */
+export async function measureIteration(group, command, phases, signal) {
+    const outcome = await group.run(command.command, command.args, {
+        capturePhases: command.capturePhases,
+        ...(command.cwd === undefined ? {} : { cwd: command.cwd }),
+        ...(command.env === undefined ? {} : { env: command.env }),
+    }, signal);
+    if (outcome.exitCode !== 0) {
+        throw new Error(describeFailure_(command, outcome));
+    }
+    if (outcome.phases !== null) {
+        phases.push(outcome.phases);
+    }
+    return outcome.wallMs;
+}
+/**
+ * Measures what starting the program costs when it is asked to do nothing.
+ *
+ * Measured once per case rather than once per condition: a condition's cases
+ * routinely spawn different programs, or none at all, and one program's
+ * start-up cost is not another's.
+ *
+ * @param group Owns the spawned processes, so none outlives the case.
+ * @param command What the case executes, including its do-nothing arguments.
+ * @param counts Warm-up and measured invocation counts.
+ * @param signal Cancellation.
+ * @returns Statistics over the measured invocations, or `null` when the case
+ *   declared no do-nothing invocation.
+ */
+export async function measureSpawnBaseline(group, command, counts, signal) {
+    if (command.baselineArgs === null) {
+        return null;
+    }
+    const baseline = {
+        ...command,
+        args: command.baselineArgs,
+        baselineArgs: null,
+        capturePhases: false,
+    };
+    const discard = [];
+    for (let iteration = 0; iteration < counts.warmup; iteration++) {
+        await measureIteration(group, baseline, discard, signal);
+    }
+    const samples = [];
+    for (let iteration = 0; iteration < counts.runs; iteration++) {
+        samples.push(await measureIteration(group, baseline, discard, signal));
+    }
+    return summarise(samples);
+}
+/**
+ * Assembles the reported baseline block.
+ *
+ * @param command What the case executes.
+ * @param statistics Baseline statistics, or `null` when none was measured.
+ * @param caseMedianMs The case's own median, for the share.
+ * @param subtracted Whether the baseline fed the `adjusted` figure.
+ */
+export function spawnBaselineReport(command, statistics, caseMedianMs, subtracted) {
+    if (statistics === null) {
+        return null;
+    }
+    return {
+        command: [command.command, ...(command.baselineArgs ?? [])].join(" "),
+        statistics,
+        share: caseMedianMs > 0 ? statistics.medianMs / caseMedianMs : 1,
+        subtracted,
+    };
+}
+/** Median of each phase, so one cold start's noise does not stand for all. */
+export function summariseColdStart(phases) {
+    if (phases.length === 0) {
+        return null;
+    }
+    return {
+        startupMs: summarise(phases.map((phase) => phase.startupMs)).medianMs,
+        importMs: summarise(phases.map((phase) => phase.importMs)).medianMs,
+        runMs: summarise(phases.map((phase) => phase.runMs)).medianMs,
+    };
+}
+function describeFailure_(command, outcome) {
+    const how = outcome.terminatedBy === null
+        ? `exited with code ${outcome.exitCode}`
+        : `was terminated by ${outcome.terminatedBy}`;
+    const invocation = [command.command, ...command.args.slice(0, 2)].join(" ");
+    const tail = outcome.stderrTail === "" ? "" : `\n${outcome.stderrTail.trimEnd()}`;
+    return `${invocation} ${how}${tail}`;
+}
+function iterationChildPath_() {
+    return fileURLToPath(import.meta.resolve("@ac-bench/measure-duration/iteration-child"));
+}
+//# sourceMappingURL=_iteration-source.js.map

package/dist/_iteration-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_iteration-source.js","sourceRoot":"","sources":["../src/_iteration-source.ts"],"names":[],"mappings":"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"}

package/dist/_pool.d.ts

@@ -0,0 +1,48 @@
+import { MeasureExecution } from "@ac-bench/core/plugin";
+import { CentralEstimator } from "@ac-bench/core/runner";
+import { ConfidenceInterval } from "@ac-kit/math-stats";
+import * as z from "zod/mini";
+import { DurationBenchRunCaseResult } from "./_types.js";
+export declare const pooledEstimateSchema: z.ZodMiniObject<{
+    estimateMs: z.ZodMiniNumber<number>;
+    lowerMs: z.ZodMiniNumber<number>;
+    upperMs: z.ZodMiniNumber<number>;
+    betweenVarianceMs2: z.ZodMiniNumber<number>;
+    heterogeneity: z.ZodMiniNumber<number>;
+    executions: z.ZodMiniNumber<number>;
+    estimator: z.ZodMiniEnum<{
+        mean: "mean";
+        median: "median";
+    }>;
+}, z.core.$strip>;
+export type PooledEstimate = z.infer<typeof pooledEstimateSchema>;
+export declare const contaminationSchema: z.ZodMiniObject<{
+    differenceMs: z.ZodMiniNumber<number>;
+    share: z.ZodMiniNumber<number>;
+    sharedExecutions: z.ZodMiniNumber<number>;
+    isolatedExecutions: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export type Contamination = z.infer<typeof contaminationSchema>;
+/**
+ * Combines every execution of one case into the result that answers for it.
+ *
+ * Executions come from different processes, and a process contributes an offset
+ * of its own — GC seed, address-space layout, which JIT tier the code settled
+ * in, the thermal state at that moment. Averaging the estimates would report an
+ * interval far too narrow, because it would treat that offset as if it did not
+ * exist. Random-effects pooling estimates it instead and widens the interval by
+ * it.
+ *
+ * The pooled interval is symmetric by construction, which is inverse-variance
+ * pooling's assumption rather than a property of the samples: a skewed median
+ * interval is symmetrised on the way in.
+ *
+ * @param executions At least one, in no particular order.
+ * @param estimator Which reported statistic to pool.
+ * @returns The pooled result, or the sole execution's own result when there is
+ *   only one.
+ */
+export declare function poolDurationExecutions(executions: readonly MeasureExecution<DurationBenchRunCaseResult>[], estimator?: CentralEstimator): DurationBenchRunCaseResult;
+/** An interval a reader can quote, from the pooled estimate. */
+export declare function pooledInterval(estimate: PooledEstimate): ConfidenceInterval;
+//# sourceMappingURL=_pool.d.ts.map

package/dist/_pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_pool.d.ts","sourceRoot":"","sources":["../src/_pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACN,kBAAkB,EAGlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAI9B,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAQzD,eAAO,MAAM,oBAAoB;;;;;;;;;;;iBAa/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,mBAAmB;;;;;iBAQ9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,SAAS,gBAAgB,CAAC,0BAA0B,CAAC,EAAE,EACnE,SAAS,GAAE,gBAA2B,GACpC,0BAA0B,CAyC5B;AA6LD,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAQ3E"}