@openmixer/omx-contract 0.0.0 → 1.0.0

package/include/omxcontract/omx_contract_limits.h

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#ifndef OMX_CONTRACT_LIMITS_H
+#define OMX_CONTRACT_LIMITS_H
+/*
+ * GENERATED — DO NOT EDIT BY HAND.
+ * Produced by `omx-contract render --target c` from FreeMixer/omx-contract's data/, the declaration
+ * as data (each item's reason is its `doc`). Change the data, never this file: a consumer builds
+ * against the render of the omx-contract version it pins and commits none.
+ *
+ * A C contract (OMX_PRE/OMX_POST/OMX_INVARIANT) reads a limit from HERE, never a literal.
+ */
+
+/* Per-parameter numeric travel, one block per `travels` table named <PREFIX>_LIMITS:
+ * OMX_<PREFIX>_<FIELD>_MIN/_MAX/_DEFAULT, float literals. */
+#define OMX_COMP_THRESHOLD_DB_MIN -60.0f
+#define OMX_COMP_THRESHOLD_DB_MAX 0.0f
+#define OMX_COMP_THRESHOLD_DB_DEFAULT -18.0f
+#define OMX_COMP_RATIO_MIN 1.0f
+#define OMX_COMP_RATIO_MAX 20.0f
+#define OMX_COMP_RATIO_DEFAULT 4.0f
+#define OMX_COMP_KNEE_DB_MIN 0.0f
+#define OMX_COMP_KNEE_DB_MAX 24.0f
+#define OMX_COMP_KNEE_DB_DEFAULT 6.0f
+#define OMX_COMP_ATTACK_MS_MIN 0.1f
+#define OMX_COMP_ATTACK_MS_MAX 100.0f
+#define OMX_COMP_ATTACK_MS_DEFAULT 5.0f
+#define OMX_COMP_RELEASE_MS_MIN 5.0f
+#define OMX_COMP_RELEASE_MS_MAX 3000.0f
+#define OMX_COMP_RELEASE_MS_DEFAULT 200.0f
+#define OMX_COMP_MAKEUP_DB_MIN 0.0f
+#define OMX_COMP_MAKEUP_DB_MAX 24.0f
+#define OMX_COMP_MAKEUP_DB_DEFAULT 0.0f
+#define OMX_COMP_MIX_PCT_MIN 0.0f
+#define OMX_COMP_MIX_PCT_MAX 100.0f
+#define OMX_COMP_MIX_PCT_DEFAULT 100.0f
+
+#define OMX_GATE_THRESHOLD_DB_MIN -80.0f
+#define OMX_GATE_THRESHOLD_DB_MAX 0.0f
+#define OMX_GATE_THRESHOLD_DB_DEFAULT -40.0f
+#define OMX_GATE_RANGE_DB_MIN -90.0f
+#define OMX_GATE_RANGE_DB_MAX 0.0f
+#define OMX_GATE_RANGE_DB_DEFAULT -90.0f
+#define OMX_GATE_KNEE_START_DB_MIN -80.0f
+#define OMX_GATE_KNEE_START_DB_MAX 0.0f
+#define OMX_GATE_KNEE_START_DB_DEFAULT -43.0f
+#define OMX_GATE_KNEE_END_DB_MIN -80.0f
+#define OMX_GATE_KNEE_END_DB_MAX 0.0f
+#define OMX_GATE_KNEE_END_DB_DEFAULT -37.0f
+#define OMX_GATE_ATTACK_MS_MIN 0.0f
+#define OMX_GATE_ATTACK_MS_MAX 500.0f
+#define OMX_GATE_ATTACK_MS_DEFAULT 1.0f
+#define OMX_GATE_HOLD_MS_MIN 0.0f
+#define OMX_GATE_HOLD_MS_MAX 2000.0f
+#define OMX_GATE_HOLD_MS_DEFAULT 10.0f
+#define OMX_GATE_RELEASE_MS_MIN 0.0f
+#define OMX_GATE_RELEASE_MS_MAX 5000.0f
+#define OMX_GATE_RELEASE_MS_DEFAULT 100.0f
+#define OMX_GATE_HYSTERESIS_DB_MIN 0.0f
+#define OMX_GATE_HYSTERESIS_DB_MAX 24.0f
+#define OMX_GATE_HYSTERESIS_DB_DEFAULT 3.0f
+#define OMX_GATE_RATIO_MIN 1.0f
+#define OMX_GATE_RATIO_MAX 100.0f
+#define OMX_GATE_RATIO_DEFAULT 16.0f
+
+#define OMX_LIMITER_CEILING_DB_MIN -12.0f
+#define OMX_LIMITER_CEILING_DB_MAX 0.0f
+#define OMX_LIMITER_CEILING_DB_DEFAULT -1.0f
+#define OMX_LIMITER_LOOKAHEAD_MS_MIN 0.5f
+#define OMX_LIMITER_LOOKAHEAD_MS_MAX 5.0f
+#define OMX_LIMITER_LOOKAHEAD_MS_DEFAULT 1.5f
+#define OMX_LIMITER_RELEASE_MS_MIN 1.0f
+#define OMX_LIMITER_RELEASE_MS_MAX 1000.0f
+#define OMX_LIMITER_RELEASE_MS_DEFAULT 50.0f
+
+#define OMX_PITCH_SEMITONES_MIN -12.0f
+#define OMX_PITCH_SEMITONES_MAX 12.0f
+#define OMX_PITCH_SEMITONES_DEFAULT 0.0f
+#define OMX_PITCH_CENTS_MIN -50.0f
+#define OMX_PITCH_CENTS_MAX 50.0f
+#define OMX_PITCH_CENTS_DEFAULT 0.0f
+#define OMX_PITCH_MIX_MIN 0.0f
+#define OMX_PITCH_MIX_MAX 100.0f
+#define OMX_PITCH_MIX_DEFAULT 100.0f
+
+#define OMX_TRANSIENT_ATTACK_DB_MIN -24.0f
+#define OMX_TRANSIENT_ATTACK_DB_MAX 24.0f
+#define OMX_TRANSIENT_ATTACK_DB_DEFAULT 0.0f
+#define OMX_TRANSIENT_SUSTAIN_DB_MIN -24.0f
+#define OMX_TRANSIENT_SUSTAIN_DB_MAX 24.0f
+#define OMX_TRANSIENT_SUSTAIN_DB_DEFAULT 0.0f
+#define OMX_TRANSIENT_ATTACK_TIME_MS_MIN 2.0f
+#define OMX_TRANSIENT_ATTACK_TIME_MS_MAX 50.0f
+#define OMX_TRANSIENT_ATTACK_TIME_MS_DEFAULT 10.0f
+#define OMX_TRANSIENT_SUSTAIN_TIME_MS_MIN 50.0f
+#define OMX_TRANSIENT_SUSTAIN_TIME_MS_MAX 2000.0f
+#define OMX_TRANSIENT_SUSTAIN_TIME_MS_DEFAULT 250.0f
+#define OMX_TRANSIENT_OUTPUT_DB_MIN -24.0f
+#define OMX_TRANSIENT_OUTPUT_DB_MAX 12.0f
+#define OMX_TRANSIENT_OUTPUT_DB_DEFAULT 0.0f
+
+/* The second C spelling of a travel, its item's `c.alias` { fact, field }:
+ * OMX_<FACT>_<FIELD>_MIN/_MAX/_DEFAULT. Removed by a MAJOR release once no consumer reads it. */
+#define OMX_DELAY_TIME_MS_MIN 0.0f
+#define OMX_DELAY_TIME_MS_MAX 2000.0f
+#define OMX_DELAY_TIME_MS_DEFAULT 300.0f
+
+/* Every scalar, sheet leaf and single travel's numbers, one block sorted by macro. An integer value
+ * is an integer literal, any other a float literal AND its OMX_<macro>_DOUBLE spelling. */
+#define OMX_ALLPASS_UNITY_TOLERANCE 0.0001f
+#define OMX_ALLPASS_UNITY_TOLERANCE_DOUBLE 0.0001
+#define OMX_BUTTERWORTH_Q 0.7071067811865476f
+#define OMX_BUTTERWORTH_Q_DOUBLE 0.7071067811865476
+#define OMX_CHORUS_SPREAD_RANGE_DEFAULT 0
+#define OMX_CHORUS_SPREAD_RANGE_MAX 0.5f
+#define OMX_CHORUS_SPREAD_RANGE_MAX_DOUBLE 0.5
+#define OMX_CHORUS_SPREAD_RANGE_MIN 0
+#define OMX_CHORUS_SPREAD_RANGE_STEP 0.01f
+#define OMX_CHORUS_SPREAD_RANGE_STEP_DOUBLE 0.01
+#define OMX_DELAY_MIX_RANGE_BY_KIND_FX_RETURN 1
+#define OMX_DELAY_MIX_RANGE_DEFAULT 0.3f
+#define OMX_DELAY_MIX_RANGE_DEFAULT_DOUBLE 0.3
+#define OMX_DELAY_MIX_RANGE_MAX 1
+#define OMX_DELAY_MIX_RANGE_MIN 0
+#define OMX_DELAY_MIX_RANGE_STEP 0
+#define OMX_DELAY_TONE_RANGE_DEFAULT 0.3f
+#define OMX_DELAY_TONE_RANGE_DEFAULT_DOUBLE 0.3
+#define OMX_DELAY_TONE_RANGE_MAX 1
+#define OMX_DELAY_TONE_RANGE_MIN 0
+#define OMX_DELAY_TONE_RANGE_STEP 0
+#define OMX_DRIVE_BIAS_MAX 0.7071067811865476f
+#define OMX_DRIVE_BIAS_MAX_DOUBLE 0.7071067811865476
+#define OMX_DSP_KNOB_REFERENCE_RATE 96000
+#define OMX_EQ_MAX_BANDS 24
+#define OMX_FDELAY_MOD_READ_ORDER 3
+#define OMX_FDELAY_READ_L1_NORM 1.25f
+#define OMX_FDELAY_READ_L1_NORM_DOUBLE 1.25
+#define OMX_FX_DELAY_FEEDBACK_RANGE_DEFAULT 0.3f
+#define OMX_FX_DELAY_FEEDBACK_RANGE_DEFAULT_DOUBLE 0.3
+#define OMX_FX_DELAY_FEEDBACK_RANGE_MAX 0.99f
+#define OMX_FX_DELAY_FEEDBACK_RANGE_MAX_DOUBLE 0.99
+#define OMX_FX_DELAY_FEEDBACK_RANGE_MIN 0
+#define OMX_FX_DELAY_FEEDBACK_RANGE_STEP 0
+#define OMX_FX_DELAY_TIME_RANGE_DEFAULT 300
+#define OMX_FX_DELAY_TIME_RANGE_MAX 2000
+#define OMX_FX_DELAY_TIME_RANGE_MIN 0
+#define OMX_FX_DELAY_TIME_RANGE_STEP 1
+#define OMX_GEQ_BANDS 31
+#define OMX_PITCH_PREFILTER_CEILING_HZ 20000
+#define OMX_PITCH_PREFILTER_Q 0.7071067811865476f
+#define OMX_PITCH_PREFILTER_Q_DOUBLE 0.7071067811865476
+#define OMX_PITCH_WINDOW_MS 40
+#define OMX_PROGRAM_RELEASE_CHARGE_MS 1000
+#define OMX_PROGRAM_RELEASE_DISCHARGE_MS 5000
+#define OMX_PROGRAM_RELEASE_PROFILES_OPTO_FAST_MS 70
+#define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SHARE 0.5f
+#define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SHARE_DOUBLE 0.5
+#define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SLOW_MAX_MS 1100
+#define OMX_PROGRAM_RELEASE_PROFILES_OPTO_SLOW_MIN_MS 110
+#define OMX_REVERB_PLATE_MOD_DEPTH_RANGE_DEFAULT 100
+#define OMX_REVERB_PLATE_MOD_DEPTH_RANGE_MAX 400
+#define OMX_REVERB_PLATE_MOD_DEPTH_RANGE_MIN 0
+#define OMX_REVERB_PLATE_MOD_DEPTH_RANGE_STEP 1
+#define OMX_RT_HARD_TARGET_QUANTUM 128
+#define OMX_RT_HARD_TARGET_RATE 192000
+#define OMX_TRANSIENT_FAST_ATTACK_MS 0.5f
+#define OMX_TRANSIENT_FAST_ATTACK_MS_DOUBLE 0.5
+#define OMX_TRANSIENT_FAST_RELEASE_MS 20
+#define OMX_TRANSIENT_FLOOR_LIN 0.00001f
+#define OMX_TRANSIENT_FLOOR_LIN_DOUBLE 0.00001
+#define OMX_TRANSIENT_REF_DB 6
+#define OMX_XOVER_LR2_SECTION_Q 0.5f
+#define OMX_XOVER_LR2_SECTION_Q_DOUBLE 0.5
+#define OMX_XOVER_LR4_SECTION_Q 0.7071067811865476f
+#define OMX_XOVER_LR4_SECTION_Q_DOUBLE 0.7071067811865476
+#define OMX_XOVER_PARTITION_TOLERANCE 0.00001f
+#define OMX_XOVER_PARTITION_TOLERANCE_DOUBLE 0.00001
+
+/* Every list rendered to C, sorted by list: OMX_<LIST>_COUNT and OMX_<LIST>_INIT { a, b, … }. */
+#define OMX_STANDARD_SAMPLE_RATES_COUNT 6u
+#define OMX_STANDARD_SAMPLE_RATES_INIT { 44100, 48000, 88200, 96000, 176400, 192000 }
+
+#endif /* OMX_CONTRACT_LIMITS_H */
+
+/* The sample rates the console declares (core's STANDARD_SAMPLE_RATES, row-codecs.ts): the set a
+ * contract's rate-is-declared precondition accepts, through omx_rate_is_declared(), and the grid a
+ * native tool iterates. Guarded on its own so a tool built against a pinned copy of this header
+ * (lv2-inprocess-pin.sh) can include this tree's copy after it and gain the rates without mixing
+ * the pin's limits. */
+#ifndef OMX_DECLARED_RATE_COUNT
+#define OMX_DECLARED_RATE_COUNT 6u
+static const float OMX_DECLARED_RATES[OMX_DECLARED_RATE_COUNT] = { 44100.0f, 48000.0f, 88200.0f, 96000.0f, 176400.0f, 192000.0f };
+/* The declared rates that are whole multiples of `base` (a tool's default grid: the 48 kHz family),
+ * in declaration order, at most `cap` of them; returns how many were written to `out`. */
+static inline int omx_declared_rates_multiple_of(unsigned base, int *out, int cap) {
+  int n = 0;
+  for (unsigned k = 0; k < OMX_DECLARED_RATE_COUNT && n < cap; k++)
+    if ((unsigned)OMX_DECLARED_RATES[k] % base == 0) out[n++] = (int)OMX_DECLARED_RATES[k];
+  return n;
+}
+#endif

