Status: CURRENT ORIENTATION (audit 2026-11-11). This document describes verified repository source and the proposed ownership model; it does NOT certify the installed Windows application or physical audio. Refresh current main/PR HEAD before changing code.
Cross-cutting design review (2026-11-18, research/documents only): Multi-Device I/O PRD · Multi-Device I/O ARD v2 · JUCE/MVVM research and current source audit · MVVM modular-monolith feasibility ADR. These documents explicitly distinguish multiple primary-ASIO output PINS (existing output routing), a second WASAPI MAIN-copy output (existing OUTPUT1), multiple independent CAPTURE devices (not yet implemented) and independent selected-BUS output SINKS (not yet implemented). Historical 'one JUCE audio callback' is a single DSP/render-ownership invariant, not a prohibition on strictly producer-only capture and consumer-only output callbacks when a future multi-I/O design is physically qualified. ArSonMix is the mixer; Harmonice is its built-in harmony plugin. Input-only draft #757 remains a separate unmerged research proposal.
Feature milestone status: H1 hotkeys MERGED #536, H2 VST3 parameter hotkeys MERGED #551, exact integrated Windows native 86/86 CTest PASS at the historical checkpoint; independent physical/vendor field FAT remains pending. O1/O2 FL-style physical multi-output is NOT YET MERGED INTO MAIN; active candidate #563 must pass integrated source/CI plus physical FAT. Use the O-only execution handoff and complete technical contract.
Maintainability implementation snapshot (2026-11-11, checked at main@b5b03669c616ac55a5d935023e0402ec7a99f7be): M0 #528 and M1 #530 merged. M2 #534/#538/#540 device transaction/readback code merged, physical ASIO FAT pending. M3 #542/#560 bounded renderer evidence merged; legacy M4 retirement not proven. M4 #553 registration fixture, #565 FX lease token uniqueness and #567 shared control envelope merged, but editor/parameter lifecycle consolidation remains partial. M5 #555/#561 negative ACK/FX guards, #564 readback effects, #568 pure presentation rules merged; further bridge isolation remains partial. M6 #562 producer identity guard and #566 contributor guide merged; guardrails still incremental. #569 is a separate active candidate until verified merged. For live Harmony #529 and multi-output #563, read the cross-thread integration guidance and their current HEAD, not this dated snapshot. Epic #527 remains open.
Entry points: Execution blueprint · Fast feature playbook · Next-thread prompt · Issue #527.
ArSonMix is a native JUCE live digital mixer and VST3 host with one approved assembled /preview/ GUI rendered by WebView2; browser preview is visual/simulated, not a browser audio engine. Native hardware audio authority is the ONE JUCE AudioIODeviceCallback and its installed ChannelId/EdgeId PCM graph, with M4 compatibility only where explicitly still needed. A logical/offline MixerSessionDocument can be edited without hardware but is NOT permission to claim audible PCM.
The current path to reason about every feature is:
Assembled /preview/ DOM (presentation only)
-> web/approved-native-bridge.js + web/approved-native-contract.js
-> Native JUCE command transport in src/Main.cpp (MESSAGE/CONTROL thread)
-> src/NativeLogicalMixerControl.h for unbound edits and readback
-> accepted logical MixerSessionDocument / ChannelId + EdgeId model
-> validated mixer graph & FX lease preparation (CONTROL, not callback)
-> engine/core/DynamicNativeSessionPublisher.h + realtime publication
-> ONE src/LiveAudioEngine.h JUCE callback (with src/LiveDryRoutingLab.h compatibility integration)
-> verified ASIO/WASAPI device outputs, optional independent stream
-> native status/ACK then accepted revision readback -> exact same GUI
Logical ACK/readback means a durable native logical edit was committed and subsequently read back. Installed PCM ACK/readback means an actual prepared graph is installed and bound to genuine device/pin identity. They must never be conflated. A third state, audible, requires valid authorized output routing; a browser 'ready' event or successful CI cannot prove it.
| Concern | Current primary files | Correct responsibility / future direction |
|---|---|---|
| Application composition / bridge transport | src/Main.cpp; src/ApprovedConsoleNativeTransportV6.h | JUCE app lifecycle, WebView wiring, dispatch only; move domain-heavy control use-cases behind narrow services incrementally |
| Logical mixer & accepted session | src/NativeLogicalMixerControl.h; src/NativeLogicalMixerWorkspace.h; src/NativeMixerSessionDocument.h; engine/core/DeviceIndependentMixerSession.h; engine/core/DynamicChannelRoster.h | One accepted workspace. The control service validates requests, stages edits, commits through the shared save worker and returns correlated ACKs. The workspace owns stable IDs and logical readback. |
| Session persistence | src/NativeMixerSessionStore.h; src/NativeMixerSessionSaveWorker.h; src/NativeMixerSessionFxRestore.h | .smix durable state, rollback, vendor-state retention and explicit schema migration |
| Native graph publisher & PCM | engine/core/DynamicNativeSessionPublisher.h; engine/core/RealtimeRoutePublisher.h; engine/core/DynamicPreparedMixerBlock.h | Validated immutable prepared graph, atomic publication, safe retirement, callback render state |
| Audio device policy | src/LiveAudioEngine.h; engine/device/**; src/Main.cpp currently applies device | Verified driver/pins, epochs, reopen/rebind, explicit physical output safety; independent from logical session document |
| Audio device apply preflight (M2a) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp (remaining orchestration) | Single message-thread transaction guard, JUCE open boundary, typed request/pin checks, accepted readback and fail-closed rollback. Remaining: simplify Main orchestration where proven, and independently witness physical restart/rebind FAT |
| Modal setup transaction (M2b) | src/Main.cpp::showDeviceSetup; NativeDeviceApplyCoordinator.h | Persistent one-owner lease across visible JUCE selector, explicit Apply and automatic ASIO restart; repeated Setup clicks never re-mute; selector close completes readback/rebind before releasing lease |
| Live hardware readback (M2c) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp | Consolidated actual device-object readback on CONTROL, strict ASIO driver instance identity and live mask/rate/buffer verification before Apply/rollback; no new device owner or callback |
| Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority |
| Waves VST3 / crash-safe recovery | scripts/patch_juce_vst3_waveshell.py; src/Vst3DescriptionCache.h; src/StartupVst3RecoveryGuard.h | Correct JUCE 8 WaveShell class-ordering defect; require name+UID resolution; protect saved .smix from repeated startup vendor crashes |
| M3a/M3b real render evidence | engine/core/ProductionRenderAudit.h; LiveDryRoutingLab::process/status; docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md | One native or M4 render attempt per JUCE callback; same-epoch bounded windows before considering M4 retirement; no fallback deletion or physical FAT claim |
| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/NativeBuiltInFx.h; src/NativeFxControlRequest.h; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; one built-in registration and typed CONTROL target across EQ/Compressor/Harmonice/Vocal Throw. Specialized DSP/editor semantics remain with their existing owners. |
| Player | engine/player/**; src/Main.cpp dispatch | Worker decode / buffered PCM, one native graph virtual input, no independent hardware output callback |
| Native status projection | integration/ApprovedNativeRuntimeSnapshot.h; integration/ApprovedNativeV8Projection.h; src/NativeLogicalMixerControl.h | Canonical installed and retained projection, with a forwarding include for old clients. Logical-only readback is separate and cannot admit PCM. |
| GUI state, WIRE, device setup | web/approved-native-bridge.js; web/approved-native-contract.js; web/monitor.js; web/mixer-io.js; site/preview-v2/ (internal build input) | Render accepted native states only; one assembled/public/native /preview/; no competing DOM model or JS PCM |
| UI build & publishing | scripts/build_pages.py; scripts/build_approved_native_gui.py; site/preview-buttons/ (approved PNG overlay source) | Deterministic single assembled renderer and native bundle provenance, not a second public GUI |
| Tests & CI | tests/**; CMakeLists.txt; .github/workflows/{ui-smoke,p1-windows,chat-ci-milestone}.yml | Cheap relevant checks every PR update, deliberate exact-SHA UI or native/FAT milestone; physical FAT separate |
arMixLogicalIntententers the logical control service. It validates the request ID, workspace token and revision, then commits the candidate document and referenced FX state throughNativeMixerSessionSaveWorker. AnarMixLogicalAckreports that commit's revision. A laterarMixConsoleSnapshot.logicalMixerprovides independent readback withLOGICAL_ONLYauthority.arMixConsoleIntentretains the admitted native control path. The approved bridge waits forarMixConsoleAckand matching accepted readback before committing the visible control state. Retained graph readback carries no installed callback authority. A verified socket connection or retarget uses the existing renderer's gravity and impact animation after the accepted graph is drawn.arMixCatalogcarries registered built-in picker metadata alongside verified external catalog entries. One registration inNativeBuiltInFx.hsupplies the control-side prepare function and limits for a generic built-in insert. An effect with its own editor supplies that editor separately.
- src/Main.cpp: 6,499 lines. Before M1, ConsoleWindow owned logical edits, native ACK/status, device selection/apply, built-in FX handlers, plugin editors, Player and UI responsibilities.
- src/LiveAudioEngine.h: 3,564 lines. The single callback shares a class with device lifecycle, legacy routing control, graph/plugin lifecycle, and monitoring policy.
- src/LiveDryRoutingLab.h: 3,261 lines. Production ChannelId paths coexist with legacy M4/Lab names/guards.
- web/approved-native-bridge.js: 3,646 lines. Many per-domain event/ACK/DOM pathways in one adapter.
- web/monitor.js: 2,118 lines; do NOT assume it is entirely in the currently assembled native GUI without checking the build.
- Before M1, two ApprovedNativeV8Projection.h headers defined overlapping projections. The canonical integration header now serves both callers, and the src header forwards to it.
- tests/ contains large routing, device, source/session and FX test suites. This is a major asset. Some source-text contract tests intentionally assert exact code strings; refactoring may legitimately need to update these only when behavior-equivalent tests also exist.
- docs/ contains 238 direct entries. The 2026-11-07 Device-Independent ADR says "NOT YET IMPLEMENTED", while merged PR #513 implements logical-only Milestone A. This is partially stale wording, not permission to claim hardware binding works.
- web/styles.css is dominated in bytes by an embedded base64 font; file size is NOT a maintainability score by itself.
README v0.5.0-alpha.10 identifies Windows as an alpha field-test build. Full physical ASIO, real singer monitoring, vendor VST3 continuity, device-loss behavior and uninterrupted audio require independent FAT. Issue #490, #412, #192, and #15 remain product/field-quality owners. A code restructure must not claim these resolved.
- Exactly one approved /preview/ GUI, assembled deterministically, shared between public preview and native host. Do not use /preview-v2/ as a separate product.
- Exactly ONE JUCE realtime callback, one installed ChannelId PCM authority; JS never handles or fabricates PCM.
- Stable native ChannelId/EdgeId and revision/epoch fences; stale or rejected commands never change accepted audio state. Never portray LOGICAL_ONLY or RETAINED as installed or audible.
- Processors, VST3 scans, editor lifecycle, session/JSON/disk, and graph construction stay off realtime callback. No RT blocking, allocation, logs or locks.
- ASIO mic monitoring remains independent of non-real-time playback/secondary WASAPI stream. Actual device and output-pin identity must be verified; never auto-reroute output or defeat user mute/intent.
- Device changes preserve mixer document, FX state and WIRE; intentional SOURCE ONLY and MAIN mute are respected; no extra monitor/ARM wizard to recover trusted already-approved output.
- Do not use docs-only work, mock GUI results or CI green as proof of physical audio FAT.
- Root AGENTS.md, Smart CI runbook, current main + active PRs.
- This map, execution blueprint, feature playbook.
- Only files and existing tests relevant to the chosen execution milestone; do not spend time reciting historical documents.
- Implement and validate a cohesive code milestone, record the exact SHA and follow the bounded CI policy.
Authority order: current user instruction + root AGENTS.md/approved GUI and native safety contract > current tested code and merged source > this orientation/implementation plan > older dated workstreams. This map is a guide to engineering and can be updated after verified source changes.