SpaceAge Whiteboard

Updated: 2026-08-11
Purpose: end-to-end map of critical user flows for human and AI maintainers
Status: intended architectural map with audited current deviations; first source-comment tranche inserted

1. How To Use This Whiteboard

This document connects what the musician does to the code and state that make it happen. It is intentionally organized by user intent rather than by source-file order.

Each flow identifies:

• Entry surface.
• UI coordinator.
• Durable project owner.
• Realtime consequence.
• Persistence boundary.
• Failure/recovery behavior.
• Verification path.

The maps describe contracts, not every implementation detail. Code and focused tests remain the final authority.

2. System At A Glance

flowchart LR
    User["Musician"] --> UI["PluginEditor.cpp<br/>JUCE message thread"]
    UI --> Processor["PluginProcessor.cpp<br/>project and performance coordinator"]
    UI --> MidiModel["SpaceAgeMidi.cpp<br/>MIDI models, plans, reports"]
    Processor --> Snapshots["Published playback snapshots"]
    Snapshots --> Audio["processBlock()<br/>audio thread"]
    Audio --> Voices["Drums, Instruments, samplers, synths"]
    Audio --> Mixer["Mixer channels and shared effects"]
    Mixer --> Output["Main audio and plugin MIDI"]
    Processor --> MidiIn["Direct and host MIDI input"]
    Processor --> MidiOut["Hardware MIDI output router"]
    Processor --> State["JSON project state"]
    State --> Files["Projects, recovery, archives, exports"]
    Archive["SpaceAgeProjectArchive.cpp"] --> Files
    Tests["AudioSelfTest + release gates"] -. verify .-> Processor
    Tests -. verify .-> MidiModel

3. Core Domain Objects

Object	Owns	Does not own
Pad	Drum/sample source in one of 64 public slots	A non-drum lane Instrument
Instrument	A private sound-generator instance and patch	Mixer fader/send state
Instrument Bay	Choice/assignment workflow for Instruments	Musical notes
Pattern	Reusable notes, chords, steps, and shared automation	Arrangement position
Clip	Pattern placement, source range, repeats, transpose, local automation	Lane Instrument
Lane	Musical role, Instrument, MIDI route/channel, Mixer destination	Individual Clip timing
Section Marker	Song-form description	Musical content below it
Mixer channel	Gain, pan, EQ, processing, sends, metering	Synth patch
Hardware Passport	External-device identity, routing, capabilities, safety evidence	Automatic permission to transmit SysEx

4. Identity And Ownership Matrix

Concern	Stable identity	Positional/index value	Key rule
Lane	laneId	Arrangement lane index	Reordering must not change ownership
Clip	clipId	Arrangement clip index	Async work must commit by identity
Drum source	Pad 0-63	Visible bank/slot	Pad operations stay in public range
Lane Instrument	Private source slot	Lane index	One private instance per non-drum lane
Mixer route	Mixer channel 1-64	Visible Mixer bank	Independent from source slot
MIDI input	Armed lane + source session	Selected Clip/lane	Selection cannot steal live input
Automation	Pattern/Clip/Lane identity	Selected row	Ownership determines persistence/playback
Hardware route	Lane + device ID + route generation	Device slot	Stale generations cannot transmit

5. Thread And Mutation Map

Context	May do	Must not do
JUCE message thread	UI changes, file choosers, project mutations, APVTS gestures, dialogs	Block for long audio/file work
Audio thread	Consume snapshots, merge MIDI, advance transport, render voices/Mixer	File I/O, UI calls, device discovery, unbounded allocation, long blocking locks
MIDI input callback	Timestamp and enqueue bounded messages	Mutate editor/project collections directly
MIDI output thread	Open prepared routes, schedule/send guarded hardware messages	Infer user permission for setup/SysEx
Recording queues	Transfer bounded captured events into project state	Lose source identity or first-measure timing
Archive/export worker	Stage, validate, report progress	Replace active project or destination before validation

6. Audited Current Deviations

The maps below state the required product contracts. A 2026-07-31 static audit found these current deviations:

• Clip Local and Lane Local automation edits/deletions do not consistently republish the sequencer snapshot, so audible state can lag behind the drawing.
• One automation helper mixes Pattern-relative and Arrangement-relative ticks; export may also add Lane Local events separately. This requires focused duplicate-event tests and likely separation by time domain.
• Project load, save, and autosave still perform blocking file work on the message thread. Current progress feedback does not make the work asynchronous.
• Failed MIDI-record arming may checkpoint undo before target validation.
• Long-operation cancellation and some recovery failure feedback remain incomplete.
• Export needs one focused proof combining shared effects with Clip/Lane automation.

Treat these as implementation blockers, not accepted alternate architecture. The remaining flows use required, must, and rule language intentionally.

The hardware-sync policy preview gap found by this audit is now repaired and covered by the focused MIDI_SYNC_POLICY regression. The UI previews the exact proposed values it later commits, confirms receive-clock and outgoing roles, and warns that an already-running transport may begin the confirmed role on the next audio block.

7. Flow A: Launch, Choose Session, And Load

flowchart TD
    Launch["Launch SpaceAge"] --> Splash["Splash / startup feedback"]
    Splash --> Choice["Last Project | Blank Project | Load Project File"]
    Choice -->|Blank| Blank["Create canonical blank state"]
    Choice -->|Last/File| Busy["Show busy/progress overlay"]
    Busy --> Read["Read and parse candidate"]
    Read --> Validate{"Valid SpaceAge state?"}
    Validate -->|No| Preserve["Explain failure; preserve current session"]
    Validate -->|Yes| Restore["restoreStateObject()"]
    Restore --> Assets["Resolve or report missing assets"]
    Assets --> ResetRT["Reset runtime voices, queues, effects, transport"]
    ResetRT --> Arrange["Open Arrangement and fit overview"]
    Blank --> Arrange

Entry: showStartupChoiceDialog() in PluginEditor.cpp.
Coordinator: loadLastProjectFromStartupDialog(), loadProjectFile(), loadBlankProject().
Owner: processor JSON state through restoreStateObject() and setStateInformation().
Critical rule: parsing and validation precede active-session replacement. Project load does not transmit hardware setup or SysEx.
Failure boundary: malformed files, missing assets, canceled choosers, and failed archive validation leave the active session intact.
Verification: project roundtrip, corrupted-state rejection, blank-project lifecycle, recovery, and missing-asset regressions.

8. Flow B: Add An Instrument Lane And First Clip

flowchart TD
    AddLane["+ ADD LANE"] --> Type{"Drum or Instrument?"}
    Type -->|Instrument| Slot["Claim private Instrument slot"]
    Slot --> Init["Initialize selected/default engine and patch"]
    Init --> Lane["Create lane at top of Instrument stack"]
    Lane --> Route["Assign MIDI channel and Mixer destination"]
    Route --> Clip["Create lane-owned starter Clip/Pattern"]
    Clip --> Select["Select and visibly light lane"]
    Select --> Playhead{"Playhead position"}
    Playhead -->|Empty lane| Start["Place at measure 1"]
    Playhead -->|Step 1 and populated| End["Append after existing content"]
    Playhead -->|Explicit target| Target["Place at snapped playhead"]

Entry: showAddArrangementLaneMenu() and Instrument Bay choice.
Coordinator: createArrangementLaneFromInstrumentSlot() and setArrangementLaneInstrument().
Owner: ArrangementLane.instrumentSlot, stable Instrument identity, Pattern, and Clip.
Realtime consequence: the next published snapshot routes Clip notes through that private Instrument and its Mixer channel.
Critical rules:

• Instrument lane additions go to the top of the non-drum stack.
• The private Instrument slot is not a Pad proxy.
• Changing the Instrument preserves notes and Mixer destination.
• ADD CLIP targets the selected lane using the documented playhead rule.

Failure boundary: no private slot, maximum 16 lanes, invalid engine/preset, or user cancellation must not partially create a lane.
Verification: maximum-lane source independence, lane save/load, instrument replacement, Mixer assignment, and starter-Clip tests.

Instrument Editor Navigation

flowchart LR
    Lane["Lane Instrument badge"] --> Drawer["Open Synth Engine drawer"]
    Drawer --> Selector["Engine selector: sound-generator authority"]
    Selector --> Engine["ENGINE: selected engine's own editor"]
    Drawer --> Shared["Shared destinations"]
    Shared --> Layers["Layers / One-Shots"]
    Shared --> Shape["Noise / Envelope / Voice / Mod / Accent"]

Rule: The engine selector answers which sound generator belongs to the Instrument. The destination row answers what aspect is being edited. Hidden page indexes are an implementation detail and must not become a second customer-facing engine selector. Exactly one destination is active; used-state coloring may indicate other destinations that contain work.

9. Flow C: Add A Drum Lane And Drum Clip

flowchart TD
    Add["+ ADD LANE or + ADD DRUM CLIP"] --> Drum["Choose Drum"]
    Drum --> Position["Insert above newest Drum lane"]
    Position --> Pads["Use public Pad assignments 0-63"]
    Pads --> Pattern["Choose/create Drum Pattern"]
    Pattern --> Clip["Place Drum Clip at resolved target"]
    Clip --> Composer["Synth icon opens Drum Composer"]

Critical difference: Drum lanes intentionally share the Pad/Drum Composer performance model. Non-drum lanes must never inherit this source-assignment rule.
Failure boundary: ADD DRUM CLIP on a selected Drum lane must not fail because private Instrument slots are unavailable.
Verification: Drum lane creation, Add Drum Clip, variant/clone, Pad playback, and Arrangement playback gates.

10. Flow D: Playback, Loop, And Transport

flowchart TD
    Play["Play button or Spacebar"] --> Loop{"Active Arrangement loop?"}
    Loop -->|Yes| LoopStart["Jump to loop start"]
    Loop -->|No| Target{"Valid playhead target?"}
    Target -->|Yes| Playhead["Start at playhead"]
    Target -->|No| Start["Start at Arrangement beginning/current policy"]
    LoopStart --> Snapshot["Consume sequencer snapshots"]
    Playhead --> Snapshot
    Start --> Snapshot
    Snapshot --> Block["processBlock() advances sample-accurate transport"]
    Block --> Render["Patterns, chords, drums, automation"]
    Render --> Mix["Mixer + shared returns"]
    Mix --> Out["Audio and MIDI output"]

Critical rules:

• Transport controls and Spacebar resolve the same start policy.
• Active Arrangement loop has priority.
• Rewind updates the actual playback start, not only the visible playhead.
• The UI reads transport state; it does not independently advance musical time.
• Visual animations follow processor time and may be throttled, but cannot drive playback.

Failure boundary: Panic and Reset Audio must retire held voices and queues without corrupting project state.
Verification: transport, loop, playhead, discontinuity, timing-jitter, and shared-effect gates.

11. Flow E: Live MIDI Monitoring And Recording

flowchart TD
    Device["Host MIDI or direct USB/DIN device"] --> Timestamp["Timestamp + source session/generation"]
    Timestamp --> Queue["Bounded direct-input queue"]
    Queue --> Block["Drain into current audio block"]
    Block --> Arm{"Lane armed?"}
    Arm -->|No| MonitorPolicy["Monitor/block by explicit policy"]
    Arm -->|Yes| Filter["Apply lane input-channel filter"]
    Filter --> Route["Route to lane Instrument/Drum source"]
    Route --> Hear["Immediate monitoring"]
    Route --> Rec{"Record enabled?"}
    Rec -->|Yes| Time["Resolve activation, playhead, loop, signed sample offset"]
    Time --> Notes["Track source-aware note-on/off ownership"]
    Notes --> Commit["Recording queues commit notes/steps/expression"]
    Commit --> Clip["Create/extend target Clip and Pattern"]

Entry: lane MIDI arm button and Arrangement record transport.
Authority: armed lane, not selected lane or selected Clip.
Target resolution: explicit Clip under playhead, compatible existing target, or new lane-owned Clip at the playhead.
Critical rules:

• Multiple input devices retain source identity.
• Host/direct duplicates are suppressed.
• Note-off closes only the matching source/channel/note ownership.
• Count-in and recording activation cannot discard the first played measure.
• Note length and timing derive from captured timestamps, not UI refresh time.
• Monitoring remains low latency and does not wait for message-thread polling.

Failure boundary: queue overflow and ambiguous source conditions are reported by MIDI Health; they must not silently retarget notes.
Verification: MIDI latency, direct-input wrap, multi-controller, recording timing, first-measure, loop-edge, source retirement, and hardware-fixture tests.

12. Flow F: Edit Notes, Drums, And Chords

User action	Durable owner	Edited object	Primary rule
Draw or move a Piano Roll note	Pattern	PianoNote	Editing changes MIDI content, never lane routing.
Toggle a Drum Composer step	Drum Pattern and Pad source	Step event	Drum rows resolve through the Pad bank; melodic lanes do not.
Add or resize a Chord Marker	Pattern chord list	Chord event	The marker's spelling and duration remain theory-aware data.
Render an arpeggio	Pattern note list	Generated notes	Rendering creates inspectable notes; it does not hide a second playback engine.
Clone a Clip	Arrangement	Clip sharing the source Pattern	Later Pattern edits intentionally affect linked clones.
Make a Variant	Arrangement and Pattern registry	Clip with independent Pattern copy	The child becomes musically independent.
Cut or split content	Owning Pattern or Arrangement	New bounded segments	No event may be duplicated or lost at the split boundary.

Interaction contract: note, step, and Chord Marker tools share predictable selection, deletion, resizing, snapping, audition, and undo behavior where their domains permit it.

Failure boundary: an editor may not silently change the lane Instrument, Mixer destination, Pad assignment, or Clip ownership mode.

Verification: note editing, drum editing, Chord Engine, clone/variant, split, undo, selection, and long-Clip navigation gates.

13. Flow G: Draw And Play Automation

flowchart TD
    Doorway["Lane automation doorway"] --> Context["Resolve lane and visible timeline context"]
    Context --> Owner{"Choose ownership"}
    Owner -->|Shared PTN| PatternAuto["Pattern automation"]
    Owner -->|Clip Local| ClipAuto["Clip automation"]
    Owner -->|Lane Local| LaneAuto["Lane automation"]
    PatternAuto --> Row["Choose CC, pitch bend, pressure, or supported target"]
    ClipAuto --> Row
    LaneAuto --> Row
    Row --> Edit["Draw, move, scale, or delete points"]
    Edit --> Store["Store ordered MidiEventList"]
    Store --> Publish["Publish immutable playback snapshot"]
    Publish --> Audio["Apply at sample/block timing during playback"]
    Edit --> Clear["Clear target"]
    Clear --> Neutral["Remove payload and restore neutral audible state"]

Ownership rule: Shared PTN automation follows the Pattern, Clip Local automation follows one Clip instance, and Lane Local automation follows the lane regardless of which Clip is active.

Required realtime rule: drawing must publish a replacement snapshot; the audio thread never reads a container while the UI mutates it. The current Clip/Lane-local publication gap is listed in Audited Current Deviations.

Clear rule: deleting the visible curve must also remove its audible influence. Hidden or stale controller state is a release-blocking defect.

Verification: automation playback, live redraw, clear/reset, loop boundary, ownership, undo, save/load, and export parity gates.

14. Flow H: Mix A Lane Through Shared Effects

flowchart LR
    Source["Lane Instrument or Drum source"] --> Channel["Assigned Mixer channel"]
    Channel --> Strip["Gain, pan, EQ, dynamics, inserts"]
    Strip --> Dry["Dry channel bus"]
    Strip --> Sends["Explicit shared-effect sends"]
    Sends --> Returns["Halostar, Reverb, EchoRay, modulation returns"]
    Dry --> Master["Master bus"]
    Returns --> Master
    Master --> Safety["Limiter and output safety"]
    Safety --> Device["Audio device / host output"]

Ownership rule: the Mixer owns gain, pan, channel EQ, routing, and effect sends. Instrument patches own synthesis or sample-generation parameters only.

Routing rule: lane Instrument assignment and lane Mixer assignment are independent, explicit, persistent choices.

Page rule: leaving the Mixer dismisses channel subpages so returning users see meters and primary controls.

Failure boundary: changing a synth parameter must never alter another lane, Pad, or Mixer channel because of a stale source index.

Verification: lane-to-Mixer routing, channel persistence, shared returns, mute/solo, master safety, and multi-lane isolation tests.

15. Flow I: Save, Load, Recover, And Archive A Project

flowchart TD
    Save["Save request"] --> Snapshot["Capture coherent project state"]
    Snapshot --> Stage["Write staged file/package"]
    Stage --> Verify["Parse and validate staged result"]
    Verify --> Commit["Atomically replace destination"]
    Commit --> Remember["Update recent/last-project metadata"]

    Load["Load request"] --> Parse["Parse into temporary state"]
    Parse --> Validate["Validate identities, ranges, assets, and routing"]
    Validate --> Swap["Commit complete state"]
    Swap --> Publish["Rebuild playback snapshots and UI"]

    Recover["Recovery request"] --> Parse
    Archive["Archive request"] --> Collect["Collect project and referenced assets"]
    Collect --> Sanitize["Sanitize package paths"]
    Sanitize --> Package["Write and inspect archive"]

Transaction rule: failed parsing or writing leaves the currently open project and existing destination untouched.

Identity rule: lane IDs and Clip IDs remain stable; array indexes are positional implementation details and must not become durable identities.

Asset rule: missing external assets produce a relinkable diagnostic rather than silent substitution.

Verification: project roundtrip, malformed input, recovery, missing assets, archive safety, and startup-choice tests.

16. Flow J: Render Or Export

flowchart TD
    Scope["Choose song, selection, lane, Clip, MIDI, or supported audio scope"] --> Ready["Run readiness checks"]
    Ready --> Destination["Choose destination"]
    Destination --> Clone["Clone/freeze render state"]
    Clone --> Execute["Offline render or MIDI serialization"]
    Execute --> Progress["Report determinate progress"]
    Progress --> Stage["Write staged output"]
    Stage --> Validate["Validate duration, format, and non-empty result"]
    Validate --> Commit["Commit final file"]

Parity rule: export uses the same musical ownership, routing, automation, tempo, and loop-independent timeline semantics as normal playback.

Isolation rule: export must not drive external MIDI hardware or emit SysEx as a side effect.

Capability rule: each Arrangement lane can render as a time-aligned audio stem using its saved Instrument and Mixer path; unsupported scopes remain visibly unavailable.

Verification: MIDI export conformance, whole-song duration, automation parity, interrupted output, and staged-file cleanup tests.

17. Flow K: Configure Hardware MIDI And SysEx

flowchart TD
    Open["Open MIDI Hardware setup"] --> Inventory["Inventory input/output ports"]
    Inventory --> Route["Create explicit lane/device route"]
    Route --> Test["Send safe note/controller test"]
    Test --> Profile["Choose or create device profile"]
    Profile --> Plan["Build parameter, bank, preset, or dump plan"]
    Plan --> Review["Show bytes, target, risk, and expected response"]
    Review --> Confirm["Explicit user confirmation"]
    Confirm --> Queue["Generation-guarded output queue"]
    Queue --> Send["Transmit bounded MIDI/SysEx"]
    Send --> Receipt["Match response, ACK, timeout, or retry policy"]

Safety rule: project load, report generation, preview, and export are passive. They never transmit to hardware.

Device rule: input and output ports are identified independently; hot-plugging retires stale generations so queued work cannot reach a replacement device accidentally.

SysEx rule: manufacturer/device IDs, checksums, pacing, acknowledgement, dump size, and cancellation behavior belong to the device profile or protocol plan, not scattered UI callbacks.

Verification: virtual fixtures, loopback, hot-plug, multi-controller, timeout, cancellation, checksum, and real-device proof.

18. Flow L: Panic And Recover Performance State

flowchart TD
    Panic["PANIC / reset request"] --> Internal["Release all internal voices"]
    Panic --> Midi["Send bounded all-notes-off/reset messages to active routes"]
    Internal --> Ownership["Clear note ownership and deferred events"]
    Midi --> Ownership
    Ownership --> Queues["Retire stale queued generations"]
    Queues --> UI["Refresh transport, meters, and health status"]

Safety rule: panic is idempotent and bounded. Repeated use must not allocate unbounded work, corrupt project state, or leave a source permanently muted.

Verification: stuck-note, page-switch, device-removal, loop-edge, playback-stop, and repeated-panic tests.

19. Failure Checklist For Any Flow Change

Before modifying a flow, answer all of these:

1. Who owns the durable data?
2. Which identifier remains stable after insertion, deletion, reordering, save, and load?
3. Which thread may mutate the data?
4. What immutable or bounded representation reaches the audio thread?
5. What happens at a loop, transport, or device-generation boundary?
6. What does undo restore?
7. What is persisted, archived, and exported?
8. Can the action accidentally affect hardware?
9. What visible diagnostic proves success or explains failure?
10. Which automated gate and human scenario defend the behavior?

20. Current Architectural Boundaries

• The current Arrangement model supports a bounded set of lanes and private lane Instrument source slots; this is not the final dynamic Instrument Bay architecture.
• Drum Pads remain a 64-source performance and Drum Composer domain.
• Melodic Instrument lanes must not use Pads as their customer-facing identity.
• VST hosting, audio stems, signing/installer work, SpaceAge Scenes, and Raspberry Pi support remain future or release-track work, not implied beta features.
• Real hardware proof remains necessary even when virtual MIDI fixtures pass.

21. Maintaining This Whiteboard

• Update a flow only when its ownership or user-visible journey changes.
• Link to focused specifications instead of copying protocol tables or chronological reports here.
• Keep historical decisions in journals; keep current truth here.
• Add a new flow when a feature introduces a new durable owner, thread boundary, transaction, or hardware side effect.
• Remove obsolete flows rather than preserving misleading migration history.

22. Source Navigation Index

Concern	Primary source anchor
Audio-block coordination	PluginProcessor.cpp::processBlock()
MIDI record activation	PluginProcessor.cpp::startMidiRecording()
Arrangement lane routing	PluginProcessor.cpp::setArrangementLaneInstrumentSlot() and setArrangementLaneMixerChannel()
Arrangement Clip creation	PluginProcessor.cpp::addArrangementClip()
Transport and panic	PluginProcessor.cpp::startSequencerFromArrangementStart() and panicAllNotesOff()
State persistence	PluginProcessor.cpp::getStateInformation(), setStateInformation(), and restoreStateObject()
Page and modal coordination	PluginEditor.cpp::showPage() and related panel entrypoints
Startup/project workflows	PluginEditor.cpp::showStartupChoiceDialog(), loadProjectFile(), and saveCompleteProjectTo()
MIDI models and plans	SpaceAgeMidi.cpp and SpaceAgeMidi.h
Project archives	SpaceAgeProjectArchive.cpp

