Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
3a90163
feat(device): prepare exact sparse live input-port masks with device …
masarray Oct 27, 2026
79fbc33
feat(audio): nonblocking epoch/revision route publisher with deferred…
masarray Oct 27, 2026
dd64b25
fix(rt): unpublish immediately gates audio even when retired ring is …
masarray Oct 27, 2026
402c58f
test(rt): sparse enabled pins, generation fencing, atomic snapshots a…
masarray Oct 27, 2026
1372fb6
feat(native): opt-in real 10-channel dry callback renderer with exact…
masarray Oct 27, 2026
31a9a7c
fix(native): hold JUCE var assignment lifetime and bound callback por…
masarray Oct 27, 2026
20f6853
safety(audio): retain explicit dry-lab silence after hotplug instead …
masarray Oct 27, 2026
59aab26
feat(native): wire opt-in DRY 10-channel routing into verified JUCE c…
masarray Oct 28, 2026
0182c4c
fix(native): expose truthful dry LAB levels and reset stale peaks on …
masarray Oct 28, 2026
90753a0
safety(native): prohibit plugin graph edits and snapshot actions duri…
masarray Oct 28, 2026
d30d44c
feat(ui bridge): expose explicit native ten-channel dry Apply/Stop wi…
masarray Oct 28, 2026
3a90b18
feat(ui): add compact real hardware routing inspector with native tra…
masarray Oct 28, 2026
efea4ff
safety(live): require muted output before applying lab routes and mut…
masarray Oct 28, 2026
f3e7ae9
feat(audio): block-boundary 256-sample de-click and precise stale-dev…
masarray Oct 28, 2026
f2df029
build: compile native live dry-routable JUCE host and P1E concurrent …
masarray Oct 28, 2026
816df95
ci: compile and execute P1E native route publication tests in existin…
masarray Oct 28, 2026
26aa1b1
fix(ui): truthful dry LAB 10-channel metering/status and safe mute-be…
masarray Oct 28, 2026
37372c4
test(native ui): protect opt-in dry routing truth, safe ACK, device e…
masarray Oct 28, 2026
5fcd7aa
docs: real ASIO 10-input dry routing operator how-to, limits and phys…
masarray Oct 28, 2026
beeb881
ci: assert native dry LAB UI/engine parity in Windows Node contract gate
masarray Oct 28, 2026
a311c36
merge latest main P3 backup + P1D #118 into live P1E routing lab with…
masarray Oct 28, 2026
000e56e
fix(rt): eliminate device-start vs GUI status routing-map data race a…
masarray Oct 28, 2026
1bc4c1c
fix(P1 rt): replace unsafe reader count with seq-cst reader admission…
masarray Oct 28, 2026
1281a54
fix(P2 ui): bind routing drafts to exact audio-device epoch; reset/de…
masarray Oct 28, 2026
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
3 changes: 2 additions & 1 deletion .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ jobs:
'tests/native_artifact_packaging_contract_test.mjs'
'tests/portable_workspace_contract_test.mjs'
'tests/plugin_vault_contract_test.mjs'
'tests/live_routing_ui_contract_test.mjs'
'tests/studio_backup_contract_test.mjs'
)
node --test $contracts
Expand All @@ -90,7 +91,7 @@ jobs:
-DBUILD_TESTING=ON
-DJUCE_WEBVIEW2_PACKAGE_LOCATION="${{ github.workspace }}/.deps"
- name: Build executable and native RT tests
run: cmake --build build --config Release --target ARMixConsole ARMixMixerRoutingTests ARMixChannelRoutingContractTests ARMixChannelSendTests ARMixPreparedMixerBlockTests ARMixWorkspaceTests ARMixVaultTests ARMixBackupTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixFxBypassEnvelopeTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2
run: cmake --build build --config Release --target ARMixConsole ARMixMixerRoutingTests ARMixChannelRoutingContractTests ARMixChannelSendTests ARMixPreparedMixerBlockTests ARMixLiveRoutingEpochTests ARMixWorkspaceTests ARMixVaultTests ARMixBackupTests ARMixOrbitPhaseTests ARMixOrbitControlTests ARMixOrbitMotionTests ARMixOrbitDistanceTests ARMixFxBypassEnvelopeTests ARMixDearVrPolarPolicyTests ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixVirtualClockSoakTests ARMixCadenceTests ARMixCrackleWindowTests ARMixHealthTests ARMixPolicyTests ARMixPeriodEvidenceTests ARMixLifecycleTests ARMixWasapiProbeTests ARMixDualJuceTests ARMixClockSizingTests ARMixIndependentFormatTests ARMixRecoveryTests ARMixStreamWatchdogTests ARMixBridgeContinuityTests ARMixEndpointPolicyTests ARMixEndpointGuardTests ARMixAsioPolicyTests ARMixAsioBackendTests ARMixAsioRegistryIdentityTests ARMixDirectFenceTests --parallel 2
- name: Test realtime control primitives
run: ctest --test-dir build -C Release --output-on-failure
- name: Package verified JUCE GUI for hardware FAT
Expand Down
5 changes: 4 additions & 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/app.js web/bridge.js web/monitor.js)

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/PreparedMixerBlock.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/PluginVault.h src/PortableWorkspace.h src/StudioBackup.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.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/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/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/PreparedMixerBlock.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/PluginVault.h src/PortableWorkspace.h src/StudioBackup.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.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/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/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 Expand Up @@ -59,6 +59,9 @@ if(BUILD_TESTING)
add_executable(ARMixPreparedMixerBlockTests tests/prepared_mixer_block_test.cpp)
target_compile_features(ARMixPreparedMixerBlockTests PRIVATE cxx_std_20)
add_test(NAME TenChannelEndToEndPreparedAudioRender COMMAND ARMixPreparedMixerBlockTests)
add_executable(ARMixLiveRoutingEpochTests tests/live_port_epoch_publisher_test.cpp)
target_compile_features(ARMixLiveRoutingEpochTests PRIVATE cxx_std_20)
add_test(NAME P1ELivePortGenerationRevisionAndRealtimeRetirement COMMAND ARMixLiveRoutingEpochTests)
add_executable(ARMixOrbitPhaseTests tests/orbit_phase_test.cpp)
target_compile_features(ARMixOrbitPhaseTests PRIVATE cxx_std_20)
add_test(NAME VstAzimuthOrbitRamp COMMAND ARMixOrbitPhaseTests)
Expand Down
36 changes: 36 additions & 0 deletions docs/P1E_NATIVE_DRY_LAB_FAT_20261028.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# P1E — REAL 10-CHANNEL DRY ASIO/WASAPI FAT LAB (2026-10-28)

**Native code, not just another offline graph.** The owner-approved ten-strip P1D `PreparedMixerBlock` is now callable from the live JUCE audio callback in a **separate, explicit, fail-closed DRY ROUTING LAB**. This milestone exists to prove **actual physical input channel separation, mono/stereo hardware patching, routing graph activation and Windows device continuity**, while preserving the current VST3 CH1 production path whenever the lab is OFF.

**The lab is not a finished performance mixer.** It deliberately has NO VST3 inserts, AUX sends, independent channel fader binding, automatic portable device map restore, multi-output patchbay, PDC or FX Tail guarantees. CH2–CH10 rack buttons remain truthful preview. Never advertise ten live VST3 chains or approved #15 zero-FX crackle status based on this PR alone.

## Open it on real Windows hardware

1. Build Windows artifact from **the passing P1E PR head**, do NOT use a stale previously downloaded build. Set headphone volume physically LOW.
2. In **AUDIO SETUP**, choose and verify the actual ASIO/WASAPI DIRECT interface and enable the needed physical input channels in its active input mask. Do not expect `initialise(1,2)` to activate all channels automatically.
3. If a VST3 was loaded in CH1, save/stop it and remove it from the chain before the dry test. Disable Smart Clock / independent capture/render, set SIGNAL CHECK to NORMAL, and leave the verified DIRECT route selected.
4. Open **SIGNAL CHECK**, click **MUTE OUTPUT**, then **ROUTING LAB · 10 CH**. Only channels reported from the **actual opened device's enabled input-channel bitmask** appear in the selectors. If the port you need does not appear, enable it in AUDIO SETUP, which may restart the device; do not lie with phantom dropdown ports.
5. Example with an active 8-input interface: set CH1 **MONO** input 3; CH2 **STEREO** input 5(L) / 6(R); CH3 **MONO** input 1. All other CH4–CH10 **NONE**. Choose a low initial per-strip level, e.g. −18 or −12 dB. Press **APPLY TO NATIVE AUDIO**; wait for explicit native ACK, never infer audio commit from UI selection alone.
6. Close the routing lab, go back to SIGNAL CHECK, and deliberately **UNMUTE OUTPUT**. Stimulate each physical input separately and confirm that only the corresponding path is heard. Then try nonadjacent L/R mappings, duplicate input fanout and a muted/None channel.
7. MUTE OUTPUT and press **STOP LAB**. STOP also forces output mute before returning to the original CH1 VST3 engine; unmute only after selecting/validating the wanted signal path.

### Safety and determinism

