@openmixer/omx-contract 2.11.0 → 2.12.0

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

@@ -1,7 +1,97 @@
 {
   "name": "@openmixer/omx-contract",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "items": {
+    "HOSTED_STAGE_LIMITS": {
+      "rel": "data/hosting.json",
+      "kind": "sheet",
+      "doc": "The numbers a hosted plugin's stage limits itself to: the warm-up before it is published, the blocks of non-finite output that strike it, the level its output is clamped at, the parameter queue and the events one block delivers, the polls and timeouts of the hand-over between threads, the ports the core accepts and the caps on a plugin's state, log and parameter count. These are the stage's safety numbers, not an operator's travel.",
+      "docs": {
+        "warmupLevelDbfs": "the level of the warm-up signal, in dBFS",
+        "nonFiniteStrikes": "the blocks of non-finite output that strike a stage",
+        "clampDbfs": "the level the output is clamped at, in dBFS",
+        "paramQueueDepth": "the records the parameter queue holds",
+        "eventsPerBlock": "the parameter events delivered in one block",
+        "unpublishPollUs": "the poll interval while an unpublish waits for the audio thread, in microseconds",
+        "unpublishTimeoutUs": "the longest an unpublish waits for the audio thread, in microseconds",
+        "workerPollUs": "how often an LV2 instance's worker thread polls its request ring, in microseconds",
+        "workerRingBytes": "the bytes of each of an LV2 instance's two worker rings; a power of two, 16 or more",
+        "notesPerBlock": "the note events delivered in one block",
+        "mainPortChannels": "the channels the main port is limited to",
+        "auxOutputs": "the auxiliary output ports the core accepts",
+        "auxInputs": "the auxiliary input ports (side chains) the core accepts",
+        "stateMaxBytes": "the largest plugin state the core saves or loads, in bytes",
+        "logBytes": "the size of a plugin log message, in bytes",
+        "rolePollUs": "the poll interval while the audio role is taken, in microseconds",
+        "roleTimeoutUs": "the longest the audio role is waited for, in microseconds",
+        "paramCountMax": "the widest parameter count the core trusts",
+        "latencyHoldMs": "the hold before a hosted stage's new latency takes effect, in milliseconds"
+      },
+      "value": {
+        "warmupBlocks": 64,
+        "warmupLevelDbfs": -6,
+        "nonFiniteStrikes": 3,
+        "clampDbfs": 24,
+        "paramQueueDepth": 256,
+        "eventsPerBlock": 64,
+        "unpublishPollUs": 100,
+        "unpublishTimeoutUs": 2000000,
+        "workerPollUs": 1000,
+        "workerRingBytes": 16384,
+        "notesPerBlock": 256,
+        "mainPortChannels": 2,
+        "auxOutputs": 8,
+        "auxInputs": 8,
+        "stateMaxBytes": 1048576,
+        "logBytes": 256,
+        "rolePollUs": 1000,
+        "roleTimeoutUs": 200000,
+        "paramCountMax": 2048,
+        "latencyHoldMs": 250
+      }
+    },
+    "HOSTING_CODES": {
+      "rel": "data/hosting.json",
+      "kind": "codes",
+      "doc": "The refusals the CLAP core returns, by the hosting code a verdict names them by. A code is never reworded.",
+      "value": {
+        "headlessFailed": {
+          "code": "hosting.clap.headless-failed"
+        },
+        "notAudioEffect": {
+          "code": "hosting.clap.not-audio-effect",
+          "doc": "the plugin is not an audio effect"
+        },
+        "noteInput": {
+          "code": "hosting.clap.note-input",
+          "doc": "the plugin declares a note input the configuration refuses"
+        },
+        "noAudioInput": {
+          "code": "hosting.topology.no-audio-input",
+          "doc": "the plugin has no audio input"
+        },
+        "noAudioOutput": {
+          "code": "hosting.topology.no-audio-output",
+          "doc": "the plugin has no audio output"
+        },
+        "widerThanStrip": {
+          "code": "hosting.topology.wider-than-strip",
+          "doc": "the plugin is wider than the strip"
+        },
+        "extraInputs": {
+          "code": "hosting.topology.extra-inputs-fed-silence",
+          "doc": "the plugin has extra inputs, fed silence"
+        },
+        "crashedLive": {
+          "code": "hosting.stability.crashed-live-on-this-rig",
+          "doc": "the plugin crashed live on this rig"
+        },
+        "outputNonFinite": {
+          "code": "hosting.output.non-finite",
+          "doc": "the plugin produced non-finite output"
+        }
+      }
+    },
     "PAN_RANGE": {
       "rel": "data/kernels/balance.json",
       "kind": "travels",
@@ -124,7 +214,7 @@
     "CHORUS_SPREAD_RANGE": {
       "rel": "data/kernels/chorus.json",
       "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 ''.",
+      "doc": "The chorus's right-leg phase offset, in TURNS of its one oscillator. 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 ''.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -138,7 +228,7 @@
     "CHORUS_RATE_RANGE": {
       "rel": "data/kernels/chorus.json",
       "kind": "travels",
-      "doc": "The chorus sweep's speed (§3a). Above ~3 Hz it stops being a chorus and becomes a vibrato.",
+      "doc": "The chorus sweep's speed. Above ~3 Hz it stops being a chorus and becomes a vibrato.",
       "shape": "travel",
       "value": {
         "min": 0.05,
@@ -152,7 +242,7 @@
     "CHORUS_DEPTH_RANGE": {
       "rel": "data/kernels/chorus.json",
       "kind": "travels",
-      "doc": "The chorus's peak-to-peak excursion above its declared 10 ms base (§3a).",
+      "doc": "The chorus's peak-to-peak excursion above its declared 10 ms base.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -166,7 +256,7 @@
     "CHORUS_VOICES_RANGE": {
       "rel": "data/kernels/chorus.json",
       "kind": "travels",
-      "doc": "The chorus's tap count — one oscillator read at k/N (§3a).",
+      "doc": "The chorus's tap count — one oscillator read at k/N.",
       "shape": "travel",
       "value": {
         "min": 1,
@@ -180,7 +270,7 @@
     "CHORUS_MIX_RANGE": {
       "rel": "data/kernels/chorus.json",
       "kind": "travels",
-      "doc": "The chorus's wet/dry, as an instance of DRIVE_MIX_RANGE — the same percent travel, its own come-up value: 35 %, a colour under the dry on a strip (§3a). The REVERB_LOWCUT_RANGE-over- REVERB_CUT_RANGE shape: one travel, one declared default per field that reads it.",
+      "doc": "The chorus's wet/dry, as an instance of DRIVE_MIX_RANGE — the same percent travel, its own come-up value: 35 %, a colour under the dry on a strip. The REVERB_LOWCUT_RANGE-over- REVERB_CUT_RANGE shape: one travel, one declared default per field that reads it.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -302,7 +392,7 @@
     "DETECTOR_TOPOLOGY": {
       "rel": "data/kernels/comp.json",
       "kind": "set",
-      "doc": "Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`, the SSL bus compressor design §3a) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.",
+      "doc": "Where the compressor's detector listens: `feedforward` hears the slot's input (or its key), `feedback` hears the slot's own pre-make-up output DYN_FB_LOOP_DELAY_SAMPLES late, through one envelope stage, and a keyed slot stays feed-forward (omx-dsp's OMX_DYN_TOPOLOGY_FEEDFORWARD 0 and _FEEDBACK 1, in that order; the set is named for its control, so C spells them OMX_DETECTOR_TOPOLOGY_*). The console's comp row carries it (`detectorTopology`) and comes up `feedforward`, so a zeroed atom is the compressor every slot runs.",
       "default": "feedforward",
       "value": [
         "feedforward",
@@ -312,7 +402,7 @@
     "PROGRAM_RELEASE": {
       "rel": "data/kernels/comp.json",
       "kind": "sheet",
-      "doc": "The program-dependent release's model constants — the LA-2A's opto cell as DATA (compressor models design §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.",
+      "doc": "The program-dependent release's model constants — the LA-2A's opto cell as DATA. `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,
@@ -392,7 +482,7 @@
     "DEESS_RANGE_RANGE": {
       "rel": "data/kernels/deesser.json",
       "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.",
+      "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). 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.",
       "shape": "travel",
       "value": {
         "min": -24,
@@ -529,7 +619,7 @@
     "FX_DELAY_PINGPONG_DEFAULT": {
       "rel": "data/kernels/delay.json",
       "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 console's delay default state (which now reads it) so the DPF plugin generator (omx-plugins, DPF plugin design §3a) reads the same fact the desk seeds a fresh strip with.",
+      "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 console's delay default state (which now reads it) so the DPF plugin generator (omx-plugins) reads the same fact the desk seeds a fresh strip with.",
       "unit": "",
       "value": false
     },
@@ -658,7 +748,7 @@
     "DRIVE_AUTO_GAINS": {
       "rel": "data/kernels/drive.json",
       "kind": "set",
-      "doc": "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.",
+      "doc": "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`), 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.",
       "default": "on",
       "labels": [
         "Off",
@@ -672,7 +762,7 @@
     "DRIVE_STEREO_LINKS": {
       "rel": "data/kernels/drive.json",
       "kind": "set",
-      "doc": "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.",
+      "doc": "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`). A field of the console's drive row (`DriveState.stereoLink`), on at come-up there and in omx-dsp's drive face.",
       "default": "on",
       "labels": [
         "Off",
@@ -724,7 +814,7 @@
     "DRIVE_BIAS_MAX": {
       "rel": "data/kernels/drive.json",
       "kind": "scalar",
-      "doc": "The bias at `character = +1`, in the SHAPER's own input units — `OMX_DRIVE_BIAS_MAX`. DERIVED, not chosen (§4b). In the saturating limit every knee tends to `sgn`, the output is a rectangular wave of duty `d = ½ + asin(b)/π`, and its `n`th harmonic goes as `sin(nπd)/n` — so `|H2|` is maximal at `d = ¾`, which is `b = sin(π/4) = 1/√2` exactly. Measured too: the H2-maximising bias for a full-scale sine at unity drive is 0.712 (soft), 0.658 (tape), 0.645 (tube), and this one value costs 0.000 / 0.035 / 0.088 dB of H2 against each curve's own optimum. ONE normalised bias for all three knees, not three.",
+      "doc": "The bias at `character = +1`, in the SHAPER's own input units — `OMX_DRIVE_BIAS_MAX`. DERIVED, not chosen. In the saturating limit every knee tends to `sgn`, the output is a rectangular wave of duty `d = ½ + asin(b)/π`, and its `n`th harmonic goes as `sin(nπd)/n` — so `|H2|` is maximal at `d = ¾`, which is `b = sin(π/4) = 1/√2` exactly. Measured too: the H2-maximising bias for a full-scale sine at unity drive is 0.712 (soft), 0.658 (tape), 0.645 (tube), and this one value costs 0.000 / 0.035 / 0.088 dB of H2 against each curve's own optimum. ONE normalised bias for all three knees, not three.",
       "unit": "",
       "value": 0.7071067811865476
     },
@@ -923,7 +1013,7 @@
     "GEQ_BANDS": {
       "rel": "data/kernels/eq.json",
       "kind": "scalar",
-      "doc": "The graphic EQ's section count: DERIVED from ISO_THIRD_OCTAVE_CENTRES_HZ, never a second literal. Generated into `omx_contract_limits.h` as `OMX_GEQ_BANDS`, which sizes `mix_geq.h`'s section array — its OWN budget, never a claimant on EQ_MAX_BANDS (graphic-eq-31 spec §3, roster ruling 3).",
+      "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 (roster ruling 3).",
       "unit": "",
       "value": 31
     },
@@ -1140,7 +1230,7 @@
     "GROWTH_MIN_DB_PER_FRAME": {
       "rel": "data/kernels/fbs.json",
       "kind": "scalar",
-      "doc": "Minimum least-squares slope, in dB PER FRAME, over GROWTH_WINDOW_FRAMES for a bin to count as \"running away\" rather than merely holding level. Set with real margin on BOTH sides — comfortably above measurement jitter on a held tone or a quiet/broadband mix (well under 0.2 dB/frame in practice) and comfortably below a genuine feedback ramp, which climbs several dB across a handful of ~20 ms hops as it heads toward clipping. Issue #91's acceptance bar is \"arming must never burst-alarm on non-growing content\", so this errs conservative (under-fire a marginal ramp) rather than tight (risk a false alarm) — the ramp gate (`omx_fbs_is_growing`) also requires the window's end to sit above its start, a cheap belt-and-braces check against a fit dragged positive by one mid-window wobble.",
+      "doc": "Minimum least-squares slope, in dB PER FRAME, over GROWTH_WINDOW_FRAMES for a bin to count as \"running away\" rather than merely holding level. Set with real margin on BOTH sides — comfortably above measurement jitter on a held tone or a quiet/broadband mix (well under 0.2 dB/frame in practice) and comfortably below a genuine feedback ramp, which climbs several dB across a handful of ~20 ms hops as it heads toward clipping. The acceptance bar is \"arming must never burst-alarm on non-growing content\", so this errs conservative (under-fire a marginal ramp) rather than tight (risk a false alarm) — the ramp gate (`omx_fbs_is_growing`) also requires the window's end to sit above its start, a cheap belt-and-braces check against a fit dragged positive by one mid-window wobble.",
       "unit": "dB",
       "value": 0.8
     },
@@ -1154,21 +1244,21 @@
     "GROWTH_MIN_TOTAL_RISE_DB": {
       "rel": "data/kernels/fbs.json",
       "kind": "scalar",
-      "doc": "Minimum END-TO-END rise (dB) across the window. The live-music corpus (issue #106) showed sustained melody notes drifting up ~4–5 dB over a window without ever being feedback; a loop past unity gains several dB per hop and clears 6 dB in a window trivially. Below this the tone is holding level, not running away.",
+      "doc": "Minimum END-TO-END rise (dB) across the window. The live-music corpus showed sustained melody notes drifting up ~4–5 dB over a window without ever being feedback; a loop past unity gains several dB per hop and clears 6 dB in a window trivially. Below this the tone is holding level, not running away.",
       "unit": "dB",
       "value": 6
     },
     "GROWTH_MAX_SINGLE_FRAME_SHARE": {
       "rel": "data/kernels/fbs.json",
       "kind": "scalar",
-      "doc": "Cap on the share of the window's total rise a SINGLE frame may carry. Feedback is exponential in amplitude ⇒ linear in dB ⇒ its rise is distributed roughly evenly across the window; a musical attack / re-articulation puts almost the whole rise in one hop (the exact shape behind every one of issue #106's 72 live false positives). One half is generous to real ramps (an even N-frame ramp puts 1/(N−1) per hop) and fatal to steps. A side effect worth knowing: a 2-sample window can never pass (one hop IS the whole rise), so confirmation always rests on at least three frames of actual ramp evidence.",
+      "doc": "Cap on the share of the window's total rise a SINGLE frame may carry. Feedback is exponential in amplitude ⇒ linear in dB ⇒ its rise is distributed roughly evenly across the window; a musical attack / re-articulation puts almost the whole rise in one hop (the exact shape behind every one of the 72 live false positives of the live-music corpus). One half is generous to real ramps (an even N-frame ramp puts 1/(N−1) per hop) and fatal to steps. A side effect worth knowing: a 2-sample window can never pass (one hop IS the whole rise), so confirmation always rests on at least three frames of actual ramp evidence.",
       "unit": "",
       "value": 0.5
     },
     "GROWTH_CONFIRM_FRAMES": {
       "rel": "data/kernels/fbs.json",
       "kind": "scalar",
-      "doc": "How many CONSECUTIVE frames the ramp gate (`omx_fbs_is_growing`) must hold before a bin confirms — the time-domain tiebreak for the one shape a single window cannot judge (issue #106): a smooth musical crescendo. Within one window a +6 dB swell (live corpus: a C6 at 1 049 Hz, `[-53.7, -51.4, -50.4, -48, -47.3]`) is indistinguishable from slow feedback — the difference is only visible on the NEXT hop, where a crescendo peaks and plateaus (the window's rise collapses) while feedback keeps climbing. Requiring the gate to hold twice in a row costs a clean ramp nothing — its gate is already true while persistence is still arming — and blocks the swell that peaks the very frame it would have confirmed.",
+      "doc": "How many CONSECUTIVE frames the ramp gate (`omx_fbs_is_growing`) must hold before a bin confirms — the time-domain tiebreak for the one shape a single window cannot judge: a smooth musical crescendo. Within one window a +6 dB swell (live corpus: a C6 at 1 049 Hz, `[-53.7, -51.4, -50.4, -48, -47.3]`) is indistinguishable from slow feedback — the difference is only visible on the NEXT hop, where a crescendo peaks and plateaus (the window's rise collapses) while feedback keeps climbing. Requiring the gate to hold twice in a row costs a clean ramp nothing — its gate is already true while persistence is still arming — and blocks the swell that peaks the very frame it would have confirmed.",
       "unit": "",
       "value": 2
     },
@@ -1193,7 +1283,7 @@
     "FBS_MAX_NOTCH_DEPTH_DB": {
       "rel": "data/kernels/fbs.json",
       "kind": "scalar",
-      "doc": "THE NOTCH DEPTH LAW: the deepest cut any machine planter may propose from one reading, in dB. A number, not a literal at the call site, because two planters now lean on it. FBS derives a candidate's depth from the peak-to-average ratio around its bin and stops here; Room Analysis derives a mode's depth from its height above the median curve and is held to the SAME ceiling (the room-analysis design §4 — \"never more than the FBS notch depth law\"). Written twice as `18` those two bounds would be equal by coincidence and could drift apart in silence. It is a CEILING ON THE PROPOSAL, not the final gain: a band that lands as a rampable BELL is bounded again by `EQ_GAIN_RANGE`, which is tighter. A planter must honour both and REPORT when either bit, never quietly deliver a shallower cut than it was asked for.",
+      "doc": "THE NOTCH DEPTH LAW: the deepest cut any machine planter may propose from one reading, in dB. A number, not a literal at the call site, because two planters now lean on it. FBS derives a candidate's depth from the peak-to-average ratio around its bin and stops here; Room Analysis derives a mode's depth from its height above the median curve and is held to the SAME ceiling (the room-analysis design — \"never more than the FBS notch depth law\"). Written twice as `18` those two bounds would be equal by coincidence and could drift apart in silence. It is a CEILING ON THE PROPOSAL, not the final gain: a band that lands as a rampable BELL is bounded again by `EQ_GAIN_RANGE`, which is tighter. A planter must honour both and REPORT when either bit, never quietly deliver a shallower cut than it was asked for.",
       "unit": "dB",
       "value": 18
     },
@@ -1214,7 +1304,7 @@
     "FLANGER_RATE_RANGE": {
       "rel": "data/kernels/flanger.json",
       "kind": "travels",
-      "doc": "The flanger's jet sweep (§3b).",
+      "doc": "The flanger's jet sweep.",
       "shape": "travel",
       "value": {
         "min": 0.05,
@@ -1228,7 +1318,7 @@
     "FLANGER_DEPTH_RANGE": {
       "rel": "data/kernels/flanger.json",
       "kind": "travels",
-      "doc": "The flanger's peak-to-peak excursion above its declared 0.5 ms base (§3b).",
+      "doc": "The flanger's peak-to-peak excursion above its declared 0.5 ms base.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -1242,7 +1332,7 @@
     "FLANGER_FEEDBACK_RANGE": {
       "rel": "data/kernels/flanger.json",
       "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.",
+      "doc": "The flanger's SIGNED resonance. 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.",
       "shape": "travel",
       "value": {
         "min": -0.95,
@@ -1256,7 +1346,7 @@
     "FLANGER_MIX_RANGE": {
       "rel": "data/kernels/flanger.json",
       "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).",
+      "doc": "The flanger's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, equal dry and wet, where the comb is deepest.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -1414,7 +1504,7 @@
     "GEQ_BAND_RANGE": {
       "rel": "data/kernels/geq.json",
       "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).",
+      "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.",
       "shape": "travel",
       "value": {
         "min": -15,
@@ -1428,21 +1518,21 @@
     "GEQ_BAND_Q": {
       "rel": "data/kernels/geq.json",
       "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).",
+      "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.",
       "unit": "",
       "value": 4.3
     },
     "GEQ_PROTO_DB": {
       "rel": "data/kernels/geq.json",
       "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.",
+      "doc": "The prototype gain the `true` solve's first interaction matrix is evaluated at: 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": {
       "rel": "data/kernels/geq.json",
       "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.",
+      "doc": "The ceiling on a section gain the `true` solve may ask for: 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
     },
@@ -1484,35 +1574,35 @@
     "HRP_EXCESS_THRESHOLD_DB": {
       "rel": "data/kernels/hrp.json",
       "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.)",
+      "doc": "How far a partial must stand above its LEARNED BASELINE before HRP calls it a resonance (increment 8: `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": {
       "rel": "data/kernels/hrp.json",
       "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.",
+      "doc": "How far ONE reconcile pass may move an HRP band's gain, in dB — the gain smoothing, done at the control level because the native cascade applies pushed coefficients verbatim and the design 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": {
       "rel": "data/kernels/hrp.json",
       "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.",
+      "doc": "How close two correction candidates must sit, in cents, to count as the SAME spectral region: 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 design makes the threshold configurable and tested: declared once here, a parameter everywhere below.",
       "unit": "cents",
       "value": 100
     },
     "HRP_ATTRIBUTION_CENTS": {
       "rel": "data/kernels/hrp.json",
       "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.",
+      "doc": "The ATTRIBUTION window: 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 (the 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": {
       "rel": "data/kernels/hrp.json",
       "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. the engine's conformance test 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.",
+      "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 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 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. the engine's conformance test 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
     },
@@ -1551,14 +1641,14 @@
     "BUS_INPUT_CAP": {
       "rel": "data/kernels/mixmatrix.json",
       "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. the engine's conformance test holds this to the C header; the console allocation design §9 carries the ruling and the measured cost of width.",
+      "doc": "The input cap a summing bus can be sized to — **the engine's declared input ceiling**, read from the engine's 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. the engine's conformance test holds this to the C header; the console allocation design carries the ruling and the measured cost of width.",
       "unit": "",
       "value": 128
     },
     "PHASER_RATE_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The phaser's sweep speed (§3). `omx_lfo_inc` freezes at Nyquist; this travel stays far below.",
+      "doc": "The phaser's sweep speed. `omx_lfo_inc` freezes at Nyquist; this travel stays far below.",
       "shape": "travel",
       "value": {
         "min": 0.05,
@@ -1572,7 +1662,7 @@
     "PHASER_BASE_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The phaser's lowest centre frequency; the sweep runs upward from it (§3).",
+      "doc": "The phaser's lowest centre frequency; the sweep runs upward from it.",
       "shape": "travel",
       "value": {
         "min": 50,
@@ -1586,7 +1676,7 @@
     "PHASER_DEPTH_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The sweep's span above `base`, in octaves; 0 is a static phaser at `base` (§3).",
+      "doc": "The sweep's span above `base`, in octaves; 0 is a static phaser at `base`.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -1600,7 +1690,7 @@
     "PHASER_STAGES_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The phaser's section count per leg — EVEN, 2 … 12 (§2: two sections per notch). Its ends are the kernel's state capacity (`OMX_PHASER_MAX_STAGES` reads `OMX_PHASER_STAGES_RANGE_MAX`); the row moves it through the closed member set PHASER_STAGE_COUNTS, which is derived from it.",
+      "doc": "The phaser's section count per leg — EVEN, 2 … 12 (two sections per notch). Its ends are the kernel's state capacity (`OMX_PHASER_MAX_STAGES` reads `OMX_PHASER_STAGES_RANGE_MAX`); the row moves it through the closed member set PHASER_STAGE_COUNTS, which is derived from it.",
       "shape": "travel",
       "value": {
         "min": 2,
@@ -1614,7 +1704,7 @@
     "PHASER_FEEDBACK_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "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.",
+      "doc": "The phaser's SIGNED resonance. ±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.",
       "shape": "travel",
       "value": {
         "min": -0.9,
@@ -1628,7 +1718,7 @@
     "PHASER_MIX_RANGE": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The phaser's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, where the notch is complete (§3).",
+      "doc": "The phaser's wet/dry, as an instance of DRIVE_MIX_RANGE: 50 %, where the notch is complete.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -1642,7 +1732,7 @@
     "PHASER_TRAVELS": {
       "rel": "data/kernels/phaser.json",
       "kind": "travels",
-      "doc": "The phaser's continuous travels by row field — the ONE map its control bounds and its row travels both read (§3). `stages` is not here: it moves through PHASER_STAGE_COUNTS.",
+      "doc": "The phaser's continuous travels by row field — the ONE map its control bounds and its row travels both read. `stages` is not here: it moves through PHASER_STAGE_COUNTS.",
       "shape": "table",
       "value": {
         "rateHz": {
@@ -1717,17 +1807,26 @@
         "semitones": {
           "min": -12,
           "max": 12,
-          "default": 0
+          "step": 1,
+          "unit": "st",
+          "default": 0,
+          "defaultFrom": "desk"
         },
         "cents": {
           "min": -50,
           "max": 50,
-          "default": 0
+          "step": 1,
+          "unit": "cents",
+          "default": 0,
+          "defaultFrom": "desk"
         },
         "mix": {
           "min": 0,
           "max": 100,
-          "default": 100
+          "step": 0.1,
+          "unit": "%",
+          "default": 100,
+          "defaultFrom": "desk"
         }
       }
     },
@@ -2018,7 +2117,7 @@
     "ROTARY_MIX_RANGE": {
       "rel": "data/kernels/rotary.json",
       "kind": "travels",
-      "doc": "The rotary's wet/dry, as an instance of DRIVE_MIX_RANGE: 100 %, because a rotary on an insert IS the sound (it replaces the cabinet) and an `fxReturn` wants it wet too (§3).",
+      "doc": "The rotary's wet/dry, as an instance of DRIVE_MIX_RANGE: 100 %, because a rotary on an insert IS the sound (it replaces the cabinet) and an `fxReturn` wants it wet too.",
       "shape": "travel",
       "value": {
         "min": 0,
@@ -2232,7 +2331,7 @@
     "TRANSIENT_LIMITS": {
       "rel": "data/kernels/transient.json",
       "kind": "travels",
-      "doc": "The legal range of each transient-designer field (engineering units), transient spec §3. Every kind comes up flat: no per-kind default differs. the engine's limits generator emits each as `OMX_TRANSIENT_<FIELD>_{MIN,MAX,DEFAULT}` for `mix_transient.h`'s resolve; the row publishes them on OPTIONS when it lands (issue #921).",
+      "doc": "The legal range of each transient-designer field (engineering units). Every kind comes up flat: no per-kind default differs. the engine's limits generator emits each as `OMX_TRANSIENT_<FIELD>_{MIN,MAX,DEFAULT}` for `mix_transient.h`'s resolve; the row publishes them on OPTIONS when it lands.",
       "shape": "table",
       "value": {
         "attackDb": {
@@ -2280,28 +2379,28 @@
     "TRANSIENT_FAST_ATTACK_MS": {
       "rel": "data/kernels/transient.json",
       "kind": "scalar",
-      "doc": "The fast follower's attack, ms: exactly the dynamics detector's no-oversampling line (transient spec §3, L7).",
+      "doc": "The fast follower's attack, ms: exactly the dynamics detector's no-oversampling line.",
       "unit": "ms",
       "value": 0.5
     },
     "TRANSIENT_FAST_RELEASE_MS": {
       "rel": "data/kernels/transient.json",
       "kind": "scalar",
-      "doc": "The fast follower's release, ms: one 50 Hz cycle held, a 180 bpm sixteenth forgotten (transient spec §3).",
+      "doc": "The fast follower's release, ms: one 50 Hz cycle held, a 180 bpm sixteenth forgotten.",
       "unit": "ms",
       "value": 20
     },
     "TRANSIENT_REF_DB": {
       "rel": "data/kernels/transient.json",
       "kind": "scalar",
-      "doc": "The contrast, dB, at which a knob reaches its full value (transient spec §2, §3).",
+      "doc": "The contrast, dB, at which a knob reaches its full value.",
       "unit": "dB",
       "value": 6
     },
     "TRANSIENT_FLOOR_LIN": {
       "rel": "data/kernels/transient.json",
       "kind": "scalar",
-      "doc": "The detector floor, linear (−100 dBFS): below it both envelopes read the floor and the stage is unity (transient spec §3).",
+      "doc": "The detector floor, linear (−100 dBFS): below it both envelopes read the floor and the stage is unity.",
       "unit": "",
       "value": 0.00001
     },
@@ -2447,7 +2546,7 @@
     "FDELAY_MOD_READ_ORDER": {
       "rel": "data/primitives.json",
       "kind": "scalar",
-      "doc": "The order the chorus and flanger construct their lines with (four taps; the fdelay spec §1).",
+      "doc": "The order the chorus and flanger construct their lines with (four taps).",
       "unit": "",
       "value": 3
     },