@openmixer/plugin-qualify 0.20.1 → 0.20.3

package/src/qualify-declarations.ts

@@ -14,9 +14,16 @@ import { ORACLE_FLOOR_RATES, RT_HARD_TARGET } from "@openmixer/omx-contract";
 export const COST_REFERENCE_RATE = 96000;
 
 /**
- * The reference quantum in frames: the rig's buffer, and the block `benchmark.py` runs.
+ * The reference quantum in frames: the buffer the console aims at (96000/256), the quantum its budget is judged at,
+ * and the block `benchmark.py` runs.
  */
-export const QUANTUM_FRAMES = 1024;
+export const QUANTUM_FRAMES = 256;
+
+/**
+ * The long quantum, in frames: the console's basis until 0.20.2, kept as a measured cell so a plugin's cost at a large
+ * buffer stays on record beside its cost at the console's.
+ */
+export const LONG_QUANTUM_FRAMES = 1024;
 
 /** The rate the offline capture window is sized at; other rates scale from it. */
 export const MEASURE_BASE_RATE = 48000;
@@ -31,8 +38,8 @@ export const OPERATIONAL_RATE_FLOOR = 48000;
 /** The rates a run measures when `--rates` is not given — recorded in `run.rates`: omx-contract's ORACLE_FLOOR_RATES. */
 export const QUALIFY_RATES: readonly number[] = ORACLE_FLOOR_RATES;
 
-/** The quanta (frames) a run rates cost at when `--quanta` is not given: the contract's hard-target quantum, then 256, 512 and the reference. */
-export const QUALIFY_QUANTA: readonly number[] = [RT_HARD_TARGET.quantum, 256, 512, QUANTUM_FRAMES];
+/** The quanta (frames) a run rates cost at when `--quanta` is not given: the contract's hard-target quantum, the reference, 512 and the long quantum. */
+export const QUALIFY_QUANTA: readonly number[] = [RT_HARD_TARGET.quantum, QUANTUM_FRAMES, 512, LONG_QUANTUM_FRAMES];
 
 /** Seconds one plugin's offline pass may take before its worker is killed and it reads as a timeout. */
 export const PLUGIN_TIMEOUT_S = 15;
@@ -174,13 +181,22 @@ export const MEMORY_BOUND_EXIT_STATUS = 121;
 /**
  * The memory-only pass (`plugin-qualify-sync --memory-only`). With `PROBE_MEMORY_ONLY_ENV` set the probers take the
  * footprint and nothing else; the probe runner passes its environment on, so its limits hold unchanged.
- * `PROBE_NOTES_ENV` is the count of notes an instrument that declares no voice capacity holds, basis `probe`:
+ * `PROBE_NOTES_ENV` is the count of notes an instrument that declares no voice capacity holds, basis `probe`, in every
+ * LV2 run (probe-runner) and in the memory-only pass:
  * `MEMORY_PASS_PROBE_NOTES` unless `memory_notes` says otherwise.
  */
 export const PROBE_MEMORY_ONLY_ENV = "OMX_PROBE_MEMORY_ONLY";
 export const PROBE_NOTES_ENV = "OMX_PROBE_NOTES";
 export const MEMORY_PASS_PROBE_NOTES = 16;
 
+/**
+ * The counts of notes an LV2 instrument is timed at, besides its probe count, for its cost against the notes held
+ * (the rate's `voiceCurve`, probe output 1.4): the counts the Pi measurements held Surge XT at
+ * (openmixer.org/notes/instruments-on-a-pi-5), so a voice limit shows as the count past which the cost stops growing.
+ */
+export const PROBE_NOTES_CURVE_ENV = "OMX_PROBE_NOTES_CURVE";
+export const PROBE_NOTES_CURVE = [1, 8, 16, 32, 48, 64] as const;
+
 /**
  * What `tools/mod-host-admit.mjs` is told in an adapter-only pass: how long the host has for one command, its address
  * space (`ulimit -v`, in KB) and the directory for the state files of the plugin it loads.
@@ -239,6 +255,8 @@ export const DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing
 export const DESCRIPTOR_CODE_SCHEMA_FLOOR = "qualify.descriptor.schema-floor";
 export const DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed";
 export const DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable";
+/** Two ports of one plugin carry the same symbol: neither can be addressed by it, so the plugin is not described. Args: `symbol`. */
+export const DESCRIPTOR_CODE_DUPLICATE_SYMBOL = "qualify.descriptor.duplicate-symbol";
 
 
 