23. Relationship To Source Comments

The Code Commenting Architecture Guide defines what belongs beside the code. This Whiteboard defines the journeys those comments must help a maintainer traverse. A useful source comment should clarify one dangerous edge in these flows, not repeat the whole map.

2026-07-31 - Automation Publication And Export Flow

UI edit / undo / paste / restore
    -> mutate one automation owner
    -> publish one immutable playback generation
    -> audio thread reads the new generation

MIDI export
    -> Shared Pattern + Clip Local: crop in source time, then place/repeat at clip destination
    -> Lane Local: crop once in absolute Arrangement time
    -> write the two domains to MIDI without cross-domain merging

Release invariant: removing visible automation must also remove its audible snapshot state; resetting owner IDs must retire their payloads before reuse.

Pattern MIDI Import Transaction

flowchart LR
    File["MIDI file"] --> Parse["Parse and convert source time"]
    Parse --> Stage["Stage notes, drum steps, expression/setup, and SysEx"]
    Stage --> Accepted{"Accepted payload?"}
    Accepted -->|"No"| Reject["Return false; no checkpoint or mutation"]
    Accepted -->|"SysEx only"| Vault["Checkpoint, then quarantine in SysEx Vault"]
    Accepted -->|"Pattern payload"| Undo["Create one undo checkpoint"]
    Undo --> Lock["Acquire patternMutex"]
    Lock --> Commit["Apply full or partial replacement boundaries"]
    Commit --> Publish["Publish exactly one Pattern playback snapshot"]
    Publish --> Unlock["Release patternMutex"]
    Unlock --> Refresh["Refresh affected expression lanes from committed state"]
    Refresh --> VaultToo["Quarantine any staged SysEx separately"]

Identity invariant:

existing lane/clip property edit -> retain laneId/clipId -> owner-scoped automation remains attached
new lane/clip insertion          -> allocate/validate identity -> new automation owner

Hardware Profile Delete Publication

flowchart LR
    Delete["Remove profile request"] --> Lock["Joint patternMutex + midiProfileMutex lock"]
    Lock --> Registry["Remove registry entry"]
    Registry --> Lanes["Clear dependent lane hardwareProfileId routes"]
    Lanes --> Ready["Refresh cached sync/chase readiness"]
    Ready --> Publish["Publish sequencer snapshot"]
    Publish --> Unlock["Release both locks"]
    Unlock --> Clock["Refresh hardware clock output snapshot"]

Release proof: MIDI_PROFILE_DELETE_PUBLICATION checks registry, mutable lane, immutable snapshot, serialized state, readiness, and idempotent repeat removal.

Live Monitor Channel Ownership

flowchart LR
    Input["Incoming note/control on Channel 4"] --> Owner["Control ownership: source session + Channel 4"]
    Input --> Route["Lane output remap: Channel 15"]
    Owner --> Sustain["Sustain/expression/note-off release Channel 4 voice"]
    Route --> Sound["Voice and outbound MIDI use Channel 15"]

Release proof: MIDI_RECORD_TIMING includes a non-recording Channel 4 to Channel 15 sustain/expression ownership case for melodic live monitoring; the same input-control/output-voice split is wired through the drum fallback path.

Restore Recording Boundary

flowchart LR
    Capture["Realtime note/drum/expression capture"] --> Stamp["Stamp queued item with recording epoch"]
    Stamp --> Worker["Recording worker reaches commit"]
    Restore["Undo or state restore"] --> Cancel["Cancel active/pending recording; reset count-in and targets"]
    Cancel --> Lock["Acquire patternMutex"]
    Lock --> Advance["Advance epoch and clear held-note bookkeeping"]
    Advance --> Rebuild["Restore model and publish restored snapshots"]
    Worker --> Compare{"Item epoch equals current epoch inside commit lock?"}
    Compare -->|"Yes"| Commit["Commit and publish"]
    Compare -->|"No"| Discard["Discard without mutation or publication"]

Release proof: MIDI_RESTORE_RECORDING_BOUNDARY holds note and expression workers before commit, restores through both direct state load and undo, releases stale work, sends a late note-off, and checks mutable plus immutable Pattern state.

Long-Pattern Post-Record Quantization

flowchart LR
    Take["Recorded note near step 192.5"] --> Grid["Quantize to one-step grid"]
    Horizon["Stored Pattern length: 256"] --> Clamp["Clamp to Pattern horizon"]
    Grid --> Clamp
    Clamp --> Result["Note near step 193; length 1; horizon 256"]

Release proof: the existing 256-step direct-record fixture is part of MIDI_RECORD_TIMING and now includes the post-record transform.

Count-In Boundary And Passport Deletion

flowchart LR
    Block["8192-sample block at 48 kHz / 120 BPM"] --> CountIn["Count-in consumes samples 0..5999"]
    CountIn --> Boundary["Recording activates at sample 6000"]
    Boundary --> StepZero["Schedule step zero + metronome at 6000"]
    StepZero --> Continue["Process remaining 2192 samples; advance Arrangement step"]

Release proof: PLAYBACK_COUNTIN_BOUNDARY requires the metronome event at sample 6000 and the Arrangement playhead at step 1 after one callback.

flowchart TD
    Button["REMOVE PASSPORT"] --> Confirm{"Customer confirms?"}
    Confirm -->|"No"| Cancel["Editor helper returns cancelled; no checkpoint"]
    Confirm -->|"Yes"| Guard{"Any SysEx snapshot attached?"}
    Guard -->|"Yes"| Block["Explain Vault detach/delete requirement; preserve Passport, lane, and SysEx"]
    Guard -->|"No"| Checkpoint["Checkpoint project"]
    Checkpoint --> Delete["Processor deletion transaction"]
    Delete --> Refresh["Refresh editor and panel models"]
    Refresh --> Undo["Undo restores Passport + lane attachment"]

Release proof: MIDI_PROFILE_DELETE_PUBLICATION exercises the editor helper for cancel, confirmed delete, no-op, undo, serialization, snapshot publication, and attached-SysEx refusal.

Realtime Recording And Arm Transaction - 2026-07-31

Mermaid-ready flow:

flowchart LR
    A["Pattern, lane, clip, or record-target edit"] --> B["Publish immutable RecordingReadSnapshot"]
    B --> C["Audio callback loads one generation"]
    C --> D["Map note, drum, and expression timing without patternMutex"]
    D --> E["Bounded recording queues"]
    E --> F["Worker commits under patternMutex"]
    G["REC requested"] --> H["Preflight armed/selected lane, clip capacity, unused Pattern, timeline range"]
    H -->|failure| I["No mutation; redo retained"]
    H -->|success| J["Checkpoint at commit boundary"]
    J --> K["Select/create target and start recording"]

Release gates: REALTIME_RECORDING_NOLOCK, PROJECT_PERSISTENCE, then MIDI_RECORD_TIMING, MIDI_CLOSEOUT, and MIDI_HEALTH.

Realtime Loop Playback Snapshot - 2026-07-31

• UI/load/restore writers take sampleMutex, update the complete loop model, and atomically publish one immutable LoopPlaybackSnapshot generation.
• processBlock() acquires exactly one snapshot at entry and uses only that generation for loop asset ownership, routing, mute/solo/scope, reverse, gain, and loop processor settings for the entire block.
• Fixed LoopRuntimeState belongs only to the audio thread. Transport reset requests clear it at a callback boundary; a track-generation change resets only that track before rendering the new model.
• A writer may destroy a replaced snapshot immediately only when the callback epoch is stably idle. Otherwise it queues the old generation for reclamation by a later non-audio publisher after the epoch changes.
• REALTIME_LOOP_SNAPSHOT holds a callback after capture, clears/replaces/reconfigures the loop concurrently, then proves old-generation current-block output, new-generation next-block output, finite samples, zero loop callback lock/allocation/destruction diagnostics, and observed non-audio retirement.

This flow does not migrate legacy visible-Pad lane state and does not claim process-wide allocation instrumentation.

Realtime Instrument Asset Retirement - Verified 2026-07-31

• Writer under the asset mutex: build complete immutable generation -> atomic exchange -> move displaced generation to retirement storage -> reclaim only entries with no callback/voice owner.
• Voice start: atomically capture cache -> select prepared asset -> retain the cache generation for the voice lifetime.
• Voice completion/retirement: drop TSF/sample/mapped leaf handles first -> drop generation token last; no locks, allocation, unmap, or final TSF close.
• Shared sample ownership covers normal layers plus Liftoff and Lunacy user-source paths. Quasar voices retain the selected zone-cache generation. SoundFont voices retain the prepared rack generation containing the master and prepared instances.
• REALTIME_INSTRUMENT_ASSET_RETIREMENT is green with sample generations 82 -> 85 -> 86, SoundFont generations 1 -> 2 -> 3, finite output, zero callback diagnostics, and observed non-audio reclaim.
• Companion verification is green: Quasar asset, SoundFont asset, all 21 synth engines, realtime loop snapshot, realtime recording no-lock, MIDI closeout, and MIDI health.

Owner-Scoped Live Automation Remap - Verified 2026-07-31

flowchart LR
    Edit["Stored automation event: source Channel 4 + owner identity"] --> Resolve["Resolve owner in immutable sequencer snapshot"]
    Resolve --> Shared["Shared Pattern: lanes containing that Pattern"]
    Resolve --> Clip["Clip Local: lane owning stable clipId"]
    Resolve --> Lane["Lane Local: lane owning stable laneId"]
    Shared --> Routes["Collect affected Arrangement lane routes"]
    Clip --> Routes
    Lane --> Routes
    Routes --> Internal{"Any owner-scoped Arrangement destination?"}
    Internal -->|"Internal lane"| Remap["Apply lane output remap; dedupe channels"]
    Remap --> Live["Apply or neutral-reset internal CC/bend/sustain state"]
    Internal -->|"External-only"| Skip["No internal state fallback"]
    Internal -->|"No Arrangement destination"| Raw["Use raw source-channel fallback"]
    Routes --> Hardware["Existing hardware-output path remains separate"]

Release proof: AUTOMATION_OWNERSHIP covers Channel 4 to Channel 12 apply/delete for Shared Pattern, Clip Local, and Lane Local owners; CC1/7/10/11, pitch bend, sustain, deduplication, external-only routing, raw fallback, stale-state cleanup, and cross-lane isolation. Companion gates: AUTOMATION_RESTORE, MIDI_CLOSEOUT, and MIDI_HEALTH.

Candidate Clean-Checkout Convergence - Wired 2026-07-31

flowchart LR
    SHA["Candidate SHA"] --> Resolve["Resolve exact commit"]
    Resolve --> Refuse{"Required current inputs clean?"}
    Refuse -->|"No"| Stop["Refuse before worktree/build"]
    Refuse -->|"Yes"| Worktree["Detached guarded temp worktree"]
    Worktree --> Tracked["Verify CMake/package inputs tracked"]
    Tracked --> Build["Fresh SampleSquadAudioTest build"]
    Build --> Gates["Canonical convergence including I08-A"]
    Gates --> Diff["git diff --check + clean status"]
    Diff --> Receipt["Exact-SHA PASS receipt"]
    Receipt --> Cleanup["Remove guarded temp worktree only"]

