@ac-bench/lib 0.1.0

package/dist/environment-monitor.d.ts

@@ -0,0 +1,59 @@
+import { ReportDiagnostic } from "@ac-kit/app-report";
+/** One observation of everything a child process does not isolate. */
+export type EnvironmentSample = {
+    at: number;
+    /** 1-minute load average divided by CPU count. */
+    loadRatio: number;
+    /** Mean of `scaling_cur_freq / cpuinfo_max_freq` across cores, when readable. */
+    frequencyRatio: number | null;
+    /** Hottest thermal zone in °C, when readable. */
+    temperatureC: number | null;
+    /** The parent's own CPU time in this interval, as a fraction of it. */
+    parentCpuRatio: number;
+    /** Resident set of the measuring child. */
+    childRssBytes: number | null;
+};
+export type EnvironmentStability = "stable" | "drifting" | "unstable";
+export type EnvironmentVerdict = {
+    stability: EnvironmentStability;
+    diagnostics: ReportDiagnostic[];
+    samples: EnvironmentSample[];
+};
+/**
+ * Classifies a scripted or collected series.
+ *
+ * A monotone ramp and an oscillation of the same amplitude look identical to a
+ * variance threshold and mean completely different things, so the two tests are
+ * separated: `mannKendallTrend` answers "is it going somewhere" and
+ * `reversalRate` answers "does it keep changing its mind".
+ */
+export declare function classifyEnvironment(samples: readonly EnvironmentSample[]): EnvironmentVerdict;
+export type EnvironmentProbe = () => Promise<EnvironmentSample>;
+export type EnvironmentMonitorOptions = {
+    readonly intervalMs?: number;
+};
+/**
+ * Samples the machine while a child measures, and judges what it saw.
+ *
+ * The parent is idle during a measurement, which makes it the only process in a
+ * position to watch the things a fork cannot isolate.
+ */
+export declare class EnvironmentMonitor {
+    private readonly probe;
+    private readonly intervalMs;
+    private samples;
+    private controller;
+    private loop;
+    constructor(probe: EnvironmentProbe, options?: EnvironmentMonitorOptions);
+    start(): void;
+    /** Stops sampling and classifies everything collected since `start()`. */
+    stop(): Promise<EnvironmentVerdict>;
+    private collect;
+}
+export type NodeEnvironmentProbeOptions = {
+    /** Resolved per sample, because the child outlives no single one of them. */
+    readonly pidOf?: () => number | undefined;
+};
+/** Reads the host metrics this platform exposes; unreadable ones are `null`. */
+export declare function nodeEnvironmentProbe(options?: NodeEnvironmentProbeOptions): EnvironmentProbe;
+//# sourceMappingURL=environment-monitor.d.ts.map

package/dist/environment-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-monitor.d.ts","sourceRoot":"","sources":["../src/environment-monitor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQtD,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iDAAiD;IACjD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAEtE,MAAM,MAAM,kBAAkB,GAAG;IAChC,SAAS,EAAE,oBAAoB,CAAC;IAChC,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAiBF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACnC,kBAAkB,CAkEpB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhE,MAAM,MAAM,yBAAyB,GAAG;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF;;;;;GAKG;AACH,qBAAa,kBAAkB;IAO7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IANvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,IAAI,CAA8B;IAE1C,YACkB,KAAK,EAAE,gBAAgB,EACxC,OAAO,CAAC,EAAE,yBAAyB,EAGnC;IAED,KAAK,IAAI,IAAI,CAQZ;IAED,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAQxC;YAEa,OAAO;CAWrB;AAED,MAAM,MAAM,2BAA2B,GAAG;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAC1C,CAAC;AAEF,gFAAgF;AAChF,wBAAgB,oBAAoB,CACnC,OAAO,CAAC,EAAE,2BAA2B,GACnC,gBAAgB,CA6BlB"}

package/dist/environment-monitor.js

