@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/tools/gen-python-declarations.d.mts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/** The generated `tools/_declarations.py` body, from `src/qualify-declarations.ts`. */
+export function declarationsFile(decl?: Readonly<Record<string, unknown>>): string;

package/tools/gen-python-declarations.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/*
+ * gen-python-declarations.mjs — `tools/_declarations.py`, generated from the package's ONE
+ * declarations module, `src/qualify-declarations.ts`.
+ * `benchmark.py`'s `DEFAULT_BLOCK`, `DEFAULT_RATES` and timeouts are these facts under its own names.
+ *
+ * `benchmark.py` cannot import a TS module — that scan's own comment already names the mirror as
+ * "known" — so this is the `omx_contract_limits.h` shape in its cheapest form: a file emitted on
+ * demand, committed, and checked byte-identical rather than hand-typed twice.
+ *
+ * Usage:
+ *   node tools/gen-python-declarations.mjs --check   # exit 1 if the committed file is stale
+ *   node tools/gen-python-declarations.mjs --write   # (re)write the committed file
+ *   node tools/gen-python-declarations.mjs --emit-stdout   # print it (R-094's cross-language arm)
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const OUT = join(PKG, 'tools/_declarations.py');
+
+const D = await import(join(PKG, 'dist/qualify-declarations.js'));
+
+/** The declarations the Python tools read, in the order the file states them. */
+const PY_NAMES = [
+  'COST_REFERENCE_RATE',
+  'QUANTUM_FRAMES',
+  'MEASURE_BASE_RATE',
+  'OPERATIONAL_RATE_FLOOR',
+  'QUALIFY_RATES',
+  'QUALIFY_QUANTA',
+  'PLUGIN_TIMEOUT_S',
+  'BOOT_TIMEOUT_S',
+  'COST_TIMEOUT_S',
+];
+
+const py = (v) => (Array.isArray(v) ? `(${v.join(', ')})` : String(v));
+
+/** `decl` defaults to the built declarations; a test passes moved ones to prove the Python side follows. */
+export function declarationsFile(decl = D) {
+  return (
+    `# SPDX-License-Identifier: GPL-3.0-or-later\n` +
+    `# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>\n` +
+    `#\n` +
+    `# GENERATED by tools/gen-python-declarations.mjs — do not hand-edit.\n` +
+    `#\n` +
+    `# Source: src/qualify-declarations.ts. The Python tools cannot import a TS module, so this file\n` +
+    `# stands in for that import: regenerated and checked byte-identical instead of a second,\n` +
+    `# hand-typed copy of the figures (2026-09-17 declare-derive audit, F8).\n` +
+    `#\n` +
+    `# Regenerate: node tools/gen-python-declarations.mjs --write\n` +
+    `# Verify:     node tools/gen-python-declarations.mjs --check\n` +
+    `\n` +
+    PY_NAMES.map((n) => `${n} = ${py(decl[n])}\n`).join('')
+  );
+}
+
+function main() {
+  const mode = process.argv[2];
+  const content = declarationsFile();
+  if (mode === '--emit-stdout') {
+    process.stdout.write(content);
+    return;
+  }
+  if (mode === '--check') {
+    let onDisk;
+    try {
+      onDisk = readFileSync(OUT, 'utf8');
+    } catch (err) {
+      console.error(`gen-python-declarations: cannot read ${OUT}: ${err.message}`);
+      process.exit(1);
+    }
+    if (onDisk !== content) {
+      console.error(`gen-python-declarations: ${OUT} is stale — run with --write`);
+      process.exit(1);
+    }
+    console.log('gen-python-declarations: up to date');
+    return;
+  }
+  if (mode === '--write') {
+    writeFileSync(OUT, content);
+    console.log(`gen-python-declarations: wrote ${OUT}`);
+    return;
+  }
+  console.error('usage: node tools/gen-python-declarations.mjs --check|--write|--emit-stdout');
+  process.exit(2);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();

package/tools/hosting-sweep.mjs

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The hosting sweep directory → ONE interchange document. Shared by `curate.mjs --hosting-sweep`
+ * (which writes it into `data/hosting-measurements.json`) and `hosting-report.mjs` (which lands it
+ * in memory before it classifies), so the report and the served catalog read the sweep through
+ * the same reader and the same door.
+ *
+ * The directory carries its own run record, `sweep-run.json`: who measured, on what, when, and
+ * which JSONL file is which pass. A figure without its conditions is not a measurement.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  buildMeasurementDocument,
+  buildRun,
+  measuredPluginsFromSweep,
+  parseJsonl,
+} from '../dist/measurement/index.js';
+
+/** The dimensions a hosting sweep covers. */
+export const HOSTING_DIMENSIONS = ['stability', 'rtSafety', 'features'];
+
+/**
+ * Read `<dir>/sweep-run.json` and the passes it names, and build the document.
+ * Throws when the run record or the measurements pass is missing — no default run, no guessed file.
+ */
+export function hostingSweepDocument(dir) {
+  const run = JSON.parse(readFileSync(join(dir, 'sweep-run.json'), 'utf8'));
+  const passes = run.passes ?? {};
+  if (!passes.measurements) throw new Error(`${dir}/sweep-run.json names no measurements pass`);
+  const read = (name) => (name ? parseJsonl(readFileSync(join(dir, name), 'utf8')) : undefined);
+  const plugins = measuredPluginsFromSweep({
+    measurements: read(passes.measurements),
+    lifecycle: read(passes.lifecycle),
+    soak: read(passes.soak),
+  });
+  return buildMeasurementDocument(
+    buildRun({
+      id: run.id,
+      measuredAt: run.measuredAt,
+      dimensions: HOSTING_DIMENSIONS,
+      rates: run.rates,
+      tool: run.tool,
+      host: run.host,
+      ...(run.label ? { label: run.label } : {}),
+    }),
+    plugins,
+  );
+}

