From 51c4dd9e97b408369db3c9eae7bdc3c8291ebc76 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 5 Oct 2026 08:18:35 +0200 Subject: [PATCH] feat(M1.5): resolve mute toggles against pending intent Plan explicit per-stream mute commands while preserving observed mixed/offline state and independent gain. Tests: cargo test -p fader-core --test mute --locked first failed for missing API; cargo test -p fader-core --all-targets --locked passed (30 tests). cargo clippy -p fader-core --all-targets --locked -- -D warnings and formatting passed. --- core/src/lib.rs | 2 ++ core/src/mute.rs | 69 ++++++++++++++++++++++++++++++++++++++++++++ core/tests/mute.rs | 72 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+) create mode 100644 core/src/mute.rs create mode 100644 core/tests/mute.rs diff --git a/core/src/lib.rs b/core/src/lib.rs index 7487fa3..e502e44 100644 --- a/core/src/lib.rs +++ b/core/src/lib.rs @@ -9,6 +9,7 @@ mod bindings; mod group; mod id; mod matching; +mod mute; mod revision; mod routing; mod state; @@ -24,6 +25,7 @@ pub use matching::{ ApplicationMatcher, ApplicationRuntime, ApplicationSelector, MetadataField, SelectorError, SelectorKind, StreamHandle, StreamMetadata, }; +pub use mute::{MuteIntent, MutePlanner, mute_view}; pub use revision::{BackendEpoch, Revision}; pub use routing::{Routing, RoutingError, Target}; pub use state::{Availability, Mute, ValueState}; diff --git a/core/src/mute.rs b/core/src/mute.rs new file mode 100644 index 0000000..b046552 --- /dev/null +++ b/core/src/mute.rs @@ -0,0 +1,69 @@ +//! Mute intent planning independent of gain and native audio state. +use crate::{Mute, StreamHandle, ValueState}; +use std::collections::BTreeMap; + +/// Explicit mute actions or a toggle resolved at command acceptance time. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum MuteIntent { + /// Apply one value to every resolved stream. + Set(Mute), + /// Mute if any member is unmuted; otherwise unmute. + Toggle, +} + +/// Aggregates observed mute values, preserving mixed and unavailable states. +pub fn mute_view(values: impl IntoIterator) -> ValueState { + let mut values = values.into_iter(); + let Some(first) = values.next() else { + return ValueState::Unavailable; + }; + if values.any(|value| value != first) { + ValueState::Mixed + } else { + ValueState::Uniform(first) + } +} + +/// Serial command intent shared by overlapping targets. +/// +/// Pending intent affects subsequent toggles, never the observed mute view. +/// The state owner clears a stream when its latest operation settles or is +/// cancelled, and on removal/disconnect. Older operation completions must not +/// clear a newer intent; operation correlation belongs to the server reducer. +#[derive(Clone, Debug, Default)] +pub struct MutePlanner { + pending: BTreeMap, +} + +impl MutePlanner { + /// Resolves an action into one explicit mute command per stream. + /// No channel gain is accepted or modified by this API. + pub fn plan( + &mut self, + observed: &BTreeMap, + intent: MuteIntent, + ) -> BTreeMap { + let value = match intent { + MuteIntent::Set(value) => value, + MuteIntent::Toggle => { + let any_unmuted = observed.iter().any(|(handle, value)| { + self.pending.get(handle).unwrap_or(value) == &Mute::Unmuted + }); + if any_unmuted { + Mute::Muted + } else { + Mute::Unmuted + } + } + }; + let commands: BTreeMap<_, _> = observed.keys().map(|handle| (*handle, value)).collect(); + self.pending + .extend(commands.iter().map(|(handle, value)| (*handle, *value))); + commands + } + + /// Releases intent only after the owner has checked operation freshness. + pub fn clear(&mut self, handle: StreamHandle) { + self.pending.remove(&handle); + } +} diff --git a/core/tests/mute.rs b/core/tests/mute.rs new file mode 100644 index 0000000..1d4fcf4 --- /dev/null +++ b/core/tests/mute.rs @@ -0,0 +1,72 @@ +use fader_core::{ + BackendEpoch, Mute, MuteIntent, MutePlanner, StreamHandle, ValueState, mute_view, +}; +use std::collections::BTreeMap; + +fn handle(id: u64) -> StreamHandle { + StreamHandle::new(BackendEpoch::new(1), id, 1) +} + +#[test] +fn mixed_toggles_mute_all_and_rapid_second_toggle_unmutes_all() { + let observed = BTreeMap::from([(handle(1), Mute::Muted), (handle(2), Mute::Unmuted)]); + let mut planner = MutePlanner::default(); + assert_eq!(mute_view(observed.values().copied()), ValueState::Mixed); + let first = planner.plan(&observed, MuteIntent::Toggle); + assert!(first.values().all(|value| *value == Mute::Muted)); + let second = planner.plan(&observed, MuteIntent::Toggle); + assert!(second.values().all(|value| *value == Mute::Unmuted)); + // Intent does not change the reported observation. + assert_eq!(mute_view(observed.values().copied()), ValueState::Mixed); +} + +#[test] +fn overlapping_groups_share_pending_intent_and_set_unmute_clears_every_member() { + let observed = BTreeMap::from([(handle(1), Mute::Unmuted), (handle(2), Mute::Muted)]); + let mut planner = MutePlanner::default(); + planner.plan(&observed, MuteIntent::Set(Mute::Muted)); + let subset = BTreeMap::from([(handle(1), Mute::Unmuted)]); + assert_eq!( + planner.plan(&subset, MuteIntent::Toggle)[&handle(1)], + Mute::Unmuted + ); + assert!( + planner + .plan(&observed, MuteIntent::Set(Mute::Unmuted)) + .values() + .all(|value| *value == Mute::Unmuted) + ); +} + +#[test] +fn offline_has_no_commands_and_settled_or_removed_streams_use_observations() { + let mut planner = MutePlanner::default(); + assert_eq!(mute_view([]), ValueState::Unavailable); + assert!( + planner + .plan(&BTreeMap::new(), MuteIntent::Toggle) + .is_empty() + ); + let observed = BTreeMap::from([(handle(1), Mute::Unmuted)]); + planner.plan(&observed, MuteIntent::Toggle); + planner.clear(handle(1)); + assert_eq!( + planner.plan(&observed, MuteIntent::Toggle)[&handle(1)], + Mute::Muted + ); +} + +#[test] +fn all_muted_toggle_unmutes_and_uniform_observations_stay_explicit() { + let observed = BTreeMap::from([(handle(1), Mute::Muted), (handle(2), Mute::Muted)]); + assert_eq!( + mute_view(observed.values().copied()), + ValueState::Uniform(Mute::Muted) + ); + assert!( + MutePlanner::default() + .plan(&observed, MuteIntent::Toggle) + .values() + .all(|value| *value == Mute::Unmuted) + ); +}