alkblobs/tasks/fuzz-target-ops-ingress.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
fuzz-target-ops-ingress	Fuzz target — `ops_ingress` (the ops payload ingress surfaces)	completed	fuzz-scaffold fuzz-ingress-exposure	moderate	medium	component	implementation	wave-11 fuzzing ops

Description

The plan's second named target cluster: the ops payload surfaces — resolved at decomposition to the alkblobs-owned post-schema ingress (the JSON-spec schema gate itself is alkcall's surface, family-fuzzed there; the in-process harness is #[cfg(test)] and unavailable to the sidecar). Two drivers:

• fetch_ranges_ingress (via the fuzz-ingress-exposure re-exports) — the ranged-fetch bounds ingress (review-001 S-2's remediated surface): the {offset, len} items parse and the total-bytes bound arithmetic. Input: arbitrary JSON Values — raw-byte serde_json parses plus arbitrary-derived JsonValues (the scaffold's bounded-depth helper). Invariants:

  • no-panic on any Value — the baseline;
  • the absent-field contract: no ranges field → Ok(None) (the whole-form fetch);
  • item-shape rejects: a non-array ranges, or any item missing offset/len or carrying non-u64 shapes (negatives, floats, strings, nulls, nested) → Err with the stable domain text, never a panic, never Ok;
  • bound arithmetic: a checked_add overflow of the running sum → Err (the over-bytes text); a sum over max_total_bytes → Err carrying the wire numbers; a sum within the bound → Ok(Some) with every range's (offset, len) preserved exactly and in order;
  • boundary exactness (constructed probes in the replay module): total == bound accepts, bound + 1 rejects;
  • the count bound is not this ingress's duty: an over-count array within the bytes bound parses Ok — the maxItems gate lives at the schema (alkcall's); pinned honestly, not asserted away;
  • determinism: double invocation, same verdict.

