@openmixer/plugin-qualify 0.20.1 → 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/host-admission.ts

@@ -11,6 +11,7 @@
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { withRunHome } from "./run-home.js";
 import type { HostProfile } from "./host-profiles.js";
 import { ADMIT_STEP_MS_ENV } from "./qualify-declarations.js";
 
@@ -83,7 +84,17 @@ export interface ModHostRun {
    * not be read. Absent for a plugin that is no instrument, and for any plugin under mod-host.
    */
   /** `notes`: how many keys were played; a run from when one key was played has none. */
-  readonly sound?: { readonly peak?: number; readonly notes?: number; readonly problem?: string };
+  readonly sound?: { readonly peak?: number; readonly notes?: number; readonly problem?: string; readonly content?: AdapterContent };
+}
+
+/**
+ * The content an instrument declares it plays from (its `patch:writable` parameters of range `atom:Path`, `lv2ContentParams`)
+ * and what came of giving each a short sample before the notes: `loaded` the host took, `refused` it did not (with its answer).
+ */
+export interface AdapterContent {
+  readonly params: readonly string[];
+  readonly loaded: readonly string[];
+  readonly refused?: readonly string[];
 }
 
 /** At or under this magnitude (-120 dBFS) a held note is taken as digital silence: clap-qualify's own SILENCE. */
@@ -97,6 +108,22 @@ export const SILENT_PEAK = 1e-6;
 export const ADAPTER_SILENT_CODE = `${ADAPTER_HOST}.silent-under-note`;
 export const ADAPTER_LEVEL_UNMEASURED_CODE = `${ADAPTER_HOST}.level-unmeasured`;
 const UNPROVEN_SOUND: readonly string[] = [ADAPTER_SILENT_CODE, ADAPTER_LEVEL_UNMEASURED_CODE];
