Phase 26: add common parameter targets, step automation and MIDI control mapping

docs/PROJECT_FORMAT.md

@@ -1,6 +1,6 @@
-# Project format v9 (reads v1–v8)
+# Project format v10 (reads v1–v9)
 
-Phases 5–15 use a bounded text format implemented in C99 without a parser library.
+Phases 5–26 use a bounded text format implemented in C99 without a parser library.
 The extension is `.xtc`. File operations run exclusively on the control thread.
 The project owns its graph, tracks and silent/audio arrangement regions. Audio samples remain in external WAV
 files; MIDI notes are stored inline.
@@ -12,7 +12,7 @@ Fields use ASCII spaces. Integers are unsigned decimal, without signs.
 Counts determine the number of subsequent records:
 
 ```text
-XTC_PROJECT 7
+XTC_PROJECT 10
 APP 0 1 0
 TEMPO 120000
 IDS 1 1
@@ -23,12 +23,31 @@ EDGE 0 1
 TRACKS 1
 TRACK 0 547261636b
 MIX 3f800000 00000000 0 0
+ROUTE 0 18446744073709551615
 CLIPS 1
 CLIP 0 0 3840 2880 960 3840 526567696f6e
 ASSET -
 MIDI 0
+AUDIO 3f800000 0 0
 NOTES 0 0
 AUTOMATION 0
+CONTROL_MAPS 16
+MAP 0 7 10 64
+MAP 1 7 10 64
+MAP 2 7 10 64
+MAP 3 7 10 64
+MAP 4 7 10 64
+MAP 5 7 10 64
+MAP 6 7 10 64
+MAP 7 7 10 64
+MAP 8 7 10 64
+MAP 9 7 10 64
+MAP 10 7 10 64
+MAP 11 7 10 64
+MAP 12 7 10 64
+MAP 13 7 10 64
+MAP 14 7 10 64
+MAP 15 7 10 64
 END
 ```
 
@@ -47,6 +66,8 @@ END
 - `TRACK`: ID and hex-encoded name bytes. In v4/v5 each is immediately followed
   by `MIX gain_bits pan_bits mute solo`: finite binary32 gain 0..4, pan -1..1
   encoded as eight hex digits, mute and solo unsigned 0/1.
+- `ROUTE`: since v9, required after MIX: bus flag and destination bus ID;
+  UINT64_MAX denotes master. See Phase 24 constraints below.
 - `CLIP`: ID, track ID, start tick, length tick, source offset tick, source
   length tick, hex-encoded name bytes. Trimming
   preserves source bounds, so a region can re-extend only within its original
@@ -63,7 +84,8 @@ END
   within source bounds. Pitch is 0..127, velocity 1..127, channel 0..15.
   Note IDs are unique, monotonic uint64 IDs with UINT64_MAX reserved.
 - `AUTOMATION`: global point count, after the last NOTE and before END in v4/v5.
-  Follow with `POINT track_id parameter tick value_bits` for each point.
+  Follow with `POINT track_id parameter tick value_bits step` in v10 (v4–v9
+  omit step and migrate to linear). Step is 0 linear or 1 hold for the next segment.
   Parameter 0 is gain (0..4), 1 pan (-1..1); values use finite binary32 hex.
   Track must exist; tick <= MAX_TICK; duplicate track/parameter/tick is invalid.
   Record order is preserved; rendering sorts a separate prepared copy.
@@ -227,3 +249,23 @@ Bus controls and automation use existing MIX and POINT records. Older readers
 reject v9 rather than discard routing. The public `xtc_track_info` grew fields;
 API consumers must rebuild. Fixtures cover v1–v8 migration and tests exercise
 v9 exact roundtrips and malformed routing.
+
+## Phase 26: version 10 interpolation and controller bindings
+
+The current writer emits v10 and reads v1–v9. Track/bus automation points are
+`POINT track_id parameter tick value_bits step`, where step is 0 linear or 1
+hold for the segment starting there. v1–v9 points migrate to step=0. LADSPA
+`PARAM` encoding remains unchanged (already has interpolation mode).
+
+Immediately after all POINT records, before END, v10 requires `CONTROL_MAPS 16`
+and exactly 16 records in ascending channel order:
+`MAP channel volume_CC pan_CC sustain_CC`. Channels are 0..15. Controllers are
+0..127 or 128 (disabled); enabled numbers must be distinct within a row and may
+not be 120 or 123. Duplicate/missing/out-of-order channels, invalid CCs, reserved
+bindings and invalid interpolation modes reject the complete candidate. v1–v9
+supply default 7/10/64 bindings on every channel. No event history/current live
+controller values are serialized. Older readers reject v10.
+
+Fixtures cover v1–v9 migration. Exact roundtrips, malformed metadata, step/linear
+renders and remapped live events cover the new writer/reader. Public clients
+must rebuild and initialize the appended `xtc_automation_point.step` field.