# Development state ## Phase 1 — 2026-09-16 (Australia/Brisbane) This was a new workspace containing only `rivet-master-build-prompt.txt` and empty protected metadata directories. No existing application or usable Git repository was present. The master prompt explicitly asks for Phase 1 only. The implementation stops at that boundary. ### Created files - `CMakeLists.txt`, `.gitignore`: build, dependency detection, CTest and install rule. - `src/app/main.cpp`: application identity, startup, smoke/capture options. - `src/audio/AudioEngine.{h,cpp}`: real JACK client, stereo/MIDI ports, lifecycle, callback status, graph connection selection and error handling. - `src/dsp/DiagnosticProcessor.{h,cpp}`: independent diagnostic DSP and safety. - `src/midi/MidiEvent.{h,cpp}`: validated MIDI messages and bounded SPSC queue. - `src/ui/MainWindow.{h,cpp}`: native working settings/status/diagnostic interface. - `src/utilities/Logging.{h,cpp}`: ordinary-thread logging with launch-time rotation. - `tests/core_tests.cpp`, `tests/jack_integration.cpp`: deterministic and real server integration checks. - `tests/pipewire-test.conf`, `tests/isolated_audio.py`: isolated real PipeWire server, no hardware enumeration, connection and shutdown validation. - `README.md`, `BUILDING.md`, `ARCHITECTURE.md`, `DEVELOPMENT.md`, `CHANGELOG.md`: current behavior, exact commands, design, evidence and future tasks. - `docs/phase1.png`: development UI capture after layout review. Build products live in ignored `build/` and `build-release/`; development RPMs and extracted headers live outside the workspace in `/tmp/rivet-devel/`. The master prompt and `.agents` / `.codex` directories are unchanged. Git was subsequently initialized as described in the repository maintenance section. ### What works The native window starts without opening audio. Settings and device names persist; test signal activation does not persist. Audio starts silent and registers real stereo output and MIDI input ports. Selected external JACK ports are connected by name. Missing ports fail visibly and clean up the client. Unconnected operation is supported and explicitly identified by the status. A development sine passes through the real callback and selected output connections. Frequency, level and enabled controls affect that DSP. The processor smooths gain, limits the diagnostic to 0.05 linear peak, silences non-finite samples and caps output to ±0.95. Meters read generated output samples; they are not evidence that physical speakers are connected. MIDI parsing supports note on/off, velocity-zero note-off, pitch bend and CC. An integration sender verified events actually enter through JACK, with their channel and sample offsets preserved. The GUI monitor is the consumer in this phase. There is no voice engine and no MIDI recording/playback claim. Output disconnection leaves a valid running engine and updates connection status. Server loss publishes atomic flags, then the control thread performs cleanup. The user can refresh and restart. Logging and settings I/O are outside the callback; no sample file or project I/O exists yet. ### Validation evidence - Initial no-JACK limited build compiled and passed core + Qt smoke checks, explicitly reporting audio unavailable. - JACK-enabled Debug build compiled with GCC warnings enabled and passed CTest. - JACK-enabled Release build compiled without compiler warnings and passed both CTest checks. Final Debug CTest also passed (2/2 in each configuration). - Final Release isolated-server integration passed all 18 checks, including invalid buffer validation and server-loss cleanup: 48,000 Hz / 256 frames, 243 callbacks, captured 439.586 Hz, peak 0.025, zero reported xruns. - Native KDE/Wayland desktop launch/capture succeeded and exited without opening audio. Offscreen smoke also passed with `QT_SCALE_FACTOR=2`. - Core: silence, 440 Hz frequency, bounded finite stereo, gain ramps, peak meter, block-boundary phase continuity, invalid sample rate, invalid parameters, clipping protection, MIDI decoding and malformed-message rejection. - Queue: overflow, wraparound and 100,000 concurrent ordered messages. - Offscreen Qt: window startup, diagnostic parameter editing, safe initial controls, settings write, clean shutdown. UI images were inspected and a sizing problem was fixed; controls now have explicit minimum heights and the window has a scrollable viewport for smaller screens. - **Desktop PipeWire 1.6.8 integration passed:** 48,000 Hz, 2,048-frame blocks, 31 observed engine callbacks during the signal window, captured frequency 440.885 Hz, peak 0.025, zero reported xruns during that run. - **Isolated PipeWire integration passed:** 48,000 Hz, 256-frame blocks, 244 callbacks during the signal window, captured frequency 439.586 Hz, peak 0.025, zero reported xruns during that run. - Both integrations verified real stereo graph links, captured startup silence, nonzero bounded signal, return to silence, actual metering, MIDI types and offsets, output disconnection, repeated restart and missing-port errors. - Isolated daemon termination verified server-loss flags, safe cleanup and an actionable error when subsequently starting without a server. The capture checks create only application-to-application links; they do not send test audio to physical speakers. Frequency estimates count crossings over a finite capture window, so small deviations from exactly 440 Hz are expected. These short checks are functional evidence, not latency/CPU benchmarks or long-duration reliability claims. ### Environment and dependencies Fedora 44 KDE / x86_64, GCC 16.2.1, CMake 4.3.0, Ninja 1.13.2, Qt 6.11.2, PipeWire 1.6.8. `BUILDING.md` lists all inspected runtimes and missing headers. The first build used the genuine Fedora JACK development RPM extracted into `/tmp`, linked to the installed JACK runtime. Sudo authentication prevented that initial system install. The owner subsequently installed JACK development 1.6.8 and ALSA development 1.2.16.1; RPM and pkg-config confirmed both. Fresh `build-system/` and `build-system-release/` configurations use system packages. sndfile, SQLite and native PipeWire development files remain unused in Phase 1. ### Known limitations - Sample rate is configured through the server or PipeWire launch hint, not a native JACK per-client setter. Actual rate/quantum are displayed. Buffer-size requests can affect the shared server and remain subject to its policy. - Direct ALSA sequencer input is deferred. Hardware MIDI must be exposed as a JACK/PipeWire port. No physical MIDI controller or hardware hot-unplug was tested; virtual port disconnect and real server termination were tested. - No audio hardware listening test was performed; real server capture proved the signal path without playing a test sound through the user's speakers. - No automatic reconnect. Refresh and restart are explicit. - GUI meter reads a block peak at ~30 Hz with visual decay. Short transients can fall between polls; a production peak accumulator belongs with the mixer. - Displayed CPU load is JACK's graph-wide report, not RIVET-only DSP profiling. - Monitor queue has 1,023 usable entries and a maximum 256 decoded events per callback. Excess events are counted/dropped. Before synthesis, implement a defined note-state recovery policy; a dropped diagnostic event cannot leave voices stuck because this phase has no voices. - Diagnostic DSP is not band-limited synthesis, a mixer or a production limiter. The master safety clamp is a last-resort bound, not a lookahead limiter. - Native JACK (jackd), long-duration load, suspend/resume, and sanitizer runs have not been validated. No performance optimization claims are made. - A development launch can log a harmless portal registration warning because `org.retrace.rivet` has no installed desktop entry yet. A desktop entry belongs with the later installation/packaging work; the native window still runs. - Small settings/log operations happen on the GUI thread. Future file decoding, indexing and project I/O need background workers before implementation. - Logs rotate on launch, not continuously. No crash recovery/project format yet. - The original build directories retain temporary header paths; use the fresh system-package build directories documented in `BUILDING.md`. ## Repository maintenance — 2026-09-16 - Initialized Git on `main` and committed the original verified Phase 1 baseline as `591028f` (`feat: establish Phase 1 audio and MIDI foundation`). This commit retains the disclosed temporary author. Subsequent commits use the owner's corrected repository-local identity: Retrace Enterprises. - Added `AGENTS.md`, `CONTRIBUTING.md` and `VERSIONING.md` to make ongoing Git, compatibility, release and documentation maintenance explicit. - Added `VERSION` and `src/app/Version.h.in`; CMake validates Semantic Versions (including prereleases/metadata) and generates the runtime version constant. - Standardized changelog sections, editor settings and line endings. Build directories, generated headers and temporary artifacts remain untracked. - Established an annotated local `v0.1.0` development baseline. No remote or publication is configured. This is the tested foundation, not a finished DAW. - Validation: fresh Debug and Release system-package builds passed CTest (2/2 each); both report `RIVET 0.1.0`. The Release build passed the 18-check isolated PipeWire audio/MIDI/shutdown suite. Its CMake cache uses `/usr/include` and the installed PipeWire JACK library directory, with no temporary header dependency. - Version configuration accepted and propagated `0.2.0-alpha.1+build.5` in a temporary source copy, and rejected leading-zero numeric components, leading-zero numeric prerelease identifiers, incomplete versions, empty build metadata and multiple version lines. The working source remains `0.1.0`. ### Recommended Phase 2 work 1. Define device IDs, typed ports, parameter metadata and fixed block contracts. 2. Build and test graph connection validation, cycle rejection and execution ordering independently of Qt. 3. Prepare graph buffers and execution plans outside audio; implement safe plan publication and old-plan reclamation without callback allocation/destruction. 4. Add simple signal/gain/sink test devices and verify routing by audio capture. 5. Build add/remove/reorder/select/collapse front rack controls and rear jacks. Add a cable only when it edits the real tested graph. 6. Extend disconnection, rapid graph edits and multiple-buffer-size tests before beginning Phase 3 synthesis. Preserve silence-on-start and safety boundaries.