# Roadmap ## Phase 0 — Baseline Inspect repository/toolchain, verify Makefile and minimal executable, document dependencies. No system changes without permission. Baseline implementation: headless startup/shutdown executable, core tests, separate debug build, optional FLTK shell build, and header dependencies. See [BUILD.md](BUILD.md) for toolchain, commands, licensing and limitations. ## Phase 1 — C core and offline processing Graph data structures, validation, cycle detection, topological ordering, preallocated buffers, test oscillator, gain and offline render tests. Implemented: mono ports, transactional cycle rejection, independent compiled plans, precomputed input routing, oscillator/gain/meter/output, deterministic variable-block tests and lifecycle/error coverage. See AUDIO_ENGINE.md for API limits and compatibility behavior. ## Phase 2 — Real-time backend Choose and implement a Linux backend. Document callback semantics, start/stop, device errors, shutdown, and safe graph publication. Implemented: optional JACK-compatible mono backend, explicit audio port routing, format/xrun/loss status, start/stop/reopen, and bounded pending/retired plan handoff using lock-free atomics. Hardware-independent failure/concurrency tests and a 30-second software-loopback run pass. See decision 0004 and AUDIO_ENGINE.md. Physical hardware playback/endurance and live server-loss recovery remain unverified; GUI engine controls are implemented in Phase 3. ## Phase 3 — FLTK shell Main window, transport controls, view switching, backend status, clean startup and shutdown through the C API. Implemented: dark FLTK shell, Play/Stop/Reconnect, view/menu shortcuts, backend state/format/xrun/process status, persistent command errors, timer-based refresh and retirement collection, and callback-safe close/retry. Mock-backend GUI tests and live GUI/JACK start/stop/reconnect/close tests pass under Xvfb. Sequencer, mixer and project-file actions remain placeholders; initial graph is silent. See GUI.md. ## Phase 4 — Modular editor Draw nodes/ports/edges; create, move and connect nodes; reject invalid edges; safely submit edits to the C core. Implemented: scrollable node/port/wire canvas; add/select/move/delete nodes; drag connections, select/delete wires, and show invalid-edit feedback. C owns stable IDs, read-only snapshots and transactional edits. Exact accepted graph snapshots are submitted to the backend; prepared/queued/active state is exposed through revision acknowledgements. Core/render, GUI rollback, mouse smoke and live adoption tests pass. See GUI.md and AUDIO_ENGINE.md. Preset parameters, mono-only processing, fixed canvas and no persistence/undo/zoom remain limits. ## Phase 5 — Project and sequencer Versioned persistence, stable IDs, tracks, clips, timeline, selection, zoom, scrolling, and transport synchronization. Implemented: bounded version-1 project persistence with transactional loads and temporary-file/fsync/rename saves; stable track/clip/node IDs; silent regions; track and region creation/deletion, selection, move/trim, timeline zoom/scroll; sample-counted playhead, pause/resume and stopped seek. Project/graph arrangement roundtrips, malformed-input, GUI rollback/gesture and live transport tests pass. See PROJECT_FORMAT.md and GUI.md. Constant tempo/4/4, silent metadata regions, no undo, asset playback, MIDI or persisted GUI layout are explicit limits. ## Phase 6 — Audio clips and recording Audio import/playback, recording through bounded buffers, missing-asset handling, no file I/O in callbacks. Implemented: bounded PCM16/24/32 and float32 WAV import (mono/stereo downmix), preloaded overlap-summed clip plans with linear rate conversion, and an audio source node using ordinary graph routing. A lock-free SPSC ring transfers JACK input to a control-thread WAV writer; Stop finalizes and adds successful takes. Version 2 metadata stores external asset references and reads v1. Missing assets remain silent with reporting and manual relinking. Core, callback, GUI and live software record/save/reopen/play acceptance tests pass. See AUDIO_FILES.md for memory/format limits, overflow recovery and deferred physical-device validation. No new dependency or callback I/O was introduced. ## Phase 7 — MIDI and instrument MIDI input/events/clips, simple internal instrument, note-off/panic handling, then a basic piano roll. Implemented: bounded source-relative note events with stable IDs; sample-offset JACK MIDI input; a velocity-scaled sine instrument and separate graph source; panic, note-off, stop and seek handling; and a piano roll for drawing, moving, resizing and deleting notes. Version 3 saves notes and reads v1/v2 projects. Core, fault-injection, GUI and live software MIDI/save/reopen/play tests pass. Acceptance uses drawn notes; MIDI recording and SMF import are deferred. See MIDI.md for capacities, immediate note-off, routing and hardware limits. ## Phase 8 — Mixer and editing Gain/pan, meters, mute/solo, automation, undo/redo, keyboard workflow. Implemented: selectable per-track channel strips with gain/pan and mute/solo; stereo graph/JACK output and output peak meters; editable gain/pan automation lanes with sample interpolation; bounded 32-edit C snapshot undo/redo and mixer keyboard controls. Format v4 persists mixing/automation and reads v1–v3. Core, GUI rollback/gesture/history and live stereo software playback tests pass. See MIXER.md for routing, mono compatibility, pan law, history behavior and limits. Track inserts/sends, live fader adoption, MIDI capture, per-track meters and advanced automation remain deferred. No project-file editing is needed for the implemented composition/mixing workflow. ## Phase 9 — Extensibility and release Native node API, evaluate plugin hosting, licensing review, packaging, installation tests, performance and recovery tests. Implemented: versioned native C processor lifecycle and graph source/effect API, explicit instrument-buffer integration, example and error/retirement tests; external-hosting evaluation (deferred); dependency/license review; deterministic source/release targets; core/GUI staged install/uninstall and installed C/C++ consumer tests; headless version/help/metadata validation; offline performance and process-crash/write-failure recovery tests. Source format stays v4, reading v1–v3. See NATIVE_API.md, RELEASING.md, LINUX.md, LICENSES.md, PERFORMANCE.md and RECOVERY.md. Native graphs remain session-only, with unsupported saves preserving files. No stable binary plugin ABI, external host, system package, autosave or physical-device/endurance qualification is claimed. ## Phase 10 — Engine Correctness and Reliability **Goal:** Verify that the existing implementation behaves correctly under realistic workloads before adding more features. ### Tasks - Audit graph compilation, topological ordering, port compatibility, and cycle detection. - Test graph replacement while audio is running, including safe reclamation of old processing graphs. - Verify that audio-thread operations are bounded and non-blocking. - Test repeated initialization, start/stop cycles, device failures, shutdown, and partial initialization. - Run AddressSanitizer, UndefinedBehaviorSanitizer, leak checks, and static analysis where available. - Add regression tests for every bug discovered. - Document known limitations and thread ownership for shared resources. ### Acceptance criteria - Reproducible tests cover engine lifecycle, graph changes, error handling, and DSP output. - No known critical real-time safety defects remain. - Resource ownership and cleanup behavior are documented. Implemented: graph/DSP and ownership audit; stereo source-alias correction with exact-output regression tests; maximum-size reverse-order graph/cycle rollback; allocation-failure sweeps and callback allocation/free guards; 2000 concurrent native-plan replacements with control-thread destruction and balanced lifetimes; repeatable ASan/UBSan/leak and Clang static-analysis targets. Core, no-JACK, GUI/mock/live JACK, recovery and TSan publication/recorder tests pass. See RELIABILITY.md for ownership, synchronization, bounded-work analysis, commands and evidence. Physical-device/endurance validation and trusted native callback behavior remain explicit limits; no critical realtime safety defect is known within the documented contracts. ## Phase 11 — Complete Minimal Music-Making Workflow **Goal:** Ensure a user can create, save, reopen, and play a small musical project without manually editing project files. ### Tasks - Verify project creation, track creation, clip arrangement, routing, and transport as one integrated workflow. - Ensure play, pause, stop, seek, and return-to-start behavior are consistent. - Save, close, reopen, and continue editing projects. - Provide useful defaults and actionable error messages. - Keep the sequencer as the default workspace, with the modular graph available when needed. - Test that GUI state and engine state remain synchronized. ### Acceptance criteria - A user can create and reopen a small project and reproduce the same arrangement and routing. - Common operations do not require manual project-file edits. - Transport and GUI state remain consistent during normal playback and error conditions. Implemented: explicit Pause/F7 and To start/Home controls, position-preserving Stop compatibility, recording guards, sequencer selection on New/Open, first-use composition/routing guidance, and GUI status refresh after failed installation. A real GUI/backend workflow test creates MIDI and audio, arranges/routes, saves, closes/destroys the window, reopens in a fresh window, compares exact stereo rendering and stable clip/routing metadata, then plays/seeks/pauses/resumes, continues editing with undo/redo and saves/reopens again. Mock failure tests and live JACK/GUI/software MIDI tests pass. See WORKFLOW.md for instructions, transport semantics, test commands and limits. External playback routing remains explicit; physical-device listening and endurance remain unqualified. ## Phase 12 — Audio Quality and Transport Correctness **Goal:** Make timing and audio output predictable and musically reliable. ### Tasks - Define precise behavior for tempo and meter changes. - Verify conversion between musical positions and sample positions without accumulated timing drift. - Test clips and events that cross processing-block boundaries. - Prevent clicks at clip boundaries and during playback start/stop where appropriate. - Implement gain ramps and parameter smoothing where abrupt changes could create artifacts. - Test silence, clipping, denormal values, channel layouts, and unusual supported buffer sizes. - Document latency reporting and identify whether latency compensation is required by the current architecture. - Add deterministic tests for sample-accurate event scheduling where supported. ### Acceptance criteria - Automated tests verify timing conversions and expected sample output. - Tests cover events and clips at block boundaries and tempo changes. - Listening tests cover transitions, start/stop behavior, and representative projects. - Known limitations involving latency and synchronization are documented. Implemented: documented constant-tempo/fixed-4/4 snapshot policy; absolute timing and sample-offset regression matrix; configurable audio/scheduled-note boundary fades; single-owner gain ramps; GUI 5 ms start and asynchronous Pause/Stop fades with control-thread acknowledgement/deactivation; finite/subnormal output policy; exact endpoint, block-size, stereo, overload and failure/retry tests. Latency and synchronization limits are documented in AUDIO_QUALITY.md. Normal/no-JACK, sanitizer/static-analysis, TSan, GUI/workflow/live JACK and install checks pass. `make quality-preview` generates matched listening WAVs. Human listening and physical-device acceptance remain pending; immediate safety/recording/seek paths and live graph swaps may still click. No tempo/meter map, latency compensation, limiter or project-format change is claimed. ## Phase 13 — Recording and Recovery **Goal:** Protect recorded material and handle recording failures predictably. ### Tasks - Test long recordings and recording-buffer saturation. - Handle disk-full conditions, write errors, interrupted recording, and unavailable destinations. - Keep file I/O outside the real-time audio callback. - Define and implement recovery or clear reporting for incomplete recordings. - Make recording destinations and supported file formats explicit. - Protect existing files from accidental overwrites. - Test reopening projects when media files are missing, incomplete, or inaccessible. - Ensure shutdown and project closure do not silently discard pending recorded data. ### Acceptance criteria - Recording failures are reported clearly and do not cause unsafe audio-thread behavior. - Valid recorded material is preserved whenever possible. - Incomplete recordings and missing media are detected and explained. - Recording and recovery behavior is covered by automated or repeatable integration tests. Implemented: no-clobber recording destinations and race-safe publication; explicit opt-in replacement API; retained failed temporaries and recovery-path reporting; streaming `xtc-check --recover-recording TEMP NEW.wav` salvage; quiescent destructor draining and exceptional-shutdown reporting. Virtual 30-minute recording, saturation/concurrency, destination races, disk-write failure/prefix recovery, killed writers and missing/incomplete media tests pass. See AUDIO_FILES.md and RECOVERY.md. Physical endurance, power-loss guarantees and playback of assets above the existing preload limit remain unqualified. ## Phase 14 — Native Plugin, Instrument, and Effect Architecture **Goal:** Provide a stable internal extension interface before hosting external plugins. ### Tasks - Finalize the native C node API, including initialization, processing, reset, and destruction. - Define parameter metadata, defaults, valid ranges, and automation behavior. - Specify audio channel layouts and MIDI/event handling. - Define node state serialization and restoration requirements. - Establish rules for node creation, failure, reconfiguration, and destruction. - Ensure the GUI uses documented public APIs rather than internal engine structures. - Provide a small example instrument and effect implemented against the public interface. - Document ABI/API compatibility expectations for native extensions. ### Acceptance criteria - A developer can implement a small native instrument or effect using documented interfaces. - Invalid parameters, unsupported layouts, and failed initialization are handled safely. - Node state can be saved and restored where required. - No C++ or FLTK types leak into the public C API. Implemented: ABI 2 parameter-only C processor lifecycle with copied descriptors, metadata/default/range validation, sample-offset parameter/MIDI ordering, transactional portable configuration restoration, and public gain/instrument examples. Lifecycle, invalid input, event ordering, in-place output, reset, callback failure and state compatibility tests pass. See NATIVE_API.md. ABI 1 graph compatibility is retained; native graph persistence and opaque plugin state are explicitly outside this parameter-only interface. ## Phase 15 — External Plugin Hosting **Goal:** Add external plugin support only after the internal node lifecycle is reliable. ### Tasks - Evaluate candidate plugin formats for licensing, dependencies, maintenance, and Linux support. - Record the selected format and rationale in an architecture decision document. - Implement plugin discovery and loading outside the real-time callback. - Map plugin audio ports, parameters, MIDI/events, and channel layouts to the engine's node model. - Support plugin state save/load and clear reporting for missing or incompatible plugins. - Test plugins with different channel counts, parameter sets, and processing requirements. - Define how plugin failures are reported and how the engine recovers. - Document crash-isolation limitations; an in-process plugin must not be assumed safe merely because the host is safe. ### Acceptance criteria - A small, documented set of compatible third-party plugins can be loaded, connected, saved, reopened, and played. - Missing or incompatible plugins do not silently corrupt the project. - Plugin loading and destruction do not occur in the real-time callback. - The chosen format's dependencies and licensing are documented. Implemented: bounded LADSPA 1.1 C host with explicit file/index discovery, control-thread loading/lifecycle, mono source/effect graph mapping, independent stereo instances, metadata/range checks and v5 identity/control persistence. Public-API GUI load/configure commands support ordinary routing/save/reopen and undo. Fixture/error/retirement/GUI tests and installed amp/inverter/sine acceptance pass. See decision 0009, PLUGIN_HOSTING.md and LICENSES.md. MIDI, true multichannel layouts, opaque state, editors, latency compensation and crash isolation are unsupported; plugin realtime behavior and physical listening are unqualified. ## Phase 16 — Automation and Expressive Control **Goal:** Make automation and MIDI control reliable, sample-timed, and usable. ### Tasks - Support automation for common parameters such as volume, pan, instrument parameters, and effect parameters. - Define interpolation modes and behavior at clip boundaries. - Evaluate automation at the correct time and sample offsets for each processing block. - Smooth parameter changes where needed to avoid zipper noise or audio artifacts. - Add MIDI controller mapping where appropriate. - Handle note-off, panic, seek, stop, project teardown, and device disconnect correctly. - Define deterministic ordering for MIDI and automation events that occur at the same sample position. - Test overlapping notes, repeated note-ons, and interrupted playback. ### Acceptance criteria - Automation and MIDI control reproduce consistent results across repeated playback and project reloads. - Held notes are released safely on stop, panic, seek, and relevant failure paths. - Event ordering and interpolation behavior are documented and tested. Implemented: persisted sample-evaluated LADSPA parameter lanes with linear/step modes, range/discrete validation and public GUI editing; absolute automation position through seek and plan handoff; fixed live CC7/10/64 mappings with volume/ pan ramps, sustain/retrigger safety, and exact block-partition regressions. Existing track Gain/Pan lanes cover audio and scheduled instrument volume. Format v6 migrates v1–v5. See CONTROL.md. MIDI capture/learn, pitch bend, new instrument timbres and physical listening remain outside the supported scope. ## Phase 17 — Editing Workflow, Undo/Redo, and Usability **Goal:** Make common editing tasks efficient and protect users from accidental changes. ### Tasks - Make common operations undoable, including create, delete, move, trim, duplicate, and connect. - Define undo behavior for recording and destructive operations. - Add consistent keyboard shortcuts and context menus for frequently used actions. - Implement predictable snapping, grid settings, zoom, scrolling, and selection behavior. - Improve clip labels, track organization, and visual feedback. - Make destructive actions difficult to trigger accidentally. - Keep the GUI responsive while audio is running. - Ensure undo/redo updates project state and the active engine graph consistently. - Test keyboard focus and accessibility of essential controls where practical. ### Acceptance criteria - Common editing workflows can be completed without unnecessary dialogs or manual workarounds. - Undo/redo restores the intended project state and corresponding engine state. - GUI operations do not block the real-time audio thread. - Interaction behavior is documented and covered by relevant tests. Implemented: transactional full-source clip duplication, clip/track names, track ordering, configurable timeline snap, Ctrl+D/F2/Alt+arrow commands and a context menu; kind/name clip labels and focus regressions. Snapshot/GUI tests verify duplicate/rename/order undo/redo, source-note retention, capacity rollback and existing graph/backend history behavior. Recording undo removes references, never media. See WORKFLOW.md. Background loading, persisted UI layout and broad screen-reader/accessibility qualification remain explicit limits. ## Phase 18 — Project Format, Compatibility, and Portability **Goal:** Keep project files valid, recoverable, and maintainable over time. ### Tasks - Version the project format and implement explicit migration logic when the format changes. - Validate project data before constructing engine objects from it. - Handle malformed files, unknown node types, missing assets, and unavailable plugins. - Define project-folder behavior and reliable media path handling. - Make saving robust against interrupted writes, for example by writing a temporary file and replacing the destination safely where supported. - Test save/load round trips and migration from every format version that is supported. - Keep the format documented and preferably human-inspectable. - Avoid silently discarding unknown data during load/save unless the format policy explicitly requires it. ### Acceptance criteria - Supported older projects load correctly or produce clear, actionable compatibility errors. - Malformed project files do not crash the application or trigger unsafe allocations. - Missing media and plugins are reported clearly. - Save/load round trips and format migrations have automated tests. Implemented: v7 folder-relative media persistence with absolute runtime references, transactional resolution independent of launch cwd, Save As identity preservation, and parent-directory fsync after atomic publication. Checked-in v1–v6 migrations (including missing plugins), moved-folder exact playback, missing-media retention, truncation/mutation and unknown-record/error tests pass. See PROJECT_FORMAT.md. No media is copied/deleted automatically; absolute external/plugin dependencies, path bounds, post-rename sync errors and physical power-loss limits are explicit. ## Phase 19 — Performance, Scalability, and Stress Testing **Goal:** Measure performance and establish predictable behavior as projects grow. ### Tasks - Create repeatable benchmarks for increasing node counts and audio channel counts. - Measure processing time at supported sample rates and block sizes. - Profile graph compilation separately from real-time audio processing. - Identify unnecessary buffer copies, allocations, and redundant processing. - Test large arrangements, many clips, automation events, and active meters. - Define bounded processing limits and meaningful overload diagnostics. - Test under CPU pressure and during frequent GUI redraws. - Optimize only after profiling identifies a meaningful bottleneck. - Record baseline benchmark results so regressions can be detected. ### Acceptance criteria - Performance targets and test conditions are documented. - Repeatable benchmarks cover representative small and large projects. - Overload behavior is defined and does not cause unbounded work in the callback. - Significant performance regressions can be detected through repeatable tests. Implemented: 24-case node/channel/rate/block matrix with separate compilation and warmed process timings, recorded machine/compiler baseline and opt-in regression budgets; maximum track/clip/note/automation/meter capacity checks and publication/GUI tests under CPU contention. Measurements justified skipping unused live-controller processing; exact output tests remain passing. See PERFORMANCE.md and performance-baseline.json for results, thresholds and overload policy. Arbitrary plugin costs and physical realtime/endurance are unqualified. ## Phase 20 — Release Engineering, Packaging, and Maintenance **Goal:** Make the application straightforward to build, install, use, diagnose, and maintain. ### Tasks - Provide reproducible release builds and clean build instructions. - Add Makefile targets for building, testing, installing, and uninstalling. - Package the application and required resources for the initial supported Linux target. - Review licenses and attribution for direct and bundled dependencies. - Document supported audio backends, required system packages, and configuration. - Add useful crash and error diagnostics without compromising real-time processing. - Test fresh installations, upgrades, missing dependencies, and removal. - Publish a basic user manual, developer documentation, and a known-limitations list. - Define a release checklist and a policy for handling regressions and project-format compatibility. ### Acceptance criteria - A person other than the primary developer can build or install the application using the documented steps. - The installed application can complete the supported core workflow. - Installation and removal are tested on the initial target environment. - Dependencies, licensing, limitations, and troubleshooting steps are documented. - A release can be reproduced from a clean checkout with recorded build instructions. Implemented: normalized Linux binary/development archives with SHA-256/file/ ELF-dependency manifests, headless compiled-feature diagnostics, repeat-install upgrade/repair and installed C/C++ save/reopen/render checks. Existing deterministic source/release, no-dependency, sanitizer, staged uninstall and GUI/live tests are retained. USER_MANUAL.md, KNOWN_LIMITATIONS.md and MAINTENANCE.md consolidate setup, operation, licensing/diagnostics, release and regression policy. No public release or distro registration is performed. Independent human installation/usability, physical-device/endurance and listening acceptance remain pending and must be completed before claiming production qualification. ## Phase 21 — Advanced MIDI and Composition ### Goal Make MIDI composition expressive and efficient without turning the application into an unnecessarily complicated notation editor. ### Tasks - Improve piano-roll editing for note creation, selection, movement, resizing, and deletion. - Support configurable snap and grid resolution, including triplets where practical. - Add velocity editing and editing for supported MIDI note properties. - Support MIDI channel and note-range filtering where appropriate. - Improve quantization, transposition, duplication, and pattern repetition. - Ensure MIDI event ordering is deterministic, especially when note-off and note-on events share a timestamp. - Define handling for overlapping notes, repeated notes, and malformed MIDI events. - Add regression tests for MIDI editing and playback scheduling. ### Acceptance criteria - Common MIDI editing tasks can be completed without manually editing project files. - Editing preserves unrelated notes and event properties. - MIDI scheduling remains deterministic at buffer boundaries and under transport changes. - MIDI operations are covered by automated tests. Implemented: transactional C filtered note transforms, nearest-grid quantization, velocity/channel edits, transposition, bounded fresh-ID repetition and deletion; piano-roll Notes menu, keyboard commands, configurable straight/triplet grids, channel/pitch filtering and filtered-set selection. Existing mouse move/resize and project undo/redo remain supported. Core and GUI regression tests demonstrate property/other-clip preservation, rollback, undo/redo, adjacent/overlapping notes, equal-offset caller ordering, exact block partitions and seek chase. See MIDI.md. No format change, MIDI capture, SMF import, lasso selection or piano-roll zoom; physical-device and listening validation remain pending. Acceptance evidence: - [x] Menu/keyboard/mouse commands edit notes without project-file editing. - [x] Filtered batch tests preserve unmatched notes and unrelated properties. - [x] Exact scheduling tests cover buffer boundaries and transport seeks. - [x] Core composition and GUI undo/redo regressions exercise these operations. ## Phase 22 — Audio Clip Editing and Utility Operations ### Goal Provide focused, non-destructive audio editing tools for arranging and preparing recorded or imported material. ### Tasks - Support moving, trimming, splitting, duplicating, and deleting audio clips. - Define clip-boundary behavior, including fades and source offsets. - Add non-destructive clip gain and basic fade-in/fade-out controls. - Support time-stretching and pitch-shifting only after selecting a suitable implementation and quality target; otherwise document them as future work. - Ensure edits do not unexpectedly modify source audio files. - Add waveform display caching that never blocks the audio thread. - Test edits at project boundaries, source-file boundaries, and very short clip lengths. - Document which operations are destructive and non-destructive. ### Acceptance criteria - Basic clip editing is predictable and undoable. - Source files remain unchanged unless a documented destructive operation is explicitly invoked. - Clip boundaries do not produce unintended clicks from invalid offsets or discontinuities. - Editing and waveform generation never perform blocking work in the real-time audio callback. Implemented: transactional audio/silent-clip splitting with stable IDs and source offsets; persisted linear clip gain and explicit in/out fades in v8 (v1–v7 migrate to unity/no explicit fades); undoable sequencer menu/context/keyboard controls; immutable bounded source-peak summaries shared across clips and drawn from cached memory. Existing move/trim/duplicate/delete remain supported; very short clip hit testing now matches drawing. See AUDIO_FILES.md and PROJECT_FORMAT.md. Stretch/pitch processing and crossfades remain future work; waveform loading is synchronous on the control thread, and physical listening remains pending. Acceptance evidence: - [x] Core/GUI regressions cover split/duplicate/delete and snapshot undo. - [x] Exact byte comparison verifies source files survive all metadata edits. - [x] Boundary tests cover invalid offsets, short tails, one-frame media, explicit fade endpoints, gain, block partitions, seeks and capacity rollback. - [x] Waveform construction stays on control-thread paths; redraw reads cached peaks and audio rendering retains immutable/preloaded callback storage. ## Phase 23 — Modular Workflow and Routing Refinement ### Goal Preserve the modular spirit of the application while making complex projects understandable and manageable. ### Tasks - Refine graph and routing views so signal paths are easy to inspect. - Make connections, disconnections, and invalid routing states clear. - Provide useful names and visual distinctions for tracks, instruments, effects, buses, and I/O ports. - Support track grouping or folders if the project model can represent them cleanly. - Add routing presets or reusable track templates only if they do not complicate the core model. - Define behavior for cycles and feedback paths; reject unsupported cycles explicitly. - Make graph changes transactional so failed edits do not leave partially updated routing. - Add tests for graph changes while playback is running. ### Acceptance criteria - Users can inspect and understand a project's signal path. - Invalid graph edits fail safely and leave the previous valid graph intact. - Graph updates follow the documented real-time synchronization strategy. - GUI routing concepts map cleanly to the public C engine API. Implemented: cached public C routing analysis (edge counts, longest-path levels, output reachability and external-input fallback); directional/highlighted wires, role colors/labels, no-output badges, selection inspection and keyboard navigation; scrollable signal-flow auto-layout and non-overlapping initial placement. Atomic unity-gain wire insertion is one undoable C edit using existing node persistence. Core and mock/live GUI tests cover rollback, complete plan adoption, cycles, disconnect/restore and undo/redo. See ROUTING.md. Flat tracks/shared audio/MIDI sources do not yet represent folders or per-track routing templates; these conditional tasks are deferred. No format change, feedback processing, latency compensation or physical listening qualification is claimed. Acceptance evidence: - [x] Direction/role labels, layout and public routing diagnostics expose paths. - [x] Invalid/capacity/backend-failed commands retain the previous graph/plan. - [x] Live JACK graph tests verify complete block-boundary plan adoption. - [x] GUI routing analysis and edits use public C APIs; callback ownership is unchanged. ## Phase 24 — Mixing and Mastering Essentials ### Goal Provide the essential mixing controls needed to finish a small or medium-sized project. ### Tasks - Complete track and bus gain, pan, mute, solo, and metering behavior. - Define how solo states affect buses, sends, and sidechains. - Add peak meters with clear units and documented ballistics. - Add master-bus monitoring and clipping indicators. - Support routing to buses and auxiliary sends if the graph model supports them. - Make gain staging explicit and avoid hidden or surprising level changes. - Document meter tap points and whether values are pre-fader, post-fader, or post-effects. - Test mute, solo, pan, gain, and routing interactions. ### Acceptance criteria - [x] Mixer controls behave consistently across tracks, buses, and master output. - [x] Meter readings correspond to documented signal points and units. - [x] Solo and mute behavior is covered by automated tests. - [x] No mixer operation introduces allocations, locks, or other prohibited work in the audio callback. Implemented: one-level stereo mix buses with routing, shared gain/pan automation, inclusive solo and mute precedence; coherent audio/MIDI track and bus peaks; interval master peaks, dBFS ballistics and sticky clipping; v9 persistence reading v1–v8. See MIXER.md for exact taps, gain staging and callback scratch bounds. Independent per-track aux sends/sidechains and per-bus graph effects remain conditional/deferred because graph sources still expose shared mixes. Validation: warning-enabled core/GUI builds and unit/integration tests, bus and backend fault tests, GUI plugin/workflow tests, software JACK GUI/audio/MIDI, allocation-failure/callback-allocation guard, static analysis, installation and package relocation, optional-dependency-free build, and core/GUI ASan+UBSan. The live MIDI connection test required one retry after a JACK connection failure; its full playback assertions passed on retry. GUI leak checks use the existing fontconfig suppression; core checks are unsuppressed. Physical hardware, human listening and extended high-density endurance remain unverified. ## Phase 25 — Plugin and Instrument Usability ### Goal Make instruments and effects practical to use, manage, and diagnose in real projects. ### Tasks - Improve plugin discovery, insertion, removal, replacement, and ordering. - Show useful plugin identity and status information, including load failures. - Define parameter metadata, ranges, defaults, units, and formatting. - Support parameter reset and safe default values. - Preserve plugin state across save/load where the plugin API supports it. - Define behavior when a saved plugin is missing or incompatible. - Manage plugin UI lifetime separately from engine object lifetime. - Add tests for plugin lifecycle, state restoration, and failure paths. - Document plugin API versioning and compatibility expectations. ### Acceptance criteria - [x] Users can identify and manage loaded instruments and effects without editing configuration files. - [x] Missing or incompatible plugins produce actionable diagnostics and do not silently corrupt projects. - [x] Plugin state restoration is tested for supported plugin types. - [x] The engine remains safe if plugin initialization or processing fails, within the documented failure model. Implemented for the supported LADSPA 1.1 mono effects/audio sources: explicit module descriptor browser, copied identity and control metadata, generic parameter editor with validated Apply/Cancel and defaults reset, compatible-layout replacement preserving node ID/wires, and atomic effect insertion on a selected wire. Graph connections define order and existing deletion removes incident wires. Edits integrate with undo/redo and compile before adoption. State uses existing v9 parameter/automation records; missing/incompatible plugins retain the current document and report recovery guidance. Native processor ABI 2 remains unchanged. See PLUGIN_HOSTING.md and RECOVERY.md. Validation: warning-enabled core/GUI builds; full unit/integration suite; fixture and installed amp/inverter/sine plugin tests; actual chooser/editor GUI tests; reset/cancel, insertion, replacement, removal and undo; layout/init/missing module rollback; exact persisted rendering and noncommutative processing order; callback allocation/module-lifetime guards, reliability and static analysis; software JACK GUI/audio/MIDI and workflow; dependency-free build; installation and package relocation; ASan/UBSan including generic-dialog lifetimes (existing fontconfig leak suppression for GUI/system font allocations). Qualification remains the documented in-process failure model: LADSPA cannot signal run failure or contain crashes/hangs. No external editor, opaque state, MIDI-capable plugin instrument, recursive scanner or new format was added. Physical listening and arbitrary third-party plugin/endurance qualification remain pending. ## Phase 26 — Automation and Control Mapping ### Goal Enable repeatable changes to mix and instrument parameters over time, with clear timing and ownership rules. ### Tasks - Define a common parameter identity and metadata model. - Support automation lanes for a carefully selected set of parameters. - Define interpolation modes and behavior at clip boundaries. - Specify how automation interacts with live parameter changes and MIDI control. - Add control mapping for selected external MIDI controllers if feasible. - Schedule automation deterministically without allocating memory in the audio callback. - Define behavior when a target parameter or plugin is missing. - Test automation at buffer boundaries, during seeks, and across loop points. - Document precedence rules for automation, controller input, and direct user changes. ### Acceptance criteria - [x] Supported parameters can be automated and saved in a project. - [x] Playback produces deterministic automation values for a given project and transport position. - [x] Missing targets fail safely and are reported to the user. - [x] Automation processing meets the engine's real-time safety requirements. Implemented: common stable owner/parameter keys and copied metadata for track/bus gain/pan, LADSPA input controls and live sine controller targets; validated common static/lane edit APIs; per-point linear/hold mixer automation; per-channel saved volume/pan/sustain CC bindings with explicit disable and reserved panic controllers. GUI adds Interpolation and Audio/MIDI controller mapping; edits participate in undo/redo. Project v10 reads v1–v9 with linear/default-map migration. CONTROL.md documents target identity, clip boundaries, precedence, missing-target handling, controller ramps and real-time ownership. Validation: warning-enabled core/GUI builds and full tests; common metadata, missing owner/port/module failures and retained state; exact step/ramp endpoints, low-rate collisions, odd blocks, seeks and explicit backward wraps; default/ remapped/disabled/unmapped CCs and stereo pan, immutable maps after preparation; GUI map/interpolation/save/Open/undo/redo and invalid-edit rollback; v1–v9 migration, v10 exact persistence and malformed records; fixture/installed plugin tests, callback-allocation guards, reliability/static analysis, performance and capacity tests; software JACK GUI/audio/MIDI and workflow; dependency-free build, installation/package relocation, core/GUI ASan+UBSan (existing fontconfig leak suppression only for GUI/system font allocations). No loop transport, MIDI learn/capture, write/touch/latch modes, arbitrary MIDI mapping to arranged faders/plugins, timbre parameter for the built-in sine or opaque-plugin seek restoration is claimed. Live MIDI targets have reset-default metadata and controller bindings, not timeline lanes. Physical controllers, listening and extended third-party-plugin endurance remain unverified. ## Phase 27 — Editing Workflow, Undo/Redo, and Usability ### Goal Make common editing actions quick, discoverable, and safe to reverse. ### Tasks - Audit user-visible editing operations for undo/redo support. - Implement command-based edits with explicit ownership and rollback behavior. - Group related low-level changes into one meaningful undo step. - Define undo behavior for operations affecting engine state or external files. - Improve keyboard shortcuts, selection behavior, focus handling, and context menus. - Use confirmation only for genuinely destructive or difficult-to-reverse actions. - Provide clear feedback for long-running operations and failures. - Add GUI tests or reproducible manual test procedures for critical workflows. - Keep presentation logic out of the core C engine. ### Acceptance criteria - [x] Documented editing operations have predictable undo/redo behavior. - [x] Undo and redo restore the project model and relevant engine state consistently. - [x] Failed operations do not leave partial changes behind. - [x] Common tasks can be completed using documented keyboard and mouse interactions. Implemented: operation-by-operation audit in EDITING.md; reserved history storage before GUI command mutation/candidate publication, followed by allocation-free snapshot capture; recording start creates no empty history entry and each completed take is one undoable reference edit; unavailable main-menu history steps disabled; surviving editor selections and open piano-roll context retained on undo; piano-roll history shortcuts/context menu and pointer-targeted graph context menus; input focus guards and synchronous busy feedback. Existing C graph/batch note commands and snapshot history remain the model boundary; FLTK presentation stays in C++. No project format change (v10 retained). Validation: warning-enabled core/GUI builds and full tests; interposed allocation failure for each history reservation and capture with all allocations disabled; GUI history-reservation failure retains document, engine submission count and redo; completed-take undo grouping retains WAV; selection/context-target tests; existing grouped gestures/batches, candidate/backend rollback and save/reopen; workflow/software JACK GUI integration, reliability/callback guards, Clang static analysis, core/GUI ASan+UBSan, optional-dependency-free build, installation and package relocation. GUI sanitizer runs retain the existing fontconfig-only leak suppression. EDITING.md supplies a reproducible native manual procedure for popup dismissal, text focus, large synchronous operations and recorded takes. Native manual popup/focus/large-file usability checks, broad accessibility and physical-device listening/endurance remain pending. History remains bounded and session-only; selection/layout history, arbitrary command grouping, background loading and destructive source-media editing are not supplied. Preparation failure can stop/reset transport while retaining the old document/history. ## Phase 28 — Project Format, Compatibility, and Portability ### Goal Make project files robust, diagnosable, and maintainable across application versions and supported systems. ### Tasks - Version the project format and document its compatibility policy. - Validate project input before applying it to the live engine. - Handle missing media, plugins, and external dependencies with clear diagnostics. - Define relative-path, absolute-path, and media-relocation behavior. - Add safe migration routines for supported older versions. - Preserve unknown optional fields where practical, or document when they cannot be preserved. - Test malformed files, truncated files, oversized input, and invalid values. - Make saves atomic where the platform permits, using a temporary file and replacement strategy. - Document portability limits, including plugin and audio-backend dependencies. ### Acceptance criteria - Invalid project files are rejected safely without partially replacing the current project. - Save failures do not silently destroy the previous valid project file. - Version incompatibilities and missing dependencies are clearly reported. - Supported project versions have migration and regression tests. ## Phase 29 — Performance, Scalability, and Stress Testing ### Goal Establish measurable performance expectations and verify that larger projects remain stable. ### Tasks - Define representative test projects and target buffer sizes. - Measure audio callback duration, deadline misses, CPU use, memory use, and graph rebuild costs. - Test projects with increasing numbers of tracks, graph nodes, connections, MIDI events, and automation points. - Test long playback sessions and repeated start, stop, seek, and loop operations. - Stress-test device changes, plugin failures, missing media, and project reloads. - Use profiling to identify bottlenecks before introducing optimizations. - Verify that the real-time callback does not allocate, block on mutexes, perform file I/O, or wait on GUI work. - Document expected limits and known performance bottlenecks. - Add sanitizers and static analysis to regular development builds where supported. ### Acceptance criteria - Performance is measured against documented test cases, not subjective impressions alone. - Stress tests can run repeatedly and produce reproducible results. - No known real-time safety violation remains in the engine's own callback path. - Performance regressions can be detected by repeatable tests or benchmark reports. ## Phase 30 — Release Engineering, Packaging, and Maintenance ### Goal Turn the application into a maintainable release that users can build, install, run, and troubleshoot. ### Tasks - Define supported operating systems, compiler versions, and audio backends. - Document build dependencies and provide clear build and test commands. - Add install and uninstall targets that respect `PREFIX` and standard directory variables. - Provide appropriate package metadata and desktop integration where relevant. - Verify installation paths for binaries, libraries, headers, resources, documentation, and example projects. - Add version reporting and a concise diagnostic mode where useful. - Prepare release notes, known limitations, and upgrade guidance. - Test clean builds from a fresh checkout and installation into a staging directory. - Define a release checklist covering tests, warnings, packaging, and project compatibility. - Document how users can report reproducible bugs and how maintainers should triage them. ### Acceptance criteria - A clean checkout can be built and tested using documented commands. - Installation works with a configurable prefix and does not overwrite unrelated user files. - The release includes documentation, known limitations, and a reproducible version identifier. - The project has a repeatable process for preparing and validating releases. --- ## Recommended Execution Order Reorder the phases when the audit reveals a blocking dependency. Do not mark a phase complete merely because code exists: its acceptance criteria must be demonstrated by builds, tests, or documented manual verification. ## Definition of Done for Each Phase A phase is complete only when: - The project builds with warnings enabled. - Relevant automated tests pass, and manual tests are documented where automation is impractical. - Error paths, resource ownership, and thread boundaries have been reviewed. - Real-time audio constraints remain satisfied. - Documentation is updated alongside API or behavior changes. - No unrelated functionality was silently removed. - Untested behavior and known limitations are reported honestly. - The phase's acceptance criteria are explicitly checked off. Do not skip phases without documenting why and preserving acceptance criteria.