# Design v3.8: whole-desktop screen-share audio without self-echo

**Status:** 🟢 **v3.8 — round 11: both pre-Phase-6 design gates are closed.** The graph now
models an unobservable playback-to-capture route as a conservative same-`device.id` hardware
edge (§6.9), and the 2 s readiness budget is retained after repeated baseline, inflated-graph,
and live-churn calibration. The targeted live dry-run partition passed. The first pure Phase 6
channel-planning prerequisite is committed locally in PixelPass `781defc`; the first bounded
live fan-out mutation slice is built, validated and committed locally in PixelPass `98cde2c`.
The four versioned causal status events are built, validated and committed locally in PixelPass
`5a65f50`. Capture-sink replacement and successful all-channel relinking are built, validated
and committed locally in PixelPass `d09ee9b`. The Row 1 mutation-edge identity gate and Row
8d/8e fail-closed construction gates are built, validated and committed locally in PixelPass
`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.**
**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."
**Scope:** a new capture mode in pixelpass (`src/host/pipeline.rs`, `src/host/audio.rs`),
playback tagging + AEC-identity export + teardown-ordering invariants in peerspeak.

**Why v3 is a rewrite, not a patch.** v1 and v2 both described a design that *moves*
desktop streams onto a capture sink. That design is dead. v2's §5.1 adopted **Option C
(copy via a second owned link)** after a measured feasibility spike, and the AEC
identity gate — the one thing both reviewers agreed nothing could go ahead of — has
since passed. Roughly two thirds of v2 described problems Option C does not have.
Carrying that text forward as "retained for the record" made the live plan unreadable.
v1/v2 remain in git history at `88ad5a0` and `10203e1`.

**Review history**
| Round | Artifact | Verdict |
| --- | --- | --- |
| v1 review | `~/Documents/handoff-docs/Codex/peerspeak/review-2026-07-19-audio-exclusion-design.md` | not sound as written; 4 blockers, all verified correct |
| v2 review | `…/review-2026-07-20-audio-exclusion-design-v2.md` | blocked; produced Option C |
| fan-out spike | `~/Documents/handoff-docs/Claude/peerspeak/fanout-spike-results-2026-07-20.md` + Codex rounds 3/4 | **Option C adopted**, ratified |
| AEC identity gate | `~/Documents/handoff-docs/Claude/peerspeak/aec-playback-leg-identity-2026-07-20.md` | **🟢 gate passed**, both models agree after 2 adversarial rounds |
| **phase 5 dry-run gate (r8)** | `docs/screenshare-audio-exclusion-phase5-results.md` | **🚦 GATE FAILED** — the observation boundary is wrong (§6.7); architecture unaffected |
| **pre-Phase-6 closure (r11)** | `docs/screenshare-audio-exclusion-phase5-results.md` addendum | **PASSED** — same-device bridge, different-device negative control, and readiness calibration (§6.9) |

---

## 1. The problem

A sharer using whole-desktop audio sends their entire output mix to viewers. That mix
necessarily includes peerspeak's own playback — remote peers' voices, remote screen-share
audio — so viewers hear themselves.

`--strict-audio` solved this for *per-app* mode by refusing to mirror the desktop at all.
Whole-desktop mode has no equivalent, so a sharer today chooses between echo and sharing
exactly one app's audio. Joe's ask is the missing third option: **share the desktop,
minus peerspeak.**

## 2. Framing

PipeWire has no capture-side filter. A monitor port carries an already-summed signal;
once peerspeak's output is in that mix it cannot be subtracted out. What PipeWire does
provide is **graph topology**: a node's output ports may link to more than one consumer.

So the feature is built by constructing a sink that only *eligible* streams feed, and
capturing that sink's monitor. Same observable behaviour as a filter, entirely different
mechanism.

This is **not** echo cancellation. `src/audio/echo_cancel.rs` addresses the microphone
path, where coupling is acoustic and needs adaptive cancellation. Here the signals never
need to be summed at all.

**Fidelity is not claimed.** The *membership* of the constructed mix is exact — peerspeak's
audio is never summed in. The *delivered audio* is not lossless: pixelpass downmixes to
48 kHz stereo and AAC-encodes at 128 kbps (`pixelpass/src/host/pipeline.rs:303-324`).
Adding a second link also makes the source node participate in a second format/buffer
negotiation, which can perturb it even though the original link survives (§9.3).

## 3. What exists today

`setup_audio` (`pixelpass/src/host/pipeline.rs:123-142`) activates `Routing` **only** when
`--app` is set or `PIXELPASS_AUDIO_VIA_NULL_SINK` is set. peerspeak's no-app argv is
`--host --output json` (`peerspeak/src/screenshare/mod.rs:135-165`), so normal
whole-desktop capture **bypasses `Routing` entirely** and hands the real default monitor
to `pulsesrc`. This feature is therefore a genuinely new mode, not an inverted predicate.

`Routing::start` (`pixelpass/src/host/audio.rs:65-212`) today provides:

| Piece | Condition |
| --- | --- |
| `module-null-sink pixelpass_capture_<pid>` | always, when `Routing` runs at all |
| `module-loopback @DEFAULT_SINK@.monitor → capture` | skipped only when `--app` **and** `--strict-audio` |
| `StreamRouter` (libpipewire thread) | only when `opts.app` is `Some` |
| local-monitor `capture.monitor → @DEFAULT_SINK@` | on `FirstRoutedStream`, unloaded on `LastRoutedStreamGone` |

Under Option C the null sink is reused, the monitor loopback is never loaded in this
mode, the local monitor is not needed at all, and `StreamRouter` is replaced by a
link manager rather than extended. Two existing defects in that file are inherited and
must be dealt with as prerequisites (§10).

## 4. Architecture — Option C: copy, don't move

pixelpass creates a *second*, pixelpass-owned link from each eligible playback stream's
output ports to the capture sink, and leaves the stream's existing route untouched.

```
  app output ──────────────────────► existing hardware / filter path (UNTOUCHED)
       └── pixelpass-owned link ────► pixelpass_capture_<pid> ──► gst pulsesrc ──► viewers

  peerspeak-owned playback ────────► speakers only   (never linked to capture)
  AEC playback leg ────────────────► speakers only   (never linked to capture)