package/tools/lv2-measure.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `lv2-measure` — measure the LV2 plugins on THIS machine and write a versioned
+ * measurement document.
+ *
+ * Standalone by construction: it needs `python3` with the `lilv` bindings, the two probers
+ * next to this file (`scan.py`, `benchmark.py`), and an LV2 world to look at. It does not
+ * need the OpenMixer engine, its server, PipeWire, JACK, an audio interface, or root. Nothing
+ * it writes is openmixer-shaped — the output is the interchange format described in
+ * `src/measurement/format.ts`, which any LV2 host can read.
+ *
+ * This file is deliberately thin. Every decision — argument parsing, the pass order, the
+ * progress heuristic, the assembly of the document — lives in `src/measurement/cli.ts` and
+ * is unit-tested there without probing anything. What is left here is spawning processes and
+ * moving bytes, which is the part that cannot be tested without 958 real plugins.
+ *
+ * ## Usage
+ *
+ * ```sh
+ * pnpm build                       # this shell reads the compiled dist/
+ * node tools/lv2-measure.mjs --rates 48000,96000 --out measurements.json --run
+ * node tools/lv2-measure.mjs --rates 48000 --dimensions latency --dry-run
+ * ```
+ *
+ * `--run` (or `LV2_MEASURE_RUN=1`) is required to probe: the passes instantiate and execute
+ * every plugin on the machine, which is CPU-heavy and occasionally fatal to the probe worker.
+ * `--dry-run` prints the plan and touches nothing.
+ *
+ * ## Machine-readable progress
+ *
+ * With `--progress-json`, one JSON object per line is written to stderr, each prefixed
+ * `@progress `. A supervising process (the OpenMixer console's Setup screen) parses those and
+ * ignores everything else, so the human log stays readable.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  advanceProgress,
+  assembleDocument,
+  buildPipeline,
+  collectHostFacts,
+  INITIAL_PROGRESS,
+  parseMeasureArgs,
+  parseProbeProgress,
+  serialiseMeasurementDocument,
+  TOOL_NAME,
+  TOOL_VERSION,
+} from "../dist/measurement/index.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `${TOOL_NAME} ${TOOL_VERSION} — measure LV2 plugin latency and CPU cost on this machine.
+
+  --rates 48000,96000     REQUIRED. Sample rates to measure at. There is no default:
+                          a figure without a stated rate is not a measurement.
+  --dimensions latency,cost
+                          What to measure (default: both).
+  --out PATH              Where the document goes (default: stdout).
+  --scan PATH             Reuse an existing prober scan instead of scanning.
+  --work-dir PATH         Where intermediates go (default: alongside --out, or a temp dir).
+  --tool-dir PATH         Where scan.py / benchmark.py live (default: next to this file).
+  --python BIN            Python interpreter (default: $PYTHON or python3).
+  --sweep                 Also sweep latency-bearing controls (finds parameter-dependent latency).
+  --cost-cpu N            Pin the cost pass to core N.
+  --label TEXT            A note recorded with the run.
+  --run                   Required to probe. Instantiates and runs every plugin.
+  --dry-run               Print the plan and probe nothing.
+  --progress-json         Emit machine-readable progress on stderr, one '@progress {...}' per line.
+  --help                  This text.
+`;
+
+function fail(message, code = 2) {
+  process.stderr.write(`${TOOL_NAME}: ${message}\n`);
+  process.exit(code);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+/** Run one pipeline step, forwarding its stderr and counting the plugins it reports. */
+function runStep(step, onProgress) {
+  return new Promise((settle, reject) => {
+    const child = spawn(step.command, [...step.args], { stdio: ["ignore", "inherit", "pipe"] });
+    let pending = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      pending += chunk;
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+      for (const line of lines) {
+        process.stderr.write(`${line}\n`);
+        const progress = parseProbeProgress(line);
+        if (progress !== undefined) onProgress(step, progress);
+      }
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (pending.length > 0) process.stderr.write(`${pending}\n`);
+      if (code === 0) settle();
+      else reject(new Error(`${step.id} exited ${code}`));
+    });
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const progressJson = argv.includes("--progress-json");
+  const parsed = parseMeasureArgs(
+    argv.filter((a) => a !== "--progress-json"),
+    process.env,
+    { toolDir: HERE, workDir: join(process.cwd(), ".lv2-measure") },
+  );
+  if (!parsed.ok) fail(`${parsed.error}\n\n${HELP}`);
+  const options = parsed.options;
+
+  const pipeline = buildPipeline(options);
+
+  if (options.dryRun) {
+    process.stderr.write(
+      `${TOOL_NAME} would measure ${options.dimensions.join(" + ")} at ${options.rates.join(", ")} Hz\n`,
+    );
+    for (const step of pipeline.steps) {
+      process.stderr.write(`  ${step.id}: ${step.command} ${step.args.join(" ")}\n`);
+    }
+    return;
+  }
+  if (!options.run) {
+    fail("refusing to probe without --run (or LV2_MEASURE_RUN=1): this instantiates and runs every LV2 plugin on this machine");
+  }
+
+  mkdirSync(options.workDir, { recursive: true });
+  // Only the FIRST step's input can be checked up front — every later step reads what the
+  // one before it wrote, and a missing intermediate is a failed step, reported as one.
+  if (options.scanPath !== undefined && !existsSync(options.scanPath)) {
+    fail(`--scan: no such file: ${options.scanPath}`);
+  }
+
+  // Progress is advisory: the phase banner supplies the denominator, the indented result
+  // lines supply the numerator. A prober whose log we cannot parse simply stalls the bar.
+  let phase = INITIAL_PROGRESS;
+  const emit = (event) => {
+    if (progressJson) process.stderr.write(`@progress ${JSON.stringify(event)}\n`);
+  };
+  const onProgress = (step, progress) => {
+    const next = advanceProgress(phase, progress);
+    if (next === phase) return; // clamped: the phase's own summary lines are not plugins
+    phase = next;
+    emit({ step: step.id, dimension: step.dimension ?? null, ...phase });
+  };
+
+  const startedAt = Date.now();
+  const measuredAt = new Date().toISOString();
+  emit({ step: "start", steps: pipeline.steps.map((s) => s.id) });
+  for (const step of pipeline.steps) {
+    process.stderr.write(`== ${step.id}\n`);
+    await runStep(step, onProgress);
+  }
+  const elapsedSeconds = (Date.now() - startedAt) / 1000;
+
+  const document = assembleDocument({
+    options,
+    catalog: readJson(pipeline.finalCatalog),
+    costProvenance:
+      pipeline.costProvenance !== undefined && existsSync(pipeline.costProvenance)
+        ? readJson(pipeline.costProvenance)
+        : undefined,
+    host: collectHostFacts({
+      // Both false and recorded as such: this tool deliberately requires no privileges, so
+      // claiming otherwise would make its figures look better conditioned than they are.
+      realtimePriority: false,
+      memoryLocked: false,
+      ...(options.costCpu === undefined ? {} : { pinnedCpu: options.costCpu }),
+    }),
+    runId: `${hostname()}-${measuredAt}`,
+    measuredAt,
+    elapsedSeconds,
+  });
+
+  const serialised = serialiseMeasurementDocument(document);
+  if (options.outPath === undefined) process.stdout.write(serialised);
+  else writeFileSync(resolve(options.outPath), serialised);
+
+  const measured = document.plugins.filter(
+    (p) => Object.keys(p.latency?.perRate ?? {}).length > 0 || Object.keys(p.cost?.perRate ?? {}).length > 0,
+  ).length;
+  process.stderr.write(
+    `${TOOL_NAME}: ${document.plugins.length} plugin(s), ${measured} with at least one figure, ` +
+      `${elapsedSeconds.toFixed(1)} s -> ${options.outPath ?? "stdout"}\n`,
+  );
+  emit({ step: "done", plugins: document.plugins.length, measured, elapsedSeconds });
+}
+
+main().catch((err) => fail(err instanceof Error ? err.message : String(err), 1));

package/tools/lv2_presets.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+"""
+The presets an LV2 plugin SHIPS, read off its bundle with lilv.
+
+A preset is a `pset:Preset` resource related to the plugin (`plugin.get_related`). For each one
+this reads its label, its bank, the port values it sets and whether it carries a `state:state`
+body, and judges it against the plugin's own descriptor params:
+
+- `carries`: "params" (port values, no state body), "params+state" (both), "state" (a body only);
+- `values`: the values for the plugin's PARAMETERS. A value for a port the plugin has but no
+  host sets — an output meter, a hidden (`notOnGUI`) or designated port, which hosts that save
+  presets often record — is left out: it is not a parameter, and it is not an error either;
+- `invalid`: "UNKNOWN_SYMBOL" when a value names a symbol that is no port of the plugin at all,
+  "OUT_OF_TRAVEL" when a value lies outside that param's [min, max]. An invalid preset stays
+  listed — refuse or report, never drop.
+
+Only the bundles lilv loads from LV2_PATH are read, which is what the scan reads: the presets a
+plugin ships, never one another host saved in a user's home (ruling 2). The output is sorted by
+preset URI and the values by symbol, so the same install yields the same bytes.
+"""
+
+import struct
+
+PSET = "http://lv2plug.in/ns/ext/presets#"
+STATE = "http://lv2plug.in/ns/ext/state#"
+LV2 = "http://lv2plug.in/ns/lv2core#"
+RDFS = "http://www.w3.org/2000/01/rdf-schema#"
+
+
+def as_float(node):
+    """A preset value node as a float — the TTL LITERAL, or None when it is not a number.
+
+    The literal first: lilv's float() goes through a C float, so "0.478000" comes back as
+    0.4779999852..., and a host's param_get ("%f", 0.478000) would then read as an edit nobody
+    made the moment the preset loaded.
+    """
+    if node is None:
+        return None
+    try:
+        return float(str(node))
+    except (ValueError, TypeError):
+        try:
+            return float(node)
+        except (ValueError, TypeError):
+            return None
+
+
+def carries_of(values, has_state):
+    """What a preset sets — the three words of the spec, from what the TTL holds."""
+    if has_state and values:
+        return "params+state"
+    if has_state:
+        return "state"
+    return "params"
+
+
+def invalid_of(values, params):
+    """The first reason a preset can never be loaded against `params`, or None.
+
+    `params` are the descriptor's CONTROL params (symbol, min, max). A symbol the descriptor does
+    not carry is checked before the travel: a value for a port that does not exist has no travel.
+    """
+    by_symbol = {p["symbol"]: p for p in params if p.get("kind", "control") == "control"}
+    for v in values:
+        if v["symbol"] not in by_symbol:
+            return "UNKNOWN_SYMBOL"
+    for v in values:
+        p = by_symbol[v["symbol"]]
+        lo, hi = p.get("min"), p.get("max")
+        # The travel's ends were scanned through a C float (lilv), the value is the TTL literal:
+        # compare at the port's own precision, or "0.707" sits below its own min of "0.707".
+        value = as_port_float(v["value"])
+        if lo is not None and value < lo:
+            return "OUT_OF_TRAVEL"
+        if hi is not None and value > hi:
+            return "OUT_OF_TRAVEL"
+    return None
+
+
+def as_port_float(value):
+    """`value` rounded to the C float an LV2 control port holds."""
+    return struct.unpack("f", struct.pack("f", value))[0]
+
+
+def preset_entry(uri, name, bank, values, has_state, params, port_symbols=frozenset()):
+    """One descriptor `presets[]` entry, with absent fields left out rather than null.
+
+    `port_symbols` are every port of the plugin; a value for one of them that is not a control
+    PARAM is dropped (see the module header), any other unknown symbol keeps the preset invalid.
+    """
+    controls = {p["symbol"] for p in params if p.get("kind", "control") == "control"}
+    values = sorted((v for v in values if v["symbol"] in controls or v["symbol"] not in port_symbols),
+                    key=lambda v: v["symbol"])
+    out = {"uri": uri, "name": name}
+    if bank:
+        out["bank"] = bank
+    out["carries"] = carries_of(values, has_state)
+    if values:
+        out["values"] = values
+    reason = invalid_of(values, params)
+    if reason:
+        out["invalid"] = reason
+    return out
+
+
+def read_presets(world, plugin, params):
+    """Every preset `plugin` ships, as descriptor entries sorted by URI."""
+    uri = world.new_uri
+    port_symbols = frozenset(str(plugin.get_port_by_index(i).get_symbol())
+                             for i in range(plugin.get_num_ports()))
+    related = plugin.get_related(uri(PSET + "Preset"))
+    out = []
+    for node in (related if related is not None else []):
+        world.load_resource(node)
+        label = world.get(node, uri(RDFS + "label"), None)
+        bank_node = world.get(node, uri(PSET + "bank"), None)
+        bank = None
+        if bank_node is not None:
+            bank_label = world.get(bank_node, uri(RDFS + "label"), None)
+            bank = str(bank_label) if bank_label is not None else None
+        values = []
+        for port in (world.find_nodes(node, uri(LV2 + "port"), None) or []):
+            symbol = world.get(port, uri(LV2 + "symbol"), None)
+            value = as_float(world.get(port, uri(PSET + "value"), None))
+            if symbol is not None and value is not None:
+                values.append({"symbol": str(symbol), "value": value})
+        has_state = world.get(node, uri(STATE + "state"), None) is not None
+        name = str(label) if label is not None else str(node)
+        out.append(preset_entry(str(node), name, bank, values, has_state, params, port_symbols))
+    out.sort(key=lambda p: p["uri"])
+    return out