Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
60ddb88
feat(P0): generation-safe device recovery and bounded retry policy wi…
masarray Oct 25, 2026
2790d46
feat(P0): generation-safe device recovery and bounded retry policy wi…
masarray Oct 25, 2026
472a451
build(P0): require generation-safe device recovery Release CTest
masarray Oct 25, 2026
afde388
ci(P0): test device lifecycle and rollback policies
masarray Oct 25, 2026
a43004e
feat(P0): provenance-correct RT counters for separate capture/render …
masarray Oct 25, 2026
53c06c8
test(P0): audit independent stream frame count provenance and invalid…
masarray Oct 25, 2026
cbc4ba2
build(P0): register split-stream telemetry header
masarray Oct 25, 2026
7467541
test(P0): include split-source/render counters in CTest
masarray Oct 25, 2026
1ad5e9f
ci(P0): build independent clock stream diagnostics CTest
masarray Oct 25, 2026
7a58838
test(P0): exercise bounded clock bridge overflow, starvation and reco…
masarray Oct 25, 2026
5a1b2bf
docs(P0): exact lifecycle integration requirements and remaining hard…
masarray Oct 25, 2026
ba124c6
feat(P0): connect separate capture/render RT callbacks through prepar…
masarray Oct 25, 2026
2f219fe
test(P0): deterministic separate source/render adapter pipeline with …
masarray Oct 25, 2026
41e3df8
build(P0): require actual split clock PCM pipeline in deterministic CI
masarray Oct 25, 2026
76db4c0
ci(P0): build clock-domain pipeline with split capture/render callbacks
masarray Oct 25, 2026
db0fbd2
docs(P0): record physical backend gap, tested split callback core and…
masarray Oct 25, 2026
624e290
fix(P0): count endpoint-loss retries, prohibit restart storms and arm…
masarray Oct 25, 2026
2409830
test(P0): validate bounded endpoint-loss cooldown, no flapping restar…
masarray Oct 25, 2026
ba1f4af
feat(P0): make backend and recovery activation truth explicit in one-…
masarray Oct 25, 2026
6431f16
feat(P0): implement non-activated JUCE dual-device adapter with indep…
masarray Oct 25, 2026
dffaccd
fix(P0): let independent capture endpoint negotiate its own native ra…
masarray Oct 25, 2026
abf61c2
build(P0): compile-check real JUCE split-device adapter without produ…
masarray Oct 25, 2026
1739946
build(P0): include experimental independent JUCE device transport in …
masarray Oct 25, 2026
4f6d09d
docs(P0): record implementation and non-activation guard of real two-…
masarray Oct 25, 2026
43783cd
feat(P0): enable opt-in 0-FX physically independent JUCE capture/rend…
masarray Oct 25, 2026
af9946d
fix(P0): enforce 0-FX bridge activation contract at engine graph muta…
masarray Oct 25, 2026
1d7fa78
feat(P0): native opt-in independent capture/render route with fallbac…
masarray Oct 25, 2026
5b66c66
feat(P0): opt-in experimental independent-clock dry routing in native…
masarray Oct 25, 2026
524ecd3
fix(diag): read input latency from actual capture endpoint while Smar…
masarray Oct 25, 2026
07fe40c
fix(test): separate distinct stream and bridge status types for MSVC …
masarray Oct 25, 2026
3985809
test(P0): cover opt-in independent JUCE transport, rollback, xrun pro…
masarray Oct 25, 2026
d21c4fa
ci(P0): require native independent-stream activation and rollback con…
masarray Oct 25, 2026
840cf95
docs(P0): accurately distinguish live opt-in 0-FX split adapter from …
masarray Oct 25, 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 @@ -43,6 +43,7 @@ jobs:
node --test tests/smart_audio_ard_contract_test.mjs
node --test tests/p0_diagnostic_contract_test.mjs
node --test tests/smart_audio_diagnostic_contract_test.mjs
node --test tests/p0_live_split_contract_test.mjs
- name: Configure Windows x64
shell: pwsh
run: >
Expand All @@ -51,7 +52,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 ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixHealthTests ARMixPolicyTests --parallel 2
run: cmake --build build --config Release --target ARMixConsole ARMixRTTests ARMixPresetTests ARMixDiagnosticTests ARMixClockBridgeTests ARMixHealthTests ARMixPolicyTests ARMixRecoveryTests ARMixSplitTelemetryTests ARMixIndependentPipelineTests --parallel 2
- name: Test realtime control primitives
run: ctest --test-dir build -C Release --output-on-failure
- name: Package native executable
Expand Down
11 changes: 10 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/PluginCatalog.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h)
target_sources(ARMixConsole PRIVATE src/Main.cpp src/LiveAudioEngine.h src/PluginCatalog.h src/DiagnosticsRecorder.h src/StereoPan.h src/NativePresetArchive.h src/VstBusLayout.h src/LiveGraphHandoff.h src/DiagnosticTone.h engine/core/RealtimeHealthHistogram.h engine/device/AdaptiveClockBridge.h engine/device/AudioProfilePolicy.h engine/device/DeviceRecoveryPolicy.h engine/device/SplitStreamTelemetry.h engine/device/IndependentClockPipeline.h engine/device/JuceIndependentDeviceAdapter.h)
target_compile_definitions(ARMixConsole PRIVATE
JUCE_WEB_BROWSER=1
JUCE_USE_WIN_WEBVIEW2=1
Expand All @@ -40,6 +40,15 @@ target_link_libraries(ARMixConsole PRIVATE

include(CTest)
if(BUILD_TESTING)
add_executable(ARMixIndependentPipelineTests tests/independent_clock_pipeline_test.cpp)
target_compile_features(ARMixIndependentPipelineTests PRIVATE cxx_std_20)
add_test(NAME IndependentClockPipeline COMMAND ARMixIndependentPipelineTests)
add_executable(ARMixSplitTelemetryTests tests/split_stream_telemetry_test.cpp)
target_compile_features(ARMixSplitTelemetryTests PRIVATE cxx_std_20)
add_test(NAME SplitStreamTelemetry COMMAND ARMixSplitTelemetryTests)
add_executable(ARMixRecoveryTests tests/device_recovery_policy_test.cpp)
target_compile_features(ARMixRecoveryTests PRIVATE cxx_std_20)
add_test(NAME DeviceRecoveryPolicy COMMAND ARMixRecoveryTests)
add_executable(ARMixPolicyTests tests/audio_profile_policy_test.cpp)
target_compile_features(ARMixPolicyTests PRIVATE cxx_std_20)
add_test(NAME CapabilityAudioProfilePolicy COMMAND ARMixPolicyTests)
Expand Down
27 changes: 27 additions & 0 deletions docs/P0_DEVICE_RECOVERY_INTEGRATION_HANDOFF.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# P0 backend recovery handoff — generation-safe control plane

**Updated:** 2026-10-25
**Reference:** [P0 issue #15](https://github.com/masarray/arsonmix/issues/15), [ARD v1](ARD_SMART_AUDIO_ENGINE_V1_2026-10-25.md), [Smart Audio implementation blueprint](SMART_AUDIO_ENGINE_IMPLEMENTATION_BLUEPRINT.md)

## Implemented in this engineering tranche

- Pure `DeviceRecoveryPolicy` state machine for the message/control thread. States: stopped, discovering, preparing, running, degraded, recovering, failed. Every prepare/discovery completion must include the generation issued by its start. A late completion for a retired device is rejected rather than re-arming invalid PCM pointers.
- On endpoint loss: require render silence and device retirement **before** acquiring replacement. Retry uses bounded backoff 100 ms–10 seconds, maximum eight consecutive failures, and explicit terminal failure.
- A configuration is **eligible** for stable persistence only after 30 seconds of healthy callbacks. This is a policy primitive, not a claim that audible playback is clean.
- Pure `SplitStreamTelemetry`: lock-free independent capture/render frames, dropped input frames, bridge starvation frames and invalid-buffer counters, with separate generation numbers. These are not equivalent to Windows driver output xruns; report source provenance.
- `IndependentClockPipeline` now connects two **independently invoked callback interfaces** to the prepared FIR/ASRC and telemetry. It is JUCE-independent and tested against separate synthetic source/render callback frame counts.
- `JuceIndependentDeviceAdapter` now implements two actually separate JUCE AudioDeviceManager callback hosts: one input-only clock, one output-only clock, capture FIFO producer, render-master FIR consumer and bounded render blocks. Its source compiles into the Windows app and an explicitly opt-in **EXPERIMENTAL 0-FX** route activates separate one-sided JUCE device managers using controlled joined-device shutdown, bridge preparation and rollback. It is NOT a general plugin-host backend, nor hardware-certified. Independent capture rate is negotiated separately; output uses selected render period.
- Release-active CTests for generation cancellation, state transitions, bounded delays, stable eligibility, recording different capture/render frame rates, and FIFO overflow/starvation/re-prime.

## Production integration is **not yet complete**

The `DeviceRecoveryPolicy` planner is not yet wired to runtime AUTO/STABLE control. The default JUCE joined route still cannot expose independent clocks; the optional Smart I/O 0-FX path uses separately opened capture/render device managers and reports real bridge frame starvation. The true P0 remaining acceptance scope is:

1. Replace the current manual Smart I/O 0-FX opt-in with capability-driven AUTO/STABLE selection and a device-identity/period evidence provider. The first adapter has independent callbacks but no Windows IAudioClient3 period/clock service verification or event-driven render-padding instrumentation.
2. Extend the split route beyond zero FX through a safe, independently prepared VST3 graph handoff and ensure direct ASIO/shared-clock fast path remains free of extra SRC. The 25 ms bridge target is experimental, NOT a universal low-latency claim.
3. Attach this `DeviceRecoveryPolicy` to a real control executor that serializes COM/device change transitions, invalidates and drains old callbacks, safely owns graph/plugin lifetimes, and makes stable profile persistence transactional.
4. Integrate `SplitStreamTelemetry` into native **COPY FULL REPORT**: actual split route now exports FIFO occupancy, source frame drop, bridge underflow/priming frames, and ppm; real driver render underruns remain unavailable. Host callback timing is not an xrun.
5. Add deterministic rate-mismatch jitter and device restart failure tests plus resampling fidelity/latency/CPU acceptance gates; run automated Windows/MSVC and GUI checks.
6. Perform one consolidated hardware acceptance campaign after P0 stages are integrated. Until then mark P0 #15 OPEN and physical crackling **unresolved**.

**User workflow:** no recurring manual tests while the engineering work proceeds. An experimental **ENABLE SMART I/O · 0 FX** control is in the native SIGNAL CHECK overlay only, and COPY FULL REPORT includes its actual activation state. This control is *not* the final AUTO/STABLE selector. The approved mixer GUI v0.8 remains locked.
150 changes: 150 additions & 0 deletions engine/device/DeviceRecoveryPolicy.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <algorithm>
#include <array>
#include <cstdint>

namespace armix::device
{
// Pure control-thread state machine. All callbacks pass generation tokens;
// delayed asynchronous completions from retired devices cannot revive a stale
// session. This module NEVER opens devices or touches the audio callback.
enum class SessionState : std::uint8_t
{
stopped, discovering, preparing, running, degraded, recovering, failed
};
enum class DeviceEvent : std::uint8_t
{
start, discoveryOk, discoveryFailed, preparationOk, preparationFailed,
callbackHealthy, instability, endpointLost, recover, stop
};
enum class RecoveryAction : std::uint8_t
{
none, enumerateDevices, prepareCandidate, publishCandidate,
silenceAndRetire, scheduleRetry, persistStable, reportFailure
};
struct RecoveryDecision
{
SessionState state = SessionState::stopped;
RecoveryAction action = RecoveryAction::none;
std::uint64_t generation = 0;
std::uint64_t retryAfterMs = 0;
bool accepted = false;
};
class DeviceRecoveryPolicy final
{
public:
// One controller, one control-thread owner. nowMs must be monotonic.
RecoveryDecision apply (DeviceEvent event, std::uint64_t token, std::uint64_t nowMs) noexcept
{
if (event == DeviceEvent::stop)
{
++generation_; state_ = SessionState::stopped; consecutiveFailures_ = 0;
stabilityArmed_ = false; stableSince_ = 0; nextRetry_ = 0;
return result (RecoveryAction::silenceAndRetire, 0, true);
}
if (event == DeviceEvent::start)
{
if (state_ != SessionState::stopped && state_ != SessionState::failed)
return result (RecoveryAction::none, 0, false);
++generation_; state_ = SessionState::discovering;
consecutiveFailures_ = 0; stabilityArmed_ = false; stableSince_ = 0; nextRetry_ = 0;
return result (RecoveryAction::enumerateDevices, 0, true);
}
if (token != generation_) return result (RecoveryAction::none, 0, false);

switch (event)
{
case DeviceEvent::discoveryOk:
if (state_ != SessionState::discovering) break;
state_ = SessionState::preparing;
return result (RecoveryAction::prepareCandidate, 0, true);
case DeviceEvent::preparationOk:
if (state_ != SessionState::preparing) break;
state_ = SessionState::running;
stableSince_ = nowMs; stabilityArmed_ = true;
return result (RecoveryAction::publishCandidate, 0, true);
case DeviceEvent::callbackHealthy:
if (state_ == SessionState::running && stabilityArmed_
&& nowMs >= stableSince_ && nowMs - stableSince_ >= 30000)
{
stabilityArmed_ = false;
consecutiveFailures_ = 0; // reset only after sustained health
return result (RecoveryAction::persistStable, 0, true);
}
if (state_ == SessionState::degraded)
{
state_ = SessionState::running;
stableSince_ = nowMs; stabilityArmed_ = true;
return result (RecoveryAction::none, 0, true);
}
break;
case DeviceEvent::instability:
if (state_ == SessionState::running)
{
state_ = SessionState::degraded; stabilityArmed_ = false; stableSince_ = 0;
return result (RecoveryAction::none, 0, true);
}
break;
case DeviceEvent::endpointLost:
if (state_ == SessionState::running || state_ == SessionState::degraded
|| state_ == SessionState::preparing || state_ == SessionState::discovering)
{
++consecutiveFailures_; ++generation_;
stabilityArmed_ = false; stableSince_ = 0;
if (consecutiveFailures_ >= 8)
{
state_ = SessionState::failed; nextRetry_ = 0;
return result (RecoveryAction::silenceAndRetire, 0, true);
}
state_ = SessionState::recovering;
const auto delay = backoffFor (consecutiveFailures_);
nextRetry_ = nowMs + delay;
return result (RecoveryAction::silenceAndRetire, delay, true);
}
break;
case DeviceEvent::discoveryFailed:
case DeviceEvent::preparationFailed:
if (state_ == SessionState::discovering || state_ == SessionState::preparing)
{
++consecutiveFailures_;
if (consecutiveFailures_ >= 8)
{
++generation_; state_ = SessionState::failed; nextRetry_ = 0;
return result (RecoveryAction::reportFailure, 0, true);
}
++generation_; state_ = SessionState::recovering;
// Bounded backoff, 100ms to 10s; no uncontrolled spin.
const auto delay = backoffFor (consecutiveFailures_);
nextRetry_ = nowMs + delay;
return result (RecoveryAction::scheduleRetry, delay, true);
}
break;
case DeviceEvent::recover:
if (state_ == SessionState::recovering && nowMs >= nextRetry_)
{
state_ = SessionState::discovering;
return result (RecoveryAction::enumerateDevices, 0, true);
}
break;
default: break;
}
return result (RecoveryAction::none, 0, false);
}
std::uint64_t generation() const noexcept { return generation_; }
SessionState state() const noexcept { return state_; }
std::uint64_t nextRetryMs() const noexcept { return nextRetry_; }
private:
static std::uint64_t backoffFor (unsigned consecutive) noexcept
{
const auto shift = std::min (consecutive - 1, 7u);
return std::min<std::uint64_t> (10000, 100ull << shift);
}
RecoveryDecision result (RecoveryAction action, std::uint64_t delay, bool accepted) const noexcept
{ return {state_,action,generation_,delay,accepted}; }
SessionState state_ = SessionState::stopped;
std::uint64_t generation_ = 0, stableSince_ = 0, nextRetry_ = 0;
unsigned consecutiveFailures_ = 0;
bool stabilityArmed_ = false;
};
} // namespace armix::device
51 changes: 51 additions & 0 deletions engine/device/IndependentClockPipeline.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include "AdaptiveClockBridge.h"
#include "SplitStreamTelemetry.h"

namespace armix::device
{
// Concrete producer/consumer audio pipeline for *two independently clocked*
// callbacks. Ownership, device lifecycle and stream-format adaptation belong
// to a Windows backend adapter. This is intentionally JUCE-independent.
// prepare() only with both callbacks stopped; capture()/render() RT-safe.
class IndependentClockPipeline final
{
public:
bool prepare (double captureHz, double renderHz, int channels,
int fifoFrames, double targetLatencyMs)
{
if (!bridge_.prepare(captureHz,renderHz,channels,fifoFrames,targetLatencyMs))
return false;
telemetry_.sourceStarted();
telemetry_.renderStarted();
return true;
}
int capture (const float* const* input,int channels,int frames) noexcept
{
const int written=bridge_.push(input,channels,frames);
telemetry_.captured(frames,written);
return written;
}
void render (float* const* output,int channels,int frames) noexcept
{
const auto before=bridge_.status().underflowFrames;
bridge_.pull(output,channels,frames);
const auto after=bridge_.status().underflowFrames;
const auto delta=after>=before?after-before:0;
telemetry_.rendered(frames,static_cast<int>(
std::min<std::uint64_t>(delta,frames>0?static_cast<std::uint64_t>(frames):0)));
}
AdaptiveClockBridge::Status bridgeStatus() const noexcept
{
return bridge_.status();
}
SplitStreamSnapshot streamStatus() const noexcept
{
return telemetry_.snapshot();
}
private:
AdaptiveClockBridge bridge_;
SplitStreamTelemetry telemetry_;
};
} // namespace armix::device
Loading
Loading