@openmixer/plugin-qualify 0.8.0 → 0.9.0

package/src/clap-loader.ts

@@ -3,7 +3,8 @@
 /**
  * The CLAP implementation of the one discovery seam (`loader.ts`). A target that is a `.clap` file, or a
  * directory holding one, is scanned by `omx-clap-scan --json` (the scanner of omx-clap-host),
- * located by the ONE declared setting; `urn:clap:<id>` is one plugin without a scan. The
+ * located by the ONE declared setting; `urn:clap:<id>` is one plugin without a scan. `--all` walks
+ * the standard CLAP search path ({@link clapSearchPath}) through the same loader. The
  * scanner's JSON is the input: {@link clapScanDescriptors} normalises it into the interchange
  * rows. A scan that cannot be read is a {@link ClapScanError}, never an empty result.
  *
@@ -12,11 +13,20 @@
  * remote-control pages; a row keeps them, and each parameter's module, wherever the scan read them.
  */
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 import type { PluginLoader, PluginTarget } from "./loader.js";
-import { CLAP_SCAN_TIMEOUT_S, CLAP_SCAN_TOOL_DEFAULT, CLAP_SCAN_TOOL_ENV } from "./qualify-declarations.js";
+import { lv2BundlesOnPath } from "./lv2-loader.js";
+import {
+  CLAP_PATH_ENV,
+  CLAP_SCAN_TIMEOUT_S,
+  CLAP_SCAN_TOOL_DEFAULT,
+  CLAP_SCAN_TOOL_ENV,
+  CLAP_SYSTEM_DIR,
+  CLAP_USER_DIR,
+} from "./qualify-declarations.js";
 
 /** The scanner's own name in its document — anything else is not its output. */
 const SCANNER_NAME = "omx-clap-scan";
@@ -344,11 +354,33 @@ export function clapScanTool(env: Readonly<Record<string, string | undefined>>):
   return named === undefined || named === "" ? CLAP_SCAN_TOOL_DEFAULT : named;
 }
 
+/** An fs error met while walking a search directory, as the scan refusal that names the path. */
+function unreadable(path: string, e: unknown): ClapScanError {
+  if (e instanceof ClapScanError) return e;
+  const code = (e as NodeJS.ErrnoException).code;
+  return new ClapScanError(`cannot read ${path}: ${typeof code === "string" ? code : String(e)}`);
+}
+
+/** A directory entry that is a directory, or a symlink to one; a dangling link is not, any other fs error (a loop) is thrown. */
+function isDirectory(e: Dirent, p: string): boolean {
+  if (e.isDirectory()) return true;
+  if (!e.isSymbolicLink()) return false;
+  try {
+    return statSync(p).isDirectory();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw err;
+  }
+}
+
 function holdsClap(dir: string): boolean {
-  for (const e of readdirSync(dir, { withFileTypes: true })) {
-    const p = join(dir, e.name);
-    const isDir = e.isDirectory() || (e.isSymbolicLink() && existsSync(p) && statSync(p).isDirectory());
-    if (isDir ? holdsClap(p) : e.name.endsWith(CLAP_SUFFIX)) return true;
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (isDirectory(e, p) ? holdsClap(p) : e.name.endsWith(CLAP_SUFFIX)) return true;
+    }
+  } catch (e) {
+    throw unreadable(dir, e);
   }
   return false;
 }
@@ -391,3 +423,63 @@ export function clapLoader(options: ClapLoaderOptions = {}): PluginLoader {
     },
   };
 }
