198 lines
21 KiB
Markdown
198 lines
21 KiB
Markdown
# Implementation tasks
|
||
|
||
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
|
||
|
||
- [x] Inspect the workspace and define the project-steward role in `AGENTS.md`.
|
||
- [x] Specify state ownership, adapter boundaries, matching/groups, MIDI identity/feedback, and TOML lifecycle in `architecture.md`.
|
||
- [x] Research libraries using linked primary documentation and identify bounded technical spikes.
|
||
- [x] Define implementation order, acceptance tests, and requirement coverage below.
|
||
|
||
Planning validation: parse the architecture's TOML example, verify local Markdown links and cross-references, check all 15 requirements are mapped below, and run `git diff --check`. No runtime behavior is changed by these documents.
|
||
|
||
Baseline test attempt on 2026-10-05: `cargo test --workspace --all-targets --offline` could not run because `compact_str v0.8.2` was not cached. This is an environment/dependency limitation, not a passing suite or evidence of a code failure. Cargo generated an ignored lockfile during resolution. Foundation work must establish a complete baseline with dependencies available.
|
||
|
||
## M0 — Reproducible Rust foundation
|
||
|
||
Dependencies: planning.
|
||
|
||
- [x] **M0.1 Toolchain and build:** select/test an MSRV and pinned toolchain, centralize workspace metadata/dependencies, track Cargo.lock for the executable, document native build prerequisites. Acceptance: a fresh supported Linux checkout builds and tests reproducibly with `--locked`; the chosen MSRV builds the chosen dependency set.
|
||
- [ ] **M0.2 CI gates:** align Jenkins with AGENTS.md, including doctests, Clippy `-D warnings`, release build and later backend feature matrix. Acceptance: representative formatting/lint/test failures fail the pipeline; default and full-feature builds pass with provisioned dependencies.
|
||
Repository configuration now runs locked default, no-default-features, and all-features checks/tests plus warning-strict documentation, Clippy, and release gates. Keep this open until a real Jenkins run on the provisioned worker passes.
|
||
- [x] **M0.2a Coverage badges:** measure locked all-target line coverage with a pinned tool, enforce the documented 20% scaffold floor, and generate/archive the version, test, and coverage badges on every build. Publish atomically only from `main`, with fresh-build markers preventing stale test or coverage values. Acceptance: renderer, coverage lifecycle, finalization, and publication fixture tests pass; the real local measurement is above the floor. Jenkins publication and public retrieval remain deployment checks.
|
||
- [x] **M0.3 Domain boundary:** add `fader-core` and `fader-config`, wire current crates inward, remove placeholder arithmetic tests as real contracts replace them. Acceptance: core tests run without a terminal, sound daemon, native device connection, or Tokio runtime; dependency graph has no cycles.
|
||
|
||
## M1 — Domain state and virtual objects
|
||
|
||
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.
|
||
- [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
|
||
|
||
Dependencies: M1 types; runtime activation follows in M10.
|
||
|
||
- [x] **M2.1 Schema and validation:** profile, application/group/fader/binding/device, and state schemas; check all references and capabilities. Tests: architecture example parses semantically, round trip preserves meaning, invalid IDs/duplicate bindings/unknown fields/schema versions fail with useful paths, all supported MIDI ranges are checked.
|
||
The strict version-1 profile, reusable device-capability, and persisted-state
|
||
documents now validate before construction. The architecture TOML block and
|
||
checked-in example are test-locked to one another; five integration tests
|
||
cover semantic round trips, reference/capability failures, unknown fields,
|
||
versions, duplicates, and MIDI channel/data endpoints.
|
||
- [x] **M2.2 Atomic files:** XDG paths, same-directory temp/rename/fsync, restrictive ownership, comment-preserving edits and migration backups. Tests: disk/permission/write failures keep the old document readable; malformed/missing state is recoverable; unsafe profile paths and incompatible migrations are rejected.
|
||
XDG roots now resolve with specification fallbacks and no shared runtime
|
||
fallback. Private layout creation, effective-owner/symlink checks, mode-0600
|
||
streaming atomic writes, directory sync, recoverable state loading,
|
||
comment-preserving validated edits, and backed-up forward migration are
|
||
covered by seven persistence integration tests.
|
||
- [x] **M2.3 Checkpoints:** per-profile observed state and separate validated desired object volume/mute, surface assignments, UI preferences, debounce and shutdown flush. Tests with a fake clock: sustained movement causes bounded writes and final state persists; crash/restart treats cached observations as stale, never restores runtime IDs or pending requests; an offline command survives restart as saved intent but only explicit restore applies it when the application launches (adopt emits no write).
|
||
A runtime-independent monotonic coordinator now keeps only the newest complete
|
||
snapshot, flushes after 500 ms quiet or two seconds continuously dirty, retries
|
||
failed writes without discarding pending state, and flushes on shutdown. Five
|
||
fake-clock tests cover timing, final persistence, typed checkpoint mutations,
|
||
stale restart observations, absent ephemeral state, and bounded explicit
|
||
restore behavior.
|
||
|
||
M2 verification on 2026-10-14: 17 configuration integration tests pass alongside
|
||
the existing 30 core tests and compile-fail doctest. Locked formatting,
|
||
all-target/all-feature checks and tests, doctests, strict Clippy, release build,
|
||
and no-default-feature checks/tests pass on Rust 1.88.0. M0.2 still requires a
|
||
real Jenkins run.
|
||
|
||
## M3 — Server and fake-adapter vertical slice
|
||
|
||
Dependencies: M1, M2. No real USB/audio device required.
|
||
|
||
- [x] **M3.1 Reducer/effects:** one owner, command origins/revisions, desired/pending/observed state. Tests: accepted intent is recorded before adapter dispatch; success requires readback/observation; failure leaves actual state truthful; external changes update views without an outgoing audio command.
|
||
- [x] **M3.2 Worker contract:** capabilities, snapshot barriers, readback, per-property ordered writes, operation results and fake backend. Tests: changes during snapshot are reconciled, old epoch/incarnation events are ignored, stream removal during write is handled, and newer pending intent survives an older completion.
|
||
- [x] **M3.3 Load and ordering:** bounded channels, latest-volume coalescing, preserved mute ordering, overflow fault reporting. Tests: burst ends at latest value, toggles are not silently lost or guessed, memory stays bounded, and final readback resolves ambiguous acknowledgments.
|
||
- [x] **M3.4 Lifecycle:** startup adopt, optional explicit restore, unavailable status, reconnect/backoff and orderly shutdown. Tests: startup emits no writes by default; reconnect resnapshots; restore conflict order is deterministic; disconnect expires in-flight state; cancellation joins workers and flushes state.
|
||
|
||
Exit: simulated MIDI input changes a virtual object through a fake adapter; observation generates a confirmed snapshot and feedback effect.
|
||
|
||
M3 verification on 2026-10-14: the pure reducer records desired and pending
|
||
state before dispatch and publishes only adapter observations as confirmation.
|
||
The fake adapter implements capability reporting, snapshot barriers, readback,
|
||
failure/removal behavior, and stale epoch/incarnation rejection. Its bounded
|
||
dispatch lane coalesces only volume motion and reports mute-edge overflow.
|
||
The in-process lifecycle slice covers adopt/restore policy, bounded retry,
|
||
disconnect invalidation, final draining/checkpointing, and simulated MIDI
|
||
volume intent converging through fake write acceptance and readback.
|
||
|
||
## M4 — PulseAudio adapter and real audio slice
|
||
|
||
Dependencies: M3.
|
||
|
||
- [ ] **M4.1 Bounded API spike:** verify libpulse-binding event loop, sink-input enumeration/properties, native volume conversion, change subscriptions and readback on PulseAudio and pipewire-pulse. Record native prerequisites and visibility limitations. Acceptance: isolated test streams are discovered and volume/mute changes are observed in both directions; no shell parsing in the production path.
|
||
The pinned binding now compiles against libpulse 17 on Rust 1.88, with
|
||
feature-gated no-backend builds. A no-autospawn client implements sink-input
|
||
enumeration, normalized metadata copies, linear multichannel conversion,
|
||
volume/mute writes, and mandatory readback. Keep this item open until the
|
||
isolated daemon fixture verifies subscriptions and both server variants.
|
||
- [ ] **M4.2 Implement worker:** own native handles on their loop thread; copy callback data; reconcile enumeration races. Contract tests: add/remove/change, operation error, unavailable daemon, reconnect, balanced stereo and multichannel conversion, external mixer edit.
|
||
- [ ] **M4.3 Adapter policy:** configured/CLI override, auto probe order/capabilities, diagnostics and feature errors. Tests: manual failure never falls back; auto chooses one authority, skips incapable candidates and never substitutes ALSA Master for applications; disconnect follows retry policy.
|
||
- [ ] **M4.4 Real-daemon fixture:** isolated playback streams and external control client. Acceptance: server command and external change both converge to the observed value/mute; stream churn and daemon restart recover. Document commands and opt-in fixture requirements; do not label mocks as hardware verification.
|
||
|
||
## M5 — MIDI transport, device identity, and first controller
|
||
|
||
Dependencies: M3; M4 for full end-to-end acceptance.
|
||
|
||
- [ ] **M5.1 Decode/bind:** midir connections; absolute 7-bit CC, note/CC press/release; validate channels/data. Tests: malformed/truncated messages, note-on zero, ignored clock traffic, unknown controls, duplicate press policy and surface-specific routing.
|
||
- [ ] **M5.2 Identity spike:** inspect port identifiers and ALSA/udev USB mapping; establish serial/path/manual fallback policy. Acceptance: record metadata actually exposed by tested controllers, distinguish two identical models where possible, and demonstrate explicit ambiguity resolution where not possible.
|
||
- [ ] **M5.3 Multi-surface lifecycle:** persist user IDs and independent input/output assignment; hotplug scanning/notification, retries and absent placeholders. Tests: unplug/replug/reboot-style port reorder preserve assignments; ambiguous serial-less matches stay unassigned; one failed device does not stop another.
|
||
- [ ] **M5.4 Pickup:** crossing/tolerance, current physical position, reset on external change/rebind/reconnect/profile switch. Tests: old physical position cannot jump audio at startup; crossing activates; another surface re-arms pickup; above-range target can be picked up at the endpoint.
|
||
- [ ] **M5.5 Physical smoke test:** one controller -> server -> application audio; then two controllers with overlapping MIDI message numbers. Acceptance: correct applications respond, bindings persist, and USB loss leaves server running. Record controller/firmware and environment.
|
||
|
||
## M6 — Confirmed MIDI feedback
|
||
|
||
Dependencies: M4, M5.
|
||
|
||
- [ ] **M6.1 Output profiles:** mute LED/value/motor capabilities, output pairing, mixed-state policy. Tests: confirmed/internal and external changes reach all bound surfaces; outputless surfaces receive no unsupported message; pending/failed writes never produce false success feedback.
|
||
- [ ] **M6.2 Feedback lifecycle:** attach snapshot, rate limits, deduplication, separate audio/output errors, documented device-specific echo suppression. Tests: feedback echoed as input cannot oscillate volume/mute; rapid updates converge; suppression does not swallow a genuine tested input sequence.
|
||
- [ ] **M6.3 Extended controllers:** 14-bit CC/pitch bend, explicit relative encoder modes, motor output and touch handling for declared profiles. Tests: endpoints/byte-pair ordering, relative increments, no motor push while touched, and non-motorized profile never receives motor commands. Hardware-verify every shipped specialized profile.
|
||
|
||
## M7 — Local server interface and CLI
|
||
|
||
Dependencies: M3, M2; may proceed after the fake-adapter slice.
|
||
|
||
- [ ] **M7.1 CLI:** serve/tui/validate/devices/status/profile switch arguments and override precedence. Tests: help/errors, invalid config has no side effects, explicit override wins for the session without silently modifying disk.
|
||
- [ ] **M7.2 IPC:** owned Unix socket, one-instance lock, version negotiation, length-bounded TOML frames, request IDs and revisioned state. Tests: wrong peer permissions, oversized/truncated/incompatible messages, second server, stale socket recovery and slow/disconnected client.
|
||
- [ ] **M7.3 Client resync:** full snapshot on attach/lag and revision checks for edits. Tests: TUI exit never stops the server; reconnect shows current observations; concurrent clients cannot overwrite each other's edits unnoticed.
|
||
|
||
## M8 — Live TUI
|
||
|
||
Dependencies: M7, M4 for real use.
|
||
|
||
- [ ] **M8.1 Mixer:** replace blocking prototype with event-driven client views and volume/mute actions. Test-backend assertions: groups/applications, mixed/offline/pending/error indicators, pickup state, resize and keyboard navigation reflect snapshots accurately.
|
||
- [ ] **M8.2 Devices/status:** show adapter selection/probe errors, device mappings, ambiguity and persistence problems. Tests: disconnected/unsupported states have useful actions; manual backend selection validates rather than silently applying incompatible mappings.
|
||
- [ ] **M8.3 Terminal lifecycle:** restoration on normal/error exit, nonblocking refresh, logging away from display. Tests: injected IO/client failure releases terminal guard; polling/refresh does not block server operation.
|
||
|
||
## M9 — TUI configuration editor
|
||
|
||
Dependencies: M8, M2, M1.
|
||
|
||
- [ ] **M9.1 Editor drafts:** separate tab to create/edit/delete applications, groups and faders; target/member selection, matcher preview, validation errors and referenced-delete handling. Tests: invalid regex/dangling member rejected; Cancel has no side effects; creating a group/fader produces the expected semantic TOML.
|
||
- [ ] **M9.2 Surface bindings / MIDI learn:** select surface, listen for one supported control, preview conflicts and save binding. Tests: learning suppresses the normal action, other surfaces are not captured accidentally, cancellation restores routing, duplicate binding is rejected.
|
||
- [ ] **M9.3 Apply/save/conflict:** server-owned revisioned edits, separate live apply and persistence. Tests: stale edits conflict, external file edits are not overwritten, comments survive save, write failure is shown as unsaved and leaves previous disk config usable.
|
||
|
||
## M10 — Transactional profile swapping
|
||
|
||
Dependencies: M9, M6, M7.
|
||
|
||
- [ ] **M10.1 Prepare/activate:** validate/probe candidate, pause/drain old writes, obtain new snapshot and atomically publish generation/mappings. Tests: invalid profile/unavailable manual adapter keeps old profile; late commands/events do not reach new targets; un-drainable native operations force reconciliation before activation.
|
||
- [ ] **M10.2 Restore/adopt policy:** default switch adopts live state; explicit restore uses saved object intents and deterministic overlap ordering. Tests: no surprise startup/switch write, restore limits enforced, offline/new members follow configured policy, pickup/feedback resync happens on every surface.
|
||
- [ ] **M10.3 Durable selection:** save active pointer after successful activation and reconcile state namespaces. Tests: disk failure marks active runtime selection unsaved, restart selects last durably saved profile, and corruption cannot silently activate an unintended profile.
|
||
|
||
## M11 — Native PipeWire and optional ALSA mixer
|
||
|
||
Dependencies: M4 adapter contract; native PipeWire follows a working Pulse slice.
|
||
|
||
- [ ] **M11.1 PipeWire spike:** verify playback node classification, writable SPA volume/mute parameters, channel balance, application properties, notifications and thread ownership. Acceptance: isolated native and Pulse-origin playback streams have documented coverage under a session manager; unsupported objects produce capability errors.
|
||
- [ ] **M11.2 Native implementation:** implement feature-gated worker and run shared contract suite plus real-daemon scenarios. Tests: external changes, reconnect, stream churn, snapshot races and normalized gain match domain semantics; auto never double-writes through Pulse and native APIs.
|
||
- [ ] **M11.3 ALSA hardware extension:** add explicit hardware target schema/UI selection, mixer element discovery/control, event/readback and capability reporting. Tests: unsupported mute rejected, integer/dB scaling round trips, external mixer changes observed, application profile never silently maps to master hardware gain.
|
||
- [ ] **M11.4 Feature matrix:** default Pulse, native-only, mixer-only, no backend, full-feature builds. Acceptance: each isolated feature builds with only its documented native prerequisites; manual selection of an unbuilt adapter gives a useful diagnostic.
|
||
|
||
## M12 — Reliability and release
|
||
|
||
Dependencies: all required feature milestones; hardware-only ALSA remains an explicitly scoped extension.
|
||
|
||
- [ ] **M12.1 Adversarial replay:** deterministic reconnect/churn/write-failure/echo/reordered-event/profile-switch scenarios. Property tests preserve domain invariants; command storms stay bounded and converge without starving mute or shutdown.
|
||
- [ ] **M12.2 Integration matrix:** PulseAudio, pipewire-pulse, native PipeWire, two controllers, external desktop mixer, reload/restart, read-only/full state directory. Record fixtures, supported device profiles and known limitations; never run destructive audio tests on the user's current session by default.
|
||
- [ ] **M12.3 Packaging:** example TOML profiles, schema/migration documentation, build/install guide, optional systemd user unit and troubleshooting. Acceptance: fresh user install can discover, bind, edit, save, restart and reconnect without root or manual state repair.
|
||
- [ ] **M12.4 Release gates:** all workspace/default/feature/MSRV checks, reproducible lockfile, license review and dependency advisory review using maintained tooling selected at implementation time. Measure/control latency under multi-surface load and publish the tested envelope.
|
||
|
||
## User requirement coverage
|
||
|
||
| # | Requirement | Work items |
|
||
| --- | --- | --- |
|
||
| 1 | MIDI -> server records intent -> audio adapter | M3.1–M3.3, M5.1, M5.5 |
|
||
| 2 | Different sound manager adapters | M4, M11 |
|
||
| 3 | Automatic/manual selection | M4.3, M8.2, M11.4 |
|
||
| 4 | Exact/regex application selectors | M1.2, M9.1 |
|
||
| 5 | One fader controls grouped applications | M1.3–M1.4 |
|
||
| 6 | Mute/unmute | M1.5, M4.2, M6.1 |
|
||
| 7 | Load current volume/mute/state | M3.2–M3.4, M4.2, M10.2 |
|
||
| 8 | TUI tab creates/edits groups and faders | M9 |
|
||
| 9 | Fader -> virtual application/group -> adapter | M1.3, M3.1–M3.2 |
|
||
| 10 | External audio changes update state | M3.1–M3.2, M4.4, M11.2 |
|
||
| 11 | Server sends state back to MIDI surfaces | M6 |
|
||
| 12 | Concurrent surfaces and remembered bindings | M5.2–M5.5, M2.3 |
|
||
| 13 | Architecture with design improvements | architecture.md; pickup, epochs, partial failures, atomic reload |
|
||
| 14 | Swappable configuration; durable data in TOML | M2, M9.3, M10 |
|
||
| 15 | Library research | architecture.md library table; M4.1, M5.2, M11.1 |
|
||
|
||
First implementation target: M0, then a hardware-free M1/M2/M3 slice; follow with Pulse and one MIDI controller before broadening backend or device protocol support.
|