@openmixer/plugin-qualify 0.20.3 → 0.20.4

package/src/compare.ts

@@ -15,6 +15,9 @@
  */
 import { createHash } from "node:crypto";
 
+import { TEXT_CODE, type ReasonText } from "./text-codes.js";
+import { reasonText } from "./text-catalog.js";
+
 export const COMPARISON_RECORD_SCHEMA = "plugin-qualify.comparison-record/1";
 export const COMPARISON_SUMMARY_SCHEMA = "plugin-qualify.comparison-summary/1";
 export const COMPARISON_RECORD_SUFFIX = ".comparison.json";
@@ -33,7 +36,7 @@ export interface HostTraits {
   readonly drive: "protocol" | "process";
   readonly formats: readonly ("lv2" | "clap")[];
   /** Why the plugin latency it reports is or is not observable. */
-  readonly latency: { readonly observable: boolean; readonly how: string };
+  readonly latency: { readonly observable: boolean; readonly how: ReasonText };
   readonly rt: string;
 }
 
@@ -42,28 +45,28 @@ export const HOST_TRAITS: Readonly<Record<CompareHost, HostTraits>> = {
     program: "omx-clap-host",
     drive: "protocol",
     formats: ["lv2", "clap"],
-    latency: { observable: true, how: "the host sets a JACK latency callback: the plugin's latency is on its output port's capture range" },
+    latency: { observable: true, how: { code: TEXT_CODE.compareLatencyPortObservable } },
     rt: "its JACK process callback, counted by rt_watch.so",
   },
   "plugin-hostd": {
     program: "plugin-hostd",
     drive: "protocol",
     formats: ["lv2", "clap"],
-    latency: { observable: true, how: "its worker (omx-clap-host) sets a JACK latency callback" },
+    latency: { observable: true, how: { code: TEXT_CODE.compareLatencyHostdPortObservable } },
     rt: "the JACK process callback of every process it starts, counted by rt_watch.so",
   },
   "mod-host": {
     program: "mod-host",
     drive: "protocol",
     formats: ["lv2"],
-    latency: { observable: false, how: "mod-host sets no JACK latency callback, so a plugin's latency is not on its ports" },
+    latency: { observable: false, how: { code: TEXT_CODE.compareLatencyNotObservableModHost } },
     rt: "its JACK process callback, counted by rt_watch.so",
   },
   jalv: {
     program: "jalv",
     drive: "process",
     formats: ["lv2"],
-    latency: { observable: true, how: "jalv sets a JACK latency callback: the plugin's latency is on its output port's capture range" },
+    latency: { observable: true, how: { code: TEXT_CODE.compareLatencyPortObservable } },
     rt: "its JACK process callback, counted by rt_watch.so",
   },
 };
@@ -234,15 +237,15 @@ export interface HostPresence {
   readonly installed: boolean;
   readonly version: string | null;
   /** Why it is skipped, when it is. */
-  readonly reason?: string;
+  readonly reason?: ReasonText;
 }
 
 /** The reference hosts a publishable summary lacks, by name, with the reason each is missing. */
-export function missingReferences(present: readonly HostPresence[]): readonly { host: CompareHost; reason: string }[] {
+export function missingReferences(present: readonly HostPresence[]): readonly { host: CompareHost; reason: ReasonText }[] {
   return REFERENCE_HOSTS.flatMap((h) => {
     const p = present.find((x) => x.host === h);
-    if (p === undefined) return [{ host: h, reason: "not asked for with --hosts" }];
-    if (!p.installed) return [{ host: h, reason: p.reason ?? `${HOST_TRAITS[h].program} is not installed` }];
+    if (p === undefined) return [{ host: h, reason: { code: TEXT_CODE.compareHostNotAsked } }];
+    if (!p.installed) return [{ host: h, reason: p.reason ?? { code: TEXT_CODE.compareHostNotInstalled, args: { program: HOST_TRAITS[h].program } } }];
     return [];
   });
 }
@@ -256,7 +259,7 @@ export function presenceFromRecords(records: readonly ComparisonRecord[]): HostP
     if (ran !== undefined) return [{ host: h, installed: true, version: ran.version }];
     if (rows.every((x) => x.status === "not-applicable")) return [{ host: h, installed: true, version: rows[0]?.version ?? null }];
     const skipped = rows.find((x) => x.status === "skipped");
-    return [{ host: h, installed: false, version: null, reason: skipped?.reason ?? `${HOST_TRAITS[h].program} did not run` }];
+    return [{ host: h, installed: false, version: null, reason: skipped?.reason ?? { code: TEXT_CODE.compareHostDidNotRun, args: { program: HOST_TRAITS[h].program } } }];
   });
 }
 