+
+// --- the standard search path (`--all`) ----------------------------------------------------------
+
+/**
+ * The directories `--all` walks, in order and once each: every non-empty entry of `CLAP_PATH`, then
+ * `~/.clap`, then `/usr/lib/clap`.
+ */
+export function clapSearchPath(env: Readonly<Record<string, string | undefined>>, home: string): string[] {
+  const named = (env[CLAP_PATH_ENV] ?? "").split(":").filter((d) => d !== "");
+  return [...new Set([...named, join(home, CLAP_USER_DIR), CLAP_SYSTEM_DIR].map((d) => resolve(d)))];
+}
+
+export interface ClapDiscoverOptions extends ClapLoaderOptions {
+  /** The home directory `~/.clap` is read under; the default is the user's. */
+  readonly home?: string;
+}
+
+/**
+ * Every CLAP plugin on the standard search path, each directory resolved through {@link clapLoader}
+ * exactly as a named directory is. A directory that is absent or holds no `.clap` is skipped; a
+ * plugin id found twice keeps its first place on the path. A directory that cannot be read (a
+ * permission error, a symlink loop) is a {@link ClapScanError} naming it, never a partial list.
+ */
+export function discoverClapTargets(options: ClapDiscoverOptions = {}): PluginTarget[] {
+  const loader = clapLoader(options);
+  const found = new Map<string, PluginTarget>();
+  for (const dir of clapSearchPath(options.env ?? process.env, options.home ?? homedir())) {
+    try {
+      if (!existsSync(dir) || !statSync(dir).isDirectory()) continue;
+      for (const t of loader.resolve(dir) ?? []) if (!found.has(t.uri)) found.set(t.uri, t);
+    } catch (e) {
+      throw unreadable(dir, e);
+    }
+  }
+  return [...found.values()];
+}
+
+export interface DiscoverAllOptions extends ClapDiscoverOptions {}
+
+/**
+ * The targets of `--all`. The LV2 plugins lilv finds cannot be measured from this entry point, so
+ * when the LV2 search path holds any bundle the run refuses (exit 2) and names how many, rather
+ * than qualifying only the CLAP side and reporting everything qualified.
+ */
+export function discoverAllTargets(options: DiscoverAllOptions = {}): PluginTarget[] {
+  const env = options.env ?? process.env;
+  let bundles: string[];
+  try {
+    bundles = lv2BundlesOnPath(env, options.home ?? homedir());
+  } catch (e) {
+    throw unreadable("the LV2 search path", e);
+  }
+  if (bundles.length > 0) {
+    throw new ClapScanError(
+      `--all cannot measure LV2 from this entry point and ${String(bundles.length)} LV2 bundle(s) are on the LV2 path ` +
+        `(first: ${bundles[0]}); name the plugins or bundles to qualify instead, or unset LV2_PATH to an empty directory`,
+    );
+  }
+  return discoverClapTargets(options);
+}

package/src/index.ts

@@ -17,5 +17,6 @@ export * from "./clap-loader.js";
 export * from "./clap-qualify.js";
 export * from "./qualify-options.js";
 export * from "./qualify-cli.js";
+export * from "./pins-file.js";
 export * from "./measure-host.js";
 export * from "./cost-fields.js";

package/src/lv2-loader.ts

@@ -9,8 +9,9 @@
  * The manifest read is the subset every LV2 bundle's manifest uses (subject, `a lv2:Plugin`,
  * `lv2:binary <x.so>`), not a Turtle parser; `--all` goes through lilv itself.
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { basename, join } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
 
 import type { PluginLoader, PluginTarget } from "./loader.js";
 
@@ -48,3 +49,28 @@ export const lv2Loader: PluginLoader = {
     return URI_SHAPE.test(target) ? [{ format: "lv2", uri: target }] : undefined;
   },
 };
+
+/** lilv's default LV2 search path, used when `LV2_PATH` is unset. */
+const LV2_DEFAULT_DIRS = [".lv2", "/usr/lib/lv2", "/usr/lib64/lv2", "/usr/local/lib/lv2", "/usr/local/lib64/lv2"];
+
+/**
+ * Every `.lv2` bundle directly under the LV2 search path (`LV2_PATH`, else lilv's defaults). An
+ * absent directory holds none; any other fs error propagates for the caller to name.
+ */
+export function lv2BundlesOnPath(env: Readonly<Record<string, string | undefined>>, home: string = homedir()): string[] {
+  const named = (env["LV2_PATH"] ?? "").split(":").filter((d) => d !== "");
+  const dirs = named.length > 0 ? named : LV2_DEFAULT_DIRS.map((d) => (d.startsWith("/") ? d : join(home, d)));
+  const bundles: string[] = [];
+  for (const dir of new Set(dirs.map((d) => resolve(d)))) {
+    let names: string[];
+    try {
+      names = readdirSync(dir);
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "ENOTDIR") continue;
+      throw e;
+    }
+    for (const n of names.sort()) if (n.endsWith(".lv2")) bundles.push(join(dir, n));
+  }
+  return bundles;
+}

package/src/measurement/cli.ts

@@ -79,8 +79,22 @@ export interface MeasureOptions {
   readonly run: boolean;
   /** Print the plan and probe nothing. */
   readonly dryRun: boolean;
+  /**
+   * The LV2 measurer's feature-option flags (`--features`, `--strict`, ...), in the order given, passed
+   * to every run of the hosting pass. Absent or empty: the measurer's defaults.
+   */
+  readonly featureFlags?: readonly string[];
 }
 
+/**
+ * The words the LV2 measurer's feature-option flags take, as `native/lv2-measure-options.c` names
+ * them: the provider's kinds (`--features`), its buf-size declarations (`--block-declares`) and its log
+ * modes (`--log`). A conformance test reads both.
+ */
+export const LV2_FEATURE_KINDS = ["map", "unmap", "options", "bounded", "worker", "default-state", "log"] as const;
+export const LV2_BLOCK_DECLARATIONS = ["bounded", "fixed", "pow2"] as const;
+export const LV2_LOG_MODES = ["silent", "route", "capture"] as const;
+
 /** One subprocess the pipeline runs, and what it leaves behind. */
 export interface PipelineStep {
   /** Stable id: `scan` / `latency-declared` / `latency-measured` / `cost` / `hosting`. */
@@ -205,6 +219,7 @@ export function buildPipeline(options: MeasureOptions, native?: HostingTools): P
         String(LV2_HOSTING_BLOCK_FRAMES),
         String(LV2_HOSTING_LIFECYCLES),
         String(LV2_HOSTING_REPEATS),
+        ...(options.featureFlags ?? []),
       ],
       perPlugin: true,
       env: { LD_PRELOAD: native.interposer, OMX_STIM: "noise" },
@@ -287,6 +302,32 @@ function parseRates(text: string): number[] | undefined {
 /** What `--dimensions` takes: the prober's, and the hosting pass's. */
 export const MEASURED_DIMENSIONS: readonly MeasurementDimension[] = [...PROBED_DIMENSIONS, ...HOSTING_PASS_DIMENSIONS];
 
+/** Whether `text` is a comma-separated list of `words` (empty: none of them). */
+function wordList(text: string, words: readonly string[]): boolean {
+  return text === "" || text.split(",").every((w) => words.includes(w));
+}
+
+/** A block length or a buffer size: a whole number of at least `min`. */
+function wholeNumber(text: string, min: number): boolean {
+  return /^\d+$/.test(text) && Number(text) >= min && Number(text) <= 2 ** 31 - 1;
+}
+
+/**
+ * What each feature-option flag takes: a check of its value, or `undefined` for a switch. The
+ * measurer checks the values again; these refuse a bad one before any plugin is run.
+ */
+const FEATURE_FLAGS: Readonly<Record<string, ((value: string) => boolean) | undefined>> = {
+  "--features": (v) => wordList(v, LV2_FEATURE_KINDS),
+  "--block-declares": (v) => wordList(v, LV2_BLOCK_DECLARATIONS),
+  "--block-min": (v) => wholeNumber(v, 0),
+  "--block-max": (v) => wholeNumber(v, 0),
+  "--block-nominal": (v) => wholeNumber(v, 0),
+  "--log": (v) => (LV2_LOG_MODES as readonly string[]).includes(v),
+  "--log-capture-bytes": (v) => wholeNumber(v, 2),
+  "--strict": undefined,
+  "--no-strict": undefined,
+};
+
 function parseDimensions(text: string): MeasurementDimension[] | undefined {
   const wanted = text.split(",").map((part) => part.trim());
   const dimensions = MEASURED_DIMENSIONS.filter((d) => wanted.includes(d));
@@ -320,6 +361,7 @@ export function parseMeasureArgs(
   let python = env.PYTHON ?? "python3";
   let run = env.LV2_MEASURE_RUN === "1";
   let dryRun = false;
+  const featureFlags: string[] = [];
 
   for (let i = 0; i < argv.length; i += 1) {
     const flag = argv[i];
@@ -403,8 +445,19 @@ export function parseMeasureArgs(
       case "--dry-run":
         dryRun = true;
         break;
-      default:
-        return { ok: false, error: `unknown argument: ${String(flag)}` };
+      default: {
+        if (flag === undefined || !Object.hasOwn(FEATURE_FLAGS, flag)) {
+          return { ok: false, error: `unknown argument: ${String(flag)}` };
+        }
+        const check = FEATURE_FLAGS[flag];
+        if (check === undefined) {
+          featureFlags.push(flag);
+          break;
+        }
+        const value = next();
+        if (value === undefined || !check(value)) return { ok: false, error: `${flag}: ${featureFlagUse(flag)}` };
+        featureFlags.push(flag, value);
+      }
     }
   }
 
@@ -414,6 +467,12 @@ export function parseMeasureArgs(
       error: "--rates is required: a measurement with no stated rate is not a measurement",
     };
   }
+  if (featureFlags.length > 0 && !dimensions.some((d) => (HOSTING_PASS_DIMENSIONS as readonly string[]).includes(d))) {
+    return {
+      ok: false,
+      error: `the feature options are the hosting pass's: ${featureFlags[0]} needs one of ${HOSTING_PASS_DIMENSIONS.join(",")}`,
+    };
+  }
   if (plugins !== undefined && dimensions.some((d) => (PROBED_DIMENSIONS as readonly string[]).includes(d))) {
     return {
       ok: false,
@@ -436,10 +495,26 @@ export function parseMeasureArgs(
       ...(plugins === undefined ? {} : { plugins }),
       ...(costCpu === undefined ? {} : { costCpu }),
       ...(label === undefined ? {} : { label }),
+      ...(featureFlags.length === 0 ? {} : { featureFlags }),
     },
   };
 }
 
+function featureFlagUse(flag: string): string {
+  switch (flag) {
+    case "--features":
+      return `a comma-separated list of ${LV2_FEATURE_KINDS.join(",")} (empty: none)`;
+    case "--block-declares":
+      return `a comma-separated list of ${LV2_BLOCK_DECLARATIONS.join(",")} (empty: none)`;
+    case "--log":
+      return `one of ${LV2_LOG_MODES.join(", ")}`;
+    case "--log-capture-bytes":
+      return "a size in bytes of at least 2";
+    default:
+      return "a number of frames, 0 for the run's block";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Progress
 // ---------------------------------------------------------------------------

package/src/pins-file.ts

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The pins file `plugin-qualify --pins <file>` writes and plugin-hostd loads (`pin_file` in its settings, or its
+ * pin store's import): one line per qualified plugin, the SAME line as hostd's `pin_set` verb, with the
+ * qualification verdict as a last word.
+ *
+ *     pin_set <uri> <path>=<sha256>[,<path>=<sha256>...] <scheme>:<sha256> [verdict=<word>]
+ *
+ * The digests and the layout are the prober's, raw (`IntegrityMeasurement`); nothing here computes a hash. A plugin
+ * whose run took no whole pin has no line: a pins file never holds a partial pin. The grammar is plugin-hostd's
+ * (`include/plugin-hostd/protocol.h`, PHD_PIN_*); `parsePinLine` reads a line back with the daemon's rules, so a
+ * writer that drifts from them is a red test and not a refused add.
+ */
+import { resolve } from "node:path";
+
+import type { RtSafetyDocument } from "./clap-qualify.js";
+import type { IntegrityMeasurement, MeasuredPlugin } from "./measurement/format.js";
+import type { QualifyVerdict } from "./qualify-cli.js";
+import type { SuitabilityRating } from "./rating.js";
+
+/** The verb the line starts with in a pins file, hostd's `PHD_VERB_PIN_SET`. */
+export const PIN_VERB = "pin_set";
+
+/** The key of the verdict word, hostd's `PHD_PIN_VERDICT_KEY`. */
+export const PIN_VERDICT_KEY = "verdict=";
+
+/** The verdict words hostd knows (`PHD_PIN_VERDICTS`). */
+export const PIN_VERDICTS = ["in-process", "isolated", "refused"] as const;
+export type PinVerdict = (typeof PIN_VERDICTS)[number];
+
+/**
+ * What a rating says about where the plugin may run, in hostd's words. `suitable` is qualified for a worker that other
+ * plugins share. `conditional` loads and is isolated. `unsuitable` is measured to fail and is `refused`. `unknown` is no
+ * opinion: no verdict word, and hostd treats the plugin as not qualified.
+ */
+export function pinVerdictOf(rating: SuitabilityRating): PinVerdict | undefined {
+  switch (rating) {
+    case "suitable":
+      return "in-process";
+    case "conditional":
+      return "isolated";
+    case "unsuitable":
+      return "refused";
+    case "unknown":
+      return undefined;
+  }
+}
+
+/** One pin: what hostd's `pin_set` takes, and the verdict of the run that took it. */
+export interface PinEntry {
+  /** hostd's uri: `clap:<path of the .clap>#<id>`, or an LV2 plugin's own URI. */
+  readonly uri: string;
+  readonly integrity: IntegrityMeasurement;
+  readonly verdict?: PinVerdict;
+}
+
+/** The line of one pin, or `undefined` when the integrity block is not a whole pin. A uri with whitespace in it would be read back as more words: it is refused, by name. */
+export function pinLine(entry: PinEntry): string | undefined {
+  const spaced = [entry.uri, ...(entry.integrity.files ?? []).map((f) => f.path)].find((w) => /\s/.test(w));
+  if (spaced !== undefined) {
+    throw new Error(`${entry.uri}: ${JSON.stringify(spaced)} has whitespace in it and cannot be a word of a pin line`);
+  }
+  const { files, layout } = entry.integrity;
+  if (files === undefined || files.length === 0 || layout === undefined) return undefined;
+  const list = files.map((f) => `${f.path}=${f.sha256}`).join(",");
+  const verdict = entry.verdict === undefined ? "" : ` ${PIN_VERDICT_KEY}${entry.verdict}`;
+  return `${PIN_VERB} ${entry.uri} ${list} ${layout.scheme}:${layout.sha256}${verdict}`;
+}
+
+/** hostd's uri of a CLAP plugin the prober loaded: its file as it was handed, made absolute, and its id. */
+export function clapPinUri(binaryPath: string, pluginUri: string): string {
+  const id = pluginUri.startsWith("urn:clap:") ? pluginUri.slice("urn:clap:".length) : pluginUri;
+  return `clap:${resolve(binaryPath)}#${id}`;
+}
+
+/** What went into a pins file and what did not. */
+export interface PinsFile {
+  readonly text: string;
+  /** The uris written. */
+  readonly written: readonly string[];
+  /** The uris of plugins that took no whole pin: they have no line. */
+  readonly skipped: readonly string[];
+  /** The uris refused because a word of their line has whitespace in it, each with the reason: they have no line. */
+  readonly refused: readonly { readonly uri: string; readonly problem: string }[];
+}
+
+/**
+ * The file: a comment that says where it came from, then one line per plugin, sorted by uri. A uri given twice keeps
+ * the entry whose verdict is the worse one (`refused` over `isolated` over `in-process`, no word over all), so a
+ * plugin found twice is never pinned more kindly than its worst measurement.
+ */
+export function pinsFile(entries: readonly PinEntry[]): PinsFile {
+  const byUri = new Map<string, string>();
+  const verdictOf = new Map<string, PinVerdict | undefined>();
+  const skipped: string[] = [];
+  const refused: { uri: string; problem: string }[] = [];
+  const rank = (v: PinVerdict | undefined): number => (v === undefined ? 4 : { "in-process": 1, isolated: 2, refused: 3 }[v]);
+  for (const entry of entries) {
+    let line: string | undefined;
+    try {
+      line = pinLine(entry);
+    } catch (e) {
+      refused.push({ uri: entry.uri, problem: (e as Error).message });
+      continue;
+    }
+    if (line === undefined) {
+      skipped.push(entry.uri);
+      continue;
+    }
+    if (byUri.has(entry.uri) && rank(verdictOf.get(entry.uri)) >= rank(entry.verdict)) continue;
+    byUri.set(entry.uri, line);
+    verdictOf.set(entry.uri, entry.verdict);
+  }
+  const uris = [...byUri.keys()].sort();
+  const text = [
+    "# written by plugin-qualify --pins; plugin-hostd reads it with pin_file",
+    ...uris.map((u) => byUri.get(u)!),
+    "",
+  ].join("\n");
+  return { text, written: uris, skipped: skipped.filter((u) => !byUri.has(u)), refused };
+}
+
+/**
+ * The entries of a CLAP pass for one host: each document of that host's profile with its pin and the verdict its
+ * rating says. The documents of other profiles are ignored; a pins file is for one host.
+ */
+export function clapPinEntries(documents: readonly RtSafetyDocument[], host: string): PinEntry[] {
+  return documents
+    .filter((d) => d.console === host)
+    .map((d) => {
+      const verdict = pinVerdictOf(d.verdict.rating);
+      return {
+        uri: clapPinUri(d.plugin.binary.path, d.plugin.uri),
+        integrity: d.measured.integrity,
+        ...(verdict === undefined ? {} : { verdict }),
+      };
+    });
+}
+
+/**
+ * The entries of an LV2 run: each measured plugin with a pin and the verdict row of that host. A plugin with no verdict
+ * row for the host is pinned without a verdict word.
+ */
+export function measuredPinEntries(
+  plugins: readonly MeasuredPlugin[],
+  verdicts: readonly QualifyVerdict[],
+  host: string,
+): PinEntry[] {
+  return plugins.flatMap((p) => {
+    if (p.integrity === undefined) return [];
+    const row = verdicts.find((v) => v.uri === p.uri && v.host === host);
+    const verdict = row === undefined || !row.measured ? undefined : pinVerdictOf(row.rating);
+    return [{ uri: p.uri, integrity: p.integrity, ...(verdict === undefined ? {} : { verdict }) }];
+  });
+}
+
+/** A line read back with hostd's rules. */
+export interface ParsedPin {
+  readonly uri: string;
+  readonly files: readonly { readonly path: string; readonly sha256: string }[];
+  readonly layout: { readonly scheme: string; readonly sha256: string };
+  readonly verdict?: PinVerdict;
+}
+
+const HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * hostd's grammar for a pin line, the verb optional; `undefined` for a blank or comment line, and a thrown Error for a
+ * line the daemon would refuse (a path holding a separator, a path that climbs out of the bundle, a digest that is not
+ * 64 lowercase hex digits, a layout without a scheme, a verdict outside the vocabulary, a path named twice).
+ */
+export function parsePinLine(line: string): ParsedPin | undefined {
+  const words = line.trim().split(/\s+/).filter((w) => w !== "");
+  if (words.length === 0 || words[0]!.startsWith("#")) return undefined;
+  if (words[0] === PIN_VERB) words.shift();
+  if (words.length !== 3 && words.length !== 4) throw new Error(`a pin line has 3 or 4 words, not ${words.length}`);
+  const [uri, list, layout, verdictWord] = words as [string, string, string, string | undefined];
+  const files = list.split(",").map((item) => {
+    const eq = item.lastIndexOf("=");
+    if (eq < 0) throw new Error(`${item}: no =`);
+    const path = item.slice(0, eq);
+    const sha256 = item.slice(eq + 1);
+    if (path === "" || path.startsWith("/") || path.split("/").some((part) => part === "" || part === "..")) {
+      throw new Error(`${path}: not a path inside the bundle`);
+    }
+    if (!HEX.test(sha256)) throw new Error(`${path}: not a sha256`);
+    return { path, sha256 };
+  });
+  if (new Set(files.map((f) => f.path)).size !== files.length) throw new Error("a path is named twice");
+  const colon = layout.lastIndexOf(":");
+  if (colon <= 0 || !HEX.test(layout.slice(colon + 1))) throw new Error(`${layout}: not a layout pin`);
+  let verdict: PinVerdict | undefined;
+  if (verdictWord !== undefined) {
+    const word = verdictWord.startsWith(PIN_VERDICT_KEY) ? verdictWord.slice(PIN_VERDICT_KEY.length) : "";
+    if (!(PIN_VERDICTS as readonly string[]).includes(word)) throw new Error(`${verdictWord}: not a verdict`);
+    verdict = word as PinVerdict;
+  }
+  return { uri, files, layout: { scheme: layout.slice(0, colon), sha256: layout.slice(colon + 1) }, ...(verdict === undefined ? {} : { verdict }) };
+}

package/src/qualify-cli.ts

@@ -27,6 +27,8 @@ export interface QualifyArgs {
   readonly rates: readonly number[];
   readonly quanta: readonly number[];
   readonly out?: string;
+  /** `--pins`: where the pins file is written. */
+  readonly pins?: string;
   readonly format: OutputFormat;
   readonly isolate: boolean;
   readonly hostSweep: boolean;
@@ -83,6 +85,8 @@ export function parseQualifyArgs(argv: readonly string[]): ParseResult {
     return { ok: false, error: `--format must be one of ${OUTPUT_FORMATS.join(", ")}` };
   }
   const out = seen.get("--out") as string | undefined;
+  const pins = seen.get("--pins") as string | undefined;
+  if (pins !== undefined && pins.startsWith("--")) return { ok: false, error: "--pins needs a file name" };
   const hostProfiles = [...new Set(profileSpecs.length > 0 ? profileSpecs : [defaultOf("--host-profile")])];
   return {
     ok: true,
@@ -92,6 +96,7 @@ export function parseQualifyArgs(argv: readonly string[]): ParseResult {
       rates,
       quanta,
       ...(out === undefined ? {} : { out }),
+      ...(pins === undefined ? {} : { pins }),
       format: format as OutputFormat,
       isolate: seen.has("--isolate"),
       hostSweep: !seen.has("--no-host-sweep"),
@@ -111,7 +116,9 @@ export function helpText(): string {
     "plugin-qualify — qualify audio plugins for real-time hosting",
     "",
     "  plugin-qualify <uri|bundle-path>...   exactly the named plugins; a .lv2 bundle = every plugin in it",
-    "  plugin-qualify --all                  every plugin lilv finds (LV2_PATH honoured)",
+    "  plugin-qualify --all                  every CLAP plugin on CLAP_PATH, then ~/.clap, then /usr/lib/clap;",
+    "                                        refuses (exit 2) when LV2 bundles are on the LV2 path (LV2_PATH),",
+    "                                        which this entry point cannot measure",
     "",
     ...rows,
     "",

package/src/qualify-declarations.ts

@@ -69,6 +69,15 @@ export const SOAK_CALIBRATION_S = 30;
 export const CLAP_SCAN_TOOL_ENV = "OMX_CLAP_SCAN";
 export const CLAP_SCAN_TOOL_DEFAULT = "omx-clap-scan";
 
+/**
+ * The standard CLAP search path `--all` walks, in this order: every directory `CLAP_PATH` names
+ * (colon-separated), then `~/.clap`, then `/usr/lib/clap`. The system directory is the same on
+ * every distribution and architecture; it is never the library directory (`/usr/lib64`).
+ */
+export const CLAP_PATH_ENV = "CLAP_PATH";
+export const CLAP_USER_DIR = ".clap";
+export const CLAP_SYSTEM_DIR = "/usr/lib/clap";
+
 /** Seconds one run of the CLAP scanner may take over everything it was pointed at. */
 export const CLAP_SCAN_TIMEOUT_S = 300;
 

package/src/qualify-options.ts

@@ -32,7 +32,7 @@ export interface QualifyOption {
 }
 
 export const QUALIFY_OPTIONS: readonly QualifyOption[] = [
-  { flag: "--all", describe: "every plugin lilv finds (LV2_PATH honoured)" },
+  { flag: "--all", describe: "every CLAP plugin on the CLAP search path; refuses when LV2 bundles are on the LV2 path" },
   { flag: "--rates", value: "list", describe: "sample rates to measure at, comma-separated", default: QUALIFY_RATES.join(",") },
   { flag: "--quanta", value: "list", describe: "quanta (frames) to rate cost at, comma-separated", default: QUALIFY_QUANTA.join(",") },
   { flag: "--out", value: "dir", describe: "write one interchange JSON document per run into this directory" },
@@ -45,5 +45,11 @@ export const QUALIFY_OPTIONS: readonly QualifyOption[] = [
     describe: `judge against this host (${HOST_PROFILES.map((p) => p.id).join(", ")}, or a profile JSON file); repeat or comma-separate for one verdict per profile`,
     default: OPENMIXER_CONSOLE_PROFILE.id,
   },
+  {
+    flag: "--pins",
+    value: "file",
+    describe:
+      "write one pin per qualified plugin to this file, with its verdict, for plugin-hostd's pin_file (the verdict is the first host profile's)",
+  },
   { flag: "--help", describe: "this text" },
 ];

package/tools/lv2-measure.mjs

@@ -85,6 +85,22 @@ const HELP = `${TOOL_NAME} ${TOOL_VERSION} — measure LV2 plugin latency and CP
   --dry-run               Print the plan and probe nothing.
   --progress-json         Emit machine-readable progress on stderr, one '@progress {...}' per line.
   --help                  This text.
+
+The hosting pass's host features are omx-clap-core's LV2 feature provider; each of its options is
+a flag, passed to every run of lv2_measure and named in each plugin's record (featureOptions):
+
+  --features LIST         Kinds offered: map,unmap,options,bounded,worker,default-state,log
+                          (default: all but default-state; empty: none).
+  --strict                Refuse a plugin requiring a feature not offered, naming it (refusedFeature).
+  --no-strict             Hand it to its own instantiate without it (default).
+  --block-declares LIST   Buf-size declarations when bounded is offered: bounded,fixed,pow2
+                          (default: bounded; empty: none).
+  --block-min N           bufsz:minBlockLength (default: 1; 0: the run's block).
+  --block-max N           bufsz:maxBlockLength (default: 0, the run's block).
+  --block-nominal N       bufsz:nominalBlockLength (default: 0, the maximum).
+  --log MODE              log:log lines: silent, route (to stderr) or capture (into the record)
+                          (default: silent).
+  --log-capture-bytes N   The capture buffer, its NUL included (default: 4096).
 `;
 
 function fail(message, code = 2) {