@@ -0,0 +1,163 @@
+import os from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import { readCpuFrequencyRatio, readMaxTemperatureC, readProcessRssBytes, } from "@ac-kit/app-system";
+import { mannKendallTrend, reversalRate } from "@ac-kit/math-stats";
+/** Two-sided 5% normal deviate: the trend is real rather than sampling noise. */
+const TREND_SIGNIFICANT_ = 1.96;
+/** Above this fraction of reversals a series is oscillating, not drifting. */
+const REVERSALS_UNSTABLE_ = 0.4;
+/** Below this fraction a series is monotone enough to call a drift. */
+const REVERSALS_DRIFTING_ = 0.25;
+/** A core dropping this far below the run's own best is throttling. */
+const FREQUENCY_FLOOR_ = 0.9;
+/** Load per core above which the machine is contended. */
+const LOAD_CONTENDED_ = 0.7;
+/**
+ * Classifies a scripted or collected series.
+ *
+ * A monotone ramp and an oscillation of the same amplitude look identical to a
+ * variance threshold and mean completely different things, so the two tests are
+ * separated: `mannKendallTrend` answers "is it going somewhere" and
+ * `reversalRate` answers "does it keep changing its mind".
+ */
+export function classifyEnvironment(samples) {
+    const metrics = [
+        {
+            name: "load",
+            values: samples.map((sample) => sample.loadRatio),
+            unstable: (values) => Math.min(...values) < LOAD_CONTENDED_ &&
+                Math.max(...values) > LOAD_CONTENDED_,
+        },
+        {
+            name: "frequency",
+            values: definedValues_(samples, (sample) => sample.frequencyRatio),
+            unstable: (values) => Math.min(...values) < FREQUENCY_FLOOR_ * Math.max(...values),
+        },
+        {
+            name: "temperature",
+            values: definedValues_(samples, (sample) => sample.temperatureC),
+            // Temperature climbs and does not oscillate; only its drift is meaningful.
+            unstable: () => false,
+        },
+    ];
+    const diagnostics = [];
+    let stability = "stable";
+    for (const metric of metrics) {
+        if (metric.values.length < 3) {
+            continue;
+        }
+        const reversals = reversalRate(metric.values);
+        const { normalised } = mannKendallTrend(metric.values);
+        const low = Math.min(...metric.values);
+        const high = Math.max(...metric.values);
+        if (reversals >= REVERSALS_UNSTABLE_ && metric.unstable(metric.values)) {
+            stability = "unstable";
+            diagnostics.push({
+                severity: "warning",
+                code: "environment-unstable",
+                message: `${metric.name} oscillated between ${format_(low)} and ${format_(high)} during this measurement; the numbers are contended, not merely shifted`,
+                attributes: { metric: metric.name, low, high, reversals },
+            });
+            continue;
+        }
+        if (Math.abs(normalised) >= TREND_SIGNIFICANT_ &&
+            reversals <= REVERSALS_DRIFTING_) {
+            if (stability === "stable") {
+                stability = "drifting";
+            }
+            diagnostics.push({
+                severity: "info",
+                code: "environment-drift",
+                message: `${metric.name} drifted ${normalised > 0 ? "up" : "down"} from ${format_(metric.values[0] ?? 0)} to ${format_(metric.values[metric.values.length - 1] ?? 0)} during this measurement`,
+                attributes: { metric: metric.name, low, high, normalised },
+            });
+        }
+    }
+    // A clean run stays quiet.
+    return { stability, diagnostics, samples: [...samples] };
+}
+const DEFAULT_INTERVAL_MS_ = 1000;
+/**
+ * Samples the machine while a child measures, and judges what it saw.
+ *
+ * The parent is idle during a measurement, which makes it the only process in a
+ * position to watch the things a fork cannot isolate.
+ */
+export class EnvironmentMonitor {
+    probe;
+    intervalMs;
+    samples = [];
+    controller = null;
+    loop = null;
+    constructor(probe, options) {
+        this.probe = probe;
+        this.intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS_;
+    }
+    start() {
+        if (this.controller !== null) {
+            return;
+        }
+        this.samples = [];
+        this.controller = new AbortController();
+        this.loop = this.collect(this.controller.signal);
+    }
+    /** Stops sampling and classifies everything collected since `start()`. */
+    async stop() {
+        this.controller?.abort();
+        await this.loop;
+        this.controller = null;
+        this.loop = null;
+        return classifyEnvironment(this.samples);
+    }
+    async collect(signal) {
+        while (!signal.aborted) {
+            try {
+                this.samples.push(await this.probe());
+                await delay(this.intervalMs, undefined, { signal });
+            }
+            catch {
+                // An unreadable metric or an aborted wait ends the watch, never the run.
+                return;
+            }
+        }
+    }
+}
+/** Reads the host metrics this platform exposes; unreadable ones are `null`. */
+export function nodeEnvironmentProbe(options) {
+    const cpuCount = Math.max(1, os.cpus().length);
+    let lastCpu = process.cpuUsage();
+    let lastAt = Date.now();
+    return async () => {
+        const at = Date.now();
+        const cpu = process.cpuUsage();
+        const elapsedUs = Math.max(1, (at - lastAt) * 1000);
+        const usedUs = cpu.user - lastCpu.user + (cpu.system - lastCpu.system);
+        lastCpu = cpu;
+        lastAt = at;
+        const [frequencyRatio, temperatureC, childRssBytes] = await Promise.all([
+            readCpuFrequencyRatio(),
+            readMaxTemperatureC(),
+            readChildRss_(options?.pidOf?.()),
+        ]);
+        return {
+            at,
+            loadRatio: (os.loadavg()[0] ?? 0) / cpuCount,
+            frequencyRatio,
+            temperatureC,
+            parentCpuRatio: usedUs / elapsedUs,
+            childRssBytes,
+        };
+    };
+}
+function readChildRss_(pid) {
+    return pid === undefined ? Promise.resolve(null) : readProcessRssBytes(pid);
+}
+function definedValues_(samples, pick) {
+    return samples
+        .map((sample) => pick(sample))
+        .filter((value) => value !== null);
+}
+function format_(value) {
+    return value.toFixed(2);
+}
+//# sourceMappingURL=environment-monitor.js.map

