@openmixer/plugin-qualify 0.11.0 → 0.13.0

package/src/measurement/vocabulary.ts

@@ -10,13 +10,41 @@
  * whether the plugin has nothing to measure or whether OUR PROBE failed — and each with
  * a plain description a UI can render.
  *
- * Everything is a data table, not a switch. Adding a term is one row; a consumer that
- * meets a term it does not know must be able to fall back on the `kind`, which is why the
- * readers below return a term record rather than a bare string.
+ * Everything is a data table, not a switch. A consumer that meets a term it does not know
+ * must be able to fall back on the `kind`, which is why the readers below return a term record
+ * rather than a bare string.
+ *
+ * The WORDS are omx-contract's (`data/measurement.json` and `data/resource-profile.json`, rendered
+ * as `<ITEM>_WORDS`), in its order: a word is added there, once, and every consumer reads it. What
+ * stays here is the prose, keyed by the contract's word type, so a word the contract adds without
+ * a description here, or a description for a word it lacks, is a type error.
  */
 
+import {
+  MEASUREMENT_COST_METHODS_WORDS,
+  MEASUREMENT_DIMENSIONS_WORDS,
+  MEASUREMENT_LATENCY_EXCLUSIONS_WORDS,
+  MEASUREMENT_LATENCY_METHODS_WORDS,
+  MEASUREMENT_LATENCY_SCALING_NOTES_WORDS,
+  MEASUREMENT_LATENCY_SCALING_WORDS,
+  MEASUREMENT_UNMEASURED_KINDS_WORDS,
+  MEASUREMENT_UNMEASURED_REASONS,
+  MEASUREMENT_UNMEASURED_REASONS_WORDS,
+  MEASUREMENT_VERDICT_RATINGS_WORDS,
+  MEASUREMENT_VOICE_BASES_WORDS,
+  RESOURCE_HOST_ISOLATIONS_WORDS,
+  RESOURCE_HOST_LATENCY_HANDLING_WORDS,
+} from "@openmixer/omx-contract";
 import { nonEmptyString } from "./guards.js";
 
+/** Pairs each word, in the contract's order, with its description here. */
+function described<Code extends string>(
+  words: readonly Code[],
+  descriptions: Readonly<Record<Code, string>>,
+): readonly { readonly code: Code; readonly description: string }[] {
+  return words.map((code) => ({ code, description: descriptions[code] }));
+}
+
 // ---------------------------------------------------------------------------
 // Why a figure is absent
 // ---------------------------------------------------------------------------
@@ -35,105 +63,75 @@ import { nonEmptyString } from "./guards.js";
  *   a finding nor a failure; it is the shape a PARTIAL run has, and partial runs are
  *   first-class here.
  */
-export type UnmeasuredKind = "nothing-to-measure" | "probe-failed" | "not-attempted";
+export type UnmeasuredKind = (typeof MEASUREMENT_UNMEASURED_KINDS_WORDS)[number];
+
+/** One reason a figure may be absent: a word of the contract's MEASUREMENT_UNMEASURED_REASONS. */
+export type UnmeasuredCode = (typeof MEASUREMENT_UNMEASURED_REASONS_WORDS)[number];
 
 /** One term of the "why is there no figure" vocabulary. */
 export interface UnmeasuredTerm {
-  readonly code: string;
+  readonly code: UnmeasuredCode;
   readonly kind: UnmeasuredKind;
   /** Plain description, English. A UI localises from `code`; this is for logs and specs. */
   readonly description: string;
 }
 
 /**
- * Every reason a figure may be absent. These were derived from a sweep of 958 plugins — each
- * one is an outcome that sweep actually produced, not a hypothetical.
+ * Every reason a figure may be absent, in plain English. These were derived from a sweep of 958
+ * plugins — each one is an outcome that sweep actually produced, not a hypothetical. The words and
+ * their kinds are the contract's.
  */
-export const UNMEASURED_TERMS: readonly UnmeasuredTerm[] = [
-  {
-    code: "no-audio-in",
-    kind: "nothing-to-measure",
-    description: "No audio input port: an instrument, a generator or an analyser. Nothing to drive.",
-  },
-  {
-    code: "no-audio-out",
-    kind: "nothing-to-measure",
-    description: "No audio output port: a meter or a sink. Nothing to read.",
-  },
-  {
-    code: "silent-output",
-    kind: "nothing-to-measure",
-    description:
-      "Instantiated and driven, but emitted nothing under a stimulus that should have passed. " +
+const UNMEASURED_DESCRIPTIONS: Readonly<Record<UnmeasuredCode, string>> = {
+  "no-audio-in":
+    "No audio input port: an instrument, a generator or an analyser. Nothing to drive.",
+  "no-audio-out":
+    "No audio output port: a meter or a sink. Nothing to read.",
+  "silent-output":
+    "Instantiated and driven, but emitted nothing under a stimulus that should have passed. " +
       "A convolver with no impulse response, a vocoder with no carrier, a gate that never opened.",
-  },
-  {
-    code: "needs-carrier",
-    kind: "nothing-to-measure",
-    description: "Requires a second audio input (a carrier or side-chain) the prober did not supply.",
-  },
-  {
-    code: "needs-impulse-response",
-    kind: "nothing-to-measure",
-    description: "A convolver requiring an IR file the prober did not load.",
-  },
-  {
-    code: "unpinnable",
-    kind: "nothing-to-measure",
-    description:
-      "The files the host loads cannot be pinned (plugin-qualify spec §11.1): a path holding ',', '=' or " +
+  "needs-carrier":
+    "Requires a second audio input (a carrier or side-chain) the prober did not supply.",
+  "needs-impulse-response":
+    "A convolver requiring an IR file the prober did not load.",
+  "unpinnable":
+    "The files the host loads cannot be pinned (plugin-qualify spec §11.1): a path holding ',', '=' or " +
       "whitespace, a manifest using @base or a percent-encoded IRI, or a CLAP plugin with more parameters than the " +
       "host accepts. The plugin stays unpinned, never partly pinned.",
-  },
-  {
-    code: "refused-instantiation",
-    kind: "probe-failed",
-    description: "The plugin would not instantiate at this rate or block size.",
-  },
-  {
-    code: "probe-crashed",
-    kind: "probe-failed",
-    description: "The probe worker died (signal or abort) while hosting this plugin.",
-  },
-  {
-    code: "probe-timeout",
-    kind: "probe-failed",
-    description: "The probe exceeded its per-plugin time limit and was abandoned.",
-  },
-  {
-    code: "non-finite-output",
-    kind: "probe-failed",
-    description: "Output contained NaN or infinity, so no onset or block time could be trusted.",
-  },
-  {
-    code: "not-installed",
-    kind: "probe-failed",
-    description:
-      "The URI was not present in this machine's LV2 world. A fact about this installation, " +
+  "no-voices":
+    "An instrument whose voice-info declares a voice capacity of 0: there is no voice to hold down, so its " +
+      "cost with notes held cannot be taken.",
+  "notes-unplayable":
+    "An instrument whose note input reads no dialect the prober speaks (CLAP's or MIDI's): it cannot be played.",
+  "voices-unknown":
+    "An instrument that declares no voice capacity, measured by a run given no probe count (`--probe-notes`): " +
+      "the run did not know how many notes to hold, so it timed none.",
+  "refused-instantiation":
+    "The plugin would not instantiate at this rate or block size.",
+  "probe-crashed":
+    "The probe worker died (signal or abort) while hosting this plugin.",
+  "probe-timeout":
+    "The probe exceeded its per-plugin time limit and was abandoned.",
+  "non-finite-output":
+    "Output contained NaN or infinity, so no onset or block time could be trusted.",
+  "not-installed":
+    "The URI was not present in this machine's LV2 world. A fact about this installation, " +
       "not about the plugin — another host may well have it.",
-  },
-  {
-    code: "worker-nonconforming",
-    kind: "probe-failed",
-    description:
-      "The plugin's LV2_Worker_Interface leaves work or work_response NULL, which the LV2 worker " +
+  "worker-nonconforming":
+    "The plugin's LV2_Worker_Interface leaves work or work_response NULL, which the LV2 worker " +
       "specification does not allow: it was refused before any call, not measured.",
-  },
-  {
-    code: "probe-error",
-    kind: "probe-failed",
-    description:
-      "The probe reported a failure with no more specific term. Its own words are kept verbatim " +
+  "probe-error":
+    "The probe reported a failure with no more specific term. Its own words are kept verbatim " +
       "in the measurement's `unmeasuredDetail`, so a coarse code never destroys the detail.",
-  },
-  {
-    code: "not-attempted",
-    kind: "not-attempted",
-    description: "This run did not cover this plugin for this dimension. A partial run, not a finding.",
-  },
-];
+  "not-attempted":
+    "This run did not cover this plugin for this dimension. A partial run, not a finding.",
+};
+
+/** Every reason a figure may be absent, in the contract's order, of the contract's kind. */
+export const UNMEASURED_TERMS: readonly UnmeasuredTerm[] = Object.values(MEASUREMENT_UNMEASURED_REASONS).map(
+  (reason) => ({ code: reason.word, kind: reason.group, description: UNMEASURED_DESCRIPTIONS[reason.word] }),
+);
 
