feat(M1.1): add typed domain values

Introduce validated stable IDs, finite non-negative gain and channel vectors, explicit aggregate/mute/availability states, and non-wrapping revision and backend epoch types. Preserve observed above-unity gain while requiring an explicit write ceiling.

Tests: cargo test -p fader-core --all-targets --locked (10 passed, including proptest invariants)

Tests: cargo clippy -p fader-core --all-targets --locked -- -D warnings; cargo test -p fader-core --doc --locked; cargo fmt --all -- --check; git diff --check (passed)
This commit is contained in:
Dandaedre 2026-10-05 08:00:03 +02:00
parent 123a67732f
commit 616ae07217
9 changed files with 791 additions and 6 deletions

289
Cargo.lock generated
View File

@ -8,6 +8,27 @@ version = "0.2.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
[[package]]
name = "autocfg"
version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
[[package]]
name = "bit-set"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
dependencies = [
"bit-vec",
]
[[package]]
name = "bit-vec"
version = "0.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
[[package]]
name = "bitflags"
version = "2.13.2"
@ -63,7 +84,7 @@ dependencies = [
"crossterm_winapi",
"mio",
"parking_lot",
"rustix",
"rustix 0.38.44",
"signal-hook",
"signal-hook-mio",
"winapi",
@ -150,6 +171,10 @@ dependencies = [
[[package]]
name = "fader-core"
version = "0.1.0"
dependencies = [
"proptest",
"thiserror",
]
[[package]]
name = "fader_master"
@ -162,12 +187,47 @@ dependencies = [
"volume_lib",
]
[[package]]
name = "fastrand"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
[[package]]
name = "fnv"
version = "1.0.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
[[package]]
name = "foldhash"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
[[package]]
name = "getrandom"
version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
dependencies = [
"cfg-if",
"libc",
"r-efi 5.3.0",
"wasip2",
]
[[package]]
name = "getrandom"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"libc",
"r-efi 6.0.0",
]
[[package]]
name = "hashbrown"
version = "0.15.5"
@ -240,6 +300,12 @@ version = "0.4.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "lock_api"
version = "0.4.14"
@ -289,6 +355,15 @@ version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
[[package]]
name = "num-traits"
version = "0.2.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
dependencies = [
"autocfg",
]
[[package]]
name = "num_threads"
version = "0.1.7"
@ -298,6 +373,12 @@ dependencies = [
"libc",
]
[[package]]
name = "once_cell"
version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "parking_lot"
version = "0.12.5"
@ -333,6 +414,15 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
[[package]]
name = "ppv-lite86"
version = "0.2.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
dependencies = [
"zerocopy",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
@ -342,6 +432,31 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "proptest"
version = "1.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
dependencies = [
"bit-set",
"bit-vec",
"bitflags",
"num-traits",
"rand",
"rand_chacha",
"rand_xorshift",
"regex-syntax",
"rusty-fork",
"tempfile",
"unarray",
]
[[package]]
name = "quick-error"
version = "1.2.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
[[package]]
name = "quote"
version = "1.0.47"
@ -351,6 +466,56 @@ dependencies = [
"proc-macro2",
]
[[package]]
name = "r-efi"
version = "5.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
[[package]]
name = "r-efi"
version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "rand"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
dependencies = [
"rand_chacha",
"rand_core",
]
[[package]]
name = "rand_chacha"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
dependencies = [
"ppv-lite86",
"rand_core",
]
[[package]]
name = "rand_core"
version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
dependencies = [
"getrandom 0.3.4",
]
[[package]]
name = "rand_xorshift"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
dependencies = [
"rand_core",
]
[[package]]
name = "ratatui"
version = "0.29.0"
@ -383,6 +548,12 @@ dependencies = [
"bitflags",
]
[[package]]
name = "regex-syntax"
version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "rustix"
version = "0.38.44"
@ -392,8 +563,21 @@ dependencies = [
"bitflags",
"errno",
"libc",
"linux-raw-sys",
"windows-sys 0.52.0",
"linux-raw-sys 0.4.15",
"windows-sys 0.59.0",
]
[[package]]
name = "rustix"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"
dependencies = [
"bitflags",
"errno",
"libc",
"linux-raw-sys 0.12.1",
"windows-sys 0.61.2",
]
[[package]]
@ -402,6 +586,18 @@ version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
[[package]]
name = "rusty-fork"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
dependencies = [
"fnv",
"quick-error",
"tempfile",
"wait-timeout",
]
[[package]]
name = "ryu"
version = "1.0.23"
@ -537,6 +733,39 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "tempfile"
version = "3.27.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [
"fastrand",
"getrandom 0.4.3",
"once_cell",
"rustix 1.1.5",
"windows-sys 0.61.2",
]
[[package]]
name = "thiserror"
version = "2.0.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
dependencies = [
"thiserror-impl",
]
[[package]]
name = "thiserror-impl"
version = "2.0.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "time"
version = "0.3.55"
@ -566,6 +795,12 @@ dependencies = [
"ratatui",
]
[[package]]
name = "unarray"
version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
[[package]]
name = "unicode-ident"
version = "1.0.26"
@ -608,12 +843,30 @@ dependencies = [
"fader-core",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
dependencies = [
"libc",
]
[[package]]
name = "wasi"
version = "0.11.1+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[package]]
name = "wasip2"
version = "1.0.4+wasi-0.2.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
dependencies = [
"wit-bindgen",
]
[[package]]
name = "winapi"
version = "0.3.9"
@ -644,9 +897,9 @@ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.52.0"
version = "0.59.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
dependencies = [
"windows-targets",
]
@ -723,3 +976,29 @@ name = "windows_x86_64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "wit-bindgen"
version = "0.57.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
[[package]]
name = "zerocopy"
version = "0.8.59"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6df92bf3d9227be3d53173901ddbffac2babc27ae50f397776ffd6dc33f800cb"
dependencies = [
"zerocopy-derive",
]
[[package]]
name = "zerocopy-derive"
version = "0.8.59"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ac4f328cf2f05d084e496c3e9c3f33ed0a183656a16e1fcec4d464d8373aec82"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]

View File

@ -15,6 +15,7 @@ fader-config = { path = "config" }
fader-core = { path = "core" }
midi = { path = "midi" }
ratatui = { version = "0.29.0", features = ["all-widgets", "serde"] }
thiserror = "2.0.21"
tui = { path = "tui" }
volume_lib = { path = "sound" }

View File

@ -8,3 +8,7 @@ repository.workspace = true
publish.workspace = true
[dependencies]
thiserror.workspace = true
[dev-dependencies]
proptest = "1.11.0"

156
core/src/id.rs Normal file
View File

@ -0,0 +1,156 @@
use std::{fmt, str::FromStr};
use thiserror::Error;
const MAX_ID_LENGTH: usize = 64;
/// Why a stable user-defined identifier was rejected.
#[derive(Clone, Debug, Error, Eq, PartialEq)]
pub enum IdError {
/// The identifier was empty.
#[error("identifier must not be empty")]
Empty,
/// The identifier exceeded the stable storage limit.
#[error("identifier length {actual} exceeds the maximum {maximum}")]
TooLong {
/// Actual byte length.
actual: usize,
/// Maximum allowed byte length.
maximum: usize,
},
/// The first character was not ASCII alphanumeric.
#[error("identifier must start with an ASCII letter or digit, found {found:?}")]
InvalidStart {
/// Invalid first character.
found: char,
},
/// A later character was outside the durable identifier alphabet.
#[error("identifier contains invalid character {found:?} at position {position}")]
InvalidCharacter {
/// Zero-based character position.
position: usize,
/// Invalid character.
found: char,
},
}
fn validate(value: &str) -> Result<(), IdError> {
if value.is_empty() {
return Err(IdError::Empty);
}
if value.len() > MAX_ID_LENGTH {
return Err(IdError::TooLong {
actual: value.len(),
maximum: MAX_ID_LENGTH,
});
}
let mut characters = value.chars();
let Some(first) = characters.next() else {
return Err(IdError::Empty);
};
if !first.is_ascii_alphanumeric() {
return Err(IdError::InvalidStart { found: first });
}
for (offset, character) in characters.enumerate() {
if !(character.is_ascii_alphanumeric() || matches!(character, '-' | '_')) {
return Err(IdError::InvalidCharacter {
position: offset + 1,
found: character,
});
}
}
Ok(())
}
macro_rules! stable_id {
($name:ident, $description:literal) => {
#[doc = $description]
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct $name(String);
impl $name {
/// Validates and constructs an identifier.
///
/// # Errors
///
/// Returns [`IdError`] when `value` is empty, too long, or outside
/// the portable `[A-Za-z0-9_-]` identifier alphabet.
pub fn new(value: impl Into<String>) -> Result<Self, IdError> {
let value = value.into();
validate(&value)?;
Ok(Self(value))
}
/// Returns the persisted string representation.
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for $name {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.0)
}
}
impl FromStr for $name {
type Err = IdError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
Self::new(value)
}
}
};
}
stable_id!(
ApplicationId,
"Stable identifier for a virtual application."
);
stable_id!(FaderId, "Stable identifier for a logical fader.");
stable_id!(GroupId, "Stable identifier for an application group.");
stable_id!(ProfileId, "Stable identifier for a configuration profile.");
stable_id!(SurfaceId, "Stable identifier for a physical MIDI surface.");
#[cfg(test)]
mod tests {
use std::any::TypeId;
use super::*;
#[test]
fn accepts_portable_stable_ids() {
let id = ApplicationId::new("music-player_2").expect("valid application ID");
assert_eq!(id.as_str(), "music-player_2");
assert_eq!(id.to_string(), "music-player_2");
}
#[test]
fn rejects_invalid_ids_with_a_precise_reason() {
assert_eq!(GroupId::new(""), Err(IdError::Empty));
assert_eq!(
GroupId::new("-group"),
Err(IdError::InvalidStart { found: '-' })
);
assert_eq!(
GroupId::new("group/name"),
Err(IdError::InvalidCharacter {
position: 5,
found: '/',
})
);
assert!(matches!(
GroupId::new("a".repeat(MAX_ID_LENGTH + 1)),
Err(IdError::TooLong { .. })
));
}
#[test]
fn stable_id_types_cannot_be_interchanged() {
assert_ne!(TypeId::of::<ApplicationId>(), TypeId::of::<GroupId>());
assert_ne!(TypeId::of::<FaderId>(), TypeId::of::<SurfaceId>());
assert_ne!(TypeId::of::<ProfileId>(), TypeId::of::<ApplicationId>());
}
}

