@openmixer/plugin-qualify 0.5.0 → 0.6.0

package/src/qualify-declarations.ts

@@ -41,6 +41,27 @@ export const BOOT_TIMEOUT_S = 120;
 /** Seconds one plugin's cost pass may take (a sustained tone runs longer than an impulse). */
 export const COST_TIMEOUT_S = 60;
 
+/**
+ * The soak's control sweep is bounded to musically sane ranges (spec §2a.4): a `units:db` port
+ * is swept at most this many dB either side of its default, and a strictly-positive-default
+ * linear port at most this ratio either side. Calf's linear gains reach 64x (+36 dB); a startup
+ * blast the sweep itself drives is not the plugin's. The measuring host reads both from the
+ * environment this package sets (`soakSweepEnv`), so the C default and this value cannot differ.
+ */
+export const SOAK_SWEEP_DB = 12;
+export const SOAK_SWEEP_RATIO = 4;
+
+/**
+ * A soak's wall-clock limit is SIZED, never fixed (spec §2a): the calibration soak's wall seconds
+ * per audio second, times the soak length, times this margin, plus this floor in seconds.
+ * 2026-10-01: a fixed 900 s cut ZamGEQ31's 51-minute wall at 192 kHz and read as "died".
+ */
+export const SOAK_TIMEOUT_MARGIN = 2;
+export const SOAK_TIMEOUT_FLOOR_S = 60;
+
+/** Audio seconds the calibration soak renders to measure the host's speed on this plugin and rate. */
+export const SOAK_CALIBRATION_S = 30;
+
 /**
  * The ONE setting that locates the CLAP scanner (spec §7): the environment variable that names
  * the `omx-clap-scan` binary, and what is run when it is unset (looked up on `PATH`).
@@ -52,12 +73,36 @@ export const CLAP_SCAN_TOOL_DEFAULT = "omx-clap-scan";
 export const CLAP_SCAN_TIMEOUT_S = 300;
 
 /**
- * The CLAP prober (`native/clap-qualify.c`) and the interposer it runs under (`native/rt-interpose.c`):
- * each located by one environment variable, else the package's own build in `native/build/`.
+ * The CLAP prober (`native/clap-qualify.c`), the LV2 measurer (`native/lv2-measure.c`) and the
+ * interposer both run under (`native/rt-interpose.c`): each located by one environment variable, else
+ * the first of `NATIVE_TOOL_DIRS` that holds it, else the package's own build in `native/build/`.
  */
 export const CLAP_QUALIFY_TOOL_ENV = "OMX_CLAP_QUALIFY";
+export const LV2_MEASURE_TOOL_ENV = "OMX_LV2_MEASURE";
 export const RT_INTERPOSE_ENV = "OMX_RT_INTERPOSE";
 
+/** The file names of the native tools, in every place they are looked for. */
+export const CLAP_QUALIFY_TOOL_NAME = "clap-qualify";
+export const LV2_MEASURE_TOOL_NAME = "lv2_measure";
+export const RT_INTERPOSE_NAME = "rt_interpose.so";
+
+/**
+ * The ONE list of the native tools the packages install, each with the setting that names it.
+ * `make -C native install` installs exactly these; a test holds the Makefile to the list.
+ */
+export const NATIVE_TOOLS: readonly { readonly name: string; readonly env: string }[] = [
+  { name: CLAP_QUALIFY_TOOL_NAME, env: CLAP_QUALIFY_TOOL_ENV },
+  { name: LV2_MEASURE_TOOL_NAME, env: LV2_MEASURE_TOOL_ENV },
+  { name: RT_INTERPOSE_NAME, env: RT_INTERPOSE_ENV },
+];
+
+/**
+ * Where the RPM and the DEB install the native tools: the libexec directory on Fedora,
+ * `/usr/lib/<package>` on Debian (policy keeps a package's private programs there). The packaging
+ * installs into exactly these; a test holds the spec and `debian/rules` to them.
+ */
+export const NATIVE_TOOL_DIRS: readonly string[] = ["/usr/libexec/plugin-qualify", "/usr/lib/plugin-qualify"];
+
 /** The CLAP sweep: blocks of `CLAP_SWEEP_FRAMES` frames per rate, every parameter moved through events. */
 export const CLAP_SWEEP_BLOCKS = 512;
 export const CLAP_SWEEP_FRAMES = 512;
