daniel/reasampler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: close Γ-F7 to signal-flow order and spec real units at the host boundary

Browse Source 
The 44-id table stated in full. Adds the plain-value layer, a per-category
unit/precision table, the one-formatter invariant, a stepCount sweep, and the
filter read-side resolution.
This commit is contained in:
Daniel Harvey
2026-08-01 18:18:09 -04:00
parent 9f17df1420
commit 0a7778b396
3 changed files with 556 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/instrument-control-surface.md
+46 -18
View File
@@ -60,8 +60,12 @@ own width formula, not carried over from a prior measurement. The stale geometry
- **VST3 automation parameters SHIP IN THIS PHASE, as its last track** (Ruling 1, Daniel
2026-08-01). The specification is `docs/product/parameter-automation.md` §§6–10: 44
exposed parameters derived from the three-state commit predicate, a hand-assigned
FOREVER-FROZEN id table in blocks of 100 with steps of 10, and the blob left
authoritative with parameters as a third surface onto the one model.
FOREVER-FROZEN id table in blocks of 100 with steps of 10 **in signal-flow order**
(Γ-F7, ruled), and the blob left authoritative with parameters as a third surface onto the
one model. **They report REAL UNITS to the host** (Ruling 3) through VST3's plain-value
layer — a plain range, a unit string and a stated display precision per parameter, formatted
by the same pure function the knob label uses. §6.7 there; §8.4 here for what it binds in
this doc.
- **The stage-time ceiling moves 2 s → 10 s, in wave 1** (Daniel, reversing Γ-F3),
*because* parameters now ship in-phase — a range endpoint is host-facing normalization,
free to move now and permanently expensive afterwards. Its real cost is not the constant
@@ -783,6 +787,13 @@ model"* — a snap available on one and not the others would be a divergence.
| **decibels** | master gain | whole **dB** |
| **already integer** | voice count, preview velocity | no change |
> **This table is a DRAG rule and must never become `ParameterInfo::stepCount`** (Ruling 3,
> §8.4). `stepCount` quantizes the parameter itself — permanently, and for the host's
> automation too — which would put continuous cents out of reach from a lane and freeze the
> grid into the forever contract. The two axes are already visibly independent here: filter
> cutoff *displays* in Hz, *snaps* in whole percent of its normalized position, and is
> *automated* continuously. All 44 exposed parameters ship `stepCount = 0`.
### 4.3 The tapers
**Both taper changes are SAFE for persistence and require no format bump.** The
@@ -1352,7 +1363,7 @@ shape is deliberate and its reasoning is documented at the call site.
---
## 8. Forks — six ruled (one later reversed), one open
## 8. Forks — SEVEN ruled (one later reversed), NONE open
### 8.1 Ruled by Daniel, 2026-08-01
@@ -1369,6 +1380,7 @@ ceiling.
| **Γ-F4** | Explicit loop enable? | **Yes — on the CHROME ROW.** Not a deck cell; loop is a waveform-overlay concept and has no deck. | **§6.4** (new), §6.5, §7.9 |
| **Γ-F5** | MASTER's reserved slot: one cell or two? | **One cell.** Two would spend 60 of the 90 px headroom on an unnamed control and freeze row 1 forever. | **§1.6** (new), §1.4 |
| **Γ-F6** | Is the `kLatencyChanged` deactivate/reactivate acceptable as the cost of the toggle? | **Yes — ship dynamic latency as ruled.** No constant-latency fallback, no measurement gate. *Corrected this doc's analysis: the cost is self-inflicted, not SDK-imposed.* | **§3.1.1** (rewritten), §7.10, §7.11, `docs/TODO.md` |
| **Γ-F7** | VST3 parameter ORDER: signal flow, or the editor's visual rows? | **Signal flow** — *"signal flow order."* The frozen id numbering and the presentation index both follow the deck's own rule; the visual layout is too mobile to freeze against. | **§8.3**; `parameter-automation.md` §6.4 (argument) and §6.2 (the 44-id table) |
Three of these corrected this doc rather than confirming it, and all three corrections are
worth remembering as pattern:
@@ -1425,27 +1437,43 @@ than just counting:
`restartComponent`), not about this flag.
5. **The reduction is filed**, with a trigger condition, in `docs/TODO.md`.
### 8.3 Γ-F7 — OPEN. The parameter order
### 8.3 Γ-F7 — RULED: signal flow. The parameter order
**Opened 2026-08-01 by Ruling 1** (*"Make the parameter order logical"*), because "logical"
resolves two ways and the choice is frozen forever the day parameters ship.
resolved two ways and the choice freezes forever the day parameters ship. **Closed the same
day by Daniel: *"signal flow order."***
> **Signal-flow order** — PITCH/RATE → PITCH ENV → FILTER → FILTER ENV → AMP → VELOCITY →
> VOICE → MASTER, the deck's own documented ordering rule, layout-independent.
> **OR the editor's visual row order** after the Γ-W3 reflow — row 1 then row 2 then MASTER,
> matching what the user's eye scans.
> **PITCH/RATE → PITCH ENV → FILTER → FILTER ENV → AMP → VELOCITY → VOICE → MASTER**, the
> deck's own documented ordering rule, layout-independent. Both the frozen id numbering and
> the `getParameterInfo` presentation index follow it; each group's cells take the semantic
> order the id table freezes.
Same membership, different sequence; the recommendation, both arguments, and why the
grouping (`IUnitInfo`, one unit per deck group) is settled either way are in
`docs/product/parameter-automation.md` §6.4. **Recommendation: signal flow**, because the
visual layout has moved twice already and this phase moves it again, and freezing a forever
identity to a thing that moves is the wrong coupling.
**The rejected alternative** was the editor's visual row order after the Γ-W3 reflow — row 1,
then row 2, then MASTER, matching what the user's eye scans. **The reason it lost, recorded
because a reader will ask why the numbering does not match the screen:** the editor's layout
has already moved twice and this phase moves it again, and within-row order is settled by
width fitting rather than by meaning — so binding a permanently-frozen id order to a
demonstrably mobile layout guarantees the two drift apart, after which the order is neither
logical nor matching. Signal flow is the axis that does not move.
**Urgency: low, but not zero.** Three waves sit in front of Γ-W4-T1 and nothing before it
depends on the answer. It must close **before Γ-W4 dispatches**, and it cannot be closed by
proposal at review — a forever commitment is a Daniel call.
The full argument, the accepted residual cost (a user scanning REAPER's flat list), and the
resulting 44-id table are in `docs/product/parameter-automation.md` §6.4 and §6.2.
*Every other fork in this phase is ruled. Nothing in §§1–7 awaits a Daniel answer.*
*Every fork in this phase is now ruled, and nothing in this doc awaits a Daniel answer.*
### 8.4 Ruling 3 — real units at the host boundary
**Daniel, 2026-08-01:** *"The parameter values exposed to the VST host should be in real
units, such that the host automation lanes report usable values."* Not a fork — it arrived as
a requirement and is specified rather than decided. It lands entirely in Γ-W4-T1 and moves no
wave boundary.
It reaches back into this doc in exactly one place: **§4's interaction law and §4.2's
snap-unit table are DRAG rules and must never become `ParameterInfo::stepCount`.** Snapped
drag and parameter continuity are independent axes — this doc's own table already proves it,
since filter cutoff displays in Hz, snaps in whole percent of normalized position, and is
automated continuously. Full spec, including the unit/precision table, the one-formatter
invariant and the `stepCount` sweep: `docs/product/parameter-automation.md` §6.7.
---