feat(anvil)!: make the version guard and the unknown-entry fallback replaceable services

[TheMeinerLP]

Proposed changes

falco-anvil had two decisions fixed in code that are really policy:

1. Which worlds are readable. #45 refuses
   anything below the version floor or carrying a Level compound. Right for a server that only
   wants worlds it can read, wrong for a tool that wants to inspect one it cannot.
2. What an unknown palette entry becomes. BlockPaletteResolver substitutes air,
   BiomePaletteResolver substitutes plains, both counting it. A reasonable last resort for a server
   keeping a world loadable; the wrong reaction for anything that converts or audits one, because a
   substitution that is counted is still a substitution written back on the next save.

Neither is wrong. Both are policy, and policy only one consumer can choose is not policy.

Both become services, discoverable through the platform ServiceLoader or settable through a builder
slot. PaletteEntryResolver already proved the shape; what it lacked was discovery.

FalcoAnvilLoader.builder()
    .versionPolicy(myPolicy)          // explicit
    .discoverUnknownEntryPolicy()     // or from the classpath
    .build(worldRoot, OVERWORLD);

UnknownEntryPolicy returns a substitute name, not an id — "minecraft:air",
"minecraft:plains", or whatever the caller wants — or throws to fail the chunk. The resolver
resolves the name, because it holds the registry anyway. That shape was not the first draft; see
below.

Resolution rules, uniform across both services

• The shipped default steps aside for a foreign provider. Without this, falco-anvil registering
  its own implementations would mean a third party taking the documented route always produces two
  providers and always gets the refusal — discovery could never return anything but the default, and
  the extension point would be decoration.
• Two foreign providers throw, naming both. The default is not among the names.
• Builder slot and discovery are exclusive; the slot short-circuits before the class path is read.
• Discovery loads with the service's own class loader, not the thread context loader. Under
  CloudNet or extension class loaders the context loader may not see the jar; discovery would find
  nothing, resolve to no policy, and silently put the pre-21w43a air chunk back.

Resolution happens once, when the loader is built.

One deliberate behaviour change, decided with its cost stated

The version guard may be absent entirely: no registered provider means no check. That is a
deliberate decision, not an oversight, and its consequence is that a world older than snapshot 21w43a
loads as air again — no error, no log line. Three things keep it from being something anyone stumbles
into:

• falco-anvil registers its own guard, so losing it takes an exclusion somebody writes rather than
  an empty class path.
• The startup line that already reports the chosen region layout now reports the resolved policy, or
  none.
• testWithoutAnyPolicyALegacyChunkIsNotChecked asserts the chunk decodes to air. The cost is in
  executable form, so nobody has to take a paragraph's word for it.

Types of changes

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

The break is behavioural and narrow: build(...) now refuses a caller who configures an
UnknownEntryPolicy and supplies a custom resolver, because the custom resolver would silently
swallow the policy. Every signature change is additive; checkApiCompatibility reports "No changes."

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 (wiki commit held back locally until this lands)

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

Concurrency

Both services are resolved once and then called from every parallel chunk load.

• 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? No shared mutable state is introduced. Both shipped
defaults are stateless — they hold only static final constants and no instance fields.
ServiceLoader creates a fresh instance per loader build, so discovery shares nothing. The one route
to sharing is an explicitly passed policy on a reused builder, which every loader built from it then
shares; both policy slots document that, the way the diagnostics slot already did. Both interfaces
now state that implementations are called concurrently and must be thread-safe.

No new *ConcurrencyTest: the change adds no state for one to exercise, and a test over stateless
defaults would assert nothing.

Measurements

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

Further comments

The interface was rebuilt mid-flight, and the reason is worth recording. UnknownEntryPolicy
first returned an int id, which meant the default implementation resolved Block.AIR and the biome
registry itself. That tripped three ArchUnit rules — among them
dynamicRegistryOnlyInBiomeResolver, whose stated reason is that the registry lives "in exactly one
adapter". Two review rounds had waved the resulting duplication through as acceptable; the
architecture rules were sharper than the reviews. Returning a name instead put the registry back in
one place and removed the duplication, its double-checked locking included.

The rules only fired in the acceptance run, because no task had run :falco-archunit:test — a gap in
the plan, not in the work.

A fourth rule, byteLayerKnowsNoNbt, was widened rather than worked around: its allow list is
hand-maintained, and its own Javadoc wrongly promised it needed no maintenance, which is exactly why
nobody extended it. The promise is corrected. That rule is a layering statement about the byte
level, not the cardinality statement the registry rule makes — the policies sit a layer above and
carry NBT in their contracts by design.

Two findings are recorded as deliberate rather than fixed: checkVersion labels every policy refusal
as a version refusal (reachable only with a foreign policy throwing a non-version Reason;
diagnostics, not control flow), and it dereferences a @Nullable field under the caller's guard,
documented at both ends.

🤖 Generated with Claude Code

https://claude.ai/code/session_016jtJ4GUtmyCSHkiGY1CvgR

[github-actions]

Test results

  294 files    294 suites   8m 22s ⏱️
  973 tests   972 ✅ 1 💤 0 ❌
2 946 runs  2 944 ✅ 2 💤 0 ❌

Results for commit f41530b.