wave 7: fuzz sidecar scaffold (fuzz/ workspace, shared crate, runner, dict, seeds skeleton)

fuzz/README.md

@@ -0,0 +1,57 @@
+# alkstore fuzzing
+
+libFuzzer targets for alkstore's parse/codec surfaces (see
+`docs/research/fuzzing.md` for the full rationale and campaign plan).
+
+## Layout
+
+- `fuzz_targets/` — one binary per target; thin `fuzz_target!` wrappers
+  (land with the wave-7 target tasks).
+- `shared/` — the invariant logic, as a plain library so normal
+  `cargo test` (stable toolchain) can replay the committed corpora
+  through the same invariants (`fuzz/shared/src/*.rs` `#[cfg(test)]`
+  modules; quinn's CI pattern). The fuzz binaries are nightly-only;
+  the shared crate is stable-clean. It consumes alkstore's public API
+  only and must never become a dependency of any workspace crate.
+- `corpus/<target>/` — committed hand-made seeds (regenerate with
+  `python3 fuzz/gen_fuzz_seeds.py` from the repo root). Grown corpora
+  and artifacts are gitignored; each target task adds its `!`-negation
+  line when its corpus lands.
+- `run-detached.sh` — mandatory runner for agent sessions: wraps
+  `cargo fuzz run` in `setsid` + `nohup` + log redirection so an OOM
+  in a target can never take down the agent host (research doc §5).
+- `json.dict` — JSON token dictionary for the structured targets.
+- `gen_fuzz_seeds.py` — deterministic seed generator (quiche pattern).
+
+## Targets
+
+| Target | Drives | Invariants |
+|---|---|---|
+| `payload_codec` | `encode_payload` / `payload_as::<T>` (`alkstore/src/payload.rs`) | filled by its target task |
+| `every_parse` | the three `parse_every_interval` implementations (differential) | filled by its target task |
+| `name_validation` | `validate_name` / `validate_shared_name` / `validate_local_name` (`alkstore/src/validation.rs`) | filled by its target task |
+
+## Commands
+
+`cargo fuzz build` and `cargo fuzz run` must be executed with `fuzz/`
+(or deeper) as the working directory so rustup selects the pinned
+nightly toolchain — the detached runner handles that itself.
+
+```sh
+# build (nightly, pinned by rust-toolchain.toml inside fuzz/; run from fuzz/)
+cargo fuzz build
+
+# agent sessions: detached campaign (never foreground; CWD-independent)
+FUZZ_RUNTIME_SECS=600 fuzz/run-detached.sh <target> [extra libfuzzer args...]
+
+# corpus replay through the invariants (stable toolchain, no nightly)
+cargo test --manifest-path fuzz/shared/Cargo.toml
+
+# coverage
+cargo fuzz coverage <target>
+```
+
+The fuzz workspace is excluded from the main workspace (`exclude` in
+the root `Cargo.toml`); it pins its own nightly toolchain via
+`rust-toolchain.toml` and does not affect the root workspace's stable
+toolchain or MSRV.