@openmixer/plugin-qualify 0.13.0 → 0.14.1

package/src/hosting-codes.ts

@@ -4,184 +4,18 @@
  * The hosting verdict's message codes. Codes, never prose: the surface renders the operator's
  * locale.
  *
- * 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.
+ * omx-clap-core declares every hosting code: one `HOSTING_<DIMENSION>_CODES` table per dimension,
+ * in the TypeScript modules its package installs under `pkg-config --variable=tsdir omx-clap-core`
+ * (BUILDING.md). {@link HOSTING_CODE} is those tables flattened into one `key: code` map, written
+ * as plain data into `hosting-codes.generated.ts` by `tools/gen-hosting-codes.mjs` at build time:
+ * a code omx-clap-core does not declare cannot be named here, and this module reads no file and
+ * imports no `node:` module, so every public subpath that reaches it bundles for a browser.
+ * `src/contract-vocabulary-conformance.test.ts` holds the generated map to omx-clap-core's real
+ * modules, either way.
  */
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { HOSTING_CODE } from "./hosting-codes.generated.js";
 
-/** 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;
+export { HOSTING_CODE };
 
-/** 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());
+/** {@link HOSTING_CODE}'s type: each key's literal code. */
+export type HostingCodeTable = typeof HOSTING_CODE;

package/src/qualify-declarations.ts

@@ -147,6 +147,35 @@ export const LV2_HOSTING_LIFECYCLES = 30;
 export const LV2_HOSTING_REPEATS = 3;
 export const LV2_HOSTING_TIMEOUT_S = 240;
 
+/**
+ * The scanned descriptors (owner spec 6.6 and 6.9): both scanners write one file per plugin into the
+ * directory the key `descriptor_dir` names, `<id>@<version>-<binary sha256 first DESCRIPTOR_HASH_PREFIX>.json`.
+ * With no directory named it is `$XDG_STATE_HOME/<DESCRIPTOR_DIR_STATE_SUBDIR>`, else
+ * `~/.local/state/<DESCRIPTOR_DIR_STATE_SUBDIR>`; a system service's is `DESCRIPTOR_DIR_SYSTEM`.
+ */
+export const DESCRIPTOR_DIR_KEY = "descriptor_dir";
+export const DESCRIPTOR_DIR_STATE_SUBDIR = "omx/descriptors";
+export const DESCRIPTOR_DIR_SYSTEM = "/var/lib/omx/descriptors";
+export const DESCRIPTOR_HASH_PREFIX = 12;
+
+/**
+ * The one descriptor schema both scanners hold a file to: omx-contract's, named by `DESCRIPTOR_SCHEMA_ENV`
+ * when set (a test, or a checkout pointing at another contract), else the omx-contract package this one
+ * depends on, else `DESCRIPTOR_SCHEMA_INSTALLED`. A written descriptor requires `DESCRIPTOR_SCHEMA_FLOOR`.
+ */
+export const DESCRIPTOR_SCHEMA_ENV = "OMX_CONTRACT_SCHEMA";
+export const DESCRIPTOR_SCHEMA_INSTALLED = "/usr/share/omx-contract/omx-contract.schema.json";
+export const DESCRIPTOR_SCHEMA_FLOOR = ">= 3.0.0";
+
+/**
+ * Why a scanned descriptor is not written. A file the schema refuses is omx-contract's own
+ * `contract.file.invalid`; the others are the scanners' own.
+ */
+export const DESCRIPTOR_CODE_SCHEMA = "contract.file.invalid";
+export const DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing";
+export const DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed";
+export const DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable";
+
 
 
 

package/tools/_declarations.py

@@ -19,3 +19,14 @@ QUALIFY_QUANTA = (128, 256, 512, 1024)
 PLUGIN_TIMEOUT_S = 15
 BOOT_TIMEOUT_S = 120
 COST_TIMEOUT_S = 60
