frf-fuzz

de Beer, R. (2026). FRF-Fuzz: Endoductive Residual-Guided Fuzzing Across Input, State, Environment, and Software-Evolution Space — Broad Prior-Art Technical Disclosure and Research Architecture (Version v1.0). Zenodo. https://doi.org/10.5281/zenodo.22096094

Heterogeneous residual-guided fuzzing engine and deterministic endoductive software-experimentation system. One crate, two planes.

Coverage tells us where execution went.
Residual structure tells us how behavior is changing.
Historical residual trajectories tell us where to interrogate next.
FRF determines whether promoted discoveries are evidence.
Gemel remembers what those discoveries meant across software evolution.

Status: Phases 0-8 complete (v0.8.1) — a usable, deterministic fuzzer and endoductive experimentation system: coverage + compare guidance, target-defined semantic signals, mutation residuals, regime episodes (Stable → Drift → InEpisode → Recovering with deterministic close), inspectable morphology signatures with a Structured-Unknown discipline, DSFB endoduction (structural verdicts/episodes, the FuzzSemanticBank, a durable precedent bank with falsifiable probes, DISCRIMINATE/FALSIFY scheduling), AVX2-hardened hot paths (scalar == AVX2, bit-for-bit), an optional real dsfb-database bridge for database telemetry targets, a batch GPU ComputeBackend contract whose only semantics is the CPU oracle (no device adapter is admitted until the parity gates pass on real hardware), FRF court verification at promotion (real receipts; explicitly unverified without an authority), Gemel longitudinal memory (durable boundaries only, never per-execution writes), and the Phase-8 scientific-evaluation instrument (frf-fuzz experiment: repeated independent trials over the cov/cov+cmp/residual/full ablation arms, raw-series export, median/A12/Mann-Whitney, held-out partitions, negative controls). Persistent instrumented workers, a content-addressed corpus, crash recovery without per-execution IPC, and the init/add/build/run/experiment/replay/tmin/cmin/boundary/precedent/verify/ revision/inspect/report/fsck/doctor surface. See docs/ROADMAP.md for the per-phase record and docs/EXPERIMENT_PROTOCOL.md for the evaluation methodology.

The idea in one paragraph

Ordinary fuzzers remember inputs that reach new code. frf-fuzz also watches how behavior changes — coverage, compare operands, target-defined signals, mutation residuals, structural drift/slew/regimes — and when a behavioral trajectory starts to look like a historically evidence-backed precursor, it proposes a falsifiable next experiment instead of guessing. FRF (the Forensic Residual Framework) independently verifies promoted discoveries; Gemel remembers what they meant across software evolution. It never converts any of this into probabilistic bug prediction.

Using it

cargo install frf-fuzz

cd my-project
# add the dependency (the fuzz target links only the tiny target-runtime):
#   [dependencies]
#   frf-fuzz = { version = "0.8", default-features = false, features = ["target-runtime"] }

cargo frf-fuzz init
cargo frf-fuzz add parser      # creates src/bin/frf_fuzz_parser.rs
cargo frf-fuzz build parser    # pinned-nightly instrumented build
cargo frf-fuzz run parser      # spawns N persistent workers and fuzzes

# residual-guided / endoductive tools:
cargo frf-fuzz run parser --cmp off           # true coverage-only ablation
cargo frf-fuzz run parser --residual off      # no residual machinery
cargo frf-fuzz run parser --precedent on --discriminate-weight <w> --falsify-weight <w>
cargo frf-fuzz boundary <finding-id>          # two-sided minimization
cargo frf-fuzz precedent list                 # renders the precedent bank
cargo frf-fuzz precedent show <id>            # detail for one precedent

# scientific evaluation (Phase 8): repeated independent trials over the
# code-level ablation arms (each trial is a fresh store; the budget is
# mandatory — trials that find nothing are censored, never dropped):
cargo frf-fuzz experiment parser --arms cov,cov+cmp,residual,full \
    --trials 2 --max-time 10                  # exports raw-series CSV + analysis

# FRF verification + Gemel longitudinal memory (Phase 4):
# run a campaign that court-verifies every replay-confirmed crash finding
# against a reference executable and publishes durable Gemel boundaries
# (a .gemel repository must exist for the Gemel side):
cargo frf-fuzz run parser --authority ./reference-cli \
    --authority-name my-ref --authority-version 1.0 \
    --verify-candidate target/debug/frf_fuzz_parser
