@ac-bench/measure-duration 0.1.0

package/dist/_run-case.js

@@ -0,0 +1,267 @@
+import { createRelativeErrorPolicy, Sampler, } from "@ac-bench/core/runner";
+import { defaults, formatError } from "@ac-kit/core";
+import { calibrateHarnessOverhead, detectHarnessShape, } from "./_harness-overhead.js";
+import { SINGLE_ITERATION_OPTION } from "./_iteration-protocol.js";
+import { commandCaseCommand, iterationProcessCommand, measureIteration, measureSpawnBaseline, spawnBaselineReport, summariseColdStart, } from "./_iteration-source.js";
+import { ProcessGroup } from "./_process-execution.js";
+import { DURATION_SAMPLING_DEFAULTS, } from "./_sampling-options.js";
+import { summarise } from "./_statistics.js";
+import { detectWarnings_ } from "./_warnings.js";
+/** Above this predicted batch duration, cancellation is checked per iteration. */
+const LONG_BATCH_MS_ = 200;
+/**
+ * Runs one benchmark case under the adaptive sampler.
+ *
+ * The loop belongs to the sampler: it decides how many samples to take next and
+ * when the interval around the estimate is tight enough. What happens here is
+ * only the measuring — the timed span is `performance.now()` immediately around
+ * one iteration and nothing else, so hooks, statistics and reporting stay
+ * outside the number being reported.
+ *
+ * An iteration is one call in this process, one fresh process running this same
+ * case body, or one execution of an external program. All three go through the
+ * same loop and the same stopping rule; only what an iteration _is_ differs.
+ *
+ * @param title Case name, carried into the reported result.
+ * @param runFn The work to measure.
+ * @param context Run context, used to report the result and check for abort.
+ * @param options Sampling policy and execution mode.
+ */
+export async function runDurationCase(title, runFn, context, options) {
+    const { signal } = context;
+    signal.throwIfAborted();
+    // A spawned iteration re-enters this same case body; without this it would
+    // start a sampling run of its own, one process deep, forever.
+    if (context.measureOptions[SINGLE_ITERATION_OPTION] === true) {
+        await runSingleIteration_(runFn, options, signal);
+        return;
+    }
+    const sampling = defaults(options?.conditionOptions?.sampling, DURATION_SAMPLING_DEFAULTS);
+    const tags = options?.tags ?? {};
+    const command = resolveCommand_(context, options);
+    const execution = options?.commandCase !== undefined
+        ? "command"
+        : (options?.execution ?? "in-process");
+    if (command !== null && options?.overheadMs !== undefined) {
+        if (options.subtractSpawnBaseline === true) {
+            throw new Error(`Case "${title}" declares both overheadMs and subtractSpawnBaseline; they would be subtracted twice`);
+        }
+    }
+    const subtractBaseline = command !== null &&
+        options?.overheadMs === undefined &&
+        options?.subtractSpawnBaseline !== false;
+    const group = command === null ? null : new ProcessGroup();
+    const coldStartPhases = [];
+    let overheadMs = options?.overheadMs ?? 0;
+    let baselineStatistics = null;
+    const sampler = new Sampler(createRelativeErrorPolicy(sampling), {
+        bounds: sampling,
+        signal,
+        costOf: (ms) => ms,
+    });
+    const timings = [];
+    const correctedTimings = [];
+    const adjustedTimings = [];
+    let measuredMs = 0;
+    let startedAt = null;
+    let endedAt = 0;
+    let shape = "sync";
+    let harnessMs = 0;
+    let harnessOverhead = null;
+    try {
+        // The case's own setup runs inside each spawned process, so that a cold
+        // start is measured whole rather than with its preparation hoisted out.
+        if (command === null) {
+            await options?.setup?.(signal);
+        }
+        if (command === null) {
+            // Warmup runs before the pilot and is never counted in the statistics.
+            for (let iteration = 0; iteration < sampling.warmup; iteration++) {
+                signal.throwIfAborted();
+                await options?.beforeEach?.(signal);
+                const returned = runFn(signal);
+                if (iteration === 0) {
+                    shape = detectHarnessShape(runFn, returned);
+                }
+                await returned;
+                await options?.afterEach?.(signal);
+            }
+            // After warmup and before the pilot, so the shape is known and the
+            // measurement has not started.
+            const harness = await calibrateHarnessOverhead(shape, sampling.outlierThreshold, signal);
+            harnessMs = sampling.subtractHarnessOverhead ? harness.medianMs : 0;
+            harnessOverhead = {
+                shape,
+                medianMs: harness.medianMs,
+                share: 0,
+                subtracted: sampling.subtractHarnessOverhead,
+            };
+        }
+        else {
+            // A spawn is orders of magnitude above the call overhead a harness
+            // correction addresses; what it needs removed is the program's own
+            // start-up, which is what the baseline measures.
+            baselineStatistics = await measureSpawnBaseline(group, command, { warmup: sampling.warmup, runs: sampling.minRuns }, signal);
+            if (subtractBaseline && baselineStatistics !== null) {
+                overheadMs = baselineStatistics.medianMs;
+            }
+        }
+        for (let size = sampler.nextBatch(); size !== null;) {
+            const sliceStartedAt = performance.now();
+            startedAt ??= sliceStartedAt;
+            const batch = [];
+            const longBatch = size * (measuredMs / Math.max(1, timings.length)) > LONG_BATCH_MS_;
+            for (let iteration = 0; iteration < size; iteration++) {
+                if (longBatch || command !== null) {
+                    signal.throwIfAborted();
+                }
+                await options?.beforeEach?.(signal);
+                const spanMs = command === null
+                    ? await measureInProcess_(runFn, signal)
+                    : await measureIteration(group, command, coldStartPhases, signal);
+                await options?.afterEach?.(signal);
+                measuredMs += spanMs;
+                timings.push(spanMs);
+                // Negatives are kept rather than clamped: a one-sided truncation
+                // would bias the result upward exactly where the correction helps.
+                const corrected = spanMs - harnessMs;
+                correctedTimings.push(corrected);
+                adjustedTimings.push(corrected - overheadMs);
+                // The controller steers on the number a comparison is made on.
+                batch.push(corrected - overheadMs);
+            }
+            endedAt = performance.now();
+            sampler.observe(batch, endedAt - sliceStartedAt);
+            context.progress(timings.length);
+            if (signal.aborted) {
+                sampler.stop("cancelled");
+                break;
+            }
+            size = sampler.nextBatch();
+            // A batch is a slice, and this is the boundary between two of them: a
+            // sibling case takes the next one. Asking the sampler first means a
+            // case that is done never spends a turn discovering it.
+            if (size !== null) {
+                await context.round();
+            }
+        }
+    }
+    catch (error) {
+        sampler.stop(signal.aborted ? "cancelled" : "failure");
+        await group?.dispose();
+        context.setCaseResult({
+            name: title,
+            tags,
+            statistics: null,
+            adjusted: null,
+            overheadMs,
+            timings: [],
+            sampling: null,
+            harnessOverhead: null,
+            execution,
+            spawnBaseline: null,
+            coldStart: null,
+            estimate: null,
+            contamination: null,
+            warnings: [],
+            failure: await failureMessage_(error, options, signal),
+        });
+        return;
+    }
+    await group?.dispose();
+    if (command === null) {
+        await options?.teardown?.(signal);
+    }
+    const result = sampler.result();
+    const report = {
+        ...result.metadata,
+        stopReason: result.stopReason,
+        measuredMs,
+        activeMs: result.activeMs,
+        elapsedMs: startedAt === null ? 0 : endedAt - startedAt,
+        samples: timings.length,
+        batches: result.batches,
+    };
+    // Outliers are flagged, never removed: dropping them would let the controller
+    // reach its target by discarding the evidence that it had not.
+    const statistics = summarise(correctedTimings, sampling.outlierThreshold);
+    if (harnessOverhead !== null) {
+        harnessOverhead = {
+            ...harnessOverhead,
+            share: statistics.medianMs > 0
+                ? harnessOverhead.medianMs / statistics.medianMs
+                : 1,
+        };
+    }
+    const spawnBaseline = command === null
+        ? null
+        : spawnBaselineReport(command, baselineStatistics, statistics.medianMs, subtractBaseline && baselineStatistics !== null);
+    context.setCaseResult({
+        name: title,
+        tags,
+        statistics,
+        adjusted: overheadMs > 0
+            ? summarise(adjustedTimings, sampling.outlierThreshold)
+            : null,
+        overheadMs,
+        timings,
+        sampling: report,
+        harnessOverhead,
+        execution,
+        spawnBaseline,
+        coldStart: summariseColdStart(coldStartPhases),
+        estimate: null,
+        contamination: null,
+        warnings: detectWarnings_({
+            timings,
+            statistics,
+            overheadMs,
+            minRuns: sampling.minRuns,
+            sampling: report,
+            harnessOverhead,
+            spawnBaseline,
+            needsBaselineArgs: command !== null && command.baselineArgs === null,
+        }),
+    });
+    // After the timed region, and only on request: `child.send` has no transfer
+    // list, so every sample is copied across the boundary.
+    if (context.measureOptions["emitSamples"] === true) {
+        context.attach(JSON.stringify(timings), "application/json", `${title} samples`);
+    }
+}
+async function measureInProcess_(runFn, signal) {
+    const begin = performance.now();
+    await runFn(signal);
+    return performance.now() - begin;
+}
+/** What one iteration executes, or `null` when it is a call in this process. */
+function resolveCommand_(context, options) {
+    if (options?.commandCase !== undefined) {
+        return commandCaseCommand(options.commandCase.command, options.commandCase.args, options.commandCase.options);
+    }
+    return options?.execution === "per-iteration-process"
+        ? iterationProcessCommand(context.caseId)
+        : null;
+}
+/** The body of one spawned iteration: setup and teardown are part of the sample. */
+async function runSingleIteration_(runFn, options, signal) {
+    await options?.setup?.(signal);
+    try {
+        await runFn(signal);
+    }
+    finally {
+        await options?.teardown?.(signal);
+    }
+}
+async function failureMessage_(error, options, signal) {
+    let failureMessage;
+    try {
+        await options?.teardown?.(signal);
+        failureMessage = formatError(error);
+    }
+    catch (tearDownError) {
+        failureMessage = formatError(new SuppressedError(tearDownError, error, "teardown failed after case failure"));
+    }
+    return failureMessage;
+}
+//# sourceMappingURL=_run-case.js.map

