@openmixer/plugin-qualify 0.0.0-stage → 0.4.1

package/src/clap-qualify.ts

@@ -0,0 +1,387 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The CLAP arm of the one qualifier. `native/clap-qualify` loads a `.clap` under the interposer
+ * (`native/rt_interpose.so`), sweeps each plugin at every rate and prints what it MEASURED, one
+ * JSON line per plugin; this module runs it, reads those lines strictly, and turns each into the
+ * RT-safety verdict document: the binary's SHA-256, the console it was judged for, and the verdict
+ * of the `rtSafety` dimension from the same rules `classifyPluginHosting` folds
+ * ({@link rtSafetyReasons}, {@link clapRtReasons}) — never a second judge. A line that cannot be
+ * 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_ENV,
+  CLAP_SWEEP_BLOCKS,
+  CLAP_SWEEP_FRAMES,
+  RT_INTERPOSE_ENV,
+} from "./qualify-declarations.js";
+import {
+  HOSTING_CODE,
+  clapRtReasons,
+  contributedHostingRating,
+  rtSafetyReasons,
+  type HostingReason,
+  type PluginClapMeasurement,
+  type PluginRtSafetyMeasurement,
+} from "./hosting-suitability.js";
+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 { clapQualifyToolPath, rtInterposePath } from "./tool-paths.js";
+
+export class ClapQualifyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClapQualifyError";
+  }
+}
+
+// --- the prober's line ---------------------------------------------------------------------------
+
+/** What the interposer counted; `interposer: false` is a run without it, which counts nothing. */
+export interface ClapRtSafetyReading extends PluginRtSafetyMeasurement {
+  /** The first events the interposer recorded inside `process()`, by libc call (`malloc`, `pthread_mutex_lock`, ...). */
+  readonly events?: readonly string[];
+}
+
+/** The CLAP facts as the prober printed them: the measurement, and whether any output was not finite. */
+export interface ClapProbedFacts extends PluginClapMeasurement {
+  readonly nonFinite: boolean;
+}
+
+/** One plugin's line from `clap-qualify`. */
+export interface ClapQualifyLine {
+  readonly uri: string;
+  readonly id: string;
+  readonly binary: { readonly path: string; readonly sha256: string };
+  /** The host extensions the prober offered; the verdict's headless pass holds only for these. */
+  readonly hostExtensions: readonly string[];
+  readonly clap: ClapProbedFacts;
+  readonly rtSafety: ClapRtSafetyReading;
+}
+
+const SHA256 = /^[0-9a-f]{64}$/;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return Object.prototype.toString.call(v) === "[object Object]";
+}
+
+function bad(what: string): never {
+  throw new ClapQualifyError(`clap-qualify printed a line that is not its document: ${what}`);
+}
+
+function str(o: Record<string, unknown>, key: string, where: string): string {
+  const v = o[key];
+  return typeof v === "string" ? v : bad(`${where} has no string ${key}`);
+}
+
+function count(o: Record<string, unknown>, key: string, where: string): number {
+  const v = o[key];
+  return typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : bad(`${where} has no count ${key}`);
+}
+
+function bool(o: Record<string, unknown>, key: string, where: string): boolean {
+  const v = o[key];
+  return typeof v === "boolean" ? v : bad(`${where} has no boolean ${key}`);
+}
+
+function strings(o: Record<string, unknown>, key: string, where: string): string[] {
+  const v = o[key];
+  if (!Array.isArray(v)) return bad(`${where} has no list ${key}`);
+  return v.map((s) => (typeof s === "string" ? s : bad(`${where} ${key} holds something that is not a string`)));
+}
+
+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 }> = {};
+  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}`) };
+  }
+  return {
+    mainInputChannels: count(v, "mainInputChannels", "clap"),
+    mainOutputChannels: count(v, "mainOutputChannels", "clap"),
+    sidechainInputs: count(v, "sidechainInputs", "clap"),
+    features: strings(v, "features", "clap"),
+    headlessOk: bool(v, "headlessOk", "clap"),
+    noteInputs: count(v, "noteInputs", "clap"),
+    latency,
+    threadViolations: count(v, "threadViolations", "clap"),
+    processErrors: count(v, "processErrors", "clap"),
+    processCalls: count(v, "processCalls", "clap"),
+    nonFinite: bool(v, "nonFinite", "clap"),
+  };
+}
+
+function readRtSafety(v: unknown): ClapRtSafetyReading {
+  if (!isRecord(v)) return bad("no rtSafety");
+  if (!bool(v, "interposer", "rtSafety")) return { interposer: false };
+  return {
+    interposer: true,
+    swept: bool(v, "swept", "rtSafety"),
+    sweepApplicable: bool(v, "sweepApplicable", "rtSafety"),
+    blocks: count(v, "blocks", "rtSafety"),
+    blockFrames: count(v, "blockFrames", "rtSafety"),
+    allocationsInRun: count(v, "allocationsInRun", "rtSafety"),
+    locksInRun: count(v, "locksInRun", "rtSafety"),
+    syscallsInRun: count(v, "syscallsInRun", "rtSafety"),
+    events: strings(v, "events", "rtSafety"),
+  };
+}
+
+/** One line of the prober's stdout, or a {@link ClapQualifyError} saying how it differs. */
+export function parseClapQualifyLine(text: string): ClapQualifyLine {
+  let v: unknown;
+  try {
+    v = JSON.parse(text);
+  } catch {
+    return bad("not JSON");
+  }
+  if (!isRecord(v)) return bad("not an object");
+  if (v["format"] !== "clap") return bad(`format is ${JSON.stringify(v["format"])}`);
+  const id = str(v, "id", "the line");
+  const uri = str(v, "uri", "the line");
+  if (uri !== `urn:clap:${id}`) return bad(`uri ${uri} is not urn:clap:${id}`);
+  const binary = v["binary"];
+  if (!isRecord(binary)) return bad("no binary");
+  const sha256 = str(binary, "sha256", "binary");
+  if (!SHA256.test(sha256)) return bad(`binary sha256 ${sha256} is not 64 lowercase hex digits`);
+  return {
+    uri,
+    id,
+    binary: { path: str(binary, "path", "binary"), sha256 },
+    hostExtensions: strings(v, "hostExtensions", "the line"),
+    clap: readClap(v["clap"]),
+    rtSafety: readRtSafety(v["rtSafety"]),
+  };
+}
+
+/** Every non-empty line of the prober's stdout. */
+export function parseClapQualifyOutput(stdout: string): ClapQualifyLine[] {
+  return stdout.split("\n").filter((l) => l.trim() !== "").map(parseClapQualifyLine);
+}
+
+// --- the verdict document ------------------------------------------------------------------------
+
+/** The document's schema name; a reader refuses any other. */
+export const RT_SAFETY_DOCUMENT_SCHEMA = "plugin-qualify.rt-safety/1";
+
+/**
+ * The RT-safety verdict of one plugin binary for one console: keyed by the binary's SHA-256 and
+ * the host profile id, so a verdict never outlives the bytes it was measured on. `measured` is what
+ * the prober printed, raw; `verdict` is the `rtSafety` dimension's worst-wins fold of it.
+ */
+export interface RtSafetyDocument {
+  readonly schema: typeof RT_SAFETY_DOCUMENT_SCHEMA;
+  readonly plugin: {
+    readonly uri: string;
+    readonly format: "clap";
+    readonly binary: { readonly path: string; readonly sha256: string };
+  };
+  /** The host profile the verdict is for. */
+  readonly console: string;
+  readonly verdict: {
+    readonly rating: SuitabilityRating;
+    /** `rating === "suitable"` — in-process only with it. */
+    readonly rtSafe: boolean;
+    /** The ONE reason that decided it; absent when suitable. */
+    readonly deciding?: HostingReason;
+    readonly reasons: readonly HostingReason[];
+  };
+  readonly measured: {
+    readonly hostExtensions: readonly string[];
+    readonly clap: ClapProbedFacts;
+    readonly rtSafety: ClapRtSafetyReading;
+  };
+}
+
+/**
+ * The verdict document for one prober line under one host profile. The interposer's counts and the
+ * two violations only a CLAP commits decide it. The line is judged against the profile's own CLAP
+ * host extensions: a line from a prober that offered others is not that host's measurement, and a
+ * host with no CLAP path has none; both read `unknown`.
+ */
+export function rtSafetyDocument(line: ClapQualifyLine, profile: HostProfile = OPENMIXER_CONSOLE_PROFILE): RtSafetyDocument {
+  const offered = profile.clapExtensions;
+  const offeredAsProfile =
+    offered !== null && line.hostExtensions.length === offered.length && offered.every((e) => line.hostExtensions.includes(e));
+  const reasons: HostingReason[] =
+    offered === null
+      ? [{ dimension: "rtSafety", kind: "objective", rating: "unknown", code: HOSTING_CODE.clapFormatNotHosted, params: {} }]
+      : offeredAsProfile
+        ? [...rtSafetyReasons(line.rtSafety), ...clapRtReasons(line.clap)]
+        : [
+            {
+              dimension: "rtSafety",
+              kind: "objective",
+              rating: "unknown",
+              code: HOSTING_CODE.clapExtensionsNotCovered,
+              params: { extensions: line.hostExtensions.join(" ") },
+            },
+          ];
+  const rating = worstRating(reasons.map(contributedHostingRating));
+  const deciding = [...reasons]
+    .sort((a, b) => RATING_SEVERITY[contributedHostingRating(b)] - RATING_SEVERITY[contributedHostingRating(a)])
+    .find((r) => contributedHostingRating(r) === rating);
+  return {
+    schema: RT_SAFETY_DOCUMENT_SCHEMA,
+    plugin: { uri: line.uri, format: "clap", binary: line.binary },
+    console: profile.id,
+    verdict: { rating, rtSafe: rating === "suitable", ...(rating === "suitable" || deciding === undefined ? {} : { deciding }), reasons },
+    measured: { hostExtensions: line.hostExtensions, clap: line.clap, rtSafety: line.rtSafety },
+  };
+}
+
+/** The document as the CLI's verdict row. */
+export function rtSafetyVerdict(doc: RtSafetyDocument): QualifyVerdict {
+  return {
+    uri: doc.plugin.uri,
+    host: doc.console,
+    measured: true,
+    rating: doc.verdict.rating,
+    qualified: doc.verdict.rtSafe,
+    ...(doc.verdict.deciding === undefined ? {} : { deciding: doc.verdict.deciding.code }),
+  };
+}
+
+/** Where a document is written in `--out`: one file per binary and console. */
+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;
+}
+
+function setting(env: Readonly<Record<string, string | undefined>>, name: string, fallback: string): string {
+  const v = env[name];
+  return v === undefined || v === "" ? fallback : v;
+}
+
+/** The prober and the interposer this run uses: each its setting, else the package's own build. */
+export function clapQualifyTools(env: Readonly<Record<string, string | undefined>>): { tool: string; interposer: string } {
+  return { tool: setting(env, CLAP_QUALIFY_TOOL_ENV, clapQualifyToolPath()), interposer: setting(env, RT_INTERPOSE_ENV, rtInterposePath()) };
+}
+
+/**
+ * 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 exists = options.exists ?? existsSync;
+  const { tool, interposer } = clapQualifyTools(env);
+  for (const [what, path, name] of [["prober", tool, CLAP_QUALIFY_TOOL_ENV], ["interposer", interposer, RT_INTERPOSE_ENV]] as const) {
+    if (!exists(path)) throw new ClapQualifyError(`no CLAP ${what} at ${path}: build it with make -C native, or set ${name}`);
+  }
+  const args = [
+    "--rates",
+    options.rates.join(","),
+    "--block",
+    String(CLAP_SWEEP_FRAMES),
+    "--blocks",
+    String(CLAP_SWEEP_BLOCKS),
+    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 }[];
+}
+
+/**
+ * Qualify every CLAP target, one prober run per target (a crash takes only that plugin), and judge
+ * each line under every host profile. 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;
+    let lines: ClapQualifyLine[];
+    try {
+      if (target.binaryPath === undefined) throw new ClapQualifyError(`${target.uri}: no .clap to load; name the file or a directory holding it`);
+      lines = qualifyClap(target.binaryPath, id, options);
+    } 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 line of lines) {
+      for (const profile of profiles) {
+        const doc = rtSafetyDocument(line, profile);
+        documents.push(doc);
+        verdicts.push(rtSafetyVerdict(doc));
+      }
+    }
+  }
+  return { documents, verdicts, failures };
+}

package/src/host-profiles.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * HOST PROFILES — the host a verdict is judged against, declared. The measurements are profile-free; `classifyPluginHosting` reads one of these to say
+ * whether THAT host can run the plugin. A profile names only what differs between hosts; every
+ * other rule is the one classifier's.
+ */
+import { HOST_BUDGETS } from "./qualify-declarations.js";
+
+// The profile's shape and its reader belong to the interchange (a document carries its
+// profiles, §3b), whose directory imports nothing from outside itself; they are re-exported here.
+export {
+  HOST_ISOLATIONS,
+  HOST_LATENCY_HANDLING,
+  type HostIsolation,
+  type HostLatencyHandling,
+} from "./measurement/vocabulary.js";
+export { readHostProfile, type HostProfile, type HostProfileRead } from "./measurement/format.js";
+import type { HostProfile } from "./measurement/format.js";
+
+/**
+ * The LV2 features the in-process stage provides — the ONE list (the console's host-backend contract).
+ * The verdict judges `required ⊆ provided` against it (as the `openmixer-console` profile), and
+ * the console hands the same array to the in-process LV2 table at `omx_host_backend_configure`,
+ * which builds one provider per URI and refuses a URI it cannot provide; there is no C copy (the
+ * console's native test reads this export).
+ */
+export const OMX_INPROCESS_FEATURES: readonly string[] = [
+  "http://lv2plug.in/ns/ext/urid#map",
+  "http://lv2plug.in/ns/ext/urid#unmap",
+  "http://lv2plug.in/ns/ext/options#options",
+  "http://lv2plug.in/ns/ext/buf-size#boundedBlockLength",
+  "http://lv2plug.in/ns/ext/worker#schedule",
+  "http://lv2plug.in/ns/ext/state#loadDefaultState",
+  "http://lv2plug.in/ns/ext/log#log",
+];
+
+/**
+ * The CLAP host object's extensions — what the console's control-thread host provides to every
+ * instance it hosts (CLAP hosting spec §5), and ALL the qualifier offers, so a plugin that needs
+ * more fails `init` headless in qualification and reads `hosting.clap.headless-failed` rather
+ * than on the desk. The list's home is the CLAP library — libomx-clap-core's own
+ * `clap_host_extensions.h`, what its host object offers — and this is its mirror, held equal to the
+ * header at the pinned omx-clap-host (by the console's conformance test), so the verdict never
+ * promises more or less than the host provides. Nothing else: no `gui`, no `timer-support`, no
+ * `posix-fd-support`, no `thread-pool`.
+ */
+export const OMX_CLAP_HOST_EXTENSIONS: readonly string[] = [
+  "clap.log",
+  "clap.thread-check",
+  "clap.latency",
+  "clap.params",
+  "clap.audio-ports",
+  "clap.state",
+];
+
+/** The LV2 extension namespace the jalv and mod-host lists are spelled in. */
+const LV2_EXT = "http://lv2plug.in/ns/ext/";
+const BUF_SIZE_ALL = ["powerOf2BlockLength", "fixedBlockLength", "boundedBlockLength"].map((f) => `${LV2_EXT}buf-size#${f}`);
+
+/**
+ * jalv 1.6.8 `src/jalv.c` 123–127 + 1316–1325: the list passed to `lilv_plugin_instantiate`
+ * (the zynthian fork, 1.6.9, `src/jalv.c` 1371–1380, passes the identical list).
+ */
+export const JALV_LV2_FEATURES: readonly string[] = [
+  ...["urid#map", "urid#unmap", "worker#schedule", "log#log", "options#options", "state#loadDefaultState"].map((f) => LV2_EXT + f),
+  ...BUF_SIZE_ALL,
+];
+
+/**
+ * mod-host f14a230 `src/effects.c` 254–275 + 2980–2995, without the `__MOD_DEVICES__`-only HMI
+ * feature: every feature `effects_add` hands a plugin, in its enum order.
+ */
+export const MOD_HOST_LV2_FEATURES: readonly string[] = [
+  ...["uri-map", "urid#map", "urid#unmap", "options#options"].map((f) => LV2_EXT + f),
+  "http://moddevices.com/ns/ext/license#feature",
+  ...BUF_SIZE_ALL,
+  ...["log#log", "state#freePath", "state#makePath"].map((f) => LV2_EXT + f),
+  "http://kx.studio/ns/lv2ext/control-input-port-change-request",
+  `${LV2_EXT}worker#schedule`,
+];
+
+/** The console's RT thread — exactly the verdict before profiles existed, and the default. */
+export const OPENMIXER_CONSOLE_PROFILE: HostProfile = {
+  id: "openmixer-console",
+  lv2Features: OMX_INPROCESS_FEATURES,
+  clapExtensions: OMX_CLAP_HOST_EXTENSIONS,
+  instruments: false,
+  cost: HOST_BUDGETS["openmixer-console"],
+  latency: "compensated",
+  isolation: "in-process",
+};
+
+/** zynthian's host: one jalv process per plugin, instruments fed, latency published to JACK. */
+export const JALV_PROFILE: HostProfile = {
+  id: "jalv",
+  lv2Features: JALV_LV2_FEATURES,
+  clapExtensions: null,
+  instruments: true,
+  cost: HOST_BUDGETS.jalv,
+  latency: "uncompensated",
+  isolation: "per-process",
+};
+
+/** MOD's host: every plugin of a pedalboard in one shared mod-host process. */
+export const MOD_HOST_PROFILE: HostProfile = {
+  id: "mod-host",
+  lv2Features: MOD_HOST_LV2_FEATURES,
+  clapExtensions: null,
+  instruments: true,
+  cost: HOST_BUDGETS["mod-host"],
+  latency: "uncompensated",
+  isolation: "shared-process",
+};
+
+/** Every profile the tool ships, by id. */
+export const HOST_PROFILES: readonly HostProfile[] = [OPENMIXER_CONSOLE_PROFILE, JALV_PROFILE, MOD_HOST_PROFILE];
+
+/** A shipped profile by id, or `undefined`. */
+export function shippedHostProfile(id: string): HostProfile | undefined {
+  return HOST_PROFILES.find((p) => p.id === id);
+}

