docs: record completed Phase 7

2026-08-21 21:56:06 -04:00
parent d72271bd2e
commit ba96e59db0
2 changed files with 60 additions and 9 deletions
@@ -20,9 +20,10 @@ construction gates are built, validated and committed locally in PixelPass (`6be
 PixelPass (`956534f`).** **The revised Row 9 positive/negative late-arrival partition is built,
 validated and committed locally in PixelPass (`7b11827`).** The deterministic Phase 6
 link-manager matrix is complete. **The production-path three-arm AEC leak qualification is
-built, validated and committed locally in PixelPass (`e027bc6`), completing Phase 6.** Phases
+built, validated and committed locally in PixelPass (`e027bc6`), completing Phase 6.**
-7–9 are not built — nothing released to date changes the feature's user-visible behaviour.
+**Phase 7's public selector, AEC wiring and versioned capability response are built, validated
-**Phase 7 is now the current front.**
+and committed locally in PixelPass (`792f2bd`).** Phases 8–9 are not built — nothing released to
 date changes the feature's user-visible behaviour. **Phase 8 is now the current front.**
 **Date:** 2026-07-21 (v4); status line refreshed 2026-08-21
 **Design of record:** [`screenshare-audio-exclusion-plan.md`](screenshare-audio-exclusion-plan.md) v3.8, round 11.
 **Scope:** *ordering, gates and acceptance criteria only.*
@@ -890,8 +891,9 @@ shippable runtime override.
 ### Phase 7 — public mode selector + capability advertisement (pixelpass ships first)
 ⚠️ **Round-3 P1: nothing in v3 ever promoted the hidden trigger to a public flag.** 0d added an
-internal mode input; Phase 7 advertised capability and naming; Phase 8 added `--aec`, the picker
+internal mode input; Phase 7 advertised capability and naming; Phase 8 added PeerSpeak's
-and status. No phase required the actual **mode selector** to exist publicly or to be passed.
+`--aec` emission, the picker and status. No phase required the actual **mode selector** to exist
 publicly or to be passed.
 The result would be a capability-gated picker entry that, when chosen, still spawns legacy
 whole-desktop capture — the feature appearing to ship while doing nothing. Reachable: peerspeak's
 host argv has no mode parameter (`screenshare/mod.rs:152`) and pixelpass's `HostOpts` has no mode
@@ -910,6 +912,39 @@ byte-identical, absent `--aec` still accepted.
 v3.4 §11 public naming is a **blocking user input at the start of this phase**. Internal typed
 variant names (0d) do not block on it.
 > **Phase 7 — built, validated and committed locally as PixelPass `792f2bd` on 2026-08-21.** The
 > user selected `--audio-mode=desktop-shared|desktop-excluding`. The shared value resolves to the
 > byte-identical legacy plan; the excluding value reaches the existing typed
 > `DesktopExcluding` plan and requires an explicit `--aec=off|pulse-module:<idx>`. The exact
 > Phase-4 parser is now the public CLI parser, malformed values fail before host startup, and the
 > selected AEC config is carried through `CapturePlan` into the production graph controller
 > instead of being hardcoded to `Off`. Both protocol flags require `--host`; the hidden 0d
 > trigger remains test-only and defaults to `Off` for its existing fixtures.
 >
 > `pixelpass --capabilities` now emits exactly one versioned JSON line:
 > `{"schema_version":1,"capabilities":{"strict_app_audio":true,"desktop_audio_exclusion":true}}`.
 > The two booleans are independent by construction. The old-PeerSpeak/new-PixelPass golden feeds
 > both existing whole-desktop and strict per-app argv into the new parser unchanged and proves
 > absent `--audio-mode`/`--aec` still resolves to legacy behavior. The existing byte-exact legacy
 > GStreamer audio-tail gate remains green; `--help` probing is retained only for old integrations.
 >
 > Phase-7 validation also made the Phase-6 signal gate consume the selector-owned AEC config. Its
 > first rerun caught the stale test-local input immediately. Two later reruns exposed a separate
 > measurement issue: a coherent projection of sub-LSB stochastic noise can land in an unusually
 > deep single-bin null, so comparing only control-bin to guarded-bin overstated the rig's
 > resolution. Retained raw spectra showed no coherent guarded 1500 Hz peak and comparable nearby
 > noise. The committed gate now defines the control resolution as the larger of the exact control
 > bin and the 90th percentile of neighboring ±5–25 Hz projections outside the Hann main lobe;
 > the 3 dB guarded tolerance and 18 dB naive positive-control margin remain unchanged. This is a
 > resolution estimate for the steady-state gross-leak gate, not the Phase-9 PN/MLS upgrade.
 >
 > Final PixelPass validation: 354 passed, 0 failed and 13 ignored; strict all-target Clippy,
 > formatting, `git diff --check`, the exact capability/help probes, `pixelpass --doctor`, and all
 > four serialized live audio gates pass. The final Pulse/PipeWire/process/temp-file residue scan
 > is empty. Nix is unavailable, so validation used system Rust 1.96.1. Phase 8 is next: bind the
 > capability to the resolved PixelPass path, add the capability-gated picker/argv, and carry
 > exclusion status causally to the UI.
 ### Phase 8 — peerspeak integration
 - `EchoCancelGuard::module_index()` accessor (currently private; only `source_name()` /
  `sink_name()` exist).
@@ -13,7 +13,9 @@ and committed locally in PixelPass `d09ee9b`. The Row 1 mutation-edge identity g
 `6be07ef`. The independent Row 6 refusal gates (`956534f`) and revised Row 9 partition
 (`7b11827`) complete the deterministic link-manager matrix. The production-path three-arm AEC
 leak qualification is built, validated and committed locally in PixelPass `e027bc6`; **Phase 6
-is complete and Phase 7 is the current implementation front.**
+is complete.** The public selector, AEC wiring and versioned capability response are built,
 validated and committed locally in PixelPass `792f2bd`; **Phase 7 is complete and Phase 8 is the
 current implementation front.**
 **Date:** 2026-08-21 (v1: 07-19 · v2: 07-20 · Option C 07-20 · v3.1 r4 · v3.2 r5 · v3.3 r6 ·
 v3.4 r7 · v3.5 r8 · v3.6 r9 · v3.7 r10 · v3.8 r11 2026-08-21)
 **Origin:** Joe's suggestion — "whitelist all audio except audio coming from peerspeak."
@@ -1445,9 +1447,23 @@ above the control floor at this analysis resolution**, not proof of absence. Ful
 346 passed and 13 ignored; strict Clippy, all four serialized Phase 6 live audio gates,
 `pixelpass --doctor` and residue checks pass.
-1. **Continue with Phase 7:** publish the mode selector and versioned capability from PixelPass,
+PixelPass commit `792f2bd` completes Phase 7. The selected public contract is
-   preserving the old-PeerSpeak/new-PixelPass compatibility gate.
+`--audio-mode=desktop-shared|desktop-excluding`; excluding requires the explicit
-2. Then complete Phase 8's capability-gated PeerSpeak argv, picker, UI and causal status path.
+`--aec=off|pulse-module:<idx>` state and carries it into the production fan-out controller.
 `pixelpass --capabilities` emits schema version 1 with independent `strict_app_audio` and
 `desktop_audio_exclusion` booleans. Exact old-PeerSpeak argv remains legacy and byte-compatible.
 Phase-7 validation also corrected the Phase-6 estimator without weakening its declared margins.
 Several extra runs showed that one sub-LSB coherent control bin can fall into a stochastic null.
 The gate now resolves its control floor from that bin plus the 90th percentile of neighboring
 frequencies outside the Hann main lobe; the 3 dB guarded tolerance and 18 dB naive margin are
 unchanged. Final validation is 354 passed and 13 ignored; strict Clippy, all four serialized
 live gates, exact capability/help probes, `pixelpass --doctor` and residue checks pass.
 1. **Continue with Phase 8:** bind capability results to the resolved PixelPass path and add the
   capability-gated picker plus exact mode/AEC argv.
 2. Carry Phase-6 status events causally through the core/UI message boundary, preserving existing
   per-app argv byte-for-byte and proving old-PixelPass fallback emits no new flags.
 Still owed beyond that, unchanged: the §9.2 rig upgrade before any exclusion claim is
 published, and **field-test §12** — nothing in this design has been tested over the real