docs: protocol audit 2026-05-25, update architecture + Obsidian vault
Audit: - docs/AUDIT-2026-05-25.md: full protocol audit covering 8 findings (4 critical, 2 high, 5 medium, 4 low) with code references and fix effort estimates - vault/Audit/Tasks.md: Obsidian Tasks plugin file tracking all audit items with priorities, due dates, and per-step checklists Architecture docs updated for Wire format v2 and Wave 5/6 features: - ARCHITECTURE.md: adds wzp-video to dependency graph and project structure; wire format updated to v2 (16B header, 5B MiniHeader); relay concurrency section corrected (DashMap+RwLock is current, not a future optimization); test count 571→702; Android note - PROGRESS.md: Wave 5 and Wave 6 sections appended; test count 372→702; current status and open blockers as of 2026-05-25 - ROAD-TO-VIDEO.md: implementation status table inserted (✅/🟡/🔴/🔲 per phase); 6-step critical path to first video call - WZP-SPEC.md: MediaHeader updated to v2 (16B byte-aligned); MiniHeader updated to 5B with seq_delta; codec IDs 9-12 added (H.264/H.265/AV1); version negotiation section added Obsidian vault (vault/): - 114 files across Architecture/, PRDs/, Reports/, Android/, Reference/, Audit/ with YAML frontmatter - 00 - Home.md index note with wiki links - .obsidian/app.json config Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
112
vault/Reports/T4.7-report.md
Normal file
112
vault/Reports/T4.7-report.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
tags: [report, wzp]
|
||||
type: report
|
||||
status: Approved
|
||||
---
|
||||
|
||||
# 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 `PictureLossIndication`s, 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
|
||||
|
||||
```bash
|
||||
$ cargo build -p wzp-relay
|
||||
Finished `dev` profile [unoptimized + debuginfo] target(s) in 13.12s
|
||||
```
|
||||
|
||||
```bash
|
||||
$ cargo test -p wzp-relay
|
||||
test result: ok. 20 passed; 0 failed
|
||||
```
|
||||
|
||||
```bash
|
||||
$ cargo test --workspace --exclude wzp-video
|
||||
# 656 tests passed
|
||||
```
|
||||
|
||||
```bash
|
||||
$ 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)
|
||||
|
||||
- [x] Code matches PRD intent — PLI dedup window per `(room, sender, stream_id)`, 200 ms, with per-sender forwarding via `stream_owner` map
|
||||
- [x] 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
|
||||
- [x] No backward-incompat surprises — `should_forward_pli` signature changed, only one production caller, updated
|
||||
- [x] Tests cover the new behavior — 6 unit tests covering the dedup window from both sides + cross-stream / cross-room independence + missing-owner
|
||||
- [x] 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.
|
||||
Reference in New Issue
Block a user