• PinToken::from_hex (public API, src/ops/tokens.rs) — the renewal form's token ingress (review-001 S-5's remediated surface). Input: arbitrary strings (lossy-decoded bytes + arbitrary-derived). Invariants:

  • no-panic on any string;
  • length-before-decode (the S-5 posture): any length ≠ 64 → None — the 1 MiB canary seed pins the rejection (correctness observable; the proportional-allocation absence stays pinned by the existing unit test's shape);
  • non-hex 64-char → None; case-insensitive decode agreement with the wire schema's pattern (upper == lower == Some, same bytes — the S-5 case posture);
  • round-trip: to_hex ∘ from_hex closes on accepted tokens;
  • determinism.

• fuzz_targets/ops_ingress.rs — the thin fuzz_target! wrapper delegating to alkblobs_fuzz_shared::ops_ingress::fuzz_ops_ingress(data); the [[bin]] entry lands in fuzz/Cargo.toml.

• shared/src/ops_ingress.rs — the invariant logic + the #[cfg(test)] replay module.

• shared/Cargo.toml — the alkblobs dep gains features = ["ops"] (design point, recorded: features unify per build, so from this task on the gate build compiles alkcall transitively; the gate stays stable-clean — alkcall is published and stable-built family-wide).

• Seeds (via gen_fuzz_seeds.py gaining ops_ingress_seeds()): ranges arrays — absent field, empty, one item, many items, an over-default-count array, malformed items (missing fields, negatives, floats, strings, nulls, nested objects), lens at u64::MAX, sums overflowing, sums at/over/under a bound; token forms — valid 64-hex lower/upper, 63/65/0 lengths, the 1 MiB canary, non-hex, unicode, whitespace. Corpus committed under fuzz/corpus/ops_ingress/; the gitignore negation lines; the README targets-table row.

Campaign flags are the campaign task's concern (-max_len=65536 -dict=json.dict starting point); this task lands target + seeds + replay.

Acceptance Criteria

• fuzz_targets/ops_ingress.rs + shared/src/ops_ingress.rs exist; cargo fuzz build builds the target (nightly, from fuzz/)
• All invariants above implemented in shared and exercised by both the fuzz path and the #[cfg(test)] replay module (including the boundary-exactness probes and the over-count honesty pin)
• Seed corpus committed (fuzz/corpus/ops_ingress/), generated by python3 fuzz/gen_fuzz_seeds.py (deterministic — re-running is a no-op diff); gitignore negation in place
• cargo test --manifest-path fuzz/shared/Cargo.toml green (the gate now compiles the ops feature — alkcall transitively — and stays stable-clean)
• shared clippy/fmt gates green
• Root workspace gates still green (the exposure's visibility-only diff unchanged by this task)

References

• docs/plans/implementation.md §Wave 11 (the ops payload surfaces cluster; the decomposition record's resolution)
• tasks/fuzz-ingress-exposure.md (the drive surface this target consumes)
• src/ops/fetch.rs (fetch_ranges_ingress — the S-2 ingress); src/ops/tokens.rs (PinToken::from_hex — the S-5 ingress)
• tasks/review-wave-10.md (S-2/S-5's landed shapes — the bound arithmetic and the length-before-decode posture the invariants pin)
• /workspace/@alkdev/alkstore/tasks/fuzz-target-payload-codec.md (the family target-task pattern; its arbitrary-JSON input shape)
• /workspace/@alkdev/alkstore/fuzz/shared/src/arbitrary_value.rs (the bounded-depth JsonValue helper the scaffold copies)

Notes

• Verdict-vs-recomputation shape (the key_encoding precedent's discipline): both ingress verdicts are held against a locally recomputed contract (RangesVerdict, the token_accepted_locally rule) plus a double-invocation determinism pin, over raw-byte serde_json parses (and lossy-decode re-parses), arbitrary-derived JsonValues/strings, and the constructed batteries. The stable texts are pinned exactly — the array/item texts as consts matching the S-2 landed wording, the two bytes-bound forms rebuilt from the bound (the over-bound form's wire numbers therefore verified verbatim, not by substring).
• No derives were needed: FetchRange ships Debug-less by the exposure's design, so the replay-module panic messages format tuples/strings instead of the struct (the exposure task's pinned constraint, held on this side too).
• The over-count honesty pin constructs max_ranges: 1 bounds over a 64-item array: the ingress answers Ok(Some(64)) — the count gate demonstrably not this ingress's duty. The unknown-extra- field item ({"offset":0,"len":1,"extra":2}) is the same posture on the item side (accepted; additionalProperties is the schema's).
• The arbitrary-value reach: the bounded-depth JsonValues are driven three ways (whole input, as the ranges field, as a two-element array's items) — the generator's keys never spell offset/len, so accepts stay the batteries' province and the arbitrary path exercises the reject branches through structure. The canary is a LazyLock so the battery's 1 MiB string is built once per process, not per exec.
• A smoke campaign ran detached (FUZZ_RUNTIME_SECS=60 ops_ingress -max_len=65536 -dict=json.dict): 69 s, 0 oom/timeout/ crash, cov 1654 / corp 343 at ~345 exec/s — the target drives end-to-end; the campaign itself stays the campaigns-and-gate task's concern.
• Seeds came out at 53 including the 1 MiB token canary; the replay floor is ≥ 32 (the key_encoding precedent's shape).

Summary

Landed (2026-10-16) the wave-11 ops_ingress fuzz target — the ops payload ingress surfaces, resolved to alkblobs' post-schema ingress:

• fuzz/shared/src/ops_ingress.rs (new): both ingress surfaces — fetch_ranges_ingress (via the #[doc(hidden)] re-exports of the exact production function) and PinToken::from_hex (public API) — pinned by the recomputed-contract + determinism discipline across the raw-byte, arbitrary (JsonValue bounded-depth helper + strings), and battery input space. Invariants landed: no-panic on any Value/string; the absent-field contract (Ok(None)); item-shape and non-array rejects on the exact stable texts; the bound arithmetic (overflow form, over-bound form with wire numbers, within-bound accepts with ranges preserved exactly and in order); boundary exactness (total == bound accepts, bound + 1 rejects); the over-count honesty pin (a max_ranges: 1 shape must not filter a 64-item array — the maxItems gate lives at alkcall's schema); the token length-before-decode posture (1 MiB canary pins the rejection), case-insensitive decode agreement (upper == lower == Some, same bytes), and to_hex ∘ from_hex round-trip closure. The #[cfg(test)] replay module replays the committed corpus, the standalone no-corpus probes, and the boundary/over-count/S-5 posture probes.
• fuzz/fuzz_targets/ops_ingress.rs + the [[bin]] entry: the thin wrapper. shared/Cargo.toml: alkblobs gains features = ["ops"] — the recorded design point held: the gate build now compiles alkcall transitively and stays stable-clean.
• Seeds: gen_fuzz_seeds.py gained ops_ingress_seeds() — 53 deterministic seeds committed under fuzz/corpus/ops_ingress/ (re-run is a no-op diff), the gitignore negations, the README targets-table row. fuzz/Cargo.lock updated (alkcall et al).

Verified: cargo test --manifest-path fuzz/shared/Cargo.toml green (7 tests: corpus replay 53/53 + the key_encoding replays + the probe tests); shared clippy -D warnings + fmt --check green; cargo fuzz build green from fuzz/ (nightly, both targets); a 60 s detached smoke campaign clean (0 oom/timeout/crash); root workspace gates green (cargo test default 149+54+4, --features ops 201+54+4, clippy -D warnings on both builds, fmt --check). No src/ changes — the exposure's visibility-only diff rides untouched.