alkblobs/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, detached runner, dict, seed generator, shared-crate skeleton	completed		moderate	low	phase	implementation	wave-11 fuzzing

Description

The wave-11 scaffold: the fuzz/ sidecar workspace and its stable-toolchain gate crate, copied from alkstore (the most recent sibling; its fuzz/ is the family's current edition) with only naming substitutions. The layout is inherited wholesale from the family (alkcall/alktunnels/alksocks/alktty/alkstore all carry the same shape) — not re-decided.

• fuzz/ sidecar workspace: fuzz/Cargo.toml (alkblobs-fuzz, publish = false, own [workspace] table, libfuzzer-sys + alkblobs-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 crate itself stays on stable, and the root's toolchain behavior must be unaffected.
• fuzz/shared/ — alkblobs-fuzz-shared, the STABLE-toolchain library whose #[cfg(test)] corpus-replay modules are the fuzz gate (the quinn CI pattern): skeleton lib.rs with the crate doc carrying the pattern rationale, plus the arbitrary_value.rs JsonValue bounded-depth helper copied from alkstore's (itself alksocks' — the structured-generation path the ops-ingress target shares). Dependencies: alkblobs (path). The ops-ingress target task amends the dep with features = ["ops"] when its invariant module lands (features unify per build, so the gate build compiles alkcall transitively from then on — recorded there, not here). shared consumes public API only (plus the wave's #[doc(hidden)] exposure) — it must never become a dependency of the root crate.
• fuzz/run-detached.sh — copied byte-identical from alkstore (cmp-verified identical across alkcall/alksocks/alkstore at decomposition — the script is repo-agnostic already). This is the family's OOM-isolation rule: campaigns never run as a foreground child of an agent session — an OOM in a target must not take down the agent host (the setsid + nohup + full-redirection detach; FUZZ_RUNTIME_SECS override; the pid= echo for explicit-pid kills). Inherited verbatim, unchanged.
• fuzz/json.dict — copied verbatim (byte-identical across the siblings; the ops-ingress target's JSON tokens).
• fuzz/gen_fuzz_seeds.py — the deterministic seed generator (quiche pattern): alkstore's script as the structural template, alkblobs' 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 alkstore pattern: target, artifacts, coverage, and corpus/* with !-negations for the committed seed dirs (each target task adds its negation lines when its corpus lands; the final retightened form — dirs re-included, contents ignored, !corpus/<target>/seed-* — is the campaigns task's to verify).
• fuzz/README.md — skeleton modeled on alkstore's (layout, targets table filled by the target tasks, commands incl. the run-from-fuzz/-so-rustup-selects-nightly rule).
• Root Cargo.toml: the [workspace] table's exclude = [] gains "fuzz" — defensive insurance against auto-discovery (the alkcall lesson; this repo's explicit-members list already prevents it, the exclude makes it structural). The publish-exclusion verification stays wave 12's (release readiness owns publish prep); this task lands the mechanism.
• Corpus dirs: fuzz/corpus/<target>/ scaffolding lands per-target with the seeds; nothing to commit here.

Repo-layout substitution (the one beyond naming): alkstore's core crate sits in a workspace subdir; alkblobs is a root-level package (the alksocks shape) — the fuzz package's dep is alkblobs = { path = ".." } and shared's is alkblobs = { path = "../.." }.

Toolchain prerequisites verified present in the dev environment (2026-10-15): cargo-fuzz 0.13.2 and the nightly toolchain installed; alkstore's fuzz/Cargo.lock exists as the copy reference (generated fresh here — locks are not portable across dep sets).

Acceptance Criteria

• fuzz/ exists with the family layout: sidecar Cargo.toml (own [workspace], publish = false), rust-toolchain.toml (nightly + llvm-tools-preview), shared/ crate, run-detached.sh (executable, cmp-identical to alkstore's), 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; cargo-fuzz does NOT tolerate zero targets — a bins-only package with no [[bin]] fails manifest parse, which also blocks the shared gate's workspace discovery; a placeholder target fuzz_targets/placeholder.rs documents the check and is replaced by the target tasks — the alkstore scaffold's recorded lesson)
• 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 alkstore's (cmp clean)
• shared is not referenced by the root crate's manifest (only the root's exclude mentions fuzz at all)

References

• docs/plans/implementation.md §Wave 11 (the family pattern named: the fuzz/ sidecar workspace, nightly pinned inside fuzz/ only, the stable fuzz/shared corpus-replay gate, the detached runner)
• /workspace/@alkdev/alkstore/fuzz/ (the copy source: Cargo.toml, rust-toolchain.toml, run-detached.sh, json.dict, gen_fuzz_seeds.py, .gitignore, README.md, shared/)
• /workspace/@alkdev/alkstore/tasks/fuzz-scaffold.md (the family scaffold task this adapts — its Notes carry the zero-targets lesson and the layout substitutions)
• AGENTS.md (the verification block the gate line joins at the campaigns task)

Notes

• Layout substitutions beyond naming: alkstore's core crate sits in a workspace subdir; alkblobs is a root-level package (the alksocks shape), so the fuzz package has no alkblobs dep at scaffold time (the task text names only libfuzzer-sys + the shared path dep; the target tasks add alkblobs = { path = ".." } when their targets need it) and shared's dep is alkblobs = { path = "../.." }.
• Zero targets are NOT tolerated by cargo-fuzz / cargo here (the alkstore scaffold's recorded lesson, confirmed): a bins-only package with no [[bin]] entries fails manifest parse, which also breaks the shared gate's workspace discovery. Placeholder route taken: fuzz_targets/placeholder.rs (minimal fuzz_target! stub, doc comment says the wave-11 target tasks replace it) plus its [[bin]] entry in fuzz/Cargo.toml.
• fuzz/Cargo.toml carries no alkblobs dep yet — deliberate divergence from alkstore's manifest (which has it); alkstore's is post-target-landing. The target tasks add it, per the task text's dependency list.
• shared/Cargo.toml: alkblobs (path, default features), serde_json
  • arbitrary (derive) for the copied arbitrary_value.rs; no engine-crate deps (alkstore's shared lists its split engine crates — not applicable here, single package). The ops feature amendment of the shared dep is the ops-ingress target task's, as recorded in the description.
• arbitrary_value.rs copied verbatim from alkstore (itself alksocks') with no substitutions needed — its comments are already target-agnostic ("the semantic target", "the payload targets").
• run-detached.sh byte-identical to alkstore's (cmp clean), mode 755. json.dict copied verbatim (alkcall-envelope tokens; byte-identical across the siblings per the alkstore task's md5 verification).
• gen_fuzz_seeds.py is the plumbing-only skeleton (seed_name / write_seed, empty main() registry); runs clean as a no-op.
• fuzz/.gitignore is the alkstore pattern's pre-negation form (target, artifacts, coverage, corpus/*); each target task adds its !corpus/<target> negation lines when its corpus lands.
• fuzz/Cargo.lock committed (family pattern), generated fresh under the pinned nightly (67 packages; locks are not portable across dep sets).

Summary

Landed the wave-11 scaffold, copied from alkstore with the two repo-layout substitutions: fuzz/ sidecar workspace (alkblobs-fuzz, publish = false, own [workspace], libfuzzer-sys + path-dep shared crate, placeholder [[bin]]) with rust-toolchain.toml pinning nightly + llvm-tools-preview inside fuzz/ only; stable-toolchain fuzz/shared (alkblobs-fuzz-shared) with the quinn-CI-pattern crate doc and the arbitrary_value.rs JsonValue bounded-depth helper; run-detached.sh (byte-identical to alkstore's, executable); json.dict; gen_fuzz_seeds.py skeleton; .gitignore (no corpus negations yet — per-target tasks add them); README skeleton (targets table open, commands incl. the run-from-fuzz/-so-rustup-selects-nightly rule); exclude = ["fuzz"] on the root [workspace] table; and the placeholder fuzz target so the toolchain check and the shared gate work before the real targets land. Fresh fuzz/Cargo.lock committed.

Verified: cargo test --manifest-path fuzz/shared/Cargo.toml green on stable from the root; shared cargo clippy --all-targets -- -D warnings + cargo fmt --check green; cargo fuzz build green from fuzz/ (nightly pin selected, rustc 1.99.0 stable at the root — no upward leak; placeholder + shared + alkblobs compile under ASAN); root cargo fmt --check / cargo clippy --all-targets -- -D warnings / cargo clippy --all-features --all-targets -- -D warnings / cargo test / cargo test --all-features all green (pg suites skip cleanly without the harness); only the root manifest mentions fuzz (the exclude line); no manifest references alkblobs-fuzz-shared.