@a11ign/screenreader-fleet 0.1.0 → 0.3.0

package/dist/compare-workers.mjs

@@ -1,123 +1,285 @@
 #!/usr/bin/env node
-// @ts-check
-// Why is one worker slower than another? Run the same page on each and diff every phase.
-//
-//   npm run worker:compare -- <page-url> <worker-url> <worker-url> [...] [--rounds=6]
-//
-// This exists because I spent hours attributing a 2x difference between two guests to the wrong phase.
-// `bench-capture.mjs` gives a phase table for ONE worker, so comparing two meant eyeballing two
-// printouts, and I compared wall times instead — which said "worker 1 is faster" without saying where.
-// The moment the phases were put side by side the answer was immediate: `windowsActivate` was identical
-// (7.4s vs 7.3s, so Edge launch was never the difference) and the entire gap was in `sweep`.
-//
-// It also surfaces the per-sweep detail that capture-core already records and nothing displayed.
-// `collectByType` marks every sweep with its type, elapsed ms and round-trip count in each direction,
-// and the aggregate hid all of it. Six sweeps collapsed into one number cannot tell you whether a worker
-// is doing MORE round trips or SLOWER ones — and those have different causes.
-//
-// Samples are INTERLEAVED round-robin and reported as medians with an interquartile range, never as
-// means. Both choices are corrections to how this went wrong before:
-//
-//   - Sequential sampling (all of worker A, then all of worker B) charges any drift in the host during
-//     those minutes to the difference between the workers. Round-robin makes drift common to all of them.
-//   - A single mute-recovery outlier (~86s against a normal ~12s) moves a mean by 5s and makes a healthy
-//     worker look broken. The median and IQR do not move.
-//
-// It also refuses to declare a difference the samples do not support -- see `./worker-stats.mjs`.
-// "Not distinguishable" is a real answer, and it is the one that was missing.
-import { writeFileSync, mkdirSync, realpathSync } from "node:fs";
-import { refuseIfBusy, sampleVitals } from "./measure-guard.mjs";
-import { pathToFileURL, fileURLToPath } from "node:url";
-import { compareWorkers, describe as summarise, recoveryRates } from "./worker-stats.mjs";
-import { sampleHost, diffHost } from "./host-metrics.mjs";
-import { requestJson, CAPTURE_CLIENT_TIMEOUT_MS } from "./worker-http.mjs";
+import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
+import { describeProbe, probeHealth, WORKER_PROBE_TIMEOUT_MS } from "./probe-outcome.mjs";
+import { CAPTURE_CLIENT_TIMEOUT_MS, requestJson } from "./worker-http.mjs";
 import { refuseUnknownFlags } from "./cli-flags.mjs";
