@openmixer/omx-contract 1.3.0 → 2.1.0

package/dist/ts/omx-contract.js

@@ -13,6 +13,98 @@ export const PAN_RANGE = {
   "unit": ""
 };
 
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_MODES = [
+  "above",
+  "below"
+];
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_THRESHOLD_RANGE = {
+  "min": -60,
+  "max": 0,
+  "step": 0.5,
+  "unit": "dB",
+  "default": -30,
+  "defaultFrom": "desk"
+};
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_RATIO_RANGE = {
+  "min": 1,
+  "max": 20,
+  "step": 0.1,
+  "unit": "",
+  "default": 2,
+  "defaultFrom": "desk"
+};
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_RANGE_RANGE = {
+  "min": -24,
+  "max": 12,
+  "step": 0.5,
+  "unit": "dB",
+  "default": -6,
+  "defaultFrom": "desk"
+};
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_ATTACK_RANGE = {
+  "min": 0.5,
+  "max": 100,
+  "step": 0.1,
+  "unit": "ms",
+  "default": 5,
+  "defaultFrom": "desk"
+};
+
+/**
+ * The detector's release, in ms. 100 ms is long enough not to modulate a 40 Hz band inside four cycles.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_RELEASE_RANGE = {
+  "min": 5,
+  "max": 3000,
+  "step": 1,
+  "unit": "ms",
+  "default": 100,
+  "defaultFrom": "desk"
+};
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_KNEE_DB = 6;
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const BAND_DYN_MAX_BANDS = 9;
+
+/**
+ * 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.
+ * @see data/kernels/band_dyn.json
+ */
+export const DETECTOR_OVERSAMPLE_AUTO_MS = 0.5;
+
 /**
  * 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 ''.
  * @see data/kernels/chorus.json
@@ -261,12 +353,6 @@ export const DEESS_RELEASE_RANGE = {
   "defaultFrom": "desk"
 };
 
-/**
- * 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.
- * @see data/kernels/deesser.json
- */
-export const DEESS_KNEE_DB = 6;
-
 /**
  * The de-esser's modes, in the order of the integer the kernel reads: split attenuates the detected band only, wideband the whole signal while the sibilance lasts.
  * @see data/kernels/deesser.json
@@ -276,6 +362,12 @@ export const DEESS_MODES = [
   "wideband"
 ];
 
+/**
+ * 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.
+ * @see data/kernels/deesser.json
+ */
+export const DEESS_KNEE_DB = 6;
+
 /**
  * The FX delay's time travel. `max` is the NATIVE ring's ceiling — the same number as `OMX_FXDELAY_MAX_MS` in `omx_delay.h`, pinned to it by `output-delay-ceiling.test.ts`. Distinct from the per-route ALIGNMENT delay (`OUTPUT_DELAY_RANGE`, 1 s, `OMX_DELAY_MAX_MS`): one is a musical echo with feedback and mix, the other is a pure latency. Two facts, two rings, two ceilings — sharing the word "delay" is why they keep being confused for each other.
  * @see data/kernels/delay.json
@@ -337,12 +429,6 @@ export const DELAY_MIX_RANGE = {
  */
 export const FX_DELAY_PINGPONG_DEFAULT = false;
 
-/**
- * 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.
- * @see data/kernels/drive.json
- */
-export const DRIVE_BIAS_MAX = 0.7071067811865476;
-
 /**
  * The PRE-CURVE gain, in dB. 0 dB is unity into the curve, so a stage switched on at its defaults changes almost nothing — which is what an `on` switch should mean. The ceiling is where every curve is saturating hard on any signal a console carries.
  * @see data/kernels/drive.json
@@ -431,54 +517,10 @@ export const DRIVE_BANDS = [
 ];
 
 /**
- * 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.
- * @see data/kernels/eq.json
- */
-export const EQ_MAX_BANDS = 24;
-
-/**
- * The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.
- * @see data/kernels/eq.json
- */
-export const ISO_THIRD_OCTAVE_CENTRES_HZ = [
-  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
-];
-
-/**
- * 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).
- * @see data/kernels/eq.json
+ * 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.
+ * @see data/kernels/drive.json
  */
