Document and check fuzz corpus policy

Author: eldryoth

CHANGELOG.md

@@ -27,6 +27,8 @@
 - Added `scripts/check_miri.sh` and routed CI/release Miri checks through it so
   both no-default scalar and all-features alloc/stream surfaces run under Miri
   when nightly Miri is installed.
+- Added `docs/FUZZING.md` and `scripts/check_fuzz_corpus.sh` to document and
+  enforce reviewed fuzz corpus handling.
 
 ## 0.5.0 - 2026-05-14
 

README.md

@@ -484,6 +484,7 @@ For dependency admission rules, see [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)
 For adoption guidance from the established `base64` crate, see
 [docs/MIGRATION.md](docs/MIGRATION.md).
 For performance evidence guidance, see [docs/BENCHMARKS.md](docs/BENCHMARKS.md).
+For fuzz target and corpus policy, see [docs/FUZZING.md](docs/FUZZING.md).
 
 ## Local Checks
 
@@ -548,6 +549,12 @@ Compile fuzz targets without running a campaign:
 scripts/check_fuzz.sh
 ```
 
+Validate the committed fuzz corpus policy directly:
+
+```sh
+scripts/check_fuzz_corpus.sh
+```
+
 Compile and audit the isolated performance harness:
 
 ```sh

docs/FUZZING.md

@@ -0,0 +1,70 @@
+# Fuzzing Policy
+
+`base64-ng` keeps fuzzing isolated from the published crate. The root crate
+remains dependency-free; fuzz-only dependencies live under `fuzz/` and are
+checked separately.
+
+Run fuzz harness checks with:
+
+```sh
+scripts/check_fuzz.sh
+```
+
+Run corpus policy checks directly with:
+
+```sh
+scripts/check_fuzz_corpus.sh
+```
+
+## Targets
+
+Current fuzz targets:
+
+- `decode`: arbitrary strict, legacy, and constant-time-oriented decode input
+- `in_place`: in-place encode/decode and legacy compaction behavior
+- `stream_chunks`: fragmented stream reader/writer state machines and adjacent
+  framed payload boundaries
+- `differential`: canonical output comparison against the established Base64
+  behavior used by the harness
+
+## Corpus Admission
+
+Committed corpus inputs are allowed only under:
+
+- `fuzz/corpus/decode/`
+- `fuzz/corpus/in_place/`
+- `fuzz/corpus/stream_chunks/`
+- `fuzz/corpus/differential/`
+
+Each committed corpus input must be:
+
+- small enough to review manually, with a hard local limit of 64 KiB
+- relevant to a previously fixed bug, a protocol boundary, or an edge case not
+  already represented by deterministic tests
+- non-sensitive and safe to publish
+- named or documented well enough that reviewers can understand why it exists
+
+Generated crashes, hangs, and local artifacts must stay out of commits. The
+release gate rejects files under `fuzz/artifacts/` other than `.gitignore`.
+
+## Running Local Campaigns
+
+Install nightly and cargo-fuzz:
+
+```sh
+rustup toolchain install nightly
+cargo install --locked cargo-fuzz
+```
+
+Run bounded smoke campaigns before release-sensitive stream or decode changes:
+
+```sh
+cargo +nightly fuzz run decode -- -runs=1000
+cargo +nightly fuzz run in_place -- -runs=1000
+cargo +nightly fuzz run stream_chunks -- -runs=1000
+cargo +nightly fuzz run differential -- -runs=1000
+```
+
+Longer campaigns are useful before release candidates, but generated corpus
+changes should be reviewed deliberately. Keep only the inputs that improve
+coverage or preserve a regression.

docs/PLAN.md

@@ -324,14 +324,14 @@ the zero-runtime-dependency stance.
   documentation.
 - Strengthened Miri coverage with a shared check script for no-default scalar
   APIs and all-features alloc/stream APIs when nightly Miri is installed.
+- Stabilized fuzz corpus handling with documented admission rules and a local
+  corpus policy check.
 - Expand Kani proof coverage for length helpers, in-place decode bounds, and
   selected scalar decoder invariants when Kani supports the pinned Rust
   toolchain.
 - Add a documented constant-time verification plan for the `ct` module,
   including generated-code review requirements before making cryptographic
   constant-time claims.
-- Stabilize fuzz corpus handling and document which corpus inputs are accepted
-  into the repository.
 
 ### v0.7
 

docs/RELEASE.md

