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.
This commit is contained in:
Dandaedre 2026-10-05 08:18:35 +02:00
parent 3aae565c24
commit 51c4dd9e97
3 changed files with 143 additions and 0 deletions

View File

@ -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};

69
core/src/mute.rs Normal file
View File

@ -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<Item = Mute>) -> ValueState<Mute> {
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<StreamHandle, Mute>,
}
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<StreamHandle, Mute>,
intent: MuteIntent,
) -> BTreeMap<StreamHandle, Mute> {
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);
}
}

72
core/tests/mute.rs Normal file
View File

@ -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)
);
}