-export const GEQ_BANDS = 31;
+export const DRIVE_BIAS_MAX = 0.7071067811865476;
 
 /**
  * The frequency band a parametric band can be dragged across.
@@ -546,12 +588,6 @@ export const LPF_FREQ_RANGE = {
   "unit": "Hz"
 };
 
-/**
- * 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.
- * @see data/kernels/eq.json
- */
-export const OPERATOR_EQ_BANDS_RESERVE = 9;
-
 /**
  * The generic EQ band shapes, in the order a picker offers them and in the order of the integer a plugin host sees on a band type port. The id is the name; the position is the value. A bell is the shape a band added by the operator starts as.
  * @see data/kernels/eq.json
@@ -574,6 +610,62 @@ export const FILTER_SLOPES = [
   24
 ];
 
+/**
+ * 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.
+ * @see data/kernels/eq.json
+ */
+export const EQ_MAX_BANDS = 24;
+
+/**
+ * The standard ISO 266 one-third-octave centre frequencies, 20 Hz–20 kHz (31 bands) — the classic 31-band graphic-EQ layout's centres.
+ * @see data/kernels/eq.json
+ */
+export const ISO_THIRD_OCTAVE_CENTRES_HZ = [
+  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
+];
+
+/**
+ * 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).
+ * @see data/kernels/eq.json
+ */
+export const GEQ_BANDS = 31;
+
+/**
+ * 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.
+ * @see data/kernels/eq.json
+ */
+export const OPERATOR_EQ_BANDS_RESERVE = 9;
+
 /**
  * How many bands each strip type's EQ starts with (`default`) and may hold (`max`). `channel` is the console's channel strip: it starts with four and the operator adds bands up to EQ_MAX_BANDS (a band added takes the frequency it is added at, so no default is declared for it). `strip` is the omx-strip plugin's EQ and `eq8`, `eq16` and `eq32` the omx-eq plugins, whose bands are fixed. A default may never exceed its maximum, and the default centres of any count come from the one default rule, whatever the strip.
  * @see data/kernels/eq.json
@@ -894,6 +986,15 @@ export const FLANGER_BASE_MS = 0.5;
  */
 export const FLANGER_MAX_MS = 6;
 
+/**
+ * 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.
+ * @see data/kernels/gate.json
+ */
+export const GATE_KEY_SOURCES = [
+  "self",
+  "sidechain"
+];
+
 /**
  * The legal range of each gate field (engineering units). The widget clamps drags to these, `normalizeGate` enforces them, the row's codec refuses by them and the travel sheet publishes them — one source of truth. `rangeDb` reaches GATE_RANGE_FLOOR_DB, shown as "−∞" in readouts (a gate fully closed is silence).
  * @see data/kernels/gate.json
@@ -973,15 +1074,6 @@ export const GATE_LIMITS = {
   }
 };
 
-/**
- * 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.
- * @see data/kernels/gate.json
- */
-export const GATE_KEY_SOURCES = [
-  "self",
-  "sidechain"
-];
-
 /**
  * One graphic-EQ fader's travel: EQ_GAIN_RANGE by reference (a graphic fader is an EQ gain), with the come-up value it needs as a row field — flat, 0 dB (graphic-eq-31 spec §3).
  * @see data/kernels/geq.json
@@ -1013,6 +1105,19 @@ export const GEQ_PROTO_DB = 12;
  */
 export const GEQ_DESIGN_GAIN_MAX_DB = 30;
 
+/**
+ * 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.
+ * @see data/kernels/hrp.json
+ */
+export const HRP_AMOUNT_RANGE = {
+  "min": 0,
+  "max": 1,
+  "step": 0,
+  "unit": "",
+  "default": 0.5,
+  "defaultFrom": "desk"
+};
+
 /**
  * The largest automatic cut HRP may place on one harmonic, as a POSITIVE dB magnitude. Well inside the ±15 dB an operator band may hold (core's `EQ_GAIN_LIMIT_DB`): an automatic correction the operator did not ask for gets far less authority than one they dialled themselves.
  * @see data/kernels/hrp.json
@@ -1061,18 +1166,6 @@ export const HRP_ATTRIBUTION_CENTS = 60;
  */
 export const HRP_DEFAULT_MAX_AUTO_BANDS = 8;
 