package/dist/_run-case.js.map

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

package/dist/_sampling-options.d.ts

@@ -0,0 +1,61 @@
+import { CentralEstimator, RelativeErrorTarget, SamplingBounds } from "@ac-bench/core/runner";
+/**
+ * Every sampling knob, fully populated.
+ *
+ * Frozen because it is the only place a default is applied: nothing downstream
+ * may write `?? someDefault`, which is what makes a cross-wired option (reading
+ * `minRuns` from `minTimeMs`, say) a single-file defect rather than a class of
+ * them.
+ */
+export type DurationSampling = SamplingBounds & {
+    /**
+     * Warmup iterations run before any measured samples, letting the JIT
+     * specialise and caches warm.
+     *
+     * Defaults to 3.
+     */
+    warmup: number;
+    /**
+     * How tight the confidence interval must be, relative to the estimate, before
+     * sampling stops.
+     *
+     * `"auto"` (the default) derives a target from the spread observed on this
+     * machine for this case, so a noisy runner and a quiet workstation each get
+     * an appropriate one. `"off"` reproduces the fixed-bound loop exactly, which
+     * is what a differential or regression run wants.
+     */
+    relativeError: RelativeErrorTarget;
+    /** Confidence level for the reported interval. Defaults to 0.95. */
+    confidenceLevel: number;
+    /**
+     * Defaults to `"median"`, whose uncertainty is the distribution-free
+     * order-statistic interval — the right choice for a distribution whose right
+     * tail is made of GC pauses and scheduler preemptions.
+     */
+    estimator: CentralEstimator;
+    /** Modified Z-score above which a sample is flagged. Defaults to 3.5. */
+    outlierThreshold: number;
+    /**
+     * Whether to subtract the harness overhead from each sample. Defaults to
+     * `false`.
+     */
+    subtractHarnessOverhead: boolean;
+};
+/**
+ * With an error target driving the loop, `maxRuns` is a safety net rather than
+ * the primary control, and a `minTimeMs` that dominates the controller would
+ * make the controller pointless.
+ */
+export declare const DURATION_SAMPLING_DEFAULTS: {
+    readonly warmup: 3;
+    readonly minRuns: 10;
+    readonly maxRuns: 100000;
+    readonly minTimeMs: 250;
+    readonly maxTimeMs: 10000;
+    readonly relativeError: "auto";
+    readonly confidenceLevel: 0.95;
+    readonly estimator: "median";
+    readonly outlierThreshold: 3.5;
+    readonly subtractHarnessOverhead: false;
+};
+//# sourceMappingURL=_sampling-options.d.ts.map

package/dist/_sampling-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_sampling-options.d.ts","sourceRoot":"","sources":["../src/_sampling-options.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG;IAC/C;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;;OAQG;IACH,aAAa,EAAE,mBAAmB,CAAC;IAEnC,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAE5B,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,uBAAuB,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;qBAC9B,CAAC;sBACA,EAAE;sBACF,MAAO;wBACL,GAAG;wBACH,KAAM;4BACF,MAAM;8BACJ,IAAI;wBACV,QAAQ;;;CAGiB,CAAC"}

package/dist/_sampling-options.js

@@ -0,0 +1,19 @@
+import { DEFAULT_OUTLIER_THRESHOLD } from "@ac-kit/math-stats";
+/**
+ * With an error target driving the loop, `maxRuns` is a safety net rather than
+ * the primary control, and a `minTimeMs` that dominates the controller would
+ * make the controller pointless.
+ */
+export const DURATION_SAMPLING_DEFAULTS = {
+    warmup: 3,
+    minRuns: 10,
+    maxRuns: 100000,
+    minTimeMs: 250,
+    maxTimeMs: 10000,
+    relativeError: "auto",
+    confidenceLevel: 0.95,
+    estimator: "median",
+    outlierThreshold: DEFAULT_OUTLIER_THRESHOLD,
+    subtractHarnessOverhead: false,
+};
+//# sourceMappingURL=_sampling-options.js.map

package/dist/_sampling-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_sampling-options.js","sourceRoot":"","sources":["../src/_sampling-options.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAkD/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,EAAE;IACX,OAAO,EAAE,MAAO;IAChB,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,KAAM;IACjB,aAAa,EAAE,MAAM;IACrB,eAAe,EAAE,IAAI;IACrB,SAAS,EAAE,QAAQ;IACnB,gBAAgB,EAAE,yBAAyB;IAC3C,uBAAuB,EAAE,KAAK;CACM,CAAC"}

package/dist/_sampling-report.d.ts

@@ -0,0 +1,44 @@
+import * as z from "zod/mini";
+export declare const durationStopReasonSchema: z.ZodMiniEnum<{
+    cancelled: "cancelled";
+    failure: "failure";
+    "max-runs": "max-runs";
+    "max-time": "max-time";
+    "min-time": "min-time";
+    mixed: "mixed";
+    "policy-satisfied": "policy-satisfied";
+}>;
+/**
+ * What the sampler did, and how well it did it.
+ *
+ * Three clocks rather than two, because round-robin interleaving makes wall
+ * time and this-case time different numbers — and because `measuredMs /
+ * activeMs` is a directly observable contamination ratio.
+ */
+export declare const durationSamplingReportSchema: z.ZodMiniObject<{
+    requestedRelativeError: z.ZodMiniUnion<readonly [z.ZodMiniNumber<number>, z.ZodMiniLiteral<"auto">, z.ZodMiniLiteral<"off">]>;
+    effectiveRelativeErrorTarget: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    achievedRelativeError: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    targetReached: z.ZodMiniBoolean<boolean>;
+    confidenceLevel: z.ZodMiniNumber<number>;
+    estimator: z.ZodMiniEnum<{
+        mean: "mean";
+        median: "median";
+    }>;
+    stopReason: z.ZodMiniEnum<{
+        cancelled: "cancelled";
+        failure: "failure";
+        "max-runs": "max-runs";
+        "max-time": "max-time";
+        "min-time": "min-time";
+        mixed: "mixed";
+        "policy-satisfied": "policy-satisfied";
+    }>;
+    measuredMs: z.ZodMiniNumber<number>;
+    activeMs: z.ZodMiniNumber<number>;
+    elapsedMs: z.ZodMiniNumber<number>;
+    samples: z.ZodMiniNumber<number>;
+    batches: z.ZodMiniNumber<number>;
+}, z.core.$strip>;
+export type DurationSamplingReport = z.infer<typeof durationSamplingReportSchema>;
+//# sourceMappingURL=_sampling-report.d.ts.map