-/**
- * takes a page and two workers POSITIONALLY. `--runs=` is a documented alias of `--rounds=`, so both
- * are accepted — a guard listing only one would refuse a spelling the code deliberately supports.
- *
- * An unrecognised flag is otherwise IGNORED, so it runs the default and reports success.
- */
-refuseUnknownFlags(["--rounds=", "--runs="], { entry: import.meta.url, command: "npm run worker:compare" });
-// `requestJson`, not `fetch`: undici stops waiting for response HEADERS at 300 s whatever the
-// AbortSignal says, and the worker writes its status and body together at the END of a capture.
-// See worker-http.mjs -- this budget sits at or above that cap, so it never applied.
-// Resolved from THIS module, never the cwd -- same reason as `doctor.mjs`'s `DATASET`: this package
-// cannot import `@a11ign/lab`'s canonical `runs/` resolution without a dependency cycle.
+async function refuseIfBusy(workers, { what, timeoutMs = WORKER_PROBE_TIMEOUT_MS, request }) {
+    const states = await Promise.all(workers.map(async (worker)=>{
+        const probe = await probeHealth(worker, {
+            timeoutMs,
+            request
+        });
+        if ("ready" === probe.outcome) return {
+            worker,
+            free: true,
+            why: ""
+        };
+        return {
+            worker,
+            free: false,
+            why: describeProbe(probe, {
+                worker,
+                timeoutMs
+            })
+        };
+    }));
+    const busy = states.filter((s)=>!s.free);
+    if (!busy.length) return;
+    throw new Error(`REFUSING to measure ${what}: ${busy.length} of ${workers.length} worker(s) are not free — ${busy.map((b)=>b.why).join(" ")} A measurement taken against a busy box samples its 429s, not its behaviour, and returns a number that looks real. Wait, or pass a worker that is free.`);
+}
+const VITALS_TIMEOUT_MS = 20000;
+async function sampleVitals(worker, { timeoutMs = VITALS_TIMEOUT_MS, request, warn = ()=>{} } = {}) {
+    const probe = await probeHealth(worker, {
+        timeoutMs,
+        request
+    });
+    if ("refused" === probe.outcome || "no-answer" === probe.outcome) {
+        warn(`  no vitals sampled: ${describeProbe(probe, {
+            worker,
+            timeoutMs
+        })}\n`);
+        return null;
+    }
+    return probe.health?.vitals ?? null;
+}
+const MIN_ROUNDS_FOR_A_VERDICT = 5;
+const sorted = (values)=>[
+        ...values
+    ].sort((a, b)=>a - b);
+function quantile(values, q) {
+    if (!values.length) return null;
+    const s = sorted(values);
+    const position = (s.length - 1) * q;
+    const low = Math.floor(position), high = Math.ceil(position);
+    return low === high ? s[low] : s[low] + (s[high] - s[low]) * (position - low);
+}
+function describe(values) {
+    if (!values.length) return null;
+    const q1 = quantile(values, 0.25);
+    const q3 = quantile(values, 0.75);
+    return {
+        n: values.length,
+        median: quantile(values, 0.5),
+        q1,
+        q3,
+        iqr: q3 - q1,
+        min: Math.min(...values),
+        max: Math.max(...values)
+    };
+}
+function overlaps(a, b) {
+    return a.q1 <= b.q3 && b.q1 <= a.q3;
+}
+function compareWorkers(samplesByWorker) {
+    const stats = {};
+    for (const [worker, values] of Object.entries(samplesByWorker)){
+        const description = describe(values);
+        if (description) stats[worker] = description;
+    }
+    const names = Object.keys(stats);
+    if (names.length < 2) return {
+        stats,
+        slowest: null,
+        fastest: null,
+        distinguishable: false,
+        verdict: "need at least two workers with samples"
+    };
+    const rounds = Math.min(...names.map((n)=>stats[n].n));
+    const byMedian = [
+        ...names
+    ].sort((a, b)=>stats[a].median - stats[b].median);
+    const fastest = byMedian[0], slowest = byMedian[byMedian.length - 1];
+    const gap = stats[slowest].median - stats[fastest].median;
+    const widest = Math.max(stats[fastest].iqr, stats[slowest].iqr);
+    if (rounds < MIN_ROUNDS_FOR_A_VERDICT) return {
+        stats,
+        slowest,
+        fastest,
+        distinguishable: false,
+        verdict: `only ${rounds} round(s) — too few to claim anything. Run at least ${MIN_ROUNDS_FOR_A_VERDICT}.`
+    };
+    if (gap <= widest || overlaps(stats[fastest], stats[slowest])) return {
+        stats,
+        slowest,
+        fastest,
+        distinguishable: false,
+        verdict: `NOT DISTINGUISHABLE: medians differ by ${gap.toFixed(1)} but the spread is ${widest.toFixed(1)} and the interquartile ranges overlap. These samples do not support a difference between the workers.`
+    };
+    return {
+        stats,
+        slowest,
+        fastest,
+        distinguishable: true,
+        verdict: `${slowest} is slower than ${fastest} by ${gap.toFixed(1)} (medians), with non-overlapping interquartile ranges over ${rounds} interleaved rounds.`
+    };
+}
+function recoveryRates(deltas) {
+    const rates = {};
+    for (const [worker, d] of Object.entries(deltas))rates[worker] = d.captures > 0 ? d.recoveries / d.captures : null;
+    return rates;
+}
+const BYTES_PER_MB = 1048576;
+function parseVmStat(output) {
+    const pageSize = Number(/page size of (\d+) bytes/.exec(output)?.[1]);
+    if (!Number.isFinite(pageSize)) return null;
+    const pages = (label)=>Number(new RegExp(`${label}:\\s+(\\d+)`).exec(output)?.[1] ?? 0);
+    const mb = (label)=>Math.round(pages(label) * pageSize / BYTES_PER_MB);
+    return {
+        freeMb: mb("Pages free"),
+        activeMb: mb("Pages active"),
+        inactiveMb: mb("Pages inactive"),
+        wiredMb: mb("Pages wired down"),
+        compressorMb: mb("Pages occupied by compressor"),
+        pageins: pages("Pageins"),
+        pageouts: pages("Pageouts")
+    };
+}
+function parseIostat(output) {
+    const lines = String(output).trim().split(/\r?\n/);
+    const header = lines.findIndex((l)=>/^\s*disk/.test(l));
+    if (-1 === header) return [];
+    const devices = lines[header].trim().split(/\s+/);
+    const samples = lines.slice(header + 2).filter((l)=>/\d/.test(l));
+    const last = samples.at(-1);
+    if (!last) return [];
+    const numbers = last.trim().split(/\s+/).map(Number);
+    return devices.map((device, i)=>({
+            device,
+            kbPerTransfer: numbers[3 * i] ?? 0,
+            transfersPerSecond: numbers[3 * i + 1] ?? 0,
+            mbPerSecond: numbers[3 * i + 2] ?? 0
+        })).filter((d)=>Number.isFinite(d.mbPerSecond));
+}
+function parseLoadAverage(output) {
+    const m = /([\d.]+)\s+([\d.]+)\s+([\d.]+)/.exec(String(output));
+    return m ? {
+        one: Number(m[1]),
+        five: Number(m[2]),
+        fifteen: Number(m[3])
+    } : null;
+}
+function parseProcessMemory(psOutput, match) {
+    return String(psOutput).trim().split(/\r?\n/).flatMap((line)=>{
+        const fields = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!fields || !fields[3].includes(match)) return [];
+        return [
+            {
+                pid: Number(fields[1]),
+                residentMb: Math.round(Number(fields[2]) / 1024),
+                command: fields[3]
+            }
+        ];
+    });
+}
+const run = (cmd, args)=>{
+    try {
+        return execFileSync(cmd, args, {
+            encoding: "utf8",
+            timeout: 15000
+        });
+    } catch  {
+        return "";
+    }
+};
+function sampleHost({ processMatch = "QEMU" } = {}) {
+    const memory = parseVmStat(run("vm_stat", []));
+    return {
+        at: new Date().toISOString(),
+        memory,
+        disk: parseIostat(run("iostat", [
+            "-d",
+            "-c",
+            "2",
+            "-w",
+            "1"
+        ])),
+        load: parseLoadAverage(run("sysctl", [
+            "-n",
+            "vm.loadavg"
+        ])),
+        processes: parseProcessMemory(run("ps", [
+            "-Ao",
+            "pid=,rss=,comm="
+        ]), processMatch)
+    };
+}
+const reading = (snapshot, field, fallback)=>snapshot?.memory?.[field] ?? fallback;
+function diffHost(before, after) {
+    const pageouts = (reading(after, "pageouts", 0) ?? 0) - (reading(before, "pageouts", 0) ?? 0);
+    const pageins = (reading(after, "pageins", 0) ?? 0) - (reading(before, "pageins", 0) ?? 0);
+    return {
+        pageoutsDelta: pageouts,
+        pageinsDelta: pageins,
+        swappingDuringRun: pageouts > 0,
+        compressorMb: reading(after, "compressorMb", null),
+        freeMb: reading(after, "freeMb", null),
+        residentMbTotal: (after?.processes ?? []).reduce((sum, p)=>sum + p.residentMb, 0)
+    };
+}
+refuseUnknownFlags([
+    "--rounds=",
+    "--runs="
+], {
+    entry: import.meta.url,
+    command: "npm run worker:compare"
+});
 const OUT = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/worker-compare");
 const MS_PER_S = 1000;
