fader_master/task.md

41 KiB
Raw Blame History

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. While the only worker is FreeBSD, the ENABLE_NATIVE_BACKENDS=false default runs explicit portable-package gates and honestly marks coverage unavailable. Enabling that build parameter restores the full existing Linux/native matrix; M0.2 remains open until that mode passes on a provisioned Linux worker.
  • 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: active absolute/sync planning plus a prepared relative-group domain state with per-member independent/external maxima, channel balance, reversible zero, normalized position, lifecycle removal, aggregate max/mixed state, and clipping. Tests: heterogeneous members, externally changed member anchors, zero-to-maximum recovery, empty group, late joiner behavior, and partial failure. Runtime profile validation keeps relative reserved and accepts only absolute groups.
  • 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-pulse on 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. Validated profile choices and ordered preferences now translate into a typed runtime policy, with a non-persistent session/CLI override taking precedence. Probes retain server identity, capability, availability, and unbuilt-feature diagnostics. Auto mode stops at its first capable authority; manual mode never falls back; application profiles reject hardware-only candidates. Disconnect backoff remains pinned to the selected authority until a reload.
  • 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. An opt-in fixture now creates a uniquely named silent paplay stream and verifies real worker volume/mute writes, independent-client edits, readback, removal, and replacement without targeting other desktop streams. That phase passed against PipeWire 1.6.9 through pipewire-pulse on 2026-10-14. A separately acknowledged test restarts the known PipeWire user services and requires disconnect, bounded retry, a new epoch, and a complete resnapshot. That disruptive phase passed on 2026-10-15: it observed epoch 20 disconnect, epoch 21 reconnect, and a complete fresh snapshot. The same stream fixture can target an isolated standalone PulseAudio server through PULSE_SERVER.
  • M4.5 Default output master: expose the Pulse server's current default output as a stable logical target; subscribe to sink/default changes and keep application streams distinct. Tests: balanced output volume and mute use confirmed readback, external changes re-arm pickup, a default-sink switch invalidates the old handle, and application commands cannot reach an output. The Pulse worker, profile schema, live mixer, IPC, and TUI now carry a dedicated output/default object. The Arch profile assigns the APC master strip CC 56 / Note 98 to it and moves Media to CC 50 / Note 66. Keep this item open until the physical output checklist passes on PipeWire/Pulse.

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.

M4.3 verification on 2026-10-14: deterministic policy tests cover manual and automatic selection, session override precedence, incapable/unavailable candidates, ALSA application rejection, compiled-feature errors, single authority, and bounded same-backend reconnect. A read-only auto probe selected the Pulse adapter and reported PulseAudio (on PipeWire 1.6.9) version 15.0.0; an explicit native PipeWire request failed visibly without fallback.

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. The feature-gated midir 0.11.1 transport enumerates opaque port IDs and names, owns each input connection, and copies decoded events into a bounded nonblocking callback lane with explicit overflow state. The pure decoder and surface-scoped router cover every channel and 7-bit endpoint, press/release normalization, press-only toggles, unrelated traffic, and malformed input. An opt-in monitor lists real ports and watches one selected input without changing audio or saved configuration.
  • 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. The Linux probe now maps midir's ALSA client:port through the sequencer client card number to udev, copying VID/PID, serial, and physical path. Pure policy tests prove serial and path matching survive port reorder and that two identical serial-less candidates stay ambiguous until manually selected. An Akai APC MINI (USB 09e8:0028, firmware-reported serial Ver00.10) was observed on 2026-10-15. Its serial and ALSA backend ID 36:0 remained stable across USB sockets while its udev path changed, validating serial-first matching on real hardware. Keep this item open until the two-identical-device ambiguity cases in the checklist can be exercised.
  • 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. The server now scans on a bounded interval, matches validated VID/PID and serial/path hints, owns independent bounded input connections, and publishes connected/missing/ambiguous/error placeholders through IPC and status. Deterministic tests cover reorder, unplug/replug, ambiguity, duplicate claims, retry after one connection failure, and isolation between surfaces. A live smoke run connected the APC MINI as 36:0; keep this item open for physical unplug/replug acceptance and durable editor-managed assignment persistence.
  • 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. The pure pickup state machine and routed live server cover startup inhibition, tolerance and crossing activation, external-change/reconnect resets, competing surfaces, and above-range endpoint pickup. The Arch profile routes APC MINI CC 48/49/50/56 and notes 64/65/66/98 to Music, Browser, Media, and the default output master. Input targeting an offline/read-only object is a nonfatal no-op, leaving other targets and the server available. Keep this item open until pickup state is published to the TUI and profile-switch rearming is implemented.
  • 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.

M5.1 verification on 2026-10-14: nine decoder/router/transport tests pass with the native transport enabled, seven hardware-free tests pass without default features, and the locked dependency set builds and tests on Rust 1.88.0. The host ALSA sequencer probe initialized and enumerated port 14:0; controller traffic remains an opt-in checklist item. Locked workspace formatting, all-target/all-feature checks and tests, doctests, strict Clippy, release build, and no-default-feature checks/tests pass.

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. Typed subcommands now validate profiles before probing audio or creating the runtime socket. serve, tui, validate, devices, and status are active; profile switch parsing is reserved for the transactional M10 implementation. A session audio override is applied only to runtime selection.
  • 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. The first local slice uses an owned mode-0600 socket, bounded request timeouts, versioned/request-correlated 64-KiB TOML frames, revisioned snapshots, one-instance detection, safe stale-socket replacement, same-UID Linux peer authentication, and a 20-ms server-side frame deadline so stalled clients cannot monopolize the state owner.
  • 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. Each request receives a complete current snapshot; stale edit revisions trigger a background resnapshot and one retry. The TUI's IPC worker exits independently of the server, starts with a disconnected placeholder when the socket is absent, retains the last confirmed view during failures, and retries until a server appears again. Competing edits from one attached revision prove that only the first is accepted and that a lagging client obtains the newer complete snapshot before retrying.
  • M7.4 Buffered interaction: isolate blocking IPC and native audio round trips from input/rendering; coalesce unsent volume motion, preserve mute edges, update the local view immediately, and converge on confirmed state. Tests: a blocked client call does not block snapshot/redraw access, a volume burst sends its first in-flight and final buffered values only, stale edits resnapshot and retry, rapid mute presses remain ordered, and server dispatch uses bounded backpressure rather than failing on a merely busy worker. A TUI client thread owns IPC, publishes optimistic shared snapshots, polls at 20 ms while pending and 250 ms while idle, and retains a bounded 128-edge mute FIFO. Quit restores the terminal before teardown; cooperative workers join in a short grace period, while a worker stuck in a server request is detached so it cannot block exit. The live server uses the tested 256-command coalescing queue ahead of a one-slot Pulse command lane, an independent 256-event snapshot lane, and a batch event drain. Matching Pulse subscription echoes retain the originating operation so confirmed writes do not repeatedly re-arm pickup during continuous physical fader motion; genuinely different external observations still re-arm it. Profiles may tune the shared server/native polling interval from 1 through 100 ms (10 by default) without changing bounded latest-value coalescing.
  • M7.5 Combined and dedicated launchers: provide fader_master_server, fader_master_client, and an all-in-one fader_master default mode. Combined mode reuses a responding per-user server, starts one only when absent, resolves startup races through the owned socket, and stops and joins only the server it created. Existing serve and tui subcommands remain compatible. Tests: CLI parsing and binary help cover all three entry points; the launch decision never invokes server startup after a successful probe.

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. The live slice now lists stable configured applications and groups, preserves offline and mixed gain/mute states, deduplicates overlapping group streams, and fans sync-group writes out with absolute policy. It refreshes without blocking rendering or server operation, updates accepted input locally, and shows pending, read-only, and error indicators. Pickup state now follows configured surface/fader bindings through IPC and is rendered as unavailable, waiting, tracking, or mixed. Profile-aware hands-on checks including terminal resize passed on 2026-10-15. A later UI refinement should add a denser row mode and/or horizontal fader layout for smaller terminals.
  • 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. The live TUI now preserves server-published MIDI placeholders and shows connected backend IDs, connection progress, missing-device guidance, ambiguity selection guidance, and transport errors in its compact status line. Editor save/conflict failures now remain visible while the prior live state and unsaved draft are retained.
  • 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. Blocking IPC runs on a joined worker and a delayed request cannot block redraw access. The restoration guard is independently injected and proven to run when client initialization returns an error; client/transport diagnostics are rendered inside the TUI rather than printed into the active terminal.
  • M8.4 Relative-group activation (reserved): wire the prepared per-member maximum state into origin-aware runtime observations, lifecycle, snapshots, pickup, and editor help before allowing volume_mode = "relative" in profiles. Tests: group confirmations never rebase maxima; application MIDI, TUI, and external edits rebase only the affected member; zero is reversible; joins adopt live maxima and removals discard anchors. Do not enable this mode in shipped profiles without a separate product decision.
  • M8.5 Built-in themes (stretch): centralize semantic TUI colors and provide Default, Dracula, Nord, Gruvbox Dark, Catppuccin Mocha, and Solarized Dark palettes. Profiles persist the selected palette; tui --theme is an optional session override and t edits the profile draft. Tests: known CLI names parse, unknown names fail, cycling wraps deterministically, and the selected palette/name reach rendered cells.

