@openmixer/plugin-qualify 0.19.1 → 0.20.1

package/src/distributed-records.ts

@@ -12,8 +12,10 @@
  * treats the plugin as one it measured.
  */
 import { readFileSync, readdirSync } from "node:fs";
+import { machine } from "node:os";
 import { join, resolve } from "node:path";
 
+import { cellKey, type GridCell } from "./measurement-grid.js";
 import { clapPinUri, pinVerdictOf, type PinEntry } from "./pins-file.js";
 import { integrityOfProbeOutput } from "./probe-judge.js";
 import { readProbeOutput, sha256Hex } from "./probe-output.js";
@@ -60,6 +62,20 @@ export function hostClassOfBoard(model: string | undefined): string | undefined
   return m === null ? undefined : `rpi${m[1]!}`;
 }
 
+/** The architecture `uname -m` names, or `undefined` when it cannot be read. */
+export function readMachine(): string | undefined {
+  try {
+    return machine();
+  } catch {
+    return undefined;
+  }
+}
+
+/** The host class of a machine with no board name, by `uname -m`: `x86-64` for an x86_64 one; none for an architecture without a class. */
+export function hostClassOfMachine(arch: string | undefined): string | undefined {
+  return arch?.trim() === "x86_64" ? "x86-64" : undefined;
+}
+
 /** One distributed record, read: where it is, what it says, and the set it came with. */
 export interface DistributedRecord {
   readonly path: string;
@@ -156,26 +172,38 @@ export function outcomeOfVerdict(v: Pick<RecordVerdict, "measured" | "rating" |
   return v.rating === "unsuitable" ? "refused" : "unmeasured";
 }
 
+/** The cells a record's grid holds, by rate then quantum: where the set it came in was measured. */
+export function recordCells(record: Pick<QualificationRecord, "measurements">): GridCell[] {
+  const seen = new Map<string, GridCell>();
+  for (const p of record.measurements?.grid ?? []) seen.set(cellKey(p), { rate: p.rate, quantum: p.quantum });
+  return [...seen.values()].sort((a, b) => a.rate - b.rate || a.quantum - b.quantum);
+}
+
 /** What the layer makes of one item. */
 export type DistributedMatch =
   /** No distributed record names the plugin: it is measured, and nothing is said. */
   | { readonly status: "none" }
   /** Every reason a record found was not taken, one line each; the plugin is measured. */
   | { readonly status: "ignored"; readonly lines: readonly string[] }
-  | { readonly status: "applies"; readonly set: string; readonly records: readonly DistributedRecord[]; readonly files: readonly string[] };
+  /** A set applies; `lines` names every set tried before it and why it was passed over. */
+  | { readonly status: "applies"; readonly set: string; readonly records: readonly DistributedRecord[]; readonly files: readonly string[]; readonly lines: readonly string[] };
 
 /**
  * Whether the item is taken from the layer. The records that find it are tried one set at a time, in the order the
  * layer read them. Of a set, only the records whose every file is installed with the SHA-256 it recorded (computed
  * here by `digest`) count: a record of other bytes is another build of the plugin and is passed over. The set applies
  * when at least one record of these bytes holds a verdict for `host`, and none of those verdicts is one the source
- * could not measure; a set with no record of these bytes is a binary that differs.
+ * could not measure; a set with no record of these bytes is a binary that differs. A set is per machine class, rate
+ * and quantum: of these records, only the ones whose grid holds every cell in `cells` (the cells the sync runs at)
+ * count, so a set measured at another cell is passed over, naming the cells it was measured at, and never answers a
+ * sync at this one by the order its name sorts in (#317). No cells given asks nothing of the grid.
  */
 export function matchDistributed(
   layer: DistributedLayer,
   item: SyncItem,
   host: string,
   digest: (files: readonly string[]) => readonly FileDigest[] | undefined,
+  cells: readonly GridCell[] = [],
 ): DistributedMatch {
   const found = item.format === "clap" ? layer.clap.get(resolve(join(item.root, item.files[0]!))) : layer.lv2.get(item.uri ?? "");
   if (found === undefined || found.length === 0) return { status: "none" };
@@ -195,7 +223,16 @@ export function matchDistributed(
       say(`distributed: ${distributedUri(item, found.find((r) => r.set === set)!)}: binary differs`);
       continue;
     }
-    const judged = records.filter((r) => r.record.verdicts.some((v) => v.host === host));
+    const atCell = records.filter((r) => {
+      const held = new Set(recordCells(r.record).map(cellKey));
+      return cells.every((c) => held.has(cellKey(c)));
+    });
+    if (atCell.length === 0) {
+      const measuredAt = [...new Set(records.flatMap((r) => recordCells(r.record).map(cellKey)))];
+      say(`distributed: ${distributedUri(item, records[0]!)}: set ${set} measured at ${measuredAt.length === 0 ? "no cell" : measuredAt.join(", ")}`);
+      continue;
+    }
+    const judged = atCell.filter((r) => r.record.verdicts.some((v) => v.host === host));
     if (judged.length === 0) {
       say(`distributed: ${distributedUri(item, records[0]!)}: no verdict for ${host} in ${set}`);
       continue;
@@ -205,7 +242,7 @@ export function matchDistributed(
       say(`distributed: ${distributedUri(item, unmeasured)}: unmeasured in ${set}, measured here`);
       continue;
     }
-    return { status: "applies", set, records, files: [...new Set(records.flatMap((r) => r.record.binary.files.map((f) => f.path)))] };
+    return { status: "applies", set, records: atCell, files: [...new Set(atCell.flatMap((r) => r.record.binary.files.map((f) => f.path)))], lines };
   }
   return { status: "ignored", lines };
 }

package/src/index.ts

@@ -24,6 +24,8 @@ export * from "./cost-fields.js";
 export * from "./probe-output.js";
 export * from "./probe-judge.js";
 export * from "./qualification-record.js";
+export * from "./judgement-line.js";
+export * from "./judged-layer.js";
 export * from "./probe-runner.js";
 export * from "./measurement-grid.js";
 export * from "./memory-bound.js";

package/src/judged-layer.ts

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The judged layer of a plugin-db entry, from a qualification record: plugin-qualify is that layer's one writer
+ * (plugin-db's records design note, FreeMixer/plugin-db#10). The reader never parses a record; it reads the layer this writes, so every field
+ * the state function reads is set here, from the record and from what plugin-qualify declares once:
+ *
+ * - the latency line (`LATENCY_LINE_MS`), written beside each cell's figure (`latencyMs`), so a surface shows the
+ *   figure within or over the line and keeps no tier word (openmixer plugin-system design 7.15);
+ * - the rules the record was judged by (`judgementRules`), the minor of the plugin-qualify that judged it: a rule
+ *   changes only in a minor, so a patch release leaves every record current;
+ * - the hosting epoch of the host the verdict is for (`HOSTING_EPOCH`).
+ *
+ * One layer is one verdict under one host: the host plugin-hostd runs a plugin with. Its verdict is the one the pins
+ * file gives the same bytes (`pinVerdictOf` of the isolated tier's host, omx-clap-host, which is plugin-hostd's
+ * worker). A record whose verdict for that host was not measured has no judged layer: the reader then answers
+ * unqualified, with its reason.
+ */
+import { judgementRules, latencyMsOf, LATENCY_LINE_MS } from "./judgement-line.js";
+import { pinVerdictOf, type PinVerdict } from "./pins-file.js";
+import { QUALIFICATION_RECORD_SCHEMA, ISOLATED_TIER_HOST, type QualificationRecord } from "./qualification-record.js";
+import type { SuitabilityRating } from "./rating.js";
+
+/** The host a judged layer is written for: the one that runs plugins, in workers of its own (PLUGIN_DB_ISOLATION_HOSTS). */
+export const JUDGED_HOST = "plugin-hostd";
+
+/**
+ * The hosting epoch of each host a layer is written for. The epoch is the host owner's to move, when a release of it
+ * changes how it hosts; plugin-hostd has declared no hosting change since records were written, so its epoch is 0.
+ */
+export const HOSTING_EPOCH = { [JUDGED_HOST]: 0 } as const satisfies Readonly<Record<string, number>>;
+
+/** The plugin-db envelope version this writes (plugin-db data/store.schema.json). */
+export const PLUGIN_DB_ENVELOPE = 1;
+
+/** The pin a layer is written for, as plugin-db's pinned layer holds it. */
+export interface LayerPin {
+  /** The `omx-files/1` SHA-256 of the plugin's files. */
+  readonly files: string;
+  /** `<scheme>:<sha256>` of the parameter layout, or null when the pin holds none. */
+  readonly layout: string | null;
+}
+
+export interface JudgedCell {
+  readonly rate: number;
+  readonly quantum: number;
+  readonly latencyMs?: number;
+}
+
+export interface JudgedBody {
+  readonly verdict: PinVerdict;
+  readonly machineClass: string;
+  readonly host: { readonly name: string; readonly version: string; readonly hostingEpoch: number };
+  readonly rules: string;
+  readonly recordSchema: string;
+  readonly cells: readonly JudgedCell[];
+  readonly conditions: Readonly<Record<string, string>>;
+  readonly latencyLineMs: number;
+}
+
+export interface JudgedLayer {
+  readonly envelope: typeof PLUGIN_DB_ENVELOPE;
+  readonly layer: "judged";
+  readonly address: string;
+  readonly pin: LayerPin;
+  readonly writer: "plugin-qualify";
+  readonly body: JudgedBody;
+}
+
+/** What the converter is given beside the record: the class word, the pin, and the rules when the record states none. */
+export interface JudgedLayerInput {
+  /** The machine class word the record was measured on (`rpi5`, `x86-64`): the set's host class. */
+  readonly machineClass: string;
+  readonly pin: LayerPin;
+  /** plugin-db's address; by default `<format>:<id>`. */
+  readonly address?: string;
+  /** The rules of a record that states none: the plugin-qualify version that judged its set (the set's provenance). */
+  readonly judgedBy?: string;
+}
+
+/** Why a record has no judged layer, when it has none. */
+export type NoLayer = { readonly layer: null; readonly reason: string };
+
+/** The version of a tool named `<name> <version>` in the record's `tool`. */
+function versionOf(record: QualificationRecord, name: string): string | undefined {
+  for (const v of Object.values(record.tool)) {
+    const m = new RegExp(`^${name.replace(/[-.]/g, "\\$&")} (\\S+)$`).exec(v);
+    if (m) return m[1];
+  }
+  return undefined;
+}
+
+/** The cells of the record: each measured rate and quantum, with its latency in milliseconds when one was measured. */
+export function judgedCells(record: QualificationRecord): JudgedCell[] {
+  return record.measurements.grid
+    .filter((p) => p.outcome === "probe.ok")
+    .map((p) => {
+      const frames = (p.latency as { measuredFrames?: number }).measuredFrames;
+      return { rate: p.rate, quantum: p.quantum, ...(frames === undefined ? {} : { latencyMs: latencyMsOf(frames, p.rate) }) };
+    });
+}
+
+/**
+ * The judged layer of a record, or why there is none. The verdict is the isolated tier host's, as the pins file gives
+ * it; the host is plugin-hostd at the probe runner's version, which is plugin-hostd's.
+ */
+export function judgedLayerOf(record: QualificationRecord, input: JudgedLayerInput): JudgedLayer | NoLayer {
+  if (record.schema !== QUALIFICATION_RECORD_SCHEMA) return { layer: null, reason: `record schema ${JSON.stringify(record.schema)} is not ${QUALIFICATION_RECORD_SCHEMA}` };
+  const tierHost = ISOLATED_TIER_HOST[record.plugin.format];
+  const v = record.verdicts.find((r) => r.host === tierHost);
+  if (v === undefined) return { layer: null, reason: `no verdict under ${tierHost ?? `a host for ${record.plugin.format}`}` };
+  const verdict = v.measured ? pinVerdictOf(v.rating as SuitabilityRating) : undefined;
+  if (verdict === undefined) return { layer: null, reason: `${tierHost}: not measured (${v.deciding ?? v.rating})` };
+  const hostVersion = versionOf(record, "plugin-hostd-probe");
+  if (hostVersion === undefined) return { layer: null, reason: "the record names no plugin-hostd-probe version" };
+  const rules = record.rules ?? (input.judgedBy === undefined ? undefined : judgementRules(input.judgedBy));
+  if (rules === undefined) return { layer: null, reason: "the record states no rules, and no judgedBy was given" };
+  return {
+    envelope: PLUGIN_DB_ENVELOPE,
+    layer: "judged",
+    address: input.address ?? `${record.plugin.format}:${record.plugin.id}`,
+    pin: input.pin,
+    writer: "plugin-qualify",
+    body: {
+      verdict,
+      machineClass: input.machineClass,
+      host: { name: JUDGED_HOST, version: hostVersion, hostingEpoch: HOSTING_EPOCH[JUDGED_HOST] },
+      rules,
+      recordSchema: record.schema,
+      cells: judgedCells(record),
+      conditions: {},
+      latencyLineMs: record.latencyLineMs ?? LATENCY_LINE_MS,
+    },
+  };
+}
+
+export interface JudgedLayerArgs {
+  readonly record: string;
+  readonly machineClass: string;
+  readonly files: string;
+  readonly layout: string | null;
+  readonly judgedBy?: string;
+  readonly address?: string;
+  /** Print the body only, as `plugin-db put <address> judged --writer plugin-qualify` reads it from stdin. */
+  readonly body: boolean;
+}
+
+export function judgedLayerHelpText(): string {
+  return [
+    "usage: plugin-qualify judged-layer <record.qualification.json> --machine-class <word> --files <sha256>",
+    "                                   [--layout <scheme>:<sha256>] [--judged-by <version>] [--address <address>] [--body]",
+    "",
+    "Print the plugin-db judged layer of a qualification record, for the pin plugin-db holds (its files digest and",
+    "layout). --judged-by names the plugin-qualify that judged a record stating no rules (the set's provenance). --body",
+    "prints the body only, for `plugin-db put <address> judged --writer plugin-qualify`. A record whose verdict under",
+    "plugin-hostd's worker was not measured has no layer: the reason is printed and the exit status is 1.",
+    "",
+  ].join("\n");
+}
+
+export type ParsedJudgedLayerArgs = { ok: true; args: JudgedLayerArgs } | { ok: true; help: true } | { ok: false; error: string };
+
+export function parseJudgedLayerArgs(argv: readonly string[]): ParsedJudgedLayerArgs {
+  const opts: Record<string, string> = {};
+  const files: string[] = [];
+  let body = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--help" || a === "-h") return { ok: true, help: true };
+    if (a === "--body") body = true;
+    else if (["--machine-class", "--files", "--layout", "--judged-by", "--address"].includes(a)) {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith("--")) return { ok: false, error: `${a} needs a value` };
+      opts[a] = v;
+    } else if (a.startsWith("--")) return { ok: false, error: `unknown option ${a}` };
+    else files.push(a);
+  }
+  if (files.length !== 1) return { ok: false, error: "name one record" };
+  const machineClass = opts["--machine-class"];
+  const pinFiles = opts["--files"];
+  if (machineClass === undefined) return { ok: false, error: "--machine-class is required" };
+  if (pinFiles === undefined || !/^[0-9a-f]{64}$/.test(pinFiles)) return { ok: false, error: "--files must be the 64 hex digits of the files pin" };
+  const layout = opts["--layout"] ?? null;
+  if (layout !== null && !/^[^:]+:[0-9a-f]{64}$/.test(layout)) return { ok: false, error: "--layout must be <scheme>:<sha256>" };
+  return {
+    ok: true,
+    args: {
+      record: files[0]!,
+      machineClass,
+      files: pinFiles,
+      layout,
+      body,
+      ...(opts["--judged-by"] === undefined ? {} : { judgedBy: opts["--judged-by"] }),
+      ...(opts["--address"] === undefined ? {} : { address: opts["--address"] }),
+    },
+  };
+}

package/src/judgement-line.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * What plugin-qualify's judgement declares once and writes into every record (and so into every judged layer): the
+ * latency line and the rules a record was judged by (openmixer plugin-system design 7.15, plugin-db records.md).
+ */
+import { readFileSync } from "node:fs";
+
+/** The latency line, in milliseconds: declared once, here, and written into every record and judged layer. */
+export const LATENCY_LINE_MS = 5;
+
+/** A measured latency in milliseconds at its rate, rounded to the microsecond. */
+export const latencyMsOf = (frames: number, rate: number): number => Math.round((frames * 1e9) / rate) / 1e6;
+
+const VERSION: string = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/** The rules a plugin-qualify of this version judges by: `plugin-qualify-rules/<major>.<minor>`. */
+export function judgementRules(version: string = VERSION): string {
+  const m = /^(\d+)\.(\d+)\.\d+/.exec(version);
+  if (m === null) throw new Error(`judgementRules: ${JSON.stringify(version)} is no version`);
+  return `plugin-qualify-rules/${m[1]}.${m[2]}`;
+}

package/src/measurement/cli.ts

@@ -35,7 +35,7 @@
 import { join } from "node:path";
 
 import type { MeasurementDocument, MeasurementRun, MeasuredPlugin } from "./format.js";
-import { buildMeasurementDocument } from "./format.js";
+import { buildMeasurementDocument, readIntegrity } from "./format.js";
 import { measuredPluginsFromProbeOutput } from "./probe-json.js";
 import { buildRun, costMethodFromProbeProvenance, hostFromProbeProvenance } from "./provenance.js";
 import type { MeasurementHost, LatencyMethod } from "./format.js";
@@ -237,10 +237,17 @@ export function buildPipeline(options: MeasureOptions, native?: HostingTools): P
     });
   }
 
+  // a run of the prober's dimensions alone takes the pin too: a plugin measured with no integrity block cannot be pinned
+  // from its figures (plugin-qualify#316), and the measurer names the files without instantiating anything
+  const pinned = !hosting && probed && native !== undefined && (options.plugins !== undefined || current !== undefined);
+  if (pinned && native !== undefined) {
+    steps.push({ id: "pin", command: native.tool, args: ["--pin"], perPlugin: true, produces: join(options.workDir, "pins.jsonl") });
+  }
+
   return {
     steps,
     ...(probed && current !== undefined ? { finalCatalog: current } : {}),
-    ...(hosting && options.plugins === undefined && current !== undefined ? { hostingScan: current } : {}),
+    ...((hosting || pinned) && options.plugins === undefined && current !== undefined ? { hostingScan: current } : {}),
     ...(costProvenance === undefined ? {} : { costProvenance }),
   };
 }
@@ -599,6 +606,8 @@ export interface AssemblyInput {
   readonly catalog?: unknown;
   /** The hosting pass's lines ({@link hostingLine}), one per plugin. Absent when it did not run. */
   readonly hosting?: readonly unknown[];
+  /** The measurer's `--pin` lines ({@link hostingLine}), one per plugin, for a run with no hosting pass. Absent when the pin step did not run. */
+  readonly pins?: readonly unknown[];
   /** The cost pass's provenance JSON, already parsed. Absent on a latency-only run. */
   readonly costProvenance?: unknown;
   /** Host facts, for a run whose provenance the cost pass did not write. */
@@ -636,6 +645,7 @@ export function assembleDocument(input: AssemblyInput): MeasurementDocument {
   const plugins: MeasuredPlugin[] =
     probed.length > 0 && input.catalog !== undefined ? measuredPluginsFromProbeOutput(input.catalog, probed) : [];
   if (input.hosting !== undefined) mergeHosting(plugins, measuredPluginsFromSweep({ measurements: input.hosting }), input.options.dimensions);
+  if (input.pins !== undefined) mergePins(plugins, input.pins);
   const costMethod = costMethodFromProbeProvenance(input.costProvenance);
   const host = hostFromProbeProvenance(input.costProvenance) ?? input.host;
   const run: MeasurementRun = buildRun({
@@ -655,6 +665,20 @@ export function assembleDocument(input: AssemblyInput): MeasurementDocument {
   return buildMeasurementDocument(run, plugins);
 }
 
+/** The pin lines folded into the prober's plugins, by URI: a plugin without one keeps none, and a line for a plugin not measured adds none. */
+function mergePins(plugins: MeasuredPlugin[], rows: readonly unknown[]): void {
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null) continue;
+    const r = row as Record<string, unknown>;
+    const integrity = readIntegrity(r["integrity"]);
+    const at = plugins.findIndex((p) => p.uri === r["uri"]);
+    if (integrity === undefined || at < 0) continue;
+    const p = plugins[at]!;
+    const version = typeof r["version"] === "string" && r["version"] !== "" ? r["version"] : undefined;
+    plugins[at] = { ...p, ...(p.integrity === undefined ? { integrity } : {}), ...(p.version === undefined && version !== undefined ? { version } : {}) };
+  }
+}
+
 /**
  * The hosting pass's plugins folded into the prober's, by URI: each keeps the hosting dimensions the
  * run asked for and the pin, and a plugin only the hosting pass measured joins with its own topology.

package/src/measurement/format.ts

@@ -303,6 +303,8 @@ export interface MemoryFootprint {
   /** Activated, after processing: what a long-running host carries. */
   readonly atRestKb?: number;
   readonly notesHeldKb?: number;
+  /** The notes held (voices sounding) when `notesHeldKb` was read, the count `basis` says where it came from. */
+  readonly notesHeld?: number;
   readonly secondInstanceKb?: number;
   readonly basis?: VoiceBasis;
   readonly unmeasuredReason?: string;
@@ -950,6 +952,11 @@ function readLatency(value: unknown): LatencyMeasurement | undefined {
 }
 
 /** A KB figure: finite and never negative. */
+function notesCount(value: unknown): number | undefined {
+  const n = positiveNumber(value);
+  return n !== undefined && Number.isInteger(n) ? n : undefined;
+}
+
 function kilobytes(value: unknown): number | undefined {
   const n = finiteNumber(value);
   return n !== undefined && n >= 0 ? n : undefined;
@@ -963,6 +970,7 @@ export function readMemoryFootprint(value: unknown): MemoryFootprint | undefined
     ...optional("afterActivateKb", kilobytes(value.afterActivateKb)),
     ...optional("atRestKb", kilobytes(value.atRestKb)),
     ...optional("notesHeldKb", kilobytes(value.notesHeldKb)),
+    ...optional("notesHeld", notesCount(value.notesHeld)),
     ...optional("secondInstanceKb", kilobytes(value.secondInstanceKb)),
     ...optional("basis", isVoiceBasis(value.basis) ? value.basis : undefined),
     ...reasonOf(value),

package/src/probe-merge.ts

@@ -83,6 +83,10 @@ export function mergeProbeRuns(parts: readonly ProbeRunPart[], bound: MemoryBoun
   };
   merged["steps"] = steps;
   merged["grid"] = grid;
+  // every run's stderr is cited, not only the first's: the cell that crashed is as often a later one
+  const logs = docs.flatMap((d) => (Array.isArray(d["logs"]) ? (d["logs"] as Json[]) : []));
+  if (logs.length > 0) merged["logs"] = logs;
+  else delete merged["logs"];
   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}`);

package/src/probe-runner.ts

@@ -165,6 +165,9 @@ export interface ProbeLoad {
 export interface ProbedTarget {
   readonly bytes: Buffer;
   readonly output: ProbeOutput;
+  /** What each run's child printed on stderr (the file the document's `logs` cites, read before the run's directory goes),
+   * one entry a run that printed anything: a crash's own words are kept with the record (#samplv1, 459 bytes lost on the Pi). */
+  readonly stderr: readonly Buffer[];
   /** The most loaded the machine was when any of the target's runs started. */
   readonly load?: ProbeLoad;
 }
@@ -226,7 +229,14 @@ function runOne(target: PluginTarget, options: ProbeTargetOptions, invocation: R
     if (read.output.plugin.id !== expectedId) {
       throw new ProbeRunnerError(`${tool} measured ${read.output.plugin.id} when asked for ${expectedId}: not judged as the plugin asked for`);
     }
-    return { bytes, output: read.output, load };
+    let stderr: Buffer[] = [];
+    try {
+      const said = readFileSync(log);
+      if (said.length > 0) stderr = [said];
+    } catch {
+      // the runner wrote no log: the document cites none
+    }
+    return { bytes, output: read.output, load, stderr };
   } finally {
     rmSync(work, { recursive: true, force: true });
   }
@@ -246,7 +256,7 @@ export function probeTarget(target: PluginTarget, options: ProbeTargetOptions):
   const loads = parts.flatMap((p) => (p.load === undefined ? [] : [p.load]));
   const load = loads.length === 0 ? undefined : loads.reduce((a, b) => (b.loadavg1 > a.loadavg1 ? b : a));
   try {
-    return { ...mergeProbeRuns(parts, options.memory), ...(load === undefined ? {} : { load }) };
+    return { ...mergeProbeRuns(parts, options.memory), stderr: parts.flatMap((p) => p.stderr), ...(load === undefined ? {} : { load }) };
   } catch (e) {
     if (e instanceof ProbeMergeError) throw new ProbeRunnerError(e.message);
     throw e;
@@ -256,7 +266,7 @@ export function probeTarget(target: PluginTarget, options: ProbeTargetOptions):
 /** What the pass over a run's targets produced. */
 export interface ProbePass {
   /** Every probe output that was judged, with its bytes, for the qualification directory. */
-  readonly runs: readonly { readonly bytes: Buffer; readonly judgment: Judgment }[];
+  readonly runs: readonly { readonly bytes: Buffer; readonly judgment: Judgment; readonly stderr: readonly Buffer[] }[];
   readonly verdicts: readonly QualifyVerdict[];
   /** The CLAP documents of today's judge, which the pins file is taken from. */
   readonly documents: readonly RtSafetyDocument[];
@@ -292,7 +302,7 @@ export function qualifyTargets(
   const admissionRuns = options.admissions ?? SPAWNED_ADMISSIONS;
   const runEnvironment = options.env ?? process.env;
   const admissionEnv = options.admissionLv2Path === undefined ? runEnvironment : { ...runEnvironment, LV2_PATH: options.admissionLv2Path.join(":") };
-  const runs: { bytes: Buffer; judgment: Judgment }[] = [];
+  const runs: { bytes: Buffer; judgment: Judgment; stderr: readonly Buffer[] }[] = [];
   const verdicts: QualifyVerdict[] = [];
   const documents: RtSafetyDocument[] = [];
   const failures: { uri: string; problem: string }[] = [];
@@ -330,13 +340,13 @@ export function qualifyTargets(
     const judged = new Map<string, QualifyVerdict>();
     // a target's runs and documents count only when every one of its runs gave a probe output: one that
     // failed leaves the target not measured, and then nothing of it is recorded or pinned
-    const targetRuns: { bytes: Buffer; judgment: Judgment }[] = [];
+    const targetRuns: { bytes: Buffer; judgment: Judgment; stderr: readonly Buffer[] }[] = [];
     try {
       for (const { offer, profiles: forOffer } of byOffer.values()) {
         const probed = probeTarget(target, { ...options, ...measured, offer });
         const plain = judgeProbeOutput(probed.output, forOffer, { admissions });
         const judgment = { ...plain, ...(adapter === undefined ? {} : { adapter }), ...(probed.load === undefined ? {} : { load: probed.load }) };
-        targetRuns.push({ bytes: probed.bytes, judgment });
+        targetRuns.push({ bytes: probed.bytes, judgment, stderr: probed.stderr });
         for (const v of judgmentVerdicts(judgment)) judged.set(v.host, v);
       }
     } catch (e) {

package/src/qualification-record.ts

@@ -20,11 +20,12 @@ import { join } from "node:path";
 
 import type { Adjustment } from "./history-adjust.js";
 import type { Judgment, RecordReason } from "./probe-judge.js";
-import { sha256Hex, PROBE_OK, type ProbeGridPoint, type ProbeOutput } from "./probe-output.js";
+import { sha256Hex, PROBE_NOT_ATTEMPTED, 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";
+import { judgementRules, latencyMsOf, LATENCY_LINE_MS } from "./judgement-line.js";
 
 export const QUALIFICATION_RECORD_SCHEMA = "plugin-qualify.qualification-record/1";
 
@@ -201,6 +202,8 @@ 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;
+  /** The measured latency in milliseconds at the cell's rate, beside the record's `latencyLineMs`; absent when none was measured. */
+  readonly latencyMs?: number;
 };
 
 const UNMEASURED_WORDS: ReadonlySet<string> = new Set(Object.values(MEASUREMENT_UNMEASURED_REASONS).map((r) => r.word));
@@ -220,12 +223,20 @@ export function memoryOfCell(p: ProbeGridPoint): Pick<RecordGridPoint, "memory">
   return { memory: { ...p.memory, ...(first === undefined ? {} : { firstInstanceKb: first }), ...(per === undefined ? {} : { perInstanceKb: per }) } };
 }
 
+/** A grid point as the record writes it: its footprint, its latency or why there is none, and the latency in milliseconds. */
+export function gridPointOf(output: ProbeOutput, p: ProbeGridPoint): RecordGridPoint {
+  const latency = latencyOfCell(output, p);
+  const frames = (latency as { measuredFrames?: number }).measuredFrames;
+  return { ...p, ...memoryOfCell(p), latency, ...(frames === undefined ? {} : { latencyMs: latencyMsOf(frames, p.rate) }) };
+}
+
 /** 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"),
+  [PROBE_NOT_ATTEMPTED]: word("notAttempted"),
 };
 
 /**
@@ -361,6 +372,10 @@ export interface QualificationRecord {
   /** Who measured and when. */
   readonly tool: Readonly<Record<string, string>>;
   readonly measuredAt: string;
+  /** The latency line the cells' `latencyMs` stand against (`LATENCY_LINE_MS`); absent on a record written before it was declared. */
+  readonly latencyLineMs?: number;
+  /** The rules the verdicts were judged by (`judgementRules`); absent on a record written before they were stated. */
+  readonly rules?: 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. */
@@ -428,6 +443,8 @@ export function qualificationBaseName(output: ProbeOutput): string {
 
 export const recordFileName = (output: ProbeOutput): string => `${qualificationBaseName(output)}.qualification.json`;
 export const probeCopyFileName = (output: ProbeOutput): string => `${qualificationBaseName(output)}.probe.json`;
+/** A child's stderr beside the record, named by the first 12 of the SHA-256 the probe copy's `logs` cites it by. */
+export const stderrCopyFileName = (output: ProbeOutput, sha256: string): string => `${qualificationBaseName(output)}.stderr.${sha256.slice(0, 12)}.log`;
 
 function tierOf(judgment: Judgment, host: string | undefined): TierVerdict | undefined {
   const v = judgment.hosts.find((h) => h.verdict.host === host)?.verdict;
@@ -481,13 +498,15 @@ export function buildQualificationRecord(
     tiers: tiersOf(judgment),
     cost: judgment.hosts.map((h) => ({ host: h.verdict.host, ...h.cost })),
     measurements: {
-      grid: o.grid.map((p) => ({ ...p, ...memoryOfCell(p), latency: latencyOfCell(o, p) })),
+      grid: o.grid.map((p) => gridPointOf(o, p)),
       ...(o.behaviour === undefined ? {} : { behaviour: o.behaviour }),
       ...(unmeasuredFigures(o).length === 0 ? {} : { unmeasured: unmeasuredFigures(o) }),
     },
     ...(notMeasured.length === 0 ? {} : { notMeasured }),
     tool: o.run.tools,
     measuredAt: o.run.startedAt,
+    latencyLineMs: LATENCY_LINE_MS,
+    rules: judgementRules(),
     probe: {
       file: copy.file,
       sha256: copy.sha256,
@@ -518,6 +537,8 @@ export interface WrittenQualification {
   readonly recordPath: string;
   readonly probePath: string;
   readonly record: QualificationRecord;
+  /** The children's stderr written beside the record, one file each run that printed anything. */
+  readonly stderrPaths: readonly string[];
 }
 
 /**
@@ -530,33 +551,46 @@ export function writeQualification(
   probeBytes: Uint8Array,
   judgment: Judgment,
   notMeasured: readonly NotMeasured[] = [],
+  stderr: readonly Uint8Array[] = [],
 ): WrittenQualification {
   mkdirSync(dir, { recursive: true });
+  // the children's own words first, as the probe copy cites them: a crash's reason is kept, not only its size
+  const stderrPaths = stderr
+    .filter((s) => s.length > 0)
+    .map((s) => {
+      const path = join(dir, stderrCopyFileName(judgment.output, sha256Hex(s)));
+      writeFileWhole(path, s);
+      return path;
+    });
   const probePath = join(dir, probeCopyFileName(judgment.output));
   writeFileWhole(probePath, probeBytes);
   const copy = readFileSync(probePath);
   const record = buildQualificationRecord(judgment, { file: probeCopyFileName(judgment.output), sha256: sha256Hex(copy), bytes: copy.length }, notMeasured);
   const recordPath = join(dir, recordFileName(judgment.output));
   writeFileWhole(recordPath, `${JSON.stringify(record, null, 2)}\n`);
-  return { recordPath, probePath, record };
+  return { recordPath, probePath, record, stderrPaths };
 }
 
 /**
  * Runs that name the same binary and offer share one record file (a CLAP judged with and without the extra extensions
  * offered): their verdicts become one record over the first run's probe output, so the second is never written over the first.
  */
-export function mergeRunsByRecord<T extends { readonly bytes: Uint8Array; readonly judgment: Judgment }>(runs: readonly T[]): { bytes: Uint8Array; judgment: Judgment }[] {
-  const byName = new Map<string, { bytes: Uint8Array; judgment: Judgment }>();
+export function mergeRunsByRecord<T extends { readonly bytes: Uint8Array; readonly judgment: Judgment; readonly stderr?: readonly Uint8Array[] }>(
+  runs: readonly T[],
+): { bytes: Uint8Array; judgment: Judgment; stderr: readonly Uint8Array[] }[] {
+  // the stderr kept is the first run's, as its probe output is the copy that cites it
+  const byName = new Map<string, { bytes: Uint8Array; judgment: Judgment; stderr: readonly Uint8Array[] }>();
   for (const r of runs) {
     const name = qualificationBaseName(r.judgment.output);
     const first = byName.get(name);
     byName.set(
       name,
       first === undefined
-        ? r
+        ? { bytes: r.bytes, judgment: r.judgment, stderr: r.stderr ?? [] }
         : {
             bytes: first.bytes,
             judgment: { ...first.judgment, hosts: [...first.judgment.hosts, ...r.judgment.hosts], documents: [...first.judgment.documents, ...r.judgment.documents] },
+            stderr: first.stderr,
           },
     );
   }