@openmixer/plugin-qualify 0.0.0-stage → 0.4.1

package/dist/measurement/provenance.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Where a run happened, and under what settings — assembled from what the machine will
+ * actually tell us.
+ *
+ * The discipline this module enforces is the one `data/CPU_COST_PROVENANCE.md` states in
+ * prose: *"realtime priority / mlock — no, both need privileges the benchmark must not
+ * require; recorded as `false` rather than assumed."* Every fact here is READ at run time
+ * or omitted. Nothing is defaulted, nothing is inferred from the platform, and a `/sys`
+ * file that will not open produces an absent field rather than a plausible value.
+ *
+ * The two `false`s are the exception and they are required fields: `realtimePriority` and
+ * `memoryLocked` say "we did not run with this", which is a finding a comparison needs,
+ * and leaving them absent would let a reader assume the good case.
+ */
+import type { CostMethod, LatencyMethod, MeasurementHost, MeasurementRun } from "./format.js";
+import { type MeasurementDimension } from "./vocabulary.js";
+/** The machine facts this module reads, injectable so the collector is testable. */
+export interface HostProbes {
+    hostname(): string;
+    kernelRelease(): string;
+    osName(): string;
+    cpuModel(): string | undefined;
+    cpuCount(): number;
+    /** Contents of a `/sys` or `/proc` file, or `undefined` when it cannot be read. */
+    readSystemFile(path: string): string | undefined;
+}
+/** The real machine. */
+export declare const SYSTEM_HOST_PROBES: HostProbes;
+/** Facts the caller knows that the machine cannot be asked for. */
+export interface HostFactInput {
+    /** The core the prober pinned to, when it pinned. */
+    readonly pinnedCpu?: number;
+    /** Whether the prober ran with realtime scheduling — a claim the caller must make. */
+    readonly realtimePriority: boolean;
+    /** Whether the prober's pages were locked. */
+    readonly memoryLocked: boolean;
+    /** Versions of what did the probing, e.g. `{ python: "3.14.6" }`. */
+    readonly toolchain?: Readonly<Record<string, string>>;
+}
+/**
+ * Read the governor, the max frequency and the turbo state for a core, plus the CPU model
+ * and count. Any file that will not open yields an absent field.
+ *
+ * `pinnedCpuKind` deliberately reports what the kernel exposes rather than a classification
+ * of our own: on a hybrid CPU the two `cpuinfo_max_freq` populations are what distinguishes
+ * a performance core from an efficiency one, so the frequency IS the evidence and the label
+ * is only offered when the split is unambiguous.
+ */
+export declare function collectHostFacts(input: HostFactInput, probes?: HostProbes): MeasurementHost;
+/**
+ * The host block from `benchmark.py --cost-provenance`'s JSON, or `undefined`.
+ *
+ * That file is the model this format generalises, so the mapping is mostly renaming. The
+ * one judgement: its `realtimePriority` / `memoryLocked` are already explicit booleans, and
+ * a file that omits them is treated as not having run privileged — the safe reading, and
+ * the one that matches what the prober can actually do without privileges.
+ */
+export declare function hostFromProbeProvenance(value: unknown): MeasurementHost | undefined;
+/** The cost method block from `benchmark.py --cost-provenance`'s JSON, or `undefined`. */
+export declare function costMethodFromProbeProvenance(value: unknown): CostMethod | undefined;
+/** The caveat that rides on every run carrying cost figures. */
+export declare const RELATIVE_RANKING_NOTE: string;
+/** The caveat on a run carrying only latency figures — portable, but not unconditionally. */
+export declare const LATENCY_ONLY_NOTE: string;
+/** The caveat on a run carrying the hosting dimensions — survival, RT-safety, features. */
+export declare const HOSTING_NOTE: string;
+/** Everything {@link buildRun} needs that is not read off the machine. */
+export interface RunInput {
+    readonly id: string;
+    readonly measuredAt: string;
+    readonly dimensions: readonly MeasurementDimension[];
+    readonly rates: readonly number[];
+    readonly tool: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly host: MeasurementHost;
+    readonly latencyMethod?: LatencyMethod;
+    readonly costMethod?: CostMethod;
+    readonly elapsedSeconds?: number;
+    readonly label?: string;
+}
+/**
+ * Assemble a run record.
+ *
+ * `relativeRankingOnly` is derived, not passed: it is true exactly when the run carries cost
+ * figures, and letting a caller set it would let a caller unset it. The note follows the
+ * same rule — a latency-only run gets the version caveat, a cost run gets the machine one,
+ * and a run carrying both gets both, because both apply.
+ */
+export declare function buildRun(input: RunInput): MeasurementRun;

