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

package/dist/transient-fault.mjs

@@ -0,0 +1,86 @@
+// @ts-check
+/**
+ * Is a capture-worker failure recoverable, or the end of this case?
+ *
+ * MOVED HERE from `packages/lab/src/training/capture-decisions.mjs` — architecture-audit.md §5, item 3:
+ * "the protocol version and fault codes are reached by scraping" because no shared, dependency-free home
+ * existed for classification that both the lab AND anything else speaking to a worker over HTTP need. This
+ * package already exists for exactly that ("host-side lifecycle, health and capacity for a fleet of
+ * Windows NVDA capture workers"), and `capture-client.mjs` — which needs this to decide whether a lost
+ * response is worth reconciling rather than failing outright — moved here alongside it for the same
+ * reason: `packages/cli` can depend on `@a11ign/screenreader-fleet` (it already does, for `requestJson`)
+ * but must never depend on `@a11ign/lab`, which is private and never published.
+ *
+ * `capture-decisions.mjs` re-exports `isTransient` from here so every existing lab-side importer is
+ * unchanged.
+ */
+// BY CODE, from the module that defines them — architecture-audit.md §5, item 3 and item 4: "fault codes
+// are copied as string literals... because no ./capture-faults subpath is exported". `capture-faults.mjs`
+// has no imports of its own, so it was always safe to expose; the subpath just did not exist. Reading the
+// actual codes here means a renamed fault cannot silently stop being recognised as recoverable.
+import { FAULT } from "@a11ign/screenreader-worker/capture-faults";
+/**
+ * Recoverable, or the end of this case?
+ *
+ * Everything here heals on its own, which is why waiting beats failing. The connection errors are
+ * here because the first full dataset run lost its last four cases to one guest bugchecking — it came
+ * back by itself, but the run had already recorded four permanent failures.
+ *
+ * `running but not speaking` and `hard timeout` are the subtle ones: both make the worker STOP its
+ * screen reader, so the next capture cold-starts a fresh one. They are self-healing by construction,
+ * and classifying them fatal cost a case in the run that proved it.
+ */
+const TRANSIENT = new RegExp([
+    "fetch failed", "ECONNREFUSED", "ECONNRESET", "socket hang up", "timed out", "aborted",
+    "HTTP 429.*capture is already in progress",
+    "running but not speaking",
+    "hard timeout",
+].join("|"), "i");
+/**
+ * Faults the WORKER named for us, which never need matching against prose.
+ *
+ * Both self-heal: the worker stops NVDA on any failed capture, so the next attempt cold-starts a clean
+ * one. The worker now retries these itself before answering, so seeing one here means even its retry
+ * did not clear it — still worth reissuing the case rather than recording a permanent failure.
+ */
+const TRANSIENT_FAULTS = new Set([FAULT.SCREEN_READER_MUTE, FAULT.SCREEN_READER_START_FAILED]);
+/**
+ * Network failures that heal on their own, by CODE rather than by wording.
+ *
+ * These became visible when the capture clients moved off `fetch` to `node:http` (see
+ * `worker-fleet/src/worker-http.mjs` for why they had to). `fetch` collapsed every network failure into
+ * `TypeError: fetch failed`, which the regex above matched — so the whole class was transient by accident,
+ * through a wrapper's wording rather than through anything we had decided.
+ *
+ * `EHOSTUNREACH` is the one that would have bitten. It is how a bare-metal worker presents while its NIC
+ * wakes from selective suspend, recorded in provision-nvda-worker.ps1: 48 instant failures in one
+ * evidence-check run, and the box answered a curl thirty seconds later. Under the real code, and without
+ * this set, that would now be classified FATAL and fail 48 cases permanently.
+ *
+ * `ETIMEDOUT` covers both a dead peer and our own deadline in `requestJson`, which is deliberate: a
+ * capture that outran its budget is exactly the case the worker recovers from by cold-starting NVDA.
+ */
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNREFUSED", "ECONNRESET", "EHOSTUNREACH", "ENETUNREACH", "ENETDOWN",
+    "EPIPE", "ETIMEDOUT", "EAI_AGAIN", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT",
+]);
+/**
+ * @param {unknown} error  anything a failed request threw — a node:http Error, an undici one, a string
+ * @returns {boolean}
+ */
+export function isTransient(error) {
+    const failure = /** @type {{ code?: string, cause?: { code?: string }, message?: string }} */ (error);
+    // Prefer the code. The regex below is the fallback for older workers and for host-side failures
+    // (a dropped socket has no fault code), but a message is prose and prose gets reworded — see
+    // packages/nvda-worker/src/capture-faults.mjs for what that cost.
+    if (TRANSIENT_FAULTS.has(failure?.code ?? ""))
+        return true;
+    if (TRANSIENT_NETWORK_CODES.has(failure?.code ?? ""))
+        return true;
+    // A node:http error carries its code on the error itself; an undici one hides it on `cause`. Checking
+    // both means the classification does not depend on which client the caller happened to use.
+    if (TRANSIENT_NETWORK_CODES.has(failure?.cause?.code ?? ""))
+        return true;
+    return TRANSIENT.test(String(failure?.message ?? error ?? ""));
+}
+//# sourceMappingURL=transient-fault.mjs.map

