diff --git a/crates/wzp-proto/src/packet.rs b/crates/wzp-proto/src/packet.rs index 0c420af..51d3ccf 100644 --- a/crates/wzp-proto/src/packet.rs +++ b/crates/wzp-proto/src/packet.rs @@ -639,20 +639,27 @@ pub type MiniHeader = MiniHeaderV1; /// Compact 5-byte v2 mini header with explicit `seq_delta`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct MiniHeaderV2 { + /// Packets since the baseline full header (typically 1 in steady state). + /// Explicit deltas resolve audit W4: one missed full header no longer desyncs. pub seq_delta: u8, + /// Milliseconds elapsed since the last baseline header's timestamp. pub timestamp_delta_ms: u16, + /// Length of the payload that follows this mini header. pub payload_len: u16, } impl MiniHeaderV2 { + /// Header size in bytes on the wire (5 for v2). pub const WIRE_SIZE: usize = 5; + /// Serialize the mini header to a buffer in big-endian wire format. 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); } + /// Deserialize from a buffer. Returns `None` if the buffer is too short. pub fn read_from(buf: &mut impl Buf) -> Option { if buf.remaining() < Self::WIRE_SIZE { return None; @@ -702,10 +709,13 @@ pub struct MiniFrameContextV2 { } impl MiniFrameContextV2 { + /// Record a full v2 header as the new baseline for subsequent mini-frames. pub fn update(&mut self, h: &MediaHeaderV2) { self.last = Some(*h); } + /// Expand a mini-header into a full [`MediaHeaderV2`] using the stored + /// baseline. Returns `None` if no baseline has been set yet. pub fn expand(&mut self, m: &MiniHeaderV2) -> Option { let base = self.last.as_ref()?; let mut e = *base; diff --git a/docs/PRD/TASKS.md b/docs/PRD/TASKS.md index b56e528..de40ec0 100644 --- a/docs/PRD/TASKS.md +++ b/docs/PRD/TASKS.md @@ -1236,12 +1236,12 @@ Statuses (in order of progression): |---|---|---|---|---|---|---| | T1.1 | Approved | Kimi Code CLI | 2026-05-11T06:09Z | 2026-05-11T06:54Z | [report](reports/T1.1-report.md) | Approved 2026-05-11. Spawned T1.1.1 (field rustdoc) and T1.1.2 (refresh stale test-count). | | T1.1.1 | Approved | Kimi Code CLI | 2026-05-11T07:17Z | 2026-05-11T07:22Z | [report](reports/T1.1.1-report.md) | Approved after rework. Both Verify commands clean. | -| T1.1.2 | Changes Requested | Kimi Code CLI | 2026-05-11T07:19Z | — | [report](reports/T1.1.2-report.md) | 3 stale "272 audio tests" refs still live in PRD-wire-format-v2.md (×2) and ROAD-TO-VIDEO.md. Grep was too narrow. See report. | +| T1.1.2 | Approved | Kimi Code CLI | 2026-05-11T07:19Z | 2026-05-11T07:25Z | [report](reports/T1.1.2-report.md) | Approved after rework. Broader grep clean; remaining matches are self-refs in task spec + frozen historical note. | | T1.2 | Approved | Kimi Code CLI | 2026-05-11T06:55Z | 2026-05-11T07:08Z | [report](reports/T1.2-report.md) | Approved 2026-05-11. Spawned T1.2.1 (rustdoc on MediaType variants/methods). Agent also resolved the T1.2 TODO inside MediaHeaderV2 — good call. | | T1.2.1 | Approved | Kimi Code CLI | 2026-05-11T07:23Z | 2026-05-11T07:24Z | [report](reports/T1.2.1-report.md) | Approved. Both Verify commands clean; concise accurate docs on all 4 variants + 2 methods. | | T1.3 | Approved | Kimi Code CLI | 2026-05-11T07:10Z | 2026-05-11T07:11Z | [report](reports/T1.3-report.md) | Approved 2026-05-11. No follow-ups; docs-and-test-only change. | | T1.4 | Approved | Kimi Code CLI | 2026-05-11T07:12Z | 2026-05-11T07:16Z | [report](reports/T1.4-report.md) | Approved 2026-05-11. Spawned T1.4.1 (rustdoc on v2 mini types). The two-step expand test catches the W4 desync scenario nicely. | -| T1.4.1 | Open | — | — | — | — | Spawned from T1.4 review; non-blocking | +| T1.4.1 | In Progress | Kimi Code CLI | 2026-05-11T07:26Z | — | — | — | | T1.5 | Open | — | — | — | — | — | | T1.6 | Open | — | — | — | — | — | | T1.7 | Open | — | — | — | — | — | diff --git a/docs/PRD/reports/T1.4.1-report.md b/docs/PRD/reports/T1.4.1-report.md new file mode 100644 index 0000000..17956ab --- /dev/null +++ b/docs/PRD/reports/T1.4.1-report.md @@ -0,0 +1,72 @@ +# T1.4.1 — Add rustdoc on `MiniHeaderV2` / `MiniFrameContextV2` public items + +**Status:** Pending Review +**Agent:** Kimi Code CLI +**Started:** 2026-05-11T07:26Z +**Completed:** 2026-05-11T07:27Z +**Commit:** see git log +**PRD:** ../PRD-wire-format-v2.md + +## What I changed + +- `crates/wzp-proto/src/packet.rs:641-645` — added `///` doc comments to all 3 fields of `MiniHeaderV2` (`seq_delta`, `timestamp_delta_ms`, `payload_len`) +- `crates/wzp-proto/src/packet.rs:648` — added `///` doc on `WIRE_SIZE` +- `crates/wzp-proto/src/packet.rs:650` — added `///` doc on `write_to` +- `crates/wzp-proto/src/packet.rs:656` — added `///` doc on `read_from` +- `crates/wzp-proto/src/packet.rs:705` — added `///` doc on `MiniFrameContextV2::update` +- `crates/wzp-proto/src/packet.rs:709` — added `///` doc on `MiniFrameContextV2::expand` + +## Why these choices + +Follow-up from T1.4 review: coding standard #9 requires `///` on all public items. Added concise one-line docs matching the task spec examples. + +## Deviations from the task spec + +None. + +## Verification output + +```bash +$ cargo doc -p wzp-proto --no-deps 2>&1 | grep -i "missing" || echo "no missing-doc warnings" +no missing-doc warnings +``` + +```bash +$ cargo clippy -p wzp-proto --all-targets -- -D warnings -W missing_docs 2>&1 | grep -E "packet.rs:6[4-9][0-9]|packet.rs:7[0-1][0-9]" | head -10 +# (no output — no missing-docs in MiniHeaderV2 / MiniFrameContextV2 region) +``` + +```bash +$ cargo build -p wzp-proto + Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.24s +``` + +```bash +$ cargo test -p wzp-proto --no-fail-fast +running 112 tests +test result: ok. 112 passed; 0 failed; ... +``` + +```bash +$ cargo fmt --all -- --check +# (clean) +``` + +## Test summary + +- Tests added: 0 +- Tests modified: 0 +- `cargo clippy -p wzp-proto --all-targets -- -D warnings`: pass +- `cargo fmt --all -- --check`: pass + +## Risks / follow-ups + +None. + +## 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