@openmixer/plugin-qualify 0.18.4 → 0.19.1

package/src/qualify-sync.ts

@@ -24,21 +24,22 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 
 import { clapQualifyTools } from "./clap-qualify.js";
-import { DISTRIBUTED_DIR_SYSTEM, EMPTY_LAYER, applyDistributed, distributedUri, hostClassOfBoard, matchDistributed, readBoardModel, readDistributedLayer, type DistributedLayer } from "./distributed-records.js";
+import { DISTRIBUTED_DIR_SYSTEM, EMPTY_LAYER, applyDistributed, distributedUri, hostClassOfBoard, outcomeOfVerdict, matchDistributed, readBoardModel, readDistributedLayer, type DistributedLayer } from "./distributed-records.js";
 import { clapSearchPath, parseClapScan } from "./clap-loader.js";
 import { HOSTING_CODE } from "./hosting-codes.js";
 import { shippedHostProfile, type HostProfile } from "./host-profiles.js";
 import { lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
-import { judgmentPinEntries, pinsFile, type PinEntry } from "./pins-file.js";
+import { judgmentPinEntries, pinClearLine, pinLineUri, pinsFile, type PinEntry } from "./pins-file.js";
+import { POOL_RESULT, completePool, judgePoolRun, pinAfterPool, pinFromRecordWithPool, poolEnv, spawnedPoolRunner, type PoolRunner } from "./qualify-pool.js";
 import { hostdPinFiles, type PinFilesRun } from "./hostd-pin-files.js";
 import type { Judgment } from "./probe-judge.js";
 import { qualifyTargets, type ProbeRun } from "./probe-runner.js";
 import { GRID_FULL, parseGridSpec, type GridSpec } from "./measurement-grid.js";
 import { adapterPass, type AdapterPassOptions, type AdapterPassResult } from "./qualify-adapter-pass.js";
 import { ISOLATED_RESULT, baseSteps, completeIsolated, isolatedCell, missingSteps, judgeIsolatedRun, owesIsolated, pinAfterStep, spawnedIsolatedRunner, type IsolatedRunner } from "./qualify-isolated.js";
-import { lv2World, rejudgeState, memoryPass, type MemoryPassResult, type RejudgeResult } from "./qualify-rejudge.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 { rewriteRecord, writeQualification, type NotMeasured, type QualificationRecord } from "./qualification-record.js";
+import { QUALIFICATION_RECORD_SCHEMA, 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";
@@ -57,7 +58,7 @@ export const ZYNTHIAN_LV2_DIRS = ["/zynthian/zynthian-plugins/lv2", "/zynthian/z
 export interface SyncSetting {
   readonly key: string;
   readonly meaning: string;
-  /** The default as `--help` and the README print it. */
+  /** The default as `--help` and docs/overview.md print it. */
   readonly default: string;
 }
 
@@ -142,6 +143,8 @@ export interface SyncArgs {
   readonly adapterOnly: boolean;
   /** `--isolated-only`: the missing isolated step of each record already judged, extending its run. */
   readonly isolatedOnly: boolean;
+  /** `--pool-only`: the pool step of each CLAP record already judged that owes it, extending its run and giving its pin the word. */
+  readonly poolOnly: boolean;
   readonly help: boolean;
   /** The settings given as flags, by key. */
   readonly values: ReadonlyMap<string, string>;
@@ -162,6 +165,7 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
   let memoryOnly = false;
   let adapterOnly = false;
   let isolatedOnly = false;
+  let poolOnly = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -174,6 +178,7 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
     else if (a === "--memory-only") memoryOnly = true;
     else if (a === "--adapter-only") adapterOnly = true;
     else if (a === "--isolated-only") isolatedOnly = true;
+    else if (a === "--pool-only") poolOnly = true;
     else if (a === "--help") help = true;
     else if (a === "--grid-hosts") values.set("grid", "hosts");
     else if (a === "--config" || byFlag.has(a)) {
@@ -183,9 +188,9 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
       else values.set(byFlag.get(a)!, v);
     } else return { ok: false, error: `unknown argument ${a}` };
   }
-  if (rejudge && (memoryOnly || adapterOnly || isolatedOnly || force || refreshPinsOnly)) return { ok: false, error: "--rejudge measures nothing: it goes with none of --memory-only, --adapter-only, --force and --refresh-pins" };
-  if ([memoryOnly, adapterOnly, isolatedOnly, refreshPinsOnly].filter(Boolean).length > 1) return { ok: false, error: "--memory-only, --adapter-only and --refresh-pins are different runs: one at a time" };
-  return { ok: true, args: { ...(config === undefined ? {} : { config }), system, force, noDistributed, noWait, refreshPins: refreshPinsOnly, rejudge, memoryOnly, adapterOnly, isolatedOnly, help, values } };
+  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" };
+  return { ok: true, args: { ...(config === undefined ? {} : { config }), system, force, noDistributed, noWait, refreshPins: refreshPinsOnly, rejudge, memoryOnly, adapterOnly, isolatedOnly, poolOnly, help, values } };
 }
 
 export function syncHelpText(): string {
@@ -202,6 +207,7 @@ export function syncHelpText(): string {
     "  --rejudge                           derive every record's verdicts, tiers and pin again from the figures it holds; measures nothing",
     "  --memory-only                       measure only the footprint of each recorded plugin at the Pi's cells and merge it; with --force, those already merged too",
     "  --isolated-only                     run only the isolated step each record still owes, adding it to the record's run",
+    "  --pool-only                         run only the pool step each CLAP record still owes: a plugin that asks for the thread pool is run with it off and on, and its pin gets pool=cores or pool=off",
     "  --adapter-only                      run each LV2 plugin only under omx-clap-host's LV2 adapter at the Pi's cells, on private JACK servers, and merge it; with --force, those already done too",
     "  --grid-hosts                        the fast grid, the same as --grid hosts (7 cells with the shipped hosts)",
     "  --help                              this text",
@@ -522,6 +528,25 @@ export function machineReason(p: Pick<SyncPlugin, "outcome" | "code" | "detail">
   return /wrote no document|cannot run the probe runner/.test(p.detail ?? "") ? "the measurement wrote no document" : undefined;
 }
 
+/**
+ * The figure the records of a recorded entry never took, or `undefined`: a record whose probe ran before that figure's
+ * pass ({@link latencyNeverTaken}) owes a measurement, and the sync measures the entry again although its bytes are the
+ * ones it recorded. A record that cannot be read owes nothing here: the sync's other checks deal with it.
+ */
+export function figureOwed(entry: Pick<SyncEntry, "plugins">): "latency" | undefined {
+  for (const p of entry.plugins) {
+    if (p.record === undefined) continue;
+    let r: QualificationRecord;
+    try {
+      r = JSON.parse(readFileSync(p.record, "utf8")) as QualificationRecord;
+    } catch {
+      continue;
+    }
+    if (r.schema === QUALIFICATION_RECORD_SCHEMA && latencyNeverTaken(r)) return "latency";
+  }
+  return undefined;
+}
+
 /** What the quick qualification never measures, stated in every record it writes. */
 export const QUICK_NOT_MEASURED: readonly NotMeasured[] = [{ dimension: "stability", code: HOSTING_CODE.stabilityUnsoaked }];
 
@@ -621,6 +646,8 @@ export interface SyncContext {
   readonly pinFilesRun?: PinFilesRun;
   /** The isolated step, a stand-in in tests. */
   readonly isolatedRunner?: IsolatedRunner;
+  /** The pool step, a stand-in in tests. */
+  readonly poolRunner?: PoolRunner;
 }
 
 /**
@@ -738,6 +765,13 @@ function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgmen
         code = undefined;
       }
     }
+    // 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)));
+      steps.push(step);
+      pin = pinAfterPool(pin, step);
+    }
     rewriteRecord(recordPath, { ...record, run: { id: judgment.output.run.id, steps } });
     const plugin: SyncPlugin = { uri: pin?.uri ?? judgment.output.plugin.id, outcome, ...(code === undefined ? {} : { code }), ...(pin === undefined ? {} : { pin }), record: recordPath };
     return { plugin, judgedHere: judgment.hosts.some((h) => h.verdict.host === host) };
@@ -866,8 +900,8 @@ export function qualifyItem(ctx: SyncContext, item: SyncItem, files: readonly Fi
  * The isolated steps the records of a state still owe, each extending its record's run. A plugin's pin follows its step, and
  * a step that could not run stays owed: the next pass tries it again.
  */
-export function isolatedPass(ctx: SyncContext, state: SyncState): { readonly state: SyncState; readonly isolated: number; readonly refused: number; readonly notRun: number } {
-  const count = { isolated: 0, refused: 0, notRun: 0 };
+export function isolatedPass(ctx: SyncContext, state: SyncState): { readonly state: SyncState; readonly isolated: number; readonly refused: number; readonly notRun: number; readonly repinned: number } {
+  const count = { isolated: 0, refused: 0, notRun: 0, repinned: 0 };
   const runner = ctx.isolatedRunner ?? spawnedIsolatedRunner();
   const host = ctx.settings.hostProfile.id;
   const entries: Record<string, SyncEntry> = {};
@@ -885,7 +919,17 @@ export function isolatedPass(ctx: SyncContext, state: SyncState): { readonly sta
           return p;
         }
         const done = completeIsolated(path, record, p.pin?.uri ?? record.plugin.id, isolatedCell(record, host), runner, isolatedEnv(ctx));
-        if (done === undefined) return p;
+        if (done === undefined) {
+          // a plugin the isolated step already decided but the state holds no pin for: the record keeps the bytes and the
+          // step, and the pin follows them (hostd names the files, as at every other pin)
+          if (p.pin !== undefined) return p;
+          const rebuilt = withHostdFiles(ctx, pinFromRecordWithPool(record));
+          if (rebuilt === undefined) return p;
+          count.repinned++;
+          ctx.log(`${p.uri}: pinned again from its record (isolated step ${rebuilt.verdict ?? "undecided"})`);
+          const { code: _c, ...rest } = p;
+          return rest.outcome === "qualified" && rebuilt.verdict === "refused" ? { ...rest, outcome: "refused" as const, pin: rebuilt } : { ...rest, pin: rebuilt };
+        }
         ctx.log(`${p.uri}: isolated step ${done.step.result}${done.step.code === undefined ? "" : ` (${done.step.code})`}`);
         const pin = pinAfterStep(p.pin, done.step);
         const { pin: _pin, code: _code, ...rest } = p;
@@ -899,7 +943,44 @@ export function isolatedPass(ctx: SyncContext, state: SyncState): { readonly sta
       }),
     };
   }
-  return { ...count, state: count.isolated + count.refused + count.notRun === 0 ? state : { ...state, entries } };
+  return { ...count, state: count.isolated + count.refused + count.notRun + count.repinned === 0 ? state : { ...state, entries } };
+}
+
+/**
+ * The pool steps the CLAP records of a state still owe, each extending its record's run. A plugin's pin takes the pool word
+ * of its step (`cores`, or `off` for a plugin that was measured and gains nothing) and none for a plugin that does not ask
+ * for the pool. A step that could not run stays owed: the next pass tries it again.
+ */
+export function poolPass(ctx: SyncContext, state: SyncState): { readonly state: SyncState; readonly cores: number; readonly off: number; readonly notAsked: number; readonly notRun: number } {
+  const count = { cores: 0, off: 0, notAsked: 0, notRun: 0 };
+  const runner = ctx.poolRunner ?? spawnedPoolRunner();
+  const host = ctx.settings.hostProfile.id;
+  const entries: Record<string, SyncEntry> = {};
+  for (const [key, entry] of Object.entries(state.entries)) {
+    entries[key] = {
+      ...entry,
+      plugins: entry.plugins.map((p) => {
+        if (p.record === undefined || !p.record.endsWith(".qualification.json") || p.pin === undefined || p.pin.verdict === "refused") return p;
+        const path = join(ctx.settings.qualificationDir, basename(p.record));
+        let record: QualificationRecord;
+        try {
+          record = JSON.parse(readFileSync(path, "utf8")) as QualificationRecord;
+        } catch {
+          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));
+        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++;
+        else if (done.step.result === POOL_RESULT.off) count.off++;
+        else if (done.step.result === POOL_RESULT.notAsked) count.notAsked++;
+        else count.notRun++;
+        return { ...p, pin: pinAfterPool(p.pin, done.step)! };
+      }),
+    };
+  }
+  return { ...count, state: count.cores + count.off + count.notAsked + count.notRun === 0 ? state : { ...state, entries } };
 }
 
 // --- the distributed records ----------------------------------------------------------------------------------------
@@ -938,10 +1019,35 @@ function takeDistributed(ctx: SyncContext, layer: DistributedLayer, item: SyncIt
       ctx.log(`distributed: ${distributedUri(item, r)}: its record lacks the step${missing.length === 1 ? "" : "s"} ${missing.join(", ")}; measured here`);
       return undefined;
     }
+    if (latencyNeverTaken(r.record)) {
+      ctx.log(`distributed: ${distributedUri(item, r)}: its record never took the latency figure (a probe from before that pass); measured here`);
+      return undefined;
+    }
+  }
+  // The set was judged by the plugin-qualify that measured it. Its figures are carried across and judged again under
+  // today's rules, as an upgrade's are (`--rejudge`): a verdict of an older judge (RT-unsafe read as refused, before
+  // #196) is never taken as it stands. A record today's judge cannot decide for this host is measured here.
+  const by = rejudgeToolName();
+  const at = new Date(started).toISOString();
+  const records = [];
+  for (const r of match.records) {
+    let record: QualificationRecord;
+    try {
+      record = rejudgeRecord(r.record, readFileSync(join(r.path, "..", r.record.probe.file)), { host, by, at }).record;
+    } catch (e) {
+      ctx.log(`distributed: ${distributedUri(item, r)}: ${(e as Error).message}; measured here`);
+      return undefined;
+    }
+    const v = record.verdicts.find((x) => x.host === host);
+    if (v !== undefined && outcomeOfVerdict(v) === "unmeasured") {
+      ctx.log(`distributed: ${distributedUri(item, r)}: judged again, ${v.deciding ?? "unknown"} for ${host}; measured here`);
+      return undefined;
+    }
+    records.push({ ...r, record });
   }
   let plugins: SyncPlugin[];
   try {
-    plugins = applyDistributed(ctx.settings.qualificationDir, item, match, host);
+    plugins = applyDistributed(ctx.settings.qualificationDir, item, { ...match, records }, host);
   } catch (e) {
     ctx.log(`distributed: ${distributedUri(item, match.records[0]!)}: ${(e as Error).message}; measured here`);
     return undefined;
@@ -980,7 +1086,7 @@ export function syncPinsText(state: SyncState): string {
 /** The pin lines, by uri. */
 function pinLinesOf(text: string): Map<string, string> {
   const out = new Map<string, string>();
-  for (const line of text.split("\n")) if (line !== "" && !line.startsWith("#")) out.set(line.split(" ")[1]!, line);
+  for (const line of text.split("\n")) if (line !== "" && !line.startsWith("#")) out.set(pinLineUri(line)!, line);
   return out;
 }
 
@@ -1181,6 +1287,8 @@ export interface SyncSummary {
   readonly machineFailure?: string;
   /** `--isolated-only`: how the steps ended. */
   readonly isolatedOnly?: { readonly isolated: number; readonly refused: number; readonly notRun: number };
+  /** `--pool-only`: the plugins granted the thread pool, those measured and not granted it, those that do not ask for it, and those the step could not run for. */
+  readonly poolOnly?: { readonly cores: number; readonly off: number; readonly notAsked: number; readonly notRun: number };
   /** `--adapter-only`: the plugins run, those done already at these host versions, and those whose host could not be run. */
   readonly adapterOnly?: { readonly measured: number; readonly already: number; readonly failed: number };
 }
@@ -1218,8 +1326,55 @@ 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`;
+  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.poolOnly === undefined ? "" : `, pool granted ${String(s.poolOnly.cores)}, off ${String(s.poolOnly.off)}, not asked ${String(s.poolOnly.notAsked)}, not run ${String(s.poolOnly.notRun)}`}${s.adapterOnly === undefined ? "" : `, adapter run ${String(s.adapterOnly.measured)}, already ${String(s.adapterOnly.already)}, failed ${String(s.adapterOnly.failed)}`}, ${s.seconds.toFixed(1)} s`;
 }
 
 /** The exit status `flock -n` returns when the lock is held (-E), told apart from a failure of flock itself. */
@@ -1273,6 +1428,10 @@ export interface SyncRunOptions {
   readonly isolatedRunner?: IsolatedRunner;
   /** `--isolated-only`: take only the isolated steps records still owe. */
   readonly isolatedOnly?: boolean;
+  /** The pool step, a stand-in in tests. */
+  readonly poolRunner?: PoolRunner;
+  /** `--pool-only`: take only the pool steps records still owe. */
+  readonly poolOnly?: boolean;
   /** `--adapter-only`: take only the adapter runs; `force` takes those already done again. */
   readonly adapterOnly?: boolean;
   /** Stand-ins for the pass's hosts, in tests. */
@@ -1341,6 +1500,7 @@ function addSummaries(a: SyncSummary, b: SyncSummary): SyncSummary {
     ...(b.rejudge === undefined ? (a.rejudge === undefined ? {} : { rejudge: a.rejudge }) : { rejudge: b.rejudge }),
     ...(b.memoryOnly === undefined ? (a.memoryOnly === undefined ? {} : { memoryOnly: a.memoryOnly }) : { memoryOnly: b.memoryOnly }),
     ...(b.isolatedOnly === undefined ? (a.isolatedOnly === undefined ? {} : { isolatedOnly: a.isolatedOnly }) : { isolatedOnly: b.isolatedOnly }),
+    ...(b.poolOnly === undefined ? (a.poolOnly === undefined ? {} : { poolOnly: a.poolOnly }) : { poolOnly: b.poolOnly }),
     ...(b.adapterOnly === undefined ? (a.adapterOnly === undefined ? {} : { adapterOnly: a.adapterOnly }) : { adapterOnly: b.adapterOnly }),
   };
 }
@@ -1366,7 +1526,7 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
   {
     const started = Date.now();
     const dirs = [...settings.clapDirs, ...settings.lv2Dirs];
-    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }), ...(options.isolatedRunner === undefined ? {} : { isolatedRunner: options.isolatedRunner }) };
+    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }), ...(options.isolatedRunner === undefined ? {} : { isolatedRunner: options.isolatedRunner }), ...(options.poolRunner === undefined ? {} : { poolRunner: options.poolRunner }) };
     // the pins first, before the quiet wait and any measurement: an upgrade of plugin-hostd that collects more files
     // than the pins on disk hold refuses those plugins until their pins name them (plugin-qualify#239)
     const fresh = refreshPins(ctx, readSyncState(settings.stateFile, log));