@@ -133,15 +133,19 @@ Fuzz-only dependencies are checked separately with:
 scripts/check_fuzz.sh
 ```
 
-The `fuzz/` package is not part of the published crate.
+The `fuzz/` package is not part of the published crate. Corpus admission rules
+are documented in `docs/FUZZING.md` and checked by
+`scripts/check_fuzz_corpus.sh`.
 
 Run the streaming fuzz smoke when changing stream state machines:
 
 ```sh
 cargo +nightly fuzz run stream_chunks -- -runs=1000
 ```
 
-Review generated local corpus files before committing.
+Review generated local corpus files before committing. Commit only small,
+non-sensitive inputs that preserve a regression, protocol boundary, or edge
+case not already represented by deterministic tests.
 
 Reserved SIMD feature bundles are checked with:
 

docs/RELEASE_EVIDENCE.md

@@ -53,6 +53,8 @@ The release gate runs:
 - Miri through `scripts/check_miri.sh` when nightly Miri is installed,
   covering no-default-features scalar APIs and all-features alloc/stream APIs
 - fuzz target compile check when `cargo-fuzz` is installed
+- fuzz corpus policy validation for target-specific reviewed corpus inputs and
+  release-blocking artifact cleanup
 - isolated fuzz and performance harness dependency checks
 - installed-target `no_std` checks for the reserved `simd` feature
 - reserved SIMD feature-bundle compile checks for AVX2, AVX-512 VBMI, and

scripts/check_fuzz.sh

@@ -9,6 +9,9 @@ fi
 echo "fuzz checks: compile harnesses"
 cargo check --manifest-path fuzz/Cargo.toml --bins
 
+echo "fuzz checks: corpus policy"
+scripts/check_fuzz_corpus.sh
+
 echo "fuzz checks: RustSec advisories"
 cargo audit --file fuzz/Cargo.lock
 

scripts/check_fuzz_corpus.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ ! -d fuzz ]; then
+    echo "fuzz corpus: skipping; fuzz/ is not present"
+    exit 0
+fi
+
+test -s docs/FUZZING.md
+
+for target in decode in_place stream_chunks differential; do
+    mkdir -p "fuzz/corpus/$target"
+done
+
+find fuzz/artifacts -type f ! -name .gitignore -print | while IFS= read -r artifact; do
+    echo "fuzz corpus: artifact must not be committed or left for release gates: $artifact" >&2
+    exit 1
+done
+
+find fuzz/corpus -type f ! -name .gitkeep -print | while IFS= read -r corpus_file; do
+    case "$corpus_file" in
+        fuzz/corpus/decode/* | fuzz/corpus/in_place/* | fuzz/corpus/stream_chunks/* | fuzz/corpus/differential/*)
+            ;;
+        *)
+            echo "fuzz corpus: unknown corpus target for $corpus_file" >&2
+            exit 1
+            ;;
+    esac
+
+    size="$(wc -c <"$corpus_file" | tr -d '[:space:]')"
+    if [ "$size" -gt 65536 ]; then
+        echo "fuzz corpus: $corpus_file is larger than 65536 bytes" >&2
+        exit 1
+    fi
+done
+
+echo "fuzz corpus: ok"

scripts/validate-release-metadata.sh

@@ -60,6 +60,7 @@ test -s docs/ASYNC.md
 test -s docs/BENCHMARKS.md
 test -s docs/CONSTANT_TIME.md
 test -s docs/DEPENDENCIES.md
+test -s docs/FUZZING.md
 test -s docs/MIGRATION.md
 test -s docs/PANIC_POLICY.md
 test -s docs/PLAN.md
@@ -73,6 +74,7 @@ test -s docs/UNSAFE.md
 for required_script in \
     "scripts/check_backend_evidence.sh" \
     "scripts/check_fuzz.sh" \
+    "scripts/check_fuzz_corpus.sh" \
     "scripts/check_kani.sh" \
     "scripts/check_miri.sh" \
     "scripts/check_perf.sh" \
@@ -132,6 +134,7 @@ for required_package_file in \
     "docs/BENCHMARKS.md" \
     "docs/CONSTANT_TIME.md" \
     "docs/DEPENDENCIES.md" \
+    "docs/FUZZING.md" \
     "docs/MIGRATION.md" \
     "docs/PANIC_POLICY.md" \
     "docs/PLAN.md" \
@@ -143,6 +146,7 @@ for required_package_file in \
     "docs/UNSAFE.md" \
     "scripts/check_backend_evidence.sh" \
     "scripts/check_fuzz.sh" \
+    "scripts/check_fuzz_corpus.sh" \
     "scripts/check_kani.sh" \
     "scripts/check_miri.sh" \
     "scripts/check_perf.sh" \