```

### 4.1 Why this beats the move-based design

| Problem under move (Option A) | Under copy |
| --- | --- |
| local-monitor loopback needed to keep the sharer hearing audio | not needed — audio never leaves the speakers |
| added playback latency for the sharer | gone |
| output-device switch mid-share strands the desktop | gone — the app's own route is never touched |
| prior `target.object` capture/restore | gone — nothing is retargeted |
| pavucontrol conflicts | gone |
| two concurrent hosts fight over `target.object` | gone — links are independent per host |
| SIGKILL strands the whole desktop on an orphan sink | gone — see §4.2 |

**The decisive measurement (spike E2): destroying the capture sink mid-share left the
application playing to its speakers undisturbed.** Capture-side failure degrades to "not
captured," never to "the user's audio is broken." That is Option C's entire case, and it
is the reason a broader eligibility predicate is now acceptable (§6).

### 4.2 Ownership of links is the safety mechanism

In the Rust `pipewire` crate, **dropping a `Link` proxy destroys the object.** So:

- Links are created **non-lingering** and their proxies are **retained** for the life of
  the share.
- Process death (including SIGKILL) destroys the connection, which destroys the links.
  Measured: non-lingering links die on SIGKILL of the owner.
- A stream is counted as captured only once **every** required link reaches `ACTIVE`.
- On any link failure: leave the original route alone, report the stream as unsupported.
  Never fall back to "capture the default monitor instead" — that fallback *is* the echo.

⚠️ **Rig gotchas that constrain how this is built and tested** (learned the hard way):
`pw-link --props object.linger=false` and `pw-cli create-link <props>` both **ignore**
linger and force it on; only `pw-link -m` yields a non-lingering link. `pw-cli
create-object` does not exist in 1.6.8 — the verb is `create-link <node> <port> <node>
<port>`. And links do **not** self-restore after a node or sink is recreated: a *live
owner* must re-link. That re-link loop is the pattern pixelpass has to implement, and
it is also what makes the daemon-restart case (§12) untested rather than free.

## 5. Ownership: identifying peerspeak's own audio

Every peerspeak-owned playback path is either a stream peerspeak itself creates, a
`Command::new(…)` spawn, or a pactl-loaded module. Three mechanisms cover all three.

### 5.1 Env-inherited tag, for spawned children — mechanism ✅ MEASURED, not yet built

⚠️ **This table lists IMPLEMENTATION SITES, not current behaviour.** None of these sites
tags anything today: `pipewire_impl.rs:374-388` sets no `peerspeak.owned` prop, and
neither the mpv/VLC spawn (`screenshare/mod.rs:768-775`) nor the notification spawn
(`notify.rs:265-272`) sets any env. The *mechanism* is measured working (below); the
*wiring* is work.

| Owner | Site | Mechanism to add |
| --- | --- | --- |
| native call playback | `src/audio/pipewire_impl.rs:374-388` | add the tag to the stream's property dict |
| mpv / VLC | `src/screenshare/mod.rs:768-775` | `.env("PULSE_PROP", …)` + `PIPEWIRE_PROPS` on the `Command` |
| `pw-play` / `paplay` / `aplay` | `src/notify.rs:265-272` | same |

Exact strings to be pinned at implementation time (§11), and each site needs a test:
native props asserted on the constructed dict, child sites asserted on the `Command` env.

Measured 2026-07-20 on this box (PipeWire 1.6.8): `peerspeak.owned=1` reached the graph
node for **paplay ✅, mpv ✅, VLC ✅**. `PULSE_PROP` and `PULSE_PROP_OVERRIDE` are both
present in `/usr/lib/pulseaudio/libpulsecommon-17.0.so`. (Codex asserted this mechanism
did not exist; it was disproved empirically. VLC has no native PipeWire aout on this box,
which is true and irrelevant — its Pulse path honours `PULSE_PROP`.)

**The tag is a correctness mechanism, not a security boundary.** Any same-user client can
set `peerspeak.owned=1` and opt itself out of capture, and a child can sanitize its own
environment. PipeWire is explicit that only `pipewire.*` properties are usable for
security decisions. Acceptable here: the threat model is "don't echo the user's own call
back at them," not "defend against a hostile local process." Stated, not assumed.

⚠️ **Known leak: a stable boolean is inherited by grandchildren.** Anything mpv or VLC
spawns is exempted too. Accepted for now; revisit if it bites.

⚠️ **Round 8 — the tag needs a SECOND, registry-visible carrier (user's call, 2026-07-25).**
`peerspeak.owned` is invisible to the registry `global` event (§6.7) and is readable only via
a node bind. That is safe — an unread tag means the node is withheld or the epoch fails
closed, i.e. silence, never echo — but it makes the primary taint root depend on the one
mechanism the round-8 finding proved fragile. So each tagging site sets **both**:

| carrier | visibility | role |
| --- | --- | --- |
| `peerspeak.owned=1` | bind only | primary root; keeps the measured `PULSE_PROP` env-inheritance mechanism for mpv/VLC/paplay |
| a pinned `node.name` prefix | **announced by the registry** | secondary root; fires with no bind at all |

The prefix mechanism is already proven in this codebase — `pixelpass_capture_*` is matched on
`node.name` and was the *only* root still functioning under the defect. Either carrier alone
marks a node owned (union, not intersection: fail-closed direction). `node.description` is
deliberately left untouched so volume mixers still read "mpv", not "peerspeak: mpv". The
literal is a cross-repo wire contract and is pinned in the implementation plan §3 alongside
the property literal.

### 5.2 The AEC playback leg — 🟢 gate passed, with five load-bearing corrections

`module-echo-cancel` is loaded via pactl (`peerspeak/src/audio/echo_cancel.rs:83-94`), so
its playback leg lives inside `pipewire-pulse` and **cannot inherit an env tag.** It is a
`Stream/Output/Audio` node linked straight to the speakers, so a broad selector *will*
pick it up unless explicitly excluded — and that is not a nicety:

> **Measured (3 arms, links verified in-graph before measuring, recorded via
> `parec -d <sink>.monitor` — the production path):** naive fan-out that includes the AEC
> leg copies remote-call audio into the share at **≈desktop level** (−45.0 dB vs the
> −44.5 dB desktop tone). Exact exclusion produces **−83.3 dB, matching the control floor
> to 0.1 dB.**

**What `module-echo-cancel` actually creates (RESULT 1):** four nodes, not two —
`Audio/Sink peerspeak_ec_sink.<pid>`, `Audio/Source peerspeak_ec_source.<pid>`,
`Stream/Output/Audio **echo-cancel-playback**` (passive, virtual), and
`Stream/Input/Audio echo-cancel-capture`. Codex's "Pulse-compat exposes only
`sink_properties`" concern is real about the *module args* and irrelevant to the *graph
props*.

**The identity (RESULT 2):** all four nodes carry `pulse.module.id` equal, byte for byte,
to the module index `pactl load-module` returned — the value peerspeak already stores in
`EchoCancelGuard::module_index` (`echo_cancel.rs:106-112`, a `String` validated as `u64`).
No PID guesswork, no name matching, no leg correlation.

```
exclude every node where pulse.module.id == <the index pactl returned to the live guard>
```

**⚠️ The five corrections. These are the design, not footnotes:**

1. **This is not an "identity contract."** It is an exact correlation *observed on
   PipeWire 1.6.8*, not a documented API. No PipeWire source is installed on this box and
   neither model had network, so whether the property is the *mechanism* pipewire-pulse
   uses to reap module-created objects or a cosmetic mirror is **UNRESOLVED**.
   ⇒ **Runtime-validate and fail closed** (§5.3).
2. **"Has any `pulse.module.id`" is REJECTED as an exclusion rule.** Tunnel, RTP and
   loopback modules may be the *only* carrier of audio the user legitimately wants
   shared. **Exact equality with the owned live index — nothing weaker.**
3. **Module index and `node.link-group` are REUSED verbatim across unload/reload** (both
   came back `536870919` / `echo-cancel-1974-13`), and **node IDs are recycled *and
   reassigned across legs*** — id 136 was the playback leg on load 1 and the capture leg
   on load 2. ⇒ **Never cache a node id. Never assume leg order. Never cache the module
   index across an unload** — it is only trustworthy as "the index for the currently-live
   guard," so pixelpass must be (re)told on every load.
4. **The `echo-cancel-` group prefix is hazard *detection*, not ownership.** Neither it
   nor the fixed node name `echo-cancel-playback` identifies *peerspeak's* instance. A
   foreign or second AEC is a product-policy question (§5.4). The better long-term answer
   is the **native** PipeWire AEC module, which exposes `playback.props` and would let us
   stamp our own random token directly on the playback leg.
5. **PID — the whole muddle, finally resolved** (third measurement, 2026-07-21, settles
   four rounds of contradictory claims). Two *different properties on two different
   object types* were being conflated:

   | property | lives on | value for Pulse-emulated clients |
   | --- | --- | --- |
   | `application.process.id` | the **Node** | the app's **own** PID (Firefox `11114`, paplay's own) |
   | `pipewire.sec.pid` | the **Client** | **pipewire-pulse's** PID — `2541` for *every* Pulse client on this box (Firefox, Steam, KDE Connect, libcanberra all identical) |

   Module-created streams (the AEC) are the exception on the *node* side: their
   `application.process.id` is pipewire-pulse's (`1974` at the time of that run), because
   pipewire-pulse genuinely is the client. Earlier notes claiming `pipewire.sec.pid` was
   "absent on these nodes" were right — it is absent from **nodes** because it is a
   **Client** property. **PID-based AEC exclusion stays unusable**; PID is a fallback
   hint, never identity. `client.id` — *not* PID — is the usable per-app correlation key
   (§6.1 edge type 3).

Parse defensively: `pulse.module.id` renders as a JSON **number** in `pw-dump` but SPA
props are strings. `536870919 = 0x20000007`; pipewire-pulse indices start at `0x20000000`
so they fit u32 — but this sits right next to the `object.serial` u32-truncation bug
(§10.1), so compare as strings or as `u64`, never as `u32`.

### 5.3 Fail closed — validation and revocation

Because the identity is an observed correlation rather than a contract, pixelpass must
**verify it at runtime and refuse to run the mode when it cannot.** A one-shot
"enumerate at start" check is *not* good enough — it races, in both directions:

- peerspeak's `enable()` returns once `wait_for_nodes` sees the virtual **source and
  sink** by name (`echo_cancel.rs:132-158`, polling `pactl list sources/sinks short`).
  It does **not** wait for the playback `Stream/Output/Audio` hazard leg, which is the
  node we actually need to exclude.
- pixelpass's capture spawns **lazily, on first viewer** (`pixelpass/src/host/mod.rs:300-304`),
  so enumeration happens at a moment peerspeak does not control, and a refusal surfaces
  *after* the ticket has been handed out.

**So validation is a bounded state machine, not a check:**

```
NotConfigured  ──(--aec=off)──────────────► fan-out proceeds, no AEC exclusion
Validating     ──(--aec=pulse-module:<i>)─► enumerate after a registry sync barrier;
                                            wait up to a bounded deadline for ≥1 node
                                            with pulse.module.id == i
Validated      ──► fan-out permitted, excluding that identity transitively (§6.1)
Failed         ──► deadline expired, identity never observed  ⇒ NO FAN-OUT
Revoked        ──► the live module identity disappeared        ⇒ STOP FAN-OUT NOW
```

- **No fan-out occurs in `Validating`.** Silence is the safe direction; echo is not.
- **`Failed` is fail-closed**: report a capability failure, do not silently share.
  Fall back to a mode with no echo risk, or an explicit user override.
- **Revocation is loss of the live *module* identity** — *all* nodes bearing the index
  gone — not the transient absence of one playback leg, which can cork or relink. Getting
  this wrong turns a normal cork into a spurious share-wide audio stop.
- On `Revoked`, **drop the link proxies**; do not keep the numeric index and hope. The
  index is reused (§5.2 correction 3), so a retained stale index can alias onto an
  unrelated future module.
- **Never** infer exclusion from `node.name == "echo-cancel-playback"` alone — it is a
  fixed, non-unique, trivially spoofable string. Usable only as belt-and-braces *after*
  the exact match, or as foreign-instance hazard detection.

### 5.4 Foreign or second AEC instances — a product decision

If a node matching `node.link-group` prefix `echo-cancel-` exists that is **not** ours,
peerspeak is not the only echo canceller on the box. Options: (a) fail closed — refuse
the mode; (b) warn and exclude all `echo-cancel-*` groups, accepting that a legitimate
unrelated AEC's output silently won't be shared. **Recommendation: (b) with a visible
warning** — the failure it prevents (echo) is worse than the failure it causes (one
app's audio missing), and it matches §6's overall posture. **Open decision D3 (§13).**

## 6. Eligibility — a broad guarded selector

Under a *move* design, mis-selection rewired the user's desktop, which forced a narrow
allowlist. Under copy, mis-selection costs at most one stream's capture — so the narrow
allowlist is out. But "fan out everything" is still wrong: it recreates self-echo, it
recreates call echo, it can build cycles, and a second link participates in format/buffer
negotiation.

### 6.1 ⚠️ Eligibility is a GRAPH property, not a node property

**This is the single biggest correction in round 4, and it is reachable on the target
machine, not hypothetical.**

A node-local property check is unsound, because **exclusion does not propagate downstream.**
If any node re-emits audio it received, the re-emitting node is a fresh, *untagged*
`Stream/Output/Audio` carrying the mix — including peerspeak's playback and the AEC leg,
both of which were correctly excluded one hop earlier.

### 6.1.0 The hazard is REACHABLE on this machine — it was live when measured

⚠️ **Round-8 correction to this heading, and it is the point of the correction.** v3.4 said
"🔴 LIVE on this machine **right now**." That was true at 2026-07-21 ~09:00 and **false by
~14:55 the same day** — six hours later the default sink was
`alsa_output.pci-0000_10_00.6.analog-stereo` (IDLE), all three `sink-sunshine-*` null sinks
SUSPENDED, with Sunshine still running the whole time. So the topology appears when
**Sunshine actually routes desktop audio through its null-sink chain**, which is strictly
narrower than "Sunshine is running."

**Nothing may gate on this topology being present.** The reachability argument below is
unaffected and stands: a stock third-party application puts a virtual-sink forwarder in the
default audio path on an ordinary desktop, no EasyEffects required. But as a *test* input it
is opportunistic only — the controlled `module-null-sink` + `module-loopback` fixture is the
authoritative one because it is deterministic and always available.

Measured 2026-07-21 ~09:00. **The user's default sink was not hardware.** `pactl info`
reported:

```
Default Sink: sink-sunshine-stereo        ← factory.name = support.null-audio-sink
```

All three real hardware sinks (`Arctis_1_Wireless`, `pci-…analog-stereo`,
`…hdmi-stereo-extra3`) are **SUSPENDED**; the only `RUNNING` sink is Sunshine's virtual
one. The live graph is:

```
Firefox:output_{FL,FR} ──► sink-sunshine-stereo:playback_{FL,FR}   (a null sink)
                           sink-sunshine-stereo:monitor_{FL,FR} ──► sunshine:input_{FL,FR}