package/dist/transient-fault.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transient-fault.mjs","sourceRoot":"","sources":["../src/transient-fault.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;GAcG;AACH,yGAAyG;AACzG,0GAA0G;AAC1G,0GAA0G;AAC1G,gGAAgG;AAChG,OAAO,EAAE,KAAK,EAAE,MAAM,4CAA4C,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC;IAC3B,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS;IACtF,0CAA0C;IAC1C,0BAA0B;IAC1B,cAAc;CACf,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;AAE/F;;;;;;;;;;;;;;;GAeG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC;IACtC,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU;IACvE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,yBAAyB,EAAE,sBAAsB;CACrF,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAK;IAC/B,MAAM,OAAO,GAAG,6EAA6E,CAAC,CAAC,KAAK,CAAC,CAAC;IACtG,gGAAgG;IAChG,6FAA6F;IAC7F,kEAAkE;IAClE,IAAI,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,uBAAuB,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,sGAAsG;IACtG,4FAA4F;IAC5F,IAAI,uBAAuB,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/dist/utm-deprecated.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @param {string} what The command or module the caller is about to run — named so the message is
+ *   specific to what actually fired, not a generic banner every UTM-adjacent file prints identically.
+ */
+export function warnUtmDeprecated(what: string): void;
+//# sourceMappingURL=utm-deprecated.d.mts.map

package/dist/utm-deprecated.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utm-deprecated.d.mts","sourceRoot":"","sources":["../src/utm-deprecated.mjs"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wCAHW,MAAM,QAShB"}

package/dist/utm-deprecated.mjs

@@ -0,0 +1,23 @@
+// @ts-check
+// One deprecation notice, said the same way everywhere it applies.
+//
+// architecture-audit.md §8: "the deprecated UTM path is still the CLI's default" — ~2,460 lines of
+// UTM-only code still ship, and until this file existed, using any of them said nothing about it. The
+// repository owner stated plainly on 2026-09-05: "The UTM is deprecated, that was a testing thing." This
+// is the loud half CLAUDE.md's own rule calls for: "a deprecated path that is still the first one
+// documented is not deprecated" — printing nothing at the point of use is the runtime version of that
+// same mistake.
+//
+// A notice, not a refusal: some of these entry points are still how an existing UTM guest is reached
+// (worker-ctl.sh status, for instance), and this file does not decide which are safe to keep working —
+// that is a separate proposal. This only makes sure nobody reaches any of them without being told.
+/**
+ * @param {string} what The command or module the caller is about to run — named so the message is
+ *   specific to what actually fired, not a generic banner every UTM-adjacent file prints identically.
+ */
+export function warnUtmDeprecated(what) {
+    process.stderr.write(`DEPRECATED: ${what} manages a local UTM worker VM. UTM was a testing path and is not the fleet.\n` +
+        "Capture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy. See CLAUDE.md's\n" +
+        '"Working on a Mac" section.\n');
+}
+//# sourceMappingURL=utm-deprecated.mjs.map

