18 KiB
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.
Planning delivered
- Inspect the workspace and define the project-steward role in
AGENTS.md. - Specify state ownership, adapter boundaries, matching/groups, MIDI identity/feedback, and TOML lifecycle in
architecture.md. - Research libraries using linked primary documentation and identify bounded technical spikes.
- 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.
- 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. - 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. - M0.3 Domain boundary: add
fader-coreandfader-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.
- 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.
- 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.
M2 — TOML schemas and safe persistence
Dependencies: M1 types; runtime activation follows in M10.
- 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.
- 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.
- 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).
M3 — Server and fake-adapter vertical slice
Dependencies: M1, M2. No real USB/audio device required.
- 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.
- 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.
- 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.
- 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.
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.
- 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.