@openmixer/plugin-qualify 0.13.1 → 0.14.1

package/README.md

@@ -193,6 +193,40 @@ names the options it ran under, `featureOptions`:
 The defaults are the measurement as it has always been, so a verdict reached under them does not
 move. `lv2_measure --help` lists the same flags.
 
+## Scanned descriptors
+
+Both scanners also write what each plugin states about itself as a scanned descriptor: one JSON file per
+plugin in omx-contract's descriptor words (identity, controls, ports, what it needs from a host, whether it
+reports latency), held to omx-contract's descriptor schema before it is written. A descriptor holds no
+measurement and no verdict; those are the qualification record's.
+
+The files go into the descriptor directory, the key `descriptor_dir`:
+
+| | where |
+| --- | --- |
+| named | `--descriptor-dir <dir>` |
+| a user (the default) | `$XDG_STATE_HOME/omx/descriptors`, else `~/.local/state/omx/descriptors` |
+| a system service | `/var/lib/omx/descriptors` (`--system`) |
+
+Each file is named `<id>@<version>-<sha256 first 12>.json`: the CLAP id or the LV2 URI, the version the
+plugin states (`unversioned` when it states none) and the SHA-256 of its binary (the `.clap`, or the LV2
+bundle's `lv2:binary`), with every character other than letters, digits, `.`, `_` and `-` written `_`. The hash
+keys which file describes which binary: a changed binary is a new file, and the old one stays as history.
+
+```
+tools/scan.py --out catalog.json                                     # LV2: the catalog, and the descriptors beside it
+tools/scan.py --descriptor-dir ./descriptors urn:my:plugin           # one plugin, into a directory of your own
+native/build/clap-qualify --json ./my-fx.clap | tools/descriptors.py clap --descriptor-dir ./descriptors
+```
+
+`scan.py --no-descriptors` writes the catalog only. A descriptor the schema refuses is not written and is
+reported as `contract.file.invalid`, omx-contract's code; a plugin whose binary cannot be read is
+`qualify.descriptor.binary-unhashed`; a directory that cannot be written is `qualify.descriptor.dir-unwritable`;
+no schema found is `qualify.descriptor.schema-missing`. Any of them makes the run exit `2`, and the other
+plugins are still written. The schema is the omx-contract package plugin-qualify depends on, else
+`/usr/share/omx-contract/omx-contract.schema.json`; `OMX_CONTRACT_SCHEMA` names another one, for a test. The
+writer needs Python's `jsonschema` (`python3-jsonschema`).
+
 ## What the verdicts mean
 
 - **suitable**: every dimension was measured and passed. Safe to run inside the engine's own

package/dist/qualify-declarations.d.ts

@@ -117,6 +117,32 @@ export declare const LV2_HOSTING_BLOCK_FRAMES = 512;
 export declare const LV2_HOSTING_LIFECYCLES = 30;
 export declare const LV2_HOSTING_REPEATS = 3;
 export declare 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 declare const DESCRIPTOR_DIR_KEY = "descriptor_dir";
+export declare const DESCRIPTOR_DIR_STATE_SUBDIR = "omx/descriptors";
+export declare const DESCRIPTOR_DIR_SYSTEM = "/var/lib/omx/descriptors";
+export declare 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 declare const DESCRIPTOR_SCHEMA_ENV = "OMX_CONTRACT_SCHEMA";
+export declare const DESCRIPTOR_SCHEMA_INSTALLED = "/usr/share/omx-contract/omx-contract.schema.json";
+export declare 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 declare const DESCRIPTOR_CODE_SCHEMA = "contract.file.invalid";
+export declare const DESCRIPTOR_CODE_SCHEMA_MISSING = "qualify.descriptor.schema-missing";
+export declare const DESCRIPTOR_CODE_BINARY_UNHASHED = "qualify.descriptor.binary-unhashed";
+export declare const DESCRIPTOR_CODE_DIR_UNWRITABLE = "qualify.descriptor.dir-unwritable";
 /** Every threshold, so none is baked into the code. */
 export interface HostingPolicy {
     /** Minimum instantiate/destroy lifecycles. The operator's §14.4 ruling: 1000. */

package/dist/qualify-declarations.js

@@ -122,6 +122,32 @@ export const LV2_HOSTING_BLOCK_FRAMES = 512;
 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";
 /**
  * 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

package/dist/qualify-declarations.js.map

@@ -1 +1 @@
-{"version":3,"file":"qualify-declarations.js","sourceRoot":"","sources":["../src/qualify-declarations.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,sDAAsD;AACtD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;GAIG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAE5C,yHAAyH;AACzH,MAAM,CAAC,MAAM,aAAa,GAAsB,kBAAkB,CAAC;AAEnE,iJAAiJ;AACjJ,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;AAEpG,wGAAwG;AACxG,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAEnC,0FAA0F;AAC1F,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,sGAAsG;AACtG,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAClD,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAC/C,0IAA0I;AAC1I,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,oBAAoB,GAAG,oBAAoB,CAAC;AAEzD,sFAAsF;AACtF,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AACnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AACnD,MAAM,CAAC,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAA+D;IACtF,EAAE,IAAI,EAAE,sBAAsB,EAAE,GAAG,EAAE,qBAAqB,EAAE;IAC5D,EAAE,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,oBAAoB,EAAE;IAC1D,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,gBAAgB,EAAE;IAClD,EAAE,IAAI,EAAE,wBAAwB,EAAE,GAAG,EAAE,uBAAuB,EAAE;CACjE,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,6BAA6B,EAAE,yBAAyB,CAAC,CAAC;AAE9G,2GAA2G;AAC3G,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,yFAAyF;AACzF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAsBzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE;IACxB,oBAAoB,EAAE,CAAC;IACvB,cAAc,EAAE,EAAE;CACnB,CAAC;AAOF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,mBAAmB,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,cAAc,EAAE;IACtG,IAAI,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,EAAE;IAC1E,UAAU,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,EAAE;IAChF,eAAe,EAAE,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,EAAE;CAC9B,CAAC"}
+{"version":3,"file":"qualify-declarations.js","sourceRoot":"","sources":["../src/qualify-declarations.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/plugin-qualify",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "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",

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/descriptors.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+"""
+The scanned descriptors both scanners write (owner spec 6.6 and 6.9): one file per plugin, in
+omx-contract's descriptor words, named by the plugin's id, its version and the SHA-256 of its
+binary, in `descriptor_dir`.
+
+This module is the one writer: it resolves the directory, names the file, holds the document to
+the one descriptor schema (omx-contract's) and writes it whole. `scan.py` maps an LV2 plugin into a
+descriptor through lilv and writes it here; for CLAP, `clap-qualify --json` reads the plugin and
+`descriptors.py clap` maps its scan document. A descriptor the schema refuses is never written:
+it is refused with omx-contract's code, `contract.file.invalid`, and the scan goes on.
+
+A scan writes only what the plugin states. What it does not state is `unknown` (a unit, a scale,
+a meaning), or absent; a fact of the format that has no descriptor word is carried verbatim in
+`extensions.<format>` under the field the format names it by.
+
+Usage:
+  clap-qualify --json <path.clap>... | descriptors.py clap [--descriptor-dir DIR | --system] [-]
+  descriptors.py clap [--descriptor-dir DIR | --system] scan.json
+"""
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+
+from _declarations import (
+    DESCRIPTOR_CODE_BINARY_UNHASHED,
+    DESCRIPTOR_CODE_DIR_UNWRITABLE,
+    DESCRIPTOR_CODE_SCHEMA,
+    DESCRIPTOR_CODE_SCHEMA_MISSING,
+    DESCRIPTOR_DIR_STATE_SUBDIR,
+    DESCRIPTOR_DIR_SYSTEM,
+    DESCRIPTOR_HASH_PREFIX,
+    DESCRIPTOR_SCHEMA_ENV,
+    DESCRIPTOR_SCHEMA_FLOOR,
+    DESCRIPTOR_SCHEMA_INSTALLED,
+)
+
+SCHEMA_URL = "https://github.com/FreeMixer/omx-contract/raw/v3/schema/omx-contract.schema.json"
+TOOLS = os.path.dirname(os.path.abspath(__file__))
+PKG = os.path.dirname(TOOLS)
+
+# the plugin features the descriptor has words for: CLAP's own names, LV2 classes mapped onto them
+FEATURE_WORDS = ("audio-effect", "instrument", "note-effect", "analyzer")
+
+
+class DescriptorRefused(Exception):
+    """A descriptor that is not written, with the code it is refused by."""
+
+    def __init__(self, code, problem):
+        super().__init__(f"{code}: {problem}")
+        self.code = code
+        self.problem = problem
+
+
+# ---- the directory and the name -----------------------------------------------------------------
+
+def descriptor_dir(named=None, system=False, env=None, home=None):
+    """`descriptor_dir`: the directory named, else a system service's, else the user's state directory."""
+    if named:
+        return named
+    if system:
+        return DESCRIPTOR_DIR_SYSTEM
+    env = os.environ if env is None else env
+    state = env.get("XDG_STATE_HOME") or os.path.join(home or os.path.expanduser("~"), ".local", "state")
+    return os.path.join(state, *DESCRIPTOR_DIR_STATE_SUBDIR.split("/"))
+
+
+def _safe(text):
+    return re.sub(r"[^A-Za-z0-9._-]", "_", text)
+
+
+def descriptor_file_name(plugin_id, version, sha256):
+    """`<id>@<version>-<sha256 first 12>.json`, the base-name rule of the qualification record."""
+    if not isinstance(sha256, str) or not re.fullmatch(r"[0-9a-f]{64}", sha256):
+        raise DescriptorRefused(DESCRIPTOR_CODE_BINARY_UNHASHED, f"{plugin_id}: no SHA-256 of its binary")
+    return f"{_safe(plugin_id)}@{_safe(version or 'unversioned')}-{sha256[:DESCRIPTOR_HASH_PREFIX]}.json"
+
+
+def file_sha256(path):
+    """The SHA-256 of a file's bytes, as plugin-hostd's pin.h computes it."""
+    h = hashlib.sha256()
+    try:
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(1 << 20), b""):
+                h.update(chunk)
+    except OSError as e:
+        raise DescriptorRefused(DESCRIPTOR_CODE_BINARY_UNHASHED, f"{path}: {e.strerror}") from e
+    return h.hexdigest()
+
+
+# ---- the schema ---------------------------------------------------------------------------------
+
+def schema_candidates(env=None):
+    """Where the one schema is looked for, in order: the setting, this package's omx-contract, the installed one."""
+    env = os.environ if env is None else env
+    named = env.get(DESCRIPTOR_SCHEMA_ENV)
+    if named:
+        return [named]
+    rel = os.path.join("schema", "omx-contract.schema.json")
+    return [
+        os.path.join(PKG, "node_modules", "@openmixer", "omx-contract", rel),  # a checkout
+        os.path.join(os.path.dirname(PKG), "omx-contract", rel),  # installed beside this package
+        DESCRIPTOR_SCHEMA_INSTALLED,
+    ]
+
+
+class SchemaValidator:
+    """omx-contract's schema, compiled once; `check` refuses a document it does not hold."""
+
+    def __init__(self, path=None, env=None):
+        found = [path] if path else [p for p in schema_candidates(env) if os.path.isfile(p)]
+        if not found or not os.path.isfile(found[0]):
+            raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA_MISSING,
+                                    f"no omx-contract schema at {', '.join(schema_candidates(env))}")
+        self.path = found[0]
+        try:
+            import jsonschema
+        except ImportError as e:
+            raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA_MISSING, "python3-jsonschema is not installed") from e
+        with open(self.path, encoding="utf-8") as f:
+            schema = json.load(f)
+        cls = jsonschema.validators.validator_for(schema)
+        self._validator = cls(schema)
+        self.version = schema.get("x-omx-schema-version")
+
+    def check(self, doc):
+        if not isinstance(doc, dict) or doc.get("origin") != "scanned":
+            raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA, "a scanned descriptor carries origin scanned")
+        errors = sorted(self._validator.iter_errors(doc), key=lambda e: list(e.absolute_path))
+        if errors:
+            e = errors[0]
+            where = "/".join(str(p) for p in e.absolute_path) or "(the file)"
+            raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA, f"{where}: {e.message}")
+
+
+def write_descriptor(directory, doc, sha256, validator):
+    """Hold `doc` to the schema and write it whole into `directory`; the path written, or DescriptorRefused."""
+    validator.check(doc)
+    name = descriptor_file_name(doc["plugin"]["id"], doc["plugin"].get("version"), sha256)
+    try:
+        os.makedirs(directory, mode=0o700, exist_ok=True)
+        path = os.path.join(directory, name)
+        pending = path + ".new"
+        with open(pending, "w", encoding="utf-8") as f:
+            f.write(json.dumps(doc, indent=2, ensure_ascii=False) + "\n")
+        os.replace(pending, path)
+    except OSError as e:
+        raise DescriptorRefused(DESCRIPTOR_CODE_DIR_UNWRITABLE, f"{directory}: {e.strerror}") from e
+    return path
+
+
+def write_all(directory, described, validator, err=sys.stderr):
+    """Write each `(doc, sha256)`; a refusal is reported by its code and the others go on. (written, refused)."""
+    written, refused = [], []
+    for doc, sha256 in described:
+        try:
+            written.append(write_descriptor(directory, doc, sha256, validator))
+        except DescriptorRefused as e:
+            pid = (doc.get("plugin") or {}).get("id", "?") if isinstance(doc, dict) else "?"
+            refused.append((pid, e.code, e.problem))
+            err.write(f"descriptor refused: {pid}: {e.code}: {e.problem}\n")
+    return written, refused
+
+
+# ---- shared words -------------------------------------------------------------------------------
+
+def head(fmt, plugin):
+    """The fields every scanned descriptor opens with."""
+    return {
+        "$schema": SCHEMA_URL,
+        "requires": {"omx-contract-schema": DESCRIPTOR_SCHEMA_FLOOR},
+        "origin": "scanned",
+        "plugin": {"format": fmt, **plugin},
+    }
+
+
+def link_segment(text):
+    """A path segment or a selector key a link can hold; a character it cannot is written `_`."""
+    return re.sub(r"[^A-Za-z0-9_+.-]", "_", text) or "_"
+
+
+def link_key(text):
+    """A link's selector key, `[<key>]`; a character it cannot hold is written `_`."""
+    return re.sub(r"[^A-Za-z0-9_.-]", "_", text) or "_"
+
+
+def link_symbol(text):
+    """A link's symbol: an identifier, `_` for a character it cannot hold."""
+    s = re.sub(r"[^A-Za-z0-9_]", "_", text)
+    return s if re.match(r"[A-Za-z_]", s) else "_" + s
+
+
+def one_line(text):
+    text = " ".join((text or "").split())
+    return text or None
+
+
+def choice_ids(labels):
+    """A choice's ids, from its labels: their letters and digits, `v<n>` where that is empty or taken."""
+    ids, seen = [], set()
+    for n, label in enumerate(labels):
+        word = re.sub(r"[^A-Za-z0-9]", "", label)
+        word = word[:1].lower() + word[1:]
+        if not word or word in seen:
+            word = f"v{n}"
+        while word in seen:
+            word += "x"
+        seen.add(word)
+        ids.append(word)
+    return ids
+
+
+def _number(v):
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and v == v and abs(v) != float("inf")
+
+
+# ---- CLAP: clap-qualify's scan document ---------------------------------------------------------
+
+CLAP_DIALECTS = {"clap": "clap", "midi": "midi", "midi_mpe": "midiMpe", "midi2": "midi2"}
+CLAP_LAYOUTS = {"mono": "mono", "stereo": "stereo", "surround": "surround"}
+
+
+def clap_control(p, entry):
+    flags = set(p.get("flags", []))
+    c = {"id": p["id"], "name": p["name"] or str(p["id"])}
+    labels = p.get("labels") or []
+    if "enum" in flags and labels:
+        ids = choice_ids([lb["label"] for lb in labels])
+        c["kind"] = "choice"
+        c["ids"] = ids
+        if all(lb["label"] for lb in labels):
+            c["labels"] = [lb["label"] for lb in labels]
+        c["values"] = [lb["value"] for lb in labels]
+        for i, lb in enumerate(labels):
+            if lb["value"] == p.get("default"):
+                c["default"] = ids[i]
+    else:
+        c["kind"] = "travel"
+        travel = {
+            "min": p["min"],
+            "max": p["max"],
+            "unit": "unknown",
+            "scale": "stepped" if "stepped" in flags else "unknown",
+        }
+        if "stepped" in flags:
+            travel["step"] = 1
+        if _number(p.get("default")):
+            travel["default"] = p["default"]
+        c["travel"] = travel
+    if p.get("module"):
+        group = [g for g in p["module"].split("/") if g]
+        if group:
+            c["group"] = group
+    c["meaning"] = "bypass" if "bypass" in flags else "unknown"
+    for flag in ("hidden", "readonly", "automatable"):
+        if flag in flags:
+            c[flag] = True
+    c["source"] = {"from": f"{entry}[{p['id']}]"}
+    return c
+
+
+def open_bound(p):
+    """A parameter the plugin leaves unbounded: no travel holds it, so it is carried verbatim instead."""
+    labels = p.get("labels") or []
+    return not ("enum" in p.get("flags", []) and labels) and not (_number(p.get("min")) and _number(p.get("max")))
+
+
+def clap_ports(p):
+    ports = []
+    for direction, key in (("in", "inputs"), ("out", "outputs")):
+        for port in p["audio_ports"][key]:
+            q = {"id": port["id"], "name": port["name"] or f"audio {direction} {port['id']}",
+                 "kind": "audio", "direction": direction, "role": port["role"]}
+            if port.get("channels", 0) >= 1:
+                q["channels"] = port["channels"]
+            layout = CLAP_LAYOUTS.get(port.get("port_type") or "")
+            if layout:
+                q["layout"] = layout
+            ports.append(q)
+    notes = p.get("note_port_info")
+    for direction, key in (("in", "inputs"), ("out", "outputs")):
+        for port in (notes or {}).get(key, []):
+            q = {"id": port["id"], "name": port["name"] or f"notes {direction} {port['id']}",
+                 "kind": "note", "direction": direction}
+            dialects = [CLAP_DIALECTS[d] for d in port.get("dialects", []) if d in CLAP_DIALECTS]
+            if dialects:
+                q["dialects"] = dialects
+            ports.append(q)
+    return ports
+
+
+def clap_descriptor(p, path):
+    """One plugin of clap-qualify's scan document as a scanned descriptor."""
+    entry = f"{link_segment(os.path.basename(path))}#clap_entry[{link_key(p['id'])}]"
+    plugin = {"id": p["id"], "name": p["name"] or p["id"]}
+    if p.get("vendor"):
+        plugin["vendor"] = p["vendor"]
+    if p.get("version"):
+        plugin["version"] = p["version"]
+    doc = one_line(p.get("description"))
+    if doc:
+        plugin["doc"] = doc
+    stated = [f for f in p.get("features", []) if f in FEATURE_WORDS]
+    plugin["features"] = list(dict.fromkeys(stated)) or ["audio-effect"]
+    d = head("clap", plugin)
+    params = p.get("params", [])
+    d["controls"] = [clap_control(q, entry) for q in params if not open_bound(q)]
+    d["ports"] = clap_ports(p)
+    if "latency_extension" in p:
+        d["latency"] = {"reports": bool(p["latency_extension"])}
+    bag = {}
+    if p.get("features"):
+        bag["clap_plugin_descriptor.features"] = list(p["features"])
+    if p.get("url"):
+        bag["clap_plugin_descriptor.url"] = p["url"]
+    if "latency" in p:
+        bag["clap_plugin_latency.get"] = p["latency"]
+    unbounded = [q for q in params if open_bound(q)]
+    if unbounded:
+        bag["clap_plugin_params.get_info"] = unbounded
+    if p.get("remote_controls"):
+        bag["clap_plugin_remote_controls.get"] = p["remote_controls"]
+    if bag:
+        d["extensions"] = {"clap": bag}
+    d["source"] = {"from": entry}
+    return d
+
+
+def clap_described(scan, err=sys.stderr):
+    """Every plugin of a clap-qualify scan document as `(doc, sha256)`; a file that held none is reported."""
+    if not isinstance(scan, dict) or not isinstance(scan.get("files"), list):
+        raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA, "not a CLAP scan document")
+    out = []
+    for f in scan["files"]:
+        if "plugins" not in f:
+            err.write(f"not described: {f.get('path')}: {f.get('error')}\n")
+            continue
+        for p in f["plugins"]:
+            if "error" in p:
+                err.write(f"not described: {p.get('id')}: {p['error']}\n")
+                continue
+            out.append((clap_descriptor(p, f["path"]), f.get("sha256")))
+    return out
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Write the scanned descriptors of a CLAP scan document.")
+    ap.add_argument("format", choices=["clap"], help="the scan document's format")
+    ap.add_argument("scan", nargs="?", default="-", help="clap-qualify --json output (default: stdin)")
+    where = ap.add_mutually_exclusive_group()
+    where.add_argument("--descriptor-dir", help="where the descriptors go (descriptor_dir)")
+    where.add_argument("--system", action="store_true", help=f"a system service's directory, {DESCRIPTOR_DIR_SYSTEM}")
+    # intermixed: `clap --descriptor-dir DIR -` puts the scan after an option, and parse_args on Python 3.11
+    # and 3.12.3 (Debian bookworm, Ubuntu noble) fills the optional positional with its default first and
+    # then refuses the `-` as unrecognized; later interpreters accept it. Intermixed parsing reads it on all.
+    args = ap.parse_intermixed_args(argv)
+    try:
+        text = sys.stdin.read() if args.scan == "-" else open(args.scan, encoding="utf-8").read()
+        scan = json.loads(text)
+    except (OSError, ValueError) as e:
+        sys.stderr.write(f"cannot read the scan document: {e}\n")
+        return 2
+    try:
+        validator = SchemaValidator()
+        described = clap_described(scan)
+    except DescriptorRefused as e:
+        sys.stderr.write(f"{e.code}: {e.problem}\n")
+        return 2
+    directory = descriptor_dir(args.descriptor_dir, args.system)
+    written, refused = write_all(directory, described, validator)
+    for path in written:
+        print(path)
+    return 2 if refused else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/gen-python-declarations.mjs

@@ -35,9 +35,21 @@ const PY_NAMES = [
   'PLUGIN_TIMEOUT_S',
   'BOOT_TIMEOUT_S',
   'COST_TIMEOUT_S',
+  'DESCRIPTOR_DIR_KEY',
+  'DESCRIPTOR_DIR_STATE_SUBDIR',
+  'DESCRIPTOR_DIR_SYSTEM',
+  'DESCRIPTOR_HASH_PREFIX',
+  'DESCRIPTOR_SCHEMA_ENV',
+  'DESCRIPTOR_SCHEMA_INSTALLED',
+  'DESCRIPTOR_SCHEMA_FLOOR',
+  'DESCRIPTOR_CODE_SCHEMA',
+  'DESCRIPTOR_CODE_SCHEMA_MISSING',
+  'DESCRIPTOR_CODE_BINARY_UNHASHED',
+  'DESCRIPTOR_CODE_DIR_UNWRITABLE',
 ];
 
-const py = (v) => (Array.isArray(v) ? `(${v.join(', ')})` : String(v));
+/** A Python literal: a tuple, a string (JSON's quoting is Python's for these ASCII words) or a number. */
+const py = (v) => (Array.isArray(v) ? `(${v.join(', ')})` : typeof v === 'string' ? JSON.stringify(v) : String(v));
 
 /** `decl` defaults to the built declarations; a test passes moved ones to prove the Python side follows. */
 export function declarationsFile(decl = D) {

package/tools/scan.py

@@ -13,17 +13,25 @@ parameter are captured: classic LV2 **control ports** (set via mod-host
 `param_set <id> <symbol> <value>`) and LV2 **Patch properties** (`lv2:Parameter`
 flagged `patch:writable`, set via `patch_set <id> <uri> <value>`).
 
+Beside the catalog, every plugin scanned is written as a scanned descriptor (omx-contract's
+descriptor words, `descriptors.py`) into `descriptor_dir`: `--descriptor-dir`, else `--system`'s
+directory, else `$XDG_STATE_HOME/omx/descriptors`, else `~/.local/state/omx/descriptors`.
+
 Usage:
   scan.py                       # scan all installed plugins -> stdout JSON
   scan.py --out catalog.json    # write to a file
   scan.py URI [URI ...]         # scan only these URIs (faster, for tests)
   scan.py --annotate catalog.json   # refresh only the DECLARED fields, in place
+  scan.py --descriptor-dir DIR  # the scanned descriptors go here
+  scan.py --no-descriptors      # the catalog only
 """
 import argparse
 import json
+import os
 import subprocess
 import sys
 
+import descriptors as desc
 from lv2_presets import read_presets
 
 LV2 = "http://lv2plug.in/ns/lv2core#"
@@ -36,6 +44,9 @@ PATCH = "http://lv2plug.in/ns/ext/patch#"
 ATOM = "http://lv2plug.in/ns/ext/atom#"
 RDFS = "http://www.w3.org/2000/01/rdf-schema#"
 MIDI = "http://lv2plug.in/ns/ext/midi#"
+PG = "http://lv2plug.in/ns/ext/port-groups#"
+PARAM = "http://lv2plug.in/ns/ext/parameters#"
+TIME = "http://lv2plug.in/ns/ext/time#"
 
 # An output control port designated lv2:latency reports the plugin's own latency
 # (in frames) — the truth a host delay-compensates by, and what openmixer reads to
@@ -61,6 +72,30 @@ KNOWN_UNITS = {
     UNITS + "bpm": "BPM", UNITS + "midiNote": "note", UNITS + "frame": "fr",
 }
 
+# LV2 unit URI -> the descriptor's unit word; any other unit, or none, is `unknown`
+DESCRIPTOR_UNITS = {
+    UNITS + "db": "dB", UNITS + "hz": "Hz", UNITS + "s": "s", UNITS + "ms": "ms",
+    UNITS + "min": "min", UNITS + "pc": "%", UNITS + "semitone12TET": "st", UNITS + "cent": "cents",
+    UNITS + "degree": "deg", UNITS + "coef": "x", UNITS + "oct": "oct", UNITS + "bpm": "bpm",
+    UNITS + "midiNote": "midiNote", UNITS + "frame": "frames",
+}
+
+# lv2:designation -> the descriptor's meaning, where the meaning carries the LV2 term's name
+DESIGNATED_MEANINGS = {
+    **{PARAM + m: m for m in ("gain", "threshold", "ratio", "attack", "release", "hold", "decay", "frequency",
+                              "cutoffFrequency", "resonance", "bypass", "wetDryRatio", "delay")},
+    LV2 + "enabled": "enabled",
+}
+
+# LV2 classes -> the descriptor's plugin features; a plugin of none of them is an audio effect
+CLASS_FEATURES = {
+    LV2 + "InstrumentPlugin": "instrument",
+    LV2 + "AnalyserPlugin": "analyzer",
+    LV2 + "MIDIPlugin": "note-effect",
+}
+
+NUMERIC_PATCH_RANGES = ("Float", "Double", "Int", "Long")
+
 
 def fnum(node):
     """float(node) tolerant of None and integer/string-typed nodes.
@@ -80,11 +115,23 @@ def fnum(node):
             return None
 
 
+def each(nodes):
+    """Every element of a lilv collection (None is empty), walked by the binding's own begin, is_end and next,
+    which every version has: the Python iteration of some does not hold for every collection."""
+    if nodes is None:
+        return []
+    if isinstance(nodes, (list, tuple)):
+        return list(nodes)
+    out = []
+    it = nodes.begin()
+    while not it.is_end():
+        out.append(it.next())
+    return out
+
+
 def first(nodes):
     """First element of a lilv Nodes collection, or None."""
-    if nodes is None:
-        return None
-    for n in nodes:
+    for n in each(nodes):
         return n
     return None
 
@@ -144,6 +191,8 @@ class Scanner:
             RDFS + "label", RDFS + "range", MIDI + "MidiEvent",
             LV2 + "designation", LATENCY, REPORTS_LATENCY,
             MINIMUM, MAXIMUM, DEFAULT,
+            LV2 + "isSideChain", LV2 + "name", PG + "group", TIME + "Position",
+            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
         )}
 
     def is_a(self, port, uri):
@@ -306,6 +355,195 @@ class Scanner:
         out["owningRpm"] = owning_rpm(bp)
         return out
 
+    # ---- the scanned descriptor ----
+
+    def designation_meaning(self, port):
+        """The meaning an lv2:designation names; `unknown` with none; absent (None) for one with no word."""
+        des = [str(d) for d in each(port.get_value(self.u[LV2 + "designation"]))]
+        if not des:
+            return "unknown"
+        for d in des:
+            if d in DESIGNATED_MEANINGS:
+                return DESIGNATED_MEANINGS[d]
+        return None
+
+    def port_group(self, port):
+        """The pg:group a port belongs to, by its name, as a one-step group path."""
+        g = first(port.get_value(self.u[PG + "group"]))
+        if g is None:
+            return None
+        label = first(self.w.find_nodes(g, self.u[LV2 + "name"], None)) or first(self.w.find_nodes(g, self.u[RDFS + "label"], None))
+        return [str(label)] if label is not None and str(label) else None
+
+    def descriptor_unit(self, port):
+        un = first(port.get_value(self.u[UNITS + "unit"]))
+        return DESCRIPTOR_UNITS.get(str(un), "unknown") if un is not None else "unknown"
+
+    def descriptor_control(self, port, link, readonly=False):
+        """An input (or, readonly, an output) control port as a descriptor control."""
+        d, mn, mx = port.get_range()
+        mnf, mxf, df = fnum(mn), fnum(mx), fnum(d)
+        sym = str(port.get_symbol())
+        nm = port.get_name()
+        c = {"id": sym, "name": str(nm) if nm is not None else sym}
+        sps = self.scale_points(port)
+        if self.has(port, LV2 + "toggled"):
+            c["kind"] = "toggle"
+            if df is not None:
+                c["default"] = df > 0
+        elif self.has(port, PP + "trigger"):
+            c["kind"] = "trigger"
+        elif self.has(port, LV2 + "enumeration") and sps:
+            ids = desc.choice_ids([sp["label"] for sp in sps])
+            c["kind"] = "choice"
+            c["ids"] = ids
+            if all(sp["label"] for sp in sps):
+                c["labels"] = [sp["label"] for sp in sps]
+            c["values"] = [sp["value"] for sp in sps]
+            for i, sp in enumerate(sps):
+                if df is not None and sp["value"] == df:
+                    c["default"] = ids[i]
+        else:
+            # an LV2 port's range defaults to 0..1 where it declares none (the catalog row's own rule)
+            integer = self.has(port, LV2 + "integer")
+            travel = {
+                "min": mnf if mnf is not None else 0.0,
+                "max": mxf if mxf is not None else 1.0,
+                "unit": self.descriptor_unit(port),
+                "scale": "log" if self.has(port, PP + "logarithmic") else "stepped" if integer else "linear",
+            }
+            if integer:
+                travel["step"] = 1
+            if df is not None:
+                travel["default"] = df
+            c["kind"] = "travel"
+            c["travel"] = travel
+        group = self.port_group(port)
+        if group:
+            c["group"] = group
+        meaning = self.designation_meaning(port)
+        if meaning is not None:
+            c["meaning"] = meaning
+        if self.has(port, PP + "notOnGUI"):
+            c["hidden"] = True
+        if readonly:
+            c["readonly"] = True
+        c["source"] = {"from": f"{link}#{desc.link_symbol(sym)}"}
+        return c
+
+    def descriptor(self, plugin):
+        """The plugin as a scanned descriptor, and the SHA-256 of its binary: `(doc, sha256)`."""
+        uri = str(plugin.get_uri())
+        bundle = bundle_path(plugin) or ""
+        lib = plugin.get_library_uri()
+        lib_path = lib.get_path() if lib is not None else None
+        try:
+            sha256 = desc.file_sha256(lib_path) if lib_path else None
+        except desc.DescriptorRefused:
+            sha256 = None  # refused by its code when it is written: no name without the binary's hash
+        data = sorted(os.path.basename(str(u)) for u in each(plugin.get_data_uris()))
+        ttl = next((f for f in data if f != "manifest.ttl"), "manifest.ttl")
+        bundle_seg = desc.link_segment(os.path.basename(bundle))
+        link = f"{bundle_seg}/{desc.link_segment(ttl)}"
+
+        types = [str(t) for t in each(plugin.get_value(self.u["http://www.w3.org/1999/02/22-rdf-syntax-ns#type"]))]
+        features = [CLASS_FEATURES[t] for t in types if t in CLASS_FEATURES]
+        p = {"id": uri, "uri": uri, "name": str(plugin.get_name())}
+        author = plugin.get_author_name()
+        if author is not None and str(author):
+            p["vendor"] = str(author)
+        version = self.plugin_version(plugin)
+        if version is not None:
+            p["version"] = f"{version[0]}.{version[1]}"
+        comment = declared_comment(plugin, self.w)
+        if comment:
+            p["doc"] = comment
+        p["features"] = list(dict.fromkeys(features)) or ["audio-effect"]
+        d = desc.head("lv2", p)
+
+        controls, ports = [], []
+        latency_symbol, timed = None, False
+        for i in range(plugin.get_num_ports()):
+            port = plugin.get_port_by_index(i)
+            sym = str(port.get_symbol())
+            nm = port.get_name()
+            name = str(nm) if nm is not None else sym
+            direction = "in" if self.is_a(port, LV2 + "InputPort") else "out"
+            if self.is_a(port, LV2 + "AudioPort"):
+                ports.append({"id": sym, "name": name, "kind": "audio", "direction": direction,
+                              "role": "sidechain" if self.has(port, LV2 + "isSideChain") else "main", "channels": 1})
+            elif self.is_a(port, LV2 + "CVPort"):
+                ports.append({"id": sym, "name": name, "kind": "cv", "direction": direction})
+            elif self.is_a(port, LV2 + "ControlPort"):
+                if direction == "out" and latency_symbol is None and self.is_latency_port(port):
+                    latency_symbol = sym
+                    continue
+                controls.append(self.descriptor_control(port, link, readonly=direction == "out"))
+            elif self.is_a(port, ATOM + "AtomPort"):
+                try:
+                    midi = bool(port.supports_event(self.u[MIDI + "MidiEvent"]))
+                    timed = timed or (direction == "in" and bool(port.supports_event(self.u[TIME + "Position"])))
+                except Exception:  # noqa: BLE001
+                    midi = False
+                if midi:
+                    ports.append({"id": sym, "name": name, "kind": "midi", "direction": direction})
+
+        writable = []
+        for prm in self.patch_params(plugin):
+            writable.append({"uri": prm["uri"], "label": prm["name"], "range": prm["datatype"]})
+            if prm["datatype"] in NUMERIC_PATCH_RANGES and "min" in prm and "max" in prm:
+                travel = {"min": prm["min"], "max": prm["max"], "unit": "unknown", "scale": "linear"}
+                if "default" in prm:
+                    travel["default"] = prm["default"]
+                controls.append({"id": desc.link_symbol(prm["symbol"]), "name": prm["name"], "kind": "travel",
+                                 "travel": travel, "meaning": "unknown",
+                                 "source": {"from": f"{link}#{desc.link_symbol(prm['symbol'])}"}})
+        d["controls"] = controls
+        d["ports"] = ports
+
+        needs = {}
+        if timed:
+            needs["tempo"] = needs["transport"] = True
+        required = [str(f) for f in each(plugin.get_required_features())]
+        optional = [str(f) for f in each(plugin.get_optional_features())]
+        ext = {}
+        if required:
+            ext["required"] = sorted(set(required))
+        if optional:
+            ext["optional"] = sorted(set(optional))
+        if ext:
+            needs["extensions"] = ext
+        if needs:
+            d["needs"] = needs
+        d["latency"] = {"reports": latency_symbol is not None}
+
+        bag = {"rdf:type": str(plugin.get_class().get_uri())}
+        if latency_symbol is not None:
+            bag["lv2:latency"] = latency_symbol
+        if writable:
+            bag["patch:writable"] = writable
+        d["extensions"] = {"lv2": bag}
+        lib_name = os.path.basename(lib_path) if lib_path else "manifest.ttl"
+        d["source"] = {"from": f"{bundle_seg}/{desc.link_segment(lib_name)}#lv2_descriptor"}
+        return d, sha256
+
+    def descriptors(self, uris=None):
+        """`(doc, sha256)` for every plugin `scan` would describe."""
+        plugins = self.w.get_all_plugins()
+        chosen = [plugins.get_by_uri(self.w.new_uri(u)) for u in uris] if uris else list(plugins)
+        out = []
+        for p in chosen:
+            if p is None:
+                continue
+            try:
+                out.append(self.descriptor(p))
+            except desc.DescriptorRefused as e:
+                sys.stderr.write(f"descriptor refused: {p.get_uri()}: {e.code}: {e.problem}\n")
+            except Exception as e:  # noqa: BLE001 - one plugin's bad data never stops the scan
+                line = e.__traceback__.tb_next.tb_lineno if e.__traceback__ and e.__traceback__.tb_next else "?"
+                sys.stderr.write(f"not described: {p.get_uri()}: {type(e).__name__}: {e} (scan.py:{line})\n")
+        return out
+
     def plugin_version(self, plugin):
         """(minor, micro) from lv2:minorVersion / lv2:microVersion, or None.
 
@@ -395,6 +633,11 @@ def main():
     ap.add_argument("--out", help="write JSON here (default: stdout)")
     ap.add_argument("--annotate", metavar="FILE",
                     help="refresh only the DECLARED fields of an existing catalog, in place")
+    where = ap.add_mutually_exclusive_group()
+    where.add_argument("--descriptor-dir", help="where the scanned descriptors go (descriptor_dir)")
+    where.add_argument("--system", action="store_true",
+                       help=f"a system service's descriptor_dir, {desc.DESCRIPTOR_DIR_SYSTEM}")
+    where.add_argument("--no-descriptors", action="store_true", help="write the catalog only")
     args = ap.parse_args()
     if args.annotate:
         with open(args.annotate, encoding="utf-8") as f:
@@ -408,7 +651,18 @@ def main():
             f"annotated {len(catalog)} plugins in {args.annotate}: "
             f"{changed} declared fields changed, {absent} not installed here\n")
         return
-    catalog = Scanner().scan(args.uris or None)
+    scanner = Scanner()
+    catalog = scanner.scan(args.uris or None)
+    refused = 0
+    if not args.no_descriptors:
+        try:
+            validator = desc.SchemaValidator()
+        except desc.DescriptorRefused as e:
+            sys.exit(f"{e.code}: {e.problem}")
+        directory = desc.descriptor_dir(args.descriptor_dir, args.system)
+        written, bad = desc.write_all(directory, scanner.descriptors(args.uris or None), validator)
+        refused = len(bad)
+        sys.stderr.write(f"wrote {len(written)} descriptors -> {directory}\n")
     text = json.dumps(catalog, indent=2, ensure_ascii=False)
     if args.out:
         with open(args.out, "w", encoding="utf-8") as f:
@@ -426,6 +680,8 @@ def main():
             sys.stderr.write(f"wrote {len(uris)} URIs -> {uri_path}\n")
     else:
         print(text)
+    if refused:
+        sys.exit(2)
 
 
 if __name__ == "__main__":