@@ -308,7 +311,7 @@ export type FigureResult = "measured" | "not-observable" | "not-run";
 
 export interface Check {
   readonly result: CheckResult;
-  readonly detail?: string;
+  readonly detail?: ReasonText;
 }
 export interface OutputCheck extends Check {
   readonly peak?: number;
@@ -335,12 +338,12 @@ export interface CpuFigure {
   readonly result: FigureResult;
   /** utime + stime of the host's processes over the soak, in percent of one core. */
   readonly percent?: number;
-  readonly detail?: string;
+  readonly detail?: ReasonText;
 }
 export interface LatencyFigure {
   readonly result: FigureResult;
   readonly frames?: number;
-  readonly detail?: string;
+  readonly detail?: ReasonText;
 }
 
 export interface HostChecks {
@@ -358,7 +361,7 @@ export interface HostRow {
   readonly host: CompareHost;
   readonly version: string | null;
   readonly status: "ran" | "skipped" | "not-applicable";
-  readonly reason?: string;
+  readonly reason?: ReasonText;
   readonly checks?: HostChecks;
   /** The step the host died at and how, when it did. */
   readonly crash?: { readonly step: string; readonly signal: string };
@@ -410,11 +413,11 @@ const audible = (p: number | null | undefined): boolean => typeof p === "number"
 
 /** The real-time verdict from the reports of the host's processes. */
 export function rtCheckOf(reports: readonly RtReport[] | undefined): RtCheck {
-  if (reports === undefined || reports.length === 0) return { result: "not-observable", detail: "no process of the host reported (rt_watch.so was not loaded, or the host was gone)" };
+  if (reports === undefined || reports.length === 0) return { result: "not-observable", detail: { code: TEXT_CODE.compareRtNotReported } };
   const watched = reports.filter((r) => r.callbacks > 0);
   const armed = watched.reduce((s, r) => s + r.armedCycles, 0);
-  if (watched.length === 0) return { result: "not-observable", detail: "no process of the host set a JACK process callback that rt_watch.so could wrap" };
-  if (armed === 0) return { result: "not-observable", detail: "the process callback never ran past its warm-up" };
+  if (watched.length === 0) return { result: "not-observable", detail: { code: TEXT_CODE.compareRtNoCallback } };
+  if (armed === 0) return { result: "not-observable", detail: { code: TEXT_CODE.compareRtNoWarmUp } };
   const allocations = watched.reduce((s, r) => s + r.allocations, 0);
   const locks = watched.reduce((s, r) => s + r.locks, 0);
   const syscalls = watched.reduce((s, r) => s + r.syscalls, 0);
@@ -429,65 +432,92 @@ export function rtCheckOf(reports: readonly RtReport[] | undefined): RtCheck {
     syscalls,
     cycles: armed,
     ...(kinds.length ? { kinds } : {}),
-    ...(clean ? (trylocks > 0 ? { detail: `${String(trylocks)} try-locks on the audio thread over ${String(armed)} cycles; a try-lock never waits` } : {}) : { detail: `on the audio thread over ${String(armed)} cycles: ${String(allocations)} allocations, ${String(locks)} locks, ${String(syscalls)} system calls` }),
+    ...(clean
+      ? trylocks > 0
+        ? { detail: { code: TEXT_CODE.compareRtTrylocksOnly, args: { trylocks, cycles: armed } } }
+        : {}
+      : { detail: { code: TEXT_CODE.compareRtUnsafe, args: { cycles: armed, allocations, locks, syscalls } } }),
   };
 }
 
-const NOT_RUN = (why: string): Check => ({ result: "not-run", detail: why });
+const NOT_RUNNING: ReasonText = { code: TEXT_CODE.compareNotRunning };
+const NOT_RUN = (why: ReasonText): Check => ({ result: "not-run", detail: why });
 
 /** One host's observation of one plugin as its row. */
 export function hostRowOf(host: CompareHost, version: string | null, obs: HostObservation, conditions: { cycles: number; soakS: number }): HostRow {
   const base = { host, version };
-  if (!obs.installed) return { ...base, status: "skipped", reason: obs.problem ?? `${HOST_TRAITS[host].program} is not installed` };
-  if (obs.started === false) return { ...base, status: "skipped", reason: obs.problem ?? `${HOST_TRAITS[host].program} did not start` };
+  if (!obs.installed) return { ...base, status: "skipped", reason: obs.problem ?? { code: TEXT_CODE.compareHostNotInstalled, args: { program: HOST_TRAITS[host].program } } };
+  if (obs.started === false) return { ...base, status: "skipped", reason: obs.problem ?? { code: TEXT_CODE.compareHostDidNotStart, args: { program: HOST_TRAITS[host].program } } };
   const load = obs.load;
   const loaded = load?.ok === true;
   const loads: Check = loaded
     ? { result: "pass" }
-    : { result: "fail", detail: load?.died ? `the host ended (${load.died})` : load?.resp !== undefined ? `resp ${String(load.resp)}` : load?.detail ?? "no answer in time" };
+    : {
+        result: "fail",
+        detail: load?.died
+          ? { code: TEXT_CODE.compareLoadHostEnded, args: { died: load.died } }
+          : load?.resp !== undefined
+            ? { code: TEXT_CODE.compareLoadResp, args: { resp: load.resp } }
+            : (load?.detail ?? { code: TEXT_CODE.compareLoadTimeout }),
+      };
   const ports = obs.ports;
   const anyPort = ports !== undefined && ports.audioIn + ports.audioOut + ports.midiIn > 0;
-  const instantiates: Check = !loaded ? NOT_RUN("it did not load") : anyPort ? { result: "pass" } : { result: "fail", detail: "no port of the plugin appeared on the graph" };
+  const instantiates: Check = !loaded
+    ? NOT_RUN({ code: TEXT_CODE.compareNotLoaded })
+    : anyPort
+      ? { result: "pass" }
+      : { result: "fail", detail: { code: TEXT_CODE.compareNoPort } };
   const running = loaded && anyPort;
 
   let output: OutputCheck;
-  if (!running) output = { ...NOT_RUN("it is not running") };
-  else if (ports.audioOut === 0) output = { result: "not-observable", detail: "the plugin has no audio output" };
+  if (!running) output = { ...NOT_RUN(NOT_RUNNING) };
+  else if (ports.audioOut === 0) output = { result: "not-observable", detail: { code: TEXT_CODE.compareNoAudioOutput } };
   else if (obs.peakProblem !== undefined) output = { result: "not-observable", detail: obs.peakProblem };
-  else if ((obs.nonFinite ?? 0) > 0) output = { result: "fail", detail: `the output is not finite (${String(obs.nonFinite)} NaN or infinite samples)`, peak: obs.peak ?? 0, stimulus: obs.stimulus ?? "none" };
+  else if ((obs.nonFinite ?? 0) > 0)
+    output = { result: "fail", detail: { code: TEXT_CODE.compareOutputNotFinite, args: { count: obs.nonFinite ?? 0 } }, peak: obs.peak ?? 0, stimulus: obs.stimulus ?? "none" };
   else if (audible(obs.peak)) output = { result: "pass", peak: obs.peak as number, stimulus: obs.stimulus ?? "none" };
-  else if (obs.stimulus === "none" || obs.stimulus === undefined) output = { result: "not-observable", detail: "no stimulus this plugin takes (no audio or MIDI input), and its output was silent", peak: obs.peak ?? 0, stimulus: "none" };
-  else output = { result: "fail", detail: `silent under ${obs.stimulus}`, peak: obs.peak ?? 0, stimulus: obs.stimulus };
+  else if (obs.stimulus === "none" || obs.stimulus === undefined)
+    output = { result: "not-observable", detail: { code: TEXT_CODE.compareNoStimulusSilent }, peak: obs.peak ?? 0, stimulus: "none" };
+  else output = { result: "fail", detail: { code: TEXT_CODE.compareSilentUnderStimulus, args: { stimulus: obs.stimulus } }, peak: obs.peak ?? 0, stimulus: obs.stimulus };
 
   const c = obs.cycles;
   const cycles: CyclesCheck =
     c === undefined
-      ? { result: "not-run", done: 0, of: conditions.cycles, detail: "the cycles did not run" }
+      ? { result: "not-run", done: 0, of: conditions.cycles, detail: { code: TEXT_CODE.compareCyclesNotRun } }
       : c.done === c.of
         ? { result: "pass", done: c.done, of: c.of }
-        : { result: "fail", done: c.done, of: c.of, detail: c.died ? `the host ended at cycle ${String(c.done + 1)} (${c.died})` : `cycle ${String(c.done + 1)} failed${c.failedAt ? ` at ${c.failedAt}` : ""}` };
+        : {
+            result: "fail",
+            done: c.done,
+            of: c.of,
+            detail: c.died
+              ? { code: TEXT_CODE.compareCycleHostEnded, args: { cycle: c.done + 1, died: c.died } }
+              : c.failedAt
+                ? { code: TEXT_CODE.compareCycleFailedAt, args: { cycle: c.done + 1, step: c.failedAt } }
+                : { code: TEXT_CODE.compareCycleFailed, args: { cycle: c.done + 1 } },
+          };
 
   const s = obs.soak;
   const soak: SoakCheck = !running || s === undefined
-    ? { result: "not-run", seconds: 0, detail: "it is not running" }
+    ? { result: "not-run", seconds: 0, detail: NOT_RUNNING }
     : s.alive
       ? { result: "pass", seconds: s.seconds, ...(typeof s.peakAtEnd === "number" ? { peakAtEnd: s.peakAtEnd } : {}) }
-      : { result: "fail", seconds: s.seconds, detail: `the host ended during the soak${s.died ? ` (${s.died})` : ""}` };
+      : { result: "fail", seconds: s.seconds, detail: s.died ? { code: TEXT_CODE.compareSoakHostEnded, args: { died: s.died } } : { code: TEXT_CODE.compareSoakEnded } };
 
-  const rtSafe: RtCheck = !running ? { result: "not-run", detail: "it is not running" } : rtCheckOf(obs.rt);
+  const rtSafe: RtCheck = !running ? { result: "not-run", detail: NOT_RUNNING } : rtCheckOf(obs.rt);
   const cpu: CpuFigure = !running || obs.cpu === undefined
-    ? { result: "not-run", detail: "it is not running" }
+    ? { result: "not-run", detail: NOT_RUNNING }
     : "percent" in obs.cpu
       ? { result: "measured", percent: Math.round(obs.cpu.percent * 100) / 100 }
       : { result: "not-observable", detail: obs.cpu.problem };
   const traits = HOST_TRAITS[host];
   const latency: LatencyFigure = !running
-    ? { result: "not-run", detail: "it is not running" }
+    ? { result: "not-run", detail: NOT_RUNNING }
     : !traits.latency.observable
       ? { result: "not-observable", detail: traits.latency.how }
       : typeof obs.latencyFrames === "number"
         ? { result: "measured", frames: obs.latencyFrames }
-        : { result: "not-observable", detail: "the output port's latency could not be read" };
+        : { result: "not-observable", detail: { code: TEXT_CODE.compareLatencyUnreadable } };
 
   const crashed = obs.died !== undefined;
   const runsClean = !crashed && loaded && running && cycles.result === "pass" && soak.result === "pass" && output.result !== "fail";
@@ -542,7 +572,7 @@ export function comparisonRecordOf(
 
 /** The row of a host that does not take this plugin's format. */
 export function notApplicableRow(host: CompareHost, version: string | null, format: string): HostRow {
-  return { host, version, status: "not-applicable", reason: `${HOST_TRAITS[host].program} takes no ${format.toUpperCase()} plugin` };
+  return { host, version, status: "not-applicable", reason: { code: TEXT_CODE.compareFormatNotTaken, args: { program: HOST_TRAITS[host].program, format: format.toUpperCase() } } };
 }
 
 /** Problems with a record's shape, empty when it is one: the records repository's check holds the same rules. */
@@ -567,7 +597,7 @@ export interface HostTotals {
   readonly host: CompareHost;
   readonly version: string | null;
   readonly status: "ran" | "skipped";
-  readonly reason?: string;
+  readonly reason?: ReasonText;
   /** Plugins of a format the host takes. */
   readonly plugins: number;
   readonly loads: number;
@@ -597,7 +627,7 @@ export interface ComparisonSummary {
   readonly set: string | null;
   readonly measured: string | null;
   readonly publishable: boolean;
-  readonly missing: readonly { host: CompareHost; reason: string }[];
+  readonly missing: readonly { host: CompareHost; reason: ReasonText }[];
   readonly conditions: ComparisonConditions | null;
   readonly records: number;
   /** Plugins every host that ran takes and ran: the like-for-like set the headline counts. */
@@ -636,7 +666,7 @@ export function summarise(
       host: h,
       version,
       status: skipped ? "skipped" : "ran",
-      ...(skipped ? { reason: p?.reason ?? `${HOST_TRAITS[h].program} is not installed` } : {}),
+      ...(skipped ? { reason: p?.reason ?? { code: TEXT_CODE.compareHostNotInstalled, args: { program: HOST_TRAITS[h].program } } } : {}),
       plugins: rows.length,
       loads: count((r) => r.checks?.loads.result === "pass"),
       instantiates: count((r) => r.checks?.instantiates.result === "pass"),
@@ -681,19 +711,29 @@ export function summarise(
   };
 }
 
-/** The text table of a summary, for the terminal. */
-export function summaryTable(s: ComparisonSummary): string {
+/** The text table of a summary, for the terminal, in `lang` (the catalog's sentence, else the English source). */
+export function summaryTable(s: ComparisonSummary, lang?: string): string {
   const lines = [`host            version                     plugins loads clean rt-safe/observed crashes cpu%`];
   for (const t of s.hosts) {
     if (t.status === "skipped") {
-      lines.push(`${t.host.padEnd(15)} skipped: ${t.reason ?? ""}`);
+      lines.push(`${t.host.padEnd(15)} ${reasonText({ code: TEXT_CODE.compareSkippedReason, args: { reason: t.reason === undefined ? "" : reasonText(t.reason, lang) } }, lang)}`);
       continue;
     }
     lines.push(
       `${t.host.padEnd(15)} ${(t.version ?? "?").padEnd(27)} ${String(t.plugins).padStart(7)} ${String(t.loads).padStart(5)} ${String(t.runsClean).padStart(5)} ${`${String(t.rtSafe)}/${String(t.rtObserved)}`.padStart(16)} ${String(t.crashes).padStart(7)} ${t.cpuMedianPercent === null ? "-" : String(t.cpuMedianPercent)}`,
     );
   }
-  for (const [h, list] of Object.entries(s.beats)) if (list.length) lines.push(`${h} does better on ${String(list.length)}: ${list.map((b) => `${b.id} (${b.on} over ${b.over.join(",")})`).join("; ")}`);
-  if (!s.publishable) lines.push(`not publishable${s.missing.length ? `: ${s.missing.map((m) => `${m.host}: ${m.reason}`).join("; ")}` : " (no --publish)"}`);
+  for (const [h, list] of Object.entries(s.beats)) {
+    if (!list.length) continue;
+    const detail = list.map((b) => reasonText({ code: TEXT_CODE.compareBeatDescription, args: { id: b.id, on: b.on, over: b.over.join(",") } }, lang)).join("; ");
+    lines.push(reasonText({ code: TEXT_CODE.compareDoesBetterOn, args: { host: h, count: list.length, detail } }, lang));
+  }
+  if (!s.publishable) {
+    lines.push(
+      s.missing.length
+        ? reasonText({ code: TEXT_CODE.compareNotPublishableWithMissing, args: { missing: s.missing.map((m) => `${m.host}: ${reasonText(m.reason, lang)}`).join("; ") } }, lang)
+        : reasonText({ code: TEXT_CODE.compareNotPublishableNoFlag }, lang),
+    );
+  }
   return `${lines.join("\n")}\n`;
 }

package/src/hostd-pin-files.ts

@@ -12,6 +12,8 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { TEXT_CODE, type ReasonText } from "./text-codes.js";
+
 /** The daemon binary, else `plugin-hostd` on the PATH. */
 export const HOSTD_ENV = "PLUGIN_HOSTD";
 
@@ -41,9 +43,12 @@ export const SPAWNED_PIN_FILES: PinFilesRun = (uri, lv2Dirs, env) => {
 
 export type PinFiles =
   | { readonly ok: true; readonly root: string; readonly files: readonly { readonly path: string; readonly sha256: string }[] }
-  | { readonly ok: false; readonly detail: string };
+  | { readonly ok: false; readonly detail: ReasonText };
 
-/** The files plugin-hostd collects for `uri`, each hashed; why not, when it cannot say. */
+/**
+ * The files plugin-hostd collects for `uri`, each hashed; why not, when it cannot say: one of this package's codes
+ * (`reasonText` renders it), or the daemon's own last line as it wrote it.
+ */
 export function hostdPinFiles(
   uri: string,
   lv2Dirs: readonly string[],
@@ -52,11 +57,11 @@ export function hostdPinFiles(
   read: (path: string) => Buffer = (p) => readFileSync(p),
 ): PinFiles {
   const r = run(uri, lv2Dirs, env);
-  if (r.missing) return { ok: false, detail: "plugin-hostd is not installed: the files of a pin are plugin-hostd's to name" };
+  if (r.missing) return { ok: false, detail: { code: TEXT_CODE.pinHostdNotInstalled } };
   if (r.status !== 0) {
-    const why = r.stdout.startsWith("Usage:")
-      ? "this plugin-hostd has no --pin-files (plugin-hostd 0.15.0 or later names the files of a pin)"
-      : r.stderr.trim().split("\n").pop() || `plugin-hostd --pin-files exited ${String(r.status)}`;
+    const why: ReasonText = r.stdout.startsWith("Usage:")
+      ? { code: TEXT_CODE.pinHostdNoPinFiles }
+      : r.stderr.trim().split("\n").pop() || { code: TEXT_CODE.pinHostdExited, args: { status: String(r.status) } };
     return { ok: false, detail: why };
   }
   let root: string | undefined;
@@ -65,13 +70,13 @@ export function hostdPinFiles(
     if (line.startsWith("root ")) root = line.slice(5);
     else if (line.startsWith("file ")) names.push(line.slice(5));
   }
-  if (root === undefined || names.length === 0) return { ok: false, detail: "plugin-hostd --pin-files printed no root or no file" };
+  if (root === undefined || names.length === 0) return { ok: false, detail: { code: TEXT_CODE.pinHostdNoRootOrFile } };
   try {
     // a name is the word of a pin, percent-encoded when the file's name needs it (Surge XT's libSurge%20XT.so): the pin
     // keeps it as written, the file is the name it decodes to, as the daemon opens it
     const files = names.map((path) => ({ path, sha256: createHash("sha256").update(read(join(root!, decodeURIComponent(path)))).digest("hex") }));
     return { ok: true, root, files: files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) };
   } catch (e) {
-    return { ok: false, detail: `a file plugin-hostd names cannot be read: ${e instanceof Error ? e.message : String(e)}` };
+    return { ok: false, detail: { code: TEXT_CODE.pinFileUnreadable, args: { error: e instanceof Error ? e.message : String(e) } } };
   }
 }

package/src/index.ts

@@ -24,6 +24,7 @@ export * from "./cost-fields.js";
 export * from "./probe-output.js";
 export * from "./probe-judge.js";
 export * from "./qualification-record.js";
+export * from "./record-figures.js";
 export * from "./judgement-line.js";
 export * from "./judged-layer.js";
 export * from "./probe-runner.js";
@@ -42,3 +43,6 @@ export * from "./history-file.js";
 export * from "./history-adjust.js";
 export * from "./adjust-cli.js";
 export * from "./compare.js";
+export * from "./text-codes.js";
+export * from "./text-catalog.js";
+export * from "./refused-stderr-kept.js";

package/src/plugin-db-cli.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * plugin-db is the one writer's call into plugin-db's own store, as plugin-db's records documentation describes it:
+ * `plugin-db pin <address> --files <sha256> [--layout <scheme>:<sha256>]` writes the pinned layer, `plugin-db put
+ * <address> judged --writer plugin-qualify` writes the judged layer plugin-qualify is the one writer of, its body on
+ * stdin. `--system` names the service's store (plugin-db's own default otherwise, for an interactive caller). Nothing
+ * here computes a digest or a body; `plugin-db-pin.ts` and `judged-layer.ts` do.
+ */
+import { spawnSync } from "node:child_process";
+
+import type { JudgedBody } from "./judged-layer.js";
+import type { LayerPin } from "./judged-layer.js";
+
+/** The binary, else `plugin-db` on the PATH. */
+export const PLUGIN_DB_ENV = "PLUGIN_DB";
+
+export interface PluginDbRunResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** plugin-db is not installed. */
+  readonly missing?: boolean;
+}
+
+/** One run of `plugin-db <args...>`, the body on stdin when one is given. */
+export type PluginDbRun = (args: readonly string[], input: string | undefined, env: Readonly<Record<string, string | undefined>>) => PluginDbRunResult;
+
+export const SPAWNED_PLUGIN_DB: PluginDbRun = (args, input, env) => {
+  const r = spawnSync(env[PLUGIN_DB_ENV] ?? "plugin-db", args, { encoding: "utf8", timeout: 30000, env: { ...env }, ...(input === undefined ? {} : { input }) });
+  const missing = (r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", ...(missing ? { missing } : {}) };
+};
+
+export interface PluginDbCallOptions {
+  /** The service's store (`--system`), plugin-db's own default otherwise. */
+  readonly system: boolean;
+}
+
+export type PluginDbCallResult = { readonly ok: true } | { readonly ok: false; readonly detail: string };
+
+function systemFlag(args: readonly string[], opts: PluginDbCallOptions): string[] {
+  return opts.system ? [...args, "--system"] : [...args];
+}
+
+function refusal(r: PluginDbRunResult, verb: string): PluginDbCallResult {
+  if (r.missing) return { ok: false, detail: `plugin-db is not installed: the store is plugin-db's to ${verb}` };
+  const detail = r.stderr.trim().split("\n").pop();
+  return { ok: false, detail: detail || `plugin-db ${verb} exited ${String(r.status)}` };
+}
+
+/** `plugin-db pin <address> --files <sha256> [--layout <scheme>:<sha256>]`: the files of a plugin's bytes, pinned. */
+export function pluginDbPin(
+  address: string,
+  pin: LayerPin,
+  opts: PluginDbCallOptions,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  run: PluginDbRun = SPAWNED_PLUGIN_DB,
+): PluginDbCallResult {
+  const args = systemFlag(["pin", address, "--files", pin.files, ...(pin.layout === null ? [] : ["--layout", pin.layout])], opts);
+  const r = run(args, undefined, env);
+  if (r.status !== 0 || r.missing) return refusal(r, "pin");
+  return { ok: true };
+}
+
+/** `plugin-db put <address> judged --writer plugin-qualify`, the judged layer's body on stdin. */
+export function pluginDbPutJudged(
+  address: string,
+  body: JudgedBody,
+  opts: PluginDbCallOptions,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  run: PluginDbRun = SPAWNED_PLUGIN_DB,
+): PluginDbCallResult {
+  const args = systemFlag(["put", address, "judged", "--writer", "plugin-qualify"], opts);
+  const r = run(args, JSON.stringify(body), env);
+  if (r.status !== 0 || r.missing) return refusal(r, "put");
+  return { ok: true };
+}

package/src/plugin-db-pin.ts

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The pin plugin-db holds for an address: `files`, the combined digest of every file a plugin's bytes are
+ * (`omx-files/1`, plugin-db's `plugin_db_tables.h`: the SHA-256 of the line `omx-files/1`, then one line
+ * `<path>\t<sha256>` per file in byte order of the paths, each ending in one `\n`), and `layout`, the parameter-layout
+ * fingerprint plugin-hostd's prober took (`omx-layout/1:<sha256>`), or none. Computed here from the raw per-file
+ * digests the prober wrote (`IntegrityMeasurement`): nothing here opens a file or hashes bytes plugin-hostd did not
+ * already hash.
+ */
+import { createHash } from "node:crypto";
+
+import type { IntegrityMeasurement, PinnedFile } from "./measurement/format.js";
+import type { LayerPin } from "./judged-layer.js";
+
+/** The scheme name the combined files digest states, plugin-db's `PDB_STORE_FILES_PIN_SCHEME`. */
+export const OMX_FILES_SCHEME = "omx-files/1";
+
+/** The combined `omx-files/1` digest of a pin's files, plugin-db's one way to fold several file hashes into one. */
+export function omxFilesDigest(files: readonly PinnedFile[]): string {
+  const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const text = [`${OMX_FILES_SCHEME}\n`, ...sorted.map((f) => `${f.path}\t${f.sha256}\n`)].join("");
+  return createHash("sha256").update(text).digest("hex");
+}
+
+/** The pin plugin-db holds for an integrity measurement, or `undefined` when it took no whole pin (no files). */
+export function layerPinOf(integrity: Pick<IntegrityMeasurement, "files" | "layout">): LayerPin | undefined {
+  if (integrity.files === undefined || integrity.files.length === 0) return undefined;
+  return {
+    files: omxFilesDigest(integrity.files),
+    layout: integrity.layout === undefined ? null : `${integrity.layout.scheme}:${integrity.layout.sha256}`,
+  };
+}

package/src/qualify-sync.ts

@@ -35,6 +35,7 @@ import { iriPath, lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
 import { judgmentPinEntries, pinClearLine, pinLineUri, pinsFile, type PinEntry } from "./pins-file.js";
 import { POOL_RESULT, completePool, judgePoolRun, pinAfterPool, pinFromRecordWithPool, poolEnv, spawnedPoolRunner, type PoolRunner } from "./qualify-pool.js";
 import { hostdPinFiles, type PinFilesRun } from "./hostd-pin-files.js";
+import { localeOf, reasonText } from "./text-catalog.js";
 import type { Judgment } from "./probe-judge.js";
 import { qualifyTargets, type ProbeRun } from "./probe-runner.js";
 import { GRID_FULL, hostCells, parseGridSpec, type GridCell, type GridSpec } from "./measurement-grid.js";
@@ -670,7 +671,7 @@ function withHostdFiles(ctx: SyncContext, pin: PinEntry | undefined): PinEntry |
   if (pin === undefined || pin.integrity.files === undefined) return pin;
   const r = hostdPinFiles(pin.uri, ctx.settings.lv2Dirs, ctx.env, ...(ctx.pinFilesRun === undefined ? [] : [ctx.pinFilesRun]));
   if (!r.ok) {
-    ctx.log(`${pin.uri}: not pinned: ${r.detail}`);
+    ctx.log(`${pin.uri}: not pinned: ${reasonText(r.detail, localeOf(ctx.env))}`);
     return undefined;
   }
   return { ...pin, integrity: { ...pin.integrity, files: r.files } };
@@ -693,7 +694,7 @@ export function refreshPins(ctx: SyncContext, state: SyncState): { state: SyncSt
       if (pin === undefined || pin.integrity.files === undefined) return plugin;
       const r = hostdPinFiles(pin.uri, ctx.settings.lv2Dirs, ctx.env, ...(ctx.pinFilesRun === undefined ? [] : [ctx.pinFilesRun]));
       if (!r.ok) {
-        ctx.log(`${pin.uri}: pin files not refreshed: ${r.detail}`);
+        ctx.log(`${pin.uri}: pin files not refreshed: ${reasonText(r.detail, localeOf(ctx.env))}`);
         return plugin;
       }
       const old = new Map(pin.integrity.files.map((f) => [f.path, f.sha256]));

package/src/record-figures.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The figures a qualification record holds at one rate and quantum: what plugin-qualify's own
+ * menus and the zynthian-ui fork both need to show, read from `plugin-qualify.qualification-record/1`
+ * (`qualification-record.ts`) rather than re-derived.
+ *
+ * `tools/record_figures.py` is the same reader for a Python console (zynthian-ui): the two are
+ * held equal over the same fixtures (`record-figures-python-conformance.test.ts`), figure for
+ * figure, word for word and code for code.
+ *
+ * This reader takes no side on the plugin: no tier, no state, no verdict. A figure plugin-qualify
+ * did not take is absent here, never a zero and never guessed — that is plugin-db's reader
+ * (plugin-db#4) and the tiers already in the record (`RecordTiers`).
+ */
+import type { QualificationRecord } from "./qualification-record.js";
+
+/** The latency frames this cell holds: what the plugin declared, and what the run measured, when either was taken. */
+export interface RecordLatencyFigures {
+  readonly declaredFrames?: number;
+  readonly measuredFrames?: number;
+}
+
+/** The interposer's RT-safety counts for this cell, as the probe wrote them — never re-summed. */
+export interface RecordRtSafetyFigures {
+  /** The interposer was loaded; a count below is zero from a real run, not from no interposer. */
+  readonly interposer?: boolean;
+  readonly swept?: boolean;
+  readonly sweepApplicable?: boolean;
+  readonly allocations?: number;
+  readonly locks?: number;
+  readonly syscalls?: number;
+  readonly threadViolations?: number;
+  readonly processErrors?: number;
+  /** How many events the interposer logged (`malloc ? ?`, ...); the words themselves are for a log, not this reader. */
+  readonly events?: number;
+}
+
+/** The figures of one qualification record at one rate and quantum. */
+export interface RecordFigures {
+  readonly latency?: RecordLatencyFigures;
+  /** The median cost of this cell, in nanoseconds per sample (`ProbeCost.median`'s own unit). */
+  readonly costNsPerSampleMedian?: number;
+  readonly rtSafety?: RecordRtSafetyFigures;
+  /** Whether the continuous soak ran at this rate; `false` when the record never names a soak reading here. */
+  readonly soakRan: boolean;
+  /** This cell's own outcome code, carried verbatim, exactly when it is a crash. */
+  readonly crashCode?: string;
+  /** This cell's own outcome code, carried verbatim, exactly when it is a supervisor timeout. */
+  readonly timeoutCode?: string;
+}
+
+const PROBE_CRASHED = "probe.crashed";
+const PROBE_TIMEOUT = "probe.timeout";
+
+function rtSafetyFiguresOf(rtSafety: QualificationRecord["measurements"]["grid"][number]["rtSafety"]): RecordRtSafetyFigures | undefined {
+  if (rtSafety === undefined) return undefined;
+  return {
+    ...(rtSafety.interposer === undefined ? {} : { interposer: rtSafety.interposer }),
+    ...(rtSafety.swept === undefined ? {} : { swept: rtSafety.swept }),
+    ...(rtSafety.sweepApplicable === undefined ? {} : { sweepApplicable: rtSafety.sweepApplicable }),
+    ...(rtSafety.allocations === undefined ? {} : { allocations: rtSafety.allocations }),
+    ...(rtSafety.locks === undefined ? {} : { locks: rtSafety.locks }),
+    ...(rtSafety.syscalls === undefined ? {} : { syscalls: rtSafety.syscalls }),
+    ...(rtSafety.threadViolations === undefined ? {} : { threadViolations: rtSafety.threadViolations }),
+    ...(rtSafety.processErrors === undefined ? {} : { processErrors: rtSafety.processErrors }),
+    ...(rtSafety.events === undefined ? {} : { events: rtSafety.events.length }),
+  };
+}
+
+function latencyFiguresOf(latency: QualificationRecord["measurements"]["grid"][number]["latency"]): RecordLatencyFigures | undefined {
+  const declaredFrames = (latency as { declaredFrames?: number } | undefined)?.declaredFrames;
+  const measuredFrames = (latency as { measuredFrames?: number } | undefined)?.measuredFrames;
+  if (declaredFrames === undefined && measuredFrames === undefined) return undefined;
+  return {
+    ...(declaredFrames === undefined ? {} : { declaredFrames }),
+    ...(measuredFrames === undefined ? {} : { measuredFrames }),
+  };
+}
+
+/** Whether the record names a continuous soak reading at this rate (`measurements.behaviour.soak.perRate`). */
+function soakRanAt(record: QualificationRecord, rate: number): boolean {
+  const soak = record.measurements.behaviour?.soak as { readonly perRate?: Readonly<Record<string, unknown>> } | undefined;
+  return soak?.perRate?.[String(rate)] !== undefined;
+}
+
+/**
+ * The figures `plugin-qualify.qualification-record/1` holds at one rate and quantum: the cell the
+ * record's grid names at that pair, else every per-cell figure is absent and `soakRan` alone still
+ * answers for the rate.
+ */
+export function recordFigures(record: QualificationRecord, rate: number, quantum: number): RecordFigures {
+  const point = record.measurements.grid.find((p) => p.rate === rate && p.quantum === quantum);
+  return {
+    ...(point === undefined ? {} : { ...wrapLatency(point.latency), ...wrapCost(point.cost), ...wrapRtSafety(point.rtSafety) }),
+    soakRan: soakRanAt(record, rate),
+    ...(point?.outcome === PROBE_CRASHED ? { crashCode: point.outcome } : {}),
+    ...(point?.outcome === PROBE_TIMEOUT ? { timeoutCode: point.outcome } : {}),
+  };
+}
+
+function wrapLatency(latency: QualificationRecord["measurements"]["grid"][number]["latency"]): Pick<RecordFigures, "latency"> | Record<string, never> {
+  const l = latencyFiguresOf(latency);
+  return l === undefined ? {} : { latency: l };
+}
+
+function wrapCost(cost: QualificationRecord["measurements"]["grid"][number]["cost"]): Pick<RecordFigures, "costNsPerSampleMedian"> | Record<string, never> {
+  return cost === undefined ? {} : { costNsPerSampleMedian: cost.median };
+}
+
+function wrapRtSafety(rtSafety: QualificationRecord["measurements"]["grid"][number]["rtSafety"]): Pick<RecordFigures, "rtSafety"> | Record<string, never> {
+  const rt = rtSafetyFiguresOf(rtSafety);
+  return rt === undefined ? {} : { rtSafety: rt };
+}