• Cheap proof is green: PowerShell parsing, convergence-manifest assertions, release hygiene, and deterministic dirty-dependency refusal.
• Full clean-checkout convergence subsequently passed for exact candidate 0b0fafe08d78996e5286b448f2c1e6b5bb7b9156; receipt test-reports/clean-checkout-convergence-0b0fafe08d78-20260731-202928.out records 21/21 PASS.
• The runner builds no customer executable and does not stage, commit, package, or delete current-workspace artifacts.
• Hardware, listening, installer/signing, and clean-machine receipts remain independent human gates.

Explicit Arrangement Recording Interval - Verified 2026-07-31

flowchart LR
    Input["Note, drum, or expression input"] --> Target{"Explicit clip ID selected?"}
    Target -->|"Yes"| Resolve["Resolve only that clip"]
    Resolve --> Preroll["Clamp tiny pre-roll to clip start"]
    Preroll --> Interval{"Inside length x repeats?"}
    Interval -->|"No"| Drop["Reject before queue; increment dropped-event diagnostic"]
    Interval -->|"Yes"| Map["Map relative position through source length"]
    Map --> Queue["Enqueue bounded recording mutation"]
    Drop --> Shared["Shared Pattern remains unchanged"]
    Shared --> Linked["Longer linked clip on another lane cannot reveal hidden data"]

Release proof: MIDI_RECORD_TIMING selects a 16-step clip while longer same-Pattern clips exist, sends step-20 note-on/off, drum, and CC11 events, and requires zero queued writes, empty shared payloads, note/drum and expression drop diagnostics, and zero linked-lane playback leaks. Companion gates: MIDI_RECORD_CAPTURE_CORE, PLAYBACK_COUNTIN_BOUNDARY, REALTIME_RECORDING_NOLOCK, MIDI_RESTORE_RECORDING_BOUNDARY, MIDI_CLOSEOUT, MIDI_HEALTH, and the Arranger edit contract.

Release-candidate provenance flow

Dirty working tree -> classify required product inputs -> ignore generated evidence -> review ambiguous asset provenance -> stage explicit manifest -> inspect staged diff -> candidate commit -> detached clean-checkout build -> canonical convergence -> physical hardware/listening/installer QA.

Windows proof-workspace constraint: the detached checkout and build live under a short guarded temporary path (.../Temp/SA/cc-.../src and b). This prevents JUCE/MSBuild nested try-compile paths from exceeding the legacy path limit while retaining exact-SHA isolation and guarded cleanup.

Build-location contract: release convergence resolves its test executable through the shared SPACEAGE_BUILD_DIR path contract. The clean-checkout runner publishes its isolated build directory through that contract, preventing a successful detached build from being confused with a legacy workspace build.

TG55 asset clearance boundary

Preserve WAV + recipe + catalog + hash -> mark public distribution blocked -> recover generator and reproduce, obtain creator attestation, or replace with newly tracked deterministic generation -> update legal ledger -> release hygiene review -> package.

2026-07-31 - Automation Ownership Release Invariant

Shared PTN + Clip Local forms a clip's effective Automation payload. Lane Local remains on the Arrangement timeline and is applied independently in absolute time. Tests, import/export, playback, and future editing surfaces must preserve this boundary; Lane Local events must not be copied into each clip-effective event list.

Privacy-Safe Support Flow - Foundation 2026-07-31

flowchart LR
    State["System + MIDI readiness state"] --> Text["Plain-text reports"]
    Text --> Redact["Redact user home + absolute paths"]
    Redact --> Stage["Stage README, system, diagnostics"]
    Stage --> Zip["Atomic three-entry ZIP"]
    Zip --> Verify["Verify exact entry contract"]
    Verify --> Reveal["Reveal support bundle to user"]
    Project["Projects, notes, audio, samples, presets"] --> Exclude["Excluded by design"]

• Current proof: focused archive test passes with three expected entries and no private-path leakage.
• Next diagnostic layer: rotating session log, startup/clean-shutdown markers, and standalone crash interception.
• Boundary: support diagnostics may describe routing and health; they must not capture musical content or private source assets.

A08 Exact Section And Clip Movement

flowchart LR
    Select["Selected clips + Section markers"] --> Delta["One shared horizontal delta"]
    Delta --> Own{"Contains primary Chain-owned Drum clip?"}
    Own -->|"Yes"| Refuse["Refuse complete move; preserve history"]
    Own -->|"No"| Preflight["Validate every bound and collision"]
    Preflight -->|"Invalid"| Refuse
    Preflight -->|"Valid"| Checkpoint["Create one Undo checkpoint"]
    Checkpoint --> Commit["Commit clips and Sections together"]
    Commit --> Publish["Publish one playback snapshot"]
    Publish --> Persist["Preserve IDs, automation, Undo/Redo, reopen"]

The first Drum lane is a projection of the legacy Chain. Each Chain slot owns a persistent projected clip ID; edits and reordering keep that identity, duplication creates a fresh identity, and additional Drum lanes remain native Arrangement material.

L08 Time-Aligned Lane Audio Stems

flowchart LR
    User["RENDER: Lane Audio Stems"] --> Snapshot["Capture one immutable project state"]
    Snapshot --> Plan["Plan every lane: ID, name, Instrument, Mixer, route, state"]
    Plan --> Stage["Create unique temporary package"]
    Stage --> Each["For each Arrangement lane"]
    Each --> Isolate["Mute other lanes before event scheduling"]
    Isolate --> Mix["Run saved Mixer, sends, effects, and Master path"]
    Mix --> WAV["Write aligned stereo 24-bit WAV + five-second tail"]
    WAV --> More{"More lanes?"}
    More -->|"Yes"| Each
    More -->|"No"| Manifest["Write manifest with ownership and silence reasons"]
    Manifest --> Verify["Verify package and publish atomically"]
    Each --> Cancel{"Cancelled or failed?"}
    Cancel -->|"Yes"| Remove["Remove temporary package; preserve destination"]

The Drum lane is isolated as one musical owner even though it can feed many Pad Mixer channels. Muted, solo-excluded, empty, and external-only lanes remain aligned files with explicit manifest reasons. Offline rendering suppresses physical MIDI and transport output.

S01 Drum Composer Edit Flow

flowchart LR
    Entry["Left-click empty step"] --> Select["Enable and select step"]
    Select --> Property["Drag Accent / Probability / Ratchets"]
    Property --> History["One gesture = one Undo record"]
    Active["Left-click active step"] --> Audition["Audition; keep note"]
    Delete["Right-click active step"] --> Remove["Delete with one checkpoint"]
    Bank["Ctrl+A in visible bank"] --> BankDelete["Delete only visible-bank notes"]
    Clear["Clear Drum Composer"] --> Preserve["Remove Drum steps; preserve duration, notes, chords"]

Empty cells have no editable hidden property payload. All Drum mutations pass the same lane-ownership guard before changing project state.

S02 Piano Roll Edit Flow

flowchart LR
    Begin["Mouse gesture begins"] --> Own{"Instrument-owned target?"}
    Own -->|"No"| Refuse["Refuse without history mutation"]
    Own -->|"Yes"| Change{"First real change?"}
    Change -->|"No"| EndNoOp["End gesture; preserve Redo"]
    Change -->|"Yes"| Checkpoint["Create one Undo checkpoint"]
    Checkpoint --> Mutate["Apply live note/velocity/erase updates"]
    Mutate --> End["Gesture ends"]
    End --> Refresh["Publish one final editor/project refresh"]

Selection identity is based on the actual note object/index, not a value signature. Group movement and resize use one bounded delta. FIT follows selected notes; reset exposes the complete clip source window, including nonzero source offsets.

S03 Chord Engine Edit Flow

flowchart LR
    Select["Select lane-owned Chord Marker"] --> Begin["Begin one lazy edit transaction"]
    Begin --> Edit["Create / move / resize / split / delete / clone"]
    Begin --> Perform["Gain / pan / voices / strum / arp / mute"]
    Begin --> Type["Typed chord / slash bass / custom cluster"]
    Edit --> Validate["Validate ownership, bounds, and minimum duration"]
    Perform --> Captured["Write to panel-captured pattern and Instrument"]
    Type --> Parse["Accept exact spelling or refuse atomically"]
    Validate --> Publish["Publish one coherent ChordClip update"]
    Captured --> Publish
    Parse --> Publish
    Publish --> Persist["Save / reopen exact performance object"]
    Publish --> Export["Playback / arp render / MIDI export"]
    Publish --> History["One Undo / Redo action"]

Trust rule: A Chord Marker keeps the same musical identity everywhere. UI gestures, floating panels, reopening, rendering, and export may transform presentation, but may not silently discard performance fields or redirect ownership.

Automated gate: S03-A plus neighboring S01-A, S02-A, A04-A, and P04-A; canonical Release convergence 31/31.

A01 Arrangement Move Flow

flowchart LR
    Select["Visible clip / Section selection"] --> Lift["One lifted magnetic preview"]
    Lift --> Edge{"Pointer near viewport edge?"}
    Edge -->|"Yes"| Scroll["60 Hz continuous auto-scroll"]
    Scroll --> Snap["Recalculate exact snapped destination"]
    Edge -->|"No"| Snap
    Snap --> Validate{"All selected items fit exactly?"}
    Validate -->|"Yes"| Commit["One transaction; preserve clip IDs and selection"]
    Validate -->|"No"| Refuse["No mutation; refresh processor truth; preserve Redo"]
    Lift --> Escape["Escape"]
    Escape --> Cancel["Restore local geometry; cancel gesture; clear selection"]

Trust rule: What lifts is what moves, where the preview lands is where the data lands, and a refused or cancelled gesture changes nothing.

Automated gate: A01-A plus A07-A, S06-A, S08-A, and M03-B; canonical Release convergence 37/37.

A02 Whole-Song Playhead Insertion Flow

flowchart LR
    Copy["Mixed clips and Section selection"] --> Span["Measure one global source span"]
    Span --> Target["Snap to explicit playhead target"]
    Target --> Preflight{"All lane, Drum-chain, Section, automation, and capacity rules pass?"}
    Preflight -->|"No"| Refuse["Explain refusal; mutate nothing; preserve Redo"]
    Preflight -->|"Yes"| Shift["Shift complete song by longest copied span"]
    Shift --> Insert["Insert copies with relative offsets and ownership intact"]
    Insert --> Publish["One checkpoint and one coherent Arrangement publication"]
    Publish --> Persist["Undo/Redo and save/reopen exact"]

Trust rule: Explicit playhead paste is ripple insertion across the complete song, not lane-local overwrite. The widest copied item defines the inserted time. A real primary Drum block may be shifted only from an exact edge; SpaceAge refuses an unsafe middle cut instead of guessing.

Automated gate: A02-A plus A07-A, A06-A, S08-A, M03-B, and P04-A; canonical Release convergence 38/38.

A03 Preserve-Time Delete Flow

flowchart LR
    Select["Visible clips and Section markers"] --> Resolve["Resolve clip IDs, primary Drum slots, and Section indices"]
    Resolve --> Preflight{"At least one Section remains and Drum gaps have empty Patterns?"}
    Preflight -->|"No"| Refuse["Explain refusal; mutate nothing; preserve Redo"]
    Preflight -->|"Yes"| Checkpoint["One project checkpoint"]
    Checkpoint --> Native["Native clips become same-span gaps; selected native gaps disappear"]
    Checkpoint --> Drum["Primary Drum blocks become same-duration silent chain slots"]
    Checkpoint --> Sections["Remove only selected Section markers"]
    Native --> Publish["One deferred Arrangement publication"]
    Drum --> Publish
    Sections --> Publish
    Publish --> Persist["Undo/Redo and save/reopen exact"]

