@openmixer/plugin-qualify 0.18.0 → 0.18.2

package/src/qualify-sync.ts

@@ -18,7 +18,7 @@
  */
 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, sep } from "node:path";
@@ -32,11 +32,14 @@ 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 { 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 { 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 { 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";
 
@@ -73,6 +76,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 +98,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 +134,14 @@ 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;
+  /** `--isolated-only`: the missing isolated step of each record already judged, extending its run. */
+  readonly isolatedOnly: boolean;
   readonly help: boolean;
   /** The settings given as flags, by key. */
   readonly values: ReadonlyMap<string, string>;
@@ -144,6 +158,10 @@ 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 isolatedOnly = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -152,6 +170,10 @@ 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 === "--isolated-only") isolatedOnly = 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 +183,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 || 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 } };
 }
 
 export function syncHelpText(): string {
@@ -175,6 +199,10 @@ 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",
+    "  --isolated-only                     run only the isolated step each record still owes, adding it to the record's run",
+    "  --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 +254,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 +286,7 @@ export function resolveSyncSettings(
       grid: grid.spec,
       cellsPerPluginBudget,
       ...(memory === undefined ? {} : { memory }),
+      memoryNotes,
       hostdPort,
       hostdFeedbackPort: feedbackPort === 0 && hostdPort !== 0 ? hostdPort + 1 : feedbackPort,
       settleS,
@@ -279,6 +310,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 +387,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 +404,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 +427,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 +509,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 +589,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 {
@@ -503,6 +619,8 @@ export interface SyncContext {
   readonly log: (line: string) => void;
   /** The run of `plugin-hostd --pin-files`, a stand-in in tests. */
   readonly pinFilesRun?: PinFilesRun;
+  /** The isolated step, a stand-in in tests. */
+  readonly isolatedRunner?: IsolatedRunner;
 }
 
 /**
@@ -586,13 +704,41 @@ function writeUnmeasuredRecord(ctx: SyncContext, item: SyncItem, files: readonly
   return path;
 }
 
+/** The step's environment: each of its commands has the sync's budget. */
+const isolatedEnv = (ctx: SyncContext): Readonly<Record<string, string | undefined>> => ({ ...ctx.env, [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000) });
+
 /** Each judged run of a pass as the plugins it qualified: the record written, the pin taken, the outcome. */
-function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgment: Judgment }[]): SyncPlugin[] {
+function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgment: Judgment }[], describeProblem?: string): SyncPlugin[] {
   const host = ctx.settings.hostProfile.id;
   const entries = runs.map(({ bytes, judgment }) => {
-    const { recordPath } = writeQualification(ctx.settings.qualificationDir, bytes, judgment, QUICK_NOT_MEASURED);
-    const pin = withHostdFiles(ctx, judgmentPinEntries(judgment, host)[0]);
-    const { outcome, code } = outcomeOf(judgment, host);
+    const { recordPath, record } = writeQualification(ctx.settings.qualificationDir, bytes, judgment, QUICK_NOT_MEASURED);
+    const steps = baseSteps(record, describeProblem);
+    let pin = withHostdFiles(ctx, judgmentPinEntries(judgment, host)[0]);
+    let { outcome, code } = outcomeOf(judgment, host);
+    if (owesIsolated(record)) {
+      // in this same pass: a record's verdict=isolated is a run seen alone, never a rating alone
+      const uri = pin?.uri ?? judgment.output.plugin.id;
+      const runner = ctx.isolatedRunner ?? spawnedIsolatedRunner();
+      const step = judgeIsolatedRun(runner(uri, isolatedCell(record, host), isolatedEnv(ctx)));
+      steps.push(step);
+      pin = pinAfterStep(pin, step);
+      // a crash or a hang in the probe stays what it was unless the step saw the plugin run: only a rating waited on the step
+      if (step.result === ISOLATED_RESULT.refused) {
+        if (outcome === "qualified") {
+          outcome = "refused";
+          code = step.code;
+        }
+      } else if (step.result === ISOLATED_RESULT.notRun) {
+        if (outcome === "qualified") {
+          outcome = "unmeasured";
+          code = step.code;
+        }
+      } else if (outcome !== "qualified") {
+        outcome = "qualified";
+        code = undefined;
+      }
+    }
+    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) };
   });
