wz-phone/docs/PRD/reports/T1.4-report.md

T1.4 — Add v2 MiniHeader with seq_delta

Status: Approved Agent: Kimi Code CLI Started: 2026-05-11T07:12Z Completed: 2026-05-11T07:16Z Commit: see git log PRD: ../PRD-wire-format-v2.md

What I changed

• crates/wzp-proto/src/packet.rs:580-611 — renamed MiniHeader → MiniHeaderV1, kept all impls intact
• crates/wzp-proto/src/packet.rs:613 — added pub type MiniHeader = MiniHeaderV1; backward-compat alias
• crates/wzp-proto/src/packet.rs:616-640 — added new MiniHeaderV2 struct (5 bytes: seq_delta + timestamp_delta_ms + payload_len) with write_to/read_from
• crates/wzp-proto/src/packet.rs:642-666 — renamed MiniFrameContext → MiniFrameContextV1, kept all impls intact
• crates/wzp-proto/src/packet.rs:668 — added pub type MiniFrameContext = MiniFrameContextV1; backward-compat alias
• crates/wzp-proto/src/packet.rs:670-695 — added new MiniFrameContextV2 tracking MediaHeaderV2 baseline, with update and expand using explicit seq_delta
• crates/wzp-proto/src/lib.rs:31 — re-exported MiniHeaderV1, MiniHeaderV2, MiniFrameContextV1, MiniFrameContextV2
• crates/wzp-proto/src/packet.rs:1968-2014 — added 3 v2 tests: mini_header_v2_roundtrip, mini_frame_context_v2_expand, mini_frame_context_v2_no_baseline

Why these choices

Same naming collision as T1.1: Rust does not allow a type alias and a struct with the same name in the same module. The new structs are named MiniHeaderV2 and MiniFrameContextV2 with temporary aliases preserving the old names; T1.5 will delete the v1 types and rename.

The v2 MiniFrameContextV2::expand uses base.seq.wrapping_add(m.seq_delta as u32) instead of the hard-coded wrapping_add(1) from v1, which resolves audit W4 (a missed full header no longer desyncs the sequence).

Deviations from the task spec

1. Step 2 / Step 3 (struct names): The new mini struct is MiniHeaderV2 and the new context is MiniFrameContextV2 instead of MiniHeader / MiniFrameContext. Required because pub type MiniHeader = MiniHeaderV1; and pub type MiniFrameContext = MiniFrameContextV1; occupy the base names. T1.5 will resolve.

Verification output

$ cargo test -p wzp-proto mini
running 12 tests
test packet::tests::full_vs_mini_size_comparison ... ok
test packet::tests::mini_frame_context_expand ... ok
test packet::tests::mini_frame_context_no_baseline ... ok
test packet::tests::mini_frame_context_v2_expand ... ok
test packet::tests::mini_frame_context_v2_no_baseline ... ok
test packet::tests::mini_frame_disabled ... ok
test packet::tests::mini_frame_encode_decode_sequence ... ok
test packet::tests::mini_frame_periodic_full ... ok
test packet::tests::mini_header_encode_decode ... ok
test packet::tests::mini_header_v2_roundtrip ... ok
test packet::tests::mini_header_wire_size ... ok
test packet::tests::candidate_update_minimal_roundtrip ... ok

test result: ok. 12 passed; 0 failed; 0 ignored; 0 measured; 100 filtered out; finished in 0.00s

$ cargo build -p wzp-proto -p wzp-codec -p wzp-fec -p wzp-crypto -p wzp-transport -p wzp-relay -p wzp-client -p wzp-web -p wzp-native
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 15.71s

$ cargo test -p wzp-proto -p wzp-codec -p wzp-fec -p wzp-crypto -p wzp-transport -p wzp-relay -p wzp-client -p wzp-web -p wzp-native --no-fail-fast
...
test result: ok. 571 passed; 0 failed; ...

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

$ cargo fmt --all -- --check
# (clean)

Test summary

• Tests added: 3 (mini_header_v2_roundtrip, mini_frame_context_v2_expand, mini_frame_context_v2_no_baseline)
• Tests modified: 0
• Workspace test count before: 568 pass / 0 fail (non-Android subset)
• Workspace test count after: 571 pass / 0 fail (non-Android subset)
• cargo clippy -p wzp-proto --all-targets -- -D warnings: pass
• cargo fmt --all -- --check: pass

Risks / follow-ups

• MiniHeaderV2 / MiniFrameContextV2 must be renamed to MiniHeader / MiniFrameContext in T1.5 after v1 types are deleted.

Reviewer checklist (filled in by reviewer)

• Code matches PRD intent
• Verification output is real (re-run if suspicious) — re-ran cargo test -p wzp-proto mini (12 passed), clippy + fmt clean.
• No backward-incompat surprises — pub type MiniHeader = MiniHeaderV1 and the equivalent alias for MiniFrameContext keep current call sites compiling.
• Tests cover the new behavior — mini_frame_context_v2_expand is particularly good: tests two consecutive expansions, proving seq_delta carries forward state correctly (this is exactly the W4 desync scenario).
• Approved

Reviewer notes (2026-05-11)

Approved. Naming workaround (V2 suffix + alias) is consistent with T1.1 and will be cleaned up in T1.5. The two-step expansion test is well-designed — it catches the bug audit W4 was about.

One small follow-up:

1. T1.4.1 — Add rustdoc on MiniHeaderV2 / MiniFrameContextV2 public items. Same rustdoc-coverage pattern as T1.1.1 and T1.2.1 (coding standard #9). Public fields and methods need /// comments; the structs already have top-level doc comments which is good.