alkstore/tasks/fuzz-scaffold.md

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

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

Description

The wave-7 scaffold (docs/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