Trust rule: Normal Delete removes selected content, never song time. Unselected overlapping clips survive. Shared Pattern and Lane Local automation survive; Clip Local automation leaves with its clip.

Automated gate: A03-A plus A02-A, A06-A, and A07-A; canonical Release convergence 39/39.

Project Trust Flow: Save, Save As, And Load

MUSICIAN CHOOSES LOAD
        |
        v
preflight file identity + version + semantic bounds + portable asset references
        |
        +---- reject ----> keep open project, target, preference, history, and UI unchanged
        |                         |
        |                         v
        |                 visible failure receipt
        v
restore processor state exactly
        |
        v
clear former-project Undo / Redo / rollback history
        |
        v
adopt file identity once in editor
        |
        v
sync tempo + Instruments + Arrangement + Mixer + loops + editors + Library
        |
        v
show and fit Arrangement

SAVE AS
  capture current project state
  -> write independent target atomically
  -> source project remains byte-identical
  -> adopt new target only after success
  -> future Save Over writes only that target

EXTERNAL ASSET
  empty path       -> valid empty slot
  absolute + good  -> decode and restore
  absolute + bad   -> retain repair receipt
  relative         -> reject as ambiguous; never guess from process CWD

User promise: Loading another song cannot make Undo resurrect the previous song, a failed load cannot steal the save target, Save As cannot secretly depend on the source project file, and a silent/corrupt asset cannot disappear without explanation.

Automated gate: P02-P03-A plus complete application self-test and canonical Release convergence 39/39 (reports/p02-p03-project-trust-convergence-20260803.out). Human QA remains for Windows chooser cancellation, overwrite/refusal language, large-project progress, and real-library relinking.

P06 Honest Project-Load Feedback Flow

flowchart LR
    Choose["Musician chooses Load Last, Project File, Preset, Recovery, or imported archive"] --> Acknowledge["Immediate visible loading acknowledgement"]
    Acknowledge --> Guard["Disable load choices and consume global keyboard commands"]
    Guard --> Phase["Show checking/restoring phase with indeterminate progress"]
    Phase --> Restore["Synchronous atomic project restore"]
    Restore --> Result{"Restore succeeded?"}
    Result -->|"No"| Failure["Keep current session; preserve remembered path; durable failure receipt"]
    Result -->|"Yes"| Adopt["Adopt project identity; sync UI; fit Arrangement"]
    Adopt --> Complete["Generation-guarded hide; durable completion receipt"]

Trust rule: SpaceAge never claims a percentage it cannot measure, never lets a stale timer close a newer loading state, and never converts a temporarily disconnected drive into a forgotten project.

Automated gate: P06-A plus P02-P03-A, P04-B, and canonical Release convergence 40/40 (reports/p06-project-load-feedback-convergence-20260803.out). Human QA remains for the feel of very large synchronous SoundFont/Quasar restoration and real removable-drive retry.

P07 Missing-Asset Repair Flow

flowchart LR
    Open["Open project"] --> Receipt["List exact missing dependencies"]
    Receipt --> Search["Choose parent folder or one replacement"]
    Search --> Unique{"Exactly one valid match?"}
    Unique -->|No| Preserve["Leave unresolved; change nothing"]
    Unique -->|Yes| Decode["Decode/load into original owner"]
    Decode --> Refresh["Refresh receipts and audible state"]
    Refresh --> Save["Tell musician to save project"]
    Save --> Reopen["Reopen with repaired paths"]

Safety boundary: folder repair matches exact filenames or exact Quasar package-directory names. Duplicate names are never guessed. Quasar directory and manifest discovery are deduplicated before counting. Individual repair callbacks carry the original missing-asset identity and are rejected once stale.

Automated gate: P07-C creates all five external asset classes in one project, relocates them, forces one deliberate duplicate-name ambiguity, repairs the four unique dependencies, repairs the final dependency after ambiguity removal, rejects a stale receipt, renders finite audio, saves, and reopens with no missing assets. Canonical Release convergence is 41/41 after this gate is included.

P08 Clean Close And Relaunch Flow

flowchart LR
    Close["Close SpaceAge or release audio resources"] --> Stop["Stop transport, recording, and MIDI producers"]
    Stop --> Panic["Retire voices, sustain, note ownership, and future events"]
    Panic --> Drain["Drain hardware safety messages"]
    Drain --> Devices["Stop router and close MIDI outputs"]
    Devices --> Clean["Write clean-session evidence"]
    Clean --> Relaunch["Relaunch into SpaceAge startup choices"]
    Relaunch --> Choice{"Standalone or hosted?"}
    Choice -->|"Standalone"| Startup["SpaceAge owns Last / Blank / File decision"]
    Choice -->|"VST3"| Host["Host restores plugin state; no standalone startup UI"]

Runtime rule: clean-session evidence is the final checkpoint, not an optimistic first step. No queued output or active musical owner may outlive it.

State rule: JUCE wrapper state is host-facing plugin infrastructure. It must not silently choose a standalone song or bypass SpaceAge's explicit startup workflow.

Automated gate: P08-A plus project persistence, project-load feedback, golden lifecycle, MIDI closeout, complete application self-test, and canonical Release convergence 42/42.

P04 Recovery Flow

flowchart LR
    Edit["Musician changes notes, sound design, routing, Flux, or MIDI"] --> Snapshot["Standalone writes a distinct recovery snapshot"]
    Snapshot --> Interrupt{"Session ends cleanly?"}
    Interrupt -->|"Yes"| Normal["Normal Last / Blank / File startup choices"]
    Interrupt -->|"No or useful recovery remains"| Offer["Startup offers newest recovery with timestamp and summary"]
    Offer --> Restore["Shared production recovery loader"]
    Restore --> Valid{"Snapshot valid?"}
    Valid -->|"No"| Preserve["Keep current session and preferences unchanged"]
    Valid -->|"Yes"| Unsaved["Adopt exact state as Recovered Session (Unsaved)"]
    Unsaved --> Assets{"External assets available?"}
    Assets -->|"No"| Repair["Open Library repair workflow"]
    Assets -->|"Yes"| SaveAs["Choose Save As"]
    Repair --> SaveAs
    SaveAs --> Project["Independent normal project"]

Ownership rule: hosted plugin editors are host-owned and do not write global standalone recovery snapshots. Standalone recovery remains visible from both startup and Library through one loader.

Safety rule: a malformed snapshot, stale callback, or failed restore cannot change the open project, current save target, Last Project preference, or visible state.

Automated gate: P04-C plus P04-D. Human QA remains for a real Windows forced interruption, startup wording/readability, and one recovered project with moved personal assets.

I03 Factory Preset Safety Flow

flowchart LR
    UI["Visible engine preset menu"] --> Manifest["Enumerate every customer-visible choice"]
    Manifest --> Index["Reject stale or invalid index"]
    Index --> Reset["Reset shared modulation and pitch state"]
    Reset --> Recipe["Apply the named preset recipe"]
    Recipe --> Display["Refresh every visible control"]
    Display --> Validate["Finite values, ranges, category tuning, unique name"]
    Validate --> Audition["Eight-note audition and voice retirement"]
    Audition --> CPU["Representative CPU gate"]
    CPU --> Human["Human chord listening and target-machine profile"]

Product rule: tonal category names promise restrained, musically legible pitch behavior. Experimental categories may use wide dispersion only when their names and browser metadata make that intention clear.

Ownership rule: a preset owns Instrument voice state only. It never owns Mixer processing, lane routing, or shared-effect sends.

State rule: recall starts from deterministic shared movement state. A preset may not inherit vibrato, gate, pitch spread, or another hidden behavior from the preset loaded before it.

Automated gate: I03-C derives its manifest from the actual preset menus and checks all 619 visible choices. I03-A and I03-B cover isolated and Arrangement CPU/retirement behavior. Canonical Release convergence is 51/51. Human listening and target-machine profiling remain in the QA matrix.

Native Instrument Control Gesture

Open lane Instrument editor -> choose engine/subpage -> slow drag for fine change or fast drag for range -> hear the change -> exact-value entry if needed -> release -> one Undo restores the prior sound

Control rules:

• The visible value belongs to the parameter currently producing sound.
• One pointer gesture creates one history entry.
• Every engine uses the same interaction grammar.
• A page may not hide a control below its bounds; adding parameters expands the calculated grid rather than relying on a fixed row count.
• Human beta judges tactile comfort and Windows scaling after the automated geometry/Undo contract passes.

I01 Factory Instrument Default Flow

flowchart LR
    Bay["Instrument Bay or lane choice"] --> Preset["First customer-visible factory preset"]
    Preset --> Lane["Private Instrument Lane source"]
    Lane --> A4["Audition MIDI A4 and release"]
    A4 --> Audio["Finite, audible, bounded output"]
    Audio --> Type{"Tonal engine?"}
    Type -->|Yes| Pitch["Measure A440 fundamental"]
    Type -->|No| Retire["Verify clean voice retirement"]
    Pitch --> Retire
    Retire --> Pass["I01-B receipt"]
    Bay --> Assets{"Asset-backed engine?"}
    Assets -->|SoundFont| I04["I04 real SF2 fixture"]
    Assets -->|Quasar| I05["I05 real package fixture"]

Product rule: a fresh Instrument must speak safely without setup. Tonal engines must agree with concert pitch; intentionally percussive or noisy engines must declare that different contract rather than failing an irrelevant pitch test.

Ownership rule: audition through the lane-owned Instrument source. Raw note numbers also address Drum pads and can test the wrong object while producing apparently valid audio.

Granular rule: grain position chooses the source offset; grain age advances the source at pitch. They are not two independent phase clocks.

Automated gate: I01-B passes all thirteen self-contained factory engines. SoundFont and Quasar remain in their real-asset gates. Canonical Release convergence is 52/52; human listening remains responsible for default-patch appeal and register balance.

I05 Quasar Production Build Flow

flowchart LR
    Source["Lane-owned Instrument state"] --> Freeze["Freeze slot, engine, patch, and processor state"]
    Freeze --> Stage["Create hidden staging package"]
    Stage --> Matrix["Render roots x velocity layers x round robins"]
    Matrix --> WAV["Write portable ASCII WAV filenames"]
    WAV --> Manifest["Write exact ranges, loops, RR, and source metadata"]
    Manifest --> Publish["Publish complete directory"]
    Publish --> Owner{"Same slot, engine, and patch still active?"}
    Owner -->|Yes| Load["Load finished Quasar Instrument"]
    Owner -->|No| Preserve["Keep package; do not hijack changed lane"]
    Stage --> Cancel["Cancel before commit: remove staging"]

Snapshot rule: one package represents one moment of sound design. Every zone renders from the same frozen source state even if the musician continues editing the live project.

Commit rule: incomplete work remains private in staging. Cancellation wins before publication; a completed publication wins over a late Cancel receipt. Progress reaches 100% only after that commit.

Ownership rule: asynchronous completion carries its original logical owner. A successful asset may survive a lane or patch change, but it may not overwrite the musician's newer choice.

Mapping rule: roots, velocity layers, and round robins form an exact matrix. Sample paths are portable, ASCII-safe, package-relative, and verified before playback.

Automated gate: I05-B proves an eight-zone production build, mapping, portable filenames, monotonic progress, immediate load/playback, cancellation cleanup, and existing-target preservation. I05-A proves consumer load/relink/project behavior. Canonical Release convergence is 53/53 in reports/release-convergence-i05b-final-20260803.out; large-build feel and forced interruption remain human beta work.

I08 Hostile Instrument Replacement Flow

flowchart LR
    Candidate["SoundFont or Quasar candidate"] --> Type{"Resource type"}
    Type -->|SF2| SF["Bounded RIFF/SF2 structural preflight"]
    Type -->|Quasar| Q["Strict manifest, path containment, and decode budget"]
    SF --> Prepare["Decode and prepare complete private candidate"]
    Q --> Prepare
    Prepare --> Valid{"Fully valid?"}
    Valid -->|No| Preserve["Report failure and preserve active Instrument"]
    Valid -->|Yes| Commit["Atomically publish candidate"]
    Commit --> Exclusive["Retire stale external engine in this slot"]
    Exclusive --> Snapshot["Republish playback and persistence truth"]
    Repair["Missing-asset chooser receipt"] --> Epoch{"Same project epoch and tuple?"}
    Epoch -->|No| Refuse["Reject stale callback"]
    Epoch -->|Yes| Candidate

Validation rule: parsing does not grant ownership. Every table, index, range, path, sample, and aggregate allocation must be proven safe before live state changes.

Preservation rule: rejection leaves the previous path, metadata, cache generation, engine, audible playback, lane/Instrument identity, backing slot, Mixer route, MIDI route, and project state intact.

Exclusivity rule: a slot cannot secretly contain both SoundFont and Quasar. Successful replacement clears the stale external engine before save/reopen can reactivate it.

Async rule: repair callbacks carry a project epoch as well as the resource tuple. Reusing a slot and path in a later project cannot make an old chooser result valid again.

Automated gate: I08-B/C proves both hostile replacement and same-project reload after an already-live asset becomes corrupt. Restore retains only an exact same-path/preset known-good cache, records a repair receipt, preserves lane/Mixer/MIDI ownership and Quasar round-robin state, and retires stale caches not reclaimed by the incoming project. Focused receipts: reports/hostile-instrument-resource-i08b-final.out and reports/hostile-instrument-resource-i08c.out; canonical Release convergence 54/54 in reports/release-convergence-i08c-final-20260803.out. Human beta remains for real vendor assets, giant packages, slow/removable storage, interruption, and message clarity.

X03 Full Shared-Effects Signal Boundary

flowchart LR
    Source["Audible Mixer channel"] --> Send["One public send"]
    Send --> Family{"Effect family"}
    Family -->|Ambience or delay| Tail["Finite audible tail plus control response"]
    Family -->|Modulation or pitch| Transform["Audible transformation plus control response"]
    Transform --> Silence["Late window returns to silence"]
    Tail --> Disable["Disable produces no return"]
    Silence --> Disable

Automated gate: X03-A now covers Halostar, Reverb, EchoRay, Chorus, Flanger, Phaser, Tremolo, and Octave through production parameters and Mixer sends. The strengthened test exposed and closed an Octave DC-output defect. Focused evidence is reports/x03-full-rack-dc-safe-20260803.out; canonical Release convergence is 54/54 in reports/release-convergence-x03-full-rack-20260803.out.

X05 Frozen-State Render Parity Boundary

flowchart LR
    A["Captured project state"] --> B["Normal live processBlock playback"]
    A --> C["Production offline renderer"]
    B --> D["Reference audio"]
    C --> E["Verified 24-bit temporary WAV"]
    D --> F["Parity comparison"]
    E --> F
    F --> G["Atomic destination replacement"]
    C --> H["Cancellation"]
    H --> I["Existing destination remains intact"]

Contract: exact tempo-derived timeline length, late material, Mixer routing, shared-effect decay, finite output, progress monotonicity, live/offline parity, successful atomic publication, and cancellation preservation.

Automated gate: X05-A, focused evidence reports/x05-offline-render-parity-20260803.out.

I04 SoundFont Workstation Contract - Verified 2026-08-04

flowchart LR
    File["Generated three-preset SF2"] --> Preflight["Bounded SF2 preflight"]
    Preflight --> Load["Private lane Instrument load"]
    Load --> Presets["Enumerate, select, and clamp presets"]
    Presets --> ProgramAudio["Prove each preset changes audio"]
    ProgramAudio --> Controls["Isolate cutoff and each ADSR stage"]
    Controls --> Save["Save selected preset and controls"]
    Save --> Reopen["Reopen with identical Instrument state"]
    Reopen --> Move["Move the SF2"]
    Move --> Receipt["Typed missing-asset receipt"]
    Receipt --> Relink["Relink exact asset"]
    Relink --> Audio["Match saved peak, RMS windows, and retirement"]

Software boundary: the generated bank proves deterministic format, audible program choice, control response, identity, persistence, and repair behavior without private content. Negative and positive preset-index clamps are both covered; cutoff, attack, decay, sustain, and release are measured separately.

Human boundary: Shane's large GM bank and an independently authored bank must still prove real preset variety, Panic/controller response, loading feel, CPU/memory behavior, and musical quality on release hardware.

Automated gate: focused I04-A evidence is reports/i04-soundfont-controls-final-20260804.out; exact-source canonical Release convergence is 54/54 in reports/release-convergence-i04-controls-final-20260804.out.

Release Rights Flow

Integrated dependency or embedded asset
        |
        +--> machine inventory + exact evidence hash
        |       |
        |       +--> release hygiene rejects drift or missing notice
        |
        +--> human ownership/commercial-license decision
                |
                +--> blocked until durable attestation exists
                        |
                        +--> public package includes manifest + notices

Automated proof can establish what entered the build and whether the reviewed evidence changed. It cannot sign JUCE/VST3 agreements or establish authorship of art/audio. Release_Legal_Signoff.md is the bridge between those two truths.

Exact clean commit
       |
       +--> dependency + embedded-asset hashes
       +--> completed rights and preset signoff
       +--> fresh standalone + VST3 identity checks
       +--> copied standalone launch
                 |
                 +--> ReleaseManifest.json
                           |
                           +--> signed installer / public checksums (future)

Factory Preset Identity Boundary

619 factory presets
       |
       +--> deterministic safety sweep
       |       +--> bank + name + sorted normalized parameter state
       |       +--> fingerprint 4d2ddc400437c5d6
       |
       +--> Resources/FactoryPresetInventory.json
       |       +--> exact bank counts
       |       +--> release hygiene drift rejection
       |
       +--> ReleaseManifest.json SHA-256 evidence
               |
               +--> human provenance attestation remains separate

The 2026-08-11 recapture is authoritative because the complete live runtime bank, focused 619-preset safety sweep, machine-readable inventory, and release hygiene all agree. Earlier dated fingerprints remain historical receipts rather than current package policy.

Final Archive Publication Boundary

Verified staging tree
       |
       +--> compress ZIP
                |
                +--> reopen as untrusted input
                        +--> reject unsafe/duplicate paths
                        +--> verify source commit + identity
                        +--> re-hash binaries + legal evidence
                        +--> require runtime-import + toolchain inventory
                        +--> verify complete package file set
                        +--> verify upstream-proven JUCE evidence
                                |
                                +--> PASS: atomically publish ZIP + .sha256
                                |           +--> generate exact-ZIP attestation
                                |                    +--> human review + validation
                                |                              +--> public distribution
                                +--> FAIL: no public checksum, no release

The rights signoff authorizes candidate creation. It cannot truthfully attest to an archive that does not exist yet. The generated archive attestation is the second boundary and is deliberately bound to the final bytes.

Human Beta Evidence Flow

authoritative open blocker
        |
        +--> Beta Readiness selects exact next test
                |
                +--> human performs test on exact build
                        |
                        +--> explicitly chooses PASS / FAIL / BLOCKED
                        +--> supplies evidence + references + environment
                                |
                                +--> validate complete receipt
                                +--> re-read ledger under process lock
                                +--> append sequence + previous SHA-256 link
                                +--> atomically publish + verify chain
                                        |
                                        +--> display HUMAN QA REPORTED result
                                        +--> authoritative blocker remains unchanged

The receipt answers what a human observed on one binary. It does not answer whether the product is releasable. Release status remains the convergence of automated gates, reviewed human evidence, legal signoff, packaging proof, and explicit release judgment.

MIDI Launch-Proof Interaction

MIDI Health identifies next missing proof
        |
        +--> primary action opens the real test surface
        |       +--> Automation / MIDI Timing / Hardware Passport
        |       +--> MIDI Maps / SysEx Vault / MIDI Import / Beta Readiness
        |
        +--> musician performs the test on the exact build
                |
                +--> dedicated proof action records PASS / FAIL / BLOCKED
                        +--> evidence reference and tester identity
                        +--> build-scoped receipt
                        +--> public claims remain locked until proof is complete

The doorway starts the work; the receipt documents the result. They must never be presented as the same action.

Physical Controller Proof Detail

MIDI Health opens MIDI Timing
        |
        +--> perform controller test on exact build
                |
                +--> record controller + USB/DIN path
                +--> record audio buffer + latency
                +--> record compensation/pinning
                +--> record timing and note-placement result
                        |
                        +--> PASS only when every required observation exists
                        +--> FAIL/BLOCKED still require real evidence
                        +--> save build-scoped receipt

The structured notes remain one compact UI field, but they preserve enough context to compare controllers, interfaces, USB versus DIN paths, and future Hardware Passport recommendations.

Visible Launch Cockpit

MIDI Health opens
        |
        +--> first nine rows always contain
                +--> launch card and proof state
                +--> verdict and exact run identity
                +--> evidence detail
                +--> correct action doorway
                        +--> RPN/NRPN -> MIDI Patch
                        +--> public wording -> Capture Review

The critical row count is guarded against the visible-row budget. Long diagnostic inventories may follow, but they cannot push the next release action out of sight.

Receipt Validation Without Data Loss

musician enters MIDI proof
        |
        +--> Save
                |
                +--> valid -> append ledger receipt
                |
                +--> incomplete
                        +--> retain temporary complete draft
                        +--> report exact missing fields
                        +--> return to populated form
                                +--> correct and retry
                                +--> Cancel deliberately discards draft

A validation refusal changes no project, MIDI route, or hardware state and must not erase the human observation being documented.

Accessible MIDI Health Cockpit

health model / receipt store changes
        |
        +--> repaint visible cockpit
        |       +--> title row
        |       +--> responsive command row
        |       +--> readable critical proof rows
        |
        +--> rebuild semantic summary
                +--> cockpit status
                +--> next action
                +--> proof count
                +--> verdict
                +--> action guidance
                        |
                        +--> notify accessibility client

Visual and spoken status are derived from the same model. The Settings scroll shell owns viewport reachability; MIDI Health does not shrink critical text to avoid scrolling.

MIDI Health Presentation Contract

health model --> shared semantic builder --> live accessibility description
                    |
                    +--> Settings regression assertions

available command row --> shared bounds builder --> live button placement
                            |
                            +--> full-width contract
                            +--> compact-width contract
                                    +--> contained
                                    +--> minimum target width
                                    +--> stable gaps
                                    +--> stable height

The test does not imitate the interface. It executes the same presentation calculations used by the interface.

Shared Popup Exit Contract

ordinary popup opens
        |
        +--> content receives keyboard focus
        +--> accessible title explains purpose
        +--> Escape -> dismiss callout without applying a new action
        +--> outside click -> JUCE callout shell dismisses

protected decision popup
        |
        +--> keeps its specialized confirmation / cancellation rules

The shared behavior removes interaction drift without weakening dialogs that intentionally protect consequential work.

Long Clip Preview Reduction

