@ac-bench/measure-duration 0.1.0

package/dist/_statistics.d.ts

@@ -0,0 +1,25 @@
+import { type RatioWithUncertainty } from "@ac-kit/math-stats";
+import { DurationStatistics } from "./_statistics-schema.js";
+/**
+ * Compute descriptive statistics for a set of timings.
+ *
+ * @param samples Durations in milliseconds. Not modified.
+ * @param outlierThreshold Modified Z-score above which a sample is flagged.
+ * @returns The computed statistics.
+ * @throws {RangeError} If `samples` is empty.
+ */
+export declare function summarise(samples: readonly number[], outlierThreshold?: number): DurationStatistics;
+/**
+ * Ratio of two measurements with propagated uncertainty.
+ *
+ * Reporting `2.4x` without an error term invites reading noise as signal, so
+ * the relative dispersions of both operands are combined.
+ *
+ * @param value Statistics for the measurement being compared.
+ * @param baseline Statistics for the reference measurement.
+ * @param basis Which central tendency to compare. `median` pairs with the
+ *   median absolute deviation and is the robust choice.
+ * @returns The ratio and its error margin.
+ */
+export declare function relativeTo(value: DurationStatistics, baseline: DurationStatistics, basis?: "mean" | "median"): RatioWithUncertainty;
+//# sourceMappingURL=_statistics.d.ts.map

package/dist/_statistics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_statistics.d.ts","sourceRoot":"","sources":["../src/_statistics.ts"],"names":[],"mappings":"AAAA,OAAO,EAQN,KAAK,oBAAoB,EAEzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAK7D;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,gBAAgB,GAAE,MAAkC,GAClD,kBAAkB,CA+BpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,GAAE,MAAM,GAAG,QAAmB,GACjC,oBAAoB,CAUtB"}

package/dist/_statistics.js

@@ -0,0 +1,72 @@
+import { DEFAULT_OUTLIER_THRESHOLD, findOutliers, mean, medianAbsoluteDeviation, medianConfidenceInterval, quantile, ratioWithUncertainty, sampleStandardDeviation, } from "@ac-kit/math-stats";
+/** Normal quantile for a two-sided 95% interval. */
+const Z_95 = 1.959964;
+/**
+ * Compute descriptive statistics for a set of timings.
+ *
+ * @param samples Durations in milliseconds. Not modified.
+ * @param outlierThreshold Modified Z-score above which a sample is flagged.
+ * @returns The computed statistics.
+ * @throws {RangeError} If `samples` is empty.
+ */
+export function summarise(samples, outlierThreshold = DEFAULT_OUTLIER_THRESHOLD) {
+    if (samples.length === 0) {
+        throw new RangeError("Cannot summarise an empty sample set");
+    }
+    const sorted = [...samples].sort((left, right) => left - right);
+    const count = sorted.length;
+    const meanMs = mean(sorted);
+    const stdDevMs = sampleStandardDeviation(sorted);
+    const medianMs = quantile(sorted, 0.5);
+    const madMs = medianAbsoluteDeviation(sorted, medianMs);
+    return {
+        samples: count,
+        meanMs,
+        stdDevMs,
+        confidence95Ms: count > 1 ? (Z_95 * stdDevMs) / Math.sqrt(count) : 0,
+        medianMs,
+        medianConfidence95Ms: medianHalfWidth_(sorted),
+        madMs,
+        minMs: sorted[0],
+        maxMs: sorted[count - 1],
+        p95Ms: quantile(sorted, 0.95),
+        p99Ms: quantile(sorted, 0.99),
+        relativeStdDev: meanMs > 0 ? stdDevMs / meanMs : 0,
+        relativeMad: medianMs > 0 ? madMs / medianMs : 0,
+        outlierIndices: findOutliers(samples, outlierThreshold),
+        // An overhead correction can legitimately drive the mean to zero or below,
+        // and there is no rate to report when it does.
+        opsPerSecond: meanMs > 0 ? 1000 / meanMs : null,
+    };
+}
+/**
+ * Ratio of two measurements with propagated uncertainty.
+ *
+ * Reporting `2.4x` without an error term invites reading noise as signal, so
+ * the relative dispersions of both operands are combined.
+ *
+ * @param value Statistics for the measurement being compared.
+ * @param baseline Statistics for the reference measurement.
+ * @param basis Which central tendency to compare. `median` pairs with the
+ *   median absolute deviation and is the robust choice.
+ * @returns The ratio and its error margin.
+ */
+export function relativeTo(value, baseline, basis = "median") {
+    const centre = basis === "mean" ? "meanMs" : "medianMs";
+    const spread = basis === "mean" ? "relativeStdDev" : "relativeMad";
+    return ratioWithUncertainty(value[centre], value[spread], baseline[centre], baseline[spread]);
+}
+/**
+ * Half-width of the distribution-free 95% interval around the median.
+ *
+ * A single sample has no spread to measure, so the interval collapses to zero
+ * width rather than being undefined.
+ */
+function medianHalfWidth_(sorted) {
+    if (sorted.length < 2) {
+        return 0;
+    }
+    const interval = medianConfidenceInterval(sorted);
+    return (interval.upper - interval.lower) / 2;
+}
+//# sourceMappingURL=_statistics.js.map

package/dist/_statistics.js.map

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

package/dist/_types.d.ts

@@ -0,0 +1,302 @@
+import * as z from "zod/mini";
+import { durationStatisticsSchema } from "./_statistics-schema.js";
+export type { DurationStatistics } from "./_statistics-schema.js";
+export { durationStatisticsSchema };
+export declare const durationBenchRunCaseResultSchema: z.ZodMiniObject<{
+    name: z.ZodMiniString<string>;
+    tags: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+    statistics: z.ZodMiniNullable<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>>;
+    adjusted: z.ZodMiniNullable<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>>;
+    overheadMs: z.ZodMiniNumber<number>;
+    timings: z.ZodMiniArray<z.ZodMiniNumber<number>>;
+    sampling: z.ZodMiniNullable<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>>;
+    harnessOverhead: z.ZodMiniNullable<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>>;
+    execution: z.ZodMiniEnum<{
+        command: "command";
+        "in-process": "in-process";
+        "per-iteration-process": "per-iteration-process";
+    }>;
+    spawnBaseline: z.ZodMiniNullable<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>>;
+    coldStart: z.ZodMiniNullable<z.ZodMiniObject<{
+        startupMs: z.ZodMiniNumber<number>;
+        importMs: z.ZodMiniNumber<number>;
+        runMs: z.ZodMiniNumber<number>;
+    }, z.core.$strip>>;
+    estimate: z.ZodMiniNullable<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>>;
+    contamination: z.ZodMiniNullable<z.ZodMiniObject<{
+        differenceMs: z.ZodMiniNumber<number>;
+        share: z.ZodMiniNumber<number>;
+        sharedExecutions: z.ZodMiniNumber<number>;
+        isolatedExecutions: z.ZodMiniNumber<number>;
+    }, z.core.$strip>>;
+    warnings: z.ZodMiniArray<z.ZodMiniObject<{
+        kind: z.ZodMiniEnum<{
+            "first-run-slow": "first-run-slow";
+            "harness-overhead-dominates": "harness-overhead-dominates";
+            "high-variance": "high-variance";
+            "no-baseline-args": "no-baseline-args";
+            outliers: "outliers";
+            "overhead-dominates": "overhead-dominates";
+            "overhead-subtracted": "overhead-subtracted";
+            "spawn-baseline-dominates": "spawn-baseline-dominates";
+            "spawn-baseline-subtracted": "spawn-baseline-subtracted";
+            "target-not-reached": "target-not-reached";
+            "too-few-samples": "too-few-samples";
+        }>;
+        message: z.ZodMiniString<string>;
+        severity: z.ZodMiniOptional<z.ZodMiniEnum<{
+            info: "info";
+            warning: "warning";
+        }>>;
+    }, z.core.$strip>>;
+    failure: z.ZodMiniOptional<z.ZodMiniString<string>>;
+}, z.core.$strip>;
+export type DurationBenchRunCaseResult = z.infer<typeof durationBenchRunCaseResultSchema>;
+export declare const durationBenchRunConditionResultSchema: z.ZodMiniObject<{
+    title: z.ZodMiniString<string>;
+    results: z.ZodMiniArray<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+        tags: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+        statistics: z.ZodMiniNullable<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>>;
+        adjusted: z.ZodMiniNullable<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>>;
+        overheadMs: z.ZodMiniNumber<number>;
+        timings: z.ZodMiniArray<z.ZodMiniNumber<number>>;
+        sampling: z.ZodMiniNullable<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>>;
+        harnessOverhead: z.ZodMiniNullable<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>>;
+        execution: z.ZodMiniEnum<{
+            command: "command";
+            "in-process": "in-process";
+            "per-iteration-process": "per-iteration-process";
+        }>;
+        spawnBaseline: z.ZodMiniNullable<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>>;
+        coldStart: z.ZodMiniNullable<z.ZodMiniObject<{
+            startupMs: z.ZodMiniNumber<number>;
+            importMs: z.ZodMiniNumber<number>;
+            runMs: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        estimate: z.ZodMiniNullable<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>>;
+        contamination: z.ZodMiniNullable<z.ZodMiniObject<{
+            differenceMs: z.ZodMiniNumber<number>;
+            share: z.ZodMiniNumber<number>;
+            sharedExecutions: z.ZodMiniNumber<number>;
+            isolatedExecutions: z.ZodMiniNumber<number>;
+        }, z.core.$strip>>;
+        warnings: z.ZodMiniArray<z.ZodMiniObject<{
+            kind: z.ZodMiniEnum<{
+                "first-run-slow": "first-run-slow";
+                "harness-overhead-dominates": "harness-overhead-dominates";
+                "high-variance": "high-variance";
+                "no-baseline-args": "no-baseline-args";
+                outliers: "outliers";
+                "overhead-dominates": "overhead-dominates";
+                "overhead-subtracted": "overhead-subtracted";
+                "spawn-baseline-dominates": "spawn-baseline-dominates";
+                "spawn-baseline-subtracted": "spawn-baseline-subtracted";
+                "target-not-reached": "target-not-reached";
+                "too-few-samples": "too-few-samples";
+            }>;
+            message: z.ZodMiniString<string>;
+            severity: z.ZodMiniOptional<z.ZodMiniEnum<{
+                info: "info";
+                warning: "warning";
+            }>>;
+        }, z.core.$strip>>;
+        failure: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DurationBenchRunConditionResult = z.infer<typeof durationBenchRunConditionResultSchema>;
+//# sourceMappingURL=_types.d.ts.map

package/dist/_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_types.d.ts","sourceRoot":"","sources":["../src/_types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAO9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuD3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,gCAAgC,CACvC,CAAC;AAEF,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGhD,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACpD,OAAO,qCAAqC,CAC5C,CAAC"}

package/dist/_types.js

@@ -0,0 +1,57 @@
+import * as z from "zod/mini";
+import { harnessOverheadSchema } from "./_harness-overhead.js";
+import { contaminationSchema, pooledEstimateSchema } from "./_pool.js";
+import { coldStartPhasesSchema } from "./_process-execution.js";
+import { durationSamplingReportSchema } from "./_sampling-report.js";
+import { spawnBaselineReportSchema } from "./_spawn-baseline.js";
+import { durationStatisticsSchema } from "./_statistics-schema.js";
+import { durationBenchWarningSchema } from "./_warnings.js";
+export { durationStatisticsSchema };
+export const durationBenchRunCaseResultSchema = z.object({
+    name: z.string(),
+    tags: z.record(z.string(), z.string()),
+    /** `null` when the case failed. */
+    statistics: z.nullable(durationStatisticsSchema),
+    /**
+     * Statistics with the declared fixed overhead removed from every sample, or
+     * `null` when no overhead was declared.
+     */
+    adjusted: z.nullable(durationStatisticsSchema),
+    /** Declared fixed overhead, in milliseconds. */
+    overheadMs: z.number(),
+    /** Raw timings in collection order, for export and re-analysis. */
+    timings: z.array(z.number()),
+    /** How the sampler ran, or `null` when the case never got that far. */
+    sampling: z.nullable(durationSamplingReportSchema),
+    /** What the measuring apparatus itself cost, or `null` when uncalibrated. */
+    harnessOverhead: z.nullable(harnessOverheadSchema),
+    /** How one iteration was executed. */
+    execution: z.enum(["in-process", "per-iteration-process", "command"]),
+    /**
+     * Cost of merely starting the program, for a process-based execution mode.
+     *
+     * `null` for `"in-process"`, and for a command case that declared no
+     * `baselineArgs` — there is no honest way to guess what "this program doing
+     * nothing" means.
+     */
+    spawnBaseline: z.nullable(spawnBaselineReportSchema),
+    /** Median phase breakdown of a cold start, when the process reported one. */
+    coldStart: z.nullable(coldStartPhasesSchema),
+    /**
+     * The answer, weighted across every process that measured this case.
+     *
+     * `null` when one process measured it: there is no between-process spread to
+     * estimate, and `statistics` already says everything that was measured.
+     */
+    estimate: z.nullable(pooledEstimateSchema),
+    /** How much the case's neighbours cost it. `null` unless both arms ran. */
+    contamination: z.nullable(contaminationSchema),
+    warnings: z.array(durationBenchWarningSchema),
+    /** Present when the case threw or crashed. */
+    failure: z.optional(z.string()),
+});
+export const durationBenchRunConditionResultSchema = z.object({
+    title: z.string(),
+    results: z.array(durationBenchRunCaseResultSchema),
+});
+//# sourceMappingURL=_types.js.map

package/dist/_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_types.js","sourceRoot":"","sources":["../src/_types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAG5D,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAEtC,mCAAmC;IACnC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAEhD;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IAE9C,gDAAgD;IAChD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IAEtB,mEAAmE;IACnE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAE5B,uEAAuE;IACvE,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAElD,6EAA6E;IAC7E,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAElD,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,uBAAuB,EAAE,SAAS,CAAC,CAAC;IAErE;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAEpD,6EAA6E;IAC7E,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAE5C;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAE1C,2EAA2E;IAC3E,aAAa,EAAE,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAE9C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC;IAE7C,8CAA8C;IAC9C,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC/B,CAAC,CAAC;AAKH,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC;CAClD,CAAC,CAAC"}

package/dist/_warnings.d.ts

@@ -0,0 +1,62 @@
+import * as z from "zod/mini";
+import { HarnessOverhead } from "./_harness-overhead.js";
+import { DurationSamplingReport } from "./_sampling-report.js";
+import { SpawnBaselineReport } from "./_spawn-baseline.js";
+import { DurationStatistics } from "./_statistics-schema.js";
+/** Categories of quality problem detected in a result. */
+export declare const durationBenchWarningKindSchema: z.ZodMiniEnum<{
+    "first-run-slow": "first-run-slow";
+    "harness-overhead-dominates": "harness-overhead-dominates";
+    "high-variance": "high-variance";
+    "no-baseline-args": "no-baseline-args";
+    outliers: "outliers";
+    "overhead-dominates": "overhead-dominates";
+    "overhead-subtracted": "overhead-subtracted";
+    "spawn-baseline-dominates": "spawn-baseline-dominates";
+    "spawn-baseline-subtracted": "spawn-baseline-subtracted";
+    "target-not-reached": "target-not-reached";
+    "too-few-samples": "too-few-samples";
+}>;
+export type DurationBenchWarningKind = z.infer<typeof durationBenchWarningKindSchema>;
+/** A quality problem that should be shown alongside the numbers. */
+export declare const durationBenchWarningSchema: z.ZodMiniObject<{
+    kind: z.ZodMiniEnum<{
+        "first-run-slow": "first-run-slow";
+        "harness-overhead-dominates": "harness-overhead-dominates";
+        "high-variance": "high-variance";
+        "no-baseline-args": "no-baseline-args";
+        outliers: "outliers";
+        "overhead-dominates": "overhead-dominates";
+        "overhead-subtracted": "overhead-subtracted";
+        "spawn-baseline-dominates": "spawn-baseline-dominates";
+        "spawn-baseline-subtracted": "spawn-baseline-subtracted";
+        "target-not-reached": "target-not-reached";
+        "too-few-samples": "too-few-samples";
+    }>;
+    message: z.ZodMiniString<string>;
+    severity: z.ZodMiniOptional<z.ZodMiniEnum<{
+        info: "info";
+        warning: "warning";
+    }>>;
+}, z.core.$strip>;
+export type DurationBenchWarning = z.infer<typeof durationBenchWarningSchema>;
+export type DetectWarningsInput = {
+    readonly timings: readonly number[];
+    readonly statistics: DurationStatistics;
+    readonly overheadMs: number;
+    readonly minRuns: number;
+    /** Omitted when the case never got as far as sampling. */
+    readonly sampling?: DurationSamplingReport | null;
+    readonly harnessOverhead?: HarnessOverhead | null;
+    readonly spawnBaseline?: SpawnBaselineReport | null;
+    /** A process-based case that declared no do-nothing invocation. */
+    readonly needsBaselineArgs?: boolean;
+};
+/**
+ * Surfaces conditions that make a number untrustworthy.
+ *
+ * Reporting a tidy median while the machine was busy is worse than reporting
+ * nothing, because it looks authoritative.
+ */
+export declare function detectWarnings_(input: DetectWarningsInput): DurationBenchWarning[];
+//# sourceMappingURL=_warnings.d.ts.map

package/dist/_warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_warnings.d.ts","sourceRoot":"","sources":["../src/_warnings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,EAEN,eAAe,EACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAEN,mBAAmB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAc7D,0DAA0D;AAC1D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;EAYzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,8BAA8B,CACrC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;iBAKrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,MAAM,mBAAmB,GAAG;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpD,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACrC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,mBAAmB,GACxB,oBAAoB,EAAE,CAwHxB"}