-const UNMEASURED_BY_CODE: ReadonlyMap<string, UnmeasuredTerm> = new Map(
+const UNMEASURED_BY_CODE: ReadonlyMap<string, UnmeasuredTerm> = new Map<string, UnmeasuredTerm>(
   UNMEASURED_TERMS.map((term) => [term.code, term]),
 );
 
@@ -173,25 +171,19 @@ export interface ScalingTerm {
   readonly description: string;
 }
 
-export const SCALING_TERMS: readonly ScalingTerm[] = [
-  {
-    code: "fixed-frame",
-    description: "Constant frame count at every rate — an FFT window. Milliseconds halve when the rate doubles.",
-  },
-  {
-    code: "fixed-time",
-    description: "Constant milliseconds at every rate — a look-ahead. Frames double when the rate doubles.",
-  },
-  { code: "zero", description: "No latency a mix can notice at any measured rate." },
-  {
-    code: "nonconforming",
-    description:
-      "Fits neither law at a magnitude that reaches a mix: the plugin changes what it does with " +
-      "the rate. Flagged rather than averaged; nothing may be projected from it.",
-  },
-  { code: "single-rate", description: "One usable reading, so no law can be fitted." },
-  { code: "unmeasured", description: "No rate produced a figure." },
-];
+/** A word of the contract's MEASUREMENT_LATENCY_SCALING. */
+export type ScalingCode = (typeof MEASUREMENT_LATENCY_SCALING_WORDS)[number];
+
+export const SCALING_TERMS: readonly ScalingTerm[] = described(MEASUREMENT_LATENCY_SCALING_WORDS, {
+  "fixed-frame": "Constant frame count at every rate — an FFT window. Milliseconds halve when the rate doubles.",
+  "fixed-time": "Constant milliseconds at every rate — a look-ahead. Frames double when the rate doubles.",
+  zero: "No latency a mix can notice at any measured rate.",
+  nonconforming:
+    "Fits neither law at a magnitude that reaches a mix: the plugin changes what it does with " +
+    "the rate. Flagged rather than averaged; nothing may be projected from it.",
+  "single-rate": "One usable reading, so no law can be fitted.",
+  unmeasured: "No rate produced a figure.",
+});
 
 const SCALING_CODES: ReadonlySet<string> = new Set(SCALING_TERMS.map((t) => t.code));
 
@@ -206,60 +198,55 @@ export function isKnownScalingCode(code: string): boolean {
  * detector's rather than the plugin's, and `informational-rate`, where only a reading below
  * the operational rates breaks the law (`lv2-measurement-interchange.md` §1a).
  */
-export const SCALING_NOTE_TERMS = [
-  {
-    code: "below-budget",
-    description:
-      "The readings fit no law, but every one of them is inside the per-channel latency budget, " +
-      "so the disagreement is measurement noise rather than plugin behaviour.",
-  },
-  {
-    code: "informational-rate",
-    description:
-      "The readings together fit no law, but those at the operational rates (48 kHz and up) do; " +
-      "the reading below them stays in perRate as information and does not flag the plugin.",
-  },
-] as const satisfies readonly ScalingTerm[];
+export const SCALING_NOTE_TERMS = described(MEASUREMENT_LATENCY_SCALING_NOTES_WORDS, {
+  "below-budget":
+    "The readings fit no law, but every one of them is inside the per-channel latency budget, " +
+    "so the disagreement is measurement noise rather than plugin behaviour.",
+  "informational-rate":
+    "The readings together fit no law, but those at the operational rates (48 kHz and up) do; " +
+    "the reading below them stays in perRate as information and does not flag the plugin.",
+});
 
 /** One of the {@link SCALING_NOTE_TERMS} codes — the words `latency.scalingNote` may carry. */
-export type ScalingNoteCode = (typeof SCALING_NOTE_TERMS)[number]["code"];
+export type ScalingNoteCode = (typeof MEASUREMENT_LATENCY_SCALING_NOTES_WORDS)[number];
 
 /**
  * Why one rate's reading was excluded from the fit and from every rate resolution. A
  * failed reading served as an exact answer is worse than no reading, because a zero reads
  * as confidence.
  */
-export const EXCLUSION_TERMS: readonly ScalingTerm[] = [
-  {
-    code: "impossible-zero",
-    description:
-      "Zero frames at this rate while another rate measured non-zero. Both scaling laws map zero " +
-      "to zero, so no single latency produces this; the onset detector was defeated.",
-  },
-];
+export const EXCLUSION_TERMS: readonly ScalingTerm[] = described(MEASUREMENT_LATENCY_EXCLUSIONS_WORDS, {
+  "impossible-zero":
+    "Zero frames at this rate while another rate measured non-zero. Both scaling laws map zero " +
+    "to zero, so no single latency produces this; the onset detector was defeated.",
+});
 
 // ---------------------------------------------------------------------------
 // How a figure was taken
 // ---------------------------------------------------------------------------
 
-/** The measurement methods the format has names for. */
+/** How a latency figure was taken: a word of the contract's MEASUREMENT_LATENCY_METHODS. */
+export type LatencyMethodCode = (typeof MEASUREMENT_LATENCY_METHODS_WORDS)[number];
+
+/** How a cost figure was taken: a word of the contract's MEASUREMENT_COST_METHODS. */
+export type CostMethodCode = (typeof MEASUREMENT_COST_METHODS_WORDS)[number];
+
+/** The measurement methods the format has names for: the latency methods, then the cost methods. */
 export const METHOD_TERMS: readonly ScalingTerm[] = [
-  {
-    code: "impulse-onset",
-    description:
+  ...described(MEASUREMENT_LATENCY_METHODS_WORDS, {
+    "impulse-onset":
       "Latency as the round-trip delay from a unit impulse to the first output sample above the " +
       "residual floor. Measures the plugin, not what it declares.",
-  },
-  {
-    code: "declared-port",
-    description: "Latency read from the plugin's own lv2:latency output port. What it CLAIMS.",
-  },
-  {
-    code: "block-time-percentile",
-    description:
+    "declared-port": "Latency read from the plugin's own lv2:latency output port. What it CLAIMS.",
+    "note-onset":
+      "An instrument's latency: the delay from a note on to the first output sample above the " +
+      "residual floor. Measures what the plugin does with a held note.",
+  }),
+  ...described(MEASUREMENT_COST_METHODS_WORDS, {
+    "block-time-percentile":
       "Cost as a percentile of per-block wall time under a sustained stimulus, warm-up blocks " +
       "discarded, normalised to nanoseconds per sample.",
-  },
+  }),
 ];
 
 const METHOD_CODES: ReadonlySet<string> = new Set(METHOD_TERMS.map((t) => t.code));
@@ -276,7 +263,7 @@ export function isKnownMethodCode(code: string): boolean {
  * hosting verdict — whether a plugin survives, whether its `run()` is RT-clean, what it
  * demands of a host — and merge under exactly the same per-plugin, per-DIMENSION precedence.
  */
-export const MEASUREMENT_DIMENSIONS = ["latency", "cost", "stability", "rtSafety", "features"] as const;
+export const MEASUREMENT_DIMENSIONS = MEASUREMENT_DIMENSIONS_WORDS;
 
 /**
  * The dimensions the standalone prober (`scan.py` + `benchmark.py`, driven by `lv2-measure.mjs`
@@ -302,18 +289,30 @@ export function readDimension(value: unknown): MeasurementDimension | undefined
 }
 
 /**
- * The four ratings a verdict speaks (`lv2-measurement-interchange.md` §3b) — the ONE list; the
- * rating vocabulary (`rating.ts`) derives its type from it, so the document and the classifier
- * can never disagree on a word.
+ * The four ratings a verdict speaks (`lv2-measurement-interchange.md` §3b): the contract's
+ * MEASUREMENT_VERDICT_RATINGS. The rating vocabulary (`rating.ts`) derives its type from it, so
+ * the document and the classifier can never disagree on a word.
  */
-export const VERDICT_RATINGS = ["suitable", "conditional", "unknown", "unsuitable"] as const;
+export const VERDICT_RATINGS = MEASUREMENT_VERDICT_RATINGS_WORDS;
 export type VerdictRating = (typeof VERDICT_RATINGS)[number];
 
-/** How a host runs its plugins. */
-export const HOST_ISOLATIONS = ["in-process", "per-process", "shared-process"] as const;
+/** How a host runs its plugins: the contract's RESOURCE_HOST_ISOLATIONS. */
+export const HOST_ISOLATIONS = RESOURCE_HOST_ISOLATIONS_WORDS;
 export type HostIsolation = (typeof HOST_ISOLATIONS)[number];
 
-/** Whether a host aligns on a plugin's reported latency (`compensated`) or only passes it on. */
-export const HOST_LATENCY_HANDLING = ["compensated", "uncompensated"] as const;
+/** Whether a host aligns on a plugin's reported latency (`compensated`) or only passes it on: the contract's RESOURCE_HOST_LATENCY_HANDLING. */
+export const HOST_LATENCY_HANDLING = RESOURCE_HOST_LATENCY_HANDLING_WORDS;
 export type HostLatencyHandling = (typeof HOST_LATENCY_HANDLING)[number];
 
+/**
+ * Where the number of notes an instrument's cost was measured with came from: `declared` is the voice
+ * capacity the plugin declares (CLAP's voice-info, read after activate at that rate); `probe` is a count
+ * the caller gave (`--probe-notes`, the console's `SYNTH_VOICE_PROBE_NOTES`), used when the plugin declares
+ * none or when the caller asked for that count whatever it declares.
+ */
+export const VOICE_BASES = MEASUREMENT_VOICE_BASES_WORDS;
+export type VoiceBasis = (typeof VOICE_BASES)[number];
+
+export function isVoiceBasis(value: unknown): value is VoiceBasis {
+  return VOICE_BASES.some((b) => b === value);
+}

package/src/probe-judge.ts

@@ -27,6 +27,7 @@ import {
 import { gridCostReadings } from "./cost-fields.js";
 import {
   hostingCostReasons,
+  noteSweepReasons,
   rtSafetyReasons,
   contributedHostingRating,
   type HostingReason,
@@ -35,7 +36,7 @@ import type { HostProfile } from "./host-profiles.js";
 import { PROBE_NOT_ATTEMPTED, PROBE_OK, type ProbeGridPoint, type ProbeOutput } from "./probe-output.js";
 import type { QualifyVerdict } from "./qualify-cli.js";
 import { RATING_SEVERITY, worstRating, type SuitabilityRating } from "./rating.js";
-import type { IntegrityMeasurement } from "./measurement/format.js";
+import type { IntegrityMeasurement, VoicesHeld } from "./measurement/format.js";
 
 /** Facts of the descriptor, which the probe output repeats none of. */
 export interface JudgeFacts {
@@ -168,8 +169,11 @@ export interface HostJudgment {
   /** In-process only for a suitable plugin on a host that runs its plugins in its own process, else isolated. */
   readonly hosting: "in-process" | "isolated";
   readonly reasons: readonly RecordReason[];
-  /** The cost reasons at this host's rate and quantum, kept beside the verdict, not folded into it. */
-  readonly cost: { readonly rate: number; readonly quantum: number; readonly reasons: readonly RecordReason[] };
+  /**
+   * The cost reasons at this host's rate and quantum, kept beside the verdict, not folded into it; for an instrument,
+   * the notes it held while that figure was timed.
+   */
+  readonly cost: { readonly rate: number; readonly quantum: number; readonly voices?: VoicesHeld; readonly reasons: readonly RecordReason[] };
 }
 
 export interface Judgment {
@@ -191,7 +195,8 @@ function costOf(output: ProbeOutput, profile: HostProfile): HostJudgment["cost"]
     { rate, quantum, profile },
     DEFAULT_HOSTING_POLICY,
   );
-  return { rate, quantum, reasons: reasons.map(asRecordReason) };
+  const voices = output.grid.find((p) => p.outcome === PROBE_OK && p.rate === rate && p.quantum === quantum)?.cost?.voices;
+  return { rate, quantum, ...(voices === undefined ? {} : { voices }), reasons: reasons.map(asRecordReason) };
 }
 
 /**
@@ -237,7 +242,10 @@ export function judgeProbeOutput(output: ProbeOutput, profiles: readonly HostPro
       documents.push(doc);
       reasons = doc.verdict.reasons.map(asRecordReason);
     } else {
-      reasons = rtSafetyReasons(rtSafetyOfProbeOutput(output)).map(asRecordReason);
+      // an LV2 plugin: the control sweep's counts, and the note sweep's when it was played through a MIDI input
+      const rt = rtSafetyOfProbeOutput(output);
+      const notes = noteSweepOfProbeOutput(output, rt);
+      reasons = [...rtSafetyReasons(rt), ...noteSweepReasons(notes, facts.noteInputs ?? (notes.applicable ? 1 : 0))].map(asRecordReason);
     }
     const rating = worstRating(reasons.map((r) => r.rating));
     const deciding = decidingOf(reasons, rating);

package/src/probe-output.ts

@@ -20,6 +20,7 @@
 import { createHash } from "node:crypto";
 
 import { finiteNumber, isRecord, nonEmptyString, optional } from "./measurement/guards.js";
+import { readVoicesHeld, type VoicesHeld } from "./measurement/format.js";
 
 export const PROBE_OUTPUT_FORMAT = "plugin-hostd.probe-output";
 /** The one major this reader knows. A minor of it only adds fields. */
@@ -60,6 +61,8 @@ export interface ProbeCost {
   readonly percentile: { readonly p: number; readonly value: number };
   readonly blocks: number;
   readonly warmupBlocks: number;
+  /** For an instrument: the notes it held while it was timed, how many and why that many. */
+  readonly voices?: VoicesHeld;
 }
 
 export interface ProbeRtSafety {
@@ -240,11 +243,14 @@ function readCost(v: unknown, where: string): ProbeCost {
   const median = num(o, "median", where);
   const value = num(pct, "value", `${where} percentile`);
   if (median < 0 || value < 0) invalid(`${where} holds a negative cost`);
+  const voices = o["voices"] === undefined ? undefined : readVoicesHeld(o["voices"]);
+  if (o["voices"] !== undefined && voices === undefined) invalid(`${where} voices is not a count of held notes with its basis`);
   return {
     median,
     percentile: { p, value },
     blocks: posInt(o, "blocks", where),
     warmupBlocks: count(o, "warmupBlocks", where),
+    ...(voices === undefined ? {} : { voices }),
   };
 }
 

package/src/qualification-record.ts

@@ -18,6 +18,7 @@ import { join } from "node:path";
 
 import type { Judgment, RecordReason } from "./probe-judge.js";
 import { sha256Hex, type ProbeGridPoint, type ProbeOutput } from "./probe-output.js";
+import type { VoicesHeld } from "./measurement/format.js";
 
 export const QUALIFICATION_RECORD_SCHEMA = "plugin-qualify.qualification-record/1";
 
@@ -41,8 +42,14 @@ export interface QualificationRecord {
   readonly testedVersion?: string;
   readonly binary: ProbeOutput["binary"];
   readonly verdicts: readonly RecordVerdict[];
-  /** The cost reasons at each host's rate and quantum, beside the verdicts. */
-  readonly cost: readonly { readonly host: string; readonly rate: number; readonly quantum: number; readonly reasons: readonly RecordReason[] }[];
+  /** The cost reasons at each host's rate and quantum, beside the verdicts; an instrument's with the notes it held. */
+  readonly cost: readonly {
+    readonly host: string;
+    readonly rate: number;
+    readonly quantum: number;
+    readonly voices?: VoicesHeld;
+    readonly reasons: readonly RecordReason[];
+  }[];
   /** The figures as measured, per rate and quantum. */
   readonly measurements: { readonly grid: readonly ProbeGridPoint[]; readonly behaviour?: Readonly<Record<string, unknown>> };
   /** Who measured and when. */