v

- Restore cave spawning and correct floor placement across platforms.
- Enforce category population limits and clamp ambient spawn batches.
- Honor mob-spawning rules and entity-ticking chunk admission.
- Separate chunk saving from configurable distance-despawn retention.
- Add spawning regressions and Folia gameplay acceptance coverage.

.github/ISSUE_TEMPLATE/bug.yml

@@ -27,19 +27,42 @@ body:
       placeholder: The code to place a is missing b and c...
     validations:
       required: false
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      description: Which server platform is Iris running on? Pick the loader or server software, not the launcher.
+      options:
+        - Paper
+        - Purpur
+        - Leaf
+        - Canvas
+        - Folia
+        - Spigot / CraftBukkit
+        - Fabric
+        - Forge
+        - NeoForge
+        - Other (describe under Problem)
+    validations:
+      required: true
   - type: dropdown
     id: mcversion
     attributes:
       label: Minecraft Version
-      description: What version of Minecraft is the server on?
+      description: What version of Minecraft is the server on? Iris 4.x supports 26.1.2 to 26.3 on Bukkit-family servers and 26.3 on Fabric, Forge and NeoForge; older versions are not supported.
       options:
-        - 1.14.X
-        - 1.15.X
-        - 1.16.X
-        - 1.17
-        - 1.17.1
-        - 1.18
-        - 1.19
+        - '26.3'
+        - '26.2'
+        - '26.1.2'
+        - Other (unsupported)
+    validations:
+      required: true
+  - type: input
+    id: loaderversion
+    attributes:
+      label: Platform / Loader Version
+      description: Exact server or loader build (see console). For example "Paper 26.3-133", "Fabric Loader 0.19.5", "NeoForge 26.3.0.33-beta".
+      placeholder: DO NOT SAY "LATEST"
     validations:
       required: true
   - type: input

.gitignore

@@ -10,4 +10,69 @@ libs/
 
 collection/
 
-src/main/java/com/volmit/iris/util/uniques/
+out/
+tools/simd-bench/out/
+tools/simd-bench/simd-bench.jar
+
+DataPackExamples/
+
+TreeGenStuff/
+dist/
+core/plugins/
+adapters/bukkit/plugin/plugins/
+
+# Dev-run artifacts. `run/` is a loom/ForgeGradle/ModDevGradle working directory and `logs/` is
+# server output; neither is ever source. No source directory in this repo is named run or logs.
+run/
+logs/
+*.log
+*.log.gz
+crash-reports/
+hs_err_pid*.log
+replay_pid*.log
+
+.codegraph/
+
+plans/
+
+.env
+.env.*
+!.env.example
+local.properties
+*.jks
+*.p12
+*.pfx
+*.pem
+*.key
+*.hprof
+credentials.json
+service-account*.json
+
+# docs/ is hand-written and tracked (flat numbered product docs). Nothing under it is
+# generated, so there is nothing to ignore here.
+
+.qa/
+.repro/
+.perf/
+.release-gate/
+
+# Throwaway worktree copies used by the API / PlaceholderAPI rebuild lanes. Generated, never source.
+.apiwt/
+.papiwt/
+
+__pycache__/
+
+# Doc authoring scratch
+.docs-wip/
+
+AGENTS.md
+
+# Local build tooling, not part of the project
+build-lt.sh
+BUILDS/
+.run/
+
+# Version-content compat lane worktree. Generated, never source.
+.compatwt/
+
+.worktrees/

README.md

@@ -1,79 +1,327 @@
 # Iris
 
-The master branch is for the latest version of minecraft.
+Iris is a world generation engine for Minecraft servers and mod loaders. It generates terrain,
+biomes, caves, structures, objects, and entities from editable JSON packs, with a full in-game
+studio authoring workflow. The same engine runs as a Bukkit-family plugin and as a Fabric, Forge,
+or NeoForge server mod. Cross-platform generation targets deterministic parity for identical
+artifacts, pack bytes, seeds, and test areas. The master branch targets Minecraft 26.3.
 
-# [Support](https://discord.gg/3xxPTpT) **|** [Documentation](https://docs.volmit.com/iris/) **|** [Git](https://github.com/IrisDimensions)
+# [Support](https://discord.gg/3xxPTpT) **|** [Documentation](https://github.com/VolmitSoftware/docs/blob/master/iris/00-overview.md) **|** [Git](https://github.com/IrisDimensions)
 
-# Building
+Authoritative docs live in the central [VolmitSoftware/docs](https://github.com/VolmitSoftware/docs/tree/master/iris) repository, which is the source for the hosted wiki.
 
-Building Iris is fairly simple, though you will need to setup a few things if your system has never been used for java
-development.
+Consider supporting development by buying Iris on Spigot.
 
-Consider supporting our development by buying Iris on spigot! We work hard to make Iris the best it can be for everyone.
+## Language and localization
 
-## Preface: if you need help compiling and you are a developer / intend to help out in the community or with development we would love to help you regardless in the discord! however do not come to the discord asking for free copies, or a tutorial on how to compile.
+Canonical English is defined in the typed Java catalogs under `core/src/main/java/art/arcane/iris/localization`, next to the command, Studio, runtime, and UI surfaces that use it. Iris does not ship an English server translation file; the required Minecraft client asset remains at `assets/irisworldgen/lang/en_us.json`. Complete server bundles and matching client assets are included for German, Spanish, Finnish, French, Hebrew, Italian, Japanese, Korean, Lithuanian, Dutch, Polish, Portuguese, Russian, Turkish, Vietnamese, Simplified Chinese, and Traditional Chinese. Set `language` in Iris settings to select one. A JSON file at `languages/overrides/<locale>.json` can override only selected server messages; omitted entries resolve from the bundle and then code-owned English.
 
-### Command Line Builds
+## Platforms
 
-1. Install [Java JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
-2. Set the JDK installation path to `JAVA_HOME` as an environment variable.
-    * Windows
-        1. Start > Type `env` and press Enter
-        2. Advanced > Environment Variables
-        3. Under System Variables, click `New...`
-        4. Variable Name: `JAVA_HOME`
-        5. Variable Value: `C:\Program Files\Java\jdk-17.0.1` (verify this exists after installing java don't just copy
-           the example text)
-    * MacOS
-        1. Run `/usr/libexec/java_home -V` and look for Java 17
-        2. Run `sudo nano ~/.zshenv`
-        3. Add `export JAVA_HOME=$(/usr/libexec/java_home)` as a new line
-        4. Use `CTRL + X`, then Press `Y`, Then `ENTER`
-        5. Quit & Reopen Terminal and verify with `echo $JAVA_HOME`. It should print a directory
-3. If this is your first time building Iris for MC 1.18+ run `gradlew setup` inside the root Iris project folder.
-   Otherwise, skip this step. Grab a coffee, this may take up to 5 minutes depending on your cpu & internet connection.
-4. Once the project has setup, run `gradlew iris`
-5. The Iris jar will be placed in `Iris/build/Iris-XXX-XXX.jar` Enjoy! Consider supporting us by buying it on spigot!
+| Platform | Artifact | Minecraft | Notes |
+|---|---|---|---|
+| Paper / Purpur / Leaf / Canvas | plugin jar | 26.1.2 - 26.3 | Full feature set |
+| Folia | plugin jar | 26.1.2 - 26.3 | Region-safe scheduling throughout |
+| Spigot / CraftBukkit | plugin jar | 26.1.2 - 26.3 | Managed `iris:*` creation and generation; exact vanilla-slot `/iris replace` is unavailable |
+| Fabric | mod jar | 26.3 | Server worldgen + client HUD; requires Fabric Loader 0.19.5+ |
+| Forge | mod jar | 26.3 | Server worldgen + client HUD; current target is Forge 26.3-66.0.8 |
+| NeoForge | mod jar | 26.3 | Server worldgen + client HUD; current target is NeoForge 26.3.0.33-beta |
 
-### IDE Builds (for development)
+Java 25 is required on every platform.
 
-* Run `gradlew setup` any time you get dependency issues with craftbukkit
-* Configure ITJ Gradle to use JDK 17 (in settings, search for gradle)
-* Add a build line in the build.gradle for your own build task to directly compile Iris into your plugins folder if you
-  prefer.
-* Resync the project & run your newly created task (under the development folder in gradle tasks!)
+The modded feature set matches the plugin wherever the operation is not Bukkit-bound: worldgen
+from Iris packs, authoring with mod blocks/items/entities (with validation suggestions), studio
+workspaces with schema autocomplete over the server's live registries, entity spawning parity
+including death loot, pregeneration with a boss bar or client HUD, the `/iris` command tree, and
+the goldenhash determinism gate, which is interchangeable across all four platforms.
 
-# Iris Toolbelt
+### Native worldgen over Iris terrain
 
-Everyone needs a tool-belt.
+Iris replaces the chunk generator, so vanilla and mod worldgen only runs where Iris runs it. This
+is identical on every platform.
 
-```java
-package com.volmit.iris.core.tools;
+| Vanilla / mod worldgen | Over Iris terrain | Control |
+|---|---|---|
+| Structures (vanilla, datapack, mod) | Yes, on by default | `importedStructures.disabled` denies individual keys |
+| Placed features: ores, trees, plants, springs, geodes | Yes, **off by default** | `importedFeatures.enabled` per dimension, with per-step and per-key filters |
+| Carvers (caves, canyons, mod carvers) | Never - architectural | Iris has no `NoiseGeneratorSettings` for a carver to sample; use pack `caves`/`carvings` |
+| Surface builders and surface rules | Never | Iris builds its surface from pack palettes |
+| Mod biomes | Only as a `derivative`, `vanillaDerivative`, `biomeScatter` or `biomeSkyScatter` target | Iris chooses biomes from the pack, not from a biome source |
+| Mob spawning, including mod mobs | Yes | Biome spawn tables are merged with the vanilla derivative's |
 
-// Get IrisDataManager from a world
-IrisToolbelt.access(anyWorld).getCompound().getData();
+With `importedFeatures` off - the default - chunk output is byte-for-byte what Iris has always
+produced. See [94 - API - Modded](https://github.com/VolmitSoftware/docs/blob/master/iris/94-api-modded.md) and
+[01 - Installation & Platforms](https://github.com/VolmitSoftware/docs/blob/master/iris/01-installation-platforms.md) for the full control reference, including
+which `pointed_dripstone` keys the 26.2 `speleothem` rename does and does not affect.
 
-// Get Default Engine from world
-IrisToolbelt.access(anyWorld).getCompound().getDefaultEngine();
+Independently of that flag, Iris custom biomes now inherit the biome tags of their vanilla
+derivative on every platform, so the emitted datapack tag files change. Anything driven by biome
+tags therefore applies to Iris custom biomes: mob variants, spawn rules, and any vanilla or mod
+content selecting on `#minecraft:is_overworld` and friends.
 
-// Get the engine at the given height
-IrisToolbelt.access(anyWorld).getCompound().getEngineForHeight(68);
+## Install
 
-// IS THIS THING ON?
-boolean yes=IrisToolbelt.isIrisWorld(world);
+**Plugin (Paper/Purpur/Leaf/Canvas/Folia/Spigot):** drop the plugin jar into `plugins/` and start
+the server. First boot performs no pack download. Run `/iris download pack=overworld`,
+`/iris download pack=underworld`, or `/iris download link=https://host/path/pack.zip`, waiting for
+each download to finish before starting another. The current built-in packs declare no external
+datapack imports. Restart after download so Minecraft loads their dimension types and biomes.
+Custom packs that declare `datapackImports` must complete their external-datapack installation and
+registry restart first. Bukkit accepts Modrinth, direct HTTP(S), and absolute local `file:` ZIP URLs;
+ZIPs under `plugins/Iris/datapacks/imports/` are discovered for every Iris dimension. Plain Spigot
+supports ordinary managed `/iris create`, but not
+the early-bootstrap `/iris replace` path for canonical Overworld, Nether, or End slots.
 
-// GTFO for worlds (moves players to any other world, just not this one)
-IrisToolbelt.evacuate(world);
+**Mod (Fabric/Forge/NeoForge):** drop the mod jar into `mods/` and start the server. The jar is
+self-contained (core, SPI, and required Fabric API modules are bundled). First boot compiles only
+packs already on disk and never accesses the network. `/iris download` installs a pack atomically
+without stopping the server. The current built-in packs declare no external datapack imports.
+Custom packs that declare them require compatible archives in that save's `datapacks/` directory;
+modded `/iris datapack ingest` is an explanatory stub and does not install them. Restart only after
+the Iris pack and all of its inputs are present. Packs register their custom dimension types,
+height ranges, biomes, and external structure keys during that boot; worlds created
+before it run with fallback registry data.
+
+**Singleplayer (modded clients):** installed Iris packs appear as selectable World Types on the
+Create New World screen; the integrated server runs the same engine.
+
+## The client mod
+
+Installing the mod jar on a client adds a native pregeneration HUD: a top-left panel with a
+progress bar, chunks done/total, percent, chunks per second, and ETA, turning yellow while the
+pregen is paused. The `H` key (rebindable, under the "Iris" controls category) toggles it.
+
+The HUD works against modded Iris servers and against Bukkit/Paper Iris servers, both over the
+`irisworldgen:main` channel (custom payloads on modded, plugin messaging on Bukkit). Vanilla
+clients are unaffected and get the server-side boss bar instead; on non-Iris servers the client
+mod is inert.
+
+## Quickstart
+
+Complete the platform's pack, external-datapack, and registry-restart workflow above first. Then
+create and enter an Iris world.
+
+Plugin (optional arguments are keyed):
 
-IrisAccess access=IrisToolbelt.createWorld() // If you like builders...
-  .name("myWorld") // The world name
-  .dimension("terrifyinghands")
-  .seed(69133742) // The world seed
-  .headless(true)  // Headless make gen go fast
-  .pregen(PregenTask // Define a pregen job to run
-  .builder()
-    .center(new Position2(0,0)) // REGION coords (1 region = 32x32 chunks)
-    .radius(4)  // Radius in REGIONS. Rad of 4 means a 9x9 Region map.
-    .build())
-  .create();
 ```
+/iris create myworld type=overworld seed=1337
+/iris tp myworld
+```
+
+Mod (positional arguments):
+
+```
+/iris create myworld overworld 1337
+/iris tp irisworldgen:myworld
+```
+
+On Paper-family servers with early bootstrap (not plain Spigot), the shipping pair can instead
+replace the canonical portal-linked slots after their registry workflow is complete:
+
+```
+/iris replace minecraft:overworld type=overworld seed=123456789
+/iris replace minecraft:the_nether type=underworld seed=-987654321
+```
+
+Restart once after both commands report staged. The independent seeds apply to their respective
+slots, and vanilla portals keep routing between the canonical Overworld and Nether identities.
+
+Pregeneration requires a radius in blocks. On the plugin, optional arguments are keyed; on modded
+servers they are positional and composable:
+
+```
+/iris pregen start 352 world=myworld center=0,0 gui=false
+/iris pregen start 352 irisworldgen:myworld at 0 0 sync
+```
+
+Players with the client mod see the native HUD; everyone else gets a boss bar (modded) or
+console/status output. `/iris pregen status` reports progress on the plugin.
+
+## Studio and VSCode workspace
+
+The studio is the pack authoring environment, available on all platforms. Studio worlds are
+transient - they are deleted on close and purged at startup.
+
+Plugin:
+
+```
+/iris studio create name=<name> [template=<pack>]
+/iris studio open <pack> [seed=1337]
+/iris studio vscode [dimension=<pack>]
+/iris studio update [dimension=<pack>]
+/iris studio close
+```
+
+Mod:
+
+```
+/iris studio create [name] [template]
+/iris studio open <pack> [seed]
+/iris studio vscode [pack]
+/iris studio update [pack]
+/iris studio close
+```
+
+The generated VSCode workspace wires per-type JSON schemas (dimensions, biomes, regions, objects,
+loot, entities, snippets) for full autocomplete. Schemas are generated from the server's live
+registries, so on modded servers block, item, entity, enchantment, and potion-effect completion
+includes installed mod content (for example `create:brass_ingot`). Editing an open studio's pack
+files hotloads the changes and regenerates the schemas.
+
+## PlaceholderAPI
+
+Iris registers the `iris` expansion when PlaceholderAPI is enabled. Paths are dot-separated,
+lowercase, and never contain an underscore. Every value is plain text: no colour codes, no unit
+suffixes, no `%` character, `.` as the decimal separator, and no thousands grouping.
+
+Three answers are possible. A path that is not in the list below returns nothing, so PlaceholderAPI
+re-emits the literal `%iris_...%` and a typo stays visible. A known path with no value right now
+returns `---`. A real zero returns `0`.
+
+| Placeholder | Value |
+|---|---|
+| `%iris_available%` | `true` when the Iris terrain service is live |
+| `%iris_world.available%` | `true` when the reading player is in an Iris world and a reading exists |
+| `%iris_world.biome%` | Surface biome display name at the player, e.g. `Hot Desert Dunes` |
+| `%iris_world.biome-key%` | Surface biome load key, e.g. `desert/hot-dunes` |
+| `%iris_world.biome-custom%` | `true` when the surface biome defines custom derivatives, otherwise `false` |
+| `%iris_world.biome-custom-id%` | Authored `customDerivitives[].id` when exactly one derivative is defined, for example `golden-dunes`; `---` for none or multiple |
+| `%iris_world.biome-custom-ids%` | All authored custom derivative IDs, comma-and-space separated in definition order; `---` for none |
+| `%iris_world.biome-custom-key%` | Namespaced Minecraft registry key for the sole custom derivative, such as `iris:biomes/<hash>`; `---` for none, multiple, or unavailable mapping |
+| `%iris_world.biome-custom-keys%` | Registry keys for all custom derivatives in definition order, comma-and-space separated; `---` for none or any unavailable mapping |
+| `%iris_world.biome-custom-count%` | Number of authored custom derivatives; `0` for a vanilla-only biome |
+| `%iris_world.biome-derivative%` | Configured base derivative registry key, for example `minecraft:desert` |
+| `%iris_world.biome-vanilla-derivative%` | Effective vanilla derivative registry key used when a vanilla biome is required |
+| `%iris_world.biome-type%` | Inferred biome category: `land`, `sea`, `shore`, or `cave`; `---` when unavailable |
+| `%iris_world.min-height%` | World minimum absolute Y, inclusive |
+| `%iris_world.max-height%` | World maximum absolute Y, exclusive |
+| `%iris_world.height%` | World vertical span, equal to maximum minus minimum height |
+| `%iris_world.fluid-height%` | Dimension fluid level in absolute world Y; this is configuration, not a measurement of water at the player |
+| `%iris_world.region%` | Region display name at the player |
+| `%iris_world.region-key%` | Region load key |
+| `%iris_world.dimension%` | Dimension (pack) load key of the player's world |
+| `%iris_pregen.available%` | `true` while a pregeneration job is running |
+| `%iris_pregen.world%` | World name the running job is pregenerating |
+| `%iris_pregen.percent%` | Completion, `0.00` to `100.00`, no `%` character |
+| `%iris_pregen.eta%` | Estimated seconds remaining, whole number |
+| `%iris_pregen.eta-text%` | Same estimate as `2m 5s` or `1h 30m` |
+| `%iris_pregen.chunks%` | Chunks generated so far |
+| `%iris_pregen.total%` | Chunks in the job |
+| `%iris_pregen.chunks-per-second%` | Current rate |
+| `%iris_pregen.paused%` | `true` while the job is paused |
+
+Custom derivative IDs are authored metadata. A singular ID or registry key is available only when the biome defines one derivative; plural keys list all definitions. Saved columns retain their historical biome definitions.
+
+Biome and region values describe the surface at the player's block column. Height values describe world configuration. Walking refreshes them at most
+once per second per player, so a whole board of `world.*` keys costs one refresh per player per
+second no matter how many of them are on it, and a value may lag a sprinting player by up to a
+second. A jump that is not walking - joining, respawning, changing worlds, stepping through a portal,
+or any teleport including `/iris goto`, `/tp`, an ender pearl and a random teleport - is published
+immediately, so a player who arrives somewhere and then stands still never keeps reading the biome,
+region or dimension of where they came from. `pregen.*` is global: there is one pregeneration job per
+server, and `%iris_pregen.world%` says which world it is.
+
+### Migration from the pre-2.0 keys
+
+The old underscore keys are gone. There is no alias and no dual-accept window; an old key now
+renders literally so it is visible rather than silently wrong.
+
+| Old key | New key | Why |
+|---|---|---|
+| `%iris_biome_name%` | `%iris_world.biome%` | Renamed onto the dot grammar |
+| `%iris_biome_id%` | `%iris_world.biome-key%` | Renamed; `id` was always the load key |
+| `%iris_region_name%` | `%iris_world.region%` | Renamed onto the dot grammar |
+| `%iris_region_id%` | `%iris_world.region-key%` | Renamed; `id` was always the load key |
+| `%iris_biome_file%` | removed | Rendered an absolute server path into player-visible text, and threw on packs with no backing file |
+| `%iris_region_file%` | removed | Same as `biome_file` |
+| `%iris_world_seed%` | removed | Handed the world seed to anyone who could read a scoreboard, and a placeholder has no permission context to gate on |
+| `%iris_terrain_height%` | removed | Reported the *generated* height, before objects and player edits, so it disagreed with the block under the player's feet |
+| `%iris_terrain_slope%` | removed | Three extra noise samples per read for an unformatted pack-authoring diagnostic |
+| `%iris_world_mode%` | removed | Studio or Production; a studio world exists for seconds during authoring and is never on a live board |
+| `%iris_world_speed%` | removed | Mutated engine rate-window state every time it was read. `%iris_pregen.chunks-per-second%` answers the same question from a snapshot |
+
+The old keys also read the *cave* biome for a player standing under an overhang, because they
+sampled two blocks above the player's feet. The new `world.biome` is always the surface biome,
+which is what a board reader means.
+
+## Building from source
+
+Requirements: JDK 25 (set `JAVA_HOME` to it). The Gradle wrapper handles everything else.
+
+```
+./gradlew buildAllToOut
+```
+
+builds every platform artifact into the workspace-level `../PluginOuts/` directory:
+
+```
+Iris v<version> [CraftBukkit] <mc>.jar
+Iris v<version> [Fabric] <mc>+<loader>.jar
+Iris v<version> [Forge] <mc>+<loader>.jar
+Iris v<version> [NeoForge] <mc>+<loader>.jar
+```
+
+Per-platform tasks: `./gradlew buildBukkit`, `buildFabric`, `buildForge`, `buildNeoforge`. The
+SPI jar (the pure-JVM adapter/platform contract, not the stable plugin API) is built to `spi/build/libs/` by
+`./gradlew :spi:jar`.
+
+`./gradlew buildAll` also runs `buildAllToOut` and copies the jars into a consumer dropin tree
+for a local test server. The consumer directory defaults to `../../[Minecraft Server]/consumers/`
+when it exists, otherwise `build/consumers/` inside the repo. `-Plocation=/path/to/consumers`
+changes only the consumer directory. Both tasks copy all four verified platform jars into
+`../PluginOuts/`.
+
+VolmLib is built from source when a `VolmLib` checkout sits beside the repo or in a parent directory
+(`VOLMLIB_DIR` or `-PlocalVolmLibDirectory=<path>` pick another one). Without one, or with
+`-PuseLocalVolmLib=false`, the build uses VolmLib `master-SNAPSHOT` from JitPack. There is no VolmLib
+version to bump. The build logs which VolmLib it used, and every jar records it in
+`META-INF/volmit/volmlib.properties`.
+
+If you need help compiling as a developer or contributor, ask in the Discord.
+
+## Adapters / modded development
+
+`core/` and `spi/` are pure JVM. `adapters/bukkit/` is part of the root Gradle build; the three
+modded adapters (`adapters/fabric`, `adapters/forge`, `adapters/neoforge`) are standalone builds
+with their own `settings.gradle`, which is what keeps Loom, ForgeGradle, and ModDevGradle off one
+plugin classpath. Drive them with `-p`:
+
+```
+./gradlew -p adapters/fabric   runServer      # or runClient
+./gradlew -p adapters/forge    runServer
+./gradlew -p adapters/neoforge runServer
+./gradlew -p adapters/fabric   test           # shared adapters/modded-common test suite
+```
+
+Each `runServer` accepts determinism and world-integrity flags, forwarded to the game as system
+properties:
+
+| Flag | System property | Purpose |
+|---|---|---|
+| `-PirisParity=<pack>` | `iris.parity` | Run the cross-platform parity harness for a pack |
+| `-PirisParityGolden=<file>` | `iris.parity.golden` | Compare against a captured golden-hash file |
+| `-PirisParityDeep=true` | `iris.parity.deep` | Deep (per-block) parity instead of hash-only |
+| `-PirisWorldCheck=<world>` | `iris.worldcheck` | Post-generation world integrity check |
+
+Fabric additionally takes `-PirisClientRunDir=<dir>` to relocate the `runClient` working directory.
+Shared code lives in `adapters/modded-common` (loaders + the shared test suite) and
+`adapters/client-common` (client HUD and world-type screens); every adapter adds those source
+directories, so one edit reaches all three loaders. Shared Minecraft-native code lives in VolmLib
+(`native/minecraft-common`).
+
+For IDE import you can surface the three adapter builds in the root composite with
+`-PincludeModdedAdapters=true`. It is off by default: each adapter includes the root build back to
+substitute `art.arcane:core` and `art.arcane:spi`, so including them from the root closes a
+composite cycle. The build and release paths do not need it.
+
+## Documentation
+
+Full product docs live in the central [VolmitSoftware/docs](https://github.com/VolmitSoftware/docs/tree/master/iris) repository. Start with:
+
+- [Overview and index](https://github.com/VolmitSoftware/docs/blob/master/iris/00-overview.md)
+- [Installation and platforms](https://github.com/VolmitSoftware/docs/blob/master/iris/01-installation-platforms.md)
+- [Getting started](https://github.com/VolmitSoftware/docs/blob/master/iris/02-getting-started.md)
+- [Structures overview](https://github.com/VolmitSoftware/docs/blob/master/iris/18-structures-overview.md)
+- [API — Getting Started](https://github.com/VolmitSoftware/docs/blob/master/iris/90-api-getting-started.md)
+- [Maintainer — MC version bump](https://github.com/VolmitSoftware/docs/blob/master/iris/85-maintainer-mc-version-bump.md)
+- [Maintainer — release checklist](https://github.com/VolmitSoftware/docs/blob/master/iris/86-maintainer-release-checklist.md)

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/IrisChunkGeneratorHeightCacheTest.java

@@ -0,0 +1,137 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeChunkGenerator;
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeTerrainColumns;
+import art.arcane.iris.platform.bukkit.nms.BukkitTerrainColumnPolicy;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.runtime.GenerationSessionLease;
+import art.arcane.iris.world.history.BoundaryColumnGeometry;
+import art.arcane.iris.world.history.TerrainBoundarySignature;
+import art.arcane.iris.testsupport.PlatformLeakGuard;
+import art.arcane.volmlib.nativelib.terrain.NativeTerrainColumnPolicy;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import static org.junit.Assert.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.never;
+
+public final class IrisChunkGeneratorHeightCacheTest {
+    @Rule
+    public final PlatformLeakGuard leakGuard = PlatformLeakGuard.clean();
+
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void repeatedNativeHeightUsesLiveHeightQueriesAcrossRuntimeChanges() throws Exception {
+        Fixture fixture = fixture();
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        when(fixture.engine().getHeight(-1, -33, false)).thenReturn(4);
+        for (int index = 0; index < 100; index++) {
+            assertEquals(-11, fixture.generator().getBaseHeight(
+                    -1, -33, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        }
+        verify(fixture.engine(), times(100)).getHeight(-1, -33, false);
+
+        when(fixture.engine().getCacheID()).thenReturn(2);
+        when(fixture.engine().getHeight(-1, -33, false)).thenReturn(7);
+        assertEquals(-8, fixture.generator().getBaseHeight(-1, -33, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        verify(fixture.engine(), never()).getComplex();
+        verify(fixture.engine(), never()).getMode();
+    }
+
+    @Test
+    public void nativeHeightPredicatesSelectFluidOrSolidHeightWithoutGeneratingTerrain() throws Exception {
+        Fixture fixture = fixture();
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        when(fixture.engine().getHeight(0, 0, false)).thenReturn(20, 25);
+        when(fixture.engine().getHeight(0, 0, true)).thenReturn(8);
+
+        assertEquals(5, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        assertEquals(10, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        assertEquals(-7, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.OCEAN_FLOOR, bounds, null));
+        verify(fixture.engine(), times(2)).getHeight(0, 0, false);
+        verify(fixture.engine(), times(1)).getHeight(0, 0, true);
+        verify(fixture.engine(), never()).getComplex();
+        verify(fixture.engine(), never()).getMode();
+    }
+
+    @Test
+    public void nativePredicatesAndAccessorBoundsRemainExact() throws Exception {
+        NativeTerrainColumnPolicy policy = mock(NativeTerrainColumnPolicy.class);
+        NativeTerrainColumnPolicy.ColumnSession session = mock(NativeTerrainColumnPolicy.ColumnSession.class);
+        when(policy.openQuery(any())).thenReturn(session);
+        when(policy.placementKey(anyString())).thenAnswer(invocation -> invocation.getArgument(0));
+        doReturn(Optional.of(signature().geometry())).when(session).resolvedColumn();
+        NativeChunkGenerator<?, ?, ?, ?, ?> generator = generator(policy);
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        for (int repeat = 0; repeat < 2; repeat++) {
+            assertEquals(-11, generator.getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+            assertEquals(-13, generator.getBaseHeight(0, 0, Heightmap.Types.OCEAN_FLOOR, bounds, null));
+            assertEquals(-13, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING, bounds, null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, bounds, null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE,
+                    LevelHeightAccessor.create(-16, 2), null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING_NO_LEAVES,
+                    LevelHeightAccessor.create(-14, 3), null));
+        }
+        verify(session, times(6)).resolvedColumn();
+    }
+
+    private static Fixture fixture() throws Exception {
+        Engine engine = mock(Engine.class);
+        when(engine.getCacheID()).thenReturn(1);
+        when(engine.acquireGenerationLease(anyString())).thenReturn(GenerationSessionLease.noop());
+        return new Fixture(generator(new BukkitTerrainColumnPolicy(engine, null)), engine);
+    }
+
+    private static NativeChunkGenerator<?, ?, ?, ?, ?> generator(NativeTerrainColumnPolicy policy) throws Exception {
+        NativeChunkGenerator<?, ?, ?, ?, ?> generator = mock(NativeChunkGenerator.class, CALLS_REAL_METHODS);
+        set(generator, "terrainColumns", new NativeTerrainColumns(policy));
+        return generator;
+    }
+
+    private static void set(NativeChunkGenerator<?, ?, ?, ?, ?> generator, String name, Object value) throws Exception {
+        Field field = NativeChunkGenerator.class.getDeclaredField(name);
+        field.setAccessible(true);
+        field.set(generator, value);
+    }
+
+    private static TerrainBoundarySignature signature() {
+        BoundaryColumnGeometry geometry = BoundaryColumnGeometry.fromVoxels(-16, List.of(
+                new BoundaryColumnGeometry.Voxel("minecraft:stone", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:water", BoundaryColumnGeometry.Phase.FLUID, "minecraft:water", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:oak_leaves[persistent=true]", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:short_grass", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:light[level=15]", BoundaryColumnGeometry.Phase.SOLID, "", false)));
+        return new TerrainBoundarySignature(
+                new TerrainBoundarySignature.Column(0, 0, 4, 4, OptionalInt.of(1), OptionalInt.empty()),
+                new TerrainBoundarySignature.Samples(new TerrainBoundarySignature.VerticalLayout(-16, 5, 1),
+                        new TerrainBoundarySignature.BiomeEncoding(List.of("minecraft:plains"), new short[]{0})), geometry);
+    }
+
+    private record Fixture(NativeChunkGenerator<?, ?, ?, ?, ?> generator, Engine engine) {
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeGenerationWriteGuardTest.java

@@ -0,0 +1,129 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.iris.structure.nativegen.GenerationWritePolicy;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeGenerationWriteGuard;
+
+import art.arcane.iris.generation.runtime.DimensionStackContext;
+import art.arcane.iris.generation.runtime.DimensionStackLayout;
+import art.arcane.iris.generation.runtime.IrisComplex;
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.world.history.GenerationActivation;
+import art.arcane.iris.world.history.GenerationHistory;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.structure.object.IrisStaticObjectLayer;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.Optional;
+import java.util.function.Predicate;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+public final class NativeGenerationWriteGuardTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void staticObjectsProtectRelativeHeightBeforeStackSampling() {
+        IrisStaticObjectLayer objects = mock(IrisStaticObjectLayer.class);
+        DimensionStackContext stack = mock(DimensionStackContext.class);
+        when(objects.contains(-3, 74, -7)).thenReturn(true);
+
+        Predicate<BlockPos> protectedPositions = NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, stack, -64));
+
+        assertTrue(protectedPositions.test(new BlockPos(-3, 10, -7)));
+        verifyNoInteractions(stack);
+        assertFalse(NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, null, -64))
+                .test(new BlockPos(-3, 11, -7)));
+    }
+
+    @Test
+    public void emptyStaticLayerSkipsContainsAndCachesEachSignedColumn() {
+        IrisStaticObjectLayer objects = mock(IrisStaticObjectLayer.class);
+        DimensionStackContext stack = mock(DimensionStackContext.class);
+        DimensionStackLayout negative = mock(DimensionStackLayout.class);
+        DimensionStackLayout positive = mock(DimensionStackLayout.class);
+        when(objects.isEmpty()).thenReturn(true);
+        when(stack.sample(-1, -1)).thenReturn(negative);
+        when(stack.sample(-1, 1)).thenReturn(positive);
+        when(negative.isHostFeatureProtectedY(64)).thenReturn(true);
+        when(positive.isHostFeatureProtectedY(65)).thenReturn(true);
+
+        Predicate<BlockPos> protectedPositions = NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, stack, -64));
+
+        assertTrue(protectedPositions.test(new BlockPos(-1, 0, -1)));
+        assertFalse(protectedPositions.test(new BlockPos(-1, 1, -1)));
+        assertTrue(protectedPositions.test(new BlockPos(-1, 1, 1)));
+        verify(stack, times(1)).sample(-1, -1);
+        verify(stack, times(1)).sample(-1, 1);
+        verify(objects, never()).contains(anyInt(), anyInt(), anyInt());
+    }
+
+    @Test
+    public void preTerrainSavedStampDistinguishesEarlierNativeStarts() {
+        IrisEngine engine = mock(IrisEngine.class);
+        GenerationHistoryRuntimeRouter router = mock(GenerationHistoryRuntimeRouter.class);
+        GenerationHistory history = mock(GenerationHistory.class);
+        GenerationActivation active = mock(GenerationActivation.class);
+        when(engine.getGenerationHistoryRuntimeRouter()).thenReturn(Optional.of(router));
+        when(router.history()).thenReturn(history);
+        when(history.activeActivation()).thenReturn(active);
+        when(active.activationId()).thenReturn(4L);
+        assertTrue(GenerationWritePolicy.isHistoricalStructure(engine, 3));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 0));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 4));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 5));
+    }
+
+    @Test
+    public void partialNeighborsMayFinishButCompletedHistoricalNeighborRejectsPass() {
+        Engine engine = mock(Engine.class);
+        IrisComplex complex = mock(IrisComplex.class);
+        when(engine.getComplex()).thenReturn(complex);
+        WorldGenLevel region = mock(WorldGenLevel.class);
+        ChunkAccess partial = mock(ChunkAccess.class);
+        when(partial.getPersistedStatus()).thenReturn(ChunkStatus.NOISE);
+        when(region.getChunk(anyInt(), anyInt())).thenReturn(partial);
+        assertTrue(NativeGenerationWriteGuard.allowsDecoration(engine.getComplex()::allowsMantleChunkWrite, region, new ChunkPos(0, 0)));
+        ChunkAccess complete = mock(ChunkAccess.class);
+        when(complete.getPersistedStatus()).thenReturn(ChunkStatus.FULL);
+        when(region.getChunk(1, -1)).thenReturn(complete);
+        assertFalse(NativeGenerationWriteGuard.allowsDecoration(engine.getComplex()::allowsMantleChunkWrite, region, new ChunkPos(0, 0)));
+    }
+
+    @Test
+    public void historicalNoiseMayFinishFeaturesButNeverReplaysNoiseOrCompletedStage() {
+        Engine engine = mock(Engine.class);
+        IrisComplex complex = mock(IrisComplex.class);
+        when(engine.getComplex()).thenReturn(complex);
+        ChunkAccess chunk = mock(ChunkAccess.class);
+        when(chunk.getPos()).thenReturn(new ChunkPos(-2, 3));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.NOISE);
+        assertTrue(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.FEATURES));
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.NOISE));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.FEATURES);
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.FEATURES));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.FULL);
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.SPAWN));
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureFactoryTest.java

@@ -0,0 +1,485 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureStartInjector;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureFactory;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeJigsawMetadata;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.ForcedStructureChunkGenerator;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureTemplatePoolBounds;
+
+import art.arcane.iris.structure.jigsaw.IrisJigsawConfiguration;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import com.mojang.datafixers.util.Either;
+import com.mojang.datafixers.util.Pair;
+import com.mojang.serialization.MapCodec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderOwner;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.Vec3i;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.IntTag;
+import net.minecraft.nbt.ListTag;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.biome.FixedBiomeSource;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.blending.Blender;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.EmptyPoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.ListPoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.SinglePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElementType;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.pools.alias.PoolAliasBinding;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureFactoryTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void genericSourceDoesNotRequireJigsawType() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+
+        Structure configured = NativeStructureFactory.configure(
+                null, source, null, false, 80);
+
+        assertSame(source, configured);
+    }
+
+    @Test
+    public void jigsawOptionsFailClosedForNonJigsawSource() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+
+        assertThrows(IllegalStateException.class, () -> NativeStructureFactory.configure(
+                null, source, new IrisJigsawConfiguration(), false, 80));
+    }
+
+    @Test
+    public void sourceMetadataReadsScalarAndAxisSpecificJigsawRanges() {
+        CompoundTag scalar = new CompoundTag();
+        scalar.putInt("max_distance_from_center", 80);
+        CompoundTag axisSpecific = new CompoundTag();
+        CompoundTag distance = new CompoundTag();
+        distance.putInt("horizontal", 96);
+        distance.putInt("vertical", 64);
+        axisSpecific.put("max_distance_from_center", distance);
+
+        assertEquals(80, NativeJigsawMetadata.sourceDistance(scalar, "horizontal"));
+        assertEquals(80, NativeJigsawMetadata.sourceDistance(scalar, "vertical"));
+        assertEquals(96, NativeJigsawMetadata.sourceDistance(axisSpecific, "horizontal"));
+        assertEquals(64, NativeJigsawMetadata.sourceDistance(axisSpecific, "vertical"));
+    }
+
+    @Test
+    public void sourceMetadataIncludesAdjustBoundingBoxExpansion() {
+        Structure none = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        Structure beardBox = new SwampHutStructure(new Structure.StructureSettings.Builder(HolderSet.empty())
+                .terrainAdapation(TerrainAdjustment.BEARD_BOX)
+                .build());
+
+        assertEquals(0, NativeJigsawMetadata.horizontalReferenceExpansion(none));
+        assertEquals(12, NativeJigsawMetadata.horizontalReferenceExpansion(beardBox));
+    }
+
+    @Test
+    public void templatePoolSpanIncludesWeightedListsFallbacksAndRotations() {
+        StructurePoolElement narrow = inlineElement(30, 8, 70);
+        StructurePoolElement wide = inlineElement(96, 8, 12);
+        ListPoolElement list = new ListPoolElement(
+                List.of(narrow, wide, EmptyPoolElement.INSTANCE),
+                StructureTemplatePool.Projection.RIGID);
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(
+                fallbackHolder,
+                List.of(Pair.of(inlineElement(110, 8, 20), 1)));
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                fallbackHolder,
+                List.of(Pair.of(list, 5), Pair.of(EmptyPoolElement.INSTANCE, 1)));
+        startHolder.bind(start);
+
+        assertEquals(110, NativeStructureTemplatePoolBounds.horizontalSpan(start, null));
+    }
+
+    @Test
+    public void oversizedInlineStartTemplateReportsItsFullSpan() {
+        BoundPoolHolder holder = new BoundPoolHolder("test:oversized");
+        StructureTemplatePool pool = new StructureTemplatePool(
+                holder,
+                List.of(Pair.of(inlineElement(160, 8, 9), 1)));
+        holder.bind(pool);
+
+        assertEquals(160, NativeStructureTemplatePoolBounds.horizontalSpan(pool, null));
+    }
+
+    @Test
+    public void sourceSpanIncludesOnlyAliasesThatCanReplaceTheStartPool() {
+        BoundPoolHolder emptyHolder = new BoundPoolHolder("test:empty");
+        StructureTemplatePool empty = new StructureTemplatePool(emptyHolder, List.of());
+        emptyHolder.bind(empty);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(20, 8, 12), 1)));
+        startHolder.bind(start);
+        BoundPoolHolder replacementHolder = new BoundPoolHolder("test:replacement");
+        StructureTemplatePool replacement = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(30, 8, 12), 1)));
+        replacementHolder.bind(replacement);
+        BoundPoolHolder unrelatedHolder = new BoundPoolHolder("test:unrelated");
+        StructureTemplatePool unrelated = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(200, 8, 12), 1)));
+        unrelatedHolder.bind(unrelated);
+        ResourceKey<StructureTemplatePool> startKey = startHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> replacementKey = replacementHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> unrelatedKey = unrelatedHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> childAlias = ResourceKey.create(
+                Registries.TEMPLATE_POOL, Identifier.parse("test:child_alias"));
+        List<PoolAliasBinding> aliases = List.of(
+                PoolAliasBinding.direct(startKey, replacementKey),
+                PoolAliasBinding.direct(childAlias, unrelatedKey));
+        Map<ResourceKey<StructureTemplatePool>, StructureTemplatePool> pools = Map.of(
+                replacementKey, replacement,
+                unrelatedKey, unrelated);
+
+        assertEquals(30, NativeStructureTemplatePoolBounds.sourceHorizontalSpan(
+                null, start, startKey, aliases, pools::get));
+    }
+
+    @Test
+    public void sourceStartSpanDoesNotIncludeItsFallbackPool() {
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:large_fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(inlineElement(180, 8, 10), 1)));
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:small_start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(inlineElement(24, 8, 10), 1)));
+        startHolder.bind(start);
+
+        assertEquals(180, NativeStructureTemplatePoolBounds.horizontalSpan(start, null));
+        assertEquals(24, NativeStructureTemplatePoolBounds.sourceHorizontalSpan(
+                null, start, startHolder.unwrapKey().orElseThrow(), List.of(), ignored -> null));
+    }
+
+    @Test
+    public void customPoolElementUsesItsBoundingBoxCapability() {
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:custom_fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(fallbackHolder, List.of());
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder poolHolder = new BoundPoolHolder("test:custom");
+        StructureTemplatePool pool = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(new BoundingPoolElement(37, 11), 1)));
+        poolHolder.bind(pool);
+
+        assertEquals(37, NativeStructureTemplatePoolBounds.horizontalSpan(pool, null));
+    }
+
+    @Test
+    public void forcedGeneratorBypassesBiomeEligibilityWithoutFabricatingTerrain() {
+        ChunkGenerator delegate = new TestChunkGenerator();
+        Holder<Biome> biome = Holder.direct((Biome) null);
+        LevelHeightAccessor heightAccessor = LevelHeightAccessor.create(-64, 384);
+        ForcedStructureChunkGenerator generator = new ForcedStructureChunkGenerator(
+                delegate, biome);
+
+        assertEquals(63, generator.getSeaLevel());
+        assertEquals(64, generator.getBaseHeight(
+                0, 0, Heightmap.Types.WORLD_SURFACE_WG, heightAccessor, null));
+        NoiseColumn column = generator.getBaseColumn(
+                0, 0, heightAccessor, null);
+        assertSame(Blocks.STONE, column.getBlock(80).getBlock());
+        assertSame(Blocks.STONE, column.getBlock(81).getBlock());
+        assertNotSame(delegate.getBiomeSource(), generator.getBiomeSource());
+    }
+
+    @Test
+    public void undergroundRelocationMovesGenericPiecesAndReturnsFreshStart() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece piece = new SwampHutPiece(RandomSource.create(17L), 0, 0);
+        StructureStart start = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(piece))
+        );
+
+        StructureStart relocated = NativeStructureVerticalPlacer.relocateToMinY(
+                start, source, -20, LevelHeightAccessor.create(-64, 384));
+
+        assertNotSame(start, relocated);
+        assertEquals(-20, relocated.getPieces().getFirst().getBoundingBox().minY());
+        assertEquals(-20, relocated.getBoundingBox().minY());
+    }
+
+    @Test
+    public void invalidGeneratedStartIsANormalSkippedCandidate() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        StructureStart valid = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(
+                        new SwampHutPiece(RandomSource.create(23L), 0, 0)))
+        );
+
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(
+                StructureStart.INVALID_START));
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(null));
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(
+                new StructureStart(source, new ChunkPos(0, 0), 0,
+                        new PiecesContainer(List.of()))));
+        assertTrue(NativeStructureStartInjector.isUsableGeneratedStart(valid));
+    }
+
+    @Test
+    public void unrepresentableGeneratedContentBecomesAnUnpublishedInvalidStart() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece boundaryPiece = new SwampHutPiece(RandomSource.create(29L), 0, 0);
+        boundaryPiece.move(143 - boundaryPiece.getBoundingBox().maxX(), 0, 0);
+        StructureStart boundary = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(boundaryPiece))
+        );
+        SwampHutPiece oversizedPiece = new SwampHutPiece(RandomSource.create(31L), 0, 0);
+        oversizedPiece.move(144 - oversizedPiece.getBoundingBox().maxX(), 0, 0);
+        StructureStart oversized = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(oversizedPiece))
+        );
+
+        StructureStart boundaryResult = NativeStructureReferenceEnvelope.wrapForPublication(
+                boundary, source, 0, new IrisStructureTerrain(), "test:boundary_content");
+
+        StructureStart result = NativeStructureReferenceEnvelope.wrapForPublication(
+                oversized, source, 0,
+                new IrisStructureTerrain(),
+                "test:oversized_content");
+
+        assertTrue(boundaryResult.isValid());
+        assertSame(StructureStart.INVALID_START, result);
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(result));
+        assertEquals(1, oversized.getPieces().size());
+    }
+
+    private static final class TestChunkGenerator extends ChunkGenerator {
+        private TestChunkGenerator() {
+            super(new FixedBiomeSource(Holder.direct((Biome) null)));
+        }
+
+        @Override
+        protected MapCodec<? extends ChunkGenerator> codec() {
+            return MapCodec.unit(this);
+        }
+
+        @Override
+        public void applyCarvers(WorldGenRegion region, long seed, RandomState randomState,
+                                 BiomeManager biomeManager, StructureManager structureManager,
+                                 ChunkAccess chunk) {
+        }
+
+        @Override
+        public void buildSurface(WorldGenRegion level, StructureManager structureManager,
+                                 RandomState randomState, ChunkAccess protoChunk) {
+        }
+
+        @Override
+        public void spawnOriginalMobs(WorldGenRegion worldGenRegion) {
+        }
+
+        @Override
+        public int getGenDepth() {
+            return 384;
+        }
+
+        @Override
+        public CompletableFuture<ChunkAccess> fillFromNoise(
+                Blender blender, RandomState randomState,
+                StructureManager structureManager, ChunkAccess centerChunk) {
+            return CompletableFuture.completedFuture(centerChunk);
+        }
+
+        @Override
+        public int getSeaLevel() {
+            return 63;
+        }
+
+        @Override
+        public int getMinY() {
+            return -64;
+        }
+
+        @Override
+        public int getBaseHeight(int x, int z, Heightmap.Types type,
+                                 LevelHeightAccessor heightAccessor, RandomState randomState) {
+            return 64;
+        }
+
+        @Override
+        public NoiseColumn getBaseColumn(int x, int z, LevelHeightAccessor heightAccessor,
+                                         RandomState randomState) {
+            BlockState[] states = new BlockState[heightAccessor.getHeight()];
+            for (int index = 0; index < states.length; index++) {
+                states[index] = Blocks.STONE.defaultBlockState();
+            }
+            return new NoiseColumn(heightAccessor.getMinY(), states);
+        }
+
+        @Override
+        public void addDebugScreenInfo(List<String> result, RandomState randomState,
+                                       BlockPos feetPos) {
+        }
+    }
+
+    private static StructurePoolElement inlineElement(int sizeX, int sizeY, int sizeZ) {
+        StructureTemplate template = new StructureTemplate();
+        CompoundTag tag = new CompoundTag();
+        ListTag size = new ListTag();
+        size.add(IntTag.valueOf(sizeX));
+        size.add(IntTag.valueOf(sizeY));
+        size.add(IntTag.valueOf(sizeZ));
+        tag.put("size", size);
+        template.load(BuiltInRegistries.BLOCK, tag);
+        return new InlinePoolElement(template);
+    }
+
+    private static final class InlinePoolElement extends SinglePoolElement {
+        private final StructureTemplate inlineTemplate;
+
+        private InlinePoolElement(StructureTemplate template) {
+            super(Either.right(template), Holder.direct(new StructureProcessorList(List.of())),
+                    StructureTemplatePool.Projection.RIGID, Optional.<LiquidSettings>empty());
+            inlineTemplate = template;
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return inlineTemplate.getBoundingBox(
+                    new StructurePlaceSettings().setRotation(rotation), position);
+        }
+    }
+
+    private static final class BoundingPoolElement extends StructurePoolElement {
+        private final int width;
+        private final int depth;
+
+        private BoundingPoolElement(int width, int depth) {
+            super(StructureTemplatePool.Projection.RIGID);
+            this.width = width;
+            this.depth = depth;
+        }
+
+        @Override
+        public Vec3i getSize(StructureTemplateManager templateManager, Rotation rotation) {
+            return new Vec3i(width, 1, depth);
+        }
+
+        @Override
+        public List<StructureTemplate.JigsawBlockInfo> getShuffledJigsawBlocks(
+                StructureTemplateManager templateManager, BlockPos position,
+                Rotation rotation, RandomSource random) {
+            return List.of();
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return new BoundingBox(
+                    position.getX(), position.getY(), position.getZ(),
+                    position.getX() + width - 1, position.getY(),
+                    position.getZ() + depth - 1);
+        }
+
+        @Override
+        public boolean place(StructureTemplateManager templateManager,
+                             WorldGenLevel world,
+                             StructureManager structureManager, ChunkGenerator chunkGenerator,
+                             BlockPos position, BlockPos pivot, Rotation rotation,
+                             BoundingBox area, RandomSource random,
+                             LiquidSettings liquidSettings, boolean keepJigsaws) {
+            return true;
+        }
+
+        @Override
+        public StructurePoolElementType<?> getType() {
+            return StructurePoolElementType.EMPTY;
+        }
+    }
+
+    private static final class BoundPoolHolder extends Holder.Reference<StructureTemplatePool> {
+        private BoundPoolHolder(String key) {
+            super(Type.STAND_ALONE, new HolderOwner<>() {
+            }, ResourceKey.create(Registries.TEMPLATE_POOL, Identifier.parse(key)), null);
+        }
+
+        private void bind(StructureTemplatePool pool) {
+            bindValue(pool);
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureGenerationKeysContractTest.java

@@ -0,0 +1,45 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureGenerationKeys;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Vec3i;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadType;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacement;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.Optional;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureGenerationKeysContractTest {
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void frequencyGateUsesMappedAccessorAndRejectsNonPositivePlacements() {
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(0.0F)));
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(-0.1F)));
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(Float.NaN)));
+        assertTrue(NativeStructureGenerationKeys.isEnabledPlacement(placement(0.25F)));
+    }
+
+    private static RandomSpreadStructurePlacement placement(float frequency) {
+        return new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                StructurePlacement.FrequencyReductionMethod.DEFAULT,
+                frequency,
+                1,
+                Optional.empty(),
+                2,
+                1,
+                RandomSpreadType.LINEAR);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureLocatePersistenceTest.java

@@ -0,0 +1,199 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureLocatePersistence;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureLocatePersistenceTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void storageProbeScansEachCandidateOnlyOnce() {
+        AtomicInteger reads = new AtomicInteger();
+        CompoundTag chunk = new CompoundTag();
+        chunk.putInt("DataVersion", SharedConstants.getCurrentVersion().dataVersion().version());
+        chunk.putString("Status", "full");
+        CompoundTag start = new CompoundTag();
+        start.putString("id", "minecraft:village_plains");
+        start.putInt("references", 0);
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", start);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            reads.incrementAndGet();
+                            chunk.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        });
+        ChunkPos chunkPos = new ChunkPos(7, -11);
+
+        assertTrue(budget.acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+        assertTrue(budget.acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+        assertEquals(1, reads.get());
+        assertEquals(1, budget.used());
+    }
+
+    @Test
+    public void legacyStoredChunkIsDatafixedBeforeItsStartIsClassified() {
+        AtomicBoolean datafixed = new AtomicBoolean();
+        CompoundTag legacy = new CompoundTag();
+        legacy.putInt("DataVersion", 100);
+        legacy.putString("Status", "full");
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            legacy.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        },
+                        (level, storedChunk) -> {
+                            datafixed.set(true);
+                            CompoundTag fixed = storedChunk.copy();
+                            fixed.putInt("DataVersion",
+                                    SharedConstants.getCurrentVersion().dataVersion().version());
+                            CompoundTag start = new CompoundTag();
+                            start.putString("id", "minecraft:village_plains");
+                            start.putInt("references", 1);
+                            CompoundTag starts = new CompoundTag();
+                            starts.put("minecraft:village_plains", start);
+                            CompoundTag structures = new CompoundTag();
+                            structures.put("starts", starts);
+                            fixed.put("structures", structures);
+                            return fixed;
+                        });
+
+        assertFalse(budget.acceptsStored(
+                null, new ChunkPos(3, 4), "minecraft:village_plains", true));
+        assertTrue(datafixed.get());
+    }
+
+    @Test
+    public void partialDatafixFailureFallsBackToSelectedChunkVerification() {
+        CompoundTag legacy = new CompoundTag();
+        legacy.putInt("DataVersion", 100);
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            legacy.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        },
+                        (level, storedChunk) -> {
+                            throw new IllegalStateException("broken partial datafix");
+                        });
+
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(9, -2), "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void missingStartsContainerFallsBackToSelectedChunkVerification() {
+        CompoundTag chunk = currentChunk();
+        NativeStructureLocatePersistence.ProbeBudget budget = budget(chunk);
+
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(5, 8), "minecraft:village_plains", false));
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(5, 8), "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void presentEmptyStartsContainerRejectsTheCandidateWithoutLoading() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", new CompoundTag());
+        chunk.put("structures", structures);
+        NativeStructureLocatePersistence.ProbeBudget budget = budget(chunk);
+
+        assertFalse(budget.acceptsStored(
+                null, new ChunkPos(-3, 2), "minecraft:village_plains", false));
+    }
+
+    @Test
+    public void collisionTombstoneIsRejectedForNormalAndUnexploredLocate() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag tombstone = new CompoundTag();
+        tombstone.putString("id", "INVALID");
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", tombstone);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        ChunkPos chunkPos = new ChunkPos(12, -9);
+
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", false));
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void malformedNonCompoundStartIsRejectedWithoutLoading() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag starts = new CompoundTag();
+        starts.putInt("minecraft:village_plains", 1);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+
+        assertFalse(budget(chunk).acceptsStored(
+                null, new ChunkPos(1, 1), "minecraft:village_plains", false));
+    }
+
+    @Test
+    public void referencedStoredStartIsOnlyRejectedForUnexploredLocate() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag start = new CompoundTag();
+        start.putString("id", "minecraft:village_plains");
+        start.putInt("references", 1);
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", start);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        ChunkPos chunkPos = new ChunkPos(-4, -7);
+
+        assertTrue(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", false));
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+    }
+
+    private static CompoundTag currentChunk() {
+        CompoundTag chunk = new CompoundTag();
+        chunk.putInt("DataVersion", SharedConstants.getCurrentVersion().dataVersion().version());
+        return chunk;
+    }
+
+    private static NativeStructureLocatePersistence.ProbeBudget budget(CompoundTag chunk) {
+        return new NativeStructureLocatePersistence.ProbeBudget(
+                512,
+                (chunkPos, visitor) -> {
+                    chunk.acceptAsRoot(visitor);
+                    return CompletableFuture.completedFuture(null);
+                });
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureOwnershipFingerprintTest.java

@@ -0,0 +1,345 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceRepair;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureOwnershipFingerprint;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.nativegen.IrisNativeStructure;
+import art.arcane.iris.structure.placement.IrisStructurePlacement;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.Vec3i;
+import net.minecraft.nbt.ListTag;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.LegacyRandomSource;
+import net.minecraft.world.level.levelgen.RandomSupport;
+import net.minecraft.world.level.levelgen.WorldgenRandom;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElementType;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureOwnershipFingerprintTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void monumentFingerprintSurvivesSourceYRegenerationWithoutSyntheticPieces() {
+        long seed = 8372619L;
+        ChunkPos origin = new ChunkPos(9, -4);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart generated = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                generated, 0, 80, -64, 320);
+        int alignedLocatorY = NativeStructureOwnershipFingerprint.locatorY(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.FORCE_CARVE)
+                .setHorizontalPadding(24);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                structure,
+                0,
+                terrain);
+        String beforeReload = NativeStructureOwnershipFingerprint.fingerprint(
+                "minecraft:monument", wrapped);
+
+        ListTag serializedPieces = (ListTag) new PiecesContainer(wrapped.getPieces()).save(null);
+        PiecesContainer loadedPieces = PiecesContainer.load(serializedPieces, null);
+        assertEquals(1, loadedPieces.pieces().size());
+        assertTrue(loadedPieces.pieces().getFirst()
+                instanceof OceanMonumentPieces.MonumentBuilding);
+        PiecesContainer regeneratedPieces = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                origin, seed, loadedPieces);
+        StructureStart reloaded = new StructureStart(structure, origin, 0, regeneratedPieces);
+        String afterReload = NativeStructureOwnershipFingerprint.fingerprint(
+                "minecraft:monument", reloaded);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", wrapped, NativeStructureReferenceEnvelope.referenceBounds(wrapped, structure, terrain)), plan(origin, NativeStructureReferenceEnvelope.contentBounds(wrapped).minY()));
+
+        assertEquals(beforeReload, afterReload);
+        assertTrue(NativeStructureOwnershipFingerprint.matches(ownership, reloaded));
+        assertNotEquals(alignedLocatorY, NativeStructureOwnershipFingerprint.locatorY(reloaded));
+        assertEquals(alignedLocatorY, ownership.locatorY());
+        assertEquals(1, reloaded.getPieces().size());
+        assertEquals(1, wrapped.getPieces().size());
+    }
+
+    @Test
+    public void sameKeyAndOriginStillRequiresMatchingContentIdentity() {
+        long seed = 18273L;
+        ChunkPos origin = new ChunkPos(2, 3);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart expected = monumentStart(structure, origin, seed);
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", expected, expected.getBoundingBox()), plan(origin, NativeStructureReferenceEnvelope.contentBounds(expected).minY()));
+
+        assertFalse(NativeStructureOwnershipFingerprint.matches(ownership, moved));
+    }
+
+    @Test
+    public void persistedEnvelopeRepairsReloadedMonumentReferenceOutsideLiveBounds() {
+        long seed = 772931L;
+        ChunkPos origin = new ChunkPos(4, -7);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart generated = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                generated, 0, 80, -64, 320);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.FORCE_CARVE)
+                .setHorizontalPadding(24);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                structure,
+                0,
+                terrain);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", wrapped, NativeStructureReferenceEnvelope.referenceBounds(wrapped, structure, terrain)), plan(origin, NativeStructureReferenceEnvelope.contentBounds(wrapped).minY()));
+        PiecesContainer regeneratedPieces = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                origin, seed, new PiecesContainer(wrapped.getPieces()));
+        StructureStart reloaded = new StructureStart(structure, origin, 0, regeneratedPieces);
+        ChunkPos target = outsideLiveBounds(ownership, reloaded);
+
+        assertNotNull(target);
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                target, "minecraft:monument", reloaded, ownership));
+        assertFalse(NativeStructureReferenceRepair.requiresReference(
+                target, "minecraft:monument", reloaded, null));
+    }
+
+    @Test
+    public void overlappingManualStartsSixteenChunksApartRemainIndependentlyReferenced() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos westOrigin = new ChunkPos(0, 0);
+        ChunkPos eastOrigin = new ChunkPos(16, 0);
+        StructureStart west = monumentStart(structure, westOrigin, 317L);
+        StructureStart east = monumentStart(structure, eastOrigin, 941L);
+        west.getPieces().getFirst().move(112, 0, 0);
+        east.getPieces().getFirst().move(-96, 0, 0);
+        NativeStructureOwnershipRecord westOwnership = ownership(westOrigin, west, structure);
+        NativeStructureOwnershipRecord eastOwnership = ownership(eastOrigin, east, structure);
+        ChunkPos shared = new ChunkPos(8, 0);
+
+        assertTrue(NativeStructureReferenceEnvelope.contentBounds(west).intersects(
+                NativeStructureReferenceEnvelope.contentBounds(east)));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", west, westOwnership));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", east, eastOwnership));
+    }
+
+    @Test
+    public void denseAdjacentManualStartsDoNotSuppressEachOther() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos firstOrigin = new ChunkPos(0, 0);
+        ChunkPos secondOrigin = new ChunkPos(1, 0);
+        StructureStart first = monumentStart(structure, firstOrigin, 17L);
+        StructureStart second = monumentStart(structure, secondOrigin, 23L);
+        NativeStructureOwnershipRecord firstOwnership = ownership(firstOrigin, first, structure);
+        NativeStructureOwnershipRecord secondOwnership = ownership(secondOrigin, second, structure);
+        ChunkPos shared = new ChunkPos(0, 0);
+
+        assertTrue(NativeStructureReferenceEnvelope.contentBounds(first).intersects(
+                NativeStructureReferenceEnvelope.contentBounds(second)));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", first, firstOwnership));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", second, secondOwnership));
+    }
+
+    @Test
+    public void customPoolElementIdentityDoesNotDependOnProcessLocalToString() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos origin = new ChunkPos(3, -2);
+        StructureStart first = poolStart(structure, origin, new IdentityStringPoolElement());
+        StructureStart reloaded = poolStart(structure, origin, new IdentityStringPoolElement());
+
+        assertEquals(
+                NativeStructureOwnershipFingerprint.fingerprint("test:custom_pool", first),
+                NativeStructureOwnershipFingerprint.fingerprint("test:custom_pool", reloaded));
+    }
+
+    @Test
+    public void namedPoolTemplateRemainsPartOfTheStableFingerprint() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos origin = new ChunkPos(3, -2);
+        StructurePoolElement firstElement = StructurePoolElement.single("test:first")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        StructurePoolElement secondElement = StructurePoolElement.single("test:second")
+                .apply(StructureTemplatePool.Projection.RIGID);
+
+        assertNotEquals(
+                NativeStructureOwnershipFingerprint.fingerprint(
+                        "test:named_pool", poolStart(structure, origin, firstElement)),
+                NativeStructureOwnershipFingerprint.fingerprint(
+                        "test:named_pool", poolStart(structure, origin, secondElement)));
+    }
+
+    private static StructureStart monumentStart(OceanMonumentStructure structure,
+                                                  ChunkPos origin, long seed) {
+        WorldgenRandom random = new WorldgenRandom(
+                new LegacyRandomSource(RandomSupport.generateUniqueSeed()));
+        random.setLargeFeatureSeed(seed, origin.x(), origin.z());
+        Direction orientation = Direction.Plane.HORIZONTAL.getRandomDirection(random);
+        OceanMonumentPieces.MonumentBuilding building = new OceanMonumentPieces.MonumentBuilding(
+                random,
+                origin.getMinBlockX() - 29,
+                origin.getMinBlockZ() - 29,
+                orientation
+        );
+        return new StructureStart(
+                structure,
+                origin,
+                0,
+                new PiecesContainer(List.of(building))
+        );
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin, int baseY) {
+        IrisNativeStructure source = new IrisNativeStructure()
+                .setStructure("minecraft:monument")
+                .setWeight(1);
+        IrisStructurePlacement placement = new IrisStructurePlacement()
+                .setPlacementId("monument-test")
+                .setNativeStructures(new KList<IrisNativeStructure>().qadd(source));
+        return new NativeStructureStartPlan(
+                placement,
+                source,
+                origin.x(),
+                origin.z(),
+                baseY
+        );
+    }
+
+    private static NativeStructureOwnershipRecord ownership(
+            ChunkPos origin, StructureStart start, OceanMonumentStructure structure) {
+        return NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", start, NativeStructureReferenceEnvelope.referenceBounds(
+                        start, structure, new IrisStructureTerrain())), plan(origin, NativeStructureReferenceEnvelope.contentBounds(start).minY()));
+    }
+
+    private static StructureStart poolStart(
+            OceanMonumentStructure structure, ChunkPos origin, StructurePoolElement element) {
+        BlockPos position = new BlockPos(
+                origin.getMiddleBlockX(), 64, origin.getMiddleBlockZ());
+        PoolElementStructurePiece piece = new PoolElementStructurePiece(
+                null, element, position, 0, Rotation.NONE,
+                new BoundingBox(position), LiquidSettings.APPLY_WATERLOGGING);
+        return new StructureStart(
+                structure, origin, 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static final class IdentityStringPoolElement extends StructurePoolElement {
+        private IdentityStringPoolElement() {
+            super(StructureTemplatePool.Projection.RIGID);
+        }
+
+        @Override
+        public Vec3i getSize(StructureTemplateManager templateManager, Rotation rotation) {
+            return new Vec3i(1, 1, 1);
+        }
+
+        @Override
+        public List<StructureTemplate.JigsawBlockInfo> getShuffledJigsawBlocks(
+                StructureTemplateManager templateManager, BlockPos position,
+                Rotation rotation, RandomSource random) {
+            return List.of();
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return new BoundingBox(position);
+        }
+
+        @Override
+        public boolean place(StructureTemplateManager templateManager,
+                             WorldGenLevel world, StructureManager structureManager,
+                             ChunkGenerator chunkGenerator, BlockPos position, BlockPos pivot,
+                             Rotation rotation, BoundingBox area, RandomSource random,
+                             LiquidSettings liquidSettings, boolean keepJigsaws) {
+            return true;
+        }
+
+        @Override
+        public StructurePoolElementType<?> getType() {
+            return StructurePoolElementType.EMPTY;
+        }
+
+        @Override
+        public String toString() {
+            return "IdentityStringPoolElement@"
+                    + Integer.toHexString(System.identityHashCode(this));
+        }
+    }
+
+    private static ChunkPos outsideLiveBounds(NativeStructureOwnershipRecord ownership,
+                                              StructureStart start) {
+        for (int chunkX = ownership.referenceMinChunkX();
+             chunkX <= ownership.referenceMaxChunkX(); chunkX++) {
+            for (int chunkZ = ownership.referenceMinChunkZ();
+                 chunkZ <= ownership.referenceMaxChunkZ(); chunkZ++) {
+                ChunkPos candidate = new ChunkPos(chunkX, chunkZ);
+                if (!start.getBoundingBox().intersects(
+                        candidate.getMinBlockX(), candidate.getMinBlockZ(),
+                        candidate.getMaxBlockX(), candidate.getMaxBlockZ())) {
+                    return candidate;
+                }
+            }
+        }
+        return null;
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureOwnershipRecoveryTest.java

@@ -0,0 +1,327 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructureOwnershipRecordView;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureOwnershipRecovery;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureOwnershipFingerprint;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.placement.StructurePlacementGrid;
+import art.arcane.iris.structure.nativegen.IrisNativeStructure;
+import art.arcane.iris.structure.placement.IrisStructurePlacement;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.LegacyRandomSource;
+import net.minecraft.world.level.levelgen.RandomSupport;
+import net.minecraft.world.level.levelgen.WorldgenRandom;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureOwnershipRecoveryTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void missingSidecarRecoversExactPolicyEnvelopeAndLocatorAfterReload() {
+        long seed = 5519231L;
+        ChunkPos origin = new ChunkPos(7, -5);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                expected, 0, 80, -64, 320);
+        int expectedLocatorY = NativeStructureOwnershipFingerprint.locatorY(expected);
+        NativeStructureStartPlan plan = plan(origin, "recovery-exact", 24);
+        StructureStart reloaded = new StructureStart(
+                structure,
+                origin,
+                expected.getReferences(),
+                OceanMonumentStructure.regeneratePiecesAfterLoad(
+                        origin, seed, new PiecesContainer(expected.getPieces()))
+        );
+
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, reloaded,
+                        plan, expected, false, NativeStructureOwnershipRecord::capture);
+
+        assertNotNull(recovered);
+        assertEquals(StructurePlacementGrid.placementIdentity(plan.placement()),
+                recovered.placementIdentity());
+        assertEquals(expectedLocatorY, recovered.locatorY());
+        assertNotEquals(NativeStructureOwnershipFingerprint.locatorY(reloaded),
+                recovered.locatorY());
+        assertEquals(StructureTerrainMode.FORCE_CARVE,
+                recovered.restoredDecision().terrain().resolvedMode());
+        assertEquals(24, recovered.restoredDecision().terrain().getHorizontalPadding());
+        assertTrue(recovered.referenceMinChunkX()
+                < NativeStructureReferenceEnvelope.contentBounds(reloaded).minX() >> 4);
+    }
+
+    @Test
+    public void naturalSameKeyStartRemainsUnownedWhenOriginIsAmbiguous() {
+        long seed = 22817L;
+        ChunkPos origin = new ChunkPos(-3, 6);
+        OceanMonumentStructure structure = structure();
+        StructureStart natural = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(origin, "natural-ambiguous", 0);
+
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, natural,
+                        plan, natural, true, NativeStructureOwnershipRecord::capture);
+
+        assertNull(recovered);
+    }
+
+    @Test
+    public void changedPlacementIdentityOrGeometryCannotRecoverOwnership() {
+        long seed = 991723L;
+        ChunkPos origin = new ChunkPos(2, 4);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        StructureStart changedGeometry = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : changedGeometry.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+        NativeStructureStartPlan originalIdentity = plan(
+                origin, "original-identity", 0);
+        NativeStructureStartPlan changedIdentity = plan(
+                new ChunkPos(origin.x() + 1, origin.z()), "changed-identity", 0);
+
+        assertNotEquals(
+                StructurePlacementGrid.placementIdentity(originalIdentity.placement()),
+                StructurePlacementGrid.placementIdentity(changedIdentity.placement()));
+        assertNull(NativeStructureOwnershipRecovery.proveCandidate(
+                "minecraft:monument", structure, expected,
+                changedIdentity, expected, false, NativeStructureOwnershipRecord::capture));
+        assertNull(NativeStructureOwnershipRecovery.proveCandidate(
+                "minecraft:monument", structure, changedGeometry,
+                plan(origin, "geometry-check", 0), expected, false, NativeStructureOwnershipRecord::capture));
+    }
+
+    @Test
+    public void recoveredEnvelopeStillRequiresExactFingerprint() {
+        long seed = 81337L;
+        ChunkPos origin = new ChunkPos(-8, -9);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, expected,
+                        plan(origin, "fingerprint-check", 16), expected, false, NativeStructureOwnershipRecord::capture);
+        assertNotNull(recovered);
+
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(0, 0, 1);
+        }
+
+        assertFalse(NativeStructureOwnershipFingerprint.matches(recovered, moved));
+    }
+
+    @Test
+    public void staleVacuumEnvelopeRefreshesWithoutReplacingOwnershipIdentity() {
+        String structureKey = "minecraft:monument";
+        long seed = 648231L;
+        ChunkPos origin = new ChunkPos(5, -6);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(
+                origin, "vacuum-envelope-refresh", StructureTerrainMode.VACUUM, 0);
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(start);
+        NativeStructureOwnershipRecord stale = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, content), plan);
+
+        NativeStructureOwnershipRecord refreshed =
+                NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                        structureKey, structure, start, stale);
+
+        assertNotNull(refreshed);
+        assertNotEquals(stale, refreshed);
+        assertEquals(stale.schema(), refreshed.schema());
+        assertEquals(stale.ownershipKey(), refreshed.ownershipKey());
+        assertEquals(stale.placementIdentity(), refreshed.placementIdentity());
+        assertEquals(stale.baseY(), refreshed.baseY());
+        assertEquals(stale.locatorY(), refreshed.locatorY());
+        assertEquals(stale.contentFingerprint(), refreshed.contentFingerprint());
+        assertEquals(stale.decision(), refreshed.decision());
+        assertEquals(StructureTerrainMode.VACUUM,
+                refreshed.restoredDecision().terrain().resolvedMode());
+        BoundingBox expected = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        assertEquals(expected.minX() >> 4, refreshed.referenceMinChunkX());
+        assertEquals(expected.maxX() >> 4, refreshed.referenceMaxChunkX());
+        assertEquals(expected.minZ() >> 4, refreshed.referenceMinChunkZ());
+        assertEquals(expected.maxZ() >> 4, refreshed.referenceMaxChunkZ());
+        assertTrue(hasExpandedCoverage(stale, refreshed));
+        assertSame(refreshed, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, refreshed));
+    }
+
+    @Test
+    public void staleEnvelopeCannotRefreshAgainstDifferentContent() {
+        String structureKey = "minecraft:monument";
+        long seed = 412987L;
+        ChunkPos origin = new ChunkPos(-2, 7);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(
+                origin, "vacuum-content-check", StructureTerrainMode.VACUUM, 0);
+        NativeStructureOwnershipRecord stale = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, expected, NativeStructureReferenceEnvelope.contentBounds(expected)), plan);
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+
+        assertNull(NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, moved, stale));
+    }
+
+    @Test
+    public void currentNonVacuumEnvelopeRemainsThePersistedAuthority() {
+        String structureKey = "minecraft:monument";
+        long seed = 927451L;
+        ChunkPos origin = new ChunkPos(3, 8);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(origin, "current-force-carve", 24);
+        BoundingBox envelope = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, envelope), plan);
+
+        assertSame(ownership, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, ownership));
+    }
+
+    @Test
+    public void clippedVacuumEnvelopeRemainsStableAtTheReferenceLimit() {
+        String structureKey = "minecraft:monument";
+        long seed = 381729L;
+        ChunkPos origin = new ChunkPos(0, 0);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        BoundingBox initial = NativeStructureReferenceEnvelope.contentBounds(start);
+        int maximumReferenceBlockX = ((origin.x()
+                + StructureOwnershipRecordView.MAX_REFERENCE_DISTANCE_CHUNKS) << 4) + 15;
+        int shiftX = maximumReferenceBlockX - initial.maxX();
+        for (StructurePiece piece : start.getPieces()) {
+            piece.move(shiftX, 0, 0);
+        }
+        NativeStructureStartPlan plan = plan(
+                origin, "clipped-vacuum", StructureTerrainMode.VACUUM, 0);
+        BoundingBox envelope = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, envelope), plan);
+
+        assertEquals(origin.x() + StructureOwnershipRecordView.MAX_REFERENCE_DISTANCE_CHUNKS,
+                ownership.referenceMaxChunkX());
+        assertSame(ownership, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, ownership));
+    }
+
+    private static OceanMonumentStructure structure() {
+        return new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+    }
+
+    private static StructureStart monumentStart(OceanMonumentStructure structure,
+                                                 ChunkPos origin, long seed) {
+        WorldgenRandom random = new WorldgenRandom(
+                new LegacyRandomSource(RandomSupport.generateUniqueSeed()));
+        random.setLargeFeatureSeed(seed, origin.x(), origin.z());
+        Direction orientation = Direction.Plane.HORIZONTAL.getRandomDirection(random);
+        OceanMonumentPieces.MonumentBuilding building =
+                new OceanMonumentPieces.MonumentBuilding(
+                        random,
+                        origin.getMinBlockX() - 29,
+                        origin.getMinBlockZ() - 29,
+                        orientation
+                );
+        return new StructureStart(
+                structure, origin, 0, new PiecesContainer(List.of(building)));
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin,
+                                                  String placementId,
+                                                  int horizontalPadding) {
+        return plan(origin, placementId,
+                StructureTerrainMode.FORCE_CARVE, horizontalPadding);
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin,
+                                                  String placementId,
+                                                  StructureTerrainMode terrainMode,
+                                                  int horizontalPadding) {
+        IrisNativeStructure source = new IrisNativeStructure()
+                .setStructure("minecraft:monument")
+                .setWeight(1);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(terrainMode)
+                .setHorizontalPadding(horizontalPadding);
+        IrisStructurePlacement placement = new IrisStructurePlacement()
+                .setPlacementId(placementId)
+                .setTerrain(terrain)
+                .setNativeStructures(new KList<IrisNativeStructure>().qadd(source));
+        return new NativeStructureStartPlan(
+                placement,
+                source,
+                origin.x(),
+                origin.z(),
+                NativeStructureReferenceEnvelope.contentBounds(
+                        monumentStart(structure(), origin, 1L)).minY()
+        );
+    }
+
+    private static boolean hasExpandedCoverage(
+            NativeStructureOwnershipRecord stale,
+            NativeStructureOwnershipRecord refreshed) {
+        for (int chunkX = refreshed.referenceMinChunkX();
+             chunkX <= refreshed.referenceMaxChunkX(); chunkX++) {
+            for (int chunkZ = refreshed.referenceMinChunkZ();
+                 chunkZ <= refreshed.referenceMaxChunkZ(); chunkZ++) {
+                if (!stale.covers(chunkX, chunkZ)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorEncaseTest.java

@@ -0,0 +1,542 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructurePalette;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructureTerrainSettings;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureTerrainIntegrator;
+
+import art.arcane.iris.generation.terrain.IrisMaterialPalette;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.iris.structure.placement.IrisStructureYBand;
+import art.arcane.volmlib.util.math.RNG;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.dimension.BuiltinDimensionTypes;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockIgnoreProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.BitSet;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorEncaseTest {
+    private static final long TEST_SEED = 1234L;
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void encaseFillsAirAndLiquidWithoutOverwritingExistingTerrain() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 1, bounds.minY() - 1, bounds.minZ() - 1,
+                bounds.maxX() + 1, bounds.maxY() + 1, bounds.maxZ() + 1);
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        put(blocks, bounds.minX(), bounds.minY(), bounds.minZ(), Blocks.DIRT.defaultBlockState());
+        put(blocks, bounds.maxX(), bounds.minY(), bounds.maxZ(), Blocks.WATER.defaultBlockState());
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "minecraft:stronghold", start,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.ENCASE)
+                        .setHorizontalPadding(1)
+                        .setCeilingPadding(1)
+                        .setFloorPadding(1),
+                null);
+
+        assertEquals(Blocks.DIRT.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.maxX(), bounds.minY(), bounds.maxZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 1, bounds.minY() - 1, bounds.minZ() - 1));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.maxX() + 1, bounds.maxY() + 1, bounds.maxZ() + 1));
+    }
+
+    @Test
+    public void defaultEncasePaletteSplitsStoneAboveZeroAndDeepslateBelow() {
+        StructureStart start = start(TerrainAdjustment.BURY, -1);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), bounds, "minecraft:stronghold", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.ENCASE),
+                null);
+
+        assertEquals(-1, bounds.minY());
+        assertEquals(Blocks.DEEPSLATE.defaultBlockState(),
+                state(blocks, bounds.minX(), -1, bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), 0, bounds.minZ()));
+    }
+
+    @Test
+    public void defaultEncaseMaterialFollowsVanillaDimensionTerrain() {
+        assertEquals(Blocks.NETHERRACK.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.NETHER, 64));
+        assertEquals(Blocks.END_STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.END, 64));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.OVERWORLD, 64));
+    }
+
+    @Test
+    public void sourceEncaseMaterialFollowsNearbyIrisTerrain() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(4, 64, 8);
+        put(blocks, fill.getX() + 3, fill.getY(), fill.getZ(), Blocks.TUFF.defaultBlockState());
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(world(blocks), fill));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotIgnoresPreviouslyDecoratedAdjacentChunks() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(0, 64, 8);
+        put(blocks, -1, 64, 8, Blocks.OAK_PLANKS.defaultBlockState());
+        put(blocks, 3, 64, 8, Blocks.TUFF.defaultBlockState());
+        WorldGenLevel world = world(blocks);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                sourceSnapshot(world, new BoundingBox(0, 64, 0, 15, 64, 15));
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(
+                        world, fill, sourceTerrain));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotIsStableAcrossEarlierFillsInTheSameChunk() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(0, 64, 8);
+        put(blocks, 3, 64, 8, Blocks.TUFF.defaultBlockState());
+        WorldGenLevel world = world(blocks);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                sourceSnapshot(world, new BoundingBox(0, 64, 0, 15, 64, 15));
+        put(blocks, 1, 64, 8, Blocks.OAK_PLANKS.defaultBlockState());
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(
+                        world, fill, sourceTerrain));
+    }
+
+    @Test
+    public void sourceMaterialRejectsStructureBlocksAndOresBeforeDimensionFallback() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(4, -20, 8);
+        put(blocks, 3, -20, 8, Blocks.OAK_PLANKS.defaultBlockState());
+        put(blocks, 5, -20, 8, Blocks.STONE_BRICKS.defaultBlockState());
+        put(blocks, 4, -20, 7, Blocks.IRON_ORE.defaultBlockState());
+
+        assertEquals(Blocks.DEEPSLATE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(world(blocks), fill));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotOnlyAllocatesActualFillLayers() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox area = new BoundingBox(0, -2032, 0, 15, 2030, 15);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                NativeStructureTerrainIntegrator.captureSourceTerrain(
+                        world(new HashMap<>()), area,
+                        List.of(new NativeStructureTerrainIntegrator.TerrainTarget(
+                                "test:bounded-snapshot", start,
+                                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE))));
+
+        assertNotNull(sourceTerrain);
+        assertEquals(23 * 16 * 16, sourceTerrain.sampledCells());
+    }
+
+    @Test
+    public void customDimensionKeyUsesRegisteredVanillaDimensionType() {
+        ResourceKey<Level> customDimension = ResourceKey.create(
+                Registries.DIMENSION, Identifier.parse("iris:custom_nether"));
+
+        assertEquals(Blocks.NETHERRACK.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(
+                        customDimension, BuiltinDimensionTypes.NETHER, null, 64));
+        assertEquals(Blocks.END_STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(
+                        customDimension, BuiltinDimensionTypes.END, null, 64));
+    }
+
+    @Test
+    public void configuredEncasePaletteReplacesTheDefaultMaterial() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        IrisMaterialPalette palette = new IrisMaterialPalette().qclear().qadd("minecraft:tuff");
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), bounds, "minecraft:stronghold", start,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.ENCASE)
+                        .setEncasePalette(palette),
+                NativeStructurePostProcessorEncaseTest::tuffBlock);
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.minY(), bounds.minZ()));
+    }
+
+    @Test
+    public void omittedTerrainConfigurationRetainsSourceSemantics() {
+        for (TerrainAdjustment adjustment : TerrainAdjustment.values()) {
+            StructureTerrainSettings resolved = NativeStructureTerrainIntegrator.resolveNativeTerrain(
+                    start(adjustment, 64), null);
+
+            assertEquals(StructureTerrainMode.SOURCE, resolved.resolvedMode());
+        }
+    }
+
+    @Test
+    public void sourceBuryUsesTheVanillaSixByTwelveInfluenceEnvelope() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        int groundY = bounds.minY();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 7, groundY - 13, bounds.minZ(),
+                bounds.maxX(), groundY + 13, bounds.maxZ());
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "test:bury", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE), null);
+
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 5, groundY, bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 11, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 6, groundY, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 12, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 7, groundY, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 13, bounds.minZ()));
+    }
+
+    @Test
+    public void sourceEncapsulateWrapsTheFullPieceBounds() {
+        StructureStart start = start(TerrainAdjustment.ENCAPSULATE, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 13, bounds.minY(), bounds.minZ(),
+                bounds.maxX(), bounds.maxY() + 13, bounds.maxZ());
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "test:encapsulate", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE), null);
+
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 11, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 11, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 12, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 12, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 13, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 13, bounds.minZ()));
+    }
+
+    @Test
+    public void sourceTerrainDensityOnlyUsesRigidPoolPieces() {
+        PoolElementStructurePiece terrainMatching = poolPiece(StructureTemplatePool.Projection.TERRAIN_MATCHING);
+        PoolElementStructurePiece rigid = poolPiece(StructureTemplatePool.Projection.RIGID);
+
+        assertFalse(NativeStructureTerrainIntegrator.isSourceRigidPiece(terrainMatching));
+        assertTrue(NativeStructureTerrainIntegrator.isSourceRigidPiece(rigid));
+    }
+
+    @Test
+    public void sourceJunctionTerrainUsesTheStrictLowerTwelveBlockEnvelope() {
+        assertTrue(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -1, 0));
+        assertTrue(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -11, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, 0, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -12, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(12, -1, 0));
+    }
+
+    @Test
+    public void explicitTerrainConfigurationWinsOverAutoEncase() {
+        IrisStructureTerrain configured = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.PRESERVE);
+
+        assertSame(configured, NativeStructureTerrainIntegrator.resolveNativeTerrain(
+                start(TerrainAdjustment.BURY, 64), configured));
+    }
+
+    @Test
+    public void legacyTemplateAirIsClearedAfterEveryTerrainFillPath() {
+        IrisStructureTerrain source = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.SOURCE);
+        IrisStructureTerrain preserve = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.PRESERVE);
+        IrisStructureTerrain encase = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE);
+
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BURY, 64), source));
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BEARD_BOX, 64), source));
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.NONE, 64), encase));
+        assertFalse(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.NONE, 64), source));
+        assertFalse(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BURY, 64), preserve));
+    }
+
+    @Test
+    public void encaseReservesTheNeighborChunkEnvelope() {
+        StructureStart generated = start(TerrainAdjustment.BURY, 64);
+        BoundingBox sourceBounds = generated.getBoundingBox();
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE)
+                .setHorizontalPadding(4);
+
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                generated.getStructure(),
+                0,
+                terrain);
+        BoundingBox referenceBounds = NativeStructureReferenceEnvelope.referenceBounds(
+                wrapped, wrapped.getStructure(), terrain);
+
+        assertEquals(sourceBounds, wrapped.getBoundingBox());
+        assertEquals(content.minX() - 4, referenceBounds.minX());
+        assertEquals(content.maxX() + 4, referenceBounds.maxX());
+        assertEquals(content.minZ() - 4, referenceBounds.minZ());
+        assertEquals(content.maxZ() + 4, referenceBounds.maxZ());
+        assertEquals(generated.getPieces().size(), wrapped.getPieces().size());
+    }
+
+    @Test
+    public void referenceEnvelopeRejectsChunkCoordinateOverflow() {
+        StructureStart generated = start(TerrainAdjustment.NONE, 64);
+        StructureStart extreme = new StructureStart(
+                generated.getStructure(), new ChunkPos(Integer.MAX_VALUE, 0), 0,
+                new PiecesContainer(generated.getPieces()));
+
+        assertThrows(IllegalStateException.class, () ->
+                NativeStructureReferenceEnvelope.referenceBounds(
+                        extreme, extreme.getStructure(), new IrisStructureTerrain()));
+    }
+
+    @Test
+    public void explicitTerrainEnvelopeDoesNotInheritSourceAdjustment() {
+        StructureStart generated = start(TerrainAdjustment.BURY, 64);
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE)
+                .setHorizontalPadding(112);
+
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated, generated.getStructure(), 0, terrain);
+        BoundingBox referenceBounds = NativeStructureReferenceEnvelope.referenceBounds(
+                wrapped, wrapped.getStructure(), terrain);
+
+        assertEquals(content.minX() - 112, referenceBounds.minX());
+        assertEquals(content.maxX() + 112, referenceBounds.maxX());
+    }
+
+    @Test
+    public void yBandRelocatesTheStartMidpointDeterministically() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-120).setMax(-20);
+        StructureStart first = start(TerrainAdjustment.BURY, 64);
+        StructureStart second = start(TerrainAdjustment.BURY, 64);
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                first, -64, -256, 320, true, false, band, (x, z) -> 40);
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                second, -64, -256, 320, true, false, band, (x, z) -> 40);
+
+        BoundingBox bounds = first.getBoundingBox();
+        assertEquals(bounds.minY(), second.getBoundingBox().minY());
+        assertTrue(bounds.minY() >= -120);
+        assertTrue(bounds.maxY() <= -20);
+
+        int repeated = NativeStructureVerticalPlacer.applyVerticalShift(
+                first, -64, -256, 320, true, false, band, (x, z) -> 40);
+        assertEquals(0, repeated);
+    }
+
+    @Test
+    public void yBandClampsWhenTheBandCannotContainTheStructure() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-50).setMax(-45);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                start, 0, -256, 320, true, false, band, (x, z) -> 40);
+
+        BoundingBox bounds = start.getBoundingBox();
+        int midpoint = bounds.minY() + (bounds.maxY() - bounds.minY()) / 2;
+        assertTrue(midpoint >= -50);
+        assertTrue(midpoint <= -45);
+    }
+
+    @Test
+    public void yBandReplacesBothTheBlindShiftAndBurial() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-64).setMax(-64);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getBoundingBox();
+        int height = bounds.maxY() - bounds.minY();
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                start, -200, -256, 320, true, false, band, (x, z) -> 40);
+
+        assertEquals(-64 - height / 2, start.getBoundingBox().minY());
+    }
+
+    @Test
+    public void preserveSourceYWinsOverTheConfiguredBand() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-120).setMax(-20);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        int minY = start.getBoundingBox().minY();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalShift(
+                start, 0, -256, 320, true, true, band, (x, z) -> 40);
+
+        assertEquals(0, offset);
+        assertEquals(minY, start.getBoundingBox().minY());
+    }
+
+    private static BlockState tuffBlock(StructurePalette palette, RNG rng, int x, int y, int z) {
+        assertNotNull(palette);
+        assertNotNull(rng);
+        return Blocks.TUFF.defaultBlockState();
+    }
+
+    private static StructureStart start(TerrainAdjustment adjustment, int minY) {
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(
+                HolderSet.empty(), Map.of(), GenerationStep.Decoration.STRONGHOLDS, adjustment));
+        StructurePiece piece = new DesertPyramidPiece(RandomSource.create(7L), 0, 0);
+        piece.move(0, minY - piece.getBoundingBox().minY(), 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static PoolElementStructurePiece poolPiece(StructureTemplatePool.Projection projection) {
+        BlockPos position = new BlockPos(0, 64, 0);
+        StructurePoolElement element = StructurePoolElement.single(
+                "minecraft:empty",
+                Holder.direct(new StructureProcessorList(List.of(
+                        BlockIgnoreProcessor.STRUCTURE_AND_AIR))),
+                LiquidSettings.APPLY_WATERLOGGING
+        ).apply(projection);
+        return new PoolElementStructurePiece(
+                null,
+                element,
+                position,
+                0,
+                Rotation.NONE,
+                new BoundingBox(position),
+                LiquidSettings.APPLY_WATERLOGGING);
+    }
+
+    private static WorldGenLevel world(Map<BlockPos, BlockState> blocks) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getBlockState")) {
+                BlockPos position = (BlockPos) arguments[0];
+                return state(blocks, position.getX(), position.getY(), position.getZ());
+            }
+            if (methodName.equals("setBlock")) {
+                BlockPos position = (BlockPos) arguments[0];
+                BlockState blockState = (BlockState) arguments[1];
+                put(blocks, position.getX(), position.getY(), position.getZ(), blockState);
+                return true;
+            }
+            if (methodName.equals("getSeed")) {
+                return TEST_SEED;
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "encase-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceSnapshot(
+            WorldGenLevel world, BoundingBox area) {
+        BitSet requiredLayers = new BitSet(area.getYSpan());
+        requiredLayers.set(0, area.getYSpan());
+        return NativeStructureTerrainIntegrator.SourceTerrainSnapshot.capture(
+                world, area, requiredLayers);
+    }
+
+    private static void put(Map<BlockPos, BlockState> blocks,
+                           int x, int y, int z, BlockState state) {
+        blocks.put(new BlockPos(x, y, z), state);
+    }
+
+    private static BlockState state(Map<BlockPos, BlockState> blocks, int x, int y, int z) {
+        return blocks.getOrDefault(new BlockPos(x, y, z), Blocks.AIR.defaultBlockState());
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorMonumentTest.java

@@ -0,0 +1,206 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorMonumentTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void vanillaSeaLevelKeepsTheVanillaMonumentHeight() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 63, -64, 320, false, false, null, (x, z) -> 0);
+
+        assertEquals(0, offset);
+        assertEquals(39, start.getBoundingBox().minY());
+        assertEquals(61, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void shiftedSeaLevelMovesTheShellAndEveryRoomTogether() {
+        StructureStart start = monumentStart(1337L);
+        OceanMonumentPieces.MonumentBuilding building = monumentBuilding(start);
+        List<StructurePiece> children = NativeStructureVerticalPlacer.monumentChildPieces(building);
+        int[] childMinY = minimumYs(children);
+        BoundingBox cachedBounds = start.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        assertEquals(-13, offset);
+        assertSame(cachedBounds, start.getBoundingBox());
+        assertEquals(26, building.getBoundingBox().minY());
+        assertEquals(48, building.getBoundingBox().maxY());
+        assertEquals(26, start.getBoundingBox().minY());
+        assertEquals(48, start.getBoundingBox().maxY());
+        assertTrue(children.size() > 20);
+        for (int i = 0; i < children.size(); i++) {
+            assertEquals(childMinY[i] - 13, children.get(i).getBoundingBox().minY());
+        }
+
+        int repeatedOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+        assertEquals(0, repeatedOffset);
+    }
+
+    @Test
+    public void configuredOffsetIsRelativeToTheActualSeaLevel() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 3, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        assertEquals(-10, offset);
+        assertEquals(29, start.getBoundingBox().minY());
+        assertEquals(51, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void referenceEnvelopeDoesNotAddMonumentPieces() {
+        StructureStart start = monumentStart(1337L);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                start,
+                start.getStructure(),
+                0,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.FORCE_CARVE)
+                        .setHorizontalPadding(4));
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                wrapped, "minecraft:monument", 0, 63, -64, 320,
+                false, false, null, (x, z) -> 0);
+
+        assertEquals(0, offset);
+        assertEquals(1, wrapped.getPieces().size());
+    }
+
+    @Test
+    public void vanillaReloadRegenerationIsRealignedBeforePlacement() {
+        long seed = 1337L;
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        StructureStart initial = monumentStart(seed);
+        NativeStructureVerticalPlacer.applyVerticalPlacement(
+                initial, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        PiecesContainer regenerated = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                chunkPos, seed, new PiecesContainer(initial.getPieces()));
+        StructureStart reloaded = new StructureStart(
+                monumentStructure(), chunkPos, 0, regenerated);
+
+        assertEquals(39, reloaded.getBoundingBox().minY());
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                reloaded, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+        assertEquals(-13, offset);
+        assertEquals(26, reloaded.getBoundingBox().minY());
+        assertEquals(48, reloaded.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void neighboringChunkPlacementRealignsReloadedMonumentOnce() throws Exception {
+        long seed = 1337L;
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        StructureStart initial = monumentStart(seed);
+        NativeStructureVerticalPlacer.applyVerticalPlacement(
+                initial, "minecraft:monument", 0, 50, -256, 512,
+                false, false, null, (x, z) -> 0);
+        PiecesContainer regenerated = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                chunkPos, seed, new PiecesContainer(initial.getPieces()));
+        StructureStart reloaded = new StructureStart(
+                monumentStructure(), chunkPos, 0, regenerated);
+        ExecutorService executor = Executors.newFixedThreadPool(8);
+        CountDownLatch release = new CountDownLatch(1);
+        List<Future<?>> futures = new ArrayList<>();
+        try {
+            for (int task = 0; task < 16; task++) {
+                futures.add(executor.submit(() -> {
+                    release.await();
+                    NativeStructureVerticalPlacer.ensureMonumentSeaLevelAlignment(
+                            reloaded, "minecraft:monument", 0, 50, -256, 512);
+                    return null;
+                }));
+            }
+            release.countDown();
+            for (Future<?> future : futures) {
+                future.get();
+            }
+        } finally {
+            executor.shutdownNow();
+        }
+
+        assertEquals(26, reloaded.getBoundingBox().minY());
+        assertEquals(48, reloaded.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void impossibleSeaLevelAlignmentFailsInsteadOfClippingTheMonument() {
+        StructureStart start = monumentStart(1337L);
+        try {
+            NativeStructureVerticalPlacer.applyVerticalPlacement(
+                    start, "minecraft:monument", 0, -50, -64, 320, false, false, null, (x, z) -> 0);
+        } catch (IllegalStateException error) {
+            assertTrue(error.getMessage().contains("cannot align"));
+            return;
+        }
+        throw new AssertionError("Expected an out-of-bounds monument alignment to fail");
+    }
+
+    private static StructureStart monumentStart(long seed) {
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        OceanMonumentPieces.MonumentBuilding building = new OceanMonumentPieces.MonumentBuilding(
+                RandomSource.create(seed), -29, -29, Direction.NORTH);
+        return new StructureStart(
+                monumentStructure(), chunkPos, 0, new PiecesContainer(List.of(building)));
+    }
+
+    private static OceanMonumentStructure monumentStructure() {
+        return new OceanMonumentStructure(new Structure.StructureSettings(HolderSet.empty()));
+    }
+
+    private static OceanMonumentPieces.MonumentBuilding monumentBuilding(StructureStart start) {
+        return (OceanMonumentPieces.MonumentBuilding) start.getPieces().get(0);
+    }
+
+    private static int[] minimumYs(List<StructurePiece> pieces) {
+        int[] ys = new int[pieces.size()];
+        for (int i = 0; i < pieces.size(); i++) {
+            ys[i] = pieces.get(i).getBoundingBox().minY();
+        }
+        return ys;
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorScatteredFeatureTest.java

@@ -0,0 +1,204 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureSurfaceFitter;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReflection;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelAccessor;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.ScatteredFeaturePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.structures.JungleTemplePiece;
+import net.minecraft.world.level.levelgen.structure.structures.JungleTempleStructure;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorScatteredFeatureTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void desertPyramidUsesTheLowestFootprintSurfaceAndLocksVanillaReanchor() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(11L), 0, 0);
+        StructureStart start = desertStart(piece);
+        BoundingBox cachedBounds = start.getBoundingBox();
+        BoundingBox footprint = piece.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null,
+                (x, z) -> x == footprint.maxX() && z == footprint.maxZ() ? 64 : 92);
+
+        assertEquals(1, offset);
+        assertSame(cachedBounds, start.getBoundingBox());
+        assertEquals(65, piece.getBoundingBox().minY());
+        assertEquals(65, start.getBoundingBox().minY());
+        assertTrue(piece.attemptVanillaAlignment(-2));
+        assertEquals(65, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void jungleTempleUsesAverageFootprintSurfaceAndHonorsConfiguredShift() {
+        TestJungleTemplePiece piece = new TestJungleTemplePiece(RandomSource.create(19L), 32, -16);
+        StructureStart start = jungleStart(piece);
+        BoundingBox footprint = piece.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:jungle_pyramid", 4, 63, -64, 320, false, false, null,
+                (x, z) -> x == footprint.minX() && z == footprint.minZ() ? 88 : 70);
+
+        assertEquals(11, offset);
+        assertEquals(75, piece.getBoundingBox().minY());
+        assertTrue(piece.attemptVanillaAlignment());
+        assertEquals(75, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void repeatedAlignmentIsIdempotent() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(23L), 0, 0);
+        StructureStart start = desertStart(piece);
+
+        int initialOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 80);
+        int repeatedOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 80);
+
+        assertEquals(17, initialOffset);
+        assertEquals(0, repeatedOffset);
+        assertEquals(81, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void scatteredAlignmentStaysInsideWorldBounds() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(29L), 0, 0);
+        StructureStart start = desertStart(piece);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 318);
+
+        assertEquals(241, offset);
+        assertEquals(305, piece.getBoundingBox().minY());
+        assertEquals(319, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void scatteredStructuresDoNotOptIntoFullFootprintSurfaceFitting() {
+        TestDesertPyramidPiece desert = new TestDesertPyramidPiece(RandomSource.create(31L), 0, 0);
+        TestJungleTemplePiece jungle = new TestJungleTemplePiece(RandomSource.create(37L), 0, 0);
+        SwampHutPiece swamp = new SwampHutPiece(RandomSource.create(41L), 0, 0);
+        StructureStart desertStart = desertStart(desert);
+        StructureStart jungleStart = jungleStart(jungle);
+        StructureStart swampStart = swampStart(swamp);
+
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(desertStart));
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(jungleStart));
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(swampStart));
+
+        AtomicInteger terrainQueries = new AtomicInteger();
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                swampStart, "minecraft:swamp_hut", 0, 63, -64, 320, false, false, null,
+                (x, z) -> terrainQueries.incrementAndGet());
+        assertEquals(0, offset);
+        assertEquals(0, terrainQueries.get());
+        assertEquals(64, swamp.getBoundingBox().minY());
+    }
+
+    @Test
+    public void scatteredHeightFieldMatchesTheRuntimeContract() {
+        Field field = NativeStructureReflection.resolveScatteredHeightPositionField();
+
+        assertEquals(ScatteredFeaturePiece.class, field.getDeclaringClass());
+        assertEquals(int.class, field.getType());
+        assertTrue(Modifier.isProtected(field.getModifiers()));
+        assertFalse(Modifier.isFinal(field.getModifiers()));
+        assertFalse(Modifier.isStatic(field.getModifiers()));
+        assertTrue(field.trySetAccessible());
+    }
+
+    @Test
+    public void datapackOverridesOfSpecialVanillaIdsUseGenericPlacement() {
+        StructureStart pyramidOverride = swampStart(
+                new SwampHutPiece(RandomSource.create(43L), 0, 0));
+        int pyramidMinY = pyramidOverride.getBoundingBox().minY();
+        int pyramidOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                pyramidOverride, "minecraft:desert_pyramid", 5,
+                63, -64, 320, false, false, null, (x, z) -> 200);
+
+        assertEquals(5, pyramidOffset);
+        assertEquals(pyramidMinY + 5, pyramidOverride.getBoundingBox().minY());
+
+        StructureStart monumentOverride = swampStart(
+                new SwampHutPiece(RandomSource.create(47L), 0, 0));
+        int monumentMinY = monumentOverride.getBoundingBox().minY();
+        NativeStructureVerticalPlacer.ensureMonumentSeaLevelAlignment(
+                monumentOverride, "minecraft:monument", 0, 40, -64, 320);
+
+        assertEquals(monumentMinY, monumentOverride.getBoundingBox().minY());
+    }
+
+    private static StructureStart desertStart(StructurePiece piece) {
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart jungleStart(StructurePiece piece) {
+        Structure structure = new JungleTempleStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart swampStart(StructurePiece piece) {
+        Structure structure = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart start(Structure structure, StructurePiece piece) {
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static final class TestDesertPyramidPiece extends DesertPyramidPiece {
+        private TestDesertPyramidPiece(RandomSource random, int west, int north) {
+            super(random, west, north);
+        }
+
+        private boolean attemptVanillaAlignment(int offset) {
+            return updateHeightPositionToLowestGroundHeight((LevelAccessor) null, offset);
+        }
+    }
+
+    private static final class TestJungleTemplePiece extends JungleTemplePiece {
+        private TestJungleTemplePiece(RandomSource random, int west, int north) {
+            super(random, west, north);
+        }
+
+        private boolean attemptVanillaAlignment() {
+            return updateAverageGroundHeight((LevelAccessor) null, null, 0);
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorVegetationTest.java

@@ -0,0 +1,388 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureSurfaceFitter;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVegetationClearer;
+
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.IdMapper;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorVegetationTest {
+    private static final long TEST_SEED = 1234L;
+    private static final int MIN_Y = -64;
+    private static final int MAX_Y = 319;
+    private static final int GROUND_Y = 64;
+    private static final BoundingBox AREA = new BoundingBox(0, MIN_Y, 0, 15, MAX_Y, 15);
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void canopyAboveTheStructureRoofSurvivesVegetationClearing() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        for (int y = bounds.maxY() - 1; y <= GROUND_Y + 40; y++) {
+            fillLayer(chunk, y, leaves());
+        }
+        write(chunk, 4, bounds.minY() - 1, 4, log());
+
+        clearVegetation(chunk, start);
+
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                assertEquals(leaves(), chunk.getBlockState(new BlockPos(x, GROUND_Y + 40, z)));
+                assertEquals(leaves(), chunk.getBlockState(new BlockPos(x, bounds.maxY() + 1, z)));
+                assertEquals(air(), chunk.getBlockState(new BlockPos(x, bounds.maxY(), z)));
+                assertEquals(air(), chunk.getBlockState(new BlockPos(x, bounds.maxY() - 1, z)));
+            }
+        }
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 1, 4)));
+    }
+
+    @Test
+    public void buriedStructuresPreserveTheForestAboveThem() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, -20);
+        write(chunk, 8, GROUND_Y + 1, 8, log());
+        write(chunk, 8, GROUND_Y + 2, 8, log());
+        write(chunk, 8, GROUND_Y + 3, 8, log());
+        write(chunk, 8, GROUND_Y + 4, 8, leaves());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 1, 8)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 2, 8)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 3, 8)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 4, 8)));
+    }
+
+    @Test
+    public void columnsOutsideThePieceFootprintKeepEveryTreeBlock() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(8, 8, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        int inside = bounds.minY() + 4;
+        write(chunk, 0, inside, 0, log());
+        write(chunk, 0, GROUND_Y + 40, 0, leaves());
+        write(chunk, 12, inside, 12, log());
+        write(chunk, 12, GROUND_Y + 40, 12, leaves());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(0, inside, 0)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(0, GROUND_Y + 40, 0)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(12, inside, 12)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(12, GROUND_Y + 40, 12)));
+    }
+
+    @Test
+    public void clearingStopsAtThePieceEnvelopeBoundaries() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        write(chunk, 4, bounds.maxY() + 1, 4, log());
+        write(chunk, 4, bounds.maxY(), 4, log());
+        write(chunk, 4, bounds.minY() - 1, 4, log());
+        write(chunk, 4, bounds.minY() - 2, 4, log());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(4, bounds.maxY() + 1, 4)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.maxY(), 4)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 1, 4)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 2, 4)));
+    }
+
+    @Test
+    public void overlappingPieceEnvelopesMergeIntoOneClearedRange() {
+        ProtoChunk chunk = chunk();
+        StructureStart low = desertStart(0, 0, GROUND_Y);
+        StructureStart high = desertStart(0, 0, GROUND_Y + 40);
+        int between = GROUND_Y + 20;
+        write(chunk, 4, between, 4, log());
+        write(chunk, 4, high.getBoundingBox().maxY() + 1, 4, log());
+        write(chunk, 4, low.getBoundingBox().minY() - 2, 4, log());
+
+        NativeStructureVegetationClearer.clearIntersectingVegetation(
+                world(chunk), chunk, AREA, List.of(low, high));
+
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, between, 4)));
+        assertEquals(log(), chunk.getBlockState(
+                new BlockPos(4, high.getBoundingBox().maxY() + 1, 4)));
+        assertEquals(log(), chunk.getBlockState(
+                new BlockPos(4, low.getBoundingBox().minY() - 2, 4)));
+    }
+
+    @Test
+    public void validStartsReachIntersectionProcessing() {
+        assertTrue(NativeStructureVegetationClearer.shouldProcessStart(
+                desertStart(0, 0, GROUND_Y + 15)));
+        assertFalse(NativeStructureVegetationClearer.shouldProcessStart(
+                StructureStart.INVALID_START));
+    }
+
+    @Test
+    public void allUndergroundGenerationStepsShareOneClassification() {
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.UNDERGROUND_STRUCTURES));
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.UNDERGROUND_DECORATION));
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.STRONGHOLDS));
+        assertFalse(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.SURFACE_STRUCTURES));
+    }
+
+    @Test
+    public void undergroundStructuresUseTheLowestTerrainColumn() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        int offset = NativeStructureVerticalPlacer.resolveBuriedOffset(
+                bounds, 0, -64, 320, (x, z) -> x == 1 ? 76 : 100);
+        assertEquals(-5, offset);
+    }
+
+    @Test
+    public void undergroundBurialClampsToTheWorldFloorInsteadOfFailing() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        assertEquals(-2, NativeStructureVerticalPlacer.resolveBuriedOffset(
+                bounds, 0, 58, 320, (x, z) -> x == 1 ? 76 : 100));
+    }
+
+    @Test
+    public void loweringSurfaceRemovesCactusStacksAndTheirFlowers() {
+        ProtoChunk chunk = chunk();
+        for (int y = 80; y <= 102; y++) {
+            write(chunk, 4, y, 4, Blocks.SAND.defaultBlockState());
+        }
+        for (int y = 103; y <= 105; y++) {
+            write(chunk, 4, y, 4, Blocks.CACTUS.defaultBlockState());
+        }
+        write(chunk, 4, 106, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world(chunk), new BlockPos.MutableBlockPos(), 4, 4, 102, 93, MIN_Y, MAX_Y);
+
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 93, 4)));
+        for (int y = 94; y <= 106; y++) {
+            assertTrue("Unsupported decoration at " + y, chunk.getBlockState(new BlockPos(4, y, 4)).isAir());
+        }
+    }
+
+    @Test
+    public void loweringSurfacePreservesCactusOnUnchangedColumns() {
+        ProtoChunk chunk = chunk();
+        for (int x : List.of(4, 5)) {
+            for (int y = 60; y <= 64; y++) {
+                write(chunk, x, y, 4, Blocks.SAND.defaultBlockState());
+            }
+            write(chunk, x, 65, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, x, 66, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+        }
+        WorldGenLevel world = world(chunk);
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 5, 4, 64, 64, MIN_Y, MAX_Y);
+
+        assertTrue(chunk.getBlockState(new BlockPos(4, 65, 4)).isAir());
+        assertTrue(chunk.getBlockState(new BlockPos(4, 66, 4)).isAir());
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 64, 4)));
+        assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 65, 4)));
+        assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 66, 4)));
+    }
+
+    @Test
+    public void loweringSurfaceKeepsTreeBoundaries() {
+        for (BlockState boundary : List.of(Blocks.OAK_LOG.defaultBlockState(), Blocks.OAK_LEAVES.defaultBlockState())) {
+            ProtoChunk chunk = chunk();
+            write(chunk, 4, 63, 4, Blocks.SAND.defaultBlockState());
+            write(chunk, 4, 64, 4, Blocks.SAND.defaultBlockState());
+            write(chunk, 4, 65, 4, boundary);
+            write(chunk, 4, 66, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, 4, 67, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+
+            NativeStructureSurfaceFitter.applySurfaceColumn(
+                    world(chunk), new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+
+            assertEquals(boundary, chunk.getBlockState(new BlockPos(4, 65, 4)));
+            assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 66, 4)));
+            assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 67, 4)));
+        }
+    }
+
+    @Test
+    public void loweringSurfaceRemovesUnsupportedPlankDecoration() {
+        ProtoChunk chunk = chunk();
+        for (int x : List.of(4, 5)) {
+            for (int y = 60; y <= 64; y++) {
+                write(chunk, x, y, 4, Blocks.SAND.defaultBlockState());
+            }
+            write(chunk, x, 65, 4, Blocks.OAK_PLANKS.defaultBlockState());
+            write(chunk, x, 66, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, x, 67, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+        }
+        WorldGenLevel world = world(chunk);
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 5, 4, 64, 64, MIN_Y, MAX_Y);
+
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 60, 4)));
+        for (int y = 61; y <= 67; y++) {
+            assertTrue(chunk.getBlockState(new BlockPos(4, y, 4)).isAir());
+        }
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 64, 4)));
+        assertEquals(Blocks.OAK_PLANKS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 65, 4)));
+        assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 66, 4)));
+        assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 67, 4)));
+    }
+
+    private static void clearVegetation(ProtoChunk chunk, StructureStart start) {
+        NativeStructureVegetationClearer.clearIntersectingVegetation(
+                world(chunk), chunk, AREA, List.of(start));
+    }
+
+    private static StructureStart desertStart(int originX, int originZ, int topY) {
+        Structure structure = new DesertPyramidStructure(
+                new Structure.StructureSettings(
+                        HolderSet.empty(), Map.of(),
+                        GenerationStep.Decoration.SURFACE_STRUCTURES, TerrainAdjustment.NONE));
+        DesertPyramidPiece piece = new DesertPyramidPiece(RandomSource.create(7L), originX, originZ);
+        piece.move(0, topY - piece.getBoundingBox().maxY(), 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static ProtoChunk chunk() {
+        return new ProtoChunk(
+                new ChunkPos(0, 0), UpgradeData.EMPTY,
+                LevelHeightAccessor.create(MIN_Y, MAX_Y - MIN_Y + 1), containerFactory(), null);
+    }
+
+    private static void fillLayer(ProtoChunk chunk, int y, BlockState state) {
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                write(chunk, x, y, z, state);
+            }
+        }
+    }
+
+    private static void write(ProtoChunk chunk, int x, int y, int z, BlockState state) {
+        LevelChunkSection section = chunk.getSection(chunk.getSectionIndex(y));
+        section.setBlockState(x, y & 15, z, state, false);
+    }
+
+    private static BlockState log() {
+        return Blocks.OAK_LOG.defaultBlockState();
+    }
+
+    private static BlockState leaves() {
+        return Blocks.OAK_LEAVES.defaultBlockState();
+    }
+
+    private static BlockState air() {
+        return Blocks.AIR.defaultBlockState();
+    }
+
+    private static WorldGenLevel world(ChunkAccess chunk) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getBlockState")) {
+                return chunk.getBlockState((BlockPos) arguments[0]);
+            }
+            if (methodName.equals("setBlock")) {
+                return chunk.setBlockState(
+                        ((BlockPos) arguments[0]).immutable(),
+                        (BlockState) arguments[1], (int) arguments[2]) != null;
+            }
+            if (methodName.equals("getSeed")) {
+                return TEST_SEED;
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("holderLookup")) {
+                return BuiltInRegistries.BLOCK;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "vegetation-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blockStates = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> defaultBiome = Holder.direct((Biome) null);
+        biomeIds.add(defaultBiome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(
+                name -> defaultBiome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(
+                blockStates,
+                air,
+                PalettedContainer.codecRW(BlockState.CODEC, blockStates, air),
+                biomes,
+                defaultBiome,
+                PalettedContainer.codecRO(biomeCodec, biomes, defaultBiome),
+                PalettedContainer.codecRW(biomeCodec, biomes, defaultBiome));
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureTemplateOccupancyTest.java

@@ -0,0 +1,240 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureTemplateOccupancy;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureReflection;
+
+import com.mojang.datafixers.util.Either;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.tags.TagKey;
+import net.minecraft.util.valueproviders.ConstantInt;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.pools.SinglePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlackstoneReplaceProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockAgeProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockIgnoreProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.CappedProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.GravityProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.JigsawReplacementProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LavaSubmergedBlockProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.NopProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.ProtectedBlockProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.RuleProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.Assume;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.TreeSet;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureTemplateOccupancyTest {
+    private static final BoundingBox PROCESSING_AREA = new BoundingBox(0, 56, 0, 15, 80, 0);
+    private static final int TEMPLATE_WIDTH = 32;
+    private static final int TERRAIN_HEIGHT = 64;
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void straddlingGravityPieceHeightReadsHonorTheVanillaClipContract() throws Exception {
+        ColumnRecorder recorder = new ColumnRecorder();
+
+        resolve(straddlingPiece(
+                List.of(new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0))), recorder);
+
+        // 26.2 vanilla clips processor evaluation to the placement bounding box; 26.1.2 vanilla
+        // runs processors across the whole piece. Iris mirrors the pinned version's semantics.
+        assertEquals(expectedClippedColumns(), recorder.heightColumns);
+    }
+
+    @Test
+    public void cappedStraddlingPieceRunsProcessorsAcrossTheWholePiece() throws Exception {
+        ColumnRecorder recorder = new ColumnRecorder();
+
+        resolve(straddlingPiece(List.of(
+                new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0),
+                new CappedProcessor(NopProcessor.INSTANCE, ConstantInt.of(0)))), recorder);
+
+        assertEquals(columns(0, TEMPLATE_WIDTH - 1), recorder.heightColumns);
+    }
+
+    @Test
+    public void cappedProcessorIsTheOnlyProcessorThatDisablesTheProcessingAreaClip() throws Exception {
+        Method contract = clipContractMethod();
+        Assume.assumeTrue("evaluatesEntirePieceState only exists on 26.2+", contract != null);
+
+        for (StructureProcessor processor : List.of(
+                BlockIgnoreProcessor.STRUCTURE_BLOCK,
+                JigsawReplacementProcessor.INSTANCE,
+                LavaSubmergedBlockProcessor.INSTANCE,
+                NopProcessor.INSTANCE,
+                BlackstoneReplaceProcessor.INSTANCE,
+                new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0),
+                new RuleProcessor(List.of()),
+                new BlockAgeProcessor(0.5F),
+                protectedBlockProcessor())) {
+            assertFalse(processor.getClass().getName(),
+                    (Boolean) contract.invoke(processor));
+        }
+        assertTrue((Boolean) contract.invoke(
+                new CappedProcessor(NopProcessor.INSTANCE, ConstantInt.of(4))));
+    }
+
+    @Test
+    public void placementSettingsCarryTheProcessingAreaAsTheirClipBox() throws Exception {
+        PoolElementStructurePiece piece = straddlingPiece(List.of());
+
+        StructurePlaceSettings settings = NativeStructureReflection.resolvePlacementSettings(
+                (SinglePoolElement) piece.getElement(), piece, PROCESSING_AREA);
+
+        assertEquals(PROCESSING_AREA, settings.getBoundingBox());
+    }
+
+    private static void resolve(PoolElementStructurePiece piece, ColumnRecorder recorder) {
+        NativeStructureTemplateOccupancy.resolve(
+                world(recorder), piece, piece.getPosition(), PROCESSING_AREA,
+                NativeStructureTemplateOccupancyTest::forbiddenTemplateManager,
+                PROCESSING_AREA::isInside, amount -> {
+                });
+    }
+
+    private static PoolElementStructurePiece straddlingPiece(
+            List<StructureProcessor> processors) throws Exception {
+        BoundingBox bounds = new BoundingBox(0, 70, 0, TEMPLATE_WIDTH - 1, 76, 0);
+        return new PoolElementStructurePiece(
+                null, new InlineSinglePoolElement(template(), processors),
+                new BlockPos(bounds.minX(), bounds.minY(), bounds.minZ()),
+                1, Rotation.NONE, bounds, LiquidSettings.APPLY_WATERLOGGING);
+    }
+
+    private static Set<Integer> columns(int minimumX, int maximumX) {
+        Set<Integer> columns = new TreeSet<>();
+        for (int x = minimumX; x <= maximumX; x++) {
+            columns.add(x);
+        }
+        return columns;
+    }
+
+    private static Method clipContractMethod() {
+        try {
+            return StructureProcessor.class.getMethod("evaluatesEntirePieceState");
+        } catch (NoSuchMethodException absent) {
+            return null;
+        }
+    }
+
+    private static Set<Integer> expectedClippedColumns() {
+        return clipContractMethod() != null
+                ? columns(PROCESSING_AREA.minX(), PROCESSING_AREA.maxX())
+                : columns(0, TEMPLATE_WIDTH - 1);
+    }
+
+    private static StructureProcessor protectedBlockProcessor() throws Exception {
+        // Constructed reflectively: the constructor takes HolderSet on 26.2 and TagKey on 26.1.2.
+        Constructor<?> constructor = ProtectedBlockProcessor.class.getConstructors()[0];
+        Class<?> parameter = constructor.getParameterTypes()[0];
+        Object argument = parameter == HolderSet.class
+                ? HolderSet.empty()
+                : TagKey.create(Registries.BLOCK, Identifier.fromNamespaceAndPath("minecraft", "air"));
+        return (StructureProcessor) constructor.newInstance(argument);
+    }
+
+    private static StructureTemplateManager forbiddenTemplateManager() {
+        throw new AssertionError("Inline templates must not resolve a template manager");
+    }
+
+    private static StructureTemplate template() throws Exception {
+        List<StructureTemplate.StructureBlockInfo> blocks = new ArrayList<>();
+        for (int x = 0; x < TEMPLATE_WIDTH; x++) {
+            blocks.add(new StructureTemplate.StructureBlockInfo(
+                    new BlockPos(x, 0, 0), Blocks.COBBLESTONE.defaultBlockState(), null));
+        }
+        Constructor<StructureTemplate.Palette> constructor =
+                StructureTemplate.Palette.class.getDeclaredConstructor(List.class);
+        assertTrue(constructor.trySetAccessible());
+        StructureTemplate template = new StructureTemplate();
+        template.palettes.add(constructor.newInstance(blocks));
+        return template;
+    }
+
+    private static WorldGenLevel world(ColumnRecorder recorder) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getHeight") && arguments.length == 3) {
+                recorder.heightColumns.add((Integer) arguments[1]);
+                return TERRAIN_HEIGHT;
+            }
+            if (methodName.equals("getBlockState")) {
+                recorder.stateColumns.add(((BlockPos) arguments[0]).getX());
+                return Blocks.STONE.defaultBlockState();
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("holderLookup")) {
+                return BuiltInRegistries.BLOCK;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "occupancy-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(),
+                new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static final class ColumnRecorder {
+        private final Set<Integer> heightColumns = new TreeSet<>();
+        private final Set<Integer> stateColumns = new TreeSet<>();
+    }
+
+    private static final class InlineSinglePoolElement extends SinglePoolElement {
+        private InlineSinglePoolElement(
+                StructureTemplate template, List<StructureProcessor> processors) {
+            super(Either.right(template),
+                    Holder.direct(new StructureProcessorList(processors)),
+                    StructureTemplatePool.Projection.RIGID,
+                    Optional.<LiquidSettings>empty());
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeTerrainHeightCacheTest.java

@@ -0,0 +1,131 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeTerrainHeightCache;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.OptionalInt;
+import java.util.function.IntSupplier;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public final class NativeTerrainHeightCacheTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void coordinatesRuntimePredicatesAndBoundsHaveSeparateEntries() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        AtomicInteger calls = new AtomicInteger();
+        NativeTerrainHeightCache.Query[] queries = {
+                query(1, -1, 1),
+                query(1, 1, -1),
+                query(2, -1, 1),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.OCEAN_FLOOR, -256, 768),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.WORLD_SURFACE, -64, 768),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.WORLD_SURFACE, -256, 256)
+        };
+        for (int index = 0; index < queries.length; index++) {
+            assertEquals(index + 1, cached(cache, queries[index], calls::incrementAndGet));
+        }
+        for (int index = 0; index < queries.length; index++) {
+            assertEquals(index + 1, cached(cache, queries[index], calls::incrementAndGet));
+        }
+        assertEquals(queries.length, calls.get());
+        cache.evictRuntime(1);
+        assertEquals(3, cached(cache, queries[2], calls::incrementAndGet));
+        assertEquals(7, cached(cache, queries[0], calls::incrementAndGet));
+    }
+
+    @Test
+    public void allIntegerResultsAreCacheable() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertEquals(Integer.MIN_VALUE, cached(cache, query, () -> Integer.MIN_VALUE));
+        assertEquals(Integer.MIN_VALUE, cached(cache, query, () -> 0));
+    }
+
+    @Test
+    public void failedResolutionCanBeRetried() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertThrows(IllegalStateException.class, () -> cached(cache, query, () -> {
+            throw new IllegalStateException("terrain unavailable");
+        }));
+        assertEquals(42, cached(cache, query, () -> 42));
+    }
+
+    @Test
+    public void coldResolutionDoesNotHoldCacheMonitor() throws Exception {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        CountDownLatch entered = new CountDownLatch(1);
+        CountDownLatch release = new CountDownLatch(1);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<Integer> slow = executor.submit(() -> cached(cache, query(1, 0, 0), () -> {
+                entered.countDown();
+                try {
+                    assertTrue(release.await(5, TimeUnit.SECONDS));
+                } catch (InterruptedException interruption) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(interruption);
+                }
+                return 9;
+            }));
+            assertTrue(entered.await(5, TimeUnit.SECONDS));
+            Future<Integer> independent = executor.submit(() -> cached(cache, query(1, 1, 0), () -> 17));
+            assertEquals(Integer.valueOf(17), independent.get(1, TimeUnit.SECONDS));
+            release.countDown();
+            assertEquals(Integer.valueOf(9), slow.get(5, TimeUnit.SECONDS));
+        } finally {
+            release.countDown();
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void boundedCacheKeepsRecentlyReadCoordinates() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        for (int x = 0; x < 65_536; x++) {
+            cached(cache, query(1, x, 0), () -> 8);
+        }
+        assertEquals(8, cached(cache, query(1, 0, 0), () -> 99));
+        cached(cache, query(1, 65_536, 0), () -> 9);
+        assertEquals(8, cached(cache, query(1, 0, 0), () -> 99));
+        assertEquals(99, cached(cache, query(1, 1, 0), () -> 99));
+    }
+
+    @Test
+    public void unavailableResolvedHeightIsNotCached() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertTrue(cache.resolvedHeight(query, OptionalInt::empty).isEmpty());
+        assertEquals(42, cache.resolvedHeight(query, () -> OptionalInt.of(42)).orElseThrow());
+        assertEquals(42, cache.resolvedHeight(query, OptionalInt::empty).orElseThrow());
+    }
+
+    private static int cached(NativeTerrainHeightCache cache, NativeTerrainHeightCache.Query query,
+                              IntSupplier resolver) {
+        return cache.resolvedHeight(query, () -> OptionalInt.of(resolver.getAsInt())).orElseThrow();
+    }
+
+    private static NativeTerrainHeightCache.Query query(int runtimeId, int x, int z) {
+        return new NativeTerrainHeightCache.Query(runtimeId, x, z, Heightmap.Types.WORLD_SURFACE, -256, 768);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/nativegen/NativeTransitionColumnTest.java

@@ -0,0 +1,108 @@
+package art.arcane.iris.nativegen;
+
+import art.arcane.iris.world.history.TerrainNativeBlockKeys;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeTransitionColumn;
+
+import art.arcane.iris.world.history.BoundaryColumnGeometry;
+import art.arcane.iris.world.history.TerrainBoundarySignature;
+import art.arcane.iris.spi.IrisPlatform;
+import art.arcane.iris.spi.IrisPlatforms;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import art.arcane.iris.spi.PlatformRegistries;
+import art.arcane.iris.testsupport.PlatformLeakGuard;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.RotatedPillarBlock;
+import net.minecraft.world.level.block.LiquidBlock;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.util.List;
+import java.util.OptionalInt;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.when;
+
+public final class NativeTransitionColumnTest {
+    @Rule
+    public final PlatformLeakGuard leakGuard = PlatformLeakGuard.clean();
+
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void customKeysUseCarrierForNativeColumnsAndHeightmaps() {
+        String key = "itemsadder:rocks/ruby_ore";
+        NativeBlockState custom = mock(NativeBlockState.class);
+        NativeBlockState carrier = mock(NativeBlockState.class);
+        when(custom.placementBaseState()).thenReturn(carrier);
+        when(carrier.key()).thenReturn("minecraft:oak_log[axis=z]");
+        IrisPlatform platform = mock(IrisPlatform.class);
+        PlatformRegistries registries = mock(PlatformRegistries.class);
+        when(platform.registries()).thenReturn(registries);
+        when(registries.blockOrNull(key)).thenReturn(custom);
+        LevelHeightAccessor height = LevelHeightAccessor.create(-16, 32);
+        TerrainBoundarySignature signature = signature(key);
+
+        try (MockedStatic<IrisPlatforms> platforms = mockStatic(IrisPlatforms.class)) {
+            platforms.when(IrisPlatforms::isBound).thenReturn(true);
+            platforms.when(IrisPlatforms::get).thenReturn(platform);
+            NoiseColumn column = NativeTransitionColumn.column(signature.geometry(), height, TerrainNativeBlockKeys::placementKey);
+
+            assertEquals(Direction.Axis.Z, column.getBlock(-15).getValue(RotatedPillarBlock.AXIS));
+            assertEquals(-14, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.OCEAN_FLOOR_WG, height, TerrainNativeBlockKeys::placementKey));
+        }
+    }
+
+    @Test
+    public void preservesNativePropertiesCavesAndFluids() {
+        NoiseColumn column = NativeTransitionColumn.column(signature("minecraft:oak_log[axis=x]").geometry(),
+                LevelHeightAccessor.create(-16, 32), TerrainNativeBlockKeys::placementKey);
+        assertEquals(Direction.Axis.X, column.getBlock(-15).getValue(RotatedPillarBlock.AXIS));
+        assertTrue(column.getBlock(-14).is(Blocks.CAVE_AIR));
+        assertEquals(Integer.valueOf(3), column.getBlock(-13).getValue(LiquidBlock.LEVEL));
+        assertTrue(column.getBlock(0).isAir());
+    }
+
+    @Test
+    public void usesNativeHeightmapPredicatesForWaterAndOpenSpace() {
+        TerrainBoundarySignature signature = signature("minecraft:oak_log[axis=x]");
+        LevelHeightAccessor height = LevelHeightAccessor.create(-16, 32);
+        assertEquals(-12, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.WORLD_SURFACE_WG, height, TerrainNativeBlockKeys::placementKey));
+        assertEquals(-14, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.OCEAN_FLOOR_WG, height, TerrainNativeBlockKeys::placementKey));
+    }
+
+    @Test
+    public void rejectsUnknownSavedStatesInsteadOfReplacingTerrain() {
+        assertThrows(IllegalArgumentException.class, () -> NativeTransitionColumn.column(signature("missing:removed_block").geometry(), LevelHeightAccessor.create(-16, 32), TerrainNativeBlockKeys::placementKey));
+    }
+
+    private static TerrainBoundarySignature signature(String solidState) {
+        BoundaryColumnGeometry geometry = BoundaryColumnGeometry.fromVoxels(-16, List.of(
+                new BoundaryColumnGeometry.Voxel("minecraft:stone", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel(solidState, BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:cave_air", BoundaryColumnGeometry.Phase.AIR, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:water[level=3]", BoundaryColumnGeometry.Phase.FLUID,
+                        "minecraft:water[level=3]", false)));
+        return new TerrainBoundarySignature(
+                new TerrainBoundarySignature.Column(0, 0, 3, 1, OptionalInt.of(3), OptionalInt.empty()),
+                new TerrainBoundarySignature.Samples(new TerrainBoundarySignature.VerticalLayout(-16, 4, 1),
+                        new TerrainBoundarySignature.BiomeEncoding(List.of("minecraft:plains"), new short[]{0})),
+                geometry);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/CustomBiomeSourceStructureContractTest.java

@@ -0,0 +1,66 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.iris.platform.bukkit.nms.BukkitBiomePolicy;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.terrain.IrisDimension;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Proxy;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertTrue;
+
+public class CustomBiomeSourceStructureContractTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void stackedCustomBiomesUseTheirOwningDimensionNamespace() {
+        IrisDimension host = new IrisDimension();
+        host.setLoadKey("Host");
+        IrisDimension upper = new IrisDimension();
+        upper.setLoadKey("Layers/Upper");
+
+        assertEquals("layers:upper/aurora", BukkitBiomePolicy.customBiomeKey(upper, "Aurora"));
+        assertNotEquals(
+                BukkitBiomePolicy.customBiomeKey(host, "Aurora"),
+                BukkitBiomePolicy.customBiomeKey(upper, "Aurora")
+        );
+    }
+
+    @Test
+    public void temporaryNaturalBiomeAnswersAreNotMemoized() {
+        Engine temporary = engineAnsweringNaturalFallback(true, 12, -8);
+        Engine stable = engineAnsweringNaturalFallback(false, 12, -8);
+        assertFalse(BukkitBiomePolicy.isBiomeCacheable(temporary, 12, -8));
+        assertTrue(BukkitBiomePolicy.isBiomeCacheable(stable, 12, -8));
+    }
+
+    private static Engine engineAnsweringNaturalFallback(
+            boolean naturalFallback,
+            int expectedX,
+            int expectedZ
+    ) {
+        return (Engine) Proxy.newProxyInstance(
+                Engine.class.getClassLoader(),
+                new Class<?>[]{Engine.class},
+                (proxy, method, arguments) -> {
+                    if (!method.getName().equals("answersFromNaturalTerrain")) {
+                        throw new UnsupportedOperationException(method.getName());
+                    }
+                    assertEquals(Integer.valueOf(expectedX), arguments[0]);
+                    assertEquals(Integer.valueOf(expectedZ), arguments[1]);
+                    return naturalFallback;
+                }
+        );
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/IrisChunkGeneratorFailureContractTest.java

@@ -0,0 +1,97 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import org.junit.Test;
+
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.Semaphore;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.locks.LockSupport;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class IrisChunkGeneratorFailureContractTest {
+    @Test
+    public void releasedNoiseAdmissionLetsSynchronousDependentWaitForQueuedExclusive() throws Exception {
+        Semaphore admission = new Semaphore(1, true);
+        admission.acquire();
+        CountDownLatch exclusiveEntered = new CountDownLatch(1);
+        CountDownLatch releaseExclusive = new CountDownLatch(1);
+        AtomicBoolean dependentFinished = new AtomicBoolean(false);
+        ExecutorService executor = Executors.newSingleThreadExecutor();
+        boolean stageReleased = false;
+
+        try {
+            Future<?> exclusive = executor.submit(() -> {
+                boolean acquired = false;
+                try {
+                    admission.acquire();
+                    acquired = true;
+                    exclusiveEntered.countDown();
+                    assertTrue(releaseExclusive.await(2, TimeUnit.SECONDS));
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(e);
+                } finally {
+                    if (acquired) {
+                        admission.release();
+                    }
+                }
+            });
+            awaitQueueLength(admission, 1);
+            CompletableFuture<Void> outward = new CompletableFuture<>();
+            outward.thenRun(() -> {
+                try {
+                    assertTrue(exclusiveEntered.await(2, TimeUnit.SECONDS));
+                    dependentFinished.set(true);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(e);
+                }
+            });
+
+            admission.release();
+            stageReleased = true;
+            assertTrue(outward.complete(null));
+            assertTrue(dependentFinished.get());
+            releaseExclusive.countDown();
+            exclusive.get(2, TimeUnit.SECONDS);
+            assertEquals(1, admission.availablePermits());
+        } finally {
+            if (!stageReleased) {
+                admission.release();
+            }
+            releaseExclusive.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    @Test
+    public void transformedDelegateCancellationIsDetectedThroughItsCompletionFailure() {
+        CompletableFuture<Void> delegate = new CompletableFuture<>();
+        CompletableFuture<Void> transformed = delegate.thenApply(value -> value);
+
+        assertTrue(delegate.cancel(false));
+        assertFalse(transformed.isCancelled());
+        CompletionException failure = assertThrows(CompletionException.class, transformed::join);
+        assertTrue(failure.getCause() instanceof CancellationException);
+    }
+
+    private static void awaitQueueLength(Semaphore semaphore, int expected) {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(2);
+        while (semaphore.getQueueLength() < expected && System.nanoTime() < deadline) {
+            LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(1));
+        }
+        assertTrue("Expected at least " + expected + " queued semaphore threads",
+                semaphore.getQueueLength() >= expected);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/IrisChunkGeneratorMonumentLocateContractTest.java

@@ -0,0 +1,58 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureLocateResults;
+import com.mojang.datafixers.util.Pair;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import org.junit.Test;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+
+public class IrisChunkGeneratorMonumentLocateContractTest {
+    @Test
+    public void mixedLocateSelectsNearestProviderAndPrefersNativeOnTie() {
+        BlockPos origin = BlockPos.ZERO;
+        Pair<BlockPos, Holder<Structure>> irisNear = Pair.of(new BlockPos(4, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeFar = Pair.of(new BlockPos(8, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeNear = Pair.of(new BlockPos(2, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeTie = Pair.of(new BlockPos(0, 70, 4), null);
+
+        assertSame(irisNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeFar));
+        assertSame(nativeNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeNear));
+        assertSame(nativeTie, NativeStructureLocateResults.nearest(origin, irisNear, nativeTie));
+    }
+
+    @Test
+    public void mixedUnexploredLocateReferencesOnlyTheSelectedProvider() {
+        BlockPos origin = BlockPos.ZERO;
+        Pair<BlockPos, Holder<Structure>> irisNear = Pair.of(new BlockPos(4, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeFar = Pair.of(new BlockPos(8, 70, 0), null);
+        AtomicInteger irisReferences = new AtomicInteger();
+        AtomicInteger nativeReferences = new AtomicInteger();
+
+        Pair<BlockPos, Holder<Structure>> irisSelected =
+                NativeStructureLocateResults.selectAndReference(
+                        origin,
+                        irisNear, () -> irisReferences.incrementAndGet(),
+                        nativeFar, () -> nativeReferences.incrementAndGet());
+
+        assertSame(irisNear, irisSelected);
+        assertEquals(1, irisReferences.get());
+        assertEquals(0, nativeReferences.get());
+
+        Pair<BlockPos, Holder<Structure>> nativeNear = Pair.of(new BlockPos(2, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeSelected =
+                NativeStructureLocateResults.selectAndReference(
+                        origin,
+                        irisNear, () -> irisReferences.incrementAndGet(),
+                        nativeNear, () -> nativeReferences.incrementAndGet());
+
+        assertSame(nativeNear, nativeSelected);
+        assertEquals(1, irisReferences.get());
+        assertEquals(1, nativeReferences.get());
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/IrisChunkGeneratorSpawnAdmissionTest.java

@@ -0,0 +1,149 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.iris.platform.bukkit.nms.BukkitGeneratorContext;
+import org.bukkit.World;
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeChunkGenerator;
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeBiomeSourceImpl;
+
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.generation.runtime.GenerationSessionManager;
+import art.arcane.iris.generation.runtime.GenerationTransitionGate;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.iris.world.history.NativeBiomeSpawnSelection;
+import art.arcane.iris.world.history.SavedBiomeRuntime;
+import art.arcane.iris.generation.context.IrisContext;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.random.WeightedList;
+import net.minecraft.world.entity.MobCategory;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.MobSpawnSettings;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class IrisChunkGeneratorSpawnAdmissionTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void tickSpawnQueryLeavesOwnerThreadAvailableForBoundaryCheckpoint() throws Exception {
+        Fixture fixture = new Fixture();
+        ExecutorService owner = Executors.newSingleThreadExecutor();
+        ExecutorService reloader = Executors.newSingleThreadExecutor();
+        AtomicInteger snapshots = new AtomicInteger();
+        long previousSession = fixture.sessions.currentSessionId();
+        try {
+            assertSame(fixture.expected, owner.submit(fixture::query).get(2L, TimeUnit.SECONDS));
+            assertEquals(previousSession, fixture.readSession.get());
+            CompletableFuture<Void> cutover = CompletableFuture.runAsync(() -> {
+                try (GenerationTransitionGate.Transition ignored = fixture.sessions.transitionGate().beginTransition(2_000L)) {
+                    fixture.sessions.sealAndAwait("Studio generation cutover", 2_000L);
+                    Future<?> query = owner.submit(() -> {
+                        assertTrue(fixture.query().isEmpty());
+                        assertNull(IrisContext.get());
+                    });
+                    owner.submit(snapshots::incrementAndGet).get(2L, TimeUnit.SECONDS);
+                    query.get(2L, TimeUnit.SECONDS);
+                    assertEquals(1, fixture.savedReads.get());
+                    assertEquals(1, fixture.routes.get());
+                    fixture.sessions.activateNextSession();
+                } catch (Exception failure) {
+                    throw new IllegalStateException(failure);
+                }
+            }, reloader);
+
+            cutover.get(3L, TimeUnit.SECONDS);
+            assertEquals(1, snapshots.get());
+            assertEquals(0, fixture.sessions.activeLeases());
+            assertSame(fixture.expected, owner.submit(fixture::query).get(2L, TimeUnit.SECONDS));
+            assertEquals(fixture.sessions.currentSessionId(), fixture.readSession.get());
+            assertTrue(fixture.readSession.get() > previousSession);
+            assertEquals(2, fixture.savedReads.get());
+            assertEquals(2, fixture.routes.get());
+            assertEquals(0, fixture.sessions.activeLeases());
+        } finally {
+            owner.shutdownNow();
+            reloader.shutdownNow();
+            assertTrue(owner.awaitTermination(2L, TimeUnit.SECONDS));
+            assertTrue(reloader.awaitTermination(2L, TimeUnit.SECONDS));
+        }
+    }
+
+    private static void setField(NativeChunkGenerator<?, ?, ?, ?, ?> generator, String name, Object value) throws Exception {
+        Field field = NativeChunkGenerator.class.getDeclaredField(name);
+        field.setAccessible(true);
+        field.set(generator, value);
+    }
+
+    private static final class Fixture {
+        private final GenerationSessionManager sessions = new GenerationSessionManager(true);
+        private final IrisEngine engine = mock(IrisEngine.class);
+        private final NativeChunkGenerator<?, ?, ?, ?, ?> generator = mock(NativeChunkGenerator.class, CALLS_REAL_METHODS);
+        private final Holder<Biome> biome = Holder.direct(mock(Biome.class));
+        private final StructureManager structures = mock(StructureManager.class);
+        private final WeightedList<MobSpawnSettings.SpawnerData> expected = mock(WeightedList.class);
+        private final AtomicInteger savedReads = new AtomicInteger();
+        private final AtomicInteger routes = new AtomicInteger();
+        private final AtomicLong readSession = new AtomicLong();
+
+        private Fixture() throws Exception {
+            GenerationHistoryRuntimeRouter router = mock(GenerationHistoryRuntimeRouter.class);
+            SavedBiomeRuntime saved = mock(SavedBiomeRuntime.class);
+            ChunkGenerator delegate = mock(ChunkGenerator.class);
+            NativeBiomeSourceImpl source = mock(NativeBiomeSourceImpl.class);
+            when(engine.getGenerationSessions()).thenReturn(sessions);
+            when(engine.getGenerationHistoryRuntimeRouter()).thenReturn(Optional.of(router));
+            when(router.biomes()).thenReturn(saved);
+            when(saved.nativeSpawnSelection(0, 64, 0, "")).thenAnswer(invocation -> {
+                assertAdmitted();
+                savedReads.incrementAndGet();
+                return new NativeBiomeSpawnSelection(NativeBiomeSpawnSelection.Mode.RETAINED, "minecraft:plains");
+            });
+            when(engine.openGenerationHistoryCoordinateScope(0, 0)).thenAnswer(invocation -> {
+                assertAdmitted();
+                routes.incrementAndGet();
+                return null;
+            });
+            when(delegate.getMobsAt(biome, structures, MobCategory.MONSTER, new BlockPos(0, 64, 0)))
+                    .thenReturn(expected);
+            setField(generator, "context", new BukkitGeneratorContext(new BukkitGeneratorContext.Options(1L, engine, mock(World.class))));
+            setField(generator, "delegate", delegate);
+            setField(generator, "customBiomeSource", source);
+        }
+
+        private WeightedList<MobSpawnSettings.SpawnerData> query() {
+            return generator.getMobsAt(biome, structures, MobCategory.MONSTER, new BlockPos(0, 64, 0));
+        }
+
+        private void assertAdmitted() {
+            assertEquals(1, sessions.activeLeases());
+            assertSame(engine, IrisContext.get().getEngine());
+            readSession.set(IrisContext.get().getGenerationSessionId());
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NMSBindingDatapackStructureScopeTest.java

@@ -0,0 +1,511 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeStructureSetFilter;
+
+import art.arcane.iris.pack.datapack.DatapackIngestService;
+import art.arcane.iris.pack.datapack.DatapackStructureScopeIndex;
+import art.arcane.iris.structure.nativegen.IrisImportedStructureControl;
+import art.arcane.iris.structure.placement.IrisStructureSetFrequencyOverride;
+import art.arcane.volmlib.util.collection.KList;
+import com.mojang.datafixers.util.Either;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderOwner;
+import net.minecraft.core.Vec3i;
+import net.minecraft.core.component.DataComponentMap;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.tags.TagKey;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureSet;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadType;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacementType;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import org.junit.Test;
+import org.junit.BeforeClass;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+
+public class NMSBindingDatapackStructureScopeTest {
+    private static final String SOURCE = "https://example.test/managed.zip";
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void managedSetContainingVanillaStructureIsAbsentOutsideDeclaringDimension() {
+        Holder<Structure> vanillaStructure = structureHolder("minecraft:pillager_outpost");
+        Holder<StructureSet> managedSet = structureSetHolder(
+                "managed:illager_barracks", vanillaStructure);
+        DatapackStructureScopeIndex index = index(
+                List.of(),
+                List.of("managed:illager_barracks"));
+
+        NativeStructureSetFilter.Selection vanilla = NativeStructureSetFilter.filter(
+                List.of(managedSet), index, Set.of());
+        NativeStructureSetFilter.Selection declaring = NativeStructureSetFilter.filter(
+                List.of(managedSet), index, index.declaredSources(List.of(SOURCE)));
+
+        assertEquals(0, vanilla.structureSets().size());
+        assertEquals(1, vanilla.excludedManagedSets());
+        assertEquals(1, declaring.structureSets().size());
+        assertSame(managedSet, declaring.structureSets().getFirst());
+    }
+
+    @Test
+    public void unmanagedSetRetainsOnlyDefinitionsAllowedInTheWorld() {
+        Holder<Structure> vanillaStructure = structureHolder("minecraft:village_plains");
+        Holder<Structure> managedStructure = structureHolder("managed:tavern");
+        Holder<StructureSet> vanillaSet = structureSetHolder(
+                "minecraft:villages", vanillaStructure, managedStructure);
+        DatapackStructureScopeIndex index = index(
+                List.of("managed:tavern"),
+                List.of());
+
+        NativeStructureSetFilter.Selection vanilla = NativeStructureSetFilter.filter(
+                List.of(vanillaSet), index, Set.of());
+        NativeStructureSetFilter.Selection declaring = NativeStructureSetFilter.filter(
+                List.of(vanillaSet), index, index.declaredSources(List.of(SOURCE)));
+
+        assertEquals(1, vanilla.structureSets().size());
+        assertEquals(1, vanilla.structureSets().getFirst().value().structures().size());
+        assertSame(vanillaStructure,
+                vanilla.structureSets().getFirst().value().structures().getFirst().structure());
+        assertSame(vanillaSet.value().placement(),
+                vanilla.structureSets().getFirst().value().placement());
+        assertSame(vanillaSet, declaring.structureSets().getFirst());
+    }
+
+    @Test
+    public void setWithNoAllowedDefinitionsIsRemoved() {
+        Holder<StructureSet> unmanagedSet = structureSetHolder(
+                "minecraft:custom", structureHolder("managed:only"));
+        DatapackStructureScopeIndex index = index(List.of("managed:only"), List.of());
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(unmanagedSet), index, Set.of());
+
+        assertEquals(0, selection.structureSets().size());
+    }
+
+    @Test
+    public void spigotDirectHolderRecoversItsRegistryKeyFromSharedEntries() {
+        ResourceKey<StructureSet> key = ResourceKey.create(
+                Registries.STRUCTURE_SET,
+                Identifier.parse("managed:illager_barracks"));
+        List<StructureSet.StructureSelectionEntry> entries = List.of(
+                new StructureSet.StructureSelectionEntry(
+                        structureHolder("minecraft:pillager_outpost"), 1));
+        Holder<StructureSet> registered = new KeyedHolder<>(key, new StructureSet(
+                entries,
+                new RandomSpreadStructurePlacement(
+                        34, 8, RandomSpreadType.LINEAR, 10387312)));
+        Holder<StructureSet> spigotDirect = Holder.direct(new StructureSet(
+                entries,
+                new RandomSpreadStructurePlacement(
+                        34, 8, RandomSpreadType.LINEAR, 14357620)));
+        DatapackStructureScopeIndex scopeIndex = index(
+                List.of(), List.of("managed:illager_barracks"));
+        NativeStructureSetFilter.StructureSetKeyIndex keyIndex =
+                NativeStructureSetFilter.keyIndex(List.of(registered));
+
+        NativeStructureSetFilter.Selection excluded =
+                NativeStructureSetFilter.filter(
+                        List.of(spigotDirect),
+                        scopeIndex,
+                        Set.of(),
+                        new IrisImportedStructureControl(),
+                        keyIndex);
+        NativeStructureSetFilter.Selection retained =
+                NativeStructureSetFilter.filter(
+                        List.of(spigotDirect),
+                        scopeIndex,
+                        scopeIndex.declaredSources(List.of(SOURCE)),
+                        new IrisImportedStructureControl(),
+                        keyIndex);
+
+        assertEquals(0, excluded.structureSets().size());
+        assertEquals(1, excluded.excludedManagedSets());
+        assertSame(spigotDirect, retained.structureSets().getFirst());
+        assertEquals(1, retained.retainedManagedSets());
+    }
+
+    @Test
+    public void structureScopeDoesNotLinkPaperOnlyPlacementClasses() throws IOException {
+        InputStream classResource = NativeStructureSetFilter.class
+                .getResourceAsStream("NativeStructureSetFilter.class");
+        assertNotNull(classResource);
+        try (InputStream input = classResource) {
+            String classFile = new String(input.readAllBytes(), StandardCharsets.ISO_8859_1);
+            assertFalse(classFile.contains("KeyedRandomSpreadStructurePlacement"));
+        }
+    }
+
+    @Test
+    public void exactFrequencyOverridesScaleOnlyTheNamedNativeStructureSet() {
+        Holder<StructureSet> complexes = structureSetHolder(
+                "minecraft:nether_complexes",
+                new RandomSpreadStructurePlacement(27, 4, RandomSpreadType.LINEAR, 30084232),
+                structureHolder("minecraft:fortress"));
+        Holder<StructureSet> fossils = structureSetHolder(
+                "minecraft:nether_fossils",
+                new RandomSpreadStructurePlacement(2, 1, RandomSpreadType.LINEAR, 14357921),
+                structureHolder("minecraft:nether_fossil"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("minecraft:nether_complexes")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(complexes, fossils), index(List.of(), List.of()), Set.of(), control);
+
+        RandomSpreadStructurePlacement scaledComplexes =
+                (RandomSpreadStructurePlacement) selection.structureSets().get(0).value().placement();
+        RandomSpreadStructurePlacement unchangedFossils =
+                (RandomSpreadStructurePlacement) selection.structureSets().get(1).value().placement();
+        assertEquals(26, scaledComplexes.spacing());
+        assertEquals(4, scaledComplexes.separation());
+        assertEquals(2, unchangedFossils.spacing());
+        assertSame(fossils, selection.structureSets().get(1));
+        assertEquals(27, ((RandomSpreadStructurePlacement) complexes.value().placement()).spacing());
+    }
+
+    @Test
+    public void frequencyOnlyPassLeavesUnrelatedCustomPlacementUntouched() {
+        Holder<StructureSet> exclusionTarget = structureSetHolder(
+                "example:target", structureHolder("example:target"));
+        Holder<StructureSet> custom = structureSetHolder(
+                "example:custom",
+                new UnsupportedPlacement(Optional.of(
+                        new StructurePlacement.ExclusionZone(exclusionTarget, 1))),
+                structureHolder("example:custom"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("minecraft:nether_complexes")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(custom), index(List.of(), List.of()), Set.of(), control);
+
+        assertSame(custom, selection.structureSets().getFirst());
+    }
+
+    @Test
+    public void frequencyOnlyPassRebindsDependentExclusionTarget() {
+        Holder<StructureSet> target = structureSetHolder(
+                "example:target",
+                new RandomSpreadStructurePlacement(27, 4, RandomSpreadType.LINEAR, 30084232),
+                structureHolder("example:target"));
+        RandomSpreadStructurePlacement dependentPlacement = new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                StructurePlacement.FrequencyReductionMethod.DEFAULT,
+                1.0F,
+                4567,
+                Optional.of(new StructurePlacement.ExclusionZone(target, 1)),
+                32,
+                8,
+                RandomSpreadType.LINEAR);
+        Holder<StructureSet> dependent = structureSetHolder(
+                "example:dependent",
+                dependentPlacement,
+                structureHolder("example:dependent"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:target")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(dependent, target), index(List.of(), List.of()), Set.of(), control);
+
+        Holder<StructureSet> scaledDependent = selection.structureSets().get(0);
+        Holder<StructureSet> scaledTarget = selection.structureSets().get(1);
+        assertNotSame(dependent, scaledDependent);
+        assertNotSame(target, scaledTarget);
+        assertSame(scaledTarget, NativeStructureSetFilter.exclusionZone(
+                scaledDependent.value().placement()).orElseThrow().otherSet());
+        assertEquals(26, ((RandomSpreadStructurePlacement)
+                scaledTarget.value().placement()).spacing());
+    }
+
+    @Test
+    public void frequencyOnlyPassRebindsAffectedExclusionCycle() {
+        MutableStructureSetHolder first = new MutableStructureSetHolder("example:first");
+        MutableStructureSetHolder second = new MutableStructureSetHolder("example:second");
+        first.bind(structureSet(
+                new RandomSpreadStructurePlacement(
+                        Vec3i.ZERO,
+                        StructurePlacement.FrequencyReductionMethod.DEFAULT,
+                        1.0F,
+                        101,
+                        Optional.of(new StructurePlacement.ExclusionZone(second, 1)),
+                        32,
+                        8,
+                        RandomSpreadType.LINEAR),
+                "example:first"));
+        second.bind(structureSet(
+                new RandomSpreadStructurePlacement(
+                        Vec3i.ZERO,
+                        StructurePlacement.FrequencyReductionMethod.DEFAULT,
+                        1.0F,
+                        102,
+                        Optional.of(new StructurePlacement.ExclusionZone(first, 1)),
+                        27,
+                        4,
+                        RandomSpreadType.LINEAR),
+                "example:second"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:second")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(first, second), index(List.of(), List.of()), Set.of(), control);
+
+        Holder<StructureSet> scaledFirst = selection.structureSets().get(0);
+        Holder<StructureSet> scaledSecond = selection.structureSets().get(1);
+        assertSame(scaledSecond, NativeStructureSetFilter.exclusionZone(
+                scaledFirst.value().placement()).orElseThrow().otherSet());
+        assertSame(scaledFirst, NativeStructureSetFilter.exclusionZone(
+                scaledSecond.value().placement()).orElseThrow().otherSet());
+        assertEquals(26, ((RandomSpreadStructurePlacement)
+                scaledSecond.value().placement()).spacing());
+    }
+
+    @Test
+    public void randomSpreadSubtypeUsesTheCanonicalPlacementContract() {
+        Holder<StructureSet> custom = structureSetHolder(
+                "example:custom",
+                new CustomRandomSpreadPlacement(),
+                structureHolder("example:custom"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:custom")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(custom), index(List.of(), List.of()), Set.of(), control);
+        StructurePlacement placement = selection.structureSets().getFirst().value().placement();
+
+        assertEquals(RandomSpreadStructurePlacement.class, placement.getClass());
+        assertEquals(26, ((RandomSpreadStructurePlacement) placement).spacing());
+    }
+
+    @Test
+    public void excludedManagedSetCannotSuppressAnAllowedSetThroughExclusionZone() {
+        Holder<StructureSet> managedSet = structureSetHolder(
+                "managed:blocked",
+                structureHolder("managed:blocked"));
+        RandomSpreadStructurePlacement originalPlacement = new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                StructurePlacement.FrequencyReductionMethod.DEFAULT,
+                1.0F,
+                4567,
+                Optional.of(new StructurePlacement.ExclusionZone(managedSet, 1)),
+                32,
+                8,
+                RandomSpreadType.LINEAR);
+        Holder<StructureSet> vanillaSet = structureSetHolder(
+                "minecraft:allowed",
+                originalPlacement,
+                structureHolder("minecraft:village_plains"));
+        DatapackStructureScopeIndex index = index(
+                List.of("managed:blocked"),
+                List.of("managed:blocked"));
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(vanillaSet, managedSet), index, Set.of());
+
+        assertEquals(1, selection.structureSets().size());
+        StructurePlacement scopedPlacement = selection.structureSets().getFirst().value().placement();
+        assertEquals(0, NativeStructureSetFilter.exclusionZone(scopedPlacement).stream().count());
+    }
+
+    private static DatapackStructureScopeIndex index(
+            List<String> structureKeys,
+            List<String> structureSetKeys
+    ) {
+        return DatapackStructureScopeIndex.create(List.of(
+                new DatapackIngestService.StructureScopeResources(
+                        SOURCE,
+                        structureKeys,
+                        structureSetKeys)));
+    }
+
+    private static Holder<Structure> structureHolder(String key) {
+        return new KeyedHolder<>(ResourceKey.create(Registries.STRUCTURE, Identifier.parse(key)), null);
+    }
+
+    private static Holder<StructureSet> structureSetHolder(
+            String key,
+            Holder<Structure>... structures
+    ) {
+        return structureSetHolder(
+                key,
+                new RandomSpreadStructurePlacement(32, 8, RandomSpreadType.LINEAR, 12345),
+                structures);
+    }
+
+    private static Holder<StructureSet> structureSetHolder(
+            String key,
+            StructurePlacement placement,
+            Holder<Structure>... structures
+    ) {
+        List<StructureSet.StructureSelectionEntry> entries = Stream.of(structures)
+                .map(structure -> new StructureSet.StructureSelectionEntry(structure, 1))
+                .toList();
+        StructureSet value = new StructureSet(entries, placement);
+        return new KeyedHolder<>(
+                ResourceKey.create(Registries.STRUCTURE_SET, Identifier.parse(key)),
+                value);
+    }
+
+    private static StructureSet structureSet(StructurePlacement placement, String structureKey) {
+        return new StructureSet(
+                List.of(new StructureSet.StructureSelectionEntry(
+                        structureHolder(structureKey), 1)),
+                placement);
+    }
+
+    private static final class KeyedHolder<T> implements Holder<T> {
+        private final ResourceKey<T> key;
+        private final T value;
+
+        private KeyedHolder(ResourceKey<T> key, T value) {
+            this.key = key;
+            this.value = value;
+        }
+
+        @Override
+        public T value() {
+            return value;
+        }
+
+        @Override
+        public boolean isBound() {
+            return true;
+        }
+
+        @Override
+        public boolean areComponentsBound() {
+            return true;
+        }
+
+        @Override
+        public boolean is(Identifier identifier) {
+            return key.identifier().equals(identifier);
+        }
+
+        @Override
+        public boolean is(ResourceKey<T> candidate) {
+            return key.equals(candidate);
+        }
+
+        @Override
+        public boolean is(Predicate<ResourceKey<T>> predicate) {
+            return predicate.test(key);
+        }
+
+        @Override
+        public boolean is(TagKey<T> tag) {
+            return false;
+        }
+
+        @Override
+        public boolean is(Holder<T> holder) {
+            return holder == this;
+        }
+
+        @Override
+        public Stream<TagKey<T>> tags() {
+            return Stream.empty();
+        }
+
+        @Override
+        public DataComponentMap components() {
+            return DataComponentMap.EMPTY;
+        }
+
+        @Override
+        public Either<ResourceKey<T>, T> unwrap() {
+            return Either.left(key);
+        }
+
+        @Override
+        public Optional<ResourceKey<T>> unwrapKey() {
+            return Optional.of(key);
+        }
+
+        @Override
+        public Kind kind() {
+            return Kind.REFERENCE;
+        }
+
+        @Override
+        public boolean canSerializeIn(HolderOwner<T> owner) {
+            return true;
+        }
+    }
+
+    private static final class UnsupportedPlacement extends StructurePlacement {
+        private UnsupportedPlacement(Optional<ExclusionZone> exclusionZone) {
+            super(Vec3i.ZERO, FrequencyReductionMethod.DEFAULT, 1F, 1, exclusionZone);
+        }
+
+        @Override
+        protected boolean isPlacementChunk(ChunkGeneratorStructureState state, int x, int z) {
+            return false;
+        }
+
+        @Override
+        public StructurePlacementType<?> type() {
+            return null;
+        }
+    }
+
+    private static final class MutableStructureSetHolder extends Holder.Reference<StructureSet> {
+        private MutableStructureSetHolder(String key) {
+            super(Type.STAND_ALONE, new HolderOwner<>() {
+            }, ResourceKey.create(Registries.STRUCTURE_SET, Identifier.parse(key)), null);
+        }
+
+        private void bind(StructureSet structureSet) {
+            bindValue(structureSet);
+        }
+    }
+
+    private static final class CustomRandomSpreadPlacement extends RandomSpreadStructurePlacement {
+        private CustomRandomSpreadPlacement() {
+            super(27, 4, RandomSpreadType.LINEAR, 30084232);
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NativeStructurePoiUpdatesTest.java

@@ -0,0 +1,252 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeStructurePoiUpdates;
+
+import ca.spottedleaf.moonrise.common.util.TickThread;
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.IdMapper;
+import net.minecraft.core.SectionPos;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.entity.ai.village.poi.PoiManager;
+import net.minecraft.world.entity.ai.village.poi.PoiRecord;
+import net.minecraft.world.entity.ai.village.poi.PoiSection;
+import net.minecraft.world.entity.ai.village.poi.PoiType;
+import net.minecraft.world.entity.ai.village.poi.PoiTypes;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ImposterProtoChunk;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import org.bukkit.NamespacedKey;
+import org.bukkit.craftbukkit.persistence.CraftPersistentDataTypeRegistry;
+import org.bukkit.craftbukkit.persistence.DirtyCraftPersistentDataContainer;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.FutureTask;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class NativeStructurePoiUpdatesTest {
+    private static final NamespacedKey DIRTY_SECTIONS = new NamespacedKey("iris", "native_poi_sections");
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void generationRecordsIntentBeforeSuppressingNativePoiCallbacks() {
+        Fixture fixture = new Fixture();
+        BlockPos position = new BlockPos(-31, 5, 49);
+        doAnswer(call -> {
+            assertNotNull(fixture.proto.persistentDataContainer.get(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY));
+            assertEquals(Block.UPDATE_CLIENTS | 4096, (int) call.getArgument(2));
+            fixture.proto.setBlockState(position, call.getArgument(1), 0);
+            return true;
+        }).when(fixture.world).setBlock(any(), any(), anyInt(), anyInt());
+
+        assertTrue(fixture.updates.setBlock(fixture.world, position,
+                Blocks.COMPOSTER.defaultBlockState(), Block.UPDATE_CLIENTS, 17));
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+    }
+
+    @Test
+    public void denseWritesStoreOneSectionBitAndSurvivePersistentDataRoundTrip() throws Exception {
+        Fixture fixture = new Fixture();
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                fixture.write(new BlockPos(-32 + x, 5, 48 + z), Blocks.COMPOSTER.defaultBlockState());
+            }
+        }
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+        DirtyCraftPersistentDataContainer restored = new DirtyCraftPersistentDataContainer(new CraftPersistentDataTypeRegistry());
+        restored.putAll(fixture.proto.persistentDataContainer.toTagCompound());
+        fixture.loaded.persistentDataContainer = restored;
+
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+
+        assertEquals(256L, fixture.records().getRecords(type -> true, PoiManager.Occupancy.ANY).count());
+        assertFalse(restored.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void validSectionsReconcileFinalStatesAndKeepMatchingClaimedTickets() throws Exception {
+        Fixture fixture = new Fixture();
+        BlockPos retained = new BlockPos(-31, 5, 49);
+        BlockPos replaced = new BlockPos(-30, 5, 49);
+        BlockPos removed = new BlockPos(-29, 5, 49);
+        Holder<PoiType> farmer = PoiTypes.forState(Blocks.COMPOSTER.defaultBlockState()).orElseThrow();
+        PoiSection existing = new PoiSection.Packed(true, List.of(
+                new PoiRecord.Packed(retained, farmer, 0),
+                new PoiRecord.Packed(replaced, farmer, 1),
+                new PoiRecord.Packed(removed, farmer, 1))).unpack(() -> {});
+        fixture.pois.put(SectionPos.of(retained).asLong(), existing);
+        PoiRecord retainedRecord = existing.getRecords(type -> true, PoiManager.Occupancy.ANY)
+                .filter(record -> record.getPos().equals(retained)).findFirst().orElseThrow();
+        for (BlockPos position : List.of(retained, replaced, removed)) {
+            fixture.proto.setBlockState(position, Blocks.COMPOSTER.defaultBlockState(), 0);
+        }
+        fixture.write(replaced, Blocks.BARREL.defaultBlockState());
+        fixture.write(removed, Blocks.AIR.defaultBlockState());
+
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+
+        assertEquals(PoiTypes.forState(Blocks.BARREL.defaultBlockState()), existing.getType(replaced));
+        assertTrue(existing.getType(removed).isEmpty());
+        assertSame(retainedRecord, existing.getRecords(type -> true, PoiManager.Occupancy.ANY)
+                .filter(record -> record.getPos().equals(retained)).findFirst().orElseThrow());
+        assertEquals(0, existing.getFreeTickets(retained));
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+        assertEquals(0, existing.getFreeTickets(retained));
+    }
+
+    @Test
+    public void failedReconciliationRetainsIntentForRetry() throws Exception {
+        Fixture fixture = new Fixture();
+        fixture.write(new BlockPos(-31, 5, 49), Blocks.COMPOSTER.defaultBlockState());
+        IllegalStateException failure = new IllegalStateException("POI storage failure");
+        doThrow(failure).when(fixture.manager).add(any(), any());
+
+        onOwner(() -> assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> NativeStructurePoiUpdates.reconcile(fixture.loaded))));
+
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+        fixture.allowPoiAdds();
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void explicitPoiSuppressionAndReadOnlyFullChunksDoNotCreateIntent() {
+        Fixture fixture = new Fixture();
+        BlockPos position = new BlockPos(-31, 5, 49);
+        fixture.updates.setBlock(fixture.world, position, Blocks.COMPOSTER.defaultBlockState(),
+                4096, 17);
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+        ImposterProtoChunk full = mock(ImposterProtoChunk.class);
+        when(fixture.world.getChunk(any(BlockPos.class))).thenReturn(full);
+        fixture.updates.setBlock(fixture.world, position, Blocks.BARREL.defaultBlockState(), 2, 17);
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void invalidSectionBitsRetainTheStoredRecord() throws Exception {
+        Fixture fixture = new Fixture();
+        fixture.proto.persistentDataContainer.set(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY, new long[]{1L << 24});
+        onOwner(() -> assertThrows(IllegalArgumentException.class,
+                () -> NativeStructurePoiUpdates.reconcile(fixture.loaded)));
+        assertArrayEquals(new long[]{1L << 24}, fixture.marker());
+    }
+
+    private static void onOwner(Runnable action) throws Exception {
+        FutureTask<Void> task = new FutureTask<>(action, null);
+        new TickThread(task, "Native POI test").start();
+        task.get(5L, TimeUnit.SECONDS);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blocks = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> biome = Holder.direct((Biome) null);
+        biomeIds.add(biome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(name -> biome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(blocks, air, PalettedContainer.codecRW(BlockState.CODEC, blocks, air),
+                biomes, biome, PalettedContainer.codecRO(biomeCodec, biomes, biome),
+                PalettedContainer.codecRW(biomeCodec, biomes, biome));
+    }
+
+    private static final class Fixture {
+        private final NativeStructurePoiUpdates updates = new NativeStructurePoiUpdates(4096);
+        private final ProtoChunk proto = new ProtoChunk(new ChunkPos(-2, 3), UpgradeData.EMPTY,
+                LevelHeightAccessor.create(-64, 384), containerFactory(), null);
+        private final LevelChunk loaded = mock(LevelChunk.class);
+        private final WorldGenLevel world = mock(WorldGenLevel.class);
+        private final PoiManager manager = mock(PoiManager.class);
+        private final Map<Long, PoiSection> pois = new HashMap<>();
+
+        private Fixture() {
+            ServerLevel level = mock(ServerLevel.class);
+            when(level.getPoiManager()).thenReturn(manager);
+            loaded.persistentDataContainer = proto.persistentDataContainer;
+            when(loaded.getLevel()).thenReturn(level);
+            when(loaded.getPos()).thenReturn(proto.getPos());
+            when(loaded.getSectionsCount()).thenReturn(proto.getSectionsCount());
+            when(loaded.getSectionYFromSectionIndex(anyInt())).thenAnswer(call -> proto.getSectionYFromSectionIndex(call.getArgument(0)));
+            when(loaded.getSection(anyInt())).thenAnswer(call -> proto.getSection(call.getArgument(0)));
+            when(loaded.getBlockState(any())).thenAnswer(call -> proto.getBlockState(call.getArgument(0)));
+            when(world.getChunk(any(BlockPos.class))).thenReturn(proto);
+            when(world.setBlock(any(), any(), anyInt(), anyInt())).thenAnswer(call -> {
+                proto.setBlockState(call.getArgument(0), call.getArgument(1), call.getArgument(2));
+                return true;
+            });
+            when(manager.getOrLoad(anyLong())).thenAnswer(call -> Optional.ofNullable(pois.get((long) call.getArgument(0))));
+            when(manager.getType(any())).thenAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                PoiSection section = pois.get(SectionPos.of(position).asLong());
+                return section == null ? Optional.empty() : section.getType(position);
+            });
+            doAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                pois.get(SectionPos.of(position).asLong()).remove(position);
+                return null;
+            }).when(manager).remove(any());
+            allowPoiAdds();
+        }
+
+        private void allowPoiAdds() {
+            doAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                return pois.computeIfAbsent(SectionPos.of(position).asLong(), ignored -> new PoiSection(() -> {}))
+                        .add(position, call.getArgument(1));
+            }).when(manager).add(any(), any());
+        }
+
+        private void write(BlockPos position, BlockState state) {
+            updates.setBlock(world, position, state, Block.UPDATE_CLIENTS, Block.UPDATE_LIMIT);
+        }
+
+        private long[] marker() {
+            return proto.persistentDataContainer.get(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY);
+        }
+
+        private PoiSection records() {
+            return pois.get(SectionPos.of(new BlockPos(-31, 5, 49)).asLong());
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NativeStructureWorldgenAccessTest.java

@@ -0,0 +1,466 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeStructureWorldgenAccess;
+
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructurePostProcessor;
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureTerrainIntegrator;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.entity.Entity;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.entity.EntityTypeTest;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.GravityProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.material.Fluid;
+import net.minecraft.world.level.material.FluidState;
+import net.minecraft.world.phys.AABB;
+import net.minecraft.world.phys.Vec3;
+import net.minecraft.world.ticks.LevelTickAccess;
+import net.minecraft.world.ticks.ScheduledTick;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureWorldgenAccessTest {
+    private static final int GENERATION_CENTER_X = 60;
+    private static final int GENERATION_CENTER_Z = 15;
+    private static final int SURFACE_FIRST_FREE_Y = 80;
+    private static final int FLOOR_FIRST_FREE_Y = 70;
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void ordinaryWorldFlattenPreparationHandlesReferencedVillagePiecesBeyondEightChunks() {
+        int farX = (GENERATION_CENTER_X - 9) << 4;
+        int farZ = (GENERATION_CENTER_Z + 4) << 4;
+        BoundingBox bounds = new BoundingBox(farX, 64, farZ, farX + 4, 90, farZ + 4);
+        PoolElementStructurePiece piece = new PoolElementStructurePiece(
+                null, StructurePoolElement.single("minecraft:empty").apply(StructureTemplatePool.Projection.RIGID),
+                new BlockPos(farX, 64, farZ), 1, Rotation.NONE, bounds, LiquidSettings.APPLY_WATERLOGGING);
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(
+                HolderSet.empty(), Map.of(), GenerationStep.Decoration.SURFACE_STRUCTURES, TerrainAdjustment.BEARD_BOX));
+        StructureStart start = new StructureStart(structure, generationCenter(), 0, new PiecesContainer(List.of(piece)));
+        List<NativeStructureTerrainIntegrator.TerrainTarget> targets = List.of(
+                new NativeStructureTerrainIntegrator.TerrainTarget("minecraft:village_plains", start,
+                        new IrisStructureTerrain().setMode(StructureTerrainMode.FLATTEN)));
+        BoundingBox area = new BoundingBox(generationCenter().getMinBlockX(), -64, generationCenter().getMinBlockZ(),
+                generationCenter().getMaxBlockX(), 319, generationCenter().getMaxBlockZ());
+        RecordingDelegate unbounded = new RecordingDelegate();
+        unbounded.rejectDistantTerrainReads = true;
+
+        assertThrows(IllegalStateException.class, () -> NativeStructurePostProcessor.prepareTerrain(
+                unbounded.world(), area, targets, (palette, rng, x, y, z) -> Blocks.STONE.defaultBlockState()));
+
+        RecordingDelegate recording = new RecordingDelegate();
+        recording.rejectDistantTerrainReads = true;
+        NativeStructureWorldgenAccess access = access(recording);
+        NativeStructurePostProcessor.prepareTerrain(
+                access, area, targets, (palette, rng, x, y, z) -> Blocks.STONE.defaultBlockState());
+
+        assertEquals(0, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+        assertEquals(0, recording.terrainReads);
+        assertEquals(0, recording.mutations);
+        assertEquals(91, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG,
+                generationCenter().getMinBlockX(), generationCenter().getMinBlockZ()));
+        assertEquals(1, recording.heightReads);
+    }
+
+    @Test
+    public void projectedTemplatePrefiltersUseRemoteTerrainAndRetainLocalHeightmaps() {
+        RecordingDelegate recording = new RecordingDelegate();
+        recording.rejectDistantTerrainReads = true;
+        NativeStructureWorldgenAccess access = access(recording);
+        GravityProcessor gravity = new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, -1);
+        BlockPos remote = new BlockPos((GENERATION_CENTER_X - 9) << 4, 64, (GENERATION_CENTER_Z + 4) << 4);
+        StructureTemplate.StructureBlockInfo raw = new StructureTemplate.StructureBlockInfo(
+                new BlockPos(0, 4, 0), Blocks.DIRT_PATH.defaultBlockState(), null);
+        StructurePlaceSettings settings = new StructurePlaceSettings().addProcessor(gravity);
+
+        StructureTemplate.StructureBlockInfo projected = StructureTemplate.processBlockInfos(
+                access, remote, BlockPos.ZERO, settings, List.of(raw)).getFirst();
+
+        assertEquals(remote.atY(SURFACE_FIRST_FREE_Y + 3), projected.pos());
+        assertEquals(0, recording.heightReads);
+        BlockPos local = generationCenter().getMiddleBlockPosition(64);
+        StructureTemplate.StructureBlockInfo localBlock = new StructureTemplate.StructureBlockInfo(
+                BlockPos.ZERO, Blocks.DIRT_PATH.defaultBlockState(), null);
+        StructureTemplate.StructureBlockInfo localProjection = StructureTemplate.processBlockInfos(
+                access, local, BlockPos.ZERO, settings, List.of(localBlock)).getFirst();
+        assertEquals(local.atY(90), localProjection.pos());
+        assertEquals(1, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+    }
+
+    @Test
+    public void distanceTwoTerrainReadsNeverReachTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        int x = generationCenter.getMiddleBlockX();
+        int z = (generationCenter.z() + 2) << 4;
+
+        assertSame(Blocks.STONE, access.getBlockState(new BlockPos(x, FLOOR_FIRST_FREE_Y - 1, z)).getBlock());
+        assertSame(Blocks.WATER, access.getBlockState(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)).getBlock());
+        assertSame(Blocks.AIR, access.getBlockState(new BlockPos(x, SURFACE_FIRST_FREE_Y, z)).getBlock());
+        assertSame(Blocks.WATER.defaultBlockState().getFluidState(),
+                access.getFluidState(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)));
+        assertEquals(SURFACE_FIRST_FREE_Y, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z));
+        assertEquals(FLOOR_FIRST_FREE_Y, access.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, x, z));
+        assertNull(access.getBlockStateIfLoaded(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)));
+        assertNull(access.getChunk(generationCenter.x(), generationCenter.z() + 2, ChunkStatus.FEATURES, false));
+        assertNull(access.getChunkIfLoadedImmediately(
+                generationCenter.x(), generationCenter.z() + 2));
+        List<BlockState> streamed = access.getBlockStates(new AABB(
+                x, FLOOR_FIRST_FREE_Y, z, x, FLOOR_FIRST_FREE_Y, z)).toList();
+
+        assertEquals(1, streamed.size());
+        assertSame(Blocks.WATER, streamed.getFirst().getBlock());
+        assertEquals(0, recording.terrainReads);
+        assertEquals(0, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+    }
+
+    @Test
+    public void distanceTwoMutationsAndSideEffectsNeverReachTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        BlockPos position = new BlockPos(
+                generationCenter.getMiddleBlockX(),
+                FLOOR_FIRST_FREE_Y,
+                (generationCenter.z() + 2) << 4);
+
+        assertFalse(access.ensureCanWrite(position));
+        assertFalse(access.setBlock(position, Blocks.DIRT.defaultBlockState(), 2));
+        assertFalse(access.removeBlock(position, false));
+        assertFalse(access.destroyBlock(position, false));
+        access.updateNeighborsAt(position, Blocks.DIRT);
+        access.neighborShapeChanged(
+                Direction.NORTH, position, position.north(),
+                Blocks.DIRT.defaultBlockState(), 2, 512);
+        access.levelEvent(null, 2001, position, 0);
+        access.gameEvent(null, Vec3.atCenterOf(position), null);
+        access.addParticle(null, position.getX(), position.getY(), position.getZ(), 0, 0, 0);
+        access.getBlockTicks().schedule(new ScheduledTick<>(
+                Blocks.DIRT, position, 1L, 0L));
+
+        assertEquals(0, recording.mutations);
+        assertEquals(0, recording.events);
+        assertEquals(0, recording.blockTicks.count());
+    }
+
+    @Test
+    public void radiusOneReadsWritesAndTicksRemainUnchanged() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        BlockPos position = new BlockPos(
+                (generationCenter.x() + 1) << 4,
+                FLOOR_FIRST_FREE_Y,
+                (generationCenter.z() - 1) << 4);
+
+        assertTrue(access.isInsideGenerationRegion(
+                generationCenter.x() + 1, generationCenter.z() - 1));
+        assertSame(Blocks.DIRT, access.getBlockState(position).getBlock());
+        assertEquals(91, access.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, position.getX(), position.getZ()));
+        assertTrue(access.ensureCanWrite(position));
+        assertTrue(access.setBlock(position, Blocks.STONE.defaultBlockState(), 2));
+        assertTrue(access.removeBlock(position, false));
+        assertTrue(access.destroyBlock(position, false));
+        access.getBlockTicks().schedule(new ScheduledTick<>(
+                Blocks.DIRT, position, 1L, 0L));
+
+        assertEquals(1, recording.terrainReads);
+        assertEquals(1, recording.heightReads);
+        assertEquals(4, recording.mutations);
+        assertEquals(1, recording.blockTicks.count());
+    }
+
+    @Test
+    public void virtualizedHeightsHideInRegionTerrainFromTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        ChunkPos generationCenter = generationCenter();
+        NativeStructureWorldgenAccess access = NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter,
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                true,
+                position -> false);
+        int x = generationCenter.getMiddleBlockX();
+        int z = generationCenter.getMiddleBlockZ();
+
+        assertEquals(SURFACE_FIRST_FREE_Y, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z));
+        assertEquals(FLOOR_FIRST_FREE_Y, access.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, x, z));
+        assertEquals(0, recording.heightReads);
+    }
+
+    @Test
+    public void protectedCellsRemainReadableButRejectWritesTilesAndTicks() {
+        RecordingDelegate recording = new RecordingDelegate();
+        BlockPos position = generationCenter().getMiddleBlockPosition(70);
+        NativeStructureWorldgenAccess access = NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter(),
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                false,
+                position::equals);
+
+        assertSame(Blocks.DIRT, access.getBlockState(position).getBlock());
+        assertFalse(access.ensureCanWrite(position));
+        assertFalse(access.setBlock(position, Blocks.STONE.defaultBlockState(), 2));
+        assertFalse(access.removeBlock(position, false));
+        assertFalse(access.destroyBlock(position, false));
+        assertNull(access.getBlockEntity(position));
+        assertTrue(access.getBlockEntity(position, null).isEmpty());
+        access.getBlockTicks().schedule(new ScheduledTick<>(Blocks.DIRT, position, 1L, 0L));
+        access.updateNeighborsAt(position.east(), Blocks.DIRT);
+        access.neighborShapeChanged(
+                Direction.EAST, position, position.east(), Blocks.DIRT.defaultBlockState(), 2, 512);
+
+        assertEquals(1, recording.terrainReads);
+        assertEquals(0, recording.mutations);
+        assertEquals(0, recording.blockTicks.count());
+        assertTrue(access.setBlock(position.above(), Blocks.STONE.defaultBlockState(), 2));
+        assertEquals(1, recording.mutations);
+    }
+
+    @Test
+    public void statuslessChunkReadsPreserveWorldgenDelegateSemantics() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+
+        assertNull(access.getChunk(generationCenter.getWorldPosition()));
+
+        assertEquals(1, recording.statuslessChunkReads);
+        assertEquals(0, recording.statusChunkReads);
+    }
+
+    @Test
+    public void entityQueriesRejectDisjointAreasAndClampOverlaps() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        int safeMaxX = generationCenter.getMaxBlockX() + 17;
+        int safeMinZ = generationCenter.getMinBlockZ() - 16;
+        int safeMaxZ = generationCenter.getMaxBlockZ() + 17;
+        AABB disjoint = new AABB(
+                safeMaxX, -64, safeMinZ,
+                safeMaxX + 16, 320, safeMaxZ);
+        AABB overlap = new AABB(
+                safeMaxX - 8, -128, safeMinZ - 8,
+                safeMaxX + 16, 400, safeMaxZ + 8);
+        EntityTypeTest<Entity, Entity> type = EntityTypeTest.forClass(Entity.class);
+
+        assertTrue(access.getEntities((Entity) null, disjoint, entity -> true).isEmpty());
+        assertTrue(access.getEntities(type, disjoint, entity -> true).isEmpty());
+        access.getEntities((Entity) null, overlap, entity -> true);
+        access.getEntities(type, overlap, entity -> true);
+
+        assertEquals(2, recording.entityAreas.size());
+        for (AABB delegatedArea : recording.entityAreas) {
+            assertEquals(safeMaxX - 8, delegatedArea.minX, 0D);
+            assertEquals(-64, delegatedArea.minY, 0D);
+            assertEquals(safeMinZ, delegatedArea.minZ, 0D);
+            assertEquals(safeMaxX, delegatedArea.maxX, 0D);
+            assertEquals(320, delegatedArea.maxY, 0D);
+            assertEquals(safeMaxZ, delegatedArea.maxZ, 0D);
+        }
+    }
+
+    private static NativeStructureWorldgenAccess access(RecordingDelegate recording) {
+        return NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter(),
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                false,
+                position -> false);
+    }
+
+    private static ChunkPos generationCenter() {
+        return new ChunkPos(GENERATION_CENTER_X, GENERATION_CENTER_Z);
+    }
+
+    private static final class RecordingDelegate implements InvocationHandler {
+        private final Holder<Biome> biome;
+        private final BiomeManager biomeManager;
+        private final RecordingTicks<Block> blockTicks;
+        private final RecordingTicks<Fluid> fluidTicks;
+        private final List<AABB> entityAreas;
+        private int terrainReads;
+        private int heightReads;
+        private int chunkReads;
+        private int statuslessChunkReads;
+        private int statusChunkReads;
+        private int mutations;
+        private int events;
+        private boolean rejectDistantTerrainReads;
+
+        private RecordingDelegate() {
+            this.biome = Holder.direct((Biome) null);
+            this.biomeManager = new BiomeManager((x, y, z) -> biome, 13L);
+            this.blockTicks = new RecordingTicks<>();
+            this.fluidTicks = new RecordingTicks<>();
+            this.entityAreas = new ArrayList<>();
+        }
+
+        private WorldGenLevel world() {
+            return (WorldGenLevel) Proxy.newProxyInstance(
+                    WorldGenLevel.class.getClassLoader(),
+                    new Class<?>[]{WorldGenLevel.class}, this);
+        }
+
+        @Override
+        public Object invoke(Object proxy, Method method, Object[] arguments) {
+            String name = method.getName();
+            if (name.equals("getSeaLevel")) {
+                return 63;
+            }
+            if (name.equals("getBiome")) {
+                return biome;
+            }
+            if (name.equals("getBiomeManager")) {
+                return biomeManager;
+            }
+            if (name.equals("getBlockTicks")) {
+                return blockTicks;
+            }
+            if (name.equals("getFluidTicks")) {
+                return fluidTicks;
+            }
+            if (name.equals("getMinY")) {
+                return -64;
+            }
+            if (name.equals("getHeight") && arguments == null) {
+                return 384;
+            }
+            if (name.equals("getHeight")) {
+                if (rejectDistantTerrainReads
+                        && (Math.abs(((int) arguments[1] >> 4) - GENERATION_CENTER_X) > 1
+                        || Math.abs(((int) arguments[2] >> 4) - GENERATION_CENTER_Z) > 1)) {
+                    throw new IllegalStateException("Requested chunk unavailable during world generation");
+                }
+                heightReads++;
+                return 91;
+            }
+            if (name.equals("getBlockState")) {
+                terrainReads++;
+                return Blocks.DIRT.defaultBlockState();
+            }
+            if (name.equals("getFluidState")) {
+                terrainReads++;
+                return Blocks.WATER.defaultBlockState().getFluidState();
+            }
+            if (name.equals("getChunk")) {
+                chunkReads++;
+                if (arguments.length == 2) {
+                    statuslessChunkReads++;
+                } else {
+                    statusChunkReads++;
+                }
+                return null;
+            }
+            if (name.equals("getChunkIfLoadedImmediately")) {
+                chunkReads++;
+                return null;
+            }
+            if (name.equals("getEntities")) {
+                entityAreas.add((AABB) arguments[1]);
+                return List.of();
+            }
+            if (name.equals("ensureCanWrite") || name.equals("setBlock")
+                    || name.equals("removeBlock") || name.equals("destroyBlock")) {
+                mutations++;
+                return true;
+            }
+            if (name.equals("updateNeighborsAt") || name.equals("neighborShapeChanged")) {
+                mutations++;
+                return null;
+            }
+            if (name.equals("levelEvent") || name.equals("gameEvent") || name.equals("addParticle")) {
+                events++;
+                return null;
+            }
+            if (name.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (name.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (name.equals("toString")) {
+                return "native-structure-worldgen-test-delegate";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        }
+    }
+
+    private static final class RecordingTicks<T> implements LevelTickAccess<T> {
+        private int count;
+
+        @Override
+        public void schedule(ScheduledTick<T> tick) {
+            count++;
+        }
+
+        @Override
+        public boolean hasScheduledTick(BlockPos position, T type) {
+            return false;
+        }
+
+        @Override
+        public int count() {
+            return count;
+        }
+
+        @Override
+        public boolean willTickThisTick(BlockPos position, T type) {
+            return false;
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NmsChunkIOFlushTest.java

@@ -0,0 +1,101 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeTerrainAccessImpl;
+import ca.spottedleaf.moonrise.patches.chunk_system.io.MoonriseRegionFileIO.RegionDataController;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ServerLevel;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkIOFlushTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void nativeDrainCanWaitOffOwnerUntilChunkPoiAndEntityIoFinish() throws Exception {
+        Fixture fixture = new Fixture();
+        AtomicBoolean chunkPending = new AtomicBoolean(true);
+        AtomicBoolean poiPending = new AtomicBoolean(true);
+        AtomicBoolean entityPending = new AtomicBoolean(true);
+        CountDownLatch chunkDrain = new CountDownLatch(1);
+        CountDownLatch poiDrain = new CountDownLatch(1);
+        CountDownLatch entityDrain = new CountDownLatch(1);
+        when(fixture.chunks.hasTasks()).thenAnswer(invocation -> {
+            chunkDrain.countDown();
+            return chunkPending.get();
+        });
+        when(fixture.pois.hasTasks()).thenAnswer(invocation -> {
+            poiDrain.countDown();
+            return poiPending.get();
+        });
+        when(fixture.entities.hasTasks()).thenAnswer(invocation -> {
+            entityDrain.countDown();
+            return entityPending.get();
+        });
+        ExecutorService io = Executors.newSingleThreadExecutor();
+        try {
+            Future<?> drain = io.submit(() -> fixture.binding.flushChunkIO(fixture.world));
+            assertTrue(chunkDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            chunkPending.set(false);
+            assertTrue(poiDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            poiPending.set(false);
+            assertTrue(entityDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            entityPending.set(false);
+            drain.get(5L, TimeUnit.SECONDS);
+        } finally {
+            chunkPending.set(false);
+            poiPending.set(false);
+            entityPending.set(false);
+            io.shutdownNow();
+            assertTrue(io.awaitTermination(5L, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void nativeDrainFailurePropagatesToItsCompletionReceipt() {
+        Fixture fixture = new Fixture();
+        IllegalStateException failure = new IllegalStateException("native IO failed");
+        when(fixture.chunks.hasTasks()).thenThrow(failure);
+        assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> fixture.binding.flushChunkIO(fixture.world)));
+    }
+
+    private static final class Fixture {
+        private final NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        private final CraftWorld world = mock(CraftWorld.class);
+        private final ServerLevel level = mock(ServerLevel.class);
+        private final RegionDataController chunks = mock(RegionDataController.class);
+        private final RegionDataController pois = mock(RegionDataController.class);
+        private final RegionDataController entities = mock(RegionDataController.class);
+
+        private Fixture() {
+            when(world.getHandle()).thenReturn(level);
+            when(level.moonrise$getChunkDataController()).thenReturn(chunks);
+            when(level.moonrise$getPoiChunkDataController()).thenReturn(pois);
+            when(level.moonrise$getEntityChunkDataController()).thenReturn(entities);
+        }
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NmsChunkRetentionTest.java

@@ -0,0 +1,84 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeTerrainAccessImpl;
+import ca.spottedleaf.moonrise.patches.chunk_system.scheduling.ChunkHolderManager;
+import ca.spottedleaf.moonrise.patches.chunk_system.scheduling.ChunkTaskScheduler;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ChunkLevel;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.TicketType;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.lang.reflect.Field;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.ArgumentMatchers.same;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkRetentionTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void retentionRequestsNothingBeyondTheOuterRingOfAFullRequest() {
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        assertEquals(ChunkLevel.RADIUS_AROUND_FULL_CHUNK, binding.fullChunkDependencyRadius());
+        assertEquals(ChunkLevel.MAX_LEVEL, ChunkHolderManager.MAX_TICKET_LEVEL);
+        assertEquals(ChunkLevel.generationStatus(ChunkLevel.FULL_CHUNK_LEVEL + binding.fullChunkDependencyRadius()),
+                ChunkLevel.generationStatus(ChunkHolderManager.MAX_TICKET_LEVEL));
+        assertEquals(ChunkStatus.STRUCTURE_STARTS, ChunkLevel.generationStatus(ChunkHolderManager.MAX_TICKET_LEVEL));
+    }
+
+    @Test
+    public void retainAndReleaseUseOnePermanentNonPersistentTicketAtTheMaximumLevel() throws Exception {
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        ChunkTaskScheduler scheduler = mock(ChunkTaskScheduler.class);
+        ChunkHolderManager manager = mock(ChunkHolderManager.class);
+        Field managerField = ChunkTaskScheduler.class.getField("chunkHolderManager");
+        managerField.setAccessible(true);
+        managerField.set(scheduler, manager);
+        when(world.getHandle()).thenReturn(level);
+        when(level.moonrise$getChunkTaskScheduler()).thenReturn(scheduler);
+        when(manager.addTicketAtLevel(any(TicketType.class), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull()))
+                .thenReturn(true);
+        when(manager.removeTicketAtLevel(any(TicketType.class), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull()))
+                .thenReturn(true);
+
+        assertTrue(binding.retainChunk(world, 3, -4));
+        ArgumentCaptor<TicketType> type = ArgumentCaptor.forClass(TicketType.class);
+        verify(manager).addTicketAtLevel(type.capture(), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+        assertEquals(TicketType.NO_TIMEOUT, type.getValue().timeout());
+        assertTrue(type.getValue().doesLoad());
+        assertFalse(type.getValue().doesSimulate());
+        assertFalse(type.getValue().persist());
+
+        assertTrue(binding.releaseChunk(world, 3, -4));
+        verify(manager).removeTicketAtLevel(same(type.getValue()), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+
+        binding.retainChunk(world, 3, -4);
+        ArgumentCaptor<TicketType> again = ArgumentCaptor.forClass(TicketType.class);
+        verify(manager, times(2)).addTicketAtLevel(again.capture(), eq(3), eq(-4),
+                eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+        assertSame(type.getValue(), again.getValue());
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NmsChunkTaskPollingTest.java

@@ -0,0 +1,96 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeTerrainAccessImpl;
+import art.arcane.volmlib.util.scheduling.FoliaScheduler;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerChunkCache;
+import net.minecraft.server.level.ServerLevel;
+import org.bukkit.Bukkit;
+import org.bukkit.Server;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.util.concurrent.CompletableFuture;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkTaskPollingTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void serverOwnerPumpsOnlyTheTargetWorldQueue() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        MinecraftServer server = mock(MinecraftServer.class);
+        ServerChunkCache chunks = mock(ServerChunkCache.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        CompletableFuture<Void> completed = new CompletableFuture<>();
+        when(world.getHandle()).thenReturn(level);
+        when(level.getServer()).thenReturn(server);
+        when(server.getRunningThread()).thenReturn(Thread.currentThread());
+        when(level.getChunkSource()).thenReturn(chunks);
+        when(chunks.pollTask()).thenAnswer(invocation -> completed.complete(null)).thenReturn(false);
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(false);
+            assertTrue(binding.pollChunkTask(world));
+            assertTrue(completed.isDone());
+            assertFalse(binding.pollChunkTask(world));
+        }
+        verify(chunks, times(2)).pollTask();
+        verify(server, never()).executeAllRecentInternalTasks();
+    }
+
+    @Test
+    public void nonOwnerIsRejectedBeforeAccessingTheChunkQueue() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        MinecraftServer server = mock(MinecraftServer.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        when(world.getHandle()).thenReturn(level);
+        when(level.getServer()).thenReturn(server);
+        when(server.getRunningThread()).thenReturn(new Thread("Other server owner"));
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(false);
+            assertThrows(IllegalStateException.class, () -> binding.pollChunkTask(world));
+        }
+        verify(level, never()).getChunkSource();
+    }
+
+    @Test
+    public void foliaNeverUsesTheWorldWideTaskPump() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(true);
+            assertFalse(binding.pollChunkTask(world));
+        }
+        verifyNoInteractions(world);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/NmsEntitySpawnDifficultyTest.java

@@ -0,0 +1,104 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeTerrainAccessImpl;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.server.Bootstrap;
+import org.bukkit.Difficulty;
+import org.bukkit.Location;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.EntityType;
+import org.bukkit.event.entity.CreatureSpawnEvent;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+public class NmsEntitySpawnDifficultyTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void peacefulRejectsEveryNativeForbiddenTypeBeforeBukkitCreatesIt() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        int rejected = 0;
+
+        for (EntityType type : EntityType.values()) {
+            if (type.getEntityClass() == null) {
+                continue;
+            }
+            if (BuiltInRegistries.ENTITY_TYPE.getValue(Identifier.parse(type.getKey().toString())).isAllowedInPeaceful()) {
+                continue;
+            }
+            assertNull(type.name(), binding.spawnEntity(location, type, CreatureSpawnEvent.SpawnReason.NATURAL));
+            rejected++;
+        }
+
+        assertTrue(rejected > 20);
+        verify(world, never()).spawn(any(Location.class), any(Class.class), isNull(), any(CreatureSpawnEvent.SpawnReason.class));
+    }
+
+    @Test
+    public void peacefulPreservesPassiveAndNativeMonsterCategoryExceptions() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        Entity created = mock(Entity.class);
+        doReturn(created).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        for (EntityType type : List.of(EntityType.COW, EntityType.VILLAGER, EntityType.WOLF, EntityType.PIGLIN, EntityType.SHULKER)) {
+            assertSame(type.name(), created, binding.spawnEntity(location, type, CreatureSpawnEvent.SpawnReason.NATURAL));
+        }
+    }
+
+    @Test
+    public void nonPeacefulDifficultiesPreserveHostileSpawns() {
+        CraftWorld world = mock(CraftWorld.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        Entity created = mock(Entity.class);
+        doReturn(created).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        for (Difficulty difficulty : List.of(Difficulty.EASY, Difficulty.NORMAL, Difficulty.HARD)) {
+            when(world.getDifficulty()).thenReturn(difficulty);
+            assertSame(created, binding.spawnEntity(location, EntityType.ZOMBIE, CreatureSpawnEvent.SpawnReason.NATURAL));
+        }
+    }
+
+    @Test
+    public void unrelatedBukkitSpawnFailuresStillPropagate() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        IllegalStateException failure = new IllegalStateException("Spawn rejected by platform");
+        doThrow(failure).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> binding.spawnEntity(location, EntityType.COW, CreatureSpawnEvent.SpawnReason.NATURAL)));
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_2_R1/WorldgenTerrainHeightmapsTest.java

@@ -0,0 +1,345 @@
+package art.arcane.iris.platform.bukkit.nms.v26_2_R1;
+
+import art.arcane.volmlib.nativelib.v26_2_R1.terrain.NativeTerrainPipeline;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.WorldgenTerrainHeightmaps;
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.IdMapper;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.IglooPieces;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.IntBinaryOperator;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class WorldgenTerrainHeightmapsTest {
+    private static final int MIN_Y = -64;
+    private static final int HEIGHT = 384;
+    private static final int LAND_TERRAIN_TOP = 70;
+    private static final int LAND_CANOPY_TOP = 80;
+    private static final int OCEAN_FLOOR_TOP = 60;
+    private static final int OCEAN_FLUID_TOP = 64;
+    private static final int LAND_X = 3;
+    private static final int LAND_Z = 5;
+    private static final int OCEAN_X = 8;
+    private static final int OCEAN_Z = 8;
+    private static final int TERRAIN_SLAB_DEPTH = 4;
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void authoringHeightmapsReadPlacedObjectsAndFluidsWithoutTerrainResolvers() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        NativeTerrainPipeline.primeAuthoringHeightmaps(chunk);
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.MOTION_BLOCKING, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP + 6,
+                chunk.getHeight(Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, LAND_X, LAND_Z));
+        assertEquals(OCEAN_FLUID_TOP, chunk.getHeight(Heightmap.Types.WORLD_SURFACE_WG, OCEAN_X, OCEAN_Z));
+        assertEquals(OCEAN_FLOOR_TOP, chunk.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, OCEAN_X, OCEAN_Z));
+    }
+
+    @Test
+    public void primeTerrainWritesEngineSurfaceAndOceanFloorHeights() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertFalse(chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertFalse(chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertTrue(chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(OCEAN_FLUID_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, OCEAN_X, OCEAN_Z));
+        assertEquals(OCEAN_FLOOR_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, OCEAN_X, OCEAN_Z));
+    }
+
+    @Test
+    public void finalHeightmapPrimingDoesNotClobberTheWorldgenHeightmaps() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+        Heightmap.primeHeightmaps(chunk, ChunkStatus.FINAL_HEIGHTMAPS);
+
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void unprimedWorldgenHeightmapResolvesTheIrisCanopyInstead() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void primeTerrainOverwritesAnAlreadyLazyPrimedCanopyHeight() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void structurePlacementPrimesTheWestNeighbourAnIglooEntranceReads() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        chunks.put(ChunkPos.pack(0, 0), terrainChunk(new ChunkPos(0, 0)));
+        chunks.put(ChunkPos.pack(-1, 0), terrainChunk(new ChunkPos(-1, 0)));
+        WorldGenLevel world = world(chunks);
+        StructureStart start = startInOrigin();
+
+        int canopySnap = IglooPieces.GENERATION_HEIGHT + iglooSnapOffset(world);
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(start), surfaceFirstFreeY(), floorFirstFreeY());
+        int terrainSnap = IglooPieces.GENERATION_HEIGHT + iglooSnapOffset(world);
+
+        assertEquals(LAND_TERRAIN_TOP + 1, world.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, -2, 5));
+        assertEquals(LAND_TERRAIN_TOP, terrainSnap);
+        assertEquals(LAND_CANOPY_TOP, canopySnap);
+        assertEquals(LAND_CANOPY_TOP - LAND_TERRAIN_TOP, canopySnap - terrainSnap);
+    }
+
+    @Test
+    public void structurePlacementPrimesEveryChunkTheStartFootprintTouches() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        for (int chunkX = -1; chunkX <= 1; chunkX++) {
+            for (int chunkZ = -1; chunkZ <= 1; chunkZ++) {
+                chunks.put(ChunkPos.pack(chunkX, chunkZ), terrainChunk(new ChunkPos(chunkX, chunkZ)));
+            }
+        }
+        WorldGenLevel world = world(chunks);
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(startInOrigin()),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        for (ChunkAccess chunk : chunks.values()) {
+            assertTrue(chunk.getPos().toString(),
+                    chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+            assertTrue(chunk.getPos().toString(),
+                    chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+            assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                    Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        }
+    }
+
+    @Test
+    public void structurePlacementDoesNotPrimeALoadedDistanceTwoChunk() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        ProtoChunk origin = terrainChunk(new ChunkPos(0, 0));
+        ProtoChunk neighbour = terrainChunk(new ChunkPos(1, 0));
+        ProtoChunk distanceTwo = terrainChunk(new ChunkPos(2, 0));
+        chunks.put(ChunkPos.pack(0, 0), origin);
+        chunks.put(ChunkPos.pack(1, 0), neighbour);
+        chunks.put(ChunkPos.pack(2, 0), distanceTwo);
+        WorldGenLevel world = world(chunks);
+        StructureStart shifted = startInOrigin();
+        shifted.getPieces().forEach(piece -> piece.move(16, 0, 0));
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(shifted),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(origin.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertTrue(neighbour.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertFalse(distanceTwo.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+    }
+
+    @Test
+    public void structurePlacementSkipsChunksOutsideTheGenerationRegion() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        ProtoChunk origin = terrainChunk(new ChunkPos(0, 0));
+        chunks.put(ChunkPos.pack(0, 0), origin);
+        WorldGenLevel world = world(chunks);
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(startInOrigin()),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(origin.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertEquals(LAND_TERRAIN_TOP, origin.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    private static int iglooSnapOffset(WorldGenLevel world) {
+        return world.getHeight(Heightmap.Types.WORLD_SURFACE_WG, -2, 5)
+                - IglooPieces.GENERATION_HEIGHT - 1;
+    }
+
+    private static StructureStart startInOrigin() {
+        Structure structure = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece piece = new SwampHutPiece(RandomSource.create(13L), 0, 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static IntBinaryOperator surfaceFirstFreeY() {
+        return (x, z) -> isOcean(x, z) ? OCEAN_FLUID_TOP + 1 : LAND_TERRAIN_TOP + 1;
+    }
+
+    private static IntBinaryOperator floorFirstFreeY() {
+        return (x, z) -> isOcean(x, z) ? OCEAN_FLOOR_TOP + 1 : LAND_TERRAIN_TOP + 1;
+    }
+
+    private static boolean isOcean(int x, int z) {
+        return Math.floorMod(x, 16) == OCEAN_X && Math.floorMod(z, 16) == OCEAN_Z;
+    }
+
+    private static ProtoChunk terrainChunk(ChunkPos pos) {
+        ProtoChunk chunk = new ProtoChunk(
+                pos, UpgradeData.EMPTY, LevelHeightAccessor.create(MIN_Y, HEIGHT),
+                containerFactory(), null);
+        for (int x = 0; x < 16; x++) {
+            for (int z = 0; z < 16; z++) {
+                boolean ocean = isOcean(pos.getMinBlockX() + x, pos.getMinBlockZ() + z);
+                int stoneTop = ocean ? OCEAN_FLOOR_TOP : LAND_TERRAIN_TOP;
+                for (int y = stoneTop - TERRAIN_SLAB_DEPTH; y <= stoneTop; y++) {
+                    write(chunk, x, y, z, Blocks.STONE.defaultBlockState());
+                }
+                if (ocean) {
+                    for (int y = OCEAN_FLOOR_TOP + 1; y <= OCEAN_FLUID_TOP; y++) {
+                        write(chunk, x, y, z, Blocks.WATER.defaultBlockState());
+                    }
+                    continue;
+                }
+                for (int y = LAND_TERRAIN_TOP + 1; y <= LAND_TERRAIN_TOP + 6; y++) {
+                    write(chunk, x, y, z, Blocks.SPRUCE_LOG.defaultBlockState());
+                }
+                for (int y = LAND_TERRAIN_TOP + 7; y <= LAND_CANOPY_TOP; y++) {
+                    write(chunk, x, y, z, Blocks.SPRUCE_LEAVES.defaultBlockState());
+                }
+            }
+        }
+        return chunk;
+    }
+
+    private static void write(ProtoChunk chunk, int x, int y, int z, BlockState state) {
+        LevelChunkSection section = chunk.getSection(chunk.getSectionIndex(y));
+        section.setBlockState(x, y & 15, z, state, false);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blockStates = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> defaultBiome = Holder.direct((Biome) null);
+        biomeIds.add(defaultBiome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(
+                name -> defaultBiome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(
+                blockStates,
+                air,
+                PalettedContainer.codecRW(BlockState.CODEC, blockStates, air),
+                biomes,
+                defaultBiome,
+                PalettedContainer.codecRO(biomeCodec, biomes, defaultBiome),
+                PalettedContainer.codecRW(biomeCodec, biomes, defaultBiome));
+    }
+
+    private static WorldGenLevel world(Map<Long, ChunkAccess> chunks) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("hasChunk")) {
+                return chunks.containsKey(ChunkPos.pack((int) arguments[0], (int) arguments[1]));
+            }
+            if (methodName.equals("getChunk") && arguments.length == 2) {
+                ChunkAccess chunk = chunks.get(ChunkPos.pack((int) arguments[0], (int) arguments[1]));
+                if (chunk == null) {
+                    throw new AssertionError("Heightmap priming requested an unavailable chunk "
+                            + arguments[0] + "," + arguments[1]);
+                }
+                return chunk;
+            }
+            if (methodName.equals("getHeight") && arguments.length == 3) {
+                Heightmap.Types type = (Heightmap.Types) arguments[0];
+                int x = (int) arguments[1];
+                int z = (int) arguments[2];
+                ChunkAccess chunk = chunks.get(ChunkPos.pack(x >> 4, z >> 4));
+                if (chunk == null) {
+                    throw new AssertionError("Heightmap read requested an unavailable chunk at "
+                            + x + "," + z);
+                }
+                return chunk.getHeight(type, x & 15, z & 15) + 1;
+            }
+            if (methodName.equals("getBlockState")) {
+                BlockPos position = (BlockPos) arguments[0];
+                ChunkAccess chunk = chunks.get(ChunkPos.pack(position.getX() >> 4, position.getZ() >> 4));
+                if (chunk == null) {
+                    throw new AssertionError("Block read requested an unavailable chunk at " + position);
+                }
+                return chunk.getBlockState(position);
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "worldgen-heightmap-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/structure/VillageImporterListPoolElementRuntimeContractTest.java

@@ -0,0 +1,294 @@
+/*
+ * Iris is a World Generator for Minecraft Bukkit Servers
+ * Copyright (c) 2022 Arcane Arts (Volmit Software)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package art.arcane.iris.structure;
+
+import art.arcane.volmlib.nativelib.common.structure.StructureReaderFixture;
+import art.arcane.iris.structure.authoring.StructureCapability;
+import art.arcane.iris.structure.authoring.StructureLoss;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.levelgen.structure.pools.ListPoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class VillageImporterListPoolElementRuntimeContractTest {
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void pillagerOutpostTowerCompositeProducesOnePhysicalTowerChoice() throws Exception {
+        StructurePoolElement tower = StructurePoolElement.legacy("minecraft:pillager_outpost/watchtower")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        StructurePoolElement overgrown = StructurePoolElement.legacy("minecraft:pillager_outpost/watchtower_overgrown")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        ListPoolElement towers = new ListPoolElement(
+                List.of(tower, overgrown),
+                StructureTemplatePool.Projection.RIGID
+        );
+
+        VillageImporter.PoolElementResolution resolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(towers));
+        Map<String, Object> entry = VillageImporter.piecePoolEntry(
+                "qa/pillager_outpost/piece/minecraft/pillager_outpost/watchtower",
+                1
+        );
+        StructureLoss loss = VillageImporter.listElementFallbackLoss(
+                resolution,
+                "minecraft:pillager_outpost/towers"
+        );
+        Map<String, Object> basePlatePiece = VillageImporter.pieceJson(
+                "qa/pillager_outpost/piece/minecraft/pillager_outpost/base_plate",
+                List.of(Map.of("name", "minecraft:bottom")),
+                0
+        );
+        Map<String, Object> watchtowerPiece = VillageImporter.pieceJson(
+                "qa/pillager_outpost/piece/minecraft/pillager_outpost/watchtower",
+                List.of(),
+                1155
+        );
+        VillageImporter.PoolMemberNormalization connectorScaffold = VillageImporter.normalizePoolMember(
+                "minecraft:pillager_outpost/features",
+                "qa/pillager_outpost/pool/minecraft/pillager_outpost/features",
+                false,
+                2,
+                "minecraft:empty",
+                "minecraft:pillager_outpost/feature_plate",
+                "qa/pillager_outpost/piece/minecraft/pillager_outpost/feature_plate",
+                1,
+                0,
+                List.of(Map.of("name", "minecraft:bottom")));
+
+        assertEquals(tower.getClass().getSimpleName(), resolution.physicalElement().typeName());
+        assertEquals("minecraft:pillager_outpost/watchtower", resolution.templateLocation());
+        assertEquals(1, resolution.omittedElements());
+        assertEquals("qa/pillager_outpost/piece/minecraft/pillager_outpost/watchtower", entry.get("piece"));
+        assertEquals(1, entry.get("weight"));
+        assertEquals(StructureCapability.LIST_ELEMENTS, loss.capability());
+        assertEquals("list_pool_overlays_not_imported", loss.code());
+        assertEquals(false, basePlatePiece.get("collidable"));
+        assertFalse(watchtowerPiece.containsKey("collidable"));
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, connectorScaffold.disposition());
+        assertTrue(connectorScaffold.losses().isEmpty());
+    }
+
+    @Test
+    public void actualWaystoneLikeAllAirMemberNormalizesToEmpty() throws Exception {
+        StructurePoolElement waystone = StructurePoolElement
+                .legacy("dungeons_and_taverns:waystones/waystone_scaffold")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution resolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(waystone));
+        VillageImporter.PoolMemberNormalization normalization = VillageImporter.normalizePoolMember(
+                "dungeons_and_taverns:waystones",
+                "qa/pool/dungeons_and_taverns/waystones",
+                false,
+                1,
+                "dungeons_and_taverns:waystones",
+                resolution.templateLocation(),
+                "qa/piece/dungeons_and_taverns/waystones/waystone_scaffold",
+                2,
+                0,
+                List.of());
+
+        assertEquals(waystone.getClass().getSimpleName(), resolution.physicalElement().typeName());
+        assertEquals("dungeons_and_taverns:waystones/waystone_scaffold", resolution.templateLocation());
+        assertEquals(VillageImporter.PoolMemberDisposition.EMPTY, normalization.disposition());
+        assertEquals(true, normalization.poolEntry().get("empty"));
+        assertEquals(2, normalization.poolEntry().get("weight"));
+        assertEquals("connectorless_all_air_member_normalized_empty",
+                normalization.losses().getFirst().code());
+    }
+
+    @Test
+    public void actualNonAirOrphanMemberIsOmitted() throws Exception {
+        StructurePoolElement orphan = StructurePoolElement
+                .legacy("test:orphan_house")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution resolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(orphan));
+        VillageImporter.PoolMemberNormalization normalization = VillageImporter.normalizePoolMember(
+                "test:orphan_pool",
+                "qa/pool/test/orphan_pool",
+                false,
+                1,
+                null,
+                resolution.templateLocation(),
+                "qa/piece/test/orphan_house",
+                4,
+                37,
+                List.of());
+
+        assertEquals(orphan.getClass().getSimpleName(), resolution.physicalElement().typeName());
+        assertEquals("test:orphan_house", resolution.templateLocation());
+        assertEquals(VillageImporter.PoolMemberDisposition.OMITTED, normalization.disposition());
+        assertTrue(normalization.poolEntry().isEmpty());
+        assertEquals("connectorless_non_air_member_omitted",
+                normalization.losses().getFirst().code());
+        assertTrue(normalization.losses().getFirst().detail().contains("37 non-air block(s)"));
+        assertTrue(normalization.losses().getFirst().detail().contains("no source fallback"));
+        assertTrue(normalization.losses().getFirst().detail().contains("selection weights"));
+        assertTrue(normalization.losses().getFirst().detail().contains("RNG consumption"));
+    }
+
+    @Test
+    public void actualConnectorlessStartMemberRemainsPhysical() throws Exception {
+        StructurePoolElement start = StructurePoolElement
+                .legacy("test:air_start")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution resolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(start));
+        VillageImporter.PoolMemberNormalization normalization = VillageImporter.normalizePoolMember(
+                "test:start",
+                "qa/pool/test/start",
+                true,
+                2,
+                "test:fallback",
+                resolution.templateLocation(),
+                "qa/piece/test/air_start",
+                6,
+                0,
+                List.of());
+
+        assertEquals(start.getClass().getSimpleName(), resolution.physicalElement().typeName());
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, normalization.disposition());
+        assertEquals("qa/piece/test/air_start", normalization.poolEntry().get("piece"));
+        assertTrue(normalization.losses().isEmpty());
+    }
+
+    @Test
+    public void actualMixedPoolAllAirMemberIsOmittedWithoutBecomingEmpty() throws Exception {
+        StructurePoolElement inert = StructurePoolElement
+                .legacy("test:mixed_air_inert")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution resolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(inert));
+        VillageImporter.PoolMemberNormalization normalization = VillageImporter.normalizePoolMember(
+                "test:mixed",
+                "qa/pool/test/mixed",
+                false,
+                4,
+                "test:mixed",
+                resolution.templateLocation(),
+                "qa/piece/test/mixed_air_inert",
+                9,
+                0,
+                List.of());
+
+        assertEquals(inert.getClass().getSimpleName(), resolution.physicalElement().typeName());
+        assertEquals(VillageImporter.PoolMemberDisposition.OMITTED, normalization.disposition());
+        assertTrue(normalization.poolEntry().isEmpty());
+        assertEquals("connectorless_all_air_mixed_member_omitted",
+                normalization.losses().getFirst().code());
+        assertTrue(normalization.losses().getFirst().detail().contains("selection weights"));
+        assertTrue(normalization.losses().getFirst().detail().contains("RNG consumption"));
+    }
+
+    @Test
+    public void actualMixedDistinctFallbackRetainsAllConnectorlessMembers() throws Exception {
+        StructurePoolElement allAirElement = StructurePoolElement
+                .legacy("test:mixed_all_air_primary")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        StructurePoolElement nonAirElement = StructurePoolElement
+                .legacy("test:mixed_non_air_primary")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution allAirResolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(allAirElement));
+        VillageImporter.PoolElementResolution nonAirResolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(nonAirElement));
+        VillageImporter.PoolMemberNormalization allAir = VillageImporter.normalizePoolMember(
+                "test:mixed",
+                "qa/pool/test/mixed",
+                false,
+                4,
+                "test:fallback",
+                allAirResolution.templateLocation(),
+                "qa/piece/test/mixed_all_air_primary",
+                9,
+                0,
+                List.of());
+        VillageImporter.PoolMemberNormalization nonAir = VillageImporter.normalizePoolMember(
+                "test:mixed",
+                "qa/pool/test/mixed",
+                false,
+                4,
+                "test:fallback",
+                nonAirResolution.templateLocation(),
+                "qa/piece/test/mixed_non_air_primary",
+                12,
+                41,
+                List.of());
+
+        assertEquals(allAirElement.getClass().getSimpleName(), allAirResolution.physicalElement().typeName());
+        assertEquals(nonAirElement.getClass().getSimpleName(), nonAirResolution.physicalElement().typeName());
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, allAir.disposition());
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, nonAir.disposition());
+        assertEquals("qa/piece/test/mixed_all_air_primary", allAir.poolEntry().get("piece"));
+        assertEquals("qa/piece/test/mixed_non_air_primary", nonAir.poolEntry().get("piece"));
+        assertTrue(allAir.losses().isEmpty());
+        assertTrue(nonAir.losses().isEmpty());
+    }
+
+    @Test
+    public void actualSingletonDistinctFallbackRetainsAllAirAndNonAirMembers() throws Exception {
+        StructurePoolElement allAirElement = StructurePoolElement
+                .legacy("test:all_air_primary")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        StructurePoolElement nonAirElement = StructurePoolElement
+                .legacy("test:non_air_primary")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        VillageImporter.PoolElementResolution allAirResolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(allAirElement));
+        VillageImporter.PoolElementResolution nonAirResolution = VillageImporter.resolvePoolElement(StructureReaderFixture.element(nonAirElement));
+        VillageImporter.PoolMemberNormalization allAir = VillageImporter.normalizePoolMember(
+                "test:primary",
+                "qa/pool/test/primary",
+                false,
+                1,
+                "test:fallback",
+                allAirResolution.templateLocation(),
+                "qa/piece/test/all_air_primary",
+                5,
+                0,
+                List.of());
+        VillageImporter.PoolMemberNormalization nonAir = VillageImporter.normalizePoolMember(
+                "test:primary",
+                "qa/pool/test/primary",
+                false,
+                1,
+                "test:fallback",
+                nonAirResolution.templateLocation(),
+                "qa/piece/test/non_air_primary",
+                7,
+                29,
+                List.of());
+
+        assertEquals(allAirElement.getClass().getSimpleName(), allAirResolution.physicalElement().typeName());
+        assertEquals(nonAirElement.getClass().getSimpleName(), nonAirResolution.physicalElement().typeName());
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, allAir.disposition());
+        assertEquals(VillageImporter.PoolMemberDisposition.PHYSICAL, nonAir.disposition());
+        assertEquals("qa/piece/test/all_air_primary", allAir.poolEntry().get("piece"));
+        assertEquals("qa/piece/test/non_air_primary", nonAir.poolEntry().get("piece"));
+        assertTrue(allAir.losses().isEmpty());
+        assertTrue(nonAir.losses().isEmpty());
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/iris/structure/nativegen/NativeStructureVolumeIndexTest.java

@@ -0,0 +1,604 @@
+package art.arcane.iris.structure.nativegen;
+
+import art.arcane.iris.structure.nativegen.IrisStructureVolumePolicy;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.terrain.NativeStructureVolumeSource;
+
+import art.arcane.iris.structure.nativegen.NativeStructureVolumeIndex;
+
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.volmlib.nativelib.terrain.structure.NativeStructureVolume;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Proxy;
+import java.lang.reflect.Field;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CopyOnWriteArraySet;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.ForkJoinPool;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.concurrent.locks.LockSupport;
+import java.util.function.IntConsumer;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class NativeStructureVolumeIndexTest {
+    private static final String STRUCTURE_KEY = "minecraft:swamp_hut";
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void assembledPiecesBecomeWorldSpacePieceVolumes() {
+        StructureStart start = swampHut(0, 0, 4, 6);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+
+        KList<NativeStructureVolume> volumes = NativeStructureVolumeSource.appendPieces(null, STRUCTURE_KEY, start);
+
+        assertEquals(1, volumes.size());
+        NativeStructureVolume volume = volumes.getFirst();
+        assertEquals(STRUCTURE_KEY, volume.structure());
+        assertEquals(bounds.minX(), volume.minX());
+        assertEquals(bounds.minY(), volume.minY());
+        assertEquals(bounds.minZ(), volume.minZ());
+        assertEquals(bounds.maxX(), volume.maxX());
+        assertEquals(bounds.maxY(), volume.maxY());
+        assertEquals(bounds.maxZ(), volume.maxZ());
+    }
+
+    @Test
+    public void invalidStartsContributeNoVolumes() {
+        assertNull(NativeStructureVolumeSource.appendPieces(null, STRUCTURE_KEY, StructureStart.INVALID_START));
+        assertNull(NativeStructureVolumeSource.appendPieces(null, STRUCTURE_KEY, null));
+    }
+
+    @Test
+    public void coldAndCachedQueriesResolveIdenticalVolumes() {
+        CountingResolver resolver = new CountingResolver(0, 0);
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+
+        KList<NativeStructureVolume> cold = index.resolve(null, 0, 0, 15, 15);
+        int coldResolutions = resolver.resolutions();
+        KList<NativeStructureVolume> cached = index.resolve(null, 0, 0, 15, 15);
+
+        assertTrue(coldResolutions > 0);
+        assertFalse(cold.isEmpty());
+        assertEquals(cold, cached);
+        assertEquals(coldResolutions, resolver.resolutions());
+    }
+
+    @Test
+    public void completedOriginsRemainBoundedAndPendingBuildsAreReleased() throws Exception {
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(
+                (engine, chunkX, chunkZ) -> NativeStructureVolume.NONE);
+        for (int chunkX = -8_192; chunkX <= 8_192; chunkX++) {
+            index.originVolumes(null, chunkX, -17);
+        }
+        assertEquals(16_384, cache(index, "originCache").size());
+        assertTrue(cache(index, "originBuilds").isEmpty());
+        index.resolve(null, -16, -16, -1, -1);
+        assertEquals(16_384, cache(index, "originCache").size());
+        assertTrue(cache(index, "originBuilds").isEmpty());
+        assertTrue(cache(index, "queryBuilds").isEmpty());
+    }
+
+    @Test
+    public void runtimeBucketsStayIsolatedAndRetirementEvictsOnlyTheirEntries() {
+        AtomicInteger runtimeId = new AtomicInteger(1);
+        Engine engine = runtimeEngine(runtimeId);
+        CountingResolver resolver = new CountingResolver(0, 0);
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+
+        index.resolve(engine, 0, 0, 15, 15);
+        assertEquals(289, resolver.resolutions());
+        index.resolve(engine, 0, 0, 15, 15);
+        assertEquals(289, resolver.resolutions());
+
+        runtimeId.set(2);
+        index.resolve(engine, 0, 0, 15, 15);
+        assertEquals(578, resolver.resolutions());
+        index.resolve(engine, 0, 0, 15, 15);
+        assertEquals(578, resolver.resolutions());
+
+        index.evictRuntime(1);
+        runtimeId.set(1);
+        index.resolve(engine, 0, 0, 15, 15);
+        assertEquals(867, resolver.resolutions());
+    }
+
+    @Test
+    public void pinnedRuntimeReusesCachedOriginsWithoutOpeningCoordinateScopes() throws Exception {
+        ScopedEngine scoped = scopedEngine(true, 1);
+        CountingResolver resolver = new CountingResolver(0, 0);
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+
+        KList<NativeStructureVolume> first = index.resolve(scoped.engine(), 0, 0, 15, 15);
+        assertEquals(289, scoped.scopes().get());
+        index.resolve(scoped.engine(), 16, 0, 31, 15);
+        assertEquals(306, resolver.resolutions());
+        assertEquals(306, scoped.scopes().get());
+        assertEquals(first, index.resolve(scoped.engine(), 0, 0, 15, 15));
+        assertEquals(306, scoped.scopes().get());
+    }
+
+    @Test
+    public void absentOrMismatchedRuntimeOwnershipKeepsCoordinateRouting() throws Exception {
+        ScopedEngine detached = scopedEngine(true, 1);
+        when(detached.engine().getGenerationHistoryRuntimeRouter()).thenReturn(Optional.empty());
+        for (ScopedEngine scoped : List.of(scopedEngine(false, 1), scopedEngine(true, 0),
+                scopedEngine(true, 2), detached)) {
+            NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(new CountingResolver(0, 0));
+            index.resolve(scoped.engine(), 0, 0, 15, 15);
+            index.resolve(scoped.engine(), 16, 0, 31, 15);
+            assertEquals(578, scoped.scopes().get());
+        }
+    }
+
+    @Test
+    public void retiredPinnedOriginsRebuildThroughCoordinateScopes() throws Exception {
+        ScopedEngine scoped = scopedEngine(true, 1);
+        CountingResolver resolver = new CountingResolver(0, 0);
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+
+        KList<NativeStructureVolume> first = index.resolve(scoped.engine(), 0, 0, 15, 15);
+        index.evictRuntime(1);
+        assertEquals(first, index.resolve(scoped.engine(), 0, 0, 15, 15));
+        assertEquals(578, resolver.resolutions());
+        assertEquals(578, scoped.scopes().get());
+    }
+
+    @Test
+    public void invalidatedIndexReceivesRuntimeRetirementAndDetachesOnUninstall() throws Exception {
+        IrisEngine engine = mock(IrisEngine.class);
+        Set<IntConsumer> listeners = new CopyOnWriteArraySet<>();
+        doAnswer(invocation -> {
+            listeners.add(invocation.getArgument(0));
+            return null;
+        }).when(engine).addGenerationRuntimeRetirementListener(any());
+        doAnswer(invocation -> {
+            listeners.remove(invocation.getArgument(0));
+            return null;
+        }).when(engine).removeGenerationRuntimeRetirementListener(any());
+        NativeStructureVolumeSource.Context context = new NativeStructureVolumeSource.Context(
+                null, null, null, null, () -> null, () -> null, () -> null);
+        NativeStructureVolumeIndex.install(engine,
+                new NativeStructureVolumeSource<>(context, IrisStructureVolumePolicy.INSTANCE)::volumesAt);
+        try {
+            assertEquals(1, listeners.size());
+            IntConsumer original = listeners.iterator().next();
+            NativeStructureVolumeIndex.invalidate(engine);
+            assertEquals(1, listeners.size());
+            assertFalse(listeners.contains(original));
+
+            NativeStructureVolumeIndex.volumes(engine, 0, 0, 15, 15);
+            NativeStructureVolumeIndex current = installedIndexes().get(engine);
+            assertEquals(289, cache(current, "originCache").size());
+            assertEquals(1, cache(current, "queryCache").size());
+            for (IntConsumer listener : listeners) {
+                listener.accept(0);
+            }
+            assertTrue(cache(current, "originCache").isEmpty());
+            assertTrue(cache(current, "queryCache").isEmpty());
+        } finally {
+            NativeStructureVolumeIndex.uninstall(engine);
+        }
+        assertTrue(listeners.isEmpty());
+    }
+
+    @Test
+    public void retiringOriginBuildCannotRepublishWhileQueryEvictionWaits() throws Exception {
+        BlockingResolver resolver = new BlockingResolver();
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        Map<?, ?> origins = cache(index, "originCache");
+        Map<?, ?> queries = cache(index, "queryCache");
+        try {
+            Future<KList<NativeStructureVolume>> builder = executor.submit(() -> index.originVolumes(null, 0, 0));
+            assertTrue(resolver.awaitFirstEntry());
+            index.originVolumes(null, 1, 0);
+            assertEquals(1, origins.size());
+            Future<?> retirement;
+            synchronized (queries) {
+                retirement = executor.submit(() -> index.evictRuntime(0));
+                long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5);
+                boolean cleared = false;
+                while (System.nanoTime() < deadline) {
+                    synchronized (origins) {
+                        cleared = origins.isEmpty();
+                    }
+                    if (cleared) {
+                        break;
+                    }
+                    LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(10L));
+                }
+                assertTrue("Origin eviction did not complete before the query cache lock", cleared);
+                resolver.release();
+                assertTrue(builder.get(5, TimeUnit.SECONDS).isEmpty());
+                synchronized (origins) {
+                    assertTrue("The retired in-flight origin was cached again", origins.isEmpty());
+                }
+            }
+            retirement.get(5, TimeUnit.SECONDS);
+            index.originVolumes(null, 0, 0);
+            assertEquals(3, resolver.resolutions());
+        } finally {
+            resolver.release();
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void independentIndexesResolveIdenticalVolumesFromTheSameSeed() {
+        NativeStructureVolumeIndex first = NativeStructureVolumeIndex.forTesting(new CountingResolver(0, 0));
+        NativeStructureVolumeIndex second = NativeStructureVolumeIndex.forTesting(new CountingResolver(0, 0));
+
+        assertEquals(first.resolve(null, 0, 0, 15, 15), second.resolve(null, 0, 0, 15, 15));
+        assertEquals(first.resolve(null, -32, -32, 47, 47), second.resolve(null, -32, -32, 47, 47));
+    }
+
+    @Test
+    public void volumesOutsideTheQueryRectAreExcluded() {
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(new CountingResolver(0, 0));
+        BoundingBox bounds = swampHut(0, 0, 4, 6).getPieces().getFirst().getBoundingBox();
+
+        KList<NativeStructureVolume> hit = index.resolve(null, bounds.minX(), bounds.minZ(), bounds.maxX(), bounds.maxZ());
+        KList<NativeStructureVolume> miss = index.resolve(null,
+                bounds.maxX() + 1, bounds.minZ(), bounds.maxX() + 8, bounds.maxZ());
+
+        assertEquals(1, hit.size());
+        assertTrue(miss.isEmpty());
+    }
+
+    @Test
+    public void startsWithinTheOriginReachContributeAndBeyondItDoNot() {
+        int reach = NativeStructureVolumeIndex.originReachChunks();
+        NativeStructureVolumeIndex reachable = NativeStructureVolumeIndex.forTesting(new CountingResolver(reach, 0));
+        NativeStructureVolumeIndex unreachable = NativeStructureVolumeIndex.forTesting(new CountingResolver(reach + 1, 0));
+
+        assertFalse(reachable.resolve(null, 0, 0, 15, 15).isEmpty());
+        assertTrue(unreachable.resolve(null, 0, 0, 15, 15).isEmpty());
+    }
+
+    @Test
+    public void overlappingColdQueriesResolveIndependentOriginsConcurrently() throws Exception {
+        BlockingResolver resolver = new BlockingResolver();
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<KList<NativeStructureVolume>> first = executor.submit(() -> index.resolve(null, 0, 0, 15, 15));
+            assertTrue(resolver.awaitFirstEntry());
+            Future<KList<NativeStructureVolume>> adjacent = executor.submit(() -> index.resolve(null, 16, 0, 31, 15));
+
+            assertTrue(resolver.awaitSecondEntry(5_000));
+            assertTrue(adjacent.get(5, TimeUnit.SECONDS).isEmpty());
+            resolver.release();
+            assertTrue(first.get(5, TimeUnit.SECONDS).isEmpty());
+            assertTrue(adjacent.get(5, TimeUnit.SECONDS).isEmpty());
+            assertEquals(306, resolver.resolutions());
+        } finally {
+            resolver.release();
+            executor.shutdownNow();
+        }
+    }
+
+    @Test
+    public void overlappingNegativeQueriesPreserveEveryVolumeAndOriginOrder() throws Exception {
+        BlockingResolver coordination = new BlockingResolver();
+        NativeStructureVolumeIndex.OriginResolver volumes = (engine, chunkX, chunkZ) ->
+                new KList<>(new NativeStructureVolume(chunkX + ":" + chunkZ,
+                        -256, 0, -256, 256, 255, 256));
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting((engine, chunkX, chunkZ) -> {
+            coordination.volumesAt(engine, chunkX, chunkZ);
+            return volumes.volumesAt(engine, chunkX, chunkZ);
+        });
+        NativeStructureVolumeIndex sequential = NativeStructureVolumeIndex.forTesting(volumes);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<KList<NativeStructureVolume>> negative = executor.submit(
+                    () -> index.resolve(null, -16, 0, -1, 15));
+            assertTrue(coordination.awaitFirstEntry());
+            Future<KList<NativeStructureVolume>> positive = executor.submit(
+                    () -> index.resolve(null, 0, 0, 15, 15));
+            assertTrue(coordination.awaitSecondEntry(5_000));
+            assertEquals(sequential.resolve(null, 0, 0, 15, 15), positive.get(5, TimeUnit.SECONDS));
+            coordination.release();
+            assertEquals(sequential.resolve(null, -16, 0, -1, 15), negative.get(5, TimeUnit.SECONDS));
+            assertEquals(306, coordination.resolutions());
+        } finally {
+            coordination.release();
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void sharedOriginWaitAllowsQueuedTerrainWorkToRun() throws Exception {
+        assertQueuedTerrainCanComplete(false);
+    }
+
+    @Test
+    public void interruptedOriginWaitPreservesInterruptAndResult() throws Exception {
+        assertQueuedTerrainCanComplete(true);
+    }
+
+    private static void assertQueuedTerrainCanComplete(boolean interruptWaiter) throws Exception {
+        CountDownLatch ownerEntered = new CountDownLatch(1);
+        CompletableFuture<Void> terrain = new CompletableFuture<>();
+        AtomicBoolean firstOrigin = new AtomicBoolean(true);
+        AtomicBoolean interruptedAfterQuery = new AtomicBoolean();
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting((engine, chunkX, chunkZ) -> {
+            if (firstOrigin.compareAndSet(true, false)) {
+                ownerEntered.countDown();
+                terrain.join();
+            }
+            return new KList<>(new NativeStructureVolume(chunkX + ":" + chunkZ,
+                    -256, 0, -256, 256, 100, 256));
+        });
+        ExecutorService owner = Executors.newSingleThreadExecutor();
+        ForkJoinPool workers = new ForkJoinPool(2);
+        AtomicReference<Thread> firstWaiter = new AtomicReference<>();
+        AtomicReference<Thread> secondWaiter = new AtomicReference<>();
+        try {
+            Future<KList<NativeStructureVolume>> original = owner.submit(
+                    () -> index.originVolumes(null, -6, -8));
+            assertTrue(ownerEntered.await(5, TimeUnit.SECONDS));
+            Future<KList<NativeStructureVolume>> adjacent = workers.submit(() -> {
+                firstWaiter.set(Thread.currentThread());
+                KList<NativeStructureVolume> result = index.resolve(null, 16, 0, 31, 15);
+                interruptedAfterQuery.set(Thread.currentThread().isInterrupted());
+                return result;
+            });
+            Future<KList<NativeStructureVolume>> next = workers.submit(() -> {
+                secondWaiter.set(Thread.currentThread());
+                return index.resolve(null, 32, 0, 47, 15);
+            });
+            awaitOriginWaiter(firstWaiter);
+            awaitOriginWaiter(secondWaiter);
+            if (interruptWaiter) {
+                firstWaiter.get().interrupt();
+            }
+
+            Future<?> terrainTask = workers.submit(() -> terrain.complete(null));
+            terrainTask.get(3, TimeUnit.SECONDS);
+            assertEquals(1, original.get(3, TimeUnit.SECONDS).size());
+            KList<NativeStructureVolume> adjacentVolumes = adjacent.get(3, TimeUnit.SECONDS);
+            assertEquals(289, adjacentVolumes.size());
+            assertEquals(adjacentVolumes, index.resolve(null, 16, 0, 31, 15));
+            assertEquals(289, next.get(3, TimeUnit.SECONDS).size());
+            assertEquals(interruptWaiter, interruptedAfterQuery.get());
+        } finally {
+            terrain.complete(null);
+            owner.shutdownNow();
+            workers.shutdownNow();
+            assertTrue(owner.awaitTermination(5, TimeUnit.SECONDS));
+            assertTrue(workers.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    private static void awaitOriginWaiter(AtomicReference<Thread> reference) {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(5);
+        while (System.nanoTime() < deadline) {
+            Thread thread = reference.get();
+            if (thread != null && thread.getState() == Thread.State.WAITING) {
+                for (StackTraceElement frame : thread.getStackTrace()) {
+                    if (frame.getClassName().equals("art.arcane.volmlib.nativelib.terrain.NativeBuildFutures")
+                            && frame.getMethodName().equals("awaitBuild")) {
+                        return;
+                    }
+                }
+            }
+            LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(1));
+        }
+        throw new AssertionError("Native query did not wait for the shared origin");
+    }
+
+    @Test
+    public void distantColdQueriesCanResolveOriginsConcurrently() throws Exception {
+        BlockingResolver resolver = new BlockingResolver();
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(resolver);
+        int distantChunkX = 64;
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<KList<NativeStructureVolume>> first = executor.submit(() -> index.resolve(null, 0, 0, 15, 15));
+            assertTrue(resolver.awaitFirstEntry());
+            Future<KList<NativeStructureVolume>> distant = executor.submit(
+                    () -> index.resolve(null, distantChunkX << 4, 0, (distantChunkX << 4) + 15, 15));
+
+            assertTrue(resolver.awaitSecondEntry(5_000));
+            resolver.release();
+            assertTrue(first.get(5, TimeUnit.SECONDS).isEmpty());
+            assertTrue(distant.get(5, TimeUnit.SECONDS).isEmpty());
+        } finally {
+            resolver.release();
+            executor.shutdownNow();
+        }
+    }
+
+    @Test
+    public void coordinatedResolutionPreservesCanonicalOriginOrder() {
+        NativeStructureVolumeIndex index = NativeStructureVolumeIndex.forTesting(new OrderedResolver());
+
+        KList<NativeStructureVolume> volumes = index.resolve(null, 0, 0, 15, 15);
+
+        assertEquals(289, volumes.size());
+        assertEquals("-8:-8", volumes.getFirst().structure());
+        assertEquals("0:0", volumes.get(144).structure());
+        assertEquals("8:8", volumes.getLast().structure());
+    }
+
+    private static ScopedEngine scopedEngine(boolean scoped, int ownerRuntimeId) throws Exception {
+        IrisEngine engine = mock(IrisEngine.class);
+        GenerationHistoryRuntimeRouter router = mock(GenerationHistoryRuntimeRouter.class);
+        when(engine.hasGenerationRuntimeScope()).thenReturn(scoped);
+        when(engine.getGenerationHistoryRuntimeRouter()).thenReturn(Optional.of(router));
+        when(engine.getCacheID()).thenReturn(1);
+        if (ownerRuntimeId != 0) {
+            IrisEngine.GenerationRuntimeBinding binding = mock(IrisEngine.GenerationRuntimeBinding.class);
+            when(binding.runtimeId()).thenReturn(ownerRuntimeId);
+            when(router.currentRuntimeOwnership()).thenReturn(Optional.of(
+                    new GenerationHistoryRuntimeRouter.RuntimeOwnership(1L, binding)));
+        }
+        AtomicInteger scopes = new AtomicInteger();
+        when(engine.openGenerationHistoryCoordinateScope(anyInt(), anyInt())).thenAnswer(invocation -> {
+            scopes.incrementAndGet();
+            return null;
+        });
+        return new ScopedEngine(engine, scopes);
+    }
+
+    @SuppressWarnings("unchecked")
+    private static Map<Engine, NativeStructureVolumeIndex> installedIndexes() throws Exception {
+        Field indexes = NativeStructureVolumeIndex.class.getDeclaredField("INDEXES");
+        indexes.setAccessible(true);
+        return (Map<Engine, NativeStructureVolumeIndex>) indexes.get(null);
+    }
+
+    private static Map<?, ?> cache(NativeStructureVolumeIndex index, String name) throws Exception {
+        Field field = NativeStructureVolumeIndex.class.getDeclaredField(name);
+        field.setAccessible(true);
+        return (Map<?, ?>) field.get(index);
+    }
+
+    private static StructureStart swampHut(int chunkX, int chunkZ, int x, int z) {
+        Structure source = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece piece = new SwampHutPiece(RandomSource.create(17L), x, z);
+        return new StructureStart(source, new ChunkPos(chunkX, chunkZ), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static Engine runtimeEngine(AtomicInteger runtimeId) {
+        return (Engine) Proxy.newProxyInstance(
+                Engine.class.getClassLoader(),
+                new Class<?>[]{Engine.class},
+                (proxy, method, arguments) -> {
+                    if (method.getName().equals("getCacheID")) {
+                        return runtimeId.get();
+                    }
+                    if (method.getName().equals("hashCode")) {
+                        return System.identityHashCode(proxy);
+                    }
+                    if (method.getName().equals("equals")) {
+                        return proxy == arguments[0];
+                    }
+                    if (method.getName().equals("toString")) {
+                        return "runtime-engine-" + runtimeId.get();
+                    }
+                    throw new UnsupportedOperationException(method.getName());
+                }
+        );
+    }
+
+    private static final class CountingResolver implements NativeStructureVolumeIndex.OriginResolver {
+        private final AtomicInteger resolutions = new AtomicInteger();
+        private final int originChunkX;
+        private final int originChunkZ;
+
+        private CountingResolver(int originChunkX, int originChunkZ) {
+            this.originChunkX = originChunkX;
+            this.originChunkZ = originChunkZ;
+        }
+
+        private int resolutions() {
+            return resolutions.get();
+        }
+
+        @Override
+        public KList<NativeStructureVolume> volumesAt(Engine engine, int chunkX, int chunkZ) {
+            resolutions.incrementAndGet();
+            if (chunkX != originChunkX || chunkZ != originChunkZ) {
+                return NativeStructureVolume.NONE;
+            }
+            return NativeStructureVolumeSource.appendPieces(null, STRUCTURE_KEY, swampHut(chunkX, chunkZ, 4, 6));
+        }
+    }
+
+    private static final class BlockingResolver implements NativeStructureVolumeIndex.OriginResolver {
+        private final AtomicInteger resolutions = new AtomicInteger();
+        private final CountDownLatch firstEntry = new CountDownLatch(1);
+        private final CountDownLatch secondEntry = new CountDownLatch(1);
+        private final CountDownLatch release = new CountDownLatch(1);
+
+        private int resolutions() {
+            return resolutions.get();
+        }
+
+        private boolean awaitFirstEntry() throws InterruptedException {
+            return firstEntry.await(5, TimeUnit.SECONDS);
+        }
+
+        private boolean awaitSecondEntry(long timeoutMillis) throws InterruptedException {
+            return secondEntry.await(timeoutMillis, TimeUnit.MILLISECONDS);
+        }
+
+        private void release() {
+            release.countDown();
+        }
+
+        @Override
+        public KList<NativeStructureVolume> volumesAt(Engine engine, int chunkX, int chunkZ) {
+            int resolution = resolutions.incrementAndGet();
+            if (resolution == 1) {
+                firstEntry.countDown();
+                try {
+                    if (!release.await(5, TimeUnit.SECONDS)) {
+                        throw new IllegalStateException("Timed out waiting to release native structure resolution");
+                    }
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException("Interrupted while coordinating native structure resolution", e);
+                }
+            } else if (resolution == 2) {
+                secondEntry.countDown();
+            }
+            return NativeStructureVolume.NONE;
+        }
+    }
+
+    private static final class OrderedResolver implements NativeStructureVolumeIndex.OriginResolver {
+        @Override
+        public KList<NativeStructureVolume> volumesAt(Engine engine, int chunkX, int chunkZ) {
+            return new KList<>(new NativeStructureVolume(
+                    chunkX + ":" + chunkZ,
+                    0, 0, 0,
+                    15, 255, 15));
+        }
+    }
+    private record ScopedEngine(IrisEngine engine, AtomicInteger scopes) {
+    }
+}

adapters/bukkit/nms/v26_2_R1/src/test/java/art/arcane/volmlib/nativelib/common/structure/StructureReaderFixture.java

@@ -0,0 +1,12 @@
+package art.arcane.volmlib.nativelib.common.structure;
+
+import art.arcane.volmlib.nativelib.terrain.NativeStructureReader;
+
+public final class StructureReaderFixture {
+    private StructureReaderFixture() {
+    }
+
+    public static NativeStructureReader.Element element(Object handle) {
+        return new ReflectiveStructureReader.ElementView(handle, null, ReflectiveStructureReader::readDefaultConnectors);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessChunkGenerator.java

@@ -0,0 +1,111 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.platform.bukkit.nms.BukkitBiomePolicy;
+import art.arcane.iris.platform.bukkit.nms.BukkitTerrainColumnPolicy;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeBiomeRegistryImpl;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeBiomeSourceImpl;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainColumns;
+import com.mojang.serialization.MapCodec;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.blending.Blender;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+
+final class HeadlessChunkGenerator extends ChunkGenerator {
+    private final NativeTerrainColumns columns;
+    private final int minimumY;
+    private final int height;
+    private final int seaLevel;
+
+    HeadlessChunkGenerator(Options options) {
+        super(biomes(options));
+        Engine engine = options.engine();
+        columns = new NativeTerrainColumns(new BukkitTerrainColumnPolicy(engine, null));
+        minimumY = engine.getMinHeight();
+        height = engine.getHeight();
+        seaLevel = minimumY + engine.getDimension().getFluidHeight();
+        if (engine instanceof IrisEngine irisEngine) {
+            irisEngine.addGenerationRuntimeRetirementListener(columns::evictRuntime);
+        }
+    }
+
+    @Override
+    protected MapCodec<? extends ChunkGenerator> codec() {
+        return MapCodec.unit(this);
+    }
+
+    @Override
+    public int getGenDepth() {
+        return height;
+    }
+
+    @Override
+    public int getSeaLevel() {
+        return seaLevel;
+    }
+
+    @Override
+    public int getMinY() {
+        return minimumY;
+    }
+
+    @Override
+    public int getBaseHeight(int x, int z, Heightmap.Types type, LevelHeightAccessor accessor, RandomState random) {
+        return columns.baseHeight(x, z, type, accessor);
+    }
+
+    @Override
+    public NoiseColumn getBaseColumn(int x, int z, LevelHeightAccessor accessor, RandomState random) {
+        return columns.baseColumn(x, z, accessor);
+    }
+
+    @Override
+    public CompletableFuture<ChunkAccess> buildTerrain(ChunkAccess chunk, Blender blender, RandomState random,
+            StructureManager structures, BiomeManager biomes, WorldGenRegion region, Set<Holder<Biome>> possibleBiomes) {
+        throw new UnsupportedOperationException("Headless terrain must be generated through the Iris region pipeline");
+    }
+
+    @Override
+    public void spawnOriginalMobs(WorldGenRegion region) {
+        throw new UnsupportedOperationException("Headless native population is not installed");
+    }
+
+    @Override
+    public void addDebugScreenInfo(List<String> result, RandomState random, BlockPos position, SamplerContext context) {
+        result.add("Iris native structure terrain");
+    }
+
+    private static NativeBiomeSourceImpl biomes(Options options) {
+        NativeBiomeRegistryImpl registry = new NativeBiomeRegistryImpl(options.registries().lookupOrThrow(Registries.BIOME));
+        BukkitBiomePolicy<Holder<Biome>, Biome> policy = new BukkitBiomePolicy<>(
+                new BukkitBiomePolicy.RuntimeOptions<>(options.engine().getSeedManager().getSeed(), options.engine(),
+                        null, () -> registry), registry);
+        return new NativeBiomeSourceImpl(policy);
+    }
+
+    record Options(Engine engine, RegistryAccess registries) {
+        Options {
+            Objects.requireNonNull(engine, "engine");
+            Objects.requireNonNull(registries, "registries");
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessChunkLighting.java

@@ -0,0 +1,259 @@
+package art.arcane.iris.probe;
+
+import ca.spottedleaf.moonrise.patches.starlight.chunk.StarlightChunk;
+import ca.spottedleaf.moonrise.patches.starlight.light.SWMRNibbleArray;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.SectionPos;
+import net.minecraft.world.level.BlockGetter;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.DataLayer;
+import net.minecraft.world.level.chunk.LightChunk;
+import net.minecraft.world.level.chunk.LightChunkGetter;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.lighting.BlockLightEngine;
+import net.minecraft.world.level.lighting.ChunkSkyLightSources;
+import net.minecraft.world.level.lighting.LayerLightEventListener;
+import net.minecraft.world.level.lighting.SkyLightEngine;
+import net.minecraft.world.level.material.FluidState;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+import java.util.function.BiConsumer;
+
+final class HeadlessChunkLighting {
+    private static final int MAXIMUM_WINDOW_CHUNKS = 256;
+    private static final int HALO = 2;
+
+    private HeadlessChunkLighting() {
+    }
+
+    static void light(Request request) {
+        if (Thread.currentThread().isInterrupted()) {
+            throw new IllegalStateException("Offline lighting interrupted before initialization");
+        }
+        Window window = new Window(request);
+        BlockLightEngine block = new BlockLightEngine(window);
+        SkyLightEngine sky = request.skyLight() ? new SkyLightEngine(window) : null;
+        for (LightingChunk chunk : window.chunks.values()) {
+            ProtoChunk source = chunk.source;
+            for (int section = source.getMinSectionY(); section <= source.getMaxSectionY(); section++) {
+                SectionPos position = SectionPos.of(source.getPos(), section);
+                boolean empty = source.getSection(source.getSectionIndexFromSectionY(section)).hasOnlyAir();
+                block.updateSectionStatus(position, empty);
+                if (sky != null) {
+                    sky.updateSectionStatus(position, empty);
+                }
+            }
+        }
+        for (LightingChunk chunk : window.chunks.values()) {
+            block.propagateLightSources(chunk.source.getPos());
+            if (sky != null) {
+                sky.propagateLightSources(chunk.source.getPos());
+            }
+        }
+        drain(block);
+        if (sky != null) {
+            drain(sky);
+        }
+        for (ChunkPos position : request.targets()) {
+            ProtoChunk chunk = window.chunks.get(position.pack()).source;
+            StarlightChunk destination = (StarlightChunk) chunk;
+            destination.starlight$setBlockNibbles(copyLight(block, chunk));
+            destination.starlight$setSkyNibbles(copyLight(sky, chunk));
+            boolean[] emptySections = new boolean[chunk.getSectionsCount()];
+            for (int index = 0; index < emptySections.length; index++) {
+                emptySections[index] = chunk.getSection(index).hasOnlyAir();
+            }
+            destination.starlight$setBlockEmptinessMap(emptySections.clone());
+            destination.starlight$setSkyEmptinessMap(emptySections);
+            chunk.setPersistedStatus(ChunkStatus.LIGHT);
+            chunk.setLightCorrect(true);
+        }
+    }
+
+    private static void drain(LayerLightEventListener engine) {
+        while (engine.hasLightWork()) {
+            if (Thread.currentThread().isInterrupted()) {
+                throw new IllegalStateException("Offline lighting interrupted before completion");
+            }
+            engine.runLightUpdates();
+        }
+    }
+
+    private static SWMRNibbleArray[] copyLight(LayerLightEventListener engine, ProtoChunk chunk) {
+        SWMRNibbleArray[] result = new SWMRNibbleArray[chunk.getSectionsCount() + 2];
+        BlockPos.MutableBlockPos position = new BlockPos.MutableBlockPos();
+        for (int index = 0; index < result.length; index++) {
+            int sectionY = chunk.getMinSectionY() + index - 1;
+            DataLayer layer = engine == null ? new DataLayer() : engine.getDataLayerData(SectionPos.of(chunk.getPos(), sectionY));
+            if (layer == null) {
+                layer = new DataLayer();
+                for (int y = 0; y < 16; y++) {
+                    for (int z = 0; z < 16; z++) {
+                        for (int x = 0; x < 16; x++) {
+                            position.set(chunk.getPos().getMinBlockX() + x, (sectionY << 4) + y,
+                                    chunk.getPos().getMinBlockZ() + z);
+                            layer.set(x, y, z, engine.getLightValue(position));
+                        }
+                    }
+                }
+            }
+            result[index] = SWMRNibbleArray.fromVanilla(layer);
+        }
+        return result;
+    }
+
+    record Request(List<ProtoChunk> chunks, Set<ChunkPos> targets, boolean skyLight) {
+        Request {
+            chunks = List.copyOf(chunks);
+            targets = Set.copyOf(targets);
+            if (chunks.isEmpty() || chunks.size() > MAXIMUM_WINDOW_CHUNKS || targets.isEmpty()) {
+                throw new IllegalArgumentException("Offline lighting requires targets inside a bounded chunk window");
+            }
+        }
+    }
+
+    private static final class Window implements LightChunkGetter, BlockGetter {
+        private final Map<Long, LightingChunk> chunks;
+        private final int minimumY;
+        private final int height;
+
+        private Window(Request request) {
+            minimumY = request.chunks().getFirst().getMinY();
+            height = request.chunks().getFirst().getHeight();
+            chunks = new HashMap<>(request.chunks().size());
+            for (ProtoChunk chunk : request.chunks()) {
+                if (chunk.getMinY() != minimumY || chunk.getHeight() != height
+                        || chunk.getPersistedStatus() != ChunkStatus.FEATURES) {
+                    throw new IllegalArgumentException("Offline lighting requires matching heights and completed FEATURES chunks");
+                }
+                if (chunks.putIfAbsent(chunk.getPos().pack(), new LightingChunk(chunk)) != null) {
+                    throw new IllegalArgumentException("Duplicate lighting chunk: " + chunk.getPos());
+                }
+            }
+            for (ChunkPos target : request.targets()) {
+                for (int dz = -HALO; dz <= HALO; dz++) {
+                    for (int dx = -HALO; dx <= HALO; dx++) {
+                        if (!chunks.containsKey(ChunkPos.pack(Math.addExact(target.x(), dx), Math.addExact(target.z(), dz)))) {
+                            throw new IllegalArgumentException("Offline lighting target lacks its completed neighbor halo: " + target);
+                        }
+                    }
+                }
+            }
+        }
+
+        @Override
+        public LightChunk getChunkForLighting(int x, int z) {
+            return chunks.get(ChunkPos.pack(x, z));
+        }
+
+        @Override
+        public BlockGetter getLevel() {
+            return this;
+        }
+
+        @Override
+        public int getMinY() {
+            return minimumY;
+        }
+
+        @Override
+        public int getHeight() {
+            return height;
+        }
+
+        @Override
+        public BlockEntity getBlockEntity(BlockPos position) {
+            return requireChunk(position).getBlockEntity(position);
+        }
+
+        @Override
+        public BlockState getBlockState(BlockPos position) {
+            return requireChunk(position).getBlockState(position);
+        }
+
+        @Override
+        public BlockState getBlockStateIfLoaded(BlockPos position) {
+            LightingChunk chunk = chunks.get(ChunkPos.pack(position.getX() >> 4, position.getZ() >> 4));
+            return chunk == null ? null : chunk.getBlockState(position);
+        }
+
+        @Override
+        public FluidState getFluidState(BlockPos position) {
+            return getBlockState(position).getFluidState();
+        }
+
+        @Override
+        public FluidState getFluidIfLoaded(BlockPos position) {
+            BlockState state = getBlockStateIfLoaded(position);
+            return state == null ? null : state.getFluidState();
+        }
+
+        private LightingChunk requireChunk(BlockPos position) {
+            return Objects.requireNonNull(chunks.get(ChunkPos.pack(position.getX() >> 4, position.getZ() >> 4)),
+                    "Lighting query outside the supplied chunk window");
+        }
+    }
+
+    private static final class LightingChunk implements LightChunk {
+        private final ProtoChunk source;
+        private final ChunkSkyLightSources skySources;
+
+        private LightingChunk(ProtoChunk source) {
+            this.source = source;
+            skySources = new ChunkSkyLightSources(source);
+            skySources.fillFrom(source);
+        }
+
+        @Override
+        public void findBlockLightSources(BiConsumer<BlockPos, BlockState> consumer) {
+            source.findBlockLightSources(consumer);
+        }
+
+        @Override
+        public ChunkSkyLightSources getSkyLightSources() {
+            return skySources;
+        }
+
+        @Override
+        public BlockEntity getBlockEntity(BlockPos position) {
+            return source.getBlockEntity(position);
+        }
+
+        @Override
+        public BlockState getBlockState(BlockPos position) {
+            return source.getBlockState(position);
+        }
+
+        @Override
+        public BlockState getBlockStateIfLoaded(BlockPos position) {
+            return source.getBlockStateIfLoaded(position);
+        }
+
+        @Override
+        public FluidState getFluidState(BlockPos position) {
+            return source.getFluidState(position);
+        }
+
+        @Override
+        public FluidState getFluidIfLoaded(BlockPos position) {
+            return source.getFluidIfLoaded(position);
+        }
+
+        @Override
+        public int getMinY() {
+            return source.getMinY();
+        }
+
+        @Override
+        public int getHeight() {
+            return source.getHeight();
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessChunkSerialization.java

@@ -0,0 +1,126 @@
+package art.arcane.iris.probe;
+
+import ca.spottedleaf.moonrise.patches.starlight.chunk.StarlightChunk;
+import ca.spottedleaf.moonrise.patches.starlight.light.SWMRNibbleArray;
+import ca.spottedleaf.moonrise.patches.starlight.storage.StarlightSectionData;
+import it.unimi.dsi.fastutil.longs.LongSet;
+import it.unimi.dsi.fastutil.shorts.ShortArrayList;
+import it.unimi.dsi.fastutil.shorts.ShortList;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Registry;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.level.chunk.DataLayer;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkType;
+import net.minecraft.world.level.chunk.storage.SerializableChunkData;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.StructurePieceSerializationContext;
+
+import java.util.ArrayList;
+import java.util.EnumMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+final class HeadlessChunkSerialization {
+    private HeadlessChunkSerialization() {
+    }
+
+    static SerializableChunkData copyOf(ProtoChunk chunk, Context context) {
+        if (!chunk.canBeSerialized() || chunk.getPersistedStatus().getChunkType() != ChunkType.PROTOCHUNK) {
+            throw new IllegalArgumentException("Headless serialization requires a serializable proto chunk");
+        }
+        List<CompoundTag> blockEntities = new ArrayList<>(chunk.getBlockEntitiesPos().size());
+        for (BlockPos position : chunk.getBlockEntitiesPos()) {
+            CompoundTag tag = chunk.getBlockEntityNbtForSaving(position, context.structures().registryAccess());
+            if (tag != null) {
+                blockEntities.add(tag.copy());
+            }
+        }
+        List<CompoundTag> entities = new ArrayList<>(chunk.getEntities().size());
+        for (CompoundTag entity : chunk.getEntities()) {
+            entities.add(entity.copy());
+        }
+        Map<Heightmap.Types, long[]> heightmaps = new EnumMap<>(Heightmap.Types.class);
+        for (Map.Entry<Heightmap.Types, Heightmap> entry : chunk.getHeightmaps()) {
+            heightmaps.put(entry.getKey(), entry.getValue().getRawData().clone());
+        }
+        ShortList[] postProcessing = new ShortList[chunk.getPostProcessing().length];
+        for (int i = 0; i < postProcessing.length; i++) {
+            ShortList source = chunk.getPostProcessing()[i];
+            if (source != null && !source.isEmpty()) {
+                postProcessing[i] = new ShortArrayList(source);
+            }
+        }
+        CompoundTag persistent = chunk.persistentDataContainer.isEmpty()
+                ? null : chunk.persistentDataContainer.toTagCompound().copy();
+        return new SerializableChunkData(context.containers(), chunk.getPos(), chunk.getMinSectionY(),
+                context.gameTime(), chunk.getInhabitedTime(), chunk.getPersistedStatus(),
+                chunk.getBlendingData() == null ? null : chunk.getBlendingData().pack(),
+                chunk.getBelowZeroRetrogen(), chunk.getUpgradeData().copy(), heightmaps,
+                chunk.getTicksForSerialization(context.gameTime()), postProcessing, chunk.isLightCorrect(),
+                sections(chunk), entities, blockEntities, structures(chunk, context.structures()), persistent);
+    }
+
+    private static List<SerializableChunkData.SectionData> sections(ProtoChunk chunk) {
+        LevelChunkSection[] blocks = chunk.getSections();
+        StarlightChunk light = (StarlightChunk) chunk;
+        SWMRNibbleArray[] blockLight = light.starlight$getBlockNibbles();
+        SWMRNibbleArray[] skyLight = light.starlight$getSkyNibbles();
+        List<SerializableChunkData.SectionData> sections = new ArrayList<>(blocks.length + 2);
+        for (int i = 0; i < blocks.length + 2; i++) {
+            LevelChunkSection blocksCopy = i > 0 && i <= blocks.length ? blocks[i - 1].copy() : null;
+            SWMRNibbleArray.SaveState blockState = blockLight[i].getSaveState();
+            SWMRNibbleArray.SaveState skyState = skyLight[i].getSaveState();
+            if (blocksCopy == null && blockState == null && skyState == null) {
+                continue;
+            }
+            SerializableChunkData.SectionData section = new SerializableChunkData.SectionData(
+                    chunk.getMinSectionY() + i - 1, blocksCopy, layer(blockState), layer(skyState));
+            if (blockState != null) {
+                ((StarlightSectionData) (Object) section).starlight$setBlockLightState(blockState.state);
+            }
+            if (skyState != null) {
+                ((StarlightSectionData) (Object) section).starlight$setSkyLightState(skyState.state);
+            }
+            sections.add(section);
+        }
+        return sections;
+    }
+
+    private static DataLayer layer(SWMRNibbleArray.SaveState state) {
+        return state == null || state.data == null ? null : new DataLayer(state.data);
+    }
+
+    private static CompoundTag structures(ProtoChunk chunk, StructurePieceSerializationContext context) {
+        Registry<Structure> registry = context.registryAccess().lookupOrThrow(Registries.STRUCTURE);
+        CompoundTag starts = new CompoundTag();
+        for (Map.Entry<Structure, StructureStart> entry : chunk.getAllStarts().entrySet()) {
+            starts.put(Objects.requireNonNull(registry.getKey(entry.getKey()), "structure key").toString(),
+                    entry.getValue().createTag(context, chunk.getPos()));
+        }
+        CompoundTag references = new CompoundTag();
+        for (Map.Entry<Structure, LongSet> entry : chunk.getAllReferences().entrySet()) {
+            if (!entry.getValue().isEmpty()) {
+                references.putLongArray(Objects.requireNonNull(registry.getKey(entry.getKey()), "structure key").toString(),
+                        entry.getValue().toLongArray());
+            }
+        }
+        CompoundTag result = new CompoundTag();
+        result.put("starts", starts);
+        result.put("References", references);
+        return result;
+    }
+
+    record Context(StructurePieceSerializationContext structures, PalettedContainerFactory containers, long gameTime) {
+        Context {
+            Objects.requireNonNull(structures, "structures");
+            Objects.requireNonNull(containers, "containers");
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessNativeBiomeWriter.java

@@ -0,0 +1,33 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.spi.PlatformBiomeWriter;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBiome;
+import art.arcane.volmlib.nativelib.terrain.NativeBiome;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.Registry;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+
+import java.util.List;
+import java.util.function.Supplier;
+
+record HeadlessNativeBiomeWriter(Supplier<HolderLookup.Provider> registries) implements PlatformBiomeWriter {
+    @Override
+    public int biomeIdFor(String key) {
+        Registry<Biome> registry = registry();
+        Biome biome = registry.getOrThrow(ResourceKey.create(Registries.BIOME, Identifier.parse(key))).value();
+        return registry.getId(biome);
+    }
+
+    @Override
+    public List<NativeBiome> allBiomes() {
+        return registry().listElements().map(holder -> (NativeBiome) ModdedBiome.of(
+                holder.value(), holder.key().identifier().toString())).toList();
+    }
+
+    private Registry<Biome> registry() {
+        return (Registry<Biome>) registries.get().lookupOrThrow(Registries.BIOME);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessNativeBootstrap.java

@@ -0,0 +1,47 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.component.DataComponentInitializers;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.tags.TagLoader;
+
+import java.util.List;
+
+final class HeadlessNativeBootstrap {
+    private static boolean initialized;
+
+    private HeadlessNativeBootstrap() {
+    }
+
+    static synchronized void bindComponents(HolderLookup.Provider registries) {
+        List<DataComponentInitializers.PendingComponents<?>> pending =
+                BuiltInRegistries.DATA_COMPONENT_INITIALIZERS.build(registries);
+        for (DataComponentInitializers.PendingComponents<?> components : pending) {
+            components.apply();
+        }
+    }
+
+    static synchronized void initialize() {
+        if (initialized) {
+            return;
+        }
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        try (MultiPackResourceManager resources = new MultiPackResourceManager(PackType.SERVER_DATA,
+                List.of(ServerPacksSource.createVanillaPackSource().fullResources()))) {
+            List<Registry.PendingTags<?>> pending = TagLoader.loadTagsForExistingRegistries(resources,
+                    RegistryAccess.fromRegistryOfRegistries(BuiltInRegistries.REGISTRY));
+            for (Registry.PendingTags<?> tags : pending) {
+                tags.apply();
+            }
+        }
+        initialized = true;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessNativePlatform.java

@@ -0,0 +1,273 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.configuration.IrisSettings;
+import art.arcane.iris.platform.bukkit.nms.BukkitGenerationRegistry;
+import art.arcane.iris.spi.IrisPlatform;
+import art.arcane.iris.spi.PlatformGenerationRegistry;
+import art.arcane.iris.spi.LogLevel;
+import art.arcane.iris.spi.PlatformBiomeWriter;
+import art.arcane.iris.spi.PlatformRegistries;
+import art.arcane.iris.spi.PlatformScheduler;
+import art.arcane.iris.spi.PlatformStructureHooks;
+import art.arcane.volmlib.nativelib.entity.NativeEntityType;
+import art.arcane.volmlib.nativelib.item.NativeItem;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeBlockResolver;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeRegistryAccess;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeGenerationRegistryImpl;
+import art.arcane.volmlib.nativelib.terrain.NativeBiome;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockProperty;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import art.arcane.volmlib.nativelib.terrain.NativeWorld;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.RegistryAccess;
+
+import java.io.File;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.function.Supplier;
+
+final class HeadlessNativePlatform implements IrisPlatform, PlatformRegistries, NativeBlockResolver.Policy {
+    private final StubPlatform services;
+    private final NativeRegistryAccess nativeAccess;
+    private final PlatformBiomeWriter biomeWriter;
+    private final PlatformGenerationRegistry generationRegistry;
+    private final NativeBlockResolver blocks = new NativeBlockResolver(this);
+    private final NativeBlockState air = blocks.getAir();
+    private final ConcurrentHashMap<String, NativeBlockState> states = new ConcurrentHashMap<>();
+
+    HeadlessNativePlatform(File root, Supplier<HolderLookup.Provider> registries) {
+        services = new StubPlatform(root);
+        biomeWriter = new HeadlessNativeBiomeWriter(registries);
+        generationRegistry = new BukkitGenerationRegistry(new NativeGenerationRegistryImpl(() -> {
+            HolderLookup.Provider lookup = registries.get();
+            if (lookup instanceof RegistryAccess access) {
+                return access;
+            }
+            throw new IllegalStateException("Generation registry contract requires loaded native registries");
+        }), "bukkit-generation-registry-v1");
+        nativeAccess = new NativeRegistryAccess(new NativeRegistryAccess.Configuration(registries,
+                () -> { throw new UnsupportedOperationException("Headless reloadable registries are not loaded"); },
+                message -> { throw new IllegalStateException("Unavailable native registry: " + message); }));
+    }
+
+    NativeBlockResolver blocks() {
+        return blocks;
+    }
+
+    @Override
+    public PlatformRegistries registries() {
+        return this;
+    }
+
+    @Override
+    public PlatformGenerationRegistry generationRegistry() {
+        return generationRegistry;
+    }
+
+    @Override
+    public String platformName() {
+        return "headless-native-core";
+    }
+
+    @Override
+    public String minecraftVersion() {
+        return SharedConstants.getCurrentVersion().name();
+    }
+
+    @Override
+    public NativeBlockState decodeBlockState(String key) {
+        return states.computeIfAbsent(key, NativeBlockResolver::strictParse);
+    }
+
+    @Override
+    public NativeBlockState block(String key) {
+        return states.computeIfAbsent(key, candidate -> Objects.requireNonNull(blocks.getOrNull(candidate, true),
+                "Unresolved native block: " + candidate));
+    }
+
+    @Override
+    public NativeBlockState blockOrNull(String key) {
+        return blocks.getOrNull(key);
+    }
+
+    @Override
+    public NativeBlockState blockOrNull(String key, boolean warn) {
+        return blocks.getOrNull(key, warn);
+    }
+
+    @Override
+    public NativeBlockState air() {
+        return air;
+    }
+
+    @Override
+    public ModdedBlockState resolveCustomBlock(String key) {
+        return null;
+    }
+
+    @Override
+    public boolean preventLeafDecay() {
+        return IrisSettings.get().getGenerator().isPreventLeafDecay();
+    }
+
+    @Override
+    public void reportError(String key, Throwable failure) {
+        services.reportError(failure);
+        failure.printStackTrace(System.err);
+    }
+
+    @Override
+    public void warnUnresolved(String key, String message) {
+        throw new IllegalArgumentException(message + ": " + key);
+    }
+
+    @Override
+    public void debug(String message) {
+        services.log(LogLevel.DEBUG, message);
+    }
+
+    @Override
+    public NativeBlockState deepSlateOre(NativeBlockState block, NativeBlockState ore) {
+        return nativeAccess.deepSlateOre(block, ore);
+    }
+
+    @Override
+    public NativeBiome biome(String key) {
+        return nativeAccess.biome(key);
+    }
+
+    @Override
+    public NativeItem item(String key) {
+        return nativeAccess.item(key);
+    }
+
+    @Override
+    public NativeEntityType entity(String key) {
+        return nativeAccess.entity(key);
+    }
+
+    @Override
+    public List<String> blockKeys() {
+        return nativeAccess.blockKeys();
+    }
+
+    @Override
+    public List<String> biomeKeys() {
+        return nativeAccess.biomeKeys();
+    }
+
+    @Override
+    public List<String> structureKeys() {
+        return nativeAccess.structureKeys();
+    }
+
+    @Override
+    public List<String> itemKeys() {
+        return nativeAccess.itemKeys();
+    }
+
+    @Override
+    public List<String> entityKeys() {
+        return nativeAccess.entityKeys();
+    }
+
+    @Override
+    public List<String> enchantmentKeys() {
+        return nativeAccess.enchantmentKeys();
+    }
+
+    @Override
+    public List<String> potionEffectKeys() {
+        return nativeAccess.potionEffectKeys();
+    }
+
+    @Override
+    public List<String> lootTableKeys() {
+        return nativeAccess.lootTableKeys();
+    }
+
+    @Override
+    public Map<String, List<NativeBlockProperty>> blockStateProperties() {
+        return nativeAccess.blockStateProperties();
+    }
+
+    @Override
+    public List<String> blockTypeKeys() {
+        return blockKeys();
+    }
+
+    @Override
+    public PlatformScheduler scheduler() {
+        return services.scheduler();
+    }
+
+    @Override
+    public PlatformStructureHooks structureHooks() {
+        return services.structureHooks();
+    }
+
+    @Override
+    public PlatformBiomeWriter biomeWriter() {
+        return biomeWriter;
+    }
+
+    @Override
+    public File dataFolder() {
+        return services.dataFolder();
+    }
+
+    @Override
+    public File dataFile(String... path) {
+        return services.dataFile(path);
+    }
+
+    @Override
+    public File pluginJar() {
+        return services.pluginJar();
+    }
+
+    @Override
+    public int irisVersionNumber() {
+        return services.irisVersionNumber();
+    }
+
+    @Override
+    public int minecraftVersionNumber() {
+        return Integer.parseInt(minecraftVersion().replace(".", ""));
+    }
+
+    @Override
+    public void callEvent(Object event) {
+        services.callEvent(event);
+    }
+
+    @Override
+    public void dispatchConsoleCommand(String command) {
+        services.dispatchConsoleCommand(command);
+    }
+
+    @Override
+    public boolean spawnEntity(NativeWorld world, String entityKey, double x, double y, double z) {
+        return services.spawnEntity(world, entityKey, x, y, z);
+    }
+
+    @Override
+    public void log(LogLevel level, String message) {
+        services.log(level, message);
+    }
+
+    @Override
+    public void msg(String message) {
+        services.msg(message);
+    }
+
+    @Override
+    public void reportError(Throwable error) {
+        services.reportError(error);
+    }
+
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessNativeRegistries.java

@@ -0,0 +1,116 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.pack.datapack.IrisDatapackCompiler;
+import art.arcane.iris.pack.datapack.v263.DataFixerV263;
+import art.arcane.volmlib.util.collection.KList;
+
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.network.chat.Component;
+import net.minecraft.resources.RegistryDataLoader;
+import net.minecraft.server.packs.PackLocationInfo;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.PathPackResources;
+import net.minecraft.server.packs.repository.PackSource;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+
+import java.io.IOException;
+import java.io.File;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.stream.Stream;
+
+final class HeadlessNativeRegistries implements AutoCloseable {
+    private final Path directory;
+    private final MultiPackResourceManager resources;
+    private final RegistryAccess.Frozen registries;
+
+    private HeadlessNativeRegistries(Path directory, MultiPackResourceManager resources, RegistryAccess.Frozen registries) {
+        this.directory = directory;
+        this.resources = resources;
+        this.registries = registries;
+    }
+
+    static HeadlessNativeRegistries load(Map<String, String> definitions) throws IOException {
+        HeadlessNativeBootstrap.initialize();
+        Path directory = Files.createTempDirectory("iris-native-registry-");
+        try {
+            for (Map.Entry<String, String> definition : definitions.entrySet()) {
+                Path file = directory.resolve(definition.getKey()).normalize();
+                if (!file.startsWith(directory.resolve("data")) || !file.toString().endsWith(".json")) {
+                    throw new IllegalArgumentException("Invalid generated registry resource " + definition.getKey());
+                }
+                Files.createDirectories(file.getParent());
+                Files.writeString(file, definition.getValue());
+            }
+            return load(directory);
+        } catch (IOException | RuntimeException failure) {
+            delete(directory);
+            throw failure;
+        }
+    }
+
+    static HeadlessNativeRegistries compile(File pack) throws IOException {
+        HeadlessNativeBootstrap.initialize();
+        Path directory = Files.createTempDirectory("iris-native-pack-");
+        try {
+            IrisDatapackCompiler.compile(List.of(pack), new KList<>(directory.toFile()), List.of(),
+                    new DataFixerV263(), false);
+            return load(directory);
+        } catch (IOException | RuntimeException failure) {
+            delete(directory);
+            throw failure;
+        }
+    }
+
+    private static HeadlessNativeRegistries load(Path directory) {
+        PackLocationInfo location = new PackLocationInfo("iris-headless", Component.literal("Iris"),
+                PackSource.WORLD, Optional.empty());
+        MultiPackResourceManager resources = new MultiPackResourceManager(PackType.SERVER_DATA, List.of(
+                ServerPacksSource.createVanillaPackSource().fullResources(), new PathPackResources(location, directory)));
+        try {
+            RegistryAccess.Frozen builtins = RegistryAccess.fromRegistryOfRegistries(BuiltInRegistries.REGISTRY);
+            RegistryAccess.Frozen loaded;
+            try (ExecutorService executor = Executors.newFixedThreadPool(4)) {
+                loaded = RegistryDataLoader.load(resources, builtins.listRegistries().toList(),
+                        RegistryDataLoader.WORLD_REGISTRIES, executor).join();
+            }
+            RegistryAccess.Frozen registries = new RegistryAccess.ImmutableRegistryAccess(
+                    Stream.concat(builtins.registries(), loaded.registries())).freeze();
+            HeadlessNativeBootstrap.bindComponents(registries);
+            return new HeadlessNativeRegistries(directory, resources, registries);
+        } catch (RuntimeException failure) {
+            resources.close();
+            throw failure;
+        }
+    }
+
+    RegistryAccess.Frozen registries() {
+        return registries;
+    }
+
+    MultiPackResourceManager resources() {
+        return resources;
+    }
+
+    @Override
+    public void close() throws IOException {
+        resources.close();
+        delete(directory);
+    }
+
+    private static void delete(Path directory) throws IOException {
+        try (Stream<Path> paths = Files.walk(directory)) {
+            for (Path path : paths.sorted(Comparator.reverseOrder()).toList()) {
+                Files.delete(path);
+            }
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessNativeRuntime.java

@@ -0,0 +1,109 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.block.BlockDataMergeSupport;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.structure.nativegen.NativeStructureVolumeIndex;
+import art.arcane.volmlib.nativelib.terrain.structure.NativeStructureVolume;
+import art.arcane.volmlib.util.collection.KList;
+import art.arcane.iris.generation.block.TileData;
+import art.arcane.iris.generation.decoration.DecoratorPlatformHooks;
+import art.arcane.iris.generation.terrain.IrisDimension;
+import art.arcane.iris.modded.ModdedDecoratorHooks;
+import art.arcane.iris.modded.ModdedStateRotator;
+import art.arcane.iris.modded.ModdedTileData;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeTileReader;
+import art.arcane.iris.pack.datapack.v263.DataFixerV263;
+import art.arcane.iris.pack.loading.IrisData;
+import art.arcane.iris.world.history.GenerationHistory;
+import art.arcane.iris.spi.IrisPlatform;
+import art.arcane.iris.structure.object.IrisObjectRotation;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeStateMerger;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.file.Path;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.data.registries.VanillaRegistries;
+import net.minecraft.server.packs.resources.ResourceManager;
+
+final class HeadlessNativeRuntime implements RealPackProbeSupport.RuntimeBindings {
+    private final Path stagingRoot;
+    private NativeRegionTerrainWriter writer;
+    private HeadlessNativeRegistries nativeRegistries;
+    private HolderLookup.Provider registries;
+
+    HeadlessNativeRuntime() {
+        stagingRoot = null;
+    }
+
+    HeadlessNativeRuntime(Path stagingRoot) throws IOException {
+        this.stagingRoot = stagingRoot.toRealPath();
+    }
+
+    @Override
+    public IrisPlatform create(File root) {
+        HeadlessNativeBootstrap.initialize();
+        registries = VanillaRegistries.createWorldLookup();
+        HeadlessNativePlatform platform = new HeadlessNativePlatform(root, () -> registries);
+        ModdedDecoratorHooks decorators = new ModdedDecoratorHooks();
+        DecoratorPlatformHooks.bind(decorators, decorators);
+        IrisObjectRotation.bindPlatformRotator(new ModdedStateRotator());
+        BlockDataMergeSupport.bindPlatformMerger(new NativeStateMerger(platform.blocks())::merge);
+        NativeTileReader tiles = new NativeTileReader(() -> registries);
+        TileData.bindPlatformReader(input -> ModdedTileData.wrap(tiles.read(input)));
+        TileData.bindPlatformFactory(ModdedTileData::fromProperties);
+        return platform;
+    }
+
+    @Override
+    public void prepare(IrisData data, IrisDimension dimension) {
+        try {
+            if (nativeRegistries != null) {
+                throw new IllegalStateException("Headless native runtime supports one immutable pack per process");
+            }
+            nativeRegistries = HeadlessNativeRegistries.compile(data.getDataFolder());
+            registries = nativeRegistries.registries();
+            writer = new NativeRegionTerrainWriter(nativeRegistries.registries());
+        } catch (IOException failure) {
+            throw new UncheckedIOException("Cannot load native generation registries", failure);
+        }
+    }
+
+    @Override
+    public KList<NativeStructureVolume> nativeStructureVolumes(Engine engine, int minX, int minZ, int maxX, int maxZ) {
+        return NativeStructureVolumeIndex.volumes(engine, minX, minZ, maxX, maxZ);
+    }
+
+    @Override
+    public GenerationHistory createHistory(RealPackProbeSupport.HistoryRequest request) throws IOException {
+        if (stagingRoot != null) {
+            if (!request.worldRoot().getParent().toRealPath().startsWith(stagingRoot)) {
+                throw new IOException("Unpublished native generation must remain inside its private staging directory");
+            }
+            return HeadlessGenerationHistorySession.createUnpublished(request, new DataFixerV263());
+        }
+        return HeadlessGenerationHistorySession.create(request, new DataFixerV263());
+    }
+
+    @Override
+    public void close() throws IOException {
+        if (nativeRegistries != null) {
+            nativeRegistries.close();
+            nativeRegistries = null;
+        }
+    }
+
+    RegistryAccess.Frozen registries() {
+        return nativeRegistries.registries();
+    }
+
+    ResourceManager resources() {
+        return nativeRegistries.resources();
+    }
+
+    NativeRegionTerrainWriter writer() {
+        return writer;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessRegionTerrain.java

@@ -0,0 +1,211 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.context.IrisContext;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.runtime.GenerationSessionLease;
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.iris.world.history.NativeTerrainReceipt;
+import art.arcane.volmlib.nativelib.terrain.NativeBiome;
+import art.arcane.volmlib.nativelib.terrain.NativeBiomeSourcePolicy;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.volmlib.util.hunk.Hunk;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainPipeline;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.WorldgenTerrainHeightmaps;
+import net.minecraft.core.Holder;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Consumer;
+
+final class HeadlessRegionTerrain {
+    private static final NamespacedKey STRUCTURE_ACTIVATION = new NamespacedKey("iris", "structure_activation");
+    private static final NamespacedKey NATURAL_TERRAIN = new NamespacedKey("iris", "natural_terrain");
+
+    private HeadlessRegionTerrain() {
+    }
+
+    static final class Session {
+        private final Map<Long, HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord>> chunks = new HashMap<>();
+        private final RegionGenerationWindow workers;
+        private HeadlessTerrainContext context;
+
+        Session(RegionGenerationWindow workers) {
+            this.workers = Objects.requireNonNull(workers, "workers");
+        }
+
+        Result generate(Request request, Consumer<String> progress) throws Exception {
+            workers.requireOpen();
+            if (context != null && context != request.context()) {
+                throw new IllegalArgumentException("Rolling regions require one native terrain context");
+            }
+            context = request.context();
+            List<NativeRegionPlan.PlannedChunk> plan = NativeRegionPlan.plan(
+                    request.chunkX(), request.chunkZ(), request.width());
+            Set<Long> retained = new HashSet<>(plan.size());
+            for (NativeRegionPlan.PlannedChunk planned : plan) {
+                retained.add(ChunkPos.pack(planned.x(), planned.z()));
+            }
+            chunks.keySet().retainAll(retained);
+            Map<Long, ChunkStatus> previous = new HashMap<>(chunks.size());
+            for (Map.Entry<Long, HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord>> entry : chunks.entrySet()) {
+                previous.put(entry.getKey(), entry.getValue().chunk().getPersistedStatus());
+            }
+            for (ChunkStatus status : List.of(ChunkStatus.STRUCTURE_STARTS, ChunkStatus.STRUCTURE_REFERENCES,
+                    ChunkStatus.BIOMES, ChunkStatus.TERRAIN)) {
+                List<NativeRegionPlan.PlannedChunk> eligible = new ArrayList<>();
+                for (NativeRegionPlan.PlannedChunk planned : plan) {
+                    HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> existing =
+                            chunks.get(ChunkPos.pack(planned.x(), planned.z()));
+                    if (planned.status().isOrAfter(status)
+                            && (status != ChunkStatus.BIOMES || planned.status() == ChunkStatus.BIOMES)
+                            && (existing == null || existing.chunk().getPersistedStatus().isBefore(status))) {
+                        eligible.add(planned);
+                    }
+                }
+                if (eligible.isEmpty()) {
+                    continue;
+                }
+                long started = System.nanoTime();
+                AtomicInteger completed = new AtomicInteger();
+                workers.process(new RegionGenerationWindow.Request<>(eligible.size(), request.parallelism(),
+                        index -> apply(request.context(), eligible.get(index), status, chunks),
+                        (index, result) -> {
+                            if (status == ChunkStatus.STRUCTURE_STARTS) {
+                                chunks.put(result.chunk().getPos().pack(), result);
+                            }
+                            int count = completed.incrementAndGet();
+                            if (count % 128 == 0 || count == eligible.size()) {
+                                progress.accept("stage=" + status.getName() + " chunks=" + count + "/" + eligible.size()
+                                        + " seconds=" + (System.nanoTime() - started) / 1_000_000_000.0);
+                            }
+                        }));
+                failReported();
+            }
+            List<ProtoChunk> ordered = new ArrayList<>(plan.size());
+            List<ProtoChunk> updated = new ArrayList<>();
+            for (NativeRegionPlan.PlannedChunk planned : plan) {
+                ProtoChunk chunk = chunks.get(ChunkPos.pack(planned.x(), planned.z())).chunk();
+                if (chunk.getPersistedStatus().isBefore(planned.status())) {
+                    throw new IllegalStateException("Incomplete native stage at " + chunk.getPos());
+                }
+                ordered.add(chunk);
+                ChunkStatus prior = previous.get(chunk.getPos().pack());
+                if (prior == null || chunk.getPersistedStatus().isAfter(prior)) {
+                    updated.add(chunk);
+                }
+            }
+            return new Result(List.copyOf(ordered), List.copyOf(updated), request.width() * request.width());
+        }
+    }
+
+    private static HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> apply(
+            HeadlessTerrainContext context, NativeRegionPlan.PlannedChunk planned, ChunkStatus status,
+            Map<Long, HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord>> chunks) throws Exception {
+        Engine engine = context.engine();
+        GenerationHistoryRuntimeRouter router = ((IrisEngine) engine).getGenerationHistoryRuntimeRouter().orElseThrow();
+        try (GenerationHistoryRuntimeRouter.RuntimeRoute route = router.openRoute(planned.x(), planned.z());
+             GenerationHistoryRuntimeRouter.RuntimeRoute.RuntimeScope scope = route.openRuntimeScope();
+             GenerationSessionLease lease = engine.acquireGenerationLease("headless_native_terrain");
+             IrisContext.Scope generation = IrisContext.open(engine, lease.sessionId(), null)) {
+            if (status == ChunkStatus.STRUCTURE_STARTS) {
+                HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> result = HeadlessStructurePlanner.plan(
+                        context.structures(), context.policies(), new ChunkPos(planned.x(), planned.z()));
+                result.chunk().persistentDataContainer.set(STRUCTURE_ACTIVATION,
+                        PersistentDataType.LONG, route.activation().activationId());
+                return result;
+            }
+            HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> result = Objects.requireNonNull(
+                    chunks.get(ChunkPos.pack(planned.x(), planned.z())), "planned structure chunk");
+            if (status == ChunkStatus.STRUCTURE_REFERENCES) {
+                HeadlessStructurePlanner.references(context.policies(), result, chunks);
+            } else if (status == ChunkStatus.BIOMES) {
+                biomes(context, result.chunk());
+            } else if (status == ChunkStatus.TERRAIN) {
+                if (result.chunk().getPersistedStatus().isBefore(ChunkStatus.BIOMES)) {
+                    biomes(context, result.chunk());
+                }
+                terrain(context, result.chunk(), route);
+            } else {
+                throw new IllegalArgumentException("Unsupported headless native stage " + status);
+            }
+            return result;
+        }
+    }
+
+    private static void biomes(HeadlessTerrainContext context, ProtoChunk chunk) {
+        context.biomes().prepareVisibleBiomeBatch();
+        NativeBiomeSourcePolicy.VisibleResolver<Holder<Biome>> resolver = context.biomes().visibleResolver();
+        chunk.fillBiomesFromNoise(resolver::biome);
+        chunk.setPersistedStatus(ChunkStatus.BIOMES);
+    }
+
+    private static void terrain(HeadlessTerrainContext context, ProtoChunk target,
+                                GenerationHistoryRuntimeRouter.RuntimeRoute route) throws Exception {
+        Engine engine = context.engine();
+        ChunkPos position = target.getPos();
+        Hunk<NativeBlockState> blocks = Hunk.newArrayHunk(16, engine.getHeight(), 16);
+        Hunk<NativeBiome> biomes = Hunk.newArrayHunk(16, engine.getHeight(), 16);
+        engine.generate(position.x() << 4, position.z() << 4, blocks, biomes, true);
+        context.writer().fill(target, new NativeRegionTerrainWriter.TerrainInput(position.x(), position.z(),
+                engine.getMinHeight(), engine.getHeight(),
+                (x, y, z) -> blockState(blocks.getRaw(x, y, z)),
+                (x, y, z) -> Objects.requireNonNull(biomes.getRaw(x, y, z), "Generated native biome").key(), List.of()));
+        NativeTerrainPipeline.claimGeneratedSemantics(route, target, engine.getMinHeight());
+        target.persistentDataContainer.set(NATURAL_TERRAIN, PersistentDataType.BYTE_ARRAY,
+                NativeTerrainReceipt.encode(route.naturalTerrain().orElseThrow(),
+                        route.activation().activationId(), route.epoch().epochId()));
+        WorldgenTerrainHeightmaps.primeTerrain(target,
+                (x, z) -> engine.getHeight(x, z, false) + engine.getMinHeight() + 1,
+                (x, z) -> engine.getHeight(x, z, true) + engine.getMinHeight() + 1);
+        Heightmap.primeHeightmaps(target, EnumSet.of(Heightmap.Types.MOTION_BLOCKING,
+                Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, Heightmap.Types.OCEAN_FLOOR, Heightmap.Types.WORLD_SURFACE));
+        target.setPersistedStatus(ChunkStatus.TERRAIN);
+        target.markUnsaved();
+    }
+
+    private static BlockState blockState(NativeBlockState state) {
+        return state == null ? Blocks.AIR.defaultBlockState() : ((ModdedBlockState) state).handle();
+    }
+
+    private static void failReported() {
+        List<Throwable> reports = RealPackProbeSupport.drainReported();
+        if (!reports.isEmpty()) {
+            IllegalStateException failure = new IllegalStateException("Native terrain generation reported errors");
+            for (Throwable report : reports) {
+                failure.addSuppressed(report);
+            }
+            throw failure;
+        }
+    }
+
+    record Request(HeadlessTerrainContext context, int chunkX, int chunkZ, int width, int parallelism) {
+        Request {
+            Objects.requireNonNull(context, "context");
+            if (parallelism < 1 || parallelism > 32) {
+                throw new IllegalArgumentException("Headless native parallelism must be 1..32");
+            }
+        }
+    }
+
+    record Result(List<ProtoChunk> chunks, List<ProtoChunk> updated, int targetChunks) {
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessStructureConfiguration.java

@@ -0,0 +1,104 @@
+package art.arcane.iris.probe;
+
+import net.kyori.adventure.key.Key;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.Level;
+import org.bukkit.Bukkit;
+import org.bukkit.configuration.ConfigurationSection;
+import org.bukkit.configuration.InvalidConfigurationException;
+import org.bukkit.configuration.file.YamlConfiguration;
+import org.spigotmc.SpigotConfig;
+import org.spigotmc.SpigotWorldConfig;
+
+import java.io.File;
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.util.Objects;
+
+final class HeadlessStructureConfiguration {
+    private static final int CONFIG_VERSION = 13;
+    private static final Field CONFIG_FILE = nativeField("CONFIG_FILE");
+    private static final Field VERSION = nativeField("version");
+
+    private HeadlessStructureConfiguration() {
+    }
+
+    static SpigotWorldConfig load(Options options) throws IOException {
+        if (Bukkit.getServer() != null) {
+            throw new IllegalStateException("Headless structure configuration cannot initialize inside a Bukkit server");
+        }
+        Files.createDirectories(options.stagingDirectory());
+        Path staged = Files.createTempFile(options.stagingDirectory(), "spigot-structures-", ".yml");
+        try {
+            Files.copy(options.source(), staged, StandardCopyOption.REPLACE_EXISTING);
+            YamlConfiguration configuration = new YamlConfiguration();
+            configuration.load(staged.toFile());
+            configuration.options().copyDefaults(true);
+            int version = configuration.getInt("config-version", CONFIG_VERSION);
+            String worldName = options.levelKey().identifier().toString();
+            prepareEnvironment(configuration, options.legacyWorldName(), worldName, version);
+            configuration.set("config-version", CONFIG_VERSION);
+            return initialize(options, staged, configuration);
+        } catch (InvalidConfigurationException | ReflectiveOperationException | RuntimeException failure) {
+            throw new IOException("Could not initialize native structure configuration from " + options.source(), failure);
+        } finally {
+            Files.deleteIfExists(staged);
+        }
+    }
+
+    private static void prepareEnvironment(YamlConfiguration configuration, String legacyWorldName,
+                                           String worldName, int version) {
+        if (version <= 12) {
+            ConfigurationSection legacy = configuration.getConfigurationSection("world-settings." + legacyWorldName);
+            if (legacy != null) {
+                configuration.set("world-settings." + legacyWorldName, null);
+                configuration.set("world-settings." + worldName, legacy);
+            }
+        }
+        String worldPath = "world-settings." + worldName + ".";
+        configuration.set(worldPath + "verbose", false);
+        configuration.set(worldPath + "view-distance", 3);
+        configuration.set(worldPath + "simulation-distance", 3);
+    }
+
+    private static SpigotWorldConfig initialize(Options options, Path staged, YamlConfiguration configuration)
+            throws ReflectiveOperationException {
+        synchronized (SpigotConfig.class) {
+            YamlConfiguration previousConfiguration = SpigotConfig.config;
+            File previousFile = (File) CONFIG_FILE.get(null);
+            int previousVersion = VERSION.getInt(null);
+            try {
+                SpigotConfig.config = configuration;
+                CONFIG_FILE.set(null, staged.toFile());
+                VERSION.setInt(null, CONFIG_VERSION);
+                return new SpigotWorldConfig(options.legacyWorldName(), Key.key(options.levelKey().identifier().toString()));
+            } finally {
+                SpigotConfig.config = previousConfiguration;
+                CONFIG_FILE.set(null, previousFile);
+                VERSION.setInt(null, previousVersion);
+            }
+        }
+    }
+
+    private static Field nativeField(String name) {
+        try {
+            Field field = SpigotConfig.class.getDeclaredField(name);
+            field.setAccessible(true);
+            return field;
+        } catch (ReflectiveOperationException failure) {
+            throw new ExceptionInInitializerError(failure);
+        }
+    }
+
+    record Options(Path source, String legacyWorldName, ResourceKey<Level> levelKey, Path stagingDirectory) {
+        Options {
+            Objects.requireNonNull(source, "source");
+            Objects.requireNonNull(legacyWorldName, "legacyWorldName");
+            Objects.requireNonNull(levelKey, "levelKey");
+            Objects.requireNonNull(stagingDirectory, "stagingDirectory");
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessStructurePlanner.java

@@ -0,0 +1,333 @@
+package art.arcane.iris.probe;
+
+import art.arcane.volmlib.nativelib.terrain.NativeGenerationScope;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureInjectionPolicy;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureOwnershipRecordView;
+import art.arcane.volmlib.nativelib.terrain.structure.StructurePlacementDecision;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureReferencePolicy;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureStartPlan;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureTerrainSettings;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureFactory;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureOwnershipFingerprint;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceRepair;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureTerrainIntegrator;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVegetationClearer;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+import it.unimi.dsi.fastutil.longs.LongOpenHashSet;
+import it.unimi.dsi.fastutil.longs.LongSet;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Holder;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.biome.Climate;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.LegacyRandomSource;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.WorldgenRandom;
+import net.minecraft.world.level.levelgen.WorldOptions;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureSet;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacement;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.function.Predicate;
+
+final class HeadlessStructurePlanner {
+    private HeadlessStructurePlanner() {
+    }
+
+    static <P extends StructureStartPlan, O extends StructureOwnershipRecordView<O>> PlannedChunk<O> plan(
+            NativeContext context, Policies<P, O> policies, ChunkPos position) {
+        ProtoChunk chunk = new ProtoChunk(position, UpgradeData.EMPTY,
+                LevelHeightAccessor.create(context.generator().getMinY(), context.generator().getGenDepth()),
+                PalettedContainerFactory.create(context.registries()), null);
+        if (!context.enabled()) {
+            chunk.setPersistedStatus(ChunkStatus.STRUCTURE_STARTS);
+            return new PlannedChunk<O>(context, chunk, Map.of(), Map.of());
+        }
+        try (NativeGenerationScope scope = policies.references().openOriginScope(chunk.getPos().x(), chunk.getPos().z())) {
+            generateNaturalStarts(context, chunk);
+            Map<Structure, O> ownership = inject(context, policies, chunk);
+            Map<Structure, StructureTerrainSettings> terrain = adjust(context, policies, chunk, ownership);
+            chunk.setPersistedStatus(ChunkStatus.STRUCTURE_STARTS);
+            return new PlannedChunk<>(context, chunk, Map.copyOf(ownership), Map.copyOf(terrain));
+        }
+    }
+
+    static <P extends StructureStartPlan, O extends StructureOwnershipRecordView<O>> void references(
+            Policies<P, O> policies, PlannedChunk<O> target, Map<Long, PlannedChunk<O>> grid) {
+        ChunkPos position = target.chunk().getPos();
+        List<PlannedChunk<O>> origins = new ArrayList<>(289);
+        if (target.chunk().getPersistedStatus() != ChunkStatus.STRUCTURE_STARTS) {
+            throw new IllegalArgumentException("Structure references require an unreferenced planned chunk: " + position);
+        }
+        if (!target.context().adapterEnabled()) {
+            target.chunk().setPersistedStatus(ChunkStatus.STRUCTURE_REFERENCES);
+            return;
+        }
+        for (int x = position.x() - 8; x <= position.x() + 8; x++) {
+            for (int z = position.z() - 8; z <= position.z() + 8; z++) {
+                PlannedChunk<O> origin = grid.get(ChunkPos.pack(x, z));
+                if (origin == null || origin.context() != target.context()
+                        || origin.chunk().getPos().x() != x || origin.chunk().getPos().z() != z
+                        || !origin.chunk().getPersistedStatus().isOrAfter(ChunkStatus.STRUCTURE_STARTS)) {
+                    throw new IllegalArgumentException("Missing matching structure origin at " + x + "," + z);
+                }
+                origins.add(origin);
+            }
+        }
+        Map<Structure, LongSet> references = new HashMap<>();
+        Registry<Structure> registry = target.context().registries().lookupOrThrow(Registries.STRUCTURE);
+        for (PlannedChunk<O> origin : origins) {
+            ChunkPos source = origin.chunk().getPos();
+            try (NativeGenerationScope scope = policies.references().openOriginScope(source.x(), source.z())) {
+                for (Map.Entry<Structure, StructureStart> entry : origin.chunk().getAllStarts().entrySet()) {
+                    StructureStart start = entry.getValue();
+                    if (!start.isValid()) {
+                        continue;
+                    }
+                    String key = Objects.requireNonNull(registry.getKey(entry.getKey()), "structure key").toString();
+                    if (!NativeStructureReferenceEnvelope.contentFitsReferenceRange(start)) {
+                        throw new IllegalStateException("Planned structure exceeds its reference range: " + key);
+                    }
+                    O ownership = origin.ownership().get(entry.getKey());
+                    boolean relevant = ownership == null
+                            ? NativeStructureReferenceRepair.requiresNaturalReference(policies.references(), position,
+                            key, entry.getKey(), start)
+                            : NativeStructureReferenceRepair.requiresReference(position, key, start, ownership);
+                    if (relevant) {
+                        references.computeIfAbsent(entry.getKey(), ignored -> new LongOpenHashSet()).add(source.pack());
+                    }
+                }
+            }
+        }
+        target.chunk().setAllReferences(references);
+        target.chunk().setPersistedStatus(ChunkStatus.STRUCTURE_REFERENCES);
+    }
+
+    private static <P extends StructureStartPlan, O extends StructureOwnershipRecordView<O>> Map<Structure, O> inject(
+            NativeContext context, Policies<P, O> policies, ProtoChunk chunk) {
+        Registry<Structure> registry = context.registries().lookupOrThrow(Registries.STRUCTURE);
+        Map<Structure, O> ownership = new LinkedHashMap<>();
+        for (P plan : policies.injection().plansAt(chunk.getPos().x(), chunk.getPos().z())) {
+            Holder.Reference<Structure> holder = registry.getOrThrow(ResourceKey.create(Registries.STRUCTURE,
+                    Identifier.parse(plan.structureKey())));
+            Structure structure = holder.value();
+            if (ownership.containsKey(structure)) {
+                policies.injection().duplicate(plan.structureKey());
+                continue;
+            }
+            StructureStart existing = chunk.getStartForStructure(structure);
+            boolean replace = plan.replacesSource() || existing != null && existing.isValid()
+                    && policies.injection().sourceReplaced(plan.structureKey(),
+                    NativeStructureVegetationClearer.isUndergroundStep(structure.step()));
+            if (!replace && existing != null && existing.isValid()) {
+                continue;
+            }
+            int references = existing != null && existing.isValid() ? existing.getReferences() : 0;
+            StructureStart generated = NativeStructureFactory.generate(new NativeStructureFactory.GenerationContext(
+                    context.registries(), context.generator(), context.generator().getBiomeSource(),
+                    context.structureState().randomState(), context.templates(), context.structureState().getLevelSeed(),
+                    context.levelKey(), chunk, biome -> true, context.generator().getSeaLevel(),
+                    policies.injection()::surfaceHeight), holder, plan, references);
+            if (!generated.isValid()) {
+                if (replace) {
+                    chunk.setStartForStructure(structure, StructureStart.INVALID_START);
+                }
+                policies.injection().discard(plan.structureKey(), chunk.getPos().x(), chunk.getPos().z());
+                continue;
+            }
+            BoundingBox envelope = NativeStructureReferenceEnvelope.referenceBounds(generated, structure,
+                    plan.terrain(), plan.structureKey());
+            policies.injection().record(plan, NativeStructureOwnershipFingerprint.capture(plan.structureKey(), generated, envelope));
+            O recorded;
+            try {
+                recorded = policies.references().findPersisted(plan.structureKey(), chunk.getPos().x(), chunk.getPos().z());
+                if (!NativeStructureOwnershipFingerprint.matches(recorded, generated)) {
+                    throw new IllegalStateException("Configured structure ownership was not retained: " + plan.structureKey());
+                }
+                chunk.setStartForStructure(structure, generated);
+            } catch (RuntimeException | Error failure) {
+                try {
+                    policies.injection().discard(plan.structureKey(), chunk.getPos().x(), chunk.getPos().z());
+                } catch (RuntimeException | Error cleanupFailure) {
+                    failure.addSuppressed(cleanupFailure);
+                }
+                throw failure;
+            }
+            ownership.put(structure, recorded);
+        }
+        return ownership;
+    }
+
+    private static <P extends StructureStartPlan, O extends StructureOwnershipRecordView<O>> Map<Structure, StructureTerrainSettings> adjust(
+            NativeContext context, Policies<P, O> policies, ProtoChunk chunk, Map<Structure, O> ownership) {
+        Registry<Structure> registry = context.registries().lookupOrThrow(Registries.STRUCTURE);
+        Map<Structure, StructureTerrainSettings> terrain = new HashMap<>();
+        for (Map.Entry<Structure, StructureStart> entry : chunk.getAllStarts().entrySet()) {
+            Structure structure = entry.getKey();
+            StructureStart start = entry.getValue();
+            if (!start.isValid()) {
+                continue;
+            }
+            String key = Objects.requireNonNull(registry.getKey(structure), "structure key").toString();
+            if (!policies.allowsFootprint().test(start.getBoundingBox())) {
+                chunk.setStartForStructure(structure, StructureStart.INVALID_START);
+                if (ownership.remove(structure) != null) {
+                    policies.references().discard(key, chunk.getPos().x(), chunk.getPos().z());
+                }
+                continue;
+            }
+            O recorded = ownership.get(structure);
+            if (recorded != null) {
+                terrain.put(structure, NativeStructureTerrainIntegrator.resolveNativeTerrain(start, recorded.terrain()));
+                continue;
+            }
+            boolean underground = NativeStructureVegetationClearer.isUndergroundStep(structure.step());
+            StructurePlacementDecision decision = policies.references().resolve(key, underground);
+            if (!decision.generate()) {
+                chunk.setStartForStructure(structure, StructureStart.INVALID_START);
+                continue;
+            }
+            NativeStructureVerticalPlacer.applyVerticalPlacement(start, key, decision.yShift(),
+                    context.generator().getSeaLevel(), chunk.getMinY(), chunk.getMinY() + chunk.getHeight(),
+                    underground, decision.preserveSourceY(), decision.yBand(), policies.injection()::surfaceHeight);
+            StructureTerrainSettings resolved = NativeStructureTerrainIntegrator.resolveNativeTerrain(start, decision.terrain());
+            StructureStart wrapped = NativeStructureReferenceEnvelope.wrapForPublication(start, structure,
+                    start.getReferences(), resolved, key);
+            chunk.setStartForStructure(structure, wrapped);
+            if (wrapped.isValid()) {
+                terrain.put(structure, resolved);
+            }
+        }
+        return terrain;
+    }
+
+    static void generateNaturalStarts(NativeContext context, ChunkAccess chunk) {
+        if (!context.enabled() || SharedConstants.DEBUG_DISABLE_STRUCTURES) {
+            return;
+        }
+        RandomState random = context.structureState().randomState();
+        Climate.Sampler climate = random.createClimateSampler(SamplerContext.builder().enableCaches().build());
+        for (Holder<StructureSet> holder : context.structureState().possibleStructureSets()) {
+            generateSet(context, chunk, holder.value(), climate);
+        }
+    }
+
+    private static void generateSet(NativeContext context, ChunkAccess chunk, StructureSet set, Climate.Sampler climate) {
+        List<StructureSet.StructureSelectionEntry> entries = set.structures();
+        for (StructureSet.StructureSelectionEntry entry : entries) {
+            StructureStart existing = chunk.getStartForStructure(entry.structure().value());
+            if (existing != null && existing.isValid()) {
+                return;
+            }
+        }
+        StructurePlacement placement = set.placement();
+        ChunkPos position = chunk.getPos();
+        ResourceKey<StructureSet> key = placement instanceof ChunkGeneratorStructureState.KeyedRandomSpreadStructurePlacement keyed
+                ? keyed.key : null;
+        if (!placement.isStructureChunk(context.structureState(), position.x(), position.z(), key)) {
+            return;
+        }
+        if (entries.size() == 1) {
+            generate(context, chunk, entries.getFirst(), climate);
+            return;
+        }
+        ArrayList<StructureSet.StructureSelectionEntry> remaining = new ArrayList<>(entries);
+        WorldgenRandom random = new WorldgenRandom(new LegacyRandomSource(0L));
+        random.setLargeFeatureSeed(context.structureState().getLevelSeed(), position.x(), position.z());
+        int weight = 0;
+        for (StructureSet.StructureSelectionEntry entry : remaining) {
+            weight += entry.weight();
+        }
+        while (!remaining.isEmpty()) {
+            int selection = random.nextInt(weight);
+            int index = 0;
+            for (StructureSet.StructureSelectionEntry entry : remaining) {
+                selection -= entry.weight();
+                if (selection < 0) {
+                    break;
+                }
+                index++;
+            }
+            StructureSet.StructureSelectionEntry selected = remaining.get(index);
+            if (generate(context, chunk, selected, climate)) {
+                return;
+            }
+            remaining.remove(index);
+            weight -= selected.weight();
+        }
+    }
+
+    private static boolean generate(NativeContext context, ChunkAccess chunk,
+                                    StructureSet.StructureSelectionEntry entry, Climate.Sampler climate) {
+        Structure structure = entry.structure().value();
+        StructureStart existing = chunk.getStartForStructure(structure);
+        int references = existing == null ? 0 : existing.getReferences();
+        StructureStart generated = structure.generate(entry.structure(), context.levelKey(), context.registries(),
+                context.generator(), context.generator().getBiomeSource(), climate, context.structureState().randomState(),
+                context.templates(), context.structureState().getLevelSeed(), chunk.getPos(), references, chunk,
+                structure.biomes()::contains);
+        if (!generated.isValid()) {
+            return false;
+        }
+        chunk.setStartForStructure(structure, generated);
+        return true;
+    }
+
+    record NativeContext(RegistryAccess registries, ChunkGenerator generator,
+                         ChunkGeneratorStructureState structureState, StructureTemplateManager templates,
+                         ResourceKey<Level> levelKey, WorldOptions worldOptions, boolean adapterEnabled) {
+        NativeContext {
+            Objects.requireNonNull(registries, "registries");
+            Objects.requireNonNull(generator, "generator");
+            Objects.requireNonNull(structureState, "structureState");
+            Objects.requireNonNull(templates, "templates");
+            Objects.requireNonNull(levelKey, "levelKey");
+            Objects.requireNonNull(worldOptions, "worldOptions");
+            if (worldOptions.seed() != structureState.getLevelSeed()) {
+                throw new IllegalArgumentException("Structure state seed differs from world options");
+            }
+        }
+
+        boolean enabled() {
+            return worldOptions.generateStructures() && adapterEnabled;
+        }
+    }
+
+    record Policies<P extends StructureStartPlan, O extends StructureOwnershipRecordView<O>>(
+            StructureInjectionPolicy<P> injection, StructureReferencePolicy<P, O> references,
+            Predicate<BoundingBox> allowsFootprint) {
+        Policies {
+            Objects.requireNonNull(injection, "injection");
+            Objects.requireNonNull(references, "references");
+            Objects.requireNonNull(allowsFootprint, "allowsFootprint");
+        }
+    }
+
+    record PlannedChunk<O extends StructureOwnershipRecordView<O>>(NativeContext context, ProtoChunk chunk,
+            Map<Structure, O> ownership, Map<Structure, StructureTerrainSettings> terrain) {
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/HeadlessTerrainContext.java

@@ -0,0 +1,159 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.platform.bukkit.nms.BukkitBiomePolicy;
+import art.arcane.iris.structure.nativegen.IrisStructurePolicy;
+import art.arcane.iris.structure.nativegen.IrisStructureVolumePolicy;
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.nativegen.NativeStructureVolumeIndex;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeBiomeRegistryImpl;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVolumeSource;
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.util.datafix.DataFixers;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.WorldOptions;
+import net.minecraft.world.level.levelgen.structure.pieces.StructurePieceSerializationContext;
+import net.minecraft.world.level.levelgen.structure.StructureSet;
+import net.minecraft.world.level.levelgen.structure.placement.ConcentricRingsStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import net.minecraft.world.level.storage.LevelStorageSource;
+import org.spigotmc.SpigotWorldConfig;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.Objects;
+
+final class HeadlessTerrainContext implements AutoCloseable {
+    private final Engine engine;
+    private final LevelStorageSource.LevelStorageAccess storage;
+    private final HeadlessStructurePlanner.NativeContext structures;
+    private final HeadlessStructurePlanner.Policies<NativeStructureStartPlan, NativeStructureOwnershipRecord> policies;
+    private final BukkitBiomePolicy<Holder<Biome>, Biome> biomes;
+    private final HeadlessChunkSerialization.Context serialization;
+    private final NativeRegionTerrainWriter writer;
+
+    private HeadlessTerrainContext(Options options, LevelStorageSource.LevelStorageAccess storage) {
+        engine = options.engine();
+        this.storage = storage;
+        HeadlessNativeRuntime runtime = options.runtime();
+        writer = runtime.writer();
+        HeadlessChunkGenerator generator = new HeadlessChunkGenerator(new HeadlessChunkGenerator.Options(
+                engine, runtime.registries()));
+        long seed = engine.getSeedManager().getSeed();
+        NoiseGeneratorSettings settings = runtime.registries().lookupOrThrow(Registries.NOISE_SETTINGS)
+                .getOrThrow(options.noiseSettings()).value();
+        RandomState random = RandomState.create(runtime.registries().lookupOrThrow(Registries.NOISE), seed, settings);
+        ChunkGeneratorStructureState state = generator.createState(
+                runtime.registries().lookupOrThrow(Registries.STRUCTURE_SET), random, seed, options.configuration());
+        initializeStructureState(state);
+        StructureTemplateManager templates = new StructureTemplateManager(runtime.resources(), storage,
+                DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+        structures = new HeadlessStructurePlanner.NativeContext(runtime.registries(), generator, state,
+                templates, options.levelKey(), new WorldOptions(seed, true, false), true);
+        IrisStructurePolicy policy = new IrisStructurePolicy(engine);
+        policies = new HeadlessStructurePlanner.Policies<>(policy, policy,
+                bounds -> engine.getComplex().allowsNewGenerationFootprint(
+                        bounds.minX(), bounds.minZ(), bounds.maxX(), bounds.maxZ()));
+        NativeBiomeRegistryImpl registry = new NativeBiomeRegistryImpl(runtime.registries().lookupOrThrow(Registries.BIOME));
+        biomes = new BukkitBiomePolicy<>(new BukkitBiomePolicy.RuntimeOptions<>(seed, engine, null, () -> registry), registry);
+        serialization = new HeadlessChunkSerialization.Context(new StructurePieceSerializationContext(
+                runtime.resources(), runtime.registries(), templates), PalettedContainerFactory.create(runtime.registries()), 0L);
+        NativeStructureVolumeSource<Engine, NativeStructureStartPlan> volumes = new NativeStructureVolumeSource<>(
+                new NativeStructureVolumeSource.Context(runtime.registries(), templates, options.levelKey(),
+                        LevelHeightAccessor.create(engine.getMinHeight(), engine.getHeight()),
+                        () -> generator, generator::getBiomeSource, () -> state), IrisStructureVolumePolicy.INSTANCE);
+        NativeStructureVolumeIndex.install(engine, volumes::volumesAt);
+    }
+
+    static HeadlessTerrainContext create(Options options) throws IOException {
+        LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(options.templateStorage())
+                .createAccess("native-templates");
+        try {
+            return new HeadlessTerrainContext(options, storage);
+        } catch (RuntimeException | Error failure) {
+            try {
+                storage.close();
+            } catch (IOException closeFailure) {
+                failure.addSuppressed(closeFailure);
+            }
+            throw failure;
+        }
+    }
+
+    private static void initializeStructureState(ChunkGeneratorStructureState state) {
+        state.ensureStructuresGenerated();
+        Throwable failure = null;
+        for (Holder<StructureSet> structureSet : state.possibleStructureSets()) {
+            if (!(structureSet.value().placement() instanceof ConcentricRingsStructurePlacement rings)) {
+                continue;
+            }
+            try {
+                state.getRingPositionsFor(rings);
+            } catch (RuntimeException | Error problem) {
+                if (failure == null) {
+                    failure = problem;
+                } else {
+                    failure.addSuppressed(problem);
+                }
+            }
+        }
+        if (failure instanceof RuntimeException exception) {
+            throw exception;
+        }
+        if (failure instanceof Error error) {
+            throw error;
+        }
+    }
+
+    @Override
+    public void close() throws IOException {
+        NativeStructureVolumeIndex.uninstall(engine);
+        storage.close();
+    }
+
+    Engine engine() {
+        return engine;
+    }
+
+    HeadlessStructurePlanner.NativeContext structures() {
+        return structures;
+    }
+
+    HeadlessStructurePlanner.Policies<NativeStructureStartPlan, NativeStructureOwnershipRecord> policies() {
+        return policies;
+    }
+
+    BukkitBiomePolicy<Holder<Biome>, Biome> biomes() {
+        return biomes;
+    }
+
+    HeadlessChunkSerialization.Context serialization() {
+        return serialization;
+    }
+
+    NativeRegionTerrainWriter writer() {
+        return writer;
+    }
+
+    record Options(Engine engine, HeadlessNativeRuntime runtime, Path templateStorage, ResourceKey<Level> levelKey,
+                   ResourceKey<NoiseGeneratorSettings> noiseSettings, SpigotWorldConfig configuration) {
+        Options {
+            Objects.requireNonNull(engine, "engine");
+            Objects.requireNonNull(runtime, "runtime");
+            Objects.requireNonNull(templateStorage, "templateStorage");
+            Objects.requireNonNull(levelKey, "levelKey");
+            Objects.requireNonNull(noiseSettings, "noiseSettings");
+            Objects.requireNonNull(configuration, "configuration");
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/NativeRegionPlan.java

@@ -0,0 +1,56 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.chunk.status.ChunkPyramid;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.status.ChunkStep;
+
+import java.util.ArrayList;
+import java.util.List;
+
+final class NativeRegionPlan {
+    private NativeRegionPlan() {
+    }
+
+    static List<PlannedChunk> plan(int chunkX, int chunkZ, int width) {
+        if (width < 1 || width > 32) {
+            throw new IllegalArgumentException("Native terrain tile width must be 1..32 chunks");
+        }
+        ChunkStep target = ChunkPyramid.GENERATION_PYRAMID.getStepTo(ChunkStatus.FULL);
+        int halo = target.accumulatedDependencies().size() - 1;
+        int maximumX = Math.addExact(chunkX, width - 1);
+        int maximumZ = Math.addExact(chunkZ, width - 1);
+        if (!new ChunkPos(Math.subtractExact(chunkX, halo), Math.subtractExact(chunkZ, halo)).isValid()
+                || !new ChunkPos(Math.addExact(maximumX, halo), Math.addExact(maximumZ, halo)).isValid()) {
+            throw new IllegalArgumentException("Native terrain tile exceeds supported chunk bounds");
+        }
+        List<PlannedChunk> result = new ArrayList<>((width + halo * 2) * (width + halo * 2));
+        for (int z = Math.subtractExact(chunkZ, halo); z <= Math.addExact(maximumZ, halo); z++) {
+            for (int x = Math.subtractExact(chunkX, halo); x <= Math.addExact(maximumX, halo); x++) {
+                int distance = Math.max(distance(x, chunkX, maximumX), distance(z, chunkZ, maximumZ));
+                ChunkStatus required = distance == 0 ? ChunkStatus.FULL : target.accumulatedDependencies().get(distance);
+                ChunkStatus status = required.isAfter(ChunkStatus.TERRAIN) ? ChunkStatus.TERRAIN : required;
+                result.add(new PlannedChunk(x, z, status, distance == 0));
+            }
+        }
+        return List.copyOf(result);
+    }
+
+    static int terrainHalo() {
+        ChunkStep target = ChunkPyramid.GENERATION_PYRAMID.getStepTo(ChunkStatus.FULL);
+        int radius = 0;
+        for (int distance = 1; distance < target.accumulatedDependencies().size(); distance++) {
+            if (target.accumulatedDependencies().get(distance).isOrAfter(ChunkStatus.TERRAIN)) {
+                radius = distance;
+            }
+        }
+        return radius;
+    }
+
+    private static int distance(int value, int minimum, int maximum) {
+        return Math.max(0, Math.max(minimum - value, value - maximum));
+    }
+
+    record PlannedChunk(int x, int z, ChunkStatus status, boolean target) {
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/NativeRegionTerrainWriter.java

@@ -0,0 +1,223 @@
+package art.arcane.iris.probe;
+
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import it.unimi.dsi.fastutil.shorts.ShortList;
+import net.minecraft.commands.arguments.blocks.BlockStateParser;
+import net.minecraft.core.Holder;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.NbtIo;
+import net.minecraft.nbt.NbtOps;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.block.EntityBlock;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.util.ProblemReporter;
+import net.minecraft.world.level.storage.TagValueInput;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.storage.RegionFile;
+import net.minecraft.world.level.chunk.storage.SerializableChunkData;
+
+import java.io.DataOutputStream;
+import java.io.IOException;
+import java.util.ArrayList;
+import it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+
+final class NativeRegionTerrainWriter {
+    private final Registry<Biome> biomes;
+    private final RegistryAccess registries;
+    private final PalettedContainerFactory containers;
+    private final Map<String, BlockState> tileStates = new ConcurrentHashMap<>();
+    private final Map<String, Holder<Biome>> biomeHolders = new ConcurrentHashMap<>();
+
+    NativeRegionTerrainWriter(RegistryAccess registries) {
+        this.registries = Objects.requireNonNull(registries, "registries");
+        biomes = registries.lookupOrThrow(Registries.BIOME);
+        containers = PalettedContainerFactory.create(registries);
+    }
+
+    RegistryAccess registries() {
+        return registries;
+    }
+
+    CompoundTag encode(TerrainInput input) {
+        TerrainData terrain = terrain(input, null);
+        SerializableChunkData data = new SerializableChunkData(containers,
+                new ChunkPos(input.chunkX(), input.chunkZ()), input.minimumY() >> 4, 0L, 0L,
+                ChunkStatus.EMPTY, null, null, UpgradeData.EMPTY, Map.of(),
+                new ChunkAccess.PackedTicks(List.of(), List.of()), new ShortList[input.height() >> 4], false,
+                terrain.sections(), List.of(), terrain.blockEntities(), new CompoundTag(), null);
+        CompoundTag tag = data.write();
+        tag.putString("iris:checkpoint", "iris:terrain_checkpoint");
+        return tag;
+    }
+
+
+    void fill(ProtoChunk chunk, TerrainInput input) {
+        if (chunk.getPos().x() != input.chunkX() || chunk.getPos().z() != input.chunkZ()
+                || chunk.getMinY() != input.minimumY() || chunk.getHeight() != input.height()) {
+            throw new IllegalArgumentException("Generated terrain does not match its planned chunk");
+        }
+        TerrainData terrain = terrain(input, chunk.getSections());
+        for (int i = 0; i < terrain.sections().size(); i++) {
+            chunk.getSections()[i] = terrain.sections().get(i).chunkSection();
+        }
+        for (CompoundTag entity : terrain.blockEntities()) {
+            chunk.setBlockEntityNbt(entity);
+        }
+        chunk.markUnsaved();
+    }
+
+    private TerrainData terrain(TerrainInput input, LevelChunkSection[] existingBiomes) {
+        Int2ObjectOpenHashMap<TileInput> tiles = new Int2ObjectOpenHashMap<>(input.tiles().size());
+        for (TileInput tile : input.tiles()) {
+            if (tile.y() >= input.height() || tiles.put(tile.x() | tile.z() << 4 | tile.y() << 8, tile) != null) {
+                throw new IllegalArgumentException("Duplicate or out-of-bounds tile data");
+            }
+        }
+        List<CompoundTag> blockEntities = new ArrayList<>();
+        List<SerializableChunkData.SectionData> sections = new ArrayList<>(input.height() >> 4);
+        for (int sectionY = 0; sectionY < input.height(); sectionY += 16) {
+            PalettedContainer<BlockState> blocks = containers.createForBlockStates();
+            PalettedContainer<Holder<Biome>> sectionBiomes = existingBiomes == null
+                    ? containers.createForBiomes() : existingBiomes[sectionY >> 4].getBiomes().copy();
+            for (int y = 0; y < 16; y++) {
+                for (int z = 0; z < 16; z++) {
+                    for (int x = 0; x < 16; x++) {
+                        BlockState state = Objects.requireNonNull(input.blocks().state(x, sectionY + y, z), "block state");
+                        TileInput tile = tiles.isEmpty() ? null : tiles.get(x | z << 4 | (sectionY + y) << 8);
+                        if (tile == null && state == Blocks.AIR.defaultBlockState()) {
+                            continue;
+                        }
+                        if (tile != null) {
+                            state = tileStates.computeIfAbsent(tile.stateKey(), NativeRegionTerrainWriter::resolveState);
+                        }
+                        blocks.set(x, y, z, state);
+                        if (state.hasBlockEntity()) {
+                            BlockPos position = new BlockPos((input.chunkX() << 4) + x,
+                                    input.minimumY() + sectionY + y, (input.chunkZ() << 4) + z);
+                            CompoundTag entity = encodeBlockEntity(state, position, tile);
+                            if (entity != null) {
+                                blockEntities.add(entity);
+                            }
+                        } else if (tile != null) {
+                            throw new IllegalArgumentException("Tile data has no native block entity at " + x + "," + y + "," + z);
+                        }
+                    }
+                }
+            }
+            if (existingBiomes == null) {
+                for (int y = 0; y < 4; y++) {
+                    for (int z = 0; z < 4; z++) {
+                        for (int x = 0; x < 4; x++) {
+                            String key = Objects.requireNonNull(input.biomes().key(x << 2, sectionY + (y << 2), z << 2), "biome key");
+                            sectionBiomes.set(x, y, z, biomeHolders.computeIfAbsent(key, this::resolveBiome));
+                        }
+                    }
+                }
+            }
+            sections.add(new SerializableChunkData.SectionData((input.minimumY() + sectionY) >> 4,
+                    new LevelChunkSection(blocks, sectionBiomes), null, null));
+        }
+        return new TerrainData(sections, blockEntities);
+    }
+
+    private CompoundTag encodeBlockEntity(BlockState state, BlockPos position, TileInput tile) {
+        BlockEntity entity = ((EntityBlock) state.getBlock()).newBlockEntity(position, state);
+        if (entity == null) {
+            if (tile != null) {
+                throw new IllegalStateException("Native block did not create a tile entity at " + position);
+            }
+            return null;
+        }
+        if (tile != null) {
+            CompoundTag merged = entity.saveWithoutMetadata(registries);
+            merged.merge(tile.payload());
+            entity.loadWithComponents(TagValueInput.create(ProblemReporter.DISCARDING, registries, merged));
+        }
+        return entity.saveWithFullMetadata(registries);
+    }
+
+    BlockState readBlock(CompoundTag tag, int x, int y, int z) {
+        for (CompoundTag section : tag.getListOrEmpty("sections").compoundStream().toList()) {
+            if (section.getByteOr("Y", (byte) 0) == y >> 4) {
+                return containers.blockStatesContainerCodec().parse(NbtOps.INSTANCE,
+                        section.getCompoundOrEmpty("block_states")).getOrThrow().get(x & 15, y & 15, z & 15);
+            }
+        }
+        throw new IllegalArgumentException("Missing section at " + y);
+    }
+
+    static void write(RegionFile region, CompoundTag tag) throws IOException {
+        ChunkPos position = new ChunkPos(tag.getIntOr("xPos", 0), tag.getIntOr("zPos", 0));
+        try (DataOutputStream output = region.getChunkDataOutputStream(position)) {
+            NbtIo.write(tag, output);
+        }
+    }
+
+    private static BlockState resolveState(String key) {
+        try {
+            return BlockStateParser.parseForBlock(BuiltInRegistries.BLOCK, key, false).blockState();
+        } catch (CommandSyntaxException failure) {
+            throw new IllegalArgumentException("Unsupported native block state: " + key, failure);
+        }
+    }
+
+    private Holder<Biome> resolveBiome(String key) {
+        return biomes.get(ResourceKey.create(Registries.BIOME, Identifier.parse(key)))
+                .orElseThrow(() -> new IllegalArgumentException("Unsupported native biome: " + key));
+    }
+
+    record TerrainInput(int chunkX, int chunkZ, int minimumY, int height, BlockLookup blocks, KeyLookup biomes, List<TileInput> tiles) {
+        TerrainInput {
+            if ((minimumY & 15) != 0 || (height & 15) != 0 || height < 16
+                    || minimumY < -2032 || (long) minimumY + height > 2032) {
+                throw new IllegalArgumentException("Terrain bounds must be section aligned within the native height range");
+            }
+            Objects.requireNonNull(blocks, "blocks");
+            Objects.requireNonNull(biomes, "biomes");
+            tiles = List.copyOf(tiles);
+        }
+    }
+
+    record TileInput(int x, int y, int z, String stateKey, CompoundTag payload) {
+        TileInput {
+            if (x < 0 || x > 15 || z < 0 || z > 15 || y < 0) {
+                throw new IllegalArgumentException("Tile position is outside its chunk");
+            }
+            Objects.requireNonNull(stateKey, "stateKey");
+            payload = Objects.requireNonNull(payload, "payload").copy();
+        }
+    }
+
+    private record TerrainData(List<SerializableChunkData.SectionData> sections, List<CompoundTag> blockEntities) {
+    }
+
+    @FunctionalInterface
+    interface BlockLookup {
+        BlockState state(int x, int y, int z);
+    }
+
+    @FunctionalInterface
+    interface KeyLookup {
+        String key(int x, int y, int z);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/OfflineRegionGenerator.java

@@ -0,0 +1,264 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.configuration.IrisSettings;
+import art.arcane.iris.generation.concurrent.MultiBurst;
+import art.arcane.iris.generation.hydrology.HydrologyTileCache;
+import art.arcane.iris.generation.hydrology.runtime.IrisHydrologyRuntime;
+import art.arcane.iris.world.pregen.PregenPerformanceProfile;
+
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import org.spigotmc.SpigotWorldConfig;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Bukkit;
+import org.bukkit.persistence.PersistentDataType;
+
+import java.io.File;
+import java.io.IOException;
+import java.io.PrintStream;
+import java.nio.channels.FileChannel;
+import java.nio.channels.FileLock;
+import java.nio.file.Files;
+import java.nio.file.FileVisitResult;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.StandardOpenOption;
+import java.security.MessageDigest;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Locale;
+
+public final class OfflineRegionGenerator {
+    private OfflineRegionGenerator() {
+    }
+
+    public static void main(String[] arguments) {
+        PrintStream diagnostics = System.err;
+        try {
+            execute(arguments);
+        } catch (Throwable failure) {
+            failure.printStackTrace(diagnostics);
+            diagnostics.flush();
+            System.exit(1);
+        }
+    }
+
+    private static void execute(String[] arguments) throws Exception {
+        if (arguments.length == 1 && arguments[0].equals("--help")) {
+            System.out.println("Usage: iris-offline pack dimension seed chunkX chunkZ width regionsX regionsZ parallelism spigot worldName levelKey noiseSettings output");
+            System.out.println("Java 25; width 1..32 chunks; parallelism 1..32. Output must be a new absolute directory.");
+            System.out.println("Generates fresh TERRAIN checkpoints and immutable Iris history. Native server completion is required for features, population and lighting.");
+            return;
+        }
+        if (Bukkit.getServer() != null) {
+            throw new IllegalStateException("Offline generation requires a separate process without a running Bukkit server");
+        }
+        long processStarted = System.nanoTime();
+        HeadlessNativeBootstrap.initialize();
+        Configuration configuration = Configuration.parse(arguments);
+        Files.createDirectory(configuration.output());
+        force(configuration.output());
+        try (FileChannel channel = FileChannel.open(configuration.output().resolve("checkpoint.lock"),
+                StandardOpenOption.CREATE_NEW, StandardOpenOption.WRITE);
+             FileLock lock = channel.lock()) {
+            if (!lock.isValid()) {
+                throw new IllegalStateException("Headless checkpoint lock is invalid");
+            }
+            run(configuration);
+            System.out.println("processSeconds=" + (System.nanoTime() - processStarted) / 1_000_000_000.0);
+        }
+    }
+
+    private static void run(Configuration configuration) throws Exception {
+        Path staged = Files.createDirectory(configuration.output().resolve("incomplete"));
+        byte[] configurationBytes = Files.readAllBytes(configuration.spigot());
+        Path capturedConfiguration = staged.resolve("spigot.yml");
+        Files.write(capturedConfiguration, configurationBytes, StandardOpenOption.CREATE_NEW);
+        String configurationHash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(configurationBytes));
+        HeadlessNativeRuntime runtime = new HeadlessNativeRuntime(staged);
+        long started = System.nanoTime();
+        long writes = 0;
+        long terrainWrites = 0;
+        double generationSeconds = 0;
+        double serializationSeconds = 0;
+        try (RealPackProbeSupport.Workspace workspace = RealPackProbeSupport.openWorkspace(new RealPackProbeSupport.WorkspaceOptions(configuration.pack(),
+                configuration.dimension(), "[headless-native-region]", runtime, staged));
+             RealPackProbeSupport.EngineSession session = workspace.openEngine(configuration.seed(), false, "native-region")) {
+            session.retainWorld(staged.resolve("world"));
+            SpigotWorldConfig spigot = HeadlessStructureConfiguration.load(new HeadlessStructureConfiguration.Options(
+                    capturedConfiguration, configuration.worldName(), configuration.levelKey(), staged.resolve("configuration")));
+            PregenPerformanceProfile.apply(session.engine());
+            System.out.println("generationProfile=pregen noiseCacheSize=" + IrisSettings.get().getPerformance().getNoiseCacheSize()
+                    + " burstParallelism=" + MultiBurst.burst.parallelism() + " multicore=true");
+            IrisHydrologyRuntime hydrology = session.engine().getComplex().getHydrologyRuntime();
+            try (HydrologyTileCache.PregenerationScope hydrologyScope = hydrology == null ? null
+                    : hydrology.preparePregeneration(configuration.hydrologyArea());
+                 HeadlessTerrainContext context = HeadlessTerrainContext.create(new HeadlessTerrainContext.Options(
+                    session.engine(), runtime, staged.resolve("templates"), configuration.levelKey(),
+                    configuration.noiseSettings(), spigot));
+                 RegionGenerationWindow workers = new RegionGenerationWindow(configuration.parallelism(),
+                         RegionGenerationWindow.Policy.STANDALONE)) {
+                HeadlessRegionTerrain.Session rolling = new HeadlessRegionTerrain.Session(workers);
+                Path regionDirectory = session.engine().getTarget().getWorld().worldFolder().toPath().resolve("region");
+                Files.createDirectory(regionDirectory);
+                OfflineRegionWriter writer = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                        context, regionDirectory, workers));
+                for (int row = 0; row < configuration.regionsZ(); row++) {
+                    for (int column = 0; column < configuration.regionsX(); column++) {
+                        int regionX = row % 2 == 0 ? column : configuration.regionsX() - column - 1;
+                        int chunkX = Math.addExact(configuration.chunkX(), Math.multiplyExact(regionX, configuration.width()));
+                        int chunkZ = Math.addExact(configuration.chunkZ(), Math.multiplyExact(row, configuration.width()));
+                        RegionResult generated = generateRegion(new RegionRequest(context, rolling, writer, chunkX, chunkZ,
+                                configuration.width(), configuration.parallelism(),
+                                staged.resolve("receipts.properties")));
+                        writes += generated.written().chunks();
+                        terrainWrites += generated.written().terrainChunks();
+                        generationSeconds += generated.generationSeconds();
+                        serializationSeconds += generated.serializationSeconds();
+                        System.out.println("region=" + regionX + "," + row + " residentChunks=" + generated.residentChunks()
+                                + " upgradedChunks=" + generated.upgradedChunks() + " writtenChunks=" + generated.written().chunks());
+                    }
+                }
+            } finally {
+                PregenPerformanceProfile.restore();
+            }
+        }
+        double wallSeconds = (System.nanoTime() - started) / 1_000_000_000.0;
+        String report = String.format(Locale.ROOT,
+                "format=iris-native-terrain-checkpoint\nplatform=headless-native\nstatus=minecraft:terrain\ncomplete=false\n"
+                        + "targetChunks=%d\nchunkWrites=%d\nterrainWrites=%d\nparallelism=%d\nseed=%d\nchunkX=%d\nchunkZ=%d\nwidth=%d\nregionsX=%d\nregionsZ=%d\n"
+                        + "levelKey=%s\nworldName=%s\nnoiseSettings=%s\nspigotSha256=%s\npipelineWallSeconds=%.3f\ngenerationSeconds=%.3f\nserializationSeconds=%.3f\n"
+                        + "limitations=Fresh offline world checkpoint only. Native features, population, lighting, POI, entities and scheduled ticks require native completion. No live plugin events are dispatched. Authored tile payloads remain in retained mantle for native completion. No transitions or existing chunks are imported.\n",
+                Math.multiplyExact(Math.multiplyExact(configuration.width(), configuration.width()),
+                        Math.multiplyExact(configuration.regionsX(), configuration.regionsZ())), writes, terrainWrites,
+                configuration.parallelism(), configuration.seed(), configuration.chunkX(), configuration.chunkZ(),
+                configuration.width(), configuration.regionsX(), configuration.regionsZ(), configuration.levelKey().identifier(),
+                configuration.worldName(), configuration.noiseSettings().identifier(), configurationHash,
+                wallSeconds, generationSeconds, serializationSeconds);
+        Files.writeString(staged.resolve("checkpoint.properties"), report, StandardOpenOption.CREATE_NEW);
+        long publicationStarted = System.nanoTime();
+        publish(staged, configuration.output().resolve("native-terrain-checkpoint"));
+        System.out.println(report);
+        System.out.println("publicationSeconds=" + (System.nanoTime() - publicationStarted) / 1_000_000_000.0);
+        System.out.println("totalSeconds=" + (System.nanoTime() - started) / 1_000_000_000.0);
+    }
+
+    private static RegionResult generateRegion(RegionRequest request) throws Exception {
+        long generationStarted = System.nanoTime();
+        HeadlessRegionTerrain.Result generated = request.rolling().generate(new HeadlessRegionTerrain.Request(
+                request.context(), request.chunkX(), request.chunkZ(), request.width(), request.parallelism()), System.out::println);
+        double generationSeconds = (System.nanoTime() - generationStarted) / 1_000_000_000.0;
+        long serializationStarted = System.nanoTime();
+        OfflineRegionWriter.Result written = request.writer().write(generated);
+        writeReceipts(generated, request.receipts());
+        return new RegionResult(written, generated.chunks().size(), generated.updated().size(), generationSeconds,
+                (System.nanoTime() - serializationStarted) / 1_000_000_000.0);
+    }
+
+    private record RegionRequest(HeadlessTerrainContext context, HeadlessRegionTerrain.Session rolling, OfflineRegionWriter writer,
+                                 int chunkX, int chunkZ, int width, int parallelism, Path receipts) {
+    }
+
+    private record RegionResult(OfflineRegionWriter.Result written, int residentChunks, int upgradedChunks,
+                                double generationSeconds, double serializationSeconds) {
+    }
+
+    private static void writeReceipts(HeadlessRegionTerrain.Result generated, Path path) throws Exception {
+        NamespacedKey key = new NamespacedKey("iris", "natural_terrain");
+        MessageDigest digest = MessageDigest.getInstance("SHA-256");
+        StringBuilder receipts = new StringBuilder();
+        for (ProtoChunk chunk : generated.updated()) {
+            if (!chunk.getPersistedStatus().isOrAfter(ChunkStatus.TERRAIN)) {
+                continue;
+            }
+            byte[] receipt = chunk.persistentDataContainer.get(key, PersistentDataType.BYTE_ARRAY);
+            if (receipt == null) {
+                throw new IllegalStateException("Native TERRAIN checkpoint has no receipt at " + chunk.getPos());
+            }
+            receipts.append(chunk.getPos().x()).append(',').append(chunk.getPos().z()).append('=')
+                    .append(HexFormat.of().formatHex(digest.digest(receipt))).append('\n');
+        }
+        Files.writeString(path, receipts, StandardOpenOption.CREATE, StandardOpenOption.APPEND);
+    }
+
+    private static void forceTree(Path directory) throws IOException {
+        Files.walkFileTree(directory, new SimpleFileVisitor<>() {
+            @Override
+            public FileVisitResult visitFile(Path file, BasicFileAttributes attributes) throws IOException {
+                force(file);
+                return FileVisitResult.CONTINUE;
+            }
+
+            @Override
+            public FileVisitResult postVisitDirectory(Path path, IOException failure) throws IOException {
+                if (failure != null) {
+                    throw failure;
+                }
+                force(path);
+                return FileVisitResult.CONTINUE;
+            }
+        });
+    }
+
+    static void publish(Path staged, Path destination) throws IOException {
+        forceTree(staged);
+        Files.move(staged, destination, StandardCopyOption.ATOMIC_MOVE);
+        force(destination.getParent());
+    }
+
+    private static void force(Path path) throws IOException {
+        try (FileChannel channel = FileChannel.open(path, Files.isDirectory(path)
+                ? StandardOpenOption.READ : StandardOpenOption.WRITE)) {
+            channel.force(true);
+        }
+    }
+
+    record Configuration(File pack, String dimension, long seed, int chunkX, int chunkZ, int width,
+                         int regionsX, int regionsZ, int parallelism, Path spigot, String worldName, ResourceKey<Level> levelKey,
+                         ResourceKey<NoiseGeneratorSettings> noiseSettings, Path output) {
+        Configuration {
+            if (regionsX < 1 || regionsZ < 1) {
+                throw new IllegalArgumentException("Region dimensions must be positive");
+            }
+            Math.multiplyExact(Math.multiplyExact(width, width), Math.multiplyExact(regionsX, regionsZ));
+            NativeRegionPlan.plan(chunkX, chunkZ, width);
+            NativeRegionPlan.plan(Math.addExact(chunkX, Math.multiplyExact(regionsX - 1, width)),
+                    Math.addExact(chunkZ, Math.multiplyExact(regionsZ - 1, width)), width);
+            if (parallelism < 1 || parallelism > 32 || !Files.isRegularFile(spigot)) {
+                throw new IllegalArgumentException("Parallelism must be 1..32 and Spigot configuration must exist");
+            }
+            if (!output.isAbsolute() || Files.exists(output) || !Files.isDirectory(output.getParent())) {
+                throw new IllegalArgumentException("Output must be a new absolute directory under an existing parent");
+            }
+        }
+
+        HydrologyTileCache.PregenerationArea hydrologyArea() {
+            int halo = NativeRegionPlan.terrainHalo();
+            long minimumX = ((long) chunkX - halo) * 16L;
+            long minimumZ = ((long) chunkZ - halo) * 16L;
+            long maximumX = ((long) chunkX + (long) width * regionsX + halo) * 16L - 1L;
+            long maximumZ = ((long) chunkZ + (long) width * regionsZ + halo) * 16L - 1L;
+            return new HydrologyTileCache.PregenerationArea(Math.toIntExact((minimumX + maximumX) / 2L),
+                    Math.toIntExact((minimumZ + maximumZ) / 2L), minimumX, minimumZ, maximumX, maximumZ);
+        }
+
+        static Configuration parse(String[] arguments) throws IOException {
+            if (arguments.length != 14) {
+                throw new IllegalArgumentException("Expected pack dimension seed chunkX chunkZ width regionsX regionsZ parallelism spigot worldName levelKey noiseSettings output");
+            }
+            return new Configuration(new File(arguments[0]).getCanonicalFile(), arguments[1], Long.parseLong(arguments[2]),
+                    Integer.parseInt(arguments[3]), Integer.parseInt(arguments[4]), Integer.parseInt(arguments[5]),
+                    Integer.parseInt(arguments[6]), Integer.parseInt(arguments[7]), Integer.parseInt(arguments[8]),
+                    Path.of(arguments[9]), arguments[10],
+                    ResourceKey.create(Registries.DIMENSION, Identifier.parse(arguments[11])),
+                    ResourceKey.create(Registries.NOISE_SETTINGS, Identifier.parse(arguments[12])), Path.of(arguments[13]));
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/OfflineRegionWriter.java

@@ -0,0 +1,161 @@
+package art.arcane.iris.probe;
+
+import ca.spottedleaf.moonrise.patches.chunk_system.io.MoonriseRegionFileIO.RegionDataController.IORunnable;
+import ca.spottedleaf.moonrise.patches.chunk_system.io.MoonriseRegionFileIO.RegionDataController.WriteData;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.NbtIo;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.storage.RegionFile;
+import net.minecraft.world.level.chunk.storage.RegionStorageInfo;
+
+import java.io.DataInputStream;
+import java.io.DataOutputStream;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+final class OfflineRegionWriter {
+    private static final int MAXIMUM_PREPARATION_WORKERS = 8;
+    private static final int MAXIMUM_STATUS_REGIONS = 64;
+
+    private final Options options;
+    private final Map<Long, int[]> published = new LinkedHashMap<>(MAXIMUM_STATUS_REGIONS, 0.75F, true) {
+        @Override
+        protected boolean removeEldestEntry(Map.Entry<Long, int[]> eldest) {
+            return size() > MAXIMUM_STATUS_REGIONS;
+        }
+    };
+
+    OfflineRegionWriter(Options options) {
+        this.options = Objects.requireNonNull(options, "options");
+    }
+
+    Result write(HeadlessRegionTerrain.Result generated) throws Exception {
+        options.workers().requireOpen();
+        try (OpenRegions regions = new OpenRegions(options)) {
+            List<ChunkWrite> pending = new ArrayList<>(generated.updated().size());
+            for (ProtoChunk chunk : generated.updated()) {
+                ChunkPos position = chunk.getPos();
+                long regionKey = ChunkPos.pack(position.x() >> 5, position.z() >> 5);
+                int[] statuses = published.computeIfAbsent(regionKey, ignored -> new int[1024]);
+                int index = (position.x() & 31) + ((position.z() & 31) << 5);
+                int status = chunk.getPersistedStatus().getIndex() + 2;
+                if (statuses[index] >= status) {
+                    continue;
+                }
+                RegionFile region = regions.get(position);
+                if (statuses[index] == 0) {
+                    statuses[index] = readStatus(region, position);
+                    if (statuses[index] >= status) {
+                        continue;
+                    }
+                }
+                pending.add(new ChunkWrite(chunk, region, statuses, index, status));
+            }
+            if (pending.isEmpty()) {
+                return new Result(0, 0);
+            }
+            int[] counts = new int[2];
+            options.workers().process(new RegionGenerationWindow.Request<>(pending.size(),
+                    Math.min(options.workers().parallelism(), MAXIMUM_PREPARATION_WORKERS),
+                    index -> prepare(pending.get(index)),
+                    (index, prepared) -> {
+                        ChunkWrite chunk = prepared.chunk();
+                        prepared.commit().run(chunk.region());
+                        chunk.statuses()[chunk.index()] = chunk.status();
+                        counts[0]++;
+                        if (chunk.chunk().getPersistedStatus().isOrAfter(ChunkStatus.TERRAIN)) {
+                            counts[1]++;
+                        }
+                    }));
+            return new Result(counts[0], counts[1]);
+        }
+    }
+
+    private PreparedWrite prepare(ChunkWrite chunk) throws IOException {
+        CompoundTag tag = HeadlessChunkSerialization.copyOf(chunk.chunk(), options.context().serialization()).write();
+        WriteData prepared = chunk.region().moonrise$startWrite(tag, chunk.chunk().getPos());
+        try (DataOutputStream output = prepared.output()) {
+            NbtIo.write(tag, output);
+        }
+        return new PreparedWrite(chunk, prepared.write());
+    }
+
+    private static int readStatus(RegionFile region, ChunkPos position) throws IOException {
+        try (DataInputStream input = region.getChunkDataInputStream(position)) {
+            if (input == null) {
+                return 1;
+            }
+            ChunkStatus status = ChunkStatus.byName(NbtIo.read(input).getStringOr("Status", ""));
+            if (status == null) {
+                throw new IOException("Invalid native chunk status at " + position);
+            }
+            return status.getIndex() + 2;
+        }
+    }
+
+    record Options(HeadlessTerrainContext context, Path directory, RegionGenerationWindow workers) {
+        Options {
+            Objects.requireNonNull(context, "context");
+            Objects.requireNonNull(directory, "directory");
+            Objects.requireNonNull(workers, "workers");
+        }
+    }
+
+    record Result(int chunks, int terrainChunks) {
+    }
+
+    private record ChunkWrite(ProtoChunk chunk, RegionFile region, int[] statuses, int index, int status) {
+    }
+
+    private record PreparedWrite(ChunkWrite chunk, IORunnable commit) {
+    }
+
+    private static final class OpenRegions implements AutoCloseable {
+        private final Options options;
+        private final Map<Long, RegionFile> regions = new HashMap<>();
+
+        private OpenRegions(Options options) {
+            this.options = options;
+        }
+
+        private RegionFile get(ChunkPos position) throws IOException {
+            long key = ChunkPos.pack(position.x() >> 5, position.z() >> 5);
+            RegionFile region = regions.get(key);
+            if (region != null) {
+                return region;
+            }
+            Path path = options.directory().resolve("r." + (position.x() >> 5) + "." + (position.z() >> 5) + ".mca");
+            region = new RegionFile(new RegionStorageInfo("headless-native-terrain",
+                    options.context().structures().levelKey(), "chunk"), path, options.directory(), false);
+            regions.put(key, region);
+            return region;
+        }
+
+        @Override
+        public void close() throws IOException {
+            IOException failure = null;
+            for (RegionFile region : regions.values()) {
+                try {
+                    region.close();
+                } catch (IOException exception) {
+                    if (failure == null) {
+                        failure = exception;
+                    } else {
+                        failure.addSuppressed(exception);
+                    }
+                }
+            }
+            if (failure != null) {
+                throw failure;
+            }
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/offline/java/art/arcane/iris/probe/RegionGenerationWindow.java

@@ -0,0 +1,176 @@
+package art.arcane.iris.probe;
+
+import java.time.Duration;
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.concurrent.ExecutorCompletionService;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+final class RegionGenerationWindow implements AutoCloseable {
+    private static final int UNRESPONSIVE_WORKER_EXIT = 70;
+
+    private final int parallelism;
+    private final Policy policy;
+    private final ExecutorService workers;
+    private boolean closed;
+    private boolean processing;
+
+    RegionGenerationWindow(int parallelism, Policy policy) {
+        if (parallelism < 1 || parallelism > 32) {
+            throw new IllegalArgumentException("Generation workers must be 1..32");
+        }
+        this.parallelism = parallelism;
+        this.policy = Objects.requireNonNull(policy, "policy");
+        workers = Executors.newFixedThreadPool(parallelism);
+    }
+
+    @Override
+    public synchronized void close() {
+        if (processing) {
+            throw new IllegalStateException("Cannot close generation workers from an active batch");
+        }
+        if (closed) {
+            return;
+        }
+        closed = true;
+        workers.shutdown();
+        drain(workers, policy, null);
+    }
+
+    int parallelism() {
+        return parallelism;
+    }
+
+    synchronized void requireOpen() {
+        if (closed) {
+            throw new IllegalStateException("Generation workers are closed");
+        }
+    }
+
+    synchronized <T> void process(Request<T> request) throws Exception {
+        requireOpen();
+        if (processing || request.parallelism() > parallelism) {
+            throw new IllegalArgumentException("Generation batch requires idle workers within the session limit");
+        }
+        ExecutorCompletionService<Completed<T>> completions = new ExecutorCompletionService<>(workers);
+        Set<Future<Completed<T>>> active = new HashSet<>(request.parallelism());
+        processing = true;
+        try {
+            int submitted = 0;
+            for (; submitted < Math.min(request.count(), request.parallelism()); submitted++) {
+                active.add(submit(completions, request.generator(), submitted));
+            }
+            for (int completed = 0; completed < request.count(); completed++) {
+                Future<Completed<T>> pending = completions.poll(policy.completionTimeout().toNanos(), TimeUnit.NANOSECONDS);
+                if (pending == null) {
+                    throw new TimeoutException("No generation worker completed within " + policy.completionTimeout());
+                }
+                active.remove(pending);
+                Completed<T> result = pending.get();
+                if (submitted < request.count()) {
+                    active.add(submit(completions, request.generator(), submitted++));
+                }
+                request.sink().accept(result.index(), result.value());
+            }
+        } catch (Exception | Error failure) {
+            closed = true;
+            for (Future<Completed<T>> future : active) {
+                future.cancel(true);
+            }
+            workers.shutdownNow();
+            drain(workers, policy, failure);
+            throw failure;
+        } finally {
+            processing = false;
+        }
+    }
+
+    private static void drain(ExecutorService workers, Policy policy, Throwable failure) {
+        boolean interrupted = Thread.interrupted() || failure instanceof InterruptedException;
+        long deadline = System.nanoTime() + policy.drainTimeout().toNanos();
+        try {
+            while (!workers.isTerminated()) {
+                long remaining = deadline - System.nanoTime();
+                if (remaining <= 0L) {
+                    break;
+                }
+                try {
+                    workers.awaitTermination(remaining, TimeUnit.NANOSECONDS);
+                } catch (InterruptedException interruption) {
+                    interrupted = true;
+                }
+            }
+            if (workers.isTerminated()) {
+                return;
+            }
+            IllegalStateException stalled = new IllegalStateException(
+                    "Generation workers did not stop within " + policy.drainTimeout()
+                            + "; generation resources remain open and no checkpoint will be published", failure);
+            stalled.printStackTrace(System.err);
+            if (policy.haltOnUnresponsiveWorkers()) {
+                System.err.println("Terminating offline generation; incomplete output is retained for inspection");
+                System.err.flush();
+                Runtime.getRuntime().halt(UNRESPONSIVE_WORKER_EXIT);
+            }
+            System.err.println("Waiting for embedded generation workers to stop before releasing their resources");
+            while (!workers.isTerminated()) {
+                try {
+                    workers.awaitTermination(1L, TimeUnit.DAYS);
+                } catch (InterruptedException interruption) {
+                    interrupted = true;
+                }
+            }
+        } finally {
+            if (interrupted) {
+                Thread.currentThread().interrupt();
+            }
+        }
+    }
+
+    private static <T> Future<Completed<T>> submit(ExecutorCompletionService<Completed<T>> completions,
+                                                  Generator<T> generator, int index) {
+        return completions.submit(() -> new Completed<>(index, generator.generate(index)));
+    }
+
+    record Policy(Duration completionTimeout, Duration drainTimeout, boolean haltOnUnresponsiveWorkers) {
+        static final Policy EMBEDDED = new Policy(Duration.ofMinutes(5), Duration.ofSeconds(30), false);
+        static final Policy STANDALONE = new Policy(Duration.ofMinutes(5), Duration.ofSeconds(30), true);
+
+        Policy {
+            Objects.requireNonNull(completionTimeout, "completionTimeout");
+            Objects.requireNonNull(drainTimeout, "drainTimeout");
+            if (completionTimeout.isNegative() || completionTimeout.isZero()
+                    || drainTimeout.isNegative() || drainTimeout.isZero()) {
+                throw new IllegalArgumentException("Worker completion and drain timeouts must be positive");
+            }
+            completionTimeout.toNanos();
+            drainTimeout.toNanos();
+        }
+    }
+
+    record Request<T>(int count, int parallelism, Generator<T> generator, Sink<T> sink) {
+        Request {
+            if (count < 1 || count > 4096 || parallelism < 1 || parallelism > 32) {
+                throw new IllegalArgumentException("Generation window requires 1..4096 tasks and 1..32 workers");
+            }
+        }
+    }
+
+    private record Completed<T>(int index, T value) {
+    }
+
+    @FunctionalInterface
+    interface Generator<T> {
+        T generate(int index) throws Exception;
+    }
+
+    @FunctionalInterface
+    interface Sink<T> {
+        void accept(int index, T value) throws Exception;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/IrisChunkGeneratorHeightCacheTest.java

@@ -0,0 +1,138 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeChunkGenerator;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainColumns;
+import art.arcane.iris.platform.bukkit.nms.BukkitTerrainColumnPolicy;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.runtime.GenerationSessionLease;
+import art.arcane.iris.world.history.BoundaryColumnGeometry;
+import art.arcane.iris.world.history.TerrainBoundarySignature;
+import art.arcane.iris.testsupport.PlatformLeakGuard;
+import art.arcane.volmlib.nativelib.terrain.NativeTerrainColumnPolicy;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.util.List;
+import java.util.Optional;
+import java.util.OptionalInt;
+
+import static org.junit.Assert.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.mockito.Mockito.never;
+
+public final class IrisChunkGeneratorHeightCacheTest {
+    @Rule
+    public final PlatformLeakGuard leakGuard = PlatformLeakGuard.clean();
+
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        NativeBlockTags.bindHeightmapFixtures();
+    }
+
+    @Test
+    public void repeatedNativeHeightUsesLiveHeightQueriesAcrossRuntimeChanges() throws Exception {
+        Fixture fixture = fixture();
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        when(fixture.engine().getHeight(-1, -33, false)).thenReturn(4);
+        for (int index = 0; index < 100; index++) {
+            assertEquals(-11, fixture.generator().getBaseHeight(
+                    -1, -33, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        }
+        verify(fixture.engine(), times(100)).getHeight(-1, -33, false);
+
+        when(fixture.engine().getCacheID()).thenReturn(2);
+        when(fixture.engine().getHeight(-1, -33, false)).thenReturn(7);
+        assertEquals(-8, fixture.generator().getBaseHeight(-1, -33, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        verify(fixture.engine(), never()).getComplex();
+        verify(fixture.engine(), never()).getMode();
+    }
+
+    @Test
+    public void nativeHeightPredicatesSelectFluidOrSolidHeightWithoutGeneratingTerrain() throws Exception {
+        Fixture fixture = fixture();
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        when(fixture.engine().getHeight(0, 0, false)).thenReturn(20, 25);
+        when(fixture.engine().getHeight(0, 0, true)).thenReturn(8);
+
+        assertEquals(5, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        assertEquals(10, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+        assertEquals(-7, fixture.generator().getBaseHeight(0, 0, Heightmap.Types.OCEAN_FLOOR, bounds, null));
+        verify(fixture.engine(), times(2)).getHeight(0, 0, false);
+        verify(fixture.engine(), times(1)).getHeight(0, 0, true);
+        verify(fixture.engine(), never()).getComplex();
+        verify(fixture.engine(), never()).getMode();
+    }
+
+    @Test
+    public void nativePredicatesAndAccessorBoundsRemainExact() throws Exception {
+        NativeTerrainColumnPolicy policy = mock(NativeTerrainColumnPolicy.class);
+        NativeTerrainColumnPolicy.ColumnSession session = mock(NativeTerrainColumnPolicy.ColumnSession.class);
+        when(policy.openQuery(any())).thenReturn(session);
+        when(policy.placementKey(anyString())).thenAnswer(invocation -> invocation.getArgument(0));
+        doReturn(Optional.of(signature().geometry())).when(session).resolvedColumn();
+        NativeChunkGenerator<?, ?, ?, ?, ?> generator = generator(policy);
+        LevelHeightAccessor bounds = LevelHeightAccessor.create(-16, 32);
+        for (int repeat = 0; repeat < 2; repeat++) {
+            assertEquals(-11, generator.getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE, bounds, null));
+            assertEquals(-13, generator.getBaseHeight(0, 0, Heightmap.Types.OCEAN_FLOOR, bounds, null));
+            assertEquals(-13, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING, bounds, null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, bounds, null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.WORLD_SURFACE,
+                    LevelHeightAccessor.create(-16, 2), null));
+            assertEquals(-14, generator.getBaseHeight(0, 0, Heightmap.Types.MOTION_BLOCKING_NO_LEAVES,
+                    LevelHeightAccessor.create(-14, 3), null));
+        }
+        verify(session, times(6)).resolvedColumn();
+    }
+
+    private static Fixture fixture() throws Exception {
+        Engine engine = mock(Engine.class);
+        when(engine.getCacheID()).thenReturn(1);
+        when(engine.acquireGenerationLease(anyString())).thenReturn(GenerationSessionLease.noop());
+        return new Fixture(generator(new BukkitTerrainColumnPolicy(engine, null)), engine);
+    }
+
+    private static NativeChunkGenerator<?, ?, ?, ?, ?> generator(NativeTerrainColumnPolicy policy) throws Exception {
+        NativeChunkGenerator<?, ?, ?, ?, ?> generator = mock(NativeChunkGenerator.class, CALLS_REAL_METHODS);
+        set(generator, "terrainColumns", new NativeTerrainColumns(policy));
+        return generator;
+    }
+
+    private static void set(NativeChunkGenerator<?, ?, ?, ?, ?> generator, String name, Object value) throws Exception {
+        Field field = NativeChunkGenerator.class.getDeclaredField(name);
+        field.setAccessible(true);
+        field.set(generator, value);
+    }
+
+    private static TerrainBoundarySignature signature() {
+        BoundaryColumnGeometry geometry = BoundaryColumnGeometry.fromVoxels(-16, List.of(
+                new BoundaryColumnGeometry.Voxel("minecraft:stone", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:water", BoundaryColumnGeometry.Phase.FLUID, "minecraft:water", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:oak_leaves[persistent=true]", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:short_grass", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:light[level=15]", BoundaryColumnGeometry.Phase.SOLID, "", false)));
+        return new TerrainBoundarySignature(
+                new TerrainBoundarySignature.Column(0, 0, 4, 4, OptionalInt.of(1), OptionalInt.empty()),
+                new TerrainBoundarySignature.Samples(new TerrainBoundarySignature.VerticalLayout(-16, 5, 1),
+                        new TerrainBoundarySignature.BiomeEncoding(List.of("minecraft:plains"), new short[]{0})), geometry);
+    }
+
+    private record Fixture(NativeChunkGenerator<?, ?, ?, ?, ?> generator, Engine engine) {
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeGenerationWriteGuardTest.java

@@ -0,0 +1,129 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.iris.structure.nativegen.GenerationWritePolicy;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeGenerationWriteGuard;
+
+import art.arcane.iris.generation.runtime.DimensionStackContext;
+import art.arcane.iris.generation.runtime.DimensionStackLayout;
+import art.arcane.iris.generation.runtime.IrisComplex;
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.world.history.GenerationActivation;
+import art.arcane.iris.world.history.GenerationHistory;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.structure.object.IrisStaticObjectLayer;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.Optional;
+import java.util.function.Predicate;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+public final class NativeGenerationWriteGuardTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void staticObjectsProtectRelativeHeightBeforeStackSampling() {
+        IrisStaticObjectLayer objects = mock(IrisStaticObjectLayer.class);
+        DimensionStackContext stack = mock(DimensionStackContext.class);
+        when(objects.contains(-3, 74, -7)).thenReturn(true);
+
+        Predicate<BlockPos> protectedPositions = NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, stack, -64));
+
+        assertTrue(protectedPositions.test(new BlockPos(-3, 10, -7)));
+        verifyNoInteractions(stack);
+        assertFalse(NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, null, -64))
+                .test(new BlockPos(-3, 11, -7)));
+    }
+
+    @Test
+    public void emptyStaticLayerSkipsContainsAndCachesEachSignedColumn() {
+        IrisStaticObjectLayer objects = mock(IrisStaticObjectLayer.class);
+        DimensionStackContext stack = mock(DimensionStackContext.class);
+        DimensionStackLayout negative = mock(DimensionStackLayout.class);
+        DimensionStackLayout positive = mock(DimensionStackLayout.class);
+        when(objects.isEmpty()).thenReturn(true);
+        when(stack.sample(-1, -1)).thenReturn(negative);
+        when(stack.sample(-1, 1)).thenReturn(positive);
+        when(negative.isHostFeatureProtectedY(64)).thenReturn(true);
+        when(positive.isHostFeatureProtectedY(65)).thenReturn(true);
+
+        Predicate<BlockPos> protectedPositions = NativeGenerationWriteGuard.protectedPositions(GenerationWritePolicy.protectedPositions(objects, stack, -64));
+
+        assertTrue(protectedPositions.test(new BlockPos(-1, 0, -1)));
+        assertFalse(protectedPositions.test(new BlockPos(-1, 1, -1)));
+        assertTrue(protectedPositions.test(new BlockPos(-1, 1, 1)));
+        verify(stack, times(1)).sample(-1, -1);
+        verify(stack, times(1)).sample(-1, 1);
+        verify(objects, never()).contains(anyInt(), anyInt(), anyInt());
+    }
+
+    @Test
+    public void preTerrainSavedStampDistinguishesEarlierNativeStarts() {
+        IrisEngine engine = mock(IrisEngine.class);
+        GenerationHistoryRuntimeRouter router = mock(GenerationHistoryRuntimeRouter.class);
+        GenerationHistory history = mock(GenerationHistory.class);
+        GenerationActivation active = mock(GenerationActivation.class);
+        when(engine.getGenerationHistoryRuntimeRouter()).thenReturn(Optional.of(router));
+        when(router.history()).thenReturn(history);
+        when(history.activeActivation()).thenReturn(active);
+        when(active.activationId()).thenReturn(4L);
+        assertTrue(GenerationWritePolicy.isHistoricalStructure(engine, 3));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 0));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 4));
+        assertFalse(GenerationWritePolicy.isHistoricalStructure(engine, 5));
+    }
+
+    @Test
+    public void partialNeighborsMayFinishButCompletedHistoricalNeighborRejectsPass() {
+        Engine engine = mock(Engine.class);
+        IrisComplex complex = mock(IrisComplex.class);
+        when(engine.getComplex()).thenReturn(complex);
+        WorldGenLevel region = mock(WorldGenLevel.class);
+        ChunkAccess partial = mock(ChunkAccess.class);
+        when(partial.getPersistedStatus()).thenReturn(ChunkStatus.TERRAIN);
+        when(region.getChunk(anyInt(), anyInt())).thenReturn(partial);
+        assertTrue(NativeGenerationWriteGuard.allowsDecoration(engine.getComplex()::allowsMantleChunkWrite, region, new ChunkPos(0, 0)));
+        ChunkAccess complete = mock(ChunkAccess.class);
+        when(complete.getPersistedStatus()).thenReturn(ChunkStatus.FULL);
+        when(region.getChunk(1, -1)).thenReturn(complete);
+        assertFalse(NativeGenerationWriteGuard.allowsDecoration(engine.getComplex()::allowsMantleChunkWrite, region, new ChunkPos(0, 0)));
+    }
+
+    @Test
+    public void historicalNoiseMayFinishFeaturesButNeverReplaysNoiseOrCompletedStage() {
+        Engine engine = mock(Engine.class);
+        IrisComplex complex = mock(IrisComplex.class);
+        when(engine.getComplex()).thenReturn(complex);
+        ChunkAccess chunk = mock(ChunkAccess.class);
+        when(chunk.getPos()).thenReturn(new ChunkPos(-2, 3));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.TERRAIN);
+        assertTrue(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.FEATURES));
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.TERRAIN));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.FEATURES);
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.FEATURES));
+        when(chunk.getPersistedStatus()).thenReturn(ChunkStatus.FULL);
+        assertFalse(NativeGenerationWriteGuard.allowsPendingStage(engine.getComplex()::allowsMantleChunkWrite, chunk, ChunkStatus.SPAWN));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureFactoryTest.java

@@ -0,0 +1,476 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureStartInjector;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureFactory;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeJigsawMetadata;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.ForcedStructureChunkGenerator;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureTemplatePoolBounds;
+
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import java.util.Set;
+import art.arcane.iris.structure.jigsaw.IrisJigsawConfiguration;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import com.mojang.datafixers.util.Either;
+import com.mojang.datafixers.util.Pair;
+import com.mojang.serialization.MapCodec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderOwner;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.Vec3i;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.IntTag;
+import net.minecraft.nbt.ListTag;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.biome.FixedBiomeSource;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.blending.Blender;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.EmptyPoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.ListPoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.SinglePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElementType;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.pools.alias.PoolAliasBinding;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureFactoryTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void genericSourceDoesNotRequireJigsawType() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+
+        Structure configured = NativeStructureFactory.configure(
+                null, source, null, false, 80);
+
+        assertSame(source, configured);
+    }
+
+    @Test
+    public void jigsawOptionsFailClosedForNonJigsawSource() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+
+        assertThrows(IllegalStateException.class, () -> NativeStructureFactory.configure(
+                null, source, new IrisJigsawConfiguration(), false, 80));
+    }
+
+    @Test
+    public void sourceMetadataReadsScalarAndAxisSpecificJigsawRanges() {
+        CompoundTag scalar = new CompoundTag();
+        scalar.putInt("max_distance_from_center", 80);
+        CompoundTag axisSpecific = new CompoundTag();
+        CompoundTag distance = new CompoundTag();
+        distance.putInt("horizontal", 96);
+        distance.putInt("vertical", 64);
+        axisSpecific.put("max_distance_from_center", distance);
+
+        assertEquals(80, NativeJigsawMetadata.sourceDistance(scalar, "horizontal"));
+        assertEquals(80, NativeJigsawMetadata.sourceDistance(scalar, "vertical"));
+        assertEquals(96, NativeJigsawMetadata.sourceDistance(axisSpecific, "horizontal"));
+        assertEquals(64, NativeJigsawMetadata.sourceDistance(axisSpecific, "vertical"));
+    }
+
+    @Test
+    public void sourceMetadataIncludesAdjustBoundingBoxExpansion() {
+        Structure none = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        Structure beardBox = new SwampHutStructure(new Structure.StructureSettings.Builder(HolderSet.empty())
+                .terrainAdapation(TerrainAdjustment.BEARD_BOX)
+                .build());
+
+        assertEquals(0, NativeJigsawMetadata.horizontalReferenceExpansion(none));
+        assertEquals(12, NativeJigsawMetadata.horizontalReferenceExpansion(beardBox));
+    }
+
+    @Test
+    public void templatePoolSpanIncludesWeightedListsFallbacksAndRotations() {
+        StructurePoolElement narrow = inlineElement(30, 8, 70);
+        StructurePoolElement wide = inlineElement(96, 8, 12);
+        ListPoolElement list = new ListPoolElement(
+                List.of(narrow, wide, EmptyPoolElement.INSTANCE),
+                StructureTemplatePool.Projection.RIGID);
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(
+                fallbackHolder,
+                List.of(Pair.of(inlineElement(110, 8, 20), 1)));
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                fallbackHolder,
+                List.of(Pair.of(list, 5), Pair.of(EmptyPoolElement.INSTANCE, 1)));
+        startHolder.bind(start);
+
+        assertEquals(110, NativeStructureTemplatePoolBounds.horizontalSpan(start, null));
+    }
+
+    @Test
+    public void oversizedInlineStartTemplateReportsItsFullSpan() {
+        BoundPoolHolder holder = new BoundPoolHolder("test:oversized");
+        StructureTemplatePool pool = new StructureTemplatePool(
+                holder,
+                List.of(Pair.of(inlineElement(160, 8, 9), 1)));
+        holder.bind(pool);
+
+        assertEquals(160, NativeStructureTemplatePoolBounds.horizontalSpan(pool, null));
+    }
+
+    @Test
+    public void sourceSpanIncludesOnlyAliasesThatCanReplaceTheStartPool() {
+        BoundPoolHolder emptyHolder = new BoundPoolHolder("test:empty");
+        StructureTemplatePool empty = new StructureTemplatePool(emptyHolder, List.of());
+        emptyHolder.bind(empty);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(20, 8, 12), 1)));
+        startHolder.bind(start);
+        BoundPoolHolder replacementHolder = new BoundPoolHolder("test:replacement");
+        StructureTemplatePool replacement = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(30, 8, 12), 1)));
+        replacementHolder.bind(replacement);
+        BoundPoolHolder unrelatedHolder = new BoundPoolHolder("test:unrelated");
+        StructureTemplatePool unrelated = new StructureTemplatePool(
+                emptyHolder, List.of(Pair.of(inlineElement(200, 8, 12), 1)));
+        unrelatedHolder.bind(unrelated);
+        ResourceKey<StructureTemplatePool> startKey = startHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> replacementKey = replacementHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> unrelatedKey = unrelatedHolder.unwrapKey().orElseThrow();
+        ResourceKey<StructureTemplatePool> childAlias = ResourceKey.create(
+                Registries.TEMPLATE_POOL, Identifier.parse("test:child_alias"));
+        List<PoolAliasBinding> aliases = List.of(
+                PoolAliasBinding.direct(startKey, replacementKey),
+                PoolAliasBinding.direct(childAlias, unrelatedKey));
+        Map<ResourceKey<StructureTemplatePool>, StructureTemplatePool> pools = Map.of(
+                replacementKey, replacement,
+                unrelatedKey, unrelated);
+
+        assertEquals(30, NativeStructureTemplatePoolBounds.sourceHorizontalSpan(
+                null, start, startKey, aliases, pools::get));
+    }
+
+    @Test
+    public void sourceStartSpanDoesNotIncludeItsFallbackPool() {
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:large_fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(inlineElement(180, 8, 10), 1)));
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder startHolder = new BoundPoolHolder("test:small_start");
+        StructureTemplatePool start = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(inlineElement(24, 8, 10), 1)));
+        startHolder.bind(start);
+
+        assertEquals(180, NativeStructureTemplatePoolBounds.horizontalSpan(start, null));
+        assertEquals(24, NativeStructureTemplatePoolBounds.sourceHorizontalSpan(
+                null, start, startHolder.unwrapKey().orElseThrow(), List.of(), ignored -> null));
+    }
+
+    @Test
+    public void customPoolElementUsesItsBoundingBoxCapability() {
+        BoundPoolHolder fallbackHolder = new BoundPoolHolder("test:custom_fallback");
+        StructureTemplatePool fallback = new StructureTemplatePool(fallbackHolder, List.of());
+        fallbackHolder.bind(fallback);
+        BoundPoolHolder poolHolder = new BoundPoolHolder("test:custom");
+        StructureTemplatePool pool = new StructureTemplatePool(
+                fallbackHolder, List.of(Pair.of(new BoundingPoolElement(37, 11), 1)));
+        poolHolder.bind(pool);
+
+        assertEquals(37, NativeStructureTemplatePoolBounds.horizontalSpan(pool, null));
+    }
+
+    @Test
+    public void forcedGeneratorBypassesBiomeEligibilityWithoutFabricatingTerrain() {
+        ChunkGenerator delegate = new TestChunkGenerator();
+        Holder<Biome> biome = Holder.direct((Biome) null);
+        LevelHeightAccessor heightAccessor = LevelHeightAccessor.create(-64, 384);
+        ForcedStructureChunkGenerator generator = new ForcedStructureChunkGenerator(
+                delegate, biome);
+
+        assertEquals(63, generator.getSeaLevel());
+        assertEquals(64, generator.getBaseHeight(
+                0, 0, Heightmap.Types.WORLD_SURFACE_WG, heightAccessor, null));
+        NoiseColumn column = generator.getBaseColumn(
+                0, 0, heightAccessor, null);
+        assertSame(Blocks.STONE, column.getBlock(80).getBlock());
+        assertSame(Blocks.STONE, column.getBlock(81).getBlock());
+        assertNotSame(delegate.getBiomeSource(), generator.getBiomeSource());
+    }
+
+    @Test
+    public void undergroundRelocationMovesGenericPiecesAndReturnsFreshStart() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece piece = new SwampHutPiece(RandomSource.create(17L), 0, 0);
+        StructureStart start = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(piece))
+        );
+
+        StructureStart relocated = NativeStructureVerticalPlacer.relocateToMinY(
+                start, source, -20, LevelHeightAccessor.create(-64, 384));
+
+        assertNotSame(start, relocated);
+        assertEquals(-20, relocated.getPieces().getFirst().getBoundingBox().minY());
+        assertEquals(-20, relocated.getBoundingBox().minY());
+    }
+
+    @Test
+    public void invalidGeneratedStartIsANormalSkippedCandidate() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        StructureStart valid = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(
+                        new SwampHutPiece(RandomSource.create(23L), 0, 0)))
+        );
+
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(
+                StructureStart.INVALID_START));
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(null));
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(
+                new StructureStart(source, new ChunkPos(0, 0), 0,
+                        new PiecesContainer(List.of()))));
+        assertTrue(NativeStructureStartInjector.isUsableGeneratedStart(valid));
+    }
+
+    @Test
+    public void unrepresentableGeneratedContentBecomesAnUnpublishedInvalidStart() {
+        Structure source = new SwampHutStructure(
+                new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece boundaryPiece = new SwampHutPiece(RandomSource.create(29L), 0, 0);
+        boundaryPiece.move(143 - boundaryPiece.getBoundingBox().maxX(), 0, 0);
+        StructureStart boundary = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(boundaryPiece))
+        );
+        SwampHutPiece oversizedPiece = new SwampHutPiece(RandomSource.create(31L), 0, 0);
+        oversizedPiece.move(144 - oversizedPiece.getBoundingBox().maxX(), 0, 0);
+        StructureStart oversized = new StructureStart(
+                source,
+                new ChunkPos(0, 0),
+                0,
+                new PiecesContainer(List.of(oversizedPiece))
+        );
+
+        StructureStart boundaryResult = NativeStructureReferenceEnvelope.wrapForPublication(
+                boundary, source, 0, new IrisStructureTerrain(), "test:boundary_content");
+
+        StructureStart result = NativeStructureReferenceEnvelope.wrapForPublication(
+                oversized, source, 0,
+                new IrisStructureTerrain(),
+                "test:oversized_content");
+
+        assertTrue(boundaryResult.isValid());
+        assertSame(StructureStart.INVALID_START, result);
+        assertFalse(NativeStructureStartInjector.isUsableGeneratedStart(result));
+        assertEquals(1, oversized.getPieces().size());
+    }
+
+    private static final class TestChunkGenerator extends ChunkGenerator {
+        private TestChunkGenerator() {
+            super(new FixedBiomeSource(Holder.direct((Biome) null)));
+        }
+
+        @Override
+        protected MapCodec<? extends ChunkGenerator> codec() {
+            return MapCodec.unit(this);
+        }
+
+        @Override
+        public void spawnOriginalMobs(WorldGenRegion worldGenRegion) {
+        }
+
+        @Override
+        public int getGenDepth() {
+            return 384;
+        }
+
+        @Override
+        public CompletableFuture<ChunkAccess> buildTerrain(
+                ChunkAccess centerChunk, Blender blender, RandomState randomState,
+                StructureManager structureManager, BiomeManager biomeManager, WorldGenRegion region, Set<Holder<Biome>> possibleBiomes) {
+            return CompletableFuture.completedFuture(centerChunk);
+        }
+
+        @Override
+        public int getSeaLevel() {
+            return 63;
+        }
+
+        @Override
+        public int getMinY() {
+            return -64;
+        }
+
+        @Override
+        public int getBaseHeight(int x, int z, Heightmap.Types type,
+                                 LevelHeightAccessor heightAccessor, RandomState randomState) {
+            return 64;
+        }
+
+        @Override
+        public NoiseColumn getBaseColumn(int x, int z, LevelHeightAccessor heightAccessor,
+                                         RandomState randomState) {
+            BlockState[] states = new BlockState[heightAccessor.getHeight()];
+            for (int index = 0; index < states.length; index++) {
+                states[index] = Blocks.STONE.defaultBlockState();
+            }
+            return new NoiseColumn(heightAccessor.getMinY(), states);
+        }
+
+        @Override
+        public void addDebugScreenInfo(List<String> result, RandomState randomState,
+                                       BlockPos feetPos, SamplerContext samplerContext) {
+        }
+    }
+
+    private static StructurePoolElement inlineElement(int sizeX, int sizeY, int sizeZ) {
+        StructureTemplate template = new StructureTemplate();
+        CompoundTag tag = new CompoundTag();
+        ListTag size = new ListTag();
+        size.add(IntTag.valueOf(sizeX));
+        size.add(IntTag.valueOf(sizeY));
+        size.add(IntTag.valueOf(sizeZ));
+        tag.put("size", size);
+        template.load(BuiltInRegistries.BLOCK, tag);
+        return new InlinePoolElement(template);
+    }
+
+    private static final class InlinePoolElement extends SinglePoolElement {
+        private final StructureTemplate inlineTemplate;
+
+        private InlinePoolElement(StructureTemplate template) {
+            super(Either.right(template), Holder.direct(new StructureProcessorList(List.of())),
+                    StructureTemplatePool.Projection.RIGID, Optional.<LiquidSettings>empty());
+            inlineTemplate = template;
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return inlineTemplate.getBoundingBox(
+                    new StructurePlaceSettings().setRotation(rotation), position);
+        }
+    }
+
+    private static final class BoundingPoolElement extends StructurePoolElement {
+        private final int width;
+        private final int depth;
+
+        private BoundingPoolElement(int width, int depth) {
+            super(StructureTemplatePool.Projection.RIGID);
+            this.width = width;
+            this.depth = depth;
+        }
+
+        @Override
+        public Vec3i getSize(StructureTemplateManager templateManager, Rotation rotation) {
+            return new Vec3i(width, 1, depth);
+        }
+
+        @Override
+        public List<StructureTemplate.JigsawBlockInfo> getShuffledJigsawBlocks(
+                StructureTemplateManager templateManager, BlockPos position,
+                Rotation rotation, RandomSource random) {
+            return List.of();
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return new BoundingBox(
+                    position.getX(), position.getY(), position.getZ(),
+                    position.getX() + width - 1, position.getY(),
+                    position.getZ() + depth - 1);
+        }
+
+        @Override
+        public boolean place(StructureTemplateManager templateManager,
+                             WorldGenLevel world,
+                             StructureManager structureManager, ChunkGenerator chunkGenerator,
+                             BlockPos position, BlockPos pivot, Rotation rotation,
+                             BoundingBox area, RandomSource random,
+                             LiquidSettings liquidSettings, boolean keepJigsaws) {
+            return true;
+        }
+
+        @Override
+        public StructurePoolElementType<?> getType() {
+            return StructurePoolElementType.EMPTY;
+        }
+    }
+
+    private static final class BoundPoolHolder extends Holder.Reference<StructureTemplatePool> {
+        private BoundPoolHolder(String key) {
+            super(Type.STAND_ALONE, new HolderOwner<>() {
+            }, ResourceKey.create(Registries.TEMPLATE_POOL, Identifier.parse(key)), null);
+        }
+
+        private void bind(StructureTemplatePool pool) {
+            bindValue(pool);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureGenerationKeysContractTest.java

@@ -0,0 +1,46 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureGenerationKeys;
+
+import net.minecraft.world.level.levelgen.structure.placement.AbstractSpreadingStructurePlacement;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Vec3i;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadType;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacement;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.Optional;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureGenerationKeysContractTest {
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void frequencyGateUsesMappedAccessorAndRejectsNonPositivePlacements() {
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(0.0F)));
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(-0.1F)));
+        assertFalse(NativeStructureGenerationKeys.isEnabledPlacement(placement(Float.NaN)));
+        assertTrue(NativeStructureGenerationKeys.isEnabledPlacement(placement(0.25F)));
+    }
+
+    private static RandomSpreadStructurePlacement placement(float frequency) {
+        return new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                AbstractSpreadingStructurePlacement.FrequencyReductionMethod.DEFAULT,
+                frequency,
+                1,
+                Optional.empty(),
+                2,
+                1,
+                RandomSpreadType.LINEAR);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureLocatePersistenceTest.java

@@ -0,0 +1,199 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureLocatePersistence;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureLocatePersistenceTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void storageProbeScansEachCandidateOnlyOnce() {
+        AtomicInteger reads = new AtomicInteger();
+        CompoundTag chunk = new CompoundTag();
+        chunk.putInt("DataVersion", SharedConstants.getCurrentVersion().dataVersion().version());
+        chunk.putString("Status", "full");
+        CompoundTag start = new CompoundTag();
+        start.putString("id", "minecraft:village_plains");
+        start.putInt("references", 0);
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", start);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            reads.incrementAndGet();
+                            chunk.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        });
+        ChunkPos chunkPos = new ChunkPos(7, -11);
+
+        assertTrue(budget.acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+        assertTrue(budget.acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+        assertEquals(1, reads.get());
+        assertEquals(1, budget.used());
+    }
+
+    @Test
+    public void legacyStoredChunkIsDatafixedBeforeItsStartIsClassified() {
+        AtomicBoolean datafixed = new AtomicBoolean();
+        CompoundTag legacy = new CompoundTag();
+        legacy.putInt("DataVersion", 100);
+        legacy.putString("Status", "full");
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            legacy.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        },
+                        (level, storedChunk) -> {
+                            datafixed.set(true);
+                            CompoundTag fixed = storedChunk.copy();
+                            fixed.putInt("DataVersion",
+                                    SharedConstants.getCurrentVersion().dataVersion().version());
+                            CompoundTag start = new CompoundTag();
+                            start.putString("id", "minecraft:village_plains");
+                            start.putInt("references", 1);
+                            CompoundTag starts = new CompoundTag();
+                            starts.put("minecraft:village_plains", start);
+                            CompoundTag structures = new CompoundTag();
+                            structures.put("starts", starts);
+                            fixed.put("structures", structures);
+                            return fixed;
+                        });
+
+        assertFalse(budget.acceptsStored(
+                null, new ChunkPos(3, 4), "minecraft:village_plains", true));
+        assertTrue(datafixed.get());
+    }
+
+    @Test
+    public void partialDatafixFailureFallsBackToSelectedChunkVerification() {
+        CompoundTag legacy = new CompoundTag();
+        legacy.putInt("DataVersion", 100);
+        NativeStructureLocatePersistence.ProbeBudget budget =
+                new NativeStructureLocatePersistence.ProbeBudget(
+                        512,
+                        (chunkPos, visitor) -> {
+                            legacy.acceptAsRoot(visitor);
+                            return CompletableFuture.completedFuture(null);
+                        },
+                        (level, storedChunk) -> {
+                            throw new IllegalStateException("broken partial datafix");
+                        });
+
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(9, -2), "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void missingStartsContainerFallsBackToSelectedChunkVerification() {
+        CompoundTag chunk = currentChunk();
+        NativeStructureLocatePersistence.ProbeBudget budget = budget(chunk);
+
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(5, 8), "minecraft:village_plains", false));
+        assertTrue(budget.acceptsStored(
+                null, new ChunkPos(5, 8), "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void presentEmptyStartsContainerRejectsTheCandidateWithoutLoading() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", new CompoundTag());
+        chunk.put("structures", structures);
+        NativeStructureLocatePersistence.ProbeBudget budget = budget(chunk);
+
+        assertFalse(budget.acceptsStored(
+                null, new ChunkPos(-3, 2), "minecraft:village_plains", false));
+    }
+
+    @Test
+    public void collisionTombstoneIsRejectedForNormalAndUnexploredLocate() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag tombstone = new CompoundTag();
+        tombstone.putString("id", "INVALID");
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", tombstone);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        ChunkPos chunkPos = new ChunkPos(12, -9);
+
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", false));
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+    }
+
+    @Test
+    public void malformedNonCompoundStartIsRejectedWithoutLoading() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag starts = new CompoundTag();
+        starts.putInt("minecraft:village_plains", 1);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+
+        assertFalse(budget(chunk).acceptsStored(
+                null, new ChunkPos(1, 1), "minecraft:village_plains", false));
+    }
+
+    @Test
+    public void referencedStoredStartIsOnlyRejectedForUnexploredLocate() {
+        CompoundTag chunk = currentChunk();
+        CompoundTag start = new CompoundTag();
+        start.putString("id", "minecraft:village_plains");
+        start.putInt("references", 1);
+        CompoundTag starts = new CompoundTag();
+        starts.put("minecraft:village_plains", start);
+        CompoundTag structures = new CompoundTag();
+        structures.put("starts", starts);
+        chunk.put("structures", structures);
+        ChunkPos chunkPos = new ChunkPos(-4, -7);
+
+        assertTrue(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", false));
+        assertFalse(budget(chunk).acceptsStored(
+                null, chunkPos, "minecraft:village_plains", true));
+    }
+
+    private static CompoundTag currentChunk() {
+        CompoundTag chunk = new CompoundTag();
+        chunk.putInt("DataVersion", SharedConstants.getCurrentVersion().dataVersion().version());
+        return chunk;
+    }
+
+    private static NativeStructureLocatePersistence.ProbeBudget budget(CompoundTag chunk) {
+        return new NativeStructureLocatePersistence.ProbeBudget(
+                512,
+                (chunkPos, visitor) -> {
+                    chunk.acceptAsRoot(visitor);
+                    return CompletableFuture.completedFuture(null);
+                });
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureOwnershipFingerprintTest.java

@@ -0,0 +1,345 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceRepair;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureOwnershipFingerprint;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.nativegen.IrisNativeStructure;
+import art.arcane.iris.structure.placement.IrisStructurePlacement;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.Vec3i;
+import net.minecraft.nbt.ListTag;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.LegacyRandomSource;
+import net.minecraft.world.level.levelgen.RandomSupport;
+import net.minecraft.world.level.levelgen.WorldgenRandom;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElementType;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureOwnershipFingerprintTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void monumentFingerprintSurvivesSourceYRegenerationWithoutSyntheticPieces() {
+        long seed = 8372619L;
+        ChunkPos origin = new ChunkPos(9, -4);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart generated = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                generated, 0, 80, -64, 320);
+        int alignedLocatorY = NativeStructureOwnershipFingerprint.locatorY(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.FORCE_CARVE)
+                .setHorizontalPadding(24);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                structure,
+                0,
+                terrain);
+        String beforeReload = NativeStructureOwnershipFingerprint.fingerprint(
+                "minecraft:monument", wrapped);
+
+        ListTag serializedPieces = (ListTag) new PiecesContainer(wrapped.getPieces()).save(null);
+        PiecesContainer loadedPieces = PiecesContainer.load(serializedPieces, null);
+        assertEquals(1, loadedPieces.pieces().size());
+        assertTrue(loadedPieces.pieces().getFirst()
+                instanceof OceanMonumentPieces.MonumentBuilding);
+        PiecesContainer regeneratedPieces = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                origin, seed, loadedPieces);
+        StructureStart reloaded = new StructureStart(structure, origin, 0, regeneratedPieces);
+        String afterReload = NativeStructureOwnershipFingerprint.fingerprint(
+                "minecraft:monument", reloaded);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", wrapped, NativeStructureReferenceEnvelope.referenceBounds(wrapped, structure, terrain)), plan(origin, NativeStructureReferenceEnvelope.contentBounds(wrapped).minY()));
+
+        assertEquals(beforeReload, afterReload);
+        assertTrue(NativeStructureOwnershipFingerprint.matches(ownership, reloaded));
+        assertNotEquals(alignedLocatorY, NativeStructureOwnershipFingerprint.locatorY(reloaded));
+        assertEquals(alignedLocatorY, ownership.locatorY());
+        assertEquals(1, reloaded.getPieces().size());
+        assertEquals(1, wrapped.getPieces().size());
+    }
+
+    @Test
+    public void sameKeyAndOriginStillRequiresMatchingContentIdentity() {
+        long seed = 18273L;
+        ChunkPos origin = new ChunkPos(2, 3);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart expected = monumentStart(structure, origin, seed);
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", expected, expected.getBoundingBox()), plan(origin, NativeStructureReferenceEnvelope.contentBounds(expected).minY()));
+
+        assertFalse(NativeStructureOwnershipFingerprint.matches(ownership, moved));
+    }
+
+    @Test
+    public void persistedEnvelopeRepairsReloadedMonumentReferenceOutsideLiveBounds() {
+        long seed = 772931L;
+        ChunkPos origin = new ChunkPos(4, -7);
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        StructureStart generated = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                generated, 0, 80, -64, 320);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.FORCE_CARVE)
+                .setHorizontalPadding(24);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                structure,
+                0,
+                terrain);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", wrapped, NativeStructureReferenceEnvelope.referenceBounds(wrapped, structure, terrain)), plan(origin, NativeStructureReferenceEnvelope.contentBounds(wrapped).minY()));
+        PiecesContainer regeneratedPieces = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                origin, seed, new PiecesContainer(wrapped.getPieces()));
+        StructureStart reloaded = new StructureStart(structure, origin, 0, regeneratedPieces);
+        ChunkPos target = outsideLiveBounds(ownership, reloaded);
+
+        assertNotNull(target);
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                target, "minecraft:monument", reloaded, ownership));
+        assertFalse(NativeStructureReferenceRepair.requiresReference(
+                target, "minecraft:monument", reloaded, null));
+    }
+
+    @Test
+    public void overlappingManualStartsSixteenChunksApartRemainIndependentlyReferenced() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos westOrigin = new ChunkPos(0, 0);
+        ChunkPos eastOrigin = new ChunkPos(16, 0);
+        StructureStart west = monumentStart(structure, westOrigin, 317L);
+        StructureStart east = monumentStart(structure, eastOrigin, 941L);
+        west.getPieces().getFirst().move(112, 0, 0);
+        east.getPieces().getFirst().move(-96, 0, 0);
+        NativeStructureOwnershipRecord westOwnership = ownership(westOrigin, west, structure);
+        NativeStructureOwnershipRecord eastOwnership = ownership(eastOrigin, east, structure);
+        ChunkPos shared = new ChunkPos(8, 0);
+
+        assertTrue(NativeStructureReferenceEnvelope.contentBounds(west).intersects(
+                NativeStructureReferenceEnvelope.contentBounds(east)));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", west, westOwnership));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", east, eastOwnership));
+    }
+
+    @Test
+    public void denseAdjacentManualStartsDoNotSuppressEachOther() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos firstOrigin = new ChunkPos(0, 0);
+        ChunkPos secondOrigin = new ChunkPos(1, 0);
+        StructureStart first = monumentStart(structure, firstOrigin, 17L);
+        StructureStart second = monumentStart(structure, secondOrigin, 23L);
+        NativeStructureOwnershipRecord firstOwnership = ownership(firstOrigin, first, structure);
+        NativeStructureOwnershipRecord secondOwnership = ownership(secondOrigin, second, structure);
+        ChunkPos shared = new ChunkPos(0, 0);
+
+        assertTrue(NativeStructureReferenceEnvelope.contentBounds(first).intersects(
+                NativeStructureReferenceEnvelope.contentBounds(second)));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", first, firstOwnership));
+        assertTrue(NativeStructureReferenceRepair.requiresReference(
+                shared, "minecraft:monument", second, secondOwnership));
+    }
+
+    @Test
+    public void customPoolElementIdentityDoesNotDependOnProcessLocalToString() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos origin = new ChunkPos(3, -2);
+        StructureStart first = poolStart(structure, origin, new IdentityStringPoolElement());
+        StructureStart reloaded = poolStart(structure, origin, new IdentityStringPoolElement());
+
+        assertEquals(
+                NativeStructureOwnershipFingerprint.fingerprint("test:custom_pool", first),
+                NativeStructureOwnershipFingerprint.fingerprint("test:custom_pool", reloaded));
+    }
+
+    @Test
+    public void namedPoolTemplateRemainsPartOfTheStableFingerprint() {
+        OceanMonumentStructure structure = new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+        ChunkPos origin = new ChunkPos(3, -2);
+        StructurePoolElement firstElement = StructurePoolElement.single("test:first")
+                .apply(StructureTemplatePool.Projection.RIGID);
+        StructurePoolElement secondElement = StructurePoolElement.single("test:second")
+                .apply(StructureTemplatePool.Projection.RIGID);
+
+        assertNotEquals(
+                NativeStructureOwnershipFingerprint.fingerprint(
+                        "test:named_pool", poolStart(structure, origin, firstElement)),
+                NativeStructureOwnershipFingerprint.fingerprint(
+                        "test:named_pool", poolStart(structure, origin, secondElement)));
+    }
+
+    private static StructureStart monumentStart(OceanMonumentStructure structure,
+                                                  ChunkPos origin, long seed) {
+        WorldgenRandom random = new WorldgenRandom(
+                new LegacyRandomSource(RandomSupport.generateUniqueSeed()));
+        random.setLargeFeatureSeed(seed, origin.x(), origin.z());
+        Direction orientation = Direction.Plane.HORIZONTAL.getRandomDirection(random);
+        OceanMonumentPieces.MonumentBuilding building = new OceanMonumentPieces.MonumentBuilding(
+                random,
+                origin.getMinBlockX() - 29,
+                origin.getMinBlockZ() - 29,
+                orientation
+        );
+        return new StructureStart(
+                structure,
+                origin,
+                0,
+                new PiecesContainer(List.of(building))
+        );
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin, int baseY) {
+        IrisNativeStructure source = new IrisNativeStructure()
+                .setStructure("minecraft:monument")
+                .setWeight(1);
+        IrisStructurePlacement placement = new IrisStructurePlacement()
+                .setPlacementId("monument-test")
+                .setNativeStructures(new KList<IrisNativeStructure>().qadd(source));
+        return new NativeStructureStartPlan(
+                placement,
+                source,
+                origin.x(),
+                origin.z(),
+                baseY
+        );
+    }
+
+    private static NativeStructureOwnershipRecord ownership(
+            ChunkPos origin, StructureStart start, OceanMonumentStructure structure) {
+        return NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        "minecraft:monument", start, NativeStructureReferenceEnvelope.referenceBounds(
+                        start, structure, new IrisStructureTerrain())), plan(origin, NativeStructureReferenceEnvelope.contentBounds(start).minY()));
+    }
+
+    private static StructureStart poolStart(
+            OceanMonumentStructure structure, ChunkPos origin, StructurePoolElement element) {
+        BlockPos position = new BlockPos(
+                origin.getMiddleBlockX(), 64, origin.getMiddleBlockZ());
+        PoolElementStructurePiece piece = new PoolElementStructurePiece(
+                null, element, position, 0, Rotation.NONE,
+                new BoundingBox(position), LiquidSettings.APPLY_WATERLOGGING);
+        return new StructureStart(
+                structure, origin, 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static final class IdentityStringPoolElement extends StructurePoolElement {
+        private IdentityStringPoolElement() {
+            super(StructureTemplatePool.Projection.RIGID);
+        }
+
+        @Override
+        public Vec3i getSize(StructureTemplateManager templateManager, Rotation rotation) {
+            return new Vec3i(1, 1, 1);
+        }
+
+        @Override
+        public List<StructureTemplate.JigsawBlockInfo> getShuffledJigsawBlocks(
+                StructureTemplateManager templateManager, BlockPos position,
+                Rotation rotation, RandomSource random) {
+            return List.of();
+        }
+
+        @Override
+        public BoundingBox getBoundingBox(StructureTemplateManager templateManager,
+                                          BlockPos position, Rotation rotation) {
+            return new BoundingBox(position);
+        }
+
+        @Override
+        public boolean place(StructureTemplateManager templateManager,
+                             WorldGenLevel world, StructureManager structureManager,
+                             ChunkGenerator chunkGenerator, BlockPos position, BlockPos pivot,
+                             Rotation rotation, BoundingBox area, RandomSource random,
+                             LiquidSettings liquidSettings, boolean keepJigsaws) {
+            return true;
+        }
+
+        @Override
+        public StructurePoolElementType<?> getType() {
+            return StructurePoolElementType.EMPTY;
+        }
+
+        @Override
+        public String toString() {
+            return "IdentityStringPoolElement@"
+                    + Integer.toHexString(System.identityHashCode(this));
+        }
+    }
+
+    private static ChunkPos outsideLiveBounds(NativeStructureOwnershipRecord ownership,
+                                              StructureStart start) {
+        for (int chunkX = ownership.referenceMinChunkX();
+             chunkX <= ownership.referenceMaxChunkX(); chunkX++) {
+            for (int chunkZ = ownership.referenceMinChunkZ();
+                 chunkZ <= ownership.referenceMaxChunkZ(); chunkZ++) {
+                ChunkPos candidate = new ChunkPos(chunkX, chunkZ);
+                if (!start.getBoundingBox().intersects(
+                        candidate.getMinBlockX(), candidate.getMinBlockZ(),
+                        candidate.getMaxBlockX(), candidate.getMaxBlockZ())) {
+                    return candidate;
+                }
+            }
+        }
+        return null;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureOwnershipRecoveryTest.java

@@ -0,0 +1,327 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructureOwnershipRecordView;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureOwnershipRecovery;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureOwnershipFingerprint;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.placement.StructurePlacementGrid;
+import art.arcane.iris.structure.nativegen.IrisNativeStructure;
+import art.arcane.iris.structure.placement.IrisStructurePlacement;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.LegacyRandomSource;
+import net.minecraft.world.level.levelgen.RandomSupport;
+import net.minecraft.world.level.levelgen.WorldgenRandom;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureOwnershipRecoveryTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void missingSidecarRecoversExactPolicyEnvelopeAndLocatorAfterReload() {
+        long seed = 5519231L;
+        ChunkPos origin = new ChunkPos(7, -5);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureVerticalPlacer.alignOceanMonumentToSeaLevel(
+                expected, 0, 80, -64, 320);
+        int expectedLocatorY = NativeStructureOwnershipFingerprint.locatorY(expected);
+        NativeStructureStartPlan plan = plan(origin, "recovery-exact", 24);
+        StructureStart reloaded = new StructureStart(
+                structure,
+                origin,
+                expected.getReferences(),
+                OceanMonumentStructure.regeneratePiecesAfterLoad(
+                        origin, seed, new PiecesContainer(expected.getPieces()))
+        );
+
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, reloaded,
+                        plan, expected, false, NativeStructureOwnershipRecord::capture);
+
+        assertNotNull(recovered);
+        assertEquals(StructurePlacementGrid.placementIdentity(plan.placement()),
+                recovered.placementIdentity());
+        assertEquals(expectedLocatorY, recovered.locatorY());
+        assertNotEquals(NativeStructureOwnershipFingerprint.locatorY(reloaded),
+                recovered.locatorY());
+        assertEquals(StructureTerrainMode.FORCE_CARVE,
+                recovered.restoredDecision().terrain().resolvedMode());
+        assertEquals(24, recovered.restoredDecision().terrain().getHorizontalPadding());
+        assertTrue(recovered.referenceMinChunkX()
+                < NativeStructureReferenceEnvelope.contentBounds(reloaded).minX() >> 4);
+    }
+
+    @Test
+    public void naturalSameKeyStartRemainsUnownedWhenOriginIsAmbiguous() {
+        long seed = 22817L;
+        ChunkPos origin = new ChunkPos(-3, 6);
+        OceanMonumentStructure structure = structure();
+        StructureStart natural = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(origin, "natural-ambiguous", 0);
+
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, natural,
+                        plan, natural, true, NativeStructureOwnershipRecord::capture);
+
+        assertNull(recovered);
+    }
+
+    @Test
+    public void changedPlacementIdentityOrGeometryCannotRecoverOwnership() {
+        long seed = 991723L;
+        ChunkPos origin = new ChunkPos(2, 4);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        StructureStart changedGeometry = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : changedGeometry.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+        NativeStructureStartPlan originalIdentity = plan(
+                origin, "original-identity", 0);
+        NativeStructureStartPlan changedIdentity = plan(
+                new ChunkPos(origin.x() + 1, origin.z()), "changed-identity", 0);
+
+        assertNotEquals(
+                StructurePlacementGrid.placementIdentity(originalIdentity.placement()),
+                StructurePlacementGrid.placementIdentity(changedIdentity.placement()));
+        assertNull(NativeStructureOwnershipRecovery.proveCandidate(
+                "minecraft:monument", structure, expected,
+                changedIdentity, expected, false, NativeStructureOwnershipRecord::capture));
+        assertNull(NativeStructureOwnershipRecovery.proveCandidate(
+                "minecraft:monument", structure, changedGeometry,
+                plan(origin, "geometry-check", 0), expected, false, NativeStructureOwnershipRecord::capture));
+    }
+
+    @Test
+    public void recoveredEnvelopeStillRequiresExactFingerprint() {
+        long seed = 81337L;
+        ChunkPos origin = new ChunkPos(-8, -9);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureOwnershipRecord recovered =
+                NativeStructureOwnershipRecovery.proveCandidate(
+                        "minecraft:monument", structure, expected,
+                        plan(origin, "fingerprint-check", 16), expected, false, NativeStructureOwnershipRecord::capture);
+        assertNotNull(recovered);
+
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(0, 0, 1);
+        }
+
+        assertFalse(NativeStructureOwnershipFingerprint.matches(recovered, moved));
+    }
+
+    @Test
+    public void staleVacuumEnvelopeRefreshesWithoutReplacingOwnershipIdentity() {
+        String structureKey = "minecraft:monument";
+        long seed = 648231L;
+        ChunkPos origin = new ChunkPos(5, -6);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(
+                origin, "vacuum-envelope-refresh", StructureTerrainMode.VACUUM, 0);
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(start);
+        NativeStructureOwnershipRecord stale = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, content), plan);
+
+        NativeStructureOwnershipRecord refreshed =
+                NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                        structureKey, structure, start, stale);
+
+        assertNotNull(refreshed);
+        assertNotEquals(stale, refreshed);
+        assertEquals(stale.schema(), refreshed.schema());
+        assertEquals(stale.ownershipKey(), refreshed.ownershipKey());
+        assertEquals(stale.placementIdentity(), refreshed.placementIdentity());
+        assertEquals(stale.baseY(), refreshed.baseY());
+        assertEquals(stale.locatorY(), refreshed.locatorY());
+        assertEquals(stale.contentFingerprint(), refreshed.contentFingerprint());
+        assertEquals(stale.decision(), refreshed.decision());
+        assertEquals(StructureTerrainMode.VACUUM,
+                refreshed.restoredDecision().terrain().resolvedMode());
+        BoundingBox expected = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        assertEquals(expected.minX() >> 4, refreshed.referenceMinChunkX());
+        assertEquals(expected.maxX() >> 4, refreshed.referenceMaxChunkX());
+        assertEquals(expected.minZ() >> 4, refreshed.referenceMinChunkZ());
+        assertEquals(expected.maxZ() >> 4, refreshed.referenceMaxChunkZ());
+        assertTrue(hasExpandedCoverage(stale, refreshed));
+        assertSame(refreshed, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, refreshed));
+    }
+
+    @Test
+    public void staleEnvelopeCannotRefreshAgainstDifferentContent() {
+        String structureKey = "minecraft:monument";
+        long seed = 412987L;
+        ChunkPos origin = new ChunkPos(-2, 7);
+        OceanMonumentStructure structure = structure();
+        StructureStart expected = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(
+                origin, "vacuum-content-check", StructureTerrainMode.VACUUM, 0);
+        NativeStructureOwnershipRecord stale = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, expected, NativeStructureReferenceEnvelope.contentBounds(expected)), plan);
+        StructureStart moved = monumentStart(structure, origin, seed);
+        for (StructurePiece piece : moved.getPieces()) {
+            piece.move(1, 0, 0);
+        }
+
+        assertNull(NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, moved, stale));
+    }
+
+    @Test
+    public void currentNonVacuumEnvelopeRemainsThePersistedAuthority() {
+        String structureKey = "minecraft:monument";
+        long seed = 927451L;
+        ChunkPos origin = new ChunkPos(3, 8);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        NativeStructureStartPlan plan = plan(origin, "current-force-carve", 24);
+        BoundingBox envelope = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, envelope), plan);
+
+        assertSame(ownership, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, ownership));
+    }
+
+    @Test
+    public void clippedVacuumEnvelopeRemainsStableAtTheReferenceLimit() {
+        String structureKey = "minecraft:monument";
+        long seed = 381729L;
+        ChunkPos origin = new ChunkPos(0, 0);
+        OceanMonumentStructure structure = structure();
+        StructureStart start = monumentStart(structure, origin, seed);
+        BoundingBox initial = NativeStructureReferenceEnvelope.contentBounds(start);
+        int maximumReferenceBlockX = ((origin.x()
+                + StructureOwnershipRecordView.MAX_REFERENCE_DISTANCE_CHUNKS) << 4) + 15;
+        int shiftX = maximumReferenceBlockX - initial.maxX();
+        for (StructurePiece piece : start.getPieces()) {
+            piece.move(shiftX, 0, 0);
+        }
+        NativeStructureStartPlan plan = plan(
+                origin, "clipped-vacuum", StructureTerrainMode.VACUUM, 0);
+        BoundingBox envelope = NativeStructureReferenceEnvelope.referenceBounds(
+                start, structure, plan.placement().resolvedTerrain(), structureKey);
+        NativeStructureOwnershipRecord ownership = NativeStructureOwnershipRecord.capture(
+                NativeStructureOwnershipFingerprint.capture(
+                        structureKey, start, envelope), plan);
+
+        assertEquals(origin.x() + StructureOwnershipRecordView.MAX_REFERENCE_DISTANCE_CHUNKS,
+                ownership.referenceMaxChunkX());
+        assertSame(ownership, NativeStructureOwnershipRecovery.refreshReferenceEnvelope(
+                structureKey, structure, start, ownership));
+    }
+
+    private static OceanMonumentStructure structure() {
+        return new OceanMonumentStructure(
+                new OceanMonumentStructure.StructureSettings(HolderSet.empty()));
+    }
+
+    private static StructureStart monumentStart(OceanMonumentStructure structure,
+                                                 ChunkPos origin, long seed) {
+        WorldgenRandom random = new WorldgenRandom(
+                new LegacyRandomSource(RandomSupport.generateUniqueSeed()));
+        random.setLargeFeatureSeed(seed, origin.x(), origin.z());
+        Direction orientation = Direction.Plane.HORIZONTAL.getRandomDirection(random);
+        OceanMonumentPieces.MonumentBuilding building =
+                new OceanMonumentPieces.MonumentBuilding(
+                        random,
+                        origin.getMinBlockX() - 29,
+                        origin.getMinBlockZ() - 29,
+                        orientation
+                );
+        return new StructureStart(
+                structure, origin, 0, new PiecesContainer(List.of(building)));
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin,
+                                                  String placementId,
+                                                  int horizontalPadding) {
+        return plan(origin, placementId,
+                StructureTerrainMode.FORCE_CARVE, horizontalPadding);
+    }
+
+    private static NativeStructureStartPlan plan(ChunkPos origin,
+                                                  String placementId,
+                                                  StructureTerrainMode terrainMode,
+                                                  int horizontalPadding) {
+        IrisNativeStructure source = new IrisNativeStructure()
+                .setStructure("minecraft:monument")
+                .setWeight(1);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(terrainMode)
+                .setHorizontalPadding(horizontalPadding);
+        IrisStructurePlacement placement = new IrisStructurePlacement()
+                .setPlacementId(placementId)
+                .setTerrain(terrain)
+                .setNativeStructures(new KList<IrisNativeStructure>().qadd(source));
+        return new NativeStructureStartPlan(
+                placement,
+                source,
+                origin.x(),
+                origin.z(),
+                NativeStructureReferenceEnvelope.contentBounds(
+                        monumentStart(structure(), origin, 1L)).minY()
+        );
+    }
+
+    private static boolean hasExpandedCoverage(
+            NativeStructureOwnershipRecord stale,
+            NativeStructureOwnershipRecord refreshed) {
+        for (int chunkX = refreshed.referenceMinChunkX();
+             chunkX <= refreshed.referenceMaxChunkX(); chunkX++) {
+            for (int chunkZ = refreshed.referenceMinChunkZ();
+                 chunkZ <= refreshed.referenceMaxChunkZ(); chunkZ++) {
+                if (!stale.covers(chunkX, chunkZ)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorEncaseTest.java

@@ -0,0 +1,542 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructurePalette;
+
+import art.arcane.volmlib.nativelib.terrain.structure.StructureTerrainSettings;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureTerrainIntegrator;
+
+import art.arcane.iris.generation.terrain.IrisMaterialPalette;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.iris.structure.placement.IrisStructureYBand;
+import art.arcane.volmlib.util.math.RNG;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.dimension.BuiltinDimensionTypes;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockIgnoreProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.BitSet;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorEncaseTest {
+    private static final long TEST_SEED = 1234L;
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void encaseFillsAirAndLiquidWithoutOverwritingExistingTerrain() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 1, bounds.minY() - 1, bounds.minZ() - 1,
+                bounds.maxX() + 1, bounds.maxY() + 1, bounds.maxZ() + 1);
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        put(blocks, bounds.minX(), bounds.minY(), bounds.minZ(), Blocks.DIRT.defaultBlockState());
+        put(blocks, bounds.maxX(), bounds.minY(), bounds.maxZ(), Blocks.WATER.defaultBlockState());
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "minecraft:stronghold", start,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.ENCASE)
+                        .setHorizontalPadding(1)
+                        .setCeilingPadding(1)
+                        .setFloorPadding(1),
+                null);
+
+        assertEquals(Blocks.DIRT.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.maxX(), bounds.minY(), bounds.maxZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 1, bounds.minY() - 1, bounds.minZ() - 1));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.maxX() + 1, bounds.maxY() + 1, bounds.maxZ() + 1));
+    }
+
+    @Test
+    public void defaultEncasePaletteSplitsStoneAboveZeroAndDeepslateBelow() {
+        StructureStart start = start(TerrainAdjustment.BURY, -1);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), bounds, "minecraft:stronghold", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.ENCASE),
+                null);
+
+        assertEquals(-1, bounds.minY());
+        assertEquals(Blocks.DEEPSLATE.defaultBlockState(),
+                state(blocks, bounds.minX(), -1, bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), 0, bounds.minZ()));
+    }
+
+    @Test
+    public void defaultEncaseMaterialFollowsVanillaDimensionTerrain() {
+        assertEquals(Blocks.NETHERRACK.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.NETHER, 64));
+        assertEquals(Blocks.END_STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.END, 64));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(Level.OVERWORLD, 64));
+    }
+
+    @Test
+    public void sourceEncaseMaterialFollowsNearbyIrisTerrain() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(4, 64, 8);
+        put(blocks, fill.getX() + 3, fill.getY(), fill.getZ(), Blocks.TUFF.defaultBlockState());
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(world(blocks), fill));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotIgnoresPreviouslyDecoratedAdjacentChunks() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(0, 64, 8);
+        put(blocks, -1, 64, 8, Blocks.OAK_PLANKS.defaultBlockState());
+        put(blocks, 3, 64, 8, Blocks.TUFF.defaultBlockState());
+        WorldGenLevel world = world(blocks);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                sourceSnapshot(world, new BoundingBox(0, 64, 0, 15, 64, 15));
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(
+                        world, fill, sourceTerrain));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotIsStableAcrossEarlierFillsInTheSameChunk() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(0, 64, 8);
+        put(blocks, 3, 64, 8, Blocks.TUFF.defaultBlockState());
+        WorldGenLevel world = world(blocks);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                sourceSnapshot(world, new BoundingBox(0, 64, 0, 15, 64, 15));
+        put(blocks, 1, 64, 8, Blocks.OAK_PLANKS.defaultBlockState());
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(
+                        world, fill, sourceTerrain));
+    }
+
+    @Test
+    public void sourceMaterialRejectsStructureBlocksAndOresBeforeDimensionFallback() {
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        BlockPos fill = new BlockPos(4, -20, 8);
+        put(blocks, 3, -20, 8, Blocks.OAK_PLANKS.defaultBlockState());
+        put(blocks, 5, -20, 8, Blocks.STONE_BRICKS.defaultBlockState());
+        put(blocks, 4, -20, 7, Blocks.IRON_ORE.defaultBlockState());
+
+        assertEquals(Blocks.DEEPSLATE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.sourceEncaseBlock(world(blocks), fill));
+    }
+
+    @Test
+    public void sourceMaterialSnapshotOnlyAllocatesActualFillLayers() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox area = new BoundingBox(0, -2032, 0, 15, 2030, 15);
+        NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceTerrain =
+                NativeStructureTerrainIntegrator.captureSourceTerrain(
+                        world(new HashMap<>()), area,
+                        List.of(new NativeStructureTerrainIntegrator.TerrainTarget(
+                                "test:bounded-snapshot", start,
+                                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE))));
+
+        assertNotNull(sourceTerrain);
+        assertEquals(23 * 16 * 16, sourceTerrain.sampledCells());
+    }
+
+    @Test
+    public void customDimensionKeyUsesRegisteredVanillaDimensionType() {
+        ResourceKey<Level> customDimension = ResourceKey.create(
+                Registries.DIMENSION, Identifier.parse("iris:custom_nether"));
+
+        assertEquals(Blocks.NETHERRACK.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(
+                        customDimension, BuiltinDimensionTypes.NETHER, null, 64));
+        assertEquals(Blocks.END_STONE.defaultBlockState(),
+                NativeStructureTerrainIntegrator.defaultEncaseBlock(
+                        customDimension, BuiltinDimensionTypes.END, null, 64));
+    }
+
+    @Test
+    public void configuredEncasePaletteReplacesTheDefaultMaterial() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+        IrisMaterialPalette palette = new IrisMaterialPalette().qclear().qadd("minecraft:tuff");
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), bounds, "minecraft:stronghold", start,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.ENCASE)
+                        .setEncasePalette(palette),
+                NativeStructurePostProcessorEncaseTest::tuffBlock);
+
+        assertEquals(Blocks.TUFF.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.minY(), bounds.minZ()));
+    }
+
+    @Test
+    public void omittedTerrainConfigurationRetainsSourceSemantics() {
+        for (TerrainAdjustment adjustment : TerrainAdjustment.values()) {
+            StructureTerrainSettings resolved = NativeStructureTerrainIntegrator.resolveNativeTerrain(
+                    start(adjustment, 64), null);
+
+            assertEquals(StructureTerrainMode.SOURCE, resolved.resolvedMode());
+        }
+    }
+
+    @Test
+    public void sourceBuryUsesTheVanillaSixByTwelveInfluenceEnvelope() {
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        int groundY = bounds.minY();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 7, groundY - 13, bounds.minZ(),
+                bounds.maxX(), groundY + 13, bounds.maxZ());
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "test:bury", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE), null);
+
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 5, groundY, bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 11, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 6, groundY, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 12, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 7, groundY, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), groundY + 13, bounds.minZ()));
+    }
+
+    @Test
+    public void sourceEncapsulateWrapsTheFullPieceBounds() {
+        StructureStart start = start(TerrainAdjustment.ENCAPSULATE, 64);
+        BoundingBox bounds = start.getPieces().getFirst().getBoundingBox();
+        BoundingBox area = new BoundingBox(
+                bounds.minX() - 13, bounds.minY(), bounds.minZ(),
+                bounds.maxX(), bounds.maxY() + 13, bounds.maxZ());
+        Map<BlockPos, BlockState> blocks = new HashMap<>();
+
+        NativeStructureTerrainIntegrator.integrateTerrain(
+                world(blocks), area, "test:encapsulate", start,
+                new IrisStructureTerrain().setMode(StructureTerrainMode.SOURCE), null);
+
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX() - 11, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.STONE.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 11, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 12, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 12, bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX() - 13, bounds.minY(), bounds.minZ()));
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                state(blocks, bounds.minX(), bounds.maxY() + 13, bounds.minZ()));
+    }
+
+    @Test
+    public void sourceTerrainDensityOnlyUsesRigidPoolPieces() {
+        PoolElementStructurePiece terrainMatching = poolPiece(StructureTemplatePool.Projection.TERRAIN_MATCHING);
+        PoolElementStructurePiece rigid = poolPiece(StructureTemplatePool.Projection.RIGID);
+
+        assertFalse(NativeStructureTerrainIntegrator.isSourceRigidPiece(terrainMatching));
+        assertTrue(NativeStructureTerrainIntegrator.isSourceRigidPiece(rigid));
+    }
+
+    @Test
+    public void sourceJunctionTerrainUsesTheStrictLowerTwelveBlockEnvelope() {
+        assertTrue(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -1, 0));
+        assertTrue(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -11, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, 0, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(0, -12, 0));
+        assertFalse(NativeStructureTerrainIntegrator.insideSourceJunctionEnvelope(12, -1, 0));
+    }
+
+    @Test
+    public void explicitTerrainConfigurationWinsOverAutoEncase() {
+        IrisStructureTerrain configured = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.PRESERVE);
+
+        assertSame(configured, NativeStructureTerrainIntegrator.resolveNativeTerrain(
+                start(TerrainAdjustment.BURY, 64), configured));
+    }
+
+    @Test
+    public void legacyTemplateAirIsClearedAfterEveryTerrainFillPath() {
+        IrisStructureTerrain source = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.SOURCE);
+        IrisStructureTerrain preserve = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.PRESERVE);
+        IrisStructureTerrain encase = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE);
+
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BURY, 64), source));
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BEARD_BOX, 64), source));
+        assertTrue(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.NONE, 64), encase));
+        assertFalse(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.NONE, 64), source));
+        assertFalse(NativeStructureTerrainIntegrator.clearsLegacyTemplateAir(
+                start(TerrainAdjustment.BURY, 64), preserve));
+    }
+
+    @Test
+    public void encaseReservesTheNeighborChunkEnvelope() {
+        StructureStart generated = start(TerrainAdjustment.BURY, 64);
+        BoundingBox sourceBounds = generated.getBoundingBox();
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE)
+                .setHorizontalPadding(4);
+
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated,
+                generated.getStructure(),
+                0,
+                terrain);
+        BoundingBox referenceBounds = NativeStructureReferenceEnvelope.referenceBounds(
+                wrapped, wrapped.getStructure(), terrain);
+
+        assertEquals(sourceBounds, wrapped.getBoundingBox());
+        assertEquals(content.minX() - 4, referenceBounds.minX());
+        assertEquals(content.maxX() + 4, referenceBounds.maxX());
+        assertEquals(content.minZ() - 4, referenceBounds.minZ());
+        assertEquals(content.maxZ() + 4, referenceBounds.maxZ());
+        assertEquals(generated.getPieces().size(), wrapped.getPieces().size());
+    }
+
+    @Test
+    public void referenceEnvelopeRejectsChunkCoordinateOverflow() {
+        StructureStart generated = start(TerrainAdjustment.NONE, 64);
+        StructureStart extreme = new StructureStart(
+                generated.getStructure(), new ChunkPos(Integer.MAX_VALUE, 0), 0,
+                new PiecesContainer(generated.getPieces()));
+
+        assertThrows(IllegalStateException.class, () ->
+                NativeStructureReferenceEnvelope.referenceBounds(
+                        extreme, extreme.getStructure(), new IrisStructureTerrain()));
+    }
+
+    @Test
+    public void explicitTerrainEnvelopeDoesNotInheritSourceAdjustment() {
+        StructureStart generated = start(TerrainAdjustment.BURY, 64);
+        BoundingBox content = NativeStructureReferenceEnvelope.contentBounds(generated);
+        IrisStructureTerrain terrain = new IrisStructureTerrain()
+                .setMode(StructureTerrainMode.ENCASE)
+                .setHorizontalPadding(112);
+
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                generated, generated.getStructure(), 0, terrain);
+        BoundingBox referenceBounds = NativeStructureReferenceEnvelope.referenceBounds(
+                wrapped, wrapped.getStructure(), terrain);
+
+        assertEquals(content.minX() - 112, referenceBounds.minX());
+        assertEquals(content.maxX() + 112, referenceBounds.maxX());
+    }
+
+    @Test
+    public void yBandRelocatesTheStartMidpointDeterministically() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-120).setMax(-20);
+        StructureStart first = start(TerrainAdjustment.BURY, 64);
+        StructureStart second = start(TerrainAdjustment.BURY, 64);
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                first, -64, -256, 320, true, false, band, (x, z) -> 40);
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                second, -64, -256, 320, true, false, band, (x, z) -> 40);
+
+        BoundingBox bounds = first.getBoundingBox();
+        assertEquals(bounds.minY(), second.getBoundingBox().minY());
+        assertTrue(bounds.minY() >= -120);
+        assertTrue(bounds.maxY() <= -20);
+
+        int repeated = NativeStructureVerticalPlacer.applyVerticalShift(
+                first, -64, -256, 320, true, false, band, (x, z) -> 40);
+        assertEquals(0, repeated);
+    }
+
+    @Test
+    public void yBandClampsWhenTheBandCannotContainTheStructure() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-50).setMax(-45);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                start, 0, -256, 320, true, false, band, (x, z) -> 40);
+
+        BoundingBox bounds = start.getBoundingBox();
+        int midpoint = bounds.minY() + (bounds.maxY() - bounds.minY()) / 2;
+        assertTrue(midpoint >= -50);
+        assertTrue(midpoint <= -45);
+    }
+
+    @Test
+    public void yBandReplacesBothTheBlindShiftAndBurial() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-64).setMax(-64);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        BoundingBox bounds = start.getBoundingBox();
+        int height = bounds.maxY() - bounds.minY();
+
+        NativeStructureVerticalPlacer.applyVerticalShift(
+                start, -200, -256, 320, true, false, band, (x, z) -> 40);
+
+        assertEquals(-64 - height / 2, start.getBoundingBox().minY());
+    }
+
+    @Test
+    public void preserveSourceYWinsOverTheConfiguredBand() {
+        IrisStructureYBand band = new IrisStructureYBand().setMin(-120).setMax(-20);
+        StructureStart start = start(TerrainAdjustment.BURY, 64);
+        int minY = start.getBoundingBox().minY();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalShift(
+                start, 0, -256, 320, true, true, band, (x, z) -> 40);
+
+        assertEquals(0, offset);
+        assertEquals(minY, start.getBoundingBox().minY());
+    }
+
+    private static BlockState tuffBlock(StructurePalette palette, RNG rng, int x, int y, int z) {
+        assertNotNull(palette);
+        assertNotNull(rng);
+        return Blocks.TUFF.defaultBlockState();
+    }
+
+    private static StructureStart start(TerrainAdjustment adjustment, int minY) {
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(
+                HolderSet.empty(), Map.of(), GenerationStep.Decoration.STRONGHOLDS, adjustment));
+        StructurePiece piece = new DesertPyramidPiece(RandomSource.create(7L), 0, 0);
+        piece.move(0, minY - piece.getBoundingBox().minY(), 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static PoolElementStructurePiece poolPiece(StructureTemplatePool.Projection projection) {
+        BlockPos position = new BlockPos(0, 64, 0);
+        StructurePoolElement element = StructurePoolElement.single(
+                "minecraft:empty",
+                Holder.direct(new StructureProcessorList(List.of(
+                        BlockIgnoreProcessor.STRUCTURE_AND_AIR))),
+                LiquidSettings.APPLY_WATERLOGGING
+        ).apply(projection);
+        return new PoolElementStructurePiece(
+                null,
+                element,
+                position,
+                0,
+                Rotation.NONE,
+                new BoundingBox(position),
+                LiquidSettings.APPLY_WATERLOGGING);
+    }
+
+    private static WorldGenLevel world(Map<BlockPos, BlockState> blocks) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getBlockState")) {
+                BlockPos position = (BlockPos) arguments[0];
+                return state(blocks, position.getX(), position.getY(), position.getZ());
+            }
+            if (methodName.equals("setBlock")) {
+                BlockPos position = (BlockPos) arguments[0];
+                BlockState blockState = (BlockState) arguments[1];
+                put(blocks, position.getX(), position.getY(), position.getZ(), blockState);
+                return true;
+            }
+            if (methodName.equals("getSeed")) {
+                return TEST_SEED;
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "encase-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static NativeStructureTerrainIntegrator.SourceTerrainSnapshot sourceSnapshot(
+            WorldGenLevel world, BoundingBox area) {
+        BitSet requiredLayers = new BitSet(area.getYSpan());
+        requiredLayers.set(0, area.getYSpan());
+        return NativeStructureTerrainIntegrator.SourceTerrainSnapshot.capture(
+                world, area, requiredLayers);
+    }
+
+    private static void put(Map<BlockPos, BlockState> blocks,
+                           int x, int y, int z, BlockState state) {
+        blocks.put(new BlockPos(x, y, z), state);
+    }
+
+    private static BlockState state(Map<BlockPos, BlockState> blocks, int x, int y, int z) {
+        return blocks.getOrDefault(new BlockPos(x, y, z), Blocks.AIR.defaultBlockState());
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorMonumentTest.java

@@ -0,0 +1,206 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReferenceEnvelope;
+
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentPieces;
+import net.minecraft.world.level.levelgen.structure.structures.OceanMonumentStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorMonumentTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void vanillaSeaLevelKeepsTheVanillaMonumentHeight() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 63, -64, 320, false, false, null, (x, z) -> 0);
+
+        assertEquals(0, offset);
+        assertEquals(39, start.getBoundingBox().minY());
+        assertEquals(61, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void shiftedSeaLevelMovesTheShellAndEveryRoomTogether() {
+        StructureStart start = monumentStart(1337L);
+        OceanMonumentPieces.MonumentBuilding building = monumentBuilding(start);
+        List<StructurePiece> children = NativeStructureVerticalPlacer.monumentChildPieces(building);
+        int[] childMinY = minimumYs(children);
+        BoundingBox cachedBounds = start.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        assertEquals(-13, offset);
+        assertSame(cachedBounds, start.getBoundingBox());
+        assertEquals(26, building.getBoundingBox().minY());
+        assertEquals(48, building.getBoundingBox().maxY());
+        assertEquals(26, start.getBoundingBox().minY());
+        assertEquals(48, start.getBoundingBox().maxY());
+        assertTrue(children.size() > 20);
+        for (int i = 0; i < children.size(); i++) {
+            assertEquals(childMinY[i] - 13, children.get(i).getBoundingBox().minY());
+        }
+
+        int repeatedOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+        assertEquals(0, repeatedOffset);
+    }
+
+    @Test
+    public void configuredOffsetIsRelativeToTheActualSeaLevel() {
+        StructureStart start = monumentStart(1337L);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:monument", 3, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        assertEquals(-10, offset);
+        assertEquals(29, start.getBoundingBox().minY());
+        assertEquals(51, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void referenceEnvelopeDoesNotAddMonumentPieces() {
+        StructureStart start = monumentStart(1337L);
+        StructureStart wrapped = NativeStructureReferenceEnvelope.wrap(
+                start,
+                start.getStructure(),
+                0,
+                new IrisStructureTerrain()
+                        .setMode(StructureTerrainMode.FORCE_CARVE)
+                        .setHorizontalPadding(4));
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                wrapped, "minecraft:monument", 0, 63, -64, 320,
+                false, false, null, (x, z) -> 0);
+
+        assertEquals(0, offset);
+        assertEquals(1, wrapped.getPieces().size());
+    }
+
+    @Test
+    public void vanillaReloadRegenerationIsRealignedBeforePlacement() {
+        long seed = 1337L;
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        StructureStart initial = monumentStart(seed);
+        NativeStructureVerticalPlacer.applyVerticalPlacement(
+                initial, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+
+        PiecesContainer regenerated = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                chunkPos, seed, new PiecesContainer(initial.getPieces()));
+        StructureStart reloaded = new StructureStart(
+                monumentStructure(), chunkPos, 0, regenerated);
+
+        assertEquals(39, reloaded.getBoundingBox().minY());
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                reloaded, "minecraft:monument", 0, 50, -256, 512, false, false, null, (x, z) -> 0);
+        assertEquals(-13, offset);
+        assertEquals(26, reloaded.getBoundingBox().minY());
+        assertEquals(48, reloaded.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void neighboringChunkPlacementRealignsReloadedMonumentOnce() throws Exception {
+        long seed = 1337L;
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        StructureStart initial = monumentStart(seed);
+        NativeStructureVerticalPlacer.applyVerticalPlacement(
+                initial, "minecraft:monument", 0, 50, -256, 512,
+                false, false, null, (x, z) -> 0);
+        PiecesContainer regenerated = OceanMonumentStructure.regeneratePiecesAfterLoad(
+                chunkPos, seed, new PiecesContainer(initial.getPieces()));
+        StructureStart reloaded = new StructureStart(
+                monumentStructure(), chunkPos, 0, regenerated);
+        ExecutorService executor = Executors.newFixedThreadPool(8);
+        CountDownLatch release = new CountDownLatch(1);
+        List<Future<?>> futures = new ArrayList<>();
+        try {
+            for (int task = 0; task < 16; task++) {
+                futures.add(executor.submit(() -> {
+                    release.await();
+                    NativeStructureVerticalPlacer.ensureMonumentSeaLevelAlignment(
+                            reloaded, "minecraft:monument", 0, 50, -256, 512);
+                    return null;
+                }));
+            }
+            release.countDown();
+            for (Future<?> future : futures) {
+                future.get();
+            }
+        } finally {
+            executor.shutdownNow();
+        }
+
+        assertEquals(26, reloaded.getBoundingBox().minY());
+        assertEquals(48, reloaded.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void impossibleSeaLevelAlignmentFailsInsteadOfClippingTheMonument() {
+        StructureStart start = monumentStart(1337L);
+        try {
+            NativeStructureVerticalPlacer.applyVerticalPlacement(
+                    start, "minecraft:monument", 0, -50, -64, 320, false, false, null, (x, z) -> 0);
+        } catch (IllegalStateException error) {
+            assertTrue(error.getMessage().contains("cannot align"));
+            return;
+        }
+        throw new AssertionError("Expected an out-of-bounds monument alignment to fail");
+    }
+
+    private static StructureStart monumentStart(long seed) {
+        ChunkPos chunkPos = new ChunkPos(0, 0);
+        OceanMonumentPieces.MonumentBuilding building = new OceanMonumentPieces.MonumentBuilding(
+                RandomSource.create(seed), -29, -29, Direction.NORTH);
+        return new StructureStart(
+                monumentStructure(), chunkPos, 0, new PiecesContainer(List.of(building)));
+    }
+
+    private static OceanMonumentStructure monumentStructure() {
+        return new OceanMonumentStructure(new Structure.StructureSettings(HolderSet.empty()));
+    }
+
+    private static OceanMonumentPieces.MonumentBuilding monumentBuilding(StructureStart start) {
+        return (OceanMonumentPieces.MonumentBuilding) start.getPieces().get(0);
+    }
+
+    private static int[] minimumYs(List<StructurePiece> pieces) {
+        int[] ys = new int[pieces.size()];
+        for (int i = 0; i < pieces.size(); i++) {
+            ys[i] = pieces.get(i).getBoundingBox().minY();
+        }
+        return ys;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorScatteredFeatureTest.java

@@ -0,0 +1,204 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureSurfaceFitter;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReflection;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelAccessor;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.ScatteredFeaturePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructurePiece;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.structures.JungleTemplePiece;
+import net.minecraft.world.level.levelgen.structure.structures.JungleTempleStructure;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorScatteredFeatureTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void desertPyramidUsesTheLowestFootprintSurfaceAndLocksVanillaReanchor() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(11L), 0, 0);
+        StructureStart start = desertStart(piece);
+        BoundingBox cachedBounds = start.getBoundingBox();
+        BoundingBox footprint = piece.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null,
+                (x, z) -> x == footprint.maxX() && z == footprint.maxZ() ? 64 : 92);
+
+        assertEquals(1, offset);
+        assertSame(cachedBounds, start.getBoundingBox());
+        assertEquals(65, piece.getBoundingBox().minY());
+        assertEquals(65, start.getBoundingBox().minY());
+        assertTrue(piece.attemptVanillaAlignment(-2));
+        assertEquals(65, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void jungleTempleUsesAverageFootprintSurfaceAndHonorsConfiguredShift() {
+        TestJungleTemplePiece piece = new TestJungleTemplePiece(RandomSource.create(19L), 32, -16);
+        StructureStart start = jungleStart(piece);
+        BoundingBox footprint = piece.getBoundingBox();
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:jungle_pyramid", 4, 63, -64, 320, false, false, null,
+                (x, z) -> x == footprint.minX() && z == footprint.minZ() ? 88 : 70);
+
+        assertEquals(11, offset);
+        assertEquals(75, piece.getBoundingBox().minY());
+        assertTrue(piece.attemptVanillaAlignment());
+        assertEquals(75, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void repeatedAlignmentIsIdempotent() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(23L), 0, 0);
+        StructureStart start = desertStart(piece);
+
+        int initialOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 80);
+        int repeatedOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 80);
+
+        assertEquals(17, initialOffset);
+        assertEquals(0, repeatedOffset);
+        assertEquals(81, piece.getBoundingBox().minY());
+    }
+
+    @Test
+    public void scatteredAlignmentStaysInsideWorldBounds() {
+        TestDesertPyramidPiece piece = new TestDesertPyramidPiece(RandomSource.create(29L), 0, 0);
+        StructureStart start = desertStart(piece);
+
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                start, "minecraft:desert_pyramid", 0, 63, -64, 320, false, false, null, (x, z) -> 318);
+
+        assertEquals(241, offset);
+        assertEquals(305, piece.getBoundingBox().minY());
+        assertEquals(319, start.getBoundingBox().maxY());
+    }
+
+    @Test
+    public void scatteredStructuresDoNotOptIntoFullFootprintSurfaceFitting() {
+        TestDesertPyramidPiece desert = new TestDesertPyramidPiece(RandomSource.create(31L), 0, 0);
+        TestJungleTemplePiece jungle = new TestJungleTemplePiece(RandomSource.create(37L), 0, 0);
+        SwampHutPiece swamp = new SwampHutPiece(RandomSource.create(41L), 0, 0);
+        StructureStart desertStart = desertStart(desert);
+        StructureStart jungleStart = jungleStart(jungle);
+        StructureStart swampStart = swampStart(swamp);
+
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(desertStart));
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(jungleStart));
+        assertFalse(NativeStructureSurfaceFitter.requiresSurfaceTerrain(swampStart));
+
+        AtomicInteger terrainQueries = new AtomicInteger();
+        int offset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                swampStart, "minecraft:swamp_hut", 0, 63, -64, 320, false, false, null,
+                (x, z) -> terrainQueries.incrementAndGet());
+        assertEquals(0, offset);
+        assertEquals(0, terrainQueries.get());
+        assertEquals(64, swamp.getBoundingBox().minY());
+    }
+
+    @Test
+    public void scatteredHeightFieldMatchesTheRuntimeContract() {
+        Field field = NativeStructureReflection.resolveScatteredHeightPositionField();
+
+        assertEquals(ScatteredFeaturePiece.class, field.getDeclaringClass());
+        assertEquals(int.class, field.getType());
+        assertTrue(Modifier.isProtected(field.getModifiers()));
+        assertFalse(Modifier.isFinal(field.getModifiers()));
+        assertFalse(Modifier.isStatic(field.getModifiers()));
+        assertTrue(field.trySetAccessible());
+    }
+
+    @Test
+    public void datapackOverridesOfSpecialVanillaIdsUseGenericPlacement() {
+        StructureStart pyramidOverride = swampStart(
+                new SwampHutPiece(RandomSource.create(43L), 0, 0));
+        int pyramidMinY = pyramidOverride.getBoundingBox().minY();
+        int pyramidOffset = NativeStructureVerticalPlacer.applyVerticalPlacement(
+                pyramidOverride, "minecraft:desert_pyramid", 5,
+                63, -64, 320, false, false, null, (x, z) -> 200);
+
+        assertEquals(5, pyramidOffset);
+        assertEquals(pyramidMinY + 5, pyramidOverride.getBoundingBox().minY());
+
+        StructureStart monumentOverride = swampStart(
+                new SwampHutPiece(RandomSource.create(47L), 0, 0));
+        int monumentMinY = monumentOverride.getBoundingBox().minY();
+        NativeStructureVerticalPlacer.ensureMonumentSeaLevelAlignment(
+                monumentOverride, "minecraft:monument", 0, 40, -64, 320);
+
+        assertEquals(monumentMinY, monumentOverride.getBoundingBox().minY());
+    }
+
+    private static StructureStart desertStart(StructurePiece piece) {
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart jungleStart(StructurePiece piece) {
+        Structure structure = new JungleTempleStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart swampStart(StructurePiece piece) {
+        Structure structure = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        return start(structure, piece);
+    }
+
+    private static StructureStart start(Structure structure, StructurePiece piece) {
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static final class TestDesertPyramidPiece extends DesertPyramidPiece {
+        private TestDesertPyramidPiece(RandomSource random, int west, int north) {
+            super(random, west, north);
+        }
+
+        private boolean attemptVanillaAlignment(int offset) {
+            return updateHeightPositionToLowestGroundHeight((LevelAccessor) null, offset);
+        }
+    }
+
+    private static final class TestJungleTemplePiece extends JungleTemplePiece {
+        private TestJungleTemplePiece(RandomSource random, int west, int north) {
+            super(random, west, north);
+        }
+
+        private boolean attemptVanillaAlignment() {
+            return updateAverageGroundHeight((LevelAccessor) null, null, 0);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructurePostProcessorVegetationTest.java

@@ -0,0 +1,388 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVerticalPlacer;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureSurfaceFitter;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureVegetationClearer;
+
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.IdMapper;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidPiece;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructurePostProcessorVegetationTest {
+    private static final long TEST_SEED = 1234L;
+    private static final int MIN_Y = -64;
+    private static final int MAX_Y = 319;
+    private static final int GROUND_Y = 64;
+    private static final BoundingBox AREA = new BoundingBox(0, MIN_Y, 0, 15, MAX_Y, 15);
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void canopyAboveTheStructureRoofSurvivesVegetationClearing() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        for (int y = bounds.maxY() - 1; y <= GROUND_Y + 40; y++) {
+            fillLayer(chunk, y, leaves());
+        }
+        write(chunk, 4, bounds.minY() - 1, 4, log());
+
+        clearVegetation(chunk, start);
+
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                assertEquals(leaves(), chunk.getBlockState(new BlockPos(x, GROUND_Y + 40, z)));
+                assertEquals(leaves(), chunk.getBlockState(new BlockPos(x, bounds.maxY() + 1, z)));
+                assertEquals(air(), chunk.getBlockState(new BlockPos(x, bounds.maxY(), z)));
+                assertEquals(air(), chunk.getBlockState(new BlockPos(x, bounds.maxY() - 1, z)));
+            }
+        }
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 1, 4)));
+    }
+
+    @Test
+    public void buriedStructuresPreserveTheForestAboveThem() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, -20);
+        write(chunk, 8, GROUND_Y + 1, 8, log());
+        write(chunk, 8, GROUND_Y + 2, 8, log());
+        write(chunk, 8, GROUND_Y + 3, 8, log());
+        write(chunk, 8, GROUND_Y + 4, 8, leaves());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 1, 8)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 2, 8)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 3, 8)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(8, GROUND_Y + 4, 8)));
+    }
+
+    @Test
+    public void columnsOutsideThePieceFootprintKeepEveryTreeBlock() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(8, 8, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        int inside = bounds.minY() + 4;
+        write(chunk, 0, inside, 0, log());
+        write(chunk, 0, GROUND_Y + 40, 0, leaves());
+        write(chunk, 12, inside, 12, log());
+        write(chunk, 12, GROUND_Y + 40, 12, leaves());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(0, inside, 0)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(0, GROUND_Y + 40, 0)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(12, inside, 12)));
+        assertEquals(leaves(), chunk.getBlockState(new BlockPos(12, GROUND_Y + 40, 12)));
+    }
+
+    @Test
+    public void clearingStopsAtThePieceEnvelopeBoundaries() {
+        ProtoChunk chunk = chunk();
+        StructureStart start = desertStart(0, 0, GROUND_Y + 15);
+        BoundingBox bounds = start.getBoundingBox();
+        write(chunk, 4, bounds.maxY() + 1, 4, log());
+        write(chunk, 4, bounds.maxY(), 4, log());
+        write(chunk, 4, bounds.minY() - 1, 4, log());
+        write(chunk, 4, bounds.minY() - 2, 4, log());
+
+        clearVegetation(chunk, start);
+
+        assertEquals(log(), chunk.getBlockState(new BlockPos(4, bounds.maxY() + 1, 4)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.maxY(), 4)));
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 1, 4)));
+        assertEquals(log(), chunk.getBlockState(new BlockPos(4, bounds.minY() - 2, 4)));
+    }
+
+    @Test
+    public void overlappingPieceEnvelopesMergeIntoOneClearedRange() {
+        ProtoChunk chunk = chunk();
+        StructureStart low = desertStart(0, 0, GROUND_Y);
+        StructureStart high = desertStart(0, 0, GROUND_Y + 40);
+        int between = GROUND_Y + 20;
+        write(chunk, 4, between, 4, log());
+        write(chunk, 4, high.getBoundingBox().maxY() + 1, 4, log());
+        write(chunk, 4, low.getBoundingBox().minY() - 2, 4, log());
+
+        NativeStructureVegetationClearer.clearIntersectingVegetation(
+                world(chunk), chunk, AREA, List.of(low, high));
+
+        assertEquals(air(), chunk.getBlockState(new BlockPos(4, between, 4)));
+        assertEquals(log(), chunk.getBlockState(
+                new BlockPos(4, high.getBoundingBox().maxY() + 1, 4)));
+        assertEquals(log(), chunk.getBlockState(
+                new BlockPos(4, low.getBoundingBox().minY() - 2, 4)));
+    }
+
+    @Test
+    public void validStartsReachIntersectionProcessing() {
+        assertTrue(NativeStructureVegetationClearer.shouldProcessStart(
+                desertStart(0, 0, GROUND_Y + 15)));
+        assertFalse(NativeStructureVegetationClearer.shouldProcessStart(
+                StructureStart.INVALID_START));
+    }
+
+    @Test
+    public void allUndergroundGenerationStepsShareOneClassification() {
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.UNDERGROUND_STRUCTURES));
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.UNDERGROUND_DECORATION));
+        assertTrue(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.STRONGHOLDS));
+        assertFalse(NativeStructureVegetationClearer.isUndergroundStep(
+                GenerationStep.Decoration.SURFACE_STRUCTURES));
+    }
+
+    @Test
+    public void undergroundStructuresUseTheLowestTerrainColumn() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        int offset = NativeStructureVerticalPlacer.resolveBuriedOffset(
+                bounds, 0, -64, 320, (x, z) -> x == 1 ? 76 : 100);
+        assertEquals(-5, offset);
+    }
+
+    @Test
+    public void undergroundBurialClampsToTheWorldFloorInsteadOfFailing() {
+        BoundingBox bounds = new BoundingBox(0, 60, 0, 1, 80, 0);
+        assertEquals(-2, NativeStructureVerticalPlacer.resolveBuriedOffset(
+                bounds, 0, 58, 320, (x, z) -> x == 1 ? 76 : 100));
+    }
+
+    @Test
+    public void loweringSurfaceRemovesCactusStacksAndTheirFlowers() {
+        ProtoChunk chunk = chunk();
+        for (int y = 80; y <= 102; y++) {
+            write(chunk, 4, y, 4, Blocks.SAND.defaultBlockState());
+        }
+        for (int y = 103; y <= 105; y++) {
+            write(chunk, 4, y, 4, Blocks.CACTUS.defaultBlockState());
+        }
+        write(chunk, 4, 106, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world(chunk), new BlockPos.MutableBlockPos(), 4, 4, 102, 93, MIN_Y, MAX_Y);
+
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 93, 4)));
+        for (int y = 94; y <= 106; y++) {
+            assertTrue("Unsupported decoration at " + y, chunk.getBlockState(new BlockPos(4, y, 4)).isAir());
+        }
+    }
+
+    @Test
+    public void loweringSurfacePreservesCactusOnUnchangedColumns() {
+        ProtoChunk chunk = chunk();
+        for (int x : List.of(4, 5)) {
+            for (int y = 60; y <= 64; y++) {
+                write(chunk, x, y, 4, Blocks.SAND.defaultBlockState());
+            }
+            write(chunk, x, 65, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, x, 66, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+        }
+        WorldGenLevel world = world(chunk);
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 5, 4, 64, 64, MIN_Y, MAX_Y);
+
+        assertTrue(chunk.getBlockState(new BlockPos(4, 65, 4)).isAir());
+        assertTrue(chunk.getBlockState(new BlockPos(4, 66, 4)).isAir());
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 64, 4)));
+        assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 65, 4)));
+        assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 66, 4)));
+    }
+
+    @Test
+    public void loweringSurfaceKeepsTreeBoundaries() {
+        for (BlockState boundary : List.of(Blocks.OAK_LOG.defaultBlockState(), Blocks.OAK_LEAVES.defaultBlockState())) {
+            ProtoChunk chunk = chunk();
+            write(chunk, 4, 63, 4, Blocks.SAND.defaultBlockState());
+            write(chunk, 4, 64, 4, Blocks.SAND.defaultBlockState());
+            write(chunk, 4, 65, 4, boundary);
+            write(chunk, 4, 66, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, 4, 67, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+
+            NativeStructureSurfaceFitter.applySurfaceColumn(
+                    world(chunk), new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+
+            assertEquals(boundary, chunk.getBlockState(new BlockPos(4, 65, 4)));
+            assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 66, 4)));
+            assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 67, 4)));
+        }
+    }
+
+    @Test
+    public void loweringSurfaceRemovesUnsupportedPlankDecoration() {
+        ProtoChunk chunk = chunk();
+        for (int x : List.of(4, 5)) {
+            for (int y = 60; y <= 64; y++) {
+                write(chunk, x, y, 4, Blocks.SAND.defaultBlockState());
+            }
+            write(chunk, x, 65, 4, Blocks.OAK_PLANKS.defaultBlockState());
+            write(chunk, x, 66, 4, Blocks.CACTUS.defaultBlockState());
+            write(chunk, x, 67, 4, Blocks.CACTUS_FLOWER.defaultBlockState());
+        }
+        WorldGenLevel world = world(chunk);
+
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 4, 4, 64, 60, MIN_Y, MAX_Y);
+        NativeStructureSurfaceFitter.applySurfaceColumn(
+                world, new BlockPos.MutableBlockPos(), 5, 4, 64, 64, MIN_Y, MAX_Y);
+
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(4, 60, 4)));
+        for (int y = 61; y <= 67; y++) {
+            assertTrue(chunk.getBlockState(new BlockPos(4, y, 4)).isAir());
+        }
+        assertEquals(Blocks.SAND.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 64, 4)));
+        assertEquals(Blocks.OAK_PLANKS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 65, 4)));
+        assertEquals(Blocks.CACTUS.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 66, 4)));
+        assertEquals(Blocks.CACTUS_FLOWER.defaultBlockState(), chunk.getBlockState(new BlockPos(5, 67, 4)));
+    }
+
+    private static void clearVegetation(ProtoChunk chunk, StructureStart start) {
+        NativeStructureVegetationClearer.clearIntersectingVegetation(
+                world(chunk), chunk, AREA, List.of(start));
+    }
+
+    private static StructureStart desertStart(int originX, int originZ, int topY) {
+        Structure structure = new DesertPyramidStructure(
+                new Structure.StructureSettings(
+                        HolderSet.empty(), Map.of(),
+                        GenerationStep.Decoration.SURFACE_STRUCTURES, TerrainAdjustment.NONE));
+        DesertPyramidPiece piece = new DesertPyramidPiece(RandomSource.create(7L), originX, originZ);
+        piece.move(0, topY - piece.getBoundingBox().maxY(), 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static ProtoChunk chunk() {
+        return new ProtoChunk(
+                new ChunkPos(0, 0), UpgradeData.EMPTY,
+                LevelHeightAccessor.create(MIN_Y, MAX_Y - MIN_Y + 1), containerFactory(), null);
+    }
+
+    private static void fillLayer(ProtoChunk chunk, int y, BlockState state) {
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                write(chunk, x, y, z, state);
+            }
+        }
+    }
+
+    private static void write(ProtoChunk chunk, int x, int y, int z, BlockState state) {
+        LevelChunkSection section = chunk.getSection(chunk.getSectionIndex(y));
+        section.setBlockState(x, y & 15, z, state, false);
+    }
+
+    private static BlockState log() {
+        return Blocks.OAK_LOG.defaultBlockState();
+    }
+
+    private static BlockState leaves() {
+        return Blocks.OAK_LEAVES.defaultBlockState();
+    }
+
+    private static BlockState air() {
+        return Blocks.AIR.defaultBlockState();
+    }
+
+    private static WorldGenLevel world(ChunkAccess chunk) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getBlockState")) {
+                return chunk.getBlockState((BlockPos) arguments[0]);
+            }
+            if (methodName.equals("setBlock")) {
+                return chunk.setBlockState(
+                        ((BlockPos) arguments[0]).immutable(),
+                        (BlockState) arguments[1], (int) arguments[2]) != null;
+            }
+            if (methodName.equals("getSeed")) {
+                return TEST_SEED;
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("holderLookup")) {
+                return BuiltInRegistries.BLOCK;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "vegetation-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blockStates = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> defaultBiome = Holder.direct((Biome) null);
+        biomeIds.add(defaultBiome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(
+                name -> defaultBiome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(
+                blockStates,
+                air,
+                PalettedContainer.codecRW(BlockState.CODEC, blockStates, air),
+                biomes,
+                defaultBiome,
+                PalettedContainer.codecRO(biomeCodec, biomes, defaultBiome),
+                PalettedContainer.codecRW(biomeCodec, biomes, defaultBiome));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeStructureTemplateOccupancyTest.java

@@ -0,0 +1,240 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureTemplateOccupancy;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureReflection;
+
+import com.mojang.datafixers.util.Either;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.tags.TagKey;
+import net.minecraft.util.valueproviders.ConstantInt;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.pools.SinglePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlackstoneReplaceProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockAgeProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.BlockIgnoreProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.CappedProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.GravityProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.JigsawReplacementProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LavaSubmergedBlockProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.NopProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.ProtectedBlockProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.RuleProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureProcessorList;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import org.junit.Assume;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.TreeSet;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureTemplateOccupancyTest {
+    private static final BoundingBox PROCESSING_AREA = new BoundingBox(0, 56, 0, 15, 80, 0);
+    private static final int TEMPLATE_WIDTH = 32;
+    private static final int TERRAIN_HEIGHT = 64;
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void straddlingGravityPieceHeightReadsHonorTheVanillaClipContract() throws Exception {
+        ColumnRecorder recorder = new ColumnRecorder();
+
+        resolve(straddlingPiece(
+                List.of(new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0))), recorder);
+
+        // 26.2 vanilla clips processor evaluation to the placement bounding box; 26.1.2 vanilla
+        // runs processors across the whole piece. Iris mirrors the pinned version's semantics.
+        assertEquals(expectedClippedColumns(), recorder.heightColumns);
+    }
+
+    @Test
+    public void cappedStraddlingPieceRunsProcessorsAcrossTheWholePiece() throws Exception {
+        ColumnRecorder recorder = new ColumnRecorder();
+
+        resolve(straddlingPiece(List.of(
+                new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0),
+                new CappedProcessor(NopProcessor.INSTANCE, ConstantInt.of(0)))), recorder);
+
+        assertEquals(columns(0, TEMPLATE_WIDTH - 1), recorder.heightColumns);
+    }
+
+    @Test
+    public void cappedProcessorIsTheOnlyProcessorThatDisablesTheProcessingAreaClip() throws Exception {
+        Method contract = clipContractMethod();
+        Assume.assumeTrue("evaluatesEntirePieceState only exists on 26.2+", contract != null);
+
+        for (StructureProcessor processor : List.of(
+                BlockIgnoreProcessor.STRUCTURE_BLOCK,
+                JigsawReplacementProcessor.INSTANCE,
+                LavaSubmergedBlockProcessor.INSTANCE,
+                NopProcessor.INSTANCE,
+                BlackstoneReplaceProcessor.INSTANCE,
+                new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, 0),
+                new RuleProcessor(List.of()),
+                new BlockAgeProcessor(0.5F),
+                protectedBlockProcessor())) {
+            assertFalse(processor.getClass().getName(),
+                    (Boolean) contract.invoke(processor));
+        }
+        assertTrue((Boolean) contract.invoke(
+                new CappedProcessor(NopProcessor.INSTANCE, ConstantInt.of(4))));
+    }
+
+    @Test
+    public void placementSettingsCarryTheProcessingAreaAsTheirClipBox() throws Exception {
+        PoolElementStructurePiece piece = straddlingPiece(List.of());
+
+        StructurePlaceSettings settings = NativeStructureReflection.resolvePlacementSettings(
+                (SinglePoolElement) piece.getElement(), piece, PROCESSING_AREA);
+
+        assertEquals(PROCESSING_AREA, settings.getBoundingBox());
+    }
+
+    private static void resolve(PoolElementStructurePiece piece, ColumnRecorder recorder) {
+        NativeStructureTemplateOccupancy.resolve(
+                world(recorder), piece, piece.getPosition(), PROCESSING_AREA,
+                NativeStructureTemplateOccupancyTest::forbiddenTemplateManager,
+                PROCESSING_AREA::isInside, amount -> {
+                });
+    }
+
+    private static PoolElementStructurePiece straddlingPiece(
+            List<StructureProcessor> processors) throws Exception {
+        BoundingBox bounds = new BoundingBox(0, 70, 0, TEMPLATE_WIDTH - 1, 76, 0);
+        return new PoolElementStructurePiece(
+                null, new InlineSinglePoolElement(template(), processors),
+                new BlockPos(bounds.minX(), bounds.minY(), bounds.minZ()),
+                1, Rotation.NONE, bounds, LiquidSettings.APPLY_WATERLOGGING);
+    }
+
+    private static Set<Integer> columns(int minimumX, int maximumX) {
+        Set<Integer> columns = new TreeSet<>();
+        for (int x = minimumX; x <= maximumX; x++) {
+            columns.add(x);
+        }
+        return columns;
+    }
+
+    private static Method clipContractMethod() {
+        try {
+            return StructureProcessor.class.getMethod("evaluatesEntirePieceState");
+        } catch (NoSuchMethodException absent) {
+            return null;
+        }
+    }
+
+    private static Set<Integer> expectedClippedColumns() {
+        return clipContractMethod() != null
+                ? columns(PROCESSING_AREA.minX(), PROCESSING_AREA.maxX())
+                : columns(0, TEMPLATE_WIDTH - 1);
+    }
+
+    private static StructureProcessor protectedBlockProcessor() throws Exception {
+        // Constructed reflectively: the constructor takes HolderSet on 26.2 and TagKey on 26.1.2.
+        Constructor<?> constructor = ProtectedBlockProcessor.class.getConstructors()[0];
+        Class<?> parameter = constructor.getParameterTypes()[0];
+        Object argument = parameter == HolderSet.class
+                ? HolderSet.empty()
+                : TagKey.create(Registries.BLOCK, Identifier.fromNamespaceAndPath("minecraft", "air"));
+        return (StructureProcessor) constructor.newInstance(argument);
+    }
+
+    private static StructureTemplateManager forbiddenTemplateManager() {
+        throw new AssertionError("Inline templates must not resolve a template manager");
+    }
+
+    private static StructureTemplate template() throws Exception {
+        List<StructureTemplate.StructureBlockInfo> blocks = new ArrayList<>();
+        for (int x = 0; x < TEMPLATE_WIDTH; x++) {
+            blocks.add(new StructureTemplate.StructureBlockInfo(
+                    new BlockPos(x, 0, 0), Blocks.COBBLESTONE.defaultBlockState(), null));
+        }
+        Constructor<StructureTemplate.Palette> constructor =
+                StructureTemplate.Palette.class.getDeclaredConstructor(List.class);
+        assertTrue(constructor.trySetAccessible());
+        StructureTemplate template = new StructureTemplate();
+        template.palettes.add(constructor.newInstance(blocks));
+        return template;
+    }
+
+    private static WorldGenLevel world(ColumnRecorder recorder) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("getHeight") && arguments.length == 3) {
+                recorder.heightColumns.add((Integer) arguments[1]);
+                return TERRAIN_HEIGHT;
+            }
+            if (methodName.equals("getBlockState")) {
+                recorder.stateColumns.add(((BlockPos) arguments[0]).getX());
+                return Blocks.STONE.defaultBlockState();
+            }
+            if (methodName.equals("getLevel")) {
+                return null;
+            }
+            if (methodName.equals("holderLookup")) {
+                return BuiltInRegistries.BLOCK;
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "occupancy-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(),
+                new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+
+    private static final class ColumnRecorder {
+        private final Set<Integer> heightColumns = new TreeSet<>();
+        private final Set<Integer> stateColumns = new TreeSet<>();
+    }
+
+    private static final class InlineSinglePoolElement extends SinglePoolElement {
+        private InlineSinglePoolElement(
+                StructureTemplate template, List<StructureProcessor> processors) {
+            super(Either.right(template),
+                    Holder.direct(new StructureProcessorList(processors)),
+                    StructureTemplatePool.Projection.RIGID,
+                    Optional.<LiquidSettings>empty());
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeTerrainHeightCacheTest.java

@@ -0,0 +1,131 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainHeightCache;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.OptionalInt;
+import java.util.function.IntSupplier;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public final class NativeTerrainHeightCacheTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void coordinatesRuntimePredicatesAndBoundsHaveSeparateEntries() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        AtomicInteger calls = new AtomicInteger();
+        NativeTerrainHeightCache.Query[] queries = {
+                query(1, -1, 1),
+                query(1, 1, -1),
+                query(2, -1, 1),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.OCEAN_FLOOR, -256, 768),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.WORLD_SURFACE, -64, 768),
+                new NativeTerrainHeightCache.Query(1, -1, 1, Heightmap.Types.WORLD_SURFACE, -256, 256)
+        };
+        for (int index = 0; index < queries.length; index++) {
+            assertEquals(index + 1, cached(cache, queries[index], calls::incrementAndGet));
+        }
+        for (int index = 0; index < queries.length; index++) {
+            assertEquals(index + 1, cached(cache, queries[index], calls::incrementAndGet));
+        }
+        assertEquals(queries.length, calls.get());
+        cache.evictRuntime(1);
+        assertEquals(3, cached(cache, queries[2], calls::incrementAndGet));
+        assertEquals(7, cached(cache, queries[0], calls::incrementAndGet));
+    }
+
+    @Test
+    public void allIntegerResultsAreCacheable() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertEquals(Integer.MIN_VALUE, cached(cache, query, () -> Integer.MIN_VALUE));
+        assertEquals(Integer.MIN_VALUE, cached(cache, query, () -> 0));
+    }
+
+    @Test
+    public void failedResolutionCanBeRetried() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertThrows(IllegalStateException.class, () -> cached(cache, query, () -> {
+            throw new IllegalStateException("terrain unavailable");
+        }));
+        assertEquals(42, cached(cache, query, () -> 42));
+    }
+
+    @Test
+    public void coldResolutionDoesNotHoldCacheMonitor() throws Exception {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        CountDownLatch entered = new CountDownLatch(1);
+        CountDownLatch release = new CountDownLatch(1);
+        ExecutorService executor = Executors.newFixedThreadPool(2);
+        try {
+            Future<Integer> slow = executor.submit(() -> cached(cache, query(1, 0, 0), () -> {
+                entered.countDown();
+                try {
+                    assertTrue(release.await(5, TimeUnit.SECONDS));
+                } catch (InterruptedException interruption) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(interruption);
+                }
+                return 9;
+            }));
+            assertTrue(entered.await(5, TimeUnit.SECONDS));
+            Future<Integer> independent = executor.submit(() -> cached(cache, query(1, 1, 0), () -> 17));
+            assertEquals(Integer.valueOf(17), independent.get(1, TimeUnit.SECONDS));
+            release.countDown();
+            assertEquals(Integer.valueOf(9), slow.get(5, TimeUnit.SECONDS));
+        } finally {
+            release.countDown();
+            executor.shutdownNow();
+            assertTrue(executor.awaitTermination(5, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void boundedCacheKeepsRecentlyReadCoordinates() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        for (int x = 0; x < 65_536; x++) {
+            cached(cache, query(1, x, 0), () -> 8);
+        }
+        assertEquals(8, cached(cache, query(1, 0, 0), () -> 99));
+        cached(cache, query(1, 65_536, 0), () -> 9);
+        assertEquals(8, cached(cache, query(1, 0, 0), () -> 99));
+        assertEquals(99, cached(cache, query(1, 1, 0), () -> 99));
+    }
+
+    @Test
+    public void unavailableResolvedHeightIsNotCached() {
+        NativeTerrainHeightCache cache = new NativeTerrainHeightCache();
+        NativeTerrainHeightCache.Query query = query(1, 0, 0);
+        assertTrue(cache.resolvedHeight(query, OptionalInt::empty).isEmpty());
+        assertEquals(42, cache.resolvedHeight(query, () -> OptionalInt.of(42)).orElseThrow());
+        assertEquals(42, cache.resolvedHeight(query, OptionalInt::empty).orElseThrow());
+    }
+
+    private static int cached(NativeTerrainHeightCache cache, NativeTerrainHeightCache.Query query,
+                              IntSupplier resolver) {
+        return cache.resolvedHeight(query, () -> OptionalInt.of(resolver.getAsInt())).orElseThrow();
+    }
+
+    private static NativeTerrainHeightCache.Query query(int runtimeId, int x, int z) {
+        return new NativeTerrainHeightCache.Query(runtimeId, x, z, Heightmap.Types.WORLD_SURFACE, -256, 768);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/NativeTransitionColumnTest.java

@@ -0,0 +1,109 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import art.arcane.iris.world.history.TerrainNativeBlockKeys;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTransitionColumn;
+
+import art.arcane.iris.world.history.BoundaryColumnGeometry;
+import art.arcane.iris.world.history.TerrainBoundarySignature;
+import art.arcane.iris.spi.IrisPlatform;
+import art.arcane.iris.spi.IrisPlatforms;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import art.arcane.iris.spi.PlatformRegistries;
+import art.arcane.iris.testsupport.PlatformLeakGuard;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Direction;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.RotatedPillarBlock;
+import net.minecraft.world.level.block.LiquidBlock;
+import net.minecraft.world.level.levelgen.Heightmap;
+import org.junit.BeforeClass;
+import org.junit.Rule;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.util.List;
+import java.util.OptionalInt;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.when;
+
+public final class NativeTransitionColumnTest {
+    @Rule
+    public final PlatformLeakGuard leakGuard = PlatformLeakGuard.clean();
+
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        NativeBlockTags.bindHeightmapFixtures();
+    }
+
+    @Test
+    public void customKeysUseCarrierForNativeColumnsAndHeightmaps() {
+        String key = "itemsadder:rocks/ruby_ore";
+        NativeBlockState custom = mock(NativeBlockState.class);
+        NativeBlockState carrier = mock(NativeBlockState.class);
+        when(custom.placementBaseState()).thenReturn(carrier);
+        when(carrier.key()).thenReturn("minecraft:oak_log[axis=z]");
+        IrisPlatform platform = mock(IrisPlatform.class);
+        PlatformRegistries registries = mock(PlatformRegistries.class);
+        when(platform.registries()).thenReturn(registries);
+        when(registries.blockOrNull(key)).thenReturn(custom);
+        LevelHeightAccessor height = LevelHeightAccessor.create(-16, 32);
+        TerrainBoundarySignature signature = signature(key);
+
+        try (MockedStatic<IrisPlatforms> platforms = mockStatic(IrisPlatforms.class)) {
+            platforms.when(IrisPlatforms::isBound).thenReturn(true);
+            platforms.when(IrisPlatforms::get).thenReturn(platform);
+            NoiseColumn column = NativeTransitionColumn.column(signature.geometry(), height, TerrainNativeBlockKeys::placementKey);
+
+            assertEquals(Direction.Axis.Z, column.getBlock(-15).getValue(RotatedPillarBlock.AXIS));
+            assertEquals(-14, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.OCEAN_FLOOR_WG, height, TerrainNativeBlockKeys::placementKey));
+        }
+    }
+
+    @Test
+    public void preservesNativePropertiesCavesAndFluids() {
+        NoiseColumn column = NativeTransitionColumn.column(signature("minecraft:oak_log[axis=x]").geometry(),
+                LevelHeightAccessor.create(-16, 32), TerrainNativeBlockKeys::placementKey);
+        assertEquals(Direction.Axis.X, column.getBlock(-15).getValue(RotatedPillarBlock.AXIS));
+        assertTrue(column.getBlock(-14).is(Blocks.CAVE_AIR));
+        assertEquals(Integer.valueOf(3), column.getBlock(-13).getValue(LiquidBlock.LEVEL));
+        assertTrue(column.getBlock(0).isAir());
+    }
+
+    @Test
+    public void usesNativeHeightmapPredicatesForWaterAndOpenSpace() {
+        TerrainBoundarySignature signature = signature("minecraft:oak_log[axis=x]");
+        LevelHeightAccessor height = LevelHeightAccessor.create(-16, 32);
+        assertEquals(-12, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.WORLD_SURFACE_WG, height, TerrainNativeBlockKeys::placementKey));
+        assertEquals(-14, NativeTransitionColumn.height(signature.geometry(), Heightmap.Types.OCEAN_FLOOR_WG, height, TerrainNativeBlockKeys::placementKey));
+    }
+
+    @Test
+    public void rejectsUnknownSavedStatesInsteadOfReplacingTerrain() {
+        assertThrows(IllegalArgumentException.class, () -> NativeTransitionColumn.column(signature("missing:removed_block").geometry(), LevelHeightAccessor.create(-16, 32), TerrainNativeBlockKeys::placementKey));
+    }
+
+    private static TerrainBoundarySignature signature(String solidState) {
+        BoundaryColumnGeometry geometry = BoundaryColumnGeometry.fromVoxels(-16, List.of(
+                new BoundaryColumnGeometry.Voxel("minecraft:stone", BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel(solidState, BoundaryColumnGeometry.Phase.SOLID, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:cave_air", BoundaryColumnGeometry.Phase.AIR, "", false),
+                new BoundaryColumnGeometry.Voxel("minecraft:water[level=3]", BoundaryColumnGeometry.Phase.FLUID,
+                        "minecraft:water[level=3]", false)));
+        return new TerrainBoundarySignature(
+                new TerrainBoundarySignature.Column(0, 0, 3, 1, OptionalInt.of(3), OptionalInt.empty()),
+                new TerrainBoundarySignature.Samples(new TerrainBoundarySignature.VerticalLayout(-16, 4, 1),
+                        new TerrainBoundarySignature.BiomeEncoding(List.of("minecraft:plains"), new short[]{0})),
+                geometry);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/nativegen/v26_3_R1/NativeBlockTags.java

@@ -0,0 +1,28 @@
+package art.arcane.iris.nativegen.v26_3_R1;
+
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.tags.TagLoader;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+
+import java.util.List;
+import java.util.Map;
+
+public final class NativeBlockTags {
+    private NativeBlockTags() {
+    }
+
+    public static void bindHeightmapFixtures() {
+        List<Holder<Block>> solid = List.of(Blocks.STONE.builtInRegistryHolder(),
+                Blocks.OAK_LOG.builtInRegistryHolder(), Blocks.SPRUCE_LOG.builtInRegistryHolder());
+        List<Holder<Block>> canopy = List.of(Blocks.STONE.builtInRegistryHolder(),
+                Blocks.OAK_LOG.builtInRegistryHolder(), Blocks.SPRUCE_LOG.builtInRegistryHolder(),
+                Blocks.OAK_LEAVES.builtInRegistryHolder(), Blocks.SPRUCE_LEAVES.builtInRegistryHolder());
+        BuiltInRegistries.BLOCK.prepareTagReload(new TagLoader.LoadResult<>(Registries.BLOCK, Map.of(
+                BlockTags.BLOCKS_MOTION_IN_HEIGHTMAP, canopy,
+                BlockTags.BLOCKS_MOTION_IN_HEIGHTMAP_NO_LEAVES, solid))).apply();
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/CustomBiomeCodecTest.java

@@ -0,0 +1,60 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.iris.generation.biome.IrisBiomeCustom;
+import art.arcane.iris.generation.biome.IrisBiomeCustomSpawn;
+import art.arcane.iris.generation.biome.IrisBiomeCustomSpawnType;
+import art.arcane.iris.pack.datapack.v263.DataFixerV263;
+import art.arcane.volmlib.util.collection.KList;
+import com.google.gson.JsonParser;
+import com.mojang.serialization.JsonOps;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.data.registries.VanillaRegistries;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.attribute.EnvironmentAttributes;
+import net.minecraft.world.attribute.modifier.MobSpawnSettingsModifier;
+import net.minecraft.world.entity.MobCategory;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.MobSpawnSettings;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+
+public class CustomBiomeCodecTest {
+    private static HolderLookup.Provider registries;
+
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        registries = VanillaRegistries.createWorldLookup();
+    }
+
+    @Test
+    public void nativeCodecAcceptsCustomColorsAndSpawnCounts() {
+        IrisBiomeCustom custom = new IrisBiomeCustom();
+        custom.setId("codec_test");
+        custom.setWaterColor("#102030");
+        custom.setFogColor("#405060");
+        custom.setSpawnRarity(2);
+        IrisBiomeCustomSpawn spawn = new IrisBiomeCustomSpawn();
+        spawn.setType("minecraft:zombie");
+        spawn.setGroup(IrisBiomeCustomSpawnType.MONSTER);
+        spawn.setMinCount(2);
+        spawn.setMaxCount(4);
+        spawn.setWeight(7);
+        custom.setSpawns(new KList<>(spawn));
+        Biome biome = Biome.DIRECT_CODEC.parse(RegistryOps.create(JsonOps.INSTANCE, registries),
+                JsonParser.parseString(custom.generateJson(new DataFixerV263()))).getOrThrow();
+        MobSpawnSettings settings = biome.getAttributes().applyModifier(EnvironmentAttributes.NATURAL_MOB_SPAWNS,
+                EnvironmentAttributes.NATURAL_MOB_SPAWNS.defaultValue());
+        MobSpawnSettings.SpawnerData decoded = settings.getMobsToSpawn(MobCategory.MONSTER).unwrap().getFirst().value();
+        assertEquals(2, decoded.count().minInclusive());
+        assertEquals(4, decoded.count().maxInclusive());
+        assertEquals(0x102030, biome.getWaterColor() & 0xFFFFFF);
+        assertEquals(MobSpawnSettingsModifier.overlay(),
+                biome.getAttributes().get(EnvironmentAttributes.NATURAL_MOB_SPAWNS).modifier());
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/CustomBiomeSourceStructureContractTest.java

@@ -0,0 +1,66 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.iris.platform.bukkit.nms.BukkitBiomePolicy;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.terrain.IrisDimension;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Proxy;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertTrue;
+
+public class CustomBiomeSourceStructureContractTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void stackedCustomBiomesUseTheirOwningDimensionNamespace() {
+        IrisDimension host = new IrisDimension();
+        host.setLoadKey("Host");
+        IrisDimension upper = new IrisDimension();
+        upper.setLoadKey("Layers/Upper");
+
+        assertEquals("layers:upper/aurora", BukkitBiomePolicy.customBiomeKey(upper, "Aurora"));
+        assertNotEquals(
+                BukkitBiomePolicy.customBiomeKey(host, "Aurora"),
+                BukkitBiomePolicy.customBiomeKey(upper, "Aurora")
+        );
+    }
+
+    @Test
+    public void temporaryNaturalBiomeAnswersAreNotMemoized() {
+        Engine temporary = engineAnsweringNaturalFallback(true, 12, -8);
+        Engine stable = engineAnsweringNaturalFallback(false, 12, -8);
+        assertFalse(BukkitBiomePolicy.isBiomeCacheable(temporary, 12, -8));
+        assertTrue(BukkitBiomePolicy.isBiomeCacheable(stable, 12, -8));
+    }
+
+    private static Engine engineAnsweringNaturalFallback(
+            boolean naturalFallback,
+            int expectedX,
+            int expectedZ
+    ) {
+        return (Engine) Proxy.newProxyInstance(
+                Engine.class.getClassLoader(),
+                new Class<?>[]{Engine.class},
+                (proxy, method, arguments) -> {
+                    if (!method.getName().equals("answersFromNaturalTerrain")) {
+                        throw new UnsupportedOperationException(method.getName());
+                    }
+                    assertEquals(Integer.valueOf(expectedX), arguments[0]);
+                    assertEquals(Integer.valueOf(expectedZ), arguments[1]);
+                    return naturalFallback;
+                }
+        );
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/IrisChunkGeneratorFailureContractTest.java

@@ -0,0 +1,97 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import org.junit.Test;
+
+import java.util.concurrent.CancellationException;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.Semaphore;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.locks.LockSupport;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class IrisChunkGeneratorFailureContractTest {
+    @Test
+    public void releasedNoiseAdmissionLetsSynchronousDependentWaitForQueuedExclusive() throws Exception {
+        Semaphore admission = new Semaphore(1, true);
+        admission.acquire();
+        CountDownLatch exclusiveEntered = new CountDownLatch(1);
+        CountDownLatch releaseExclusive = new CountDownLatch(1);
+        AtomicBoolean dependentFinished = new AtomicBoolean(false);
+        ExecutorService executor = Executors.newSingleThreadExecutor();
+        boolean stageReleased = false;
+
+        try {
+            Future<?> exclusive = executor.submit(() -> {
+                boolean acquired = false;
+                try {
+                    admission.acquire();
+                    acquired = true;
+                    exclusiveEntered.countDown();
+                    assertTrue(releaseExclusive.await(2, TimeUnit.SECONDS));
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(e);
+                } finally {
+                    if (acquired) {
+                        admission.release();
+                    }
+                }
+            });
+            awaitQueueLength(admission, 1);
+            CompletableFuture<Void> outward = new CompletableFuture<>();
+            outward.thenRun(() -> {
+                try {
+                    assertTrue(exclusiveEntered.await(2, TimeUnit.SECONDS));
+                    dependentFinished.set(true);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new IllegalStateException(e);
+                }
+            });
+
+            admission.release();
+            stageReleased = true;
+            assertTrue(outward.complete(null));
+            assertTrue(dependentFinished.get());
+            releaseExclusive.countDown();
+            exclusive.get(2, TimeUnit.SECONDS);
+            assertEquals(1, admission.availablePermits());
+        } finally {
+            if (!stageReleased) {
+                admission.release();
+            }
+            releaseExclusive.countDown();
+            executor.shutdownNow();
+        }
+    }
+
+    @Test
+    public void transformedDelegateCancellationIsDetectedThroughItsCompletionFailure() {
+        CompletableFuture<Void> delegate = new CompletableFuture<>();
+        CompletableFuture<Void> transformed = delegate.thenApply(value -> value);
+
+        assertTrue(delegate.cancel(false));
+        assertFalse(transformed.isCancelled());
+        CompletionException failure = assertThrows(CompletionException.class, transformed::join);
+        assertTrue(failure.getCause() instanceof CancellationException);
+    }
+
+    private static void awaitQueueLength(Semaphore semaphore, int expected) {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(2);
+        while (semaphore.getQueueLength() < expected && System.nanoTime() < deadline) {
+            LockSupport.parkNanos(TimeUnit.MILLISECONDS.toNanos(1));
+        }
+        assertTrue("Expected at least " + expected + " queued semaphore threads",
+                semaphore.getQueueLength() >= expected);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/IrisChunkGeneratorMonumentLocateContractTest.java

@@ -0,0 +1,58 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureLocateResults;
+import com.mojang.datafixers.util.Pair;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import org.junit.Test;
+
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+
+public class IrisChunkGeneratorMonumentLocateContractTest {
+    @Test
+    public void mixedLocateSelectsNearestProviderAndPrefersNativeOnTie() {
+        BlockPos origin = BlockPos.ZERO;
+        Pair<BlockPos, Holder<Structure>> irisNear = Pair.of(new BlockPos(4, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeFar = Pair.of(new BlockPos(8, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeNear = Pair.of(new BlockPos(2, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeTie = Pair.of(new BlockPos(0, 70, 4), null);
+
+        assertSame(irisNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeFar));
+        assertSame(nativeNear, NativeStructureLocateResults.nearest(origin, irisNear, nativeNear));
+        assertSame(nativeTie, NativeStructureLocateResults.nearest(origin, irisNear, nativeTie));
+    }
+
+    @Test
+    public void mixedUnexploredLocateReferencesOnlyTheSelectedProvider() {
+        BlockPos origin = BlockPos.ZERO;
+        Pair<BlockPos, Holder<Structure>> irisNear = Pair.of(new BlockPos(4, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeFar = Pair.of(new BlockPos(8, 70, 0), null);
+        AtomicInteger irisReferences = new AtomicInteger();
+        AtomicInteger nativeReferences = new AtomicInteger();
+
+        Pair<BlockPos, Holder<Structure>> irisSelected =
+                NativeStructureLocateResults.selectAndReference(
+                        origin,
+                        irisNear, () -> irisReferences.incrementAndGet(),
+                        nativeFar, () -> nativeReferences.incrementAndGet());
+
+        assertSame(irisNear, irisSelected);
+        assertEquals(1, irisReferences.get());
+        assertEquals(0, nativeReferences.get());
+
+        Pair<BlockPos, Holder<Structure>> nativeNear = Pair.of(new BlockPos(2, 70, 0), null);
+        Pair<BlockPos, Holder<Structure>> nativeSelected =
+                NativeStructureLocateResults.selectAndReference(
+                        origin,
+                        irisNear, () -> irisReferences.incrementAndGet(),
+                        nativeNear, () -> nativeReferences.incrementAndGet());
+
+        assertSame(nativeNear, nativeSelected);
+        assertEquals(1, irisReferences.get());
+        assertEquals(1, nativeReferences.get());
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/IrisChunkGeneratorSpawnAdmissionTest.java

@@ -0,0 +1,153 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.iris.platform.bukkit.nms.BukkitGeneratorContext;
+import org.bukkit.World;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeChunkGenerator;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeBiomeSourceImpl;
+
+import net.minecraft.server.level.ServerLevel;
+import art.arcane.iris.generation.runtime.IrisEngine;
+import art.arcane.iris.generation.runtime.GenerationSessionManager;
+import art.arcane.iris.generation.runtime.GenerationTransitionGate;
+import art.arcane.iris.world.history.GenerationHistoryRuntimeRouter;
+import art.arcane.iris.world.history.NativeBiomeSpawnSelection;
+import art.arcane.iris.world.history.SavedBiomeRuntime;
+import art.arcane.iris.generation.context.IrisContext;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.random.WeightedList;
+import net.minecraft.world.entity.MobCategory;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.MobSpawnSettings;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.Field;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class IrisChunkGeneratorSpawnAdmissionTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void tickSpawnQueryLeavesOwnerThreadAvailableForBoundaryCheckpoint() throws Exception {
+        Fixture fixture = new Fixture();
+        ExecutorService owner = Executors.newSingleThreadExecutor();
+        ExecutorService reloader = Executors.newSingleThreadExecutor();
+        AtomicInteger snapshots = new AtomicInteger();
+        long previousSession = fixture.sessions.currentSessionId();
+        try {
+            assertSame(fixture.expected, owner.submit(fixture::query).get(2L, TimeUnit.SECONDS));
+            assertEquals(previousSession, fixture.readSession.get());
+            CompletableFuture<Void> cutover = CompletableFuture.runAsync(() -> {
+                try (GenerationTransitionGate.Transition ignored = fixture.sessions.transitionGate().beginTransition(2_000L)) {
+                    fixture.sessions.sealAndAwait("Studio generation cutover", 2_000L);
+                    Future<?> query = owner.submit(() -> {
+                        assertTrue(fixture.query().isEmpty());
+                        assertNull(IrisContext.get());
+                    });
+                    owner.submit(snapshots::incrementAndGet).get(2L, TimeUnit.SECONDS);
+                    query.get(2L, TimeUnit.SECONDS);
+                    assertEquals(1, fixture.savedReads.get());
+                    assertEquals(1, fixture.routes.get());
+                    fixture.sessions.activateNextSession();
+                } catch (Exception failure) {
+                    throw new IllegalStateException(failure);
+                }
+            }, reloader);
+
+            cutover.get(3L, TimeUnit.SECONDS);
+            assertEquals(1, snapshots.get());
+            assertEquals(0, fixture.sessions.activeLeases());
+            assertSame(fixture.expected, owner.submit(fixture::query).get(2L, TimeUnit.SECONDS));
+            assertEquals(fixture.sessions.currentSessionId(), fixture.readSession.get());
+            assertTrue(fixture.readSession.get() > previousSession);
+            assertEquals(2, fixture.savedReads.get());
+            assertEquals(2, fixture.routes.get());
+            assertEquals(0, fixture.sessions.activeLeases());
+        } finally {
+            owner.shutdownNow();
+            reloader.shutdownNow();
+            assertTrue(owner.awaitTermination(2L, TimeUnit.SECONDS));
+            assertTrue(reloader.awaitTermination(2L, TimeUnit.SECONDS));
+        }
+    }
+
+    private static void setField(NativeChunkGenerator<?, ?, ?, ?, ?> generator, String name, Object value) throws Exception {
+        Field field = NativeChunkGenerator.class.getDeclaredField(name);
+        field.setAccessible(true);
+        field.set(generator, value);
+    }
+
+    private static final class Fixture {
+        private final GenerationSessionManager sessions = new GenerationSessionManager(true);
+        private final IrisEngine engine = mock(IrisEngine.class);
+        private final NativeChunkGenerator<?, ?, ?, ?, ?> generator = mock(NativeChunkGenerator.class, CALLS_REAL_METHODS);
+        private final Holder<Biome> biome = Holder.direct(mock(Biome.class));
+        private final StructureManager structures = mock(StructureManager.class);
+        private final WeightedList<MobSpawnSettings.SpawnerData> expected = mock(WeightedList.class);
+        private final ServerLevel level = mock(ServerLevel.class);
+        private final AtomicInteger savedReads = new AtomicInteger();
+        private final AtomicInteger routes = new AtomicInteger();
+        private final AtomicLong readSession = new AtomicLong();
+
+        private Fixture() throws Exception {
+            GenerationHistoryRuntimeRouter router = mock(GenerationHistoryRuntimeRouter.class);
+            SavedBiomeRuntime saved = mock(SavedBiomeRuntime.class);
+            ChunkGenerator delegate = mock(ChunkGenerator.class);
+            NativeBiomeSourceImpl source = mock(NativeBiomeSourceImpl.class);
+            when(level.getBiome(new BlockPos(0, 64, 0))).thenReturn(biome);
+            setField(generator, "runtimeLevel", level);
+            when(engine.getGenerationSessions()).thenReturn(sessions);
+            when(engine.getGenerationHistoryRuntimeRouter()).thenReturn(Optional.of(router));
+            when(router.biomes()).thenReturn(saved);
+            when(saved.nativeSpawnSelection(0, 64, 0, "")).thenAnswer(invocation -> {
+                assertAdmitted();
+                savedReads.incrementAndGet();
+                return new NativeBiomeSpawnSelection(NativeBiomeSpawnSelection.Mode.RETAINED, "minecraft:plains");
+            });
+            when(engine.openGenerationHistoryCoordinateScope(0, 0)).thenAnswer(invocation -> {
+                assertAdmitted();
+                routes.incrementAndGet();
+                return null;
+            });
+            when(delegate.getMobsAt(level, structures, MobCategory.MONSTER, new BlockPos(0, 64, 0)))
+                    .thenReturn(expected);
+            setField(generator, "context", new BukkitGeneratorContext(new BukkitGeneratorContext.Options(1L, engine, mock(World.class))));
+            setField(generator, "delegate", delegate);
+            setField(generator, "customBiomeSource", source);
+        }
+
+        private WeightedList<MobSpawnSettings.SpawnerData> query() {
+            return generator.getMobsAt(level, structures, MobCategory.MONSTER, new BlockPos(0, 64, 0));
+        }
+
+        private void assertAdmitted() {
+            assertEquals(1, sessions.activeLeases());
+            assertSame(engine, IrisContext.get().getEngine());
+            readSession.set(IrisContext.get().getGenerationSessionId());
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NMSBindingDatapackStructureScopeTest.java

@@ -0,0 +1,439 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureSetFilter;
+
+import net.minecraft.world.level.levelgen.structure.placement.AbstractSpreadingStructurePlacement;
+import art.arcane.iris.pack.datapack.DatapackIngestService;
+import art.arcane.iris.pack.datapack.DatapackStructureScopeIndex;
+import art.arcane.iris.structure.nativegen.IrisImportedStructureControl;
+import art.arcane.iris.structure.placement.IrisStructureSetFrequencyOverride;
+import art.arcane.volmlib.util.collection.KList;
+import com.mojang.datafixers.util.Either;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderOwner;
+import net.minecraft.core.Vec3i;
+import net.minecraft.core.component.DataComponentMap;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.tags.TagKey;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureSet;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadType;
+import net.minecraft.world.level.levelgen.structure.placement.StructurePlacement;
+import com.mojang.serialization.MapCodec;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import org.junit.Test;
+import org.junit.BeforeClass;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+
+public class NMSBindingDatapackStructureScopeTest {
+    private static final String SOURCE = "https://example.test/managed.zip";
+
+    @BeforeClass
+    public static void bootstrapMinecraft() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void managedSetContainingVanillaStructureIsAbsentOutsideDeclaringDimension() {
+        Holder<Structure> vanillaStructure = structureHolder("minecraft:pillager_outpost");
+        Holder<StructureSet> managedSet = structureSetHolder(
+                "managed:illager_barracks", vanillaStructure);
+        DatapackStructureScopeIndex index = index(
+                List.of(),
+                List.of("managed:illager_barracks"));
+
+        NativeStructureSetFilter.Selection vanilla = NativeStructureSetFilter.filter(
+                List.of(managedSet), index, Set.of());
+        NativeStructureSetFilter.Selection declaring = NativeStructureSetFilter.filter(
+                List.of(managedSet), index, index.declaredSources(List.of(SOURCE)));
+
+        assertEquals(0, vanilla.structureSets().size());
+        assertEquals(1, vanilla.excludedManagedSets());
+        assertEquals(1, declaring.structureSets().size());
+        assertSame(managedSet, declaring.structureSets().getFirst());
+    }
+
+    @Test
+    public void unmanagedSetRetainsOnlyDefinitionsAllowedInTheWorld() {
+        Holder<Structure> vanillaStructure = structureHolder("minecraft:village_plains");
+        Holder<Structure> managedStructure = structureHolder("managed:tavern");
+        Holder<StructureSet> vanillaSet = structureSetHolder(
+                "minecraft:villages", vanillaStructure, managedStructure);
+        DatapackStructureScopeIndex index = index(
+                List.of("managed:tavern"),
+                List.of());
+
+        NativeStructureSetFilter.Selection vanilla = NativeStructureSetFilter.filter(
+                List.of(vanillaSet), index, Set.of());
+        NativeStructureSetFilter.Selection declaring = NativeStructureSetFilter.filter(
+                List.of(vanillaSet), index, index.declaredSources(List.of(SOURCE)));
+
+        assertEquals(1, vanilla.structureSets().size());
+        assertEquals(1, vanilla.structureSets().getFirst().value().structures().size());
+        assertSame(vanillaStructure,
+                vanilla.structureSets().getFirst().value().structures().getFirst().structure());
+        assertSame(vanillaSet.value().placement(),
+                vanilla.structureSets().getFirst().value().placement());
+        assertSame(vanillaSet, declaring.structureSets().getFirst());
+    }
+
+    @Test
+    public void setWithNoAllowedDefinitionsIsRemoved() {
+        Holder<StructureSet> unmanagedSet = structureSetHolder(
+                "minecraft:custom", structureHolder("managed:only"));
+        DatapackStructureScopeIndex index = index(List.of("managed:only"), List.of());
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(unmanagedSet), index, Set.of());
+
+        assertEquals(0, selection.structureSets().size());
+    }
+
+    @Test
+    public void spigotDirectHolderRecoversItsRegistryKeyFromSharedEntries() {
+        ResourceKey<StructureSet> key = ResourceKey.create(
+                Registries.STRUCTURE_SET,
+                Identifier.parse("managed:illager_barracks"));
+        List<StructureSet.StructureSelectionEntry> entries = List.of(
+                new StructureSet.StructureSelectionEntry(
+                        structureHolder("minecraft:pillager_outpost"), 1));
+        Holder<StructureSet> registered = new KeyedHolder<>(key, new StructureSet(
+                entries,
+                new RandomSpreadStructurePlacement(
+                        34, 8, RandomSpreadType.LINEAR, 10387312)));
+        Holder<StructureSet> spigotDirect = Holder.direct(new StructureSet(
+                entries,
+                new RandomSpreadStructurePlacement(
+                        34, 8, RandomSpreadType.LINEAR, 14357620)));
+        DatapackStructureScopeIndex scopeIndex = index(
+                List.of(), List.of("managed:illager_barracks"));
+        NativeStructureSetFilter.StructureSetKeyIndex keyIndex =
+                NativeStructureSetFilter.keyIndex(List.of(registered));
+
+        NativeStructureSetFilter.Selection excluded =
+                NativeStructureSetFilter.filter(
+                        List.of(spigotDirect),
+                        scopeIndex,
+                        Set.of(),
+                        new IrisImportedStructureControl(),
+                        keyIndex);
+        NativeStructureSetFilter.Selection retained =
+                NativeStructureSetFilter.filter(
+                        List.of(spigotDirect),
+                        scopeIndex,
+                        scopeIndex.declaredSources(List.of(SOURCE)),
+                        new IrisImportedStructureControl(),
+                        keyIndex);
+
+        assertEquals(0, excluded.structureSets().size());
+        assertEquals(1, excluded.excludedManagedSets());
+        assertSame(spigotDirect, retained.structureSets().getFirst());
+        assertEquals(1, retained.retainedManagedSets());
+    }
+
+    @Test
+    public void structureScopeDoesNotLinkPaperOnlyPlacementClasses() throws IOException {
+        InputStream classResource = NativeStructureSetFilter.class
+                .getResourceAsStream("NativeStructureSetFilter.class");
+        assertNotNull(classResource);
+        try (InputStream input = classResource) {
+            String classFile = new String(input.readAllBytes(), StandardCharsets.ISO_8859_1);
+            assertFalse(classFile.contains("KeyedRandomSpreadStructurePlacement"));
+        }
+    }
+
+    @Test
+    public void exactFrequencyOverridesScaleOnlyTheNamedNativeStructureSet() {
+        Holder<StructureSet> complexes = structureSetHolder(
+                "minecraft:nether_complexes",
+                new RandomSpreadStructurePlacement(27, 4, RandomSpreadType.LINEAR, 30084232),
+                structureHolder("minecraft:fortress"));
+        Holder<StructureSet> fossils = structureSetHolder(
+                "minecraft:nether_fossils",
+                new RandomSpreadStructurePlacement(2, 1, RandomSpreadType.LINEAR, 14357921),
+                structureHolder("minecraft:nether_fossil"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("minecraft:nether_complexes")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(complexes, fossils), index(List.of(), List.of()), Set.of(), control);
+
+        RandomSpreadStructurePlacement scaledComplexes =
+                (RandomSpreadStructurePlacement) selection.structureSets().get(0).value().placement();
+        RandomSpreadStructurePlacement unchangedFossils =
+                (RandomSpreadStructurePlacement) selection.structureSets().get(1).value().placement();
+        assertEquals(26, scaledComplexes.spacing());
+        assertEquals(4, scaledComplexes.separation());
+        assertEquals(2, unchangedFossils.spacing());
+        assertSame(fossils, selection.structureSets().get(1));
+        assertEquals(27, ((RandomSpreadStructurePlacement) complexes.value().placement()).spacing());
+    }
+
+    @Test
+    public void frequencyOnlyPassLeavesUnrelatedCustomPlacementUntouched() {
+        Holder<StructureSet> exclusionTarget = structureSetHolder(
+                "example:target", structureHolder("example:target"));
+        Holder<StructureSet> custom = structureSetHolder(
+                "example:custom",
+                new UnsupportedPlacement(Optional.of(
+                        new AbstractSpreadingStructurePlacement.ExclusionZone(exclusionTarget, 1))),
+                structureHolder("example:custom"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("minecraft:nether_complexes")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(custom), index(List.of(), List.of()), Set.of(), control);
+
+        assertSame(custom, selection.structureSets().getFirst());
+    }
+
+    @Test
+    public void frequencyOnlyPassRebindsDependentExclusionTarget() {
+        Holder<StructureSet> target = structureSetHolder(
+                "example:target",
+                new RandomSpreadStructurePlacement(27, 4, RandomSpreadType.LINEAR, 30084232),
+                structureHolder("example:target"));
+        RandomSpreadStructurePlacement dependentPlacement = new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                AbstractSpreadingStructurePlacement.FrequencyReductionMethod.DEFAULT,
+                1.0F,
+                4567,
+                Optional.of(new AbstractSpreadingStructurePlacement.ExclusionZone(target, 1)),
+                32,
+                8,
+                RandomSpreadType.LINEAR);
+        Holder<StructureSet> dependent = structureSetHolder(
+                "example:dependent",
+                dependentPlacement,
+                structureHolder("example:dependent"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:target")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(dependent, target), index(List.of(), List.of()), Set.of(), control);
+
+        Holder<StructureSet> scaledDependent = selection.structureSets().get(0);
+        Holder<StructureSet> scaledTarget = selection.structureSets().get(1);
+        assertNotSame(dependent, scaledDependent);
+        assertNotSame(target, scaledTarget);
+        assertSame(scaledTarget, NativeStructureSetFilter.exclusionZone(
+                scaledDependent.value().placement()).orElseThrow().otherSet());
+        assertEquals(26, ((RandomSpreadStructurePlacement)
+                scaledTarget.value().placement()).spacing());
+    }
+
+    @Test
+    public void frequencyOnlyPassRebindsAffectedExclusionCycle() {
+        MutableStructureSetHolder first = new MutableStructureSetHolder("example:first");
+        MutableStructureSetHolder second = new MutableStructureSetHolder("example:second");
+        first.bind(structureSet(
+                new RandomSpreadStructurePlacement(
+                        Vec3i.ZERO,
+                        AbstractSpreadingStructurePlacement.FrequencyReductionMethod.DEFAULT,
+                        1.0F,
+                        101,
+                        Optional.of(new AbstractSpreadingStructurePlacement.ExclusionZone(second, 1)),
+                        32,
+                        8,
+                        RandomSpreadType.LINEAR),
+                "example:first"));
+        second.bind(structureSet(
+                new RandomSpreadStructurePlacement(
+                        Vec3i.ZERO,
+                        AbstractSpreadingStructurePlacement.FrequencyReductionMethod.DEFAULT,
+                        1.0F,
+                        102,
+                        Optional.of(new AbstractSpreadingStructurePlacement.ExclusionZone(first, 1)),
+                        27,
+                        4,
+                        RandomSpreadType.LINEAR),
+                "example:second"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:second")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(first, second), index(List.of(), List.of()), Set.of(), control);
+
+        Holder<StructureSet> scaledFirst = selection.structureSets().get(0);
+        Holder<StructureSet> scaledSecond = selection.structureSets().get(1);
+        assertSame(scaledSecond, NativeStructureSetFilter.exclusionZone(
+                scaledFirst.value().placement()).orElseThrow().otherSet());
+        assertSame(scaledFirst, NativeStructureSetFilter.exclusionZone(
+                scaledSecond.value().placement()).orElseThrow().otherSet());
+        assertEquals(26, ((RandomSpreadStructurePlacement)
+                scaledSecond.value().placement()).spacing());
+    }
+
+    @Test
+    public void randomSpreadSubtypeUsesTheCanonicalPlacementContract() {
+        Holder<StructureSet> custom = structureSetHolder(
+                "example:custom",
+                new CustomRandomSpreadPlacement(),
+                structureHolder("example:custom"));
+        KList<IrisStructureSetFrequencyOverride> overrides = new KList<>();
+        overrides.add(new IrisStructureSetFrequencyOverride()
+                .setStructureSet("example:custom")
+                .setMultiplier(1.1D));
+        IrisImportedStructureControl control = new IrisImportedStructureControl()
+                .setFrequencyOverrides(overrides);
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(custom), index(List.of(), List.of()), Set.of(), control);
+        StructurePlacement placement = selection.structureSets().getFirst().value().placement();
+
+        assertEquals(RandomSpreadStructurePlacement.class, placement.getClass());
+        assertEquals(26, ((RandomSpreadStructurePlacement) placement).spacing());
+    }
+
+    @Test
+    public void excludedManagedSetCannotSuppressAnAllowedSetThroughExclusionZone() {
+        Holder<StructureSet> managedSet = structureSetHolder(
+                "managed:blocked",
+                structureHolder("managed:blocked"));
+        RandomSpreadStructurePlacement originalPlacement = new RandomSpreadStructurePlacement(
+                Vec3i.ZERO,
+                AbstractSpreadingStructurePlacement.FrequencyReductionMethod.DEFAULT,
+                1.0F,
+                4567,
+                Optional.of(new AbstractSpreadingStructurePlacement.ExclusionZone(managedSet, 1)),
+                32,
+                8,
+                RandomSpreadType.LINEAR);
+        Holder<StructureSet> vanillaSet = structureSetHolder(
+                "minecraft:allowed",
+                originalPlacement,
+                structureHolder("minecraft:village_plains"));
+        DatapackStructureScopeIndex index = index(
+                List.of("managed:blocked"),
+                List.of("managed:blocked"));
+
+        NativeStructureSetFilter.Selection selection = NativeStructureSetFilter.filter(
+                List.of(vanillaSet, managedSet), index, Set.of());
+
+        assertEquals(1, selection.structureSets().size());
+        StructurePlacement scopedPlacement = selection.structureSets().getFirst().value().placement();
+        assertEquals(0, NativeStructureSetFilter.exclusionZone(scopedPlacement).stream().count());
+    }
+
+    private static DatapackStructureScopeIndex index(
+            List<String> structureKeys,
+            List<String> structureSetKeys
+    ) {
+        return DatapackStructureScopeIndex.create(List.of(
+                new DatapackIngestService.StructureScopeResources(
+                        SOURCE,
+                        structureKeys,
+                        structureSetKeys)));
+    }
+
+    private static Holder<Structure> structureHolder(String key) {
+        return new KeyedHolder<>(ResourceKey.create(Registries.STRUCTURE, Identifier.parse(key)), null);
+    }
+
+    private static Holder<StructureSet> structureSetHolder(
+            String key,
+            Holder<Structure>... structures
+    ) {
+        return structureSetHolder(
+                key,
+                new RandomSpreadStructurePlacement(32, 8, RandomSpreadType.LINEAR, 12345),
+                structures);
+    }
+
+    private static Holder<StructureSet> structureSetHolder(
+            String key,
+            StructurePlacement placement,
+            Holder<Structure>... structures
+    ) {
+        List<StructureSet.StructureSelectionEntry> entries = Stream.of(structures)
+                .map(structure -> new StructureSet.StructureSelectionEntry(structure, 1))
+                .toList();
+        StructureSet value = new StructureSet(entries, placement);
+        return new KeyedHolder<>(
+                ResourceKey.create(Registries.STRUCTURE_SET, Identifier.parse(key)),
+                value);
+    }
+
+    private static StructureSet structureSet(StructurePlacement placement, String structureKey) {
+        return new StructureSet(
+                List.of(new StructureSet.StructureSelectionEntry(
+                        structureHolder(structureKey), 1)),
+                placement);
+    }
+
+    private static final class KeyedHolder<T> extends Holder.Reference<T> {
+        private KeyedHolder(ResourceKey<T> key, T value) {
+            super(Type.STAND_ALONE, new HolderOwner<>() {}, key, null);
+            bindValue(value);
+        }
+    }
+
+    private static final class UnsupportedPlacement extends AbstractSpreadingStructurePlacement {
+        private UnsupportedPlacement(Optional<ExclusionZone> exclusionZone) {
+            super(Vec3i.ZERO, FrequencyReductionMethod.DEFAULT, 1F, 1, exclusionZone);
+        }
+
+        @Override
+        protected boolean isPlacementChunk(ChunkGeneratorStructureState state, int x, int z) {
+            return false;
+        }
+
+        @Override
+        public MapCodec<? extends AbstractSpreadingStructurePlacement> codec() {
+            return null;
+        }
+    }
+
+    private static final class MutableStructureSetHolder extends Holder.Reference<StructureSet> {
+        private MutableStructureSetHolder(String key) {
+            super(Type.STAND_ALONE, new HolderOwner<>() {
+            }, ResourceKey.create(Registries.STRUCTURE_SET, Identifier.parse(key)), null);
+        }
+
+        private void bind(StructureSet structureSet) {
+            bindValue(structureSet);
+        }
+    }
+
+    private static final class CustomRandomSpreadPlacement extends RandomSpreadStructurePlacement {
+        private CustomRandomSpreadPlacement() {
+            super(27, 4, RandomSpreadType.LINEAR, 30084232);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NativeStructurePoiUpdatesTest.java

@@ -0,0 +1,252 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructurePoiUpdates;
+
+import ca.spottedleaf.moonrise.common.util.TickThread;
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.IdMapper;
+import net.minecraft.core.SectionPos;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.entity.ai.village.poi.PoiManager;
+import net.minecraft.world.entity.ai.village.poi.PoiRecord;
+import net.minecraft.world.entity.ai.village.poi.PoiSection;
+import net.minecraft.world.entity.ai.village.poi.PoiType;
+import net.minecraft.world.entity.ai.village.poi.PoiTypes;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ImposterProtoChunk;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import org.bukkit.NamespacedKey;
+import org.bukkit.craftbukkit.persistence.CraftPersistentDataTypeRegistry;
+import org.bukkit.craftbukkit.persistence.DirtyCraftPersistentDataContainer;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.FutureTask;
+import java.util.concurrent.TimeUnit;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.doAnswer;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class NativeStructurePoiUpdatesTest {
+    private static final NamespacedKey DIRTY_SECTIONS = new NamespacedKey("iris", "native_poi_sections");
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void generationRecordsIntentBeforeSuppressingNativePoiCallbacks() {
+        Fixture fixture = new Fixture();
+        BlockPos position = new BlockPos(-31, 5, 49);
+        doAnswer(call -> {
+            assertNotNull(fixture.proto.persistentDataContainer.get(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY));
+            assertEquals(Block.UPDATE_CLIENTS | 4096, (int) call.getArgument(2));
+            fixture.proto.setBlockState(position, call.getArgument(1), 0);
+            return true;
+        }).when(fixture.world).setBlock(any(), any(), anyInt(), anyInt());
+
+        assertTrue(fixture.updates.setBlock(fixture.world, position,
+                Blocks.COMPOSTER.defaultBlockState(), Block.UPDATE_CLIENTS, 17));
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+    }
+
+    @Test
+    public void denseWritesStoreOneSectionBitAndSurvivePersistentDataRoundTrip() throws Exception {
+        Fixture fixture = new Fixture();
+        for (int z = 0; z < 16; z++) {
+            for (int x = 0; x < 16; x++) {
+                fixture.write(new BlockPos(-32 + x, 5, 48 + z), Blocks.COMPOSTER.defaultBlockState());
+            }
+        }
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+        DirtyCraftPersistentDataContainer restored = new DirtyCraftPersistentDataContainer(new CraftPersistentDataTypeRegistry());
+        restored.putAll(fixture.proto.persistentDataContainer.toTagCompound());
+        fixture.loaded.persistentDataContainer = restored;
+
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+
+        assertEquals(256L, fixture.records().getRecords(type -> true, PoiManager.Occupancy.ANY).count());
+        assertFalse(restored.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void validSectionsReconcileFinalStatesAndKeepMatchingClaimedTickets() throws Exception {
+        Fixture fixture = new Fixture();
+        BlockPos retained = new BlockPos(-31, 5, 49);
+        BlockPos replaced = new BlockPos(-30, 5, 49);
+        BlockPos removed = new BlockPos(-29, 5, 49);
+        Holder<PoiType> farmer = PoiTypes.forState(Blocks.COMPOSTER.defaultBlockState()).orElseThrow();
+        PoiSection existing = new PoiSection.Packed(true, List.of(
+                new PoiRecord.Packed(retained, farmer, 0),
+                new PoiRecord.Packed(replaced, farmer, 1),
+                new PoiRecord.Packed(removed, farmer, 1))).unpack(() -> {});
+        fixture.pois.put(SectionPos.of(retained).asLong(), existing);
+        PoiRecord retainedRecord = existing.getRecords(type -> true, PoiManager.Occupancy.ANY)
+                .filter(record -> record.getPos().equals(retained)).findFirst().orElseThrow();
+        for (BlockPos position : List.of(retained, replaced, removed)) {
+            fixture.proto.setBlockState(position, Blocks.COMPOSTER.defaultBlockState(), 0);
+        }
+        fixture.write(replaced, Blocks.BARREL.defaultBlockState());
+        fixture.write(removed, Blocks.AIR.defaultBlockState());
+
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+
+        assertEquals(PoiTypes.forState(Blocks.BARREL.defaultBlockState()), existing.getType(replaced));
+        assertTrue(existing.getType(removed).isEmpty());
+        assertSame(retainedRecord, existing.getRecords(type -> true, PoiManager.Occupancy.ANY)
+                .filter(record -> record.getPos().equals(retained)).findFirst().orElseThrow());
+        assertEquals(0, existing.getFreeTickets(retained));
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+        assertEquals(0, existing.getFreeTickets(retained));
+    }
+
+    @Test
+    public void failedReconciliationRetainsIntentForRetry() throws Exception {
+        Fixture fixture = new Fixture();
+        fixture.write(new BlockPos(-31, 5, 49), Blocks.COMPOSTER.defaultBlockState());
+        IllegalStateException failure = new IllegalStateException("POI storage failure");
+        doThrow(failure).when(fixture.manager).add(any(), any());
+
+        onOwner(() -> assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> NativeStructurePoiUpdates.reconcile(fixture.loaded))));
+
+        assertArrayEquals(new long[]{16L}, fixture.marker());
+        fixture.allowPoiAdds();
+        onOwner(() -> NativeStructurePoiUpdates.reconcile(fixture.loaded));
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void explicitPoiSuppressionAndReadOnlyFullChunksDoNotCreateIntent() {
+        Fixture fixture = new Fixture();
+        BlockPos position = new BlockPos(-31, 5, 49);
+        fixture.updates.setBlock(fixture.world, position, Blocks.COMPOSTER.defaultBlockState(),
+                4096, 17);
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+        ImposterProtoChunk full = mock(ImposterProtoChunk.class);
+        when(fixture.world.getChunk(any(BlockPos.class))).thenReturn(full);
+        fixture.updates.setBlock(fixture.world, position, Blocks.BARREL.defaultBlockState(), 2, 17);
+        assertFalse(fixture.proto.persistentDataContainer.has(DIRTY_SECTIONS));
+    }
+
+    @Test
+    public void invalidSectionBitsRetainTheStoredRecord() throws Exception {
+        Fixture fixture = new Fixture();
+        fixture.proto.persistentDataContainer.set(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY, new long[]{1L << 24});
+        onOwner(() -> assertThrows(IllegalArgumentException.class,
+                () -> NativeStructurePoiUpdates.reconcile(fixture.loaded)));
+        assertArrayEquals(new long[]{1L << 24}, fixture.marker());
+    }
+
+    private static void onOwner(Runnable action) throws Exception {
+        FutureTask<Void> task = new FutureTask<>(action, null);
+        new TickThread(task, "Native POI test").start();
+        task.get(5L, TimeUnit.SECONDS);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blocks = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> biome = Holder.direct((Biome) null);
+        biomeIds.add(biome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(name -> biome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(blocks, air, PalettedContainer.codecRW(BlockState.CODEC, blocks, air),
+                biomes, biome, PalettedContainer.codecRO(biomeCodec, biomes, biome),
+                PalettedContainer.codecRW(biomeCodec, biomes, biome));
+    }
+
+    private static final class Fixture {
+        private final NativeStructurePoiUpdates updates = new NativeStructurePoiUpdates(4096);
+        private final ProtoChunk proto = new ProtoChunk(new ChunkPos(-2, 3), UpgradeData.EMPTY,
+                LevelHeightAccessor.create(-64, 384), containerFactory(), null);
+        private final LevelChunk loaded = mock(LevelChunk.class);
+        private final WorldGenLevel world = mock(WorldGenLevel.class);
+        private final PoiManager manager = mock(PoiManager.class);
+        private final Map<Long, PoiSection> pois = new HashMap<>();
+
+        private Fixture() {
+            ServerLevel level = mock(ServerLevel.class);
+            when(level.getPoiManager()).thenReturn(manager);
+            loaded.persistentDataContainer = proto.persistentDataContainer;
+            when(loaded.getLevel()).thenReturn(level);
+            when(loaded.getPos()).thenReturn(proto.getPos());
+            when(loaded.getSectionsCount()).thenReturn(proto.getSectionsCount());
+            when(loaded.getSectionYFromSectionIndex(anyInt())).thenAnswer(call -> proto.getSectionYFromSectionIndex(call.getArgument(0)));
+            when(loaded.getSection(anyInt())).thenAnswer(call -> proto.getSection(call.getArgument(0)));
+            when(loaded.getBlockState(any())).thenAnswer(call -> proto.getBlockState(call.getArgument(0)));
+            when(world.getChunk(any(BlockPos.class))).thenReturn(proto);
+            when(world.setBlock(any(), any(), anyInt(), anyInt())).thenAnswer(call -> {
+                proto.setBlockState(call.getArgument(0), call.getArgument(1), call.getArgument(2));
+                return true;
+            });
+            when(manager.getOrLoad(anyLong())).thenAnswer(call -> Optional.ofNullable(pois.get((long) call.getArgument(0))));
+            when(manager.getType(any())).thenAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                PoiSection section = pois.get(SectionPos.of(position).asLong());
+                return section == null ? Optional.empty() : section.getType(position);
+            });
+            doAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                pois.get(SectionPos.of(position).asLong()).remove(position);
+                return null;
+            }).when(manager).remove(any());
+            allowPoiAdds();
+        }
+
+        private void allowPoiAdds() {
+            doAnswer(call -> {
+                BlockPos position = call.getArgument(0);
+                return pois.computeIfAbsent(SectionPos.of(position).asLong(), ignored -> new PoiSection(() -> {}))
+                        .add(position, call.getArgument(1));
+            }).when(manager).add(any(), any());
+        }
+
+        private void write(BlockPos position, BlockState state) {
+            updates.setBlock(world, position, state, Block.UPDATE_CLIENTS, Block.UPDATE_LIMIT);
+        }
+
+        private long[] marker() {
+            return proto.persistentDataContainer.get(DIRTY_SECTIONS, PersistentDataType.LONG_ARRAY);
+        }
+
+        private PoiSection records() {
+            return pois.get(SectionPos.of(new BlockPos(-31, 5, 49)).asLong());
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NativeStructureWorldgenAccessTest.java

@@ -0,0 +1,466 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureWorldgenAccess;
+
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructurePostProcessor;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureTerrainIntegrator;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.entity.Entity;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Rotation;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.entity.EntityTypeTest;
+import net.minecraft.world.level.levelgen.GenerationStep;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.BoundingBox;
+import net.minecraft.world.level.levelgen.structure.PoolElementStructurePiece;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.TerrainAdjustment;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pools.StructurePoolElement;
+import net.minecraft.world.level.levelgen.structure.pools.StructureTemplatePool;
+import net.minecraft.world.level.levelgen.structure.structures.DesertPyramidStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.GravityProcessor;
+import net.minecraft.world.level.levelgen.structure.templatesystem.LiquidSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructurePlaceSettings;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplate;
+import net.minecraft.world.level.material.Fluid;
+import net.minecraft.world.level.material.FluidState;
+import net.minecraft.world.phys.AABB;
+import net.minecraft.world.phys.Vec3;
+import net.minecraft.world.ticks.LevelTickAccess;
+import net.minecraft.world.ticks.ScheduledTick;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class NativeStructureWorldgenAccessTest {
+    private static final int GENERATION_CENTER_X = 60;
+    private static final int GENERATION_CENTER_Z = 15;
+    private static final int SURFACE_FIRST_FREE_Y = 80;
+    private static final int FLOOR_FIRST_FREE_Y = 70;
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void ordinaryWorldFlattenPreparationHandlesReferencedVillagePiecesBeyondEightChunks() {
+        int farX = (GENERATION_CENTER_X - 9) << 4;
+        int farZ = (GENERATION_CENTER_Z + 4) << 4;
+        BoundingBox bounds = new BoundingBox(farX, 64, farZ, farX + 4, 90, farZ + 4);
+        PoolElementStructurePiece piece = new PoolElementStructurePiece(
+                null, StructurePoolElement.single("minecraft:empty").apply(StructureTemplatePool.Projection.RIGID),
+                new BlockPos(farX, 64, farZ), 1, Rotation.NONE, bounds, LiquidSettings.APPLY_WATERLOGGING);
+        Structure structure = new DesertPyramidStructure(new Structure.StructureSettings(
+                HolderSet.empty(), Map.of(), GenerationStep.Decoration.SURFACE_STRUCTURES, TerrainAdjustment.BEARD_BOX));
+        StructureStart start = new StructureStart(structure, generationCenter(), 0, new PiecesContainer(List.of(piece)));
+        List<NativeStructureTerrainIntegrator.TerrainTarget> targets = List.of(
+                new NativeStructureTerrainIntegrator.TerrainTarget("minecraft:village_plains", start,
+                        new IrisStructureTerrain().setMode(StructureTerrainMode.FLATTEN)));
+        BoundingBox area = new BoundingBox(generationCenter().getMinBlockX(), -64, generationCenter().getMinBlockZ(),
+                generationCenter().getMaxBlockX(), 319, generationCenter().getMaxBlockZ());
+        RecordingDelegate unbounded = new RecordingDelegate();
+        unbounded.rejectDistantTerrainReads = true;
+
+        assertThrows(IllegalStateException.class, () -> NativeStructurePostProcessor.prepareTerrain(
+                unbounded.world(), area, targets, (palette, rng, x, y, z) -> Blocks.STONE.defaultBlockState()));
+
+        RecordingDelegate recording = new RecordingDelegate();
+        recording.rejectDistantTerrainReads = true;
+        NativeStructureWorldgenAccess access = access(recording);
+        NativeStructurePostProcessor.prepareTerrain(
+                access, area, targets, (palette, rng, x, y, z) -> Blocks.STONE.defaultBlockState());
+
+        assertEquals(0, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+        assertEquals(0, recording.terrainReads);
+        assertEquals(0, recording.mutations);
+        assertEquals(91, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG,
+                generationCenter().getMinBlockX(), generationCenter().getMinBlockZ()));
+        assertEquals(1, recording.heightReads);
+    }
+
+    @Test
+    public void projectedTemplatePrefiltersUseRemoteTerrainAndRetainLocalHeightmaps() {
+        RecordingDelegate recording = new RecordingDelegate();
+        recording.rejectDistantTerrainReads = true;
+        NativeStructureWorldgenAccess access = access(recording);
+        GravityProcessor gravity = new GravityProcessor(Heightmap.Types.WORLD_SURFACE_WG, -1);
+        BlockPos remote = new BlockPos((GENERATION_CENTER_X - 9) << 4, 64, (GENERATION_CENTER_Z + 4) << 4);
+        StructureTemplate.StructureBlockInfo raw = new StructureTemplate.StructureBlockInfo(
+                new BlockPos(0, 4, 0), Blocks.DIRT_PATH.defaultBlockState(), null);
+        StructurePlaceSettings settings = new StructurePlaceSettings().addProcessor(gravity);
+
+        StructureTemplate.StructureBlockInfo projected = StructureTemplate.processBlockInfos(
+                access, remote, BlockPos.ZERO, settings, List.of(raw)).getFirst();
+
+        assertEquals(remote.atY(SURFACE_FIRST_FREE_Y + 3), projected.pos());
+        assertEquals(0, recording.heightReads);
+        BlockPos local = generationCenter().getMiddleBlockPosition(64);
+        StructureTemplate.StructureBlockInfo localBlock = new StructureTemplate.StructureBlockInfo(
+                BlockPos.ZERO, Blocks.DIRT_PATH.defaultBlockState(), null);
+        StructureTemplate.StructureBlockInfo localProjection = StructureTemplate.processBlockInfos(
+                access, local, BlockPos.ZERO, settings, List.of(localBlock)).getFirst();
+        assertEquals(local.atY(90), localProjection.pos());
+        assertEquals(1, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+    }
+
+    @Test
+    public void distanceTwoTerrainReadsNeverReachTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        int x = generationCenter.getMiddleBlockX();
+        int z = (generationCenter.z() + 2) << 4;
+
+        assertSame(Blocks.STONE, access.getBlockState(new BlockPos(x, FLOOR_FIRST_FREE_Y - 1, z)).getBlock());
+        assertSame(Blocks.WATER, access.getBlockState(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)).getBlock());
+        assertSame(Blocks.AIR, access.getBlockState(new BlockPos(x, SURFACE_FIRST_FREE_Y, z)).getBlock());
+        assertSame(Blocks.WATER.defaultBlockState().getFluidState(),
+                access.getFluidState(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)));
+        assertEquals(SURFACE_FIRST_FREE_Y, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z));
+        assertEquals(FLOOR_FIRST_FREE_Y, access.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, x, z));
+        assertNull(access.getBlockStateIfLoaded(new BlockPos(x, FLOOR_FIRST_FREE_Y, z)));
+        assertNull(access.getChunk(generationCenter.x(), generationCenter.z() + 2, ChunkStatus.FEATURES, false));
+        assertNull(access.getChunkIfLoadedImmediately(
+                generationCenter.x(), generationCenter.z() + 2));
+        List<BlockState> streamed = access.getBlockStates(new AABB(
+                x, FLOOR_FIRST_FREE_Y, z, x, FLOOR_FIRST_FREE_Y, z)).toList();
+
+        assertEquals(1, streamed.size());
+        assertSame(Blocks.WATER, streamed.getFirst().getBlock());
+        assertEquals(0, recording.terrainReads);
+        assertEquals(0, recording.heightReads);
+        assertEquals(0, recording.chunkReads);
+    }
+
+    @Test
+    public void distanceTwoMutationsAndSideEffectsNeverReachTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        BlockPos position = new BlockPos(
+                generationCenter.getMiddleBlockX(),
+                FLOOR_FIRST_FREE_Y,
+                (generationCenter.z() + 2) << 4);
+
+        assertFalse(access.ensureCanWrite(position));
+        assertFalse(access.setBlock(position, Blocks.DIRT.defaultBlockState(), 2));
+        assertFalse(access.removeBlock(position, false));
+        assertFalse(access.destroyBlock(position, false));
+        access.updateNeighborsAt(position, Blocks.DIRT);
+        access.neighborShapeChanged(
+                Direction.NORTH, position, position.north(),
+                Blocks.DIRT.defaultBlockState(), 2, 512);
+        access.levelEvent(null, 2001, position, 0);
+        access.gameEvent(null, Vec3.atCenterOf(position), null);
+        access.addParticle(null, position.getX(), position.getY(), position.getZ(), 0, 0, 0);
+        access.getBlockTicks().schedule(new ScheduledTick<>(
+                Blocks.DIRT, position, 1L, 0L));
+
+        assertEquals(0, recording.mutations);
+        assertEquals(0, recording.events);
+        assertEquals(0, recording.blockTicks.count());
+    }
+
+    @Test
+    public void radiusOneReadsWritesAndTicksRemainUnchanged() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        BlockPos position = new BlockPos(
+                (generationCenter.x() + 1) << 4,
+                FLOOR_FIRST_FREE_Y,
+                (generationCenter.z() - 1) << 4);
+
+        assertTrue(access.isInsideGenerationRegion(
+                generationCenter.x() + 1, generationCenter.z() - 1));
+        assertSame(Blocks.DIRT, access.getBlockState(position).getBlock());
+        assertEquals(91, access.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, position.getX(), position.getZ()));
+        assertTrue(access.ensureCanWrite(position));
+        assertTrue(access.setBlock(position, Blocks.STONE.defaultBlockState(), 2));
+        assertTrue(access.removeBlock(position, false));
+        assertTrue(access.destroyBlock(position, false));
+        access.getBlockTicks().schedule(new ScheduledTick<>(
+                Blocks.DIRT, position, 1L, 0L));
+
+        assertEquals(1, recording.terrainReads);
+        assertEquals(1, recording.heightReads);
+        assertEquals(4, recording.mutations);
+        assertEquals(1, recording.blockTicks.count());
+    }
+
+    @Test
+    public void virtualizedHeightsHideInRegionTerrainFromTheDelegate() {
+        RecordingDelegate recording = new RecordingDelegate();
+        ChunkPos generationCenter = generationCenter();
+        NativeStructureWorldgenAccess access = NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter,
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                true,
+                position -> false);
+        int x = generationCenter.getMiddleBlockX();
+        int z = generationCenter.getMiddleBlockZ();
+
+        assertEquals(SURFACE_FIRST_FREE_Y, access.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z));
+        assertEquals(FLOOR_FIRST_FREE_Y, access.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, x, z));
+        assertEquals(0, recording.heightReads);
+    }
+
+    @Test
+    public void protectedCellsRemainReadableButRejectWritesTilesAndTicks() {
+        RecordingDelegate recording = new RecordingDelegate();
+        BlockPos position = generationCenter().getMiddleBlockPosition(70);
+        NativeStructureWorldgenAccess access = NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter(),
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                false,
+                position::equals);
+
+        assertSame(Blocks.DIRT, access.getBlockState(position).getBlock());
+        assertFalse(access.ensureCanWrite(position));
+        assertFalse(access.setBlock(position, Blocks.STONE.defaultBlockState(), 2));
+        assertFalse(access.removeBlock(position, false));
+        assertFalse(access.destroyBlock(position, false));
+        assertNull(access.getBlockEntity(position));
+        assertTrue(access.getBlockEntity(position, null).isEmpty());
+        access.getBlockTicks().schedule(new ScheduledTick<>(Blocks.DIRT, position, 1L, 0L));
+        access.updateNeighborsAt(position.east(), Blocks.DIRT);
+        access.neighborShapeChanged(
+                Direction.EAST, position, position.east(), Blocks.DIRT.defaultBlockState(), 2, 512);
+
+        assertEquals(1, recording.terrainReads);
+        assertEquals(0, recording.mutations);
+        assertEquals(0, recording.blockTicks.count());
+        assertTrue(access.setBlock(position.above(), Blocks.STONE.defaultBlockState(), 2));
+        assertEquals(1, recording.mutations);
+    }
+
+    @Test
+    public void statuslessChunkReadsPreserveWorldgenDelegateSemantics() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+
+        assertNull(access.getChunk(generationCenter.getWorldPosition()));
+
+        assertEquals(1, recording.statuslessChunkReads);
+        assertEquals(0, recording.statusChunkReads);
+    }
+
+    @Test
+    public void entityQueriesRejectDisjointAreasAndClampOverlaps() {
+        RecordingDelegate recording = new RecordingDelegate();
+        NativeStructureWorldgenAccess access = access(recording);
+        ChunkPos generationCenter = generationCenter();
+        int safeMaxX = generationCenter.getMaxBlockX() + 17;
+        int safeMinZ = generationCenter.getMinBlockZ() - 16;
+        int safeMaxZ = generationCenter.getMaxBlockZ() + 17;
+        AABB disjoint = new AABB(
+                safeMaxX, -64, safeMinZ,
+                safeMaxX + 16, 320, safeMaxZ);
+        AABB overlap = new AABB(
+                safeMaxX - 8, -128, safeMinZ - 8,
+                safeMaxX + 16, 400, safeMaxZ + 8);
+        EntityTypeTest<Entity, Entity> type = EntityTypeTest.forClass(Entity.class);
+
+        assertTrue(access.getEntities((Entity) null, disjoint, entity -> true).isEmpty());
+        assertTrue(access.getEntities(type, disjoint, entity -> true).isEmpty());
+        access.getEntities((Entity) null, overlap, entity -> true);
+        access.getEntities(type, overlap, entity -> true);
+
+        assertEquals(2, recording.entityAreas.size());
+        for (AABB delegatedArea : recording.entityAreas) {
+            assertEquals(safeMaxX - 8, delegatedArea.minX, 0D);
+            assertEquals(-64, delegatedArea.minY, 0D);
+            assertEquals(safeMinZ, delegatedArea.minZ, 0D);
+            assertEquals(safeMaxX, delegatedArea.maxX, 0D);
+            assertEquals(320, delegatedArea.maxY, 0D);
+            assertEquals(safeMaxZ, delegatedArea.maxZ, 0D);
+        }
+    }
+
+    private static NativeStructureWorldgenAccess access(RecordingDelegate recording) {
+        return NativeStructureWorldgenAccess.create(
+                recording.world(), generationCenter(),
+                (x, z) -> SURFACE_FIRST_FREE_Y,
+                (x, z) -> FLOOR_FIRST_FREE_Y,
+                false,
+                position -> false);
+    }
+
+    private static ChunkPos generationCenter() {
+        return new ChunkPos(GENERATION_CENTER_X, GENERATION_CENTER_Z);
+    }
+
+    private static final class RecordingDelegate implements InvocationHandler {
+        private final Holder<Biome> biome;
+        private final BiomeManager biomeManager;
+        private final RecordingTicks<Block> blockTicks;
+        private final RecordingTicks<Fluid> fluidTicks;
+        private final List<AABB> entityAreas;
+        private int terrainReads;
+        private int heightReads;
+        private int chunkReads;
+        private int statuslessChunkReads;
+        private int statusChunkReads;
+        private int mutations;
+        private int events;
+        private boolean rejectDistantTerrainReads;
+
+        private RecordingDelegate() {
+            this.biome = Holder.direct((Biome) null);
+            this.biomeManager = new BiomeManager((x, y, z) -> biome, 13L);
+            this.blockTicks = new RecordingTicks<>();
+            this.fluidTicks = new RecordingTicks<>();
+            this.entityAreas = new ArrayList<>();
+        }
+
+        private WorldGenLevel world() {
+            return (WorldGenLevel) Proxy.newProxyInstance(
+                    WorldGenLevel.class.getClassLoader(),
+                    new Class<?>[]{WorldGenLevel.class}, this);
+        }
+
+        @Override
+        public Object invoke(Object proxy, Method method, Object[] arguments) {
+            String name = method.getName();
+            if (name.equals("getSeaLevel")) {
+                return 63;
+            }
+            if (name.equals("getBiome")) {
+                return biome;
+            }
+            if (name.equals("getBiomeManager")) {
+                return biomeManager;
+            }
+            if (name.equals("getBlockTicks")) {
+                return blockTicks;
+            }
+            if (name.equals("getFluidTicks")) {
+                return fluidTicks;
+            }
+            if (name.equals("getMinY")) {
+                return -64;
+            }
+            if (name.equals("getHeight") && arguments == null) {
+                return 384;
+            }
+            if (name.equals("getHeight")) {
+                if (rejectDistantTerrainReads
+                        && (Math.abs(((int) arguments[1] >> 4) - GENERATION_CENTER_X) > 1
+                        || Math.abs(((int) arguments[2] >> 4) - GENERATION_CENTER_Z) > 1)) {
+                    throw new IllegalStateException("Requested chunk unavailable during world generation");
+                }
+                heightReads++;
+                return 91;
+            }
+            if (name.equals("getBlockState")) {
+                terrainReads++;
+                return Blocks.DIRT.defaultBlockState();
+            }
+            if (name.equals("getFluidState")) {
+                terrainReads++;
+                return Blocks.WATER.defaultBlockState().getFluidState();
+            }
+            if (name.equals("getChunk")) {
+                chunkReads++;
+                if (arguments.length == 2) {
+                    statuslessChunkReads++;
+                } else {
+                    statusChunkReads++;
+                }
+                return null;
+            }
+            if (name.equals("getChunkIfLoadedImmediately")) {
+                chunkReads++;
+                return null;
+            }
+            if (name.equals("getEntities")) {
+                entityAreas.add((AABB) arguments[1]);
+                return List.of();
+            }
+            if (name.equals("ensureCanWrite") || name.equals("setBlock")
+                    || name.equals("removeBlock") || name.equals("destroyBlock")) {
+                mutations++;
+                return true;
+            }
+            if (name.equals("updateNeighborsAt") || name.equals("neighborShapeChanged")) {
+                mutations++;
+                return null;
+            }
+            if (name.equals("levelEvent") || name.equals("gameEvent") || name.equals("addParticle")) {
+                events++;
+                return null;
+            }
+            if (name.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (name.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (name.equals("toString")) {
+                return "native-structure-worldgen-test-delegate";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        }
+    }
+
+    private static final class RecordingTicks<T> implements LevelTickAccess<T> {
+        private int count;
+
+        @Override
+        public void schedule(ScheduledTick<T> tick) {
+            count++;
+        }
+
+        @Override
+        public boolean hasScheduledTick(BlockPos position, T type) {
+            return false;
+        }
+
+        @Override
+        public int count() {
+            return count;
+        }
+
+        @Override
+        public boolean willTickThisTick(BlockPos position, T type) {
+            return false;
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NmsChunkIOFlushTest.java

@@ -0,0 +1,101 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainAccessImpl;
+import ca.spottedleaf.moonrise.patches.chunk_system.io.MoonriseRegionFileIO.RegionDataController;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ServerLevel;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkIOFlushTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void nativeDrainCanWaitOffOwnerUntilChunkPoiAndEntityIoFinish() throws Exception {
+        Fixture fixture = new Fixture();
+        AtomicBoolean chunkPending = new AtomicBoolean(true);
+        AtomicBoolean poiPending = new AtomicBoolean(true);
+        AtomicBoolean entityPending = new AtomicBoolean(true);
+        CountDownLatch chunkDrain = new CountDownLatch(1);
+        CountDownLatch poiDrain = new CountDownLatch(1);
+        CountDownLatch entityDrain = new CountDownLatch(1);
+        when(fixture.chunks.hasTasks()).thenAnswer(invocation -> {
+            chunkDrain.countDown();
+            return chunkPending.get();
+        });
+        when(fixture.pois.hasTasks()).thenAnswer(invocation -> {
+            poiDrain.countDown();
+            return poiPending.get();
+        });
+        when(fixture.entities.hasTasks()).thenAnswer(invocation -> {
+            entityDrain.countDown();
+            return entityPending.get();
+        });
+        ExecutorService io = Executors.newSingleThreadExecutor();
+        try {
+            Future<?> drain = io.submit(() -> fixture.binding.flushChunkIO(fixture.world));
+            assertTrue(chunkDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            chunkPending.set(false);
+            assertTrue(poiDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            poiPending.set(false);
+            assertTrue(entityDrain.await(5L, TimeUnit.SECONDS));
+            assertFalse(drain.isDone());
+            entityPending.set(false);
+            drain.get(5L, TimeUnit.SECONDS);
+        } finally {
+            chunkPending.set(false);
+            poiPending.set(false);
+            entityPending.set(false);
+            io.shutdownNow();
+            assertTrue(io.awaitTermination(5L, TimeUnit.SECONDS));
+        }
+    }
+
+    @Test
+    public void nativeDrainFailurePropagatesToItsCompletionReceipt() {
+        Fixture fixture = new Fixture();
+        IllegalStateException failure = new IllegalStateException("native IO failed");
+        when(fixture.chunks.hasTasks()).thenThrow(failure);
+        assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> fixture.binding.flushChunkIO(fixture.world)));
+    }
+
+    private static final class Fixture {
+        private final NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        private final CraftWorld world = mock(CraftWorld.class);
+        private final ServerLevel level = mock(ServerLevel.class);
+        private final RegionDataController chunks = mock(RegionDataController.class);
+        private final RegionDataController pois = mock(RegionDataController.class);
+        private final RegionDataController entities = mock(RegionDataController.class);
+
+        private Fixture() {
+            when(world.getHandle()).thenReturn(level);
+            when(level.moonrise$getChunkDataController()).thenReturn(chunks);
+            when(level.moonrise$getPoiChunkDataController()).thenReturn(pois);
+            when(level.moonrise$getEntityChunkDataController()).thenReturn(entities);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NmsChunkRetentionTest.java

@@ -0,0 +1,84 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainAccessImpl;
+import ca.spottedleaf.moonrise.patches.chunk_system.scheduling.ChunkHolderManager;
+import ca.spottedleaf.moonrise.patches.chunk_system.scheduling.ChunkTaskScheduler;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.level.ChunkLevel;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.TicketType;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.lang.reflect.Field;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.ArgumentMatchers.same;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkRetentionTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void retentionRequestsNothingBeyondTheOuterRingOfAFullRequest() {
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        assertEquals(ChunkLevel.RADIUS_AROUND_FULL_CHUNK, binding.fullChunkDependencyRadius());
+        assertEquals(ChunkLevel.MAX_LEVEL, ChunkHolderManager.MAX_TICKET_LEVEL);
+        assertEquals(ChunkLevel.generationStatus(ChunkLevel.FULL_CHUNK_LEVEL + binding.fullChunkDependencyRadius()),
+                ChunkLevel.generationStatus(ChunkHolderManager.MAX_TICKET_LEVEL));
+        assertEquals(ChunkStatus.STRUCTURE_STARTS, ChunkLevel.generationStatus(ChunkHolderManager.MAX_TICKET_LEVEL));
+    }
+
+    @Test
+    public void retainAndReleaseUseOnePermanentNonPersistentTicketAtTheMaximumLevel() throws Exception {
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        ChunkTaskScheduler scheduler = mock(ChunkTaskScheduler.class);
+        ChunkHolderManager manager = mock(ChunkHolderManager.class);
+        Field managerField = ChunkTaskScheduler.class.getField("chunkHolderManager");
+        managerField.setAccessible(true);
+        managerField.set(scheduler, manager);
+        when(world.getHandle()).thenReturn(level);
+        when(level.moonrise$getChunkTaskScheduler()).thenReturn(scheduler);
+        when(manager.addTicketAtLevel(any(TicketType.class), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull()))
+                .thenReturn(true);
+        when(manager.removeTicketAtLevel(any(TicketType.class), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull()))
+                .thenReturn(true);
+
+        assertTrue(binding.retainChunk(world, 3, -4));
+        ArgumentCaptor<TicketType> type = ArgumentCaptor.forClass(TicketType.class);
+        verify(manager).addTicketAtLevel(type.capture(), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+        assertEquals(TicketType.NO_TIMEOUT, type.getValue().timeout());
+        assertTrue(type.getValue().doesLoad());
+        assertFalse(type.getValue().doesSimulate());
+        assertFalse(type.getValue().persist());
+
+        assertTrue(binding.releaseChunk(world, 3, -4));
+        verify(manager).removeTicketAtLevel(same(type.getValue()), eq(3), eq(-4), eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+
+        binding.retainChunk(world, 3, -4);
+        ArgumentCaptor<TicketType> again = ArgumentCaptor.forClass(TicketType.class);
+        verify(manager, times(2)).addTicketAtLevel(again.capture(), eq(3), eq(-4),
+                eq(ChunkHolderManager.MAX_TICKET_LEVEL), isNull());
+        assertSame(type.getValue(), again.getValue());
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NmsChunkTaskPollingTest.java

@@ -0,0 +1,96 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainAccessImpl;
+import art.arcane.volmlib.util.scheduling.FoliaScheduler;
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerChunkCache;
+import net.minecraft.server.level.ServerLevel;
+import org.bukkit.Bukkit;
+import org.bukkit.Server;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.util.concurrent.CompletableFuture;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+public class NmsChunkTaskPollingTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void serverOwnerPumpsOnlyTheTargetWorldQueue() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        MinecraftServer server = mock(MinecraftServer.class);
+        ServerChunkCache chunks = mock(ServerChunkCache.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        CompletableFuture<Void> completed = new CompletableFuture<>();
+        when(world.getHandle()).thenReturn(level);
+        when(level.getServer()).thenReturn(server);
+        when(server.getRunningThread()).thenReturn(Thread.currentThread());
+        when(level.getChunkSource()).thenReturn(chunks);
+        when(chunks.pollTask()).thenAnswer(invocation -> completed.complete(null)).thenReturn(false);
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(false);
+            assertTrue(binding.pollChunkTask(world));
+            assertTrue(completed.isDone());
+            assertFalse(binding.pollChunkTask(world));
+        }
+        verify(chunks, times(2)).pollTask();
+        verify(server, never()).executeAllRecentInternalTasks();
+    }
+
+    @Test
+    public void nonOwnerIsRejectedBeforeAccessingTheChunkQueue() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        ServerLevel level = mock(ServerLevel.class);
+        MinecraftServer server = mock(MinecraftServer.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        when(world.getHandle()).thenReturn(level);
+        when(level.getServer()).thenReturn(server);
+        when(server.getRunningThread()).thenReturn(new Thread("Other server owner"));
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(false);
+            assertThrows(IllegalStateException.class, () -> binding.pollChunkTask(world));
+        }
+        verify(level, never()).getChunkSource();
+    }
+
+    @Test
+    public void foliaNeverUsesTheWorldWideTaskPump() {
+        Server bukkitServer = mock(Server.class);
+        CraftWorld world = mock(CraftWorld.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        try (MockedStatic<Bukkit> bukkit = mockStatic(Bukkit.class);
+             MockedStatic<FoliaScheduler> folia = mockStatic(FoliaScheduler.class)) {
+            bukkit.when(Bukkit::getServer).thenReturn(bukkitServer);
+            folia.when(() -> FoliaScheduler.isRegionizedRuntime(bukkitServer)).thenReturn(true);
+            assertFalse(binding.pollChunkTask(world));
+        }
+        verifyNoInteractions(world);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/NmsEntitySpawnDifficultyTest.java

@@ -0,0 +1,104 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainAccessImpl;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.server.Bootstrap;
+import org.bukkit.Difficulty;
+import org.bukkit.Location;
+import org.bukkit.craftbukkit.CraftWorld;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.EntityType;
+import org.bukkit.event.entity.CreatureSpawnEvent;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.List;
+
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.doReturn;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+public class NmsEntitySpawnDifficultyTest {
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void peacefulRejectsEveryNativeForbiddenTypeBeforeBukkitCreatesIt() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        int rejected = 0;
+
+        for (EntityType type : EntityType.values()) {
+            if (type.getEntityClass() == null) {
+                continue;
+            }
+            if (BuiltInRegistries.ENTITY_TYPE.getValue(Identifier.parse(type.getKey().toString())).isAllowedInPeaceful()) {
+                continue;
+            }
+            assertNull(type.name(), binding.spawnEntity(location, type, CreatureSpawnEvent.SpawnReason.NATURAL));
+            rejected++;
+        }
+
+        assertTrue(rejected > 20);
+        verify(world, never()).spawn(any(Location.class), any(Class.class), isNull(), any(CreatureSpawnEvent.SpawnReason.class));
+    }
+
+    @Test
+    public void peacefulPreservesPassiveAndNativeMonsterCategoryExceptions() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        Entity created = mock(Entity.class);
+        doReturn(created).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        for (EntityType type : List.of(EntityType.COW, EntityType.VILLAGER, EntityType.WOLF, EntityType.PIGLIN, EntityType.SHULKER)) {
+            assertSame(type.name(), created, binding.spawnEntity(location, type, CreatureSpawnEvent.SpawnReason.NATURAL));
+        }
+    }
+
+    @Test
+    public void nonPeacefulDifficultiesPreserveHostileSpawns() {
+        CraftWorld world = mock(CraftWorld.class);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        Entity created = mock(Entity.class);
+        doReturn(created).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        for (Difficulty difficulty : List.of(Difficulty.EASY, Difficulty.NORMAL, Difficulty.HARD)) {
+            when(world.getDifficulty()).thenReturn(difficulty);
+            assertSame(created, binding.spawnEntity(location, EntityType.ZOMBIE, CreatureSpawnEvent.SpawnReason.NATURAL));
+        }
+    }
+
+    @Test
+    public void unrelatedBukkitSpawnFailuresStillPropagate() {
+        CraftWorld world = mock(CraftWorld.class);
+        when(world.getDifficulty()).thenReturn(Difficulty.PEACEFUL);
+        NativeTerrainAccessImpl binding = mock(NativeTerrainAccessImpl.class, CALLS_REAL_METHODS);
+        Location location = new Location(world, 0.5, 80, 0.5);
+        IllegalStateException failure = new IllegalStateException("Spawn rejected by platform");
+        doThrow(failure).when(world).spawn(eq(location), any(Class.class), isNull(), eq(CreatureSpawnEvent.SpawnReason.NATURAL));
+
+        assertSame(failure, assertThrows(IllegalStateException.class,
+                () -> binding.spawnEntity(location, EntityType.COW, CreatureSpawnEvent.SpawnReason.NATURAL)));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/platform/bukkit/nms/v26_3_R1/WorldgenTerrainHeightmapsTest.java

@@ -0,0 +1,347 @@
+package art.arcane.iris.platform.bukkit.nms.v26_3_R1;
+
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeTerrainPipeline;
+
+import art.arcane.iris.nativegen.v26_3_R1.NativeBlockTags;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.WorldgenTerrainHeightmaps;
+import com.mojang.serialization.Codec;
+import net.minecraft.SharedConstants;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.IdMapper;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.LevelChunkSection;
+import net.minecraft.world.level.chunk.PalettedContainer;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.Strategy;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.structures.IglooPieces;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Proxy;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.IntBinaryOperator;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+public class WorldgenTerrainHeightmapsTest {
+    private static final int MIN_Y = -64;
+    private static final int HEIGHT = 384;
+    private static final int LAND_TERRAIN_TOP = 70;
+    private static final int LAND_CANOPY_TOP = 80;
+    private static final int OCEAN_FLOOR_TOP = 60;
+    private static final int OCEAN_FLUID_TOP = 64;
+    private static final int LAND_X = 3;
+    private static final int LAND_Z = 5;
+    private static final int OCEAN_X = 8;
+    private static final int OCEAN_Z = 8;
+    private static final int TERRAIN_SLAB_DEPTH = 4;
+
+    @BeforeClass
+    public static void bootstrapMinecraftRegistries() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+        NativeBlockTags.bindHeightmapFixtures();
+    }
+
+    @Test
+    public void authoringHeightmapsReadPlacedObjectsAndFluidsWithoutTerrainResolvers() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        NativeTerrainPipeline.primeAuthoringHeightmaps(chunk);
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(Heightmap.Types.MOTION_BLOCKING, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP + 6,
+                chunk.getHeight(Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, LAND_X, LAND_Z));
+        assertEquals(OCEAN_FLUID_TOP, chunk.getHeight(Heightmap.Types.WORLD_SURFACE_WG, OCEAN_X, OCEAN_Z));
+        assertEquals(OCEAN_FLOOR_TOP, chunk.getHeight(Heightmap.Types.OCEAN_FLOOR_WG, OCEAN_X, OCEAN_Z));
+    }
+
+    @Test
+    public void primeTerrainWritesEngineSurfaceAndOceanFloorHeights() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertFalse(chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertFalse(chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertTrue(chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(OCEAN_FLUID_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, OCEAN_X, OCEAN_Z));
+        assertEquals(OCEAN_FLOOR_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, OCEAN_X, OCEAN_Z));
+    }
+
+    @Test
+    public void finalHeightmapPrimingDoesNotClobberTheWorldgenHeightmaps() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+        Heightmap.primeHeightmaps(chunk, ChunkStatus.FINAL_HEIGHTMAPS);
+
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.OCEAN_FLOOR_WG, LAND_X, LAND_Z));
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void unprimedWorldgenHeightmapResolvesTheIrisCanopyInstead() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void primeTerrainOverwritesAnAlreadyLazyPrimedCanopyHeight() {
+        ProtoChunk chunk = terrainChunk(new ChunkPos(0, 0));
+
+        assertEquals(LAND_CANOPY_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        WorldgenTerrainHeightmaps.primeTerrain(chunk, surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    @Test
+    public void structurePlacementPrimesTheWestNeighbourAnIglooEntranceReads() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        chunks.put(ChunkPos.pack(0, 0), terrainChunk(new ChunkPos(0, 0)));
+        chunks.put(ChunkPos.pack(-1, 0), terrainChunk(new ChunkPos(-1, 0)));
+        WorldGenLevel world = world(chunks);
+        StructureStart start = startInOrigin();
+
+        int canopySnap = IglooPieces.GENERATION_HEIGHT + iglooSnapOffset(world);
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(start), surfaceFirstFreeY(), floorFirstFreeY());
+        int terrainSnap = IglooPieces.GENERATION_HEIGHT + iglooSnapOffset(world);
+
+        assertEquals(LAND_TERRAIN_TOP + 1, world.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, -2, 5));
+        assertEquals(LAND_TERRAIN_TOP, terrainSnap);
+        assertEquals(LAND_CANOPY_TOP, canopySnap);
+        assertEquals(LAND_CANOPY_TOP - LAND_TERRAIN_TOP, canopySnap - terrainSnap);
+    }
+
+    @Test
+    public void structurePlacementPrimesEveryChunkTheStartFootprintTouches() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        for (int chunkX = -1; chunkX <= 1; chunkX++) {
+            for (int chunkZ = -1; chunkZ <= 1; chunkZ++) {
+                chunks.put(ChunkPos.pack(chunkX, chunkZ), terrainChunk(new ChunkPos(chunkX, chunkZ)));
+            }
+        }
+        WorldGenLevel world = world(chunks);
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(startInOrigin()),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        for (ChunkAccess chunk : chunks.values()) {
+            assertTrue(chunk.getPos().toString(),
+                    chunk.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+            assertTrue(chunk.getPos().toString(),
+                    chunk.hasPrimedHeightmap(Heightmap.Types.OCEAN_FLOOR_WG));
+            assertEquals(LAND_TERRAIN_TOP, chunk.getHeight(
+                    Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+        }
+    }
+
+    @Test
+    public void structurePlacementDoesNotPrimeALoadedDistanceTwoChunk() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        ProtoChunk origin = terrainChunk(new ChunkPos(0, 0));
+        ProtoChunk neighbour = terrainChunk(new ChunkPos(1, 0));
+        ProtoChunk distanceTwo = terrainChunk(new ChunkPos(2, 0));
+        chunks.put(ChunkPos.pack(0, 0), origin);
+        chunks.put(ChunkPos.pack(1, 0), neighbour);
+        chunks.put(ChunkPos.pack(2, 0), distanceTwo);
+        WorldGenLevel world = world(chunks);
+        StructureStart shifted = startInOrigin();
+        shifted.getPieces().forEach(piece -> piece.move(16, 0, 0));
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(shifted),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(origin.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertTrue(neighbour.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertFalse(distanceTwo.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+    }
+
+    @Test
+    public void structurePlacementSkipsChunksOutsideTheGenerationRegion() {
+        Map<Long, ChunkAccess> chunks = new HashMap<>();
+        ProtoChunk origin = terrainChunk(new ChunkPos(0, 0));
+        chunks.put(ChunkPos.pack(0, 0), origin);
+        WorldGenLevel world = world(chunks);
+
+        WorldgenTerrainHeightmaps.primeStructurePlacement(
+                world, new ChunkPos(0, 0), List.of(startInOrigin()),
+                surfaceFirstFreeY(), floorFirstFreeY());
+
+        assertTrue(origin.hasPrimedHeightmap(Heightmap.Types.WORLD_SURFACE_WG));
+        assertEquals(LAND_TERRAIN_TOP, origin.getHeight(
+                Heightmap.Types.WORLD_SURFACE_WG, LAND_X, LAND_Z));
+    }
+
+    private static int iglooSnapOffset(WorldGenLevel world) {
+        return world.getHeight(Heightmap.Types.WORLD_SURFACE_WG, -2, 5)
+                - IglooPieces.GENERATION_HEIGHT - 1;
+    }
+
+    private static StructureStart startInOrigin() {
+        Structure structure = new SwampHutStructure(new Structure.StructureSettings(HolderSet.empty()));
+        SwampHutPiece piece = new SwampHutPiece(RandomSource.create(13L), 0, 0);
+        return new StructureStart(
+                structure, new ChunkPos(0, 0), 0, new PiecesContainer(List.of(piece)));
+    }
+
+    private static IntBinaryOperator surfaceFirstFreeY() {
+        return (x, z) -> isOcean(x, z) ? OCEAN_FLUID_TOP + 1 : LAND_TERRAIN_TOP + 1;
+    }
+
+    private static IntBinaryOperator floorFirstFreeY() {
+        return (x, z) -> isOcean(x, z) ? OCEAN_FLOOR_TOP + 1 : LAND_TERRAIN_TOP + 1;
+    }
+
+    private static boolean isOcean(int x, int z) {
+        return Math.floorMod(x, 16) == OCEAN_X && Math.floorMod(z, 16) == OCEAN_Z;
+    }
+
+    private static ProtoChunk terrainChunk(ChunkPos pos) {
+        ProtoChunk chunk = new ProtoChunk(
+                pos, UpgradeData.EMPTY, LevelHeightAccessor.create(MIN_Y, HEIGHT),
+                containerFactory(), null);
+        for (int x = 0; x < 16; x++) {
+            for (int z = 0; z < 16; z++) {
+                boolean ocean = isOcean(pos.getMinBlockX() + x, pos.getMinBlockZ() + z);
+                int stoneTop = ocean ? OCEAN_FLOOR_TOP : LAND_TERRAIN_TOP;
+                for (int y = stoneTop - TERRAIN_SLAB_DEPTH; y <= stoneTop; y++) {
+                    write(chunk, x, y, z, Blocks.STONE.defaultBlockState());
+                }
+                if (ocean) {
+                    for (int y = OCEAN_FLOOR_TOP + 1; y <= OCEAN_FLUID_TOP; y++) {
+                        write(chunk, x, y, z, Blocks.WATER.defaultBlockState());
+                    }
+                    continue;
+                }
+                for (int y = LAND_TERRAIN_TOP + 1; y <= LAND_TERRAIN_TOP + 6; y++) {
+                    write(chunk, x, y, z, Blocks.SPRUCE_LOG.defaultBlockState());
+                }
+                for (int y = LAND_TERRAIN_TOP + 7; y <= LAND_CANOPY_TOP; y++) {
+                    write(chunk, x, y, z, Blocks.SPRUCE_LEAVES.defaultBlockState());
+                }
+            }
+        }
+        return chunk;
+    }
+
+    private static void write(ProtoChunk chunk, int x, int y, int z, BlockState state) {
+        LevelChunkSection section = chunk.getSection(chunk.getSectionIndex(y));
+        section.setBlockState(x, y & 15, z, state, false);
+    }
+
+    private static PalettedContainerFactory containerFactory() {
+        Strategy<BlockState> blockStates = Strategy.createForBlockStates(Block.BLOCK_STATE_REGISTRY);
+        BlockState air = Blocks.AIR.defaultBlockState();
+        IdMapper<Holder<Biome>> biomeIds = new IdMapper<>();
+        Holder<Biome> defaultBiome = Holder.direct((Biome) null);
+        biomeIds.add(defaultBiome);
+        Strategy<Holder<Biome>> biomes = Strategy.createForBiomes(biomeIds);
+        Codec<Holder<Biome>> biomeCodec = Codec.STRING.xmap(
+                name -> defaultBiome, holder -> "iris-test-biome");
+        return new PalettedContainerFactory(
+                blockStates,
+                air,
+                PalettedContainer.codecRW(BlockState.CODEC, blockStates, air),
+                biomes,
+                defaultBiome,
+                PalettedContainer.codecRO(biomeCodec, biomes, defaultBiome),
+                PalettedContainer.codecRW(biomeCodec, biomes, defaultBiome));
+    }
+
+    private static WorldGenLevel world(Map<Long, ChunkAccess> chunks) {
+        InvocationHandler handler = (proxy, method, arguments) -> {
+            String methodName = method.getName();
+            if (methodName.equals("hasChunk")) {
+                return chunks.containsKey(ChunkPos.pack((int) arguments[0], (int) arguments[1]));
+            }
+            if (methodName.equals("getChunk") && arguments.length == 2) {
+                ChunkAccess chunk = chunks.get(ChunkPos.pack((int) arguments[0], (int) arguments[1]));
+                if (chunk == null) {
+                    throw new AssertionError("Heightmap priming requested an unavailable chunk "
+                            + arguments[0] + "," + arguments[1]);
+                }
+                return chunk;
+            }
+            if (methodName.equals("getHeight") && arguments.length == 3) {
+                Heightmap.Types type = (Heightmap.Types) arguments[0];
+                int x = (int) arguments[1];
+                int z = (int) arguments[2];
+                ChunkAccess chunk = chunks.get(ChunkPos.pack(x >> 4, z >> 4));
+                if (chunk == null) {
+                    throw new AssertionError("Heightmap read requested an unavailable chunk at "
+                            + x + "," + z);
+                }
+                return chunk.getHeight(type, x & 15, z & 15) + 1;
+            }
+            if (methodName.equals("getBlockState")) {
+                BlockPos position = (BlockPos) arguments[0];
+                ChunkAccess chunk = chunks.get(ChunkPos.pack(position.getX() >> 4, position.getZ() >> 4));
+                if (chunk == null) {
+                    throw new AssertionError("Block read requested an unavailable chunk at " + position);
+                }
+                return chunk.getBlockState(position);
+            }
+            if (methodName.equals("hashCode")) {
+                return System.identityHashCode(proxy);
+            }
+            if (methodName.equals("equals")) {
+                return proxy == arguments[0];
+            }
+            if (methodName.equals("toString")) {
+                return "worldgen-heightmap-test-world";
+            }
+            throw new UnsupportedOperationException(method.toString());
+        };
+        return (WorldGenLevel) Proxy.newProxyInstance(
+                WorldGenLevel.class.getClassLoader(), new Class<?>[]{WorldGenLevel.class}, handler);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/BareMobSpawnHistoryTest.java

@@ -0,0 +1,156 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.biome.IrisBiomeCustom;
+import art.arcane.iris.generation.biome.IrisBiomeCustomSpawn;
+import art.arcane.iris.generation.biome.IrisBiomeCustomSpawnType;
+import art.arcane.iris.pack.datapack.v263.DataFixerV263;
+import art.arcane.iris.spi.PlatformGenerationRegistry;
+import art.arcane.iris.world.history.GenerationRegistryContract;
+import art.arcane.iris.world.history.GenerationRegistryContractFactory;
+import art.arcane.volmlib.util.collection.KList;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import org.bukkit.Bukkit;
+import org.junit.AfterClass;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.Map;
+import java.util.Set;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThrows;
+
+public final class BareMobSpawnHistoryTest {
+    private static final String LEGACY_RENDERER_IDENTITY = "bukkit-v26_3_R1-generated-registry-json-v1";
+    private static final String NATURAL_MOB_SPAWNS = "minecraft:gameplay/natural_mob_spawns";
+    private static final GenerationRegistryContract.PhysicalResourceKey INSTALLED =
+            new GenerationRegistryContract.PhysicalResourceKey(
+                    GenerationRegistryContractFactory.BIOME_REGISTRY,
+                    "iris:biomes/" + "c".repeat(64)
+            );
+    private static HeadlessNativeRegistries loaded;
+    private static PlatformGenerationRegistry registry;
+
+    @BeforeClass
+    public static void installOverlayRendering() throws IOException {
+        assertNull(Bukkit.getServer());
+        loaded = HeadlessNativeRegistries.load(Map.of(
+                "data/iris/worldgen/biome/biomes/" + "c".repeat(64) + ".json",
+                spawningBiome().generateJson(new DataFixerV263())
+        ));
+        registry = new HeadlessNativePlatform(new File("unused-native-platform"), loaded::registries)
+                .generationRegistry();
+    }
+
+    @AfterClass
+    public static void closeRegistries() throws IOException {
+        if (loaded != null) {
+            loaded.close();
+        }
+    }
+
+    @Test
+    public void bareMobSpawnHistoryValidatesAgainstTheInstalledOverlayRendering() throws IOException {
+        GenerationRegistryContract legacy = legacyContract(INSTALLED, spawningBiome());
+        GenerationRegistryContract.GeneratedSource source = legacy.generatedSources().get(INSTALLED);
+        assertEquals(GenerationRegistryContract.FINGERPRINT_SCHEMA_VERSION_ONE, legacy.fingerprintSchema());
+        assertEquals(LEGACY_RENDERER_IDENTITY, source.rendererIdentity());
+        assertNotEquals(
+                JsonParser.parseString(source.sourceJson()),
+                JsonParser.parseString(registry.generatedDefinition(
+                        INSTALLED.registryKey(),
+                        INSTALLED.resourceKey()
+                ).value())
+        );
+
+        GenerationRegistryContract available = GenerationRegistryContractFactory.captureRequiredDefinitions(
+                Set.of(legacy),
+                new DataFixerV263(),
+                registry
+        );
+
+        legacy.requireDefinitionsAvailableIn(available);
+    }
+
+    @Test
+    public void bareMobSpawnHistoryStillRejectsDifferentSemantics() throws IOException {
+        GenerationRegistryContract changed = legacyContract(INSTALLED, spawningBiome().setTemperature(0.2D));
+
+        IOException failure = assertThrows(IOException.class,
+                () -> GenerationRegistryContractFactory.captureRequiredDefinitions(
+                        Set.of(changed),
+                        new DataFixerV263(),
+                        registry
+                ));
+
+        assertEquals("Historical generated registry definition changed for minecraft:worldgen/biome / "
+                + INSTALLED.resourceKey() + ".", failure.getMessage());
+    }
+
+    @Test
+    public void bareMobSpawnHistoryStillRejectsAMissingDefinition() throws IOException {
+        GenerationRegistryContract missing = legacyContract(new GenerationRegistryContract.PhysicalResourceKey(
+                GenerationRegistryContractFactory.BIOME_REGISTRY,
+                "iris:biomes/" + "d".repeat(64)
+        ), spawningBiome());
+
+        assertThrows(IOException.class, () -> GenerationRegistryContractFactory.captureRequiredDefinitions(
+                Set.of(missing),
+                new DataFixerV263(),
+                registry
+        ));
+    }
+
+    private static GenerationRegistryContract legacyContract(
+            GenerationRegistryContract.PhysicalResourceKey key,
+            IrisBiomeCustom biome
+    ) {
+        JsonObject rendered = JsonParser.parseString(biome.generateJson(new DataFixerV263())).getAsJsonObject();
+        JsonObject attributes = rendered.getAsJsonObject("attributes");
+        attributes.add(NATURAL_MOB_SPAWNS, attributes.getAsJsonObject(NATURAL_MOB_SPAWNS).get("argument"));
+        String captured = registry.canonicalDefinition(key.registryKey(), key.resourceKey(), rendered.toString())
+                .value();
+        String semantic = GenerationRegistryContractFactory.customBiomeEffectiveSemanticJson(biome, null);
+        GenerationRegistryContract.GeneratedSource source = new GenerationRegistryContract.GeneratedSource(
+                GenerationRegistryContractFactory.CUSTOM_BIOME_EFFECTIVE_SOURCE_SCHEMA,
+                GenerationRegistryContractFactory.fingerprintCustomBiomeAuthoredDefinition(semantic),
+                semantic,
+                LEGACY_RENDERER_IDENTITY,
+                GenerationRegistryContractFactory.fingerprintDefinition(
+                        key,
+                        PlatformGenerationRegistry.Definition.exactJson(captured),
+                        "generated"
+                ),
+                captured
+        );
+        return GenerationRegistryContract.fromDefinitionsAndGeneratedSources(
+                Map.of(key, GenerationRegistryContractFactory.fingerprintGeneratedSemantic(key, source)),
+                Map.of(key, source)
+        );
+    }
+
+    private static IrisBiomeCustom spawningBiome() {
+        return new IrisBiomeCustom()
+                .setId("tester")
+                .setSpawnRarity(2)
+                .setSpawns(new KList<>(
+                        new IrisBiomeCustomSpawn()
+                                .setType("minecraft:zombie")
+                                .setGroup(IrisBiomeCustomSpawnType.MONSTER)
+                                .setMinCount(2)
+                                .setMaxCount(4)
+                                .setWeight(7),
+                        new IrisBiomeCustomSpawn()
+                                .setType("minecraft:cow")
+                                .setGroup(IrisBiomeCustomSpawnType.CREATURE)
+                                .setMinCount(3)
+                                .setMaxCount(3)
+                                .setWeight(5)
+                ));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/DetachedNativeTerrain.java

@@ -0,0 +1,235 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.probe.NativeRegionPlan.PlannedChunk;
+
+import net.minecraft.nbt.CompoundTag;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+import net.minecraft.server.level.ChunkMap;
+import net.minecraft.server.level.GenerationChunkHolder;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.util.StaticCache2D;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkPyramid;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.status.ChunkStep;
+import net.minecraft.world.level.chunk.status.WorldGenContext;
+import net.minecraft.world.level.chunk.storage.RegionFile;
+import net.minecraft.world.level.chunk.storage.RegionStorageInfo;
+import net.minecraft.world.level.chunk.storage.SerializableChunkData;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.HexFormat;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Consumer;
+import java.util.concurrent.atomic.AtomicInteger;
+
+final class DetachedNativeTerrain {
+    private static final NamespacedKey NATURAL_TERRAIN = new NamespacedKey("iris", "natural_terrain");
+
+    private DetachedNativeTerrain() {
+    }
+
+    static Result generate(Request request, Consumer<String> progress) throws Exception {
+        List<PlannedChunk> plan = NativeRegionPlan.plan(request.chunkX(), request.chunkZ(), request.width());
+        Path output = Files.createDirectory(request.output());
+        WorldGenContext context = context(request.level().getChunkSource().chunkMap);
+        Map<Long, DetachedHolder> holders = new HashMap<>(plan.size());
+        for (PlannedChunk planned : plan) {
+            ChunkPos position = new ChunkPos(planned.x(), planned.z());
+            holders.put(position.pack(), new DetachedHolder(new ProtoChunk(position, UpgradeData.EMPTY,
+                    request.level(), request.level().palettedContainerFactory(), null)));
+        }
+        long started = System.nanoTime();
+        try (RegionGenerationWindow workers = new RegionGenerationWindow(request.parallelism(), RegionGenerationWindow.Policy.EMBEDDED)) {
+            for (ChunkStatus status : ChunkStatus.getStatusList()) {
+                if (status == ChunkStatus.EMPTY) {
+                    continue;
+                }
+                if (status.isAfter(ChunkStatus.TERRAIN)) {
+                    break;
+                }
+                ChunkStep step = ChunkPyramid.GENERATION_PYRAMID.getStepTo(status);
+                executeStage(new Stage(context, step, plan, holders, request.parallelism()), workers, progress);
+            }
+        }
+        long serializationStarted = System.nanoTime();
+        write(request.level(), output, plan, holders);
+        progress.accept("stage=native_serialization seconds=" + (System.nanoTime() - serializationStarted) / 1_000_000_000.0);
+        double seconds = (System.nanoTime() - started) / 1_000_000_000.0;
+        return new Result(request.width() * request.width(), plan.size(), seconds);
+    }
+
+    private static void executeStage(Stage stage, RegionGenerationWindow workers, Consumer<String> progress) throws Exception {
+        long started = System.nanoTime();
+        List<PlannedChunk> eligible = new ArrayList<>();
+        for (PlannedChunk planned : stage.plan()) {
+            if (planned.status().isOrAfter(stage.step().targetStatus())) {
+                eligible.add(planned);
+            }
+        }
+        AtomicInteger completed = new AtomicInteger();
+        AtomicInteger targetCompleted = new AtomicInteger();
+        workers.process(new RegionGenerationWindow.Request<>(eligible.size(), stage.parallelism(),
+                index -> {
+                    PlannedChunk planned = eligible.get(index);
+                    apply(stage, planned);
+                    return planned;
+                }, (index, planned) -> {
+                    int count = completed.incrementAndGet();
+                    if (planned.target()) {
+                        targetCompleted.incrementAndGet();
+                    }
+                    if (count % 128 == 0) {
+                        progress.accept("stage=" + stage.step().targetStatus().getName() + " completed=" + count
+                                + " elapsedSeconds=" + (System.nanoTime() - started) / 1_000_000_000.0);
+                    }
+                }));
+        progress.accept("stage=" + stage.step().targetStatus().getName() + " chunks=" + completed.get()
+                + " targetChunks=" + targetCompleted.get() + " haloChunks=" + (completed.get() - targetCompleted.get())
+                + " seconds=" + (System.nanoTime() - started) / 1_000_000_000.0);
+    }
+
+    private static void apply(Stage stage, PlannedChunk planned) {
+        DetachedHolder center = requireHolder(stage.holders(), planned.x(), planned.z());
+        StaticCache2D<GenerationChunkHolder> cache = StaticCache2D.create(planned.x(), planned.z(),
+                stage.step().directDependencies().size() - 1, (x, z) -> requireHolder(stage.holders(), x, z));
+        ChunkAccess result = stage.step().apply(stage.context(), cache, center.chunk).join();
+        if (result != center.chunk || result.getPersistedStatus() != stage.step().targetStatus()) {
+            throw new IllegalStateException("Native stage did not retain its detached chunk: " + stage.step().targetStatus());
+        }
+    }
+
+    private static DetachedHolder requireHolder(Map<Long, DetachedHolder> holders, int x, int z) {
+        DetachedHolder holder = holders.get(ChunkPos.pack(x, z));
+        if (holder == null) {
+            throw new IllegalStateException("Native dependency escaped the terrain halo at " + x + "," + z);
+        }
+        return holder;
+    }
+
+    private static WorldGenContext context(ChunkMap map) throws ReflectiveOperationException {
+        for (Field field : ChunkMap.class.getDeclaredFields()) {
+            if (field.getType() == WorldGenContext.class) {
+                field.setAccessible(true);
+                return (WorldGenContext) field.get(map);
+            }
+        }
+        throw new IllegalStateException("Native world generation context is unavailable");
+    }
+
+    private static void write(ServerLevel level, Path output, List<PlannedChunk> plan,
+                              Map<Long, DetachedHolder> holders) throws IOException {
+        List<PlannedChunk> ordered = new ArrayList<>(plan);
+        ordered.sort(Comparator.comparingInt((PlannedChunk chunk) -> chunk.z() >> 5)
+                .thenComparingInt(chunk -> chunk.x() >> 5).thenComparingInt(PlannedChunk::z).thenComparingInt(PlannedChunk::x));
+        StringBuilder receipts = new StringBuilder();
+        RegionFile region = null;
+        long currentRegion = Long.MIN_VALUE;
+        try {
+            for (PlannedChunk planned : ordered) {
+                if (planned.status() == ChunkStatus.EMPTY) {
+                    continue;
+                }
+                long key = ChunkPos.pack(planned.x() >> 5, planned.z() >> 5);
+                if (key != currentRegion) {
+                    if (region != null) {
+                        region.close();
+                    }
+                    Path file = output.resolve("r." + (planned.x() >> 5) + "." + (planned.z() >> 5) + ".mca");
+                    region = new RegionFile(new RegionStorageInfo(level.serverLevelData.getLevelName(),
+                            level.dimension(), "chunk"), file, output, false);
+                    currentRegion = key;
+                }
+                ChunkAccess chunk = holders.get(ChunkPos.pack(planned.x(), planned.z())).chunk;
+                if (planned.status() == ChunkStatus.TERRAIN) {
+                    receipts.append(planned.x()).append(",").append(planned.z()).append("=")
+                            .append(receiptHash(chunk)).append("\n");
+                }
+                CompoundTag tag = SerializableChunkData.copyOf(level, chunk).write();
+                NativeRegionTerrainWriter.write(region, tag);
+            }
+            Files.writeString(output.resolve("receipts.properties"), receipts.toString(), StandardCharsets.UTF_8);
+        } finally {
+            if (region != null) {
+                region.close();
+            }
+        }
+    }
+
+
+    static String receiptHash(ChunkAccess chunk) {
+        byte[] receipt = chunk.persistentDataContainer.get(NATURAL_TERRAIN,
+                PersistentDataType.BYTE_ARRAY);
+        if (receipt == null || receipt.length == 0) {
+            throw new IllegalStateException("Missing Iris natural terrain receipt at " + chunk.getPos());
+        }
+        try {
+            return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(receipt));
+        } catch (NoSuchAlgorithmException failure) {
+            throw new IllegalStateException(failure);
+        }
+    }
+
+    record Request(ServerLevel level, int chunkX, int chunkZ, int width, int parallelism, Path output) {
+        Request {
+            if (parallelism < 1 || parallelism > 16) {
+                throw new IllegalArgumentException("Native terrain worker count must be 1..16");
+            }
+        }
+    }
+
+    private record Stage(WorldGenContext context, ChunkStep step, List<PlannedChunk> plan,
+                         Map<Long, DetachedHolder> holders, int parallelism) {
+    }
+
+    record Result(int terrainChunks, int dependencyChunks, double seconds) {
+    }
+
+
+    private static final class DetachedHolder extends GenerationChunkHolder {
+        private final ProtoChunk chunk;
+
+        private DetachedHolder(ProtoChunk chunk) {
+            super(chunk.getPos());
+            this.chunk = chunk;
+        }
+
+        @Override
+        public ChunkAccess getChunkIfPresentUnchecked(ChunkStatus status) {
+            if (chunk.getPersistedStatus().isBefore(status)) {
+                throw new IllegalStateException("Native dependency is not ready: " + getPos() + " needs " + status);
+            }
+            return chunk;
+        }
+
+        @Override
+        protected void addSaveDependency(CompletableFuture<?> dependency) {
+            throw new UnsupportedOperationException("Detached chunks have no live save queue");
+        }
+
+        @Override
+        public int getTicketLevel() {
+            throw new UnsupportedOperationException("Detached chunks have no live tickets");
+        }
+
+        @Override
+        public int getQueueLevel() {
+            throw new UnsupportedOperationException("Detached chunks have no live queue");
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/DetachedNativeTerrainTest.java

@@ -0,0 +1,57 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.chunk.status.ChunkPyramid;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.status.ChunkStep;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+public final class DetachedNativeTerrainTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void fullRegionPlanSatisfiesEveryNativeStageDependency() {
+        List<NativeRegionPlan.PlannedChunk> plan = NativeRegionPlan.plan(-32, 64, 32);
+        Map<Long, ChunkStatus> statuses = new HashMap<>();
+        int terrain = 0;
+        for (NativeRegionPlan.PlannedChunk chunk : plan) {
+            statuses.put(ChunkPos.pack(chunk.x(), chunk.z()), chunk.status());
+            if (chunk.status() == ChunkStatus.TERRAIN) {
+                terrain++;
+            }
+        }
+        assertEquals(1296, terrain);
+        assertEquals(2916, plan.size());
+        assertTrue(plan.size() < 4096);
+        for (NativeRegionPlan.PlannedChunk chunk : plan) {
+            for (ChunkStatus status : ChunkStatus.getStatusList()) {
+                if (status == ChunkStatus.EMPTY || status.isAfter(chunk.status())) {
+                    continue;
+                }
+                ChunkStep step = ChunkPyramid.GENERATION_PYRAMID.getStepTo(status);
+                int radius = step.directDependencies().size() - 1;
+                for (int z = -radius; z <= radius; z++) {
+                    for (int x = -radius; x <= radius; x++) {
+                        ChunkStatus required = step.directDependencies().get(Math.max(Math.abs(x), Math.abs(z)));
+                        ChunkStatus available = statuses.get(ChunkPos.pack(chunk.x() + x, chunk.z() + z));
+                        assertTrue("Missing native stage dependency", available != null && available.isOrAfter(required));
+                    }
+                }
+            }
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessChunkGeneratorTest.java

@@ -0,0 +1,145 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeBiomeSourceImpl;
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.util.datafix.DataFixers;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import net.minecraft.world.level.storage.LevelStorageSource;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.bukkit.craftbukkit.generator.CustomChunkGenerator;
+
+import java.lang.reflect.Method;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.Mockito.atLeastOnce;
+import static org.mockito.Mockito.clearInvocations;
+import static org.mockito.Mockito.spy;
+import static org.mockito.Mockito.verify;
+
+public class HeadlessChunkGeneratorTest {
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+
+    @Test
+    public void nativeStructureStateAndOriginMatchThePaperGeneratorDefaults() throws Exception {
+        int checked = 0;
+        for (Method method : CustomChunkGenerator.class.getMethods()) {
+            if (!method.getName().equals("getOrigin") && !method.getName().equals("createState")) {
+                continue;
+            }
+            assertEquals(ChunkGenerator.class, method.getDeclaringClass());
+            assertEquals(method, HeadlessChunkGenerator.class.getMethod(method.getName(), method.getParameterTypes()));
+            checked++;
+        }
+        assertEquals(2, checked);
+    }
+
+    @Test
+    public void nativeSwampHutQueriesRealPackHeightsAndBiomesWithoutAServer() throws Exception {
+        long seed = 69420L;
+        HeadlessNativeRuntime runtime = new HeadlessNativeRuntime();
+        try (RealPackProbeSupport.Workspace workspace = RealPackProbeSupport.openWorkspace(new RealPackProbeSupport.WorkspaceOptions(
+                pack().toFile(), "main", "[native-column-test]", runtime, temporary.getRoot().toPath()));
+             RealPackProbeSupport.EngineSession session = workspace.openEngine(seed, false, "columns");
+             MultiPackResourceManager resources = new MultiPackResourceManager(PackType.SERVER_DATA,
+                     List.of(ServerPacksSource.createVanillaPackSource().fullResources()));
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(
+                     temporary.newFolder().toPath()).createAccess("native")) {
+            Engine engine = session.engine();
+            HeadlessChunkGenerator generator = spy(new HeadlessChunkGenerator(
+                    new HeadlessChunkGenerator.Options(engine, runtime.registries())));
+            assertTrue(generator.getBiomeSource() instanceof NativeBiomeSourceImpl);
+            assertEquals(engine.getMinHeight(), generator.getMinY());
+            assertEquals(engine.getHeight(), generator.getGenDepth());
+            assertEquals(engine.getMinHeight() + engine.getDimension().getFluidHeight(), generator.getSeaLevel());
+            Holder<NoiseGeneratorSettings> settings = runtime.registries().lookupOrThrow(Registries.NOISE_SETTINGS)
+                    .getOrThrow(NoiseGeneratorSettings.OVERWORLD);
+            RandomState random = RandomState.create(runtime.registries().lookupOrThrow(Registries.NOISE), seed, settings.value());
+            LevelHeightAccessor height = LevelHeightAccessor.create(generator.getMinY(), generator.getGenDepth());
+            Holder<Biome> swamp = runtime.registries().lookupOrThrow(Registries.BIOME).getOrThrow(
+                    ResourceKey.create(Registries.BIOME, Identifier.parse("minecraft:swamp")));
+            assertTrue(generator.getBiomeSource().possibleBiomes().contains(swamp));
+            for (int x : new int[]{-33, 0, 49}) {
+                int z = -x - 7;
+                int expected = engine.getMinHeight() + engine.getHeight(x, z, true) + 1;
+                assertTrue(expected > generator.getSeaLevel());
+                assertEquals(expected, generator.getBaseHeight(x, z, Heightmap.Types.OCEAN_FLOOR_WG, height, random));
+                NoiseColumn column = generator.getBaseColumn(x, z, height, random);
+                assertFalse(column.getBlock(expected - 1).isAir());
+                assertTrue(column.getBlock(expected).isAir());
+                assertEquals(swamp, generator.getBiomeSource().createResolver(
+                        random.createClimateSampler(SamplerContext.builder().enableCaches().build()))
+                        .getNoiseBiome(x >> 2, expected >> 2, z >> 2));
+            }
+            Holder.Reference<Structure> hut = runtime.registries().lookupOrThrow(Registries.STRUCTURE).getOrThrow(
+                    ResourceKey.create(Registries.STRUCTURE, Identifier.parse("minecraft:swamp_hut")));
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            ChunkPos position = new ChunkPos(-3, 2);
+            ProtoChunk chunk = new ProtoChunk(position, UpgradeData.EMPTY, height,
+                    PalettedContainerFactory.create(runtime.registries()), null);
+            clearInvocations(generator);
+            StructureStart start = hut.value().generate(hut, Level.OVERWORLD, runtime.registries(), generator,
+                    generator.getBiomeSource(), random.createClimateSampler(SamplerContext.builder().enableCaches().build()),
+                    random, templates, seed, position, 0, chunk, hut.value().biomes()::contains);
+            assertTrue(start.isValid());
+            assertFalse(start.getPieces().isEmpty());
+            verify(generator, atLeastOnce()).getBaseHeight(anyInt(), anyInt(), any(Heightmap.Types.class),
+                    any(LevelHeightAccessor.class), any(RandomState.class));
+            StructureStart excluded = hut.value().generate(hut, Level.OVERWORLD, runtime.registries(), generator,
+                    generator.getBiomeSource(), random.createClimateSampler(SamplerContext.builder().enableCaches().build()),
+                    random, templates, seed, position, 0, chunk, selected -> !selected.equals(swamp));
+            assertFalse(excluded.isValid());
+            assertTrue(RealPackProbeSupport.drainReported().isEmpty());
+        }
+    }
+
+    private Path pack() throws Exception {
+        Path pack = temporary.newFolder().toPath();
+        for (String directory : List.of("dimensions", "regions", "biomes", "generators")) {
+            Files.createDirectories(pack.resolve(directory));
+        }
+        Files.writeString(pack.resolve("dimensions/main.json"), """
+                {"name":"Native columns","focus":"swamp","regions":["owned"],"fluidHeight":40,"logicalHeight":256,
+                 "landChance":1,"carvingEnabled":false,"hydrology":{"rivers":{"enabled":false}}}
+                """);
+        Files.writeString(pack.resolve("regions/owned.json"), "{\"landBiomes\":[\"swamp\"]}");
+        Files.writeString(pack.resolve("generators/flat.json"), "{\"composite\":[]}");
+        Files.writeString(pack.resolve("biomes/swamp.json"), """
+                {"derivative":"minecraft:swamp","generators":[{"generator":"flat","min":35,"max":35}]}
+                """);
+        return pack;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessChunkLightingTest.java

@@ -0,0 +1,260 @@
+package art.arcane.iris.probe;
+
+import ca.spottedleaf.moonrise.patches.starlight.chunk.StarlightChunk;
+import ca.spottedleaf.moonrise.patches.starlight.light.StarLightInterface;
+import ca.spottedleaf.moonrise.patches.starlight.light.SWMRNibbleArray;
+import ca.spottedleaf.moonrise.patches.starlight.util.SaveUtil;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.NbtAccounter;
+import net.minecraft.nbt.NbtIo;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.util.datafix.DataFixers;
+import net.minecraft.world.level.BlockGetter;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.LightChunk;
+import net.minecraft.world.level.chunk.LightChunkGetter;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.storage.SerializableChunkData;
+import net.minecraft.world.level.levelgen.structure.pieces.StructurePieceSerializationContext;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import net.minecraft.world.level.storage.LevelStorageSource;
+import org.bukkit.Bukkit;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public final class HeadlessChunkLightingTest {
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+
+    @Test
+    public void nativeLightCrossesChunkEdgesAndRoundTripsSavedNibblesWithoutServer() throws Exception {
+        Fixture fixture = new Fixture(-1, -2);
+        int edgeX = fixture.target.x() * 16;
+        int z = fixture.target.z() * 16 + 8;
+        for (ProtoChunk chunk : fixture.chunks) {
+            for (int x = 0; x < 16; x++) {
+                for (int localZ = 0; localZ < 16; localZ++) {
+                    chunk.setBlockState(new BlockPos(chunk.getPos().getMinBlockX() + x, 0,
+                            chunk.getPos().getMinBlockZ() + localZ), Blocks.STONE.defaultBlockState(), 0);
+                }
+            }
+        }
+        fixture.set(new BlockPos(edgeX - 1, 0, z), Blocks.AIR.defaultBlockState());
+        fixture.set(new BlockPos(edgeX - 1, -12, z), Blocks.GLOWSTONE.defaultBlockState());
+        fixture.finishFeatures();
+        assertNull(Bukkit.getServer());
+        HeadlessChunkLighting.light(fixture.request(true));
+        ProtoChunk target = fixture.chunk(fixture.target);
+        assertEquals(14, light(target, false, new BlockPos(edgeX, -12, z)));
+        assertEquals(13, light(target, false, new BlockPos(edgeX + 1, -12, z)));
+        assertEquals(14, light(target, true, new BlockPos(edgeX, -1, z)));
+        assertEquals(15, light(target, true, new BlockPos(edgeX, 1, z)));
+        assertEquals(0, light(target, true, new BlockPos(edgeX + 15, -1, z)));
+        assertEquals(ChunkStatus.LIGHT, target.getPersistedStatus());
+        assertTrue(target.isLightCorrect());
+        assertEquals(ChunkStatus.FEATURES, fixture.chunk(new ChunkPos(fixture.target.x() - 2, fixture.target.z())).getPersistedStatus());
+        assertFalse(fixture.chunk(new ChunkPos(fixture.target.x() - 2, fixture.target.z())).isLightCorrect());
+
+        try (MultiPackResourceManager resources = new MultiPackResourceManager(PackType.SERVER_DATA,
+                List.of(ServerPacksSource.createVanillaPackSource().fullResources()));
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(
+                     temporary.newFolder().toPath()).createAccess("lighting")) {
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            HeadlessChunkSerialization.Context context = new HeadlessChunkSerialization.Context(
+                    new StructurePieceSerializationContext(resources, fixture.registries, templates), fixture.containers, 0L);
+            CompoundTag tag = HeadlessChunkSerialization.copyOf(target, context).write();
+            assertEquals("minecraft:light", tag.getStringOr("Status", ""));
+            assertEquals(SaveUtil.STARLIGHT_LIGHT_VERSION, tag.getIntOr(SaveUtil.STARLIGHT_VERSION_TAG, -1));
+            assertTrue(tag.contains("isLightOn"));
+            assertFalse(tag.getBooleanOr("isLightOn", true));
+            assertThrows(ClassCastException.class, () -> SerializableChunkData.parse(target, fixture.containers, tag));
+            ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+            NbtIo.writeCompressed(tag, bytes);
+            CompoundTag restored = NbtIo.readCompressed(new ByteArrayInputStream(bytes.toByteArray()), NbtAccounter.unlimitedHeap());
+            assertEquals(tag, restored);
+            List<CompoundTag> sections = restored.getListOrEmpty("sections").compoundStream().toList();
+            assertEquals(target.getSectionsCount() + 2, sections.size());
+            for (CompoundTag section : sections) {
+                int index = section.getByteOr("Y", (byte) 0) - target.getMinSectionY() + 1;
+                assertTrue(section.contains(SaveUtil.BLOCKLIGHT_STATE_TAG));
+                assertTrue(section.contains(SaveUtil.SKYLIGHT_STATE_TAG));
+                SWMRNibbleArray block = new SWMRNibbleArray(section.getByteArray("BlockLight").orElse(null),
+                        section.getIntOr(SaveUtil.BLOCKLIGHT_STATE_TAG, 0));
+                SWMRNibbleArray sky = new SWMRNibbleArray(section.getByteArray("SkyLight").orElse(null),
+                        section.getIntOr(SaveUtil.SKYLIGHT_STATE_TAG, 0));
+                assertNibbleEquals(((StarlightChunk) target).starlight$getBlockNibbles()[index], block);
+                assertNibbleEquals(((StarlightChunk) target).starlight$getSkyNibbles()[index], sky);
+            }
+        }
+        assertNull(Bukkit.getServer());
+    }
+
+    @Test
+    public void nativeOpacityAndShapeRulesApplyAcrossTheBoundaryWithoutSkylight() {
+        for (BlockState barrier : List.of(Blocks.GLASS.defaultBlockState(), Blocks.TINTED_GLASS.defaultBlockState(),
+                Blocks.STONE_SLAB.defaultBlockState(), Blocks.STONE.defaultBlockState())) {
+            Fixture fixture = new Fixture(0, 0);
+            for (int x = -2; x <= 3; x++) {
+                for (int y = -13; y <= -11; y++) {
+                    for (int z = 7; z <= 9; z++) {
+                        fixture.set(new BlockPos(x, y, z), Blocks.STONE.defaultBlockState());
+                    }
+                }
+            }
+            for (int x = -1; x <= 2; x++) {
+                fixture.set(new BlockPos(x, -12, 8), Blocks.AIR.defaultBlockState());
+            }
+            fixture.set(new BlockPos(-1, -12, 8), Blocks.GLOWSTONE.defaultBlockState());
+            fixture.set(new BlockPos(0, -12, 8), barrier);
+            fixture.finishFeatures();
+            HeadlessChunkLighting.light(fixture.request(false));
+            ProtoChunk target = fixture.chunk(fixture.target);
+            int expected = barrier.is(Blocks.GLASS) || barrier.is(Blocks.STONE_SLAB) ? 13 : 0;
+            assertEquals(barrier.toString(), expected, light(target, false, new BlockPos(1, -12, 8)));
+            assertEquals(0, light(target, true, new BlockPos(1, 20, 8)));
+        }
+        assertNull(Bukkit.getServer());
+    }
+
+    @Test
+    public void emptySectionsRetainImplicitSkyLightAcrossFullHeightAndPadding() {
+        for (boolean sky : List.of(true, false)) {
+            Fixture fixture = new Fixture(0, 0);
+            fixture.finishFeatures();
+            HeadlessChunkLighting.light(fixture.request(sky));
+            ProtoChunk target = fixture.chunk(fixture.target);
+            for (int y = target.getMinY() - 16; y <= target.getMaxY() + 16; y++) {
+                assertEquals("sky y=" + y, sky ? 15 : 0, light(target, true, new BlockPos(8, y, 8)));
+                assertEquals("block y=" + y, 0, light(target, false, new BlockPos(8, y, 8)));
+            }
+        }
+    }
+
+    @Test
+    public void interruptionLeavesChunkUnlitAndRetainsInterrupt() {
+        Fixture fixture = new Fixture(0, 0);
+        fixture.finishFeatures();
+        Thread.currentThread().interrupt();
+        try {
+            assertThrows(IllegalStateException.class, () -> HeadlessChunkLighting.light(fixture.request(true)));
+            assertTrue(Thread.currentThread().isInterrupted());
+            assertFalse(fixture.chunk(fixture.target).isLightCorrect());
+            assertEquals(ChunkStatus.FEATURES, fixture.chunk(fixture.target).getPersistedStatus());
+        } finally {
+            Thread.interrupted();
+        }
+    }
+
+    @Test
+    public void rejectsIncompleteNeighborsBeforePromotingOrMutatingLight() {
+        Fixture fixture = new Fixture(0, 0);
+        fixture.finishFeatures();
+        fixture.chunks.removeFirst();
+        ProtoChunk target = fixture.chunk(fixture.target);
+        SWMRNibbleArray[] previous = ((StarlightChunk) target).starlight$getBlockNibbles();
+        assertThrows(IllegalArgumentException.class, () -> HeadlessChunkLighting.light(fixture.request(true)));
+        assertEquals(ChunkStatus.FEATURES, target.getPersistedStatus());
+        assertFalse(target.isLightCorrect());
+        assertArrayEquals(previous, ((StarlightChunk) target).starlight$getBlockNibbles());
+        fixture.chunks.add(new ProtoChunk(new ChunkPos(-2, -2), UpgradeData.EMPTY, target, fixture.containers, null));
+        assertThrows(IllegalArgumentException.class, () -> HeadlessChunkLighting.light(fixture.request(true)));
+    }
+
+    @Test
+    public void directStarlightRequiresLevelButNativeLightEnginesDoNot() {
+        Fixture fixture = new Fixture(0, 0);
+        ProtoChunk chunk = fixture.chunk(fixture.target);
+        LightChunkGetter source = new LightChunkGetter() {
+            @Override
+            public LightChunk getChunkForLighting(int x, int z) {
+                return chunk;
+            }
+
+            @Override
+            public BlockGetter getLevel() {
+                return chunk;
+            }
+        };
+        assertThrows(ClassCastException.class, () -> new StarLightInterface(source, true, true, null));
+        assertNull(Bukkit.getServer());
+    }
+
+    private static int light(ProtoChunk chunk, boolean sky, BlockPos position) {
+        StarlightChunk light = (StarlightChunk) chunk;
+        SWMRNibbleArray[] nibbles = sky ? light.starlight$getSkyNibbles() : light.starlight$getBlockNibbles();
+        return nibbles[(position.getY() >> 4) - chunk.getMinSectionY() + 1]
+                .getVisible(position.getX(), position.getY(), position.getZ());
+    }
+
+    private static void assertNibbleEquals(SWMRNibbleArray expected, SWMRNibbleArray actual) {
+        for (int index = 0; index < 4096; index++) {
+            assertEquals(expected.getVisible(index), actual.getVisible(index));
+        }
+    }
+
+    private static final class Fixture {
+        private final RegistryAccess registries = HeadlessNativeTestRegistries.get();
+        private final PalettedContainerFactory containers = PalettedContainerFactory.create(registries);
+        private final List<ProtoChunk> chunks = new ArrayList<>();
+        private final ChunkPos target;
+
+        private Fixture(int x, int z) {
+            target = new ChunkPos(x, z);
+            LevelHeightAccessor height = LevelHeightAccessor.create(-64, 128);
+            for (int dz = -2; dz <= 2; dz++) {
+                for (int dx = -2; dx <= 2; dx++) {
+                    chunks.add(new ProtoChunk(new ChunkPos(x + dx, z + dz), UpgradeData.EMPTY, height, containers, null));
+                }
+            }
+        }
+
+        private ProtoChunk chunk(ChunkPos position) {
+            for (ProtoChunk chunk : chunks) {
+                if (chunk.getPos().equals(position)) {
+                    return chunk;
+                }
+            }
+            throw new IllegalArgumentException("Missing fixture chunk " + position);
+        }
+
+        private void set(BlockPos position, BlockState state) {
+            chunk(new ChunkPos(position.getX() >> 4, position.getZ() >> 4)).setBlockState(position, state, 0);
+        }
+
+        private void finishFeatures() {
+            for (ProtoChunk chunk : chunks) {
+                chunk.setPersistedStatus(ChunkStatus.FEATURES);
+            }
+        }
+
+        private HeadlessChunkLighting.Request request(boolean sky) {
+            return new HeadlessChunkLighting.Request(chunks, Set.of(target), sky);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessChunkSerializationTest.java

@@ -0,0 +1,157 @@
+package art.arcane.iris.probe;
+
+import ca.spottedleaf.moonrise.patches.starlight.chunk.StarlightChunk;
+import it.unimi.dsi.fastutil.longs.LongOpenHashSet;
+import it.unimi.dsi.fastutil.shorts.ShortArrayList;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.util.RandomSource;
+import net.minecraft.util.datafix.DataFixers;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.storage.SerializableChunkData;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.pieces.PiecesContainer;
+import net.minecraft.world.level.levelgen.structure.pieces.StructurePieceSerializationContext;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutPiece;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import net.minecraft.world.level.material.Fluids;
+import net.minecraft.world.level.storage.LevelStorageSource;
+import net.minecraft.world.ticks.ScheduledTick;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+public class HeadlessChunkSerializationTest {
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+
+    @Test
+    public void snapshotMatchesNativeCopyOfIncludingStructuresLightAndReceipts() throws Exception {
+        RegistryAccess registries = HeadlessNativeTestRegistries.get();
+        PalettedContainerFactory containers = PalettedContainerFactory.create(registries);
+        LevelHeightAccessor height = LevelHeightAccessor.create(-64, 384);
+        ProtoChunk chunk = new ProtoChunk(new ChunkPos(-33, 17), UpgradeData.EMPTY, height, containers, null);
+        BlockPos block = new BlockPos(-528, -40, 272);
+        chunk.setBlockState(block, Blocks.CHEST.defaultBlockState(), 0);
+        CompoundTag chest = new CompoundTag();
+        chest.putString("id", "minecraft:chest");
+        chest.putInt("x", block.getX());
+        chest.putInt("y", block.getY());
+        chest.putInt("z", block.getZ());
+        chest.putString("LootTable", "minecraft:chests/simple_dungeon");
+        chunk.setBlockEntityNbt(chest);
+        CompoundTag entity = new CompoundTag();
+        entity.putString("id", "minecraft:pig");
+        chunk.addEntity(entity);
+        chunk.getBlockTicks().schedule(new ScheduledTick<>(Blocks.CHEST, block, 37L, 2L));
+        chunk.getFluidTicks().schedule(new ScheduledTick<>(Fluids.WATER, block.above(), 41L, 3L));
+        chunk.addPackedPostProcess(new ShortArrayList(new short[]{17, 2049}), 1);
+        chunk.setInhabitedTime(192L);
+        Heightmap.primeHeightmaps(chunk, EnumSet.allOf(Heightmap.Types.class));
+        chunk.setPersistedStatus(ChunkStatus.TERRAIN);
+        chunk.persistentDataContainer.set(new NamespacedKey("iris", "natural_terrain"),
+                PersistentDataType.BYTE_ARRAY, new byte[]{1, -8, 92, 0});
+        StarlightChunk light = (StarlightChunk) chunk;
+        light.starlight$getBlockNibbles()[1].setFull();
+        light.starlight$getBlockNibbles()[1].updateVisible();
+        light.starlight$getSkyNibbles()[0].setFull();
+        light.starlight$getSkyNibbles()[0].updateVisible();
+        chunk.setLightCorrect(true);
+        Structure hut = registries.lookupOrThrow(Registries.STRUCTURE).getOrThrow(
+                ResourceKey.create(Registries.STRUCTURE, Identifier.parse("minecraft:swamp_hut"))).value();
+        StructureStart start = new StructureStart(hut, chunk.getPos(), 2,
+                new PiecesContainer(List.of(new SwampHutPiece(RandomSource.create(69420L), block.getX(), block.getZ()))));
+        start.persistentDataContainer.set(new NamespacedKey("iris", "structure_activation"), PersistentDataType.LONG, 73L);
+        chunk.setAllStarts(Map.of(hut, start));
+        chunk.setAllReferences(Map.of(hut, new LongOpenHashSet(new long[]{ChunkPos.pack(-32, 17)})));
+        try (MultiPackResourceManager resources = new MultiPackResourceManager(PackType.SERVER_DATA,
+                List.of(ServerPacksSource.createVanillaPackSource().fullResources()));
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(
+                     temporary.newFolder().toPath()).createAccess("serialization")) {
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            StructurePieceSerializationContext structures = new StructurePieceSerializationContext(resources, registries, templates);
+            HeadlessChunkSerialization.Context context = new HeadlessChunkSerialization.Context(structures, containers, 29L);
+            MinecraftServer server = mock(MinecraftServer.class);
+            when(server.getResourceManager()).thenReturn(resources);
+            when(server.registryAccess()).thenReturn(registries.freeze());
+            when(server.getStructureTemplateManager()).thenReturn(templates);
+            ServerLevel level = mock(ServerLevel.class);
+            when(level.getServer()).thenReturn(server);
+            when(level.registryAccess()).thenReturn(registries);
+            when(level.palettedContainerFactory()).thenReturn(containers);
+            when(level.getGameTime()).thenReturn(29L);
+            when(level.getMinSectionY()).thenReturn(height.getMinSectionY());
+            when(level.getMaxSectionY()).thenReturn(height.getMaxSectionY());
+            CompoundTag nativeTag = SerializableChunkData.copyOf(level, chunk).write();
+            SerializableChunkData snapshot = HeadlessChunkSerialization.copyOf(chunk, context);
+            CompoundTag headless = snapshot.write();
+            assertEquals(nativeTag, headless);
+            assertEquals("minecraft:terrain", headless.getStringOr("Status", ""));
+            assertEquals(29L, headless.getLongOr("LastUpdate", -1L));
+            assertEquals(192L, headless.getLongOr("InhabitedTime", -1L));
+            assertArrayEquals(new byte[]{1, -8, 92, 0}, headless.getCompoundOrEmpty("ChunkBukkitValues")
+                    .getByteArray("iris:natural_terrain").orElseThrow());
+            assertFalse(headless.getListOrEmpty("block_entities").isEmpty());
+            assertFalse(headless.getListOrEmpty("block_ticks").isEmpty());
+            assertFalse(headless.getListOrEmpty("fluid_ticks").isEmpty());
+            assertTrue(headless.getCompoundOrEmpty("structures").getCompoundOrEmpty("starts").contains("minecraft:swamp_hut"));
+            CompoundTag serializedStart = headless.getCompoundOrEmpty("structures").getCompoundOrEmpty("starts")
+                    .getCompoundOrEmpty("minecraft:swamp_hut");
+            StructureStart restored = StructureStart.loadStaticStart(structures, serializedStart, 69420L);
+            assertTrue(restored.isValid());
+            assertEquals(start.getBoundingBox(), restored.getBoundingBox());
+            assertEquals(73L, serializedStart.getCompoundOrEmpty("StructureBukkitValues")
+                    .getLongOr("iris:structure_activation", -1L));
+            chunk.getSection(1).setBlockState(0, 8, 0, Blocks.AIR.defaultBlockState());
+            chunk.getPostProcessing()[1].clear();
+            chunk.getOrCreateHeightmapUnprimed(Heightmap.Types.WORLD_SURFACE).getRawData()[0] = 0L;
+            assertEquals(headless, snapshot.write());
+            for (ChunkStatus status : List.of(ChunkStatus.EMPTY, ChunkStatus.STRUCTURE_STARTS,
+                    ChunkStatus.STRUCTURE_REFERENCES, ChunkStatus.BIOMES, ChunkStatus.TERRAIN)) {
+                ProtoChunk fresh = new ProtoChunk(new ChunkPos(0, -1), UpgradeData.EMPTY, height, containers, null);
+                fresh.setPersistedStatus(status);
+                CompoundTag freshTag = HeadlessChunkSerialization.copyOf(fresh, context).write();
+                assertEquals(SerializableChunkData.copyOf(level, fresh).write(), freshTag);
+                assertEquals(status, SerializableChunkData.getChunkStatusFromTag(freshTag));
+                assertFalse(freshTag.contains("ChunkBukkitValues"));
+                assertTrue(freshTag.getListOrEmpty("entities").isEmpty());
+                assertTrue(freshTag.getListOrEmpty("block_entities").isEmpty());
+            }
+            chunk.setPersistedStatus(ChunkStatus.FULL);
+            assertThrows(IllegalArgumentException.class, () -> HeadlessChunkSerialization.copyOf(chunk, context));
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessGenerationRegistryTest.java

@@ -0,0 +1,45 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.spi.PlatformGenerationRegistry;
+import net.minecraft.data.registries.VanillaRegistries;
+import org.bukkit.Bukkit;
+import org.junit.Test;
+
+import java.io.File;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThrows;
+
+public final class HeadlessGenerationRegistryTest {
+    @Test
+    public void capturesGeneratedDefinitionsThroughNativeCodecs() throws Exception {
+        HeadlessNativeBootstrap.initialize();
+        String biome = HeadlessNativeTestRegistries.generatedBiome();
+        String dimension = HeadlessNativeTestRegistries.generatedDimension();
+        HeadlessNativePlatform platform = new HeadlessNativePlatform(new File("unused-native-platform"),
+            HeadlessNativeTestRegistries::get);
+        PlatformGenerationRegistry registry = platform.generationRegistry();
+        assertEquals("bukkit-generation-registry-v1", registry.runtimeIdentity());
+        assertEquals(registry.canonicalDefinition("minecraft:worldgen/biome", "iris:native_test", biome),
+                registry.generatedDefinition("minecraft:worldgen/biome", "iris:native_test"));
+        assertEquals(registry.canonicalDefinition("minecraft:dimension_type", "iris:native_test", dimension),
+                registry.generatedDefinition("minecraft:dimension_type", "iris:native_test"));
+        assertEquals(PlatformGenerationRegistry.Definition.resourceIdentity("minecraft:block", "minecraft:stone"),
+                registry.definition("minecraft:block", "minecraft:stone"));
+        assertThrows(IllegalStateException.class,
+                () -> registry.generatedDefinition("minecraft:worldgen/biome", "iris:absent"));
+        assertThrows(IllegalArgumentException.class,
+                () -> registry.canonicalDefinition("minecraft:worldgen/biome", "iris:invalid", "{}"));
+        assertNull(Bukkit.getServer());
+    }
+
+    @Test
+    public void rejectsContractCaptureBeforeCoherentRegistriesLoad() {
+        HeadlessNativeBootstrap.initialize();
+        HeadlessNativePlatform platform = new HeadlessNativePlatform(new File("unused-native-platform"),
+            VanillaRegistries::createWorldLookup);
+        assertThrows(IllegalStateException.class,
+            () -> platform.generationRegistry().definition("minecraft:block", "minecraft:stone"));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessMantleInspection.java

@@ -0,0 +1,90 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.block.TileData;
+import art.arcane.iris.world.storage.matter.TileWrapper;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.generation.runtime.IrisEngineMantle;
+import art.arcane.volmlib.util.matter.Matter;
+import art.arcane.volmlib.util.mantle.runtime.Mantle;
+
+import java.io.ByteArrayOutputStream;
+import java.io.DataOutputStream;
+import java.io.File;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.util.Comparator;
+import java.util.HexFormat;
+import java.util.Map;
+import java.util.TreeMap;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Stream;
+
+public final class HeadlessMantleInspection {
+    private HeadlessMantleInspection() {
+    }
+
+    public static void main(String[] arguments) throws Exception {
+        if (arguments.length != 6) {
+            throw new IllegalArgumentException("Expected pack, dimension, seed, world, regionX, regionZ");
+        }
+        Path temporary = Files.createTempDirectory("iris-mantle-inspection-");
+        Path copied = temporary.resolve("mantle");
+        try {
+            Process copy = new ProcessBuilder("cp", "-Rc", Path.of(arguments[3]).resolve("mantle-hydrology").toString(),
+                    copied.toString()).inheritIO().start();
+            if (copy.waitFor() != 0) {
+                throw new IllegalStateException("Could not clone retained mantle for read-only inspection");
+            }
+            inspect(arguments, copied);
+        } finally {
+            try (Stream<Path> paths = Files.walk(temporary)) {
+                for (Path path : paths.sorted(Comparator.reverseOrder()).toList()) {
+                    Files.delete(path);
+                }
+            }
+        }
+    }
+
+    private static void inspect(String[] arguments, Path copied) throws Exception {
+        HeadlessNativeRuntime runtime = new HeadlessNativeRuntime();
+        try (RealPackProbeSupport.Workspace workspace = RealPackProbeSupport.openWorkspace(new RealPackProbeSupport.WorkspaceOptions(
+                new File(arguments[0]), arguments[1], "[mantle-inspection]", runtime,
+                Path.of(System.getProperty("java.io.tmpdir"))));
+             RealPackProbeSupport.EngineSession session = workspace.openEngine(Long.parseLong(arguments[2]), false, "inspect")) {
+            Engine engine = session.engine();
+            Mantle<Matter> mantle = IrisEngineMantle.createMantle(engine, copied, engine::getData);
+            try {
+                AtomicInteger tiles = new AtomicInteger();
+                Map<String, Integer> materials = new TreeMap<>();
+                MessageDigest digest = MessageDigest.getInstance("SHA-256");
+                int minimumX = Integer.parseInt(arguments[4]) << 5;
+                int minimumZ = Integer.parseInt(arguments[5]) << 5;
+                for (int z = minimumZ; z < minimumZ + 32; z++) {
+                    for (int x = minimumX; x < minimumX + 32; x++) {
+                        mantle.iterateChunk(x, z, TileWrapper.class, (localX, y, localZ, wrapper) -> {
+                            TileData tile = wrapper.getData();
+                            tiles.incrementAndGet();
+                            materials.merge(tile.getMaterialKey(), 1, Integer::sum);
+                            digest.update(encoded(tile));
+                        });
+                    }
+                }
+                System.out.println("retainedMantleTiles=" + tiles.get() + " materials=" + materials
+                        + " sha256=" + HexFormat.of().formatHex(digest.digest()));
+            } finally {
+                mantle.close();
+            }
+        }
+    }
+
+    private static byte[] encoded(TileData tile) {
+        try (ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+             DataOutputStream output = new DataOutputStream(bytes)) {
+            tile.toBinary(output);
+            return bytes.toByteArray();
+        } catch (Exception failure) {
+            throw new IllegalStateException("Cannot serialize retained tile " + tile.getMaterialKey(), failure);
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeBlockPredicateTest.java

@@ -0,0 +1,54 @@
+package art.arcane.iris.probe;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeBlockProperties;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.times;
+
+public final class HeadlessNativeBlockPredicateTest {
+    @BeforeClass
+    public static void bootstrap() {
+        HeadlessNativeBootstrap.initialize();
+    }
+
+    @Test
+    public void memoizedPredicatesMatchEveryNativeBlockStateIncludingStateProperties() {
+        for (Block block : BuiltInRegistries.BLOCK) {
+            for (BlockState state : block.getStateDefinition().getPossibleStates()) {
+                ModdedBlockState wrapped = ModdedBlockState.deferred(state, Map.of(), "iris:test");
+                for (int iteration = 0; iteration < 2; iteration++) {
+                    assertEquals(NativeBlockProperties.isStorage(state), wrapped.isStorage());
+                    assertEquals(NativeBlockProperties.isUpdatable(state), wrapped.isUpdatable());
+                }
+            }
+        }
+    }
+
+    @Test
+    public void repeatedWritesClassifyImmutableStateOnlyOnce() {
+        BlockState state = Blocks.CHEST.defaultBlockState();
+        ModdedBlockState wrapped = ModdedBlockState.deferred(state, Map.of(), "iris:chest");
+        boolean storage = NativeBlockProperties.isStorage(state);
+        boolean updatable = NativeBlockProperties.isUpdatable(state);
+        try (MockedStatic<NativeBlockProperties> properties = mockStatic(NativeBlockProperties.class, CALLS_REAL_METHODS)) {
+            for (int iteration = 0; iteration < 512; iteration++) {
+                assertEquals(storage, wrapped.isStorage());
+                assertEquals(updatable, wrapped.isUpdatable());
+            }
+            properties.verify(() -> NativeBlockProperties.isUpdatable(state), times(1));
+            properties.verify(() -> NativeBlockProperties.isStorage(state), times(2));
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeBootstrapTest.java

@@ -0,0 +1,45 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.tags.BlockTags;
+import net.minecraft.core.component.DataComponents;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.world.item.Item;
+import net.minecraft.world.item.ItemStack;
+import net.minecraft.world.item.Items;
+
+import java.util.Map;
+import net.minecraft.world.level.block.Blocks;
+import org.junit.Test;
+import org.bukkit.Bukkit;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+
+public final class HeadlessNativeBootstrapTest {
+    @Test
+    public void bindsNativeItemComponentsWithoutStartingServer() throws Exception {
+        HeadlessNativeBootstrap.bindComponents(HeadlessNativeTestRegistries.get());
+        for (Item item : BuiltInRegistries.ITEM) {
+            ItemStack stack = new ItemStack(item);
+            if (item != Items.AIR) {
+                assertTrue(stack.getMaxStackSize() > 0);
+            }
+        }
+        assertNotNull(new ItemStack(Items.APPLE).get(DataComponents.FOOD));
+        assertEquals(64, new ItemStack(Items.TRIAL_KEY).getMaxStackSize());
+        assertTrue(Bukkit.getServer() == null);
+    }
+
+    @Test
+    public void loadsActualNativeTagsWithoutStartingServer() throws Exception {
+        HeadlessNativeBootstrap.initialize();
+        assertTrue(Blocks.OAK_LOG.defaultBlockState().is(BlockTags.LOGS));
+        assertTrue(Blocks.OAK_LEAVES.defaultBlockState().is(BlockTags.LEAVES));
+        assertTrue(Blocks.STONE.defaultBlockState().is(BlockTags.BLOCKS_MOTION));
+        assertFalse(Blocks.WATER.defaultBlockState().is(BlockTags.BLOCKS_MOTION));
+        assertFalse(Blocks.SHORT_GRASS.defaultBlockState().is(BlockTags.BLOCKS_MOTION));
+        assertTrue(Bukkit.getServer() == null);
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeRegistriesTest.java

@@ -0,0 +1,28 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.core.Holder;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import org.junit.Test;
+
+
+import static org.junit.Assert.assertTrue;
+
+public final class HeadlessNativeRegistriesTest {
+    @Test
+    public void nativeStructureBiomeTagsUseTheLoadedBiomeHolders() throws Exception {
+        RegistryAccess registries = HeadlessNativeTestRegistries.get();
+        Structure swampHut = registries.lookupOrThrow(Registries.STRUCTURE)
+                .getValue(Identifier.parse("minecraft:swamp_hut"));
+        Holder<Biome> swamp = registries.lookupOrThrow(Registries.BIOME)
+                .getOrThrow(ResourceKey.create(Registries.BIOME, Identifier.parse("minecraft:swamp")));
+        assertTrue(swampHut.biomes().contains(swamp));
+        Holder<Biome> custom = registries.lookupOrThrow(Registries.BIOME)
+                .getOrThrow(ResourceKey.create(Registries.BIOME, Identifier.parse("iris:coherent_swamp")));
+        assertTrue(swampHut.biomes().contains(custom));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeRegistryTest.java

@@ -0,0 +1,55 @@
+package art.arcane.iris.probe;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeRegistryAccess;
+import net.minecraft.core.registries.Registries;
+import org.bukkit.Bukkit;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.util.Map;
+import java.io.File;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+
+public final class HeadlessNativeRegistryTest {
+    @BeforeClass
+    public static void bootstrap() {
+        HeadlessNativeBootstrap.initialize();
+    }
+
+    @Test
+    public void corePlatformUsesNativeResolutionWithoutBiomeFallback() throws Exception {
+        NativeRegionTerrainWriter writer = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        HeadlessNativePlatform platform = new HeadlessNativePlatform(new File("unused-native-platform"), writer::registries);
+        assertEquals("headless-native-core", platform.platformName());
+        assertTrue(platform.block("minecraft:stone").isSolid());
+        assertFalse(platform.block("minecraft:short_grass").isSolid());
+        assertTrue(platform.block("minecraft:oak_log").isTreeBlock());
+        assertTrue(platform.biomeWriter().biomeIdFor("minecraft:plains") >= 0);
+        assertThrows(IllegalStateException.class, () -> platform.biomeWriter().biomeIdFor("iris:unknown"));
+        assertThrows(UnsupportedOperationException.class, platform::lootTableKeys);
+    }
+
+    @Test
+    public void resolvesNativeDynamicAndStaticRegistriesWithoutServer() throws Exception {
+        NativeRegionTerrainWriter writer = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        NativeRegistryAccess access = new NativeRegistryAccess(new NativeRegistryAccess.Configuration(
+                writer::registries, writer::registries, message -> {
+                    throw new AssertionError("Unavailable registry: " + message);
+                }));
+        assertNull(Bukkit.getServer());
+        assertEquals("iris:headless/test", access.biome("iris:headless/test").key());
+        assertNotNull(access.biome("minecraft:plains"));
+        assertNull(access.biome("iris:unknown"));
+        assertTrue(access.structureKeys().contains("minecraft:mineshaft"));
+        assertTrue(access.enchantmentKeys().contains("minecraft:fortune"));
+        assertEquals("minecraft:diamond_sword", access.item("DIAMOND SWORD").key());
+        assertEquals("creature", access.entity("minecraft:cow").spawnCategory());
+        assertTrue(access.blockStateProperties().containsKey("minecraft:oak_log"));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeStateTest.java

@@ -0,0 +1,71 @@
+package art.arcane.iris.probe;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeBlockResolver;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.mockito.MockedStatic;
+
+import java.io.File;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.times;
+
+public final class HeadlessNativeStateTest {
+    @BeforeClass
+    public static void bootstrap() {
+        HeadlessNativeBootstrap.initialize();
+    }
+
+    @Test
+    public void platformAirResolvesOnceAndRetainsCanonicalNativeState() {
+        BlockState air = Blocks.AIR.defaultBlockState();
+        try (MockedStatic<ModdedBlockState> states = mockStatic(ModdedBlockState.class, CALLS_REAL_METHODS)) {
+            HeadlessNativePlatform platform = new HeadlessNativePlatform(new File("unused-native-platform"),
+                    HeadlessNativeTestRegistries::get);
+            NativeBlockState wrapped = platform.air();
+            for (int iteration = 0; iteration < 1024; iteration++) {
+                assertSame(wrapped, platform.air());
+                assertSame(air, ((ModdedBlockState) platform.air()).handle());
+            }
+            states.verify(() -> ModdedBlockState.of(air, null), times(1));
+        }
+    }
+
+    @Test
+    public void nativeMaterialsDistinguishDecorationsFluidsGlassAndBlockEntities() {
+        assertFalse(NativeBlockResolver.strictParse("minecraft:short_grass").isSolid());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:glass").isSolid());
+        assertFalse(NativeBlockResolver.strictParse("minecraft:glass").isOccluding());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:stone").isOccluding());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:oak_log").isTreeBlock());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:oak_leaves").isTreeBlock());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:chest").hasTileEntity());
+        NativeBlockState slab = NativeBlockResolver.strictParse("minecraft:oak_slab[waterlogged=true]");
+        assertTrue(slab.isWaterLogged());
+        assertFalse(slab.isFluid());
+        assertTrue(NativeBlockResolver.strictParse("minecraft:water").isFluid());
+    }
+
+    @Test
+    public void canonicalStateKeysRoundTripEveryNativeDefaultState() {
+        for (Block block : BuiltInRegistries.BLOCK) {
+            BlockState state = block.defaultBlockState();
+            ModdedBlockState decoded = NativeBlockResolver.strictParse(ModdedBlockState.serialize(state));
+            assertEquals(state, decoded.handle());
+        }
+        assertThrows(IllegalArgumentException.class,
+                () -> NativeBlockResolver.strictParse("minecraft:oak_log[axis=invalid]"));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeTestRegistries.java

@@ -0,0 +1,66 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.biome.IrisBiomeCustom;
+import art.arcane.iris.generation.terrain.IrisDimensionType;
+import art.arcane.iris.generation.terrain.IrisDimensionTypeOptions;
+import art.arcane.iris.pack.datapack.IDataFixer;
+import art.arcane.iris.pack.datapack.v263.DataFixerV263;
+import com.mojang.serialization.JsonOps;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.data.registries.VanillaRegistries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.util.Map;
+
+final class HeadlessNativeTestRegistries {
+    private static RegistryAccess registries;
+
+    private HeadlessNativeTestRegistries() {
+    }
+
+    static synchronized RegistryAccess get() {
+        if (registries != null) {
+            return registries;
+        }
+        HeadlessNativeBootstrap.initialize();
+        HolderLookup.Provider vanilla = VanillaRegistries.createWorldLookup();
+        String plains = biome(vanilla, "minecraft:plains");
+        String swamp = biome(vanilla, "minecraft:swamp");
+        Map<String, String> definitions = Map.of(
+                "data/iris/worldgen/biome/native_test.json", generatedBiome(),
+                "data/iris/dimension_type/native_test.json", generatedDimension(),
+                "data/iris/worldgen/biome/biomes/test.json", plains,
+                "data/iris/worldgen/biome/headless/test.json", plains,
+                "data/iris/worldgen/biome/coherent_swamp.json", swamp,
+                "data/minecraft/tags/worldgen/biome/has_structure/swamp_hut.json",
+                "{\"replace\":false,\"values\":[\"iris:coherent_swamp\"]}");
+        try (HeadlessNativeRegistries loaded = HeadlessNativeRegistries.load(definitions)) {
+            registries = loaded.registries();
+            return registries;
+        } catch (IOException failure) {
+            throw new UncheckedIOException(failure);
+        }
+    }
+
+    static String generatedBiome() {
+        return new IrisBiomeCustom().setId("native_test").generateJson(new DataFixerV263());
+    }
+
+    static String generatedDimension() {
+        return new IrisDimensionType(IDataFixer.Dimension.OVERWORLD,
+                new IrisDimensionTypeOptions(), 768, 768, -256).toJson(new DataFixerV263());
+    }
+
+    private static String biome(HolderLookup.Provider vanilla, String key) {
+        Biome biome = vanilla.lookupOrThrow(Registries.BIOME).getOrThrow(
+                ResourceKey.create(Registries.BIOME, Identifier.parse(key))).value();
+        return Biome.DIRECT_CODEC.encodeStart(vanilla.createSerializationContext(JsonOps.INSTANCE), biome)
+                .getOrThrow().toString();
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeTileTest.java

@@ -0,0 +1,71 @@
+package art.arcane.iris.probe;
+
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeTileData;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.iris.modded.ModdedTileData;
+import net.minecraft.core.BlockPos;
+import net.minecraft.world.level.block.Blocks;
+import java.util.Map;
+import java.util.List;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeTileReader;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.data.registries.VanillaRegistries;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.DataInputStream;
+import java.io.DataOutputStream;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+
+public final class HeadlessNativeTileTest {
+    @BeforeClass
+    public static void bootstrap() {
+        HeadlessNativeBootstrap.initialize();
+    }
+
+    @Test
+    public void nativeTileBinaryRetainsTypedPayloadWithoutWorld() throws Exception {
+        NativeTileData captured = NativeTileData.capture("minecraft:player_head",
+                "{id:\"minecraft:skull\",profile:{id:[I;1,2,3,4]},note:[B;5b,6b]}",
+                message -> { throw new AssertionError(message); });
+        ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+        try (DataOutputStream output = new DataOutputStream(bytes)) {
+            captured.toBinary(output);
+        }
+        NativeTileReader reader = new NativeTileReader(VanillaRegistries::createWorldLookup);
+        NativeTileData decoded;
+        try (DataInputStream input = new DataInputStream(new ByteArrayInputStream(bytes.toByteArray()))) {
+            decoded = reader.read(input);
+        }
+        CompoundTag payload = decoded.payload();
+        assertEquals(captured.payload(), payload);
+        assertArrayEquals(new int[]{1, 2, 3, 4}, payload.getCompoundOrEmpty("profile").getIntArray("id").orElseThrow());
+        assertArrayEquals(new byte[]{5, 6}, payload.getByteArray("note").orElseThrow());
+        assertEquals(captured, decoded);
+    }
+
+    @Test
+    public void writesNativeTilePayloadIntoChunkAndRejectsMismatchedBlocks() throws Exception {
+        ModdedTileData tile = ModdedTileData.capture("minecraft:chest",
+                "{LootTable:'minecraft:chests/simple_dungeon',LootTableSeed:17L}");
+        HeadlessNativeTiles.Placement placement = new HeadlessNativeTiles.Placement(2, 4, 6,
+                new BlockPos(-32, -64, 48), ModdedBlockState.of(Blocks.CHEST.defaultBlockState(), Map.of()), tile);
+        NativeRegionTerrainWriter.TileInput input = HeadlessNativeTiles.prepare(placement);
+        NativeRegionTerrainWriter writer = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        CompoundTag chunk = writer.encode(new NativeRegionTerrainWriter.TerrainInput(-2, 3, -64, 16,
+                (x, y, z) -> x == 2 && y == 4 && z == 6 ? Blocks.CHEST.defaultBlockState() : Blocks.AIR.defaultBlockState(),
+                (x, y, z) -> "minecraft:plains", List.of(input)));
+        CompoundTag entity = chunk.getListOrEmpty("block_entities").getCompoundOrEmpty(0);
+        assertEquals("minecraft:chest", entity.getStringOr("id", ""));
+        assertEquals(17L, entity.getLongOr("LootTableSeed", 0));
+        assertEquals(-60, entity.getIntOr("y", 0));
+        assertThrows(IllegalStateException.class, () -> HeadlessNativeTiles.prepare(new HeadlessNativeTiles.Placement(
+                2, 4, 6, placement.origin(), ModdedBlockState.of(Blocks.BARREL.defaultBlockState(), Map.of()), tile)));
+    }
+
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessNativeTiles.java

@@ -0,0 +1,62 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.generation.block.TileData;
+import art.arcane.iris.generation.runtime.Engine;
+import art.arcane.iris.modded.ModdedTileData;
+import art.arcane.iris.world.storage.matter.TileWrapper;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.ModdedBlockState;
+import art.arcane.volmlib.nativelib.minecraft26_2.modded.NativeTileData;
+import art.arcane.volmlib.nativelib.terrain.NativeBlockState;
+import net.minecraft.core.BlockPos;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.world.level.block.EntityBlock;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+
+import java.util.ArrayList;
+import java.util.List;
+
+final class HeadlessNativeTiles {
+    private HeadlessNativeTiles() {
+    }
+
+    static List<NativeRegionTerrainWriter.TileInput> capture(Engine engine,
+                                                             RealPackProbeSupport.GeneratedChunk chunk,
+                                                             BlockPos origin) {
+        List<NativeRegionTerrainWriter.TileInput> tiles = new ArrayList<>();
+        engine.getMantle().getMantle().iterateChunk(origin.getX() >> 4, origin.getZ() >> 4,
+                TileWrapper.class, (x, y, z, wrapper) -> tiles.add(prepare(new Placement(x, y, z, origin,
+                        chunk.blocks().get(x, y, z), wrapper.getData()))));
+        return List.copyOf(tiles);
+    }
+
+    static NativeRegionTerrainWriter.TileInput prepare(Placement placement) {
+        if (!(placement.tile() instanceof ModdedTileData tile)
+                || !(placement.state() instanceof ModdedBlockState original)) {
+            throw new IllegalStateException("Native tile export requires native block and tile data");
+        }
+        NativeTileData data = tile.nativeData();
+        BlockState state = data.adjustBlockState(original.handle());
+        BlockPos position = placement.origin().offset(placement.x(), placement.y(), placement.z());
+        if (!(state.getBlock() instanceof EntityBlock block)) {
+            throw new IllegalStateException("Tile data has no native block entity at " + position);
+        }
+        BlockEntity entity = block.newBlockEntity(position, state);
+        if (entity == null || !data.isApplicable(state, entity)) {
+            throw new IllegalStateException("Tile data does not match native block at " + position);
+        }
+        try {
+            CompoundTag payload = data.payload();
+            if (payload == null) {
+                throw new IllegalStateException("Tile data has no native payload at " + position);
+            }
+            return new NativeRegionTerrainWriter.TileInput(placement.x(), placement.y(), placement.z(),
+                    ModdedBlockState.serialize(state), payload);
+        } catch (Exception failure) {
+            throw new IllegalStateException("Cannot export native tile payload at " + position, failure);
+        }
+    }
+
+    record Placement(int x, int y, int z, BlockPos origin, NativeBlockState state, TileData tile) {
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessRegionTerrainTest.java

@@ -0,0 +1,197 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.structure.nativegen.NativeStructureVolumeIndex;
+import art.arcane.iris.generation.hydrology.HydrologyTileCache;
+import art.arcane.volmlib.nativelib.terrain.structure.NativeStructureVolume;
+import art.arcane.volmlib.util.collection.KList;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.NbtIo;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.chunk.storage.RegionFile;
+import net.minecraft.world.level.chunk.storage.RegionStorageInfo;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import org.bukkit.Bukkit;
+import org.bukkit.NamespacedKey;
+import org.bukkit.persistence.PersistentDataType;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.spigotmc.SpigotWorldConfig;
+
+import java.io.DataInputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Random;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+
+public final class HeadlessRegionTerrainTest {
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+
+    @Test
+    public void producesNativeTerrainAndFullCompletionHaloWithoutAServer() throws Exception {
+        Path root = temporary.newFolder().toPath();
+        Path configuration = root.resolve("spigot.yml");
+        Files.writeString(configuration, "config-version: 13\nworld-settings:\n  default:\n    verbose: false\n");
+        HeadlessNativeRuntime runtime = new HeadlessNativeRuntime();
+        try (RealPackProbeSupport.Workspace workspace = RealPackProbeSupport.openWorkspace(new RealPackProbeSupport.WorkspaceOptions(
+                pack().toFile(), "main", "[headless-native-grid-test]", runtime, temporary.getRoot().toPath()));
+             RealPackProbeSupport.EngineSession session = workspace.openEngine(69420L, false, "native-grid")) {
+            NativeStructureVolume volume = NativeStructureVolume.of("minecraft:swamp_hut", 0, 20, 0, 7, 30, 7);
+            NativeStructureVolumeIndex.install(session.engine(), (engine, x, z) ->
+                    x == 0 && z == 0 ? new KList<>(List.of(volume)) : NativeStructureVolume.NONE);
+            assertEquals(List.of(volume), session.engine().getNativeStructureVolumes(0, 0, 15, 15));
+            SpigotWorldConfig spigot = HeadlessStructureConfiguration.load(new HeadlessStructureConfiguration.Options(
+                    configuration, "probe", Level.OVERWORLD, root.resolve("configuration")));
+            try (HeadlessTerrainContext context = HeadlessTerrainContext.create(new HeadlessTerrainContext.Options(
+                    session.engine(), runtime, root.resolve("templates"), Level.OVERWORLD,
+                    NoiseGeneratorSettings.OVERWORLD, spigot));
+                 RegionGenerationWindow workers = new RegionGenerationWindow(4, RegionGenerationWindow.Policy.EMBEDDED)) {
+                HeadlessRegionTerrain.Session rolling = new HeadlessRegionTerrain.Session(workers);
+                HeadlessRegionTerrain.Result result = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, -3, 2, 1, 4), System.out::println);
+                OfflineRegionGenerator.Configuration export = new OfflineRegionGenerator.Configuration(
+                        workspace.pack(), "main", 69420L, -3, 2, 1, 2, 3, 4, configuration,
+                        "probe", Level.OVERWORLD, NoiseGeneratorSettings.OVERWORLD, root.resolve("export"));
+                HydrologyTileCache.PregenerationArea bounds = export.hydrologyArea();
+                assertEquals(-80L, bounds.minimumBlockX());
+                assertEquals(0L, bounds.minimumBlockZ());
+                assertEquals(15L, bounds.maximumBlockX());
+                assertEquals(111L, bounds.maximumBlockZ());
+                assertEquals(1, result.targetChunks());
+                assertEquals(529, result.chunks().size());
+                long terrain = result.chunks().stream().filter(chunk -> chunk.getPersistedStatus() == ChunkStatus.TERRAIN).count();
+                long biomes = result.chunks().stream().filter(chunk -> chunk.getPersistedStatus() == ChunkStatus.BIOMES).count();
+                assertEquals(25L, terrain);
+                assertEquals(24L, biomes);
+                ProtoChunk target = result.chunks().stream().filter(chunk -> chunk.getPos().equals(new ChunkPos(-3, 2)))
+                        .findFirst().orElseThrow();
+                CompoundTag tag = HeadlessChunkSerialization.copyOf(target, context.serialization()).write();
+                assertEquals("minecraft:terrain", tag.getStringOr("Status", ""));
+                assertFalse(tag.getBooleanOr("isLightOn", false));
+                assertTrue(tag.getCompoundOrEmpty("Heightmaps").contains("WORLD_SURFACE_WG"));
+                assertTrue(tag.getCompoundOrEmpty("Heightmaps").contains("OCEAN_FLOOR_WG"));
+                assertEquals(6, tag.getCompoundOrEmpty("Heightmaps").size());
+                assertTrue(tag.getCompoundOrEmpty("ChunkBukkitValues").contains("iris:natural_terrain"));
+                assertTrue(tag.getCompoundOrEmpty("ChunkBukkitValues").contains("iris:structure_activation"));
+                assertFalse(tag.getListOrEmpty("sections").isEmpty());
+                assertTrue(RealPackProbeSupport.drainReported().isEmpty());
+                assertNull(Bukkit.getServer());
+                HeadlessRegionTerrain.Result repeated = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, -3, 2, 1, 4), System.out::println);
+                assertEquals(0, repeated.updated().size());
+                HeadlessRegionTerrain.Result adjacent = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, -2, 2, 1, 4), System.out::println);
+                assertEquals(529, adjacent.chunks().size());
+                assertTrue(adjacent.updated().size() < result.updated().size());
+                ProtoChunk retained = adjacent.chunks().stream().filter(chunk -> chunk.getPos().equals(target.getPos()))
+                        .findFirst().orElseThrow();
+                assertSame(target, retained);
+                assertEquals(ChunkStatus.TERRAIN, retained.getPersistedStatus());
+                Path regionDirectory = Files.createDirectory(root.resolve("region"));
+                OfflineRegionWriter writer = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                        context, regionDirectory, workers));
+                OfflineRegionWriter.Result firstWrite = writer.write(result);
+                assertEquals(result.updated().size(), firstWrite.chunks());
+                assertEquals(tag, read(regionDirectory, target.getPos()));
+                OfflineRegionWriter.Result duplicateWrite = writer.write(result);
+                assertEquals(0, duplicateWrite.chunks());
+                OfflineRegionWriter reopened = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                        context, regionDirectory, workers));
+                assertEquals(0, reopened.write(result).chunks());
+                target.setPersistedStatus(ChunkStatus.STRUCTURE_STARTS);
+                try {
+                    assertEquals(0, writer.write(
+                            new HeadlessRegionTerrain.Result(List.of(target), List.of(target), 1)).chunks());
+                } finally {
+                    target.setPersistedStatus(ChunkStatus.TERRAIN);
+                }
+                HeadlessRegionTerrain.Result nextRow = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, -2, 3, 1, 4), System.out::println);
+                assertEquals(529, nextRow.chunks().size());
+                assertSame(target, nextRow.chunks().stream().filter(chunk -> chunk.getPos().equals(target.getPos()))
+                        .findFirst().orElseThrow());
+                assertTrue(nextRow.updated().size() < result.updated().size());
+                HeadlessRegionTerrain.Result distant = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, 20, 2, 1, 4), System.out::println);
+                assertEquals(529, distant.chunks().size());
+                ProtoChunk previousHalo = distant.chunks().getFirst();
+                HeadlessRegionTerrain.Result back = rolling.generate(
+                        new HeadlessRegionTerrain.Request(context, -3, 2, 1, 4), System.out::println);
+                assertFalse(back.chunks().contains(previousHalo));
+                ProtoChunk regenerated = back.chunks().stream().filter(chunk -> chunk.getPos().equals(target.getPos()))
+                        .findFirst().orElseThrow();
+                CompoundTag regeneratedTag = HeadlessChunkSerialization.copyOf(regenerated, context.serialization()).write();
+                for (String key : List.of("sections", "Heightmaps", "structures", "ChunkBukkitValues")) {
+                    assertEquals(key, tag.get(key), regeneratedTag.get(key));
+                }
+                assertEquals(0, writer.write(back).chunks());
+                Path oversizedDirectory = Files.createDirectory(root.resolve("oversized"));
+                OfflineRegionWriter oversizedWriter = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                        context, oversizedDirectory, workers));
+                NamespacedKey payloadKey = new NamespacedKey("iris", "serialization_test_payload");
+                byte[] payload = new byte[2 * 1024 * 1024];
+                new Random(69420L).nextBytes(payload);
+                regenerated.persistentDataContainer.set(payloadKey, PersistentDataType.BYTE_ARRAY, payload);
+                HeadlessRegionTerrain.Result singleton = new HeadlessRegionTerrain.Result(List.of(regenerated), List.of(regenerated), 1);
+                assertEquals(1, oversizedWriter.write(singleton).chunks());
+                assertTrue(Files.isRegularFile(oversizedDirectory.resolve("c.-3.2.mcc")));
+                assertArrayEquals(payload, read(oversizedDirectory, regenerated.getPos())
+                        .getCompoundOrEmpty("ChunkBukkitValues").getByteArray("iris:serialization_test_payload").orElseThrow());
+                regenerated.persistentDataContainer.remove(payloadKey);
+                Path failedDirectory = Files.createDirectory(root.resolve("failed"));
+                OfflineRegionWriter failedWriter = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                        context, failedDirectory, workers));
+                regenerated.setPersistedStatus(ChunkStatus.FULL);
+                try {
+                    assertThrows(Exception.class, () -> failedWriter.write(singleton));
+                } finally {
+                    regenerated.setPersistedStatus(ChunkStatus.TERRAIN);
+                }
+                assertThrows(IllegalStateException.class, () -> failedWriter.write(singleton));
+                try (RegionGenerationWindow replacement = new RegionGenerationWindow(4, RegionGenerationWindow.Policy.EMBEDDED)) {
+                    OfflineRegionWriter retried = new OfflineRegionWriter(new OfflineRegionWriter.Options(
+                            context, failedDirectory, replacement));
+                    assertEquals(1, retried.write(singleton).chunks());
+                }
+                assertEquals("minecraft:terrain", read(failedDirectory, regenerated.getPos()).getStringOr("Status", ""));
+            }
+        }
+    }
+
+    private static CompoundTag read(Path directory, ChunkPos position) throws Exception {
+        Path path = directory.resolve("r." + (position.x() >> 5) + "." + (position.z() >> 5) + ".mca");
+        try (RegionFile region = new RegionFile(new RegionStorageInfo("test", Level.OVERWORLD, "chunk"), path, directory, false);
+             DataInputStream input = region.getChunkDataInputStream(position)) {
+            return NbtIo.read(input);
+        }
+    }
+
+    private Path pack() throws Exception {
+        Path pack = temporary.newFolder().toPath();
+        for (String directory : List.of("dimensions", "regions", "biomes", "generators")) {
+            Files.createDirectories(pack.resolve(directory));
+        }
+        Files.writeString(pack.resolve("dimensions/main.json"), """
+                {"name":"Native region","focus":"swamp","regions":["owned"],"fluidHeight":40,"logicalHeight":256,
+                 "landChance":1,"carvingEnabled":false,"hydrology":{"rivers":{"enabled":false}}}
+                """);
+        Files.writeString(pack.resolve("regions/owned.json"), "{\"landBiomes\":[\"swamp\"]}");
+        Files.writeString(pack.resolve("generators/flat.json"), "{\"composite\":[]}");
+        Files.writeString(pack.resolve("biomes/swamp.json"), """
+                {"derivative":"minecraft:swamp","generators":[{"generator":"flat","min":35,"max":35}]}
+                """);
+        return pack;
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessStructureConfigurationTest.java

@@ -0,0 +1,163 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.world.level.Level;
+import org.bukkit.configuration.file.YamlConfiguration;
+import org.junit.Rule;
+import org.junit.BeforeClass;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.spigotmc.SpigotConfig;
+import org.spigotmc.SpigotWorldConfig;
+
+import java.io.IOException;
+import java.lang.reflect.Field;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Comparator;
+import java.util.Locale;
+import java.util.stream.Stream;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class HeadlessStructureConfigurationTest {
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+
+    @BeforeClass
+    public static void initializeNative() {
+        HeadlessNativeBootstrap.initialize();
+    }
+
+    @Test
+    public void nativeConstructorInitializesEveryDefaultWithoutChangingTheSourceOrGlobals() throws Exception {
+        Path source = temporary.newFile("spigot.yml").toPath();
+        Path staging = temporary.newFolder().toPath();
+        byte[] original = Files.readAllBytes(source);
+        YamlConfiguration previous = SpigotConfig.config;
+        Object previousFile = nativeField("CONFIG_FILE").get(null);
+        int previousVersion = nativeField("version").getInt(null);
+        SpigotWorldConfig configuration = HeadlessStructureConfiguration.load(options(source, staging));
+        assertEquals(SpigotWorldConfig.class, configuration.getClass());
+        int checked = 0;
+        for (Field field : seedFields()) {
+            if (field.getType() == int.class) {
+                assertTrue(field.getName(), field.getInt(configuration) > 0);
+            } else {
+                assertNull(field.getName(), field.get(configuration));
+            }
+            checked++;
+        }
+        assertTrue(checked >= 22);
+        assertEquals(100, configuration.cactusModifier);
+        assertArrayEquals(original, Files.readAllBytes(source));
+        assertSame(previous, SpigotConfig.config);
+        assertEquals(previousFile, nativeField("CONFIG_FILE").get(null));
+        assertEquals(previousVersion, nativeField("version").getInt(null));
+        assertEmpty(staging);
+    }
+
+    @Test
+    public void everyNativeSeedHonorsDefaultAndNamespacedOverrides() throws Exception {
+        Path source = temporary.newFile("overrides.yml").toPath();
+        Path staging = temporary.newFolder().toPath();
+        YamlConfiguration yaml = new YamlConfiguration();
+        yaml.set("config-version", 13);
+        int ordinal = 0;
+        for (Field field : seedFields()) {
+            String path = seedPath(field);
+            yaml.set("world-settings.default." + path, 12000 + ordinal);
+            yaml.set("world-settings.minecraft:overworld." + path,
+                    field.getType() == Long.class ? 9000000000L + ordinal : 24000L + ordinal);
+            ordinal++;
+        }
+        yaml.set("world-settings.default.verbose", true);
+        yaml.set("world-settings.legacy.seed-swamp", 9);
+        yaml.save(source.toFile());
+        byte[] original = Files.readAllBytes(source);
+        SpigotWorldConfig configured = HeadlessStructureConfiguration.load(options(source, staging));
+        ordinal = 0;
+        for (Field field : seedFields()) {
+            assertEquals(field.getName(), field.getType() == Long.class ? 9000000000L + ordinal : 24000L + ordinal,
+                    ((Number) field.get(configured)).longValue());
+            ordinal++;
+        }
+        assertArrayEquals(original, Files.readAllBytes(source));
+        yaml.set("world-settings.minecraft:overworld", null);
+        yaml.save(source.toFile());
+        SpigotWorldConfig defaults = HeadlessStructureConfiguration.load(options(source, staging));
+        ordinal = 0;
+        for (Field field : seedFields()) {
+            assertEquals(field.getName(), 12000L + ordinal++, ((Number) field.get(defaults)).longValue());
+        }
+        assertEmpty(staging);
+    }
+
+    @Test
+    public void legacyMigrationRetainsNativePrecedenceAndFailuresRestoreState() throws Exception {
+        Path source = temporary.newFile("legacy.yml").toPath();
+        Path staging = temporary.newFolder().toPath();
+        Files.writeString(source, """
+                config-version: 12
+                world-settings:
+                  default:
+                    seed-swamp: 11
+                  legacy:
+                    seed-swamp: 73
+                    verbose: true
+                  minecraft:overworld:
+                    seed-swamp: 99
+                """);
+        byte[] original = Files.readAllBytes(source);
+        assertEquals(73, HeadlessStructureConfiguration.load(options(source, staging)).swampSeed);
+        assertArrayEquals(original, Files.readAllBytes(source));
+        assertEquals(99, HeadlessStructureConfiguration.load(new HeadlessStructureConfiguration.Options(
+                source, "minecraft:overworld", Level.OVERWORLD, staging)).swampSeed);
+        assertArrayEquals(original, Files.readAllBytes(source));
+        YamlConfiguration previous = SpigotConfig.config;
+        Object previousFile = nativeField("CONFIG_FILE").get(null);
+        int previousVersion = nativeField("version").getInt(null);
+        for (String invalid : List.of("world-settings: [broken", "world-settings:\n  default:\n    seed-stronghold: '2.5'\n")) {
+            Files.writeString(source, invalid);
+            IOException failure = assertThrows(IOException.class,
+                    () -> HeadlessStructureConfiguration.load(options(source, staging)));
+            assertNotNull(failure.getCause());
+            assertEquals(invalid, Files.readString(source));
+            assertSame(previous, SpigotConfig.config);
+            assertEquals(previousFile, nativeField("CONFIG_FILE").get(null));
+            assertEquals(previousVersion, nativeField("version").getInt(null));
+            assertEmpty(staging);
+        }
+    }
+
+    private static HeadlessStructureConfiguration.Options options(Path source, Path staging) {
+        return new HeadlessStructureConfiguration.Options(source, "legacy", Level.OVERWORLD, staging);
+    }
+
+    private static List<Field> seedFields() {
+        return Stream.of(SpigotWorldConfig.class.getFields()).filter(field -> field.getName().endsWith("Seed"))
+                .sorted(Comparator.comparing(Field::getName)).toList();
+    }
+
+    private static String seedPath(Field field) {
+        return "seed-" + field.getName().substring(0, field.getName().length() - 4).toLowerCase(Locale.ROOT);
+    }
+
+    private static Field nativeField(String name) throws Exception {
+        Field field = SpigotConfig.class.getDeclaredField(name);
+        field.setAccessible(true);
+        return field;
+    }
+
+    private static void assertEmpty(Path directory) throws IOException {
+        try (Stream<Path> entries = Files.list(directory)) {
+            assertEquals(0L, entries.count());
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/HeadlessStructurePlannerTest.java

@@ -0,0 +1,366 @@
+package art.arcane.iris.probe;
+
+import art.arcane.iris.structure.nativegen.IrisNativeStructure;
+import art.arcane.iris.structure.nativegen.IrisNativeStructureDecision;
+import art.arcane.iris.structure.nativegen.NativeStructureGenerationStatus;
+import art.arcane.iris.structure.nativegen.NativeStructureOwnershipRecord;
+import art.arcane.iris.structure.nativegen.NativeStructureStartPlan;
+import art.arcane.iris.structure.placement.IrisStructurePlacement;
+import art.arcane.iris.structure.placement.IrisStructureTerrain;
+import art.arcane.volmlib.nativelib.terrain.NativeGenerationScope;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureFingerprint;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureInjectionPolicy;
+import art.arcane.volmlib.nativelib.terrain.structure.StructurePlacementDecision;
+import art.arcane.volmlib.nativelib.terrain.structure.StructureReferencePolicy;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureFactory;
+import art.arcane.volmlib.nativelib.v26_3_R1.terrain.NativeStructureOwnershipFingerprint;
+import art.arcane.volmlib.util.structure.StructureTerrainMode;
+import com.mojang.serialization.Lifecycle;
+import net.kyori.adventure.key.Key;
+import net.minecraft.core.Holder;
+import net.minecraft.core.HolderLookup;
+import net.minecraft.core.HolderSet;
+import net.minecraft.core.MappedRegistry;
+import net.minecraft.core.Registry;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.RegistrationInfo;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.data.registries.VanillaRegistries;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.packs.PackType;
+import net.minecraft.server.packs.repository.ServerPacksSource;
+import net.minecraft.server.packs.resources.MultiPackResourceManager;
+import net.minecraft.util.datafix.DataFixers;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.FixedBiomeSource;
+import net.minecraft.world.level.biome.MultiNoiseBiomeSource;
+import net.minecraft.world.level.biome.MultiNoiseBiomeSourceParameterLists;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.WorldOptions;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.structure.Structure;
+import net.minecraft.world.level.levelgen.structure.StructureSet;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.structure.StructureType;
+import net.minecraft.world.level.levelgen.structure.pieces.StructurePieceSerializationContext;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadStructurePlacement;
+import net.minecraft.world.level.levelgen.structure.placement.RandomSpreadType;
+import net.minecraft.world.level.levelgen.structure.structures.SwampHutStructure;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+import net.minecraft.world.level.storage.LevelStorageSource;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+import org.spigotmc.SpigotWorldConfig;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.Optional;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+
+public class HeadlessStructurePlannerTest {
+    private static final long SEED = 69420L;
+    @Rule
+    public TemporaryFolder temporary = new TemporaryFolder();
+    private HolderLookup.Provider lookup;
+    private MappedRegistry<Biome> biomes;
+    private Holder.Reference<Biome> biome;
+    private RandomState random;
+    private ChunkGenerator generator;
+
+    @Before
+    public void initialize() {
+        HeadlessNativeBootstrap.initialize();
+        lookup = VanillaRegistries.createWorldLookup();
+        biomes = new MappedRegistry<>(Registries.BIOME, Lifecycle.stable());
+        Biome value = lookup.lookupOrThrow(Registries.BIOME).getOrThrow(
+                ResourceKey.create(Registries.BIOME, Identifier.parse("minecraft:plains"))).value();
+        biome = biomes.register(ResourceKey.create(Registries.BIOME, Identifier.parse("minecraft:plains")),
+                value, RegistrationInfo.BUILT_IN);
+        biomes.freeze();
+        Holder.Reference<NoiseGeneratorSettings> settings = lookup.lookupOrThrow(Registries.NOISE_SETTINGS)
+                .getOrThrow(NoiseGeneratorSettings.OVERWORLD);
+        random = RandomState.create(lookup.lookupOrThrow(Registries.NOISE), SEED, settings.value());
+        generator = new NoiseBasedChunkGenerator(new FixedBiomeSource(biome), settings);
+    }
+
+    @Test
+    public void weightedFailedTrialsMatchNativeSelectionAndClimateAtNegativeCoordinates() throws Exception {
+        generator = new NoiseBasedChunkGenerator(MultiNoiseBiomeSource.createFromPreset(
+                lookup.lookupOrThrow(Registries.MULTI_NOISE_BIOME_SOURCE_PARAMETER_LIST)
+                        .getOrThrow(MultiNoiseBiomeSourceParameterLists.OVERWORLD)),
+                lookup.lookupOrThrow(Registries.NOISE_SETTINGS).getOrThrow(NoiseGeneratorSettings.OVERWORLD));
+        List<String> attempts = new ArrayList<>();
+        Set<String> climates = new HashSet<>();
+        MappedRegistry<Structure> structures = new MappedRegistry<>(Registries.STRUCTURE, Lifecycle.stable());
+        List<StructureSet.StructureSelectionEntry> entries = new ArrayList<>();
+        for (int index = 0; index < 4; index++) {
+            String key = "probe:rejected_" + index;
+            Holder.Reference<Structure> holder = structures.register(ResourceKey.create(Registries.STRUCTURE,
+                    Identifier.parse(key)), new RejectedStructure(
+                    HolderSet.direct(List.copyOf(generator.getBiomeSource().possibleBiomes())), key, attempts), RegistrationInfo.BUILT_IN);
+            entries.add(new StructureSet.StructureSelectionEntry(holder, index + 1));
+        }
+        structures.freeze();
+        RegistryAccess registries = new RegistryAccess.ImmutableRegistryAccess(List.of(biomes, structures));
+        ChunkGeneratorStructureState state = state(entries, "probe:weighted", 18373);
+        try (MultiPackResourceManager resources = resources();
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(temporary.newFolder().toPath()).createAccess("world")) {
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            HeadlessStructurePlanner.NativeContext context = new HeadlessStructurePlanner.NativeContext(
+                    registries, generator, state, templates, Level.OVERWORLD, new WorldOptions(SEED, true, false), true);
+            for (ChunkPos position : List.of(new ChunkPos(-17, 31), new ChunkPos(0, 0), new ChunkPos(17, -31))) {
+                attempts.clear();
+                generator.createStructures(registries, state,
+                        new StructureManager(null, new WorldOptions(SEED, true, false), null), chunk(position, registries),
+                        templates, Level.OVERWORLD);
+                List<String> nativeAttempts = List.copyOf(attempts);
+                attempts.clear();
+                HeadlessStructurePlanner.generateNaturalStarts(context, chunk(position, registries));
+                assertEquals(nativeAttempts, attempts);
+                assertEquals(4, attempts.size());
+                climates.add(attempts.getFirst().split("\\|", 3)[1]);
+            }
+            assertTrue(climates.size() > 1);
+        }
+    }
+
+    @Test
+    public void nativePiecesAndConfiguredPlacementSaltArePreserved() throws Exception {
+        MappedRegistry<Structure> structures = new MappedRegistry<>(Registries.STRUCTURE, Lifecycle.stable());
+        Holder.Reference<Structure> hut = structures.register(ResourceKey.create(Registries.STRUCTURE,
+                Identifier.parse("probe:hut")), new SwampHutStructure(new Structure.StructureSettings(HolderSet.direct(biome))),
+                RegistrationInfo.BUILT_IN);
+        structures.freeze();
+        RegistryAccess registries = new RegistryAccess.ImmutableRegistryAccess(List.of(biomes, structures));
+        ChunkGeneratorStructureState state = state(List.of(new StructureSet.StructureSelectionEntry(hut, 1)),
+                "minecraft:villages", 18373);
+        RandomSpreadStructurePlacement placement = (RandomSpreadStructurePlacement) state.possibleStructureSets().getFirst().value().placement();
+        try (MultiPackResourceManager resources = resources();
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(temporary.newFolder().toPath()).createAccess("world")) {
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            HeadlessStructurePlanner.NativeContext context = new HeadlessStructurePlanner.NativeContext(
+                    registries, generator, state, templates, Level.OVERWORLD, new WorldOptions(SEED, true, false), true);
+            ChunkPos position = placement.getPotentialStructureChunk(SEED, -33, 17);
+            ProtoChunk chunk = chunk(position, registries);
+            HeadlessStructurePlanner.generateNaturalStarts(context, chunk);
+            StructureStart expected = hut.value().generate(hut, Level.OVERWORLD, registries, generator,
+                    generator.getBiomeSource(), random.createClimateSampler(SamplerContext.builder().enableCaches().build()),
+                    random, templates, SEED, position, 0, chunk, hut.value().biomes()::contains);
+            assertTrue(expected.isValid());
+            StructurePieceSerializationContext serialization = new StructurePieceSerializationContext(resources, registries, templates);
+            CompoundTag expectedTag = expected.createTag(serialization, position);
+            assertEquals(expectedTag, chunk.getStartForStructure(hut.value()).createTag(serialization, position));
+            RandomSpreadStructurePlacement configured = new RandomSpreadStructurePlacement(7, 1, RandomSpreadType.LINEAR, 17);
+            assertEquals(configured.getPotentialStructureChunk(SEED, -33, 17), position);
+            HeadlessStructurePlanner.NativeContext disabled = new HeadlessStructurePlanner.NativeContext(
+                    registries, generator, state, templates, Level.OVERWORLD, new WorldOptions(SEED, false, false), true);
+            ProtoChunk empty = chunk(position, registries);
+            HeadlessStructurePlanner.generateNaturalStarts(disabled, empty);
+            assertTrue(empty.getAllStarts().isEmpty());
+        }
+    }
+
+    private ChunkGeneratorStructureState state(List<StructureSet.StructureSelectionEntry> entries, String key, int salt) {
+        MappedRegistry<StructureSet> sets = new MappedRegistry<>(Registries.STRUCTURE_SET, Lifecycle.stable());
+        sets.register(ResourceKey.create(Registries.STRUCTURE_SET, Identifier.parse(key)), new StructureSet(entries,
+                new RandomSpreadStructurePlacement(key.equals("minecraft:villages") ? 7 : 1,
+                        key.equals("minecraft:villages") ? 1 : 0, RandomSpreadType.LINEAR, salt)), RegistrationInfo.BUILT_IN);
+        sets.freeze();
+        return ChunkGeneratorStructureState.createForNormal(random, SEED, generator.getOrigin(random),
+                generator.getBiomeSource(), sets, configuration());
+    }
+
+    @Test
+    public void configuredStartsKeepOwnershipTerrainAndReferencesBeyondPieceBounds() throws Exception {
+        MappedRegistry<Structure> structures = new MappedRegistry<>(Registries.STRUCTURE, Lifecycle.stable());
+        Holder.Reference<Structure> hut = structures.register(ResourceKey.create(Registries.STRUCTURE,
+                Identifier.parse("probe:hut")), new SwampHutStructure(new Structure.StructureSettings(HolderSet.direct(biome))),
+                RegistrationInfo.BUILT_IN);
+        structures.freeze();
+        RegistryAccess registries = new RegistryAccess.ImmutableRegistryAccess(List.of(biomes, structures));
+        MappedRegistry<StructureSet> sets = new MappedRegistry<>(Registries.STRUCTURE_SET, Lifecycle.stable());
+        sets.freeze();
+        ChunkGeneratorStructureState state = ChunkGeneratorStructureState.createForNormal(random, SEED,
+                generator.getOrigin(random), generator.getBiomeSource(), sets, configuration());
+        IrisStructureTerrain terrain = new IrisStructureTerrain().setMode(StructureTerrainMode.BORE).setHorizontalPadding(24);
+        NativeStructureStartPlan plan = new NativeStructureStartPlan(
+                new IrisStructurePlacement().setUnderground(true).setTerrain(terrain),
+                new IrisNativeStructure().setStructure("probe:hut"), -1, 0, 30);
+        TestPolicy policy = new TestPolicy(plan);
+        HeadlessStructurePlanner.Policies<NativeStructureStartPlan, NativeStructureOwnershipRecord> policies =
+                new HeadlessStructurePlanner.Policies<>(policy, policy, footprint -> true);
+        try (MultiPackResourceManager resources = resources();
+             LevelStorageSource.LevelStorageAccess storage = LevelStorageSource.createDefault(temporary.newFolder().toPath()).createAccess("world")) {
+            StructureTemplateManager templates = new StructureTemplateManager(resources, storage,
+                    DataFixers.getDataFixer(), BuiltInRegistries.BLOCK);
+            HeadlessStructurePlanner.NativeContext context = new HeadlessStructurePlanner.NativeContext(
+                    registries, generator, state, templates, Level.OVERWORLD, new WorldOptions(SEED, true, false), true);
+            Map<Long, HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord>> grid = new HashMap<>();
+            for (int x = -10; x <= 6; x++) {
+                for (int z = -8; z <= 8; z++) {
+                    ChunkPos position = new ChunkPos(x, z);
+                    grid.put(position.pack(), HeadlessStructurePlanner.plan(context, policies, position));
+                }
+            }
+            HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> origin = grid.get(new ChunkPos(-1, 0).pack());
+            StructureStart actual = origin.chunk().getStartForStructure(hut.value());
+            StructureStart expected = NativeStructureFactory.generate(new NativeStructureFactory.GenerationContext(
+                    registries, generator, generator.getBiomeSource(), random, templates, SEED, Level.OVERWORLD,
+                    origin.chunk(), selected -> true, generator.getSeaLevel(), policy::surfaceHeight), hut, plan, 0);
+            StructurePieceSerializationContext serialization = new StructurePieceSerializationContext(resources, registries, templates);
+            assertEquals(expected.createTag(serialization, origin.chunk().getPos()), actual.createTag(serialization, origin.chunk().getPos()));
+            assertEquals(30, actual.getBoundingBox().minY());
+            assertTrue(NativeStructureOwnershipFingerprint.matches(origin.ownership().get(hut.value()), actual));
+            assertEquals(StructureTerrainMode.BORE, origin.terrain().get(hut.value()).resolvedMode());
+            HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> target = grid.get(new ChunkPos(-2, 0).pack());
+            assertFalse(actual.getBoundingBox().intersects(-32, 0, -17, 15));
+            Map<Long, HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord>> incomplete = new HashMap<>(grid);
+            incomplete.remove(new ChunkPos(-10, -8).pack());
+            assertThrows(IllegalArgumentException.class, () -> HeadlessStructurePlanner.references(policies, target, incomplete));
+            assertTrue(target.chunk().getAllReferences().isEmpty());
+            HeadlessStructurePlanner.references(policies, target, grid);
+            assertTrue(target.chunk().getAllReferences().get(hut.value()).contains(new ChunkPos(-1, 0).pack()));
+            assertEquals(ChunkStatus.STRUCTURE_REFERENCES, target.chunk().getPersistedStatus());
+            HeadlessStructurePlanner.Policies<NativeStructureStartPlan, NativeStructureOwnershipRecord> excluded =
+                    new HeadlessStructurePlanner.Policies<>(policy, policy, footprint -> false);
+            HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> rejected = HeadlessStructurePlanner.plan(
+                    context, excluded, new ChunkPos(-1, 0));
+            assertFalse(rejected.chunk().getStartForStructure(hut.value()).isValid());
+            assertTrue(rejected.ownership().isEmpty());
+            assertTrue(rejected.terrain().isEmpty());
+            assertEquals(1, policy.discards);
+            policy.hideOwnership = true;
+            assertThrows(IllegalStateException.class, () -> HeadlessStructurePlanner.plan(context, policies, new ChunkPos(-1, 0)));
+            assertEquals(2, policy.discards);
+            for (boolean adapterEnabled : new boolean[]{true, false}) {
+                HeadlessStructurePlanner.NativeContext disabled = new HeadlessStructurePlanner.NativeContext(
+                        registries, generator, state, templates, Level.OVERWORLD,
+                        new WorldOptions(SEED, !adapterEnabled, false), adapterEnabled);
+                HeadlessStructurePlanner.PlannedChunk<NativeStructureOwnershipRecord> empty = HeadlessStructurePlanner.plan(
+                        disabled, policies, new ChunkPos(-1, 0));
+                assertTrue(empty.chunk().getAllStarts().isEmpty());
+                assertTrue(empty.ownership().isEmpty());
+                if (!adapterEnabled) {
+                    int scopes = policy.scopes;
+                    HeadlessStructurePlanner.references(policies, empty, Map.of());
+                    assertEquals(scopes, policy.scopes);
+                    assertTrue(empty.chunk().getAllReferences().isEmpty());
+                    assertEquals(ChunkStatus.STRUCTURE_REFERENCES, empty.chunk().getPersistedStatus());
+                }
+            }
+            assertEquals(2, policy.discards);
+            assertThrows(IllegalArgumentException.class, () -> new HeadlessStructurePlanner.NativeContext(
+                    registries, generator, state, templates, Level.OVERWORLD,
+                    new WorldOptions(SEED + 1, true, false), true));
+        }
+    }
+
+    private static SpigotWorldConfig configuration() {
+        return new SpigotWorldConfig("probe", Key.key("probe:world")) {
+            @Override
+            public void init() {
+                villageSeed = 17;
+            }
+        };
+    }
+
+    private static final class TestPolicy implements StructureInjectionPolicy<NativeStructureStartPlan>,
+            StructureReferencePolicy<NativeStructureStartPlan, NativeStructureOwnershipRecord> {
+        private final NativeStructureStartPlan plan;
+        private NativeStructureOwnershipRecord ownership;
+        private boolean hideOwnership;
+        private int discards;
+        private int scopes;
+
+        private TestPolicy(NativeStructureStartPlan plan) { this.plan = plan; }
+        @Override public List<NativeStructureStartPlan> plansAt(int x, int z) {
+            return x == plan.chunkX() && z == plan.chunkZ() ? List.of(plan) : List.of();
+        }
+        @Override public boolean sourceReplaced(String key, boolean underground) { return false; }
+        @Override public int surfaceHeight(int x, int z) { return 80; }
+        @Override public void record(NativeStructureStartPlan selected, StructureFingerprint fingerprint) {
+            ownership = NativeStructureOwnershipRecord.capture(fingerprint, selected);
+        }
+        @Override public void discard(String key, int x, int z) { ownership = null; discards++; }
+        @Override public void duplicate(String key) { throw new AssertionError(key); }
+        @Override public NativeStructureStartPlan matchingPlan(String key, int x, int z) {
+            return plansAt(x, z).stream().findFirst().orElse(null);
+        }
+        @Override public NativeStructureOwnershipRecord findPersisted(String key, int x, int z) {
+            return !hideOwnership && ownership != null && ownership.structureKey().equals(key) && ownership.originChunkX() == x
+                    && ownership.originChunkZ() == z ? ownership : null;
+        }
+        @Override public NativeStructureOwnershipRecord capture(StructureFingerprint fingerprint, NativeStructureStartPlan selected) {
+            return NativeStructureOwnershipRecord.capture(fingerprint, selected);
+        }
+        @Override public void record(NativeStructureOwnershipRecord record) { ownership = record; }
+        @Override public NativeGenerationScope openOriginScope(int x, int z) { scopes++; return () -> {}; }
+        @Override public StructurePlacementDecision resolve(String key, boolean underground) {
+            return new IrisNativeStructureDecision(NativeStructureGenerationStatus.GENERATE_NATIVE, 0, null,
+                    true, null, new IrisStructureTerrain());
+        }
+        @Override public void invalidated(String key) { throw new AssertionError(key); }
+    }
+
+    private static ProtoChunk chunk(ChunkPos position, RegistryAccess registries) {
+        return new ProtoChunk(position, UpgradeData.EMPTY, LevelHeightAccessor.create(-64, 384),
+                PalettedContainerFactory.create(registries), null);
+    }
+
+    private static MultiPackResourceManager resources() {
+        return new MultiPackResourceManager(PackType.SERVER_DATA,
+                List.of(ServerPacksSource.createVanillaPackSource().fullResources()));
+    }
+
+    private static final class RejectedStructure extends Structure {
+        private final String key;
+        private final List<String> attempts;
+
+        private RejectedStructure(HolderSet<Biome> biomes, String key, List<String> attempts) {
+            super(new StructureSettings(biomes));
+            this.key = key;
+            this.attempts = attempts;
+        }
+
+        @Override
+        protected Optional<GenerationStub> findGenerationPoint(GenerationContext context) {
+            int x = context.chunkPos().getMinBlockX() >> 2;
+            int z = context.chunkPos().getMinBlockZ() >> 2;
+            attempts.add(key + "|" + context.climateSampler().sample(x, 20, z)
+                    + "|" + context.biomeResolver().getNoiseBiome(x, 20, z).unwrapKey().orElseThrow());
+            return Optional.empty();
+        }
+
+        @Override
+        public StructureType<?> type() {
+            return StructureType.SWAMP_HUT;
+        }
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/NativeRegionTerrainWriterTest.java

@@ -0,0 +1,183 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.SharedConstants;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.NbtIo;
+import net.minecraft.server.Bootstrap;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.EntityBlock;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.biome.Biomes;
+import net.minecraft.world.level.LevelHeightAccessor;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.UpgradeData;
+import net.minecraft.world.level.chunk.PalettedContainerFactory;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.ChestBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.storage.RegionFile;
+import net.minecraft.world.level.chunk.storage.RegionStorageInfo;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import java.io.DataInputStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Map;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public final class NativeRegionTerrainWriterTest {
+    @BeforeClass
+    public static void bootstrap() {
+        SharedConstants.tryDetectVersion();
+        Bootstrap.bootStrap();
+    }
+
+    @Test
+    public void nativeRoundTripPreservesNegativeCoordinatesAndPartialStatus() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        CompoundTag tag = codec.encode(new NativeRegionTerrainWriter.TerrainInput(-33, -1, -64, 32,
+                (x, y, z) -> y < 17 ? Blocks.STONE.defaultBlockState() : Blocks.AIR.defaultBlockState(),
+                (x, y, z) -> "minecraft:plains", List.of()));
+        assertEquals("minecraft:empty", tag.getStringOr("Status", ""));
+        assertEquals(SharedConstants.getCurrentVersion().dataVersion().version(), tag.getIntOr("DataVersion", -1));
+        assertFalse(tag.contains("Level"));
+        assertFalse(tag.getBooleanOr("isLightOn", false));
+        assertEquals("iris:terrain_checkpoint", tag.getStringOr("iris:checkpoint", ""));
+        assertEquals(Blocks.STONE.defaultBlockState(), codec.readBlock(tag, 0, -48, 0));
+        assertEquals(Blocks.AIR.defaultBlockState(), codec.readBlock(tag, 0, -47, 0));
+        Path directory = Files.createTempDirectory("iris-native-region-test-");
+        Path file = directory.resolve("r.-2.-1.mca");
+        try {
+            try (RegionFile region = new RegionFile(new RegionStorageInfo("checkpoint", Level.OVERWORLD, "chunk"), file, directory, false)) {
+                NativeRegionTerrainWriter.write(region, tag);
+            }
+            try (RegionFile region = new RegionFile(new RegionStorageInfo("checkpoint", Level.OVERWORLD, "chunk"), file, directory, false);
+                 DataInputStream input = region.getChunkDataInputStream(new ChunkPos(-33, -1))) {
+                assertTrue(input != null);
+                assertEquals(tag, NbtIo.read(input));
+            }
+        } finally {
+            Files.deleteIfExists(file);
+            Files.delete(directory);
+        }
+    }
+
+    @Test
+    public void preservesDistinctAirStatesInInitiallyEmptyContainers() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        assertEquals(Blocks.AIR.defaultBlockState(),
+                PalettedContainerFactory.create(codec.registries()).createForBlockStates().get(0, 0, 0));
+        CompoundTag tag = codec.encode(new NativeRegionTerrainWriter.TerrainInput(0, 0, 0, 16,
+                (x, y, z) -> x == 1 ? Blocks.CAVE_AIR.defaultBlockState()
+                        : x == 2 ? Blocks.VOID_AIR.defaultBlockState() : Blocks.AIR.defaultBlockState(),
+                (x, y, z) -> "minecraft:plains", List.of()));
+        assertEquals(Blocks.AIR.defaultBlockState(), codec.readBlock(tag, 0, 0, 0));
+        assertEquals(Blocks.CAVE_AIR.defaultBlockState(), codec.readBlock(tag, 1, 0, 0));
+        assertEquals(Blocks.VOID_AIR.defaultBlockState(), codec.readBlock(tag, 2, 0, 0));
+        assertTrue(tag.getListOrEmpty("block_entities").isEmpty());
+    }
+
+    @Test
+    public void serializesNativeBlockEntityDefaultsAndCustomPayload() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        CompoundTag payload = new CompoundTag();
+        payload.putString("LootTable", "minecraft:chests/simple_dungeon");
+        payload.putLong("LootTableSeed", 91L);
+        NativeRegionTerrainWriter.TileInput tile = new NativeRegionTerrainWriter.TileInput(3, 5, 7,
+                "minecraft:chest[facing=north,type=single,waterlogged=false]", payload);
+        CompoundTag tag = codec.encode(new NativeRegionTerrainWriter.TerrainInput(-2, 3, -64, 16,
+                (x, y, z) -> x == 3 && y == 5 && z == 7 || x == 1 && y == 2 && z == 4
+                        ? Blocks.CHEST.defaultBlockState() : Blocks.AIR.defaultBlockState(),
+                (x, y, z) -> "minecraft:plains", List.of(tile)));
+        List<CompoundTag> entities = tag.getListOrEmpty("block_entities").compoundStream().toList();
+        assertEquals(2, entities.size());
+        CompoundTag custom = entities.stream().filter(entity -> entity.getIntOr("x", 0) == -29)
+                .findFirst().orElseThrow();
+        assertEquals("minecraft:chest", custom.getStringOr("id", ""));
+        assertEquals(-59, custom.getIntOr("y", 0));
+        assertEquals(55, custom.getIntOr("z", 0));
+        assertEquals("minecraft:chests/simple_dungeon", custom.getStringOr("LootTable", ""));
+        assertEquals(91L, custom.getLongOr("LootTableSeed", 0));
+        assertEquals("minecraft:empty", tag.getStringOr("Status", ""));
+    }
+
+    @Test
+    public void fillsPlannedChunkWithoutDiscardingStatusOrBlockEntities() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        ProtoChunk chunk = new ProtoChunk(new ChunkPos(-2, 3), UpgradeData.EMPTY,
+                LevelHeightAccessor.create(-64, 32), PalettedContainerFactory.create(codec.registries()), null);
+        chunk.setPersistedStatus(ChunkStatus.BIOMES);
+        chunk.fillBiomesFromNoise((x, y, z) -> codec.registries().lookupOrThrow(Registries.BIOME)
+                .getOrThrow(Biomes.SWAMP));
+        BlockState chest = Blocks.CHEST.defaultBlockState().setValue(ChestBlock.FACING, Direction.EAST);
+        NativeRegionTerrainWriter.TerrainInput input = new NativeRegionTerrainWriter.TerrainInput(-2, 3, -64, 32,
+                (x, y, z) -> x == 3 && y == 5 && z == 7 ? chest : Blocks.STONE.defaultBlockState(),
+                (x, y, z) -> "minecraft:plains", List.of());
+        codec.fill(chunk, input);
+        assertEquals(ChunkStatus.BIOMES, chunk.getPersistedStatus());
+        assertEquals(Biomes.SWAMP,
+                chunk.getNoiseBiome(-8, -16, 12).unwrapKey().orElseThrow());
+        assertEquals(Blocks.STONE.defaultBlockState(), chunk.getBlockState(new BlockPos(-32, -33, 48)));
+        assertEquals(chest, chunk.getBlockState(new BlockPos(-29, -59, 55)));
+        assertEquals("minecraft:chest", chunk.getBlockEntityNbt(new BlockPos(-29, -59, 55))
+                .getStringOr("id", ""));
+        assertThrows(IllegalArgumentException.class, () -> codec.fill(chunk,
+                new NativeRegionTerrainWriter.TerrainInput(0, 0, -64, 32,
+                        input.blocks(), input.biomes(), List.of())));
+    }
+
+    @Test
+    public void serializesEveryNativeDefaultBlockEntityWithoutWorld() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        int tested = 0;
+        for (Block block : BuiltInRegistries.BLOCK) {
+            if (!block.defaultBlockState().hasBlockEntity()) {
+                continue;
+            }
+            String key = BuiltInRegistries.BLOCK.getKey(block).toString();
+            CompoundTag tag = codec.encode(new NativeRegionTerrainWriter.TerrainInput(0, 0, 0, 16,
+                    (x, y, z) -> x == 0 && y == 0 && z == 0 ? block.defaultBlockState() : Blocks.AIR.defaultBlockState(),
+                    (x, y, z) -> "minecraft:plains", List.of()));
+            int expected = ((EntityBlock) block).newBlockEntity(BlockPos.ZERO, block.defaultBlockState()) == null ? 0 : 1;
+            assertEquals(key, expected, tag.getListOrEmpty("block_entities").size());
+            tested++;
+        }
+        assertTrue(tested > 50);
+    }
+
+    @Test
+    public void rejectsMissingNativeStatesAndUnregisteredBiomes() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        assertThrows(NullPointerException.class, () -> codec.encode(new NativeRegionTerrainWriter.TerrainInput(
+                0, 0, 0, 16, (x, y, z) -> null, (x, y, z) -> "minecraft:plains", List.of())));
+        assertThrows(IllegalArgumentException.class, () -> codec.encode(new NativeRegionTerrainWriter.TerrainInput(
+                0, 0, 0, 16, (x, y, z) -> Blocks.STONE.defaultBlockState(), (x, y, z) -> "iris:custom_biome", List.of())));
+    }
+
+    @Test
+    public void validatesSectionBounds() throws Exception {
+        assertThrows(IllegalArgumentException.class, () -> new NativeRegionTerrainWriter.TerrainInput(
+                0, 0, -63, 16, (x, y, z) -> Blocks.AIR.defaultBlockState(), (x, y, z) -> "minecraft:plains", List.of()));
+    }
+
+    @Test
+    public void preservesDeclaredCustomBiomeKeys() throws Exception {
+        NativeRegionTerrainWriter codec = new NativeRegionTerrainWriter(HeadlessNativeTestRegistries.get());
+        CompoundTag tag = codec.encode(new NativeRegionTerrainWriter.TerrainInput(0, 0, 0, 16,
+                (x, y, z) -> Blocks.STONE.defaultBlockState(), (x, y, z) -> "iris:biomes/test", List.of()));
+        assertEquals("iris:biomes/test", tag.getListOrEmpty("sections").getCompoundOrEmpty(0)
+                .getCompoundOrEmpty("biomes").getListOrEmpty("palette").getStringOr(0, ""));
+    }
+}

adapters/bukkit/nms/v26_3_R1/src/test/java/art/arcane/iris/probe/OfflineFeatureWorld.java

@@ -0,0 +1,443 @@
+package art.arcane.iris.probe;
+
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.Holder;
+import net.minecraft.core.RegistryAccess;
+import net.minecraft.core.particles.ParticleOptions;
+import net.minecraft.server.MinecraftServer;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.sounds.SoundEvent;
+import net.minecraft.sounds.SoundSource;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.DifficultyInstance;
+import net.minecraft.world.attribute.EnvironmentAttributeReader;
+import net.minecraft.world.entity.Entity;
+import net.minecraft.world.entity.player.Player;
+import net.minecraft.world.flag.FeatureFlagSet;
+import net.minecraft.world.flag.FeatureFlags;
+import net.minecraft.world.level.BlockGetter;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.LightLayer;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeManager;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.EntityBlock;
+import net.minecraft.world.level.block.entity.BlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.border.WorldBorder;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkSource;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.dimension.DimensionType;
+import net.minecraft.world.level.entity.EntityTypeTest;
+import net.minecraft.world.level.gameevent.GameEvent;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.lighting.LevelLightEngine;
+import net.minecraft.world.level.material.Fluid;
+import net.minecraft.world.level.material.FluidState;
+import net.minecraft.world.level.storage.LevelData;
+import net.minecraft.world.phys.AABB;
+import net.minecraft.world.phys.Vec3;
+import net.minecraft.world.ticks.LevelTickAccess;
+import net.minecraft.world.ticks.ScheduledTick;
+import net.minecraft.world.ticks.TickContainerAccess;
+import org.bukkit.event.entity.CreatureSpawnEvent;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.function.Predicate;
+
+final class OfflineFeatureWorld implements WorldGenLevel {
+    private final Options options;
+    private final Map<Long, ProtoChunk> chunks = new HashMap<>();
+    private final RandomSource random;
+    private final BiomeManager biomeManager;
+    private final WorldBorder border = new WorldBorder();
+    private final LevelTickAccess<Block> blockTicks;
+    private final LevelTickAccess<Fluid> fluidTicks;
+    private long subTick;
+
+    OfflineFeatureWorld(Options options, List<ProtoChunk> chunks) {
+        this.options = options;
+        for (ProtoChunk chunk : chunks) {
+            if (chunk.getPersistedStatus() != ChunkStatus.TERRAIN) {
+                throw new IllegalArgumentException("Feature fixture requires TERRAIN chunks");
+            }
+            if (this.chunks.put(chunk.getPos().pack(), chunk) != null) {
+                throw new IllegalArgumentException("Duplicate chunk");
+            }
+        }
+        random = RandomSource.create(options.seed());
+        biomeManager = new BiomeManager(this, BiomeManager.obfuscateSeed(options.seed()));
+        blockTicks = ticks(ProtoChunk::getBlockTicks);
+        fluidTicks = ticks(ProtoChunk::getFluidTicks);
+    }
+
+    @Override
+    public long getGameTime() {
+        return 0L;
+    }
+
+    @Override
+    public ServerLevel getMinecraftWorld() {
+        throw unsupported("ServerLevel");
+    }
+
+    @Override
+    public long getSeed() {
+        return options.seed();
+    }
+
+    @Override
+    public boolean ensureCanWrite(BlockPos position) {
+        return !isOutsideBuildHeight(position) && hasChunk(position.getX() >> 4, position.getZ() >> 4);
+    }
+
+    @Override
+    public ServerLevel getLevel() {
+        throw unsupported("ServerLevel");
+    }
+
+    @Override
+    public DifficultyInstance getCurrentDifficultyAt(BlockPos position) {
+        throw unsupported("getCurrentDifficultyAt");
+    }
+
+    @Override
+    public long nextSubTickCount() {
+        return subTick++;
+    }
+
+    @Override
+    public LevelTickAccess<Block> getBlockTicks() {
+        return blockTicks;
+    }
+
+    @Override
+    public LevelTickAccess<Fluid> getFluidTicks() {
+        return fluidTicks;
+    }
+
+    @Override
+    public LevelData getLevelData() {
+        throw unsupported("getLevelData");
+    }
+
+    @Override
+    public MinecraftServer getServer() {
+        throw unsupported("getServer");
+    }
+
+    @Override
+    public ChunkSource getChunkSource() {
+        throw unsupported("getChunkSource");
+    }
+
+    @Override
+    public RandomSource getRandom() {
+        return random;
+    }
+
+    @Override
+    public void updateNeighborsAt(BlockPos position, Block block) {
+        throw unsupported("updateNeighborsAt");
+    }
+
+    @Override
+    public void neighborShapeChanged(Direction direction, BlockPos position, BlockPos neighbourPosition, BlockState neighbourState, int updateFlags, int updateLimit) {
+        throw unsupported("neighborShapeChanged");
+    }
+
+    @Override
+    public void playSound(Entity source, BlockPos position, SoundEvent sound, SoundSource soundSource, float volume, float pitch) {
+        throw unsupported("playSound");
+    }
+
+    @Override
+    public void addParticle(ParticleOptions particle, double x, double y, double z, double velocityX, double velocityY, double velocityZ) {
+        throw unsupported("addParticle");
+    }
+
+    @Override
+    public void levelEvent(Entity source, int eventId, BlockPos position, int data) {
+        throw unsupported("levelEvent");
+    }
+
+    @Override
+    public void gameEvent(Holder<GameEvent> event, Vec3 position, GameEvent.Context context) {
+        throw unsupported("gameEvent");
+    }
+
+    @Override
+    public ChunkAccess getChunk(int chunkX, int chunkZ) {
+        return chunk(chunkX, chunkZ);
+    }
+
+    @Override
+    public ChunkAccess getChunk(int chunkX, int chunkZ, ChunkStatus status, boolean create) {
+        ProtoChunk chunk = chunks.get(ChunkPos.pack(chunkX, chunkZ));
+        if (chunk == null && !create) {
+            return null;
+        }
+        chunk = chunk(chunkX, chunkZ);
+        if (!chunk.getPersistedStatus().isOrAfter(status)) {
+            throw unsupported("chunk status " + status);
+        }
+        return chunk;
+    }
+
+    @Override
+    public ChunkAccess getChunkIfLoadedImmediately(int chunkX, int chunkZ) {
+        return chunks.get(ChunkPos.pack(chunkX, chunkZ));
+    }
+
+    @Override
+    public boolean hasChunk(int chunkX, int chunkZ) {
+        return chunks.containsKey(ChunkPos.pack(chunkX, chunkZ));
+    }
+
+    @Override
+    public int getHeight(Heightmap.Types type, int x, int z) {
+        return chunk(x >> 4, z >> 4).getHeight(type, x & 15, z & 15) + 1;
+    }
+
+    @Override
+    public int getSkyDarken() {
+        throw unsupported("getSkyDarken");
+    }
+
+    @Override
+    public BiomeManager getBiomeManager() {
+        return biomeManager;
+    }
+
+    @Override
+    public Holder<Biome> getNoiseBiome(int quartX, int quartY, int quartZ) {
+        return getUncachedNoiseBiome(quartX, quartY, quartZ);
+    }
+
+    @Override
+    public Holder<Biome> getUncachedNoiseBiome(int quartX, int quartY, int quartZ) {
+        return chunk(quartX >> 2, quartZ >> 2).getNoiseBiome(quartX, quartY, quartZ);
+    }
+
+    @Override
+    public boolean isClientSide() {
+        return false;
+    }
+
+    @Override
+    public int getSeaLevel() {
+        return options.seaLevel();
+    }
+
+    @Override
+    public DimensionType dimensionType() {
+        return options.dimension();
+    }
+
+    @Override
+    public int getMinY() {
+        return options.dimension().minY();
+    }
+
+    @Override
+    public int getHeight() {
+        return options.dimension().height();
+    }
+
+    @Override
+    public RegistryAccess registryAccess() {
+        return options.registries();
+    }
+
+    @Override
+    public FeatureFlagSet enabledFeatures() {
+        return FeatureFlags.DEFAULT_FLAGS;
+    }
+
+    @Override
+    public EnvironmentAttributeReader environmentAttributes() {
+        throw unsupported("environmentAttributes");
+    }
+
+    @Override
+    public LevelLightEngine getLightEngine() {
+        throw unsupported("getLightEngine");
+    }
+
+    @Override
+    public int getBrightness(LightLayer layer, BlockPos position) {
+        throw unsupported("getBrightness");
+    }
+
+    @Override
+    public int getRawBrightness(BlockPos position, int ambientDarkening) {
+        throw unsupported("getRawBrightness");
+    }
+
+    @Override
+    public boolean canSeeSky(BlockPos position) {
+        throw unsupported("canSeeSky");
+    }
+
+    @Override
+    public WorldBorder getWorldBorder() {
+        return border;
+    }
+
+    @Override
+    public BlockGetter getChunkForCollisions(int chunkX, int chunkZ) {
+        return chunk(chunkX, chunkZ);
+    }
+
+    @Override
+    public BlockEntity getBlockEntity(BlockPos position) {
+        return chunk(position).getBlockEntity(position);
+    }
+
+    @Override
+    public BlockState getBlockState(BlockPos position) {
+        return chunk(position).getBlockState(position);
+    }
+
+    @Override
+    public BlockState getBlockStateIfLoaded(BlockPos position) {
+        return hasChunk(position.getX() >> 4, position.getZ() >> 4) ? getBlockState(position) : null;
+    }
+
+    @Override
+    public FluidState getFluidState(BlockPos position) {
+        return getBlockState(position).getFluidState();
+    }
+
+    @Override
+    public FluidState getFluidIfLoaded(BlockPos position) {
+        BlockState state = getBlockStateIfLoaded(position);
+        return state == null ? null : state.getFluidState();
+    }
+
+    @Override
+    public List<Entity> getEntities(Entity source, AABB area, Predicate<? super Entity> predicate) {
+        throw unsupported("getEntities");
+    }
+
+    @Override
+    public <T extends Entity> List<T> getEntities(EntityTypeTest<Entity, T> type, AABB area, Predicate<? super T> predicate) {
+        throw unsupported("getEntities");
+    }
+
+    @Override
+    public List<? extends Player> players() {
+        return List.of();
+    }
+
+    @Override
+    public boolean isStateAtPosition(BlockPos position, Predicate<BlockState> predicate) {
+        return predicate.test(getBlockState(position));
+    }
+
+    @Override
+    public boolean isFluidAtPosition(BlockPos position, Predicate<FluidState> predicate) {
+        return predicate.test(getFluidState(position));
+    }
+
+    @Override
+    public BlockPos getHeightmapPos(Heightmap.Types type, BlockPos position) {
+        return position.atY(getHeight(type, position.getX(), position.getZ()));
+    }
+
+    @Override
+    public boolean setBlock(BlockPos position, BlockState state, int updateFlags, int updateLimit) {
+        if (!ensureCanWrite(position)) {
+            throw new IllegalStateException("Feature write outside prepared bounds: " + position);
+        }
+        ProtoChunk chunk = chunk(position);
+        BlockState previous = chunk.setBlockState(position, state, updateFlags);
+        if (previous == state) {
+            return false;
+        }
+        chunk.removeBlockEntity(position);
+        if (state.getBlock() instanceof EntityBlock block) {
+            BlockEntity entity = block.newBlockEntity(position, state);
+            if (entity != null) {
+                chunk.setBlockEntity(entity);
+            }
+        }
+        BlockPos postProcess = state.getPostProcessPos(this, position);
+        if (postProcess != null) {
+            chunk(postProcess).markPosForPostProcessing(postProcess);
+        }
+        return true;
+    }
+
+    @Override
+    public boolean removeBlock(BlockPos position, boolean move) {
+        return setBlock(position, Blocks.AIR.defaultBlockState(), 2, 0);
+    }
+
+    @Override
+    public boolean destroyBlock(BlockPos position, boolean drop, Entity source, int updateLimit) {
+        throw unsupported("destroyBlock");
+    }
+
+    @Override
+    public boolean addFreshEntity(Entity entity) {
+        throw unsupported("addFreshEntity");
+    }
+
+    @Override
+    public boolean addFreshEntity(Entity entity, CreatureSpawnEvent.SpawnReason reason) {
+        throw unsupported("addFreshEntity");
+    }
+
+    private ProtoChunk chunk(BlockPos position) {
+        return chunk(position.getX() >> 4, position.getZ() >> 4);
+    }
+
+    private ProtoChunk chunk(int x, int z) {
+        ProtoChunk chunk = chunks.get(ChunkPos.pack(x, z));
+        if (chunk == null) {
+            throw new IllegalStateException("Feature escaped prepared chunk region: " + x + "," + z);
+        }
+        return chunk;
+    }
+
+    private <T> LevelTickAccess<T> ticks(Function<ProtoChunk, TickContainerAccess<T>> containers) {
+        return new LevelTickAccess<>() {
+            @Override
+            public void schedule(ScheduledTick<T> tick) {
+                containers.apply(chunk(tick.pos())).schedule(tick);
+            }
+            @Override
+            public boolean hasScheduledTick(BlockPos position, T type) {
+                return containers.apply(chunk(position)).hasScheduledTick(position, type);
+            }
+            @Override
+            public int count() {
+                int count = 0;
+                for (ProtoChunk chunk : chunks.values()) {
+                    count += containers.apply(chunk).count();
+                }
+                return count;
+            }
+            @Override
+            public boolean willTickThisTick(BlockPos position, T type) {
+                throw unsupported("live tick execution");
+            }
+        };
+    }
+
+    private static UnsupportedOperationException unsupported(String capability) {
+        return new UnsupportedOperationException("Offline feature fixture has no " + capability);
+    }
+
+    record Options(RegistryAccess registries, DimensionType dimension, long seed, int seaLevel) {
+    }
+}