cargo frf-fuzz verify <finding-id> --authority ./reference-cli --candidate <harness>
cargo frf-fuzz revision replay <finding-id> \
    --state v1=<bin-from-v1> --state v2=<bin-from-v2>   # revision residual

A generated target is a normal binary in your existing crate:

use frf_fuzz::target_runtime::FuzzContext;

frf_fuzz::fuzz_target!(|data: &[u8], cx: &mut FuzzContext| {
    let _ = mycrate::parse(data);
});

Optional hooks (setup / reset / execute / teardown, any order) are supported; persistent fuzzing of stateful targets needs an explicit reset.

Post-campaign tooling: cargo frf-fuzz replay <finding-id>, tmin <finding-id>, cmin <target>, verify <finding-id>, revision replay <id>, inspect <id>, report [--json], fsck, doctor.

The FRF authority is an executable that honors the case-harness interface (--frf-fuzz-fixture <path> — the instrumented fuzz-target binary itself does); it models the REFERENCE behavior of the software under test. Without an authority, findings stay explicitly unverified. Gemel boundaries are published only when a .gemel repository is present.

One-command end-to-end demonstrations (each builds the instrumented target with the pinned nightly):

# build -> fuzz -> compare-guided magic-gate crash -> replay -> fsck -> tmin ->
# FRF-verified finding -> Gemel boundaries -> revision replay:
sh scripts/golden_demo.sh

# Phase 8: 4-arm repeated-trial ablation experiment on the golden target +
# raw-series CSV export + median/A12/Mann-Whitney analysis:
sh scripts/phase8_ablation_demo.sh

# Phase 8 baseline (informational single trials; AFL++ recorded as skipped
# when not installed):
sh scripts/baseline_compare.sh

Requirements

• Coordinator: stable Rust >= 1.98 (MSRV), a C compiler (gemel's bundled sqlite).
• Instrumented fuzz target: the pinned nightly (nightly-2026-07-24; rustup toolchain install nightly-2026-07-24) — LLVM SanitizerCoverage and sanitizer flags require nightly. The exact nightly identity is verified by frf-fuzz doctor and recorded in campaign metadata; a mismatched nightly is never silently used.
• x86_64 with AVX2 for the accelerated SIMD path (the scalar path is portable and normative).

Status by phase

Phase	Content	Status
0	Specification / forensic spikes	DONE
1	Minimum useful fuzzer (init/add/build/run, workers, corpus, crashes, replay, tmin, cmin, inspect, report, fsck)	DONE
2	Residual-guided fuzzing (signals, residuals, regimes, morphology, boundaries, tapes)	DONE
3	DSFB endoduction (FuzzSemanticBank, precedents, probes)	DONE
4	FRF courts (real receipts at promotion) + Gemel durable boundaries + revision tape replay	DONE
5	AVX2 hardening: measured per-window scan/clear + cmp snapshot wired through runtime-dispatched SIMD; per-execution event-window allocation removed (examples/phase5_bench); scalar == AVX2 property-tested	DONE
6	Database specialization: real dsfb-database bridge (database feature) with typed rows -> real SQL-semantics constructors -> real MotifEngine; type-level I7 refusal (source lock + compile_fail); regression demo cargo run --features database --example db_regression_demo	DONE
7	GPU: batch ComputeBackend contract + CPU oracle (gpu/), integer-only deterministic kernels, recorded fallback for unadmitted CUDA/ROCm (I8/I14/I15), CubeCL gate record; cargo run --example gpu_backend_demo	DONE
8	Scientific evaluation: frf-fuzz experiment repeated-trial ablation harness (cov / cov+cmp / residual / full arms, honest --cmp switch, censoring discipline), raw-series CSV export + median/A12/Mann-Whitney, held-out partition, negative controls, cargo-fuzz baseline + golden-demo ablation demos (scripts/phase8_ablation_demo.sh)	DONE

The two planes

• Exploration plane (fast, disposable): coverage + compare + residual guided mutation in persistent workers; the target-runtime feature.
• Evidence plane (deliberate, immutable): promotion, replay, FRF courts, Gemel boundaries; the coordinator feature.

Only promoted discoveries reach FRF, Gemel, or the full DSFB detector field. The hot loop stays fast; the memory stays trustworthy.

Non-claims (the short version)

frf-fuzz does not predict bugs. It recognizes deterministic structural prefixes and proposes falsifiable experiments. It never emits probabilities, never forces an unknown structure into a label, never reimplements FRF semantics, and never writes per-execution Gemel telemetry. See docs/NON_CLAIMS.md.