@@ -1386,6 +1546,12 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       const summary = await sendRefreshed(settings, r.state, fresh.refreshed.length, started, log);
       return { ...summary, isolatedOnly: { isolated: r.isolated, refused: r.refused, notRun: r.notRun } };
     }
+    if (options.poolOnly === true) {
+      const r = poolPass(ctx, fresh.state);
+      if (r.state !== fresh.state) writeFileWhole(settings.stateFile, `${JSON.stringify(r.state, null, 1)}\n`);
+      const summary = await sendRefreshed(settings, r.state, fresh.refreshed.length, started, log);
+      return { ...summary, poolOnly: { cores: r.cores, off: r.off, notAsked: r.notAsked, notRun: r.notRun } };
+    }
     if (options.adapterOnly === true) {
       const r: AdapterPassResult = adapterPass(ctx, fresh.state, { ...options.adapterPass, force: options.force === true });
       log(`adapter runs under ${Object.entries(r.versions).map(([k, v]) => `${k} ${v}`).join(", ")}`);
@@ -1433,7 +1599,8 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       for (const item of items) {
         const recorded = recordedAsIs(item, entries[item.key]);
         const retry = recorded.same ? entries[item.key]!.plugins.map(machineReason).find((r) => r !== undefined) : undefined;
-        if (recorded.same && options.force !== true && retry === undefined) {
+        const owed = recorded.same && options.force !== true && retry === undefined ? figureOwed(entries[item.key]!) : undefined;
+        if (recorded.same && options.force !== true && retry === undefined && owed === undefined) {
           if (pass === 0) count.skipped += entries[item.key]!.plugins.length;
           continue;
         }
@@ -1451,6 +1618,7 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
           continue;
         }
         if (recorded.same && retry !== undefined) log(`${item.key}: unmeasured last run by the machine (${retry}); measured again`);
+        if (owed !== undefined) log(`${item.key}: its record never took the ${owed} figure (a probe from before that pass); measured again`);
         const files = recorded.files ?? digestFiles(item.root, item.files);
         if (files === undefined) {
           log(`${item.key}: a file of it cannot be read; skipped this run`);
@@ -1497,7 +1665,7 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
     if (unreadable) log("a plugin directory could not be read; no record or descriptor is removed this run");
     else for (const f of pruneStale(settings, stateBefore, state)) log(`${f}: removed, its plugin is gone or changed`);
     // a plugin that was pinned and is not any more is also forgotten by a running daemon
-    const changed = [...changedPinLines(before, after), ...removedPinUris(before, after).map((uri) => `pin_clear ${uri}`)];
+    const changed = [...changedPinLines(before, after), ...removedPinUris(before, after).map(pinClearLine)];
     const sent = await sendPins(settings.hostdPort, settings.hostdFeedbackPort, changed);
     if ("unsent" in sent) {
       const why = {
@@ -1508,7 +1676,7 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       log(`${why}; the ${String(changed.length)} changed pins apply at its next start, from the pin file`);
     }
     const replies = "replies" in sent ? sent.replies : [];
-    for (let i = 0; i < replies.length; i++) if (replies[i] !== "resp 0") log(`plugin-hostd answered ${replies[i]!} to ${changed[i]!.split(" ")[1]!}`);
+    for (let i = 0; i < replies.length; i++) if (replies[i] !== "resp 0") log(`plugin-hostd answered ${replies[i]!} to ${pinLineUri(changed[i]!)!}`);
     const taken = replies.filter((r) => r === "resp 0").length;
     for (const [why, n] of byMachine) if (n > 1) log(`${String(n)} plugins unmeasured by the machine (${why}); the first is listed above`);
     const [only] = byMachine.size === 1 ? [...byMachine] : [];

package/src/records-package.ts

@@ -4,7 +4,8 @@
  * `plugin-qualify-records-package`: the Debian package of a device's qualification records, so other devices of the
  * machine class install them as the distributed layer instead of measuring the same plugin set again.
  *
- * In: a qualification directory as plugin-qualify-sync leaves it. Out: `omx-qualification-<class>-<set>_<version>_all.deb`
+ * In: a qualification directory as plugin-qualify-sync leaves it. Out: `plugin-db-qualification-<class>-<set>_<version>_all.deb`,
+ * a package of plugin-db's qualification layer,
  * installing every record and the probe output it judged under `/usr/share/omx/qualification/<class>/<set>/`, beside
  * the set's `provenance.json`. A record goes in only with its probe output, byte for byte the copy the record names;
  * an unmeasured record never applies and stays out. The archive is written here, `ar` and two `tar.xz` members, so a
@@ -16,7 +17,7 @@ import { closeSync, copyFileSync, mkdirSync, mkdtempSync, openSync, readFileSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { DISTRIBUTED_DIR_SYSTEM, DISTRIBUTED_LAYER_SINCE, DISTRIBUTED_PROVENANCE_FILE, DISTRIBUTED_PROVENANCE_SCHEMA, type DistributedProvenance } from "./distributed-records.js";
+import { DISTRIBUTED_DIR_SYSTEM, DISTRIBUTED_PROVENANCE_FILE, DISTRIBUTED_PROVENANCE_SCHEMA, type DistributedProvenance } from "./distributed-records.js";
 import { sha256Hex } from "./probe-output.js";
 import { QUALIFICATION_RECORD_SCHEMA } from "./qualification-record.js";
 
@@ -53,7 +54,7 @@ export function recordsPackageHelp(): string {
     "  --maintainer <who>       the package's Maintainer field",
     "  --help                   this text",
     "",
-    `the package installs ${DISTRIBUTED_DIR_SYSTEM}/<class>/<set>/ and depends on plugin-qualify (>= ${DISTRIBUTED_LAYER_SINCE})`,
+    `the package installs ${DISTRIBUTED_DIR_SYSTEM}/<class>/<set>/ and depends on this plugin-qualify's minor, up to the next one`,
     "exit 0 the package was written, 2 it could not be",
     "",
   ].join("\n");
@@ -97,7 +98,21 @@ export function parseRecordsPackageArgs(argv: readonly string[]): { ok: true; ar
 }
 
 /** The package of a class and a set. */
-export const recordsPackageName = (hostClass: string, set: string): string => `omx-qualification-${hostClass}-${set}`;
+export const recordsPackageName = (hostClass: string, set: string): string => `plugin-db-qualification-${hostClass}-${set}`;
+
+/** The plugin-qualify a package of records depends on: the minor that wrote them, up to the next minor. */
+export function recordsDependsRange(version: string): { floor: string; ceiling: string } | undefined {
+  const m = /^(\d+)\.(\d+)\.\d+/.exec(version);
+  if (m === null) return undefined;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  return { floor: `${String(major)}.${String(minor)}.0`, ceiling: `${String(major)}.${String(minor + 1)}` };
+}
+
+/** This plugin-qualify's own version, read where it is installed. */
+function ownVersion(): string {
+  return (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: string }).version ?? "";
+}
 
 /** Today as a package version, `2026.10.29`, and as a date, `2026-10-29`, in local time. */
 export function today(now = new Date()): { version: string; date: string } {
@@ -199,6 +214,8 @@ export interface BuiltRecordsPackage {
 /** The package of `args`, written into `args.out`. Throws, naming why, when it cannot be built. */
 export function buildRecordsPackage(args: RecordsPackageArgs, now = new Date()): BuiltRecordsPackage {
   const name = recordsPackageName(args.hostClass, args.set);
+  const range = recordsDependsRange(ownVersion());
+  if (range === undefined) throw new Error("this plugin-qualify names no version, so the package cannot say which one reads it");
   const day = today(now);
   const version = args.version ?? day.version;
   statSync(args.stateDir);
@@ -238,13 +255,13 @@ export function buildRecordsPackage(args: RecordsPackageArgs, now = new Date()):
         "Architecture: all",
         `Maintainer: ${args.maintainer}`,
         `Installed-Size: ${String(kib)}`,
-        `Depends: plugin-qualify (>= ${DISTRIBUTED_LAYER_SINCE}~)`,
+        `Depends: plugin-qualify (>= ${range.floor}~), plugin-qualify (<< ${range.ceiling}~)`,
         "Section: sound",
         "Priority: optional",
         "Multi-Arch: foreign",
-        `Description: qualification records of the ${args.set} plugin set for ${args.hostClass}`,
-        ` The plugin-qualify records of the ${args.set} plugin set, measured on a`,
-        ` ${args.hostClass} device. plugin-qualify-sync takes a plugin from them instead of`,
+        `Description: plugin-db qualification layer: ${args.set} set for ${args.hostClass}`,
+        ` The qualification layer of the plugin database: the plugin-qualify records`,
+        ` of the ${args.set} plugin set, measured on a ${args.hostClass} device. plugin-qualify-sync takes a plugin from them instead of`,
         " measuring it, and only when every file of the installed plugin hashes as the",
         " measured one did; any other plugin is measured on the device as before.",
         "",

package/tools/benchmark.py

@@ -1201,7 +1201,9 @@ class _Host:
     def __init__(self, rate, block):
         import ctypes
 
-        import lilv
+        from lilv_load import load_lilv
+
+        lilv = load_lilv()
 
         self.urids = {}
 
@@ -1362,7 +1364,9 @@ def probe_one(host, uri, symbol, cycles=DEFAULT_RUN_CYCLES):
     """
     import numpy as np
 
-    import lilv
+    from lilv_load import load_lilv
+
+    lilv = load_lilv()
 
     plugin = host.world.get_all_plugins().get_by_uri(host.world.new_uri(uri))
     if plugin is None:
@@ -1453,7 +1457,9 @@ def instantiate_connected(host, plugin, overrides=None):
     """
     import numpy as np
 
-    import lilv
+    from lilv_load import load_lilv
+
+    lilv = load_lilv()
 
     host.worker.reset()
     instance = lilv.Instance(plugin, float(host.rate), host.features)