@a11ign/screenreader-fleet 0.5.2 → 0.6.0

package/README.md

@@ -93,3 +93,40 @@ the only real lifecycle — a cold boot to ready is 15–45 s, which is fine.
 
 Not exported: `host-metrics`, `worker-stats`, `fleet-consistency`. They are measurement internals whose shapes
 change every time something new gets measured.
+
+## Working here
+
+This repository is the package: `package.json`, `src/` and this README sit at the root, and the README is the npm page. It moved here from
+[`a11ign/a11ign`](https://github.com/a11ign/a11ign) with its history. It depends on
+[`@a11ign/screenreader-worker`](https://github.com/a11ign/screenreader-worker) and `@a11ign/judge` **by name, from the registry**.
+
+**The fleet drives workers that have no authentication.** Anyone who can reach a worker's port can drive the browser and the screen
+reader on that machine (`SECURITY.md` in `a11ign/a11ign` says what else somebody must know first). Run it only on a network you control.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm test        # what the `gate` check runs on every pull request and merge-queue entry, with lint, typecheck and layout-check
+```
+
+`main` takes pull requests only, each with one approving review, through the merge queue. `pnpm exec layout-check` is the repository-layout
+check from `@a11ign/toolchain`: it fails a workspace of one package, a directory not named for its package, a second README and a leftover
+`lerna.json`.
+
+### What did not come across: 27 tests
+
+The package's test directory was written for the monorepo, and 27 of its 53 test files read something that is not in this repository:
+`packages/control`'s playbooks and inventories, `packages/lab`'s capture clients, the private `guards` package, or the root's
+`scripts/`. Run here, they fail on a file they cannot find, so they were **not** carried into this repository; they stay in
+`a11ign/a11ign`, beside what they read, until its row #3504 relocates them. Their names are the `COUPLED` list in
+`packages/lab/src/packaging/screenreader-fleet-extraction.test.ts` there. The other 26 run here and are what `gate` runs, with
+`scripts/package-boundary.test.ts` holding the package to its own directory.
+
+### Releasing
+
+This repository releases on its own, not with `a11ign/a11ign`. A change that should reach npm carries a changeset
+(`pnpm exec changeset`), and **merging it to `main` is the release**: `.github/workflows/release.yml` calls the one
+reusable per-merge workflow in `a11ign/toolchain`, which versions the merge on a detached commit, publishes, tags and
+releases it. There is no version pull request and nothing is written to `main`, so its `package.json` version and
+`CHANGELOG.md` lag the last tag (`.changeset/README.md`). The publish uses npm trusted publishing over OIDC with
+provenance and no stored token. The first release, 0.1.0, was published before this workflow existed;
+no git tag names it, so the first per-merge release bases on `main`'s 0.1.0.

package/dist/{capture-client.d.mts → capture-client.d.ts}

@@ -13,7 +13,7 @@
  *
  * @param {string} worker @param {string} captureId
  */
-export function recoverCapture(worker: string, captureId: string): Promise<{
+export declare function recoverCapture(worker: string, captureId: string): Promise<{
     status: number;
     ok: boolean;
     text: string;
@@ -38,7 +38,7 @@ export function recoverCapture(worker: string, captureId: string): Promise<{
  *           beforeRecovery?: (error: unknown) => Promise<void>,
  *           onProgress?: (progress: object) => void, sync?: boolean }} request
  */
-export function captureTolerantly({ worker, body, timeoutMs, beforeRecovery, onProgress, sync }: {
+export declare function captureTolerantly({ worker, body, timeoutMs, beforeRecovery, onProgress, sync }: {
     worker: string;
     body: object;
     timeoutMs?: number;

package/dist/{check-worker-code.d.mts → check-worker-code.d.ts}

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { configuredWorkers, inventoryWorkerUrls } from "./fleet-env.js";
 /**
  * Which workers to ask, AND WHERE THAT LIST CAME FROM — the second half is not decoration.
  *
@@ -18,7 +19,7 @@
  * Reading it here is safe in a way it would not be for a capture run: this probes `/health` and starts
  * nothing, so the rule that naming workers means you are managing them does not apply.
  */
-export function workerUrls({ named, local, inventory, }?: {
+export declare function workerUrls({ named, local, inventory, }?: {
     named?: typeof configuredWorkers | undefined;
     local?: typeof localPoolUrls | undefined;
     inventory?: typeof inventoryWorkerUrls | undefined;
@@ -26,8 +27,6 @@ export function workerUrls({ named, local, inventory, }?: {
     urls: string[];
     source: string;
 };
-import { configuredWorkers } from "./fleet-env.mjs";
 /** The local UTM pool, or none — `utmctl` is absent on a machine that never had one. */
 declare function localPoolUrls(): any;
-import { inventoryWorkerUrls } from "./fleet-env.mjs";
 export {};

package/dist/check-worker-code.mjs

@@ -3,7 +3,7 @@ import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { execFileSync } from "node:child_process";
 import { errorText } from "@a11ign/screenreader-worker/error-text";
-import { fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
+import { fleetScriptPaths } from "./src_fleet-scripts_ts.mjs";
 import { inventoryWorkerUrls, configuredWorkers, resolveWorkerPool } from "./fleet-env.mjs";
 import { remedyLines, codeDrift, resolveExpectedWorkerCode } from "./worker-code-check.mjs";
 import { refuseUnknownFlags } from "./cli-flags.mjs";

package/dist/{cli-flags.d.mts → cli-flags.d.ts}

@@ -2,7 +2,7 @@
  * The flag name alone: `--shard=0/4` and `--shard` both name `--shard`.
  * @param {string} argument @returns {string}
  */
-export function nameOf(argument: string): string;
+export declare function nameOf(argument: string): string;
 /**
  * `--name=value`'s value, or `undefined` if `--name=` was never passed. audit §9's "argv parsing" row:
  * VALIDATION is owned here (`refuseUnknownFlags`), but 15+ files each hand-rolled this exact three-line
@@ -21,7 +21,7 @@ export function nameOf(argument: string): string;
  * @param {readonly string[]} argv @param {string} name
  * @returns {string | undefined}
  */
-export function flagValue(argv: readonly string[], name: string): string | undefined;
+export declare function flagValue(argv: readonly string[], name: string): string | undefined;
 /**
  * Which of `argv` are flags this command does not know. PURE, so it is testable without a process.
  *
@@ -45,12 +45,12 @@ export function flagValue(argv: readonly string[], name: string): string | undef
 /**
  * @param {string[]} argv @param {string[]} known @returns {string[]}
  */
-export function unknownFlags(argv: string[], known: string[]): string[];
+export declare function unknownFlags(argv: string[], known: string[]): string[];
 /**
  * The closest known flag, when there is one close enough to be a likely typo rather than a guess.
  * @param {string} flag @param {string[]} known @returns {string | undefined}
  */
-export function didYouMean(flag: string, known: string[]): string | undefined;
+export declare function didYouMean(flag: string, known: string[]): string | undefined;
 /**
  * Refuse, naming the flag and what this command does take. Exits 2; does not return on failure.
  *
@@ -63,7 +63,7 @@ export function didYouMean(flag: string, known: string[]): string | undefined;
  *   `entry` is the caller's `import.meta.url`, and it is REQUIRED. `command` names the thing a HUMAN
  *   typed — the npm script, not the file — because that is what they will retype.
  */
-export function refuseUnknownFlags(known: string[], { entry, argv, command }: {
+export declare function refuseUnknownFlags(known: string[], { entry, argv, command }: {
     entry: string;
     argv?: string[];
     command?: string;

package/dist/{code-drift.d.mts → code-drift.d.ts}

@@ -16,7 +16,7 @@
  * @returns {{expected: string, stale: Array<{worker: string, serving: string}>, unreachable: string[],
  *            answered: number}}
  */
-export function codeDrift(expected: string, readings: Array<{
+export declare function codeDrift(expected: string, readings: Array<{
     worker: string;
     code: string | null | undefined;
 }>): {
@@ -49,7 +49,7 @@ export function codeDrift(expected: string, readings: Array<{
  * @param {string[]} bareMetalUrls
  * @returns {string[]}
  */
-export function remedyLines(staleUrls: string[], bareMetalUrls: string[]): string[];
+export declare function remedyLines(staleUrls: string[], bareMetalUrls: string[]): string[];
 /**
  * The refusal text, or `null` when the fleet is running this checkout. PURE.
  *
@@ -61,7 +61,7 @@ export function remedyLines(staleUrls: string[], bareMetalUrls: string[]): strin
  * @param {{when?: string, bareMetalUrls?: string[], sourceDirty?: string}} options
  * @returns {string|null}
  */
-export function describeCodeDrift(drift: {
+export declare function describeCodeDrift(drift: {
     expected: string;
     stale: Array<{
         worker: string;
@@ -76,7 +76,7 @@ export function describeCodeDrift(drift: {
 }): string | null;
 /** What a single worker is serving, or `null` when it did not answer. */
 /** @param {string} url */
-export function readWorkerCode(url: string): Promise<any>;
+export declare function readWorkerCode(url: string): Promise<any>;
 /**
  * Is the worker source in `sourceDir` modified against HEAD?
  *
@@ -89,7 +89,7 @@ export function readWorkerCode(url: string): Promise<any>;
  *
  * @param {string} sourceDir
  */
-export function workerSourceDirty(sourceDir: string): string;
+export declare function workerSourceDirty(sourceDir: string): string;
 /**
  * AN EMPTY POOL IS NOT A CLEAN FLEET — the refusal, as a value, so it can be tested without exiting.
  *
@@ -110,7 +110,7 @@ export function workerSourceDirty(sourceDir: string): string;
  * @param {string} expected
  * @returns {string | null} the refusal, or null when there is a pool to check
  */
-export function describeEmptyPool(workers: string[] | undefined, expected: string): string | null;
+export declare function describeEmptyPool(workers: string[] | undefined, expected: string): string | null;
 /**
  * Refuse to run against a fleet that is not serving `expected` — the shared body of
  * `assertFleetRunsThisCheckout`, taking the hash as a parameter rather than computing it.
@@ -131,7 +131,7 @@ export function describeEmptyPool(workers: string[] | undefined, expected: strin
  *
  * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[], sourceDir: string}} options
  */
-export function assertWorkersServe(expected: string, workers: string[], options: {
+export declare function assertWorkersServe(expected: string, workers: string[], options: {
     when?: string;
     allow?: boolean;
     read?: (url: string) => Promise<string | null>;

package/dist/{command-line-census.d.mts → command-line-census.d.ts}

@@ -5,7 +5,7 @@
  * @param {string} repoRoot absolute path to the repository root
  * @returns {string[]} repo-relative paths, unsorted (discovery order)
  */
-export function allMjsFiles(repoRoot: string): string[];
+export declare function allMjsFiles(repoRoot: string): string[];
 /**
  * Does this file read argv? Comments stripped first, and that is not a nicety: matching raw source
  * classified a module as a CLI merely because a COMMENT mentioned `process.argv` — measured on
@@ -20,7 +20,7 @@ export function allMjsFiles(repoRoot: string): string[];
  * @param {string} repoRoot absolute path to the repository root
  * @returns {boolean}
  */
-export function readsArgv(rel: string, repoRoot: string): boolean;
+export declare function readsArgv(rel: string, repoRoot: string): boolean;
 /**
  * `allMjsFiles()` filtered to the ones that read argv — the population `cli-flags.test.ts`'s flag-guard
  * census classifies. NOT the same question as "is this a runnable command with an entry-point guard";
@@ -29,4 +29,4 @@ export function readsArgv(rel: string, repoRoot: string): boolean;
  * @param {string} repoRoot absolute path to the repository root
  * @returns {string[]}
  */
-export function commandLineModules(repoRoot: string): string[];
+export declare function commandLineModules(repoRoot: string): string[];

package/dist/{compare-workers.d.mts → compare-workers.d.ts}

@@ -12,7 +12,7 @@
  * @param {{ argv?: readonly string[], baseDir?: string }} [options]
  * @returns {string}
  */
-export function outDirFor({ argv, baseDir }?: {
+export declare function outDirFor({ argv, baseDir }?: {
     argv?: readonly string[];
     baseDir?: string;
 }): string;

package/dist/{control-plane-isolation.d.mts → control-plane-isolation.d.ts}

@@ -33,7 +33,7 @@
  * @param {{ hasNodeModules: boolean, hasFleetKey: boolean, packages?: number, isWorkspace?: boolean }} found
  * @returns {{ violated: boolean, why: string }}
  */
-export function controlPlaneIsolation({ hasNodeModules, hasFleetKey, packages, isWorkspace }: {
+export declare function controlPlaneIsolation({ hasNodeModules, hasFleetKey, packages, isWorkspace }: {
     hasNodeModules: boolean;
     hasFleetKey: boolean;
     packages?: number;

package/dist/{doctor.d.mts → doctor.d.ts}

@@ -12,10 +12,47 @@
  * @param {{ argv?: readonly string[], baseDir?: string }} [options]
  * @returns {string}
  */
-export function runsDirFor({ argv, baseDir }?: {
+export declare function runsDirFor({ argv, baseDir }?: {
     argv?: readonly string[];
     baseDir?: string;
 }): string;
+/** What the checks have recorded so far, for a test that drives one check through the real recorder. */
+export declare const recordedChecks: () => {
+    name: string;
+    id: string;
+    ok: boolean;
+    detail: string;
+    fix: string | null;
+    note?: string | null;
+    advisory?: boolean;
+}[];
+/**
+ * One check's verdict, and its REMEDY. Every parameter is typed here rather than inferred, because
+ * `remedy` defaulting to `null` infers as exactly `null` -- so the argument that matters most, what a
+ * reader is to do about a failed check, was the one the compiler refused.
+ *
+ * `id` is always `name` -- #256 is the first check queried individually by `--json`
+ * (`.checks[] | select(.id=="dist-freshness")`), and every check already has a unique `name`, so a
+ * separate parameter here would be a second spelling of the same fact rather than a new one.
+ *
+ * #1059: `fix` IS A COMMAND OR IT IS `null`, and human advice goes in `note`.
+ *
+ * CLAUDE.md tells an agent to read `next_command` and do that, and `next_command` is `fix`. A sentence
+ * there ("unlock the Mac if it is locked, then re-run …") is not something anything can run, so an
+ * automated reader loops. The advice is not lost -- it moves to the field nothing executes.
+ * ONE `remedy` ARGUMENT, not two: a bare string stays a command (which is what every existing call site
+ * passes), and the object form carries the advice beside it. Four parameters is the house limit and
+ * bundling cohesive arguments is the house answer to it.
+ * @param {string} name
+ * @param {boolean} ok
+ * @param {string} detail
+ * @param {string|null|{fix: string|null, note?: string|null}} [remedy] a runnable command, `null` when
+ *   none can be constructed, or `{ fix, note }` when there is advice a shell cannot run
+ */
+export declare const addCheck: (name: string, ok: boolean, detail: string, remedy?: string | null | {
+    fix: string | null;
+    note?: string | null;
+}) => void;
 /**
  * The remedy for a failed local-pool query, as a runnable command plus the advice that is not one.
  *
@@ -27,7 +64,7 @@ export function runsDirFor({ argv, baseDir }?: {
  * @param {string} observed
  * @returns {{ fix: string|null, note: string|null }}
  */
-export function workerControlFix(observed: string): {
+export declare function workerControlFix(observed: string): {
     fix: string | null;
     note: string | null;
 };
@@ -64,10 +101,10 @@ export function workerControlFix(observed: string): {
  * and telling four of those five to mark themselves would be the #198 defect wearing an advisory's
  * clothes. It states what is true and names the command; the operator decides.
  */
-export function checkPrimaryCheckoutMark({ baseDir }?: {
+export declare function checkPrimaryCheckoutMark({ baseDir }?: {
     baseDir?: string | undefined;
 }): void;
-export function checkControlPlaneIsolation({ baseDir }?: {
+export declare function checkControlPlaneIsolation({ baseDir }?: {
     baseDir?: string | undefined;
 }): void;
 /**
@@ -80,7 +117,7 @@ export function checkControlPlaneIsolation({ baseDir }?: {
  * @param {string} thisCheckoutRootReal
  * @returns {boolean}
  */
-export function resolvesToThisCheckout(resolvedRealPath: string, thisCheckoutRootReal: string): boolean;
+export declare function resolvesToThisCheckout(resolvedRealPath: string, thisCheckoutRootReal: string): boolean;
 /**
  * Pure: which checkout root does a resolved `packages/<name>/dist/...` path belong to? Everything before
  * the first `/packages/` -- this repo's own, fixed layout, not a guess. `null` when the path does not look
@@ -89,7 +126,7 @@ export function resolvesToThisCheckout(resolvedRealPath: string, thisCheckoutRoo
  * @param {string} resolvedRealPath
  * @returns {string | null}
  */
-export function checkoutRootFor(resolvedRealPath: string): string | null;
+export declare function checkoutRootFor(resolvedRealPath: string): string | null;
 /**
  * The `exports` targets of `packageDir` that are NOT on disk, or `null` when the package's manifest could not be
  * read or declares none -- "could not tell" and "missing" need opposite responses (investigate vs. rebuild), and a
@@ -106,7 +143,7 @@ export function checkoutRootFor(resolvedRealPath: string): string | null;
  * @param {string} packageDir
  * @returns {string[] | null}
  */
-export function missingExportTargets(packageDir: string): string[] | null;
+export declare function missingExportTargets(packageDir: string): string[] | null;
 /**
  * WHOSE dist a cross-package import actually resolves to, and is IT stale (#256) -- both computed from
  * the exact SPECIFIER a real import site in this repo uses, never the bare package name. CLAUDE.md's own
@@ -120,7 +157,7 @@ export function missingExportTargets(packageDir: string): string[] | null;
  * environmental fact would be ignored, which is how a guard gets switched off. It is reported every run
  * so a stale answer is a known condition, not a silent one.
  */
-export function checkCrossPackageDist({ baseDir }?: {
+export declare function checkCrossPackageDist({ baseDir }?: {
     baseDir?: string | undefined;
 }): number | void;
 /**
@@ -135,10 +172,10 @@ export function checkCrossPackageDist({ baseDir }?: {
  * @param {{ from?: string }} [options] a path or file URL to resolve `@a11ign/judge` from
  * @returns {Promise<string>}
  */
-export function scorerWeightsFor({ from }?: {
+export declare function scorerWeightsFor({ from }?: {
     from?: string;
 }): Promise<string>;
-export function checkJudge({ from }?: {
+export declare function checkJudge({ from }?: {
     from?: string | undefined;
 }): Promise<void>;
 /**
@@ -184,7 +221,7 @@ export function checkJudge({ from }?: {
  *                     coverage?: { field: string, reported: number, asked: number }[] } }} input
  * @returns {string}
  */
-export function fleetAgreementLine({ agreeing, configured, fields }: {
+export declare function fleetAgreementLine({ agreeing, configured, fields }: {
     agreeing: number;
     configured: number;
     fields: {
@@ -213,7 +250,7 @@ export function fleetAgreementLine({ agreeing, configured, fields }: {
  * @param {{ok: boolean, fix: string|null}[]} [checkList]
  * @returns {string|null}
  */
-export function nextCommand(checkList?: {
+export declare function nextCommand(checkList?: {
     ok: boolean;
     fix: string | null;
 }[]): string | null;
@@ -227,7 +264,7 @@ export function nextCommand(checkList?: {
  * @param {string|null} line
  * @returns {boolean}
  */
-export function isRunnableCommand(line: string | null): boolean;
+export declare function isRunnableCommand(line: string | null): boolean;
 /**
  * Only when RUN, never on import.
  *
@@ -246,10 +283,14 @@ export function isRunnableCommand(line: string | null): boolean;
  * @param {{name: string, ok: boolean}[]} checkList
  * @returns {boolean}
  */
-export function readyFrom(checkList: {
+export declare function readyFrom(checkList: {
     name: string;
     ok: boolean;
 }[]): boolean;
+/** Every DECLARED check name, gating or not -- so a test can compare the two sets without a literal. */
+export declare const allChecks: () => string[];
+/** Which checks decide `ready`, for a test that must not retype the list. */
+export declare const gatingChecks: () => string[];
 /**
  * #1082: A `--json` RUN THAT CANNOT PRODUCE JSON STILL PRODUCES JSON.
  *
@@ -271,7 +312,7 @@ export function readyFrom(checkList: {
  * @param {unknown} error
  * @returns {{ready: false, error: string, checks: never[]}}
  */
-export function errorDocument(error: unknown): {
+export declare function errorDocument(error: unknown): {
     ready: false;
     error: string;
     checks: never[];
@@ -283,25 +324,10 @@ export function errorDocument(error: unknown): {
  *           err?: (line: string) => void, runsDir?: () => string }} [deps]
  * @returns {Promise<number>}
  */
-export function doctorRun(deps?: {
+export declare function doctorRun(deps?: {
     steps?: (() => unknown)[];
     json?: boolean;
     out?: (line: string) => void;
     err?: (line: string) => void;
     runsDir?: () => string;
 }): Promise<number>;
-export function recordedChecks(): {
-    name: string;
-    id: string;
-    ok: boolean;
-    detail: string;
-    fix: string | null;
-    note?: string | null;
-    advisory?: boolean;
-}[];
-export function addCheck(name: string, ok: boolean, detail: string, remedy?: string | null | {
-    fix: string | null;
-    note?: string | null;
-}): void;
-export function allChecks(): string[];
-export function gatingChecks(): string[];

package/dist/doctor.mjs

@@ -2,17 +2,17 @@
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
 import { fleetConsistency, describeMismatches } from "./fleet-consistency.mjs";
-import { fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
+import { fleetScriptPaths } from "./src_fleet-scripts_ts.mjs";
 import { namedInventoryWorkers, configuredWorkers } from "./fleet-env.mjs";
 import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 import { requestJson } from "./worker-http.mjs";
-import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
+import { sandboxGitEnv } from "./src_git-safe-env_ts.mjs";
 import { assessWorker } from "./worker-health.mjs";
 function controlPlaneIsolation({ hasNodeModules, hasFleetKey, packages, isWorkspace = false }) {
     if (!hasNodeModules || !hasFleetKey) return {
@@ -361,7 +361,7 @@ async function checkDegradedWorkers(probed) {
     for (const w of probed){
         if (!w.health) continue;
         const { degraded, reason } = assessWorker(w.health.vitals);
-        if (degraded) add(`worker ${w.name}`, true, `DEGRADED — ${reason}`, `re-provision ${w.name}: packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1, elevated, in the interactive session`);
+        if (degraded) add(`worker ${w.name}`, true, `DEGRADED — ${reason}`, `re-provision ${w.name}: ${join(fleetScriptPaths().provisioning, "provision-nvda-worker.ps1")}, elevated, in the interactive session`);
     }
 }
 function checkFleetConsistency(probed, configured) {

package/dist/{fleet-consistency.d.mts → fleet-consistency.d.ts}

@@ -1,42 +1,3 @@
-/**
- * Compare guests field by field.
- *
- * @param {Guest[]} guests
- * @returns {{consistent: boolean, mismatches: Mismatch[], compared: number, fields: FieldCoverage,
- *   reportedOnly: ReportedDrift[]}}
- *   `compared` is how many guests the verdict is actually ABOUT -- #920. A guest with no `environment`
- *   and no `policy` is dropped below before comparing, so it is not the length of what was passed in,
- *   and a caller that reports `consistent` without it is stating agreement over a set it cannot name.
- *   `fields` is that same question one axis over: WHICH fields the verdict is about -- #1997.
- *   `reportedOnly` is the third channel (#2063): compared, named, and part of NEITHER of the two above,
- *   which is what makes it something to report rather than something to refuse.
- */
-export function fleetConsistency(guests: Guest[]): {
-    consistent: boolean;
-    mismatches: Mismatch[];
-    compared: number;
-    fields: FieldCoverage;
-    reportedOnly: ReportedDrift[];
-};
-/**
- * One line per reported-only field that has something to say, in `describeMismatches`'s own shape.
- *
- * SEPARATE FROM `describeMismatches` rather than a flag on it, because the two lines make different
- * claims and a reader has to be able to tell them apart at a glance: that one says the fleet is not
- * usable for a capture run, this one says the fleet is not identical and the run may proceed anyway.
- * Folding them would put the ruling's own distinction behind a boolean argument.
- *
- * @param {ReportedDrift[]} drifts
- * @returns {string[]}
- */
-export function describeReportedOnly(drifts: ReportedDrift[]): string[];
-/**
- * One line per mismatch, naming the guests, so the report is actionable rather than just alarming.
- *
- * @param {Mismatch[]} mismatches
- * @returns {string[]}
- */
-export function describeMismatches(mismatches: Mismatch[]): string[];
 /**
  * Are the guests actually interchangeable?
  *
@@ -65,7 +26,7 @@ export function describeMismatches(mismatches: Mismatch[]): string[];
  * `workerCode` is absent on purpose: it changes when a comment changes, and the deploy tooling already
  * verifies it against the checkout. Flagging it here would cry wolf on every reworded line.
  */
-export const MUST_MATCH: {
+export declare const MUST_MATCH: {
     path: string;
     why: string;
 }[];
@@ -98,7 +59,7 @@ export const MUST_MATCH: {
  * until the worker carrying it was deployed on 2026-09-23, and the state any field added here starts in,
  * and it must be readable as such without refusing anything.
  */
-export const REPORTED_ONLY: {
+export declare const REPORTED_ONLY: {
     path: string;
     why: string;
 }[];
@@ -110,11 +71,14 @@ export const REPORTED_ONLY: {
  * `Record<string, unknown>` on the other, which typecheck caught in the test that calls them in sequence.
  * Two spellings of one shape is the duplication this repo names as its most expensive recurring defect,
  * and a typedef is the cheapest form of "delete a copy".
- *
- * @typedef {{field: string, why: string, values: Record<string, unknown>}} Mismatch
  */
+export type Mismatch = {
+    field: string;
+    why: string;
+    values: Record<string, unknown>;
+};
 /** Edge policy values every guest must agree on, checked separately because they come from /diagnostics. */
-export const POLICY_MUST_MATCH: string[];
+export declare const POLICY_MUST_MATCH: string[];
 /**
  * Which fields the verdict is actually ABOUT -- #1997.
  *
@@ -141,27 +105,6 @@ export type FieldReporters = {
     reported: number;
     asked: number;
 };
-/**
- * Which fields the verdict is actually ABOUT -- #1997.
- *
- * `compared` NAMES the fields at least one guest reported a value for; `unchecked` names the ones that
- * drew a value from NOBODY. The second list exists because `check()` below skips an absent value, which
- * is right (a rolling deploy must not flag the guest it has not reached yet) and has a cost: a field no
- * guest reports contributes no values, `new Set([]).size > 1` is false, and it reads as agreement.
- * A field compared on nobody and a field equal on everybody produced the IDENTICAL verdict.
- *
- * Measured 2026-09-22T20:09Z on the live fleet, at the merge of #1953: nine fields at 10/10 guests and
- * `displayMode` at 0/10, and `fleet:status` printed `fleet CONSISTENT across 10 of 10 -- these workers
- * are interchangeable for capture`. The display was still not compared. Naming the two lists is what
- * lets a reader tell "they agree" from "nobody was asked".
- *
- * `coverage` IS THE SAME QUESTION WITHOUT THE THRESHOLD -- #2019. The two lists above are a PARTITION on
- * "did anybody report it", which answers 0-of-10 and says nothing about 1-of-10; `fleet:status` read the
- * second as agreement about ten guests on the strength of one. So every asked field also carries how many
- * of the asked guests actually reported it, and the verdict draws its own line. `compared`/`unchecked`
- * stay because they are what a caller greps for the REMEDY -- a field at 0 sends a reader to the field,
- * a field at k sends them to the boxes -- and `coverage` is the measurement both are derived from.
- */
 export type FieldCoverage = {
     compared: string[];
     unchecked: string[];
@@ -195,22 +138,19 @@ export type ReportedDrift = {
  * that gates nothing. One reader means the two channels cannot drift apart in how they compare — a
  * second copy of this loop is how a "reported-only" field would end up counted differently from a gating
  * one and nobody would know which was right.
+ *
+ * @param {Guest[]} present
+ * @param {{field: string, why: string, source: (guest: Guest) => Record<string, unknown> | undefined,
+ *   key: string}} ask `source` is the BLOCK this field lives in, not the value: coverage has to tell
+ *   "the guest did not report this field" from "this caller never collected that block at all", and only
+ *   the block answers the second
+ * @returns {Reading}
  */
 export type Guest = {
     worker: string;
     environment?: Record<string, unknown>;
     policy?: Record<string, unknown>;
 };
-/**
- * ONE FIELD READ ACROSS THE FLEET, before anybody decides what it means.
- *
- * Split out from `fleetConsistency` when the third channel arrived (#2063), because the READING and the
- * CONSEQUENCE are two things and only the second differs between the channels: `MUST_MATCH` turns a
- * reading into a mismatch and a coverage row, `REPORTED_ONLY` turns the same reading into a named drift
- * that gates nothing. One reader means the two channels cannot drift apart in how they compare — a
- * second copy of this loop is how a "reported-only" field would end up counted differently from a gating
- * one and nobody would know which was right.
- */
 export type Reading = {
     field: string;
     why: string;
@@ -219,16 +159,41 @@ export type Reading = {
     asked: number;
 };
 /**
- * One field the guests disagree about, and the guests' values for it.
+ * Compare guests field by field.
  *
- * Named once because it is produced by `fleetConsistency` and consumed by `describeMismatches`, and the
- * two had already drifted apart the moment either was annotated — `object` on one side against
- * `Record<string, unknown>` on the other, which typecheck caught in the test that calls them in sequence.
- * Two spellings of one shape is the duplication this repo names as its most expensive recurring defect,
- * and a typedef is the cheapest form of "delete a copy".
+ * @param {Guest[]} guests
+ * @returns {{consistent: boolean, mismatches: Mismatch[], compared: number, fields: FieldCoverage,
+ *   reportedOnly: ReportedDrift[]}}
+ *   `compared` is how many guests the verdict is actually ABOUT -- #920. A guest with no `environment`
+ *   and no `policy` is dropped below before comparing, so it is not the length of what was passed in,
+ *   and a caller that reports `consistent` without it is stating agreement over a set it cannot name.
+ *   `fields` is that same question one axis over: WHICH fields the verdict is about -- #1997.
+ *   `reportedOnly` is the third channel (#2063): compared, named, and part of NEITHER of the two above,
+ *   which is what makes it something to report rather than something to refuse.
  */
-export type Mismatch = {
-    field: string;
-    why: string;
-    values: Record<string, unknown>;
+export declare function fleetConsistency(guests: Guest[]): {
+    consistent: boolean;
+    mismatches: Mismatch[];
+    compared: number;
+    fields: FieldCoverage;
+    reportedOnly: ReportedDrift[];
 };
+/**
+ * One line per reported-only field that has something to say, in `describeMismatches`'s own shape.
+ *
+ * SEPARATE FROM `describeMismatches` rather than a flag on it, because the two lines make different
+ * claims and a reader has to be able to tell them apart at a glance: that one says the fleet is not
+ * usable for a capture run, this one says the fleet is not identical and the run may proceed anyway.
+ * Folding them would put the ruling's own distinction behind a boolean argument.
+ *
+ * @param {ReportedDrift[]} drifts
+ * @returns {string[]}
+ */
+export declare function describeReportedOnly(drifts: ReportedDrift[]): string[];
+/**
+ * One line per mismatch, naming the guests, so the report is actionable rather than just alarming.
+ *
+ * @param {Mismatch[]} mismatches
+ * @returns {string[]}
+ */
+export declare function describeMismatches(mismatches: Mismatch[]): string[];