package/dist/utm-deprecated.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utm-deprecated.mjs","sourceRoot":"","sources":["../src/utm-deprecated.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ,mEAAmE;AACnE,EAAE;AACF,mGAAmG;AACnG,sGAAsG;AACtG,yGAAyG;AACzG,kGAAkG;AAClG,sGAAsG;AACtG,gBAAgB;AAChB,EAAE;AACF,qGAAqG;AACrG,uGAAuG;AACvG,mGAAmG;AAEnG;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI;IACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,eAAe,IAAI,gFAAgF;QACnG,wGAAwG;QACxG,+BAA+B,CAChC,CAAC;AACJ,CAAC"}

package/dist/worker-code-check.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Refuse to capture with a fleet that is not running this checkout.
+ *
+ * Called at the boundary of every capture entry point, for the reason `assertWorkerUrl` is: the
+ * alternative is discovering it in the evidence weeks later, where a stale worker looks like a page that
+ * changed. **Both entry points, not one** — a remedy that reaches one of several paths is the shape this
+ * repo has paid for three times over (`anchorToTop`, `ensureSpeechChannel`, `waitForAnnouncement`), and
+ * `capture-preflight.test.ts` pins that both call it.
+ *
+ * A thin wrapper over `assertWorkersServe`, supplying the one thing only this file can compute: the hash.
+ *
+ * @param {string[]} workers
+ * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[]}} options
+ */
+export function assertFleetRunsThisCheckout(workers: string[], options?: {
+    when?: string;
+    allow?: boolean;
+    read?: (url: string) => Promise<string | null>;
+    bareMetalUrls?: string[];
+}): Promise<void>;
+export function expectedWorkerCode(): string;
+import { codeDrift } from "./code-drift.mjs";
+import { describeCodeDrift } from "./code-drift.mjs";
+import { describeEmptyPool } from "./code-drift.mjs";
+import { readWorkerCode } from "./code-drift.mjs";
+import { remedyLines } from "./code-drift.mjs";
+import { workerSourceDirty } from "./code-drift.mjs";
+export { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty };
+//# sourceMappingURL=worker-code-check.d.mts.map

package/dist/worker-code-check.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-code-check.d.mts","sourceRoot":"","sources":["../src/worker-code-check.mjs"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;GAaG;AACH,qDAHW,MAAM,EAAE,YACR;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAC,IAAI,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAC,iBAIlH;AAvBM,6CAA+D;0BAVvB,kBAAkB;kCAAlB,kBAAkB;kCAAlB,kBAAkB;+BAAlB,kBAAkB;4BAAlB,kBAAkB;kCAAlB,kBAAkB"}