package/include/omxcontract/params/omx_delay_params.h

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#ifndef OMX_DELAY_PARAMS_H
+#define OMX_DELAY_PARAMS_H
+/*
+ * GENERATED — DO NOT EDIT BY HAND.
+ * Produced by `omx-contract render --target c` from FreeMixer/omx-contract's data/plugins/delay.json
+ * (DELAY_PLUGIN): FX_DELAY_TIME_RANGE, FX_DELAY_FEEDBACK_RANGE, DELAY_MIX_RANGE for kind input, DELAY_TONE_RANGE, FX_DELAY_PINGPONG_DEFAULT.
+ * Change the data, never this file. Order is append-only (omx-contract spec §3.3).
+ */
+#include "omx_plugin_param.h"
+
+enum {
+  OMX_DELAY_PARAM_TIME_MS = 0,
+  OMX_DELAY_PARAM_FEEDBACK = 1,
+  OMX_DELAY_PARAM_MIX = 2,
+  OMX_DELAY_PARAM_TONE = 3,
+  OMX_DELAY_PARAM_PINGPONG = 4,
+  OMX_DELAY_PARAM_COUNT = 5
+};
+
+static const omx_plugin_param OMX_DELAY_PARAMS[OMX_DELAY_PARAM_COUNT] = {
+  { "timeMs", "Time", "ms", 0.0f, 2000.0f, 300.0f, OMX_PLUGIN_PARAM_INTEGER },
+  { "feedback", "Feedback", "", 0.0f, 0.99f, 0.3f, 0u },
+  { "mix", "Mix", "", 0.0f, 1.0f, 0.3f, 0u },
+  { "tone", "Tone", "", 0.0f, 1.0f, 0.3f, 0u },
+  { "pingpong", "Pingpong", "", 0.0f, 1.0f, 0.0f, OMX_PLUGIN_PARAM_TOGGLE },
+};
+
+/* One macro per declared bound: what a C face reads where a constant is needed. */
+#define OMX_DELAY_PARAM_TIME_MS_MIN 0.0f
+#define OMX_DELAY_PARAM_TIME_MS_MAX 2000.0f
+#define OMX_DELAY_PARAM_TIME_MS_DEFAULT 300.0f
+#define OMX_DELAY_PARAM_FEEDBACK_MIN 0.0f
+#define OMX_DELAY_PARAM_FEEDBACK_MAX 0.99f
+#define OMX_DELAY_PARAM_FEEDBACK_DEFAULT 0.3f
+#define OMX_DELAY_PARAM_MIX_MIN 0.0f
+#define OMX_DELAY_PARAM_MIX_MAX 1.0f
+#define OMX_DELAY_PARAM_MIX_DEFAULT 0.3f
+#define OMX_DELAY_PARAM_TONE_MIN 0.0f
+#define OMX_DELAY_PARAM_TONE_MAX 1.0f
+#define OMX_DELAY_PARAM_TONE_DEFAULT 0.3f
+#define OMX_DELAY_PARAM_PINGPONG_MIN 0.0f
+#define OMX_DELAY_PARAM_PINGPONG_MAX 1.0f
+#define OMX_DELAY_PARAM_PINGPONG_DEFAULT 0.0f
+
+#endif /* OMX_DELAY_PARAMS_H */

