leafsleuth-ADR-001 - Confounder-Resistant Marginal MSPT Attribution, Clock Autocorrelation, and Dual Spatial Heatmap Overlay¶
Status: Accepted Date: 2026-10-27 Extends: leafsleuth-ADR-003, maps-api-ADR-003, menu-api-ADR-001
Context¶
On a multi-player Minecraft server (Paper or Folia), tick duration (MSPT) is a noisy aggregate of baseline server work, garbage-collection jitter, and localized activity bursts across dozens of loaded chunks. Naive attribution heuristics that rank players or chunks by raw proximity or total event count fail under two common operational confounders:
1. Bystander Confounding: A passive player standing in or near a chunk where another player activates a heavy redstone/hopper farm or mob grinder shares spatial coordinates during the spike, causing naive proximity counters to blame both accounts equally.
2. Unquantified Uncertainty: Short observation windows or high background variance can produce transient correlation spikes; reporting a bare point estimate without a calibrated 95% confidence interval misleads administrators.
Furthermore, operators need to know what kind of workload is driving a hotspot (steady load vs. a periodic $k$-tick redstone clock vs. entity cramming vs. rapid chunk-line thrashing) and inspect hotspots both in-game (128x128 filled maps and menu-api books) and in the LeafConfig web panel (512x512 WebTileRenderer PNG tiles with clickable cell metadata).
Decision¶
Implement a pure-Java lag attribution and spatial cartography pipeline in sleuth-common (net.leaf.sleuth.common.lag) with zero platform imports and zero synchronous chunk I/O (S-005):
1. Marginal MSPT Regression & Bystander De-Biasing (LagAttributionEngine)¶
- Each tick observation records the global/regional tick duration $Y_t$ (in ms) alongside per-chunk activity weights $X_{c,t}$ (weighted sum of redstone/hopper triggers, entity ticks/collisions, block mutations, and chunk load events) and per-player causal activity impulses $A_{p,c,t}$ tracked in
predict-api'sWorkAttributionLedgerandEwmaEstimator. - To isolate chunk $c$'s marginal cost $\hat{\beta}_c$ ($\text{ms/tick}$ per unit activity burst) and total attributed $\text{ms/tick}$ contribution $M_c = \hat{\beta}_c \cdot \bar{X}_c$:
LagAttributionEnginemaintains online exponentially weighted sample mean, variance, and covariance between tick excess $\Delta Y_t = \max(0, Y_t - Y_{\text{baseline}})$ and chunk activity share $S_{c,t} = X_{c,t} / \max(1, \sum_j X_{j,t})$.- Standard error is computed from residual variance and effective sample count $n_{\text{eff}}$, yielding a 95% confidence interval $\hat{\mu}_c \pm 1.96 \cdot \text{SE}(\hat{\mu}_c)$ (
ConfidenceInterval). - Within chunk $c$ (and globally per player), causal share is partitioned proportionally to active causal initiation covariance ($\text{Cov}(\Delta Y_t, A_{p,c,t})$ plus
WorkAttributionLedgeractive work rate) rather than passive spatial presence. An idle bystander with $A_{\text{bystander},c,t} = 0$ receives an estimate centered at $0.0\text{ ms/tick}$ whose 95% CI covers $0.0\text{ ms/tick}$ (REQ-SLEUTH-LAG-001).
2. Bounded Lag-$k$ Autocorrelation & Burst Classification (LagPatternRecognizer)¶
- For each active chunk,
LagPatternRecognizermaintains a bounded circular history of per-tick event counts $x_t$ (window $W = 160$ ticks) and inter-event arrival intervals. - It computes normalized sample autocorrelation $R(k)$ across candidate periods $k \in [2, 40]$ ticks: $$R(k) = \frac{\sum_{t=1}^{n-k} (x_t - \bar{x})(x_{t+k} - \bar{x})}{\sum_{t=1}^{n} (x_t - \bar{x})^2}$$
- To prevent sub-harmonic aliasing (e.g., an 8-tick clock also peaking at $k = 16, 24, 32$), the recognizer selects the smallest fundamental period $k^$ whose autocorrelation exceeds the periodicity threshold ($R(k^) \ge 0.45$) and classifies the chunk as
PERIODIC_CLOCKwithdetectedClockPeriodTicks = k*(REQ-SLEUTH-LAG-002). - Non-periodic chunks are classified by dominant burst telemetry into
CHUNK_THRASH,ENTITY_CRAM_BURST,STEADY_LOAD, orUNKNOWN.
3. Co-Registered Heatmap2D & SpatialCellMetadata Grid (SpatialAttributionGrid)¶
SpatialAttributionGridprojects chunk attributions onto a configurable $W \times H$ viewport grid, producing aSpatialHeatmapBundlecontaining:meanMsptHeatmap(Heatmap2DforHeatmapRenderer/WebTileRenderer).upperCi95Heatmap(Heatmap2Dof 95% upper confidence bounds for conservative hotspot triage).SpatialCellMetadata[]row-major cell descriptors soLeafConfigweb panels can resolve(cellX, cellZ)clicks directly to world/chunk bounds,marginalMsptCI,LagPatternType, and top suspect player (REQ-SLEUTH-MAP-001).
Alternatives Considered¶
| Alternative | Why Rejected |
|---|---|
| Attribute lag equally to all players within Euclidean radius $R$ of a hot chunk | Violates REQ-SLEUTH-LAG-001 by falsely blaming idle bystanders standing near another player's contraption. |
| Unbounded FFT over long tick histories | Adds unnecessary allocation and CPU cost when Minecraft redstone/hopper clocks operate at discrete integer tick periods $k \in [2, 40]$. |
| Query live chunks on the main thread when rendering heatmaps | Violates S-005 and REQ-RTP-MAP-002; all rendering consumes immutable snapshots off-thread. |
4. False-Negative Countermeasures: Counterfactual Micro-Dithering, Bounded Taint Debt Rehabilitation, and Contraption Cluster Attribution¶
- Low-Variance Steady-State Chunk Blind Spot (
LagAttributionEngine+CausalAutoTuner): - When an always-loaded chunk (e.g., spawn, chunk-loader, or stationary AFK player) executes a heavy contraption at nearly constant load ($X_{c,t} \approx \text{const}$), natural activity variance $\text{Var}(S_{c,t}) \to 0$ inflates standard error $\text{SE}$ and keeps
marginalMspt.lowerBound95() < minGuaranteedMspt(1.5 ms). LagAttributionEngine#isLowVarianceSteadyCandidatedetects high-activity candidates (estimate >= minGuaranteedMsptorupperBound95 >= 3.5 mswithlowerBound95 < minGuaranteedMsptand $\text{CV}(X_{c,t}) < 0.15$), andCausalAutoTunerissues a boundedDIAGNOSTIC_MICRO_DITHERdirective (TunerTrialState.DIAGNOSTIC_MICRO_DITHER/MitigationLever.DIAGNOSTIC_MICRO_DITHER: a 2-tick deferment window per 20-tick half-cycle out of40ticks).- Counterfactual on/off tick deltas (
ditherHighMsptvs.ditherLowMspt) collapse the 95% CI within 1–2 cycles, promoting true steady-state culprits toTRIAL_PROBE(TRIAL_STAGE_1) and immediately exonerating innocent constant-activity chunks (upperBound95 < 1.5 ms) back toOBSERVE_ONLY. - Bounded Taint Debt & Provenance Flushing without Duplication Risk (
EmpiricalFarmBlackBox): - Virtual yield never synthesizes player-deposited or unverified items, and tainted arrivals are excluded from the learned
yieldPerCausalEvent/itemRatesPerMinutenumerator. - Instead of permanent boolean poisoning when 1 stray item is dropped into a water stream, each
ContainerNodeandChunkCausalWebtrackstaintedItemDebtandlastTaintTick, holding virtualization inTAINTED_BY_PLAYER_WEB/TAINT_FLUSHINGwhiletaintedItemDebt > 0or withintaintCleanWindowTicks($T_{\text{clean}} = 35\text{ ticks}$). - Verified
PROVABLE_GENERATIVEarrivals (MOB_NATURAL_SPAWN,CROP_NATURAL_GROWTH,BLOCK_GENERATOR_FORM) amortizetaintedItemDebt1-for-1 (amortizeTaintDebt); oncetaintedItemDebt == 0and the quiet window elapses, the web rehabilitates toPROVABLE_GENERATIVEandVIRTUALIZED_ACTIVE. - Multi-Chunk Contraption Cluster Attribution (
CausalAutoTuner+EmpiricalFarmBlackBox): - Adjacent active chunks (
Chebyshev distance <= 1) or chunks linked viaEmpiricalFarmBlackBox#areChunksCausallyLinked(cross-chunk container transfers or redstone/piston border propagation) are grouped into a connected contraption cluster with aggregateclusterMarginalMspt, allowing a4.4 mscontraption split across a2x2chunk boundary (1.1 msper chunk) to triggerTRIAL_STAGE_1(TRIAL_PROBE) andCOMMITTED_ACTIVEacross all member chunks.
Consequences¶
- Positive:
- Accurately separates causal lag culprits from passive bystanders with honest 95% confidence intervals.
- Detects exact tick periods of synthetic redstone/hopper clocks without per-block bytecode instrumentation.
- Serves both in-game
128x128maps andLeafConfigclickable512x512web tiles from a single immutable bundle. - Negative / Trade-offs:
- When two players simultaneously trigger unlabelled redstone bursts in the exact same chunk at the exact same tick, their within-chunk covariance is shared and the confidence interval widens to reflect that ambiguity.