@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/dist/measurement/format.d.ts

@@ -0,0 +1,483 @@
+/**
+ * **The LV2 plugin measurement interchange format** — one measurement run, on one
+ * machine, in one document.
+ *
+ * `lv2:latency` is a declared port and it is often wrong: the 958-plugin sweep behind
+ * `data/catalog.json` found 57 declared-vs-measured mismatches. Measured figures exist in
+ * several projects and are shared by none of them, because there is no shape to share them
+ * in. This is that shape. The schema is the deliverable; the prober is replaceable.
+ *
+ * ## The three rules the format exists to enforce
+ *
+ * 1. **A figure carries the conditions it was taken under.** {@link MeasurementRun} is not
+ *    optional metadata and is not a footer — it is the document's other half. A cost
+ *    figure without its host, governor, block and stimulus is a decoration; a latency
+ *    figure without the plugin's version is a trap, because the next release moves the FFT
+ *    window and the number silently becomes a lie.
+ * 2. **Unknown is a value.** A plugin that could not be measured carries a REASON from a
+ *    controlled vocabulary ({@link ./vocabulary.ts}) and no number at all. Nothing in this
+ *    format has a default: an absent field means "not determined", never zero and never
+ *    false. Readers here return `undefined` rather than inventing.
+ * 3. **Per rate, always.** Latency does not scale one way and cost does not scale at all
+ *    predictably — 19 plugins in the reference sweep fit neither scaling law, and 48 cost
+ *    figures grow with the SQUARE of the rate. A single-rate document is a claim about one
+ *    rate and the format will not let it pretend otherwise: every figure lives under an
+ *    explicit rate key.
+ *
+ * ## Version strategy
+ *
+ * `formatVersion` is `"<major>.<minor>"`.
+ *
+ * - **major** changes when a reader written for the previous major would MISREAD a
+ *   document: a field removed, renamed, re-scaled, or given a new meaning. A reader that
+ *   meets a higher major must refuse the document ({@link readMeasurementDocument} does),
+ *   because the alternative is silently consuming figures it has misunderstood.
+ * - **minor** changes are additive only: new optional fields, new vocabulary terms. A
+ *   reader at minor N reads minor N+1 fine, ignoring what it does not know — and is TOLD
+ *   it is doing so ({@link MeasurementReadResult.forwardMinor}), so a UI can say "this
+ *   document was written by a newer tool" instead of quietly dropping data.
+ *
+ * Unknown fields are preserved nowhere and that is deliberate: a reader that round-trips
+ * fields it does not understand invites a consumer to depend on them. Re-emit from the
+ * original document, never from a parse.
+ */
+import { type HostIsolation, type HostLatencyHandling, type MeasurementDimension, type VerdictRating, MEASUREMENT_DIMENSIONS } from "./vocabulary.js";
+/** The `format` discriminator every document carries. Never absent, never anything else. */
+export declare const MEASUREMENT_FORMAT_ID = "lv2-plugin-measurements";
+/** The major this build writes and is guaranteed to understand. */
+export declare const MEASUREMENT_FORMAT_MAJOR = 1;
+/** The minor this build writes. Additive-only within {@link MEASUREMENT_FORMAT_MAJOR}.
+ *  `1.1` added the three hosting dimensions — {@link StabilityMeasurement},
+ *  {@link RtSafetyMeasurement}, {@link FeaturesMeasurement} — which a 1.0 reader skips. */
+export declare const MEASUREMENT_FORMAT_MINOR = 2;
+/** The version string this build writes, e.g. `"1.0"`. */
+export declare const MEASUREMENT_FORMAT_VERSION = "1.2";
+/** A parsed `formatVersion`. */
+export interface FormatVersion {
+    readonly major: number;
+    readonly minor: number;
+}
+/**
+ * Parse a `"<major>.<minor>"` version, or `undefined` when it is not one.
+ *
+ * Deliberately strict — two non-negative integers and nothing else. A version we cannot
+ * parse is a document we cannot claim to understand, and guessing at `"1"` or `"1.0.0"`
+ * would be exactly the sloppiness a version field exists to prevent.
+ */
+export declare function parseFormatVersion(value: unknown): FormatVersion | undefined;
+/**
+ * The machine a run happened on.
+ *
+ * Every field except {@link hostname} is optional and every one of them is absent when it
+ * could not be READ — the prober reports what `/proc` and `/sys` told it and nothing else.
+ * `realtimePriority` and `memoryLocked` are the exception and are required, because
+ * "we did not try" and "we tried and were not allowed" are both `false` and a consumer
+ * comparing two runs must not have to guess which.
+ */
+export interface MeasurementHost {
+    /** The machine's name. The single field an operator recognises. */
+    readonly hostname: string;
+    readonly kernel?: string;
+    readonly os?: string;
+    readonly cpuModel?: string;
+    readonly cpuCount?: number;
+    /** The core the prober pinned itself to, when it pinned at all. */
+    readonly pinnedCpu?: number;
+    /** What kind of core that was — `performance` / `efficiency` on a hybrid CPU. */
+    readonly pinnedCpuKind?: string;
+    readonly pinnedCpuMaxKHz?: number;
+    /** The cpufreq governor in force, read at run time. `performance` and `powersave`
+     *  produce materially different cost figures on the same silicon. */
+    readonly governor?: string;
+    readonly turboEnabled?: boolean;
+    /** Whether the prober ran with realtime scheduling. Required: `false` is a finding. */
+    readonly realtimePriority: boolean;
+    /** Whether the prober's pages were locked. Required, same reason. */
+    readonly memoryLocked: boolean;
+    /** Versions of what did the probing (`{ python: "3.14.6", lilv: "0.24.26" }`). */
+    readonly toolchain?: Readonly<Record<string, string>>;
+}
+/** How the latency figures in this document were taken. */
+export interface LatencyMethod {
+    /** A {@link ../vocabulary.METHOD_TERMS} code — `impulse-onset` or `declared-port`. */
+    readonly method: string;
+    readonly blockFrames: number;
+    /** What was fed in, in words. An onset measured through an opened gate is not the same
+     *  measurement as one through a bare impulse, and the difference must be legible. */
+    readonly stimulus: string;
+    /** Whether latency-bearing controls were swept to find parameter-dependent latency. */
+    readonly paramSweep: boolean;
+}
+/** How the cost figures in this document were taken. */
+export interface CostMethod {
+    /** A {@link ../vocabulary.METHOD_TERMS} code — `block-time-percentile`. */
+    readonly method: string;
+    readonly blockFrames: number;
+    /** Blocks timed and then DISCARDED before the steady-state window opened. */
+    readonly warmupBlocks: number;
+    readonly minTimedBlocks?: number;
+    readonly maxTimedBlocks?: number;
+    /** Wall-time budget per plugin per rate, after which timing stops early. */
+    readonly targetSecondsPerPlugin?: number;
+    /** The percentile the headline figure is quoted at. The mean hides the tail that xruns. */
+    readonly percentile: number;
+    readonly stimulus: string;
+    /** How control ports were set — the operating point the figure describes. */
+    readonly controls: string;
+    /** Lower bound on the harness's own per-block overhead. Plugins near it are too cheap
+     *  to rank apart, and it is REPORTED rather than subtracted. */
+    readonly timingFloorNsPerBlock?: number;
+}
+/**
+ * One measurement run: who measured, on what, how, when, and over which rates.
+ *
+ * A document is exactly one run, on purpose. Merging figures taken on different machines
+ * is a consumer's decision with a consumer's caveats ({@link ./merge.ts}); baking it into
+ * the document would make a merged file indistinguishable from a measured one.
+ */
+export interface MeasurementRun {
+    /** Stable identifier for this run — referenced by a merged view to name a figure's source. */
+    readonly id: string;
+    /** ISO 8601, with offset. */
+    readonly measuredAt: string;
+    /** Which dimensions this run covered. A plugin carrying no figure for a dimension NOT
+     *  listed here was never asked; one carrying none for a dimension that IS listed has a
+     *  reason. That distinction is why the field exists. */
+    readonly dimensions: readonly MeasurementDimension[];
+    /** Every sample rate the run measured at, ascending. */
+    readonly rates: readonly number[];
+    readonly tool: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly host: MeasurementHost;
+    readonly method: {
+        readonly latency?: LatencyMethod;
+        readonly cost?: CostMethod;
+    };
+    /** Wall-clock duration of the run. The only honest basis for estimating the next one. */
+    readonly elapsedSeconds?: number;
+    /** Free-text label an operator gave the run ("after installing LSP 1.2.22"). */
+    readonly label?: string;
+    /**
+     * Always `true` on a run carrying cost figures: the numbers RANK plugins on the machine
+     * named above and do not predict another. Kept as an explicit field rather than a
+     * convention so a consumer cannot claim it never saw the caveat.
+     */
+    readonly relativeRankingOnly: boolean;
+    /** The caveat in prose, for anyone reading the file directly. */
+    readonly note: string;
+}
+/** What the prober saw of the plugin's ports. Cheap, portable, and it decides suitability. */
+export interface PluginTopology {
+    readonly audioInputs: number;
+    readonly audioOutputs: number;
+    readonly midiInputs?: number;
+    readonly controlInputs?: number;
+}
+/** One rate's latency reading. */
+export interface LatencyAtRate {
+    readonly frames: number;
+    readonly ms: number;
+    /** Set when this reading needed an ESCALATED stimulus (a gate that had to be opened).
+     *  The figure then describes that operating point, not the plugin at rest. */
+    readonly stimulus?: string;
+    /**
+     * Set when the reading was taken but REJECTED as evidence, with a vocabulary code
+     * ({@link ../vocabulary.EXCLUSION_TERMS}). The number stays — this is the measurement
+     * record — but a consumer must not resolve a rate to it.
+     */
+    readonly excludedReason?: string;
+}
+/** The controls that move a plugin's latency, and the span they move it over. */
+export interface MeasuredParamSweep {
+    readonly rate: number;
+    readonly defaultFrames: number;
+    readonly minFrames: number;
+    readonly maxFrames: number;
+    /** Per-control span, keyed by control-port symbol. */
+    readonly controls: Readonly<Record<string, {
+        readonly minFrames: number;
+        readonly maxFrames: number;
+    }>>;
+}
+/** Everything one run learned about one plugin's latency. */
+export interface LatencyMeasurement {
+    /** Readings keyed by sample rate in Hz as a decimal string (`"96000"`). May be empty. */
+    readonly perRate: Readonly<Record<string, LatencyAtRate>>;
+    /** A {@link ../vocabulary.SCALING_TERMS} code, derived from {@link perRate}. */
+    readonly scalingClass?: string;
+    /** A {@link ../vocabulary.SCALING_NOTE_TERMS} code: why the class is not the naive fit. */
+    readonly scalingNote?: string;
+    /** Symbol of the plugin's own `lv2:latency` port, when it has one. */
+    readonly declaredPortSymbol?: string;
+    /** What that port CLAIMED, in frames. Kept next to the measurement, never instead of it. */
+    readonly declaredFrames?: number;
+    /** Set when declared and measured disagree beyond rounding — a data-quality flag on the
+     *  PLUGIN, and the single most useful thing this format publishes. */
+    readonly declaredMismatch?: boolean;
+    readonly paramSweep?: MeasuredParamSweep;
+    /** An {@link ../vocabulary.UNMEASURED_TERMS} code. Set exactly when {@link perRate} is
+     *  empty; a figure and a reason are mutually exclusive. */
+    readonly unmeasuredReason?: string;
+    /** The prober's own words for that reason, kept verbatim. The CODE is what a merger
+     *  branches on; this is what a human reads when the code is too coarse to debug with. */
+    readonly unmeasuredDetail?: string;
+}
+/** One rate's cost reading. Per SAMPLE, so it is independent of the block size. */
+export interface CostAtRate {
+    readonly nsPerSampleMedian: number;
+    /** The percentile named in {@link CostMethod.percentile} — what a bad block costs. */
+    readonly nsPerSamplePercentile: number;
+    readonly nsPerSampleMin?: number;
+    readonly nsPerSampleMax?: number;
+    /** Timed blocks the statistics were computed over, warm-up already dropped. */
+    readonly blocks: number;
+    readonly blockFrames: number;
+    /** Median over the DISCARDED warm-up blocks: the evidence that discarding was warranted
+     *  rather than assumed. */
+    readonly warmupNsPerSampleMedian?: number;
+    /** Timed, but emitted silence under a stimulus that should have passed — the figure may
+     *  describe a short-circuit path rather than the DSP. */
+    readonly silentOutput?: boolean;
+}
+/** Everything one run learned about one plugin's CPU cost. */
+export interface CostMeasurement {
+    /** Readings keyed by sample rate in Hz as a decimal string. May be empty. */
+    readonly perRate: Readonly<Record<string, CostAtRate>>;
+    /** An {@link ../vocabulary.UNMEASURED_TERMS} code, set exactly when {@link perRate} is empty. */
+    readonly unmeasuredReason?: string;
+    /** The prober's own words for that reason, kept verbatim. See {@link LatencyMeasurement.unmeasuredDetail}. */
+    readonly unmeasuredDetail?: string;
+}
+/** Instantiate/destroy cycles, as run. */
+export interface LifecycleReading {
+    readonly cycles: number;
+    readonly instantiated: number;
+    readonly failed: number;
+}
+/** The process's thread count around the plugin's first instance. */
+export interface ThreadReading {
+    readonly before: number;
+    readonly afterFirstInstantiate: number;
+    readonly afterAllFreed?: number;
+    readonly leaked?: number;
+}
+/** A crash as observed. Attribution — whose fault — is the consumer's, from its own table. */
+export interface CrashReading {
+    readonly signal?: string;
+    readonly topFrame?: string;
+    /** The error class a sanitizer build reported, verbatim (`"heap-buffer-overflow"`). */
+    readonly sanitizer?: string;
+    /** Basename of the shared object the faulting frame lies in (`"zero-path.so"`). */
+    readonly frameObject?: string;
+}
+/** One rate of a continuous soak: the render as it went, window by window. */
+export interface SoakAtRate {
+    /** The process died at this rate. Every other field is then absent. */
+    readonly died?: boolean;
+    readonly instantiated?: boolean;
+    readonly seconds?: number;
+    readonly blockFrames?: number;
+    readonly windows?: number;
+    readonly nonFiniteWindows?: number;
+    readonly silentWindows?: number;
+    readonly firstRmsDbfs?: number;
+    readonly lastRmsDbfs?: number;
+    readonly minRmsDbfs?: number;
+    readonly rssStartKb?: number;
+    readonly rssMaxKb?: number;
+    readonly rssGrowthKb?: number;
+}
+/** A continuous soak, per rate, with whether the controls were swept while it ran. */
+export interface SoakReading {
+    readonly sweptParams: boolean;
+    readonly perRate: Readonly<Record<string, SoakAtRate>>;
+}
+/** Everything one run learned about one plugin SURVIVING. Readable when it has a lifecycle. */
+export interface StabilityMeasurement {
+    readonly lifecycle?: LifecycleReading;
+    readonly threads?: ThreadReading;
+    readonly crashes?: readonly CrashReading[];
+    readonly soak?: SoakReading;
+    readonly unmeasuredReason?: string;
+    readonly unmeasuredDetail?: string;
+}
+/**
+ * What an interposer counted INSIDE `run()`. `rate` and `blockFrames` are the pair it ran at —
+ * a count is a property of the code paths the run took there. Readable when all three counts
+ * are present.
+ */
+export interface RtSafetyMeasurement {
+    readonly rate?: number;
+    readonly blockFrames?: number;
+    readonly blocks?: number;
+    readonly repeats?: number;
+    /** The interposer was actually loaded. A zero from an absent interposer counts nothing. */
+    readonly interposer?: boolean;
+    /** The controls were swept across their ranges while counting. */
+    readonly swept?: boolean;
+    /** False when the plugin has no control a sweep could move. */
+    readonly sweepApplicable?: boolean;
+    readonly allocationsInRun?: number;
+    readonly allocationsMin?: number;
+    readonly locksInRun?: number;
+    readonly syscallsInRun?: number;
+    /** Repeats disagreed. */
+    readonly variable?: boolean;
+    readonly unmeasuredReason?: string;
+    readonly unmeasuredDetail?: string;
+}
+/** What the plugin DEMANDS of a host, read off the instance the run loaded. */
+export interface FeaturesMeasurement {
+    readonly required?: readonly string[];
+    readonly optional?: readonly string[];
+    readonly cvPorts?: number;
+    readonly unmeasuredReason?: string;
+    readonly unmeasuredDetail?: string;
+}
+/** One plugin as one run saw it. */
+export interface MeasuredPlugin {
+    readonly uri: string;
+    readonly name?: string;
+    /**
+     * The plugin's own version (`lv2:minorVersion.lv2:microVersion`), when it declares one.
+     * A latency figure attached to no version is a trap: the next release moves
+     * the window and the figure becomes wrong without becoming absent.
+     */
+    readonly version?: string;
+    /** The LV2 bundle it came from — what an operator greps for when a figure surprises them. */
+    readonly bundle?: string;
+    /** The plugin's declared LV2 class label, verbatim. */
+    readonly lv2Class?: string;
+    readonly topology: PluginTopology;
+    readonly latency?: LatencyMeasurement;
+    readonly cost?: CostMeasurement;
+    readonly stability?: StabilityMeasurement;
+    readonly rtSafety?: RtSafetyMeasurement;
+    readonly features?: FeaturesMeasurement;
+}
+/** What a host spends on one plugin instance: the P95 core-fraction ceiling, at its rate and quantum. */
+export interface HostBudget {
+    readonly coreFractionCeiling: number;
+    readonly rate: number;
+    readonly quantum: number;
+}
+/**
+ * A HOST PROFILE (`2026-09-25-plugin-qualify.md` §3a; §3b here): the host a verdict was judged
+ * against — only what differs between hosts. A document carries every profile its verdicts name,
+ * in full, so a verdict against a project's own profile is reproducible from the document alone.
+ */
+export interface HostProfile {
+    readonly id: string;
+    /** The LV2 feature URIs the host passes to `instantiate`. */
+    readonly lv2Features: readonly string[];
+    /** The CLAP host extensions it offers; `null` for a host with no CLAP path at all. */
+    readonly clapExtensions: readonly string[] | null;
+    /** Whether it feeds note/MIDI input — hosts instruments. */
+    readonly instruments: boolean;
+    readonly cost: HostBudget;
+    readonly latency: HostLatencyHandling;
+    readonly isolation: HostIsolation;
+}
+/** One plugin's verdict under one host profile (§3b). `host` is a `hostProfiles[].id`. */
+export interface DocumentVerdict {
+    readonly uri: string;
+    readonly host: string;
+    readonly rating: VerdictRating;
+    /** `rating === "suitable"`, and nothing else. */
+    readonly qualified: boolean;
+    /** The code of the reason that decided it; absent for `suitable`. */
+    readonly deciding?: string;
+}
+/** A complete document: one run, and what it found. */
+export interface MeasurementDocument {
+    readonly format: typeof MEASUREMENT_FORMAT_ID;
+    readonly formatVersion: string;
+    readonly run: MeasurementRun;
+    readonly plugins: readonly MeasuredPlugin[];
+    /** v1.2: the hosts the run's verdicts were judged against (§3b). */
+    readonly hostProfiles?: readonly HostProfile[];
+    /** v1.2: one verdict per plugin per host profile — conclusions, beside the raw blocks. */
+    readonly verdicts?: readonly DocumentVerdict[];
+}
+export type HostProfileRead = {
+    ok: true;
+    profile: HostProfile;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Read a host profile — a document's, or a project's own file. Every field is required and
+ * typed; a missing or mistyped one is refused by name, and a host the reader was not told about
+ * is never filled in from a default.
+ */
+export declare function readHostProfile(value: unknown): HostProfileRead;
+/** A refusal to read a document, with the reason in a form a UI can render. */
+export interface MeasurementReadFailure {
+    readonly ok: false;
+    /** Stable code: `not-an-object` / `wrong-format` / `bad-version` / `future-major` /
+     *  `missing-run` / `missing-plugins`. */
+    readonly problem: string;
+    /** English detail for logs. UIs render from {@link problem} plus {@link found}. */
+    readonly detail: string;
+    /** What was actually there, when the problem is about a value. */
+    readonly found?: string;
+}
+/** A document read successfully, plus what the reader had to tolerate to do it. */
+export interface MeasurementReadSuccess {
+    readonly ok: true;
+    readonly document: MeasurementDocument;
+    readonly version: FormatVersion;
+    /**
+     * Set when the document's minor is AHEAD of this build's: it was written by a newer tool
+     * and may carry fields this reader dropped. Everything read is still valid — minors are
+     * additive — but a surface should say so rather than imply completeness.
+     */
+    readonly forwardMinor?: true;
+    /**
+     * Plugin entries dropped for being malformed. Never silent: a document that half-parses
+     * must say how much of it was lost, or a consumer will read a partial catalogue as a
+     * complete one.
+     */
+    readonly droppedPlugins: number;
+    /**
+     * v1.2: verdicts (and host profiles) dropped for being malformed or naming a host the document
+     * does not declare — present whenever the document carried either list.
+     */
+    readonly droppedVerdicts?: number;
+}
+/** The outcome of {@link readMeasurementDocument}. */
+export type MeasurementReadResult = MeasurementReadSuccess | MeasurementReadFailure;
+/** A lifecycle reading, or `undefined` unless all three counts are there. */
+export declare function readLifecycle(value: unknown): LifecycleReading | undefined;
+/** A thread reading, or `undefined` without its before/after pair. */
+export declare function readThreads(value: unknown): ThreadReading | undefined;
+/** One soak rate. Every field optional: a rate that died carries `died` and nothing else. */
+export declare function readSoakAtRate(value: unknown): SoakAtRate | undefined;
+/**
+ * Read an untrusted value — a parsed JSON file, a wire frame — as a measurement document.
+ *
+ * Never throws and never casts: every field is validated on the way in and the result is
+ * built from the pieces that passed. A document whose major exceeds this build's is
+ * REFUSED rather than partially read, because a major bump means a field this reader
+ * recognises no longer means what it thinks.
+ */
+export declare function readMeasurementDocument(value: unknown): MeasurementReadResult;
+/**
+ * Build a document at THIS build's version.
+ *
+ * The only supported way to create one: it stamps `format` and `formatVersion` so no call
+ * site can write a document claiming a version its content does not match, and it sorts
+ * plugins by URI so two runs over the same host produce a diffable file.
+ */
+export declare function buildMeasurementDocument(run: MeasurementRun, plugins: readonly MeasuredPlugin[], judged?: {
+    readonly hostProfiles: readonly HostProfile[];
+    readonly verdicts: readonly DocumentVerdict[];
+}): MeasurementDocument;
+/** Serialise a document: 2-space JSON with a trailing newline, stable across runs. */
+export declare function serialiseMeasurementDocument(document: MeasurementDocument): string;
+/** Every dimension a run may declare, in presentation order. Re-exported for consumers
+ *  that need the list without reaching into the vocabulary module. */
+export { MEASUREMENT_DIMENSIONS, type MeasurementDimension };