@openmixer/omx-contract 2.0.0 → 2.2.0

package/dist/ts/omx-contract.js

@@ -245,6 +245,25 @@ export const COMP_LIMITS = {
   }
 };
 
+/**
+ * The compressor's character, which picks its detector: `comp` runs the RMS detector, `limiter` the peak detector. The console's comp row carries it (`CompState.kind`, `COMP_KINDS`) and comes up as `comp`.
+ * @see data/kernels/comp.json
+ */
+export const COMP_KINDS = [
+  "comp",
+  "limiter"
+];
+
+/**
+ * The compressor's detector oversampling: `auto` runs the control path at 4x only while the attack is faster than DETECTOR_OVERSAMPLE_AUTO_MS, `off` never, `x4` always (omx-dsp's OMX_DYN_OVS_AUTO, _OFF and _X4, in that order). The console's comp row carries it as the operator's choice (`CompState.detectorOversampling`, spelled auto, off, 4x) and comes up `auto`.
+ * @see data/kernels/comp.json
+ */
+export const DETECTOR_OVERSAMPLINGS = [
+  "auto",
+  "off",
+  "x4"
+];
+
 /**
  * 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.
  * @see data/kernels/comp.json
@@ -423,6 +442,15 @@ export const DELAY_MIX_RANGE = {
   }
 };
 
+/**
+ * The FX delay's PING-PONG switch: on cross-feeds the two legs' feedback, so each leg's repeats come from the other leg's damped tap and the echoes bounce L<->R (`omx_delay.h`'s `struct omx_fx_delay.pingpong`, read where the feedback is formed). A live control on the console's delay row (`DelayState.pingpong`) and on the omx-delay plugin. Its come-up value is FX_DELAY_PINGPONG_DEFAULT, by reference, so the default keeps one home.
+ * @see data/kernels/delay.json
+ */
+export const DELAY_PINGPONGS = [
+  "off",
+  "on"
+];
+
 /**
  * The FX delay's PING-PONG come-up value — a toggle, so it has no travel, only this. Declared here rather than as a literal in the server's `DEFAULT_DELAY_STATE` (which now reads it) so the DPF plugin generator (`packages/omx-plugins/tools/params-gen.mjs`, `2026-09-25-omx-plugins-dpf.md` §3a) reads the same fact the desk seeds a fresh strip with.
  * @see data/kernels/delay.json
@@ -517,54 +545,47 @@ export const DRIVE_BANDS = [
 ];
 
 /**
- * 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.
+ * The drive's AUTO-GAIN switch: on, the stage measures its own level change and matches it out (`omx_drive.h`'s `struct omx_drive.auto_gain`, drive-stage spec §4d), so turning the drive up adds colour rather than loudness. A field of the console's drive row (`DriveState.autoGain`), on at come-up there and in omx-dsp's drive face.
  * @see data/kernels/drive.json
  */
-export const DRIVE_BIAS_MAX = 0.7071067811865476;
+export const DRIVE_AUTO_GAINS = [
+  "off",
+  "on"
+];
 
 /**
- * The frequency band a parametric band can be dragged across.
- * @see data/kernels/eq.json
+ * The drive's STEREO LINK switch: on, ONE auto-gain path is driven by both legs' summed energy, so the image cannot shift under the level match; off, each leg matches its own (`omx_drive.h`'s `struct omx_drive.stereo_link`, spec §4e). A field of the console's drive row (`DriveState.stereoLink`), on at come-up there and in omx-dsp's drive face.
+ * @see data/kernels/drive.json
  */
-export const EQ_FREQ_RANGE = {
-  "min": 20,
-  "max": 20000,
-  "step": 10,
-  "unit": "Hz"
-};
+export const DRIVE_STEREO_LINKS = [
+  "off",
+  "on"
+];
 
 /**
- * The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (`core/src/eq.ts` derives `EQ_GAIN_LIMIT_DB` from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour.
- * @see data/kernels/eq.json
+ * The drive's post-curve HIGH-FREQUENCY ROLL-OFF corner, in Hz: the id is the corner, and 0 names no roll-off (the section does not run: `omx_drive.h`'s `struct omx_drive.hf_on` is 0). The console's drive row offers off, 12000 and 16000 (`DriveState.hfRolloff`, `DRIVE_HF_ROLLOFFS`) and comes up off, as omx-dsp's drive face does.
+ * @see data/kernels/drive.json
  */
