diff --git a/CMakeLists.txt b/CMakeLists.txt index ab6f1cd81..3efe6f19e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -219,6 +219,10 @@ if(BUILD_TESTING) target_link_libraries(ARMixApprovedRoutingPcmTests PRIVATE juce::juce_core juce::juce_recommended_config_flags) target_compile_features(ARMixApprovedRoutingPcmTests PRIVATE cxx_std_20) add_test(NAME P0ApprovedDecoderChannelToChannelAndSourceOnlyPCM COMMAND ARMixApprovedRoutingPcmTests) + # M3a: actual ChannelId vs M4 production blocks before compatibility retirement. + add_executable(ARMixProductionRenderAuditTests tests/production_render_audit_test.cpp) + target_compile_features(ARMixProductionRenderAuditTests PRIVATE cxx_std_20) + add_test(NAME M3ActualProductionRenderPathAndFailSilentCounters COMMAND ARMixProductionRenderAuditTests) add_dependencies(ARMixMixerRoutingTests ARMixApprovedRoutingPcmTests) add_executable(ARMixLatencyCompensationTests tests/dynamic_latency_compensation_test.cpp) target_compile_features(ARMixLatencyCompensationTests PRIVATE cxx_std_20) diff --git a/docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md b/docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md new file mode 100644 index 000000000..e16b4ad7b --- /dev/null +++ b/docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md @@ -0,0 +1,48 @@ +# M3a — production render-path evidence + +## Verified callback structure + +The one JUCE device callback is LiveAudioEngine::audioDeviceIOCallbackWithContext. +It checks the hardware direct fence, then NativeRenderAuthority decides +fail-silent unpatched, accepted routed session or isolated diagnostics. +A routed session calls LiveDryRoutingLab::process ONCE. Its nonblocking +RealtimeRenderPermit prevents overlapping callbacks from invoking the same FX. + +Inside this existing sole routed pass, native ChannelId PCM uses +DynamicNativeSessionPublisher::render when the matching device-epoch admission +is installed. The compatibility branch uses PreparedMixerBlock::process only +when no native ChannelId PCM epoch is admitted. These are alternatives, never +summed, but M4 compatibility is still reachable in source. Do NOT delete it. + +The explicit diagnostic tail runs no vendor VST3. SOURCE ONLY may still +process and meter channel PCM without a MAIN signal, and hardware mute can +silence device pins while a logical graph continues to run. The secondary +WASAPI output copies MAIN PCM after this single render pass. + +## Instrumentation and meaning + +The native status object now contains dryRoutingLab.renderAudit. It reports +nativeStarted, nativeCompleted, nativeFailed, m4Started, m4Completed, m4Failed, +overlapDenied, unpatchedSilent and mutedNoRender. All counters are monotonic +within the application process, not per device. They are independent relaxed +atomics: a concurrent CONTROL snapshot can briefly observe an unfinished +callback attempt. A block is counted once regardless of DSP chunk count. + +This is an observation, not output authorization or proof of audible sound. +Compare deltas of these counters across a field-test window alongside +deviceEpoch, routing admission and output mute. Do not add browser polling +or a new dashboard solely for these metrics. + +## Tests and next-step admission + +The new zero-JUCE M3ActualProductionRenderPathAndFailSilentCounters CTest checks +that native and M4 attempts, completions, failures, overlapping callbacks and +silent exits remain distinct. Existing real block-by-block PCM tests for +WIRE, SOURCE ONLY, parallel sends, bus and channel FX remain mandatory. +A Windows MSVC/full CTest validates integration. Physical ASIO listening is +PENDING and cannot be inferred from green CI. + +Retire an M4 branch only after actual native field sessions show no M4 +render deltas with equivalent VST3/FX, channel meters, bus and physical MAIN +performance across restart, devices and output mute. Never permit legacy +fallback merely because native publication failed. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index cde40b813..8b1096a27 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -40,6 +40,7 @@ Assembled /preview/ DOM (presentation only) | Modal setup transaction (M2b) | src/Main.cpp::showDeviceSetup; NativeDeviceApplyCoordinator.h | Persistent one-owner lease across visible JUCE selector, explicit Apply and automatic ASIO restart; repeated Setup clicks never re-mute; selector close completes readback/rebind before releasing lease | | Live hardware readback (M2c) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp | Consolidated actual device-object readback on CONTROL, strict ASIO driver instance identity and live mask/rate/buffer verification before Apply/rollback; no new device owner or callback | | Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority | +| M3a actual render evidence | engine/core/ProductionRenderAudit.h; LiveDryRoutingLab::process/status; docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md | One native or M4 render attempt per JUCE callback; success/fault/overlap and muted/unpatched readback; no audio authority change | | 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/NativeLogicalMixerControl.h | Canonical installed and retained projection, with a forwarding include for old clients. Logical-only readback is separate and cannot admit PCM. | diff --git a/engine/core/ProductionRenderAudit.h b/engine/core/ProductionRenderAudit.h new file mode 100644 index 000000000..99dde2fd9 --- /dev/null +++ b/engine/core/ProductionRenderAudit.h @@ -0,0 +1,48 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#pragma once +#include +#include + +// Read-only evidence for the single JUCE production renderer. Neither this +// type nor its counters authorize PCM/output. No heap, lock, wait or log on RT. +namespace armix::rt { +class ProductionRenderAudit final { +public: + enum class Path : std::uint8_t { channelId, compatibilityM4 }; + struct Snapshot { + std::uint64_t nativeStarted=0,nativeCompleted=0,nativeFailed=0; + std::uint64_t m4Started=0,m4Completed=0,m4Failed=0; + std::uint64_t overlapDenied=0,unpatchedSilent=0,mutedNoRender=0; + }; + ProductionRenderAudit()=default; + ProductionRenderAudit(const ProductionRenderAudit&)=delete; + ProductionRenderAudit& operator=(const ProductionRenderAudit&)=delete; + void started(Path path) noexcept {select(path,nativeStarted_,m4Started_).fetch_add(1,std::memory_order_relaxed);} + void completed(Path path) noexcept {select(path,nativeCompleted_,m4Completed_).fetch_add(1,std::memory_order_relaxed);} + void failed(Path path) noexcept {select(path,nativeFailed_,m4Failed_).fetch_add(1,std::memory_order_relaxed);} + void deniedOverlap() noexcept {overlapDenied_.fetch_add(1,std::memory_order_relaxed);} + void unpatched() noexcept {unpatchedSilent_.fetch_add(1,std::memory_order_relaxed);} + void muted() noexcept {mutedNoRender_.fetch_add(1,std::memory_order_relaxed);} + // CONTROL only: independent relaxed loads can briefly show an in-flight + // attempt. Counters are monotonic since process start, not per device. + [[nodiscard]] Snapshot snapshot() const noexcept { + return {nativeStarted_.load(std::memory_order_relaxed), + nativeCompleted_.load(std::memory_order_relaxed), + nativeFailed_.load(std::memory_order_relaxed), + m4Started_.load(std::memory_order_relaxed), + m4Completed_.load(std::memory_order_relaxed), + m4Failed_.load(std::memory_order_relaxed), + overlapDenied_.load(std::memory_order_relaxed), + unpatchedSilent_.load(std::memory_order_relaxed), + mutedNoRender_.load(std::memory_order_relaxed)}; + } +private: + using Counter=std::atomic; + static Counter& select(Path path,Counter& native,Counter& m4) noexcept { + return path==Path::channelId?native:m4; + } + Counter nativeStarted_{0},nativeCompleted_{0},nativeFailed_{0}; + Counter m4Started_{0},m4Completed_{0},m4Failed_{0}; + Counter overlapDenied_{0},unpatchedSilent_{0},mutedNoRender_{0}; +}; +} // namespace armix::rt diff --git a/src/LiveDryRoutingLab.h b/src/LiveDryRoutingLab.h index d0bd9b720..fc4d41d75 100644 --- a/src/LiveDryRoutingLab.h +++ b/src/LiveDryRoutingLab.h @@ -17,6 +17,7 @@ #include "../engine/device/JuceActivePortSnapshot.h" #include "../engine/core/RealtimeRoutePublisher.h" #include "../engine/core/RealtimeRenderPermit.h" +#include "../engine/core/ProductionRenderAudit.h" #include "../engine/device/LiveInputPortRegistry.h" #include #include @@ -2777,6 +2778,7 @@ class LiveDryRoutingLab final { // do not spin or take a lock on the host-owned realtime callback. armix::rt::RealtimeRenderPermit exclusive{rendering_}; if(!exclusive) { + renderAudit_.deniedOverlap(); if(outputs && frames>0 && frames<=Block::hardFrameLimit) for(int c=0;c perChannelPeaks{}; std::array perChannelPeaksL{},perChannelPeaksR{}; @@ -2967,6 +2979,7 @@ class LiveDryRoutingLab final { // A native publication can briefly contend with a reader. // The epoch/pin checks above own sticky topology faults. if(!channelIdRender)topologyFault_.store(true,std::memory_order_release); + renderAudit_.failed(auditPath); silence();return true; } for(int ch=0;chsetProperty("hasAcceptedRoute",hasExplicitRoute()); const bool nativePcm=channelIdPhysicalPcmActive(); out->setProperty("nativeChannelIdPcmActive",nativePcm); + // Exact attempted PCM producers, not an optimistic GUI/admission + // indicator. Allocations are CONTROL-only in status(), never render(). + const auto evidence=renderAudit_.snapshot(); + auto audit=std::make_unique(); + audit->setProperty("nativeStarted",static_cast(evidence.nativeStarted)); + audit->setProperty("nativeCompleted",static_cast(evidence.nativeCompleted)); + audit->setProperty("nativeFailed",static_cast(evidence.nativeFailed)); + audit->setProperty("m4Started",static_cast(evidence.m4Started)); + audit->setProperty("m4Completed",static_cast(evidence.m4Completed)); + audit->setProperty("m4Failed",static_cast(evidence.m4Failed)); + audit->setProperty("overlapDenied",static_cast(evidence.overlapDenied)); + audit->setProperty("unpatchedSilent",static_cast(evidence.unpatchedSilent)); + audit->setProperty("mutedNoRender",static_cast(evidence.mutedNoRender)); + out->setProperty("renderAudit",juce::var(audit.release())); // ShowV2 and the legacy M4 route cannot serialize extra ChannelId // GROUP/FX RETURN buses. This stays visible even after DSP faults // silent so SAVE/RECALL cannot silently discard audible topology. @@ -3209,6 +3237,7 @@ class LiveDryRoutingLab final { static constexpr int mutedMeterFrames=512; std::array,2> mutedMain_{},mutedMonitor_{}; std::atomic_flag rendering_=ATOMIC_FLAG_INIT; // one AUDIO producer + armix::rt::ProductionRenderAudit renderAudit_; // per-process, RT-only writers Publisher publisher_; armix::mixer::DynamicNativeSessionPublisher nativePublisher_; armix::mixer::UnifiedLegacyAccepted nativeAccepted_; diff --git a/tests/live_routing_ui_contract_test.mjs b/tests/live_routing_ui_contract_test.mjs index 2adbad5d1..c23d8d57a 100644 --- a/tests/live_routing_ui_contract_test.mjs +++ b/tests/live_routing_ui_contract_test.mjs @@ -67,7 +67,7 @@ test("MUTE gate precedes processing and suppresses previous audible crossfade",( assert.match(gate,/fadeRemaining_=rampFrames/); assert.match(gate,/fadeFromL_=fadeFromR_=0\.f/); assert.match(gate,/lastOutputL_=lastOutputR_=0\.f/); - assert.match(gate,/if\(!meterOnly\)\{silence\(\);return true;\}/); + assert.match(gate,/if\(!meterOnly\)\s*\{\s*renderAudit_\.muted\(\);\s*silence\(\);return true;\s*\}/); assert.match(gate,/meterOnly\?mutedMain_\[0\]\.data\(\):mainL\+offset/); assert.match(lab,/if\(outputs\[c\] && \(meterOnly \|\|/); assert.ok(!lab.includes("masterMuted?0.f:std::clamp(masterGain"), "don't mute before fade and then reintroduce old samples"); diff --git a/tests/production_render_audit_test.cpp b/tests/production_render_audit_test.cpp new file mode 100644 index 000000000..1c103897a --- /dev/null +++ b/tests/production_render_audit_test.cpp @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: AGPL-3.0-only +#if defined(NDEBUG) +#undef NDEBUG +#endif +#include "../engine/core/ProductionRenderAudit.h" +#include +#include +#include +using Audit=armix::rt::ProductionRenderAudit; +static_assert(!std::is_copy_constructible_v); +static_assert(noexcept(std::declval().started(Audit::Path::channelId))); +static_assert(noexcept(std::declval().snapshot())); +int main() { + Audit a; + auto s=a.snapshot(); + assert(s.nativeStarted==0 && s.m4Started==0 && s.overlapDenied==0); + // Count once per outer hardware callback, not per DSP chunk or channel. + a.started(Audit::Path::channelId);a.completed(Audit::Path::channelId); + a.started(Audit::Path::channelId);a.completed(Audit::Path::channelId); + a.started(Audit::Path::channelId);a.failed(Audit::Path::channelId); + a.started(Audit::Path::compatibilityM4);a.completed(Audit::Path::compatibilityM4); + a.started(Audit::Path::compatibilityM4);a.failed(Audit::Path::compatibilityM4); + a.deniedOverlap();a.unpatched();a.unpatched();a.muted(); + s=a.snapshot(); + assert(s.nativeStarted==3&&s.nativeCompleted==2&&s.nativeFailed==1); + assert(s.m4Started==2&&s.m4Completed==1&&s.m4Failed==1); + assert(s.overlapDenied==1&&s.unpatchedSilent==2&&s.mutedNoRender==1); + assert(s.nativeStarted==s.nativeCompleted+s.nativeFailed); + assert(s.m4Started==s.m4Completed+s.m4Failed); +}