@ac-bench/util 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,36 @@
+# @ac-bench/util
+
+The fixtures a benchmark needs before it can measure anything honestly.
+
+Two things go wrong most often. Inputs generated with `Math.random()` differ
+between runs, so two runs are not comparable; and an "optimised" implementation
+that quietly returns the wrong answer wins every benchmark. These helpers
+address both: every generator is seeded, and `checksum` gives you a cheap way to
+assert two implementations agreed.
+
+```ts
+import { checksum, DEFAULT_SEED, randomFloat64Values } from "@ac-bench/util";
+
+// Same values on every run and every machine.
+const values = randomFloat64Values(10_000, DEFAULT_SEED);
+
+const expected = checksum(reference(values));
+// ... assert each candidate reproduces `expected` before trusting its timing.
+```
+
+## What it exposes
+
+- **Seeded workloads** — `randomFloat64Values`, `randomUint32Values`,
+  `randomInts`, `words`, `skewedIndices`, `distinctKeys`, and `DEFAULT_SEED`.
+- **Equivalence** — `checksum`, `sequentialChecksum`, `hashString`,
+  `stringHash32`: order-sensitive digests for proving two implementations
+  produced the same output.
+- **Contention** — `EventLoopLoad`, a controllable background load, for
+  measuring the same operation idle and under pressure.
+- **Native toolchains** — `prepareNativeToolchains`, for suites comparing
+  against a reference implementation in another language.
+
+Generic process helpers (`execAsync`, `hasBinary`, `createTempDir`) are
+`@ac-kit/node`'s — they carry no measurement-specific semantics. Spawn-overhead
+calibration lives with the measure that needs it, in
+`@ac-bench/measure-duration`.

package/dist/event-loop-load.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keeps the event loop busy until stopped.
+ *
+ * Timer benchmarks run on an idle loop measure a best case nobody experiences:
+ * the loop only checks its timer list once per iteration, so lateness is
+ * bounded below by whatever else is already queued. Measuring a condition both
+ * idle and loaded, and comparing the two, shows how much of the result belongs
+ * to the runtime rather than to the timer.
+ */
+export declare class EventLoopLoad {
+    private running;
+    private handle;
+    start(): void;
+    stop(): void;
+    private schedule;
+}
+//# sourceMappingURL=event-loop-load.d.ts.map

package/dist/event-loop-load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop-load.d.ts","sourceRoot":"","sources":["../src/event-loop-load.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAiC;IAE/C,KAAK,IAAI,IAAI,CAMZ;IAED,IAAI,IAAI,IAAI,CAMX;IAED,OAAO,CAAC,QAAQ;CAShB"}

package/dist/event-loop-load.js

@@ -0,0 +1,40 @@
+import { busyWaitSync } from "@ac-kit/test-util";
+/** Milliseconds of CPU burned per scheduled slice. */
+const SLICE_MS = 2;
+/**
+ * Keeps the event loop busy until stopped.
+ *
+ * Timer benchmarks run on an idle loop measure a best case nobody experiences:
+ * the loop only checks its timer list once per iteration, so lateness is
+ * bounded below by whatever else is already queued. Measuring a condition both
+ * idle and loaded, and comparing the two, shows how much of the result belongs
+ * to the runtime rather than to the timer.
+ */
+export class EventLoopLoad {
+    running = false;
+    handle = null;
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.schedule();
+    }
+    stop() {
+        this.running = false;
+        if (this.handle) {
+            clearImmediate(this.handle);
+            this.handle = null;
+        }
+    }
+    schedule() {
+        if (!this.running) {
+            return;
+        }
+        this.handle = setImmediate(() => {
+            busyWaitSync(SLICE_MS);
+            this.schedule();
+        });
+    }
+}
+//# sourceMappingURL=event-loop-load.js.map

package/dist/event-loop-load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop-load.js","sourceRoot":"","sources":["../src/event-loop-load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,sDAAsD;AACtD,MAAM,QAAQ,GAAG,CAAC,CAAC;AAEnB;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IACjB,OAAO,GAAG,KAAK,CAAC;IAChB,MAAM,GAA4B,IAAI,CAAC;IAE/C,KAAK;QACJ,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO;QACR,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,QAAQ,EAAE,CAAC;IACjB,CAAC;IAED,IAAI;QACH,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACpB,CAAC;IACF,CAAC;IAEO,QAAQ;QACf,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO;QACR,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE;YAC/B,YAAY,CAAC,QAAQ,CAAC,CAAC;YACvB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjB,CAAC,CAAC,CAAC;IACJ,CAAC;CACD"}