-export const EQ_GAIN_RANGE = {
-  "min": -15,
-  "max": 15,
-  "step": 0.5,
-  "unit": "dB"
-};
+export const DRIVE_HF_ROLLOFFS = [
+  0,
+  12000,
+  16000
+];
 
 /**
- * The Q (resonance) extent of a parametric band.
- * @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 EQ_Q_RANGE = {
-  "min": 0.3,
-  "max": 8,
-  "step": 0.1,
-  "unit": ""
-};
+export const DRIVE_BIAS_MAX = 0.7071067811865476;
 
 /**
- * The Q extent of a NOTCH band. Wider than EQ_Q_RANGE on purpose (#116, operator decision): an ultra-narrow surgical cut is the notch shape's whole point — the FBS ring-out pool plants dbx-AFS-style ring killers at Q ≈ 116 (~1/80 octave), inaudible on program yet fatal to a single ringing frequency. Gain-carrying shapes stay bounded at EQ_Q_RANGE — a Q-116 bell is a resonator, not an EQ move.
+ * The HPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).
  * @see data/kernels/eq.json
  */
-export const EQ_NOTCH_Q_RANGE = {
-  "min": 0.3,
-  "max": 116,
-  "step": 1,
-  "unit": ""
-};
+export const EQ_HPF_ONS = [
+  "off",
+  "on"
+];
 
 /**
  * Where the HPF cutoff can sit (low end); mirrors the drawn low-frequency handle.
@@ -577,6 +598,24 @@ export const HPF_FREQ_RANGE = {
   "unit": "Hz"
 };
 
+/**
+ * The pass-filter slopes the EQ offers, in dB per octave: the HPF's slope, and by use the LPF's. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.
+ * @see data/kernels/eq.json
+ */
+export const FILTER_SLOPES = [
+  12,
+  24
+];
+
+/**
+ * The LPF's switch: off, the filter is not in the EQ's bank at all; on, its one or two Butterworth sections run after the bands and the HPF. It comes up off, on the console's channel EQ and in omx-dsp's EQ face (see EQ_PASS_FILTER_DEFAULTS).
+ * @see data/kernels/eq.json
+ */
+export const EQ_LPF_ONS = [
+  "off",
+  "on"
+];
+
 /**
  * Where the LPF cutoff can sit (high end).
  * @see data/kernels/eq.json
@@ -602,12 +641,56 @@ export const EQ_BAND_TYPES = [
 ];
 
 /**
- * The pass-filter slopes the EQ offers, in dB per octave. The id is the slope: 12 is one maximally flat section, 24 the two-section Butterworth.
+ * The frequency band a parametric band can be dragged across.
  * @see data/kernels/eq.json
  */
-export const FILTER_SLOPES = [
-  12,
-  24
+export const EQ_FREQ_RANGE = {
+  "min": 20,
+  "max": 20000,
+  "step": 10,
+  "unit": "Hz"
+};
+
+/**
+ * The parametric-band gain travel, in dB. The ± scalar `clampEqGain` enforces is READ off this (`core/src/eq.ts` derives `EQ_GAIN_LIMIT_DB` from `max`), so the bound is stated once and a surface cannot draw a wider knob than the clamp will honour.
+ * @see data/kernels/eq.json
+ */
+export const EQ_GAIN_RANGE = {
+  "min": -15,
+  "max": 15,
+  "step": 0.5,
+  "unit": "dB"
+};
+
+/**
+ * The Q (resonance) extent of a parametric band.
+ * @see data/kernels/eq.json
+ */
+export const EQ_Q_RANGE = {
+  "min": 0.3,
+  "max": 8,
+  "step": 0.1,
+  "unit": ""
+};
+
+/**
+ * The Q extent of a NOTCH band. Wider than EQ_Q_RANGE on purpose (#116, operator decision): an ultra-narrow surgical cut is the notch shape's whole point — the FBS ring-out pool plants dbx-AFS-style ring killers at Q ≈ 116 (~1/80 octave), inaudible on program yet fatal to a single ringing frequency. Gain-carrying shapes stay bounded at EQ_Q_RANGE — a Q-116 bell is a resonator, not an EQ move.
+ * @see data/kernels/eq.json
+ */
+export const EQ_NOTCH_Q_RANGE = {
+  "min": 0.3,
+  "max": 116,
+  "step": 1,
+  "unit": ""
+};
+
+/**
+ * A band's switch. Off, the band is not in the EQ's bank (the slots close up); on, it runs, parked when it is a gain-carrying shape at 0 dB. No come-up value is declared, because the strips differ: the console's channel EQ brings its default bands up on, an omx-eq plugin brings every band up off so a racked instance is a wire.
+ * @see data/kernels/eq.json
+ */
+export const EQ_BAND_ONS = [
+  "off",
+  "on"
 ];
 
 /**

package/include/omxcontract/omx_contract_limits.h

@@ -622,11 +622,36 @@ enum omx_band_dyn_modes {
 };
 #define OMX_BAND_DYN_MODES_COUNT 2u
 #define OMX_BAND_DYN_MODES_DEFAULT OMX_BAND_DYN_MODES_ABOVE
+enum omx_comp_kinds {
+  OMX_COMP_KINDS_COMP = 0,
+  OMX_COMP_KINDS_LIMITER = 1,
+};
+#define OMX_COMP_KINDS_COUNT 2u
+#define OMX_COMP_KINDS_DEFAULT OMX_COMP_KINDS_COMP
 enum omx_deess_modes {
   OMX_DEESS_MODES_SPLIT = 0,
   OMX_DEESS_MODES_WIDEBAND = 1,
 };
 #define OMX_DEESS_MODES_COUNT 2u
+enum omx_delay_pingpongs {
+  OMX_DELAY_PINGPONGS_OFF = 0,
+  OMX_DELAY_PINGPONGS_ON = 1,
+};
+#define OMX_DELAY_PINGPONGS_COUNT 2u
+#define OMX_DELAY_PINGPONGS_DEFAULT OMX_DELAY_PINGPONGS_OFF
+enum omx_detector_oversamplings {
+  OMX_DETECTOR_OVERSAMPLINGS_AUTO = 0,
+  OMX_DETECTOR_OVERSAMPLINGS_OFF = 1,
+  OMX_DETECTOR_OVERSAMPLINGS_X4 = 2,
+};
+#define OMX_DETECTOR_OVERSAMPLINGS_COUNT 3u
+#define OMX_DETECTOR_OVERSAMPLINGS_DEFAULT OMX_DETECTOR_OVERSAMPLINGS_AUTO
+enum omx_drive_auto_gains {
+  OMX_DRIVE_AUTO_GAINS_OFF = 0,
+  OMX_DRIVE_AUTO_GAINS_ON = 1,
+};
+#define OMX_DRIVE_AUTO_GAINS_COUNT 2u
+#define OMX_DRIVE_AUTO_GAINS_DEFAULT OMX_DRIVE_AUTO_GAINS_ON
 enum omx_drive_bands {
   OMX_DRIVE_BANDS_FULL = 0,
   OMX_DRIVE_BANDS_LOW = 1,
@@ -641,6 +666,24 @@ enum omx_drive_curves {
   OMX_DRIVE_CURVES_EXCITER = 3,
 };
 #define OMX_DRIVE_CURVES_COUNT 4u
+enum omx_drive_hf_rolloffs {
+  OMX_DRIVE_HF_ROLLOFFS_0 = 0,
+  OMX_DRIVE_HF_ROLLOFFS_12000 = 12000,
+  OMX_DRIVE_HF_ROLLOFFS_16000 = 16000,
+};
+#define OMX_DRIVE_HF_ROLLOFFS_COUNT 3u
+#define OMX_DRIVE_HF_ROLLOFFS_DEFAULT OMX_DRIVE_HF_ROLLOFFS_0
+enum omx_drive_stereo_links {
+  OMX_DRIVE_STEREO_LINKS_OFF = 0,
+  OMX_DRIVE_STEREO_LINKS_ON = 1,
+};
+#define OMX_DRIVE_STEREO_LINKS_COUNT 2u
+#define OMX_DRIVE_STEREO_LINKS_DEFAULT OMX_DRIVE_STEREO_LINKS_ON
+enum omx_eq_band_ons {
+  OMX_EQ_BAND_ONS_OFF = 0,
+  OMX_EQ_BAND_ONS_ON = 1,
+};
+#define OMX_EQ_BAND_ONS_COUNT 2u
 enum omx_eq_band_types {
   OMX_EQ_BAND_TYPES_BELL = 0,
   OMX_EQ_BAND_TYPES_LOW_SHELF = 1,
@@ -651,6 +694,18 @@ enum omx_eq_band_types {
 };
 #define OMX_EQ_BAND_TYPES_COUNT 6u
 #define OMX_EQ_BAND_TYPES_DEFAULT OMX_EQ_BAND_TYPES_BELL
+enum omx_eq_hpf_ons {
+  OMX_EQ_HPF_ONS_OFF = 0,
+  OMX_EQ_HPF_ONS_ON = 1,
+};
+#define OMX_EQ_HPF_ONS_COUNT 2u
+#define OMX_EQ_HPF_ONS_DEFAULT OMX_EQ_HPF_ONS_OFF
+enum omx_eq_lpf_ons {
+  OMX_EQ_LPF_ONS_OFF = 0,
+  OMX_EQ_LPF_ONS_ON = 1,
+};
+#define OMX_EQ_LPF_ONS_COUNT 2u
+#define OMX_EQ_LPF_ONS_DEFAULT OMX_EQ_LPF_ONS_OFF
 enum omx_filter_slopes {
   OMX_FILTER_SLOPES_12 = 12,
   OMX_FILTER_SLOPES_24 = 24,

package/lib/data.mjs

@@ -54,6 +54,13 @@ 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, '_');
 
+/**
+ * Whether a control is a USE: it declares no travel and no ids of its own and takes its values from the item its
+ * `global` names, which another control of the same kernel declares (the EQ's lpfSlope takes FILTER_SLOPES, which
+ * hpfSlope declares). A use adds no item; it is a control of the kernel all the same.
+ */
+export const isUse = (c) => c && !c.table && c.travel === undefined && c.ids === undefined && typeof c.global === 'string';
+
 /** 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'}`;
 
@@ -69,16 +76,20 @@ export function entriesOf(rel, doc) {
   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: {} }]));
+  const placed = new Set();
   for (const c of controls) {
-    const { name, kind, global, table, ...rest } = c;
+    const { name, kind, global, table, rearms, count, of, when, ...rest } = c;
+    if (isUse(c)) continue;
     if (table) {
       if (!tables.has(table)) throw new Error(`${rel}: control ${name} names table ${table}, which is not declared`);
+      // a table is an item where its first control stands, so a control after a table keeps its place
+      if (!placed.has(table)) { placed.add(table); out.push([table, tables.get(table)]); }
       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]);
+  for (const [n, t] of tables) if (!placed.has(n)) 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;
@@ -91,6 +102,42 @@ export function entriesOf(rel, doc) {
   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?, count?, when? }] } }`,
+ * 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. `count` names the item that counts a
+ * control the kernel takes once per band (a scalar, or a sheet whose every variant gives its count as `max`). A
+ * control that declares `of` is no control of its own but the travel the control it names reaches while the choice
+ * `when` names holds the id it names: it is listed under that control's `when` as `{ control, is, global }`.
+ */
+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 : [];
+    const global = (c) => c.table ?? controlGlobal(f.rel, c);
+    out[kernelName(f.rel)] = {
+      controls: controls.filter((c) => c.of === undefined).map((c) => {
+        const when = controls.filter((x) => x.of === c.name).map((x) => ({ control: x.when.control, is: x.when.is, global: global(x) }));
+        return {
+          name: c.name,
+          kind: c.kind,
+          global: global(c),
+          ...(c.table ? { table: c.table } : {}),
+          ...(c.rearms === true ? { rearms: true } : {}),
+          ...(c.count !== undefined ? { count: c.count } : {}),
+          ...(when.length ? { when } : {}),
+        };
+      }),
+    };
+  }
+  return out;
+}
+
 const isWholeRef = (v) => typeof v === 'object' && v !== null && Object.keys(v).length === 1 && typeof v.ref === 'string' && !v.ref.includes('.');
 
 /**
@@ -213,7 +260,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) {
@@ -251,7 +299,7 @@ export function resolveData(data) {
     if (item.unit !== undefined) r.unit = item.unit;
     if (item.c !== undefined) r.c = item.c;
     if (item.kind === 'set') {
-      if (item.default !== undefined) r.default = item.default;
+      if (item.default !== undefined) r.default = setDefault(item, (v) => val(v, name), name);
       if (item.labels !== undefined) r.labels = item.labels;
     }
     if (item.kind === 'travels') r.shape = item.fields ? 'table' : 'travel';
@@ -262,9 +310,24 @@ 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;
 }
 
+/**
+ * A set's default, resolved: an id as written, or `{ ref }` to the scalar that states it. A boolean scalar names the
+ * second id of a two-id switch when true and the first when false (FX_DELAY_PINGPONG_DEFAULT is the delay's
+ * DELAY_PINGPONG_SWITCH default, so the come-up value keeps one home).
+ * @throws naming the set: a boolean default of a set that is not two ids.
+ */
+export function setDefault(item, val, name) {
+  if (!isObj(item.default)) return item.default;
+  const v = val(item.default);
+  if (typeof v !== 'boolean') return v;
+  if (item.ids.length !== 2) throw new Error(`${name}: a boolean default needs a two-id switch, not ${item.ids.length} ids`);
+  return item.ids[v ? 1 : 0];
+}
+
 /** 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

@@ -8,7 +8,7 @@
  */
 
 const ORDER = {
-  control: ['name', 'kind', 'global', 'table', 'since', 'doc', 'why', 'unit', 'ids', 'default', 'labels', 'travel', 'c'],
+  control: ['name', 'kind', 'global', 'table', 'rearms', 'since', 'doc', 'why', 'unit', 'ids', 'default', 'labels', 'travel', 'c'],
   sections: ['controls', 'tables', 'aggregates', 'constants'],
   item: ['kind', 'since', 'doc', 'why', 'unit', 'value', 'values', 'ids', 'default', 'labels', 'fields', 'travel', 'c'],
   travel: ['min', 'max', 'step', 'unit', 'default', 'defaultFrom', 'scale', 'byKind', 'doc', 'why'],

package/lib/validate.mjs

@@ -8,7 +8,7 @@
 import { readFileSync } from 'node:fs';
 import { posix } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
-import { KERNEL_SECTIONS, entriesOf, isKernelFile, resolveData } from './data.mjs';
+import { KERNEL_SECTIONS, controlGlobal, entriesOf, isKernelFile, isUse, resolveData } from './data.mjs';
 import { eqDefaultBands, eqDefaultParams } from './eq-defaults.mjs';
 import { renderC } from '../render/c.mjs';
 import { renderTs } from '../render/ts.mjs';
@@ -18,7 +18,10 @@ 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.
+ * `table` declared under `tables`; `rearms` a boolean, and only on a control; a use (a control with a `global` and no
+ * travel or ids) naming an item another control of the kernel declares, of its kind; `count` an item name; `of` naming
+ * another control of its kind with `when` a { control, is } of a choice of the kernel; 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) {
@@ -37,10 +40,31 @@ export function shapeProblems(rel, doc) {
     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"`);
+    if (c.kind !== 'travel' && c.kind !== 'choice') out.push(`controls[${i}] ${c.name}: kind ${JSON.stringify(c.kind)} is neither travel nor choice`);
+    else if (isUse(c)) {
+      const owner = controls.find((x) => x !== c && !isUse(x) && !x.table && controlGlobal(rel, x) === c.global);
+      if (!owner) out.push(`controls[${i}] ${c.name}: uses ${c.global}, which no other control of this kernel declares`);
+      else if (owner.kind !== c.kind) out.push(`controls[${i}] ${c.name}: a ${c.kind} that uses ${c.global}, which is a ${owner.kind}`);
+      for (const k of ['doc', 'default', 'labels', 'c']) if (k in c) out.push(`controls[${i}] ${c.name}: a use carries no ${k}; ${c.global} holds it`);
+    } else 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 ('count' in c && (typeof c.count !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(c.count))) out.push(`controls[${i}] ${c.name}: count ${JSON.stringify(c.count)} is not an item name`);
+    if ('of' in c || 'when' in c) {
+      const target = controls.find((x) => x.name === c.of);
+      const w = c.when;
+      const chooser = w && controls.find((x) => x.name === w.control);
+      const ids = chooser && (isUse(chooser) ? controls.find((x) => !isUse(x) && controlGlobal(rel, x) === chooser.global)?.ids : chooser.ids);
+      if (!target || target === c || target.of !== undefined || target.kind !== c.kind) out.push(`controls[${i}] ${c.name}: of ${JSON.stringify(c.of)} names no other control of its kind`);
+      else if (!w || typeof w !== 'object' || Object.keys(w).sort().join() !== 'control,is') out.push(`controls[${i}] ${c.name}: when must be { control, is }`);
+      else if (!chooser || chooser.kind !== 'choice') out.push(`controls[${i}] ${c.name}: when.control ${JSON.stringify(w.control)} names no choice of this kernel`);
+      else if (!(ids ?? []).includes(w.is)) out.push(`controls[${i}] ${c.name}: when.is ${JSON.stringify(w.is)} is not an id of ${w.control}`);
+      if (c.count !== undefined) out.push(`controls[${i}] ${c.name}: a control with of is counted as the control it names`);
+    }
     if (c.table && !(doc.tables && c.table in doc.tables)) out.push(`controls[${i}] ${c.name}: table ${c.table} is not declared`);
+    if ('rearms' in c && typeof c.rearms !== 'boolean') out.push(`controls[${i}] ${c.name}: rearms ${JSON.stringify(c.rearms)} is not a boolean`);
+  }
+  for (const s of ['tables', 'aggregates', 'constants']) {
+    for (const [n, it] of Object.entries(doc[s] ?? {})) if (it && typeof it === 'object' && 'rearms' in it) out.push(`${s} ${n}: rearms is a control's flag, never a ${s.slice(0, -1)}'s`);
   }
   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 ?? {})) {
@@ -75,6 +99,19 @@ function semanticRules(resolved, say) {
     }
   }
 
