@openmixer/plugin-qualify 0.0.0-stage → 0.3.0

package/src/measurement/provenance.ts

@@ -0,0 +1,220 @@
+// 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 type { CostMethod, LatencyMethod, MeasurementHost, MeasurementRun } from "./format.js";
+import { booleanValue, finiteNumber, isRecord, nonEmptyString, optional } from "./guards.js";
+import { type MeasurementDimension, MEASUREMENT_DIMENSIONS } 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 const SYSTEM_HOST_PROBES: HostProbes = {
+  hostname: () => osHostname(),
+  kernelRelease: () => osRelease(),
+  osName: () => osType(),
+  cpuModel: () => osCpus()[0]?.model,
+  cpuCount: () => osCpus().length,
+  readSystemFile: (path) => {
+    try {
+      return readFileSync(path, "utf8").trim();
+    } catch {
+      return undefined;
+    }
+  },
+};
+
+/** 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 function collectHostFacts(input: HostFactInput, probes: HostProbes = SYSTEM_HOST_PROBES): MeasurementHost {
+  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: unknown): MeasurementHost | undefined {
+  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: unknown): CostMethod | undefined {
+  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.";
+
+/** 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 function buildRun(input: RunInput): MeasurementRun {
+  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),
+  };
+}

package/src/measurement/sweep-jsonl.ts

@@ -0,0 +1,173 @@
+// 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 type {
+  CrashReading,
+  FeaturesMeasurement,
+  MeasuredPlugin,
+  RtSafetyMeasurement,
+  SoakReading,
+  StabilityMeasurement,
+} from "./format.js";
+import { readLifecycle, readSoakAtRate, readThreads } from "./format.js";
+import { booleanValue, finiteNumber, isRecord, mapArray, nonEmptyString, optional, positiveNumber } from "./guards.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[];
+}
+
+/** 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: Readonly<Record<number, string>> = {
+  134: "SIGABRT",
+  135: "SIGBUS",
+  139: "SIGSEGV",
+};
+
+function crashOf(row: Record<string, unknown>): CrashReading | undefined {
+  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: unknown): SoakReading | undefined {
+  if (!isRecord(row) || !isRecord(row.perRate)) return undefined;
+  const perRate: Record<string, NonNullable<ReturnType<typeof readSoakAtRate>>> = {};
+  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: Record<string, unknown>,
+  deep: Record<string, unknown> | undefined,
+  soakRow: unknown,
+): StabilityMeasurement {
+  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 is CrashReading => c !== undefined,
+  );
+  const soak = soakRow === undefined ? undefined : soakOf(soakRow);
+  return {
+    lifecycle,
+    ...optional("threads", threads),
+    crashes,
+    ...optional("soak", soak),
+  };
+}
+
+function rtSafetyOf(row: Record<string, unknown>): RtSafetyMeasurement {
+  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: Record<string, unknown>): FeaturesMeasurement {
+  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: readonly unknown[] | undefined): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>();
+  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: SweepPasses): MeasuredPlugin[] {
+  const deep = byUri(passes.lifecycle);
+  const soak = byUri(passes.soak);
+  const out: MeasuredPlugin[] = [];
+  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: string): unknown[] {
+  return text
+    .split("\n")
+    .filter((line) => line.trim().startsWith("{"))
+    .map((line): unknown => JSON.parse(line));
+}