package/dist/_sampling-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_sampling-report.d.ts","sourceRoot":"","sources":["../src/_sampling-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,eAAO,MAAM,wBAAwB;;;;;;;;EASnC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;iBAyBvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,4BAA4B,CACnC,CAAC"}

package/dist/_sampling-report.js

@@ -0,0 +1,43 @@
+import * as z from "zod/mini";
+export const durationStopReasonSchema = z.enum([
+    "policy-satisfied",
+    "min-time",
+    "max-time",
+    "max-runs",
+    "cancelled",
+    "failure",
+    /** Pooled from executions that did not agree on why they stopped. */
+    "mixed",
+]);
+/**
+ * What the sampler did, and how well it did it.
+ *
+ * Three clocks rather than two, because round-robin interleaving makes wall
+ * time and this-case time different numbers — and because `measuredMs /
+ * activeMs` is a directly observable contamination ratio.
+ */
+export const durationSamplingReportSchema = z.object({
+    requestedRelativeError: z.union([
+        z.number(),
+        z.literal("auto"),
+        z.literal("off"),
+    ]),
+    effectiveRelativeErrorTarget: z.nullable(z.number()),
+    achievedRelativeError: z.nullable(z.number()),
+    targetReached: z.boolean(),
+    confidenceLevel: z.number(),
+    estimator: z.enum(["mean", "median"]),
+    stopReason: durationStopReasonSchema,
+    /** Sum of the per-iteration timed spans. What the statistics describe. */
+    measuredMs: z.number(),
+    /**
+     * Wall time attributable to this case, hooks and recomputation included. The
+     * time bounds apply here, never to `elapsedMs`.
+     */
+    activeMs: z.number(),
+    /** First slice to last. Under interleaving it includes other cases' work. */
+    elapsedMs: z.number(),
+    samples: z.number(),
+    batches: z.number(),
+});
+//# sourceMappingURL=_sampling-report.js.map

package/dist/_sampling-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_sampling-report.js","sourceRoot":"","sources":["../src/_sampling-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC9C,kBAAkB;IAClB,UAAU;IACV,UAAU;IACV,UAAU;IACV,WAAW;IACX,SAAS;IACT,qEAAqE;IACrE,OAAO;CACP,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,sBAAsB,EAAE,CAAC,CAAC,KAAK,CAAC;QAC/B,CAAC,CAAC,MAAM,EAAE;QACV,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;QACjB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;KAChB,CAAC;IACF,4BAA4B,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACpD,qBAAqB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7C,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;IAC1B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACrC,UAAU,EAAE,wBAAwB;IAEpC,0EAA0E;IAC1E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,6EAA6E;IAC7E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IAErB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC"}

package/dist/_spawn-baseline.d.ts