@@ -65,6 +110,17 @@ export const CLAP_SWEEP_FRAMES = 512;
 /** Seconds one `.clap` may take to qualify at every rate before the prober is killed. */
 export const CLAP_QUALIFY_TIMEOUT_S = 120;
 
+/**
+ * The LV2 hosting pass (`lv2-measure.mjs`, the native `lv2_measure`): each plugin at the run's highest
+ * rate, in blocks of `LV2_HOSTING_BLOCK_FRAMES` frames, `LV2_HOSTING_LIFECYCLES` instantiate/destroy
+ * cycles and `LV2_HOSTING_REPEATS` swept RT-safety runs (the worst kept), under the noise stimulus:
+ * the figures openmixer's hosting sweep took. One plugin may take `LV2_HOSTING_TIMEOUT_S` seconds.
+ */
+export const LV2_HOSTING_BLOCK_FRAMES = 512;
+export const LV2_HOSTING_LIFECYCLES = 30;
+export const LV2_HOSTING_REPEATS = 3;
+export const LV2_HOSTING_TIMEOUT_S = 240;
+
 
 
 

package/src/tool-paths.ts

@@ -5,8 +5,17 @@
  * wherever it is installed (a checkout, an RPM's bundled node_modules, a pnpm store). The
  * tools are shipped RUNTIME artefacts, not dev scripts.
  */
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  CLAP_QUALIFY_TOOL_NAME,
+  LV2_MEASURE_TOOL_NAME,
+  NATIVE_TOOLS,
+  NATIVE_TOOL_DIRS,
+  RT_INTERPOSE_NAME,
+} from "./qualify-declarations.js";
+
 /**
  * `tools/` — `scan.py`, `benchmark.py`, `lv2-measure.mjs`, `hosting-sweep.mjs`. Resolved when a
  * console asks, never at import: a consumer that only reads this package's declarations from a
@@ -21,12 +30,44 @@ export function lv2MeasureToolPath(): string {
   return fileURLToPath(new URL("../tools/lv2-measure.mjs", import.meta.url));
 }
 
+/** The package's own build of the native tools (`make -C native`). */
+function nativeBuildDir(): string {
+  return fileURLToPath(new URL("../native/build/", import.meta.url));
+}
+
 /** The package's own build of the CLAP prober (`make -C native`). */
 export function clapQualifyToolPath(): string {
-  return fileURLToPath(new URL("../native/build/clap-qualify", import.meta.url));
+  return join(nativeBuildDir(), CLAP_QUALIFY_TOOL_NAME);
 }
 
 /** The package's own build of the interposer the CLAP prober runs under. */
 export function rtInterposePath(): string {
-  return fileURLToPath(new URL("../native/build/rt_interpose.so", import.meta.url));
+  return join(nativeBuildDir(), RT_INTERPOSE_NAME);
+}
+
+/** The package's own build of the LV2 measurer (`make -C native`). */
+export function lv2MeasureNativePath(): string {
+  return join(nativeBuildDir(), LV2_MEASURE_TOOL_NAME);
+}
+
+/** Where a native tool is looked for when no setting names it, in order: the installed directories, then the own build. */
+export function nativeToolCandidates(name: string): string[] {
+  return [...NATIVE_TOOL_DIRS, nativeBuildDir()].map((dir) => join(dir, name));
+}
+
+/**
+ * One of `NATIVE_TOOLS`: its setting when set (and only that), else the first candidate that exists.
+ * `path` is absent when none does; `looked` is every place tried, for the refusal to name.
+ */
+export function locateNativeTool(
+  name: string,
+  env: Readonly<Record<string, string | undefined>>,
+  exists: (path: string) => boolean,
+): { readonly path?: string; readonly looked: readonly string[]; readonly setting: string } {
+  const setting = NATIVE_TOOLS.find((t) => t.name === name)?.env;
+  if (setting === undefined) throw new Error(`${name} is not one of NATIVE_TOOLS`);
+  const v = env[setting];
+  const looked = v === undefined || v === "" ? nativeToolCandidates(name) : [v];
+  const path = looked.find((p) => exists(p));
+  return { ...(path === undefined ? {} : { path }), looked, setting };
 }

