feat(anvil): let a loader migrate the chunks it reads

[TheMeinerLP]

Wires the falco-migration engine into the loader, and closes the one block rename it was missing.

Why

A world older than the running server loses whatever the server no longer knows by name — silently. Measured against a real 52 GB world (8299 region files, both dimensions), all 991 block names checked against the 26.1.2 registry:

Block	occurrences	rule
minecraft:grass → short_grass	241708	already present (3693)
minecraft:chain → iron_chain	18248	added here

989 of 991 names are fine. Those two decode to air through the UnknownEntryPolicy, with one log line each for the entire world — 260856 blocks. The loader then stamps the current DataVersion onto every chunk it saves, so the loss is written back and the world afterwards claims to be current.

The world holds both forms side by side — grass and short_grass, chain and iron_chain — because Paper converts what it loads. What was never loaded since the update is still in the old form.

What this adds

ChunkMigrationMode names three answers:

• OFF — the default, and exactly what the loader did before
• IN_MEMORY — translates on every read, never touches the world
• ON_DISK — writes the result back, so the work happens once per chunk instead of once per load

FalcoAnvilLoader.builder()
    .migration(ChunkMigrationMode.IN_MEMORY)
    .build(worldRoot, dimension);

A log line on startup states which mode is on and what it costs; both non-default modes are invisible from the outside otherwise.

Two decisions worth reviewing

Migration runs before the version guard. The guard refuses a chunk below the floor and one in the pre-1.18 Level layout, and migrating is what turns such a chunk into one it accepts. The other order would reject every world the option exists to rescue.

The backup cannot be switched off. There is a slot for where it goes and none for skipping it. ON_DISK replaces stored chunks, a wrong rule is only found afterwards, and by then the original is the only way back. It is copied per region file just before that file is first written, through a .partial name and an atomic move, and it lands beside the region directory — a copy inside would be read back as world data by the loader it was taken to protect.

The seam is a classpath service because the dependency only runs one way: falco-migration depends on falco-anvil, so the reverse is impossible. A deployment that registers no migrator carries no migration code; one that selects a mode without an engine fails to build rather than migrating nothing.

The chain rule's version is measured, not looked up

The two wiki-sourced numbers already in BlockStateRules were each wrong on the first attempt in the same release-vs-snapshot way, so this one comes from the world: every chunk's block names correlated with that same chunk's stored DataVersion, across 1399 region files.

chain appears at 3465, 3578, 3955 and 4435 (4930 chunks). iron_chain only at 4556 (189 chunks). No chunk carries both. The change happened in (4435, 4556] and the data cannot resolve it further.

4556 is the upper bound and the safe end: too high only lets the rule inspect chunks that no longer contain the old name, where nothing happens; too low would leave chain standing between the true version and the chosen one, and an unknown name is what becomes air.

Evidence

Against real 1.20.1 chunks (2219 chunks from the survival world):

	OFF	IN_MEMORY	ON_DISK 1st	ON_DISK 2nd
unknown blocks	grass, chain	none	none	none
migrated	0	3000	3000	0
errors	0	0	0	0

The second ON_DISK run finding nothing to do is what shows the write-back was correct. The backup held exactly the four region files actually touched.

19 tests, each checked by injecting the defect it exists to catch:

injected defect	caught by
migration moved behind the guard	testMigrationRunsBeforeTheVersionGuard
IN_MEMORY writing to disk	testInMemoryMigratesTheChunkAndLeavesTheFileUntouched
backup skipped before writing	testOnDiskCopiesTheOriginalBeforeItWrites
existing backup overwritten	testAnExistingBackupIsNotOverwrittenByALaterRun
META-INF/services removed	testTheAdapterIsRegisteredAsAService
since() moved off its measurement	testChainIsRenamedToIronChainAtTheMeasuredBoundary

Each was caught by its own test and by no other.

byteLayerKnowsNoNbt gains ChunkMigrator: it takes and returns a CompoundBinaryTag, the same shape as ChunkVersionPolicy, so it belongs to that layer rather than being an exception to it. ChunkMigrationMode names no NBT type and deliberately gets no entry.

./gradlew check --rerun-tasks is green across all modules.

Not in this PR

No downgrade, no Bedrock, no CLI. The engine's floor stays at 1.13.

🤖 Generated with Claude Code

https://claude.ai/code/session_016jtJ4GUtmyCSHkiGY1CvgR

[github-actions]

Test results

  330 files    330 suites   9m 56s ⏱️
1 068 tests 1 067 ✅ 1 💤 0 ❌
3 231 runs  3 229 ✅ 2 💤 0 ❌

Results for commit 0179350.