+/**
+ * An instrument that declares content it plays from and stayed silent under the notes even so: the content could not be
+ * given (the host refused the sample) or the sample did not reach the keys played. Its silence says nothing of the plugin,
+ * so the note test is not observable for it: the run admits it, and the record names this code and the content (#318).
+ * No other host is asked instead.
+ */
+export const ADAPTER_CONTENT_UNOBSERVED_CODE = `${ADAPTER_HOST}.silent-needs-content`;
+
+/** The run's content, as a reason's params carry it: the declared parameters, the ones loaded, the ones refused. */
+function contentParams(content: AdapterContent): Record<string, string> {
+  return {
+    content: content.params.join(" "),
+    loaded: content.loaded.join(" "),
+    ...(content.refused === undefined || content.refused.length === 0 ? {} : { refused: content.refused.join("; ") }),
+  };
+}
 
 /** The rating a run that did not admit the plugin gives its host's verdict. */
 export function admissionRating(admission: HostAdmission): "unsuitable" | "unknown" {
@@ -109,6 +136,19 @@ export function admissionRating(admission: HostAdmission): "unsuitable" | "unkno
  */
 const JACK_CLIENT_RESPS: readonly number[] = [-201, -202];
 
+/** The name of the reason a run stops on when no JACK server answers: the admission cannot say anything of any plugin. */
+export const NO_JACK_SERVER = "no JACK server";
+
+/**
+ * The refusal to go on when an admission found no JACK client to have (`<host>.no-jack-client`): the server the host is
+ * pointed at (the default one, or `JACK_DEFAULT_SERVER`) is not there, and every plugin would be recorded with the same
+ * resp -201 as if it were the plugin's. `undefined` for any other run.
+ */
+export function noJackServerProblem(admission: HostAdmission | undefined): string | undefined {
+  if (admission === undefined || admission.measured || !admission.code?.endsWith(".no-jack-client")) return undefined;
+  return `${NO_JACK_SERVER}: ${admission.host} could not open a JACK client (resp ${String(admission.params["resp"] ?? "-201")}), so nothing is learned of any plugin; start the JACK server it is pointed at (JACK_DEFAULT_SERVER names it) and run again`;
+}
+
 /** The verdict of a run of a host that speaks mod-host's protocol: the first step that did not answer `resp 0` decides. */
 export function classifyProtocolRun(host: ProtocolHost, run: ModHostRun): HostAdmission {
   if (!run.installed) return notInstalled(host);
@@ -128,7 +168,14 @@ export function classifyProtocolRun(host: ProtocolHost, run: ModHostRun): HostAd
   if (run.sound !== undefined) {
     const { peak, problem } = run.sound;
     if (peak === undefined) return { host, measured: true, admitted: false, code: ADAPTER_LEVEL_UNMEASURED_CODE, params: { problem: problem ?? "no figure" } };
-    if (!(peak > SILENT_PEAK)) return { host, measured: true, admitted: false, code: ADAPTER_SILENT_CODE, params: { peak, ...(run.sound.notes === undefined ? {} : { notes: run.sound.notes }) } };
+    const notes: Record<string, number> = run.sound.notes === undefined ? {} : { notes: run.sound.notes };
+    const content = run.sound.content;
+    if (!(peak > SILENT_PEAK)) {
+      if (content !== undefined && content.params.length > 0) return { host, measured: true, admitted: true, code: ADAPTER_CONTENT_UNOBSERVED_CODE, params: { peak, ...notes, ...contentParams(content) } };
+      return { host, measured: true, admitted: false, code: ADAPTER_SILENT_CODE, params: { peak, ...notes } };
+    }
+    // it sounded on the content it was given: the record says which
+    if (content !== undefined && content.loaded.length > 0) return { ...admitted(host), params: { peak, ...notes, ...contentParams(content) } };
   }
   return admitted(host);
 }
@@ -186,14 +233,14 @@ export const SPAWNED_ADMISSIONS: AdmissionRuns = {
     // two commands at the limit the pass gives each, and the tool's own start and end: it kills the host itself first
     const stepMs = Number(env?.[ADMIT_STEP_MS_ENV] ?? 0);
     const timeout = stepMs > 0 ? 2 * stepMs + 15000 : MOD_HOST_ADMISSION_MS;
-    const r = spawnSync(process.execPath, [MOD_HOST_ADMIT, uri, ADAPTER_HOST], { encoding: "utf8", timeout, killSignal: "SIGKILL", ...(env === undefined ? {} : { env: { ...env } }) });
+    const r = spawnSync(process.execPath, [MOD_HOST_ADMIT, uri, ADAPTER_HOST], { encoding: "utf8", timeout, killSignal: "SIGKILL", env: withRunHome(env ?? process.env) });
     if (r.error !== undefined || r.status !== 0) {
       throw new Error(`${ADAPTER_HOST} admission of ${uri} gave no answer (${r.error?.message ?? `exit ${String(r.status)}`}): ${(r.stderr ?? "").trim()}`);
     }
     return JSON.parse(r.stdout) as ModHostRun;
   },
   modHost(uri, env) {
-    const r = spawnSync(process.execPath, [MOD_HOST_ADMIT, uri], { encoding: "utf8", timeout: MOD_HOST_ADMISSION_MS, ...(env === undefined ? {} : { env: { ...env } }) });
+    const r = spawnSync(process.execPath, [MOD_HOST_ADMIT, uri], { encoding: "utf8", timeout: MOD_HOST_ADMISSION_MS, env: withRunHome(env ?? process.env) });
     if (r.error !== undefined || r.status !== 0) {
       throw new Error(`mod-host admission of ${uri} gave no answer (${r.error?.message ?? `exit ${String(r.status)}`}): ${(r.stderr ?? "").trim()}`);
     }
@@ -203,7 +250,7 @@ export const SPAWNED_ADMISSIONS: AdmissionRuns = {
     // SIGKILL at the deadline: jalv hosting some plugins ignores SIGTERM, and one stuck in jack_client_open never reaches
     // the loop that reads the flag TERM sets, so a TERM left spawnSync waiting with it (#187). Alive at the deadline is
     // all the verdict asks, so nothing is lost by not letting it exit cleanly.
-    const r = spawnSync("jalv", ["-n", "plugin-qualify", uri], { encoding: "utf8", timeout: JALV_HOSTED_MS, killSignal: "SIGKILL", input: "", ...(env === undefined ? {} : { env: { ...env } }) });
+    const r = spawnSync("jalv", ["-n", "plugin-qualify", uri], { encoding: "utf8", timeout: JALV_HOSTED_MS, killSignal: "SIGKILL", input: "", env: withRunHome(env ?? process.env) });
     const code = (r.error as NodeJS.ErrnoException | undefined)?.code;
     if (code === "ENOENT") return { installed: false, stillRunning: false, status: null, signal: null, stderr: "" };
     return { installed: true, stillRunning: code === "ETIMEDOUT", status: r.status, signal: code === "ETIMEDOUT" ? null : r.signal, stderr: r.stderr ?? "" };

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/hostd-search-path.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The directories the sync scans, as plugin-hostd searches them (plugin-qualify#9). One definition of the search path:
+ * the daemon's, which `plugin-hostd --search-path [-c <file>]` prints from the code it searches with (plugin-hostd 0.20.3
+ * and later). This module never works the lists out itself: it runs the daemon on its settings file and reads the
+ * `lv2` and `clap` lines, and where each list came from (`file`, `env` or `default`).
+ */
+import { spawnSync } from "node:child_process";
+import { HOSTD_ENV } from "./hostd-pin-files.js";
+
+/** Where plugin-hostd took a list from: its settings file, its environment (`LV2_PATH`, `CLAP_PATH`) or its default. */
+export type SearchPathSource = "file" | "env" | "default";
+
+export interface HostdSearchPath {
+  /** The LV2 directories, in the order the daemon searches them: `lv2_path` then `lv2_extra`. */
+  readonly lv2: readonly string[];
+  /** The CLAP directories, in the order the daemon searches them. */
+  readonly clap: readonly string[];
+  /** Where each of `lv2_path`, `lv2_extra` and `clap_path` came from. */
+  readonly sources: Readonly<Record<"lv2_path" | "lv2_extra" | "clap_path", SearchPathSource>>;
+}
+
+export interface SearchPathRunResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** The daemon is not installed. */
+  readonly missing?: boolean;
+}
+
+/** One run of `plugin-hostd --search-path`, with `-c <conf>` when a settings file is named. */
+export type SearchPathRun = (conf: string | undefined, env: Readonly<Record<string, string | undefined>>) => SearchPathRunResult;
+
+export const SPAWNED_SEARCH_PATH: SearchPathRun = (conf, env) => {
+  const r = spawnSync(env[HOSTD_ENV] ?? "plugin-hostd", [...(conf === undefined ? [] : ["-c", conf]), "--search-path"], { encoding: "utf8", timeout: 30000, env: { ...env } });
+  const missing = (r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", ...(missing ? { missing } : {}) };
+};
+
+const SOURCES: readonly string[] = ["file", "env", "default"];
+const dirList = (text: string): string[] => text.split(":").filter((d) => d !== "");
+
+/** The lines `plugin-hostd --search-path` prints, read: `<key> TAB <source> TAB <value>`; why not, when one is missing. */
+export function parseSearchPath(stdout: string): { ok: true; path: HostdSearchPath } | { ok: false; error: string } {
+  const rows = new Map<string, { source: string; value: string }>();
+  for (const line of stdout.split("\n")) {
+    const f = line.split("\t");
+    if (f.length >= 2 && f[0] !== undefined && f[1] !== undefined) rows.set(f[0], { source: f[1], value: f.slice(2).join("\t") });
+  }
+  for (const key of ["lv2_path", "lv2_extra", "clap_path"]) {
+    const r = rows.get(key);
+    if (r === undefined || !SOURCES.includes(r.source)) return { ok: false, error: `plugin-hostd --search-path printed no ${key} with its source` };
+  }
+  const lv2 = rows.get("lv2");
+  const clap = rows.get("clap");
+  if (lv2?.source !== "effective" || clap?.source !== "effective") return { ok: false, error: "plugin-hostd --search-path printed no effective lv2 and clap lists" };
+  const src = (key: string) => rows.get(key)!.source as SearchPathSource;
+  return { ok: true, path: { lv2: dirList(lv2.value), clap: dirList(clap.value), sources: { lv2_path: src("lv2_path"), lv2_extra: src("lv2_extra"), clap_path: src("clap_path") } } };
+}
+
+/** The directories plugin-hostd searches with the settings file `conf` (its own default when undefined); why not, when it cannot say. */
+export function hostdSearchPath(
+  conf: string | undefined,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+  run: SearchPathRun = SPAWNED_SEARCH_PATH,
+): { ok: true; path: HostdSearchPath } | { ok: false; error: string } {
+  const r = run(conf, env);
+  if (r.missing) return { ok: false, error: "plugin-hostd is not installed: the directories scanned are the ones plugin-hostd searches" };
+  if (r.status !== 0) {
+    const why = /unrecognized option|^Usage:/m.test(r.stdout + r.stderr)
+      ? "this plugin-hostd has no --search-path (plugin-hostd 0.20.3 or later names the directories it searches)"
+      : r.stderr.trim().split("\n").pop() || `plugin-hostd --search-path exited ${String(r.status)}`;
+    return { ok: false, error: why };
+  }
+  return parseSearchPath(r.stdout);
+}
+
+/** What the run says when a list is not the settings file's: the running daemon, started with another environment, may search other directories. */
+export function searchPathWarnings(path: HostdSearchPath, conf: string | undefined): string[] {
+  const where = conf ?? "plugin-hostd's own settings file";
+  return (["lv2_path", "clap_path"] as const)
+    .filter((k) => path.sources[k] !== "file")
+    .map((k) => `${k} is plugin-hostd's ${path.sources[k] === "env" ? `environment (${k === "lv2_path" ? "LV2_PATH" : "CLAP_PATH"})` : "default"}, not ${where}: the running daemon may search other directories; write ${k} in ${where}`);
+}

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/jack-registry.ts

@@ -3,7 +3,7 @@
 /**
  * JACK's table of its servers, /dev/shm/jack-shm-registry: a header, then eight rows of a pid and a name
  * (`jack-<uid>:<server>:`). A server that is killed never clears its row, and once the eight are taken no server starts.
- * The adapter pass starts and stops servers of its own, `omx-qualify-<pid>-<quantum>`; a row of one of those whose
+ * The adapter pass starts and stops servers of its own, `omx-qualify-<pid>-<rate>-<quantum>`; a row of one of those whose
  * process is gone is freed (pid 0, name empty) before the next start, as jackd frees its own row when it ends well.
  * Rows of any other server are never touched, and a file of another layout is left as it is.
  */