@openmixer/omx-contract 1.3.0 → 2.0.0

package/lib/validate.mjs

@@ -8,13 +8,47 @@
 import { readFileSync } from 'node:fs';
 import { posix } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
-import { resolveData } from './data.mjs';
+import { KERNEL_SECTIONS, entriesOf, isKernelFile, resolveData } from './data.mjs';
 import { eqDefaultBands, eqDefaultParams } from './eq-defaults.mjs';
 import { renderC } from '../render/c.mjs';
 import { renderTs } from '../render/ts.mjs';
 
 const SCHEMA = JSON.parse(readFileSync(new URL('../schema/omx-contract.schema.json', import.meta.url), 'utf8'));
 let compiled;
+/**
+ * The kernel-file shape (2.0.0), which the item schema cannot see: only the four sections at the top; every control
+ * named, of kind travel or choice, unique by name, a travel carrying a `travel` and a choice its `ids`; a control's
+ * `table` declared under `tables`; an aggregate's fields naming controls; a constant a scalar, a list or a sheet.
+ * A kernel file written as a flat item map (the 1.x shape) is refused as a whole. Any other data file returns [].
+ */
+export function shapeProblems(rel, doc) {
+  if (!isKernelFile(rel)) return [];
+  const sections = KERNEL_SECTIONS;
+  const keys = Object.keys(doc).filter((k) => k !== '$schema');
+  if (keys.length && !keys.some((k) => sections.includes(k))) {
+    return [`${rel} is a flat item map (the 1.x shape): a kernel file declares its items under ${sections.join(', ')}`];
+  }
+  const out = [];
+  for (const k of keys) if (!sections.includes(k)) out.push(`unknown top-level key ${k}: a kernel file holds ${sections.join(', ')}`);
+  const controls = doc.controls ?? [];
+  if (!Array.isArray(controls)) return [...out, 'controls must be a list'];
+  const seen = new Set();
+  for (const [i, c] of controls.entries()) {
+    if (typeof c.name !== 'string' || !/^[a-z][A-Za-z0-9]*$/.test(c.name)) out.push(`controls[${i}]: name ${JSON.stringify(c.name)} is not a lowerCamel identifier`);
+    if (seen.has(c.name)) out.push(`controls[${i}]: name ${c.name} declared twice`);
+    seen.add(c.name);
+    if (c.kind === 'travel' && !c.travel) out.push(`controls[${i}] ${c.name}: a travel without "travel"`);
+    else if (c.kind === 'choice' && !Array.isArray(c.ids)) out.push(`controls[${i}] ${c.name}: a choice without "ids"`);
+    else if (c.kind !== 'travel' && c.kind !== 'choice') out.push(`controls[${i}] ${c.name}: kind ${JSON.stringify(c.kind)} is neither travel nor choice`);
+    if (c.table && !(doc.tables && c.table in doc.tables)) out.push(`controls[${i}] ${c.name}: table ${c.table} is not declared`);
+  }
+  for (const [n, a] of Object.entries(doc.aggregates ?? {})) for (const f of a.fields ?? []) if (!seen.has(f)) out.push(`aggregate ${n}: field ${f} names no control`);
+  for (const [n, it] of Object.entries(doc.constants ?? {})) {
+    if (!['scalar', 'list', 'sheet'].includes(it?.kind)) out.push(`constant ${n}: kind ${JSON.stringify(it?.kind)} is not scalar, list or sheet (a travel or a set is a control)`);
+  }
+  return out;
+}
+
 /** The compiled schema validator. */
 export function schemaValidator() {
   if (!compiled) compiled = new Ajv2020({ allErrors: true, strict: true, strictRequired: false, allowUnionTypes: true }).compile(SCHEMA);
@@ -88,7 +122,10 @@ export function validateData(data) {
     const depth = f.rel.split('/').length - 1;
     const want = posix.join(...Array(depth).fill('..'), 'schema/omx-contract.schema.json');
     if (f.doc.$schema !== want) say(f.rel, '-', 'schema-path', `"$schema" must be "${want}"`);
-    if (!validate(f.doc)) {
+    for (const m of shapeProblems(f.rel, f.doc)) say(f.rel, '-', 'shape', m);
+    // The schema reads items: a kernel file is checked as the items it expands to, so no rule is lost.
+    const items = { $schema: f.doc.$schema, ...Object.fromEntries(entriesOf(f.rel, f.doc)) };
+    if (!validate(items)) {
       for (const e of validate.errors) {
         const item = e.instancePath.split('/')[1] || '-';
         say(f.rel, item, 'schema', `${e.instancePath || '/'} ${e.message}${e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : ''}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "The FreeMixer declarations as data: a JSON Schema, the data, and one CLI that renders them into C, TypeScript and JSON",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/share/omx-contract/omx-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "items": {
     "PAN_RANGE": {
       "rel": "data/kernels/balance.json",
@@ -20,6 +20,107 @@
         "unit": ""
       }
     },
+    "BAND_DYN_MODES": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "set",
+      "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.",
+      "default": "above",
+      "value": [
+        "above",
+        "below"
+      ]
+    },
+    "BAND_DYN_THRESHOLD_RANGE": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "travels",
+      "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.",
+      "shape": "travel",
+      "value": {
+        "min": -60,
+        "max": 0,
+        "step": 0.5,
+        "unit": "dB",
+        "default": -30,
+        "defaultFrom": "desk"
+      }
+    },
+    "BAND_DYN_RATIO_RANGE": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "travels",
+      "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.",
+      "shape": "travel",
+      "value": {
+        "min": 1,
+        "max": 20,
+        "step": 0.1,
+        "unit": "",
+        "default": 2,
+        "defaultFrom": "desk"
+      }
+    },
+    "BAND_DYN_RANGE_RANGE": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "travels",
+      "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.",
+      "shape": "travel",
+      "value": {
+        "min": -24,
+        "max": 12,
+        "step": 0.5,
+        "unit": "dB",
+        "default": -6,
+        "defaultFrom": "desk"
+      }
+    },
+    "BAND_DYN_ATTACK_RANGE": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "travels",
+      "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.",
+      "shape": "travel",
+      "value": {
+        "min": 0.5,
+        "max": 100,
+        "step": 0.1,
+        "unit": "ms",
+        "default": 5,
+        "defaultFrom": "desk"
+      }
+    },
+    "BAND_DYN_RELEASE_RANGE": {
+      "rel": "data/kernels/band_dyn.json",
+      "kind": "travels",
+      "doc": "The detector's release, in ms. 100 ms is long enough not to modulate a 40 Hz band inside four cycles.",
+      "shape": "travel",
+      "value": {
+        "min": 5,
+        "max": 3000,
+        "step": 1,
+        "unit": "ms",
+        "default": 100,
+        "defaultFrom": "desk"
+      }
+    },
+    "BAND_DYN_KNEE_DB": {
+      "rel": "data/kernels/band_dyn.json",
+      "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": {
+      "rel": "data/kernels/band_dyn.json",
+      "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": 9
+    },
+    "DETECTOR_OVERSAMPLE_AUTO_MS": {
+      "rel": "data/kernels/band_dyn.json",
+      "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
+    },
     "CHORUS_SPREAD_RANGE": {
       "rel": "data/kernels/chorus.json",
       "kind": "travels",
@@ -283,13 +384,6 @@
         "defaultFrom": "desk"
       }
     },
-    "DEESS_KNEE_DB": {
-      "rel": "data/kernels/deesser.json",
-      "kind": "scalar",
-      "doc": "The knee, in dB — a CONSTANT of the stage and not a row field (`2026-09-22-native-deesser-stage.md` §4b): a de-esser without a soft knee latches audibly on the first sibilant of a phrase, and no other value of this number is a de-esser anyone would dial. The controller pushes it to the node and this is the same number; a second spelling would be a picture that disagrees with the audio about where the reduction starts.",
-      "unit": "dB",
-      "value": 6
-    },
     "DEESS_MODES": {
       "rel": "data/kernels/deesser.json",
       "kind": "set",
@@ -299,6 +393,13 @@
         "wideband"
       ]
     },
+    "DEESS_KNEE_DB": {
+      "rel": "data/kernels/deesser.json",
+      "kind": "scalar",
+      "doc": "The knee, in dB — a CONSTANT of the stage and not a row field (`2026-09-22-native-deesser-stage.md` §4b): a de-esser without a soft knee latches audibly on the first sibilant of a phrase, and no other value of this number is a de-esser anyone would dial. The controller pushes it to the node and this is the same number; a second spelling would be a picture that disagrees with the audio about where the reduction starts.",
+      "unit": "dB",
+      "value": 6
+    },
     "FX_DELAY_TIME_RANGE": {
       "rel": "data/kernels/delay.json",
       "kind": "travels",
@@ -371,13 +472,6 @@
       "unit": "",
       "value": false
     },
-    "DRIVE_BIAS_MAX": {
-      "rel": "data/kernels/drive.json",
-      "kind": "scalar",
-      "doc": "The bias at `character = +1`, in the SHAPER's own input units — `OMX_DRIVE_BIAS_MAX`. DERIVED, not chosen (§4b). In the saturating limit every knee tends to `sgn`, the output is a rectangular wave of duty `d = ½ + asin(b)/π`, and its `n`th harmonic goes as `sin(nπd)/n` — so `|H2|` is maximal at `d = ¾`, which is `b = sin(π/4) = 1/√2` exactly. Measured too: the H2-maximising bias for a full-scale sine at unity drive is 0.712 (soft), 0.658 (tape), 0.645 (tube), and this one value costs 0.000 / 0.035 / 0.088 dB of H2 against each curve's own optimum. ONE normalised bias for all three knees, not three.",
-      "unit": "",
-      "value": 0.7071067811865476
-    },
     "DRIVE_AMOUNT_RANGE": {
       "rel": "data/kernels/drive.json",
       "kind": "travels",
@@ -500,58 +594,12 @@
         "tilt"
       ]
     },
-    "EQ_MAX_BANDS": {
-      "rel": "data/kernels/eq.json",
-      "kind": "scalar",
-      "doc": "The maximum number of parametric bands a channel EQ may hold — the operator can add up to this many. Generated into `omx_contract_limits.h` as `OMX_EQ_MAX_BANDS`, which `omx_biquad.h` reads (`output-delay-ceiling.test.ts` reads the header): the native lane allocates exactly this many biquad slots per channel and silently clamps above it, so the model, the wire, and the DSP agree by test, not by memory.",
-      "unit": "",
-      "value": 24
-    },
-    "ISO_THIRD_OCTAVE_CENTRES_HZ": {
-      "rel": "data/kernels/eq.json",
-      "kind": "list",
-      "doc": "The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.",
-      "unit": "Hz",
-      "value": [
-        20,
-        25,
-        31.5,
-        40,
-        50,
-        63,
-        80,
-        100,
-        125,
-        160,
-        200,
-        250,
-        315,
-        400,
-        500,
-        630,
-        800,
-        1000,
-        1250,
-        1600,
-        2000,
-        2500,
-        3150,
-        4000,
-        5000,
-        6300,
-        8000,
-        10000,
-        12500,
-        16000,
-        20000
-      ]
-    },
-    "GEQ_BANDS": {
-      "rel": "data/kernels/eq.json",
+    "DRIVE_BIAS_MAX": {
+      "rel": "data/kernels/drive.json",
       "kind": "scalar",
-      "doc": "The graphic EQ's section count: DERIVED from ISO_THIRD_OCTAVE_CENTRES_HZ, never a second literal. Generated into `omx_contract_limits.h` as `OMX_GEQ_BANDS`, which sizes `mix_geq.h`'s section array — its OWN budget, never a claimant on EQ_MAX_BANDS (graphic-eq-31 spec §3, roster ruling 3).",
+      "doc": "The bias at `character = +1`, in the SHAPER's own input units — `OMX_DRIVE_BIAS_MAX`. DERIVED, not chosen (§4b). In the saturating limit every knee tends to `sgn`, the output is a rectangular wave of duty `d = ½ + asin(b)/π`, and its `n`th harmonic goes as `sin(nπd)/n` — so `|H2|` is maximal at `d = ¾`, which is `b = sin(π/4) = 1/√2` exactly. Measured too: the H2-maximising bias for a full-scale sine at unity drive is 0.712 (soft), 0.658 (tape), 0.645 (tube), and this one value costs 0.000 / 0.035 / 0.088 dB of H2 against each curve's own optimum. ONE normalised bias for all three knees, not three.",
       "unit": "",
-      "value": 31
+      "value": 0.7071067811865476
     },
     "EQ_FREQ_RANGE": {
       "rel": "data/kernels/eq.json",
@@ -625,13 +673,6 @@
         "unit": "Hz"
       }
     },
-    "OPERATOR_EQ_BANDS_RESERVE": {
-      "rel": "data/kernels/eq.json",
-      "kind": "scalar",
-      "doc": "The band slots kept for the operator's own hand: the reserve the feedback suppressor and the ring correction may never eat into. Nine is the working set a live EQ actually holds. The budget OPERATOR_EQ_BANDS_RESERVE + FBS_DEFAULT_MAX_AUTO_BANDS + HRP_DEFAULT_MAX_AUTO_BANDS (9 + 6 + 8 = 23) must fit EQ_MAX_BANDS, and `omx-contract validate` refuses data where it does not.",
-      "unit": "",
-      "value": 9
-    },
     "EQ_BAND_TYPES": {
       "rel": "data/kernels/eq.json",
       "kind": "set",
@@ -664,6 +705,66 @@
         24
       ]
     },
+    "EQ_MAX_BANDS": {
+      "rel": "data/kernels/eq.json",
+      "kind": "scalar",
+      "doc": "The maximum number of parametric bands a channel EQ may hold — the operator can add up to this many. Generated into `omx_contract_limits.h` as `OMX_EQ_MAX_BANDS`, which `omx_biquad.h` reads (`output-delay-ceiling.test.ts` reads the header): the native lane allocates exactly this many biquad slots per channel and silently clamps above it, so the model, the wire, and the DSP agree by test, not by memory.",
+      "unit": "",
+      "value": 24
+    },
+    "ISO_THIRD_OCTAVE_CENTRES_HZ": {
+      "rel": "data/kernels/eq.json",
+      "kind": "list",
+      "doc": "The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.",
+      "unit": "Hz",
+      "value": [
+        20,
+        25,
+        31.5,
+        40,
+        50,
+        63,
+        80,
+        100,
+        125,
+        160,
+        200,
+        250,
+        315,
+        400,
+        500,
+        630,
+        800,
+        1000,
+        1250,
+        1600,
+        2000,
+        2500,
+        3150,
+        4000,
+        5000,
+        6300,
+        8000,
+        10000,
+        12500,
+        16000,
+        20000
+      ]
+    },
+    "GEQ_BANDS": {
+      "rel": "data/kernels/eq.json",
+      "kind": "scalar",
+      "doc": "The graphic EQ's section count: DERIVED from ISO_THIRD_OCTAVE_CENTRES_HZ, never a second literal. Generated into `omx_contract_limits.h` as `OMX_GEQ_BANDS`, which sizes `mix_geq.h`'s section array — its OWN budget, never a claimant on EQ_MAX_BANDS (graphic-eq-31 spec §3, roster ruling 3).",
+      "unit": "",
+      "value": 31
+    },
+    "OPERATOR_EQ_BANDS_RESERVE": {
+      "rel": "data/kernels/eq.json",
+      "kind": "scalar",
+      "doc": "The band slots kept for the operator's own hand: the reserve the feedback suppressor and the ring correction may never eat into. Nine is the working set a live EQ actually holds. The budget OPERATOR_EQ_BANDS_RESERVE + FBS_DEFAULT_MAX_AUTO_BANDS + HRP_DEFAULT_MAX_AUTO_BANDS (9 + 6 + 8 = 23) must fit EQ_MAX_BANDS, and `omx-contract validate` refuses data where it does not.",
+      "unit": "",
+      "value": 9
+    },
     "EQ_BAND_COUNTS": {
       "rel": "data/kernels/eq.json",
       "kind": "sheet",
@@ -1011,6 +1112,15 @@
       "unit": "ms",
       "value": 6
     },
+    "GATE_KEY_SOURCES": {
+      "rel": "data/kernels/gate.json",
+      "kind": "set",
+      "doc": "Where the gate listens: its own input (self), or the key it is handed (sidechain), in the order of the integer the key port carries.",
+      "value": [
+        "self",
+        "sidechain"
+      ]
+    },
     "GATE_LIMITS": {
       "rel": "data/kernels/gate.json",
       "kind": "travels",
@@ -1091,15 +1201,6 @@
         }
       }
     },
-    "GATE_KEY_SOURCES": {
-      "rel": "data/kernels/gate.json",
-      "kind": "set",
-      "doc": "Where the gate listens: its own input (self), or the key it is handed (sidechain), in the order of the integer the key port carries.",
-      "value": [
-        "self",
-        "sidechain"
-      ]
-    },
     "GEQ_BAND_RANGE": {
       "rel": "data/kernels/geq.json",
       "kind": "travels",
@@ -1135,6 +1236,20 @@
       "unit": "dB",
       "value": 30
     },
+    "HRP_AMOUNT_RANGE": {
+      "rel": "data/kernels/hrp.json",
+      "kind": "travels",
+      "doc": "How much of the computed correction HRP applies: 0 = analyse only, 1 = the full cut. It comes up at 0.5, half the computed cut.",
+      "shape": "travel",
+      "value": {
+        "min": 0,
+        "max": 1,
+        "step": 0,
+        "unit": "",
+        "default": 0.5,
+        "defaultFrom": "desk"
+      }
+    },
     "HRP_MAX_CUT_DB": {
       "rel": "data/kernels/hrp.json",
       "kind": "scalar",
@@ -1191,19 +1306,6 @@
       "unit": "",
       "value": 8
     },
-    "HRP_AMOUNT_RANGE": {
-      "rel": "data/kernels/hrp.json",
-      "kind": "travels",
-      "doc": "How much of the computed correction HRP applies: 0 = analyse only, 1 = the full cut. It comes up at 0.5, half the computed cut.",
-      "shape": "travel",
-      "value": {
-        "min": 0,
-        "max": 1,
-        "step": 0,
-        "unit": "",
-        "default": 0.5
-      }
-    },
     "LIMITER_LIMITS": {
       "rel": "data/kernels/limiter.json",
       "kind": "travels",
@@ -1299,20 +1401,6 @@
         "defaultFrom": "desk"
       }
     },
-    "PHASER_STAGE_COUNTS": {
-      "rel": "data/kernels/phaser.json",
-      "kind": "list",
-      "doc": "The member set the `stages` field accepts: PHASER_STAGES_RANGE walked by its step.",
-      "unit": "",
-      "value": [
-        2,
-        4,
-        6,
-        8,
-        10,
-        12
-      ]
-    },
     "PHASER_FEEDBACK_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
@@ -1389,6 +1477,20 @@
         }
       }
     },
+    "PHASER_STAGE_COUNTS": {
+      "rel": "data/kernels/phaser.json",
+      "kind": "list",
+      "doc": "The member set the `stages` field accepts: PHASER_STAGES_RANGE walked by its step.",
+      "unit": "",
+      "value": [
+        2,
+        4,
+        6,
+        8,
+        10,
+        12
+      ]
+    },
     "PHASER_F_TOP_HZ": {
       "rel": "data/kernels/phaser.json",
       "kind": "scalar",
@@ -1717,6 +1819,16 @@
         "defaultFrom": "desk"
       }
     },
+    "ROTARY_SPEEDS": {
+      "rel": "data/kernels/rotary.json",
+      "kind": "set",
+      "doc": "The rotary speaker's speed settings, in the order of the integer the kernel reads: the rotors stopped, at their chorale (slow) rate, or at their tremolo (fast) rate.",
+      "value": [
+        "stop",
+        "slow",
+        "fast"
+      ]
+    },
     "ROTARY_TRAVELS": {
       "rel": "data/kernels/rotary.json",
       "kind": "travels",
@@ -1865,16 +1977,6 @@
       "unit": "",
       "value": 256
     },
-    "ROTARY_SPEEDS": {
-      "rel": "data/kernels/rotary.json",
-      "kind": "set",
-      "doc": "The rotary speaker's speed settings, in the order of the integer the kernel reads: the rotors stopped, at their chorale (slow) rate, or at their tremolo (fast) rate.",
-      "value": [
-        "stop",
-        "slow",
-        "fast"
-      ]
-    },
     "RTA_TARGET_BIN_HZ": {
       "rel": "data/kernels/rta.json",
       "kind": "scalar",
@@ -2007,6 +2109,16 @@
         "defaultFrom": "desk"
       }
     },
+    "TREMOLO_MODES": {
+      "rel": "data/kernels/tremolo.json",
+      "kind": "set",
+      "doc": "What the tremolo's one oscillator modulates, in the order of the integer the kernel reads: the level of both legs in phase (tremolo), or the balance law's position with the legs in opposition (pan).",
+      "default": "tremolo",
+      "value": [
+        "tremolo",
+        "pan"
+      ]
+    },
     "TREMOLO_TRAVELS": {
       "rel": "data/kernels/tremolo.json",
       "kind": "travels",
@@ -2039,16 +2151,6 @@
         }
       }
     },
-    "TREMOLO_MODES": {
-      "rel": "data/kernels/tremolo.json",
-      "kind": "set",
-      "doc": "What the tremolo's one oscillator modulates, in the order of the integer the kernel reads: the level of both legs in phase (tremolo), or the balance law's position with the legs in opposition (pan).",
-      "default": "tremolo",
-      "value": [
-        "tremolo",
-        "pan"
-      ]
-    },
     "BUTTERWORTH_Q": {
       "rel": "data/primitives.json",
       "kind": "scalar",