@a11ign/screenreader-fleet 0.0.0-reserved.0 → 0.2.0

package/dist/host-metrics.d.mts

@@ -0,0 +1,116 @@
+/**
+ * Parse `vm_stat`. Pure — the arithmetic is where this goes wrong, not the shelling out.
+ *
+ * The page size is read from the output rather than assumed: it is 16 KB on Apple Silicon and 4 KB on
+ * Intel, and hardcoding 4096 would understate every figure on this machine by a factor of four.
+ *
+ * @param {string} output
+ */
+export function parseVmStat(output: string): {
+    freeMb: number;
+    activeMb: number;
+    inactiveMb: number;
+    wiredMb: number;
+    compressorMb: number;
+    pageins: number;
+    pageouts: number;
+} | null;
+/**
+ * Parse `iostat -d -c 2` — the disk columns for each device.
+ *
+ * The FIRST sample from iostat is an average since boot and is meaningless for a measurement window;
+ * callers must use the second. Getting that wrong reports a busy disk as idle and vice versa.
+ *
+ * @param {string} output
+ * @returns {Array<{device: string, kbPerTransfer: number, transfersPerSecond: number, mbPerSecond: number}>}
+ */
+export function parseIostat(output: string): Array<{
+    device: string;
+    kbPerTransfer: number;
+    transfersPerSecond: number;
+    mbPerSecond: number;
+}>;
+/**
+ * Load averages, or null.
+ * @param {string} output
+ */
+export function parseLoadAverage(output: string): {
+    one: number;
+    five: number;
+    fifteen: number;
+} | null;
+/**
+ * RESIDENT size per process. Not footprint — `ps` has no such column; see this module's header for why
+ * that is a deliberate limit rather than an oversight, and what to read beside it.
+ *
+ * @param {string} psOutput output of `ps -o pid=,rss=,comm=`
+ * @param {string} match substring of the command to keep
+ */
+export function parseProcessMemory(psOutput: string, match: string): {
+    pid: number;
+    residentMb: number;
+    command: string;
+}[];
+/**
+ * One snapshot of the foundations.
+ *
+ * `iostat -c 2 -w 1` deliberately takes two samples a second apart and uses the second, because the
+ * first is a since-boot average. That makes this call cost ~1 s, which is why it is a snapshot taken
+ * around a measurement rather than something polled continuously.
+ *
+ * @param {{ processMatch?: string }} options
+ */
+export function sampleHost({ processMatch }?: {
+    processMatch?: string;
+}): {
+    at: string;
+    memory: {
+        freeMb: number;
+        activeMb: number;
+        inactiveMb: number;
+        wiredMb: number;
+        compressorMb: number;
+        pageins: number;
+        pageouts: number;
+    } | null;
+    disk: {
+        device: string;
+        kbPerTransfer: number;
+        transfersPerSecond: number;
+        mbPerSecond: number;
+    }[];
+    load: {
+        one: number;
+        five: number;
+        fifteen: number;
+    } | null;
+    processes: {
+        pid: number;
+        residentMb: number;
+        command: string;
+    }[];
+};
+/**
+ * @param {HostSnapshot} before
+ * @param {HostSnapshot} after
+ */
+export function diffHost(before: HostSnapshot, after: HostSnapshot): {
+    pageoutsDelta: number;
+    pageinsDelta: number;
+    swappingDuringRun: boolean;
+    compressorMb: number | null;
+    freeMb: number | null;
+    residentMbTotal: number;
+};
+/**
+ * Named because the first attempt at annotating this called it `Record<string, number>` -- flat numbers,
+ * which is what the CALL SITES read out of it and not what it is. A shape guessed from its uses is the
+ * same defect as a type inferred from its defaults, one file over.
+ */
+export type HostSnapshot = {
+    memory?: Record<string, number>;
+    processes?: {
+        residentMb: number;
+    }[];
+};
+//# sourceMappingURL=host-metrics.d.mts.map

