@openmixer/plugin-qualify 0.20.0 → 0.20.3

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@openmixer/plugin-qualify",
-  "version": "0.20.0",
+  "version": "0.20.3",
   "description": "Qualify audio plugins for real-time hosting: scan, offline latency and cost measurement, and a fail-closed rating.",
   "type": "module",
   "license": "GPL-3.0-or-later",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/FreeMixer/plugin-qualify.git"
+    "url": "git+https://github.com/Open-Mixer/plugin-qualify.git"
   },
   "author": "Pau Aliagas <linuxnow@gmail.com>",
-  "homepage": "https://github.com/FreeMixer/plugin-qualify#readme",
+  "homepage": "https://github.com/Open-Mixer/plugin-qualify#readme",
   "bugs": {
-    "url": "https://github.com/FreeMixer/plugin-qualify/issues"
+    "url": "https://github.com/Open-Mixer/plugin-qualify/issues"
   },
   "engines": {
     "node": ">=18"
@@ -75,6 +75,8 @@
     "!**/__pycache__",
     "!**/*.pyc",
     "fixtures",
+    "schema/codes.json",
+    "catalogs",
     "README.md",
     "LICENSE"
   ],
@@ -98,6 +100,6 @@
     "provenance": true
   },
   "dependencies": {
-    "@openmixer/omx-contract": "^3.9.1"
+    "@openmixer/omx-contract": "^3.12.0"
   }
 }

package/schema/codes.json

@@ -0,0 +1,15 @@
+{
+  "kind": "codes",
+  "doc": "The codes plugin-qualify's scan refuses a plugin by, each with its source sentence in English and the args it names (omx-contract's codes shape; translations are not here). Each language's sentences are in catalogs/<lang>.json, keyed by the code. tools/descriptors.py renders the English sentence from this file; no module repeats it. A code is never reworded.",
+  "codes": {
+    "descriptorDuplicateSymbol": {
+      "code": "qualify.descriptor.duplicate-symbol",
+      "text": {
+        "en": "Two ports of this plugin share the symbol {symbol}, so neither can be addressed by it; the plugin is not described."
+      },
+      "args": [
+        "symbol"
+      ]
+    }
+  }
+}

package/src/clap-loader.ts

@@ -17,6 +17,7 @@ import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import type { PluginLoader, PluginTarget } from "./loader.js";
 import { lv2BundlesOnPath, lv2Loader } from "./lv2-loader.js";
 import {
@@ -345,7 +346,7 @@ export interface ClapScanRunResult {
 export type ClapScanRun = (tool: string, args: readonly string[], timeoutMs: number) => ClapScanRunResult;
 
 const spawnScan: ClapScanRun = (tool, args, timeoutMs) => {
-  const r = spawnSync(tool, [...args], { encoding: "utf8", timeout: timeoutMs, maxBuffer: MAX_SCAN_BYTES });
+  const r = spawnSync(tool, [...args], { encoding: "utf8", timeout: timeoutMs, maxBuffer: MAX_SCAN_BYTES, env: withRunHome(process.env) });
   return { status: r.status, stdout: r.stdout ?? "", ...(r.error === undefined ? {} : { error: r.error }) };
 };
 

package/src/clap-qualify.ts

@@ -79,6 +79,18 @@ export interface ClapCostFigure {
   readonly voices?: VoicesHeld;
   /** What these blocks were timed under. */
   readonly scheduling?: TimingScheduling;
+  /**
+   * For an instrument: its cost at each count of notes held with every parameter at its default (`--curve`), the
+   * rate's voiceCurve that plugin-hostd's runner carries into probe output 1.4; an entry it could not time has a reason.
+   */
+  readonly voiceCurve?: readonly ClapVoiceCurveEntry[];
+}
+
+export interface ClapVoiceCurveEntry {
+  readonly held: number;
+  readonly nsPerSampleMedian?: number;
+  readonly nsPerSampleP95?: number;
+  readonly unmeasuredReason?: string;
 }
 
 /** One rate the cost arm did not time, and why; an instrument's declared capacity is kept when it has one. */
@@ -281,9 +293,22 @@ function readCostAtRate(v: unknown, where: string, notes: boolean): ClapCostAtRa
       ? {}
       : { voices: { held: voices.held, basis: voices.basis, ...(voices.capacity === undefined ? {} : { capacity: voices.capacity }) } }),
     ...(scheduling === undefined ? {} : { scheduling }),
+    ...(v["voiceCurve"] === undefined ? {} : { voiceCurve: readVoiceCurve(v["voiceCurve"], `${where} voiceCurve`) }),
   };
 }
 
+function readVoiceCurve(v: unknown, where: string): ClapVoiceCurveEntry[] {
+  if (!Array.isArray(v)) return bad(`${where} is not a list`);
+  return v.map((e: unknown, i: number) => {
+    const at = `${where} entry ${i}`;
+    if (!isRecord(e)) return bad(`${at} is not an object`);
+    const held = count(e, "held", at);
+    if (held === 0) return bad(`${at} holds no note`);
+    if (e["unmeasuredReason"] !== undefined) return { held, unmeasuredReason: str(e, "unmeasuredReason", at) };
+    return { held, nsPerSampleMedian: figure(e, "nsPerSampleMedian", at), nsPerSampleP95: figure(e, "nsPerSampleP95", at) };
+  });
+}
+
 function readCost(v: unknown): ClapCostReading {
   if (!isRecord(v)) return bad("cost is not an object");
   const stimulus = str(v, "stimulus", "cost");

package/src/distributed-records.ts

@@ -12,8 +12,10 @@
  * treats the plugin as one it measured.
  */
 import { readFileSync, readdirSync } from "node:fs";
+import { machine } from "node:os";
 import { join, resolve } from "node:path";
 
+import { cellKey, type GridCell } from "./measurement-grid.js";
 import { clapPinUri, pinVerdictOf, type PinEntry } from "./pins-file.js";
 import { integrityOfProbeOutput } from "./probe-judge.js";
 import { readProbeOutput, sha256Hex } from "./probe-output.js";
@@ -60,6 +62,20 @@ export function hostClassOfBoard(model: string | undefined): string | undefined
   return m === null ? undefined : `rpi${m[1]!}`;
 }
 
+/** The architecture `uname -m` names, or `undefined` when it cannot be read. */
+export function readMachine(): string | undefined {
+  try {
+    return machine();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The host class of a machine with no board name, by `uname -m`: `x86-64` for an x86_64 one; none for an architecture without a class. */
+export function hostClassOfMachine(arch: string | undefined): string | undefined {
+  return arch?.trim() === "x86_64" ? "x86-64" : undefined;
+}
+
 /** One distributed record, read: where it is, what it says, and the set it came with. */
 export interface DistributedRecord {
   readonly path: string;
@@ -156,26 +172,38 @@ export function outcomeOfVerdict(v: Pick<RecordVerdict, "measured" | "rating" |
   return v.rating === "unsuitable" ? "refused" : "unmeasured";
 }
 
+/** The cells a record's grid holds, by rate then quantum: where the set it came in was measured. */
+export function recordCells(record: Pick<QualificationRecord, "measurements">): GridCell[] {
+  const seen = new Map<string, GridCell>();
+  for (const p of record.measurements?.grid ?? []) seen.set(cellKey(p), { rate: p.rate, quantum: p.quantum });
+  return [...seen.values()].sort((a, b) => a.rate - b.rate || a.quantum - b.quantum);
+}
+
 /** What the layer makes of one item. */
 export type DistributedMatch =
   /** No distributed record names the plugin: it is measured, and nothing is said. */
   | { readonly status: "none" }
   /** Every reason a record found was not taken, one line each; the plugin is measured. */
   | { readonly status: "ignored"; readonly lines: readonly string[] }
-  | { readonly status: "applies"; readonly set: string; readonly records: readonly DistributedRecord[]; readonly files: readonly string[] };
+  /** A set applies; `lines` names every set tried before it and why it was passed over. */
+  | { readonly status: "applies"; readonly set: string; readonly records: readonly DistributedRecord[]; readonly files: readonly string[]; readonly lines: readonly string[] };
 
 /**
  * Whether the item is taken from the layer. The records that find it are tried one set at a time, in the order the
  * layer read them. Of a set, only the records whose every file is installed with the SHA-256 it recorded (computed
  * here by `digest`) count: a record of other bytes is another build of the plugin and is passed over. The set applies
  * when at least one record of these bytes holds a verdict for `host`, and none of those verdicts is one the source
- * could not measure; a set with no record of these bytes is a binary that differs.
+ * could not measure; a set with no record of these bytes is a binary that differs. A set is per machine class, rate
+ * and quantum: of these records, only the ones whose grid holds every cell in `cells` (the cells the sync runs at)
+ * count, so a set measured at another cell is passed over, naming the cells it was measured at, and never answers a
+ * sync at this one by the order its name sorts in (#317). No cells given asks nothing of the grid.
  */
 export function matchDistributed(
   layer: DistributedLayer,
   item: SyncItem,
   host: string,
   digest: (files: readonly string[]) => readonly FileDigest[] | undefined,
+  cells: readonly GridCell[] = [],
 ): DistributedMatch {
   const found = item.format === "clap" ? layer.clap.get(resolve(join(item.root, item.files[0]!))) : layer.lv2.get(item.uri ?? "");
   if (found === undefined || found.length === 0) return { status: "none" };
@@ -195,7 +223,16 @@ export function matchDistributed(
       say(`distributed: ${distributedUri(item, found.find((r) => r.set === set)!)}: binary differs`);
       continue;
     }
-    const judged = records.filter((r) => r.record.verdicts.some((v) => v.host === host));
+    const atCell = records.filter((r) => {
+      const held = new Set(recordCells(r.record).map(cellKey));
+      return cells.every((c) => held.has(cellKey(c)));
+    });
+    if (atCell.length === 0) {
+      const measuredAt = [...new Set(records.flatMap((r) => recordCells(r.record).map(cellKey)))];
+      say(`distributed: ${distributedUri(item, records[0]!)}: set ${set} measured at ${measuredAt.length === 0 ? "no cell" : measuredAt.join(", ")}`);
+      continue;
+    }
+    const judged = atCell.filter((r) => r.record.verdicts.some((v) => v.host === host));
     if (judged.length === 0) {
       say(`distributed: ${distributedUri(item, records[0]!)}: no verdict for ${host} in ${set}`);
       continue;
@@ -205,7 +242,7 @@ export function matchDistributed(
       say(`distributed: ${distributedUri(item, unmeasured)}: unmeasured in ${set}, measured here`);
       continue;
     }
-    return { status: "applies", set, records, files: [...new Set(records.flatMap((r) => r.record.binary.files.map((f) => f.path)))] };
+    return { status: "applies", set, records: atCell, files: [...new Set(atCell.flatMap((r) => r.record.binary.files.map((f) => f.path)))], lines };
   }
   return { status: "ignored", lines };
 }

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-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,8 @@ export * from "./cost-fields.js";
 export * from "./probe-output.js";
 export * from "./probe-judge.js";
 export * from "./qualification-record.js";
+export * from "./judgement-line.js";
+export * from "./judged-layer.js";
 export * from "./probe-runner.js";
 export * from "./measurement-grid.js";
 export * from "./memory-bound.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.
  */

package/src/judged-layer.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The judged layer of a plugin-db entry, from a qualification record: plugin-qualify is that layer's one writer
+ * (plugin-db's records design note, FreeMixer/plugin-db#10). The reader never parses a record; it reads the layer this writes, so every field
+ * the state function reads is set here, from the record and from what plugin-qualify declares once:
+ *
+ * - the latency line (`LATENCY_LINE_MS`), written beside each cell's figure (`latencyMs`), so a surface shows the
+ *   figure within or over the line and keeps no tier word (openmixer plugin-system design 7.15);
+ * - the rules the record was judged by (`judgementRules`), the minor of the plugin-qualify that judged it: a rule
+ *   changes only in a minor, so a patch release leaves every record current;
+ * - the hosting epoch of the host the verdict is for (`HOSTING_EPOCH`).
+ *
+ * One layer is one verdict under one host: the host plugin-hostd runs a plugin with. Its verdict is the one the pins
+ * file gives the same bytes (`pinVerdictOf` of the isolated tier's host, omx-clap-host, which is plugin-hostd's
+ * worker). A record whose verdict for that host was not measured has no judged layer: the reader then answers
+ * unqualified, with its reason.
+ */
+import { judgementRules, latencyMsOf, LATENCY_LINE_MS } from "./judgement-line.js";
+import { pinVerdictOf, type PinVerdict } from "./pins-file.js";
+import { QUALIFICATION_RECORD_SCHEMA, ISOLATED_TIER_HOST, type QualificationRecord } from "./qualification-record.js";
+import type { SuitabilityRating } from "./rating.js";
+
+/** The host a judged layer is written for: the one that runs plugins, in workers of its own (PLUGIN_DB_ISOLATION_HOSTS). */
+export const JUDGED_HOST = "plugin-hostd";
+
+/**
+ * The hosting epoch of each host a layer is written for. The epoch is the host owner's to move, when a release of it
+ * changes how it hosts; plugin-hostd has declared no hosting change since records were written, so its epoch is 0.
+ */
+export const HOSTING_EPOCH = { [JUDGED_HOST]: 0 } as const satisfies Readonly<Record<string, number>>;
+
+/** The plugin-db envelope version this writes (plugin-db data/store.schema.json). */
+export const PLUGIN_DB_ENVELOPE = 1;
+
+/** The pin a layer is written for, as plugin-db's pinned layer holds it. */
+export interface LayerPin {
+  /** The `omx-files/1` SHA-256 of the plugin's files. */
+  readonly files: string;
+  /** `<scheme>:<sha256>` of the parameter layout, or null when the pin holds none. */
+  readonly layout: string | null;
+}
+
+export interface JudgedCell {
+  readonly rate: number;
+  readonly quantum: number;
+  readonly latencyMs?: number;
+}
+
+export interface JudgedBody {
+  readonly verdict: PinVerdict;
+  readonly machineClass: string;
+  readonly host: { readonly name: string; readonly version: string; readonly hostingEpoch: number };
+  readonly rules: string;
+  readonly recordSchema: string;
+  readonly cells: readonly JudgedCell[];
+  readonly conditions: Readonly<Record<string, string>>;
+  readonly latencyLineMs: number;
+}
+
+export interface JudgedLayer {
+  readonly envelope: typeof PLUGIN_DB_ENVELOPE;
+  readonly layer: "judged";
+  readonly address: string;
+  readonly pin: LayerPin;
+  readonly writer: "plugin-qualify";
+  readonly body: JudgedBody;
+}
+
+/** What the converter is given beside the record: the class word, the pin, and the rules when the record states none. */
+export interface JudgedLayerInput {
+  /** The machine class word the record was measured on (`rpi5`, `x86-64`): the set's host class. */
+  readonly machineClass: string;
+  readonly pin: LayerPin;
+  /** plugin-db's address; by default `<format>:<id>`. */
+  readonly address?: string;
+  /** The rules of a record that states none: the plugin-qualify version that judged its set (the set's provenance). */
+  readonly judgedBy?: string;
+}
+
+/** Why a record has no judged layer, when it has none. */
+export type NoLayer = { readonly layer: null; readonly reason: string };
+
+/** The version of a tool named `<name> <version>` in the record's `tool`. */
+function versionOf(record: QualificationRecord, name: string): string | undefined {
+  for (const v of Object.values(record.tool)) {
+    const m = new RegExp(`^${name.replace(/[-.]/g, "\\$&")} (\\S+)$`).exec(v);
+    if (m) return m[1];
+  }
+  return undefined;
+}
+
+/** The cells of the record: each measured rate and quantum, with its latency in milliseconds when one was measured. */
+export function judgedCells(record: QualificationRecord): JudgedCell[] {
+  return record.measurements.grid
+    .filter((p) => p.outcome === "probe.ok")
+    .map((p) => {
+      const frames = (p.latency as { measuredFrames?: number }).measuredFrames;
+      return { rate: p.rate, quantum: p.quantum, ...(frames === undefined ? {} : { latencyMs: latencyMsOf(frames, p.rate) }) };
+    });
+}
+
+/**
+ * The judged layer of a record, or why there is none. The verdict is the isolated tier host's, as the pins file gives
+ * it; the host is plugin-hostd at the probe runner's version, which is plugin-hostd's.
+ */
+export function judgedLayerOf(record: QualificationRecord, input: JudgedLayerInput): JudgedLayer | NoLayer {
+  if (record.schema !== QUALIFICATION_RECORD_SCHEMA) return { layer: null, reason: `record schema ${JSON.stringify(record.schema)} is not ${QUALIFICATION_RECORD_SCHEMA}` };
+  const tierHost = ISOLATED_TIER_HOST[record.plugin.format];
+  const v = record.verdicts.find((r) => r.host === tierHost);
+  if (v === undefined) return { layer: null, reason: `no verdict under ${tierHost ?? `a host for ${record.plugin.format}`}` };
+  const verdict = v.measured ? pinVerdictOf(v.rating as SuitabilityRating) : undefined;
+  if (verdict === undefined) return { layer: null, reason: `${tierHost}: not measured (${v.deciding ?? v.rating})` };
+  const hostVersion = versionOf(record, "plugin-hostd-probe");
+  if (hostVersion === undefined) return { layer: null, reason: "the record names no plugin-hostd-probe version" };
+  const rules = record.rules ?? (input.judgedBy === undefined ? undefined : judgementRules(input.judgedBy));
+  if (rules === undefined) return { layer: null, reason: "the record states no rules, and no judgedBy was given" };
+  return {
+    envelope: PLUGIN_DB_ENVELOPE,
+    layer: "judged",
+    address: input.address ?? `${record.plugin.format}:${record.plugin.id}`,
+    pin: input.pin,
+    writer: "plugin-qualify",
+    body: {
+      verdict,
+      machineClass: input.machineClass,
+      host: { name: JUDGED_HOST, version: hostVersion, hostingEpoch: HOSTING_EPOCH[JUDGED_HOST] },
+      rules,
+      recordSchema: record.schema,
+      cells: judgedCells(record),
+      conditions: {},
+      latencyLineMs: record.latencyLineMs ?? LATENCY_LINE_MS,
+    },
+  };
+}
+
+export interface JudgedLayerArgs {
+  readonly record: string;
+  readonly machineClass: string;
+  readonly files: string;
+  readonly layout: string | null;
+  readonly judgedBy?: string;
+  readonly address?: string;
+  /** Print the body only, as `plugin-db put <address> judged --writer plugin-qualify` reads it from stdin. */
+  readonly body: boolean;
+}
+
+export function judgedLayerHelpText(): string {
+  return [
+    "usage: plugin-qualify judged-layer <record.qualification.json> --machine-class <word> --files <sha256>",
+    "                                   [--layout <scheme>:<sha256>] [--judged-by <version>] [--address <address>] [--body]",
+    "",
+    "Print the plugin-db judged layer of a qualification record, for the pin plugin-db holds (its files digest and",
+    "layout). --judged-by names the plugin-qualify that judged a record stating no rules (the set's provenance). --body",
+    "prints the body only, for `plugin-db put <address> judged --writer plugin-qualify`. A record whose verdict under",
+    "plugin-hostd's worker was not measured has no layer: the reason is printed and the exit status is 1.",
+    "",
+  ].join("\n");
+}
+
+export type ParsedJudgedLayerArgs = { ok: true; args: JudgedLayerArgs } | { ok: true; help: true } | { ok: false; error: string };
+
+export function parseJudgedLayerArgs(argv: readonly string[]): ParsedJudgedLayerArgs {
+  const opts: Record<string, string> = {};
+  const files: string[] = [];
+  let body = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--help" || a === "-h") return { ok: true, help: true };
+    if (a === "--body") body = true;
+    else if (["--machine-class", "--files", "--layout", "--judged-by", "--address"].includes(a)) {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith("--")) return { ok: false, error: `${a} needs a value` };
+      opts[a] = v;
+    } else if (a.startsWith("--")) return { ok: false, error: `unknown option ${a}` };
+    else files.push(a);
+  }
+  if (files.length !== 1) return { ok: false, error: "name one record" };
+  const machineClass = opts["--machine-class"];
+  const pinFiles = opts["--files"];
+  if (machineClass === undefined) return { ok: false, error: "--machine-class is required" };
+  if (pinFiles === undefined || !/^[0-9a-f]{64}$/.test(pinFiles)) return { ok: false, error: "--files must be the 64 hex digits of the files pin" };
+  const layout = opts["--layout"] ?? null;
+  if (layout !== null && !/^[^:]+:[0-9a-f]{64}$/.test(layout)) return { ok: false, error: "--layout must be <scheme>:<sha256>" };
+  return {
+    ok: true,
+    args: {
+      record: files[0]!,
+      machineClass,
+      files: pinFiles,
+      layout,
+      body,
+      ...(opts["--judged-by"] === undefined ? {} : { judgedBy: opts["--judged-by"] }),
+      ...(opts["--address"] === undefined ? {} : { address: opts["--address"] }),
+    },
+  };
+}

package/src/judgement-line.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * What plugin-qualify's judgement declares once and writes into every record (and so into every judged layer): the
+ * latency line and the rules a record was judged by (openmixer plugin-system design 7.15, plugin-db records.md).
+ */
+import { readFileSync } from "node:fs";
+
+/** The latency line, in milliseconds: declared once, here, and written into every record and judged layer. */
+export const LATENCY_LINE_MS = 5;
+
+/** A measured latency in milliseconds at its rate, rounded to the microsecond. */
+export const latencyMsOf = (frames: number, rate: number): number => Math.round((frames * 1e9) / rate) / 1e6;
+
+const VERSION: string = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/** The rules a plugin-qualify of this version judges by: `plugin-qualify-rules/<major>.<minor>`. */
+export function judgementRules(version: string = VERSION): string {
+  const m = /^(\d+)\.(\d+)\.\d+/.exec(version);
+  if (m === null) throw new Error(`judgementRules: ${JSON.stringify(version)} is no version`);
+  return `plugin-qualify-rules/${m[1]}.${m[2]}`;
+}