benchforge 0.1.11 → 0.2.4

package/dist/BenchMatrix-BZVrBB_h.mjs

@@ -0,0 +1,1050 @@
+import { g as percentile, i as coefficientOfVariation, m as medianAbsoluteDeviation, p as median, t as average } from "./StatisticalUtils-BD92crgM.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { fork } from "node:child_process";
+import { getHeapStatistics } from "node:v8";
+//#region src/matrix/CaseLoader.ts
+/** Import and validate a cases module, which must export a `cases` array */
+async function loadCasesModule(moduleUrl) {
+	const module = await import(moduleUrl);
+	if (!Array.isArray(module.cases)) throw new Error(`Cases module at ${moduleUrl} must export 'cases' array`);
+	return {
+		cases: module.cases,
+		defaultCases: module.defaultCases,
+		defaultVariants: module.defaultVariants,
+		loadCase: module.loadCase
+	};
+}
+/** Load case data from a CasesModule, or use the caseId as data if no module */
+async function loadCaseData(casesModule, caseId) {
+	if (casesModule?.loadCase) return casesModule.loadCase(caseId);
+	return { data: caseId };
+}
+//#endregion
+//#region src/runners/MeasuredResults.ts
+/**
+* V8 GetOptimizationStatus() return codes ==> human-readable tier names.
+*   Bit 0 (1): is_function
+*   Bit 4 (16): is_optimized (TurboFan)
+*   Bit 5 (32): is_optimized (Maglev)
+*   Bit 7 (128): is_baseline (Sparkplug)
+*   Bit 3 (8): maybe_deoptimized
+*/
+const optStatusNames = {
+	1: "interpreted",
+	129: "sparkplug",
+	17: "turbofan",
+	33: "maglev",
+	49: "turbofan+maglev",
+	32769: "optimized"
+};
+//#endregion
+//#region src/runners/SampleStats.ts
+/** Compute percentiles, CV, MAD, and outlier rate from timing samples. */
+function computeStats(samples) {
+	let min = Number.POSITIVE_INFINITY;
+	let max = Number.NEGATIVE_INFINITY;
+	let sum = 0;
+	for (const s of samples) {
+		if (s < min) min = s;
+		if (s > max) max = s;
+		sum += s;
+	}
+	const sorted = [...samples].sort((a, b) => a - b);
+	const pct = (p) => sorted[Math.max(0, Math.ceil(sorted.length * p) - 1)];
+	return {
+		min,
+		max,
+		avg: sum / samples.length,
+		p25: pct(.25),
+		p50: pct(.5),
+		p75: pct(.75),
+		p95: pct(.95),
+		p99: pct(.99),
+		p999: pct(.999),
+		cv: coefficientOfVariation(samples),
+		mad: medianAbsoluteDeviation(samples),
+		outlierRate: outlierImpactRatio(samples)
+	};
+}
+/** Measure outlier impact as proportion of excess time above 1.5*IQR threshold. */
+function outlierImpactRatio(samples) {
+	if (samples.length === 0) return 0;
+	const med = median(samples);
+	const threshold = med + 1.5 * (percentile(samples, .75) - med);
+	let excessTime = 0;
+	for (const sample of samples) if (sample > threshold) excessTime += sample - med;
+	const total = samples.reduce((a, b) => a + b, 0);
+	return total > 0 ? excessTime / total : 0;
+}
+/** Group samples by V8 optimization tier and count deopts. */
+function analyzeOptStatus(samples, statuses) {
+	if (statuses.length === 0 || statuses[0] === void 0) return void 0;
+	const byStatus = /* @__PURE__ */ new Map();
+	let deoptCount = 0;
+	for (let i = 0; i < samples.length; i++) {
+		const status = statuses[i];
+		if (status === void 0) continue;
+		if (status & 8) deoptCount++;
+		const group = byStatus.get(status);
+		if (group) group.push(samples[i]);
+		else byStatus.set(status, [samples[i]]);
+	}
+	const entries = [...byStatus].map(([status, times]) => {
+		return [optStatusNames[status] || `status=${status}`, {
+			count: times.length,
+			medianMs: median(times)
+		}];
+	});
+	return {
+		byTier: Object.fromEntries(entries),
+		deoptCount
+	};
+}
+/** @return runtime gc() function, or a no-op if --expose-gc wasn't passed. */
+function gcFunction() {
+	const gc = globalThis.gc ?? globalThis.__gc;
+	if (gc) return gc;
+	console.warn("gc() not available, run node/bun with --expose-gc");
+	return () => {};
+}
+/** @return function that reads V8 optimization status via %GetOptimizationStatus. */
+function createOptStatusGetter() {
+	try {
+		const fn = new Function("f", "return %GetOptimizationStatus(f)");
+		fn(() => {});
+		return fn;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/runners/MergeBatches.ts
+/** Merge multiple batch results, concatenating samples and tracking batch boundaries. */
+function mergeBatchResults(results) {
+	if (results.length === 0) throw new Error("Cannot merge empty results array");
+	if (results.length === 1) return {
+		...results[0],
+		batchOffsets: [0]
+	};
+	const allSamples = results.flatMap((r) => r.samples);
+	const time = computeStats(allSamples);
+	const batchOffsets = [];
+	const offsetPauses = [];
+	let offset = 0;
+	for (const r of results) {
+		batchOffsets.push(offset);
+		for (const p of r.pausePoints ?? []) {
+			const sampleIndex = p.sampleIndex + offset;
+			offsetPauses.push({
+				sampleIndex,
+				durationMs: p.durationMs
+			});
+		}
+		offset += r.samples.length;
+	}
+	return {
+		...results[results.length - 1],
+		name: results[0].name,
+		samples: allSamples,
+		warmupSamples: concatOptional(results, (r) => r.warmupSamples),
+		allocationSamples: concatOptional(results, (r) => r.allocationSamples),
+		heapSamples: concatOptional(results, (r) => r.heapSamples),
+		optSamples: concatOptional(results, (r) => r.optSamples),
+		time,
+		startTime: results[0].startTime,
+		totalTime: results.reduce((sum, r) => sum + (r.totalTime || 0), 0),
+		pausePoints: offsetPauses.length ? offsetPauses : void 0,
+		batchOffsets,
+		gcStats: mergeGcStats(results)
+	};
+}
+/** Sum GcStats across batches, or undefined if none collected. */
+function mergeGcStats(results) {
+	const stats = results.map((r) => r.gcStats).filter(Boolean);
+	if (!stats.length) return void 0;
+	const sum = (fn) => stats.reduce((acc, s) => acc + (fn(s) ?? 0), 0);
+	return {
+		scavenges: sum((s) => s.scavenges),
+		markCompacts: sum((s) => s.markCompacts),
+		totalCollected: sum((s) => s.totalCollected),
+		gcPauseTime: sum((s) => s.gcPauseTime),
+		totalAllocated: sum((s) => s.totalAllocated) || void 0,
+		totalPromoted: sum((s) => s.totalPromoted) || void 0,
+		totalSurvived: sum((s) => s.totalSurvived) || void 0
+	};
+}
+/** Run N benchmarks + optional baseline in batched alternation, merge results. */
+async function runBatched(runners, baseline, batches, warmupBatch = false, onProgress) {
+	const runnerBatches = runners.map(() => []);
+	const baselineBatches = [];
+	const start = performance.now();
+	const report = (batch, label) => onProgress?.({
+		batch,
+		batches,
+		label,
+		elapsed: performance.now() - start
+	});
+	for (let i = 0; i < batches; i++) {
+		const reverse = i % 2 === 1;
+		if (!reverse && baseline) {
+			baselineBatches.push(await baseline());
+			report(i, "baseline");
+		}
+		for (let j = 0; j < runners.length; j++) {
+			runnerBatches[j].push(await runners[j]());
+			report(i, "current");
+		}
+		if (reverse && baseline) {
+			baselineBatches.push(await baseline());
+			report(i, "baseline");
+		}
+	}
+	if (!warmupBatch && batches > 1) {
+		for (const b of runnerBatches) b.shift();
+		baselineBatches.shift();
+	}
+	return {
+		results: runnerBatches.map((b) => mergeBatchResults(b)),
+		baseline: baselineBatches.length ? mergeBatchResults(baselineBatches) : void 0
+	};
+}
+/** Concat optional number arrays across batches. */
+function concatOptional(results, fn) {
+	const all = results.flatMap((r) => fn(r) || []);
+	return all.length ? all : void 0;
+}
+//#endregion
+//#region src/runners/GcStats.ts
+/** Parse a single --trace-gc-nvp stderr line into a GcEvent. */
+function parseGcLine(line) {
+	if (!line.includes("pause=")) return void 0;
+	const fields = parseNvpFields(line);
+	if (!fields.gc) return void 0;
+	const intField = (name) => Number.parseInt(fields[name] || "0", 10);
+	const type = parseGcType(fields.gc);
+	const pauseMs = Number.parseFloat(fields.pause || "0");
+	if (Number.isNaN(pauseMs)) return void 0;
+	const allocated = intField("allocated");
+	const promoted = intField("promoted");
+	const survived = intField("new_space_survived") || intField("survived");
+	const start = intField("start_object_size");
+	const end = intField("end_object_size");
+	return {
+		type,
+		pauseMs,
+		allocated,
+		collected: start > end ? start - end : 0,
+		promoted,
+		survived
+	};
+}
+/** Aggregate a list of GC events into summary statistics. */
+function aggregateGcStats(events) {
+	let scavenges = 0;
+	let markCompacts = 0;
+	let gcPauseTime = 0;
+	let totalCollected = 0;
+	let hasNode = false;
+	let totalAllocated = 0;
+	let totalPromoted = 0;
+	let totalSurvived = 0;
+	for (const event of events) {
+		if (event.type === "scavenge" || event.type === "minor-ms") scavenges++;
+		else if (event.type === "mark-compact") markCompacts++;
+		gcPauseTime += event.pauseMs;
+		totalCollected += event.collected;
+		if (event.allocated != null) {
+			hasNode = true;
+			totalAllocated += event.allocated;
+			totalPromoted += event.promoted ?? 0;
+			totalSurvived += event.survived ?? 0;
+		}
+	}
+	return {
+		scavenges,
+		markCompacts,
+		totalCollected,
+		gcPauseTime,
+		...hasNode && {
+			totalAllocated,
+			totalPromoted,
+			totalSurvived
+		}
+	};
+}
+/** Parse name=value pairs from a trace-gc-nvp line. */
+function parseNvpFields(line) {
+	const pairs = [...line.matchAll(/(\w+)=([^\s,]+)/g)];
+	return Object.fromEntries(pairs.map(([, key, value]) => [key, value]));
+}
+/** Map V8 gc type codes to normalized event types. */
+function parseGcType(gcField) {
+	if (gcField === "s" || gcField === "scavenge") return "scavenge";
+	if (gcField === "mc" || gcField === "ms" || gcField === "mark-compact") return "mark-compact";
+	if (gcField === "mmc" || gcField === "minor-mc" || gcField === "minor-ms") return "minor-ms";
+	return "unknown";
+}
+//#endregion
+//#region src/matrix/VariantLoader.ts
+/** List variant IDs by scanning .ts files in a directory */
+async function discoverVariants(dirUrl) {
+	const dirPath = fileURLToPath(dirUrl);
+	return (await fs.readdir(dirPath, { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".ts")).map((e) => e.name.slice(0, -3)).sort();
+}
+/** Import a variant module and return its run/setup exports as a Variant */
+async function loadVariant(dirUrl, variantId) {
+	const moduleUrl = variantModuleUrl(dirUrl, variantId);
+	return extractVariant(await import(moduleUrl), variantId, moduleUrl);
+}
+/** Resolve the import URL for a variant file */
+function variantModuleUrl(dirUrl, variantId) {
+	return new URL(`${variantId}.ts`, dirUrl).href;
+}
+/** Validate and extract a Variant from a module's exports */
+function extractVariant(module, variantId, moduleUrl) {
+	const { setup, run } = module;
+	const loc = `Variant '${variantId}' at ${moduleUrl}`;
+	if (typeof run !== "function") throw new Error(`${loc} must export 'run'`);
+	if (setup === void 0) return run;
+	if (typeof setup !== "function") throw new Error(`${loc}: 'setup' must be a function`);
+	return {
+		setup,
+		run
+	};
+}
+//#endregion
+//#region src/runners/AdaptiveWrapper.ts
+const minTime = 1e3;
+const maxTime = 1e4;
+const targetConfidence = 95;
+const fallbackThreshold = 80;
+const windowSize = 50;
+const stability = .05;
+const initialBatch = 100;
+const continueBatch = 100;
+const continueIterations = 10;
+/** Wrap a runner with adaptive sampling (convergence detection or timeout). */
+function createAdaptiveWrapper(baseRunner, options) {
+	return { async runBench(bench, opts, params) {
+		return runAdaptiveBench(baseRunner, bench, opts, options, params);
+	} };
+}
+/** Check convergence by comparing sliding windows of samples for stability. */
+function checkConvergence(samples) {
+	const windowSize = getWindowSize(samples);
+	const minSamples = windowSize * 2;
+	if (samples.length < minSamples) return {
+		converged: false,
+		confidence: samples.length / minSamples * 100,
+		reason: `Collecting samples: ${samples.length}/${minSamples}`
+	};
+	return buildConvergence(getStability(samples, windowSize));
+}
+/** Run benchmark with adaptive sampling until convergence or timeout. */
+async function runAdaptiveBench(runner, bench, opts, adaptive, params) {
+	const overrides = opts;
+	const min = overrides.minTime ?? adaptive.minTime ?? minTime;
+	const max = overrides.maxTime ?? adaptive.maxTime ?? maxTime;
+	const target = overrides.convergence ?? adaptive.convergence ?? targetConfidence;
+	const allSamples = [];
+	const { warmup, startTime: hrtimeStart } = await collectInitial(runner, bench, opts, params, allSamples);
+	const startTime = performance.now();
+	await collectAdaptive(runner, bench, opts, params, allSamples, {
+		minTime: min,
+		maxTime: max,
+		targetConfidence: target,
+		startTime
+	});
+	return buildResults(allSamples, startTime, checkConvergence(allSamples.map((s) => s * msToNs)), bench.name, warmup, hrtimeStart);
+}
+/** Scale window size inversely with execution time -- fast ops need more samples. */
+function getWindowSize(samples) {
+	if (samples.length < 20) return windowSize;
+	const recentMedian = median(samples.slice(-20).map((s) => s / msToNs));
+	if (recentMedian < .01) return 200;
+	if (recentMedian < .1) return 100;
+	if (recentMedian < 1) return 50;
+	if (recentMedian < 10) return 30;
+	return 20;
+}
+/** Convert stability metrics to a convergence result with confidence score. */
+function buildConvergence(metrics) {
+	const { medianDrift, impactDrift, medianStable, impactStable } = metrics;
+	if (medianStable && impactStable) return {
+		converged: true,
+		confidence: 100,
+		reason: "Stable performance pattern"
+	};
+	const raw = (1 - medianDrift / stability) * 50 + (1 - impactDrift / stability) * 50;
+	return {
+		converged: false,
+		confidence: Math.max(0, Math.min(100, raw)),
+		reason: medianDrift > impactDrift ? `Median drifting: ${(medianDrift * 100).toFixed(1)}%` : `Outlier impact changing: ${(impactDrift * 100).toFixed(1)}%`
+	};
+}
+/** Compare median and outlier-impact drift between recent and previous windows. */
+function getStability(samples, windowSize) {
+	const toMs = (s) => s / msToNs;
+	const recentMs = samples.slice(-windowSize).map(toMs);
+	const previousMs = samples.slice(-windowSize * 2, -windowSize).map(toMs);
+	const medianRecent = median(recentMs);
+	const medianPrevious = median(previousMs);
+	const medianDrift = Math.abs(medianRecent - medianPrevious) / medianPrevious;
+	const impactRecent = outlierImpactRatio(recentMs);
+	const impactPrevious = outlierImpactRatio(previousMs);
+	const impactDrift = Math.abs(impactRecent - impactPrevious);
+	return {
+		medianDrift,
+		impactDrift,
+		medianStable: medianDrift < stability,
+		impactStable: impactDrift < stability
+	};
+}
+/** Collect the initial batch (warmup + settle), returning warmup samples. */
+async function collectInitial(runner, bench, opts, params, allSamples) {
+	const batchOpts = {
+		...opts,
+		maxTime: initialBatch,
+		maxIterations: void 0
+	};
+	const results = await runner.runBench(bench, batchOpts, params);
+	appendSamples(results[0], allSamples);
+	return {
+		warmup: results[0].warmupSamples,
+		startTime: results[0].startTime
+	};
+}
+/** Collect batches until convergence or timeout, with progress logging. */
+async function collectAdaptive(runner, bench, opts, params, allSamples, limits) {
+	const { minTime, maxTime, targetConfidence, startTime } = limits;
+	let lastLog = 0;
+	while (performance.now() - startTime < maxTime) {
+		const convergence = checkConvergence(allSamples.map((s) => s * msToNs));
+		const elapsed = performance.now() - startTime;
+		lastLog = logProgress(bench.name, convergence, elapsed, lastLog);
+		if (shouldStop(convergence, targetConfidence, elapsed, minTime)) break;
+		const batch = {
+			...opts,
+			maxTime: continueBatch,
+			maxIterations: continueIterations,
+			skipWarmup: true
+		};
+		appendSamples((await runner.runBench(bench, batch, params))[0], allSamples);
+	}
+	process.stderr.write("\r" + " ".repeat(60) + "\r");
+}
+/** Build final MeasuredResults from collected samples and convergence state. */
+function buildResults(samples, elapsedStart, convergence, name, warmupSamples, startTime) {
+	const totalTime = (performance.now() - elapsedStart) / 1e3;
+	return [{
+		name,
+		samples,
+		warmupSamples,
+		time: computeStats(samples),
+		totalTime,
+		startTime,
+		convergence
+	}];
+}
+/** Append samples one-by-one to avoid stack overflow from spread on large arrays. */
+function appendSamples(result, samples) {
+	if (!result.samples?.length) return;
+	for (const sample of result.samples) samples.push(sample);
+}
+/** Log adaptive sampling progress at ~1s intervals. */
+function logProgress(name, convergence, elapsed, lastLog) {
+	if (elapsed - lastLog <= 1e3) return lastLog;
+	const sec = (elapsed / 1e3).toFixed(1);
+	const conf = convergence.confidence.toFixed(0);
+	process.stderr.write(`\r◊ ${name}: ${conf}% confident (${sec}s)   `);
+	return elapsed;
+}
+/** @return true if convergence target met, or minTime elapsed with fallback confidence. */
+function shouldStop(convergence, target, elapsed, minElapsed) {
+	if (convergence.converged && convergence.confidence >= target) return true;
+	return elapsed >= minElapsed && convergence.confidence >= Math.max(target, fallbackThreshold);
+}
+//#endregion
+//#region src/runners/BenchRunner.ts
+/** Invoke the benchmark function, forwarding setup params. */
+function executeBenchmark(benchmark, params) {
+	benchmark.fn(params);
+}
+//#endregion
+//#region src/runners/TimingRunner.ts
+const defaultCollectOptions = {
+	maxTime: 5e3,
+	maxIterations: 1e6,
+	warmup: 0,
+	traceOpt: false,
+	pauseWarmup: 0
+};
+/**
+* Timing-based runner that collects samples within time/iteration limits.
+* Handles warmup, heap tracking, V8 optimization tracing, and periodic pauses.
+*/
+var TimingRunner = class {
+	async runBench(benchmark, options, params) {
+		const collected = await collectSamples({
+			benchmark,
+			params,
+			...defaultCollectOptions,
+			...options
+		});
+		return [buildMeasuredResults(benchmark.name, collected)];
+	}
+};
+/** Collect timing samples with warmup, heap tracking, and optional V8 opt tracing. */
+async function collectSamples(config) {
+	if (!config.maxIterations && !config.maxTime) throw new Error(`At least one of maxIterations or maxTime must be set`);
+	const warmupSamples = config.skipWarmup ? [] : await runWarmup(config);
+	const heapBefore = process.memoryUsage().heapUsed;
+	const { samples, heapSamples, optStatuses, pausePoints, startTime } = await runSampleLoop(config);
+	if (samples.length === 0) throw new Error(`No samples collected for benchmark: ${config.benchmark.name}`);
+	const heapAfter = process.memoryUsage().heapUsed;
+	return {
+		samples,
+		warmupSamples,
+		heapGrowth: Math.max(0, heapAfter - heapBefore) / 1024 / samples.length,
+		heapSamples,
+		startTime,
+		optStatus: config.traceOpt ? analyzeOptStatus(samples, optStatuses) : void 0,
+		optSamples: config.traceOpt && optStatuses.length > 0 ? optStatuses : void 0,
+		pausePoints
+	};
+}
+/** Assemble CollectResult into a MeasuredResults record. */
+function buildMeasuredResults(name, collected) {
+	const { samples, warmupSamples, heapSamples } = collected;
+	const { optStatus, optSamples, pausePoints, heapGrowth, startTime } = collected;
+	return {
+		name,
+		samples,
+		warmupSamples,
+		heapSamples,
+		time: computeStats(samples),
+		heapSize: {
+			avg: heapGrowth,
+			min: heapGrowth,
+			max: heapGrowth
+		},
+		startTime,
+		optStatus,
+		optSamples,
+		pausePoints
+	};
+}
+/**
+* Run warmup iterations with gc + settle time for V8 optimization. Returns warmup timings.
+*
+* V8 has 4 compilation tiers: Ignition (interpreter) ==> Sparkplug (baseline) ==>
+* Maglev (mid-tier optimizer) ==> TurboFan (full optimizer). Tiering thresholds:
+*   - Ignition ==> Sparkplug: 8 invocations
+*   - Sparkplug ==> Maglev: 500 invocations
+*   - Maglev ==> TurboFan: 6000 invocations
+*
+* Optimization compilation happens on background threads and requires idle time
+* on the main thread to complete. Without sufficient warmup + settle time,
+* benchmarks exhibit bimodal timing: slow Sparkplug samples (~30% slower) mixed
+* with fast optimized samples.
+*
+* The warmup iterations trigger the optimization decision, then settle time
+* provides idle time for background compilation to finish before measurement.
+*
+* @see https://v8.dev/blog/sparkplug
+* @see https://v8.dev/blog/maglev
+* @see https://v8.dev/blog/background-compilation
+*/
+async function runWarmup(config) {
+	const gc = gcFunction();
+	const samples = new Array(config.warmup);
+	for (let i = 0; i < config.warmup; i++) {
+		const start = performance.now();
+		executeBenchmark(config.benchmark, config.params);
+		samples[i] = performance.now() - start;
+	}
+	gc();
+	if (config.pauseWarmup) {
+		await new Promise((r) => setTimeout(r, config.pauseWarmup));
+		gc();
+	}
+	return samples;
+}
+/** Collect timing samples with optional periodic pauses for V8 background compilation to complete. */
+async function runSampleLoop(config) {
+	const { maxTime, maxIterations, pauseFirst } = config;
+	const { pauseInterval = 0, pauseDuration = 100 } = config;
+	const getOptStatus = config.traceOpt ? createOptStatusGetter() : void 0;
+	const trackOpt = !!getOptStatus;
+	const arrays = createSampleArrays(maxIterations || Math.ceil(maxTime / .1), trackOpt);
+	let count = 0;
+	let elapsed = 0;
+	let totalPauseTime = 0;
+	const startTime = Number(process.hrtime.bigint() / 1000n);
+	const loopStart = performance.now();
+	while ((!maxIterations || count < maxIterations) && (!maxTime || elapsed < maxTime)) {
+		const start = performance.now();
+		executeBenchmark(config.benchmark, config.params);
+		const end = performance.now();
+		arrays.samples[count] = end - start;
+		arrays.heapSamples[count] = getHeapStatistics().used_heap_size;
+		if (getOptStatus) arrays.optStatuses[count] = getOptStatus(config.benchmark.fn);
+		count++;
+		if (shouldPause(count, pauseFirst, pauseInterval)) {
+			const sampleIndex = count - 1;
+			arrays.pausePoints.push({
+				sampleIndex,
+				durationMs: pauseDuration
+			});
+			const pauseStart = performance.now();
+			await new Promise((r) => setTimeout(r, pauseDuration));
+			totalPauseTime += performance.now() - pauseStart;
+		}
+		elapsed = performance.now() - loopStart - totalPauseTime;
+	}
+	trimArrays(arrays, count, trackOpt);
+	return {
+		...arrays,
+		startTime
+	};
+}
+/** Pre-allocate sample arrays to reduce GC pressure during measurement. */
+function createSampleArrays(n, trackOpt) {
+	const arr = () => new Array(n);
+	return {
+		samples: arr(),
+		heapSamples: arr(),
+		optStatuses: trackOpt ? arr() : [],
+		pausePoints: []
+	};
+}
+/** @return true if this iteration should pause for V8 background compilation. */
+function shouldPause(iter, first, interval) {
+	if (first !== void 0 && iter === first) return true;
+	if (interval <= 0) return false;
+	if (first === void 0) return iter % interval === 0;
+	return (iter - first) % interval === 0;
+}
+/** Trim pre-allocated arrays to the actual sample count. */
+function trimArrays(arrays, count, trackOpt) {
+	arrays.samples.length = arrays.heapSamples.length = count;
+	if (trackOpt) arrays.optStatuses.length = count;
+}
+//#endregion
+//#region src/runners/CreateRunner.ts
+/** Create a benchmark runner by name. */
+async function createRunner(_name) {
+	return new TimingRunner();
+}
+//#endregion
+//#region src/runners/RunnerUtils.ts
+const msToNs = 1e6;
+/** Get named or default export from module, throw if not a function */
+function getModuleExport(module, exportName, modulePath) {
+	const fn = exportName ? module[exportName] : module.default || module;
+	if (typeof fn !== "function") throw new Error(`Export '${exportName || "default"}' from ${modulePath} is not a function`);
+	return fn;
+}
+/** Import a benchmark function from a module, optionally running a setup export */
+async function importBenchFn(modulePath, exportName, setupExportName, params) {
+	const module = await import(modulePath);
+	const fn = getModuleExport(module, exportName, modulePath);
+	if (!setupExportName) return {
+		fn,
+		params
+	};
+	return {
+		fn,
+		params: await getModuleExport(module, setupExportName, modulePath)(params)
+	};
+}
+/** Resolve a matrix variant to a benchmark function (shared by orchestrator and worker). */
+async function resolveVariantFn(params) {
+	let { caseData } = params;
+	if (params.casesModule && params.caseId) caseData = (await loadCaseData(await loadCasesModule(params.casesModule), params.caseId)).data;
+	return {
+		fn: await prepareBenchFn(await loadVariant(params.variantDir, params.variantId), caseData),
+		params: void 0
+	};
+}
+/** Create runner, wrapping with adaptive sampling if options.adaptive is set */
+async function createBenchRunner(runnerName, options) {
+	const base = await createRunner(runnerName);
+	if ("adaptive" in options && options.adaptive) return createAdaptiveWrapper(base, options);
+	return base;
+}
+//#endregion
+//#region src/runners/TimingUtils.ts
+/** Current time in ms, or 0 when debug timing is off (zero-cost no-op) */
+function getPerfNow() {
+	return 0;
+}
+/** Elapsed ms between marks, or 0 when debug timing is off */
+function getElapsed(startMark, endMark) {
+	return 0;
+}
+//#endregion
+//#region src/runners/RunnerOrchestrator.ts
+const logTiming = () => {};
+/** Run a benchmark spec, optionally in an isolated worker process for profiling support. */
+async function runBenchmark({ spec, runner, options, useWorker = false, params }) {
+	if (!useWorker) {
+		const resolved = spec.modulePath ? await resolveModuleSpec(spec, params) : {
+			spec,
+			params
+		};
+		return (await createBenchRunner(runner, options)).runBench(resolved.spec, options, resolved.params);
+	}
+	const msg = createRunMessage(spec, runner, options, params);
+	return runWorkerWithMessage(spec.name, options, msg);
+}
+/** Run a matrix variant benchmark, directly or in a worker. */
+async function runMatrixVariant(params) {
+	const { variantId, caseId, runner, options, useWorker = true } = params;
+	const name = `${variantId}/${caseId}`;
+	if (!useWorker) return runMatrixVariantDirect(params, name);
+	const { variantDir, caseData, casesModule } = params;
+	return runWorkerWithMessage(name, options, {
+		type: "run",
+		spec: { name },
+		runnerName: runner,
+		options,
+		variantDir,
+		variantId,
+		caseId,
+		caseData,
+		casesModule
+	});
+}
+/** Resolve modulePath/exportName to a real function for non-worker mode */
+async function resolveModuleSpec(spec, params) {
+	const { modulePath, exportName, setupExportName } = spec;
+	const imported = await importBenchFn(modulePath, exportName, setupExportName, params);
+	const fn = imported.fn;
+	return {
+		spec: {
+			...spec,
+			fn
+		},
+		params: imported.params
+	};
+}
+/** Serialize a BenchmarkSpec into a worker-safe message (modulePath or fnCode) */
+function createRunMessage(spec, runnerName, options, params) {
+	const { fn, ...rest } = spec;
+	const message = {
+		type: "run",
+		spec: rest,
+		runnerName,
+		options,
+		params
+	};
+	if (spec.modulePath) {
+		message.modulePath = spec.modulePath;
+		message.exportName = spec.exportName;
+		if (spec.setupExportName) message.setupExportName = spec.setupExportName;
+	} else message.fnCode = fn.toString();
+	return message;
+}
+/** Run a benchmark in an isolated worker process with timeout and GC capture. */
+function runWorkerWithMessage(name, options, message) {
+	const startTime = getPerfNow();
+	const collectGcStats = options.gcStats ?? false;
+	logTiming(`Starting worker for ${name}`);
+	return new Promise((resolve, reject) => {
+		const gcEvents = [];
+		const worker = spawnWorkerProcess(collectGcStats);
+		if (collectGcStats && worker.stdout) setupGcCapture(worker, gcEvents);
+		const timeoutId = setTimeout(() => {
+			killWorker();
+			reject(/* @__PURE__ */ new Error(`Benchmark "${name}" timed out after 60 seconds`));
+		}, 6e4);
+		function killWorker() {
+			clearTimeout(timeoutId);
+			if (!worker.killed) worker.kill("SIGTERM");
+		}
+		worker.on("message", (msg) => {
+			killWorker();
+			if (msg.type === "error") {
+				const error = /* @__PURE__ */ new Error(`Benchmark "${name}" failed: ${msg.error}`);
+				if (msg.stack) error.stack = msg.stack;
+				return reject(error);
+			}
+			logTiming(`Total worker time for ${name}: ${getElapsed(startTime).toFixed(1)}ms`);
+			const { results, heapProfile, timeProfile, coverage } = msg;
+			attachProfilingData(results, gcEvents, heapProfile, timeProfile, coverage);
+			resolve(results);
+		});
+		worker.on("error", (error) => {
+			killWorker();
+			const msg = `Worker process failed for "${name}": ${error.message}`;
+			reject(new Error(msg));
+		});
+		worker.on("exit", (code) => {
+			if (code !== 0 && code !== null) {
+				killWorker();
+				reject(/* @__PURE__ */ new Error(`Worker exited with code ${code} for "${name}"`));
+			}
+		});
+		worker.send(message);
+	});
+}
+/** Run matrix variant in-process (no worker isolation) */
+async function runMatrixVariantDirect(params, name) {
+	const { runner, options } = params;
+	const { fn } = await resolveVariantFn(params);
+	return (await createBenchRunner(runner, options)).runBench({
+		name,
+		fn
+	}, options);
+}
+/** Spawn worker process with V8 flags */
+function spawnWorkerProcess(gcStats) {
+	const workerPath = resolveWorkerPath();
+	const execArgv = ["--expose-gc", "--allow-natives-syntax"];
+	if (gcStats) execArgv.push("--trace-gc-nvp");
+	return fork(workerPath, [], {
+		execArgv,
+		silent: gcStats,
+		env: {
+			...process.env,
+			NODE_OPTIONS: ""
+		},
+		serialization: "advanced"
+	});
+}
+/** Capture and parse GC lines from worker stdout (--trace-gc-nvp). */
+function setupGcCapture(worker, gcEvents) {
+	let buffer = "";
+	worker.stdout.on("data", (data) => {
+		buffer += data.toString();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() || "";
+		for (const line of lines) {
+			const event = parseGcLine(line);
+			if (event) gcEvents.push(event);
+			else if (line.trim()) process.stdout.write(line + "\n");
+		}
+	});
+}
+/** Attach profiling data collected by the worker to each result. */
+function attachProfilingData(results, gcEvents, heapProfile, timeProfile, coverage) {
+	const gcStats = gcEvents?.length ? aggregateGcStats(gcEvents) : void 0;
+	const attach = (key, value) => {
+		if (value) for (const r of results) r[key] = value;
+	};
+	attach("gcStats", gcStats);
+	attach("heapProfile", heapProfile);
+	attach("timeProfile", timeProfile);
+	attach("coverage", coverage);
+}
+/** Resolve WorkerScript path for dev (.ts) or dist (.mjs) */
+function resolveWorkerPath() {
+	const dir = import.meta.dirname;
+	const tsPath = path.join(dir, "WorkerScript.ts");
+	if (existsSync(tsPath)) return tsPath;
+	return path.join(dir, "runners", "WorkerScript.mjs");
+}
+//#endregion
+//#region src/matrix/MatrixDirRunner.ts
+/** Run matrix using variant files from a directory, each in a worker process */
+async function runMatrixWithDir(matrix, options) {
+	const allVariantIds = await discoverVariants(matrix.variantDir);
+	if (allVariantIds.length === 0) throw new Error(`No variants found in ${matrix.variantDir}`);
+	const variants = await runDirVariants(options.filteredVariants ?? allVariantIds, await createDirContext(matrix, options));
+	return {
+		name: matrix.name,
+		variants
+	};
+}
+/** Create context for directory-based matrix execution */
+async function createDirContext(matrix, options) {
+	const baselineIds = matrix.baselineDir ? await discoverVariants(matrix.baselineDir) : [];
+	const { casesModule, caseIds } = await resolveCases(matrix, options);
+	const runnerOpts = buildRunnerOptions(options);
+	const { batches = 1, warmupBatch = false, useWorker = true } = options;
+	return {
+		matrix,
+		casesModule,
+		baselineIds,
+		caseIds,
+		runnerOpts,
+		batches,
+		warmupBatch,
+		useWorker
+	};
+}
+/** Run all variants sequentially, collecting per-case results */
+async function runDirVariants(variantIds, ctx) {
+	const variants = [];
+	for (const id of variantIds) {
+		const cases = await runDirVariantCases(id, ctx);
+		variants.push({
+			id,
+			cases
+		});
+	}
+	return variants;
+}
+/** Run all cases for a single variant */
+async function runDirVariantCases(variantId, ctx) {
+	const { matrix, casesModule, caseIds, runnerOpts, batches } = ctx;
+	const cases = [];
+	for (const caseId of caseIds) {
+		const caseData = matrix.cases && !matrix.casesModule ? caseId : void 0;
+		const variantArgs = {
+			variantDir: matrix.variantDir,
+			variantId,
+			caseId,
+			caseData,
+			casesModule: matrix.casesModule,
+			runner: "timing",
+			options: runnerOpts,
+			useWorker: ctx.useWorker
+		};
+		const baselineArgs = matrix.baselineDir && ctx.baselineIds.includes(variantId) ? {
+			...variantArgs,
+			variantDir: matrix.baselineDir
+		} : void 0;
+		const { metadata } = await loadCaseData(casesModule, caseId);
+		const { measured, baseline } = batches > 1 ? await runCaseBatched(variantArgs, baselineArgs, ctx) : await runCaseSingle(variantArgs, baselineArgs);
+		const deltaPercent = baseline ? computeDeltaPercent(baseline, measured) : void 0;
+		cases.push({
+			caseId,
+			measured,
+			metadata,
+			baseline,
+			deltaPercent
+		});
+	}
+	return cases;
+}
+/** Run a batched measurement for a case, alternating current/baseline order. */
+async function runCaseBatched(variantArgs, baselineArgs, ctx) {
+	const runCurrent = async () => (await runMatrixVariant(variantArgs))[0];
+	const { results, baseline } = await runBatched([runCurrent], baselineArgs ? async () => (await runMatrixVariant(baselineArgs))[0] : void 0, ctx.batches, ctx.warmupBatch);
+	return {
+		measured: results[0],
+		baseline
+	};
+}
+/** Run a single unbatched measurement for a case. */
+async function runCaseSingle(variantArgs, baselineArgs) {
+	const [measured] = await runMatrixVariant(variantArgs);
+	return {
+		measured,
+		baseline: baselineArgs ? (await runMatrixVariant(baselineArgs))[0] : void 0
+	};
+}
+//#endregion
+//#region src/matrix/MatrixInlineRunner.ts
+/** Run matrix with in-memory variant functions (no worker isolation) */
+async function runMatrixInline(matrix, options) {
+	if (matrix.baselineDir) throw new Error("BenchMatrix with inline 'variants' cannot use 'baselineDir'. Use 'variantDir' instead.");
+	const { casesModule, caseIds } = await resolveCases(matrix, options);
+	const runner = new TimingRunner();
+	const runnerOpts = buildRunnerOptions(options);
+	const allEntries = Object.entries(matrix.variants);
+	const { filteredVariants } = options;
+	const variantEntries = filteredVariants ? allEntries.filter(([id]) => filteredVariants.includes(id)) : allEntries;
+	const variants = [];
+	for (const [variantId, variant] of variantEntries) {
+		const cases = [];
+		for (const caseId of caseIds) {
+			const loaded = await loadCaseData(casesModule, caseId);
+			const spec = {
+				name: variantId,
+				fn: await prepareBenchFn(variant, casesModule || matrix.cases ? loaded.data : void 0)
+			};
+			const [measured] = await runner.runBench(spec, runnerOpts);
+			cases.push({
+				caseId,
+				measured,
+				metadata: loaded.metadata
+			});
+		}
+		variants.push({
+			id: variantId,
+			cases
+		});
+	}
+	return {
+		name: matrix.name,
+		variants
+	};
+}
+//#endregion
+//#region src/matrix/BenchMatrix.ts
+/** Run a BenchMatrix with inline variants or variantDir */
+async function runMatrix(matrix, options = {}) {
+	if (matrix.baselineDir && matrix.baselineVariant) throw new Error("BenchMatrix cannot have both 'baselineDir' and 'baselineVariant'");
+	if (!matrix.variantDir && !matrix.variants) throw new Error("BenchMatrix requires either 'variants' or 'variantDir'");
+	const effectiveOptions = {
+		...matrix.defaults,
+		...options
+	};
+	const result = matrix.variantDir ? await runMatrixWithDir(matrix, effectiveOptions) : await runMatrixInline(matrix, effectiveOptions);
+	if (matrix.baselineVariant) applyBaselineVariant(result.variants, matrix.baselineVariant);
+	return result;
+}
+/** Prepare a benchmark function from a variant, calling setup if stateful. */
+async function prepareBenchFn(variant, data) {
+	if (isStatefulVariant(variant)) {
+		const state = await variant.setup(data);
+		return () => variant.run(state);
+	}
+	return () => variant(data);
+}
+/** Type guard for StatefulVariant */
+function isStatefulVariant(v) {
+	return typeof v === "object" && "setup" in v && "run" in v;
+}
+/** Apply baselineVariant comparison - one variant is the reference for all others */
+function applyBaselineVariant(variants, baselineVariantId) {
+	const baselineVariant = variants.find((v) => v.id === baselineVariantId);
+	if (!baselineVariant) return;
+	const baselineByCase = new Map(baselineVariant.cases.map((c) => [c.caseId, c.measured]));
+	for (const variant of variants) {
+		if (variant.id === baselineVariantId) continue;
+		for (const cr of variant.cases) {
+			const base = baselineByCase.get(cr.caseId);
+			if (base) {
+				cr.baseline = base;
+				cr.deltaPercent = computeDeltaPercent(base, cr.measured);
+			}
+		}
+	}
+}
+/** Load cases module and resolve filtered case IDs */
+async function resolveCases(matrix, options) {
+	const casesModule = matrix.casesModule ? await loadCasesModule(matrix.casesModule) : void 0;
+	const allCaseIds = casesModule?.cases ?? matrix.cases ?? ["default"];
+	return {
+		casesModule,
+		caseIds: options.filteredCases ?? allCaseIds
+	};
+}
+/** Map matrix options to runner options, applying defaults for maxTime and warmup */
+function buildRunnerOptions(opts) {
+	const { filteredCases, filteredVariants, useWorker, batches, warmupBatch, ...base } = opts;
+	const { iterations, maxTime, warmup, ...rest } = base;
+	return {
+		maxIterations: iterations,
+		maxTime: maxTime ?? (iterations ? void 0 : 1e3),
+		warmup: warmup ?? 0,
+		...rest
+	};
+}
+/** Compute percentage change of current vs baseline mean */
+function computeDeltaPercent(base, cur) {
+	const avg = average(base.samples);
+	if (avg === 0) return 0;
+	return (average(cur.samples) - avg) / avg * 100;
+}
+//#endregion
+export { getPerfNow as a, resolveVariantFn as c, mergeGcStats as d, runBatched as f, loadCasesModule as h, getElapsed as i, discoverVariants as l, loadCaseData as m, runMatrix as n, createBenchRunner as o, computeStats as p, runBenchmark as r, importBenchFn as s, isStatefulVariant as t, aggregateGcStats as u };
+
+//# sourceMappingURL=BenchMatrix-BZVrBB_h.mjs.map