leaffuzz-ADR-001: Cross-Platform In-JVM Quality Control, Command-Tree Fuzzing, Post-GC Leak Screening, and Bytecode Causal Auditing¶
- Status: Accepted
- Date: 2026-10-30
- Related ADRs:
ADR-049,ADR-115,ADR-125,ADR-126,corpus-atlas-ADR-001,corpus-atlas-ADR-002,leafsleuth-ADR-006
Context¶
Plugin and mod authors on Modrinth and BuiltByBit routinely test new releases by starting a local server, running a command once or twice, and checking the console for stack traces. In production, defects surface under boundary arguments (-1, 0, Integer.MAX_VALUE), rapid disconnect races (quit_lt1s), unguarded default-tier subcommands, main-thread tick stalls (> 100 ms), synchronous main-thread chunk loads (hazard:sync-chunk:), per-departure object retention leaks that only appear across post-GC heap histograms, and unwired/hollow commands or dead YAML config keys (<DeclaredSurface> -> <CausalDefect>).
While ADR-125 and leafsleuth-ADR-006 introduced in-JVM command-surface auditing, UCB1 boundary fuzzing, ddmin shrinking, and ClassRetentionScreener inside LeafSleuth, bundling a QA fuzzer inside a production lag governor obscured both products and limited the fuzzer to Paper/Folia.
Decision¶
- Standalone Multi-Loader Community Resource (
resource/LeafFuzz): - Package
LeafFuzzas a standalone, MIT-licensed multi-loader JAR (LeafFuzz-<version>.jar) built from::resource:LeafFuzz:leaffuzz-common(pure Java 17 core consuming:server-api,:commands-api,:yaml-api,:bit-api,:config-bit-api, and:helpers:stresstest-core):resource:LeafFuzz:leaffuzz-paper(PaperLeafFuzzPluginviaBukkitPluginServerAccessor,PaperCommandTreeInspector, andLeafFuzzPaperEpisodeRunner):resource:LeafFuzz:leaffuzz-fabric(FabricLeafFuzzModviaFabricModServerAccessor,BrigadierDispatcherInspector, andNmsEmbeddedPlayerSession):resource:LeafFuzz:leaffuzz-neoforge(NeoForgeLeafFuzzModviaNeoForgeModServerAccessor,BrigadierDispatcherInspector, andNmsEmbeddedPlayerSession):resource:LeafFuzz:leaffuzz-plugin(shaded multi-loader assembly JAR withMain-Class: net.leaf.fuzz.common.cli.LeafFuzzStandaloneCli)
- Multi-Format Archive Ownership Indexing & Zero-Classloading Causal Graph Scanning (
JarClassOwnershipIndex,BytecodeCausalGraphScanner): JarClassOwnershipIndex#scanArchiveDirectoriesindexes bothplugins/*.jar(paper-plugin.yml,plugin.yml) andmods/*.jar(fabric.mod.json,META-INF/neoforge.mods.toml,META-INF/mods.toml, and nestedMETA-INF/jars/*/META-INF/jarjar/*archives) off-thread, filtering out multi-JAR shaded class collisions.BytecodeCausalGraphScanner(:bytecode-api) parses.classconstant pools, method bodies, andBootstrapMethodswithout loading classes to extract white-box command schemas (BytecodeCommandSchemaseeding Stage 1 & Stage 2) and evaluate Order-1 (0-hop command/event/config wiring, distinguishingREGISTERED_UNCONDITIONAL,REGISTERED_CONFIG_GATED, andUNREGISTERED) and Order-2 ($k$-hop causal chains to terminal effect sinks, $k \le 4$) causal audit invariants (CausalFinding).LlmCausalChainAuditor(:bytecode-api) optionally enriches proven Stage 2/3/5 findings withJminorAST-grounded explanations (explainProvenFuzzFault) and advisory semantic causal checks, verifying every citedClass#methodagainstCausalGraphReport#closedWorldSymbols().- In-JVM Synthetic Persona Bot, Spiral Swarm Roster & One-Command 5-Stage QC Scorecard (
/fuzz check target=<target>): PersonaPolicyBotActor,LeafFuzzPaperEpisodeRunner, andNmsEmbeddedPlayerSessionevaluate the 256-byteInt8[16x16]sleuth_persona_v1policy genome (selectPolicyActionIntover 16POLICY_MICRO_SKILLS), spawn live server-sideServerPlayer+ NettyEmbeddedChannelsessions dispersed across golden-angle Archimedean spiral coordinates (players=1..500orplayers=autoramp-to-instability), click salient GUI menu slots (auditinghazard:gui-item-leak), and drive lifecycle/spatial follow-ups (quit_lt1s,quit_delay,move,chunk_border_thrash,window_click,repeat,concurrent)./fuzz check [target=<target>] [episodes=<n>] [players=<auto|1..500>] [stage=<all|commands|fuzz|faults|leaks|causal|snapshot>]runs Command & Least-Privilege Auditing (Stage 1), Persona Bot UCB1 Boundary, GUI Menu & Swarm Fuzzing withddmin+ binary numeric bisection (Stage 2), Main-Thread Stall, Sync-Hazard & Exception Attribution (Stage 3), Post-GC Bonferroni OLS Class Retention Screening (Stage 4), and First/Second-Order Bytecode & Causal Auditing (Stage 5), outputting an in-game Book scorecard (/fuzz report) and status-leading reports in<rootFolder>/reports/<target>-qc-report.md,<target>-qc-data.yml, and<target>-qc-data.json.LeafFuzzStandaloneCliandLeafFuzzTcpSwarmClientallow the sameLeafFuzz.jarto run from a terminal (java -jar LeafFuzz.jar swarm/extract-mineflayer) as a zero-dependency external TCP swarm and capacity tester.
Consequences¶
- Positive: Any Paper, Spigot, Folia, Fabric, or NeoForge developer or server administrator can drop
LeafFuzz.jarinto their test server and run/fuzz check target=<PluginOrMod>with zero external Python/Docker/RCON dependencies, or runjava -jar LeafFuzz.jar swarmfrom a terminal. - Safety (
S-002,S-004,S-005,S-007): All archiveZipFilescans, bytecode causal graph scans, andGC.class_histograminvocations execute off the main tick thread viaServerAccessor#scheduler();NmsEmbeddedPlayerSessionreleases all NettyReferenceCountedbuffers and removesServerPlayersessions on disconnect; destructive server commands (CommandSurfaceAuditor.DEFAULT_DENYLIST) are blocked from fuzz execution; all user-facing command failure strings are configurable inmessages.yml.