Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 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
5cddb1c
fix(test): separate distinct stream and bridge status types for MSVC …
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
2 changes: 1 addition & 1 deletion .github/workflows/p1-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,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 but **is not activated**: a controlled migration from the existing joined device and plugin-graph ownership must be implemented and verified before exposure. 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 policy is intentionally not wired to the legacy JUCE joined audio device callback or its GUI yet. The existing app still cannot measure independent capture/render clocks from that callback. The true P0 remaining acceptance scope is:

1. Implement independent Windows capture and render stream adapters or demonstrate that a supported JUCE API exposes actual independent timelines. Use real endpoint IDs/formats/IAudioClient buffer events, not friendly-name matching.
2. Wire the prepared `AdaptiveClockBridge` only for **proven independent clocks** with render-master timeline, bounded callback scratch buffers and no RT allocations. Maintain direct ASIO/shared-clock fast path.
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** with true callback-source labels; do not claim render driver starvation from inferred callback delays.
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 are required while this engineering work proceeds. The approved GUI v0.8 baseline is locked; existing SIGNAL CHECK diagnostics remain unchanged.
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