package/dist/measurement/provenance.js

@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * Where a run happened, and under what settings — assembled from what the machine will
+ * actually tell us.
+ *
+ * The discipline this module enforces is the one `data/CPU_COST_PROVENANCE.md` states in
+ * prose: *"realtime priority / mlock — no, both need privileges the benchmark must not
+ * require; recorded as `false` rather than assumed."* Every fact here is READ at run time
+ * or omitted. Nothing is defaulted, nothing is inferred from the platform, and a `/sys`
+ * file that will not open produces an absent field rather than a plausible value.
+ *
+ * The two `false`s are the exception and they are required fields: `realtimePriority` and
+ * `memoryLocked` say "we did not run with this", which is a finding a comparison needs,
+ * and leaving them absent would let a reader assume the good case.
+ */
+import { hostname as osHostname, cpus as osCpus, release as osRelease, type as osType } from "node:os";
+import { readFileSync } from "node:fs";
+import { booleanValue, finiteNumber, isRecord, nonEmptyString, optional } from "./guards.js";
+import { MEASUREMENT_DIMENSIONS } from "./vocabulary.js";
+/** The real machine. */
+export const SYSTEM_HOST_PROBES = {
+    hostname: () => osHostname(),
+    kernelRelease: () => osRelease(),
+    osName: () => osType(),
+    cpuModel: () => osCpus()[0]?.model,
+    cpuCount: () => osCpus().length,
+    readSystemFile: (path) => {
+        try {
+            return readFileSync(path, "utf8").trim();
+        }
+        catch {
+            return undefined;
+        }
+    },
+};
+/**
+ * Read the governor, the max frequency and the turbo state for a core, plus the CPU model
+ * and count. Any file that will not open yields an absent field.
+ *
+ * `pinnedCpuKind` deliberately reports what the kernel exposes rather than a classification
+ * of our own: on a hybrid CPU the two `cpuinfo_max_freq` populations are what distinguishes
+ * a performance core from an efficiency one, so the frequency IS the evidence and the label
+ * is only offered when the split is unambiguous.
+ */
+export function collectHostFacts(input, probes = SYSTEM_HOST_PROBES) {
+    const cpu = input.pinnedCpu;
+    const base = cpu === undefined ? undefined : `/sys/devices/system/cpu/cpu${cpu}/cpufreq`;
+    const governor = base === undefined ? undefined : nonEmptyString(probes.readSystemFile(`${base}/scaling_governor`));
+    const maxKHzText = base === undefined ? undefined : probes.readSystemFile(`${base}/cpuinfo_max_freq`);
+    const maxKHz = maxKHzText === undefined ? undefined : finiteNumber(Number(maxKHzText));
+    const noTurbo = probes.readSystemFile("/sys/devices/system/cpu/intel_pstate/no_turbo");
+    const turboEnabled = noTurbo === undefined ? undefined : noTurbo.trim() === "0";
+    const cpuCount = probes.cpuCount();
+    return {
+        hostname: probes.hostname(),
+        realtimePriority: input.realtimePriority,
+        memoryLocked: input.memoryLocked,
+        ...optional("kernel", nonEmptyString(probes.kernelRelease())),
+        ...optional("os", nonEmptyString(probes.osName())),
+        ...optional("cpuModel", nonEmptyString(probes.cpuModel())),
+        ...optional("cpuCount", cpuCount > 0 ? cpuCount : undefined),
+        ...optional("pinnedCpu", cpu),
+        ...optional("pinnedCpuMaxKHz", maxKHz),
+        ...optional("governor", governor),
+        ...optional("turboEnabled", turboEnabled),
+        ...optional("toolchain", input.toolchain),
+    };
+}
+/**
+ * The host block from `benchmark.py --cost-provenance`'s JSON, or `undefined`.
+ *
+ * That file is the model this format generalises, so the mapping is mostly renaming. The
+ * one judgement: its `realtimePriority` / `memoryLocked` are already explicit booleans, and
+ * a file that omits them is treated as not having run privileged — the safe reading, and
+ * the one that matches what the prober can actually do without privileges.
+ */
+export function hostFromProbeProvenance(value) {
+    if (!isRecord(value))
+        return undefined;
+    const host = nonEmptyString(value.host);
+    if (host === undefined)
+        return undefined;
+    const python = nonEmptyString(value.python);
+    return {
+        hostname: host,
+        realtimePriority: booleanValue(value.realtimePriority) ?? false,
+        memoryLocked: booleanValue(value.memoryLocked) ?? false,
+        ...optional("kernel", nonEmptyString(value.kernel)),
+        ...optional("cpuModel", nonEmptyString(value.cpuModel)),
+        ...optional("cpuCount", finiteNumber(value.cpuCount)),
+        ...optional("pinnedCpu", finiteNumber(value.pinnedCpu)),
+        ...optional("pinnedCpuKind", nonEmptyString(value.pinnedCpuKind)),
+        ...optional("pinnedCpuMaxKHz", finiteNumber(value.pinnedCpuMaxKHz)),
+        ...optional("governor", nonEmptyString(value.governor)),
+        ...optional("turboEnabled", booleanValue(value.turboEnabled)),
+        ...optional("toolchain", python === undefined ? undefined : { python }),
+    };
+}
+/** The cost method block from `benchmark.py --cost-provenance`'s JSON, or `undefined`. */
+export function costMethodFromProbeProvenance(value) {
+    if (!isRecord(value))
+        return undefined;
+    const blockFrames = finiteNumber(value.blockFrames);
+    const warmupBlocks = finiteNumber(value.warmupBlocks);
+    const percentile = finiteNumber(value.percentile);
+    const stimulus = nonEmptyString(value.stimulus);
+    if (blockFrames === undefined || warmupBlocks === undefined || percentile === undefined || stimulus === undefined) {
+        return undefined;
+    }
+    return {
+        method: "block-time-percentile",
+        blockFrames,
+        warmupBlocks,
+        percentile,
+        stimulus,
+        controls: nonEmptyString(value.controls) ?? "lv2:default on every control input",
+        ...optional("minTimedBlocks", finiteNumber(value.minTimedBlocks)),
+        ...optional("maxTimedBlocks", finiteNumber(value.maxTimedBlocks)),
+        ...optional("targetSecondsPerPlugin", finiteNumber(value.targetSecondsPerPlugin)),
+        ...optional("timingFloorNsPerBlock", finiteNumber(value.timingFloorNsPerBlock)),
+    };
+}
+/** The caveat that rides on every run carrying cost figures. */
+export const RELATIVE_RANKING_NOTE = "A RELATIVE ranking measured on one machine, not a guarantee on any other. Different silicon, " +
+    "a different governor or a busier machine will produce different absolute figures; what carries " +
+    "over is the ORDER and the rough ratios.";
+/** The caveat on a run carrying only latency figures — portable, but not unconditionally. */
+export const LATENCY_ONLY_NOTE = "Latency is mostly algorithmic, so these figures travel between machines better than cost does. " +
+    "They are still tied to the PLUGIN VERSIONS recorded here: a new release moves an FFT window and " +
+    "the figure becomes wrong without becoming absent.";
+/** The caveat on a run carrying the hosting dimensions — survival, RT-safety, features. */
+export const HOSTING_NOTE = "Whether a plugin survives and keeps run() free of allocations, locks and syscalls was measured " +
+    "on the host named here, against its libc, lilv and the plugin builds installed at the time. An " +
+    "upgrade of any of them is a different host: carry the figures across and re-judge, never trust.";
+/**
+ * Assemble a run record.
+ *
+ * `relativeRankingOnly` is derived, not passed: it is true exactly when the run carries cost
+ * figures, and letting a caller set it would let a caller unset it. The note follows the
+ * same rule — a latency-only run gets the version caveat, a cost run gets the machine one,
+ * and a run carrying both gets both, because both apply.
+ */
+export function buildRun(input) {
+    const dimensions = MEASUREMENT_DIMENSIONS.filter((d) => input.dimensions.includes(d));
+    const hasCost = dimensions.includes("cost");
+    const hasLatency = dimensions.includes("latency");
+    const hasHosting = dimensions.some((d) => d === "stability" || d === "rtSafety" || d === "features");
+    const note = [
+        hasCost ? RELATIVE_RANKING_NOTE : undefined,
+        hasLatency ? LATENCY_ONLY_NOTE : undefined,
+        hasHosting ? HOSTING_NOTE : undefined,
+    ]
+        .filter((part) => part !== undefined)
+        .join(" ");
+    return {
+        id: input.id,
+        measuredAt: input.measuredAt,
+        dimensions,
+        rates: [...input.rates].sort((a, b) => a - b),
+        tool: input.tool,
+        host: input.host,
+        method: {
+            ...optional("latency", input.latencyMethod),
+            ...optional("cost", input.costMethod),
+        },
+        relativeRankingOnly: hasCost,
+        note: note.length > 0 ? note : RELATIVE_RANKING_NOTE,
+        ...optional("elapsedSeconds", input.elapsedSeconds),
+        ...optional("label", input.label),
+    };
+}
+//# sourceMappingURL=provenance.js.map

package/dist/measurement/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../src/measurement/provenance.ts"],"names":[],"mappings":"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"}

package/dist/measurement/sweep-jsonl.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The hosting sweep's JSONL → the interchange format's three hosting dimensions.
+ *
+ * `lv2-measure` (a C lilv host, run under an
+ * allocation-and-syscall interposer) writes one JSON line per plugin, and the sweep ran it in THREE passes a
+ * reader has to put back together:
+ *
+ * - the QUICK pass (`all-measurements.jsonl`): every plugin, 30 lifecycles, the interposer's
+ *   counts, the required features, the threads;
+ * - the DEEP lifecycle pass (`lifecycle-1000.jsonl`): the candidates again at 1000 lifecycles —
+ *   where present it SUPERSEDES the quick pass's lifecycle and threads, and a crash in it is a
+ *   crash the quick pass could not have seen;
+ * - the SOAK (`soak*.jsonl`): a show-length render per rate with every control swept slowly
+ *   across its range (`lv2-measure.c`'s soak mode), one line per plugin.
+ *
+ * Like `probe-json.ts`, this is a TRANSLATION and never a judgement. An exit status of 139 is
+ * written as the signal it is (128 + SIGSEGV); whether that crash is the plugin's fault, whether a
+ * soak held, whether a count is a measurement at all — those are the consumer's rules, and a
+ * reader that decided them would be a second classifier ahead of the real one.
+ */
+import type { MeasuredPlugin } from "./format.js";
+/** The sweep's three passes, each a list of parsed JSONL lines. Only `measurements` is required. */
+export interface SweepPasses {
+    readonly measurements: readonly unknown[];
+    readonly lifecycle?: readonly unknown[];
+    readonly soak?: readonly unknown[];
+}
+/**
+ * Every plugin the sweep INSTANTIATED, as a {@link MeasuredPlugin} carrying the three hosting
+ * dimensions.
+ *
+ * A line for a plugin the tool could not find or instantiate carries no topology, and the
+ * format's plugin entry requires one (rule 2: no invented numbers). It is left out rather than
+ * written with a reason: its three blocks would all be `probe-failed`, which by the merge's own
+ * rule override nothing — a line with no reading and no power to change a figure.
+ */
+export declare function measuredPluginsFromSweep(passes: SweepPasses): MeasuredPlugin[];
+/** Parse JSONL text: every line that is a JSON object, in order. A plugin's own stdout banner
+ *  before the JSON is the sweep harness's problem and already stripped there. */
+export declare function parseJsonl(text: string): unknown[];

package/dist/measurement/sweep-jsonl.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The hosting sweep's JSONL → the interchange format's three hosting dimensions.
+ *
+ * `lv2-measure` (a C lilv host, run under an
+ * allocation-and-syscall interposer) writes one JSON line per plugin, and the sweep ran it in THREE passes a
+ * reader has to put back together:
+ *
+ * - the QUICK pass (`all-measurements.jsonl`): every plugin, 30 lifecycles, the interposer's
+ *   counts, the required features, the threads;
+ * - the DEEP lifecycle pass (`lifecycle-1000.jsonl`): the candidates again at 1000 lifecycles —
+ *   where present it SUPERSEDES the quick pass's lifecycle and threads, and a crash in it is a
+ *   crash the quick pass could not have seen;
+ * - the SOAK (`soak*.jsonl`): a show-length render per rate with every control swept slowly
+ *   across its range (`lv2-measure.c`'s soak mode), one line per plugin.
+ *
+ * Like `probe-json.ts`, this is a TRANSLATION and never a judgement. An exit status of 139 is
+ * written as the signal it is (128 + SIGSEGV); whether that crash is the plugin's fault, whether a
+ * soak held, whether a count is a measurement at all — those are the consumer's rules, and a
+ * reader that decided them would be a second classifier ahead of the real one.
+ */
+import { readLifecycle, readSoakAtRate, readThreads } from "./format.js";
+import { booleanValue, finiteNumber, isRecord, mapArray, nonEmptyString, optional, positiveNumber } from "./guards.js";
+/** A process exit status that IS a signal death, as the signal's name. Anything else is not a
+ *  crash this reader can name — a timeout (124) or an early refusal is the run failing, not the
+ *  plugin dying, and it is not written as a crash. */
+const SIGNAL_EXITS = {
+    134: "SIGABRT",
+    135: "SIGBUS",
+    139: "SIGSEGV",
+};
+function crashOf(row) {
+    if (row.crashed !== true)
+        return undefined;
+    const exit = finiteNumber(row.exit);
+    const signal = exit === undefined ? undefined : SIGNAL_EXITS[exit];
+    return signal === undefined ? undefined : { signal };
+}
+/** One soak line's per-rate map. The tool writes `block` and a redundant `rate` inside each
+ *  reading; the rate is the key, and `block` is the format's `blockFrames`. */
+function soakOf(row) {
+    if (!isRecord(row) || !isRecord(row.perRate))
+        return undefined;
+    const perRate = {};
+    for (const [key, reading] of Object.entries(row.perRate)) {
+        const rate = positiveNumber(Number(key));
+        if (rate === undefined || !Number.isInteger(rate) || !isRecord(reading))
+            continue;
+        const parsed = readSoakAtRate({ ...reading, blockFrames: reading.block });
+        if (parsed !== undefined)
+            perRate[String(rate)] = parsed;
+    }
+    // lv2-measure's soak mode sweeps every control across its range for the whole render.
+    return { sweptParams: true, perRate };
+}
+function stabilityOf(quick, deep, soakRow) {
+    const lifecycle = readLifecycle(deep?.lifecycle) ?? readLifecycle(quick.lifecycle);
+    if (lifecycle === undefined)
+        return { unmeasuredReason: "probe-error", unmeasuredDetail: "no lifecycle in the sweep line" };
+    const threads = readThreads(deep?.threads) ?? readThreads(quick.threads);
+    const crashes = [crashOf(quick), deep === undefined ? undefined : crashOf(deep)].filter((c) => c !== undefined);
+    const soak = soakRow === undefined ? undefined : soakOf(soakRow);
+    return {
+        lifecycle,
+        ...optional("threads", threads),
+        crashes,
+        ...optional("soak", soak),
+    };
+}
+function rtSafetyOf(row) {
+    const rt = row.rtSafety;
+    if (!isRecord(rt))
+        return { unmeasuredReason: "probe-error", unmeasuredDetail: "no interposer block in the sweep line" };
+    return {
+        ...optional("rate", positiveNumber(row.rate)),
+        ...optional("blockFrames", positiveNumber(row.block)),
+        ...optional("blocks", finiteNumber(rt.blocks)),
+        ...optional("repeats", finiteNumber(rt.repeats)),
+        ...optional("interposer", booleanValue(rt.interposer)),
+        ...optional("swept", booleanValue(rt.swept)),
+        ...optional("sweepApplicable", booleanValue(rt.sweepApplicable)),
+        ...optional("allocationsInRun", finiteNumber(rt.allocationsInRun)),
+        ...optional("allocationsMin", finiteNumber(rt.allocationsMin)),
+        ...optional("locksInRun", finiteNumber(rt.locksInRun)),
+        ...optional("syscallsInRun", finiteNumber(rt.syscallsInRun)),
+        ...optional("variable", booleanValue(rt.variable)),
+    };
+}
+function featuresOf(row) {
+    const required = mapArray(row.requiredFeatures, nonEmptyString);
+    if (required === undefined)
+        return { unmeasuredReason: "probe-error", unmeasuredDetail: "no feature list in the sweep line" };
+    return {
+        required,
+        ...optional("optional", mapArray(row.optionalFeatures, nonEmptyString)),
+        ...optional("cvPorts", finiteNumber(row.cvPorts)),
+    };
+}
+function byUri(rows) {
+    const out = new Map();
+    for (const row of rows ?? []) {
+        if (!isRecord(row))
+            continue;
+        const uri = nonEmptyString(row.uri);
+        if (uri !== undefined)
+            out.set(uri, row);
+    }
+    return out;
+}
+/**
+ * Every plugin the sweep INSTANTIATED, as a {@link MeasuredPlugin} carrying the three hosting
+ * dimensions.
+ *
+ * A line for a plugin the tool could not find or instantiate carries no topology, and the
+ * format's plugin entry requires one (rule 2: no invented numbers). It is left out rather than
+ * written with a reason: its three blocks would all be `probe-failed`, which by the merge's own
+ * rule override nothing — a line with no reading and no power to change a figure.
+ */
+export function measuredPluginsFromSweep(passes) {
+    const deep = byUri(passes.lifecycle);
+    const soak = byUri(passes.soak);
+    const out = [];
+    for (const row of passes.measurements) {
+        if (!isRecord(row))
+            continue;
+        const uri = nonEmptyString(row.uri);
+        const audioInputs = finiteNumber(row.audioInputs);
+        const audioOutputs = finiteNumber(row.audioOutputs);
+        if (uri === undefined || audioInputs === undefined || audioOutputs === undefined)
+            continue;
+        out.push({
+            uri,
+            topology: {
+                audioInputs,
+                audioOutputs,
+                ...optional("controlInputs", finiteNumber(row.controlInputs)),
+            },
+            stability: stabilityOf(row, deep.get(uri), soak.get(uri)),
+            rtSafety: rtSafetyOf(row),
+            features: featuresOf(row),
+        });
+    }
+    return out;
+}
+/** Parse JSONL text: every line that is a JSON object, in order. A plugin's own stdout banner
+ *  before the JSON is the sweep harness's problem and already stripped there. */
+export function parseJsonl(text) {
+    return text
+        .split("\n")
+        .filter((line) => line.trim().startsWith("{"))
+        .map((line) => JSON.parse(line));
+}
+//# sourceMappingURL=sweep-jsonl.js.map

package/dist/measurement/sweep-jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep-jsonl.js","sourceRoot":"","sources":["../../src/measurement/sweep-jsonl.ts"],"names":[],"mappings":"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"}

package/dist/measurement/vocabulary.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The controlled vocabularies the interchange format speaks.
+ *
+ * This is the boring file that decides whether two projects' measurements can be merged
+ * Everyone who has written an LV2 prober has invented their own
+ * words for "there was nothing to measure here", so nobody's results combine. The words
+ * are fixed here, each with the ONE property a merger actually needs to branch on —
+ * whether the plugin has nothing to measure or whether OUR PROBE failed — and each with
+ * a plain description a UI can render.
+ *
+ * Everything is a data table, not a switch. Adding a term is one row; a consumer that
+ * meets a term it does not know must be able to fall back on the `kind`, which is why the
+ * readers below return a term record rather than a bare string.
+ */
+/**
+ * What an absent figure means for a MERGE, and it is the only distinction that changes
+ * behaviour:
+ *
+ * - `nothing-to-measure` — a property of the PLUGIN. An instrument has no audio input to
+ *   drive; a meter has no audio output to read. Any prober on any machine reaches the
+ *   same conclusion, so this outcome is as portable as a measurement and may override one.
+ * - `probe-failed` — a property of THIS RUN. The plugin crashed the worker, timed out,
+ *   refused to instantiate. It says nothing about the plugin's latency or cost, so it
+ *   must NOT override a figure someone else managed to take.
+ * - `not-attempted` — the run did not cover this plugin or this dimension at all. Neither
+ *   a finding nor a failure; it is the shape a PARTIAL run has, and partial runs are
+ *   first-class here.
+ */
+export type UnmeasuredKind = "nothing-to-measure" | "probe-failed" | "not-attempted";
+/** One term of the "why is there no figure" vocabulary. */
+export interface UnmeasuredTerm {
+    readonly code: string;
+    readonly kind: UnmeasuredKind;
+    /** Plain description, English. A UI localises from `code`; this is for logs and specs. */
+    readonly description: string;
+}
+/**
+ * Every reason a figure may be absent. These were derived from a sweep of 958 plugins — each
+ * one is an outcome that sweep actually produced, not a hypothetical.
+ */
+export declare const UNMEASURED_TERMS: readonly UnmeasuredTerm[];
+/**
+ * The vocabulary term for a code, or `undefined` when the code is not one of ours.
+ *
+ * A third-party document carrying an unknown reason is not an error — the format is meant
+ * to be extended by people we will never meet. {@link unmeasuredKind} is what a merger
+ * should consult, and it is deliberately conservative about strangers.
+ */
+export declare function unmeasuredTerm(code: string | undefined): UnmeasuredTerm | undefined;
+/**
+ * How a merger must treat an absence reason. An UNKNOWN code resolves to `probe-failed`,
+ * the conservative answer: a reason we cannot interpret must never be allowed to delete
+ * somebody else's real measurement, and treating it as a plugin property would do exactly
+ * that.
+ */
+export declare function unmeasuredKind(code: string | undefined): UnmeasuredKind;
+/**
+ * The rate-scaling laws, DERIVED from readings at several rates and never assumed from
+ * what a plugin is called. The population behind each term is in
+ * `CATALOG_PROVENANCE.md`'s 2026-07-28 rows.
+ */
+export interface ScalingTerm {
+    readonly code: string;
+    readonly description: string;
+}
+export declare const SCALING_TERMS: readonly ScalingTerm[];
+/** True when `code` is a scaling term this version of the format defines. */
+export declare function isKnownScalingCode(code: string): boolean;
+/**
+ * Why a derived scaling class is not the naive fit over every reading — `below-budget`,
+ * where the readings fit no law but are all small enough that the disagreement is the onset
+ * detector's rather than the plugin's, and `informational-rate`, where only a reading below
+ * the operational rates breaks the law (`lv2-measurement-interchange.md` §1a).
+ */
+export declare const SCALING_NOTE_TERMS: readonly [{
+    readonly code: "below-budget";
+    readonly description: string;
+}, {
+    readonly code: "informational-rate";
+    readonly description: string;
+}];
+/** One of the {@link SCALING_NOTE_TERMS} codes — the words `latency.scalingNote` may carry. */
+export type ScalingNoteCode = (typeof SCALING_NOTE_TERMS)[number]["code"];
+/**
+ * Why one rate's reading was excluded from the fit and from every rate resolution. A
+ * failed reading served as an exact answer is worse than no reading, because a zero reads
+ * as confidence.
+ */
+export declare const EXCLUSION_TERMS: readonly ScalingTerm[];
+/** The measurement methods the format has names for. */
+export declare const METHOD_TERMS: readonly ScalingTerm[];
+/** True when `code` is a method term this version of the format defines. */
+export declare function isKnownMethodCode(code: string): boolean;
+/**
+ * The measurable dimensions. A document declares which of them it covers.
+ *
+ * `latency` and `cost` are 1.0's. `stability`, `rtSafety` and `features` joined in 1.1 for the
+ * hosting verdict — whether a plugin survives, whether its `run()` is RT-clean, what it
+ * demands of a host — and merge under exactly the same per-plugin, per-DIMENSION precedence.
+ */
+export declare const MEASUREMENT_DIMENSIONS: readonly ["latency", "cost", "stability", "rtSafety", "features"];
+/**
+ * The dimensions the standalone prober (`scan.py` + `benchmark.py`, driven by `lv2-measure.mjs`
+ * and the console's Setup analysis) can measure. The three hosting dimensions come from a
+ * different tool — the `lv2-measure.c` sweep, read by `sweep-jsonl.ts` — so a run asked of the
+ * prober for `stability` would be asking it for something it cannot take.
+ */
+export declare const PROBED_DIMENSIONS: readonly ["latency", "cost"];
+/** One measurable dimension. */
+export type MeasurementDimension = (typeof MEASUREMENT_DIMENSIONS)[number];
+/** `value` as a dimension, or `undefined` when it is not one. */
+export declare function readDimension(value: unknown): MeasurementDimension | undefined;
+/**
+ * The four ratings a verdict speaks (`lv2-measurement-interchange.md` §3b) — the ONE list; the
+ * rating vocabulary (`rating.ts`) derives its type from it, so the document and the classifier
+ * can never disagree on a word.
+ */
+export declare const VERDICT_RATINGS: readonly ["suitable", "conditional", "unknown", "unsuitable"];
+export type VerdictRating = (typeof VERDICT_RATINGS)[number];
+/** How a host runs its plugins (`2026-09-25-plugin-qualify.md` §3a). */
+export declare const HOST_ISOLATIONS: readonly ["in-process", "per-process", "shared-process"];
+export type HostIsolation = (typeof HOST_ISOLATIONS)[number];
+/** Whether a host aligns on a plugin's reported latency (`compensated`) or only passes it on. */
+export declare const HOST_LATENCY_HANDLING: readonly ["compensated", "uncompensated"];
+export type HostLatencyHandling = (typeof HOST_LATENCY_HANDLING)[number];