View File

@ -4,3 +4,13 @@
//! native audio dependencies.
#![forbid(unsafe_code)]
mod id;
mod revision;
mod state;
mod volume;
pub use id::{ApplicationId, FaderId, GroupId, IdError, ProfileId, SurfaceId};
pub use revision::{BackendEpoch, Revision};
pub use state::{Availability, Mute, ValueState};
pub use volume::{ChannelGainError, ChannelGains, Gain, GainError};

75
core/src/revision.rs Normal file
View File

@ -0,0 +1,75 @@
/// Monotonic revision of domain-visible state.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct Revision(u64);
impl Revision {
/// Initial revision before any accepted state change.
pub const INITIAL: Self = Self(0);
/// Creates a revision from its persisted/wire representation.
#[must_use]
pub const fn new(value: u64) -> Self {
Self(value)
}
/// Returns the numeric wire representation.
#[must_use]
pub const fn get(self) -> u64 {
self.0
}
/// Advances the revision, returning `None` rather than wrapping.
#[must_use]
pub const fn checked_next(self) -> Option<Self> {
match self.0.checked_add(1) {
Some(next) => Some(Self(next)),
None => None,
}
}
}
/// Connection generation used to reject events from an obsolete backend.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct BackendEpoch(u64);
impl BackendEpoch {
/// Initial epoch before the first connection is established.
pub const INITIAL: Self = Self(0);
/// Creates an epoch from its numeric representation.
#[must_use]
pub const fn new(value: u64) -> Self {
Self(value)
}
/// Returns the numeric representation.
#[must_use]
pub const fn get(self) -> u64 {
self.0
}
/// Advances the epoch, returning `None` rather than wrapping.
#[must_use]
pub const fn checked_next(self) -> Option<Self> {
match self.0.checked_add(1) {
Some(next) => Some(Self(next)),
None => None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn counters_advance_without_wrapping() {
assert_eq!(Revision::INITIAL.checked_next(), Some(Revision::new(1)));
assert_eq!(Revision::new(u64::MAX).checked_next(), None);
assert_eq!(
BackendEpoch::INITIAL.checked_next(),
Some(BackendEpoch::new(1))
);
assert_eq!(BackendEpoch::new(u64::MAX).checked_next(), None);
}
}

42
core/src/state.rs Normal file
View File

@ -0,0 +1,42 @@
/// Per-stream mute value, independent from gain.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum Mute {
/// Audio is muted.
Muted,
/// Audio is not muted, even when its gain is zero.
Unmuted,
}
/// Whether a configured object currently resolves to live resources.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum Availability {
/// At least one live resource is available.
Online,
/// No live resource is currently available.
Offline,
}
/// Aggregate state that preserves unavailable and heterogeneous values.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum ValueState<T> {
/// No value is currently observable.
Unavailable,
/// Every resolved member has the same value.
Uniform(T),
/// Resolved members have different values.
Mixed,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn zero_gain_does_not_imply_mute() {
let gain_state = ValueState::Uniform(0_u8);
let mute_state = ValueState::Uniform(Mute::Unmuted);
assert_eq!(gain_state, ValueState::Uniform(0));
assert_eq!(mute_state, ValueState::Uniform(Mute::Unmuted));
}
}

