@openmixer/omx-contract 1.2.1 → 2.0.0

package/data/kernels/flanger.json

@@ -1,51 +1,81 @@
 {
   "$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"
+  "controls": [
+    {
+      "name": "rate",
+      "kind": "travel",
+      "doc": "The flanger's jet sweep (§3b).",
+      "travel": {
+        "min": 0.05,
+        "max": 5,
+        "step": 0.01,
+        "unit": "Hz",
+        "default": 0.25,
+        "defaultFrom": "desk"
+      }
+    },
+    {
+      "name": "depth",
+      "kind": "travel",
+      "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"
+      }
+    },
+    {
+      "name": "feedback",
+      "kind": "travel",
+      "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"
+      }
+    },
+    {
+      "name": "mix",
+      "kind": "travel",
+      "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"
+      }
     }
-  },
-  "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,
+  ],
+  "constants": {
+    "FLANGER_BASE_MS": {
+      "kind": "scalar",
+      "doc": "The flanger's base delay, ms: the sweep rides on it up to the depth.",
       "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"
+      "value": 0.5
+    },
+    "FLANGER_MAX_MS": {
+      "kind": "scalar",
+      "doc": "The longest delay a flanger sweep reaches, rounded up to whole ms: the base delay plus the depth maximum. The delay line is sized from it.",
+      "unit": "ms",
+      "value": {
+        "derive": "ceilSum",
+        "of": [
+          {
+            "ref": "FLANGER_BASE_MS"
+          },
+          {
+            "ref": "FLANGER_DEPTH_RANGE.max"
+          }
+        ]
+      }
     }
   }
 }

package/data/kernels/gate.json

@@ -1,74 +1,124 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "GATE_LIMITS": {
-    "kind": "travels",
-    "doc": "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).",
-    "fields": {
-      "thresholdDb": {
+  "controls": [
+    {
+      "name": "keySource",
+      "kind": "choice",
+      "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.",
+      "ids": [
+        "self",
+        "sidechain"
+      ]
+    },
+    {
+      "name": "thresholdDb",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": -80,
         "max": 0,
         "step": 1,
         "unit": "dB",
         "default": -40,
         "defaultFrom": "desk"
-      },
-      "rangeDb": {
+      }
+    },
+    {
+      "name": "rangeDb",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": -90,
         "max": 0,
         "step": 1,
         "unit": "dB",
         "default": -90,
         "defaultFrom": "desk"
-      },
-      "kneeStartDb": {
+      }
+    },
+    {
+      "name": "kneeStartDb",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": -80,
         "max": 0,
         "step": 1,
         "unit": "dB",
         "default": -43,
         "defaultFrom": "desk"
-      },
-      "kneeEndDb": {
+      }
+    },
+    {
+      "name": "kneeEndDb",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": -80,
         "max": 0,
         "step": 1,
         "unit": "dB",
         "default": -37,
         "defaultFrom": "desk"
-      },
-      "attackMs": {
+      }
+    },
+    {
+      "name": "attackMs",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": 0,
         "max": 500,
         "step": 0.5,
         "unit": "ms",
         "default": 1,
         "defaultFrom": "desk"
-      },
-      "holdMs": {
+      }
+    },
+    {
+      "name": "holdMs",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": 0,
         "max": 2000,
         "step": 5,
         "unit": "ms",
         "default": 10,
         "defaultFrom": "desk"
-      },
-      "releaseMs": {
+      }
+    },
+    {
+      "name": "releaseMs",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": 0,
         "max": 5000,
         "step": 10,
         "unit": "ms",
         "default": 100,
         "defaultFrom": "desk"
-      },
-      "hysteresisDb": {
+      }
+    },
+    {
+      "name": "hysteresisDb",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": 0,
         "max": 24,
         "step": 0.5,
         "unit": "dB",
         "default": 3,
         "defaultFrom": "desk"
-      },
-      "ratio": {
+      }
+    },
+    {
+      "name": "ratio",
+      "kind": "travel",
+      "table": "GATE_LIMITS",
+      "travel": {
         "min": 1,
         "max": 100,
         "step": 1,
@@ -77,5 +127,10 @@
         "defaultFrom": "desk"
       }
     }
