@openmixer/plugin-qualify 0.20.1 → 0.20.4

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/_declarations.py

@@ -11,7 +11,7 @@
 # Verify:     node tools/gen-python-declarations.mjs --check
 
 COST_REFERENCE_RATE = 96000
-QUANTUM_FRAMES = 1024
+QUANTUM_FRAMES = 256
 MEASURE_BASE_RATE = 48000
 OPERATIONAL_RATE_FLOOR = 48000
 QUALIFY_RATES = (44100, 48000, 96000, 192000)
@@ -33,3 +33,4 @@ DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing"
 DESCRIPTOR_CODE_SCHEMA_FLOOR = "qualify.descriptor.schema-floor"
 DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed"
 DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable"
+DESCRIPTOR_CODE_DUPLICATE_SYMBOL = "qualify.descriptor.duplicate-symbol"

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/descriptors.py

@@ -30,6 +30,7 @@ import sys
 from _declarations import (
     DESCRIPTOR_CODE_BINARY_UNHASHED,
     DESCRIPTOR_CODE_DIR_UNWRITABLE,
+    DESCRIPTOR_CODE_DUPLICATE_SYMBOL,
     DESCRIPTOR_CODE_SCHEMA,
     DESCRIPTOR_CODE_SCHEMA_MISSING,
     DESCRIPTOR_DIR_STATE_SUBDIR,
@@ -49,12 +50,44 @@ FEATURE_WORDS = ("audio-effect", "instrument", "note-effect", "analyzer")
 
 
 class DescriptorRefused(Exception):
-    """A descriptor that is not written, with the code it is refused by."""
+    """A descriptor that is not written, with the code it is refused by (and, for a code `schema/codes.json`
+    declares, the args its sentence names)."""
 
-    def __init__(self, code, problem):
+    def __init__(self, code, problem, args=None):
         super().__init__(f"{code}: {problem}")
         self.code = code
         self.problem = problem
+        self.code_args = dict(args or {})
+
+
+# ---- the codes' sentences -----------------------------------------------------------------------
+
+CODES_FILE = os.path.join(PKG, "schema", "codes.json")
+
+
+def code_sentence(code, args, path=CODES_FILE):
+    """The English source sentence of `code` (schema/codes.json) with `args` filled in. A code the file does not
+    declare, or no file, reads as the code and its args, so a refusal is never lost for want of its words."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            entries = {e["code"]: e for e in json.load(f)["codes"].values()}
+        return entries[code]["text"]["en"].format(**args)
+    except (OSError, ValueError, KeyError, IndexError):
+        return f"{code} " + " ".join(f"{k}={v}" for k, v in sorted(args.items()))
+
+
+def refused(code, **args):
+    """A refusal by `code`, its args and its sentence."""
+    return DescriptorRefused(code, code_sentence(code, args), args)
+
+
+def duplicate_symbol(symbols):
+    """The first (sorted) symbol `symbols` holds twice, else None: two ports with one symbol cannot be addressed
+    by it (EQ10Q's eq1qs..eq10qs name both output meters out_2_vu_ctl, plugin-qualify#27)."""
+    seen, twice = set(), set()
+    for s in symbols:
+        (twice if s in seen else seen).add(s)
+    return min(twice) if twice else None
 
 
 # ---- the directory and the name -----------------------------------------------------------------
@@ -71,7 +104,11 @@ def descriptor_dir(named=None, system=False, env=None, home=None):
 
 
 def _safe(text):
-    return re.sub(r"[^A-Za-z0-9._-]", "_", text)
+    """each byte of the UTF-8 text outside [A-Za-z0-9._-] as one '_', plugin-hostd-protocol's descriptor name rule"""
+    return "".join(chr(b) if chr(b) in _SAFE else "_" for b in text.encode("utf-8"))
+
+
+_SAFE = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-")
 
 
 def descriptor_file_name(plugin_id, version, sha256):

package/tools/gen-python-declarations.mjs

@@ -49,6 +49,7 @@ const PY_NAMES = [
   'DESCRIPTOR_CODE_SCHEMA_FLOOR',
   'DESCRIPTOR_CODE_BINARY_UNHASHED',
   'DESCRIPTOR_CODE_DIR_UNWRITABLE',
+  'DESCRIPTOR_CODE_DUPLICATE_SYMBOL',
 ];
 
 /** A Python literal: a tuple, a string (JSON's quoting is Python's for these ASCII words) or a number. */

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();

package/tools/isolated-step.mjs

@@ -5,7 +5,7 @@
 // added alone, worker_list read, a sine through it for a window, and worker_list read again. Prints one JSON line for
 // src/qualify-isolated.ts to judge. A host that never listened says started: false: nothing was learned about the plugin.
 import { spawn, spawnSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync } from "node:fs";
 import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -25,7 +25,11 @@ const CLOCK_TICKS = 100;
 const WORKER_SPAWN = -503;
 
 const state = mkdtempSync(join(tmpdir(), "plugin-qualify-isolated-"));
-const host = spawn(hostd, ["-n", "-p", String(port)], { stdio: "ignore", detached: true, env: { ...process.env, XDG_STATE_HOME: state } });
+// the daemon says why it refused a plugin on stderr only: kept, so a refused add carries that reason into the record
+const hostLog = join(state, "plugin-hostd.stderr");
+const hostLogFd = openSync(hostLog, "a");
+const host = spawn(hostd, ["-n", "-p", String(port)], { stdio: ["ignore", "ignore", hostLogFd], detached: true, env: { ...process.env, XDG_STATE_HOME: state } });
+closeSync(hostLogFd);
 let ended = false;
 host.on("exit", () => (ended = true));
 host.on("error", () => (ended = true));
@@ -78,6 +82,19 @@ function cpuTicks(pid) {
   }
 }
 
+/** The last thing the daemon said of `uri` beyond its having no pin yet (first-use learns one at add): "" when nothing. */
+function daemonReason() {
+  let text = "";
+  try {
+    text = readFileSync(hostLog, "utf8");
+  } catch {
+    return "";
+  }
+  const prefix = `plugin-hostd: ${uri}: `;
+  const said = text.split("\n").filter((l) => l.startsWith(prefix)).map((l) => l.slice(prefix.length).trim()).filter((l) => l !== "" && l !== "no pin");
+  return said.at(-1) ?? "";
+}
+
 async function main() {
   const sock = await connect();
   if (sock === undefined) return { started: false, problem: `${hostd} did not listen` };
@@ -85,7 +102,11 @@ async function main() {
   const added = await send(`add ${pinWord(uri)} ${String(INSTANCE)}`);
   // WORKER_SPAWN: no worker came up to hold the plugin, which says nothing of the plugin. The next pass tries it again.
   if (added?.code === WORKER_SPAWN) return { started: false, problem: `no worker came up: add answered ${String(WORKER_SPAWN)}` };
-  if (added === undefined || added.code < 0) return { started: true, added: false, problem: added === undefined ? "the host gave no answer to add" : `add answered ${String(added.code)}` };
+  if (added === undefined || added.code < 0) {
+    const why = daemonReason();
+    const answered = added === undefined ? "the host gave no answer to add" : `add answered ${String(added.code)}`;
+    return { started: true, added: false, problem: why === "" ? answered : `${answered}: ${why}` };
+  }
   const before = workersOf(await send("worker_list"));
   const worker = before[0];
   const ticksBefore = worker === undefined ? undefined : cpuTicks(worker.pid);