@openmixer/plugin-qualify 0.16.1 → 0.17.1

package/src/measurement-grid.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The measurement grid (#193): the cells, each one rate and one quantum, a plugin is measured at, and the runs of the
+ * probe runner that measure them. A host is judged at its own cell, so the grid a run takes is chosen from the hosts it
+ * judges; README "The measurement grid" states the three ways of choosing it and the order the cells are taken in.
+ *
+ * Pure: no file, no process. `probe-runner.ts` runs what `runnerInvocations` plans.
+ */
+import { GRID_CONTINUITY_QUANTUM } from "./qualify-declarations.js";
+
+/** One cell of the grid. */
+export interface GridCell {
+  readonly rate: number;
+  readonly quantum: number;
+}
+
+/** How the grid is chosen: the hosts' cells, the full product of the rates and quanta, or the cells named. */
+export type GridSpec = { readonly kind: "hosts" } | { readonly kind: "full" } | { readonly kind: "cells"; readonly cells: readonly GridCell[] };
+
+export const GRID_HOSTS: GridSpec = { kind: "hosts" };
+export const GRID_FULL: GridSpec = { kind: "full" };
+
+export const cellKey = (c: GridCell): string => `${String(c.rate)}/${String(c.quantum)}`;
+
+const positive = (t: string): number | undefined => {
+  const n = Number(t);
+  return /^\d+$/.test(t) && Number.isSafeInteger(n) && n > 0 ? n : undefined;
+};
+
+/** `hosts`, `full`, or `<rate>/<quantum>,...`; anything else is refused with what was wrong. */
+export function parseGridSpec(text: string): { ok: true; spec: GridSpec } | { ok: false; error: string } {
+  const t = text.trim();
+  if (t === "hosts") return { ok: true, spec: GRID_HOSTS };
+  if (t === "full") return { ok: true, spec: GRID_FULL };
+  const cells: GridCell[] = [];
+  for (const part of t.split(",").map((p) => p.trim())) {
+    const m = /^(\d+)\/(\d+)$/.exec(part);
+    const rate = m === null ? undefined : positive(m[1]!);
+    const quantum = m === null ? undefined : positive(m[2]!);
+    if (rate === undefined || quantum === undefined) {
+      return { ok: false, error: `the grid is hosts, full, or cells as <rate>/<quantum>, comma-separated; "${part}" is none of them` };
+    }
+    cells.push({ rate, quantum });
+  }
+  return { ok: true, spec: { kind: "cells", cells: unique(cells) } };
+}
+
+function unique(cells: readonly GridCell[]): GridCell[] {
+  const seen = new Set<string>();
+  return cells.filter((c) => (seen.has(cellKey(c)) ? false : (seen.add(cellKey(c)), true)));
+}
+
+const byRateThenQuantum = (a: GridCell, b: GridCell): number => a.rate - b.rate || a.quantum - b.quantum;
+
+/**
+ * The cells of a grid, in the order they are taken: for `hosts`, each host's own cell in the order the hosts are given,
+ * then `GRID_CONTINUITY_QUANTUM` at every rate; for `full`, those cells first as well, then the rest of the product by
+ * rate and quantum; for named cells, as named. A cell is listed once.
+ */
+export function gridCells(
+  spec: GridSpec,
+  context: { readonly rates: readonly number[]; readonly quanta: readonly number[]; readonly hosts: readonly GridCell[] },
+): GridCell[] {
+  if (spec.kind === "cells") return unique(spec.cells);
+  const continuity = [...context.rates].sort((a, b) => a - b).map((rate) => ({ rate, quantum: GRID_CONTINUITY_QUANTUM }));
+  const lead = unique([...context.hosts, ...continuity]);
+  if (spec.kind === "hosts") return lead;
+  const product = context.rates.flatMap((rate) => context.quanta.map((quantum) => ({ rate, quantum }))).sort(byRateThenQuantum);
+  const inProduct = new Set(product.map(cellKey));
+  // the full grid is the product: a host's cell outside --rates x --quanta is not part of it
+  return unique([...lead.filter((c) => inProduct.has(cellKey(c))), ...product]);
+}
+
+/** The first `budget` cells, or every one when the budget is absent or 0. */
+export function budgetCells(cells: readonly GridCell[], budget: number | undefined): GridCell[] {
+  return budget === undefined || budget === 0 ? [...cells] : cells.slice(0, budget);
+}
+
+/** One run of the probe runner: the rates it is given, its quantum, and the cells it stands for. */
+export interface RunnerInvocation {
+  readonly rates: readonly number[];
+  readonly quantum: number;
+  readonly cells: readonly GridCell[];
+}
+
+/**
+ * The runs that measure `cells`. A CLAP plugin is run once per quantum, at every rate of the grid at that quantum (the
+ * prober takes a list of rates and one block size). An LV2 plugin is run once per cell: plugin-hostd's runner measures
+ * an LV2 plugin at one rate a run, the highest of the rates it is given, so a list would measure only that one.
+ */
+export function runnerInvocations(format: string, cells: readonly GridCell[]): RunnerInvocation[] {
+  if (format !== "clap") return cells.map((c) => ({ rates: [c.rate], quantum: c.quantum, cells: [c] }));
+  const byQuantum = new Map<number, GridCell[]>();
+  for (const c of cells) byQuantum.set(c.quantum, [...(byQuantum.get(c.quantum) ?? []), c]);
+  return [...byQuantum.entries()].map(([quantum, at]) => ({ rates: [...new Set(at.map((c) => c.rate))].sort((a, b) => a - b), quantum, cells: at }));
+}

package/src/memory-bound.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The memory bound of a run (#193). A sampler loading its library can take all of a small machine's memory; unbounded,
+ * the kernel's out-of-memory killer ends it (or something else) and the run is a crash nobody can tell from a bug. So
+ * every run is bounded: the runner's data limit (`--data-bytes`, `RLIMIT_DATA` on the measuring child), with the
+ * interposer told to exit `MEMORY_BOUND_EXIT_STATUS` the moment an allocation is refused under it.
+ *
+ * A run is out of memory when one of its steps says the child exited with that status, or was killed by a `SIGKILL`
+ * the runner did not send (its own deadline kill is `probe.timeout`, never `probe.crashed`): the kernel's killer.
+ */
+import { totalmem } from "node:os";
+
+import type { ProbeOutput } from "./probe-output.js";
+import { MEMORY_BOUND_EXIT_STATUS, MEMORY_LIMIT_RAM_FRACTION } from "./qualify-declarations.js";
+
+/** How the bound is applied: the runner's data limit on the child. */
+export const MEMORY_BOUND_MECHANISM = "rlimit-data";
+
+/** The outcome of a run, and of each of its cells, that outgrew the bound. */
+export const PROBE_OOM = "probe.oom";
+
+export interface MemoryBound {
+  readonly bytes: number;
+  readonly mechanism: typeof MEMORY_BOUND_MECHANISM;
+}
+
+const UNITS: Readonly<Record<string, number>> = { "": 1, K: 2 ** 10, M: 2 ** 20, G: 2 ** 30, T: 2 ** 40 };
+
+/** `off`, a number of bytes, or one with a K, M, G or T suffix (powers of two: K is 2 ** 10 bytes). */
+export function parseMemoryLimit(text: string): { ok: true; bytes: number | "off" } | { ok: false; error: string } {
+  const t = text.trim();
+  if (t === "off") return { ok: true, bytes: "off" };
+  const m = /^(\d+)([KMGT]?)(?:i?B)?$/i.exec(t);
+  const bytes = m === null ? NaN : Number(m[1]) * UNITS[m[2]!.toUpperCase()]!;
+  if (!Number.isSafeInteger(bytes) || bytes <= 0) return { ok: false, error: `the memory limit is off, or bytes as 2147483648, 2048M or 2G; "${t}" is neither` };
+  return { ok: true, bytes };
+}
+
+/** The default bound: `MEMORY_LIMIT_RAM_FRACTION` of the machine's RAM. */
+export function defaultMemoryLimit(ramBytes: number = totalmem()): number {
+  return Math.floor(ramBytes * MEMORY_LIMIT_RAM_FRACTION);
+}
+
+/** The bound a setting names: `undefined` (the default), `off`, or a size. */
+export function memoryBoundOf(setting: number | "off" | undefined, ramBytes?: number): MemoryBound | undefined {
+  if (setting === "off") return undefined;
+  return { bytes: setting ?? defaultMemoryLimit(ramBytes), mechanism: MEMORY_BOUND_MECHANISM };
+}
+
+/** Whether a run under `bound` ended out of memory: the interposer's exit status, or a SIGKILL that was no deadline's. */
+export function outOfMemory(output: ProbeOutput, bound: MemoryBound | undefined): boolean {
+  if (bound === undefined) return false;
+  return output.steps.some((s) => s.exitStatus === MEMORY_BOUND_EXIT_STATUS || (s.signal === "SIGKILL" && s.outcome === "probe.crashed"));
+}

package/src/probe-judge.ts

@@ -38,6 +38,7 @@ import { PROBE_NOT_ATTEMPTED, PROBE_OK, type ProbeGridPoint, type ProbeOutput }
 import type { QualifyVerdict } from "./qualify-cli.js";
 import { RATING_SEVERITY, worstRating, type SuitabilityRating } from "./rating.js";
 import type { IntegrityMeasurement, VoicesHeld } from "./measurement/format.js";
+import { PROBE_OOM } from "./memory-bound.js";
 
 /** Facts of the descriptor, which the probe output repeats none of. */
 export interface JudgeFacts {
@@ -197,8 +198,25 @@ function decidingOf(reasons: readonly RecordReason[], rating: SuitabilityRating)
   return [...reasons].sort((a, b) => RATING_SEVERITY[b.rating] - RATING_SEVERITY[a.rating]).find((r) => r.rating === rating);
 }
 
+/** The grid point at a host's own cell, whatever its outcome; `undefined` when the grid does not hold that cell. */
+function cellOf(output: ProbeOutput, profile: HostProfile): ProbeGridPoint | undefined {
+  return output.grid.find((p) => p.rate === profile.cost.rate && p.quantum === profile.cost.quantum);
+}
+
+const memoryParams = (p: ProbeGridPoint): Record<string, number | string> =>
+  p.memoryLimit === undefined ? {} : { memoryLimitBytes: p.memoryLimit.bytes, memoryLimitMechanism: p.memoryLimit.mechanism };
+
+/**
+ * The cost reasons at the host's rate and quantum. A cell that was measured is read against the host's budget; a cell
+ * whose run did not end well is `unknown` with that run's outcome (`probe.oom`, `probe.crashed`); only a cell the grid
+ * does not hold is `hosting.cost.unmeasured-at-rate-and-quantum`.
+ */
 function costOf(output: ProbeOutput, profile: HostProfile): HostJudgment["cost"] {
   const { rate, quantum } = profile.cost;
+  const cell = cellOf(output, profile);
+  if (cell !== undefined && cell.outcome !== PROBE_OK && cell.outcome !== PROBE_NOT_ATTEMPTED) {
+    return { rate, quantum, reasons: [{ dimension: "cost", rating: "unknown", code: cell.outcome, params: { rate, quantum, ...memoryParams(cell) } }] };
+  }
   const reasons = hostingCostReasons(
     { cpuCost: { perRateQuantum: gridCostReadings(output.grid, PROBE_OK) } },
     { rate, quantum, profile },
@@ -215,7 +233,8 @@ function costOf(output: ProbeOutput, profile: HostProfile): HostJudgment["cost"]
  */
 function failedOutcome(output: ProbeOutput): string | undefined {
   if (output.run.outcome !== PROBE_OK) return output.run.outcome;
-  return output.grid.find((p) => p.outcome !== PROBE_OK && p.outcome !== PROBE_NOT_ATTEMPTED)?.outcome;
+  // a cell that outgrew the memory bound is a recorded outcome of that cell, judged per host below, not the run's end
+  return output.grid.find((p) => p.outcome !== PROBE_OK && p.outcome !== PROBE_NOT_ATTEMPTED && p.outcome !== PROBE_OOM)?.outcome;
 }
 
 /**
@@ -257,6 +276,11 @@ export function judgeProbeOutput(output: ProbeOutput, profiles: readonly HostPro
       const notes = noteSweepOfProbeOutput(output, rt);
       reasons = [...rtSafetyReasons(rt), ...noteSweepReasons(notes, facts.noteInputs ?? (notes.applicable ? 1 : 0))].map(asRecordReason);
     }
+    // the plugin did not run within the memory bound at this host's own rate and quantum: not hostable there as measured
+    const cell = cellOf(output, profile);
+    if (cell?.outcome === PROBE_OOM) {
+      reasons = [...reasons, { dimension: "memory", rating: "unknown", code: PROBE_OOM, params: { rate: cell.rate, quantum: cell.quantum, ...memoryParams(cell) } }];
+    }
     const admission = facts.admissions?.[profile.id];
     if (admission !== undefined && admittedHostOf(profile) !== undefined) {
       if (!admission.measured || !admission.admitted) {

package/src/probe-merge.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The runs of one plugin and one offer, made one probe output (#193). The grid takes several runs of the probe runner
+ * (one per quantum for a CLAP plugin, one per cell for an LV2 one); the judge and the record read one document. The
+ * merge is a translation, never a judgment:
+ *
+ * - the grid is every run's points, and, for a run that did not end `probe.ok`, a point at each of its cells that holds
+ *   none, carrying the run's outcome (and, for `probe.oom`, the bound it ran under), so no cell is silently absent;
+ * - the steps are every run's, in order; the run's time is the sum, and it is complete when every run was;
+ * - the run's outcome is the first that was not `probe.ok` among the runs that did not outgrow the bound; a run that
+ *   outgrew it leaves its cells `probe.oom` and the rest are still judged; when every run did, it is `probe.oom`;
+ * - `run.parts` names each run: its id, its outcome, its rates and quantum, its time.
+ *
+ * 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 { cellKey, type RunnerInvocation } from "./measurement-grid.js";
+import { PROBE_OK, readProbeOutput, type ProbeOutput } from "./probe-output.js";
+
+/** One run of the runner, as it was read. */
+export interface ProbeRunPart {
+  readonly bytes: Buffer;
+  readonly output: ProbeOutput;
+  readonly invocation: RunnerInvocation;
+}
+
+export class ProbeMergeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProbeMergeError";
+  }
+}
+
+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));
+  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) {
+      throw new ProbeMergeError(
+        `the runs of ${first.output.plugin.id} measured different things (${p.output.plugin.id}, ${p.output.binary.sha256.slice(0, 12)}, offer ${p.output.offer.id}): the plugin's files changed between them`,
+      );
+    }
+  }
+  const missingCell = (p: ProbeRunPart): boolean => p.invocation.cells.some((c) => !p.output.grid.some((g) => g.rate === c.rate && g.quantum === c.quantum));
+  if (parts.length === 1 && outcomes[0] === first.output.run.outcome && (outcomes[0] === PROBE_OK || !missingCell(first))) {
+    return { bytes: first.bytes, output: first.output };
+  }
+
+  const docs = parts.map((p) => JSON.parse(p.bytes.toString("utf8")) as Json);
+  const merged = structuredClone(docs[0]!);
+  const grid: Json[] = [];
+  const seen = new Set<string>();
+  const steps: unknown[] = [];
+  parts.forEach((p, i) => {
+    for (const point of (docs[i]!["grid"] as Json[] | undefined) ?? []) {
+      const key = cellKey({ rate: point["rate"] as number, quantum: point["quantum"] as number });
+      if (seen.has(key)) continue;
+      seen.add(key);
+      grid.push(point);
+    }
+    if (outcomes[i] !== PROBE_OK) {
+      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 } } : {}) });
+      }
+    }
+    steps.push(...((docs[i]!["steps"] as unknown[] | undefined) ?? []));
+  });
+  const judged = outcomes.filter((o) => o !== PROBE_OOM);
+  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),
+    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;
+  merged["grid"] = grid;
+  const bytes = Buffer.from(`${JSON.stringify(merged, null, 2)}\n`);
+  const read = readProbeOutput(bytes.toString("utf8"));
+  if (!read.ok) throw new ProbeMergeError(`the merged runs of ${first.output.plugin.id} do not read as a probe output (${read.code}): ${read.problem}`);
+  return { bytes, output: read.output };
+}