package/tools/benchmark.py

@@ -1088,13 +1088,66 @@ PARAMS = "http://lv2plug.in/ns/ext/parameters#"
 WORKER = "http://lv2plug.in/ns/ext/worker#"
 
 
+LV2_WORKER_SUCCESS = 0
+LV2_WORKER_ERR_NO_SPACE = 3
+
+
+class WorkerQueue:
+    """The host half of `worker:schedule`: jobs are QUEUED, and run between blocks, off `run()`.
+
+    Spec 2a (`2026-09-25-plugin-qualify.md`): a schedule that accepts a job and
+    drops it measures an UNBUILT plugin — the Hex Chain amp read 0.9 us/sample that way against 5.4
+    built. After every block the host calls `pump(interface)`: the plugin's `work()` for each
+    queued job, then `work_response()` with whatever it answered, then `end_run()` once every answer
+    is delivered (the LV2 worker's order), all before the next block. Pure Python on purpose: the ctypes glue in `_Host` only adapts to it.
+    """
+
+    def __init__(self):
+        self.jobs = []
+        self.reset()
+
+    def reset(self):
+        self.jobs = []
+        self._jobs_run = 0
+        self._responses = 0
+        self._dropped = 0
+
+    def schedule(self, data):
+        self.jobs.append(bytes(data))
+        return LV2_WORKER_SUCCESS
+
+    def pump(self, interface):
+        """Drive one between-blocks turn. `interface` is None when the plugin exports no
+        LV2_Worker_Interface: its jobs are then DROPPED and counted as dropped, never as done."""
+        if interface is None:
+            self._dropped += len(self.jobs)
+            self.jobs = []
+            return
+        jobs, self.jobs = self.jobs, []
+        answers = []
+
+        def respond(data):
+            answers.append(bytes(data))
+            return LV2_WORKER_SUCCESS
+
+        for data in jobs:
+            interface.work(data, respond)
+            self._jobs_run += 1
+        for data in answers:
+            interface.work_response(data)
+            self._responses += 1
+        interface.end_run()
+
+    def stats(self):
+        return {"jobs": self._jobs_run, "responses": self._responses, "dropped": self._dropped}
+
+
 class _Host:
     """The minimal offline LV2 host the probe needs: a urid map, host options
     (sample rate + block sizes — DPF-based plugins refuse to instantiate without
-    them), block-length guarantees, and a stub worker schedule that accepts jobs
-    but never runs them (enough to satisfy `worker:schedule` as a required
-    feature; a plugin whose latency depends on completed worker jobs simply
-    reports its resting value). All ctypes callbacks/structs are kept as
+    them), block-length guarantees, and a REAL worker (`WorkerQueue`: the host runs the
+    plugin's work() between blocks and delivers its answers — call `pump` after every
+    block). All ctypes callbacks/structs are kept as
     attributes so nothing is garbage-collected while plugins hold pointers.
     """
 
@@ -1113,7 +1166,9 @@ class _Host:
 
         self._map_cb = map_fn(lambda _h, uri: self.map_uri(uri))
         self._unmap_cb = unmap_fn(lambda _h, urid: self._unmap(urid))