@@ -0,0 +1,35 @@
+import * as z from "zod/mini";
+/** Share of a case's median above which the baseline is most of the number. */
+export declare const SPAWN_BASELINE_DOMINATES = 0.75;
+/**
+ * What starting the program costs when it is asked to do nothing.
+ *
+ * A benchmark whose iteration is a whole process pays this on every sample
+ * while an in-process contender pays none of it. It is reported next to the
+ * result rather than folded into it, so a comparison can never quietly be
+ * between one number that had start-up removed and one that did not.
+ */
+export declare const spawnBaselineReportSchema: z.ZodMiniObject<{
+    command: z.ZodMiniString<string>;
+    statistics: z.ZodMiniObject<{
+        samples: z.ZodMiniNumber<number>;
+        meanMs: z.ZodMiniNumber<number>;
+        stdDevMs: z.ZodMiniNumber<number>;
+        confidence95Ms: z.ZodMiniNumber<number>;
+        medianMs: z.ZodMiniNumber<number>;
+        medianConfidence95Ms: z.ZodMiniNumber<number>;
+        madMs: z.ZodMiniNumber<number>;
+        minMs: z.ZodMiniNumber<number>;
+        maxMs: z.ZodMiniNumber<number>;
+        p95Ms: z.ZodMiniNumber<number>;
+        p99Ms: z.ZodMiniNumber<number>;
+        relativeStdDev: z.ZodMiniNumber<number>;
+        relativeMad: z.ZodMiniNumber<number>;
+        outlierIndices: z.ZodMiniArray<z.ZodMiniNumber<number>>;
+        opsPerSecond: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+    }, z.core.$strip>;
+    share: z.ZodMiniNumber<number>;
+    subtracted: z.ZodMiniBoolean<boolean>;
+}, z.core.$strip>;
+export type SpawnBaselineReport = z.infer<typeof spawnBaselineReportSchema>;
+//# sourceMappingURL=_spawn-baseline.d.ts.map

package/dist/_spawn-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_spawn-baseline.d.ts","sourceRoot":"","sources":["../src/_spawn-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAI9B,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;iBAQpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/_spawn-baseline.js

@@ -0,0 +1,22 @@
+import * as z from "zod/mini";
+import { durationStatisticsSchema } from "./_statistics-schema.js";
+/** Share of a case's median above which the baseline is most of the number. */
+export const SPAWN_BASELINE_DOMINATES = 0.75;
+/**
+ * What starting the program costs when it is asked to do nothing.
+ *
+ * A benchmark whose iteration is a whole process pays this on every sample
+ * while an in-process contender pays none of it. It is reported next to the
+ * result rather than folded into it, so a comparison can never quietly be
+ * between one number that had start-up removed and one that did not.
+ */
+export const spawnBaselineReportSchema = z.object({
+    /** Program measured, as invoked. */
+    command: z.string(),
+    statistics: durationStatisticsSchema,
+    /** Baseline median as a fraction of the case median. */
+    share: z.number(),
+    /** Whether it was removed from the samples behind `adjusted`. */
+    subtracted: z.boolean(),
+});
+//# sourceMappingURL=_spawn-baseline.js.map

package/dist/_spawn-baseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_spawn-baseline.js","sourceRoot":"","sources":["../src/_spawn-baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,oCAAoC;IACpC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,UAAU,EAAE,wBAAwB;IACpC,wDAAwD;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,iEAAiE;IACjE,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC"}

package/dist/_statistics-schema.d.ts