```

That is **exactly the forwarder shape** this section is about, active in the default audio
path, with no EasyEffects involved. Consequences:

1. **Reachability is settled.** Earlier rounds argued from "EasyEffects is installed";
   the real machine is already running a virtual-sink forwarder topology full time.
   peerspeak's own playback would land in `sink-sunshine-stereo` and its monitor.
2. **§6.5's "hardware-sink-only" shortcut wouldn't just leak — it would capture
   NOTHING here**, because no application links to a hardware sink at all.
3. Sunshine happens to have **only** a `Stream/Input/Audio` leg (id 168) — it encodes and
   sends over the network rather than re-emitting locally — so it is not itself a fan-out
   leak source. The topology, not this particular app, is the point.
4. §10 item 2 (`@DEFAULT_SINK@` resolved once) is worse than described: the default sink
   here is a *transient app-owned null sink* that appears and disappears with Sunshine.

**Separate item this raised for peerspeak itself — RESOLVED for this machine, kept as a
low-priority general defect** (not part of this feature): `echo_cancel::enable` appends
`sink_master=` / `source_master=` only when the configured device is `Some` and non-empty
(`echo_cancel.rs:89-94`); otherwise `module-echo-cancel` binds to whatever PipeWire calls
the default. On a box where an application owns the default sink — as Sunshine does here —
that means the AEC would bind to a null sink.

✅ **Not live for this user:** `~/.config/peerspeak/config.json` pins
`output_device = alsa_output.usb-SteelSeries_…Arctis_1_Wireless-00.analog-stereo` and
`input_device = …mono-fallback`, so `sink_master` is always passed explicitly and the AEC
binds to the Arctis regardless of the default. The exposure exists only for a user on
"system default". Possible hardening (own task, not this feature): resolve and validate
the default sink before load, and refuse or warn when it is a null/virtual sink.

The canonical *installed* instance: **EasyEffects.** When it is running, applications play into
`ee_sink` and EasyEffects emits a single combined output stream to the hardware. That
output leg has no `peerspeak.owned` tag and no `pulse.module.id` matching our AEC, so
**both §5.1 and §5.2 pass it**, and fanning it out re-injects the entire call into the
share at full level — the exact bug this feature exists to prevent, arriving through the
front door. ⚠️ **`easyeffects` is installed on this machine** (`pacman -Qq easyeffects`),
and `libpipewire-module-filter-chain.so` is present. It happened not to be running during
the spike, which is *why* the spike did not catch this. Same shape: combine-sinks,
`module-loopback`, virtual-sink forwarders, tunnel/RTP sinks, DSP bridges, and any
monitor-sourced stream.

**So the predicate is transitive TAINT over the live SIGNAL graph** — and "signal graph"
is doing real work in that sentence, because it is **not** the graph of `Link` objects.

> A node is eligible only if **no** signal path reaches it from a peerspeak-owned node,
> the live AEC identity, or any pixelpass-owned object (ours *or* another host's
> `pixelpass_capture_*`). Unresolvable ancestry is **not** eligible.

⚠️ **A Link-only walk does NOT catch the leak.** Measured on the live graph 2026-07-21
by reproducing the forwarder topology with `module-null-sink` + `module-loopback`
(same shape as EasyEffects, no EasyEffects required):

```
  fabletest_sink:monitor_FL ──Link 87──►  input.loopback-2541-13   (Stream/Input/Audio,  id 109)
                                                    ⋮  ← NO LINK OBJECT EXISTS HERE
  output.loopback-2541-13   ──Link 105─►  alsa_output…analog-stereo (id 56)
   (Stream/Output/Audio, id 86)
```

**There is no `Link` between the forwarder's input leg (109) and its output leg (86).**
Walking upstream from the leaking node 86 over Links alone finds *no inbound links at
all* — a dead end that reads as "clean," and the node gets fanned out. The two legs are
related only by shared properties:

| key | input leg (109) | output leg (86) |
| --- | --- | --- |
| `node.link-group` | `loopback-2541-13` | `loopback-2541-13` |
| `client.id` | `107` | `107` |
| `pulse.module.id` | `536870917` | `536870917` |

So the signal graph needs **three** edge types:

1. **Link edges** — `link.output.node → link.input.node`. ✅ Measured: registry Link
   objects carry all four endpoint props (`link.output.node`, `link.output.port`,
   `link.input.node`, `link.input.port`).
2. **Sink-monitor edges** — ✅ **free at node granularity.** Measured: the monitor
   connection *is* a real `Link` whose output node is the sink node itself
   (`out-node=104 (fabletest_sink) → in-node=109`). So a node-level walk crosses
   `app → sink → monitor-reader` with no synthetic edge. A **port**-granular walk *does*
   need an explicit rule (inputs feed `port.monitor=true` outputs); a node-granular one
   does not. **Use node granularity for taint; use ports only for link creation.**
   ⚠️ **Accepted cost — duplex over-taint.** Node granularity smears taint across
   multi-role nodes: an `Audio/Duplex` node whose playback side is tainted will have its
   capture side treated as tainted too. That is **fail-closed** (over-exclusion, not a
   leak) and is accepted for v1, but it can contradict the "Firefox with a microphone
   stays shareable" promise in §6.1.1 on a duplex device. Port-modelling `Audio/Duplex`
   and unknown-role nodes is the fix if this bites in field testing.
3. **Owner-bridge edges** — the intra-process hop the graph cannot see. This one is
   genuinely hard; see §6.1.2. A single key does **not** work.

### 6.1.2 ⚠️ The owner bridge — no single key works (measured refutation)

**I claimed `client.id` was the fallback bridge key for apps without a `link-group`.
I disproved my own claim; Codex independently reached the same verdict.**

Test: one `gst-launch-1.0 pulsesrc device=fable_src.monitor ! audioconvert ! pulsesink
device=fable_dst` process — one PID, an input leg and an output leg, the exact
OBS/recorder/forwarder shape, and the same framework pixelpass itself uses.

| leg | `client.id` | `node.link-group` | `application.process.id` |
| --- | --- | --- | --- |
| `Stream/Input/Audio` | **209** | null | 20172 |
| `Stream/Output/Audio` | **210** | null | 20172 |

**Two distinct client objects for one process**, both named `gst-launch-1.0`, both with
`pipewire.sec.pid=2541`. So `client.id` bridges *a client connection*, not *an owner* —
an app is free to open one connection per stream, and GStreamer does exactly that. The
earlier "libcanberra appears as clients 74 and 77" observation was the same signal and I
under-weighted it.

**Replacement: a conservative union of owner keys, strongest first.**

⚠️ **Wording trap — "resolves" means "yields a MATCH between the two legs," NOT "is the
first property present on the node."** A naive first-present implementation reproduces the
exact bug: in the gst-launch case `client.id` **is present on both legs** (209 and 210), so
first-present stops at key 3, finds the values differ, and concludes "different owners —
not bridged." The leak survives. The rule is: *try each key in order; a key resolves only
if both legs carry it and the values are equal; otherwise fall through to the next key.*
This must be an explicit unit test (§12).

| # | key | scope | notes |
| --- | --- | --- | --- |
| 1 | `node.link-group` | per module/filter instance | precise; set by PipeWire modules (loopback, echo-cancel, filter-chain) |
| 2 | `pulse.module.id` | per pactl module | precise; module-created streams only |
| 3 | `client.id` | per **connection** | correct when an app uses one connection; insufficient alone |
| 4 | `application.process.id` (on the **Node**) | per process | ✅ the only key that bridged the gst-launch legs (`20172` on both) |
| — | else | — | **unresolved ⇒ fail closed** (exclude the output leg) |

⚠️ **Key 4 has a trap that must be coded explicitly.** For *module-created* streams,
`application.process.id` is **pipewire-pulse's own PID** (§5.2 correction 5). Bridging on
it would fuse *every* Pulse module's legs into one owner, so a single tainted module input
would exclude every module-created stream on the box — mass over-exclusion, and exactly
the failure correction 2 warned about (a tunnel/RTP module may be the sole carrier of
audio the user wants shared). **So: never bridge on key 4 when the value equals the
pipewire-pulse PID.** Those cases are already covered precisely by keys 1 and 2.

Note the irony worth recording: PID returns to the design, but in a different *role*.
It is unusable as **identity** ("is this peerspeak's audio?") and workable as
**correlation** ("are these two legs the same app?") — and in the correlation role a
wrong answer fails closed rather than leaking.

**How pixelpass learns the pipewire-pulse PID** (needed for the key-4 exception). It must
derive this itself; it cannot assume a value, and peerspeak can supply only a *hint*:

- Read `pipewire.sec.pid` from the **Client** objects of Pulse-emulated streams. Measured:
  it is `2541` for Firefox, Steam, KDE Connect, sunshine and libcanberra alike, while each
  node's own `application.process.id` differs (Firefox `11114`, sunshine `4119`).
- ~~Require a **single consistent** value across those clients~~ and validate it by reading
  `/proc/<pid>/comm` (or cmdline) and confirming it is `pipewire-pulse`.
- "This PID owns implausibly many unrelated streams" is a **diagnostic**, never
  correctness logic.

> #### 🔴 Round 10 (MEASURED, phase-5 run 2): "a repeated `sec_pid`" does not identify pulse
>
> The struck rule above was implemented as *the single `sec_pid` shared by two or more
> Clients*, on the reasoning that native clients each carry their own distinct PID so only the
> Pulse shim repeats a value. **Measured on this host: WirePlumber repeats one too** — it holds
> two Clients, `WirePlumber` and `WirePlumber [export]`, both `sec_pid` 1747. Two values
> repeated, "single consistent" was unsatisfiable, and the derivation returned `None`
> **permanently, on a stock desktop**.
>
> The consequence was not a missing optimisation. With the daemon PID unknown the key-4
> exception never fires, every Pulse-emulated node fuses into one owner, and the result is the
> machine-wide over-exclusion cascade of phase 5's F2 — reached again from a new cause, and
> caught again only by the §5.1 requirement to assert the **eligible** half of a row.
>
> The rule failed in both directions, so the repetition test is **deleted** rather than
> tightened:
>
> - **False ambiguity** — any second process holding two Clients defeats it, and WirePlumber
>   always does.
> - **False absence** — a session in which pipewire-pulse holds exactly one Client (one Pulse
>   app running) repeats nothing at all, so the candidate is never even considered.
>
> `comm` was always the authoritative check; repetition was a heuristic standing in front of it,
> and what it actually encoded was an assumption about *other* processes' Client counts.
> **The rule is now: every distinct `pipewire.sec.pid` is a candidate; the daemon is the unique
> one whose `/proc/<pid>/comm` is exactly `pipewire-pulse`.** Zero matches ⇒ `None` (nothing we
> can prove to suppress). **Several** matches ⇒ also `None`: two live pipewire-pulse daemons (a
> nested or sandboxed session) cannot both be suppressed by a single `Option<u32>`, and failing
> closed there lands on the over-exclusion side, consistent with the failure-mode paragraph
> below. Suppressing a *set* of daemon PIDs is the real answer if a multi-daemon host ever turns
> up; it is out of v1 and recorded rather than silently approximated.
>
> The lesson generalises past this key: **a property of the objects we are trying to identify is
> evidence; a property of everyone else's object count is a guess.** The `/proc` read was already
> there and already authoritative — the heuristic in front of it only added a way to be wrong.

Failure modes: if pixelpass fails to identify the real pipewire-pulse PID, the result is
broad **over-exclusion** (annoying, safe). If it wrongly suppresses a genuine app PID, the
result is over-exclusion **for that app** — safe *only* because unresolved ancestry is
fail-closed. If unresolved ancestry were ever implemented fail-open, both of these become
leaks. That is the invariant holding this whole section up.

### 6.1.1 ⚠️ Bridge taint must be conditional, or it over-excludes badly

The owner bridge must propagate taint **only when the input leg is itself tainted.**
The naive rule "this client has both an input and an output leg ⇒ exclude the output" is
catastrophic: it excludes any app using a microphone. Firefox in a video call has both
legs, and its playback is perfectly shareable.

The correct rule:

1. Taint roots: peerspeak-owned nodes, live AEC identity, pixelpass-owned objects.
2. Taint flows downstream along Link edges (crossing sinks and monitors for free, §6.1
   edge type 2). A sink carrying tainted audio has a **tainted monitor**.
3. A `Stream/Input/Audio` reading a tainted monitor becomes tainted.
4. **Only then** does the owner bridge carry taint to that client's `Stream/Output/Audio`
   legs.

Result, both cases correct:

| scenario | outcome |
| --- | --- |
| Firefox playing music (output leg only) | **eligible** — shared |
| Firefox in a Meet call (mic input leg, untainted source) | **eligible** — shared |
| Firefox screen-sharing *with desktop audio* (input leg on a tainted monitor) | **excluded** |
| EasyEffects / loopback / combine-sink forwarding a mix containing peerspeak | **excluded** |

Where an owner has a tainted input leg and an output leg with **no** resolvable bridge
(§6.1.2), fail closed and exclude the output leg. This only ever engages for owners
actually reading a tainted monitor, so the blast radius is small.

> **⚠️ Round 13 (F11-1) — "bounded" is not "has a key". A self-claimed pid is not
> provenance.** Which legs this backstop sweeps depends on whether the tainted reader and
> the candidate outputs are *bounded* — i.e. whether we could enumerate their sibling legs
> and be right. Key 4 is a union of the node's `application.process.id` (client-controlled,
> optional) and its Client's `pipewire.sec.pid` (protected), so a node could bound itself
> with a value it invented and escape the sweep while its real sibling was unfindable.
>
> **Rule:** a strong key (`node.link-group`, `pulse.module.id`) bounds an owner on its own;
> key 4 bounds an owner **only when the node's Client resolves** — an unambiguous Client
> yielding `Some(pipewire.sec.pid)`, read *before* pipewire-pulse suppression. The
> ordering is load-bearing in both directions: read after suppression and every
> Pulse-emulated app on the box goes unbounded (§6.1.1 catastrophe, new door); accept "a
> unique Client object exists" instead of a `sec_pid` and a pid-less Client leaves the hole
> open.
>
> **Bridging is unchanged** — it still uses the full union, because a self-claimed pid is
> perfectly good *evidence that two legs are related*, which is the taint-increasing
> direction. Only the permission to declare a differently-keyed output "provably someone
> else" now demands a `pipewire.*` answer to "who is this".
>
> Measured cost on this host: **zero** — before/after binaries audited the same live graph
> simultaneously, same 14 decision states, no `unresolved-owner` on either side, eligible
> half non-empty. Implemented in pixelpass `c78eb2d`; five-case Client matrix in the tests.

### 6.1.3 ⚠️ Taint must be STICKY — current topology is not enough

**Conceded to Codex in round 6; my "conditional bridge" was correct about topology and
wrong about time.** Taint computed from the *current* graph forgets **buffered audio**.

Failure: an app reads a tainted monitor, buffers or delays (a recorder with a 5 s ring
buffer, a DAW with latency compensation, anything doing lookahead), and then its input leg
untaints or disappears — the user stops sharing to it, the stream corks, the app closes
the capture. A purely topological recompute now sees a clean input, un-taints the owner,
and pixelpass **relinks the output leg while it is still emitting peerspeak audio from
the buffer.** No graph event marks the moment the buffer drains.

**Rule: taint is sticky per owner for the duration of the share.** Once an owner is
tainted it stays tainted until its client/output nodes disappear. Re-eligibility requires
teardown, not a topology change. A timed drain is strictly weaker and would need
measurement to justify; do not ship one in v1.

⚠️ **Stickiness must be lifetime-aware, never keyed on a raw recyclable id.** `client.id`,
node ids, module indices, `node.link-group` values and PIDs **all recycle on this stack** —
measured directly for module indices and node ids (§5.2 correction 3), and the same
`link-group` string came back verbatim across an unload/reload. If sticky taint were stored
against a bare key, a later unrelated app inheriting that recycled id would inherit the
taint and be silently excluded forever.

Store stickiness against a **live owner component** — the concrete set of node/client
objects observed to form that owner — and clear it only once **all** member objects have
disappeared. A key that reappears after full teardown is a new owner and starts clean.

The cost is that an app which *once* read a tainted monitor stays unshared for the rest of
the share. That is the right trade — it is silence for one app, versus echo for everyone.

### 6.1.4 The transition window is real but bounded

Taint can also *arrive*: a peer joins and speaks, or the AEC loads, mid-share. Recompute
on every graph event and dropping links for newly tainted nodes is **necessary but not
zero-leak**, because a topology change races audio already in flight.

Order of magnitude on this box: a graph quantum is ~`512/48000`–`1024/48000` ⇒ **≈10.6–21.3
ms**, plus main-loop scheduling. App-internal buffers are unbounded in principle. So the
worst case is a sub-quantum-to-tens-of-ms audible sliver at the transition.

⚠️ Mitigating structure: if peerspeak's playback **roots already exist** in the graph and
merely become non-silent (the common case — the AEC and call playback nodes are created at
join, long before anyone speaks), then topological taint has **already** excluded
everything downstream and there is no window at all. The window exists only when a taint
root is *newly created* mid-share.

⚠️ **Round-8 correction: v3.4 nominated an unreachable test case here** ("that makes
AEC-load-mid-share the case to test"), **and so did its first replacement.** The conclusion
above is unaffected; only the example was wrong.

- *AEC-load-mid-share is unreachable.* There is exactly one `echo_cancel::enable` site, at
  session join (`core/mod.rs:1850`); the guard moves into `ActiveSession` (`:2729`); and
  `StartScreenShare` rejects `active_session == None` (`:3397-3404`). The AEC always
  predates the share.
- *"A peer joins and their playback node is created" is also unreachable.* peerspeak starts
  **one mixed playback stream** at session construction (`core/mod.rs:1900`); `PeerJoined`
  (`:2396-2409`) admits and connects the sender and creates no per-peer node.

**The reachable newly-created mid-share taint roots are: a notification sound played
mid-share** (`notify.rs:265-272`) **and starting to view another share mid-share**, which
spawns a tagged mpv/VLC (`screenshare/mod.rs:768-775`). Those are the transition-window
field tests. Owned-AEC mid-share load stays a **synthetic** test until a second `enable`
site or a hot reload arms it.

This means pixelpass must **track Node, Port and Link globals** — not just node
global-add, which is all the existing router does (`pixelpass/src/host/audio.rs:523-584`
subscribes to global-add/global-remove and never binds links). That is a materially
larger component than v3.0 implied.

Ancestry that cannot be resolved (unknown forwarder shape, unresolvable monitor source)
is **not** eligible. That is a deliberate reversal of v3.0's "unrecognized ⇒ fan out":
E2 makes mis-selection cheap *for the user's audio graph*, but it is not cheap for
**echo**, and echo is the whole feature.

### 6.2 The predicate

**Start from all `Stream/Output/Audio` nodes, then exclude:**

| Exclusion | Basis |
| --- | --- |
| `peerspeak.owned` present | §5.1 env tag |
| `pulse.module.id` == the live AEC index | §5.2, exact equality only |
| **tainted via the signal graph** (Link + monitor + conditional owner bridge) | §6.1 — the load-bearing one |
| pixelpass-owned objects, incl. **other hosts'** `pixelpass_capture_*` ancestry | cycle prevention |
| tainted input leg + output leg with no resolvable bridge | §6.1.1, fail closed |
| `port.exclusive` ports, encoded/passthrough streams | fan-out will refuse or corrupt |
| links we already own for that node | idempotence |

- `node.dont-move` **drops out entirely** — fan-out is not a metadata move.
- Links are created **per port**; channel-count and layout mismatches are per-port.

### 6.3 Dynamic graph handling — revalidate, don't fire-and-forget

A node can appear with incomplete ancestry, pass the predicate, get fanned out, and only
*then* receive an inbound link from a filter input or `pixelpass_capture_<pid>.monitor`.
An add-only listener never sees it. Required:

1. An **initial registry sync barrier** — register the listener, call `Core::sync()`, wait
   for `done`, and only then consider the initial pass complete.
   ⚠️ **Know what this barrier is and is not.** PipeWire's `core.h:261` defines sync as a
   *previous-work roundtrip*: because methods and events are ordered, `done` means
   "everything emitted so far has been handled." It is **not** graph quiescence and does
   not promise the graph has stopped changing. Readiness therefore = `done` **plus** "no
   unresolved required Link/Port observations outstanding," with a fail-closed timeout.
2. Candidates stay **pending** until their ports *and* current inbound links are known.
3. **Revalidate immediately before creating each Link**, not just at selection time.
4. On any later link add/remove that makes ancestry unsafe, **drop the owned link
   proxies** for the affected node — retention (§4.2) is what makes revocation possible.

### 6.4 Implementation shape and cost

`pipewire` crate **0.9.2** (`pixelpass/Cargo.toml:48`, `Cargo.lock:4121`).

- **Endpoint props are an OPTIMIZATION, not the correctness path** (settled in round 6).
  Registry `Link` globals carry all four endpoint keys
  (`/usr/include/pipewire-0.3/pipewire/keys.h:256`) and they were observed present on
  every live Link — but the observation was via `pw-dump`, which binds objects, and
  neither the headers nor the crate prove those keys are *always* present in the
  **global-add** props. So: use them when present, and **rely on the bind fallback for
  correctness.** A raw global-add log in the implementation spike settles current
  behaviour, but the fallback must exist regardless.
- **Fallback:** bind that Link, install an info listener, read the endpoint ids off
  `LinkInfoRef` (`pipewire-0.9.2/src/link.rs:153` exposes all four without params), then
  **drop the observer proxy**. Retained proxies are needed only for *our own* fan-out
  links, where dropping is the ownership/lifecycle mechanism (§4.2) — not for external
  links we merely observe.
  ⚠️ **Round 8: measured, the Link endpoint props are always present** — this fallback is
  correctness insurance that never fires on this host. The bullet above it is still right;
  it was just under-applied. See **§6.7**.
- 🔴 **Node and Device props are NOT AVAILABLE from the global at all** — not an
  optimisation, not usually-present, never. Binding each Node and Device is the **only**
  path to `peerspeak.owned`, `pulse.module.id`, `node.link-group`,
  `application.process.id`, `node.passthrough`, `factory.name`, `device.api` and
  `alsa.driver_name`. **§6.7** is the whole story; it is the round-8 finding and it
  supersedes any reading of this section that treats node props as observable off the
  registry.
- **Readiness epoch.** Start fan-out only when: initial `core.sync`/`done` received **and**
  every required Link/Port/Client/Node observer fallback has resolved or hit a fail-closed
  timeout. Then **revalidate in the same graph epoch immediately before creating each
  owned link** — a stale decision from a previous epoch is not a decision.
- **Full recompute per graph event is fine for v1.** Rebuild taint by BFS/DFS from the
  hazard roots, O(V+E). A typical desktop graph is ~40 nodes / ~120 links; this is
  sub-millisecond-class in Rust. No incremental dirty-set in v1; coalesce bursts only if
  logs show churn.

### 6.5 Rejected: the "hardware-sink-only" shortcut

Considered and **rejected**: "fan out only nodes whose output links to a real hardware
sink, excluding anything feeding a virtual/null sink." It is cheaper and it is **unsound
for exactly the case that matters** — measured: `output.loopback-2541-13` links *directly*
to `alsa_output.pci-0000_10_00.6.analog-stereo`. The forwarder's output leg **is** a
hardware-linked node, so the shortcut passes it and leaks the mix. The original app stream
would meanwhile be excluded for feeding the virtual sink — i.e. the shortcut gets both
halves backwards.

It survives only as an optional degraded fallback mode whose stated behaviour is "no
EasyEffects/filter/loopback-routed audio is captured at all."

### 6.6 Foreign/hazard nodes

Treat an unvalidated `echo-cancel-*` output node as an excluded hazard rather than an
eligible stream (§5.4).

### 6.7 🔴 The observation boundary — registry props are a FILTERED SUBSET (round 8, MEASURED)

**This is the finding that failed the phase-5 gate**, and it is the one place v3.4 was
materially wrong. Full evidence: `docs/screenshare-audio-exclusion-phase5-results.md` (F1).

**The fact.** The registry `global` event does **not** carry an object's properties. It
carries a small fixed subset the daemon copies onto the global. Measured on PipeWire 1.6.8 /
WirePlumber 0.5.15, the complete union of keys announced for a `Node` global across every
node on the box is:

```
application.name  client.api  client.id  device.id  factory.id  media.class
node.description  node.name   node.nick  object.path  object.serial
priority.driver   priority.session
```

Eight properties this design depends on are **never** announced, and a props lookup for them
returns absent rather than failing — so an implementation reading them off the global is
silently, permanently wrong:

| property | what dies without it |
| --- | --- |
| `peerspeak.owned` | **the primary taint root** — §5.1, all of phase 1 |
| `pulse.module.id` | **AEC identity exclusion** — §5.2 and the §5.3 validator |
| `node.link-group` | owner key 1 — echo-cancel, EasyEffects, loopback siblings (§6.1.2) |
| `application.process.id` | owner key 4 — the measured GStreamer split-client case (§6.1.2) |
| `node.passthrough` | the passthrough exclusion (§6.2) |
| `device.api` | `session_device` classification |
| `factory.name` | `session_device` classification — the discriminator itself |
| `alsa.driver_name` | `session_device` classification — the `snd_aloop` denylist |

`port.exclusive` is likewise absent from `Port` globals, so that §6.2 exclusion never fires.
**Links and Clients are unaffected** — every endpoint key and `pipewire.sec.pid` is announced,
so §6.1.2's pulse-PID derivation works as designed.

The consequence measured live was not degradation but inversion: with `peerspeak.owned`
invisible the tagged sink is **not a taint root at all** (an echo, with AEC off), while the
one root that still fires — the `pixelpass_capture_*` name prefix, `node.name` being
announced — leaves every candidate with no *strong* owner key, which trips §6.1.1's
fail-closed backstop and excludes every stream on the machine. Both halves broken, in
opposite directions, from one cause.

**The rule (round 8).**

> **A node's properties come from a bind, never from the global.** The registry global is an
> *index* — it tells us an object exists, its id, its serial, its media class and its name —
> and nothing it says about ownership, grouping or hardware identity may be trusted or even
> read. Every `Node` global is bound and its `info` props are the sole source of node
> properties. Same for `Device`.

Verified recoverable by bind on the same objects that lack them from the registry:
`factory.name = api.alsa.pcm.sink`, `device.api = alsa`, `alsa.driver_name = snd_usb_audio`,
`peerspeak.owned = true`, `pulse.module.id`, `node.link-group = loopback-2528-13`,
`application.process.id`.

Four decisions fix the shape (user's calls, 2026-07-25):

1. **Bind every `Node` global, unconditionally** — no filtering by `media.class`. Deciding
   which nodes matter *before* their props exist is the same class of mistake as reading the
   props off the global, and a node skipped for looking irrelevant has no owner keys, which
   is exactly the unbounded-reader condition that produced the machine-wide cascade. Cost is
   ~14 nodes at rest on this box.
2. **Track prop changes for the node's lifetime.** `info` fires again with `PROPS` set in
   `change_mask`; re-read, re-classify, re-emit. A one-shot read (the Link-fallback pattern)
   would miss a `node.link-group` or `pulse.module.id` set after node creation. Measured
   cheap: one change event in 8 s at rest.
3. **One readiness obligation per unbound node**, and a node with no `info` yet is **withheld
   from the snapshot entirely** — never admitted with provisional ownership (the §6.1.3 rule,
   already applied to device-unresolved nodes). If a bind never resolves, readiness goes
   sticky-`TimedOut` and there is no fan-out at all: identical to a never-resolving Link
   bind, one rule for both. ⚠️ *Owed hardening:* per-node quarantine (that node ineligible
   **and** taint-bearing, the rest of the graph still working) is strictly better and is
   deferred because it is a new concept in the pure engine, not a fix to the observer.
4. **`session_device` reads from both.** `factory.name` exists only on the node, so the node
   bind is required regardless. But `device.api` **and** `alsa.driver_name` are on the bound
   `Device`'s `info` props (measured — they are absent from the Device *global*, which is
   what the phase-5 results file checked). Reading the ALSA driver from the backing Device is
   authoritative and closes the phase-3 review's owed fix: on PipeWire ≥ 1.2.6 with
   WirePlumber < 0.5.13 the driver name is not copied to the node, and the fail-closed
   "absent driver ⇒ not a session device" rule would over-exclude real cards.

**Why v3.4 missed it, which is the transferable lesson.** Round 6 settled the *same question*
for Links and got it right — "endpoint props are an OPTIMISATION, the bind is the correctness
path" (§6.4) — on the explicit reasoning that `pw-dump` binds, so observing a key via
`pw-dump` says nothing about whether the **global-add** carries it. Every property in the
table above was likewise confirmed via `pw-dump`. The doubt was correctly formed and then
applied to exactly one object type. The general form: **`pw-dump` is a bound view; the
registry is not, and the difference is silent.**

Two things this does *not* change: the architecture (Option C, taint as a graph property, the
owner-key union, sticky taint — all vindicated, and the fixtures that fed them correct props
produced correct answers), and the Link/Client observation path.

⚠️ **O5 must be re-measured.** The phase-5 numbers (max 15 µs recompute, `busy_fraction`
0.0004) were taken on the graph this defect produces and do not include per-node bind I/O.

### 6.8 🔴 Uncertainty is not history — what stickiness may remember (round 9, MEASURED)

**Found by the phase-5 audit on the live graph within minutes of §6.7's fix landing**, which
is the strongest available argument for the dry-run phase existing at all.

**The observation.** With phase 3r running, a real hardware sink
(`alsa_output.usb-…Arctis_1_Wireless…`) carried `unresolved-ancestry` **permanently** — the
mark survived the readiness epoch, 21 recomputes and deliberate module churn. Traced to a
single event during enumeration: a link was observed while its output node was still
unbound, so §6.1.4's fail-closed rule correctly raised `UnresolvedAncestry` on the input
side. That mark was then written into sticky state, and §6.1.3 retires a sticky entry only
when **every member object is absent** — which a live sound card never is.

**Why round 8 made it systematic rather than rare.** Under §6.7 every node is withheld until
its bind resolves, so *any* link observed across that gap raises unresolved ancestry. It
fires at startup, every startup, on whichever node happens to lose the race.

**The rule (round 9).**

> **Sticky taint is a claim about history, and uncertainty is not history.** A node tainted
> only because the graph could not be seen has had nothing observed about it. Decisions
> still fail closed on it — that is unchanged and non-negotiable — but nothing about it may
> be *remembered* once the uncertainty is gone.

**Retiring by reason code is not sufficient, and this is the load-bearing part.** Uncertainty
launders itself: an unresolved node propagates `TaintedUpstream` to everything downstream,
and that reason is indistinguishable from real contamination once recorded. The split must
be by **provenance**, so the engine runs its fixpoint twice per recompute:

| pass | uncertainty roots | consumed by |
| --- | --- | --- |
| fail-closed | raised (`UnresolvedAncestry`, `UnresolvedOwner`) | **every decision** — unchanged from v3.5 |
| evidence-only | never raised, so nothing derived from one exists | **sticky state, and only sticky state** |

Evidence-based taint — `peerspeak.owned`, the AEC identity, pixelpass-owned objects, a
foreign echo canceller, and anything propagated from them — keeps §6.1.3's absence rule
exactly as written. That is what stops an app buffering the call and laundering itself
through a teardown, and it is unaffected by this change.

Cost: two fixpoints per graph event. Measured 80 µs worst case against a 47 Hz event rate,
so the O5 headroom absorbs it without argument.

⚠️ **Round-9 open item — CLOSED in round 11 (§6.9): hardware playback-to-capture
paths.** A card offering "Stereo Mix" / "Digital Loopback" presents an
ordinary driver name (`snd_hda_intel`), so both its sink and its source classify
`session_device` — and audio written to the sink reappears on the source through a hop the
Link graph cannot see. This is the `snd_aloop` hazard (§6.1.1, phase-3 review finding 2) in
a form the driver denylist cannot detect. It is **not new in round 9** and not introduced by
either recent round. Round 11 closes it without relying on a driver denylist or control name.

⚠️ **Round-9 open item — CLOSED in round 11 (§6.9): calibration of the readiness
budget.** The observer times out
after 2 s and `TimedOut` is sticky by design, so a process that never sees one
obligation-free instant during initial enumeration is silent for its lifetime. The original
~3 ms observation on one idle desktop was not enough; round 11 adds repeated starts, an
inflated graph, and concurrent graph churn.

### 6.9 🟢 Same-device hardware bridge + readiness calibration (round 11, MEASURED)

**The hardware rule.** For every positively classified passive hardware terminal, retain the
Node's snapshot-local `device.id`. The taint walk adds a directed synthetic edge from an
`Audio/Sink` (or output side of `Audio/Duplex`) to every `Audio/Source` (or input side of
`Audio/Duplex`) carrying the **same** `device.id`:

```
tainted stream -> hardware sink ~[private mixer / firmware]~> same-device source -> reader
```

Both predicates are load-bearing. `session_device=true` limits the rule to the observer's
positive passive-hardware allowlist; `device.id` limits it to one physical Device instead of
fusing every card exported by WirePlumber. The id never enters sticky identity and never
survives its snapshot.

**Why this is unconditional rather than an ALSA-control probe.** Measured 2026-08-21: the
ALC897 exposes `Loopback Mixing` (disabled) and two `Input Source` controls containing Rear
Mic, Front Mic and Line, but no `Stereo Mix`. Linux HDA treats analog loopback monitoring and
the optional `Stereo Mix` capture source as distinct mechanisms (kernel
[`hda_generic.c`](https://code.googlesource.com/linux/torvalds/linux/+/master/sound/pci/hda/hda_generic.c)
and [HDA control documentation](https://cdn.kernel.org/doc/html/latest/sound/hd-audio/controls.html)).
More importantly, ALSA/HDA
control spelling cannot prove the absence of USB, vendor-DSP or firmware loopback paths. A
control-name allowlist would therefore be precise on this card and unsound as a portable
absence proof. The graph rule closes every such hidden same-device hop without a new runtime
ALSA dependency.

**Accepted cost.** An app capturing a microphone from the same Device that is receiving
tainted playback is excluded even when that particular microphone path is clean. A source on
a different Device remains eligible. This is deliberate fail-closed over-exclusion, pinned by
pure exact-partition tests and a live dry-run negative control.

**Live partition, 2026-08-21.** Tagged playback was routed to the ALC897 sink. A controlled
reader/re-emitter on the ALC897 source was excluded `tainted-owner-bridge`; the identical
reader/re-emitter on the Arctis source remained eligible. The audit was graph-ready, all
temporary modules were unloaded by exact module id, and the configured default sink/source
were unchanged.

**Readiness budget — keep 2 s for v1.** Fresh observer startup measurements on the same live
desktop, using the observer's own monotonic `at_ms` clock:

| arm | runs | p50 | p95 | max | timeout |
| --- | ---: | ---: | ---: | ---: | ---: |
| ambient graph | 30 | 5 ms | 10 ms | 11 ms | 0 |
| inflated graph: 24 null sinks + 24 loopbacks | 30 | 111 ms | 113 ms | 114 ms | 0 |
| 250 create/remove cycles concurrent with fresh starts | 20 | 5 ms | 6 ms | 8 ms | 0 |

The deliberately inflated maximum leaves 17.5x headroom to the sticky 2 s deadline. This is
not a universal latency promise; it is a calibration argument that exercises enumeration
volume and graph instability, rather than extrapolating from one idle start. Revisit the
budget if a supported target measures startup p95 above 500 ms or produces a real timeout;
do not weaken `TimedOut`'s fail-closed/sticky semantics to hide one.

## 7. Lifecycle and teardown invariants

### 7.1 ⚠️ The invariant

> **The AEC module must not unload while pixelpass is alive and fanning out.**

If it does, the index pixelpass holds becomes stale, and — because indices are reused
(§5.2 correction 3) — it can alias onto an unrelated future module, silently un-excluding
the real hazard or excluding innocent audio.

### 7.2 ⚠️ VERIFIED DEFECT — implicit-drop order is inverted (not yet fixed)

`ActiveSession` (`peerspeak/src/core/mod.rs:668-691`) declares:

```rust
echo_cancel: Option<EchoCancelGuard>,      // :682
screenshare_host: Option<tokio::process::Child>,   // :685   (kill_on_drop)
```

Rust drops fields in **declaration order**. On the **implicit-drop** path — the command
channels close at `core/mod.rs:1512` (`reliable_rx.recv()` returns `None` → `break`), or
the core loop unwinds — `ActiveSession` is dropped **without** `shutdown()` running. So
`echo_cancel` unloads (a blocking `pactl unload`) *before* `screenshare_host`'s
`kill_on_drop` even fires: **the AEC unloads while pixelpass is still alive.** Exactly the
ordering the invariant forbids. Verified in source.

`shutdown()` (`:694-730`) gets it right — it kills `screenshare_host` at `:699` and drops
`echo_cancel` at `:730` — but only as an emergent property of statement order, which any
refactor can silently invert.

**⚠️ Reordering the fields is NOT sufficient** (round-4 correction). `screenshare_host`
is spawned with `kill_on_drop(true)` (`peerspeak/src/screenshare/mod.rs:402`). Tokio's
`Drop` for such a `Child` *sends* the kill and hands the process to a best-effort orphan
reaper — it does **not** wait, and gives no promptness guarantee, especially if the
runtime is itself shutting down. Explicit `child.kill().await` is SIGKILL **plus wait**;
implicit drop is SIGKILL and move on. So even with `echo_cancel` declared last, the
`pactl unload` can still run while pixelpass is briefly alive.

**Fix, in order of importance:**

1. **Eliminate the implicit path.** At both channel-close `break` sites
   (`core/mod.rs:1516` and `:1532`), explicitly `take()` the session and
   `shutdown().await` it rather than letting it drop. The ordered teardown should be the
   *only* teardown.
2. **Move `echo_cancel` to the last declared field** anyway, with a comment naming the
   invariant — defence in depth for paths 1 does not cover (panics, unwinds).
3. **Last-ditch ordering in the drop path**: a wrapper whose `Drop` does `start_kill` +
   a bounded `try_wait` loop on the host before the AEC guard unloads.

**D4 regression guard** (concrete, replacing v3.0's vague "field-order assertion"): a
test using a **fake host** and **fake echo-cancel guard** that each record a timestamped
event into a shared slot on teardown, asserting `host kill+wait completed` strictly
precedes `echo unload` — plus a core-loop test that closes the command channel and proves
`shutdown()` actually ran. A field-order assertion alone does not test the behaviour that
matters.

### 7.3 Construction paths

There is exactly **one** `echo_cancel::enable` call site (`core/mod.rs:1850`, at session
join), the guard moves into `ActiveSession`, and there is exactly **one** explicit drop
(`:730`). **No mid-call AEC reload path exists.** This is what downgraded Codex's demanded
QUIESCE/SET_AEC/RESUME two-process epoch protocol to:

> **P1-impact latent hazard, currently unreachable in normal operation.** Required now:
> encode teardown ordering for explicit *and* implicit destruction, prevent or review
> additional AEC construction paths, fail closed if identity is missing or revoked.
> **An epoch protocol becomes required if and only if hot AEC reload is added.**

Anyone adding a second `enable` site, or any hot-reload, re-opens that requirement.

### 7.4 Graceful stop is still owed

**Stop Share is currently SIGKILL** (`peerspeak/src/core/mod.rs:699` + `:3480`, Tokio
`Child::kill()`). Under Option C this no longer strands the user's desktop audio — the
links die with the connection, which is the point. But it still leaks:

- The capture null sink is **pactl-loaded and pipewire-pulse-owned**
  (`pixelpass/src/host/audio.rs:69`), so **Stop Share leaks one null-sink module every
  time.** This is true today, independent of this feature.

Required:
1. A graceful control path in peerspeak: **SIGINT** (not SIGTERM — pixelpass installs
   only `tokio::signal::ctrl_c()`, `pixelpass/src/common/signal.rs:6`), bounded wait,
   SIGKILL fallback.
2. The capture sink should become **connection-owned** rather than pactl-owned, so it
   shares the links' death-with-the-process property.
3. `--repair` (`pixelpass/src/repair.rs:15-63`) extended to this mode, and safe with a
   second live host.

## 8. IPC: getting the index to pixelpass

pixelpass is a **separate process** and cannot learn the module index on its own.
peerspeak spawns it, so:

- New pixelpass flag: `--exclude-pulse-module <idx>` (naming, §11).
- peerspeak passes `EchoCancelGuard`'s index at spawn. The field is currently private
  with only `source_name()` / `sink_name()` accessors — add `module_index()`.
- If the AEC is **off**, the flag is absent and pixelpass must not invent an exclusion.
- If the AEC is **on** but the flag is absent, that is a bug in peerspeak; pixelpass
  cannot detect it. ⇒ peerspeak should pass an explicit `--aec=off|<idx>` rather than
  "flag present or not," so pixelpass can distinguish "no AEC" from "someone forgot."
  **Open decision D5 (§13).**
- Because no hot-reload path exists (§7.3), spawn-time argv is sufficient today. A
  runtime channel is required only alongside hot reload.

## 9. What is proven, and what is not

### 9.1 Proven by measurement on this machine (PipeWire 1.6.8 / WirePlumber 0.5.15)

- Fan-out carries full-level audio (−24.1 dB, matching the speaker monitor) for **paplay,
  mpv, VLC**; the app keeps its speaker link.
- WirePlumber does **not** reap foreign links across default-sink switch, switch-back,
  suspend, resume, or 100 s steady state.
- Non-lingering links die on **SIGKILL** of the owner.
- **E2:** destroying the capture sink mid-share left the app playing to speakers
  undisturbed.
- `peerspeak.owned=1` lands on paplay/mpv/VLC nodes via `PULSE_PROP`.
- `pulse.module.id` on all four AEC nodes == the index pactl returned.
- Naive fan-out of the AEC leg leaks remote audio at ≈desktop level; exact exclusion sits
  at the control floor.

**Round 8 (2026-07-25), from the phase-5 dry-run against the live graph:**

- The registry `global` event announces **13 keys** for a Node and **none** of the eight
  ownership/identity properties this design reads (§6.7). `port.exclusive` is absent from
  Port globals. Link endpoint keys and Client `pipewire.sec.pid` **are** announced, on every
  object, always.
- **Binding recovers all of them** — `factory.name`, `device.api`, `alsa.driver_name`,
  `peerspeak.owned`, `pulse.module.id`, `node.link-group`, `application.process.id` read off
  the bound object's `info` props.
- `factory.id` is **not** a shortcut to `factory.name`: every ALSA node claims `factory.id`
  19, whose Factory resolves to `"adapter"`, not `api.alsa.pcm.sink`.
- `alsa.driver_name` and `device.api` **are** on the **bound `Device`**'s `info` props
  (absent from the Device *global*) — the authoritative source for §6.7 decision 4.
- Full recompute per graph event: **max 15 µs, mean 4 µs** over 334 recomputes at a 47 Hz
  event rate under deliberate churn; `busy_fraction` 0.0004. Closes O5 for the engine —
  ⚠️ but measured on the degraded graph, with no per-node bind I/O in it.

### 9.2 ⚠️ Wording discipline — three overclaims already made, do not make a fourth

The correct statement of the exclusion result is:

> *"No incremental 1500 Hz energy was detectable above the control floor at the analysis
> resolution in this steady-state run."*

**Not** "absent," **not** "conclusive." What survives is the gross-leak distinction: the
naive arm copies the probe at ≈desktop level, exact exclusion does not. Likewise, equal
`mean_volume` on a sine proves **signal presence, not fidelity** (blind to xruns, drift,
dropouts, channel swap, quantum change), and "copy semantics" is a **topology** result —
it shows the tested link operation did not move the tested Pulse stream, and says nothing
about gain, latency, continuity, or native clients.

The rig is additionally blind to: startup/teardown/cork/relink transients (hidden by
whole-file averaging), broadband and out-of-band leakage, level-dependent and nonlinear
products, and nodes created after enumeration.

**Minimum rig upgrade before shipping:** two orthogonal PN/MLS probes + windowed
per-channel normalized cross-correlation, reporting max per-window correlation, plus xrun
telemetry.

### 9.3 Untested — carried forward, each one a real risk

AEC reload mid-share · two concurrent AEC instances · two concurrent capture sinks · the
**native** PipeWire AEC module · a native-PipeWire (non-Pulse) app · pixelpass's own
null-sink + loopback present simultaneously · the full GStreamer/AAC/network path ·
fidelity (needs broadband source + correlation + xrun telemetry) · PipeWire daemon restart
· quantum/latency perturbation from the second link · sample-rate mismatch, surround,
IEC958 passthrough · browser and game stream shapes.

## 10. Prerequisite fixes (split out, land before the feature)

Both reviews agree these are their own tasks, not part of this feature.

1. **`object.serial` u32 truncation** — 64-bit in PipeWire, parsed as `u32` at
   `pixelpass/src/host/audio.rs:534-540`. Global IDs are reused; serial is the recommended
   stable identifier. Must be fixed before the router grows.
2. **`@DEFAULT_SINK@` resolved once at module load** (`audio.rs:139-151`), no
   default-metadata listener — the user's `Ctrl+Meta+F` / `Ctrl+Meta+S` output-switch
   hotkeys strand the local monitor mid-share. **This already hurts per-app mode today.**
   Option C does not need the local monitor, so this is decoupled from the feature — but
   it is a live bug.
3. **`try_flush` records intent, not success** (`audio.rs:642-655`): it ignores
   `Metadata::set_property`'s return and appends every pending ID to `routed_node_ids`.
   Any status surfaced to the user inherits that dishonesty. Option C's link-state
   `ACTIVE` check (§4.2) is the honest replacement for the new mode; the old path should
   be fixed or deleted.
4. **Graceful stop + connection-owned capture sink** (§7.4).
5. **Drop-order fix + regression guard** (§7.2).

## 11. Naming — the user's call

Placeholders throughout. pixelpass mode: `--audio-mode=desktop-shared` /
`--audio-mode=desktop-excluding`. Exclusion flag: `--exclude-pulse-module <idx>` (or
`--aec <idx|off>`, §8). Do **not** surface `--exclude-pid` — it names an unreliable
mechanism and reads like process control.

peerspeak picker wording: something like "System audio except peerspeak," noting that
call and watched-share playback are excluded. Whether "All system audio" stays alongside
it (with a stated echo risk) or is replaced when the capability is present is a product
decision.

## 12. Testing

Pure, unit-testable seams with PipeWire at the edges, per house style:

- `fn eligibility(node_props: &Props, ctx: &ExclusionCtx) -> Eligibility` with
  `NotEligible { reason }` so status can explain itself. Cases: `peerspeak.owned` present;
  `pulse.module.id` == live index; `pulse.module.id` present but **different** (must be
  ELIGIBLE — correction 2); `pulse.module.id` absent; a pixelpass-owned node; capture-sink
  ancestry; `port.exclusive`; passthrough; non-`Stream/Output/Audio`; missing props
  entirely; the capture sink itself; a foreign `echo-cancel-*` group.
- `pulse.module.id` parsing: JSON number **and** string forms, values > `u32::MAX`,
  absent, malformed.
- AEC-identity validation state machine: `NotConfigured` / `Validated` / `Revoked`, and
  the assertion that `Revoked` stops fan-out.
- Pure capability-probe parsing (§13 D2).
- Link bookkeeping: per-port link set, "captured" only at all-`ACTIVE`, idempotent
  re-enumeration, proxy retention/drop.

**⚠️ Node-local eligibility tests are NOT sufficient.** The C2/C3-class defects all live in
the graph engine, so the taint engine needs its own pure test surface, fed synthetic
Node/Port/Link/Client fixtures:

| test | catches |
| --- | --- |
| GStreamer **split clients** (two `client.id`s, one `application.process.id`) are bridged | the C2 refutation |
| the key union **falls through** a present-but-unequal key (`client.id` differs ⇒ try key 4) | the §6.1.2 wording trap |
| the pipewire-pulse PID does **not** bridge unrelated modules | mass over-exclusion |
| a module forwarder with neither `link-group` nor `pulse.module.id` ⇒ **unresolved ⇒ excluded** | fail-closed invariant |
| sticky taint **survives** the tainted input leg unlinking/disappearing while the output leg lives | the C3 buffered-audio defect |
| sticky taint **clears** once every owner member object is gone | over-exclusion forever |
| a **recycled** `client.id` / module index / node id / `link-group` does **not** inherit taint | §6.1.3 lifetime-awareness |
| the readiness epoch blocks stale or unresolved link decisions | §6.4 |
| taint crosses `app → sink → monitor-reader` at node granularity | §6.1 edge type 2 |
| an `Audio/Duplex` node over-taints (asserted as *known accepted* behaviour, so a future fix is a deliberate change) | §6.1 caveat |

Field tests — the only thing that can prove a viewer does not hear themselves:

1. Sharer in a call while sharing, **AEC on and AEC off**.
2. Sharer simultaneously *viewing* another share while sharing.
3. Lifecycle, each separately: Stop button, room leave, UI crash, pixelpass panic, SIGINT,
   SIGTERM, SIGKILL, last-viewer disconnect, pipewire-pulse restart, PipeWire daemon
   restart, `pixelpass --repair`.
4. Output-device switch mid-share via the real hotkey scripts.
5. Two concurrent hosts (second pixelpass CLI, second peerspeak instance).
6. A notification sound firing mid-share.
7. An app that **starts playing after** the share began (dynamic node).
8. Sample-rate / channel / passthrough behaviour on real sinks; CPU cost.

⚠️ **Test-rig discipline** (each of these already produced a wrong result once):
filter on `media.class` **first** when selecting nodes with `jq` — `media.name` also
matches the Client object; **never** filter stderr out of a measurement run; **verify the
link exists in the graph** before measuring; reproduce over the transport production
actually uses (`parec -d <sink>.monitor`, not `pw-record --target <sink-node-id>`, which
reads −91 dB silence); **(r8)** never conclude a property is *observable* because
`pw-dump` shows it — `pw-dump` **binds**, the registry does not, and the eight properties
of §6.7 look identical in `pw-dump` to properties the code can actually see. Compare
`pw-cli ls <Type>` (registry view) against `pw-dump` (bound view) before depending on any
key.

## 13. Decisions — resolved in round 4

Both reviewers agree on all seven. Recorded as decided; reopen only with new evidence.

- **D1 — fail closed, but only after a bounded validation wait** (§5.3). Never "share
  anyway, warn" as the default. ✅
- **D2 — a versioned machine-readable capability response or bitset.** The
  `pixelpass --help` substring probe (`src/screenshare/mod.rs:245-278`, invoked at
  `src/core/mod.rs:3368`) stays only as a compatibility fallback, and this mode must
  **not** overload `app_audio_supported: bool` — strict per-app and desktop-excluding are
  independent capabilities. ✅
- **D3 — warn and exclude foreign `echo-cancel-*` nodes** for the first implementation;
  never fan them out. ✅
- **D4 — explicit async shutdown + a fake-resource ordering test** (§7.2). A field-order
  assertion alone is inadequate. ✅
- **D5 — `--aec=off|pulse-module:<idx>`, always passed.** Absence of the flag is not a
  protocol state (§8). ✅
- **D6 — land §10 items 1, 4 and 5 first**, plus the new graph-ancestry predicate (§6.1).
  Items 2 and 3 are real per-app debt but do not block Option C unless the new mode reuses
  those code paths. ✅
- **D7 — no materially simpler design exists** that still meets Joe's ask. The available
  simplification is to *narrow v1 scope*, not to change architecture. ✅

## 14. Readiness — 🟢 v3.7 (round 10): the §5.1 matrix PASSED; architecture unchanged.

**Round 10 (2026-07-26).** The phase-5 matrix ran in full and **passed all 13 rows with a
non-empty eligible half in every one** — results in
`screenshare-audio-exclusion-phase5-results.md`. It also found a third measured defect on
first contact, and once again the failure was fail-closed and *silent*, exposed only by the
requirement to assert what must remain **eligible**: §6.1.2's pulse-PID derivation returned
`None` permanently on this host, so key 4 fused every Pulse-emulated node into one owner.

| | verdict |
| --- | --- |
| Architecture — Option C, taint as a graph property, owner-key union, sticky taint, AEC identity state machine | **unchanged, three times vindicated** |
| §6.1.2 | **revised** — the derivation heuristic is deleted; `comm` alone decides |
| §5.1 matrix | **PASSED** — 13/13, incl. the full sticky lifecycle (row 10) and provable identifier recycling (row 11) |
| O5 | **closed on the real graph** — worst recompute 67 µs, churn mean 10 µs, busy fraction 0.0006 |
| Phase 5 | **machinery unchanged and correct** — three real defects caught on first contact with the live graph, none of them in the engine |
| Phase 6 | **still blocked** — by F11-1, phases 0b/0c/0d, and the "Stereo Mix" design call, *not* by this matrix. (F11-1 was **closed later the same day** with this matrix's data — §6.1.2's round-13 box; the rest stand.) |

Three rows passed with recorded substitutions (8 EasyEffects, 9 Firefox's own mic/monitor
paths, 13 a real `Audio/Duplex` device) and the third-party samples stay owed.

**Round-11 supersession (2026-08-21):** the row above is the round-10 snapshot, not current
status. F11-1 and phases 0b/0c/0d are satisfied, and §6.9 closes the hardware-path decision
plus readiness calibration. S4/S5/0d, round 11, and Phase 6's first pure channel planner are
committed locally in PixelPass `781defc`; the first live fan-out mutation is committed locally
in `98cde2c`.

**Round 9 (2026-07-25).** Phase 3r shipped §6.7 and the audit was re-run
immediately; it found a *second* measured defect within minutes — a permanent sticky taint
on a hardware sink (§6.8). Both rounds share a shape worth naming: **the architecture was
right and the instrumentation was wrong**, and only running the code against a live daemon
found either.

| | verdict |
| --- | --- |
| Architecture — Option C, taint as a graph property, owner-key union, sticky taint, AEC identity state machine | **unchanged, twice vindicated** |
| §6.8 | **new** — sticky state is built from an evidence-only pass; decisions still fail closed |
| §6.1.3 | **narrowed** — the absence rule now governs evidence-based taint only |
| Phase 3r | **built and merged**, four-part gate passed incl. live |
| Phase 5 | **machinery unchanged and correct** — it has now caught two real defects on first contact with the live graph |



**Round 8 was not a review round.** It was opened by the phase-5 dry-run audit failing its
gate on the first live run: the engine built to v3.4 was measured **non-functional** — it
failed to recognise its own primary taint root (an echo) while excluding every stream on the
machine (silence). One cause, §6.7: node properties are not observable from the registry.

What that does and does not touch:

| | verdict |
| --- | --- |
| Architecture — Option C, taint as a graph property, owner-key union, sticky taint, AEC identity state machine | **unchanged and vindicated.** Fed correct properties, the engine decided correctly in every fixture; the defect is entirely at the observation boundary |
| §5.1 tagging | **revised** — a second, registry-visible carrier added |
| §6.4 implementation shape | **revised** — node/device props require a bind |
| §6.7 | **new** — the observation boundary, and the rule that the global is an index, not a source of truth |
| §6.1.0, §6.1.4 | **corrected** — a time-dependent claim and an unreachable test case |
| Phases 2 and 4 (pure engine, AEC validator) | **no change owed** |
| Phase 3 (observer) | **must be revised before phase 5 re-runs** |

The §5.1 exact-partition requirement is what caught this, exactly as argued: the build's
exclusions were all defensible, and an exclusion-only checklist would have passed it. It was
the *eligible* half of the partition being empty that exposed the failure.

**Rounds 1–7 record.** Both reviewers agreed v3.4 was ready to become the implementation
plan; every blocker raised was either fixed or refuted with evidence. That remains true —
round 8 found something no design review could have, because it required running the code
against a live daemon.

How the blockers closed:

| round | blocker | outcome |
| --- | --- | --- |
| 4 | eligibility is node-local | **fixed** — §6 rewritten as graph taint |
| 4 | one-shot AEC validation | **fixed** — §5.3 bounded state machine |
| 4 | field reorder insufficient | **fixed** — §7.2 explicit shutdown + ordering test |
| 5 | Link-only walk misses forwarders | **fixed** — §6.1 three edge types, measured |
| 5 | monitor edge needs synthetic modelling | **refuted** — free at node granularity (C1) |
| 6 | `client.id` is not an owner key | **refuted my own claim** — §6.1.2 owner-key union |
| 6 | current-only taint forgets buffers | **conceded** — §6.1.3 sticky taint |
| 7 | "resolves" = first-present would still leak | **fixed** — §6.1.2 wording trap + test |
| 7 | stickiness on recyclable ids | **fixed** — §6.1.3 lifetime-aware owner components |
| **8** | **node props are not on the registry global (measured, phase 5)** | **fixed** — §6.7 bind-every-node rule; §5.1 second carrier |
| **9** | **a fail-closed unresolved mark became permanent sticky taint (measured, phase 5 re-run)** | **fixed** — §6.8 evidence-only sticky pass |
| **9** | `device_props` tested for one live *Device* rather than one live *global* on the id (Codex, certain) | **fixed** in phase 3r — stale `session_device` on a contested id is an echo path |
| **9** | `device.api` corroborated by presence, so `v4l2` under an ALSA factory passed (Codex) | **fixed** in phase 3r — the API must equal the allowlist's own |
| **9 → 11** | hardware playback-to-capture ("Stereo Mix") defeats the `session_device` classifier (Codex, P1 worth checking) | **CLOSED — §6.9.** Conservative `Sink → Source` edge for passive terminals sharing `device.id`; pure and targeted live exact partitions pass. No runtime control-name guess. |
| **9 → 11** | the 2 s readiness budget has no calibration argument (Codex) | **CLOSED — §6.9.** 30 baseline starts, 30 starts with 48 temporary modules, and 20 starts during 250 create/remove cycles; inflated max 114 ms, zero timeouts. Keep 2 s. |
| **10** | **the pulse-PID derivation required a *single* repeated `sec_pid`; WirePlumber repeats one too, so it returned `None` permanently and key 4's suppression never fired (measured, phase-5 run 2)** | **fixed** — §6.1.2 round-10 box: probe every distinct `sec_pid`, let `/proc/<pid>/comm` decide |
| **10** | the audit's `sticky` flag means "is in the remembered set", so it is true for nearly every tainted node and does not answer "excluded only because remembered" | **OPEN — reporting only**; the evidence-only pass §6.8 already computes what is needed |
| **10** | a bridge's named key is lost when a leg reappears under a new serial (sticky `reason_for` falls back to keyless, and `raise` will not replace a same-rank reason) | **OPEN — reporting only**; verdict unaffected |

### v1 scope — agreed

Option C fan-out · explicit `--aec=off|pulse-module:<idx>` · peerspeak playback and child
tagging · exact AEC module validation · graph taint with the owner-key union and the
pipewire-pulse PID exception · sticky taint · readiness epoch · fail-closed unresolved
ancestry · conservative same-device hardware bridge · owned non-lingering links · §10 items
1, 4 and 5 landed first.

### Deliberately OUT of v1

Node-granular taint only (no port modelling, duplex over-taint accepted) · no timed drain ·
no hot-AEC-reload epoch protocol · no native PipeWire AEC support · no incremental
dirty-set (full recompute) · no "implausibly many streams" heuristic as correctness ·
pipewire-pulse/PipeWire daemon restart handled as **revoke and stop**, not seamless
recovery · **(r8)** no per-node quarantine — an unresolvable node bind fails the whole
readiness epoch closed rather than isolating that node (§6.7 decision 3) · **(r8)** no Port
binding, so `port.exclusive` is never observed and the §6.2 row it guards relies on the link
create failing cleanly · **(r8)** no serial-continuity signal for the AEC validator's
no-coalescing contract.

### Current front after round 11

Phases 0a–5 and 3r are built; the full phase-5 matrix passed; 0b is merged; and 0c/0d plus
the S4/S5 ownership work are built, validated, and committed locally. Round 11 closes the last
two pre-Phase-6 design decisions with pure, observer, live PipeWire and targeted dry-run
evidence. Phase 6's channel-aware pure planner is also committed in PixelPass `781defc`. On top
of that checkpoint, local commit `98cde2c` creates and retains serial-guarded
non-lingering links through the hidden production path, requires all planned links to be
`ACTIVE`, revokes them when eligibility changes, and passed both normal-teardown and `SIGKILL`
cleanup gates. Local commit `5a65f50` adds exact version-1 status records for stream link failure,
AEC validation failure, AEC revocation and foreign AEC detection; PipeWire callbacks enqueue them
for Tokio-side JSON emission. Local commit `d09ee9b` recreates an unexpectedly removed
connection-owned sink with a fresh serial, hands that exact identity to the fan-out observer,
drops stale link proxies, and returns every replacement channel to `ACTIVE`. The pure recovery
gate, an owner-only live sink-destruction gate, and the full hidden
host-path sink-destruction/relink gate pass; the full suite reports 332 passed and 12 ignored, all
three serialized Phase 6 live gates pass together, and strict Clippy plus `pixelpass --doctor`
remain clean.

PixelPass commit `6be07ef` closes Row 1 and Row 8d/8e. Mutation-edge serial
revalidation now covers retained proxies as well as new links, and a recycled identity produces
zero unsafe creates. Two optimized-release fault-injection gates prove capture-sink construction
failure and readiness timeout both fail `DesktopExcluding` closed without resolving the legacy
default monitor or constructing legacy routing. Full validation reports 335 passed and 12
ignored; strict Clippy, all three serialized live Phase 6 gates, diagnostics and residue checks
pass.

PixelPass commit `956534f` closes the three independent Row 6a/6b/6c refusal/reason fixtures.
`Stream/Output/Audio` Nodes advertising a readable configured Format
param are subscribed and parsed through libspa into raw, encoded or IEC958; unknown format is
per-stream fail-closed, while the existing `node.passthrough` property remains an independent
predicate. Separate controller gates prove `port.exclusive`, encoded and IEC958 each make zero
link-create calls and emit only `port-exclusive`, `encoded` and `iec958-passthrough`
respectively. An additional gate proves an explicit passthrough property cannot be masked by a
raw Format, and the initial Node-info-before-Format ordering does not emit a false warning.

A read-only live audit initially caught generic Pod parsing failures and harmful Format queries
against Nodes that did not advertise the param. After switching to libspa's native parser and
gating queries on readable Format support, Strawberry, FFXIV and Chromium all settled to raw
eligible streams with no parse/core errors. Full validation is 342 passed and 12 ignored; the
three Row 6 cases also pass optimized release, strict Clippy and `pixelpass --doctor` are clean.
The `port.exclusive` case remains an injected-graph gate under v1's accepted no-Port-binding
limitation; a live exclusive port still degrades through the separately tested link-failure path.

PixelPass commit `7b11827` carries the revised Row 9 partition through the real fan-out
controller. Four independent late-arrival gates prove music-only and a different-device
microphone each create both stereo links and reach `Captured`, while same-device capture and a
tainted-monitor capture retain `tainted-owner-bridge` and make zero link calls. Full validation
is 345 passed and 12 ignored; strict Clippy, all three serialized live Phase 6 mutation gates,
diagnostics and residue checks pass. This completes the deterministic link-manager matrix, not
Phase 6's separate live signal qualification.

PixelPass commit `e027bc6` completes Phase 6's separate live signal qualification. Its
deliberately unsafe predicate is wholly `#[cfg(test)]` and re-admits only the exact configured
`aec-identity` candidate. The live test drives the hidden selector through the real sink,
observer, taint controller, native link manager and Pulse monitor recording path; filters
`media.class` before the exact module ID; preserves child stderr; and verifies the intended
links in PipeWire before recording with `parec`.

Two complete runs kept the guarded 1500 Hz result at or below the run's control floor within the
declared 3 dB tolerance, while the naive arm captured 1500 Hz at desktop level and at least 18 dB
above control and guarded. The supported result is **no incremental 1500 Hz energy detectable
above the control floor at this analysis resolution**, not proof of absence. Full validation is
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,
   preserving the old-PeerSpeak/new-PixelPass compatibility gate.
2. Then complete Phase 8's capability-gated PeerSpeak argv, picker, UI and causal status path.

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
GStreamer/AAC/network path or on two machines.
