# 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<u8>,  // e.g. [2]
}
```

Relay/peer side:
- If `protocol_version` is supported → proceed.
- If unsupported → close with `Hangup::ProtocolVersionMismatch { server_supported: Vec<u8> }`.

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).