package/src/hosting-codes.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The hosting verdict's message codes (2026-09-04-lv2-hosting-path.md). Codes, never prose: the
+ * surface renders the operator's locale.
+ *
+ * A UNION list file (2026-09-15-no-stored-derivations.md §9): `.gitattributes` marks it
+ * `merge=union`, so two lanes that each add a code merge with both kept. Only the table lives
+ * here, one `key: 'code',` per line, with keys and codes unique; the registry-hotspots gate
+ * refuses anything else.
+ */
+export const HOSTING_CODE = {
+  stabilitySoaked: 'hosting.stability.soaked',
+  stabilityCrashedAttributed: 'hosting.stability.crashed-attributed-plugin',
+  stabilityCrashedLive: 'hosting.stability.crashed-live-on-this-rig',
+  stabilityBelowFloor: 'hosting.stability.cycles-below-floor',
+  stabilityUnsoaked: 'hosting.stability.unsoaked',
+  stabilityUnmeasured: 'hosting.stability.unmeasured',
+  stabilityCrashUnattributed: 'hosting.stability.crash-unattributed',
+  stabilitySpawnsThreads: 'hosting.stability.spawns-threads',
+  stabilityLinksGuiToolkit: 'hosting.stability.links-gui-toolkit',
+  rtSafetyClean: 'hosting.rt-safety.clean-under-sweep',
+  rtSafetyViolations: 'hosting.rt-safety.violations-in-run',
+  rtSafetyUnmeasured: 'hosting.rt-safety.unmeasured',
+  rtSafetyNotReproducible: 'hosting.rt-safety.not-reproducible',
+  featuresProvided: 'hosting.features.all-provided',
+  featuresMissing: 'hosting.features.required-not-provided',
+  featuresDisqualifying: 'hosting.features.host-not-provided',
+  featuresCv: 'hosting.features.cv-ports',
+  featuresMidiIn: 'hosting.features.midi-in-fed-empty',
+  featuresUnscanned: 'hosting.features.scan-predates-field',
+  costWithinCeiling: 'hosting.cost.within-ceiling',
+  costAboveCeiling: 'hosting.cost.above-ceiling',
+  costSpiky: 'hosting.cost.spiky-tail',
+  costUnmeasured: 'hosting.cost.unmeasured-at-rate-and-quantum',
+  latencyResolved: 'hosting.latency.resolved',
+  latencyUnmeasured: 'hosting.latency.unmeasured',
+  latencyNonconforming: 'hosting.latency.nonconforming',
+  latencyParameterDependent: 'hosting.latency.parameter-dependent',
+  topologyMatched: 'hosting.topology.matched',
+  topologyNoAudioInput: 'hosting.topology.no-audio-input',
+  topologyNoAudioOutput: 'hosting.topology.no-audio-output',
+  topologyExtraInputs: 'hosting.topology.extra-inputs-fed-silence',
+  topologyInstrument: 'hosting.topology.instrument',
+  // The CLAP arm (2026-09-26-clap-hosting-path.md §3): the SAME dimensions fed from CLAP facts,
+  // minted here where the LV2 table has no code for the fact.
+  topologyWiderThanStrip: 'hosting.topology.wider-than-strip',
+  clapLatencyMismatch: 'hosting.clap.latency-mismatch',
+  clapNotAudioEffect: 'hosting.clap.not-audio-effect',
+  clapHeadlessFailed: 'hosting.clap.headless-failed',
+  clapNoteInput: 'hosting.clap.note-input',
+  clapThreadViolation: 'hosting.clap.thread-violation',
+  clapProcessError: 'hosting.clap.process-error',
+  clapUnqualified: 'hosting.clap.unqualified',
+  clapFormatNotHosted: 'hosting.clap.format-not-hosted',
+  clapExtensionsNotCovered: 'hosting.clap.extensions-not-covered',
+  outputNonFinite: 'hosting.output.non-finite',
+  overrideIsolated: 'hosting.override.curator-isolated',
+  hostProvenanceDiffers: 'hosting.provenance.host-differs',
+  sweepControlDidNotFire: 'hosting.provenance.sweep-control-did-not-fire',
+  // The five REALISED reasons. Everything above answers what a plugin EARNED; these answer
+  // what the console DID with that, and the difference between the two is the operator's
+  // whole question when a slot is not on the fast path.
+  disabled: 'hosting.disabled',
+  unjudged: 'hosting.unjudged',
+  noRealisation: 'hosting.no-realisation',
+  realisedInProcess: 'hosting.realised.in-process',
+  // A plugin LINKED into the engine (the static-link registry) runs in-process without a
+  // verdict: the library's oracles are its proof (`2026-09-26-clap-hosting-path.md` §7).
+  linked: 'hosting.linked',
+} as const;