package/include/omxcontract/params/omx_plugin_param.h

@@ -0,0 +1,25 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later
+ * Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+ *
+ * omx_plugin_param.h — the SHAPE of one generated plugin parameter, and nothing else: no number
+ * lives here. The rows are rendered by `omx-contract render --target c` into omx_<plugin>_params.h
+ * beside this file, from FreeMixer/omx-contract's data/plugins/ (omx-contract spec §4.2); a DPF
+ * plugin's initParameter reads them and types no range of its own.
+ */
+#ifndef OMX_PLUGIN_PARAM_H
+#define OMX_PLUGIN_PARAM_H
+
+/** A whole-number travel (declared `step` >= 1 over integer bounds). */
+#define OMX_PLUGIN_PARAM_INTEGER 1u
+/** A declared boolean: domain {0, 1}, the come-up value declared. */
+#define OMX_PLUGIN_PARAM_TOGGLE 2u
+
+typedef struct {
+  const char *symbol; /* the declared field name — the LV2 symbol, the CLAP param's identity */
+  const char *name;   /* derived from the symbol, never a label table */
+  const char *unit;
+  float min, max, def;
+  unsigned flags;
+} omx_plugin_param;
+
+#endif /* OMX_PLUGIN_PARAM_H */

package/lib/data.mjs

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The declaration as data: load every `data/**.json` file, then resolve each item's references
+ * and derivations into plain values. The renderers are pure functions of the resolved items.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/** Every `.json` file under `dir`, sorted by its path relative to `dir`. */
+export function dataFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const f of readdirSync(d).sort()) {
+      const p = join(d, f);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (f.endsWith('.json')) out.push(p);
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => (relative(dir, a) < relative(dir, b) ? -1 : 1));
+}
+
+/**
+ * The raw data: `{ files: [{ path, rel, doc }], items: Map<name, { name, rel, item }> }`, items in
+ * file order then key order. `files` may be handed in as `{ rel: text }` (a tag's data, a test).
+ * @throws naming the file when one is not JSON, and an item declared by two files.
+ */
+export function loadData(dir, texts) {
+  const files = [];
+  const entries = texts ? Object.entries(texts).sort(([a], [b]) => (a < b ? -1 : 1)) : dataFiles(dir).map((p) => [relative(join(dir, '..'), p), readFileSync(p, 'utf8')]);
+  const items = new Map();
+  for (const [rel, text] of entries) {
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { throw new Error(`${rel}: not JSON: ${e.message}`); }
+    files.push({ rel, text, doc });
+    for (const [name, item] of Object.entries(doc)) {
+      if (name === '$schema') continue;
+      if (items.has(name)) throw new Error(`${rel}: ${name}: already declared by ${items.get(name).rel}`);
+      items.set(name, { name, rel, item });
+    }
+  }
+  return { files, items };
+}
+
+/** An item's own value before resolution, by kind. */
+export function rawValue(item) {
+  switch (item.kind) {
+    case 'scalar': return item.value;
+    case 'travels': return item.fields ?? item.travel;
+    case 'sheet': return item.value;
+    case 'list': return item.values;
+    case 'plugin': return item.params;
+    default: return undefined;
+  }
+}
+
+/** The closed list of derivations (spec §3.3). A new one is a change here with its own test. */
+export const DERIVATIONS = {
+  count: (d, val) => {
+    const v = val(typeof d.of === 'string' ? { ref: d.of } : d.of);
+    if (!Array.isArray(v)) throw new Error(`count: ${JSON.stringify(d.of)} is not a list`);
+    return v.length;
+  },
+  sqrt: (d, val) => {
+    const v = val(d.of);
+    if (typeof v !== 'number' || v < 0) throw new Error(`sqrt: ${JSON.stringify(d.of)} is not a non-negative number`);
+    return Math.sqrt(v);
+  },
+  lagrangeReadL1: (d, val) => {
+    const order = val(d.order);
+    if (!Number.isInteger(order) || order < 1) throw new Error(`lagrangeReadL1: order ${order} is not a positive integer`);
+    return lagrangeReadL1(order);
+  },
+};
+
+/** The taps of the order-`order` Lagrange fractional read at fraction `f` (the fdelay kernel's read). */
+export function lagrangeReadTaps(order, f) {
+  const off = Math.floor((order - 1) / 2);
+  const c = [];
+  for (let k = 0; k <= order; k++) {
+    let num = 1;
+    let den = 1;
+    for (let j = 0; j <= order; j++) {
+      if (j === k) continue;
+      num *= f - (j - off);
+      den *= k - j;
+    }
+    c.push(num / den);
+  }
+  return c;
+}
+
+/** The worst L1 norm of the read over 1024 fractions, rounded to 1e-9 (core's readKernelL1Norm). */
+export function lagrangeReadL1(order) {
+  const FRACTION_STEPS = 1024;
+  let worst = 0;
+  for (let i = 0; i < FRACTION_STEPS; i++) {
+    const l1 = lagrangeReadTaps(order, i / FRACTION_STEPS).reduce((a, c) => a + Math.abs(c), 0);
+    if (l1 > worst) worst = l1;
+  }
+  return Math.round(worst * 1e9) / 1e9;
+}
+
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/**
+ * Resolve every item: `{ name, rel, kind, doc, why?, unit?, c?, shape?, value }`, where `value` has
+ * every `{ref}` and `{derive}` evaluated. A plugin's value is its parameters resolved against the
+ * items they read.
+ * @throws naming the item: a reference that does not resolve, a cycle, an unknown derivation.
+ */
+export function resolveData(data) {
+  const done = new Map();
+  const busy = new Set();
+  const lookup = (path, from) => {
+    const [head, ...rest] = path.split('.');
+    const entry = data.items.get(head);
+    if (!entry) throw new Error(`${from}: reference ${path}: no item ${head}`);
+    let v = resolveItem(head).value;
+    for (const k of rest) {
+      if (!isObj(v) || !(k in v)) throw new Error(`${from}: reference ${path}: ${head} has no ${k}`);
+      v = v[k];
+    }
+    return v;
+  };
+  const val = (v, from) => {
+    if (Array.isArray(v)) return v.map((x) => val(x, from));
+    if (!isObj(v)) return v;
+    if ('ref' in v) return lookup(v.ref, from);
+    if ('derive' in v) {
+      const fn = DERIVATIONS[v.derive];
+      if (!fn) throw new Error(`${from}: unknown derivation ${v.derive}`);
+      try { return fn(v, (x) => val(x, from)); } catch (e) { throw new Error(`${from}: ${e.message}`); }
+    }
+    return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, val(x, from)]));
+  };
+  function resolveItem(name) {
+    if (done.has(name)) return done.get(name);
+    if (busy.has(name)) throw new Error(`${name}: reference cycle through ${[...busy].join(' -> ')} -> ${name}`);
+    busy.add(name);
+    const { rel, item } = data.items.get(name);
+    const r = { name, rel, kind: item.kind, doc: item.doc };
+    if (item.why !== undefined) r.why = item.why;
+    if (item.unit !== undefined) r.unit = item.unit;
+    if (item.c !== undefined) r.c = item.c;
+    if (item.kind === 'travels') r.shape = item.fields ? 'table' : 'travel';
+    if (item.kind === 'plugin') {
+      for (const k of ['plugin', 'header', 'prefix', 'source']) r[k] = item[k];
+      r.value = item.params.map((p) => resolveParam(name, p));
+    } else {
+      r.value = val(rawValue(item), name);
+    }
+    busy.delete(name);
+    done.set(name, r);
+    return r;
+  }
+  function resolveParam(plugin, p) {
+    const from = `${plugin}.${p.symbol}`;
+    const read = lookup(p.from, from);
+    const toggle = (p.flags ?? []).includes('toggle');
+    if (toggle) {
+      if (typeof read !== 'boolean') throw new Error(`${from}: a toggle reads a boolean, ${p.from} is ${JSON.stringify(read)}`);
+      return { symbol: p.symbol, min: 0, max: 1, def: read ? 1 : 0, step: 1, unit: '', toggle: true };
+    }
+    if (!isObj(read)) throw new Error(`${from}: ${p.from} is not a travel`);
+    let def = read.default;
+    if (p.forKind !== undefined) def = read.byKind?.[p.forKind] ?? read.default;
+    for (const [k, v] of [['min', read.min], ['max', read.max], ['default', def], ['step', read.step], ['unit', read.unit]]) {
+      if (v === undefined) throw new Error(`${from}: ${p.from} declares no ${k}`);
+    }
+    return { symbol: p.symbol, min: read.min, max: read.max, def, step: read.step, unit: read.unit, toggle: false };
+  }
+  const out = new Map();
+  for (const name of data.items.keys()) out.set(name, resolveItem(name));
+  return out;
+}
+
+/** The package version (package.json), which names the tag, the release and the npm version. */
+export function packageVersion(root) {
+  return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+}

