@openmixer/plugin-qualify 0.17.5 → 0.18.1

package/src/probe-merge.ts

@@ -14,7 +14,7 @@
  *
  * One run that ended well and needs nothing added is kept as the runner wrote it, byte for byte.
  */
-import { outOfMemory, PROBE_OOM, type MemoryBound } from "./memory-bound.js";
+import { isOutOfMemory, MEMORY_CGROUP_MECHANISM, outOfMemory, PROBE_MEMORY_LIMIT, PROBE_OOM, type MemoryBound } from "./memory-bound.js";
 import { cellKey, type RunnerInvocation } from "./measurement-grid.js";
 import { PROBE_OK, readProbeOutput, type ProbeOutput } from "./probe-output.js";
 
@@ -36,7 +36,8 @@ type Json = Record<string, unknown>;
 
 export function mergeProbeRuns(parts: readonly ProbeRunPart[], bound: MemoryBound | undefined): { bytes: Buffer; output: ProbeOutput } {
   if (parts.length === 0) throw new ProbeMergeError("no run to merge");
-  const outcomes = parts.map((p) => (outOfMemory(p.output, bound) ? PROBE_OOM : p.output.run.outcome));
+  // the runner's own outcome when it says it (the kernel killed the child at memory.max), else what its exit means under the data limit
+  const outcomes = parts.map((p) => (p.output.run.outcome === PROBE_MEMORY_LIMIT ? PROBE_MEMORY_LIMIT : outOfMemory(p.output, bound) ? PROBE_OOM : p.output.run.outcome));
   const first = parts[0]!;
   for (const p of parts.slice(1)) {
     if (p.output.plugin.id !== first.output.plugin.id || p.output.binary.sha256 !== first.output.binary.sha256 || p.output.offer.id !== first.output.offer.id) {
@@ -66,18 +67,18 @@ export function mergeProbeRuns(parts: readonly ProbeRunPart[], bound: MemoryBoun
       for (const c of p.invocation.cells) {
         if (seen.has(cellKey(c))) continue;
         seen.add(cellKey(c));
-        grid.push({ rate: c.rate, quantum: c.quantum, outcome: outcomes[i], ...(outcomes[i] === PROBE_OOM && bound !== undefined ? { memoryLimit: { bytes: bound.bytes, mechanism: bound.mechanism } } : {}) });
+        grid.push({ rate: c.rate, quantum: c.quantum, outcome: outcomes[i], ...(isOutOfMemory(outcomes[i]!) && bound !== undefined ? { memoryLimit: { bytes: bound.bytes, mechanism: outcomes[i] === PROBE_MEMORY_LIMIT ? MEMORY_CGROUP_MECHANISM : bound.mechanism } } : {}) });
       }
     }
     steps.push(...((docs[i]!["steps"] as unknown[] | undefined) ?? []));
   });
-  const judged = outcomes.filter((o) => o !== PROBE_OOM);
+  const judged = outcomes.filter((o) => !isOutOfMemory(o));
   const run = merged["run"] as Json;
   merged["run"] = {
     ...run,
     elapsedMs: parts.reduce((sum, p) => sum + p.output.run.elapsedMs, 0),
     complete: parts.every((p, i) => p.output.run.complete && outcomes[i] === PROBE_OK),
-    outcome: judged.length === 0 ? PROBE_OOM : (judged.find((o) => o !== PROBE_OK) ?? PROBE_OK),
+    outcome: judged.length === 0 ? outcomes[0]! : (judged.find((o) => o !== PROBE_OK) ?? PROBE_OK),
     parts: parts.map((p, i) => ({ id: p.output.run.id, outcome: outcomes[i], rates: p.invocation.rates, quantum: p.invocation.quantum, elapsedMs: p.output.run.elapsedMs })),
   };
   merged["steps"] = steps;

package/src/probe-output-fixtures.ts

@@ -11,11 +11,20 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import type { ClapQualifyLine } from "./clap-qualify.js";
-import { OMX_CLAP_HOST_EXTENSIONS } from "./host-profiles.js";
+import { OMX_CLAP_HOST_EXTENSIONS, type HostProfile } from "./host-profiles.js";
 import { readProbeOutput, type ProbeOutput } from "./probe-output.js";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "..", "fixtures", "probe-output");
 
+/**
+ * The same host with no memory budget: for the tests of what a probe output says about everything else, on documents
+ * that do not hold a footprint at the host's own cell.
+ */
+export function withoutMemoryBudget<T extends HostProfile>(profile: T): T {
+  const { memory: _memory, ...cost } = profile.cost;
+  return { ...profile, cost };
+}
+
 export function fixtureText(name: string): string {
   return readFileSync(join(FIXTURES, `${name}.json`), "utf8");
 }

