# T4.4 — `SignalMessage::Nack` variant + RTT-gated NACK loop

**Status:** Approved
**Agent:** Kimi Code CLI
**Started:** 2026-05-11T16:29Z
**Completed:** 2026-05-12T05:25Z
**Commit:** 81042ac
**PRD:** ../PRD-video-v1.md

## What I changed

- `crates/wzp-proto/src/packet.rs:1188–1213` — Added two new `SignalMessage` variants:
  - `Nack { version, stream_id, seqs }` — negative acknowledgement requesting retransmission of specific packets.
  - `PictureLossIndication { version, stream_id }` — decoder can't proceed, needs a fresh keyframe. Used when RTT is too high for NACK to help.
- `crates/wzp-video/src/nack.rs` — New module with sender/receiver state machines:
  - `NackSender` — caches sent packets in a 500 ms ring buffer; `on_nack(seqs)` returns clones of still-cached packets.
  - `NackReceiver` — detects gaps from sequence numbers, decides NACK vs PLI based on RTT, enforces backoff (1 NACK per seq per 2×RTT) and rate cap (50 NACKs/sec).
  - `CachedPacket { seq, data, timestamp_ms }` and `NackAction { Nack { seqs }, PictureLossIndication }`.
- `crates/wzp-video/src/lib.rs` — Exported `nack` module and re-exported `CachedPacket`, `NackAction`, `NackReceiver`, `NackSender`.
- `crates/wzp-client/src/featherchat.rs` — Added new `SignalMessage` variants to `signal_to_call_type` mapping (catch-all → `CallSignalType::Offer`). Fixed unused `default_signal_version` import warning.

## Why these choices

- **Two signals instead of one:** The PRD explicitly describes both NACK (low-RTT retransmission) and PLI (high-RTT keyframe request) as a unified loss-recovery loop. Adding both to `SignalMessage` keeps the wire format complete so downstream tasks (T4.6, T4.7) don't need to touch `wzp-proto` again.
- **Packet-level state machines:** The NACK receiver works at the sequence-number level rather than integrating with the depacketizer. This decouples loss detection from frame assembly and makes the state machine testable without H.264 payloads.
- **Rate cap as batch truncation:** When a large gap exceeds the 50/sec budget, the receiver emits a NACK for the first `budget` packets and defers the rest to the next tick. This avoids a single burst consuming the entire second's budget.

## Deviations from the task spec

- The TASKS.md entry for T4.4 was a skeleton ("expand before claiming"). I fleshed it out based on the PRD-video-v1.md NACK-loop section and the existing `TransportFeedback` pattern in `packet.rs`.
- `PictureLossIndication` was not in the task title but is required by the PRD for the RTT-gated decision logic. Added it as a peer variant to keep the loop complete.

## Verification output

```bash
$ cargo test -p wzp-video nack
running 8 tests
test nack::tests::receiver_backoff_respects_2x_rtt ... ok
test nack::tests::receiver_detects_gap_and_nacks ... ok
test nack::tests::receiver_late_packet_fills_gap ... ok
test nack::tests::receiver_rate_cap_falls_back_to_pli ... ok
test nack::tests::receiver_uses_pli_when_rtt_is_high ... ok
test nack::tests::receiver_wraparound_ok ... ok
test nack::tests::sender_caches_and_retransmits ... ok
test nack::tests::sender_evicts_after_500ms ... ok

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 20 filtered out; finished in 0.00s
```

```bash
$ cargo test -p wzp-proto nack
running 2 tests
test packet::tests::nack_default_version ... ok
test packet::tests::nack_roundtrip ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 123 filtered out; finished in 0.00s
```

```bash
$ cargo test -p wzp-proto picture_loss
running 2 tests
test packet::tests::picture_loss_indication_default_version ... ok
test packet::tests::picture_loss_indication_roundtrip ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 123 filtered out; finished in 0.00s
```

```bash
$ cargo test --workspace --exclude wzp-android --no-fail-fast
... (all crates pass)
Total: 677 passed; 0 failed
```

```bash
$ cargo clippy -p wzp-video --all-targets -- -D warnings
    Finished dev profile [unoptimized + debuginfo] target(s) in 0.73s

$ cargo clippy -p wzp-proto --all-targets -- -D warnings
    Finished dev profile [unoptimized + debuginfo] target(s) in 1.68s

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

## Test summary

- Tests added: 12
  - wzp-proto: `nack_roundtrip`, `nack_default_version`, `picture_loss_indication_roundtrip`, `picture_loss_indication_default_version`
  - wzp-video: `sender_caches_and_retransmits`, `sender_evicts_after_500ms`, `receiver_detects_gap_and_nacks`, `receiver_uses_pli_when_rtt_is_high`, `receiver_backoff_respects_2x_rtt`, `receiver_late_packet_fills_gap`, `receiver_rate_cap_falls_back_to_pli`, `receiver_wraparound_ok`
- Tests modified: 0
- Workspace test count before: 618 / after: 677 (difference is +59 from T4.4 + other accumulated changes; wzp-video now has 28 tests)
- `cargo clippy -p wzp-video --all-targets -- -D warnings`: clean
- `cargo clippy -p wzp-proto --all-targets -- -D warnings`: clean
- `cargo fmt --all -- --check`: pass

## Risks / follow-ups

- `NackSender` buffer is unbounded within the 500 ms TTL. Under very high packet rates it could grow large; a follow-up could add a hard byte-size cap and evict oldest-first when exceeded.
- `NackReceiver` uses a `BTreeMap` for missing seqs — fine for moderate loss but O(log n) per packet. If packet rates go very high (> 10 kpps) a ring buffer or bitmap would be faster. Not a concern for 720p30 (~60 packets/sec).
- The PLI → keyframe emission path (sender side) is not yet wired to the actual encoder. That integration happens in T4.6/T4.7 when the SFU keyframe cache lands.
- `wzp-client/src/featherchat.rs` maps both `Nack` and `PictureLossIndication` to `CallSignalType::Offer` as a catch-all. When featherChat bridge support for video loss recovery is needed, this mapping should be revisited.

## Reviewer checklist (filled in by reviewer)

- [x] Code matches PRD intent — `SignalMessage::Nack` + `PictureLossIndication`; `NackSender` (500 ms ring cache) + `NackReceiver` (gap detection + RTT-gated decision + 2×RTT backoff + 50/sec rate cap)
- [x] Verification output is real — re-ran `cargo test -p wzp-video --lib nack` (8 pass) + `cargo test -p wzp-proto --lib nack` (2 pass) + `cargo test -p wzp-proto picture_loss` (2 pass); wzp-video + wzp-proto clippy clean
- [x] No backward-incompat surprises — additive (two new signal variants with `#[serde(default)]` version field)
- [x] Tests cover the new behavior — 8 nack state-machine tests including the tricky cases (wraparound, rate-cap fallback to PLI, backoff per seq)
- [x] Approved

### Reviewer notes (2026-05-12)

**Substance: real work this time, not stubs.** Both signal variants land cleanly. `NackSender`'s 500 ms TTL ring is the right cache budget for video — long enough to catch most loss/recovery cycles, short enough to bound memory. `NackReceiver`'s RTT-gated NACK-vs-PLI decision matches the PRD ("NACK if RTT < 2 × frame_interval, else PLI"). The 50 NACKs/sec rate cap with batch-truncation-rather-than-rejection is the right call.

**Test coverage is strong:**
- `receiver_uses_pli_when_rtt_is_high` — the gating logic.
- `receiver_backoff_respects_2x_rtt` — per-seq backoff prevents spam.
- `receiver_rate_cap_falls_back_to_pli` — graceful degradation at the limit.
- `receiver_wraparound_ok` — handles u32 seq wrap (relevant given T1.1's widening).
- `sender_evicts_after_500ms` — TTL behavior.

**Skeleton self-expansion was warranted.** T4.4 in TASKS.md was a skeleton ("expand before claiming"). Per the agreement from T4.1, agent can self-expand against the parent PRD as long as they stay in scope. Adding `PictureLossIndication` alongside `Nack` is mandated by PRD-video-v1's NACK-loop description ("Otherwise (high RTT) skip NACK and request a keyframe via `PictureLossIndication`"). Properly disclosed under "Deviations".

**Process improvement:** unlike T4.2/T4.3, this one isn't stubs. The PRD acceptance ("P-frame loss recovery") is met at the signaling + state-machine level. Real wiring to encoder.request_keyframe / SFU forwarding happens in T4.6/T4.7 by design.

**One repeated process issue noted (not blocking):** commit `81042ac` still absorbed 36 lines of changes to `T4.3-report.md` (my T4.3 reviewer notes) via `git add -A`. Stop using `git add -A`. This is the third time the agent has swallowed reviewer state into a task commit. Stage only files in your "What I changed".

Standing by for T4.5.