@@ -686,21 +832,17 @@ function qualifyClap(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
     const pass = runPass(ctx, { format: "clap", uri: `urn:clap:${p.id}`, bundle: item.root, binary: item.files[0]!, binaryPath: file }, ctx.env);
     for (const f of pass.failures) out.push({ uri, outcome: "unmeasured", code: SYNC_CODE.notMeasured, detail: f.problem });
     const problem = descriptorFailed.get(p.id);
-    out.push(...judgedPlugins(ctx, pass.runs).map((j) => (problem === undefined ? j : { ...j, descriptorProblem: problem })));
+    out.push(...judgedPlugins(ctx, pass.runs, problem).map((j) => (problem === undefined ? j : { ...j, descriptorProblem: problem })));
   }
   return out;
 }
 
 /** 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. */
@@ -720,6 +862,46 @@ export function qualifyItem(ctx: SyncContext, item: SyncItem, files: readonly Fi
   return { format: item.format, root: item.root, files: all, plugins, qualifiedAt: new Date(started).toISOString(), seconds: (Date.now() - started) / 1000 };
 }
 
+/**
+ * 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 };
+  const runner = ctx.isolatedRunner ?? spawnedIsolatedRunner();
+  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")) 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 isolated step`);
+          return p;
+        }
+        const done = completeIsolated(path, record, p.pin?.uri ?? record.plugin.id, isolatedCell(record, host), runner, isolatedEnv(ctx));
+        if (done === undefined) return p;
+        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;
+        if (done.step.result === ISOLATED_RESULT.isolated) {
+          count.isolated++;
+          return { ...rest, outcome: "qualified" as const, ...(pin === undefined ? {} : { pin }) };
+        }
+        if (done.step.result === ISOLATED_RESULT.refused) count.refused++;
+        else count.notRun++;
+        return { ...rest, outcome: done.step.result === ISOLATED_RESULT.refused ? ("refused" as const) : ("unmeasured" as const), ...(done.step.code === undefined ? {} : { code: done.step.code }), ...(pin === undefined ? {} : { pin }) };
+      }),
+    };
+  }
+  return { ...count, state: count.isolated + count.refused + count.notRun === 0 ? state : { ...state, entries } };
+}
+
 // --- the distributed records ----------------------------------------------------------------------------------------
 
 /** The layer a run reads: none under `--force` or `--no-distributed`, or without a host class. */
@@ -750,6 +932,13 @@ function takeDistributed(ctx: SyncContext, layer: DistributedLayer, item: SyncIt
     for (const line of match.lines) ctx.log(line);
     return undefined;
   }
+  for (const r of match.records) {
+    const missing = missingSteps(r.record);
+    if (missing.length > 0) {
+      ctx.log(`distributed: ${distributedUri(item, r)}: its record lacks the step${missing.length === 1 ? "" : "s"} ${missing.join(", ")}; measured here`);
+      return undefined;
+    }
+  }
   let plugins: SyncPlugin[];
   try {
     plugins = applyDistributed(ctx.settings.qualificationDir, item, match, host);
@@ -984,6 +1173,16 @@ 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;
+  /** `--isolated-only`: how the steps ended. */
+  readonly isolatedOnly?: { readonly isolated: number; readonly refused: 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 };
 }
 
 /**
@@ -1020,7 +1219,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 +1265,24 @@ 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;
+  /** The isolated step, a stand-in in tests. */
+  readonly isolatedRunner?: IsolatedRunner;
+  /** `--isolated-only`: take only the isolated steps records still owe. */
+  readonly isolatedOnly?: 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,6 +1338,10 @@ 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.isolatedOnly === undefined ? (a.isolatedOnly === undefined ? {} : { isolatedOnly: a.isolatedOnly }) : { isolatedOnly: b.isolatedOnly }),
+    ...(b.adapterOnly === undefined ? (a.adapterOnly === undefined ? {} : { adapterOnly: a.adapterOnly }) : { adapterOnly: b.adapterOnly }),
   };
 }
 
@@ -1143,11 +1362,11 @@ function scannedBy(settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">, entry:
 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];
-    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }) };
+    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }), ...(options.isolatedRunner === undefined ? {} : { isolatedRunner: options.isolatedRunner }) };
     // 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));
@@ -1155,6 +1374,29 @@ 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.isolatedOnly === true) {
+      const r = isolatedPass(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, isolatedOnly: { isolated: r.isolated, refused: r.refused, 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(", ")}`);
+      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);
@@ -1168,11 +1410,15 @@ 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> = {};
@@ -1186,10 +1432,25 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       }
       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`);
@@ -1211,6 +1472,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 };
@@ -1244,8 +1510,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 }),