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
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:
parent
df8ed342cc
commit
11b588f606
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
15
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue