diff --git a/AGENTS.md b/AGENTS.md index 422ecd4..b0ff399 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,4 +43,4 @@ cargo build --workspace --release --all-features Also test the default build, no-default-features build, and each optional backend independently once feature flags exist. Provision native development libraries in CI. Hardware-free domain, fake-adapter, config, and TUI tests must run without an audio daemon or USB device. Keep real audio/hardware checks separately opt-in and document their fixtures and prerequisites. Add property tests for numerical conversions and state invariants; use a fake clock for retries and coalescing. Test observable behavior, including failure paths, rather than private implementation details. -Current baseline: the workspace remains primarily a scaffold rather than an implementation of the architecture. The `implementation-start` tag marks the tested CI coverage/badge baseline; the remaining foundation work, including a pinned toolchain/MSRV and the initial domain/config crates, stays ordered in `task.md`. +Current baseline: Rust 1.88.0 is pinned, domain/config crate boundaries exist, and M1 domain contracts are implemented. Runtime adapters, configuration, and the executable remain scaffold work. The `implementation-start` tag marks the original CI coverage/badge baseline. M0.2 awaits real Jenkins verification; the next implementation milestone is M2 in `task.md`. diff --git a/README.md b/README.md index 60fc030..6423eda 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ Linux application volume and mute control from one or more USB MIDI surfaces. -This repository currently contains an early Rust workspace and TUI prototype. +This repository currently contains a tested Rust domain library and TUI prototype. +The domain layer supports matching, routing, balanced group volume plans, and mute +intent; the executable is still a scaffold. Configuration work starts at M2. The server, audio adapters, persistent bindings, and configuration editor are planned in the following documents: diff --git a/architecture.md b/architecture.md index 9544baa..95a2d8b 100644 --- a/architecture.md +++ b/architecture.md @@ -1,6 +1,41 @@ # fader_master architecture -Status: proposed implementation design, researched 2026-10-05. The current workspace contains placeholder MIDI/audio libraries, a Hello World executable, and a basic Ratatui example. Features below are planned, not shipped. +Status: design researched 2026-10-05; foundation and M1 domain contracts are implemented. The executable remains a Hello World scaffold and the TUI remains a basic Ratatui example. Configuration, runtime workers, and native adapters below are planned, not shipped. + +## Implemented boundary at M2 entry + +Rust 1.88.0 is the pinned toolchain and tested MSRV. The workspace inherits +package metadata, including the existing custom `LICENSE` through `license-file`. +`core` contains typed IDs, finite gain/channel vectors, normalized selectors, +stream identities, logical routing, device-scoped bindings, group gain planning, +and serial mute intent planning. `config` is an empty inward-dependent crate; +M2 configuration work has not started. MIDI/audio crates are adapter boundaries +without native handles or transport behavior yet. + +Stable IDs contain 1–64 ASCII bytes, start with an alphanumeric character, and +otherwise allow alphanumerics, `_`, and `-`. Selector patterns contain 1–256 +bytes; regex compilation has a 1 MiB size limit. Missing normalized properties +never fall back to raw metadata. Group references cannot nest. Logical routing +validates references and returns ordered, deduplicated stream sets. Physical +binding lookup includes surface, channel, message kind, and control number. + +Group gain plans clip each stream at the explicit write ceiling, preserve channel +ratios, and leave observations unchanged. Relative scaling divides a stream's +maximum by the aggregate maximum before multiplication to avoid intermediate +overflow. Partial confirmations and late members are represented by supplying +updated observations to the next plan; asynchronous dispatch belongs to M3. +Mute planning stores accepted per-stream intent so rapid toggles and overlapping +targets compose. The future reducer must clear intent only after checking that +an operation completion is current, or on removal/disconnect. Display state is +always derived from observations. + +Added dependencies were verified from their downloaded package manifests: +`thiserror 2.0.21` requires Rust 1.77, `regex 1.13.1` requires 1.65, and the +test-only `proptest 1.11.0` requires 1.85. Each offers MIT OR Apache-2.0 and +requires no audio/MIDI development library. All compile on the pinned 1.88.0 +toolchain. Regex provides bounded compiled matching, thiserror implements typed +library errors, and proptest exercises numerical invariants. Cargo.lock records +the resolved versions; dependency versions are workspace-managed. ## Purpose and scope @@ -31,8 +66,8 @@ Only the server mutates domain state. Virtual objects resolve commands; they do | Workspace location | Planned responsibility | | --- | --- | -| New `core` directory, package `fader-core` | Pure domain types, target resolution, commands/events, reducer, audio adapter contract | -| New `config` directory, package `fader-config` | TOML schemas, validation, migration, atomic persistence | +| Existing `core` directory, package `fader-core` | Pure domain types and target resolution; commands/events, reducer and adapter contract follow in M3 | +| Existing `config` directory, package `fader-config` | Empty boundary; TOML schemas, validation, migration, atomic persistence follow in M2 | | Existing `sound`, currently package `volume_lib` | Audio workers; `pulse`, `pipewire`, `alsa-mixer` features; fake adapter | | Existing `midi` | MIDI transport, parsing, device identity, bindings, feedback, pickup | | Existing `tui` | Mixer/editor/devices/status tabs and IPC client; no native audio access | diff --git a/task.md b/task.md index bd12e6c..d3efc41 100644 --- a/task.md +++ b/task.md @@ -1,6 +1,6 @@ # Implementation tasks -This is the build plan for `architecture.md`. All implementation boxes start unchecked because the repository is a scaffold. Follow `AGENTS.md`: one local commit per passing behavior/test increment, with the implementation and test together. A milestone below normally needs several commits; do not make one giant milestone commit or separate failing-test commits. Record focused test commands/results in commit bodies. +This is the build plan for `architecture.md`. Checked boxes record verified acceptance criteria. Follow `AGENTS.md`: one local commit per passing behavior/test increment, with the implementation and test together. A milestone below normally needs several commits; do not make one giant milestone commit or separate failing-test commits. Record focused test commands/results in commit bodies. ## Planning delivered @@ -30,8 +30,17 @@ Dependencies: M0. - [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. - [x] **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. - [x] **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. -- [ ] **M1.5 Mute:** explicit set/toggle independent of volume. Tests: mixed-group toggle mutes all, fully muted toggle unmutes all, two rapid toggles cancel logically, zero gain does not imply mute, and unmute does not alter gain. +- [x] **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. +- [x] **M1.5 Mute:** explicit set/toggle independent of volume. Tests: mixed-group toggle mutes all, fully muted toggle unmutes all, two rapid toggles cancel logically, zero gain does not imply mute, and unmute does not alter gain. + +M1 verification on 2026-10-05: 30 unit/integration/property tests and one +compile-fail doctest pass. Locked workspace formatting, all-target/all-feature +checks/tests, doctests, strict Clippy, release/default/no-default-feature builds, +no-default-feature tests, warning-strict rustdoc, and CI script fixtures pass on +Linux with Rust 1.88.0. Line coverage is 83.2487309645% against the unchanged 20% +floor. Group partial-failure tests operate on observed domain snapshots; native +dispatch and asynchronous operation correlation remain M3 work. M0.2 still +requires a real Jenkins run. Per user direction, stop here before starting M2. ## M2 — TOML schemas and safe persistence