Phase 16: persist sample-timed effect automation and add expressive MIDI controls

docs/CONTROL.md

@@ -0,0 +1,49 @@
+# Automation and expressive control (Phase 16)
+
+Track Gain/Pan lanes in the Mixer apply to audio and scheduled instrument voices.
+They use absolute project ticks, linear interpolation, hold-first/last outside
+points and the constant project tempo snapshot. A clip trim/move does not move
+track or effect automation: lanes belong to the project timeline. Instrument
+volume is controlled by its track Gain lane; the current sine has no timbre
+parameter. Track gain ramps and boundary fades are described in AUDIO_QUALITY.md.
+
+Select a LADSPA node in Modular Graph and use Edit/Selected plugin automation.
+Enter `port tick mode value`: mode 0 interpolates linearly, 1 holds until the next
+point, and -1 removes the point at that port/tick (value ignored). Port names,
+ranges and current tick are displayed. There are at most 32 points per plugin;
+setting an existing port/tick replaces it. Integer/toggle controls require step
+mode. Invalid values, ticks, ports or duplicate persisted points reject the edit
+or file. Edits are undoable and rebuild on the control thread while stopped.
+
+Effect lanes use the project tempo, hold first/last outside their range and
+apply before run at each exact sample. Distinct ticks rounding to one sample
+resolve to the later tick. Linear curves avoid stepping continuous controls;
+intentional step curves may click. The initial implementation calls run(1) while
+any lane exists, with connected preallocated buffers. CPU cost can be significant;
+only the documented LADSPA set is qualified. No worker, allocator, loader or
+clock is called from the host audio path. Native ABI 2 callers continue to use
+sample-offset parameter events, applied before equal-offset MIDI events.
+
+Live MIDI input maps CC7 to per-channel volume (0..1), CC10 to pan (64 center),
+and CC64 to sustain (>=64 down). Volume/pan ramp over 5 ms. These fixed mappings
+apply to live sine voices, not track faders or prerecorded clips; controller
+capture, configurable learn and plugin MIDI are not supported. CC120/123 and
+Panic release all live voices and sustain and suppress already-started scheduled
+notes. Note-on velocity zero decodes to note-off. Repeated live note-on on one
+channel/pitch retriggers one voice; note-off releases it or marks it pending while
+sustain is held. Sustain-up releases pending voices, never newer retriggers.
+Seek, stop, teardown and disconnect clear live voices; plan reset returns controller
+values to unity/center. Equal-offset live events execute in input order before
+the sample; arrange note ends precede starts, and scheduled mixer values are
+evaluated at that sample. Overlapping arranged notes are independent.
+
+Format v6 preserves v5 data plus effect lanes. A v5 plugin migrates with no lane
+and the project tempo. Repeated render/save/reopen, odd block partition, exact
+endpoints, seek/plan replacement, sustain/retrigger and controller ramp tests:
+
+```sh
+make test test-control test-plugins test-gui-plugins test-plugins-real
+```
+
+Physical controller devices and listening remain unqualified; no tempo map,
+latency compensation, MIDI capture, pitch bend or plugin crash isolation is added.

docs/PROJECT_FORMAT.md

@@ -138,3 +138,13 @@ the module. Unknown nodes/versions fail without mutating the current project.
 Missing modules remain preserved by metadata load/save; GUI installation rejects
 them with a repair message. No transient DSP state, pointer or plugin binary is
 stored. See PLUGIN_HOSTING.md and decision 0009 for supported processors/limits.
+
+## Phase 16: version 6
+
+Writer emits v6 and readers accept v1–v6. After each plugin's CONTROL records,
+`PLUGIN_AUTOMATION count` is followed by exactly count (<=32) records:
+`PARAM tick port mode float32_hex_bits`. Mode is 0 linear or 1 step. Duplicate
+port/tick pairs, nonfinite values, unknown control ports and ticks beyond the
+project limit are rejected. Loaded plugin tempo comes from TEMPO. Range and
+discrete-mode compatibility are checked on control-thread compilation. Versions
+1–5 migrate with empty plugin lanes. See CONTROL.md for timing/ordering.

docs/ROADMAP.md

@@ -324,6 +324,14 @@ unsupported; plugin realtime behavior and physical listening are unqualified.
 - Held notes are released safely on stop, panic, seek, and relevant failure paths.
 - Event ordering and interpolation behavior are documented and tested.
 
+Implemented: persisted sample-evaluated LADSPA parameter lanes with linear/step
+modes, range/discrete validation and public GUI editing; absolute automation
+position through seek and plan handoff; fixed live CC7/10/64 mappings with volume/
+pan ramps, sustain/retrigger safety, and exact block-partition regressions.
+Existing track Gain/Pan lanes cover audio and scheduled instrument volume.
+Format v6 migrates v1–v5. See CONTROL.md. MIDI capture/learn, pitch bend, new
+instrument timbres and physical listening remain outside the supported scope.
+
 ## Phase 17 — Editing Workflow, Undo/Redo, and Usability
 
 **Goal:** Make common editing tasks efficient and protect users from accidental changes.