fix(anvil)!: refuse a world the loader cannot read instead of returning air

[TheMeinerLP]

Proposed changes

FalcoAnvilLoader expects the chunk layout Minecraft writes since snapshot 21w43a: sections on the
root compound. A world written before that keeps everything one level down, under Level. Three
decisions, each defensible on its own, combined into silent data loss:

1. chunkStatus looks for Status/status on the root (:1354-1357). A pre-21w43a chunk carries
   Level.Status, so the answer is null.
2. isFullyGenerated(null) returns true (:1371-1372) — deliberately, so a world written by a tool
   that stores no status stays readable.
3. NbtReads.optionalList returns ListBinaryTag.empty() for a missing key (NbtReads.java:162-167),
   and the pre-21w43a key is Level.Sections.

The chunk was then counted as loaded and consisted entirely of air, with no error and no log line.
DataVersion would answer the question outright, and the loader writes it at :1706 — it was never
read.

This adds a guard at the one seam in loadChunk where the full root compound exists and nothing has
been interpreted yet. It checks the layout first and the version second, because a version number
is a claim about the data while the layout is the data — so the guard does not rest on a version
table being correct.

The rule in three cases:

Input	Result
Level layout	refused, regardless of version
DataVersion missing	accepted — foreign tools write worlds without it
DataVersion broken (wrong tag type, negative)	refused

This converts nothing. It does not touch the save path and it does not make a pre-21w43a world
usable. Conversion is the separate falco-migration effort.

One number moved during implementation: the floor is 2844, not 2860. The layout change landed in
snapshot 21w43a (DataVersion 2844); 2860 is merely the first stable release carrying it. Verified
against minecraft.wiki/w/Data_version and /w/Java_Edition_21w43a, whose changelog reads "Removed
chunk's Level and moved everything it contained up. Level.Sections has moved to sections."

Design and plan are in the branch: docs/superpowers/specs/2026-08-03-anvil-version-guard-design.md
and docs/superpowers/plans/2026-08-03-anvil-version-guard.md.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• New feature (non-breaking change which adds functionality)
• Performance change (behaviour unchanged, cost changed)
• Documentation Update (if none of the other choices apply)

The break is behavioural, not binary: a caller feeding the loader a pre-21w43a world now gets an
exception where it got an air chunk. Every signature change is additive and
checkApiCompatibility passes — japicmp does not flag the new enum constant, which is last in the
declaration so a foreign exhaustive switch keeps compiling.

Checklist

• I have read the CONTRIBUTING.md
• The title of this pull request is a Conventional Commit
• I have added tests that prove my fix is effective, written before the implementation and watched fail for the right reason
• Tests are package-private, named test<What><Expectation>, and use plain JUnit assertions
• Every new or changed class and method carries Javadoc with @param / @return / @throws
• I have not written @NotNull
• ./gradlew build is green locally
• I have added necessary documentation — README plus the existing Anvil-Chunk-Loader wiki page

Counts taken from the JUnit XML, all six modules, --rerun-tasks: anvil 231, light 223, instance
259, demo 167, benchmarks 42 (1 skipped), archunit 47. No count fell.

Concurrency

The guard runs in the load path, which serves a virtual thread per chunk.

• I have stated below which state the change adds or shares, and what guards it
• Any new mutable state is either confined to one call or explicitly documented as thread-safe
• I have added or extended a *ConcurrencyTest — see below

What is shared, and how is it guarded? The guard itself reads only its local data argument and
final fields (minimumDataVersion, regionDirectory, diagnostics). It adds no mutable state of its
own. The one shared structure it writes to is the new breakdown in AnvilDiagnostics, a
ConcurrentHashMap<String, LongAdder> that mirrors the existing partialChunkStatuses field
exactly — same cap over MAX_TRACKED_NAMES, same per-value throttle, same deliberate race between
the size check and the insertion, which is documented at the call site. The total counter increments
before every return path including the cap bail-out, so a version beyond the cap still counts toward
chunksSkippedAsUnsupported() and only loses its own map entry.

No new *ConcurrencyTest: the change shares no state the existing
AnvilDiagnosticsConcurrencyTest does not already cover for the identical structure it copies.

Measurements

No performance claim is made anywhere in this branch, and none may be quoted from it.

Further comments

Three things are deliberately not fixed here and belong on the open list:

1. The air hole is only half closed. The third of the three causes named above —
   optionalList returning empty instead of throwing — is unchanged at :1506. A chunk with
   Status: minecraft:full and neither sections nor Level still reaches the caller as air. That
   is a pre-existing, different defect (a truncated chunk in the current format); this branch does
   not worsen it and does not claim to close it.
2. Whether further decoder-relevant format changes lie between DataVersion 2845 and 2860 could not be
   established — the wiki marks itself incomplete there.
3. A DataVersion stored with the wrong tag type appears in the diagnostics breakdown as -1, the
   sentinel of optionalInteger, indistinguishable from a genuine -1. Both are correctly refused,
   and the exception message does distinguish them; only the breakdown label is imprecise.

🤖 Generated with Claude Code

https://claude.ai/code/session_016jtJ4GUtmyCSHkiGY1CvgR

[github-actions]

Test results

  285 files    285 suites   8m 57s ⏱️
  946 tests   945 ✅ 1 💤 0 ❌
2 865 runs  2 863 ✅ 2 💤 0 ❌

Results for commit a868454.