@openmixer/omx-contract 0.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,55 @@
-# @openmixer/omx-contract
+<!-- SPDX-License-Identifier: GPL-3.0-or-later -->
+<!-- Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com> -->
+# omx-contract
 
-The parameter, limit and law declarations of OpenMixer's DSP kernels and effects, as data, with the
-generators that render them for C, TypeScript, CLAP and LV2.
+The FreeMixer declarations as data: what a value may be (a travel, a default, a kernel constant, a
+list), as JSON validated by a JSON Schema, rendered by one CLI into
+every language that reads it. Governed by openmixer's
+`docs/design/specs/2026-10-05-omx-contract.md`; 1.0.0 carries the phase-1 items of its §4.1, what
+omx-dsp needs, and 1.1.0 adds the flanger, de-esser, phaser, rotary, tremolo and graphic EQ kernels.
 
-This 0.0.0 only reserves the name. The first real release is 1.0.0, published from
-https://github.com/FreeMixer/omx-contract by its release workflow.
+```
+data/                        the declaration, one file per group, edited by hand
+  rates.json  primitives.json  kernels/<kernel>.json
+schema/omx-contract.schema.json   JSON Schema 2020-12: five kinds, closed units, refs, closed derivations
+bin/omx-contract.mjs         the CLI
+render/                      c.mjs (openmixer's renderer, moved unchanged, under c/), ts.mjs, json.mjs
+include/omxcontract/         the committed c render (what omx-contract-devel installs)
+share/omx-contract/          the committed json render (resolved data)
+test/                        schema, semantic checks, goldens, perturbation, semver, round trip
+tools/proof/round-trip.mjs   the spec §4.4 steps 1 and 2 proof against omx-dsp v0.1.3
+recipes/kernel.recipe.json   what a complete kernel has; recipes/answers/ cites each value in the engine
+tools/omx-new-kernel.mjs     the kernel wizard and importer; tools/kernel-recipe.mjs is `make completeness`
+tools/seed/                  the one-time seed from openmixer's built core (provenance; never run by CI)
+packaging/ debian/           omx-contract-devel (RPM), libomx-contract-dev (deb)
+```
+
+## The CLI
+
+```
+npm ci
+node bin/omx-contract.mjs validate                       # schema + semantic checks
+node bin/omx-contract.mjs fmt [--check]                  # the one formatting
+node bin/omx-contract.mjs render --target c|ts|json --out <dir> [--check]
+node bin/omx-contract.mjs semver <previous tag>          # exit 1 if the version bump is short
+```
+
+Exit 0 is a pass, 1 a failure naming file, item and rule, 2 a usage or environment error. A change to
+`data/` is followed by `render --target c --out include`, `render --target json --out
+share/omx-contract` and `render --target ts --out test/golden/ts`; CI holds all three to the data.
+
+## Consuming it
+
+Pin one version (`omx-contract 1.1.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.1.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).
+
+The npm package is `@openmixer/omx-contract` on npmjs.org (the `ts` render is its main export); every
+GitHub release also carries the `npm pack` tarball, the RPMs and the debs.
+
+## License
+
+GPL-3.0-or-later. JSON cannot carry an SPDX comment; every data file is covered by `LICENSE`.

package/bin/omx-contract.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * omx-contract — the declarations as data, validated and rendered (omx-contract spec §3.4).
+ *
+ *   omx-contract validate [--data <dir>]                       schema + semantic checks
+ *   omx-contract fmt [--check] [--data <dir>]                  the one formatting
+ *   omx-contract render --target c|ts|json --out <dir> [--check] [--data <dir> | --sheet <fixture>]
+ *   omx-contract semver <previous tag> | --from-dir <data dir> --from-version <x.y.z>
+ *
+ * Exit 0 is a pass, 1 a failure naming what failed, 2 a usage or environment error (never a pass).
+ */
+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 { formatDoc } from '../lib/fmt.mjs';
+import { classify, refusal } from '../lib/semver.mjs';
+import { validateData } from '../lib/validate.mjs';
+import { renderC, renderSheetC } from '../render/c.mjs';
+import { renderJson } from '../render/json.mjs';
+import { renderTs } from '../render/ts.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+class Usage extends Error {}
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i < 0) return undefined;
+  if (i + 1 >= argv.length || argv[i + 1].startsWith('--')) throw new Usage(`${name} needs a value`);
+  return argv[i + 1];
+}
+
+function load(argv) {
+  const dir = resolve(opt(argv, '--data') ?? join(ROOT, 'data'));
+  if (!existsSync(dir)) throw new Usage(`no data directory ${dir}`);
+  return loadData(dir);
+}
+
+/** Every file under `dir`, relative to it. */
+function filesUnder(dir) {
+  if (!existsSync(dir)) return [];
+  const out = [];
+  const walk = (d) => {
+    for (const f of readdirSync(d)) {
+      const p = join(d, f);
+      if (statSync(p).isDirectory()) walk(p);
+      else out.push(relative(dir, p));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+function cmdValidate(argv) {
+  const data = load(argv);
+  const problems = validateData(data);
+  for (const p of problems) console.error(`${p.file}: ${p.item}: ${p.rule}: ${p.message}`);
+  if (problems.length) return 1;
+  console.log(`omx-contract validate: ${data.items.size} items in ${data.files.length} files, valid`);
+  return 0;
+}
+
+function cmdFmt(argv) {
+  const dir = resolve(opt(argv, '--data') ?? join(ROOT, 'data'));
+  const data = load(argv);
+  const check = argv.includes('--check');
+  let bad = 0;
+  for (const f of data.files) {
+    const want = formatDoc(f.doc);
+    if (want === f.text) continue;
+    if (check) { console.error(`omx-contract fmt --check: ${f.rel} is not in the one formatting`); bad++; } else writeFileSync(join(dir, '..', f.rel), want);
+  }
+  if (bad) return 1;
+  console.log(`omx-contract fmt${check ? ' --check' : ''}: ${data.files.length} files formatted`);
+  return 0;
+}
+
+export function renderTarget(target, argv) {
+  const sheet = opt(argv, '--sheet');
+  if (sheet) {
+    if (target !== 'c') throw new Usage('--sheet renders the c target only');
+    return renderSheetC(JSON.parse(readFileSync(resolve(sheet), 'utf8')));
+  }
+  const data = load(argv);
+  const resolved = resolveData(data);
+  if (target === 'c') return renderC(resolved);
+  if (target === 'ts') return renderTs(resolved);
+  if (target === 'json') return renderJson(resolved, packageVersion(ROOT));
+  throw new Usage(`unknown target ${target} (c, ts, json)`);
+}
+
+function cmdRender(argv) {
+  const target = opt(argv, '--target');
+  const out = opt(argv, '--out');
+  if (!target || !out) throw new Usage('render needs --target <c|ts|json> and --out <dir>');
+  const files = renderTarget(target, argv);
+  const dir = resolve(out);
+  if (argv.includes('--check')) {
+    const bad = [];
+    for (const f of files) {
+      const p = join(dir, f.path);
+      if (!existsSync(p)) bad.push(`${f.path} is missing`);
+      else if (readFileSync(p, 'utf8') !== f.text) bad.push(`${f.path} differs`);
+    }
+    const scope = target === 'c' ? 'omxcontract' : '';
+    const named = new Set(files.map((f) => f.path));
+    for (const rel of filesUnder(join(dir, scope))) if (!named.has(join(scope, rel))) bad.push(`${join(scope, rel)} is extra`);
+    for (const b of bad) console.error(`omx-contract render --check: ${out.replace(/\/$/, '')}/${b}`);
+    if (bad.length) return 1;
+    console.log(`omx-contract render --target ${target} --check: ${files.length} files byte-identical under ${out}`);
+    return 0;
+  }
+  for (const f of files) {
+    mkdirSync(dirname(join(dir, f.path)), { recursive: true });
+    writeFileSync(join(dir, f.path), f.text);
+  }
+  console.log(`omx-contract render --target ${target}: wrote ${files.length} files under ${out}`);
+  return 0;
+}
+
+/** The data of a git tag, as `{ rel: text }`. */
+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}`);
+  return texts;
+}
+
+function cmdSemver(argv) {
+  const fromDir = opt(argv, '--from-dir');
+  let prev;
+  let from;
+  if (fromDir) {
+    from = opt(argv, '--from-version');
+    if (!from) throw new Usage('--from-dir needs --from-version');
+    prev = loadData(resolve(fromDir));
+  } else {
+    const tag = argv[1];
+    if (!tag || tag.startsWith('--')) throw new Usage('semver needs the previous tag');
+    from = tag;
+    prev = loadData(null, dataAtTag(tag));
+  }
+  const to = opt(argv, '--version') ?? packageVersion(ROOT);
+  const { level, changes } = classify(resolveData(prev), resolveData(load(argv)));
+  for (const c of changes) console.log(`${c.level.toUpperCase()} ${c.item}: ${c.what}`);
+  const why = refusal(level, from, to);
+  console.log(JSON.stringify({ from: from.replace(/^v/, ''), to, level, changes: changes.length, ok: !why }));
+  if (why) { console.error(`omx-contract semver: ${why}`); return 1; }
+  return 0;
+}
+
+const USAGE = `usage: omx-contract validate [--data <dir>]
+       omx-contract fmt [--check] [--data <dir>]
+       omx-contract render --target c|ts|json --out <dir> [--check] [--data <dir> | --sheet <fixture.json>]
+       omx-contract semver <previous tag> | --from-dir <data dir> --from-version <x.y.z> [--version <x.y.z>]`;
+
+export function main(argv) {
+  const cmds = { validate: cmdValidate, fmt: cmdFmt, render: cmdRender, semver: cmdSemver };
+  try {
+    const cmd = cmds[argv[0]];
+    if (!cmd) throw new Usage(argv[0] ? `unknown command ${argv[0]}` : 'no command');
+    return cmd(argv);
+  } catch (e) {
+    if (e instanceof Usage) { console.error(`omx-contract: ${e.message}\n${USAGE}`); return 2; }
+    console.error(`omx-contract: ${e.message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/data/kernels/chorus.json

@@ -0,0 +1,15 @@
+{
+  "$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"
+    }
+  }
+}

package/data/kernels/comp.json

@@ -0,0 +1,81 @@
+{
+  "$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": {
+        "min": -60,
+        "max": 0,
+        "step": 1,
+        "unit": "dB",
+        "default": -18,
+        "defaultFrom": "desk"
+      },
+      "ratio": {
+        "min": 1,
+        "max": 20,
+        "step": 0.5,
+        "unit": "",
+        "default": 4,
+        "defaultFrom": "desk"
+      },
+      "kneeDb": {
+        "min": 0,
+        "max": 24,
+        "step": 0.5,
+        "unit": "dB",
+        "default": 6,
+        "defaultFrom": "desk"
+      },
+      "attackMs": {
+        "min": 0.1,
+        "max": 100,
+        "step": 1,
+        "unit": "ms",
+        "default": 5,
+        "defaultFrom": "desk"
+      },
+      "releaseMs": {
+        "min": 5,
+        "max": 3000,
+        "step": 10,
+        "unit": "ms",
+        "default": 200,
+        "defaultFrom": "desk"
+      },
+      "makeupDb": {
+        "min": 0,
+        "max": 24,
+        "step": 0.5,
+        "unit": "dB",
+        "default": 0,
+        "defaultFrom": "desk"
+      },
+      "mixPct": {
+        "min": 0,
+        "max": 100,
+        "step": 5,
+        "unit": "%",
+        "default": 100,
+        "defaultFrom": "desk"
+      }
+    }
+  },
+  "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
+        }
+      }
+    }
+  }
+}

package/data/kernels/deesser.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "DEESS_FREQ_RANGE": {
+    "kind": "travels",
+    "doc": "The detector band's CENTRE, in Hz. Sibilance lives at 5–10 kHz on most voices; 7 kHz with the default width covers 4 950–9 900 Hz, which is where an \"s\" and a \"t\" sit on a close vocal mic. The travel is wider than the come-up on both sides on purpose: a bright female vocal wants the band up near 9 kHz and a chesty male one down at 5, and a surface narrower than the row removes reach the console genuinely has (the same reasoning core's `REVERB_CUT_RANGE` records).",
+    "travel": {
+      "min": 2000,
+      "max": 16000,
+      "step": 10,
+      "unit": "Hz",
+      "default": 7000,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_WIDTH_RANGE": {
+    "kind": "travels",
+    "doc": "The band's WIDTH, in OCTAVES around the centre: the edges are `f / 2^(w/2)` and `f · 2^(w/2)`, which is what makes the centre the geometric middle at every width. Octaves and not a Q, because a Q is a property of one section and this band is TWO (a highpass and a lowpass, `mix_deesser.h`) — an operator asked to dial a Q would be dialling a number neither filter carries. One octave is the classic de-esser band: wide enough for a sibilant that moves with the vowel, narrow enough that a 1 kHz vowel sits 27.8 dB down the skirt.",
+    "travel": {
+      "min": 0.25,
+      "max": 4,
+      "step": 0.05,
+      "unit": "oct",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_THRESHOLD_RANGE": {
+    "kind": "travels",
+    "doc": "Where reduction starts — the level of the BAND, not of the strip, which is why the come-up is so much lower than the compressor's. A vocal peaking −12 dBFS carries roughly −30 dBFS in a one-octave band at 7 kHz on its sibilants and under −40 on its vowels, so −30 sits between the two and the stage opens on an \"s\" and stays shut on an \"ah\".",
+    "travel": {
+      "min": -60,
+      "max": 0,
+      "step": 0.5,
+      "unit": "dB",
+      "default": -30,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RATIO_RANGE": {
+    "kind": "travels",
+    "doc": "How hard the band is held once it is over the threshold. 4:1 is the textbook de-esser ratio: firm on the \"s\", short of a limiter.",
+    "travel": {
+      "min": 1,
+      "max": 20,
+      "step": 0.1,
+      "unit": "",
+      "default": 4,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RANGE_RANGE": {
+    "kind": "travels",
+    "doc": "The FLOOR on the reduction, in dB and never positive — the deepest cut the stage may reach however loud the sibilant is (`mix_deesser.h`'s clamp, §4c). 12 dB tames a hard sibilant; past that a voice starts to lisp, and a de-esser with NO floor turns a shouted \"s\" into a hole. The ceiling is 0, which switches the reduction off without switching the stage off — a legitimate thing to want while dialling the band in by ear.",
+    "travel": {
+      "min": -24,
+      "max": 0,
+      "step": 0.5,
+      "unit": "dB",
+      "default": -12,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_ATTACK_RANGE": {
+    "kind": "travels",
+    "doc": "The detector's ATTACK, in ms. A sibilant's onset is a few milliseconds; 1 ms catches it without the detector chattering on the band's own waveform.",
+    "travel": {
+      "min": 0.1,
+      "max": 50,
+      "step": 0.1,
+      "unit": "ms",
+      "default": 1,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_RELEASE_RANGE": {
+    "kind": "travels",
+    "doc": "The detector's RELEASE, in ms. 60 ms is long enough not to modulate inside one \"s\" and short enough to be open again for the next syllable.",
+    "travel": {
+      "min": 5,
+      "max": 500,
+      "step": 1,
+      "unit": "ms",
+      "default": 60,
+      "defaultFrom": "desk"
+    }
+  },
+  "DEESS_KNEE_DB": {
+    "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
+  }
+}

package/data/kernels/delay.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "FX_DELAY_TIME_RANGE": {
+    "kind": "travels",
+    "doc": "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.",
+    "travel": {
+      "min": 0,
+      "max": 2000,
+      "step": 1,
+      "unit": "ms",
+      "default": 300,
+      "defaultFrom": "desk"
+    },
+    "c": {
+      "alias": {
+        "fact": "delay",
+        "field": "timeMs"
+      }
+    }
+  },
+  "FX_DELAY_FEEDBACK_RANGE": {
+    "kind": "travels",
+    "doc": "The FX delay's REGENERATION travel — how much of the wet tail feeds back in. Stops short of 1: unity feedback is a runaway the kernel hard-clamps anyway, so offering it would draw travel the DSP refuses. Not NORMALIZED_RANGE for exactly that reason — it is a 0..1 quantity whose top the DSP does not accept, and a control must not offer a value its actuator will eat.",
+    "travel": {
+      "min": 0,
+      "max": 0.99,
+      "step": 0,
+      "unit": "",
+      "default": 0.3,
+      "defaultFrom": "desk"
+    }
+  },
+  "DELAY_TONE_RANGE": {
+    "kind": "travels",
+    "doc": "The FX delay's TONE — a NORMALIZED_RANGE instance with its own come-up value, matching `DEFAULT_DELAY_STATE.tone`. See REVERB_SIZE_RANGE for why this is a named constant rather than a default on the shared shape.",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 0.3,
+      "defaultFrom": "desk"
+    }
+  },
+  "DELAY_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The FX DELAY's wet/dry — the same split as REVERB_MIX_RANGE, its own declaration.",
+    "travel": {
+      "min": 0,
+      "max": 1,
+      "step": 0,
+      "unit": "",
+      "default": 0.3,
+      "defaultFrom": "desk",
+      "byKind": {
+        "fxReturn": 1
+      }
+    }
+  },
+  "FX_DELAY_PINGPONG_DEFAULT": {
+    "kind": "scalar",
+    "doc": "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.",
+    "unit": "",
+    "value": false
+  }
+}

package/data/kernels/drive.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "DRIVE_BIAS_MAX": {
+    "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": {
+      "derive": "sqrt",
+      "of": 0.5
+    }
+  }
+}

package/data/kernels/eq.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "EQ_MAX_BANDS": {
+    "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": {
+    "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",
+    "values": [
+      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
+    ],
+    "c": {
+      "render": false
+    }
+  },
+  "GEQ_BANDS": {
+    "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": {
+      "derive": "count",
+      "of": "ISO_THIRD_OCTAVE_CENTRES_HZ"
+    }
+  }
+}

package/data/kernels/flanger.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "FLANGER_RATE_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's jet sweep (§3b).",
+    "travel": {
+      "min": 0.05,
+      "max": 5,
+      "step": 0.01,
+      "unit": "Hz",
+      "default": 0.25,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_DEPTH_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's peak-to-peak excursion above its declared 0.5 ms base (§3b).",
+    "travel": {
+      "min": 0,
+      "max": 5,
+      "step": 0.1,
+      "unit": "ms",
+      "default": 2,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_FEEDBACK_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's SIGNED resonance (§3b). The ±0.95 clamp is DECLARED here — a PATCH asking for 1.0 is answered by this travel — and the kernel's own clamp is the enforcement half.",
+    "travel": {
+      "min": -0.95,
+      "max": 0.95,
+      "step": 0.01,
+      "unit": "",
+      "default": 0.6,
+      "defaultFrom": "desk"
+    }
+  },
+  "FLANGER_MIX_RANGE": {
+    "kind": "travels",
+    "doc": "The flanger's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, equal dry and wet, where the comb is deepest (§3b).",
+    "travel": {
+      "min": 0,
+      "max": 100,
+      "step": 0.1,
+      "unit": "%",
+      "default": 50,
+      "defaultFrom": "desk"
+    }
+  }
+}