diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 038e0e4..4823174 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -59,6 +59,7 @@ graph TD
FEC["wzp-fec
RaptorQ FEC"]
CRYPTO["wzp-crypto
ChaCha20 + Identity"]
TRANSPORT["wzp-transport
QUIC / Quinn"]
+ VIDEO["wzp-video
H.264 + H.265 + AV1"]
RELAY["wzp-relay
Relay Daemon"]
CLIENT["wzp-client
CLI + Call Engine"]
@@ -68,16 +69,19 @@ graph TD
PROTO --> FEC
PROTO --> CRYPTO
PROTO --> TRANSPORT
+ PROTO --> VIDEO
CODEC --> CLIENT
FEC --> CLIENT
CRYPTO --> CLIENT
TRANSPORT --> CLIENT
+ VIDEO --> CLIENT
CODEC --> RELAY
FEC --> RELAY
CRYPTO --> RELAY
TRANSPORT --> RELAY
+ VIDEO --> RELAY
CLIENT --> WEB
TRANSPORT --> WEB
@@ -90,9 +94,10 @@ graph TD
style CLIENT fill:#00b894,color:#fff
style WEB fill:#0984e3,color:#fff
style FC fill:#fd79a8,color:#fff
+ style VIDEO fill:#a29bfe,color:#fff
```
-**Star pattern**: Each leaf crate (`wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`) depends only on `wzp-proto`. No leaf depends on another leaf. Integration crates (`wzp-relay`, `wzp-client`, `wzp-web`) depend on all leaves.
+**Star pattern**: Each leaf crate (`wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`, `wzp-video`) depends only on `wzp-proto`. No leaf depends on another leaf. Integration crates (`wzp-relay`, `wzp-client`, `wzp-web`) depend on all leaves.
## Audio Encode Pipeline
@@ -106,7 +111,7 @@ sequenceDiagram
participant DT as DredTuner
(wzp-proto)
participant FEC as RaptorQ FEC
participant INT as Interleaver
(depth=3)
- participant HDR as MediaHeader
(12B or Mini 4B)
+ participant HDR as MediaHeader
(16B or Mini 5B)
participant Enc as ChaCha20-Poly1305
participant QUIC as QUIC Datagram
participant QPS as QuinnPathSnapshot
@@ -144,7 +149,7 @@ sequenceDiagram
- RNNoise processes **2 x 480** samples (ML-based noise suppression via nnnoiseless)
- Silence detection uses VAD + 100ms hangover before switching to ComfortNoise
- FEC symbols are padded to **256 bytes** with a 2-byte LE length prefix
-- MiniHeaders (4 bytes) replace full headers (12 bytes) for 49 of every 50 frames
+- MiniHeaders (5 bytes) replace full headers (16 bytes) for 49 of every 50 audio frames; video always uses full headers
- DRED tuner polls quinn path stats every 25 frames (~500ms) and adjusts DRED lookback duration continuously
- Opus tiers bypass RaptorQ entirely -- DRED handles loss recovery at the codec layer
- Opus6k DRED window: 1040ms (maximum libopus allows)
@@ -324,35 +329,29 @@ sequenceDiagram
## Wire Formats
-### MediaHeader (12 bytes)
+### `MediaHeader` v2 (16 bytes, byte-aligned)
```
-Byte 0: [V:1][T:1][CodecID:4][Q:1][FecRatioHi:1]
-Byte 1: [FecRatioLo:6][unused:2]
-Bytes 2-3: sequence (u16 BE)
-Bytes 4-7: timestamp_ms (u32 BE)
-Byte 8: fec_block_id (u8)
-Byte 9: fec_symbol_idx (u8)
-Byte 10: reserved
-Byte 11: csrc_count
+Byte 0: version (u8) 0x02
+Byte 1: flags (u8) [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
+ T = FEC repair, Q = QualityReport trailer
+ KeyFrame = packet belongs to an I-frame (video)
+ FrameEnd = last packet of an access unit (video)
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8) widened from 4-bit (room for 256 codec IDs)
+Byte 4: stream_id (u8) simulcast layer; 0=base
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE) wrapping packet sequence number
+Bytes 10-13: timestamp_ms (u32 BE) milliseconds since session start
+Bytes 14-15: fec_block_id (u16 BE)
+ audio: low 8 bits = block_id, high 8 bits = symbol_idx
+ video: full u16 block_id (large blocks for I-frames)
```
-| Field | Bits | Description |
-|-------|------|-------------|
-| V (version) | 1 | Protocol version (0 = v1) |
-| T (is_repair) | 1 | 1 = FEC repair packet, 0 = source media |
-| CodecID | 4 | Codec identifier (0-8, see table below) |
-| Q | 1 | 1 = QualityReport trailer appended |
-| FecRatio | 7 | FEC ratio encoded as 0-127 mapping to 0.0-2.0 |
-| sequence | 16 | Wrapping packet sequence number |
-| timestamp_ms | 32 | Milliseconds since session start |
-| fec_block_id | 8 | FEC source block ID (wrapping) |
-| fec_symbol_idx | 8 | Symbol index within FEC block |
-| reserved | 8 | Reserved flags |
-| csrc_count | 8 | Contributing source count (future mixing) |
-
#### CodecID Values
+**Audio codecs (media_type = 0)**
+
| Value | Codec | Bitrate | Sample Rate | Frame Duration |
|-------|-------|---------|-------------|---------------|
| 0 | Opus 24k | 24 kbps | 48 kHz | 20ms |
@@ -365,15 +364,25 @@ Byte 11: csrc_count
| 7 | Opus 48k | 48 kbps | 48 kHz | 20ms |
| 8 | Opus 64k | 64 kbps | 48 kHz | 20ms |
-### MiniHeader (4 bytes, compressed)
+**Video codecs (media_type = 1)**
+
+| Value | Codec | Notes |
+|-------|-------|-------|
+| 9 | H.264 Baseline | Universal HW encode coverage |
+| 10 | H.264 Main | Slight quality win over baseline |
+| 11 | H.265 Main | Apple A10+, Snapdragon ~2017, NVENC GTX 9xx+; ~30% better than H.264 |
+| 12 | AV1 Main | Apple M3/A17+, Snapdragon 8 Gen 3+, RTX 40+; best efficiency, narrow HW |
+
+### `MiniHeader` v2 (5 bytes)
```
-[FRAME_TYPE_MINI: 0x01]
-Bytes 0-1: timestamp_delta_ms (u16 BE)
-Bytes 2-3: payload_len (u16 BE)
+[FRAME_TYPE_MINI = 0x01]
+Byte 0: seq_delta (u8) delta from last full header's seq
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
```
-Used for 49 of every 50 frames (~1s cycle). Saves 8 bytes per packet (67% header reduction). Full header is sent every 50th frame to resynchronize state.
+Used for audio only (49 of every 50 frames). Saves 11 bytes per audio packet vs the full 16B header. Full header is sent every 50th frame to resynchronize state. Video always uses full 16B headers.
### TrunkFrame (batched datagrams)
@@ -482,9 +491,12 @@ sequenceDiagram
### Shared State & Locking
+The `RoomManager` stores `DashMap>>`. The DashMap guard is held only long enough to clone the `Arc`; all per-room operations then acquire the room-level `RwLock`. Concurrent fan-out calls share a read lock; join/leave acquire write lock.
+
| Lock | Protected Data | Hold Duration | Contention |
|------|---------------|---------------|------------|
-| `RoomManager` (Mutex) | Rooms, participants, quality tiers | ~1ms/packet | O(N) per room |
+| `DashMap>>` | Room registry | Instant (clone Arc only) | Near-zero |
+| `Room` (RwLock) | Participants, quality tiers | ~1ms/packet (read); ~1ms (write on join/leave) | Low (concurrent reads) |
| `PresenceRegistry` (Mutex) | Fingerprint registrations | ~1ms | Low (join/leave only) |
| `SessionManager` (Mutex) | Active session tracking | ~1ms | Low |
| `FederationManager.peer_links` (Mutex) | Peer connections | ~10ms during forward | Per-federation-packet |
@@ -492,15 +504,9 @@ sequenceDiagram
### Scaling Characteristics
- **Many small rooms**: Scales well across all cores (rooms are independent)
-- **Large single room (100+ participants)**: Serialized by RoomManager lock
+- **Large single room (100+ participants)**: Fan-out reads share RwLock (non-blocking); only join/leave serializes
- **Federation**: Per-peer tasks scale; `peer_links` lock held during send loop
-### Primary Bottleneck
-
-The RoomManager Mutex is acquired per-packet by every participant to get the fan-out peer list. Lock is released before I/O (sends happen outside lock), but packet processing is serialized through the lock within a room.
-
-Future optimization: per-room locks or lock-free participant lists via `DashMap`.
-
## Client Architecture
### Desktop Engine (Tauri)
@@ -553,6 +559,8 @@ Key design decisions:
### Android Engine (Kotlin + JNI)
+> **Note (2026-05-12):** The Kotlin+JNI Android app (`android/app/`) described below is superseded by the **Tauri 2.x mobile build** (`desktop/src-tauri/` + `crates/wzp-native/`). The Tauri approach uses the same Rust call engine as desktop, with Oboe audio via `wzp-native` cdylib. The Kotlin codebase is maintained for reference but the Tauri build is the live production app.
+
```mermaid
graph TB
subgraph "Compose UI"
@@ -902,6 +910,20 @@ warzonePhone/
│ │ └── rekey.rs # Forward secrecy rekeying
│ ├── wzp-transport/ # QUIC transport layer
│ │ └── src/lib.rs # QuinnTransport, send/recv media/signal/trunk
+│ ├── wzp-video/ # Video codecs + framer
+│ │ └── src/
+│ │ ├── factory.rs # VideoEncoder factory (platform dispatch)
+│ │ ├── framer.rs # NAL fragmentation (H.264/H.265)
+│ │ ├── depacketizer.rs # NAL reassembly, access unit emit
+│ │ ├── controller.rs # VideoQualityController
+│ │ ├── simulcast.rs # Simulcast layer management
+│ │ ├── encoder_mode.rs # Encoder mode selection
+│ │ ├── av1_obu.rs # AV1 OBU framing + depacketizer
+│ │ ├── dav1d.rs # dav1d AV1 software decoder
+│ │ ├── svt_av1.rs # SVT-AV1 software encoder (non-Android)
+│ │ ├── videotoolbox.rs # VideoToolbox H.265 + AV1 (macOS)
+│ │ ├── mediacodec.rs # MediaCodec H.264/H.265/AV1 (Android, NDK 0.9 migration pending)
+│ │ └── nack.rs # NACK sender/receiver framework
│ ├── wzp-relay/ # Relay daemon
│ │ └── src/
│ │ ├── main.rs # CLI, connection loop, auth + handshake
@@ -917,6 +939,10 @@ warzonePhone/
│ │ ├── presence.rs # PresenceRegistry
│ │ ├── route.rs # RouteResolver
│ │ ├── trunk.rs # TrunkBatcher
+│ │ ├── audio_scorer.rs # Per-stream audio quality scoring
+│ │ ├── response_policy.rs # Relay response policy (rate-limit, drop)
+│ │ ├── verdict.rs # Verdict enum (Allow/RateLimit/Drop/Malicious)
+│ │ ├── video_scorer.rs # VideoScorer (legitimacy scoring, keyframe regularity)
│ │ └── ws.rs # WebSocket handler for browser clients
│ ├── wzp-client/ # Call engine + CLI
│ │ └── src/
@@ -956,7 +982,7 @@ warzonePhone/
## Test Coverage
-571 tests across all crates, 0 failures:
+702 tests across all crates (excluding wzp-android), 0 failures:
| Crate | Tests | Key Coverage |
|-------|-------|-------------|
@@ -965,7 +991,8 @@ warzonePhone/
| wzp-fec | 21 | RaptorQ encode/decode, loss recovery, interleaving |
| wzp-crypto | 64 | Encrypt/decrypt, handshake, anti-replay, featherChat identity |
| wzp-transport | 11 | QUIC connection setup, path monitoring |
-| wzp-relay | 122 | Room ACL, session mgmt, metrics, probes, mesh, trunking |
+| wzp-relay | 137 | Room ACL, session mgmt, metrics, probes, mesh, trunking, scoring, verdict |
+| wzp-video | 88 | NAL framing, AV1 OBU, simulcast, quality controller, NACK |
| wzp-client | 170 | Encoder/decoder, quality adapter, silence, drift, sweep |
| wzp-web | 2 | Metrics |
| wzp-native | 0 | Native platform bindings (no unit tests) |
diff --git a/docs/AUDIT-2026-05-25.md b/docs/AUDIT-2026-05-25.md
new file mode 100644
index 0000000..8c8ff03
--- /dev/null
+++ b/docs/AUDIT-2026-05-25.md
@@ -0,0 +1,231 @@
+# WarzonePhone Protocol Audit — 2026-05-25
+
+**Auditor:** Claude Sonnet 4.6 (assisted)
+**Branch:** `experimental-ui` @ `f3e3ee5`
+**Scope:** All workspace crates (`wzp-proto`, `wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`, `wzp-relay`, `wzp-client`, `wzp-android`, `wzp-native`, `wzp-video`)
+**Test baseline:** 702 passing (excludes `wzp-android`)
+
+---
+
+## Executive Summary
+
+The audio call path is functionally correct and cryptographically sound on clean network paths. **There is a session-breaking bug in the crypto nonce derivation (C1) that will cause a permanent decryption failure on any out-of-order UDP delivery.** This is the single highest-priority fix — it will manifest as periodic session crashes under normal internet conditions. Video has a solid architectural foundation but three hard blockers remain before shipping: the AEAD coverage gap (C2), dead video scorer (C3), and Android MediaCodec compile failure (C4).
+
+The project is in good shape overall. The crypto design (X25519, HKDF, ChaCha20-Poly1305, Ed25519 identity, SAS verification) is sound. The SFU-never-decrypts architecture is rare and valuable. The codec adaptation (Opus DRED + Codec2 RaptorQ split) is genuinely innovative. The eight issues below are fixable in ~12 engineer-hours.
+
+---
+
+## Critical
+
+### C1 — Nonce derives from `recv_seq` counter, not `MediaHeader.seq`
+
+**File:** `crates/wzp-crypto/src/session.rs:132`
+**Severity:** Critical — session-breaking on any packet reorder
+
+```rust
+// decrypt()
+let nonce_bytes = nonce::build_nonce(&self.session_id, self.recv_seq, Direction::Send);
+// ...
+self.recv_seq = self.recv_seq.wrapping_add(1); // line 148
+```
+
+`recv_seq` increments once per successful `decrypt()` call. The sender's `send_seq` also increments once per `encrypt()` call (line 120). In perfect in-order delivery they stay synchronized. With any reorder or mid-stream packet loss they permanently diverge. Once diverged, every subsequent packet uses the wrong nonce → AEAD tag mismatch → every packet fails for the rest of the session.
+
+This isn't a low-probability edge case. UDP over any internet path reorders packets routinely. The `multiple_packets_roundtrip` test (line 254) only exercises in-order delivery. HANDOFF-2026-05-12.md acknowledges this as a known latent item: *"AEAD nonce derivation: switch to `MediaHeader::seq`"*.
+
+The anti-replay check at lines 152–161 already parses `MediaHeader` and has `header.seq` available. The fix is one line in `decrypt()`:
+
+```rust
+// Use sender's wire-level seq as nonce input, not a local counter.
+// This survives reordering because both sides derive the same nonce from
+// the same field. recv_seq was wrong: it diverged from send_seq on any
+// reorder, breaking all subsequent decryptions for the session.
+let header = parse_header(header_bytes)
+ .ok_or_else(|| CryptoError::Internal("header parse failed".into()))?;
+let nonce_bytes = nonce::build_nonce(&self.session_id, header.seq, Direction::Send);
+```
+
+Remove `recv_seq` field from `ChaChaSession` (it's now redundant — anti-replay uses `header.seq` directly). On the encrypt side, verify that `self.send_seq` equals the `seq` written into the `MediaHeader` at the call site.
+
+**Estimated effort:** ~1 hour including test coverage for out-of-order delivery.
+
+> **Note on rekey seq reset:** The agent initially flagged `send_seq/recv_seq = 0` in `complete_rekey()` as a separate critical issue. This is a false positive — `install_key()` rotates `session_id` (hash of new key), so pre-/post-rekey nonces live in distinct namespaces. The reset is intentional and cryptographically safe.
+
+---
+
+### C2 — AEAD not wired to every QUIC datagram send path
+
+**File:** `crates/wzp-client/src/analyzer.rs:363` (only confirmed decrypt call site)
+**Severity:** Critical — potential plaintext media leakage
+
+The HANDOFF document explicitly flags this: *"Encryption is implemented in `wzp-crypto` but not yet on every QUIC datagram path."* The `analyzer.rs` path decrypts inbound packets. What needs verification: every outbound `send_datagram()` / `write_datagram()` call across `wzp-client` and `wzp-transport` must pass through `ChaChaSession::encrypt()`.
+
+**Required action:** Grep every `send_datagram` call site. Confirm each path encrypts before transmit. Add a CI-level test or `#[forbid(dead_code)]`-style assertion that makes a plaintext send path impossible to merge. Until this is verified, the E2E security claim cannot be made.
+
+**Estimated effort:** ~1 hour audit + test.
+
+---
+
+### C3 — `VideoScorer::observe()` never called — scorer is dead code
+
+**File:** `crates/wzp-relay/src/room.rs:1263–1266`
+**Severity:** Critical — relay abuse control for video is completely absent
+
+```rust
+// T6.2-follow-up: feed video packets to VideoScorer here.
+// video_scorer.observe(&pkt.header, pkt.payload.len(), now, bwe_kbps);
+```
+
+`video_scorer.rs` was delivered in T6.2 with legitimacy scoring, keyframe regularity checks, I/P ratio analysis, and a verdict enum. The observe call was never wired into the packet forwarding loop. The scorer compiles but accumulates no data. Any participant can flood the room with malformed video or synthetic keyframe bursts and the relay will forward everything without challenge.
+
+**Fix:** Wire `video_scorer.observe(...)` at the TODO marker and integrate `legitimacy_score()` into the forwarding decision (drop or rate-limit streams with `Verdict::Malicious`). Add an integration test: synthetic high-frequency keyframe bursts should trigger a `Malicious` verdict within 2 seconds.
+
+**Estimated effort:** ~2 hours.
+
+---
+
+### C4 — `wzp-video` Android target fails to compile (31 errors)
+
+**File:** `crates/wzp-video/src/mediacodec.rs`
+**Severity:** Critical — Android video is completely blocked
+
+Five error categories from the NDK 0.9 API migration, all documented in HANDOFF-2026-05-12.md. `dav1d`/`svt-av1` were cfg-gated off Android in `f3e3ee5`; these 31 errors are the remaining MediaCodec API mismatch.
+
+| Error | Count | Root cause | Fix |
+|---|---|---|---|
+| `E0277` `NonNull` not `Send` | ~3 | Raw pointer held across `tokio::spawn` boundary | `struct SendMediaCodec(NonNull<…>); unsafe impl Send for SendMediaCodec {}` — or use `ndk::media::MediaCodec` owned type (already `Send`) |
+| `E0308` `&[MaybeUninit]` vs `&[u8]` | many | NDK 0.9 returns uninit slices | `MaybeUninit::write_slice` or transmute pattern |
+| `E0425` missing `BITRATE_MODE_CBR` | 1+ | Constant renamed in NDK 0.9 | Check `ndk` crate docs for current name |
+| `E0433` `ndk_sys` not a dep | several | Direct `ndk_sys` import; only `ndk = "0.9"` declared | Add `ndk-sys` as explicit dep or use safe `ndk` wrappers |
+| `E0599` `InputBuffer::index()` / `OutputBuffer::index()` private | 2 | API changed in NDK 0.9 | Use buffer through safe queue/dequeue API |
+
+Nothing live is blocked today — `wzp-video` is not yet consumed by Tauri Android. But video on Android cannot progress until this compiles.
+
+**Reproduce:**
+```bash
+ssh -i ~/CascadeProjects/wzp manwe@manwehs \
+ 'cd ~/wzp-builder/data/source && \
+ docker run --rm \
+ -v ~/wzp-builder/data/source:/build/source \
+ -v ~/wzp-builder/data/cache/cargo-registry:/home/builder/.cargo/registry \
+ -v ~/wzp-builder/data/cache/cargo-git:/home/builder/.cargo/git \
+ -v ~/wzp-builder/data/cache/target:/build/source/target \
+ wzp-android-builder:latest \
+ bash -c "cd /build/source && cargo build --target aarch64-linux-android -p wzp-video 2>&1 | tail -60"'
+```
+
+**Estimated effort:** ~2 hours (one commit per error category).
+
+---
+
+## High
+
+### H1 — AV1 call engine wiring missing
+
+**Source:** HANDOFF-2026-05-12.md (T6.1.2 open item)
+**File:** `crates/wzp-video/src/factory.rs`
+
+`factory.rs` and step tables landed in commit `086d0a4`. No caller yet invokes `create_video_encoder(Av1Main, ...)`. The entire AV1 path is reachable only from tests. Video on macOS/Linux desktop requires wiring `create_video_encoder` into the call engine's media negotiation path.
+
+**Estimated effort:** ~1–2 hours.
+
+---
+
+### H2 — `fec_block_id: u8` wraps every ~25 seconds
+
+**File:** `crates/wzp-fec/src/encoder.rs` (`block_id.wrapping_add(1)` on u8)
+**Reference:** PROTOCOL-AUDIT.md W2 (deferred P2)
+
+At 5 frames/block (Codec2), u8 ID wraps at block 256 ≈ 25 seconds. A slow reconstructor or late-joining peer will collide block IDs with in-flight blocks. The window distance check in `block_manager.rs` partially mitigates this but can't prevent all collisions. Widen to `u16` in the next wire-format revision.
+
+---
+
+## Medium
+
+### M1 — `SignalMessage` has no version byte
+
+**File:** `crates/wzp-proto/src/session.rs` (SignalMessage enum)
+**Reference:** PROTOCOL-AUDIT.md W12
+
+`bincode + serde(default)` handles field additions but not variant removal or semantic changes. Any variant deprecation is silent at the wire level. This becomes a correctness risk when federation routes `SignalMessage`s across relay versions. Add `version: u8` as a leading field to all variants before federation ships.
+
+---
+
+### M2 — BWE not consumed by `AdaptiveQualityController`
+
+**Reference:** PROTOCOL-AUDIT.md W6, deferred to Phase V2
+
+Quinn exposes `cwnd` and `bytes_in_flight`, but `AdaptiveQualityController` does not consume them. Loss + RTT adaptation works for audio. For video, without bandwidth estimation the encoder cannot detect available uplink capacity and will either oscillate or permanently under-utilize bandwidth. Mandatory before video production.
+
+---
+
+### M3 — PLI suppression window hardcoded at 200ms
+
+**File:** `crates/wzp-relay/src/room.rs:1060`
+
+Not adaptive to link speed. On slow links 200ms may allow multiple keyframe requests. Accept for Phase 1; make configurable in Phase 2.
+
+---
+
+### M4 — Repair packet index wrapping in FEC encoder
+
+**File:** `crates/wzp-fec/src/encoder.rs:140`
+
+```rust
+let idx = (num_source as u8).wrapping_add(i as u8);
+```
+
+If `num_source + repair_count > 255`, indices wrap silently. In practice bounded by `frames_per_block` (5–10), so max sum is ~20. Low risk today; widen to u16 when `fec_block_id` is widened (H2).
+
+---
+
+### M5 — `timestamp_ms` monotonicity after rekey not enforced
+
+**Reference:** PROTOCOL-AUDIT.md W3
+
+Spec: `timestamp_ms` must not reset on rekey. The code correctly does not reset it, but there is no assertion to prevent regression. Add a debug assert in `complete_rekey()` that `new_session.next_timestamp >= old_session.last_timestamp`.
+
+---
+
+## Low / Accepted Debt
+
+| ID | Description | File | Accepted in |
+|---|---|---|---|
+| L1 | 9 pre-existing clippy lints in `wzp-codec` | `aec.rs`, `denoise.rs`, `opus_enc.rs`, `codec2_{enc,dec}.rs`, `resample.rs` | PROTOCOL-AUDIT.md |
+| L2 | 3 clippy errors in `deps/featherchat` submodule | `ratchet.rs`, `types.rs` | PROTOCOL-AUDIT.md |
+| L3 | Audio anti-replay window 64 packets | `wzp-crypto/src/session.rs:89` | Accepted — jitter buffer + PLC masks loss |
+| L4 | Debug tap logs at INFO with no rate limiting | `wzp-relay/src/room.rs:46–59` | Safe in dev; add 1:100 sampling for prod |
+
+---
+
+## What Was Not Found
+
+These are explicitly confirmed sound after code-level verification:
+
+- **Anti-replay bitmap** — correct u32 wrapping, per-stream isolation, window sizing by `MediaType`
+- **HKDF + X25519 + Ed25519 key agreement** — standard construction, no gaps
+- **SAS code derivation** — SHA-256(shared_secret)[:4] as 4-digit voice verification code
+- **Rekey forward secrecy** — `session_id` rotation on rekey isolates nonce namespaces; seq counter reset is intentional and safe
+- **MiniHeader v2 `seq_delta`** — fully implemented at `wzp-proto/src/packet.rs:469–526` with tests; PROTOCOL-AUDIT resolution table is accurate
+- **SFU E2E preservation** — relay ciphertext passthrough, no plaintext access
+- **RaptorQ for Codec2** — correct tool for the bitrate regime
+- **DRED continuous tuning** — better than discrete tiers; 15% loss floor is empirically grounded
+- **Jitter buffer** — BTreeMap with wrapping-aware comparisons, EWMA adaptive playout delay, solid
+- **Quinn QUIC datagram transport** — correct primitives for unreliable media
+
+---
+
+## Fix Priority Table
+
+| # | Issue | Category | Effort | Blocks |
+|---|---|---|---|---|
+| 1 | C1: nonce → `MediaHeader.seq` | Crypto | 1h | All sessions on lossy paths |
+| 2 | C2: verify AEAD on all datagram send paths | Crypto | 1h | E2E security claim |
+| 3 | C3: wire `VideoScorer::observe()` into room | Relay | 2h | Relay abuse control for video |
+| 4 | C4: NDK 0.9 `mediacodec.rs` migration (5 categories) | Android | 2h | Android video |
+| 5 | H1: wire AV1 factory into call engine | Video | 2h | Desktop video |
+| 6 | H2: widen `fec_block_id` to `u16` | FEC/Wire | 30min | Next protocol release |
+| 7 | M1: `SignalMessage` version byte | Proto | 1h | Federation correctness |
+| 8 | M2: BWE into `AdaptiveQualityController` | Transport | 2–3 days | Video production quality |
+
+**Total for C1–H1 (items 1–5):** ~8 hours focused engineering.
diff --git a/docs/HANDOFF-2026-05-12.md b/docs/HANDOFF-2026-05-12.md
new file mode 100644
index 0000000..5b6ccee
--- /dev/null
+++ b/docs/HANDOFF-2026-05-12.md
@@ -0,0 +1,166 @@
+# Handoff — 2026-05-12 EOD
+
+## TL;DR
+
+Wave 5 (Phase 5) and Wave 6 (Phase 6) implementation is complete and approved on the board. Stopping for the night with one open issue: `wzp-video` does not target-compile for `aarch64-linux-android` and needs a focused `ndk = "0.9"` API migration session (~1–2 h). Nothing live is blocked — Tauri Android does not yet consume `wzp-video`.
+
+**Branch state:** local `experimental-ui` HEAD `f3e3ee5`, pushed to `github` only. **Not yet on `fj`** (deploy key was read-only). Build server (`manwe@manwehs`) is up to date via github fetch.
+
+---
+
+## What landed today
+
+| Wave | Tasks approved | New crates / files | Test delta |
+|---|---|---|---|
+| 5 | T5.1, T5.1.1, T5.2, T5.3, T5.4, T5.5, T5.6, T5.7, T5.7.1, T5.8 | `crates/wzp-relay/src/audio_scorer.rs`, `response_policy.rs`, `verdict.rs`; `wzp-video/src/controller.rs`, `simulcast.rs`, `encoder_mode.rs`; H.265 path in VT + MediaCodec | wzp-relay 99→127, wzp-video 43→71 |
+| 6 | T6.1 (+ rework), T6.1.2, T6.2 | `wzp-video/src/av1_obu.rs`, `dav1d.rs`, `svt_av1.rs`, `factory.rs`; VT AV1 decoder; MediaCodec AV1; `wzp-relay/src/video_scorer.rs` | wzp-video 76→88, wzp-relay 127→137 |
+
+Total: ~30 task units approved across the two waves. Workspace tests at 702 passing (excluding `wzp-android`).
+
+---
+
+## Open / next-up
+
+### Top of queue
+
+- **T4.3.1.1 (deferred → in-progress, blocked)** — Android target-compile of `wzp-video`. We started this tonight and hit 31 errors in `crates/wzp-video/src/mediacodec.rs` against the actual `ndk = "0.9"` API. Error categories captured below; resume with one fix-per-category commit, then attempt device instrumentation.
+- **T6.3 — federated reputation gossip.** Design exploration committed (`1e729e4`, `docs/PRD/PRD-relay-federation-gossip.md`). **Decision made: Approach 3 (Ban-List Distribution).** My answers to the 6 blocker questions are in the chat thread, awaiting conversion to a real Files/Steps/Verify/Done-when task spec for the agent. The user opted not to run the agent immediately; the task spec is a write-then-park.
+- **T5.1.1 follow-ups** — none. T5.1.1 closed clean.
+
+### Latent follow-ups from earlier waves
+
+These pre-date wave 6 and are still open:
+
+- **AEAD wired into prod send/recv path** (referenced in T1.5 / T1.6 reports). Encryption is implemented in `wzp-crypto` but not yet on every QUIC datagram path.
+- **AEAD nonce derivation: switch to `MediaHeader::seq`** (cited in T1.5.x reports). Current scheme works but isn't tied to wire-level seq.
+- **`wzp-codec` clippy debt sprint** — 9 errors documented as known debt in `docs/PROTOCOL-AUDIT.md`.
+- **T6.1.2 — wire AV1 into actual call engine.** The factory + step tables landed (commit `086d0a4`); no caller invokes `create_video_encoder(Av1Main, …)` yet. Real video sender wiring (the originally-blocked task) is unstarted.
+- **T6.2-follow-up — wire `VideoScorer::observe()` into the packet path.** TODO marker at `crates/wzp-relay/src/room.rs:1263`.
+
+### Permanently deferred
+
+- **T6.1.1 — Android MediaCodec AV1 device validation.** Deferred indefinitely: the user does not own an AV1-encode-capable Android or iPhone, and AV1 hardware will not be widespread for years. Revisit when devices land.
+
+---
+
+## The T4.3.1.1 Android build situation
+
+What we did tonight:
+
+1. Pushed `experimental-ui` to `github` (deploy key on `fj` is read-only).
+2. Added `github` as a remote on `manwe@manwehs:~/wzp-builder/data/source/` and checked out `experimental-ui`.
+3. Ran `cargo build --target aarch64-linux-android -p wzp-video` inside the `wzp-android-builder:latest` docker image.
+4. First failure: `shiguredo_dav1d` and `shiguredo_svt_av1` build scripts panic with `unsupported target: os=android, arch=aarch64`. Fixed in commit `f3e3ee5` (`fix(wzp-video): cfg-gate dav1d + svt-av1 off Android target`) — those crates now live under `[target.'cfg(not(target_os = "android"))'.dependencies]`, since Android uses MediaCodec for AV1 anyway.
+5. Re-ran the build → 31 errors in `mediacodec.rs`. **Stopped here.**
+
+### Error categories to fix tomorrow
+
+Run the same docker invocation and tackle these one fix-commit per category:
+
+| Error | Count | Root cause | Likely fix |
+|---|---|---|---|
+| `E0277` `NonNull` not `Send` | ~3 | Raw pointer field on a struct held across `tokio::spawn`-able boundaries | Wrap in `struct SendMediaCodec(NonNull<…>); unsafe impl Send for SendMediaCodec {}` or use the `ndk` crate's owned `MediaCodec` type which already implements `Send` |
+| `E0308` `&[MaybeUninit]` vs `&[u8]` | many | `ndk 0.9` returns uninitialized buffer slices; agent wrote into them as if initialized | Use `MaybeUninit::write_slice` or transmute pattern; pattern matches what `InputBuffer::write` expects |
+| `E0425` missing `BITRATE_MODE_CBR` | 1+ | Constant moved/renamed in `ndk 0.9` | Search `ndk` crate docs for current constant name (likely under `MediaCodec::set_parameters` enum) |
+| `E0433` `ndk_sys` not linked | several | Agent imported `ndk_sys` directly; it's not a dep, only `ndk = "0.9"` is | Replace direct `ndk_sys` calls with safe wrappers from the `ndk` crate, or add `ndk_sys` as an explicit dep |
+| `E0599` `InputBuffer::index()` / `OutputBuffer::index()` private | 2 | Both are private fields in `ndk 0.9`; were public methods in older versions | Either use the buffer through its safe API (queue/dequeue by handle) or expose index via a different accessor — read the `ndk` source for current API |
+
+### Reproduce the build
+
+```bash
+ssh -i ~/CascadeProjects/wzp manwe@manwehs \
+ 'cd ~/wzp-builder/data/source && \
+ docker run --rm \
+ -v ~/wzp-builder/data/source:/build/source \
+ -v ~/wzp-builder/data/cache/cargo-registry:/home/builder/.cargo/registry \
+ -v ~/wzp-builder/data/cache/cargo-git:/home/builder/.cargo/git \
+ -v ~/wzp-builder/data/cache/target:/build/source/target \
+ wzp-android-builder:latest \
+ bash -c "cd /build/source && cargo build --target aarch64-linux-android -p wzp-video 2>&1 | tail -100"'
+```
+
+After local fixes:
+
+```bash
+git push github experimental-ui && \
+ssh -i ~/CascadeProjects/wzp manwe@manwehs \
+ 'cd ~/wzp-builder/data/source && git fetch github && git reset --hard github/experimental-ui'
+# then re-run the docker build
+```
+
+### Device instrumentation half (post-compile)
+
+User has a physical Android device. Once `cargo build --target aarch64-linux-android -p wzp-video` is clean:
+
+- Build a minimal test harness binary (probably under `wzp-video/examples/` or a new `wzp-android-test/` crate) that does encode → decode of a synthetic frame via MediaCodec.
+- Use `adb push` and `adb shell run` to exercise it.
+- Compare output bytes against the dav1d/SVT-AV1 SW roundtrip from `crates/wzp-video/src/svt_av1.rs:101 svt_av1_dav1d_roundtrip_10_frames`.
+
+Out of scope for tomorrow if the API migration eats the whole session.
+
+---
+
+## T6.3 — Approach 3 decision
+
+User picked Approach 3 (Ban-List Distribution) from `docs/PRD/PRD-relay-federation-gossip.md`. My answers to the 6 open questions:
+
+1. **Trust model:** Single admin key (user). Strongest Sybil resistance, lowest complexity.
+2. **Key infra:** Reuse `wzp-crypto` Ed25519. Admin pubkey in relay config; relays verify list signatures.
+3. **Fingerprint scope:** Ed25519 pubkey, not IP. Resistant to NAT rebind evasion.
+4. **Privacy:** Publish `SHA-256(pubkey)` hashes, not raw pubkeys. Relays compute `H(observed)` and match. 256-bit space makes brute-force infeasible; loses some audit trail.
+5. **TTL:** 30-day per-entry auto-expiry. Forces ops to actively re-publish persistent bans; prevents forever-by-mistake.
+6. **Rate limiting:** N/A under Approach 3 (no gossip channel; relays poll a signed list at configurable interval, that interval is the rate limit).
+
+Next step: turn these into a Files/Steps/Verify/Done-when task spec in `docs/PRD/TASKS.md` and move T6.3 from `Blocked` → `Open` ready for the agent to claim. User did not want this kicked off tonight.
+
+---
+
+## Build / sync state
+
+| Location | Branch | HEAD |
+|---|---|---|
+| Local (Mac) | `experimental-ui` | `f3e3ee5 fix(wzp-video): cfg-gate dav1d + svt-av1 off Android target` |
+| `github` remote | `experimental-ui` | `f3e3ee5` (pushed) |
+| `fj` remote | `experimental-ui` | **not pushed** (deploy key read-only on `fj`) |
+| `origin` (git.manko.yoga) | `experimental-ui` | **not pushed** |
+| Build server `~/wzp-builder/data/source` | `experimental-ui` | `f3e3ee5` |
+
+If you want everything on `fj` / `origin` too, get the deploy key write-privileged or push from a different identity.
+
+`fj/main` and `github/main` have one commit (`9ae9441 fix(audio): check capture ring available...`) that doesn't exist on `experimental-ui` — a small audio fix from May 11. Cherry-pick or merge before merging `experimental-ui` back into `main`.
+
+### Gitleaks allowlist
+
+Added `.gitleaks.toml` in commit `f28f39d` to allowlist 4 pre-existing historical findings. Two are real tokens (paste.tbs.amn.gg and paste.dk.manko.yoga `Authorization` headers in `scripts/build*.sh`). **Rotate those tokens if those endpoints still authenticate** — the allowlist only silences the pre-push hook; the secrets are still in git history.
+
+---
+
+## Agent process notes for tomorrow
+
+The Kimi Code CLI agent on this project has a **stable, well-documented fabrication tic** — one verifiable detail per report is wrong (SHA, "updated X in same commit", fmt/clippy passes, etc.). Pattern survived an explicit CR on T6.1.
+
+**Updated policy** (in `memory/feedback_kimi_report_fabrication.md`):
+
+1. **Always verify the SHA** in the report header against `git log`.
+2. **Always run** `cargo fmt --check` and `cargo clippy -- -D warnings` yourself — don't trust the report's claims.
+3. **Don't CR fabrications anymore** — the T6.1 CR didn't change the behavior. Reviewer-fix the detail, note on the board, move on. Reserve CRs for substance issues.
+
+The substance of the code has been consistently good. Don't let the fabrication tic bias review of the code itself.
+
+### Rebase tic
+
+Agent has twice rewritten already-pushed commits to address CR feedback (T5.7.1 `d3b2da6` → `517d0eb`; T6.1 `0de9522` → `9334aa5`). Forward fix commits are the rule; rebasing wasn't asked for and breaks reviewer references. Mention this only if it happens a third time.
+
+---
+
+## Tomorrow's suggested checklist
+
+1. **(20 min)** Read this doc, the `feedback_kimi_report_fabrication.md` memory, and the T6.1 / T6.2 / T6.1.2 board rows on `docs/PRD/TASKS.md` to reload context.
+2. **(1–2 h)** Resume T4.3.1.1: ndk-0.9 API migration in `crates/wzp-video/src/mediacodec.rs`. One commit per error category.
+3. **(30 min)** If migration lands clean, attempt the minimal device test on the user's Android phone.
+4. **(20 min, optional)** Convert the T6.3 design answers into a task spec block in `TASKS.md`, leave it `Open` for the agent. Don't kick off the agent unless asked.
+5. **(parking lot)** AEAD prod wiring + nonce switch + wzp-codec clippy sprint — none urgent.
+
+---
+
+*Generated 2026-05-12, end of Wave 6 push.*
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index b2a4a6b..867a28c 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -389,3 +389,107 @@ Run with `wzp-bench --all`. Representative results (Apple M-series, single core)
- `RegisterPresenceAck` populates `relay_region` from config, `available_relays` from federation peers
- Desktop `place_call`/`answer_call` call `acquire_port_mapping()` and fill mapped addr fields
- Legacy `build-android-docker.sh` renamed to `build-android-docker-LEGACY.sh` to prevent accidental use
+
+## Wave 5: Video Infrastructure (2026-05-12)
+
+**Tasks completed:** T5.1, T5.1.1, T5.2, T5.3, T5.4, T5.5, T5.6, T5.7, T5.7.1, T5.8
+
+### Relay: Audio + Video Scoring
+
+New files in `crates/wzp-relay/src/`:
+
+- `audio_scorer.rs` — per-stream audio quality scorer tracking packet loss, codec consistency, bitrate stability
+- `response_policy.rs` — relay response policy engine mapping scores to action thresholds
+- `verdict.rs` — `Verdict` enum: `Allow`, `RateLimit`, `Drop`, `Malicious`
+- `video_scorer.rs` — `VideoScorer` with legitimacy scoring: keyframe regularity, I/P ratio, bandwidth responsiveness. **Note: wired but `observe()` not yet called from room forwarding path — T6.2 follow-up open.**
+
+### Video: H.265 + Quality Controller
+
+New files in `crates/wzp-video/src/`:
+
+- `controller.rs` — `VideoQualityController`: maps (bwe_bps, loss_pct, rtt_ms, priority_mode) to (target_bitrate, target_fps, target_resolution, simulcast_layer)
+- `simulcast.rs` — simulcast layer management (base + enhancement layers)
+- `encoder_mode.rs` — encoder mode selection (CBR/VBR, keyframe intervals, quality presets)
+
+H.265 encode/decode path added to:
+- `videotoolbox.rs` — VideoToolbox H.265 encoder + decoder (macOS/iOS)
+- `mediacodec.rs` — MediaCodec H.265 encoder + decoder (Android; NDK 0.9 compile errors pending in T4.3.1.1)
+
+**Test delta:** wzp-relay 99→127, wzp-video 43→71
+
+---
+
+## Wave 6: AV1 + Federation Gossip Design (2026-05-12)
+
+**Tasks completed:** T6.1, T6.1.2, T6.2
+
+### Video: AV1 Codec Support
+
+New files in `crates/wzp-video/src/`:
+
+- `av1_obu.rs` — AV1 OBU (Open Bitstream Unit) framing and depacketizer
+- `dav1d.rs` — dav1d AV1 software decoder (non-Android; gated via cfg)
+- `svt_av1.rs` — SVT-AV1 software encoder (non-Android; gated via cfg)
+
+Updated files:
+- `videotoolbox.rs` — VideoToolbox AV1 decoder + encoder (macOS M3+, iOS A17+)
+- `mediacodec.rs` — MediaCodec AV1 (Android; compile errors pending)
+- `factory.rs` — `create_video_encoder(codec, platform)` dispatcher added; H.264, H.265, AV1 wired
+
+**T6.1.2 follow-up open:** `create_video_encoder(Av1Main, ...)` has no caller in the call engine yet — wiring step is unstarted.
+
+### Relay: Federation Reputation Gossip (Design Phase)
+
+- T6.3 design exploration committed at `1e729e4`
+- `docs/PRD/PRD-relay-federation-gossip.md` — Ban-List Distribution approach selected (Approach 3)
+- Implementation not started; task spec pending conversion
+
+### Test Counts
+
+**Test delta Wave 6:** wzp-video 76→88, wzp-relay 127→137
+
+**Total workspace tests: 702** (excluding `wzp-android`)
+
+| Crate | Tests |
+|---|---|
+| wzp-proto | 112 |
+| wzp-codec | 69 |
+| wzp-fec | 21 |
+| wzp-crypto | 64 |
+| wzp-transport | 11 |
+| wzp-relay | 137 |
+| wzp-client | 200 |
+| wzp-video | 88 |
+| wzp-web | 2 |
+| wzp-native | 0 |
+
+---
+
+## Current Status (2026-05-25)
+
+### What Works (Audio)
+
+All audio path items from previous status section remain working. Additionally:
+
+- MediaHeader v2 (16 bytes) deployed across all paths
+- MiniHeader v2 (5 bytes with seq_delta) deployed
+- Anti-replay windows per stream with media-type-aware sizing (audio 64, video 1024)
+- Relay DashMap + RwLock concurrency model (T3.1 resolved the Mutex bottleneck)
+
+### What Works (Video — partial)
+
+- H.264 framer/depacketizer with FU-A fragmentation handling
+- H.264, H.265, AV1 VideoToolbox encode/decode (macOS)
+- AV1 dav1d + SVT-AV1 software path (non-Android)
+- Video quality controller, simulcast, encoder mode selection (controller only; no active call wiring yet)
+- Video scorer (scoring logic complete; not yet wired into relay forwarding)
+- NACK framework (`nack.rs`; not yet wired into room forwarding)
+
+### Open Blockers
+
+- **Android video:** `mediacodec.rs` has 31 NDK 0.9 compile errors (T4.3.1.1 in progress)
+- **AV1 call wiring:** `create_video_encoder(Av1Main, ...)` has no caller (T6.1.2 follow-up)
+- **VideoScorer wiring:** `VideoScorer::observe()` commented out at `room.rs:1263` (T6.2 follow-up)
+- **NACK wiring:** NACK path not wired into room forwarding (Phase V2/V4)
+- **BWE:** `AdaptiveQualityController` does not consume `cwnd`/`bytes_in_flight` (Phase V2)
+- **Crypto nonce bug:** `decrypt()` uses `recv_seq` instead of `MediaHeader.seq` (see AUDIT-2026-05-25.md C1)
diff --git a/docs/ROAD-TO-VIDEO.md b/docs/ROAD-TO-VIDEO.md
index 1ea1a08..d373eb9 100644
--- a/docs/ROAD-TO-VIDEO.md
+++ b/docs/ROAD-TO-VIDEO.md
@@ -12,6 +12,36 @@ The transport, crypto, session, federation, and SFU layers are codec-agnostic. T
4. Keyframe semantics (PLI, NACK, keyframe cache at SFU)
5. Capture / encode pipeline (VideoToolbox / MediaCodec / NVENC)
+## Implementation Status (as of 2026-05-25)
+
+| Phase | Description | Status |
+|---|---|---|
+| V1 — Wire format | 16B MediaHeader v2, 5B MiniHeader v2, MediaType, u32 seq, 8-bit CodecID | ✅ Complete (T1.x) |
+| V2 — Transport additions | BWE, NACK loop, TransportFeedback, dynamic FEC boost on I-frames | 🔲 Not started |
+| V3 — `wzp-video` crate | H.264 baseline framer/depacketizer, VideoToolbox/MediaCodec/dav1d encoders | ✅ Substantially complete (T4.x, T5.x, T6.x) |
+| V3 — H.264 Baseline | Single-layer H.264 | ✅ Complete |
+| V3 — H.265 | VideoToolbox + MediaCodec H.265 | ✅ Complete (T5.x) |
+| V3 — AV1 | dav1d + SVT-AV1 (non-Android), VideoToolbox AV1 (macOS M3+) | ✅ Complete; Android MediaCodec AV1 compile errors pending (T4.3.1.1) |
+| V3 — Android MediaCodec | NDK 0.9 API migration for `mediacodec.rs` | 🔴 Blocked (31 compile errors) |
+| V3 — Call engine wiring | `create_video_encoder()` integrated into active call negotiation | 🔴 Not started (T6.1.2 follow-up) |
+| V4 — Keyframe & loss policy | NACK path, PLI, keyframe cache at SFU | 🟡 Framework present (`nack.rs`); not wired |
+| V5 — Video adaptive controller | `VideoQualityController` + `PriorityMode` | 🟡 Controller built (`controller.rs`); not wired into call |
+| V5 — Simulcast | Simulcast layer management | 🟡 `simulcast.rs` present; not wired |
+| V6 — SFU changes | Keyframe cache, per-receiver layer selection, PLI suppression | 🟡 PLI suppression wired; keyframe cache + layer selection not started |
+| V6 — Video scorer | `VideoScorer` legitimacy detection | 🟡 Built (`video_scorer.rs`); `observe()` not wired into room forwarding |
+| V7 — Capture pipeline | Camera capture (AVCaptureSession, Camera2, NVENC) | 🔲 Not started |
+
+**Legend:** ✅ Complete · 🟡 Partial/Framework only · 🔴 Blocked · 🔲 Not started
+
+### Critical path to first video call
+
+1. Fix Android MediaCodec compile errors (T4.3.1.1) — ~2h
+2. Wire `create_video_encoder()` into call engine codec negotiation (T6.1.2) — ~2h
+3. Fix crypto nonce bug (`decrypt()` must use `MediaHeader.seq`) — see `AUDIT-2026-05-25.md` C1 — ~1h
+4. Wire `VideoScorer::observe()` into relay room forwarding (T6.2 follow-up) — ~2h
+5. Implement Phase V2 BWE (mandatory for usable video) — ~3–4 days
+6. Implement capture pipeline for at least one platform (V7) — ~1 week
+
## Phase V1 — Wire format & negotiation (no new code paths yet)
Bump protocol version. Land all wire changes together so compat breaks exactly once.
diff --git a/docs/WZP-SPEC.md b/docs/WZP-SPEC.md
index 88b1821..816eb8c 100644
--- a/docs/WZP-SPEC.md
+++ b/docs/WZP-SPEC.md
@@ -2,7 +2,7 @@
> Distilled from `docs/ARCHITECTURE.md` and the `wzp-proto` crate. Authoritative wire details live in `crates/wzp-proto/src/packet.rs`.
>
-> **Status:** v1 (audio-only) is the deployed protocol. v2 (audio + video, 16 B header, MediaType, u32 seq, etc.) is specified in `ROAD-TO-VIDEO.md` Phase V1 and supersedes this document when implemented.
+> **Status:** v2 is the deployed protocol (audio + video, 16 B header, MediaType, u32 seq). v1 clients are rejected with `Hangup::ProtocolVersionMismatch`.
## Layer summary
@@ -16,42 +16,47 @@
| Loss recovery | **RaptorQ FEC + Opus DRED + classical PLC** | NACK / PLI + reference-picture selection |
| Adaptive | 3-tier hysteresis (Good / Degraded / Catastrophic) + continuous DRED tuner | Per-frame bitrate ladder |
| Topology | SFU rooms + inter-relay federation + P2P via ICE | Mesh ≤ ~3, SFU above, Apple relays |
-| Header | 12 B `MediaHeader` / 4 B `MiniHeader` (49 of 50), 4 B `QualityReport` trailer | RTP 12 B + extensions |
+| Header | 16 B `MediaHeader` v2 / 5 B `MiniHeader` (49 of 50), 4 B `QualityReport` trailer | RTP 12 B + extensions |
## Distinctive choices
- **QUIC datagrams instead of raw UDP + SRTP.** Brings TLS 1.3, PLPMTUD, path migration, and ACK-based RTT/loss estimation for free.
- **Continuous DRED tuning.** Maps live `(loss%, RTT, jitter)` to a continuous Opus DRED lookback window. Most stacks treat DRED as discrete tiers.
-- **MiniHeader (4 B for 49/50 packets).** Saves ~8 B/packet ≈ 400 B/s/stream at 50 pps.
+- **MiniHeader (5 B for 49/50 packets).** Saves ~11 B/packet ≈ 550 B/s/stream at 50 pps vs. the full 16 B header.
- **E2E-preserving SFU.** The relay forwards encrypted datagrams; it never decrypts media. Room membership uses SNI = `hash(room_name)`.
- **Codec coordination via `QualityReport` trailer.** Receivers attach 4-byte loss/RTT/jitter/cap to media packets; the SFU broadcasts `QualityDirective` so all senders in a room converge on the same tier.
-## Wire format (current — v1)
+## Wire format (current — v2)
-### `MediaHeader` (12 bytes)
+### `MediaHeader` v2 (16 bytes, byte-aligned)
```
-Byte 0: [V:1][T:1][CodecID:4][Q:1][FecRatioHi:1]
-Byte 1: [FecRatioLo:6][unused:2]
-Bytes 2-3: sequence (u16 BE)
-Bytes 4-7: timestamp_ms (u32 BE)
-Byte 8: fec_block_id (u8)
-Byte 9: fec_symbol_idx (u8)
-Byte 10: reserved
-Byte 11: csrc_count
+Byte 0: version (u8) 0x02
+Byte 1: flags (u8) [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8) 0-255 (see codec table)
+Byte 4: stream_id (u8) simulcast layer; 0=base
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE)
+Bytes 10-13: timestamp_ms (u32 BE)
+Bytes 14-15: fec_block_id (u16 BE)
```
| Field | Bits | Meaning |
|---|---|---|
-| V | 1 | Protocol version |
-| T | 1 | 1 = FEC repair packet |
-| CodecID | 4 | See codec table |
-| Q | 1 | QualityReport trailer present |
-| FecRatio | 7 | 0–127 → 0.0–2.0 |
-| sequence | 16 | Wrapping packet seq |
+| version | 8 | Must be `0x02`; v1 clients receive `Hangup::ProtocolVersionMismatch` |
+| T (bit 7 of flags) | 1 | 1 = FEC repair packet |
+| Q (bit 6 of flags) | 1 | QualityReport trailer present |
+| KeyFrame (bit 5 of flags) | 1 | Packet belongs to a video I-frame |
+| FrameEnd (bit 4 of flags) | 1 | Last packet of an access unit |
+| reserved (bits 3-0 of flags) | 4 | Must be zero |
+| media_type | 8 | 0=audio, 1=video, 2=data, 3=control |
+| codec_id | 8 | See codec table (widened from v1's 4-bit field) |
+| stream_id | 8 | Simulcast layer; 0=base layer |
+| fec_ratio | 8 | 0..200 → 0.0..2.0 |
+| sequence | 32 | Monotonically increasing packet seq (not reset by rekey) |
| timestamp_ms | 32 | ms since session start. Monotonic across the full session; **not reset by rekey** |
-| fec_block_id | 8 | FEC source block ID |
-| fec_symbol_idx | 8 | Symbol index in block |
+| fec_block_id | 16 | FEC source block ID |
### Codec table
@@ -66,13 +71,18 @@ Byte 11: csrc_count
| 6 | Opus 32k | 32 kbps | 48 kHz | 20 ms |
| 7 | Opus 48k | 48 kbps | 48 kHz | 20 ms |
| 8 | Opus 64k | 64 kbps | 48 kHz | 20 ms |
+| 9 | H.264 Baseline | — | — | — |
+| 10 | H.264 Main | — | — | — |
+| 11 | H.265 Main | — | — | — |
+| 12 | AV1 Main | — | — | — |
-### `MiniHeader` (4 bytes, compressed — 49 of every 50 packets)
+### `MiniHeader` v2 (5 bytes, compressed — 49 of every 50 packets)
```
[FRAME_TYPE_MINI = 0x01]
-Bytes 0-1: timestamp_delta_ms (u16 BE)
-Bytes 2-3: payload_len (u16 BE)
+Byte 0: seq_delta (u8)
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
```
Full header sent every 50th packet to resync.
@@ -95,6 +105,12 @@ Byte 2: jitter_ms (0-255 ms)
Byte 3: bitrate_cap_kbps (0-255 kbps)
```
+### Version negotiation
+
+- `version=0x02` in `MediaHeader` is a hard switch — there is no fallback negotiation.
+- Both endpoints must speak v2. A v1 peer receives `Hangup::ProtocolVersionMismatch` immediately.
+- Relays inspect only `version` and `media_type`; they never downgrade or translate between versions.
+
## Session lifecycle
```
diff --git a/vault/.obsidian/app.json b/vault/.obsidian/app.json
new file mode 100644
index 0000000..7c1c751
--- /dev/null
+++ b/vault/.obsidian/app.json
@@ -0,0 +1,6 @@
+{
+ "legacyEditor": false,
+ "livePreview": true,
+ "defaultViewMode": "source",
+ "promptDelete": false
+}
diff --git a/vault/.obsidian/workspace.json b/vault/.obsidian/workspace.json
new file mode 100644
index 0000000..0967ef4
--- /dev/null
+++ b/vault/.obsidian/workspace.json
@@ -0,0 +1 @@
+{}
diff --git a/vault/00 - Home.md b/vault/00 - Home.md
new file mode 100644
index 0000000..1720698
--- /dev/null
+++ b/vault/00 - Home.md
@@ -0,0 +1,128 @@
+---
+tags: [home, wzp]
+type: index
+---
+
+# WarzonePhone Vault
+
+WarzonePhone (WZP) is a custom lossy VoIP protocol and application stack built in Rust. It features a 7-crate workspace, Opus + Codec2 audio codecs, RaptorQ FEC, QUIC transport, and a Tauri-based Android client. The project spans relay infrastructure, P2P direct calling, AV1 video, and federated relay gossip.
+
+---
+
+## Architecture
+
+- [[Architecture/Architecture|Architecture Overview]]
+- [[Architecture/WZP-Spec|WZP Protocol Spec]]
+- [[Architecture/Protocol-Audit|Protocol Audit]]
+- [[Architecture/Design|Design Doc]]
+- [[Architecture/WS-Relay-Spec|WebSocket Relay Spec]]
+- [[Architecture/Extensibility|Extensibility]]
+- [[Architecture/Road-To-Video|Road to Video]]
+- [[Architecture/Attack-Surface-Relay-Abuse|Attack Surface: Relay Abuse]]
+- [[Architecture/Refactor-Codebase-Audit|Refactor: Codebase Audit]]
+- [[Architecture/Refactor-Relay-Concurrency|Refactor: Relay Concurrency]]
+- [[Architecture/Branch-Desktop-Audio-Rewrite|Branch: Desktop Audio Rewrite]]
+
+---
+
+## Active Work
+
+- [[Reference/Handoff-2026-05-12|Handoff 2026-05-12]] — current state handoff doc
+- [[PRDs/TASKS|TASKS — Status Board]]
+- [[Audit/Audit-2026-05-25|Audit 2026-05-25]]
+
+---
+
+## PRDs
+
+### Audio & Codec
+- [[PRDs/PRD-adaptive-quality|Adaptive Quality]]
+- [[PRDs/PRD-bluetooth-audio|Bluetooth Audio]]
+- [[PRDs/PRD-coordinated-codec|Coordinated Codec]]
+- [[PRDs/PRD-dred-integration|DRED Integration]]
+- [[PRDs/PRD-studio-quality|Studio Quality]]
+
+### Networking & P2P
+- [[PRDs/PRD-p2p-direct|P2P Direct Calling]]
+- [[PRDs/PRD-hard-nat|Hard NAT Traversal]]
+- [[PRDs/PRD-ice-regather|ICE Regather]]
+- [[PRDs/PRD-mtu-discovery|MTU Discovery]]
+- [[PRDs/PRD-netcheck|Network Check]]
+- [[PRDs/PRD-network-awareness|Network Awareness]]
+- [[PRDs/PRD-portmap|Port Mapping]]
+- [[PRDs/PRD-public-stun|Public STUN]]
+- [[PRDs/PRD-transport-feedback-bwe|Transport Feedback BWE]]
+
+### Relay
+- [[PRDs/PRD-relay-concurrency|Relay Concurrency]]
+- [[PRDs/PRD-relay-conformance|Relay Conformance]]
+- [[PRDs/PRD-relay-federation|Relay Federation]]
+- [[PRDs/PRD-relay-federation-gossip|Relay Federation Gossip]]
+- [[PRDs/PRD-relay-selection|Relay Selection]]
+
+### Video
+- [[PRDs/PRD-video-v1|Video V1]]
+- [[PRDs/PRD-video-multicodec|Video Multicodec]]
+- [[PRDs/PRD-video-quality-priority|Video Quality Priority]]
+- [[PRDs/PRD-video-simulcast|Video Simulcast]]
+
+### Protocol & Security
+- [[PRDs/PRD-protocol-hardening|Protocol Hardening]]
+- [[PRDs/PRD-protocol-analyzer|Protocol Analyzer]]
+- [[PRDs/PRD-wire-format-v2|Wire Format V2]]
+- [[PRDs/PRD-delegated-trust|Delegated Trust]]
+
+### Other
+- [[PRDs/PRD-engine-dedup|Engine Dedup]]
+- [[PRDs/PRD-local-recording|Local Recording]]
+
+---
+
+## Android
+
+- [[Android/Architecture|Android Architecture]]
+- [[Android/Build-Guide|Build Guide]]
+- [[Android/Roadmap|Android Roadmap]]
+- [[Android/Debugging|Debugging]]
+- [[Android/Maintenance|Maintenance]]
+- [[Android/Fix-Audio-Ring-Desync|Fix: Audio Ring Desync]]
+- [[Android/Fix-Capture-Thread-Crash|Fix: Capture Thread Crash]]
+- [[Android/README|Android README]]
+
+---
+
+## Reference
+
+- [[Reference/API|API Reference]]
+- [[Reference/Usage|Usage]]
+- [[Reference/User-Guide|User Guide]]
+- [[Reference/Administration|Administration]]
+- [[Reference/Telemetry|Telemetry]]
+- [[Reference/Progress|Progress]]
+- [[Reference/Featherchat-Integration|FeatherChat Integration]]
+- [[Reference/Featherchat|FeatherChat]]
+- [[Reference/WZP-FC-Shared-Crates|WZP-FC Shared Crates]]
+- [[Reference/Integration-Tasks|Integration Tasks]]
+
+---
+
+## Reports
+
+### Approved
+- [[Reports/T1.1-report|T1.1]] · [[Reports/T1.1.1-report|T1.1.1]] · [[Reports/T1.1.2-report|T1.1.2]]
+- [[Reports/T1.2-report|T1.2]] · [[Reports/T1.2.1-report|T1.2.1]]
+- [[Reports/T1.3-report|T1.3]] · [[Reports/T1.4-report|T1.4]] · [[Reports/T1.4.1-report|T1.4.1]]
+- [[Reports/T1.5-report|T1.5]] · [[Reports/T1.5.1-report|T1.5.1]] · [[Reports/T1.5.2-report|T1.5.2]]
+- [[Reports/T1.6-report|T1.6]] · [[Reports/T1.7-report|T1.7]] · [[Reports/T1.8-report|T1.8]]
+- [[Reports/T2.1-report|T2.1]] · [[Reports/T2.2-report|T2.2]]
+- [[Reports/T4.2-report|T4.2]] · [[Reports/T4.2.1-report|T4.2.1]] · [[Reports/T4.3-report|T4.3]] · [[Reports/T4.3.1-report|T4.3.1]]
+- [[Reports/T4.4-report|T4.4]] · [[Reports/T4.5-report|T4.5]] · [[Reports/T4.6-report|T4.6]] · [[Reports/T4.7-report|T4.7]]
+- [[Reports/T5.1-report|T5.1]] · [[Reports/T5.2-report|T5.2]] · [[Reports/T5.3-report|T5.3]]
+
+### Pending Review
+- [[Reports/T2.3-report|T2.3]] · [[Reports/T2.4-report|T2.4]] · [[Reports/T2.5-report|T2.5]] · [[Reports/T2.6-report|T2.6]]
+- [[Reports/T3.1-report|T3.1]] · [[Reports/T3.2-report|T3.2]] · [[Reports/T3.3-report|T3.3]] · [[Reports/T3.4-report|T3.4]] · [[Reports/T3.5-report|T3.5]]
+- [[Reports/T4.1-report|T4.1]]
+- [[Reports/T5.1.1-report|T5.1.1]] · [[Reports/T5.4-report|T5.4]] · [[Reports/T5.5-report|T5.5]] · [[Reports/T5.6-report|T5.6]]
+- [[Reports/T5.7-report|T5.7]] · [[Reports/T5.7.1-report|T5.7.1]] · [[Reports/T5.8-report|T5.8]]
+- [[Reports/T6.1-report|T6.1]] · [[Reports/T6.1.2-report|T6.1.2]] · [[Reports/T6.2-report|T6.2]]
diff --git a/vault/Android/Architecture.md b/vault/Android/Architecture.md
new file mode 100644
index 0000000..d5ed2e4
--- /dev/null
+++ b/vault/Android/Architecture.md
@@ -0,0 +1,405 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Architecture
+
+## System Overview
+
+The Android client is a four-layer stack: Kotlin UI, JNI bridge, Rust engine, and C++ audio I/O. Each layer communicates through well-defined interfaces with minimal coupling.
+
+```mermaid
+graph TB
+ subgraph "Kotlin (Main Thread)"
+ CA[CallActivity]
+ VM[CallViewModel]
+ UI[InCallScreen
Compose UI]
+ CA --> VM
+ VM --> UI
+ end
+
+ subgraph "JNI Bridge"
+ JB[jni_bridge.rs
panic-safe FFI]
+ end
+
+ subgraph "Rust Engine"
+ ENG[WzpEngine
Orchestrator]
+ CT[Codec Thread
20ms real-time loop]
+ NET[Tokio Runtime
2 async workers]
+ PIPE[Pipeline
Encode/Decode/FEC/Jitter]
+ end
+
+ subgraph "C++ Audio"
+ OBOE[Oboe Bridge
Capture + Playout callbacks]
+ RB[Ring Buffers
Lock-free SPSC]
+ end
+
+ subgraph "Network"
+ QUIC[QUIC Connection
quinn]
+ RELAY[WZP Relay
SFU Room]
+ end
+
+ VM <-->|"JNI calls
+ JSON stats"| JB
+ JB <--> ENG
+ ENG --> CT
+ ENG --> NET
+ CT <--> PIPE
+ CT <-->|"Atomic R/W"| RB
+ OBOE <-->|"Atomic R/W"| RB
+ CT <-->|"mpsc channels"| NET
+ NET <-->|"QUIC datagrams
+ streams"| QUIC
+ QUIC <--> RELAY
+```
+
+## Thread Model
+
+The engine uses four distinct thread contexts, each with specific responsibilities and real-time constraints.
+
+```mermaid
+graph LR
+ subgraph "Android Main Thread"
+ UI_T["UI + JNI calls
startCall / stopCall / getStats"]
+ end
+
+ subgraph "Oboe Audio Thread (system)"
+ AUD["Capture callback: mic → ring buf
Playout callback: ring buf → speaker
⚡ Highest priority, no allocations"]
+ end
+
+ subgraph "Codec Thread (wzp-codec)"
+ COD["20ms loop:
1. Read capture ring buf
2. AEC → AGC → Encode
3. Send to network channel
4. Recv from network channel
5. FEC → Jitter → Decode
6. Write playout ring buf
⚡ Pinned to big core, RT priority"]
+ end
+
+ subgraph "Tokio Runtime (2 workers)"
+ NET_S["Send task:
Channel → MediaPacket → QUIC datagram"]
+ NET_R["Recv task:
QUIC datagram → MediaPacket → Channel"]
+ HS["Handshake:
CallOffer → CallAnswer"]
+ end
+
+ UI_T -->|"mpsc command channel"| COD
+ COD -->|"tokio::mpsc send_tx"| NET_S
+ NET_R -->|"tokio::mpsc recv_tx"| COD
+ AUD <-->|"Atomic ring buffers"| COD
+```
+
+### Thread Priorities and Constraints
+
+| Thread | Priority | Allocations | Blocking | Lock-free |
+|--------|----------|-------------|----------|-----------|
+| Oboe audio | SCHED_FIFO (system) | None | Never | Yes |
+| Codec | RT priority, big core | Pre-allocated buffers | sleep(remainder of 20ms) | Ring buf: yes, Stats: Mutex |
+| Tokio workers | Normal | Allowed | Async only | N/A |
+| Main/JNI | Normal | Allowed | Allowed | N/A |
+
+## Call Lifecycle
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant UI as InCallScreen
+ participant VM as CallViewModel
+ participant ENG as WzpEngine (JNI)
+ participant NET as Tokio Network
+ participant RELAY as WZP Relay
+
+ User->>UI: Tap CALL
+ UI->>VM: startCall()
+ VM->>ENG: init() + startCall(relay, room)
+ ENG->>ENG: Create tokio runtime
+ ENG->>NET: Spawn network task
+
+ NET->>RELAY: QUIC connect (SNI = room name)
+ RELAY-->>NET: Connection established
+
+ Note over NET,RELAY: Crypto Handshake
+ NET->>RELAY: CallOffer {identity_pub, ephemeral_pub, signature, profiles}
+ RELAY-->>NET: CallAnswer {ephemeral_pub, chosen_profile, signature}
+ NET->>NET: Derive ChaCha20-Poly1305 session
+
+ ENG->>ENG: Spawn codec thread
+ Note over ENG: State → Active
+
+ loop Every 20ms
+ ENG->>ENG: Read mic → AEC → AGC → Encode
+ ENG->>NET: Encoded frame via channel
+ NET->>RELAY: MediaPacket via QUIC DATAGRAM
+ RELAY->>NET: MediaPacket from other peer
+ NET->>ENG: MediaPacket via channel
+ ENG->>ENG: FEC → Jitter → Decode → Speaker
+ end
+
+ User->>UI: Tap END
+ UI->>VM: stopCall()
+ VM->>ENG: stopCall()
+ ENG->>ENG: Set running=false, send Stop command
+ ENG->>ENG: Join codec thread
+ ENG->>NET: Drop tokio runtime
+ NET->>RELAY: Connection close
+```
+
+## Audio Pipeline Detail
+
+```mermaid
+graph LR
+ subgraph "Capture Path"
+ MIC[Microphone] -->|"48kHz i16"| OBOE_C[Oboe Capture
Callback]
+ OBOE_C -->|"ring_write()"| RB_C[Capture
Ring Buffer]
+ RB_C -->|"read_capture()"| AEC[Echo
Canceller]
+ AEC --> AGC[Auto Gain
Control]
+ AGC --> ENC[AdaptiveEncoder
Opus 24k]
+ ENC -->|"Vec u8"| FEC_E[RaptorQ
FEC Encoder]
+ FEC_E -->|"send_tx"| CHAN_S[Send Channel]
+ end
+
+ subgraph "Network"
+ CHAN_S --> PKT_S[MediaPacket
Header + Payload]
+ PKT_S -->|"QUIC DATAGRAM"| RELAY[Relay SFU]
+ RELAY -->|"QUIC DATAGRAM"| PKT_R[MediaPacket
Deserialize]
+ PKT_R -->|"recv_tx"| CHAN_R[Recv Channel]
+ end
+
+ subgraph "Playout Path"
+ CHAN_R --> FEC_D[RaptorQ
FEC Decoder]
+ FEC_D --> JB[Jitter Buffer
10-250 pkts]
+ JB --> DEC[AdaptiveDecoder
Opus 24k]
+ DEC -->|"48kHz i16"| AEC_REF[AEC Far-End
Reference]
+ DEC -->|"write_playout()"| RB_P[Playout
Ring Buffer]
+ RB_P -->|"ring_read()"| OBOE_P[Oboe Playout
Callback]
+ OBOE_P --> SPK[Speaker]
+ end
+```
+
+### Audio Parameters
+
+| Parameter | Value | Notes |
+|-----------|-------|-------|
+| Sample rate | 48,000 Hz | Opus native rate |
+| Channels | 1 (mono) | VoIP only |
+| Frame size | 960 samples | 20ms at 48kHz |
+| Ring buffer | 7,680 samples | 160ms (8 frames) |
+| Bit depth | 16-bit signed int | PCM format |
+| AEC tail | 100ms | Echo canceller filter length |
+
+## Crypto Handshake
+
+```mermaid
+sequenceDiagram
+ participant Client as Android Client
+ participant Relay as WZP Relay
+
+ Note over Client: Identity seed (32 bytes, random per launch)
+ Note over Client: HKDF → Ed25519 signing key + X25519 static key
+
+ Client->>Client: Generate ephemeral X25519 keypair
+ Client->>Client: Sign(ephemeral_pub || "call-offer") with Ed25519
+
+ Client->>Relay: SignalMessage::CallOffer
{identity_pub, ephemeral_pub, signature, [GOOD, DEGRADED, CATASTROPHIC]}
+
+ Relay->>Relay: Verify Ed25519 signature
+ Relay->>Relay: Generate own ephemeral X25519
+ Relay->>Relay: Sign(ephemeral_pub || "call-answer")
+ Relay->>Relay: DH(relay_ephemeral, client_ephemeral) → shared secret
+ Relay->>Relay: HKDF(shared_secret) → ChaCha20-Poly1305 key
+
+ Relay->>Client: SignalMessage::CallAnswer
{identity_pub, ephemeral_pub, signature, chosen_profile=GOOD}
+
+ Client->>Client: Verify relay signature
+ Client->>Client: DH(client_ephemeral, relay_ephemeral) → same shared secret
+ Client->>Client: HKDF(shared_secret) → same ChaCha20-Poly1305 key
+
+ Note over Client,Relay: Both sides now have identical session key
+ Note over Client,Relay: Media packets can be encrypted (not yet applied)
+```
+
+### Key Derivation Chain
+
+```
+Identity Seed (32 bytes, random)
+ │
+ ├── HKDF(seed, info="warzone-ed25519") → Ed25519 signing key
+ │ └── Public key = identity_pub (32 bytes)
+ │ └── SHA-256(identity_pub)[:16] = fingerprint (16 bytes)
+ │
+ └── HKDF(seed, info="warzone-x25519") → X25519 static key (unused currently)
+
+Per-Call Ephemeral:
+ Random X25519 keypair → ephemeral_pub (sent in CallOffer)
+
+Session Key:
+ DH(our_ephemeral_secret, peer_ephemeral_pub) → shared_secret
+ HKDF(shared_secret, info="warzone-session-key") → ChaCha20-Poly1305 key (32 bytes)
+```
+
+## QUIC Transport
+
+```mermaid
+graph TB
+ subgraph "QUIC Connection"
+ EP[Client Endpoint
0.0.0.0:0 UDP]
+ CONN[Connection to Relay
SNI = room name]
+
+ subgraph "Unreliable Channel"
+ DG_S[Send DATAGRAM
MediaPacket serialized]
+ DG_R[Recv DATAGRAM
MediaPacket deserialized]
+ end
+
+ subgraph "Reliable Channel"
+ ST_S[Open bidi stream
JSON length-prefixed
SignalMessage]
+ ST_R[Accept bidi stream
JSON length-prefixed
SignalMessage]
+ end
+
+ EP --> CONN
+ CONN --> DG_S
+ CONN --> DG_R
+ CONN --> ST_S
+ CONN --> ST_R
+ end
+```
+
+### QUIC Configuration (VoIP-tuned)
+
+| Setting | Value | Rationale |
+|---------|-------|-----------|
+| ALPN | `wzp` | Protocol identification |
+| Idle timeout | 30s | Keep connection alive during silence |
+| Keep-alive | 5s | Prevent NAT timeout |
+| Datagram receive buffer | 65 KB | Buffer for burst arrivals |
+| Flow control (recv) | 256 KB | Conservative for VoIP |
+| Flow control (send) | 128 KB | Prevent bufferbloat |
+| TLS | Self-signed certs | Development mode |
+| Certificate verification | Disabled | Client accepts any cert |
+
+## MediaPacket Wire Format
+
+```
+12-byte header:
+┌─────────────────────────────────────────────────┐
+│ Byte 0: V(1) T(1) CodecID(4) Q(1) FecHi(1) │
+│ Byte 1: FecLo(6) unused(2) │
+│ Byte 2-3: Sequence number (u16 BE) │
+│ Byte 4-7: Timestamp ms (u32 BE) │
+│ Byte 8: FEC block ID │
+│ Byte 9: FEC symbol index │
+│ Byte 10: Reserved │
+│ Byte 11: CSRC count │
+├─────────────────────────────────────────────────┤
+│ Payload: Opus-encoded audio frame │
+├─────────────────────────────────────────────────┤
+│ Optional: QualityReport (4 bytes, if Q=1) │
+│ loss_pct(u8) rtt_4ms(u8) jitter_ms(u8) │
+│ bitrate_cap_kbps(u8) │
+└─────────────────────────────────────────────────┘
+```
+
+## Relay Room Mode (SFU)
+
+```mermaid
+graph LR
+ subgraph "Room: android"
+ P1[Phone A
QUIC conn] -->|MediaPacket| RELAY[Relay SFU]
+ RELAY -->|MediaPacket| P2[Phone B
QUIC conn]
+ P2 -->|MediaPacket| RELAY
+ RELAY -->|MediaPacket| P1
+ end
+
+ Note1["Room name from QUIC TLS SNI
No auth required
Packets forwarded to all others"]
+```
+
+The relay operates as a Selective Forwarding Unit:
+1. Client connects via QUIC, room name extracted from TLS SNI
+2. Crypto handshake completes (relay has its own ephemeral identity)
+3. Client joins named room
+4. All received media packets are forwarded to every other participant in the room
+5. Signaling messages are not forwarded (point-to-point with relay)
+
+## Adaptive Quality System
+
+```mermaid
+graph TD
+ QR[QualityReport
loss%, RTT, jitter] --> AQC[AdaptiveQualityController]
+
+ AQC -->|"loss<10%, RTT<400ms"| GOOD[GOOD
Opus 24kbps
FEC 20%
20ms frames]
+ AQC -->|"loss 10-40%
RTT 400-600ms"| DEG[DEGRADED
Opus 6kbps
FEC 50%
40ms frames]
+ AQC -->|"loss>40%
RTT>600ms"| CAT[CATASTROPHIC
Codec2 1.2kbps
FEC 100%
40ms frames]
+
+ GOOD -->|"Hysteresis:
sustained degradation"| DEG
+ DEG -->|"Sustained improvement"| GOOD
+ DEG -->|"Further degradation"| CAT
+ CAT -->|"Improvement"| DEG
+```
+
+| Profile | Codec | Bitrate | FEC Ratio | Frame Size | FEC Block |
+|---------|-------|---------|-----------|------------|-----------|
+| GOOD | Opus 24k | 24 kbps | 20% | 20ms | 5 frames |
+| DEGRADED | Opus 6k | 6 kbps | 50% | 40ms | 10 frames |
+| CATASTROPHIC | Codec2 1.2k | 1.2 kbps | 100% | 40ms | 8 frames |
+
+## Module Dependency Graph
+
+```mermaid
+graph BT
+ PROTO[wzp-proto
Types, traits, jitter,
quality, session]
+ CODEC[wzp-codec
Opus, Codec2, AEC,
AGC, resampling]
+ FEC[wzp-fec
RaptorQ fountain codes]
+ CRYPTO[wzp-crypto
Ed25519, X25519,
ChaCha20-Poly1305]
+ TRANSPORT[wzp-transport
QUIC, datagrams,
signaling streams]
+ ANDROID[wzp-android
Engine, JNI bridge,
Oboe audio, pipeline]
+ RELAY[wzp-relay
SFU, rooms, auth,
metrics, probes]
+
+ CODEC --> PROTO
+ FEC --> PROTO
+ CRYPTO --> PROTO
+ TRANSPORT --> PROTO
+ ANDROID --> PROTO
+ ANDROID --> CODEC
+ ANDROID --> FEC
+ ANDROID --> CRYPTO
+ ANDROID --> TRANSPORT
+ RELAY --> PROTO
+ RELAY --> CRYPTO
+ RELAY --> TRANSPORT
+```
+
+## File Map
+
+### Kotlin (`android/app/src/main/java/com/wzp/`)
+
+| File | Purpose |
+|------|---------|
+| `WzpApplication.kt` | App entry, notification channel creation |
+| `engine/WzpEngine.kt` | JNI wrapper for native engine |
+| `engine/WzpCallback.kt` | Callback interface for engine events |
+| `engine/CallStats.kt` | Stats data class with JSON deserialization |
+| `ui/call/CallActivity.kt` | Activity host, permissions, theme |
+| `ui/call/CallViewModel.kt` | MVVM state holder, stats polling |
+| `ui/call/InCallScreen.kt` | Compose UI (idle + in-call states) |
+| `service/CallService.kt` | Foreground service, wake/wifi locks |
+| `audio/AudioRouteManager.kt` | Speaker/earpiece/Bluetooth routing |
+
+### Rust (`crates/wzp-android/src/`)
+
+| File | Purpose |
+|------|---------|
+| `lib.rs` | Module declarations |
+| `jni_bridge.rs` | JNI FFI (panic-safe, proper jni crate) |
+| `engine.rs` | Call orchestrator (threads, channels, lifecycle) |
+| `pipeline.rs` | Codec pipeline (AEC, AGC, encode, FEC, jitter, decode) |
+| `audio_android.rs` | Oboe backend, SPSC ring buffers, RT scheduling |
+| `commands.rs` | Engine command enum |
+| `stats.rs` | CallState/CallStats types (serde) |
+
+### C++ (`crates/wzp-android/cpp/`)
+
+| File | Purpose |
+|------|---------|
+| `oboe_bridge.h` | FFI header for Rust-C++ audio interface |
+| `oboe_bridge.cpp` | Oboe capture/playout callbacks, ring buffer I/O |
+| `oboe_stub.cpp` | No-op stub for non-Android builds |
+
+### Build
+
+| File | Purpose |
+|------|---------|
+| `android/app/build.gradle.kts` | Android build config, cargo-ndk task |
+| `crates/wzp-android/Cargo.toml` | Rust dependencies (cdylib output) |
+| `crates/wzp-android/build.rs` | C++ compilation, Oboe fetch |
diff --git a/vault/Android/Build-Guide.md b/vault/Android/Build-Guide.md
new file mode 100644
index 0000000..ca7a181
--- /dev/null
+++ b/vault/Android/Build-Guide.md
@@ -0,0 +1,160 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Build Guide
+
+## Prerequisites
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| JDK | 17 | Android Gradle builds |
+| Android SDK | 34 | Compile SDK |
+| Android NDK | 26.1.10909125 | Native C++/Rust compilation |
+| Rust | 1.85+ | Native engine (edition 2024) |
+| cargo-ndk | latest | Cross-compile Rust → Android |
+| `aarch64-linux-android` target | - | Rust target for ARM64 |
+
+### Install Rust Android target
+
+```bash
+rustup target add aarch64-linux-android
+cargo install cargo-ndk
+```
+
+### Environment Variables
+
+```bash
+export JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64"
+export ANDROID_HOME="$HOME/android-sdk"
+export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/26.1.10909125"
+
+# For manual cargo-ndk builds (Gradle sets these automatically):
+export CC_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang"
+export CXX_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang++"
+export AR_aarch64_linux_android="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
+```
+
+## Build Commands
+
+### Full Build (Gradle drives everything)
+
+```bash
+cd android
+./gradlew assembleRelease
+```
+
+This runs:
+1. `cargoNdkBuild` task: invokes `cargo ndk -t arm64-v8a -o app/src/main/jniLibs build --release -p wzp-android`
+2. Compiles Kotlin/Compose code
+3. Packages APK with signing
+
+### Native Library Only
+
+```bash
+cargo ndk -t arm64-v8a -o android/app/src/main/jniLibs build --release -p wzp-android
+```
+
+Output: `android/app/src/main/jniLibs/arm64-v8a/libwzp_android.so`
+
+### Skip Native Rebuild
+
+If the `.so` hasn't changed:
+
+```bash
+cd android
+./gradlew assembleRelease -x cargoNdkBuild
+```
+
+### Debug Build
+
+```bash
+cd android
+./gradlew assembleDebug
+```
+
+Debug APK is ~8.9 MB (unstripped `.so`), release is ~6.9 MB.
+
+## Signing
+
+### Debug
+
+```
+Keystore: android/keystore/wzp-debug.jks
+Password: android
+Key alias: wzp-debug
+```
+
+### Release
+
+```
+Keystore: android/keystore/wzp-release.jks
+Password: wzphone2024
+Key alias: wzp-release
+```
+
+Both keystores are checked into the repo for development convenience. For production, replace with proper key management.
+
+## Build Artifacts
+
+| Artifact | Path | Size |
+|----------|------|------|
+| Debug APK | `android/app/build/outputs/apk/debug/app-debug.apk` | ~8.9 MB |
+| Release APK | `android/app/build/outputs/apk/release/app-release.apk` | ~6.9 MB |
+| Native lib | `android/app/src/main/jniLibs/arm64-v8a/libwzp_android.so` | ~5 MB |
+
+## ABI Support
+
+Currently only `arm64-v8a` (ARM64) is built. This covers 95%+ of modern Android devices.
+
+To add more ABIs, edit `build.gradle.kts`:
+
+```kotlin
+ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
+```
+
+And update the cargo-ndk command in `cargoNdkBuild` task:
+
+```kotlin
+commandLine("cargo", "ndk", "-t", "arm64-v8a", "-t", "armeabi-v7a", ...)
+```
+
+## Oboe Dependency
+
+The Oboe C++ audio library is fetched at build time by `build.rs`:
+
+1. Attempts `git clone` of Oboe 1.8.1 into `$OUT_DIR/oboe`
+2. If successful, compiles `oboe_bridge.cpp` with Oboe headers
+3. If clone fails (no network), falls back to `oboe_stub.cpp` (no-op audio)
+
+This means **first build requires internet** to fetch Oboe. Subsequent builds use the cached checkout.
+
+## Common Build Issues
+
+### `cargo ndk` not found
+
+```bash
+cargo install cargo-ndk
+```
+
+### Missing Android target
+
+```bash
+rustup target add aarch64-linux-android
+```
+
+### NDK not found
+
+Ensure `ANDROID_NDK_HOME` points to the NDK directory containing `toolchains/llvm/`.
+
+### C++ compilation errors
+
+Check that `CXX_aarch64_linux_android` points to a valid clang++ from the NDK.
+
+### Gradle daemon issues
+
+```bash
+./gradlew --stop
+./gradlew assembleRelease --no-daemon
+```
diff --git a/vault/Android/Debugging.md b/vault/Android/Debugging.md
new file mode 100644
index 0000000..8edc373
--- /dev/null
+++ b/vault/Android/Debugging.md
@@ -0,0 +1,219 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Debugging Guide
+
+## Crash on Launch
+
+### Symptom: App crashes immediately after opening
+
+**Most likely cause: Namespace mismatch in AndroidManifest.xml**
+
+The Gradle namespace is `com.wzp.phone` but all Kotlin classes are in package `com.wzp.*`. If the manifest uses shorthand names (`.WzpApplication`, `.ui.call.CallActivity`), Android resolves them as `com.wzp.phone.WzpApplication` which doesn't exist.
+
+**Fix**: Always use fully-qualified class names in the manifest:
+
+```xml
+
+
+
+
+
+
+
+```
+
+### Symptom: Crash in `System.loadLibrary("wzp_android")`
+
+The native `.so` is missing or incompatible. Check:
+
+```bash
+# Verify the .so exists in the APK
+unzip -l app-release.apk | grep libwzp
+# Should show: lib/arm64-v8a/libwzp_android.so
+
+# Verify ABI matches device
+adb shell getprop ro.product.cpu.abi
+# Should return: arm64-v8a
+```
+
+### Symptom: Crash when calling `nativeGetStats()` (returns null jstring)
+
+The JNI bridge must return a valid `jstring`, not a null pointer. The Kotlin side declares the return as `String?` (nullable) and wraps in try/catch:
+
+```kotlin
+fun getStats(): String {
+ if (nativeHandle == 0L) return "{}"
+ return try {
+ nativeGetStats(nativeHandle) ?: "{}"
+ } catch (_: Exception) {
+ "{}"
+ }
+}
+```
+
+### Symptom: Tracing subscriber panic
+
+`tracing_subscriber::fmt()` writes to stdout, which doesn't exist on Android. The init was removed. If you need logging, use `android_logger` crate instead.
+
+## Logcat Filters
+
+### View all WZP logs
+
+```bash
+adb logcat -s wzp-android:V wzp-codec:V wzp-net:V
+```
+
+### View Rust tracing output (if android_logger is added)
+
+```bash
+adb logcat | grep -E "(wzp|WzpEngine|CallActivity)"
+```
+
+### View Oboe audio logs
+
+```bash
+adb logcat -s AAudio:V oboe:V
+```
+
+### View native crashes
+
+```bash
+adb logcat -s DEBUG:V libc:V
+```
+
+Look for `signal 11 (SIGSEGV)` or `signal 6 (SIGABRT)` with a backtrace in `libwzp_android.so`.
+
+### Symbolicate native crash
+
+```bash
+# Find the .so with debug symbols (before stripping)
+SO_PATH="target/aarch64-linux-android/release/libwzp_android.so"
+
+# Use addr2line from NDK
+$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-addr2line \
+ -e $SO_PATH -f 0x
+```
+
+## Network Issues
+
+### Call stuck on "Connecting..."
+
+The QUIC handshake to the relay is failing. Common causes:
+
+1. **Relay not running**: Verify the relay is listening:
+ ```bash
+ nc -zvu 172.16.81.125 4433
+ ```
+
+2. **Wrong relay address**: Hardcoded in `CallViewModel.kt`:
+ ```kotlin
+ const val DEFAULT_RELAY = "172.16.81.125:4433"
+ ```
+
+3. **QUIC blocked by firewall**: QUIC uses UDP. Many networks block UDP traffic. Ensure UDP port 4433 is open.
+
+4. **TLS handshake failure**: The client uses `client_config()` which disables certificate verification. If the relay's QUIC config changed, this may fail.
+
+### Connected but no audio
+
+1. **Microphone permission denied**: Check Android settings. The app requests `RECORD_AUDIO` on first launch.
+
+2. **Oboe failed to start**: The codec thread logs this. Check logcat for "failed to start audio".
+
+3. **Ring buffer underrun**: The stats overlay shows "Under" count. High underruns mean the codec thread isn't keeping up.
+
+4. **Network not forwarding**: If both phones show "Active" but frame counters aren't increasing, the relay may not be forwarding. Check relay logs.
+
+### High packet loss
+
+The stats overlay shows loss percentage. Common causes:
+
+- Wi-Fi congestion (try cellular or move closer to AP)
+- UDP throttling by carrier/ISP
+- Relay overloaded (check relay metrics)
+
+## Audio Issues
+
+### Echo
+
+AEC (Acoustic Echo Cancellation) is enabled by default with a 100ms tail. If echo persists:
+
+- The AEC may need a longer tail for the specific acoustic environment
+- Speaker volume too high overwhelms the canceller
+- Check that `last_decoded_farend` is being set (playout path working)
+
+### Robot voice / glitching
+
+Usually caused by jitter buffer underruns. The jitter buffer adapts between 10-250 packets. Check:
+
+- `jitter_buffer_depth` in stats (should be > 0 during active call)
+- `underruns` counter (should not climb rapidly)
+- Network jitter (high jitter_ms causes adaptation)
+
+### No sound from speaker
+
+1. Check `isSpeaker` state in the UI
+2. Oboe playout stream may have failed — check logcat for Oboe errors
+3. Ring buffer might be empty — check `framesDecoded` counter
+
+## JNI Issues
+
+### `UnsatisfiedLinkError: No implementation found for...`
+
+The JNI function name doesn't match. JNI names must follow the pattern:
+```
+Java_com_wzp_engine_WzpEngine_
+```
+
+If the package structure changes, all JNI function names must be updated in `jni_bridge.rs`.
+
+### Panic across FFI boundary
+
+All JNI functions wrap their body in `panic::catch_unwind()`. If a Rust panic escapes to Java, it causes a `SIGABRT`. The catch_unwind returns safe defaults:
+
+| Function | Panic return |
+|----------|--------------|
+| `nativeInit` | 0 (null handle) |
+| `nativeStartCall` | -1 (error) |
+| `nativeGetStats` | `JObject::null()` |
+| Others | void (silently swallowed) |
+
+### Thread safety
+
+All JNI methods must be called from the same thread (Android main thread). The `EngineHandle` is a raw pointer — concurrent access is undefined behavior.
+
+## Stats JSON Format
+
+The `nativeGetStats()` returns JSON matching this Rust struct:
+
+```json
+{
+ "state": "Active",
+ "duration_secs": 42.5,
+ "quality_tier": 0,
+ "loss_pct": 0.5,
+ "rtt_ms": 45,
+ "jitter_ms": 12,
+ "jitter_buffer_depth": 3,
+ "frames_encoded": 2125,
+ "frames_decoded": 2100,
+ "underruns": 5
+}
+```
+
+Kotlin deserializes this via `CallStats.fromJson()` using `org.json.JSONObject` (Android built-in, no library needed).
+
+## Diagnostic Checklist
+
+When something doesn't work, check in this order:
+
+1. **APK installed for correct ABI?** (`arm64-v8a` only)
+2. **Manifest class names fully qualified?** (no dots prefix)
+3. **Relay running and reachable?** (`nc -zvu `)
+4. **Microphone permission granted?**
+5. **Stats polling working?** (check if frame counters increment)
+6. **Logcat for native crashes?** (`adb logcat -s DEBUG:V`)
+7. **Network connectivity?** (UDP port open, no firewall)
diff --git a/vault/Android/Fix-Audio-Ring-Desync.md b/vault/Android/Fix-Audio-Ring-Desync.md
new file mode 100644
index 0000000..ea87160
--- /dev/null
+++ b/vault/Android/Fix-Audio-Ring-Desync.md
@@ -0,0 +1,399 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Fix: AudioRing SPSC Buffer Cursor Desync
+
+## Problem
+
+A critical bug causes 10-16 seconds of bidirectional audio silence mid-call (~25-30s in). Both participants go silent at the exact same moment. The QUIC transport, relay, Opus codec, and FEC are all healthy — the bug is in the lock-free ring buffer that transfers decoded PCM from the Rust recv task to the Kotlin AudioTrack playout thread.
+
+**Root cause:** `AudioRing::write()` modifies `read_pos` from the producer thread during overflow handling (lines 68-72 of `audio_ring.rs`). This violates the SPSC invariant — only the consumer should own `read_pos`. When both threads write to `read_pos`, a race corrupts the cursor state, causing the reader to see an empty or stale buffer for 12-16 seconds.
+
+**Full forensics:** `debug/INCIDENT-2026-04-06-playout-ring-desync.md`
+
+---
+
+## Solution: Reader-Detects-Lap Architecture
+
+The writer NEVER touches `read_pos`. On overflow, the writer simply overwrites old buffer data and advances `write_pos`. The reader detects it was lapped and self-corrects by snapping its own `read_pos` forward.
+
+---
+
+## Implementation Steps
+
+### Step 1: Rewrite `AudioRing`
+
+**File:** `crates/wzp-android/src/audio_ring.rs`
+
+Replace the entire implementation with:
+
+**Constants:**
+```rust
+/// Ring buffer capacity — must be a power of 2 for bitmask indexing.
+/// 16384 samples = 341.3ms at 48kHz mono. Provides 70% more headroom
+/// than the previous 9600 (200ms) for surviving Android GC pauses.
+const RING_CAPACITY: usize = 16384; // 2^14
+const RING_MASK: usize = RING_CAPACITY - 1;
+```
+
+**Struct:**
+```rust
+pub struct AudioRing {
+ buf: Box<[i16; RING_CAPACITY]>,
+ write_pos: AtomicUsize, // monotonically increasing, ONLY written by producer
+ read_pos: AtomicUsize, // monotonically increasing, ONLY written by consumer
+ overflow_count: AtomicU64, // incremented by reader when it detects a lap
+ underrun_count: AtomicU64, // incremented by reader when ring is empty
+}
+```
+
+**`write()` — producer. Does NOT touch `read_pos`:**
+```rust
+pub fn write(&self, samples: &[i16]) -> usize {
+ let count = samples.len().min(RING_CAPACITY);
+ let w = self.write_pos.load(Ordering::Relaxed);
+
+ for i in 0..count {
+ unsafe {
+ let ptr = self.buf.as_ptr() as *mut i16;
+ *ptr.add((w + i) & RING_MASK) = samples[i];
+ }
+ }
+
+ self.write_pos.store(w.wrapping_add(count), Ordering::Release);
+ count
+}
+```
+
+**`read()` — consumer. Detects lap, self-corrects:**
+```rust
+pub fn read(&self, out: &mut [i16]) -> usize {
+ let w = self.write_pos.load(Ordering::Acquire);
+ let mut r = self.read_pos.load(Ordering::Relaxed);
+
+ let mut avail = w.wrapping_sub(r);
+
+ // Lap detection: writer has overwritten our unread data.
+ // Snap read_pos forward to oldest valid data in the buffer.
+ // Safe because we (the reader) are the sole owner of read_pos.
+ if avail > RING_CAPACITY {
+ r = w.wrapping_sub(RING_CAPACITY);
+ avail = RING_CAPACITY;
+ self.overflow_count.fetch_add(1, Ordering::Relaxed);
+ }
+
+ let count = out.len().min(avail);
+ if count == 0 {
+ if w == r {
+ self.underrun_count.fetch_add(1, Ordering::Relaxed);
+ }
+ return 0;
+ }
+
+ for i in 0..count {
+ out[i] = unsafe { *self.buf.as_ptr().add((r + i) & RING_MASK) };
+ }
+
+ self.read_pos.store(r.wrapping_add(count), Ordering::Release);
+ count
+}
+```
+
+**`available()` — clamped for external callers:**
+```rust
+pub fn available(&self) -> usize {
+ let w = self.write_pos.load(Ordering::Acquire);
+ let r = self.read_pos.load(Ordering::Relaxed);
+ w.wrapping_sub(r).min(RING_CAPACITY)
+}
+```
+
+**`free_space()` — keep for API compat:**
+```rust
+pub fn free_space(&self) -> usize {
+ RING_CAPACITY.saturating_sub(self.available())
+}
+```
+
+**Diagnostic accessors:**
+```rust
+pub fn overflow_count(&self) -> u64 {
+ self.overflow_count.load(Ordering::Relaxed)
+}
+
+pub fn underrun_count(&self) -> u64 {
+ self.underrun_count.load(Ordering::Relaxed)
+}
+```
+
+**Constructor:**
+```rust
+pub fn new() -> Self {
+ debug_assert!(RING_CAPACITY.is_power_of_two());
+ Self {
+ buf: Box::new([0i16; RING_CAPACITY]),
+ write_pos: AtomicUsize::new(0),
+ read_pos: AtomicUsize::new(0),
+ overflow_count: AtomicU64::new(0),
+ underrun_count: AtomicU64::new(0),
+ }
+}
+```
+
+**Imports to add:** `use std::sync::atomic::AtomicU64;`
+
+**Safety comment update:**
+```rust
+// SAFETY: AudioRing is SPSC — one thread writes (producer), one reads (consumer).
+// The producer only writes write_pos. The consumer only writes read_pos.
+// Neither thread writes the other's cursor. Buffer indices are derived from
+// the owning thread's cursor, ensuring no concurrent access to the same index.
+```
+
+---
+
+### Step 2: Add counter fields to `CallStats`
+
+**File:** `crates/wzp-android/src/stats.rs`
+
+Add three fields to the `CallStats` struct (after `fec_recovered`):
+
+```rust
+/// Playout ring overflow count (reader was lapped by writer).
+pub playout_overflows: u64,
+/// Playout ring underrun count (reader found empty buffer).
+pub playout_underruns: u64,
+/// Capture ring overflow count.
+pub capture_overflows: u64,
+```
+
+These derive `Default` (= 0) automatically via the existing `#[derive(Default)]`.
+
+---
+
+### Step 3: Wire ring diagnostics into engine stats + logging
+
+**File:** `crates/wzp-android/src/engine.rs`
+
+**3a.** In `get_stats()` (~line 181), populate the new fields:
+
+```rust
+stats.playout_overflows = self.state.playout_ring.overflow_count();
+stats.playout_underruns = self.state.playout_ring.underrun_count();
+stats.capture_overflows = self.state.capture_ring.overflow_count();
+```
+
+**3b.** In the recv task periodic stats log, add ring health:
+
+```rust
+info!(
+ frames_decoded,
+ fec_recovered,
+ recv_errors,
+ max_recv_gap_ms,
+ playout_avail = state.playout_ring.available(),
+ playout_overflows = state.playout_ring.overflow_count(),
+ playout_underruns = state.playout_ring.underrun_count(),
+ "recv stats"
+);
+```
+
+**3c.** In the send task periodic stats log, add capture ring health:
+
+```rust
+info!(
+ seq = s,
+ block_id,
+ frames_sent,
+ frames_dropped,
+ send_errors,
+ ring_avail = state.capture_ring.available(),
+ capture_overflows = state.capture_ring.overflow_count(),
+ "send stats"
+);
+```
+
+---
+
+### Step 4: Parse new stats in Kotlin
+
+**File:** `android/app/src/main/java/com/wzp/engine/CallStats.kt`
+
+Add fields to the data class:
+
+```kotlin
+val playoutOverflows: Long = 0,
+val playoutUnderruns: Long = 0,
+val captureOverflows: Long = 0,
+```
+
+Add parsing in `fromJson()`:
+
+```kotlin
+playoutOverflows = obj.optLong("playout_overflows", 0),
+playoutUnderruns = obj.optLong("playout_underruns", 0),
+captureOverflows = obj.optLong("capture_overflows", 0),
+```
+
+No UI changes needed — these fields will appear in debug report JSON automatically.
+
+---
+
+### Step 5: Unit tests
+
+**File:** `crates/wzp-android/src/audio_ring.rs` — add `#[cfg(test)] mod tests`
+
+```rust
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn capacity_is_power_of_two() {
+ assert!(RING_CAPACITY.is_power_of_two());
+ }
+
+ #[test]
+ fn basic_write_read() {
+ let ring = AudioRing::new();
+ let input: Vec = (0..960).map(|i| i as i16).collect();
+ ring.write(&input);
+ assert_eq!(ring.available(), 960);
+
+ let mut output = vec![0i16; 960];
+ let read = ring.read(&mut output);
+ assert_eq!(read, 960);
+ assert_eq!(output, input);
+ assert_eq!(ring.available(), 0);
+ }
+
+ #[test]
+ fn wraparound() {
+ let ring = AudioRing::new();
+ let frame = vec![42i16; 960];
+ // Write enough to wrap the buffer multiple times
+ for _ in 0..20 {
+ ring.write(&frame);
+ let mut out = vec![0i16; 960];
+ ring.read(&mut out);
+ assert!(out.iter().all(|&s| s == 42));
+ }
+ }
+
+ #[test]
+ fn overflow_detected_by_reader() {
+ let ring = AudioRing::new();
+ // Write more than RING_CAPACITY without reading
+ let big = vec![7i16; RING_CAPACITY + 960];
+ ring.write(&big[..RING_CAPACITY]);
+ ring.write(&big[RING_CAPACITY..]);
+
+ // Reader should detect lap
+ let mut out = vec![0i16; 960];
+ let read = ring.read(&mut out);
+ assert!(read > 0);
+ assert_eq!(ring.overflow_count(), 1);
+ // Data should be from the most recent writes
+ assert!(out.iter().all(|&s| s == 7));
+ }
+
+ #[test]
+ fn writer_never_modifies_read_pos() {
+ let ring = AudioRing::new();
+ // Read pos should stay at 0 until read() is called
+ let data = vec![1i16; RING_CAPACITY + 960];
+ ring.write(&data);
+ // read_pos is private, but we can check available() > CAPACITY
+ // which proves write() didn't advance read_pos
+ let w = ring.write_pos.load(std::sync::atomic::Ordering::Relaxed);
+ let r = ring.read_pos.load(std::sync::atomic::Ordering::Relaxed);
+ assert_eq!(r, 0, "write() must not modify read_pos");
+ assert!(w.wrapping_sub(r) > RING_CAPACITY);
+ }
+
+ #[test]
+ fn underrun_counted() {
+ let ring = AudioRing::new();
+ let mut out = vec![0i16; 960];
+ let read = ring.read(&mut out);
+ assert_eq!(read, 0);
+ assert_eq!(ring.underrun_count(), 1);
+ }
+
+ #[test]
+ fn overflow_recovery_reads_recent_data() {
+ let ring = AudioRing::new();
+ // Fill with old data
+ let old = vec![1i16; RING_CAPACITY];
+ ring.write(&old);
+ // Overwrite with new data (lapping the reader)
+ let new_data = vec![99i16; 960];
+ ring.write(&new_data);
+
+ // Reader should snap forward and get recent data
+ let mut out = vec![0i16; RING_CAPACITY];
+ let read = ring.read(&mut out);
+ assert_eq!(read, RING_CAPACITY);
+ // The last 960 samples should be 99
+ assert!(out[RING_CAPACITY - 960..].iter().all(|&s| s == 99));
+ assert_eq!(ring.overflow_count(), 1);
+ }
+}
+```
+
+---
+
+## Memory Ordering Reference
+
+| Operation | Ordering | Rationale |
+|-----------|----------|-----------|
+| `write_pos.store` in `write()` | Release | Buffer writes visible before cursor advances |
+| `write_pos.load` in `read()` | Acquire | Pairs with Release above — sees all buffer writes |
+| `write_pos.load` in `write()` | Relaxed | Writer is sole owner of write_pos |
+| `read_pos.load` in `read()` | Relaxed | Reader is sole owner of read_pos |
+| `read_pos.store` in `read()` | Release | Makes available() consistent from any thread |
+| `read_pos.load` in `available()` | Relaxed | Informational only, slight staleness OK |
+| All counters | Relaxed | Diagnostic only |
+
+---
+
+## Capacity Tradeoff
+
+| Capacity | Duration | Memory | Verdict |
+|----------|----------|--------|---------|
+| 8192 (2^13) | 170ms | 16KB | Less than current 200ms — risky |
+| **16384 (2^14)** | **341ms** | **32KB** | **70% more headroom, bitmask indexing** |
+| 32768 (2^15) | 682ms | 64KB | Excessive latency on overflow recovery |
+
+---
+
+## Verification
+
+1. `cargo test -p wzp-android` — new unit tests pass
+2. `cargo ndk -t arm64-v8a build --release -p wzp-android` — ARM cross-compile succeeds
+3. Build APK, install on both test devices (Nothing A059 + Pixel 6)
+4. 2+ minute call — verify no audio gaps
+5. Check debug report JSON: `playout_overflows` should be 0 or very small
+6. Check logcat `wzp_android` tag: send/recv stats show healthy ring state
+7. Stress test: play music through one device speaker while on call — forces high ring throughput
+
+---
+
+## Files to Modify
+
+| File | What changes |
+|------|-------------|
+| `crates/wzp-android/src/audio_ring.rs` | Complete rewrite — the core fix |
+| `crates/wzp-android/src/stats.rs` | Add 3 counter fields |
+| `crates/wzp-android/src/engine.rs` | Wire counters into get_stats() + periodic logs |
+| `android/app/src/main/java/com/wzp/engine/CallStats.kt` | Parse 3 new JSON fields |
+
+## What Does NOT Change
+
+- `AudioPipeline.kt` — calls `readAudio()`/`writeAudio()` unchanged; ring fix is transparent
+- `jni_bridge.rs` — JNI bridge passes through unchanged
+- `audio_android.rs` — separate Oboe-based ring, currently unused, different design
+- Relay code — relay is confirmed healthy
+- Desktop client — uses `Mutex + mpsc`, not `AudioRing`
diff --git a/vault/Android/Fix-Capture-Thread-Crash.md b/vault/Android/Fix-Capture-Thread-Crash.md
new file mode 100644
index 0000000..29c846f
--- /dev/null
+++ b/vault/Android/Fix-Capture-Thread-Crash.md
@@ -0,0 +1,154 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Fix: Capture/Playout Thread Use-After-Free on Hangup
+
+## Problem
+
+App crashes (SIGSEGV) when hanging up a call. The capture thread (`wzp-capture`) calls `engine.writeAudio()` via JNI after `teardown()` has freed the native engine handle. Same race exists for the playout thread's `readAudio()`.
+
+**Root cause:** TOCTOU race between the `nativeHandle == 0L` check in `WzpEngine.writeAudio()`/`readAudio()` and `destroy()` freeing the native memory on the ViewModel thread. Audio threads can't be joined (libcrypto TLS destructor crash), so there's no synchronization between `stopAudio()` and `destroy()`.
+
+**Full forensics:** `debug/INCIDENT-2026-04-06-capture-thread-use-after-free.md`
+
+---
+
+## Solution: Destroy Latch
+
+Add a `CountDownLatch(2)` that both audio threads count down after exiting their loops. `teardown()` awaits the latch (with timeout) before calling `destroy()`, guaranteeing no in-flight JNI calls.
+
+---
+
+## Implementation Steps
+
+### Step 1: Add a drain latch to `AudioPipeline`
+
+**File:** `android/app/src/main/java/com/wzp/audio/AudioPipeline.kt`
+
+Add a `CountDownLatch` field:
+
+```kotlin
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+class AudioPipeline(private val context: Context) {
+ // ... existing fields ...
+
+ /** Latch counted down by each audio thread after exiting its loop.
+ * stop() does NOT wait on this — teardown waits via awaitDrain(). */
+ private var drainLatch: CountDownLatch? = null
+```
+
+In `start()`, create the latch before spawning threads:
+
+```kotlin
+fun start(engine: WzpEngine) {
+ if (running) return
+ running = true
+ drainLatch = CountDownLatch(2) // one for capture, one for playout
+
+ captureThread = Thread({
+ runCapture(engine)
+ drainLatch?.countDown() // signal: capture loop exited
+ parkThread()
+ }, "wzp-capture").apply { ... }
+
+ playoutThread = Thread({
+ runPlayout(engine)
+ drainLatch?.countDown() // signal: playout loop exited
+ parkThread()
+ }, "wzp-playout").apply { ... }
+ // ...
+}
+```
+
+Add `awaitDrain()` — called by ViewModel before `destroy()`:
+
+```kotlin
+/** Block until both audio threads have exited their loops (max 200ms).
+ * After this returns, no more JNI calls to the engine will be made. */
+fun awaitDrain(): Boolean {
+ return drainLatch?.await(200, TimeUnit.MILLISECONDS) ?: true
+}
+```
+
+`stop()` remains unchanged (non-blocking, sets `running = false`).
+
+### Step 2: Update `CallViewModel.teardown()` to await drain
+
+**File:** `android/app/src/main/java/com/wzp/ui/call/CallViewModel.kt`
+
+Change teardown to wait for audio threads before destroying:
+
+```kotlin
+private fun teardown(stopService: Boolean = true) {
+ Log.i(TAG, "teardown: stopping audio, stopService=$stopService")
+ val hadCall = audioStarted
+ CallService.onStopFromNotification = null
+ stopAudio() // sets running=false (non-blocking)
+ stopStatsPolling()
+
+ // Wait for audio threads to exit their loops before destroying the engine.
+ // This guarantees no in-flight JNI calls to writeAudio/readAudio.
+ val drained = audioPipeline?.awaitDrain() ?: true
+ if (!drained) {
+ Log.w(TAG, "teardown: audio threads did not drain in time")
+ }
+ audioPipeline = null
+
+ Log.i(TAG, "teardown: stopping engine")
+ try { engine?.stopCall() } catch (e: Exception) { Log.w(TAG, "stopCall err: $e") }
+ try { engine?.destroy() } catch (e: Exception) { Log.w(TAG, "destroy err: $e") }
+ engine = null
+ engineInitialized = false
+ // ... rest unchanged
+}
+```
+
+**Key change:** `awaitDrain()` is called AFTER `stopAudio()` (which sets `running=false`) but BEFORE `engine?.destroy()`. The latch guarantees both threads have exited their `while(running)` loops and will never call `writeAudio`/`readAudio` again.
+
+Also move `audioPipeline = null` to after `awaitDrain()` to keep the reference alive for the latch call.
+
+### Step 3: Move `stopAudio()` pipeline nulling
+
+**File:** `android/app/src/main/java/com/wzp/ui/call/CallViewModel.kt`
+
+In `stopAudio()`, do NOT null out the pipeline — let `teardown()` handle it after drain:
+
+```kotlin
+private fun stopAudio() {
+ if (!audioStarted) return
+ audioPipeline?.stop() // sets running=false
+ // DON'T null audioPipeline here — teardown() needs it for awaitDrain()
+ audioRouteManager?.unregister()
+ audioRouteManager?.setSpeaker(false)
+ _isSpeaker.value = false
+ audioStarted = false
+}
+```
+
+---
+
+## Files to Modify
+
+| File | What changes |
+|------|-------------|
+| `android/.../audio/AudioPipeline.kt` | Add `CountDownLatch`, `countDown()` in threads, `awaitDrain()` method |
+| `android/.../ui/call/CallViewModel.kt` | `teardown()` calls `awaitDrain()` before `destroy()`; `stopAudio()` doesn't null pipeline |
+
+## What Does NOT Change
+
+- `WzpEngine.kt` — the `nativeHandle == 0L` guard stays as defense-in-depth
+- `jni_bridge.rs` — `panic::catch_unwind` stays as last resort
+- `AudioPipeline.stop()` — remains non-blocking
+- Thread parking — still needed to avoid libcrypto TLS crash
+
+## Verification
+
+1. Build APK, install on test device
+2. Make a call, hang up — verify no crash in logcat (`adb logcat -s AndroidRuntime:E DEBUG:F`)
+3. Rapid call/hangup/call/hangup cycles — stress the teardown path
+4. Check logcat for `teardown: audio threads did not drain in time` — should never appear under normal conditions
+5. Verify debug report still works after hangup (latch doesn't interfere with report collection)
diff --git a/vault/Android/Maintenance.md b/vault/Android/Maintenance.md
new file mode 100644
index 0000000..1ba828f
--- /dev/null
+++ b/vault/Android/Maintenance.md
@@ -0,0 +1,195 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Maintenance Guide
+
+## Code Map — Where to Change Things
+
+### Changing the relay address or room
+
+Edit `CallViewModel.kt`:
+```kotlin
+companion object {
+ const val DEFAULT_RELAY = "172.16.81.125:4433"
+ const val DEFAULT_ROOM = "android"
+}
+```
+
+For a proper settings screen, add a new Composable in `ui/` that persists to `SharedPreferences` and passes values to `viewModel.startCall(relay, room)`.
+
+### Adding authentication
+
+1. In `CallViewModel.startCall()`, pass a token parameter
+2. In `engine.rs`, after QUIC connect but before CallOffer, send:
+ ```rust
+ transport.send_signal(&SignalMessage::AuthToken { token: auth_token }).await?;
+ ```
+3. Wait for the relay to accept before proceeding to handshake
+4. Start relay with `--auth-url `
+
+### Enabling media encryption
+
+The crypto session is already derived in `engine.rs` but not applied to packets. To enable:
+
+1. Pass `_session` (currently unused) to the send/recv tasks
+2. Before `transport.send_media()`, encrypt the payload:
+ ```rust
+ let mut ciphertext = Vec::new();
+ session.encrypt(&header_bytes, &payload, &mut ciphertext)?;
+ packet.payload = Bytes::from(ciphertext);
+ ```
+3. After `transport.recv_media()`, decrypt:
+ ```rust
+ let mut plaintext = Vec::new();
+ session.decrypt(&header_bytes, &pkt.payload, &mut plaintext)?;
+ pkt.payload = Bytes::from(plaintext);
+ ```
+
+### Adding a new codec / quality profile
+
+1. Define the profile in `wzp-proto/src/codec_id.rs`
+2. Implement `AudioEncoder`/`AudioDecoder` traits in `wzp-codec`
+3. Register in `AdaptiveEncoder`/`AdaptiveDecoder` switch logic
+4. Add to `supported_profiles` in the CallOffer (engine.rs)
+
+### Changing audio parameters
+
+- **Sample rate**: Change `FRAME_SAMPLES` in `audio_android.rs` and `WzpOboeConfig.sample_rate` in `oboe_bridge.cpp`. Must match the codec's expected rate.
+- **Frame duration**: Change `FRAME_SAMPLES` (960 = 20ms at 48kHz, 1920 = 40ms)
+- **Ring buffer size**: Change `RING_CAPACITY` in `audio_android.rs`
+- **AEC tail length**: Change the `100` in `Pipeline::new()` → `EchoCanceller::new(48000, 100)`
+
+### Adding x86_64 support (emulator)
+
+1. `build.gradle.kts`: add `"x86_64"` to `abiFilters`
+2. `cargoNdkBuild` task: add `-t x86_64`
+3. `build.rs`: handle `x86_64-linux-android` target for Oboe
+4. Note: Oboe in the emulator uses a different audio HAL — audio quality will differ
+
+## Dependency Overview
+
+### Rust Crate Dependencies (wzp-android)
+
+| Crate | Version | Purpose | Upgrade risk |
+|-------|---------|---------|--------------|
+| `jni` | 0.21 | Java FFI | Low — stable API |
+| `tokio` | 1.x | Async runtime | Low |
+| `quinn` | 0.11 | QUIC transport | Medium — breaking changes between 0.x |
+| `rustls` | 0.23 | TLS for QUIC | Medium — tied to quinn version |
+| `serde_json` | 1.x | Stats serialization | Low |
+| `anyhow` | 1.x | Error handling | Low |
+| `tracing` | 0.1 | Logging | Low |
+| `rand` | 0.8 | Random seed generation | Low |
+
+### Workspace Crate Dependencies
+
+| Crate | Purpose | Key trait |
+|-------|---------|-----------|
+| `wzp-proto` | Shared types and traits | `MediaTransport`, `AudioEncoder`, `KeyExchange` |
+| `wzp-codec` | Opus + Codec2 + signal processing | `AdaptiveEncoder`, `EchoCanceller` |
+| `wzp-fec` | RaptorQ FEC | `RaptorQFecEncoder` |
+| `wzp-crypto` | Key exchange + encryption | `WarzoneKeyExchange`, `ChaChaSession` |
+| `wzp-transport` | QUIC connection management | `QuinnTransport`, `connect()` |
+
+### Android/Kotlin Dependencies
+
+| Library | Version | Purpose |
+|---------|---------|---------|
+| `compose-bom` | 2024.01.00 | Compose version alignment |
+| `material3` | (from BOM) | UI components |
+| `activity-compose` | 1.8.2 | Activity integration |
+| `lifecycle-runtime-ktx` | 2.7.0 | ViewModel + coroutines |
+| `core-ktx` | 1.12.0 | Kotlin extensions |
+
+## Updating Dependencies
+
+### Rust
+
+```bash
+cargo update -p wzp-android
+cargo ndk -t arm64-v8a build --release -p wzp-android
+```
+
+Watch for `quinn`/`rustls` version coupling. They must be compatible:
+- quinn 0.11 requires rustls 0.23
+
+### Android/Kotlin
+
+Update versions in `android/app/build.gradle.kts`. Key compatibility:
+- `kotlinCompilerExtensionVersion` must match the Kotlin version
+- `compose-bom` version determines all Compose library versions
+- `compileSdk` and `targetSdk` should stay in sync
+
+### NDK
+
+If upgrading the NDK:
+1. Update `ndkVersion` in `build.gradle.kts`
+2. Update `ANDROID_NDK_HOME` environment variable
+3. Update `CC_aarch64_linux_android` and friends
+4. Verify Oboe still builds with the new toolchain
+
+## Key Invariants to Preserve
+
+1. **JNI function names must match package structure**: If the Kotlin package changes, all `Java_com_wzp_engine_WzpEngine_*` functions in `jni_bridge.rs` must be renamed.
+
+2. **Manifest uses fully-qualified class names**: Never use `.ClassName` shorthand because the Gradle namespace (`com.wzp.phone`) differs from the Kotlin package (`com.wzp`).
+
+3. **Stats JSON field names are snake_case**: Rust serializes with serde defaults (snake_case). Kotlin's `CallStats.fromJson()` expects `duration_secs`, `loss_pct`, etc.
+
+4. **Ring buffer ordering**: Producer uses Release store on write index, consumer uses Acquire load. Breaking this causes torn reads.
+
+5. **Codec thread owns Pipeline**: Pipeline is `!Send` (Opus encoder state). It must never be accessed from another thread.
+
+6. **panic::catch_unwind on all JNI functions**: Rust panics unwinding across the FFI boundary is UB. Every JNI-exposed function must catch panics.
+
+7. **Channel capacity (64)**: Both `send_tx` and `recv_tx` are bounded at 64 packets. If the network is slow, packets are dropped (`try_send` best-effort).
+
+## Testing
+
+### Unit Tests (Rust)
+
+```bash
+# Run all workspace tests (host, not Android)
+cargo test
+
+# Run only wzp-android tests (uses oboe_stub.cpp on host)
+cargo test -p wzp-android
+```
+
+Note: Pipeline, codec, FEC, crypto tests run on the host. Audio tests use stubs.
+
+### On-Device Testing
+
+1. Build and install debug APK
+2. Open app, tap CALL
+3. Verify in logcat:
+ - `WzpEngine created via JNI`
+ - `connecting to relay...`
+ - `QUIC connected to relay`
+ - `CallOffer sent`
+ - `handshake complete, call active`
+ - `codec thread started`
+4. Check stats overlay: frame counters should increment
+5. Speak into mic — other connected device should hear audio
+
+### Stress Testing
+
+- Run a call for 30+ minutes — check for memory leaks (stats should be stable)
+- Kill and restart the relay — client should eventually get a connection error
+- Toggle mute rapidly — verify no crashes
+- Switch speaker on/off — verify audio route changes
+
+## Performance Monitoring
+
+Key metrics to watch during a call:
+
+| Metric | Healthy Range | Warning | Critical |
+|--------|--------------|---------|----------|
+| frames_encoded | Increasing ~50/sec | Stalled | 0 |
+| frames_decoded | Increasing ~50/sec | Stalled | 0 |
+| underruns | < 5/min | > 20/min | > 100/min |
+| jitter_buffer_depth | 2-5 | 0 or >10 | N/A |
+| loss_pct | < 5% | 5-20% | > 20% |
+| rtt_ms | < 100ms | 100-300ms | > 500ms |
diff --git a/vault/Android/README.md b/vault/Android/README.md
new file mode 100644
index 0000000..8bcdb50
--- /dev/null
+++ b/vault/Android/README.md
@@ -0,0 +1,46 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# WarzonePhone Android Client
+
+The WZP Android client is a native VoIP application built with Kotlin/Jetpack Compose on top of a Rust audio engine. It connects to WZP relay servers over QUIC, providing encrypted voice calls with adaptive quality, forward error correction, and acoustic echo cancellation.
+
+## Quick Start
+
+1. **Build**: `cd android && ./gradlew assembleRelease` (requires NDK 26.1, cargo-ndk)
+2. **Install**: `adb install app/build/outputs/apk/release/app-release.apk`
+3. **Run**: Open "WZ Phone", tap **CALL** to connect to the hardcoded relay
+4. **Relay**: Must be running at the configured address (default `172.16.81.125:4433`)
+
+## Current State (April 2025)
+
+| Feature | Status |
+|---------|--------|
+| QUIC transport to relay | Working |
+| Crypto handshake (X25519 + Ed25519) | Working |
+| Opus 24k encoding/decoding | Working |
+| Oboe audio I/O (48kHz mono) | Working |
+| AEC / AGC signal processing | Working |
+| RaptorQ FEC | Wired (repair symbols not sent yet) |
+| Jitter buffer | Working |
+| Adaptive quality switching | Codec-ready, not network-driven yet |
+| Authentication (featherChat) | Skipped (relay has no --auth-url) |
+| Media encryption (ChaCha20-Poly1305) | Session derived but not applied to packets |
+| Foreground service / wake locks | Implemented, not started from UI |
+
+## Documentation Index
+
+- [Architecture](architecture.md) - System design, data flow diagrams, thread model
+- [Build Guide](build-guide.md) - Build environment setup, dependencies, signing
+- [Debugging](debugging.md) - Crash diagnosis, logcat filters, common issues
+- [Maintenance](maintenance.md) - Code map, dependency management, upgrade paths
+- [Roadmap](roadmap.md) - Planned work and known gaps
+
+## Key Design Decisions
+
+- **Rust native engine**: All audio processing, codecs, FEC, crypto, and networking run in Rust. Kotlin is UI-only.
+- **Lock-free audio**: SPSC ring buffers with atomic ordering between Oboe C++ callbacks and the Rust codec thread. No mutexes in the audio path.
+- **cargo-ndk**: The native library (`libwzp_android.so`) is cross-compiled for `arm64-v8a` using cargo-ndk, invoked automatically by Gradle's `cargoNdkBuild` task.
+- **Single-activity Compose**: One `CallActivity` hosts all UI via Jetpack Compose with `CallViewModel` as the state holder.
diff --git a/vault/Android/Roadmap.md b/vault/Android/Roadmap.md
new file mode 100644
index 0000000..1c06085
--- /dev/null
+++ b/vault/Android/Roadmap.md
@@ -0,0 +1,117 @@
+---
+tags: [android, wzp]
+type: reference
+---
+
+# Roadmap & Known Gaps
+
+## Current State Summary
+
+The Android client can connect to a WZP relay, complete the crypto handshake, and exchange audio in real-time. Two phones on the same network can talk to each other through the relay.
+
+## What Works (April 2025)
+
+- QUIC transport to relay with room-based SFU
+- Full crypto handshake (X25519 ephemeral + Ed25519 signatures)
+- Opus 24kbps encoding/decoding at 48kHz
+- Lock-free audio I/O via Oboe (capture + playout)
+- AEC (acoustic echo cancellation) with 100ms tail
+- AGC (automatic gain control)
+- RaptorQ FEC encoder/decoder (wired to pipeline)
+- Adaptive jitter buffer (10-250 packets)
+- UI with connect/disconnect, mute, speaker, live stats
+- Random identity seed per app launch
+
+## Known Gaps
+
+### P0 — Must fix for usable calls
+
+| Gap | Impact | Where to fix |
+|-----|--------|--------------|
+| **Media encryption not applied** | Audio sent in cleartext over QUIC | `engine.rs` — pass `_session` to send/recv, encrypt/decrypt payloads |
+| **FEC repair symbols not sent** | No loss recovery — audio gaps on packet loss | `engine.rs` send task — call `fec_encoder.generate_repair()` and send repair packets |
+| **Quality reports not sent** | Relay can't monitor quality, no adaptive switching | `engine.rs` — periodically attach `QualityReport` to MediaPacket header |
+| **CallService not started** | Call dies when app is backgrounded | `CallViewModel.startCall()` — call `CallService.start(context)` |
+
+### P1 — Important for production
+
+| Gap | Impact | Where to fix |
+|-----|--------|--------------|
+| **Hardcoded relay address** | Can't change server without rebuild | Add settings screen with `SharedPreferences` |
+| **No reconnection logic** | Connection drop = call over | `engine.rs` network task — detect disconnect, retry with backoff |
+| **No adaptive quality switching** | Stays on GOOD profile even in bad conditions | Wire `AdaptiveQualityController` to network path quality from `QuinnTransport` |
+| **Identity seed not persisted** | New identity every launch | Save seed to Android Keystore or SharedPreferences |
+| **No Bluetooth audio routing** | `AudioRouteManager` exists but not wired to UI | Add Bluetooth button to InCallScreen, call `AudioRouteManager` methods |
+| **No ringtone/notification for incoming** | Only outgoing calls supported | Need signaling for call setup (currently both sides initiate independently) |
+
+### P2 — Nice to have
+
+| Gap | Impact | Where to fix |
+|-----|--------|--------------|
+| **No android_logger** | Rust tracing output lost on Android | Add `android_logger` crate, init in `nativeInit()` |
+| **Stats don't include network metrics** | Loss/RTT/jitter always 0 | Feed `QuinnTransport.path_quality()` back to stats |
+| **No ProGuard/R8 minification** | Release APK larger than necessary | Enable `isMinifyEnabled = true` in build.gradle.kts |
+| **Single ABI (arm64-v8a)** | No support for older 32-bit devices or emulators | Add `armeabi-v7a` and `x86_64` to cargo-ndk build |
+| **No call history** | Can't see past calls | Add Room database for call log |
+| **No contact integration** | Manual relay/room entry | Add contacts with fingerprint-based identity |
+
+## Architecture Evolution Plan
+
+### Phase 1: Make Calls Reliable (current → next)
+
+```
+[x] QUIC connection to relay
+[x] Crypto handshake
+[x] Audio encode/decode pipeline
+[ ] Media encryption (ChaCha20-Poly1305)
+[ ] FEC repair packet transmission
+[ ] Foreground service for background calls
+[ ] Reconnection on network change
+```
+
+### Phase 2: Quality & Polish
+
+```
+[ ] Adaptive quality (GOOD → DEGRADED → CATASTROPHIC switching)
+[ ] Quality reports in MediaPacket headers
+[ ] Network path quality display (real RTT, loss, jitter)
+[ ] Settings screen (relay, room, seed persistence)
+[ ] Bluetooth/wired headset audio routing
+[ ] Rust android_logger for debugging
+```
+
+### Phase 3: Production Features
+
+```
+[ ] featherChat authentication
+[ ] Persistent identity (Android Keystore)
+[ ] Push notifications for incoming calls
+[ ] Multi-party rooms (already supported by relay)
+[ ] Call transfer
+[ ] End-to-end encryption (bypass relay decryption)
+```
+
+## Dependency Upgrade Path
+
+### quinn 0.11 → 0.12 (when released)
+
+Quinn 0.12 will likely require rustls 0.24. Update both together:
+1. `Cargo.toml`: bump quinn and rustls versions
+2. Check `client_config()` and `server_config()` in wzp-transport for API changes
+3. DATAGRAM API may change — check `send_datagram()` / `read_datagram()`
+
+### Compose BOM 2024.01 → 2025.x
+
+The `LinearProgressIndicator` `progress` parameter changed from `Float` to `() -> Float` in Material3 1.2+. If upgrading the BOM:
+
+```kotlin
+// Old (current):
+LinearProgressIndicator(progress = level, ...)
+
+// New (Material3 1.2+):
+LinearProgressIndicator(progress = { level }, ...)
+```
+
+### Kotlin 1.9 → 2.x
+
+Kotlin 2.0 changed the Compose compiler plugin. Update `kotlinCompilerExtensionVersion` in `composeOptions` and the Kotlin Gradle plugin version together.
diff --git a/vault/Architecture/Architecture.md b/vault/Architecture/Architecture.md
new file mode 100644
index 0000000..4823174
--- /dev/null
+++ b/vault/Architecture/Architecture.md
@@ -0,0 +1,1245 @@
+# WarzonePhone Architecture
+
+> Custom lossy VoIP protocol built in Rust. E2E encrypted, FEC-protected, adaptive quality, designed for hostile network conditions.
+
+## System Overview
+
+```mermaid
+graph TB
+ subgraph "Client A (Desktop / Android / CLI)"
+ MIC[Microphone] --> DN[NoiseSuppressor
RNNoise ML]
+ DN --> SD[SilenceDetector
VAD + Hangover]
+ SD --> ENC[CallEncoder
Opus / Codec2]
+ ENC --> FEC_E[FEC Encoder
RaptorQ]
+ FEC_E --> CRYPT_E[ChaCha20-Poly1305
Encrypt]
+ CRYPT_E --> QUIC_S[QUIC Datagram
Send]
+
+ QUIC_R[QUIC Datagram
Recv] --> CRYPT_D[ChaCha20-Poly1305
Decrypt]
+ CRYPT_D --> FEC_D[FEC Decoder
RaptorQ]
+ FEC_D --> JIT[JitterBuffer
Adaptive Playout]
+ JIT --> DEC[CallDecoder
Opus / Codec2]
+ DEC --> SPK[Speaker]
+ end
+
+ subgraph "Relay (SFU)"
+ ACCEPT[Accept QUIC] --> AUTH{Auth?}
+ AUTH -->|token| VALIDATE[POST /v1/auth/validate]
+ AUTH -->|no auth| HS
+ VALIDATE --> HS[Crypto Handshake
X25519 + Ed25519]
+ HS --> ROOM[Room Manager
Named Rooms via SNI]
+ ROOM --> FWD[Forward to
Other Participants]
+ end
+
+ subgraph "Client B"
+ B_SPK[Speaker]
+ B_MIC[Microphone]
+ end
+
+ QUIC_S -->|UDP / QUIC| ACCEPT
+ FWD -->|UDP / QUIC| QUIC_R
+ B_MIC -.->|same pipeline| ACCEPT
+ FWD -.->|same pipeline| B_SPK
+
+ style MIC fill:#4a9eff,color:#fff
+ style SPK fill:#4a9eff,color:#fff
+ style B_MIC fill:#4a9eff,color:#fff
+ style B_SPK fill:#4a9eff,color:#fff
+ style ROOM fill:#ff9f43,color:#fff
+ style CRYPT_E fill:#ee5a24,color:#fff
+ style CRYPT_D fill:#ee5a24,color:#fff
+```
+
+## Crate Dependency Graph
+
+```mermaid
+graph TD
+ PROTO["wzp-proto
Types, Traits, Wire Format"]
+
+ CODEC["wzp-codec
Opus + Codec2 + RNNoise"]
+ FEC["wzp-fec
RaptorQ FEC"]
+ CRYPTO["wzp-crypto
ChaCha20 + Identity"]
+ TRANSPORT["wzp-transport
QUIC / Quinn"]
+ VIDEO["wzp-video
H.264 + H.265 + AV1"]
+
+ RELAY["wzp-relay
Relay Daemon"]
+ CLIENT["wzp-client
CLI + Call Engine"]
+ WEB["wzp-web
Browser Bridge"]
+
+ PROTO --> CODEC
+ PROTO --> FEC
+ PROTO --> CRYPTO
+ PROTO --> TRANSPORT
+ PROTO --> VIDEO
+
+ CODEC --> CLIENT
+ FEC --> CLIENT
+ CRYPTO --> CLIENT
+ TRANSPORT --> CLIENT
+ VIDEO --> CLIENT
+
+ CODEC --> RELAY
+ FEC --> RELAY
+ CRYPTO --> RELAY
+ TRANSPORT --> RELAY
+ VIDEO --> RELAY
+
+ CLIENT --> WEB
+ TRANSPORT --> WEB
+ CRYPTO --> WEB
+
+ FC["warzone-protocol
featherChat Identity"] -.->|path dep| CRYPTO
+
+ style PROTO fill:#6c5ce7,color:#fff
+ style RELAY fill:#ff9f43,color:#fff
+ style CLIENT fill:#00b894,color:#fff
+ style WEB fill:#0984e3,color:#fff
+ style FC fill:#fd79a8,color:#fff
+ style VIDEO fill:#a29bfe,color:#fff
+```
+
+**Star pattern**: Each leaf crate (`wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`, `wzp-video`) depends only on `wzp-proto`. No leaf depends on another leaf. Integration crates (`wzp-relay`, `wzp-client`, `wzp-web`) depend on all leaves.
+
+## Audio Encode Pipeline
+
+```mermaid
+sequenceDiagram
+ participant Mic as Microphone
(48kHz)
+ participant Ring as SPSC Ring
(lock-free)
+ participant RNN as RNNoise
(2 x 480)
+ participant VAD as SilenceDetector
+ participant Codec as Opus / Codec2
+ participant DT as DredTuner
(wzp-proto)
+ participant FEC as RaptorQ FEC
+ participant INT as Interleaver
(depth=3)
+ participant HDR as MediaHeader
(16B or Mini 5B)
+ participant Enc as ChaCha20-Poly1305
+ participant QUIC as QUIC Datagram
+ participant QPS as QuinnPathSnapshot
+
+ Mic->>Ring: f32 x 512 (macOS callback)
+ Ring->>Ring: Accumulate to 960 samples
+ Ring->>RNN: PCM i16 x 960 (20ms frame)
+ RNN->>VAD: Denoised audio
+ alt Speech active (or hangover)
+ VAD->>Codec: Encode active frame
+ else Silence (>100ms)
+ VAD->>Codec: ComfortNoise (every 200ms)
+ end
+
+ Note over QPS,DT: Every 25 frames (~500ms)
+ QPS->>DT: loss_pct, rtt_ms, jitter_ms
+ DT->>Codec: set_dred_duration() + set_expected_loss()
+
+ alt Opus tier (any bitrate)
+ Codec->>HDR: Compressed bytes + DRED side-channel (no RaptorQ)
+ else Codec2 tier
+ Codec->>FEC: Compressed bytes (pad to 256B symbol)
+ FEC->>FEC: Accumulate block (5-10 symbols)
+ FEC->>INT: Source + repair symbols
+ INT->>HDR: Interleaved packets
+ end
+ HDR->>Enc: Header as AAD
+ Enc->>QUIC: Encrypted payload + 16B tag
+```
+
+### Key Details
+
+- macOS delivers **512 f32** samples per callback (not configurable to 960)
+- Ring buffer accumulates to **960 samples** (20ms at 48 kHz) for codec frame
+- RNNoise processes **2 x 480** samples (ML-based noise suppression via nnnoiseless)
+- Silence detection uses VAD + 100ms hangover before switching to ComfortNoise
+- FEC symbols are padded to **256 bytes** with a 2-byte LE length prefix
+- MiniHeaders (5 bytes) replace full headers (16 bytes) for 49 of every 50 audio frames; video always uses full headers
+- DRED tuner polls quinn path stats every 25 frames (~500ms) and adjusts DRED lookback duration continuously
+- Opus tiers bypass RaptorQ entirely -- DRED handles loss recovery at the codec layer
+- Opus6k DRED window: 1040ms (maximum libopus allows)
+
+## Audio Decode Pipeline
+
+```mermaid
+sequenceDiagram
+ participant QUIC as QUIC Datagram
+ participant Dec as ChaCha20-Poly1305
+ participant AR as Anti-Replay
(sliding window)
+ participant HDR as Header Parse
+ participant DEINT as De-interleaver
+ participant FEC as RaptorQ FEC
(reconstruct)
+ participant JIT as JitterBuffer
(BTreeMap)
+ participant Codec as Opus / Codec2
+ participant Ring as SPSC Ring
(lock-free)
+ participant SPK as Speaker
+
+ QUIC->>Dec: Encrypted packet
+ Dec->>AR: Decrypt (header = AAD)
+ AR->>AR: Check seq window (reject replay)
+ AR->>HDR: Verified packet
+
+ alt Opus packet
+ HDR->>JIT: Direct to jitter buffer (no FEC/interleave)
+ else Codec2 packet
+ HDR->>DEINT: MediaHeader + payload
+ DEINT->>FEC: Reordered symbols by block
+ FEC->>FEC: Attempt decode (need K of K+R)
+ FEC->>JIT: Recovered audio frames
+ end
+
+ JIT->>JIT: BTreeMap ordered by seq
+ JIT->>JIT: Wait until depth >= target
+
+ alt Packet present
+ JIT->>Codec: Pop lowest seq frame
+ else Packet missing (Opus)
+ JIT->>Codec: DRED reconstruction (neural)
+ alt DRED fails or unavailable
+ Codec->>Codec: Classical PLC fallback
+ end
+ else Packet missing (Codec2)
+ Codec->>Codec: Classical PLC
+ end
+
+ Codec->>Ring: PCM i16 x 960
+ Ring->>SPK: Audio callback pulls samples
+```
+
+### Key Details
+
+- Anti-replay uses a **64-packet sliding window** to reject duplicates
+- FEC decoder needs any **K of K+R** symbols to reconstruct a block
+- Jitter buffer target: **10 packets (200ms)** for client, **50 packets (1s)** for relay
+- Desktop client uses **direct playout** (no jitter buffer) with lock-free ring
+- Codec2 frames at 8 kHz are resampled to 48 kHz transparently
+- DRED reconstruction: on packet loss, decoder tries neural DRED reconstruction before falling back to classical PLC
+- Jitter-spike detection pre-emptively boosts DRED to ceiling when jitter variance spikes >30%
+
+## Relay SFU Forwarding
+
+```mermaid
+graph TB
+ subgraph "Room Mode (Default SFU)"
+ C1[Client 1
Alice] -->|"QUIC SNI=room-hash"| RM[Room Manager]
+ C2[Client 2
Bob] -->|"QUIC SNI=room-hash"| RM
+ C3[Client 3
Charlie] -->|"QUIC SNI=room-hash"| RM
+ RM --> R1["Room 'podcast'"]
+ R1 -->|"fan-out (skip sender)"| C1
+ R1 -->|"fan-out (skip sender)"| C2
+ R1 -->|"fan-out (skip sender)"| C3
+ end
+
+ subgraph "Forward Mode (--remote)"
+ C4[Client] -->|QUIC| RA[Relay A]
+ RA -->|"FEC decode
jitter buffer
FEC re-encode"| RB[Relay B
--remote]
+ RB -->|QUIC| C5[Client]
+ end
+
+ subgraph "Probe Mode (--probe)"
+ PA[Relay A] -->|"Ping 1/s
~50 bytes"| PB[Relay B]
+ PB -->|Pong| PA
+ PA --> PM[Prometheus
RTT / Loss / Jitter]
+ end
+
+ style RM fill:#ff9f43,color:#fff
+ style R1 fill:#fdcb6e
+ style PM fill:#0984e3,color:#fff
+```
+
+### SFU Fan-out Rules
+
+1. Each incoming datagram is forwarded to all other participants in the room
+2. The sender is excluded from fan-out (no echo)
+3. If one send fails, the relay continues to the next participant (best-effort)
+4. The relay never decodes or re-encodes audio (preserves E2E encryption)
+5. With trunking enabled, packets to the same receiver are batched into TrunkFrames (flushed every 5ms)
+6. Relay tracks per-participant quality from QualityReport trailers and broadcasts `QualityDirective` when the room-wide tier degrades (coordinated codec switching)
+
+## Federation Topology
+
+```mermaid
+graph TB
+ subgraph "Relay A (EU)"
+ A_R["Room Manager"]
+ A_F["Federation
Manager"]
+ A1["Alice (local)"]
+ A2["Bob (local)"]
+ end
+
+ subgraph "Relay B (US)"
+ B_R["Room Manager"]
+ B_F["Federation
Manager"]
+ B1["Charlie (local)"]
+ end
+
+ subgraph "Relay C (APAC)"
+ C_R["Room Manager"]
+ C_F["Federation
Manager"]
+ C1["Dave (local)"]
+ end
+
+ A1 -->|media| A_R
+ A2 -->|media| A_R
+ B1 -->|media| B_R
+ C1 -->|media| C_R
+
+ A_F <-->|"SNI='_federation'
GlobalRoomActive
media forward"| B_F
+ A_F <-->|"SNI='_federation'
GlobalRoomActive
media forward"| C_F
+ B_F <-->|"SNI='_federation'
GlobalRoomActive
media forward"| C_F
+
+ A_R --> A_F
+ B_R --> B_F
+ C_R --> C_F
+
+ style A_F fill:#6c5ce7,color:#fff
+ style B_F fill:#6c5ce7,color:#fff
+ style C_F fill:#6c5ce7,color:#fff
+ style A_R fill:#ff9f43,color:#fff
+ style B_R fill:#ff9f43,color:#fff
+ style C_R fill:#ff9f43,color:#fff
+```
+
+### Federation Protocol Flow
+
+```mermaid
+sequenceDiagram
+ participant RA as Relay A
+ participant RB as Relay B
+
+ Note over RA: Startup: connect to configured peers
+
+ RA->>RB: QUIC connect (SNI="_federation")
+ RA->>RB: FederationHello { tls_fingerprint }
+ RB->>RB: Verify fingerprint against [[trusted]]
+
+ Note over RA,RB: Federation link established
+
+ Note over RA: Alice joins global room "podcast"
+ RA->>RB: GlobalRoomActive { room: "podcast" }
+
+ Note over RB: Charlie joins global room "podcast"
+ RB->>RA: GlobalRoomActive { room: "podcast" }
+
+ Note over RA,RB: Media bridging active
+
+ loop Every media packet in global room
+ RA->>RB: [room_hash:8][encrypted_media]
+ RB->>RA: [room_hash:8][encrypted_media]
+ end
+
+ Note over RA: Last local participant leaves
+ RA->>RB: GlobalRoomInactive { room: "podcast" }
+```
+
+## Wire Formats
+
+### `MediaHeader` v2 (16 bytes, byte-aligned)
+
+```
+Byte 0: version (u8) 0x02
+Byte 1: flags (u8) [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
+ T = FEC repair, Q = QualityReport trailer
+ KeyFrame = packet belongs to an I-frame (video)
+ FrameEnd = last packet of an access unit (video)
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8) widened from 4-bit (room for 256 codec IDs)
+Byte 4: stream_id (u8) simulcast layer; 0=base
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE) wrapping packet sequence number
+Bytes 10-13: timestamp_ms (u32 BE) milliseconds since session start
+Bytes 14-15: fec_block_id (u16 BE)
+ audio: low 8 bits = block_id, high 8 bits = symbol_idx
+ video: full u16 block_id (large blocks for I-frames)
+```
+
+#### CodecID Values
+
+**Audio codecs (media_type = 0)**
+
+| Value | Codec | Bitrate | Sample Rate | Frame Duration |
+|-------|-------|---------|-------------|---------------|
+| 0 | Opus 24k | 24 kbps | 48 kHz | 20ms |
+| 1 | Opus 16k | 16 kbps | 48 kHz | 20ms |
+| 2 | Opus 6k | 6 kbps | 48 kHz | 40ms |
+| 3 | Codec2 3200 | 3.2 kbps | 8 kHz | 20ms |
+| 4 | Codec2 1200 | 1.2 kbps | 8 kHz | 40ms |
+| 5 | ComfortNoise | 0 | 48 kHz | 20ms |
+| 6 | Opus 32k | 32 kbps | 48 kHz | 20ms |
+| 7 | Opus 48k | 48 kbps | 48 kHz | 20ms |
+| 8 | Opus 64k | 64 kbps | 48 kHz | 20ms |
+
+**Video codecs (media_type = 1)**
+
+| Value | Codec | Notes |
+|-------|-------|-------|
+| 9 | H.264 Baseline | Universal HW encode coverage |
+| 10 | H.264 Main | Slight quality win over baseline |
+| 11 | H.265 Main | Apple A10+, Snapdragon ~2017, NVENC GTX 9xx+; ~30% better than H.264 |
+| 12 | AV1 Main | Apple M3/A17+, Snapdragon 8 Gen 3+, RTX 40+; best efficiency, narrow HW |
+
+### `MiniHeader` v2 (5 bytes)
+
+```
+[FRAME_TYPE_MINI = 0x01]
+Byte 0: seq_delta (u8) delta from last full header's seq
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
+```
+
+Used for audio only (49 of every 50 frames). Saves 11 bytes per audio packet vs the full 16B header. Full header is sent every 50th frame to resynchronize state. Video always uses full 16B headers.
+
+### TrunkFrame (batched datagrams)
+
+```
+[count: u16]
+ [session_id: 2][len: u16][payload: len] x count
+```
+
+Packs multiple session packets into one QUIC datagram. Maximum 10 entries or PMTUD-discovered MTU (starts at 1200, grows to ~1452 on Ethernet), flushed every 5ms.
+
+### QualityReport (4 bytes, optional trailer)
+
+```
+Byte 0: loss_pct (0-255 maps to 0-100%)
+Byte 1: rtt_4ms (0-255 maps to 0-1020ms, resolution 4ms)
+Byte 2: jitter_ms (0-255ms)
+Byte 3: bitrate_cap_kbps (0-255 kbps)
+```
+
+Appended to a media packet when the Q flag is set in the MediaHeader.
+
+## Path MTU Discovery
+
+Quinn's PLPMTUD is enabled with:
+- `initial_mtu`: 1200 bytes (QUIC minimum, always safe)
+- `upper_bound`: 1452 bytes (Ethernet minus IP/UDP/QUIC headers)
+- `interval`: 300s (re-probe every 5 minutes)
+- `black_hole_cooldown`: 30s (faster retry on lossy links)
+
+The discovered MTU is exposed via `QuinnPathSnapshot::current_mtu` and used by:
+- `TrunkedForwarder`: refreshes `max_bytes` on every send to fill larger datagrams
+- Future video framer: larger MTU = fewer application-layer fragments per frame
+
+## Continuous DRED Tuning
+
+Instead of locking DRED duration to 3 discrete quality tiers, the `DredTuner` (in `wzp-proto::dred_tuner`) maps live path quality to a continuous DRED duration:
+
+| Input | Source | Update Rate |
+|-------|--------|-------------|
+| Loss % | `QuinnPathSnapshot::loss_pct` (from quinn ACK frames) | Every 25 packets (~500ms) |
+| RTT ms | `QuinnPathSnapshot::rtt_ms` (quinn congestion controller) | Every 25 packets |
+| Jitter ms | `PathMonitor::jitter_ms` (EWMA of RTT variance) | Every 25 packets |
+
+### Mapping Logic
+
+- **Baseline**: codec-tier default (Studio=100ms, Good=200ms, Degraded=500ms)
+- **Ceiling**: codec-tier max (Studio=300ms, Good=500ms, Degraded=1040ms)
+- **Continuous**: linear interpolation between baseline and ceiling based on loss (0%->baseline, 40%->ceiling)
+- **RTT phantom loss**: high RTT (>200ms) adds phantom loss contribution to keep DRED generous
+- **Jitter spike**: >30% EWMA spike pre-emptively boosts to ceiling for ~5s cooldown
+
+### Output
+
+`DredTuning { dred_frames: u8, expected_loss_pct: u8 }` -> fed to `CallEncoder::apply_dred_tuning()` -> `OpusEncoder::set_dred_duration()` + `set_expected_loss()`
+
+## Signal Message Handshake Flow
+
+```mermaid
+sequenceDiagram
+ participant C as Client
+ participant R as Relay
+
+ C->>R: QUIC Connect (SNI = hashed room name)
+
+ alt Auth enabled (--auth-url)
+ C->>R: SignalMessage::AuthToken { token }
+ R->>R: POST auth_url to validate
+ R-->>C: (connection closed if invalid)
+ end
+
+ C->>R: CallOffer { identity_pub, ephemeral_pub, signature, supported_profiles }
+ R->>R: Verify Ed25519 signature
+ R->>R: Generate ephemeral X25519
+ R->>R: shared_secret = DH(eph_relay, eph_client)
+ R->>R: session_key = HKDF(shared_secret, "warzone-session-key")
+ R->>C: CallAnswer { identity_pub, ephemeral_pub, signature, chosen_profile }
+
+ C->>C: Verify signature
+ C->>C: Derive same session_key
+
+ Note over C,R: Session established -- both have ChaCha20-Poly1305 key
+
+ C->>R: RoomUpdate (join notification broadcast)
+
+ loop Media exchange
+ C->>R: QUIC Datagram (encrypted media)
+ R->>C: QUIC Datagram (forwarded from others)
+ end
+
+ opt Every 65,536 packets
+ C->>R: Rekey { new_ephemeral_pub, signature }
+ R->>C: Rekey { new_ephemeral_pub, signature }
+ Note over C,R: New session key via fresh DH
+ end
+
+ C->>R: Hangup { reason: Normal }
+ R->>R: Remove from room, broadcast RoomUpdate
+```
+
+## Relay Concurrency Model
+
+### Threading
+- Multi-threaded Tokio runtime (all available cores, work-stealing scheduler)
+- Task-per-connection: each QUIC connection gets a dedicated `tokio::spawn`
+- Task-per-participant-per-room: each participant's media forwarding loop is independent
+
+### Shared State & Locking
+
+The `RoomManager` stores `DashMap>>`. The DashMap guard is held only long enough to clone the `Arc`; all per-room operations then acquire the room-level `RwLock`. Concurrent fan-out calls share a read lock; join/leave acquire write lock.
+
+| Lock | Protected Data | Hold Duration | Contention |
+|------|---------------|---------------|------------|
+| `DashMap>>` | Room registry | Instant (clone Arc only) | Near-zero |
+| `Room` (RwLock) | Participants, quality tiers | ~1ms/packet (read); ~1ms (write on join/leave) | Low (concurrent reads) |
+| `PresenceRegistry` (Mutex) | Fingerprint registrations | ~1ms | Low (join/leave only) |
+| `SessionManager` (Mutex) | Active session tracking | ~1ms | Low |
+| `FederationManager.peer_links` (Mutex) | Peer connections | ~10ms during forward | Per-federation-packet |
+
+### Scaling Characteristics
+
+- **Many small rooms**: Scales well across all cores (rooms are independent)
+- **Large single room (100+ participants)**: Fan-out reads share RwLock (non-blocking); only join/leave serializes
+- **Federation**: Per-peer tasks scale; `peer_links` lock held during send loop
+
+## Client Architecture
+
+### Desktop Engine (Tauri)
+
+```mermaid
+graph TB
+ subgraph "Tauri Frontend (HTML/JS)"
+ UI[Connect / Call UI]
+ SET[Settings Panel]
+ end
+
+ subgraph "Tauri Rust Backend"
+ CMD[Tauri Commands
connect/disconnect/toggle]
+ ENG[WzpEngine
State Machine]
+ end
+
+ subgraph "Audio I/O"
+ CPAL_C[CPAL Capture
or VoiceProcessingIO]
+ RING_C[SPSC Ring
Capture]
+ RING_P[SPSC Ring
Playout]
+ CPAL_P[CPAL Playback
or VoiceProcessingIO]
+ end
+
+ subgraph "Network Tasks (tokio)"
+ SEND[Send Loop
encode + encrypt]
+ RECV[Recv Loop
decrypt + decode]
+ SIG[Signal Handler
room updates]
+ end
+
+ UI --> CMD
+ SET --> CMD
+ CMD --> ENG
+ ENG --> SEND
+ ENG --> RECV
+ ENG --> SIG
+
+ CPAL_C --> RING_C --> SEND
+ RECV --> RING_P --> CPAL_P
+
+ style ENG fill:#00b894,color:#fff
+ style SEND fill:#0984e3,color:#fff
+ style RECV fill:#0984e3,color:#fff
+```
+
+Key design decisions:
+- **Lock-free SPSC rings** between audio callbacks and network tasks (no mutex on audio thread)
+- **VoiceProcessingIO** on macOS for OS-level AEC (CPAL uses HalOutput which has no AEC)
+- **Direct playout** -- no jitter buffer on client; audio callback pulls from ring
+- **Release builds required** -- debug builds too slow for real-time audio
+
+### Android Engine (Kotlin + JNI)
+
+> **Note (2026-05-12):** The Kotlin+JNI Android app (`android/app/`) described below is superseded by the **Tauri 2.x mobile build** (`desktop/src-tauri/` + `crates/wzp-native/`). The Tauri approach uses the same Rust call engine as desktop, with Oboe audio via `wzp-native` cdylib. The Kotlin codebase is maintained for reference but the Tauri build is the live production app.
+
+```mermaid
+graph TB
+ subgraph "Compose UI"
+ CALL[CallActivity]
+ SET[SettingsScreen]
+ VM[CallViewModel]
+ end
+
+ subgraph "Service Layer"
+ SVC[CallService
Foreground Service]
+ PIPE[AudioPipeline
AudioTrack + AudioRecord]
+ end
+
+ subgraph "Rust Engine (JNI)"
+ JNI[WzpEngine.kt
JNI bridge]
+ NATIVE[libwzp_android.so
Rust call engine]
+ end
+
+ subgraph "Android Audio"
+ REC[AudioRecord
+ AEC effect]
+ TRK[AudioTrack
low-latency]
+ end
+
+ CALL --> VM
+ SET --> VM
+ VM --> SVC
+ SVC --> PIPE
+ PIPE --> JNI
+ JNI --> NATIVE
+
+ REC --> PIPE
+ PIPE --> TRK
+
+ style NATIVE fill:#00b894,color:#fff
+ style SVC fill:#ff9f43,color:#fff
+ style PIPE fill:#0984e3,color:#fff
+```
+
+Key design decisions:
+- **Foreground service** keeps audio alive when the screen is off
+- **AudioRecord + AudioTrack** with Android's built-in AEC (AudioEffect)
+- **Lock-free AudioRing** with preallocated Vec (not push/pop) to avoid allocation on audio thread
+- **JNI bridge** marshals PCM frames between Kotlin and Rust
+
+### CLI Architecture
+
+```mermaid
+graph TB
+ subgraph "CLI Modes"
+ LIVE[--live
Mic + Speaker]
+ TONE[--send-tone
Sine Generator]
+ FILE[--send-file
PCM Reader]
+ ECHO[--echo-test
Quality Analysis]
+ DRIFT[--drift-test
Clock Analysis]
+ SWEEP[--sweep
Buffer Sweep]
+ end
+
+ subgraph "Call Engine"
+ ENCODE[CallEncoder
codec + FEC]
+ DECODE[CallDecoder
FEC + codec]
+ QA[QualityAdapter
adaptive switching]
+ end
+
+ subgraph "Transport"
+ QUIC[QuinnTransport
send/recv media + signal]
+ HS[Handshake
X25519 + Ed25519]
+ end
+
+ LIVE --> ENCODE
+ TONE --> ENCODE
+ FILE --> ENCODE
+ ENCODE --> QUIC
+ QUIC --> DECODE
+ ECHO --> ENCODE
+ ECHO --> DECODE
+ DRIFT --> ENCODE
+ HS --> QUIC
+
+ style ENCODE fill:#00b894,color:#fff
+ style DECODE fill:#00b894,color:#fff
+ style QUIC fill:#0984e3,color:#fff
+```
+
+## Adaptive Quality System
+
+```mermaid
+graph LR
+ subgraph GOOD ["GOOD (28.8 kbps)"]
+ G_C[Opus 24kbps]
+ G_F[FEC 20%]
+ G_FR[20ms frames]
+ end
+
+ subgraph DEGRADED ["DEGRADED (9.0 kbps)"]
+ D_C[Opus 6kbps]
+ D_F[FEC 50%]
+ D_FR[40ms frames]
+ end
+
+ subgraph CATASTROPHIC ["CATASTROPHIC (2.4 kbps)"]
+ C_C[Codec2 1200bps]
+ C_F[FEC 100%]
+ C_FR[40ms frames]
+ end
+
+ GOOD -->|"loss>10% or RTT>400ms
3 consecutive reports"| DEGRADED
+ DEGRADED -->|"loss>40% or RTT>600ms
3 consecutive"| CATASTROPHIC
+ CATASTROPHIC -->|"loss<10% and RTT<400ms
10 consecutive"| DEGRADED
+ DEGRADED -->|"loss<10% and RTT<400ms
10 consecutive"| GOOD
+
+ style GOOD fill:#00b894,color:#fff
+ style DEGRADED fill:#fdcb6e
+ style CATASTROPHIC fill:#e17055,color:#fff
+```
+
+Hysteresis prevents tier flapping: **fast downgrade** (3 reports, or 2 on cellular) and **slow upgrade** (10 reports, one tier at a time).
+
+## Cryptographic Handshake
+
+```mermaid
+sequenceDiagram
+ participant C as Caller
+ participant R as Relay / Callee
+
+ Note over C: Derive identity from seed
Ed25519 + X25519 via HKDF
+
+ C->>C: Generate ephemeral X25519
+ C->>C: Sign(ephemeral_pub || "call-offer")
+ C->>R: CallOffer { identity_pub, ephemeral_pub, signature, profiles }
+
+ R->>R: Verify Ed25519 signature
+ R->>R: Generate ephemeral X25519
+ R->>R: shared_secret = DH(eph_b, eph_a)
+ R->>R: session_key = HKDF(shared_secret, "warzone-session-key")
+ R->>R: Sign(ephemeral_pub || "call-answer")
+ R->>C: CallAnswer { identity_pub, ephemeral_pub, signature, profile }
+
+ C->>C: Verify signature
+ C->>C: shared_secret = DH(eph_a, eph_b)
+ C->>C: session_key = HKDF(shared_secret)
+
+ Note over C,R: Both have identical ChaCha20-Poly1305 session key
+ C->>R: Encrypted media (QUIC datagrams)
+ R->>C: Encrypted media (QUIC datagrams)
+
+ Note over C,R: Rekey every 65,536 packets
New ephemeral DH + HKDF mix
+```
+
+## Identity Model
+
+```mermaid
+graph TD
+ SEED["32-byte Seed
(BIP39 Mnemonic: 24 words)"] --> HKDF1["HKDF
salt=None
info='warzone-ed25519'"]
+ SEED --> HKDF2["HKDF
salt=None
info='warzone-x25519'"]
+
+ HKDF1 --> ED["Ed25519 SigningKey
Digital Signatures"]
+ HKDF2 --> X25519["X25519 StaticSecret
Key Agreement"]
+
+ ED --> VKEY["Ed25519 VerifyingKey
(Public)"]
+ X25519 --> XPUB["X25519 PublicKey
(Public)"]
+
+ VKEY --> FP["Fingerprint
SHA-256(pubkey) truncated 16 bytes
xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx"]
+
+ style SEED fill:#6c5ce7,color:#fff
+ style FP fill:#fd79a8,color:#fff
+ style ED fill:#ee5a24,color:#fff
+ style X25519 fill:#00b894,color:#fff
+```
+
+## Adaptive Jitter Buffer
+
+```mermaid
+graph TD
+ PKT[Incoming Packet] --> SEQ{Sequence Check}
+ SEQ -->|Duplicate| DROP[Drop + AntiReplay]
+ SEQ -->|Valid| BUF["BTreeMap Buffer
(ordered by seq)"]
+
+ BUF --> ADAPT["AdaptivePlayoutDelay
(EMA jitter tracking)"]
+ ADAPT --> TARGET["target_delay =
ceil(jitter_ema / 20ms) + 2"]
+
+ BUF --> READY{"depth >= target?"}
+ READY -->|No| WAIT["Wait (Underrun++)"]
+ READY -->|Yes| POP[Pop lowest seq]
+ POP --> DECODE[Decode to PCM]
+ DECODE --> PLAY[Playout]
+
+ BUF --> OVERFLOW{"depth > max?"}
+ OVERFLOW -->|Yes| EVICT["Drop oldest (Overrun++)"]
+
+ style ADAPT fill:#fdcb6e
+ style DROP fill:#e17055,color:#fff
+ style EVICT fill:#e17055,color:#fff
+```
+
+## FEC Protection (RaptorQ)
+
+```mermaid
+graph LR
+ subgraph "Encoder"
+ F1[Frame 1] --> BLK["Source Block
(5-10 frames)"]
+ F2[Frame 2] --> BLK
+ F3[Frame 3] --> BLK
+ F4[Frame 4] --> BLK
+ F5[Frame 5] --> BLK
+ BLK --> SRC[5 Source Symbols]
+ BLK --> REP["1-10 Repair Symbols
(ratio dependent)"]
+ SRC --> INT["Interleaver
(depth=3)"]
+ REP --> INT
+ end
+
+ subgraph "Network"
+ INT --> LOSS{Packet Loss}
+ LOSS -->|some lost| RCV[Received Symbols]
+ end
+
+ subgraph "Decoder"
+ RCV --> DEINT[De-interleaver]
+ DEINT --> RAPTORQ["RaptorQ Decoder
Reconstruct from
any K of K+R symbols"]
+ RAPTORQ --> OUT[Original Frames]
+ end
+
+ style LOSS fill:#e17055,color:#fff
+ style RAPTORQ fill:#00b894,color:#fff
+```
+
+## Telemetry Stack
+
+```mermaid
+graph TB
+ subgraph "Relay"
+ RM["RelayMetrics
sessions, rooms, packets"]
+ SM["SessionMetrics
per-session jitter, loss, RTT"]
+ PM["ProbeMetrics
inter-relay RTT, loss"]
+ RM --> PROM1["GET /metrics :9090"]
+ SM --> PROM1
+ PM --> PROM1
+ end
+
+ subgraph "Web Bridge"
+ WM["WebMetrics
connections, frames, latency"]
+ WM --> PROM2["GET /metrics :8080"]
+ end
+
+ subgraph "Client"
+ CM["JitterStats + QualityAdapter"]
+ CM --> JSONL["--metrics-file
JSONL 1 line/sec"]
+ end
+
+ PROM1 --> GRAF["Grafana Dashboard
4 rows, 18 panels"]
+ PROM2 --> GRAF
+ JSONL --> ANALYSIS[Offline Analysis]
+
+ style GRAF fill:#ff6b6b,color:#fff
+ style PROM1 fill:#0984e3,color:#fff
+ style PROM2 fill:#0984e3,color:#fff
+```
+
+## Deployment Topology
+
+```mermaid
+graph TB
+ subgraph "Region A"
+ RA["wzp-relay A
:4433 UDP"]
+ WA["wzp-web A
:8080 HTTPS"]
+ WA --> RA
+ end
+
+ subgraph "Region B"
+ RB["wzp-relay B
:4433 UDP"]
+ WB["wzp-web B
:8080 HTTPS"]
+ WB --> RB
+ end
+
+ RA <-->|"Probe 1/s + Federation"| RB
+
+ BA[Browser A] -->|WSS| WA
+ BB[Browser B] -->|WSS| WB
+ CA[CLI Client] -->|QUIC| RA
+ DA[Desktop Client] -->|QUIC| RA
+ MA[Android Client] -->|QUIC| RB
+
+ PROM[Prometheus] -->|scrape| RA
+ PROM -->|scrape| RB
+ PROM -->|scrape| WA
+ PROM --> GRAF[Grafana]
+
+ FC[featherChat Server] -->|auth validate| RA
+ FC -->|auth validate| RB
+
+ style RA fill:#ff9f43,color:#fff
+ style RB fill:#ff9f43,color:#fff
+ style GRAF fill:#ff6b6b,color:#fff
+ style FC fill:#fd79a8,color:#fff
+```
+
+## Session State Machine
+
+```mermaid
+stateDiagram-v2
+ [*] --> Idle
+ Idle --> Connecting: connect()
+ Connecting --> Handshaking: QUIC established
+ Handshaking --> Active: CallOffer/Answer complete
+ Active --> Rekeying: 65,536 packets
+ Rekeying --> Active: new key derived
+ Active --> Closed: Hangup / Error / Timeout
+ Rekeying --> Closed: Error
+ Connecting --> Closed: Timeout
+ Handshaking --> Closed: Signature fail
+
+ note right of Active: Media flows (encrypted)
+ note right of Rekeying: Media continues while rekeying
+```
+
+## Project Structure
+
+```
+warzonePhone/
+├── Cargo.toml # Workspace root
+├── crates/
+│ ├── wzp-proto/ # Protocol types, traits, wire format
+│ │ └── src/
+│ │ ├── codec_id.rs # CodecId, QualityProfile
+│ │ ├── error.rs # Error types
+│ │ ├── jitter.rs # JitterBuffer, AdaptivePlayoutDelay
+│ │ ├── packet.rs # MediaHeader, MiniHeader, TrunkFrame, SignalMessage
+│ │ ├── quality.rs # Tier, AdaptiveQualityController
+│ │ ├── session.rs # SessionState machine
+│ │ └── traits.rs # AudioEncoder, FecEncoder, CryptoSession, etc.
+│ ├── wzp-codec/ # Audio codecs
+│ │ └── src/
+│ │ ├── adaptive.rs # AdaptiveEncoder/Decoder (Opus + Codec2)
+│ │ ├── denoise.rs # NoiseSuppressor (RNNoise / nnnoiseless)
+│ │ └── silence.rs # SilenceDetector, ComfortNoise
+│ ├── wzp-fec/ # Forward error correction
+│ │ └── src/
+│ │ ├── encoder.rs # RaptorQFecEncoder
+│ │ ├── decoder.rs # RaptorQFecDecoder
+│ │ └── interleave.rs # Interleaver (burst protection)
+│ ├── wzp-crypto/ # Cryptography + identity
+│ │ └── src/
+│ │ ├── identity.rs # Seed, Fingerprint, hash_room_name
+│ │ ├── handshake.rs # WarzoneKeyExchange (X25519 + Ed25519)
+│ │ ├── session.rs # ChaChaSession (ChaCha20-Poly1305)
+│ │ ├── nonce.rs # Deterministic nonce construction
+│ │ ├── anti_replay.rs # Sliding window replay protection
+│ │ └── rekey.rs # Forward secrecy rekeying
+│ ├── wzp-transport/ # QUIC transport layer
+│ │ └── src/lib.rs # QuinnTransport, send/recv media/signal/trunk
+│ ├── wzp-video/ # Video codecs + framer
+│ │ └── src/
+│ │ ├── factory.rs # VideoEncoder factory (platform dispatch)
+│ │ ├── framer.rs # NAL fragmentation (H.264/H.265)
+│ │ ├── depacketizer.rs # NAL reassembly, access unit emit
+│ │ ├── controller.rs # VideoQualityController
+│ │ ├── simulcast.rs # Simulcast layer management
+│ │ ├── encoder_mode.rs # Encoder mode selection
+│ │ ├── av1_obu.rs # AV1 OBU framing + depacketizer
+│ │ ├── dav1d.rs # dav1d AV1 software decoder
+│ │ ├── svt_av1.rs # SVT-AV1 software encoder (non-Android)
+│ │ ├── videotoolbox.rs # VideoToolbox H.265 + AV1 (macOS)
+│ │ ├── mediacodec.rs # MediaCodec H.264/H.265/AV1 (Android, NDK 0.9 migration pending)
+│ │ └── nack.rs # NACK sender/receiver framework
+│ ├── wzp-relay/ # Relay daemon
+│ │ └── src/
+│ │ ├── main.rs # CLI, connection loop, auth + handshake
+│ │ ├── config.rs # RelayConfig, TOML parsing
+│ │ ├── room.rs # RoomManager, TrunkedForwarder
+│ │ ├── pipeline.rs # RelayPipeline (forward mode)
+│ │ ├── session_mgr.rs # SessionManager (limits, lifecycle)
+│ │ ├── auth.rs # featherChat token validation
+│ │ ├── handshake.rs # Relay-side accept_handshake
+│ │ ├── metrics.rs # Prometheus RelayMetrics + per-session
+│ │ ├── probe.rs # Inter-relay probes + ProbeMesh
+│ │ ├── federation.rs # FederationManager, global rooms
+│ │ ├── presence.rs # PresenceRegistry
+│ │ ├── route.rs # RouteResolver
+│ │ ├── trunk.rs # TrunkBatcher
+│ │ ├── audio_scorer.rs # Per-stream audio quality scoring
+│ │ ├── response_policy.rs # Relay response policy (rate-limit, drop)
+│ │ ├── verdict.rs # Verdict enum (Allow/RateLimit/Drop/Malicious)
+│ │ ├── video_scorer.rs # VideoScorer (legitimacy scoring, keyframe regularity)
+│ │ └── ws.rs # WebSocket handler for browser clients
+│ ├── wzp-client/ # Call engine + CLI
+│ │ └── src/
+│ │ ├── cli.rs # CLI arg parsing + main
+│ │ ├── call.rs # CallEncoder, CallDecoder, QualityAdapter
+│ │ ├── handshake.rs # Client-side perform_handshake
+│ │ ├── featherchat.rs # CallSignal bridge
+│ │ ├── echo_test.rs # Automated echo quality test
+│ │ ├── drift_test.rs # Clock drift measurement
+│ │ ├── sweep.rs # Jitter buffer parameter sweep
+│ │ ├── metrics.rs # JSONL telemetry writer
+│ │ └── bench.rs # Component benchmarks
+│ └── wzp-web/ # Browser bridge
+│ ├── src/
+│ │ ├── main.rs # Axum server, WS handler, TLS
+│ │ └── metrics.rs # Prometheus WebMetrics
+│ └── static/
+│ ├── index.html # SPA UI (room, PTT, level meter)
+│ └── audio-processor.js # AudioWorklet (capture + playback)
+├── android/ # Android app (Kotlin + JNI)
+│ └── app/src/main/java/com/wzp/
+│ ├── audio/ # AudioPipeline, AudioRouteManager
+│ ├── engine/ # WzpEngine (JNI), CallStats, WzpCallback
+│ ├── ui/ # CallActivity, SettingsScreen, Identicon
+│ ├── data/ # SettingsRepository
+│ ├── net/ # RelayPinger
+│ ├── service/ # CallService (foreground)
+│ └── debug/ # DebugReporter
+├── desktop/ # Desktop app (Tauri)
+│ └── dist/ # Built frontend (HTML/JS/CSS)
+├── deps/featherchat/ # Git submodule
+├── docs/ # Documentation
+├── scripts/ # Build scripts
+│ └── build-linux.sh # Hetzner VM build
+└── tools/ # Development tools
+```
+
+## Test Coverage
+
+702 tests across all crates (excluding wzp-android), 0 failures:
+
+| Crate | Tests | Key Coverage |
+|-------|-------|-------------|
+| wzp-proto | 112 | Wire format, jitter buffer, quality tiers, mini-frames, trunking |
+| wzp-codec | 69 | Opus/Codec2 roundtrip, silence detection, noise suppression |
+| wzp-fec | 21 | RaptorQ encode/decode, loss recovery, interleaving |
+| wzp-crypto | 64 | Encrypt/decrypt, handshake, anti-replay, featherChat identity |
+| wzp-transport | 11 | QUIC connection setup, path monitoring |
+| wzp-relay | 137 | Room ACL, session mgmt, metrics, probes, mesh, trunking, scoring, verdict |
+| wzp-video | 88 | NAL framing, AV1 OBU, simulcast, quality controller, NACK |
+| wzp-client | 170 | Encoder/decoder, quality adapter, silence, drift, sweep |
+| wzp-web | 2 | Metrics |
+| wzp-native | 0 | Native platform bindings (no unit tests) |
+
+## Audio Backend Architecture (Platform Matrix)
+
+WarzonePhone's audio I/O goes through one of four backends depending on the target platform and feature flags. All backends expose the same public API (`AudioCapture::start() → AudioCapture { ring(), stop() }`) via conditional re-exports in `crates/wzp-client/src/lib.rs`, so the `CallEngine` above the audio layer doesn't know or care which backend is running.
+
+```
+ ┌─────────────────────────────────────────────┐
+ │ CallEngine (platform-agnostic) │
+ │ reads PCM from AudioCapture::ring() │
+ │ writes PCM to AudioPlayback::ring() │
+ └────────────────────┬────────────────────────┘
+ │
+ ┌─────────────────────┼─────────────────────┐
+ │ │ │
+ ▼ ▼ ▼
+ ┌───────────────┐ ┌────────────────┐ ┌───────────────┐
+ │ audio_io │ │ audio_vpio │ │ audio_wasapi │
+ │ (CPAL) │ │ (Core Audio │ │ (Windows │
+ │ │ │ VoiceProc IO) │ │ IAudioClient2│
+ │ All platforms │ │ macOS only │ │ Windows │
+ │ (baseline) │ │ feature=vpio │ │ feature= │
+ │ │ │ │ │ windows-aec │
+ └───────────────┘ └────────────────┘ └───────────────┘
+ │
+ ▼ on Android only
+ ┌───────────────┐
+ │ wzp-native │
+ │ (Oboe bridge │
+ │ via dlopen) │
+ │ │
+ │ Android only │
+ │ libloading │
+ └───────────────┘
+```
+
+### Backend selection matrix
+
+| Platform | Capture | Playback | OS AEC | Feature flags |
+|---|---|---|---|---|
+| macOS | VoiceProcessingIO (native Core Audio) | CPAL | **Yes** — Apple's hardware-accelerated AEC (same AEC as FaceTime, iMessage audio, Voice Memos) | `audio`, `vpio` |
+| Windows (AEC build) | Direct WASAPI with `AudioCategory_Communications` | CPAL | **Yes** — Windows routes the capture stream through the driver's communications APO chain (AEC + NS + AGC), driver-dependent quality | `audio`, `windows-aec` |
+| Windows (baseline) | CPAL (WASAPI shared mode) | CPAL | No | `audio` |
+| Linux | CPAL (ALSA / PulseAudio) | CPAL | No | `audio` |
+| Android (Tauri Mobile) | Oboe via `wzp-native` cdylib, `Usage::VoiceCommunication` + `MODE_IN_COMMUNICATION` | Same Oboe stream | Depends on device (some Android devices apply AEC to the voice-communication stream, most do not) | none (`wzp-client` compiled with `default-features = false`) |
+
+### Why `wzp-native` is a standalone cdylib
+
+On Android, the audio backend lives in a separate cdylib crate (`crates/wzp-native`) that `wzp-desktop`'s lib crate loads at runtime via `libloading`. It is **not** linked as a regular Rust dep.
+
+This is deliberate. rust-lang/rust#104707 documents that a crate with `crate-type = ["cdylib", "staticlib"]` leaks non-exported symbols from the staticlib into the cdylib. On Android, that caused Bionic's private `__init_tcb` / `pthread_create` symbols to be bound LOCALLY inside our `.so` instead of resolved dynamically against `libc.so` at `dlopen` time — which crashed the app at launch as soon as `tao` tried to `std::thread::spawn()` from the JNI `onCreate` callback.
+
+Keeping `wzp-native` in its own cdylib and loading it via `libloading` means:
+
+1. The app's own `.so` has `crate-type = ["cdylib", "rlib"]` only — no `staticlib`, no symbol leak.
+2. `libwzp_native.so` is loaded via `System.loadLibrary` from the JVM side (or `dlopen` from Rust), which triggers the normal Bionic resolver and binds all private symbols against `libc.so` at load time.
+3. The C/C++ Oboe bridge is fully isolated inside `libwzp_native.so`'s symbol space — no chance of its archives leaking into `wzp-desktop`'s `.so`.
+
+See `docs/BRANCH-android-rewrite.md` for the full incident postmortem and `docs/incident-tauri-android-init-tcb.md` for the debug log.
+
+### Vendored `audiopus_sys` for libopus / clang-cl cross-compile
+
+The workspace root carries a vendored copy of `audiopus_sys` at `vendor/audiopus_sys/` with a patched `opus/CMakeLists.txt`. This is needed because libopus 1.3.1 gates its per-file `-msse4.1` / `-mssse3` `COMPILE_FLAGS` behind `if(NOT MSVC)`, and under `clang-cl` (used by `cargo-xwin` for Windows cross-compiles) CMake sets `MSVC=1` unconditionally — so the SIMD source files compile without the required target feature and fail to link the intrinsic `always_inline` functions.
+
+The patch introduces an `MSVC_CL` variable that is true only for real `cl.exe` (distinguished via `CMAKE_C_COMPILER_ID STREQUAL "MSVC"`), and flips the eight `if(NOT MSVC)` SIMD guards to `if(NOT MSVC_CL)` so clang-cl gets the GCC-style per-file flags. Wired in via `[patch.crates-io] audiopus_sys = { path = "vendor/audiopus_sys" }` at the workspace root.
+
+This does not affect macOS or Linux builds — on those platforms `MSVC=0` everywhere so the patched logic behaves identically to upstream.
+
+Upstream tracking: xiph/opus#256, xiph/opus PR #257 (both stale).
+
+## Network Awareness (Android)
+
+The adaptive quality controller (`AdaptiveQualityController` in `wzp-proto`) supports proactive network-aware adaptation via `signal_network_change(NetworkContext)`. On Android, this is fed by `NetworkMonitor.kt` which wraps `ConnectivityManager.NetworkCallback`.
+
+```
+ConnectivityManager
+ │ onCapabilitiesChanged / onLost
+ ▼
+NetworkMonitor.kt ──classify──► type: Int (WiFi=0, LTE=1, 5G=2, 3G=3)
+ │ onNetworkChanged(type, bw)
+ ▼
+CallViewModel ──► WzpEngine.onNetworkChanged()
+ │ JNI
+ ▼
+ jni_bridge.rs
+ │
+ ▼
+ EngineState.pending_network_type (AtomicU8, lock-free)
+ │ polled every ~20ms
+ ▼
+ recv task: quality_ctrl.signal_network_change(ctx)
+ │
+ ├─ WiFi → Cellular: preemptive 1-tier downgrade
+ ├─ Any change: 10s FEC boost (+0.2 ratio)
+ └─ Cellular: faster downgrade thresholds (2 vs 3)
+```
+
+Cellular generation is approximated from `getLinkDownstreamBandwidthKbps()` to avoid requiring `READ_PHONE_STATE` permission.
+
+## Audio Routing (Android)
+
+Both Android app variants support 3-way audio routing: **Earpiece → Speaker → Bluetooth SCO**.
+
+### Audio Mode Lifecycle
+
+`MODE_IN_COMMUNICATION` is set by the Rust call engine (via JNI `AudioManager.setMode()`) right before Oboe streams open — NOT at app launch. Restored to `MODE_NORMAL` when the call ends. This prevents hijacking system audio routing (music, BT A2DP) before a call is active.
+
+### Native Kotlin App
+
+`AudioRouteManager.kt` handles device detection (via `AudioDeviceCallback`), SCO lifecycle, and auto-fallback on BT disconnect. `CallViewModel.cycleAudioRoute()` cycles through available routes.
+
+### Tauri Desktop App
+
+`android_audio.rs` provides JNI bridges to `AudioManager` for speakerphone and Bluetooth SCO control. After each route change, Oboe streams are stopped and restarted via `spawn_blocking`.
+
+```
+User tap ──► cycleAudioRoute()
+ │
+ ├─ Earpiece: setSpeakerphoneOn(false) + clearCommunicationDevice()
+ ├─ Speaker: setSpeakerphoneOn(true)
+ └─ BT SCO: setCommunicationDevice(bt_device) [API 31+]
+ │ fallback: startBluetoothSco() [API < 31]
+ ▼
+ Oboe stop + start_bt() for BT / start() for others
+```
+
+### BT SCO and Oboe
+
+BT SCO only supports 8/16kHz. When `bt_active=1`, Oboe capture skips `setSampleRate(48000)` and `setInputPreset(VoiceCommunication)`, letting the system choose the native BT rate. Oboe's `SampleRateConversionQuality::Best` bridges to our 48kHz ring buffers. Playout uses `Usage::Media` in BT mode to avoid conflicts with the communication device routing.
+
+### Hangup Signal Fix
+
+`SignalMessage::Hangup` now carries an optional `call_id` field. The relay uses it to end only the specific call instead of broadcasting to all active calls for the user — preventing a race where a hangup for call 1 kills a newly-placed call 2.
+
+## Phase 8: Tailscale-Inspired NAT Traversal (2026-04-14)
+
+Five new modules in `wzp-client` bring NAT traversal capability close to Tailscale's approach:
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ wzp-client NAT Traversal Stack │
+│ │
+│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
+│ │ stun.rs │ │ portmap.rs │ │ reflect.rs (existing) │ │
+│ │ RFC 5389 │ │ NAT-PMP │ │ Relay-based STUN │ │
+│ │ Public │ │ PCP │ │ Multi-relay NAT detect │ │
+│ │ STUN │ │ UPnP IGD │ │ │ │
+│ └──────┬──────┘ └──────┬───────┘ └────────────┬─────────────┘ │
+│ │ │ │ │
+│ └────────────────┼────────────────────────┘ │
+│ │ │
+│ ┌───────▼────────┐ │
+│ │ ice_agent.rs │ │
+│ │ Gather / Re- │ │
+│ │ gather / Apply│ │
+│ └───────┬────────┘ │
+│ │ │
+│ ┌───────────┼───────────┐ │
+│ │ │ │ │
+│ ┌───────▼───┐ ┌───▼───┐ ┌───▼──────────┐ │
+│ │ netcheck │ │ dual_ │ │ relay_map.rs │ │
+│ │ .rs │ │ path │ │ RTT-sorted │ │
+│ │ Diagnostic│ │ .rs │ │ relay list │ │
+│ └───────────┘ │ Race │ └──────────────┘ │
+│ └───────┘ │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Candidate Types
+
+| Type | Source | Priority | When Used |
+|------|--------|----------|-----------|
+| Host | `local_host_candidates()` | 1 (highest) | Same-LAN peers |
+| Port-mapped | `portmap::acquire_port_mapping()` | 2 | Router supports NAT-PMP/PCP/UPnP |
+| Server-reflexive | `stun::discover_reflexive()` or relay Reflect | 3 | Cone NAT |
+| Relay | Relay address (fallback) | 4 (lowest) | Always available |
+
+### Signal Flow for Mid-Call Re-Gathering
+
+```
+Network change (WiFi → cellular)
+ │
+ ▼
+IceAgent::re_gather()
+ ├── stun::discover_reflexive()
+ ├── portmap::acquire_port_mapping()
+ └── local_host_candidates()
+ │
+ ▼
+SignalMessage::CandidateUpdate { generation: N+1, ... }
+ │
+ ▼ (via relay)
+Peer's IceAgent::apply_peer_update()
+ │
+ ▼
+PeerCandidates { reflexive, local, mapped }
+ │
+ ▼
+dual_path::race() with new candidates (TODO: transport hot-swap)
+```
+
+### New SignalMessage Variants & Fields
+
+| Signal | New Fields | Purpose |
+|--------|-----------|---------|
+| `DirectCallOffer` | `caller_mapped_addr` | Port-mapped address from NAT-PMP/PCP/UPnP |
+| `DirectCallAnswer` | `callee_mapped_addr` | Same, callee side |
+| `CallSetup` | `peer_mapped_addr` | Relay cross-wires mapped addr to peer |
+| `CandidateUpdate` | (new variant) | Mid-call candidate re-gathering |
+| `RegisterPresenceAck` | `relay_region`, `available_relays` | Relay mesh metadata for auto-selection |
+
+All new fields use `#[serde(default, skip_serializing_if)]` for backward compatibility with older clients/relays.
+
+### Hard NAT Port Prediction
+
+For symmetric NATs that don't support port mapping, the system detects the NAT's port allocation pattern:
+
+```
+Single socket → 5 STUN servers (sequential probes)
+ │
+ ▼
+Observed ports: [40001, 40002, 40003, 40004, 40005]
+ │
+ ▼
+classify_port_allocation() → Sequential { delta: 1 }
+ │
+ ▼
+predict_ports(last=40005, delta=1, offset=0, spread=2)
+ → [40004, 40005, 40006, 40007, 40008]
+ │
+ ▼
+HardNatProbe signal → peer
+ │
+ ▼
+Peer dials predicted port range in parallel
+```
+
+| Pattern | Detection | Traversal Strategy |
+|---------|-----------|-------------------|
+| Port-preserving | All probes return same port | Standard hole-punch |
+| Sequential (delta=N) | Consistent N-increment | Predict next port, dial range |
+| Random | No pattern | Birthday attack or relay |
+| Unknown | < 3 probes succeeded | Relay fallback |
+
+The classifier tolerates:
+- **Jitter**: ±1 from dominant delta (concurrent flow grabbed a port)
+- **Wraparound**: 65535 → 1 treated as delta=+2, not -65534
+- **Noise**: 60% threshold — if most deltas agree, call it sequential
diff --git a/vault/Architecture/Attack-Surface-Relay-Abuse.md b/vault/Architecture/Attack-Surface-Relay-Abuse.md
new file mode 100644
index 0000000..51efeed
--- /dev/null
+++ b/vault/Architecture/Attack-Surface-Relay-Abuse.md
@@ -0,0 +1,233 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# Relay Abuse: Attack Surface & Mitigations
+
+> WZP is end-to-end encrypted. The relay forwards ciphertext and cannot inspect payload content. This document enumerates the abuse vectors that survive E2E and the mitigations available without breaking it.
+>
+> Motivating threat: a PoC on another project (LiveKit) showed that an E2E SFU with no conformance enforcement can be repurposed as a free arbitrary-data tunnel. WZP must not be that.
+
+## Threat model
+
+### In scope
+
+- **Bulk data tunneling.** Attacker uses a legitimate handshake, then pushes arbitrary bytes (file transfer, piracy, scraped traffic) through media datagrams.
+- **Bandwidth parasitism.** Attacker uses the relay as a cheap forwarder for unrelated traffic at scale.
+- **Quota / billing evasion.** Attacker disguises high-bandwidth use as low-bandwidth audio.
+- **DoS via amplification.** Attacker sends one packet → SFU fans out to N peers, multiplying egress cost N×.
+
+### Out of scope (cannot be solved without breaking E2E)
+
+- **Steganography inside real audio.** Modulating Opus-encoded waveforms to encode a covert channel. Information-theoretic limit; ~tens to hundreds of bps achievable; economically uninteresting.
+- **Modem-over-call.** Real audio whose semantic content is data. Same limit.
+- **Slow exfiltration under all rate caps.** Attacker who stays within audio's natural bandwidth envelope, indefinitely.
+
+### Threat actor profile
+
+We are defending against **economically motivated abuse at scale**, not against a determined nation-state covert channel. The former needs bandwidth and is loud; the latter is impossible to stop and not worth the engineering cost.
+
+## What the relay can observe
+
+Despite E2E, the relay sees a lot. None of this is encrypted to the relay:
+
+| Observable | Source | Bits available |
+|---|---|---|
+| `CodecID` (declared codec) | `MediaHeader`, AAD | 4 (today) / 6 (v2) |
+| `MediaType` (audio / video / data / control) | `MediaHeader` v2 | 2 |
+| `sequence`, `timestamp_ms` | `MediaHeader` | 32 + 32 |
+| `fec_block_id`, `fec_symbol_idx`, `FecRatio`, `T` (repair) | `MediaHeader` | varies |
+| `KeyFrame` bit | `MediaHeader` v2 | 1 |
+| `Q` flag (QualityReport trailer present) | `MediaHeader` | 1 |
+| Packet size | QUIC layer | — |
+| Packet inter-arrival timing | QUIC layer | — |
+| Aggregate bytes/sec per session | RelayMetrics | — |
+| Source fingerprint, src IP | Session state | — |
+
+This is enough surface for strong conformance enforcement without ever touching encrypted payload.
+
+## Mitigation tiers
+
+Listed in order of cost-to-implement vs. decisiveness. Tier A alone kills the gross-abuse threat. Higher tiers add defense in depth.
+
+### Tier A — Codec-conformance bitrate caps
+
+For each declared `CodecID`, the wire bitrate has a math-derivable hard ceiling:
+
+```
+ceiling_bps[CodecID] = nominal_bitrate * (1 + max_FEC_ratio) * (1 + overhead_pct)
+ = nominal * 3.0 * 1.15 // FEC max 2.0 → factor 3.0
+```
+
+| Codec | Nominal | Hard ceiling |
+|---|---|---|
+| Opus 64k | 64 kbps | ~221 kbps |
+| Opus 24k | 24 kbps | ~83 kbps |
+| Opus 6k | 6 kbps | ~21 kbps |
+| Codec2 1200 | 1.2 kbps | ~4 kbps |
+| ComfortNoise | 0 | ~2 kbps |
+
+Sliding 1 s window per session. Sustained excess → hard violation, close session.
+
+Decisive against bulk tunneling. False-positive rate negligible if ceilings set at math-derived max × 1.5.
+
+### Tier B — Packet-rate conformance
+
+Each codec has a fixed frame interval (20 ms or 40 ms), so legal `pps` is 25 or 50, plus FEC repair packets (max ~150 pps total at FEC ratio 2.0). Anything sustaining > 200 pps for an audio codec is not audio.
+
+### Tier C — Timestamp-rate consistency
+
+`timestamp_ms` advances at the declared frame interval. `Δtimestamp / Δseq` over a rolling window should match the codec's frame duration ±2×. Divergence catches abusers who send audio-rate small packets but burn fields for payload.
+
+### Tier D — Per-codec packet-size sanity
+
+EWMA of packet size per session, compared to per-codec typical:
+
+| Codec | Typical | Reject above |
+|---|---|---|
+| Opus 24k 20 ms | 60–80 B | 160 B |
+| Opus 6k 40 ms | 30–40 B | 90 B |
+| Codec2 1200 40 ms | 6 B | 30 B |
+| ComfortNoise | 0–4 B | 16 B |
+
+### Tier E — Per-fingerprint / per-IP token bucket
+
+Aggregate quota regardless of declared codec:
+
+```
+For each (fingerprint, src_ip):
+ monthly_bytes_quota authenticated = 50 GB (tune)
+ anonymous = 1 GB
+ per-session cap audio = 256 kbps
+ video = 5 Mbps
+ burst = 30 s at 2× cap
+```
+
+Won't stop a single rogue session under cap; bounds aggregate blast radius and makes relay economics predictable.
+
+### Tier F — Behavioral entropy / statistical fingerprinting
+
+The deeper layer. Computed continuously per session over 10–30 s windows. Combined score flags streams that pass declared-codec checks but do not statistically look like real media.
+
+**Why this works:** real audio and real video have very specific statistical signatures that tunneled data does not naturally produce, and that an attacker would have to deliberately and expensively mimic. The signatures differ wildly between audio and video — which is exactly why we separate them (see next section).
+
+#### Audio fingerprint features
+
+| Feature | Real Opus speech | Tunneled data |
+|---|---|---|
+| **IAT coefficient of variation** | 0.1–0.4 (clocked) | > 1.0 (bursty) |
+| **Payload-size distribution** | Bimodal: speech 60–80 B + silence/CN 0–10 B | Unimodal, large, MTU-skewed |
+| **Silence fraction** | 10–40 % (real conversation pauses) | < 2 % |
+| **Bitrate over 30 s** | Tracks nominal codec ±20 % | Often saturates ceiling |
+| **`Q` flag cadence** | Periodic, regular | Absent or random |
+| **DRED / FEC ratio response** | Tracks `QualityReport` trend | Static or noise |
+
+Single derived score: `audio_legitimacy ∈ [0, 1]`. Below threshold (e.g. 0.3) for 60 s → flag.
+
+#### Video fingerprint features (post-V1)
+
+| Feature | Real H.264 / AV1 video | Tunneled data |
+|---|---|---|
+| **Keyframe periodicity** | Regular (every 1–4 s, or on PLI) | Absent or uniform `KeyFrame=1` |
+| **Frame-size ratio (I / P)** | 5–20× | ≈ 1× |
+| **Burst structure** | One I-frame = N packets in < 5 ms, then quiet | Uniform spacing |
+| **Bitrate response to BWE feedback** | Tracks `TransportFeedback::remb_bps` | Ignores it |
+| **Resolution / FPS implied by bitrate** | Coherent (240 p ≠ 8 Mbps) | Incoherent |
+| **NACK / PLI responsiveness** | Sender produces keyframe within 200 ms | No response |
+
+Single derived score: `video_legitimacy ∈ [0, 1]`.
+
+#### Implementation shape
+
+```rust
+pub struct LegitimacyScorer {
+ media_type: MediaType,
+ iat_ewma: ExponentialMovingAverage,
+ iat_variance: ExponentialMovingVariance,
+ size_histogram: SizeBuckets<8>,
+ silence_count: u32,
+ speech_count: u32,
+ quality_reports_seen: u32,
+ keyframe_intervals: RingBuffer,
+ window_start: Instant,
+}
+
+impl LegitimacyScorer {
+ pub fn observe(&mut self, header: &MediaHeader, payload_len: usize, now: Instant);
+ pub fn score(&self) -> f32; // [0, 1]
+ pub fn verdict(&self) -> Verdict; // Legitimate | Suspect | Abusive
+}
+```
+
+Cheap: a few floats and counters per session. Update on every packet, score every 1 s, escalate over 30+ s.
+
+### Tier G — Reactive response
+
+A scoring system needs a response policy:
+
+| Verdict | Action |
+|---|---|
+| Legitimate | None |
+| Suspect | Apply tighter Tier-E quota; emit `relay_conformance_suspect_total` |
+| Abusive | Close session with `Hangup::PolicyViolation`; log to audit; cool-down fingerprint |
+| Repeat-abusive | Lower-tier quota across the federation (gossip via federation channel) |
+
+Never silent-drop. Always close with a typed reason so legitimate users hitting a bug get a clear error.
+
+## Separating audio and video
+
+**Yes — this is one of the strongest arguments for the v2 `MediaType` bit and should be a hard design rule.**
+
+Audio and video have nothing in common statistically:
+
+| Property | Audio | Video |
+|---|---|---|
+| Bitrate | 6–64 kbps | 100 kbps – 5 Mbps |
+| Packet rate | 25–50 pps | 500–2000 pps |
+| Packet size | 6–160 B | 200–1450 B |
+| Burst structure | Clocked, near-CBR | Bursty (I-frames) |
+| Silence | Common (10–40 %) | Meaningless |
+| Loss tolerance | High (PLC, DRED) | Variable (keyframes critical) |
+| Recovery primitive | FEC + DRED | NACK + PLI + keyframe cache |
+
+A single scoring model trying to cover both would have to be so permissive at the union of envelopes that it would let tunnels through. **Separation is mandatory for Tier F to work.**
+
+### What separation requires
+
+1. **`MediaType:2` in `MediaHeader` v2** (already in `ROAD-TO-VIDEO.md` Phase V1). Without this, the relay must keep a `CodecID → MediaType` table and update it every time a codec is added — fragile.
+2. **Per-`MediaType` conformance rules.** A and B and D have separate tables per type. Tier F has separate scorers.
+3. **Per-`MediaType` quotas.** Tier E uses two buckets: `audio_bps_cap`, `video_bps_cap`. A session in audio-only mode never gets to spend the video budget. A video session has both, audio-priority.
+4. **Per-`MediaType` keyframe/silence semantics.** `KeyFrame` bit is meaningless for audio; silence fraction is meaningless for video. The scorer needs to know which features apply.
+
+### Bonus: separation also helps the SFU
+
+Beyond abuse detection, the same separation makes graceful degradation cleaner: under congestion the relay can drop video packets first while preserving audio, because it knows which is which without parsing the codec table.
+
+## Open questions for later decision
+
+1. **Hard-close on first hard violation, or three-strikes?** Three-strikes is friendlier but lets twice the abuse through. Recommend hard-close + clear typed reason; legitimate users will reconnect, abusers won't try again at the same fingerprint.
+2. **Where do verdicts persist?** In-memory per relay is simplest. Federated gossip is more powerful but a new attack surface (poisoning).
+3. **Threshold tuning.** All thresholds in this doc are first-pass math. Real numbers come from a few weeks of Prometheus data on legitimate traffic before any enforcement turns on.
+4. **Anonymous vs. authenticated split.** featherChat-authed users get generous quotas; anonymous users get tight ones. This makes the economics of mass abuse hostile (need many real identities) without locking out small legitimate use.
+5. **What to log.** Conformance hits should be Prometheus counters + ringbuffer of recent violations; never log raw payload content (even encrypted) for privacy.
+
+## Suggested implementation order (whenever this is picked up)
+
+| Step | What | Why first |
+|---|---|---|
+| 1 | Land v2 wire format with `MediaType:2` | Prereq for separation; already on the road-to-video plan |
+| 2 | Tier A + B + C as `wzp-relay/src/conformance.rs` | Kills bulk tunneling; cheap; no false positives if math is right |
+| 3 | Prometheus metrics for violations + raw observables (IAT, size, silence frac) | Gather baseline of legitimate traffic before tightening |
+| 4 | Tier D + E (size sanity + token bucket) | Defense in depth |
+| 5 | Tier F scorer, audio-only first; tuned against the baseline from step 3 | Adds covert-tunnel pressure |
+| 6 | Tier F video scorer once video is in production | Same shape, different features |
+| 7 | Tier G response policy + audit log | Operationalize |
+
+Steps 1–2 are decisive against the LiveKit-style PoC. The rest is steady tightening as real traffic accumulates.
+
+## What this does NOT promise
+
+- It does not stop a patient adversary running a slow covert channel inside real audio. Nothing E2E-preserving can.
+- It does not detect content (no CSAM scan, no copyright fingerprint). Those would require breaking E2E and are out of scope by design.
+- It does not eliminate abuse — it makes abuse loud, expensive, and detectable, which is the realistic goal for any E2E system.
diff --git a/vault/Architecture/Branch-Desktop-Audio-Rewrite.md b/vault/Architecture/Branch-Desktop-Audio-Rewrite.md
new file mode 100644
index 0000000..915678b
--- /dev/null
+++ b/vault/Architecture/Branch-Desktop-Audio-Rewrite.md
@@ -0,0 +1,169 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# Branch: `feat/desktop-audio-rewrite`
+
+Home of the Tauri desktop client for macOS, Windows, and Linux. Named "audio-rewrite" because the original driver was replacing a CPAL-only audio pipeline with platform-native backends that support OS-level echo cancellation (VoiceProcessingIO on macOS, WASAPI Communications on Windows), but the branch has grown into the full desktop story — Windows cross-compilation, vendored dependencies, history UI, direct calling, the whole thing.
+
+## Purpose
+
+The desktop client shares 100% of its frontend (`desktop/src/`) and Tauri command layer (`desktop/src-tauri/src/lib.rs`, `engine.rs`, `history.rs`) with the Android build on `android-rewrite`. Differences are limited to:
+
+- **Audio backends**, which are platform-gated via Cargo target-dep sections in `desktop/src-tauri/Cargo.toml` and feature flags in `crates/wzp-client/Cargo.toml`.
+- **Identity storage paths**, which resolve via Tauri's `app_data_dir()` (`~/Library/Application Support/…` on macOS, `%APPDATA%\…` on Windows, `~/.local/share/…` on Linux).
+- **Build toolchains**: native `cargo build` on macOS/Linux, `cargo xwin` cross-compile from Linux for Windows via Docker on SepehrHomeserverdk.
+
+## Audio backend matrix
+
+| Target | Capture | Playback | AEC |
+|---|---|---|---|
+| macOS | CPAL (WASAPI/CoreAudio via cpal crate) OR VoiceProcessingIO (native Core Audio) | CPAL | VoiceProcessingIO native AEC (when `vpio` feature enabled) |
+| Windows (default) | CPAL → WASAPI shared mode | CPAL → WASAPI shared mode | None |
+| Windows (AEC build) | Direct WASAPI with `IAudioClient2::SetClientProperties(AudioCategory_Communications)` | CPAL → WASAPI shared mode | **OS-level**: Windows routes the capture stream through the driver's communications APO chain (AEC + NS + AGC) |
+| Linux | CPAL → ALSA/PulseAudio | CPAL → ALSA/PulseAudio | None |
+
+The macOS VPIO path is gated behind the `vpio` feature in `wzp-client` and the `coreaudio-rs` dep is itself `cfg(target_os = "macos")`, so enabling the feature on Windows or Linux is a no-op.
+
+The Windows AEC path is gated behind the `windows-aec` feature, also target-gated (the `windows` crate dep is only pulled in on Windows), and re-exports `WasapiAudioCapture as AudioCapture` when enabled so downstream code doesn't need to know which backend is active. The current Windows build at `target/windows-exe/wzp-desktop.exe` has `windows-aec` on; a baseline noAEC build is preserved at `target/windows-exe/wzp-desktop-noAEC.exe` for A/B comparison on real hardware.
+
+See [`BRANCH-android-rewrite.md`](BRANCH-android-rewrite.md) for Oboe audio on Android, which is its own story.
+
+## Recent major work
+
+### 1. Desktop direct calling feature (commit `2fd9465` and neighbors)
+
+Brought direct 1:1 calls to macOS with full parity to the Android client:
+
+- **Identity path fix**: the desktop `CallEngine::start` was loading seed from `$HOME/.wzp/identity` while `register_signal` used Tauri's `app_data_dir()`, producing two different fingerprints per run. Both now route through `load_or_create_seed()` which uses `app_data_dir()` everywhere.
+- **Call history with dedup**: `history.rs` stores a `Vec` with a `CallDirection` enum (`Placed | Received | Missed`). The `log` function dedupes by `call_id` so an outgoing call isn't logged twice as "missed" (when the signal loop's `DirectCallOffer` handler fires) and then again as "placed" (when `place_call` returns). Instead the entry is updated in place.
+- **Recent contacts row**: a horizontal chip UI in the direct-call panel showing the last N peers with friendly aliases, clickable to re-dial.
+- **Deregister button**: lets a user drop their signal registration without quitting the app, useful when switching identities.
+- **Random alias derivation**: a new client sees a human-friendly alias like "silent-forest-41" derived deterministically from its seed, so it's identifiable in the UI before manual naming.
+- **Default room "general"** instead of "android", since the desktop client is not Android.
+
+### 2. macOS VoiceProcessingIO integration
+
+`crates/wzp-client/src/audio_vpio.rs` — a native Core Audio implementation using `AUGraph` + `AudioComponentInstance` with the VPIO audio unit. Gives you hardware-accelerated AEC (same AEC Apple ships in FaceTime / iMessage audio / voice memos) at the cost of tight coupling to Apple frameworks. Lock-free ring pattern matches the CPAL path so the upper layers don't notice the difference.
+
+Enabled by `features = ["audio", "vpio"]` in the macOS target section of `desktop/src-tauri/Cargo.toml`.
+
+### 3. Windows cross-compilation via cargo-xwin
+
+Cross-compiling Rust + Tauri to `x86_64-pc-windows-msvc` from Linux using `cargo-xwin`, which downloads the Microsoft CRT + Windows SDK on demand and drives `clang-cl` as the compiler. No Windows machine is needed for the build itself — only for runtime testing.
+
+**Build infrastructure**:
+
+- `scripts/Dockerfile.windows-builder` — Debian bookworm + Rust + cargo-xwin + Node 20 + cmake + ninja + llvm + clang + lld + nasm. Pre-warms the xwin MSVC CRT cache at image build time (saves ~4 minutes per cold build).
+- `scripts/build-windows-docker.sh` — fire-and-forget remote build via Docker on SepehrHomeserverdk. Same pattern as `build-tauri-android.sh`. Uploads the `.exe` to rustypaste and fires an `ntfy.sh/wzp` notification on start and on completion.
+- `scripts/build-windows-cloud.sh` — alternative pipeline using a temporary Hetzner Cloud VPS. Slower (full VM spin-up), more expensive, but useful when Docker image rebuilds would be disruptive.
+
+**Two critical blockers resolved** on the way to a working `.exe`:
+
+1. **libopus SSE4.1 / SSSE3 intrinsic compile failure**. `audiopus_sys` vendors libopus 1.3.1, whose `CMakeLists.txt` gates the per-file `-msse4.1` `COMPILE_FLAGS` behind `if(NOT MSVC)`. Under `clang-cl`, CMake sets `MSVC=1` (because `CMAKE_C_COMPILER_FRONTEND_VARIANT=MSVC` triggers `Platform/Windows-MSVC.cmake` which unconditionally sets the variable), so the per-file flag is never set and the SSE4.1 source files compile without the target feature — then fail with 20+ "always_inline function '_mm_cvtepi16_epi32' requires target feature 'sse4.1'" errors.
+
+ Fixed by **vendoring audiopus_sys into `vendor/audiopus_sys/`** and patching its bundled libopus to introduce an `MSVC_CL` variable that is true only for real `cl.exe` (distinguished via `CMAKE_C_COMPILER_ID STREQUAL "MSVC"`). The eight `if(NOT MSVC)` SIMD guards are flipped to `if(NOT MSVC_CL)` and the global `/arch` block at line 445 becomes `if(MSVC_CL)`, so clang-cl gets the GCC-style per-file flags while real cl.exe keeps the `/arch:AVX` / `/arch:SSE2` globals.
+
+ Wired in via `[patch.crates-io] audiopus_sys = { path = "vendor/audiopus_sys" }` at the workspace root.
+
+ Upstream tracking: [xiph/opus#256](https://github.com/xiph/opus/issues/256), [xiph/opus PR #257](https://github.com/xiph/opus/pull/257) (both stale).
+
+2. **tauri-build needs `icons/icon.ico` for the Windows PE resource**. The desktop only had `icon.png`. Generated a multi-size ICO (16/24/32/48/64/128/256) from the existing placeholder via Pillow and committed it. Placeholder quality — real branded icons can replace it later.
+
+### 4. Windows `AudioCategory_Communications` capture path (task #24)
+
+`crates/wzp-client/src/audio_wasapi.rs` — direct WASAPI capture via `IMMDeviceEnumerator → IAudioClient2 → SetClientProperties` with `AudioCategory_Communications`. This tells Windows "this is a VoIP call" and Windows routes the capture stream through the driver's registered communications APO chain, which on most Win10/11 consumer hardware includes AEC, NS, and AGC.
+
+**Caveat**: quality is driver-dependent. On a machine with a good communications APO (Intel Smart Sound, Dolby, modern Realtek on Win11 24H2+, anything with Voice Clarity enabled) it's excellent. On generic class-compliant drivers with no communications APO registered, it's a no-op. For a guaranteed AEC regardless of driver, see task #26 which tracks implementing the classic Voice Capture DSP (`CLSID_CWMAudioAEC`) as a fallback.
+
+Gated behind the `windows-aec` feature in `wzp-client`. Enabled by default in the Windows target section of `desktop/src-tauri/Cargo.toml`.
+
+## Build pipelines
+
+### Native macOS / Linux
+
+```bash
+cd desktop
+npm install
+npm run build
+cd src-tauri
+cargo build --release --bin wzp-desktop
+```
+
+### Windows x86_64 via Docker on SepehrHomeserverdk
+
+```bash
+./scripts/build-windows-docker.sh # Full: pull + build + download
+./scripts/build-windows-docker.sh --no-pull # Skip git fetch
+./scripts/build-windows-docker.sh --rust # Force-clean Rust target
+./scripts/build-windows-docker.sh --image-build # (Re)build the Docker image (fire-and-forget)
+```
+
+Output lands at `target/windows-exe/wzp-desktop.exe`. Both `wzp-desktop.exe` and `wzp-desktop-noAEC.exe` can coexist in that directory; the script writes `wzp-desktop.exe` so renaming the prior build to `-noAEC.exe` (or any other name) before rebuilding preserves it.
+
+### Windows x86_64 via Hetzner Cloud (alternative)
+
+```bash
+./scripts/build-windows-cloud.sh # Full: create VM → build → download → destroy
+./scripts/build-windows-cloud.sh --prepare # Create VM and install deps only
+./scripts/build-windows-cloud.sh --build # Build on existing VM
+./scripts/build-windows-cloud.sh --destroy # Delete the VM
+WZP_KEEP_VM=1 ./scripts/build-windows-cloud.sh # Keep VM alive after build for debug
+```
+
+Remember to destroy the VM at end of day with `--destroy`.
+
+### Linux x86_64 (relay + CLI + bench)
+
+```bash
+./scripts/build-linux-docker.sh # Fire-and-forget remote Docker build
+./scripts/build-linux-docker.sh --install # Wait for completion and download
+```
+
+Uses the same `wzp-android-builder` Docker image as Android (not a separate image), since the deps (Rust + cmake + ring prereqs) are the same.
+
+## Testing
+
+### Direct calling parity
+
+1. Build on two machines (macOS + Windows, or two macOS, or any combination).
+2. Both machines register on the same relay.
+3. Copy one machine's fingerprint into the other's direct-call panel.
+4. Place the call. Confirm ringing UI on the callee and "calling…" UI on the caller.
+5. Answer. Confirm audio flows both ways.
+6. Hang up from either side. Confirm call-history entries are labeled correctly (`Outgoing` on caller, `Incoming` on callee, never `Missed` on a successful call).
+
+### Windows AEC A/B
+
+1. Install `wzp-desktop-noAEC.exe` and `wzp-desktop.exe` on the same Windows box.
+2. Join a call from each (separately) while a second machine plays known audio through the first machine's speakers.
+3. On the remote (listening) side: the `noAEC` call should have clear audible echo; the AEC call should have minimal or no echo after a 1–2 s convergence period.
+4. If both builds sound identical (with echo) → the `AudioCategory_Communications` switch isn't triggering the driver's APO chain. Investigate via task #26 (Voice Capture DSP fallback).
+
+## Known quirks
+
+1. **libopus vendor path is workspace-relative**. `[patch.crates-io] audiopus_sys = { path = "vendor/audiopus_sys" }` works from any crate in the workspace because Cargo resolves it against the root `Cargo.toml`'s directory. If the workspace is moved or vendored into another workspace, update the path.
+
+2. **`cargo xwin` overwrites `override.cmake` on every invocation**. Any attempt to patch `~/.cache/cargo-xwin/cmake/clang-cl/override.cmake` at Docker image build time is inert because `src/compiler/clang_cl.rs` line ~444 writes the bundled file fresh on every run. All real fixes must land in the source tree (via the vendored audiopus_sys, as done here), not in the cargo-xwin cache.
+
+3. **WebView2 runtime is a prerequisite on Windows 10**. Windows 11 ships with it. If the `.exe` launches and immediately exits with no error on a Win10 machine, that's the missing runtime — install it from [Microsoft's Evergreen bootstrapper](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
+
+4. **Rust 2024 edition `unsafe_op_in_unsafe_fn` lint**. The WASAPI backend in `audio_wasapi.rs` emits ~18 of these warnings because Rust 2024 requires explicit `unsafe { ... }` blocks inside `unsafe fn` bodies. The warnings don't block the build and don't affect runtime behavior; cleaning them up is tracked informally as tech debt.
+
+## Files of interest
+
+| Path | Purpose |
+|---|---|
+| `desktop/src/` | Shared frontend (TypeScript + HTML + CSS) |
+| `desktop/src-tauri/src/lib.rs` | Tauri commands shared with Android |
+| `desktop/src-tauri/src/engine.rs` | `CallEngine` wrapper |
+| `desktop/src-tauri/src/history.rs` | Persistent call history store with dedup |
+| `crates/wzp-client/src/audio_io.rs` | CPAL capture + playback (baseline) |
+| `crates/wzp-client/src/audio_vpio.rs` | macOS VoiceProcessingIO capture (AEC) |
+| `crates/wzp-client/src/audio_wasapi.rs` | Windows WASAPI communications capture (AEC) |
+| `vendor/audiopus_sys/opus/CMakeLists.txt` | Patched libopus for clang-cl SIMD |
+| `scripts/Dockerfile.windows-builder` | Windows cross-compile Docker image |
+| `scripts/build-windows-docker.sh` | Remote Docker build pipeline |
+| `scripts/build-windows-cloud.sh` | Hetzner VPS alternative pipeline |
+| `scripts/build-linux-docker.sh` | Linux x86_64 relay/CLI build pipeline |
diff --git a/vault/Architecture/Design.md b/vault/Architecture/Design.md
new file mode 100644
index 0000000..002f154
--- /dev/null
+++ b/vault/Architecture/Design.md
@@ -0,0 +1,666 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# WarzonePhone Design Document
+
+> Custom encrypted VoIP protocol built in Rust. Designed for hostile network conditions: 5-70% packet loss, 100-500 kbps throughput, 300-800 ms RTT. Multi-platform: Desktop (Tauri), Android, CLI, Web.
+
+## System Overview
+
+WarzonePhone is a voice-over-IP system built from scratch in Rust, targeting reliable encrypted voice communication over severely degraded networks. The protocol uses adaptive codecs (Opus + Codec2), fountain-code FEC (RaptorQ), and end-to-end ChaCha20-Poly1305 encryption over a QUIC transport layer.
+
+The system comprises three categories of components:
+
+1. **Protocol crates** -- a Rust workspace of 7 library crates with a star dependency graph enabling parallel development
+2. **Client applications** -- Desktop (Tauri), Android (Kotlin + JNI), CLI, and Web (browser bridge)
+3. **Relay infrastructure** -- SFU relay daemons with federation, health probing, and Prometheus metrics
+
+### Design Principles
+
+- **User sovereignty** -- client-driven route selection, BIP39 identity backup, no central authority
+- **End-to-end encryption** -- relays never see plaintext audio; SFU forwarding preserves E2E encryption
+- **Adaptive resilience** -- automatic codec and FEC switching based on observed network quality
+- **Parallel development** -- star dependency graph allows 5 agents/developers to work simultaneously with zero merge conflicts
+
+## Architecture
+
+### Crate Overview
+
+The workspace contains 7 core crates plus integration binaries:
+
+| Crate | Purpose | Key Dependencies |
+|-------|---------|-----------------|
+| `wzp-proto` | Protocol types, traits, wire format | serde, bytes |
+| `wzp-codec` | Audio codecs (Opus, Codec2, RNNoise) | audiopus, codec2, nnnoiseless |
+| `wzp-fec` | Forward error correction | raptorq |
+| `wzp-crypto` | Cryptography and identity | ed25519-dalek, x25519-dalek, chacha20poly1305, bip39 |
+| `wzp-transport` | QUIC transport layer | quinn, rustls |
+| `wzp-relay` | Relay daemon (SFU, federation, metrics) | tokio, prometheus |
+| `wzp-client` | Call engine and CLI | All above |
+
+Additional integration targets: `wzp-web` (browser bridge via WebSocket), Android native library (JNI), Desktop (Tauri).
+
+### Dependency Graph
+
+```mermaid
+graph TD
+ PROTO["wzp-proto
(Types, Traits, Wire Format)"]
+
+ CODEC["wzp-codec
(Opus + Codec2 + RNNoise)"]
+ FEC["wzp-fec
(RaptorQ FEC)"]
+ CRYPTO["wzp-crypto
(ChaCha20 + Identity)"]
+ TRANSPORT["wzp-transport
(QUIC / Quinn)"]
+
+ RELAY["wzp-relay
(Relay Daemon)"]
+ CLIENT["wzp-client
(CLI + Call Engine)"]
+ WEB["wzp-web
(Browser Bridge)"]
+ DESKTOP["Desktop
(Tauri + CPAL)"]
+ ANDROID["Android
(Kotlin + JNI)"]
+
+ PROTO --> CODEC
+ PROTO --> FEC
+ PROTO --> CRYPTO
+ PROTO --> TRANSPORT
+
+ CODEC --> CLIENT
+ FEC --> CLIENT
+ CRYPTO --> CLIENT
+ TRANSPORT --> CLIENT
+
+ CODEC --> RELAY
+ FEC --> RELAY
+ CRYPTO --> RELAY
+ TRANSPORT --> RELAY
+
+ CLIENT --> WEB
+ CLIENT --> DESKTOP
+ CLIENT --> ANDROID
+ TRANSPORT --> WEB
+
+ FC["warzone-protocol
(featherChat Identity)"] -.->|path dep| CRYPTO
+
+ style PROTO fill:#6c5ce7,color:#fff
+ style RELAY fill:#ff9f43,color:#fff
+ style CLIENT fill:#00b894,color:#fff
+ style WEB fill:#0984e3,color:#fff
+ style DESKTOP fill:#0984e3,color:#fff
+ style ANDROID fill:#0984e3,color:#fff
+ style FC fill:#fd79a8,color:#fff
+```
+
+The star pattern ensures each leaf crate (`wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`) depends only on `wzp-proto` and never on each other. This enables:
+
+- **Parallel development** -- 5 agents work on 5 crates with no merge conflicts
+- **Independent testing** -- each crate has self-contained tests
+- **Pluggability** -- any implementation can be swapped by implementing the same trait
+- **Fast compilation** -- changing one leaf only recompiles that leaf and integration crates
+
+## Audio Pipeline
+
+### Encode Pipeline (Mic to Network)
+
+```mermaid
+sequenceDiagram
+ participant Mic as Microphone
+ participant RNN as RNNoise Denoise
+ participant VAD as Silence Detector
+ participant ENC as Opus/Codec2 Encode
+ participant FEC as RaptorQ FEC Encode
+ participant INT as Interleaver
+ participant HDR as Header Assembly
+ participant CRYPT as ChaCha20-Poly1305
+ participant QUIC as QUIC Datagram
+
+ Mic->>RNN: PCM i16 x 960 (20ms @ 48kHz)
+ RNN->>VAD: Denoised samples (2 x 480)
+ alt Silence detected (>100ms)
+ VAD->>ENC: ComfortNoise packet (every 200ms)
+ else Active speech or hangover
+ VAD->>ENC: Active audio frame
+ end
+ ENC->>FEC: Compressed frame (padded to 256 bytes)
+ FEC->>FEC: Accumulate block (5-10 frames)
+ FEC->>INT: Source + repair symbols
+ INT->>HDR: Interleaved packets (depth=3)
+ HDR->>CRYPT: MediaHeader (12B) or MiniHeader (4B)
+ CRYPT->>QUIC: Header=AAD, Payload=encrypted
+```
+
+### Decode Pipeline (Network to Speaker)
+
+```mermaid
+sequenceDiagram
+ participant QUIC as QUIC Datagram
+ participant CRYPT as ChaCha20-Poly1305
+ participant HDR as Header Parse
+ participant DEINT as De-interleaver
+ participant FEC as RaptorQ FEC Decode
+ participant JIT as Jitter Buffer
+ participant DEC as Opus/Codec2 Decode
+ participant SPK as Speaker
+
+ QUIC->>CRYPT: Encrypted packet
+ CRYPT->>HDR: Decrypt (header=AAD)
+ HDR->>DEINT: Parsed MediaHeader + payload
+ DEINT->>FEC: Reordered symbols
+ FEC->>FEC: Reconstruct from any K of K+R symbols
+ FEC->>JIT: Recovered audio frames
+ JIT->>JIT: Sequence-ordered BTreeMap
+ JIT->>DEC: Pop when depth >= target
+ DEC->>SPK: PCM i16 x 960
+```
+
+## Codec System
+
+WarzonePhone uses a dual-codec architecture to cover the full range of network conditions:
+
+### Opus (Primary)
+
+Opus is the primary codec for normal to degraded conditions. It operates at 48 kHz natively with built-in inband FEC and DTX (discontinuous transmission). The `audiopus` crate provides mature Rust bindings to libopus.
+
+| Profile | Bitrate | Frame Duration | FEC Ratio | Total Bandwidth | Use Case |
+|---------|---------|---------------|-----------|----------------|----------|
+| Studio 64k | 64 kbps | 20ms | 10% | 70.4 kbps | LAN, excellent WiFi |
+| Studio 48k | 48 kbps | 20ms | 10% | 52.8 kbps | Good WiFi, wired |
+| Studio 32k | 32 kbps | 20ms | 10% | 35.2 kbps | WiFi, LTE |
+| Good (24k) | 24 kbps | 20ms | 20% | 28.8 kbps | WiFi, LTE, decent links |
+| Opus 16k | 16 kbps | 20ms | 20% | 19.2 kbps | 3G, moderate congestion |
+| Degraded (6k) | 6 kbps | 40ms | 50% | 9.0 kbps | 3G, congested WiFi |
+
+### Codec2 (Fallback)
+
+Codec2 is a narrowband vocoder designed for HF radio links with extreme bandwidth constraints. It operates at 8 kHz, and the adaptive layer handles 48 kHz <-> 8 kHz resampling transparently. The pure-Rust `codec2` crate means no C dependencies.
+
+| Profile | Bitrate | Frame Duration | FEC Ratio | Total Bandwidth | Use Case |
+|---------|---------|---------------|-----------|----------------|----------|
+| Codec2 3200 | 3.2 kbps | 20ms | 50% | 4.8 kbps | Poor conditions |
+| Catastrophic (1200) | 1.2 kbps | 40ms | 100% | 2.4 kbps | Satellite, extreme loss |
+
+### ComfortNoise
+
+When the silence detector identifies no speech activity for over 100ms, the encoder switches to emitting a ComfortNoise packet every 200ms instead of encoding silence. This provides approximately 50% bandwidth savings in typical conversations.
+
+### Adaptive Switching
+
+The `AdaptiveEncoder`/`AdaptiveDecoder` in `wzp-codec` hold both codec instances and switch between them based on the active `QualityProfile`. This avoids codec re-initialization latency during tier transitions. The `AdaptiveQualityController` in `wzp-proto` manages tier transitions with hysteresis:
+
+- **Downgrade**: 3 consecutive bad reports (2 on cellular networks)
+- **Upgrade**: 10 consecutive good reports (one tier at a time)
+- **Network handoff**: WiFi-to-cellular switch triggers preemptive one-tier downgrade plus a temporary 10-second FEC boost (+20%)
+
+Quality tier classification thresholds:
+
+| Tier | WiFi/Unknown | Cellular |
+|------|-------------|----------|
+| Good | loss < 10%, RTT < 400ms | loss < 8%, RTT < 300ms |
+| Degraded | loss 10-40%, RTT 400-600ms | loss 8-25%, RTT 300-500ms |
+| Catastrophic | loss > 40%, RTT > 600ms | loss > 25%, RTT > 500ms |
+
+## Forward Error Correction (FEC)
+
+### Why RaptorQ Over Reed-Solomon
+
+WarzonePhone uses RaptorQ (RFC 6330) fountain codes via the `raptorq` crate:
+
+1. **Rateless** -- generate arbitrary repair symbols on the fly; if conditions worsen mid-block, generate additional repair without re-encoding
+2. **Efficient decoding** -- decode from any K symbols with high probability (typically K + 1 or K + 2 suffice)
+3. **Lower complexity** -- O(K) encoding/decoding time vs O(K^2) for Reed-Solomon
+4. **Variable block sizes** -- 1-56,403 source symbols per block (WZP uses 5-10)
+
+### FEC Block Structure
+
+Each FEC block consists of 5-10 audio frames padded to 256-byte symbols with a 2-byte LE length prefix:
+
+```
+[len:u16 LE][audio_frame][zero_padding_to_256_bytes]
+```
+
+### Loss Survival by FEC Ratio
+
+With 5 source frames per block:
+
+| FEC Ratio | Repair Symbols | Survives Loss | Profile |
+|-----------|---------------|---------------|---------|
+| 10% | 1 | 1 of 6 (16.7%) | Studio |
+| 20% | 1 | 1 of 6 (16.7%) | Good |
+| 50% | 3 | 3 of 8 (37.5%) | Degraded |
+| 100% | 5 | 5 of 10 (50.0%) | Catastrophic |
+
+### Interleaving
+
+Burst loss protection via depth-3 interleaving: packets from 3 consecutive FEC blocks are interleaved before transmission. A burst of 3 consecutive lost packets affects 3 different blocks (1 loss each) rather than destroying 1 block entirely.
+
+```mermaid
+graph LR
+ subgraph "FEC Encoder"
+ F1[Frame 1] --> BLK[Source Block
5-10 frames]
+ F2[Frame 2] --> BLK
+ F3[Frame 3] --> BLK
+ F4[Frame 4] --> BLK
+ F5[Frame 5] --> BLK
+ BLK --> SRC[Source Symbols]
+ BLK --> REP[Repair Symbols
ratio-dependent]
+ SRC --> INT[Interleaver
depth=3]
+ REP --> INT
+ end
+
+ subgraph "Network"
+ INT --> LOSS{Packet Loss}
+ LOSS -->|some lost| RCV[Received Symbols]
+ end
+
+ subgraph "FEC Decoder"
+ RCV --> DEINT[De-interleaver]
+ DEINT --> RAPTORQ[RaptorQ Decode
Any K of K+R]
+ RAPTORQ --> OUT[Original Frames]
+ end
+
+ style LOSS fill:#e17055,color:#fff
+ style RAPTORQ fill:#00b894,color:#fff
+```
+
+## Transport Layer
+
+### Why QUIC Over Raw UDP
+
+WarzonePhone uses QUIC (via the `quinn` crate) rather than raw UDP for several reasons:
+
+| Feature | Benefit |
+|---------|---------|
+| DATAGRAM frames (RFC 9221) | Unreliable delivery without head-of-line blocking -- behaves like UDP for media |
+| Reliable streams | Multiplexed signaling (CallOffer, Hangup, Rekey) without a separate TCP connection |
+| Congestion control | Prevents overwhelming degraded links, important when chaining relays |
+| Connection migration | Connections survive IP address changes (WiFi to cellular handoff) |
+| TLS 1.3 built-in | Transport-level encryption protects headers and signaling |
+| NAT keepalive | 5-second interval maintains NAT bindings without application-level pings |
+| Firewall traversal | Runs on UDP port 443 with `wzp` ALPN identifier |
+
+The tradeoff is approximately 20-40 bytes of additional per-packet overhead compared to raw UDP.
+
+### Wire Formats
+
+#### MediaHeader (12 bytes)
+
+```
+Byte 0: [V:1][T:1][CodecID:4][Q:1][FecRatioHi:1]
+Byte 1: [FecRatioLo:6][unused:2]
+Bytes 2-3: sequence (u16 BE)
+Bytes 4-7: timestamp_ms (u32 BE)
+Byte 8: fec_block_id (u8)
+Byte 9: fec_symbol_idx (u8)
+Byte 10: reserved
+Byte 11: csrc_count
+
+V = version (0), T = is_repair, CodecID = codec, Q = quality_report appended
+```
+
+#### MiniHeader (4 bytes, compressed)
+
+```
+Bytes 0-1: timestamp_delta_ms (u16 BE)
+Bytes 2-3: payload_len (u16 BE)
+
+Preceded by FRAME_TYPE_MINI (0x01). Full header every 50 frames (~1s).
+Saves 8 bytes/packet (67% header reduction).
+```
+
+#### TrunkFrame (batched datagrams)
+
+```
+[count:u16]
+ [session_id:2][len:u16][payload:len] x count
+
+Packs multiple session packets into one QUIC datagram.
+Max 10 entries or 1200 bytes, flushed every 5ms.
+```
+
+#### QualityReport (4 bytes, optional trailer)
+
+```
+Byte 0: loss_pct (0-255 maps to 0-100%)
+Byte 1: rtt_4ms (0-255 maps to 0-1020ms)
+Byte 2: jitter_ms
+Byte 3: bitrate_cap_kbps
+```
+
+### Bandwidth Summary
+
+| Profile | Audio | FEC Overhead | Total | Silence Savings |
+|---------|-------|-------------|-------|----------------|
+| Studio 64k | 64 kbps | 10% = 6.4 kbps | **70.4 kbps** | ~50% with DTX |
+| Studio 48k | 48 kbps | 10% = 4.8 kbps | **52.8 kbps** | ~50% with DTX |
+| Studio 32k | 32 kbps | 10% = 3.2 kbps | **35.2 kbps** | ~50% with DTX |
+| Good (24k) | 24 kbps | 20% = 4.8 kbps | **28.8 kbps** | ~50% with DTX |
+| Degraded (6k) | 6 kbps | 50% = 3.0 kbps | **9.0 kbps** | ~50% with DTX |
+| Catastrophic (1.2k) | 1.2 kbps | 100% = 1.2 kbps | **2.4 kbps** | ~50% with DTX |
+
+Additional savings: MiniHeaders save 8 bytes/packet (67% header reduction). Trunking shares QUIC overhead across multiplexed sessions.
+
+## Security
+
+### Identity Model
+
+Every user has a persistent identity derived from a 32-byte seed:
+
+```mermaid
+graph TD
+ SEED["32-byte Seed
(BIP39 Mnemonic: 24 words)"] --> HKDF1["HKDF
info='warzone-ed25519'"]
+ SEED --> HKDF2["HKDF
info='warzone-x25519'"]
+
+ HKDF1 --> ED["Ed25519 SigningKey
(Digital Signatures)"]
+ HKDF2 --> X25519["X25519 StaticSecret
(Key Agreement)"]
+
+ ED --> VKEY["Ed25519 VerifyingKey
(Public)"]
+ X25519 --> XPUB["X25519 PublicKey
(Public)"]
+
+ VKEY --> FP["Fingerprint
SHA-256(pubkey), truncated 16 bytes
xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx"]
+
+ style SEED fill:#6c5ce7,color:#fff
+ style FP fill:#fd79a8,color:#fff
+ style ED fill:#ee5a24,color:#fff
+ style X25519 fill:#00b894,color:#fff
+```
+
+**BIP39 Mnemonic Backup**: The 32-byte seed can be encoded as a 24-word BIP39 mnemonic for human-readable backup. The same seed produces the same identity on any platform.
+
+**featherChat Compatibility**: The identity derivation is compatible with the Warzone messenger (featherChat), allowing a shared identity across messaging and calling.
+
+### Cryptographic Handshake
+
+```mermaid
+sequenceDiagram
+ participant C as Caller
+ participant R as Relay / Callee
+
+ Note over C: Derive identity from seed
Ed25519 + X25519 via HKDF
+
+ C->>C: Generate ephemeral X25519 keypair
+ C->>C: Sign(ephemeral_pub || "call-offer")
+ C->>R: CallOffer { identity_pub, ephemeral_pub, signature, profiles }
+
+ R->>R: Verify Ed25519 signature
+ R->>R: Generate ephemeral X25519 keypair
+ R->>R: shared_secret = DH(eph_b, eph_a)
+ R->>R: session_key = HKDF(shared_secret, "warzone-session-key")
+ R->>R: Sign(ephemeral_pub || "call-answer")
+ R->>C: CallAnswer { identity_pub, ephemeral_pub, signature, profile }
+
+ C->>C: Verify signature
+ C->>C: shared_secret = DH(eph_a, eph_b)
+ C->>C: session_key = HKDF(shared_secret)
+
+ Note over C,R: Both have identical ChaCha20-Poly1305 session key
+ C->>R: Encrypted media (QUIC datagrams)
+ R->>C: Encrypted media (QUIC datagrams)
+
+ Note over C,R: Rekey every 65,536 packets
New ephemeral DH + HKDF mix
+```
+
+### Encryption Details
+
+| Component | Algorithm | Purpose |
+|-----------|-----------|---------|
+| Identity signing | Ed25519 | Authenticate handshake messages |
+| Key agreement | X25519 (ephemeral) | Derive shared secret |
+| Key derivation | HKDF-SHA256 | Derive session key from shared secret |
+| Media encryption | ChaCha20-Poly1305 | Encrypt audio payloads (16-byte tag) |
+| Nonce construction | Deterministic from sequence number | No nonce reuse, no state sync needed |
+| Anti-replay | Sliding window (64-packet) | Reject duplicate/old packets |
+| Forward secrecy | Rekey every 65,536 packets | New ephemeral DH + HKDF mix |
+
+**Why ChaCha20-Poly1305 over AES-GCM**:
+- Faster on hardware without AES-NI (ARM phones, Raspberry Pi relays)
+- Inherently constant-time (add-rotate-XOR only)
+- Compatible with Warzone messenger (featherChat)
+- Same 16-byte authentication tag overhead as AES-GCM
+
+**AEAD with AAD**: The MediaHeader is used as Associated Authenticated Data. The header is authenticated but not encrypted, allowing relays to read routing information (block ID, sequence number) without decrypting the payload.
+
+### Trust on First Use (TOFU)
+
+Clients remember the relay's TLS certificate fingerprint after first connection. If the fingerprint changes on a subsequent connection, the desktop client shows a "Server Key Changed" warning dialog. The relay derives its TLS certificate deterministically from its persisted identity seed, so the fingerprint is stable across restarts.
+
+## Relay Architecture
+
+### Room Mode (Default SFU)
+
+In room mode, the relay acts as a Selective Forwarding Unit. Clients join named rooms via the QUIC SNI (Server Name Indication) field. The relay forwards each participant's encrypted packets to all other participants in the room without decoding or re-encoding.
+
+```mermaid
+graph TB
+ subgraph "Room Mode (SFU)"
+ C1[Client 1] -->|"QUIC SNI=room-hash"| RM[Room Manager]
+ C2[Client 2] -->|"QUIC SNI=room-hash"| RM
+ C3[Client 3] -->|"QUIC SNI=room-hash"| RM
+ RM --> R1[Room 'podcast']
+ R1 -->|fan-out| C1
+ R1 -->|fan-out| C2
+ R1 -->|fan-out| C3
+ end
+
+ style RM fill:#ff9f43,color:#fff
+ style R1 fill:#fdcb6e
+```
+
+**SFU vs MCU trade-off**: SFU was chosen because it preserves end-to-end encryption (the relay never sees plaintext audio). An MCU would need to decode, mix, and re-encode, breaking E2E encryption. The trade-off is O(N) bandwidth at the relay for N participants.
+
+### Forward Mode
+
+With `--remote`, the relay forwards all traffic to a remote relay. Used for chaining relays across lossy or censored links:
+
+```
+Client --> Relay A (--remote B) --> Relay B --> Destination Client
+```
+
+The relay pipeline in forward mode: FEC decode, jitter buffer, then FEC re-encode for the next hop.
+
+## Federation
+
+### Overview
+
+Two or more relays form a federation mesh. Each relay is an independent SFU. When configured to trust each other, they bridge **global rooms** -- participants on relay A in a global room hear participants on relay B in the same room.
+
+### Configuration
+
+Federation uses three TOML configuration sections:
+
+- `[[peers]]` -- outbound connections to peer relays (url + TLS fingerprint)
+- `[[trusted]]` -- inbound connections accepted from relays (TLS fingerprint only)
+- `[[global_rooms]]` -- room names to bridge across all federated peers
+
+### Federation Topology
+
+```mermaid
+graph TB
+ subgraph "Relay A (EU)"
+ A_RM[Room Manager]
+ A_FM[Federation Manager]
+ A1[Alice - local]
+ A2[Bob - local]
+ A_RM --> A_FM
+ end
+
+ subgraph "Relay B (US)"
+ B_RM[Room Manager]
+ B_FM[Federation Manager]
+ B1[Charlie - local]
+ B_RM --> B_FM
+ end
+
+ A_FM <-->|"QUIC SNI='_federation'
GlobalRoomActive/Inactive
Media forwarding"| B_FM
+
+ A1 -->|media| A_RM
+ A2 -->|media| A_RM
+ B1 -->|media| B_RM
+
+ A_RM -->|"federated fan-out"| A1
+ A_RM -->|"federated fan-out"| A2
+ B_RM -->|"federated fan-out"| B1
+
+ style A_FM fill:#6c5ce7,color:#fff
+ style B_FM fill:#6c5ce7,color:#fff
+ style A_RM fill:#ff9f43,color:#fff
+ style B_RM fill:#ff9f43,color:#fff
+```
+
+### Protocol
+
+1. On startup, each relay connects to all configured `[[peers]]` via QUIC with SNI `"_federation"`
+2. After QUIC handshake, sends `FederationHello { tls_fingerprint }` for identity verification
+3. Peer verifies the fingerprint against its `[[trusted]]` or `[[peers]]` list
+4. When a local participant joins a global room, sends `GlobalRoomActive { room }` to all peers
+5. When the last local participant leaves, sends `GlobalRoomInactive { room }`
+6. Media is forwarded as `[room_hash:8][original_media_packet]` -- the relay does not decrypt
+
+### What Relays Do NOT Do
+
+- **No transcoding** -- media passes through as-is
+- **No re-encryption** -- packets are already encrypted E2E
+- **No central coordinator** -- each relay independently connects to configured peers
+- **No automatic peer discovery** -- peers must be explicitly configured
+
+### Failure Handling
+
+- If a peer goes down, local rooms continue working; federated participants disappear from presence
+- Reconnection: every 30 seconds with exponential backoff up to 5 minutes
+- If a peer restarts with a different identity, the fingerprint check fails with a clear log message
+
+## Jitter Buffer
+
+The jitter buffer balances latency vs quality:
+
+| Setting | Client | Relay |
+|---------|--------|-------|
+| Target depth | 10 packets (200ms) | 50 packets (1s) |
+| Minimum before playout | 3 packets (60ms) | 25 packets (500ms) |
+| Maximum cap | 250 packets (5s) | 250 packets (5s) |
+
+The relay uses a deeper buffer to absorb jitter from lossy inter-relay links. The client uses a shallower buffer for lower latency.
+
+The adaptive playout delay tracks jitter via exponential moving average and adjusts the target depth:
+
+```
+target_delay = ceil(jitter_ema / 20ms) + 2
+```
+
+**Known limitation**: The current jitter buffer does not use timestamp-based playout scheduling. It relies on sequence-number ordering only, which can lead to drift during long calls.
+
+## Signal Messages
+
+Signal messages are sent over reliable QUIC streams as length-prefixed JSON:
+
+```
+[4-byte length prefix][serde_json payload]
+```
+
+| Message | Purpose |
+|---------|---------|
+| `CallOffer` | Identity, ephemeral key, signature, supported profiles |
+| `CallAnswer` | Identity, ephemeral key, signature, chosen profile |
+| `AuthToken` | featherChat bearer token for relay authentication |
+| `Hangup` | Reason: Normal, Busy, Declined, Timeout, Error |
+| `Hold` / `Unhold` | Call hold state |
+| `Mute` / `Unmute` | Mic mute state |
+| `Transfer` | Call transfer to another relay/fingerprint |
+| `Rekey` | New ephemeral key for forward secrecy |
+| `QualityUpdate` | Quality report + recommended profile |
+| `Ping` / `Pong` | Latency measurement (timestamp_ms) |
+| `RoomUpdate` | Participant list changes |
+| `PresenceUpdate` | Federation presence gossip |
+| `RouteQuery` / `RouteResponse` | Presence discovery for routing |
+| `FederationHello` | Relay identity during federation setup |
+| `GlobalRoomActive` / `GlobalRoomInactive` | Federation room bridging |
+
+## Test Coverage
+
+571 tests across all crates, 0 failures:
+
+| Crate | Tests | Key Coverage |
+|-------|-------|-------------|
+| wzp-proto | 41 | Wire format, jitter buffer, quality tiers, mini-frames, trunking |
+| wzp-codec | 31 | Opus/Codec2 roundtrip, silence detection, noise suppression |
+| wzp-fec | 22 | RaptorQ encode/decode, loss recovery, interleaving |
+| wzp-crypto | 34 + 28 compat | Encrypt/decrypt, handshake, anti-replay, featherChat identity |
+| wzp-transport | 2 | QUIC connection setup |
+| wzp-relay | 40 + 4 integration | Room ACL, session mgmt, metrics, probes, mesh, trunking |
+| wzp-client | 30 + 2 integration | Encoder/decoder, quality adapter, silence, drift, sweep |
+| wzp-web | 2 | Metrics |
+
+## Audio Routing (Android)
+
+WarzonePhone supports three audio output routes on Android: **Earpiece**, **Speaker**, and **Bluetooth SCO**. The user cycles through available routes with a single button.
+
+### Audio mode lifecycle
+
+`MODE_IN_COMMUNICATION` is set **when the call engine starts** (right before Oboe `audio_start()`), not at app launch. This is critical — setting it early hijacks system audio routing (e.g. music drops from BT A2DP to earpiece). `MODE_NORMAL` is restored when the call engine stops.
+
+```
+App launch → MODE_NORMAL (other apps' audio unaffected)
+Call start → set_audio_mode_communication() → MODE_IN_COMMUNICATION
+Call end → audio_stop() → set_audio_mode_normal() → MODE_NORMAL
+```
+
+### Route lifecycle
+
+1. Call starts → Earpiece (default).
+2. User taps route button → cycles to next available route.
+3. Route change requires Oboe stream restart (~60-400ms) because AAudio silently tears down streams on some OEMs when the routing target changes mid-stream.
+4. Bluetooth disconnect mid-call → `AudioDeviceCallback.onAudioDevicesRemoved` fires → auto-fallback to Earpiece or Speaker.
+
+### Bluetooth SCO
+
+SCO (Synchronous Connection Oriented) is the correct Bluetooth profile for VoIP — it provides bidirectional mono audio at 8/16 kHz with ~30ms latency. A2DP (stereo, high-quality) is unidirectional and adds 100-200ms of buffering, making it unsuitable for real-time voice.
+
+On API 31+ (Android 12), we use the modern `setCommunicationDevice(AudioDeviceInfo)` API to route audio to the BT SCO device. The deprecated `startBluetoothSco()` + `setBluetoothScoOn()` path is used as fallback on older APIs. `setBluetoothScoOn()` is silently rejected on Android 12+ for non-system apps.
+
+BT SCO devices only support 8/16kHz sample rates, but our pipeline runs at 48kHz. When BT is active, Oboe opens in **BT mode** (`bt_active=1`): capture skips `setSampleRate(48000)` and `setInputPreset(VoiceCommunication)`, letting the system open at the device's native rate. Oboe's `SampleRateConversionQuality::Best` resamples to/from 48kHz for our ring buffers.
+
+### Two app variants
+
+Both the native Kotlin app (`AudioRouteManager.kt`) and the Tauri app (`android_audio.rs` JNI bridge) support BT SCO routing. The native app uses `AudioDeviceCallback` for automatic device detection; the Tauri app uses `getAvailableCommunicationDevices()` (API 31+) or `getDevices()` on demand.
+
+## Network Change Response
+
+The `AdaptiveQualityController` in `wzp-proto` reacts to network transport changes signaled via `signal_network_change(NetworkContext)`:
+
+| Transition | Response |
+|-----------|----------|
+| WiFi → Cellular | Preemptive 1-tier quality downgrade + 10s FEC boost |
+| Cellular → WiFi | FEC boost only (quality recovers via normal adaptive logic) |
+| Any change | Reset hysteresis counters to avoid stale state |
+
+On Android, `NetworkMonitor.kt` wraps `ConnectivityManager.NetworkCallback` and classifies the transport type using bandwidth heuristics (no `READ_PHONE_STATE` needed). The classification is delivered to the Rust engine via JNI → `AtomicU8` → recv task polling — the same lock-free cross-task signaling pattern used for adaptive profile switches.
+
+### Cellular generation heuristics
+
+| Downstream bandwidth | Classification |
+|---------------------|---------------|
+| >= 100 Mbps | 5G NR |
+| >= 10 Mbps | LTE |
+| < 10 Mbps | 3G or worse |
+
+These thresholds are conservative. Carriers over-report bandwidth, but for VoIP quality decisions the exact generation matters less than the rough category.
+
+## Build Requirements
+
+- **Rust** 1.85+ (2024 edition)
+- **Linux**: cmake, pkg-config, libasound2-dev (for audio feature)
+- **macOS**: Xcode command line tools (CoreAudio included)
+- **Android**: NDK 26.1 (r26b), cmake 3.25-3.28 (system package)
+
+### Android APK Builds
+
+```bash
+# arm64 only (default, 25MB release APK)
+./scripts/build-tauri-android.sh --init --release --arch arm64
+
+# armv7 only (smaller devices)
+./scripts/build-tauri-android.sh --init --release --arch armv7
+
+# both architectures as separate APKs
+./scripts/build-tauri-android.sh --init --release --arch all
+```
+
+Release APKs are signed with `android/keystore/wzp-release.jks` via `apksigner`. Per-arch builds produce separate APKs (~25MB each vs ~50MB universal) for easier sharing with testers.
diff --git a/vault/Architecture/Extensibility.md b/vault/Architecture/Extensibility.md
new file mode 100644
index 0000000..e94e9f7
--- /dev/null
+++ b/vault/Architecture/Extensibility.md
@@ -0,0 +1,209 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# WarzonePhone Extension Points & Future Features
+
+## Trait-Based Architecture
+
+The protocol is designed around trait interfaces defined in `crates/wzp-proto/src/traits.rs`. Any implementation that satisfies the trait contract can be plugged in without modifying other crates.
+
+### Adding a New Audio Codec
+
+Implement `AudioEncoder` and `AudioDecoder` from `wzp_proto::traits`:
+
+```rust
+pub trait AudioEncoder: Send + Sync {
+ fn encode(&mut self, pcm: &[i16], out: &mut [u8]) -> Result;
+ fn codec_id(&self) -> CodecId;
+ fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError>;
+ fn max_frame_bytes(&self) -> usize;
+ fn set_inband_fec(&mut self, _enabled: bool) {}
+ fn set_dtx(&mut self, _enabled: bool) {}
+}
+
+pub trait AudioDecoder: Send + Sync {
+ fn decode(&mut self, encoded: &[u8], pcm: &mut [i16]) -> Result;
+ fn decode_lost(&mut self, pcm: &mut [i16]) -> Result;
+ fn codec_id(&self) -> CodecId;
+ fn set_profile(&mut self, profile: QualityProfile) -> Result<(), CodecError>;
+}
+```
+
+Steps:
+1. Add a new variant to `CodecId` in `crates/wzp-proto/src/codec_id.rs` (uses 4-bit wire encoding, currently 5 of 16 values used)
+2. Implement `AudioEncoder` and `AudioDecoder` for your codec
+3. Register the codec in `AdaptiveEncoder`/`AdaptiveDecoder` in `crates/wzp-codec/src/adaptive.rs`
+4. Add a `QualityProfile` constant for the new codec
+
+### Adding a New FEC Scheme
+
+Implement `FecEncoder` and `FecDecoder` from `wzp_proto::traits`:
+
+```rust
+pub trait FecEncoder: Send + Sync {
+ fn add_source_symbol(&mut self, data: &[u8]) -> Result<(), FecError>;
+ fn generate_repair(&mut self, ratio: f32) -> Result)>, FecError>;
+ fn finalize_block(&mut self) -> Result;
+ fn current_block_id(&self) -> u8;
+ fn current_block_size(&self) -> usize;
+}
+
+pub trait FecDecoder: Send + Sync {
+ fn add_symbol(&mut self, block_id: u8, symbol_index: u8, is_repair: bool, data: &[u8]) -> Result<(), FecError>;
+ fn try_decode(&mut self, block_id: u8) -> Result>>, FecError>;
+ fn expire_before(&mut self, block_id: u8);
+}
+```
+
+For example, a Reed-Solomon implementation would maintain the same block/symbol structure but use a different coding algorithm internally. The FEC block ID and symbol index fields in `MediaHeader` support any scheme that fits the block/symbol model.
+
+### Adding a New Transport
+
+Implement `MediaTransport` from `wzp_proto::traits`:
+
+```rust
+#[async_trait]
+pub trait MediaTransport: Send + Sync {
+ async fn send_media(&self, packet: &MediaPacket) -> Result<(), TransportError>;
+ async fn recv_media(&self) -> Result, TransportError>;
+ async fn send_signal(&self, msg: &SignalMessage) -> Result<(), TransportError>;
+ async fn recv_signal(&self) -> Result, TransportError>;
+ fn path_quality(&self) -> PathQuality;
+ async fn close(&self) -> Result<(), TransportError>;
+}
+```
+
+A raw UDP transport, a WebRTC data channel transport, or a TCP tunnel transport could all implement this trait.
+
+## Obfuscation Layer (Phase 2)
+
+The `ObfuscationLayer` trait is defined in `crates/wzp-proto/src/traits.rs` but not yet implemented:
+
+```rust
+pub trait ObfuscationLayer: Send + Sync {
+ fn obfuscate(&mut self, data: &[u8], out: &mut Vec) -> Result<(), ObfuscationError>;
+ fn deobfuscate(&mut self, data: &[u8], out: &mut Vec) -> Result<(), ObfuscationError>;
+}
+```
+
+Planned implementations:
+- **TLS-in-TLS**: Wrap QUIC traffic inside a TLS connection to port 443, making it look like ordinary HTTPS
+- **HTTP/2 mimicry**: Frame QUIC packets as HTTP/2 data frames
+- **Random padding**: Add random-length padding to defeat traffic analysis
+- **Domain fronting**: Use CDN infrastructure to hide the true destination
+
+The obfuscation layer sits between the crypto layer and the transport layer in the protocol stack, wrapping encrypted packets before transmission.
+
+## FeatherChat / Warzone Messenger Integration
+
+As described in `docs/featherchat.md`, WarzonePhone is designed to integrate with the existing Warzone messenger.
+
+### Shared Identity Model
+
+Both WarzonePhone and Warzone use the same identity derivation:
+- 32-byte seed (BIP39 mnemonic backup)
+- HKDF with context strings: `"warzone-ed25519-identity"` and `"warzone-x25519-identity"`
+- Ed25519 for signing, X25519 for encryption
+- Fingerprint: `SHA-256(Ed25519_pub)[:16]`
+
+This is implemented in `crates/wzp-crypto/src/handshake.rs` as `WarzoneKeyExchange::from_identity_seed()`.
+
+### Signaling via Existing WebSocket
+
+Call initiation flows through the Warzone messenger's existing WebSocket connection:
+1. Caller looks up callee via `@alias`, federated address, or raw fingerprint
+2. Caller sends `WireMessage::CallOffer` through the existing message channel
+3. Callee receives the offer and responds with `WireMessage::CallAnswer`
+4. Both sides establish a direct QUIC connection to the relay using ephemeral keys from the signaling exchange
+
+The `SignalMessage::CallOffer` and `SignalMessage::CallAnswer` variants in `crates/wzp-proto/src/packet.rs` carry the same fields needed for this flow.
+
+### Key Derivation from Existing Shared Secret
+
+When two Warzone users already have an X3DH shared secret from their messaging session, call keys can be derived from it:
+- `HKDF(x3dh_shared_secret, "warzone-call-session")` -> 32-byte session key
+- Or: fresh ephemeral exchange per call (current implementation) for independent forward secrecy
+
+### Unified Addressing
+
+The Warzone addressing system resolves user identities across multiple namespaces:
+
+| Method | Format | Resolution |
+|--------|--------|------------|
+| Local alias | `@manwe` | Server resolves to fingerprint |
+| Federated | `@manwe.b1.example.com` | DNS TXT record -> fingerprint + endpoint |
+| ENS | `@manwe.eth` | Ethereum address -> fingerprint (planned) |
+| Raw fingerprint | `xxxx:xxxx:...` | Direct lookup |
+
+A user calls `@manwe` the same way they message `@manwe`.
+
+## Authentication: Caller Verification Before Bridging
+
+Currently, relays forward packets without verifying caller identity. To add authentication:
+
+1. **Relay-side handshake**: The relay receives the `CallOffer`, verifies the Ed25519 signature, and checks the caller's identity against an allowlist before accepting the connection.
+
+2. **Implementation point**: `crates/wzp-relay/src/handshake.rs` already implements `accept_handshake()` which performs signature verification. To gate admission, add an authorization check after signature verification.
+
+3. **Token-based auth**: Add a `token: Vec` field to `CallOffer` containing a relay-issued authentication token (e.g., signed by the relay operator's key).
+
+## Multi-Relay Mesh
+
+The current two-relay chain (`--remote` flag) can be extended to a multi-hop mesh:
+
+```
+Client -> Relay A -> Relay B -> Relay C -> Destination
+```
+
+Each hop uses the relay pipeline (FEC decode -> jitter buffer -> FEC re-encode) to absorb loss on each link independently. This requires:
+
+1. Relay discovery and route selection (not yet implemented)
+2. Per-hop FEC parameters (each link may have different loss characteristics)
+3. Cumulative latency management (each hop adds jitter buffer delay)
+
+## Video Support
+
+The trait architecture supports video by adding:
+
+1. **Video codec trait**: Similar to `AudioEncoder`/`AudioDecoder` but for video frames
+2. **Codec choices**: AV1 (best compression, higher CPU), VP9 SVC (scalable, moderate CPU)
+3. **Separate FEC strategy**: Video frames are larger and more critical (I-frames vs P-frames need different protection levels)
+4. **SVC (Scalable Video Coding)**: With VP9 SVC, the relay can drop enhancement layers without transcoding, adapting video quality to each receiver's bandwidth
+
+Video would add new `CodecId` variants and a separate `QualityProfile` for video parameters.
+
+## Android Native Client
+
+The workspace is designed with Android in mind (`wzp-client` description mentions "for Android (JNI) and Windows desktop"):
+
+1. **JNI bindings**: Use `jni` crate or `uniffi` to expose `CallEncoder`, `CallDecoder`, and `MediaTransport` to Kotlin/Java
+2. **Audio I/O**: Android uses AAudio or OpenSL ES instead of cpal
+3. **Build**: Cross-compile with `cargo ndk` targeting `aarch64-linux-android` and `armv7-linux-androideabi`
+4. **Permissions**: `RECORD_AUDIO`, `INTERNET`, `WAKE_LOCK`
+
+## STUN/TURN NAT Traversal Integration
+
+The `SignalMessage::IceCandidate` variant is already defined for NAT traversal:
+
+```rust
+IceCandidate { candidate: String }
+```
+
+Integration would involve:
+1. STUN server queries to discover the client's public IP/port
+2. ICE candidate exchange via the signaling channel
+3. TURN relay fallback when direct UDP is blocked
+4. Integration with the existing QUIC transport (QUIC can traverse NATs via its connection migration)
+
+## Bandwidth Estimation and Adaptive Bitrate
+
+The `PathMonitor` in `crates/wzp-transport/src/path_monitor.rs` already estimates bandwidth from observed packet rates. To close the loop:
+
+1. Feed `PathMonitor::quality()` into `AdaptiveQualityController::observe()` as `QualityReport` values
+2. The controller will trigger tier transitions when conditions change
+3. Propagate the new `QualityProfile` to both encoder (codec switch) and FEC (ratio change)
+4. Signal the peer via `SignalMessage::QualityUpdate` so both sides switch simultaneously
+
+The framework is in place; the missing piece is the integration wiring in the client's main loop to periodically generate quality reports from path metrics.
diff --git a/vault/Architecture/Protocol-Audit.md b/vault/Architecture/Protocol-Audit.md
new file mode 100644
index 0000000..e2275a7
--- /dev/null
+++ b/vault/Architecture/Protocol-Audit.md
@@ -0,0 +1,113 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# WZP Protocol Audit
+
+> Protocol-level review of WZP as of 2026-05-11. See `WZP-SPEC.md` for the spec being audited.
+
+## Strengths
+
+- **QUIC datagrams instead of raw UDP + SRTP** — buys TLS 1.3, PLPMTUD, path migration, and ACK-based loss/RTT estimation. Quinn's `PathSnapshot` feeding `DredTuner` is something WebRTC stacks build from scratch.
+- **Continuous DRED tuning.** Mapping RTT / loss / jitter to a continuous Opus DRED lookback window is genuinely better than discrete tiers — most stacks treat DRED as on/off.
+- **MiniHeader (49/50).** At 50 pps that is ~400 B/s saved per stream; meaningful at scale.
+- **SFU never decodes.** Preserves E2E. Most SFUs (LiveKit, Janus) terminate SRTP at the SFU.
+- **RaptorQ for low-bitrate Codec2 + DRED for Opus.** Correct split — DRED is cheaper than FEC at high bitrate; RaptorQ shines when you can afford many small symbols.
+
+## Weaknesses
+
+### W1. `u16` sequence wraps every ~21 minutes at 50 pps
+Anti-replay window is 64 packets so wrap is safe for replay. **But** the jitter buffer's `BTreeMap` will misorder across the wrap boundary if a packet is delayed more than ~32 k frames. Widen to `u32` (or version the field).
+
+### W2. `fec_block_id: u8` wraps every 256 blocks (~25 s at 5-frame blocks)
+A late-joining peer or a slow reconstructor can collide block IDs. Widen to `u16` or carry an epoch counter.
+
+### W3. `timestamp_ms` rebase behavior at rekey is unspecified
+Rekey every 65,536 packets (~22 min). If `timestamp_ms` resets, downstream sync glitches. If it does not, document explicitly.
+
+### W4. `MiniHeader` has no `seq`
+Receiver infers absolute seq from the most recent full header + frame count. One missed full header (every 50 frames = 1 s) leaves 49 packets with unknown absolute seq. Acceptable for audio with short jitter buffers — **fatal for video** where one missed full header can desync an entire GOP. **Add `seq_delta: u8` to MiniHeader before video lands.**
+
+### W5. `QualityReport` placement vs. AEAD
+A 4-byte trailer on encrypted media is fine **iff it sits inside the AEAD payload**. If it is outside, anything stripping the last 4 bytes corrupts decryption and creates a downgrade vector. Verify in `packet.rs`; if outside, move it inside or AAD-bind it.
+
+### W6. Adaptive controller is loss / RTT-only — no bandwidth estimator
+Quinn exposes `cwnd` and `bytes_in_flight`, but `AdaptiveQualityController` does not consume them. Under low utilization you cannot detect that you *could* upgrade to Opus 64 k. **For video this is mandatory** — without BWE you will either oscillate or never use available capacity.
+
+### W7. No NACK / explicit retransmit path
+For audio with DRED + FEC this is fine. For video keyframes it is wasteful — an I-frame is 50–200 packets, protecting at 50 % FEC doubles bitrate. A NACK path is cheap and far cheaper than blanket FEC for I-frames.
+
+### W8. TrunkFrame batching multiplies AEAD cost
+Each inner payload is its own AEAD operation. At 10 entries that is 10× ChaCha calls per recv. Fine on x86 / ARM with AES-NI / NEON; profile on weak Android (Nothing A059 baseline).
+
+### W9. `CodecID` is 4 bits → max 16 codecs; 9 already used
+Adding H.264, H.265, AV1, VP9 takes you to 13. Land the widening **before** deployment — either steal from `reserved` / `csrc_count` to make CodecID 8-bit, or split into `MediaType:2 / CodecID:6`. Doing this post-deployment is painful.
+
+### W10. No `MediaType` field
+Audio vs. video vs. data is implicit in CodecID. A 2-bit `MediaType` lets the SFU apply per-type policy (drop video first under congestion, prioritize audio fan-out) without a codec lookup.
+
+### W11. Anti-replay window 64 packets is tight for video
+One keyframe burst can be 100+ packets; a single reordered earlier packet stalls the window. Bump to 256 or 1024 for video streams, or maintain a per-stream window.
+
+### W12. `SignalMessage` has no version byte
+Bincode + `#[serde(default, skip_serializing_if)]` covers field additions but not variant removal or semantic change. Lead every variant with `version: u8`.
+
+### W13. RoomManager Mutex per-packet — **RESOLVED**
+Already flagged in `ARCHITECTURE.md`. At ~1500 pps/sender for video this becomes a real ceiling.
+
+**Resolution (T3.1):** `RoomManager` now stores `DashMap>>` instead of `DashMap`. The DashMap guard is held only long enough to clone the `Arc`; all per-room operations (fan-out `others()`, quality `observe_quality()`, join/leave) then acquire the room-level `std::sync::RwLock`. This lets concurrent `others()` calls share a read lock while writers hold the write lock, eliminating the per-packet DashMap contention that was the original concern.
+
+### W14. No receiver → sender congestion feedback beyond inline QualityReport
+For video you need REMB-style or transport-CC-style explicit BWE feedback at ~50 ms cadence, independent of media packets.
+
+## Priorities
+
+| Priority | Issue | Why |
+|---|---|---|
+| P0 | W9 (CodecID width), W10 (MediaType), W4 (MiniHeader seq_delta) | Wire-format changes — must land before video, painful to change post-deploy |
+| P0 | W1 (seq u16 → u32) | Same window; audio benefits too |
+| P1 | W6 (BWE), W14 (transport feedback) | Blocking for usable video; improves audio adaptation |
+| P1 | W5 (QualityReport in AEAD) | Security correctness |
+| P2 | W2 (fec_block_id width), W11 (anti-replay window), W12 (signal version byte) | Long-tail correctness |
+| P2 | W7 (NACK path), W13 (RoomManager lock) | Video performance, not correctness |
+| P3 | W3 (timestamp rebase doc), W8 (AEAD profiling) | Documentation / measurement |
+
+## Resolution status (2026-05-11)
+
+The v2 wire format specified in `ROAD-TO-VIDEO.md` Phase V1 addresses:
+
+| Issue | Resolved by |
+|---|---|
+| W1 (seq u16 → u32) | `sequence: u32` in MediaHeader v2 |
+| W4 (MiniHeader seq) | `seq_delta: u8` added; MiniHeader v2 is 5 B |
+| W9 (CodecID width) | Widened to 8-bit (room for 256) |
+| W10 (MediaType) | Explicit `media_type: u8` byte |
+
+W6 / W14 (BWE + TransportFeedback) addressed in Phase V2. W7 (NACK) addressed in Phase V2 / V4. Others remain open.
+
+## Known pre-existing clippy debt (as of T1.5.2)
+
+Measured at commit `c93d302` on `experimental-ui` (2026-05-11).
+
+`cargo clippy --workspace --all-targets -- -D warnings` fails in two crates with **pre-existing** errors (verified against `HEAD~1`). These are not introduced by any Wave 1 task; they should be cleaned up in a dedicated hygiene sprint or accepted as known debt.
+
+### `wzp-codec` — 9 errors
+
+| Category | Count | Lint | Files |
+|---|---|---|---|
+| Manual saturating sub | 1 | `clippy::implicit_saturating_sub` | `aec.rs:117` |
+| Needless range loop | 2 | `clippy::needless_range_loop` | `aec.rs:164`, `resample.rs:51` |
+| Manual `div_ceil` | 2 | `clippy::manual_div_ceil` | `codec2_dec.rs:48`, `codec2_enc.rs:48` |
+| Manual `clamp` | 2 | `clippy::manual_clamp` | `denoise.rs:59`, `opus_enc.rs:250` |
+| Manual ASCII case-cmp | 1 | `clippy::manual_ascii_check` | `opus_enc.rs:99` |
+| Same-item push in loop | 1 | `clippy::same_item_push` | `resample.rs:184` |
+
+### `warzone-protocol` (submodule `deps/featherchat`) — 3 errors
+
+| Category | Count | Lint | Files |
+|---|---|---|---|
+| `clone` on `Copy` type | 1 | `clippy::clone_on_copy` | `ratchet.rs:202` |
+| Missing `Default` impl | 2 | `clippy::new_without_default` | `types.rs:59`, `types.rs:69` |
+
+**Policy:** New tasks must not add *new* clippy errors in crates they touch. The 12 errors above are grandfathered; a follow-up cleanup task should be scheduled to fix them (especially the `wzp-codec` ones, which are straightforward mechanical replacements).
diff --git a/vault/Architecture/Refactor-Codebase-Audit.md b/vault/Architecture/Refactor-Codebase-Audit.md
new file mode 100644
index 0000000..9eaf2df
--- /dev/null
+++ b/vault/Architecture/Refactor-Codebase-Audit.md
@@ -0,0 +1,276 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# Codebase Refactoring Audit (2026-04-13)
+
+> Full analysis of the WarzonePhone codebase after the DashMap relay refactor, DRED continuous tuning, and adaptive quality wiring. The codebase is ~15K lines of Rust across 8 crates plus a 1.7K-line Tauri engine. This document identifies every refactoring opportunity ranked by impact.
+
+## Critical: engine.rs is 1,705 Lines With ~35% Duplication
+
+`desktop/src-tauri/src/engine.rs` has two nearly-identical `CallEngine::start()` implementations:
+- **Android path:** 880 lines (lines 321–1200)
+- **Desktop path:** 430 lines (lines 1203–1633)
+
+### What's Duplicated (350+ lines)
+
+| Block | Android Lines | Desktop Lines | Size | Identical? |
+|-------|--------------|---------------|------|-----------|
+| CallConfig initialization | 529–539 | 1353–1363 | 23 lines | Yes |
+| DRED tuner + frame_samples setup | 541–555 | 1360–1375 | 15 lines | Yes |
+| Adaptive quality profile switch | 651–665 | 1414–1428 | 15 lines | Yes |
+| Codec-to-QualityProfile match | 852–864 | 1488–1500 | 19 lines | Yes |
+| DRED ingest + gap fill | 886–902 | 1511–1528 | 17 lines | Yes |
+| Quality report ingestion | 905–912 | 1531–1538 | 8 lines | Yes |
+| Signal task (entire thing) | 1133–1180 | 1569–1616 | 48 lines | Yes |
+
+### Suggested Fix: Extract Shared Helpers
+
+```rust
+// Top of engine.rs — shared between both platforms
+
+fn build_call_config(quality: &str) -> CallConfig { ... }
+
+fn codec_to_profile(codec: CodecId) -> QualityProfile { ... }
+
+fn check_adaptive_switch(
+ pending: &AtomicU8,
+ encoder: &mut CallEncoder,
+ tuner: &mut DredTuner,
+ frame_samples: &mut usize,
+ tx_codec: &Mutex,
+) { ... }
+
+async fn run_signal_task(
+ transport: Arc,
+ running: Arc,
+ pending_profile: Arc,
+ participants: Arc>>,
+) { ... }
+```
+
+This would reduce engine.rs by ~200 lines and make the Android/desktop paths only differ in their audio I/O (Oboe vs CPAL).
+
+**Effort:** 2-3 hours. **Impact:** High — every future change to the send/recv pipeline currently requires editing two places.
+
+---
+
+## High: SignalMessage Enum Has 36 Variants
+
+`crates/wzp-proto/src/packet.rs` (1,727 lines) has a `SignalMessage` enum with 36 variants mixing orthogonal concerns:
+
+- Legacy call signaling (CallOffer, CallAnswer, IceCandidate, Rekey...)
+- Direct calling (RegisterPresence, DirectCallOffer, DirectCallAnswer, CallSetup...)
+- Federation (FederationHello, GlobalRoomActive/Inactive, FederatedSignalForward)
+- Relay control (SessionForward, PresenceUpdate, RouteQuery, RoomUpdate)
+- NAT traversal (Reflect, ReflectResponse, MediaPathReport)
+- Quality (QualityUpdate, QualityDirective)
+- Call control (Ping/Pong, Hold/Unhold, Mute/Unmute, Transfer)
+
+Every new feature adds variants here, and every match on `SignalMessage` must handle all 36 arms (or use `_` wildcard).
+
+### Suggested Fix: Sub-Enum Grouping
+
+```rust
+enum SignalMessage {
+ Call(CallSignal), // CallOffer, CallAnswer, IceCandidate, Rekey, Hangup...
+ Direct(DirectCallSignal), // RegisterPresence, DirectCallOffer, CallSetup, MediaPathReport...
+ Federation(FedSignal), // FederationHello, GlobalRoomActive, FederatedSignalForward...
+ Control(ControlSignal), // Ping/Pong, Hold/Unhold, Mute/Unmute, QualityDirective...
+ Relay(RelaySignal), // SessionForward, PresenceUpdate, RouteQuery, RoomUpdate...
+}
+```
+
+**Caution:** This is a wire-format change. Serde serialization must remain backward-compatible with already-deployed relays. Use `#[serde(untagged)]` or versioned deserialization. Consider doing this as a v2 protocol bump.
+
+**Effort:** 1 day. **Impact:** High for maintainability, but risky for wire compatibility.
+
+---
+
+## High: Federation Has Zero Tests
+
+`crates/wzp-relay/src/federation.rs` (1,132 lines) has **no unit tests and no integration tests**. This is the most complex file in the relay crate, handling:
+
+- Peer link management (connect, reconnect, stale sweep)
+- Federation media egress (forward_to_peers)
+- Federation media ingress (handle_datagram: dedup, rate limit, local delivery, multi-hop)
+- Cross-relay signal forwarding
+- Room event subscription and GlobalRoomActive/Inactive broadcasting
+
+The relay crate has 91 tests, but none cover federation. Any refactoring of federation (like the DashMap migration or clone-before-send) is flying blind.
+
+### Suggested Fix
+
+Priority test cases:
+1. `forward_to_peers` with 0, 1, 3 peers — verify datagram construction and label tracking
+2. `handle_datagram` — dedup (same packet twice → second dropped), rate limit (exceed → dropped)
+3. Stale presence sweeper — verify cleanup after timeout
+4. `broadcast_signal` — verify signal reaches all peers
+5. Multi-hop forward — verify source peer excluded from re-forward
+
+**Effort:** 1 day. **Impact:** Critical for safe refactoring.
+
+---
+
+## Medium: Federation `peer_links` Lock-During-Send
+
+`broadcast_signal()` (line 216) holds `peer_links` Mutex **across async `send_signal()` calls**. A slow peer blocks all signal delivery. `forward_to_peers()` (line 406) holds it during sync sends (less severe but still serializes).
+
+### Fix (30 minutes)
+
+```rust
+// Before:
+let links = self.peer_links.lock().await;
+for (fp, link) in links.iter() {
+ link.transport.send_signal(msg).await; // lock held across await!
+}
+
+// After:
+let peers: Vec<_> = {
+ let links = self.peer_links.lock().await;
+ links.values().map(|l| (l.label.clone(), l.transport.clone())).collect()
+};
+for (label, transport) in &peers {
+ transport.send_signal(msg).await; // no lock held
+}
+```
+
+Apply to `forward_to_peers()`, `broadcast_signal()`, and `send_signal_to_peer()`.
+
+**Effort:** 30 minutes. **Impact:** Medium — eliminates last lock-during-I/O pattern.
+
+---
+
+## Medium: Magic Numbers Scattered Through engine.rs
+
+```rust
+// These appear as literals in multiple places:
+tokio::time::sleep(Duration::from_millis(5)) // 6 occurrences
+tokio::time::sleep(Duration::from_millis(100)) // 2 occurrences
+Duration::from_millis(200) // 2 occurrences (signal timeout)
+Duration::from_secs(10) // 1 occurrence (QUIC connect timeout)
+Duration::from_secs(2) // 2 occurrences (heartbeat interval)
+const DRED_POLL_INTERVAL: u32 = 25; // defined twice (Android + desktop)
+vec![0i16; 1920] // 2 occurrences (should use FRAME_SAMPLES_40MS)
+```
+
+### Fix
+
+```rust
+// Top of engine.rs
+const CAPTURE_POLL_MS: u64 = 5;
+const RECV_TIMEOUT_MS: u64 = 100;
+const SIGNAL_TIMEOUT_MS: u64 = 200;
+const CONNECT_TIMEOUT_SECS: u64 = 10;
+const HEARTBEAT_INTERVAL_SECS: u64 = 2;
+const DRED_POLL_INTERVAL: u32 = 25;
+// Already exists: const FRAME_SAMPLES_40MS: usize = 1920;
+```
+
+**Effort:** 15 minutes. **Impact:** Low but prevents bugs from inconsistent values.
+
+---
+
+## Medium: CLI Arg Parsing in Relay main.rs
+
+`parse_args()` in main.rs is 154 lines of manual `while i < args.len()` parsing with `match args[i].as_str()`. Every new flag adds 5-10 lines of boilerplate.
+
+### Suggested Fix
+
+Replace with `clap` derive macro:
+
+```rust
+#[derive(clap::Parser)]
+struct RelayArgs {
+ #[arg(long, default_value = "0.0.0.0:4433")]
+ listen: SocketAddr,
+ #[arg(long)]
+ remote: Option,
+ #[arg(long)]
+ auth_url: Option,
+ // ...
+}
+```
+
+**Effort:** 1 hour. **Impact:** Medium — cleaner, auto-generates `--help`, validates types at parse time.
+
+---
+
+## Medium: Error Handling Inconsistency
+
+13 instances of `.ok()` silently swallowing errors on `transport.close()` across the relay. Federation signal forwarding has inconsistent error handling — some paths log, some don't.
+
+### Fix
+
+```rust
+// Helper at top of main.rs/federation.rs:
+async fn close_transport(t: &impl MediaTransport, context: &str) {
+ if let Err(e) = t.close().await {
+ tracing::debug!(context, error = %e, "transport close error (non-fatal)");
+ }
+}
+```
+
+**Effort:** 30 minutes. **Impact:** Better observability when debugging connection issues.
+
+---
+
+## Low: Unused Crypto Fields
+
+`crates/wzp-crypto/src/handshake.rs` has `x25519_static_secret` and `x25519_static_public` fields marked `#[allow(dead_code)]`. These are derived from the identity seed but never used in any handshake flow.
+
+**Decision needed:** Are these intended for a future feature (static key federation auth)? If not, remove. If yes, document the intended use.
+
+**Effort:** 5 minutes to remove, or 10 minutes to document.
+
+---
+
+## Low: 20 Unsafe Functions Missing Safety Docs
+
+`crates/wzp-native/src/lib.rs` has 20 `unsafe` functions (extern "C" FFI bridge to Oboe) without `/// # Safety` documentation. Clippy flags all of them.
+
+**Effort:** 30 minutes. **Impact:** Clippy clean, better documentation for contributors.
+
+---
+
+## Low: quality.rs vs dred_tuner.rs Overlap
+
+Both files deal with network quality → codec decisions, but they're complementary:
+- `quality.rs`: discrete tier classification (Good/Degraded/Catastrophic) → codec profile
+- `dred_tuner.rs`: continuous DRED frame mapping from loss/RTT/jitter
+
+No consolidation needed, but add cross-references:
+
+```rust
+// In dred_tuner.rs:
+//! See also: `quality.rs` for discrete tier classification that drives
+//! codec switching. DredTuner operates within a tier, adjusting DRED
+//! parameters continuously.
+
+// In quality.rs:
+//! See also: `dred_tuner.rs` for continuous DRED tuning within a tier.
+```
+
+**Effort:** 5 minutes.
+
+---
+
+## Summary: Priority Matrix
+
+| # | Refactor | Effort | Impact | Risk |
+|---|----------|--------|--------|------|
+| 1 | Extract shared engine.rs helpers | 2-3h | High | Low |
+| 2 | Federation tests | 1 day | Critical | None |
+| 3 | Federation clone-before-send | 30 min | Medium | Low |
+| 4 | Extract magic numbers to constants | 15 min | Low | None |
+| 5 | Error handling helpers | 30 min | Medium | None |
+| 6 | CLI parser → clap | 1h | Medium | Low |
+| 7 | SignalMessage sub-enums | 1 day | High | High (wire compat) |
+| 8 | Safety docs on unsafe fns | 30 min | Low | None |
+| 9 | Remove/document dead crypto fields | 5 min | Low | None |
+| 10 | Cross-reference quality.rs ↔ dred_tuner.rs | 5 min | Low | None |
+
+**Recommended order:** 4 → 3 → 5 → 1 → 2 → 6 → 8 → 9 → 10 → 7
+
+Items 4, 3, 5 are quick wins (under 1 hour total). Item 1 is the biggest maintainability win. Item 2 is the most important for safety. Item 7 should wait for a protocol version bump.
diff --git a/vault/Architecture/Refactor-Relay-Concurrency.md b/vault/Architecture/Refactor-Relay-Concurrency.md
new file mode 100644
index 0000000..127d86d
--- /dev/null
+++ b/vault/Architecture/Refactor-Relay-Concurrency.md
@@ -0,0 +1,261 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# Relay Concurrency Refactor Guide
+
+> Post-DashMap analysis: what was done, what remains, and what to do next.
+
+## What Was Done (2026-04-13)
+
+Replaced the global `Arc>` with `DashMap` inside `RoomManager`. The relay's media forwarding hot path no longer serializes through a single lock.
+
+### Before
+
+```
+Participant A recv_media()
+ → room_mgr.lock().await ← ALL participants, ALL rooms compete here
+ → mgr.observe_quality(...) ← O(N) quality computation inside lock
+ → mgr.others(...) ← clone Vec
+ → drop(lock)
+ → fan-out sends
+```
+
+One `tokio::sync::Mutex` guarding all rooms, all participants, all quality state. A 100-room relay was effectively single-threaded for media forwarding.
+
+### After
+
+```
+Participant A recv_media()
+ → room_mgr.observe_quality(...) ← DashMap::get_mut(), per-room shard lock
+ → room_mgr.others(...) ← DashMap::get(), shared shard lock
+ → fan-out sends ← no lock held
+```
+
+64 internal shards. Rooms on different shards are fully parallel. Rooms on the same shard use RwLock semantics — reads (`others()`) are concurrent, writes (`observe_quality()`, `join()`, `leave()`) are exclusive per-shard only.
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| `crates/wzp-relay/Cargo.toml` | Added `dashmap = "6"` |
+| `crates/wzp-relay/src/room.rs` | `HashMap` → `DashMap`, per-room quality/tier, all methods `&self` |
+| `crates/wzp-relay/src/main.rs` | `Arc>` → `Arc`, 3 lock sites removed |
+| `crates/wzp-relay/src/federation.rs` | 11 lock sites removed, `room_mgr` field type changed |
+| `crates/wzp-relay/src/ws.rs` | 3 lock sites removed, `room_mgr` field type changed |
+
+### Measured Improvement
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Lock type (rooms) | 1 global `tokio::sync::Mutex` | 64-shard `DashMap` with per-shard RwLock |
+| Cross-room blocking | Yes (all rooms share 1 lock) | No (rooms are independent) |
+| Read concurrency within room | None (Mutex is exclusive) | Yes (`get()` is shared) |
+| `.lock().await` sites | 20 across 4 files | 0 for room operations |
+| Test count | 314 passing | 314 passing (0 regressions) |
+
+---
+
+## Current Lock Inventory
+
+### Tier 0: Eliminated (Room Hot Path)
+
+These are gone — DashMap handles them internally:
+
+- ~~`room_mgr.lock().await` in media forwarding~~ → `room_mgr.others()` (DashMap shard)
+- ~~`room_mgr.lock().await` in quality tracking~~ → `room_mgr.observe_quality()` (DashMap shard)
+- ~~`room_mgr.lock().await` in join/leave~~ → `room_mgr.join()` / `.leave()` (DashMap entry)
+
+### Tier 1: Federation `peer_links` (Medium Priority)
+
+**Location:** `crates/wzp-relay/src/federation.rs:142`
+```rust
+peer_links: Arc>>
+```
+
+**22 lock sites** across federation.rs. The most important:
+
+| Method | Line | Hold Duration | I/O While Locked | Frequency |
+|--------|------|---------------|-------------------|-----------|
+| `forward_to_peers()` | 406 | 1-5ms (iterate + sync send) | Sync only | Per-packet batch |
+| `broadcast_signal()` | 216 | N × send_signal latency | **YES (async)** | Per-signal |
+| `handle_datagram()` multi-hop | 1123 | 1-2ms (iterate + sync send) | Sync only | Per-federation-packet |
+| `send_signal_to_peer()` | 246 | send_signal latency | **YES (async)** | Per-signal |
+| Stale sweeper | 523 | 1-5ms | No | Every 5s |
+
+**Impact:** Only matters with 5+ federation peers or high federation datagram rates (>1000 pps). For 1-3 peers, contention is negligible.
+
+### Tier 2: Control Plane (Low Priority)
+
+These are on the connection setup / signal path, not the media hot path:
+
+| Lock | Location | Frequency |
+|------|----------|-----------|
+| `session_mgr` | main.rs:450 | Per-connection setup |
+| `signal_hub` | main.rs:453 | Per-signal lookup |
+| `call_registry` | main.rs:454 | Per-call setup |
+| `presence` | main.rs:283 | Per-presence change |
+| `ACL` | room.rs:357 | Per-room join |
+
+**Impact:** None. These handle rare events (connection setup, call signaling) and hold locks for <5ms with no I/O inside.
+
+### Tier 3: Forward Mode Pipeline (Niche)
+
+| Lock | Location | Notes |
+|------|----------|-------|
+| `RelayPipeline` | main.rs:198, 228 | Only used in `--remote` forward mode (relay-to-relay), not SFU room mode |
+
+**Impact:** None for normal operation. Forward mode is a niche deployment.
+
+---
+
+## Suggested Next Refactors (Priority Order)
+
+### 1. Federation `peer_links` Clone-Before-Send
+
+**Effort:** 30 minutes
+**Impact:** Eliminates the lock-held-during-iteration pattern in `forward_to_peers()` and `broadcast_signal()`
+
+**Current:**
+```rust
+pub async fn forward_to_peers(&self, ...) {
+ let links = self.peer_links.lock().await; // held for entire loop
+ for (_fp, link) in links.iter() {
+ link.transport.send_raw_datagram(&tagged); // sync, but lock still held
+ }
+}
+```
+
+**Fix:**
+```rust
+pub async fn forward_to_peers(&self, ...) {
+ let peers: Vec<(String, Arc)> = {
+ let links = self.peer_links.lock().await;
+ links.values().map(|l| (l.label.clone(), l.transport.clone())).collect()
+ }; // lock released — hold time: ~1μs for Arc clones
+
+ for (label, transport) in &peers {
+ transport.send_raw_datagram(&tagged); // no lock held
+ }
+}
+```
+
+Same treatment for `broadcast_signal()` (line 216) which currently holds the lock across **async** `send_signal()` calls — this is the worst offender since a slow peer blocks all signal delivery.
+
+### 2. Federation `peer_links` → DashMap
+
+**Effort:** 2 hours
+**Impact:** Per-peer sharding, eliminates all cross-peer contention
+
+Only worth doing if:
+- Running 10+ federation peers
+- `forward_to_peers()` shows up in profiling
+- The clone-before-send fix from suggestion 1 is insufficient
+
+```rust
+peer_links: DashMap
+```
+
+Most lock sites become `self.peer_links.get(&fp)` or `.get_mut(&fp)`. The multi-hop forward loop would use `.iter()` which takes temporary shared locks per shard.
+
+### 3. Quality Tracking Out of Hot Path
+
+**Effort:** 1 day
+**Impact:** Reduces per-packet DashMap shard lock from exclusive (`get_mut`) to shared (`get`)
+
+Currently, every packet with a `QualityReport` calls `observe_quality()` which uses `rooms.get_mut()` (exclusive shard lock). This serializes quality-carrying packets within the same DashMap shard.
+
+**Fix:** Use per-participant `AtomicU8` for latest loss/RTT (written lock-free from hot path). A background task (every 1s) reads the atomics, computes tiers via `rooms.get_mut()`, and broadcasts `QualityDirective`. The per-packet hot path becomes purely read-only: `rooms.get()` → `others()`.
+
+```rust
+struct ParticipantQualityAtomic {
+ latest_loss: AtomicU8, // written per-packet (lock-free)
+ latest_rtt: AtomicU8, // written per-packet (lock-free)
+}
+
+// Hot path (per-packet):
+if let Some(ref qr) = pkt.quality_report {
+ participant_quality.latest_loss.store(qr.loss_pct, Ordering::Relaxed);
+ participant_quality.latest_rtt.store(qr.rtt_4ms, Ordering::Relaxed);
+}
+let others = room_mgr.others(&room_name, participant_id); // DashMap::get() — shared lock
+
+// Background task (every 1 second):
+for room in room_mgr.rooms.iter_mut() { // DashMap::iter_mut() — exclusive per-shard
+ room.recompute_tiers_from_atomics();
+ if tier_changed { broadcast QualityDirective }
+}
+```
+
+### 4. Lock-Free Participant Snapshot (Future)
+
+**Effort:** 0.5 day
+**Impact:** Zero-lock media hot path
+
+Replace `Vec` in `Room` with an `arc-swap` snapshot:
+
+```rust
+struct Room {
+ participants: Vec,
+ sender_snapshot: arc_swap::ArcSwap>,
+}
+```
+
+The snapshot is rebuilt on join/leave (rare). The hot path does `sender_snapshot.load()` — an atomic pointer read with zero locking. DashMap wouldn't even be involved in the per-packet path.
+
+Only worth doing if DashMap shard contention becomes measurable in profiling (unlikely for rooms <100 people).
+
+---
+
+## Decision Matrix
+
+| Scenario | Current (DashMap) | + Clone-Before-Send | + Quality Atomics | + arc-swap |
+|----------|-------------------|---------------------|-------------------|-----------|
+| 10 rooms × 5 people | Saturates all cores | Same | Same | Same |
+| 1 room × 100 people | Good (shared read) | Same | Better (no exclusive) | Best |
+| 5 federation peers | 1-5ms contention | <1μs contention | Same | Same |
+| 20 federation peers | 10-20ms contention | <1μs contention | Same | Same |
+| 1000 rooms × 3 people | Excellent | Same | Same | Same |
+
+**Recommendation:** Do suggestion 1 (clone-before-send, 30 min) now. Everything else is future optimization that current workloads don't need.
+
+---
+
+## Concurrency Diagram (Current State)
+
+```
+ ┌─────────────────────────────────┐
+ │ tokio multi-threaded │
+ │ work-stealing runtime │
+ └───────────────┬─────────────────┘
+ │
+ ┌────────────────────────────┼────────────────────────────┐
+ │ │ │
+ ┌──────▼──────┐ ┌───────▼───────┐ ┌───────▼───────┐
+ │ QUIC Accept │ │ Federation │ │ Signal Hub │
+ │ (per-conn │ │ (per-peer │ │ (per-client │
+ │ task) │ │ task) │ │ task) │
+ └──────┬──────┘ └───────┬───────┘ └───────┬───────┘
+ │ │ │
+ ┌──────▼──────┐ ┌───────▼───────┐ ┌───────▼───────┐
+ │ Per-Room │ │ peer_links │ │ signal_hub │
+ │ DashMap │◄──64 shards│ Mutex │◄──1 lock │ Mutex │
+ │ (media hot │ │ (federation │ │ (signal │
+ │ path) │ │ hot path) │ │ plane) │
+ └─────────────┘ └───────────────┘ └───────────────┘
+ │ │
+ No cross-room Low frequency
+ blocking (<1 call/sec)
+```
+
+## Files Reference
+
+| File | Lines | Role |
+|------|-------|------|
+| `crates/wzp-relay/src/room.rs` | ~1275 | DashMap room storage, participant management, quality tracking, media forwarding loops |
+| `crates/wzp-relay/src/federation.rs` | ~1152 | Peer link management, federation media egress/ingress, signal forwarding |
+| `crates/wzp-relay/src/main.rs` | ~1746 | Connection accept, handshake dispatch, signal handling, room/federation wiring |
+| `crates/wzp-relay/src/ws.rs` | ~250 | WebSocket bridge, room integration |
+| `crates/wzp-relay/src/metrics.rs` | ~200 | Prometheus counters (lock-free atomics) |
+| `crates/wzp-relay/src/trunk.rs` | ~150 | TrunkBatcher (per-instance, no shared state) |
diff --git a/vault/Architecture/Road-To-Video.md b/vault/Architecture/Road-To-Video.md
new file mode 100644
index 0000000..a5c13b8
--- /dev/null
+++ b/vault/Architecture/Road-To-Video.md
@@ -0,0 +1,290 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# Road to Video
+
+> Plan for adding video to WZP. Audio remains unchanged through Phase V1; video is additive. See `PROTOCOL-AUDIT.md` for the issues this plan addresses.
+
+## Premise
+
+The transport, crypto, session, federation, and SFU layers are codec-agnostic. The work is concentrated in:
+
+1. Wire format (CodecID width, MediaType, MiniHeader seq, simulcast hooks)
+2. Framer / depacketizer (NAL fragmentation, access-unit reassembly)
+3. Bandwidth estimator (Quinn cwnd + transport feedback)
+4. Keyframe semantics (PLI, NACK, keyframe cache at SFU)
+5. Capture / encode pipeline (VideoToolbox / MediaCodec / NVENC)
+
+## Implementation Status (as of 2026-05-25)
+
+| Phase | Description | Status |
+|---|---|---|
+| V1 — Wire format | 16B MediaHeader v2, 5B MiniHeader v2, MediaType, u32 seq, 8-bit CodecID | ✅ Complete (T1.x) |
+| V2 — Transport additions | BWE, NACK loop, TransportFeedback, dynamic FEC boost on I-frames | 🔲 Not started |
+| V3 — `wzp-video` crate | H.264 baseline framer/depacketizer, VideoToolbox/MediaCodec/dav1d encoders | ✅ Substantially complete (T4.x, T5.x, T6.x) |
+| V3 — H.264 Baseline | Single-layer H.264 | ✅ Complete |
+| V3 — H.265 | VideoToolbox + MediaCodec H.265 | ✅ Complete (T5.x) |
+| V3 — AV1 | dav1d + SVT-AV1 (non-Android), VideoToolbox AV1 (macOS M3+) | ✅ Complete; Android MediaCodec AV1 compile errors pending (T4.3.1.1) |
+| V3 — Android MediaCodec | NDK 0.9 API migration for `mediacodec.rs` | 🔴 Blocked (31 compile errors) |
+| V3 — Call engine wiring | `create_video_encoder()` integrated into active call negotiation | 🔴 Not started (T6.1.2 follow-up) |
+| V4 — Keyframe & loss policy | NACK path, PLI, keyframe cache at SFU | 🟡 Framework present (`nack.rs`); not wired |
+| V5 — Video adaptive controller | `VideoQualityController` + `PriorityMode` | 🟡 Controller built (`controller.rs`); not wired into call |
+| V5 — Simulcast | Simulcast layer management | 🟡 `simulcast.rs` present; not wired |
+| V6 — SFU changes | Keyframe cache, per-receiver layer selection, PLI suppression | 🟡 PLI suppression wired; keyframe cache + layer selection not started |
+| V6 — Video scorer | `VideoScorer` legitimacy detection | 🟡 Built (`video_scorer.rs`); `observe()` not wired into room forwarding |
+| V7 — Capture pipeline | Camera capture (AVCaptureSession, Camera2, NVENC) | 🔲 Not started |
+
+**Legend:** ✅ Complete · 🟡 Partial/Framework only · 🔴 Blocked · 🔲 Not started
+
+### Critical path to first video call
+
+1. Fix Android MediaCodec compile errors (T4.3.1.1) — ~2h
+2. Wire `create_video_encoder()` into call engine codec negotiation (T6.1.2) — ~2h
+3. Fix crypto nonce bug (`decrypt()` must use `MediaHeader.seq`) — see `AUDIT-2026-05-25.md` C1 — ~1h
+4. Wire `VideoScorer::observe()` into relay room forwarding (T6.2 follow-up) — ~2h
+5. Implement Phase V2 BWE (mandatory for usable video) — ~3–4 days
+6. Implement capture pipeline for at least one platform (V7) — ~1 week
+
+## Phase V1 — Wire format & negotiation (no new code paths yet)
+
+Bump protocol version. Land all wire changes together so compat breaks exactly once.
+
+### Sizing decision (2026-05-11)
+
+Hypothetical benchmarks on 12 B packed vs 16 B byte-aligned showed the overhead delta is invisible across every realistic scenario:
+
+| Scenario | Δ overhead (12 B → 16 B) | Δ % of stream |
+|---|---|---|
+| Opus 24k audio (MiniHeader 49/50) | 4 B/s | 0.013 % |
+| Codec2 1200 audio | 2 B/s | 0.13 % |
+| H.264 SD 500 kbps video | 1.6 kbps | 0.32 % |
+| H.264 HD 2.5 Mbps video | 7.1 kbps | 0.28 % |
+| H.264 FHD 5 Mbps video | 14.1 kbps | 0.28 % |
+
+Trunking cap (10) binds before MTU for audio, so TrunkFrame layout is unaffected. ChaCha20-Poly1305 cost is dominated by AEAD setup, not byte count — 4 extra bytes per packet is < 0.1 % of AEAD CPU on Cortex-A55.
+
+**Decision: 16 B byte-aligned.** Bit-packing saves nothing material and costs recurring debug / fuzzer / evolution complexity. Reserves headroom for the next decade.
+
+### `MediaHeader` v2 (16 B byte-aligned)
+
+```
+Byte 0: version (u8) currently 0x02
+Byte 1: flags (u8) [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
+ T = FEC repair
+ Q = QualityReport trailer present
+ KeyFrame = packet belongs to an I-frame (video)
+ FrameEnd = last packet of an access unit (video)
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8) widened from 4-bit (room for 256)
+Byte 4: stream_id (u8) simulcast layer; 0=base
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE)
+Bytes 10-13: timestamp_ms (u32 BE)
+Bytes 14-15: fec_block_id (u16 BE)
+ audio: low 8 bits block_id, high 8 bits symbol_idx
+ video: full u16 block_id (large blocks for I-frames)
+```
+
+- `version=2` is a hard switch — old clients receive a typed `Hangup::ProtocolVersionMismatch`.
+- `media_type` (W10) lets the SFU drop video first under load without a codec lookup.
+- `KeyFrame` lets a joining peer fast-forward to the next I-frame; SFU keyframe cache keys on it.
+- `FrameEnd` lets the depacketizer fire an access unit without counting packets.
+- `stream_id` is forward-compatible for simulcast (Phase V5).
+- `sequence` widened to u32 (W1) — also benefits audio.
+
+### `MiniHeader` v2 (5 B)
+
+```
+[FRAME_TYPE_MINI = 0x01]
+Byte 0: seq_delta (u8) ← new (W4)
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
+```
+
+Audio-only in V1. Video pays the full 16 B header per packet (every frame is a new access unit; no clean periodic structure to compress).
+
+### New codec IDs
+
+| ID | Codec | Notes |
+|---|---|---|
+| 9 | H.264 baseline | Universal HW encode coverage; ship first |
+| 10 | H.264 main | Slight quality win over baseline; same HW |
+| 11 | H.265 main | Apple A10+ universal, Snapdragon since ~2017, NVENC GTX 9xx+; ~30 % win vs H.264 |
+| 12 | AV1 | Apple M3/A17+, Snapdragon 8 Gen 3+, RTX 40+, Arc, RX 7000+; best efficiency, narrow HW |
+| 13 | VP9 | Reserved; may not implement |
+
+Negotiation: `CallOffer.supported_codecs: Vec`. Both sides pick the highest mutually supported codec from preference cascade `[AV1, H.265, H.264 main, H.264 baseline]`.
+
+### `QualityProfile` extension
+
+Add:
+- `video_bitrate_kbps: Option`
+- `video_resolution: Option<(u16, u16)>`
+- `video_fps: Option`
+- `priority_mode: PriorityMode` (see Phase V5)
+
+`CallOffer` / `CallAnswer` already negotiate profiles — slot video into the same path.
+
+### Acceptance
+- All 571 audio tests pass with `V=2` headers.
+- Old v1 clients refused gracefully (clear error in `CallAnswer`).
+
+## Phase V2 — Transport additions
+
+**Decision (2026-05-11): all media on QUIC datagrams; no separate "reliable media" stream.**
+
+A QUIC stream for I-frames was considered and rejected. A 200 KB I-frame on a 1 Mbps mobile link takes ~1.6 s to transit a stream, and the next I-frame queues behind it (HoL blocking by design). Datagrams + NACK + dynamic per-keyframe FEC degrade more gracefully on the lossy links we care about.
+
+1. **All media on datagrams.** Uniform wire format; no HoL.
+2. **NACK loop for video P-frames.** When `RTT < 2 × frame_interval`, receiver NACKs missing P-frame packets via `SignalMessage::Nack { stream_id, seqs }`. Otherwise (high RTT) skip NACK and request a keyframe via `PictureLossIndication`.
+3. **Dynamic FEC boost on I-frames.** Encoder bumps `fec_ratio` to ~0.5 for keyframe packets (k=20 source → r=10 repair). Recovers most I-frame loss without a round trip.
+4. **SPS/PPS / parameter sets on the existing signal stream.** Reliable, ordered, one-time at session start. Re-sent on codec switch. No new stream needed.
+5. **`SignalMessage::TransportFeedback`** — `{ acked_seqs: Vec, nacked_seqs: Vec, remb_bps: u32, recv_time_us: u64 }`. Sent every 50 ms or every N packets, whichever first. Feeds BWE.
+6. **`BandwidthEstimator` in `wzp-proto`** — consumes Quinn `cwnd`, `bytes_in_flight`, plus `TransportFeedback`. Output: `target_send_bps = min(cwnd_bps * 0.9, remb_bps)`.
+
+### Acceptance
+- Audio adapts to bandwidth (not just loss/RTT); fewer oscillations between 24 k and 32 k Opus on stable links.
+- BWE output is on Prometheus.
+- NACK round-trip recovery verified under 1–5 % packet loss at RTT ≤ 100 ms.
+
+## Phase V3 — `wzp-video` crate
+
+New crate parallel to `wzp-codec`:
+
+```
+wzp-video/
+ src/
+ encoder.rs # trait VideoEncoder; VideoToolboxEncoder, MediaCodecEncoder,
+ # OpenH264Encoder fallback
+ decoder.rs # trait VideoDecoder
+ framer.rs # NAL unit fragmentation to MTU-sized chunks
+ # (simpler than RFC 6184 FU-A — we own both ends)
+ depacketizer.rs # Reassemble NALs, emit access units
+ keyframe.rs # Keyframe request handling
+```
+
+Framing rules:
+- One access unit → N packets, each ≤ MTU − 12 (MediaHeader) − 16 (AEAD tag).
+- `sequence` global per stream; `timestamp_ms` is presentation time.
+- `KeyFrame` bit set on every packet of an I-frame.
+- Last packet of frame: "frame end" bit (steal from `StreamId` or repurpose `reserved`).
+
+Platform encoders:
+- macOS / iOS: VideoToolbox
+- Android: MediaCodec (surface texture path, no CPU copy)
+- Windows: MediaFoundation → NVENC / QSV / AMF
+- Linux: VAAPI / NVENC; OpenH264 software fallback
+
+### Acceptance
+- Unidirectional H.264 call working between two desktop clients.
+- CPU usage on M1 < 5 % at 720p30; on Android mid-tier < 15 %.
+
+## Phase V4 — Keyframe & loss policy
+
+- On packet loss inside a P-frame: NACK if RTT < 2× frame interval, otherwise request keyframe via `SignalMessage::PictureLossIndication { stream_id }`.
+- Joining peer: relay sends most recent keyframe from its cache.
+- Tier downgrade: drop to lower simulcast layer, request keyframe for the new layer.
+
+### Acceptance
+- Black-screen-on-join < 200 ms when keyframe cache is warm.
+- < 1 keyframe / 2 s on stable links; bursty on lossy links.
+
+## Phase V5 — Video adaptive controller + PriorityMode
+
+### `PriorityMode` on `QualityProfile`
+
+```rust
+pub enum PriorityMode {
+ AudioFirst, // default for calls: audio absolute priority, video elastic
+ VideoFirst, // user override: video priority, audio degrades second
+ ScreenShare, // video + slide-fallback; audio = intelligible speech only
+ Balanced, // proportional split, no absolute priority
+}
+```
+
+Selected at call setup. Mutable mid-call via `SignalMessage::SetPriorityMode { mode }`. Defaults to `AudioFirst` for voice/video calls; presentation apps set `ScreenShare`; users can override to `VideoFirst` from settings.
+
+### `VideoQualityController`
+
+```
+inputs: bwe_bps, loss_pct, rtt_ms, encoder_queue_ms, priority_mode
+outputs: target_bitrate, target_fps, target_resolution, simulcast_layer
+
+allocation gate (per PriorityMode):
+
+ AudioFirst:
+ audio_budget = max(24 kbps, audio_tier_min)
+ video_budget = bwe_bps - audio_budget
+ Under congestion: video → 0 before audio degrades.
+
+ VideoFirst:
+ video_budget = max(video_floor, target_video_kbps)
+ audio_budget = bwe_bps - video_budget
+ Audio degrades first to Opus 16 k; video held at floor.
+
+ ScreenShare:
+ video_budget = bwe_bps - 16 kbps // audio gets just Opus 16 k floor
+ If video_budget < SD floor: switch encoder to slide mode
+ (single high-quality I-frame every 2-5s instead of continuous video).
+ Audio floor in this mode is Opus 16 k (speech only, no music).
+
+ Balanced:
+ audio_budget = bwe_bps * 0.15
+ video_budget = bwe_bps * 0.85
+ Both degrade proportionally.
+```
+
+Slide mode in `ScreenShare` is an encoder policy on the existing `wzp-video` framer (lower fps, higher per-frame quality, prefer HEVC/AV1 for text). No wire format change.
+
+### Acceptance
+- On a 100 kbps link in `AudioFirst`, audio stays at Opus 24 k and video drops to 0.
+- On a 100 kbps link in `ScreenShare`, slide mode emits one I-frame every 3 s and audio holds Opus 16 k.
+- On a 5 Mbps link, video ramps to top simulcast layer within 10 s.
+- `SetPriorityMode` mid-call is honored within 1 s.
+
+## Phase V6 — SFU changes
+
+- **Per-room keyframe cache.** Latest I-frame per `(sender, stream_id)`. Sent to new joiners immediately. Eliminates "black screen for 2 seconds" on join.
+- **Per-receiver layer selection.** Sender uploads ~3 simulcast layers; relay decides which to forward to each receiver based on their last `QualityReport`. Critical for N > 3 rooms.
+- **PLI suppression.** If 10 receivers PLI within 200 ms, send one `KeyframeRequest` upstream, not 10.
+
+### Acceptance
+- 8-peer room with mixed link quality; high-quality peers see HD, low-quality peers see SD, no peer holds the room back.
+- PLI traffic at SFU upstream < 1 / s under simulated mass packet loss.
+
+## Phase V7 — Capture pipeline (platform-specific)
+
+- macOS: `AVCaptureSession` → VideoToolbox → `wzp-video`. Wire into Tauri backend.
+- Android: Camera2 → MediaCodec → JNI bridge into `wzp-native` or sibling cdylib. Surface texture path.
+- Desktop Tauri (Windows): MediaFoundation → NVENC.
+
+### Acceptance
+- Camera permission flows on all platforms.
+- < 50 ms end-to-end capture-to-encode latency on M1.
+
+## Deferred
+
+- **SVC** (per-layer temporal scalability in one bitstream). Simulcast (separate streams per layer) is enough for v1; wire format already supports it via `StreamId`.
+- **Screen sharing.** Same codec path with a different capture source.
+- **Group video keys.** Existing X25519 session key works; no protocol change needed.
+
+## Suggested order of work
+
+| Step | Effort | Output |
+|---|---|---|
+| 1. Wire format v2: 16 B MediaHeader, 5 B MiniHeader, MediaType, KeyFrame, FrameEnd, u32 seq, 8-bit CodecID | ~1 day | Audio still works under new header layout |
+| 2. TransportFeedback + BandwidthEstimator (Quinn cwnd + remb) | 3–4 days | Audio adaptation improves; BWE on Prom |
+| 3. `wzp-video` crate, H.264 baseline single-layer | 1–2 weeks | Unidirectional video call works |
+| 4. NACK path + dynamic FEC boost on I-frames | 4–5 days | Loss recovery for video |
+| 5. Keyframe cache at SFU + PLI suppression | 1 week | Fast join, low PLI traffic |
+| 6. H.265 codec support (reuse framer) | 3 days | ~30 % quality win on Apple HW |
+| 7. Simulcast + per-receiver layer selection | 1 week | Mixed-quality rooms work |
+| 8. `VideoQualityController` + PriorityMode (incl. ScreenShare slide mode) | 1 week | Graceful degradation under congestion, user choice |
+| 9. AV1 codec (gated on HW telemetry) | 4–5 days | Top-tier efficiency on capable devices |
+| 10. Native capture pipelines (VideoToolbox / MediaCodec / NVENC) | 2 weeks | Production camera support per OS |
+
+Step 1 is the lowest-regret, highest-leverage change and unlocks everything else.
+
+Steps 3 + 6 + 9 form the codec rollout: ship H.264 first (works everywhere → unblocks integration testing on every device), add H.265 once framer is stable (low-effort, big Apple win), gate AV1 on real device telemetry. By 2028 we should be in a position to deprecate H.264 if telemetry says < 5 % of sessions still need it.
diff --git a/vault/Architecture/WS-Relay-Spec.md b/vault/Architecture/WS-Relay-Spec.md
new file mode 100644
index 0000000..f3eb4d0
--- /dev/null
+++ b/vault/Architecture/WS-Relay-Spec.md
@@ -0,0 +1,262 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# WS Support in wzp-relay — Implementation Spec
+
+## Goal
+
+Add WebSocket listener to `wzp-relay` so browsers connect directly, eliminating `wzp-web` bridge.
+
+```
+Before: Browser → WS → wzp-web → QUIC → wzp-relay
+After: Browser → WS → wzp-relay (handles both WS + QUIC)
+```
+
+## Architecture
+
+```
+wzp-relay
+├── QUIC listener (:4433) — native clients, inter-relay
+├── WS listener (:8080) — browsers via Caddy
+│ ├── GET /ws/{room} — WebSocket upgrade
+│ └── Auth: first msg = {"type":"auth","token":"..."}
+└── Shared RoomManager — both transports in same rooms
+```
+
+## Key Changes
+
+### 1. Abstract `Participant` over transport type
+
+**File: `room.rs`**
+
+Currently:
+```rust
+struct Participant {
+ id: ParticipantId,
+ _addr: std::net::SocketAddr,
+ transport: Arc,
+}
+```
+
+Change to:
+```rust
+struct Participant {
+ id: ParticipantId,
+ _addr: std::net::SocketAddr,
+ sender: ParticipantSender,
+}
+
+/// How to send a media packet to a participant.
+enum ParticipantSender {
+ Quic(Arc),
+ WebSocket(tokio::sync::mpsc::Sender),
+}
+```
+
+The `others()` method returns `Vec` instead of `Vec>`.
+
+`ParticipantSender` implements a `send_pcm(&self, data: &[u8])` method:
+- **Quic**: wraps in `MediaPacket`, calls `transport.send_media()`
+- **WebSocket**: sends raw binary frame via the mpsc channel
+
+### 2. Add `join_ws()` to RoomManager
+
+```rust
+pub fn join_ws(
+ &mut self,
+ room_name: &str,
+ addr: std::net::SocketAddr,
+ sender: tokio::sync::mpsc::Sender,
+ fingerprint: Option<&str>,
+) -> Result
+```
+
+### 3. Add WS listener in `main.rs`
+
+New flag: `--ws-port 8080`
+
+```rust
+if let Some(ws_port) = config.ws_port {
+ let room_mgr = room_mgr.clone();
+ let auth_url = config.auth_url.clone();
+ let metrics = metrics.clone();
+ tokio::spawn(run_ws_server(ws_port, room_mgr, auth_url, metrics));
+}
+```
+
+### 4. WebSocket handler (`ws.rs` — new file)
+
+```rust
+use axum::{
+ extract::{ws::{Message, WebSocket}, Path, WebSocketUpgrade},
+ routing::get,
+ Router,
+};
+
+async fn ws_handler(
+ Path(room): Path,
+ ws: WebSocketUpgrade,
+ /* state */
+) -> impl IntoResponse {
+ ws.on_upgrade(move |socket| handle_ws(socket, room, state))
+}
+
+async fn handle_ws(mut socket: WebSocket, room: String, state: WsState) {
+ let addr = /* peer addr */;
+
+ // 1. Auth: first message must be {"type":"auth","token":"..."}
+ let fingerprint = if let Some(ref auth_url) = state.auth_url {
+ match socket.recv().await {
+ Some(Ok(Message::Text(text))) => {
+ let parsed: serde_json::Value = serde_json::from_str(&text)?;
+ if parsed["type"] == "auth" {
+ let token = parsed["token"].as_str().unwrap();
+ let client = auth::validate_token(auth_url, token).await?;
+ Some(client.fingerprint)
+ } else { return; }
+ }
+ _ => return,
+ }
+ } else { None };
+
+ // 2. Create mpsc channel for outbound frames
+ let (tx, mut rx) = tokio::sync::mpsc::channel::(64);
+
+ // 3. Join room
+ let participant_id = {
+ let mut mgr = state.room_mgr.lock().await;
+ mgr.join_ws(&room, addr, tx, fingerprint.as_deref())?
+ };
+
+ // 4. Run send/recv loops
+ let (mut ws_tx, mut ws_rx) = socket.split();
+
+ // Outbound: mpsc rx → WS send
+ let send_task = tokio::spawn(async move {
+ while let Some(data) = rx.recv().await {
+ if ws_tx.send(Message::Binary(data.to_vec())).await.is_err() {
+ break;
+ }
+ }
+ });
+
+ // Inbound: WS recv → fan-out to room
+ loop {
+ match ws_rx.next().await {
+ Some(Ok(Message::Binary(data))) => {
+ // Raw PCM Int16 from browser — fan-out to all others
+ let others = {
+ let mgr = state.room_mgr.lock().await;
+ mgr.others(&room, participant_id)
+ };
+ for other in &others {
+ other.send_raw(&data);
+ }
+ }
+ Some(Ok(Message::Close(_))) | None => break,
+ _ => continue,
+ }
+ }
+
+ // 5. Cleanup
+ send_task.abort();
+ let mut mgr = state.room_mgr.lock().await;
+ mgr.leave(&room, participant_id);
+}
+```
+
+### 5. Cross-transport fan-out
+
+When a QUIC participant sends audio → WS participants receive raw PCM bytes.
+When a WS participant sends audio → QUIC participants receive a `MediaPacket`.
+
+The `ParticipantSender::send_raw()` method:
+```rust
+impl ParticipantSender {
+ async fn send_raw(&self, pcm_bytes: &[u8]) {
+ match self {
+ ParticipantSender::WebSocket(tx) => {
+ let _ = tx.try_send(bytes::Bytes::copy_from_slice(pcm_bytes));
+ }
+ ParticipantSender::Quic(transport) => {
+ // Wrap raw PCM in a MediaPacket
+ let pkt = MediaPacket {
+ header: MediaHeader::default_pcm(),
+ payload: bytes::Bytes::copy_from_slice(pcm_bytes),
+ quality_report: None,
+ };
+ let _ = transport.send_media(&pkt).await;
+ }
+ }
+ }
+}
+```
+
+For QUIC→WS direction, `run_participant` extracts `pkt.payload` bytes and sends to WS channels.
+
+### 6. Dependencies to add
+
+```toml
+# wzp-relay/Cargo.toml
+axum = { version = "0.8", features = ["ws"] }
+tokio = { version = "1", features = ["full"] } # already present
+```
+
+### 7. Config change
+
+```rust
+// config.rs
+pub struct RelayConfig {
+ // ... existing fields ...
+ pub ws_port: Option,
+}
+```
+
+### 8. Docker compose change (featherChat side)
+
+Remove `wzp-web` service entirely. Update Caddy to proxy `/audio/*` to relay's WS port:
+
+```yaml
+# Before:
+wzp-web:
+ entrypoint: ["wzp-web"]
+ command: ["--port", "8080", "--relay", "172.28.0.10:4433"]
+
+# After: REMOVED. Relay handles WS directly.
+
+wzp-relay:
+ command:
+ - "--listen"
+ - "0.0.0.0:4433"
+ - "--ws-port"
+ - "8080"
+ - "--auth-url"
+ - "http://warzone-server:7700/v1/auth/validate"
+```
+
+## What Stays the Same
+
+- Browser's `startAudio()` — unchanged, still connects WS to `/audio/ws/ROOM`
+- Caddy proxies `/audio/*` → relay:8080 (same path, different backend)
+- Auth flow — same JSON token as first message
+- PCM format — same Int16 binary frames
+- QUIC clients — unchanged, still connect to :4433
+- Room naming, ACL, session management — all unchanged
+
+## Testing
+
+1. Start relay with `--ws-port 8080 --listen 0.0.0.0:4433`
+2. Open browser, initiate call via featherChat
+3. Verify audio flows (both directions)
+4. Verify QUIC + WS clients can be in same room (mixed mode)
+5. Verify auth works
+6. Verify room cleanup on disconnect
+
+## Migration Path
+
+1. Implement WS in relay
+2. Test with featherChat (no featherChat changes needed)
+3. Remove wzp-web from Docker stack
+4. Later: add WebTransport alongside WS
diff --git a/vault/Architecture/WZP-Spec.md b/vault/Architecture/WZP-Spec.md
new file mode 100644
index 0000000..1a21e2e
--- /dev/null
+++ b/vault/Architecture/WZP-Spec.md
@@ -0,0 +1,152 @@
+---
+tags: [architecture, wzp]
+type: architecture
+---
+
+# WZP Protocol Specification (one-page reference)
+
+> Distilled from `docs/ARCHITECTURE.md` and the `wzp-proto` crate. Authoritative wire details live in `crates/wzp-proto/src/packet.rs`.
+>
+> **Status:** v2 is the deployed protocol (audio + video, 16 B header, MediaType, u32 seq). v1 clients are rejected with `Hangup::ProtocolVersionMismatch`.
+
+## Layer summary
+
+| Layer | WZP | FaceTime equivalent |
+|---|---|---|
+| Transport | **QUIC datagrams** (Quinn), PLPMTUD 1200 → 1452 | RTP/SRTP over UDP, ICE |
+| Signaling | `SignalMessage` (bincode) over a QUIC stream, SNI = hashed room name | APNs-tunneled binary plist |
+| Identity | Ed25519 + X25519 from BIP39 seed; fingerprint = SHA-256(pubkey)[..16] | IDS RSA + ECDSA per device |
+| Key agreement | X25519 DH + HKDF, Ed25519 signatures, rekey every 65,536 packets | Per-call DH signed by IDS keys |
+| Bulk crypto | ChaCha20-Poly1305, 64-packet sliding anti-replay | SRTP (AES-CTR + HMAC) |
+| Loss recovery | **RaptorQ FEC + Opus DRED + classical PLC** | NACK / PLI + reference-picture selection |
+| Adaptive | 3-tier hysteresis (Good / Degraded / Catastrophic) + continuous DRED tuner | Per-frame bitrate ladder |
+| Topology | SFU rooms + inter-relay federation + P2P via ICE | Mesh ≤ ~3, SFU above, Apple relays |
+| Header | 16 B `MediaHeader` v2 / 5 B `MiniHeader` (49 of 50), 4 B `QualityReport` trailer | RTP 12 B + extensions |
+
+## Distinctive choices
+
+- **QUIC datagrams instead of raw UDP + SRTP.** Brings TLS 1.3, PLPMTUD, path migration, and ACK-based RTT/loss estimation for free.
+- **Continuous DRED tuning.** Maps live `(loss%, RTT, jitter)` to a continuous Opus DRED lookback window. Most stacks treat DRED as discrete tiers.
+- **MiniHeader (5 B for 49/50 packets).** Saves ~11 B/packet ≈ 550 B/s/stream at 50 pps vs. the full 16 B header.
+- **E2E-preserving SFU.** The relay forwards encrypted datagrams; it never decrypts media. Room membership uses SNI = `hash(room_name)`.
+- **Codec coordination via `QualityReport` trailer.** Receivers attach 4-byte loss/RTT/jitter/cap to media packets; the SFU broadcasts `QualityDirective` so all senders in a room converge on the same tier.
+
+## Wire format (current — v2)
+
+### `MediaHeader` v2 (16 bytes, byte-aligned)
+
+```
+Byte 0: version (u8) 0x02
+Byte 1: flags (u8) [T:1][Q:1][KeyFrame:1][FrameEnd:1][reserved:4]
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8) 0-255 (see codec table)
+Byte 4: stream_id (u8) simulcast layer; 0=base
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE)
+Bytes 10-13: timestamp_ms (u32 BE)
+Bytes 14-15: fec_block_id (u16 BE)
+```
+
+| Field | Bits | Meaning |
+|---|---|---|
+| version | 8 | Must be `0x02`; v1 clients receive `Hangup::ProtocolVersionMismatch` |
+| T (bit 7 of flags) | 1 | 1 = FEC repair packet |
+| Q (bit 6 of flags) | 1 | QualityReport trailer present |
+| KeyFrame (bit 5 of flags) | 1 | Packet belongs to a video I-frame |
+| FrameEnd (bit 4 of flags) | 1 | Last packet of an access unit |
+| reserved (bits 3-0 of flags) | 4 | Must be zero |
+| media_type | 8 | 0=audio, 1=video, 2=data, 3=control |
+| codec_id | 8 | See codec table (widened from v1's 4-bit field) |
+| stream_id | 8 | Simulcast layer; 0=base layer |
+| fec_ratio | 8 | 0..200 → 0.0..2.0 |
+| sequence | 32 | Monotonically increasing packet seq (not reset by rekey) |
+| timestamp_ms | 32 | ms since session start. Monotonic across the full session; **not reset by rekey** |
+| fec_block_id | 16 | FEC source block ID |
+
+### Codec table
+
+| ID | Codec | Bitrate | Sample | Frame |
+|---|---|---|---|---|
+| 0 | Opus 24k | 24 kbps | 48 kHz | 20 ms |
+| 1 | Opus 16k | 16 kbps | 48 kHz | 20 ms |
+| 2 | Opus 6k | 6 kbps | 48 kHz | 40 ms |
+| 3 | Codec2 3200 | 3.2 kbps | 8 kHz | 20 ms |
+| 4 | Codec2 1200 | 1.2 kbps | 8 kHz | 40 ms |
+| 5 | ComfortNoise | 0 | 48 kHz | 20 ms |
+| 6 | Opus 32k | 32 kbps | 48 kHz | 20 ms |
+| 7 | Opus 48k | 48 kbps | 48 kHz | 20 ms |
+| 8 | Opus 64k | 64 kbps | 48 kHz | 20 ms |
+| 9 | H.264 Baseline | — | — | — |
+| 10 | H.264 Main | — | — | — |
+| 11 | H.265 Main | — | — | — |
+| 12 | AV1 Main | — | — | — |
+
+### `MiniHeader` v2 (5 bytes, compressed — 49 of every 50 packets)
+
+```
+[FRAME_TYPE_MINI = 0x01]
+Byte 0: seq_delta (u8)
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
+```
+
+Full header sent every 50th packet to resync.
+
+### `TrunkFrame` (batched, relay-internal)
+
+```
+[count: u16]
+ [session_id: 2][len: u16][payload: len] × count
+```
+
+Up to 10 entries or PMTUD-discovered MTU; flushed every 5 ms.
+
+### `QualityReport` (4 bytes, optional inline trailer)
+
+```
+Byte 0: loss_pct (0-255 → 0-100%)
+Byte 1: rtt_4ms (0-255 → 0-1020 ms)
+Byte 2: jitter_ms (0-255 ms)
+Byte 3: bitrate_cap_kbps (0-255 kbps)
+```
+
+### Version negotiation
+
+- `version=0x02` in `MediaHeader` is a hard switch — there is no fallback negotiation.
+- Both endpoints must speak v2. A v1 peer receives `Hangup::ProtocolVersionMismatch` immediately.
+- Relays inspect only `version` and `media_type`; they never downgrade or translate between versions.
+
+## Session lifecycle
+
+```
+Idle → Connecting → Handshaking → Active ⇄ Rekeying → Closed
+```
+
+- `CallOffer { identity_pub, ephemeral_pub, signature, profiles }`
+- `CallAnswer { identity_pub, ephemeral_pub, signature, chosen_profile }`
+- `session_key = HKDF(X25519_DH(eph_a, eph_b), "warzone-session-key")`
+- Rekey every 65,536 packets via fresh ephemeral DH.
+
+## SFU forwarding rules
+
+1. Fan-out to all room participants except the sender.
+2. Failed sends are skipped; forwarding is best-effort.
+3. The relay never decrypts media.
+4. With trunking on, packets to the same receiver are batched (flush 5 ms).
+5. `QualityDirective` is broadcast when the room-wide tier degrades.
+
+## Adaptive quality (audio, today)
+
+| Tier | Codec | FEC | Frame |
+|---|---|---|---|
+| Good | Opus 24 k | 20 % | 20 ms |
+| Degraded | Opus 6 k | 50 % | 40 ms |
+| Catastrophic | Codec2 1200 | 100 % | 40 ms |
+
+Hysteresis: 3 reports to downgrade (2 on cellular), 10 to upgrade.
+
+## NAT traversal (Phase 8)
+
+- Candidate types: Host, Port-mapped (NAT-PMP / PCP / UPnP), Server-reflexive (STUN), Relay.
+- Hard-NAT port prediction with `classify_port_allocation()` → `predict_ports()` → `HardNatProbe` signal.
+- Mid-call re-gather: `CandidateUpdate { generation }`.
diff --git a/vault/Audit/Audit-2026-05-25.md b/vault/Audit/Audit-2026-05-25.md
new file mode 100644
index 0000000..b080e13
--- /dev/null
+++ b/vault/Audit/Audit-2026-05-25.md
@@ -0,0 +1,237 @@
+---
+tags: [audit, wzp]
+type: audit
+created: 2026-05-25
+---
+
+# WarzonePhone Protocol Audit — 2026-05-25
+
+**Auditor:** Claude Sonnet 4.6 (assisted)
+**Branch:** `experimental-ui` @ `f3e3ee5`
+**Scope:** All workspace crates (`wzp-proto`, `wzp-codec`, `wzp-fec`, `wzp-crypto`, `wzp-transport`, `wzp-relay`, `wzp-client`, `wzp-android`, `wzp-native`, `wzp-video`)
+**Test baseline:** 702 passing (excludes `wzp-android`)
+
+---
+
+## Executive Summary
+
+The audio call path is functionally correct and cryptographically sound on clean network paths. **There is a session-breaking bug in the crypto nonce derivation (C1) that will cause a permanent decryption failure on any out-of-order UDP delivery.** This is the single highest-priority fix — it will manifest as periodic session crashes under normal internet conditions. Video has a solid architectural foundation but three hard blockers remain before shipping: the AEAD coverage gap (C2), dead video scorer (C3), and Android MediaCodec compile failure (C4).
+
+The project is in good shape overall. The crypto design (X25519, HKDF, ChaCha20-Poly1305, Ed25519 identity, SAS verification) is sound. The SFU-never-decrypts architecture is rare and valuable. The codec adaptation (Opus DRED + Codec2 RaptorQ split) is genuinely innovative. The eight issues below are fixable in ~12 engineer-hours.
+
+---
+
+## Critical
+
+### C1 — Nonce derives from `recv_seq` counter, not `MediaHeader.seq`
+
+**File:** `crates/wzp-crypto/src/session.rs:132`
+**Severity:** Critical — session-breaking on any packet reorder
+
+```rust
+// decrypt()
+let nonce_bytes = nonce::build_nonce(&self.session_id, self.recv_seq, Direction::Send);
+// ...
+self.recv_seq = self.recv_seq.wrapping_add(1); // line 148
+```
+
+`recv_seq` increments once per successful `decrypt()` call. The sender's `send_seq` also increments once per `encrypt()` call (line 120). In perfect in-order delivery they stay synchronized. With any reorder or mid-stream packet loss they permanently diverge. Once diverged, every subsequent packet uses the wrong nonce → AEAD tag mismatch → every packet fails for the rest of the session.
+
+This isn't a low-probability edge case. UDP over any internet path reorders packets routinely. The `multiple_packets_roundtrip` test (line 254) only exercises in-order delivery. HANDOFF-2026-05-12.md acknowledges this as a known latent item: *"AEAD nonce derivation: switch to `MediaHeader::seq`"*.
+
+The anti-replay check at lines 152–161 already parses `MediaHeader` and has `header.seq` available. The fix is one line in `decrypt()`:
+
+```rust
+// Use sender's wire-level seq as nonce input, not a local counter.
+// This survives reordering because both sides derive the same nonce from
+// the same field. recv_seq was wrong: it diverged from send_seq on any
+// reorder, breaking all subsequent decryptions for the session.
+let header = parse_header(header_bytes)
+ .ok_or_else(|| CryptoError::Internal("header parse failed".into()))?;
+let nonce_bytes = nonce::build_nonce(&self.session_id, header.seq, Direction::Send);
+```
+
+Remove `recv_seq` field from `ChaChaSession` (it's now redundant — anti-replay uses `header.seq` directly). On the encrypt side, verify that `self.send_seq` equals the `seq` written into the `MediaHeader` at the call site.
+
+**Estimated effort:** ~1 hour including test coverage for out-of-order delivery.
+
+> **Note on rekey seq reset:** The agent initially flagged `send_seq/recv_seq = 0` in `complete_rekey()` as a separate critical issue. This is a false positive — `install_key()` rotates `session_id` (hash of new key), so pre-/post-rekey nonces live in distinct namespaces. The reset is intentional and cryptographically safe.
+
+---
+
+### C2 — AEAD not wired to every QUIC datagram send path
+
+**File:** `crates/wzp-client/src/analyzer.rs:363` (only confirmed decrypt call site)
+**Severity:** Critical — potential plaintext media leakage
+
+The HANDOFF document explicitly flags this: *"Encryption is implemented in `wzp-crypto` but not yet on every QUIC datagram path."* The `analyzer.rs` path decrypts inbound packets. What needs verification: every outbound `send_datagram()` / `write_datagram()` call across `wzp-client` and `wzp-transport` must pass through `ChaChaSession::encrypt()`.
+
+**Required action:** Grep every `send_datagram` call site. Confirm each path encrypts before transmit. Add a CI-level test or `#[forbid(dead_code)]`-style assertion that makes a plaintext send path impossible to merge. Until this is verified, the E2E security claim cannot be made.
+
+**Estimated effort:** ~1 hour audit + test.
+
+---
+
+### C3 — `VideoScorer::observe()` never called — scorer is dead code
+
+**File:** `crates/wzp-relay/src/room.rs:1263–1266`
+**Severity:** Critical — relay abuse control for video is completely absent
+
+```rust
+// T6.2-follow-up: feed video packets to VideoScorer here.
+// video_scorer.observe(&pkt.header, pkt.payload.len(), now, bwe_kbps);
+```
+
+`video_scorer.rs` was delivered in T6.2 with legitimacy scoring, keyframe regularity checks, I/P ratio analysis, and a verdict enum. The observe call was never wired into the packet forwarding loop. The scorer compiles but accumulates no data. Any participant can flood the room with malformed video or synthetic keyframe bursts and the relay will forward everything without challenge.
+
+**Fix:** Wire `video_scorer.observe(...)` at the TODO marker and integrate `legitimacy_score()` into the forwarding decision (drop or rate-limit streams with `Verdict::Malicious`). Add an integration test: synthetic high-frequency keyframe bursts should trigger a `Malicious` verdict within 2 seconds.
+
+**Estimated effort:** ~2 hours.
+
+---
+
+### C4 — `wzp-video` Android target fails to compile (31 errors)
+
+**File:** `crates/wzp-video/src/mediacodec.rs`
+**Severity:** Critical — Android video is completely blocked
+
+Five error categories from the NDK 0.9 API migration, all documented in HANDOFF-2026-05-12.md. `dav1d`/`svt-av1` were cfg-gated off Android in `f3e3ee5`; these 31 errors are the remaining MediaCodec API mismatch.
+
+| Error | Count | Root cause | Fix |
+|---|---|---|---|
+| `E0277` `NonNull` not `Send` | ~3 | Raw pointer held across `tokio::spawn` boundary | `struct SendMediaCodec(NonNull<…>); unsafe impl Send for SendMediaCodec {}` — or use `ndk::media::MediaCodec` owned type (already `Send`) |
+| `E0308` `&[MaybeUninit]` vs `&[u8]` | many | NDK 0.9 returns uninit slices | `MaybeUninit::write_slice` or transmute pattern |
+| `E0425` missing `BITRATE_MODE_CBR` | 1+ | Constant renamed in NDK 0.9 | Check `ndk` crate docs for current name |
+| `E0433` `ndk_sys` not a dep | several | Direct `ndk_sys` import; only `ndk = "0.9"` declared | Add `ndk-sys` as explicit dep or use safe `ndk` wrappers |
+| `E0599` `InputBuffer::index()` / `OutputBuffer::index()` private | 2 | API changed in NDK 0.9 | Use buffer through safe queue/dequeue API |
+
+Nothing live is blocked today — `wzp-video` is not yet consumed by Tauri Android. But video on Android cannot progress until this compiles.
+
+**Reproduce:**
+```bash
+ssh -i ~/CascadeProjects/wzp manwe@manwehs \
+ 'cd ~/wzp-builder/data/source && \
+ docker run --rm \
+ -v ~/wzp-builder/data/source:/build/source \
+ -v ~/wzp-builder/data/cache/cargo-registry:/home/builder/.cargo/registry \
+ -v ~/wzp-builder/data/cache/cargo-git:/home/builder/.cargo/git \
+ -v ~/wzp-builder/data/cache/target:/build/source/target \
+ wzp-android-builder:latest \
+ bash -c "cd /build/source && cargo build --target aarch64-linux-android -p wzp-video 2>&1 | tail -60"'
+```
+
+**Estimated effort:** ~2 hours (one commit per error category).
+
+---
+
+## High
+
+### H1 — AV1 call engine wiring missing
+
+**Source:** HANDOFF-2026-05-12.md (T6.1.2 open item)
+**File:** `crates/wzp-video/src/factory.rs`
+
+`factory.rs` and step tables landed in commit `086d0a4`. No caller yet invokes `create_video_encoder(Av1Main, ...)`. The entire AV1 path is reachable only from tests. Video on macOS/Linux desktop requires wiring `create_video_encoder` into the call engine's media negotiation path.
+
+**Estimated effort:** ~1–2 hours.
+
+---
+
+### H2 — `fec_block_id: u8` wraps every ~25 seconds
+
+**File:** `crates/wzp-fec/src/encoder.rs` (`block_id.wrapping_add(1)` on u8)
+**Reference:** PROTOCOL-AUDIT.md W2 (deferred P2)
+
+At 5 frames/block (Codec2), u8 ID wraps at block 256 ≈ 25 seconds. A slow reconstructor or late-joining peer will collide block IDs with in-flight blocks. The window distance check in `block_manager.rs` partially mitigates this but can't prevent all collisions. Widen to `u16` in the next wire-format revision.
+
+---
+
+## Medium
+
+### M1 — `SignalMessage` has no version byte
+
+**File:** `crates/wzp-proto/src/session.rs` (SignalMessage enum)
+**Reference:** PROTOCOL-AUDIT.md W12
+
+`bincode + serde(default)` handles field additions but not variant removal or semantic changes. Any variant deprecation is silent at the wire level. This becomes a correctness risk when federation routes `SignalMessage`s across relay versions. Add `version: u8` as a leading field to all variants before federation ships.
+
+---
+
+### M2 — BWE not consumed by `AdaptiveQualityController`
+
+**Reference:** PROTOCOL-AUDIT.md W6, deferred to Phase V2
+
+Quinn exposes `cwnd` and `bytes_in_flight`, but `AdaptiveQualityController` does not consume them. Loss + RTT adaptation works for audio. For video, without bandwidth estimation the encoder cannot detect available uplink capacity and will either oscillate or permanently under-utilize bandwidth. Mandatory before video production.
+
+---
+
+### M3 — PLI suppression window hardcoded at 200ms
+
+**File:** `crates/wzp-relay/src/room.rs:1060`
+
+Not adaptive to link speed. On slow links 200ms may allow multiple keyframe requests. Accept for Phase 1; make configurable in Phase 2.
+
+---
+
+### M4 — Repair packet index wrapping in FEC encoder
+
+**File:** `crates/wzp-fec/src/encoder.rs:140`
+
+```rust
+let idx = (num_source as u8).wrapping_add(i as u8);
+```
+
+If `num_source + repair_count > 255`, indices wrap silently. In practice bounded by `frames_per_block` (5–10), so max sum is ~20. Low risk today; widen to u16 when `fec_block_id` is widened (H2).
+
+---
+
+### M5 — `timestamp_ms` monotonicity after rekey not enforced
+
+**Reference:** PROTOCOL-AUDIT.md W3
+
+Spec: `timestamp_ms` must not reset on rekey. The code correctly does not reset it, but there is no assertion to prevent regression. Add a debug assert in `complete_rekey()` that `new_session.next_timestamp >= old_session.last_timestamp`.
+
+---
+
+## Low / Accepted Debt
+
+| ID | Description | File | Accepted in |
+|---|---|---|---|
+| L1 | 9 pre-existing clippy lints in `wzp-codec` | `aec.rs`, `denoise.rs`, `opus_enc.rs`, `codec2_{enc,dec}.rs`, `resample.rs` | PROTOCOL-AUDIT.md |
+| L2 | 3 clippy errors in `deps/featherchat` submodule | `ratchet.rs`, `types.rs` | PROTOCOL-AUDIT.md |
+| L3 | Audio anti-replay window 64 packets | `wzp-crypto/src/session.rs:89` | Accepted — jitter buffer + PLC masks loss |
+| L4 | Debug tap logs at INFO with no rate limiting | `wzp-relay/src/room.rs:46–59` | Safe in dev; add 1:100 sampling for prod |
+
+---
+
+## What Was Not Found
+
+These are explicitly confirmed sound after code-level verification:
+
+- **Anti-replay bitmap** — correct u32 wrapping, per-stream isolation, window sizing by `MediaType`
+- **HKDF + X25519 + Ed25519 key agreement** — standard construction, no gaps
+- **SAS code derivation** — SHA-256(shared_secret)[:4] as 4-digit voice verification code
+- **Rekey forward secrecy** — `session_id` rotation on rekey isolates nonce namespaces; seq counter reset is intentional and safe
+- **MiniHeader v2 `seq_delta`** — fully implemented at `wzp-proto/src/packet.rs:469–526` with tests; PROTOCOL-AUDIT resolution table is accurate
+- **SFU E2E preservation** — relay ciphertext passthrough, no plaintext access
+- **RaptorQ for Codec2** — correct tool for the bitrate regime
+- **DRED continuous tuning** — better than discrete tiers; 15% loss floor is empirically grounded
+- **Jitter buffer** — BTreeMap with wrapping-aware comparisons, EWMA adaptive playout delay, solid
+- **Quinn QUIC datagram transport** — correct primitives for unreliable media
+
+---
+
+## Fix Priority Table
+
+| # | Issue | Category | Effort | Blocks |
+|---|---|---|---|---|
+| 1 | C1: nonce → `MediaHeader.seq` | Crypto | 1h | All sessions on lossy paths |
+| 2 | C2: verify AEAD on all datagram send paths | Crypto | 1h | E2E security claim |
+| 3 | C3: wire `VideoScorer::observe()` into room | Relay | 2h | Relay abuse control for video |
+| 4 | C4: NDK 0.9 `mediacodec.rs` migration (5 categories) | Android | 2h | Android video |
+| 5 | H1: wire AV1 factory into call engine | Video | 2h | Desktop video |
+| 6 | H2: widen `fec_block_id` to `u16` | FEC/Wire | 30min | Next protocol release |
+| 7 | M1: `SignalMessage` version byte | Proto | 1h | Federation correctness |
+| 8 | M2: BWE into `AdaptiveQualityController` | Transport | 2–3 days | Video production quality |
+
+**Total for C1–H1 (items 1–5):** ~8 hours focused engineering.
diff --git a/vault/PRDs/PRD-adaptive-quality.md b/vault/PRDs/PRD-adaptive-quality.md
new file mode 100644
index 0000000..1ce9139
--- /dev/null
+++ b/vault/PRDs/PRD-adaptive-quality.md
@@ -0,0 +1,219 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Adaptive Quality Control (Auto Codec)
+
+## Problem
+
+When a user selects "Auto" quality, the system currently just starts at Opus 24k (GOOD) and never changes. There is no runtime adaptation — if the network degrades mid-call, audio breaks up instead of gracefully stepping down to a lower bitrate codec. Conversely, if the network is excellent, the user stays on 24k when they could have studio-quality 64k.
+
+The relay already sends `QualityReport` messages with loss % and RTT, and a `QualityAdapter` exists in `call.rs` that classifies network conditions into GOOD/DEGRADED/CATASTROPHIC — but none of this is wired into the Android or desktop engines.
+
+## Solution
+
+Wire the existing `QualityAdapter` into both engines so that "Auto" mode continuously monitors network quality and switches codecs mid-call. The full quality range should be used:
+
+```
+Excellent network → Studio 64k (best quality)
+Good network → Opus 24k (default)
+Degraded network → Opus 6k (lower bitrate, more FEC)
+Poor network → Codec2 3.2k (vocoder, heavy FEC)
+Catastrophic → Codec2 1.2k (minimum viable voice)
+```
+
+## Architecture
+
+```
+ ┌─────────────────────┐
+ Relay ──────────► │ QualityReport │ loss %, RTT, jitter
+ │ (every ~1s) │
+ └────────┬────────────┘
+ │
+ ▼
+ ┌─────────────────────┐
+ │ QualityAdapter │ classify + hysteresis
+ │ (3-report window) │
+ └────────┬────────────┘
+ │ recommend new profile
+ ▼
+ ┌──────────────┴──────────────┐
+ │ │
+ ▼ ▼
+ ┌────────────────┐ ┌────────────────┐
+ │ Encoder │ │ Decoder │
+ │ set_profile() │ │ (auto-switch │
+ │ + FEC update │ │ already works)│
+ └────────────────┘ └────────────────┘
+```
+
+## Existing Infrastructure
+
+### What already exists (in `crates/wzp-client/src/call.rs`)
+
+1. **`QualityAdapter`** (lines 97-196):
+ - Sliding window of `QualityReport` messages
+ - `classify()`: loss > 15% or RTT > 200ms → CATASTROPHIC, loss > 5% or RTT > 100ms → DEGRADED, else → GOOD
+ - `should_switch()`: hysteresis — requires 3 consecutive reports recommending the same profile before switching
+ - Prevents oscillation between profiles
+
+2. **`QualityReport`** (in `wzp-proto/src/packet.rs`):
+ - Sent by relay piggy-backed on media packets
+ - Fields: `loss_pct` (u8, 0-255 scaled), `rtt_4ms` (u8, RTT in 4ms units), `jitter_ms`, `bitrate_cap_kbps`
+
+3. **`CallEncoder::set_profile()`** / **`CallDecoder` auto-switch**:
+ - Encoder can switch codec mid-stream
+ - Decoder already auto-detects incoming codec from packet headers
+
+### What's been implemented since PRD was written
+
+1. **QualityReport ingestion** — ~~neither Android engine nor desktop engine reads quality reports from the relay~~ **Done**: both Android (`crates/wzp-android/src/engine.rs`) and desktop (`desktop/src-tauri/src/engine.rs`) recv tasks ingest quality reports and feed `AdaptiveQualityController`
+2. **Profile switch loop** — ~~no periodic check~~ **Done**: `pending_profile` AtomicU8 bridges recv→send task in both engines; send task applies profile switch at frame boundary
+3. **Notification to UI** — ~~when quality changes, the UI should show the current active codec~~ **Done**: `tx_codec`/`rx_codec` in desktop `EngineStatus`; `currentCodec`/`peerCodec` in Android `CallStats`
+
+### What's still missing
+
+1. **Upward adaptation** — `QualityAdapter` only classifies into 3 tiers (GOOD/DEGRADED/CATASTROPHIC). Needs extension to recommend studio tiers when conditions are excellent (loss < 1%, RTT < 50ms). See Phase 2 below.
+2. **Relay QualityDirective handling** — relay broadcasts coordinated quality directives but neither engine processes them (signals are silently discarded). See PRD-coordinated-codec.md for details.
+
+## Requirements
+
+### Phase 1: Basic Adaptive (3-tier)
+
+**Both Android and Desktop:**
+
+1. **Ingest QualityReports**: In the recv loop, extract `quality_report` from incoming `MediaPacket`s when present. Feed to `QualityAdapter`.
+
+2. **Periodic quality check**: Every 1 second (or on each QualityReport), call `adapter.should_switch(¤t_profile)`. If it returns `Some(new_profile)`:
+ - Switch the encoder: `encoder.set_profile(new_profile)`
+ - Update FEC encoder: `fec_enc = create_encoder(&new_profile)`
+ - Update frame size if changed (e.g., 20ms → 40ms)
+ - Log the switch
+
+3. **Frame size adaptation on switch**: When switching from 20ms to 40ms frames (or vice versa):
+ - Android: update `frame_samples` variable, resize `capture_buf`
+ - Desktop: same — the send loop reads `frame_samples` dynamically
+
+4. **UI indicator**: Show current active codec in the call screen stats line.
+ - Android: add to `CallStats` and display in stats text
+ - Desktop: add to `get_status` response and display in stats div
+
+5. **Only in Auto mode**: Adaptive switching should only happen when the user selected "Auto". If they manually selected a profile, respect their choice.
+
+### Phase 2: Extended Range (5-tier)
+
+Extend `QualityAdapter::classify()` to use the full codec range:
+
+| Condition | Profile | Codec |
+|-----------|---------|-------|
+| loss < 1% AND RTT < 30ms | STUDIO_64K | Opus 64k |
+| loss < 1% AND RTT < 50ms | STUDIO_48K | Opus 48k |
+| loss < 2% AND RTT < 80ms | STUDIO_32K | Opus 32k |
+| loss < 5% AND RTT < 100ms | GOOD | Opus 24k |
+| loss < 15% AND RTT < 200ms | DEGRADED | Opus 6k |
+| loss >= 15% OR RTT >= 200ms | CATASTROPHIC | Codec2 1.2k |
+
+With hysteresis:
+- **Downgrade**: 3 consecutive reports (fast reaction to degradation)
+- **Upgrade**: 5 consecutive reports (slow, cautious improvement)
+- **Studio upgrade**: 10 consecutive reports (very conservative — avoid bouncing to 64k on brief good patches)
+
+### Phase 3: Bandwidth Probing
+
+Rather than relying solely on loss/RTT:
+1. Start at GOOD
+2. After 10 seconds of stable call, probe upward by switching to STUDIO_32K
+3. If no quality degradation after 5 seconds, probe to STUDIO_48K
+4. If degradation detected, immediately fall back
+5. This discovers the true available bandwidth rather than guessing from loss stats
+
+## Implementation Plan
+
+### Android (`crates/wzp-android/src/engine.rs`)
+
+```rust
+// In the recv loop, after decoding:
+if let Some(ref qr) = pkt.quality_report {
+ quality_adapter.ingest(qr);
+}
+
+// Periodic check (every 50 frames ≈ 1 second):
+if auto_profile && frames_decoded % 50 == 0 {
+ if let Some(new_profile) = quality_adapter.should_switch(¤t_profile) {
+ info!(from = ?current_profile.codec, to = ?new_profile.codec, "auto: switching quality");
+ let _ = encoder_ref.lock().set_profile(new_profile);
+ fec_enc_ref.lock() = create_encoder(&new_profile);
+ current_profile = new_profile;
+ frame_samples = frame_samples_for(&new_profile);
+ // Resize capture buffer if needed
+ }
+}
+```
+
+**Challenge**: The encoder is in the send task and the quality reports arrive in the recv task. Need shared state (AtomicU8 for profile index, or a channel).
+
+**Recommended approach**: Use an `AtomicU8` that the recv task writes and the send task reads:
+```rust
+let pending_profile = Arc::new(AtomicU8::new(0xFF)); // 0xFF = no change
+
+// Recv task: when adapter recommends switch
+pending_profile.store(new_profile_index, Ordering::Release);
+
+// Send task: check at frame boundary
+let p = pending_profile.swap(0xFF, Ordering::Acquire);
+if p != 0xFF { /* apply switch */ }
+```
+
+### Desktop (`desktop/src-tauri/src/engine.rs`)
+
+Same pattern. The desktop engine already has separate send/recv tasks with shared atomics for mic_muted, etc. Add a `pending_profile: Arc` following the same pattern.
+
+### Desktop CLI (`crates/wzp-client/src/call.rs`)
+
+The `CallEncoder` already has `set_profile()`. The `CallDecoder` already auto-switches. Just need to:
+1. Add `QualityAdapter` to `CallDecoder`
+2. Feed quality reports in `ingest()`
+3. Check `should_switch()` in `decode_next()`
+4. Emit the recommendation via a callback or return value
+
+## Testing
+
+1. **Local test with tc/netem**: Use Linux traffic control to simulate loss/latency:
+ ```bash
+ # Simulate 10% loss, 150ms RTT
+ tc qdisc add dev lo root netem loss 10% delay 75ms
+ # Run 2 clients in auto mode, verify they switch to DEGRADED
+ ```
+
+2. **CLI test**: Run `wzp-client --profile auto` between two instances with simulated network conditions
+
+3. **Relay quality reports**: Verify the relay actually sends QualityReport messages. If it doesn't yet, that needs to be implemented first (check relay code).
+
+## Open Questions
+
+1. **Does the relay currently send QualityReports?** If not, Phase 1 is blocked until the relay implements per-client loss/RTT tracking and report generation. The relay sees all packets and can compute loss % per sender.
+
+2. **Codec2 3.2k placement**: Should auto mode use Codec2 3.2k between DEGRADED and CATASTROPHIC? It's 20ms frames (lower latency than Opus 6k's 40ms) but speech-only quality.
+
+3. **Cross-client adaptation**: If client A is on GOOD and client B auto-adapts to CATASTROPHIC, client A still sends Opus 24k. Client B can decode it fine (auto-switch on recv). But should A also be told to lower quality to save B's bandwidth? This requires signaling between clients.
+
+## Milestones
+
+| Phase | Scope | Effort | Status |
+|-------|-------|--------|--------|
+| 0 | Verify relay sends QualityReports | 0.5 day | Done |
+| 1a | Wire QualityAdapter in Android engine | 1 day | Done |
+| 1b | Wire QualityAdapter in desktop engine | 1 day | Done |
+| 1c | UI indicator (current codec) | 0.5 day | Done |
+| 2 | Extended 5-tier classification (Studio64k→Catastrophic) | 0.5 day | Done (2026-04-13) |
+| 3 | Bandwidth probing | 2 days | Pending (task #10) |
+
+## Implementation Status Update (2026-04-13)
+
+All phases implemented:
+- Phase 1: QualityAdapter with 3-tier classification — DONE
+- Phase 2: Extended 5-tier (Studio 64k/48k/32k + GOOD + DEGRADED + CATASTROPHIC) — DONE
+- Phase 3: Bandwidth probing — NOT DONE (see remaining tasks)
+- P2P adaptive quality: QualityReport::from_path_stats() + self-observation from quinn stats — DONE
+- Both relay and P2P calls now have full adaptive quality switching
diff --git a/vault/PRDs/PRD-bluetooth-audio.md b/vault/PRDs/PRD-bluetooth-audio.md
new file mode 100644
index 0000000..99d6ea7
--- /dev/null
+++ b/vault/PRDs/PRD-bluetooth-audio.md
@@ -0,0 +1,110 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Bluetooth Audio Routing
+
+> Phase: Implemented
+> Status: Ready for testing
+> Platforms: Android (native Kotlin app + Tauri desktop app)
+
+## Problem
+
+WarzonePhone had `AudioRouteManager.kt` with complete Bluetooth SCO support, but it was disconnected from both UIs. Users with Bluetooth headsets had no way to route call audio to them.
+
+## Solution
+
+Wire Bluetooth SCO routing end-to-end through both app variants, replacing the binary speaker toggle with a 3-way audio route cycle: **Earpiece → Speaker → Bluetooth**.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Native Kotlin App (com.wzp) │
+│ │
+│ InCallScreen ──► CallViewModel ──► AudioRouteManager
+│ (Compose UI) cycleAudioRoute() setSpeaker() │
+│ "Ear/Spk/BT" audioRoute Flow setBluetoothSco()
+│ isBluetoothAvailable()
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tauri Desktop App (com.wzp.desktop) │
+│ │
+│ main.ts ──► Tauri Commands ──► android_audio.rs │
+│ cycleAudioRoute() set_bluetooth_sco() JNI calls │
+│ "Ear/Spk/BT" is_bluetooth_available() │
+│ get_audio_route() │
+│ │
+│ After each route change: Oboe stop + start │
+│ (spawn_blocking to avoid stalling tokio) │
+└─────────────────────────────────────────────────────┘
+```
+
+## Components Modified
+
+### Native Kotlin App
+
+| File | Change |
+|------|--------|
+| `CallViewModel.kt` | Added `audioRoute: StateFlow`, `cycleAudioRoute()`, wired `onRouteChanged` callback |
+| `InCallScreen.kt` | `ControlRow` now takes `audioRoute: AudioRoute` + `onCycleRoute`, displays Ear/Spk/BT with distinct colors |
+
+### Tauri App
+
+| File | Change |
+|------|--------|
+| `android_audio.rs` | `setCommunicationDevice()` (API 31+) with `startBluetoothSco()` fallback; `set_audio_mode_communication/normal()` for call lifecycle |
+| `lib.rs` | `set_bluetooth_sco`, `is_bluetooth_available`, `get_audio_route` Tauri commands; SCO polling + 500ms route delay |
+| `wzp_native.rs` | Added `audio_start_bt()` for BT-mode Oboe (skips 48kHz + VoiceCommunication preset) |
+| `oboe_bridge.cpp` | `bt_active` flag: capture skips sample rate + input preset; playout uses `Usage::Media`; both use `Shared` mode + `SampleRateConversionQuality::Best` |
+| `engine.rs` | `set_audio_mode_communication()` before `audio_start()`; `set_audio_mode_normal()` after `audio_stop()` |
+| `MainActivity.kt` | Removed `MODE_IN_COMMUNICATION` from app launch — deferred to call start |
+| `main.ts` | Replaced `speakerphoneOn` toggle with `currentAudioRoute` cycling logic |
+| `style.css` | Added `.bt-on` CSS class (blue-400 highlight) |
+
+## Audio Route Lifecycle
+
+1. **App launch** → `MODE_NORMAL` (other apps' audio unaffected — BT A2DP music keeps playing)
+2. **Call starts** → `MODE_IN_COMMUNICATION` set via JNI, Oboe opens with earpiece routing
+3. **User taps route button** → cycles to next available route
+4. **Route changes** → `setCommunicationDevice()` (API 31+) + Oboe restart in BT mode or normal mode
+5. **BT device disconnects mid-call** → `AudioDeviceCallback.onAudioDevicesRemoved` fires → auto-fallback to Earpiece/Speaker
+6. **Call ends** → route reset, `MODE_NORMAL` restored
+
+## Route Cycling Logic
+
+```
+Available routes = [Earpiece, Speaker] + [Bluetooth] if SCO device connected
+
+Tap cycle:
+ Earpiece → Speaker → Bluetooth (if available) → Earpiece → ...
+
+If BT not available:
+ Earpiece → Speaker → Earpiece → ...
+```
+
+## Permissions
+
+- `BLUETOOTH_CONNECT` (Android 12+) — already in `AndroidManifest.xml`
+- `MODIFY_AUDIO_SETTINGS` — already in manifest
+
+## Known Limitations
+
+- **SCO only** — no A2DP (stereo music profile). SCO is correct for VoIP (bidirectional mono).
+- **API 31+ required for modern path** — `setCommunicationDevice()` is the primary BT routing API. Fallback to deprecated `startBluetoothSco()` on API < 31 (untested).
+- **BT SCO capture at 8/16kHz** — Oboe resamples to 48kHz via `SampleRateConversionQuality::Best`. Quality is inherently limited by the SCO codec (CVSD at 8kHz or mSBC at 16kHz).
+- **No auto-switch on BT connect** — when a BT device connects mid-call, user must tap the route button.
+- **500ms route switch delay** — after `setCommunicationDevice()` returns, the audio policy needs time to apply the bt-sco route. We wait 500ms before restarting Oboe.
+
+## Testing
+
+1. Pair a Bluetooth SCO headset with Android device
+2. Start call → verify Earpiece is default
+3. Tap route → Speaker (audio moves to loudspeaker, button shows "Spk")
+4. Tap route → BT (audio moves to headset, button shows "BT", blue highlight)
+5. Tap route → Earpiece (audio back to earpiece, button shows "Ear")
+6. Disconnect BT mid-call → verify auto-fallback
+7. Verify both app variants work identically
+8. Verify no audio glitches during route transitions
diff --git a/vault/PRDs/PRD-coordinated-codec.md b/vault/PRDs/PRD-coordinated-codec.md
new file mode 100644
index 0000000..ea95b41
--- /dev/null
+++ b/vault/PRDs/PRD-coordinated-codec.md
@@ -0,0 +1,226 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Coordinated Codec Switching (Relay-Judged Quality)
+
+## Problem
+
+The current adaptive quality system (`QualityAdapter` in call.rs) exists but isn't wired into either engine. Clients encode at a fixed quality chosen at call start. When network conditions change mid-call, audio degrades instead of gracefully stepping down. When conditions improve, clients stay on low quality unnecessarily.
+
+Additionally, in SFU mode with multiple participants, uncoordinated codec switching creates asymmetry: if client A upgrades to 64k while B stays on 24k, bandwidth is wasted. Participants should switch together.
+
+## Solution
+
+The **relay acts as the quality judge** since it sees both sides of every connection. It monitors packet loss, jitter, and RTT per participant, then signals quality recommendations. Clients react to these signals with coordinated codec switches.
+
+## Architecture
+
+```
+┌─────────┐ ┌─────────┐ ┌─────────┐
+│ Client A │◄──────►│ Relay │◄──────►│ Client B │
+│ │ │ (judge) │ │ │
+│ Encoder │ │ │ │ Encoder │
+│ Decoder │ │ Monitor │ │ Decoder │
+└─────────┘ │ per-peer│ └─────────┘
+ │ quality │
+ └────┬────┘
+ │
+ Quality Signals:
+ - StableSignal (conditions good)
+ - DegradeSignal (conditions bad)
+ - UpgradeProposal (try higher quality?)
+ - UpgradeConfirm (all agreed, switch at T)
+```
+
+## Quality Classification (Relay-Side)
+
+The relay monitors each participant's connection quality:
+
+| Condition | Classification | Action |
+|-----------|---------------|--------|
+| loss >= 15% OR RTT >= 200ms | Critical | Immediate downgrade signal |
+| loss >= 5% OR RTT >= 100ms | Degraded | Downgrade signal after 3 reports |
+| loss < 2% AND RTT < 80ms | Good | Stable signal |
+| loss < 1% AND RTT < 50ms for 30s | Excellent | Upgrade proposal |
+| loss < 0.5% AND RTT < 30ms for 60s | Studio | Studio upgrade proposal |
+
+## Coordinated Switching Protocol
+
+### Downgrade (fast, safety-first)
+
+1. Relay detects degradation for ANY participant
+2. Relay sends `QualityUpdate { recommended_profile: DEGRADED }` to ALL participants
+3. ALL participants immediately switch encoder to the recommended profile
+4. No negotiation — downgrade is mandatory and instant
+
+### Upgrade (slow, consensual)
+
+1. Relay detects sustained good conditions for ALL participants (threshold: 30s stable)
+2. Relay sends `UpgradeProposal { target_profile, switch_timestamp }` to all
+3. Each client responds: `UpgradeAccept` or `UpgradeReject`
+4. If ALL accept within 5s → Relay sends `UpgradeConfirm { profile, switch_at_ms }`
+5. All clients switch encoder at the agreed timestamp (relative to session clock)
+6. If ANY rejects or times out → upgrade cancelled, stay on current profile
+
+### Asymmetric Encoding (SFU optimization)
+
+In SFU mode, each client encodes independently. The relay could allow:
+- Client A (strong connection): encode at 64k
+- Client B (weak connection): encode at 6k
+- Relay forwards A's 64k to B's decoder (auto-switch handles it)
+- B benefits from A's quality without needing to send at 64k
+
+This requires NO protocol changes — just each client independently following the relay's recommendation for their own encoding quality. The decoder already handles any codec.
+
+### Split Network Consideration
+
+If participant A has great quality but participant C has terrible quality:
+- Option 1: **Match weakest link** — everyone encodes at C's level (current approach, simple)
+- Option 2: **Per-participant recommendations** — A encodes at 64k, C encodes at 6k. B (good connection) receives and decodes both. Works because decoders auto-switch per packet.
+- Option 3: **Relay transcoding** — relay re-encodes A's 64k as 6k for C. Adds CPU on relay, but saves bandwidth for C. Future feature.
+
+Recommended: start with Option 1 (match weakest), add Option 2 later.
+
+## Signal Messages (New/Modified)
+
+```rust
+/// Quality signal from relay to client
+QualityDirective {
+ /// Recommended profile to use for encoding
+ recommended_profile: QualityProfile,
+ /// Reason for the recommendation
+ reason: QualityReason,
+}
+
+enum QualityReason {
+ /// Network conditions require this quality level
+ NetworkCondition,
+ /// Coordinated upgrade — all participants agreed
+ CoordinatedUpgrade,
+ /// Coordinated downgrade — weakest link determines level
+ CoordinatedDowngrade,
+}
+
+/// Upgrade proposal from relay
+UpgradeProposal {
+ target_profile: QualityProfile,
+ /// Milliseconds from now when the switch would happen
+ switch_delay_ms: u32,
+}
+
+/// Client response to upgrade proposal
+UpgradeResponse {
+ accepted: bool,
+}
+
+/// Confirmed upgrade — all clients switch at this time
+UpgradeConfirm {
+ profile: QualityProfile,
+ /// Session-relative timestamp to switch (ms since call start)
+ switch_at_session_ms: u64,
+}
+```
+
+## Relay-Side Implementation
+
+### Per-Participant Quality Tracking
+
+```rust
+struct ParticipantQuality {
+ /// Sliding window of recent observations
+ loss_samples: VecDeque, // last 30 seconds
+ rtt_samples: VecDeque, // last 30 seconds
+ jitter_samples: VecDeque,
+ /// Current classification
+ classification: QualityClass,
+ /// How long current classification has been stable
+ stable_since: Instant,
+}
+```
+
+### Quality Monitor Task (on relay)
+
+Runs alongside the SFU forwarding loop:
+1. Every 1 second, compute per-participant quality from QUIC connection stats
+2. Classify each participant
+3. If ANY participant degrades → send downgrade to ALL
+4. If ALL participants stable for threshold → propose upgrade
+5. Track upgrade negotiation state
+
+### Integration with Existing Code
+
+The relay already has access to:
+- `QuinnTransport::path_quality()` → loss, RTT, jitter, bandwidth estimates
+- `QualityReport` embedded in media packet headers
+- Per-session metrics in `RelayMetrics`
+
+The quality monitor just needs to read these existing metrics and produce signals.
+
+## Client-Side Implementation
+
+### Handling Quality Signals
+
+In the recv loop (both Android engine and desktop engine):
+```rust
+SignalMessage::QualityDirective { recommended_profile, .. } => {
+ // Immediate: switch encoder to recommended profile
+ encoder.set_profile(recommended_profile)?;
+ fec_enc = create_encoder(&recommended_profile);
+ frame_samples = frame_samples_for(&recommended_profile);
+ info!(codec = ?recommended_profile.codec, "quality directive: switched");
+}
+```
+
+### P2P Quality (simpler case)
+
+For P2P calls (no relay), both clients directly observe quality:
+1. Each client runs its own `QualityAdapter` on the direct connection
+2. When quality changes, client proposes to peer via signal
+3. Simpler negotiation: only 2 parties, no relay middleman
+4. Same coordinated switching logic, just peer-to-peer signals
+
+## Backporting P2P → Relay
+
+The quality monitoring and codec switching logic is identical:
+- **P2P**: client observes quality directly → proposes switch to peer
+- **Relay**: relay observes quality → proposes switch to all clients
+
+The only difference is WHO makes the decision (client vs relay) and HOW many participants need to agree (2 vs N).
+
+Implementation strategy: build for P2P first (simpler, 2 parties), then wrap the same logic with relay-mediated signals for SFU mode.
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Relay-side quality monitor (per-participant tracking) | 1 day |
+| 2 | Downgrade signal (immediate, match weakest) | 1 day |
+| 3 | Client handling of QualityDirective | 1 day (both engines) |
+| 4 | Upgrade proposal + negotiation protocol | 2 days |
+| 5 | P2P quality adaptation (direct observation) | 1 day |
+| 6 | Per-participant asymmetric encoding (Option 2) | 1 day |
+
+## Implementation Status (2026-04-13)
+
+Phases 1-2 are implemented. Phase 3 has a critical gap.
+
+### What was built
+
+- **`QualityDirective` signal** (`crates/wzp-proto/src/packet.rs`): New `SignalMessage` variant with `recommended_profile` and optional `reason`
+- **`ParticipantQuality`** (`crates/wzp-relay/src/room.rs`): Per-participant quality tracking using `AdaptiveQualityController`, created on join, removed on leave
+- **Weakest-link broadcast**: `observe_quality()` method computes room-wide worst tier, broadcasts `QualityDirective` to all participants when tier changes
+- **Desktop engine handling** (`desktop/src-tauri/src/engine.rs`): `AdaptiveQualityController` in recv task, `pending_profile` AtomicU8 bridge to send task, auto-mode profile switching based on **inbound quality reports**
+
+### Phase 3 completed (2026-04-13)
+
+Both engines now handle `QualityDirective` signals from the relay:
+- **Desktop** (`engine.rs`): both P2P and relay signal tasks match `QualityDirective`, extract `recommended_profile`, store index via `sig_pending_profile.store(idx, Release)`. Send task picks it up at the next frame boundary.
+- **Android** (`engine.rs`): signal task matches `QualityDirective`, stores via `pending_profile_recv.store(idx, Release)`.
+
+Relay-coordinated codec switching is now end-to-end: relay monitors → broadcasts directive → clients switch.
+
+### Phase remaining
+
+- Phase 4: Upgrade proposal/negotiation protocol for quality recovery (task #28)
diff --git a/vault/PRDs/PRD-delegated-trust.md b/vault/PRDs/PRD-delegated-trust.md
new file mode 100644
index 0000000..890fd15
--- /dev/null
+++ b/vault/PRDs/PRD-delegated-trust.md
@@ -0,0 +1,175 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Delegated Trust for Relay Federation
+
+## Problem
+
+In the current federation model, when Relay 1 trusts Relay 2, and Relay 2 forwards media from Relay 3, Relay 1 has no way to know or control that Relay 3's traffic is reaching it. This is a trust gap — any relay in the chain can introduce untrusted traffic.
+
+**Example:** Relay 1 (trusted zone) ←→ Relay 2 (hub) ←→ Relay 3 (unknown)
+
+Relay 1 explicitly trusts Relay 2. But Relay 2 forwards Relay 3's media to Relay 1 without Relay 1's consent. Relay 1 receives media that originated from an entity it never approved.
+
+## Solution
+
+Add a `delegate` flag to `[[trusted]]` entries. When `delegate = true`, the relay accepts media forwarded through the trusted peer from relays that the trusted peer vouches for. When `delegate = false` (default), only media originating from explicitly trusted/peered relays is accepted.
+
+## Trust Levels
+
+| Config | Meaning |
+|--------|---------|
+| `[[peers]]` | "I connect to you and trust your identity" |
+| `[[trusted]]` | "I accept connections from you" |
+| `[[trusted]] delegate = true` | "I accept connections from you AND from relays you vouch for" |
+| No entry | "I reject your connections and drop your forwarded media" |
+
+## Configuration
+
+```toml
+# Relay 1: trusts Relay 2 and delegates trust
+[[trusted]]
+fingerprint = "relay-2-tls-fingerprint"
+label = "Relay 2 (Hub)"
+delegate = true # Accept relays that Relay 2 forwards from
+
+# Without delegate (default = false):
+[[trusted]]
+fingerprint = "relay-4-tls-fingerprint"
+label = "Relay 4"
+# delegate = false (implicit default)
+# Only direct media from Relay 4 is accepted
+```
+
+## Protocol Changes
+
+### Relay-to-Relay Media Authorization
+
+When Relay 2 forwards media from Relay 3 to Relay 1, the datagram needs to carry origin information so Relay 1 can decide whether to accept it.
+
+**Option A: Origin tag in datagram** (recommended)
+
+Extend the federation datagram format:
+```
+[room_hash: 8 bytes][origin_relay_fp: 8 bytes][media_packet]
+```
+
+The 8-byte origin fingerprint identifies which relay originally produced the media. The forwarding relay (Relay 2) sets this to the source relay's fingerprint. Relay 1 checks:
+1. Is the origin relay directly trusted? → accept
+2. Is the forwarding relay trusted with `delegate = true`? → accept
+3. Otherwise → drop
+
+**Option B: Trust announcement signal**
+
+When Relay 2 connects to Relay 1, it sends a `FederationTrustChain` signal listing which relays it will forward from:
+```rust
+FederationTrustChain {
+ /// Fingerprints of relays this peer may forward media from
+ vouched_relays: Vec,
+}
+```
+
+Relay 1 checks each fingerprint against its policy:
+- If Relay 2 has `delegate = true` in Relay 1's config → accept all listed relays
+- If Relay 2 has `delegate = false` → reject, only accept direct media from Relay 2
+
+Option B is simpler to implement (no datagram format change) but less granular.
+
+### Recommended: Option B for v1, Option A for v2
+
+Option B is simpler — the trust chain is established at connection time, not per-datagram. The forwarding relay announces what it will forward, and the receiving relay approves or rejects upfront.
+
+## Implementation
+
+### Config Changes
+
+```rust
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrustedConfig {
+ pub fingerprint: String,
+ #[serde(default)]
+ pub label: Option,
+ /// When true, also accept media forwarded through this relay from
+ /// relays it vouches for. Default: false.
+ #[serde(default)]
+ pub delegate: bool,
+}
+```
+
+### Federation Signal
+
+```rust
+/// Sent after FederationHello — lists relays this peer will forward from.
+FederationTrustChain {
+ /// TLS fingerprints of relays whose media may be forwarded through us.
+ vouched_relays: Vec,
+}
+```
+
+### Forwarding Authorization
+
+In `handle_datagram`, before forwarding media to local participants:
+
+```rust
+// Check if we should accept this forwarded media
+let is_authorized = if source_is_direct_peer {
+ true // Direct peer, always accepted
+} else {
+ // Check if the forwarding peer has delegate=true
+ let forwarding_peer = fm.find_trusted_by_fingerprint(forwarding_peer_fp);
+ forwarding_peer.map(|t| t.delegate).unwrap_or(false)
+};
+
+if !is_authorized {
+ warn!("dropping forwarded media from unauthorized relay chain");
+ return;
+}
+```
+
+### Relay 2 (Hub) Behavior
+
+When Relay 2 receives `FederationTrustChain` queries from peers:
+1. Collect all directly connected peer fingerprints
+2. Send `FederationTrustChain { vouched_relays }` to each peer
+3. When a new relay connects, update all peers' trust chains
+
+### Anti-Spam Properties
+
+| Attack | Mitigation |
+|--------|-----------|
+| Unknown relay connects to hub | Hub rejects (not in `[[trusted]]`) |
+| Hub forwards spam relay's media | Receiving relay checks delegate flag, drops if false |
+| Relay spoofs origin fingerprint | Origin tag is set by the forwarding relay, not the source. The forwarding relay is trusted, so if it lies about origin, the trust is misplaced at the config level. |
+| Chain amplification (A→B→C→D→...) | TTL on forwarded datagrams (decrement at each hop, drop at 0). Default TTL=2 (one intermediate relay). |
+
+## TTL for Chain Length
+
+Add a TTL byte to the federation datagram to limit chain depth:
+
+```
+[room_hash: 8 bytes][ttl: 1 byte][media_packet]
+```
+
+- Default TTL = 2 (allows one intermediate relay: A→B→C)
+- Each forwarding relay decrements TTL
+- When TTL = 0, don't forward further (only deliver to local participants)
+- Configurable per-relay: `max_federation_hops = 2`
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Add `delegate` field to `TrustedConfig` | 0.5 day |
+| 2 | `FederationTrustChain` signal + announcement | 1 day |
+| 3 | Authorization check in `handle_datagram` | 0.5 day |
+| 4 | TTL in federation datagrams | 0.5 day |
+| 5 | Testing: authorized vs unauthorized forwarding | 0.5 day |
+
+## Non-Goals (v1)
+
+- Per-room trust policies (trust Relay X only for room "android")
+- Dynamic trust negotiation (relays negotiate trust level at runtime)
+- Revocation (removing a relay from trust chain requires config edit + restart)
+- Cryptographic proof of origin (signed datagrams from source relay)
diff --git a/vault/PRDs/PRD-dred-integration.md b/vault/PRDs/PRD-dred-integration.md
new file mode 100644
index 0000000..77d3bb2
--- /dev/null
+++ b/vault/PRDs/PRD-dred-integration.md
@@ -0,0 +1,407 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: DRED Integration & Opus-Tier FEC Simplification
+
+## Problem
+
+WarzonePhone's audio loss-recovery stack is built around classical Opus + application-level RaptorQ FEC. It was the right answer when WZP was designed, but libopus 1.5 (December 2023) introduced **Deep REDundancy (DRED)** — a neural speech-recovery feature that is strictly better than classical FEC for the loss patterns VoIP calls actually experience. We are paying real latency, bitrate, and complexity costs for protection that DRED now does better and cheaper.
+
+Concretely, on every Opus call today we pay:
+
+- **~40–100 ms of receiver-side latency** waiting for RaptorQ block completion before decode
+- **10–20% bitrate overhead** from RaptorQ repair symbols (more on studio profiles)
+- **~20–40% codec-internal overhead** from Opus inband FEC (LBRR)
+- Classical Opus PLC on loss bursts exceeding the RaptorQ block size — which sounds robotic and gap-ridden
+
+…in exchange for bit-exact recovery of isolated single-frame losses, which is perceptually indistinguishable from classical Opus PLC for 20 ms of speech. The protection is misaligned with the failure modes.
+
+DRED delivers:
+
+- **Zero added receive latency** — reconstruction runs only on detected loss
+- **~1 kbps flat bitrate overhead** regardless of base bitrate
+- **Plausible reconstruction of bursts up to ~1 second** — DRED's headline capability, exactly the regime RaptorQ can't touch
+- Neural PLC that sounds like continuous speech, not a gap
+
+We also have a second, unrelated problem blocking adoption: our FFI crate `audiopus_sys 0.2.2` vendors **libopus 1.3**, predating DRED entirely. We cannot enable DRED without first swapping the FFI layer. The naïve choice (`opus` crate from SpaceManiac) is a trap — it depends on the same dead `audiopus_sys`. The real target is `opusic-c 1.5.5` by DoumanAsh, which vendors libopus 1.5.2 with full DRED support and documents Android NDK cross-compile.
+
+This PRD covers the FFI swap, DRED enablement, the decision to **remove RaptorQ and Opus inband FEC from the Opus tiers entirely** (keeping RaptorQ only for Codec2 where DRED is N/A), and the jitter buffer refactor that the DRED lookahead/backfill pattern requires.
+
+## Goals
+
+- Replace `audiopus 0.3.0-rc.0` + `audiopus_sys 0.2.2` (dead upstream, libopus 1.3) with `opusic-c 1.5.5` + `opusic-sys 0.6.0` (active upstream, libopus 1.5.2)
+- Enable DRED on every Opus profile with a tiered duration policy, lower at studio bitrates and higher at degraded bitrates
+- Disable Opus inband FEC (LBRR) on all Opus profiles — opusic-c's own docs recommend this, and it overlaps DRED's job
+- Remove `wzp-fec` (RaptorQ) from the Opus tiers entirely — the latency and bitrate savings are real, and DRED strictly dominates it on speech
+- Keep RaptorQ + current FEC ratios on the Codec2 tiers unchanged — DRED is libopus-only, Codec2 has no neural equivalent
+- Refactor `wzp-transport::jitter` to a lookahead/backfill pattern that lets DRED reconstruct loss windows when the next packet arrives, instead of the current "wait for block completion or fall through to classical PLC" policy
+- Ship behind a runtime escape hatch (`AUDIO_USE_LEGACY_FEC`) for the first rollout window so we can revert to RaptorQ if DRED has surprises in real-world conditions
+
+## Non-goals
+
+- Changing Codec2 at all. Codec2 1200 / 3200 are outside the DRED lineage and keep their current RaptorQ protection, block sizes, and PLC path.
+- Adding new Opus bitrate tiers or changing the quality adaptation thresholds. This PRD is about the protection layer, not the bitrate ladder.
+- Enabling OSCE (Opus Speech Coding Enhancement — a separate libopus 1.5 neural post-processor that opusic-c exposes via an `osce` feature flag). Valuable, complementary, and free once opusic-c is in — but out of scope here to keep the PRD focused. Track as follow-up.
+- Video, audio-over-MoQ, or any protocol-layer changes discussed in prior conversations.
+- Touching the wzp-web / browser client. Browser Opus is a separate codepath via WebAudio / WASM libopus and is not affected by the native FFI swap.
+
+## Background
+
+### How the three protection mechanisms actually differ
+
+| | Opus inband FEC (LBRR) | RaptorQ (wzp-fec) | DRED |
+|---|---|---|---|
+| Layer | codec-internal | application, across Opus packets | codec-internal |
+| What it sends | low-bitrate copy of the *previous* frame, embedded in every packet | fountain-code repair symbols across a block | neural-coded history of the recent past |
+| Protection horizon | 1 packet back | block duration (currently 100 ms, proposed 40 ms) | configurable, 0–1040 ms |
+| Recovery granularity | 1 frame (lower quality) | 1 frame (bit-exact) | 10 ms frames (plausible reconstruction) |
+| Latency cost | 0 ms | block duration on receive | 0 ms |
+| Bitrate cost | ~20–40% of base | `fec_ratio × base` (currently +20% GOOD, +50% DEGRADED) | ~1 kbps flat |
+| Effective loss tolerance | ~single-packet losses | up to `(repair symbols / block)` losses, cliff beyond | bursts up to the configured duration |
+| Content assumption | any Opus audio | any | speech (DRED model is speech-trained) |
+
+### Why DRED dominates on the Opus tiers
+
+Loss-scenario walkthrough (verified against opusic-c and libopus 1.5 docs):
+
+- **1-frame loss (20 ms)**: RaptorQ recovers bit-exactly, DRED wouldn't run (classical Opus PLC is perceptually indistinguishable for single 20 ms frames). RaptorQ "wins" on paper but not on ears.
+- **2–3 frame burst (40–60 ms)**: RaptorQ at current ratio 0.2 hits its tolerance cliff. DRED handles this trivially — well within a 200 ms window.
+- **5–10 frame burst (100–200 ms)**: RaptorQ completely overwhelmed at any reasonable ratio. DRED's sweet spot.
+- **10+ frame burst (>200 ms)**: RaptorQ useless. DRED at 500–1000 ms still recovers.
+
+The only scenario where RaptorQ strictly beats DRED is bit-exact recovery of isolated single-frame losses — which is perceptually irrelevant for speech. In every other scenario DRED either ties or wins.
+
+### Why Codec2 keeps RaptorQ
+
+DRED lives inside libopus — it does not help Codec2 at all. Codec2's classical PLC is a parametric-vocoder interpolation that produces noticeably robotic artifacts on loss. On the Codec2 tiers, RaptorQ is the only protection we have, and it should stay at current ratios (1.0 on CATASTROPHIC, 0.5 on the Codec2 3200 tier).
+
+### The opusic-c / opusic-sys situation
+
+- `opusic-sys 0.6.0` — FFI crate, published 2026-03-17, vendors libopus 1.5.2 via its `bundled` feature (on by default), documents Android NDK cross-compile via `ANDROID_NDK_HOME` (which our `wzp-android/build.rs` already sets). Exposes raw bindings to `opus_dred_parse`, `opus_decoder_dred_decode`, and the `OpusDRED` state struct.
+- `opusic-c 1.5.5` — high-level safe wrapper. Its **encoder** side is fine: exposes `Encoder::set_dred_duration(value: u8) -> Result<(), ErrorCode>` with range `0..=104` (each unit is 10 ms, so 0–1040 ms configurable). Also exposes `set_bitrate`, `set_inband_fec`, `set_dtx`, `set_packet_loss`, `set_signal`, `set_complexity`, `set_bandwidth`, `set_application` on the encoder.
+- **opusic-c's decoder-side DRED wrapper is NOT sufficient for our architecture.** Confirmed by reading the source of `opusic-c/src/dred.rs`:
+ 1. `Dred::decode_to` ignores the `dred_end` output of `opus_dred_parse` (prefixed `_dred_end`), so the caller cannot know how much DRED history a given packet actually carried.
+ 2. In `opus_decoder_dred_decode(decoder, dred, dred_offset, pcm, frame_size)`, the wrapper passes `frame_size` to BOTH the `dred_offset` and `frame_size` arguments. This looks like a bug — it means reconstruction always starts at offset `frame_size` into the DRED window, not at an arbitrary caller-chosen offset. Arbitrary-gap reconstruction (which we need for the lookahead/backfill pattern) requires proper offset control.
+ 3. `DredPacket` is owned internally by a `Dred` instance; its internal buffer is overwritten on every `decode_to` call. We cannot hold a ring of parsed DredPackets from multiple recent arrivals — which is exactly what the lookahead/backfill jitter buffer pattern requires.
+- **Decision**: use opusic-c for the encoder path (its wrapper is correct and saves work), and drop to `opusic-sys` raw FFI for the entire decoder path AND the DRED reconstruction path. Both use a single shared `DecoderHandle` so internal decoder state stays consistent. **Verified at pre-flight**: `opusic_c::Decoder.inner` is `pub(crate)`, so there is no way to reach the raw `*mut OpusDecoder` from outside opusic-c. Running two parallel decoders (one from opusic-c for audio, one from opusic-sys for DRED) would cause state drift because the DRED-only decoder wouldn't see the normal decode calls. Single unified decoder via opusic-sys is the only correct architecture.
+- **Three FFI handles required** per decode session: `opusic_c::Encoder` (encoder side, unchanged), our own `DecoderHandle` wrapping `*mut OpusDecoder` from opusic-sys (for normal decode AND for the `OpusDecoder` pointer passed to `opus_decoder_dred_decode`), and a new `DredDecoderHandle` wrapping `*mut OpusDREDDecoder` from opusic-sys (passed to `opus_dred_parse`). Note: `OpusDREDDecoder` is a **separate struct** from `OpusDecoder` in libopus 1.5 — verified from opus.h. Allocation via `opus_dred_decoder_create()` (confirm exact symbol name at Phase 3a start).
+- The `opus` crate from SpaceManiac (0.3.1, published 2026-01-03) is a trap: it depends on `audiopus_sys ^0.2.0` — the same dead FFI crate we're trying to get away from. Do not use.
+- **Follow-up (out of scope for this PRD)**: upstream the fixes to `opusic-c/src/dred.rs` (preserve `dred_end`, fix the `dred_offset` double-pass, expose `DredPacket` externally). Worth a GitHub PR once our own implementation has proven correct. Would let us eventually delete our internal FFI wrapper.
+
+### Critical note from opusic-c docs
+
+From the `dred` module documentation: *"The documentation recommends disabling in-band FEC and using `Application::Voip` for optimal results."* This applies to the **codec-internal** Opus inband FEC (LBRR), not our application-level RaptorQ. The two are independent layers. This PRD disables both on Opus tiers, but for different reasons — inband FEC per upstream recommendation, RaptorQ per the analysis above.
+
+### The libopus 1.5 loss-percentage gating quirk
+
+In libopus 1.5, both inband FEC and DRED are gated on `OPUS_SET_PACKET_LOSS_PERC` being non-zero. If the encoder thinks loss is 0%, it will not emit DRED data even when `set_dred_duration` is configured. We must plumb a meaningful loss percentage into the encoder continuously, floored at a small non-zero value so DRED stays active even when the network is perfect. Planned floor: **5%**, overridden upward by the real `QualityReport` loss value when it exceeds the floor.
+
+## Solution
+
+### High-level architecture change
+
+**Before** (per Opus frame encode path):
+```
+PCM → AdaptiveEncoder.encode (Opus)
+ → inband FEC embedded in packet
+ → wzp-fec FEC encoder (accumulate into block, generate repair symbols)
+ → DATAGRAM out
+```
+
+**Before** (per Opus frame decode path):
+```
+DATAGRAM in → wzp-fec block assembly (wait for block, recover if possible)
+ → AdaptiveDecoder.decode (Opus) / decode_lost (classical PLC)
+ → PCM
+```
+
+**After** (Opus tiers):
+```
+PCM → OpusEncoder.encode (opusic-c, DRED enabled via set_dred_duration, inband FEC off)
+ → DATAGRAM out directly (no RaptorQ block)
+```
+
+```
+DATAGRAM in → jitter buffer (lookahead/backfill)
+ → on frame arrival: OpusDecoder.decode
+ → on detected gap: if next packet has DRED state → dred::Dred.reconstruct(gap)
+ else → OpusDecoder.decode_lost (classical PLC)
+ → PCM
+```
+
+**After** (Codec2 tiers): unchanged. RaptorQ block encoding + classical Codec2 decode path stay exactly as they are today.
+
+### New per-profile protection matrix
+
+| Profile | Codec | Inband FEC | RaptorQ ratio | DRED duration | Total overhead |
+|---|---|---|---|---|---|
+| `STUDIO_64K` | Opus 64k | **off** | **none** | **10 frames (100 ms)** | +1 kbps |
+| `STUDIO_48K` | Opus 48k | **off** | **none** | **10 frames (100 ms)** | +1 kbps |
+| `STUDIO_32K` | Opus 32k | **off** | **none** | **10 frames (100 ms)** | +1 kbps |
+| `GOOD` | Opus 24k | **off** | **none** | **20 frames (200 ms)** | +1 kbps |
+| `NORMAL_16K` | Opus 16k | **off** | **none** | **20 frames (200 ms)** | +1 kbps |
+| `DEGRADED` | Opus 6k | **off** | **none** | **50 frames (500 ms)** | +1 kbps |
+| `CODEC2_3200` | Codec2 3200 | N/A | **0.5 (unchanged)** | N/A | +50% |
+| `CATASTROPHIC` | Codec2 1200 | N/A | **1.0 (unchanged)** | N/A | +100% |
+| `COMFORT_NOISE` | CN | — | — | — | — |
+
+DRED duration rationale:
+
+- **Studio tiers (100 ms)**: loss is rare on the networks where users pick studio quality. Short DRED window keeps decode-side CPU modest. Still covers multi-frame bursts that classical PLC can't touch.
+- **Normal tiers (200 ms)**: balanced baseline. Handles the common VoIP loss pattern (20–150 ms bursts from wifi roam, transient congestion).
+- **Degraded tier (500 ms)**: users on Opus 6k are by definition on a bad link. Long DRED window buys maximum burst resilience where it matters most. Still well under the 1040 ms cap.
+
+### Runtime escape hatch
+
+Ship with a single environment variable / settings flag: **`AUDIO_USE_LEGACY_FEC`**. When set, the entire Opus-tier path reverts to the pre-PRD behavior: RaptorQ re-enabled at the old ratios, Opus inband FEC re-enabled, DRED disabled (`set_dred_duration(0)`). This is the rollback safety valve for the first production window.
+
+Escape hatch semantics:
+- Read once at `CallEncoder::new` / `CallDecoder::new` time. Call-scoped, not re-read mid-call.
+- Exposed via Android Settings UI as a hidden "Legacy FEC (debug)" toggle, and as a CLI flag `--legacy-fec` on the desktop client.
+- Logged in `DebugReporter` so we can tell which mode a call was in when diagnosing.
+- Removed entirely after 2 months of stable production with no regressions reported. Removal is a follow-up PR, not part of this PRD's scope.
+
+## Detailed design
+
+### Phase 0 — FFI crate swap (prerequisite, no behavior change)
+
+**Files touched:**
+- `Cargo.toml` (workspace root) — replace `audiopus = "0.3.0-rc.0"` with `opusic-c = { version = "1.5.5", features = ["bundled", "dred"] }` and `opusic-sys = { version = "0.6.0", features = ["bundled"] }`. The `opusic-sys` direct dep is for the DRED decoder path below.
+- `crates/wzp-codec/Cargo.toml` — update `audiopus = { workspace = true }` to `opusic-c = { workspace = true }`, add `opusic-sys = { workspace = true }`, add `bytemuck = "1"` for the i16↔u16 slice cast.
+- `crates/wzp-codec/src/opus_enc.rs` — rewrite against opusic-c. API mapping:
+ - `audiopus::coder::Encoder::new(SampleRate::Hz48000, Channels::Mono, Application::Voip)` → `opusic_c::Encoder::new(Channels::Mono, SampleRate::Hz48000, Application::Voip)` (argument order swapped)
+ - `set_bitrate(Bitrate::BitsPerSecond(bps))` → `set_bitrate(Bitrate::Bits(bps))` or equivalent variant — verify at implementation time
+ - `set_inband_fec(true/false)` → `set_inband_fec(InbandFec::On/Off)` (now an enum)
+ - `set_packet_loss_perc(u8)` → `set_packet_loss(u8)` (method renamed)
+ - `set_dtx(bool)`, `set_signal(Signal::Voice)`, `set_complexity(u8)` — names match
+ - `encode(&[i16], &mut [u8])` → `encode_to_slice(&[u16], &mut [u8])` with `bytemuck::cast_slice::(pcm)` at the call site
+- `crates/wzp-codec/src/opus_dec.rs` — same-style rewrite for the `Decoder` path. Note that opusic-c's decoder methods take `decode_fec: bool` as a parameter directly (not a separate ctl).
+- `vendor/audiopus_sys/` — delete the directory (only exists on `feat/desktop-audio-rewrite`, not on `android-rewrite`, so this is a no-op on the current branch but do remove the `[patch.crates-io]` block from Cargo.toml when merging back).
+
+**Acceptance criteria:**
+- `cargo check --workspace` passes on Linux x86_64, macOS, and Android NDK cross-compile.
+- All existing codec unit tests in `crates/wzp-codec/src/adaptive.rs` pass unchanged. DRED is still disabled at this phase (default `set_dred_duration(0)`), so behavior is equivalent to pre-swap libopus 1.3 for call quality purposes.
+- A short real-call smoke test produces audio identical to current behavior (no audible regression).
+- `opusic_c::version()` at startup logs libopus version containing `1.5.2` — hard signal that the swap landed correctly.
+
+### Phase 1 — DRED encoder enable on all Opus profiles
+
+**Files touched:**
+- `crates/wzp-codec/src/opus_enc.rs`:
+ - Add `fn dred_duration_for(codec: CodecId) -> u8` returning the per-profile value from the matrix above (10 / 20 / 50 frames).
+ - In `OpusEncoder::new`, after the existing `set_bitrate`/`set_signal`/`set_complexity` block: call `inner.set_inband_fec(InbandFec::Off)`, then `inner.set_dred_duration(dred_duration_for(profile.codec))`, then `inner.set_packet_loss(5)` as the default floor.
+ - Add `pub fn set_dred_duration(&mut self, frames: u8)` to allow the adaptive ladder to update DRED duration on profile switch.
+ - In the existing `set_profile` impl, call `set_dred_duration(dred_duration_for(profile.codec))` after `apply_bitrate`.
+- `crates/wzp-codec/src/adaptive.rs`:
+ - `AdaptiveEncoder::set_profile` already delegates to `self.opus.set_profile` — no changes needed. DRED update rides along.
+- `crates/wzp-client/src/call.rs` (and equivalent on `wzp-android/src/pipeline.rs`):
+ - In the `QualityReport` handler (wherever we currently call `set_expected_loss` / `set_packet_loss_perc`), also ensure the loss value is floored at 5% before passing to the Opus encoder. This is a 1-line change.
+
+**Acceptance criteria:**
+- Encoder produces DRED-enabled Opus packets. Verifiable via libopus's reference decoder in debug mode, or by wire capture + inspection — a DRED-bearing Opus packet has a larger `opus_packet_get_nb_frames` footprint than a non-DRED one of the same nominal bitrate.
+- Total outgoing bitrate on Opus 24k is ~25 kbps (up from ~24 kbps) — confirms ~1 kbps DRED overhead.
+- On a lossless path, decoder output is audibly identical to Phase 0.
+- Escape hatch `AUDIO_USE_LEGACY_FEC=1` cleanly reverts the DRED enable (calls `set_dred_duration(0)` and `set_inband_fec(InbandFec::On)` instead).
+
+### Phase 2 — RaptorQ removal on Opus tiers
+
+**Files touched:**
+- `crates/wzp-client/src/call.rs`:
+ - In `CallEncoder::encode_frame` (or wherever `wzp_fec::Encoder::add_source_symbol` is called), gate the RaptorQ path on `!profile.codec.is_opus()` — Opus frames go straight to DATAGRAM emit, Codec2 frames continue through RaptorQ.
+ - When a profile switch crosses the Opus↔Codec2 boundary, flush/reset the RaptorQ encoder state.
+- `crates/wzp-android/src/pipeline.rs`:
+ - Mirror the same gate in the Android encode path.
+- `crates/wzp-proto/src/packet.rs`:
+ - `MediaHeader.fec_block` and `fec_symbol` are still valid fields on the wire. For Opus packets we emit `fec_block = 0`, `fec_symbol = 0`, `fec_ratio_encoded = 0`. No wire format change; the receiver just sees all-zeros in the FEC fields for Opus packets and skips the FEC decoder path.
+ - Bump protocol version to v1 → v2? **No** — the change is semantically backward compatible because existing RaptorQ decoders handle a zero ratio correctly (ratio 0.0 means "no repair symbols expected"). Old receivers can still decode new Opus packets; they just won't see any DRED benefit because their libopus is old. This is a property we want: the opposite (new receiver, old sender) is the more common mixed-version case during rollout and also Just Works.
+- `crates/wzp-client/src/call.rs` — `CallDecoder`:
+ - Symmetric change: Opus frames bypass the RaptorQ block assembly, go straight to the decoder. Only Codec2 frames (`codec_id.is_codec2()`) feed through `wzp-fec` block decoding.
+
+**Acceptance criteria:**
+- Outgoing Opus packets have `fec_ratio_encoded == 0` (verifiable with the existing wire capture tooling in `wzp-client/src/echo_test.rs`).
+- On a clean network, receiver latency (measured as encode-to-playout one-way delay) drops by ~40 ms versus Phase 1. This is the primary win and should be directly measurable with the existing telemetry.
+- Codec2 calls show no latency change and no packet-format change. Regression-test Codec2 3200 and Codec2 1200 specifically.
+- Total outgoing bitrate on Opus 24k drops from ~28.8 kbps (24k base + 0.2 RaptorQ ratio) to ~25 kbps (24k base + ~1 kbps DRED). Direct savings observable in network telemetry.
+
+### Phase 3 — DRED reconstruction wrapper + jitter buffer lookahead/backfill refactor
+
+This phase is larger than originally estimated because opusic-c's decoder-side DRED wrapper is unusable for our architecture (see Background). We write our own safe wrapper over `opusic-sys` raw FFI first, then plumb it through the jitter buffer.
+
+**Step 3a — Safe DRED reconstruction wrapper in `wzp-codec`:**
+
+New file `crates/wzp-codec/src/dred_ffi.rs`. Wraps the raw libopus 1.5 DRED API:
+
+- `pub struct DredState` — owns an `OpusDRED` buffer (allocated via `opusic_sys::opus_dred_alloc` or equivalent; size is fixed at 10,592 bytes per libopus 1.5). `Clone` is intentionally NOT implemented — the state is heap-owned and non-trivial to copy.
+- `pub fn parse_from_packet(&mut self, decoder: &opusic_c::Decoder, packet: &[u8], max_dred_samples: i32) -> Result` — wraps `opus_dred_parse`, preserves the `dred_end` output (number of samples of history the packet carried), returns it in `DredParseResult { samples_available: i32, frames_available: u8 }`.
+- `pub fn reconstruct_into(&self, decoder: &mut opusic_c::Decoder, dred_offset_samples: i32, output: &mut [i16]) -> Result` — wraps `opus_decoder_dred_decode`, takes the offset explicitly, decodes `output.len()` samples starting from that offset in the DRED window.
+- All `unsafe` contained here, strict bounds checking on offsets, Rust-level panic safety. Unit tests use a reference encoder + known-good reference decoder to verify that reconstruction at specific offsets produces expected output.
+- Depends on `opusic-sys` directly and on `opusic-c::Decoder` for the decoder handle. The Decoder handle must be reachable as a raw pointer; opusic-c exposes this via an unstable internal or we wrap the pointer ourselves. **Verify at implementation time** — if opusic-c doesn't expose the raw decoder pointer safely, we create our own thin Decoder wrapper in `dred_ffi.rs` using raw opusic-sys, losing the convenience of opusic-c's decoder but keeping its encoder. This is the smaller-risk fallback.
+
+New `pub trait DredReconstructor` in `wzp-codec/src/lib.rs`:
+```rust
+pub trait DredReconstructor: Send {
+ /// Parse DRED state from an arriving Opus packet into `state`.
+ /// Returns number of 48 kHz samples of history available, or 0 if the packet has no DRED.
+ fn parse(&mut self, state: &mut DredState, packet: &[u8]) -> Result;
+
+ /// Reconstruct `output.len()` samples from `state`, starting at the given
+ /// sample offset (measured from the end of the DRED window going backward).
+ fn reconstruct(&mut self, state: &DredState, offset_samples: i32, output: &mut [i16]) -> Result;
+}
+```
+
+Implement `DredReconstructor` over the `dred_ffi::DredState` + opusic-c Decoder combination. This is the clean boundary the jitter buffer will talk to.
+
+**Step 3b — Jitter buffer refactor in `crates/wzp-transport/src/jitter.rs`:**
+
+- Current behavior: buffer waits a fixed number of frames of jitter before emitting; on a missing slot, after a timeout it gives up and signals the decoder to run `decode_lost()` (classical Opus PLC or Codec2 PLC).
+- New behavior on Opus tiers: when a frame arrives (in-order or late), first call `DredReconstructor::parse` on it to update a rolling ring of `DredState` instances tagged with their originating sequence number. When a gap is detected (missing sequence number between last-emitted and current arrival), and the ring contains a `DredState` from a nearby packet that covers the gap's sample offset, call `DredReconstructor::reconstruct` with the correct offset to synthesize the missing frames, splice them into playout, then continue normal decode.
+- If no DRED state covers the gap (e.g., gap too far back, or every nearby packet was dropped), fall through to classical PLC exactly as today. The classical path stays intact as the ultimate fallback.
+- Codec2 packets bypass the entire DRED ring. They are not inspected for DRED state and take the unchanged classical PLC path.
+- Ring sizing: `max_dred_duration_frames` + `jitter_depth_frames` worth of `DredState` instances. At 500 ms DRED on degraded tier + 60 ms jitter depth, that's ~28 DredState instances × 10,592 bytes ≈ 300 KB. Acceptable. On studio tier with 100 ms DRED it's only ~80 KB.
+- The jitter buffer takes a `Box` at construction, passed in by the call engine. `wzp-transport` does NOT take a direct dep on `opusic-c` or `opusic-sys` — it only knows about the trait defined in `wzp-codec`.
+
+**Files touched:**
+- `crates/wzp-codec/src/dred_ffi.rs` (new, ~150–300 lines)
+- `crates/wzp-codec/src/lib.rs` — expose `DredReconstructor`, `DredState`, `DredError` types
+- `crates/wzp-codec/Cargo.toml` — add `opusic-sys = { workspace = true }` as a direct dep (already done in Phase 0)
+- `crates/wzp-transport/src/jitter.rs` — lookahead/backfill refactor, DRED ring
+- `crates/wzp-transport/Cargo.toml` — add `wzp-codec = { workspace = true }` (likely already present) for the trait import
+- `crates/wzp-client/src/call.rs` — construct a `DredReconstructor` and pass into `CallDecoder`'s jitter buffer
+- `crates/wzp-android/src/pipeline.rs` — same on Android
+
+**Acceptance criteria:**
+- Unit tests in `dred_ffi.rs`: round-trip a known speech waveform through an encoder with DRED enabled, parse the resulting packets, reconstruct at several different offsets, verify the reconstructed samples are within an energy/spectral threshold of the original. (Not bit-exact — DRED reconstruction is lossy by design.)
+- Synthetic loss test on the full pipeline: inject 200 ms bursts at 10% rate into a looped call, verify the DRED reconstruction rate on receiver telemetry is ≥95% of all loss events whose gaps fall within the configured DRED duration window.
+- Reconstructed audio is audibly continuous on 40–200 ms bursts — no gaps, no classical-PLC robot artifact. Verified on real voice samples (not just sine tones), and on at least two distinct speaker profiles (male, female) because DRED can have voice-dependent quality.
+- End-to-end latency metric is unchanged versus Phase 2 (no regression from adding the lookahead path). The DRED ring insertion on packet arrival must be O(1) in practice.
+- Existing `echo_test.rs` and `drift_test.rs` pass with the new jitter buffer.
+- Codec2 path uses classical PLC exclusively (no DRED invocation) because Codec2 packets don't carry DRED state. Verify by injecting loss on a Codec2 call and confirming zero DRED reconstruction telemetry events during that call.
+- `wzp-transport` has no direct dependency on `opusic-sys` or `opusic-c` in its `Cargo.toml` after the refactor — only on `wzp-codec`. Verify by grepping the Cargo.toml file.
+
+### Phase 4 — Telemetry and tooling updates
+
+**Files touched:**
+- `crates/wzp-proto/src/packet.rs` — `QualityReport` or equivalent telemetry message gains `dred_reconstructions: u32` as a new counter (frames reconstructed via DRED this reporting window) and `classical_plc_invocations: u32` (frames filled by Opus/Codec2 classical PLC). These are separate counters because they're different recovery mechanisms.
+- `crates/wzp-relay/src/*` — relay telemetry pipeline surfaces both counters in Prometheus metrics: `wzp_dred_reconstructions_total{call_id}`, `wzp_classical_plc_total{call_id}`.
+- `docs/grafana-dashboard.json` — new panel: "Loss recovery breakdown" stacked bar, DRED vs classical PLC vs clean decode, per call.
+- `android/app/src/main/java/com/wzp/debug/DebugReporter.kt` — surfaces `dredReconstructions` and `classicalPlc` counts in the debug report; also logs active DRED duration and whether legacy-FEC mode is engaged.
+
+**Acceptance criteria:**
+- Grafana dashboard shows a clear visual distinction between DRED-recovered and classical-PLC-recovered frames across a test fleet of calls.
+- Debug report includes the active protection mode ("DRED 200 ms" / "Legacy RaptorQ") and reconstruction counts, so incidents can be classified unambiguously.
+
+### Phase 5 — Escape hatch removal (follow-up, ~2 months post-ship)
+
+After 2 months of stable production with no rollbacks triggered:
+- Delete `AUDIO_USE_LEGACY_FEC` handling in `opus_enc.rs` / `call.rs` / `pipeline.rs`
+- Delete the Opus-tier paths of `wzp-fec` (the crate stays for Codec2)
+- Delete the Android settings toggle and desktop CLI flag
+- Remove the `--legacy-fec` path from smoke tests
+
+## Critical files to modify (summary)
+
+- `Cargo.toml` (workspace) — dep swap (audiopus → opusic-c + opusic-sys)
+- `crates/wzp-codec/Cargo.toml` — dep swap + `bytemuck` for slice cast
+- `crates/wzp-codec/src/opus_enc.rs` — opusic-c rewrite + DRED enable + inband FEC off
+- `crates/wzp-codec/src/opus_dec.rs` — opusic-c rewrite
+- `crates/wzp-codec/src/dred_ffi.rs` — **new file**, safe wrapper over opusic-sys raw DRED FFI
+- `crates/wzp-codec/src/lib.rs` — expose `DredReconstructor` trait, `DredState`, `DredError`
+- `crates/wzp-codec/src/adaptive.rs` — verify profile switch carries DRED duration
+- `crates/wzp-client/src/call.rs` — Opus/Codec2 gate on RaptorQ path, loss floor, wire DredReconstructor into CallDecoder
+- `crates/wzp-android/src/pipeline.rs` — same gate, same loss floor, wire DredReconstructor
+- `crates/wzp-transport/src/jitter.rs` — lookahead/backfill refactor, DRED ring, reconstruction dispatch
+- `crates/wzp-transport/Cargo.toml` — verify it depends only on `wzp-codec`, not directly on opusic-*
+- `crates/wzp-proto/src/packet.rs` — new telemetry counters
+- `crates/wzp-relay/` — Prometheus metric exposure
+- `android/app/src/main/java/com/wzp/debug/DebugReporter.kt` — debug output
+- `docs/grafana-dashboard.json` — loss-recovery panel
+- (delete) `vendor/audiopus_sys/` on `feat/desktop-audio-rewrite` when merging back
+
+## Existing utilities to reuse
+
+- `wzp_codec::resample::Downsampler48to8` / `Upsampler8to48` — unchanged, only Codec2 path uses them
+- `wzp_codec::adaptive::AdaptiveEncoder` / `AdaptiveDecoder` — existing profile-switching machinery, DRED duration changes ride along
+- `wzp_codec::silence::SilenceDetector` / `ComfortNoise` — unchanged
+- `wzp_codec::agc::AutoGainControl` — unchanged, runs before encode as today
+- `wzp_fec::RaptorQFecEncoder` / decoder — unchanged, still used for Codec2 tiers
+- `wzp_client::call::QualityAdapter` — unchanged; drives profile switching, which now also reconfigures DRED duration via the existing `set_profile` path
+
+## Verification
+
+End-to-end testing, in order:
+
+1. **Unit**: `cargo test -p wzp-codec` — Opus encode/decode round-trip at every profile, DRED enabled. Verify `version()` reports libopus 1.5.2.
+2. **Unit**: `cargo test -p wzp-transport` — jitter buffer lookahead/backfill behavior with injected loss patterns (0%, 5%, 15%, 30%, 50% loss; isolated losses, 40 ms bursts, 200 ms bursts, 500 ms bursts).
+3. **Integration**: `crates/wzp-client/src/echo_test.rs` — existing echo test must pass on all Opus profiles with <5% perceived quality regression (measure via the time-window analysis already built into `echo_test.rs`).
+4. **Integration**: `crates/wzp-client/src/drift_test.rs` — latency measurement. Must show ~40 ms reduction on Opus profiles versus pre-PRD baseline. Codec2 profiles unchanged.
+5. **Manual**: Android release build, real call over bad wifi (or a shaped network via `tc netem` on Linux). Burst losses of 200 ms should be perceptually continuous speech, not robotic gaps.
+6. **Manual**: Same call with `AUDIO_USE_LEGACY_FEC=1` — verify behavior reverts to current production behavior. This is the pre-ship rollback rehearsal.
+7. **Cross-compile**: full build matrix — Android arm64-v8a + armeabi-v7a (via `scripts/build-and-notify.sh`), macOS universal, Linux x86_64 (via `scripts/build-linux-docker.sh`). Windows cross-compile via cargo-xwin should also pass — libopus 1.5 upstream fixed the clang-cl SIMD issue that required the vendor patch on `feat/desktop-audio-rewrite`.
+8. **Telemetry smoke**: deploy to staging relay, make 10 test calls, verify Grafana's new "Loss recovery breakdown" panel shows DRED reconstruction events firing on injected loss and classical-PLC on packet-loss beyond DRED's window.
+
+## Risks and mitigations
+
+- **Custom DRED FFI wrapper is WZP-maintained code with no second source.** opusic-c's decoder-side DRED wrapper is insufficient (see Background), so we carry our own `dred_ffi.rs` that calls `opus_dred_parse` and `opus_decoder_dred_decode` directly via opusic-sys. Bugs in this wrapper — offset arithmetic off-by-ones, lifetime errors on `OpusDRED` buffers, UB from misuse of the C API — could manifest as silent audio corruption on loss bursts, hard to diagnose. **Mitigation**: extensive unit tests in `dred_ffi.rs` using a reference encoder + reference decoder round-trip with known offsets; strict bounds checking on every `unsafe` boundary; Miri run in CI if feasible; the legacy-FEC escape hatch disables the entire DRED code path including our custom wrapper, giving us a single flag to revert any wrapper bug in production. Long-term: upstream the fixes to opusic-c (follow-up task, not blocking).
+- **opusic-c's encoder-side API and internal Decoder pointer access**. Step 3a depends on being able to call opusic-sys raw functions that take an `*mut OpusDecoder` pointer while still using opusic-c's `Decoder` for normal decode. If opusic-c doesn't expose the raw pointer cleanly, we fall back to a thin opusic-sys-direct Decoder wrapper inside `dred_ffi.rs` and lose some of opusic-c's convenience. **Mitigation**: verify at the start of Phase 3 (one afternoon of reading opusic-c source). If the clean path doesn't work, the fallback is not difficult — it's what we'd have built anyway if opusic-c didn't exist.
+- **DRED reconstruction quality varies by voice / content**. The neural model is trained on speech; edge cases (shouting, whispering, heavy accents, music-on-hold, cough, laughter) may reconstruct less cleanly than continuous speech. **Mitigation**: escape hatch ships from day one. If production telemetry shows perceptible quality regression on specific voice patterns, flip legacy mode for affected users while tuning. Also: classical Opus PLC remains as the third-tier fallback when DRED state is unavailable.
+- **Removing RaptorQ removes bit-exact recovery**. Isolated single-packet losses are now reconstructed plausibly instead of bit-exactly. **Mitigation**: as argued in Background, bit-exactness on a single 20 ms speech frame is perceptually meaningless. The assumption is "speech is the workload" — if we ever add non-speech features (music bot, ringtones over the call path, DTMF-over-audio) we revisit.
+- **libopus 1.5 DRED API stability**. **Verified at pre-flight**: opus.h in the upstream xiph/opus repository has no "experimental" marker on the DRED API declarations. The earlier characterization was incorrect. DRED shipped as a first-class feature in libopus 1.5.0 (Dec 2023) and has been iterated in 1.5.1 and 1.5.2. Google Meet and Duo ship it at scale. **Mitigation**: pin `opusic-sys` exactly (no `^` range) to ensure reproducible builds, follow upstream 1.5.x bugfixes as they land. No special stability concerns beyond normal dependency hygiene.
+- **Jitter buffer refactor is the largest code change**. Jitter bugs are notoriously subtle (off-by-one on sequence wraparound, clock drift interactions, playout starvation corner cases). **Mitigation**: keep the classical-PLC path intact as the DRED fallback, so jitter bugs degrade to "current behavior" rather than "broken audio". Write targeted unit tests for the buffer at each loss-pattern scenario before touching production paths. Consider shipping Phase 3 behind a sub-flag separate from the main escape hatch, so we can independently toggle "DRED enabled but classical jitter buffer" for bisection.
+- **Cross-compile surprises**. `opusic-sys` is actively maintained but our exact combination of Android NDK version / Docker builder environment / Windows cross-compile via cargo-xwin has not been tested by upstream. **Mitigation**: Phase 0 includes the full cross-compile matrix as an acceptance criterion. Any blockers surface before we touch loss-recovery behavior.
+- **Wire-format compatibility during rollout**. Mixed-version calls (new sender + old receiver, or vice versa) need to keep working. **Verified at pre-flight**: traced both live receive paths (`wzp-client/src/call.rs::CallDecoder::ingest` and `wzp-android/src/engine.rs` the JNI-driven engine path), and both degrade gracefully: new-sender Opus packets with `fec_ratio_encoded=0` / `fec_block=0` / `fec_symbol=0` flow through to the jitter buffer and decode normally on old receivers. The RaptorQ decoder either ignores zero-FEC packets entirely (Android pipeline.rs gates on non-zero fec_block/fec_symbol) or accumulates them harmlessly until the 2-second staleness eviction (desktop call.rs). Old-sender packets with populated RaptorQ fields are handled by new receivers via the unchanged Codec2 path (new receivers keep wzp-fec for Codec2 tiers and simply ignore RaptorQ fields on Opus packets). **No wire format version bump required.**
+- **Pre-existing desktop RaptorQ gap** (incidental finding, NOT caused by this PRD). The desktop `wzp-client/src/call.rs::CallDecoder` feeds packets into `fec_dec.add_symbol` but **never calls `fec_dec.try_decode`** — RaptorQ recovery is effectively dead code on the desktop path today. Main decode reads from the jitter buffer directly, falling through to classical Opus PLC on missing packets. The Android `engine.rs` path properly uses `try_decode` for recovery. This PRD does not fix the desktop gap — it's unrelated — but is noted here so nobody is surprised that removing RaptorQ from Opus tiers on the desktop client causes no measurable recovery regression (there was nothing to lose). Recommend filing a follow-up task to either fix or remove the vestigial desktop RaptorQ wiring independently of this work.
+- **`AUDIO_USE_LEGACY_FEC` itself becoming permanent tech debt**. Escape hatches have a way of outliving their intended lifespan. **Mitigation**: put an explicit removal date in a `// TODO(2026-06-15): remove legacy FEC path` comment at the flag-handling site. Track in taskmaster.
+
+## Open questions
+
+- ~~**Does opusic-c expose `opusic_c::Decoder`'s raw inner pointer?**~~ **Resolved at pre-flight**: no, it's `pub(crate)`. We build a unified `DecoderHandle` over raw opusic-sys in `dred_ffi.rs` and use it for both normal decode and DRED reconstruction. Opusic-c is used only for the encoder side.
+- **Exact opusic-sys symbol name for DRED decoder allocation**. opus.h documents the `OpusDREDDecoder` type and `opus_dred_parse`/`opus_decoder_dred_decode` functions, but the allocation function name is not in the fetched snippet. Expected to be `opus_dred_decoder_create` / `opus_dred_decoder_destroy` per libopus naming convention, but confirm at the very start of Phase 3a by reading the actual opusic-sys bindings. If the function is not exported by opusic-sys, we file a PR upstream to opusic-sys (small fix, trivially mergeable) and temporarily vendor the function declaration locally.
+- **Should the 5% loss floor be configurable per profile?** Currently specified as a constant. A future refinement might make it higher at degraded tiers and lower at studio tiers, but without real telemetry we don't know if the constant is wrong. Keep as a constant for now, revisit after 1 month of production data.
+- **OSCE enable**: opusic-c has an `osce` feature flag for Opus Speech Coding Enhancement, a separate libopus 1.5 neural post-processor. Out of scope for this PRD but should be the next audio-quality follow-up. Probably one-line enable once opusic-c is in.
+- **Upstream PR to opusic-c**: our own `dred_ffi.rs` wrapper should be proven in production first, then the fixes upstreamed to `opusic-c/src/dred.rs` (preserve `dred_end`, fix `dred_offset` double-pass, expose `DredPacket` externally). Follow-up task, not blocking this PRD.
+- **`feat/desktop-audio-rewrite` merge**: the vendored `audiopus_sys` patch on that branch becomes obsolete under this PRD. Coordinate removal with whoever owns that branch.
+
+## Phase A: Continuous DRED Tuning (Implemented 2026-04-12)
+
+Phase A extends the discrete tier-locked DRED durations from Phases 1-3 with continuous, network-driven tuning.
+
+### What was built
+
+- **`DredTuner`** (`crates/wzp-proto/src/dred_tuner.rs`): Maps `(loss_pct, rtt_ms, jitter_ms)` → `(dred_frames, expected_loss_pct)` continuously
+- **Quinn stats exposure** (`crates/wzp-transport/src/quic.rs`): `QuinnPathSnapshot` provides quinn's internal RTT, loss, congestion events — more accurate than sequence-gap heuristics
+- **Jitter variance window** (`crates/wzp-transport/src/path_monitor.rs`): 10-sample sliding window for RTT standard deviation, used for spike detection
+- **`AudioEncoder` trait extensions** (`crates/wzp-proto/src/traits.rs`): `set_expected_loss()` and `set_dred_duration()` with default no-op, overridden by `OpusEncoder` and `AdaptiveEncoder`
+- **Engine integration** (`desktop/src-tauri/src/engine.rs`): Both Android and desktop send tasks poll every 25 frames and apply tuning
+
+### Opus6k DRED extended
+
+`dred_duration_for(Opus6k)` changed from 50 (500ms) to 104 (1040ms) — the maximum libopus 1.5 supports. The RDO-VAE's quality-vs-offset curve makes this nearly free in bitrate terms while doubling burst resilience on the worst links.
+
+### Jitter spike detection ("Sawtooth" prediction)
+
+When instantaneous jitter exceeds the EWMA × 1.3 (asymmetric: fast-up α=0.3, slow-down α=0.05), the tuner enters spike-boost mode:
+- DRED immediately jumps to the codec tier's ceiling
+- Cooldown: 10 cycles (~5 seconds at 25 packets/cycle)
+- Designed for Starlink satellite handover sawtooth jitter pattern
+
+### Test coverage
+
+- 10 unit tests for tuner math (baseline, scaling, spike, cooldown, codec switch, Codec2 no-op)
+- 4 integration tests (encoder adjustment, spike boost, Codec2 no-op, profile switch with encode verification)
+
+### Opus6k Frame Starvation Bug (Fixed 2026-04-13)
+
+During testing of the extended 1040ms DRED window on Opus6k, the 40ms codec produced only ~11 frames/s instead of 25 — making audio choppy regardless of DRED quality.
+
+**Root cause:** The Android capture ring read loop did partial reads that consumed samples from the ring but discarded them when retrying:
+1. Ring has 960 samples (one Oboe burst)
+2. `audio_read_capture(&mut buf[..1920])` reads 960 into `buf[0..960]`, returns 960
+3. Loop sees 960 < 1920, sleeps, retries from `buf[0..]` → overwrites the consumed samples
+4. ~50% of captured audio thrown away per frame
+
+**Fix:** Added `wzp_native_audio_capture_available()` to check ring fill level before reading (same pattern as the desktop CPAL path's `capture_ring.available()`). Also made `frame_samples` mutable so codec switches update the read size.
+
+**Affected codecs:** Only 40ms frame codecs (Opus6k, Codec2_1200). 20ms codecs (Opus24k, etc.) were unaffected because a single Oboe burst fills the entire request.
diff --git a/vault/PRDs/PRD-engine-dedup.md b/vault/PRDs/PRD-engine-dedup.md
new file mode 100644
index 0000000..5166a03
--- /dev/null
+++ b/vault/PRDs/PRD-engine-dedup.md
@@ -0,0 +1,145 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Engine.rs Deduplication — Extract Shared Send/Recv Helpers
+
+## Problem
+
+`desktop/src-tauri/src/engine.rs` is 1,705 lines with two nearly identical `CallEngine::start()` implementations — one for Android (880 lines) and one for desktop (430 lines). ~350 lines are copy-pasted between them. Every change to the encode/decode/adaptive-quality pipeline requires editing both places, and they've already diverged in subtle ways (Android has extensive first-join diagnostics that desktop lacks).
+
+## Scope
+
+Extract the duplicated logic into shared helper functions. The Android and desktop paths should only differ in their audio I/O mechanism (Oboe ring via wzp-native vs CPAL capture_ring/playout_ring).
+
+## What's Duplicated
+
+| Block | Description | Lines (each) |
+|-------|-------------|------|
+| `build_call_config()` | Resolve quality string → CallConfig | 23 |
+| Codec-to-profile match | Map CodecId → QualityProfile for decoder switch | 19 |
+| Adaptive quality switch | Read AtomicU8, index_to_profile, set_profile, update frame_samples + dred_tuner | 15 |
+| DRED tuner poll | Check frame counter, poll quinn stats, apply tuning | 15 |
+| Quality report ingestion | Extract quality_report, feed to AdaptiveQualityController, store to AtomicU8 | 8 |
+| Signal task | Accept signals, handle RoomUpdate/QualityDirective/Hangup | 48 |
+| **Total** | | **~128 lines × 2 = 256 lines eliminated** |
+
+## Implementation
+
+### Phase 1: Top-Level Helper Functions
+
+```rust
+fn build_call_config(quality: &str) -> CallConfig {
+ let profile = resolve_quality(quality);
+ match profile {
+ Some(p) => CallConfig {
+ noise_suppression: false,
+ suppression_enabled: false,
+ ..CallConfig::from_profile(p)
+ },
+ None => CallConfig {
+ noise_suppression: false,
+ suppression_enabled: false,
+ ..CallConfig::default()
+ },
+ }
+}
+
+fn codec_to_profile(codec: CodecId) -> QualityProfile {
+ match codec {
+ CodecId::Opus24k => QualityProfile::GOOD,
+ CodecId::Opus6k => QualityProfile::DEGRADED,
+ CodecId::Opus32k => QualityProfile::STUDIO_32K,
+ CodecId::Opus48k => QualityProfile::STUDIO_48K,
+ CodecId::Opus64k => QualityProfile::STUDIO_64K,
+ CodecId::Codec2_1200 => QualityProfile::CATASTROPHIC,
+ CodecId::Codec2_3200 => QualityProfile {
+ codec: CodecId::Codec2_3200,
+ fec_ratio: 0.5,
+ frame_duration_ms: 20,
+ frames_per_block: 5,
+ },
+ other => QualityProfile { codec: other, ..QualityProfile::GOOD },
+ }
+}
+
+fn check_adaptive_switch(
+ pending: &AtomicU8,
+ encoder: &mut CallEncoder,
+ tuner: &mut wzp_proto::DredTuner,
+ frame_samples: &mut usize,
+ tx_codec: &tokio::sync::Mutex,
+) -> bool {
+ let p = pending.swap(PROFILE_NO_CHANGE, Ordering::Acquire);
+ if p == PROFILE_NO_CHANGE { return false; }
+ if let Some(new_profile) = index_to_profile(p) {
+ let new_fs = (new_profile.frame_duration_ms as usize) * 48;
+ if encoder.set_profile(new_profile).is_ok() {
+ *frame_samples = new_fs;
+ tuner.set_codec(new_profile.codec);
+ // Caller updates tx_codec display string
+ return true;
+ }
+ }
+ false
+}
+```
+
+### Phase 2: Shared Signal Task
+
+Extract the signal task into a standalone async function:
+
+```rust
+async fn run_signal_task(
+ transport: Arc,
+ running: Arc,
+ pending_profile: Arc,
+ participants: Arc>>,
+) {
+ loop {
+ if !running.load(Ordering::Relaxed) { break; }
+ match tokio::time::timeout(
+ Duration::from_millis(SIGNAL_TIMEOUT_MS),
+ transport.recv_signal(),
+ ).await {
+ Ok(Ok(Some(msg))) => {
+ // Handle RoomUpdate, QualityDirective, Hangup...
+ }
+ _ => {}
+ }
+ }
+}
+```
+
+### Phase 3: Shared DRED Poll + Quality Ingestion
+
+These are small blocks but appear in both send and recv tasks. Extract as inline helpers or closures.
+
+## Verification
+
+1. `cargo check --workspace` — must compile
+2. `cargo test -p wzp-proto -p wzp-relay -p wzp-client --lib` — must pass
+3. Manual test: place a call Android↔Desktop, verify audio works in both directions
+4. Verify adaptive quality still switches (set one side to auto, degrade network)
+
+## Effort
+
+- Phase 1: 1 hour (extract 3 functions, update 6 call sites)
+- Phase 2: 30 min (extract signal task, update 2 spawn sites)
+- Phase 3: 30 min (cleanup remaining small duplicates)
+- Total: ~2 hours
+
+## Not In Scope
+
+- Audio I/O trait abstraction (Oboe vs CPAL) — different project, different risk profile
+- Moving Android-specific diagnostics (first-join, PCM recorder) into a feature flag
+- Splitting engine.rs into multiple files
+
+## Implementation Status (2026-04-13)
+
+All phases implemented:
+- build_call_config(): shared CallConfig construction — DONE
+- codec_to_profile(): shared CodecId → QualityProfile mapping — DONE
+- run_signal_task(): shared signal handler — DONE
+- Net reduction: ~39 lines, 6 duplicated blocks → single-line calls
diff --git a/vault/PRDs/PRD-hard-nat.md b/vault/PRDs/PRD-hard-nat.md
new file mode 100644
index 0000000..406dca3
--- /dev/null
+++ b/vault/PRDs/PRD-hard-nat.md
@@ -0,0 +1,225 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Hard NAT Traversal (Port Prediction + Birthday Attack)
+
+> Phase: Partial implementation
+> Status: Phase A done, Phase B signal ready, C-D not started (2026-04-14)
+> Crate: wzp-client, wzp-proto, wzp-relay
+
+## Problem
+
+When both peers are behind **symmetric NATs** (endpoint-dependent mapping), standard hole-punching fails because the external port changes per destination. Our Phase 8.2 port mapping (NAT-PMP/PCP/UPnP) solves this when the router supports it (~70% of consumer routers), but the remaining ~30% — plus corporate firewalls, cloud NATs (AWS/Azure), and carrier-grade NATs — fall back to relay.
+
+Tailscale tackles this with two techniques:
+1. **Port prediction** for NATs with sequential allocation patterns
+2. **Birthday attack** for NATs with random allocation
+
+Both are viable when **at least one peer has a predictable NAT** (easy+hard pair). When **both** peers have fully random symmetric NATs, even Tailscale falls back to relay.
+
+## Background: How Symmetric NATs Allocate Ports
+
+| Pattern | Behavior | Prevalence | Traversal |
+|---------|----------|------------|-----------|
+| **Sequential** | port N, N+1, N+2... per new flow | ~40% of symmetric NATs (home routers) | Port prediction viable |
+| **Random** | truly random port per flow | ~50% (enterprise, cloud, CGNAT) | Birthday attack only |
+| **Port-preserving** | same as source port when possible | ~10% (behaves like cone NAT) | Standard hole-punch works |
+
+## Solution Overview
+
+### Phase A: NAT Port Allocation Pattern Detection
+
+Before attempting hard NAT traversal, detect whether the NAT allocates ports sequentially or randomly. This determines which strategy to use.
+
+**Method**: Send 5 STUN Binding Requests from the same source socket to 5 different STUN servers. Collect the 5 observed external ports. Analyze:
+
+```
+Ports: [40001, 40002, 40003, 40004, 40005] → Sequential (delta=1)
+Ports: [40001, 40003, 40005, 40007, 40009] → Sequential (delta=2)
+Ports: [40001, 52847, 19432, 61203, 8847] → Random
+Ports: [4433, 4433, 4433, 4433, 4433] → Port-preserving (cone-like)
+```
+
+Classification:
+- All same port → `PortPreserving` (use standard hole-punch)
+- Consistent delta between consecutive ports → `Sequential { delta: i16 }`
+- No pattern → `Random`
+
+**New struct**:
+```rust
+pub enum PortAllocation {
+ PortPreserving,
+ Sequential { delta: i16 },
+ Random,
+ Unknown,
+}
+```
+
+Add to `NetcheckReport` and `NatDetection`.
+
+### Phase B: Port Prediction (Sequential NATs)
+
+When the NAT is sequential, we can **predict** the next external port:
+
+1. Client sends a STUN probe → observes external port P
+2. Client knows the NAT will assign P+delta for the next outbound flow
+3. Client tells peer (via relay or chat): "dial me at `my_ip:(P + delta * N)`" where N is the number of flows the client will open before the peer's packet arrives
+4. Client opens a QUIC connection to the peer's predicted port at the same time
+5. If the prediction lands within a small window, the QUIC handshake succeeds
+
+**Timing is critical**: both peers must probe, predict, and dial within a tight window (~500ms) so the port prediction doesn't drift.
+
+**Coordination via relay** (or out-of-band chat):
+```
+SignalMessage::HardNatProbe {
+ call_id: String,
+ /// My observed port sequence (last 3 ports, most recent first)
+ port_sequence: Vec,
+ /// My detected allocation pattern
+ allocation: PortAllocation,
+ /// Timestamp (ms since epoch) — for synchronization
+ probe_time_ms: u64,
+ /// My external IP (from STUN)
+ external_ip: String,
+}
+```
+
+Both peers exchange `HardNatProbe`, then simultaneously:
+1. Each predicts the other's next port: `peer_ip:(peer_last_port + peer_delta * offset)`
+2. Each opens N parallel QUIC connections to predicted port range: `[predicted - 2, predicted + 2]`
+3. First successful handshake wins
+
+**Expected success rate**: ~80% for sequential NATs with consistent delta, within 2-3 seconds.
+
+### Phase C: Birthday Attack (Random NATs)
+
+When the NAT is random, port prediction is impossible. Instead, exploit the **birthday paradox**:
+
+**Math**: With N ports open on side A and M probes from side B into a 65536-port space:
+- N=256, M=256: P(collision) ≈ 1 - e^(-256*256/65536) ≈ 63%
+- N=256, M=512: P(collision) ≈ 1 - e^(-256*512/65536) ≈ 87%
+- N=256, M=1024: P(collision) ≈ 1 - e^(-256*1024/65536) ≈ 98%
+
+**Implementation**:
+
+1. **Acceptor side** (easy NAT or the side with more ports available):
+ - Open 256 UDP sockets bound to random ports
+ - For each socket, send one STUN probe to learn its external port
+ - Report all 256 external ports to the peer
+
+2. **Dialer side** (hard NAT):
+ - Send 1024 QUIC Initial packets to random ports on the Acceptor's external IP
+ - Rate: 100-200 packets/sec to avoid triggering rate limits
+ - Duration: ~5-10 seconds
+
+3. **Collision detection**:
+ - When one of the Dialer's packets hits one of the Acceptor's open ports, the QUIC handshake begins
+ - The Acceptor sees an incoming Initial on one of its 256 sockets
+
+**Problem for VoIP**: This takes 5-10 seconds even at high probe rates. For a phone call, this means a long "connecting..." phase. Acceptable as a last resort before relay fallback.
+
+### Phase D: Hybrid Strategy
+
+Combine all techniques in a waterfall:
+
+```
+1. Port mapping (NAT-PMP/PCP/UPnP) → <100ms [Phase 8.2, done]
+ ↓ failed
+2. Standard hole-punch (cone NAT) → <500ms [Phase 3-6, done]
+ ↓ failed (symmetric NAT detected)
+3. Port prediction (sequential NAT) → <2s [Phase A+B, new]
+ ↓ failed (random NAT detected)
+4. Birthday attack (one side random) → <10s [Phase C, new]
+ ↓ failed (both sides random)
+5. Relay fallback → always [Phase 1, done]
+```
+
+The relay path starts **immediately in parallel** with all direct attempts (existing 500ms head-start architecture). The user hears audio via relay while the harder traversal techniques probe in the background. If a direct path is found, the call seamlessly upgrades (using the Phase 8.3 transport hot-swap mechanism).
+
+## QUIC-Specific Challenges
+
+### 1. Connection ID Mismatch
+QUIC's Initial packet contains a random Destination Connection ID. When birthday-attack probes land on the Acceptor's socket, the CID won't match any expected value. Quinn handles this via its `Endpoint` which accepts any incoming Initial — but we need to ensure the Endpoint is in server mode on all 256 ports.
+
+**Solution**: Use quinn's `Endpoint` with a server config on each socket. Quinn's accept logic handles unknown CIDs correctly.
+
+### 2. Probe Packet Format
+Birthday attack probes must be valid QUIC Initial packets (not raw UDP). Quinn's `Endpoint::connect()` sends a proper Initial, so each probe is a real connection attempt. Failed probes time out naturally.
+
+### 3. Stateful Connections
+Unlike WireGuard (stateless), each QUIC probe creates connection state. With 1024 probes, that's 1024 half-open connections. Must aggressively abort losers once one succeeds.
+
+**Solution**: Use `JoinSet` (existing pattern in `dual_path.rs`) and `abort_all()` on first success.
+
+### 4. NAT Pinhole Lifetime
+QUIC Initial retransmission timer (1s default) may exceed the NAT pinhole lifetime on aggressive NATs. One probe per port may not be enough.
+
+**Solution**: Send 2-3 Initials per predicted port, 200ms apart.
+
+## Signal Protocol
+
+New variants:
+
+```rust
+/// Hard NAT probe coordination — exchanged before birthday attack.
+HardNatProbe {
+ call_id: String,
+ /// Last 5 observed external ports (most recent first).
+ port_sequence: Vec,
+ /// Detected allocation pattern.
+ allocation: String, // "sequential:1", "sequential:2", "random", "preserving"
+ /// Probe timestamp for synchronization (ms since epoch).
+ probe_time_ms: u64,
+ /// External IP from STUN.
+ external_ip: String,
+}
+
+/// Hard NAT birthday attack coordination.
+HardNatBirthdayStart {
+ call_id: String,
+ /// Number of ports opened by the acceptor side.
+ acceptor_port_count: u16,
+ /// External ports the acceptor has open (for targeted probing).
+ /// Only sent if port_count is small enough to enumerate.
+ acceptor_ports: Vec,
+ /// "start probing now" timestamp.
+ start_at_ms: u64,
+}
+```
+
+## Integration with Existing Architecture
+
+- **Netcheck**: `NetcheckReport` gains `port_allocation: PortAllocation` field
+- **IceAgent**: `gather()` includes port allocation detection; `re_gather()` re-probes on network change
+- **dual_path**: `race()` extended with hard-NAT probe phase between standard hole-punch timeout and relay commitment
+- **Desktop**: `place_call` / `answer_call` exchange `HardNatProbe` when both sides report `SymmetricPort` NAT type
+
+## Effort Estimate
+
+| Phase | Scope | Effort | Status |
+|-------|-------|--------|--------|
+| A | Port allocation pattern detection | 1 day | **Done** — `PortAllocation` enum, `detect_port_allocation()`, `classify_port_allocation()`, `predict_ports()`, 17 tests |
+| B | Sequential port prediction + coordination | 2 days | **Signal ready** — `HardNatProbe` signal + relay forwarding done. `dual_path::race()` integration pending |
+| C | Birthday attack (256 sockets + 1024 probes) | 3 days | Not started |
+| D | Hybrid waterfall + background upgrade | 2 days | Not started |
+
+**Total**: ~8 days. Phase A is done and feeds into netcheck. Phase B has signal plumbing complete — needs `dual_path::race()` integration to actually dial predicted ports. Phase C (birthday) is the most complex and lowest ROI.
+
+## Success Criteria
+
+- Port allocation detection correctly classifies sequential vs random on test routers
+- Sequential port prediction achieves >70% direct connection rate on sequential-NAT routers
+- Birthday attack achieves >90% within 10 seconds when one peer has cone NAT
+- Relay-to-direct upgrade is seamless (no audio gap) via Phase 8.3 transport hot-swap
+- No regression in call setup time for cone-NAT pairs (the common case)
+
+## References
+
+- [Tailscale: How NAT traversal works](https://tailscale.com/blog/how-nat-traversal-works)
+- [Tailscale: NAT traversal improvements pt.1](https://tailscale.com/blog/nat-traversal-improvements-pt-1)
+- [Tailscale: NAT traversal improvements pt.2 — cloud environments](https://tailscale.com/blog/nat-traversal-improvements-pt-2-cloud-environments)
+- RFC 4787: NAT Behavioral Requirements for Unicast UDP
+- RFC 5245: ICE (Interactive Connectivity Establishment)
+- Birthday problem: P(collision) = 1 - e^(-n²/2m) where n=probes, m=port space
diff --git a/vault/PRDs/PRD-ice-regather.md b/vault/PRDs/PRD-ice-regather.md
new file mode 100644
index 0000000..7db153b
--- /dev/null
+++ b/vault/PRDs/PRD-ice-regather.md
@@ -0,0 +1,121 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Mid-Call ICE Re-Gathering
+
+> Phase: Implemented (signal plane); transport hot-swap deferred
+> Status: Partial (2026-04-14)
+> Crate: wzp-client, wzp-proto, wzp-relay
+
+## Problem
+
+When a mobile device transitions between networks (WiFi -> cellular, IP address change), the active QUIC connection dies. The call stays on a dead path until timeout, then the user experiences silence. There is no mechanism to re-discover candidates and re-establish a direct path mid-call.
+
+Android's `NetworkMonitor.onIpChanged` already fires on `onLinkPropertiesChanged`, but nothing consumes it for candidate re-gathering or path migration.
+
+## Solution
+
+Implement an `IceAgent` that manages the full candidate lifecycle — initial gathering, mid-call re-gathering on network change, and peer candidate application. A new `CandidateUpdate` signal message carries refreshed candidates to the peer through the relay.
+
+## Implementation
+
+### New Module: `crates/wzp-client/src/ice_agent.rs`
+
+**IceAgent struct**:
+- Owns `IceAgentConfig` (STUN config, portmap toggle, gather timeout, local ports)
+- Monotonic `generation: AtomicU32` — incremented on each re-gather, peers reject stale updates
+- `peer_generation: AtomicU32` — tracks last-seen peer generation for ordering
+
+**Public API**:
+- `gather()` -> `CandidateSet` — runs STUN + portmap + host candidates in parallel with timeout
+- `re_gather()` -> `(CandidateSet, SignalMessage)` — increments generation, returns update to send
+- `apply_peer_update(signal)` -> `Option` — parses `CandidateUpdate`, rejects if generation <= last-seen
+
+**CandidateSet**:
+```rust
+pub struct CandidateSet {
+ pub reflexive: Option,
+ pub local: Vec,
+ pub mapped: Option,
+ pub generation: u32,
+}
+```
+
+### New Signal: `CandidateUpdate`
+
+```rust
+CandidateUpdate {
+ call_id: String,
+ reflexive_addr: Option,
+ local_addrs: Vec,
+ mapped_addr: Option,
+ generation: u32,
+}
+```
+
+- All address fields use `#[serde(default, skip_serializing_if)]` for backward compat
+- Generation counter is mandatory — prevents stale updates from network reordering
+
+### Relay Forwarding
+
+`CandidateUpdate` is forwarded to the call peer using the same pattern as `MediaPathReport`:
+1. Look up peer fingerprint + `peer_relay_fp` from `CallRegistry`
+2. If cross-relay: wrap in `FederatedSignalForward` and forward via federation link
+3. If local: send via `signal_hub.send_to()`
+
+### Desktop Handling
+
+Signal recv loop handles `CandidateUpdate`:
+- Logs generation, reflexive, mapped, local count
+- Emits `recv:CandidateUpdate` debug event
+- Emits `signal-event` type `candidate_update` to JS frontend
+- TODO: wire into `IceAgent.apply_peer_update()` + `race_upgrade()` for transport hot-swap
+
+### Deferred: Transport Hot-Swap
+
+The actual mid-call transport replacement is not yet wired. The designed approach:
+- `Arc>>` — send/recv tasks clone inner Arc per frame
+- On upgrade, swap inner Arc under write lock — next frame picks up new transport
+- Android: `pending_ice_regather: AtomicBool` polled in recv task, triggers re-gather + swap
+- Requires live testing to validate seamless audio continuity during swap
+
+## Signal Flow
+
+```
+Network change (WiFi -> cellular)
+ |
+ v
+IceAgent::re_gather()
+ |-- stun::discover_reflexive()
+ |-- portmap::acquire_port_mapping()
+ |-- local_host_candidates()
+ |
+ v
+SignalMessage::CandidateUpdate { generation: N+1 }
+ |
+ v (via relay)
+Peer IceAgent::apply_peer_update()
+ |
+ v
+PeerCandidates { reflexive, local, mapped }
+ |
+ v
+dual_path::race() with new candidates [NOT YET WIRED]
+```
+
+## Files
+
+| File | Change |
+|------|--------|
+| `crates/wzp-client/src/ice_agent.rs` | New — IceAgent + CandidateSet |
+| `crates/wzp-proto/src/packet.rs` | `CandidateUpdate` variant |
+| `crates/wzp-relay/src/main.rs` | Forward `CandidateUpdate` to peer |
+| `crates/wzp-client/src/featherchat.rs` | Map `CandidateUpdate` to `IceCandidate` type |
+| `desktop/src-tauri/src/lib.rs` | Handle `CandidateUpdate` in signal recv loop |
+
+## Testing
+
+- 10 unit tests: generation monotonicity, apply_peer_update (all fields, empty fields, unparseable addrs, stale rejection, wrong signal type), default config, gather with no STUN, re_gather produces signal with incrementing generation
+- 2 protocol roundtrip tests: CandidateUpdate full + minimal
diff --git a/vault/PRDs/PRD-local-recording.md b/vault/PRDs/PRD-local-recording.md
new file mode 100644
index 0000000..b421dac
--- /dev/null
+++ b/vault/PRDs/PRD-local-recording.md
@@ -0,0 +1,146 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Local Recording + Cloud Mixer for Podcast-Quality Interviews
+
+## Problem
+
+WarzonePhone delivers real-time encrypted voice, but the audio quality is limited by network conditions (codec compression, packet loss, jitter). Podcasters and interviewers need pristine, studio-grade recordings of each participant — independent of what the network delivers.
+
+## Solution
+
+**Dual-path architecture**: each client simultaneously (1) participates in the live call at whatever codec quality the network supports, and (2) records their own microphone locally as lossless PCM. After the session, all local recordings are uploaded to a self-hosted mixer service that aligns, normalizes, and outputs a final multi-track or mixed file.
+
+## Architecture
+
+```
+ ┌──────────────────┐
+ Mic ──┬── Opus/Codec2 ──► Network (live) │ ← real-time call
+ │ └──────────────────┘
+ │
+ └── WAV 48kHz ────► Local File │ ← pristine recording
+ (timestamped)
+ │
+ ▼ (after hangup)
+ ┌──────────────────┐
+ │ Mixer Service │ ← self-hosted
+ │ (align + mix) │
+ └──────────────────┘
+ │
+ ▼
+ Final MP3/WAV/FLAC
+```
+
+## Requirements
+
+### Phase 1: Local Recording (MVP)
+
+**All clients (Desktop, Android, Web):**
+
+1. **Record toggle**: User can enable "Record this call" before or during a call
+2. **Recording pipeline**: Tap raw PCM from the microphone capture path *before* it enters the codec encoder
+3. **File format**: WAV (48kHz, 16-bit, mono) — simple, universally supported, lossless
+4. **Sync markers**: Embed a monotonic timestamp (ms since call start) at the beginning of the recording, and periodically (every 10s) write a sync marker packet into a sidecar JSON file:
+ ```json
+ {"ts_ms": 30000, "seq": 1500, "wall_clock_utc": "2026-04-07T12:00:30Z"}
+ ```
+ This allows the mixer to align recordings from different participants even if they join at different times.
+5. **Storage**:
+ - Desktop: `~/.wzp/recordings/{room}_{timestamp}.wav`
+ - Android: `Documents/WarzonePhone/{room}_{timestamp}.wav`
+ - Web: IndexedDB blob or File System Access API
+6. **File size estimate**: 48kHz * 16-bit * mono = 96 KB/s = ~5.6 MB/min = ~345 MB/hour
+7. **UI indicator**: Red dot + timer showing recording is active and file size growing
+8. **On hangup**: Close the WAV file, show "Recording saved" with file path/size
+
+### Phase 2: Upload to Mixer
+
+1. **Upload endpoint**: Self-hosted HTTP service (Rust or Go) that accepts WAV uploads with metadata
+2. **Chunked/resumable upload**: Large files need resumable uploads (tus protocol or simple chunked POST)
+3. **Upload metadata**:
+ ```json
+ {
+ "session_id": "uuid",
+ "participant_fingerprint": "xxxx:xxxx:...",
+ "alias": "Alice",
+ "room": "podcast-ep-42",
+ "duration_secs": 3600,
+ "sync_markers": [...],
+ "sample_rate": 48000,
+ "channels": 1,
+ "bit_depth": 16
+ }
+ ```
+4. **Upload UI**: Progress bar after hangup, option to upload now or later
+5. **Retry on failure**: Queue uploads for retry if network is unavailable
+
+### Phase 3: Mixer Service
+
+1. **Alignment**: Use sync markers (wall clock + sequence numbers) to align recordings from all participants to a common timeline
+2. **Silence trimming**: Detect and optionally trim leading/trailing silence
+3. **Normalization**: Per-track loudness normalization (LUFS-based)
+4. **Noise reduction**: Optional per-track noise gate or RNNoise pass
+5. **Output formats**:
+ - Multi-track: ZIP of individual WAVs (aligned, normalized)
+ - Mixed: Single stereo or mono WAV/MP3/FLAC with all participants
+ - Podcast-ready: Loudness-normalized to -16 LUFS (podcast standard)
+6. **Web UI**: Simple dashboard to see sessions, download outputs, preview waveforms
+7. **Self-hosted**: Docker image, single binary, SQLite for metadata
+
+## Implementation Notes
+
+### Recording tap point
+
+The recording must tap *after* AGC (so levels are normalized) but *before* the codec encoder (to avoid compression artifacts). In the current architecture:
+
+```
+Mic → Ring Buffer → AGC → [TAP HERE for recording] → Opus/Codec2 → Network
+```
+
+**Desktop** (`engine.rs`): After `capture_agc.process_frame()`, before `encoder.encode()`
+**Android** (`engine.rs`): Same location — after AGC, before encode
+**CLI** (`call.rs`): After `self.agc.process_frame()` in `CallEncoder::encode_frame()`
+
+### WAV writer
+
+Use a simple streaming WAV writer that:
+- Writes the WAV header with placeholder data length
+- Appends PCM samples as they come
+- On close, seeks back to update the data length in the header
+
+### Sync mechanism
+
+Wall-clock UTC alone is insufficient (clocks drift). The sync strategy:
+1. Each participant records their local monotonic time + wall clock at call start
+2. Periodically (every 10s), each participant writes: `{local_mono_ms, seq_number, utc_iso}`
+3. The mixer uses sequence numbers (which are shared via the wire protocol) as ground truth for alignment, with wall clock as a fallback
+
+### Privacy
+
+- Local recordings never leave the device without explicit user action
+- Upload is manual, not automatic
+- The mixer service processes files and can delete originals after mixing
+- No recording data flows through the relay — only the user's own mic
+
+## Non-Goals (v1)
+
+- Live transcription (future)
+- Video recording (audio only)
+- Automatic upload without user consent
+- Recording other participants' audio (only your own mic)
+- Real-time mixing (post-session only)
+
+## Milestones
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1a | Local WAV recording on Desktop | 1-2 days |
+| 1b | Local WAV recording on Android | 1-2 days |
+| 1c | Sync markers + metadata sidecar | 1 day |
+| 2a | Upload service (HTTP + storage) | 2-3 days |
+| 2b | Upload UI in clients | 1-2 days |
+| 3a | Mixer: alignment + normalization | 2-3 days |
+| 3b | Mixer: web dashboard | 2-3 days |
+| 3c | Docker packaging | 1 day |
diff --git a/vault/PRDs/PRD-mtu-discovery.md b/vault/PRDs/PRD-mtu-discovery.md
new file mode 100644
index 0000000..35b1e02
--- /dev/null
+++ b/vault/PRDs/PRD-mtu-discovery.md
@@ -0,0 +1,89 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: QUIC Path MTU Discovery
+
+## Problem
+
+WarzonePhone uses conservative 1200-byte QUIC datagrams. Some network paths support larger MTUs (1400+), wasting bandwidth. Some broken paths (VPNs, tunnels, double-NAT, cellular) have MTU < 1200, causing silent packet drops — this may explain why Opus 64k fails on some paths while 24k works (larger encoded frames + FEC repair packets).
+
+## Solution
+
+Enable Quinn's built-in Path MTU Discovery (PMTUD) and handle edge cases:
+1. PMTUD probes larger packet sizes and discovers the actual path MTU
+2. Graceful fallback when datagrams exceed discovered MTU
+3. Expose MTU in metrics for debugging
+
+## Implementation
+
+### Phase 1: Enable PMTUD in Quinn
+
+`crates/wzp-transport/src/config.rs` — update `transport_config()`:
+
+```rust
+// Enable PMTUD (Quinn default is enabled, but we should ensure it)
+config.mtu_discovery_config(Some(quinn::MtuDiscoveryConfig::default()));
+
+// Set minimum MTU for safety (some paths can't handle 1200)
+// Quinn default min is 1200, which is the QUIC spec minimum
+```
+
+Quinn's `MtuDiscoveryConfig` has:
+- `interval`: how often to probe (default: 600s)
+- `upper_bound`: max MTU to probe (default: 1452 for IPv4)
+- `minimum_change`: min MTU increase to be worth probing (default: 20)
+
+### Phase 2: Handle MTU-related Failures
+
+In federation forwarding (`send_raw_datagram`), if the datagram exceeds the connection's current MTU, Quinn returns an error. Handle gracefully:
+- Log warning with packet size vs MTU
+- Drop the packet (don't crash)
+- Track in metrics: `wzp_relay_mtu_exceeded_total`
+
+### Phase 3: Codec-Aware MTU
+
+When the path MTU is small, the relay or client should:
+- Prefer lower-bitrate codecs (smaller packets)
+- Reduce FEC ratio (fewer repair packets)
+- This feeds into the adaptive quality system
+
+### Phase 4: Expose MTU in Stats
+
+- Add `path_mtu` to relay metrics (per peer)
+- Add `path_mtu` to client stats (visible in UI)
+- Log MTU on connection establishment
+
+## Non-Goals (v1)
+
+- Datagram fragmentation (QUIC datagrams are atomic — either fit or don't)
+- Manual MTU override per relay config
+- MTU-based codec selection (future, needs adaptive quality)
+
+## Effort: 1 day
+
+## Implementation Status (2026-04-12)
+
+Phase 1 is now implemented:
+
+### What was built
+
+- **Transport config** (`crates/wzp-transport/src/config.rs`):
+ - `MtuDiscoveryConfig` with `upper_bound=1452`, `interval=300s`, `black_hole_cooldown=30s`
+ - `initial_mtu=1200` (safe QUIC minimum)
+ - Quinn's PLPMTUD binary-searches from 1200 up to 1452 automatically
+
+- **`QuinnPathSnapshot::current_mtu`** (`crates/wzp-transport/src/quic.rs`):
+ - Reads `connection.max_datagram_size()` which reflects the PMTUD-discovered value
+ - Available to all callers via `transport.quinn_path_stats()`
+
+- **Trunk batcher MTU-aware** (`crates/wzp-relay/src/room.rs`):
+ - `TrunkedForwarder::new()` initializes `max_bytes` from discovered MTU
+ - `send()` refreshes `max_bytes` on every call (cheap atomic read in quinn)
+ - Federation trunk frames grow automatically as PMTUD discovers larger paths
+
+### Phases 2-3 status
+
+- Phase 2 (handle MTU failures): Already handled — `send_media()`/`send_trunk()` check `max_datagram_size()` and return `DatagramTooLarge` errors. These are logged and the packet is dropped gracefully.
+- Phase 3 (codec-aware MTU): Not yet implemented. Future video frames will need application-layer fragmentation when they exceed the discovered MTU.
diff --git a/vault/PRDs/PRD-netcheck.md b/vault/PRDs/PRD-netcheck.md
new file mode 100644
index 0000000..fdf1295
--- /dev/null
+++ b/vault/PRDs/PRD-netcheck.md
@@ -0,0 +1,82 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Network Diagnostic (Netcheck)
+
+> Phase: Implemented
+> Status: Done (2026-04-14)
+> Crate: wzp-client
+
+## Problem
+
+When P2P connections fail or call quality is poor, there is no diagnostic tool to understand why. Users and developers must manually probe STUN, check NAT type, test relay connectivity, and verify port mapping support — all separately. Tailscale's `netcheck` consolidates all of this into a single diagnostic report.
+
+## Solution
+
+A comprehensive `run_netcheck()` function that probes all network capabilities in parallel and produces a structured `NetcheckReport`. Exposed as a CLI subcommand (`wzp-client --netcheck`) and available for in-app diagnostics.
+
+## Implementation
+
+### New Module: `crates/wzp-client/src/netcheck.rs`
+
+**NetcheckReport**:
+```rust
+pub struct NetcheckReport {
+ pub nat_type: NatType,
+ pub reflexive_addr: Option,
+ pub ipv4_reachable: bool,
+ pub ipv6_reachable: bool,
+ pub hairpin_works: Option,
+ pub port_mapping: Option,
+ pub relay_latencies: Vec,
+ pub preferred_relay: Option,
+ pub stun_latency_ms: Option,
+ pub upnp_available: bool,
+ pub pcp_available: bool,
+ pub nat_pmp_available: bool,
+ pub gateway: Option,
+ pub duration_ms: u32,
+ pub stun_probes: Vec,
+ pub port_allocation: Option,
+}
+```
+
+**Probes (all parallel via `tokio::join!`)**:
+1. **STUN probes** — `probe_stun_servers()` to all configured STUN servers
+2. **Relay latencies** — `probe_reflect_addr()` to each configured relay
+3. **Port mapping** — `acquire_port_mapping()` to detect NAT-PMP/PCP/UPnP
+4. **Gateway** — `default_gateway()` for the router address
+5. **IPv6** — attempt to bind `[::]:0` and send to an IPv6 STUN server
+6. **Port allocation** — `detect_port_allocation()` probes STUN servers from single socket to classify NAT pattern as PortPreserving/Sequential/Random (feeds into hard NAT prediction)
+
+**Derived fields**:
+- `nat_type` / `reflexive_addr` — from `classify_nat()` on STUN probes
+- `ipv4_reachable` — true if any STUN probe succeeded
+- `preferred_relay` — relay with lowest RTT
+- `port_mapping` / `nat_pmp_available` / `pcp_available` / `upnp_available` — from portmap result
+
+**Human-readable output**: `format_report()` produces a formatted text report with sections for NAT info, port mapping, STUN probes, relay latencies.
+
+### CLI Integration
+
+`wzp-client --netcheck ` — runs the diagnostic using the specified relay plus default STUN servers, prints the report, and exits.
+
+### Deferred
+
+- **Hairpin test** — send packet from shared endpoint to own reflexive addr to test NAT hairpinning. Architecture is in place (`hairpin_works: Option`) but the actual probe is not yet implemented.
+- **Android/Desktop in-app UI** — expose via JNI (Android) and Tauri command (desktop) for user-facing diagnostics.
+
+## Files
+
+| File | Change |
+|------|--------|
+| `crates/wzp-client/src/netcheck.rs` | New — NetcheckReport + run_netcheck + format_report |
+| `crates/wzp-client/src/lib.rs` | Add `pub mod netcheck` |
+| `crates/wzp-client/src/cli.rs` | `--netcheck` flag + handler |
+
+## Testing
+
+- 5 unit tests: default config, report JSON serialization + roundtrip, RelayLatency serialization, format_report with empty relays, format_report with full data (STUN probes, relay latencies, preferred relay, port mapping)
+- 1 integration test (`#[ignore]`): full netcheck run
diff --git a/vault/PRDs/PRD-network-awareness.md b/vault/PRDs/PRD-network-awareness.md
new file mode 100644
index 0000000..8d62ab0
--- /dev/null
+++ b/vault/PRDs/PRD-network-awareness.md
@@ -0,0 +1,144 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Network Awareness
+
+> Phase: Implemented (core path)
+> Status: Ready for testing
+> Platform: Android native Kotlin app (com.wzp)
+
+## Problem
+
+WarzonePhone's quality controller (`AdaptiveQualityController`) had a `signal_network_change()` API for proactive adaptation to WiFi↔cellular transitions, but nothing called it. Network handoffs during calls were only detected reactively via jitter spikes — by which time the user had already experienced degraded audio.
+
+## Solution
+
+Integrate Android's `ConnectivityManager.NetworkCallback` to detect network transport changes in real-time and feed them to the quality controller. This enables:
+
+1. **Preemptive quality downgrade** when switching from WiFi to cellular
+2. **FEC boost** (10-second window with +0.2 ratio) after any network change
+3. **Faster downgrade thresholds** on cellular (2 consecutive reports vs 3 on WiFi)
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Android │
+│ │
+│ ConnectivityManager │
+│ │ NetworkCallback │
+│ ▼ │
+│ NetworkMonitor.kt │
+│ │ onNetworkChanged(type, bandwidthKbps) │
+│ ▼ │
+│ CallViewModel.kt ──► WzpEngine.onNetworkChanged() │
+│ │ JNI │
+│ ▼ │
+│ jni_bridge.rs: nativeOnNetworkChanged(handle, type, bw) │
+│ │ │
+│ ▼ │
+│ engine.rs: state.pending_network_type.store(type) │
+│ │ AtomicU8 (lock-free) │
+│ ▼ │
+│ recv task: quality_ctrl.signal_network_change(ctx) │
+│ │ │
+│ ├─ Preemptive downgrade (WiFi → cellular) │
+│ ├─ FEC boost 10s │
+│ └─ Faster cellular thresholds │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Network Classification
+
+`NetworkMonitor` classifies the active transport without requiring `READ_PHONE_STATE` permission by using bandwidth heuristics:
+
+| Downstream Bandwidth | Classification | Rust `NetworkContext` |
+|----------------------|---------------|----------------------|
+| N/A (WiFi transport) | WiFi | `WiFi` |
+| >= 100 Mbps | 5G NR | `Cellular5g` |
+| >= 10 Mbps | LTE | `CellularLte` |
+| < 10 Mbps | 3G or worse | `Cellular3g` |
+| Ethernet | WiFi (equivalent) | `WiFi` |
+| Network lost | None | `Unknown` |
+
+## Cross-Task Signaling
+
+The network type is communicated from the JNI thread to the recv task via `AtomicU8` — the same pattern used for `pending_profile` (adaptive quality profile switches):
+
+```
+JNI thread recv task (tokio)
+ │ │
+ │ store(type, Release) │
+ │──────────────────────────────►│
+ │ │ swap(0xFF, Acquire)
+ │ │ if != 0xFF:
+ │ │ quality_ctrl.signal_network_change(ctx)
+ │ │
+```
+
+Sentinel value `0xFF` means "no change pending". The recv task polls on every received packet (~20-40ms), so latency is bounded by the inter-packet interval.
+
+## Components
+
+### New File
+
+| File | Purpose |
+|------|---------|
+| `android/.../net/NetworkMonitor.kt` | ConnectivityManager callback, transport classification, deduplication |
+
+### Modified Files
+
+| File | Change |
+|------|--------|
+| `android/.../engine/WzpEngine.kt` | Added `onNetworkChanged()` method + `nativeOnNetworkChanged` external |
+| `android/.../ui/call/CallViewModel.kt` | Instantiates NetworkMonitor, wires callback, register/unregister lifecycle |
+| `crates/wzp-android/src/jni_bridge.rs` | Added `Java_com_wzp_engine_WzpEngine_nativeOnNetworkChanged` JNI entry |
+| `crates/wzp-android/src/engine.rs` | Added `pending_network_type: AtomicU8` to EngineState, recv task polls it |
+
+### Unchanged (already implemented)
+
+| File | API |
+|------|-----|
+| `crates/wzp-proto/src/quality.rs` | `AdaptiveQualityController::signal_network_change(NetworkContext)` |
+| `crates/wzp-transport/src/path_monitor.rs` | `PathMonitor::detect_handoff()` (available for future use) |
+
+## Deferred Work
+
+### Tauri Desktop App (com.wzp.desktop)
+
+~~The Tauri engine doesn't use `AdaptiveQualityController` — quality is resolved once at call start.~~ **Update (2026-04-13):** Desktop now has `AdaptiveQualityController` wired into the recv task with `pending_profile` AtomicU8 bridge. Network monitoring on desktop is now feasible — the blocker was adaptive quality, which is done. Remaining work: platform-specific network change detection (macOS: `SCNetworkReachability` or `NWPathMonitor`; Linux: `netlink` socket).
+
+### Mid-Call ICE Re-gathering — PARTIALLY IMPLEMENTED (2026-04-14)
+
+When the device's IP address changes, the system now:
+1. Re-gather local host candidates (`local_host_candidates()`) ✅
+2. Re-probe STUN (`stun::discover_reflexive()` + `portmap::acquire_port_mapping()`) ✅
+3. Send updated candidates to the peer (`CandidateUpdate` signal message) ✅
+4. Relay forwards `CandidateUpdate` to peer (same pattern as `MediaPathReport`) ✅
+5. Peer receives and can parse via `IceAgent::apply_peer_update()` ✅
+6. Attempt new dual-path race for path upgrade — **NOT YET WIRED** (transport hot-swap)
+
+`NetworkMonitor.onIpChanged` fires on `onLinkPropertiesChanged` — the hook is ready.
+The signaling plane is fully implemented via `IceAgent` + `CandidateUpdate`.
+Remaining: wire `onIpChanged` → JNI → `pending_ice_regather` AtomicBool → recv task → `ice_agent.re_gather()` → transport swap.
+
+New modules added in Phase 8 (Tailscale-inspired):
+- `crates/wzp-client/src/ice_agent.rs` — candidate lifecycle management
+- `crates/wzp-client/src/stun.rs` — public STUN server probing (independent of relay)
+- `crates/wzp-client/src/portmap.rs` — NAT-PMP/PCP/UPnP port mapping
+- `crates/wzp-client/src/netcheck.rs` — comprehensive network diagnostic
+
+## Testing
+
+1. Build native APK
+2. Start a call on WiFi
+3. Verify logcat: `quality controller: network context updated` with `ctx=WiFi`
+4. Disable WiFi → device falls to cellular
+5. Verify logcat: `ctx=CellularLte` (or `Cellular5g`/`Cellular3g`)
+6. Verify FEC boost activates (check quality_ctrl logs)
+7. Verify preemptive quality downgrade (tier drops one level on WiFi→cellular)
+8. Re-enable WiFi → verify transition back
+9. Rapid WiFi toggle (5x in 10s) → verify no crashes, deduplication works
+10. Airplane mode → verify `onLost` fires with `TYPE_NONE`
diff --git a/vault/PRDs/PRD-p2p-direct.md b/vault/PRDs/PRD-p2p-direct.md
new file mode 100644
index 0000000..ed79894
--- /dev/null
+++ b/vault/PRDs/PRD-p2p-direct.md
@@ -0,0 +1,217 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Peer-to-Peer Direct Calls (No Relay)
+
+## Problem
+
+All calls currently route through a relay, even 1-on-1 calls between clients that could reach each other directly. This adds latency (2x hop), creates a single point of failure, and requires trusting the relay operator (even though media is encrypted, the relay sees metadata).
+
+## Solution
+
+For 1-on-1 calls, clients attempt a direct QUIC connection using STUN-discovered addresses. If NAT traversal succeeds, media flows directly between peers. If it fails, fall back to relay-assisted mode (current behavior).
+
+## Architecture
+
+```
+Preferred (P2P):
+ Client A ←──QUIC direct──→ Client B
+ (no relay in media path, true E2E)
+
+Fallback (Relay):
+ Client A ──→ Relay ──→ Client B
+ (current model)
+
+Hybrid discovery:
+ Client A → Relay (signaling only) → Client B
+ ↓ ↓
+ STUN server STUN server
+ ↓ ↓
+ Discover public IP:port Discover public IP:port
+ ↓ ↓
+ Exchange candidates via relay signaling
+ ↓ ↓
+ Attempt direct QUIC connection ←──→
+```
+
+## Why P2P = True E2E
+
+- QUIC TLS handshake establishes encrypted tunnel directly between A and B
+- No third party sees the traffic
+- Certificate pinning via identity fingerprints: each client derives their TLS cert from their Ed25519 seed (same as relay identity). During QUIC handshake, both sides verify the peer's cert fingerprint against the known identity
+- MITM elimination: if A knows B's fingerprint (from prior call, QR code, or identity server), any interceptor presents a different cert → fingerprint mismatch → connection rejected
+- Stronger guarantee than relay-assisted: user doesn't need to trust relay operator
+
+## Requirements
+
+### Phase 1: STUN Discovery
+
+1. **STUN client**: lightweight UDP-based STUN client to discover public IP:port
+ - Use existing public STUN servers (stun.l.google.com:19302, etc.)
+ - Or run a STUN server alongside the relay
+ - Discover: local addresses, server-reflexive addresses (STUN), relay candidates (TURN/relay fallback)
+
+2. **Candidate gathering**: on call initiation, gather all candidates:
+ - Host candidates: local network interfaces
+ - Server-reflexive: STUN-discovered public IP:port
+ - Relay candidate: the relay's address (fallback)
+
+3. **Candidate exchange**: via relay signaling channel (existing `IceCandidate` signal message)
+ - A sends candidates to relay → relay forwards to B
+ - B sends candidates to relay → relay forwards to A
+
+### Phase 2: Direct Connection
+
+1. **QUIC hole punching**: both clients simultaneously attempt QUIC connections to each other's candidates
+ - Quinn supports connecting to multiple addresses
+ - First successful connection wins
+ - Timeout after 3 seconds, fall back to relay
+
+2. **Identity verification**: during QUIC handshake, verify peer's TLS cert fingerprint
+ - `server_config_from_seed()` already exists — derive client cert from identity seed
+ - Both sides present certs (mutual TLS)
+ - Verify fingerprint matches expected identity
+
+3. **Media flow**: once connected, use existing `QuinnTransport` for media + signals
+ - Same `send_media()` / `recv_media()` API
+ - Same codec pipeline, FEC, jitter buffer
+ - No code changes needed in the call engine
+
+### Phase 3: Adaptive Quality (P2P)
+
+P2P connections have direct quality visibility — no relay middleman:
+
+1. Both clients observe RTT, loss, jitter directly from QUIC stats
+2. Adapt codec quality based on direct observations
+3. Since only 2 participants, coordinated switching is simple: propose → ack → switch
+
+This is the simplest case for adaptive quality. Once proven, backport the logic to relay-assisted mode.
+
+### Phase 4: Hybrid Mode
+
+1. **Call initiation**: always connect to relay for signaling
+2. **Parallel attempt**: while relay call is active, attempt P2P in background
+3. **Seamless migration**: if P2P succeeds, migrate media path from relay to direct
+ - Both clients switch simultaneously
+ - Relay connection kept alive for signaling (presence, room updates)
+4. **Fallback**: if P2P connection drops, seamlessly fall back to relay
+
+## Security Properties
+
+| Property | Relay Mode | P2P Mode |
+|----------|-----------|----------|
+| Encryption | ChaCha20-Poly1305 (app layer) | QUIC TLS 1.3 + ChaCha20-Poly1305 |
+| Key exchange | Via relay signaling | Direct QUIC handshake |
+| Identity verification | TOFU (server fingerprint) | Mutual TLS cert pinning |
+| Metadata privacy | Relay sees who talks to whom | No third party sees anything |
+| MITM resistance | Depends on relay trust | Strong (cert pinning) |
+| Forward secrecy | ECDH ephemeral keys | QUIC built-in + app-layer rekey |
+
+## Implementation Notes
+
+### STUN in Rust
+
+Use `stun-rs` or `webrtc-rs` crate for STUN client. Minimal: just need Binding Request/Response to discover server-reflexive address.
+
+### Quinn Hole Punching
+
+Quinn's `Endpoint` can both listen and connect. For hole punching:
+```rust
+let endpoint = create_endpoint(bind_addr, Some(server_config))?;
+// Send connect to peer's address (opens NAT pinhole)
+let conn = connect(&endpoint, peer_addr, "peer", client_config).await?;
+// Simultaneously, peer connects to our address
+// First successful handshake wins
+```
+
+### Client TLS Certificate
+
+Already have `server_config_from_seed()` for relays. Create `client_config_from_seed()` that presents a TLS client certificate derived from the identity seed. The peer verifies this cert's fingerprint.
+
+### Signaling via Relay
+
+The existing relay connection carries `IceCandidate` signals. No new infrastructure needed — just use the relay as a dumb signaling pipe for candidate exchange.
+
+## Non-Goals (v1)
+
+- SFU over P2P (P2P is 1-on-1 only; multi-party uses relay SFU)
+- TURN server (relay acts as the fallback, no separate TURN)
+- mDNS local discovery (future)
+- Mesh P2P for multi-party (future, complex)
+
+## Milestones
+
+| Phase | Scope | Effort | Status |
+|-------|-------|--------|--------|
+| 1 | STUN client + candidate gathering | 2 days | Done |
+| 2 | QUIC hole punching + identity verification | 3 days | Done |
+| 3 | Adaptive quality on P2P connection | 2 days | Done (#23) |
+| 4 | Hybrid mode (relay + P2P, seamless migration) | 3 days | Done |
+| 5 | Single-socket Nebula (shared signal+direct endpoint) | 2 days | Done |
+| 6 | ICE path negotiation + dual-path race | 3 days | Done |
+| 7 | IPv6 dual-socket | 2 days | Done (but `dual_path.rs` integration tests broken — missing `ipv6_endpoint` arg) |
+| 8.1 | Public STUN client (RFC 5389) | 1 day | Done |
+| 8.2 | PCP/PMP/UPnP port mapping | 2 days | Done |
+| 8.3 | Mid-call ICE re-gathering + CandidateUpdate signal | 2 days | Done (signal plane; transport hot-swap TODO) |
+| 8.4 | Netcheck diagnostic | 1 day | Done |
+| 8.5 | Region-based relay selection (data model) | 1 day | Done |
+| 8.6a | Hard NAT: port allocation detection | 1 day | Done |
+| 8.6b | Hard NAT: sequential port prediction signal | 1 day | Done (signal + prediction fn; dial integration pending) |
+| 8.6c | Hard NAT: birthday attack (256×1024 probes) | 3 days | Not started |
+| 8.6d | Hard NAT: hybrid waterfall + background upgrade | 2 days | Not started |
+
+## Implementation Status (2026-04-13)
+
+Phases 1-2, 4-7 are implemented. First P2P call completed 2026-04-12.
+
+### Known regression
+
+Phase 7 added `ipv6_endpoint: Option` parameter to `race()` in `crates/wzp-client/src/dual_path.rs` but the 3 test call sites in `crates/wzp-client/tests/dual_path.rs` (lines 111, 153, 191) were not updated — they pass 6 args instead of 7. Fix: add `None,` after the `shared_endpoint` arg in each call.
+
+## Update (2026-04-13)
+
+P2P adaptive quality (#23) now implemented:
+- Both peers self-observe network quality from QUIC path stats
+- Quality reports generated every ~1s and attached to outgoing packets
+- AdaptiveQualityController drives codec switching on both P2P and relay calls
+
+## Update (2026-04-14): Phase 8 — Tailscale-Inspired Enhancements
+
+Added 5 new modules to bring NAT traversal capability close to Tailscale's:
+
+### Phase 8.1: Public STUN Client (Done)
+- `stun.rs`: RFC 5389 Binding Request/Response over raw UDP
+- Independent reflexive discovery via public STUN servers (Google, Cloudflare)
+- `detect_nat_type_with_stun()` combines relay + STUN probes for higher confidence
+- STUN fallback in desktop's `try_reflect_own_addr()` when relay reflection fails
+
+### Phase 8.2: PCP/PMP/UPnP Port Mapping (Done)
+- `portmap.rs`: NAT-PMP (RFC 6886), PCP (RFC 6887), UPnP IGD
+- Gateway discovery (macOS + Linux), try NAT-PMP → PCP → UPnP in sequence
+- New candidate type: `PeerCandidates.mapped` + signal fields `caller_mapped_addr`/`callee_mapped_addr`/`peer_mapped_addr`
+- Dial order: host → mapped → reflexive (mapped helps on symmetric NATs)
+
+### Phase 8.3: Mid-Call ICE Re-Gathering (Done — signal plane)
+- `ice_agent.rs`: `IceAgent` with `gather()`, `re_gather()`, `apply_peer_update()`
+- `SignalMessage::CandidateUpdate` with monotonic generation counter
+- Relay forwards `CandidateUpdate` like `MediaPathReport`
+- Desktop handles and emits to JS frontend
+- Transport hot-swap: designed but not yet wired into live call engine
+
+### Phase 8.4: Netcheck Diagnostic (Done)
+- `netcheck.rs`: comprehensive network diagnostic (NAT type, reflexive addr, IPv4/v6, port mapping, relay latencies)
+- CLI: `wzp-client --netcheck `
+
+### Phase 8.5: Region-Based Relay Selection (Done — data model)
+- `relay_map.rs`: `RelayMap` sorted by RTT with `preferred()` selection
+- `RegisterPresenceAck` extended with `relay_region` + `available_relays`
+
+### Phase 8.6: Hard NAT Traversal (Phase A done, B-D pending)
+- **Phase A (Done)**: Port allocation pattern detection — `PortAllocation` enum (`PortPreserving`/`Sequential{delta}`/`Random`/`Unknown`), `detect_port_allocation()` probes N STUN servers from single socket, `classify_port_allocation()` with wraparound + jitter tolerance, `predict_ports()` for sequential NATs
+- **Phase B (signal ready)**: `HardNatProbe` signal message carries `port_sequence`, `allocation`, `external_ip` — relay forwarding implemented. Actual dial-to-predicted-ports integration into `dual_path::race()` pending.
+- **Phase C (not started)**: Birthday attack (256 sockets × 1024 probes) for random NATs
+- **Phase D (not started)**: Hybrid waterfall with background relay-to-direct upgrade
+- `NetcheckReport.port_allocation` populated automatically from `detect_port_allocation()`
+- See `docs/PRD-hard-nat.md` for full design
diff --git a/vault/PRDs/PRD-portmap.md b/vault/PRDs/PRD-portmap.md
new file mode 100644
index 0000000..cdfdccd
--- /dev/null
+++ b/vault/PRDs/PRD-portmap.md
@@ -0,0 +1,97 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: NAT Port Mapping (PCP/PMP/UPnP)
+
+> Phase: Implemented
+> Status: Done (2026-04-14)
+> Crate: wzp-client, wzp-proto, wzp-relay
+
+## Problem
+
+WarzonePhone falls back to relay-only when the client is behind a symmetric NAT (different external port per destination). The STUN-discovered reflexive address won't match what a peer sees, so direct hole-punching fails. Tailscale reports ~70% of consumer routers support NAT-PMP, PCP, or UPnP — protocols that let clients request explicit port mappings, making symmetric NATs traversable.
+
+## Solution
+
+Implement all three port mapping protocols, tried in sequence (NAT-PMP -> PCP -> UPnP). When a mapping is acquired, advertise the mapped address as a new candidate type alongside reflexive and host candidates. The relay cross-wires it into `CallSetup.peer_mapped_addr` so the peer can dial it.
+
+## Implementation
+
+### New Module: `crates/wzp-client/src/portmap.rs`
+
+**NAT-PMP (RFC 6886)**:
+- UDP to gateway:5351
+- External address request (opcode 0) -> returns router's public IP
+- Map UDP request (opcode 1) -> returns mapped external port + lifetime
+- 12-byte request, 16-byte response
+
+**PCP (RFC 6887)**:
+- Same gateway:5351, version 2
+- MAP opcode with client IP as IPv4-mapped IPv6
+- 60-byte request/response with 12-byte nonce for anti-spoofing
+- Superset of NAT-PMP, supports IPv6
+
+**UPnP IGD**:
+- SSDP M-SEARCH to 239.255.255.250:1900 for InternetGatewayDevice discovery
+- Parse LOCATION header -> fetch device description XML -> find WANIPConnection controlURL
+- SOAP `GetExternalIPAddress` -> router's public IP
+- SOAP `AddPortMapping` -> maps the QUIC port
+
+**Gateway discovery**:
+- macOS: `route -n get default` (parse `gateway:` line)
+- Linux/Android: `/proc/net/route` (parse hex gateway for 00000000 destination)
+
+**Public API**:
+- `acquire_port_mapping(internal_port, local_ip)` -> tries all 3, first success wins
+- `release_port_mapping(mapping)` -> best-effort cleanup (lifetime=0 for NAT-PMP)
+- `spawn_refresh(mapping)` -> background task renewing at half-lifetime
+- `default_gateway()` -> cross-platform gateway discovery
+
+### Signal Protocol Extensions
+
+| Message | New Field | Purpose |
+|---------|-----------|---------|
+| `DirectCallOffer` | `caller_mapped_addr: Option` | Caller's port-mapped address |
+| `DirectCallAnswer` | `callee_mapped_addr: Option` | Callee's port-mapped address |
+| `CallSetup` | `peer_mapped_addr: Option` | Relay cross-wires peer's mapped addr |
+
+All fields use `#[serde(default, skip_serializing_if)]` for backward compatibility.
+
+### Relay Cross-Wiring
+
+`CallRegistry` extended with `caller_mapped_addr` / `callee_mapped_addr` fields + setter methods. The relay:
+1. Extracts `caller_mapped_addr` from `DirectCallOffer`, stores in registry
+2. Extracts `callee_mapped_addr` from `DirectCallAnswer`, stores in registry
+3. Cross-wires into `CallSetup`: caller gets callee's mapped addr as `peer_mapped_addr`, and vice versa
+
+### Candidate Priority
+
+`PeerCandidates.mapped` added to `dual_path.rs`. Dial order:
+1. Host (LAN) candidates — fastest on same-LAN
+2. **Port-mapped** — stable even behind symmetric NATs
+3. Server-reflexive (STUN) — standard hole-punching
+4. Relay — always-available fallback
+
+### Desktop Integration
+
+Both `place_call()` and `answer_call()` call `acquire_port_mapping()` using the signal endpoint's local port. Privacy-mode answers (`AcceptGeneric`) skip portmap to keep the address hidden.
+
+## Files
+
+| File | Change |
+|------|--------|
+| `crates/wzp-client/src/portmap.rs` | New — NAT-PMP/PCP/UPnP client |
+| `crates/wzp-client/src/dual_path.rs` | `PeerCandidates.mapped` field + dial_order update |
+| `crates/wzp-proto/src/packet.rs` | `caller/callee_mapped_addr` + `peer_mapped_addr` fields |
+| `crates/wzp-relay/src/call_registry.rs` | `caller/callee_mapped_addr` fields + setters |
+| `crates/wzp-relay/src/main.rs` | Extract, store, cross-wire mapped addrs |
+| `desktop/src-tauri/src/lib.rs` | Call portmap in place_call/answer_call |
+
+## Testing
+
+- 18 unit tests: NAT-PMP encoding, UPnP XML parsing (5 variants including real-world router XML), URL host extraction, error Display, protocol serde, PortMapping serialization, gateway detection, constants verification
+- 2 integration tests (`#[ignore]`): gateway discovery, acquire_mapping
+- 9 PeerCandidates tests: dial_order with all types, dedup, is_empty edge cases
+- 12 protocol roundtrip tests: offer/answer/setup with mapped addr, backward compat without
diff --git a/vault/PRDs/PRD-protocol-analyzer.md b/vault/PRDs/PRD-protocol-analyzer.md
new file mode 100644
index 0000000..24db03b
--- /dev/null
+++ b/vault/PRDs/PRD-protocol-analyzer.md
@@ -0,0 +1,205 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Protocol Analyzer & Debug Tap
+
+## 1. Relay-Side Metadata Tap (`--debug-tap`)
+
+### Problem
+
+When debugging federation, codec issues, or packet flow problems, there's no visibility into what's actually flowing through the relay. You have to guess from client-side logs.
+
+### Solution
+
+A `--debug-tap ` flag on the relay that logs every packet's **header metadata** for a specific room (or all rooms with `--debug-tap *`). No decryption needed — the MediaHeader is not encrypted, only the audio payload is.
+
+### Output Format
+
+```
+[12:00:00.123] TAP room=test dir=in src=192.168.1.5:54321 seq=1234 codec=Opus24k ts=24000 fec_block=5 fec_sym=2 repair=false len=87
+[12:00:00.123] TAP room=test dir=out dst=192.168.1.6:54322 seq=1234 codec=Opus24k ts=24000 fec_block=5 fec_sym=2 repair=false len=87 fan_out=2
+[12:00:00.143] TAP room=test dir=in src=192.168.1.5:54321 seq=1235 codec=Opus24k ts=24960 fec_block=5 fec_sym=3 repair=false len=91
+[12:00:00.500] TAP room=test dir=in src=192.168.1.6:54322 seq=0042 codec=Codec2_1200 ts=40000 fec_block=1 fec_sym=0 repair=false len=6
+[12:00:01.000] TAP room=test SIGNAL type=RoomUpdate count=3 participants=[Alice,Bob,Charlie]
+[12:00:05.000] TAP room=test STATS period=5s in_pkts=250 out_pkts=500 fan_out_avg=2.0 loss_detected=0 codecs_seen=[Opus24k,Codec2_1200]
+```
+
+### What it shows
+
+- **Per-packet**: direction, source/dest, sequence number, codec ID, timestamp, FEC block/symbol, repair flag, payload size
+- **Signals**: RoomUpdate, FederationRoomJoin/Leave, handshake events
+- **Periodic stats**: packets in/out, average fan-out, codecs seen, detected sequence gaps (loss)
+- **Federation**: room-hash tagged datagrams with source/dest relay
+
+### Implementation
+
+**File:** `crates/wzp-relay/src/room.rs` — in `run_participant_plain()` and `run_participant_trunked()`
+
+After receiving a packet and before forwarding:
+```rust
+if debug_tap_enabled {
+ let h = &pkt.header;
+ info!(
+ room = %room_name,
+ dir = "in",
+ src = %addr,
+ seq = h.seq,
+ codec = ?h.codec_id,
+ ts = h.timestamp,
+ fec_block = h.fec_block,
+ fec_sym = h.fec_symbol,
+ repair = h.is_repair,
+ len = pkt.payload.len(),
+ "TAP"
+ );
+}
+```
+
+**Activation:** `--debug-tap ` CLI flag, or `debug_tap = "test"` / `debug_tap = "*"` in TOML config.
+
+**Performance:** Only active when enabled. When enabled, adds one `info!()` log per packet per direction. At 50 fps × 5 participants = 500 log lines/sec — acceptable for debugging, not for production.
+
+**Output options:**
+- Default: tracing log (stderr)
+- `--debug-tap-file `: write to a dedicated file (JSONL format for machine parsing)
+
+### Effort: 0.5 day
+
+### Implementation Status (2026-04-13)
+
+Fully implemented. `--debug-tap ` (or `*` for all rooms) logs:
+
+- **Per-packet metadata** (`TAP`): direction, addr, seq, codec, timestamp, FEC fields, payload size, fan_out
+- **Signal events** (`TAP SIGNAL`): `RoomUpdate` (count + participant names), `QualityDirective` (codec + reason), other signals by discriminant
+- **Lifecycle events** (`TAP EVENT`): participant join (id, addr, alias), participant leave (id, addr, forwarded count, or room closed)
+
+All output uses tracing `target: "debug_tap"` so it can be filtered with `RUST_LOG=debug_tap=info`.
+
+---
+
+## 2. Full Protocol Analyzer (Standalone Tool)
+
+### Problem
+
+The metadata tap shows packet flow but can't inspect audio content, verify encryption, or measure audio quality. For deep debugging (codec issues, resampling bugs, encryption mismatches), you need to see the actual decrypted audio.
+
+### Solution
+
+A standalone `wzp-analyzer` binary that either:
+- **A)** Acts as a transparent proxy between client and relay (MITM mode)
+- **B)** Reads a pcap/capture file with QUIC session keys (passive mode)
+- **C)** Runs as a special "observer" client that joins a room in listen-only mode with all participants' consent
+
+### Architecture
+
+**Option C (recommended — simplest, no MITM):**
+
+```
+ ┌──────────────┐
+ Client A ────────►│ Relay │◄──────── Client B
+ │ │
+ │ (SFU) │◄──────── wzp-analyzer
+ └──────────────┘ (observer mode)
+ │
+ ▼
+ ┌──────────────────┐
+ │ Decode + Analyze │
+ │ - Packet timing │
+ │ - Codec decode │
+ │ - Audio quality │
+ │ - Jitter stats │
+ │ - Waveform plot │
+ └──────────────────┘
+```
+
+The analyzer joins the room as a regular participant (receives all media via SFU forwarding) but doesn't send audio. It decodes everything it receives and produces analysis.
+
+**Limitation:** End-to-end encrypted payloads can't be decoded without session keys. The analyzer would either:
+1. Need the session key (shared out-of-band for debugging)
+2. Or only analyze unencrypted headers + timing (same as the relay tap, but from client perspective with jitter buffer simulation)
+
+For now, since encryption is not fully enforced in the current codebase (the crypto session is established but the actual ChaCha20 encryption of payloads is TODO in some paths), the analyzer can decode raw Opus/Codec2 payloads directly.
+
+### Features
+
+**Real-time display (TUI):**
+```
+┌─ wzp-analyzer: room "podcast" on 193.180.213.68:4433 ─────────────┐
+│ │
+│ Participants: Alice (Opus24k), Bob (Codec2_3200) │
+│ │
+│ Alice ──────────────────────────────────────── │
+│ seq: 5234 codec: Opus24k ts: 125760 loss: 0.2% jitter: 3ms │
+│ RMS: 4521 peak: 15280 silence: no │
+│ FEC blocks: 1046/1046 complete (0 recovered) │
+│ ▁▂▃▅▇█▇▅▃▂▁▁▂▃▅▇█▇▅▃▂▁ (waveform last 1s) │
+│ │
+│ Bob ────────────────────────────────────── │
+│ seq: 2617 codec: Codec2_3200 ts: 62800 loss: 1.5% jitter: 8ms│
+│ RMS: 1250 peak: 6800 silence: no │
+│ FEC blocks: 523/525 complete (4 recovered) │
+│ ▁▁▂▃▅▇▅▃▂▁▁▁▂▃▅▇▅▃▂▁▁ (waveform last 1s) │
+│ │
+│ Total: 7851 pkts recv, 0 pkts sent, 2 participants │
+│ Uptime: 2m 35s │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+**Recorded analysis:**
+- Save all received packets to a capture file
+- Post-session report: per-participant stats, quality timeline, codec switches, packet loss patterns
+- Export decoded audio as WAV per participant (if decryptable)
+
+**Quality metrics per participant:**
+- Packet loss % (from sequence gaps)
+- Jitter (inter-arrival time variance)
+- Codec switches (timestamps + reasons)
+- RMS audio level over time
+- Silence detection
+- FEC recovery rate
+- Round-trip estimates (from Ping/Pong if available)
+
+### Implementation
+
+**Binary:** `wzp-analyzer` (new crate or subcommand of `wzp-client`)
+
+```
+wzp-analyzer 193.180.213.68:4433 --room podcast
+wzp-analyzer 193.180.213.68:4433 --room podcast --record capture.wzp
+wzp-analyzer --replay capture.wzp --report report.html
+```
+
+**Dependencies:**
+- Existing: `wzp-transport`, `wzp-proto`, `wzp-codec`, `wzp-crypto`
+- New: `ratatui` for TUI display (optional)
+
+### Phases
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Header-only analysis: join room, log packet metadata, show per-participant stats (TUI) | 2 days |
+| 2 | Audio decode: decode Opus/Codec2 payloads (unencrypted path), show waveform + RMS | 1-2 days |
+| 3 | Capture/replay: save packets to file, replay offline with full analysis | 1 day |
+| 4 | HTML report: post-session quality report with charts | 2 days |
+| 5 | Encrypted payload support: accept session keys, decrypt ChaCha20 | 1 day |
+
+### Non-Goals (v1)
+
+- Active probing (sending test patterns)
+- Modifying packets in transit
+- Automated quality scoring (MOS estimation)
+- Video support
+
+## Implementation Status (2026-04-13)
+
+All phases implemented:
+- Phase 1 (Observer + stats): wzp-analyzer binary, passive room observer, per-participant stats — DONE
+- Phase 2 (TUI): ratatui display with color-coded loss severity — DONE
+- Phase 3 (Capture/Replay): Binary .wzp format + CaptureReader for offline replay — DONE
+- Phase 4 (HTML report): Self-contained with Chart.js loss/jitter timelines — DONE
+- Phase 5 (Encrypted decode): Stub — SFU E2E encryption requires session context. Header-only analysis works. — PARTIAL
+
+Binary: `cargo build --bin wzp-analyzer`
+Usage: `wzp-analyzer relay:4433 --room test [--capture out.wzp] [--html report.html] [--no-tui]`
diff --git a/vault/PRDs/PRD-protocol-hardening.md b/vault/PRDs/PRD-protocol-hardening.md
new file mode 100644
index 0000000..4b6001e
--- /dev/null
+++ b/vault/PRDs/PRD-protocol-hardening.md
@@ -0,0 +1,114 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Protocol Hardening Batch
+
+> **Status:** proposed
+> **Resolves:** Audit W2 (fec_block_id width), W3 (timestamp rebase doc), W5 (QualityReport AEAD binding), W11 (per-stream anti-replay), W12 (signal version byte), W13 (RoomManager lock).
+> **Depends on:** PRD #1 (wire format v2 already widens block_id field).
+
+## Problem
+
+A handful of medium-priority audit findings that don't individually justify a PRD but together represent the long tail of protocol correctness and concurrency. Batching them avoids version churn.
+
+## Items
+
+### H1 — W5: `QualityReport` trailer must be inside AEAD
+
+**Current risk.** If the 4-byte trailer sits *outside* the encrypted payload, anything stripping the last 4 bytes corrupts AEAD verification on legitimate packets and creates a quality-feedback downgrade vector. Even if it's correctly inside today, the v2 wire format change is the right moment to assert this explicitly.
+
+**Action.**
+- Audit `crates/wzp-proto/src/packet.rs` for `QualityReport` placement.
+- Move inside AEAD payload if currently outside.
+- Document: "QualityReport, when Q-flag set, is appended to plaintext payload before encryption."
+- Test: tamper with trailer → AEAD decrypt fails.
+
+**Severity.** Security correctness. Do this in Wave 1.
+
+### H2 — W2: `fec_block_id` width
+
+Resolved by v2 wire format (`u16` instead of `u8`). PRD #1 carries the wire change; this PRD just confirms semantics:
+
+- Wraps at 2^16. At 5-frame blocks and 50 pps → ~22 min between collisions, vs. ~25 s in v1.
+- Late-joining peers must still discard FEC blocks older than 2 s; widening is defense in depth.
+
+**Action.** Update `wzp-fec` to operate on u16 block_id end-to-end. Test reconstruction across a synthetic 22-min session.
+
+### H3 — W11: Per-stream, per-`MediaType` anti-replay window
+
+**Current.** 64-packet sliding window globally.
+
+**Problem.** Video keyframe burst (100+ packets) can stall the window behind one reordered prior packet.
+
+**Action.**
+- Anti-replay state is per (stream_id, media_type).
+- Window size: 64 for audio, 1024 for video, 256 for data.
+- Window size selected at session setup based on declared profile; tunable via `QualityProfile`.
+
+**Severity.** Required before video. Wave 1.
+
+### H4 — W12: `SignalMessage` versioning
+
+**Current.** Bincode-serialized enum. `#[serde(default, skip_serializing_if)]` handles field additions; variant removals or semantic changes are unsafe.
+
+**Action.**
+- Every variant gains `version: u8` as its first field.
+- Add `SignalMessage::Unknown { version, raw: Bytes }` to absorb future unknown variants gracefully.
+- Decode path: unknown variant → log + drop, do not close session.
+
+**Severity.** Future-proofing. Wave 3.
+
+### H5 — W3: `timestamp_ms` rebase documentation
+
+**Current.** Behavior at rekey (every 65,536 packets, ~22 min) is not documented.
+
+**Decision (this PRD).** `timestamp_ms` is **monotonic across rekeys** — it does not reset. Rekey changes only the cryptographic key material; sequence and timestamp are session-scoped, not key-scoped.
+
+**Action.**
+- Document in `WZP-SPEC.md` and inline in `packet.rs` doc comments.
+- Add a test that performs a rekey mid-session and asserts `timestamp_ms` continuity.
+
+**Severity.** Doc + test. Wave 3.
+
+### H6 — W13: `RoomManager` lock concurrency
+
+**Current.** Single `Mutex` acquired per packet by every participant for fan-out peer list. Serializes packet processing within a room.
+
+**Problem.** At 1500 pps/sender for video, this is the dominant bottleneck.
+
+**Action.**
+- Migrate to `DashMap>>`.
+- Per-room `RwLock` allows concurrent reads (fan-out peer list) and exclusive writes (join/leave/quality changes).
+- Fan-out path holds read lock; participant churn holds write lock.
+- Federation manager updated to match.
+
+**Severity.** Required for video scale. Wave 3.
+
+**Migration safety.**
+- Integration test suite (40 + 4 relay tests) must pass.
+- Federation tests must pass.
+- Trunking tests must pass.
+- Property-test: 100-participant room, 500 join/leave events, 10k packets — no panics, no missed forwards.
+
+## Implementation order
+
+| Wave | Item | Task |
+|---|---|---|
+| 1 | H1 (W5 AEAD binding) | T1.4 |
+| 1 | H3 (W11 anti-replay per-stream) | T1.5 |
+| 1 | H2 (W2 block_id widening) | folded into PRD #1 |
+| 3 | H4 (W12 signal versioning) | T3.3 |
+| 3 | H5 (W3 timestamp doc) | T3.2 |
+| 3 | H6 (W13 RoomManager lock) | T3.4 |
+
+## Acceptance criteria
+
+- All current tests pass post-hardening.
+- New tests: AEAD trailer tampering, rekey timestamp continuity, 100-participant property test, signal forward-compat decode.
+- No Prometheus regression in fan-out latency p99 after H6.
+
+## Effort
+
+~4.5 engineer-days total (1.5 in Wave 1, 3 in Wave 3).
diff --git a/vault/PRDs/PRD-public-stun.md b/vault/PRDs/PRD-public-stun.md
new file mode 100644
index 0000000..4b7b578
--- /dev/null
+++ b/vault/PRDs/PRD-public-stun.md
@@ -0,0 +1,73 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Public STUN Client
+
+> Phase: Implemented
+> Status: Done (2026-04-14)
+> Crate: wzp-client
+
+## Problem
+
+WarzonePhone's reflexive address discovery depends entirely on relay-based `Reflect` messages over an authenticated QUIC signal channel. If the relay is unreachable, overloaded, or not yet connected, the client cannot discover its public IP:port for P2P hole-punching. This single point of failure means call setup is delayed or falls back to relay-only unnecessarily.
+
+Tailscale solves this by querying multiple public STUN servers in parallel, independent of its DERP relay infrastructure.
+
+## Solution
+
+Implement a minimal RFC 5389 STUN Binding client over raw UDP that queries public STUN servers (Google, Cloudflare) in parallel. This provides:
+
+1. **Independent reflexive discovery** — works without any relay connection
+2. **Redundancy** — STUN fallback when relay reflection fails
+3. **Better NAT classification** — more probes = higher confidence in Cone vs Symmetric detection
+4. **Faster call setup** — STUN can run before signal registration completes
+
+## Implementation
+
+### New Module: `crates/wzp-client/src/stun.rs`
+
+**Wire format** (RFC 5389):
+- 20-byte header: type (u16) + length (u16) + magic cookie (0x2112A442) + transaction ID (12 bytes)
+- Binding Request (0x0001): no attributes, just the header
+- Binding Response (0x0101): parses XOR-MAPPED-ADDRESS (0x0020, preferred) and MAPPED-ADDRESS (0x0001, fallback)
+- XOR decoding: port XOR'd with top 16 bits of magic cookie, IPv4 XOR'd with cookie, IPv6 XOR'd with cookie || txn ID
+
+**Public API**:
+- `stun_reflect(socket, server, timeout)` — single-server probe with one retry on first-packet timeout
+- `discover_reflexive(config)` — parallel probe of N servers, first success wins
+- `probe_stun_servers(config)` — all-server probe returning `Vec` for NAT classification
+- `resolve_stun_server(host_port)` — DNS resolution preferring IPv4
+
+**Default servers**: `stun.l.google.com:19302`, `stun1.l.google.com:19302`, `stun.cloudflare.com:3478`
+
+**Error handling**: `StunError` enum — Io, Timeout, Malformed, TxnMismatch, ErrorResponse, NoMappedAddress, DnsError
+
+### Integration Points
+
+1. **`reflect.rs`**: New `detect_nat_type_with_stun()` runs relay probes and STUN probes concurrently via `tokio::join!`, merges results, re-classifies
+2. **Desktop `lib.rs`**: `try_reflect_own_addr()` falls back to `try_stun_fallback()` when relay reflection fails or times out
+3. **Desktop `detect_nat_type` command**: Uses `detect_nat_type_with_stun()` for combined relay + STUN classification
+
+### Design Decisions
+
+- **Separate UDP socket** per STUN probe — can't share the QUIC socket (quinn owns its I/O driver)
+- **No external crate** — RFC 5389 Binding is ~200 lines of code, no need for `stun-rs` or `webrtc-rs`
+- **Retry once** at half-timeout — handles the "first-packet problem" where some NATs drop the initial UDP packet to a new destination
+- **IPv4 preferred** for DNS resolution — Phase 7 IPv6 is still flaky
+
+## Files
+
+| File | Change |
+|------|--------|
+| `crates/wzp-client/src/stun.rs` | New — STUN client |
+| `crates/wzp-client/src/lib.rs` | Add `pub mod stun` |
+| `crates/wzp-client/src/reflect.rs` | Add `detect_nat_type_with_stun()` |
+| `crates/wzp-client/Cargo.toml` | Add `rand` dependency |
+| `desktop/src-tauri/src/lib.rs` | STUN fallback in `try_reflect_own_addr()`, STUN in `detect_nat_type` |
+
+## Testing
+
+- 22 unit tests: encode/decode roundtrips, XOR-MAPPED-ADDRESS (IPv4, IPv6, high port), MAPPED-ADDRESS fallback (IPv4, IPv6), unknown family, attribute padding, unknown attributes skipped, truncated attributes, error response, bad cookie, txn mismatch, too short, no mapped address, XOR preferred over mapped, error Display, default config, empty servers
+- 2 integration tests (`#[ignore]`): query `stun.l.google.com`, multi-server probe
diff --git a/vault/PRDs/PRD-relay-concurrency.md b/vault/PRDs/PRD-relay-concurrency.md
new file mode 100644
index 0000000..9fa03d2
--- /dev/null
+++ b/vault/PRDs/PRD-relay-concurrency.md
@@ -0,0 +1,319 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Relay Concurrency — DashMap Room Sharding
+
+## Problem
+
+The relay's media forwarding hot path routes every packet through a single `Arc>`. In a room with N participants, all N per-participant tasks compete for this one lock on every packet. The lock hold time is short (~1ms, no I/O), but the serialization means a 100-participant room effectively runs single-threaded despite having a multi-core tokio runtime.
+
+Separately, the federation manager holds `peer_links` locked across multiple network sends, meaning a slow federation peer blocks all others.
+
+### Measured bottleneck (from code audit)
+
+```
+Per-packet hot path (room.rs:748-757, 968-976):
+ lock(room_mgr)
+ → observe_quality() O(N) iterate qualities HashMap
+ → others() O(M) clone Vec
+ unlock
+ → fan-out sends sequential, no lock held
+```
+
+Lock contention = O(N) per room per packet, where N = participants in the room.
+
+### Current lock inventory (hot path only)
+
+| Lock | Location | Hold Duration | I/O While Locked | Frequency |
+|------|----------|---------------|-------------------|-----------|
+| `RoomManager` | room.rs:749, 968 | ~1ms | No | Every packet, every participant |
+| `RoomManager` | room.rs:845, 1041 | <1ms | No | Every 5s per participant |
+| `RoomManager` | room.rs:870 | ~1ms | No (explicit `drop` before broadcast) | On leave |
+| `peer_links` | federation.rs:409 | N × send latency | **YES** — `send_raw_datagram` in loop | Every federation packet |
+| `peer_links` | federation.rs:216 | N × send latency | **YES** — `send_signal` in loop | Every federation signal |
+| `dedup` | federation.rs:1066 | <1ms | No | Every federation ingress packet |
+| `rate_limiters` | federation.rs:1113 | <1ms | No | Every federation ingress packet |
+
+### Scaling impact
+
+| Room Size | Effective Core Usage | Bottleneck |
+|-----------|---------------------|------------|
+| 3 people × 100 rooms | All cores | None |
+| 10 people × 10 rooms | Most cores | Mild contention per room |
+| 100 people × 1 room | ~1 core | RoomManager lock |
+| 1000 people × 1 room | ~1 core | Severely serialized |
+
+## Goals
+
+- Eliminate the global RoomManager Mutex as a serialization point for media forwarding
+- Allow per-room parallelism: packets in room A don't block packets in room B
+- Fix federation `peer_links` lock held across network sends
+- Maintain correctness: no double-delivery, no stale participant lists
+- Zero-copy or minimal-clone for fan-out participant lists
+- Keep the refactor incremental — each phase independently shippable
+
+## Non-Goals
+
+- Lock-free data structures (overkill for our scale; DashMap or per-room Mutex is sufficient)
+- Changing the SFU forwarding model (no mixing, no transcoding)
+- Optimizing single-room beyond ~1000 participants (conferencing at that scale needs a different architecture)
+- Changing the wire protocol or client behavior
+
+## Design Options Evaluated
+
+### Option A: Per-Room `Arc>`
+
+**Approach:** Replace `HashMap` inside RoomManager with `HashMap>>`. The outer HashMap is protected by a short-lived lock for room lookup only; the per-room lock protects participant state.
+
+```rust
+struct RoomManager {
+ rooms: Mutex>>>, // outer: room lookup
+ // ...
+}
+
+// Hot path becomes:
+let room_arc = {
+ let rooms = room_mgr.rooms.lock().await;
+ rooms.get(&room_name).cloned() // Arc clone, <1ns
+}; // outer lock released
+
+if let Some(room) = room_arc {
+ let room = room.lock().await; // per-room lock
+ let others = room.others(participant_id);
+ drop(room);
+ // fan-out sends...
+}
+```
+
+**Pros:**
+- Rooms are fully independent — room A's lock doesn't block room B
+- Minimal code change (~50 lines)
+- Per-room lock contention = O(participants in that room), not O(total participants)
+- Outer lock held for <1μs (just a HashMap get + Arc clone)
+
+**Cons:**
+- Two-level locking (room lookup + room lock) — slightly more complex
+- Room creation/deletion still serialized through outer lock (acceptable, rare operation)
+- Quality tracking needs to move into the Room struct
+
+**Verdict: Best option. Biggest win for least effort.**
+
+### Option B: `DashMap`
+
+**Approach:** Replace `Mutex>` with `dashmap::DashMap`. DashMap uses internal sharding (default 64 shards) with per-shard RwLocks.
+
+```rust
+struct RoomManager {
+ rooms: DashMap,
+}
+
+// Hot path:
+if let Some(room) = room_mgr.rooms.get(&room_name) {
+ let others = room.others(participant_id); // read lock on shard
+ drop(room); // release shard lock
+ // fan-out sends...
+}
+```
+
+**Pros:**
+- No explicit locking in user code
+- Built-in sharding (64 shards by default)
+- Read-heavy workload benefits from RwLock per shard
+
+**Cons:**
+- New dependency (`dashmap` crate)
+- DashMap guards can't be held across `.await` points (not `Send`)
+- Mutable operations (join/leave/quality update) need `get_mut()` which takes exclusive shard lock
+- Less control over lock granularity than Option A
+- Quality tracking across rooms becomes awkward (can't iterate all rooms while holding one shard)
+
+**Verdict: Good but Option A is simpler and more explicit.**
+
+### Option C: Channel-Based Fan-Out
+
+**Approach:** Replace direct `send_media()` calls with per-participant `mpsc::Sender` channels. Room join registers a sender; the forwarding loop just does `tx.send(pkt)` which is lock-free.
+
+```rust
+struct Room {
+ participants: Vec<(ParticipantId, mpsc::Sender)>,
+}
+
+// Each participant's task:
+let (tx, mut rx) = mpsc::channel(64);
+room_mgr.join(room, participant_id, tx);
+
+// Forwarding in recv loop:
+let senders = room.others(participant_id); // Vec clone
+for tx in &senders {
+ let _ = tx.try_send(pkt.clone()); // non-blocking, no lock
+}
+```
+
+**Pros:**
+- Fan-out is completely lock-free (channel send is atomic)
+- Backpressure per participant (full channel = drop packet, not block others)
+- Natural decoupling: recv task → channel → send task
+
+**Cons:**
+- Requires cloning MediaPacket per participant (currently we clone ParticipantSender Arc, much cheaper)
+- Additional memory: 64-packet channel buffer × N participants
+- Still need a lock to get the sender list (unless we snapshot on join/leave)
+- Adds latency: channel hop + wake adds ~1-5μs vs direct send
+
+**Verdict: Over-engineered for current scale. Consider for 1000+ participant rooms.**
+
+### Option D: Snapshot-on-Change (Optimistic Read)
+
+**Approach:** Maintain a read-optimized `Arc>` snapshot per room. Updated atomically on join/leave (rare). Readers just `Arc::clone()` — no lock at all.
+
+```rust
+struct Room {
+ participants: Vec,
+ /// Atomically-updated snapshot of all senders (rebuilt on join/leave).
+ sender_snapshot: Arc>>,
+}
+
+// Hot path (zero locking!):
+let senders = room.sender_snapshot.load(); // atomic load, ~1ns
+for sender in senders.iter() {
+ if sender.id != participant_id { ... }
+}
+```
+
+**Pros:**
+- Zero lock contention on hot path — just an atomic pointer load
+- Rebuild cost amortized over all packets between joins/leaves
+- `arc-swap` crate is battle-tested and tiny
+
+**Cons:**
+- New dependency (`arc-swap`)
+- Quality tracking still needs a mutable path (separate concern)
+- Snapshot doesn't include mutable room state (quality tiers)
+- More complex join/leave (must rebuild snapshot atomically)
+
+**Verdict: Best theoretical performance, but adds complexity. Consider if DashMap proves insufficient.**
+
+## Recommended Implementation: Option B (DashMap) + Federation Fix
+
+DashMap is the right tool here. The original objections don't hold up:
+
+- "Guards can't be held across `.await`" — we already drop locks before any async sends
+- "Less control" — DashMap's 64 internal shards give finer granularity than manual per-room locks
+- "New dependency" — one crate, battle-tested, widely used in the Rust ecosystem
+
+DashMap's advantages over manual per-room `Arc>`:
+- **No two-level locking** — single `rooms.get()` vs outer-lock → Arc clone → drop → inner-lock
+- **Read/write separation** — `get()` is a shared shard lock, multiple rooms on the same shard can read concurrently
+- **Less code** — no manual Arc/Mutex wrapping, no explicit lock choreography
+- **Iteration without global lock** — federation room announcements don't block media forwarding
+
+### Phase 1: DashMap Room Storage (Biggest Win)
+
+1. Add `dashmap` dependency to `wzp-relay`
+2. Replace `rooms: HashMap` with `rooms: DashMap`
+3. Move `qualities` and `room_tiers` into the `Room` struct (per-room state, not global)
+4. RoomManager no longer needs a wrapping Mutex — it becomes `Arc` directly
+5. Per-packet hot path: `rooms.get(&name)` takes a shared shard lock, releases on drop
+
+```rust
+pub struct RoomManager {
+ rooms: DashMap,
+ acl: Option>>, // read-only after init
+ event_tx: broadcast::Sender,
+}
+
+struct Room {
+ participants: Vec,
+ qualities: HashMap,
+ current_tier: Tier,
+}
+
+// Hot path becomes:
+let (others, directive) = if let Some(mut room) = room_mgr.rooms.get_mut(&room_name) {
+ let directive = if let Some(ref qr) = pkt.quality_report {
+ room.observe_quality(participant_id, qr)
+ } else {
+ None
+ };
+ let o = room.others(participant_id);
+ (o, directive)
+} else {
+ (vec![], None)
+};
+// Shard lock released here — fan-out sends are lock-free
+```
+
+**Files to modify:**
+- `crates/wzp-relay/Cargo.toml` — add `dashmap` dependency
+- `crates/wzp-relay/src/room.rs` — RoomManager struct, Room struct, all methods
+- `crates/wzp-relay/src/lib.rs` — change from `Arc>` to `Arc`
+- `crates/wzp-relay/src/main.rs` — update RoomManager construction and all `.lock().await` call sites
+- `crates/wzp-relay/src/federation.rs` — update room_mgr usage (no more `.lock().await`)
+
+**Key behavior change:** `Arc>` → `Arc`. Every call site that does `room_mgr.lock().await.some_method()` becomes `room_mgr.some_method()` directly. The DashMap handles internal locking.
+
+**Concurrency improvement:**
+- Before: 100 rooms × 10 people = all 1000 tasks compete for 1 Mutex
+- After: 100 rooms × 10 people = distributed across 64 shards, ~15 tasks per shard average
+- Within a room: participants still serialize through the shard lock, but hold time is <0.1ms for `get()` and `others()` (just Vec clone of Arcs)
+
+### Phase 2: Federation Lock Fix
+
+Clone the peer list, release lock, then send:
+
+```rust
+pub async fn forward_to_peers(&self, room_hash: &[u8; 8], media_data: &Bytes) {
+ let peers: Vec<_> = {
+ let links = self.peer_links.lock().await;
+ links.values().map(|l| (l.label.clone(), l.transport.clone())).collect()
+ }; // lock released immediately
+
+ for (label, transport) in &peers {
+ // send without holding lock — slow peer doesn't block others
+ }
+}
+```
+
+Also apply to `broadcast_signal()` and `send_signal_to_peer()`.
+
+**Files to modify:**
+- `crates/wzp-relay/src/federation.rs` — 3 methods
+
+**Concurrency improvement:** A slow federation peer no longer blocks all other peers' media delivery.
+
+### Phase 3: Quality Tracking Optimization (Optional)
+
+With DashMap, quality tracking uses `get_mut()` (exclusive shard lock) on every packet that carries a QualityReport. For rooms where quality reports are frequent, this creates write contention on the shard.
+
+Option: Move quality observation to a background task:
+1. Per-participant `AtomicU8` for latest loss/RTT (lock-free write from hot path)
+2. Background task every 1s reads atomics, computes tiers, broadcasts directives
+3. Hot path becomes read-only: `rooms.get()` (shared lock) → `others()` → done
+
+**Reduces shard lock from exclusive (`get_mut`) to shared (`get`) on every packet.**
+
+## Verification
+
+1. **Correctness:** `cargo test -p wzp-relay` — all existing tests must pass
+2. **Compile check:** `cargo check --workspace` — no regressions
+3. **Load test:** 10 rooms × 10 participants, verify rooms forward concurrently
+4. **Large room:** 1 room × 50 participants, no deadlocks
+5. **Federation:** 3 relays, media bridges correctly with new lock pattern
+6. **Benchmark:** Before/after packets-per-second on multi-core with `wzp-bench`
+
+## Effort
+
+- Phase 1: 1 day (DashMap migration + test updates)
+- Phase 2: 0.5 day (federation clone-and-release)
+- Phase 3: 0.5 day (optional, quality tracking with atomics)
+- Total: 1.5–2 days
+
+## Implementation Status (2026-04-13)
+
+Phase 1 (DashMap): DONE — global Mutex → DashMap with 64 shards
+Phase 2 (Federation clone-before-send): DONE — forward_to_peers, broadcast_signal, send_signal_to_peer
+Phase 3 (Quality atomics): NOT DONE — optional optimization
+
+See also: docs/REFACTOR-relay-concurrency.md for the full post-refactor analysis.
diff --git a/vault/PRDs/PRD-relay-conformance.md b/vault/PRDs/PRD-relay-conformance.md
new file mode 100644
index 0000000..ff9ff58
--- /dev/null
+++ b/vault/PRDs/PRD-relay-conformance.md
@@ -0,0 +1,176 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Relay Conformance Enforcement (Abuse Mitigation Tiers A–G)
+
+> **Status:** proposed
+> **Resolves:** All in-scope vectors from `docs/ATTACK-SURFACE-RELAY-ABUSE.md`.
+> **Depends on:** PRD #1 (wire format v2 — for `MediaType` separation in Tiers D/F).
+
+## Problem
+
+WZP relays forward E2E-encrypted ciphertext and cannot inspect payload content. A trivial PoC on another E2E SFU (LiveKit) showed that without conformance enforcement, the relay becomes a free arbitrary-data tunnel. WZP must enforce media-shape conformance against observable header and timing metadata, without breaking E2E.
+
+## Goals
+
+- Make bulk data tunneling through WZP infeasible.
+- Bound aggregate per-user abuse blast radius.
+- Make covert tunneling expensive (Tier F) without false-positiving real calls.
+- Audio and video evaluated by **separate scorers** (statistical signatures don't overlap).
+
+## Non-goals
+
+- Content inspection (would break E2E).
+- Detecting steganographic covert channels inside legitimate audio (information-theoretic limit; not worth chasing).
+- CSAM / copyright detection (would require E2E break; explicit non-goal).
+
+## Design — tiered enforcement
+
+### Tier A — Codec-conformance bitrate caps
+
+For each `CodecID`, compute math-derived ceiling and enforce sliding 1 s window per session:
+
+```
+ceiling_bps[CodecID] = nominal * (1 + max_FEC_ratio) * (1 + overhead_pct)
+ = nominal * 3.0 * 1.15
+```
+
+Hard violation (sustained > ceiling for 1 s) → close session with `Hangup::PolicyViolation { code: BITRATE }`.
+
+### Tier B — Packet-rate cap
+
+Per `CodecID`, max `pps` known (25 or 50 base × up to 3× for FEC = ~150 pps for audio). Sustained > 200 pps audio → hard violation.
+
+### Tier C — Timestamp-rate consistency
+
+`Δtimestamp_ms / Δsequence` over rolling 200-packet window must match codec frame duration ± 2×. Violation → hard.
+
+### Tier D — Per-codec packet-size sanity
+
+EWMA(`payload_len`) per session; reject sustained mean > 2× codec typical. Per-codec table in spec.
+
+### Tier E — Per-fingerprint / per-IP token bucket
+
+```
+For each (fingerprint, src_ip):
+ monthly_bytes_quota authed = 50 GB (tunable)
+ anon = 1 GB
+ per-session bps cap audio = 256 kbps
+ video = 5 Mbps
+ burst = 30 s @ 2× cap
+```
+
+Anonymous quotas tight; authenticated (via featherChat) quotas generous. Soft enforcement: throttle, then close on persistent overage.
+
+### Tier F — Behavioral entropy scoring (per `MediaType`)
+
+Separate scorers for audio and video. Computed over 10–30 s windows.
+
+**Audio scorer features:**
+
+| Feature | Legitimate | Abusive |
+|---|---|---|
+| IAT coefficient of variation | 0.1–0.4 | > 1.0 |
+| Payload-size bimodality | Bimodal (speech + silence) | Unimodal |
+| Silence fraction | 10–40 % | < 2 % |
+| 30 s bitrate vs. nominal | ± 20 % | Saturates ceiling |
+| `Q` flag cadence | Periodic | Absent/random |
+
+**Video scorer features (post-PRD #5):**
+
+| Feature | Legitimate | Abusive |
+|---|---|---|
+| Keyframe periodicity | Regular (1–4 s or on PLI) | Absent / uniform KF=1 |
+| I/P frame-size ratio | 5–20× | ~1× |
+| Burst structure | I-frame in < 5 ms, then quiet | Uniform spacing |
+| Bitrate response to BWE | Tracks `remb_bps` | Ignores |
+| NACK/PLI responsiveness | Keyframe within 200 ms | No response |
+
+Output: `legitimacy ∈ [0, 1]` per session per `MediaType`. < 0.3 for 60 s → Suspect; < 0.1 for 60 s → Abusive.
+
+### Tier G — Reactive response
+
+```
+Verdict::Legitimate → no action
+Verdict::Suspect → apply tighter Tier E quota; emit metric
+Verdict::Abusive → close session with typed Hangup; cool-down fingerprint 1 h
+Verdict::RepeatAbusive → relay-local block 24 h; (optional gossip)
+```
+
+Always typed close. No silent drops.
+
+## Implementation outline
+
+New module `wzp-relay/src/conformance.rs`:
+
+```rust
+pub struct ConformanceMeter {
+ media_type: MediaType,
+ declared_codec: AtomicU8,
+ bytes_window: SlidingWindow<1000>,
+ packet_window: SlidingWindow<1000>,
+ iat_ewma: ExponentialMovingAverage,
+ iat_variance: ExponentialMovingVariance,
+ size_histogram: SizeBuckets<8>,
+ silence_count: AtomicU32,
+ speech_count: AtomicU32,
+ quality_reports_seen: AtomicU32,
+ last_timestamp_ms: AtomicU32,
+ last_seq: AtomicU32,
+ keyframe_intervals: RingBuffer,
+ violations: AtomicU32,
+}
+
+impl ConformanceMeter {
+ pub fn observe(&self, h: &MediaHeader, payload_len: usize, now: Instant) -> Result<(), Violation>;
+ pub fn legitimacy(&self) -> f32;
+ pub fn verdict(&self) -> Verdict;
+}
+```
+
+Hooked into per-participant forwarding loop in `RoomManager`. Tier A–D run synchronously (cheap). Tier F runs on a periodic task (every 1 s per session).
+
+Prometheus exports:
+
+```
+wzp_relay_conformance_violations_total{tier,codec_id,media_type,verdict}
+wzp_relay_conformance_legitimacy{media_type} histogram
+wzp_relay_conformance_iat_cov{media_type} histogram
+wzp_relay_conformance_silence_fraction histogram
+```
+
+## Rollout
+
+1. Deploy with all tiers in **observe-only** mode (Prometheus only, no enforcement).
+2. Collect 1–2 weeks of baseline traffic.
+3. Set thresholds at observed 99.9th percentile of legitimate traffic + headroom.
+4. Flip Tier A enforcement first (highest confidence, lowest false-positive risk).
+5. Flip B, C, D over 2 weeks.
+6. Tune Tier F thresholds against the baseline; flip Suspect first, then Abusive.
+
+## Acceptance criteria
+
+- Synthetic abuse test (5 Mbps random bytes declared as Opus 24 k) closed within 1 s.
+- Synthetic abuse test (audio-rate small packets with stuffed payload) closed within 5 s by Tier D.
+- Synthetic abuse test (audio-rate, audio-sized, but no silence and CoV=2.0 IAT) flagged Suspect within 60 s.
+- Real-call false-positive rate < 0.1 % over a week of production baseline.
+- All verdict transitions emit Prometheus counters.
+
+## Risks
+
+- **False positives on edge cases** (long lectures with little silence, ambient-music calls). Mitigation: Tier F floor at Suspect for 30 s minimum; manual review channel for repeat-flagged authed users.
+- **Threshold drift** as codecs evolve. Mitigation: ceilings are math-derived from codec table; updated when codec table updates.
+- **Federated abuse moving between relays.** Mitigation: Tier G optional gossip (post-Wave 5).
+
+## Effort
+
+- Tier A + B + C: 1.5 d (T2.4 + T2.5)
+- Tier D: 0.5 d (T3.6)
+- Tier E: 1.5 d (T3.5)
+- Tier F audio: 3 d (T5.7)
+- Tier F video: 3 d (T6.2)
+- Tier G: 1 d (T5.8)
+
+Total: ~10 engineer-days, spread across Waves 2–6.
diff --git a/vault/PRDs/PRD-relay-federation-gossip.md b/vault/PRDs/PRD-relay-federation-gossip.md
new file mode 100644
index 0000000..3ea51e6
--- /dev/null
+++ b/vault/PRDs/PRD-relay-federation-gossip.md
@@ -0,0 +1,307 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# Design Exploration: Federated Reputation Gossip (T6.3)
+
+> **Status:** Design exploration — no approach selected.
+> **Blocked on:** Reviewer design call (needs operator-trust model decision).
+> **Scope:** How should WZP relays share abuse verdicts across a federation mesh so that abusers cannot hop between relays?
+
+## Background
+
+WZP relays are E2E-encrypted SFUs. They cannot inspect payload content, but they **can** observe metadata: packet rates, payload sizes, timestamps, keyframe patterns, and BWE responsiveness. Tiers A–F of the conformance pipeline observe these signals and produce a `Verdict ∈ {Legitimate, Suspect, Abusive}`.
+
+Tier G (`ResponsePolicy`) escalates:
+- `Abusive` → typed `Hangup` + 1 h fingerprint cool-down
+- Repeat `Abusive` within 24 h → relay-local `Block` for 24 h
+
+**The gap:** Block state is in-memory only and per-relay. A blocked fingerprint on relay A can reconnect to relay B (same room, same mesh) and resume abuse immediately. T6.3 explores closing this gap.
+
+**What is being gossiped?** A *reputation event*: "fingerprint `F` produced violation `V` with verdict `Abusive` at time `T` on relay `R`."
+
+---
+
+## Assumptions
+
+1. Relays trust each other *connection-level* (TLS fingerprints in `PeerConfig` / `TrustedConfig`) but are **not** guaranteed to share the same abuse-detection thresholds or calibration.
+2. The federation mesh is small (tens of relays, not thousands).
+3. False positives happen — a legitimate user on a long lecture call can trigger `Suspect` or even `Abusive` on an aggressively-tuned relay.
+4. A compromised relay is a realistic threat model (stolen credentials, operator coercion, buggy calibration).
+5. Relays are operated by different entities — there is no single administrative root of trust.
+
+---
+
+## Approach 1: Push Gossip
+
+### Summary
+When a relay issues a `Block` action (repeat abusive), it immediately broadcasts a `ReputationEvent` to all peer relays via the existing federation QUIC channels. Peers incorporate the event into their local block lists.
+
+### Wire format
+
+```rust
+// New SignalMessage variant
+ReputationEvent {
+ version: u8,
+ /// Fingerprint being reported (the abused party, not the reporter).
+ fingerprint: String,
+ /// Which violation code triggered the block.
+ violation: ViolationCode,
+ /// When the block was issued (Unix epoch seconds, u64).
+ issued_at: u64,
+ /// TTL in seconds (default 86400 = 24 h).
+ ttl_secs: u32,
+ /// Relay that issued the block (TLS fingerprint hex).
+ origin_relay_fp: String,
+ /// Ed25519 signature over (fingerprint || violation || issued_at || ttl_secs || origin_relay_fp).
+ /// The signing key is the relay's long-term identity key (reused from client handshake identity).
+ signature: [u8; 64],
+}
+```
+
+**What is signed?** The canonical serialization of the payload fields (excluding the signature itself). This prevents replay of old events and binds the event to a specific origin relay.
+
+**Key distribution:** Each relay's Ed25519 public key is published in a well-known endpoint (e.g., `/.well-known/wzp-relay.pub`) or embedded in the `FederationHello` handshake. Verification happens on receipt.
+
+### Sybil resistance
+
+- **Signing requirement:** Only relays with a known Ed25519 pubkey can produce valid events. A rogue relay must first be in the `TrustedConfig` to even connect.
+- **Origin attribution:** Every event is traceable to a specific relay. If relay R starts flooding false positives, peers can blacklist R's pubkey or reduce R's event weight to zero.
+- **No aggregate thresholding:** This design trusts every signed event equally. A single malicious relay can block any fingerprint across the mesh.
+
+**Mitigation option (not implemented):** Require *k-of-n* independent relay reports before applying a cross-relay block. This introduces complexity (tracking per-fingerprint report counts, decaying counters, handling churn).
+
+### Convergence model
+
+- **Eventual consistency:** Events propagate via multi-hop flood (same mechanism as `GlobalRoomActive`).
+- **Bounded staleness:** Events carry TTL. Stale events (> TTL) are ignored.
+- **No ordering guarantee:** Two relays may issue conflicting events (relay A blocks F, relay B clears F). Last-writer-wins based on `issued_at`.
+
+### Storage
+
+- **In-memory only:** `HashMap<(fingerprint, origin_relay), ReputationEntry>` with TTL-based eviction.
+- **No persistence:** Restarting a relay loses all gossiped state. Re-blocking requires the origin relay to re-gossip or the abuser to re-offend.
+- **Memory bound:** ~100 bytes per entry × 10k entries = ~1 MB. Trivial.
+
+### Partition tolerance
+
+- **Partitioned relay A** blocks fingerprint F locally but cannot push to peers. When partition heals, A floods the backlog. Peers apply events with `issued_at` within TTL; expired backlog is ignored.
+- **Partitioned relay B** never hears about F's block. F can abuse B freely during the partition. This is acceptable for a best-effort gossip system.
+
+### Failure modes
+
+| Scenario | Impact | Mitigation |
+|---|---|---|
+| Compromised relay floods false blocks | All fingerprints blocked mesh-wide | Manual pubkey blacklist; no automatic mitigation in this design |
+| Buggy relay false-positives a popular fingerprint | Legitimate users blocked everywhere | Operator contact + pubkey downgrade |
+| Network partition | Split-brain block lists | Acceptable; partition healing replays backlog |
+| Clock skew | Events from future/past rejected or mis-ordered | Use `issued_at` with ±5 min tolerance; NTP assumed |
+| Replay attack | Old event re-broadcast after TTL | Signature binds `issued_at`; verify TTL at receipt |
+
+### Complexity
+
+- **Low-medium:** Reuses existing federation broadcast infrastructure. Adds one `SignalMessage` variant, Ed25519 signing/verification, and an in-memory TTL map.
+
+---
+
+## Approach 2: Pull Gossip (Reputation Oracle)
+
+### Summary
+One relay in the mesh is designated the **reputation oracle** (or a small quorum of 3). Other relays query the oracle periodically (e.g., every 60 s) for the current block list. The oracle maintains the authoritative reputation state.
+
+### Wire format
+
+```rust
+// Pull request
+ReputationQuery {
+ version: u8,
+ /// Last checkpoint the requester has seen (opaque cursor).
+ since_cursor: Option,
+}
+
+// Pull response
+ReputationSnapshot {
+ version: u8,
+ /// Opaque cursor for delta pagination.
+ cursor: String,
+ /// List of active blocks at the oracle.
+ blocks: Vec,
+ /// Oracle's Ed25519 signature over the serialized snapshot.
+ signature: [u8; 64],
+}
+
+struct ReputationBlock {
+ fingerprint: String,
+ violation: ViolationCode,
+ issued_at: u64,
+ ttl_secs: u32,
+ /// Which relay originally reported this (for audit).
+ reported_by: String,
+}
+```
+
+**What is signed?** The entire `ReputationSnapshot` serialized canonically. The oracle is the sole signer.
+
+**Oracle selection:** Config-based. Each relay's config names its oracle(s):
+```toml
+[reputation]
+oracle = "https://relay-oracle.example.com"
+oracle_pubkey = "AA:BB:CC:..."
+```
+
+### Sybil resistance
+
+- **Centralized trust:** The oracle is a single point of trust. If the oracle is honest, no rogue relay can poison the mesh.
+- **Oracle compromise:** A compromised oracle can block or unblock any fingerprint across all querying relays. This is a **catastrophic** failure mode.
+- **Quorum variant:** 3 oracles with 2-of-3 signing. Queries return the intersection of block lists. More resilient but adds latency and complexity.
+
+### Convergence model
+
+- **Bounded staleness:** Worst-case = query interval (60 s) + network RTT.
+- **Strong consistency within staleness bound:** All querying relays see the same oracle state (modulo query timing skew).
+- **No multi-hop gossip:** Direct query/response only.
+
+### Storage
+
+- **Oracle side:** In-memory + optional persistence (SQLite or flat file). Oracle restarts reload from disk.
+- **Querying relays:** In-memory cache of the last snapshot. No local state between restarts.
+- **Memory bound:** Same as Approach 1 (~1 MB for 10k entries).
+
+### Partition tolerance
+
+- **Partitioned querying relay:** Falls back to local-only blocking (current behavior). When partition heals, next query re-syncs.
+- **Partitioned oracle:** All querying relays lose cross-relay reputation and fall back to local-only. Oracle restart without persistence = same.
+- **No split-brain:** Either you have the oracle snapshot or you don't. No conflicting states.
+
+### Failure modes
+
+| Scenario | Impact | Mitigation |
+|---|---|---|
+| Oracle compromise | Global block/unblock of any fingerprint | 2-of-3 quorum; operator out-of-band alert |
+| Oracle downtime | All querying relays lose cross-relay reputation | Fallback to local-only; no amplification |
+| Rogue relay reports to oracle | Oracle may incorporate false positives | Oracle applies local thresholding (e.g., require 2 independent reports) |
+| Query amplification | N relays × 60 s = many queries | Oracle caches; responses are cheap |
+| Man-in-the-middle on query | Attacker injects fake snapshot | TLS + signature verification on response |
+
+### Complexity
+
+- **Medium:** Adds an HTTP/QUIC query endpoint, snapshot pagination, oracle election/config, and a new failure mode (oracle as SPOF).
+- **Operational burden:** Someone must run the oracle. Small federations may not want this.
+
+---
+
+## Approach 3: No Gossip — Explicit Ban-List Distribution
+
+### Summary
+Relays do **not** gossip reputation automatically. Instead, a human admin (or an automated audit pipeline) curates an authoritative ban list, signs it, and pushes it to all relays. Relays apply the list verbatim.
+
+### Wire format
+
+```rust
+// Signed ban list (distributed out-of-band: HTTPS, SCP, S3, etc.)
+BanList {
+ version: u8,
+ /// Issued at (Unix epoch seconds).
+ issued_at: u64,
+ /// Expires at (Unix epoch seconds). After this, the list is ignored.
+ expires_at: u64,
+ /// Entries.
+ entries: Vec,
+ /// Admin Ed25519 signature over canonical serialization.
+ signature: [u8; 64],
+}
+
+struct BanEntry {
+ fingerprint: String,
+ /// Human-readable reason (not machine-parsed).
+ reason: String,
+ /// Optional: which relay originally reported.
+ source_relay: Option,
+}
+```
+
+**What is signed?** The entire `BanList`. The admin (not a relay) is the signer.
+
+**Distribution:** Out-of-band from the federation mesh. Could be:
+- Admin `scp`s JSON to each relay's config directory
+- Relays poll an HTTPS URL every 5 min
+- Shared object storage (S3, GCS)
+
+**Key distribution:** Admin pubkey is baked into each relay's config at provisioning time:
+```toml
+[ban_list]
+admin_pubkey = "AA:BB:CC:..."
+url = "https://ops.example.com/banlist.json"
+refresh_secs = 300
+```
+
+### Sybil resistance
+
+- **Strong:** Only the admin can produce a valid ban list. No relay can poison another relay.
+- **Admin compromise:** Catastrophic — attacker controls the global ban list. But this is a standard operational threat model (same as DNS root, certificate transparency log, etc.).
+- **No relay-to-relay trust required:** Relays don't need to trust each other's calibration or behaviour.
+
+### Convergence model
+
+- **Poll-based bounded staleness:** Worst-case = `refresh_secs` (default 300 s = 5 min).
+- **Strong consistency:** All relays that successfully fetch the list see identical state.
+- **No event propagation:** No flood, no multi-hop, no deduplication needed.
+
+### Storage
+
+- **On-disk cache:** Each relay stores the latest fetched ban list to survive restart.
+- **In-memory lookup:** `HashSet` for O(1) block checks.
+- **Memory bound:** Same as other approaches.
+
+### Partition tolerance
+
+- **Partitioned relay:** Continues using its last cached ban list until `expires_at`. After expiry, falls back to local-only blocking.
+- **No split-brain:** Either you have the signed list or you don't.
+
+### Failure modes
+
+| Scenario | Impact | Mitigation |
+|---|---|---|
+| Admin key compromise | Global block/unblock of any fingerprint | Key rotation + out-of-band alert |
+| Distribution channel down | Relays use stale cached list until expiry | Short expiry + monitoring |
+| Admin false-positives a popular fingerprint | Global block of legitimate users | Human review process; short expiry allows quick recovery |
+| Relay never fetches list | Local-only blocking only | Monitoring alert on relay ops dashboard |
+| List too large | Fetch latency, memory bloat | Pagination; but 10k entries = ~500 KB JSON, trivial |
+
+### Complexity
+
+- **Low:** No changes to federation mesh at all. Adds an HTTP polling loop, a file watcher, or an S3 sync. The signing/verification is trivial (one Ed25519 verify on fetch).
+- **Operational burden:** Requires a human or automated pipeline to maintain the ban list. This is acceptable for small federations (the WZP target audience) but does not scale to open meshes.
+
+---
+
+## Comparative Summary
+
+| Dimension | Approach 1: Push Gossip | Approach 2: Pull Oracle | Approach 3: Ban-List Distribution |
+|---|---|---|---|
+| **Trust model** | Every relay trusts every other relay's verdict equally | Trusts a designated oracle (or 2-of-3 quorum) | Trusts a single admin key |
+| **Sybil resistance** | Weak — one rogue relay can poison the mesh | Medium-strong — oracle is gatekeeper | Strong — only admin can sign |
+| **Convergence** | Eventual; multi-hop flood | Bounded (query interval); direct pull | Bounded (poll interval); out-of-band |
+| **Partition tolerance** | Acceptable (backlog replay on heal) | Acceptable (fallback to local) | Good (cached list + expiry) |
+| **False-positive blast radius** | Mesh-wide from one relay | Mesh-wide from oracle | Mesh-wide from admin |
+| **Operational burden** | Low — fully automatic | Medium — must run oracle | Medium — must curate list |
+| **Federation code changes** | Medium — broadcast loop, dedup, signatures | Medium — query endpoint, snapshot pagination | Low — out-of-band, no mesh changes |
+| **Scaling** | Poor — flood doesn't scale past ~50 relays | Good — O(N) queries, oracle is O(1) | Good — O(N) fetches, no mesh load |
+| **Audit trail** | Good — every event attributed to origin relay | Good — oracle logs all reports | Good — list is a snapshot |
+| **Rollback / correction** | Hard — events spread everywhere; need counter-events | Easy — oracle updates snapshot | Easy — admin publishes new list |
+
+## Open Questions (Blockers for Implementation)
+
+1. **Trust model:** Do we trust all peer relays equally (Approach 1), trust a designated oracle (Approach 2), or trust a human admin (Approach 3)? This is a product/operations decision, not a technical one.
+2. **Key infrastructure:** The federation layer currently has **no message-level signing**. All three approaches require adding Ed25519 signing/verification to relay-relay messages (or out-of-band fetches). The `wzp-crypto` crate already has Ed25519 identity support (used in client handshake) — it can be reused.
+3. **Fingerprint scope:** Is the block scoped to a fingerprint (Ed25519 pubkey), an IP address, or both? Current `ResponsePolicy` uses a string fingerprint. Gossip should probably scope to the cryptographic identity, not IP, to prevent NAT rebind evasion.
+4. **Privacy leakage:** Gossiping "fingerprint F is abusive" leaks that F was on a call. Is this acceptable? WZP is not anonymous by design (participants know each other's fingerprints), but operators learning about calls they are not in is a privacy concern.
+5. **TTL vs. persistent bans:** Should a gossiped block expire automatically (TTL), or should it require manual review for extension? Automatic expiry limits false-positive damage but allows persistent abusers to cycle.
+6. **Rate limiting on gossip:** A compromised relay could flood the mesh with `ReputationEvent` messages. The existing per-room rate limiter (500 pps) doesn't apply to control messages. A per-peer gossip rate limit is needed regardless of approach.
+
+## Recommendation
+
+**Do not implement any approach yet.** The blockers above (especially #1 trust model and #4 privacy) need a reviewer/operator design call. T6.3 should remain **Blocked** until then.
+
+If forced to pick a default for a small, closed federation (the current WZP target audience), **Approach 3 (Ban-List Distribution)** has the lowest complexity, the strongest Sybil resistance, and the easiest rollback. It sacrifices automation but small federations typically have an ops person who can review blocks anyway. Approach 1 (Push Gossip) is more elegant for larger meshes but requires solving the rogue-relay problem first (e.g., k-of-n thresholding).
diff --git a/vault/PRDs/PRD-relay-federation.md b/vault/PRDs/PRD-relay-federation.md
new file mode 100644
index 0000000..fc65094
--- /dev/null
+++ b/vault/PRDs/PRD-relay-federation.md
@@ -0,0 +1,175 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Relay Federation (Multi-Relay Mesh)
+
+## Problem
+
+Currently all participants in a call must connect to the same relay. This creates:
+- **Single point of failure** — if the relay goes down, the entire call drops
+- **Geographic latency** — users far from the relay get high RTT
+- **Capacity limits** — one relay handles all traffic
+
+Users should be able to connect to their nearest/preferred relay and still talk to users on other relays, as long as the relays are federated.
+
+## Prerequisite: Fix Relay Identity Persistence
+
+### Bug: TLS certificate regenerates on every restart
+
+**Root cause:** `wzp-transport/src/config.rs:17` calls `rcgen::generate_simple_self_signed()` which creates a new keypair every time. The relay's Ed25519 identity seed IS persisted to `~/.wzp/relay-identity`, but the TLS certificate is not derived from it.
+
+**Impact:** Clients see a different server fingerprint after every relay restart, triggering the "Server Key Changed" warning. This also breaks federation since relays identify each other by certificate fingerprint.
+
+**Fix:** Derive the TLS certificate from the persisted relay seed:
+1. Add `server_config_from_seed(seed: &[u8; 32])` to `wzp-transport`
+2. Use the seed to create a deterministic keypair (e.g., derive an ECDSA key via HKDF from the Ed25519 seed)
+3. Generate a self-signed cert with that keypair — same seed = same cert = same fingerprint
+4. The relay passes its loaded seed to `server_config_from_seed()` instead of `server_config()`
+
+**Effort:** 0.5 day
+
+## Federation Design
+
+### Core Concept
+
+Two or more relays form a **federation mesh**. Each relay is an independent SFU. When relays are configured to trust each other, they bridge rooms with matching names — participants on relay A in room "podcast" hear participants on relay B in room "podcast" as if everyone were on the same relay.
+
+### Configuration
+
+Each relay reads a YAML config file (e.g., `~/.wzp/relay.yaml` or `--config relay.yaml`):
+
+```yaml
+# Relay identity (auto-generated if missing)
+listen: 0.0.0.0:4433
+
+# Federation peers — other relays we trust and bridge rooms with
+# Both sides must configure each other for federation to work
+peers:
+ - url: "193.180.213.68:4433"
+ fingerprint: "a5d6:e3c6:5ae7:185c:4eb1:af89:daed:4a43"
+ label: "Pangolin EU"
+
+ - url: "10.0.0.5:4433"
+ fingerprint: "7f2a:b391:0c44:..."
+ label: "Office LAN"
+```
+
+**Key rules:**
+- Both relays must configure each other — **mutual trust** required
+- A relay that receives a connection from an unknown peer logs: `"Relay a5d6:e3c6:... (193.180.213.68) wants to federate. To accept, add to peers config: url: 193.180.213.68:4433, fingerprint: a5d6:e3c6:..."`
+- Fingerprints are verified via the TLS certificate (requires the identity fix above)
+
+### Protocol
+
+#### Peer Connection
+
+1. On startup, each relay attempts QUIC connections to all configured peers
+2. The connection uses SNI `"_federation"` (reserved room name prefix) to distinguish from client connections
+3. After QUIC handshake, verify the peer's certificate fingerprint matches the configured fingerprint
+4. If fingerprint mismatch → reject, log warning
+5. If peer connects but isn't in our config → log the helpful "add to config" message, reject
+
+#### Room Bridging
+
+Once two relays are connected:
+
+1. **Room discovery**: When a local participant joins room "T", the relay sends a `FederationRoomJoin { room: "T" }` signal to all connected peers
+2. **Room leave**: When the last local participant leaves room "T", send `FederationRoomLeave { room: "T" }`
+3. **Media forwarding**: For each room that exists on both relays:
+ - Relay A forwards all media packets from its local participants to relay B
+ - Relay B forwards all media packets from its local participants to relay A
+ - Each relay then fans out received federated media to its local participants (same as local SFU forwarding)
+4. **Participant presence**: `RoomUpdate` signals are merged — local participants + federated participants from all peers
+
+```
+Relay A (2 local users) Relay B (1 local user)
+┌─────────────────────┐ ┌─────────────────────┐
+│ Room "T" │ │ Room "T" │
+│ Alice (local) ────┼──media──►│ Charlie (local) │
+│ Bob (local) ────┼──media──►│ │
+│ │◄──media──┼── Charlie │
+│ Charlie (federated)│ │ Alice (federated) │
+│ │ │ Bob (federated) │
+└─────────────────────┘ └─────────────────────┘
+```
+
+#### Signal Messages (new)
+
+```rust
+enum FederationSignal {
+ /// A room exists on this relay with active participants
+ RoomJoin { room: String, participants: Vec },
+ /// Room is empty on this relay
+ RoomLeave { room: String },
+ /// Participant update for a federated room
+ ParticipantUpdate { room: String, participants: Vec },
+}
+```
+
+#### Media Forwarding
+
+Federated media is forwarded as raw QUIC datagrams — the relay doesn't decode/re-encode. Each packet is prefixed with a room identifier so the receiving relay knows which room to fan it out to:
+
+```
+[room_hash: 8 bytes][original_media_packet]
+```
+
+The 8-byte room hash is computed once when the federation room bridge is established.
+
+### What Relays DON'T Do
+
+- **No transcoding** — media passes through as-is. If Alice sends Opus 64k, Charlie receives Opus 64k
+- **No re-encryption** — packets are already encrypted end-to-end between participants. Relays just forward opaque bytes
+- **No central coordinator** — each relay independently connects to its configured peers. No master/slave, no consensus protocol
+- **No automatic peer discovery** — peers must be explicitly configured in YAML
+
+### Failure Handling
+
+- If a peer relay goes down, the federation link drops. Local rooms continue to work. Federated participants disappear from presence.
+- Reconnection: attempt every 30 seconds with exponential backoff up to 5 minutes
+- If a peer relay restarts with a new identity (bug not fixed), the fingerprint check fails and federation is rejected with a clear error log
+
+## Implementation Plan
+
+### Phase 0: Fix Relay Identity (prerequisite)
+- Derive TLS cert from persisted seed
+- Same seed → same cert → same fingerprint across restarts
+
+### Phase 1: YAML Config + Peer Connection
+- Add `--config relay.yaml` CLI flag
+- Parse peers config
+- On startup, connect to all configured peers via QUIC
+- Verify certificate fingerprints
+- Log helpful message for unconfigured peers
+- Reconnect on disconnect
+
+### Phase 2: Room Bridging
+- Track which rooms exist on each peer
+- Forward media for shared rooms
+- Merge participant presence across peers
+- Handle room join/leave signals
+
+### Phase 3: Resilience
+- Graceful handling of peer disconnect/reconnect
+- Don't duplicate packets if a participant is reachable via multiple paths
+- Rate limiting on federation links (prevent amplification)
+- Metrics: federated rooms, packets forwarded, peer latency
+
+## Effort Estimates
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 0 | Fix relay TLS identity from seed | 0.5 day |
+| 1 | YAML config + peer QUIC connections | 2 days |
+| 2 | Room bridging + media forwarding + presence merge | 3-4 days |
+| 3 | Resilience + metrics | 2 days |
+
+## Non-Goals (v1)
+
+- Automatic peer discovery (mDNS, DHT, etc.)
+- Cascading federation (relay A ↔ B ↔ C where A doesn't know C)
+- Load balancing across relays
+- Encryption between relays (QUIC provides transport encryption; e2e encryption between participants is orthogonal)
+- Different rooms on different relays (all federated rooms are bridged by name)
diff --git a/vault/PRDs/PRD-relay-selection.md b/vault/PRDs/PRD-relay-selection.md
new file mode 100644
index 0000000..6c48346
--- /dev/null
+++ b/vault/PRDs/PRD-relay-selection.md
@@ -0,0 +1,93 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Region-Based Relay Selection
+
+> Phase: Implemented (data model)
+> Status: Done (2026-04-14)
+> Crate: wzp-client, wzp-proto, wzp-relay
+
+## Problem
+
+Clients are configured with a single relay address. With multiple relays in the federation mesh, the client should automatically discover all available relays and select the lowest-latency one. Currently there is no mechanism for the relay to advertise its mesh peers to clients, and no client-side data structure to track relay health over time.
+
+## Solution
+
+1. Relays advertise their region and mesh peers in `RegisterPresenceAck`
+2. Clients maintain a `RelayMap` sorted by measured RTT
+3. `preferred()` returns the best relay for call setup
+
+## Implementation
+
+### New Module: `crates/wzp-client/src/relay_map.rs`
+
+**RelayEntry**:
+```rust
+pub struct RelayEntry {
+ pub name: String,
+ pub addr: SocketAddr,
+ pub region: Option,
+ pub rtt_ms: Option,
+ pub last_probed: Option,
+ pub reachable: bool,
+}
+```
+
+**RelayMap API**:
+- `upsert(name, addr, region)` — add or update a relay entry
+- `update_rtt(addr, rtt_ms)` — record probe result, marks reachable, re-sorts
+- `mark_unreachable(addr)` — sorts unreachable entries to end
+- `preferred()` -> `Option<&RelayEntry>` — lowest RTT reachable relay
+- `populate_from_ack(relays, region)` — parse `RegisterPresenceAck.available_relays` (format: `"name|addr"`)
+- `needs_reprobe(max_age)` — true if any entry has stale or missing probe
+- `stale_entries(max_age)` — list of entries needing fresh probes
+
+### Signal Protocol Extension
+
+`RegisterPresenceAck` extended:
+```rust
+RegisterPresenceAck {
+ success: bool,
+ error: Option,
+ relay_build: Option,
+ relay_region: Option, // NEW
+ available_relays: Vec, // NEW — "name|addr" format
+}
+```
+
+### Relay Config Extension
+
+`RelayConfig` extended:
+```rust
+pub region: Option, // e.g., "us-east", "eu-west"
+pub advertised_addr: Option, // for available_relays population
+```
+
+### Relay Population
+
+On `RegisterPresenceAck`, the relay populates:
+- `relay_region` from `config.region`
+- `available_relays` from `config.peers` (label|url format)
+
+### Deferred
+
+- **Automatic relay switching** — using `preferred()` to select relay during call setup instead of hardcoded config
+- **Background reprobing** — periodic RTT measurements to keep the relay map fresh
+- **Cross-relay RTT estimation** — using mesh probe data to estimate combined caller-RTT + callee-RTT for optimal relay placement
+
+## Files
+
+| File | Change |
+|------|--------|
+| `crates/wzp-client/src/relay_map.rs` | New — RelayMap + RelayEntry |
+| `crates/wzp-client/src/lib.rs` | Add `pub mod relay_map` |
+| `crates/wzp-proto/src/packet.rs` | `relay_region` + `available_relays` on RegisterPresenceAck |
+| `crates/wzp-relay/src/config.rs` | `region` + `advertised_addr` fields |
+| `crates/wzp-relay/src/main.rs` | Populate RegisterPresenceAck from config + peers |
+
+## Testing
+
+- 15 unit tests: preferred by RTT, unreachable not preferred, preferred empty/all-unreachable, populate_from_ack (valid + malformed entries), upsert updates/preserves region, needs_reprobe (empty/never/fresh), stale_entries, sort stability with equal RTT, mark_unreachable sorts to end, RelayEntry serialization
+- 2 protocol tests: RegisterPresenceAck roundtrip with new fields, backward compat without new fields
diff --git a/vault/PRDs/PRD-studio-quality.md b/vault/PRDs/PRD-studio-quality.md
new file mode 100644
index 0000000..a3200e1
--- /dev/null
+++ b/vault/PRDs/PRD-studio-quality.md
@@ -0,0 +1,61 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Studio Quality Tiers (Opus 32k/48k/64k)
+
+## Status: Implemented
+
+Studio quality tiers have been added to the wire protocol and all clients.
+
+## What Was Added
+
+### Wire Protocol (codec_id.rs)
+
+Three new `CodecId` variants using the 4-bit header space (values 6-8):
+
+| CodecId | Wire Value | Bitrate | Frame | Use Case |
+|---------|-----------|---------|-------|----------|
+| Opus32k | 6 | 32 kbps | 20ms | Studio low — noticeable improvement over 24k for voice |
+| Opus48k | 7 | 48 kbps | 20ms | Studio — excellent voice, captures nuance |
+| Opus64k | 8 | 64 kbps | 20ms | Studio high — near-transparent quality |
+
+### Quality Profiles
+
+| Profile | Codec | FEC | Bandwidth (with FEC) |
+|---------|-------|-----|---------------------|
+| STUDIO_32K | Opus 32k | 10% | ~35 kbps |
+| STUDIO_48K | Opus 48k | 10% | ~53 kbps |
+| STUDIO_64K | Opus 64k | 10% | ~70 kbps |
+
+FEC is set to 10% (vs 20% for GOOD) — studio assumes a good network.
+
+### Client Support
+
+| Client | Selection | Status |
+|--------|-----------|--------|
+| Desktop (Tauri) | Quality slider in Settings (8 levels) | Done |
+| CLI | `--profile studio-64k` / `studio-48k` / `studio-32k` | Done |
+| Android | Needs codec picker update in SettingsScreen.kt | TODO |
+| Web | Needs UI | TODO |
+
+### Cross-Codec Interop
+
+All decoder auto-switch paths (call.rs, desktop engine.rs) handle the new codec IDs. A studio-64k client can talk to a codec2-1200 client — the receiver auto-switches.
+
+## When to Use Studio Tiers
+
+- **Podcast recording sessions**: Use studio-64k for best quality (combined with local WAV recording for pristine output)
+- **Music collaboration**: Opus at 48-64k captures instrument harmonics much better than 24k
+- **Good network conditions**: Only useful when bandwidth isn't constrained; the extra bits are wasted on lossy networks
+
+## When NOT to Use
+
+- **Mobile data**: Stick with Auto/GOOD — studio tiers use 2-3x the bandwidth
+- **High packet loss**: Studio profiles use minimal FEC (10%); degraded networks need DEGRADED or CATASTROPHIC profiles with 50-100% FEC
+- **Large group calls**: Each participant's stream multiplies bandwidth; 64k * 10 participants = 640 kbps incoming
+
+## Backward Compatibility
+
+Old clients (before this change) will receive packets with CodecId 6/7/8 which they don't recognize. The `from_wire()` returns `None` for unknown values, causing the packet to be dropped. Old clients can still *send* to new clients fine (they use CodecId 0-5). This is acceptable for a pre-release protocol.
diff --git a/vault/PRDs/PRD-transport-feedback-bwe.md b/vault/PRDs/PRD-transport-feedback-bwe.md
new file mode 100644
index 0000000..fbfcdca
--- /dev/null
+++ b/vault/PRDs/PRD-transport-feedback-bwe.md
@@ -0,0 +1,121 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Transport Feedback & Bandwidth Estimator
+
+> **Status:** proposed
+> **Resolves:** Audit W6 (no BWE), W14 (no receiver→sender feedback channel).
+> **Depends on:** PRD #1 (wire format v2 — for u32 seq).
+
+## Problem
+
+`AdaptiveQualityController` decides tier transitions from loss% and RTT only. Quinn exposes congestion-window and bytes-in-flight, but we don't consume them. There is no receiver→sender feedback channel beyond the inline 4-byte `QualityReport`.
+
+Consequences:
+- On stable links with spare capacity, we never upgrade past the declared profile (audio stuck at Opus 24 k when 64 k is available).
+- Oscillation between adjacent tiers on the boundary.
+- **No bandwidth-aware adaptation = no usable video.** Video without BWE either oscillates wildly or never uses available capacity.
+
+## Goals
+
+- Continuous bandwidth estimate per session, surfaced to adaptation controllers.
+- Receiver→sender feedback at ~50 ms cadence carrying ack/nack/remb.
+- Audio benefits immediately (smarter upgrades, fewer oscillations).
+- Video uses BWE as its primary input (PRD #7).
+
+## Non-goals
+
+- Replacing Quinn's congestion controller — we ride on top.
+- Cross-stream BWE (each session estimates independently for v1).
+
+## Design
+
+### `SignalMessage::TransportFeedback`
+
+New signal variant, sent on the existing signal stream every 50 ms or every N media packets, whichever first:
+
+```rust
+pub struct TransportFeedback {
+ pub version: u8, // PRD #4 W12: always present
+ pub stream_id: u8, // 0 for session-wide; >0 for per-stream
+ pub acked_seqs: Vec, // recent seqs received OK (RLE-compressed)
+ pub nacked_seqs: Vec, // recent seqs missing (RLE-compressed)
+ pub remb_bps: u32, // receiver's estimated max bandwidth
+ pub recv_time_us: u64, // arrival-time for sender-side jitter calc
+}
+```
+
+RLE compression keeps the wire size bounded (typical payload ~50 B).
+
+### `BandwidthEstimator` (in `wzp-proto`)
+
+```rust
+pub struct BandwidthEstimator {
+ cwnd_bps: AtomicU64, // from Quinn path stats
+ bytes_in_flight: AtomicU64, // from Quinn path stats
+ peer_remb_bps: AtomicU64, // from TransportFeedback
+ smoothed_bps: AtomicU64, // EWMA output
+}
+
+impl BandwidthEstimator {
+ pub fn update_from_quinn(&self, stats: &QuinnPathStats);
+ pub fn update_from_peer(&self, fb: &TransportFeedback);
+ pub fn target_send_bps(&self) -> u64 {
+ // 0.9 × min(cwnd_bps, peer_remb_bps), EWMA-smoothed
+ }
+}
+```
+
+Three signals fused:
+1. **Quinn cwnd.** Conservative ceiling — sending faster than cwnd just drops or queues.
+2. **Peer REMB.** Receiver's perspective on what they can actually consume (after their own jitter buffer, decode budget, etc.).
+3. **EWMA smoothing.** Half-life ~2 s; avoids oscillation.
+
+Target = 90 % of `min(cwnd, remb)`, leaving headroom for probing upward.
+
+### Adaptation controller integration
+
+`AdaptiveQualityController::tick()` already consumes loss/RTT/jitter. Add BWE input:
+
+```rust
+if self.bwe.target_send_bps() > self.current_tier_ceiling_bps() * 1.3
+ && consecutive_upgrade_reports >= UPGRADE_THRESHOLD {
+ self.upgrade_one_tier();
+}
+```
+
+Upgrade gated on BWE *headroom*, not just clean reports. Eliminates the "always at Opus 24 k on a fiber link" pathology.
+
+### Probing
+
+To detect unused capacity, sender occasionally adds 5–10 % padding/FEC during otherwise-clean windows. If `cwnd` doesn't drop and `remb` doesn't fall, the headroom is real — upgrade. If signals degrade, back off. Cheap and standard.
+
+## Implementation outline
+
+1. New `wzp-proto::bwe::BandwidthEstimator`.
+2. `wzp-transport` exposes `QuinnPathStats { cwnd_bps, bytes_in_flight, rtt_ms }`; already partially there via `QuinnPathSnapshot`.
+3. `SignalMessage::TransportFeedback` variant + serde.
+4. Receiver-side: track recent seqs in a ring buffer; emit feedback every 50 ms.
+5. Sender-side: BWE consumes own Quinn stats + incoming feedback.
+6. `AdaptiveQualityController::set_bwe(&BandwidthEstimator)`.
+7. Prometheus: `wzp_session_bwe_bps`, `wzp_session_remb_bps`, `wzp_session_cwnd_bps`.
+8. Probing logic behind a flag for first deployment.
+
+## Acceptance criteria
+
+- On a shaped 5 Mbps link with Opus 24 k, controller upgrades to Opus 64 k within 30 s.
+- On a shaped 50 kbps link, controller stays at Opus 6 k and does not oscillate.
+- Feedback wire size < 100 B per 50 ms (= < 2 kbps overhead).
+- Probing finds headroom on a 10 Mbps link in < 60 s.
+
+## Risks
+
+- **Probing-induced loss on already-saturated links.** Mitigation: probe only when smoothed loss < 1 % over 10 s.
+- **Feedback storm under heavy loss.** Mitigation: feedback rate capped at 20 Hz independent of media rate.
+- **Quinn cwnd lies on QUIC-over-some-VPNs.** Mitigation: REMB serves as cross-check; take min of the two.
+
+## Effort
+
+~4 engineer-days (Wave 2 tasks T2.1–T2.3).
diff --git a/vault/PRDs/PRD-video-multicodec.md b/vault/PRDs/PRD-video-multicodec.md
new file mode 100644
index 0000000..93f521a
--- /dev/null
+++ b/vault/PRDs/PRD-video-multicodec.md
@@ -0,0 +1,116 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Multi-Codec Video Negotiation (H.264 + H.265 + AV1)
+
+> **Status:** proposed
+> **Resolves:** Road-to-video Phase V3 codec rollout; reserves `CodecID` slots 9–13.
+> **Depends on:** PRD #5 (video v1 working with H.264).
+
+## Problem
+
+H.264 baseline ships first because it has universal hardware encode coverage. H.265 offers ~30 % efficiency at equal quality and is now broadly supported in HW (Apple A10+, Snapdragon since ~2017, NVENC since GTX 9xx). AV1 is the long-term target but hardware encode is limited (Apple M3/A17+, Snapdragon 8 Gen 3+, RTX 40+).
+
+We need codec negotiation so each session uses the best mutually-supported codec without manual configuration, and so we can roll AV1 in gated on real telemetry.
+
+## Goals
+
+- `CodecID` assignments for H.264 baseline (9), H.264 main (10), H.265 main (11), AV1 (12), VP9 reserved (13).
+- Capability declaration in `CallOffer.supported_codecs`.
+- Picker logic: highest mutually-supported codec from a deterministic preference cascade.
+- Hardware-encode detection at session start; refuse codecs requiring SW encode on battery-powered devices.
+- Existing framer/depacketizer reused — only the codec wrapper changes.
+
+## Non-goals
+
+- New codecs beyond this list.
+- Per-receiver codec selection (one codec per stream for v1; could be revisited with simulcast).
+
+## Design
+
+### Codec capability declaration
+
+```rust
+pub struct CodecCapability {
+ pub codec_id: u8,
+ pub max_resolution: (u16, u16),
+ pub max_fps: u8,
+ pub hardware: bool, // true if HW encode available
+}
+
+pub struct CallOffer {
+ ...
+ pub supported_codecs: Vec,
+}
+```
+
+### Preference cascade
+
+```
+preference: [AV1, H.265 main, H.264 main, H.264 baseline]
+
+pick = first codec in `preference` where:
+ caller.supported.contains(codec)
+ AND callee.supported.contains(codec)
+ AND (codec.hardware on both sides OR codec.allow_software)
+```
+
+`allow_software` defaults to `false` for AV1 (battery cost too high), `true` for H.264 (cheap SW fallback).
+
+### Per-codec details
+
+| ID | Codec | Encoder priority |
+|---|---|---|
+| 9 | H.264 baseline | VideoToolbox / MediaCodec / NVENC / QSV / AMF / VAAPI; OpenH264 SW |
+| 10 | H.264 main | Same HW; same SW |
+| 11 | H.265 main | VideoToolbox A10+ / MediaCodec / NVENC GTX 9xx+ / QSV Skylake+; x265 SW (slow, disabled by default) |
+| 12 | AV1 | VideoToolbox M3+/A17+ / MediaCodec SD8G3+ / NVENC RTX 40+; SVT-AV1 SW (gated) |
+| 13 | VP9 | Reserved; may not implement |
+
+### Framer reuse
+
+The 16 B `MediaHeader` carries `codec_id`. The framer doesn't care which codec — it fragments NALs (for H.264/H.265) or OBUs (for AV1) into MTU-sized chunks, sets `KeyFrame`/`FrameEnd` bits, and passes payload through. Per-codec parameter sets (SPS/PPS for H.264/H.265, sequence header OBU for AV1) ship on the signal stream.
+
+### Mid-call codec switch
+
+Optional in v1. If implemented:
+- Sender sends `SignalMessage::CodecSwitch { stream_id, new_codec_id, parameter_sets }`.
+- Receiver swaps decoder and emits PLI to force a clean keyframe.
+
+## Implementation outline
+
+1. `CodecCapability` declaration + serde (additive change).
+2. HW probe at session start (per platform).
+3. Picker logic in `CallOffer`/`CallAnswer` flow.
+4. H.265 encoder/decoder wrappers (VideoToolbox + MediaCodec).
+5. AV1 encoder/decoder wrappers, gated on HW (SVT-AV1 fallback behind flag).
+6. Prometheus: `wzp_session_codec_id_total{codec}` for telemetry on actual codec usage.
+
+## Acceptance criteria
+
+- Two macOS clients (M1 + M3) pick H.265 by default; M3 + iPhone 15 Pro pick AV1.
+- M1 + Android device without H.265 HW picks H.264.
+- Codec selection is deterministic given both sides' capabilities.
+- AV1 refused on devices without HW unless `allow_software` flag explicitly set.
+
+## Rollout gates
+
+- H.264 baseline + main: ship with PRD #5.
+- H.265: enable by default once HW probe accuracy verified on 5+ macOS + 5+ Android devices.
+- AV1: 20 % of session-start probes must report HW encode capability before enabling by default. Until then, available only via debug flag.
+
+## Risks
+
+- **AV1 SW encode torches battery.** Mitigation: HW gate is mandatory; SW fallback off by default.
+- **H.265 patent surface.** Mitigation: rely on platform-provided HW encoders (license covered upstream); avoid shipping x265 binary.
+- **HW probe lies on some Android devices.** Mitigation: in-session fallback if encoder errors at start; degrade one codec tier.
+
+## Effort
+
+- H.265 wrappers: 3 d (T5.4)
+- AV1 wrappers + HW gate: 5 d (T6.1)
+- Picker + capability declaration: 1 d
+
+Total: ~9 engineer-days, in Waves 5–6.
diff --git a/vault/PRDs/PRD-video-quality-priority.md b/vault/PRDs/PRD-video-quality-priority.md
new file mode 100644
index 0000000..0b7e22f
--- /dev/null
+++ b/vault/PRDs/PRD-video-quality-priority.md
@@ -0,0 +1,165 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Video Quality Controller + PriorityMode
+
+> **Status:** proposed
+> **Resolves:** Road-to-video Phase V5 (video adaptive controller, audio-priority gate, ScreenShare slide-mode).
+> **Depends on:** PRD #3 (BWE), PRD #5 (video v1).
+
+## Problem
+
+Audio and video share a finite bandwidth budget. The FaceTime model — audio absolute priority, video elastic on top — is right for the default voice/video call, but it's wrong for screen-share / presentation where a frozen slide deck is worse than slightly degraded audio.
+
+We need: a single `VideoQualityController` consuming BWE, with a policy gate driven by a user/product-selectable `PriorityMode`.
+
+## Goals
+
+- `PriorityMode` enum carried on `QualityProfile`.
+- Per-mode allocation gates: `AudioFirst`, `VideoFirst`, `ScreenShare`, `Balanced`.
+- Mid-call `SetPriorityMode` signal for runtime override.
+- ScreenShare slide-fallback: when bandwidth drops below SD video floor, encoder switches to single-I-frame-every-N-seconds mode (no wire format change).
+- Sensible defaults per call type (voice/video call → AudioFirst; presentation app → ScreenShare).
+
+## Non-goals
+
+- Multi-stream priority (e.g., one HD + one screen-share in the same session — separate work).
+- Custom user-defined modes; only the four enum variants.
+
+## Design
+
+### `PriorityMode`
+
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PriorityMode {
+ AudioFirst, // default for voice/video calls
+ VideoFirst, // user override
+ ScreenShare, // video + slide fallback; audio = intelligible speech only
+ Balanced, // proportional split
+}
+```
+
+Carried on `QualityProfile`:
+
+```rust
+pub struct QualityProfile {
+ ...
+ pub priority_mode: PriorityMode, // default AudioFirst
+ pub video_bitrate_kbps: Option,
+ pub video_resolution: Option<(u16, u16)>,
+ pub video_fps: Option,
+}
+```
+
+Mid-call change:
+
+```rust
+SignalMessage::SetPriorityMode {
+ version: u8,
+ mode: PriorityMode,
+}
+```
+
+### Allocation gates
+
+```
+let bwe = bandwidth_estimator.target_send_bps();
+
+match priority_mode {
+ AudioFirst => {
+ audio_budget = max(24_kbps, audio_tier_min); // audio floor first
+ video_budget = bwe.saturating_sub(audio_budget);
+ // video → 0 before audio degrades below floor
+ }
+ VideoFirst => {
+ video_budget = max(video_floor, target_video_bps);
+ audio_budget = bwe.saturating_sub(video_budget);
+ // audio degrades to Opus 16k floor first
+ }
+ ScreenShare => {
+ // Audio gets just enough for intelligible speech.
+ audio_budget = 16_kbps;
+ video_budget = bwe.saturating_sub(audio_budget);
+ if video_budget < SD_VIDEO_FLOOR {
+ encoder.set_mode(EncoderMode::SlideFallback);
+ }
+ }
+ Balanced => {
+ audio_budget = (bwe as f64 * 0.15) as u64;
+ video_budget = bwe - audio_budget;
+ }
+}
+```
+
+### `VideoQualityController`
+
+```rust
+pub struct VideoQualityController {
+ bwe: Arc,
+ mode: AtomicU8, // PriorityMode
+ encoder: Arc,
+ loss_pct: AtomicU8,
+ rtt_ms: AtomicU32,
+ encoder_queue_ms: AtomicU32,
+}
+
+impl VideoQualityController {
+ pub fn tick(&self) {
+ let budget = self.allocate();
+ let target = self.derive_target(budget); // (bitrate, fps, resolution, layer)
+ self.encoder.set_target(target);
+ }
+}
+```
+
+`derive_target` maps `(budget, loss, rtt, queue)` to encoder parameters via a step table. Smoothed; no jumps larger than 2× per second.
+
+### ScreenShare slide-fallback
+
+Pure encoder policy:
+- Normal video: continuous frames, target fps (5–15 for screen content).
+- When `video_budget < SD_VIDEO_FLOOR` (e.g., 150 kbps): switch to slide mode.
+- Slide mode: emit one high-quality I-frame every 2–5 s. No P-frames. Encoder prefers H.265 or AV1 (text legibility).
+- Wire format: `KeyFrame=1` on every packet, `FrameEnd=1` on last packet of slide. No new fields.
+
+Receiver doesn't know slide mode is on — just sees keyframes arriving slowly.
+
+### Defaults
+
+| Product flow | Default mode |
+|---|---|
+| Voice call | AudioFirst (no video) |
+| Video call | AudioFirst |
+| Screen share | ScreenShare |
+| User toggle in settings | VideoFirst or Balanced |
+
+## Implementation outline
+
+1. `PriorityMode` enum + serde + `QualityProfile` field (T5.1).
+2. `SetPriorityMode` signal variant (T5.1).
+3. `VideoQualityController::new` + `tick` (T5.2).
+4. Per-mode allocation gates (T5.2).
+5. `EncoderMode::SlideFallback` in `wzp-video` (T5.3).
+6. Integration: `CallEngine` honors `SetPriorityMode` within 1 s.
+7. UI plumbing for runtime toggle (out of scope here; tracked by platform team).
+
+## Acceptance criteria
+
+- 100 kbps shaped link, `AudioFirst`: audio holds Opus 24 k, video drops to 0.
+- 100 kbps shaped link, `ScreenShare`: audio holds Opus 16 k, video in slide mode emits 1 I-frame / 3 s.
+- 100 kbps shaped link, `VideoFirst`: audio drops to Opus 16 k, video holds floor.
+- 5 Mbps link, `AudioFirst`: video reaches HD within 10 s.
+- `SetPriorityMode` mid-call applied within 1 s.
+
+## Risks
+
+- **Mode flapping under unstable BWE.** Mitigation: 10 s dwell time before allowing mode-driven encoder reconfiguration.
+- **Slide mode mistaken for poor connection by users.** Mitigation: UI indicator distinguishing "slide mode active" from "poor connection".
+- **AudioFirst floor too aggressive for low-bandwidth music calls.** Mitigation: when audio profile is `Opus 64k music`, floor raised to 48 k.
+
+## Effort
+
+~6 engineer-days (Wave 5 tasks T5.1–T5.3).
diff --git a/vault/PRDs/PRD-video-simulcast.md b/vault/PRDs/PRD-video-simulcast.md
new file mode 100644
index 0000000..b83019f
--- /dev/null
+++ b/vault/PRDs/PRD-video-simulcast.md
@@ -0,0 +1,111 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Simulcast + Per-Receiver Layer Selection
+
+> **Status:** proposed
+> **Resolves:** Road-to-video Phases V5 + V6 (simulcast at sender, layer selection at SFU).
+> **Depends on:** PRD #5 (video v1), PRD #7 (VideoQualityController).
+
+## Problem
+
+In a multi-peer video room, peers have wildly different link quality. A single uplink stream forces a choice: encode for the worst peer (everyone sees SD) or encode for the best peer (poor peers drop out). Simulcast solves this — sender uploads multiple independent layers, and the SFU forwards the appropriate layer to each receiver based on their current quality.
+
+WZP's v2 wire format already reserves `stream_id: u8` for this. This PRD wires it up.
+
+## Goals
+
+- Sender emits 2–3 simultaneous H.264/H.265/AV1 streams per source (different bitrate/resolution).
+- Each layer tagged by `stream_id` (0 = base/SD, 1 = mid/HD, 2 = high/FHD).
+- SFU selects per-receiver which layer to forward, based on that receiver's last `QualityReport` / BWE.
+- Layer switches are seamless (next keyframe boundary) and don't require sender involvement.
+- Mixed-quality rooms work: best peer gets FHD, worst peer gets SD, no peer holds the room back.
+
+## Non-goals
+
+- SVC (per-layer temporal scalability within one bitstream). Simulcast achieves the same outcome with simpler encoder.
+- Audio simulcast (audio is small; not worth the encode cost).
+
+## Design
+
+### Sender side
+
+Three encoder instances per source:
+
+| `stream_id` | Resolution | Target bitrate | Frame rate |
+|---|---|---|---|
+| 0 (low) | 480×270 | 150 kbps | 15 fps |
+| 1 (mid) | 960×540 | 600 kbps | 30 fps |
+| 2 (high) | 1920×1080 | 2.5 Mbps | 30 fps |
+
+Resolution/bitrate ladder configurable per profile. Encoders share input frames (downsample for low/mid).
+
+Each layer is an independent stream with its own `sequence`, `timestamp_ms`, and FEC blocks. Identified on the wire by `stream_id` byte in `MediaHeader` v2.
+
+### SFU forwarding
+
+`RoomManager` per-receiver state:
+
+```rust
+pub struct ReceiverState {
+ fingerprint: Fingerprint,
+ bwe_kbps: AtomicU32,
+ loss_pct: AtomicU8,
+ selected_layer: AtomicU8, // per (sender, source_stream)
+}
+```
+
+Layer selection logic (run periodically per receiver):
+
+```
+if receiver.bwe_kbps > HIGH_THRESHOLD && receiver.loss_pct < 2:
+ selected_layer = high
+elif receiver.bwe_kbps > MID_THRESHOLD:
+ selected_layer = mid
+else:
+ selected_layer = low
+```
+
+Hysteresis: must hold new tier for 3 s before switching.
+
+On layer switch:
+- SFU continues forwarding the old layer until the next keyframe arrives on the new layer.
+- If no keyframe on the new layer within 500 ms, SFU emits PLI to sender for that layer.
+
+### Per-layer keyframe cache
+
+PRD #5 keyframe cache extended: one cache entry per `(room, sender, stream_id)`. New joiner gets the most recent keyframe from the layer matched to their BWE.
+
+### Layer-aware PLI suppression
+
+PLI is layer-scoped. Sender refreshes only the requested layer, not all three.
+
+## Implementation outline
+
+1. `VideoQualityController` extended to drive 3 encoder instances per source (T5.5).
+2. Frame distributor: downsample input frame for low/mid layers before encode.
+3. Per-layer state on `MediaHeader` (already in v2 via `stream_id`).
+4. SFU `ReceiverState` and selection logic (T5.6).
+5. Per-layer keyframe cache (extension of PRD #5).
+6. Per-layer PLI plumbing.
+7. Telemetry: `wzp_room_layer_distribution{stream_id}` histogram.
+
+## Acceptance criteria
+
+- 3-encoder uplink works on M1 within 8 % CPU at 1080p30 / 540p30 / 270p15.
+- 4-peer room with shaped links (5 Mbps, 1 Mbps, 500 kbps, 100 kbps): each peer receives the highest layer their link supports.
+- Layer switch under improving link conditions occurs within 5 s of bandwidth recovery.
+- No peer's bandwidth degradation holds back any other peer.
+
+## Risks
+
+- **3-encoder CPU cost on mid/low-end Android.** Mitigation: dynamic layer count — drop high layer if encoder queue grows; some devices may only support 2 layers.
+- **Frame-rate drift between layers** (independent encoders running). Mitigation: shared frame clock; low/mid layers drop frames if needed to stay aligned.
+- **SFU per-receiver state bloat.** Mitigation: only allocate state for active receivers; 80 B/receiver/sender bound.
+- **Layer switch causing brief visible flicker.** Mitigation: switch only at keyframes; UI may show momentary resolution change but no glitch.
+
+## Effort
+
+~7 engineer-days (Wave 5 tasks T5.5 + T5.6).
diff --git a/vault/PRDs/PRD-video-v1.md b/vault/PRDs/PRD-video-v1.md
new file mode 100644
index 0000000..e9e4c15
--- /dev/null
+++ b/vault/PRDs/PRD-video-v1.md
@@ -0,0 +1,137 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Video v1 — H.264 Single-Layer
+
+> **Status:** proposed
+> **Resolves:** Road-to-video Phases V3 + V4 (encoder/decoder, framer, NACK, keyframe cache).
+> **Depends on:** PRD #1 (wire format v2), PRD #3 (TransportFeedback + BWE).
+
+## Problem
+
+WZP has no video path. Add a working unidirectional video call (macOS↔macOS first, then Android↔macOS) using H.264 baseline, with loss recovery appropriate for lossy mobile links.
+
+## Goals
+
+- New `wzp-video` crate parallel to `wzp-codec`.
+- H.264 baseline encode/decode using platform hardware encoders.
+- NAL fragmentation and access-unit reassembly conformant to our 16 B `MediaHeader` v2.
+- NACK loop for P-frame loss (RTT-gated).
+- Dynamic FEC ratio boost on I-frame packets.
+- SFU keyframe cache for fast join-to-first-frame.
+- PLI suppression at SFU to bound upstream keyframe-request traffic.
+
+## Non-goals
+
+- Multi-codec negotiation (PRD #6).
+- Simulcast or per-receiver layer selection (PRD #8).
+- VideoQualityController logic beyond a fixed bitrate target (PRD #7).
+- Native camera capture pipelines (separate platform work).
+
+## Design
+
+### `wzp-video` crate
+
+```
+wzp-video/
+ src/
+ encoder.rs # trait VideoEncoder
+ # VideoToolboxEncoder (macOS)
+ # MediaCodecEncoder (Android, JNI)
+ # OpenH264Encoder (software fallback)
+ decoder.rs # trait VideoDecoder; mirror per-platform
+ framer.rs # H.264 NAL fragmentation to MTU-sized chunks
+ depacketizer.rs # Reassemble NALs, emit access units
+ keyframe.rs # Keyframe request handling, sender + receiver
+ config.rs # SPS/PPS shipment over signal stream
+```
+
+### Framing
+
+One access unit (frame) → N packets, each ≤ `MTU - 16 (header) - 16 (AEAD tag)`.
+
+- `sequence` global per (session, stream_id), advances per packet.
+- `timestamp_ms` is presentation time, equal across all packets of a single access unit.
+- `KeyFrame` bit set on every packet of an I-frame.
+- `FrameEnd` bit set on the last packet of the access unit.
+- `fec_block_id` per access unit (u16 in v2, large blocks).
+
+Parameter sets (SPS/PPS) ride on the **signal stream**, not media datagrams. Sent at session start and on codec change. Reliable, ordered, one-time.
+
+### NACK loop
+
+```
+SignalMessage::Nack {
+ version: u8,
+ stream_id: u8,
+ seqs: Vec, // missing P-frame packets
+}
+```
+
+Receiver behavior:
+- If access unit incomplete after `frame_interval` ms:
+ - If `RTT < 2 × frame_interval`: emit `Nack`.
+ - Else: emit `PictureLossIndication`.
+- Backoff: max 1 Nack per (stream, seq) per 2 × RTT.
+
+Sender behavior:
+- On `Nack`: re-transmit if packet is still in send buffer (last 500 ms).
+- On `PictureLossIndication`: emit a fresh I-frame within 200 ms.
+
+### Dynamic FEC on I-frames
+
+Encoder marks packets belonging to I-frames. FEC layer applies a higher ratio (default 0.5) to I-frame blocks, vs. nominal (0.1) for P-frames. Configurable.
+
+### SFU keyframe cache
+
+`RoomManager` maintains per `(room, sender, stream_id)`:
+
+```rust
+struct KeyframeCache {
+ packets: Vec, // most recent complete I-frame
+ timestamp_ms: u32,
+ sequence_first: u32,
+}
+```
+
+On new participant join, cache is replayed before live forwarding starts. Eliminates 2 s black-screen-on-join.
+
+Cache TTL: replaced whenever a new complete I-frame arrives.
+
+### PLI suppression
+
+If ≥ 2 receivers PLI within 200 ms for the same `(sender, stream_id)`, the SFU emits one `KeyframeRequest` upstream, not N. Tracked per-(sender, stream).
+
+## Implementation outline
+
+1. `wzp-video` crate scaffold (T4.1).
+2. Framer/depacketizer with property tests (T4.1).
+3. VideoToolbox encoder/decoder (macOS) (T4.2).
+4. MediaCodec encoder/decoder (Android, JNI) (T4.3).
+5. NACK signal + sender/receiver state machines (T4.4).
+6. I-frame FEC ratio hint plumbed from encoder to FEC layer (T4.5).
+7. SFU keyframe cache (T4.6).
+8. PLI suppression (T4.7).
+9. End-to-end test: macOS sender → relay → macOS receiver, 5 min call, < 1 % loss network.
+
+## Acceptance criteria
+
+- Unidirectional H.264 720p30 call macOS↔macOS, CPU < 5 % on M1.
+- Android↔macOS works with MediaCodec (surface-texture path).
+- Black-screen-on-join < 200 ms when keyframe cache is warm.
+- Under 5 % synthetic packet loss at 50 ms RTT: NACK recovery keeps video smooth, < 1 keyframe / 2 s.
+- Under 5 % synthetic packet loss at 300 ms RTT: PLI fallback fires, keyframe rate ~ 1 / s.
+- Upstream PLI traffic at SFU < 2 / s under simulated mass packet loss with 8 receivers.
+
+## Risks
+
+- **MediaCodec surface-texture edge cases.** Per-device matrix; software fallback path mandatory.
+- **VideoToolbox H.264 baseline restrictions** (some profiles are main-only in HW). Mitigation: profile detection at session start.
+- **NACK storm under heavy loss.** Mitigation: rate cap (max 50 Nacks/s/receiver) and exponential backoff.
+- **Keyframe cache memory footprint** (one I-frame per active stream per room). Mitigation: cap cache at 200 KB; if exceeded, drop and rely on PLI.
+
+## Effort
+
+~3 weeks (Wave 4 tasks T4.1–T4.7).
diff --git a/vault/PRDs/PRD-wire-format-v2.md b/vault/PRDs/PRD-wire-format-v2.md
new file mode 100644
index 0000000..01582ab
--- /dev/null
+++ b/vault/PRDs/PRD-wire-format-v2.md
@@ -0,0 +1,119 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD: Wire Format v2
+
+> **Status:** proposed
+> **Resolves:** Audit W1, W4, W9, W10. Keystone prerequisite for video and per-`MediaType` conformance enforcement.
+> **References:** `docs/WZP-SPEC.md`, `docs/ROAD-TO-VIDEO.md` Phase V1, `docs/PROTOCOL-AUDIT.md`.
+
+## Problem
+
+v1 wire format has four structural problems that compound the moment video lands:
+
+- 16-bit sequence wraps in ~21 min at 50 pps (W1)
+- MiniHeader has no sequence delta, so a missed full header desyncs (W4)
+- CodecID is 4 bits → 16 codec slots, 9 used; video will exhaust it (W9)
+- No `MediaType` field → SFU cannot distinguish audio/video/data without a codec lookup (W10)
+
+Fixing these post-deployment is a multi-client coordinated break. Fix once, before video.
+
+## Goals
+
+- One wire-format change resolves W1, W4, W9, W10 and reserves headroom for the next decade.
+- v1 and v2 can co-exist briefly during rollout via explicit version handshake (typed rejection, not silent corruption).
+- All 571 audio tests pass under v2.
+
+## Non-goals
+
+- Backward wire compatibility (we will not encode v2 atop v1 — it is a clean break).
+- Video framing rules themselves (covered by PRD #5).
+- New codec IDs beyond reservation (covered by PRDs #5, #6).
+
+## Design
+
+### `MediaHeader` v2 (16 bytes, byte-aligned)
+
+```
+Byte 0: version (u8) 0x02
+Byte 1: flags (u8) bit 7: T (FEC repair)
+ bit 6: Q (QualityReport trailer present, inside AEAD)
+ bit 5: KeyFrame (video I-frame packet)
+ bit 4: FrameEnd (last packet of access unit)
+ bits 3-0: reserved (must be 0)
+Byte 2: media_type (u8) 0=audio, 1=video, 2=data, 3=control
+Byte 3: codec_id (u8)
+Byte 4: stream_id (u8) 0=base; simulcast layers 1..N
+Byte 5: fec_ratio (u8) 0..200 → 0.0..2.0
+Bytes 6-9: sequence (u32 BE)
+Bytes 10-13: timestamp_ms (u32 BE)
+Bytes 14-15: fec_block_id (u16 BE)
+ audio: low 8 bits = block_id, high 8 = symbol_idx
+ video: full u16 block_id (large FEC blocks for I-frames)
+```
+
+Justification for byte alignment (16 B over 12 B packed) is in `ROAD-TO-VIDEO.md` Phase V1; benchmarks showed ≤ 0.32 % stream overhead delta across all scenarios.
+
+### `MiniHeader` v2 (5 bytes)
+
+```
+[FRAME_TYPE_MINI = 0x01]
+Byte 0: seq_delta (u8) ← new; resolves W4
+Bytes 1-2: timestamp_delta_ms (u16 BE)
+Bytes 3-4: payload_len (u16 BE)
+```
+
+Audio only. Video pays the full 16 B header per packet (no clean periodic structure to compress).
+
+### Version negotiation
+
+`CallOffer` and `CallAnswer` already carry supported profiles. Add:
+
+```rust
+struct CallOffer {
+ ...
+ protocol_version: u8, // 2 in v2 clients
+ supported_versions: Vec, // e.g. [2]
+}
+```
+
+Relay/peer side:
+- If `protocol_version` is supported → proceed.
+- If unsupported → close with `Hangup::ProtocolVersionMismatch { server_supported: Vec }`.
+
+No silent fallback. No mixed-version session.
+
+### Sequencing semantics
+
+- `sequence` is per-stream, monotonic, u32, wraps at 2^32. At 1000 pps that is ~50 days — effectively no wrap.
+- `timestamp_ms` is per-stream, milliseconds since session start, u32, ~49.7 days range. Rebase behavior at rekey: **does not reset** — kept monotonic across rekeys (documented as a separate hardening item in PRD #4, W3).
+- `fec_block_id` is per-stream, u16, wraps at 2^16. With ≥ 5-frame blocks that is ~22 minutes at 50 pps — adequate but PRD #4 (W2) covers epoch counter if needed.
+
+## Implementation outline
+
+1. New types in `wzp-proto/src/packet.rs` behind a `proto-v2` feature flag.
+2. Round-trip tests for `MediaHeader v2` and `MiniHeader v2` (encode → decode → assert equal).
+3. Migrate `wzp-codec` encode path to emit v2 headers.
+4. Migrate `wzp-client` and `wzp-relay` parse paths.
+5. `CallOffer`/`CallAnswer` carry `protocol_version` and `supported_versions`.
+6. Typed `Hangup::ProtocolVersionMismatch` reason.
+7. Remove v1 emission path once all 571 tests pass under v2 (drop the feature flag default).
+8. Add migration note to `WZP-SPEC.md`.
+
+## Acceptance criteria
+
+- All 571 audio tests pass with v2 headers.
+- A v1 client connecting to a v2 relay receives `Hangup::ProtocolVersionMismatch` within 1 RTT.
+- Wire-level capture confirms 16 B `MediaHeader` and 5 B `MiniHeader` on real audio calls.
+- `media_type` byte readable by relay without parsing `codec_id` (enables PRD #2 Tier A separation).
+
+## Risks
+
+- **Stranding old clients.** Force-update prompt in UI; release notes; staged rollout (relays accept v1 for 2 weeks before flipping to reject).
+- **MiniHeader 5 B vs 4 B regression check.** Trunking math reconfirmed (cap of 10 binds before MTU — no change).
+
+## Effort
+
+~2.5 engineer-days (Wave 1 tasks T1.1–T1.3 in the index).
diff --git a/vault/PRDs/README.md b/vault/PRDs/README.md
new file mode 100644
index 0000000..b040efa
--- /dev/null
+++ b/vault/PRDs/README.md
@@ -0,0 +1,156 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# PRD Index — Protocol v2, Video, Abuse Mitigation
+
+> Coordinated worklist that addresses (a) the P0/P1 findings in `docs/PROTOCOL-AUDIT.md`, (b) the video roadmap in `docs/ROAD-TO-VIDEO.md`, and (c) the relay abuse vectors in `docs/ATTACK-SURFACE-RELAY-ABUSE.md`. Each item below links to its own PRD.
+
+## Why a combined plan
+
+The three documents share substantial structure:
+
+- **Wire format v2** (audit P0: W1, W4, W9, W10) is the prerequisite for video framing **and** for per-`MediaType` conformance enforcement against abuse. One change resolves three pressures.
+- **TransportFeedback + BWE** (audit P1: W6, W14) is mandatory for video, materially improves audio adaptation, and gives the relay another observable for abuse detection.
+- **Relay conformance enforcement** (attack surface Tiers A–G) is independently valuable for audio today, and the v2 `MediaType` bit lets it scale cleanly to video.
+
+Sequencing matters. Implementing v2 wire format **before** any video work or any deep abuse mitigation avoids two compatibility breaks.
+
+## PRD catalog
+
+| # | PRD | Resolves | Status |
+|---|---|---|---|
+| 1 | [PRD-wire-format-v2](./PRD-wire-format-v2.md) | Audit W1, W4, W9, W10; prereq for #5/#6/#7/#8 and Tier F of #2 | proposed |
+| 2 | [PRD-relay-conformance](./PRD-relay-conformance.md) | Attack-surface Tiers A–G | proposed |
+| 3 | [PRD-transport-feedback-bwe](./PRD-transport-feedback-bwe.md) | Audit W6, W14 | proposed |
+| 4 | [PRD-protocol-hardening](./PRD-protocol-hardening.md) | Audit W2, W3, W5, W11, W12, W13 (security + correctness batch) | proposed |
+| 5 | [PRD-video-v1](./PRD-video-v1.md) | Road-to-video Phases V3 + V4 (H.264 single-layer, NACK, keyframe cache) | proposed |
+| 6 | [PRD-video-multicodec](./PRD-video-multicodec.md) | H.265 + AV1 negotiation (road-to-video Phase V3 codec rollout) | proposed |
+| 7 | [PRD-video-quality-priority](./PRD-video-quality-priority.md) | Road-to-video Phase V5 (VideoQualityController + PriorityMode + ScreenShare) | proposed |
+| 8 | [PRD-video-simulcast](./PRD-video-simulcast.md) | Road-to-video Phases V5 + V6 (simulcast, per-receiver layer selection at SFU) | proposed |
+
+Native capture pipelines (road-to-video Phase V7) are out of scope here — they sit downstream of #5 and are platform team work; tracked separately.
+
+## Dependency graph
+
+```
+ ┌───────────────────────────────┐
+ │ #1 Wire format v2 (keystone) │
+ └────────┬──────────────────────┘
+ │
+ ┌──────────────────────┼────────────────────────┐
+ │ │ │
+ ▼ ▼ ▼
+┌──────────────┐ ┌──────────────────┐ ┌──────────────────────┐
+│ #2 Conformance│ │ #3 Transport │ │ #4 Protocol │
+│ Tier A-G │ │ Feedback + BWE │ │ Hardening │
+└──────┬────────┘ └────────┬─────────┘ └──────────────────────┘
+ │ Tier A-D first │
+ │ Tier F needs traffic │
+ │ baseline │
+ │ │
+ │ ┌───────▼────────┐
+ │ │ #5 Video v1 │
+ │ │ (H.264 + NACK) │
+ │ └───────┬────────┘
+ │ │
+ │ ┌──────────────┼──────────────┐
+ │ │ │ │
+ │ ▼ ▼ ▼
+ │ ┌────────┐ ┌──────────────┐ ┌──────────────┐
+ │ │ #6 │ │ #7 Video │ │ #8 Simulcast │
+ │ │ Multi- │ │ Quality + │ │ │
+ │ │ codec │ │ Priority │ │ │
+ │ └────────┘ └──────────────┘ └──────────────┘
+ │
+ └──> #2 Tier F (video) — needs #5 in production traffic to baseline
+```
+
+## Combined task list
+
+Ordered by dependency and risk. Each task references its PRD.
+
+### Wave 1 — Foundation (week 1)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T1.1 Land 16 B MediaHeader v2 + 5 B MiniHeader v2 in `wzp-proto` | #1 | 1 d | New types behind feature flag; old paths still work |
+| T1.2 Update `wzp-codec` + `wzp-client` + `wzp-relay` to emit v2 | #1 | 1 d | All audio tests pass under v2 |
+| T1.3 Protocol version negotiation in `CallOffer/CallAnswer` (typed `Hangup::ProtocolVersionMismatch`) | #1 + #4 (W12) | 0.5 d | v1 clients rejected with clear reason |
+| T1.4 `QualityReport` trailer moved inside AEAD payload (or AAD-bound) | #4 (W5) | 0.5 d | Security fix, audit log |
+| T1.5 Anti-replay window made per-stream and per-MediaType configurable | #4 (W11) | 0.5 d | Audio=64, video=1024 ready |
+
+### Wave 2 — Feedback + abuse mitigation (week 2)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T2.1 `SignalMessage::TransportFeedback` variant | #3 | 1 d | Wire path; not yet consumed |
+| T2.2 `BandwidthEstimator` in `wzp-proto` (cwnd + remb fusion) | #3 | 2 d | Prometheus output |
+| T2.3 `AdaptiveQualityController` consumes BWE | #3 | 1 d | Audio upgrade decisions use bandwidth, not just loss |
+| T2.4 `wzp-relay/src/conformance.rs` — Tier A (bitrate ceilings per CodecID) | #2 | 1 d | Bulk-tunnel abuse killed |
+| T2.5 Tier B (packet-rate cap) + Tier C (timestamp consistency) | #2 | 1 d | Loud abuse caught |
+| T2.6 Prometheus: `relay_conformance_*` counters + observable histograms | #2 | 0.5 d | Baseline data collection starts |
+
+### Wave 3 — Protocol hardening (week 3)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T3.1 `fec_block_id` widened to u16 in v2 | #4 (W2) | 0.5 d | No FEC collisions on slow joiners |
+| T3.2 Document `timestamp_ms` rebase behavior at rekey | #4 (W3) | 0.5 d | Spec clarity |
+| T3.3 `SignalMessage` variants prefixed with `version: u8` | #4 (W12) | 0.5 d | Future-proof signaling |
+| T3.4 `RoomManager` migrated to `DashMap>>` | #4 (W13) | 2 d | No per-packet global lock |
+| T3.5 Tier E (per-fingerprint / per-IP token bucket) wired to featherChat auth | #2 | 1.5 d | Aggregate quota enforced |
+| T3.6 Tier D (per-codec packet-size sanity) | #2 | 0.5 d | Sneaky-payload class caught |
+
+### Wave 4 — Video v1 (weeks 4–6)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T4.1 `wzp-video` crate scaffold; H.264 framer + depacketizer | #5 | 4 d | NAL fragmentation, access-unit reassembly |
+| T4.2 VideoToolbox encoder + decoder (macOS) | #5 | 3 d | Unidirectional video macOS↔macOS |
+| T4.3 MediaCodec encoder + decoder (Android, via JNI) | #5 | 5 d | Android video path |
+| T4.4 NACK loop (`SignalMessage::Nack`) + RTT-gated policy | #5 | 2 d | P-frame loss recovery |
+| T4.5 Dynamic FEC ratio on I-frames (encoder hint to FEC layer) | #5 | 1 d | I-frame survivability without round trip |
+| T4.6 SFU keyframe cache per (room, sender, stream) | #5 | 2 d | < 200 ms join-to-first-frame |
+| T4.7 PLI suppression at SFU | #5 | 1 d | Bounded upstream PLI rate |
+
+### Wave 5 — Quality, codecs, simulcast (weeks 7–9)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T5.1 `PriorityMode` enum on `QualityProfile` + `SignalMessage::SetPriorityMode` | #7 | 1 d | Wire path |
+| T5.2 `VideoQualityController` with per-mode allocation gates | #7 | 3 d | AudioFirst / VideoFirst / Balanced live |
+| T5.3 ScreenShare mode: slide-fallback encoder policy | #7 | 2 d | Presentation use case viable |
+| T5.4 H.265 encoder/decoder (reuse framer) | #6 | 3 d | Codec negotiation cascade live |
+| T5.5 Simulcast: encoder emits 3 layers; `stream_id` carries layer | #8 | 4 d | Layer-tagged uplink |
+| T5.6 Per-receiver layer selection at SFU | #8 | 3 d | Mixed-quality rooms work |
+| T5.7 Tier F (entropy scorer) — audio variant first, baselined from Wave 2/3 data | #2 | 3 d | Covert-tunnel pressure |
+| T5.8 Tier G (response policy + audit log) | #2 | 1 d | Operational |
+
+### Wave 6 — AV1 + Tier F video (weeks 10+)
+
+| Task | PRD | Effort | Output |
+|---|---|---|---|
+| T6.1 AV1 encoder/decoder with HW detection (SVT-AV1 fallback) | #6 | 5 d | Top-tier efficiency on capable HW |
+| T6.2 Tier F video scorer (keyframe periodicity, I/P frame-size ratio, BWE responsiveness) | #2 | 3 d | Video abuse detection |
+| T6.3 Federated reputation gossip (optional) | #2 | 4 d | Cross-relay abuse mitigation |
+
+## Risk register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| v2 wire format break strands old clients | High | High | Typed `Hangup::ProtocolVersionMismatch`, clear UI, force update prompt |
+| BWE oscillation regresses audio adaptation | Med | Med | Behind feature flag; A/B with shadow Prometheus before flipping default |
+| Conformance Tier A false positives | Low | High | Math-derived ceilings × 1.5; counter-only mode for 1 week before enforcement |
+| `DashMap` migration regresses room semantics | Med | Med | Integration tests for federation + trunking before merging |
+| Android MediaCodec edge cases (Nothing A059 baseline) | High | Med | Per-device test matrix; software fallback path |
+| AV1 software encode torches battery | High | Low | HW probe at session start; refuse AV1 if no HW encode |
+| Tier F false-positives on edge cases (e.g., long silences in lectures) | Med | High | Verdict-only mode + 30 s window minimum + Suspect tier escalation |
+
+## Open product questions (not blocking)
+
+- Anonymous vs. authenticated quota split — numbers TBD pending Prometheus baseline.
+- Whether to expose `PriorityMode` UI for end users or only via product preset (call vs. screen-share).
+- AV1 rollout gate: 5 %? 20 %? of sessions reporting HW support before enabling by default.
+- Federated reputation gossip is powerful but introduces a poisoning surface; decision deferred to after Wave 5.
diff --git a/vault/PRDs/TASKS.md b/vault/PRDs/TASKS.md
new file mode 100644
index 0000000..324b4dc
--- /dev/null
+++ b/vault/PRDs/TASKS.md
@@ -0,0 +1,1907 @@
+---
+tags: [prd, wzp]
+type: prd
+---
+
+# Haiku-Ready Task Breakdown
+
+> Companion to `docs/PRD/README.md`. Every task here is sized for an agent with limited context to pick up cold: it names exact files, exact symbols, and exact verification commands. Do tasks in order within a wave; waves are dependency-ordered.
+
+---
+
+## Agent operating instructions — read first
+
+You are an implementing agent. The human is the reviewer. **Your job is not done when the code compiles; it is done when the reviewer has approved your report.** Read this section before touching any task.
+
+### Workflow per task
+
+1. **Claim the task.** Move its status in the [Status board](#status-board) at the bottom of this file from `Open` → `In Progress`. Add your handle / model name and a UTC timestamp.
+2. **Implement.** Follow the steps in the task block exactly. If the steps don't fit reality (e.g. line numbers shifted, a referenced symbol doesn't exist, the API has evolved), **stop and surface the mismatch in your report** — do not improvise silently.
+3. **Verify.** Run the exact commands in the task's `Verify` block. Capture their output verbatim — the reviewer will read it.
+4. **Write the report.** Create `docs/PRD/reports/T-report.md` using the template below. One report per task. No exceptions.
+5. **Commit.** One commit per task. Message: `T: `. The report file is part of the same commit.
+6. **Move to review.** Update the [Status board](#status-board): `In Progress` → `Pending Review`. Add a link to the report path.
+7. **Stop.** Do NOT start the next task until the reviewer marks the previous one `Approved`. If they mark it `Changes Requested`, address the feedback in a follow-up commit, update the report, and move back to `Pending Review`.
+
+### Follow-up tasks (`T.`)
+
+When the reviewer approves a task but finds small non-blocking issues (missing docs, stale comments, minor cleanups), they **spawn new follow-up tasks** instead of carrying the work forward into an unrelated task. The parent task stays `Approved` and closed.
+
+Follow-up IDs extend the parent: `T1.1.1`, `T1.1.2`, etc. They are first-class tasks — full block in this file with `Files`, `Steps`, `Verify`, `Done when` — and they show up in the status board between the parent and the next sibling (`T1.1.1` sits between `T1.1` and `T1.2`).
+
+Agents pick up follow-ups in the same order they pick up wave tasks. A follow-up never blocks the next wave task: e.g. `T1.2` is claimable even if `T1.1.1` is still `Open`, unless the follow-up's body explicitly says otherwise (it usually doesn't).
+
+Reviewers, when spawning a follow-up:
+
+1. Add a numbered task block in the right section of this file (just below the parent).
+2. Add a status-board row between the parent and the next sibling.
+3. Reference the follow-up in the parent report's reviewer notes (e.g. "Spawned T1.1.1, T1.1.2 to track follow-ups.").
+
+### Report template
+
+Every report lives at `docs/PRD/reports/T-report.md` and uses this template:
+
+```markdown
+# T —
+
+**Status:** Pending Review
+**Agent:**
+**Started:**
+**Completed:**
+**Commit:**
+**PRD:** ../.md
+
+## What I changed
+
+- `:` —
+- `:` —
+- (etc.)
+
+## Why these choices
+
+<2-6 sentences explaining any non-obvious decision: why this signature, why
+this default, why this error type, why a deviation from the task steps if any.
+If you followed the steps verbatim, say "Followed steps T.1 through T.N
+without deviation." and that's enough.>
+
+## Deviations from the task spec
+
+
+
+## Verification output
+
+For each `Verify` command in the task block, paste the actual output. Trim
+benign noise (warnings already present on main) but never trim test failure
+output.
+
+```
+$ cargo test -p wzp-proto media_header_v2_roundtrip
+running 1 test
+test packet::tests::media_header_v2_roundtrip ... ok
+
+test result: ok. 1 passed; 0 failed; ...
+```
+
+## Test summary
+
+- Tests added:
+- Tests modified:
+- Workspace test count before: / after:
+- `cargo clippy --workspace --all-targets -- -D warnings`: pass / fail (or N known-debt errors in ; see PROTOCOL-AUDIT.md)
+- `cargo fmt --all -- --check`: pass / fail
+
+## Risks / follow-ups
+
+
+
+## Reviewer checklist (filled in by reviewer)
+
+- [ ] Code matches PRD intent
+- [ ] Verification output is real (re-run if suspicious)
+- [ ] No backward-incompat surprises
+- [ ] Tests cover the new behavior
+- [ ] Approved
+```
+
+### Coding standards — non-negotiable
+
+These apply to every task. They are NOT repeated in each task block. Violating them is grounds for `Changes Requested` even if the code works.
+
+1. **Rust edition 2024** (set in workspace root). No exceptions.
+2. **`cargo fmt --all`** must produce a clean diff before commit. CI will reject otherwise.
+3. **`cargo clippy --workspace --all-targets -- -D warnings`** must pass in crates you touch. Do not `#[allow(...)]` to silence — fix the root cause. If a lint is genuinely wrong, justify the allow in the report. Pre-existing debt in other crates (documented in `PROTOCOL-AUDIT.md`) is not your problem.
+4. **No `unwrap()` / `expect()` in production code paths.** Tests are fine. Production: return a typed error.
+5. **No `println!` / `eprintln!`.** Use `tracing::{debug,info,warn,error}!`. The crates are already wired for tracing.
+6. **No new dependencies without justification.** If a task forces a new crate, list it under "Risks / follow-ups" in the report so the reviewer can sanity-check the supply chain.
+7. **One commit per task** — see workflow. Don't squash multiple tasks. Don't split a task across commits unless the task itself instructs you to.
+8. **Never modify `Cargo.lock` by hand.** Run a real build; commit the resulting lockfile delta.
+9. **Public API changes need rustdoc.** Every new `pub fn`, `pub struct`, `pub enum`, or `pub trait` gets a `///` doc comment. Private items: doc only when non-obvious.
+10. **Tests live with code.** `#[cfg(test)] mod tests { ... }` next to the code under test. Integration tests in `crates//tests/.rs` only when they exercise multiple modules end-to-end.
+11. **Async: tokio only.** Do not introduce `async-std` or `smol`. Spawn via `tokio::spawn`, not raw futures.
+12. **Wire format types live in `wzp-proto`.** Do not redefine `MediaHeader`, `SignalMessage`, or codec/quality types in another crate. Re-export if needed.
+13. **No emoji in code or commit messages** unless the surrounding context already uses them.
+14. **No AI-attribution lines in commit messages.** Plain `T: ` body, that's it.
+15. **Comments:** comment WHY, never WHAT. If the code needs a WHAT comment, rename the symbol instead. See repo-root CLAUDE.md (if present) for global guidance.
+16. **Don't take destructive actions.** Specifically: never `git reset --hard`, `git push --force`, drop database tables, delete branches, or touch CI configs without the reviewer asking. If you think you need to, stop and ask in your report.
+17. **Auto mode is not a license to skip these.** Even when the harness is set to autonomous execution, the workflow (report → Pending Review → wait for Approved) is mandatory.
+
+### Environment-blocked tasks → file Blocked, do not ship stubs
+
+You operate on a macOS host without an Android device or NDK build pipeline. For any task that requires Android-target compilation, an Android emulator/device, or Hetzner remote-builder access:
+
+- **Do not "wrote it but couldn't test it" the deliverable.** A file with `#[cfg(target_os = "android")]` AMediaCodec code that has never been compiled for an Android target is not a completed task — it's an aspirational PR.
+- **File a `Blocked` report** with whatever partial work made sense (e.g., trait surface, codec-agnostic helpers, cfg-gating fixes for non-Android builds). The reviewer will either pick up the Android validation themselves or close the task as `Deferred (reviewer-owned)`.
+- Existing Deferred-but-reviewer-owned tasks today: **T4.3.1.1** (Android MediaCodec target-compile + device instrumentation). Skip past it.
+
+### When to stop and ask
+
+Stop and write a report with status `Blocked` (not `Pending Review`) if any of these happen:
+
+- A task step references code that doesn't exist.
+- A test fails for reasons unrelated to your change.
+- The workspace doesn't build at HEAD before you started (the baseline is dirty).
+- You need to make a meaningful design decision the task didn't anticipate.
+- A "Verify" command produces output you don't understand.
+
+A `Blocked` report is not a failure — it is the correct outcome when the task spec is wrong or incomplete.
+
+---
+
+## How to read a task
+
+Each task block has:
+
+- **ID & title** — `T.` like `T1.1`.
+- **PRD** — link to the parent PRD for the "why".
+- **Effort** — rough hours for a junior dev with this doc + the repo.
+- **Files** — exact paths you will edit.
+- **Context** — 2-4 lines on what's there today.
+- **Steps** — numbered, do them in order.
+- **Verify** — exact commands; output must match.
+- **Done when** — single-line acceptance.
+
+---
+
+## Environment setup (do this once)
+
+```bash
+# All commands assume CWD = /Users/manwe/CascadeProjects/warzonePhone
+cargo build --workspace # baseline: must succeed
+cargo test --workspace --no-fail-fast # baseline: should be 571 pass / 0 fail (non-Android subset)
+```
+
+If either fails before you start a task, stop and report — the tree is dirty.
+
+### Conventions
+
+- Format on save: `cargo fmt --all` after any code change.
+- Lints: `cargo clippy --workspace --all-targets -- -D warnings` must pass in crates you touch before commit. Pre-existing debt in other crates is documented in `PROTOCOL-AUDIT.md`.
+- Tests live next to code under `#[cfg(test)]` modules, or in `crates//tests/`.
+- Wire format types: `crates/wzp-proto/src/packet.rs` is authoritative. Do not duplicate field semantics elsewhere.
+- Commit one task per commit. Reference task ID in commit message: `T1.1: widen MediaHeader to v2`.
+
+### Useful greps
+
+```bash
+grep -rn "MediaHeader::" --include="*.rs" # 6 files outside tests
+grep -rn "MiniHeader::" --include="*.rs"
+grep -rn "SignalMessage::" --include="*.rs"
+grep -rn "CodecId::" --include="*.rs"
+```
+
+---
+
+# Wave 1 — Foundation (target: 1 week)
+
+Goal: v2 wire format lands cleanly. Audio works under v2. Old clients are politely rejected.
+
+---
+
+## T1.1 — Add v2 `MediaHeader` type
+
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 3 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Context
+Today `MediaHeader` is defined at line 20 of `packet.rs` with `WIRE_SIZE = 12` (line 47). Fields are bit-packed across the first two bytes. It is constructed in tests starting around line 1229.
+
+### Steps
+
+1. Open `crates/wzp-proto/src/packet.rs`.
+2. **Do not delete** the existing `MediaHeader`. Rename it in-place to `MediaHeaderV1` (also rename `WIRE_SIZE` consts only on that struct). Keep all impls.
+3. Below the `MediaHeaderV1` block, add a new `MediaHeader` struct (16 bytes, byte-aligned):
+
+ ```rust
+ /// 16-byte v2 media header. See docs/PRD/PRD-wire-format-v2.md.
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+ pub struct MediaHeader {
+ pub version: u8, // always 2
+ pub flags: u8, // bit 7 T, bit 6 Q, bit 5 KeyFrame, bit 4 FrameEnd
+ pub media_type: MediaType, // u8 wire repr
+ pub codec_id: CodecId,
+ pub stream_id: u8,
+ pub fec_ratio: u8, // 0..200 → 0.0..2.0
+ pub seq: u32,
+ pub timestamp: u32,
+ pub fec_block: u16,
+ }
+
+ impl MediaHeader {
+ pub const WIRE_SIZE: usize = 16;
+ pub const VERSION: u8 = 2;
+
+ pub fn write_to(&self, buf: &mut impl BufMut) {
+ buf.put_u8(self.version);
+ buf.put_u8(self.flags);
+ buf.put_u8(self.media_type.to_wire());
+ buf.put_u8(self.codec_id.to_wire());
+ buf.put_u8(self.stream_id);
+ buf.put_u8(self.fec_ratio);
+ buf.put_u32(self.seq);
+ buf.put_u32(self.timestamp);
+ buf.put_u16(self.fec_block);
+ }
+
+ pub fn read_from(buf: &mut impl Buf) -> Option {
+ if buf.remaining() < Self::WIRE_SIZE { return None; }
+ let version = buf.get_u8();
+ if version != Self::VERSION { return None; }
+ let flags = buf.get_u8();
+ let media_type = MediaType::from_wire(buf.get_u8())?;
+ let codec_id = CodecId::from_wire(buf.get_u8())?;
+ let stream_id = buf.get_u8();
+ let fec_ratio = buf.get_u8();
+ let seq = buf.get_u32();
+ let timestamp = buf.get_u32();
+ let fec_block = buf.get_u16();
+ Some(Self { version, flags, media_type, codec_id, stream_id, fec_ratio, seq, timestamp, fec_block })
+ }
+
+ pub const FLAG_REPAIR: u8 = 0b1000_0000;
+ pub const FLAG_QUALITY: u8 = 0b0100_0000;
+ pub const FLAG_KEYFRAME: u8 = 0b0010_0000;
+ pub const FLAG_FRAME_END: u8 = 0b0001_0000;
+
+ pub fn is_repair(&self) -> bool { self.flags & Self::FLAG_REPAIR != 0 }
+ pub fn has_quality(&self) -> bool { self.flags & Self::FLAG_QUALITY != 0 }
+ pub fn is_keyframe(&self) -> bool { self.flags & Self::FLAG_KEYFRAME != 0 }
+ pub fn is_frame_end(&self) -> bool { self.flags & Self::FLAG_FRAME_END != 0 }
+ }
+ ```
+
+4. `MediaType` and `CodecId::to_wire` (8-bit) come from T1.2 and T1.3 — add a `// TODO(T1.2)` placeholder if those aren't merged yet (use `u8` directly).
+5. Add a round-trip test next to the existing tests:
+
+ ```rust
+ #[test]
+ fn media_header_v2_roundtrip() {
+ let h = MediaHeader {
+ version: 2, flags: MediaHeader::FLAG_QUALITY,
+ media_type: MediaType::Audio, codec_id: CodecId::Opus24k,
+ stream_id: 0, fec_ratio: 50,
+ seq: 0xDEAD_BEEF, timestamp: 0x1234_5678,
+ fec_block: 0xABCD,
+ };
+ let mut buf = BytesMut::with_capacity(MediaHeader::WIRE_SIZE);
+ h.write_to(&mut buf);
+ assert_eq!(buf.len(), 16);
+ let mut cursor = std::io::Cursor::new(&buf[..]);
+ let parsed = MediaHeader::read_from(&mut cursor).unwrap();
+ assert_eq!(h, parsed);
+ }
+ ```
+
+### Verify
+
+```bash
+cargo test -p wzp-proto media_header_v2_roundtrip
+cargo build --workspace
+```
+
+### Done when
+- New test passes. Workspace still builds. `MediaHeaderV1` still exists (we delete it later in T1.5).
+
+---
+
+## T1.1.1 — Add rustdoc on `MediaHeaderV2` public fields
+
+- **Parent:** T1.1 (Approved)
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 15 min
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Context
+T1.1 added `MediaHeaderV2` with inline `//` comments on the public fields. The pre-existing `MediaHeaderV1` uses `///` rustdoc on every public field (coding standard #9 — public items need rustdoc). Match the existing pattern.
+
+### Steps
+
+1. Open `crates/wzp-proto/src/packet.rs`. Find `pub struct MediaHeaderV2`.
+2. For each public field, replace the trailing `//` comment with a leading `///` doc comment. Example transformation:
+
+ Before:
+ ```rust
+ pub struct MediaHeaderV2 {
+ pub version: u8, // always 2
+ pub flags: u8, // bit 7 T, bit 6 Q, bit 5 KeyFrame, bit 4 FrameEnd
+ ...
+ }
+ ```
+
+ After:
+ ```rust
+ pub struct MediaHeaderV2 {
+ /// Protocol version. Always `2` on the wire; `read_from` rejects anything else.
+ pub version: u8,
+ /// Bit-packed flags. See `FLAG_REPAIR`, `FLAG_QUALITY`, `FLAG_KEYFRAME`, `FLAG_FRAME_END`.
+ pub flags: u8,
+ ...
+ }
+ ```
+
+3. Document the four `FLAG_*` constants with `///` too. One line each is fine.
+4. Document the four `is_*` / `has_*` accessor methods with `///`. One line each.
+5. The `media_type: u8` field gets a doc comment that mentions the `TODO(T1.2)` — keep that TODO inline.
+
+### Verify
+
+```bash
+cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" # should be empty
+cargo clippy -p wzp-proto --all-targets -- -D warnings -W missing_docs # should pass
+```
+
+### Done when
+- All public items on `MediaHeaderV2` carry `///` doc comments.
+- `cargo doc -p wzp-proto --no-deps` emits no "missing documentation" warnings for `MediaHeaderV2`.
+
+---
+
+## T1.1.2 — Refresh stale test-count figures in docs
+
+- **Parent:** T1.1 (Approved)
+- **PRD:** `PRD-wire-format-v2.md` (housekeeping)
+- **Effort:** 30 min
+- **Files:**
+ - `docs/ARCHITECTURE.md`
+ - `docs/PRD/TASKS.md` (the Environment setup block)
+ - Any other doc referencing "272 tests"
+
+### Context
+The original audit and the TASKS environment-setup block reference a workspace test count of **272**. The actual non-Android workspace baseline measured during T1.1 is **564** (with 1 added test → 565 after T1.1). The 272 figure is stale.
+
+### Steps
+
+1. Grep for the stale figure across the docs:
+ ```bash
+ grep -rn "272 tests\|272 pass\|272 total" docs/
+ ```
+2. For each hit, replace with the current count. **Re-measure before writing the number.**
+ ```bash
+ cargo test --workspace --no-fail-fast 2>&1 | grep "test result:" | awk '{s+=$4} END {print s}'
+ # ... this gives a rough total; sanity-check against per-crate output
+ ```
+3. If `wzp-android` cannot build on the dev machine (no NDK), note that the count excludes `wzp-android` and is the "non-Android subset".
+4. Update the per-crate Test Coverage table in `docs/ARCHITECTURE.md` (search for "## Test Coverage") with the new per-crate counts.
+
+### Verify
+
+```bash
+grep -rn "272 tests\|272 pass" docs/ # should be empty
+```
+
+### Done when
+- No doc references the stale 272 figure.
+- ARCHITECTURE.md test coverage table reflects current per-crate counts.
+
+---
+
+## T1.2 — Add `MediaType` enum
+
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 1 h
+- **Files:**
+ - `crates/wzp-proto/src/codec_id.rs` (or new sibling file `media_type.rs`)
+ - `crates/wzp-proto/src/lib.rs` (re-export)
+
+### Steps
+
+1. Create `crates/wzp-proto/src/media_type.rs`:
+ ```rust
+ use serde::{Deserialize, Serialize};
+
+ #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+ #[repr(u8)]
+ pub enum MediaType {
+ Audio = 0,
+ Video = 1,
+ Data = 2,
+ Control = 3,
+ }
+
+ impl MediaType {
+ pub const fn to_wire(self) -> u8 { self as u8 }
+ pub const fn from_wire(v: u8) -> Option {
+ match v {
+ 0 => Some(Self::Audio),
+ 1 => Some(Self::Video),
+ 2 => Some(Self::Data),
+ 3 => Some(Self::Control),
+ _ => None,
+ }
+ }
+ }
+ ```
+2. In `crates/wzp-proto/src/lib.rs`, add `pub mod media_type;` and `pub use media_type::MediaType;`.
+
+### Verify
+```bash
+cargo build -p wzp-proto
+cargo test -p wzp-proto
+```
+
+### Done when
+`MediaType` is importable as `wzp_proto::MediaType`.
+
+---
+
+## T1.2.1 — Add rustdoc on `MediaType` variants and methods
+
+- **Parent:** T1.2 (Approved)
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 10 min
+- **Files:**
+ - `crates/wzp-proto/src/media_type.rs`
+
+### Context
+T1.2 created `MediaType` with a one-line top-level doc comment but no `///` rustdoc on the variants (`Audio`, `Video`, `Data`, `Control`) or methods (`to_wire`, `from_wire`). Coding standard #9 — public items need rustdoc. Same shape of follow-up as T1.1.1.
+
+### Steps
+
+1. Open `crates/wzp-proto/src/media_type.rs`.
+2. Add a `///` doc comment to each variant. Examples (do not just copy — pick what's accurate):
+ ```rust
+ pub enum MediaType {
+ /// Encoded speech / music (Opus, Codec2, ComfortNoise).
+ Audio = 0,
+ /// Encoded video access unit (H.264, H.265, AV1; PRD-video-multicodec).
+ Video = 1,
+ /// Opaque payload not interpreted by the relay (reserved).
+ Data = 2,
+ /// In-band control message carried on the media plane (reserved).
+ Control = 3,
+ }
+ ```
+3. Add a `///` doc on `to_wire` and `from_wire`. One line each is fine — explain the wire byte mapping and the `None` case.
+
+### Verify
+```bash
+cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" || echo "no missing-doc warnings"
+cargo clippy -p wzp-proto --all-targets -- -D warnings -W missing_docs
+```
+
+### Done when
+- All variants and methods on `MediaType` carry `///` doc comments.
+- `cargo doc -p wzp-proto --no-deps` emits no "missing documentation" warnings for `MediaType`.
+
+---
+
+## T1.3 — Widen `CodecId` wire representation to u8
+
+- **PRD:** `PRD-wire-format-v2.md` (resolves audit W9)
+- **Effort:** 1 h
+- **Files:**
+ - `crates/wzp-proto/src/codec_id.rs`
+
+### Context
+`CodecId::to_wire` returns `self as u8` (already u8 in memory). The "4 bits on wire" is enforced by how `MediaHeaderV1` packs it. With v2 the wire byte is full 8-bit — so reserve more IDs without touching `to_wire`/`from_wire` for the existing variants.
+
+### Steps
+
+1. In `codec_id.rs`, **reserve** (but do not implement) future codec IDs by adding doc comments after `Opus64k = 8`:
+ ```rust
+ // Reserved for video codecs; implementations land in PRD-video-multicodec.
+ // 9 => H264 baseline
+ // 10 => H264 main
+ // 11 => H265 main
+ // 12 => AV1
+ // 13 => VP9
+ ```
+2. **Do not** add new variants yet — that happens in T4.x once `wzp-video` exists.
+3. Add a regression test confirming `from_wire(9..=255)` returns `None`:
+ ```rust
+ #[test] fn codec_id_unknown_values_rejected() {
+ for v in 9u8..=255 { assert!(CodecId::from_wire(v).is_none(), "v={v}"); }
+ }
+ ```
+
+### Verify
+```bash
+cargo test -p wzp-proto codec_id_unknown_values_rejected
+```
+
+### Done when
+Test passes. Existing audio tests still pass.
+
+---
+
+## T1.4 — Add v2 `MiniHeader` with `seq_delta`
+
+- **PRD:** `PRD-wire-format-v2.md` (resolves audit W4)
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Context
+Existing `MiniHeader` is 4 bytes at line 501. `MiniFrameContext::expand` infers `seq` by `wrapping_add(1)` (line ~553) — a missed full header desyncs. v2 carries explicit `seq_delta`.
+
+### Steps
+
+1. Rename existing `MiniHeader` → `MiniHeaderV1` and `MiniFrameContext` → `MiniFrameContextV1`. Keep impls intact.
+2. Add new `MiniHeader` (5 bytes):
+ ```rust
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
+ pub struct MiniHeader {
+ pub seq_delta: u8, // packets since baseline; 1 in steady state
+ pub timestamp_delta_ms: u16,
+ pub payload_len: u16,
+ }
+
+ impl MiniHeader {
+ pub const WIRE_SIZE: usize = 5;
+
+ pub fn write_to(&self, buf: &mut impl BufMut) {
+ buf.put_u8(self.seq_delta);
+ buf.put_u16(self.timestamp_delta_ms);
+ buf.put_u16(self.payload_len);
+ }
+
+ pub fn read_from(buf: &mut impl Buf) -> Option {
+ if buf.remaining() < Self::WIRE_SIZE { return None; }
+ Some(Self {
+ seq_delta: buf.get_u8(),
+ timestamp_delta_ms: buf.get_u16(),
+ payload_len: buf.get_u16(),
+ })
+ }
+ }
+ ```
+3. Add `MiniFrameContext` (no `V1` suffix) tracking v2 `MediaHeader`:
+ ```rust
+ #[derive(Clone, Debug, Default)]
+ pub struct MiniFrameContext {
+ last: Option,
+ }
+ impl MiniFrameContext {
+ pub fn update(&mut self, h: &MediaHeader) { self.last = Some(*h); }
+ pub fn expand(&mut self, m: &MiniHeader) -> Option {
+ let base = self.last.as_ref()?;
+ let mut e = *base;
+ e.seq = base.seq.wrapping_add(m.seq_delta as u32);
+ e.timestamp = base.timestamp.wrapping_add(m.timestamp_delta_ms as u32);
+ self.last = Some(e);
+ Some(e)
+ }
+ }
+ ```
+4. Add round-trip test mirroring `T1.1`.
+
+### Verify
+```bash
+cargo test -p wzp-proto mini
+```
+
+### Done when
+v2 mini header round-trips. v1 type still compiles.
+
+---
+
+## T1.4.1 — Add rustdoc on `MiniHeaderV2` / `MiniFrameContextV2` public items
+
+- **Parent:** T1.4 (Approved)
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 15 min
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Context
+T1.4 added v2 types with top-level `///` docs on the structs themselves but no `///` rustdoc on the fields or methods. Same shape of follow-up as T1.1.1 and T1.2.1 — coding standard #9.
+
+### Steps
+
+1. Open `crates/wzp-proto/src/packet.rs`. Find `pub struct MiniHeaderV2`.
+2. Add `///` doc comments to each public field:
+ - `seq_delta` — explain it's the count of packets since the baseline (typically 1), and that explicit deltas resolve audit W4 (one missed full header no longer desyncs).
+ - `timestamp_delta_ms` — milliseconds since baseline's `timestamp`.
+ - `payload_len` — bytes of payload following the mini header.
+3. Document `WIRE_SIZE`, `write_to`, `read_from`. One line each. Mention that `read_from` returns `None` on short buffer.
+4. Same treatment for `MiniFrameContextV2`: doc the `update` and `expand` methods. `expand` should note that it returns `None` if no baseline has been set.
+
+### Verify
+```bash
+cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" || echo "no missing-doc warnings"
+cargo clippy -p wzp-proto --all-targets -- -D warnings -W missing_docs
+```
+
+### Done when
+- All public items on `MiniHeaderV2` and `MiniFrameContextV2` carry `///` doc comments.
+- `cargo doc -p wzp-proto --no-deps` emits no "missing documentation" warnings for these types.
+
+---
+
+## T1.5 — Migrate emit/parse sites to v2
+
+- **PRD:** `PRD-wire-format-v2.md`
+- **Effort:** 4 h
+- **Files (touch all that use `MediaHeader::`):**
+ - `crates/wzp-proto/src/packet.rs`
+ - `crates/wzp-client/src/call.rs`
+ - `crates/wzp-relay/src/room.rs`
+ - `crates/wzp-relay/src/pipeline.rs`
+ - `crates/wzp-android/src/engine.rs`
+
+### Context
+Only 6 production files outside `packet.rs` reference `MediaHeader::`. Confirm with:
+```bash
+grep -rln "MediaHeader::" crates/ | grep -v target
+```
+
+### Steps
+
+1. For each file in the list above, replace v1 construction patterns with v2. The audio fields are unchanged in semantics; new fields default as follows:
+ - `version: 2`
+ - `flags: 0` (set `FLAG_QUALITY` where the v1 code set `has_quality_report = true`, etc.)
+ - `media_type: MediaType::Audio`
+ - `stream_id: 0`
+ - `fec_ratio: ` (convert range)
+ - `seq: old_seq as u32`
+ - `timestamp` unchanged
+ - `fec_block: u16::from(old_fec_block) | (u16::from(old_fec_symbol) << 8)` for audio (low byte block_id, high byte symbol_idx)
+2. Update `MediaHeaderV1`-using parse code identically — convert from u16 seq/u8 block_id to v2 layout at parse boundary.
+3. Search for `WIRE_SIZE` arithmetic and update buffer sizes (12 → 16, 4 → 5).
+4. Delete `MediaHeaderV1`, `MiniHeaderV1`, `MiniFrameContextV1` once everything builds.
+
+### Verify
+```bash
+cargo build --workspace
+cargo test --workspace --no-fail-fast
+# Expected: all 571 tests still pass
+```
+
+### Done when
+- Workspace builds clean.
+- All audio tests pass.
+- No reference to `MediaHeaderV1` / `MiniHeaderV1` anywhere.
+
+---
+
+## T1.5.1 — Remove `unwrap()` from `encode_compact`
+
+- **Parent:** T1.5 (Approved)
+- **PRD:** `PRD-wire-format-v2.md` (cleanup)
+- **Effort:** 20 min
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Context
+`encode_compact` calls `ctx.last_header().unwrap()` at line ~262. The invariant ("a full header is forced on the first frame and every `MINI_FRAME_FULL_INTERVAL` frames") makes it logically safe, but standard #4 forbids `unwrap()` in production paths. Carried over from v1.
+
+### Steps
+
+1. Open `crates/wzp-proto/src/packet.rs`. Find `pub fn encode_compact`.
+2. Replace the `unwrap()` with one of:
+ - **Recommended:** when `ctx.last_header()` is `None`, fall back to emitting a full frame and force `frames_since_full = 0`. This makes the invariant explicit in the code rather than implicit.
+ - Alternative: return `Result` with a typed `NoBaselineHeader` variant. More invasive (changes the public signature).
+3. Add a test that constructs a fresh `MiniFrameContext` and calls `encode_compact` immediately — without the existing fix, this would panic; with the fix, it should emit a full frame.
+
+### Verify
+```bash
+cargo test -p wzp-proto encode_compact
+cargo clippy -p wzp-proto --all-targets -- -D warnings
+grep -n "\.unwrap()" crates/wzp-proto/src/packet.rs | grep -v "#\[cfg(test)\]\|^[[:space:]]*//\|tests::"
+# the unwrap on line ~262 should be gone; only test-code unwraps remain.
+```
+
+### Done when
+- No `unwrap()` in `encode_compact` or anywhere else in non-test code in `packet.rs`.
+- New test passes; existing `encode_compact` tests still pass.
+
+---
+
+## T1.5.2 — Workspace clippy hygiene + document pre-existing debt
+
+- **Parent:** T1.5 (Approved)
+- **PRD:** `PRD-wire-format-v2.md` (process)
+- **Effort:** 30 min
+- **Files:**
+ - `docs/PROTOCOL-AUDIT.md` (add a "Known pre-existing clippy debt" section)
+ - This file (TASKS.md) — update report template instruction to require workspace clippy
+
+### Context
+T1.5 review revealed two issues: (1) the agent ran only `-p wzp-proto` clippy, not workspace; (2) workspace clippy fails with 9 `wzp-codec` errors and 3 `warzone-protocol` errors. Both are pre-existing (verified against HEAD~1). Need to capture these as known debt so they don't stay invisible, and tighten the report template to require workspace clippy on every task.
+
+### Steps
+
+1. Run `cargo clippy --workspace --all-targets -- -D warnings 2>&1 | grep -E "^error\[|could not compile" | head -50` and capture the output.
+2. Add a section to `docs/PROTOCOL-AUDIT.md` named **"Known pre-existing clippy debt (as of T1.5.2)"** listing the failing crates and a brief description per error category (manual ASCII case-cmp, manual arithmetic check, loop index, etc.). Reference the commit SHA of HEAD at time of measurement.
+3. In `docs/PRD/TASKS.md`, update the report template's "Test summary" section: change `cargo clippy --workspace --all-targets -- -D warnings: pass / fail` to `cargo clippy --workspace --all-targets -- -D warnings: pass / fail (or N known-debt errors in ; see PROTOCOL-AUDIT.md)`. This makes the expectation explicit and gives agents a way to acknowledge known debt without re-discussing it every task.
+4. Optional: add a `make clippy-baseline` or similar script to `tools/` that prints expected-error count so agents can detect regressions.
+
+### Verify
+```bash
+grep -c "Known pre-existing clippy debt" docs/PROTOCOL-AUDIT.md # >= 1
+grep -c "or N known-debt errors" docs/PRD/TASKS.md # >= 1
+```
+
+### Done when
+- PROTOCOL-AUDIT.md has the known-debt section with current error counts and categories.
+- TASKS.md report template reflects the new expectation.
+- A follow-up cleanup task is created in the audit (separate from this one) to actually fix the pre-existing debt over time.
+
+---
+
+## T1.6 — Protocol version negotiation in handshake
+
+- **PRD:** `PRD-wire-format-v2.md` + `PRD-protocol-hardening.md` (W12)
+- **Effort:** 3 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs` (extend `SignalMessage`)
+ - `crates/wzp-client/src/handshake.rs`
+ - `crates/wzp-relay/src/handshake.rs`
+
+### Steps
+
+1. In `packet.rs`, add to `CallOffer`:
+ ```rust
+ #[serde(default = "default_proto_version")]
+ pub protocol_version: u8,
+ #[serde(default = "default_supported_versions")]
+ pub supported_versions: Vec,
+ ```
+ Helpers:
+ ```rust
+ fn default_proto_version() -> u8 { 2 }
+ fn default_supported_versions() -> Vec { vec![2] }
+ ```
+2. Add a new `Hangup` reason variant. Find `SignalMessage::Hangup` (look for the `Hangup` variant in the enum near the bottom) and add to the reason enum / fields:
+ ```rust
+ ProtocolVersionMismatch { server_supported: Vec },
+ ```
+ If `reason` is a `String`, instead add a structured variant `SignalMessage::ProtocolVersionMismatch { server_supported: Vec }` and use that.
+3. In `crates/wzp-relay/src/handshake.rs`, after parsing `CallOffer`, check `protocol_version == 2`. If not, send `ProtocolVersionMismatch` and close.
+4. In `crates/wzp-client/src/handshake.rs`, set the field on outgoing `CallOffer`; on receiving the mismatch variant, return a typed error.
+
+### Verify
+```bash
+cargo test -p wzp-relay handshake
+cargo test -p wzp-client handshake
+```
+
+### Done when
+A v1-style offer (missing `protocol_version` field — serde default makes it 2 in this codebase, so explicitly test with `protocol_version: 1`) is rejected with the typed signal.
+
+---
+
+## T1.7 — Move `QualityReport` trailer inside AEAD payload
+
+- **PRD:** `PRD-protocol-hardening.md` (W5)
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-client/src/call.rs` (encode/decode paths)
+ - `crates/wzp-crypto/src/session.rs` (verify AEAD boundary)
+
+### Context
+A `QualityReport` (4 bytes) is appended to media packets when the `Q` flag is set. The flag is in the (plaintext, AAD-bound) header; the trailer must sit **inside** the AEAD payload so stripping it corrupts decryption.
+
+### Steps
+
+1. Grep for the encode site:
+ ```bash
+ grep -rn "has_quality_report\|FLAG_QUALITY\|QualityReport" crates/wzp-client/src/call.rs
+ ```
+2. Find where `QualityReport::write_to` (or `put_*` calls) writes the 4 bytes. Confirm it writes into the buffer that is **then** passed to `encrypt_in_place` / `seal` — not after.
+3. If currently appended *after* AEAD seal: refactor so the order is:
+ - Write `MediaHeader` (becomes AAD).
+ - Write payload.
+ - Write `QualityReport` trailer if Q flag set.
+ - AEAD-seal the (payload + trailer) bytes with header as AAD.
+4. Mirror on decode side.
+5. Add a test that tampers with the trailer post-encrypt and asserts decrypt fails.
+
+### Verify
+```bash
+cargo test -p wzp-client quality_report_aead
+cargo test -p wzp-crypto
+```
+
+### Done when
+- Tamper test passes (decryption fails on trailer tamper).
+- Round-trip with quality flag set still works.
+
+---
+
+## T1.8 — Per-stream anti-replay window with configurable size
+
+- **PRD:** `PRD-protocol-hardening.md` (W11)
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-crypto/src/anti_replay.rs`
+ - `crates/wzp-crypto/src/session.rs` (or wherever the window is owned)
+
+### Steps
+
+1. Today the window is fixed 64 packets. Make it constructible with size:
+ ```rust
+ impl AntiReplay { pub fn with_window(size: usize) -> Self { ... } }
+ ```
+2. The session owner (search `AntiReplay::new`) is updated to allocate per `(stream_id, MediaType)`. Use a `HashMap<(u8, MediaType), AntiReplay>` keyed on the v2 header fields.
+3. Default sizes:
+ - `Audio`: 64
+ - `Video`: 1024
+ - `Data`: 256
+ - `Control`: 32
+
+### Verify
+```bash
+cargo test -p wzp-crypto anti_replay
+```
+
+### Done when
+- A new test confirms a 200-packet video burst with one reorder doesn't drop any.
+- Existing audio anti-replay tests pass.
+
+---
+
+# Wave 2 — Feedback + abuse mitigation (target: 1 week)
+
+Goal: BWE drives adaptation. Tier A/B/C conformance running in observe-only mode at the relay.
+
+---
+
+## T2.1 — Add `SignalMessage::TransportFeedback`
+
+- **PRD:** `PRD-transport-feedback-bwe.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Steps
+
+1. Add to the `SignalMessage` enum:
+ ```rust
+ TransportFeedback {
+ #[serde(default)] version: u8, // = 1
+ stream_id: u8,
+ acked_seqs: Vec,
+ nacked_seqs: Vec,
+ remb_bps: u32,
+ recv_time_us: u64,
+ },
+ ```
+2. Add a unit test serializing/deserializing with `bincode` to ensure forward/backward compat.
+
+### Verify
+```bash
+cargo test -p wzp-proto transport_feedback
+```
+
+### Done when
+Variant round-trips. No other code consumes it yet — that's T2.2/T2.3.
+
+---
+
+## T2.2 — `BandwidthEstimator` in `wzp-proto::bandwidth`
+
+- **PRD:** `PRD-transport-feedback-bwe.md`
+- **Effort:** 4 h
+- **Files:**
+ - `crates/wzp-proto/src/bandwidth.rs` (already exists — extend, don't replace)
+ - `crates/wzp-transport/src/path_monitor.rs` (read existing cwnd/RTT exposure)
+
+### Context
+`bandwidth.rs` already exists (14 KB). Read it first. The `QuinnPathSnapshot` type exposes `loss_pct`, `rtt_ms` today; add `cwnd_bps`, `bytes_in_flight` if missing.
+
+### Steps
+
+1. Read `crates/wzp-transport/src/path_monitor.rs` to find how Quinn `PathStats` are exposed.
+2. Add to `QuinnPathSnapshot`:
+ ```rust
+ pub cwnd_bytes: u64,
+ pub bytes_in_flight: u64,
+ ```
+ Populate from `quinn::Connection::stats().path`.
+3. In `wzp-proto/src/bandwidth.rs`, add:
+ ```rust
+ pub struct BandwidthEstimator {
+ cwnd_bps: AtomicU64,
+ peer_remb_bps: AtomicU64,
+ smoothed_bps: AtomicU64,
+ }
+ impl BandwidthEstimator {
+ pub fn new() -> Self { ... default ... }
+ pub fn update_from_quinn(&self, snap: &QuinnPathSnapshot) { /* compute cwnd_bps = cwnd_bytes * 8 / rtt_s */ }
+ pub fn update_from_peer(&self, fb_remb_bps: u32) { ... }
+ pub fn target_send_bps(&self) -> u64 {
+ let m = self.cwnd_bps.load(Relaxed).min(self.peer_remb_bps.load(Relaxed));
+ (m as f64 * 0.9) as u64
+ }
+ }
+ ```
+4. EWMA smoothing: half-life 2 s. Update `smoothed_bps` from input on each tick.
+
+### Verify
+```bash
+cargo test -p wzp-proto bandwidth
+cargo test -p wzp-transport
+```
+
+### Done when
+- Unit test: feed scripted cwnd + remb values, assert `target_send_bps` smooths correctly.
+
+---
+
+## T2.3 — Plumb BWE into adaptive controller
+
+- **PRD:** `PRD-transport-feedback-bwe.md`
+- **Effort:** 3 h
+- **Files:**
+ - `crates/wzp-proto/src/quality.rs` (`AdaptiveQualityController`)
+ - `crates/wzp-client/src/call.rs` (instantiate + feed)
+
+### Steps
+
+1. Add a setter to `AdaptiveQualityController`:
+ ```rust
+ pub fn set_bandwidth_estimator(&mut self, bwe: Arc) { self.bwe = Some(bwe); }
+ ```
+2. In the controller's upgrade decision (search for "consecutive_good_reports" or similar threshold logic), add a guard:
+ ```rust
+ if let Some(bwe) = &self.bwe {
+ if bwe.target_send_bps() < self.current_tier_ceiling_bps() * 130 / 100 { return; }
+ }
+ ```
+3. In `call.rs`, instantiate one `Arc` per session, feed it from both send loop (`update_from_quinn` from path snapshot) and recv loop (`update_from_peer` from incoming TransportFeedback), pass to the controller.
+
+### Verify
+```bash
+cargo test -p wzp-proto quality
+```
+
+### Done when
+Existing quality tests pass with BWE attached. New test: scripted "loss = 0, cwnd = 50 kbps" never upgrades past Opus 24k.
+
+---
+
+## T2.4 — Relay conformance: Tier A (bitrate ceiling)
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 3 h
+- **Files:**
+ - `crates/wzp-relay/src/conformance.rs` (new)
+ - `crates/wzp-relay/src/room.rs` (call site)
+
+### Steps
+
+1. Create `crates/wzp-relay/src/conformance.rs`:
+ ```rust
+ use std::sync::atomic::{AtomicU64, Ordering::Relaxed};
+ use std::time::Instant;
+ use wzp_proto::{CodecId, MediaHeader, MediaType};
+
+ pub struct ConformanceMeter {
+ window_start: parking_lot::Mutex,
+ bytes_in_window: AtomicU64,
+ packets_in_window: AtomicU64,
+ last_seq: AtomicU64,
+ last_ts: AtomicU64,
+ }
+
+ #[derive(Debug)]
+ pub enum Violation { BitrateExceeded, PacketRateExceeded, TimestampDrift }
+
+ impl ConformanceMeter {
+ pub fn new() -> Self { ... }
+ pub fn observe(&self, h: &MediaHeader, payload_len: usize, now: Instant) -> Result<(), Violation> {
+ // Tier A
+ let window_bytes = self.bytes_in_window.fetch_add((MediaHeader::WIRE_SIZE + payload_len) as u64, Relaxed);
+ // ... compare against ceiling_bps_for(h.codec_id, h.media_type)
+ }
+ }
+
+ pub fn ceiling_bps(codec: CodecId) -> u64 {
+ let nominal = codec.bitrate_bps() as u64;
+ (nominal * 3 * 115 / 100).max(2_000) // FEC 2.0 + 15% overhead, floor 2 kbps
+ }
+ ```
+2. In `room.rs`, attach one `ConformanceMeter` per participant. Call `observe` on each incoming media packet.
+3. **Observe-only mode for now.** Log violations to `tracing::warn!` and bump a Prometheus counter. Do not close session.
+
+### Verify
+```bash
+cargo test -p wzp-relay conformance
+```
+
+### Done when
+Unit test: synthetic 1 MB/s declared as Opus 24k logs `Violation::BitrateExceeded`.
+
+---
+
+## T2.5 — Tier B (packet-rate) + Tier C (timestamp drift)
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-relay/src/conformance.rs`
+
+### Steps
+
+1. Add packet-rate enforcement: `packets_in_window > max_pps(codec) * 1.5` over a 1 s window → `PacketRateExceeded`.
+2. `max_pps(codec) = 1000 / codec.frame_duration_ms() * 3` (×3 for FEC).
+3. Timestamp drift: track `Δtimestamp / Δseq` over rolling 200-packet window. If outside `frame_duration_ms × [0.5, 2.0]`, log `TimestampDrift`.
+
+### Verify
+```bash
+cargo test -p wzp-relay conformance
+```
+
+### Done when
+Both new tests pass alongside Tier A test.
+
+---
+
+## T2.6 — Prometheus metrics for conformance
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-relay/src/metrics.rs`
+
+### Steps
+
+1. Add counters / histograms:
+ ```rust
+ wzp_relay_conformance_violations_total{tier, codec_id, media_type, verdict}
+ wzp_relay_conformance_bytes_per_session{media_type} histogram
+ wzp_relay_conformance_iat_ms{media_type} histogram
+ ```
+2. Wire `ConformanceMeter` to bump these on `observe`.
+
+### Verify
+```bash
+curl localhost:9090/metrics | grep wzp_relay_conformance
+```
+(after `cargo run -p wzp-relay -- --listen 127.0.0.1:4433 --no-auth` with a synthetic client)
+
+### Done when
+Counters increment under abusive traffic; quiet on legitimate audio.
+
+---
+
+# Wave 3 — Protocol hardening (target: 3-4 days)
+
+---
+
+## T3.1 — Confirm `RoomManager` concurrency (W13)
+
+- **PRD:** `PRD-protocol-hardening.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-relay/src/room.rs`
+
+### Context
+`RoomManager` already uses `DashMap` (verified at line 352). The audit (W13) was based on the older ARCHITECTURE doc which mentioned a single Mutex. The actual remaining contention point is whatever's *inside* `Room` — confirm.
+
+### Steps
+
+1. Read the `Room` struct definition.
+2. If `Room` itself uses fine-grained locks or is `Arc>` already, document this in `PROTOCOL-AUDIT.md` and mark W13 resolved.
+3. If `Room` has a single per-room `Mutex` held during fan-out, identify the hot path and either:
+ - Split fan-out list into `RwLock>` (read-mostly).
+ - Use `ArcSwap>` for lock-free reads.
+4. Run the 40+4 relay integration tests.
+
+### Verify
+```bash
+cargo test -p wzp-relay
+cargo test -p wzp-relay --test federation
+cargo test -p wzp-relay --test handshake_integration
+```
+
+### Done when
+Tests pass + a one-line update in `PROTOCOL-AUDIT.md` noting actual state.
+
+---
+
+## T3.2 — Document `timestamp_ms` rebase across rekey (W3)
+
+- **PRD:** `PRD-protocol-hardening.md`
+- **Effort:** 1 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs` (doc comment on `MediaHeader::timestamp`)
+ - `crates/wzp-crypto/src/rekey.rs` (add comment)
+ - `docs/WZP-SPEC.md`
+ - Add test in `crates/wzp-client/tests/long_session.rs`
+
+### Steps
+
+1. Decision (already made): `timestamp_ms` is monotonic across rekeys. Document inline:
+ ```rust
+ /// Milliseconds since session start. Monotonic for the full session lifetime;
+ /// NOT reset by rekey (rekey changes only key material, not framing state).
+ pub timestamp: u32,
+ ```
+2. In `rekey.rs`, add a comment near the rekey handler confirming sequence + timestamp are untouched.
+3. Add a test that performs 2 rekeys mid-session and asserts `timestamp` continues monotonically.
+
+### Verify
+```bash
+cargo test -p wzp-client --test long_session rekey_timestamp_monotonic
+```
+
+### Done when
+Test passes.
+
+---
+
+## T3.3 — `SignalMessage` version field (W12)
+
+- **PRD:** `PRD-protocol-hardening.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+
+### Steps
+
+1. For each variant of `SignalMessage`, add `#[serde(default)] version: u8` as the first field, with helper `fn default_signal_version() -> u8 { 1 }`.
+2. Add fallback variant for unknown future signals:
+ ```rust
+ #[serde(other)]
+ Unknown,
+ ```
+ (Note: bincode + serde `other` may need a wrapper — research before implementing. If not feasible, document the limitation and skip the `Unknown` arm.)
+3. Decode path: on `Unknown`, log `tracing::warn!("unknown signal variant")` and **do not** close session.
+
+### Verify
+```bash
+cargo test -p wzp-proto signal_message
+```
+
+### Done when
+Existing signal tests pass. Old payloads (without `version` field) still deserialize.
+
+---
+
+## T3.4 — Tier D (per-codec packet size sanity)
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 2 h
+- **Files:**
+ - `crates/wzp-relay/src/conformance.rs`
+
+### Steps
+
+1. Add per-codec typical / max payload table:
+ ```rust
+ pub fn payload_size_bound(codec: CodecId) -> usize {
+ match codec {
+ CodecId::Opus64k => 320, CodecId::Opus48k => 240,
+ CodecId::Opus32k => 200, CodecId::Opus24k => 160,
+ CodecId::Opus16k => 100, CodecId::Opus6k => 90,
+ CodecId::Codec2_3200 => 30, CodecId::Codec2_1200 => 30,
+ CodecId::ComfortNoise => 16,
+ }
+ }
+ ```
+2. Maintain EWMA of payload size per meter. Reject if EWMA exceeds 2× typical for declared codec.
+
+### Verify
+```bash
+cargo test -p wzp-relay conformance_tier_d
+```
+
+### Done when
+Synthetic stream of 1400-byte payloads declared as Codec2_1200 flagged within 5 s.
+
+---
+
+## T3.5 — Tier E (per-fingerprint token bucket)
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 4 h
+- **Files:**
+ - `crates/wzp-relay/src/conformance.rs` (or sibling `quota.rs`)
+ - `crates/wzp-relay/src/auth.rs` (for authed/anon split)
+
+### Steps
+
+1. Implement a simple token bucket per `(fingerprint, src_ip)`:
+ ```rust
+ pub struct TokenBucket {
+ capacity: u64,
+ tokens: AtomicU64,
+ refill_per_sec: u64,
+ last_refill: AtomicU64,
+ }
+ ```
+2. Wire into per-participant forward loop. Refill on each `observe`.
+3. Authed/anon split: authenticated quota = 50 GB/month; anon = 1 GB/month. Per-session cap = 256 kbps audio (5 Mbps video reserved for later).
+4. **Observe-only:** log + counter; do not throttle yet.
+
+### Verify
+```bash
+cargo test -p wzp-relay token_bucket
+```
+
+### Done when
+Unit test: 100 KB at 256 kbps cap consumes no tokens; 1 MB exceeds.
+
+---
+
+# Wave 4 — Video v1 (3 weeks)
+
+See `PRD-video-v1.md` for design.
+
+---
+
+## T4.1 — `wzp-video` crate scaffold + H.264 NAL framer + depacketizer
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 3 d
+- **Files:**
+ - `crates/wzp-video/Cargo.toml`
+ - `crates/wzp-video/src/lib.rs`
+ - `crates/wzp-video/src/framer.rs`
+ - `crates/wzp-video/src/depacketizer.rs`
+ - `crates/wzp-proto/src/codec_id.rs`
+ - `Cargo.toml` (workspace members)
+
+### Context
+
+WZP currently has no video path. Wave 4 adds H.264 baseline single-layer video. T4.1 is the foundation: a new `wzp-video` crate parallel to `wzp-codec`, containing the NAL framer and depacketizer. No platform encoder/decoder yet — that lands in T4.2/T4.3.
+
+### Steps
+
+1. Create `crates/wzp-video` and register it in the workspace `Cargo.toml`.
+2. Add `H264Baseline = 9` to `CodecId` in `wzp-proto` (reserved slot).
+3. Implement `H264Framer` in `framer.rs`:
+ - Parses access units into NAL units (split by 0x000001 / 0x00000001 start codes).
+ - Emits Single-NAL packets when the NAL fits in `max_payload_size`.
+ - Fragments oversized NALs using H.264 FU-A (RFC 6184).
+ - Returns a `Vec` where the last packet has `is_frame_end = true`.
+4. Implement `H264Depacketizer` in `depacketizer.rs`:
+ - Reassembles Single-NAL packets directly.
+ - Accumulates FU-A fragments until the end marker is seen.
+ - Emits a complete access unit (`Vec`) when `is_frame_end` arrives and no fragmentation is in progress.
+5. Add roundtrip tests and edge-case tests (empty input, single NAL, multi-NAL access unit, FU-A fragmentation, FU-A reassembly).
+
+### Verify
+
+```bash
+cargo test -p wzp-video
+```
+
+### Done when
+
+Synthetic H.264 access units (single NAL, multi-NAL, and oversized NAL requiring FU-A fragmentation) roundtrip correctly through framer + depacketizer.
+
+---
+
+## T4.2 — VideoToolbox H.264 encoder + decoder (macOS)
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 3 d
+- **Files:**
+ - `crates/wzp-video/src/encoder.rs`
+ - `crates/wzp-video/src/decoder.rs`
+ - `crates/wzp-video/src/videotoolbox.rs`
+
+### Context
+
+T4.1 created the `wzp-video` crate with framer/depacketizer. T4.2 adds the macOS platform layer: `VideoEncoder` and `VideoDecoder` traits plus a VideoToolbox implementation. "Minimum viable" means the API compiles on macOS, can be instantiated, and has the correct shape for T4.4–T4.7 to call into.
+
+### Steps
+
+1. Add `video-toolbox` crate dependency (safe Rust bindings to Apple VideoToolbox).
+2. Define `VideoEncoder` trait in `encoder.rs`:
+ ```rust
+ pub trait VideoEncoder: Send {
+ fn encode(&mut self, frame: &VideoFrame) -> Result, VideoError>;
+ fn request_keyframe(&mut self);
+ fn is_keyframe(&self, packet: &[u8]) -> bool;
+ }
+ ```
+3. Define `VideoDecoder` trait in `decoder.rs`:
+ ```rust
+ pub trait VideoDecoder: Send {
+ fn decode(&mut self, packet: &[u8]) -> Result, VideoError>;
+ }
+ ```
+4. Implement `VideoToolboxEncoder` and `VideoToolboxDecoder` in `videotoolbox.rs` (macOS only, gated by `#[cfg(target_os = "macos")]`).
+5. Add compile-guarded stubs for non-macOS targets.
+
+### Verify
+
+```bash
+cargo test -p wzp-video videotoolbox
+cargo build -p wzp-video
+```
+
+### Done when
+
+`wzp-video` compiles on macOS with `VideoToolboxEncoder`/`VideoToolboxDecoder` structs present and instantiable.
+
+---
+
+## T4.2.1 — Wire real VideoToolbox VTCompressionSession / VTDecompressionSession (macOS)
+
+- **Parent:** T4.2 (Approved — scaffold only)
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 3–4 d
+- **Files:**
+ - `crates/wzp-video/src/videotoolbox.rs`
+ - `crates/wzp-video/Cargo.toml` (will need `core-foundation`, `core-media`, `core-video`, `block` crates or equivalent — disclose under "Risks / follow-ups")
+ - `crates/wzp-video/tests/encode_decode_macos.rs` (new — round-trip test, `#[cfg(target_os = "macos")]`)
+
+### Context
+T4.2 shipped the API surface (traits, structs, `is_keyframe`) but stubbed both `encode()` and `decode()`. This task fills in those stubs against the actual Apple frameworks. **This is the task that satisfies the original PRD-video-v1 T4.2 acceptance criterion.**
+
+The current TODOs are at:
+- `crates/wzp-video/src/videotoolbox.rs:34` — `VideoToolboxEncoder::encode` stub.
+- `crates/wzp-video/src/videotoolbox.rs:72` — `VideoToolboxDecoder::decode` stub.
+
+### Steps
+
+1. **Encoder.** Replace the `encode()` stub with a real `VTCompressionSession`:
+ - Create the session once at first `encode()` call (or in `new()`).
+ - Configure: `kVTCompressionPropertyKey_RealTime = true`, `kVTProfileLevel_H264_Baseline_AutoLevel`, `kVTCompressionPropertyKey_AverageBitRate = bitrate_bps`, `kVTCompressionPropertyKey_MaxKeyFrameInterval = 30` (≈ 1 s at 30 fps), `kVTCompressionPropertyKey_AllowFrameReordering = false`.
+ - Wrap the input `VideoFrame.data` (assume NV12 or I420 for now — disclose the format choice) into a `CVPixelBuffer`.
+ - Encode via `VTCompressionSessionEncodeFrame`, collect the resulting `CMSampleBuffer` from the callback.
+ - Extract NAL units from the sample buffer's `CMBlockBuffer` and convert to Annex-B (add `0x000001` start codes).
+ - Return the assembled Annex-B byte vector.
+ - On `force_keyframe` flag: pass `kVTEncodeFrameOptionKey_ForceKeyFrame = true` and clear the flag.
+
+2. **Decoder.** Replace the `decode()` stub with a real `VTDecompressionSession`:
+ - Parse incoming Annex-B access unit into NAL units.
+ - On SPS/PPS NALs, build/refresh `CMFormatDescription`.
+ - Wrap remaining NALs into `CMSampleBuffer`.
+ - Call `VTDecompressionSessionDecodeFrame`; in the callback, convert the output `CVImageBuffer` back to `VideoFrame.data` (mirror the encoder's pixel format).
+
+3. **Threading.** VideoToolbox callbacks run on internal queues. Use a `crossbeam_channel` (single-producer, single-consumer; already in workspace deps via Quinn) or `std::sync::mpsc` to bridge callback → caller. Keep the encode/decode API synchronous from the caller's perspective.
+
+4. **Test.** Add `crates/wzp-video/tests/encode_decode_macos.rs` (`#[cfg(target_os = "macos")]`):
+ - Generate a synthetic 640×360 NV12 frame (gradient pattern).
+ - Encode 30 frames at 30 fps.
+ - Assert at least one keyframe in the first 5 frames.
+ - Pipe the encoded bytes through the depacketizer and decoder.
+ - Assert the decoded frame dimensions match input dimensions (pixel-exact match not required given lossy compression).
+
+5. **Acceptance measurement.**
+ - Measure encode CPU: run 60 s of 1280×720 @ 30 fps NV12 input on M1, log wall-clock + `getrusage` CPU time.
+ - Acceptance: CPU < 5 % of one core on M1 (PRD-video-v1 line).
+
+### Verify
+
+```bash
+cargo test -p wzp-video --test encode_decode_macos
+cargo test -p wzp-video
+cargo clippy -p wzp-video --all-targets -- -D warnings
+cargo fmt --all -- --check
+# Optional manual measurement (record in report):
+cargo run -p wzp-video --release --example bench_encode_720p
+```
+
+### Done when
+- `cargo test -p wzp-video --test encode_decode_macos` passes on macOS.
+- A round-trip (raw frame → encode → packetize → depacketize → decode → frame) produces a frame with matching dimensions.
+- CPU measurement at 720p30 documented in the report. If > 5 %, document why (e.g., software fallback path) and propose mitigation.
+- Non-macOS targets remain unaffected (the existing `target_os` gates already do this; just don't break them).
+
+### Out of scope
+- Android MediaCodec (T4.3).
+- NACK (T4.4) / FEC boost (T4.5) / keyframe cache (T4.6) / PLI (T4.7).
+- Multi-codec negotiation (T5.4 / T6.1).
+
+---
+
+## T4.3 — MediaCodec H.264 encoder + decoder via JNI (Android)
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 5 d
+- **Files:**
+ - `crates/wzp-video/src/mediacodec.rs`
+ - `crates/wzp-android/src/...`
+
+### Context
+
+T4.2 created the `VideoEncoder` / `VideoDecoder` traits and a macOS VideoToolbox implementation. T4.3 adds the Android equivalent using `MediaCodec` via JNI. Because the agent runs on macOS, the MediaCodec implementation is a compile-gated stub; real hardware integration requires an Android device/emulator.
+
+### Steps
+
+1. Create `MediaCodecEncoder` and `MediaCodecDecoder` structs in `wzp-video/src/mediacodec.rs`.
+2. Implement `VideoEncoder` / `VideoDecoder` traits for the structs.
+3. Gate the module with `#[cfg(target_os = "android")]`; on non-Android targets the module exports placeholder types that return `NotInitialized` errors.
+4. Leave JNI surface-texture wiring as a TODO for the Android build environment.
+
+### Verify
+
+```bash
+cargo test -p wzp-video mediacodec
+cargo build -p wzp-video
+```
+
+### Done when
+
+`MediaCodecEncoder` / `MediaCodecDecoder` compile on Android targets and return `Err(NotInitialized)` on non-Android targets.
+
+---
+
+## T4.3.1 — Wire real MediaCodec JNI bridge (Android)
+
+- **Parent:** T4.3 (Approved — scaffold only)
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 5 d (gated on Android build environment working)
+- **Files:**
+ - `crates/wzp-video/src/mediacodec.rs`
+ - `crates/wzp-android/src/video/mod.rs` (new — Kotlin/JNI side may live here)
+ - `android/app/src/main/java/com/wzp/video/` (new — MediaCodec Kotlin glue if needed)
+
+### Prerequisite
+**The `wzp-android` build environment must work first.** Current `liblog` link failure must be resolved. This task is **Blocked** until that prerequisite is fixed; agents should not claim this task until the build env is confirmed working with `build-tauri-android.sh --init`.
+
+### Context
+T4.3 shipped the API surface but stubbed both `encode()` and `decode()` even on Android. This task fills in the real JNI MediaCodec wiring. **This is the task that satisfies the original PRD-video-v1 T4.3 acceptance.**
+
+Current TODOs at `crates/wzp-video/src/mediacodec.rs:39` (encoder) and `:91` (decoder).
+
+### Steps
+
+1. **Decide on JNI surface.** Two options — pick one and document:
+ - **(A) Direct ndk-sys `AMediaCodec`** (NDK r24+, no Java↔native bouncing). Pure Rust with `ndk-sys` crate dep. Simpler, but requires NDK API ≥ 21.
+ - **(B) Java MediaCodec via JNI bridge** (call into Kotlin/Java glue that owns MediaCodec lifecycle). Slower (JNI calls per buffer) but matches existing `wzp-android` pattern.
+ - Recommended: **(A)** for the encode/decode hot path, **(B)** only if surface-texture path is required.
+
+2. **Encoder configure.**
+ - `AMediaCodec_createEncoderByType("video/avc")`.
+ - `AMediaFormat` keys: `KEY_MIME="video/avc"`, `KEY_WIDTH`, `KEY_HEIGHT`, `KEY_BIT_RATE = bitrate_bps`, `KEY_FRAME_RATE = 30`, `KEY_I_FRAME_INTERVAL = 1` (1 s ≈ 30 frames at 30 fps), `KEY_COLOR_FORMAT = COLOR_FormatYUV420Flexible` (or NV12 / I420 — choose and document).
+ - `AMediaCodec_configure` with surface=NULL for byte-buffer mode (or attach a surface for the surface-texture path).
+ - `AMediaCodec_start`.
+
+3. **Encoder per-frame loop.**
+ - `AMediaCodec_dequeueInputBuffer(timeout_us=10_000)`.
+ - Copy `VideoFrame.data` (NV12/I420) into input buffer.
+ - `AMediaCodec_queueInputBuffer(presentation_us=timestamp_ms*1000, flags=0)`.
+ - `AMediaCodec_dequeueOutputBuffer` in a loop — collect Annex-B output. Note: MediaCodec emits AVCC by default; you may need to convert AVCC → Annex-B (replace 4-byte length prefix with `0x000001`) or set `KEY_PREPEND_HEADER_TO_SYNC_FRAMES=1`.
+ - Return assembled Annex-B `Vec`.
+
+4. **Decoder mirror.** Same `AMediaCodec` pattern but `createDecoderByType("video/avc")`, parse SPS/PPS from incoming access unit on first frame to build CSD, feed input, drain output buffer → `VideoFrame`.
+
+5. **Keyframe request.** `AMediaCodec_setParameters` with `PARAMETER_KEY_REQUEST_SYNC_FRAME = 0`.
+
+6. **Test.** New `crates/wzp-video/tests/encode_decode_android.rs` gated `#[cfg(target_os = "android")]`:
+ - Run only when invoked from the Android test runner (instrumented test) or via emulator.
+ - Synthetic 640×360 NV12 frame; encode 30 frames; assert at least one IDR in first 5; round-trip through depacketizer + decoder.
+ - Skip with `#[ignore]` if MediaCodec init fails (e.g., on non-MediaCodec-capable emulator).
+
+7. **Manual Android↔macOS test.** Wire both T4.2.1 (macOS real encoder) and T4.3.1 (Android real encoder) into a CLI test harness. Record latency + CPU on a real Android device and on M1.
+
+### Verify
+
+```bash
+# On the Android builder (Hetzner remote):
+./scripts/build-tauri-android.sh --init
+# Then on the device:
+adb shell am instrument -w -e class com.wzp.video.MediaCodecTests com.wzp/com.wzp.video.TestRunner
+```
+
+### Done when
+- `cargo build -p wzp-video --target aarch64-linux-android` (or via cargo-ndk) succeeds.
+- Android↔macOS unidirectional H.264 call works manually (record measurement in report).
+- Encode CPU on a mid-tier Android device < 15 % of one core at 720p30 (PRD-video-v1 line).
+
+### Out of scope
+- iOS (use T4.2.1's VideoToolbox path).
+- Per-receiver simulcast layer selection (T5.5/T5.6).
+
+---
+
+## T4.3.1.1 — Validate Android-target compile + run MediaCodec on device
+
+- **Parent:** T4.3.1 (Approved — Android code present but unverified)
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 1–2 d (mostly waiting on Android builder + device access)
+- **Files:**
+ - `crates/wzp-video/src/mediacodec.rs` (fix any compile errors that surface on the Android target)
+ - `crates/wzp-video/tests/encode_decode_android.rs` (new — `#[cfg(target_os = "android")]` instrumented test)
+ - `android/app/src/androidTest/java/com/wzp/video/MediaCodecTest.kt` (new — invokes the Rust JNI test entry point)
+
+### Prerequisite
+The Android build pipeline must be functional. Use `build-tauri-android.sh --init` per the project memory. Trigger from the Hetzner remote builder (188.245.59.196) if needed.
+
+### Context
+T4.3.1 shipped `AMediaCodec`-based Rust code behind `#[cfg(target_os = "android")]` but **the agent could not compile or test it on their macOS host**. The code is structurally similar to T4.2.1's working VideoToolbox code, but plausibility is not verification. This task is the actual verification step that should have been part of T4.3.1.
+
+### Steps
+
+1. **Verify the target build compiles.** From the Hetzner remote or local NDK-equipped machine:
+ ```bash
+ cargo build -p wzp-video --target aarch64-linux-android
+ ```
+ Capture full stderr. If anything errors, fix the smallest possible thing in `crates/wzp-video/src/mediacodec.rs` to make it compile (record the diff in the report). Common likely failures:
+ - `ndk` crate API differences between version `0.9` and whatever's actually resolvable.
+ - Missing imports if `#[cfg]` gates weren't comprehensive.
+ - Pixel-format constants that don't exist on the current `ndk` version.
+
+2. **Add the instrumented test.** Create `crates/wzp-video/tests/encode_decode_android.rs`:
+ ```rust
+ #![cfg(target_os = "android")]
+ use wzp_video::{MediaCodecEncoder, MediaCodecDecoder, VideoFrame};
+
+ #[test]
+ fn encode_decode_roundtrip_android() {
+ // 30 synthetic 640×360 I420 gradient frames → encode → decode → assert dimensions
+ // mirror T4.2.1's encode_decode_macos.rs structure
+ }
+ ```
+ Mirror the macOS test in `tests/encode_decode_macos.rs` closely so the two are comparable.
+
+3. **Run the test on a real device.** Connect via `adb`, deploy the test APK (`cargo apk` or via Gradle if `android/` Gradle build is set up), and run:
+ ```bash
+ adb shell am instrument -w com.wzp.video.test/androidx.test.runner.AndroidJUnitRunner
+ ```
+ Capture the result.
+
+4. **Measure CPU at 720p30.** Encode 60 s of 1280×720 frames; record `getrusage()` / `top -p ` CPU%. PRD acceptance: < 15 % of one core on a mid-tier Android device.
+
+5. **Manual Android↔macOS interop.** Run the macOS T4.2.1 encoder, send a bitstream over QUIC datagrams (mock if the relay isn't wired yet), decode on Android. Confirm visual round-trip. Record device model + Android version in the report.
+
+### Verify
+
+```bash
+# On Android builder:
+cargo build -p wzp-video --target aarch64-linux-android
+# After APK is on device:
+adb shell am instrument -w -e class com.wzp.video.MediaCodecTest com.wzp.video.test/androidx.test.runner.AndroidJUnitRunner
+```
+
+### Done when
+- `cargo build -p wzp-video --target aarch64-linux-android` succeeds (record any fixes needed in the report).
+- Instrumented `encode_decode_roundtrip_android` test passes on at least one real device.
+- 720p30 CPU measurement documented. Target < 15 % of one core; if higher, document why and propose mitigation (e.g., surface-input path, format negotiation).
+- Manual Android↔macOS interop: visual decode of the same stream on both ends.
+
+### Out of scope
+- Surface-texture zero-copy path (defer to a later UX/battery-focused task).
+- Decoder pixel-format negotiation (NV12 / NV21 / vendor tiled) — call out in the report which format MediaCodec actually emits on the test device.
+
+---
+
+## T4.4 — `SignalMessage::Nack` variant + RTT-gated NACK loop
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 2 d
+- **Files:**
+ - `crates/wzp-proto/src/packet.rs`
+ - `crates/wzp-video/src/nack.rs`
+
+Skeleton — expand before claiming.
+
+---
+
+## T4.5 — I-frame FEC ratio boost
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 1 d
+- **Files:**
+ - `crates/wzp-fec/src/...`
+ - `crates/wzp-video/src/...`
+
+Skeleton — expand before claiming.
+
+---
+
+## T4.6 — SFU keyframe cache
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 2 d
+- **Files:**
+ - `crates/wzp-relay/src/room.rs`
+
+Skeleton — expand before claiming.
+
+---
+
+## T4.7 — PLI suppression at SFU
+
+- **PRD:** `PRD-video-v1.md`
+- **Effort:** 1 d
+- **Files:**
+ - `crates/wzp-relay/src/room.rs`
+
+Skeleton — expand before claiming.
+
+---
+
+# Wave 5 — Quality, codecs, simulcast (3 weeks)
+
+Detailed task breakdown deferred. Skeleton:
+
+| Task | Summary |
+|---|---|
+| T5.1 | `PriorityMode` enum + `SignalMessage::SetPriorityMode` |
+| T5.2 | `VideoQualityController` with per-mode allocation gates |
+| T5.3 | `EncoderMode::SlideFallback` for ScreenShare |
+| T5.4 | H.265 encoder/decoder (reuse framer from T4.1) |
+| T5.5 | 3-layer simulcast at sender |
+| T5.6 | Per-receiver layer selection at SFU |
+| T5.7 | Tier F audio scorer (entropy/IAT/silence-fraction) |
+| T5.8 | Tier G response policy (typed Hangup + audit log) |
+
+---
+
+# Wave 6 — AV1 + Tier F video (2-3 weeks)
+
+| Task | Summary |
+|---|---|
+| T6.1 | AV1 encoder/decoder with HW probe + SVT-AV1 SW fallback |
+| T6.2 | Tier F video scorer (keyframe periodicity, I/P ratio, BWE responsiveness) |
+| T6.3 | Federated reputation gossip (optional) |
+
+---
+
+## T6.1 — AV1 encoder/decoder with HW probe + SVT-AV1 SW fallback
+
+- **PRD:** `PRD-video-multicodec.md`
+- **Effort:** 5 d
+- **Files:**
+ - `crates/wzp-proto/src/codec_id.rs` — add `Av1Main = 12`
+ - `crates/wzp-video/src/av1_obu.rs` — new `Av1ObuFramer` / `Av1Depacketizer` (OBU parsing, not NAL)
+ - `crates/wzp-video/src/svt_av1.rs` — SW encoder wrapper (`shiguredo_svt_av1`)
+ - `crates/wzp-video/src/dav1d.rs` — SW decoder wrapper (`shiguredo_dav1d`)
+ - `crates/wzp-video/src/videotoolbox.rs` — AV1 decode via `DecoderCodec::Av1` (macOS, M3+)
+ - `crates/wzp-video/src/mediacodec.rs` — AV1 encode/decode via `video/av01` (Android 10+)
+ - `crates/wzp-video/Cargo.toml` — add `shiguredo_dav1d`, `shiguredo_svt_av1` deps
+ - `crates/wzp-video/src/lib.rs` — re-export new types
+ - `crates/wzp-codec/src/opus_enc.rs`, `wzp-client/src/call.rs`, `wzp-relay/src/conformance.rs` — add `Av1Main` match arms
+
+### Context
+
+AV1 uses **OBU (Open Bitstream Unit)** framing, not NAL. The existing `H264Framer`/`H264Depacketizer` cannot be reused directly. A minimal `Av1ObuFramer` parses the 1-byte OBU header (`obu_type`, `has_size_field`, `extension_flag`) and extracts OBU payloads. Keyframe detection inspects the `OBU_FRAME_HEADER` or `OBU_FRAME` payload for `frame_type == KEY_FRAME`.
+
+**CodecId allocation:** `Av1Main = 12` (next free slot after `H265Main = 11`).
+
+**SW library choice:** `shiguredo_dav1d` (decode) + `shiguredo_svt_av1` (encode).
+
+| Dimension | dav1d + SVT-AV1 | aom (alternative) |
+|---|---|---|
+| Decode speed | Fastest (dav1d is reference fast decoder) | Slower |
+| Encode quality | Production-grade (SVT-AV1 is Netflix/Intel reference) | Good, but slower |
+| Binary size | Two libs, ~2–3 MB each | One lib, ~3–4 MB |
+| Build complexity | dav1d = prebuilt binaries; SVT-AV1 = prebuilt or source-build | shiguredo_aom is canary, less stable |
+| License | Both BSD-2-Clause | BSD-2-Clause |
+
+**Decision:** dav1d + SVT-AV1. Matches the PRD's "SVT-AV1 SW fallback" wording and follows the project's existing shiguredo ecosystem (`shiguredo_video_toolbox` is already used). aom is rejected because `shiguredo_aom` is canary and slower at both roles.
+
+**Hardware probe strategy:**
+
+- **macOS** — VideoToolbox AV1 **decode only** (M3+). `DecoderCodec::Av1 { width, height }` returns `Error::UnsupportedCodec` on M1/M2. **No AV1 encode via VideoToolbox** → macOS encode always uses SVT-AV1.
+- **Android** — MediaCodec AV1 (`video/av01`). Encode and decode supported on Android 10+ (API 29+). Project `minSdk = 26`, so on API 26–28 devices AV1 HW is unavailable → SW fallback. Probe at runtime with `MediaCodecList`.
+- **Fallback path** — SVT-AV1 (encode) + dav1d (decode) on all platforms. Compiled everywhere; HW wrappers are `cfg`-gated.
+
+### Steps
+
+1. **CodecId** — add `Av1Main = 12`, update `bitrate_bps()`, `frame_duration_ms()`, `sample_rate_hz()`, `is_video()`, `from_wire()`, and any exhaustive match expressions in `wzp-codec`, `wzp-client`, `wzp-relay`.
+2. **OBU framer** — create `crates/wzp-video/src/av1_obu.rs`:
+ ```rust
+ pub struct ObuHeader { pub obu_type: u8, pub has_size_field: bool, pub extension_flag: bool }
+ pub fn split_obus(data: &[u8]) -> Vec<(ObuHeader, Vec)>;
+ pub fn is_keyframe_obu(data: &[u8]) -> bool; // inspects OBU_FRAME_HEADER / OBU_FRAME
+ ```
+3. **SW decoder** — `crates/wzp-video/src/dav1d.rs`:
+ - `Dav1dDecoder` wrapping `shiguredo_dav1d::Decoder`
+ - Lazy init on first OBU sequence header
+ - `decode(&[u8]) -> Result`
+4. **SW encoder** — `crates/wzp-video/src/svt_av1.rs`:
+ - `SvtAv1Encoder` wrapping `shiguredo_svt_av1::Encoder`
+ - Config: 1280×720@30, 2 Mbps, GOP 120
+ - `encode(&FrameData) -> Result, VideoError>` (outputs OBUs)
+5. **macOS HW decoder** — extend `videotoolbox.rs`:
+ - `VideoToolboxAv1Decoder` using `DecoderCodec::Av1 { width, height }`
+ - Returns `VideoError::NotInitialized` if `Error::UnsupportedCodec`
+6. **Android HW** — extend `mediacodec.rs`:
+ - `MediaCodecAv1Encoder` / `MediaCodecAv1Decoder` using `video/av01`
+ - Non-Android targets return `VideoError::NotInitialized`
+7. **Re-exports** — update `wzp-video/src/lib.rs`.
+8. **Fix exhaustive matches** — add `Av1Main` arms in `wzp-codec`, `wzp-client`, `wzp-relay`.
+
+### Verify
+
+```bash
+cargo test -p wzp-video -- av1
+cargo test -p wzp-proto -- av1
+cargo build --workspace
+```
+
+### Done when
+
+- `Av1Main = 12` roundtrips through `to_wire`/`from_wire`.
+- `Av1ObuFramer` splits a synthetic OBU stream correctly and `is_keyframe_obu` detects keyframes.
+- SW encode-decode roundtrip test passes on the build host (macOS ARM64):
+ - Encode 10 frames via `SvtAv1Encoder` → OBU stream
+ - Decode same stream via `Dav1dDecoder` → assert 10 frames out
+- macOS HW decode test: `VideoToolboxAv1Decoder::new()` returns `Ok` on M3+, `Err(NotInitialized)` on M1/M2 (or on CI if no HW).
+- Android HW test: returns `NotInitialized` on non-Android target (same pattern as H.265).
+- `cargo clippy -p wzp-video --all-targets -- -D warnings` and `cargo fmt --all -- --check` pass.
+- **T6.1.1 deferred note:** If Android MediaCodec AV1 validation requires a physical device (like T4.3.1.1), spawn a deferred follow-up instead of blocking the commit.
+
+---
+
+## T6.2 — Tier F video scorer (keyframe periodicity, I/P ratio, BWE responsiveness)
+
+- **PRD:** `PRD-relay-conformance.md`
+- **Effort:** 3 d
+- **Files:**
+ - `crates/wzp-relay/src/video_scorer.rs` (new)
+ - `crates/wzp-relay/src/lib.rs` (add `pub mod video_scorer;`)
+ - `crates/wzp-relay/src/room.rs` (documented call site, no wiring yet)
+
+### Context
+
+Parallel to `audio_scorer.rs` (T5.7). The video scorer observes video packet streams and produces a `legitimacy ∈ [0, 1]` score over a 5–15 s window. It reuses the unified `crate::verdict::Verdict` from T5.7.1 (`Legitimate`, `Suspect`, `Abusive`).
+
+**Feeding point:** `run_participant_plain` / `run_participant_trunked` in `room.rs`, immediately after the existing `conformance.observe()` call (around line 1248). Frequency: once per incoming packet whose `MediaHeader.media_type == MediaType::Video`. The scorer is **not wired in this task** — only created and unit-tested. Wiring is T6.2-follow-up or T6.x integration scope.
+
+### Steps
+
+1. Create `crates/wzp-relay/src/video_scorer.rs`:
+ ```rust
+ use std::collections::VecDeque;
+ use std::time::{Duration, Instant};
+ use wzp_proto::{MediaHeader, MediaType};
+ use crate::verdict::Verdict;
+
+ pub struct VideoScorer {
+ keyframe_iat_samples: VecDeque,
+ last_keyframe_at: Option,
+ i_frame_count: u32,
+ p_frame_count: u32,
+ bwe_samples: VecDeque<(Instant, u32)>, // (timestamp, bwe_kbps)
+ window_start: Instant,
+ window_bytes: u64,
+ }
+ ```
+2. **Keyframe periodicity** — `keyframe_regularity()`: compute CoV of inter-arrival times between packets with `header.is_keyframe()`. Legitimate streams have low variance (encoder-driven GOP). Abusive streams have random or missing keyframes. Returns `Option` in [0, 1] where 1 = perfectly regular.
+3. **I/P ratio** — `ip_ratio()`: count `is_keyframe()` (I) vs non-keyframe (P) over the observation window. Legitimate H.264/H.265 has I:P ≈ 1:29 to 1:119 (GOP 30–120). Abusive all-I-frame streams have ratio > 1:5. Returns `Option`.
+4. **BWE responsiveness** — `bwe_responsiveness()`: compare sender bitrate against the last downstream BWE reported via `TransportFeedback` (or `BandwidthEstimator`). If BWE drops > 30 % but sender bitrate stays within 10 % of previous window → unresponsive. Returns `Option`.
+5. `legitimacy()` — weighted combination:
+ - keyframe regularity: 0.35 weight
+ - I/P ratio sanity: 0.30 weight (was 0.35 — bumped BWE during T6.2 implementation)
+ - BWE responsiveness: 0.40 weight (was 0.30 — see T6.2 deviation)
+ - Clamp to [0, 1] with `score.clamp(0.0, 1.0)`.
+6. `verdict()` — map score to `Verdict` using same thresholds as audio scorer (≥ 0.7 Legitimate, ≥ 0.3 Suspect, else Abusive).
+7. In `lib.rs`, add `pub mod video_scorer;` after `pub mod audio_scorer;`.
+8. In `room.rs`, add a `// TODO(T6.2-follow-up): feed video packets to VideoScorer here` comment on the line after `conformance.observe()` (around line 1262) so the wiring point is documented.
+
+### Verify
+
+```bash
+cargo test -p wzp-relay video_scorer
+```
+
+### Done when
+
+Unit tests cover at minimum:
+- `video_scorer_legitimate_traffic` — regular GOP (every 30 frames), sane I/P ratio, responsive BWE. Expect `Verdict::Legitimate`.
+- `video_scorer_abusive_no_keyframes` — no keyframes at all for 5 s. Expect score < 0.3 → `Abusive`.
+- `video_scorer_abusive_bwe_unresponsive` — BWE drops 50 % but bitrate unchanged. Expect `Suspect` or `Abusive`.
+- `video_scorer_ip_ratio_out_of_range` — all-I-frame stream (I:P = 1:1). Expect `Abusive`.
+- Plus 4–7 additional tests mirroring T5.7 breadth (insufficient samples, ignores audio packets, mixed traffic, window expiry, etc.). **Target: 8–10 tests total.**
+
+---
+
+# Working agreements
+
+- **One commit per task.** Message: `T: