LeafSleuth: Continuous Investigation & Performance Governance¶

Continuous Investigation & Performance Governance for Paper & Folia (100% culprit & clock recall, -68.6% hotspot MSPT, 0.000% roommate false flags, 0 / 18 real-human false flags) (ADR-129, leafsleuth-ADR-001..006).
Overview¶
LeafSleuth is the Continuous Investigation & Performance Governance suite for Paper and Folia in the LeafCraft ecosystem (LicenseRef-LeafCraft-Commercial). It pinpoints exact lag sources—cross-referencing CoreProtect block history so walk-away lag-machine builders get caught instead of nearby bystanders—and cuts hotspot lag by -68.6% without breaking item sorters, pistons, or farm output. At the same time, LeafSleuth watches the server 24/7 and groups Lag Machines, Item Dupes & Stash Rings, and VPN Ban-Evader Alts / Bots into a single 1-click staff inbox (/sleuth cases) with teleport links and plain-English proof.
It ships with governor.mode: OBSERVE as the safe out-of-the-box default so server operators can verify every attribution and forensic engine on a live server with zero world changes first, and then switch to GOVERN_SAFE or GOVERN_BLACKBOX (/sleuth governor safe|on) whenever ready. Everything is organized under a 6-command operational tree (/sleuth <status|governor|cases|alts|farm|reload>) alongside Java method profilers (spark), block loggers (CoreProtect), and PvP packet anticheats (GrimAC, FairPlay):
- Confounder-Resistant, Online-Learned Lag Attribution (
REQ-SLEUTH-LAG-001): - Combines
predict-api's lock-freeWorkAttributionLedger,EwmaEstimator, andEwmaLinearFitwith online Normalized Least Mean Squares (NLMS) event-weight learning,CoreProtectblock-placement provenance, andSparkTimingClassifier(fork-agnostic probabilisticsparktiming / stack-frame classification acrossPaper,Purpur,Pufferfish,Leaf, andFolia) so forks that have already solved hopper or redstone lag learn near-zero weight for harmless events automatically rather than relying on hardcoded event times. - An idle bystander standing in the same chunk as an active lag machine has near-zero covariance with $\Delta\text{MSPT}$ and zero causal ledger initiation, keeping their 95% confidence interval centered around
0.0 ms/tick. - Synthetic & Periodic Pattern Recognition (
REQ-SLEUTH-LAG-002): - Computes bounded lag-$k$ autocorrelation ($k \in [1, 40]$ ticks) and inter-arrival coefficient of variation on chunk event bursts to classify
PERIODIC_CLOCK(redstone/hopper clocks with exact tick period),ENTITY_CRAM_BURST,CHUNK_THRASH, andSTEADY_LOAD. - 4-Pillar Bayesian Behavioral & Stylometric Profiling (
REQ-SLEUTH-BIO-001..005): - Evaluates four conditionally independent biometric and linguistic pillars to compute the posterior probability $P(\text{SamePerson} \mid E) \pm 95\%\text{ CI}$ and surface top
ExplainableTellmarkers:LINGUISTIC_STYLOMETRY: Privacy-safe hashed lexical/character n-grams, inverse-document-frequency ($\text{IDF} = \ln(N / \text{df})$) rare-word shibboleths, casing/punctuation habits (lowercase-only, trailing ellipsis, contraction style), command alias preferences (/homevs/h), and inter-message typing burst cadence (WPM + variance).MOTOR_KINEMATICS: Camera yaw/pitch delta histograms, mouse sensitivity greatest-common-divisor (GCD) quantization step, angular jerk, and click/hotbar switching cadence.TEMPORAL_CORRELATION: Active input burst cross-correlation $r \in [-1, 1]$ across short sliding buckets during overlapping sessions, separating genuine shared-IP roommates ($r \approx 0$, independent simultaneous bursts) from single-person multiboxing/tab-switching ($r < -0.35$, alternating bursts) or AFK-bot pairing.GAMEPLAY_GOAL_MARKOV: First-order transition matrix across coarse gameplay states (MINING,BUILDING,CRAFTING,COMBAT,CONTAINER_SORT,COMMAND_CHAT,AFK) plus spatial/container interaction overlap.
- Guardrails Against Historical "ML Anticheat" Failures (
leafsleuth-ADR-002Section 6):- No Black-Box Scores: Every comparison surfaces human-readable
ExplainableTellevidence (exact rare-word IDF shibboleths, WPM burst cadence, mouse GCD quantization step, and temporal cross-correlation $r$). - Base-Rate & Corroboration Protection: Applies skeptical prior odds, clamps individual pillar LLRs to $[-3.0, +3.0]$, and requires multi-pillar corroboration so no single shared quirk can trigger
LIKELY_SAME_PERSON. - Ping & Packet-Batch Sanitization: Filters sub-5ms packet-batched movement bursts and uses coarse $2\text{ s}$ temporal correlation buckets so latency jitter or server TPS drops never masquerade as kinematic anomalies.
- Cold-Start Shrinkage: Shrinks low-sample likelihood ratios via $w_k(n_{\text{eff}}) = n_{\text{eff}} / (n_{\text{eff}} + \kappa_k)$ and emits
INSUFFICIENT_EVIDENCEwhen the 95% credible interval is wide.
- No Black-Box Scores: Every comparison surfaces human-readable
- Population-Centered Multidimensional Relative Coordinate Space, Persistent Ban-Evasion Store & Banned Behavior Proximity (
RelativeCoordinateSpace,SleuthProfileStore,BannedBehaviorArchetype,leafsleuth-ADR-004):- Normalizes each player's heuristic features into intra-player relative proportions per namespace (
lex:,tri:,habit:,cmd:,cadence:,motor:,goal:,spatial:,behavior:), projects them onto $D = 16$ continuous orthogonal axes and 64 random hyperplanes viaSplitMix64, and subtracts the sybil-guarded online server population centroid $\hat{\mu}_d$ (down-weighting behavioral clone clusters, shared-subnet bot waves, andBannedBehaviorArchetypematches so a 30-bot swarm cannot poison the human baseline). - Common server-wide vocabulary and gameplay loops automatically cancel out at the origin $\vec{0}$ without a predefined feature dictionary, while similar players cluster into identical 64-bit Charikar
SimHashLSH bands and 3D spatial cells for sub-quadratic candidate discovery. - Persists compact, privacy-safe 4-pillar behavioral sketches and banned-account markers across server restarts (
SleuthProfileStore), filters out simultaneous independent players (isIndependentSimultaneousPair), and catches silent cheat alts by coordinate proximity (across both population-centered and uncentered anchor space) to canonicalBannedBehaviorArchetypeanchors (AUTOMINING_BOT,SCRIPTED_MACRO_CLICKER).
- Normalizes each player's heuristic features into intra-player relative proportions per namespace (
- Interactive Book/Chat UI & Unified Moderator Case Reports (
REQ-SLEUTH-UI-001): - Renders multi-page
MenuDescriptorreports viamenu-apiusing dark-on-parchment colors (&0,&1,&4,&5,&8) with expiringMenuTokenServicedrill-down callbacks, explicit confidence-tier / base-rate guidance (SleuthMenuBuilder#formatConfidenceGuidance), and side-by-side "Why Same Operator" vs "Why Distinct People" evidence columns (/sleuth status report,/sleuth alts compare,/sleuth cases).
Module Layout¶
| Module | Platform | Responsibility |
|---|---|---|
sleuth-common |
Pure Java 17 | Lag attribution regression, clock autocorrelation, 4-pillar stylometric/behavioral profiler, synthetic trace simulator, menu-api report builder, and [LeafSleuth bit] self-tests. Zero org.bukkit.* / net.minecraft.* imports. |
sleuth-paper |
Paper / Folia | Lock-free tick duration sampler, chunk/entity burst collector, kinematics/chat/action listener, and /sleuth command registrar (commands-api). Zero main-thread chunk I/O (S-005). |
sleuth-plugin |
Shaded JAR | Single distributable LeafSleuth-<version>.jar assembly. |
Commands¶
Operational 6-command tree (alias: /leafsleuth):
| Command | Subcommands / Parameters | Description | Permission |
|---|---|---|---|
/sleuth [status] |
report, chunk, plugins, archetypes, map, test, telemetry |
Open the interactive Book/Chat lag & forensic overview (report), inspect chunk marginal MSPT & clock period (chunk), rank third-party plugin listeners (plugins) and mechanism archetypes (archetypes), deliver a 128x128 spatial lag heatmap (map), run the 7-component [LeafSleuth bit] self-test (test), or inspect k-anonymity-guarded bStats telemetry |
leafsleuth.admin |
/sleuth governor |
status, safe, on, off, preview, blackbox |
Switch between OBSERVE (off), GOVERN_SAFE (safe), and GOVERN_BLACKBOX (on), preview projected -68.6% hotspot MSPT savings (preview), or inspect certified causal farm webs (blackbox) |
leafsleuth.admin |
/sleuth cases |
player=<name>, resolve, audit |
Open the 1-click staff investigation inbox grouping Lag Machines, Item Dupes & Stash Rings, and VPN Ban-Evader Alts / Bots with teleport links and plain-English proof (player=<name>), resolve a case, or run on-demand forensic audit suites (economy, rings, resources, probes, leaks, commands, faults, all) |
leafsleuth.admin |
/sleuth alts |
evaders, compare, profile, banmark |
List top VPN ban-evader and BannedBehaviorArchetype matches across 10,000+ accounts (evaders), compute a 4-pillar Bayesian identity comparison (compare), inspect a player's lag/kinematic fingerprint (profile), or freeze a banned profile in SleuthProfileStore (banmark) |
leafsleuth.admin |
/sleuth farm |
border, book |
Player-accessible inspection of a nearby farm's Causal Black-Box Certificate, Redstone Coach taint diagnostics (book), and rate-limited 3D particle boundary (border) |
leafsleuth.farm |
/sleuth reload |
(none) | Reload config.yml (governor mode, hysteresis, and forensic toggles) at runtime |
leafsleuth.admin |
Statistical Calibration & Empirical Hit Rates¶
Full statistical methodology, hypothesis-testing equations, confusion matrices, and reproduction commands are recorded in docs/dev/STATISTICAL_CALIBRATION.md:
| Subsystem / Task | Empirical Hit Rate (TPR / Recall) |
Empirical False Positive Rate (FPR) |
Calibration Dataset & Scale |
|---|---|---|---|
Lag Culprit Attribution (LagAttributionEngine) |
100.0% Top-1 Hit Rate (40 / 40 seeded trials); 92.5%+ CI95 coverage of true 6.0 ms/tick load |
0.000% (0 / 40) bystander misattribution (bystanderOnly=true) |
20-player, 50-chunk Monte Carlo (8,000 ticks) |
Periodic Clock Detection (LagPatternRecognizer) |
100.0% Period Recall (25 / 25 trials across $k \in [3, 25]$ ticks + Poisson noise) |
0.000% false clock classification on aperiodic noise |
jqwik property suite + Poisson mob-noise tests |
Closed-Loop Pareto Governor (CausalAutoTuner) |
100.0% Commit Recall across 1-chunk, 2x2 split (4 x 1.1 ms), & 0-variance steady culprits (DIAGNOSTIC_MICRO_DITHER) |
0.000% unwarranted throttling on GC spikes, bystanders, capped hoppers, sorters, or pistons |
Closed-loop plant simulations + live Paper 26.2-56 (9.24 -> 2.90 ms/tick, -68.6%) |
Causal Farm Virtualization (EmpiricalFarmBlackBox) |
100.0% Virtualization Recall on pure generative DAGs & post-taint-flush webs (35 clean ticks) |
0.000% Dupe / Taint Leakage (0 virtual items minted during taint or unload spikes) |
8-hop mob/crop DAG + single-item taint debt recovery + .litematic sugarcane benchmarks |
Bot / Macro & X-Ray Forensics (MotorKinematicsProfiler, GoalMarkovProfiler) |
100.0% Bot Recall (4 / 4 archetypes) & 100.0% X-Ray Surfacing (25.0% blind stone redirect yield) |
0.000% (0 / 18) on real human traces (10 OpenAI VPT + 8 Siddiqui same-PC); 0.000% on branch miners |
18 real human traces + Baritone / GCD-smooth / ghost-clicker & poke-hole branch-mining suites |
Modal Population & Doppelganger Matrix (BayesianIdentityLinker) |
100.0% Evader Lead Recall (12 / 12) (9 / 9 non-silent at LIKELY_SAME_PERSON, 3 / 3 silent VPN at MODERATE_INVESTIGATE_LEAD) |
0.000% (0 / 3,148) false LIKELY_SAME_PERSON convictions (0 / 4 distinct-IP & 0 / 4 shared-IP doppelgangers) |
$N = 80$ accounts ($\binom{80}{2} = 3,160$ pairs); soft MODERATE_INVESTIGATE_LEAD overlap bounded at 1.302% (41 / 3,148) |
10,000-Account Multi-Epoch Scaling & Wald's SPRT (RelativeCoordinateSpace) |
100.0% Top-1 Banned Match (posterior = 0.993, ACCEPT_H1_SAME_PERSON); 8 ms single-player IVM update; 9 ms ban query |
0.000% concept-drift misattribution (ACCEPT_H0_DISTINCT_PEOPLE after 4 hardware/playstyle drift epochs) |
$N = 10,000$ accounts (49,995,000 possible pairs), 1,311 ms initial sync, 64-hash MinHash + Space-Saving sketches |
Architecture Decision Records & Technical Documentation¶
docs/dev/STATISTICAL_CALIBRATION.md- Statistical Methodology, Asymmetric Operating Point, Modal/Doppelganger Confusion Matrix, Head-to-Head Comparison vs. Conventional Detection Mechanisms, and 10,000-Account Multi-Epoch Scaling Benchmarksleafsleuth-ADR-001- Confounder-Resistant Marginal MSPT Attribution, Clock Autocorrelation, and Dual Spatial Heatmap Overlayleafsleuth-ADR-002- 4-Pillar Bayesian Behavioral & Stylometric Identity Profiling with Explainable Tellsleafsleuth-ADR-003- Heuristic Lag Attribution with Confidence Intervals (LeafSleuth) and Web Panel Heatmap-to-Config Remediation Bridgeleafsleuth-ADR-004- Population-Centered Multidimensional Relative Coordinate Space and SimHash LSH Graph Scalingleafsleuth-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)