@@ -0,0 +1,28 @@
+import * as z from "zod/mini";
+/**
+ * Descriptive statistics for a set of timing samples.
+ *
+ * Both a mean with dispersion and a median with percentiles are reported. The
+ * mean is what most tools show and is comparable across runs; the median and
+ * MAD are robust to the long right tail that dominates benchmarks involving
+ * I/O, garbage collection or process scheduling.
+ */
+export declare const durationStatisticsSchema: z.ZodMiniObject<{
+    samples: z.ZodMiniNumber<number>;
+    meanMs: z.ZodMiniNumber<number>;
+    stdDevMs: z.ZodMiniNumber<number>;
+    confidence95Ms: z.ZodMiniNumber<number>;
+    medianMs: z.ZodMiniNumber<number>;
+    medianConfidence95Ms: z.ZodMiniNumber<number>;
+    madMs: z.ZodMiniNumber<number>;
+    minMs: z.ZodMiniNumber<number>;
+    maxMs: z.ZodMiniNumber<number>;
+    p95Ms: z.ZodMiniNumber<number>;
+    p99Ms: z.ZodMiniNumber<number>;
+    relativeStdDev: z.ZodMiniNumber<number>;
+    relativeMad: z.ZodMiniNumber<number>;
+    outlierIndices: z.ZodMiniArray<z.ZodMiniNumber<number>>;
+    opsPerSecond: z.ZodMiniNullable<z.ZodMiniNumber<number>>;
+}, z.core.$strip>;
+export type DurationStatistics = z.infer<typeof durationStatisticsSchema>;
+//# sourceMappingURL=_statistics-schema.d.ts.map

package/dist/_statistics-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_statistics-schema.d.ts","sourceRoot":"","sources":["../src/_statistics-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;iBAgDnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/_statistics-schema.js

@@ -0,0 +1,59 @@
+import * as z from "zod/mini";
+/**
+ * Descriptive statistics for a set of timing samples.
+ *
+ * Both a mean with dispersion and a median with percentiles are reported. The
+ * mean is what most tools show and is comparable across runs; the median and
+ * MAD are robust to the long right tail that dominates benchmarks involving
+ * I/O, garbage collection or process scheduling.
+ */
+export const durationStatisticsSchema = z.object({
+    /** Number of measured samples. */
+    samples: z.number(),
+    /** Arithmetic mean, in milliseconds. */
+    meanMs: z.number(),
+    /** Sample standard deviation (Bessel-corrected), in milliseconds. */
+    stdDevMs: z.number(),
+    /** Half-width of the 95% confidence interval of the mean. */
+    confidence95Ms: z.number(),
+    /** Median, in milliseconds. */
+    medianMs: z.number(),
+    /**
+     * Half-width of the 95% confidence interval of the median.
+     *
+     * Distribution-free, from the order statistics, so it does not assume the
+     * heavy right tail away the way the mean's normal approximation does. The
+     * underlying interval can be asymmetric about the median; this is half its
+     * total width, which is what combining executions needs.
+     */
+    medianConfidence95Ms: z.number(),
+    /**
+     * Median absolute deviation, in milliseconds. A dispersion measure that a
+     * handful of extreme samples cannot inflate.
+     */
+    madMs: z.number(),
+    /** Minimum sample, in milliseconds. */
+    minMs: z.number(),
+    /** Maximum sample, in milliseconds. */
+    maxMs: z.number(),
+    /** 95th percentile, in milliseconds. */
+    p95Ms: z.number(),
+    /** 99th percentile, in milliseconds. */
+    p99Ms: z.number(),
+    /** Standard deviation as a fraction of the mean. */
+    relativeStdDev: z.number(),
+    /**
+     * Median absolute deviation as a fraction of the median.
+     *
+     * The robust counterpart of {@link DurationStatistics.relativeStdDev}. Garbage
+     * collection and scheduler preemption give benchmark timings a heavy right
+     * tail, which inflates the standard deviation without saying anything about
+     * the typical case.
+     */
+    relativeMad: z.number(),
+    /** Indices of samples flagged by `findOutliers`. */
+    outlierIndices: z.array(z.number()),
+    /** Operations per second, derived from the mean. */
+    opsPerSecond: z.nullable(z.number()),
+});
+//# sourceMappingURL=_statistics-schema.js.map

package/dist/_statistics-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_statistics-schema.js","sourceRoot":"","sources":["../src/_statistics-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,qEAAqE;IACrE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,6DAA6D;IAC7D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,+BAA+B;IAC/B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB;;;;;;;OAOG;IACH,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE;IAChC;;;OAGG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,wCAAwC;IACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,wCAAwC;IACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,oDAAoD;IACpD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,oDAAoD;IACpD,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnC,oDAAoD;IACpD,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACpC,CAAC,CAAC"}