@openmixer/plugin-qualify 0.17.5 → 0.18.1

package/src/qualify-sync.ts

@@ -18,10 +18,10 @@
  */
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createConnection } from "node:net";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+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";
@@ -32,11 +32,13 @@ import { lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
 import { judgmentPinEntries, pinsFile, type PinEntry } from "./pins-file.js";
 import { hostdPinFiles, type PinFilesRun } from "./hostd-pin-files.js";
 import type { Judgment } from "./probe-judge.js";
-import { qualifyTargets } from "./probe-runner.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 { lv2World, rejudgeState, memoryPass, type MemoryPassResult, type RejudgeResult } from "./qualify-rejudge.js";
 import { memoryBoundOf, parseMemoryLimit, type MemoryBound } from "./memory-bound.js";
 import { writeQualification, type NotMeasured } from "./qualification-record.js";
-import { DESCRIPTOR_DIR_STATE_SUBDIR, DESCRIPTOR_DIR_SYSTEM, QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
+import { 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";
 
@@ -73,6 +75,7 @@ export const SYNC_SETTINGS: readonly SyncSetting[] = [
   { key: "grid", meaning: "the cells measured: full (every rate at every block size, 16 cells), hosts (the fast option: the host's and the console tiers' rate/quantum, then 512 at every rate; also --grid-hosts), or <rate>/<quantum>,...", default: "full" },
   { key: "cells_per_plugin_budget", meaning: "measure at most the first n cells of the grid a plugin; 0 is every cell", default: "0" },
   { key: "memory_limit", meaning: "the memory bound of every run: bytes, or with K, M, G; off for none; past it a cell is probe.oom", default: "half of the RAM" },
+  { key: "memory_notes", meaning: "the notes an instrument that declares no voice capacity holds in a --memory-only run, 1 to 128 (basis probe)", default: String(MEMORY_PASS_PROBE_NOTES) },
   { key: "hostd_port", meaning: "plugin-hostd's command port the new pins are sent to; 0 sends none", default: "5555" },
   { key: "hostd_feedback_port", meaning: "plugin-hostd's feedback port, connected before the command port; 0 is the command port's next", default: "0" },
   { key: "settle_s", meaning: "wait until the plugin directories have been quiet this long before a run", default: "0" },
@@ -94,6 +97,8 @@ export interface SyncSettings {
   readonly cellsPerPluginBudget: number;
   /** The memory bound of every run; `undefined` is `off`. */
   readonly memory?: MemoryBound;
+  /** The notes an instrument with no declared capacity holds in a memory-only run. */
+  readonly memoryNotes: number;
   readonly hostdPort: number;
   readonly hostdFeedbackPort: number;
   readonly settleS: number;
@@ -128,6 +133,12 @@ export interface SyncArgs {
   readonly noWait: boolean;
   /** `--refresh-pins`: refresh the pins' files from plugin-hostd and measure nothing (the package's upgrade runs it). */
   readonly refreshPins: boolean;
+  /** `--rejudge`: the verdicts, tiers and pins derived again from the records' figures, measuring nothing. */
+  readonly rejudge: boolean;
+  /** `--memory-only`: the footprint of each recorded plugin at the Pi's cells, merged into its record. */
+  readonly memoryOnly: boolean;
+  /** `--adapter-only`: the run of each LV2 plugin under the adapter at the Pi's cells, merged into its record. */
+  readonly adapterOnly: boolean;
   readonly help: boolean;
   /** The settings given as flags, by key. */
   readonly values: ReadonlyMap<string, string>;
@@ -144,6 +155,9 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
   let noDistributed = false;
   let noWait = false;
   let refreshPinsOnly = false;
+  let rejudge = false;
+  let memoryOnly = false;
+  let adapterOnly = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -152,6 +166,9 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
     else if (a === "--no-distributed") noDistributed = true;
     else if (a === "--no-wait") noWait = true;
     else if (a === "--refresh-pins") refreshPinsOnly = true;
+    else if (a === "--rejudge") rejudge = true;
+    else if (a === "--memory-only") memoryOnly = true;
+    else if (a === "--adapter-only") adapterOnly = true;
     else if (a === "--help") help = true;
     else if (a === "--grid-hosts") values.set("grid", "hosts");
     else if (a === "--config" || byFlag.has(a)) {
@@ -161,7 +178,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}` };
   }
-  return { ok: true, args: { ...(config === undefined ? {} : { config }), system, force, noDistributed, noWait, refreshPins: refreshPinsOnly, help, values } };
+  if (rejudge && (memoryOnly || adapterOnly || 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, 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, help, values } };
 }
 
 export function syncHelpText(): string {
@@ -175,6 +194,9 @@ export function syncHelpText(): string {
     "  --no-wait                           a run in progress is not waited for: exit 0, and the holder runs once more at its end",
     "  --no-distributed                    read no distributed record: every plugin not recorded is measured",
     "  --refresh-pins                      only bring every pin's files up to the ones plugin-hostd names, measuring nothing",
+    "  --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",
+    "  --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",
     ...rows,
@@ -226,6 +248,8 @@ export function resolveSyncSettings(
   const memoryLimit = memoryText === undefined || memoryText === "" ? undefined : parseMemoryLimit(memoryText);
   if (memoryLimit !== undefined && !memoryLimit.ok) return { ok: false, error: `memory_limit: ${memoryLimit.error}` };
   const memory = memoryBoundOf(memoryLimit?.bytes);
+  const memoryNotes = number("memory_notes", 1);
+  if (memoryNotes === undefined || !Number.isInteger(memoryNotes) || memoryNotes > 128) return { ok: false, error: "memory_notes must be a whole number of notes, 1 to 128" };
   const profileId = get("host_profile") || "omx-clap-host";
   const hostProfile = shippedHostProfile(profileId);
   if (hostProfile === undefined) return { ok: false, error: `host_profile ${profileId} is not a shipped host profile` };
@@ -256,6 +280,7 @@ export function resolveSyncSettings(
       grid: grid.spec,
       cellsPerPluginBudget,
       ...(memory === undefined ? {} : { memory }),
+      memoryNotes,
       hostdPort,
       hostdFeedbackPort: feedbackPort === 0 && hostdPort !== 0 ? hostdPort + 1 : feedbackPort,
       settleS,
@@ -279,6 +304,40 @@ export interface SyncItem {
   readonly files: readonly string[];
   /** The LV2 plugin's uri. */
   readonly uri?: string;
+  /** The LV2 plugin's binary as lilv loads it, an absolute path that may lie outside `root` (a complement's). */
+  readonly binary?: string;
+}
+
+/** One LV2 plugin as lilv resolves it over the whole search path: the bundle its version rule takes, and its binary. */
+export interface Lv2Resolved {
+  readonly uri: string;
+  readonly bundle: string;
+  readonly binary?: string | null;
+}
+
+/** The bundles lilv takes over `dirs`, or why it could not say. A stand-in in tests. */
+export type Lv2Resolve = (dirs: readonly string[]) => readonly Lv2Resolved[] | { readonly problem: string };
+
+/** lilv itself, one world over the whole search path (tools/lv2_resolve.py), as every host built on it resolves (#199). */
+export const LILV_RESOLVE: Lv2Resolve = (dirs) => {
+  const r = spawnSync("python3", [join(toolsDir(), "lv2_resolve.py")], {
+    encoding: "utf8", timeout: 120_000, killSignal: "SIGKILL", maxBuffer: 64 << 20, env: { ...process.env, LV2_PATH: dirs.join(":") },
+  });
+  if (r.error !== undefined || r.status !== 0) return { problem: (r.stderr ?? "").trim().split("\n").pop() || (r.error?.message ?? `exit ${String(r.status)}`) };
+  try {
+    return (JSON.parse(r.stdout) as { plugins: Lv2Resolved[] }).plugins;
+  } catch (e) {
+    return { problem: `lv2_resolve.py printed no JSON: ${(e as Error).message}` };
+  }
+};
+
+/** Whether `path` exists and is, through its links, the file `target` is. */
+function linksTo(path: string, target: string): boolean {
+  try {
+    return realpathSync(path) === realpathSync(target);
+  } catch {
+    return false;
+  }
 }
 
 const CLAP_SUFFIX = ".clap";
@@ -322,9 +381,13 @@ function clapFiles(dir: string, seen: Set<string>, problems: string[]): string[]
  * LV2 directories that declares it, as plugin-hostd finds it. A directory that cannot be read is a problem named, and
  * the others are still walked.
  */
-export function discoverSyncItems(settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">): { items: SyncItem[]; problems: string[] } {
+export function discoverSyncItems(
+  settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">,
+  lv2Resolve?: Lv2Resolve,
+): { items: SyncItem[]; problems: string[]; notes: string[] } {
   const items: SyncItem[] = [];
   const problems: string[] = [];
+  const notes: string[] = [];
   const seen = new Set<string>();
   const clap = new Set<string>();
   for (const dir of settings.clapDirs) {
@@ -335,6 +398,11 @@ export function discoverSyncItems(settings: Pick<SyncSettings, "lv2Dirs" | "clap
       items.push({ key: `clap:${path}`, format: "clap", root: dirname(path), files: [basename(path)] });
     }
   }
+  // the bundle lilv takes for each plugin uri; without lilv, the first bundle found (and the log says so)
+  const resolved = lv2Resolve === undefined || settings.lv2Dirs.length === 0 ? undefined : lv2Resolve(settings.lv2Dirs);
+  const taken = new Map<string, Lv2Resolved>();
+  if (resolved !== undefined && "problem" in resolved) notes.push(`lilv could not resolve the LV2 plugins (${resolved.problem}); each is keyed by the first bundle found`);
+  else if (resolved !== undefined) for (const p of resolved) taken.set(p.uri, p);
   const lv2 = new Set<string>();
   for (const dir of settings.lv2Dirs) {
     let bundles: string[];
@@ -353,13 +421,20 @@ export function discoverSyncItems(settings: Pick<SyncSettings, "lv2Dirs" | "clap
         continue;
       }
       for (const p of manifestPlugins(ttl)) {
+        const lilv = taken.get(p.uri);
+        // lilv takes another bundle for this uri: this one is not the plugin a host loads
+        if (lilv !== undefined && resolve(lilv.bundle) !== resolve(bundle)) continue;
         if (lv2.has(p.uri)) continue;
         lv2.add(p.uri);
-        items.push({ key: `lv2:${p.uri}`, format: "lv2", root: bundle, files: ["manifest.ttl", ...p.files.filter((f) => f !== "manifest.ttl")], uri: p.uri });
+        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));
+        items.push({ key: `lv2:${p.uri}`, format: "lv2", root: bundle, files, uri: p.uri, ...(binary === undefined ? {} : { binary }) });
       }
     }
   }
-  return { items, problems };
+  return { items, problems, notes };
 }
 
 // --- the file set -----------------------------------------------------------------------------------------------------
@@ -428,6 +503,19 @@ export const SYNC_CODE = {
   notMeasured: "qualify.sync.not-measured",
 } as const;
 
+/**
+ * Why a plugin is unmeasured because of the machine it ran on rather than what it is (#192): an EACCES, EPERM or
+ * ENOSPC the run hit, or a measurement that could not run or wrote no document. Such a plugin is measured again by
+ * the next run although its files are unchanged; a reason of the plugin's own (probe.limit.not-implemented, no such
+ * plugin, a crash) is not. `undefined` for every other outcome.
+ */
+export function machineReason(p: Pick<SyncPlugin, "outcome" | "code" | "detail">): string | undefined {
+  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;
+  return /wrote no document|cannot run the probe runner/.test(p.detail ?? "") ? "the measurement wrote no document" : 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 }];
 
@@ -495,6 +583,28 @@ export function recordedAsIs(item: SyncItem, entry: SyncEntry | undefined): { sa
   return { same, files: now };
 }
 
+/**
+ * The entry of an LV2 plugin a host now loads from another bundle than it was qualified in, when its binary is the
+ * same bytes (#199): the entry with the new bundle and the new bundle's file digests, its verdicts and records kept.
+ * `undefined` when the item is not that case: not LV2, no entry, the same bundle, a binary that cannot be read, or one
+ * whose bytes differ from the recorded binary's (then it is measured again).
+ */
+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!));
+  if (was === undefined) return undefined;
+  let now: string;
+  try {
+    now = fileSha256(item.binary);
+  } catch {
+    return undefined;
+  }
+  if (now !== was.sha256) return undefined;
+  const files = digestFiles(item.root, item.files);
+  if (files === undefined) return undefined;
+  return { ...entry, root: item.root, files };
+}
+
 // --- one item ---------------------------------------------------------------------------------------------------------
 
 export interface SyncContext {
@@ -693,14 +803,10 @@ function qualifyClap(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
 
 /** An LV2 plugin, measured in a world of its own bundle only, as plugin-hostd runs a pinned LV2 plugin. */
 function qualifyLv2(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
-  const world = mkdtempSync(join(tmpdir(), "plugin-qualify-sync-world-"));
-  try {
-    symlinkSync(item.root, join(world, basename(item.root)));
+  return lv2World(item.root, (world) => {
     const pass = runPass(ctx, { format: "lv2", uri: item.uri!, bundle: item.root }, { ...ctx.env, LV2_PATH: world });
     return [...pass.failures.map((f): SyncPlugin => ({ uri: item.uri!, outcome: "unmeasured", code: SYNC_CODE.notMeasured, detail: f.problem })), ...judgedPlugins(ctx, pass.runs)];
-  } finally {
-    rmSync(world, { recursive: true, force: true });
-  }
+  });
 }
 
 /** One item qualified, whatever happens to it: an error of the sync's own while measuring it is its outcome, not the run's end. */
@@ -984,6 +1090,14 @@ export interface SyncSummary {
   readonly sent?: number;
   /** The pins whose files were refreshed from plugin-hostd without a measurement (plugin-qualify#239). */
   readonly refreshed?: number;
+  /** `--rejudge`: the records whose verdicts changed, the ones that stood, and the ones that owe a measurement. */
+  readonly rejudge?: { readonly changed: number; readonly unchanged: number; readonly owing: number };
+  /** `--memory-only`: the plugins measured, those whose footprints were already merged, and those no run could read. */
+  readonly memoryOnly?: { readonly measured: number; readonly already: number; readonly failed: number };
+  /** Every plugin the run measured was unmeasured for this one reason of the machine ({@link machineReason}): the run failed. */
+  readonly machineFailure?: string;
+  /** `--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 };
 }
 
 /**
@@ -1020,7 +1134,7 @@ export function descriptorAccessProblems(dir: string): string[] {
 }
 
 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.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.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. */
@@ -1066,8 +1180,20 @@ export interface SyncRunOptions {
   readonly force?: boolean;
   /** `--refresh-pins`: only refresh the pins' files from plugin-hostd and send the changed ones; measure nothing. */
   readonly refreshOnly?: boolean;
+  /** `--rejudge`: derive the verdicts again from the records' figures; measure nothing. */
+  readonly rejudge?: boolean;
+  /** `--memory-only`: take only the footprints; `force` takes those already merged again. */
+  readonly memoryOnly?: 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. */
+  readonly adapterPass?: AdapterPassOptions;
   /** The run of `plugin-hostd --pin-files`, a stand-in in tests. */
   readonly pinFilesRun?: PinFilesRun;
+  /** The run of the probe runner in a memory-only pass, a stand-in in tests. */
+  readonly probeRun?: ProbeRun;
+  /** How LV2 plugins are resolved to the bundle a host loads: lilv itself unless a test stands in (#199). */
+  readonly lv2Resolve?: Lv2Resolve;
   /** False under `--no-wait`: a run in progress is not waited for; the holder runs once more at its end instead. */
   readonly wait?: boolean;
   readonly env?: Readonly<Record<string, string | undefined>>;
@@ -1123,9 +1249,21 @@ function addSummaries(a: SyncSummary, b: SyncSummary): SyncSummary {
     seconds: a.seconds + b.seconds,
     ...(sent === 0 ? {} : { sent }),
     ...(refreshed === 0 ? {} : { refreshed }),
+    ...(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.adapterOnly === undefined ? (a.adapterOnly === undefined ? {} : { adapterOnly: a.adapterOnly }) : { adapterOnly: b.adapterOnly }),
   };
 }
 
+/** Whether this run's scan covers an entry: its root lies under one of the run's directories of its own format. */
+function scannedBy(settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">, entry: SyncEntry): boolean {
+  const root = resolve(entry.root);
+  return (entry.format === "clap" ? settings.clapDirs : settings.lv2Dirs).some((d) => {
+    const dir = resolve(d);
+    return root === dir || root.startsWith(dir.endsWith(sep) ? dir : dir + sep);
+  });
+}
+
 /**
  * One run: wait for quiet, qualify what is new or changed, drop what is gone, write the state, the records, the
  * descriptors and the pin file, and send the changed pins to a running daemon. The state and the pin file are written
@@ -1134,7 +1272,7 @@ function addSummaries(a: SyncSummary, b: SyncSummary): SyncSummary {
 async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promise<SyncSummary> {
   const log = options.log ?? (() => {});
   const env = options.env ?? process.env;
-  log(options.refreshOnly === true ? "pin refresh begins" : "sync run begins");
+  log(options.rejudge === true ? "re-judge begins: nothing is measured" : options.memoryOnly === true ? "memory-only pass begins" : options.adapterOnly === true ? "adapter-only pass begins" : options.refreshOnly === true ? "pin refresh begins" : "sync run begins");
   {
     const started = Date.now();
     const dirs = [...settings.clapDirs, ...settings.lv2Dirs];
@@ -1146,6 +1284,23 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       writeFileWhole(settings.stateFile, `${JSON.stringify(fresh.state, null, 1)}\n`);
     }
     if (options.refreshOnly === true) return sendRefreshed(settings, fresh.state, fresh.refreshed.length, started, log);
+    if (options.rejudge === true) {
+      const r: RejudgeResult = rejudgeState(ctx, fresh.state);
+      if (JSON.stringify(r.state) !== JSON.stringify(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, rejudge: { changed: r.changed, unchanged: r.unchanged, owing: r.owing.length } };
+    }
+    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(", ")}`);
+      const summary = await sendRefreshed(settings, fresh.state, fresh.refreshed.length, started, log);
+      return { ...summary, adapterOnly: { measured: r.measured, already: r.already, failed: r.failed } };
+    }
+    if (options.memoryOnly === true) {
+      const r: MemoryPassResult = memoryPass(ctx, fresh.state, { force: options.force === true, ...(options.probeRun === undefined ? {} : { run: options.probeRun }) });
+      const summary = await sendRefreshed(settings, fresh.state, fresh.refreshed.length, started, log);
+      return { ...summary, memoryOnly: { measured: r.measured, already: r.already, failed: r.failed } };
+    }
     await waitQuiet(dirs, settings.settleS, log);
     const count = { qualified: 0, skipped: 0, refused: 0, crashed: 0, hung: 0, unmeasured: 0, distributed: 0 };
     const layer = distributedLayerOf(settings, options.force === true, log);
@@ -1159,22 +1314,47 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
     const stateBefore = state;
     let unreadable = false;
     const lv2Pinned: string[] = [];
+    // the plugins measured this run, and how many of them the machine left unmeasured, by reason (#192)
+    let measuredHere = 0;
+    const byMachine = new Map<string, number>();
     // a change made while a pass ran is caught by one more pass, a few at most
     for (let pass = 0; pass < 3; pass++) {
       const signature = directoriesSignature(dirs);
-      const { items, problems } = discoverSyncItems(settings);
+      const { items, problems, notes } = discoverSyncItems(settings, options.lv2Resolve ?? LILV_RESOLVE);
       for (const p of problems) log(p);
+      if (pass === 0) for (const n of notes) log(n);
       unreadable = problems.length > 0;
       const found = new Set(items.map((i) => i.key));
       const entries: Record<string, SyncEntry> = {};
-      for (const [key, entry] of Object.entries(state.entries)) if (found.has(key)) entries[key] = entry;
-      for (const key of Object.keys(state.entries)) if (!found.has(key)) log(`${key}: gone, its pin is dropped`);
+      for (const [key, entry] of Object.entries(state.entries)) {
+        if (found.has(key)) entries[key] = entry;
+        // a run scoped to some directories keeps what it did not scan: gone means not found where this run looked
+        else if (!scannedBy(settings, entry)) {
+          entries[key] = entry;
+          if (pass === 0) log(`${key}: not under a directory this run scans; its pin is kept`);
+        } else log(`${key}: gone, its pin is dropped`);
+      }
       for (const item of items) {
         const recorded = recordedAsIs(item, entries[item.key]);
-        if (recorded.same && options.force !== true) {
+        const retry = recorded.same ? entries[item.key]!.plugins.map(machineReason).find((r) => r !== undefined) : undefined;
+        if (recorded.same && options.force !== true && retry === undefined) {
           if (pass === 0) count.skipped += entries[item.key]!.plugins.length;
           continue;
         }
+        // an LV2 plugin a host now loads from another bundle with the same binary (a complement that restates its TTL,
+        // #199): the record stands, keyed by its uri and its binary; only the bundle, its files and the pins' files move
+        const moved = options.force === true ? undefined : sameBinaryElsewhere(item, entries[item.key]);
+        if (moved !== undefined) {
+          entries[item.key] = { ...moved, plugins: moved.plugins.map((p) => ({ ...p, ...(p.pin === undefined ? {} : { pin: withHostdFiles(ctx, p.pin) }) })) };
+          if (item.format === "lv2") lv2Pinned.push(...entries[item.key]!.plugins.filter((p) => p.pin !== undefined).map((p) => p.uri));
+          if (pass === 0) count.skipped += moved.plugins.length;
+          log(`${item.key}: loaded from ${item.root} now, with the binary it was qualified with; its record stands and its pin's files follow the bundle`);
+          state = { schema: SYNC_STATE_SCHEMA, entries };
+          writeFileWhole(settings.stateFile, `${JSON.stringify(state, null, 1)}\n`);
+          writeFileWhole(settings.pinFile, syncPinsText(state));
+          continue;
+        }
+        if (recorded.same && retry !== undefined) log(`${item.key}: unmeasured last run by the machine (${retry}); 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`);
@@ -1196,6 +1376,11 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
         if (item.format === "lv2") lv2Pinned.push(...entry.plugins.filter((p) => p.pin !== undefined).map((p) => p.uri));
         for (const p of entry.plugins) {
           count[p.outcome]++;
+          measuredHere++;
+          // a reason of the machine is said once: the plugins after the first are counted, not listed
+          const why = machineReason(p);
+          if (why !== undefined) byMachine.set(why, (byMachine.get(why) ?? 0) + 1);
+          if (why !== undefined && byMachine.get(why)! > 1) continue;
           log(`${p.uri}: ${p.outcome}${p.code === undefined ? "" : ` (${p.code})`}${p.detail === undefined ? "" : `: ${p.detail}`}`);
         }
         state = { schema: SYNC_STATE_SCHEMA, entries };
@@ -1229,8 +1414,13 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
     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]!}`);
     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] : [];
+    const machineFailure = only !== undefined && only[1] === measuredHere ? only[0] : undefined;
+    if (machineFailure !== undefined) log(`every plugin this run measured was left unmeasured by the machine (${machineFailure}): the run failed`);
     return {
       ...count,
+      ...(machineFailure === undefined ? {} : { machineFailure }),
       seconds: (Date.now() - started) / 1000,
       ...(taken === 0 ? {} : { sent: taken }),
       ...(fresh.refreshed.length === 0 ? {} : { refreshed: fresh.refreshed.length }),

package/tools/_declarations.py

@@ -17,6 +17,7 @@ OPERATIONAL_RATE_FLOOR = 48000
 QUALIFY_RATES = (44100, 48000, 96000, 192000)
 QUALIFY_QUANTA = (128, 256, 512, 1024)
 PLUGIN_TIMEOUT_S = 15
+ADDRESS_SPACE_LIMIT_RAM_FRACTION = 1
 BOOT_TIMEOUT_S = 120
 COST_TIMEOUT_S = 60
 DESCRIPTOR_DIR_KEY = "descriptor_dir"

package/tools/benchmark.py

@@ -42,6 +42,7 @@ Usage:
 import argparse
 import json
 import os
+import resource
 import select
 import shlex
 import subprocess
@@ -53,10 +54,13 @@ from collections import namedtuple
 # declarations (with the rate list and timeouts), generated from `src/qualify-declarations.ts` because this script cannot import
 # a TS module (2026-09-17 declare-derive audit, F8) — see `_declarations.py`'s own header for the
 # regenerate/verify commands.
-from _declarations import (BOOT_TIMEOUT_S, COST_REFERENCE_RATE, COST_TIMEOUT_S,
+from _declarations import (ADDRESS_SPACE_LIMIT_RAM_FRACTION, BOOT_TIMEOUT_S, COST_REFERENCE_RATE, COST_TIMEOUT_S,
                            MEASURE_BASE_RATE, OPERATIONAL_RATE_FLOOR, PLUGIN_TIMEOUT_S,
                            QUALIFY_RATES, QUANTUM_FRAMES)
 
+# the outcome of a worker past its address space, the same word as a direct spawn of plugin-qualify's (src/direct-limit.ts)
+MEMORY_LIMIT_EXCEEDED = "memory-limit-exceeded"
+
 try:  # numpy is only needed by the worker (and as a fast path in the pure helpers)
     import numpy as _np
 except ImportError:  # pragma: no cover - CI runs the pure tests without numpy
@@ -172,7 +176,7 @@ COST_TONE_AMP = 0.5
 # whose tail is genuinely fat — the one that xruns mid-show — while being a stable
 # statistic at this sample count.
 COST_PERCENTILE = 95.0
-# Cost is anchored at the rig's canonical rate: the headline figure the operator asked for is
+# Cost is anchored at the rig's canonical rate: the headline figure asked for is
 # "how many of these fit in one core at the rig's rate". `COST_REFERENCE_RATE` is imported above
 # from `_declarations.py` — the same fact `cpu-cost.ts` declares, not a second 96000 literal.
 # A cost probe runs many more blocks than a latency probe; give it room.
@@ -1908,6 +1912,8 @@ def worker_main(rate, block, measure=False, cost=False, cpu=None,
                         host, uri, declared, res["measuredFrames"], job["sweep"])
                     if swept:
                         res["sweep"] = swept
+            except MemoryError:
+                res = {"error": MEMORY_LIMIT_EXCEEDED}
             except Exception as e:  # noqa: BLE001 - report, don't die
                 res = {"error": f"probe error: {e}"}
             if "measuredFrames" in res:
@@ -1924,6 +1930,8 @@ def worker_main(rate, block, measure=False, cost=False, cpu=None,
         symbol = arg
         try:
             frames, reason = probe_one(host, uri, symbol)
+        except MemoryError:
+            frames, reason = None, MEMORY_LIMIT_EXCEEDED
         except Exception as e:  # noqa: BLE001 - report, don't die, on python-level errors
             frames, reason = None, f"probe error: {e}"
         if frames is None:
@@ -1935,6 +1943,20 @@ def worker_main(rate, block, measure=False, cost=False, cpu=None,
 # --- the parent: batch loop with crash containment -----------------------------
 
 
+def address_space_limit(ram_bytes=None):
+    """What the worker runs under: RLIMIT_AS at ADDRESS_SPACE_LIMIT_RAM_FRACTION of the machine's RAM, since a direct
+    spawn has no runner to give it a cgroup; set between fork and exec. A plugin past it fails its allocation, which the
+    worker reports as `MEMORY_LIMIT_EXCEEDED` when Python sees it and which crash containment takes when the plugin dies."""
+    if ram_bytes is None:
+        ram_bytes = os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+    limit = int(ram_bytes * ADDRESS_SPACE_LIMIT_RAM_FRACTION)
+
+    def apply():
+        resource.setrlimit(resource.RLIMIT_AS, (limit, limit))
+
+    return apply
+
+
 class _Worker:
     """Handle on one worker subprocess: spawn, job/reply exchange, kill."""
 
@@ -1942,6 +1964,7 @@ class _Worker:
         self.proc = subprocess.Popen(
             cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
             stderr=subprocess.DEVNULL, text=True, bufsize=1,
+            preexec_fn=address_space_limit(),
         )
         ready = self._read_line(boot_timeout)
         parsed = parse_worker_line(ready)

package/tools/gen-python-declarations.mjs

@@ -33,6 +33,7 @@ const PY_NAMES = [
   'QUALIFY_RATES',
   'QUALIFY_QUANTA',
   'PLUGIN_TIMEOUT_S',
+  'ADDRESS_SPACE_LIMIT_RAM_FRACTION',
   'BOOT_TIMEOUT_S',
   'COST_TIMEOUT_S',
   'DESCRIPTOR_DIR_KEY',

package/tools/lv2-measure.mjs

@@ -60,6 +60,7 @@ import {
   urisFromScan,
 } from "../dist/measurement/index.js";
 import { LV2_HOSTING_TIMEOUT_S, LV2_MEASURE_TOOL_NAME, RT_INTERPOSE_NAME } from "../dist/qualify-declarations.js";
+import { addressSpaceLimited, directOutcome } from "../dist/direct-limit.js";
 import { halfPopulatedRefusal, locateNativeTools } from "../dist/tool-paths.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -135,9 +136,10 @@ function runHosting(step, uris, onProgress) {
   const lines = [];
   onProgress(step, { kind: "phase", plugins: uris.length, rate: Number(step.args[0]) });
   for (const uri of uris) {
-    const r = spawnSync(step.command, [uri, ...step.args], {
+    const limited = addressSpaceLimited(step.command, [uri, ...step.args]);
+    const r = spawnSync(limited.command, [...limited.args], {
       encoding: "utf8",
-      env: { ...process.env, ...step.env },
+      env: { ...process.env, ...step.env, ...limited.env },
       stdio: ["ignore", "pipe", "inherit"],
       timeout: LV2_HOSTING_TIMEOUT_S * 1000,
       maxBuffer: 16 << 20,
@@ -149,9 +151,10 @@ function runHosting(step, uris, onProgress) {
       ...(r.error?.code === "ETIMEDOUT" ? { timedOut: true } : {}),
       stdout: r.stdout ?? "",
     });
-    process.stderr.write(`  ${uri}: exit ${line.exit}\n`);
+    const limitHit = directOutcome(r.status, limited);
+    process.stderr.write(`  ${uri}: exit ${line.exit}${limitHit === undefined ? "" : ` (${limitHit.outcome})`}\n`);
     onProgress(step, { kind: "plugin" });
-    lines.push(line);
+    lines.push(limitHit === undefined ? line : { ...line, ...limitHit });
   }
   writeFileSync(step.produces, lines.map((l) => `${JSON.stringify(l)}\n`).join(""));
   return lines;

package/tools/lv2_presets.py

@@ -16,7 +16,7 @@ body, and judges it against the plugin's own descriptor params:
   listed — refuse or report, never drop.
 
 Only the bundles lilv loads from LV2_PATH are read, which is what the scan reads: the presets a
-plugin ships, never one another host saved in a user's home (ruling 2). The output is sorted by
+plugin ships, never one another host saved in a user's home (decision 2). The output is sorted by
 preset URI and the values by symbol, so the same install yields the same bytes.
 """
 

package/tools/lv2_resolve.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+"""Which bundle lilv takes for each LV2 plugin on the search path, and its binary (plugin-qualify#199).
+
+lilv loads one world over the whole LV2_PATH; where two bundles describe one plugin URI, its version rule decides
+(the higher lv2:minorVersion, then lv2:microVersion, replaces the other). An LV2 complement writes a replacing bundle
+with the microVersion one above, so lilv, and every host built on it, loads that one. The sync keys an LV2 plugin by
+the bundle lilv takes, never by the first one a directory listing finds.
+
+    LV2_PATH=<dir>:<dir>... lv2_resolve.py
+
+prints one JSON object: {"plugins": [{"uri", "bundle", "binary"}, ...]}, `bundle` a directory, `binary` the absolute
+path of the library lilv would load (it may lie outside the bundle).
+"""
+import json
+import sys
+from urllib.parse import unquote, urlparse
+
+
+def path_of(uri):
+    """A file: URI as a path, its trailing slash dropped."""
+    return unquote(urlparse(uri).path).rstrip("/")
+
+
+def main():
+    try:
+        import lilv
+    except ImportError as e:
+        print(f"lv2_resolve: lilv's Python bindings are not installed: {e}", file=sys.stderr)
+        return 2
+    world = lilv.World()
+    world.load_all()
+    out = []
+    for plugin in world.get_all_plugins():
+        library = plugin.get_library_uri()
+        out.append({
+            "uri": str(plugin.get_uri()),
+            "bundle": path_of(str(plugin.get_bundle_uri())),
+            "binary": path_of(str(library)) if library is not None else None,
+        })
+    out.sort(key=lambda p: p["uri"])
+    json.dump({"plugins": out}, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())