package/dist/worker-code-check.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+/**
+ * Is the fleet running the code this checkout expects — asked BEFORE a capture run, not after it.
+ *
+ * ## The hole this closes
+ *
+ * `run-job.yml` refuses to run at a commit other than the one asked for, and the comment above that
+ * refusal says why: *"a job that quietly runs four commits behind reports success for code you did not
+ * ask for."* That guard covers the LAB. It says nothing about the twelve machines that actually take the
+ * captures, and those are a second checkout, deployed by a separate command nobody is forced to run.
+ *
+ * So a capture run could be dispatched at the right commit, on a lab that proved it was at the right
+ * commit, and still capture with the PREVIOUS release of `capture-core.mjs`. Measured on 2026-08-25: after
+ * `MAX_TAB_STOPS` went 12 -> 150 and `collectByType` started recording `prevCount`, the real-page corpus
+ * held both populations at once, and the only way to read it was to bucket captures by whether they
+ * carried the new diagnostic mark at all. The evidence was mixed, the run reported success, and the
+ * separation had to be done by hand afterwards.
+ *
+ * `npm run worker:code` has answered this question correctly the whole time. It is a separate command a
+ * human must remember, which is this repo's own definition of a check that does not happen — and it was
+ * remembered by hand four times in one day before this existed.
+ *
+ * ## Why a REFUSAL, and why on any difference at all
+ *
+ * `workerCode` is deliberately outside the capture cache key ("it changes when a comment changes, and
+ * invalidating the WHOLE corpus over a reworded comment is how a cache becomes something people turn
+ * off") and deliberately outside
+ * `fleet-consistency.mjs`'s `MUST_MATCH` for the same reason. Both of those are the right call for
+ * the questions they answer — *is this evidence still valid* and *are these guests interchangeable*.
+ *
+ * This is a third question with a different answer: *am I about to capture with the code I asked for*. A
+ * comment-only drift is a false alarm here and it costs one `fleet:deploy`; a real drift costs a corpus and
+ * is invisible, because nothing downstream keys on `workerCode`. That asymmetry is the whole argument.
+ *
+ * It is a PRECONDITION and never a key: nothing here invalidates a cached capture.
+ *
+ * ## The comparison itself lives in `code-drift.mjs`, and this file is the reason for the split
+ *
+ * `expectedWorkerCode` below needs `codeVersion`/`workerSourceDir`, reached through a SUBPATH export
+ * (`@a11ign/screenreader-worker/code-version`) rather than a relative path — a relative one drags
+ * `nvda-worker`'s `.mjs` files into this package's own tsc project and the build dies with TS5055 ("would
+ * overwrite input file"). That subpath resolves through `node_modules`, which is exactly what
+ * `packages/control` does not have (ADR 0012) — so when `lab-job.mjs` needed this same comparison BEFORE
+ * dispatching to the lab, it could not import this file. `code-drift.mjs` is the part of this file with no
+ * opinion about what "expected" means: it takes the hash as a parameter, imports nothing but
+ * `node:child_process`, and is safe from both places. This file supplies the one thing only it can compute.
+ */
+import { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty, assertWorkersServe } from "./code-drift.mjs";
+// A SUBPATH export, not a deep relative path: `../../nvda-worker/src/...` drags those .mjs files into
+// worker-fleet's tsc project and the build dies with TS5055 "would overwrite input file". The subpath is
+// also the shape already in use for the same reason -- `@a11ign/screenreader-fleet/worker-http`.
+// `code-version.mjs` imports nothing but node stdlib and `worker-files.mjs`, which is why it is safe and
+// why it is its own module. Still the ONE hasher: the subpath is the same function.
+import { codeVersion, workerSourceDir } from "@a11ign/screenreader-worker/code-version";
+/** The hash this checkout expects every worker to be serving. One hasher, shared with the guest. */
+export const expectedWorkerCode = () => codeVersion(workerSourceDir());
+// Re-exported rather than duplicated: existing callers (`capture-real-pages.mjs`,
+// `capture-screenreader-dataset.mjs`, and this module's own test) import these from here, and moving their
+// implementation to `code-drift.mjs` must not become a second place either has to be found.
+export { codeDrift, describeCodeDrift, describeEmptyPool, readWorkerCode, remedyLines, workerSourceDirty };
+/**
+ * Refuse to capture with a fleet that is not running this checkout.
+ *
+ * Called at the boundary of every capture entry point, for the reason `assertWorkerUrl` is: the
+ * alternative is discovering it in the evidence weeks later, where a stale worker looks like a page that
+ * changed. **Both entry points, not one** — a remedy that reaches one of several paths is the shape this
+ * repo has paid for three times over (`anchorToTop`, `ensureSpeechChannel`, `waitForAnnouncement`), and
+ * `capture-preflight.test.ts` pins that both call it.
+ *
+ * A thin wrapper over `assertWorkersServe`, supplying the one thing only this file can compute: the hash.
+ *
+ * @param {string[]} workers
+ * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[]}} options
+ */
+export async function assertFleetRunsThisCheckout(workers, options = {}) {
+    return assertWorkersServe(expectedWorkerCode(), workers, { ...options, sourceDir: workerSourceDir() });
+}
+//# sourceMappingURL=worker-code-check.mjs.map

