alkblobs/tasks/fuzz-ingress-exposure.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
fuzz-ingress-exposure	Ingress exposure — `#[doc(hidden)]` narrow surface for the ranged-fetch bounds ingress	completed		narrow	low	component	implementation	wave-11 fuzzing ops

Description

The wave-11 exposure design point, resolved by this decomposition: widen in place + #[doc(hidden)] re-exports — the alkstore fuzz-parser-exposure precedent (its option (b)), not a shim. The ops-ingress fuzz target needs direct access to the ranged-fetch bounds ingress, which is crate-internal:

• fetch_ranges_ingress (src/ops/fetch.rs, pub(crate)-module private fn) — the post-schema {offset, len} items parse and the total-bytes bound arithmetic (review-001 S-2's remediated surface, the one network-facing resource bound). Its signature carries two private structs: FetchRange { offset, len } and RangedBounds { max_ranges, max_total_bytes }.
• FetchRange and RangedBounds widen to pub with pub fields (inert data carriers; the target must read the parsed ranges and construct the bounds).

All three re-export from lib.rs under the existing #[cfg(feature = "ops")] block, #[doc(hidden)], each with the one-line fuzz/test-only doc note (not contract surface, not consumer API, no stability guarantee — the alkstore Job::from_row doc posture).

Why widen-in-place and not a shim (the rejected alternative, recorded): a fetch_ranges_ingress_for_fuzz(input, max_ranges, max_total_bytes) wrapper would be a src/ function whose only consumers are the fuzz sidecar and its reachability pin — dead weight, and a drift risk (the target must drive the exact production function; a shim is a second signature that can silently diverge from the real ingress's evolution). Widening keeps one function. Why not the harness route: the in-process call harness (ops/harness.rs) is #[cfg(test)] — unavailable to the sidecar by construction; and the schema gate upstream of this ingress is alkcall's surface (family-fuzzed there), so the alkblobs-owned delta is exactly this post-schema ingress.

Mechanical constraint (the alkstore lesson, compile-probed there): a pub use re-export requires the item itself to carry pub — E0364/E0603 otherwise. The delta is visibility-only: three visibility keywords plus the re-export block and doc notes. No behavior change; no logic moves; no signature changes.

Semver note (recorded, not hidden): doc-hidden pub items are still public API — removal is technically breaking. The same commitment the family's doc-hidden surfaces made, bounded here to a fuzz/test purpose. RangedBounds' max_ranges field is not the ingress's own duty (the count bound lives at the schema gate, alkcall's) — the struct rides the signature; the target pins that honestly.

Acceptance Criteria

• fetch_ranges_ingress, FetchRange, RangedBounds are pub in place with pub fields where the target needs them; the diff is visibility keywords + doc notes + the re-export block, nothing else
• All three re-exported from lib.rs, #[doc(hidden)], under #[cfg(feature = "ops")], with the fuzz/test-only doc note
• Reachability pin: a compile-level test drives the crate-root re-exports (one accept case + one reject case through fetch_ranges_ingress) — a #[cfg(test)] module or a fuzz_surface_tests-style module, the alkstore precedent's shape; record which
• No behavior change: root gates green (cargo test default, clippy -D warnings, fmt --check) on the default build AND the ops build (cargo clippy --features ops --all-targets -- -D warnings — the re-export block is feature-gated, so the ops build is where it compiles)
• cargo doc --no-deps zero warnings on the ops build (the doc-hidden items' notes are doc-clean)

References

• docs/plans/implementation.md §Wave 11 (the ops payload surfaces' target cluster; the decomposition record's exposure design point)
• src/ops/fetch.rs (fetch_ranges_ingress, FetchRange, RangedBounds — the S-2 remediated ingress)
• src/lib.rs (the #[cfg(feature = "ops")] re-export block this extends)
• /workspace/@alkdev/alkstore/tasks/fuzz-parser-exposure.md (the family precedent: option (b), the E0364 mechanical constraint, the reachability-pin shape, the semver note)
• tasks/review-wave-10.md (S-2's landed shape — the ingress's checked_add sum and stable texts the target pins)

Notes

• **Reachability pin (recorded per the criterion): src/fuzz_surface_tests.rs declared in lib.rs as #[cfg(all(test, feature = "ops"))] mod fuzz_surface_tests; — the alkstore precedent's shape (fuzz_surface_tests.rs, doc_hidden_reexports_reach_the_crate_root). The feature = "ops" conjunct is this task's delta on the precedent: the re-export block (and the ingress itself) does not exist on the default build, so the pin is only compiled under the ops build (run cargo test --features ops). The test drives all three re-exports through the crate-root paths (crate::fetch_ranges_ingress, crate::FetchRange, crate::RangedBounds) — a read of both RangedBounds fields, the absent-ranges whole form (Ok/None), one accept case (two ranges parsed in order, both items' fields read), and two reject cases (the over-bytes checked_add sum past max_total_bytes, and a malformed item) so both of the ingress' stable rejection texts are exercised across the public surface.
• No derives were added (the AC's "nothing else" held): FetchRange ships without Debug/PartialEq, so the pin asserts through the fields ((ranges[0].offset, ranges[0].len)-shaped tuple compares and match-shaped rejection capture) rather than struct equality — the same constraint the fuzz target itself will face, pinned by it.
• Field docs added on the two widened structs (the only doc-comment delta on source): the pub fields are public API surface now, so each carries a line — FetchRange { offset, len } window semantics, and RangedBounds.max_ranges marked as the schema gate's bound (the count bound is not this ingress' own duty; the struct rides the signature), max_total_bytes as the summed-lens bound this ingress enforces.
• Two doc-hidden hops, one doc note each: ops/mod.rs re-exports the three from the private mod fetch (the alkstore mod.rs facade lesson — the private module's path cannot be named at the crate root, so lib.rs re-exports through ops::), and lib.rs re-exports from ops:: under the cfg block. The lib.rs note covers all three items (the ingress and its two data carriers) — one statement, one note, the same fuzz/test-only doc posture text.
• Semver note (per the description): doc-hidden pub items are still public API — removal is technically breaking; bounded to a fuzz/test purpose.

Summary

Landed (2026-10-16): the #[doc(hidden)] narrow fuzz/test surface for the ranged-fetch bounds ingress — the alkstore fuzz-parser-exposure precedent's option (b), widen-in-place:

• src/ops/fetch.rs: fetch_ranges_ingress (fn → pub fn), FetchRange and RangedBounds (struct → pub struct, fields → pub with field docs). Zero logic, zero signatures, zero derives — visibility keywords plus field doc notes only.
• src/ops/mod.rs: doc-hidden re-export of the three from fetch (the facade hop; noted).
• src/lib.rs: doc-hidden re-export of the three from ops:: under the #[cfg(feature = "ops")] posture, plus the fuzz_surface_tests module declaration.
• src/fuzz_surface_tests.rs (new): the reachability pin — crate-root-pathing all three re-exports, accept + reject cases recorded above.

Verified: cargo test (default) green (149 unit + 54 + 4 integration); cargo test --features ops green including the new pin; cargo clippy --all-targets -- -D warnings clean on default AND ops builds; cargo fmt --check clean; cargo doc --no-deps --features ops zero warnings. Diff audited: visibility keywords + doc notes + the two re-export statements + the test module — nothing else.