-/**
- * 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.
- * @see data/kernels/hrp.json
- */
-export const HRP_AMOUNT_RANGE = {
-  "min": 0,
-  "max": 1,
-  "step": 0,
-  "unit": "",
-  "default": 0.5
-};
-
 /**
  * The precision limiter's travels (`2026-09-27-precision-limiter.md` §2), rendered into `omx_contract_limits.h` as `OMX_LIMITER_*` by `harness/contract-limits-gen.mjs`, so `mix_limiter.h` reads them and never restates one (R-094). The ceiling is a TRUE peak in dBFS (the ×4 detector); the look-ahead sets the declared latency; the release is the envelope's time constant on the gain depth.
  * @see data/kernels/limiter.json
@@ -1162,19 +1255,6 @@ export const PHASER_STAGES_RANGE = {
   "defaultFrom": "desk"
 };
 
-/**
- * The member set the `stages` field accepts: PHASER_STAGES_RANGE walked by its step.
- * @see data/kernels/phaser.json
- */
-export const PHASER_STAGE_COUNTS = [
-  2,
-  4,
-  6,
-  8,
-  10,
-  12
-];
-
 /**
  * The phaser's SIGNED resonance (§3). ±0.9, tighter than the flanger's ±0.95: the loop runs through a time-varying chain. Declared here (the refusal half); the kernel's clamp is the enforcement half.
  * @see data/kernels/phaser.json
@@ -1248,6 +1328,19 @@ export const PHASER_TRAVELS = {
   }
 };
 
+/**
+ * The member set the `stages` field accepts: PHASER_STAGES_RANGE walked by its step.
+ * @see data/kernels/phaser.json
+ */
+export const PHASER_STAGE_COUNTS = [
+  2,
+  4,
+  6,
+  8,
+  10,
+  12
+];
+
 /**
  * The highest frequency the phaser's all-pass sweep reaches, Hz.
  * @see data/kernels/phaser.json
@@ -1554,6 +1647,16 @@ export const ROTARY_MIX_RANGE = {
   "defaultFrom": "desk"
 };
 
+/**
+ * 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.
+ * @see data/kernels/rotary.json
+ */
+export const ROTARY_SPEEDS = [
+  "stop",
+  "slow",
+  "fast"
+];
+
 /**
  * The rotary's numeric travels, field → declaration: the ONE map the row's state, its bounds, its OPTIONS and its controller read (`speed` is a member set, ROTARY_SPEEDS, beside it).
  * @see data/kernels/rotary.json
@@ -1689,16 +1792,6 @@ export const ROTARY_STOP_EPS = 0.0001;
  */
 export const ROTARY_RING_FLOATS = 256;
 
