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
9 changes: 5 additions & 4 deletions .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -137,12 +137,13 @@ jobs:
& ./scripts/verify_native_windows_artifact.ps1 -OutputDir dist
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
# PRs compile/CTest/package but never silently publish a stable build.
# This single M4 FAT branch is explicitly allowed to upload an
# UNQUALIFIED experimental ZIP for real physical hardware testing.
# Only explicitly named hardware-FAT candidate PRs may upload an
# UNQUALIFIED test artifact. It is never a public/stable release.
# No extra build matrix and no upload when CTest/package audit fails.
- uses: actions/upload-artifact@v4
if: ${{ github.event_name != 'pull_request' || github.head_ref == 'milestone/m4-unified-native-multichannel-fx-20261101' }}
if: ${{ github.event_name != 'pull_request' || github.head_ref == 'milestone/m4-unified-native-multichannel-fx-20261101' || github.head_ref == 'work/m1-realtime-stability-20261102' }}
with:
name: ${{ github.event_name == 'pull_request' && 'ArSonMix-M4-EXPERIMENTAL-Hardware-FAT-Windows-x64' || 'ArSonMix-GUI10CH-P012-Verified-Hardware-FAT-Windows-x64' }}
name: ${{ github.event_name == 'pull_request' && (github.head_ref == 'work/m1-realtime-stability-20261102' && 'ArSonMix-M1-EXPERIMENTAL-Hardware-FAT-Windows-x64' || 'ArSonMix-M4-EXPERIMENTAL-Hardware-FAT-Windows-x64') || 'ArSonMix-GUI10CH-P012-Verified-Hardware-FAT-Windows-x64' }}
path: dist/
if-no-files-found: error
retention-days: 14
2 changes: 1 addition & 1 deletion CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ juce_add_gui_app(ARMixConsole
juce_add_binary_data(ARMixAssets SOURCES
web/index.html web/styles.css web/plugin-ui.css web/app.js web/plugin-ui.js web/bridge.js web/monitor.js web/mixer-io.js web/mixer-io.css web/mixer-layout.js web/mixer-layout.css web/assets/audio-interface.svg)

target_sources(ARMixConsole PRIVATE src/Main.cpp src/LiveAudioEngine.h src/VstOrbitController.h engine/core/MixerRoutingPlan.h engine/core/ChannelRoutingContract.h engine/core/ChannelSendPlan.h engine/core/AuxBusPlan.h engine/core/PreparedMixerBlock.h engine/core/MasterOutputMonoPolicy.h engine/core/LiveChannelFxGraph.h engine/core/PreparedNativeMixerSession.h engine/core/NativeDryRouteCommand.h engine/core/RealtimeRoutePublisher.h engine/device/LiveInputPortRegistry.h src/LiveDryRoutingLab.h engine/core/OrbitPhase.h engine/core/OrbitControlPolicy.h engine/core/OrbitMotion.h engine/core/OrbitDistanceMapping.h engine/core/DearVrPolarPolicy.h src/PluginCatalog.h src/FactoryFxRegistry.h src/PluginVault.h src/PortableWorkspace.h src/StudioBackup.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/NativeShowSchema.h src/NativeDryShowRecall.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/core/CallbackCadenceEvidence.h engine/diagnostics/CrackleEvidenceWindow.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h engine/device/PeriodCapabilityEvidence.h engine/device/SessionLifecycle.h engine/device/WasapiCapabilityProbe.h engine/device/JuceIndependentClockDevice.h engine/device/LiveSecondaryOutputDevice.h engine/core/LiveOutputRouteGate.h engine/device/ClockBridgeSizing.h engine/device/IndependentStreamFormatFence.h engine/device/DirectRestoreBackoff.h engine/device/IndependentStreamWatchdog.h engine/device/BridgeContinuityGate.h engine/device/EndpointIdentityPolicy.h engine/device/WasapiEndpointIdentityGuard.h engine/device/AsioStartupPolicy.h engine/device/AsioPriorityDeviceManager.h engine/device/JuceActivePortSnapshot.h engine/device/AsioRegistrationPolicy.h engine/device/AsioRegistryIdentityProbe.h engine/device/DirectRouteFence.h)
target_sources(ARMixConsole PRIVATE src/Main.cpp src/LiveAudioEngine.h src/VstOrbitController.h engine/core/MixerRoutingPlan.h engine/core/ChannelRoutingContract.h engine/core/ChannelSendPlan.h engine/core/AuxBusPlan.h engine/core/PreparedMixerBlock.h engine/core/MasterOutputMonoPolicy.h engine/core/LiveChannelFxGraph.h engine/core/NativeDryRouteCommand.h engine/core/RealtimeRoutePublisher.h engine/device/LiveInputPortRegistry.h src/LiveDryRoutingLab.h engine/core/OrbitPhase.h engine/core/OrbitControlPolicy.h engine/core/OrbitMotion.h engine/core/OrbitDistanceMapping.h engine/core/DearVrPolarPolicy.h src/PluginCatalog.h src/FactoryFxRegistry.h src/PluginVault.h src/PortableWorkspace.h src/StudioBackup.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/NativeShowSchema.h src/NativeDryShowRecall.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/core/CallbackCadenceEvidence.h engine/diagnostics/CrackleEvidenceWindow.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h engine/device/PeriodCapabilityEvidence.h engine/device/SessionLifecycle.h engine/device/WasapiCapabilityProbe.h engine/device/JuceIndependentClockDevice.h engine/device/LiveSecondaryOutputDevice.h engine/core/LiveOutputRouteGate.h engine/core/NativeRenderAuthority.h engine/device/ClockBridgeSizing.h engine/device/IndependentStreamFormatFence.h engine/device/DirectRestoreBackoff.h engine/device/IndependentStreamWatchdog.h engine/device/BridgeContinuityGate.h engine/device/EndpointIdentityPolicy.h engine/device/WasapiEndpointIdentityGuard.h engine/device/AsioStartupPolicy.h engine/device/AsioPriorityDeviceManager.h engine/device/JuceActivePortSnapshot.h engine/device/AsioRegistrationPolicy.h engine/device/AsioRegistryIdentityProbe.h engine/device/DirectRouteFence.h)
target_compile_definitions(ARMixConsole PRIVATE
JUCE_WEB_BROWSER=1
JUCE_USE_WIN_WEBVIEW2=1
Expand Down
57 changes: 57 additions & 0 deletions docs/ENGINE_RUNTIME_AUTHORITY_20261103.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# ArSonMix — ONE production engine, GUI-directed ownership
Date: 2026-11-03. Status: **binding engine ownership map** (code-enforced for existing M4 callback, NOT universal live certification).

## Only one runtime authority

```text
PR #278 + #285 approved GUI workflow (reference only, not audio)
|
PR #271 web native renderer → ConsoleLiveBridgeV6 snapshot/intent/ACK
|
Native JUCE LiveAudioEngine
|
NativeRenderAuthority (one selector)
| | |
UNPATCHED ACCEPTED M4 DIAGNOSTIC
silence one real mixer test-only 0FX
|
LiveDryRoutingLab
LiveChannelFxGraph
PreparedMixerBlock
|
existing CH1 original VST/Orbit lease
AUX / MAIN / MONITOR
|
actual verified device pins
```

The `NativeRenderAuthority` is an explicit, fixed-cost callback selector. **There is no second simultaneously running mixer.** The former standalone stereo plugin dispatch inside the diagnostic-only remainder was unreachable and is deleted, not hidden behind another flag. An unpatched NORMAL route stays silent and cannot silently fall back to stereo CH1.

## What is active, what is migration-only, what is test-only

| Ownership | Modules | Decision |
| --- | --- | --- |
| **PRODUCTION, temporary compatibility** | `src/LiveAudioEngine.h`, `src/LiveDryRoutingLab.h`, `engine/core/LiveChannelFxGraph.h`, `engine/core/PreparedMixerBlock.h`, native CH1 VST/Orbit lease | KEEP until truly equivalent unified render; bugfixes only, no new competing features |
| **Future canonical ChannelId engine (prepared, not yet production)** | `DynamicChannelRoster`, `DynamicPreparedMixerBlock`, `DynamicNativeSessionPublisher`, `DynamicChannelFxLeaseBank`, `UnifiedLegacyProductionAdmission`, `DynamicAcceptedSession` | KEEP as one migration target; **do not attach as a second callback** or advertise LIVE |
| **Compatibility translation** | `LegacyLiveGraphMigration`, accepted device epoch / actual port pin mapping | KEEP until cutover with exact PCM, VST/editor and Show parity; then retire in one controlled transaction |
| **Testing-only** | `PreparedNativeMixerSession.h`, dedicated offline dynamic test targets | No longer list testing-only session as shipped `ARMixConsole` source; keep its separate CTest target |
| **Diagnostics, no effect graph** | old stereo scratch path in `LiveAudioEngine`, diagnostic tone/capture, health and 0FX evidence | KEEP isolated with NO vendor plugin processing and NO production fallback |
| **Single non-RT worker** | `NativeShowSaveWorker` | KEEP Show I/O on worker, not on callback; no extra per-channel/per-plugin worker |

## Stop rules — prevents return of mixed engines

1. The approved reference GUI is the *workflow authority*. Native accepted snapshots, stable ChannelIds, real device pins and ACK remain the *data/PCM authority*. Never let JS or a browser mock own audio routing or create fake FX.
2. There is **one** `audioDeviceIOCallbackWithContext` production entry point and **one** selected render owner at any time. Do not run M4 and dynamic PCM, or duplicate native vendor VST3 instances.
3. New channels, Group, FX Return and WIRE must go into the **universal ChannelId graph**. No new business feature is allowed to extend fixed 10CH/M4 design, except fixes for actual physical audio reliability.
4. Freeze old plugin-feature experiments; preserve external #15 0FX crackle evidence and driver safety research (including draft #251). No destructive deletion or premature PR closure while hardware equivalence is unknown.
5. When universal graph passes real M4 migration/production gates, **remove** M4 callback selection, ordinal-as-identity adapters and legacy CH1 special cases in the **same integration PR**. The real diagnostic tone/capture remains a separate legitimate service, not a mixer.
6. Integration #270 alone certifies exact combined GUI/native SHA, Windows CTest/Chromium, VST/editor/Show parity and measured physical audio. Do not mark GUI as LIVE from screenshots or offline data.

## Decommission gates (NOT met yet)

- Real 10CH + 4AUX, MAIN/MONITOR, CH1 original vendor/Orbit/editor and Show state are rendered by the same accepted ChannelId graph.
- Normal continuous fader/MUTE/SOLO/SEND controls remain audible without mandatory device restart; no lost plugin tail or duplicated dry output.
- Native ACK/epoch/revision, output disarm/rearm and physical sparse port map are verified.
- Windows exact-SHA build/CTest and physical ASIO/WASAPI 0FX + 1FX FAT pass.

**Result:** no obsolete active stereo plugin engine remains available from the diagnostic fallback; current M4 compatibility is intentionally quarantined and will be retired only when the unified engine demonstrably replaces it.
22 changes: 21 additions & 1 deletion docs/FIRST_SOUND_FAT_QUICKSTART_20261101.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# ArSonMix — Windows First Sound / Hardware FAT
Date: 1 November 2026. Current production: **10 input channels + 4 AUX**, one JUCE callback, MAIN/MONITOR and native VST3. The experimental dynamic CH11/Group engine has **not** replaced the production callback. The outstanding 0FX hardware crackle issue is #15. This is a FAT **candidate**, not hardware certified or guaranteed zero physical latency.
Date: 1 November 2026. M1 hardware candidate addendum: 2 November 2026. Current production: **10 input channels + 4 AUX**, one JUCE callback, MAIN/MONITOR and native VST3. The experimental dynamic CH11/Group engine has **not** replaced the production callback. The outstanding 0FX hardware crackle issue is #15. This is a FAT **candidate**, not hardware certified or guaranteed zero physical latency.

## 1. Verify package
Extract the complete Windows Actions ZIP to a writable folder. `BUILD_PROVENANCE.json` must show the same `sourceCommit` as the GitHub run; EXE SHA-256 must equal `exeSha256`. Keep `portable_mode.txt`, never delete an existing `Studio` workspace. The file is a Windows x64 JUCE GUI executable; Microsoft Edge WebView2 Runtime and the correct audio hardware driver are required.
Expand Down Expand Up @@ -28,3 +28,23 @@ Send: (a) screenshot of active driver/rate/buffer/pins, (b) accepted CH01 patch
**PASS is hardware-grounded:** correct MAIN source path, verified mute/fader control, no wrong-endpoint output, clean 0FX wired audio for >=30 minutes on the recorded device/rate/buffer, followed by real plugin testing. A green Windows CTest/Chromium CI is not a substitute.

Historical full test matrix remains `docs/HARDWARE_FAT_GUI10_ENGINE_P012_20261027.md`. This packaged guide supersedes obsolete manual START AUDIO instructions.

## 5. M1 candidate — structured physical acceptance (not an M5 universal graph)

The **ArSonMix-M1-EXPERIMENTAL-Hardware-FAT-Windows-x64** workflow artifact is uploaded only if the exact PR SHA completes Windows compile, all CTests, packaging and ZIP/embedded-GUI SHA256 verification. A PR artifact is not a public stable release. The EXE preserves the existing **native M4 10CH + 4AUX** callback, not a live CH11/group universal engine. DO NOT apply an unqualified artifact on a live public-performance show.

One real device, one verified I/O clock, wired monitoring, LOW output gain and initially **0 VST3**. Start at a supported buffer of 256 samples, then 128 and 64 only after the earlier stage has passed; document actual negotiated values, don't assume the driver honored the request. For each supported buffer:

| Native check | Operator action and expected physical result | Hard fail / retain evidence |
|---|---|---|
| Unpatched startup | Launch without input patch; MAIN stays silent and unarmed | Any unexpected output/audio or wrong endpoint |
| Device isolation | Select real active ASIO or WASAPI endpoint; verify L/R physical pins, rate and epoch | Invalid pins, auto re-arm on hotplug, unexpected fallback |
| Real 0FX | Patch CH01 mic/line input, explicitly ARM; record 30-minute continuous wired output | Pops/crackle: Mark Crackle and Copy Full Report |
| Short-buffer gain | Move CH01 fader repeatedly and reverse while moving; listen for clicks, watch true meters | Zipper clicks, freezes, inconsistent physical gain |
| AUX gain/edge | Connect a validated SEND to AUX; change send and AUX return levels with effects bypassed | Silence despite accepted change, stale/reverted controls, double direct signal |
| Monitor isolation | If a separate hardware pair exists, enable MONITOR intentionally | MONITOR leaking to MAIN or shared hardware pair |
| Vendor/plugin | Only after 0FX clean, insert real VST3 and toggle bypass/editor | Stuck UI, plugin recreation, audio gap, FX state loss |
| Show lifecycle | Save and recall same route/plugin states, check output is never armed implicitly | Stale device epoch, missing FX, corrupt restoration |
| Safe shutdown | Stop/restart and unplug/replug device, reselect/ARM deliberately | Audio on unexpected pins, leaked resource or crash |

**Required evidence**: download artifact name and exact 40-character SHA from `BUILD_PROVENANCE.json`; SHA256 of installed EXE; physical device name/driver/rate/buffer and enabled port mapping; 0FX duration; crackle report if any; one short video or screenshots demonstrating CH01, AUX, MONITOR and Show. The test passes only for the exact device and configuration tested, and never proves every VST3 or absolute crash-proof operation.
24 changes: 24 additions & 0 deletions docs/M1_REALTIME_CORE_STABILIZATION_20261102.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# M1 — Realtime core stabilization (2026-11-02)

**Stacked source**: ENGINE #266 at `40a059785993cc6a4bb593020bf9749de92746f9`. No competing DSP, native callback, GUI or worker per channel.

This checkpoint repairs the Windows CTest AUX static/offline regression and corrects native fader/PAN de-zippering to remain **64 audio samples across variable callback frames** (4/16/32/12), including reverse direction. Existing live PRE/POST sends and AUX return faders retain their prepared 64-sample ramp; offline/no-live paths must not inherit old live AUX targets. All work uses fixed-size arrays and no new callback heap allocations.

The existing `RealtimeRoutePublisher` owns bounded retirement. New tests hold a real leased reader across two graph publications, verify refusal when the queue is full, and verify all four prepared owners are reclaimed after the reader leaves. All tests run in the existing CTest executables with no additional CI matrix.

**Runtime invariant:** `LiveAudioEngine::audioDeviceIOCallbackWithContext` is still M4 until the full CH1 external/Orbit owner, native vendor FX/editor/Show, physical input/output pins and monitor can migrate together. Never enable universal supportedOps or silently render the new graph alongside M4. Worker-only work belongs to existing control/Show-save processing, NOT the real-time callback.

**Remaining M1 release gates:** pass exact-SHA Windows MSVC/CTest, integrate a single full-fidelity ChannelId callback with atomic admission and no FX loss, then qualify ASIO/WASAPI and zero-FX crackle on actual hardware. This change alone is **not M1 complete**, not UAT, not acoustic FAT.

## Worker payload lifetime hardening
`NativeShowSaveWorker` validates Show IDs before reserving, releases snapshot/blob/closure memory immediately on start failure, and moves the completion closure rather than retaining a second copy after IO completion. The long-lived worker is reused; no new OS thread or realtime allocation has been introduced. Windows JUCE compilation and runtime verification are release gates.

## Exact CI evidence and hardware artifact scope (revision 2)
Windows run `41479462759` compiled successfully but 52/54 CTests passed. The remaining two failures were analyzed and corrected together:
1. Native `setAuxSendGain` / `setAuxBusGain` is **one atomic automation plane** even without separate strip controls, as exercised by `dedicated_aux_bus_test.cpp`. The old conditional gate silenced actual physical AUX level edits. In the routing CTest, a newly built `PreparedMixerBlock` establishes fresh compiled defaults, while an already automated block retains its explicit target.
2. The graph-retirement test needed to count the rejected candidate's destructor too: 3 original accepted + 1 rejected + 1 newly accepted = **5 distinct prepared instances**. The lifetime test checks that saturation safely rejects and reader-owned graphs are not reclaimed early.

This patch also authorizes **one** exact-branch `M1-EXPERIMENTAL` GitHub Actions artifact **only after** all CTests and package/provenance validation pass. This does not enable universal routing/CH11, promote stable release, or change hardware patch/ARM policy. The packaged FAT guide now includes explicit pass/fail cases for wired 0FX ASIO, AUX/monitor, state recall and hotplug. No parallel CI matrix or redundant always-on worker.

## 2026-11-03 single production authority cleanup
Real-time callback now routes through the explicit `NativeRenderAuthority` decision. The no-longer-reachable legacy stereo FX processing code has been removed from the diagnostic-only path; this does not change accepted 10CH/4AUX production routing. `PreparedNativeMixerSession.h` remains tested but is no longer listed in the shipping GUI application target. See `docs/ENGINE_RUNTIME_AUTHORITY_20261103.md` for the decommission map and strict migration gates.
Loading
Loading