@openmixer/plugin-qualify 0.14.1 → 0.15.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openmixer/plugin-qualify",
-  "version": "0.14.1",
-  "description": "Qualify audio plugins for real-time hosting: scan, offline latency and cost measurement, a mod-host hosting sweep, and a fail-closed rating.",
+  "version": "0.15.1",
+  "description": "Qualify audio plugins for real-time hosting: scan, offline latency and cost measurement, and a fail-closed rating.",
   "type": "module",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -17,7 +17,8 @@
     "node": ">=18"
   },
   "bin": {
-    "plugin-qualify": "./bin/plugin-qualify.mjs"
+    "plugin-qualify": "./bin/plugin-qualify.mjs",
+    "plugin-qualify-sync": "./bin/plugin-qualify-sync.mjs"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -96,6 +97,6 @@
     "provenance": true
   },
   "dependencies": {
-    "@openmixer/omx-contract": "^3.0.0"
+    "@openmixer/omx-contract": "^3.4.0"
   }
 }

package/src/adjust-cli.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `plugin-qualify adjust --history <file>`: read the qualification records `judge` (or a run with `--out`) wrote, read
+ * plugin-hostd's running history, and write a second verdict beside each measured one, for the host class of the history,
+ * with a reason code (`history-adjust.ts` holds the rules). The measurement and the measured verdicts of a record are
+ * never touched: the second verdict lives in the record's `history` block, one entry per host class. `--pins` writes the
+ * adjusted verdict instead of the measured one. `bin/plugin-qualify.mjs` only reads argv and prints.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { findHistory, historyClasses, readHistory, type HistoryRead, type HistoryRecord } from "./history-file.js";
+import { adjustVerdict, summariseHistory, type Adjustment } from "./history-adjust.js";
+import type { HostProfile } from "./host-profiles.js";
+import { OPENMIXER_CONSOLE_PROFILE } from "./host-profiles.js";
+import { clapPinUri, pinVerdictOf, type PinEntry, type PinVerdict } from "./pins-file.js";
+import { QUALIFICATION_RECORD_SCHEMA, type HistoryBlock, type QualificationRecord, type RecordVerdict } from "./qualification-record.js";
+import { EXIT_CODE, OUTPUT_FORMATS, type OutputFormat } from "./qualify-options.js";
+import type { SuitabilityRating } from "./rating.js";
+
+export interface AdjustArgs {
+  readonly history: string;
+  readonly hostProfiles: readonly string[];
+  readonly qualificationDir?: string;
+  readonly hostClass?: string;
+  readonly pins?: string;
+  /** UTC seconds the history is read at; the clock when absent. */
+  readonly now?: number;
+  readonly format: OutputFormat;
+  readonly help: boolean;
+}
+
+export type ParseAdjustResult = { ok: true; args: AdjustArgs } | { ok: false; error: string };
+
+const VALUE_FLAGS = ["--history", "--host-profile", "--qualification-dir", "--host-class", "--pins", "--now", "--format"];
+
+export function parseAdjustArgs(argv: readonly string[]): ParseAdjustResult {
+  const specs: string[] = [];
+  const got = new Map<string, string>();
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (!a.startsWith("--")) return { ok: false, error: `${a}: adjust takes options only; the records are read from --qualification-dir` };
+    if (a === "--help") {
+      help = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.includes(a)) return { ok: false, error: `unknown option ${a}` };
+    const v = argv[++i];
+    if (v === undefined || v.startsWith("--")) return { ok: false, error: `${a} needs a value` };
+    if (a === "--host-profile") specs.push(...v.split(",").map((t) => t.trim()).filter((t) => t !== ""));
+    else got.set(a, v);
+  }
+  const format = got.get("--format") ?? "text";
+  if (!(OUTPUT_FORMATS as readonly string[]).includes(format)) return { ok: false, error: `--format must be one of ${OUTPUT_FORMATS.join(", ")}` };
+  const nowText = got.get("--now");
+  const now = nowText === undefined ? undefined : Number(nowText);
+  if (now !== undefined && !(Number.isInteger(now) && now >= 0)) return { ok: false, error: "--now must be UTC seconds, a whole number" };
+  const history = got.get("--history");
+  if (!help && history === undefined) return { ok: false, error: "name the history file with --history" };
+  const dir = got.get("--qualification-dir");
+  const hostClass = got.get("--host-class");
+  const pins = got.get("--pins");
+  return {
+    ok: true,
+    args: {
+      history: history ?? "",
+      hostProfiles: [...new Set(specs.length > 0 ? specs : [OPENMIXER_CONSOLE_PROFILE.id])],
+      ...(dir === undefined ? {} : { qualificationDir: dir }),
+      ...(hostClass === undefined ? {} : { hostClass }),
+      ...(pins === undefined ? {} : { pins }),
+      ...(now === undefined ? {} : { now }),
+      format: format as OutputFormat,
+      help,
+    },
+  };
+}
+
+export function adjustHelpText(): string {
+  return [
+    "plugin-qualify adjust — write a second verdict beside each measured one from plugin-hostd's running history",
+    "",
+    "  plugin-qualify adjust --history <file> [options]",
+    "",
+    "  --history <file>              plugin-hostd's history file ($XDG_STATE_HOME/plugin-hostd/history); required",
+    "  --qualification-dir <dir>     the records `judge` wrote; each gets a `history` block (default: the one judge writes to)",
+    "  --host-profile <file|id>      adjust the verdict of this host; repeat or comma-separate (default: openmixer-console)",
+    "  --host-class <class>          read only this host class of the history (arch/cores/clock); default: every class the file holds",
+    "  --pins <file>                 write the pins with the ADJUSTED verdict of the first host profile; needs exactly one host class",
+    "  --now <seconds>               the UTC second the history is read at (default: the clock)",
+    "  --format <json|text>          json = the records; text = one row per plugin, host and host class (default: text)",
+    "",
+    "The measured verdicts and the measurement are never changed. History can demote in-process to isolated (a crash, xruns when",
+    "grouped), isolated to refused (three solo crashes), and promote isolated to in-process only when every reason against the",
+    "plugin is a cost reason and it ran steady alone. It never lifts a real-time-safety, feature or unknown verdict, or a refused one.",
+    "",
+    `exit ${EXIT_CODE.allQualified} done / ${EXIT_CODE.couldNotMeasure} the history, a record or an option could not be read`,
+    "",
+  ].join("\n");
+}
+
+/** A record read from the qualification directory, with the file it came from. */
+export interface RecordFile {
+  readonly path: string;
+  readonly record: QualificationRecord;
+}
+
+/** Every `*.qualification.json` of the directory with this reader's schema; a file that does not read is a failure, and the others go on. */
+export function readRecords(dir: string, read: (path: string) => string = (p) => readFileSync(p, "utf8")): {
+  readonly records: readonly RecordFile[];
+  readonly failures: readonly { readonly file: string; readonly problem: string }[];
+} {
+  const records: RecordFile[] = [];
+  const failures: { file: string; problem: string }[] = [];
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".qualification.json")).sort();
+  } catch (e) {
+    return { records, failures: [{ file: dir, problem: `cannot read: ${e instanceof Error ? e.message : String(e)}` }] };
+  }
+  for (const name of names) {
+    const path = join(dir, name);
+    try {
+      const doc = JSON.parse(read(path)) as QualificationRecord;
+      if (doc.schema !== QUALIFICATION_RECORD_SCHEMA) failures.push({ file: path, problem: `schema ${String(doc.schema)}, not ${QUALIFICATION_RECORD_SCHEMA}` });
+      else records.push({ path, record: doc });
+    } catch (e) {
+      failures.push({ file: path, problem: `cannot read: ${e instanceof Error ? e.message : String(e)}` });
+    }
+  }
+  return { records, failures };
+}
+
+/** plugin-hostd's key of a record's plugin: its uri and the digest of the first file of its pin (files sorted by path, as the pin lists them). `undefined` when the record holds no whole pin. */
+export function historyKeyOf(record: QualificationRecord): { readonly uri: string; readonly digest: string } | undefined {
+  const files = [...record.binary.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  if (files.length === 0 || record.binary.layout === undefined) return undefined;
+  const uri = record.plugin.format === "clap" ? clapPinUri(record.binary.path, record.plugin.id) : record.plugin.id;
+  return { uri, digest: files[0]!.sha256 };
+}
+
+/** The pin verdict of a record's verdict row: `unknown` and an unmeasured row have none. */
+function measuredPinVerdict(v: RecordVerdict): PinVerdict | undefined {
+  return v.measured ? pinVerdictOf(v.rating as SuitabilityRating) : undefined;
+}
+
+/** The `history` block of one record for one host class. */
+export function historyBlock(
+  record: QualificationRecord,
+  history: readonly HistoryRecord[],
+  hostClass: string,
+  profiles: readonly HostProfile[],
+  options: { file: string; now: number },
+): HistoryBlock {
+  const key = historyKeyOf(record);
+  const found = key === undefined ? undefined : findHistory(history, key.uri, key.digest, hostClass);
+  const verdicts = profiles.flatMap((profile) => {
+    const row = record.verdicts.find((v) => v.host === profile.id);
+    if (row === undefined) return [];
+    const a: Adjustment = adjustVerdict({
+      measured: measuredPinVerdict(row),
+      reasons: row.reasons.map((r) => ({ code: r.code, rating: r.rating })),
+      record: found,
+      profile,
+      now: options.now,
+    });
+    return [{ host: profile.id, ...a }];
+  });
+  return {
+    hostClass,
+    file: options.file,
+    at: new Date(options.now * 1000).toISOString(),
+    ...(key === undefined ? {} : { key }),
+    found: found !== undefined,
+    ...(found === undefined
+      ? {}
+      : {
+          windows: { solo: found.windowsSolo, grouped: found.windowsGrouped },
+          summary: summariseHistory(found, options.now),
+          ...(Object.keys(found.unknownKeys).length === 0 ? {} : { unknownKeys: found.unknownKeys }),
+        }),
+    verdicts,
+  };
+}
+
+export interface AdjustedRecord {
+  readonly path: string;
+  readonly record: QualificationRecord;
+}
+
+export type AdjustResult =
+  | {
+      readonly ok: true;
+      readonly records: readonly AdjustedRecord[];
+      /** The host classes read. */
+      readonly hostClasses: readonly string[];
+      readonly ignored: Extract<HistoryRead, { ok: true }>["ignored"];
+    }
+  | { readonly ok: false; readonly problem: string };
+
+/**
+ * Each record with its `history` block replaced by the blocks of the host classes read (an earlier block of a class not read
+ * is kept, so two histories of two classes can be applied one after the other). The measured fields are copied as they are.
+ */
+export function adjustRecords(
+  records: readonly RecordFile[],
+  historyText: string,
+  options: { profiles: readonly HostProfile[]; file: string; now: number; hostClass?: string },
+): AdjustResult {
+  const read = readHistory(historyText);
+  if (!read.ok) return { ok: false, problem: `${options.file}: ${read.problem}` };
+  const hostClasses = options.hostClass === undefined ? historyClasses(read.records) : [options.hostClass];
+  if (hostClasses.length === 0) return { ok: false, problem: `${options.file} holds no record, so there is no host class to adjust for` };
+  const adjusted = records.map(({ path, record }) => {
+    const fresh = hostClasses.map((c) => historyBlock(record, read.records, c, options.profiles, { file: options.file, now: options.now }));
+    const kept = (record.history ?? []).filter((b) => !hostClasses.includes(b.hostClass));
+    return { path, record: { ...record, history: [...kept, ...fresh].sort((a, b) => (a.hostClass < b.hostClass ? -1 : a.hostClass > b.hostClass ? 1 : 0)) } };
+  });
+  return { ok: true, records: adjusted, hostClasses, ignored: read.ignored };
+}
+
+/** The adjusted verdict of a record's host for a host class: the pin verdict, `null` when it has none, `undefined` when the record holds no block for the pair. */
+export function adjustedVerdictOf(record: QualificationRecord, hostClass: string, host: string): PinVerdict | null | undefined {
+  return record.history?.find((b) => b.hostClass === hostClass)?.verdicts.find((v) => v.host === host)?.adjusted;
+}
+
+/**
+ * The pin entries of adjusted records for one host and one host class: the integrity is the record's, the verdict is the
+ * ADJUSTED one. A record with no verdict row for the host is pinned without a verdict word, as a run without one is.
+ */
+export function adjustedPinEntries(records: readonly AdjustedRecord[], hostClass: string, host: string): PinEntry[] {
+  return records.flatMap(({ record }) => {
+    const key = historyKeyOf(record);
+    if (key === undefined) return [];
+    const adjusted = adjustedVerdictOf(record, hostClass, host);
+    return [
+      {
+        uri: key.uri,
+        integrity: {
+          ...(record.testedVersion === undefined ? {} : { version: record.testedVersion }),
+          files: [...record.binary.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+          layout: record.binary.layout!,
+        },
+        ...(adjusted === null || adjusted === undefined ? {} : { verdict: adjusted }),
+      },
+    ];
+  });
+}
+
+/** One row per plugin, host and host class: the measured verdict, the adjusted one, the reason. */
+export function adjustTable(records: readonly AdjustedRecord[]): string {
+  const rows = records.flatMap(({ record }) =>
+    (record.history ?? []).flatMap((b) =>
+      b.verdicts.map((v) => [record.plugin.id, v.host, b.hostClass, v.measured ?? "-", v.adjusted ?? "-", v.reason]),
+    ),
+  );
+  const head = ["plugin", "host", "host class", "measured", "adjusted", "reason"];
+  const width = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i]!.length)));
+  const line = (r: readonly string[]): string => r.map((c, i) => c.padEnd(width[i]!)).join("  ").trimEnd();
+  return [line(head), ...rows.map(line), ""].join("\n");
+}

package/src/clap-loader.ts

@@ -18,7 +18,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 
 import type { PluginLoader, PluginTarget } from "./loader.js";
-import { lv2BundlesOnPath } from "./lv2-loader.js";
+import { lv2BundlesOnPath, lv2Loader } from "./lv2-loader.js";
 import {
   CLAP_PATH_ENV,
   CLAP_SCAN_TIMEOUT_S,
@@ -464,23 +464,19 @@ export function discoverClapTargets(options: ClapDiscoverOptions = {}): PluginTa
 export interface DiscoverAllOptions extends ClapDiscoverOptions {}
 
 /**
- * The targets of `--all`. The LV2 plugins lilv finds cannot be measured from this entry point, so
- * when the LV2 search path holds any bundle the run refuses (exit 2) and names how many, rather
- * than qualifying only the CLAP side and reporting everything qualified.
+ * The targets of `--all`: every LV2 plugin of the bundles on the LV2 search path ({@link lv2BundlesOnPath}, each
+ * through {@link lv2Loader} as a named bundle is), then every CLAP plugin on the CLAP path. An LV2 URI found in two
+ * bundles keeps the first, as the search path does. A directory that cannot be read is a {@link ClapScanError} naming it.
  */
 export function discoverAllTargets(options: DiscoverAllOptions = {}): PluginTarget[] {
   const env = options.env ?? process.env;
-  let bundles: string[];
+  const lv2 = new Map<string, PluginTarget>();
   try {
-    bundles = lv2BundlesOnPath(env, options.home ?? homedir());
+    for (const bundle of lv2BundlesOnPath(env, options.home ?? homedir())) {
+      for (const t of lv2Loader.resolve(bundle) ?? []) if (!lv2.has(t.uri)) lv2.set(t.uri, t);
+    }
   } catch (e) {
     throw unreadable("the LV2 search path", e);
   }
-  if (bundles.length > 0) {
-    throw new ClapScanError(
-      `--all cannot measure LV2 from this entry point and ${String(bundles.length)} LV2 bundle(s) are on the LV2 path ` +
-        `(first: ${bundles[0]}); name the plugins or bundles to qualify instead, or unset LV2_PATH to an empty directory`,
-    );
-  }
-  return discoverClapTargets(options);
+  return [...lv2.values(), ...discoverClapTargets(options)];
 }

package/src/history-adjust.ts

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * What the running history may do to a measured verdict (the grouping-planner design note, How plugin-qualify uses it).
+ * A pure function of the measured verdict, the reasons behind it, one history record and the clock: it moves a pin
+ * verdict one step toward safer, or promotes `isolated` to `in-process` for a steady plugin whose only fault was a cost
+ * reason, or leaves the measured verdict alone. It never changes the measurement, and it never lifts a verdict that is a
+ * fact about the plugin (real-time safety, a missing feature, a crash in the prober, an `unknown`), nor a `refused`.
+ *
+ * The thresholds are the note's starting values, declared once in {@link HISTORY_POLICY}; the benchmark tunes them.
+ * The summaries (`crashed`, `raises-xruns`) are plugin-hostd's `history_get` rules, read here from the file because
+ * plugin-qualify runs without a daemon.
+ */
+import type { HostProfile } from "./host-profiles.js";
+import type { HistoryRecord } from "./history-file.js";
+import { PIN_VERDICTS, type PinVerdict } from "./pins-file.js";
+
+export const HISTORY_POLICY = {
+  /** plugin-hostd's PHD_HISTORY_KEEP_DAYS: a crash older than this is not read. */
+  keepDays: 30,
+  /** plugin-hostd's PHD_HISTORY_MIN_WINDOWS: grouped windows before an xrun share is read. */
+  minWindows: 30,
+  /** plugin-hostd's PHD_HISTORY_XRUN_MARGIN_PCT: percentage points the grouped xrun share may exceed the solo one by. */
+  xrunMarginPct: 5,
+  /** Solo crashes, on this binary and class within `keepDays`, that demote `isolated` to `refused`. */
+  crashedAloneCount: 3,
+  /** Windows run alone before a promotion is read: 360 windows of 60 s are six hours. */
+  steadyWindowsSolo: 360,
+} as const;
+
+const SECONDS_PER_DAY = 86_400;
+
+/** The codes of the second verdict. Codes, never prose. */
+export const HISTORY_REASON = {
+  crashed: "history.crashed",
+  xrunsGrouped: "history.xruns-grouped",
+  crashedAlone: "history.crashed-alone",
+  steady: "history.steady",
+  /** History has no line for this plugin binary on this host class: the measured verdict stands. */
+  noRecord: "history.no-record",
+  /** The record was read and no rule moves this verdict. */
+  noChange: "history.no-change",
+  /** The record would promote, but the measured verdict is a fact about the plugin and history does not lift it. */
+  notLiftable: "history.not-liftable",
+} as const;
+export type HistoryReasonCode = (typeof HISTORY_REASON)[keyof typeof HISTORY_REASON];
+
+export type HistoryMove = "demote" | "promote" | "none";
+
+/** What the daemon's `history_get` summary says of a record at `now` (UTC seconds). */
+export interface HistorySummary {
+  /** A crash was counted and the latest one is within `keepDays`. */
+  readonly crashed: boolean;
+  /** The grouped windows' share of xruns exceeds the solo share by the margin, over at least `minWindows` grouped windows. */
+  readonly raisesXruns: boolean;
+}
+
+export function summariseHistory(r: HistoryRecord, now: number): HistorySummary {
+  const last = Math.max(r.lastCrash, r.lastCrashGrouped);
+  const crashed = r.crashesSolo + r.crashesGrouped > 0 && now - last <= HISTORY_POLICY.keepDays * SECONDS_PER_DAY;
+  const wg = r.windowsGrouped;
+  const xg = r.xrunWindowsGrouped;
+  const ws = r.windowsSolo;
+  const xs = r.xrunWindowsSolo;
+  const m = HISTORY_POLICY.xrunMarginPct;
+  // xg/wg > xs/ws + m/100, cross-multiplied so no division is rounded
+  const raisesXruns = wg < HISTORY_POLICY.minWindows ? false : ws === 0 ? 100 * xg > m * wg : 100 * xg * ws > 100 * xs * wg + m * wg * ws;
+  return { crashed, raisesXruns };
+}
+
+/** One reason of the measured verdict, as the record holds it. */
+export interface MeasuredReason {
+  readonly code: string;
+  /** The rating the reason contributed to the verdict. */
+  readonly rating: string;
+}
+
+export interface AdjustInput {
+  /** The measured pin verdict of the host, or `undefined` for an `unknown` rating (no verdict word). */
+  readonly measured: PinVerdict | undefined;
+  /** The reasons of the measured verdict, all of them. */
+  readonly reasons: readonly MeasuredReason[];
+  /** The record of this plugin binary on the host class, or `undefined` when the history has none. */
+  readonly record: HistoryRecord | undefined;
+  /** The host the verdict is for; its cost ceiling is the budget a promotion is read against. */
+  readonly profile: HostProfile;
+  /** UTC seconds. */
+  readonly now: number;
+}
+
+export interface Adjustment {
+  readonly measured: PinVerdict | null;
+  readonly adjusted: PinVerdict | null;
+  readonly move: HistoryMove;
+  readonly reason: HistoryReasonCode;
+  /** For `history.not-liftable`: why the measured verdict is not history's to lift: `refused`, `unknown`, or the codes of the reasons that are not cost reasons. */
+  readonly blockedBy?: readonly string[];
+}
+
+const COST_PREFIX = "hosting.cost.";
+
+/**
+ * Why the measured verdict cannot be promoted by history, or an empty list when it can: the verdict must be `isolated`
+ * (conditional), and every reason that is not `suitable` must be a cost reason. A reason of any other dimension
+ * (real-time safety, features, stability, latency, topology) is a measurement of the plugin, not of this machine.
+ */
+function blockers(measured: Exclude<PinVerdict, "in-process"> | undefined, reasons: readonly MeasuredReason[]): string[] {
+  if (measured === undefined) return ["unknown"];
+  if (measured === "refused") return ["refused"];
+  const deciding = reasons.filter((r) => r.rating !== "suitable");
+  const notCost = deciding.filter((r) => !r.code.startsWith(COST_PREFIX)).map((r) => r.code);
+  if (notCost.length > 0) return notCost;
+  // an isolated verdict that no reason explains is not one history can vouch for
+  return deciding.length === 0 ? ["no-deciding-reason"] : [];
+}
+
+function stay(measured: PinVerdict | undefined, reason: HistoryReasonCode, blockedBy?: readonly string[]): Adjustment {
+  return { measured: measured ?? null, adjusted: measured ?? null, move: "none", reason, ...(blockedBy === undefined ? {} : { blockedBy }) };
+}
+
+function move(measured: PinVerdict, adjusted: PinVerdict, reason: HistoryReasonCode): Adjustment {
+  const demote = PIN_VERDICTS.indexOf(adjusted) > PIN_VERDICTS.indexOf(measured);
+  return { measured, adjusted, move: demote ? "demote" : "promote", reason };
+}
+
+/** Whether the record shows a plugin that has run alone long enough, without a crash or a restart, under the host's cost budget. */
+function steady(r: HistoryRecord, profile: HostProfile, summary: HistorySummary): boolean {
+  const budgetPct = profile.cost.coreFractionCeiling * 100;
+  return (
+    r.windowsSolo >= HISTORY_POLICY.steadyWindowsSolo &&
+    r.crashesSolo + r.crashesGrouped === 0 &&
+    r.restartsGrouped === 0 &&
+    !summary.raisesXruns &&
+    r.cpuP95Solo < budgetPct
+  );
+}
+
+/** The second verdict beside the measured one. Demotions are read first and promotions last; a demotion is one step. */
+export function adjustVerdict(input: AdjustInput): Adjustment {
+  const { measured, reasons, record, profile, now } = input;
+  if (record === undefined) return stay(measured, HISTORY_REASON.noRecord);
+  const summary = summariseHistory(record, now);
+  if (measured === "in-process") {
+    if (summary.crashed) return move(measured, "isolated", HISTORY_REASON.crashed);
+    if (summary.raisesXruns) return move(measured, "isolated", HISTORY_REASON.xrunsGrouped);
+    return stay(measured, HISTORY_REASON.noChange);
+  }
+  if (measured === "isolated") {
+    const aloneCrashed = record.crashesSolo >= HISTORY_POLICY.crashedAloneCount && now - record.lastCrash <= HISTORY_POLICY.keepDays * SECONDS_PER_DAY;
+    if (aloneCrashed) return move(measured, "refused", HISTORY_REASON.crashedAlone);
+  }
+  if (!steady(record, profile, summary)) return stay(measured, HISTORY_REASON.noChange);
+  const blocked = blockers(measured, reasons);
+  if (blocked.length > 0) return stay(measured, HISTORY_REASON.notLiftable, blocked);
+  return move("isolated", "in-process", HISTORY_REASON.steady);
+}

package/src/history-file.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The running-history file plugin-hostd writes and `plugin-qualify adjust --history` reads (plugin-hostd's `data/history.json`
+ * and `src/history.c`): a header line, then one line per plugin binary and host class,
+ *
+ *     history <uri> <binary digest> <host class> key=value ...
+ *
+ * The reader keeps the daemon's rules for what it reads: the header must be the one it knows, a line outside the grammar
+ * is not read (and counted, so the caller can say so), a second line of one plugin binary on one host class is not read,
+ * a value is a whole number or a decimal and never negative. It differs in one place on purpose: a key it does not know
+ * is not a reason to skip the line, it is kept on the record (`unknownKeys`) and the known keys are read, so a daemon
+ * that grows a key inside history/1 does not blind the qualifier. Nothing here writes the file; only the daemon does.
+ */
+
+/** The header line of the format this reader knows, plugin-hostd's `PHD_HISTORY_HEADER`. */
+export const HISTORY_HEADER = "# plugin-hostd history/1";
+
+/** The verb a record line starts with, plugin-hostd's `PHD_HISTORY_RECORD`. */
+export const HISTORY_RECORD = "history";
+
+/** How a key's value is written: a whole number (`count`, `time`) or a decimal (`decimal`). */
+type KeyKind = "count" | "time" | "decimal";
+
+/**
+ * PLUGIN_HOSTD_HISTORY_KEYS in the daemon's order, each with the field it fills and how its value is written. The words
+ * are plugin-hostd's (`data/history.json`); `history-file.test.ts` holds this table to them.
+ */
+const KEYS: readonly { readonly word: string; readonly field: keyof HistoryCounters; readonly kind: KeyKind }[] = [
+  { word: "first", field: "first", kind: "time" },
+  { word: "last", field: "last", kind: "time" },
+  { word: "windows_solo", field: "windowsSolo", kind: "count" },
+  { word: "windows_grouped", field: "windowsGrouped", kind: "count" },
+  { word: "cpu_p95_solo", field: "cpuP95Solo", kind: "decimal" },
+  { word: "cpu_max_solo", field: "cpuMaxSolo", kind: "decimal" },
+  { word: "pss_mb_solo", field: "pssMbSolo", kind: "decimal" },
+  { word: "xrun_windows_solo", field: "xrunWindowsSolo", kind: "count" },
+  { word: "xrun_windows_grouped", field: "xrunWindowsGrouped", kind: "count" },
+  { word: "crashes_solo", field: "crashesSolo", kind: "count" },
+  { word: "crashes_grouped", field: "crashesGrouped", kind: "count" },
+  { word: "restarts_grouped", field: "restartsGrouped", kind: "count" },
+  { word: "quarantines", field: "quarantines", kind: "count" },
+  { word: "last_crash", field: "lastCrash", kind: "time" },
+  { word: "last_crash_grouped", field: "lastCrashGrouped", kind: "time" },
+];
+
+/** The words of the keys this reader knows, in the daemon's order. */
+export const HISTORY_KEY_WORDS: readonly string[] = KEYS.map((k) => k.word);
+
+/** The figures of one record. A key the line did not carry reads as 0, as the daemon's record starts at 0. */
+export interface HistoryCounters {
+  /** UTC seconds of the first and the last window. */
+  readonly first: number;
+  readonly last: number;
+  readonly windowsSolo: number;
+  readonly windowsGrouped: number;
+  /** Percent of one core. */
+  readonly cpuP95Solo: number;
+  readonly cpuMaxSolo: number;
+  /** MiB. */
+  readonly pssMbSolo: number;
+  readonly xrunWindowsSolo: number;
+  readonly xrunWindowsGrouped: number;
+  readonly crashesSolo: number;
+  readonly crashesGrouped: number;
+  readonly restartsGrouped: number;
+  readonly quarantines: number;
+  /** UTC seconds of the last crash the plugin was blamed for alone, and in a group. */
+  readonly lastCrash: number;
+  readonly lastCrashGrouped: number;
+}
+
+/** One line of the history: a plugin binary on a host class. */
+export interface HistoryRecord extends HistoryCounters {
+  /** plugin-hostd's uri: `clap:<path of the .clap>#<id>`, or an LV2 plugin's own URI. */
+  readonly uri: string;
+  /** The SHA-256 of the first file of the plugin's pin, 64 lowercase hex digits. */
+  readonly digest: string;
+  /** The machine class the daemon recorded under, `arch/cores/clock`. */
+  readonly hostClass: string;
+  /** The keys of the line this reader does not know, as written: kept, never read. */
+  readonly unknownKeys: Readonly<Record<string, string>>;
+}
+
+export type HistoryRead =
+  | {
+      readonly ok: true;
+      readonly records: readonly HistoryRecord[];
+      /** The lines that were not read, each with the line number and why: outside the grammar, or a second line of one binary and class. */
+      readonly ignored: readonly { readonly line: number; readonly problem: string }[];
+    }
+  | { readonly ok: false; readonly problem: string };
+
+const HEX = /^[0-9a-f]{64}$/;
+const WHOLE = /^[0-9]+$/;
+const DECIMAL = /^([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?$/;
+
+function number(text: string, kind: KeyKind): number | undefined {
+  if (kind === "decimal") {
+    if (!DECIMAL.test(text)) return undefined;
+    const v = Number(text);
+    return Number.isFinite(v) ? v : undefined;
+  }
+  if (!WHOLE.test(text)) return undefined;
+  const v = Number(text);
+  return Number.isSafeInteger(v) ? v : undefined;
+}
+
+/** One record line, or the reason it is outside the grammar. */
+function parseRecord(words: readonly string[]): HistoryRecord | string {
+  if (words.length < 4 || words[0] !== HISTORY_RECORD) return `not a ${HISTORY_RECORD} line with a uri, a digest and a host class`;
+  const [, uri, digest, hostClass] = words as [string, string, string, string];
+  if (!HEX.test(digest)) return `${digest}: not a digest of 64 lowercase hex digits`;
+  const values: Record<string, number> = {};
+  const unknownKeys: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (const word of words.slice(4)) {
+    const eq = word.indexOf("=");
+    if (eq < 0) return `${word}: not key=value`;
+    const key = word.slice(0, eq);
+    const text = word.slice(eq + 1);
+    if (seen.has(key)) return `${key}: given twice`;
+    seen.add(key);
+    const known = KEYS.find((k) => k.word === key);
+    if (known === undefined) {
+      unknownKeys[key] = text;
+      continue;
+    }
+    const v = number(text, known.kind);
+    if (v === undefined) return `${key}=${text}: not ${known.kind === "decimal" ? "a decimal" : "a whole number"}, or negative`;
+    values[known.field] = v;
+  }
+  const counters = Object.fromEntries(KEYS.map((k) => [k.field, values[k.field] ?? 0])) as unknown as HistoryCounters;
+  return { uri, digest, hostClass, ...counters, unknownKeys };
+}
+
+/**
+ * Read the text of a history file. A file whose first line (blank lines apart) is not the header is refused as a whole,
+ * as the daemon blocks it: a version this reader does not know is not read by guessing. Comment lines and blank lines
+ * after the header are skipped.
+ */
+export function readHistory(text: string): HistoryRead {
+  const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
+  const first = lines.findIndex((l) => l.trim() !== "");
+  if (first < 0) return { ok: true, records: [], ignored: [] };
+  if (lines[first] !== HISTORY_HEADER) {
+    return {
+      ok: false,
+      problem: lines[first]!.startsWith("# plugin-hostd history/")
+        ? `${JSON.stringify(lines[first])} is a version this reader does not know (it reads ${HISTORY_HEADER})`
+        : "not a history file: it does not begin with " + HISTORY_HEADER,
+    };
+  }
+  const records: HistoryRecord[] = [];
+  const ignored: { line: number; problem: string }[] = [];
+  for (let i = first + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.trim() === "" || line.startsWith("#")) continue;
+    const parsed = parseRecord(line.split(/[ \t]+/).filter((w) => w !== ""));
+    if (typeof parsed === "string") {
+      ignored.push({ line: i + 1, problem: parsed });
+    } else if (records.some((r) => r.uri === parsed.uri && r.digest === parsed.digest && r.hostClass === parsed.hostClass)) {
+      ignored.push({ line: i + 1, problem: "a second line of one plugin binary on one host class" });
+    } else records.push(parsed);
+  }
+  return { ok: true, records, ignored };
+}
+
+/** The record of one plugin binary on one host class, or `undefined`. */
+export function findHistory(records: readonly HistoryRecord[], uri: string, digest: string, hostClass: string): HistoryRecord | undefined {
+  return records.find((r) => r.uri === uri && r.digest === digest && r.hostClass === hostClass);
+}
+
+/** The host classes a history holds a record for, sorted. */
+export function historyClasses(records: readonly HistoryRecord[]): string[] {
+  return [...new Set(records.map((r) => r.hostClass))].sort();
+}