feat: add chunk data recording and chunk-enabled binary replay playback

[DriftN2Forty]

Summary

This PR adds end-to-end chunk data recording for BetterReplay's binary replay format and wires that data through recording, persistence, loading, playback, diagnostics, and teardown.

The branch starts with the chunk archive contract and recording pipeline, then carries the feature through chunk-enabled replay loading and playback, and finishes with packet-friendly BRCP playback, viewer-facing tuning knobs, teardown hardening, diagnostics, caching, and documentation updates.

At a high level, this means saved binary replays can now include chunk sidecar data, replay viewers can see chunk state around the replay subject instead of relying only on timeline block mutations, and the runtime has the controls and safeguards needed to make that practical in production.

What This Adds

Binary chunk recording pipeline

• Defines the chunk sidecar contract for binary replays, including manifest metadata, canonical chunk entry naming, region grouping, temp-region persistence, and finalized .brregion archive layout.
• Adds recording-time chunk discovery based on player interest radius, deduplicated baseline capture, bounded unique-chunk capture limits, and save/recovery integration for chunk temp artifacts.
• Extends binary replay finalization and recovery so chunk-enabled recordings survive crashes and persist cleanly into finalized archives.

Chunk-enabled replay loading

• Adds manifest-aware chunk loading for binary replays.
• Validates manifest-to-entry consistency for chunk archives.
• Soft-fails invalid chunk sidecar data back to timeline-only playback instead of breaking replay load entirely.

Playback support for chunk-enabled replays

• Adds on-demand replay chunk lookup and viewer application around the replay spectator.
• Supports the existing block-baseline BRCS payload path and the packet-friendly BRCP payload path.
• Reapplies prior block mutations when chunks enter view during a replay so timeline state stays visually correct.
• Restores live chunk state when replay chunks leave view, when the replay stops, and when a viewer disconnects mid-session.

Packet-friendly BRCP playback

• Captures packet-friendly live chunk snapshots during recording.
• Includes block-entity payloads when runtime NBT extraction is available.
• Sends replay chunks back to the viewer using real chunk packets instead of only per-block rewrites.
• Keeps prepared replay chunk packets cached for the viewer session so chunks that leave and re-enter view can be resent without rebuilding payloads.

Runtime tuning and diagnostics

• Adds Playback.Chunk-View-Radius so replay chunk loading can use a replay-specific radius.
• Adds Playback.Chunk-Timing-Diagnostics for per-stage replay chunk timing and async preparation diagnostics.
• Adds Playback.Chunk-Mode with two restore strategies:
  • 1: moving-window restore as replay chunks leave the replay window
  • 2: deferred restore that cooperates with natural client chunk unloads and resends replay chunks when the viewer returns
• Adds chunk-specific replay inspection stats to /replay debug info, including region counts, chunk counts, and compressed versus decompressed chunk payload sizes.

Performance and hardening work included with the feature

• Offloads BRCP archive decode and packet-column preparation off the main thread.
• Avoids rescanning the entire timeline for per-chunk mutations by using chunk-indexed lookup during playback.
• Reuses prepared live-restore packets where possible during cleanup.
• Paces live chunk restore snapshot capture and replay stop teardown to reduce end-of-replay spikes.
• Adds reflective compatibility handling around PacketEvents chunk/runtime differences and improves logging when replay chunk decode or send operations fail.

Key Implementation Areas

Recording and artifact persistence

• New chunk recording abstractions, capture coordination, radius-based interest tracking, chunk artifact propagation, and temp-region writing.
• Binary archive finalization updated to include chunk sidecars and related manifest metadata.

Loading and storage

• Binary storage codec and manifest handling updated for chunk-enabled archives.
• Replay playback data now carries chunk payloads through the load path.
• Replay inspection now exposes chunk-aware storage metrics.

Playback and restore lifecycle

• ReplayBlockManager now owns the chunk-enabled playback lifecycle, including replay chunk preparation, application, resend behavior, live restore queueing, teardown, residency tracking, and mode-aware restore decisions.
• Packet-friendly chunk preparation and caching are split into dedicated helpers to keep the replay refresh path narrower and cheaper.

Docs and operator guidance

• Updates the README, binary format docs, archive manifest schema docs, and chunk recording planning/implementation docs so the storage contract and runtime behavior are documented alongside the code.

Config and Behavior Notes

This PR adds or finalizes the following chunk-related config surface:

• Recording.Chunks.Enabled
• Recording.Chunks.Capture-Radius
• Recording.Chunks.Max-Unique-Chunks
• Playback.Chunk-View-Radius
• Playback.Chunk-Timing-Diagnostics
• Playback.Chunk-Mode

Operationally, the biggest user-visible change is that chunk-enabled binary replays can now restore surrounding chunk state for the replay viewer, and BRCP recordings can do that with real chunk packet playback rather than only block-by-block rewriting.

Validation

• Ran mvn test
• Result: 466 tests passed, 0 failures, 0 errors, 0 skipped

Notes For Reviewers

• The implementation was landed in phases, but this PR is intended to be reviewed as one feature line: record chunk data, persist it in the binary format, load it back safely, and render/restore it correctly during replay playback.
• Most of the behavioral complexity lives in ReplayBlockManager, the binary storage codec/manifest path, and the packet-friendly capture/build helpers.
• The docs are intentionally updated in the same PR because this introduces new binary archive semantics and new operator-facing config.