+DESCRIPTOR_DIR_KEY = "descriptor_dir"
+DESCRIPTOR_DIR_STATE_SUBDIR = "omx/descriptors"
+DESCRIPTOR_DIR_SYSTEM = "/var/lib/omx/descriptors"
+DESCRIPTOR_HASH_PREFIX = 12
+DESCRIPTOR_SCHEMA_ENV = "OMX_CONTRACT_SCHEMA"
+DESCRIPTOR_SCHEMA_INSTALLED = "/usr/share/omx-contract/omx-contract.schema.json"
+DESCRIPTOR_SCHEMA_FLOOR = ">= 3.0.0"
+DESCRIPTOR_CODE_SCHEMA = "contract.file.invalid"
+DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing"
+DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed"
+DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable"

package/tools/audit-overlap.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#
+# audit-overlap.sh — every number in docs/audit-qualify-vs-compat.md, from source, by one command each.
+#
+#   tools/audit-overlap.sh <omx-clap-core dir> <plugin-hostd dir>
+#   tools/audit-overlap.sh --self-test
+#
+# It prints one line per unit (a function, or a set of functions, in one repository):
+#   unit <id> <repo> <file>:<first>-<last> lines=<n>
+# one line per pair that does the same job in two places:
+#   pair <a> <b> shared=<s> a=<na> b=<nb> overlap=<s/min(na,nb) %> diff=<changed lines or "-"> strings=<both/a/b>
+# and one line per counted marker:
+#   count <id> <repo> <n>
+# A unit is found by its name (a C or TypeScript function runs to the first column-0 `}`, a Python def or class
+# to the next column-0 statement), never by a line number, so the numbers follow the code. The audited commits are
+# printed first (`tree <repo> <commit>`); the document states which ones it quotes.
+#
+# Similarity: both bodies are normalised (comments, blank lines and lone braces dropped, whitespace squeezed), then
+# `shared` is the number of normalised lines the two have in common (comm -12 over the sorted lines, duplicates
+# kept) and `diff` the number of lines `diff` adds or removes between them. Code in two languages shares no line;
+# for it the pair prints overlap=0 and diff=-. `strings` is shared/a/b of the distinct string literals (three or
+# more characters) each body spells: messages, field names and codes, which survive a change of brace style or of
+# language, so a port of the same code shows there when its lines do not.
+set -euo pipefail
+export LC_ALL=C
+Q="$(cd "$(dirname "$0")/.." && pwd)"
+
+die() { echo "audit-overlap: $*" >&2; exit 2; }
+
+# span <lang> <file> <name> — print "<first> <last>" of the named unit, nothing when there is none
+span() { # <lang> <file> <name>
+  awk -v lang="$1" -v name="$3" '
+    function starts(l) {
+      if (lang == "py") return l ~ ("^(def|class) " name "[(:]")
+      if (lang == "ts") return l ~ ("^(export )?(async )?function " name "[(<]")
+      return l ~ ("^[A-Za-z].*[ *]" name "\\(") && l !~ /;[ \t]*$/
+    }
+    !on && starts($0) { on = 1; first = NR; last = NR; next }
+    on && lang != "py" && /^}/ { last = NR; print first, last; exit }
+    on && lang == "py" && /^[^ \t#\n]/ { print first, last; exit }
+    on && lang == "py" && /[^ \t]/ { last = NR }
+    END { if (on && lang == "py") print first, last }
+  ' "$2"
+}
+
+WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
+declare -A ROOT LANG_OF
+
+# unit <id> <repo> <lang> <file> <name>... — one unit, the names' bodies concatenated
+unit() {
+  local id="$1" repo="$2" lang="$3" file="$4"; shift 4
+  local root="${ROOT[$repo]}" n total=0 where="" s
+  : > "$WORK/$id"
+  for n in "$@"; do
+    s="$(span "$lang" "$root/$file" "$n")"
+    [ -n "$s" ] || die "$repo $file: no $lang unit named $n"
+    local a b; read -r a b <<<"$s"
+    sed -n "${a},${b}p" "$root/$file" >> "$WORK/$id"
+    total=$((total + b - a + 1)); where="${where:+$where,}$a-$b"
+  done
+  LANG_OF[$id]="$lang"
+  echo "unit $id $repo $file:$where lines=$total"
+}
+
+# whole <id> <repo> <lang> <file> — a whole file as one unit
+whole() {
+  local id="$1" repo="$2" lang="$3" file="$4" n
+  cp "${ROOT[$repo]}/$file" "$WORK/$id"; n=$(wc -l < "$WORK/$id")
+  LANG_OF[$id]="$lang"
+  echo "unit $id $repo $file:1-$n lines=$n"
+}
+
+norm() { # <lang> < body
+  case "$1" in
+    py) sed -E 's/#.*$//' ;;
+    *)  sed -E 's#//.*$##; s#/\*.*\*/##g; /^[[:space:]]*\*( |\/|$)/d; /^[[:space:]]*\/\*/d' ;;
+  esac | sed -E 's/[[:space:]]+/ /g; s/^ //; s/ $//' | grep -vE '^[{}();, ]*$' || true
+}
+
+lits() { grep -oE "\"[^\"\\\\]{3,}\"|'[^'\\\\]{3,}'" | sed -E "s/^.(.*).$/\\1/"; } # quotes dropped: '' and "" alike
+
+pair() { # <a> <b>
+  local a="$1" b="$2" na nb s d m l
+  norm "${LANG_OF[$a]}" < "$WORK/$a" | sort > "$WORK/$a.n"
+  norm "${LANG_OF[$b]}" < "$WORK/$b" | sort > "$WORK/$b.n"
+  na=$(wc -l < "$WORK/$a.n"); nb=$(wc -l < "$WORK/$b.n")
+  s=$(comm -12 "$WORK/$a.n" "$WORK/$b.n" | wc -l)
+  m=$(( na < nb ? na : nb ))
+  if [ "${LANG_OF[$a]}" = "${LANG_OF[$b]}" ]; then
+    norm "${LANG_OF[$a]}" < "$WORK/$a" > "$WORK/$a.o"; norm "${LANG_OF[$b]}" < "$WORK/$b" > "$WORK/$b.o"
+    d=$(diff "$WORK/$a.o" "$WORK/$b.o" | grep -c '^[<>]' || true)
+  else d="-"; fi
+  # the string literals (messages, field names, codes) both spell: what survives a change of style or language
+  norm "${LANG_OF[$a]}" < "$WORK/$a" | lits | sort -u > "$WORK/$a.l" || true
+  norm "${LANG_OF[$b]}" < "$WORK/$b" | lits | sort -u > "$WORK/$b.l" || true
+  l="$(comm -12 "$WORK/$a.l" "$WORK/$b.l" | wc -l)/$(wc -l < "$WORK/$a.l")/$(wc -l < "$WORK/$b.l")"
+  echo "pair $a $b shared=$s a=$na b=$nb overlap=$(( m ? 100 * s / m : 0 ))% diff=$d strings=$l"
+}
+
+count() { # <id> <repo> <git grep args> -- <pathspec>...   (this audit's own two files are never counted)
+  local id="$1" repo="$2"; shift 2
+  local self=(":(exclude)tools/audit-overlap.sh" ":(exclude)docs/audit-qualify-vs-compat.md")
+  echo "count $id $repo $(git -C "${ROOT[$repo]}" grep -IE "$@" "${self[@]}" | wc -l)"
+}
+
+audit() {
+  local r
+  for r in qualify clap-core hostd; do echo "tree $r $(git -C "${ROOT[$r]}" rev-parse --short HEAD)"; done
+
+  # 1. plugin enumeration
+  unit q.clap-walk     qualify   c  native/clap-qualify.c is_clap walk scan
+  unit c.clap-walk     clap-core c  src/scan.c has_suffix walk main
+  unit q.clap-fork     qualify   c  native/clap-qualify.c scan_file
+  unit c.clap-fork     clap-core c  src/scan.c scan_file
+  unit q.clap-describe qualify   c  native/clap-qualify.c scan_file_entry scan_plugin scan_params scan_audio_ports
+  unit c.clap-describe clap-core c  src/scan.c put_file put_plugin put_descriptor put_params put_audio_ports
+  unit q.clap-path     qualify   ts src/clap-loader.ts clapSearchPath
+  unit c.clap-path     clap-core c  src/scan.c default_paths
+  unit q.lv2-manifest  qualify   ts src/lv2-loader.ts pluginsInManifest lv2BundlesOnPath
+  unit c.lv2-manifest  clap-core c  src/lv2_locate.c lv2_locate_manifest_names walk_dir lv2_locate
+  unit q.lv2-lilv      qualify   py tools/scan.py Scanner
+  unit c.lv2-lilv      clap-core py tests/lv2_parity.py lilv_facts
+  pair q.clap-walk c.clap-walk
+  pair q.clap-fork c.clap-fork
+  pair q.clap-describe c.clap-describe
+  pair q.clap-path c.clap-path
+  pair q.lv2-manifest c.lv2-manifest
+  pair q.lv2-lilv c.lv2-lilv
+  count q.calls-omx-clap-scan qualify -e 'omx-clap-scan' -- src
+  # clap-qualify's whole scan mode (--json), which writes the document omx-clap-scan writes, plus labels and pages
+  unit q.scan-mode     qualify   c  native/clap-qualify.c put_labels scan_params scan_remote_controls scan_audio_ports \
+                                    scan_plugin put_file_error scan_file_entry scan_file list_add is_clap walk scan
+  count c.scan-labels-pages clap-core -i -e 'remote_controls|enum_labels|"labels"' -- src/scan.c
+
+  # 2. deterministic input
+  count q.lcg-nr      qualify   -e '1664525u' -- native
+  count q.lcg-glibc   qualify   -e '1103515245u' -- native
+  count c.lcg-nr      clap-core -e '1664525u' -- tests src
+  unit q.noise-lv2    qualify   c  native/lv2-measure.c fill_input
+  unit c.signal       clap-core c  tests/jack_parity.c noise signal_at
+  pair q.noise-lv2 c.signal
+  unit q.notes        qualify   c  native/clap-qualify.c note_event note_midi note_key note_block note_dialect
+  unit q.notes-py     qualify   py tools/benchmark.py held_keys midi_sequence
+  unit c.notes        clap-core c  tests/jack_parity.c midi_events
+  pair q.notes c.notes
+  pair q.notes-py q.notes
+
+  # 3. isolated PipeWire, the feeder
+  count q.pipewire    qualify   -i -e 'pipewire|unshare' -- src native tools bin
+  count c.unshare     clap-core -e 'unshare' -- tests
+  unit c.pw-parity    clap-core py tests/lv2_parity.py start_pipewire
+  unit c.pw-coverage  clap-core py tests/clap_coverage.py start_pipewire
+  unit c.ns-parity    clap-core py tests/lv2_parity.py inside_run cmd_run
+  unit c.ns-coverage  clap-core py tests/clap_coverage.py inside_host cmd_host
+  unit c.clock        clap-core c  tests/jack_parity.c clock_process clock_state clock_wait clock_start clock_cycle clock_run
+  pair c.pw-parity c.pw-coverage
+  pair c.ns-parity c.ns-coverage
+
+  # 4. host launch, teardown, crash and hang
+  unit q.probe-runner qualify   ts src/probe-runner.ts runOne probeTarget
+  unit h.run-child    hostd     c  src/probe.c apply_limits kill_tree run_child child_end
+  unit q.bench-worker qualify   py tools/benchmark.py WorkerQueue _Worker
+  unit c.host-parity  clap-core py tests/lv2_parity.py Host run_plugin
+  unit c.host-coverage clap-core py tests/clap_coverage.py Host
+  pair c.host-parity c.host-coverage
+  pair q.bench-worker c.host-parity
+  count h.runs-clap-qualify hostd -e 'clap-qualify|clap_qualify' -- src
+  count h.runs-lv2-measure  hostd -e 'lv2_measure|lv2-measure' -- src
+
+  # 5. records, classification, vocabulary, reports
+  unit q.records      qualify   ts src/measurement/sweep-jsonl.ts measuredPluginsFromSweep parseJsonl
+  unit c.tsv-parity   clap-core py tests/lv2_parity.py read_tsv write_tsv
+  unit c.tsv-coverage clap-core py tests/clap_coverage.py read_tsv write_tsv append_tsv
+  pair c.tsv-parity c.tsv-coverage
+  unit q.classify     qualify   ts src/hosting-suitability.ts classifyPluginHosting
+  unit c.classify     clap-core py tests/lv2_parity.py _classify
+  pair q.classify c.classify
+  unit c.report       clap-core py tests/lv2_parity.py report_text
+  count q.contract-imports qualify -e "from \"@openmixer/omx-contract" -- src
+  count c.contract-macros  clap-core -e 'OMX_HOSTING_[A-Z_]+' -- src lv2
+  count q.handtyped-hosting qualify -e '"hosting\.[a-z-]+\.[a-z-]+"' -- 'src/*.ts' ':!src/*.test.ts'
+
+  # 6. cost and latency
+  unit q.pct-c        qualify   c  native/clap-qualify.c percentile_sorted
+  unit q.pct-py       qualify   py tools/benchmark.py percentile
+  unit q.cost-c       qualify   c  native/clap-qualify.c cost_rate
+  unit c.stage-bench  clap-core c  tests/stage_bench.c main
+  pair q.pct-c q.pct-py
+  pair q.cost-c c.stage-bench
+
+  # the probing programs plugin-hostd's probe runs as its children today, and what the move into its child deletes
+  whole q.prober-clap qualify c  native/clap-qualify.c
+  whole q.prober-lv2  qualify c  native/lv2-measure.c
+  whole q.benchmark   qualify py tools/benchmark.py
+
+  # 7. mod-host in plugin-qualify: code that runs it, and words that name it
+  count q.modhost-spawn qualify -e "spawn[A-Za-z]*\\(['\"]mod-host|execvp?\\(\"mod-host" -- src native tools bin
+  count q.modhost-words qualify -i -e 'mod-host' -- .
+  count c.modhost-words clap-core -i -e 'mod-host' -- tests
+}
+
+self_test() {
+  T="$(mktemp -d)"; local t="$T"; trap 'rm -rf "$T" "$WORK"' EXIT
+  for r in a b c; do mkdir -p "$t/$r"; git -C "$t/$r" init -q; done
+  cat > "$t/a/x.c" <<'EOF'
+static int one(int v)
+{
+  /* a comment */
+  return v + !"same"; /* "comment" */
+}
+static int two(int v) {
+  return v * 2;
+}
+EOF
+  cat > "$t/b/y.py" <<'EOF'
+def one(v):
+    # a comment
+    return v + len("same")  # "comment"
+
+X = 1
+EOF
+  cp "$t/a/x.c" "$t/c/z.c"; sed -i 's/v \* 2/v * 3/' "$t/c/z.c"
+  for r in a b c; do git -C "$t/$r" add -A; git -C "$t/$r" -c user.name=t -c user.email=t@t commit -qm t; done
+  ROOT[qualify]="$t/a"; ROOT[clap-core]="$t/b"; ROOT[hostd]="$t/c"
+  local out fail=0
+  expect() { grep -qxF -- "$1" <<<"$out" || { echo "self-test: missing: $1" >&2; fail=1; }; }
+  out="$(unit u1 qualify c x.c one; unit u2 qualify c x.c two; unit p1 clap-core py y.py one
+         unit h1 hostd c z.c one two; unit h2 qualify c x.c one two
+         pair h2 h1; pair u1 p1; count n qualify -e 'return' -- .)"
+  expect "unit u1 qualify x.c:1-5 lines=5"
+  expect "unit u2 qualify x.c:6-8 lines=3"
+  expect "unit p1 clap-core y.py:1-3 lines=3"
+  expect "pair h2 h1 shared=3 a=4 b=4 overlap=75% diff=2 strings=1/1/1"
+  expect "pair u1 p1 shared=0 a=2 b=2 overlap=0% diff=- strings=1/1/1"
+  expect "count n qualify 2"
+  # a name that is not there is refused, never counted as zero
+  if (unit u3 qualify c x.c three) 2>/dev/null; then echo "self-test: a missing unit was not refused" >&2; fail=1; fi
+  [ "$fail" = 0 ] && echo "audit-overlap self-test: ok"
+  return "$fail"
+}
+
+case "${1:-}" in
+  --self-test) self_test ;;
+  -h|--help|"") sed -n '5,9p' "$0"; [ -n "${1:-}" ] ;;
+  *) [ $# = 2 ] || die "usage: $0 <omx-clap-core dir> <plugin-hostd dir>"
+     ROOT[qualify]="$Q"; ROOT[clap-core]="$(cd "$1" && pwd)"; ROOT[hostd]="$(cd "$2" && pwd)"
+     audit ;;
+esac

package/tools/clap-core-tsdir.d.mts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/** The two TypeScript modules omx-clap-core's `tsdir` carries. */
+export const CLAP_CORE_TS_MODULES: readonly string[];
+/** Where omx-clap-core's TypeScript modules are looked for, in order. */
+export function clapCoreTsDirCandidates(env?: Readonly<Record<string, string | undefined>>): readonly string[];
+/** The first candidate holding both modules, or `undefined`. */
+export function findClapCoreTsDir(env?: Readonly<Record<string, string | undefined>>): string | undefined;
+/** True for an export name that is one of omx-clap-core's hosting tables. */
+export function isHostingTableName(name: string): boolean;
+/** One hosting table: key to its entry. */
+export type HostingEntries = Readonly<Record<string, { readonly code: string }>>;
+/** Every hosting table the modules in `dir` export, by export name. */
+export function loadHostingTables(dir: string): Promise<Record<string, HostingEntries>>;
+/** The tables flattened into one `key: code` map. */
+export function flattenHostingTables(tables: Readonly<Record<string, HostingEntries>>): Record<string, string>;

package/tools/clap-core-tsdir.mjs

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/*
+ * clap-core-tsdir.mjs — where omx-clap-core's TypeScript modules are, and their hosting tables.
+ *
+ * omx-clap-core declares every hosting code: one `HOSTING_<DIMENSION>_CODES` table per dimension,
+ * rendered into the 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.*`. `tools/gen-hosting-codes.mjs` reads them here
+ * to write `src/hosting-codes.generated.ts`, and the conformance test reads them here to hold that
+ * file to them.
+ *
+ * Node only, and build and test only: no module under src/ imports it, so nothing a public subpath
+ * reaches touches the filesystem or a child process.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The two TypeScript modules omx-clap-core's `tsdir` carries, each a `HOSTING_<DIMENSION>_CODES` source. */
+export const CLAP_CORE_TS_MODULES = Object.freeze(['omx-clap-core-vocabulary.js', 'omx-clap-core-hosting.js']);
+
+/** This package's root. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(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) {
+  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.
+ */
+export function clapCoreTsDirCandidates(env = process.env) {
+  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];
+}
+
+/** The first candidate holding both modules, or `undefined`. */
+export function findClapCoreTsDir(env = process.env) {
+  return clapCoreTsDirCandidates(env).find((d) => CLAP_CORE_TS_MODULES.every((m) => existsSync(join(d, m))));
+}
+
+/** True for an export name that is one of omx-clap-core's hosting tables. */
+export function isHostingTableName(name) {
+  return /^HOSTING_[A-Z0-9_]+_CODES$/.test(name);
+}
+
+/** Every `HOSTING_<DIMENSION>_CODES` table the two modules in `dir` export, by export name, in module order. */
+export async function loadHostingTables(dir) {
+  const tables = {};
+  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 = 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;
+    }
+  }
+  return tables;
+}
+
+/** The tables flattened into one `key: code` map; a key two tables declare is refused. */
+export function flattenHostingTables(tables) {
+  const flat = {};
+  for (const [name, entries] of Object.entries(tables)) {
+    for (const [key, entry] of Object.entries(entries)) {
+      if (key in flat) throw new Error(`omx-clap-core declares the hosting key ${key} twice (${name})`);
+      flat[key] = entry.code;
+    }
+  }
+  return flat;
+}