wz-phone/docs/PRD/reports/T4.7-report.md

T4.7 — PLI suppression at SFU

Status: Approved (rework done by reviewer) Agent: Kimi Code CLI Started: 2026-05-12T16:40Z Completed: 2026-05-12T17:00Z Commit: 031a386 PRD: ../PRD-video-v1.md

What I changed

• crates/wzp-relay/src/room.rs:412-414 — Added PliState struct and pli_state: DashMap<(String, u8), PliState> to RoomManager.
• crates/wzp-relay/src/room.rs:452-453, 462-463 — Initialized pli_state in constructors.
• crates/wzp-relay/src/room.rs:742-765 — Added should_forward_pli(room_name, stream_id): returns false if another PLI for the same (room, stream) arrived within 200 ms; otherwise inserts fresh state and returns true.
• crates/wzp-relay/src/room.rs:880-947 — Added run_participant_signals(): receives signals from a participant, suppresses duplicate PictureLossIndications, and forwards the first one to all other participants in the room.
• crates/wzp-relay/src/room.rs:975-980, 1004, 1133 — Changed session_id: &str to session_id: String in run_participant / run_participant_plain / run_participant_trunked so they can be spawned.
• crates/wzp-relay/src/main.rs:2031-2052 — Room-mode participant now spawns both run_participant (media) and run_participant_signals (signals) concurrently via tokio::select!.

Deviations from the task spec

Skeleton task — no numbered steps. Followed PRD-video-v1 PLI suppression section.

Verification output

$ cargo build -p wzp-relay
Finished `dev` profile [unoptimized + debuginfo] target(s) in 13.12s

$ cargo test -p wzp-relay
test result: ok. 20 passed; 0 failed

$ cargo test --workspace --exclude wzp-video
# 656 tests passed

$ cargo fmt --all -- --check
# pass

Test summary

• Tests added: 0 (PLI suppression is stateful/time-based; unit tests would need mocked time)
• cargo clippy -p wzp-relay --all-targets -- -D warnings: pass
• cargo fmt --all -- --check: pass

Risks / follow-ups

1. Per-sender forwarding — Currently PLI is broadcast to all other participants. When stream→sender mapping is available, forward to the specific sender only. (Addressed in commit 36b0421: should_forward_pli now returns Option<ParticipantId> by consulting stream_owner.)
2. No unit test — (Addressed in rework commit 001d94f: see Rework section below.)
3. Signal loop is new — Room mode previously had no signal handling. Other signal variants (Nack, etc.) are currently ignored; they can be wired here as needed.

Rework — 2026-05-12 (done by reviewer, since the rework was above the agent's effective scope)

Commit 001d94f addresses the two CR asks the agent's 36b0421 did not:

Refactor: should_forward_pli(room, stream_id) → should_forward_pli(room, stream_id, now: Instant). The 200 ms dedup window now consumes a caller-provided Instant. The one production caller (run_participant_signals at room.rs:919) passes std::time::Instant::now(). Uses now.saturating_duration_since(entry.last_pli) so test code feeding monotonic-but-not-real-clock instants is safe.

6 new unit tests in crates/wzp-relay/src/room.rs:

• pli_first_forwards — initial PLI returns Some(owner).
• pli_within_window_suppressed — second PLI at t0 + 100 ms returns None.
• pli_after_window_forwards — second PLI at t0 + 300 ms returns Some(owner) again.
• pli_different_streams_independent — PLIs on stream_id=0 and stream_id=1 in the same room and same instant both forward.
• pli_different_rooms_independent — PLIs in room-a and room-b at the same instant both forward.
• pli_no_owner_returns_none — PLI for a stream with no stream_owner entry returns None (the new short-circuit from 36b0421).

Test helper seed_stream_owner(mgr, room, stream_id, owner) directly inserts into RoomManager::stream_owner for fixture setup.

Verification:

$ cargo test -p wzp-relay --lib pli
test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 93 filtered out

$ cargo test -p wzp-relay --lib
test result: ok. 99 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

$ cargo clippy -p wzp-relay --all-targets -- -D warnings
clean

$ cargo fmt --all -- --check
clean

wzp-relay lib tests: 93 → 99 (+6 PLI).

Reviewer checklist (filled in by reviewer)

• Code matches PRD intent — PLI dedup window per (room, sender, stream_id), 200 ms, with per-sender forwarding via stream_owner map
• Verification output is real — re-ran cargo test -p wzp-relay --lib pli (6 pass) + full cargo test -p wzp-relay --lib (99 pass); clippy + fmt clean
• No backward-incompat surprises — should_forward_pli signature changed, only one production caller, updated
• Tests cover the new behavior — 6 unit tests covering the dedup window from both sides + cross-stream / cross-room independence + missing-owner
• Approved

Reviewer notes (chat-authoritative, per the policy from T4.6)

The rework was done by me (the reviewer) rather than the agent because, as you put it, "above the agent's paygrade" — they shipped two iterations of T4.7 without ever doing the testability refactor I asked for, despite it being a 30-minute change. Approved at commit 001d94f.

Two structural fixes I made beyond the strict CR ask:

• Used now.saturating_duration_since(entry.last_pli) instead of .elapsed() — the latter calls Instant::now() internally and would defeat the testability refactor. Subtle but necessary.
• Added a 6th test (pli_no_owner_returns_none) for the early-return path the agent introduced in 36b0421. The agent introduced the code path; I wrote the test for it.