Skip to content

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's WorkAttributionLedger and EwmaEstimator.
  • 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$:
  • LagAttributionEngine maintains 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 WorkAttributionLedger active 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, LagPatternRecognizer maintains 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_CLOCK with detectedClockPeriodTicks = k* (REQ-SLEUTH-LAG-002).
  • Non-periodic chunks are classified by dominant burst telemetry into CHUNK_THRASH, ENTITY_CRAM_BURST, STEADY_LOAD, or UNKNOWN.

3. Co-Registered Heatmap2D & SpatialCellMetadata Grid (SpatialAttributionGrid)

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

  1. Low-Variance Steady-State Chunk Blind Spot (LagAttributionEngine + CausalAutoTuner):
  2. 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).
  3. LagAttributionEngine#isLowVarianceSteadyCandidate detects high-activity candidates (estimate >= minGuaranteedMspt or upperBound95 >= 3.5 ms with lowerBound95 < minGuaranteedMspt and $\text{CV}(X_{c,t}) < 0.15$), and CausalAutoTuner issues a bounded DIAGNOSTIC_MICRO_DITHER directive (TunerTrialState.DIAGNOSTIC_MICRO_DITHER / MitigationLever.DIAGNOSTIC_MICRO_DITHER: a 2-tick deferment window per 20-tick half-cycle out of 40 ticks).
  4. Counterfactual on/off tick deltas (ditherHighMspt vs. ditherLowMspt) collapse the 95% CI within 1–2 cycles, promoting true steady-state culprits to TRIAL_PROBE (TRIAL_STAGE_1) and immediately exonerating innocent constant-activity chunks (upperBound95 < 1.5 ms) back to OBSERVE_ONLY.
  5. Bounded Taint Debt & Provenance Flushing without Duplication Risk (EmpiricalFarmBlackBox):
  6. Virtual yield never synthesizes player-deposited or unverified items, and tainted arrivals are excluded from the learned yieldPerCausalEvent / itemRatesPerMinute numerator.
  7. Instead of permanent boolean poisoning when 1 stray item is dropped into a water stream, each ContainerNode and ChunkCausalWeb tracks taintedItemDebt and lastTaintTick, holding virtualization in TAINTED_BY_PLAYER_WEB / TAINT_FLUSHING while taintedItemDebt > 0 or within taintCleanWindowTicks ($T_{\text{clean}} = 35\text{ ticks}$).
  8. Verified PROVABLE_GENERATIVE arrivals (MOB_NATURAL_SPAWN, CROP_NATURAL_GROWTH, BLOCK_GENERATOR_FORM) amortize taintedItemDebt 1-for-1 (amortizeTaintDebt); once taintedItemDebt == 0 and the quiet window elapses, the web rehabilitates to PROVABLE_GENERATIVE and VIRTUALIZED_ACTIVE.
  9. Multi-Chunk Contraption Cluster Attribution (CausalAutoTuner + EmpiricalFarmBlackBox):
  10. Adjacent active chunks (Chebyshev distance <= 1) or chunks linked via EmpiricalFarmBlackBox#areChunksCausallyLinked (cross-chunk container transfers or redstone/piston border propagation) are grouped into a connected contraption cluster with aggregate clusterMarginalMspt, allowing a 4.4 ms contraption split across a 2x2 chunk boundary (1.1 ms per chunk) to trigger TRIAL_STAGE_1 (TRIAL_PROBE) and COMMITTED_ACTIVE across 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 128x128 maps and LeafConfig clickable 512x512 web 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.