-        self._sched_cb = sched_fn(lambda _h, _size, _data: 0)  # LV2_WORKER_SUCCESS
+        self.worker = WorkerQueue()
+        self._sched_cb = sched_fn(
+            lambda _h, size, data: self.worker.schedule(ctypes.string_at(data, size) if size else b""))
 
         class UridMap(ctypes.Structure):
             _fields_ = [("handle", ctypes.c_void_p), ("map", map_fn)]
@@ -1183,6 +1238,56 @@ class _Host:
         self.block = block
         self.seq_urid = self.map_uri(f"{ATOM}Sequence")
 
+    def worker_interface(self, instance):
+        """The plugin's LV2_Worker_Interface as an object `WorkerQueue.pump` drives, or None when
+        it exports none (its jobs are then counted dropped). The ctypes layout is
+        LV2_Worker_Interface {work, work_response, end_run}."""
+        import ctypes
+
+        respond_fn = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p)
+        work_fn = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, respond_fn, ctypes.c_void_p,
+                                   ctypes.c_uint32, ctypes.c_void_p)
+        response_fn = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_uint32, ctypes.c_void_p)
+        end_fn = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p)
+
+        class Interface(ctypes.Structure):
+            _fields_ = [("work", work_fn), ("work_response", response_fn), ("end_run", end_fn)]
+
+        try:
+            ext = instance.get_extension_data(self.world.new_uri(f"{WORKER}interface"))
+            if not ext:
+                return None
+            iface = ctypes.cast(ext, ctypes.POINTER(Interface)).contents
+            handle = ctypes.c_void_p(instance.get_handle())
+        except (AttributeError, TypeError, ValueError):
+            return None
+
+        def keep(buf):
+            return ctypes.create_string_buffer(bytes(buf), len(buf))
+
+        class Adapter:
+            def work(self_, data, respond):
+                def cb(_h, size, ptr):
+                    return respond(ctypes.string_at(ptr, size) if size else b"")
+
+                cfn = respond_fn(cb)
+                buf = keep(data)
+                iface.work(handle, cfn, None, len(data), ctypes.cast(buf, ctypes.c_void_p))
+
+            def work_response(self_, data):
+                buf = keep(data)
+                iface.work_response(handle, len(data), ctypes.cast(buf, ctypes.c_void_p))
+
+            def end_run(self_):
+                if iface.end_run:
+                    iface.end_run(handle)
+
+        return Adapter()
+
+    def pump(self, instance_interface):
+        """After a block, between blocks: run the plugin's worker (see WorkerQueue.pump)."""
+        self.worker.pump(instance_interface)
+
     def map_uri(self, uri):
         u = uri.decode() if isinstance(uri, bytes) else str(uri)
         if u not in self.urids:
@@ -1211,6 +1316,7 @@ def probe_one(host, uri, symbol, cycles=DEFAULT_RUN_CYCLES):
     plugin = host.world.get_all_plugins().get_by_uri(host.world.new_uri(uri))
     if plugin is None:
         return None, "not installed"
+    host.worker.reset()
     instance = lilv.Instance(plugin, float(host.rate), host.features)
     if not instance.instance:
         # a required feature we don't provide, or the plugin vetoed the rate.
@@ -1243,9 +1349,11 @@ def probe_one(host, uri, symbol, cycles=DEFAULT_RUN_CYCLES):
         instance.connect_port(i, buf)
     if latency_buf is None:
         return None, f"latency port {symbol!r} not found"
+    iface = host.worker_interface(instance)
     instance.activate()
     for _ in range(cycles):
         instance.run(host.block)
+        host.pump(iface)
     instance.deactivate()
     return float(latency_buf[0]), None
 
@@ -1279,6 +1387,7 @@ def instantiate_connected(host, plugin, overrides=None):
 
     import lilv
 
+    host.worker.reset()
     instance = lilv.Instance(plugin, float(host.rate), host.features)
     if not instance.instance:
         del instance.instance  # avoid lilv.py's NULL deref in __del__