package/dist/fixtures.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Fixtures shared by every benchmark package.
+ *
+ * Contenders inside a group must see identical input and produce the same
+ * answer; otherwise the ranking measures the fixture rather than the code. The
+ * generators here are deterministic so a run can be reproduced, and the
+ * reference programs in other languages can generate the same values.
+ */
+/** Default seed, shared so unrelated packages produce comparable fixtures. */
+export declare const DEFAULT_SEED = 625341585;
+/**
+ * `count` pseudo-random unsigned 32-bit values.
+ *
+ * Recovers the exact 32-bit state {@link xorshift32} divides down to a float:
+ * multiplying back by 2^32 is lossless for a value that started as an integer
+ * with 32 significant bits or fewer.
+ */
+export declare function randomUint32Values(count: number, seed?: number): number[];
+/** `count` pseudo-random floats in `[0, 1)`. */
+export declare function randomFloat64Values(count: number, seed?: number): number[];
+/** Sum of `values`, truncated to 32 bits. */
+export declare function checksum(values: Iterable<number>): number;
+/** Sum of `0..count-1`, the answer every FIFO workload must reach. */
+export declare function sequentialChecksum(count: number): number;
+/** Cheap order-sensitive hash of a string, used to verify text workloads. */
+export declare function hashString(text: string): number;
+/**
+ * Seeded 32-bit hash of a string, for structures that take a hash function as a
+ * parameter (Bloom filters, Count-Min sketches, HyperLogLog, …).
+ *
+ * Distinct from {@link hashString}, which is an unseeded checksum used to
+ * _verify_ a workload. This one is an input to the code under test, so it has
+ * to avalanche: the error bounds those structures document assume a uniformly
+ * distributed hash, and a weak one would make a suite measure the hash instead
+ * of the structure.
+ *
+ * Its shape matches `@ac-kit/data`'s `Hash32<string>` structurally, so it can
+ * be passed straight in without this package depending on `@ac-kit/data`.
+ */
+export declare function stringHash32(text: string, seed: number): number;
+/** `count` distinct keys, deterministic so every run compares like with like. */
+export declare function distinctKeys(count: number, prefix?: string): string[];
+/** `count` pseudo-random integers in `[0, bound)`. */
+export declare function randomInts(count: number, bound: number, seed?: number): number[];
+/**
+ * A skewed access pattern over `[0, universe)`: low indices drawn far more
+ * often than high ones.
+ *
+ * A uniform pattern makes every cache look alike, because a replacement policy
+ * only shows itself when some entries are genuinely hotter than others.
+ * Squaring a uniform draw is the cheapest way to get that skew and stays
+ * reproducible.
+ */
+export declare function skewedIndices(count: number, universe: number, seed?: number): number[];
+/** `count` short lowercase words, deterministic. */
+export declare function words(count: number, seed?: number): string[];
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,8EAA8E;AAC9E,eAAO,MAAM,YAAY,YAAa,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,EACb,IAAI,SAAe,GACjB,MAAM,EAAE,CAKV;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,MAAM,EACb,IAAI,SAAe,GACjB,MAAM,EAAE,CAGV;AAED,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAMzD;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAQ,GAAG,MAAM,EAAE,CAEpE;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CACzB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,SAAe,GACjB,MAAM,EAAE,CAGV;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,SAAe,GACjB,MAAM,EAAE,CAMV;AAED,oDAAoD;AACpD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAe,GAAG,MAAM,EAAE,CAclE"}

package/dist/fixtures.js

