22 KiB
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
- 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. 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. - 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.
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.
- 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.
- 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.
- 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.
- 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.
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. Manual verification on 2026-10-14
passed discovery, balanced volume/mute control, subscriptions, external mixer
changes, and stream churn against PipeWire 1.6.9 through
pipewire-pulseon Arch Linux. Keep this item open until the isolated fixture also verifies a standalone PulseAudio server. - 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. The bounded Pulse worker creates and retains all native objects on its owner thread, subscribes before snapshotting, replays queued notifications before the snapshot barrier, and copies metadata and observations across the event lane. Per-epoch incarnation tracking rejects stale commands and distinguishes reused sink-input indexes. Contract tests cover connection failure, reconnect epochs, add/change/remove and external edits, stereo/multichannel writes, rejected operations, stale handles, and explicit overflow-driven resync.
- 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.
M4.2 verification on 2026-10-14: the scripted worker contract suite passes
without an audio daemon, and a read-only owner-thread smoke run against PipeWire
1.6.9 through pipewire-pulse produced a framed snapshot of live application
streams. Locked workspace 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. M4.1 still awaits the standalone PulseAudio fixture, and M0.2
still requires a real Jenkins run.
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.