package/src/probe-output.ts

@@ -20,7 +20,7 @@
 import { createHash } from "node:crypto";
 
 import { finiteNumber, isRecord, nonEmptyString, optional } from "./measurement/guards.js";
-import { readVoicesHeld, type VoicesHeld } from "./measurement/format.js";
+import { readMemoryFootprint, readVoicesHeld, type MemoryFootprint, type VoicesHeld } from "./measurement/format.js";
 
 export const PROBE_OUTPUT_FORMAT = "plugin-hostd.probe-output";
 /** The one major this reader knows. A minor of it only adds fields. */
@@ -96,7 +96,9 @@ export interface ProbeGridPoint {
   readonly cost?: ProbeCost;
   readonly rtSafety?: ProbeRtSafety;
   readonly noteSweep?: ProbeNoteSweep;
-  /** A cell whose run outgrew the memory bound (`probe.oom`): the bound it ran under. */
+  /** What one instance holds at this rate and quantum, as the prober read it; absent when it took none. */
+  readonly memory?: MemoryFootprint;
+  /** A cell whose run outgrew the memory bound (`probe.oom`, `probe.memory-limit`): the bound it ran under. */
   readonly memoryLimit?: { readonly bytes: number; readonly mechanism: string };
 }
 
@@ -310,6 +312,7 @@ function readPoint(v: unknown, i: number): ProbeGridPoint {
     ...(o["cost"] === undefined ? {} : { cost: readCost(o["cost"], `${where} cost`) }),
     ...(o["rtSafety"] === undefined ? {} : { rtSafety: readRtSafety(o["rtSafety"], `${where} rtSafety`) }),
     ...(o["noteSweep"] === undefined ? {} : { noteSweep: readNoteSweep(o["noteSweep"], `${where} noteSweep`) }),
+    ...optional("memory", readMemoryFootprint(o["memory"])),
     ...(o["memoryLimit"] === undefined ? {} : { memoryLimit: readMemoryLimit(o["memoryLimit"], `${where} memoryLimit`) }),
   };
 }

package/src/probe-runner.ts

@@ -22,10 +22,10 @@ import type { HostProfile } from "./host-profiles.js";
 import { OPENMIXER_CONSOLE_PROFILE, shippedHostProfile } from "./host-profiles.js";
 import { IN_PROCESS_TIER_HOST, ISOLATED_TIER_HOST } from "./qualification-record.js";
 import type { PluginTarget } from "./loader.js";
-import { SPAWNED_ADMISSIONS, admitPlugin, admitUnderAdapter, admittedHostOf, type AdmissionRuns, type HostAdmission } from "./host-admission.js";
+import { ADAPTER_RUN_HOSTS, SPAWNED_ADMISSIONS, admitPlugin, admitUnderAdapter, admittedHostOf, type AdmissionRuns, type HostAdmission } from "./host-admission.js";
 import { judgeProbeOutput, judgmentVerdicts, type Judgment } from "./probe-judge.js";
 import { readProbeOutput, type ProbeOutput } from "./probe-output.js";
-import { budgetCells, gridCells, runnerInvocations, type GridCell, type GridSpec, type RunnerInvocation } from "./measurement-grid.js";
+import { budgetCells, gridCells, hostCells, runnerInvocations, type GridCell, type GridSpec, type RunnerInvocation } from "./measurement-grid.js";
 import type { MemoryBound } from "./memory-bound.js";
 import { mergeProbeRuns, ProbeMergeError } from "./probe-merge.js";
 import type { QualifyVerdict } from "./qualify-cli.js";
@@ -292,12 +292,14 @@ export function qualifyTargets(
     const cells =
       options.grid === undefined
         ? options.cells
-        : gridCells(options.grid, { rates: options.rates, quanta: options.quanta ?? QUALIFY_QUANTA, hosts: judgedProfiles.map((p) => ({ rate: p.cost.rate, quantum: p.cost.quantum })) });
+        : gridCells(options.grid, { rates: options.rates, quanta: options.quanta ?? QUALIFY_QUANTA, hosts: judgedProfiles.flatMap(hostCells) });
     const measured = cells === undefined ? {} : { cells: budgetCells(cells, options.cellsPerPluginBudget) };
     // an LV2 plugin is run under each measured host once, whichever probe output it is judged with
     const admissions: Record<string, HostAdmission> = {};
     // an LV2 plugin is also run once under plugin-hostd's LV2 adapter, recorded beside the verdicts (#223)
     const adapter = target.format === "lv2" ? admitUnderAdapter(target.uri, admissionRuns, admissionEnv) : undefined;
+    // and that run decides its omx-clap-host verdict, the isolated tier
+    if (adapter !== undefined) for (const host of ADAPTER_RUN_HOSTS) admissions[host] = adapter;
     if (target.format === "lv2") {
       for (const profile of judgedProfiles) {
         const host = admittedHostOf(profile);

package/src/qualification-record.ts

@@ -13,6 +13,8 @@
  * Not yet in the record: the fingerprint of the descriptor's controls, since the descriptor is
  * written by the scan (stage 5) and plugin-qualify does not read one yet.
  */
+import type { MemoryFootprint } from "./measurement/format.js";
+import { firstInstanceKb, perInstanceKb } from "./memory-budget.js";
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -41,6 +43,28 @@ export interface RecordVerdict {
   readonly reasons: readonly RecordReason[];
 }
 
+/**
+ * An LV2 plugin's run under the adapter. The top is what the judge reads. `--adapter-only` adds the versions of the hosts
+ * it ran under, when, and how each cell went.
+ */
+export interface AdapterBlock {
+  readonly host: string;
+  readonly measured: boolean;
+  readonly admitted: boolean;
+  readonly code?: string;
+  readonly params: Readonly<Record<string, string | number>>;
+  readonly versions?: Readonly<Record<string, string>>;
+  readonly measuredAt?: string;
+  readonly cells?: readonly {
+    readonly rate: number;
+    readonly quantum: number;
+    readonly measured: boolean;
+    readonly admitted: boolean;
+    readonly code?: string;
+    readonly params: Readonly<Record<string, string | number>>;
+  }[];
+}
+
 /** One tier of the console as a verdict: the host it is judged under and whether the plugin qualified there. */
 export interface TierVerdict {
   readonly host: string;
@@ -48,9 +72,15 @@ export interface TierVerdict {
   readonly qualified: boolean;
   readonly rating: string;
   readonly deciding?: string;
+  /** The isolated tier of a `conditional` plugin: it is offered, and runs alone in a worker of its own, never grouped. */
+  readonly runsAlone?: true;
 }
 
-/** The console's two tiers (what the console's roster offers): offered where the verdict qualified, dimmed with the reason when neither did. */
+/**
+ * The console's two tiers (what the console's roster offers): in-process where its verdict qualified; isolated where its
+ * verdict qualified or is `conditional`, which pins `isolated` and runs alone (`runsAlone`); dimmed with the reason when
+ * neither. `qualified` stays `rating === "suitable"`, as the interchange's reader holds it.
+ */
 export interface RecordTiers {
   readonly inProcess?: TierVerdict;
   readonly isolated?: TierVerdict;
@@ -59,8 +89,11 @@ export interface RecordTiers {
   readonly dimmed?: string;
 }
 
-/** The profile each format's isolated tier is judged under. */
-export const ISOLATED_TIER_HOST: Readonly<Record<string, string>> = { lv2: "mod-host", clap: "omx-clap-host" };
+/**
+ * The profile each format's isolated tier is judged under: omx-clap-host for both, an LV2 plugin through plugin-hostd's
+ * LV2 adapter, whose run decides that verdict (`host-admission.ts`). mod-host is judged only when a run asks for it.
+ */
+export const ISOLATED_TIER_HOST: Readonly<Record<string, string>> = { lv2: "omx-clap-host", clap: "omx-clap-host" };
 export const IN_PROCESS_TIER_HOST = "openmixer-console";
 
 /** A latency or cost figure the run could not take: which one, at what rate and quantum, and the code that says why. */
@@ -100,13 +133,29 @@ export interface UnmeasuredLatency {
 }
 
 /** A grid point as the record writes it: every cell carries `latency`, the figures or why there are none (#201). */
-export type RecordGridPoint = Omit<ProbeGridPoint, "latency"> & {
+export type RecordGridPoint = Omit<ProbeGridPoint, "latency" | "memory"> & {
+  /** The footprint as measured, with what it comes to: what a client adding the plugin reads (`memory-budget.ts`). */
+  readonly memory?: MemoryFootprint & { readonly firstInstanceKb?: number; readonly perInstanceKb?: number };
   readonly latency: (Omit<NonNullable<ProbeGridPoint["latency"]>, "measuredFrames"> & { readonly measuredFrames: number }) | UnmeasuredLatency;
 };
 
 const UNMEASURED_WORDS: ReadonlySet<string> = new Set(Object.values(MEASUREMENT_UNMEASURED_REASONS).map((r) => r.word));
 const word = (key: keyof typeof MEASUREMENT_UNMEASURED_REASONS): string => MEASUREMENT_UNMEASURED_REASONS[key].word;
 
+/** The same, for the test. */
+export const memoryOfCellForTest = (p: ProbeGridPoint): Pick<RecordGridPoint, "memory"> => memoryOfCell(p);
+
+/** The contract's word for a cell whose run ended with this outcome, `probe-error` for one it has no word of. */
+export const unmeasuredWordOf = (outcome: string): string => OUTCOME_WORD[outcome] ?? word("probeError");
+
+/** A cell's footprint with what it comes to; only a footprint with no reason beside it comes to anything a client may add up. */
+export function memoryOfCell(p: ProbeGridPoint): Pick<RecordGridPoint, "memory"> {
+  if (p.memory === undefined) return {};
+  const first = p.memory.unmeasuredReason === undefined ? firstInstanceKb(p.memory) : undefined;
+  const per = p.memory.unmeasuredReason === undefined ? perInstanceKb(p.memory) : undefined;
+  return { memory: { ...p.memory, ...(first === undefined ? {} : { firstInstanceKb: first }), ...(per === undefined ? {} : { perInstanceKb: per }) } };
+}
+
 /** The unmeasured word of a cell whose run did not end well, by its outcome code. */
 const OUTCOME_WORD: Readonly<Record<string, string>> = {
   "probe.crashed": word("probeCrashed"),
@@ -163,6 +212,51 @@ export interface HistoryBlock {
   readonly verdicts: readonly ({ readonly host: string } & Adjustment)[];
 }
 
+/** One measurement a record lacks, and what it keeps from being decided. */
+export interface OwedMeasurement {
+  /** `adapter-run`: the plugin under omx-clap-host's LV2 adapter. `host-run`: under the host named. `qualification`: the whole of it. */
+  readonly measurement: "adapter-run" | "host-run" | "qualification";
+  readonly host?: string;
+  readonly code: string;
+  readonly detail?: string;
+}
+
+/**
+ * The verdicts are not the ones of the run that took the figures: `plugin-qualify-sync --rejudge` derived them later, from
+ * those figures, under the rules of `by`. `figures` says who took the figures and when; the verdicts claim nothing more.
+ */
+export interface RejudgedBlock {
+  /** The UTC time the verdicts last changed. */
+  readonly at: string;
+  /** The plugin-qualify whose rules judged them. */
+  readonly by: string;
+  readonly figures: {
+    readonly tool: Readonly<Record<string, string>>;
+    readonly measuredAt: string;
+    readonly runId: string;
+    /** The footprints, when a memory-only pass took them later than the rest. */
+    readonly memory?: { readonly tool: Readonly<Record<string, string>>; readonly measuredAt: string };
+    /** The adapter run, when an adapter-only pass took it later than the rest. */
+    readonly adapter?: { readonly versions: Readonly<Record<string, string>>; readonly measuredAt: string };
+  };
+  /** What these verdicts could not decide and left `unknown`; absent when nothing is owed. */
+  readonly owes?: readonly OwedMeasurement[];
+}
+
+/** The memory-only pass that took this record's footprints: every other figure is older and comes from `tool`. */
+export interface MemoryRunBlock {
+  readonly tool: Readonly<Record<string, string>>;
+  readonly measuredAt: string;
+  readonly runId: string;
+  readonly cells: readonly {
+    readonly rate: number;
+    readonly quantum: number;
+    /** How the cell's run ended; its figures are in the grid's point of that cell. */
+    readonly outcome: string;
+    readonly memoryLimit?: { readonly bytes: number; readonly mechanism: string };
+  }[];
+}
+
 export interface QualificationRecord {
   readonly schema: typeof QUALIFICATION_RECORD_SCHEMA;
   readonly plugin: { readonly format: string; readonly id: string; readonly name?: string };
@@ -174,7 +268,7 @@ export interface QualificationRecord {
    * An LV2 plugin run under plugin-hostd's LV2 adapter (omx-clap-host), as under mod-host: admitted, or refused with
    * its code, or `measured: false` when it was not tried. Beside the verdicts, which it does not change (#223).
    */
-  readonly adapter?: { readonly host: string; readonly measured: boolean; readonly admitted: boolean; readonly code?: string; readonly params: Readonly<Record<string, string | number>> };
+  readonly adapter?: AdapterBlock;
   readonly tiers: RecordTiers;
   /** The cost reasons at each host's rate and quantum, beside the verdicts; an instrument's with the notes it held. */
   readonly cost: readonly {
@@ -205,6 +299,10 @@ export interface QualificationRecord {
   readonly history?: readonly HistoryBlock[];
   /** Where the record came from when it was not measured on this device: the distributed set's provenance, as the set's package wrote it. */
   readonly provenance?: Readonly<Record<string, unknown>>;
+  /** Present when the verdicts were derived later from the figures below, measuring nothing. */
+  readonly rejudged?: RejudgedBlock;
+  /** Present when a memory-only pass merged footprints into the grid. */
+  readonly memoryRun?: MemoryRunBlock;
   /** The probe output this record judged. */
   readonly probe: {
     readonly file: string;
@@ -246,18 +344,32 @@ function tierOf(judgment: Judgment, host: string | undefined): TierVerdict | und
 export function tiersOf(judgment: Judgment): RecordTiers {
   const inProcess = tierOf(judgment, IN_PROCESS_TIER_HOST);
   const isolated = tierOf(judgment, ISOLATED_TIER_HOST[judgment.output.plugin.format]);
+  const runsAlone = isolated?.measured === true && isolated.rating === "conditional";
   const offeredOn: ("in-process" | "isolated")[] = [];
   if (inProcess?.qualified === true) offeredOn.push("in-process");
-  if (isolated?.qualified === true) offeredOn.push("isolated");
+  if (isolated?.qualified === true || runsAlone) offeredOn.push("isolated");
   const why = [inProcess, isolated].flatMap((t) => (t === undefined ? [] : [`${t.host}: ${t.deciding ?? t.rating}`]));
   return {
     ...(inProcess === undefined ? {} : { inProcess }),
-    ...(isolated === undefined ? {} : { isolated }),
+    ...(isolated === undefined ? {} : { isolated: { ...isolated, ...(runsAlone ? { runsAlone: true as const } : {}) } }),
     offeredOn,
     ...(offeredOn.length === 0 ? { dimmed: why.length === 0 ? "no tier was judged" : why.join("; ") } : {}),
   };
 }
 
+/** A judgment's verdicts as the record writes them. */
+export const verdictRows = (judgment: Judgment): RecordVerdict[] =>
+  judgment.hosts.map((h) => ({
+    host: h.verdict.host,
+    measured: h.verdict.measured,
+    rating: h.verdict.rating,
+    qualified: h.verdict.qualified,
+    hosting: h.hosting,
+    arm: h.arm,
+    ...(h.verdict.deciding === undefined ? {} : { deciding: h.verdict.deciding }),
+    reasons: h.reasons,
+  }));
+
 export function buildQualificationRecord(
   judgment: Judgment,
   copy: { file: string; sha256: string; bytes: number },
@@ -269,21 +381,12 @@ export function buildQualificationRecord(
     plugin: { format: o.plugin.format, id: o.plugin.id, ...(o.plugin.name === undefined ? {} : { name: o.plugin.name }) },
     ...(o.plugin.version === undefined ? {} : { testedVersion: o.plugin.version }),
     binary: o.binary,
-    verdicts: judgment.hosts.map((h) => ({
-      host: h.verdict.host,
-      measured: h.verdict.measured,
-      rating: h.verdict.rating,
-      qualified: h.verdict.qualified,
-      hosting: h.hosting,
-      arm: h.arm,
-      ...(h.verdict.deciding === undefined ? {} : { deciding: h.verdict.deciding }),
-      reasons: h.reasons,
-    })),
+    verdicts: verdictRows(judgment),
     ...(judgment.adapter === undefined ? {} : { adapter: judgment.adapter }),
     tiers: tiersOf(judgment),
     cost: judgment.hosts.map((h) => ({ host: h.verdict.host, ...h.cost })),
     measurements: {
-      grid: o.grid.map((p) => ({ ...p, latency: latencyOfCell(o, p) })),
+      grid: o.grid.map((p) => ({ ...p, ...memoryOfCell(p), latency: latencyOfCell(o, p) })),
       ...(o.behaviour === undefined ? {} : { behaviour: o.behaviour }),
       ...(unmeasuredFigures(o).length === 0 ? {} : { unmeasured: unmeasuredFigures(o) }),
     },

package/src/qualify-adapter-pass.ts

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `plugin-qualify-sync --adapter-only`: an LV2 plugin's verdict on omx-clap-host is decided by its run under plugin-hostd's
+ * LV2 adapter, and a record without one owes it (`qualify-rejudge.ts`). This pass makes only that run, for each plugin, at
+ * each cell a Pi runs, and puts the block in the record; every other figure stays as it was, and `--rejudge` reads it.
+ *
+ * Each cell has a private JACK server of its own (`jackd -d dummy`, the rate and quantum on its command line), so that the
+ * run can never reach the device's live server (plugin-qualify#187), and each run a fresh host, its time limited by
+ * `budget_s` a command and its address space by the limit of a direct spawn. A crash or a timeout is the plugin's recorded
+ * outcome. A pass does not start without the versions of the hosts it runs, or without a private server: nothing it could
+ * write would say what it measured. A plugin is finished when its block was taken at these host versions at every cell,
+ * so a pass cut short can be run again; a host that could not be run decides nothing, and that plugin is tried again.
+ */
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+import { ADAPTER_HOST, SPAWNED_ADMISSIONS, admitUnderAdapter, type AdmissionRuns, type HostAdmission } from "./host-admission.js";
+import { HOSTD_ENV } from "./hostd-pin-files.js";
+import { cellKey, type GridCell } from "./measurement-grid.js";
+import { defaultAddressSpaceLimit } from "./direct-limit.js";
+import { PROBE_OK } from "./probe-output.js";
+import { QUALIFICATION_RECORD_SCHEMA, type AdapterBlock, type QualificationRecord } from "./qualification-record.js";
+import { ADMIT_ADDRESS_KB_ENV, ADMIT_STATE_DIR_ENV, ADMIT_STEP_MS_ENV, PI_CELLS } from "./qualify-declarations.js";
+import { digestFiles, type SyncContext, type SyncState } from "./qualify-sync.js";
+import { writeFileWhole } from "./whole-file.js";
+
+/** The cells the pass runs at: the ones a Pi runs. */
+export const ADAPTER_PASS_CELLS: readonly GridCell[] = PI_CELLS;
+
+/** The code of a cell no private server could be had for: the run did not happen. */
+export const NO_PRIVATE_SERVER = `${ADAPTER_HOST}.no-private-server`;
+
+const RECORD_SUFFIX = ".qualification.json";
+const SERVER_WAIT_MS = 5000;
+const SERVER_SETTLE_MS = 300;
+const SERVER_STOP_MS = 2000;
+
+/** What a program answers to `--version`: its last word on the line that says `version`. */
+export function parseVersion(text: string): string | undefined {
+  return /version:?\s+(\S+)/.exec(text)?.[1];
+}
+
+export type VersionRun = (tool: string) => { readonly status: number | null; readonly stdout: string };
+
+const spawnVersion: VersionRun = (tool) => {
+  const r = spawnSync(tool, ["--version"], { encoding: "utf8", timeout: 10000, killSignal: "SIGKILL" });
+  return { status: r.status, stdout: `${r.stdout ?? ""}\n${r.stderr ?? ""}` };
+};
+
+/** The versions of the hosts as installed now, or which of them could not say. */
+export function hostVersions(env: Readonly<Record<string, string | undefined>>, run: VersionRun = spawnVersion): { ok: true; versions: Readonly<Record<string, string>> } | { ok: false; error: string } {
+  const versions: Record<string, string> = {};
+  for (const [name, tool] of [[ADAPTER_HOST, ADAPTER_HOST], ["plugin-hostd", env[HOSTD_ENV] ?? "plugin-hostd"]] as const) {
+    const r = run(tool);
+    const version = r.status === 0 ? parseVersion(r.stdout) : undefined;
+    if (version === undefined) return { ok: false, error: `${tool} --version names no version, so a run could not say which host it was under` };
+    versions[name] = version;
+  }
+  return { ok: true, versions };
+}
+
+/** A private JACK server for one cell, for as long as a pass needs it. */
+export interface PrivateJack {
+  readonly name: string;
+  alive(): boolean;
+  stop(): void;
+}
+
+export type JackStarter = (cell: GridCell) => PrivateJack | undefined;
+
+const sleepSync = (ms: number): void => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/** `jackd` on a name of its own and the dummy driver, at the cell's rate and quantum; `undefined` when none came up. */
+export const startPrivateJack: JackStarter = (cell) => {
+  const name = `omx-qualify-${String(process.pid)}-${String(cell.quantum)}`;
+  let child: ChildProcess;
+  let ended = false;
+  try {
+    child = spawn("jackd", ["-r", "-n", name, "-d", "dummy", "-r", String(cell.rate), "-p", String(cell.quantum)], { stdio: "ignore", detached: true });
+  } catch {
+    return undefined;
+  }
+  child.on("error", () => (ended = true));
+  child.on("exit", () => (ended = true));
+  child.unref();
+  const running = (): boolean => {
+    if (ended || child.pid === undefined) return false;
+    // the exit event needs the loop this synchronous pass holds: the process table says
+    return existsSync(`/proc/${String(child.pid)}`) && !/^\S+ \(.*\) Z/.test(readStat(child.pid));
+  };
+  // a TERM first: jackd frees the shared memory it holds under /dev/shm itself, which a KILL would leave behind for good
+  const signal = (sig: NodeJS.Signals): void => {
+    try {
+      if (child.pid !== undefined) process.kill(-child.pid, sig);
+    } catch {
+      // already gone
+    }
+  };
+  const stop = (): void => {
+    signal("SIGTERM");
+    const until = Date.now() + SERVER_STOP_MS;
+    while (running() && Date.now() < until) sleepSync(20);
+    if (running()) signal("SIGKILL");
+    for (const d of serverDirs(name)) rmSync(d, { recursive: true, force: true });
+  };
+  const until = Date.now() + SERVER_WAIT_MS;
+  while (Date.now() < until) {
+    if (child.pid === undefined || !running()) {
+      stop();
+      return undefined;
+    }
+    if (serverDirs(name).length > 0) {
+      sleepSync(SERVER_SETTLE_MS);
+      return { name, alive: running, stop };
+    }
+    sleepSync(50);
+  }
+  stop();
+  return undefined;
+};
+
+const readStat = (pid: number): string => {
+  try {
+    return readFileSync(`/proc/${String(pid)}/stat`, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+/** Where jackd keeps a server's sockets, and its semaphores: the socket appears as the server opens it. */
+function serverDirs(name: string): string[] {
+  try {
+    return readdirSync("/dev/shm").filter((d) => d.startsWith(`jack_${name}_`) || new RegExp(`^jack_sem\\.\\d+_${name}_`).test(d)).map((d) => join("/dev/shm", d));
+  } catch {
+    return [];
+  }
+}
+
+/** Whether a machine can give a pass its private server at all: the program is there. */
+function jackdInstalled(env: Readonly<Record<string, string | undefined>>): boolean {
+  return (env["PATH"] ?? process.env["PATH"] ?? "").split(":").some((d) => d !== "" && existsSync(join(d, "jackd")));
+}
+
+// --- the block --------------------------------------------------------------------------------------------------------
+
+/**
+ * The runs of every cell as one block. Its top is what the judge reads: a refusal or a crash at any cell decides, with the
+ * cell it happened at, whatever the others say; then a cell where the host could not be run leaves it not measured, so
+ * still owed; only every cell admitted is admitted. Pure.
+ */
+export function adapterBlockOf(runs: readonly { readonly cell: GridCell; readonly run: HostAdmission }[], versions: Readonly<Record<string, string>>, measuredAt: string): AdapterBlock {
+  const cells = runs.map(({ cell, run }) => ({ rate: cell.rate, quantum: cell.quantum, measured: run.measured, admitted: run.admitted, ...(run.code === undefined ? {} : { code: run.code }), params: run.params }));
+  const worst = cells.find((c) => c.measured && !c.admitted) ?? cells.find((c) => !c.measured);
+  const top =
+    worst === undefined
+      ? { measured: true, admitted: true, params: {} }
+      : { measured: worst.measured, admitted: false, ...(worst.code === undefined ? {} : { code: worst.code }), params: { ...worst.params, rate: worst.rate, quantum: worst.quantum } };
+  return { host: ADAPTER_HOST, ...top, versions, measuredAt, cells };
+}
+
+/** The record with the block, and every other byte of it as it was. Pure. */
+export const mergeAdapterRun = (record: QualificationRecord, block: AdapterBlock): QualificationRecord => ({ ...record, adapter: block });
+
+/** Whether a record's adapter run is done: at these host versions, measured, at every cell. */
+export function adapterFinished(record: QualificationRecord, versions: Readonly<Record<string, string>>, cells: readonly GridCell[] = ADAPTER_PASS_CELLS): boolean {
+  const a = record.adapter;
+  if (a === undefined || !a.measured || a.versions === undefined || a.cells === undefined) return false;
+  const same = Object.keys(versions).length === Object.keys(a.versions).length && Object.entries(versions).every(([k, v]) => a.versions![k] === v);
+  return same && cells.every((c) => a.cells!.some((x) => cellKey(x) === cellKey(c)));
+}
+
+// --- the pass ---------------------------------------------------------------------------------------------------------
+
+export interface AdapterPassOptions {
+  readonly force?: boolean;
+  readonly runs?: AdmissionRuns;
+  readonly jack?: JackStarter;
+  readonly versions?: VersionRun;
+  /** The test's stand-in for jackd says it is there; the real pass looks. */
+  readonly jackdPresent?: boolean;
+  readonly now?: () => string;
+}
+
+export interface AdapterPassResult {
+  readonly measured: number;
+  readonly already: number;
+  readonly failed: number;
+  readonly versions: Readonly<Record<string, string>>;
+}
+
+/** The pass could not start: nothing was run and nothing written. */
+export class AdapterPassRefused extends Error {}
+
+const readRecord = (path: string): QualificationRecord | undefined => {
+  try {
+    const r = JSON.parse(readFileSync(path, "utf8")) as QualificationRecord;
+    return r.schema === QUALIFICATION_RECORD_SCHEMA ? r : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The run of each LV2 plugin of the state whose probe ended well (one that did not has no verdict a run could decide), at
+ * each cell. Each record is written whole as its plugin ends.
+ */
+export function adapterPass(ctx: SyncContext, state: SyncState, options: AdapterPassOptions = {}): AdapterPassResult {
+  const read = hostVersions(ctx.env, options.versions);
+  if (!read.ok) throw new AdapterPassRefused(read.error);
+  if (!(options.jackdPresent ?? jackdInstalled(ctx.env))) throw new AdapterPassRefused(`no jackd on the path: ${NO_PRIVATE_SERVER}, and the device's own JACK server is never used for this`);
+  const { versions } = read;
+  const starter = options.jack ?? startPrivateJack;
+  const runs = options.runs ?? SPAWNED_ADMISSIONS;
+  const now = options.now ?? (() => new Date().toISOString());
+  const servers = new Map<string, PrivateJack>();
+  const serverFor = (cell: GridCell): PrivateJack | undefined => {
+    const key = cellKey(cell);
+    const had = servers.get(key);
+    if (had?.alive() === true) return had;
+    had?.stop();
+    servers.delete(key);
+    const fresh = starter(cell);
+    if (fresh !== undefined) servers.set(key, fresh);
+    return fresh;
+  };
+  const count = { measured: 0, already: 0, failed: 0 };
+  const limit = { [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000), [ADMIT_ADDRESS_KB_ENV]: String(Math.ceil(defaultAddressSpaceLimit() / 2 ** 10)) };
+  try {
+    for (const [key, entry] of Object.entries(state.entries)) {
+      if (entry.format !== "lv2") continue;
+      const files = digestFiles(entry.root, entry.files.map((f) => f.path), entry.files);
+      if (files === undefined || !files.every((f) => entry.files.some((x) => x.path === f.path && x.sha256 === f.sha256))) {
+        ctx.log(`${key}: its files changed since it was measured; the sync measures it whole`);
+        continue;
+      }
+      for (const plugin of entry.plugins) {
+        if (plugin.record === undefined || !plugin.record.endsWith(RECORD_SUFFIX)) continue;
+        const path = join(ctx.settings.qualificationDir, basename(plugin.record));
+        const record = readRecord(path);
+        if (record === undefined) {
+          ctx.log(`${plugin.uri}: its record does not read; no adapter run`);
+          count.failed++;
+          continue;
+        }
+        if (record.probe.outcome !== PROBE_OK) continue;
+        if (options.force !== true && adapterFinished(record, versions)) {
+          count.already++;
+          continue;
+        }
+        const started = Date.now();
+        const done = ADAPTER_PASS_CELLS.map((cell) => {
+          const server = serverFor(cell);
+          if (server === undefined) return { cell, run: { host: ADAPTER_HOST, measured: false, admitted: false, code: NO_PRIVATE_SERVER, params: {} } as HostAdmission };
+          const stateDir = mkdtempSync(join(tmpdir(), "plugin-qualify-adapter-state-"));
+          try {
+            const env = { ...ctx.env, ...limit, [ADMIT_STATE_DIR_ENV]: stateDir, LV2_PATH: ctx.settings.lv2Dirs.join(":"), JACK_DEFAULT_SERVER: server.name, JACK_NO_START_SERVER: "1" };
+            return { cell, run: admitUnderAdapter(record.plugin.id, runs, env) ?? ({ host: ADAPTER_HOST, measured: false, admitted: false, code: `${ADAPTER_HOST}.admission-failed`, params: {} } as HostAdmission) };
+          } finally {
+            rmSync(stateDir, { recursive: true, force: true });
+          }
+        });
+        const block = adapterBlockOf(done, versions, now());
+        writeFileWhole(path, `${JSON.stringify(mergeAdapterRun(record, block), null, 2)}\n`);
+        if (block.measured) count.measured++;
+        else count.failed++;
+        ctx.log(`${plugin.uri}: adapter ${block.measured ? (block.admitted ? "admitted" : `refused (${block.code ?? ""})`) : `not run (${block.code ?? ""})`} in ${((Date.now() - started) / 1000).toFixed(1)} s`);
+      }
+    }
+  } finally {
+    for (const s of servers.values()) s.stop();
+  }
+  return { ...count, versions };
+}