@@ -0,0 +1,104 @@
+/**
+ * Fixtures shared by every benchmark package.
+ *
+ * Contenders inside a group must see identical input and produce the same
+ * answer; otherwise the ranking measures the fixture rather than the code. The
+ * generators here are deterministic so a run can be reproduced, and the
+ * reference programs in other languages can generate the same values.
+ */
+import { encodeTextUtf8 } from "@ac-kit/core";
+import { xorshift32 } from "@ac-kit/math-random";
+import { fnv1a_32, murmur3_32 } from "@ac-kit/noncrypto-hash";
+/** Default seed, shared so unrelated packages produce comparable fixtures. */
+export const DEFAULT_SEED = 0x2545f491;
+/**
+ * `count` pseudo-random unsigned 32-bit values.
+ *
+ * Recovers the exact 32-bit state {@link xorshift32} divides down to a float:
+ * multiplying back by 2^32 is lossless for a value that started as an integer
+ * with 32 significant bits or fewer.
+ */
+export function randomUint32Values(count, seed = DEFAULT_SEED) {
+    const rand = xorshift32(seed);
+    return Array.from({ length: count }, () => Math.round(rand() * 4294967296));
+}
+/** `count` pseudo-random floats in `[0, 1)`. */
+export function randomFloat64Values(count, seed = DEFAULT_SEED) {
+    const rand = xorshift32(seed);
+    return Array.from({ length: count }, () => rand());
+}
+/** Sum of `values`, truncated to 32 bits. */
+export function checksum(values) {
+    let sum = 0;
+    for (const value of values) {
+        sum = (sum + value) >>> 0;
+    }
+    return sum;
+}
+/** Sum of `0..count-1`, the answer every FIFO workload must reach. */
+export function sequentialChecksum(count) {
+    let sum = 0;
+    for (let index = 0; index < count; index++) {
+        sum = (sum + index) >>> 0;
+    }
+    return sum;
+}
+/** Cheap order-sensitive hash of a string, used to verify text workloads. */
+export function hashString(text) {
+    return fnv1a_32(encodeTextUtf8(text));
+}
+/**
+ * Seeded 32-bit hash of a string, for structures that take a hash function as a
+ * parameter (Bloom filters, Count-Min sketches, HyperLogLog, …).
+ *
+ * Distinct from {@link hashString}, which is an unseeded checksum used to
+ * _verify_ a workload. This one is an input to the code under test, so it has
+ * to avalanche: the error bounds those structures document assume a uniformly
+ * distributed hash, and a weak one would make a suite measure the hash instead
+ * of the structure.
+ *
+ * Its shape matches `@ac-kit/data`'s `Hash32<string>` structurally, so it can
+ * be passed straight in without this package depending on `@ac-kit/data`.
+ */
+export function stringHash32(text, seed) {
+    return murmur3_32(encodeTextUtf8(text), seed);
+}
+/** `count` distinct keys, deterministic so every run compares like with like. */
+export function distinctKeys(count, prefix = "key") {
+    return Array.from({ length: count }, (_, index) => `${prefix}-${index}`);
+}
+/** `count` pseudo-random integers in `[0, bound)`. */
+export function randomInts(count, bound, seed = DEFAULT_SEED) {
+    const rand = xorshift32(seed);
+    return Array.from({ length: count }, () => Math.floor(rand() * bound));
+}
+/**
+ * A skewed access pattern over `[0, universe)`: low indices drawn far more
+ * often than high ones.
+ *
+ * A uniform pattern makes every cache look alike, because a replacement policy
+ * only shows itself when some entries are genuinely hotter than others.
+ * Squaring a uniform draw is the cheapest way to get that skew and stays
+ * reproducible.
+ */
+export function skewedIndices(count, universe, seed = DEFAULT_SEED) {
+    const rand = xorshift32(seed);
+    return Array.from({ length: count }, () => {
+        const value = rand();
+        return Math.floor(value * value * universe);
+    });
+}
+/** `count` short lowercase words, deterministic. */
+export function words(count, seed = DEFAULT_SEED) {
+    const rand = xorshift32(seed);
+    const alphabet = "abcdefghijklmnopqrstuvwxyz";
+    return Array.from({ length: count }, () => {
+        const length = 3 + Math.floor(rand() * 6);
+        let word = "";
+        for (let index = 0; index < length; index++) {
+            word += alphabet[Math.floor(rand() * alphabet.length)];
+        }
+        return word;
+    });
+}
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./event-loop-load.js";
+export * from "./fixtures.js";
+export * from "./native-toolchain.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./event-loop-load.js";
+export * from "./fixtures.js";
+export * from "./native-toolchain.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC"}

