Status: CURRENT navigation (2026-11-11). Development is not gated by a separate architecture committee or manual Actions approval. This page points to maintained code, exact tests and the existing smart CI mechanism. Do not use historical PRs or old workstream handoffs as the current branch.
The only approved GUI is the deterministically assembled /preview/ used by the JUCE WebView2 desktop app. The browser preview is presentation/reference, not a PCM producer. The native audio owner is one JUCE callback with one installed ChannelId/EdgeId graph; legacy M4 compatibility cannot silently override it.
Read AGENTS.md, current architecture ownership, feature-extension playbook and smart CI policy. Then inspect live main, open PR HEADs and the actual touched code. Maintainability issue #527 records incomplete architecture work.
| Intent | Primary existing owner | Nearest verification |
|---|---|---|
| Logical tracks, WIRE, .smix edits | src/NativeLogicalMixerControl.h, src/NativeLogicalMixerWorkspace.h, src/NativeMixerSessionStore.h |
tests/native_mixer_session_store_test.cpp, tests/approved_native_m2_contract.test.cjs |
| Physical output/ASIO setup | src/NativeDeviceApplyCoordinator.h, src/LiveAudioEngine.h, engine/device/ |
tests/native_device_apply_coordinator_test.cpp, device/ASIO CTests |
| Routing / actual PCM callback | engine/core/DynamicNativeSessionPublisher.h, src/LiveDryRoutingLab.h, src/LiveAudioEngine.h |
tests/live_channel_fx_graph_test.cpp, routing golden-PCM tests |
| Built-in or VST3 effect | src/NativeBuiltInFx.h, src/NativeFxControlRequest.h, engine/core/DynamicChannelFxLeaseBank.h, src/NativeMixerSessionFxRestore.h |
tests/native_fx_registry_extension_test.cpp, FX lease/editor CTests |
| Native UI intents and readback | web/approved-native-contract.js (pure ACK, validation and presentation), web/approved-native-bridge.js (single browser/DOM adapter) |
tests/approved_native_m2_contract.test.cjs, assembled Chromium UI |
| User-facing UI assets | scripts/build_pages.py, scripts/build_approved_native_gui.py, approved site/preview-buttons/ inputs |
native bundle provenance and Chromium visual checks |
A new FX should add a catalog descriptor, processor/editor specialization, state/PCM tests and accepted readback without creating a new callback, device manager, local JS graph or unrelated device handling branch. A new hardware output must require verified physical identity and preserve the logical .smix session across device loss.
The architecture lane is not an integration gate. The latest merged FX-host safeguards are #565 (unique prepared processor instance token) and #567 (shared native control envelope and deterministic effect mailbox). #564 and #568 own GUI ACK/readback and presentation rules. A current follow-on #569 tightens malformed input types; treat it as unmerged until the live PR says otherwise.
Harmonice's active #529 builds on this shared NativeFxControlRequest for editor and user-preset actions; its vocal DSP and preset UI remain independently owned by that PR. The physical multi-output #563 edits device/graph/Main/bridge and may predate newer host changes. Do not overwrite either branch or cherry-pick its incomplete work. Before merging either, compare changed files to current main, resolve genuine semantic overlap, and qualify its own final combined HEAD. A green branch workflow alone is not proof of merged audio or field ASIO FAT.
Native FX command envelopes use exact decimal-string ChannelId/epoch/revision, a string requestId, an integer insert slot, and an optional string workspaceToken for logical editing. The hpres- user-preset request family is not a harm- realtime DSP mailbox sequence. deviceEpoch="0" represents logical-only work and must never authorize hardware output. Add/modify an FX by extending the shared host contract and its native registry test, not by copying type coercion into another plugin-specific route.
Use CONTROL/message thread for graph compilation, VST3 construction/destruction/state, device transactions, JSON/disk and editor lifetime. Audio callback must not allocate, block, lock, access disk or log. Publish prepared immutable data and retire leases safely after realtime readers finish. ASIO primary must never wait for WASAPI secondary work.
A UI intent is not complete on ACK alone: verify an independent accepted same-revision snapshot. LOGICAL_ONLY, RETAINED, INSTALLED and audible hardware are different facts. A rejected/stale command must preserve the previous accepted mixer and output safety. SOURCE ONLY must preserve channel PCM/meter while cutting MAIN output, without losing user FX state.
The original mixer and native built-in FX are AGPL-3.0-only; see LICENSE and LICENSE-NOTICE.txt. Submit original contributions only if you have the rights needed to license them accordingly. Do not copy proprietary VST3 code, restricted SDK sources, audio datasets or media into first-party modules. Keep third-party attributions and upstream licence files intact.
The Windows installer/portable ZIP and Linux/macOS packages must include the complete AGPL text, first-party notice and applicable vendored-component notices. The fast licence distribution contract and Windows byte-level artifact verifier enforce this. Do not weaken release source provenance or change the native DSP graph to implement licensing.
For JS protocol edits, use node --test tests/approved_native_m2_contract.test.cjs from the repo root and the relevant contract suites. For C++ work, choose the nearest CMake/CTest targets and build on the repository's supported JUCE/MSVC workflow. Do not skip full qualification for a changed native behavior. Use path-scoped fast checks while iterating; after green quick checks, the connected GitHub owner agent dispatches one exact-SHA ui for visual/gesture changes or one exact-SHA native for C++/ASIO/FX changes. When a hardware-test ZIP is required, use fat instead of duplicate native, and verify its SHA/artifact provenance. See the runbook.
Never call CI PASS physical FAT. Actual ASIO routing, hotplug, plugin-editor continuity, audible PCM, noise and latency must be witnessed on equipment. Keep that evidence separate from unit tests and do not promote a product release on an unqualified ZIP.
When finishing a scoped PR, record changed responsibilities, main and PR SHAs, test results and failures, exact dispatched lane (or why none), rollback/previous accepted-state proof, physical FAT status and remaining work. Favor one cohesive change over many cosmetic cleanups.
Use the repository's compact bug report or feature/milestone request template. Do not open duplicate work from old SonKu/ImmerSIB research PRs: read the Milestone A source ledger first. Existing issue priority, area, status, testable exit criteria, and approved release boundaries are indexed in Milestone B governance; change issue labels/evidence to reflect newly proven reality instead of inventing completed audio or hardware FAT.
GitHub ruleset CI-required status checks are not yet configured even though the main PR/force-push ruleset is active; #748 tracks practical fail-closed enforcement without making path-scoped Windows/Chromium checks block documentation-only PRs. Do not close #450: it is the production owner-authenticated release command endpoint. Never publish or retune a proven release merely to clean up issue metadata.