- The lab has a separate exact input registry: `juce::BigInteger activeInputChannels` is enumerated **off callback**, mapping actual hardware ID to JUCE's packed callback pointer index. Callback channel count is checked against the prepared map for every buffer. Max 256 enabled pins accepted; larger counts fail closed.
- A monotonic **device epoch** invalidates prepared routes on device stop/restart. An active lab with a stale device does NOT fall through to old CH1 audio; it outputs silence until the operator explicitly reapplies or stops the lab. UI shows **DRY LAB STALE — SILENT**.
- Graphs compile on the message/control thread; a single atomic pointer is published with `expectedRevision` and `deviceEpoch`. Callback obtains a no-heap lease before accessing the prepared graph. Old buffers are retired only when all callback readers leave. Excess rapid edits receive a specific retry response instead of freeing audio-owned memory.
- Channel processing is bounded, uses P1D's preallocated fixed workspace, has no VST instantiation or lock in the audio callback. Variable callback quanta are chunked into the prepared hard-frame limit. On invalid buffer or stale epoch, output must be silence.
- An initial 256-sample bounded de-click fade on a new route revision starts at the previously emitted output sample. This is a topology-switch mitigation, **not yet proof of click-free behavior at any buffer rate/driver**.
- MUTE OUTPUT is a *required precondition* of every APPLY; there is never an automatic audible route to an unknown speaker. STOP forces output mute. FX add/remove, preset recall, Smart Clock mode and other diagnostic modes are blocked while LAB is active.
- The lab sends dry output to actual render callback channels 1 and 2 (0-based indices 0/1); additional output channels are cleared. No hidden ASRC/split-clock buffering is introduced on a direct ASIO path.
- If the selected input is no longer available, no plugin can synthesize signal from a dummy channel and callback output remains silent. No route is persisted to a future machine until endpoint/physical-port identities have been verified by a portable-source migration workflow.

## Engineering validation

`ARMixLiveRoutingEpochTests` includes sparse 5/2/9 input mapping, duplicate/invalid masks, generation mismatch, revisions, ABA-safe reader-held graph lifetime, full retirement queue and explicit STOP fail-closed, 8,000 sequential publications and 1,000 concurrent read/publish cycles, with all C++ assertions enabled even in Release.

`tests/live_routing_ui_contract_test.mjs` asserts the opt-in event, status/ACK, mute requirements, user port selector and preservation of the original non-native VST3-preview strips. Existing Windows native build compiles the P1E JUCE header and all previous native realtime/Orbit/FX tests; Node checks validate monitor.js.

**Real-device acceptance checklist (NOT YET PASSED):** ASIO 2/4/8 inputs; non-contiguous enabled active mask; mono→both speakers and stereo L/R isolation; unplug/replug and driver re-selection silences until remap; rapid edits/STOP while audio runs, no heap/click, 0 VST case compared with issue #15; 48/96 kHz, short buffers and controlled low-volume headphones; compare DIRECT to independent-clock diagnostics only outside LAB. Preserve logs for genuine device/render errors.

**Merge gate:** exact-head Windows Native CTest + Chromium smoke, inspect binary artifact/provenance from Actions, reconcile all parallel PRs against latest `main` before merge. **Native GUI faders for CH2–CH10 and channel-VST3 processing are not delivered in this PR.** Follow-on P1F must implement per-strip plugin instance ownership, negotiated mono/stereo bus layouts and authentic mixer fader/FX bindings after the 0-VST3 hardware signal-path FAT is clean.
136 changes: 136 additions & 0 deletions engine/core/RealtimeRoutePublisher.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <array>
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <utility>