package/lib/fmt.mjs

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The one formatting of a data file (spec §3.2): two-space indent, one key per line, keys in schema
+ * order, a trailing newline. Names (items, fields, sheet keys) keep the order the author gave them:
+ * a travels table's field order is its C block order.
+ */
+
+const ORDER = {
+  item: ['kind', 'doc', 'why', 'unit', 'plugin', 'header', 'prefix', 'source', 'value', 'values', 'fields', 'travel', 'params', 'c'],
+  travel: ['min', 'max', 'step', 'unit', 'default', 'defaultFrom', 'byKind', 'doc', 'why'],
+  param: ['symbol', 'from', 'forKind', 'flags', 'scale', 'since', 'doc'],
+  c: ['alias', 'render'],
+  alias: ['fact', 'field'],
+  number: ['ref', 'derive', 'of', 'order'],
+};
+
+function ordered(obj, order) {
+  const known = order.filter((k) => k in obj);
+  const rest = Object.keys(obj).filter((k) => !order.includes(k));
+  return Object.fromEntries([...known, ...rest].map((k) => [k, obj[k]]));
+}
+
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+function number(v) {
+  if (!isObj(v)) return v;
+  return Object.fromEntries(Object.entries(ordered(v, ORDER.number)).map(([k, x]) => [k, number(x)]));
+}
+
+function sheet(v) {
+  if (!isObj(v) || 'ref' in v || 'derive' in v) return number(v);
+  return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, sheet(x)]));
+}
+
+function travel(t) {
+  const o = ordered(t, ORDER.travel);
+  for (const k of ['min', 'max', 'step', 'default']) if (k in o) o[k] = number(o[k]);
+  if (isObj(o.byKind)) o.byKind = Object.fromEntries(Object.entries(o.byKind).map(([k, x]) => [k, number(x)]));
+  return o;
+}
+
+function item(it) {
+  if (!isObj(it)) return it;
+  const o = ordered(it, ORDER.item);
+  if ('value' in o) o.value = o.kind === 'sheet' ? sheet(o.value) : number(o.value);
+  if (isObj(o.fields)) o.fields = Object.fromEntries(Object.entries(o.fields).map(([k, t]) => [k, isObj(t) ? travel(t) : t]));
+  if (isObj(o.travel)) o.travel = travel(o.travel);
+  if (Array.isArray(o.params)) o.params = o.params.map((p) => (isObj(p) ? ordered(p, ORDER.param) : p));
+  if (isObj(o.c)) {
+    o.c = ordered(o.c, ORDER.c);
+    if (isObj(o.c.alias)) o.c.alias = ordered(o.c.alias, ORDER.alias);
+  }
+  return o;
+}
+
+/** The canonical text of a parsed data file. */
+export function formatDoc(doc) {
+  const out = {};
+  if ('$schema' in doc) out.$schema = doc.$schema;
+  for (const [k, v] of Object.entries(doc)) if (k !== '$schema') out[k] = item(v);
+  return `${JSON.stringify(out, null, 2)}\n`;
+}

