@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/src/measurement/vocabulary.ts

@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The controlled vocabularies the interchange format speaks.
+ *
+ * This is the boring file that decides whether two projects' measurements can be merged
+ * Everyone who has written an LV2 prober has invented their own
+ * words for "there was nothing to measure here", so nobody's results combine. The words
+ * are fixed here, each with the ONE property a merger actually needs to branch on —
+ * 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.
+ */
+
+import { nonEmptyString } from "./guards.js";
+
+// ---------------------------------------------------------------------------
+// Why a figure is absent
+// ---------------------------------------------------------------------------
+
+/**
+ * What an absent figure means for a MERGE, and it is the only distinction that changes
+ * behaviour:
+ *
+ * - `nothing-to-measure` — a property of the PLUGIN. An instrument has no audio input to
+ *   drive; a meter has no audio output to read. Any prober on any machine reaches the
+ *   same conclusion, so this outcome is as portable as a measurement and may override one.
+ * - `probe-failed` — a property of THIS RUN. The plugin crashed the worker, timed out,
+ *   refused to instantiate. It says nothing about the plugin's latency or cost, so it
+ *   must NOT override a figure someone else managed to take.
+ * - `not-attempted` — the run did not cover this plugin or this dimension at all. Neither
+ *   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";
+
+/** One term of the "why is there no figure" vocabulary. */
+export interface UnmeasuredTerm {
+  readonly code: string;
+  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.
+ */
+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. " +
+      "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: "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, " +
+      "not about the plugin — another host may well have it.",
+  },
+  {
+    code: "probe-error",
+    kind: "probe-failed",
+    description:
+      "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.",
+  },
+];
+
+const UNMEASURED_BY_CODE: ReadonlyMap<string, UnmeasuredTerm> = new Map(
+  UNMEASURED_TERMS.map((term) => [term.code, term]),
+);
+
+/**
+ * The vocabulary term for a code, or `undefined` when the code is not one of ours.
+ *
+ * A third-party document carrying an unknown reason is not an error — the format is meant
+ * to be extended by people we will never meet. {@link unmeasuredKind} is what a merger
+ * should consult, and it is deliberately conservative about strangers.
+ */
+export function unmeasuredTerm(code: string | undefined): UnmeasuredTerm | undefined {
+  return code === undefined ? undefined : UNMEASURED_BY_CODE.get(code);
+}
+
+/**
+ * How a merger must treat an absence reason. An UNKNOWN code resolves to `probe-failed`,
+ * the conservative answer: a reason we cannot interpret must never be allowed to delete
+ * somebody else's real measurement, and treating it as a plugin property would do exactly
+ * that.
+ */
+export function unmeasuredKind(code: string | undefined): UnmeasuredKind {
+  if (code === undefined) return "not-attempted";
+  return UNMEASURED_BY_CODE.get(code)?.kind ?? "probe-failed";
+}
+
+// ---------------------------------------------------------------------------
+// How latency moves with the sample rate
+// ---------------------------------------------------------------------------
+
+/**
+ * The rate-scaling laws, DERIVED from readings at several rates and never assumed from
+ * what a plugin is called. The population behind each term is in
+ * `CATALOG_PROVENANCE.md`'s 2026-07-28 rows.
+ */
+export interface ScalingTerm {
+  readonly code: string;
+  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." },
+];
+
+const SCALING_CODES: ReadonlySet<string> = new Set(SCALING_TERMS.map((t) => t.code));
+
+/** True when `code` is a scaling term this version of the format defines. */
+export function isKnownScalingCode(code: string): boolean {
+  return SCALING_CODES.has(code);
+}
+
+/**
+ * Why a derived scaling class is not the naive fit over every reading — `below-budget`,
+ * where the readings fit no law but are all small enough that the disagreement is the onset
+ * 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[];
+
+/** One of the {@link SCALING_NOTE_TERMS} codes — the words `latency.scalingNote` may carry. */
+export type ScalingNoteCode = (typeof SCALING_NOTE_TERMS)[number]["code"];
+
+/**
+ * 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.",
+  },
+];
+
+// ---------------------------------------------------------------------------
+// How a figure was taken
+// ---------------------------------------------------------------------------
+
+/** The measurement methods the format has names for. */
+export const METHOD_TERMS: readonly ScalingTerm[] = [
+  {
+    code: "impulse-onset",
+    description:
+      "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:
+      "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));
+
+/** True when `code` is a method term this version of the format defines. */
+export function isKnownMethodCode(code: string): boolean {
+  return METHOD_CODES.has(code);
+}
+
+/**
+ * The measurable dimensions. A document declares which of them it covers.
+ *
+ * `latency` and `cost` are 1.0's. `stability`, `rtSafety` and `features` joined in 1.1 for the
+ * 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;
+
+/**
+ * The dimensions the standalone prober (`scan.py` + `benchmark.py`, driven by `lv2-measure.mjs`
+ * and the console's Setup analysis) can measure. The three hosting dimensions come from a
+ * different tool — the `lv2-measure.c` sweep, read by `sweep-jsonl.ts` — so a run asked of the
+ * prober for `stability` would be asking it for something it cannot take.
+ */
+export const PROBED_DIMENSIONS = ["latency", "cost"] as const satisfies readonly (typeof MEASUREMENT_DIMENSIONS)[number][];
+
+/** One measurable dimension. */
+export type MeasurementDimension = (typeof MEASUREMENT_DIMENSIONS)[number];
+
+/** `value` as a dimension, or `undefined` when it is not one. */
+export function readDimension(value: unknown): MeasurementDimension | undefined {
+  const text = nonEmptyString(value);
+  return MEASUREMENT_DIMENSIONS.find((d) => d === text);
+}
+
+/**
+ * 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.
+ */
+export const VERDICT_RATINGS = ["suitable", "conditional", "unknown", "unsuitable"] as const;
+export type VerdictRating = (typeof VERDICT_RATINGS)[number];
+
+/** How a host runs its plugins (`2026-09-25-plugin-qualify.md` §3a). */
+export const HOST_ISOLATIONS = ["in-process", "per-process", "shared-process"] as const;
+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;
+export type HostLatencyHandling = (typeof HOST_LATENCY_HANDLING)[number];
+

package/src/qualify-cli.ts

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The `plugin-qualify` CLI's decisions, as pure functions: parse the arguments against `QUALIFY_OPTIONS`, print `--help` from the same table, resolve
+ * the named targets through the loader seam, turn each plugin's measurements into
+ * `classifyPluginHosting`'s verdict (never a second one), and pick the exit code.
+ * `bin/plugin-qualify.mjs` only spawns the measuring tools and calls these.
+ */
+import { readFileSync } from "node:fs";
+import { QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
+import { OPENMIXER_CONSOLE_PROFILE, readHostProfile, shippedHostProfile, type HostProfile } from "./host-profiles.js";
+import {
+  buildMeasurementDocument,
+  type DocumentVerdict,
+  type MeasuredPlugin,
+  type MeasurementDocument,
+  type MeasurementRun,
+} from "./measurement/format.js";
+import { classifyPluginHosting, type QualifiedPlugin } from "./hosting-suitability.js";
+import type { SuitabilityRating } from "./rating.js";
+import type { PluginLoader, PluginTarget } from "./loader.js";
+import { EXIT_CODE, OUTPUT_FORMATS, QUALIFY_OPTIONS, type OutputFormat } from "./qualify-options.js";
+
+export interface QualifyArgs {
+  readonly all: boolean;
+  readonly targets: readonly string[];
+  readonly rates: readonly number[];
+  readonly quanta: readonly number[];
+  readonly out?: string;
+  readonly format: OutputFormat;
+  readonly isolate: boolean;
+  readonly hostSweep: boolean;
+  /** `--host-profile` specs (a shipped id or a profile file), in order, once each. */
+  readonly hostProfiles: readonly string[];
+  readonly help: boolean;
+}
+
+export type ParseResult = { ok: true; args: QualifyArgs } | { ok: false; error: string };
+
+function defaultOf(flag: string): string {
+  const d = QUALIFY_OPTIONS.find((o) => o.flag === flag)?.default;
+  if (d === undefined) throw new Error(`${flag} declares no default`);
+  return d;
+}
+
+function numberList(text: string | undefined): number[] | undefined {
+  if (text === undefined || text === "") return undefined;
+  const out = [...new Set(text.split(",").map((t) => Number(t.trim())))];
+  return out.every((n) => Number.isInteger(n) && n > 0) ? out.sort((a, b) => a - b) : undefined;
+}
+
+export function parseQualifyArgs(argv: readonly string[]): ParseResult {
+  const known = new Set(QUALIFY_OPTIONS.map((o) => o.flag));
+  const takesValue = new Set(QUALIFY_OPTIONS.filter((o) => o.value !== undefined).map((o) => o.flag));
+  const seen = new Map<string, string | true>();
+  const targets: string[] = [];
+  // The one option that repeats: every host asked about is a verdict of its own.
+  const profileSpecs: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith("--")) {
+      targets.push(a);
+      continue;
+    }
+    if (!known.has(a)) return { ok: false, error: `unknown option ${a}` };
+    if (takesValue.has(a)) {
+      const v = argv[++i];
+      if (v === undefined) return { ok: false, error: `${a} needs a value` };
+      if (a === "--host-profile") profileSpecs.push(...v.split(",").map((t) => t.trim()).filter((t) => t !== ""));
+      seen.set(a, v);
+    } else seen.set(a, true);
+  }
+  const help = seen.has("--help");
+  const all = seen.has("--all");
+  if (!help && all && targets.length > 0) return { ok: false, error: "--all takes no plugin targets" };
+  if (!help && !all && targets.length === 0) return { ok: false, error: "name a plugin (URI or .lv2 bundle) or pass --all" };
+  const rates = numberList((seen.get("--rates") as string | undefined) ?? defaultOf("--rates"));
+  if (rates === undefined) return { ok: false, error: "--rates must be positive integers, comma-separated" };
+  const quanta = numberList((seen.get("--quanta") as string | undefined) ?? defaultOf("--quanta"));
+  if (quanta === undefined) return { ok: false, error: "--quanta must be positive integers, comma-separated" };
+  const format = (seen.get("--format") as string | undefined) ?? defaultOf("--format");
+  if (!(OUTPUT_FORMATS as readonly string[]).includes(format)) {
+    return { ok: false, error: `--format must be one of ${OUTPUT_FORMATS.join(", ")}` };
+  }
+  const out = seen.get("--out") as string | undefined;
+  const hostProfiles = [...new Set(profileSpecs.length > 0 ? profileSpecs : [defaultOf("--host-profile")])];
+  return {
+    ok: true,
+    args: {
+      all,
+      targets,
+      rates,
+      quanta,
+      ...(out === undefined ? {} : { out }),
+      format: format as OutputFormat,
+      isolate: seen.has("--isolate"),
+      hostSweep: !seen.has("--no-host-sweep"),
+      hostProfiles,
+      help,
+    },
+  };
+}
+
+export function helpText(): string {
+  const rows = QUALIFY_OPTIONS.map((o) => {
+    const left = o.value === undefined ? o.flag : `${o.flag} <${o.value}>`;
+    const def = o.default === undefined ? "" : ` (default: ${o.default})`;
+    return `  ${left.padEnd(28)}${o.describe}${def}`;
+  });
+  return [
+    "plugin-qualify — qualify audio plugins for real-time hosting",
+    "",
+    "  plugin-qualify <uri|bundle-path>...   exactly the named plugins; a .lv2 bundle = every plugin in it",
+    "  plugin-qualify --all                  every plugin lilv finds (LV2_PATH honoured)",
+    "",
+    ...rows,
+    "",
+    `exit ${EXIT_CODE.allQualified} all qualified / ${EXIT_CODE.someNotQualified} some not / ${EXIT_CODE.couldNotMeasure} could not measure`,
+    `defaults are declarations: rates ${QUALIFY_RATES.join(",")}, quanta ${QUALIFY_QUANTA.join(",")}`,
+    "",
+  ].join("\n");
+}
+
+export type ResolveResult =
+  | { ok: true; plugins: readonly PluginTarget[] }
+  | { ok: false; refused: readonly string[] };
+
+/** Every target through the loaders; a target no loader claims, or one naming no plugin, is refused. */
+export function resolveTargets(targets: readonly string[], loaders: readonly PluginLoader[]): ResolveResult {
+  const plugins = new Map<string, PluginTarget>();
+  const refused: string[] = [];
+  for (const t of targets) {
+    let found: readonly PluginTarget[] | undefined;
+    for (const l of loaders) {
+      found = l.resolve(t);
+      if (found !== undefined) break;
+    }
+    if (found === undefined || found.length === 0) {
+      refused.push(t);
+      continue;
+    }
+    for (const p of found) {
+      const prior = plugins.get(p.uri);
+      // A URI and its bundle name the same plugin: keep the richer record (bundle, binary).
+      if (prior === undefined || (prior.binary === undefined && p.binary !== undefined)) plugins.set(p.uri, p);
+    }
+  }
+  return refused.length > 0 ? { ok: false, refused } : { ok: true, plugins: [...plugins.values()] };
+}
+
+export type HostProfilesResult =
+  | { ok: true; profiles: readonly HostProfile[] }
+  | { ok: false; refused: readonly { spec: string; problem: string }[] };
+
+/** Read a profile file as JSON; `undefined` when it cannot be read or parsed. */
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Every `--host-profile` spec to a profile: a shipped id, else a profile file read through
+ * `readHostProfile`. An id nobody ships and no readable file names, a file the reader refuses, or
+ * two specs naming one id are refused — never judged against a default.
+ */
+export function resolveHostProfiles(
+  specs: readonly string[],
+  readJson: (path: string) => unknown = readJsonFile,
+): HostProfilesResult {
+  const profiles: HostProfile[] = [];
+  const refused: { spec: string; problem: string }[] = [];
+  for (const spec of specs) {
+    const shipped = shippedHostProfile(spec);
+    let profile: HostProfile | undefined = shipped;
+    if (profile === undefined) {
+      const json = readJson(spec);
+      if (json === undefined) {
+        refused.push({ spec, problem: "no shipped profile has this id, and no readable JSON file is at this path" });
+        continue;
+      }
+      const r = readHostProfile(json);
+      if (!r.ok) {
+        refused.push({ spec, problem: r.problem });
+        continue;
+      }
+      profile = r.profile;
+    }
+    if (profiles.some((p) => p.id === profile.id)) {
+      refused.push({ spec, problem: `a second profile with id ${profile.id}` });
+      continue;
+    }
+    profiles.push(profile);
+  }
+  return refused.length > 0 ? { ok: false, refused } : { ok: true, profiles };
+}
+
+export interface QualifyVerdict {
+  readonly uri: string;
+  /** The id of the host profile this verdict was judged against. */
+  readonly host: string;
+  /** False when nothing about the plugin was measured at all. */
+  readonly measured: boolean;
+  readonly rating: SuitabilityRating;
+  /** `rating === "suitable"` — the only meaning `qualified` has. */
+  readonly qualified: boolean;
+  /** The code of the reason that decided it (absent for `suitable`). */
+  readonly deciding?: string;
+}
+
+/**
+ * The verdict of each plugin under each host profile: `classifyPluginHosting`'s rating and
+ * deciding reason, nothing more. Each profile is judged at the live `rate`/`quantum` when the
+ * caller names them, else at the profile's own declared budget pair.
+ */
+export function qualifyPlugins(
+  measured: readonly { target: PluginTarget; plugin?: QualifiedPlugin }[],
+  options: { rate?: number; quantum?: number; profiles?: readonly HostProfile[] },
+): QualifyVerdict[] {
+  const profiles = options.profiles ?? [OPENMIXER_CONSOLE_PROFILE];
+  return measured.flatMap(({ target, plugin }) =>
+    profiles.map((profile): QualifyVerdict => {
+      if (plugin === undefined) {
+        return { uri: target.uri, host: profile.id, measured: false, rating: "unknown", qualified: false, deciding: "not-measured" };
+      }
+      const live = options.rate !== undefined;
+      const quantum = live ? options.quantum : profile.cost.quantum;
+      const v = classifyPluginHosting(plugin, {
+        rate: options.rate ?? profile.cost.rate,
+        ...(quantum === undefined ? {} : { quantum }),
+        ...(target.binary === undefined ? {} : { pluginBinary: target.binary }),
+        profile,
+      });
+      return {
+        uri: target.uri,
+        host: profile.id,
+        measured: true,
+        rating: v.rating,
+        qualified: v.rating === "suitable",
+        ...(v.deciding === undefined ? {} : { deciding: v.deciding.code }),
+      };
+    }),
+  );
+}
+
+/** The run's interchange document (v1.2, §6): the raw plugin blocks, the profiles judged against, and the verdicts. */
+export function judgedDocument(
+  run: MeasurementRun,
+  plugins: readonly MeasuredPlugin[],
+  profiles: readonly HostProfile[],
+  verdicts: readonly QualifyVerdict[],
+): MeasurementDocument {
+  const written: DocumentVerdict[] = verdicts.map((v) => ({
+    uri: v.uri,
+    host: v.host,
+    rating: v.rating,
+    qualified: v.qualified,
+    ...(v.deciding === undefined ? {} : { deciding: v.deciding }),
+  }));
+  return buildMeasurementDocument(run, plugins, { hostProfiles: profiles, verdicts: written });
+}
+
+export function exitCodeFor(verdicts: readonly QualifyVerdict[]): number {
+  if (verdicts.length === 0 || verdicts.some((v) => !v.measured)) return EXIT_CODE.couldNotMeasure;
+  return verdicts.every((v) => v.qualified) ? EXIT_CODE.allQualified : EXIT_CODE.someNotQualified;
+}
+
+/** Plain words: plugin, verdict, the reason that decided it, the host it was judged for. */
+export function textTable(verdicts: readonly QualifyVerdict[]): string {
+  const w = Math.max("plugin".length, ...verdicts.map((v) => v.uri.length));
+  const r = Math.max("reason".length, ...verdicts.map((v) => (v.deciding ?? "-").length));
+  const head = `${"plugin".padEnd(w)}  ${"verdict".padEnd(11)}  ${"reason".padEnd(r)}  host`;
+  const rows = verdicts.map((v) => `${v.uri.padEnd(w)}  ${v.rating.padEnd(11)}  ${(v.deciding ?? "-").padEnd(r)}  ${v.host}`);
+  return [head, ...rows, ""].join("\n");
+}

package/src/qualify-declarations.ts

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * EVERY NUMBER plugin-qualify uses, declared once. The CLI's defaults and `--help`, the rating, and the Python tools (through the generated
+ * `tools/_declarations.py`) all READ these; a consumer holding its own copy is what the package's
+ * perturbation test catches (R-094).
+ */
+
+/**
+ * The reference rate cost is quoted at: the rig's rate, 96 kHz.
+ */
+export const COST_REFERENCE_RATE = 96000;
+
+/**
+ * The reference quantum in frames: the rig's buffer, and the block `benchmark.py` runs.
+ */
+export const QUANTUM_FRAMES = 1024;
+
+/** The rate the offline capture window is sized at; other rates scale from it. */
+export const MEASURE_BASE_RATE = 48000;
+
+/**
+ * The lowest rate the console runs a show at. A reading below it is informational for the scaling
+ * class: kept in `perRate` and served at its own rate, but never alone enough to flag a plugin
+ * `nonconforming` (`lv2-measurement-interchange.md` §1a).
+ */
+export const OPERATIONAL_RATE_FLOOR = 48000;
+
+/** The rates a run measures when `--rates` is not given — recorded in `run.rates`. */
+export const QUALIFY_RATES: readonly number[] = [44100, MEASURE_BASE_RATE, COST_REFERENCE_RATE, 192000];
+
+/** The quanta (frames) a run rates cost at when `--quanta` is not given. */
+export const QUALIFY_QUANTA: readonly number[] = [128, 256, 512, QUANTUM_FRAMES];
+
+/** Seconds one plugin's offline pass may take before its worker is killed and it reads as a timeout. */
+export const PLUGIN_TIMEOUT_S = 15;
+
+/** Seconds the offline worker may take to start (lilv world load on a large LV2_PATH). */
+export const BOOT_TIMEOUT_S = 120;
+
+/** Seconds one plugin's cost pass may take (a sustained tone runs longer than an impulse). */
+export const COST_TIMEOUT_S = 60;
+
+/**
+ * The ONE setting that locates the CLAP scanner (spec §7): the environment variable that names
+ * the `omx-clap-scan` binary, and what is run when it is unset (looked up on `PATH`).
+ */
+export const CLAP_SCAN_TOOL_ENV = "OMX_CLAP_SCAN";
+export const CLAP_SCAN_TOOL_DEFAULT = "omx-clap-scan";
+
+/** Seconds one run of the CLAP scanner may take over everything it was pointed at. */
+export const CLAP_SCAN_TIMEOUT_S = 300;
+
+/**
+ * The CLAP prober (`native/clap-qualify.c`) and the interposer it runs under (`native/rt-interpose.c`):
+ * each located by one environment variable, else the package's own build in `native/build/`.
+ */
+export const CLAP_QUALIFY_TOOL_ENV = "OMX_CLAP_QUALIFY";
+export const RT_INTERPOSE_ENV = "OMX_RT_INTERPOSE";
+
+/** The CLAP sweep: blocks of `CLAP_SWEEP_FRAMES` frames per rate, every parameter moved through events. */
+export const CLAP_SWEEP_BLOCKS = 512;
+export const CLAP_SWEEP_FRAMES = 512;
+
+/** Seconds one `.clap` may take to qualify at every rate before the prober is killed. */
+export const CLAP_QUALIFY_TIMEOUT_S = 120;
+
+
+
+
+// The rating's thresholds.
+
+/** Every threshold, so none is baked into the code. */
+export interface HostingPolicy {
+  /** Minimum instantiate/destroy lifecycles. The operator's §14.4 ruling: 1000. */
+  readonly cycleFloor: number;
+  /** Minimum continuous soak, seconds. Default 3 h — the operator's longest show. */
+  readonly soakSeconds: number;
+  /** Above this ratio a plugin is spiky: in-process a spike is the whole desk's xrun. */
+  readonly costTailRatioCeiling: number;
+  /** A soak rate whose settled output sits this far under the plugin's own best rate is
+   *  dead there. A ratio against the plugin itself, never an absolute floor. */
+  readonly soakDeadDropDb: number;
+  /** The host string the shipped figures were taken on, when the console knows its own. */
+  readonly hostProvenance?: string;
+}
+
+/**
+ * Defaults. The cycle floor is the operator's ruling of 2026-09-05 (§14.4, option c) and the
+ * soak is §3's default show length. The per-instance cost ceiling is the HOST's budget and
+ * lives in {@link HOST_BUDGETS} (plugin-qualify §3a), not here.
+ */
+export const DEFAULT_HOSTING_POLICY: HostingPolicy = {
+  cycleFloor: 1000,
+  soakSeconds: 3 * 60 * 60,
+  costTailRatioCeiling: 4,
+  soakDeadDropDb: 40,
+};
+
+/** What a host spends on one plugin instance (`2026-09-25-plugin-qualify.md` §3a) — the
+ *  interchange's shape, since a document carries each profile's budget. */
+import type { HostBudget } from "./measurement/format.js";
+export type { HostBudget };
+
+/**
+ * Each shipped host profile's budget, by profile id. `openmixer-console` is §14.2's 5 % per
+ * instance at the rig's rate and buffer. `mod-host` runs a whole pedalboard on one JACK thread,
+ * so it gets the same per-instance share, at 48 kHz / 128 frames. `jalv` gives each plugin its own
+ * process and client, so a quarter core per instance, at 48 kHz / 256 frames. The last two are
+ * declared defaults, not a measurement of anyone's board — a project brings its own profile file.
+ */
+export const HOST_BUDGETS = {
+  "openmixer-console": { coreFractionCeiling: 0.05, rate: COST_REFERENCE_RATE, quantum: QUANTUM_FRAMES },
+  jalv: { coreFractionCeiling: 0.25, rate: MEASURE_BASE_RATE, quantum: 256 },
+  "mod-host": { coreFractionCeiling: 0.05, rate: MEASURE_BASE_RATE, quantum: 128 },
+} as const satisfies Readonly<Record<string, HostBudget>>;
+