refactor(network): validate aligned header range payloads

[p0mvn]

Motivation

Header-sync range geometry is currently represented by loose start_height and count fields, while headers, body-size hints, and tree-aux roots cross asynchronous boundaries as independent vectors. The upcoming root-authentication lane will reuse one response for operations with different prefixes, making unchecked arithmetic and independent slicing unsafe.

PR #246 answered: “Which request and operation produced this completion?”

This PR answers: “Exactly which heights and per-height data belong to that operation?”

Why this matters:

• Root authentication requests [F+1 … E+1] but authenticates only [F+1 … E]; the last header is a successor witness.
• Short peer responses change the actual endpoint.
• Existing block progress can trim a buffered range.
• One response will eventually feed both header commit and root authentication.
• CheckedHeaderRange prevents zero-length, reversed, or overflowing range geometry and supplies checked prefix/suffix operations.

HeaderRangePayload binds headers, body-size hints, and optional roots together. Trimming a prefix now slices all three atomically, preventing roots or counts from becoming associated with the wrong header.

This is prerequisite scaffolding only. It does not yet:

• authenticate roots;
• change the wire protocol;
• change persistence;
• add the authentication frontier;
• add overlapping root scheduling.

The next design step can therefore implement state-owned root persistence knowing that network responses have exact identities, checked heights, and structurally aligned data.

Solution

• add CheckedHeaderRange for non-empty, overflow-safe inclusive geometry and checked prefix/suffix operations
• add HeaderRangePayload to validate and atomically slice headers, body sizes, and optional all-or-nothing roots
• carry the aligned payload through buffering, commit actions, tracing, the testkit, and the node state driver
• keep the wire encoding, protocol version, state request, and scheduling behavior unchanged

Specifications & References

• docs(design): specify VCT root authentication #230
• Builds on refactor(network): correlate header operations by exact identity #246

[v12-auditor]

Note

Complete: Audit complete. V12 did not find any issues that need review.

Open the full results here.

Analyzed 13 files, diff fa490f3...38f1e85.

[evan-forbes]

we're free to make breaks atm

therefore if its easier to just stick everything in a struct and have a single vector then I'm down

we can even include the request ids in the message

generally not against so I don't want to block, but I think we could also still find a better solution

[evan-forbes]

personally find the name geometry here unconventional and not intuitive

perhaps we could just say, invalid range

[p0mvn]

Ah, this was an initial AI choice. I thought I renamed everything, but it looks like this one remained. Changing

[p0mvn]

I am making a follow-up PR to address the comments