@openmixer/plugin-qualify 0.18.3 → 0.18.5

package/src/jack-registry.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * 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
+ * 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.
+ */
+import { closeSync, existsSync, openSync, readSync, writeSync } from "node:fs";
+
+export const JACK_REGISTRY = "/dev/shm/jack-shm-registry";
+/** the header jack2 writes before the server rows, and the size of a row: a pid, then the name */
+export const JACK_REGISTRY_HEADER = 24;
+export const JACK_REGISTRY_ENTRY = 264;
+const ROWS = 8;
+const MAGIC = "KCAJ";
+const OWN = ":omx-qualify-";
+
+const alive = (pid: number): boolean => existsSync(`/proc/${String(pid)}`);
+
+/** Frees the rows of the pass's own servers that are gone; the names freed, in the table's order. */
+export function freeDeadJackSlots(path: string = process.env["OMX_JACK_REGISTRY"] ?? JACK_REGISTRY): string[] {
+  const freed: string[] = [];
+  let fd: number;
+  try {
+    fd = openSync(path, "r+");
+  } catch {
+    return freed;
+  }
+  try {
+    const head = Buffer.alloc(JACK_REGISTRY_HEADER + ROWS * JACK_REGISTRY_ENTRY);
+    if (readSync(fd, head, 0, head.length, 0) !== head.length) return freed;
+    // the layout this code knows, or nothing is touched
+    if (head.toString("latin1", 0, 4) !== MAGIC || head.readUInt32LE(16) !== JACK_REGISTRY_HEADER + ROWS * JACK_REGISTRY_ENTRY) return freed;
+    for (let k = 0; k < ROWS; k++) {
+      const at = JACK_REGISTRY_HEADER + k * JACK_REGISTRY_ENTRY;
+      const pid = head.readInt32LE(at);
+      const name = head.toString("latin1", at + 4, at + JACK_REGISTRY_ENTRY).split("\0")[0] ?? "";
+      if (pid <= 0 || !name.includes(OWN) || alive(pid)) continue;
+      writeSync(fd, Buffer.alloc(4), 0, 4, at);
+      writeSync(fd, Buffer.alloc(1), 0, 1, at + 4);
+      freed.push(name);
+    }
+  } finally {
+    closeSync(fd);
+  }
+  return freed;
+}

package/src/probe-judge.ts