package/dist/worker-code-check.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-code-check.mjs","sourceRoot":"","sources":["../src/worker-code-check.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EACnF,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAElE,sGAAsG;AACtG,yGAAyG;AACzG,iGAAiG;AACjG,yGAAyG;AACzG,oFAAoF;AACpF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAExF,oGAAoG;AACpG,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,eAAe,EAAE,CAAC,CAAC;AAEvE,kFAAkF;AAClF,2GAA2G;AAC3G,4FAA4F;AAC5F,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,CAAC;AAE3G;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,EAAE;IACrE,OAAO,kBAAkB,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,EAAE,CAAC,CAAC;AACzG,CAAC"}

package/dist/worker-health.d.mts

@@ -0,0 +1,56 @@
+/**
+ * Is a worker healthy, degraded, or unusable — from the vitals it reports.
+ *
+ * This exists because a guest whose NVDA was broken on **every single capture** sat in the pool at four
+ * times the cost of its neighbours and nothing noticed. Measured, same page, same code, same moment:
+ *
+ *   worker 1   4 captures, 4 recoveries, 0 failures   nvdaStart 19.1s/capture   WALL 122.9s
+ *   worker 2   9 captures, 0 recoveries, 0 failures   nvdaStart  0.0s/capture   WALL  40.6s
+ *
+ * Two things conspired to hide it. The worker's own retry absorbed every fault, so `failures` stayed 0
+ * and the run's eviction rule — three consecutive FAILURES — could never fire. And wall-clock time only
+ * said "slower", which I twice misattributed to Edge.
+ *
+ * So degradation is defined on the recovery RATE, not on failures. `recoveries` counts faults the worker
+ * papered over for the caller, which makes it the one number that rises while everything still appears
+ * to work.
+ *
+ * **Degraded workers keep taking work.** They are slow, not broken, and pulling one from a three-VM pool
+ * costs more throughput than it saves. This mirrors the standard health-check split — a degraded service
+ * returns 200 and is *surfaced* rather than restarted, because declaring degraded things unhealthy is how
+ * you end up with nothing left to serve (Distributed Systems with Node.js, ch. 4).
+ */
+/**
+ * Can this worker take a capture right now? ONE definition, because there were four that disagreed.
+ *
+ * `ready` is about the ENVIRONMENT — Edge resolvable, ForegroundLockTimeout 0, the worker free — and a
+ * worker reports `ready: false` while NVDA warms up after a boot, which is normal and self-correcting.
+ *
+ * The subtlety, and the reason this is `!== false` rather than `=== true`: **a worker predating the
+ * field reports neither.** Treating absent as ready keeps an un-redeployed guest working instead of
+ * stalling a run against it forever; staleness has its own detector in `npm run worker:code`. The
+ * dataset runner got this right and said so. `repeat-capture.mjs` tested `health.ready` for truthiness
+ * and `capture-real-pages.mjs` tested `=== true`, so both would have waited out their whole readiness
+ * budget against a perfectly good older worker and then blamed the page.
+ *
+ * @param {{ busy?: boolean, ready?: boolean } | null | undefined} health
+ * @returns {boolean}
+ */
+export function workerIsUsable(health: {
+    busy?: boolean;
+    ready?: boolean;
+} | null | undefined): boolean;
+/**
+ * @param {{ captures?: number, recoveries?: number, failures?: number } | null | undefined} vitals
+ * @returns {{ degraded: boolean, reason: string | null, recoveryShare: number | null }}
+ */
+export function assessWorker(vitals: {
+    captures?: number;
+    recoveries?: number;
+    failures?: number;
+} | null | undefined): {
+    degraded: boolean;
+    reason: string | null;
+    recoveryShare: number | null;
+};
+//# sourceMappingURL=worker-health.d.mts.map

package/dist/worker-health.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-health.d.mts","sourceRoot":"","sources":["../src/worker-health.mjs"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,uCAHW;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GACpD,OAAO,CAKnB;AAQD;;;GAGG;AACH,qCAHW;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC9E;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAqBtF"}