First live TUI slice verification on 2026-10-15: a real server selected Pulse against PipeWire, reached ready, and published the active Qobuz playback stream through the private socket. A PTY-rendered client displayed its confirmed 9% gain and restored the terminal on quit without stopping the server. Locked workspace formatting, all-target/all-feature checks and tests, doctests, strict Clippy, release build, no-default-feature checks/tests, and the complete Rust 1.88 all-feature test suite pass. M7.2, M7.3, and M8.1 remain open for the explicit acceptance gaps noted above and in the hands-on checklist.

Hands-on acceptance on 2026-10-15 confirmed one-instance enforcement, live multi-stream display, keyboard selection, confirmed volume/mute actions, external-change refresh, stream churn, independent TUI exit/reconnect, and terminal restoration against PipeWire 1.6.9. Terminal resize remains to be checked alongside the next profile-aware TUI slice.

Profile-aware TUI verification on 2026-10-15: hardware-free tests cover stable application/group rows, offline values, mixed gain/mute aggregation, group write fan-out, pending state, stale-client resync, and small-terminal rendering. A read-only live smoke run against PipeWire 1.6.9 matched the reported Qobuz stream into Music and Media group while retaining Browser offline. All workspace formatting, all-target/all-feature checks and tests, doctests, strict Clippy, release build, default and no-default-feature tests, and isolated Pulse, no-audio, midir, and no-MIDI feature checks pass on Rust 1.88.0.

