fader_master/task.md

18 KiB
Raw Permalink Blame History

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

  • 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.