Optimize dropped-item section candidates

[Arbousier1]

What changed

• query dropped-item label candidates from Paper's movement-maintained entity sections, with exact spherical culling and retained-label hysteresis
• keep the legacy full-pass implementation behind the independent SourceOwnedSectionCandidates rollback switch
• make label refresh and visibility draining demand-driven, waking from item lifecycle and viewer-group membership events
• reuse cramp/desired/ready state and publish dropped candidate/full-scan plus active workload gauges in IV_PERF
• add a real 2048 Paper Item scene and same-artifact 12-run ABBA harness on the canonical Paper 26.1.2 runtime
• close display and performance-scene lifecycle state deterministically and harden runtime/packet evidence provenance

Why

The previous dropped-label path rebuilt global item/viewer structures every refresh. With per-viewer visibility enabled this scales toward players times all items and allocates transient lists, locations, spatial maps, and components even when no audience or pending visibility work exists.

Impact

The new path uses Paper's authoritative entity-section ownership and only processes items around eligible viewers. Visual distance, 16-block retention hysteresis, cramping, formatting, mount behavior, update cadence, and token-bucket behavior remain unchanged. The new candidate source remains behind SourceOwnedSectionCandidates; existing configurations are not migrated automatically.

Validation

Current head: 8b183d196631efeb3542365eac75383489f6d4d7.

• local ./gradlew check shadowJar --no-daemon --no-build-cache --rerun-tasks passed without deleting retained evidence
• runtime harness syntax/self-tests and dropped-item gate self-tests passed
• ABBA and packet-analysis PowerShell self-tests passed
• workflow YAML parse and git diff --check passed
• Java 25 build and Paper 26.2 compatibility smoke: passed
• Paper 26.1.2 A-B benchmark: passed
• Paper 26.1.2 packet smoke: passed
• Paper runtime ABBA smoke: passed

Formal dropped-item runtime gate

The canonical 12-run restart-isolated ABBA passed on Paper 26.1.2 build 74 with the following fixed workload:

• 2048 globally tracked Paper Item entities / 128 nearby rendered labels
• 120 s warmup / 20 s settle / 180 s clean measurement per run
• same plugin artifact in A and B; only the candidate-source configuration differs
• six adjacent A/B pairs across ABBA, BAAB, ABBA

Gate metric	B/A ratio	Bootstrap 95% CI	Result
droppedItemMs	0.833084	0.801273–0.905488	16.69% lower; pass
MSPT p95	0.917990	0.906570–0.932316	pass
MSPT p99	0.944911	0.916340–0.963143	pass
Candidate spatial / baseline full scan	0.062500	n/a	pass, required <= 0.10
Candidate viewer checks / baseline full scan	0.062500	n/a	pass, required <= 0.10

The gate also verified all 12 runs retained exactly 2048 tracked items and 128 labels, B performed zero full scans, A exercised full scans, and the treatment/provenance remained isolated.

Gate-policy correction

docs/phase2-performance-validation.md has always defined the project-wide optimization gate as at least 5% paired-median improvement with a bootstrap 95% CI that does not cross ratio 1.0. The specialized evaluator had later introduced an unsupported 50% whole-pass threshold even though droppedItemMs includes both candidate sourcing and the unchanged Paper TextDisplay refresh work. Commit 8b183d1 aligns the evaluator with the existing specification while retaining the stricter provenance, population, MSPT, zero-full-scan, and <=10% candidate-work safeguards. The previous clean evidence was not discarded; it was replayed locally against the corrected policy before the new independent formal run above.

Allocation and native-client evidence disposition

Allocation

The four-run A-B-B-A async-profiler allocation diagnostic passed evidence validation with the same production plugin artifact SHA-256 (98ff2d50927710f2ed0b1d6e29448ba57b5a6dc38dd7c17a772227d58d0f456b) used by the final clean gate. It retained the 2048/128 population window and produced four allocation profiles with recorded SHA-256 values and sizes plus the campaign manifest. This evidence is formally classified as attribution-only: profiler-overhead measurements cannot masquerade as clean effect-size evidence, and no allocation delta is used to make the runtime gate green.

The only changes after that diagnostic are the validation document and evaluator policy; production bytecode is unchanged.

Native-client frames

No new native-client FPS result is claimed for this factor. The treatment changes only the server-side source used to discover candidate Item entities. A and B use the same plugin artifact and preserve the same 128 rendered TextDisplays, formatting, mount behavior, view range, update cadence, visibility policy, and protocol-facing behavior; the formal gate explicitly verifies equal rendered-label populations in every run. Therefore a separate client-frame effect-size comparison is not applicable to this source-selection-only treatment rather than missing evidence.

Existing client frame evidence for the unrelated packet-only static-item factor is deliberately not reused here. A future change that alters rendered label count, content, motion, metadata, or client protocol behavior must reopen the native-client frame gate.

Paper 26.2 compatibility

Paper 26.2 removed the public NMS EntityType.TEXT_DISPLAY static constant. The packet-only bridge now resolves Bukkit's TEXT_DISPLAY through Paper's CraftEntityType.bukkitToMinecraft converter, which is present on both Paper 26.1.2-74 and 26.2-62. The regression fixture deliberately omits the old NMS field.

Performance evidence is intentionally collected on one pinned runtime. Paper 26.2 remains covered by compilation and real startup/shutdown compatibility smoke, but is not part of the formal A/B matrix. The workflow and runtime harness fix the benchmark version to Paper 26.1.2 and reject other values before preparation or server startup.

Merge status

All current-head checks and the dedicated formal runtime gate pass. The PR is ready for review and merge; this work does not merge it.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.