package/dist/environment-monitor.js.map

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

package/dist/escalation.d.ts

@@ -0,0 +1,24 @@
+import type { MeasureComparison } from "@ac-bench/core/plugin";
+import { type DataFrame } from "@ac-kit/model-dataset";
+/**
+ * Whether the measurements taken so far settle the comparison.
+ *
+ * A benchmark's job is to order its cases. Two cases whose intervals overlap
+ * are not ordered by the numbers: whichever came out ahead did so within the
+ * noise, and another process could reverse it. That is the only signal worth
+ * spending more machine time on, and it is measure-agnostic — the parent reads
+ * it off the frame and the comparison every plugin already declares, rather
+ * than knowing what any measure's numbers mean.
+ *
+ * Cases without an interval are ignored: an unknown interval is not an
+ * overlapping one, and treating it as such would escalate forever.
+ *
+ * O(n log n) in the case count, for the sort.
+ *
+ * @param frame The condition's frame, from `MeasurePlugin.conditionFrame`.
+ * @param comparison What the measure says orders its cases. A measure with no
+ *   interval bounds makes no claim tight enough to escalate on.
+ * @returns `true` when some adjacent pair cannot be told apart.
+ */
+export declare function comparisonUnresolved(frame: DataFrame, comparison: MeasureComparison | undefined): boolean;
+//# sourceMappingURL=escalation.d.ts.map

package/dist/escalation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escalation.d.ts","sourceRoot":"","sources":["../src/escalation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAGN,KAAK,SAAS,EACd,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,iBAAiB,GAAG,SAAS,GACvC,OAAO,CA2DT"}

package/dist/escalation.js