-/**
- * 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.
- * @see data/kernels/rotary.json
- */
-export const ROTARY_SPEEDS = [
-  "stop",
-  "slow",
-  "fast"
-];
-
 /**
  * The RTA's target bin resolution — generated into `omx_contract_limits.h` as `OMX_RTA_TARGET_BIN_HZ`, which `mix_dsp.h` reads; `rta-window-derivation.test.ts` reads it back from the header.
  * @see data/kernels/rta.json
@@ -1821,6 +1914,15 @@ export const TREMOLO_MIX_RANGE = {
   "defaultFrom": "desk"
 };
 
+/**
+ * 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).
+ * @see data/kernels/tremolo.json
+ */
+export const TREMOLO_MODES = [
+  "tremolo",
+  "pan"
+];
+
 /**
  * The tremolo's numeric travels, field → declaration: the ONE map the row's state, its bounds, its OPTIONS and its controller read (`mode` is a member set, TREMOLO_MODES, beside it).
  * @see data/kernels/tremolo.json
@@ -1852,15 +1954,6 @@ export const TREMOLO_TRAVELS = {
   }
 };
 
-/**
- * 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).
- * @see data/kernels/tremolo.json
- */
-export const TREMOLO_MODES = [
-  "tremolo",
-  "pan"
-];
-
 /**
  * The Q of a second-order Butterworth section, 1/√2 — maximally flat, the one value every Butterworth biquad in the tree designs at: the LR4 crossover section, the pitch pre-filter and the drive's tilt / band / HF sections, in TS and (as `OMX_BUTTERWORTH_Q`) in C (§7, the scalar door).
  * @see data/primitives.json

package/include/omxcontract/omx_contract_limits.h

@@ -129,6 +129,33 @@
  * 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_BAND_DYN_ATTACK_RANGE_DEFAULT 5
+#define OMX_BAND_DYN_ATTACK_RANGE_MAX 100
+#define OMX_BAND_DYN_ATTACK_RANGE_MIN 0.5f
+#define OMX_BAND_DYN_ATTACK_RANGE_MIN_DOUBLE 0.5
+#define OMX_BAND_DYN_ATTACK_RANGE_STEP 0.1f
+#define OMX_BAND_DYN_ATTACK_RANGE_STEP_DOUBLE 0.1
+#define OMX_BAND_DYN_KNEE_DB 6
+#define OMX_BAND_DYN_MAX_BANDS 9
+#define OMX_BAND_DYN_RANGE_RANGE_DEFAULT -6
+#define OMX_BAND_DYN_RANGE_RANGE_MAX 12
+#define OMX_BAND_DYN_RANGE_RANGE_MIN -24
+#define OMX_BAND_DYN_RANGE_RANGE_STEP 0.5f
+#define OMX_BAND_DYN_RANGE_RANGE_STEP_DOUBLE 0.5
+#define OMX_BAND_DYN_RATIO_RANGE_DEFAULT 2
+#define OMX_BAND_DYN_RATIO_RANGE_MAX 20
+#define OMX_BAND_DYN_RATIO_RANGE_MIN 1
+#define OMX_BAND_DYN_RATIO_RANGE_STEP 0.1f
+#define OMX_BAND_DYN_RATIO_RANGE_STEP_DOUBLE 0.1
+#define OMX_BAND_DYN_RELEASE_RANGE_DEFAULT 100
+#define OMX_BAND_DYN_RELEASE_RANGE_MAX 3000
+#define OMX_BAND_DYN_RELEASE_RANGE_MIN 5
+#define OMX_BAND_DYN_RELEASE_RANGE_STEP 1
+#define OMX_BAND_DYN_THRESHOLD_RANGE_DEFAULT -30
+#define OMX_BAND_DYN_THRESHOLD_RANGE_MAX 0
+#define OMX_BAND_DYN_THRESHOLD_RANGE_MIN -60
+#define OMX_BAND_DYN_THRESHOLD_RANGE_STEP 0.5f
+#define OMX_BAND_DYN_THRESHOLD_RANGE_STEP_DOUBLE 0.5
 #define OMX_BUS_INPUT_CAP 128
 #define OMX_BUTTERWORTH_Q 0.7071067811865476f
 #define OMX_BUTTERWORTH_Q_DOUBLE 0.7071067811865476
@@ -223,6 +250,8 @@
 #define OMX_DELAY_TONE_RANGE_MAX 1
 #define OMX_DELAY_TONE_RANGE_MIN 0
 #define OMX_DELAY_TONE_RANGE_STEP 0
+#define OMX_DETECTOR_OVERSAMPLE_AUTO_MS 0.5f
+#define OMX_DETECTOR_OVERSAMPLE_AUTO_MS_DOUBLE 0.5
 #define OMX_DRIVE_AMOUNT_RANGE_DEFAULT 0
 #define OMX_DRIVE_AMOUNT_RANGE_MAX 36
 #define OMX_DRIVE_AMOUNT_RANGE_MIN 0
@@ -587,6 +616,12 @@
 
 /* Every set rendered to C, sorted by set: an enum of the ids (a named id's position, or a numeric id's number), `OMX_<SET>_COUNT` and,
  * where the set names a default, `OMX_<SET>_DEFAULT`. */