+  ],
+  "tables": {
+    "GATE_LIMITS": {
+      "doc": "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)."
+    }
   }
 }

package/data/kernels/geq.json

@@ -1,33 +1,38 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "GEQ_BAND_RANGE": {
-    "kind": "travels",
-    "doc": "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).",
-    "travel": {
-      "min": -15,
-      "max": 15,
-      "step": 0.5,
+  "controls": [
+    {
+      "name": "band",
+      "kind": "travel",
+      "doc": "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).",
+      "travel": {
+        "min": -15,
+        "max": 15,
+        "step": 0.5,
+        "unit": "dB",
+        "default": 0,
+        "defaultFrom": "desk"
+      }
+    }
+  ],
+  "constants": {
+    "GEQ_BAND_Q": {
+      "kind": "scalar",
+      "doc": "The graphic EQ's band Q: the ISO third-octave bandwidth, `2^(1/6)/(2^(1/3) − 1) ≈ 4.318`, to one decimal as the M32 GEQ carries it. Read by the `geq31` preset and the graphic EQ's section design (graphic-eq-31 spec §3).",
+      "unit": "",
+      "value": 4.3
+    },
+    "GEQ_PROTO_DB": {
+      "kind": "scalar",
+      "doc": "The prototype gain the `true` solve's first interaction matrix is evaluated at (spec §2, §3): the middle of the travel's magnitude, where a matched-Z section's dB response per dB of gain is closest to its average.",
+      "unit": "dB",
+      "value": 12
+    },
+    "GEQ_DESIGN_GAIN_MAX_DB": {
+      "kind": "scalar",
+      "doc": "The ceiling on a section gain the `true` solve may ask for (spec §3): above the travel's worst case (26.0 dB, the alternating ±15 set) with margin. A solve past it clamps and the row says so (`designClamped`), never silently.",
       "unit": "dB",
-      "default": 0,
-      "defaultFrom": "desk"
+      "value": 30
     }
-  },
-  "GEQ_BAND_Q": {
-    "kind": "scalar",
-    "doc": "The graphic EQ's band Q: the ISO third-octave bandwidth, `2^(1/6)/(2^(1/3) − 1) ≈ 4.318`, to one decimal as the M32 GEQ carries it. Read by the `geq31` preset and the graphic EQ's section design (graphic-eq-31 spec §3).",
-    "unit": "",
-    "value": 4.3
-  },
-  "GEQ_PROTO_DB": {
-    "kind": "scalar",
-    "doc": "The prototype gain the `true` solve's first interaction matrix is evaluated at (spec §2, §3): the middle of the travel's magnitude, where a matched-Z section's dB response per dB of gain is closest to its average.",
-    "unit": "dB",
-    "value": 12
-  },
-  "GEQ_DESIGN_GAIN_MAX_DB": {
-    "kind": "scalar",
-    "doc": "The ceiling on a section gain the `true` solve may ask for (spec §3): above the travel's worst case (26.0 dB, the alternating ±15 set) with margin. A solve past it clamps and the row says so (`designClamped`), never silently.",
-    "unit": "dB",
-    "value": 30
   }
 }

package/data/kernels/hrp.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "controls": [
+    {
+      "name": "amount",
+      "kind": "travel",
+      "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.",
+      "travel": {
+        "min": 0,
+        "max": 1,
+        "step": 0,
+        "unit": "",
+        "default": 0.5,
+        "defaultFrom": "desk"
+      }
+    }
+  ],
+  "constants": {
+    "HRP_MAX_CUT_DB": {
+      "kind": "scalar",
+      "doc": "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.",
+      "unit": "dB",
+      "value": 6
+    },
+    "HRP_MAX_VOICES": {
+      "kind": "scalar",
+      "doc": "How many simultaneous musical voices the detector may report on one channel. PINNED to `OMX_HRP_MAX_VOICES` in `pipewire-native/src/hrp_pitch.h` — the C voice set is a FIXED-SIZE array, so a TS number above the macro promises voices the analyser structurally cannot return, and one below it silently drops notes the C already found. `core/src/output-delay-ceiling.test.ts` reads the header and holds the pair equal. EIGHT (operator sizing, 2026-09-01): a guitar sounds six strings, a piano or string-section voicing sits at eight. It is a SEARCH ceiling, not a cost — the detector abandons a round as soon as no credible candidate remains, so monophonic material costs what it always did.",
+      "unit": "",
+      "value": 8
+    },
+    "HRP_BAND_Q": {
+      "kind": "scalar",
+      "doc": "The Q of an HRP correction band — one declared number, operator-adjustable later. A musical cut, not a ring killer: FBS's default notch Q is ~116 because a howl is a single frequency, whereas a partial that is too loud is a note an instrument is playing and a surgical null on it would be heard as a hole. 5 sits mid-band in the 4…6 range a musical subtractive cut occupies, and inside EQ_Q_RANGE — the gain-carrying shapes' extent — so it survives the store's clamp unchanged. Deliberately NOT derived from the harmonic index. A derivation invented with no measurement behind it is a second declaration wearing a formula; this is revisited when the analyse-only surface shows what real corrections look like.",
+      "unit": "",
+      "value": 5
+    },
+    "HRP_EXCESS_THRESHOLD_DB": {
+      "kind": "scalar",
+      "doc": "How far a partial must stand above its LEARNED BASELINE before HRP calls it a resonance (increment 8, §23–§24: `deviation = measured − baseline[note][harmonic]`). A partial level tells you nothing on its own; what marks a resonance is a partial louder than THIS instrument normally measures at THIS note. Three decibels is the same order as the feedback detector's peak-to-neighbour gate and for the same reason: below it, an ordinary performance's variation — a bow dug in, a verse sung harder — would be flattened, and flattening expression is not correcting a room. (Before the learned model existed this same threshold gated the placeholder neighbour rule; the number and its reasoning carried over.)",
+      "unit": "dB",
+      "value": 3
+    },
+    "HRP_GAIN_STEP_DB": {
+      "kind": "scalar",
+      "doc": "How far ONE reconcile pass may move an HRP band's gain, in dB — §48's gain smoothing, done at the control level because the native cascade applies pushed coefficients verbatim and §48 forbids interpolating there. An unbounded gain step is a waveform discontinuity — the click heard when a correction entered or left at full depth (found live, 2026-08-20, the evening increment 9 raised the enter/leave rate). Bounded, a correction ENTERS by deepening from silence and LEAVES by walking to exactly 0 dB — the provable parked identity (`eqBandIsIdentity`) — from which removal is bit-identical. Two decibels per pass at the corrector's 10 Hz cadence walks the full HRP_MAX_CUT_DB travel in ~300 ms: the same order as the tracker's stability hold and FBS's lift steps, while each individual move stays below audibility on a Q-5 bell.",
+      "unit": "dB",
+      "value": 2
+    },
+    "HRP_COLLISION_CENTS": {
+      "kind": "scalar",
+      "doc": "How close two correction candidates must sit, in cents, to count as the SAME spectral region (§30): within it, the stronger candidate is selected and the weaker discarded rather than two near-identical filters being planted. One semitone, and the number follows from HRP_BAND_Q: a Q-5 bell's −3 dB half-width is ~170 cents, so two cuts a semitone apart overlap over most of their travel — the second one deepens the first far more than it shapes anything of its own. The spec orders the threshold configurable and tested (§30's last line): declared once here, a parameter everywhere below.",
+      "unit": "cents",
+      "value": 100
+    },
+    "HRP_ATTRIBUTION_CENTS": {
+      "kind": "scalar",
+      "doc": "The ATTRIBUTION window (§11): two partials closer than this are one spectral event as far as the desk can tell — the same ±1 bin `omx_hrp_bin_peak` reads over, expressed musically so it holds across the range. A different law from HRP_COLLISION_CENTS (§30's SELECTION window, which stays above it): this one is the analyser's resolution, that one the corrector's. Generated into `omx_contract_limits.h` as `OMX_HRP_ATTRIBUTION_CENTS`; `hrp_attribute.h` reads it.",
+      "unit": "cents",
+      "value": 60
+    },
+    "HRP_DEFAULT_MAX_AUTO_BANDS": {
+      "kind": "scalar",
+      "doc": "How many bands HRP may plant on ONE channel — its half of the machine budget, and the number that makes the budget FORECASTABLE rather than emergent. Without it the count is whatever the material happens to provoke: the placement law is sparse, so a clean note plants two bands and a resonant room plants nine, and nobody can answer \"will this fit?\" until it does not. With FBS senior (§9.3(b)) that discovery would happen at showtime, to the junior planter, silently. Declared instead, the whole sum is arithmetic an operator can read before a note is played: operator bands + FBS maxAutoBands + HRP maxAutoBands <= EQ_MAX_BANDS EIGHT — ONE CORRECTION PER VOICE at full polyphony (operator sizing, 2026-09-01). The detector's ceiling is HRP_MAX_VOICES voices, a guitar's six strings and a piano/string voicing's eight, and a budget below the voice count would decide by arithmetic which of the notes actually sounding may be corrected — a limit nobody could read off the desk. Scarcity is handled where it belongs instead: the candidates from every voice meet in ONE globally ranked list (spec §29) and the head of it is what gets planted. It is NOT a claim to seniority, and it is larger than FBS's six. Seniority is the ALLOCATION ORDER — `HrpPlanter` takes only `EQ_MAX_BANDS − others.length`, the remainder after the operator and every other machine — so a bigger junior default cannot reach a senior slot; it only means HRP asks for more of what is left. `eq-budget-fits.test.ts` asserts both halves. The per-channel DEFAULT; the row's travel is HRP_AUTO_BANDS_RANGE, so a channel that needs more can have more, as an explicit decision with a visible cost.",
+      "unit": "",
+      "value": 8
+    }
+  }
+}

