Phase 32: add MIDI track CLAP, VST2 and VST3 instruments

docs/PLUGIN_HOSTING.md

@@ -19,7 +19,7 @@ plugin recovery policy, preparation failure/partial cleanup tests, bounded event
 and parameter publication, latency/tail handling, callback-safe unload after
 retirement, a GUI/main-thread boundary and an explicit crash-containment decision.
 Native ABI tests cover some ownership mechanics but do not prove third-party
-code safe. Event graph ports and custom-instrument GUI selection remain gaps.
+code safe. Event graph ports remain a gap; Phase 32 adds track instrument selection.
 Choose one format with concrete user needs after those contracts are specified;
 do not introduce a general multi-format framework now. See decision 0008.
 
@@ -113,8 +113,7 @@ Physical listening and plugin CPU/endurance qualification remain pending.
 Discovery remains explicit-file only, bounded to 1024 descriptor indices; no
 recursive scan, plugin database or new dependency is introduced. Unsupported
 layouts are skipped with counts; source/effect roles describe audio ports, not
-MIDI instrument capabilities. Built-in MIDI synthesis remains the only GUI MIDI
-instrument. LADSPA sources can be identified, edited, replaced and removed in
+MIDI instrument capabilities. Phase 32 adds modern track instruments (see below). LADSPA sources can be identified, edited, replaced and removed in
 the graph but cannot receive MIDI events.
 
 **Edit → Insert LADSPA on selected wire** replaces one existing connection with
@@ -224,7 +223,7 @@ prefers CLAP, then VST2, then VST3, otherwise LADSPA; the C API also provides
 
 The modern subset is **one mono audio input and one mono output, float32, default
 configuration, zero reported latency**. Stereo graph playback uses independent
-instances. True stereo/multichannel/sidechain buses, instruments, MIDI/events,
+instances. For the Phase 31 effect subset, true stereo/multichannel/sidechain buses, instruments, MIDI/events,
 custom editors, parameter changes/automation, programs/presets, opaque state,
 transport/time information, workers and latency compensation are not implemented
 for these three formats. Modern metadata with controls/automation is rejected,
@@ -257,3 +256,34 @@ CLAP start/process failures, graph replacement rollback, 50 plan retirements per
 format, missing modules, v11 save/reopen and GUI add/browser/undo/reopen. Host
 allocation/loading/unloading guards remain active while rendering. This evidence
 qualifies the subset above, not arbitrary external plugins or physical audio.
+
+## Phase 32 instrument support
+
+MIDI tracks can bind CLAP, VST2 and VST3 instruments. In the Track menu, select
+**Load instrument plugin** for the selected sequencer track; **Use built-in
+instrument** removes the binding. Assignment also selects the track for live
+MIDI. **Live MIDI to selected instrument** changes that target; **Live MIDI to
+built-in sine** restores the legacy live source. MIDI clip notes always go to
+their own track's instrument. Independent instances feed track gain/pan,
+mute/solo, bus routing and automation. Bindings/live target save in v12.
+
+Supply the actual trusted Linux binary (including the inner .so of a VST3
+bundle). Supported instruments have zero audio inputs, one mono output,
+float32 processing, zero latency and one note/event input. Default configuration
+only: no custom editor, opaque state/preset restoration, modern parameter
+editing/automation, stereo/multichannel instruments or MIDI output. No arbitrary
+third-party instrument is qualified by the original ABI fixture tests.
+
+CLAP accepts MIDI or native notes; VST2 uses MIDI events; VST3 uses IEventList
+note events. Live CC reaches CLAP MIDI/VST2; native CLAP/VST3 have no controller
+mapping (including sustain). Live MIDI goes to exactly one selected target.
+Seeks/loops retrigger notes crossing the destination with fresh envelopes;
+plugin oscillator/opaque DSP state cannot be reconstructed. Panic delivers
+all-off (VST3 held-key note-offs); plugin release tails may remain. Processing
+uses preallocated 256-frame chunks and 256 incoming events per instance/chunk;
+overflow or processing failure silences the block and schedules reset events.
+The existing 32 simultaneous scheduled-note and 4096 stored-note bounds remain.
+Do not unload/replace modules during playback; candidate plans are prepared off
+the callback and old instances are reclaimed on the control thread. Missing
+references remain inspectable without loading; failed GUI preparation retains
+the current project. Save a backup for applications limited to v11 or earlier.