// One control-thread writer and any number of bounded RT readers.
// IMPORTANT: Separate "reader count" and "active pointer" atomics DO NOT
// protect reclamation; a reader can enter after a zero-count observation
// and acquire a pointer which is being freed. Gate reader reservation and
// writer publication with ONE sequentially-consistent atomic state.
//
// State bit 0: writer publishing/unpublishing (RT fails closed, NO SPIN).
// High bits: +2 per active reader. Any reader registered before writer
// publication retains old lifetime until it releases the lease.
// In contrast, readers registering after the gate clears see only NEW active.
// Retired memory is reclaimed only on control thread, and only when there
// are no preexisting readers. No heap/lock/device call on RT read path.
namespace armix::rt {
template<class Prepared, std::size_t RetiredCapacity=8>
class RealtimeRoutePublisher final {
static_assert(RetiredCapacity>=2);
static constexpr std::uint32_t writerFlag=1U, readerUnit=2U;
public:
struct Snapshot final {
std::uint64_t deviceEpoch=0;
std::uint64_t graphRevision=0;
std::unique_ptr<Prepared> prepared;
};
enum class Result : std::uint8_t {
applied, invalidCandidate, staleDevice, staleRevision, retirementFull
};
class ReadLease final {
public:
explicit ReadLease (RealtimeRoutePublisher& owner) noexcept : owner_(&owner) {
auto activity=owner_->activity_.load(std::memory_order_seq_cst);
// Do not spin/wait inside the audio callback. One silent block is
// preferable to scheduling jitter while control thread publishes.
if((activity&writerFlag)!=0 || activity>UINT32_MAX-readerUnit)
return;
if(!owner_->activity_.compare_exchange_strong(
activity,activity+readerUnit,
std::memory_order_seq_cst,std::memory_order_seq_cst))
return;
registered_=true;
item_=owner_->active_.load(std::memory_order_seq_cst);
}
ReadLease(const ReadLease&)=delete;
ReadLease& operator=(const ReadLease&)=delete;
ReadLease(ReadLease&&)=delete;
ReadLease& operator=(ReadLease&&)=delete;
~ReadLease() noexcept {
if(registered_)
owner_->activity_.fetch_sub(readerUnit,std::memory_order_seq_cst);
}
const Snapshot* get(std::uint64_t currentEpoch) const noexcept {
return item_ && item_->deviceEpoch==currentEpoch
? item_ : nullptr;
}
private:
RealtimeRoutePublisher* owner_;
const Snapshot* item_=nullptr;
bool registered_=false;
};

RealtimeRoutePublisher()=default;
RealtimeRoutePublisher(const RealtimeRoutePublisher&)=delete;
RealtimeRoutePublisher& operator=(const RealtimeRoutePublisher&)=delete;

// CONTROL thread only. Expected revision is last acknowledged revision;
// candidate is fully preallocated and validated before any RT publication.
Result publish(std::unique_ptr<Snapshot> next,
std::uint64_t expectedRevision,
std::uint64_t deviceEpochNow) noexcept {
if(!next || !next->prepared || next->deviceEpoch==0 ||
next->graphRevision==0 || next->graphRevision<=expectedRevision)
return Result::invalidCandidate;
if(next->deviceEpoch!=deviceEpochNow)
return Result::staleDevice;
if(expectedRevision!=revision_)
return Result::staleRevision;
pollRetirement();
if(owned_ && retiredCount_>=RetiredCapacity)
return Result::retirementFull;
// Single writer. Publish/retire happens only with the low-bit gate set.
activity_.fetch_or(writerFlag,std::memory_order_seq_cst);
if(owned_)retired_[retiredCount_++]=std::move(owned_);
owned_=std::move(next);
active_.store(owned_.get(),std::memory_order_seq_cst);
activity_.fetch_and(~writerFlag,std::memory_order_seq_cst);
revision_=owned_->graphRevision;
return Result::applied;
}

// Immediately gate the last route to silence. Do NOT delete a graph
// while the audio callback could own a ReadLease to its snapshot.
void unpublish() noexcept {
activity_.fetch_or(writerFlag,std::memory_order_seq_cst);
active_.store(nullptr,std::memory_order_seq_cst);
activity_.fetch_and(~writerFlag,std::memory_order_seq_cst);
revision_=0;
pollRetirement();
if(!owned_)return;
if(retiredCount_<RetiredCapacity)
retired_[retiredCount_++]=std::move(owned_);
// Saturated: preserve unpublished ownership until quiescent.
// The next publication is rejected unless safe retirement completes.
}

// CONTROL only: cannot reclaim any snapshot whose pointer might still
// be held by a reader which registered before its publication.
bool pollRetirement() noexcept {
if((activity_.load(std::memory_order_seq_cst)&~writerFlag)!=0)
return false;
for(std::size_t i=0;i<retiredCount_;++i)retired_[i].reset();
retiredCount_=0;
return true;
}
[[nodiscard]] ReadLease acquire() noexcept {return ReadLease(*this);}
std::uint64_t lastRevision() const noexcept {return revision_;} // CONTROL
std::size_t pendingRetirements() const noexcept {return retiredCount_;} // CONTROL
bool readersPresent() const noexcept {
return (activity_.load(std::memory_order_seq_cst)&~writerFlag)!=0;
}
private:
std::atomic<const Snapshot*> active_{nullptr};
std::atomic<std::uint32_t> activity_{0};
std::unique_ptr<Snapshot> owned_;
std::array<std::unique_ptr<Snapshot>,RetiredCapacity> retired_{};
std::size_t retiredCount_=0;
std::uint64_t revision_=0;
};
} // namespace armix::rt
Loading
Loading