@@ -0,0 +1,73 @@
+import { createComparatorBy } from "@ac-kit/core";
+import { columnCell, findDataFrameFieldIndexByName, } from "@ac-kit/model-dataset";
+/**
+ * Whether the measurements taken so far settle the comparison.
+ *
+ * A benchmark's job is to order its cases. Two cases whose intervals overlap
+ * are not ordered by the numbers: whichever came out ahead did so within the
+ * noise, and another process could reverse it. That is the only signal worth
+ * spending more machine time on, and it is measure-agnostic — the parent reads
+ * it off the frame and the comparison every plugin already declares, rather
+ * than knowing what any measure's numbers mean.
+ *
+ * Cases without an interval are ignored: an unknown interval is not an
+ * overlapping one, and treating it as such would escalate forever.
+ *
+ * O(n log n) in the case count, for the sort.
+ *
+ * @param frame The condition's frame, from `MeasurePlugin.conditionFrame`.
+ * @param comparison What the measure says orders its cases. A measure with no
+ *   interval bounds makes no claim tight enough to escalate on.
+ * @returns `true` when some adjacent pair cannot be told apart.
+ */
+export function comparisonUnresolved(frame, comparison) {
+    if (comparison?.interval === undefined) {
+        return false;
+    }
+    const intervals = [];
+    if (Array.isArray(comparison.interval)) {
+        const [lowerField, upperField] = comparison.interval;
+        const lowerIndex = findDataFrameFieldIndexByName(frame, lowerField);
+        const upperIndex = findDataFrameFieldIndexByName(frame, upperField);
+        const lowerColumn = frame.columns[lowerIndex];
+        const upperColumn = frame.columns[upperIndex];
+        if (lowerColumn === undefined || upperColumn === undefined) {
+            return false;
+        }
+        for (let rowIndex = 0; rowIndex < frame.rowCount; rowIndex++) {
+            const lower = columnCell(lowerColumn, rowIndex);
+            const upper = columnCell(upperColumn, rowIndex);
+            if (typeof lower === "number" && typeof upper === "number") {
+                intervals.push({ lower, upper });
+            }
+        }
+    }
+    else if (typeof comparison.interval === "string") {
+        const halfWidthField = comparison.interval;
+        const fieldIndex = findDataFrameFieldIndexByName(frame, halfWidthField);
+        const column = frame.columns[fieldIndex];
+        if (column === undefined) {
+            return false;
+        }
+        for (let rowIndex = 0; rowIndex < frame.rowCount; rowIndex++) {
+            const halfWidth = columnCell(column, rowIndex);
+            if (typeof halfWidth === "number") {
+                intervals.push({ lower: halfWidth, upper: halfWidth });
+            }
+        }
+    }
+    // One case is not a comparison, and neither is none.
+    if (intervals.length < 2) {
+        return false;
+    }
+    intervals.sort(createComparatorBy((v) => v.lower));
+    for (let index = 1; index < intervals.length; index++) {
+        const previous = intervals[index - 1];
+        const current = intervals[index];
+        if (current.lower <= previous.upper) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=escalation.js.map

package/dist/escalation.js.map

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

package/dist/fork-runner.d.ts

@@ -0,0 +1,52 @@
+import { DiscoveredCondition, MeasureData, StartMessage } from "@ac-bench/core/runner";
+import { ISink, ReportDiagnostic, ReportScopeStatus } from "@ac-kit/app-report";
+/** No message from a child for this long means it is no longer making progress. */
+export declare const DEFAULT_HEARTBEAT_TIMEOUT_MS = 30000;
+/** A child stopped producing messages without having finished. */
+export declare class ChildTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** A fork unit outlived its wall-clock budget. */
+export declare class ConditionTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** A child exited before reporting that it was done. */
+export declare class ChildExitedError extends Error {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    constructor(code: number | null, signal: NodeJS.Signals | null, options?: ErrorOptions);
+}
+export type ForkOptions = {
+    readonly runId: string;
+    readonly artifactCacheRoot: string;
+    readonly signal: AbortSignal;
+    readonly heartbeatTimeoutMs?: number;
+    /** Wall-clock cap on one fork unit. `0` (the default) disables it. */
+    readonly conditionTimeoutMs?: number;
+    /** Imported by the child before any bench file, in order. */
+    readonly setupFiles?: readonly string[];
+    readonly execArgv?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    /** Called once the child exists, and again with `undefined` once it is gone. */
+    readonly onChildPid?: (pid: number | undefined) => void;
+};
+export type ChildOutcome = {
+    status: ReportScopeStatus;
+    error: unknown;
+};
+/**
+ * Forks a discovery child for `file` and returns the condition tree it
+ * registered, without executing a single case.
+ */
+export declare function discoverConditionsInFile(file: string, options: ForkOptions): Promise<DiscoveredCondition[]>;
+/**
+ * Forks a child, runs one fork unit in it, and replays everything it reports
+ * into `sink` in order.
+ *
+ * The child's own scopes are closed out here if it dies without saying it was
+ * done, so a crash can never strand a scope.
+ */
+export declare function runForkUnitInChild(start: Omit<StartMessage, "t">, sink: ISink<MeasureData>, onDiagnostic: (diagnostic: ReportDiagnostic) => void, options: ForkOptions): Promise<ChildOutcome>;
+//# sourceMappingURL=fork-runner.d.ts.map

package/dist/fork-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork-runner.d.ts","sourceRoot":"","sources":["../src/fork-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAGN,mBAAmB,EACnB,WAAW,EAGX,YAAY,EACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOhF,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAInD,kEAAkE;AAClE,qBAAa,iBAAkB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAAtC,YAAqB,SAAS,EAAE,MAAM,EAGrC;CACD;AAED,kDAAkD;AAClD,qBAAa,qBAAsB,SAAQ,KAAK;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAAtC,YAAqB,SAAS,EAAE,MAAM,EAGrC;CACD;AAED,wDAAwD;AACxD,qBAAa,gBAAiB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI;IAFvC,YACU,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,EACtC,OAAO,CAAC,EAAE,YAAY,EAStB;CACD;AAED,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,wBAAsB,wBAAwB,CAC7C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAwBhC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACvC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,EAC9B,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC,EACxB,YAAY,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,EACpD,OAAO,EAAE,WAAW,GAClB,OAAO,CAAC,YAAY,CAAC,CA8FvB"}