Skip to content

LeafSleuth: Continuous Investigation & Performance Governance

LeafSleuth: Continuous Investigation & Performance Governance for Paper & Folia

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):

  1. Confounder-Resistant, Online-Learned Lag Attribution (REQ-SLEUTH-LAG-001):
  2. Combines predict-api's lock-free WorkAttributionLedger, EwmaEstimator, and EwmaLinearFit with online Normalized Least Mean Squares (NLMS) event-weight learning, CoreProtect block-placement provenance, and SparkTimingClassifier (fork-agnostic probabilistic spark timing / stack-frame classification across Paper, Purpur, Pufferfish, Leaf, and Folia) 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.
  3. 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.
  4. Synthetic & Periodic Pattern Recognition (REQ-SLEUTH-LAG-002):
  5. 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, and STEADY_LOAD.
  6. 4-Pillar Bayesian Behavioral & Stylometric Profiling (REQ-SLEUTH-BIO-001 .. 005):
  7. 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 ExplainableTell markers:
    • 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 (/home vs /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.
  8. Guardrails Against Historical "ML Anticheat" Failures (leafsleuth-ADR-002 Section 6):
    • No Black-Box Scores: Every comparison surfaces human-readable ExplainableTell evidence (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_EVIDENCE when the 95% credible interval is wide.
  9. 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 via SplitMix64, and subtracts the sybil-guarded online server population centroid $\hat{\mu}_d$ (down-weighting behavioral clone clusters, shared-subnet bot waves, and BannedBehaviorArchetype matches 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 SimHash LSH 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 canonical BannedBehaviorArchetype anchors (AUTOMINING_BOT, SCRIPTED_MACRO_CLICKER).
  10. Interactive Book/Chat UI & Unified Moderator Case Reports (REQ-SLEUTH-UI-001):
  11. Renders multi-page MenuDescriptor reports via menu-api using dark-on-parchment colors (&0, &1, &4, &5, &8) with expiring MenuTokenService drill-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 Benchmarks
  • leafsleuth-ADR-001 - Confounder-Resistant Marginal MSPT Attribution, Clock Autocorrelation, and Dual Spatial Heatmap Overlay
  • leafsleuth-ADR-002 - 4-Pillar Bayesian Behavioral & Stylometric Identity Profiling with Explainable Tells
  • leafsleuth-ADR-003 - Heuristic Lag Attribution with Confidence Intervals (LeafSleuth) and Web Panel Heatmap-to-Config Remediation Bridge
  • leafsleuth-ADR-004 - Population-Centered Multidimensional Relative Coordinate Space and SimHash LSH Graph Scaling
  • 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)