Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -425,6 +425,7 @@ if(BUILD_TESTING)
target_link_libraries(ARMixDurableMixerSessionTests PRIVATE
juce::juce_audio_devices juce::juce_audio_processors juce::juce_cryptography juce::juce_recommended_config_flags)
target_compile_features(ARMixDurableMixerSessionTests PRIVATE cxx_std_20)
target_compile_definitions(ARMixDurableMixerSessionTests PRIVATE JUCE_MODAL_LOOPS_PERMITTED=1)
add_test(NAME P0DynamicMixerSessionDocumentAndCrashSafeRecovery COMMAND ARMixDurableMixerSessionTests)
# Presentation-only native identity; no audio-thread access.
juce_add_console_app(ARMixChannelAppearanceTests PRODUCT_NAME "ArSonMix Channel Appearance Tests")
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Status: WORKING PLAYBOOK, v1 2026-11-11. Root [AGENTS.md](../../AGENTS.md) and [

## Recipe A — new built-in FX

Define catalog identity and stable insert/slot semantics once. Implement DSP as its own processor with deterministic prepare, bounded process, state serialization and bypass/latency reporting. Hook into the existing Factory/FX host registration; preserve the same editor/ACK readback and rack bypass mechanics as EQ/Compressor/Harmonice/Vocal Throw. Channel/BUS routing sees only generic FX lease, not the plugin brand. Verify zero/known latency/PDC, offline state, inserted audio, bypass, reorder/move and device restart. Keep plugin-specific UI ONLY in its editor component, not device setup.
Define catalog identity and stable insert/slot semantics once. Implement DSP as its own processor with deterministic prepare, bounded process, state serialization and bypass/latency reporting. Register compiled processors in `src/NativeBuiltInFx.h` for the generic live insert, offline prepare, restore and native picker. Preserve the same editor/ACK readback and rack bypass mechanics as EQ/Compressor/Harmonice/Vocal Throw. Channel/BUS routing sees only generic FX lease, not the plugin brand. Verify zero/known latency/PDC, offline state, inserted audio, bypass, reorder/move and device restart. Keep plugin-specific UI ONLY in its editor component, not device setup.

**Design signal:** needing to modify a large per-plugin switch in Main, engine callback and browser bridge for every new audio processor indicates incomplete M4 host-seam consolidation. Solve shared host responsibility once and remove old branch at the same time. Do not add a new wrapper if only one plugin needs a unique capability.

Expand Down
17 changes: 12 additions & 5 deletions docs/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ 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
Expand All @@ -29,26 +30,32 @@ Assembled /preview/ DOM (presentation only)
| 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/NativeLogicalMixerWorkspace.h; src/NativeMixerSessionDocument.h; engine/core/DeviceIndependentMixerSession.h; engine/core/DynamicChannelRoster.h | Stable ChannelId/EdgeId, control-authoritative edits, revision guard, logical-only semantics |
| 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 |
| Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority |
| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; common host lifecycle, source state, bypass, latency, editor lease and host registration |
| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/NativeBuiltInFx.h; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; one built-in registration for live insert, offline prepare, restore and native picker. Specialized editors and vendor lease 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/ApprovedNativeV8Projection.h | Installed / retained / logical-only readback with one semantic contract and no forged output/PCM authority |
| 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 |

## M1 control events

- `arMixLogicalIntent` enters the logical control service. It validates the request ID, workspace token and revision, then commits the candidate document and referenced FX state through `NativeMixerSessionSaveWorker`. An `arMixLogicalAck` reports that commit's revision. A later `arMixConsoleSnapshot.logicalMixer` provides independent readback with `LOGICAL_ONLY` authority.
- `arMixConsoleIntent` retains the admitted native control path. The approved bridge waits for `arMixConsoleAck` and 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.
- `arMixCatalog` carries registered built-in picker metadata alongside verified external catalog entries. One registration in `NativeBuiltInFx.h` supplies the control-side prepare function and limits for a generic built-in insert. An effect with its own editor supplies that editor separately.

## Verified audit hotspots at main 99f580d76bf20ea994d54f8916098c680897f41d

- src/Main.cpp: 6,499 lines. ConsoleWindow currently owns logical edits, native ACK/status, device selection/apply, built-in FX handlers, plugin editors, Player and UI responsibilities.
- 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.
- The two ApprovedNativeV8Projection.h headers define identical helper names and different public projection behavior. integration/ApprovedNativeRuntimeSnapshot.h uses the integration version for installed/retained paths; src/ConsoleLiveBridgeV6.h includes the src version. Never delete either without proving all callers and tests.
- 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.
Expand Down
9 changes: 9 additions & 0 deletions integration/ApprovedNativeV8Projection.h
Original file line number Diff line number Diff line change
Expand Up @@ -192,4 +192,13 @@ inline bool projectApprovedNativeV8(juce::var& snapshot,const juce::var& bus,
return installedChannelIdCallbackAdmitted &&
projectNativeGraph(snapshot,bus,NativeGraphProjection::installed);
}
// Legacy callers supplied a bus from the installed producer, which exposes
// its WIRE operation. The retained producer supplies an empty operation list.
// New callers must pass admission explicitly from the owning engine status.
inline bool projectApprovedNativeV8(juce::var& snapshot,const juce::var& bus) {
const auto supported=bus.getProperty("supportedOps",{});
const auto* ops=supported.getArray();
return projectApprovedNativeV8(snapshot,bus,
ops && ops->contains(juce::var("NATIVE_APPLY_WIRE_TRANSACTION")));
}
} // namespace armix::console
2 changes: 1 addition & 1 deletion scripts/build_approved_native_gui.py
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ def accepted_pages_html() -> str:
" },\n"
" closeNativePicker(){setFastPicker(false);},\n"
" colors:COLORS,channelIcons:CHANNEL_ICONS,wireGraph:ArSonWireGraph,\n"
" allocateWireId(){return nextWireId++;},\n"
" allocateWireId(){return nextWireId++;},kickWireSpring,\n"
" installGraph(channels,main,edges){\n"
" tracks=channels;master=main;wireEdges=edges;\n"
" wireWsHistory=[];selectedWireEdgeId=null;\n"
Expand Down
Loading
Loading