package/dist/native-toolchain.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Detects and, where needed, compiles a runnable reference program per
+ * toolchain spec — the machinery shared by every cross-language benchmark
+ * fixture in this workspace (a duration comparison is only meaningful once a
+ * program to compare against exists and actually runs).
+ */
+import type { ArtifactCache } from "@ac-kit/app-system";
+/** One candidate reference implementation, interpreted or compiled from source. */
+export interface NativeToolchainSpec {
+    /** Attribution label carried into `NativeProgram.language`, e.g. `"C++"`. */
+    language: string;
+    /** Absolute path to the reference program's source file. */
+    sourcePath: string;
+    /**
+     * Binaries tried in order; the first one found on `PATH` is used. For an
+     * interpreted toolchain this is the interpreter itself (e.g. `["python3"]`);
+     * for a compiled one, the candidate compilers (e.g. `["g++", "clang++"]`).
+     */
+    candidates: readonly string[];
+    /**
+     * Builds the compile command for whichever candidate was found. Omit for an
+     * interpreted toolchain, where `sourcePath` is invoked directly as the
+     * program's first argument instead.
+     */
+    compile?: (compiler: string, sourcePath: string, outBinary: string) => {
+        command: string;
+        args: readonly string[];
+    };
+}
+/**
+ * A reference program ready to spawn: `command` with `baseArgs` prepended to
+ * any call.
+ */
+export interface NativeProgram {
+    language: string;
+    command: string;
+    baseArgs: readonly string[];
+}
+export interface PrepareNativeToolchainsOptions {
+    /**
+     * Keeps only the programs that pass, e.g. a smoke test comparing against a
+     * known result. Every detected/compiled program is kept when omitted.
+     */
+    verify?: (program: NativeProgram) => Promise<boolean>;
+    /**
+     * Where compiled programs are cached. Supply the runner's own cache to share
+     * one compile across every process of a run; omitted, a persistent cache
+     * under `node_modules/.cache/ac-bench` is used.
+     */
+    cache?: ArtifactCache;
+}
+/**
+ * Detects, and where a `compile` step is declared compiles, one
+ * {@link NativeProgram} per spec whose first matching candidate is found on
+ * `PATH` — specs with no candidate found are silently skipped, and a spec whose
+ * compile step fails is reported to `stderr` and skipped rather than failing
+ * the whole batch, since a benchmark should degrade to comparing fewer
+ * languages rather than not comparing at all when one toolchain is missing.
+ *
+ * Compiled outputs are content-addressed by source text, compiler, compiler
+ * version and compile flags, so a program survives across runs and is rebuilt
+ * exactly when one of those changes. Nothing is written outside the cache
+ * root.
+ *
+ * Call once per distinct spec set and memoize the result in the caller (a lazy
+ * module-level singleton, as every consumer here already does) — the artifact
+ * cache spares the compile, not the detection work.
+ */
+export declare function prepareNativeToolchains(specs: readonly NativeToolchainSpec[], options?: PrepareNativeToolchainsOptions): Promise<readonly NativeProgram[]>;
+//# sourceMappingURL=native-toolchain.d.ts.map

package/dist/native-toolchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-toolchain.d.ts","sourceRoot":"","sources":["../src/native-toolchain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,oBAAoB,CAAC;AAKrE,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IACnC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IAEjB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CACT,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,KACb;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACtB;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC5C,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,OAAO,GAAE,8BAAmC,GAC1C,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAiEnC"}

package/dist/native-toolchain.js