+enum omx_band_dyn_modes {
+  OMX_BAND_DYN_MODES_ABOVE = 0,
+  OMX_BAND_DYN_MODES_BELOW = 1,
+};
+#define OMX_BAND_DYN_MODES_COUNT 2u
+#define OMX_BAND_DYN_MODES_DEFAULT OMX_BAND_DYN_MODES_ABOVE
 enum omx_deess_modes {
   OMX_DEESS_MODES_SPLIT = 0,
   OMX_DEESS_MODES_WIDEBAND = 1,

package/lib/data.mjs

@@ -34,8 +34,7 @@ export function loadData(dir, texts) {
     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;
+    for (const [name, item] of entriesOf(rel, doc)) {
       if (items.has(name)) throw new Error(`${rel}: ${name}: already declared by ${items.get(name).rel}`);
       items.set(name, { name, rel, item });
     }
@@ -43,6 +42,136 @@ export function loadData(dir, texts) {
   return { files, items };
 }
 
+const snakeOf = (n) => n.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+const camelOf = (u) => u.toLowerCase().replace(/_([a-z0-9])/g, (_, x) => x.toUpperCase());
+
+/** The four sections of a kernel file, in their order. */
+export const KERNEL_SECTIONS = ['controls', 'tables', 'aggregates', 'constants'];
+
+/** Whether a data file is a kernel file (`kernels/<kernel>.json`), which holds the four sections, never an item map. */
+export const isKernelFile = (rel) => /(^|\/)kernels\/[^/]+\.json$/.test(rel);
+
+/** The kernel's upper-case prefix, read off its file name: `kernels/band_dyn.json` is BAND_DYN. */
+export const kernelPrefix = (rel) => rel.replace(/^.*\//, '').replace(/\.json$/, '').toUpperCase().replace(/-/g, '_');
+
+/** A control's item name: its `global`, else <KERNEL>_<NAME>_RANGE for a travel and <KERNEL>_<NAME>S for a choice. */
+export const controlGlobal = (rel, c) => c.global ?? `${kernelPrefix(rel)}_${snakeOf(c.name)}${c.kind === 'choice' ? 'S' : '_RANGE'}`;
+
+/**
+ * A data file's items as [name, item] pairs. A kernel file's four sections are expanded into the items the renders
+ * read: a travel control is a `travels` item named by controlGlobal, a choice a `set`; the controls of one `table`
+ * regroup into that table's `travels` item with `fields`; an aggregate is regenerated as fields that reference its
+ * controls; constants pass through. Any other top-level key of a kernel file is not read (validation names it).
+ * rates.json and primitives.json are item maps, read as they are.
+ */
+export function entriesOf(rel, doc) {
+  if (!isKernelFile(rel)) return Object.entries(doc).filter(([name]) => name !== '$schema');
+  const out = [];
+  const controls = Array.isArray(doc.controls) ? doc.controls : [];
+  const tables = new Map(Object.entries(doc.tables ?? {}).map(([n, meta]) => [n, { kind: 'travels', ...meta, fields: {} }]));
+  for (const c of controls) {
+    const { name, kind, global, table, rearms, ...rest } = c;
+    if (table) {
+      if (!tables.has(table)) throw new Error(`${rel}: control ${name} names table ${table}, which is not declared`);
+      tables.get(table).fields[name] = rest.travel;
+      continue;
+    }
+    out.push([controlGlobal(rel, c), kind === 'choice' ? { kind: 'set', ...rest } : { kind: 'travels', ...rest }]);
+  }
+  for (const [n, t] of tables) out.push([n, t]);
+  const byName = new Map(controls.map((c) => [c.name, c]));
+  for (const [n, a] of Object.entries(doc.aggregates ?? {})) {
+    const { fields, ...meta } = a;
+    out.push([n, { kind: 'travels', ...meta, fields: Object.fromEntries((fields ?? []).map((f) => {
+      if (!byName.has(f)) throw new Error(`${rel}: aggregate ${n} names control ${f}, which is not declared`);
+      return [f, { ref: controlGlobal(rel, byName.get(f)) }];
+    })) }]);
+  }
+  for (const [n, item] of Object.entries(doc.constants ?? {})) out.push([n, item]);
+  return out;
+}
+
+/** A kernel's name, read off its file name: `kernels/band_dyn.json` is band_dyn. */
+export const kernelName = (rel) => rel.replace(/^.*\//, '').replace(/\.json$/, '');
+
+/**
+ * Every kernel's controls, in its file's order: `{ <kernel>: { controls: [{ name, kind, global, table?, rearms? }] } }`,
+ * kernels in file order. `global` is the item the control's value lives in: its own travel or set, or, for a field of
+ * a table, the table (`table` names it too, and the field is the control's name). `rearms` is carried only when true:
+ * changing the control re-arms the kernel's state, it is not a smooth parameter.
+ */
+export function kernelControls(data) {
+  const out = {};
+  for (const f of data.files) {
+    if (!isKernelFile(f.rel)) continue;
+    const controls = Array.isArray(f.doc.controls) ? f.doc.controls : [];
+    out[kernelName(f.rel)] = {
+      controls: controls.map((c) => ({
+        name: c.name,
+        kind: c.kind,
+        global: c.table ?? controlGlobal(f.rel, c),
+        ...(c.table ? { table: c.table } : {}),
+        ...(c.rearms === true ? { rearms: true } : {}),
+      })),
+    };
+  }
+  return out;
+}
+
+const isWholeRef = (v) => typeof v === 'object' && v !== null && Object.keys(v).length === 1 && typeof v.ref === 'string' && !v.ref.includes('.');
+
+/**
+ * The kernel file that declares `entries` ([name, item] pairs, the items entriesOf gives back), the inverse of
+ * entriesOf: a single travel is a travel control and a set a choice; a fields table whose every field IS a single
+ * travel of the kernel (`{ ref }`) is an aggregate, and its field names name those controls; any other fields table
+ * is a table whose fields are its controls; every other item is a constant. A control's `global` is written only
+ * when its name does not derive it. `kept`, a kernel file already written, is extended: its declarations stay as
+ * they are and the entries it lacks are added. Empty sections are left out.
+ * @throws naming the item: a fields table that mixes references and travels, an aggregate field whose name is not
+ * its control's.
+ */
+export function kernelDocOf(rel, entries, kept) {
+  const K = kernelPrefix(rel);
+  const doc = kept ? JSON.parse(JSON.stringify(kept)) : {};
+  doc.controls ??= [];
+  for (const s of KERNEL_SECTIONS.slice(1)) doc[s] ??= {};
+  const declared = new Set(entriesOf(rel, kept ?? {}).map(([n]) => n));
+  const singles = new Map(entries.filter(([, it]) => (it.kind === 'travels' && it.travel) || it.kind === 'set'));
+  for (const c of doc.controls) if (!c.table) singles.set(controlGlobal(rel, c), c);
+  const isAggregate = (it) => it.kind === 'travels' && it.fields && Object.values(it.fields).length > 0 && Object.values(it.fields).every((f) => isWholeRef(f) && singles.get(f.ref)?.travel);
+  // an aggregate's field names are its controls' names
+  const named = new Map();
+  for (const [n, it] of entries) if (isAggregate(it)) for (const [f, t] of Object.entries(it.fields)) named.set(t.ref, f);
+  for (const [n, it] of entries) {
+    if (declared.has(n)) continue;
+    if ((it.kind === 'travels' && it.travel) || it.kind === 'set') {
+      const { kind, ...rest } = it;
+      const ck = kind === 'set' ? 'choice' : 'travel';
+      const suffix = ck === 'choice' ? 'S' : '_RANGE';
+      const derived = n.startsWith(`${K}_`) && n.endsWith(suffix) && n.length > K.length + 1 + suffix.length ? camelOf(n.slice(K.length + 1, -suffix.length)) : undefined;
+      const c = { name: named.get(n) ?? derived ?? camelOf(n.endsWith(suffix) ? n.slice(0, -suffix.length) : n), kind: ck };
+      if (controlGlobal(rel, c) !== n) c.global = n;
+      doc.controls.push({ ...c, ...rest });
+    } else if (it.kind === 'travels' && it.fields && isAggregate(it)) {
+      const { kind, fields, ...meta } = it;
+      doc.aggregates[n] = { ...meta, fields: Object.entries(fields).map(([f, t]) => {
+        const c = doc.controls.find((x) => !x.table && controlGlobal(rel, x) === t.ref) ?? { name: named.get(t.ref) };
+        if (c.name !== f) throw new Error(`${rel}: ${n}.${f} refers to ${t.ref}, whose control is named ${c.name}: an aggregate's field is named by its control`);
+        return f;
+      }) };
+    } else if (it.kind === 'travels' && it.fields) {
+      const { kind, fields, ...meta } = it;
+      if (Object.values(fields).some(isWholeRef)) throw new Error(`${rel}: ${n} mixes fields that refer to single travels with travels of its own: declare it as an aggregate of controls, or as a table`);
+      doc.tables[n] = meta;
+      for (const [f, travel] of Object.entries(fields)) doc.controls.push({ name: f, kind: 'travel', table: n, travel });
+    } else {
+      doc.constants[n] = it;
+    }
+  }
+  for (const s of KERNEL_SECTIONS) if (s === 'controls' ? !doc[s].length : !Object.keys(doc[s]).length) delete doc[s];
+  return doc;
+}
+
 /** An item's own value before resolution, by kind. */
 export function rawValue(item) {
   switch (item.kind) {
@@ -111,7 +240,8 @@ const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 
 /**
  * Resolve every item: `{ name, rel, kind, doc, why?, unit?, c?, shape?, default?, labels?, value }` (default and labels: a set's), where `value` has
- * every `{ref}` and `{derive}` evaluated.
+ * every `{ref}` and `{derive}` evaluated. The returned map also carries `kernels`, every kernel's ordered controls
+ * (kernelControls), which the json render publishes beside the items.
  * @throws naming the item: a reference that does not resolve, a cycle, an unknown derivation.
  */
 export function resolveData(data) {
@@ -160,6 +290,7 @@ export function resolveData(data) {
   }
   const out = new Map();
   for (const name of data.items.keys()) out.set(name, resolveItem(name));
+  out.kernels = kernelControls(data);
   return out;
 }