package/dist/host-metrics.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-metrics.d.mts","sourceRoot":"","sources":["../src/host-metrics.mjs"],"names":[],"mappings":"AAmDA;;;;;;;GAOG;AACH,oCAFW,MAAM;;;;;;;;SAkBhB;AAED;;;;;;;;GAQG;AACH,oCAHW,MAAM,GACJ,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAAC,CAiB3G;AAED;;;GAGG;AACH,yCAFW,MAAM;;;;SAKhB;AAED;;;;;;GAMG;AACH,6CAHW,MAAM,SACN,MAAM;;;;IAWhB;AAUD;;;;;;;;GAQG;AACH,8CAFW;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;gBA7DR,MAAM;uBAAiB,MAAM;4BAAsB,MAAM;qBAAe,MAAM;;;;;;;;;;;;EAwEzG;AA2BD;;;GAGG;AACH,iCAHW,YAAY,SACZ,YAAY;;;;;;;EAmBtB;;;;;;2BApCY;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE"}

package/dist/host-metrics.mjs

@@ -0,0 +1,201 @@
+// @ts-check
+/**
+ * What the HOST was doing while a measurement ran: CPU, disk, memory.
+ *
+ * ## Why this exists
+ *
+ * Every performance conclusion in this project has been drawn from wall-clock time and phase marks,
+ * and the causes were misattributed three times in one day — first to memory, then to the guests
+ * themselves, then to contention in the abstract. The actual bottleneck was **disk I/O from Chromium
+ * cold-starting on three guests at once**, and it was invisible because nothing ever measured it.
+ *
+ * A timing number without the foundations underneath it does not identify a cause; it only says
+ * something got slower. These are the four things that were being guessed at:
+ *
+ *   CPU     load average and the guests' own share. Ruled contention in or out.
+ *   DISK    transfers/s and MB/s. The one that mattered, and the one never sampled.
+ *   MEMORY  RESIDENT bytes, not `phys_footprint`.
+ *   PAGING  pageouts and compressor size — the difference between "tight" and "thrashing".
+ *
+ * ## phys_footprint is a charge, not occupancy — this is the mistake it caused
+ *
+ * `MEMORY_PER_WORKER_MB` was set three times (7,600 then 8,100 then 5,600) from `top`'s memory column,
+ * which on macOS is `phys_footprint`: it counts compressed and swapped-out pages as though they were
+ * resident. Three guests showing 5.8 GB each — 17.4 GB "used" — held **3.8 GB of actual RAM** between
+ * them, with 7.8 GB sitting in the compressor. The capacity model reserved roughly four times what a
+ * worker occupies and concluded the Mac could only run two. Resident size is reported here for exactly
+ * that reason.
+ *
+ * **FOOTPRINT IS NOT REPORTED, and this header claimed it was.** The sentence used to end "footprint is
+ * reported alongside it so the gap between them stays visible", and `parseProcessMemory`'s own docstring
+ * promised "Resident size AND footprint per process". Neither is true: the source is
+ * `ps -o pid=,rss=,comm=`, which has no footprint column, and the returned records carry only `residentMb`.
+ * A documented remedy that was never implemented, vouched for by two comments.
+ *
+ * That matters because RSS is the reading that lies in the one state worth detecting: a starved guest
+ * showed `rss=0.4 GB` while its `phys_footprint` was 8.1 GB, its pages being in swap. So `residentMbTotal`
+ * FALLS as a host gets sicker — the same self-defeating shape as reading `vm_stat` for available memory.
+ *
+ * Do not read it alone. `compressorMb` and the pageout DELTA come from `vm_stat` in the same snapshot and
+ * are not distorted that way: low resident WITH a large compressor is a host absorbing pressure, and a
+ * non-zero pageout delta is one that is swapping. `compare-workers.mjs` prints all three together and
+ * labels the RSS column "<- RSS, not phys_footprint", which is why the missing field never misled anyone.
+ *
+ * Adding footprint means `top -l 1 -o mem -stats mem`, which costs a second and a fragile parse; the
+ * pairing above answers the same question from a snapshot already being taken. Recorded rather than done,
+ * so the next reader is not told a field exists that does not.
+ */
+import { execFileSync } from "node:child_process";
+const BYTES_PER_MB = 1024 * 1024;
+/**
+ * Parse `vm_stat`. Pure — the arithmetic is where this goes wrong, not the shelling out.
+ *
+ * The page size is read from the output rather than assumed: it is 16 KB on Apple Silicon and 4 KB on
+ * Intel, and hardcoding 4096 would understate every figure on this machine by a factor of four.
+ *
+ * @param {string} output
+ */
+export function parseVmStat(output) {
+    const pageSize = Number(/page size of (\d+) bytes/.exec(output)?.[1]);
+    if (!Number.isFinite(pageSize))
+        return null;
+    const pages = (/** @type {string} */ label) => Number(new RegExp(`${label}:\\s+(\\d+)`).exec(output)?.[1] ?? 0);
+    const mb = (/** @type {string} */ 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"),
+        // Compressed pages live in RAM. A large compressor with low `free` is a host absorbing pressure,
+        // which is a different state from one that is swapping, and they need different responses.
+        compressorMb: mb("Pages occupied by compressor"),
+        pageins: pages("Pageins"),
+        pageouts: pages("Pageouts"),
+    };
+}
+/**
+ * Parse `iostat -d -c 2` — the disk columns for each device.
+ *
+ * The FIRST sample from iostat is an average since boot and is meaningless for a measurement window;
+ * callers must use the second. Getting that wrong reports a busy disk as idle and vice versa.
+ *
+ * @param {string} output
+ * @returns {Array<{device: string, kbPerTransfer: number, transfersPerSecond: number, mbPerSecond: number}>}
+ */
+export function parseIostat(output) {
+    const lines = String(output).trim().split(/\r?\n/);
+    const header = lines.findIndex((l) => /^\s*disk/.test(l));
+    if (header === -1)
+        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[i * 3] ?? 0,
+        transfersPerSecond: numbers[i * 3 + 1] ?? 0,
+        mbPerSecond: numbers[i * 3 + 2] ?? 0,
+    })).filter((d) => Number.isFinite(d.mbPerSecond));
+}
+/**
+ * Load averages, or null.
+ * @param {string} output
+ */
+export 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;
+}
+/**
+ * RESIDENT size per process. Not footprint — `ps` has no such column; see this module's header for why
+ * that is a deliberate limit rather than an oversight, and what to read beside it.
+ *
+ * @param {string} psOutput output of `ps -o pid=,rss=,comm=`
+ * @param {string} match substring of the command to keep
+ */
+export function parseProcessMemory(psOutput, match) {
+    // `flatMap` rather than map -> filter -> map. The old shape checked `m &&` and was correct at runtime,
+    // but a filter cannot narrow a type for the two lines after it, so every field access read as a
+    // possible null. Doing the match and the decision in one place needs no narrowing to explain.
+    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 = (/** @type {string} */ cmd, /** @type {string[]} */ args) => {
+    try {
+        return execFileSync(cmd, args, { encoding: "utf8", timeout: 15_000 });
+    }
+    catch {
+        return ""; // a missing tool must never break a measurement; the field just reads null
+    }
+};
+/**
+ * One snapshot of the foundations.
+ *
+ * `iostat -c 2 -w 1` deliberately takes two samples a second apart and uses the second, because the
+ * first is a since-boot average. That makes this call cost ~1 s, which is why it is a snapshot taken
+ * around a measurement rather than something polled continuously.
+ *
+ * @param {{ processMatch?: string }} options
+ */
+export 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),
+    };
+}
+/**
+ * What changed between two snapshots.
+ *
+ * Paging is reported as a DELTA because the absolute counters are since-boot and therefore enormous
+ * and useless: 6.6 GB of swap left over from an incident hours ago looks identical to a host swapping
+ * right now. Only the delta distinguishes them, and that distinction was worth an afternoon.
+ */
+// Every `?.` and `??` is a branch, so six inlined reads of a possibly-absent snapshot pushed diffHost
+// to a complexity of 21 against a limit of 15 -- without being any clearer than naming the read once.
+/**
+ * @typedef {{ memory?: Record<string, number>, processes?: { residentMb: number }[] }} HostSnapshot
+ *
+ * Named because the first attempt at annotating this called it `Record<string, number>` -- flat numbers,
+ * which is what the CALL SITES read out of it and not what it is. A shape guessed from its uses is the
+ * same defect as a type inferred from its defaults, one file over.
+ */
+/**
+ * @param {HostSnapshot} snapshot
+ * @param {string} field
+ * @param {number | null} fallback
+ * @returns {number | null}
+ */
+const reading = (snapshot, field, fallback) => snapshot?.memory?.[field] ?? fallback;
+/**
+ * @param {HostSnapshot} before
+ * @param {HostSnapshot} after
+ */
+export function diffHost(before, after) {
+    // `?? 0` at the call, so these two stay plain numbers: a delta of two absent readings is 0, which is
+    // what "the host did not swap" has always meant here. `compressorMb` and `freeMb` below keep null,
+    // because an ABSENT reading and a reading of zero are different facts about the host and this file's
+    // whole purpose is that a number carries what it was computed from.
+    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,
+        // The honest headline. Non-zero pageouts during a measurement means the host was swapping and the
+        // timing describes a constrained machine, not the software under test.
+        swappingDuringRun: pageouts > 0,
+        compressorMb: reading(after, "compressorMb", null),
+        freeMb: reading(after, "freeMb", null),
+        residentMbTotal: (after?.processes ?? []).reduce((sum, p) => sum + p.residentMb, 0),
+    };
+}
+//# sourceMappingURL=host-metrics.mjs.map