package/data/kernels/limiter.json

@@ -1,26 +1,37 @@
 {
   "$schema": "../../schema/omx-contract.schema.json",
-  "LIMITER_LIMITS": {
-    "kind": "travels",
-    "doc": "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.",
-    "fields": {
-      "ceilingDb": {
+  "controls": [
+    {
+      "name": "ceilingDb",
+      "kind": "travel",
+      "table": "LIMITER_LIMITS",
+      "travel": {
         "min": -12,
         "max": 0,
         "step": 0.1,
         "unit": "dBFS",
         "default": -1,
         "defaultFrom": "desk"
-      },
-      "lookaheadMs": {
+      }
+    },
+    {
+      "name": "lookaheadMs",
+      "kind": "travel",
+      "table": "LIMITER_LIMITS",
+      "travel": {
         "min": 0.5,
         "max": 5,
         "step": 0.1,
         "unit": "ms",
         "default": 1.5,
         "defaultFrom": "desk"
-      },
-      "releaseMs": {
+      }
+    },
+    {
+      "name": "releaseMs",
+      "kind": "travel",
+      "table": "LIMITER_LIMITS",
+      "travel": {
         "min": 1,
         "max": 1000,
         "step": 1,
@@ -29,5 +40,10 @@
         "defaultFrom": "desk"
       }
     }
+  ],
+  "tables": {
+    "LIMITER_LIMITS": {
+      "doc": "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."
+    }
   }
 }

package/data/kernels/mixmatrix.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "../../schema/omx-contract.schema.json",
+  "constants": {
+    "BUS_INPUT_CAP": {
+      "kind": "scalar",
+      "doc": "The input cap a summing bus can be sized to — **the engine's declared input ceiling**, read from `@freemixer/declarations` rather than re-typed here. A gig with more than this many inputs needs more than one engine node; below it a bus is sized to `min(N, BUS_INPUT_CAP)`. It was a literal 64 until 2026-09-15, said to mirror the engine's `MAX_BUS_INPUTS` — and it did, but that 64 was the PipeWire builtin mixer's single-tier fan-in (8 × 8), never the engine's bound: the native node has allocated `OMX_MAX_STRIPS` (128) strips all along. Two literals agreeing by hand is how the console came to refuse a 96-channel desk it could carry. `native-input-ceiling.test.ts` holds this to the C header; spec `docs/design/specs/2026-09-14-console-allocation.md` §9 carries the ruling and the measured cost of width.",
+      "unit": "",
+      "value": 128
+    }
+  }
+}