---
id: fuzz-scaffold
name: Fuzz sidecar scaffold — `fuzz/` workspace, runner, dict, seed generator, shared-crate skeleton
status: pending
depends_on: []
scope: moderate
risk: low
impact: phase
level: implementation
tags: [wave-7, fuzzing]
---

## Description

The wave-7 scaffold ([docs/research/fuzzing.md](../research/fuzzing.md)
§2 — the layout is inherited wholesale from the four upstream siblings,
not re-decided): the `fuzz/` sidecar workspace and its stable-toolchain
gate crate, copied from alksocks' working edition with only naming
substitutions.

- **`fuzz/` sidecar workspace**: `fuzz/Cargo.toml` (`alkstore-fuzz`,
  `publish = false`, own `[workspace]` table, `libfuzzer-sys` +
  `alkstore-fuzz-shared` path dep; `[[bin]]` entries land with the
  target tasks, not here), `fuzz/rust-toolchain.toml` pinning
  `channel = "nightly"` + `llvm-tools-preview` **inside `fuzz/` only**
  — the crates themselves stay on stable, and the root workspace's
  toolchain behavior must be unaffected.
- **`fuzz/shared/`** — `alkstore-fuzz-shared`, the STABLE-toolchain
  library whose `#[cfg(test)]` corpus-replay modules are the fuzz gate
  (§6): skeleton `lib.rs` with the crate doc carrying the quinn-CI
  pattern rationale, plus the `arbitrary_value.rs` `JsonValue`
  bounded-depth helper copied from alksocks (the structured-generation
  path §3.1's targets share). Dependencies: `alkstore` (path), plus
  `serde_json` + `arbitrary` (derive feature). Engine-crate deps land
  with the targets that need them. `shared` consumes public API only —
  it must never become a dependency of any workspace crate (the wasm
  note, §2).
- **`fuzz/run-detached.sh`** — copied verbatim from alksocks
  (CWD-independent, `setsid` + `nohup` + full redirection, `pid=` echo,
  `FUZZ_RUNTIME_SECS` override). The §5 isolation rule is inherited
  unchanged: campaigns never run as a foreground child of an agent
  session.
- **`fuzz/json.dict`** — copied from a sibling (alksocks has it at
  `fuzz/json.dict`).
- **`fuzz/gen_fuzz_seeds.py`** — the deterministic seed generator
  (quiche pattern): alksocks' script as the structural template,
  alkstore's own seed functions land per-target. Skeleton lands here
  with the shared `seed_name`/`write_seed` plumbing and an empty
  target registry.
- **`fuzz/.gitignore`** — the alksocks pattern: `target`, `artifacts`,
  `coverage`, and `corpus/*` with `!`-negations for the committed seed
  dirs (each target task adds its negation line when its corpus lands).
- **`fuzz/README.md`** — skeleton modeled on alksocks' (layout, targets
  table filled by the target tasks, commands incl. the
  run-from-`fuzz/`-so-rustup-selects-nightly rule).
- **Root `Cargo.toml`**: add `exclude = ["fuzz"]` to the `[workspace]`
  table — defensive insurance against auto-discovery (the alkcall §2
  lesson; this repo's explicit-members list already prevents it, the
  exclude makes it structural). The publish-exclusion *verification*
  stays wave 8's (§2); this task lands the mechanism.
- **Corpus dirs**: `fuzz/corpus/<target>/` scaffolding lands per-target
  with the seeds; nothing to commit here.

Toolchain prerequisites verified present in the dev environment
(2026-10-10): nightly + `cargo-fuzz` 0.13.2 installed; alksocks'
`fuzz/Cargo.lock` exists as the copy reference.

## Acceptance Criteria

- [ ] `fuzz/` exists with the §2 layout: sidecar `Cargo.toml` (own
      `[workspace]`, `publish = false`), `rust-toolchain.toml`
      (nightly + llvm-tools-preview), `shared/` crate, `run-detached.sh`
      (executable), `json.dict`, `gen_fuzz_seeds.py`, `README.md`,
      `fuzz/.gitignore`
- [ ] `fuzz/shared` compiles and tests green on **stable** via
      `cargo test --manifest-path fuzz/shared/Cargo.toml` (the gate
      command works from the wave's first task onward)
- [ ] `cargo fuzz build` succeeds from `fuzz/` (nightly selected by the
      pin; zero targets yet is acceptable if cargo-fuzz tolerates it —
      otherwise a placeholder target documents the check; record which)
- [ ] Root workspace unaffected: `cargo build` / `cargo test` /
      `clippy -D warnings` / `fmt --check` green from the root, and the
      root toolchain is still stable (the pin did not leak upward)
- [ ] `exclude = ["fuzz"]` present on the root `[workspace]` table
- [ ] `run-detached.sh` is byte-identical to alksocks' modulo the
      usage-line naming (no behavior drift)
- [ ] `shared` is not referenced by any workspace crate manifest
      (wasm posture intact: `cargo check --target
      wasm32-unknown-unknown -p alkstore-mem` still clean)

## References

- docs/research/fuzzing.md §2 (layout + toolchain), §5 (runner), §6
  (no-CI / replay gate)
- /workspace/@alkdev/alksocks/fuzz/ (the copy source: Cargo.toml,
  rust-toolchain.toml, run-detached.sh, json.dict, gen_fuzz_seeds.py,
  .gitignore, README.md)
- docs/plans/implementation.md §Wave 7

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion