@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/src/measurement/plan.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * What a run is going to do, decided before it starts.
+ *
+ * Two questions, answered in the same breath: *"Measure at least the rates this
+ * installation can actually use … but it must not silently fall back to a rate it does not
+ * use"*, and *"show progress"* — which needs a duration, which nobody can honestly produce
+ * for a machine they have never seen.
+ *
+ * ## Rates are data, not a constant
+ *
+ * There is no default rate list in this module and there must never be one. A console that
+ * runs 48 k and 96 k does not need 192 k figures; a console whose driver only offers 44.1 k
+ * must not be handed a 48 k measurement wearing its label. The plan is derived from what the
+ * installation reports — its live rate and its device's supported list — and a request for a
+ * rate the hardware does not offer is DROPPED and reported, never honoured.
+ *
+ * A plan with no rates is a legitimate outcome: it means nobody has told us what this
+ * installation runs at, and the correct behaviour is to refuse and say so rather than pick
+ * 48 000 because it is a common number.
+ *
+ * ## Duration is an estimate or it is nothing
+ *
+ * {@link estimateRunSeconds} scales a REFERENCE run's measured wall time by the work the new
+ * plan asks for. With no reference run — or a reference that never recorded its own duration
+ * — it returns `undefined`. There is no fallback constant: "about 15 minutes" measured on a
+ * Core Ultra 9 is not an estimate for a NUC, and a wrong progress estimate is how an operator
+ * ends up cancelling a run that was nearly done.
+ */
+
+import { type MeasurementDimension, MEASUREMENT_DIMENSIONS } from "./vocabulary.js";
+import type { MeasurementDocument, MeasurementRun } from "./format.js";
+
+/** What the installation knows about its own clock, as far as the plan is concerned. */
+export interface InstallationRates {
+  /** The rate the graph is running at right now, when the console knows it. */
+  readonly liveRate?: number;
+  /** Rates the active device actually offers. Empty/absent = the console has not probed. */
+  readonly supportedRates?: readonly number[];
+  /** Rates the operator asked for. Absent = "whatever this installation can use". */
+  readonly requestedRates?: readonly number[];
+}
+
+/** The rates a run will measure at, and what was left out on the way there. */
+export interface RatePlan {
+  /** Rates to measure, ascending. Empty when nothing could be resolved. */
+  readonly rates: readonly number[];
+  /**
+   * Rates the operator asked for that the installation does not offer. Reported, not
+   * measured — a figure at a rate the rig cannot run is a figure nobody will ever use, and
+   * quietly measuring it would make the run longer for nothing.
+   */
+  readonly dropped: readonly number[];
+  /**
+   * Set when {@link rates} is empty: `no-rates-known`. The console could name neither a
+   * live rate nor a supported list, so there is nothing to measure and no safe guess.
+   */
+  readonly problem?: string;
+}
+
+/**
+ * Resolve the rates a local run should measure at.
+ *
+ * The live rate is always included when known — a console must have figures for the rate it
+ * is running at, whatever else the operator asked for. Beyond that: the requested rates
+ * intersected with what the device offers, or, absent a request, the whole supported list.
+ */
+export function ratesForInstallation(input: InstallationRates): RatePlan {
+  const supported = [...new Set((input.supportedRates ?? []).filter((r) => Number.isFinite(r) && r > 0))];
+  const live = input.liveRate !== undefined && Number.isFinite(input.liveRate) && input.liveRate > 0
+    ? input.liveRate
+    : undefined;
+  // What this installation can actually use: the device list, plus the rate it is demonstrably
+  // running at (a live rate absent from the probed list is the device telling us the list is
+  // incomplete, not the other way round).
+  const usable = new Set(supported);
+  if (live !== undefined) usable.add(live);
+
+  const requested = input.requestedRates?.filter((r) => Number.isFinite(r) && r > 0);
+  if (requested === undefined || requested.length === 0) {
+    const rates = [...usable].sort((a, b) => a - b);
+    return rates.length > 0
+      ? { rates, dropped: [] }
+      : { rates: [], dropped: [], problem: "no-rates-known" };
+  }
+
+  const wanted = new Set(requested);
+  if (live !== undefined) wanted.add(live);
+  const rates = [...wanted].filter((r) => usable.has(r)).sort((a, b) => a - b);
+  const dropped = [...wanted].filter((r) => !usable.has(r)).sort((a, b) => a - b);
+  return rates.length > 0
+    ? { rates, dropped }
+    : { rates: [], dropped, problem: "no-rates-known" };
+}
+
+/** A run, fully specified, before anything is probed. */
+export interface MeasurementPlan {
+  readonly rates: readonly number[];
+  readonly dimensions: readonly MeasurementDimension[];
+  /** Rates asked for and dropped as unusable here — carried through so the UI can say so. */
+  readonly droppedRates: readonly number[];
+  /** How many plugins the run will visit, when a scan has already told us. */
+  readonly pluginCount?: number;
+  /** Set when the plan cannot run: `no-rates-known` / `no-dimensions`. */
+  readonly problem?: string;
+}
+
+/** Build a plan from resolved rates and the dimensions the operator chose. */
+export function measurementPlan(
+  ratePlan: RatePlan,
+  dimensions: readonly MeasurementDimension[],
+  pluginCount?: number,
+): MeasurementPlan {
+  const wanted = MEASUREMENT_DIMENSIONS.filter((d) => dimensions.includes(d));
+  const problem = ratePlan.problem ?? (wanted.length === 0 ? "no-dimensions" : undefined);
+  return {
+    rates: ratePlan.rates,
+    dimensions: wanted,
+    droppedRates: ratePlan.dropped,
+    ...(pluginCount === undefined ? {} : { pluginCount }),
+    ...(problem === undefined ? {} : { problem }),
+  };
+}
+
+/** True when a plan has enough to run: at least one rate and at least one dimension. */
+export function isRunnablePlan(plan: MeasurementPlan): boolean {
+  return plan.problem === undefined && plan.rates.length > 0 && plan.dimensions.length > 0;
+}
+
+/**
+ * The unit of work a plan represents: plugins × rates × dimensions.
+ *
+ * Crude on purpose. A convolution reverb costs more than a gain, but the prober caps each
+ * plugin's wall time, so over a whole catalogue the product is close enough to scale a
+ * measured duration by — and a more elaborate model would imply a precision the estimate
+ * does not have.
+ */
+export function planWorkUnits(plan: MeasurementPlan): number | undefined {
+  if (plan.pluginCount === undefined) return undefined;
+  return plan.pluginCount * plan.rates.length * plan.dimensions.length;
+}
+
+/** A duration estimate, with the run it was extrapolated from named. */
+export interface RunEstimate {
+  readonly seconds: number;
+  /** The reference run's id, host and duration — everything needed to render "on <host>,
+   *  <n> plugins took <t>", so the operator can judge the extrapolation themselves. */
+  readonly basis: {
+    readonly runId: string;
+    readonly host: string;
+    readonly seconds: number;
+    readonly workUnits: number;
+  };
+}
+
+/** The work a completed run represents, from its own document. */
+function runWorkUnits(document: MeasurementDocument): number | undefined {
+  const units = document.plugins.length * document.run.rates.length * document.run.dimensions.length;
+  return units > 0 ? units : undefined;
+}
+
+/**
+ * How long this plan is likely to take, extrapolated from a run that actually happened.
+ *
+ * `undefined` whenever it cannot be derived — no reference document, the reference never
+ * recorded `elapsedSeconds`, or the plan does not yet know its plugin count. An unknown
+ * duration is reported as unknown; there is no constant to fall back on and inventing one
+ * would be the exact dishonesty the provenance discipline exists to prevent.
+ *
+ * When the reference ran on ANOTHER machine the estimate is still only an order of
+ * magnitude — which is why {@link RunEstimate.basis} names the host rather than hiding it.
+ */
+export function estimateRunSeconds(
+  plan: MeasurementPlan,
+  reference: MeasurementDocument | undefined,
+): RunEstimate | undefined {
+  if (reference === undefined) return undefined;
+  const elapsed = reference.run.elapsedSeconds;
+  if (elapsed === undefined || !(elapsed > 0)) return undefined;
+  const referenceUnits = runWorkUnits(reference);
+  const planUnits = planWorkUnits(plan);
+  if (referenceUnits === undefined || planUnits === undefined || planUnits === 0) return undefined;
+  return {
+    seconds: (elapsed * planUnits) / referenceUnits,
+    basis: {
+      runId: reference.run.id,
+      host: reference.run.host.hostname,
+      seconds: elapsed,
+      workUnits: referenceUnits,
+    },
+  };
+}
+
+/**
+ * Rates a completed run covers that the installation no longer cares about, and rates the
+ * installation now uses that the run never covered.
+ *
+ * The second list is the rate-change case: the operator moved the rig to 96 kHz, so the
+ * figures for 96 kHz are MISSING rather than wrong, and the console should offer to measure
+ * them instead of interpolating across a boundary 19 nonconforming plugins prove cannot be
+ * interpolated across.
+ */
+export interface RateCoverage {
+  readonly covered: readonly number[];
+  readonly missing: readonly number[];
+  readonly extra: readonly number[];
+}
+
+/** Compare a run's rates against the rates an installation now uses. */
+export function rateCoverage(run: MeasurementRun | undefined, needed: readonly number[]): RateCoverage {
+  const have = new Set(run?.rates ?? []);
+  const want = [...new Set(needed)].sort((a, b) => a - b);
+  return {
+    covered: want.filter((rate) => have.has(rate)),
+    missing: want.filter((rate) => !have.has(rate)),
+    extra: [...have].filter((rate) => !want.includes(rate)).sort((a, b) => a - b),
+  };
+}

package/src/measurement/probe-json.ts

@@ -0,0 +1,271 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The prober's JSON → the interchange format.
+ *
+ * `tools/scan.py` and `tools/benchmark.py` write a flat array of annotated descriptors —
+ * their own working shape, which predates this format and carries fields (curation tiers,
+ * parameter lists, RPM ownership) that have nothing to do with a measurement. This module
+ * is the one place that knows both shapes, and it is where three deliberate conversions
+ * happen:
+ *
+ * 1. **Free text becomes vocabulary.** The prober says `"worker crashed (…)"`,
+ *    `"probe timed out"`, `"non-finite output"` — useful to a human, unmergeable between
+ *    projects. Each is mapped to a term from {@link ./vocabulary.ts}, and the prober's own
+ *    sentence is preserved verbatim next to it so the coarser code never destroys the
+ *    detail.
+ * 2. **Derived figures are dropped.** `coreFractionP95` and `instancesPerCoreP95` are
+ *    `nsPerSample × rate` and its reciprocal. Storing them invites the two to disagree
+ *    after an edit; the format keeps the measured primitive and lets consumers derive.
+ * 3. **`nsPerSampleP95` becomes `nsPerSamplePercentile`.** The percentile is a property of
+ *    the RUN, declared once in {@link ../format.CostMethod}. Baking `95` into every field
+ *    name would make a p99 run unrepresentable.
+ *
+ * The reader is structural: it validates the fields it needs and ignores everything else,
+ * so it survives the prober growing new ones.
+ */
+
+import type {
+  CostAtRate,
+  CostMeasurement,
+  LatencyAtRate,
+  LatencyMeasurement,
+  MeasuredParamSweep,
+  MeasuredPlugin,
+  PluginTopology,
+} from "./format.js";
+import { booleanValue, finiteNumber, isRecord, nonEmptyString, optional, positiveNumber } from "./guards.js";
+import type { MeasurementDimension } from "./vocabulary.js";
+
+/** One free-text prober failure, and the vocabulary term it means. */
+interface ReasonRule {
+  /** Matched against the prober's lowercased text. */
+  readonly match: RegExp;
+  readonly code: string;
+}
+
+/**
+ * The prober's words → the controlled vocabulary. Ordered: the first match wins, so the
+ * specific patterns come before the general ones.
+ *
+ * A table rather than a switch precisely so the next prober — someone else's — can be
+ * supported by adding rows, which is the whole ambition of publishing a format.
+ */
+export const PROBE_REASON_RULES: readonly ReasonRule[] = [
+  { match: /^no-audio-in$/, code: "no-audio-in" },
+  { match: /^no-audio-out$/, code: "no-audio-out" },
+  { match: /^silent-output$/, code: "silent-output" },
+  { match: /worker crashed|worker desync|worker unavailable/, code: "probe-crashed" },
+  { match: /timed out|timeout/, code: "probe-timeout" },
+  { match: /non-finite/, code: "non-finite-output" },
+  { match: /not installed/, code: "not-installed" },
+  { match: /refus|instantiat/, code: "refused-instantiation" },
+];
+
+/**
+ * The vocabulary code for a prober reason.
+ *
+ * Anything unmatched becomes `probe-error` — never a guessed structural reason. A reason we
+ * cannot classify must not be allowed to claim the plugin has nothing to measure, because
+ * that claim would override a good figure from another machine ({@link ./merge.ts}).
+ */
+export function probeReasonCode(text: string): string {
+  const lower = text.toLowerCase();
+  return PROBE_REASON_RULES.find((rule) => rule.match.test(lower))?.code ?? "probe-error";
+}
+
+function reasonFields(text: string | undefined): { unmeasuredReason?: string; unmeasuredDetail?: string } {
+  if (text === undefined) return {};
+  const code = probeReasonCode(text);
+  return {
+    unmeasuredReason: code,
+    // Keep the prober's sentence only when it says more than the code already does.
+    ...(text === code ? {} : { unmeasuredDetail: text }),
+  };
+}
+
+function readTopology(entry: Record<string, unknown>): PluginTopology | undefined {
+  const audioInputs = finiteNumber(entry.audioInputs);
+  const audioOutputs = finiteNumber(entry.audioOutputs);
+  if (audioInputs === undefined || audioOutputs === undefined) return undefined;
+  const midiInputs = entry.hasMidiIn === true ? 1 : entry.hasMidiIn === false ? 0 : undefined;
+  const controlInputs = Array.isArray(entry.params)
+    ? entry.params.filter((p) => isRecord(p) && p.kind === "control").length
+    : undefined;
+  return {
+    audioInputs,
+    audioOutputs,
+    ...optional("midiInputs", midiInputs),
+    ...optional("controlInputs", controlInputs),
+  };
+}
+
+function readSweep(value: unknown): MeasuredParamSweep | undefined {
+  if (!isRecord(value)) return undefined;
+  const rate = positiveNumber(value.rate);
+  const defaultFrames = finiteNumber(value.defaultFrames);
+  const minFrames = finiteNumber(value.minFrames);
+  const maxFrames = finiteNumber(value.maxFrames);
+  if (rate === undefined || defaultFrames === undefined || minFrames === undefined || maxFrames === undefined) {
+    return undefined;
+  }
+  const controls: Record<string, { minFrames: number; maxFrames: number }> = {};
+  if (isRecord(value.controls)) {
+    for (const [symbol, span] of Object.entries(value.controls)) {
+      if (!isRecord(span)) continue;
+      const lo = finiteNumber(span.minFrames);
+      const hi = finiteNumber(span.maxFrames);
+      if (lo === undefined || hi === undefined) continue;
+      controls[symbol] = { minFrames: lo, maxFrames: hi };
+    }
+  }
+  return { rate, defaultFrames, minFrames, maxFrames, controls };
+}
+
+/**
+ * Rates the prober condemned, as `rate → reason`. In the catalog shape these live in a
+ * parallel `unreliableRates` array; the format puts the exclusion ON the reading it
+ * disqualifies, where a consumer cannot fail to notice it.
+ */
+function excludedRates(value: unknown): ReadonlyMap<string, string> {
+  const out = new Map<string, string>();
+  if (!Array.isArray(value)) return out;
+  for (const item of value) {
+    if (!isRecord(item)) continue;
+    const rate = positiveNumber(item.rate);
+    const reason = nonEmptyString(item.reason);
+    if (rate === undefined || reason === undefined) continue;
+    out.set(String(rate), reason);
+  }
+  return out;
+}
+
+function readLatency(value: unknown): LatencyMeasurement | undefined {
+  if (!isRecord(value)) return undefined;
+  const excluded = excludedRates(value.unreliableRates);
+  const perRate: Record<string, LatencyAtRate> = {};
+  if (isRecord(value.perRate)) {
+    for (const [key, reading] of Object.entries(value.perRate)) {
+      const rate = positiveNumber(Number(key));
+      if (rate === undefined || !isRecord(reading)) continue;
+      const frames = finiteNumber(reading.frames);
+      const ms = finiteNumber(reading.ms);
+      if (frames === undefined || ms === undefined) continue;
+      perRate[String(rate)] = {
+        frames,
+        ms,
+        ...optional("stimulus", nonEmptyString(value.stimulus)),
+        ...optional("excludedReason", excluded.get(String(rate))),
+      };
+    }
+  }
+  const unmeasurable = nonEmptyString(value.unmeasurable);
+  const measurement: LatencyMeasurement = {
+    perRate,
+    ...optional("scalingClass", nonEmptyString(value.scalingClass)),
+    ...optional("scalingNote", nonEmptyString(value.scalingNote)),
+    ...optional("declaredPortSymbol", nonEmptyString(value.portSymbol)),
+    ...optional("declaredFrames", finiteNumber(value.reportedFrames)),
+    ...optional("declaredMismatch", booleanValue(value.declaredMismatch)),
+    ...optional("paramSweep", readSweep(value.paramSweep)),
+    // A reason only when there is no reading: a figure and a reason are mutually exclusive.
+    ...(Object.keys(perRate).length === 0 ? reasonFields(unmeasurable) : {}),
+  };
+  return measurement;
+}
+
+function readCost(value: unknown): CostMeasurement | undefined {
+  if (!isRecord(value)) return undefined;
+  const perRate: Record<string, CostAtRate> = {};
+  if (isRecord(value.perRate)) {
+    for (const [key, reading] of Object.entries(value.perRate)) {
+      const rate = positiveNumber(Number(key));
+      if (rate === undefined || !isRecord(reading)) continue;
+      const median = finiteNumber(reading.nsPerSampleMedian);
+      const high = finiteNumber(reading.nsPerSampleP95);
+      const blocks = finiteNumber(reading.blocks);
+      const blockFrames = positiveNumber(reading.blockFrames);
+      if (median === undefined || high === undefined || blocks === undefined || blockFrames === undefined) {
+        continue;
+      }
+      perRate[String(rate)] = {
+        nsPerSampleMedian: median,
+        nsPerSamplePercentile: high,
+        blocks,
+        blockFrames,
+        ...optional("nsPerSampleMin", finiteNumber(reading.nsPerSampleMin)),
+        ...optional("nsPerSampleMax", finiteNumber(reading.nsPerSampleMax)),
+        ...optional("warmupNsPerSampleMedian", finiteNumber(reading.warmupNsPerSampleMedian)),
+        ...optional("silentOutput", booleanValue(reading.silentOutput)),
+      };
+    }
+  }
+  const reason = nonEmptyString(value.unmeasurable) ?? nonEmptyString(value.failed);
+  return {
+    perRate,
+    ...(Object.keys(perRate).length === 0 ? reasonFields(reason) : {}),
+  };
+}
+
+/**
+ * The plugin's own version, `"<minor>.<micro>"`, when the scan recorded one.
+ *
+ * Absent rather than `"0.0"` when it did not: a version of zero is a real LV2 answer
+ * (unstable/development), so it must not double as "we do not know".
+ */
+function readVersion(entry: Record<string, unknown>): string | undefined {
+  const minor = finiteNumber(entry.minorVersion);
+  const micro = finiteNumber(entry.microVersion);
+  if (minor === undefined || micro === undefined) return nonEmptyString(entry.version);
+  return `${minor}.${micro}`;
+}
+
+/**
+ * One prober descriptor as a {@link MeasuredPlugin}, or `undefined` when it is not one.
+ *
+ * `dimensions` says which dimensions the run covered: a dimension NOT covered yields no
+ * block at all (the run never asked), while a covered dimension always yields one, carrying
+ * either readings or a reason. That distinction is what makes a partial run readable. The
+ * prober's JSON carries only `latency` and `cost`; a hosting dimension listed here yields no
+ * block, because this reader has nothing to read it from (`sweep-jsonl.ts` does).
+ */
+export function measuredPluginFromProbeEntry(
+  value: unknown,
+  dimensions: readonly MeasurementDimension[],
+): MeasuredPlugin | undefined {
+  if (!isRecord(value)) return undefined;
+  const uri = nonEmptyString(value.uri);
+  if (uri === undefined) return undefined;
+  const topology = readTopology(value);
+  if (topology === undefined) return undefined;
+
+  const latency = dimensions.includes("latency")
+    ? readLatency(value.latency) ?? { perRate: {}, unmeasuredReason: "not-attempted" }
+    : undefined;
+  const cost = dimensions.includes("cost")
+    ? readCost(value.cpuCost) ?? { perRate: {}, unmeasuredReason: "not-attempted" }
+    : undefined;
+
+  return {
+    uri,
+    topology,
+    ...optional("name", nonEmptyString(value.name)),
+    ...optional("version", readVersion(value)),
+    ...optional("bundle", nonEmptyString(value.bundlePath)),
+    ...optional("lv2Class", nonEmptyString(value.lv2Class)),
+    ...optional("latency", latency),
+    ...optional("cost", cost),
+  };
+}
+
+/** Every readable descriptor in a prober output array, as measured plugins. */
+export function measuredPluginsFromProbeOutput(
+  value: unknown,
+  dimensions: readonly MeasurementDimension[],
+): MeasuredPlugin[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const plugin = measuredPluginFromProbeEntry(entry, dimensions);
+    return plugin === undefined ? [] : [plugin];
+  });
+}