@openmixer/plugin-qualify 0.11.0 → 0.13.0

package/fixtures/probe-output/success-msi.json

@@ -109,6 +109,17 @@
       "clap.params",
       "clap.state",
       "clap.thread-check",
+      "clap.note-ports",
+      "clap.note-name",
+      "clap.voice-info",
+      "clap.event-registry",
+      "clap.timer-support",
+      "clap.posix-fd-support",
+      "clap.thread-pool",
+      "clap.tail",
+      "clap.surround/4",
+      "clap.ambisonic/3",
+      "clap.audio-ports-config",
       "clap.preset-load/2",
       "clap.track-info/1",
       "clap.remote-controls/2"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/plugin-qualify",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Qualify audio plugins for real-time hosting: scan, offline latency and cost measurement, a mod-host hosting sweep, and a fail-closed rating.",
   "type": "module",
   "license": "GPL-3.0-or-later",
@@ -96,6 +96,6 @@
     "provenance": true
   },
   "dependencies": {
-    "@openmixer/omx-contract": "^2.16.0"
+    "@openmixer/omx-contract": "^3.0.0"
   }
 }

package/src/clap-qualify.ts

@@ -19,10 +19,13 @@ import {
   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,
@@ -33,7 +36,9 @@ import {
 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) {
@@ -61,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;
@@ -72,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.
@@ -114,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"),
@@ -175,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;
@@ -200,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"),
   };
 }
@@ -215,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
@@ -246,6 +416,7 @@ export interface RtSafetyDocument {
     readonly clap: ClapProbedFacts;
     readonly rtSafety: ClapRtSafetyReading;
     readonly noteSweep: ClapNoteSweepReading;
+    readonly cost?: ClapCostReading;
     readonly integrity: IntegrityMeasurement;
   };
 }
@@ -288,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,
     },
   };

package/src/host-profiles.ts