package/src/probe-output.ts

@@ -95,6 +95,8 @@ 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. */
+  readonly memoryLimit?: { readonly bytes: number; readonly mechanism: string };
 }
 
 export interface ProbeStep {
@@ -105,6 +107,9 @@ export interface ProbeStep {
   /** The hosting code the step carries when it says why a figure is absent (`hosting.latency.unmeasured`). */
   readonly hostingCode?: string;
   readonly detail?: string;
+  /** How the child ended, when this step is a child's end: its exit status, or the signal that killed it. */
+  readonly exitStatus?: number;
+  readonly signal?: string;
 }
 
 export interface ProbeIdleState {
@@ -301,9 +306,15 @@ 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`) }),
+    ...(o["memoryLimit"] === undefined ? {} : { memoryLimit: readMemoryLimit(o["memoryLimit"], `${where} memoryLimit`) }),
   };
 }
 
+function readMemoryLimit(v: unknown, where: string): { bytes: number; mechanism: string } {
+  const o = record(v, where);
+  return { bytes: posInt(o, "bytes", where), mechanism: str(o, "mechanism", where) };
+}
+
 function readStep(v: unknown, i: number): ProbeStep {
   const where = `steps[${i}]`;
   const o = record(v, where);
@@ -314,6 +325,8 @@ function readStep(v: unknown, i: number): ProbeStep {
     ...optional("quantum", o["quantum"] === undefined ? undefined : posInt(o, "quantum", where)),
     ...optional("hostingCode", nonEmptyString(o["hostingCode"])),
     ...optional("detail", nonEmptyString(o["detail"])),
+    ...optional("exitStatus", typeof o["exitStatus"] === "number" && Number.isInteger(o["exitStatus"]) ? o["exitStatus"] : undefined),
+    ...optional("signal", nonEmptyString(o["signal"])),
   };
 }
 

package/src/probe-runner.ts

@@ -25,6 +25,9 @@ import type { PluginTarget } from "./loader.js";
 import { SPAWNED_ADMISSIONS, admitPlugin, 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 type { MemoryBound } from "./memory-bound.js";
+import { mergeProbeRuns, ProbeMergeError } from "./probe-merge.js";
 import type { QualifyVerdict } from "./qualify-cli.js";
 import {
   CLAP_QUALIFY_TIMEOUT_S,
@@ -33,8 +36,10 @@ import {
   LV2_HOSTING_BLOCK_FRAMES,
   LV2_HOSTING_TIMEOUT_S,
   LV2_MEASURE_TOOL_NAME,
+  MEMORY_BOUND_EXIT_ENV,
   PROBE_RUNNER_DEFAULT,
   PROBE_RUNNER_ENV,
+  QUALIFY_QUANTA,
 } from "./qualify-declarations.js";
 
 export class ProbeRunnerError extends Error {
@@ -67,8 +72,14 @@ const spawnRunner: ProbeRun = (tool, args, env) => {
 };
 
 export interface ProbeTargetOptions {
-  /** The rates the plugin is measured at. */
+  /** The rates the plugin is measured at; with no `cells`, each at `CLAP_SWEEP_FRAMES`. */
   readonly rates: readonly number[];
+  /** The cells of the grid this plugin is measured at (`measurement-grid.ts`); each format's runs are planned from them. */
+  readonly cells?: readonly GridCell[];
+  /** Blocks of the CLAP sweep a cell; else `CLAP_SWEEP_BLOCKS`. The LV2 pass has a fixed shape. */
+  readonly blocks?: number;
+  /** The memory bound every run is held to; none (the runner's own default) when absent. */
+  readonly memory?: MemoryBound;
   /** Host extensions to offer beyond the prober's own (a CLAP run). */
   readonly offer?: readonly string[];
   /** The wall clock the runner gives one run, in seconds; else the format's declared one. */
@@ -80,7 +91,17 @@ export interface ProbeTargetOptions {
 
 /** The runner's arguments for a CLAP file; `child` is the prober the runner starts. */
 export function clapRunnerArgs(
-  options: { rates: readonly number[]; offer?: readonly string[]; wallS?: number; out: string; log: string; child: string },
+  options: {
+    rates: readonly number[];
+    quantum?: number;
+    blocks?: number;
+    dataBytes?: number;
+    offer?: readonly string[];
+    wallS?: number;
+    out: string;
+    log: string;
+    child: string;
+  },
   binaryPath: string,
   id: string | undefined,
 ): string[] {
@@ -91,12 +112,13 @@ export function clapRunnerArgs(
     "--rates",
     options.rates.join(","),
     "--quantum",
-    String(CLAP_SWEEP_FRAMES),
+    String(options.quantum ?? CLAP_SWEEP_FRAMES),
     "--blocks",
-    String(CLAP_SWEEP_BLOCKS),
+    String(options.blocks ?? CLAP_SWEEP_BLOCKS),
     ...(options.offer === undefined || options.offer.length === 0 ? [] : ["--offer", options.offer.join(",")]),
     "--wall-s",
     String(options.wallS ?? CLAP_QUALIFY_TIMEOUT_S),
+    ...(options.dataBytes === undefined ? [] : ["--data-bytes", String(options.dataBytes)]),
     "--out",
     options.out,
     "--log",
@@ -110,16 +132,20 @@ export function clapRunnerArgs(
  * The runner's arguments for an LV2 plugin, named as `lv2:<uri>` and measured by `lv2_measure`: the one this run
  * located when `child` names it, else the one the runner looks for where the packages install it.
  */
-export function lv2RunnerArgs(options: { rates: readonly number[]; wallS?: number; out: string; log: string; child?: string }, uri: string): string[] {
+export function lv2RunnerArgs(
+  options: { rates: readonly number[]; quantum?: number; dataBytes?: number; wallS?: number; out: string; log: string; child?: string },
+  uri: string,
+): string[] {
   return [
     "run",
     ...(options.child === undefined ? [] : ["--child", options.child]),
     "--rates",
     options.rates.join(","),
     "--quantum",
-    String(LV2_HOSTING_BLOCK_FRAMES),
+    String(options.quantum ?? LV2_HOSTING_BLOCK_FRAMES),
     "--wall-s",
     String(options.wallS ?? LV2_HOSTING_TIMEOUT_S),
+    ...(options.dataBytes === undefined ? [] : ["--data-bytes", String(options.dataBytes)]),
     "--out",
     options.out,
     "--log",
@@ -134,7 +160,7 @@ export interface ProbedTarget {
   readonly output: ProbeOutput;
 }
 
-function runOne(target: PluginTarget, options: ProbeTargetOptions): ProbedTarget {
+function runOne(target: PluginTarget, options: ProbeTargetOptions, invocation: RunnerInvocation): ProbedTarget {
   const env = options.env ?? process.env;
   const tool = probeRunnerTool(env);
   const work = mkdtempSync(join(tmpdir(), "plugin-qualify-probe-"));
@@ -145,20 +171,28 @@ function runOne(target: PluginTarget, options: ProbeTargetOptions): ProbedTarget
     let runEnv: Record<string, string | undefined> = { ...env };
     let expectedId: string;
     const wall = options.wallS === undefined ? {} : { wallS: options.wallS };
+    const bound = options.memory === undefined ? {} : { dataBytes: options.memory.bytes };
+    const at = { rates: invocation.rates, quantum: invocation.quantum, ...bound };
     if (target.format === "clap") {
       if (target.binaryPath === undefined) throw new ProbeRunnerError(`${target.uri}: no .clap to load; name the file or a directory holding it`);
       expectedId = target.uri.startsWith("urn:clap:") ? target.uri.slice("urn:clap:".length) : target.uri;
       const { tool: child, interposer } = clapQualifyTools(env, options.exists ?? existsSync);
-      args = clapRunnerArgs({ rates: options.rates, ...(options.offer === undefined ? {} : { offer: options.offer }), ...wall, out, log, child }, target.binaryPath, expectedId);
+      args = clapRunnerArgs(
+        { ...at, ...(options.blocks === undefined ? {} : { blocks: options.blocks }), ...(options.offer === undefined ? {} : { offer: options.offer }), ...wall, out, log, child },
+        target.binaryPath,
+        expectedId,
+      );
       runEnv = { ...env, LD_PRELOAD: interposer };
     } else {
       expectedId = target.uri;
       const child = locateNativeTool(LV2_MEASURE_TOOL_NAME, env, options.exists ?? existsSync).path;
       args = lv2RunnerArgs(
-        { rates: options.rates, ...wall, out, log, ...(child === undefined ? {} : { child }) },
+        { ...at, ...wall, out, log, ...(child === undefined ? {} : { child }) },
         target.uri,
       );
     }
+    // under a bound, the interposer ends the child the moment an allocation is refused, with the status that names it
+    if (options.memory !== undefined) runEnv = { ...runEnv, [MEMORY_BOUND_EXIT_ENV]: "1" };
     const r = (options.run ?? spawnRunner)(tool, args, runEnv);
     if (r.error !== undefined) {
       throw new ProbeRunnerError(`cannot run the probe runner "${tool}" (${r.error.message}): install plugin-hostd or set ${PROBE_RUNNER_ENV} to plugin-hostd-probe`);
@@ -186,9 +220,23 @@ function runOne(target: PluginTarget, options: ProbeTargetOptions): ProbedTarget
   }
 }
 
-/** The probe output of one target, through the runner. Throws {@link ProbeRunnerError} when there is none to judge. */
+/** The cells a target is measured at: the options' cells, else every rate at `CLAP_SWEEP_FRAMES`. */
+export function targetCells(options: Pick<ProbeTargetOptions, "rates" | "cells">): readonly GridCell[] {
+  return options.cells ?? options.rates.map((rate) => ({ rate, quantum: CLAP_SWEEP_FRAMES }));
+}
+
+/**
+ * The probe output of one target over its grid, through the runner: one run per quantum (CLAP) or per cell (LV2),
+ * merged into one document (`probe-merge.ts`). Throws {@link ProbeRunnerError} when a run leaves nothing to judge.
+ */
 export function probeTarget(target: PluginTarget, options: ProbeTargetOptions): ProbedTarget {
-  return runOne(target, options);
+  const parts = runnerInvocations(target.format, targetCells(options)).map((invocation) => ({ ...runOne(target, options, invocation), invocation }));
+  try {
+    return mergeProbeRuns(parts, options.memory);
+  } catch (e) {
+    if (e instanceof ProbeMergeError) throw new ProbeRunnerError(e.message);
+    throw e;
+  }
 }
 
 /** What the pass over a run's targets produced. */
@@ -210,7 +258,16 @@ export interface ProbePass {
  */
 export function qualifyTargets(
   targets: readonly PluginTarget[],
-  options: ProbeTargetOptions & { readonly profiles?: readonly HostProfile[]; readonly admissions?: AdmissionRuns },
+  options: ProbeTargetOptions & {
+    readonly profiles?: readonly HostProfile[];
+    readonly admissions?: AdmissionRuns;
+    /** How the grid is chosen; with it, each target's cells come from the hosts it is judged under. */
+    readonly grid?: GridSpec;
+    /** The quanta of a `full` grid; else `QUALIFY_QUANTA`. */
+    readonly quanta?: readonly number[];
+    /** At most this many cells a plugin, the first of the grid's order; 0 or absent is every cell. */
+    readonly cellsPerPluginBudget?: number;
+  },
 ): ProbePass {
   const profiles = options.profiles ?? [OPENMIXER_CONSOLE_PROFILE];
   const admissionRuns = options.admissions ?? SPAWNED_ADMISSIONS;
@@ -225,6 +282,11 @@ export function qualifyTargets(
       .flatMap((id) => (id === undefined ? [] : [shippedHostProfile(id)]))
       .filter((p): p is HostProfile => p !== undefined);
     const judgedProfiles = [...profiles, ...tierProfiles.filter((t) => !profiles.some((p) => p.id === t.id))];
+    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 })) });
+    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> = {};
     if (target.format === "lv2") {
@@ -246,7 +308,7 @@ export function qualifyTargets(
     const targetRuns: { bytes: Buffer; judgment: Judgment }[] = [];
     try {
       for (const { offer, profiles: forOffer } of byOffer.values()) {
-        const probed = probeTarget(target, { ...options, offer });
+        const probed = probeTarget(target, { ...options, ...measured, offer });
         const judgment = judgeProbeOutput(probed.output, forOffer, { admissions });
         targetRuns.push({ bytes: probed.bytes, judgment });
         for (const v of judgmentVerdicts(judgment)) judged.set(v.host, v);

package/src/qualification-record.ts

@@ -21,6 +21,8 @@ import type { Judgment, RecordReason } from "./probe-judge.js";
 import { sha256Hex, PROBE_OK, type ProbeGridPoint, type ProbeOutput } from "./probe-output.js";
 import type { VoicesHeld } from "./measurement/format.js";
 import { writeFileWhole } from "./whole-file.js";
+import { HOSTING_CODE } from "./hosting-codes.js";
+import { MEASUREMENT_UNMEASURED_REASONS } from "@openmixer/omx-contract";
 
 export const QUALIFICATION_RECORD_SCHEMA = "plugin-qualify.qualification-record/1";
 
@@ -89,6 +91,44 @@ export function unmeasuredFigures(output: ProbeOutput): readonly UnmeasuredFigur
     }));
 }
 
+/** A cell's latency when the run took no figure: the contract's unmeasured word and the hosting code a reader classifies by. */
+export interface UnmeasuredLatency {
+  readonly unmeasuredReason: string;
+  readonly code: string;
+}
+
+/** 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"> & {
+  readonly latency: NonNullable<ProbeGridPoint["latency"]> | 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 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"),
+  "probe.timeout": word("probeTimeout"),
+  "probe.refused-instantiation": word("refusedInstantiation"),
+  "probe.non-finite-output": word("nonFiniteOutput"),
+};
+
+/**
+ * Why a cell has no latency figure. A cell whose run failed: its outcome's word. A latency step at the cell that did not
+ * end well: the child's own reason, which the runner writes first in the step's detail, when it is a contract word,
+ * else `probe-error`. No latency step at all: the run did not take the figure (`not-attempted`), as a runner or a child
+ * older than the latency arm writes it.
+ */
+export function latencyOfCell(output: ProbeOutput, point: ProbeGridPoint): RecordGridPoint["latency"] {
+  if (point.latency !== undefined) return point.latency;
+  const code = HOSTING_CODE.latencyUnmeasured;
+  if (point.outcome !== PROBE_OK) return { unmeasuredReason: OUTCOME_WORD[point.outcome] ?? word("probeError"), code };
+  const step = output.steps.find((st) => st.step === "latency" && st.rate === point.rate && (st.quantum === undefined || st.quantum === point.quantum));
+  if (step === undefined) return { unmeasuredReason: word("notAttempted"), code };
+  const said = step.detail?.split(":")[0]?.trim() ?? "";
+  return { unmeasuredReason: UNMEASURED_WORDS.has(said) ? said : word("probeError"), code: step.hostingCode ?? code };
+}
+
 /**
  * What the running history made of the measured verdicts, for one host class: the second verdict beside the measured one.
  * Written by `plugin-qualify adjust --history`; the measured `verdicts` above are never changed by it. A record without the
@@ -136,7 +176,7 @@ export interface QualificationRecord {
    * {declaredFrames, measuredFrames}, `cost`, `rtSafety`, `noteSweep`), and the figures the run could not take, named.
    */
   readonly measurements: {
-    readonly grid: readonly ProbeGridPoint[];
+    readonly grid: readonly RecordGridPoint[];
     readonly behaviour?: Readonly<Record<string, unknown>>;
     readonly unmeasured?: readonly UnmeasuredFigure[];
   };
@@ -150,6 +190,8 @@ export interface QualificationRecord {
   readonly measuredAt: string;
   /** The second verdict, per host class of the history that was read; absent until `adjust --history` has run. */
   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>>;
   /** The probe output this record judged. */
   readonly probe: {
     readonly file: string;
@@ -227,7 +269,7 @@ export function buildQualificationRecord(
     tiers: tiersOf(judgment),
     cost: judgment.hosts.map((h) => ({ host: h.verdict.host, ...h.cost })),
     measurements: {
-      grid: o.grid,
+      grid: o.grid.map((p) => ({ ...p, latency: latencyOfCell(o, p) })),
       ...(o.behaviour === undefined ? {} : { behaviour: o.behaviour }),
       ...(unmeasuredFigures(o).length === 0 ? {} : { unmeasured: unmeasuredFigures(o) }),
     },