fix(store): rustdoc hygiene + u64-safe cursor clamping

- resolve or unlink 25 preexisting rustdoc warnings: broken
  intra-doc links (error variants), public-docs-linking-private-items
  (crate-internal cursor/registry names), and one stale reference to a
  `Store::window_host` that never existed (the form branch is
  `sweep_window`'s engine-enum match)
- `clamped` runs its arithmetic in u64 and narrows to usize after
  clamping, so a wide u64 offset can never wrap onto a small slice
  position on narrow-pointer targets; the cursor contract tests pin
  the overflowing-offset and overflowing-length forms
- zero rustdoc warnings under RUSTDOCFLAGS=-D warnings

Verification: cargo test (69+19+3 green), cargo test --all-features
(124+54+4 green), cargo clippy --all-targets -- -D warnings green,
cargo fmt --check green, RUSTDOCFLAGS=-D warnings cargo doc --no-deps
green.
This commit is contained in:
glm-5.3-flash committed 2026-10-12 05:40:09 +00:00
1 parent 97cdf682c4
commit 611d30a3c4
6 files changed
+47 -28

No files matched your search

+19 -3
View File
@@ -242,10 +242,16 @@ pub(crate) trait Backend: Send + Sync {
/// EOF-clamping arithmetic of the cursor contract. Crate-internal: the
/// engine cursor bodies behind [`Backend::Cursor`] compose this, so every
/// engine's materializing and staging bodies clamp identically.
///
/// The arithmetic runs in `u64` — the offset/len domain — and narrows to
/// `usize` only after clamping, so a truncated `as usize` cast can never
/// wrap a huge offset back onto a small slice position on narrow-pointer
/// targets.
pub(crate) fn clamped(offset: u64, len: u64, total: usize) -> (usize, usize) {
let start = (offset as usize).min(total);
let end = start.saturating_add(len as usize).min(total);
(start, end)
let total = total as u64;
let start = offset.min(total);
let end = start.saturating_add(len).min(total);
(start as usize, end as usize)
}
#[cfg(test)]
@@ -333,6 +339,16 @@ mod tests {
Vec::<u8>::new(),
"read at EOF is empty, never an error"
);
assert_eq!(
cursor.read_at(u64::MAX, 5).await.unwrap(),
Vec::<u8>::new(),
"an overflowing u64 offset clamps to EOF in u64 arithmetic — never wraps"
);
assert_eq!(
cursor.read_at(0, u64::MAX).await.unwrap(),
whole,
"an overflowing u64 length clamps to the whole body"
);
assert_eq!(
cursor.read_at(0, 0).await.unwrap(),
Vec::<u8>::new(),