Built-In Testing ([LCA bit] / PBIT / CBIT) & 4-Tier Self-Healing Reference (LeafAnvil)¶
LeafAnvil (LeafAnvilBitSuite, /leafanvil bit) and LcaRegionReader (api/anvil-api, anvil-api-ADR-003 Section 7) enforce Power-On Built-In Testing (PBIT), Continuous Built-In Testing (CBIT T1..T8), runtime class/reflection compatibility diagnostics (LCA-0001..LCA-0004), and 4-tier algebraic and structural bit-rot recovery on .lca (LeafCraft Anvil) region files.
Run /leafanvil bit (or /lca bit) in-game or from the console to execute all 4 registered [LCA bit] PBIT and CBIT runtime compatibility checks:
[LeafAnvil] === [LCA bit] Built-In Test Suite (4/4 PASS, health=HEALTHY) ===
Namespaces¶
| Prefix |
|---|
LCA |
LCA (LeafAnvilBitSuite)¶
| ID | Code | Severity | Tier | Subsystem | Remediation |
|---|---|---|---|---|---|
| 1 | LCA_CODEC_WIRE_PBIT |
ERROR | PBIT | codec | Verify .lca v2 (0x0002) LcaSectionBacking 3D Hilbert / SEC-DED-64 and LCD2 (0x4C44) wire batch round-trip integrity (LcaWireStreamProtocol). |
| 2 | LCA_DISK_STORAGE_COMPAT |
ERROR | CBIT | storage | Verify NMS RegionFileStorage / RegionFile class compatibility (NmsRegionStorageInterceptor) and confirm /leafanvil status reports interceptedStorages >= 3 per enabled dimension (region/, entities/, poi/). |
| 3 | LCA_SECTION_BRIDGE_COMPAT |
ERROR | CBIT | section | Verify NMS Block.getId, LevelChunkSection, and PalettedContainer state extraction compatibility (LcaSectionBridge) for the running Minecraft server version. |
| 4 | LCA_NETWORK_CARRIER_COMPAT |
ERROR | CBIT | carrier | Verify platform carrier networking, ServerAccessor, and CommandsAPI command bindings for the active loader (Paper, Folia, Spigot, Fabric, or NeoForge). |
1. Power-On Built-In Test (PBIT)¶
On startup (LcaRegionReader.INSTANCE.executePbit()), LcaRegionReader encodes and decodes a static 2-section micro-canary (1 inline uniform section bit 15 == 1 + 1 non-uniform 01:H_3 Delta-Roaring section with 10:Y+H_2 Reflected Binary Gray-code SkyLight) in < 2 ms, verifying bit-exact voxel, biome, and light parity and octreeOccupancyMask64 equivalence before registering .lca in RegionFormatRegistry.
2. Continuous Built-In Test Tripwires (CBIT T1..T8)¶
Every .lca read and probe executes eight $O(1)$ inline safety tripwires:
| Tripwire | Invariant Verified | Failure Action (REQ-RTP-S-004) |
|---|---|---|
CBIT T1 |
Superblock magic 0x4C43415F56303031L ("LCA_V001") at 0x0000, footer canary 0x4C4341315F454E44L ("LCA1_END") at fileLength - 8, formatVersion in {0x0001, 0x0002}, slabShift == 8 (256B), and 1 <= sectionCount <= 128. |
Throws CorruptRegionEntryException (or triggers /leafanvil heal). |
CBIT T2 |
64-bit SplitMix/XXH64 headerChecksum at 0x38..0x3F matches computed checksum over superblock bytes 0x00..0x37. |
Rejects corrupted superblock header immediately. |
CBIT T3 |
Chunk pointer bounds: (slabOffset35 << 8) + exactByteLen20 <= fileLength - 8. |
Triggers Tier 1 SEC-DED or Tier 2 slab reverse-scan recovery. |
CBIT T3b |
Self-describing ChunkFrame header word (rawDvWord & 0xFC00_0000) == 0x5800_0000 and embedded ((rawDvWord >>> 16) & 0x03FF) == chunkIdx, plus Mode B (codec1 == 1) uncompressed header (72, 64) SEC-DED verification (T3c). |
Catches pointer offset variation (pointing to the wrong chunk's slab) in $O(1)$. |
CBIT T4 |
Per-chunk uncompressed allocation ceiling <= 16 MiB (MAX_CHUNK_UNCOMPRESSED_BYTES). |
Prevents out-of-memory allocation on malformed length fields. |
CBIT T5 |
uint16 sectionOffsets[i] (scaled by 1B or 4B) stays within exactByteLen20, Mode B chunk body begins with 0x4C44 ("LD" LCD2 frame magic), and chained dictionary nextSegmentLinkTrailer traversal is acyclic (<= 64 segments) and bounded within fileLength - 8 with verified (72, 64) SEC-DED dictionary syndromes. |
Rejects truncated frames, non-LCD2 Mode B payloads, or cyclic dictionary chains. |
CBIT T6 |
Per-state Delta-Roaring and Gray-light run cursor $h$ stays within $0 \le h \le 4,096$. | Isolates corrupt section container to Tier 3 quarantine. |
CBIT T6b |
64-bit spatial syndrome check: decodedOctreeMask64 accumulated from decoded minority voxels matches the stored 8-byte octreeOccupancyMask64 section header word. |
Catches silent interior run-byte bit flips even when $h \le 4,096$. |
CBIT T7 |
VarInt palette index bounds stay strictly < stateCount (or < biomeCount). |
Rejects out-of-range dictionary references. |
CBIT T8 |
Lock-free concurrent read guard: pins slabOffset35 in the 64-slot PINNED_SLAB_STARTS hazard-pointer table, reads ptrBefore, copies/decodes the slab, issues VarHandle.loadLoadFence(), and verifies ptrBefore == ptrAfter. |
Retries automatically if a concurrent CoW save updated the pointer mid-read (0 torn reads). |
3. 4-Tier Bit-Rot Self-Healing (/leafanvil heal)¶
Running /leafanvil heal [world=<name|all>] invokes LcaRegionReader.healRegionBitRot(byte[]), executing four progressive recovery tiers:
| Tier | Mechanism | What It Repairs |
|---|---|---|
Tier 1: Extended Hamming (72, 64) SEC-DED Pointer, Dictionary & Mode B Header Healing |
Evaluates each 64-bit pointer in 0x0040..0x203F against its 1-byte syndrome in secDedTableOffset, each active 64-bit word of Layer 2 dictionary segments (segmentFlags8 bit 1 = 0x02) against its downward-growing syndrome byte, and each Mode B ChunkFrame header word against headerSecDed (LcaSectionCodec.healSingleBitFlip64). |
Algebraically repairs any single-bit flip in slabOffset35, codec1, exactByteLen20, generation8, Layer 2 dictionary words, or Mode B ChunkFrame headers in < 10 ns, and detects 2-bit errors (DED) for Tier 2. |
Tier 2: Self-Describing 256B Slab Reverse-Scan |
Scans 256B-aligned sub-slabs from slabPoolBaseOffset to fileLength - 8 for the self-describing ChunkFrame canary 0x5800_0000 \| (chunkIdx << 16). |
Reconstructs zeroed, multi-bit corrupted (DED), or offset-shifted chunk directory pointers and recomputes their SEC-DED syndrome bytes. |
Tier 3: Section-Granular octreeOccupancyMask64 Quarantine |
Validates every section's CBIT T6 cursor bound and CBIT T6b 64-bit octreeOccupancyMask64 spatial syndrome (readChunkViewWithRecovery). |
Isolates interior voxel bit rot to the single affected $16 \times 16 \times 16$ section, substituting its dominant stratum palette[0] (90.8% of voxels) while preserving the other 23 vertical sections of the chunk intact. |
Tier 4: Copy-on-Write (CoW) Prior-Generation Rollback |
Restores prevChunkPointers[chunkIdx] maintained by LcaLiveArchive#rollbackCorruptChunkToPriorCoW. |
Rolls back a chunk in $O(1)$ to its previous verified 256B CoW slab generation if an interrupted write is detected. |