218
core/src/volume.rs Normal file
View File

@ -0,0 +1,218 @@
use thiserror::Error;
/// Why a scalar gain was rejected.
#[derive(Clone, Copy, Debug, Error, PartialEq)]
pub enum GainError {
/// NaN and infinities cannot represent observable audio state.
#[error("gain must be finite, found {0}")]
NonFinite(f64),
/// Negative amplitude is outside the domain.
#[error("gain must be non-negative, found {0}")]
Negative(f64),
}
/// Finite, non-negative linear amplitude gain.
///
/// `1.0` is unity and `0.0` is silence. Values above unity are representable
/// so external observations are not silently clamped; write paths apply their
/// configured ceiling separately.
#[derive(Clone, Copy, Debug, PartialEq, PartialOrd)]
pub struct Gain(f64);
impl Gain {
/// Silence.
pub const SILENCE: Self = Self(0.0);
/// Unity gain.
pub const UNITY: Self = Self(1.0);
/// Validates a linear amplitude value.
///
/// # Errors
///
/// Returns [`GainError`] for negative, NaN, or infinite values.
pub fn new(value: f64) -> Result<Self, GainError> {
if !value.is_finite() {
return Err(GainError::NonFinite(value));
}
if value < 0.0 {
return Err(GainError::Negative(value));
}
Ok(Self(value))
}
/// Returns the linear amplitude value.
#[must_use]
pub const fn get(self) -> f64 {
self.0
}
/// Returns whether this value represents silence.
#[must_use]
pub fn is_silent(self) -> bool {
self == Self::SILENCE
}
}
/// Why a vector of channel gains or a balance-preserving operation failed.
#[derive(Clone, Debug, Error, PartialEq)]
pub enum ChannelGainError {
/// A stream must expose at least one channel.
#[error("channel gain vector must not be empty")]
Empty,
/// The requested maximum exceeds the configured write ceiling.
#[error("target gain {target} exceeds write ceiling {ceiling}")]
AboveWriteCeiling {
/// Requested output maximum.
target: f64,
/// Configured maximum write gain.
ceiling: f64,
},
/// A calculated scalar failed gain validation.
#[error(transparent)]
InvalidGain(#[from] GainError),
}
/// Non-empty per-channel gain snapshot.
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelGains(Vec<Gain>);
impl ChannelGains {
/// Constructs a non-empty channel vector.
///
/// # Errors
///
/// Returns [`ChannelGainError::Empty`] when no channels are provided.
pub fn new(channels: Vec<Gain>) -> Result<Self, ChannelGainError> {
if channels.is_empty() {
return Err(ChannelGainError::Empty);
}
Ok(Self(channels))
}
/// Returns the channel values.
#[must_use]
pub fn as_slice(&self) -> &[Gain] {
&self.0
}
/// Consumes the snapshot and returns its channel values.
#[must_use]
pub fn into_vec(self) -> Vec<Gain> {
self.0
}
/// Returns the loudest channel.
#[must_use]
pub fn maximum(&self) -> Gain {
self.0
.iter()
.copied()
.fold(Gain::SILENCE, |maximum, channel| {
if channel > maximum { channel } else { maximum }
})
}
/// Scales every channel so the loudest reaches `target`.
///
/// Existing balance is preserved. An all-silent vector has no balance to
/// preserve, so every channel is initialized to `target`.
///
/// # Errors
///
/// Returns [`ChannelGainError::AboveWriteCeiling`] when `target` exceeds
/// `write_ceiling`.
pub fn scaled_to(&self, target: Gain, write_ceiling: Gain) -> Result<Self, ChannelGainError> {
if target > write_ceiling {
return Err(ChannelGainError::AboveWriteCeiling {
target: target.get(),
ceiling: write_ceiling.get(),
});
}
let old_maximum = self.maximum();
if old_maximum.is_silent() {
return Ok(Self(vec![target; self.0.len()]));
}
let channels = self
.0
.iter()
.map(|channel| Gain::new((channel.get() / old_maximum.get()) * target.get()))
.collect::<Result<Vec<_>, _>>()?;
Ok(Self(channels))
}
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::*;
fn gain(value: f64) -> Gain {
Gain::new(value).expect("test gain must be valid")
}
#[test]
fn rejects_non_finite_and_negative_gain() {
assert!(matches!(Gain::new(f64::NAN), Err(GainError::NonFinite(_))));
assert!(matches!(
Gain::new(f64::INFINITY),
Err(GainError::NonFinite(_))
));
assert_eq!(Gain::new(-0.01), Err(GainError::Negative(-0.01)));
assert_eq!(Gain::new(-0.0), Ok(Gain::SILENCE));
}
#[test]
fn initializes_silent_channels_equally() {
let channels = ChannelGains::new(vec![Gain::SILENCE, Gain::SILENCE])
.expect("non-empty channel vector");
let scaled = channels
.scaled_to(gain(0.75), Gain::UNITY)
.expect("target is below ceiling");
assert_eq!(scaled.as_slice(), &[gain(0.75), gain(0.75)]);
}
#[test]
fn rejects_writes_above_the_explicit_ceiling() {
let channels = ChannelGains::new(vec![Gain::UNITY]).expect("non-empty channel vector");
assert_eq!(
channels.scaled_to(gain(1.5), Gain::UNITY),
Err(ChannelGainError::AboveWriteCeiling {
target: 1.5,
ceiling: 1.0,
})
);
}
proptest! {
#[test]
fn valid_gain_round_trips(value in 0.0_f64..=32.0) {
let value = Gain::new(value).expect("generated gain is valid");
prop_assert!(value.get().is_finite());
prop_assert!(value.get() >= 0.0);
}
#[test]
fn scaling_preserves_balance(
left in 0.000_001_f64..=8.0,
right in 0.000_001_f64..=8.0,
target in 0.0_f64..=4.0,
) {
let original = ChannelGains::new(vec![gain(left), gain(right)])
.expect("generated vector is non-empty");
let scaled = original
.scaled_to(gain(target), gain(4.0))
.expect("generated target is within ceiling");
prop_assert!((scaled.maximum().get() - target).abs() <= f64::EPSILON * 8.0);
if target > 0.0 {
let original_ratio = left / right;
let scaled_ratio = scaled.as_slice()[0].get() / scaled.as_slice()[1].get();
prop_assert!((original_ratio - scaled_ratio).abs() <= original_ratio.abs() * 1e-12 + 1e-12);
}
}
}
}

View File

@ -27,7 +27,7 @@ Dependencies: planning.
Dependencies: M0.
- [ ] **M1.1 Typed values:** stable IDs, finite gain, channel vectors, mute/availability/mixed states, revisions and backend epochs. Tests: invalid ranges/NaN/infinity rejected; gain/silence/channel-balance properties hold; IDs cannot be interchanged accidentally.
- [x] **M1.1 Typed values:** stable IDs, finite gain, channel vectors, mute/availability/mixed states, revisions and backend epochs. Tests: invalid ranges/NaN/infinity rejected; gain/silence/channel-balance properties hold; IDs cannot be interchanged accidentally.
- [ ] **M1.2 Application selectors:** normalized metadata, exact/regex matching, OR selectors, multiple live streams and offline objects. Tests: anchored/unanchored/case-sensitive cases, missing fields, malformed regex, stream creation/removal and backend ID reuse.
- [ ] **M1.3 Fader resolution:** surface binding -> fader -> application/group -> deduplicated live streams. Tests: identical CCs on different surfaces stay separate, multiple faders can share an object, and overlap never writes the same stream twice per operation.
- [ ] **M1.4 Group gain:** absolute and relative modes with channel balance, aggregate max/mixed state, zero fallback and clipping. Tests: heterogeneous members, externally changed members, all-zero recovery, empty group, late joiner adopting live state, and partial failure.