package/dist/worker-health.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * Is a worker healthy, degraded, or unusable — from the vitals it reports.
+ *
+ * This exists because a guest whose NVDA was broken on **every single capture** sat in the pool at four
+ * times the cost of its neighbours and nothing noticed. Measured, same page, same code, same moment:
+ *
+ *   worker 1   4 captures, 4 recoveries, 0 failures   nvdaStart 19.1s/capture   WALL 122.9s
+ *   worker 2   9 captures, 0 recoveries, 0 failures   nvdaStart  0.0s/capture   WALL  40.6s
+ *
+ * Two things conspired to hide it. The worker's own retry absorbed every fault, so `failures` stayed 0
+ * and the run's eviction rule — three consecutive FAILURES — could never fire. And wall-clock time only
+ * said "slower", which I twice misattributed to Edge.
+ *
+ * So degradation is defined on the recovery RATE, not on failures. `recoveries` counts faults the worker
+ * papered over for the caller, which makes it the one number that rises while everything still appears
+ * to work.
+ *
+ * **Degraded workers keep taking work.** They are slow, not broken, and pulling one from a three-VM pool
+ * costs more throughput than it saves. This mirrors the standard health-check split — a degraded service
+ * returns 200 and is *surfaced* rather than restarted, because declaring degraded things unhealthy is how
+ * you end up with nothing left to serve (Distributed Systems with Node.js, ch. 4).
+ */
+/**
+ * Can this worker take a capture right now? ONE definition, because there were four that disagreed.
+ *
+ * `ready` is about the ENVIRONMENT — Edge resolvable, ForegroundLockTimeout 0, the worker free — and a
+ * worker reports `ready: false` while NVDA warms up after a boot, which is normal and self-correcting.
+ *
+ * The subtlety, and the reason this is `!== false` rather than `=== true`: **a worker predating the
+ * field reports neither.** Treating absent as ready keeps an un-redeployed guest working instead of
+ * stalling a run against it forever; staleness has its own detector in `npm run worker:code`. The
+ * dataset runner got this right and said so. `repeat-capture.mjs` tested `health.ready` for truthiness
+ * and `capture-real-pages.mjs` tested `=== true`, so both would have waited out their whole readiness
+ * budget against a perfectly good older worker and then blamed the page.
+ *
+ * @param {{ busy?: boolean, ready?: boolean } | null | undefined} health
+ * @returns {boolean}
+ */
+export function workerIsUsable(health) {
+    if (!health)
+        return false;
+    return !health.busy && health.ready !== false;
+}
+/** Below this many captures the rate is noise: one recovery out of one capture is not a pattern. */
+const MIN_CAPTURES_TO_JUDGE = 4;
+/** Above this share of captures needing a recovery, the guest is not merely unlucky. */
+const DEGRADED_RECOVERY_SHARE = 0.5;
+/**
+ * @param {{ captures?: number, recoveries?: number, failures?: number } | null | undefined} vitals
+ * @returns {{ degraded: boolean, reason: string | null, recoveryShare: number | null }}
+ */
+export function assessWorker(vitals) {
+    const captures = vitals?.captures ?? 0;
+    const recoveries = vitals?.recoveries ?? 0;
+    // Recoveries are counted per capture served, so the share can exceed nothing sensible above 1.
+    const attempted = captures + (vitals?.failures ?? 0);
+    if (attempted < MIN_CAPTURES_TO_JUDGE) {
+        return { degraded: false, reason: null, recoveryShare: null };
+    }
+    const recoveryShare = recoveries / attempted;
+    if (recoveryShare <= DEGRADED_RECOVERY_SHARE) {
+        return { degraded: false, reason: null, recoveryShare };
+    }
+    return {
+        degraded: true,
+        recoveryShare,
+        reason: `${recoveries} of ${attempted} captures needed a screen-reader recovery ` +
+            `(${Math.round(recoveryShare * 100)}%) — this guest's NVDA is failing and every capture pays for it. ` +
+            "Reinstall NVDA or re-provision it (docs/nvda-worker-runbook.md); it is still serving, just slowly.",
+    };
+}
+//# sourceMappingURL=worker-health.mjs.map