package/dist/host-metrics.mjs.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Host-side worker fleet: lease a Windows capture worker, judge its health, and know how many the host can
+ * actually afford to run.
+ *
+ * None of this touches guidepup or NVDA — it runs on the machine that *drives* the workers, which is why it is
+ * a separate package from `@a11ign/screenreader-worker` (ADR 0004). The split is not cosmetic: the worker is
+ * Windows-only and the fleet is not.
+ *
+ * The measurement internals — `host-metrics`, `worker-stats`, `fleet-consistency` — are deliberately NOT
+ * exported. Their shapes change every time something new gets measured, and this project's own history is a
+ * record of that happening.
+ */
+export { DEFAULT_WORKER, isAfterRun, leaseWorker, leaseWorkerPool, hostAddressForWorker, guestReachableUrl, } from "./local-vm.js";
+export type { AfterRun, WorkerLease, PoolLease } from "./local-vm.js";
+/**
+ * The provisioning and lifecycle scripts, as absolute paths.
+ *
+ * They are shell and PowerShell, not JavaScript, so a consumer has to spawn them — and they can only be found
+ * relative to the module. Delegated to `fleet-scripts.mjs` so this package has exactly ONE definition of where
+ * they live: it had four, and one of them was wrong, which broke `leaseWorker` silently.
+ */
+export declare function fleetScriptPaths(): Record<string, string>;
+//# 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;;;;;;;;;;;GAWG;AACH,OAAO,EACL,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,oBAAoB,EAAE,iBAAiB,GAClG,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAItE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzD"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * Host-side worker fleet: lease a Windows capture worker, judge its health, and know how many the host can
+ * actually afford to run.
+ *
+ * None of this touches guidepup or NVDA — it runs on the machine that *drives* the workers, which is why it is
+ * a separate package from `@a11ign/screenreader-worker` (ADR 0004). The split is not cosmetic: the worker is
+ * Windows-only and the fleet is not.
+ *
+ * The measurement internals — `host-metrics`, `worker-stats`, `fleet-consistency` — are deliberately NOT
+ * exported. Their shapes change every time something new gets measured, and this project's own history is a
+ * record of that happening.
+ */
+export { DEFAULT_WORKER, isAfterRun, leaseWorker, leaseWorkerPool, hostAddressForWorker, guestReachableUrl, } from "./local-vm.js";
+import { fleetScriptPaths as scriptPaths } from "./fleet-scripts.mjs";
+/**
+ * The provisioning and lifecycle scripts, as absolute paths.
+ *
+ * They are shell and PowerShell, not JavaScript, so a consumer has to spawn them — and they can only be found
+ * relative to the module. Delegated to `fleet-scripts.mjs` so this package has exactly ONE definition of where
+ * they live: it had four, and one of them was wrong, which broke `leaseWorker` silently.
+ */
+export function fleetScriptPaths() {
+    return scriptPaths();
+}
+//# 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;;;;;;;;;;;GAWG;AACH,OAAO,EACL,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,oBAAoB,EAAE,iBAAiB,GAClG,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,gBAAgB,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC"}