package/lib/semver.mjs

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * `omx-contract semver`: classify every change between two resolved declarations (spec §3.6) and
+ * refuse a version whose bump is shorter than the largest class found.
+ *
+ *   major  an item, field, parameter or alias removed; a unit or kind changed; a travel narrowed; a
+ *          plugin's parameters reordered or changed; a constant a kernel computes with changed (a
+ *          scalar, sheet leaf or derived value that is not a travel bound or default; a list member
+ *          changed or removed)
+ *   minor  an item, field, sheet leaf, parameter or list member added (appended); a travel widened;
+ *          a default moved inside its travel; a step changed
+ *   patch  doc and why text
+ */
+
+const RANK = { none: 0, patch: 1, minor: 2, major: 3 };
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function travelChanges(at, a, b, say) {
+  if (b.min > a.min) say('major', `${at}: travel narrowed (min ${a.min} -> ${b.min})`);
+  if (b.max < a.max) say('major', `${at}: travel narrowed (max ${a.max} -> ${b.max})`);
+  if (b.min < a.min || b.max > a.max) say('minor', `${at}: travel widened ([${a.min}, ${a.max}] -> [${b.min}, ${b.max}])`);
+  if (a.unit !== b.unit) say('major', `${at}: unit ${JSON.stringify(a.unit)} -> ${JSON.stringify(b.unit)}`);
+  if (a.default !== b.default) say(a.default === undefined || b.default === undefined ? 'major' : 'minor', `${at}: default ${a.default} -> ${b.default}`);
+  if (a.step !== b.step) say('minor', `${at}: step ${a.step} -> ${b.step}`);
+  if (a.defaultFrom !== b.defaultFrom) say('minor', `${at}: defaultFrom ${a.defaultFrom} -> ${b.defaultFrom}`);
+  const ka = a.byKind ?? {};
+  const kb = b.byKind ?? {};
+  for (const k of Object.keys(ka)) if (!(k in kb)) say('major', `${at}.byKind.${k} removed`);
+  for (const k of Object.keys(kb)) {
+    if (!(k in ka)) say('minor', `${at}.byKind.${k} added`);
+    else if (ka[k] !== kb[k]) say('minor', `${at}.byKind.${k}: ${ka[k]} -> ${kb[k]}`);
+  }
+  if ((a.doc ?? '') !== (b.doc ?? '') || (a.why ?? '') !== (b.why ?? '')) say('patch', `${at}: doc`);
+}
+
+function leafChanges(at, a, b, say) {
+  if (typeof a === 'object' && a !== null && typeof b === 'object' && b !== null) {
+    for (const k of Object.keys(a)) {
+      if (!(k in b)) say('major', `${at}.${k} removed`);
+      else leafChanges(`${at}.${k}`, a[k], b[k], say);
+    }
+    for (const k of Object.keys(b)) if (!(k in a)) say('minor', `${at}.${k} added`);
+  } else if (a !== b) {
+    say('major', `${at}: ${JSON.stringify(a)} -> ${JSON.stringify(b)} (a constant a kernel computes with)`);
+  }
+}
+
+/** `{ level, changes: [{ level, item, what }] }` from `prev` to `next` (Maps name -> resolved item). */
+export function classify(prev, next) {
+  const changes = [];
+  for (const [name, a] of prev) {
+    const say = (level, what) => changes.push({ level, item: name, what });
+    const b = next.get(name);
+    if (!b) { say('major', 'item removed or renamed'); continue; }
+    if (a.kind !== b.kind || (a.shape ?? '') !== (b.shape ?? '')) { say('major', `kind ${a.kind} -> ${b.kind}`); continue; }
+    if ((a.unit ?? '') !== (b.unit ?? '')) say('major', `unit ${JSON.stringify(a.unit)} -> ${JSON.stringify(b.unit)}`);
+    if (a.doc !== b.doc || (a.why ?? '') !== (b.why ?? '')) say('patch', 'doc');
+    if (!same(a.c?.alias, b.c?.alias)) say(a.c?.alias ? 'major' : 'minor', a.c?.alias ? 'c.alias removed or renamed' : 'c.alias added');
+    if (!same(a.c?.render, b.c?.render)) say(b.c?.render === false ? 'major' : 'minor', 'C render of the list changed');
+    switch (a.kind) {
+      case 'travels':
+        if (a.shape === 'travel') travelChanges(name, a.value, b.value, say);
+        else {
+          for (const f of Object.keys(a.value)) {
+            if (!(f in b.value)) say('major', `${name}.${f} removed`);
+            else travelChanges(`${name}.${f}`, a.value[f], b.value[f], say);
+          }
+          for (const f of Object.keys(b.value)) if (!(f in a.value)) say('minor', `${name}.${f} added`);
+        }
+        break;
+      case 'scalar':
+      case 'sheet':
+        leafChanges(name, a.value, b.value, say);
+        break;
+      case 'list':
+        a.value.forEach((v, i) => {
+          if (i >= b.value.length) say('major', `${name}[${i}] removed`);
+          else if (b.value[i] !== v) say('major', `${name}[${i}]: ${v} -> ${b.value[i]}`);
+        });
+        if (b.value.length > a.value.length) say('minor', `${name}: ${b.value.length - a.value.length} member(s) appended`);
+        break;
+      case 'plugin':
+        for (const k of ['plugin', 'header', 'prefix']) if (a[k] !== b[k]) say('major', `${k} ${a[k]} -> ${b[k]}`);
+        if (a.source !== b.source) say('patch', 'source text');
+        a.value.forEach((p, i) => {
+          const q = b.value[i];
+          if (!q) say('major', `parameter ${p.symbol} removed`);
+          else if (q.symbol !== p.symbol) say('major', `parameter ${i} ${p.symbol} -> ${q.symbol} (reordered or renamed)`);
+          else if (!same(p, q)) say(p.min < q.min || p.max > q.max || p.unit !== q.unit || p.toggle !== q.toggle ? 'major' : 'minor', `parameter ${p.symbol} changed`);
+        });
+        if (b.value.length > a.value.length) say('minor', `${b.value.length - a.value.length} parameter(s) appended`);
+        break;
+      default:
+        break;
+    }
+  }
+  for (const name of next.keys()) if (!prev.has(name)) changes.push({ level: 'minor', item: name, what: 'item added' });
+  const level = changes.reduce((m, c) => (RANK[c.level] > RANK[m] ? c.level : m), 'none');
+  return { level, changes };
+}
+
+const parse = (v) => {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  if (!m) throw new Error(`not a version: ${v}`);
+  return m.slice(1).map(Number);
+};
+
+/** The class of the bump from version `from` to `to`: 'major' | 'minor' | 'patch' | 'none'; throws if `to` is lower. */
+export function bumpOf(from, to) {
+  const [a, b] = [parse(from), parse(to)];
+  for (let i = 0; i < 3; i++) {
+    if (b[i] > a[i]) return ['major', 'minor', 'patch'][i];
+    if (b[i] < a[i]) throw new Error(`version ${to} is lower than ${from}`);
+  }
+  return 'none';
+}
+
+/** null when bumping `from` -> `to` covers `level`, else the refusal. */
+export function refusal(level, from, to) {
+  let bump;
+  try { bump = bumpOf(from, to); } catch (e) { return e.message; }
+  return RANK[bump] >= RANK[level] ? null : `the changes since ${from} are ${level.toUpperCase()}, and ${from} -> ${to} is a ${bump} bump`;
+}