# 1. Repair Decision **Decision: RANGE NORMALIZATION CONVERTS INCLUSIVE HTTP BOUNDS TWICE AND `IF-RANGE` IS CHECKED TOO LATE — SAFE LOCAL DOWNLOAD-INTEGRITY REPAIR AVAILABLE; AUTHORIZATION, STORAGE, ETAG, COMPRESSION, RETRY, AND PUBLIC-ERROR POLICY REMAIN UNCHANGED.** # 2. Scope & Safety Boundary Reviewed the Go Range parser, object-length lookup, interval conversion, storage slice reader, `If-Range` gate, response builder, retry/resume helper, cleanup path, tests, metrics, and docs. Validation uses only deterministic local byte fixtures. No production object, credential, customer payload, remote storage, CDN, or deployed state is accessed. # 3. Download Integrity Register - representation length: supplied by the existing storage abstraction; - requested interval: inclusive HTTP bytes; - internal storage interval: intended half-open `[start,end)`; - open-ended defect: the end is incremented before entering a helper that increments again; - suffix defect: `length - suffix` underflows when suffix exceeds object length; - `If-Range`: evaluated after partial-reader creation; - response framing: built from a different interval object than the storage reader; - retry behavior: existing committed-byte policy remains authoritative. # 4. Range / Resume Timeline `bytes=1048576-` parses to inclusive `[1048576,last]`. One helper converts it to half-open bounds, then the storage reader adjusts the end again. The request therefore uses inconsistent payload and framing lengths. An oversized suffix subtracts before clamping. A changed `If-Range` opens the partial reader before the handler decides to fall back to the repository's existing full-response path. # 5. Findings - interval conversion has more than one owner; - suffix normalization occurs in the wrong order; - validator gating is too late; - storage read and response headers do not consume one canonical interval; - tests assert statuses but not exact boundary bytes; - retry policy itself is not the defect. # 6. Canonical Interval & Representation Contract One helper receives the parsed HTTP range plus complete representation length and returns either a canonical satisfiable interval, an unsatisfiable result, or the existing parse/error outcome. The canonical result contains inclusive HTTP start/end, half-open storage start/end, exact payload length, and total representation length. Storage reads, `Content-Range`, `Content-Length`, and 206/416 selection use that same result. `If-Range` is evaluated before partial reader creation. A mismatch follows the repository's existing full-response behavior. # 7. Repair Applied - centralize inclusive-range normalization; - clamp oversized suffix length before computing its start; - remove duplicate end conversion from storage reading; - evaluate `If-Range` before partial stream selection; - drive storage reads and response framing from one canonical interval; - preserve authorization, storage API, ETag policy, compression, retries, and public errors; - add deterministic byte fixtures whose contents expose off-by-one errors; - add redacted interval/status telemetry. # 8. Protocol / Storage Safety No authorization or storage policy is broadened. No live object is read. Invalid ranges cannot become wider authorized reads. Partial delivery starts only after required range and validator checks. Compression policy is preserved; the patch does not reinterpret compressed offsets as uncompressed offsets. # 9. Deterministic Byte Test Matrix 1. full 200 body equals source bytes; 2. first-byte and last-byte single ranges; 3. open-ended range returns the exact expected tail; 4. suffix smaller than object returns exact final N bytes; 5. suffix larger than object follows existing policy without underflow; 6. unsatisfiable start preserves 416 behavior; 7. `Content-Range` equals payload boundaries; 8. `Content-Length` equals emitted byte count; 9. changed `If-Range` falls back before partial stream creation; 10. unchanged validator permits correct 206; 11. resume output contains no gap or duplicated byte; 12. cleanup preserves the first real error. # 10. Observability & Rollout Track parse result, normalized interval, validator result, response status, expected/emitted byte counts, resume offset, and terminal reason. Never log payload bytes, credentials, or secret-bearing URLs. Rollout remains bounded to the download module and local regression suite. # 11. Files Modified - `internal/download/range.go` - `internal/download/handler.go` - `internal/download/ifrange.go` - `internal/download/handler_test.go` - `docs/download-integrity-contract.md` # 12. Commands Executed - `go test ./internal/download` - `go test -race ./internal/download` - `go vet ./...` # 13. Validation Local results: full response PASS; first/last byte PASS; open-ended PASS; oversized suffix PASS; unsatisfiable PASS; 206 framing PASS; changed/unchanged `If-Range` PASS; exact byte comparisons PASS; retry/resume regression PASS; race/vet PASS. Not verified: production storage, external proxies/CDNs, or compression behavior outside repository fixtures. # 14. Remaining Decisions & Handoff No authorization, storage, ETag, compression, retry, or public-error policy change is required. A backend with a different native interval representation should adapt only at the storage boundary. **Handoff: PATCH READY FOR LOCAL REVIEW — RANGE CONVERSION HAS ONE OWNER, VALIDATORS RUN BEFORE PARTIAL DELIVERY, AND RESPONSE FRAMING USES THE SAME INTERVAL AS THE STORAGE READ.**