package/dist/worker-health.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-health.mjs","sourceRoot":"","sources":["../src/worker-health.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,MAAM;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,KAAK,CAAC;AAChD,CAAC;AAED,oGAAoG;AACpG,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC,wFAAwF;AACxF,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAM;IACjC,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,MAAM,EAAE,UAAU,IAAI,CAAC,CAAC;IAC3C,+FAA+F;IAC/F,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAC,MAAM,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC;IACrD,IAAI,SAAS,GAAG,qBAAqB,EAAE,CAAC;QACtC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;IAChE,CAAC;IACD,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;IAC7C,IAAI,aAAa,IAAI,uBAAuB,EAAE,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAC1D,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,IAAI;QACd,aAAa;QACb,MAAM,EAAE,GAAG,UAAU,OAAO,SAAS,4CAA4C;YAC/E,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,mEAAmE;YACtG,oGAAoG;KACvG,CAAC;AACJ,CAAC"}

package/dist/worker-http.d.mts

@@ -0,0 +1,103 @@
+/**
+ * A worker address, validated at the BOUNDARY where it enters the program.
+ *
+ * `requestJson` already calls `new URL(url)`, which throws `ERR_INVALID_URL` on a malformed address — so an
+ * empty host dies in under a second, in principle. In practice it did not, and the way it did not is the
+ * reason this function exists.
+ *
+ * `--worker=http://:8765` reached `capture-real-pages.mjs` because nothing there did more than check the
+ * value was truthy, and `http://:8765` is truthy. The readiness loop then caught the resulting
+ * `ERR_INVALID_URL` in a bare `catch` whose only content was the comment "mid-boot or mid-restart; keep
+ * waiting", and so classified a permanent
+ * programmer error as a transient network condition: 60 attempts, 5 s apart, per page — then recorded
+ * "worker never became ready" as a failure of the PAGE. Four shards spent 29 minutes that way while every
+ * worker sat idle, and the run blamed the corpus.
+ *
+ * So the fix is two-part and both halves are needed: refuse the value here, and stop the readiness loop
+ * swallowing what it cannot recover from. Validating without fixing the catch leaves the next unrecoverable
+ * error to be absorbed the same way.
+ *
+ * Node's URL parser does the work. There is no regex here on purpose — a hand-rolled one would accept
+ * `http://:8765` again, since the only thing wrong with it is an empty host. Note `http:/x` and
+ * `http:///path` DO parse, to host `x` and host `path`; that is the parser's business and not something to
+ * second-guess here.
+ *
+ * @param {string | null | undefined} value the raw `--worker=` or `A11Y_WORKER` value
+ * @param {{ source?: string }} [options] what to name in the error, e.g. "--worker"
+ * @returns {string} the address, trailing slash removed
+ */
+export function assertWorkerUrl(value: string | null | undefined, { source }?: {
+    source?: string;
+}): string;
+/**
+ * One request, with a single deadline covering connect, headers and body.
+ *
+ * @param {string} url
+ * @param {{ method?: string, body?: unknown, timeoutMs?: number }} [options]
+ * @returns {Promise<{ status: number, ok: boolean, text: string, json: any }>}
+ *   `json: any`, not `unknown`. This is a JSON body off the wire, and every caller reads named fields
+ *   from it -- `body.error`, `body.fault`, `health.busy`, `body.transcript`. `unknown` makes each of
+ *   those a cast, and a cast written to satisfy a checker asserts a shape nobody verified, which is
+ *   strictly worse than saying the value is untyped. The SHAPE that matters is checked where it is
+ *   defined: `capture-core`'s `Capture` typedef, and the worker's own `/health` contract.
+ */
+export function requestJson(url: string, { method, body, timeoutMs }?: {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    ok: boolean;
+    text: string;
+    json: any;
+}>;
+/**
+ * How long a CLIENT should wait for a capture. One definition, because five had drifted.
+ *
+ * It must exceed the worker's own hard timeout (`CAPTURE_HARD_TIMEOUT_DEFAULT_MS`, 520 s) or the client
+ * gives up first, and a capture the worker would have completed is reported as a client failure. Five
+ * clients sat at 300 s -- `compare-workers`, `bench-capture`, `evidence-check`, `repeat-capture` and
+ * `capture-real-pages` -- against that 520 s. On the generated corpus nothing noticed, because a 1,338-byte
+ * page finishes in seconds. On REAL pages it silently dropped whatever used its budget, biasing the
+ * real-page corpus toward small simple pages: precisely the axis that corpus exists to add.
+ *
+ * 560,000 -> 620,000 on architecture-audit.md §14.5: `runCapture` (server.mjs) spends up to
+ * `DESKTOP_PREPARE_TIMEOUT_MS` (60 s) clearing the desktop BEFORE the hard-timeout-wrapped capture attempt
+ * even starts, sequentially rather than overlapping it -- so the true worst case a worker can legitimately
+ * take is 60 s + 520 s = 580 s, not 520 s alone. The old 560 s ceiling sat BELOW that, so a real page that
+ * used the full prepare budget and the full capture budget was killed by the CLIENT first and reported as
+ * a client failure for work the worker would have finished -- the exact shape this constant already exists
+ * to prevent, one rung further out. 620,000 keeps the same 40 s margin above the new true worst case that
+ * the original 560,000 kept above 520,000. `budget-ladder.test.ts` asserts the full sequence, not only the
+ * capture attempt inside it.
+ *
+ * Deliberately NOT imported from `@a11ign/screenreader-worker`: this package runs on macOS and Linux and must
+ * not depend on a win32-only one. `budget-ladder.test.ts` enforces the relationship instead, over every
+ * client it DISCOVERS rather than a list -- which is how the 300 s clients stayed invisible while a guard
+ * for exactly this existed and read one hardcoded path.
+ *
+ * `DATASET_CAPTURE_TIMEOUT_MS` still overrides it in the dataset runner, which is the only client that
+ * wants a per-run ceiling.
+ */
+export const CAPTURE_CLIENT_TIMEOUT_MS: 620000;
+/**
+ * How long a capture's silent connection may idle before the OS proves it is still there.
+ *
+ * 15 s, and RAISING IT TO 60 s WAS TRIED AND REVERTED — by this file's own test, which refuses a delay
+ * above ~30 s because common NAT idle timeouts start there.
+ *
+ * The reasoning for raising it was that the async path removed the long-lived connection, so nothing needs
+ * an aggressive value. That is true of the async path and FALSE of the `A11Y_SYNC_CAPTURE` escape hatch,
+ * which still holds one socket silent for a whole capture. At 60 s the first probe would fire after the
+ * reap, so the hatch would be unprotected while the constant looked deliberate — a guard weakened for a
+ * reason that did not cover the case it exists for.
+ *
+ * It stays aggressive until item D explains why THIS path reaps in seconds when the literature says
+ * minutes. An unexplained number is not a solved problem.
+ *
+ * EXPORTED so its test can key on the exact value. Node's own HTTP SERVER calls `setKeepAlive(true, 5000)`
+ * on every socket it accepts, so a test that merely looked for "keepalive with a plausible delay" matched
+ * the server's call and passed with this hook DELETED — found by mutation, not by reading.
+ */
+export const KEEPALIVE_DELAY_MS: 15000;
+//# sourceMappingURL=worker-http.d.mts.map

package/dist/worker-http.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-http.d.mts","sourceRoot":"","sources":["../src/worker-http.mjs"],"names":[],"mappings":"AAoGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,uCAJW,MAAM,GAAG,IAAI,GAAG,SAAS,eACzB;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjB,MAAM,CA0BlB;AAED;;;;;;;;;;;GAWG;AACH,iCATW,MAAM,gCACN;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,CAAC,CAwF7E;AAtMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wCAAyC,MAAO,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,iCAAkC,KAAM,CAAC"}