-/**
- * `dataset-paths.mjs`'s `refuseIfRunsReadonly`, duplicated rather than imported -- same reason `OUT`
- * above resolves from this module's own location instead of importing `runsRoot()`: this package cannot
- * import `@a11ign/lab` without a dependency cycle (see `dataset-paths.test.ts`'s own EXEMPT entry
- * for this file). `A11Y_RUNS_READONLY=1 npm run worker:compare ...` must refuse and name `OUT` exactly
- * like every other runs/ writer, so a peer asking "is this safe to run" gets one answer regardless of
- * which package the script happens to live in.
- */
 function refuseIfRunsReadonly() {
-    if (process.env.A11Y_RUNS_READONLY !== "1")
-        return;
+    if ("1" !== process.env.A11Y_RUNS_READONLY) return;
     console.error("REFUSING to write runs/worker-compare/compare.json — A11Y_RUNS_READONLY=1 is set.");
     console.error("  Unset A11Y_RUNS_READONLY to run this for real.");
     process.exit(3);
 }
-const args = process.argv.slice(2);
-const runs = Number(args.find((a) => a.startsWith("--rounds="))?.slice("--rounds=".length)
-    ?? args.find((a) => a.startsWith("--runs="))?.slice("--runs=".length) ?? 6);
-const [page, ...workers] = args.filter((a) => !a.startsWith("--"));
-const short = (/** @type {any} */ worker) => new URL(worker).hostname.split(".").pop();
-async function capture(/** @type {any} */ worker) {
+const compare_workers_args = process.argv.slice(2);
+const runs = Number(compare_workers_args.find((a)=>a.startsWith("--rounds="))?.slice(9) ?? compare_workers_args.find((a)=>a.startsWith("--runs="))?.slice(7) ?? 6);
+const [page, ...compare_workers_workers] = compare_workers_args.filter((a)=>!a.startsWith("--"));
+const compare_workers_short = (worker)=>new URL(worker).hostname.split(".").pop();
+async function capture(worker) {
     const response = await requestJson(`${worker.replace(/\/$/, "")}/capture`, {
         method: "POST",
-        body: { url: page, probeForms: true },
-        timeoutMs: CAPTURE_CLIENT_TIMEOUT_MS,
+        body: {
+            url: page,
+            probeForms: true
+        },
+        timeoutMs: CAPTURE_CLIENT_TIMEOUT_MS
     });
     const body = response.json ?? {};
-    if (!response.ok)
-        throw new Error(`HTTP ${response.status}: ${JSON.stringify(body).slice(0, 160)}`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${JSON.stringify(body).slice(0, 160)}`);
     return body;
 }
-async function diagnostics(/** @type {any} */ worker) {
+async function diagnostics(worker) {
     try {
-        // `requestJson`, not `fetch`: the same worker JSON client every other probe in this file uses (see
-        // `capture`, above), rather than a second hand-rolled timeout mechanism for this one endpoint.
-        const response = await requestJson(`${worker.replace(/\/$/, "")}/diagnostics`, { timeoutMs: 180_000 });
-        // `?? null`: `response.json` is `undefined` on unparseable JSON (requestJson's own contract) rather
-        // than a throw, so this still folds into the same "an older worker has no /diagnostics" outcome.
+        const response = await requestJson(`${worker.replace(/\/$/, "")}/diagnostics`, {
+            timeoutMs: 180000
+        });
         return response.ok ? response.json ?? null : null;
-    }
-    catch {
-        return null; // an older worker has no /diagnostics; the phase comparison still works
+    } catch  {
+        return null;
     }
 }
-/**
- * Phase costs from one capture's diagnostics.
- *
- * Diagnostics carry a cumulative `atMs`, so a phase's own cost is the gap from the previous mark — the
- * same arithmetic bench-capture does. Repeated events (there are six `sweep` marks) accumulate, which is
- * what makes `sweep` look like one large phase.
- */
-function phaseCosts(/** @type {any} */ entries) {
-    /** @type {Record<string, any>} */
+function phaseCosts(entries) {
     const costs = {};
     let previous = 0;
-    for (const entry of entries ?? []) {
-        if (typeof entry.atMs !== "number")
-            continue;
+    for (const entry of entries ?? [])if ("number" == typeof entry.atMs) {
         costs[entry.event] = (costs[entry.event] ?? 0) + (entry.atMs - previous);
         previous = entry.atMs;
     }
     return costs;
 }
-/** Per-sweep detail, keyed by sweep type, which the aggregate throws away. */
-function sweepDetail(/** @type {any} */ entries) {
-    /** @type {Record<string, any>} */
+function sweepDetail(entries) {
     const byType = {};
-    for (const entry of entries ?? []) {
-        if (entry.event !== "sweep" || !entry.type)
-            continue;
-        const to = byType[entry.type] ??= { found: 0, ms: 0, trips: 0, n: 0 };
+    for (const entry of entries ?? []){
+        if ("sweep" !== entry.event || !entry.type) continue;
+        const to = byType[entry.type] ??= {
+            found: 0,
+            ms: 0,
+            trips: 0,
+            n: 0
+        };
         to.found += entry.found ?? 0;
         to.ms += (entry.prevMs ?? 0) + (entry.nextMs ?? 0);
         to.trips += (entry.prevTrips ?? 0) + (entry.nextTrips ?? 0);
@@ -125,208 +287,174 @@ function sweepDetail(/** @type {any} */ entries) {
     }
     return byType;
 }
-/** `sampleVitals` says on stderr why a worker has none, so a blank column in the report has a reason. */
-async function vitals(/** @type {string} */ worker) {
-    return sampleVitals(worker, { warn: (line) => process.stderr.write(line) });
+async function vitals(worker) {
+    return sampleVitals(worker, {
+        warn: (line)=>process.stderr.write(line)
+    });
 }
-/**
- * Only when RUN, never on import.
- *
- * This drove REAL captures against two workers at module scope -- so importing it to check the file still
- * loads issued `runs * workers` captures, each up to 560 s, and wrote a report under `runs/worker-compare`.
- * The usage guard moved in with it: a missing page argument is a mistake made by a CALLER, and there is no
- * caller when a file is merely imported.
- */
 async function main() {
-    if (!page || workers.length < 2) {
+    if (!page || compare_workers_workers.length < 2) {
         process.stderr.write("usage: npm run worker:compare -- <page-url> <worker> <worker> [--rounds=6]\n");
         process.exit(2);
     }
     refuseIfRunsReadonly();
-    // REFUSE A BUSY BOX BEFORE MEASURING IT. This whole tool exists to answer "which worker is the
-    // problem", and four separate measurement errors came from sampling a box that was doing something
-    // else — including 12 straight 429s read as timings. `refuseIfBusy` was written for exactly this and
-    // was wired to nothing, which is the `scorer:verify` shape: a guard that exists and never runs.
-    await refuseIfBusy(workers, { what: `worker:compare against ${page}` });
-    // Per worker: the three series this comparison exists to print, plus the last run's diagnostics.
-    // Declared because every array here is empty at construction and inferred `never[]`, so each push --
-    // which IS the measurement -- reads as an error while the shape that discards it reads as fine.
-    /** @type {Record<string, { phases: any[], sweeps: any[], walls: number[], diagnostics: any }>} */
-    const results = Object.fromEntries(workers.map((/** @type {string} */ w) => [w, { phases: [], sweeps: [], walls: [], diagnostics: null }]));
-    /** @type {Record<string, any>} */
-    /** @type {Record<string, any>} */
+    await refuseIfBusy(compare_workers_workers, {
+        what: `worker:compare against ${page}`
+    });
+    const results = Object.fromEntries(compare_workers_workers.map((w)=>[
+            w,
+            {
+                phases: [],
+                sweeps: [],
+                walls: [],
+                diagnostics: null
+            }
+        ]));
     const vitalsBefore = {};
-    /** @type {Record<string, any>} */
     const vitalsAfter = {};
-    for (const worker of workers)
-        vitalsBefore[worker] = await vitals(worker);
-    // The foundations, sampled around the run. Timings alone say something got slower; they never say
-    // which resource ran out. Not sampling disk I/O is why three guests contending on one SSD was
-    // misdiagnosed as a memory problem, then as a guest problem, before anyone looked at the disk.
+    for (const worker of compare_workers_workers)vitalsBefore[worker] = await vitals(worker);
     const hostBefore = sampleHost();
-    // INTERLEAVED, round-robin. Measuring one worker for five minutes and then the next attributes any drift
-    // in the host during those ten minutes to the difference between the workers -- which is how a shared
-    // Mac running builds and browsers produces a confident wrong answer. Round-robin makes drift common.
-    process.stdout.write(`\nInterleaving ${runs} round(s) across ${workers.length} worker(s)\n`);
-    for (let round = 1; round <= runs; round++) {
-        for (const worker of workers) {
-            try {
-                const started = Date.now();
-                const result = await capture(worker);
-                const wall = Date.now() - started;
-                results[worker].walls.push(wall);
-                results[worker].phases.push(phaseCosts(result.diagnostics));
-                results[worker].sweeps.push(sweepDetail(result.diagnostics));
-                process.stdout.write(`  round ${round} ${short(worker)}: ${(wall / MS_PER_S).toFixed(1)}s ` +
-                    `${result.transcript?.length ?? 0} phrases\n`);
-            }
-            catch (error) {
-                process.stdout.write(`  round ${round} ${short(worker)}: FAILED ${ /** @type {any} */(error).message}\n`);
-            }
-        }
+    process.stdout.write(`\nInterleaving ${runs} round(s) across ${compare_workers_workers.length} worker(s)\n`);
+    for(let round = 1; round <= runs; round++)for (const worker of compare_workers_workers)try {
+        const started = Date.now();
+        const result = await capture(worker);
+        const wall = Date.now() - started;
+        results[worker].walls.push(wall);
+        results[worker].phases.push(phaseCosts(result.diagnostics));
+        results[worker].sweeps.push(sweepDetail(result.diagnostics));
+        process.stdout.write(`  round ${round} ${compare_workers_short(worker)}: ${(wall / MS_PER_S).toFixed(1)}s ${result.transcript?.length ?? 0} phrases\n`);
+    } catch (error) {
+        process.stdout.write(`  round ${round} ${compare_workers_short(worker)}: FAILED ${error.message}\n`);
     }
-    for (const worker of workers) {
+    for (const worker of compare_workers_workers){
         vitalsAfter[worker] = await vitals(worker);
         results[worker].diagnostics = await diagnostics(worker);
     }
-    report({ results, vitalsBefore, vitalsAfter, hostBefore });
+    report({
+        results,
+        vitalsBefore,
+        vitalsAfter,
+        hostBefore
+    });
 }
-/**
- * The comparison, and the verdict. Split from the MEASUREMENT half so neither exceeds the lint gate's
- * 70 lines and complexity 15 -- and because they are genuinely different jobs: one drives the workers,
- * the other decides what the numbers mean. `compare-workers` exists because reading two `bench-capture`
- * printouts side by side attributed a 2x difference to the wrong phase for hours.
- */
-function report(/** @type {any} */ { results, vitalsBefore, vitalsAfter, hostBefore }) {
-    // Shared by both tables below: which phases exist at all, and how to pull one worker's samples.
-    const allPhases = [...new Set(Object.values(results).flatMap((r) => r.phases.flatMap(Object.keys)))];
-    const phaseSamples = (/** @type {any} */ worker, /** @type {any} */ phase) => results[worker].phases.map((/** @type {any} */ p) => (p[phase] ?? 0) / MS_PER_S);
-    const { verdict, deltas } = reportWallTime({ results, vitalsBefore, vitalsAfter });
-    reportPhases({ results, allPhases, phaseSamples });
-    const { foundations, hostAfter } = reportFoundations({ hostBefore });
-    mkdirSync(OUT, { recursive: true });
-    writeFileSync(resolve(OUT, "compare.json"), JSON.stringify({ page, rounds: runs, results, verdict, recoveryDeltas: deltas,
-        foundations, hostBefore, hostAfter }, null, 2) + "\n", "utf8");
+function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
+    const allPhases = [
+        ...new Set(Object.values(results).flatMap((r)=>r.phases.flatMap(Object.keys)))
+    ];
+    const phaseSamples = (worker, phase)=>results[worker].phases.map((p)=>(p[phase] ?? 0) / MS_PER_S);
+    const { verdict, deltas } = reportWallTime({
+        results,
+        vitalsBefore,
+        vitalsAfter
+    });
+    reportPhases({
+        results,
+        allPhases,
+        phaseSamples
+    });
+    const { foundations, hostAfter } = reportFoundations({
+        hostBefore
+    });
+    mkdirSync(OUT, {
+        recursive: true
+    });
+    writeFileSync(resolve(OUT, "compare.json"), JSON.stringify({
+        page: page,
+        rounds: runs,
+        results,
+        verdict,
+        recoveryDeltas: deltas,
+        foundations,
+        hostBefore,
+        hostAfter
+    }, null, 2) + "\n", "utf8");
     process.stdout.write(`\nReport: ${resolve(OUT, "compare.json")}\n`);
 }
-/** Wall time and the verdict, first, because that is the question being asked. */
-function reportWallTime(/** @type {any} */ { results, vitalsBefore, vitalsAfter }) {
-    // Wall time first, with the verdict, because that is the question being asked.
-    const wallSeconds = Object.fromEntries(workers.map((w) => [short(w), results[w].walls.map((/** @type {any} */ v) => v / MS_PER_S)]));
+function reportWallTime({ results, vitalsBefore, vitalsAfter }) {
+    const wallSeconds = Object.fromEntries(compare_workers_workers.map((w)=>[
+            compare_workers_short(w),
+            results[w].walls.map((v)=>v / MS_PER_S)
+        ]));
     const verdict = compareWorkers(wallSeconds);
     process.stdout.write(`\n\nWALL TIME (seconds), ${runs} interleaved round(s)\n`);
-    process.stdout.write(`  ${"worker".padEnd(10)}${"n".padStart(4)}${"median".padStart(9)}${"IQR".padStart(9)}` +
-        `${"min".padStart(8)}${"max".padStart(8)}   recoveries\n`);
-    const deltas = Object.fromEntries(workers.map((w) => [short(w), {
-            recoveries: (vitalsAfter[w]?.recoveries ?? 0) - (vitalsBefore[w]?.recoveries ?? 0),
-            captures: (vitalsAfter[w]?.captures ?? 0) - (vitalsBefore[w]?.captures ?? 0),
-        }]));
-    const rates = /** @type {Record<string, any>} */ (recoveryRates(deltas));
-    for (const w of workers) {
-        const name = String(short(w)), d = summarise(wallSeconds[name]);
-        if (!d)
-            continue;
-        const rate = rates[name] === null ? "n/a" : `${deltas[name].recoveries}/${deltas[name].captures}`;
-        process.stdout.write(`  ${name.padEnd(10)}${String(d.n).padStart(4)}${d.median.toFixed(1).padStart(9)}` +
-            `${d.iqr.toFixed(1).padStart(9)}${d.min.toFixed(1).padStart(8)}${d.max.toFixed(1).padStart(8)}   ${rate}\n`);
+    process.stdout.write(`  ${"worker".padEnd(10)}${"n".padStart(4)}${"median".padStart(9)}${"IQR".padStart(9)}${"min".padStart(8)}${"max".padStart(8)}   recoveries\n`);
+    const deltas = Object.fromEntries(compare_workers_workers.map((w)=>[
+            compare_workers_short(w),
+            {
+                recoveries: (vitalsAfter[w]?.recoveries ?? 0) - (vitalsBefore[w]?.recoveries ?? 0),
+                captures: (vitalsAfter[w]?.captures ?? 0) - (vitalsBefore[w]?.captures ?? 0)
+            }
+        ]));
+    const rates = recoveryRates(deltas);
+    for (const w of compare_workers_workers){
+        const name = String(compare_workers_short(w)), d = describe(wallSeconds[name]);
+        if (!d) continue;
+        const rate = null === rates[name] ? "n/a" : `${deltas[name].recoveries}/${deltas[name].captures}`;
+        process.stdout.write(`  ${name.padEnd(10)}${String(d.n).padStart(4)}${d.median.toFixed(1).padStart(9)}${d.iqr.toFixed(1).padStart(9)}${d.min.toFixed(1).padStart(8)}${d.max.toFixed(1).padStart(8)}   ${rate}\n`);
     }
     process.stdout.write(`\n  ${verdict.verdict}\n`);
-    // Returned rather than written here: the JSON report is assembled once, by `report`, so one place
-    // decides what a comparison record contains.
-    return { verdict, deltas };
+    return {
+        verdict,
+        deltas
+    };
 }
-/** Where a real difference actually LIVES: per-phase medians, then the per-sweep detail. */
-function reportPhases(/** @type {any} */ { results, allPhases, phaseSamples }) {
-    // Per-phase medians, so a real difference can be located rather than guessed at.
+function reportPhases({ results, allPhases, phaseSamples }) {
     process.stdout.write(`\nPHASE MEDIANS (seconds)\n`);
-    process.stdout.write(`  ${"phase".padEnd(20)}${workers.map((/** @type {string} */ w) => String(short(w)).padStart(9)).join("")}    spread\n`);
-    const rows = allPhases
-        .map((/** @type {any} */ phase) => {
-        const medians = workers.map((w) => summarise(phaseSamples(w, phase))?.median ?? 0);
-        return { phase, medians, spread: Math.max(...medians) - Math.min(...medians) };
-    })
-        .filter((/** @type {any} */ row) => row.medians.some((/** @type {any} */ v) => v >= 0.05))
-        .sort((/** @type {any} */ a, /** @type {any} */ b) => b.spread - a.spread);
-    for (const { phase, medians, spread } of rows) {
-        process.stdout.write(`  ${phase.padEnd(20)}${medians.map((/** @type {any} */ v) => v.toFixed(1).padStart(9)).join("")}` +
-            `${spread.toFixed(1).padStart(10)}${spread >= 1 ? "  <-- diverges" : ""}\n`);
-    }
-    // The per-sweep view. `found` and `trips` separate "doing more work" from "doing work more slowly",
-    // which is the distinction the aggregate destroys and the one that identifies a cause.
-    const sweepTypes = [...new Set(Object.values(results).flatMap((r) => r.sweeps.flatMap(Object.keys)))];
+    process.stdout.write(`  ${"phase".padEnd(20)}${compare_workers_workers.map((w)=>String(compare_workers_short(w)).padStart(9)).join("")}    spread\n`);
+    const rows = allPhases.map((phase)=>{
+        const medians = compare_workers_workers.map((w)=>describe(phaseSamples(w, phase))?.median ?? 0);
+        return {
+            phase,
+            medians,
+            spread: Math.max(...medians) - Math.min(...medians)
+        };
+    }).filter((row)=>row.medians.some((v)=>v >= 0.05)).sort((a, b)=>b.spread - a.spread);
+    for (const { phase, medians, spread } of rows)process.stdout.write(`  ${phase.padEnd(20)}${medians.map((v)=>v.toFixed(1).padStart(9)).join("")}${spread.toFixed(1).padStart(10)}${spread >= 1 ? "  <-- diverges" : ""}\n`);
+    const sweepTypes = [
+        ...new Set(Object.values(results).flatMap((r)=>r.sweeps.flatMap(Object.keys)))
+    ];
     if (sweepTypes.length) {
         process.stdout.write("\nSWEEP DETAIL (mean ms / round trips / elements found)\n");
-        for (const type of sweepTypes) {
+        for (const type of sweepTypes){
             process.stdout.write(`  ${type.padEnd(14)}`);
-            for (const w of workers) {
-                const runsWith = results[w].sweeps.map((/** @type {any} */ s) => s[type]).filter(Boolean);
-                // Medians here too: one mute recovery inside a sweep skews a mean the same way it skews wall time.
-                const ms = (summarise(runsWith.map((/** @type {any} */ x) => x.ms))?.median ?? 0).toFixed(0);
-                const trips = (summarise(runsWith.map((/** @type {any} */ x) => x.trips))?.median ?? 0).toFixed(1);
-                const found = (summarise(runsWith.map((/** @type {any} */ x) => x.found))?.median ?? 0).toFixed(1);
-                process.stdout.write(`${short(w)}: ${ms}ms/${trips}t/${found}f   `);
+            for (const w of compare_workers_workers){
+                const runsWith = results[w].sweeps.map((s)=>s[type]).filter(Boolean);
+                const ms = (describe(runsWith.map((x)=>x.ms))?.median ?? 0).toFixed(0);
+                const trips = (describe(runsWith.map((x)=>x.trips))?.median ?? 0).toFixed(1);
+                const found = (describe(runsWith.map((x)=>x.found))?.median ?? 0).toFixed(1);
+                process.stdout.write(`${compare_workers_short(w)}: ${ms}ms/${trips}t/${found}f   `);
             }
             process.stdout.write("\n");
         }
         process.stdout.write("\n  ms up but trips flat => each round trip is slower (the guest or NVDA is the cause).\n");
         process.stdout.write("  trips up            => the sweep is genuinely walking more (the page or dedupe differs).\n");
     }
-    for (const w of workers) {
+    for (const w of compare_workers_workers){
         const d = results[w].diagnostics;
-        if (!d)
-            continue;
-        process.stdout.write(`\n  ${short(w)} guest: profile=${d.edgeProfile?.megabytes}MB ` +
-            `policy=${JSON.stringify(d.edgePolicy)} procs=${JSON.stringify(d.processes)}\n`);
+        if (d) process.stdout.write(`\n  ${compare_workers_short(w)} guest: profile=${d.edgeProfile?.megabytes}MB policy=${JSON.stringify(d.edgePolicy)} procs=${JSON.stringify(d.processes)}\n`);
     }
 }
-/**
- * The foundations. Timings alone say something got slower; they never say which resource ran out --
- * which is why three guests contending on one SSD was misdiagnosed as memory, then as the guests.
- */
-function reportFoundations(/** @type {any} */ { hostBefore }) {
+function reportFoundations({ hostBefore }) {
     const hostAfter = sampleHost();
-    const foundations = diffHost(/** @type {any} */ (hostBefore), /** @type {any} */ (hostAfter));
-    // These describe THE MACHINE THIS COMMAND RAN ON, which is the workers' machine only while the workers
-    // are local UTM guests. A bare-metal fleet is four separate computers, and this host's swap state then
-    // says nothing whatever about their capture times.
-    //
-    // It printed `352 pageouts <-- THE HOST WAS SWAPPING; these timings describe a constrained machine`
-    // during a four-box bare-metal run, next to `guest resident 0 MB across 0 process(es)` — the second line
-    // already saying there were no guests here to constrain. Attributing worker timings to the wrong
-    // computer is the exact failure this tool was written to stop; it should not commit it itself.
+    const foundations = diffHost(hostBefore, hostAfter);
     const localGuests = hostAfter.processes.length;
-    process.stdout.write(localGuests
-        ? "\nFOUNDATIONS (the host, during this run)\n"
-        : "\nFOUNDATIONS (this CONTROL host only — no local guests, so none of this describes the workers)\n");
-    process.stdout.write(`  load             ${hostAfter.load?.one ?? "?"} (1m), ` +
-        `${hostAfter.load?.five ?? "?"} (5m)\n`);
-    const busiest = [...(hostAfter.disk ?? [])].sort((a, b) => b.mbPerSecond - a.mbPerSecond)[0];
-    process.stdout.write(`  disk             ${busiest ? `${busiest.device} ${busiest.mbPerSecond} MB/s, ` +
-        `${busiest.transfersPerSecond} tps` : "unavailable"}\n`);
-    process.stdout.write(`  guest resident   ${foundations.residentMbTotal} MB across ` +
-        `${hostAfter.processes.length} process(es)   <- RSS, not phys_footprint\n`);
-    process.stdout.write(`  free / compressed ${foundations.freeMb} MB free, ` +
-        `${foundations.compressorMb} MB compressed\n`);
-    // The pageout DELTA is still worth printing either way — it is true about this machine. What is gated is
-    // the INFERENCE, because "these timings describe a constrained machine" is only true when the timings
-    // were produced here.
-    process.stdout.write(`  paging           ${foundations.pageoutsDelta} pageouts during the run` +
-        `${foundations.swappingDuringRun
-            ? (localGuests
-                ? "  <-- THE HOST WAS SWAPPING; these timings describe a constrained machine"
-                : "  (on this control host; the workers are elsewhere, so this did not affect them)")
-            : " (none)"}\n`);
+    process.stdout.write(localGuests ? "\nFOUNDATIONS (the host, during this run)\n" : "\nFOUNDATIONS (this CONTROL host only — no local guests, so none of this describes the workers)\n");
+    process.stdout.write(`  load             ${hostAfter.load?.one ?? "?"} (1m), ${hostAfter.load?.five ?? "?"} (5m)\n`);
+    const busiest = [
+        ...hostAfter.disk ?? []
+    ].sort((a, b)=>b.mbPerSecond - a.mbPerSecond)[0];
+    process.stdout.write(`  disk             ${busiest ? `${busiest.device} ${busiest.mbPerSecond} MB/s, ${busiest.transfersPerSecond} tps` : "unavailable"}\n`);
+    process.stdout.write(`  guest resident   ${foundations.residentMbTotal} MB across ${hostAfter.processes.length} process(es)   <- RSS, not phys_footprint\n`);
+    process.stdout.write(`  free / compressed ${foundations.freeMb} MB free, ${foundations.compressorMb} MB compressed\n`);
+    process.stdout.write(`  paging           ${foundations.pageoutsDelta} pageouts during the run${foundations.swappingDuringRun ? localGuests ? "  <-- THE HOST WAS SWAPPING; these timings describe a constrained machine" : "  (on this control host; the workers are elsewhere, so this did not affect them)" : " (none)"}\n`);
     if (!localGuests) {
         process.stdout.write("\n  No local guest processes were found, so these workers are REMOTE machines and nothing\n");
         process.stdout.write("  above describes them. For a bare-metal fleet, each worker's own /diagnostics is the\n");
         process.stdout.write("  equivalent: curl http://<worker>:8765/diagnostics | jq .\n");
     }
-    return { foundations, hostAfter };
+    return {
+        foundations,
+        hostAfter
+    };
 }
-// REALPATH'D: `import.meta.url` is resolved through symlinks by Node's ESM loader and `process.argv[1]`
-// is not, so a bin reached via its `.bin` symlink (which is how npm always installs one) mismatched here
-// and this guard silently read false — the tool loaded, did nothing, and exited 0. `/var` and `/tmp` are
-// themselves symlinks on macOS, so this fired every time. Same defect, same fix, as `cli.ts`'s `isProgram`.
-if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href)
-    await main();
-//# sourceMappingURL=compare-workers.mjs.map
+if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href) await main();