The subsequent hands-on run passed application-isolated writes, two-member absolute group writes, mixed gain/mute aggregation, offline/rejoin behavior, resize, and reconnect. Waterfox initially remained offline because its reported Waterfox/waterfox-bin metadata was absent from the example selector; the regression-tested profile fix then matched it into the two-stream media group.

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. Transactional, comment-preserving draft primitives now create applications, absolute groups and faders, and roll back invalid regexes or referenced deletes. A separate Config tab now shows the server-owned applications, group membership, logical fader targets, pickup policy, and MIDI assignments. The keyboard editor accepts explicit target/member IDs, previews live matcher results, and provides the full create/update/delete surface with inline validation errors and cancellation. The server now owns the validated draft and its independent revision; stale or invalid edit requests are rejected without advancing or altering it, and accepted edits are exposed as an unsaved draft in the Config tab.
  • 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. The Config tab starts surface/fader/action-scoped learning with L and cancels with C. Captured CC/note identity is added to the validated server draft; conflicts are shown without changing the draft revision.
  • M9.3 Save/conflict: server-owned revisioned edits with one Save action that persists and activates the validated draft. Tests: stale edits conflict, external file edits are not overwritten, comments survive save, and write failure leaves the previous disk and live configuration usable.
  • M9.4 Mixer-first layout: persist ordered logical-fader and separator entries, synthesize declaration-order entries for old profiles, and retain hidden faders in place. The main mixer can reorder either entry type, add/edit/ remove separators, hide visible faders, and restore hidden faders without changing targets or bindings. Tests: invalid/duplicate/dangling layout entries fail; reorder and hide/show round trip through comment-preserving drafts; a hidden application remains routable through a visible group. Profiles now validate and publish ordered fader/separator entries, with declaration-order synthesis for existing files. The mixer renders that layout and provides direct move, separator add/rename/remove, hide, and hidden-fader restore actions through revisioned comment-preserving drafts. Separator add and rename collect their label in a centered modal rather than reusing the mixer status line. Hidden restoration now lives in the Config settings page rather than a second mixer mode. Config also persists a Vertical or Horizontal mixer orientation. Horizontal mode renders side-by-side console-style fader strips; vertical mode keeps the stacked card layout. Separators are inline labeled divider columns in Horizontal mode so entries stay on one row, and span the display width in Vertical mode. Arrow-key selection and reordering follow the layout axis, while the perpendicular arrows adjust volume.
  • M9.5 Guided fader editor: replace pipe-delimited table commands with a selected-fader form. Application faders edit capture field/mode/pattern; groups select eligible application faders and show the absolute group mode; volume and mute assignments each expose controller selection, Learn MIDI, and Unlearn MIDI as distinct actions. Tests: editing one field preserves unrelated selectors/bindings, unlearn removes only the selected action, learn conflicts preserve the draft, and group selection translates to deduplicated application IDs. E on a mixer fader opens a field-oriented form. Application capture edits Field, Exact/Regex, and Pattern separately while preserving other selectors; Pattern opens a cursor-aware modal for local insertion and deletion rather than requiring the full value to be erased; groups show application-fader membership and the currently supported Absolute mode. Volume and Mute show separate controller, Learn MIDI, and Unlearn MIDI actions. Learning opens a modal prompt for a fader movement or button press; relearning atomically replaces only the chosen action, and validation conflicts retain the draft. Visibility uses the same form. The form also persists a per-fader Slim, Standard, or Thick size in the mixer layout. Existing profiles default to Standard. Slim renders in one terminal row for vertical cards and as a narrower strip for horizontal faders. Config stores a validated default controller; unassigned volume and mute learn actions inherit it while explicit bindings keep their selected surface.
  • M9.6 Single-screen configuration workflow: remove the normalized Config table browser once all its operations are reachable from the mixer, keep Save and draft/durable status visible, and expose hidden-item restoration and device/backend diagnostics without a separate primary tab. Tests: keyboard navigation and every modal work at small terminal sizes; Escape backs out one level and never quits; invalid edits retain form input. The normalized table browser and pipe-delimited object commands are removed. Config is now a secondary settings/status page for the persisted profile theme, hidden restoration, Save, learning cancellation, and backend/device state. Hidden restoration uses one settings action that opens a popup listing every hidden fader rather than expanding the settings page with one row per fader. MIDI-device status rows are selectable and open a details popup where the profile's default-controller assignment can be set or cleared. Keep this item open until any remaining required object-creation workflow is available from the mixer and its small-terminal acceptance passes.

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. profile switch ID now prepares a sibling profile, rejects invalid/native-only candidates and runtime timing changes, waits for pending audio reconciliation, then publishes matching, groups, faders, pickup, and MIDI together. Activation advances the mixer view revision so pre-switch client commands are stale.
  • 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. Default switching is write-free. profile switch ID --restore now validates the saved state before activation, restores online applications in profile order, and retains offline intents only under new_stream = "restore". Pickup is re-armed; completion still depends on the M6 feedback lifecycle.
  • 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. Successful activation atomically writes the strict XDG active-profile pointer. serve without --config follows it; corrupt pointers fail before audio/socket side effects, while pointer-write failure keeps the new runtime profile active but visibly marks its selection unsaved.

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.