@@ -317,11 +335,14 @@ const piMemory = (ramGib: number): NonNullable<HostBudget["memory"]> => ({
 /**
  * The cells a Raspberry Pi runs: zynthian-sys's JACK settings, 48000/128 on a Pi 5 with the V5 kit and 48000/256 on a Pi 4 and
  * the other kits, the one a Pi 5 with no kit card also ran its stress and first boot at. The Zynthian benchmark's matrix sweeps
- * more cells; these two are what a Pi is set to.
+ * more cells; these two are what a Pi is set to. Every Pi matrix carries 96000 beside 48000, so each of the two quanta
+ * is also run at twice the base rate: the passes that follow these cells (adapter, isolated, memory, pool) cost twice as long.
  */
 export const PI_CELLS = [
   { rate: MEASURE_BASE_RATE, quantum: 128 },
   { rate: MEASURE_BASE_RATE, quantum: 256 },
+  { rate: 2 * MEASURE_BASE_RATE, quantum: 128 },
+  { rate: 2 * MEASURE_BASE_RATE, quantum: 256 },
 ];
 
 export const HOST_BUDGETS = {

package/src/qualify-isolated.ts

@@ -16,6 +16,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import { ADAPTER_PASS_CELLS, startPrivateJack, type JackStarter } from "./qualify-adapter-pass.js";
 import type { GridCell } from "./measurement-grid.js";
 import { clapPinUri, type PinEntry } from "./pins-file.js";
@@ -130,6 +131,21 @@ export function pinFromRecord(record: QualificationRecord): PinEntry | undefined
   return pinAfterStep({ uri, integrity: { files: sorted, layout } }, step);
 }
 
+/**
+ * Whether a step of the isolated kind is a verdict. A refusal (`isolated.silent-output`, `isolated.not-added`) is one: the
+ * plugin was tried and the answer is no. A step that could not run decided nothing, and neither did silence before the
+ * notes were played where a plugin could hear them: a step of that tool does not say how many inputs it linked. Those two
+ * are owed, and a pass tries them again.
+ */
+export function isolatedDecided(s: RunStep): boolean {
+  return s.step === RUN_STEP.isolated && s.result !== ISOLATED_RESULT.notRun && !(s.code === ISOLATED_CODE.silent && s.figures?.midiInputsLinked === undefined);
+}
+
+/** Whether the record holds a finished isolated step, of whatever answer: nothing about it is owed. */
+export function isolatedFinished(record: QualificationRecord): boolean {
+  return record.run?.steps.some(isolatedDecided) === true;
+}
+
 /** Whether the isolated step saw this plugin running alone. A record's word alone never says so. */
 export function provenAlone(record: QualificationRecord): boolean {
   return record.run?.steps.some((s) => s.step === RUN_STEP.isolated && s.result === ISOLATED_RESULT.isolated) === true;
@@ -182,7 +198,7 @@ export function spawnedIsolatedRunner(jack: JackStarter = startPrivateJack): Iso
         encoding: "utf8",
         timeout: ISOLATED_WINDOW_MS + ISOLATED_STEP_SLACK_MS,
         killSignal: "SIGKILL",
-        env: { ...env, JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
+        env: { ...withRunHome(env), JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
       });
       if (r.error !== undefined || r.status !== 0) return { started: false, problem: `isolated-step: ${r.error?.message ?? `exit ${String(r.status)}`}: ${(r.stderr ?? "").trim()}` };
       return JSON.parse(r.stdout) as IsolatedRunFacts;
@@ -225,10 +241,7 @@ export function runIdOf(record: QualificationRecord, dir: string): string | unde
  */
 export function completeIsolated(path: string, record: QualificationRecord, uri: string, cell: GridCell, runner: IsolatedRunner, env: Readonly<Record<string, string | undefined>>): { readonly record: QualificationRecord; readonly step: RunStep } | undefined {
   const isStep = (s: RunStep): boolean => s.step === RUN_STEP.isolated;
-  // a step that could not run decided nothing, and neither did silence before the notes were played where a plugin could
-  // hear them: a step of that tool does not say how many inputs it linked. A pass tries these again, and it takes their place
-  const decided = (s: RunStep): boolean => s.result !== ISOLATED_RESULT.notRun && !(s.code === ISOLATED_CODE.silent && s.figures?.midiInputsLinked === undefined);
-  if (!owesIsolated(record) || record.run?.steps.some((s) => isStep(s) && decided(s)) === true) return undefined;
+  if (!owesIsolated(record) || isolatedFinished(record)) return undefined;
   const id = runIdOf(record, join(path, ".."));
   if (id === undefined) return undefined;
   const step = judgeIsolatedRun(runner(uri, cell, env));

package/src/qualify-pool.ts

@@ -30,6 +30,7 @@ import { existsSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import type { GridCell } from "./measurement-grid.js";
 import type { PinEntry, PinPool } from "./pins-file.js";
 import type { PoolFigures, QualificationRecord, RunBlock, RunStep } from "./qualification-record.js";
@@ -203,7 +204,7 @@ const POOL_STEP_SLACK_MS = 120000;
 export function asksForPool(prober: string, uri: string, env: Readonly<Record<string, string | undefined>>): boolean | undefined {
   const m = /^clap:(.*)#([^#]*)$/s.exec(uri);
   if (m === null) return undefined;
-  const r = spawnSync(prober, ["--asks-thread-pool", m[1]!, m[2]!], { encoding: "utf8", timeout: 60000, killSignal: "SIGKILL", env: { ...env } });
+  const r = spawnSync(prober, ["--asks-thread-pool", m[1]!, m[2]!], { encoding: "utf8", timeout: 60000, killSignal: "SIGKILL", env: withRunHome(env) });
   if (r.status !== 0) return undefined;
   try {
     return (JSON.parse(r.stdout) as { threadPool?: unknown }).threadPool === true;
@@ -233,7 +234,7 @@ export function watchOnHelpers(prober: string, interposer: string, uri: string,
     encoding: "utf8",
     timeout: 120000,
     killSignal: "SIGKILL",
-    env: { ...env, LD_PRELOAD: preload },
+    env: { ...withRunHome(env), LD_PRELOAD: preload },
   });
   if (r.error !== undefined || r.status !== 0) return { problem: `${CLAP_QUALIFY_TOOL_NAME} --pool: ${r.error?.message ?? `exit ${String(r.status)}`}` };
   const line = r.stdout.split("\n").filter((l) => l.startsWith("{")).pop();
@@ -273,7 +274,7 @@ export function spawnedPoolRunner(jack: JackStarter = startPrivateJack): PoolRun
         encoding: "utf8",
         timeout: 2 * POOL_ROUNDS * POOL_WINDOW_MS + POOL_STEP_SLACK_MS,
         killSignal: "SIGKILL",
-        env: { ...env, JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
+        env: { ...withRunHome(env), JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
       });
       if (r.error !== undefined || r.status !== 0) return { started: false, problem: `pool-step: ${r.error?.message ?? `exit ${String(r.status)}`}: ${(r.stderr ?? "").trim()}` };
       return { ...(JSON.parse(r.stdout) as PoolRunFacts), asks: true, rt: watched.rt };

package/src/qualify-rejudge.ts

@@ -48,7 +48,7 @@ import {
   type RecordVerdict,
   type RunBlock,
 } from "./qualification-record.js";
-import { ISOLATED_RESULT, RUN_STEP, pinAfterStep, provenAlone } from "./qualify-isolated.js";
+import { ISOLATED_RESULT, RUN_STEP, isolatedFinished, pinAfterStep } from "./qualify-isolated.js";
 import { pinAfterPool, poolStepOf } from "./qualify-pool.js";
 import { PI_CELLS, PROBE_MEMORY_ONLY_ENV, PROBE_NOTES_ENV } from "./qualify-declarations.js";
 import { SYNC_STATE_SCHEMA, digestFiles, recordStem, type SyncContext, type SyncEntry, type SyncPlugin, type SyncState } from "./qualify-sync.js";
@@ -198,9 +198,9 @@ export function rejudgeRecord(record: QualificationRecord, probeBytes: Uint8Arra
   const { profiles, kept } = rejudgeProfiles(record, output, options.host);
   const { reasons, owes: runs } = runsOwed(record, output, profiles);
   const judgment = judgeProbeOutput(output, profiles, { admissions: admissionsOf(record), owed: reasons });
-  // decides no verdict: a record from before the steps that reads isolated stays offered, runs alone, and is not proven by the step
+  // decides no verdict: a record from before the steps that reads isolated stays offered and runs alone, and owes the step until one has finished; a refusal is finished: it is the step's verdict, not debt
   const readsIsolated = judgment.hosts.some((h) => h.verdict.measured && h.verdict.rating === "conditional");
-  const owes = readsIsolated && !provenAlone(record) ? [...runs, { measurement: "isolated-step" as const, code: OWED_CODE.isolatedStep }] : runs;
+  const owes = readsIsolated && !isolatedFinished(record) ? [...runs, { measurement: "isolated-step" as const, code: OWED_CODE.isolatedStep }] : runs;
   const memory = record.memoryRun === undefined ? {} : { memory: { tool: record.memoryRun.tool, measuredAt: record.memoryRun.measuredAt } };
   const a = record.adapter;
   const adapterTaken = a?.versions === undefined || a.measuredAt === undefined ? {} : { adapter: { versions: a.versions, measuredAt: a.measuredAt } };

package/src/qualify-sync.ts

@@ -23,12 +23,15 @@ import { createConnection } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import { clapQualifyTools } from "./clap-qualify.js";
 import { DISTRIBUTED_DIR_SYSTEM, EMPTY_LAYER, applyDistributed, distributedUri, hostClassOfBoard, hostClassOfMachine, outcomeOfVerdict, matchDistributed, readBoardModel, readMachine, readDistributedLayer, type DistributedLayer } from "./distributed-records.js";
-import { clapSearchPath, parseClapScan } from "./clap-loader.js";
+import { parseClapScan } from "./clap-loader.js";
+import { SPAWNED_SEARCH_PATH, hostdSearchPath, searchPathWarnings, type SearchPathRun } from "./hostd-search-path.js";
 import { HOSTING_CODE } from "./hosting-codes.js";
 import { shippedHostProfile, type HostProfile } from "./host-profiles.js";
-import { lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
+import { NO_JACK_SERVER } from "./host-admission.js";
+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";
@@ -39,7 +42,7 @@ import { adapterPass, type AdapterPassOptions, type AdapterPassResult } from "./
 import { ISOLATED_RESULT, baseSteps, completeIsolated, isolatedCell, missingSteps, judgeIsolatedRun, owesIsolated, pinAfterStep, spawnedIsolatedRunner, type IsolatedRunner } from "./qualify-isolated.js";
 import { lv2World, rejudgeRecord, rejudgeState, rejudgeToolName, memoryPass, type MemoryPassResult, type RejudgeResult } from "./qualify-rejudge.js";
 import { memoryBoundOf, parseMemoryLimit, type MemoryBound } from "./memory-bound.js";
-import { QUALIFICATION_RECORD_SCHEMA, latencyNeverTaken, rewriteRecord, writeQualification, type NotMeasured, type QualificationRecord } from "./qualification-record.js";
+import { QUALIFICATION_RECORD_SCHEMA, descriptorNamePart, latencyNeverTaken, rewriteRecord, writeQualification, type NotMeasured, type QualificationRecord } from "./qualification-record.js";
 import { ADMIT_STEP_MS_ENV, DESCRIPTOR_DIR_STATE_SUBDIR, DESCRIPTOR_DIR_SYSTEM, MEMORY_PASS_PROBE_NOTES, QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
 import { toolsDir } from "./tool-paths.js";
 import { writeFileWhole } from "./whole-file.js";
@@ -49,12 +52,6 @@ import { writeFileWhole } from "./whole-file.js";
 /** The settings file a system service reads, `key value` per line. */
 export const SYNC_CONF = "/etc/omx/qualify.conf";
 
-/** The LV2 directories plugin-hostd searches when `LV2_PATH` is unset (its `lv2_path` default). */
-export const HOSTD_LV2_PATH = ["/usr/lib64/lv2", "/usr/lib/lv2", "/usr/local/lib/lv2"];
-
-/** Zynthian's own LV2 directories: the image's plugins and the ones its user installs. */
-export const ZYNTHIAN_LV2_DIRS = ["/zynthian/zynthian-plugins/lv2", "/zynthian/zynthian-my-data/plugins/lv2"];
-
 export interface SyncSetting {
   readonly key: string;
   readonly meaning: string;
@@ -64,10 +61,7 @@ export interface SyncSetting {
 
 /** Every setting, declared once: the settings file, the flags (`--pin-file` for `pin_file`) and `--help` read this. */
 export const SYNC_SETTINGS: readonly SyncSetting[] = [
-  { key: "lv2_path", meaning: "the LV2 directories, colon-separated, in the order plugin-hostd searches them", default: "$LV2_PATH, else " + HOSTD_LV2_PATH.join(":") },
-  { key: "lv2_extra", meaning: "more LV2 directories, searched after lv2_path", default: ZYNTHIAN_LV2_DIRS.join(":") },
-  { key: "clap_path", meaning: "the CLAP directories, colon-separated", default: "$CLAP_PATH, then ~/.clap, then /usr/lib/clap" },
-  { key: "clap_extra", meaning: "more CLAP directories, searched after clap_path", default: "" },
+  { key: "hostd_conf", meaning: "plugin-hostd's settings file: the LV2 and CLAP directories scanned are the ones plugin-hostd --search-path -c <file> prints", default: "plugin-hostd's own (its XDG_CONFIG_HOME/plugin-hostd.conf, else ~/.config/plugin-hostd.conf)" },
   { key: "pin_file", meaning: "the pin file plugin-hostd loads as pin_file", default: "/var/lib/omx/qualified.pins (system), else $XDG_STATE_HOME/omx/qualified.pins" },
   { key: "qualification_dir", meaning: "where the qualification records go", default: "/var/lib/omx/qualification (system), else $XDG_STATE_HOME/omx/qualification" },
   { key: "descriptor_dir", meaning: "where the scanned descriptors go", default: `${DESCRIPTOR_DIR_SYSTEM} (system), else $XDG_STATE_HOME/${DESCRIPTOR_DIR_STATE_SUBDIR}` },
@@ -85,8 +79,16 @@ export const SYNC_SETTINGS: readonly SyncSetting[] = [
   { key: "distributed_dir", meaning: "the directories of distributed records, colon-separated, each holding <host class>/<set>/", default: `${DISTRIBUTED_DIR_SYSTEM} (system), else $XDG_DATA_HOME/omx/qualification and each $XDG_DATA_DIRS/omx/qualification` },
 ];
 
+/** The search path settings that moved to plugin-hostd's settings file (plugin-qualify#9): refused here, with where they went. */
+export const MOVED_TO_HOSTD = ["lv2_path", "lv2_extra", "clap_path", "clap_extra"] as const;
+
+const movedText = (key: string): string =>
+  `${key} is plugin-hostd's setting now: write it in plugin-hostd's settings file (plugin-hostd.conf, named here by hostd_conf); the directories scanned are the ones plugin-hostd --search-path prints${key === "clap_extra" ? " (plugin-hostd has no clap_extra: add the directories to clap_path)" : ""}`;
+
 export interface SyncSettings {
+  /** The LV2 directories, as plugin-hostd searches them with hostd_conf (plugin-hostd --search-path). */
   readonly lv2Dirs: readonly string[];
+  /** The CLAP directories, as plugin-hostd searches them with hostd_conf. */
   readonly clapDirs: readonly string[];
   readonly pinFile: string;
   readonly qualificationDir: string;
@@ -121,6 +123,7 @@ export function parseSyncConf(text: string, source = SYNC_CONF): { ok: true; val
     if (line === "") continue;
     const m = /^(\S+)(?:\s+(.*))?$/.exec(line)!;
     const key = m[1]!;
+    if ((MOVED_TO_HOSTD as readonly string[]).includes(key)) return { ok: false, error: `${source}:${String(n + 1)}: ${movedText(key)}` };
     if (!known.has(key)) return { ok: false, error: `${source}:${String(n + 1)}: ${key} is not a setting` };
     values.set(key, (m[2] ?? "").trim());
   }
@@ -186,7 +189,8 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
       if (v === undefined) return { ok: false, error: `${a} needs a value` };
       if (a === "--config") config = v;
       else values.set(byFlag.get(a)!, v);
-    } else return { ok: false, error: `unknown argument ${a}` };
+    } else if (MOVED_TO_HOSTD.some((k) => flagOf(k) === a)) return { ok: false, error: `${a}: ${movedText(a.slice(2).replace(/-/g, "_"))}` };
+    else return { ok: false, error: `unknown argument ${a}` };
   }
   if (rejudge && (memoryOnly || adapterOnly || isolatedOnly || poolOnly || force || refreshPinsOnly)) return { ok: false, error: "--rejudge measures nothing: it goes with none of --memory-only, --adapter-only, --isolated-only, --pool-only, --force and --refresh-pins" };
   if ([memoryOnly, adapterOnly, isolatedOnly, poolOnly, refreshPinsOnly].filter(Boolean).length > 1) return { ok: false, error: "--memory-only, --adapter-only, --isolated-only, --pool-only and --refresh-pins are different runs: one at a time" };
@@ -229,17 +233,18 @@ export function resolveSyncSettings(
   home: string = homedir(),
   boardModel: () => string | undefined = readBoardModel,
   machineArch: () => string | undefined = readMachine,
-): { ok: true; settings: SyncSettings } | { ok: false; error: string } {
+  searchPathRun: SearchPathRun = SPAWNED_SEARCH_PATH,
+): { ok: true; settings: SyncSettings; warnings: string[] } | { ok: false; error: string } {
   const get = (key: string): string | undefined => args.values.get(key) ?? file.get(key);
   const state = env["XDG_STATE_HOME"] !== undefined && env["XDG_STATE_HOME"] !== "" ? env["XDG_STATE_HOME"] : join(home, ".local", "state");
   const place = (key: string, system: string, user: string): string => {
     const v = get(key);
     return v !== undefined && v !== "" ? v : args.system ? system : join(state, user);
   };
-  const lv2Named = get("lv2_path");
-  const lv2Base = lv2Named !== undefined && lv2Named !== "" ? dirList(lv2Named) : dirList(env["LV2_PATH"] ?? "").length > 0 ? dirList(env["LV2_PATH"]!) : HOSTD_LV2_PATH;
-  const clapNamed = get("clap_path");
-  const clapBase = clapNamed !== undefined && clapNamed !== "" ? dirList(clapNamed) : clapSearchPath(env, home);
+  const hostdConfNamed = get("hostd_conf");
+  const hostdConf = hostdConfNamed !== undefined && hostdConfNamed !== "" ? hostdConfNamed : undefined;
+  const search = hostdSearchPath(hostdConf, env, searchPathRun);
+  if (!search.ok) return { ok: false, error: `the directories to scan: ${search.error}` };
   const number = (key: string, min: number): number | undefined => {
     const v = Number(get(key) ?? SYNC_SETTINGS.find((s) => s.key === key)!.default);
     return Number.isFinite(v) && v >= min ? v : undefined;
@@ -281,9 +286,10 @@ export function resolveSyncSettings(
   if (hostClass !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(hostClass)) return { ok: false, error: `host_class ${hostClass} is not a directory name` };
   return {
     ok: true,
+    warnings: searchPathWarnings(search.path, hostdConf),
     settings: {
-      lv2Dirs: once([...lv2Base, ...dirList(get("lv2_extra") ?? ZYNTHIAN_LV2_DIRS.join(":"))]),
-      clapDirs: once([...clapBase, ...dirList(get("clap_extra") ?? "")]),
+      lv2Dirs: once(search.path.lv2),
+      clapDirs: once(search.path.clap),
       pinFile: place("pin_file", "/var/lib/omx/qualified.pins", join("omx", "qualified.pins")),
       qualificationDir: place("qualification_dir", "/var/lib/omx/qualification", join("omx", "qualification")),
       descriptorDir: place("descriptor_dir", DESCRIPTOR_DIR_SYSTEM, DESCRIPTOR_DIR_STATE_SUBDIR),
@@ -442,7 +448,7 @@ export function discoverSyncItems(
         const binary = lilv?.binary ?? (p.binary === undefined ? undefined : join(bundle, p.binary));
         const files = ["manifest.ttl", ...p.files.filter((f) => f !== "manifest.ttl")];
         // a binary named by an absolute IRI (a complement's) is tracked through the bundle's link to it, when it has one
-        if (binary !== undefined && !files.includes(basename(binary)) && linksTo(join(bundle, basename(binary)), binary)) files.push(basename(binary));
+        if (binary !== undefined && !files.some((f) => iriPath(f) === basename(binary)) && linksTo(join(bundle, basename(binary)), binary)) files.push(basename(binary));
         items.push({ key: `lv2:${p.uri}`, format: "lv2", root: bundle, files, uri: p.uri, ...(binary === undefined ? {} : { binary }) });
       }
     }
@@ -482,7 +488,10 @@ export function fileSha256(path: string): string {
 export function digestFiles(root: string, files: readonly string[], known: readonly FileDigest[] = []): FileDigest[] | undefined {
   const out: FileDigest[] = [];
   for (const path of [...new Set(files)].sort()) {
-    const full = join(root, path);
+    // a name may be an IRI's word (the pin keeps `libSurge%20XT.so`); the file is the path it decodes to, and a name
+    // that is a file as written (a .clap with a % in it) is read as written when the decoded one is not there
+    const decoded = join(root, iriPath(path));
+    const full = existsSync(decoded) ? decoded : join(root, path);
     try {
       const st = statSync(full);
       if (!st.isFile()) return undefined;
@@ -526,6 +535,7 @@ export function machineReason(p: Pick<SyncPlugin, "outcome" | "code" | "detail">
   if (p.outcome !== "unmeasured" || p.code !== SYNC_CODE.notMeasured) return undefined;
   const errno = /\b(EACCES|EPERM|ENOSPC)\b/.exec(p.detail ?? "")?.[1];
   if (errno !== undefined) return errno;
+  if ((p.detail ?? "").startsWith(NO_JACK_SERVER)) return NO_JACK_SERVER;
   return /wrote no document|cannot run the probe runner/.test(p.detail ?? "") ? "the measurement wrote no document" : undefined;
 }
 
@@ -623,7 +633,7 @@ export function recordedAsIs(item: SyncItem, entry: SyncEntry | undefined): { sa
  */
 export function sameBinaryElsewhere(item: SyncItem, entry: SyncEntry | undefined): SyncEntry | undefined {
   if (item.format !== "lv2" || entry === undefined || item.binary === undefined || resolve(entry.root) === resolve(item.root)) return undefined;
-  const was = entry.files.find((f) => basename(f.path) === basename(item.binary!));
+  const was = entry.files.find((f) => basename(iriPath(f.path)) === basename(item.binary!));
   if (was === undefined) return undefined;
   let now: string;
   try {
@@ -715,7 +725,7 @@ function outcomeOf(judgment: Judgment, host: string): { outcome: SyncOutcome; co
   return { outcome: v.rating === "unsuitable" ? "refused" : "unmeasured", ...(code === undefined ? {} : { code }) };
 }
 
-const safe = (text: string): string => text.replace(/[^A-Za-z0-9._-]/g, "_");
+const safe = descriptorNamePart;
 
 /** The record of a plugin no probe output exists for: what it is, the bytes it was, and why nothing was measured. */
 function writeUnmeasuredRecord(ctx: SyncContext, item: SyncItem, files: readonly FileDigest[], plugin: Omit<SyncPlugin, "record">): string {
@@ -735,8 +745,19 @@ function writeUnmeasuredRecord(ctx: SyncContext, item: SyncItem, files: readonly
   return path;
 }
 
-/** The step's environment: each of its commands has the sync's budget. */
-const isolatedEnv = (ctx: SyncContext): Readonly<Record<string, string | undefined>> => ({ ...ctx.env, [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000) });
+/** The directories the sync scanned, as the plugin-hostd a step starts reads them: with neither variable set it searches
+ * only its own defaults, and every plugin of `lv2_extra` or of a directory the settings add is refused at add. */
+export const hostdSearchEnv = (settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">): Record<string, string> => ({
+  LV2_PATH: settings.lv2Dirs.join(":"),
+  CLAP_PATH: settings.clapDirs.join(":"),
+});
+
+/** The step's environment: the sync's directories, and each of its commands has the sync's budget. */
+export const isolatedEnv = (ctx: Pick<SyncContext, "env" | "settings">): Readonly<Record<string, string | undefined>> => ({
+  ...ctx.env,
+  ...hostdSearchEnv(ctx.settings),
+  [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000),
+});
 
 /** Each judged run of a pass as the plugins it qualified: the record written, the pin taken, the outcome. */
 function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgment: Judgment; stderr?: readonly Buffer[] }[], describeProblem?: string): SyncPlugin[] {
@@ -772,7 +793,7 @@ function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgmen
     // the pool is for a CLAP plugin that runs: the thread pool is granted by measuring it, here and nowhere else
     if (judgment.output.plugin.format === "clap" && pin !== undefined && pin.verdict !== "refused" && outcome === "qualified") {
       const runner = ctx.poolRunner ?? spawnedPoolRunner();
-      const step = judgePoolRun(runner(pin.uri, isolatedCell(record, host), poolEnv(ctx.env, ctx.settings.budgetS)));
+      const step = judgePoolRun(runner(pin.uri, isolatedCell(record, host), poolEnv({ ...ctx.env, ...hostdSearchEnv(ctx.settings) }, ctx.settings.budgetS)));
       steps.push(step);
       pin = pinAfterPool(pin, step);
     }
@@ -845,7 +866,7 @@ function qualifyClap(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
     return [{ uri: fileUri, outcome: "unmeasured", code: SYNC_CODE.notMeasured, detail: (e as Error).message }];
   }
   // the scanner lists the plugins of the file in a child of its own, and says how that child ended
-  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20 });
+  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20, env: withRunHome(process.env) });
   let scanned;
   try {
     if (r.error !== undefined) throw r.error;
@@ -975,7 +996,7 @@ export function poolPass(ctx: SyncContext, state: SyncState): { readonly state:
           ctx.log(`${p.uri}: its record does not read; no pool step`);
           return p;
         }
-        const done = completePool(path, record, p.pin.uri, isolatedCell(record, host), runner, poolEnv(ctx.env, ctx.settings.budgetS));
+        const done = completePool(path, record, p.pin.uri, isolatedCell(record, host), runner, poolEnv({ ...ctx.env, ...hostdSearchEnv(ctx.settings) }, ctx.settings.budgetS));
         if (done === undefined) return p;
         ctx.log(`${p.uri}: pool step ${done.step.result}${done.step.code === undefined ? "" : ` (${done.step.code})`}`);
         if (done.step.result === POOL_RESULT.cores) count.cores++;
@@ -1079,7 +1100,7 @@ function scanClapDescriptors(ctx: SyncContext, item: SyncItem): void {
     ctx.log(`${file}: descriptors not written: ${(e as Error).message}`);
     return;
   }
-  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20 });
+  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20, env: withRunHome(process.env) });
   if (r.error !== undefined || r.status !== 0) {
     ctx.log(`${file}: descriptors not written: the scan ended ${r.error?.message ?? `with exit ${String(r.status)}`}`);
     return;

package/src/run-home.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The HOME every process that loads a plugin starts with: a scratch directory of this plugin-qualify run, never the
+ * caller's real home. A plugin that reads its user data from HOME (Surge XT) segfaults or stays silent without one,
+ * and a probe must not write into a user's home. Created on first use, removed when the process exits.
+ */
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+let home: string | undefined;
+
+/** The run's scratch HOME, made on first use. */
+export function runHome(): string {
+  if (home === undefined) {
+    const dir = mkdtempSync(join(tmpdir(), "plugin-qualify-home-"));
+    process.on("exit", () => rmSync(dir, { recursive: true, force: true }));
+    home = join(dir, "home");
+    mkdirSync(home);
+  }
+  return home;
+}
+
+/** `env` with HOME set to the run's scratch HOME. */
+export function withRunHome(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined> {
+  return { ...env, HOME: runHome() };
+}

package/tools/_declarations.py

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

package/tools/descriptors.py

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

package/tools/gen-python-declarations.mjs

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

package/tools/isolated-step.mjs

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