@openmixer/omx-contract 1.3.0 → 2.0.0

package/README.md

@@ -12,6 +12,7 @@ omx-dsp needs, 1.1.0 adds the flanger, de-esser, phaser, rotary, tremolo and gra
 RTA constants, the EQ band budget, the choice enums (as the `set` kind), the EQ band counts and the
 one rule that gives a fresh EQ its bands, the measurement rate sets and the bus input cap. What is
 declared here is declared nowhere else: the EQ band budget that 1.2.0 left in openmixer is here too.
+2.0.0 changes how a kernel file is written, not what it declares: every render is the same.
 
 ```
 data/                        the declaration, one file per group, edited by hand
@@ -30,6 +31,37 @@ tools/seed/                  the one-time seed from openmixer's built core (prov
 packaging/ debian/           omx-contract-devel (RPM), libomx-contract-dev (deb)
 ```
 
+## The kernel file
+
+A kernel file, `data/kernels/<kernel>.json`, holds four sections and nothing else. A sketch, values abridged
+(the tremolo's controls, a gate table, a constant):
+
+```json
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "controls": [
+    { "name": "rateHz", "kind": "travel", "global": "TREMOLO_RATE_RANGE", "doc": "…", "travel": { "min": 0.1, "max": 20, "unit": "Hz", "default": 5 } },
+    { "name": "depth", "kind": "travel", "doc": "…", "travel": { "min": 0, "max": 1, "unit": "", "default": 0.5 } },
+    { "name": "mode", "kind": "choice", "doc": "…", "ids": ["tremolo", "pan"], "labels": ["Tremolo", "Pan"] },
+    { "name": "thresholdDb", "kind": "travel", "table": "GATE_LIMITS", "travel": { "min": -80, "max": 0, "unit": "dB" } }
+  ],
+  "tables": { "GATE_LIMITS": { "doc": "…" } },
+  "aggregates": { "TREMOLO_TRAVELS": { "doc": "…", "fields": ["rateHz", "depth"] } },
+  "constants": { "CHORUS_BASE_MS": { "kind": "scalar", "doc": "…", "unit": "ms", "value": 10 } }
+}
+```
+
+- `controls`, in order: a `travel` (one travel) or a `choice` (ordered `ids`, an optional `default` and `labels`).
+  Its item name is `<KERNEL>_<NAME>_RANGE` for a travel and `<KERNEL>_<NAME>S` for a choice (`depth` in
+  tremolo.json is `TREMOLO_DEPTH_RANGE`, `mode` is `TREMOLO_MODES`); `global` names it when it is anything else.
+  A control with a `table` is one field of that table.
+- `tables`: a travels table whose fields are the controls that name it, in control order (`GATE_LIMITS`).
+- `aggregates`: a travels table whose fields are references to controls declared once above, listed by name.
+- `constants`: scalars, lists and sheets, as items.
+
+`omx-contract validate` refuses any other key, a constant that is a travel or a set, and a kernel file written
+as a flat item map (the 1.x shape). `rates.json` and `primitives.json` stay item maps.
+
 ## The CLI
 
 ```
@@ -46,9 +78,9 @@ share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all
 
 ## Consuming it
 
-Pin one version (`omx-contract 1.3.0` in `.github/pins.txt`) and build against its renders, committing
+Pin one version (`omx-contract 2.0.0` in `.github/pins.txt`) and build against its renders, committing
 none: the installed `omx-contract-devel` / `libomx-contract-dev` at exactly that version
-(`pkg-config --exact-version=1.3.0 omx-contract`), else the release's npm tarball, unpacked, and
+(`pkg-config --exact-version=2.0.0 omx-contract`), else the release's npm tarball, unpacked, and
 `omx-contract render --target c --out build/omx-contract/include`. Include
 `<omxcontract/omx_contract_limits.h>`. A plugin's parameter header is rendered by omx-plugins from its
 declaration, by reference to the kernel travels here (since 1.1.0).

package/bin/omx-contract.mjs

@@ -15,7 +15,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadData, packageVersion, resolveData } from '../lib/data.mjs';
+import { KERNEL_SECTIONS, isKernelFile, kernelDocOf, loadData, packageVersion, resolveData } from '../lib/data.mjs';
 import { formatDoc } from '../lib/fmt.mjs';
 import { classify, refusal } from '../lib/semver.mjs';
 import { validateData } from '../lib/validate.mjs';
@@ -122,12 +122,23 @@ function cmdRender(argv) {
   return 0;
 }
 
-/** The data of a git tag, as `{ rel: text }`. */
+/**
+ * The data of a git tag, as `{ rel: text }`. A tag released before 2.0.0 wrote its kernel files as flat item maps;
+ * each is restated in the kernel-file shape (kernelDocOf, the inverse of the expansion the loader reads), so the
+ * comparison is between the items the two releases declare.
+ */
 function dataAtTag(tag) {
   const git = (...a) => execFileSync('git', ['-C', ROOT, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
   try { git('rev-parse', '--verify', `${tag}^{commit}`); } catch { throw new Usage(`no tag ${tag} in ${ROOT}`); }
   const texts = {};
-  for (const rel of git('ls-tree', '-r', '--name-only', tag, '--', 'data').split('\n').filter((p) => p.endsWith('.json'))) texts[rel] = git('show', `${tag}:${rel}`);
+  for (const rel of git('ls-tree', '-r', '--name-only', tag, '--', 'data').split('\n').filter((p) => p.endsWith('.json'))) {
+    const text = git('show', `${tag}:${rel}`);
+    let doc;
+    try { doc = JSON.parse(text); } catch { texts[rel] = text; continue; }
+    if (!isKernelFile(rel) || KERNEL_SECTIONS.some((k) => k in doc)) { texts[rel] = text; continue; }
+    const { $schema, ...items } = doc;
+    texts[rel] = JSON.stringify({ $schema, ...kernelDocOf(rel, Object.entries(items)) });
+  }
   return texts;
 }
 

package/data/kernels/balance.json

@@ -1,19 +1,23 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "PAN_RANGE": {
-    "kind": "travels",
-    "doc": "The PAN travel — −1 (hard left) … 0 (center) … +1 (hard right). A property of the pan law itself, not of any desk, so it is declared once. Continuous: a pan position has no quantum, and panGains clamps to these bounds.",
-    "travel": {
-      "min": -1,
-      "max": 1,
-      "step": 0,
-      "unit": ""
-    },
-    "c": {
-      "alias": {
-        "fact": "pan",
-        "field": "pan"
+  "controls": [
+    {
+      "name": "pan",
+      "kind": "travel",
+      "global": "PAN_RANGE",
+      "doc": "The PAN travel — −1 (hard left) … 0 (center) … +1 (hard right). A property of the pan law itself, not of any desk, so it is declared once. Continuous: a pan position has no quantum, and panGains clamps to these bounds.",
+      "travel": {
+        "min": -1,
+        "max": 1,
+        "step": 0,
+        "unit": ""
+      },
+      "c": {
+        "alias": {
+          "fact": "pan",
+          "field": "pan"
+        }
       }
     }
-  }
+  ]
 }

package/data/kernels/band_dyn.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "controls": [
+    {
+      "name": "mode",
+      "kind": "choice",
+      "doc": "The side of the threshold the band acts on. Above acts when the band is loud, taming a resonance that only rings when pushed; below acts when it is quiet, lifting a band that drops out. The order is the integer the kernel reads: above is 0, below is 1.",
+      "ids": [
+        "above",
+        "below"
+      ],
+      "default": "above"
+    },
+    {
+      "name": "threshold",
+      "kind": "travel",
+      "doc": "Where the band starts to act, in dB of the band's own level and not the strip's. It is the same fact the de-esser's threshold is, so it carries the same travel.",
+      "travel": {
+        "min": {
+          "ref": "DEESS_THRESHOLD_RANGE.min"
+        },
+        "max": {
+          "ref": "DEESS_THRESHOLD_RANGE.max"
+        },
+        "step": {
+          "ref": "DEESS_THRESHOLD_RANGE.step"
+        },
+        "unit": "dB",
+        "default": {
+          "ref": "DEESS_THRESHOLD_RANGE.default"
+        },
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "ratio",
+      "kind": "travel",
+      "doc": "How hard the band is held once it is past its threshold. 2:1 rather than the de-esser's 4:1, because a dynamic band is corrective, not a limiter for a sibilant.",
+      "travel": {
+        "min": {
+          "ref": "DEESS_RATIO_RANGE.min"
+        },
+        "max": {
+          "ref": "DEESS_RATIO_RANGE.max"
+        },
+        "step": {
+          "ref": "DEESS_RATIO_RANGE.step"
+        },
+        "unit": "",
+        "default": 2,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "range",
+      "kind": "travel",
+      "doc": "The most the band may add to its static gain, signed: below zero the deepest cut, above zero the largest boost. The ceiling of +12 keeps static plus dynamic inside the EQ's own travel. Zero makes the band inert without switching it off.",
+      "travel": {
+        "min": {
+          "ref": "DEESS_RANGE_RANGE.min"
+        },
+        "max": 12,
+        "step": {
+          "ref": "DEESS_RANGE_RANGE.step"
+        },
+        "unit": "dB",
+        "default": -6,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "attack",
+      "kind": "travel",
+      "doc": "The detector's attack, in ms. The travel stops at the oversampling floor, below which the band would need the compressor's delayed control path.",
+      "travel": {
+        "min": {
+          "ref": "DETECTOR_OVERSAMPLE_AUTO_MS"
+        },
+        "max": {
+          "ref": "COMP_LIMITS.attackMs.max"
+        },
+        "step": {
+          "ref": "DEESS_ATTACK_RANGE.step"
+        },
+        "unit": "ms",
+        "default": 5,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "release",
+      "kind": "travel",
+      "doc": "The detector's release, in ms. 100 ms is long enough not to modulate a 40 Hz band inside four cycles.",
+      "travel": {
+        "min": {
+          "ref": "DEESS_RELEASE_RANGE.min"
+        },
+        "max": {
+          "ref": "COMP_LIMITS.releaseMs.max"
+        },
+        "step": {
+          "ref": "DEESS_RELEASE_RANGE.step"
+        },
+        "unit": "ms",
+        "default": 100,
+        "defaultFrom": "desk"
+      }
+    }
+  ],
+  "constants": {
+    "BAND_DYN_KNEE_DB": {
+      "kind": "scalar",
+      "doc": "The soft knee of the band's gain computer, in dB. One knee for the one band-dynamics word, shared by every stage that runs it, the de-esser included: a second spelling of 6 would be a second place where the reduction starts.",
+      "unit": "dB",
+      "value": 6
+    },
+    "BAND_DYN_MAX_BANDS": {
+      "kind": "scalar",
+      "doc": "How many dynamic bands a channel may hold. A dynamic band is an operator band, so the capacity is the operator's reserve, read and not typed again.",
+      "unit": "",
+      "value": {
+        "ref": "OPERATOR_EQ_BANDS_RESERVE"
+      }
+    },
+    "DETECTOR_OVERSAMPLE_AUTO_MS": {
+      "kind": "scalar",
+      "doc": "The shortest attack, in ms, at which the compressor's detector does not alias. Below it the compressor engages its 4x control path, which adds 72 samples of latency; a zero-latency band has no such path, so its attack travel stops at this floor.",
+      "unit": "ms",
+      "value": 0.5
+    }
+  }
+}

package/data/kernels/chorus.json

@@ -1,85 +1,94 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "CHORUS_SPREAD_RANGE": {
-    "kind": "travels",
-    "doc": "The chorus's right-leg phase offset, in TURNS of its one oscillator (§2, §3a; the native-FX catalogue's M32 Dimension row). The right leg's voice k reads the LFO at k/N + spread: 0 is both legs one phase (the stage without the field, bit for bit), 0.25 quadrature, 0.5 the Dimension's opposed sweep. A fraction of a cycle carries no engineering symbol, so the unit is ''.",
-    "travel": {
-      "min": 0,
-      "max": 0.5,
-      "step": 0.01,
-      "unit": "",
-      "default": 0,
-      "defaultFrom": "desk"
+  "controls": [
+    {
+      "name": "spread",
+      "kind": "travel",
+      "doc": "The chorus's right-leg phase offset, in TURNS of its one oscillator (§2, §3a; the native-FX catalogue's M32 Dimension row). The right leg's voice k reads the LFO at k/N + spread: 0 is both legs one phase (the stage without the field, bit for bit), 0.25 quadrature, 0.5 the Dimension's opposed sweep. A fraction of a cycle carries no engineering symbol, so the unit is ''.",
+      "travel": {
+        "min": 0,
+        "max": 0.5,
+        "step": 0.01,
+        "unit": "",
+        "default": 0,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "rate",
+      "kind": "travel",
+      "doc": "The chorus sweep's speed (§3a). Above ~3 Hz it stops being a chorus and becomes a vibrato.",
+      "travel": {
+        "min": 0.05,
+        "max": 8,
+        "step": 0.01,
+        "unit": "Hz",
+        "default": 0.6,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "depth",
+      "kind": "travel",
+      "doc": "The chorus's peak-to-peak excursion above its declared 10 ms base (§3a).",
+      "travel": {
+        "min": 0,
+        "max": 12,
+        "step": 0.1,
+        "unit": "ms",
+        "default": 4,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "voices",
+      "kind": "travel",
+      "doc": "The chorus's tap count — one oscillator read at k/N (§3a).",
+      "travel": {
+        "min": 1,
+        "max": 4,
+        "step": 1,
+        "unit": "",
+        "default": 3,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "mix",
+      "kind": "travel",
+      "doc": "The chorus's wet/dry, as an instance of DRIVE_MIX_RANGE — the same percent travel, its own come-up value: 35 %, a colour under the dry on a strip (§3a). The REVERB_LOWCUT_RANGE-over- REVERB_CUT_RANGE shape: one travel, one declared default per field that reads it.",
+      "travel": {
+        "min": 0,
+        "max": 100,
+        "step": 0.1,
+        "unit": "%",
+        "default": 35,
+        "defaultFrom": "desk"
+      }
     }
-  },
-  "CHORUS_RATE_RANGE": {
-    "kind": "travels",
-    "doc": "The chorus sweep's speed (§3a). Above ~3 Hz it stops being a chorus and becomes a vibrato.",
-    "travel": {
-      "min": 0.05,
-      "max": 8,
-      "step": 0.01,
-      "unit": "Hz",
-      "default": 0.6,
-      "defaultFrom": "desk"
-    }
-  },
-  "CHORUS_DEPTH_RANGE": {
-    "kind": "travels",
-    "doc": "The chorus's peak-to-peak excursion above its declared 10 ms base (§3a).",
-    "travel": {
-      "min": 0,
-      "max": 12,
-      "step": 0.1,
+  ],
+  "constants": {
+    "CHORUS_BASE_MS": {
+      "kind": "scalar",
+      "doc": "The chorus's base delay, ms: the voices swing around it by up to the depth.",
       "unit": "ms",
-      "default": 4,
-      "defaultFrom": "desk"
-    }
-  },
-  "CHORUS_VOICES_RANGE": {
-    "kind": "travels",
-    "doc": "The chorus's tap count — one oscillator read at k/N (§3a).",
-    "travel": {
-      "min": 1,
-      "max": 4,
-      "step": 1,
-      "unit": "",
-      "default": 3,
-      "defaultFrom": "desk"
-    }
-  },
-  "CHORUS_MIX_RANGE": {
-    "kind": "travels",
-    "doc": "The chorus's wet/dry, as an instance of DRIVE_MIX_RANGE — the same percent travel, its own come-up value: 35 %, a colour under the dry on a strip (§3a). The REVERB_LOWCUT_RANGE-over- REVERB_CUT_RANGE shape: one travel, one declared default per field that reads it.",
-    "travel": {
-      "min": 0,
-      "max": 100,
-      "step": 0.1,
-      "unit": "%",
-      "default": 35,
-      "defaultFrom": "desk"
-    }
-  },
-  "CHORUS_BASE_MS": {
-    "kind": "scalar",
-    "doc": "The chorus's base delay, ms: the voices swing around it by up to the depth.",
-    "unit": "ms",
-    "value": 10
-  },
-  "CHORUS_MAX_MS": {
-    "kind": "scalar",
-    "doc": "The longest delay a chorus voice reaches, rounded up to whole ms: the base delay plus the depth maximum. The delay line is sized from it.",
-    "unit": "ms",
-    "value": {
-      "derive": "ceilSum",
-      "of": [
-        {
-          "ref": "CHORUS_BASE_MS"
-        },
-        {
-          "ref": "CHORUS_DEPTH_RANGE.max"
-        }
-      ]
+      "value": 10
+    },
+    "CHORUS_MAX_MS": {
+      "kind": "scalar",
+      "doc": "The longest delay a chorus voice reaches, rounded up to whole ms: the base delay plus the depth maximum. The delay line is sized from it.",
+      "unit": "ms",
+      "value": {
+        "derive": "ceilSum",
+        "of": [
+          {
+            "ref": "CHORUS_BASE_MS"
+          },
+          {
+            "ref": "CHORUS_DEPTH_RANGE.max"
+          }
+        ]
+      }
     }
   }
 }

package/data/kernels/comp.json

@@ -1,58 +1,89 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "COMP_LIMITS": {
-    "kind": "travels",
-    "doc": "The legal range of each compressor field (engineering units). The widget clamps drags to these, `normalizeComp` enforces them, the row's codec refuses by them and the travel sheet publishes them. `default`/`defaultFrom` are the come-up values `defaultCompState` seeds a fresh strip with, read BACK from here rather than restated there.",
-    "fields": {
-      "thresholdDb": {
+  "controls": [
+    {
+      "name": "thresholdDb",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": -60,
         "max": 0,
         "step": 1,
         "unit": "dB",
         "default": -18,
         "defaultFrom": "desk"
-      },
-      "ratio": {
+      }
+    },
+    {
+      "name": "ratio",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 1,
         "max": 20,
         "step": 0.5,
         "unit": "",
         "default": 4,
         "defaultFrom": "desk"
-      },
-      "kneeDb": {
+      }
+    },
+    {
+      "name": "kneeDb",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 0,
         "max": 24,
         "step": 0.5,
         "unit": "dB",
         "default": 6,
         "defaultFrom": "desk"
-      },
-      "attackMs": {
+      }
+    },
+    {
+      "name": "attackMs",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 0.1,
         "max": 100,
         "step": 1,
         "unit": "ms",
         "default": 5,
         "defaultFrom": "desk"
-      },
-      "releaseMs": {
+      }
+    },
+    {
+      "name": "releaseMs",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 5,
         "max": 3000,
         "step": 10,
         "unit": "ms",
         "default": 200,
         "defaultFrom": "desk"
-      },
-      "makeupDb": {
+      }
+    },
+    {
+      "name": "makeupDb",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 0,
         "max": 24,
         "step": 0.5,
         "unit": "dB",
         "default": 0,
         "defaultFrom": "desk"
-      },
-      "mixPct": {
+      }
+    },
+    {
+      "name": "mixPct",
+      "kind": "travel",
+      "table": "COMP_LIMITS",
+      "travel": {
         "min": 0,
         "max": 100,
         "step": 5,
@@ -61,19 +92,26 @@
         "defaultFrom": "desk"
       }
     }
+  ],
+  "tables": {
+    "COMP_LIMITS": {
+      "doc": "The legal range of each compressor field (engineering units). The widget clamps drags to these, `normalizeComp` enforces them, the row's codec refuses by them and the travel sheet publishes them. `default`/`defaultFrom` are the come-up values `defaultCompState` seeds a fresh strip with, read BACK from here rather than restated there."
+    }
   },
-  "PROGRAM_RELEASE": {
-    "kind": "sheet",
-    "doc": "The program-dependent release's model constants — the LA-2A's opto cell as DATA (`docs/design/specs/2026-09-26-compressor-models.md` §3b). `chargeMs`/`dischargeMs` are the word's memory constants, shared by every profile; each profile's `fastMs`, `slowMinMs`, `slowMaxMs` and `share` fit the unit's published two-stage recovery. Not operator controls: generated into `omx_contract_limits.h` as `OMX_PROGRAM_RELEASE_*`, which libomxdsp's `omx_env_program_release` reads.",
-    "value": {
-      "chargeMs": 1000,
-      "dischargeMs": 5000,
-      "profiles": {
-        "opto": {
-          "fastMs": 70,
-          "slowMinMs": 110,
-          "slowMaxMs": 1100,
-          "share": 0.5
+  "constants": {
+    "PROGRAM_RELEASE": {
+      "kind": "sheet",
+      "doc": "The program-dependent release's model constants — the LA-2A's opto cell as DATA (`docs/design/specs/2026-09-26-compressor-models.md` §3b). `chargeMs`/`dischargeMs` are the word's memory constants, shared by every profile; each profile's `fastMs`, `slowMinMs`, `slowMaxMs` and `share` fit the unit's published two-stage recovery. Not operator controls: generated into `omx_contract_limits.h` as `OMX_PROGRAM_RELEASE_*`, which libomxdsp's `omx_env_program_release` reads.",
+      "value": {
+        "chargeMs": 1000,
+        "dischargeMs": 5000,
+        "profiles": {
+          "opto": {
+            "fastMs": 70,
+            "slowMinMs": 110,
+            "slowMaxMs": 1100,
+            "share": 0.5
+          }
         }
       }
     }