@@ -42,8 +42,7 @@ export const OMX_INPROCESS_FEATURES: readonly string[] = [
  * 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`.
+ * promises more or less than the host provides. Nothing else: no `gui`.
  */
 export const OMX_CLAP_HOST_EXTENSIONS: readonly string[] = [
   "clap.log",
@@ -52,6 +51,17 @@ export const OMX_CLAP_HOST_EXTENSIONS: readonly string[] = [
   "clap.params",
   "clap.audio-ports",
   "clap.state",
+  "clap.note-ports",
+  "clap.note-name",
+  "clap.voice-info",
+  "clap.event-registry",
+  "clap.timer-support",
+  "clap.posix-fd-support",
+  "clap.thread-pool",
+  "clap.tail",
+  "clap.surround/4",
+  "clap.ambisonic/3",
+  "clap.audio-ports-config",
 ];
 
 /**

package/src/hosting-codes.ts

@@ -1,82 +1,187 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
- * The hosting verdict's message codes. Codes, never prose: the
- * surface renders the operator's locale.
+ * The hosting verdict's message codes. Codes, never prose: the surface renders the operator's
+ * locale.
  *
- * A UNION list file: `.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.
+ * omx-clap-core declares every hosting code now (the contract split moved `data/hosting/*.json`
+ * there, byte for byte): one `HOSTING_<DIMENSION>_CODES` table per dimension, rendered into the
+ * TypeScript modules its package installs under `pkg-config --variable=tsdir omx-clap-core`
+ * (BUILDING.md) — `omx-clap-core-vocabulary.js` for the dimensions carried from omx-contract,
+ * `omx-clap-core-hosting.js` for `hosting.idle.*`, its own (both with a `.d.ts`). {@link
+ * HOSTING_CODE} is those tables flattened into one `key: code` map, loaded at import: a code
+ * neither module declares cannot be named here, and a dimension either adds arrives without an
+ * edit.
  */
-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',
-  stabilitySoakFailedAtRate: 'hosting.stability.soak-failed-at-rate',
-  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',
-  // The note sweep: an instrument played under the interposer, a count of its own.
-  rtSafetyNotesClean: 'hosting.rt-safety.clean-under-notes',
-  rtSafetyNotesViolations: 'hosting.rt-safety.violations-under-notes',
-  rtSafetyNotesUnmeasured: 'hosting.rt-safety.notes-unmeasured',
-  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',
-  costFieldsMissing: 'hosting.cost.fields-missing',
-  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: 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',
-  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',
-  integrityLayoutMismatch: 'hosting.integrity.layout-mismatch',
-  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.
-  linked: 'hosting.linked',
-} as const;
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The two TypeScript modules omx-clap-core's `tsdir` carries, each a `HOSTING_<DIMENSION>_CODES` source. */
+const CLAP_CORE_TS_MODULES = ["omx-clap-core-vocabulary.js", "omx-clap-core-hosting.js"] as const;
+
+/** This package's own root, resolved from this module so it follows wherever it is installed. */
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/** `native/fetch-deps.sh`'s own checkout of omx-clap-core, for a build with no omx-clap-core-devel installed. */
+const DEPS_TS_DIR = join(PACKAGE_ROOT, "native/deps/omx-clap-core/ts");
+
+/** Where `make install` of omx-clap-host puts them (BUILDING.md), for a run with no `pkg-config` binary at all. */
+const DEFAULT_SYSTEM_TS_DIR = "/usr/share/omx-clap-core/ts";
+
+/** `pkg-config --variable=tsdir omx-clap-core`, or `undefined` where pkg-config or the package is absent. */
+function pkgConfigTsDir(env: Readonly<Record<string, string | undefined>>): string | undefined {
+  try {
+    const out = execFileSync(env.PKG_CONFIG ?? "pkg-config", ["--variable=tsdir", "omx-clap-core"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out === "" ? undefined : out;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where omx-clap-core's TypeScript modules are looked for, in order: `OMX_CLAP_CORE_TSDIR` when
+ * set (and only that), else `pkg-config --variable=tsdir omx-clap-core`, else the checkout
+ * `native/fetch-deps.sh` stages, else the path `make install` of omx-clap-host uses by default —
+ * a packaged plugin-qualify's runtime has no `pkg-config` binary to ask.
+ */
+export function clapCoreTsDirCandidates(env: Readonly<Record<string, string | undefined>> = process.env): readonly string[] {
+  const set = env.OMX_CLAP_CORE_TSDIR;
+  if (set !== undefined && set !== "") return [set];
+  const fromPkgConfig = pkgConfigTsDir(env);
+  return [...(fromPkgConfig === undefined ? [] : [fromPkgConfig]), DEPS_TS_DIR, DEFAULT_SYSTEM_TS_DIR];
+}
+
+function locateClapCoreTsDir(): string {
+  const candidates = clapCoreTsDirCandidates();
+  const dir = candidates.find((d) => CLAP_CORE_TS_MODULES.every((m) => existsSync(join(d, m))));
+  if (dir === undefined) {
+    throw new Error(
+      `omx-clap-core's TypeScript modules (${CLAP_CORE_TS_MODULES.join(", ")}) were not found in any of: ` +
+        `${candidates.join(", ")}. Install omx-clap-core-devel (pkg-config omx-clap-core), set ` +
+        "OMX_CLAP_CORE_TSDIR to its tsdir, or run native/fetch-deps.sh.",
+    );
+  }
+  return dir;
+}
+
+/** True for an export name that is one of omx-clap-core's hosting tables. */
+export function isHostingTableName(name: string): boolean {
+  return /^HOSTING_[A-Z0-9_]+_CODES$/.test(name);
+}
+
+type HostingEntries = Record<string, { readonly code: string }>;
+
+async function loadHostingTables(): Promise<Record<string, HostingEntries>> {
+  const dir = locateClapCoreTsDir();
+  const tables: Record<string, HostingEntries> = {};
+  for (const name of CLAP_CORE_TS_MODULES) {
+    // The modules are self-contained ES modules in a directory with no package.json: Node 18 reads such a .js as
+    // CommonJS and refuses `export`, so the source is imported as a data: module, which is a module on every Node.
+    const source = readFileSync(join(dir, name), "utf8");
+    const mod: Record<string, unknown> = await import(`data:text/javascript;base64,${Buffer.from(source).toString("base64")}`);
+    for (const [exportName, table] of Object.entries(mod)) {
+      if (isHostingTableName(exportName)) tables[exportName] = table as HostingEntries;
+    }
+  }
+  return tables;
+}
+
+function flatten(tables: Record<string, HostingEntries>): HostingCodeTable {
+  const table: Record<string, string> = {};
+  for (const [name, entries] of Object.entries(tables)) {
+    for (const [key, entry] of Object.entries(entries)) {
+      if (key in table) throw new Error(`omx-clap-core declares the hosting key ${key} twice (${name})`);
+      table[key] = entry.code;
+    }
+  }
+  return Object.freeze(table) as unknown as HostingCodeTable;
+}
+
+/**
+ * omx-clap-core's hosting codes, by key, across its two TypeScript modules — hand-kept here
+ * (not derived from a static import: the source is a runtime-resolved install directory, not an
+ * npm dependency) and held to the real modules by
+ * `src/contract-vocabulary-conformance.test.ts`, which turns red on any drift either way.
+ */
+export interface HostingCodeTable {
+  readonly clapExtensionsNotCovered: "hosting.clap.extensions-not-covered";
+  readonly clapFormatNotHosted: "hosting.clap.format-not-hosted";
+  readonly clapHeadlessFailed: "hosting.clap.headless-failed";
+  readonly clapLatencyMismatch: "hosting.clap.latency-mismatch";
+  readonly clapNoteInput: "hosting.clap.note-input";
+  readonly clapProcessError: "hosting.clap.process-error";
+  readonly clapThreadViolation: "hosting.clap.thread-violation";
+  readonly clapUnqualified: "hosting.clap.unqualified";
+  readonly costAboveCeiling: "hosting.cost.above-ceiling";
+  readonly costFieldsMissing: "hosting.cost.fields-missing";
+  readonly costSpiky: "hosting.cost.spiky-tail";
+  readonly costUnmeasured: "hosting.cost.unmeasured-at-rate-and-quantum";
+  readonly costWithinCeiling: "hosting.cost.within-ceiling";
+  readonly featuresAtomInUnfed: "hosting.features.atom-in-unfed";
+  readonly featuresDisqualifying: "hosting.features.host-not-provided";
+  readonly featuresMidiIn: "hosting.features.midi-in-fed-empty";
+  readonly featuresMissing: "hosting.features.missing";
+  readonly featuresPortsUnreadable: "hosting.features.ports-unreadable";
+  readonly featuresProvided: "hosting.features.all-provided";
+  readonly featuresUnscanned: "hosting.features.scan-predates-field";
+  readonly idleHoldRefused: "hosting.idle.hold-refused";
+  readonly latencyNonconforming: "hosting.latency.nonconforming";
+  readonly latencyParameterDependent: "hosting.latency.parameter-dependent";
+  readonly latencyResolved: "hosting.latency.resolved";
+  readonly latencyUnmeasured: "hosting.latency.unmeasured";
+  readonly outputNonFinite: "hosting.output.non-finite";
+  readonly overrideIsolated: "hosting.override.curator-isolated";
+  readonly patchBusy: "hosting.patch.busy";
+  readonly patchNotWritable: "hosting.patch.not-writable";
+  readonly patchTooLarge: "hosting.patch.too-large";
+  readonly presetNotFound: "hosting.preset.not-found";
+  readonly hostProvenanceDiffers: "hosting.provenance.host-differs";
+  readonly sweepControlDidNotFire: "hosting.provenance.sweep-control-did-not-fire";
+  readonly disabled: "hosting.disabled";
+  readonly linked: "hosting.linked";
+  readonly noRealisation: "hosting.no-realisation";
+  readonly realisedInProcess: "hosting.realised.in-process";
+  readonly unjudged: "hosting.unjudged";
+  readonly rtSafetyClean: "hosting.rt-safety.clean-under-sweep";
+  readonly rtSafetyNotReproducible: "hosting.rt-safety.not-reproducible";
+  readonly rtSafetyNotesClean: "hosting.rt-safety.clean-under-notes";
+  readonly rtSafetyNotesUnmeasured: "hosting.rt-safety.notes-unmeasured";
+  readonly rtSafetyNotesViolations: "hosting.rt-safety.violations-under-notes";
+  readonly rtSafetyUnmeasured: "hosting.rt-safety.unmeasured";
+  readonly rtSafetyViolations: "hosting.rt-safety.violations-in-run";
+  readonly stabilityBelowFloor: "hosting.stability.cycles-below-floor";
+  readonly stabilityCrashUnattributed: "hosting.stability.crash-unattributed";
+  readonly stabilityCrashedAttributed: "hosting.stability.crashed-attributed-plugin";
+  readonly stabilityCrashedLive: "hosting.stability.crashed-live-on-this-rig";
+  readonly stabilityLinksGuiToolkit: "hosting.stability.links-gui-toolkit";
+  readonly stabilitySoakFailedAtRate: "hosting.stability.soak-failed-at-rate";
+  readonly stabilitySoaked: "hosting.stability.soaked";
+  readonly stabilitySpawnsThreads: "hosting.stability.spawns-threads";
+  readonly stabilityUnmeasured: "hosting.stability.unmeasured";
+  readonly stabilityUnsoaked: "hosting.stability.unsoaked";
+  readonly stateNotACopy: "hosting.state.not-a-copy";
+  readonly statePathOnAudio: "hosting.state.path-on-audio";
+  readonly statePathOutside: "hosting.state.path-outside";
+  readonly statePathSymlink: "hosting.state.path-symlink";
+  readonly statePathTooLong: "hosting.state.path-too-long";
+  readonly statePathUnmakeable: "hosting.state.path-unmakeable";
+  readonly stateUnreadable: "hosting.state.unreadable";
+  readonly topologyAmbisonicConfig: "hosting.topology.ambisonic-config";
+  readonly topologyChannelMapUnknown: "hosting.topology.channel-map-unknown";
+  readonly topologyInstrument: "hosting.topology.instrument";
+  readonly topologyMatched: "hosting.topology.matched";
+  readonly topologyNoAudioInput: "hosting.topology.no-audio-input";
+  readonly topologyNoAudioOutput: "hosting.topology.no-audio-output";
+  readonly topologyPortTooWide: "hosting.topology.port-too-wide";
+  readonly topologyPortWithoutChannels: "hosting.topology.port-without-channels";
+  readonly topologyTooManyPorts: "hosting.topology.too-many-ports";
+  readonly topologyWiderThanStrip: "hosting.topology.wider-than-strip";
+  readonly workerNonconforming: "hosting.worker.nonconforming";
+}
+
+export const HOSTING_CODE: HostingCodeTable = flatten(await loadHostingTables());