diff options
Diffstat (limited to 'docs/specs/2026-07-09-audio-doctor-spec.org')
| -rw-r--r-- | docs/specs/2026-07-09-audio-doctor-spec.org | 25 |
1 files changed, 16 insertions, 9 deletions
diff --git a/docs/specs/2026-07-09-audio-doctor-spec.org b/docs/specs/2026-07-09-audio-doctor-spec.org index 028fe8c..5851332 100644 --- a/docs/specs/2026-07-09-audio-doctor-spec.org +++ b/docs/specs/2026-07-09-audio-doctor-spec.org @@ -4,16 +4,21 @@ #+TODO: TODO | DONE #+TODO: DRAFT READY DOING | IMPLEMENTED SUPERSEDED CANCELLED -* READY Audio Doctor — diagnose and repair a broken sound stack +* IMPLEMENTED Audio Doctor — diagnose and repair a broken sound stack :PROPERTIES: :ID: 6ce3f2ef-052e-40cb-9067-42f8e665f813 :END: +- [2026-07-10 Fri] Superseded in part, later the same day: the DOCTOR section-header key and its DIAGNOSE key are replaced by a doctor key per direction, and the classifier grows an input side. See [[file:2026-07-10-audio-doctor-input-side-spec.org][2026-07-10-audio-doctor-input-side-spec.org]] (DRAFT). This spec's other decisions stand. The gap: nothing here ever examined the microphone, and the Non-Goals never said it would not. +- [2026-07-10 Fri] IMPLEMENTED — Phases 0 through 4 shipped (dotfiles =4d42eb3=, =01a1d80=, =76857e3=, =7223c51=, =1550ac8=, =4320255=, =bd33440=). Xruns stayed out of v1 as decided. Per-application stream routing remains a Non-Goal. The wall carries the net panel's copy + close controls, added past the spec at Craig's request; standardizing them across the other panels is tracked as its own task. - [2026-07-09 Thu] READY — all eight Decisions closed. Written from the roam-inbox ask "look into a doctor button for the audio panel: what happens if pulseaudio or its equivalent is borked? would we know? how could we test for it? what remedies would we have?" Probe set, classifier, and remedy tiers are grounded in a live survey of ratio's stack. Phase 0 shipped ahead of the rest. -* READY Status +* IMPLEMENTED Status :PROPERTIES: :ID: 1cc2b355-9450-4ace-bdb3-b935f7051918 :END: +- [2026-07-10 Fri] IMPLEMENTED — the build closed three things the Decisions did not anticipate. A tenth verdict =tooling-missing= (=remedy: None=), because an absent =pactl= is an unobserved stack rather than a broken one. A =re-probed= marker between a fix run's two row blocks, because unlabelled they read as the doctor contradicting itself. And the read-only key is named DIAGNOSE beside the engraved DOCTOR header rather than being named DOCTOR itself (Craig's call, 2026-07-10, after asking why the panel carries two keys where net's carries one; the two presses stand on the audibility decision, and net's single key auto-fixes because its remedies are cheap). + + Live verification on ratio replaced the planned VM run for remedies 1, 4 and 5, and immediately found two bugs no fake could surface: =pactl get-default-sink= prints the literal =@DEFAULT_SINK@= placeholder when no default is set, and remedy 1 re-probed before WirePlumber had re-created the devices, reporting a repaired stack as broken. Both fixed. - [2026-07-09 Thu] READY — Craig closed the six open Decisions, all to the recommended option: DOCTOR is a section-header key; CLI-first with the GUI as a face; hung and dead are two verdicts sharing one remedy; tiers stay Auto/Confirm/Arm as drafted; a stream-active guard refuses the audible remedies and is overridable by pressing again; xruns are out of v1. Two consequences worth naming, because they were not obvious when the questions were asked. Taking the guard is *why* remedy 4 can stay at Confirm — the danger lives in the state of the machine, not the identity of the remedy. And the guard must read its stream state from =pw-dump= rather than =pactl=, because the remedies it protects are exactly the ones you reach for when the Pulse layer is dead; a =pactl=-fed guard would go blind precisely when it is needed. @@ -24,7 +29,7 @@ | Field | Value | |--------+-------------------------------------------------------------------------------------------------------------| -| Status | ready | +| Status | implemented | |--------+-------------------------------------------------------------------------------------------------------------| | Owner | Craig Jennings | |--------+-------------------------------------------------------------------------------------------------------------| @@ -268,17 +273,19 @@ Sequenced so each phase is independently green and independently useful. Nothing CLOSED: [2026-07-09 Thu] Shipped ahead of the rest (dotfiles =4d42eb3=). =build_status()= now guards all four pactl reads, not just the two list reads, so a half-wedged server dims the bar's audio module instead of killing it. =fake-pactl= grew =FAKE_PACTL_SLEEP_DEFAULTS= to express "answers the lists, hangs on the defaults" — the blanket sleep knob cannot, because the first call would hang and mask the bug. -** Phase 1 — =diag.py=, the four probe tiers +** DONE Phase 1 — =diag.py=, the four probe tiers Bounded probes, a context dict, fakes for every outcome including hung. No classifier, no GUI. =audio diag --json= prints the context. -** Phase 2 — =classify.py=, the verdict +** DONE Phase 2 — =classify.py=, the verdict Pure function, fixture-driven, pairwise over the parameter space. =audio doctor= (read-only) prints findings and a verdict in the CLI. Already useful from a TTY at this point. -** Phase 3 — =repair.py= + =doctor.py=, the fix path +** DONE Phase 3 — =repair.py= + =doctor.py=, the fix path One function per remedy, each re-probing what it claims to fix. =audio doctor --fix= applies the lightest matching remedy. VM-tested for remedies 1, 4, and 5. -** Phase 4 — the DOCTOR key and the results wall -GUI face over the CLI. Streams events to a wall, off the GTK thread. AT-SPI smoke over the key, the wall, and the fix path on fixtures. +** DONE Phase 4 — the DOCTOR key and the results wall +CLOSED: [2026-07-10 Fri] +Shipped (dotfiles =4320255=). GUI face over the CLI. Streams events to a wall, off the GTK thread. AT-SPI smoke over the key, the wall, and the fix path on fixtures. -** Phase 5 — flip this spec to IMPLEMENTED +** DONE Phase 5 — flip this spec to IMPLEMENTED +CLOSED: [2026-07-10 Fri] With a history line naming what shipped and what was left out. |