@@ -1346,6 +1455,7 @@ def render(host, plugin, n_blocks, impulse=True, overrides=None, preroll_blocks=
     out_buf = buffers[audio_out[0]]
     captured = np.empty(n_blocks * block, dtype=np.float32)
 
+    iface = host.worker_interface(instance)
     instance.activate()
     if preroll_blocks:
         phase = 2.0 * np.pi * PREROLL_TONE_HZ / float(host.rate)
@@ -1354,12 +1464,14 @@ def render(host, plugin, n_blocks, impulse=True, overrides=None, preroll_blocks=
             in_buf[:] = PREROLL_TONE_AMP * np.sin(
                 phase * np.arange(start, start + block, dtype=np.float32))
             instance.run(block)  # output discarded: this only opens the plugin up
+            host.pump(iface)
     in_buf[:] = 0.0
     if impulse:
         in_buf[0] = 1.0  # 1.0 at frame 0 of the first block only
     for blk in range(n_blocks):
         instance.run(block)
         captured[blk * block:(blk + 1) * block] = out_buf
+        host.pump(iface)
         in_buf[:] = 0.0  # every subsequent block is silence
     instance.deactivate()
     return captured, None
@@ -1518,6 +1630,7 @@ def cost_one(host, uri, warmup=DEFAULT_COST_WARMUP, max_blocks=DEFAULT_COST_BLOC
             buf[:] = sig
 
     times = []
+    iface = host.worker_interface(instance)
     instance.activate()
     gc_was_on = gc.isenabled()
     gc.disable()
@@ -1528,6 +1641,7 @@ def cost_one(host, uri, warmup=DEFAULT_COST_WARMUP, max_blocks=DEFAULT_COST_BLOC
             t0 = clock()
             run(block)
             times.append(clock() - t0)
+            host.pump(iface)  # the plugin's worker runs between blocks, off the timed run()
             blk += 1
         spent = 0
         budget = int(target_seconds * 1e9)
@@ -1537,6 +1651,7 @@ def cost_one(host, uri, warmup=DEFAULT_COST_WARMUP, max_blocks=DEFAULT_COST_BLOC
             t0 = clock()
             run(block)
             dt = clock() - t0
+            host.pump(iface)
             times.append(dt)
             spent += dt
             timed += 1
@@ -1553,7 +1668,8 @@ def cost_one(host, uri, warmup=DEFAULT_COST_WARMUP, max_blocks=DEFAULT_COST_BLOC
     if not np.all(np.isfinite(out_buf)):
         return {"error": "non-finite output"}
     return {"blockTimesNs": times,
-            "silentOutput": bool(np.max(np.abs(out_buf)) == 0.0)}
+            "silentOutput": bool(np.max(np.abs(out_buf)) == 0.0),
+            "worker": host.worker.stats()}
 
 
 def control_ranges(host, plugin, symbols):
@@ -1668,6 +1784,10 @@ def worker_main(rate, block, measure=False, cost=False, cpu=None,
                     continue
                 if res.get("silentOutput"):
                     record["silentOutput"] = True
+                # what the host did with the plugin's worker, so a cost read can be told apart
+                # from an unbuilt plugin's (jobs and dropped are counts, never a verdict).
+                if "worker" in res:
+                    record["worker"] = res["worker"]
                 print(json.dumps({"uri": uri,
                                   "nsPerSample": record["nsPerSampleMedian"],
                                   "cost": record}), flush=True)

package/tools/lv2-measure.mjs

@@ -6,7 +6,10 @@
  * measurement document.
  *
  * Standalone by construction: it needs `python3` with the `lilv` bindings, the two probers
- * next to this file (`scan.py`, `benchmark.py`), and an LV2 world to look at. It does not
+ * next to this file (`scan.py`, `benchmark.py`), and an LV2 world to look at; the hosting
+ * dimensions need the package's native measurer and interposer (`lv2_measure`,
+ * `rt_interpose.so`), each its setting (`OMX_LV2_MEASURE`, `OMX_RT_INTERPOSE`), else where the
+ * package installs it, else `native/build` (`make -C native`). It does not
  * need the OpenMixer engine, its server, PipeWire, JACK, an audio interface, or root. Nothing
  * it writes is openmixer-shaped — the output is the interchange format described in
  * `src/measurement/format.ts`, which any LV2 host can read.
@@ -22,6 +25,7 @@
  * pnpm build                       # this shell reads the compiled dist/
  * node tools/lv2-measure.mjs --rates 48000,96000 --out measurements.json --run
  * node tools/lv2-measure.mjs --rates 48000 --dimensions latency --dry-run
+ * node tools/lv2-measure.mjs --rates 48000 --dimensions stability,rtSafety,features --plugins <uri> --run
  * ```
  *
  * `--run` (or `LV2_MEASURE_RUN=1`) is required to probe: the passes instantiate and execute
@@ -34,9 +38,9 @@
  * `@progress `. A supervising process (the OpenMixer console's Setup screen) parses those and
  * ignores everything else, so the human log stays readable.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { hostname } from "node:os";
+import { constants, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -45,13 +49,18 @@ import {
   assembleDocument,
   buildPipeline,
   collectHostFacts,
+  HOSTING_PASS_DIMENSIONS,
+  hostingLine,
   INITIAL_PROGRESS,
   parseMeasureArgs,
   parseProbeProgress,
   serialiseMeasurementDocument,
   TOOL_NAME,
   TOOL_VERSION,
+  urisFromScan,
 } from "../dist/measurement/index.js";
+import { LV2_HOSTING_TIMEOUT_S, LV2_MEASURE_TOOL_NAME, RT_INTERPOSE_NAME } from "../dist/qualify-declarations.js";
+import { locateNativeTool } from "../dist/tool-paths.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -60,7 +69,10 @@ const HELP = `${TOOL_NAME} ${TOOL_VERSION} — measure LV2 plugin latency and CP
   --rates 48000,96000     REQUIRED. Sample rates to measure at. There is no default:
                           a figure without a stated rate is not a measurement.
   --dimensions latency,cost
-                          What to measure (default: both).
+                          What to measure (default: latency,cost); also any of
+                          stability,rtSafety,features, the hosting pass (the native lv2_measure
+                          under the interposer, one process per plugin).
+  --plugins URI,URI       The hosting pass measures only these, and needs no scan.
   --out PATH              Where the document goes (default: stdout).
   --scan PATH             Reuse an existing prober scan instead of scanning.
   --work-dir PATH         Where intermediates go (default: alongside --out, or a temp dir).
@@ -84,6 +96,45 @@ function readJson(path) {
   return JSON.parse(readFileSync(path, "utf8"));
 }
 
+/** The native measurer and its interposer, located; absent, the run is refused naming where it looked. */
+function hostingTools() {
+  const at = (name) => {
+    const found = locateNativeTool(name, process.env, existsSync);
+    if (found.path === undefined) {
+      fail(`no ${name} at ${found.looked.join(", ")}: install the plugin-qualify package, build it with make -C native, or set ${found.setting}`);
+    }
+    return found.path;
+  };
+  return { tool: at(LV2_MEASURE_TOOL_NAME), interposer: at(RT_INTERPOSE_NAME) };
+}
+
+/** The hosting pass: the measurer once per plugin, each in its own process, its lines written as JSONL. */
+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], {
+      encoding: "utf8",
+      env: { ...process.env, ...step.env },
+      stdio: ["ignore", "pipe", "inherit"],
+      timeout: LV2_HOSTING_TIMEOUT_S * 1000,
+      maxBuffer: 16 << 20,
+    });
+    if (r.error !== undefined && r.error.code !== "ETIMEDOUT") throw new Error(`hosting: cannot run ${step.command}: ${r.error.message}`);
+    const line = hostingLine(uri, {
+      status: r.status,
+      ...(r.signal ? { signalNumber: constants.signals[r.signal] } : {}),
+      ...(r.error?.code === "ETIMEDOUT" ? { timedOut: true } : {}),
+      stdout: r.stdout ?? "",
+    });
+    process.stderr.write(`  ${uri}: exit ${line.exit}\n`);
+    onProgress(step, { kind: "plugin" });
+    lines.push(line);
+  }
+  writeFileSync(step.produces, lines.map((l) => `${JSON.stringify(l)}\n`).join(""));
+  return lines;
+}
+
 /** Run one pipeline step, forwarding its stderr and counting the plugins it reports. */
 function runStep(step, onProgress) {
   return new Promise((settle, reject) => {
@@ -124,14 +175,17 @@ async function main() {
   if (!parsed.ok) fail(`${parsed.error}\n\n${HELP}`);
   const options = parsed.options;
 
-  const pipeline = buildPipeline(options);
+  const hosting = options.dimensions.some((d) => HOSTING_PASS_DIMENSIONS.includes(d));
+  const pipeline = buildPipeline(options, hosting ? hostingTools() : undefined);
 
   if (options.dryRun) {
     process.stderr.write(
       `${TOOL_NAME} would measure ${options.dimensions.join(" + ")} at ${options.rates.join(", ")} Hz\n`,
     );
     for (const step of pipeline.steps) {
-      process.stderr.write(`  ${step.id}: ${step.command} ${step.args.join(" ")}\n`);
+      const env = Object.entries(step.env ?? {}).map(([k, v]) => `${k}=${v} `).join("");
+      const each = step.perPlugin ? `<each of ${options.plugins?.join(", ") ?? "the scan's plugins"}> ` : "";
+      process.stderr.write(`  ${step.id}: ${env}${step.command} ${each}${step.args.join(" ")}\n`);
     }
     return;
   }
@@ -162,15 +216,22 @@ async function main() {
   const startedAt = Date.now();
   const measuredAt = new Date().toISOString();
   emit({ step: "start", steps: pipeline.steps.map((s) => s.id) });
+  let hostingLines;
   for (const step of pipeline.steps) {
     process.stderr.write(`== ${step.id}\n`);
-    await runStep(step, onProgress);
+    if (step.perPlugin) {
+      const uris = options.plugins ?? urisFromScan(readJson(pipeline.hostingScan));
+      hostingLines = runHosting(step, uris, onProgress);
+    } else {
+      await runStep(step, onProgress);
+    }
   }
   const elapsedSeconds = (Date.now() - startedAt) / 1000;
 
   const document = assembleDocument({
     options,
-    catalog: readJson(pipeline.finalCatalog),
+    ...(pipeline.finalCatalog === undefined ? {} : { catalog: readJson(pipeline.finalCatalog) }),
+    ...(hostingLines === undefined ? {} : { hosting: hostingLines }),
     costProvenance:
       pipeline.costProvenance !== undefined && existsSync(pipeline.costProvenance)
         ? readJson(pipeline.costProvenance)
@@ -191,8 +252,14 @@ async function main() {
   if (options.outPath === undefined) process.stdout.write(serialised);
   else writeFileSync(resolve(options.outPath), serialised);
 
+  const hostingFigure = (block) => block !== undefined && block.unmeasuredReason === undefined;
   const measured = document.plugins.filter(
-    (p) => Object.keys(p.latency?.perRate ?? {}).length > 0 || Object.keys(p.cost?.perRate ?? {}).length > 0,
+    (p) =>
+      Object.keys(p.latency?.perRate ?? {}).length > 0 ||
+      Object.keys(p.cost?.perRate ?? {}).length > 0 ||
+      hostingFigure(p.stability) ||
+      hostingFigure(p.rtSafety) ||
+      hostingFigure(p.features),
   ).length;
   process.stderr.write(
     `${TOOL_NAME}: ${document.plugins.length} plugin(s), ${measured} with at least one figure, ` +