@openmixer/plugin-qualify 0.10.1 → 0.12.0

package/src/clap-qualify.ts

@@ -10,26 +10,22 @@
  * read, a prober that is absent, crashed or timed out, is a {@link ClapQualifyError}: nothing was
  * measured, and nothing is rated.
  */
-import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 
-import {
-  CLAP_QUALIFY_TIMEOUT_S,
-  CLAP_QUALIFY_TOOL_NAME,
-  CLAP_SWEEP_BLOCKS,
-  CLAP_SWEEP_FRAMES,
-  RT_INTERPOSE_NAME,
-} from "./qualify-declarations.js";
+import { CLAP_QUALIFY_TOOL_NAME, RT_INTERPOSE_NAME } from "./qualify-declarations.js";
 import {
   HOSTING_CODE,
   clapRtReasons,
   contributedHostingRating,
   noteSweepReasons,
   rtSafetyReasons,
+  type ClapLatencyAtRate,
   type HostingReason,
   type PluginClapMeasurement,
   type PluginNoteSweepMeasurement,
   type PluginRtSafetyMeasurement,
+  type PluginStabilityMeasurement,
+  type QualifiedPlugin,
 } from "./hosting-suitability.js";
 import {
   OMX_CLAP_HOST_CONFIGURED_EXTENSIONS,
@@ -37,11 +33,12 @@ import {
   OPENMIXER_CONSOLE_PROFILE,
   type HostProfile,
 } from "./host-profiles.js";
-import type { PluginTarget } from "./loader.js";
 import type { QualifyVerdict } from "./qualify-cli.js";
 import { RATING_SEVERITY, worstRating, type SuitabilityRating } from "./rating.js";
 import { halfPopulatedRefusal, locateNativeTools } from "./tool-paths.js";
-import { readIntegrity, type IntegrityMeasurement } from "./measurement/format.js";
+import { readIntegrity, type IntegrityMeasurement, type VoicesHeld } from "./measurement/format.js";
+import { isVoiceBasis } from "./measurement/vocabulary.js";
+import { coreFraction } from "./cost-fields.js";
 
 export class ClapQualifyError extends Error {
   constructor(message: string) {
@@ -69,6 +66,45 @@ export interface ClapProbedFacts extends PluginClapMeasurement {
   readonly nonFinite: boolean;
 }
 
+/** One rate's cost: the block times in nanoseconds per sample, warm-up dropped, and the notes held for an instrument. */
+export interface ClapCostFigure {
+  readonly nsPerSampleMedian: number;
+  readonly nsPerSampleP95: number;
+  readonly nsPerSampleMin: number;
+  readonly nsPerSampleMax: number;
+  /** The median of the dropped warm-up blocks: the evidence that dropping them was warranted. */
+  readonly warmupNsPerSampleMedian: number;
+  readonly blocks: number;
+  /** For an instrument: the notes held while it was timed. Absent for an effect. */
+  readonly voices?: VoicesHeld;
+}
+
+/** One rate the cost arm did not time, and why; an instrument's declared capacity is kept when it has one. */
+export interface ClapCostUnmeasured {
+  readonly unmeasuredReason: string;
+  readonly unmeasuredDetail: string;
+  readonly voices?: { readonly capacity: number };
+}
+
+export type ClapCostAtRate = ClapCostFigure | ClapCostUnmeasured;
+
+export function isClapCostFigure(at: ClapCostAtRate): at is ClapCostFigure {
+  return !("unmeasuredReason" in at);
+}
+
+/**
+ * The cost arm: every rate timed with every parameter swept, an effect fed noise and an instrument
+ * holding notes (`notes-held`), each rate's figures or the reason it has none.
+ */
+export interface ClapCostReading {
+  readonly stimulus: "notes-held" | "noise";
+  readonly blockFrames: number;
+  readonly warmupBlocks: number;
+  /** The percentile `nsPerSampleP95` is taken at. */
+  readonly percentile: number;
+  readonly perRate: Readonly<Record<string, ClapCostAtRate>>;
+}
+
 /** One plugin's line from `clap-qualify`. */
 export interface ClapQualifyLine {
   readonly uri: string;
@@ -80,6 +116,8 @@ export interface ClapQualifyLine {
   readonly rtSafety: ClapRtSafetyReading;
   /** The note sweep: the plugin played through its note input, counted apart. */
   readonly noteSweep: ClapNoteSweepReading;
+  /** The cost arm; absent when the plugin did not initialise and activate headless. */
+  readonly cost?: ClapCostReading;
   /**
    * The pin (spec §11): the `.clap`'s digest by its name in its directory and the layout fingerprint
    * the prober computed through plugin-hostd's `pin.h`, or the reason it took none.
@@ -122,10 +160,17 @@ function readClap(v: unknown): ClapProbedFacts {
   if (!isRecord(v)) return bad("no clap facts");
   const latencyIn = v["latency"];
   if (!isRecord(latencyIn)) return bad("clap has no latency map");
-  const latency: Record<string, { declaredFrames: number; measuredFrames: number }> = {};
+  const latency: Record<string, ClapLatencyAtRate> = {};
   for (const [rate, at] of Object.entries(latencyIn)) {
     if (!/^[1-9]\d*$/.test(rate) || !isRecord(at)) return bad(`clap latency at ${rate}`);
-    latency[rate] = { declaredFrames: count(at, "declaredFrames", `latency ${rate}`), measuredFrames: count(at, "measuredFrames", `latency ${rate}`) };
+    if (at["from"] !== undefined && at["from"] !== "note") return bad(`clap latency at ${rate} from ${JSON.stringify(at["from"])}`);
+    if (at["heard"] !== undefined && (at["from"] !== "note" || at["heard"] !== false)) return bad(`clap latency at ${rate} heard`);
+    latency[rate] = {
+      declaredFrames: count(at, "declaredFrames", `latency ${rate}`),
+      measuredFrames: count(at, "measuredFrames", `latency ${rate}`),
+      ...(at["from"] === "note" ? { from: "note" as const } : {}),
+      ...(at["heard"] === false ? { heard: false } : {}),
+    };
   }
   return {
     mainInputChannels: count(v, "mainInputChannels", "clap"),
@@ -183,6 +228,120 @@ function readNoteSweep(v: unknown): ClapNoteSweepReading {
   };
 }
 
+function figure(o: Record<string, unknown>, key: string, where: string): number {
+  const v = o[key];
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : bad(`${where} has no figure ${key}`);
+}
+
+function readVoices(v: unknown, where: string): { held?: number; basis?: VoicesHeld["basis"]; capacity?: number } {
+  if (!isRecord(v)) return bad(`${where} voices is not an object`);
+  const out: { held?: number; basis?: VoicesHeld["basis"]; capacity?: number } = {};
+  if ("held" in v || "basis" in v) {
+    const basis = v["basis"];
+    if (!isVoiceBasis(basis)) return bad(`${where} voices basis ${JSON.stringify(basis)}`);
+    const held = count(v, "held", `${where} voices`);
+    if (held === 0) return bad(`${where} holds no note`);
+    out.held = held;
+    out.basis = basis;
+  }
+  if ("capacity" in v) out.capacity = count(v, "capacity", `${where} voices`);
+  return out;
+}
+
+function readCostAtRate(v: unknown, where: string, notes: boolean): ClapCostAtRate {
+  if (!isRecord(v)) return bad(`${where} is not an object`);
+  const voices = v["voices"] === undefined ? undefined : readVoices(v["voices"], where);
+  if (voices !== undefined && !notes) return bad(`${where} holds notes for a plugin fed noise`);
+  if (v["unmeasuredReason"] !== undefined) {
+    if (voices?.held !== undefined) return bad(`${where} held notes and timed nothing`);
+    return {
+      unmeasuredReason: str(v, "unmeasuredReason", where),
+      unmeasuredDetail: str(v, "unmeasuredDetail", where),
+      ...(voices?.capacity === undefined ? {} : { voices: { capacity: voices.capacity } }),
+    };
+  }
+  if (notes && (voices === undefined || voices.held === undefined || voices.basis === undefined)) {
+    return bad(`${where} timed an instrument without saying what it held`);
+  }
+  const blocks = count(v, "blocks", where);
+  if (blocks === 0) return bad(`${where} timed no block`);
+  return {
+    nsPerSampleMedian: figure(v, "nsPerSampleMedian", where),
+    nsPerSampleP95: figure(v, "nsPerSampleP95", where),
+    nsPerSampleMin: figure(v, "nsPerSampleMin", where),
+    nsPerSampleMax: figure(v, "nsPerSampleMax", where),
+    warmupNsPerSampleMedian: figure(v, "warmupNsPerSampleMedian", where),
+    blocks,
+    ...(voices?.held === undefined || voices.basis === undefined
+      ? {}
+      : { voices: { held: voices.held, basis: voices.basis, ...(voices.capacity === undefined ? {} : { capacity: voices.capacity }) } }),
+  };
+}
+
+function readCost(v: unknown): ClapCostReading {
+  if (!isRecord(v)) return bad("cost is not an object");
+  const stimulus = str(v, "stimulus", "cost");
+  if (stimulus !== "notes-held" && stimulus !== "noise") return bad(`cost stimulus ${stimulus}`);
+  const perRateIn = v["perRate"];
+  if (!isRecord(perRateIn)) return bad("cost has no perRate map");
+  const perRate: Record<string, ClapCostAtRate> = {};
+  for (const [rate, at] of Object.entries(perRateIn)) {
+    if (!/^[1-9]\d*$/.test(rate)) return bad(`cost rate ${rate}`);
+    perRate[rate] = readCostAtRate(at, `cost at ${rate}`, stimulus === "notes-held");
+  }
+  return {
+    stimulus,
+    blockFrames: count(v, "blockFrames", "cost"),
+    warmupBlocks: count(v, "warmupBlocks", "cost"),
+    percentile: figure(v, "percentile", "cost"),
+    perRate,
+  };
+}
+
+/**
+ * The cost arm's figures as the classifier's cost gate reads them, per rate: the median and the P95
+ * per sample, and the P95 as a fraction of one core at that rate. A rate the arm did not time is absent.
+ */
+export function clapCostPerRate(
+  cost: ClapCostReading | undefined,
+): Record<string, { coreFractionP95: number; nsPerSampleMedian: number; nsPerSampleP95: number; voices?: VoicesHeld }> {
+  const out: Record<string, { coreFractionP95: number; nsPerSampleMedian: number; nsPerSampleP95: number; voices?: VoicesHeld }> = {};
+  for (const [rate, at] of Object.entries(cost?.perRate ?? {})) {
+    if (!isClapCostFigure(at)) continue;
+    const fraction = coreFraction(at.nsPerSampleP95, Number(rate));
+    if (fraction === undefined) continue;
+    out[rate] = {
+      coreFractionP95: fraction,
+      nsPerSampleMedian: at.nsPerSampleMedian,
+      nsPerSampleP95: at.nsPerSampleP95,
+      ...(at.voices === undefined ? {} : { voices: at.voices }),
+    };
+  }
+  return out;
+}
+
+/**
+ * A prober line as the plugin the full classifier (`classifyPluginHosting`) reads: the CLAP facts, the
+ * interposer's counts with the note sweep beside them, and the cost arm's figures per rate. The prober
+ * measures no stability (that is the soak's), so the caller passes what it has; without it the verdict
+ * is `unknown` on stability, never a pass.
+ */
+export function qualifiedPluginOfClapLine(line: ClapQualifyLine, stability?: PluginStabilityMeasurement): QualifiedPlugin {
+  const { events: _events, ...rtSafety } = line.rtSafety;
+  const { events: _noteEvents, ...noteSweep } = line.noteSweep;
+  const { nonFinite: _nonFinite, ...clap } = line.clap;
+  return {
+    format: "clap",
+    audioInputs: line.clap.mainInputChannels,
+    audioOutputs: line.clap.mainOutputChannels,
+    hasMidiIn: line.clap.noteInputs > 0,
+    clap,
+    rtSafety: { ...rtSafety, noteSweep },
+    cpuCost: { perRate: clapCostPerRate(line.cost) },
+    ...(stability === undefined ? {} : { stability }),
+  };
+}
+
 /** One line of the prober's stdout, or a {@link ClapQualifyError} saying how it differs. */
 export function parseClapQualifyLine(text: string): ClapQualifyLine {
   let v: unknown;
@@ -208,6 +367,7 @@ export function parseClapQualifyLine(text: string): ClapQualifyLine {
     clap: readClap(v["clap"]),
     rtSafety: readRtSafety(v["rtSafety"]),
     noteSweep: readNoteSweep(v["noteSweep"]),
+    ...(v["cost"] === undefined ? {} : { cost: readCost(v["cost"]) }),
     integrity: readIntegrity(v["integrity"]) ?? bad("no integrity"),
   };
 }
@@ -223,9 +383,11 @@ export function parseClapQualifyOutput(stdout: string): ClapQualifyLine[] {
  * The document's schema name; a reader refuses any other it does not know. `/2` is `/1` with
  * `measured.noteSweep` added and the note sweep's reasons folded into `verdict` (a plugin with no
  * note input gets none, so its `/2` verdict is its `/1` verdict); every `/1` field is unchanged, so
- * a `/1` reader of `verdict.rating` and `verdict.rtSafe` reads a `/2` document right.
+ * a `/1` reader of `verdict.rating` and `verdict.rtSafe` reads a `/2` document right. `/3` is `/2`
+ * with `measured.cost` added (the cost arm, an instrument's with the notes it held), which no
+ * verdict reads.
  */
-export const RT_SAFETY_DOCUMENT_SCHEMA = "plugin-qualify.rt-safety/2";
+export const RT_SAFETY_DOCUMENT_SCHEMA = "plugin-qualify.rt-safety/3";
 
 /**
  * The RT-safety verdict of one plugin binary for one console: keyed by the binary's SHA-256 and
@@ -254,6 +416,7 @@ export interface RtSafetyDocument {
     readonly clap: ClapProbedFacts;
     readonly rtSafety: ClapRtSafetyReading;
     readonly noteSweep: ClapNoteSweepReading;
+    readonly cost?: ClapCostReading;
     readonly integrity: IntegrityMeasurement;
   };
 }
@@ -296,6 +459,7 @@ export function rtSafetyDocument(line: ClapQualifyLine, profile: HostProfile = O
       clap: line.clap,
       rtSafety: line.rtSafety,
       noteSweep: line.noteSweep,
+      ...(line.cost === undefined ? {} : { cost: line.cost }),
       integrity: line.integrity,
     },
   };
@@ -318,47 +482,7 @@ export function rtSafetyDocumentName(doc: RtSafetyDocument): string {
   return `${doc.plugin.binary.sha256}.${doc.console}.rt-safety.json`;
 }
 
-// --- running the prober --------------------------------------------------------------------------
-
-/** What a run of the prober gave back; `error` is a spawn failure, `signal` a death. */
-export interface ClapQualifyRunResult {
-  readonly status: number | null;
-  readonly signal?: string | null;
-  readonly stdout: string;
-  readonly stderr?: string;
-  readonly error?: Error;
-}
-
-export type ClapQualifyRun = (
-  tool: string,
-  args: readonly string[],
-  env: Readonly<Record<string, string | undefined>>,
-  timeoutMs: number,
-) => ClapQualifyRunResult;
-
-const spawnQualify: ClapQualifyRun = (tool, args, env, timeoutMs) => {
-  const r = spawnSync(tool, [...args], { encoding: "utf8", env: { ...env }, timeout: timeoutMs, maxBuffer: 64 << 20 });
-  return {
-    status: r.status,
-    signal: r.signal,
-    stdout: r.stdout ?? "",
-    stderr: r.stderr ?? "",
-    ...(r.error === undefined ? {} : { error: r.error }),
-  };
-};
-
-export interface ClapQualifyOptions {
-  /** The rates the plugin is activated and swept at. */
-  readonly rates: readonly number[];
-  /** Runs the prober; the default spawns it. */
-  readonly run?: ClapQualifyRun;
-  /** Where the two settings are read from; the default is `process.env`. */
-  readonly env?: Readonly<Record<string, string | undefined>>;
-  /** Whether a file exists; the default asks the filesystem. */
-  readonly exists?: (path: string) => boolean;
-  /** The host extensions the prober offers beyond the console's, each one of {@link OMX_CLAP_HOST_CONFIGURED_EXTENSIONS}. */
-  readonly offer?: readonly string[];
-}
+// --- the prober and the interposer a run uses ---------------------------------------------------
 
 /**
  * The prober and the interposer this run uses: each its setting, else both from one place, the
@@ -381,44 +505,6 @@ export function clapQualifyTools(
   return { tool: tool!, interposer: interposer! };
 }
 
-/**
- * Qualify the plugins of one `.clap` (all of them, or the one `id` names) under the interposer.
- * Absent tools, a crash, a timeout, a load failure or an unreadable line throw: none of them is a
- * measurement.
- */
-export function qualifyClap(binaryPath: string, id: string | undefined, options: ClapQualifyOptions): ClapQualifyLine[] {
-  const env = options.env ?? process.env;
-  const { tool, interposer } = clapQualifyTools(env, options.exists ?? existsSync);
-  const args = [
-    "--rates",
-    options.rates.join(","),
-    "--block",
-    String(CLAP_SWEEP_FRAMES),
-    "--blocks",
-    String(CLAP_SWEEP_BLOCKS),
-    ...(options.offer === undefined || options.offer.length === 0 ? [] : ["--offer", options.offer.join(",")]),
-    binaryPath,
-    ...(id === undefined ? [] : [id]),
-  ];
-  const r = (options.run ?? spawnQualify)(tool, args, { ...env, LD_PRELOAD: interposer }, CLAP_QUALIFY_TIMEOUT_S * 1000);
-  if (r.error !== undefined) throw new ClapQualifyError(`cannot run ${tool}: ${r.error.message}`);
-  if (r.signal) throw new ClapQualifyError(`${binaryPath} killed the prober (${r.signal})`);
-  if (r.status !== 0) throw new ClapQualifyError(`${tool} exited ${String(r.status)} on ${binaryPath}: ${(r.stderr ?? "").trim()}`);
-  const lines = parseClapQualifyOutput(r.stdout);
-  if (lines.length === 0) throw new ClapQualifyError(`${tool} printed nothing for ${binaryPath}`);
-  return lines;
-}
-
-// --- the CLI's CLAP pass -------------------------------------------------------------------------
-
-/** What the CLAP pass of one run produced: a document per plugin and console, and a row per verdict. */
-export interface ClapQualifyPass {
-  readonly documents: readonly RtSafetyDocument[];
-  readonly verdicts: readonly QualifyVerdict[];
-  /** Each target that could not be measured, with why; its verdict rows read `unknown`, unmeasured. */
-  readonly failures: readonly { readonly uri: string; readonly problem: string }[];
-}
-
 /**
  * What the prober must offer beyond the console's extensions to measure for `profile`: the extra
  * extensions of its list, when the prober can offer each and the list holds the console's; `undefined`
@@ -432,48 +518,3 @@ export function proberOffer(profile: HostProfile): readonly string[] | undefined
   if (!extra.every((e) => OMX_CLAP_HOST_CONFIGURED_EXTENSIONS.includes(e))) return undefined;
   return OMX_CLAP_HOST_CONFIGURED_EXTENSIONS.filter((e) => extra.includes(e));
 }
-
-/**
- * Qualify every CLAP target, one prober run per target and set of offered extensions (a crash takes
- * only that plugin), and judge each line under every host profile, from the run that offered that
- * profile's extensions. A target without a binary path (a bare `urn:clap:` id) has nothing to load
- * and is a failure, never a pass.
- */
-export function qualifyClapTargets(
-  targets: readonly PluginTarget[],
-  options: ClapQualifyOptions & { readonly profiles?: readonly HostProfile[] },
-): ClapQualifyPass {
-  const profiles = options.profiles ?? [OPENMIXER_CONSOLE_PROFILE];
-  const documents: RtSafetyDocument[] = [];
-  const verdicts: QualifyVerdict[] = [];
-  const failures: { uri: string; problem: string }[] = [];
-  for (const target of targets) {
-    const id = target.uri.startsWith("urn:clap:") ? target.uri.slice("urn:clap:".length) : undefined;
-    // one run per distinct offer, the console's (none) for a profile the prober cannot stand in for
-    const offers = new Map<string, readonly string[]>();
-    for (const profile of profiles) {
-      const offer = proberOffer(profile) ?? [];
-      offers.set(offer.join(","), offer);
-    }
-    const runs = new Map<string, ClapQualifyLine[]>();
-    try {
-      if (target.binaryPath === undefined) throw new ClapQualifyError(`${target.uri}: no .clap to load; name the file or a directory holding it`);
-      for (const [key, offer] of offers) runs.set(key, qualifyClap(target.binaryPath, id, { ...options, offer }));
-    } catch (e) {
-      if (!(e instanceof ClapQualifyError)) throw e;
-      failures.push({ uri: target.uri, problem: e.message });
-      for (const profile of profiles) {
-        verdicts.push({ uri: target.uri, host: profile.id, measured: false, rating: "unknown", qualified: false, deciding: "not-measured" });
-      }
-      continue;
-    }
-    for (const profile of profiles) {
-      for (const line of runs.get((proberOffer(profile) ?? []).join(","))!) {
-        const doc = rtSafetyDocument(line, profile);
-        documents.push(doc);
-        verdicts.push(rtSafetyVerdict(doc));
-      }
-    }
-  }
-  return { documents, verdicts, failures };
-}

package/src/cost-fields.ts

@@ -70,3 +70,42 @@ export function classifierCostFromDocument(reading: CostAtRate, rate: number): C
     [COST_FIELDS.classifier.coreFraction]: fraction,
   };
 }
+
+/**
+ * The key of one point of a cost grid: the rate and the quantum it was measured at. One place spells it,
+ * so the reader that fills a grid and the gate that looks a point up cannot disagree.
+ */
+export function costPointKey(rate: number, quantum: number): string {
+  return `${rate}/${quantum}`;
+}
+
+/** The percentile the classifier's `nsPerSampleP95` is. A figure taken at another percentile is not that field. */
+export const CLASSIFIER_PERCENTILE = 95;
+
+/** One point of a grid as it is measured: the figures {@link gridCostReadings} turns into the classifier's. */
+export interface CostGridPoint {
+  readonly rate: number;
+  readonly quantum: number;
+  readonly outcome: string;
+  readonly cost?: { readonly median: number; readonly percentile: { readonly p: number; readonly value: number } };
+}
+
+/**
+ * The classifier's cost readings of a grid, by {@link costPointKey}. A point that did not end `probe.ok`, has no
+ * cost, or whose percentile is not {@link CLASSIFIER_PERCENTILE} has no reading: the gate then reads the pair as
+ * unmeasured, which is the truth, where a figure under the wrong name would be judged as if it were the P95.
+ */
+export function gridCostReadings(points: readonly CostGridPoint[], okOutcome: string): Record<string, ClassifierCostReading> {
+  const out: Record<string, ClassifierCostReading> = {};
+  for (const p of points) {
+    if (p.outcome !== okOutcome || p.cost === undefined || p.cost.percentile.p !== CLASSIFIER_PERCENTILE) continue;
+    const fraction = coreFraction(p.cost.percentile.value, p.rate);
+    if (fraction === undefined) continue;
+    out[costPointKey(p.rate, p.quantum)] = {
+      [COST_FIELDS.classifier.median]: p.cost.median,
+      [COST_FIELDS.classifier.percentile]: p.cost.percentile.value,
+      [COST_FIELDS.classifier.coreFraction]: fraction,
+    };
+  }
+  return out;
+}

package/src/hosting-codes.ts

@@ -61,6 +61,7 @@ export const HOSTING_CODE = {
   clapFormatNotHosted: 'hosting.clap.format-not-hosted',
   clapExtensionsNotCovered: 'hosting.clap.extensions-not-covered',
   outputNonFinite: 'hosting.output.non-finite',
+  workerNonconforming: 'hosting.worker.nonconforming',
   // The pin (spec §11; one-contract §10.3): a host's refusal at add, by the daemon's code.
   integrityUnpinned: 'hosting.integrity.unpinned',
   integrityBinaryMismatch: 'hosting.integrity.binary-mismatch',

package/src/hosting-suitability.ts

@@ -52,11 +52,19 @@ export interface QualifiedPlugin {
     readonly scalingClass?: string;
     readonly paramSweep?: unknown;
   };
-  /** Measured cost per rate (Hz as a string key). */
+  /** Measured cost: per rate (Hz as a string key), or per rate AND quantum. */
   readonly cpuCost?: {
+    /** One figure per rate, at the block the prober ran: the old format. Read only when `perRateQuantum` is absent. */
     readonly perRate?: Readonly<
       Record<string, { readonly coreFractionP95: number; readonly nsPerSampleMedian: number; readonly nsPerSampleP95: number }>
     >;
+    /**
+     * One figure per rate and quantum, keyed by {@link costPointKey}: a probe output's grid. When this is
+     * present it is the only cost there is, so a pair it lacks is unmeasured, never read from `perRate`.
+     */
+    readonly perRateQuantum?: Readonly<
+      Record<string, { readonly coreFractionP95: number; readonly nsPerSampleMedian: number; readonly nsPerSampleP95: number }>
+    >;
   };
   readonly stability?: PluginStabilityMeasurement;
   readonly rtSafety?: PluginRtSafetyMeasurement;
@@ -306,14 +314,20 @@ export type PluginLv2Features = Omit<FeaturesMeasurement, "unmeasuredReason" | "
 
 export { DEFAULT_HOSTING_POLICY, type HostingPolicy } from "./qualify-declarations.js";
 import { DEFAULT_HOSTING_POLICY, type HostingPolicy } from "./qualify-declarations.js";
-import { costFieldsMissing } from "./cost-fields.js";
+import { costFieldsMissing, costPointKey } from "./cost-fields.js";
 
 /** One declared rate's latency reading from the CLAP qualifier (CLAP spec §3, latency). */
 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;
 }
 
 /**
@@ -700,7 +714,13 @@ export function hostingCostReasons(
   options: HostingClassifyOptions,
   policy: HostingPolicy,
 ): readonly HostingReason[] {
-  const perRate = descriptor.cpuCost?.perRate?.[String(options.rate)];
+  const grid = descriptor.cpuCost?.perRateQuantum;
+  const perRate =
+    grid === undefined
+      ? descriptor.cpuCost?.perRate?.[String(options.rate)]
+      : options.quantum === undefined
+        ? undefined
+        : grid[costPointKey(options.rate, options.quantum)];
   if (perRate === undefined) {
     return [
       reason("cost", "objective", "unknown", HOSTING_CODE.costUnmeasured, {
@@ -761,6 +781,10 @@ export function hostingLatencyReasons(
   // one the benchmark declared unmeasurable, has not been judged and does not pass by
   // default. The oracle's first fixture omitted latency and still expected `suitable`,
   // which is how this branch was missing — a self-consistent suite proving nothing.
+  // A plugin whose worker interface was refused is not unmeasured by accident: it is not hostable.
+  if (typeof latency?.unmeasurable === "string" && latency.unmeasurable.includes(HOSTING_CODE.workerNonconforming)) {
+    return [reason("latency", "objective", "unsuitable", HOSTING_CODE.workerNonconforming)];
+  }
   if (latency === undefined || latency.unmeasurable !== undefined) {
     return [reason("latency", "objective", "unknown", HOSTING_CODE.latencyUnmeasured)];
   }
@@ -829,7 +853,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) : [];
@@ -838,7 +865,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,
@@ -960,12 +991,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),
@@ -974,6 +1008,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/index.ts

@@ -20,3 +20,8 @@ export * from "./qualify-cli.js";
 export * from "./pins-file.js";
 export * from "./measure-host.js";
 export * from "./cost-fields.js";
+export * from "./probe-output.js";
+export * from "./probe-judge.js";
+export * from "./qualification-record.js";
+export * from "./probe-runner.js";
+export * from "./judge-cli.js";