@openmixer/plugin-qualify 0.20.3 → 0.20.4

package/src/refused-stderr-kept.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * #6's conformance check: a refused row's cause must be readable from the record directory itself,
+ * not summed to a byte count in the probe copy's `logs` entry. #311 copies a child's stderr beside
+ * its record (`stderrCopyFileName`) so the bytes `logs` counts can still be read back; this walks a
+ * records directory and names every refused row where that reading still fails: the count is zero
+ * (nothing was ever captured) or the count is positive but no copy answers it (the count was kept,
+ * the words were not).
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readProbeOutput, sha256Hex, PROBE_OK } from "./probe-output.js";
+import { stderrCopyFileName, type QualificationRecord } from "./qualification-record.js";
+
+export type StderrKeptProblem = "empty-stderr" | "log-line-not-kept";
+
+export interface StderrKeptFinding {
+  readonly record: string;
+  readonly plugin: string;
+  readonly problem: StderrKeptProblem;
+  readonly detail: string;
+}
+
+interface ProbeLogEntry {
+  readonly name?: string;
+  readonly sha256?: string;
+  readonly bytes?: number;
+}
+
+const isRefused = (record: QualificationRecord): boolean => record.probe.outcome !== PROBE_OK || record.verdicts.some((v) => !v.qualified);
+
+/** Every `*.qualification.json` in `dir`, refused rows only, with its parsed record. */
+function refusedRecords(dir: string): { readonly file: string; readonly record: QualificationRecord }[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".qualification.json"))
+    .map((file) => ({ file, record: JSON.parse(readFileSync(join(dir, file), "utf8")) as QualificationRecord }))
+    .filter((r) => isRefused(r.record));
+}
+
+/**
+ * Every refused row in `dir` whose child's own words are not readable back from disk: a row whose every run's stderr
+ * was never kept, and a row whose `logs` count bytes a copy beside the record does not answer.
+ */
+export function checkStderrKept(dir: string): StderrKeptFinding[] {
+  const findings: StderrKeptFinding[] = [];
+  for (const { file, record } of refusedRecords(dir)) {
+    const probePath = join(dir, record.probe.file);
+    if (!existsSync(probePath)) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: `${record.probe.file}: the probe copy named by the record is not beside it` });
+      continue;
+    }
+    const probeText = readFileSync(probePath, "utf8");
+    const read = readProbeOutput(probeText);
+    if (!read.ok) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: `${record.probe.file}: ${read.problem}` });
+      continue;
+    }
+    const probeDoc = JSON.parse(probeText) as { readonly logs?: readonly ProbeLogEntry[] };
+    const logs: readonly ProbeLogEntry[] = Array.isArray(probeDoc.logs) ? probeDoc.logs : [];
+    const written = logs.filter((l) => (l.bytes ?? 0) > 0);
+    if (written.length === 0) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: "refused, and no run's child printed anything on stderr" });
+      continue;
+    }
+    for (const entry of written) {
+      const name = entry.name ?? "stderr";
+      if (entry.sha256 === undefined) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: ${String(entry.bytes)} bytes counted, no SHA-256 to find a copy by` });
+        continue;
+      }
+      const copyPath = join(dir, stderrCopyFileName(read.output, entry.sha256));
+      if (!existsSync(copyPath)) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: ${String(entry.bytes)} bytes counted, no copy at ${stderrCopyFileName(read.output, entry.sha256)}` });
+        continue;
+      }
+      const copied = readFileSync(copyPath);
+      if (copied.length === 0 || sha256Hex(copied) !== entry.sha256) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: the copy at ${stderrCopyFileName(read.output, entry.sha256)} is empty or does not match the count` });
+      }
+    }
+  }
+  return findings;
+}

package/src/text-catalog.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The sentence a surface shows for one of plugin-qualify's own {@link TextRef}s: the catalog's, for the given
+ * language, else the source sentence `schema/codes.json` declares; its `{placeholder}`s filled from `args`
+ * An entry is the sentence, or the sentence with how it was made (omx-contract 3.16.0's `catalogEntry`); a model's
+ * entry made from another source sentence is stale and skipped. This is the lookup of
+ * `@openmixer/omx-contract/catalog` (`sentenceOf`, `fill`), made here: that module reads its schema through ajv, which
+ * this package does not depend on, and the npm floor is below the release that knows an entry's provenance.
+ *
+ * `schema/codes.json` and `catalogs/<lang>.json` ship inside this package (`package.json`'s `files`), read relative
+ * to this module so it works from `src/` under vitest and from `dist/` once built alike. `PLUGIN_QUALIFY_CATALOGS_DIR`
+ * names another catalogs directory instead, for a test that wants its own fixture catalogs.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ReasonText, TextRef } from "./text-codes.js";
+
+export const OWNER = "plugin-qualify";
+export const CATALOGS_DIR_ENV = "PLUGIN_QUALIFY_CATALOGS_DIR";
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Where this package's own `catalogs/<lang>.json` live: `PLUGIN_QUALIFY_CATALOGS_DIR`, else beside this module's package. */
+export function catalogsDir(env: Readonly<Record<string, string | undefined>> = process.env): string {
+  return env[CATALOGS_DIR_ENV] ?? join(PKG, "catalogs");
+}
+
+/** One code of `schema/codes.json`: the code, the args its sentence names and the sentence. */
+export interface DeclaredCode {
+  readonly code: string;
+  readonly doc?: string;
+  readonly text: { readonly en: string };
+  readonly args: readonly string[];
+}
+
+/** One catalog entry: the sentence, or the sentence with how it was made (omx-contract's `catalogEntry`). */
+export type CatalogEntry = string | { readonly text: string; readonly by: "human" | "machine"; readonly model?: string; readonly source?: string };
+
+/** Where the codes are declared: `schema/codes.json` of this package. */
+export const CODES_FILE = join(PKG, "schema", "codes.json");
+
+let declared: ReadonlyMap<string, DeclaredCode> | undefined;
+
+/** Every code `schema/codes.json` declares, by its code; none where the file does not read. */
+export function declaredCodes(): ReadonlyMap<string, DeclaredCode> {
+  if (declared !== undefined) return declared;
+  let codes: Record<string, DeclaredCode> = {};
+  try {
+    codes = (JSON.parse(readFileSync(CODES_FILE, "utf8")) as { codes?: Record<string, DeclaredCode> }).codes ?? {};
+  } catch {
+    codes = {};
+  }
+  declared = new Map(Object.values(codes).map((c) => [c.code, c]));
+  return declared;
+}
+
+const messagesCache = new Map<string, Record<string, CatalogEntry> | undefined>();
+
+/** `catalogs/<lang>.json`'s `messages`, or `undefined` where the file is absent or does not read as one. */
+export function loadMessages(lang: string, dir: string = catalogsDir()): Record<string, CatalogEntry> | undefined {
+  const cacheKey = `${dir}\0${lang}`;
+  if (messagesCache.has(cacheKey)) return messagesCache.get(cacheKey);
+  let messages: Record<string, CatalogEntry> | undefined;
+  try {
+    const catalog = JSON.parse(readFileSync(join(dir, `${lang}.json`), "utf8")) as { messages?: Record<string, CatalogEntry> };
+    messages = catalog.messages;
+  } catch {
+    messages = undefined;
+  }
+  messagesCache.set(cacheKey, messages);
+  return messages;
+}
+
+/** `sentence` with each `{name}` replaced by `args[name]`; a placeholder with no value is left as written. */
+export function fill(sentence: string, args: Readonly<Record<string, string | number>> = {}): string {
+  return sentence.replace(/\{([^{}]*)\}/g, (m, n: string) => (Object.hasOwn(args, n) ? String(args[n]) : m));
+}
+
+/** The sha256 of a source sentence, lowercase hex of its UTF-8 bytes: what a model's entry records as `source`. */
+export const sourceHash = (sentence: string): string => createHash("sha256").update(sentence, "utf8").digest("hex");
+
+/** The sentence of `entry`; `undefined` for no entry, or a model's entry made from another sentence than `source`. */
+export function entrySentence(entry: CatalogEntry | undefined, source: string): string | undefined {
+  if (entry === undefined || typeof entry === "string") return entry;
+  return entry.source !== undefined && entry.source !== sourceHash(source) ? undefined : entry.text;
+}
+
+/** The source sentence `code` was declared with (`schema/codes.json`); throws on a code this package never declared. */
+export function sourceOf(code: string): string {
+  const source = declaredCodes().get(code)?.text.en;
+  if (source === undefined) throw new Error(`plugin-qualify declares no source sentence for ${code}`);
+  return source;
+}
+
+/** `ref` rendered for `lang`: the catalog's sentence, else the source, its `{placeholder}`s filled. `lang` undefined or "en" skips the catalog. */
+export function textOf(ref: TextRef, lang?: string): string {
+  const source = sourceOf(ref.code);
+  const sentence = lang === undefined || lang === "en" ? source : (entrySentence(loadMessages(lang)?.[ref.code], source) ?? source);
+  return fill(sentence, ref.args ?? {});
+}
+
+/** A {@link ReasonText} rendered for `lang`: another tool's own words pass straight through; plugin-qualify's own go through {@link textOf}. */
+export function reasonText(reason: ReasonText, lang?: string): string {
+  return typeof reason === "string" ? reason : textOf(reason, lang);
+}
+
+/** The language of `LC_ALL`, else `LANG` (the POSIX precedence), as the two letters before `_` or `.`; `undefined` unset, unparsed, or `C`/`POSIX` (textOf's own fallback to the source sentence is the same as leaving this undefined). */
+export function localeOf(env: Readonly<Record<string, string | undefined>> = process.env): string | undefined {
+  const raw = env["LC_ALL"] || env["LANG"];
+  if (raw === undefined || raw === "") return undefined;
+  const m = /^([a-z]{2})(?:[_.].*)?$/.exec(raw);
+  return m?.[1];
+}

package/src/text-codes.generated.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+//
+// GENERATED by tools/gen-text-codes.mjs from schema/codes.json — do not hand-edit.
+//
+// Regenerate: node tools/gen-text-codes.mjs --write
+// Verify:     node tools/gen-text-codes.mjs --check
+
+/** plugin-qualify's own codes, by key (schema/codes.json). */
+export const TEXT_CODE = Object.freeze({
+  descriptorDuplicateSymbol: "qualify.descriptor.duplicate-symbol",
+  compareHostNotInstalled: "qualify.compare.host-not-installed",
+  compareHostDidNotStart: "qualify.compare.host-did-not-start",
+  compareHostNotAsked: "qualify.compare.host-not-asked",
+  compareHostDidNotRun: "qualify.compare.host-did-not-run",
+  compareFormatNotTaken: "qualify.compare.format-not-taken",
+  compareRtNotReported: "qualify.compare.rt-not-reported",
+  compareRtNoCallback: "qualify.compare.rt-no-callback",
+  compareRtNoWarmUp: "qualify.compare.rt-no-warm-up",
+  compareRtTrylocksOnly: "qualify.compare.rt-trylocks-only",
+  compareRtUnsafe: "qualify.compare.rt-unsafe",
+  compareLoadHostEnded: "qualify.compare.load-host-ended",
+  compareLoadResp: "qualify.compare.load-resp",
+  compareLoadTimeout: "qualify.compare.load-timeout",
+  compareNotLoaded: "qualify.compare.not-loaded",
+  compareNoPort: "qualify.compare.no-port",
+  compareNotRunning: "qualify.compare.not-running",
+  compareNoAudioOutput: "qualify.compare.no-audio-output",
+  compareOutputNotFinite: "qualify.compare.output-not-finite",
+  compareNoStimulusSilent: "qualify.compare.no-stimulus-silent",
+  compareSilentUnderStimulus: "qualify.compare.silent-under-stimulus",
+  compareCyclesNotRun: "qualify.compare.cycles-not-run",
+  compareCycleHostEnded: "qualify.compare.cycle-host-ended",
+  compareCycleFailed: "qualify.compare.cycle-failed",
+  compareCycleFailedAt: "qualify.compare.cycle-failed-at",
+  compareSoakHostEnded: "qualify.compare.soak-host-ended",
+  compareSoakEnded: "qualify.compare.soak-ended",
+  compareLatencyPortObservable: "qualify.compare.latency-port-observable",
+  compareLatencyHostdPortObservable: "qualify.compare.latency-hostd-port-observable",
+  compareLatencyNotObservableModHost: "qualify.compare.latency-not-observable-mod-host",
+  compareLatencyUnreadable: "qualify.compare.latency-unreadable",
+  compareSkippedReason: "qualify.compare.skipped-reason",
+  compareDoesBetterOn: "qualify.compare.does-better-on",
+  compareBeatDescription: "qualify.compare.beat-description",
+  compareNotPublishableWithMissing: "qualify.compare.not-publishable-with-missing",
+  compareNotPublishableNoFlag: "qualify.compare.not-publishable-no-flag",
+  pinHostdNotInstalled: "qualify.pin.hostd-not-installed",
+  pinHostdNoPinFiles: "qualify.pin.hostd-no-pin-files",
+  pinHostdExited: "qualify.pin.hostd-exited",
+  pinHostdNoRootOrFile: "qualify.pin.hostd-no-root-or-file",
+  pinFileUnreadable: "qualify.pin.file-unreadable",
+} as const);
+
+/** The args each code's source sentence names, by the same key. */
+export const TEXT_CODE_ARGS = Object.freeze({
+  descriptorDuplicateSymbol: ["symbol"],
+  compareHostNotInstalled: ["program"],
+  compareHostDidNotStart: ["program"],
+  compareHostNotAsked: [],
+  compareHostDidNotRun: ["program"],
+  compareFormatNotTaken: ["program", "format"],
+  compareRtNotReported: [],
+  compareRtNoCallback: [],
+  compareRtNoWarmUp: [],
+  compareRtTrylocksOnly: ["trylocks", "cycles"],
+  compareRtUnsafe: ["cycles", "allocations", "locks", "syscalls"],
+  compareLoadHostEnded: ["died"],
+  compareLoadResp: ["resp"],
+  compareLoadTimeout: [],
+  compareNotLoaded: [],
+  compareNoPort: [],
+  compareNotRunning: [],
+  compareNoAudioOutput: [],
+  compareOutputNotFinite: ["count"],
+  compareNoStimulusSilent: [],
+  compareSilentUnderStimulus: ["stimulus"],
+  compareCyclesNotRun: [],
+  compareCycleHostEnded: ["cycle", "died"],
+  compareCycleFailed: ["cycle"],
+  compareCycleFailedAt: ["cycle", "step"],
+  compareSoakHostEnded: ["died"],
+  compareSoakEnded: [],
+  compareLatencyPortObservable: [],
+  compareLatencyHostdPortObservable: [],
+  compareLatencyNotObservableModHost: [],
+  compareLatencyUnreadable: [],
+  compareSkippedReason: ["reason"],
+  compareDoesBetterOn: ["host", "count", "detail"],
+  compareBeatDescription: ["id", "on", "over"],
+  compareNotPublishableWithMissing: ["missing"],
+  compareNotPublishableNoFlag: [],
+  pinHostdNotInstalled: [],
+  pinHostdNoPinFiles: [],
+  pinHostdExited: ["status"],
+  pinHostdNoRootOrFile: [],
+  pinFileUnreadable: ["error"],
+} as const);

package/src/text-codes.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * plugin-qualify's own verdict and reason sentences, as codes (omx-contract#2, "codes then catalogs", owner
+ * ruling 2026-11-09: a code carries its identifier, its arguments and one source sentence in English with named
+ * placeholders; translations live in catalogs the owner ships, keyed by code, checked for placeholders against the
+ * code's `args`; a surface looks up the sentence for the user's locale and falls back to this source sentence).
+ *
+ * plugin-qualify is the owner of these codes (the hosting.* codes of {@link ../hosting-codes.js} are omx-clap-core's
+ * instead, and that package owns their catalogs). A code, its args and its source sentence are written once, in
+ * `schema/codes.json`; {@link TEXT_CODE} is that file's `key: code` map, generated (`tools/gen-text-codes.mjs`), so a
+ * call site names a code by its key and no sentence is written in a module. `catalogs/<lang>.json`, read by
+ * {@link ../text-catalog.js}, hold each listed language's sentences; `src/text-catalog-conformance.test.ts` turns red
+ * on a code without its source sentence or without an entry in a language, and on a sentence whose placeholders are
+ * not its code's `args`.
+ */
+import { TEXT_CODE, TEXT_CODE_ARGS } from "./text-codes.generated.js";
+
+export { TEXT_CODE, TEXT_CODE_ARGS };
+
+/** A key of {@link TEXT_CODE}. */
+export type TextCodeKey = keyof typeof TEXT_CODE;
+
+/** A code of {@link TEXT_CODE} with the arguments its source sentence names. A reader renders it; it is never prose itself. */
+export interface TextRef {
+  readonly code: string;
+  readonly args?: Readonly<Record<string, string | number>>;
+}
+
+/**
+ * A reason as plugin-qualify writes it: its own sentence as a {@link TextRef}, or another tool's own words passed
+ * through unclassified (the shape `UnmeasuredFigure.detail` already uses elsewhere: a prober's raw text is never
+ * coded, since nothing here can translate words it did not write).
+ */
+export type ReasonText = TextRef | string;

package/tools/catalogs-gate.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#
+# The catalogs through omx-contract's release gate (translate --check, 3.16.0): every listed language has its
+# catalog, no key is missing and no entry is stale. The codes are a bare item file (schema/codes.json); the gate reads
+# a vocabulary, so it is handed one holding that item alone.
+#
+#   tools/catalogs-gate.sh [translate options]   (default --check; e.g. --lang es --model <alias> to make a language)
+
+set -eu
+cd "$(dirname "$0")/.."
+owner=$(python3 -c 'import json; print(json.load(open("package.json"))["name"].split("/")[-1])')
+data=$(mktemp -d)
+trap 'rm -r "$data"' EXIT
+python3 - "$data/codes.json" "$owner" <<'EOF'
+import json, sys
+item = sys.argv[2].upper().replace("-", "_") + "_CODES"
+json.dump({item: json.load(open("schema/codes.json"))}, open(sys.argv[1], "w"), ensure_ascii=False)
+EOF
+[ "$#" -gt 0 ] || set -- --check
+exec omx-contract translate "$@" --data "$data" --catalogs catalogs --package "$owner"

package/tools/compare-host.mjs

@@ -316,7 +316,7 @@ async function protocolHost() {
   for (let i = 0; i < CYCLES; i++) {
     const base = ports() ?? [];
     const a = await ask(`add ${spec} ${INSTANCE}`);
-    if (i === 0) obs.load = a.resp !== undefined ? { ok: a.resp >= 0, resp: a.resp } : { ok: false, ...(a.died ? { died: a.died } : { detail: "no answer in time" }) };
+    if (i === 0) obs.load = a.resp !== undefined ? { ok: a.resp >= 0, resp: a.resp } : { ok: false, ...(a.died ? { died: a.died } : {}) };
     if (a.resp === undefined || a.resp < 0) {
       obs.cycles = { done, of: CYCLES, failedAt: "add", ...(a.died ? { died: a.died } : {}) };
       if (!alive() || closed) crashed(i === 0 ? "load" : `cycle ${String(i + 1)}`);

package/tools/compare-run.mjs

@@ -32,8 +32,12 @@ import {
   summaryHelpText,
   summaryTable,
   writeFileWhole,
+  localeOf,
+  reasonText,
+  TEXT_CODE,
 } from "../dist/index.js";
 
+const LANG = localeOf();
 const DRIVER = fileURLToPath(new URL("./compare-host.mjs", import.meta.url));
 const log = (line) => process.stderr.write(`plugin-qualify compare: ${line}\n`);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -62,7 +66,7 @@ function presence(hosts) {
     const program = HOST_TRAITS[host].program;
     const w = sh("sh", ["-c", `command -v "$1"`, "sh", program]);
     const path = w.status === 0 ? w.stdout.trim() : "";
-    if (!path) return { host, installed: false, version: null, reason: `${program} is not installed (not on PATH)` };
+    if (!path) return { host, installed: false, version: null, reason: { code: TEXT_CODE.compareHostNotInstalled, args: { program } } };
     return { host, installed: true, version: versionOf(program, path) };
   });
 }
@@ -187,7 +191,7 @@ function writeSummary(dir, records, present, meta, format) {
     writeFileWhole(join(dir, COMPARISON_SUMMARY_FILE), `${JSON.stringify(summary, null, 2)}\n`);
     log(`summary ${join(dir, COMPARISON_SUMMARY_FILE)}`);
   }
-  process.stdout.write(format === "json" ? `${JSON.stringify(summary, null, 2)}\n` : summaryTable(summary));
+  process.stdout.write(format === "json" ? `${JSON.stringify(summary, null, 2)}\n` : summaryTable(summary, LANG));
   return summary;
 }
 
@@ -209,7 +213,7 @@ export async function compareSummaryMain(argv) {
   const present = presenceFromRecords(records);
   const missing = missingReferences(present);
   if (parsed.args.publish && missing.length) {
-    for (const m of missing) log(`not publishable: ${m.host}: ${m.reason}`);
+    for (const m of missing) log(`not publishable: ${m.host}: ${reasonText(m.reason, LANG)}`);
     return 1;
   }
   writeSummary(parsed.args.dir, records, present, { hostClass: parsed.args.hostClass, set: parsed.args.set, publish: parsed.args.publish }, "text");
@@ -229,11 +233,11 @@ export async function compareMain(argv) {
     return 0;
   }
   const present = presence(a.hosts);
-  for (const p of present) log(p.installed ? `host ${p.host}: ${p.version ?? "version unknown"}` : `host ${p.host}: skipped, ${p.reason}`);
+  for (const p of present) log(p.installed ? `host ${p.host}: ${p.version ?? "version unknown"}` : `host ${p.host}: skipped, ${reasonText(p.reason, LANG)}`);
   const missing = missingReferences(present);
   if (a.publish && missing.length) {
     // a publishable comparison is against both references: refused before anything runs, each missing one named
-    for (const m of missing) log(`--publish refused: ${m.host}: ${m.reason}`);
+    for (const m of missing) log(`--publish refused: ${m.host}: ${reasonText(m.reason, LANG)}`);
     log(`install them (see the README, "Compare with mod-host and jalv"), or run without --publish for a local look`);
     return 1;
   }
@@ -337,7 +341,7 @@ export async function compareMain(argv) {
         rows.push(row);
         const c = row.checks;
         log(
-          `[${String(i + 1)}/${String(targets.length)}] ${t.uri} ${p.host}: ${row.status === "ran" ? `${row.runsClean ? "clean" : "not clean"}; load ${c.loads.result}, output ${c.output.result}, cycles ${c.cycles.result}, soak ${c.soak.result}, rt ${c.rtSafe.result}${row.crash ? `, crashed at ${row.crash.step} (${row.crash.signal})` : ""}` : `${row.status}: ${row.reason}`}`,
+          `[${String(i + 1)}/${String(targets.length)}] ${t.uri} ${p.host}: ${row.status === "ran" ? `${row.runsClean ? "clean" : "not clean"}; load ${c.loads.result}, output ${c.output.result}, cycles ${c.cycles.result}, soak ${c.soak.result}, rt ${c.rtSafe.result}${row.crash ? `, crashed at ${row.crash.step} (${row.crash.signal})` : ""}` : `${row.status}: ${reasonText(row.reason, LANG)}`}`,
         );
       }
       const rec = comparisonRecordOf({ format: t.format, id: t.uri, ...(t.binary ? { binary: t.binary } : {}) }, stimulus, conditions, new Date().toISOString(), rows);

package/tools/gen-text-codes.d.mts

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/** Where the codes are declared, `schema/codes.json`. */
+export const SOURCE: string;
+/** The committed generated module, `src/text-codes.generated.ts`. */
+export const OUT: string;
+/** The generated module's text for the `codes` of a codes file. */
+export function textCodesFile(codes: Readonly<Record<string, { readonly code: string; readonly args?: readonly string[] }>>): string;

package/tools/gen-text-codes.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/*
+ * gen-text-codes.mjs — `src/text-codes.generated.ts`, the codes of schema/codes.json as one `key: code` map
+ * and the args each one names, as plain data.
+ *
+ * schema/codes.json is where a code, its args and its English source sentence are written, once. The call sites
+ * (src/compare.ts, src/hostd-pin-files.ts) name a code by its key; they reach it as a generated module rather than a read at
+ * import, so every module a public subpath reaches stays free of `node:` imports and bundles for a browser (#134).
+ * No sentence is in the generated module: the sentence is read from schema/codes.json where it is rendered
+ * (src/text-catalog.ts). The file is committed and checked identical, as src/hosting-codes.generated.ts is.
+ *
+ * Usage:
+ *   node tools/gen-text-codes.mjs --check   # exit 1 if the committed file is stale
+ *   node tools/gen-text-codes.mjs --write   # (re)write the committed file
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const SOURCE = join(PKG, 'schema/codes.json');
+export const OUT = join(PKG, 'src/text-codes.generated.ts');
+
+/** The generated module's text for the `codes` of a codes file. */
+export function textCodesFile(codes) {
+  const entries = Object.entries(codes);
+  const code = entries.map(([key, c]) => `  ${key}: ${JSON.stringify(c.code)},\n`);
+  const args = entries.map(([key, c]) => `  ${key}: [${(c.args ?? []).map((a) => JSON.stringify(a)).join(', ')}],\n`);
+  return (
+    `// SPDX-License-Identifier: GPL-3.0-or-later\n` +
+    `// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>\n` +
+    `//\n` +
+    `// GENERATED by tools/gen-text-codes.mjs from schema/codes.json — do not hand-edit.\n` +
+    `//\n` +
+    `// Regenerate: node tools/gen-text-codes.mjs --write\n` +
+    `// Verify:     node tools/gen-text-codes.mjs --check\n` +
+    `\n` +
+    `/** plugin-qualify's own codes, by key (schema/codes.json). */\n` +
+    `export const TEXT_CODE = Object.freeze({\n` +
+    code.join('') +
+    `} as const);\n` +
+    `\n` +
+    `/** The args each code's source sentence names, by the same key. */\n` +
+    `export const TEXT_CODE_ARGS = Object.freeze({\n` +
+    args.join('') +
+    `} as const);\n`
+  );
+}
+
+function main() {
+  const mode = process.argv[2];
+  if (!['--check', '--write'].includes(mode)) {
+    console.error('usage: node tools/gen-text-codes.mjs --check|--write');
+    process.exit(2);
+  }
+  const content = textCodesFile(JSON.parse(readFileSync(SOURCE, 'utf8')).codes);
+  let onDisk;
+  try {
+    onDisk = readFileSync(OUT, 'utf8');
+  } catch {
+    onDisk = undefined;
+  }
+  if (mode === '--check') {
+    if (onDisk !== content) {
+      console.error(`gen-text-codes: ${OUT} is stale against ${SOURCE} — run with --write`);
+      process.exit(1);
+    }
+    console.log('gen-text-codes: up to date');
+    return;
+  }
+  if (onDisk !== content) writeFileSync(OUT, content);
+  console.log(`gen-text-codes: ${onDisk === content ? 'up to date' : 'wrote'} ${OUT}`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();