@@ -197,6 +197,8 @@ export interface HostJudgment {
 
 export interface Judgment {
   readonly output: ProbeOutput;
+  /** How loaded the machine was when the probe started (probe-runner's ProbeLoad); absent when not taken. */
+  readonly load?: { readonly loadavg1: number; readonly cores: number };
   /** An LV2 plugin's run under plugin-hostd's LV2 adapter, beside the verdicts (plugin-qualify#223). */
   readonly adapter?: HostAdmission;
   readonly hosts: readonly HostJudgment[];

package/src/probe-runner.ts

@@ -13,7 +13,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { availableParallelism, loadavg, tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { ClapQualifyError, clapQualifyTools, proberOffer, type RtSafetyDocument } from "./clap-qualify.js";
@@ -155,11 +155,22 @@ export function lv2RunnerArgs(
 }
 
 /** One probe output and the bytes it was read from (the bytes are what gets copied beside the record). */
+/** How loaded the machine was when a probe started: the one-minute load average and the cores, so that a crash under a
+ * full machine can be told from one on an idle one. */
+export interface ProbeLoad {
+  readonly loadavg1: number;
+  readonly cores: number;
+}
+
 export interface ProbedTarget {
   readonly bytes: Buffer;
   readonly output: ProbeOutput;
+  /** The most loaded the machine was when any of the target's runs started. */
+  readonly load?: ProbeLoad;
 }
 
+const loadNow = (): ProbeLoad => ({ loadavg1: Math.round(loadavg()[0]! * 100) / 100, cores: availableParallelism() });
+
 function runOne(target: PluginTarget, options: ProbeTargetOptions, invocation: RunnerInvocation): ProbedTarget {
   const env = options.env ?? process.env;
   const tool = probeRunnerTool(env);
@@ -193,6 +204,7 @@ function runOne(target: PluginTarget, options: ProbeTargetOptions, invocation: R
     }
     // under a bound, the interposer ends the child the moment an allocation is refused, with the status that names it
     if (options.memory !== undefined) runEnv = { ...runEnv, [MEMORY_BOUND_EXIT_ENV]: "1" };
+    const load = loadNow();
     const r = (options.run ?? spawnRunner)(tool, args, runEnv);
     if (r.error !== undefined) {
       throw new ProbeRunnerError(`cannot run the probe runner "${tool}" (${r.error.message}): install plugin-hostd or set ${PROBE_RUNNER_ENV} to plugin-hostd-probe`);
@@ -214,7 +226,7 @@ function runOne(target: PluginTarget, options: ProbeTargetOptions, invocation: R
     if (read.output.plugin.id !== expectedId) {
       throw new ProbeRunnerError(`${tool} measured ${read.output.plugin.id} when asked for ${expectedId}: not judged as the plugin asked for`);
     }
-    return { bytes, output: read.output };
+    return { bytes, output: read.output, load };
   } finally {
     rmSync(work, { recursive: true, force: true });
   }
@@ -231,8 +243,10 @@ export function targetCells(options: Pick<ProbeTargetOptions, "rates" | "cells">
  */
 export function probeTarget(target: PluginTarget, options: ProbeTargetOptions): ProbedTarget {
   const parts = runnerInvocations(target.format, targetCells(options)).map((invocation) => ({ ...runOne(target, options, invocation), invocation }));
+  const loads = parts.flatMap((p) => (p.load === undefined ? [] : [p.load]));
+  const load = loads.length === 0 ? undefined : loads.reduce((a, b) => (b.loadavg1 > a.loadavg1 ? b : a));
   try {
-    return mergeProbeRuns(parts, options.memory);
+    return { ...mergeProbeRuns(parts, options.memory), ...(load === undefined ? {} : { load }) };
   } catch (e) {
     if (e instanceof ProbeMergeError) throw new ProbeRunnerError(e.message);
     throw e;
@@ -321,7 +335,7 @@ export function qualifyTargets(
       for (const { offer, profiles: forOffer } of byOffer.values()) {
         const probed = probeTarget(target, { ...options, ...measured, offer });
         const plain = judgeProbeOutput(probed.output, forOffer, { admissions });
-        const judgment = adapter === undefined ? plain : { ...plain, adapter };
+        const judgment = { ...plain, ...(adapter === undefined ? {} : { adapter }), ...(probed.load === undefined ? {} : { load: probed.load }) };
         targetRuns.push({ bytes: probed.bytes, judgment });
         for (const v of judgmentVerdicts(judgment)) judged.set(v.host, v);
       }

package/src/qualification-record.ts

@@ -72,6 +72,8 @@ export interface IsolatedFigures {
   /** The worker's CPU over the window, in percent of one core. */
   readonly cpuPercent?: number;
   readonly xruns?: number;
+  /** How many MIDI inputs of the plugin the step's notes were linked to. */
+  readonly midiInputsLinked?: number;
 }
 
 /** One step of a plugin's pass and how it ended. */
@@ -341,9 +343,38 @@ export interface QualificationRecord {
     readonly machineClass: Readonly<Record<string, string | boolean>>;
     /** Whether the machine met the protocol's optimised profile: a figure that did not is not a reference figure. */
     readonly meetsProtocol: boolean;
+    /** Each step whose child did not end well: the signal that killed it or the status it exited with, so a crash is
+     * told from the runner's own kill (a deadline or memory kill is SIGKILL). Absent when every child ended well. */
+    readonly ends?: readonly ProbeEnd[];
+    /** How loaded the machine was when the probe started; absent on a record written before it was taken. */
+    readonly load?: { readonly loadavg1: number; readonly cores: number };
   };
 }
 
+/** How one step's child ended, when not well. */
+export interface ProbeEnd {
+  readonly step: string;
+  readonly outcome: string;
+  readonly rate?: number;
+  readonly quantum?: number;
+  readonly signal?: string;
+  readonly exitStatus?: number;
+}
+
+/** The steps of a probe output whose child was killed by a signal or exited with a status other than 0. */
+export function probeEnds(output: ProbeOutput): readonly ProbeEnd[] {
+  return output.steps
+    .filter((s) => (s.signal !== undefined && s.signal !== null && s.signal !== "") || (s.exitStatus !== undefined && s.exitStatus !== 0))
+    .map((s) => ({
+      step: s.step,
+      outcome: s.outcome,
+      ...(s.rate === undefined ? {} : { rate: s.rate }),
+      ...(s.quantum === undefined ? {} : { quantum: s.quantum }),
+      ...(s.signal ? { signal: s.signal } : {}),
+      ...(s.exitStatus === undefined || s.exitStatus === 0 ? {} : { exitStatus: s.exitStatus }),
+    }));
+}
+
 /** One dimension a run did not measure, and the code that says so. */
 export interface NotMeasured {
   readonly dimension: string;
@@ -429,6 +460,8 @@ export function buildQualificationRecord(
       complete: o.run.complete,
       machineClass: o.machine.class,
       meetsProtocol: o.machine.profile.meetsProtocol,
+      ...(probeEnds(o).length === 0 ? {} : { ends: probeEnds(o) }),
+      ...(judgment.load === undefined ? {} : { load: judgment.load }),
     },
   };
 }

package/src/qualify-adapter-pass.ts

@@ -17,8 +17,9 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 
-import { ADAPTER_HOST, SPAWNED_ADMISSIONS, admitUnderAdapter, type AdmissionRuns, type HostAdmission } from "./host-admission.js";
+import { ADAPTER_HOST, ADAPTER_SILENT_CODE, SPAWNED_ADMISSIONS, admitUnderAdapter, type AdmissionRuns, type HostAdmission } from "./host-admission.js";
 import { HOSTD_ENV } from "./hostd-pin-files.js";
+import { freeDeadJackSlots } from "./jack-registry.js";
 import { cellKey, type GridCell } from "./measurement-grid.js";
 import { defaultAddressSpaceLimit } from "./direct-limit.js";
 import { PROBE_OK } from "./probe-output.js";
@@ -36,7 +37,9 @@ export const NO_PRIVATE_SERVER = `${ADAPTER_HOST}.no-private-server`;
 const RECORD_SUFFIX = ".qualification.json";
 const SERVER_WAIT_MS = 5000;
 const SERVER_SETTLE_MS = 300;
-const SERVER_STOP_MS = 2000;
+// a TERM is waited for this long: jackd on a Pi can take seconds to end, and a jackd that is KILLed keeps its row in
+// JACK's server table for good (jack-registry.ts)
+const SERVER_STOP_MS = 10000;
 
 /** What a program answers to `--version`: its last word on the line that says `version`. */
 export function parseVersion(text: string): string | undefined {
@@ -78,14 +81,18 @@ const sleepSync = (ms: number): void => {
 /**
  * jackd under a shell that waits for it. A pass is synchronous, so this process cannot reap a child; an unreaped jackd
  * that had a client stays in JACK's server table as alive, and the next start under its name reads "server already active".
- * The shell outlives jackd whatever happens: a TERM reaches jackd once, and HUP is how a stop that gives up kills jackd alone.
- * Killed with its group, the shell could not reap it.
+ * The shell outlives jackd whatever happens: a TERM to the shell is passed to jackd's own pid, and HUP is how a stop that
+ * gives up kills jackd alone. Killed with its group, the shell could not reap it. A TERM to the group does not do: a jackd
+ * that is not its group's leader keeps running after it (measured on a Raspberry Pi 5 and on CI), and the stop's KILL then
+ * left its row in JACK's registry.
  */
-const REAPING_JACKD = `trap : TERM; trap 'kill -KILL $p 2>/dev/null' HUP; jackd "$@" & p=$!; while kill -0 $p 2>/dev/null; do wait $p; done`;
+const REAPING_JACKD = `trap 'kill -TERM $p 2>/dev/null' TERM; trap 'kill -KILL $p 2>/dev/null' HUP; jackd "$@" & p=$!; while kill -0 $p 2>/dev/null; do wait $p; done`;
 
 /** `jackd` on a name of its own and the dummy driver, at the cell's rate and quantum; `undefined` when none came up. */
 export const startPrivateJack: JackStarter = (cell) => {
   const name = `omx-qualify-${String(process.pid)}-${String(cell.quantum)}`;
+  // the rows of servers of ours that were killed, freed before this one asks for a row
+  freeDeadJackSlots();
   let child: ChildProcess;
   let ended = false;
   try {
@@ -110,7 +117,11 @@ export const startPrivateJack: JackStarter = (cell) => {
     }
   };
   const stop = (): void => {
-    signal("SIGTERM");
+    try {
+      if (child.pid !== undefined) process.kill(child.pid, "SIGTERM");
+    } catch {
+      // already gone
+    }
     const until = Date.now() + SERVER_STOP_MS;
     while (running() && Date.now() < until) sleepSync(20);
     if (running()) {
@@ -124,6 +135,8 @@ export const startPrivateJack: JackStarter = (cell) => {
     }
     signal("SIGKILL");
     for (const d of serverDirs(name)) rmSync(d, { recursive: true, force: true });
+    // a jackd that had to be KILLed left its row: it is freed now, not by the next start
+    freeDeadJackSlots();
   };
   const until = Date.now() + SERVER_WAIT_MS;
   while (Date.now() < until) {
@@ -187,6 +200,8 @@ export const mergeAdapterRun = (record: QualificationRecord, block: AdapterBlock
 export function adapterFinished(record: QualificationRecord, versions: Readonly<Record<string, string>>, cells: readonly GridCell[] = ADAPTER_PASS_CELLS): boolean {
   const a = record.adapter;
   if (a === undefined || !a.measured || a.versions === undefined || a.cells === undefined) return false;
+  // silence under the one key the run once played says nothing of a plugin that maps others: it is run again
+  if (a.cells.some((c) => c.code === ADAPTER_SILENT_CODE && c.params["notes"] === undefined)) return false;
   const same = Object.keys(versions).length === Object.keys(a.versions).length && Object.entries(versions).every(([k, v]) => a.versions![k] === v);
   return same && cells.every((c) => a.cells!.some((x) => cellKey(x) === cellKey(c)));
 }

package/src/qualify-isolated.ts

@@ -59,6 +59,8 @@ export interface IsolatedRunFacts {
   readonly xruns?: number;
   readonly finite?: boolean;
   readonly silent?: boolean;
+  /** How many of the plugin's MIDI inputs the notes were linked to; none for a plugin that has none. */
+  readonly midiInputsLinked?: number;
 }
 
 export type IsolatedRunner = (uri: string, cell: GridCell, env: Readonly<Record<string, string | undefined>>) => IsolatedRunFacts;
@@ -78,16 +80,20 @@ export function judgeIsolatedRun(run: IsolatedRunFacts): RunStep {
   if ((run.workers ?? 0) < 1) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.noWorker);
   if (run.workers !== 1 || run.instancesInWorker !== 1) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.notAlone);
   if (run.finite !== true) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.nonFinite);
-  if (run.silent !== false) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.silent);
+  if (run.silent !== false) {
+    const linked = run.midiInputsLinked;
+    return step(ISOLATED_RESULT.refused, ISOLATED_CODE.silent, linked === undefined ? undefined : linked === 0 ? "no note input to link: a sine played at its audio inputs" : `notes held on ${String(linked)} MIDI input${linked === 1 ? "" : "s"} and a sine at its audio inputs`);
+  }
   return step(ISOLATED_RESULT.isolated);
 }
 
 function figuresOf(run: IsolatedRunFacts): IsolatedFigures | undefined {
-  if (run.latencyFrames === undefined && run.cpuPercent === undefined && run.xruns === undefined) return undefined;
+  if (run.latencyFrames === undefined && run.cpuPercent === undefined && run.xruns === undefined && run.midiInputsLinked === undefined) return undefined;
   return {
     ...(run.latencyFrames === undefined ? {} : { latencyFrames: run.latencyFrames }),
     ...(run.cpuPercent === undefined ? {} : { cpuPercent: run.cpuPercent }),
     ...(run.xruns === undefined ? {} : { xruns: run.xruns }),
+    ...(run.midiInputsLinked === undefined ? {} : { midiInputsLinked: run.midiInputsLinked }),
   };
 }
 
@@ -191,8 +197,10 @@ function runIdOf(record: QualificationRecord, dir: string): string | undefined {
  */
 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, so a pass tries it again and it takes that one's place
-  if (!owesIsolated(record) || record.run?.steps.some((s) => isStep(s) && s.result !== ISOLATED_RESULT.notRun) === true) return undefined;
+  // 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;
   const id = runIdOf(record, join(path, ".."));
   if (id === undefined) return undefined;
   const step = judgeIsolatedRun(runner(uri, cell, env));

package/src/qualify-sync.ts

@@ -1218,6 +1218,53 @@ export function descriptorAccessProblems(dir: string): string[] {
   return problems;
 }
 
+/** What the records say per plugin, not per record: a CLAP plugin has a record per offer (.default, the console's
+ * in-process tier, and .custom, omx-clap-host's isolated tier), and is offered when any of its records is. */
+export interface PluginCounts {
+  readonly plugins: Readonly<Record<string, number>>;
+  readonly offered: Readonly<Record<string, number>>;
+  readonly notOffered: Readonly<Record<string, number>>;
+}
+
+export function pluginCounts(qualificationDir: string): PluginCounts {
+  const offeredBy = new Map<string, boolean>();
+  let files: string[] = [];
+  try {
+    files = readdirSync(qualificationDir).filter((f) => f.endsWith(".qualification.json"));
+  } catch {
+    // no directory, no record
+  }
+  for (const f of files) {
+    let r: { plugin?: { format?: string; id?: string }; tiers?: { offeredOn?: readonly string[] } };
+    try {
+      r = JSON.parse(readFileSync(join(qualificationDir, f), "utf8"));
+    } catch {
+      continue;
+    }
+    if (!r.plugin?.format || !r.plugin.id) continue;
+    const key = `${r.plugin.format}\0${r.plugin.id}`;
+    offeredBy.set(key, (offeredBy.get(key) ?? false) || (r.tiers?.offeredOn?.length ?? 0) > 0);
+  }
+  const plugins: Record<string, number> = {}, offered: Record<string, number> = {}, notOffered: Record<string, number> = {};
+  for (const [key, isOffered] of offeredBy) {
+    const format = key.split("\0")[0]!;
+    plugins[format] = (plugins[format] ?? 0) + 1;
+    const into = isOffered ? offered : notOffered;
+    into[format] = (into[format] ?? 0) + 1;
+  }
+  return { plugins, offered, notOffered };
+}
+
+/** The per-plugin counts as one line: `plugins 1577 (clap 248, lv2 1329), offered 1399 (...), not offered 178 (...)`. */
+export function pluginCountsLine(c: PluginCounts): string {
+  const part = (m: Readonly<Record<string, number>>): string => {
+    const keys = Object.keys(m).sort();
+    const total = keys.reduce((n, k) => n + m[k]!, 0);
+    return `${String(total)}${keys.length === 0 ? "" : ` (${keys.map((k) => `${k} ${String(m[k])}`).join(", ")})`}`;
+  };
+  return `plugins ${part(c.plugins)}, offered ${part(c.offered)}, not offered ${part(c.notOffered)}`;
+}
+
 export function summaryLine(s: SyncSummary): string {
   return `qualified ${String(s.qualified)}, skipped ${String(s.skipped)}, refused ${String(s.refused)}, crashed ${String(s.crashed)}, hung ${String(s.hung)}, unmeasured ${String(s.unmeasured)}, distributed ${String(s.distributed)}${s.refreshed ? `, pins refreshed ${String(s.refreshed)}` : ""}${s.rejudge === undefined ? "" : `, rejudged ${String(s.rejudge.changed)}, unchanged ${String(s.rejudge.unchanged)}, owing ${String(s.rejudge.owing)}`}${s.memoryOnly === undefined ? "" : `, memory measured ${String(s.memoryOnly.measured)}, already ${String(s.memoryOnly.already)}, failed ${String(s.memoryOnly.failed)}, leaks not measured`}${s.adapterOnly === undefined ? "" : `, adapter run ${String(s.adapterOnly.measured)}, already ${String(s.adapterOnly.already)}, failed ${String(s.adapterOnly.failed)}`}, ${s.seconds.toFixed(1)} s`;
 }

package/tools/isolated-step.mjs

@@ -107,6 +107,7 @@ async function main() {
     xruns: heard.xruns,
     finite: heard.finite,
     silent: heard.silent,
+    midiInputsLinked: heard.midiInputsLinked,
     ...(ticksBefore === undefined || ticksAfter === undefined ? {} : { cpuPercent: ((ticksAfter - ticksBefore) * 100000) / CLOCK_TICKS / windowMs }),
   };
 }

package/tools/mod-host-admit.mjs

@@ -18,9 +18,12 @@ const STEP_MS = Number(process.env.OMX_ADMIT_STEP_MS ?? 0) || 10000;
 const ADDRESS_KB = process.env.OMX_ADMIT_ADDRESS_KB;
 const STATE_DIR = process.env.OMX_ADMIT_STATE_DIR;
 const INSTANCE = 0;
-// an instrument under the adapter is played: one note, held this long, its output read at its JACK ports
+// an instrument under the adapter is played: a wide range of keys, since a drum kit answers only the ones it maps, each
+// held, then this long; its output is read at its JACK ports from before the first note, so a short hit counts
 const NOTE_WINDOW_MS = 1000;
-const NOTE_ON = `note_on ${INSTANCE} 0 60 100`;
+const NOTE_FIRST = 36; // the same keys as native/isolated-signal.c plays
+const NOTE_COUNT = 30;
+const NOTE_VELOCITY = 100;
 const ADAPTER = "omx-clap-host";
 const COMMANDS = [
   ["add", `add ${uri} ${INSTANCE}`],
@@ -133,9 +136,11 @@ async function main() {
         ports.length === 0
           ? { problem: "no output port" }
           : await peakDuring(ports, async () => {
-              await ask(NOTE_ON);
+              // a host that stops answering costs one budget, not one for each key
+              for (let k = 0; k < NOTE_COUNT; k++) if ((await ask(`note_on ${INSTANCE} 0 ${NOTE_FIRST + k} ${NOTE_VELOCITY}`)) === undefined) break;
               await sleep(NOTE_WINDOW_MS);
             });
+      if (sound.peak !== undefined) sound.notes = NOTE_COUNT;
     }
     buffer = "";
     sock.write(`${line}\0`);