leafanvil-ADR-006: Unified Zero-Copy Cold .lca ChunkFrame Residency & Bounded AIMD Sparse Dirty Block-Change Write-Back LRU Cache¶
- Status: Accepted
- Date: 2026-11-14
- Scope:
:anvil-api(io.github.dailystruggle.anvil.{LcaSectionBacking,LcaRegionFileStorage,LcaRegionReader,LcaRegionWriter,RawChunkFrameSnapshot}) &:resource:LeafAnvil(net.leaf.anvil.common.LcaInMemoryChunkCoordinator) - Related ADRs & Specs:
leafanvil-ADR-002,leafanvil-ADR-003,leafanvil-ADR-005,anvil-api-ADR-003,ADR-115
Context¶
In live Minecraft servers (Paper, Folia, Fabric, NeoForge), > 95% of loaded chunks and vertical sections are never mutated while resident in memory—they are read from r.<rx>.<rz>.lca (or synthesized by LeafGen Stage K3 GPU kernels), streamed to vanilla and LCA_NET_V1 clients, and eventually unloaded.
Treating the in-memory write cache like a cache of hydrated 4,096-voxel 3D chunk slabs (CompactBaseIndex hydration on write, STAGE_BULK_4096 16 KiB int[4096] promotion above 48 edits, 4x4x4 octant sub-cubes, and retaining clean post-compaction slabs in an LRU map) introduces three avoidable costs:
1. Storage Round-Trip Detour: Decoding .lca ChunkFrames into Mojang NBT on load only to re-encode clean NMS PalettedContainers back into .lca baseFrames wastes CPU and allocations when the on-disk .lca ChunkFrame already uses section-local indices 0..K-1 for ~98% of every SectionFrame.
2. Write-Time Slab Hydration & 16 KiB Inflation: Block writes only need an instant $O(1)$ (pos -> runtimeStateId) modifier in front of the cold .lca baseline—hydrating CompactBaseIndex on write or inflating > 48 edits into int[4096] (16 KiB) over-indexes on dense slab geometry.
3. Clean Slab Pollution & Unsynchronized Access-Ordered LinkedHashMap Gets: Retaining clean post-flush entries in an access-ordered LinkedHashMap wastes cache capacity and causes structural linked-list corruption if .get() runs outside a common lock (ACCESS_ORDERED_LRU_UNSYNCHRONIZED_GET).
Decision¶
We unify disk, server memory, GPU worldgen, and conditional network streaming around Cold-by-Default Immutable .lca ChunkFrame Buffers paired with a Bounded Thread-Safe Sparse Dirty Block-Change Write-Back LRU Cache (DirtyChunkLruCache), governed by REQ-RTP-S-002, REQ-RTP-S-004, and REQ-RTP-S-005:
1. Unified Cold .lca ChunkFrame Residency (0 Dirty LRU Slots)¶
- Off-thread (
REQ-RTP-S-005),LcaRegionFileStorage#readRawChunkFramereads the chunk slab via positionalFileChannelI/O guarded byLcaRegionReader#pinHazardSlab's 4-epoch grace ring (avoiding Windows NTFSFileChannel#mapfile-lock leaks perJDK-4724038/REQ-RTP-S-002): Mode A (codec1 == 0) reads the rawChunkFramebytes directly; Mode B (codec1 == 1) performs one pure-JavaLCD2(0x4C44"LD"Atomic Dictionary + 12-bit Huffman) unpack intoRawChunkFrameSnapshot. - Each open
LcaLiveArchivecachesint[] dictIdToRuntimeIdandint[] runtimeIdToDictIdtranslation arrays incrementally alongside its region dictionary. TrackedChunkColumnmountsvolatile byte[] chunkFrameand its 24-section offset directory directly in memory with zero entries inDirtyChunkLruCacheand zero background NMS-to-.lcavoxel re-encoding.
2. Instant $O(1)$ Sparse (pos12 -> runtimeStateId) Cell Writes (SparseDirtyCellMap)¶
LcaSectionBackingstores uncompacted block changes inSparseDirtyCellMap—a flat power-of-two open-addressed primitiveint[]table packing((pos12 + 1) << 19) | (runtimeStateId & 0x7FFFF)(0 == empty), resizing0 -> 16 -> 64 -> 256 -> 1024 -> 8192at<= 75%load factor.- Voxel writes (
recordDirtyVoxelandsetAndGetPreviousStateId) probe/insert in $O(1)$ (~2 ns) without callinghydrateCompactBaseIndexIfNeeded(), without allocating4x4x4octant sub-cubes, and without inflating toint[4096](16 KiB). - Every write increments the section's lock-free AIMD edit score (
+additiveIncrement, bounded byMAX_AIMD_EDIT_SCORE) and admits/touches only the mutated chunk inLcaInMemoryChunkCoordinator'sDirtyChunkLruCacheundersynchronized (dirtyCacheLock).
3. Bounded Synchronized Write-Back DirtyChunkLruCache & Section-Spliced CoW Flush (REQ-RTP-S-002, REQ-RTP-S-004, REQ-RTP-S-005)¶
- Membership Invariant: Only chunks with uncompacted dirty block changes reside in
DirtyChunkLruCache; all reads, touches, iterations, and removals on the access-orderedLinkedHashMapexecute strictly insidesynchronized (dirtyCacheLock). - AIMD + LRU Write-Back Eviction & CoW Splice: When
dirtyChunkCount() > maxDirtyChunks, or on quiet-window sweeps / autosave: - The coordinator selects the dirty chunk with the lowest aggregate AIMD edit score (tie-broken by least-recently-used order in
DirtyChunkLruCache) that is not already flushing, never dropping uncompacted edits (REQ-RTP-S-004). - An off-thread worker snapshots
dirtySectionMask, translates the $O(D)$ sparseruntimeStateIdmodifiers viaruntimeIdToDictId, re-encodes only the touchedSectionFrame(s), copies all untouchedSectionFramebyte slices verbatim viaSystem.arraycopy, and commits a256 BCopy-on-Write slab viaLcaRegionFileStorage#commitSplicedChunkFrameCoW(LcaLiveArchive#commitPreEncodedChunkCoW). - The worker atomically swaps
TrackedChunkColumn'svolatile byte[] chunkFramereference, advances(lastUpdateTick, baselineSecDed64), and removes the clean chunk fromDirtyChunkLruCache(0slots once clean). - Deterministic Unload Cleanup (
REQ-RTP-S-002):markChunkUnloadedandclearWorldimmediately fence in-flight tasks (UNLOADED_BIT+EpochCommitFence) and purge matching entries fromDirtyChunkLruCache.
Consequences¶
Positive¶
- Zero-Copy Disk $\leftrightarrow$ Memory $\leftrightarrow$ Wire Symmetry: Cold chunks share one immutable
.lcaChunkFramelayout across disk slabs, server RAM,LeafGenStage K3 GPU output, andLCA_NET_V1wire slices (rewriting only the4–32 BVarInt[K]section palette header on wire). - Instant Sparse Cell Writes: Memory scales strictly with unique modified blocks (
64 Bfor1..16edits,256 Bfor17..48,1 KiBfor49..192,4 KiBfor193..768), eliminating write-timeCompactBaseIndexhydration and16 KiBslab promotions. - Zero Clean-Cache Overhead & Zero LRU Race Hazards: Clean chunks consume
0slots inDirtyChunkLruCache, anddirtyCacheLockeliminates concurrentLinkedHashMap#getstructural hazards.
Trade-Offs & Mitigations¶
- Simultaneous Dirty Burst Backpressure (
REQ-RTP-S-004): If a single-tickWorldEditor explosion burst dirties more chunks thanmaxDirtyChunks, excess dirty entries schedule immediate off-thread CoW flushes and drain back belowmaxDirtyChunksas workers complete rather than dropping block changes.
Verification¶
LcaSectionBackingAndCompactionTest(:anvil-api): Verifies instant $O(1)$ writes across1,50, and500cells withCompactBaseIndex == nulland zeroint[4096]allocation, in-place single-slot overwrites, and cold post-compaction state.LcaRegionFileStorageTest(:anvil-api): Verifies Mode A (0-LZ) and Mode B (LCD20x4C44)readRawChunkFrame+commitSplicedChunkFrameCoWbit-for-bit preservation of all 23 untouchedSectionFrameslices.LcaAimd3dSlabCacheTest(:resource:LeafAnvil:leafanvil-common): Verifies0-slot coldChunkFrameresidency, sparse dirty-only LRU admission, AIMD + LRU victim CoW flush back to cold (dirtyChunkCount() == 0), concurrent multi-threaded LRU safety, and deterministicmarkChunkUnloaded/clearWorldcleanup (REQ-RTP-S-002).