@openmixer/plugin-qualify 0.10.1 → 0.12.0

package/src/judge-cli.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `plugin-qualify judge <probe-output>...`: judge probe outputs already written (by
+ * `plugin-hostd-probe run`, by plugin-hostd's `judge_cmd`, or by hand) and write the qualification
+ * record beside a byte copy of each. `bin/plugin-qualify.mjs` only reads argv and prints.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { HostProfile } from "./host-profiles.js";
+import { judgeProbeOutput, judgmentVerdicts } from "./probe-judge.js";
+import { readProbeOutput } from "./probe-output.js";
+import { writeQualification } from "./qualification-record.js";
+import type { QualifyVerdict } from "./qualify-cli.js";
+import { EXIT_CODE, OUTPUT_FORMATS, type OutputFormat } from "./qualify-options.js";
+import { OPENMIXER_CONSOLE_PROFILE } from "./host-profiles.js";
+
+export interface JudgeArgs {
+  readonly files: readonly string[];
+  readonly hostProfiles: readonly string[];
+  readonly qualificationDir?: string;
+  readonly format: OutputFormat;
+  readonly help: boolean;
+}
+
+export type ParseJudgeResult = { ok: true; args: JudgeArgs } | { ok: false; error: string };
+
+const VALUE_FLAGS = ["--host-profile", "--qualification-dir", "--format"];
+
+export function parseJudgeArgs(argv: readonly string[]): ParseJudgeResult {
+  const files: string[] = [];
+  const specs: string[] = [];
+  let dir: string | undefined;
+  let format: string = "text";
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith("--")) {
+      files.push(a);
+      continue;
+    }
+    if (a === "--help") {
+      help = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.includes(a)) return { ok: false, error: `unknown option ${a}` };
+    const v = argv[++i];
+    if (v === undefined || v.startsWith("--")) return { ok: false, error: `${a} needs a value` };
+    if (a === "--host-profile") specs.push(...v.split(",").map((t) => t.trim()).filter((t) => t !== ""));
+    else if (a === "--qualification-dir") dir = v;
+    else format = v;
+  }
+  if (!(OUTPUT_FORMATS as readonly string[]).includes(format)) return { ok: false, error: `--format must be one of ${OUTPUT_FORMATS.join(", ")}` };
+  if (!help && files.length === 0) return { ok: false, error: "name at least one probe output" };
+  return {
+    ok: true,
+    args: {
+      files,
+      hostProfiles: [...new Set(specs.length > 0 ? specs : [OPENMIXER_CONSOLE_PROFILE.id])],
+      ...(dir === undefined ? {} : { qualificationDir: dir }),
+      format: format as OutputFormat,
+      help,
+    },
+  };
+}
+
+export function judgeHelpText(): string {
+  return [
+    "plugin-qualify judge — judge probe outputs and write the qualification records",
+    "",
+    "  plugin-qualify judge [options] <probe-output.json>...",
+    "",
+    "  --host-profile <file|id>      judge against this host; repeat or comma-separate for one verdict per profile",
+    `                                (default: ${OPENMIXER_CONSOLE_PROFILE.id})`,
+    "  --qualification-dir <dir>     where the records and the copies of the probe outputs go",
+    "                                (default: $XDG_STATE_HOME/omx/qualification, else ~/.local/state/omx/qualification)",
+    "  --format <json|text>          json = the records; text = plugin, verdict, deciding reason (default: text)",
+    "",
+    `exit ${EXIT_CODE.allQualified} all qualified / ${EXIT_CODE.someNotQualified} some not / ${EXIT_CODE.couldNotMeasure} something could not be read or judged`,
+    "",
+  ].join("\n");
+}
+
+/** The qualification directory when none is named: the state directory of owner spec section 6.9, per user. */
+export function defaultQualificationDir(env: Readonly<Record<string, string | undefined>>, home: string = homedir()): string {
+  const state = env["XDG_STATE_HOME"];
+  return join(state !== undefined && state !== "" ? state : join(home, ".local", "state"), "omx", "qualification");
+}
+
+export interface JudgeFilesResult {
+  readonly verdicts: readonly QualifyVerdict[];
+  readonly records: readonly { readonly recordPath: string; readonly probePath: string }[];
+  /** Each file that was refused or could not be read, with the code or the reason. */
+  readonly failures: readonly { readonly file: string; readonly problem: string }[];
+}
+
+/** Judge each file under every profile and write its record; a file that does not read is a failure, and the others go on. */
+export function judgeFiles(
+  files: readonly string[],
+  options: { profiles: readonly HostProfile[]; dir: string; read?: (path: string) => Buffer },
+): JudgeFilesResult {
+  const read = options.read ?? ((p: string) => readFileSync(p));
+  const verdicts: QualifyVerdict[] = [];
+  const records: { recordPath: string; probePath: string }[] = [];
+  const failures: { file: string; problem: string }[] = [];
+  for (const file of files) {
+    let bytes: Buffer;
+    try {
+      bytes = read(file);
+    } catch (e) {
+      failures.push({ file, problem: `cannot read: ${e instanceof Error ? e.message : String(e)}` });
+      continue;
+    }
+    const r = readProbeOutput(bytes.toString("utf8"));
+    if (!r.ok) {
+      failures.push({ file, problem: `${r.code}: ${r.problem}` });
+      continue;
+    }
+    const judgment = judgeProbeOutput(r.output, options.profiles);
+    const w = writeQualification(options.dir, bytes, judgment);
+    records.push({ recordPath: w.recordPath, probePath: w.probePath });
+    verdicts.push(...judgmentVerdicts(judgment));
+  }
+  return { verdicts, records, failures };
+}
+
+/** 2 when a file could not be judged or a plugin was not measured, else 0 when every verdict qualifies, else 1. */
+export function judgeExitCode(result: JudgeFilesResult): number {
+  if (result.failures.length > 0 || result.verdicts.length === 0 || result.verdicts.some((v) => !v.measured)) return EXIT_CODE.couldNotMeasure;
+  return result.verdicts.every((v) => v.qualified) ? EXIT_CODE.allQualified : EXIT_CODE.someNotQualified;
+}

package/src/measurement/cli.ts

@@ -54,6 +54,9 @@ export const TOOL_NAME = "lv2-measure";
  */
 export const TOOL_VERSION = "0.1.0";
 
+/** The most notes a cost run holds: one per MIDI key, as the probers cap it. */
+export const PROBE_NOTES_MAX = 128;
+
 /** A fully resolved invocation. */
 export interface MeasureOptions {
   /** Where the document goes. Absent = stdout. */
@@ -70,6 +73,11 @@ export interface MeasureOptions {
   readonly sweep: boolean;
   /** Core to pin the cost pass to. Absent = let the prober choose. */
   readonly costCpu?: number;
+  /**
+   * The notes the cost pass holds down while it times an instrument (`--probe-notes`, the console's
+   * `SYNTH_VOICE_PROBE_NOTES`), basis `probe`. Absent = an instrument is unmeasured `voices-unknown`.
+   */
+  readonly probeNotes?: number;
   readonly label?: string;
   /** Directory holding `scan.py` and `benchmark.py`. */
   readonly toolDir: string;
@@ -203,6 +211,7 @@ export function buildPipeline(options: MeasureOptions, native?: HostingTools): P
         "--cost-provenance",
         costProvenance,
         ...(options.costCpu === undefined ? [] : ["--cost-cpu", String(options.costCpu)]),
+        ...(options.probeNotes === undefined ? [] : ["--probe-notes", String(options.probeNotes)]),
       ],
       produces: cost,
       dimension: "cost",
@@ -356,6 +365,7 @@ export function parseMeasureArgs(
   let workDir = defaults.workDir;
   let sweep = false;
   let costCpu: number | undefined;
+  let probeNotes: number | undefined;
   let label: string | undefined;
   let toolDir = defaults.toolDir;
   let python = env.PYTHON ?? "python3";
@@ -430,6 +440,15 @@ export function parseMeasureArgs(
         costCpu = cpu;
         break;
       }
+      case "--probe-notes": {
+        const value = next();
+        const notes = value === undefined ? Number.NaN : Number(value);
+        if (!Number.isInteger(notes) || notes < 1 || notes > PROBE_NOTES_MAX) {
+          return { ok: false, error: `--probe-notes needs a count of notes, 1 to ${PROBE_NOTES_MAX}` };
+        }
+        probeNotes = notes;
+        break;
+      }
       case "--label": {
         const value = next();
         if (value === undefined) return { ok: false, error: "--label needs text" };
@@ -494,6 +513,7 @@ export function parseMeasureArgs(
       ...(scanPath === undefined ? {} : { scanPath }),
       ...(plugins === undefined ? {} : { plugins }),
       ...(costCpu === undefined ? {} : { costCpu }),
+      ...(probeNotes === undefined ? {} : { probeNotes }),
       ...(label === undefined ? {} : { label }),
       ...(featureFlags.length === 0 ? {} : { featureFlags }),
     },

package/src/measurement/format.ts

@@ -58,10 +58,12 @@ import {
   type HostLatencyHandling,
   type MeasurementDimension,
   type VerdictRating,
+  type VoiceBasis,
   HOST_ISOLATIONS,
   HOST_LATENCY_HANDLING,
   MEASUREMENT_DIMENSIONS,
   VERDICT_RATINGS,
+  isVoiceBasis,
   readDimension,
 } from "./vocabulary.js";
 
@@ -74,8 +76,10 @@ export const MEASUREMENT_FORMAT_MAJOR = 1;
 /** The minor this build writes. Additive-only within {@link MEASUREMENT_FORMAT_MAJOR}.
  *  `1.1` added the three hosting dimensions — {@link StabilityMeasurement},
  *  {@link RtSafetyMeasurement}, {@link FeaturesMeasurement} — which a 1.0 reader skips.
- *  `1.2` added the verdicts per host profile; `1.3` the {@link IntegrityMeasurement} block. */
-export const MEASUREMENT_FORMAT_MINOR = 3;
+ *  `1.2` added the verdicts per host profile; `1.3` the {@link IntegrityMeasurement} block; `1.4` the notes
+ *  an instrument's cost was measured with ({@link CostAtRate.voices}); `1.5` the note sweep an instrument's
+ *  `run()` was counted under ({@link RtSafetyMeasurement.noteSweep}). */
+export const MEASUREMENT_FORMAT_MINOR = 5;
 
 /** The version string this build writes, e.g. `"1.0"`. */
 export const MEASUREMENT_FORMAT_VERSION = `${MEASUREMENT_FORMAT_MAJOR}.${MEASUREMENT_FORMAT_MINOR}`;
@@ -270,6 +274,17 @@ export interface LatencyMeasurement {
   readonly unmeasuredDetail?: string;
 }
 
+/**
+ * The notes an instrument held down while its cost was timed (1.4): how many, where that count came
+ * from ({@link VoiceBasis}), and the voice capacity the plugin declared at that rate when it declares one.
+ * An instrument costs nothing until a voice plays, so its figure means nothing without this.
+ */
+export interface VoicesHeld {
+  readonly held: number;
+  readonly basis: VoiceBasis;
+  readonly capacity?: number;
+}
+
 /** One rate's cost reading. Per SAMPLE, so it is independent of the block size. */
 export interface CostAtRate {
   readonly nsPerSampleMedian: number;
@@ -286,6 +301,8 @@ export interface CostAtRate {
   /** Timed, but emitted silence under a stimulus that should have passed — the figure may
    *  describe a short-circuit path rather than the DSP. */
   readonly silentOutput?: boolean;
+  /** 1.4: for an instrument, the notes held while it was timed. Absent for an effect. */
+  readonly voices?: VoicesHeld;
 }
 
 /** Everything one run learned about one plugin's CPU cost. */
@@ -369,6 +386,27 @@ export interface StabilityMeasurement {
   readonly unmeasuredDetail?: string;
 }
 
+/**
+ * 1.5: an instrument played through its MIDI input while the interposer counted, apart from the control
+ * sweep — a chord, bend and a controller, pressure, the chord let go, a burst of note ons and their offs,
+ * all notes off. `applicable: false` is a plugin with no MIDI input; the counts are present only when
+ * the interposer was loaded.
+ */
+export interface NoteSweepMeasurement {
+  readonly applicable: boolean;
+  readonly dialect?: "clap" | "midi";
+  readonly blocks?: number;
+  readonly blockFrames?: number;
+  /** The note, expression and MIDI events the sweep sent. */
+  readonly noteEvents?: number;
+  readonly processErrors?: number;
+  readonly nonFinite?: boolean;
+  readonly interposer?: boolean;
+  readonly allocationsInRun?: number;
+  readonly locksInRun?: number;
+  readonly syscallsInRun?: number;
+}
+
 /**
  * What an interposer counted INSIDE `run()`. `rate` and `blockFrames` are the pair it ran at —
  * a count is a property of the code paths the run took there. Readable when all three counts
@@ -391,6 +429,8 @@ export interface RtSafetyMeasurement {
   readonly syscallsInRun?: number;
   /** Repeats disagreed. */
   readonly variable?: boolean;
+  /** 1.5: the same counts taken while the plugin was played through its MIDI input. */
+  readonly noteSweep?: NoteSweepMeasurement;
   readonly unmeasuredReason?: string;
   readonly unmeasuredDetail?: string;
 }
@@ -834,9 +874,20 @@ function readCostAtRate(value: unknown): CostAtRate | undefined {
     ...optional("nsPerSampleMax", finiteNumber(value.nsPerSampleMax)),
     ...optional("warmupNsPerSampleMedian", finiteNumber(value.warmupNsPerSampleMedian)),
     ...optional("silentOutput", booleanValue(value.silentOutput)),
+    ...optional("voices", readVoicesHeld(value.voices)),
   };
 }
 
+/** The notes held, or `undefined` unless the count and a known basis are there. */
+export function readVoicesHeld(value: unknown): VoicesHeld | undefined {
+  if (!isRecord(value)) return undefined;
+  const held = positiveNumber(value.held);
+  const basis = isVoiceBasis(value.basis) ? value.basis : undefined;
+  const capacity = finiteNumber(value.capacity);
+  if (held === undefined || !Number.isInteger(held) || basis === undefined) return undefined;
+  return { held, basis, ...(capacity !== undefined && Number.isInteger(capacity) && capacity >= 0 ? { capacity } : {}) };
+}
+
 function readCost(value: unknown): CostMeasurement | undefined {
   if (!isRecord(value)) return undefined;
   return {
@@ -942,10 +993,37 @@ function readRtSafety(value: unknown): RtSafetyMeasurement | undefined {
     ...optional("locksInRun", finiteNumber(value.locksInRun)),
     ...optional("syscallsInRun", finiteNumber(value.syscallsInRun)),
     ...optional("variable", booleanValue(value.variable)),
+    ...optional("noteSweep", readNoteSweep(value.noteSweep)),
     ...reasonOf(value),
   };
 }
 
+/** A note sweep, or `undefined` unless it says whether it was applicable; a count it cannot vouch for is left out. */
+export function readNoteSweep(value: unknown): NoteSweepMeasurement | undefined {
+  if (!isRecord(value)) return undefined;
+  const applicable = booleanValue(value.applicable);
+  if (applicable === undefined) return undefined;
+  if (!applicable) return { applicable };
+  const dialect = value.dialect === "clap" || value.dialect === "midi" ? value.dialect : undefined;
+  const counted = (v: unknown) => {
+    const n = finiteNumber(v);
+    return n !== undefined && Number.isInteger(n) && n >= 0 ? n : undefined;
+  };
+  return {
+    applicable,
+    ...optional("dialect", dialect),
+    ...optional("blocks", counted(value.blocks)),
+    ...optional("blockFrames", counted(value.blockFrames)),
+    ...optional("noteEvents", counted(value.noteEvents)),
+    ...optional("processErrors", counted(value.processErrors)),
+    ...optional("nonFinite", booleanValue(value.nonFinite)),
+    ...optional("interposer", booleanValue(value.interposer)),
+    ...optional("allocationsInRun", counted(value.allocationsInRun)),
+    ...optional("locksInRun", counted(value.locksInRun)),
+    ...optional("syscallsInRun", counted(value.syscallsInRun)),
+  };
+}
+
 function readFeatures(value: unknown): FeaturesMeasurement | undefined {
   if (!isRecord(value)) return undefined;
   return {

package/src/measurement/probe-json.ts

@@ -35,6 +35,7 @@ import type {
   PluginTopology,
 } from "./format.js";
 import { booleanValue, finiteNumber, isRecord, nonEmptyString, optional, positiveNumber } from "./guards.js";
+import { readVoicesHeld } from "./format.js";
 import type { MeasurementDimension } from "./vocabulary.js";
 
 /** One free-text prober failure, and the vocabulary term it means. */
@@ -55,6 +56,8 @@ export const PROBE_REASON_RULES: readonly ReasonRule[] = [
   { match: /^no-audio-in$/, code: "no-audio-in" },
   { match: /^no-audio-out$/, code: "no-audio-out" },
   { match: /^silent-output$/, code: "silent-output" },
+  { match: /^voices-unknown$/, code: "voices-unknown" },
+  { match: /hosting\.worker\.nonconforming/, code: "worker-nonconforming" },
   { match: /worker crashed|worker desync|worker unavailable/, code: "probe-crashed" },
   { match: /timed out|timeout/, code: "probe-timeout" },
   { match: /non-finite/, code: "non-finite-output" },
@@ -197,6 +200,7 @@ function readCost(value: unknown): CostMeasurement | undefined {
         ...optional("nsPerSampleMax", finiteNumber(reading.nsPerSampleMax)),
         ...optional("warmupNsPerSampleMedian", finiteNumber(reading.warmupNsPerSampleMedian)),
         ...optional("silentOutput", booleanValue(reading.silentOutput)),
+        ...optional("voices", readVoicesHeld(reading.voices)),
       };
     }
   }

package/src/measurement/sweep-jsonl.ts

@@ -29,7 +29,7 @@ import type {
   SoakReading,
   StabilityMeasurement,
 } from "./format.js";
-import { readIntegrity, readLifecycle, readSoakAtRate, readThreads } from "./format.js";
+import { readIntegrity, readLifecycle, readNoteSweep, readSoakAtRate, readThreads } from "./format.js";
 import { booleanValue, finiteNumber, isRecord, mapArray, nonEmptyString, optional, positiveNumber } from "./guards.js";
 
 /** The sweep's three passes, each a list of parsed JSONL lines. Only `measurements` is required. */
@@ -106,6 +106,7 @@ function rtSafetyOf(row: Record<string, unknown>): RtSafetyMeasurement {
     ...optional("locksInRun", finiteNumber(rt.locksInRun)),
     ...optional("syscallsInRun", finiteNumber(rt.syscallsInRun)),
     ...optional("variable", booleanValue(rt.variable)),
+    ...optional("noteSweep", readNoteSweep(rt.noteSweep)),
   };
 }
 

package/src/measurement/vocabulary.ts

@@ -85,6 +85,25 @@ export const UNMEASURED_TERMS: readonly UnmeasuredTerm[] = [
       "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: "no-voices",
+    kind: "nothing-to-measure",
+    description:
+      "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.",
+  },
+  {
+    code: "notes-unplayable",
+    kind: "nothing-to-measure",
+    description: "An instrument whose note input reads no dialect the prober speaks (CLAP's or MIDI's): it cannot be played.",
+  },
+  {
+    code: "voices-unknown",
+    kind: "not-attempted",
+    description:
+      "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.",
+  },
   {
     code: "refused-instantiation",
     kind: "probe-failed",
@@ -112,6 +131,13 @@ export const UNMEASURED_TERMS: readonly UnmeasuredTerm[] = [
       "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 " +
+      "specification does not allow: it was refused before any call, not measured.",
+  },
   {
     code: "probe-error",
     kind: "probe-failed",
@@ -310,3 +336,15 @@ export type HostIsolation = (typeof HOST_ISOLATIONS)[number];
 export const HOST_LATENCY_HANDLING = ["compensated", "uncompensated"] as const;
 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 = ["declared", "probe"] as const;
+export type VoiceBasis = (typeof VOICE_BASES)[number];
+
+export function isVoiceBasis(value: unknown): value is VoiceBasis {
+  return VOICE_BASES.some((b) => b === value);
+}