docs(M1): record verified domain milestone and M2 boundary
Rust CI fader_master passed CI.
MadGobblins/fader_master/pipeline/head This commit looks good Details

Document implemented contracts, selected dependency metadata, observed-state planning limits, and the requested stop before M2. Mark M1.4/M1.5 complete after workspace gates passed; retain the real-Jenkins M0.2 checkpoint.

Validation: document review against public contracts and task dependencies; git diff --cached --check passed. Runtime evidence: 30 unit/integration/property tests plus 1 compile-fail doctest; locked workspace fmt/check/test/doc/Clippy/release/default/no-default gates and scripts/test-ci.sh passed. Coverage command scripts/ci-run-coverage.sh 20 coverage/llvm-cov-summary.json coverage/.coverage-ready-local coverage/coverage-status.txt passed at 83.2487309645%.
This commit is contained in:
Dandaedre 2026-10-05 08:20:15 +02:00
parent df8ed342cc
commit 11b588f606
4 changed files with 54 additions and 8 deletions

View File

@ -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`.

View File

@ -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:

View File

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

15
task.md
View File

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