Phase 7: Add MIDI clips, instrument and piano roll

docs/PROJECT_FORMAT.md

@@ -1,9 +1,9 @@
-# Project format v2 (reads v1)
+# Project format v3 (reads v1/v2)
 
-Phases 5/6 use a bounded text format implemented in C99 without a parser library.
+Phases 5–7 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 content is a subsequent phase.
+files; MIDI notes are stored inline.
 
 ## Schema
 
@@ -12,7 +12,7 @@ Fields use ASCII spaces. Integers are unsigned decimal, without signs.
 Counts determine the number of subsequent records:
 
 ```text
-XTC_PROJECT 2
+XTC_PROJECT 3
 APP 0 1 0
 TEMPO 120000
 IDS 1 1
@@ -25,6 +25,8 @@ TRACK 0 547261636b
 CLIPS 1
 CLIP 0 0 3840 2880 960 3840 526567696f6e
 ASSET -
+MIDI 0
+NOTES 0 0
 END
 ```
 
@@ -35,7 +37,7 @@ END
 - `GRAPH`: output-node policy (0/1), next node ID, node count, edge count.
   Nodes retain stable IDs (limited to the host's size_t range). No pointers or
   compiled state are serialized.
-- `NODE`: ID, type (1 gain, 2 oscillator, 3 meter, 4 output, 5 audio source), and exactly eight
+- `NODE`: ID, type (1 gain, 2 oscillator, 3 meter, 4 output, 5 audio source, 6 instrument), and exactly eight
   hexadecimal digits encoding the IEEE binary32 parameter bits, independent
   of locale and host byte order. Nonfinite values are rejected.
 - `EDGE`: source and destination node IDs. Mono port directions are implied
@@ -45,24 +47,32 @@ END
   length tick, hex-encoded name bytes. Trimming
   preserves source bounds, so a region can re-extend only within its original
   length. Overlaps are allowed and audio clips mix through the audio source node.
-- `ASSET`: required after each CLIP in v2; "-" means silent, otherwise
+- `ASSET`: required after each CLIP in v2/v3; "-" means no audio asset, otherwise
   hex-encoded absolute path bytes, <=511 bytes after decoding, no embedded NUL
   or ASCII control characters. Each clip directly references a WAV; no sample
   data, pointers or DSP state are embedded. Paths can contain spaces.
+- `MIDI`: required after each ASSET in v3; 0 for silent/audio regions, 1 for
+  MIDI clips. MIDI clips must have no asset.
+- `NOTES`: next stable note ID and global note count, followed by that many
+  `NOTE id clip_id start_tick length_tick pitch velocity channel` records.
+  Notes reference MIDI clips; start/length are source-relative, positive length
+  within source bounds. Pitch is 0..127, velocity 1..127, channel 0..15.
+  Note IDs are unique, monotonic uint64 IDs with UINT64_MAX reserved.
 - Names decode to nonempty valid UTF-8 of at most 63 bytes; ASCII control
   characters and embedded NULs are forbidden. Hex avoids quoting ambiguity.
 
 Ticks use 960 per quarter note, 3840 per bar. All region endpoints are bounded
 by 38400000 ticks (10000 bars). Limits: 64 tracks, 1024 clips, 64 graph nodes,
-4096 edges, 2 MiB input, 1535 bytes per record, 12 tokens per record. The reader
+4096 edges, 4096 notes, 4 MiB input, 1535 bytes per record, 12 tokens per record. The reader
 rejects invalid references, duplicate IDs, inconsistent next IDs, ranges,
 truncated records, raw control/non-ASCII bytes, and trailing data.
 
 Unsupported format versions return UNSUPPORTED. Other malformed data returns
 FORMAT. The reader explicitly accepts v1 records without ASSET lines, with
-node types 1..4, migrating their clips to empty asset paths. Saving always writes
-v2. Unknown versions are rejected without replacing the destination; older
-applications cannot read v2. Migration and maximum-path roundtrips are tested.
+node types 1..4, migrating their clips to empty asset paths. Version 2 accepts
+node types 1..5 and ASSET records. Both migrate to MIDI=0 and no notes.
+Saving always writes v3. Unknown versions are rejected without replacing the destination; older
+applications cannot read v3. Migration and maximum-path roundtrips are tested.
 
 ## Ownership and failures