+  // A per-band control's count: a positive integer scalar, or a sheet whose every variant has a positive integer max.
+  for (const [k, { controls }] of Object.entries(resolved.kernels ?? {})) {
+    for (const c of controls) {
+      if (c.count === undefined) continue;
+      const it = resolved.get(c.count);
+      const rel = `data/kernels/${k}.json`;
+      if (!it) { say(rel, c.global, 'count', `${k}.${c.name}: count ${c.count} is no item`); continue; }
+      const ok = (n) => Number.isInteger(n) && n >= 1;
+      const good = it.kind === 'scalar' ? ok(it.value) : it.kind === 'sheet' && Object.values(it.value).length > 0 && Object.values(it.value).every((v) => ok(v?.max));
+      if (!good) say(rel, c.global, 'count', `${k}.${c.name}: count ${c.count} is neither a positive integer scalar nor a sheet of variants with a positive integer max`);
+    }
+  }
+
   // The EQ band budget (ruling 2026-10-08): what the operator keeps, what the feedback suppressor plants
   // and what the ring correction plants all fit in the band maximum.
   const reserve = val('OPERATOR_EQ_BANDS_RESERVE');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "2.0.0",
+  "version": "2.2.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/render/json.mjs

@@ -2,7 +2,9 @@
 // Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
 /**
  * The `json` target: the resolved data (every reference and derivation evaluated) for readers in
- * other languages, which need no resolver of their own.
+ * other languages, which need no resolver of their own. Beside the items, `kernels` lists each
+ * kernel's controls in their declared order (name, kind, the global each resolves to, the table of a
+ * table field, `rearms` when changing it re-arms the kernel's state), so a reader needs no kernel file.
  */
 
 /** Every file of the `json` target: `[{ path, text }]`. */
@@ -12,5 +14,7 @@ export function renderJson(resolved, version) {
     const { name, ...rest } = r;
     items[name] = rest;
   }
-  return [{ path: 'omx-contract.json', text: `${JSON.stringify({ name: '@openmixer/omx-contract', version, items }, null, 2)}\n` }];
+  const doc = { name: '@openmixer/omx-contract', version, items };
+  if (resolved.kernels) doc.kernels = resolved.kernels;
+  return [{ path: 'omx-contract.json', text: `${JSON.stringify(doc, null, 2)}\n` }];
 }

package/schema/omx-contract.schema.json

@@ -166,7 +166,7 @@
     },
     "set": {
       "type": "object",
-      "description": "Ordered ids with an optional default and labels. The ids and their order are the contract: all strings (the id is the name, its position the value) or all non-negative integers (the id is the value). Labels are face text and optional.",
+      "description": "Ordered ids with an optional default and labels. The ids and their order are the contract: all strings (the id is the name, its position the value) or all non-negative integers (the id is the value). Labels are face text and optional. The default may be a reference to the scalar that states it: a boolean names the second id of a two-id switch when true, the first when false.",
       "properties": {
         "kind": { "const": "set" },
         "since": { "$ref": "#/$defs/since" },
@@ -178,7 +178,7 @@
             { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 1, "uniqueItems": true }
           ]
         },
-        "default": { "oneOf": [{ "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]*$" }, { "type": "integer", "minimum": 0 }] },
+        "default": { "oneOf": [{ "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9]*$" }, { "type": "integer", "minimum": 0 }, { "$ref": "#/$defs/ref" }] },
         "labels": { "type": "array", "items": { "$ref": "#/$defs/text" }, "minItems": 1 }
       },
       "required": ["kind", "doc", "ids"],