@@ -0,0 +1,116 @@
+/**
+ * Detects and, where needed, compiles a runnable reference program per
+ * toolchain spec — the machinery shared by every cross-language benchmark
+ * fixture in this workspace (a duration comparison is only meaningful once a
+ * program to compare against exists and actually runs).
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createArtifactCache, hasBinary } from "@ac-kit/app-system";
+import { slugify } from "@ac-kit/core";
+import { spawnProcess } from "@ac-kit/node";
+const DEFAULT_CACHE_ROOT = join("node_modules", ".cache", "ac-bench");
+/** Best-effort, for the artifact identity: a compiler upgrade must invalidate. */
+async function probeVersion(compiler) {
+    try {
+        return (await spawnProcess(compiler, ["--version"])).stdout;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Detects, and where a `compile` step is declared compiles, one
+ * {@link NativeProgram} per spec whose first matching candidate is found on
+ * `PATH` — specs with no candidate found are silently skipped, and a spec whose
+ * compile step fails is reported to `stderr` and skipped rather than failing
+ * the whole batch, since a benchmark should degrade to comparing fewer
+ * languages rather than not comparing at all when one toolchain is missing.
+ *
+ * Compiled outputs are content-addressed by source text, compiler, compiler
+ * version and compile flags, so a program survives across runs and is rebuilt
+ * exactly when one of those changes. Nothing is written outside the cache
+ * root.
+ *
+ * Call once per distinct spec set and memoize the result in the caller (a lazy
+ * module-level singleton, as every consumer here already does) — the artifact
+ * cache spares the compile, not the detection work.
+ */
+export async function prepareNativeToolchains(specs, options = {}) {
+    const cache = options.cache ?? createArtifactCache({ root: DEFAULT_CACHE_ROOT });
+    const programs = [];
+    for (const spec of specs) {
+        let found = null;
+        for (const candidate of spec.candidates) {
+            if (await hasBinary(candidate)) {
+                found = candidate;
+                break;
+            }
+        }
+        if (found === null) {
+            continue;
+        }
+        if (!spec.compile) {
+            programs.push({
+                language: spec.language,
+                command: found,
+                baseArgs: [spec.sourcePath],
+            });
+            continue;
+        }
+        const compile = spec.compile;
+        const binaryName = slugify(spec.language, { fallback: "program" });
+        try {
+            const directory = await cache.ensure(await buildArtifactKey(spec, compile, found, binaryName), async (staging, signal) => {
+                const { command, args } = compile(found, spec.sourcePath, join(staging, binaryName));
+                await spawnProcess(command, args, { signal });
+            });
+            programs.push({
+                language: spec.language,
+                command: join(directory, binaryName),
+                baseArgs: [],
+            });
+        }
+        catch (error) {
+            process.stderr.write(`${spec.language} reference not built: ${String(error)}\n`);
+        }
+    }
+    if (!options.verify) {
+        return programs;
+    }
+    const usable = [];
+    for (const program of programs) {
+        if (await options.verify(program)) {
+            usable.push(program);
+        }
+    }
+    return usable;
+}
+async function buildArtifactKey(spec, compile, compiler, binaryName) {
+    // The real output path differs per attempt, so the identity uses a fixed
+    // placeholder — otherwise no two calls could ever agree on a key.
+    const { command, args } = compile(compiler, spec.sourcePath, join("<artifact>", binaryName));
+    return {
+        name: spec.language,
+        inputs: [
+            await readSourceOrPath(spec.sourcePath),
+            compiler,
+            await probeVersion(compiler),
+            command,
+            ...args,
+        ],
+    };
+}
+/**
+ * An unreadable source still gets an identity: the compile is about to fail on
+ * it anyway, and a failed build is never cached.
+ */
+async function readSourceOrPath(sourcePath) {
+    try {
+        return await readFile(sourcePath, "utf8");
+    }
+    catch {
+        return `\u0000unreadable:${sourcePath}`;
+    }
+}
+//# sourceMappingURL=native-toolchain.js.map

package/dist/native-toolchain.js.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ac-bench/util",
+  "version": "0.1.0",
+  "description": "Helpers for writing benchmarks: deterministic PRNG workloads, an order-sensitive output hash, an equivalence guard, a controllable event-loop load, and spawn-overhead measurement.",
+  "keywords": [
+    "benchmark",
+    "fixture",
+    "prng",
+    "workload"
+  ],
+  "homepage": "https://github.com/anthochamp/node-essentials/tree/main/bench/util#readme",
+  "bugs": {
+    "url": "https://github.com/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anthochamp/node-essentials.git",
+    "directory": "bench/util"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json --outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-kit/app-system": "^0.1.0",
+    "@ac-kit/core": "^0.1.0",
+    "@ac-kit/math-random": "^0.1.0",
+    "@ac-kit/math-stats": "^0.1.0",
+    "@ac-kit/node": "^0.1.0",
+    "@ac-kit/noncrypto-hash": "^0.1.0",
+    "@ac-kit/test-util": "^0.1.0"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@ac-kit/vitest-config": "0.1.0",
+    "@types/node": "26.5.1",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2",
+    "vite": "8.3.0",
+    "vitest": "5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}