106 lines
4.9 KiB
Markdown
106 lines
4.9 KiB
Markdown
---
|
|
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 |