sorted visible note / Chord events
        |
        +--> 32 or fewer: keep every event
        |
        +--> more than 32: evenly select 32 representatives
                    +--> first event retained
                    +--> final event retained
                    +--> strict temporal ordering
                            |
                            +--> Arrangement clip thumbnail spans the full clip

The miniature remains intentionally modest, but it cannot falsely imply that a long clip contains only its opening material.

Production Clip Preview Proof

256-step pattern with dense stored notes
        |
        +--> processor note store
        +--> editor refreshChain()
        +--> ArrangementLaneCanvas::setClips()
        +--> production ClipContentPreview
                    |
                    +--> 32 representative marks
                    +--> opening region present
                    +--> final region present

The full MIDI closeout verdict consumes this proof together with Add Clip placement, lane Instrument presentation, Mixer reassignment, and MIDI policy presentation. The broad verdict therefore cannot bypass the narrower lane-workflow contract.

Explicit Arrangement Loop Render Flow

1. The musician defines an Arrangement playback loop.
2. RENDER > Render Active Arrangement Loop to WAV is available only while that loop is valid.
3. The editor freezes the current first and final steps before opening the asynchronous render path.
4. The offline processor restores one captured project state, clears runtime loops, and begins at the frozen first step.
5. Duration is calculated from the frozen range across the saved tempo-multiplier chain.
6. Transport stops at the range boundary; effects decay into the standard tail without restarting the song.
7. A temporary WAV is verified and then atomically replaces the chosen destination.
8. Full Arrangement WAV remains a separate step-zero-to-song-end operation.

This boundary should be reused for future selection bounce, freeze, Motion Clip print, and range-based sample capture.

Source-Backed Patch Transaction

SAVE
active WAV + patch parameters
        |
        +--> stage/copy WAV atomically into <Patch>_Sources
        +--> same-file source is preserved as-is
        +--> publish .ssynth only with truthful source metadata

LOAD
.ssynth
        |
        +--> validate format + engine + parameter schema
        +--> try safe bundled relative WAV first
        +--> try original absolute WAV only as fallback
        +--> require successful audio decode
                    |
                    +--> success: one checkpoint, source + parameters + identity commit
                    +--> failure: no mutation, no audition, specific refusal message

This transaction model should be reused for user wavetables, impulse responses, Quasar packages, spectral analyses, and future portable Instrument Bay assets.

Project Source Repair Ledger

PROJECT LOAD / SOURCE ACTION
          |
          +--> inspect stored path + decoded sample state
          +--> classify musical dependency
          |       0 sample layer   1 one-shot   2 loop
          |       3 SoundFont      4 Quasar
          |       5 Liftoff source 6 Lunacy source
          |
          +--> publish epoch-stamped repair receipt
                      |
          replacement chosen --> decode before mutation --> rescan
          source intentionally cleared ------------------> rescan
                      |
          +--> refresh engine source label
          +--> refresh Library repair list
          +--> reject stale receipts from an earlier ledger

The same semantic receipt model should be extended to future impulse responses, user wavetables, spectral analyses, and other portable Instrument dependencies.

Complete Project Asset Boundary

ALL SOURCE SLOTS (visible Drum Pads + private Arrangement Instruments)
          |
          +--> rescan dependency ledger
          |       +--> missing: refuse with repair-or-clear instruction
          |       +--> healthy: continue
          +--> collect Pad samples + Liftoff/Lunacy sources + SoundFonts
          +--> collect Quasar package directories through their typed namespace
          +--> deduplicate canonical source files
          +--> stage assets under controlled package paths
          +--> replace private absolute paths with safe internal placeholders
          +--> validate project + manifest + extracted paths
          +--> import/remap into destination asset folder
          +--> publish project only after every dependency is bound
                      |
                      +--> prove ordinary sample exists
                      +--> prove Liftoff source renders audio
                      +--> prove Lunacy source renders audio
                      +--> prove SoundFont preset renders audio
                      +--> prove Quasar package renders audio

Automated PROJECT_ARCHIVE evidence removes every original dependency, imports five remapped references, and proves all four asset-backed Instrument engines remain playable.

IMPORTED PROJECT
      |
      +--> ordinary Save As
      +--> close imported session
      +--> construct fresh processor
      +--> reopen ordinary project
      +--> require empty repair ledger
      +--> require every resource below imported root
      +--> render Liftoff, Lunacy, SoundFont, and Quasar again

This boundary must also govern future impulse responses, user wavetables, spectral analyses, Motion Clip sources, and any Instrument Bay dependency that lives beyond the visible Pad domain.

Resource Chain Of Custody

ACTIVE PROJECT | +--> rescan missing receipts +--> save staged project with original resource paths +--> FRESH PROCESSOR LOAD | +--> any loader failure: refuse export | +--> all resources activate: package | +--> IMPORT +--> inspect ZIP and manifest +--> extract into temporary root +--> map placeholders to temporary extracted paths +--> FRESH PROCESSOR LOAD | +--> unreadable resource: delete staging and refuse | +--> all resources activate: map to final root +--> commit final root

IMPORTED PROJECT + EXTERNAL SOURCE
      |
      +--> recovery snapshot
      +--> external source moves
      +--> load recovery
      +--> exactly one missing receipt
      +--> imported source path remains healthy and audible
      +--> repair external source only
      +--> ordinary Save and fresh Reopen
      +--> both paths exact, no receipts, both audible

Folder repair compares archive-indexed names such as 001_source.wav with the original source.wav; manual repair includes FLAC.

2026-08-09 - Publication Trust Boundaries

Project archive flow:

1. Build export plan.
2. Write a temporary ZIP.
3. Inspect ZIP structure.
4. Run the production portable-project import validator against the temporary ZIP.
5. Only after successful validation, replace the destination.

VST3 release flow:

1. Build VST3 and isolated host harness.
2. Scan and instantiate the exact build bundle.
3. Process MIDI and audio at 44.1 and 48 kHz.
4. Round-trip state and reopen the editor.
5. Copy the VST3 into staging.
6. Repeat the host smoke against the staged copy.
7. Package only after the staged copy passes.

2026-08-10 - Mixer Channel Detail Navigation

CHANNEL OVERVIEW
      |
      +--> SND --> pan / auto-pan / shared-return sends / delay shaping
      |             |
      |             +--> BACK --> channel fader and meter
      |
      +--> DYN --> compressor / saturation
      |             |
      |             +--> BACK --> channel fader and meter
      |
      +--> EQ  --> musical channel EQ
                    |
                    +--> BACK --> channel fader and meter

Navigation state is editor-local. Channel values remain processor-owned and persist independently. Leaving Mixer closes every detail page so returning musicians see channel activity first; the last detail identity is not serialized into a project.

2026-08-10 - Settings And Library Decision Maps

SPACEAGE SETTINGS
      |
      +--> DISPLAY / EDITING
      |       +--> piano-roll labels and velocity
      |       +--> scale lock and preview behavior
      |       +--> tool tips and arrangement display
      |       +--> compact Drum Composer
      |
      +--> PLAYBACK / RECORDING
      |       +--> host and spacebar behavior
      |       +--> record quantize and metronome policy
      |       +--> loop snapping and startup sound
      |
      +--> MIDI PREFLIGHT
              +--> current input / device / output / runtime truth
              +--> setup, routing, expression, diagnostics, help

LIBRARY
      |
      +--> SAVE KIT / PROJECT
      +--> PROJECT / PRESET FILES
      +--> PAD BANKS / MIDI PACKAGES
      +--> PROJECT RECOVERY
      +--> STARTING POINTS

The visible reading order and keyboard focus order are now the same. Grouping describes ownership; it does not create new state or alternate execution paths.

2026-08-10 - Settings Doorways And Library State Truth

MIDI PREFLIGHT
      |
      +--> SETUP / ROUTING
      |       +--> Setup Guide / Input / Output / Hardware Profiles
      |
      +--> PERFORMANCE / DATA
      |       +--> MIDI Automation / Maps / Sync / Patch Data
      |
      +--> DIAGNOSTICS
      |       +--> Refresh / Health / Timing / Beta Readiness
      |
      +--> ADVANCED / HELP
              +--> Protocol Status / SysEx Vault / Shortcuts / Support Bundle

LIBRARY ACTION STATE
      |
      +--> no presets --> selector and LOAD SELECTED disabled
      +--> no recovery --> selector, LOAD, and DELETE disabled
      +--> assets healthy --> Repair disabled
      +--> assets missing --> count announced and Repair enabled
      +--> DELETE RECOVERY --> destructive style --> captured-file confirmation --> delete or cancel

Visible state, keyboard order, help text, and actual action availability now tell the same story.

2026-08-10 - Responsive Inspector And Dialog Floor

ARRANGER INSPECTOR
      |
      +--> Notes closed --> full inspector width
      +--> Notes open   --> responsive 340-430 px Notes pane
      +--> wide         --> two inspector rows
      +--> medium       --> three inspector rows
      +--> narrow       --> four inspector rows
      +--> every target remains readable and reachable

MIDI IMPORT DIALOG
      |
      +--> reserve bottom action row first
      +--> reserve action/body breathing room
      +--> paint fixed review dashboard
      +--> give remaining height to scrollable report
      +--> clear conditional SPLIT bounds when unavailable

Layout follows visible responsibility. Hidden work owns no pixels; essential actions never depend on leftover height.

2026-08-10 - Temporary Panel Exit Contract

ARRANGEMENT LANE BUTTON
      |
      +--> command or MIDI routing overlay opens
      +--> controls traverse in visible order
      +--> action chosen --> apply --> close --> focus canvas
      +--> Escape       --> no data change --> close --> focus canvas
      +--> outside click--> no data change --> close --> continue canvas action

MIDI EXPORT REVIEW
      |
      +--> COPY REPORT --> EXPORT FILE --> EXPORT STEMS --> CANCEL

Temporary UI must never trap focus, conceal the next action, or require a hunt for its close control.

2026-08-10 - Dynamic Choice Contract

RUNTIME-CREATED CHOICE
      |
      +--> name what it is
      +--> announce current/selected state
      +--> explain the consequence
      +--> place it in visible keyboard order
      +--> preserve existing safety behavior

GRID COLOR: 16 named swatches in row-major order
MIDI PACKAGE: import decision -> report/repair helpers -> close

Compact visual controls may omit visible prose, but they must never omit meaning. LANE INSTRUMENT DRAWER | +--> responsive layout may shorten labels +--> ownership meaning must remain Instrument, never Pad +--> control target and customer-facing words must agree

2026-08-10 - Modal Selection Dialog Contract

INVOKING ACTION
      |
      +--> modal dialog opens and owns Escape cancellation
      +--> panel announces title, purpose, and no-change exit
      +--> runtime choices traverse in visible order
      +--> each choice names its consequence
      +--> APPLY / FUSE --> commit once --> close
      +--> CANCEL / Escape --> no data change --> close

PAD VAULT: category or sound choices
FUSE PATTERNS: ordered pattern choices -> supporting actions
PICK FAVORITES: preset toggles -> supporting actions

Modal decisions do not close on click-away. Their exit is explicit because partial selections may already be staged on screen.

2026-08-10 - Loop Processor Visibility Contract

LOOP TRACK FX BUTTON
      |
      +--> processor callout opens
      +--> column 1: Compressor / Gain Boost / LP Filter
      +--> column 2: Saturation / Tape / Distortion
      +--> column 3: Halostar / Reverb / Delay
      +--> column 4: Width / Fade In / Fade Out / Curve
      +--> every control has bounds, meaning, and keyboard order
      +--> value change publishes existing loop settings immediately
      +--> Escape or outside click closes the callout

An audible state may never be controlled by an invisible widget.

2026-08-10 - Startup And Persistent Overlay Contract

WELCOME SPLASH | +--> full editor input shield +--> centered artwork card +--> Continue owns initial focus +--> no workspace shortcut leakage | v START SESSION | +--> Recovery, if available +--> Last Project, if remembered +--> Project File +--> Blank Project +--> Template Library | +--> loading begins | +--> all choices disabled +--> radar, message, and honest indeterminate progress visible +--> stale completion cannot close a newer load +--> successful completion restores workspace focus

ABOUT
      |
      +--> Close owns focus
      +--> Escape closes
      +--> focus returns to About

A surface that visually covers the workspace must also own input until it leaves.

2026-08-10 - Responsive Persistent Chrome Contract

WIDE WINDOW
[Identity + Project] [Status] [CPU] [Master] [Time] [Beat] [Pulse] [Tempo] [Settings] [Chord] [About] [Max] [-]
[Page tabs share remaining width]                         [Multi-Out] [Reset] [Panic] [Undo] [Redo]

COMPACT WINDOW
[Identity + Project]                                             [Settings] [Chord] [About] [Max] [-]
[Status]                          [CPU] [Master] [Time] [Beat] [Pulse] [Tempo]
[Page tabs share remaining width]                         [Multi-Out] [Reset] [Panic] [Undo] [Redo]

Rules:

1. Session and safety actions reserve space before descriptive text.
2. Page actions reserve space before tab widths are calculated.
3. Controls may reflow but may not overlap, disappear, or fall below tested target sizes.
4. Keyboard order mirrors the visible hierarchy.
5. Any persistent-chrome height change triggers neighboring workspace regressions. Synth-page consequence:

available page rectangle
    -> subtract required headers/displays
    -> choose columns from remaining height and control count
    -> verify label + value control minimums
    -> never let a fixed minimum row height push the final row outside the page

2026-08-10 - MIDI Health Command Hierarchy

MIDI HEALTH

[ FIX NEXT ] [ CHECK HEALTH ] [ QA RECEIPT ] [ COPY LEDGER ] [ COPY QA ]
[ COPY CLAIM ] [ COPY PROOF ] [ COPY LAUNCH ] [ COPY STEPS ] [ COPY REPORT ]

[ release-critical cockpit rows remain visible ]
[ complete diagnostic evidence continues vertically ]
[ repair recommendations and warnings ]

Rules:

1. Immediate action and proof capture precede supporting copy/export actions.
2. Visual order and keyboard order must agree.
3. Minimum-display width must not require horizontal scrolling.
4. Diagnostic depth may scroll vertically; critical launch rows remain at the top.
5. Reorganizing the cockpit must remain behaviorally cold until the musician explicitly chooses an action.

2026-08-10 - MIDI Hardware Setup Guide Command Hierarchy

MIDI HARDWARE SETUP GUIDE
|
+-- Row 1: NEXT ACTION | MIDI INPUT | MIDI OUT | HARDWARE | TIMING
|
+-- Row 2: HEALTH | MIDI PATCH | SYSEX | AUTOMATION | COPY SESSION
|
+-- Scenario cards and selected workflow
|
+-- Device template | target lane | APPLY DRAFT | TEST NOTE | UNDO | COPY PREVIEW
|
+-- Evidence and safety explanation

Rules:

• Navigation and cold-copy commands must read as a map, not a compressed ribbon.
• Visible row order and keyboard order must agree.
• The deck must fit the supported 1100-pixel display without horizontal scrolling.
• Warm/hot template and hardware actions remain separate from the navigation deck and retain confirmation.
• Vertical scrolling is acceptable for deep evidence; horizontal scanning is not.

2026-08-10 - At-A-Glance Orientation And Feedback

Persistent header
|
+-- Product identity
|
+-- Current project and immediate status receipt
|
+-- Transport and global safety
|
+-- Settings | live chord/note readout | About
|
+-- Standalone only: MIN | MAX or RESTORE

Rules:

• Persistent chrome must answer where the user is, what just happened, and what global action is available.
• Compact layout may fit text, but it must never silently discard the complete status or musical spelling; tooltip and accessibility text retain the full value.
• Hosted plug-ins must not imitate control over a DAW-owned window.
• MAX must become RESTORE while the standalone window is expanded.
• Responsive typography must preserve the visual importance of the primary workspaces without consuming additional editor height.

2026-08-10 - Musical Location Must Remain Legible

Project identity
|
+-- Primary workspace
    |
    +-- Current clip or pattern
        |
        +-- Loop-bank state
        |
        +-- Step Input state

Rules:

• A musician must be able to recover the complete project and editing identity even when the visible row is compact.
• Informational context expands into unused row space but does not enter keyboard traversal.
• Decoration remains below control surfaces and interaction feedback.
• Motion may enrich a page, but it cannot obscure hover, focus, borders, labels, or action cues.
• Responsive changes must preserve workstation height and transport placement.

2026-08-10 - Honest Instrument Creation And State Receipts

+ ADD LANE
|
+-- DRUM LANE
|
+-- INSTRUMENT LANE
    |
    +-- Ready To Play
    |   +-- create lane-owned Instrument and starter clip
    |
    +-- Load Your Source After Adding
        +-- SoundFont -> create -> open Instrument -> load SF2
        +-- Quasar -> create -> open Instrument -> load package

Selected Instrument lane
|
+-- Choose/replace Instrument
    +-- uses the same authoritative engine list

Synth editor
|
+-- PATCH | name
    +-- wide: established header row
    +-- compact: readable full-width receipt row
    +-- complete saved/modified identity in accessibility metadata

Mixer strip
|
+-- meter animation
+-- readable dB receipt using available strip width

Rules:

• Creation and reassignment must never advertise different Instrument inventories.
• Source-backed Instruments remain valid choices, but readiness and next action must be explicit before and after creation.
• Patch and level receipts must remain readable when controls reflow.
• These presentation changes must not mutate lane ownership, Mixer routing, MIDI, transport, or DSP.

2026-08-10 - First-Song Orientation Inside About

ABOUT
|
+-- START SONG GUIDE
|   |
|   +-- 1 BEGIN: load/recover/blank
|   +-- 2 ADD A LANE: Instrument or Drum
|   +-- 3 PLACE A CLIP: selected lane plus playhead
|   +-- 4 WRITE: Piano Roll, Drum Composer, or Chord Engine
|   +-- 5 ARRANGE: clips beneath Section markers
|   +-- 6 MIX, SAVE, RENDER
|   |
|   +-- BACK TO ABOUT
|
+-- WEBSITE
+-- X or Escape: return to workspace

Rules:

• About artwork is not an invisible web link; every departure is an explicit labeled action.
• The guide names production controls exactly and must change when those controls change.
• The guide explains the lane-owned Instrument model and Mixer-owned processing model without exposing implementation terms.
• It must remain readable and keyboard dismissible at the supported compact viewport.

2026-08-10 - Truthful Startup Destinations

START A SPACEAGE SESSION
|
+-- RECOVER LATEST SESSION -> newest usable recovery
+-- LOAD LAST PROJECT -> remembered project path
+-- LOAD PROJECT FILE -> file chooser
+-- LOAD BLANK PROJECT -> clean session
+-- BROWSE STARTING POINTS
    |
    +-- Library / STARTING POINTS
        +-- ready-made kits
        +-- ready-made Instruments
        +-- future complete-project templates only after they are real

Rules:

• Every enabled startup choice must finish a real customer task.
• A future feature must not occupy a first-run action with COMING SOON behavior.
• The destination must explain the next action and put keyboard focus on a usable control.
• Starting Points and full-project templates may share Library infrastructure, but their customer promises remain distinct.

2026-08-10 - Arrangement Lane Command Truth

LANE BADGE
|
+-- L / STRUCTURE
|   +-- Rename Lane
|   +-- Use As Add Clip Target / Target On
|   +-- Full Lane View
|
+-- S / SIGNAL + MIDI
|   +-- Automation (CC / Bend / Pressure)
|   +-- MIDI Routing
|   +-- Arm / Disarm MIDI Input
|   +-- Choose Instrument
|   +-- Lane Routing / Passport
|
+-- V / VIEW
    +-- Full Lane View

Rules:

• A working menu contains working commands, not roadmap advertisements.
• Future lane order, persistent collapse, color, ghost, and clip-detail commands return only with behavior, persistence, Undo, accessibility, and tests.
• The tooltip, title, menu contents, status receipt, and keyboard shortcut must describe the same capability.

2026-08-10 - Library Starting Point Identity

LIBRARY / STARTING POINTS
|
+-- CHROMATIC MARIMBA
|   +-- physical-model tuned-bar bank
|   +-- chromatic notes across the Pad bank
|
+-- STACCATO BASS
    +-- physical-model bass bank
    +-- chromatic notes across the Pad bank

Rule: customer label, production callback, underlying engine/model, metadata, and auditioned result must identify the same sound family.

2026-08-10 - Build Diagnostic Signal

SOURCE CHANGE
    |
    +-- compiler diagnostics
    |      +-- first-party warning => investigate or remove
    |      +-- third-party warning => document and isolate
    |
    +-- focused owner test
    |
    +-- neighboring workflow test
    |
    +-- broad closeout gate

Rule: do not normalize new first-party warnings. Clear diagnostics make subsequent beta fixes faster and safer for both human and AI maintainers.

2026-08-11 - Arrangement Form Boundary

FORM PRESET + APPLY FORM
|
+-- replaces Section markers
|   +-- exact type
|   +-- exact start
|   +-- exact length
|
+-- does not move or rewrite
|   +-- Drum clips
|   +-- Instrument clips
|   +-- notes / chords / automation
|   +-- lane Instruments / Mixer routes
|
+-- one Undo restores prior Section map
+-- save/reopen preserves both map and music

Rule: a Song Form is visual/compositional scaffolding. Any future command that deliberately moves music with a form must be separately named, confirmed, and implemented as its own transaction.

2026-08-11 - Library Starting Point Boundary

VISIBLE STARTING POINT BUTTON
|
+-- production callback
|   +-- expected configured scope (16 or 64 pads)
|   +-- customer-readable labels
|   +-- intended synthesis family
|   +-- finite core parameters
|
+-- representative audition
|   +-- non-silent output
|   +-- finite samples
|   +-- Panic before next collection
|
+-- human listening review
    +-- musical usefulness
    +-- loudness consistency
    +-- name matches character

Rule: layout evidence cannot prove a sound bank works. Every visible Starting Point requires both a production-callback audio contract and a human musical review.

2026-08-11 - Launch Proof Boundary

CURRENT SOURCE
|
+-- development / Release build
|   +-- normalize generated VST3 metadata
|   +-- validate strict JSON
|
+-- named convergence
|   +-- standalone launch
|   +-- VST3 inventory + host smoke
|   +-- 79/79 product contracts
|
+-- complete broad self-test
|   +-- isolated audio fixtures
|   +-- legacy cross-system regression coverage
|
+-- release ledger
    +-- automated evidence attached
    +-- human/device/listening receipts still required
    +-- legal + asset clearance still required
    +-- installer + clean-machine proof still required

Rule: green automation proves that the current source satisfies the encoded contracts. Shipping requires that proof plus the independent human, hardware, legal, packaging, and clean-machine evidence named by the fixed release ledger.