leafsleuth-ADR-005: Unified Causal Server Forensics Engines (Economy Conservation-of-Mass, Supply-Chain Laundering & Recon Rings, Resource Exhaustion & Crash Attribution, and Action-Entropy Macro / Sub-Tick Packet Probing)¶
- Status: Accepted
- Date: 2026-10-29
- Scope:
plugins/LeafSleuth(sleuth-common,sleuth-paper,sleuth-plugin) &plugins/LeafConfig(leafconfig-common) - Governing ADRs: ADR-115, ADR-129, leafsleuth-ADR-001, leafsleuth-ADR-002, leafsleuth-ADR-003, leafsleuth-ADR-004
- Requirements:
REQ-SLEUTH-ECON-001,REQ-SLEUTH-RES-001,REQ-SLEUTH-BIO-004,REQ-SLEUTH-BIO-005,REQ-SLEUTH-UI-001,S-002,S-004,S-005
Context¶
Minecraft survival and network servers face four high-impact operational blind spots that neither tick-duration flamegraphs (spark), block-history SQL loggers (CoreProtect), nor packet movement anticheats (Grim) can resolve without high false-positive rates:
- Zero-Day Item Duplication vs. Legitimate High-Yield Survival Logistics:
- Novel duplication exploits (chunk-unload/reload state splitting, portal entity cloning, or packet-desync bundle/shulker extraction) synthesize items without triggering known packet signatures.
- Naive net-worth velocity alerts falsely flag legitimate players who unpack 27-slot Shulker Boxes (
1,728items per box) into bulk storage sorters, experience a 99.9th-percentile lucky Fortune III mining streak, or collect verifiedEmpiricalFarmBlackBoxyields. - Multi-Account Item Laundering ("Drop-Muling") & Pre-Grief Reconnaissance Rings:
- Organized X-rayers, dupers, and griefers launder contraband through 2-to-4 intermediate "dead-drop" chests or send a clean "scout" account to map base coordinates 5-30 minutes before a disposable VPN alt logs in to detonate TNT.
- Naive container-overlap graph rules falsely convict public spawn charity chests, busy shopping-district diamond barrels, and co-resident faction teammates sharing base storage.
- Spiral Chunk-Gen Exhaustion, Nested NBT Serialization Bombs & OldGen Heap Ratchets (
S-002): - Crash and OOM culprits frequently degrade the server through asynchronous chunk-generation I/O saturation (spiral Elytra/boat flyers), deeply nested book/shulker NBT deserialization stalls, or leaked force-loaded chunk tickets (
S-002) rather than direct main-thread redstone events. - Naive chunk-rate or memory-delta checks falsely blame linear Nether-roof highway travelers traversing pre-generated cached chunks or whatever bystander happens to act during a YoungGen garbage-collection allocation wave.
- Stationary Renewal-Process Macros & Sub-Tick Packet-Flood Probers:
- Stationary auto-fishers, villager lectern reroll macros, and mob-grinder swing timers hold camera angles fixed (
Delta yaw = Delta pitch = 0) where mouse GCD profilers observe zero samples. - Meanwhile, exploit probers flood sub-tick window clicks (
> 40clicks/tick), lectern page flips, or custom payloads inside a single 50 ms tick window. Naive CPS thresholds falsely flag legitimate shift-click bulk villager traders and rhythmic human combat.
Decision¶
We extend LeafSleuth with four orthogonal, mathematically rigorous forensic engines in sleuth-common and wire them into sleuth-paper, ModeratorInvestigationCase, SleuthMenuBuilder, ConfigRemediationBridge, and LeafConfigRuntime behind four independent config.yml toggles (forensics.economyDupeAuditEnabled, forensics.supplyChainRingEnabled, forensics.resourceExhaustionEnabled, forensics.macroAndProbeEnabled):
1. Conservation-of-Mass & Zero-Day Duplication Forensics (ItemProvenanceLedger, ConservationOfMassAuditor)¶
For every high-value item signature (materialKey, nbtHash) and spatial/player scope, ItemProvenanceLedger maintains the conservation-of-mass balance across tick epochs:
$$\Delta M_t = M_{\text{out}}(t) - \bigl(M_{\text{in}}(t) + M_{\text{verifiedGenerative}}(t) + M_{\text{containerUnpackDelta}}(t)\bigr)$$
- Stochastic Generative Variance Allowance: Fortune mining (
L in [0, 3]) credits expected yield $\mu_L \in {1.0, 1.333, 1.75, 2.20}$ plus the physical upper-tail envelope $(L + 1) - \mu_L$ and variance $\sigma_L^2$. VerifiedEmpiricalFarmBlackBoxyields (PROVABLE_GENERATIVE,taintedItemDebt == 0) and recipe conversions are credited automatically. - Zero-Sum Shulker/Bundle Unpacking: Unpacking a Shulker Box or Bundle credits $+M_{\text{containerUnpackDelta}}(t)$ equal to the released internal stacks (
<= 1,728items/box), keeping $\Delta M_t = 0$. - Boundary State-Split Auditing & One-Sided
CI95+Wald's SPRT:recordBoundarySnapshotandreconcileBoundaryArrivalaudit item mass across chunk unload/reload, portal traversal, and container-desync boundaries.ConservationOfMassAuditorconfirmsDUPE_ANOMALY_CONFIRMEDonly when the 95% lower confidence bound $L_{95}(\Delta M) = \Delta M - 1.96 \cdot \text{SE}(\Delta M) > \tau_{\text{mass}}$ and the sequential log-likelihood ratio $\Lambda_T \ge 4.60\text{ nats}$ ($\alpha = 0.001$).
2. Directed Custody-Flow & Pre-Grief Reconnaissance Ring Forensics (SupplyChainRingForensics, MulingChainReport)¶
SupplyChainRingForensics models container item transfers as a time-decayed directed multigraph $G = (V, E)$ and pairs it with 64-hash MinHash spatial-temporal trajectory sketches:
$$W_{\text{eff}}(A \to B \mid c) = \text{Flow}(A \to B \mid c) \cdot \exp(-\lambda_{\text{decay}} \Delta t) \cdot \exp(-\gamma H_{\text{visitors}}(c)) \cdot (1 - \text{Reciprocity}(A, B))$$
- Public Hub & Reciprocity Exoneration: High-entropy community/spawn chests ($H_{\text{visitors}}(c) = -\sum_i p_i \ln p_i \ge 1.35\text{ nats}$) and bilateral shop trades ($\text{Reciprocity}(A, B) \ge 0.45$) are exponentially discounted to near-zero effective laundering weight.
- Multi-Hop Path Composition & Pre-Grief Lead-Lag Correlation: Reconstructs 1-to-4 hop dead-drop paths (
Source -> Mule_1 -> ... -> Beneficiary) and evaluates lag-shifted trajectory Jaccard similarity $\max_{\Delta t \in [1\text{m}, 60\text{m}]} J_{\text{MinHash}}(\text{Path}_A(t), \text{Path}_B(t + \Delta t))$ across non-public chunks to surfacePRE_GRIEF_RECONNAISSANCE_PAIRandMULTI_HOP_LAYERED_LAUNDERING_RING.
3. Resource Exhaustion & Crash Forensics (ResourceExhaustionForensics, ResourceCulpritReport)¶
ResourceExhaustionForensics attributes three non-redstone server degradation vectors via EwmaLinearFit marginal regression:
- Spiral New-Chunk Generation Churn (
SPIRAL_CHUNK_GEN_CHURN): Separates newly generated chunks ($N_{\text{newGen}}$) from pre-generated cached chunk loads ($N_{\text{cachedLoad}}$) and computes trajectory turning-angle entropy $H_{\text{turn}}$ so linear Nether-roof highway travelers ($N_{\text{newGen}} = 0$, $H_{\text{turn}} \approx 0$) are never flagged. - Nested NBT Serialization Bombs (
NBT_SERIALIZATION_BOMB): Regresses payload byte volume, container/book nesting depth ($d_{\text{nbt}} \ge 6$), and deserialization duration against $\Delta\text{MSPT}$. - Post-GC OldGen Heap Ratchet &
S-002Ticket Attribution (MEMORY_RETENTION_LEAK): Subtracts minor-GC YoungGen sawtooth reclamation before fitting the post-GC OldGen baseline slope ($\text{MB/min}$) against active chunk tickets and entity retention.
4. Action-Entropy Macro Ergonomics & Sub-Tick Packet-Probe Forensics (InteractionAndProbeForensics, ActionEntropyReport, SubTickProbeReport)¶
InteractionAndProbeForensics operates across two complementary axes:
- Renewal-Process Action Entropy (
ActionEntropyReport): Computes normalized inter-action interval Shannon entropy $H(\Delta t)$, Allan variance slope $\alpha_{\text{Allan}}$ (separating $1/f$ human pink-noise drift $\alpha_{\text{Allan}} \ge -0.25$ from white-noiseRandom.nextGaussian()sleep jitter $\alpha_{\text{Allan}} \approx -1.0$), Fitts/Hick-Hyman decision latency ($T_{\text{Hick}} = a + b \log_2(n_{\text{enchants}} + 1)$), and camera micro-jitter acrossAUTO_FISHING_RENEWAL,LECTERN_TRADE_REROLL,MOB_GRINDER_ATTACK_SWING, andRAPID_TRADE_SHIFT_CLICK. - Sub-Tick Packet-Burst Regression (
SubTickProbeReport): Regresses per-player sub-tick packet burst counts (window clicks, lectern page flips, custom payload bytes, entity interacts) against tick excess $\Delta\text{MSPT}t$ viaEwmaLinearFit, flaggingCONFIRMED_SUBTICK_EXPLOIT_PROBERonly when both packet-burst thresholds and $L) > 0$ are satisfied.}(\Delta\text{MSPT
5. Unified Case Pipeline, /sleuth audit, and LeafConfig Integration¶
ModeratorInvestigationCase&SleuthMenuBuilder: ExtendsModeratorInvestigationCase.CaseTypewithECONOMY_MASS_CONSERVATION_DUPE,SUPPLY_CHAIN_LAUNDERING_OR_RECON_RING,PRE_GRIEF_RECONNAISSANCE_RING,RESOURCE_EXHAUSTION_OR_CRASH_CULPRIT, andMACRO_OR_SUBTICK_PACKET_PROBER, carrying calibratedCI95bounds plus explicitsupportingTellsandexoneratingTells.ConfigRemediationBridge&LeafConfigRuntime:ConfigRemediationBridge#toWebForensicCaseCardandLeafConfigRuntime.LeafSleuthForensicCaseEntryexport unified forensic cases and YAML remediation suggestions to theLeafConfigweb workspace.- Runtime Toggles &
/sleuth audit:LeafSleuthPaperPlugin,SleuthBehaviorListener, andSleuthTickSamplergate event collection per engine viaforensics.*inconfig.yml, andSleuthCommandRegistrarexposes/sleuth audit <economy|rings|resources|probes|all>.
Consequences¶
Positive¶
- Zero-False-Positive Calibration (
0.000%FPR): All four forensic engines achieve100.0%culprit/exploit recall with0.000%false-positive rate across Fortune III mining, 27-slot shulker unpacking, public spawn chests, shopping districts, Nether-roof highway travel, YoungGen GC allocation waves, shift-click villager trading, and rhythmic human combat. - Strict
S-005Compliance: All Paper/Folia event hooks inSleuthBehaviorListenerandSleuthTickSampleroperate on in-memory event payloads without calling synchronousWorld#getChunkAtorloadChunk. - Independent Operational Control: Server administrators can enable or disable each forensic engine independently in
plugins/LeafSleuth/config.yml(forensics.*).
Trade-Offs & Guardrails¶
- Advisory Triage vs. Automated Banning: Consistent with
leafsleuth-ADR-002, forensic detections populateModeratorInvestigationCasereports withCI95bounds and supporting vs. exonerating tells for human moderator review (/sleuth audit,/sleuth cases,/sleuth report) rather than issuing automated bans.