# T3.2 — Document `timestamp_ms` rebase across rekey (W3)

**Status:** Pending Review
**Agent:** Kimi Code CLI
**Started:** 2026-05-11T21:15Z
**Completed:** 2026-05-11T21:25Z
**Commit:** (see git log)
**PRD:** ../PRD-protocol-hardening.md

## What I changed

- `crates/wzp-proto/src/packet.rs` — Updated doc comment on `MediaHeader::timestamp`:
  ```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,
  ```

- `crates/wzp-crypto/src/rekey.rs` — Added inline comment on `perform_rekey()`:
  ```rust
  /// NOTE: Rekeying changes **only** the symmetric key material.  Sequence
  /// numbers and timestamps in the media framing layer (e.g. `MediaHeader`)
  /// are untouched — they continue monotonically across the rekey boundary.
  ```

- `docs/WZP-SPEC.md` — Updated `timestamp_ms` field description:
  ```
  | timestamp_ms | 32 | ms since session start. Monotonic across the full session; **not reset by rekey** |
  ```

- `crates/wzp-client/tests/long_session.rs` — Added `rekey_timestamp_monotonic` test:
  - Simulates a 3000-frame session with two conceptual rekey boundaries at frames 1000 and 2000.
  - Collects all `MediaHeader::timestamp` values across the three phases.
  - Asserts strict monotonicity (non-decreasing) with `windows(2)`.
  - Sanity-checks that at least 3000 timestamps were collected.

## Why these choices

The test uses `CallEncoder` (which owns `timestamp_ms`) rather than `ChaChaSession` (which owns `RekeyManager`) because the property we care about is at the **framing layer**: regardless of what happens in crypto, the media header timestamps must not jump backwards or reset. `CallEncoder` is the component that actually emits timestamps, and it has no knowledge of rekeying — which is exactly the invariant we want to verify.

## Deviations from the task spec

None.

## Verification output

```bash
$ cargo test -p wzp-client --test long_session
running 4 tests
test rekey_timestamp_monotonic ... ok
test long_session_no_drift ... ok
test long_session_with_simulated_loss ... ok
test long_session_stats_consistency ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 14.62s
```

## Test summary

- Tests added: 1
  - `rekey_timestamp_monotonic` — 3000-frame session, two rekey boundaries, verifies timestamp monotonicity
- Tests modified: 0
- `wzp-client` integration test count: 4 (was 3 before T3.2)
- `cargo fmt --all -- --check`: pass

## Risks / follow-ups

- The test simulates rekeys conceptually (phase boundaries) rather than invoking `RekeyManager::perform_rekey()` directly. This is correct because `CallEncoder` doesn't touch crypto state; a more integration-level test could be added later if the encoder/decoder ever gains explicit rekey hooks.

## Reviewer checklist (filled in by reviewer)

- [ ] Code matches PRD intent
- [ ] Verification output is real
- [ ] No backward-incompat surprises
- [ ] Tests cover the new behavior
- [ ] Approved