package/dist/local-vm.d.ts

@@ -0,0 +1,125 @@
+/** Where a hand-started worker on this machine has always lived. */
+export declare const DEFAULT_WORKER = "http://localhost:8765";
+/** What to do with the VM once the run finishes. */
+export type AfterRun = "restore" | "stop" | "pause" | "leave";
+export declare function isAfterRun(v: string): v is AfterRun;
+interface VmStatus {
+    uuid: string;
+    name: string;
+    /** utmctl's own vocabulary: "started" | "paused" | "stopped" | "unknown". */
+    state: string;
+    ip: string;
+    port: number;
+    healthy: boolean;
+    /** True while a capture is in flight -- the worker's own flag. */
+    busy: boolean;
+}
+/** A worker to capture against, and the cleanup that matches how it was obtained. */
+export interface WorkerLease {
+    worker: string;
+    /** How `worker` was chosen, so callers can tailor their own error messages. */
+    source: "explicit" | "inventory.yml" | "local-vm" | "default";
+    /**
+     * The address the GUEST can use to reach THIS host, when capturing via a local VM.
+     * Undefined otherwise. Needed because anything the host serves on `localhost` is
+     * unreachable from the guest -- `localhost` there means the guest itself.
+     */
+    hostAddress?: string;
+    /** Never throws: a cleanup failure must not mask the run's own result. */
+    release: () => Promise<void>;
+}
+/**
+ * The registered local VM, or null when there is nothing to manage: not macOS, no UTM, no
+ * VM registered under that name, or duplicate registrations (worker-ctl refuses to guess
+ * between those rather than risk acting on the wrong one).
+ */
+export declare function findLocalVm(): Promise<VmStatus | null>;
+/**
+ * Start (or resume) the local VM, returning its worker URL and the matching cleanup.
+ * Throws if the VM never becomes healthy -- there is no point judging a capture that could
+ * not happen.
+ */
+export declare function acquireLocalWorker(vm: VmStatus, after: AfterRun): Promise<WorkerLease>;
+interface LeaseRequest {
+    /** A worker the caller was given explicitly (--worker / A11Y_WORKER), or null. */
+    worker: string | null;
+    after: AfterRun;
+}
+/**
+ * Decide what to capture against, in priority order:
+ *
+ *   1. A worker the caller named is used as-is. Naming one is a statement that you are
+ *      managing it yourself, so the VM lifecycle is never touched.
+ *   2. Otherwise, `inventory.yml`'s bare-metal fleet — always-on boxes, so there is no VM
+ *      lifecycle to run: the first declared worker is leased with a no-op release.
+ *   3. Otherwise, a registered local UTM VM is started on demand and released afterwards.
+ *   4. Otherwise, the historical default, so a hand-run worker on this machine still works.
+ *
+ * FOUND 2026-09-06 (`docs/backlog.md` §8): this used to go straight from (1) to (3), never
+ * reading the inventory at all -- so a checkout WITH a bare-metal fleet declared and a UTM guest
+ * still registered (the ordinary state of a Mac that used to run the deprecated pool) leased the
+ * VM by default, exactly the wrong turn CLAUDE.md already records costing a capture-path change:
+ * "a deprecated path that is still the first one documented is not deprecated". `resolveWorkerPool`
+ * (`fleet-env.mjs`) already had the corrected order for the POOL case; this brings the single-worker
+ * case into line, and `worker-precedence.test.ts` is what is supposed to keep them there.
+ *
+ * Step 2 costs nothing and throws nothing for anyone without an `inventory.yml` -- a public
+ * consumer who installs this package -- because `inventoryWorkerUrls()` already treats an absent
+ * or unparsable file as "no fleet declared here" and returns `[]`. So the fall-through to (3) and
+ * (4) is byte-for-byte what it was before this change for that consumer; only a checkout that
+ * DECLARES a fleet sees new behaviour, and it sees the behaviour `doctor` and `worker:code`
+ * already assumed it had.
+ *
+ * A11Y_LOCAL_VM=0 skips step 3 for anyone who wants the pre-inventory local-VM behaviour back --
+ * unchanged in what it does, moved because inventory now sits ahead of it.
+ *
+ * Shared by every entry point that needs a worker, so the priority order cannot drift
+ * between them.
+ *
+ * `deps` is the injection seam: real callers get the real inventory reader and the real (shells
+ * out to `utmctl`) VM lookup, and a test supplies fakes for both, so the precedence can be proven
+ * without a filesystem `inventory.yml` or a UTM install. Called as `deps.inventory?.() ?? inventoryWorkerUrls()`
+ * rather than resolved into a local first — deliberately, so `inventoryWorkerUrls(` and `findLocalVm(`
+ * both appear as real CALLS at the exact decision point, which is what lets `worker-precedence.test.ts`
+ * read this function's actual order rather than only the shape of its signature.
+ */
+export declare function leaseWorker({ worker, after }: LeaseRequest, deps?: {
+    inventory?: () => string[];
+    findLocalVm?: () => Promise<VmStatus | null>;
+}): Promise<WorkerLease>;
+/**
+ * Rewrite a base URL the GUEST has to fetch so it points at this host rather than at
+ * `localhost`, which from inside the guest means the guest.
+ *
+ * This is the trap in dataset capture: the pages are served by a plain HTTP server on the
+ * Mac, and the default base URL is `http://localhost:5050`. Left alone, every capture
+ * loads the guest's own empty port and the transcripts come back describing nothing --
+ * with no error, because a connection refused inside Edge is not a worker failure.
+ */
+/**
+ * This host's address as seen from a worker at `workerUrl`, when the two share a subnet.
+ * Returns undefined for a hostname, or for a worker somewhere we have no interface onto --
+ * in which case the caller must be told where to reach us rather than have it guessed.
+ */
+export declare function hostAddressForWorker(workerUrl: string): string | undefined;
+export declare function guestReachableUrl(baseUrl: string, lease: WorkerLease): string;
+/** Several workers, and the cleanup that puts every one of them back as it was found. */
+export interface PoolLease {
+    workers: string[];
+    hostAddress?: string;
+    release: () => Promise<void>;
+}
+/**
+ * Lease every local worker VM: start what is not running, and put each one back afterwards.
+ *
+ * This exists because the pool path used to hand back a no-op release, so a pooled run left
+ * every VM running indefinitely — which is precisely the cost the single-worker lease was
+ * written to avoid, reintroduced the moment pooling became the normal way to run.
+ *
+ * Per-VM restore, not a blanket stop: a VM you had already started stays started, exactly as
+ * in the single-worker case. A long dataset run must not shut down a worker somebody else is
+ * using, and with a pool that is likelier, not less.
+ */
+export declare function leaseWorkerPool(after: AfterRun): Promise<PoolLease | null>;
+export {};
+//# sourceMappingURL=local-vm.d.ts.map

package/dist/local-vm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-vm.d.ts","sourceRoot":"","sources":["../src/local-vm.ts"],"names":[],"mappings":"AA0BA,oEAAoE;AACpE,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAWtD,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAI9D,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,QAAQ,CAEnD;AAED,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,EAAE,UAAU,GAAG,eAAe,GAAG,UAAU,GAAG,SAAS,CAAC;IAC9D;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAuCD;;;;GAIG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAY5D;AAuBD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CA2B5F;AAED,UAAU,YAAY;IACpB,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,WAAW,CAC/B,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,YAAY,EAC/B,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;CAAO,GACtF,OAAO,CAAC,WAAW,CAAC,CAqBtB;AAED;;;;;;;;GAQG;AACH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,CAc7E;AAED,yFAAyF;AACzF,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAuCD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA8DhF"}