feat(read): signed readers and try_bytes window

[h4x0r]

Two additions to safe-read per ADR-0019 and §2.1 of the fleet DRY audit, built under strict TDD (RED commit d5ced20, GREEN commit 9d73f28), plus one documentation fix (fa568d6).

What's added

Signed readers — le_i16/be_i16/le_i32/be_i32/le_i64/be_i64 and their try_ twins. They fall out of the existing bounded_reader! macro with from_le_bytes/from_be_bytes on the signed types; no hand-written function bodies.

A caller that reads a declared-signed field through the unsigned reader gets the huge positive twin rather than the negative value. The consumers that do this today: winevt cursor.rs:122-152, forensicnomicon decode.rs (read_i32_le/read_i64_le), lnk lib.rs:208, snss lib.rs:293, segb common.rs:77.

try_bytes::<N>(data, off) -> Option<[u8; N]> — the array flavour of the same bounded read, for fixed-width windows that aren't integers (GUIDs, signatures, digests). The bounded_reader! macro already did this internally; this surfaces it. Re-derived today by ntfs arr, vsc read_guid (bytes.rs:36) and vhdx guid_at (integrity.rs:67).

Semantics preserved exactly

checked_add on off + width; plain readers return 0 out of range, try_ twins return None; never a panic.

Crate properties preserved

• #![no_std], zero dependencies — unchanged.
• unsafe_code = "forbid" — unchanged.
• MSRV 1.75 — cargo +1.75.0 check passes. try_bytes uses const generics (stable since 1.51) and slice::get + copy_from_slice; no 1.82-era API (is_none_or is not used).

Cargo.toml is untouched: no dependency added, and the package version is left for release-plz to compute from the feat commit.

The README caret, and why it moves in this PR

fa568d6 widens the README install snippet from safe-read = "0.1" to "0.3".

That snippet is the cause of a live finding, not merely a stale doc: six consuming repos pin "0.1" and are therefore stranded below the published 0.2.1, because cargo update never crosses a minor inside a caret. They pin "0.1" because the README told them to, so leaving it keeps minting the defect on each new consumer.

"0.3" is the version release-plz cuts from this PR's feat commit, so it is correct by the time anyone reads the merged README. This edits a consumer's dependency requirement in documentation, which is distinct from the package's own version = field — that stays release-plz's to compute and is untouched. The six consuming repos are deliberately not touched here; that sweep is separate work.

Out of scope, deliberately

LEB128 varints (a format, not a bounded read — and safe-read cannot carry the typed error a forensic varint decoder needs) and UTF-16 decoding (needs alloc; it belongs to a separate safe-decode crate per ADR-0019). Both were proposed and withdrawn in the audit.

Gate

Check	Result
cargo build	pass
cargo test	17 passed (15 lib + 2 doctest), 0 failed
cargo clippy --all-targets -- -D warnings	clean
cargo fmt --check	clean
cargo +1.75.0 check	pass (declared MSRV floor)
cargo llvm-cov --all-features --fail-under-functions 100	100.00% regions (349/349), functions (20/20), lines (151/151)

Fuzz — fuzz/fuzz_targets/readers.rs extended, not replaced: it now drives the six signed readers and try_bytes at N ∈ {0, 1, 4, 8, 16, 32}, both at the adversarial usize::MAX-adjacent offset and across the past-the-end boundary sweep. 14,389,581 executions in 46 s, no crash.

🤖 Generated with Claude Code