wave-7 decomposition — seven fuzzing tasks: scaffold, parser exposure (§3.2 resolved as option b), three targets, campaigns + gate wiring, review gate

tasks/fuzz-target-payload-codec.md

@@ -0,0 +1,88 @@
+---
+id: fuzz-target-payload-codec
+name: Fuzz target — `payload_codec` (core payload encode/decode invariants)
+status: pending
+depends_on: [fuzz-scaffold]
+scope: moderate
+risk: low
+impact: component
+level: implementation
+tags: [wave-7, fuzzing]
+---
+
+## Description
+
+The §3.1 target: `payload_codec`, driving core's payload surface
+(`alkstore/src/payload.rs` — `encode_payload`, `payload_as::<T>`) —
+already-`pub` API, no exposure needed.
+
+- **`fuzz_targets/payload_codec.rs`** — the thin `fuzz_target!`
+  wrapper (3-line pattern) delegating to
+  `alkstore_fuzz_shared::payload_codec::fuzz_payload_codec(data)`;
+  the `[[bin]]` entry lands in `fuzz/Cargo.toml`.
+- **`shared/src/payload_codec.rs`** — the invariant logic, with the
+  `#[cfg(test)]` corpus-replay module (the gate). Input: raw `&[u8]`
+  plus `arbitrary`-derived `serde_json::Value`s (the
+  `JsonValue` bounded-depth helper from the scaffold). Invariants
+  (§3.1, verbatim):
+  - **no-panic on any byte sequence** (the baseline);
+  - **typed-failure partition**: every decode failure is
+    `Error::Codec` — no other variant, no panic (the ADR-023 §1
+    fallibility pin, demonstrated across the input space);
+  - **deep-input loudness**: serde_json's recursion limit surfaces as
+    typed `Codec`, never a stack overflow;
+  - **Value round-trip**: `encode_payload(v)` → `payload_as::<Value>`
+    yields `v` for every arbitrary `Value` (canonicalization is
+    serde_json's, pinned-not-regressed);
+  - **typed round-trip**: for a representative typed-payload set,
+    `encode(Value::from(t))` decodes back to `t` (the ADR-020 §4
+    decode side).
+- **Seeds** (§3.1's list, via `gen_fuzz_seeds.py` gaining the
+  `payload_codec` function): valid JSON of every Value variant,
+  truncations, deep nesting at and past the recursion limit, non-UTF-8
+  bytes, trailing garbage, oversized numbers, duplicate keys, the
+  `Null`-decode shape (ADR-023 §1's empty-byte-store corruption note).
+  Corpus committed under `fuzz/corpus/payload_codec/`; the
+  `fuzz/.gitignore` gains the `!corpus/payload_codec` negation.
+- **`fuzz/README.md`** targets-table row.
+- `shared`'s manifest gains `alkstore` (path) if the scaffold didn't
+  already carry it, plus `serde_json` + `arbitrary`.
+
+Campaign flags are the campaign task's concern (`-max_len=65536
+-dict=json.dict` starting point, §7); this task lands target + seeds +
+replay.
+
+## Acceptance Criteria
+
+- [ ] `fuzz_targets/payload_codec.rs` + `shared/src/payload_codec.rs`
+      exist; `cargo fuzz build` builds the target (nightly, ASAN)
+- [ ] All five §3.1 invariants implemented in `shared` and exercised by
+      both the fuzz path and the `#[cfg(test)]` replay module
+- [ ] Seed corpus committed (`fuzz/corpus/payload_codec/`), 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
+      (replays the committed corpus through the invariants)
+- [ ] `shared` clippy/fmt gates green
+      (`cargo clippy --manifest-path fuzz/shared/Cargo.toml
+      --all-targets -- -D warnings`, `fmt --check`)
+- [ ] Root workspace gates still green
+
+## References
+
+- docs/research/fuzzing.md §3.1 (target spec), §4 (wave-1 scope), §7
+  (flags)
+- docs/architecture/decisions/020-payload-encoding.md §4 (the encoding
+  posture the round-trips pin)
+- docs/architecture/decisions/023-fourth-review-round.md §1 (encode
+  fallibility)
+- /workspace/@alkdev/alksocks/fuzz/shared/src/datagram_codec.rs (the
+  invariant-module + replay-test pattern)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion