@openmixer/plugin-qualify 0.11.0 → 0.13.0

package/src/hosting-suitability.ts

@@ -148,12 +148,11 @@ export type HostingCode = (typeof HOSTING_CODE)[keyof typeof HOSTING_CODE];
  */
 export const CLAP_CORE_REFUSALS = {
   headlessFailed: "clapHeadlessFailed",
-  notAudioEffect: "clapNotAudioEffect",
   noteInput: "clapNoteInput",
   noAudioInput: "topologyNoAudioInput",
   noAudioOutput: "topologyNoAudioOutput",
   widerThanStrip: "topologyWiderThanStrip",
-  extraInputs: "topologyExtraInputs",
+  tooManyPorts: "topologyTooManyPorts",
   crashedLive: "stabilityCrashedLive",
   outputNonFinite: "outputNonFinite",
 } as const satisfies Record<string, keyof typeof HOSTING_CODE>;
@@ -164,12 +163,11 @@ export const CLAP_CORE_REFUSALS = {
  * refusal so the renderer holds no prose. A refusal without a line renders bare.
  */
 export const CLAP_CORE_REFUSAL_DESCRIPTIONS: { readonly [K in keyof typeof CLAP_CORE_REFUSALS]?: string } = {
-  notAudioEffect: "the plugin is not an audio effect",
   noteInput: "the plugin declares a note input the configuration refuses",
   noAudioInput: "the plugin has no audio input",
   noAudioOutput: "the plugin has no audio output",
   widerThanStrip: "the plugin is wider than the strip",
-  extraInputs: "the plugin has extra inputs, fed silence",
+  tooManyPorts: "the plugin has more ports than the auxiliary limit allows",
   crashedLive: "the plugin crashed live on this rig",
   outputNonFinite: "the plugin produced non-finite output",
 };
@@ -320,8 +318,14 @@ import { costFieldsMissing, costPointKey } from "./cost-fields.js";
 export interface ClapLatencyAtRate {
   /** `latency.get()` after `activate` at this rate; a plugin without the ext declares 0. */
   readonly declaredFrames: number;
-  /** Where the qualifier's impulse landed through `process()`, in frames. */
+  /** Where the qualifier's impulse landed through `process()`, in frames; for an instrument, where a note's
+   *  sound began. */
   readonly measuredFrames: number;
+  /** `note`: a plugin with no main audio input, measured from a note struck at frame 0 (the onset of its
+   *  sound, which an attack envelope may put later than its latency). Absent: from an impulse. */
+  readonly from?: "note";
+  /** `false`: the note was struck and nothing was heard, so there is no onset to read. */
+  readonly heard?: boolean;
 }
 
 /**
@@ -690,9 +694,6 @@ export function featureReasons(
         }),
       );
     }
-    if ((features.cvPorts ?? 0) > 0) {
-      out.push(reason("features", "objective", "unsuitable", HOSTING_CODE.featuresCv));
-    }
   }
   if (descriptor.hasMidiIn && !instruments) {
     out.push(reason("features", "objective", "conditional", HOSTING_CODE.featuresMidiIn));
@@ -815,7 +816,7 @@ export function hostingTopologyReasons(
     ];
   }
   return [
-    reason("topology", "objective", "conditional", HOSTING_CODE.topologyExtraInputs, { ins, outs }),
+    reason("topology", "objective", "conditional", HOSTING_CODE.topologyTooManyPorts, { ins, outs }),
   ];
 }
 
@@ -839,7 +840,7 @@ export function clapTopologyReasons(clap: PluginClapMeasurement | undefined, ins
     return [reason("topology", "objective", "unsuitable", HOSTING_CODE.topologyWiderThanStrip, { ins, outs })];
   }
   if (clap.sidechainInputs > 0) {
-    return [reason("topology", "objective", "unsuitable", HOSTING_CODE.topologyExtraInputs, { ins, outs, sidechains: clap.sidechainInputs })];
+    return [reason("topology", "objective", "unsuitable", HOSTING_CODE.topologyTooManyPorts, { ins, outs, sidechains: clap.sidechainInputs })];
   }
   return [reason("topology", "objective", "suitable", HOSTING_CODE.topologyMatched, { ins, outs })];
 }
@@ -847,7 +848,10 @@ export function clapTopologyReasons(clap: PluginClapMeasurement | undefined, ins
 /**
  * The CLAP arm of `latency` (CLAP spec §3): declared = measured at EVERY declared rate earns;
  * one rate that lies refuses (`unsuitable` — compensation reads the figure as truth); no rate
- * measured is `unknown`.
+ * measured is `unknown`. An instrument has no input to put an impulse in, so its figure is the onset
+ * of a note struck at frame 0: an onset before the declared latency is the same lie, one at or after
+ * it is resolved (an attack envelope sounds later than the plugin's delay, and that is no latency),
+ * and a note that was never heard is unmeasured.
  */
 export function clapLatencyReasons(clap: PluginClapMeasurement | undefined): readonly HostingReason[] {
   const rates = clap ? Object.keys(clap.latency) : [];
@@ -856,7 +860,11 @@ export function clapLatencyReasons(clap: PluginClapMeasurement | undefined): rea
   }
   for (const rate of rates) {
     const at = clap.latency[rate]!;
-    if (at.declaredFrames !== at.measuredFrames) {
+    if (at.from === "note" && at.heard === false) {
+      return [reason("latency", "objective", "unknown", HOSTING_CODE.latencyUnmeasured, { rate: Number(rate) })];
+    }
+    const lies = at.from === "note" ? at.measuredFrames < at.declaredFrames : at.declaredFrames !== at.measuredFrames;
+    if (lies) {
       return [
         reason("latency", "objective", "unsuitable", HOSTING_CODE.clapLatencyMismatch, {
           rate: Number(rate), declared: at.declaredFrames, measured: at.measuredFrames,
@@ -886,11 +894,6 @@ export function clapFeatureReasons(
   }
   const out: HostingReason[] = [];
   const offered = profile.clapExtensions;
-  const kindHosted =
-    clap.features.includes(CLAP_FEATURE_AUDIO_EFFECT) || (profile.instruments && clap.features.includes(CLAP_FEATURE_INSTRUMENT));
-  if (!kindHosted) {
-    out.push(reason("features", "objective", "unsuitable", HOSTING_CODE.clapNotAudioEffect, { features: clap.features.join(" ") }));
-  }
   if (!clap.headlessOk) {
     out.push(reason("features", "objective", "unsuitable", HOSTING_CODE.clapHeadlessFailed));
   } else {
@@ -978,12 +981,15 @@ export function classifyPluginHosting(
   // report could agree with itself while every served descriptor read unknown.
   // The CLAP arm: the SAME six dimensions, fed from the
   // qualifier's CLAP facts where the LV2 scan's facts do not exist for the format. Stability,
-  // the interposer's counts and the cost are format-blind and read unchanged.
+  // the interposer's counts and the cost are format-blind and read unchanged. A host that plays
+  // notes (an instrument host) also reads the note sweep: an instrument is clean at rest, so the
+  // parameter sweep alone says nothing about what a voice does.
   const reasons: HostingReason[] = descriptor.format === "clap"
     ? [
         ...stabilityReasons(descriptor.stability, policy, options.pluginBinary, sharesProcess, options.rate),
         ...rtSafetyReasons(descriptor.rtSafety),
         ...clapRtReasons(descriptor.clap),
+        ...(profile.instruments ? noteSweepReasons(descriptor.rtSafety?.noteSweep, descriptor.clap?.noteInputs ?? (descriptor.hasMidiIn ? 1 : 0)) : []),
         ...clapFeatureReasons(descriptor.clap, profile, descriptor.hasMidiIn),
         ...hostingCostReasons(descriptor, options, policy),
         ...clapLatencyReasons(descriptor.clap),
@@ -992,6 +998,7 @@ export function classifyPluginHosting(
     : [
         ...stabilityReasons(descriptor.stability, policy, options.pluginBinary, sharesProcess, options.rate),
         ...rtSafetyReasons(descriptor.rtSafety),
+        ...(profile.instruments ? noteSweepReasons(descriptor.rtSafety?.noteSweep, descriptor.hasMidiIn ? 1 : 0) : []),
         ...featureReasons(descriptor.lv2Features, descriptor, profile.lv2Features, options.quantum !== undefined, profile.instruments),
         ...hostingCostReasons(descriptor, options, policy),
         ...hostingLatencyReasons(descriptor, profile.latency),

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;
@@ -91,7 +99,7 @@ export interface MeasureOptions {
  * them: the provider's kinds (`--features`), its buf-size declarations (`--block-declares`) and its log
  * modes (`--log`). A conformance test reads both.
  */
-export const LV2_FEATURE_KINDS = ["map", "unmap", "options", "bounded", "worker", "default-state", "log"] as const;
+export const LV2_FEATURE_KINDS = ["map", "unmap", "options", "bounded", "worker", "default-state", "log", "rtmempool"] as const;
 export const LV2_BLOCK_DECLARATIONS = ["bounded", "fixed", "pow2"] as const;
 export const LV2_LOG_MODES = ["silent", "route", "capture"] as const;
 
@@ -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}`;
@@ -143,7 +147,7 @@ export interface MeasurementHost {
 
 /** How the latency figures in this document were taken. */
 export interface LatencyMethod {
-  /** A {@link ../vocabulary.METHOD_TERMS} code — `impulse-onset` or `declared-port`. */
+  /** A {@link ../vocabulary.METHOD_TERMS} code — `impulse-onset`, `declared-port` or `note-onset`. */
   readonly method: string;
   readonly blockFrames: number;
   /** What was fed in, in words. An onset measured through an opened gate is not the same
@@ -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,7 @@ 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" },
@@ -198,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)),
   };
 }