Record alpha.13.1 release and existing Prism update

Default new Sanctuary worlds to the 20-player profile and keep legacy world generation isolated. Validate all three capacities progressively with real generation, fluid ticks and saved settings.

CHANGELOG.md

@@ -1,5 +1,262 @@
 # Changelog
 
+## 0.1.0-alpha.13.1 — 2026-09-09
+
+- Corrige l’arrêt des expansions sous Windows : le journal ne tente plus
+  d’ouvrir son dossier comme un fichier pour le synchroniser. Cette opération
+  reste exigée sur les systèmes de fichiers utilisant le séparateur Unix.
+- Écriture du fichier synchronisée, remplacement atomique et relecture stricte
+  conservés. Les véritables erreurs de stockage arrêtent toujours les expansions.
+- Après mise à jour et réouverture du même monde, une réservation valide déjà
+  enregistrée avant l’erreur est reprise automatiquement. Aucun changement de
+  schéma du journal, de génération, de paramètres ou de chunks existants.
+
+Le smoke du journal passe sur macOS, avec politique Windows simulée, erreurs
+après remplacement et récupération au rechargement. Aucun essai Windows natif
+n’a encore été réalisé. Voir le [dépannage](docs/alpha13-worldgen.md#correctif-alpha131--expansions-sous-windows)
+et les [contrôles ciblés](docs/testing.md#correctif-alpha131--journal-dexpansion-sous-windows).
+
+## 0.1.0-alpha.13 — 2026-09-09
+
+- Un seul choix public **Sanctuary**, avec le bouton natif **Personnaliser** :
+  Petit (512 blocs), Moyen (724, par défaut), Grand (1 024). Le diamètre est
+  enregistré dans le générateur ; confirmer ou annuler agit sur le monde à créer.
+- Île initiale issue de la densité et de l’hydrologie complète de Population,
+  avec sa forêt de surface et les poches de biomes souterrains natives du
+  laboratoire. Les eaux et les ressources restent dépendantes du terrain.
+- Reprise des outils d’expansion alpha.12.1 dans ce même monde : parent,
+  direction, climat, taille, relief, distance facultative et recherche de sites
+  libres, sans remplacer les chunks existants. Le déblocage collectif reste futur.
+- Nouveau codec `sanctuary:island_v13`, racine de génération 13 et journal
+  `data/sanctuary-world-v13/expansions.json`. Les extensions restent de génération
+  12. Anciens codecs et presets conservés mais cachés de la création ; aucun
+  monde existant converti, agrandi ou régénéré.
+- La suite GameTest unifiée devient le défaut de `check` et `runGameTest` ; les
+  essais historiques demandent `-PsanctuaryUnifiedTests=false`.
+
+`check build assemblePack`, interface client, trois tailles et rechargement des
+expansions vérifiés. Moyen : 63,66 s pour créer puis charger 289 chunks FULL
+autour du spawn sur la graine 0, 7,82 s pour les 80 suivants ; mesure serveur,
+sans garantie de FPS ni charge multijoueur. Release, MRpack et canal packwiz
+publiés ; même instance Prism synchronisée deux fois, avec 601 fichiers
+personnels et réglages suivis conservés.
+Voir le [guide alpha.13](docs/alpha13-worldgen.md) et les [preuves](docs/testing.md).
+
+## 0.1.0-alpha.12.1 — 2026-09-09 (historique)
+
+- Corrige le blocage de toutes les directions lorsque du vide a déjà été
+  généré : la recherche continue plus loin sur le même rayon, sans remplacer
+  les chunks existants.
+- Paramètre final `distance` facultatif pour `quick`, `create`, `preview` :
+  distance minimale entre centres en blocs, de 0 à 100 000 ; 0 ou omis = auto.
+- Recherche limitée à 32 positions et un budget global de lecture de 30 secondes.
+  Les erreurs disque et timeouts interrompent la demande ; seul un emplacement
+  occupé permet de poursuivre. La graine et le profil sont conservés.
+- Compatibilité des commandes précédentes et des mondes laboratoire alpha.12 :
+  journal v1 et génération 12 inchangés, sans migration ni régénération.
+
+Les contrôles moteur de création et de rechargement passent sur la graine 42,
+avec huit premiers sites occupés et distance explicite. `check build assemblePack`
+passe, avec les douze tests historiques. Release, MRpack et canal publiés ;
+la même instance Prism est synchronisée deux fois et ses 466 fichiers personnels
+et réglages suivis sont conservés. Voir [WG-14](docs/backlog.md).
+
+## 0.1.0-alpha.12 — 2026-09-09 (historique)
+
+- Nouveau preset Sanctuary — Laboratoire, distinct de Petit/Grand. Outils
+  opérateur `quick`, `create`, `preview`, `list`, `visit`, `resume` pour tester
+  les expansions sans blocs de commande ni économie préalable.
+- Îles de 64, 128, 256 ou 512 blocs de diamètre nominal ; parent et direction
+  enregistrés, climat libre parmi douze profils. La boussole climatique reste
+  un raccourci facultatif ; les branches peuvent composer plusieurs couronnes.
+- Nouveaux reliefs hauts : naturel, pics, canyon, volcan. Le relief naturel est
+  aussi testé sur l’île initiale du laboratoire. Palette volcanique et petites
+  poches facultatives de fluides, sans ajout de fondations artificielles.
+- 34 biomes vanilla déclarés dès le chargement, avec surface et poches souterraines.
+  Sélection de structures vanilla selon biomes, emprise et fondations : villages,
+  temples de désert/jungle, cabanes de marais et camps abandonnés.
+- Journal serveur v1 atomique, paramètres immuables, reprise des réservations,
+  refus des chunks existants ou en cours de chargement/déchargement, vide compris.
+  Aucun changement des anciens générateurs ni migration d’une sauvegarde.
+
+Validation locale : `check build assemblePack`, douze tests moteur Grand de
+graine 0, smokes de journal/relief, expansions et second processus de rechargement
+sur la graine 42 avec camp et butin natifs. Les essais restent sans client ni
+joueurs connectés. Release, MRpack et canal packwiz publiés ; la même instance
+Prism est synchronisée deux fois avec 466 fichiers personnels et réglages
+suivis conservés. Recherche collective,
+boîtes postales, Void, hydrologie étendue et autres structures restent à construire.
+Voir [le contrat du laboratoire](docs/alpha12-laboratory.md).
+
+## 0.1.0-alpha.11 — 2026-09-09
+
+- Deux choix à la création : **Petit** (512 blocs de diamètre nominal)
+  et **Grand** (environ 724 blocs), Grand par défaut. Leur aire nominale varie
+  d’un facteur deux, sur une hauteur de 384 blocs. Les repères internes 5/10
+  ne désignent pas un nombre garanti de joueurs.
+- Nouveau réglage `sanctuary:population_10` pour Grand. Les anciens formats
+  20/100 disparaissent des choix publics, mais restent chargeables avec leurs
+  identifiants et leur relief enregistrés. Aucune île existante n’est réduite.
+- Cache des coins d’interpolation conservant l’arithmétique exacte du moteur,
+  borné à 192 Kio par thread. Les plans régionaux déjà calculés restent lisibles
+  pendant le calcul d’une nouvelle région ; le sampler est compilé une seule
+  fois par plan.
+- À géométrie 20 identique, création et 289 chunks : 407,43 → 62,54 s
+  (−84,65 %). Exploration de 80 chunks : 103,14 → 14,05 s. Le nouveau Grand
+  atteint 62,67 s sur le protocole de départ. Une seule mesure par version,
+  graine 0, M1/8 Gio : ce sont des temps serveur jusqu’à FULL, pas des FPS
+  ni une garantie de délai en jeu.
+
+Validation : `check build assemblePack`, douze tests moteur pour Petit et
+Grand, 1 800 ticks de fluides, persistance des quatre références et
+3 183 804 comparaisons bit à bit de densités réelles, plus 122 528 synthétiques.
+Les sources historiques de forme et les anciens réglages sont conservés.
+Voir [Validation](docs/testing.md) et [Distribution](docs/packwiz.md).
+Le canal stable est publié et la même instance Prism est synchronisée deux fois,
+avec les 364 fichiers personnels et réglages suivis conservés.
+
+## 0.1.0-alpha.10 — 2026-09-09
+
+- Trois tailles de départ : **Sanctuary (20 joueurs)** par défaut, plus les
+  variantes 5 et 100 joueurs. Diamètres nominaux de 512, 1 024 et environ
+  2 290 blocs, hauteur de 384 blocs ; aucune limite de connexions modifiée.
+- Nouvelles générations `sanctuary:population_5`, `population_20` et
+  `population_100`. Forêts, cavités, décorations et plans d’eau/lave couvrent
+  la nouvelle emprise par régions locales ; une structure hydraulique qui
+  dépasse son domaine est écartée en entier.
+- Capacité persistante sur disque, ancien réglage alpha.9 conservé ;
+  212 anciens fichiers de production inchangés et huit fichiers de liaison
+  ou d’interface adaptés. Aucune ancienne île agrandie ou régénérée.
+
+Validation : `check build assemblePack` réussi, puis onze tests moteur
+réussis pour chacun des profils 5/20/100 sur la graine `0`, avec 1 800 ticks
+réels. Le MRpack et le ZIP d’amorçage sont vérifiés localement. Les mesures
+sont limitées aux chunks inspectés ; elles ne constituent ni un inventaire
+global ni une simulation de cent joueurs. Le premier plan local reste coûteux
+et la génération en masse reste à optimiser. Publication et synchronisations
+du canal sont consignées séparément dans [Distribution](docs/packwiz.md).
+
+## 0.1.0-alpha.9 — 2026-09-09
+
+- Cavités luxuriantes éclairées par leur végétation, secteurs à spéléothèmes
+  et géodes d’améthyste recherchés sous l’île, sur des supports naturels.
+- Province de soufre limitée dans les profondeurs ; geysers utilisant
+  les blocs et conditions de fonctionnement de Minecraft 26.3-pre-2.
+- Forêts et rivière de surface conservées ; recherche de lacs plus profonds
+  et volumineux et de groupes facultatifs de bassins en terrasses reliés par
+  des cascades. Les « rizières » désignent le relief aquatique, sans culture
+  de riz ni mécanique d’ascenseur ajoutée au joueur.
+- Nouvelle clé `sanctuary:sanctuary_cavern`, réservée aux nouveaux mondes.
+  Les générations jusqu’à l’alpha.8 restent séparées ; aucune sauvegarde
+  existante n’est convertie ou régénérée.
+
+Validation : au moins dix tests requis réussis sur chacune des graines `0`,
+`42` et `8675309`, avec 1 800 ticks de fluides ; `check build assemblePack`
+réussi. Les preuves cumulées comprennent deux bassins en terrasses reliés,
+un geyser dormant puis éruptif, des baies lumineuses, des spéléothèmes et de
+l’améthyste bourgeonnante. Les mesures et leurs périmètres figurent dans
+[Validation](docs/testing.md). Release et canal packwiz publiés ; double
+synchronisation isolée puis dans la même instance Prism réussie, avec 260
+fichiers personnels et réglages conservés. Aucun site ni stock n’est garanti
+sur chaque graine.
+
+## 0.1.0-alpha.8 — 2026-09-09
+
+- Forêts de surface conservées, avec de nouvelles failles courbes qui retirent
+  de la roche pour ouvrir l’intérieur de l’île.
+- Nappes de tuf, cobblestone, pierre moussue et boue compactée dans les étages
+  humides ; ardoise des abîmes, roche noire et basalte plus bas. Les poches de
+  soufre et de cinabre peuvent apparaître à des altitudes plus accessibles.
+- Davantage d’essais de petits filons de charbon, fer et cuivre, y compris
+  au contact de l’air. Ajout de l’émeraude et adaptation des huit familles de
+  minerais aux nouvelles roches, sans quota de remplissage.
+- Décoration des corniches revue avec de gros champignons, des petits
+  champignons plus dispersés et des sols de mousse, podzol et mycélium.
+- Bassins plus grands et recherche d’une
+  longue rivière calme au tracé arrondi, de largeur variable, soutenue par la
+  roche, avec bassins terminaux, berges progressives et source en paroi.
+- Recherche prioritaire de la poche de lave couverte entre Y=64 et Y=160,
+  avec recherche plus haute si aucun site profond ne convient. Les sources
+  profondes supplémentaires produisent leurs coulées par les ticks vanilla.
+- Nouvelle clé `sanctuary:sanctuary_rift` ; les anciennes générations jusqu’à
+  l’alpha.7 restent séparées. Cet incrément nécessite un **nouveau monde Sanctuary**.
+
+Validation : tests serveur réussis sur chacune des graines `0`, `42` et
+`8675309`, avec les bassins terminaux, la continuité des champignons et
+1 800 ticks réels de fluides. `check build assemblePack` réussi sur la graine
+`42`. Les mesures et leurs limites figurent dans [Validation](docs/testing.md).
+Publication immuable et canal packwiz vérifiés, avec deux synchronisations
+dans un dossier neuf puis deux dans la même instance Prism ; sauvegardes et
+réglages conservés.
+Aucune rivière, coulée ou réserve de ressources n’est garantie pour chaque graine.
+
+## 0.1.0-alpha.7 — 2026-09-08
+
+- Forêts de chênes plus denses, y compris au cœur et sur les hauteurs de l’île,
+  avec bouleaux, clairières fleuries et bois plus secs.
+- Vrais chênes noirs, champignons, podzol et mycélium sur les corniches intérieures
+  humides ; mousse plus ponctuelle et rares poches de jungle/bambou.
+- Un emplacement facultatif pour un arbre remarquable (cerisier favorisé,
+  épicéa, jungle, acacia, palétuvier ou chêne pâle), sans terrain ajouté.
+- Nappes de pierre, andésite, diorite et granite sur les affleurements ; dépôts
+  épais de sable, gravier et argile associés aux bassins. Rares matières de
+  soufre dans les profondeurs, sans grands bassins souterrains.
+- Petits filons de charbon, fer et cuivre autorisés à affleurer, avec des essais
+  sur les roches de surface et les corniches pour les rendre repérables.
+- Nouvelle clé `sanctuary:sanctuary_woodland`, avec formes, hauteur, ciel et
+  plans d’eau conservés. Créer un **nouveau monde Sanctuary** ; les sauvegardes
+  alpha.6 et antérieures conservent leur génération.
+
+Validation : dix tests serveur réussis sur chacune des graines `0`, `42` et
+`8675309`, arbres et minerais réellement observés, 1 800 ticks de fluides,
+et `check build assemblePack` réussi.
+
+## 0.1.0-alpha.6 — 2026-09-08
+
+- Palette tempérée plus douce, avec des couleurs communes pour l’herbe, le
+  feuillage et l’eau. Dappled Forest quitte l’île initiale et reste réservé
+  aux futurs continents ; les sauvegardes alpha.5 le conservent.
+- Prairies fleuries et affleurements rocheux plus étendus, avec une répartition
+  des biomes selon l’altitude. Les corniches inférieures peuvent porter de la
+  mousse, des fougères, des fleurs et des petits arbustes.
+- Sources recherchées aussi dans les parois des strates inférieures. Les
+  cascades peuvent rejoindre un palier ou descendre dans le vide.
+- Retrait des courts ruisseaux à niveau constant : l’île conserve ses étangs
+  et petits lacs. La grande rivière avec source, chute et bassin reste à
+  développer ; elle n’est pas activée dans cette livraison.
+- Nouvelle clé `sanctuary:sanctuary_layered`, avec les anciennes générations
+  conservées. Créer un **nouveau monde Sanctuary** pour cet incrément.
+
+Validation : dix tests serveur réussis sur chacune des graines `0`, `42` et
+`8675309`, avec 1 800 ticks de fluides, contrôles des corniches et respect des
+modifications ultérieures aux sources. `check build assemblePack` réussi.
+
+## 0.1.0-alpha.5 — 2026-09-08
+
+- Plages plus larges et irrégulières, en nappes de sable, gravier et roche, avec
+  des transitions herbeuses. Dépôts de 3 à 5 blocs au lieu d’une seule couche.
+- Étangs et lacs moins creusés, rives variées et petites terrasses ; la canne
+  à sucre reste soumise à ses conditions vanilla.
+- Quelques sources sortent de niches rocheuses naturelles à différentes
+  altitudes. Leurs cascades peuvent descendre dans le vide et servir à circuler
+  verticalement ; seuls les blocs sources sont posés par la génération.
+- Petite réserve de lave dans une niche rocheuse accessible lorsque le relief
+  fournit un fond, des parois et une voûte adaptés.
+- Mosaïque de cinq biomes tempérés, dont Dappled Forest de Minecraft 26.3.
+- Petits filons de charbon, fer, cuivre, or, redstone, lapis et diamant à des
+  altitudes adaptées à l’île. Aucun quota ajouté après comptage des ressources.
+- Nouvelle clé de génération `sanctuary:sanctuary_natural` ; anciennes versions
+  de terrain et d’hydrologie conservées pour les sauvegardes existantes.
+
+Créer un **nouveau monde Sanctuary** pour tester cette génération. La hauteur
+et le ciel validés en alpha.3/4 sont conservés. L’accès à l’End, les expansions
+et les grandes rivières en pente restent à développer.
+
+Validation : dix tests serveur réussis sur chacune des graines 0, 42 et 8675309,
+avec 1 800 ticks réels de fluides. Les bassins et les réserves de lave restent
+stables ; les neuf cascades atteignent Y=0. `check build assemblePack` et les
+contrôles des couches de sédiments, des anciens générateurs et du pack réussissent.
+
 ## 0.1.0-alpha.4 — 2026-09-08
 
 - Première hydrologie de surface : étangs, petits lacs et cours d’eau calmes

README.md

@@ -14,30 +14,170 @@ infrastructures qui permettront progressivement d'ouvrir de nouveaux continents.
 
 Ce dépôt démarre la nouvelle base Fabric. La [vision complète](docs/vision.md)
 conserve les intentions ; le [backlog](docs/backlog.md) prépare les premiers
-tickets. Les systèmes d'expansion, d'économie, de progression et les dimensions
-décrits dans la vision ne sont pas encore implémentés.
+tickets. Les systèmes d’économie, de progression collective et les dimensions
+décrits dans la vision ne sont pas encore implémentés. L’alpha.13 réunit l’île
+initiale et les outils d’expansion dans un seul choix de monde Sanctuary.
+Les trois tailles et l’interface native sont vérifiées. Le correctif alpha.13.1
+est publié et la même instance Prism Mac est synchronisée ; les versions
+précédentes restent historiques.
 
-## Premier incrément
+## Alpha.13.1 — correctif des expansions sous Windows
+
+Le journal d’expansion n’essaie plus d’ouvrir son dossier comme un fichier sous
+Windows, ce qui provoquait `AccessDeniedException` et bloquait les expansions.
+La synchronisation du fichier, son remplacement atomique et sa relecture restent
+obligatoires. Le format du journal et la génération alpha.13 restent identiques.
+
+Après installation du correctif, **rouvrir le même monde** : une réservation déjà
+enregistrée est reprise après vérification du journal. Il ne faut pas supprimer
+`sanctuary-world-v13` ni recréer le monde pour ce correctif. Voir le
+[dépannage Windows](docs/alpha13-worldgen.md) et la [validation](docs/testing.md).
+
+La [release alpha.13.1](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.13.1)
+et le canal packwiz sont publiés. Deux synchronisations isolées et deux
+synchronisations de l’instance Mac existante passent ; les 713 fichiers personnels
+et réglages suivis restent identiques. Aucun accès à l’instance Windows n’a eu lieu.
+
+## Alpha.13 — un seul monde Sanctuary
+
+À la création d’un **nouveau monde**, sélectionner **Sanctuary**, puis utiliser
+le bouton natif **Personnaliser** pour choisir la taille de l’île :
+
+| Taille | Diamètre nominal |
+| --- | --- |
+| Petit | 512 blocs |
+| Moyen, par défaut | 724 blocs |
+| Grand | 1 024 blocs |
+
+**Terminé** conserve le choix ; **Annuler** revient sans l’appliquer. La hauteur
+reste de 384 blocs. Ces tailles décrivent une emprise, sans promettre un nombre
+de joueurs, une aire constructible ou un stock de minerais.
+
+L’île reprend les forêts, le relief flottant et les plans d’eau complets du
+générateur précédent : bassins, rivière, terrasses et cascades restent liés
+aux possibilités naturelles du terrain. Les poches de cavités natives de Minecraft
+du laboratoire rejoignent cette île. Les commandes opérateur
+d’expansion, avec leur distance facultative et leur recherche d’emplacements
+libres, sont accessibles dans ce même nouveau monde. Les déblocages par la
+production et l’XP restent à construire.
+
+Les anciens choix Petit/Grand et Laboratoire sont cachés à la création, tout
+en restant chargeables avec leurs paramètres enregistrés. **Aucun monde
+existant n’est converti ni régénéré.** Le [guide alpha.13](docs/alpha13-worldgen.md)
+détaille la création, les expansions et la séparation des sauvegardes.
+
+`check build assemblePack`, les tests client, les trois tailles et les scénarios
+d’expansion/rechargement passent. Moyen atteint 63,66 secondes pour la création
+puis 289 chunks FULL dans le test serveur de référence. Les preuves et leurs
+limites sont dans [Validation](docs/testing.md).
+
+À la livraison alpha.13, le canal packwiz, le MRpack et la même instance Prism
+avaient été mis à jour, avec les 601 fichiers personnels et réglages alors suivis conservés.
+Voir [Distribution](docs/packwiz.md).
+
+## Socle livré jusqu’à l’alpha.8
 
 - Mod `sanctuary` indépendant et pack Sanctuary construit avec packwiz.
 - Preset **Sanctuary** sélectionnable à la création d'un monde, avec une île
   flottante finie, un terrain naturel et un extérieur vide.
-- Forêt de départ avec végétation, minerais et animaux vanilla. Les formes de
-  terrain reprennent l'approche du générateur 26.2, adaptée à l'API 26.3.
+- Île tempérée aux teintes douces : forêts de chênes et de bouleaux, clairières
+  fleuries et affleurements de pierre, andésite, diorite et granite. Des failles
+  courbes ouvrent le terrain flottant issu du générateur 26.2. Les corniches
+  humides accueillent chênes noirs et champignons ; les essences rares restent
+  ponctuelles.
+- Géologie enrichie en profondeur : tuf, pierres moussues et boue compactée
+  dans les intérieurs humides, puis ardoise des abîmes, roche noire, basalte et
+  poches de soufre. Les volumes existants fournissent leur support.
+- Petits filons de charbon, fer, cuivre, or, redstone, lapis, diamant et émeraude
+  à des altitudes adaptées au terrain. Les essais de charbon, fer et cuivre
+  exposés sont plus fréquents. Les stocks se constatent après génération.
 - Spawn recherché sur le sol de l'île lors de la création. Les mondes ordinaires
   et les choix ultérieurs de spawn ne sont pas remplacés.
 - Nouveaux mondes sur 384 blocs (`Y=0..383`), île relevée de 64 blocs,
   dessous sculpté et nuages au-dessus du terrain. Les anciennes sauvegardes
   conservent leurs paramètres de génération.
-- Première hydrologie de surface : étangs, petits lacs et cours d’eau calmes,
-  avec des berges de sable et de la canne à sucre lorsque le terrain s’y prête.
+- Étangs, petits lacs, plages plus larges et dépôts de
+  trois à cinq blocs de sable, gravier, pierre ou terre enherbée. La canne à
+  sucre apparaît lorsque les rives respectent ses règles vanilla.
+- Recherche de bassins plus grands et d’une longue rivière calme au tracé
+  arrondi, avec largeur variable et berges progressives. La liaison de deux
+  bassins, sa source et sa cascade entrante sont contrôlées dans les mondes
+  de test de l’alpha.8.
+- Quelques sources dans des niches rocheuses naturelles, y compris aux étages
+  inférieurs : Minecraft fait couler leur eau en cascades, qui peuvent descendre jusque dans le vide.
+- Une petite poche de lave couverte est recherchée en priorité sur une corniche
+  profonde, puis plus haut si nécessaire. Une à deux sources profondes
+  supplémentaires peuvent former des coulées, vérifiées par les ticks du moteur.
 
-L'île a une emprise nominale de 512 blocs de diamètre, avec une bordure sculptée
+Jusqu’à l’alpha.9, l’île a une emprise nominale de 512 blocs de diamètre, avec une bordure sculptée
 par des bruits liés à la seed. Aucune masse centrale n'est ajoutée pour forcer
 le terrain : le spawn cherche un emplacement naturel. Le catalogue
-TerraMix, les continents déverrouillables, les grandes rivières et cascades, les ruines et
+TerraMix, les continents déverrouillables, les océans, les ruines et
 les autres fonctionnalités restent à construire par tickets.
 
+La génération alpha.8, `sanctuary:sanctuary_rift`, passe les contrôles moteur
+sur les trois graines de référence, avec 1 800 ticks de fluides. Ces résultats
+ne valident pas par avance l’incrément suivant. Les observations et leurs
+limites figurent dans [Validation](docs/testing.md).
+
+## Alpha.9, historique : cavités vivantes et terrasses d’eau
+
+L’incrément ajoute des cavités luxuriantes et lumineuses sous l’île, des
+secteurs à spéléothèmes, des géodes d’améthyste et des poches de soufre moins
+envahissantes, avec de vrais geysers de soufre lorsque leurs conditions sont
+réunies. Les forêts de surface sont conservées ; la recherche de lacs plus
+profonds et volumineux accompagne des groupes facultatifs de bassins naturels
+étagés. Leurs cascades relient les paliers et permettent de circuler par la nage.
+L’image des « rizières » décrit ce paysage d’eau en terrasses : aucune culture
+de riz n’est ajoutée.
+
+**La validation moteur alpha.9 passe sur les trois graines de référence.**
+Les preuves de terrasses, geysers et décor souterrain sont cumulées sur ces
+trois mondes, sans imposer chaque élément à chacun. La version est publiée
+et la même instance Prism est synchronisée ; voir [Distribution](docs/packwiz.md). Le
+nouveau réglage `sanctuary:sanctuary_cavern` nécessite de créer un **nouveau
+monde Sanctuary**. Les anciennes générations jusqu’à l’alpha.8 gardent leurs
+paramètres ; aucune sauvegarde n’est régénérée. Les cavités restent dans
+l’Overworld, sans créer la dimension des cavernes prévue par la vision.
+Dappled Forest reste réservé aux futurs continents et présent dans les
+anciennes sauvegardes alpha.5. Aucun lac, groupe de terrasses, geyser ou stock
+de ressources n’est garanti sur chaque graine. Voir le ticket local
+[WG-10](docs/backlog.md).
+
+## Alpha.10, historique : îles pour 5, 20 ou 100 joueurs
+
+L’alpha.10 proposait trois tailles, avec **20 joueurs par défaut**.
+Leur aire nominale est proportionnelle à la capacité choisie, sur la base
+de l’île de 512 blocs pour cinq joueurs. La hauteur reste de 384 blocs.
+
+| Choix à la création | Identifiant du preset | Capacité | Diamètre nominal |
+| --- | --- | --- | --- |
+| Sanctuary 5 joueurs | `sanctuary:sanctuary_5` | 5 | 512 blocs |
+| Sanctuary, choix par défaut | `sanctuary:sanctuary` | 20 | 1 024 blocs |
+| Sanctuary 100 joueurs | `sanctuary:sanctuary_100` | 100 | Environ 2 290 blocs |
+
+Ces capacités dimensionnent l’île ; elles ne fixent pas la limite de
+connexions du serveur. Le contour réel dépend du relief et de la graine,
+et le stock de ressources reste celui de la génération. La taille se choisit
+pour un **nouveau monde** : aucune ancienne île n’est agrandie et aucune
+sauvegarde n’est régénérée lors de la mise à jour.
+Les paramètres sauvegardés sont distincts : `sanctuary:population_5`,
+`sanctuary:population_20` et `sanctuary:population_100`.
+
+**Les trois profils passent les onze tests moteur sur la graine `0`, avec
+1 800 ticks réels de fluides.** Le choix de capacité persiste après écriture
+et relecture sur disque. La vérification conserve 212 anciens fichiers de
+production strictement identiques ; huit fichiers d’intégration ou d’interface
+accueillent les nouveaux choix. La première planification locale reste coûteuse,
+environ 83–88 secondes pour les premiers essais 5/20 sur cette configuration.
+La génération en masse reste à optimiser. Ces essais ne simulent pas
+100 connexions et ne donnent aucune garantie de performances multijoueurs.
+Les diamètres nominaux ne permettent pas d’extrapoler les stocks ou l’aire
+réellement habitable. La version est publiée et la même instance Prism a été
+synchronisée deux fois, avec 363 fichiers personnels et réglages suivis conservés.
+Voir [WG-11](docs/backlog.md), [Validation](docs/testing.md) et
+[Distribution](docs/packwiz.md).
+
 Le premier champ de recherche climatique est défini : nord froid, sud chaud,
 ouest sec et est humide, avec leurs combinaisons diagonales. Un outil de
 développement relève les ressources après génération ; le système d'expansion
@@ -46,6 +186,95 @@ en jeu reste à construire. Voir [Expansion et ressources](docs/expansion.md).
 Les détails du terrain et de ses limites sont dans [Génération](docs/worldgen.md),
 et la provenance dans [Audit 26.2](docs/migration-26.2.md).
 
+## Alpha.11, historique : Petit, Grand et génération plus rapide
+
+Les anciens formats sont trop grands et éloignent les constructions. Le
+nouveau choix de départ se limite à **Petit** et **Grand**, avec **Grand par
+défaut**. Petit garde un diamètre nominal de 512 blocs ; Grand mesure environ
+724 blocs, soit deux fois l’aire nominale de Petit. La hauteur reste de
+384 blocs. Les repères internes 5 et 10 servent au calcul de surface : ils
+ne sont ni les noms des choix ni une promesse de capacité multijoueur.
+
+Grand utilise le nouveau réglage `sanctuary:population_10`. Les anciennes
+parties `population_5`, `population_20` et `population_100` gardent leurs
+paramètres ; les formats 20/100 sont retirés des choix publics de création,
+sans réduire les mondes déjà enregistrés. Aucun monde personnel n’est ouvert
+pour les essais.
+
+Le ticket [WG-12](docs/backlog.md) réduit les calculs répétés de terrain et
+permet de lire un plan régional déjà prêt pendant le calcul du suivant.
+À géométrie 20 identique, la création puis 289 chunks autour du spawn passent
+de 407,43 à 62,54 secondes (−84,65 %) ; 80 chunks d’exploration passent de
+103,14 à 14,05 secondes. Le nouveau Grand atteint 62,67 secondes sur le même
+protocole de départ. Ces essais serveur sur une graine et une machine ne
+mesurent pas le rendu du client ni une charge multijoueur.
+
+`check build assemblePack` passe, ainsi que douze tests moteur pour chacun
+des deux choix, avec 1 800 ticks de fluides. Plus de trois millions de
+comparaisons de densité confirment l’équivalence de calcul. Les mesures et
+limites sont dans [Validation](docs/testing.md) ; publication et synchronisation
+de la même instance sont consignées dans [Distribution](docs/packwiz.md).
+L’alpha.11 est publiée ; la même instance Prism a été synchronisée deux fois,
+avec les 364 fichiers personnels et réglages suivis conservés.
+
+## Alpha.12, historique — laboratoire d’expansion
+
+Un troisième preset **Sanctuary — Laboratoire** permet de tester les expansions
+dans un **nouveau monde**, sur la même version Minecraft. Les choix Petit et
+Grand gardent leur génération alpha.11. Le laboratoire possède sa propre île
+initiale de 512 blocs, avec un relief supérieur légèrement déformé et des biomes
+vanilla. Les nouvelles îles choisissent séparément leur parent, direction,
+climat, diamètre nominal (64/128/256/512) et relief (naturel, pics, canyon, volcan).
+
+Avec les commandes autorisées ou le statut opérateur :
+
+```text
+/sanctuary expansion quick north autumn 128 peaks
+/sanctuary expansion list
+/sanctuary expansion visit island_1
+/sanctuary expansion create oasis island_1 east arid 64 natural
+```
+
+Le premier exemple ouvre une forêt automnale au nord ; le second continent
+part vers l’est depuis cette île. `quick north` seul emploie la convention froide,
+avec 128 blocs et un relief naturel. `create` permet de choisir explicitement un
+identifiant et un parent. `preview` propose l’emplacement sans l’activer ;
+`resume <id>` reprend une réservation interrompue. L’autocomplétion liste les
+directions, douze profils climatiques et quatre reliefs.
+
+Les anciens chunks, même vides, sont refusés dans l’emprise d’une nouvelle île.
+Le registre persiste côté serveur ; la préparation est progressive et la visite
+attend un terrain prêt. Villages, temples, cabanes de marais et camps abandonnés
+vanilla peuvent être retenus selon leur biome et leurs fondations. Les autres
+structures, la grande hydrologie des continents, les recherches, les boîtes de
+dépôt et le refuge Void restent des étapes suivantes. Un biome humide ne promet
+pas encore un lagon ou un océan. Les règles, limites et essais figurent dans le
+[guide du laboratoire](docs/alpha12-laboratory.md).
+
+`check build assemblePack` et les essais d’expansion/rechargement de graine 42
+passent. L’alpha.12, son MRpack et le canal packwiz sont publiés ; la même
+instance Prism a été synchronisée deux fois, avec les 466 fichiers personnels
+et réglages suivis conservés. Voir [Distribution](docs/packwiz.md).
+
+## Alpha.12.1, historique — distance et emplacements libres
+
+Le correctif ajoute une distance minimale facultative à la fin des commandes :
+
+```text
+/sanctuary expansion quick north autumn 128 peaks 2048
+/sanctuary expansion create desert sanctuary east arid 128 natural 4096
+```
+
+La distance se mesure entre les centres depuis le parent choisi. Sans distance,
+le placement reste automatique. Les emplacements déjà générés sont maintenant
+écartés en cherchant plus loin dans la même direction, sans changer le climat
+ni réécrire les chunks. Les mondes laboratoire alpha.12 peuvent être conservés :
+le journal et la génération restent compatibles. Voir le [guide](docs/alpha12-laboratory.md).
+
+`check build assemblePack`, les scénarios moteur et les tests de distance passent.
+L’alpha.12.1 et son MRpack sont publiés ; la même instance Prism est synchronisée
+deux fois, avec 466 fichiers personnels et réglages suivis conservés.
+
 ## Versions et prérequis
 
 Au 8 septembre 2026, la cible disponible est **26.3-pre-2**. Le dépôt ne prétend
@@ -60,7 +289,7 @@ sera une mise à jour explicite, avec vérification des API et des sauvegardes.
 | Fabric API | 0.160.0+26.3 |
 | Fabric Loom | 1.17.20 |
 | Gradle Wrapper | 9.5.1, distribution vérifiée par SHA-256 |
-| Sanctuary / pack | 0.1.0-alpha.4 |
+| Sanctuary / pack | 0.1.0-alpha.13.1, publiée et synchronisée |
 
 Java 25 et Python 3.11 ou plus récent sont nécessaires. Le script pack utilise
 uniquement la bibliothèque standard et repère aussi une installation Python
@@ -81,13 +310,15 @@ cd sanctuary-beta
 ```
 
 `check` inclut les tests de forme et le serveur de test automatisé de Fabric,
-qui charge le vrai preset Sanctuary dans un monde de développement neuf.
+qui charge par défaut le nouveau générateur unifié Sanctuary dans un monde
+de développement neuf. Les suites historiques utilisent explicitement
+`-PsanctuaryUnifiedTests=false`.
 Les scénarios couverts et les essais multijoueurs restant à effectuer sont
 décrits dans [Validation](docs/testing.md).
 
 Résultats :
 
-- `mods/sanctuary/build/libs/sanctuary-0.1.0-alpha.4.jar` : mod à installer avec
+- `mods/sanctuary/build/libs/sanctuary-0.1.0-alpha.13.1.jar` : mod à installer avec
   Fabric API sur la version Minecraft indiquée.
 - `build/packwiz/` : pack de développement complet, avec le mod construit et
   l'index vérifié. Voir [Installation packwiz](packwiz/README.md).
@@ -105,7 +336,8 @@ Lancer le client de développement :
 ./gradlew :sanctuary:runClient
 ```
 
-Créer un **nouveau monde**, puis sélectionner le type de monde **Sanctuary**.
+Créer un **nouveau monde**, sélectionner le type **Sanctuary**, puis
+**Personnaliser** pour changer la taille Moyen retenue par défaut.
 L'installation du mod seule ne transforme pas un monde Minecraft ordinaire.
 
 Pour un serveur de développement, lancer `./gradlew :sanctuary:runServer`, puis

THIRD_PARTY_NOTICES.md

@@ -7,9 +7,15 @@ provenance détaillée et le périmètre du portage.
 Minecraft appartient à Mojang Studios / Microsoft. Sanctuary est un projet
 communautaire indépendant. Le dépôt ne redistribue pas le jeu.
 
-Le biome de départ reprend la configuration de la forêt vanilla 26.3-pre-2,
-adaptée pour une île finie. Les références de blocs, végétation et minerais
-sont résolues par Minecraft ; leurs textures et modèles ne sont pas inclus.
+Les biomes de départ reprennent les configurations de forêt, plaine, forêt de
+bouleaux, forêt fleurie et Dappled Forest de Minecraft 26.3-pre-2, adaptées à
+une île finie. Les variantes alpha.6 réutilisent les végétations vanilla pour
+les prairies fleuries et les bosquets ; Dappled Forest reste disponible pour
+les sauvegardes alpha.5. L’alpha.7 réemploie les arbres vanilla (dont chêne noir,
+cerisier et essences rares), les champignons, le bambou et les blocs de soufre
+de cette version, avec des conditions propres à l’île. Les règles des petits minerais sont adaptées à partir des
+features vanilla de cette même version. Les références de blocs, végétation et
+minerais sont résolues par Minecraft ; leurs textures et modèles ne sont pas inclus.
 
 Fabric Loader : Apache-2.0. Fabric API : Apache-2.0. Fabric Loom et le wrapper
 Gradle : Apache-2.0. Ces projets conservent leurs auteurs, notices et licences.

docs/alpha12-laboratory.md

@@ -0,0 +1,190 @@
+# Alpha.12 — laboratoire d’expansion
+
+Ticket local **WG-13**, branche `codex/expansion-lab`. Contrat du laboratoire et guide
+d’essai. Cette livraison reste une alpha ; le canal distribué est suivi séparément
+dans [Distribution](packwiz.md).
+
+## Décisions de conception
+
+La direction géographique et le climat deviennent deux choix distincts. La
+boussole nord froid / sud chaud / ouest sec / est humide reste un raccourci
+facultatif. Une île peut prolonger le climat de son parent ou ouvrir une branche
+vers un autre climat. Les parents et les coordonnées forment un graphe persistant,
+permettant plusieurs couronnes autour de Sanctuary. Les recherches, leurs coûts,
+les boîtes aux lettres et les boîtes de dépôt sont planifiés pour plus tard.
+
+Cette alpha fournit des commandes opérateur : créer, suivre, lister et visiter
+les expansions. Les tailles nominales des nouvelles îles sont 64, 128, 256 et
+512 blocs. Les reliefs de laboratoire s’appliquent aussi à l’île initiale, dans
+un nouveau preset expérimental. Les structures vanilla compatibles sont admises
+après contrôle de leur emprise et de leur support. Une absence reste possible.
+
+L’alpha sert à éprouver les outils et les paysages. Le passage en bêta se fera
+après définition du périmètre de la vision et de la progression jouable ; ce
+numéro ne désigne pas une progression collective déjà livrée.
+
+## Contrat de sauvegarde et d’ouverture v1
+
+- Activation exclusivement dans un **nouveau monde du laboratoire alpha.12**.
+  Les anciens presets, leurs paramètres, leurs chunks et leurs sauvegardes ne
+  sont pas convertis. Il n’existe pas de commande de migration ou de régénération.
+- Un journal serveur propre au monde enregistre graine, version, origine,
+  identifiant, parent, direction, climat, relief, diamètre, centre et statut.
+  Les paramètres d’une île sont immuables après réservation.
+- Toute la réservation inclut terrain, décorations et halo moteur. Les régions
+  déjà présentes sur disque, chargées ou en cours de déchargement sont refusées,
+  même si leurs blocs sont tous vides. Une erreur de lecture interdit l’ouverture.
+- Le journal est écrit atomiquement et relu avant de publier le nouveau plan au
+  générateur. Un journal existant absent ou corrompu n’est jamais remis à zéro.
+- La génération travaille uniquement dans la région nouvelle. Les chunks voisins
+  nécessaires au moteur restent dans son halo. Aucun bloc d’une ancienne région
+  n’est remplacé. Les références et le placement des structures utilisent le moteur.
+- Une réservation interrompue conserve son identité et sa graine. La préparation
+  peut reprendre, sans double île ni nouveau tirage, jusqu’au statut prêt.
+- Les commandes exigent la permission opérateur. Être en créatif seul ne confère
+  aucun droit sur le serveur. Une opération ne téléporte personne implicitement.
+- Le refuge Void et le déplacement collectif des joueurs restent un système
+  distinct à concevoir. Ils ne servent pas de mécanisme de protection des chunks.
+
+Le halo impose une distance supplémentaire dans cette première version. Le placer
+au plus proche ne permet pas de réutiliser silencieusement du vide déjà généré.
+Les points d’origine enregistrés ne suivent pas les changements de lit ou de spawn.
+
+## Commandes et palette
+
+Créer un **nouveau monde**, type **Sanctuary — Laboratoire**, avec les commandes
+activées. Pour un serveur neuf, utiliser `level-type=sanctuary:expansion_lab`
+et un nouveau `level-name`. La graine `42` fournit un cas reproductible observé
+avec un camp abandonné ; aucune structure n’est garantie sur chaque graine.
+
+```text
+/sanctuary expansion quick north autumn 128 peaks
+/sanctuary expansion list
+/sanctuary expansion visit island_1
+/sanctuary expansion create oasis island_1 east arid 64 natural
+/sanctuary expansion preview glacier sanctuary south glacial 256 canyon
+```
+
+`quick` part toujours de Sanctuary et attribue un identifiant `island_N`.
+`create <id> <parent> <direction> <climate> <diameter> <relief> [distance]` ouvre une branche
+nommée depuis n’importe quelle île prête. `preview` emploie les mêmes paramètres ;
+il propose des coordonnées mais ne valide ni l’occupation des chunks ni le sol.
+Répéter un `create` identique rend la même réservation ; un autre profil sous
+le même identifiant est refusé. `resume <id>` reprend une préparation interrompue.
+Après une erreur du journal, il faut rétablir le stockage puis recharger le monde.
+
+Depuis l’**alpha.12.1**, `quick`, `create` et `preview` acceptent une distance
+minimale facultative à la fin, de 0 à 100 000 blocs. Elle mesure la distance
+entre les centres du parent et de l’enfant, y compris en diagonale. L’alignement
+des chunks et les marges du terrain peuvent éloigner légèrement le résultat.
+Une valeur de 0, ou son omission, laisse le placement automatique.
+
+```text
+/sanctuary expansion quick north autumn 128 peaks 2048
+/sanctuary expansion create desert sanctuary east arid 128 natural 4096
+/sanctuary expansion preview glacier sanctuary northeast glacial 256 canyon 2048
+```
+
+Si une zone est déjà générée, `create` et `quick` essaient plus loin dans la
+même direction, sur 32 positions maximum avec un budget total de lecture de
+30 secondes. Le climat, le relief et la graine restent ceux de la demande.
+`preview` propose seulement le premier emplacement géométrique ; le résultat
+réel peut être plus loin. Les erreurs de lecture interrompent la recherche.
+Les anciens appels restent valides. Un identifiant déjà créé garde sa position ;
+demander sous le même nom une distance supérieure à sa distance réelle est refusé.
+
+Cette correction utilise le même journal v1 et les mêmes descripteurs de
+génération 12 : le monde laboratoire alpha.12 actuel peut être conservé. Aucun
+ancien chunk n’est régénéré ; la recherche réserve uniquement une nouvelle zone.
+
+| Profil de commande | Surface recherchée |
+| --- | --- |
+| `temperate` | Chênes, bouleaux, clairières et fleurs |
+| `boreal` | Taïga, bosquets et neige en hauteur |
+| `glacial` | Plaines enneigées, pics gelés et pointes de glace |
+| `cold_humid` | Vieilles taïgas et bosquets froids |
+| `humid` | Forêt sombre, marécages et Pale Garden ponctuel |
+| `tropical` | Jungle, bambous et mangrove basse |
+| `warm` | Savane et plateaux |
+| `arid` | Désert, badlands et cheminées érodées |
+| `dry` | Prairies exposées et reliefs pierreux |
+| `cold_dry` | Neige, gravier et sommets gelés |
+| `autumn` | Dappled Forest, prairies et bouleaux ponctuels |
+| `cherry` | Cerisiers, prairies et bosquets en hauteur |
+
+La sélection dépend de la graine, de l’altitude et de variations locales ; une
+petite île n’affiche pas nécessairement tous les biomes de son profil. Des poches
+luxuriantes, à spéléothèmes ou soufrées diversifient les étages inférieurs.
+Les reliefs `natural`, `peaks`, `canyon` et `volcano` sont indépendants du climat.
+Le volcan déforme et creuse la matière existante ; il ne garantit pas un cône
+plein ni un lac de lave lorsque la géométrie centrale est ajourée.
+
+Les valeurs par défaut de `quick` suivent la boussole décrite dans
+[Expansion](expansion.md), avec diamètre 128 et relief naturel. Les directions
+acceptées sont `north`, `northeast`, `east`, `southeast`, `south`, `southwest`,
+`west`, `northwest`. L’autocomplétion fournit les paramètres disponibles.
+
+## Portée technique et limites
+
+Le codec `sanctuary:expansion_lab` enregistre le générateur ; le journal conserve
+les descripteurs de génération **12**. Chaque île emploie sa propre graine dérivée
+de la graine du monde et de son identifiant. Changer d’identifiant change donc
+le tirage. Les instances de bruit sont propres aux îles, y compris après reload.
+Les 34 biomes vanilla sont déclarés avant la première expansion.
+
+La densité flottante existante sert de base. Le laboratoire ajoute les
+transformations des reliefs hauts et utilise les matériaux et décorations natifs.
+Ses carvers vanilla sont désactivés pour conserver les supports prospectés.
+Les grandes rivières et terrasses hydrologiques alpha.11 ne sont pas transférées
+dans ce prototype : les anciens presets les conservent. Le laboratoire essaie
+seulement de petites sources facultatives sur support rocheux fermé.
+
+Les structures autorisées sont les villages (diamètre au moins 256), pyramides
+du désert et de jungle, cabanes de marais et camps abandonnés. Les starts natifs
+sont acceptés après vérification de leur emprise et de leurs fondations ; le
+moteur place les pièces, références et butins. Leur grille de sélection diffère
+de celle de `/locate` vanilla : cette commande n’est pas un outil fiable pour
+les retrouver dans le laboratoire. La preuve actuelle porte sur un camp ; elle
+ne valide pas visuellement chaque type de village ou de temple.
+
+La réservation ajoute 32 blocs de décoration et 176 blocs de halo moteur autour
+de l’enveloppe de terrain. Les petites îles sont donc encore assez éloignées :
+le test de diamètre 64 place une première île à 800 blocs du centre de Sanctuary,
+puis une branche à 544 blocs de son parent. Un emplacement déjà exploré est
+écarté ; depuis l’alpha.12.1, la recherche continue plus loin sans réécrire ce vide.
+Il existe une limite de 64 régions, origine comprise, et de ±100 000 blocs pour
+leurs centres. La vérification initiale d’occupation est synchrone et peut
+suspendre brièvement le serveur pendant les lectures disque ; la préparation
+suivante avance chunk par chunk.
+
+Les bateaux volants, montgolfières, panthéons, îles uniques en béton coloré,
+océans coralliens, recherches, coûts et boîtes de dépôt restent dans la vision.
+Aucun command block, transfert collectif au Void ou reset global n’est nécessaire
+pour utiliser ces commandes.
+
+## Observations reproductibles
+
+Sur la graine **42**, le scénario moteur a ouvert une île tropicale de 64 blocs
+au nord, puis une île aride de 64 blocs à l’est de celle-ci. Chaque préparation
+a atteint 100 chunks FULL. Les biomes sauvegardés, les points d’arrivée sur sol
+réel, les permissions du dispatcher, le refus des doublons incohérents, la
+conservation d’un bloc témoin sur Sanctuary et le refus du vide déjà chargé
+ont été vérifiés. Un camp abandonné possède un tonneau placé avec sa table de
+butin vanilla. Sur la graine **0**, ces expansions fonctionnent mais aucun des
+11 sites de structure candidats n’a passé les conditions de terrain ; le test
+exigeant une preuve de butin a donc échoué sur cette graine.
+
+Un second processus Java a rouvert le monde de développement de graine 42 et
+retrouvé les trois régions prêtes, le bloc d’or écrit avant l’arrêt, les colonnes
+de blocs, biomes, densités et le tonneau. Le codec sauvegardé a aussi été décodé.
+Le framework GameTest reconstruit ses réglages depuis le preset : ce contrôle
+ne remplace pas un essai du parcours normal de chargement dans le client.
+La reprise d’un journal réservé est contrôlée séparément par le smoke ; un
+crash forcé en pleine génération, les téléportations de vrais joueurs et la
+charge multijoueur ne sont pas simulés.
+
+Les smokes parcourent cinq graines, les quatre tailles et les quatre reliefs :
+transformation verticale monotone, dessous de l’origine conservé, canyon retirant
+de la matière et couronne volcanique. Ce sont des contrôles géométriques ; les
+profils 128/256/512 et les quatre reliefs demandent encore une appréciation
+visuelle en jeu. Voir [Validation](testing.md) pour les commandes et preuves.

docs/alpha13-worldgen.md

@@ -0,0 +1,212 @@
+# Alpha.13 — un monde Sanctuary unifié
+
+**Publiée et synchronisée dans la même instance Prism.** Cette version réunit l’île de départ complète et les outils
+d’expansion du laboratoire.
+[Validation](testing.md) décrit les preuves disponibles et
+[Distribution](packwiz.md) indique la version effectivement publiée.
+
+La cible reste **Minecraft 26.3-pre-2 / Fabric**. Ce guide concerne un nouveau
+monde alpha.13. Les anciens mondes conservent leur génération.
+
+## Créer son monde
+
+1. Créer un **nouveau monde**, puis sélectionner le type **Sanctuary**.
+2. Ouvrir le bouton natif **Personnaliser**.
+3. Choisir la taille, puis cliquer sur **Terminé** avant de créer le monde.
+
+| Taille | Diamètre nominal de l’île initiale |
+| --- | --- |
+| Petit | 512 blocs |
+| Moyen, choix par défaut | 724 blocs |
+| Grand | 1 024 blocs |
+
+**Annuler** revient sans appliquer le changement. La hauteur reste de 384 blocs,
+de `Y=0` à `Y=383`. Le diamètre est une référence pour la forme : trous, surplombs,
+fragments et contour irrégulier dépendent de la graine. Il ne mesure pas une
+surface entièrement constructible et ne fixe pas un nombre de joueurs.
+
+La liste des types de monde contient un seul choix Sanctuary ; les types
+Minecraft habituels restent disponibles. Petit, Moyen et Grand sont des
+réglages de ce même choix. L’ancien Grand alpha.11, de 724 blocs, correspond
+au diamètre nominal du nouveau Moyen.
+
+Sur un serveur neuf, le preset suivant crée un monde de taille Moyen :
+
+```properties
+level-type=sanctuary:sanctuary
+level-name=sanctuary-dev
+level-seed=42
+```
+
+Choisir un dossier de monde neuf pour un essai. Le bouton **Personnaliser**
+configure la création en solo ; il ne modifie pas les fichiers d’un serveur
+existant. Installer le mod ou changer `level-type` ne transforme pas une partie.
+
+## L’île de départ
+
+Le nouveau monde reprend le générateur complet de l’île initiale : forêts de
+chênes et de bouleaux, clairières, affleurements, strates rocheuses et corniches
+intérieures. Son relief flottant conserve les trous et les surplombs, sans
+ajouter de noyau cylindrique pour garantir un terrain à l’origine.
+
+Les plans hydrologiques de Population sont repris : étangs et lacs, recherche
+de rivière, bassins étagés et leurs débordements, sources et cascades, poche et
+coulées de lave. Le placement dépend des supports réellement présents dans la
+roche. Un plan qui ne trouve pas de site admissible reste absent ; aucune
+rivière, terrasse ou ressource n’est garantie sur chaque graine. Les eaux en
+terrasses permettent la nage verticale sans ajouter de culture de riz.
+
+Les poches souterraines natives du laboratoire rejoignent cette île : cavités
+luxuriantes, à spéléothèmes ou soufrées, avec leurs décorations Minecraft.
+Il s’agit toujours des profondeurs de l’Overworld, pas de la dimension des
+cavernes prévue dans la vision. L’île garde sa palette tempérée en surface ;
+Dappled Forest reste disponible dans les expansions au climat automnal.
+
+L’intégration protège les volumes déclarés par les plans d’eau et de lave
+contre les écritures de décoration suivantes. Cette protection concerne les
+plans de génération, sans mettre les blocs à l’abri des actions des joueurs.
+Les preuves moteur et leurs limites sont suivies dans [Validation](testing.md).
+
+## Ajouter une île
+
+Les commandes demandent les commandes autorisées en solo ou la permission
+opérateur sur le serveur. Elles reprennent les outils alpha.12.1 dans le nouveau
+monde Sanctuary. L’économie, les recherches et les contributions collectives
+ne conditionnent pas encore leur utilisation.
+
+```text
+/sanctuary expansion quick north autumn 128 peaks
+/sanctuary expansion list
+/sanctuary expansion visit island_1
+/sanctuary expansion create oasis island_1 east arid 64 natural 2048
+```
+
+`quick` ouvre une île depuis Sanctuary et lui attribue un identifiant `island_N`.
+L’exemple de visite suppose qu’il s’agit de la première réservation ; `list`
+indique l’identifiant et l’état réels. La visite attend que l’île soit prête.
+`create` choisit un nom et un parent déjà prêt pour prolonger une branche.
+La création ne téléporte personne implicitement.
+
+Les nouveaux continents choisissent leur propre direction, climat, diamètre
+**64/128/256/512** et relief **natural/peaks/canyon/volcano**. La direction ne
+contraint pas le climat. L’autocomplétion fournit les huit directions et les
+douze profils : `temperate`, `boreal`, `glacial`, `cold_humid`, `humid`, `tropical`,
+`warm`, `arid`, `dry`, `cold_dry`, `autumn`, `cherry`.
+
+Le dernier nombre facultatif est une **distance minimale entre les centres**
+du parent et de l’enfant, entre 0 et 100 000 blocs. Une valeur de 0 ou son
+omission laisse le placement automatique. Les marges et l’alignement sur les
+chunks peuvent éloigner le centre retenu.
+
+Si le premier site est occupé, la recherche continue plus loin dans la même
+direction : au plus 32 positions et 30 secondes de lecture au total. Même du
+vide déjà généré compte comme occupé. Une erreur disque arrête la demande ;
+elle n’autorise pas à remplacer les chunks concernés.
+
+```text
+/sanctuary expansion preview glacier sanctuary northeast glacial 256 canyon 2048
+/sanctuary expansion resume island_1
+```
+
+`preview` calcule une proposition géométrique sans activer l’île et sans vérifier
+l’occupation ou les fondations. `resume` reprend une réservation interrompue,
+avec sa graine et ses paramètres conservés. Le système ne fournit aucune commande
+de régénération des régions déjà créées.
+
+Les îles ajoutées gardent la génération d’expansion alpha.12 : leurs climats,
+reliefs, décorations et structures compatibles. Elles ne reçoivent pas
+systématiquement la grande rivière ou les terrasses de l’île initiale. Villages,
+temples, cabanes de marais et camps abandonnés dépendent du biome, du diamètre
+et des fondations ; aucune présence n’est garantie. Les règles de progression
+futures restent décrites dans [Expansion](expansion.md).
+
+## Correctif alpha.13.1 — expansions sous Windows
+
+L’erreur `AccessDeniedException` visant le **dossier**
+`data/sanctuary-world-v13`, depuis `ExpansionJournal.persist`, vient de la
+synchronisation du répertoire après l’écriture du journal. Java sous Windows
+ne permet pas cette ouverture avec `FileChannel` ; ce message ne signifie pas
+à lui seul que le joueur manque de droits sur sa sauvegarde.
+
+1. Fermer Minecraft pour arrêter la session dont les expansions sont bloquées.
+2. Mettre l’instance Prism existante à jour vers **0.1.0-alpha.13.1** via son
+   canal packwiz, puis relancer le jeu.
+3. Rouvrir **le même monde** et consulter `/sanctuary expansion list`.
+
+Si l’instance Windows a été importée depuis le MRpack sans auto-update, fermer
+Minecraft puis remplacer seulement `sanctuary-0.1.0-alpha.13.jar` par le JAR
+`sanctuary-0.1.0-alpha.13.1.jar` de la release dans son dossier `mods`.
+Conserver un seul JAR Sanctuary actif ; les autres mods et les sauvegardes
+restent dans la même instance. Le raccordement au canal stable est décrit dans
+[Distribution](packwiz.md#raccorder-linstance-prism-existante).
+
+Le remplacement du journal ayant précédé cette erreur, l’expansion demandée
+peut déjà être enregistrée comme `reserved`. Au chargement, les réservations
+valides reprennent automatiquement avec leur identifiant, leur graine et leur
+position. Il n’est pas nécessaire de recréer le monde ou de supprimer le dossier
+du journal. La commande `resume` seule ne débloque pas une session dont le
+journal a été déclaré indisponible : sa relecture exige de rouvrir le monde.
+
+Le correctif conserve le format et le contenu du journal existant ; il ne
+migre ni ne régénère les chunks. La [validation ciblée](testing.md#correctif-alpha131--journal-dexpansion-sous-windows)
+distingue les contrôles locaux de l’essai Windows natif restant à effectuer.
+
+## Paramètres et sauvegardes
+
+Le preset public `sanctuary:sanctuary` utilise le nouveau codec de générateur
+`sanctuary:island_v13`. Sa source de biomes est également enregistrée sous
+`sanctuary:island_v13`. Le générateur sérialise `initial_diameter`, limité à
+512, 724 ou 1 024 ; une valeur absente prend 724. Ce champ appartient à la
+sauvegarde créée, et ne suit pas les changements ultérieurs de défaut du pack.
+
+Pour l’île initiale, les réglages internes `sanctuary:unified_5`,
+`sanctuary:unified_10` et `sanctuary:unified_20` correspondent respectivement
+aux diamètres 512, 724 et 1 024. Les suffixes sont des références de calcul,
+pas des capacités affichées. Ils reprennent la densité Population et son
+hydrologie avec le générateur et le `RandomState` propres à l’origine.
+
+La source combine la palette Population de départ et le sélecteur de cavités
+natives du laboratoire, avec les mêmes conditions de sélection de ces poches.
+Les îles enfants conservent le sélecteur climatique du laboratoire. Les 34
+biomes natifs de cette palette et les dix biomes Population sont déclarés
+avant la première expansion ; TerraMix n’est pas une dépendance téléchargée.
+
+Le nouveau journal est enregistré dans le dossier du monde :
+
+```text
+data/sanctuary-world-v13/expansions.json
+```
+
+Son schéma reste **1**, avec une racine de **génération 13** et des extensions
+de **génération 12**. Les identifiants, parents, graines, paramètres, positions
+et états d’ouverture sont conservés côté serveur. La racine et le diamètre
+initial ne sont pas modifiables par une commande d’expansion.
+
+Les mondes du laboratoire alpha.12/12.1 gardent leur codec et leur journal
+`data/sanctuary-expansion-v1/expansions.json`. Les générations Population et
+les autres générations antérieures gardent leurs paramètres enregistrés.
+Les presets historiques sont conservés mais cachés dans la création publique.
+**Aucun monde n’est converti, agrandi, réduit ou régénéré par l’alpha.13.**
+Le [guide alpha.12](alpha12-laboratory.md) est une référence historique, pas une
+instruction de sélectionner à nouveau le laboratoire pour cette version.
+
+## Contrôles de développement
+
+`./gradlew check build assemblePack` et `:sanctuary:runGameTest` sélectionnent
+par défaut la suite unifiée. Son diamètre de test se choisit avec
+`-PsanctuaryTestDiameter=512`, `724` ou `1024` ; il ne change pas le défaut public.
+
+Les suites Population historiques demandent `-PsanctuaryUnifiedTests=false`,
+avec leur profil `-PsanctuaryTestPlayers=5`, `10`, `20` ou `100`. Les essais du
+laboratoire historique utilisent aussi ce drapeau, avec
+`-PsanctuaryExpansionTests=true`. Ces processus travaillent dans les dossiers
+de développement ignorés, jamais dans les sauvegardes personnelles.
+
+Les validations et mesures des alpha.11, .12 et .12.1 restent historiques.
+Elles ne prouvent ni les temps de chargement ni le rendu de cette intégration.
+Les trois tailles, l’interface native et les expansions/rechargements passent
+les contrôles alpha.13. Moyen atteint 63,66 s pour créer le monde puis charger
+289 chunks FULL sur la graine 0 ; voir [Validation](testing.md) pour le protocole
+et ses limites. La release, le MRpack et le canal packwiz sont publiés ; deux
+synchronisations dans la même instance Prism conservent les 601 fichiers
+personnels et réglages suivis. Voir [Distribution](packwiz.md).

docs/backlog.md

@@ -10,7 +10,14 @@ Le [document de vision](vision.md) conserve les idées à long terme. Ce backlog
 commit. Le prototype WG-02 et l'initialisation du spawn WG-03 sont implémentés
 et passent les tests serveur décrits dans [Validation](testing.md). Les essais
 visuels, multijoueurs et de redémarrage indiqués dans ce document restent à
-faire avant de clôturer tous leurs critères. WG-04 à WG-07 restent proposés.
+faire avant de clôturer tous leurs critères. WG-04 à WG-07 restent ouverts,
+avec les incréments de l’île initiale décrits ci-dessous. WG-08 est validé ;
+WG-09 est livré en alpha.8, avec mesures moteur et mise à jour Prism vérifiées.
+WG-10 est livré en alpha.9, avec mesures moteur et synchronisation Prism vérifiées.
+WG-11 est livré en alpha.10 : tailles 5/20/100 validées sur la graine 0,
+release publiée et même instance Prism synchronisée.
+WG-12 est livré en alpha.11 : Petit/Grand, génération accélérée et même instance
+Prism synchronisée deux fois ; voir [Distribution](packwiz.md).
 
 Résultat visé : un client et un serveur Fabric compatibles peuvent ouvrir un monde Sanctuary, plusieurs joueurs y arrivent sur une même île sûre et les chunks extérieurs restent vides. La génération est reproductible et ses limites sont documentées.
 
@@ -118,13 +125,33 @@ Ce jalon fournit un outil de développement du terrain. L'interface d'expansion
 - Pour l'île initiale tempérée et légèrement humide : privilégier petits étangs,
   lacs de surface, rivière et berges propices à la canne à sucre, avec quelques
   plages plus sèches. Pas de grands bassins souterrains remplis d'eau.
-- L'eau ne se répand pas de manière incontrôlée dans le vide lors du chargement et des mises à jour de blocs du scénario testé.
+- Les étangs et les lacs retiennent leur eau après les mises à jour de blocs.
+  Des sources rocheuses déclarées peuvent former des cascades jusqu’au vide ;
+  leurs écoulements restent attribuables à ces sources, sans inondation globale.
 - Les profils du dessous et les bords du continent sont inspectés visuellement depuis les airs.
 - La génération est mesurée sur une emprise et une machine indiquées ; les valeurs observées sont consignées, sans annoncer un objectif de performance non mesuré.
 
-**Incrément île initiale — alpha.4 :** première hydrologie de surface, documentée
-dans [Génération](worldgen.md). Ce travail prépare les eaux des continents sans
-clore WG-06 : océans, grandes rivières et cascades restent à développer.
+**Incrément île initiale — alpha.4 :** première hydrologie de surface retenue,
+conservée pour les sauvegardes de cette version.
+
+**Incrément île initiale — alpha.5 :** plages plus larges,
+dépôts de trois à cinq couches sur support naturel, excavation limitée,
+rives variées et sources rocheuses pouvant former des cascades jusque dans le
+vide. Le contrat et l’isolation des anciennes générations sont décrits dans
+[Génération](worldgen.md). Ce travail prépare les eaux des continents sans clore
+WG-06 : océans, grandes rivières et ouverture des continents restent à développer.
+
+**Incrément île initiale — alpha.6 :** retrait des courts ruisseaux, conservation
+des bassins, présence de roche élargie et sources de paroi dans les strates
+inférieures. Les écoulements sont contrôlés dans le moteur et les anciennes
+générations sont préservées.
+
+**Suite suivie dans WG-09 — grande rivière facultative :** chercher un long parcours qui
+épouse l’île, avec source, chute et bassin, rives de sable, gravier et argile.
+Le démontrer sur la vraie densité Minecraft puis après décoration et ticks de
+fluide, avec une graine et des coordonnées reproductibles. Les essais du
+prototype alpha.6 n’ont fourni aucun parcours retenu sur les graines de référence ;
+ce prototype n’est pas distribué. Ne pas imposer de rivière si le relief ne s’y prête pas.
 
 ### WG-07 — Introduire un premier biome distinct et une structure
 
@@ -140,6 +167,375 @@ clore WG-06 : océans, grandes rivières et cascades restent à développer.
 - La reprise du catalogue TerraMix natif d'Another World 26.2 est évaluée séparément ; « plus de cent biomes » reste une ambition tant que son adaptation n'est pas vérifiée.
 - Les limites des futures zones Lost Cities et des structures uniques sont identifiées sans imposer leur livraison dans ce ticket.
 
+**Incrément île initiale — alpha.5 :** cinq variantes
+tempérées à dominante forestière, dont Dappled Forest vanilla 26.3, et petits
+filons de sept minerais à des altitudes adaptées. Leurs stocks sont observés
+après génération. Cela ne clôture pas WG-07 : aucune structure de référence ni
+reprise du catalogue TerraMix n’est encore fournie. La survie initiale doit
+permettre de produire et progresser au-delà du bois et de la pierre ; l’accès
+à toute la progression Minecraft n’est pas encore garanti pour chaque seed.
+
+**Ticket palette — alpha.6 :** réserver les biomes très contrastés de la 26.3,
+dont Dappled Forest, aux futurs continents. L’île combine prairies fleuries,
+bosquets et zones rocheuses, avec des teintes cohérentes et une végétation
+effective sur les corniches inférieures. Cela ne livre pas encore les continents.
+
+### WG-08 — Forêts de survie et minerais visibles — alpha.7
+
+**Branche :** `codex/woodland-canopy`.
+
+**But :** conserver les formes rocheuses appréciées en alpha.6 tout en donnant
+à l’île de vraies forêts de surface et des ressources de départ repérables.
+
+**Critères d’acceptation :**
+
+- Chênes majoritaires parmi les arbres de surface observés, bouleaux secondaires,
+  avec des arbres au cœur de l’île et des clairières fleuries.
+- Chênes noirs réels et champignons sur des corniches intérieures naturelles ;
+  jungle/bambou et matières de soufre rares et localisés.
+- Un éventuel arbre remarquable, choisi parmi les essences rares, sans ajout
+  de terrain ni obligation de fournir chaque essence par graine.
+- Affleurements de pierre, andésite, diorite et granite ; sable et gravier
+  associés aux eaux, avec des couches soutenues.
+- Charbon, fer et cuivre visibles au contact de l’air sur la roche, avec des
+  petits filons sans quota corrigé après génération.
+- Démonstration dans le moteur, maintien des eaux après 1 800 ticks et
+  conservation des anciennes générations. Publication packwiz et mise à jour
+  de l’instance Prism existante en conservant ses données personnelles.
+
+**Vérification alpha.7 :** les trois graines de référence passent les tests
+du moteur, dont les forêts, les minerais exposés et les eaux après 1 800 ticks.
+Les observations et leurs limites sont consignées dans [Validation](testing.md).
+
+### WG-09 — Failles, rivière et profondeurs — alpha.8
+
+**Branche :** `codex/rifts-rivers-and-depths`.
+
+**But :** ouvrir l’intérieur de l’île, enrichir sa géologie et ses ressources
+de survie, tout en conservant les forêts de surface appréciées en alpha.7.
+
+**Critères d’acceptation :**
+
+- Une à trois traces de failles courbes, de longueur nominale 84 à 160 blocs
+  et de largeur variable, retirent uniquement de la matière du relief initial.
+  Leur intersection réelle avec la roche est montrée sur les graines testées.
+- Les forêts de chênes et de bouleaux restent présentes en surface. Des gros
+  champignons, des petits champignons dispersés et des tapis de mousse, podzol
+  et mycélium occupent les corniches compatibles de l’intérieur humide.
+- Les matières changent avec la profondeur, avec des nappes de tuf, cobblestone,
+  pierre moussue et boue compactée, puis ardoise des abîmes, roche noire et basalte.
+  Des poches de soufre réellement accessibles sont observées sur le terrain.
+- Charbon, fer et cuivre exposés sont plus faciles à repérer dans les relevés.
+  L’émeraude est ajoutée ; or, diamant, redstone et lapis sont cherchés aux
+  altitudes présentes. Aucun stock fixé n’est réinjecté après comptage.
+- Des bassins plus grands sont retenus. Une rivière facultative est démontrée
+  par un chemin d’eau continu d’au moins 140 blocs, reliant deux bassins au
+  même niveau avec source rocheuse et cascade entrante. Le tracé est arrondi
+  à l’échelle de 16 à 32 blocs, avec largeur de lit variable d’environ 5 à 7
+  blocs. L’incision du lit reste bornée à 16 blocs ; les berges de rivière
+  s’étagent progressivement avec au plus 12 blocs retirés, contre 2 pour les
+  autres rives. Le fond et les dépôts reposent sur le terrain existant.
+- La poche de lave couverte est recherchée en priorité sur une corniche basse
+  entre Y=64 et Y=160 ; la recherche plus haute n’intervient que si aucun
+  emplacement profond compatible n’est trouvé.
+- Une à deux sources profondes de lave sont recherchées lorsque le site est
+  compatible ; leurs coulées viennent des ticks vanilla. Les supports, les
+  eaux voisines et la végétation sont contrôlés après simulation réelle.
+- La nouvelle clé `sanctuary:sanctuary_rift` n’active ces traitements que pour
+  les nouveaux mondes. Les données et comportements historiques restent séparés.
+- Les graines `0`, `42` et `8675309` disposent de mesures moteur explicites,
+  avec fluides actifs pendant 1 800 ticks. Une absence de rivière ou de source
+  est rapportée honnêtement ; un bassin isolé ne valide pas une rivière.
+- Après validation : build et pack vérifiés, publication immuable, deux
+  synchronisations du canal packwiz et conservation de la même instance Prism,
+  de ses sauvegardes et de ses réglages.
+
+**Vérification moteur alpha.8 — 9 septembre 2026 :** les trois graines de
+référence passent les contrôles finaux, dont les deux bassins terminaux,
+les champignons connectés et 1 800 ticks de fluides. Les stocks et leurs
+périmètres sont consignés dans [Validation](testing.md). Le build complet est
+réussi. L’alpha.8 est publiée sur le canal stable et la même instance Prism
+est synchronisée deux fois, avec sauvegardes et réglages conservés. Le ticket
+est livré ; l’appréciation visuelle et l’équilibrage en partie restent à
+éprouver. Ce ticket local n’est pas une issue distante publiée.
+
+### WG-10 — Cavités luxuriantes et terrasses d’eau — alpha.9
+
+**Branche :** `codex/lush-caverns-and-water-terraces`.
+
+**But :** rendre les cavités sous Sanctuary plus vivantes et lumineuses,
+diversifier leurs ressources et créer des eaux plus volumineuses, sans
+remplacer les forêts et la rivière de surface appréciées en alpha.8.
+
+**Critères d’acceptation :**
+
+- Des cavités luxuriantes portent une végétation réellement lumineuse et
+  enracinée dans les surfaces et plafonds existants. Les observations doivent
+  distinguer un biome déclaré, ses blocs décoratifs et leur lumière réelle.
+- Des secteurs à spéléothèmes et des géodes d’améthyste sont recherchés dans
+  la roche compatible ; leurs supports, leurs volumes et leur accessibilité
+  sont contrôlés dans les vrais chunks, sans géodes suspendues dans le vide.
+- Le soufre occupe moins de roche qu’en alpha.8, sur un périmètre de comparaison
+  explicite. Les geysers éventuels utilisent le soufre actif et les conditions
+  exactes de Minecraft 26.3-pre-2 ; leur fonctionnement doit être démontré,
+  sans confondre un bloc jaune avec un geyser actif.
+- Les forêts, la rivière et les bassins de surface restent présents lorsque
+  le relief le permet. Les lacs plus profonds et volumineux sont mesurés en
+  blocs d’eau réels, avec fond et parois retenus après simulation.
+- Des groupes facultatifs de deux bassins naturels en terrasses
+  peuvent relier plusieurs niveaux par des cascades déclarées. Chaque palier
+  doit avoir ses supports et son propre volume retenu ; une cascade isolée
+  ou des plans d’eau sans liaison ne valident pas un groupe de terrasses.
+  Le second bassin peut avoir une sortie terminale vers les roches ou le vide,
+  sans créer un troisième palier.
+- Ces cascades offrent un passage vertical selon les règles de nage de
+  Minecraft. « Rizières » désigne seulement leur disposition paysagère :
+  aucune culture de riz ni téléportation n’entre dans ce ticket.
+- Les sorties d’eau sont contrôlées après décoration et après 1 800 ticks,
+  y compris aux frontières de chunks. Leur finition initiale doit préserver
+  les aménagements du joueur aux rechargements suivants.
+- Le nouveau réglage `sanctuary:sanctuary_cavern` s’applique aux nouveaux
+  mondes. Les identifiants et traitements alpha.1 à alpha.8 restent séparés ;
+  aucune sauvegarde personnelle n’est modifiée par les essais.
+- Les graines `0`, `42` et `8675309` disposent de mesures identifiées par
+  version. Les sites absents sont signalés ; aucun quota de ressources ni
+  bassin de secours ne remplit un relief incompatible.
+- Après validation : `check build assemblePack`, artefacts immuables vérifiés,
+  deux synchronisations isolées puis deux dans la même instance Prism,
+  sauvegardes et réglages conservés.
+
+**Validation moteur au 9 septembre 2026 :** les trois graines de référence
+passent les contrôles finaux. Les preuves cumulées démontrent un groupe de
+deux paliers reliés, un geyser actif et les décors souterrains demandés ; les
+absences locales et périmètres de mesure figurent dans [Validation](testing.md).
+Le build est réussi ; la release et le canal packwiz sont publiés. Les deux
+synchronisations isolées puis les deux passages dans la même instance Prism
+réussissent, avec 260 fichiers personnels et réglages conservés. Ce ticket
+local n’est pas une issue distante publiée ; l’essai visuel et l’équilibrage
+restent ouverts.
+
+### WG-11 — Tailles d’île selon la capacité — alpha.10 livrée
+
+**Branche :** `codex/player-capacity-presets`.
+
+**But :** choisir une île initiale adaptée à un groupe de 5, 20 ou 100 joueurs,
+avec 20 joueurs par défaut, tout en conservant l’ambiance et les anciennes parties.
+
+**Critères d’acceptation :**
+
+- La création d’un nouveau monde propose trois choix identifiables en FR/EN :
+  Sanctuary par défaut pour 20 joueurs et des variantes pour 5 et 100 joueurs.
+  Les presets `sanctuary:sanctuary_5`, `sanctuary:sanctuary` et
+  `sanctuary:sanctuary_100` sélectionnent respectivement les paramètres
+  `sanctuary:population_5`, `sanctuary:population_20` et
+  `sanctuary:population_100`, qui doivent persister dans le monde sauvegardé.
+- L’aire nominale suit le rapport capacité/5. Les diamètres de référence sont
+  512, 1 024 et environ 2 290 blocs ; la hauteur reste de 384 blocs. Le contour
+  sculpté dépend de la graine et n’est pas remplacé par un cercle ou un cylindre.
+- Le choix dimensionne la génération, sans modifier `max-players`, imposer
+  un quota de ressources ni redimensionner l’île lorsque des joueurs arrivent.
+- Les tailles conservent un extérieur vide, un spawn naturel, les forêts et
+  l’écologie des cavités. Les eaux et les décors doivent être contrôlés dans
+  les vrais chunks de la taille testée, pas seulement extrapolés depuis l’alpha.9.
+- Les réglages et identifiants des générations précédentes restent séparés.
+  Une mise à jour du pack n’agrandit pas un ancien monde, ne convertit pas son
+  générateur et ne régénère aucun chunk.
+- La validation progresse de 5 à 20 puis 100 joueurs dans des mondes de
+  développement neufs. Chaque résultat précise capacité, graine, emprise
+  réellement inspectée et durée observée. Un petit échantillon ne valide pas
+  l’intégralité d’une grande île.
+- Les tests de génération ne sont pas présentés comme des connexions de
+  joueurs simulées ni comme une promesse de performances multijoueurs.
+- Après validation : `check build assemblePack`, artefacts immuables vérifiés,
+  deux synchronisations isolées puis deux dans la même instance Prism,
+  avec sauvegardes et réglages conservés.
+
+**État au 9 septembre 2026 :** implémentation et validation moteur terminées
+sur la graine `0` pour les profils 5, 20 et 100. Les onze tests requis passent
+dans chaque monde, avec les fluides pendant 1 800 ticks et la persistance réelle
+des réglages sur disque. Le build et les artefacts sont vérifiés ; la release
+et le canal sont publiés. Deux synchronisations isolées puis deux dans la même
+instance Prism réussissent, avec 363 fichiers personnels et réglages conservés.
+Les références figurent dans [Distribution](packwiz.md).
+Les anciens mondes restent inchangés. Les observations ne couvrent pas toute
+l’île de 100 joueurs, et le coût initial d’un plan régional reste notable.
+Ce ticket local n’est pas une issue distante publiée.
+
+### WG-12 — Petit, Grand et génération plus rapide — alpha.11 livrée
+
+**Branche :** `codex/worldgen-performance`.
+
+**Problème :** les grands formats éloignent trop les constructions. Les essais
+signalent aussi plusieurs minutes de chargement puis des chunks difficiles à
+utiliser. Le ticket rapproche les deux choix de départ et optimise les calculs,
+avec des preuves distinctes pour la taille et la vitesse.
+
+**Critères d’acceptation :**
+
+- Proposer seulement **Petit** et **Grand** dans la création, avec **Grand par
+  défaut**, et libellés FR/EN. Petit garde le diamètre nominal de 512 blocs ;
+  Grand vise environ 724 blocs, soit une aire nominale deux fois supérieure.
+  La hauteur reste de 384 blocs. Les nombres 5/10 ne servent que de repères
+  internes de surface, sans capacité de joueurs garantie.
+- Associer Petit à `sanctuary:sanctuary_5` / `sanctuary:population_5` et Grand
+  à `sanctuary:sanctuary` / nouveau réglage `sanctuary:population_10`.
+  Garder les anciens réglages `population_20` et `population_100` chargeables,
+  tout en cachant leurs formats dans les choix publics de création.
+- Ne pas modifier le relief d’une sauvegarde existante, son identifiant ou
+  son format. Les changements du défaut de création ne convertissent pas
+  un monde. Aucune sauvegarde personnelle n’est ouverte pendant les essais.
+- Pour l’optimisation, **conserver les résultats à paramètres identiques** :
+  densités, plans et blocs utiles, ordre déterministe et protections de l’eau,
+  des terrasses et de la lave. Le nouveau relief Grand a une clé distincte ;
+  la réduction de surface ne compte pas comme gain de calcul à géométrie égale.
+- Mesurer séparément démarrage initial, planification et génération d’un lot
+  explicite de chunks. Fixer machine, Java, mémoire, graine, paramètres,
+  coordonnées et état des caches pour comparer alpha.10 et alpha.11.
+- Viser **120 secondes au plus de démarrage initial** pour les choix publics
+  et **au moins 30 % de gain** sur les phases comparées à géométrie identique.
+  Un temps de planificateur seul ne prouve pas l’entrée dans un monde jouable.
+  Préciser les bornes de chronométrage et ne pas promettre ces seuils pour
+  tout matériel ou pour une charge de cent joueurs.
+- Valider Petit et Grand, plus un témoin de compatibilité et de performance
+  sur l’ancien profil 20. Les anciennes mesures 100 restent historiques ;
+  ce format n’est plus un choix public ni le centre du plan de validation.
+  Examiner le premier accès, le cache réutilisé et les chunks d’exploration.
+- Conserver les contrôles moteur de fluides et de réentrée sans marqueur,
+  puis exécuter `check build assemblePack` sur les sources finales. Garder
+  visibles les limites et toute cible de performance non atteinte.
+- Après validation seulement : artefacts immuables, canal packwiz stable,
+  deux synchronisations isolées puis deux dans la même instance Prism. Les
+  mondes, réglages et mods personnels, même désactivés, doivent être préservés.
+
+**État :** livré. Artefacts immuables publiés, canal stable avancé, deux
+synchronisations isolées et deux dans la même instance Prism, avec 364 fichiers
+personnels et réglages suivis conservés. Tailles et code validés. `check build assemblePack` passe, ainsi
+que douze tests moteur sur Petit et Grand (graine 0, 1 800 ticks), les contrôles
+de persistance et l’équivalence bit à bit. Le benchmark ancien20 comparable
+baisse de 84,65 % au départ et de 86,38 % en exploration. Grand atteint
+62,67 secondes pour création + 289 chunks FULL. Cette mesure serveur ne
+valide pas le rendu ni un temps de chargement universel. Voir
+[Validation](testing.md), [résultats](benchmarks/alpha11-generation.json) et
+[Distribution](packwiz.md) pour le reçu de publication et de synchronisation.
+Ce ticket local n’est pas une issue distante publiée.
+
+### WG-13 — Laboratoire d’expansion à branches — alpha.12
+
+**Branche :** `codex/expansion-lab`.
+
+**But :** tester en opérateur de nouvelles îles, des climats alternatifs, les
+reliefs hauts et les structures vanilla avant de développer leur progression.
+
+**Critères d’acceptation :**
+
+- Nouveau preset laboratoire ; Petit/Grand et anciennes parties conservés.
+- Commandes pour préparer, créer, suivre, reprendre et visiter une île ;
+  opérateurs uniquement, raccourcis et retours FR/EN.
+- Parent et direction indépendants du climat, avec tailles nominales bornées
+  64/128/256/512 et reliefs versionnés. Une branche peut changer de climat.
+- Application du relief haut aussi à l’île initiale expérimentale ; dessous
+  historique et sources anciennes préservés.
+- Structures vanilla sélectionnées par biome avec contrôles d’emprise/support ;
+  preuve moteur d’une structure réellement placée et de son butin natif.
+- Journal atomique et repris après interruption, demandes répétées sans doublon,
+  refus des chunks existants y compris vides, conservation d’un bloc témoin.
+- Contrat de réservation explicite avant toute activation. Aucun ancien monde
+  converti ; aucune suppression de chunks ni commande de régénération.
+- `check build assemblePack` et tests moteur sur monde jetable, avec limites
+  documentées. Les recherches, prix, boîtes postales et le Void restent planifiés.
+
+**État :** implémenté et vérifié localement : build/pack, douze tests historiques,
+expansions et rechargement moteur de graine 42. Release et MRpack publiés,
+canal packwiz avancé et même instance Prism synchronisée deux fois ; 466 fichiers
+personnels et réglages suivis conservés. Validation visuelle et multijoueur
+encore ouverte. Contrat et portée des preuves
+dans [Laboratoire alpha.12](alpha12-laboratory.md).
+Ce ticket ne clôture pas par avance les océans, toute la palette de structures
+ou la progression collective prévus par WG-04 à WG-07 et la vision.
+
+### WG-14 — Distance et recherche d’un emplacement libre — alpha.12.1
+
+**Branche :** `codex/expansion-free-space`.
+
+**Problème :** les huit premiers emplacements peuvent contenir du vide déjà
+sauvegardé. L’alpha.12 refuse alors toutes les directions au lieu de chercher
+plus loin, et ne propose aucun paramètre de distance.
+
+**Contrat et résultat attendu :**
+
+- Distance minimale facultative en fin de `quick`, `create` et `preview`, en
+  blocs entre les centres du parent et de l’enfant ; 0 ou omission = automatique.
+- Rechercher au plus 32 positions sur le même rayon en dépassant les zones
+  occupées ; conserver le budget global de lecture de 30 secondes.
+- Seule une occupation certaine autorise un nouvel essai. Une erreur disque,
+  un timeout ou un terrain sans sol ne doivent pas devenir un nouveau tirage.
+- Préserver les anciennes commandes, les identifiants, la graine de chaque île,
+  les descripteurs de génération 12 et le journal v1. La correction s’applique
+  aux mondes laboratoire alpha.12 sans conversion. Les régions existantes
+  sont inchangées ; seules de nouvelles réservations peuvent être ajoutées.
+- Vérifier les huit premières directions occupées, la création plus loin,
+  la distance demandée depuis une île fille et les chunks sauvegardés après
+  redémarrage. Fournir les retours FR/EN et la distribution packwiz/MRpack.
+
+**État :** correction implémentée, smokes et scénarios moteur de création/rechargement
+réussis. `check build assemblePack` et douze tests historiques réussis.
+Release, MRpack et canal packwiz publiés ; même instance Prism synchronisée
+deux fois, avec 466 fichiers personnels et réglages suivis conservés.
+
+### WG-15 — Unifier Sanctuary et ses options — alpha.13
+
+**Branche :** `codex/unified-worldgen`.
+
+- Un seul type public Sanctuary, bouton Personnaliser avec Petit (512), Moyen
+  (724, défaut), Grand (1 024). Choix enregistré dans le générateur ; Annuler
+  conserve les réglages. Les types vanilla restent disponibles.
+- Réunir le relief, les forêts, minerais, rivières, bassins, terrasses et lave
+  de Sanctuary avec les cavités vanilla luxuriantes, à spéléothèmes et soufrées
+  du laboratoire, en protégeant les volumes hydrologiques pendant la décoration.
+- Les outils d’expansion alpha.12.1 fonctionnent dans les nouveaux mondes unifiés.
+  Même contrat opérateur, réservation de zones nouvelles et refus du vide exploré.
+- Nouveau codec et origine génération 13 ; les anciens codecs et journaux restent
+  chargeables. Aucun monde personnel n’est ouvert ou converti, aucun chunk régénéré.
+- Vérifier les trois tailles, cavités réellement décorées et fluides après ticks,
+  persistance/rechargement, UI client, build et distribution dans la même instance.
+
+**État :** implémenté et vérifié : bouton natif, paramètres sur disque, huit tests
+moteur par taille sur la graine 42, eau après 1 800 ticks, trois cavités natives,
+compatibilité historique et rechargement des expansions. Moyen : 63,66 s pour
+création et 289 chunks FULL dans le protocole serveur de référence.
+`check build assemblePack` passe. Release, MRpack et canal packwiz publiés ;
+même instance Prism synchronisée deux fois, avec 601 fichiers personnels et
+réglages suivis conservés.
+Les limites, dont l’absence de preuve de camp dans l’origine unifiée des graines
+inspectées, sont documentées dans [Validation](testing.md).
+
+### WG-16 — Journal d’expansion sous Windows — alpha.13.1
+
+**Branche :** `codex/windows-expansion-journal`.
+
+**Problème :** après le remplacement atomique du journal, l’ouverture de son
+répertoire par `FileChannel` échoue sous Windows avec `AccessDeniedException`.
+La session arrête alors toute expansion, même si la réservation a déjà été écrite.
+
+- Écarter uniquement la synchronisation de répertoire non prise en charge par
+  le système de fichiers Windows ; conserver force du fichier, remplacement
+  atomique, relecture stricte et arrêt sur les véritables erreurs de stockage.
+- Conserver le schéma, les identifiants, la géométrie et les journaux existants.
+  Après mise à jour et rechargement, reprendre les réservations déjà enregistrées
+  avec le mécanisme existant, sans suppression ni reconstruction de l’historique.
+- Tester le chemin Windows par injection, une panne après remplacement et la
+  reprise, puis le build et les scénarios moteur dans le développement local.
+- Publier le correctif sur le canal stable. La machine Windows signalée n’est
+  pas accessible depuis cet environnement Mac : ne pas prétendre l’avoir testée.
+
+**État :** correctif et tests vérifiés en alpha.13.1. `check build assemblePack`
+passe, ainsi que le smoke du journal et les scénarios de création/rechargement
+dans deux processus Minecraft distincts. Validation Windows par injection sur
+macOS ; aucun essai Windows natif. Correctif publié depuis `b19e93d`, canal
+stable avancé et deux synchronisations isolées puis deux dans la même instance
+Prism Mac réussies, avec 713 fichiers personnels et réglages suivis conservés.
+Preuves dans [Validation](testing.md) et [Distribution](packwiz.md).
+
 ## Réserve de thèmes futurs
 
 Ces thèmes servent à retrouver la vision, pas à demander leur implémentation immédiate. On en extrait un ticket seulement lorsqu'il devient utile au prochain incrément jouable.

docs/benchmarks/alpha11-generation.json

@@ -0,0 +1,654 @@
+{
+  "ticket": "WG-12",
+  "version": "0.1.0-alpha.11",
+  "date": "2026-09-09",
+  "protocol": {
+    "machine": "Apple M1, 8 GiB RAM, macOS",
+    "minecraft": "26.3-pre-2",
+    "fabric_loader": "0.19.5",
+    "fabric_api": "0.160.0+26.3",
+    "baseline_source_commit": "a26b72f",
+    "production_files_changed_in_baseline": 0,
+    "runs_per_configuration": 1,
+    "world": "fresh ignored development world per run",
+    "workload": "289 synchronous FULL chunks in concentric rings around natural spawn, then 80 FULL chunks in an eastward corridor. Minecraft world creation timed separately from startup log.",
+    "scope": "Server generation up to FULL. Does not establish ticking readiness, postprocessing completion, client rendering, FPS, multiplayer capacity or a guaranteed user loading time.",
+    "baseline_scope_correction": "The raw alpha.10 report incorrectly says postprocessing is included; FULL alone does not guarantee this. Workload code is identical; alpha.11 corrects only that explanatory string.",
+    "build_time_excluded": true,
+    "comparison": "Only legacy20 versus legacy20 measures the algorithm gain. Grand10 changes geometry; its exploration timing cannot be used for that comparison.",
+    "frozen_runtime_files": 272,
+    "frozen_runtime_manifest_sha256": "1c2b433417a5d9e6a219e9ee19781574538d2167c774e14ed2bf254d277d4482",
+    "baseline_runtime_manifest_sha256": "d4860072d1896f0dfd784a5876f1253367b7818a2023f1910ba1612b6f0e7103",
+    "benchmark_source_sha256": "408711c97d65de63af4e0a1eac90e6edb5bf2df2b70c43772a3fdef7347d75d1"
+  },
+  "runs": {
+    "alpha10_legacy20": {
+      "version": "0.1.0-alpha.10",
+      "players": 20,
+      "seed": 0,
+      "spawn": [
+        0,
+        252,
+        0
+      ],
+      "java": "25.0.3",
+      "processors": 8,
+      "max_heap_bytes": 2147483648,
+      "spawn_area_ms": 310664.163542,
+      "spawn_area_full_chunks": 289,
+      "spawn_area_nonempty_chunks": 289,
+      "rings": [
+        {
+          "elapsed_ms": 2.609,
+          "cumulative_chunks": 1,
+          "radius": 0
+        },
+        {
+          "elapsed_ms": 5468.709333,
+          "cumulative_chunks": 9,
+          "radius": 1
+        },
+        {
+          "elapsed_ms": 17601.560917,
+          "cumulative_chunks": 25,
+          "radius": 2
+        },
+        {
+          "elapsed_ms": 27397.566458,
+          "cumulative_chunks": 49,
+          "radius": 3
+        },
+        {
+          "elapsed_ms": 36562.853333,
+          "cumulative_chunks": 81,
+          "radius": 4
+        },
+        {
+          "elapsed_ms": 44462.775334,
+          "cumulative_chunks": 121,
+          "radius": 5
+        },
+        {
+          "elapsed_ms": 52423.80275,
+          "cumulative_chunks": 169,
+          "radius": 6
+        },
+        {
+          "elapsed_ms": 60416.705916,
+          "cumulative_chunks": 225,
+          "radius": 7
+        },
+        {
+          "elapsed_ms": 66303.128125,
+          "cumulative_chunks": 289,
+          "radius": 8
+        }
+      ],
+      "spawn_area_chunk_latency_ms": {
+        "median": 993.3335,
+        "p95": 1392.158958,
+        "max": 2560.16575
+      },
+      "exploration_ms": 103141.834334,
+      "exploration_full_chunks": 80,
+      "exploration_steps": [
+        {
+          "elapsed_ms": 5146.88675,
+          "chunk_x": 9
+        },
+        {
+          "elapsed_ms": 5087.495583,
+          "chunk_x": 10
+        },
+        {
+          "elapsed_ms": 5229.782834,
+          "chunk_x": 11
+        },
+        {
+          "elapsed_ms": 5046.559,
+          "chunk_x": 12
+        },
+        {
+          "elapsed_ms": 4810.5415,
+          "chunk_x": 13
+        },
+        {
+          "elapsed_ms": 28755.95025,
+          "chunk_x": 14
+        },
+        {
+          "elapsed_ms": 4763.415834,
+          "chunk_x": 15
+        },
+        {
+          "elapsed_ms": 4772.209166,
+          "chunk_x": 16
+        },
+        {
+          "elapsed_ms": 4826.460208,
+          "chunk_x": 17
+        },
+        {
+          "elapsed_ms": 4857.054416,
+          "chunk_x": 18
+        },
+        {
+          "elapsed_ms": 4947.188167,
+          "chunk_x": 19
+        },
+        {
+          "elapsed_ms": 5168.714916,
+          "chunk_x": 20
+        },
+        {
+          "elapsed_ms": 4897.048167,
+          "chunk_x": 21
+        },
+        {
+          "elapsed_ms": 5286.23025,
+          "chunk_x": 22
+        },
+        {
+          "elapsed_ms": 4865.694458,
+          "chunk_x": 23
+        },
+        {
+          "elapsed_ms": 4661.793875,
+          "chunk_x": 24
+        }
+      ],
+      "exploration_chunk_latency_ms": {
+        "median": 925.461875,
+        "p95": 1273.829625,
+        "max": 25131.068417
+      },
+      "regions_cached": 2,
+      "passed": true,
+      "world_creation_ms": 96766,
+      "world_creation_plus_spawn_area_ms": 407430.163542,
+      "raw_report_sha256": "d70c4ac49f37470d4db15b9200e26da8ac9d4d3b1b008e7ec03e67deafcc0f93",
+      "log_sha256": "5b1df55f7a167003c089e80fe1fb824d087c137e3662bac84af3ae0b325b8392"
+    },
+    "alpha11_legacy20": {
+      "version": "0.1.0-alpha.11",
+      "players": 20,
+      "seed": 0,
+      "spawn": [
+        0,
+        252,
+        0
+      ],
+      "java": "25.0.3",
+      "processors": 8,
+      "max_heap_bytes": 2147483648,
+      "spawn_area_ms": 43647.054375,
+      "spawn_area_full_chunks": 289,
+      "spawn_area_nonempty_chunks": 289,
+      "rings": [
+        {
+          "cumulative_chunks": 1,
+          "elapsed_ms": 1.965667,
+          "radius": 0
+        },
+        {
+          "cumulative_chunks": 9,
+          "elapsed_ms": 870.4725,
+          "radius": 1
+        },
+        {
+          "cumulative_chunks": 25,
+          "elapsed_ms": 2972.902334,
+          "radius": 2
+        },
+        {
+          "cumulative_chunks": 49,
+          "elapsed_ms": 4480.355667,
+          "radius": 3
+        },
+        {
+          "cumulative_chunks": 81,
+          "elapsed_ms": 5120.230375,
+          "radius": 4
+        },
+        {
+          "cumulative_chunks": 121,
+          "elapsed_ms": 6290.425208,
+          "radius": 5
+        },
+        {
+          "cumulative_chunks": 169,
+          "elapsed_ms": 7381.384417,
+          "radius": 6
+        },
+        {
+          "cumulative_chunks": 225,
+          "elapsed_ms": 7839.425333,
+          "radius": 7
+        },
+        {
+          "cumulative_chunks": 289,
+          "elapsed_ms": 8677.269209,
+          "radius": 8
+        }
+      ],
+      "spawn_area_chunk_latency_ms": {
+        "p95": 280.6,
+        "median": 135.289625,
+        "max": 699.612708
+      },
+      "exploration_ms": 14051.250167,
+      "exploration_full_chunks": 80,
+      "exploration_steps": [
+        {
+          "chunk_x": 9,
+          "elapsed_ms": 750.152875
+        },
+        {
+          "chunk_x": 10,
+          "elapsed_ms": 680.650584
+        },
+        {
+          "chunk_x": 11,
+          "elapsed_ms": 729.180958
+        },
+        {
+          "chunk_x": 12,
+          "elapsed_ms": 725.223
+        },
+        {
+          "chunk_x": 13,
+          "elapsed_ms": 540.200125
+        },
+        {
+          "chunk_x": 14,
+          "elapsed_ms": 5554.177667
+        },
+        {
+          "chunk_x": 15,
+          "elapsed_ms": 473.982208
+        },
+        {
+          "chunk_x": 16,
+          "elapsed_ms": 471.05575
+        },
+        {
+          "chunk_x": 17,
+          "elapsed_ms": 513.109667
+        },
+        {
+          "chunk_x": 18,
+          "elapsed_ms": 533.284292
+        },
+        {
+          "chunk_x": 19,
+          "elapsed_ms": 503.983917
+        },
+        {
+          "chunk_x": 20,
+          "elapsed_ms": 513.126292
+        },
+        {
+          "chunk_x": 21,
+          "elapsed_ms": 508.7555
+        },
+        {
+          "chunk_x": 22,
+          "elapsed_ms": 587.331416
+        },
+        {
+          "chunk_x": 23,
+          "elapsed_ms": 467.628834
+        },
+        {
+          "chunk_x": 24,
+          "elapsed_ms": 494.771375
+        }
+      ],
+      "exploration_chunk_latency_ms": {
+        "p95": 186.482333,
+        "median": 103.648708,
+        "max": 5153.6295
+      },
+      "regions_cached": 2,
+      "passed": true,
+      "world_creation_ms": 18888,
+      "world_creation_plus_spawn_area_ms": 62535.054375,
+      "raw_report_sha256": "4799180bd61ec4ffc93d6a1a7ccb5440eb880f7dc08a345429b77db10cc17ab0",
+      "log_sha256": "a9347297608528e719d6780f3dd2f2588bb516e06ab771ca6da6ffdda404f7a4"
+    },
+    "alpha11_grand10": {
+      "version": "0.1.0-alpha.11",
+      "players": 10,
+      "seed": 0,
+      "spawn": [
+        0,
+        252,
+        0
+      ],
+      "java": "25.0.3",
+      "processors": 8,
+      "max_heap_bytes": 2147483648,
+      "spawn_area_ms": 44291.159875,
+      "spawn_area_full_chunks": 289,
+      "spawn_area_nonempty_chunks": 289,
+      "rings": [
+        {
+          "radius": 0,
+          "cumulative_chunks": 1,
+          "elapsed_ms": 42.387459
+        },
+        {
+          "radius": 1,
+          "cumulative_chunks": 9,
+          "elapsed_ms": 1474.290584
+        },
+        {
+          "radius": 2,
+          "cumulative_chunks": 25,
+          "elapsed_ms": 3180.279791
+        },
+        {
+          "radius": 3,
+          "cumulative_chunks": 49,
+          "elapsed_ms": 4474.062208
+        },
+        {
+          "radius": 4,
+          "cumulative_chunks": 81,
+          "elapsed_ms": 5043.704042
+        },
+        {
+          "radius": 5,
+          "cumulative_chunks": 121,
+          "elapsed_ms": 6367.417708
+        },
+        {
+          "radius": 6,
+          "cumulative_chunks": 169,
+          "elapsed_ms": 7285.252542
+        },
+        {
+          "radius": 7,
+          "cumulative_chunks": 225,
+          "elapsed_ms": 7824.965875
+        },
+        {
+          "radius": 8,
+          "cumulative_chunks": 289,
+          "elapsed_ms": 8577.641208
+        }
+      ],
+      "spawn_area_chunk_latency_ms": {
+        "max": 665.612875,
+        "p95": 274.9215,
+        "median": 136.067375
+      },
+      "exploration_ms": 7684.81575,
+      "exploration_full_chunks": 80,
+      "exploration_steps": [
+        {
+          "elapsed_ms": 739.863,
+          "chunk_x": 9
+        },
+        {
+          "elapsed_ms": 724.49625,
+          "chunk_x": 10
+        },
+        {
+          "elapsed_ms": 720.754584,
+          "chunk_x": 11
+        },
+        {
+          "elapsed_ms": 695.608958,
+          "chunk_x": 12
+        },
+        {
+          "elapsed_ms": 522.1695,
+          "chunk_x": 13
+        },
+        {
+          "elapsed_ms": 1112.798042,
+          "chunk_x": 14
+        },
+        {
+          "elapsed_ms": 430.820667,
+          "chunk_x": 15
+        },
+        {
+          "elapsed_ms": 416.082834,
+          "chunk_x": 16
+        },
+        {
+          "elapsed_ms": 400.90425,
+          "chunk_x": 17
+        },
+        {
+          "elapsed_ms": 414.387708,
+          "chunk_x": 18
+        },
+        {
+          "elapsed_ms": 394.878458,
+          "chunk_x": 19
+        },
+        {
+          "elapsed_ms": 393.643834,
+          "chunk_x": 20
+        },
+        {
+          "elapsed_ms": 391.553625,
+          "chunk_x": 21
+        },
+        {
+          "elapsed_ms": 279.306334,
+          "chunk_x": 22
+        },
+        {
+          "elapsed_ms": 25.634541,
+          "chunk_x": 23
+        },
+        {
+          "elapsed_ms": 18.210167,
+          "chunk_x": 24
+        }
+      ],
+      "exploration_chunk_latency_ms": {
+        "max": 760.323917,
+        "p95": 198.353916,
+        "median": 85.88425
+      },
+      "regions_cached": 2,
+      "passed": true,
+      "world_creation_ms": 18376,
+      "world_creation_plus_spawn_area_ms": 62667.159875,
+      "raw_report_sha256": "5284e0ef88217f01d51f9040bf13f652de8276dc3f9844dc14569848b227d05a",
+      "log_sha256": "3a4c84bb6ea1614f8fc9c85f472612750149996e2f7658c83afe398b43afe5f6"
+    }
+  },
+  "same_geometry_reduction_percent": {
+    "world_creation_plus_spawn_area_ms": 84.65134396742975,
+    "spawn_area_ms": 85.95040577665497,
+    "exploration_ms": 86.37676917641545
+  },
+  "targets": {
+    "minimum_reduction_percent": 30,
+    "grand_creation_plus_spawn_area_max_ms": 120000,
+    "same_geometry_reduction_passed": true,
+    "grand_generation_proxy_passed": true
+  },
+  "density_equivalence": {
+    "comparison": "Float.floatToRawIntBits; no tolerance",
+    "reference_commit": "a26b72f",
+    "scope": "Real compiled scalar/bulk densities, 4 capacities x 3 seeds (5/20/100 compatibility and new10 using the same parameterized algorithm), signed coordinates, region/coast/height boundaries, context switches and concurrency; no block changes",
+    "reference_source_sha256": "fcc5a8a39b7c4d181d74ce4f9183a1ca93646137955ac64bab9d22e6db0752a1",
+    "profiles": [
+      {
+        "seed": 0,
+        "bitwise_comparisons": 255678,
+        "players": 5,
+        "optimized_path_supported": true,
+        "reference_density_digest": "28ec59cba36174fd"
+      },
+      {
+        "seed": 42,
+        "bitwise_comparisons": 255678,
+        "players": 5,
+        "optimized_path_supported": true,
+        "reference_density_digest": "efd1e8084800ed5c"
+      },
+      {
+        "seed": 8675309,
+        "bitwise_comparisons": 255678,
+        "players": 5,
+        "optimized_path_supported": true,
+        "reference_density_digest": "91bea1db755d9aca"
+      },
+      {
+        "seed": 0,
+        "bitwise_comparisons": 255678,
+        "players": 10,
+        "optimized_path_supported": true,
+        "reference_density_digest": "b7bab667baf73361"
+      },
+      {
+        "seed": 42,
+        "bitwise_comparisons": 255678,
+        "players": 10,
+        "optimized_path_supported": true,
+        "reference_density_digest": "42aeaf160360e41c"
+      },
+      {
+        "seed": 8675309,
+        "bitwise_comparisons": 255678,
+        "players": 10,
+        "optimized_path_supported": true,
+        "reference_density_digest": "cb85f95333e040c0"
+      },
+      {
+        "seed": 0,
+        "bitwise_comparisons": 255678,
+        "players": 20,
+        "optimized_path_supported": true,
+        "reference_density_digest": "175524360755dd88"
+      },
+      {
+        "seed": 42,
+        "bitwise_comparisons": 255678,
+        "players": 20,
+        "optimized_path_supported": true,
+        "reference_density_digest": "4cc8aec467a2d164"
+      },
+      {
+        "seed": 8675309,
+        "bitwise_comparisons": 255678,
+        "players": 20,
+        "optimized_path_supported": true,
+        "reference_density_digest": "5a3f16e426e5a64e"
+      },
+      {
+        "seed": 0,
+        "bitwise_comparisons": 255678,
+        "players": 100,
+        "optimized_path_supported": true,
+        "reference_density_digest": "83cda17336772fa7"
+      },
+      {
+        "seed": 42,
+        "bitwise_comparisons": 255678,
+        "players": 100,
+        "optimized_path_supported": true,
+        "reference_density_digest": "e7aa7f52022cc6aa"
+      },
+      {
+        "seed": 8675309,
+        "bitwise_comparisons": 255678,
+        "players": 100,
+        "optimized_path_supported": true,
+        "reference_density_digest": "de4b8f52d249a9bd"
+      }
+    ],
+    "concurrent_workers": 3,
+    "concurrent_comparisons": 115668,
+    "passed": true,
+    "adversarial": {
+      "aligned_scalar_path_preserved": true,
+      "passed": true,
+      "bitwise_comparisons": 122528,
+      "concurrent_workers": 3,
+      "repeated_cell_corner_batches": 1
+    }
+  },
+  "persistence": {
+    "default_players": 10,
+    "profiles": [
+      {
+        "restored_settings": "sanctuary:population_5",
+        "players": 5,
+        "disk_round_trip": true,
+        "preset": "sanctuary:sanctuary_5"
+      },
+      {
+        "restored_settings": "sanctuary:population_10",
+        "players": 10,
+        "disk_round_trip": true,
+        "preset": "sanctuary:sanctuary"
+      },
+      {
+        "restored_settings": "sanctuary:population_20",
+        "players": 20,
+        "disk_round_trip": true,
+        "preset": "sanctuary:sanctuary_20"
+      },
+      {
+        "restored_settings": "sanctuary:population_100",
+        "players": 100,
+        "disk_round_trip": true,
+        "preset": "sanctuary:sanctuary_100"
+      }
+    ],
+    "passed": true,
+    "visible_presets": [
+      "sanctuary:sanctuary_5",
+      "sanctuary:sanctuary"
+    ],
+    "seed": 0,
+    "legacy_settings_preserved": "sanctuary:sanctuary_cavern",
+    "omitted_density_capacity_preserved": 20
+  },
+  "limits": [
+    "Single seed and one timed run per configuration; repeat to estimate variance.",
+    "A new cold region still has a synchronous planning cost; observed legacy20 maximum exploration chunk latency is about 5.15 s.",
+    "No personal saved world was opened or regenerated."
+  ],
+  "engine_checks": {
+    "5": {
+      "mod_version": "0.1.0-alpha.11",
+      "seed": 0,
+      "settings": "sanctuary:population_5",
+      "inspected_full_chunks": 110,
+      "retained_water_blocks": 5656,
+      "fluid_ticks": 1800,
+      "tested_springs": 1,
+      "tested_spills": 1,
+      "tested_lava_falls": 1,
+      "postprocessing_reentry_witnesses": 3,
+      "passed": true,
+      "scope": "Selected basins, terraces, springs and ecology patches in explicit regions; no whole-island inventory or multiplayer load test",
+      "raw_report_sha256": "cfaa0a532b50399ab28808f51a871363b198a67d8c096ac13f7a011bd87ff9d0"
+    },
+    "10": {
+      "mod_version": "0.1.0-alpha.11",
+      "seed": 0,
+      "settings": "sanctuary:population_10",
+      "inspected_full_chunks": 125,
+      "retained_water_blocks": 5923,
+      "fluid_ticks": 1800,
+      "tested_springs": 1,
+      "tested_spills": 1,
+      "tested_lava_falls": 1,
+      "postprocessing_reentry_witnesses": 3,
+      "passed": true,
+      "scope": "Selected basins, terraces, springs and ecology patches in explicit regions; no whole-island inventory or multiplayer load test",
+      "raw_report_sha256": "aaed5b38821197c479a8acb7f2a201c64f290666c039d0b15047340e403e028c"
+    }
+  }
+}

docs/benchmarks/alpha12-expansion.json

@@ -0,0 +1,314 @@
+{
+  "version": "0.1.0-alpha.12",
+  "date": "2026-09-09",
+  "minecraft": "26.3-pre-2",
+  "java": 25,
+  "generation": 12,
+  "source_base_commit": "f816ffc6402fe31789f9677c2ee94328b3181329",
+  "scope": "Local development tests only; no personal worlds, client rendering, live player teleport or multiplayer load.",
+  "normalization": "world_directory fields replaced with <development_game_test_world>; all other diagnostic fields retained.",
+  "artifact": {
+    "path": "mods/sanctuary/build/libs/sanctuary-0.1.0-alpha.12.jar",
+    "sha256": "f2ac2462a03a39ef330cc52143f9753ac5908b606cfe1dd1388ad5caae15e6e9",
+    "staged_pack_jar_identical": true,
+    "contains_gametest_classes": false
+  },
+  "build": {
+    "command": "./gradlew check build assemblePack",
+    "passed": true,
+    "legacy_profile": 10,
+    "legacy_seed": 0,
+    "required_engine_tests": 12,
+    "fluid_ticks": 1800,
+    "log_sha256": "dfedc75558596ce4413bd0466ec03645b2fa6853165510e9b8db0406d0958eb8"
+  },
+  "first_process_diagnostic_sha256": "90872c801cb04e3f0c78b47e0d38a0b45dd5d3e6d1e33ccc53c4359e4b407238",
+  "reload_diagnostic_sha256": "1efe055e1179ce60741a0d8546618807fc136c0de77f9aff6a979cf88b2b1cdd",
+  "fresh_world": {
+    "seed": 42,
+    "process_id": 2892,
+    "generator_version": 12,
+    "islands": [
+      {
+        "upper_biome": "minecraft:jungle",
+        "climate": "tropical",
+        "landing": [
+          0,
+          202,
+          -800
+        ],
+        "landing_biome": "minecraft:jungle",
+        "parent": "sanctuary",
+        "id": "alpha",
+        "centre": [
+          0,
+          -800
+        ],
+        "diameter": 64
+      },
+      {
+        "upper_biome": "minecraft:desert",
+        "climate": "arid",
+        "landing": [
+          544,
+          198,
+          -800
+        ],
+        "landing_biome": "minecraft:desert",
+        "parent": "alpha",
+        "id": "beta",
+        "centre": [
+          544,
+          -800
+        ],
+        "diameter": 64
+      }
+    ],
+    "scope": "Fresh laboratory world; real FULL chunks and native structure loot, asynchronous activation, branching, journal re-read and loaded void admission refusal. Journal re-read is not a process restart. The parent block witness represents a player edit; no player teleport, multiplayer or client rendering is simulated.",
+    "registered_command_permission_checks": true,
+    "parent_witness": [
+      -16,
+      248,
+      -16
+    ],
+    "root_landing": [
+      -16,
+      242,
+      -16
+    ],
+    "journal_reloaded_regions": 3,
+    "visited_void_refusal": {
+      "chunk": [
+        -50,
+        50
+      ],
+      "reason": "Expansion intersects a loaded or unloading chunk: [-61, 39]"
+    },
+    "native_structure": {
+      "full_chunks": 12,
+      "placed_block": "Block{minecraft:barrel}[facing=south,open=false]",
+      "structure": "minecraft:abandoned_camp_forest",
+      "mode": "natural candidate accepted by production ExpansionStructures, native decoration",
+      "container": [
+        28,
+        247,
+        73
+      ],
+      "loot_table": "minecraft:barrels/abandoned_camp_barrel"
+    },
+    "restart_snapshot": {
+      "world_directory": "<development_game_test_world>",
+      "gold_witness": [
+        544,
+        204,
+        -800
+      ],
+      "journal_sha256": "d7de79838744624e98ce26997ddc1daecb7bd3334bd9bf0e1ad31aa5eb7e27c3",
+      "islands": [
+        {
+          "id": "sanctuary",
+          "parent": "sanctuary",
+          "direction": "north",
+          "climate": "temperate",
+          "diameter": 512,
+          "center_x": 0,
+          "center_z": 0,
+          "seed": 42,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        },
+        {
+          "id": "alpha",
+          "parent": "sanctuary",
+          "direction": "north",
+          "climate": "tropical",
+          "diameter": 64,
+          "center_x": 0,
+          "center_z": -800,
+          "seed": 390175152143173586,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        },
+        {
+          "id": "beta",
+          "parent": "alpha",
+          "direction": "east",
+          "climate": "arid",
+          "diameter": 64,
+          "center_x": 544,
+          "center_z": -800,
+          "seed": 6281303726624369227,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        }
+      ],
+      "generator_codec": {
+        "biome_source": {
+          "biomes": [
+            "minecraft:the_void",
+            "minecraft:forest",
+            "minecraft:birch_forest",
+            "minecraft:flower_forest",
+            "minecraft:plains",
+            "minecraft:meadow",
+            "minecraft:taiga",
+            "minecraft:snowy_taiga",
+            "minecraft:snowy_plains",
+            "minecraft:grove",
+            "minecraft:ice_spikes",
+            "minecraft:frozen_peaks",
+            "minecraft:old_growth_spruce_taiga",
+            "minecraft:dark_forest",
+            "minecraft:swamp",
+            "minecraft:pale_garden",
+            "minecraft:jungle",
+            "minecraft:sparse_jungle",
+            "minecraft:bamboo_jungle",
+            "minecraft:mangrove_swamp",
+            "minecraft:savanna",
+            "minecraft:savanna_plateau",
+            "minecraft:desert",
+            "minecraft:badlands",
+            "minecraft:eroded_badlands",
+            "minecraft:wooded_badlands",
+            "minecraft:windswept_hills",
+            "minecraft:windswept_gravelly_hills",
+            "minecraft:stony_peaks",
+            "minecraft:dappled_forest",
+            "minecraft:cherry_grove",
+            "minecraft:lush_caves",
+            "minecraft:dripstone_caves",
+            "minecraft:sulfur_caves"
+          ]
+        },
+        "type": "sanctuary:expansion_lab"
+      },
+      "samples": [
+        {
+          "stored_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+          "point": [
+            -16,
+            242,
+            -16
+          ],
+          "id": "sanctuary",
+          "stored_column_sha256": "a291039b2ed502c828b4f1ec97fe111f49f62e69b5589e05116d9b1931f461a4",
+          "resolved_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+          "base_column_sha256": "646af3da3a327ab15d229b7fe2c328cc10eae7fce31d6b24c60f3be643bc1095",
+          "base_height": 242
+        },
+        {
+          "stored_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+          "point": [
+            0,
+            202,
+            -800
+          ],
+          "id": "alpha",
+          "stored_column_sha256": "0debd009e711898fe64573f31a77f03f03d680be7398918b126004fcee3cfb1c",
+          "resolved_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+          "base_column_sha256": "9269110205d64e1f72d9c44591a825d66fff3a4278fb835e5b4f2627b01a1db5",
+          "base_height": 202
+        },
+        {
+          "stored_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+          "point": [
+            544,
+            198,
+            -800
+          ],
+          "id": "beta",
+          "stored_column_sha256": "73f7b445475a80b951f05d0c5fb6fd2eca2cf7519cd6ac5d64c7fe9dac53fa23",
+          "resolved_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+          "base_column_sha256": "4df3dd476f41a8c6b0e0273b9ebe5cbba4dec6cb22001c553c15d4f6b255c555",
+          "base_height": 198
+        }
+      ],
+      "world_flushed_before_shutdown": true
+    },
+    "native_structure_starts_seen": 1,
+    "structure_start_chunks_inspected": 106,
+    "ticks": 1390,
+    "elapsed_ms": 43123.278916,
+    "passed": true
+  },
+  "reloaded_world": {
+    "seed": 42,
+    "process_id": 2975,
+    "scope": "A second Java process opens the same saved development chunks and expansion journal, and verifies a gold block written and flushed before the first shutdown. GameTestServer reconstructs its world settings from the preset; the prior generator codec is decoded separately here and its base columns are compared. This is not a normal-client world-selection test or a multiplayer/teleportation test.",
+    "previous_process_id": 2892,
+    "world_directory": "<development_game_test_world>",
+    "gold_witness": [
+      544,
+      204,
+      -800
+    ],
+    "samples": [
+      {
+        "point": [
+          -16,
+          242,
+          -16
+        ],
+        "id": "sanctuary",
+        "stored_column_sha256": "a291039b2ed502c828b4f1ec97fe111f49f62e69b5589e05116d9b1931f461a4",
+        "resolved_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+        "base_column_sha256": "646af3da3a327ab15d229b7fe2c328cc10eae7fce31d6b24c60f3be643bc1095",
+        "base_height": 242,
+        "stored_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485"
+      },
+      {
+        "point": [
+          0,
+          202,
+          -800
+        ],
+        "id": "alpha",
+        "stored_column_sha256": "0debd009e711898fe64573f31a77f03f03d680be7398918b126004fcee3cfb1c",
+        "resolved_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+        "base_column_sha256": "9269110205d64e1f72d9c44591a825d66fff3a4278fb835e5b4f2627b01a1db5",
+        "base_height": 202,
+        "stored_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b"
+      },
+      {
+        "point": [
+          544,
+          198,
+          -800
+        ],
+        "id": "beta",
+        "stored_column_sha256": "73f7b445475a80b951f05d0c5fb6fd2eca2cf7519cd6ac5d64c7fe9dac53fa23",
+        "resolved_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+        "base_column_sha256": "4df3dd476f41a8c6b0e0273b9ebe5cbba4dec6cb22001c553c15d4f6b255c555",
+        "base_height": 198,
+        "stored_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60"
+      }
+    ],
+    "regions": 3,
+    "native_container": [
+      28,
+      247,
+      73
+    ],
+    "saved_generator_codec_decoded": true,
+    "passed": true
+  },
+  "earlier_seed_0_attempt": {
+    "scope": "Earlier development run before final cache and error-message fixes. Expansion phases completed; positive loot witness failed.",
+    "native_candidate_sites": 11,
+    "no_surface": 9,
+    "insufficient_foundation": 2,
+    "accepted_structures": 0,
+    "structure_proof_passed": false
+  },
+  "unverified": [
+    "Forced crash during chunk preparation",
+    "Normal client world selection and rendering",
+    "Real player teleports and multiplayer",
+    "Visual quality of every climate/relief and 128/256/512 formats",
+    "Every village and temple variant"
+  ]
+}

docs/benchmarks/alpha121-expansion.json

@@ -0,0 +1,408 @@
+{
+  "version": "0.1.0-alpha.12.1",
+  "date": "2026-09-09",
+  "minecraft": "26.3-pre-2",
+  "java": 25,
+  "generation": 12,
+  "journal_schema": 1,
+  "base_commit": "40a86588b5f83fbc7bd2728eb9b439baa1fc9ba5",
+  "scope": "Development-world engine tests; no personal world, live player teleportation or client rendering. Process timings are not performance benchmarks.",
+  "normalization": "world_directory fields replaced with <development_game_test_world>; other diagnostic fields unchanged.",
+  "build": {
+    "command": "./gradlew check build assemblePack",
+    "passed": true,
+    "required_historical_engine_tests": 12,
+    "seed": 0,
+    "profile": 10,
+    "log_sha256": "72f2173023e5407391d7e0e528012fcda9a314c981acfea462918c36ffa7bf90"
+  },
+  "artifact": {
+    "path": "mods/sanctuary/build/libs/sanctuary-0.1.0-alpha.12.1.jar",
+    "sha256": "c9df4da956cfa54581b3fde21de006bf8ac3ec025b8dd0daa5d060bcb70aabd4"
+  },
+  "first_process_diagnostic_sha256": "3ef35faf09130409135879ad3a4be4ceba4f5644a57ae9cdcec4cd4d6e84c06a",
+  "reload_diagnostic_sha256": "401f2e6739de9efd3668aa27c5ef45a6e81e1acfde44442bf101e5ac6397074a",
+  "fresh_world": {
+    "seed": 42,
+    "process_id": 5743,
+    "generator_version": 12,
+    "islands": [
+      {
+        "centre": [
+          0,
+          -1600
+        ],
+        "diameter": 64,
+        "upper_biome": "minecraft:jungle",
+        "climate": "tropical",
+        "landing": [
+          -4,
+          171,
+          -1604
+        ],
+        "landing_biome": "minecraft:jungle",
+        "parent": "sanctuary",
+        "id": "alpha"
+      },
+      {
+        "centre": [
+          2048,
+          -1600
+        ],
+        "diameter": 64,
+        "upper_biome": "minecraft:desert",
+        "climate": "arid",
+        "landing": [
+          2048,
+          198,
+          -1600
+        ],
+        "landing_biome": "minecraft:desert",
+        "parent": "alpha",
+        "id": "beta"
+      }
+    ],
+    "scope": "Fresh laboratory world; real FULL chunks and native structure loot, asynchronous activation, branching, journal re-read and loaded void admission refusal. Journal re-read is not a process restart. The parent block witness represents a player edit; no player teleport, multiplayer or client rendering is simulated.",
+    "registered_command_permission_checks": true,
+    "parent_witness": [
+      -16,
+      248,
+      -16
+    ],
+    "root_landing": [
+      -16,
+      242,
+      -16
+    ],
+    "initial_occupied_directions": 8,
+    "journal_reloaded_regions": 3,
+    "native_structure": {
+      "container": [
+        28,
+        247,
+        73
+      ],
+      "loot_table": "minecraft:barrels/abandoned_camp_barrel",
+      "full_chunks": 12,
+      "placed_block": "Block{minecraft:barrel}[facing=south,open=false]",
+      "structure": "minecraft:abandoned_camp_forest",
+      "mode": "natural candidate accepted by production ExpansionStructures, native decoration"
+    },
+    "restart_snapshot": {
+      "world_directory": "<development_game_test_world>",
+      "gold_witness": [
+        2048,
+        204,
+        -1600
+      ],
+      "journal_sha256": "21136a5e8f1857b10ef5673281c8a3a4568ae032641995c206ed2031e112aa5b",
+      "islands": [
+        {
+          "id": "sanctuary",
+          "parent": "sanctuary",
+          "direction": "north",
+          "climate": "temperate",
+          "diameter": 512,
+          "center_x": 0,
+          "center_z": 0,
+          "seed": 42,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        },
+        {
+          "id": "alpha",
+          "parent": "sanctuary",
+          "direction": "north",
+          "climate": "tropical",
+          "diameter": 64,
+          "center_x": 0,
+          "center_z": -1600,
+          "seed": 390175152143173586,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        },
+        {
+          "id": "beta",
+          "parent": "alpha",
+          "direction": "east",
+          "climate": "arid",
+          "diameter": 64,
+          "center_x": 2048,
+          "center_z": -1600,
+          "seed": 6281303726624369227,
+          "relief": "natural",
+          "status": "ready",
+          "generation": 12
+        }
+      ],
+      "generator_codec": {
+        "biome_source": {
+          "biomes": [
+            "minecraft:the_void",
+            "minecraft:forest",
+            "minecraft:birch_forest",
+            "minecraft:flower_forest",
+            "minecraft:plains",
+            "minecraft:meadow",
+            "minecraft:taiga",
+            "minecraft:snowy_taiga",
+            "minecraft:snowy_plains",
+            "minecraft:grove",
+            "minecraft:ice_spikes",
+            "minecraft:frozen_peaks",
+            "minecraft:old_growth_spruce_taiga",
+            "minecraft:dark_forest",
+            "minecraft:swamp",
+            "minecraft:pale_garden",
+            "minecraft:jungle",
+            "minecraft:sparse_jungle",
+            "minecraft:bamboo_jungle",
+            "minecraft:mangrove_swamp",
+            "minecraft:savanna",
+            "minecraft:savanna_plateau",
+            "minecraft:desert",
+            "minecraft:badlands",
+            "minecraft:eroded_badlands",
+            "minecraft:wooded_badlands",
+            "minecraft:windswept_hills",
+            "minecraft:windswept_gravelly_hills",
+            "minecraft:stony_peaks",
+            "minecraft:dappled_forest",
+            "minecraft:cherry_grove",
+            "minecraft:lush_caves",
+            "minecraft:dripstone_caves",
+            "minecraft:sulfur_caves"
+          ]
+        },
+        "type": "sanctuary:expansion_lab"
+      },
+      "blocked_sites": [
+        {
+          "id": "blocked_north",
+          "parent": "sanctuary",
+          "direction": "north",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": 0,
+          "center_z": -800,
+          "seed": 6170446579001265223,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_northeast",
+          "parent": "sanctuary",
+          "direction": "northeast",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": 800,
+          "center_z": -800,
+          "seed": 2312608842580142629,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_east",
+          "parent": "sanctuary",
+          "direction": "east",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": 800,
+          "center_z": 0,
+          "seed": -5785143794938635053,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_southeast",
+          "parent": "sanctuary",
+          "direction": "southeast",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": 800,
+          "center_z": 800,
+          "seed": 6543995692374257629,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_south",
+          "parent": "sanctuary",
+          "direction": "south",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": 0,
+          "center_z": 800,
+          "seed": 9109857537375437182,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_southwest",
+          "parent": "sanctuary",
+          "direction": "southwest",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": -800,
+          "center_z": 800,
+          "seed": 7977138842745944844,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_west",
+          "parent": "sanctuary",
+          "direction": "west",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": -800,
+          "center_z": 0,
+          "seed": 8731833603567083481,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        },
+        {
+          "id": "blocked_northwest",
+          "parent": "sanctuary",
+          "direction": "northwest",
+          "climate": "boreal",
+          "diameter": 64,
+          "center_x": -800,
+          "center_z": -800,
+          "seed": 6470159394492078415,
+          "relief": "natural",
+          "status": "reserved",
+          "generation": 12
+        }
+      ],
+      "samples": [
+        {
+          "resolved_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+          "base_column_sha256": "646af3da3a327ab15d229b7fe2c328cc10eae7fce31d6b24c60f3be643bc1095",
+          "base_height": 242,
+          "stored_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+          "point": [
+            -16,
+            242,
+            -16
+          ],
+          "id": "sanctuary",
+          "stored_column_sha256": "a291039b2ed502c828b4f1ec97fe111f49f62e69b5589e05116d9b1931f461a4"
+        },
+        {
+          "resolved_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+          "base_column_sha256": "4ec4238d357426e34a1decfd817fc96c6b596758e98ffc1d98906a1db8d5b707",
+          "base_height": 204,
+          "stored_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+          "point": [
+            -4,
+            171,
+            -1604
+          ],
+          "id": "alpha",
+          "stored_column_sha256": "9866d275b53719e434d20996e2c061f4342e431c41d671216781d1f00c204ff1"
+        },
+        {
+          "resolved_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+          "base_column_sha256": "4df3dd476f41a8c6b0e0273b9ebe5cbba4dec6cb22001c553c15d4f6b255c555",
+          "base_height": 198,
+          "stored_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+          "point": [
+            2048,
+            198,
+            -1600
+          ],
+          "id": "beta",
+          "stored_column_sha256": "246bc9b1827effb58159dbc540c655f2d218079a49263d19ac786cf116557093"
+        }
+      ],
+      "world_flushed_before_shutdown": true
+    },
+    "native_structure_starts_seen": 1,
+    "structure_start_chunks_inspected": 106,
+    "ticks": 1470,
+    "elapsed_ms": 41563.165541,
+    "passed": true
+  },
+  "reloaded_world": {
+    "seed": 42,
+    "process_id": 5830,
+    "scope": "A second Java process opens the same saved development chunks and expansion journal, and verifies a gold block written and flushed before the first shutdown. GameTestServer reconstructs its world settings from the preset; the prior generator codec is decoded separately here and its base columns are compared. This is not a normal-client world-selection test or a multiplayer/teleportation test.",
+    "saved_only_collision_refusals": 8,
+    "previous_process_id": 5743,
+    "world_directory": "<development_game_test_world>",
+    "gold_witness": [
+      2048,
+      204,
+      -1600
+    ],
+    "samples": [
+      {
+        "stored_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+        "point": [
+          -16,
+          242,
+          -16
+        ],
+        "id": "sanctuary",
+        "stored_column_sha256": "a291039b2ed502c828b4f1ec97fe111f49f62e69b5589e05116d9b1931f461a4",
+        "resolved_biomes_sha256": "65db6d2cde63dee7b60bc74aec702aae61f558c3878b8c8efaf0cc75d6066485",
+        "base_column_sha256": "646af3da3a327ab15d229b7fe2c328cc10eae7fce31d6b24c60f3be643bc1095",
+        "base_height": 242
+      },
+      {
+        "stored_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+        "point": [
+          -4,
+          171,
+          -1604
+        ],
+        "id": "alpha",
+        "stored_column_sha256": "9866d275b53719e434d20996e2c061f4342e431c41d671216781d1f00c204ff1",
+        "resolved_biomes_sha256": "dfda92ebd5677b8ea4fcd3b02ba029a898b22a8f640a71b520bab9783695eb1b",
+        "base_column_sha256": "4ec4238d357426e34a1decfd817fc96c6b596758e98ffc1d98906a1db8d5b707",
+        "base_height": 204
+      },
+      {
+        "stored_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+        "point": [
+          2048,
+          198,
+          -1600
+        ],
+        "id": "beta",
+        "stored_column_sha256": "246bc9b1827effb58159dbc540c655f2d218079a49263d19ac786cf116557093",
+        "resolved_biomes_sha256": "7233e9fb21f196866122679eec5cabf39d383b8a26fff0848ff6700d1c9fab60",
+        "base_column_sha256": "4df3dd476f41a8c6b0e0273b9ebe5cbba4dec6cb22001c553c15d4f6b255c555",
+        "base_height": 198
+      }
+    ],
+    "regions": 3,
+    "native_container": [
+      28,
+      247,
+      73
+    ],
+    "saved_generator_codec_decoded": true,
+    "after_reload_expansion": [
+      0,
+      1600
+    ],
+    "after_reload_landing": [
+      -4,
+      153,
+      1596
+    ],
+    "final_regions": 4,
+    "passed": true
+  }
+}

docs/benchmarks/alpha131-journal.json

@@ -0,0 +1,115 @@
+{
+  "version": "0.1.0-alpha.13.1",
+  "date": "2026-09-09",
+  "minecraft": "26.3-pre-2",
+  "java": 25,
+  "host_os": "macOS",
+  "windows_native_tested": false,
+  "windows_policy_tested_by_injection": true,
+  "journal_contracts": [
+    "Windows policy skips only directory channel",
+    "file force and atomic replacement and strict read-back remain required",
+    "supported directory AccessDenied propagates after replacement",
+    "failed session refuses further writes",
+    "verified reload recovers persisted reservation",
+    "post-replacement corruption fails closed"
+  ],
+  "jar_sha256": "b340dfc58f3d2d1a2a375dc527ac6721c61430600622046db26228e0da46061b",
+  "logs": {
+    "journal-smoke": {
+      "path": "build/alpha131-journal-smoke.log",
+      "sha256": "c02e94713cf3f9a3c76674700cc5c800aecd84b213b2be9ed53629f8eb9cd3d0",
+      "passed": true,
+      "required_game_tests": null
+    },
+    "check": {
+      "path": "build/alpha131-check.log",
+      "sha256": "68f6cb97e2f80669d39e37623076229e030a0d9826c13e9420f51f6ba23885bd",
+      "passed": true,
+      "required_game_tests": 8
+    },
+    "expansion-create": {
+      "path": "build/alpha131-expansion-create.log",
+      "sha256": "61fa4513aef71290a1419c3425a329047c8fe623a561544c6a8d916fe50e226c",
+      "passed": true,
+      "required_game_tests": 2
+    },
+    "expansion-reload": {
+      "path": "build/alpha131-expansion-reload.log",
+      "sha256": "44fafb4636ff90707a068f325a245dbf9820ccb1bdf785c912f7e636fe7cfa43",
+      "passed": true,
+      "required_game_tests": 2
+    }
+  },
+  "binary_comparison": {
+    "base_version": "0.1.0-alpha.13",
+    "version": "0.1.0-alpha.13.1",
+    "added": [
+      "fr/koka/sanctuary/expansion/ExpansionJournal$DirectorySync.class"
+    ],
+    "removed": [],
+    "changed": [
+      "fabric.mod.json",
+      "fr/koka/sanctuary/expansion/ExpansionJournal$1.class",
+      "fr/koka/sanctuary/expansion/ExpansionJournal.class"
+    ],
+    "synthetic_switch_instructions_identical": true,
+    "all_other_entries_identical": true
+  },
+  "expansion": {
+    "seed": 42,
+    "initial_diameter": 724,
+    "generation": 13,
+    "creation_process": 13148,
+    "reload_process": 13279,
+    "creation_passed": true,
+    "reload_passed": true,
+    "creation_islands": [
+      {
+        "landing_biome": "minecraft:jungle",
+        "landing": [
+          0,
+          202,
+          -1792
+        ],
+        "climate": "tropical",
+        "upper_biome": "minecraft:jungle",
+        "diameter": 64,
+        "centre": [
+          0,
+          -1792
+        ],
+        "id": "alpha",
+        "parent": "sanctuary"
+      },
+      {
+        "landing_biome": "minecraft:desert",
+        "landing": [
+          2048,
+          198,
+          -1792
+        ],
+        "climate": "arid",
+        "upper_biome": "minecraft:desert",
+        "diameter": 64,
+        "centre": [
+          2048,
+          -1792
+        ],
+        "id": "beta",
+        "parent": "alpha"
+      }
+    ],
+    "reloaded_regions": 3,
+    "saved_generator_codec_decoded": true,
+    "after_reload_expansion": [
+      0,
+      1792
+    ],
+    "final_regions": 4,
+    "native_structure_status": "not_observed_after_complete_scan",
+    "native_structure_witness_required": false,
+    "limitation": "Optional native camp witness absent after complete search on seed 42, as in alpha.13; no new structures claim."
+  },
+  "scope": "No generation or journal schema change. Test worlds only; no personal world opened or regenerated. Windows native runtime and power-loss durability not tested."
+}

docs/expansion.md

@@ -1,15 +1,53 @@
 # Climats, expansion et ressources
 
-Ce document fixe les décisions de conception pour la suite de Sanctuary. Le
-registre persistant des continents, leur déblocage et leur génération dans les
-huit directions restent à implémenter. Le relevé de ressources décrit plus bas
-est un outil de développement séparé, exécuté dans le monde jetable des GameTests.
+Ce document distingue les outils de génération et la progression collective
+encore à construire. L’alpha.13 réunit l’île de départ et
+les commandes d’expansion dans le choix public **Sanctuary**. Le
+[guide alpha.13](alpha13-worldgen.md) décrit leur utilisation. Les versions
+alpha.12/12.1 et leur [laboratoire](alpha12-laboratory.md) restent historiques.
+Le déblocage par recherches, XP et contributions n’est pas encore implémenté.
 
-## Les huit directions climatiques
+## Taille initiale et extensions — alpha.13
+
+Le bouton natif **Personnaliser** propose **Petit** (512 blocs de diamètre
+nominal), **Moyen** (724, par défaut) et **Grand** (1 024). La hauteur reste de
+384 blocs. Ce choix configure un nouveau monde ; il ne promet ni nombre de
+joueurs, ni quantité de ressources, ni aire entièrement constructible.
+
+L’île initiale reprend le relief, les forêts et l’hydrologie de Population,
+avec les poches de cavités natives issues du laboratoire. Les îles ajoutées
+conservent les tailles **64/128/256/512**, les douze profils climatiques et les
+quatre reliefs d’expansion. Leur génération ne reprend pas automatiquement
+la grande rivière et les terrasses de l’île initiale.
+
+Les commandes opérateur `quick`, `create`, `preview`, `list`, `visit` et
+`resume` reprennent le fonctionnement alpha.12.1. Le paramètre final de distance
+est facultatif ; les sites occupés sont écartés en cherchant plus loin dans la
+même direction. Même un chunk de vide déjà généré est protégé. Les recherches
+collectives et les objets de déblocage ne sont pas nécessaires à ces outils.
+
+La racine alpha.13 est de génération 13 ; les extensions restent de génération
+12, dans le journal `data/sanctuary-world-v13/expansions.json` du nouveau monde.
+Les anciens mondes gardent leurs codecs, leurs paramètres et leur journal.
+Les choix séparés Petit/Grand et Laboratoire sont désormais cachés à la
+création. Aucun monde existant n’est converti ou redimensionné.
+
+## Tailles et mesures historiques
+
+L’alpha.11 proposait Petit (512) et Grand (724), avec Grand par défaut ; ses
+repères internes 5/10 ne correspondaient pas à une capacité multijoueur promise.
+Les références `population_5/10/20/100` restent celles des sauvegardes historiques.
+Les mesures alpha.3 à alpha.11 conservées ci-dessous décrivent uniquement les
+versions et les emprises observées à leur date. Les contrôles de l’alpha.13,
+les rechargements et le benchmark Moyen sont consignés dans [Validation](testing.md).
+
+## Les huit directions et les branches climatiques
 
 Sanctuary Island constitue le point de départ **tempéré, légèrement humide**.
-Le nord conduit vers le froid, le sud vers le chaud, l'ouest vers le sec et
-l'est vers l'humide. Les diagonales combinent ces tendances.
+La boussole climatique est une convention facultative : nord froid, sud chaud,
+ouest sec et est humide. Les diagonales combinent ces tendances. **La direction
+géographique ne contraint plus le climat.** Les joueurs pourront choisir de
+prolonger une voie climatique ou de bifurquer vers d’autres découvertes.
 
 | Direction | Axe Minecraft depuis Sanctuary | Tendance climatique |
 | --- | --- | --- |
@@ -22,7 +60,11 @@ l'est vers l'humide. Les diagonales combinent ces tendances.
 | Ouest | `−X` | Sec |
 | Nord-ouest | `−X, −Z` | Froid et sec |
 
-Ces directions définissent des familles de climats, pas huit biomes uniformes.
+Ces associations sont les raccourcis par défaut, pas une loi du monde.
+Une branche conserve son parent, sa direction et son climat explicite. Plusieurs
+couronnes peuvent donc proposer des biomes nouveaux au nord comme au sud.
+Le point d’origine reste enregistré même si un joueur déplace son lit ou le spawn.
+Les familles de climats ne sont pas des biomes uniformes.
 Le relief, l'altitude, les variations locales et la graine doivent conserver
 des géographies distinctes à l'intérieur de chaque continent. Les amplitudes
 de température et d'humidité, leur évolution avec la distance et les seuils
@@ -30,18 +72,35 @@ de sélection des biomes feront partie du ticket de génération des continents.
 Les ressources et cultures futures, notamment celles d'It's Alive !, pourront
 ainsi demander l'exploration de plusieurs climats.
 
-L'île initiale utilise encore un biome de départ spécifique. Une température
-ou une humidité du biome ne constitue pas à elle seule une carte climatique
-directionnelle : cette carte et la sélection des biomes des continents restent
-des travaux distincts.
+L’alpha.5 proposait cinq biomes tempérés dont Dappled Forest. L’alpha.6 réserve
+ce dernier aux futurs continents et donne à l’île une palette plus douce de
+prairies, prairies fleuries, bosquets, corniches moussues et zones rocheuses.
+La répartition tient compte de l’altitude, y compris dans les strates inférieures.
+La variation locale et l’humidité dépendent de la graine ; elles ne
+constituent pas encore le champ de recherche directionnel des continents.
+
+L’alpha.7 densifie les forêts de chênes et de bouleaux en surface et donne
+aux corniches intérieures humides des chênes noirs et des champignons.
+Des champignons vanilla peuvent aussi se rencontrer en surface. Les
+clairières fleuries et les affleurements restent présents. Les essences rares
+et un éventuel arbre remarquable dépendent du terrain ; chaque graine n’est
+pas tenue de fournir tous les bois. Les minerais de départ peuvent affleurer,
+avec des petits filons et sans correction des stocks après comptage.
 
 ## Eau de surface et exploration
 
 L'île de départ doit pouvoir accueillir naturellement des étangs et lacs de
 surface, des berges propices à la canne à sucre et, lorsque le relief s'y prête,
 des rivières. L'eau s'inscrit dans les creux et les chemins du terrain existant.
-Les rivières flottantes et les cascades doivent tenir compte de la continuité
-de leur lit et du vide sous les îles.
+Les bassins gardent un fond et des berges fermés. Une grande rivière reste
+facultative : elle doit suivre le relief et former un parcours lisible avec
+source, chute et bassin. Ses exutoires peuvent laisser couler l’eau dans le vide.
+Sans parcours suffisamment long, l’île conserve seulement ses petits bassins.
+L’alpha.6 livre cette variante à bassins seuls ; la grande rivière reste à développer.
+L’alpha.5 ajoute séparément quelques sources sortant d’une niche rocheuse
+naturelle : leurs cascades peuvent descendre dans le vide et servir à remonter
+verticalement. Cet écoulement est volontaire ; il ne doit pas entraîner des
+fuites sur toutes les rives.
 
 Le contrat ne demande ni un bassin souterrain imposé pour obtenir un stock
 d'eau, ni une cuvette ajoutée systématiquement à une position fixe. Une surface
@@ -76,12 +135,31 @@ rapports de continents devront conserver leur propre graine, version, emprise
 et état de génération, afin d'additionner seulement des régions connues et
 disjointes lorsque le besoin économique sera défini.
 
-## Relevé de développement disponible
+## Ressources de départ — depuis l’alpha.5
+
+L’île vise les premières étapes de survie, les outils, l’enchantement et la
+redstone. Les sept minerais (charbon, fer, cuivre, or, redstone, lapis et diamant)
+utilisent des petites veines à des altitudes compatibles avec le terrain relevé.
+Le charbon et le fer ne reprennent plus leurs fréquences vanilla beaucoup trop
+généreuses dans cette géométrie. Une petite réserve de lave peut apparaître dans une niche rocheuse accessible
+pour les premières productions et l’accès au Nether. Le bois, la pierre, les animaux et les cultures
+renouvelables conservent leur fonctionnement Minecraft : ce réglage des minerais
+ne constitue pas une interdiction des grandes constructions.
+
+Les placements restent probabilistes, sans quota de rattrapage après comptage.
+Une graine peut donc manquer d’une ressource ; la présence de tout le parcours
+Minecraft n’est pas garantie. Les structures donnant accès à l’End et leur lien
+avec l’expansion restent à concevoir.
+
+## Relevé de développement — générateurs historiques
 
 `ResourceSurveyDiagnostics`, dans `src/gametest`, lit les chunks au statut
 `FULL`, après le terrain, les matériaux et les décorations. Il ne figure pas
 dans le JAR Sanctuary distribué et n'ajoute aucune commande joueur ou admin.
 La tâche repart d'un monde GameTest neuf, jamais d'une sauvegarde personnelle.
+Depuis l’alpha.13, `runGameTest` et `check` sélectionnent la suite unifiée par
+défaut. Les commandes ci-dessous demandent explicitement une suite historique ;
+elles ne constituent pas un relevé du nouveau monde unifié.
 
 Le relevé standard inspecte **neuf chunks**, soit un carré de 48×48 blocs autour
 du chunk du spawn naturel, sur toute la hauteur de la dimension. Il prépare
@@ -92,26 +170,42 @@ n'est inclus dans ces comptes de blocs.
 
 ```sh
 # Contrôle standard : neuf chunks inspectés, total local uniquement.
-./gradlew :sanctuary:runGameTest -PsanctuaryResourceSurvey=sample --console=plain
+./gradlew :sanctuary:runGameTest -PsanctuaryUnifiedTests=false -PsanctuaryResourceSurvey=sample --console=plain
 
 # Relevé de toute l'enveloppe déclarée de Sanctuary, sur un monde jetable neuf.
-./gradlew :sanctuary:runGameTest -PsanctuaryTestSeed=0 -PsanctuaryResourceSurvey=island --console=plain
+./gradlew :sanctuary:runGameTest -PsanctuaryUnifiedTests=false -PsanctuaryTestSeed=0 -PsanctuaryResourceSurvey=island --console=plain
 
 # Désactiver seulement le relevé pour un autre diagnostic.
-./gradlew :sanctuary:runGameTest -PsanctuaryResourceSurvey=off --console=plain
+./gradlew :sanctuary:runGameTest -PsanctuaryUnifiedTests=false -PsanctuaryResourceSurvey=off --console=plain
 ```
 
 Les modes sont transmis à la propriété JVM de test
-`sanctuary.test.resourceSurvey`. Le mode `island` couvre **1 444 chunks** :
-`X` et `Z` de **−304 inclus à 304 exclu**, correspondant à l'enveloppe de terrain
-de rayon 288 et une marge de décoration de 16 blocs. Un halo d'un chunk porte
-la préparation à **1 600 chunks FULL** ; seuls les 1 444 chunks demandés sont
-comptés. Ce relevé complet est plus coûteux et ne s'exécute pas par défaut.
-La marge devra être revue si une future génération peut produire des structures
-ou décorations au-delà de cette enveloppe.
+`sanctuary.test.resourceSurvey`. La propriété Gradle `-PsanctuaryTestPlayers`
+choisit le profil interne. L’alpha.11 utilise `5` pour Petit et `10` pour Grand,
+ce dernier par défaut ; `20` et `100` servent à la compatibilité historique.
+Le mode `island` calcule l’enveloppe du profil actif, avec 16 blocs de marge de
+décoration et un halo de préparation d’un chunk. Les valeurs ci-dessous sont
+les bornes calculées lors de l’alpha.10, pas des relevés exécutés ni un nombre
+de chunks déjà validé pour l’ancien Grand alpha.11 :
+
+| Profil | Chunks comptés par `island` | Chunks FULL préparés avec halo |
+| --- | --- | --- |
+| 5 | 1 444 | 1 600 |
+| 20 | 4 900 | 5 184 |
+| 100 | 22 500 | 23 104 |
+
+Un relevé de toute l’emprise peut être très coûteux et ne s’exécute pas par
+défaut. La marge devra être revue si une future génération produit des
+structures ou décorations qui la dépassent. Les diagnostics alpha.10 courants
+restent des inspections ciblées ; leurs nombres de minerais ne sont pas ceux
+d’un relevé `island` complet.
+
+Les nouveaux fichiers sont nommés
+`mods/sanctuary/build/run/gameTest/diagnostics/resource-survey-players-<capacité>-seed-<graine>-<mode>.json`.
+Sur un générateur historique, le nom émis par l’outil actuel porte `legacy`.
+Les anciens chemins `resource-survey-seed-…` cités plus bas désignent uniquement
+les relevés archivés de leurs versions respectives.
 
-Le JSON est écrit dans
-`mods/sanctuary/build/run/gameTest/diagnostics/resource-survey-seed-<graine>-<mode>.json`.
 Il contient :
 
 - La graine, la version Minecraft, le preset et les réglages de génération,
@@ -187,16 +281,16 @@ essai client concurrent pendant environ 23 secondes. Elle décrit une machine
 chargée et cette exécution, pas une performance garantie sur d'autres machines.
 Le temps de préparation est distinct du coût du comptage par palettes.
 
-## Contrat du prochain ticket d'expansion
+## Contrat de progression collective restant à construire
 
-Avant toute activation de continent, enregistrer côté serveur son identifiant,
-sa direction parmi les huit, son centre, son emprise, sa graine dérivée, sa
-version de génération, son profil climatique et son état de déblocage.
-Le relevé des ressources intervient après la génération effective de sa région,
-avec une complétude explicite, indépendamment des contributions qui l'ont ouverte.
+Le registre et la réservation des alpha.12/12.1 sont repris dans l’alpha.13 :
+identifiant, parent, direction, centre, emprise, graine, génération, climat et
+statut sont enregistrés côté serveur. Les chunks existants, y compris le vide,
+sont protégés pendant la recherche d’une nouvelle région.
 
-Les zones déjà explorées dans le vide peuvent contenir des chunks sauvegardés
-ou des constructions. L'activation exige donc un contrat de réservation ou de
-matérialisation qui les protège ; elle ne peut pas régénérer silencieusement
-les chunks existants. Les règles de contribution, distances, tailles,
-réservations, migrations et prix ne sont pas décidées par ce diagnostic.
+Le prochain travail de progression doit relier ces ouvertures aux recherches,
+aux contributions et à leurs coûts. Un éventuel relevé de ressources intervient
+après la génération réelle, avec une complétude explicite ; il ne choisit pas
+une graine pour remplir un stock attendu. Les prix, les objets de déblocage et
+les règles de contribution restent à concevoir. Aucun contrat de migration
+ou de régénération d’anciennes parties n’est fourni par ce diagnostic.

docs/packwiz.md

@@ -13,13 +13,140 @@ JAR Sanctuary sont des pièces jointes de releases Gitea. Aucun JAR de mod ou
 dépendance téléchargée n'entre dans l'historique Git. Le canal Beta est distinct
 de l'ancien pack 26.2.
 
+## Correctif alpha.13.1 publié — 9 septembre 2026
+
+[Sanctuary 0.1.0-alpha.13.1](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.13.1)
+est publié depuis le commit source `b19e93d`. Le canal stable utilise cette
+version. Le JAR, le [MRpack](https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.13.1/Sanctuary-0.1.0-alpha.13.1.mrpack)
+et le ZIP d’amorçage ont été vérifiés par téléchargement public. SHA-256 du JAR :
+
+```text
+b340dfc58f3d2d1a2a375dc527ac6721c61430600622046db26228e0da46061b
+```
+
+Deux synchronisations isolées puis deux dans la même instance Prism Mac ont
+réussi. Le second passage conserve les fichiers gérés à l’identique ; un seul
+JAR Sanctuary alpha.13.1 est actif. Les **713 fichiers personnels et réglages
+suivis** conservent leurs hashes. Aucune sauvegarde personnelle n’a été ouverte,
+convertie ou régénérée. Dossier de l’instance conservé : `Sanctuary-0.1.0-alpha.1`.
+Sauvegarde ciblée : `sanctuary-backups/before-0.1.0-alpha.13.1/` ; reçus locaux
+`build/alpha131-isolated-validation.json` et `build/alpha131-prism-validation.json`.
+
+Le correctif évite la synchronisation de dossier non prise en charge sous
+Windows. **Aucun nouveau monde requis :** fermer Minecraft, mettre l’instance
+à jour puis rouvrir le même monde. Les réservations enregistrées reprennent
+après vérification. La machine Windows n’a pas été accessible pour installation
+ou essai natif : le [guide](alpha13-worldgen.md#correctif-alpha131--expansions-sous-windows)
+décrit aussi le remplacement du seul JAR Sanctuary pour une instance issue du
+MRpack sans auto-update. Voir les [preuves et limites](testing.md#correctif-alpha131--journal-dexpansion-sous-windows).
+
+## Alpha.13 publiée — 9 septembre 2026
+
+[Sanctuary 0.1.0-alpha.13](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.13)
+est publiée depuis le commit source `78b63be`. Le canal stable utilisait alors
+cette version. Le JAR, le [MRpack](https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.13/Sanctuary-0.1.0-alpha.13.mrpack)
+et le ZIP d’amorçage ont été vérifiés par téléchargement public. SHA-256 du JAR :
+
+```text
+53eb5d8eda54d322250784203824993bd675de1cb90467e74d67589b15769e76
+```
+
+Deux synchronisations isolées puis deux passages dans la même instance Prism
+ont réussi. Le second passage laisse les fichiers gérés identiques ; un seul
+JAR Sanctuary alpha.13 est actif. Les **601 fichiers personnels et réglages
+suivis** conservent leurs hashes, notamment les mondes et mods tiers. Aucune
+sauvegarde personnelle n’a été ouverte, convertie ou régénérée.
+
+L’instance conserve son dossier `Sanctuary-0.1.0-alpha.1`, sans réimportation.
+Sauvegarde ciblée : `sanctuary-backups/before-0.1.0-alpha.13/` dans cette instance.
+Reçus locaux : `build/alpha13-isolated-validation.json` et
+`build/alpha13-prism-validation.json`.
+
+Pour tester : créer un **nouveau monde**, choisir **Sanctuary**, puis le bouton
+natif **Personnaliser** : Petit 512, Moyen 724 par défaut, Grand 1 024.
+Le laboratoire n’est plus un choix public ; ses cavités et outils d’expansion
+rejoignent le nouveau monde. Les anciennes générations restent chargeables.
+Voir [le guide alpha.13](alpha13-worldgen.md) et [les preuves](testing.md).
+
+## Correctif alpha.12.1 publié — 9 septembre 2026
+
+[Sanctuary 0.1.0-alpha.12.1](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.12.1)
+est publiée depuis le commit source `332d60b`. Le canal packwiz utilisait cette
+version. Le JAR, le [MRpack](https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.12.1/Sanctuary-0.1.0-alpha.12.1.mrpack)
+et le ZIP d’amorçage ont été vérifiés par téléchargement public. SHA-256 du JAR :
+
+```text
+c9df4da956cfa54581b3fde21de006bf8ac3ec025b8dd0daa5d060bcb70aabd4
+```
+
+Deux synchronisations isolées puis deux passages dans la même instance Prism
+ont réussi ; le second laisse les fichiers gérés identiques. Un seul JAR
+Sanctuary alpha.12.1 est actif, avec **466 fichiers personnels et réglages suivis
+conservés**, y compris les mondes et les mods tiers. Aucun monde n’a été ouvert
+ou régénéré. La sauvegarde ciblée est dans
+`sanctuary-backups/before-0.1.0-alpha.12.1/` de l’instance existante ; reçus locaux
+`build/alpha121-isolated-validation.json` et `build/alpha121-prism-validation.json`.
+
+WG-14 ajoute la distance et le contournement automatique des zones occupées.
+Les mondes laboratoire alpha.12 restent utilisables sans conversion : le journal
+v1 et les descripteurs de génération 12 sont conservés. Voir le [guide](alpha12-laboratory.md).
+
+## Alpha.12 publiée — 9 septembre 2026
+
+[Sanctuary 0.1.0-alpha.12](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.12)
+est publiée depuis le commit source `cdfbba0`. Le canal stable utilisait alors
+cette version. Le JAR, le [MRpack](https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.12/Sanctuary-0.1.0-alpha.12.mrpack)
+et le ZIP d’amorçage Prism ont été téléchargés publiquement et vérifiés contre
+les artefacts locaux. SHA-256 du JAR :
+
+```text
+f2ac2462a03a39ef330cc52143f9753ac5908b606cfe1dd1388ad5caae15e6e9
+```
+
+Le véritable installateur packwiz a réussi deux passages dans un dossier de
+développement neuf, puis deux dans la même instance Sanctuary Beta. Le second
+passage conserve les hashes des fichiers gérés. Un seul JAR Sanctuary alpha.12
+est actif ; les **466 fichiers personnels et réglages suivis** conservent
+leurs hashes, y compris les sauvegardes, mods tiers et configurations. Aucun
+monde n’a été ouvert, converti ou régénéré par cette livraison.
+
+La sauvegarde ciblée est dans `sanctuary-backups/before-0.1.0-alpha.12/` de
+l’instance existante. Les reçus locaux ignorés sont
+`build/alpha12-isolated-validation.json` et `build/alpha12-prism-validation.json`.
+Le [guide](alpha12-laboratory.md) décrit le nouveau preset **Sanctuary — Laboratoire** :
+créer un nouveau monde de ce type pour essayer les expansions. Les anciennes
+parties et les presets Petit/Grand gardent leur génération.
+
 ## Livrer une mise à jour
 
+Livraison précédente, vérifiée le 9 septembre 2026 :
+[Sanctuary 0.1.0-alpha.11](https://git.botsu.net/koka/sanctuary-beta/releases/tag/v0.1.0-alpha.11),
+depuis le commit source `f30a350`. Le JAR, le `.mrpack` et le ZIP d’amorçage
+Prism sont publiés et leurs téléchargements publics vérifiés. Le canal stable
+pointait alors sur cette version. SHA-256 du JAR :
+
+```text
+f075ad8a0b97cd53e4891273adbee5f79f04ab3984442950d5d85f58d2ded589
+```
+
+Le véritable installateur packwiz a réussi deux fois dans un dossier de
+développement neuf, puis deux fois dans l’instance Sanctuary Beta existante.
+Le second passage laisse les fichiers gérés identiques. Un seul JAR Sanctuary
+alpha.11 est actif ; les 364 fichiers personnels et réglages suivis conservent
+leurs hashes, y compris les fichiers des mods tiers et leurs configurations.
+L’ancien JAR et les manifestes locaux sont sauvegardés hors de `mods/`, dans
+`sanctuary-backups/before-0.1.0-alpha.11/` de cette même instance.
+Aucun monde existant n’a été ouvert, converti ou régénéré par la livraison.
+Les reçus locaux ignorés sont `build/alpha11-isolated-validation.json` et
+`build/alpha11-prism-validation.json` ; les listes de hashes avant et après
+figurent dans le dossier de sauvegarde. Les preuves du build, des deux tailles
+et de performance figurent dans [Validation](testing.md).
+
 Après les vérifications, le commit et le push de la branche du ticket, le script
 de publication réalise les étapes de release et de canal ci-dessous :
 
 ```sh
-python3 scripts/publish_pack.py --notes-file chemin/vers/notes.md --asset build/Sanctuary-0.1.0-alpha.4.mrpack
+python3 scripts/publish_pack.py --notes-file chemin/vers/notes.md --asset build/Sanctuary-0.1.0-alpha.12.mrpack
 ```
 
 Les options sont facultatives. Ce script **publie** sur le Git configuré dans
@@ -38,7 +165,7 @@ La procédure complète, également utilisable manuellement :
 3. Préparer les métadonnées de la livraison, avec l'URL exacte du futur JAR :
 
    ```sh
-   python3 scripts/pack.py release https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.4/sanctuary-0.1.0-alpha.4.jar
+   python3 scripts/pack.py release https://git.botsu.net/koka/sanctuary-beta/releases/download/v0.1.0-alpha.12/sanctuary-0.1.0-alpha.12.jar
    ```
 
 4. Pousser le commit source vérifié. Créer une release Gitea correspondant à ce
@@ -117,10 +244,54 @@ La hauteur de 384 blocs, le dessous sculpté et le ciel de l'alpha.3 se testent
 dans un **nouveau monde** avec le preset **Sanctuary**. Les anciens mondes gardent
 leurs identifiants de génération et leurs hauteurs. L’hydrologie de l’alpha.4
 nécessite elle aussi un nouveau monde Sanctuary ; la mise à jour de l’instance
-n’ajoute pas d’eau aux sauvegardes existantes. Les détails des versions de génération sont dans
+n’ajoute pas d’eau aux sauvegardes existantes. Les nouvelles plages, cascades,
+biomes et petits filons de l’alpha.5 utilisent à leur tour un identifiant
+séparé : créer un nouveau monde Sanctuary pour les découvrir. Les détails des versions de génération sont dans
 [Génération](worldgen.md). Les changements de version Minecraft ou de format
 de sauvegarde demandent leur propre ticket et contrat de migration.
 
+L’alpha.6 utilise à son tour `sanctuary:sanctuary_layered` pour ses biomes par
+altitude et sa nouvelle hydrologie. Créer un nouveau monde Sanctuary ; les
+sauvegardes alpha.5 conservent notamment leur palette avec Dappled Forest.
+
+L’alpha.7 sélectionne `sanctuary:sanctuary_woodland` pour ses forêts, ses
+roches variées et ses minerais affleurants. Les mondes alpha.6 gardent
+`sanctuary:sanctuary_layered` ; aucune régénération de chunks n’est effectuée.
+
+L’alpha.8 sélectionne `sanctuary:sanctuary_rift` pour les failles, les grandes
+rivières, les champignons géants et la géologie des profondeurs. Créer un
+nouveau monde Sanctuary pour les découvrir. La même instance Prism reçoit
+le nouveau JAR par le canal stable ; ses sauvegardes et réglages sont conservés.
+Les mondes alpha.7 et antérieurs gardent leurs paramètres de génération.
+
+L’alpha.9 utilise `sanctuary:sanctuary_cavern` pour les cavités luxuriantes,
+les géodes, les geysers et les terrasses d’eau. Un **nouveau monde Sanctuary**
+est nécessaire pour essayer cet incrément. Les mondes
+alpha.8 conservent `sanctuary:sanctuary_rift` ; leur contenu n’est pas retouché
+par une mise à jour de la même instance Prism. Les anciennes sauvegardes et
+les réglages ont été conservés lors des deux synchronisations de livraison.
+
+L’alpha.10 propose des choix de taille pour 5, 20 et 100 joueurs, avec
+20 par défaut. Ils s’appliquent à un **nouveau monde**. Les profils sauvegardés `sanctuary:population_5`,
+`sanctuary:population_20` et `sanctuary:population_100` sont séparés des
+anciens réglages, notamment `sanctuary:sanctuary_cavern` de l’alpha.9.
+La mise à jour de la même instance Prism n’agrandit aucune île
+existante, ne modifie pas les paramètres de génération enregistrés et ne
+nécessite pas de réimporter le ZIP d’amorçage. Les fichiers de sauvegarde,
+captures, packs graphiques et réglages personnels suivis ont conservé leurs
+hashes lors des deux synchronisations de livraison.
+
+L’alpha.11 propose deux choix : **Petit** et **Grand**, Grand par défaut.
+Le preset `sanctuary:sanctuary` crée un nouveau monde `population_10` ;
+Petit garde `sanctuary:sanctuary_5` / `population_5`. Les anciens mondes
+20/100 restent chargeables à leur taille enregistrée, alors que leurs formats
+sont cachés de la création. Les formats de sauvegarde sont inchangés.
+
+L’optimisation conserve les résultats pour un même réglage. La livraison a
+préservé les fichiers personnels suivis, les mods tiers et leurs configurations.
+L’instance n’a pas été réimportée et aucun mod tiers n’a été retiré. Les
+sauvegardes personnelles sont restées fermées pendant les essais et la synchronisation.
+
 Références officielles : [installation packwiz](https://packwiz.infra.link/tutorials/installing/packwiz-installer/),
 [commandes Prism](https://prismlauncher.org/wiki/help-pages/custom-commands/),
 [bootstrap v0.0.3](https://github.com/packwiz/packwiz-installer-bootstrap/releases/tag/v0.0.3).

docs/vision.md

@@ -50,18 +50,107 @@ Les intégrations communautaires envisagées comprennent Fabric API, Sodium, Iri
 
 L'île de Sanctuary est le point de départ commun. Elle flotte dans un vide qui ne doit pas être rempli par la génération habituelle du monde. Les continents suivants sont de vastes terres suspendues, créées progressivement selon une taille et une direction maîtrisées.
 
+Le monde doit se créer par un seul choix **Sanctuary**, avec le bouton natif
+**Personnaliser** pour régler sa taille : **Petit** (512 blocs de diamètre
+nominal), **Moyen** (724, par défaut) et **Grand** (1 024). La hauteur reste de
+384 blocs. Ces dimensions ne promettent ni une aire entièrement habitable,
+ni un stock de ressources, ni une capacité multijoueur.
+
+L’alpha.13 implémente cette interface et la réunion de l’île complète de Population,
+de ses forêts et de son hydrologie, avec les cavités natives du laboratoire.
+L’alpha.11 et ses anciens choix Petit/Grand restent historiques. Les anciens
+codecs et paramètres sauvegardés restent chargeables ; les choix précédents
+sont cachés à la création et aucune partie n’est convertie ou redimensionnée.
+L’état d’intégration est décrit dans le [guide alpha.13](alpha13-worldgen.md) ;
+les observations réelles et leurs limites restent dans [Validation](testing.md).
+
 L'île initiale doit être **tempérée et légèrement humide**, avec quelques zones
-plus sèches, notamment des plages. Une rivière et de petits étangs ou lacs de
-surface peuvent accueillir de la canne à sucre. Les grands bassins souterrains
-remplis d'eau ne sont pas retenus pour cette île. Le terrain doit laisser voir un
-dessous sculpté et dégagé, dans un monde de **384 blocs de hauteur**, avec des
+plus sèches, notamment de larges plages et dépôts irréguliers de sable, gravier,
+pierre et terre enherbée. De petits étangs ou lacs de surface
+peuvent accueillir de la canne à sucre. Lorsque le relief le permet, une grande
+rivière suit la forme de l’île, depuis une source jusqu’à une cascade et un
+bassin, avec des rives de sable, de gravier et d’argile. Ce parcours doit former
+un lieu reconnaissable ; il reste facultatif. À défaut, l’île conserve ses
+petits bassins, sans imposer de courts ruisseaux. Le terrain est traité près de la surface,
+avec des dépôts épais et des rives variées. De rares sources sortent de niches
+rocheuses naturelles et leurs cascades peuvent descendre jusque dans le vide ;
+les bassins restent retenus et ne doivent pas provoquer une inondation globale.
+Une rivière peut avoir des échappements et des chutes déclarés. Les eaux
+intérieures doivent rester localisées et retenues, sans aquifère qui remplit
+globalement les cavités. Des bassins naturels étagés, évoquant des rizières,
+peuvent se relier par des cascades et offrir des passages verticaux par la nage.
+Cette image ne prévoit aucune culture de riz dans le mod Sanctuary.
+Le terrain doit laisser voir un dessous sculpté et dégagé, dans un monde de
+**384 blocs de hauteur**, avec des
 nuages relevés et sans disque noir artificiel apparaissant sous un seuil d'altitude.
 
-Le premier champ de recherche des expansions associe les **huit directions**
-autour de Sanctuary à des signatures de température et d'humidité. En regardant
-la carte avec le nord en haut : **nord froid, sud chaud, ouest sec et est humide**.
-Les diagonales combinent ces tendances. La recherche porte sur des climats et
-leurs distributions, sans imposer la même forme de continent à chaque direction.
+L’ambiance de départ doit rester douce et tempérée, avec de véritables forêts
+et des clairières fleuries, quelques zones plus sèches et de larges masses
+rocheuses mêlant pierre, andésite, diorite et granite. Les nappes de sable et
+de gravier accompagnent les eaux. Charbon, fer et cuivre doivent aussi pouvoir
+affleurer sur la roche exposée pour commencer la survie, avec du charbon assez
+repérable pour fournir les premières expériences. Les failles doivent ouvrir
+des passages courbes et des vues vers les profondeurs, sans reconstruire une
+masse artificielle au centre de l’île.
+
+La géologie change en descendant : tuf, cobblestone, pierres moussues et boue
+compactée dans les intérieurs humides, puis ardoise des abîmes, roche noire et
+basalte. Des poches de soufre doivent être réellement explorables et rester
+ponctuelles, avec de vrais geysers actifs lorsque les conditions s’y prêtent.
+Quelques sources profondes peuvent former des coulées de lave ; elles ne doivent pas
+transformer les profondeurs en grands bassins remplis. L’émeraude rejoint les
+minerais à rechercher, avec l’or, le diamant, la redstone et le lapis.
+
+Les bois dominants sont le chêne, le chêne noir et le bouleau : chênes et
+bouleaux en surface, chênes noirs et gros champignons dans l’intérieur plus
+humide, avec de petits champignons dispersés et des tapis variés de mousse,
+podzol et mycélium. Épicéa, jungle, acacia, palétuvier et chêne pâle restent rares
+mais possibles ; du bambou peut se rencontrer dans les profondeurs. Un arbre remarquable isolé peut être un
+cerisier rose ou une autre de ces essences rares, lorsque le terrain convient.
+Les biomes très contrastés de Minecraft 26.3, dont Dappled Forest, restent
+réservés aux futurs continents.
+
+Les cavités sous l’île doivent aussi accueillir des ambiances luxuriantes
+avec de la végétation lumineuse, des secteurs à stalactites et stalagmites et
+des géodes d’améthyste. Leur décor doit utiliser les sols et plafonds du relief,
+sans reconstruire l’île ni déposer de structures flottantes sans support.
+L’alpha.9 introduit ces ambiances et recherche des lacs plus profonds et
+volumineux ; les résultats et leurs limites sont documentés dans les contrôles moteur. Ces cavités appartiennent à
+l’Overworld de Sanctuary et ne remplacent pas le futur projet de dimension
+des cavernes.
+
+L’île doit offrir les ressources nécessaires aux premières étapes de Minecraft,
+en quantités modestes pour pousser à explorer les expansions lors des grands
+projets. Les minerais doivent être trouvables aux altitudes du terrain. Les
+stocks sont observés après génération et les ressources renouvelables gardent
+leurs règles Minecraft. Le réglage précis de ces quantités reste à éprouver en
+partie coopérative. La recherche de l’alpha.8 porte notamment sur une rivière
+calme continue reliant deux bassins au même niveau, alimentée par une source
+en paroi et sa cascade. Son tracé doit former de larges courbes, avec une
+largeur variable et des berges progressives. La petite réserve de lave est
+recherchée d’abord dans les étages profonds ; un site plus haut reste possible
+si la roche ne fournit pas de niche compatible en dessous. Ces formes restent
+facultatives selon le relief ; leur existence doit être démontrée en jeu.
+L’état de chaque incrément et ses limites
+figurent dans [Génération](worldgen.md).
+
+La progression des expansions se fait par **choix en branchement**. La direction
+géographique, le climat et l’archétype sont des choix distincts. La convention
+**nord froid, sud chaud, ouest sec et est humide** reste une voie possible, avec
+ses diagonales. Le joueur peut aussi ouvrir une branche alternative et composer
+des couronnes de nouvelles îles aux climats différents. Une île enregistre son
+parent ; le serveur conserve ainsi l’histoire des découvertes de son univers.
+La recherche porte sur des climats et leurs distributions, sans imposer la même
+forme ni le même climat à une direction pour toutes les parties.
+
+Les alpha.12 et alpha.12.1 ont fourni un laboratoire à cette conception :
+commandes opérateur, climats et reliefs indépendants, structures vanilla
+compatibles et recherche d’emplacements libres. L’alpha.13 reprend ces mêmes
+outils dans le nouveau monde Sanctuary unifié. Son journal est séparé de celui
+des anciens laboratoires, sans conversion de leur génération.
+Les recherches, mailboxes et deposit boxes viendront ensuite ; elles ne sont
+pas nécessaires aux commandes d’essai. Le passage en bêta dépendra du périmètre
+de progression retenu et de sa validation, pas du seul changement de générateur.
 
 L'économie naturelle d'une île doit être connue **après sa génération** : nombre
 de blocs de pierre, bûches, minerais de charbon, de fer et autres ressources,
@@ -77,6 +166,10 @@ L'ambition est de reprendre puis d'étendre la centaine de biomes du catalogue T
 
 ### Structures et territoires
 
+- **Structures vanilla** : admises dans les nouvelles générations lorsque leur
+  biome, leur emprise et leurs fondations conviennent au terrain flottant.
+  L’autorisation ne garantit pas leur présence sur chaque île. Le laboratoire
+  commence par les villages, temples, cabanes de marais et camps abandonnés.
 - **Lost Cities** : des zones traitées comme des biomes, où des bâtiments en ruine remplacent la végétation dominante. Le nom exprime ici un type de territoire souhaité, sans décider encore s'il sera produit par une intégration ou par du code Sanctuary.
 - **Structures contemporaines** : parcs, parkings et autres vestiges. Les parkings sont souterrains et peuvent s'étendre comme une infestation. Ils n'apparaissent pas dans la dimension des cavernes.
 - **Structures uniques et donjons** : d'abord sur Sanctuary Island, puis dans les continents. Ils peuvent contenir des clés de chunk et d'autres ressources rares.

docs/worldgen.md

@@ -1,64 +1,424 @@
 # Premier monde Sanctuary
 
-Le preset `sanctuary:sanctuary` crée l'île principale à l'origine de l'Overworld,
-entourée de vide sans répétition d'îles à grande distance. C'est une première
-tranche de génération pour Minecraft **26.3-pre-2 / Fabric**, pas encore le
-système d'expansion collective.
+## Alpha.13 — génération unifiée
 
-## Créer un monde
+Le choix public **Sanctuary** (`sanctuary:sanctuary`) crée l’île principale à
+l’origine de l’Overworld, entourée de vide. Son bouton natif **Personnaliser**
+propose **Petit** (512 blocs de diamètre nominal), **Moyen** (724, par défaut)
+et **Grand** (1 024). Les types vanilla restent disponibles. La hauteur reste
+de 384 blocs ; les dimensions nominales ne donnent ni aire habitable garantie
+ni capacité multijoueur.
 
-En solo : créer un **nouveau** monde et choisir le type de monde **Sanctuary**
-dans les options de génération. Les types de monde vanilla restent disponibles.
+L’île initiale reprend la densité, les forêts et l’hydrologie complète de la
+famille Population, avec les poches de biomes souterrains natives du laboratoire.
+Les extensions conservent leurs profils climatiques et leurs commandes
+alpha.12.1. Leurs règles de génération restent distinctes de celles de l’île
+initiale : la grande hydrologie de départ n’est pas automatiquement reproduite
+sur chaque continent ajouté.
 
-Sur un nouveau serveur Fabric disposant du mod et de Fabric API :
+Les trois tailles et les cavités passent les contrôles moteur. Le [guide alpha.13](alpha13-worldgen.md)
+décrit l’interface, les paramètres sauvegardés et les outils d’expansion ;
+[Validation](testing.md) conserve la portée des essais de chaque version.
+
+## Créer un nouveau monde
+
+En solo, choisir **Sanctuary**, ouvrir **Personnaliser**, puis confirmer la
+taille avec **Terminé**. **Annuler** conserve le réglage précédent. Cette
+interface configure le monde à créer ; elle ne redimensionne pas une partie.
+
+Sur un nouveau serveur Fabric avec Fabric API, le preset public utilise la
+taille **Moyen**, 724 blocs :
 
 ```properties
 level-type=sanctuary:sanctuary
-level-name=sanctuary
+level-name=sanctuary-dev
 level-seed=0
 ```
 
-La seed est libre. Modifier `level-type` ne convertit pas un monde existant :
-utiliser un nouveau `level-name` pour tester une autre génération. Les fichiers
-de test et les sauvegardes personnelles doivent rester distincts.
+La graine est libre. Utiliser un dossier neuf pour un essai ; modifier
+`level-type` ne convertit aucun monde enregistré. Aucune commande de migration
+ou de régénération des anciennes îles n’est fournie.
 
-## Ce qui est généré
+## Compatibilité et versions historiques
+
+L’alpha.13 enregistre le générateur `sanctuary:island_v13`, son diamètre initial
+et une racine de génération 13. Les nouvelles expansions restent de génération
+12. Leur journal utilise le dossier propre au monde
+`data/sanctuary-world-v13/`. Les anciens codecs et presets sont conservés, mais
+cachés de la sélection publique. Les mondes déjà créés conservent leurs réglages
+et leur journal ; aucun chunk n’est remplacé par cette mise à jour.
+
+### Alpha.12 et alpha.12.1 — laboratoire historique
+
+Le preset distinct `sanctuary:expansion_lab` proposait une origine de 512 blocs
+et des commandes opérateur pour ajouter des îles de 64/128/256/512 blocs.
+Son relief expérimental et ses biomes natifs ne reprenaient pas les grandes
+rivières et terrasses de Population. L’alpha.12.1 ajoutait une distance
+facultative et la recherche d’un emplacement libre au-delà des chunks occupés.
+
+Ces mondes gardent leur génération 12 et leur dossier
+`data/sanctuary-expansion-v1/`. Le [guide du laboratoire](alpha12-laboratory.md)
+reste la référence historique de ces versions, avec leurs seules observations.
+
+### Alpha.11 — Petit et Grand historiques
+
+| Ancien choix public | Diamètre nominal | Ancien preset | Réglage enregistré |
+| --- | --- | --- | --- |
+| Petit | 512 blocs | `sanctuary:sanctuary_5` | `sanctuary:population_5` |
+| Grand, ancien défaut | Environ 724 blocs | `sanctuary:sanctuary` | `sanctuary:population_10` |
+
+L’ancien Grand correspond à la taille nominale du nouveau Moyen. Les mondes
+historiques `population_5`, `population_10`, `population_20` et `population_100`
+restent chargeables avec leurs dimensions. Le preset public est une recette
+de création ; sa nouvelle définition ne remplace pas leur générateur sauvegardé.
+
+L’optimisation alpha.11 conserve l’arithmétique de l’interpolation et les règles
+de terrain et d’hydrologie. Ses mesures et contrôles sont historiques, sans
+validation anticipée des ajouts de l’alpha.13.
+
+## Socle de génération conservé
+
+Les points suivants décrivent le socle livré jusqu’à l’alpha.8. Les évolutions
+alpha.9 et alpha.10 sont précisées dans les sections v9 et v10 ci-dessous.
 
 - Le générateur reste celui de Minecraft, `minecraft:noise`.
 - La forme reprend le champ de bruit flottant actif en 26.2 : `old_blended_noise`
   avec `xz_scale=0.25`, `y_scale=0.25`, `xz_factor=80`, `y_factor=160`, `smear=4`,
   ainsi que son gradient supérieur. Il est échantillonné **64 blocs plus bas**
   pour relever l'île entière de 64 blocs. Reliefs, surplombs, trous et fragments
-  dépendent de la seed Minecraft. L'ancien gradient inférieur uniforme est
+  dépendent de la seed Minecraft. L’alpha.8 y soustrait des failles courbes,
+  sans ajouter de matière. L'ancien gradient inférieur uniforme est
   remplacé par la sculpture irrégulière décrite ci-dessous.
 - Le terrain naturel reste libre de laisser un trou à l'origine, de former des
   surplombs ou de se séparer en fragments. **Aucun noyau ellipsoïdal, cylindre ou
-  plateforme de départ n'est ajouté.** Au-dessus de `Y=144`, le relief de la
-  génération précédente est conservé dans la densité, simplement relevé de 64
-  blocs. L’hydrologie v4 creuse ensuite localement les lits de surface.
+  plateforme de départ n'est ajouté.** Le relief relevé de 64 blocs reste le
+  champ source ; les failles de l’alpha.8 en retirent de la matière et
+  l’hydrologie traite ensuite les lits et les rives près de la surface.
 - Le pourtour est sculpté par retrait de matière à partir du rayon **128 blocs**.
   Le contour de référence de 256 blocs est déformé par les bruits, entre 204 et
   288 blocs ; il indique la fin de l'érosion, pas un mur de roche.
   La côte réelle apparaît plus tôt, selon la densité du terrain et la seed.
-  Il reste du vide permanent au-delà de **288 blocs**, sans répétition d'îles.
+  Aucun terrain ne réapparaît au-delà de **288 blocs**, sans répétition d'îles.
   Les arbres peuvent dépasser la côte rocheuse de quelques blocs.
 - Les nouveaux mondes utilisent **384 blocs de hauteur**, de `Y=0` à `Y=383`,
   pour la dimension et le générateur. La roche disparaît avant leurs limites.
   Il n'y a ni plancher de bedrock,
   ni mer globale, ni reprise du terrain à distance. Le Nether et l'End restent
   ceux de Minecraft.
-- `sanctuary:starter_forest_hydrology` reprend végétation, minerais et animaux de la forêt
-  vanilla 26.3. Ses blocs sont exclusivement vanilla. C'est un biome distinct
-  pour ne pas hériter des tags de structures vanilla et de leurs apparitions
-  possibles dans le vide.
-- Les carvers, géodes, donjons, lacs de lave et sources sont retirés de cette
-  forêt initiale. Les minerais remplacent la roche existante et les arbres ont
-  besoin de sol. Aucun mod de biomes externe n'est nécessaire.
+- Les nouveaux mondes utilisent une palette tempérée de forêts de chênes et de
+  bouleaux, de clairières fleuries et de zones rocheuses. Les strates intérieures
+  portent des chênes noirs et des champignons sur leurs corniches naturelles.
+  Dappled Forest est réservé aux futurs continents. Leur végétation et leurs animaux proviennent
+  de Minecraft 26.3-pre-2. Les nouveaux identifiants ne reprennent pas les tags
+  de structures vanilla, afin de ne pas placer leurs structures dans le vide.
+- Jusqu’à l’alpha.8, les carvers, géodes, donjons, grands lacs de lave et sources
+  vanilla sont retirés. L’alpha.9 ajoute une intégration bornée de géodes et
+  de geysers, sans réactiver l’ensemble de la décoration souterraine vanilla.
+  L’eau de Sanctuary suit son propre plan de surface et de niches
+  rocheuses. Les arbres et les petits filons ont besoin du terrain existant.
+  Aucun mod de biomes externe n’est nécessaire.
 
-L’hydrologie v4 fournit les premières eaux de surface décrites ci-dessous. La
-répartition complète des ressources de survie et la variété de biomes restent
-à développer. Les minerais vanilla conservent leurs plages d’altitude ;
-leur abondance n'est donc pas encore équilibrée pour une île flottante.
+L’alpha.8 associe ces biomes aux plages, aux eaux et aux filons décrits
+ci-dessous. Les ressources de survie ne se limitent pas au bois et à la pierre,
+mais cet incrément ne garantit pas encore une partie Minecraft complète sur
+chaque seed. L’accès à chaque progression vanilla et les ressources renouvelables
+nécessitent des vérifications concrètes. Les stocks réels sont relevés après la
+génération, sans corriger une île pour atteindre un quota.
+
+## Capacité de l’île — génération v10 historique
+
+Lors de l’alpha.10, trois tailles étaient accessibles à la création d’un monde.
+Le choix **Sanctuary** visait 20 joueurs par défaut, accompagné de variantes
+pour 5 et 100 joueurs. Le tableau suivant conserve cette association historique ;
+l’alpha.11 utilise le nouveau défaut Grand indiqué plus haut :
+
+| Preset de création | Paramètres enregistrés dans le monde |
+| --- | --- |
+| `sanctuary:sanctuary_5` | `sanctuary:population_5` |
+| `sanctuary:sanctuary` | `sanctuary:population_20` |
+| `sanctuary:sanctuary_100` | `sanctuary:population_100` |
+
+Les nouveaux réglages restent distincts des identifiants enregistrés dans
+les anciennes sauvegardes. Modifier le preset
+sélectionné pour une nouvelle partie ne convertit pas un monde existant.
+
+| Capacité de référence | Facteur horizontal | Aire nominale relative | Diamètre nominal | Hauteur |
+| --- | --- | --- | --- | --- |
+| 5 joueurs | 1 | 1 | 512 blocs | 384 blocs |
+| 20 joueurs, défaut | 2 | 4 | 1 024 blocs | 384 blocs |
+| 100 joueurs | √20, environ 4,472 | 20 | Environ 2 290 blocs | 384 blocs |
+
+Le facteur horizontal vaut `√(capacité / 5)` : doubler le diamètre multiplie
+l’aire nominale par quatre. Cette relation décrit l’enveloppe de référence,
+pas la surface réellement constructible après les trous, les falaises et
+la sculpture de la bordure. Aucun cylindre central ni remplissage de secours
+ne doit être ajouté pour obtenir l’aire théorique. La hauteur de dimension
+reste `Y=0..383`.
+
+La capacité choisie reste un paramètre de génération. Elle ne modifie pas
+`max-players`, n’agrandit pas l’île à chaque connexion et ne fixe aucun quota
+de ressources. Les anciens mondes jusqu’à l’alpha.9 gardent leur génération
+et leur taille ; leurs chunks ne sont ni remplacés ni régénérés. Le projet
+de continents déverrouillables reste séparé de ces tailles de départ.
+
+Le bruit naturel reste échantillonné aux coordonnées du monde ; seule
+l’enveloppe extérieure change de taille. Les plans hydrauliques sont construits
+à la demande dans des régions de 512 blocs, avec une graine régionale distincte.
+Les marges d’admission sont de 16 blocs pour l’eau et 32 pour la lave. Bassins,
+berges et groupes de terrasses sont admis entiers ; les sources dépendant d’une
+coupe écartée sont retirées aussi. Aucun trajet n’est tronqué à la frontière.
+Les couches superposées et leurs sources sont ensuite traduites ensemble.
+
+Les forêts, minerais et décorations utilisent toute l’emprise du profil.
+La recherche facultative d’un arbre remarquable reste unique et centrale.
+Les sources et exutoires n’agissent que pendant la génération, avec les
+marqueurs vanilla consommés ; recharger un ancien chunk ne rouvre pas une bouche.
+
+Les trois tailles passent onze tests requis sur la graine `0`, avec 1 800 ticks
+de fluides et un aller-retour réel des paramètres sur disque. Le fichier
+`data/minecraft/world_gen_settings.dat` conserve la clé du profil choisi.
+212 anciens fichiers de production sont strictement identiques, tandis que
+huit fichiers d’intégration ou d’interface exposent les nouvelles générations.
+Le premier calcul d’une région reste coûteux ; les résultats ne sont pas un
+test de cent connexions ni une garantie de génération rapide de toute l’île.
+Voir les emprises et durées dans [Validation](testing.md).
+
+## Cavités et terrasses d’eau — génération v9
+
+Le nouveau réglage est `sanctuary:sanctuary_cavern`, avec le biome source
+`sanctuary:cavern_island` et la règle de matière `sanctuary:cavern_island`.
+La densité réutilise `sanctuary:final_density_rift` sans changer cet identifiant
+historique. Ses nouvelles données et traitements
+doivent rester distincts de `sanctuary:sanctuary_rift` et de toutes les
+générations précédentes. Le preset sélectionne la nouvelle génération à la
+création ; une mise à jour du JAR ne convertit pas une sauvegarde ni ne
+régénère ses chunks. Les cavités restent dans l’Overworld sur 384 blocs de
+hauteur ; la dimension des cavernes décrite dans la vision n’est pas ajoutée.
+
+### Ambiances et ressources
+
+Le ticket conserve les forêts de surface et ajoute des cavités luxuriantes
+éclairées par leur végétation, des secteurs à spéléothèmes et des géodes
+d’améthyste sur des emplacements compatibles. Les sols, plafonds, coquilles
+et ouvertures doivent être observés après la décoration réelle : une valeur
+de biome ne prouve ni le décor ni son éclairage. L’objectif est d’utiliser
+les volumes naturels de l’île, sans remplir ses trous pour accueillir une
+structure.
+
+Les dix biomes ont leurs propres identifiants : `cavern_oak_forest`,
+`cavern_birch_forest`, `cavern_clearing`, `cavern_dry_woodland`,
+`cavern_rocky_heath`, `cavern_dark_grove`, `cavern_bamboo_grove`,
+`cavern_sulfur_depths`, `cavern_lush_caves` et `cavern_dripstone_caves`, dans
+le namespace `sanctuary`. Les deux nouvelles ambiances luxuriantes et à
+spéléothèmes sont limitées à Y<184 par la palette ; leur décoration recherche
+des sols entre Y=40 et Y=182, avec trois blocs naturels de support et un
+plafond situé de 6 à 48 blocs au-dessus.
+
+Dans les cavités luxuriantes, la mousse remplace le sol compatible et de
+petites plantes l’accompagnent. Les vraies lianes `cave_vines` et
+`cave_vines_plant` pendent sur 3 à 8 blocs ; leurs baies émettent de la lumière
+et restent récoltables. Ce décor n’ajoute pas d’eau. Les spéléothèmes utilisent
+les blocs `pointed_dripstone` orientés, sur un appui de `dripstone_block`
+remplaçant de la roche existante, avec une longueur de 1 à 4 blocs selon
+l’espace disponible.
+
+La géode utilise une configuration vanilla compacte avec améthyste,
+améthyste bourgeonnante, calcite et basalte lisse. Son enveloppe doit tenir
+dans la roche préexistante et un passage de deux blocs de haut la relie à
+la cavité, en préservant l’améthyste bourgeonnante et les cristaux attachés.
+Un chunk sur huit est candidat ; au plus une pose réussie est retenue par
+chunk candidat. Cela ne garantit pas de géode sur une graine.
+
+Le soufre devient admissible dans une bande climatique plus étroite sous
+Y=176. La réduction de cette sélection peut être testée indépendamment du
+terrain ; seule une comparaison des vrais blocs sur un périmètre commun
+mesure sa diminution dans l’île. Un geyser éventuel creuse un seul bloc de
+sol pour sa source d’eau, avec `potent_sulfur` dessous et `magma_block` encore
+en dessous. Le fond, les quatre parois et la hauteur libre sont contrôlés.
+Le cycle du geyser reste celui de Minecraft ; ce décor est distinct des
+bassins hydrologiques et son eau doit être comptée séparément.
+
+Leur présence, leur activité, l’éclairage et la cohabitation avec les eaux
+et la végétation sont contrôlés dans les mondes de test. Les preuves de ces
+éléments sont cumulées sur les trois graines. Un site incompatible peut
+être rejeté ; aucun geyser ni stock n’est garanti pour chaque graine.
+
+### Lacs et bassins étagés
+
+Le plan hydrologique conserve la recherche de rivière de
+l’alpha.8 et vise de plus grands lacs de surface. Les cibles actuelles sont
+de l’ordre de **700 à 1 100 colonnes** par grand lac, jusqu’à **7 à 8 blocs**
+de profondeur intérieure et une incision limitée à **12 blocs**. Ce sont des
+bornes de recherche ; les dimensions réelles sont relevées séparément, sans quota d’eau à
+remplir. Les fonds, les parois et les dépôts exigent du terrain naturel.
+
+Les terrasses sont recherchées dans des cavités entre **Y=56 et Y=208**,
+avec deux paliers par groupe et jusqu’à deux groupes facultatifs.
+Un palier vise environ **40 à 180 colonnes**, une profondeur de **1 à 3 blocs**
+et une incision d’au plus **5 blocs**. Le fond doit conserver trois couches
+de sédiments et deux couches de support naturel ; le plafond et l’espace
+disponible sont vérifiés. Les mesures moteur précisent les sites effectivement retenus.
+
+La recherche suit le choix de pente de l’eau vanilla : parmi les passages
+libres, elle privilégie ceux qui rejoignent la chute la plus proche. Un
+bassin inférieur doit intercepter ce trajet réel, sans détour creusé pour
+le rejoindre. Les sorties entre paliers sont déclarées et les cascades sont formées par les
+ticks de fluides Minecraft. Le premier débordement doit atteindre le second
+bassin. Celui-ci peut avoir un exutoire terminal qui s’écoule sur les roches
+ou vers le vide, sans troisième bassin ajouté. Le générateur ne doit ni peindre une colonne
+d’eau jusqu’au vide ni colmater un trou pour retenir un bassin. Les volumes
+retenus et les liaisons réelles sont vérifiés séparément après décoration
+et simulation, y compris aux frontières de chunks. Les cascades peuvent
+servir à monter ou descendre selon la nage vanilla ; aucune mécanique
+d’ascenseur supplémentaire n’est prévue. « Rizières » décrit seulement
+l’aspect du paysage en terrasses, sans ajouter une culture de riz.
+
+**Validation moteur au 9 septembre 2026 :** les trois graines de référence
+passent les contrôles après 1 800 ticks, avec preuves cumulées des terrasses
+connectées, geysers actifs, baies lumineuses, spéléothèmes et améthyste
+bourgeonnante. Le build complet réussit. Les résultats et leurs limites sont
+consignés dans [Validation](testing.md). Aucune présence universelle n’est
+garantie. La [distribution](packwiz.md) est publiée et la même instance Prism
+est synchronisée, sauvegardes et réglages conservés.
+
+## Failles, géologie et ressources — génération v8
+
+Les nouveaux mondes utilisent `sanctuary:sanctuary_rift`, la densité
+`sanctuary:final_density_rift` et le biome source `sanctuary:rift_island`.
+Les anciens paramètres `sanctuary`, `sanctuary_384`, `sanctuary_hydrology`,
+`sanctuary_natural`, `sanctuary_layered` et `sanctuary_woodland` restent séparés.
+Changer le preset ne migre pas un monde existant ; aucune régénération de
+chunks ni modification de sauvegarde n’est prévue par cet incrément.
+
+### Failles et palette
+
+`RiftShape` définit une à trois traces principales, courbes et ramifiées,
+de longueur nominale 84 à 160 blocs. Leur largeur varie avec deux bruits en
+trois dimensions ; le cœur ouvert est de l’ordre de 4 à 12 blocs, avec des
+parois érodées autour. Ces nombres décrivent les traces avant leur intersection
+avec la roche, pas une garantie de canyon continu de cette taille. La passe
+retire seulement de la matière et laisse intactes les zones de rayon inférieur
+à 20 blocs et extérieur à 224 blocs. Elle ne crée aucun socle central.
+
+Les huit biomes `rift_oak_forest`, `rift_birch_forest`, `rift_clearing`,
+`rift_dry_woodland`, `rift_rocky_heath`, `rift_dark_grove`, `rift_bamboo_grove`
+et `rift_sulfur_depths` ont de nouveaux identifiants dans le namespace
+`sanctuary`. Les choix climatiques de l’alpha.7 sont conservés en haut. Le
+soufre devient admissible dans des régions plus larges des étages inférieurs,
+notamment vers Y=176, selon les bruits de variation et d’humidité. Le test de
+palette prouve cette possibilité ; seule la lecture des vrais blocs peut
+prouver une poche accessible sur une graine.
+
+La végétation vanilla de surface garde ses arbres et ses teintes. La feature
+`rift_groves` passe ensuite, avant `rift_shore_sugar_cane`, pour choisir les
+volumes inférieurs encore libres après les arbres. Elle peut placer de gros
+champignons vanilla, avec des petits champignons dispersés et des sols mêlant
+mousse, podzol et mycélium. Les supports naturels et la place disponible
+restent nécessaires ; un arbre remarquable peut échouer si son site est occupé.
+L’ordre des plantations intérieures donne la priorité aux arbres dans trois
+cas sur quatre et aux gros champignons dans l’autre cas, selon un choix lié
+au chunk. Cela laisse des volumes disponibles aux chênes noirs. Dans les
+biomes `sanctuary:rift_dark_grove` et `sanctuary:rift_bamboo_grove`, l’ardoise
+des abîmes peut aussi fournir le support naturel des sols et bosquets
+inférieurs. Son admissibilité est vérifiée au-dessus de chaque pied : seules
+ces deux variantes humides autorisent ce support.
+
+### Matières selon la profondeur
+
+La règle `sanctuary:rift_island` ne change que la matière de blocs déjà solides.
+Ses nappes utilisent un bruit 3D, avec un bruit distinct pour faire varier les
+transitions de profondeur.
+
+| Domaine | Matières |
+| --- | --- |
+| Masses supérieures | Pierre, granite, andésite, diorite ; sols enherbés hors affleurements |
+| Intérieur des bosquets humides | Tuf, cobblestone, cobblestone moussue, boue compactée |
+| Masses profondes | Ardoise des abîmes, roche noire, basalte |
+| Poches soufrées | Soufre et cinabre ordinaires sur les masses existantes |
+
+Les strates humides se mêlent aux matières hautes entre Y=192 et Y=224 dans
+leurs biomes ; la transition vers les roches profondes s’étend de Y=136 à Y=168.
+La profondeur sert de critère géologique : ces blocs ne signifient pas qu’une
+source de lave se trouve forcément à proximité. Aucun bassin, spike, source
+vanilla ou bloc de soufre puissant du biome Sulfur Caves n’est ajouté.
+
+Les anciens petits dépôts vanilla de granite, andésite, diorite et tuf sont
+remplacés par ces nappes dans les seuls biomes `rift_*`. Les anciennes données
+de biomes et leurs features ne sont pas modifiées.
+
+### Minerais
+
+Les features `rift_ore_*` ciblent des tags Sanctuary locaux : les pierres hautes
+et humides produisent les minerais ordinaires ; ardoise des abîmes, roche noire
+et basalte produisent leurs variantes d’ardoise. Les tags vanilla ne sont pas
+élargis globalement. Le soufre et le cinabre restent des matières distinctes.
+
+| Minerai | Taille du filon configurée | Essais principaux par chunk | Altitudes principales |
+| --- | ---: | --- | --- |
+| Charbon | 9 | 8 | Y=96..304 |
+| Fer | 7 | 4 | Y=88..280 |
+| Cuivre | 7 | 3 | Y=96..280 |
+| Or | 5 | 2 | Y=88..224 |
+| Redstone | 5 | 2 | Y=88..216 |
+| Lapis | 4 | 1 | Y=104..240 |
+| Diamant | 4 | Un essai une fois sur deux | Y=80..208 |
+| Émeraude | 3 | 1 | Y=104..224 |
+
+Les hauteurs suivent une distribution en trapèze. Charbon, fer et cuivre
+reçoivent aussi respectivement 4, 2 et 2 essais sur roche supérieure exposée,
+et autant de recherches de corniche depuis l’air entre Y=64 et Y=288. Un essai
+peut ne produire aucun bloc. Les tailles configurées ne sont ni des quantités
+garanties par filon ni des quotas par île. L’exposition à l’air est autorisée
+pour ces trois minerais et l’émeraude ; une partie des candidats exposés est
+encore écartée pour les autres minerais. Les stocks devront être relevés après
+génération, avec leur emprise explicite.
+
+### Eaux et lave
+
+`RiftHydrology` cherche des bassins plus grands et une longue liaison calme
+sur la vraie densité fissurée. Le critère de cet incrément est un chemin d’eau
+continu d’au moins 140 blocs entre deux bassins au même niveau, alimenté par
+une source rocheuse et sa cascade entrante. Il ne s’agit pas d’une rivière
+descendant continuellement en altitude. La recherche parcourt huit directions
+et pondère les trajets selon le relief et un bruit ; le parcours retenu est
+lissé sur une échelle de 16 à 32 blocs, puis arrondi avant sa conversion en
+blocs. Le lit varie entre environ 5 et 7 blocs de largeur, hors élargissement
+des bassins. Le chemin et ses marges sont à nouveau vérifiés sur la roche
+après ce lissage : une courbe ne peut pas servir à franchir un trou.
+
+La roche doit soutenir le fond et les berges. L’incision du lit reste limitée
+à 16 blocs. Les berges de rivière peuvent retirer jusqu’à 12 blocs pour
+rejoindre l’eau par paliers progressifs ; les autres rives conservent leur
+limite de 2 blocs. Les dépôts de 3 à 5 couches ont toujours besoin de supports
+naturels. Aucun remblai ne franchit une faille ou un trou. Si aucun parcours
+compatible n’est retenu, le générateur garde les bassins et sources qui
+conviennent au relief.
+
+Le calcul initial du plan reste coûteux : les essais finaux sur ce poste
+mesurent 80,5 secondes pour la graine `0`, 50,7 pour `42` et 59,7 pour
+`8675309`, hors génération des chunks. Le résultat est mis en cache par état
+aléatoire du monde ; il n’est pas recalculé pour chaque chunk. L’optimisation
+de ce premier calcul reste un travail ultérieur.
+
+La recherche de lave profonde vise une à deux petites sources entre Y=40 et
+Y=160, en complément de la niche couverte accessible. Cette poche de 18 blocs
+sources est recherchée d’abord sur une corniche intérieure entre Y=64 et
+Y=160. Si aucun site profond ne réunit les conditions de support, de voûte
+et d’accès, la recherche reprend sur les corniches plus hautes, jusqu’à Y=300.
+Il n’y a pas de poche créée de force lorsque les deux recherches échouent.
+Les sources supplémentaires laissent Minecraft former leurs coulées par ses
+ticks, sans colonne préremplie. L’eau, les supports et les marges de végétation doivent être
+contrôlés après décoration et simulation. La finition des bouches doit rester
+limitée à la première génération du chunk, sans effacer un aménagement joueur
+lors d’un rechargement.
+
+**Validation du 9 septembre 2026 :** le build complet réussit et les contrôles
+moteur passent sur les trois graines de référence. Les failles, les bassins terminaux,
+les liaisons de rivière, les champignons et les fluides après 1 800 ticks sont
+documentés avec les relevés de ressources dans [Validation](testing.md).
+Ces échantillons ne garantissent pas la présence de chaque ressource sur
+toutes les graines. Les rapports intermédiaires ne servent pas de preuve
+pour la version finale ; aucun monde personnel n’est utilisé par ces tests.
 
 ## Sculpture du pourtour — conservée depuis la génération v2
 
@@ -119,8 +479,9 @@ ce gradient inférieur. Une nouvelle érosion travaille sur une transition de
 deux bruits de sculpture existants. Elle laisse les lobes naturels se poursuivre
 vers le bas, puis les amincit à différentes hauteurs ; elle n'ajoute ni socle ni
 surface garantie. La transition n'affecte plus le terrain à partir de `Y=144`.
-Une marge vide protège le bas de la dimension ; le contrôle des chunks terminés
-vérifie que la tranche `Y=0..15` ne contient aucun bloc.
+Une marge vide protège le bas de la dimension : aucun plancher rocheux ne doit
+apparaître dans `Y=0..15`. À partir de l’alpha.5, seules les eaux descendantes de
+sources explicitement déclarées peuvent traverser cette marge.
 
 Les champs optionnels du codec `vertical_offset`, `height` et `underside` valent
 respectivement `0`, `256` et un bruit nul par défaut. Seule la nouvelle fonction
@@ -174,9 +535,187 @@ plans d’eau ; il ne simule pas encore une pente vers l’aval ou un débit. Le
 tracés peuvent passer par les diagonales, mais leur eau reste connectée de
 bloc en bloc. L’excavation est limitée à six blocs, l’eau à quatre blocs de
 profondeur, avec un fond plein sur trois blocs d’épaisseur, dont deux blocs naturels sous
-le sédiment. Les grandes rivières en pente, cascades, océans, aquifères,
-climats multiples et continents restent des incréments distincts.
-**Créer un nouveau monde Sanctuary pour tester cette hydrologie.**
+le sédiment. Ce contrat alpha.4 reste celui de ses sauvegardes. Les sources en cascade sont
+ajoutées séparément dans la génération v5 ; les grandes rivières en pente, océans,
+aquifères, climats multiples et continents restent des incréments distincts.
+
+## Plages, sources et mosaïque tempérée — génération v5
+
+L’implémentation **0.1.0-alpha.5** sélectionne la nouvelle clé de paramètres
+`sanctuary:sanctuary_natural` (`SanctuarySpawn.NATURAL_SETTINGS`). Elle conserve
+la densité relevée, les 384 blocs de hauteur et le ciel de l’alpha.3. La classe
+`NaturalHydrology` et son application sont séparées de `SurfaceHydrology` et
+`HydrologyRuntime` : le code, les paramètres `sanctuary:sanctuary_hydrology` et
+le biome `sanctuary:starter_forest_hydrology` de l’alpha.4 restent inchangés.
+Les clés alpha.2 et alpha.3 restent également disponibles avec leur comportement
+antérieur. **Ces changements concernent uniquement les nouveaux mondes** : aucune
+conversion de sauvegarde, régénération de chunk ou expansion n’est effectuée.
+
+### Dépôts et eau de surface
+
+Le plan recherche des étangs, de petits lacs et un cours d’eau calme dans le
+relief naturel. L’excavation maximale passe à **quatre blocs**, pour une eau de
+**trois blocs de profondeur** au plus. Les bassins gardent un fond et des parois
+naturels pleins ; aucune digue n’est ajoutée et aucune chambre souterraine n’est
+remplie. Le cours d’eau reste à niveau constant : il ne modélise pas un débit
+ni une pente continue vers l’aval.
+
+Les plages sont des nappes irrégulières qui suivent les faibles variations du
+relief autour des plans d’eau. Elles peuvent s’étendre sur plusieurs blocs,
+se rapprocher d’une autre poche d’eau et retrouver progressivement l’herbe ou
+la pierre. Les matériaux varient entre sable, gravier, pierre et terre enherbée ;
+l’argile peut apparaître dans les fonds. Le traitement d’une terrasse sèche
+retire au plus **deux blocs** du relief existant.
+
+Chaque dépôt remplace **trois à cinq couches** de terrain déjà plein et garde
+**deux couches naturelles de support** en dessous. Ce support permet notamment
+au sable et au gravier de rester en place après les mises à jour de gravité.
+Les veines de gravier, disques de sédiments et magma sous-marin vanilla ne sont
+pas réintroduits dans ces nouveaux biomes. Les autres décorations rocheuses et
+les minerais peuvent encore remplacer la pierre ; ils ne remplacent pas les
+couches de sable, gravier ou argile. Les rives compatibles peuvent porter de la
+canne à sucre après la végétation. Les troncs couchés vanilla peuvent occuper
+quelques blocs de la surface d’un étang ; les contrôles distinguent cette
+décoration de l’eau restante et vérifient leur fond ou l’eau sous les troncs,
+les sources voisines et la rétention du bassin.
+
+### Sources rocheuses et cascades
+
+Le plan peut retenir jusqu’à **trois sources** dans des niches rocheuses
+naturelles, séparées des dépôts modifiés. Une source remplace un seul bloc de
+roche, sous un toit, sur un fond et entre trois côtés déjà pleins. Son unique
+sortie horizontale est naturellement ouverte sur une chute d’au moins huit
+blocs. Le générateur ne construit ni pylône, ni corniche, ni tunnel pour obtenir
+ce résultat.
+
+Seul le bloc source est généré. Les ticks de fluide de Minecraft forment la
+cascade et ses éventuels passages sur des paliers. Ces écoulements peuvent
+descendre **jusque dans le vide**, conformément au comportement demandé. Cette
+exception concerne les sources déclarées. Le trajet calculé dans la roche nue
+est une prévision : les arbres générés ensuite peuvent dévier une chute. Les
+diagnostics vérifient donc les connexions réelles de chaque bloc d’eau vers une
+source, dans l’emprise des chunks inspectés et de leur halo. Ils échouent si de
+l’eau touche une frontière non inspectée ou si un bassin perd sa coque. Les
+déviations par rapport à la prévision restent mesurées dans le rapport. Le
+comportement des fluides reste celui de Minecraft, y compris lorsque les joueurs
+modifient une rive.
+
+### Petite réserve de lave
+
+`StarterLavaDeposit` recherche au plus une niche de **18 blocs sources** dans
+la roche existante, accessible par un passage sec de deux blocs de haut depuis
+une corniche naturelle. Le fond garde trois blocs pleins, les parois deux et
+la couverture huit ; ces supports sont vérifiés avant les écritures. La niche
+reste éloignée des eaux et de leurs parcours. Elle fournit de la lave prélevable
+pour les premières productions et un portail du Nether. Si aucun site ne
+convient, le plan reste vide : aucun bassin artificiel n’est ajouté dans le vide.
+
+Les tests vérifient l’accès praticable, la rétention de la lave et l’absence
+d’incendie après simulation.
+
+### Biomes et minerais
+
+Le biome source `sanctuary:temperate_island` utilise deux champs de bruit
+initialisés par la seed pour répartir cinq variantes horizontales. Une rive et
+la roche sous elle restent dans la même variante :
+
+| Identifiant | Variante |
+| --- | --- |
+| `sanctuary:temperate_forest` | Forêt dominante |
+| `sanctuary:temperate_plains` | Clairières et plaines tempérées |
+| `sanctuary:temperate_birch_forest` | Forêt de bouleaux |
+| `sanctuary:temperate_flower_forest` | Forêt fleurie |
+| `sanctuary:temperate_dappled_forest` | Dappled Forest, peupliers et végétation associée |
+
+Dappled Forest est un biome vanilla introduit dans
+[Minecraft 26.3 Snapshot 1](https://www.minecraft.net/en-us/article/minecraft-26-3-snapshot-1).
+Cette variante reprend ses données de **26.3-pre-2**, avec une humidité légèrement
+relevée pour Sanctuary. Elle n’ajoute ni dépendance externe ni structure de camp.
+La palette tempérée ne constitue pas encore le catalogue TerraMix ni le champ
+climatique des futurs continents.
+
+Les nouveaux biomes remplacent les filons vanilla de métaux par de petites
+features `sanctuary:island_ore_*`, à des altitudes adaptées à l’île relevée :
+
+| Ressource | Taille du filon | Tentatives par chunk | Plage Y |
+| --- | --- | --- | --- |
+| Charbon | 6 | 2 | 96–288 |
+| Fer | 4 | 2 | 88–248 |
+| Cuivre | 4 | 1 | 96–248 |
+| Or | 4 | 1 | 104–224 |
+| Redstone | 4 | 1 | 96–224 |
+| Lapis | 3 | Une tentative, chance 1/2 | 112–232 |
+| Diamant | 3 | Une tentative, chance 1/4 | 104–208 |
+
+Ces paramètres décrivent des tentatives, pas des quantités promises : le filon
+doit rencontrer la roche existante, et sa forme dépend du hasard de génération.
+La sélection des biomes et des eaux ne cherche aucun stock cible. Un relevé
+partiel reste un relevé partiel ; la présence des sept ressources sur une seed
+de référence ne garantit pas leur présence sur toutes les seeds.
+
+La validation de l’alpha.5 est suivie dans [Validation](testing.md). Ses diagnostics
+sont conçus pour inspecter les blocs décorés, les profils des dépôts, les
+jointures de chunks, les biomes et les ressources, puis simuler réellement les
+fluides dans les chunks des sites. Les cartes et profils PNG montrent des
+lectures de blocs, pas un rendu Minecraft. La descente des
+cascades est contrôlée après activation effective des chunks qui les simulent.
+
+## Prairies et corniches — génération v6
+
+L’alpha.6 utilise `sanctuary:sanctuary_layered` et le biome source
+`sanctuary:layered_island`. Les formes et le ciel restent ceux de la génération
+relevée. Les anciennes classes, biomes et règles de matériaux restent disponibles
+pour les sauvegardes alpha.2 à alpha.5 ; seul le preset de création choisit v6.
+
+### Une palette qui varie aussi en hauteur
+
+Les cinq variantes partagent leurs teintes d’herbe et de feuillage. Les champs
+de climat liés à la seed déforment de larges bandes d’altitude, autour de Y154
+et Y214 : prairies et prairies fleuries sur le dessus, bosquets et corniches
+moussues plus bas. Des zones rocheuses traversent ces bandes et remplacent la
+couverture de terre par de la pierre sur le relief existant. Les prairies gardent
+quelques arbres épars et leur végétation vanilla. Dappled Forest n’appartient
+plus à cette palette ; son utilisation sur de futurs continents reste à développer.
+
+| Identifiant | Ambiance |
+| --- | --- |
+| `sanctuary:layered_meadow` | Prairie tempérée |
+| `sanctuary:layered_flower_meadow` | Prairie fleurie |
+| `sanctuary:layered_lower_grove` | Bosquet inférieur |
+| `sanctuary:layered_mossy_terraces` | Corniches moussues |
+| `sanctuary:layered_rocky_terraces` | Affleurements rocheux |
+
+`LowerTerraceVegetationFeature` parcourt aussi les sols naturels sous les
+surplombs, au moins huit blocs sous une surface supérieure. Elle demande trois
+blocs pleins de support et deux blocs libres au-dessus. Elle peut remplacer la
+surface existante par de la mousse et planter fougères, fleurs ou petits arbustes
+lorsque leurs règles de survie le permettent. Les cellules hydrologiques, les
+sources, les parcours d’eau prévus et les supports de lave sont protégés.
+Il n’y a ni corniche construite dans l’air ni ajout d’éclairage artificiel.
+
+### Bassins et sources de paroi
+
+`LayeredHydrology` conserve les petits bassins et les dépôts épais, avec une
+plus grande présence de pierre. Le court `STREAM` à niveau constant de l’alpha.5
+n’est pas repris. Cette version retient uniquement les étangs et les petits
+lacs ; elle ne cherche pas de grande rivière. Le parcours traversant avec
+source, cascade et bassin reste un ticket distinct, à démontrer sur le relief
+Minecraft réel. Aucun chenal de secours n’est creusé.
+
+La profondeur reste limitée à trois blocs et l’incision à quatre. Le plan
+vérifie le fond et les rives avant d’appliquer ses écritures, dans les nouveaux
+chunks seulement. Le sable, le gravier, l’argile et la roche suivent les rives.
+Des niches de source sont également recherchées dans les strates inférieures,
+et pas seulement près de la surface la plus haute. Leurs chutes sont produites
+par les ticks de Minecraft à partir d’un seul bloc source. Le post-traitement
+des nouveaux chunks libère uniquement leur ouverture, déjà vide dans la densité
+naturelle, pour qu’un lichen ou une plante ne bouche pas la source. Les positions
+sont marquées dans la file vanilla pendant la génération, puis consommées une
+seule fois. Un rechargement ne dégage pas une bouche modifiée par un joueur.
+Aucune chute n’est préremplie et aucun nouveau passage n’est creusé dans la roche.
+
+Les parcours, les écoulements et la végétation réellement observés, ainsi que
+les limites du modèle, sont consignés dans [Validation](testing.md).
 
 ## Apparition commune
 
@@ -187,7 +726,8 @@ l'absence d'une telle surface, elle retient une colonne de sol praticable ; si
 aucun emplacement naturel sûr n'existe, la création signale la seed concernée
 plutôt que d'ajouter une plateforme. Elle ne s'applique qu'à l'Overworld
 utilisant les paramètres `sanctuary:sanctuary`, `sanctuary:sanctuary_384` ou
-`sanctuary:sanctuary_hydrology`.
+`sanctuary:sanctuary_hydrology`, `sanctuary:sanctuary_natural` ou
+`sanctuary:sanctuary_layered`.
 Elle enregistre le spawn partagé dans la sauvegarde et ne le réinitialise pas
 au redémarrage : les modifications administratives de `/setworldspawn` restent
 conservées. Les lits et la dispersion habituelle du spawn suivent encore les
@@ -266,3 +806,66 @@ chunks sauvegardés.
 La version de génération et les emprises doivent être gelées avant les premières
 sauvegardes destinées à durer. Ce prototype ne promet pas encore de migration
 automatique des mondes entre deux versions de terrain.
+
+
+## Forêts, corniches humides et affleurements — génération v7
+
+L’alpha.7 crée les nouveaux mondes avec `sanctuary:sanctuary_woodland` et
+`sanctuary:woodland_island`. La densité `sanctuary:final_density_384`, les
+formes rocheuses, la hauteur et le ciel restent identiques. Les plans des
+bassins, sources et petites niches de lave reprennent les algorithmes alpha.6.
+Les anciens paramètres, biomes et features sont conservés ; cette livraison
+ne modifie pas les mondes existants.
+
+La palette comporte huit biomes :
+
+| Identifiant | Rôle |
+| --- | --- |
+| `sanctuary:woodland_oak_forest` | Forêt de chênes dominante, bouleaux secondaires |
+| `sanctuary:woodland_birch_forest` | Forêt de bouleaux complémentaire |
+| `sanctuary:woodland_clearing` | Clairière fleurie |
+| `sanctuary:woodland_dry_woodland` | Bois sec plus clairsemé |
+| `sanctuary:woodland_rocky_heath` | Masses rocheuses exposées |
+| `sanctuary:woodland_dark_grove` | Corniches humides à chênes noirs et champignons |
+| `sanctuary:woodland_bamboo_grove` | Rare intérieur à jungle et bambou |
+| `sanctuary:woodland_sulfur_depths` | Rare poche profonde de soufre sur roche existante |
+
+Une altitude élevée ne transforme plus automatiquement une forêt en prairie
+ou en roche. Les forêts utilisent les véritables arbres vanilla avec leurs
+conditions de croissance ; les affleurements sont des patches horizontaux
+et des variations de matériau sur le terrain existant.
+
+`woodland_groves` place de vrais chênes noirs sur des sols naturels de 2×2,
+avec trois blocs de support et une place suffisante pour le tronc et la
+canopée sous le plafond. Des champignons accompagnent les sols de podzol et
+de mycélium, avec quelques touches de mousse. La jungle et le bambou restent
+limités aux rares poches qui leur conviennent.
+
+Un seul emplacement remarquable est recherché par graine, avec une essence
+choisie parmi cerisier (favorisé), épicéa, jungle, acacia, palétuvier et chêne
+pâle. Il ne produit pas de terrain : si le site ou les conditions de l’arbre
+vanilla ne conviennent pas, il ne pousse pas. Ce n’est pas une garantie de
+chaque essence sur chaque île. Aucun cœur de Creaking n’est ajouté par l’arbre
+pâle utilisé ici.
+
+Les affleurements mêlent des nappes cohérentes de pierre, andésite, diorite et
+granite. Les berges conservent leur excavation limitée et leurs dépôts de
+3 à 5 blocs, avec des patches de sable, gravier, argile et roche. Les plantations de `woodland_groves` évitent les sources, leurs exutoires
+et les niches de lave. Les décorations vanilla conservent leurs placements ;
+le traitement unique après génération peut rouvrir la seule bouche de source
+déclarée si une plante l’obstrue. Le soufre
+reste une matière rare des profondeurs ; les grands bassins et sources
+vanilla du biome Sulfur Caves ne sont pas activés.
+
+Les anciens petits filons souterrains de charbon, fer et cuivre étaient peu
+susceptibles d’atteindre les surfaces hautes ; leur réglage écartait aussi une
+partie des blocs voisins de l’air. Les nouvelles features `woodland_ore_*`
+utilisent des tailles vanilla limitées (`size=6` pour le charbon, `size=5`
+pour fer/cuivre), sans garantir ce nombre de blocs produits par filon,
+autorisent cette exposition et ajoutent des essais aléatoires sur les roches
+de surface et les corniches rencontrées depuis l’air. Elles remplacent
+seulement les roches naturelles reconnues par Minecraft, dont andésite,
+diorite et granite. Les autres minerais et les anciens générateurs gardent
+leurs réglages ; aucune quantité cible n’est réinjectée après mesure.
+
+La version et les graines de validation sont consignées dans [Validation](testing.md).

gradle.properties

@@ -8,6 +8,6 @@ loader_version=0.19.5
 loom_version=1.17.20
 fabric_api_version=0.160.0+26.3
 
-mod_version=0.1.0-alpha.4
-pack_version=0.1.0-alpha.4
+mod_version=0.1.0-alpha.13.1
+pack_version=0.1.0-alpha.13.1
 maven_group=fr.koka.sanctuary

mods/sanctuary/build.gradle

@@ -26,15 +26,37 @@ if (clientRenderTests) {
     }
 }
 
-// Every integration run must exercise fresh generation, never stale saved chunks.
+// Fresh generation by default; the explicit laboratory reload verifies the same saved test world.
 tasks.register('cleanGameTestWorld', Delete) {
+    onlyIf { !providers.gradleProperty('sanctuaryExpansionReload').map { it.toBoolean() }.getOrElse(false) }
     delete(layout.buildDirectory.dir('run/gameTest/world'))
 }
 tasks.named('runGameTest') {
     dependsOn('cleanGameTestWorld')
     systemProperty('sanctuary.test.seed', providers.gradleProperty('sanctuaryTestSeed').getOrElse('0'))
+    systemProperty('sanctuary.test.players', providers.gradleProperty('sanctuaryTestPlayers').getOrElse('10'))
     systemProperty('sanctuary.test.resourceSurvey', providers.gradleProperty('sanctuaryResourceSurvey').getOrElse('sample'))
     systemProperty('sanctuary.test.densityMaps', providers.gradleProperty('sanctuaryDensityMaps').getOrElse('true'))
+    systemProperty('sanctuary.test.unified', providers.gradleProperty('sanctuaryUnifiedTests').getOrElse('true'))
+    systemProperty('sanctuary.test.diameter', providers.gradleProperty('sanctuaryTestDiameter').getOrElse('724'))
+    systemProperty('sanctuary.test.expansion', providers.gradleProperty('sanctuaryExpansionTests').getOrElse('false'))
+    systemProperty('sanctuary.test.expansionReload', providers.gradleProperty('sanctuaryExpansionReload').getOrElse('false'))
+    systemProperty('sanctuary.test.optionalStructureWitness', providers.gradleProperty('sanctuaryOptionalStructureWitness').getOrElse('false'))
+}
+
+tasks.named('processGametestResources') {
+    def benchmark = providers.gradleProperty('sanctuaryBenchmark').map { it.toBoolean() }.getOrElse(false)
+    inputs.property('benchmark', benchmark)
+    def unified = providers.gradleProperty('sanctuaryUnifiedTests').map { it.toBoolean() }.getOrElse(true)
+    inputs.property('unified', unified)
+    def expansion = providers.gradleProperty('sanctuaryExpansionTests').map { it.toBoolean() }.getOrElse(false)
+    inputs.property('expansion', expansion)
+    filesMatching('fabric.mod.json') {
+        expand(gametest_entrypoint: expansion ? 'fr.koka.sanctuary.gametest.ExpansionWorldGameTests' : benchmark
+            ? 'fr.koka.sanctuary.gametest.WorldgenPerformanceGameTests'
+            : unified ? 'fr.koka.sanctuary.gametest.UnifiedWorldGameTests'
+            : 'fr.koka.sanctuary.gametest.SanctuaryWorldGameTests')
+    }
 }
 
 dependencies {
@@ -89,3 +111,166 @@ tasks.named('check') { dependsOn('hydrologySmoke') }
 
 // src/test contains a JavaExec assertion harness; engine tests use Fabric's gametest source set.
 tasks.named('test') { failOnNoDiscoveredTests = false }
+
+tasks.register('naturalHydrologySmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check broad shores, supported sediments and natural rock springs.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.NaturalHydrologySmoke'
+}
+
+tasks.named('check') { dependsOn('naturalHydrologySmoke') }
+
+tasks.register('starterLavaSmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check a small contained lava niche in naturally supported rock.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.StarterLavaDepositSmoke'
+}
+
+tasks.named('check') { dependsOn('starterLavaSmoke') }
+
+// Alpha.6 has separate contracts so saved alpha.5 worlds keep their generation.
+tasks.register('layeredHydrologySmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check retained basins, broad rock shores and lower wall springs.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.LayeredHydrologySmoke'
+}
+
+tasks.named('check') { dependsOn('layeredHydrologySmoke') }
+
+tasks.register('layeredEcologySmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check altitude biome variation and naturally supported lower terraces.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.LayeredEcologySmoke'
+}
+
+tasks.named('check') { dependsOn('layeredEcologySmoke') }
+
+// Alpha.7 keeps previous biome palettes and generators unchanged.
+tasks.register('woodlandPaletteSmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check surface forest coverage and bounded rare interior biomes.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.WoodlandPaletteSmoke'
+}
+tasks.register('woodlandGroveSmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check natural tree supports and canopy space without creating terrain.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.WoodlandGroveSmoke'
+}
+tasks.named('check') { dependsOn('woodlandPaletteSmoke', 'woodlandGroveSmoke') }
+
+tasks.register('riftShapeSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.RiftShapeSmoke'
+}
+tasks.named('check') { dependsOn('riftShapeSmoke') }
+
+tasks.register('riftPaletteSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.RiftPaletteSmoke'
+}
+tasks.named('check') { dependsOn('riftPaletteSmoke') }
+
+tasks.register('riftHydrologySmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.RiftHydrologySmoke'
+}
+tasks.named('check') { dependsOn('riftHydrologySmoke') }
+
+tasks.register('riftLavaSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.RiftLavaSmoke'
+}
+tasks.named('check') { dependsOn('riftLavaSmoke') }
+
+tasks.register('cavernPaletteSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.CavernPaletteSmoke'
+}
+tasks.named('check') { dependsOn('cavernPaletteSmoke') }
+
+tasks.register('cavernHydrologySmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.CavernHydrologySmoke'
+}
+tasks.named('check') { dependsOn('cavernHydrologySmoke') }
+
+tasks.register('cavernLavaSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.CavernLavaSmoke'
+}
+tasks.named('check') { dependsOn('cavernLavaSmoke') }
+
+tasks.register('populationCapacitySmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check supported capacities, area scaling, finite boundaries and regional ownership.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.PopulationCapacitySmoke'
+}
+tasks.named('check') { dependsOn('populationCapacitySmoke') }
+
+tasks.register('populationRegionPlanSmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check atomic regional admission, hydraulic dependencies and translated chunk indices.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.PopulationRegionPlanSmoke'
+}
+tasks.named('check') { dependsOn('populationRegionPlanSmoke') }
+
+tasks.register('populationPlanCacheSmoke', JavaExec) {
+    group = 'verification'
+    description = 'Check that completed regions remain readable while new regions are planned.'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.worldgen.PopulationPlanCacheSmoke'
+}
+tasks.named('check') { dependsOn('populationPlanCacheSmoke') }
+
+tasks.register('expansionJournalSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.expansion.ExpansionJournalSmoke'
+}
+tasks.register('expansionReliefSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.expansion.ExpansionReliefSmoke'
+}
+tasks.named('check') { dependsOn('expansionJournalSmoke', 'expansionReliefSmoke') }
+
+tasks.register('expansionPlacementSmoke', JavaExec) {
+    group = 'verification'
+    dependsOn('testClasses')
+    classpath = sourceSets.test.runtimeClasspath
+    mainClass = 'fr.koka.sanctuary.expansion.ExpansionPlacementSmoke'
+}
+tasks.named('check') { dependsOn('expansionPlacementSmoke') }

mods/sanctuary/src/clientGametest/java/fr/koka/sanctuary/gametest/SanctuaryClientRenderTests.java

@@ -16,6 +16,7 @@ public final class SanctuaryClientRenderTests implements FabricClientGameTest {
                     "net.minecraft.client.renderer.fog.FogRenderer", "sanctuary$openVoidFog");
             SanctuaryMod.LOGGER.info("Client render tests passed: Sanctuary sky and fog mixins applied.");
         });
+        SanctuaryWorldOptionsClientChecks.run(context);
     }
 
     private static void assertApplied(ClassLoader loader, String target, String hook) {

mods/sanctuary/src/clientGametest/java/fr/koka/sanctuary/gametest/SanctuaryWorldOptionsClientChecks.java

@@ -0,0 +1,179 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import com.mojang.blaze3d.platform.InputConstants;
+import com.mojang.serialization.JsonOps;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.client.SanctuaryWorldOptionsScreen;
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import net.fabricmc.fabric.api.client.gametest.v1.context.ClientGameTestContext;
+import net.minecraft.client.gui.components.CycleButton;
+import net.minecraft.client.gui.components.tabs.TabNavigationBar;
+import net.minecraft.client.gui.screens.Screen;
+import net.minecraft.client.gui.screens.worldselection.CreateWorldScreen;
+import net.minecraft.client.gui.screens.worldselection.WorldCreationUiState;
+import net.minecraft.client.input.KeyEvent;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.world.level.dimension.LevelStem;
+import net.minecraft.world.level.levelgen.WorldGenSettings;
+import net.minecraft.world.level.storage.LevelStorageSource;
+
+/** The real new-world button path and saved settings, without starting or opening a game world. */
+final class SanctuaryWorldOptionsClientChecks {
+    private static final KeyEvent PRESS = new KeyEvent(InputConstants.KEY_RETURN, 0, 0);
+
+    static void run(ClientGameTestContext context) {
+        Screen previous = context.computeOnClient(client -> client.gui.screen());
+        context.runOnClient(client -> CreateWorldScreen.openFresh(client, () -> client.gui.setScreen(previous)));
+        context.waitFor(client -> client.gui.screen() instanceof CreateWorldScreen, 1200);
+        CreateWorldScreen create = context.computeOnClient(client -> (CreateWorldScreen) client.gui.screen());
+        List<Map<String, Object>> savedSizes = new ArrayList<>();
+        try {
+            context.runOnClient(client -> {
+                TabNavigationBar tabs = create.children().stream().filter(TabNavigationBar.class::isInstance)
+                        .map(TabNavigationBar.class::cast).findFirst().orElseThrow();
+                tabs.selectTab(1, false); // The vanilla World tab owns the world type and Customize widgets.
+                var state = create.getUiState();
+                long sanctuaryChoices = state.getNormalPresetList().stream().filter(entry -> entry.preset() != null
+                        && entry.preset().getRegisteredName().startsWith("sanctuary:")).count();
+                require(sanctuaryChoices == 1, "Exactly one public Sanctuary choice must remain");
+                require(state.getAltPresetList().stream().filter(entry -> entry.preset() != null
+                                && entry.preset().getRegisteredName().startsWith("sanctuary:")).count() == 1,
+                        "The extended world-type cycle must not expose the old laboratory or sizes");
+                CycleButton<?> worldType = create.children().stream().filter(CycleButton.class::isInstance)
+                        .map(CycleButton.class::cast)
+                        .filter(button -> button.getValue() instanceof WorldCreationUiState.WorldTypeEntry)
+                        .findFirst().orElseThrow();
+                int attempts = state.getNormalPresetList().size();
+                while (!isSanctuary(state) && attempts-- > 0) worldType.onPress(PRESS);
+                require(isSanctuary(state), "The real world-type cycle must reach Sanctuary");
+                require(diameter(create) == 724, "Sanctuary defaults to Medium");
+                state.setSeed("42");
+                state.setGenerateStructures(false);
+                state.setBonusChest(true);
+            });
+
+            // Cancel and Escape both leave the pending generator untouched.
+            context.clickScreenButton("selectWorld.customizeType");
+            context.waitForScreen(SanctuaryWorldOptionsScreen.class);
+            context.runOnClient(client -> chooseSize(client.gui.screen(), "LARGE"));
+            context.clickScreenButton("gui.cancel");
+            context.runOnClient(client -> require(diameter(create) == 724, "Cancel must not apply Large"));
+            context.clickScreenButton("selectWorld.customizeType");
+            context.runOnClient(client -> {
+                chooseSize(client.gui.screen(), "SMALL");
+                client.gui.screen().keyPressed(new KeyEvent(InputConstants.KEY_ESCAPE, 0, 0));
+                require(client.gui.screen() == create && diameter(create) == 724,
+                        "Escape must return to creation without applying Small");
+            });
+
+            Path diagnostics = Path.of("diagnostics").toAbsolutePath();
+            Files.createDirectories(diagnostics);
+            Path testRoot = Files.createTempDirectory(diagnostics, "world-options-settings-");
+            var storage = LevelStorageSource.createDefault(testRoot);
+            for (var size : Map.of("SMALL", 512, "MEDIUM", 724, "LARGE", 1024).entrySet()) {
+                var before = context.computeOnClient(client -> create.getUiState().getSettings());
+                context.clickScreenButton("selectWorld.customizeType");
+                context.waitForScreen(SanctuaryWorldOptionsScreen.class);
+                context.runOnClient(client -> chooseSize(client.gui.screen(), size.getKey()));
+                context.clickScreenButton("gui.done");
+                context.runOnClient(client -> {
+                    require(client.gui.screen() == create && diameter(create) == size.getValue(),
+                            "Done must apply the chosen diameter and return to creation");
+                    var after = create.getUiState().getSettings();
+                    require(after.options().equals(before.options()), "Size must preserve seed, structures and bonus chest");
+                    for (var dimension : List.of(LevelStem.NETHER, LevelStem.END)) {
+                        require(after.selectedDimensions().get(dimension).equals(before.selectedDimensions().get(dimension)),
+                                "Size must preserve other dimensions");
+                    }
+                    require(isSanctuary(create.getUiState()), "Customization must keep the single Sanctuary world type");
+                    create.getUiState().setSettings(after.withOptions(options -> options));
+                    require(diameter(create) == size.getValue(),
+                            "Refreshing world settings must preserve the custom size instead of restoring the preset default");
+                    String name = size.getKey().toLowerCase(java.util.Locale.ROOT);
+                    var settings = new WorldGenSettings(after.options(), after.selectedDimensions());
+                    try (var save = storage.createAccess(name)) {
+                        LevelStorageSource.writeWorldGenSettings(after.worldgenLoadContext(), storage.getLevelPath(name), settings);
+                        var restored = LevelStorageSource.readExistingSavedData(save, after.worldgenLoadContext(),
+                                WorldGenSettings.TYPE).getOrThrow();
+                        require(restored.dimensions().overworld() instanceof SanctuaryChunkGenerator generator
+                                && generator.initialDiameter() == size.getValue(), "Selected size must survive actual settings storage");
+                        var ops = RegistryOps.create(JsonOps.INSTANCE, after.worldgenLoadContext());
+                        require(WorldGenSettings.CODEC.encodeStart(ops, restored).getOrThrow()
+                                        .equals(WorldGenSettings.CODEC.encodeStart(ops, settings).getOrThrow()),
+                                "Stored options and dimensions must remain unchanged");
+                        savedSizes.add(Map.of("size", name, "diameter", size.getValue(), "disk_round_trip", true));
+                    }
+                });
+                context.clickScreenButton("selectWorld.customizeType");
+                context.runOnClient(client -> require(sizeButton(client.gui.screen()).getValue().toString().equals(size.getKey()),
+                        "Reopening Customize must restore the saved selection"));
+                if (size.getKey().equals("MEDIUM")) context.takeScreenshot("sanctuary-world-options-medium");
+                context.clickScreenButton("gui.cancel");
+            }
+
+            context.runOnClient(client -> {
+                var state = create.getUiState();
+                var settings = state.getSettings();
+                var presets = settings.worldgenLoadContext().lookupOrThrow(Registries.WORLD_PRESET);
+                var legacy = presets.getOrThrow(ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id("sanctuary_5")))
+                        .value().createWorldDimensions().overworld();
+                state.updateDimensions((registries, dimensions) -> dimensions.replaceOverworldGenerator(registries, legacy));
+                require(state.getPresetEditor() == null,
+                        "A legacy generator under the public key must not gain an implicit conversion editor");
+                state.setSettings(settings);
+                var flat = presets.getOrThrow(net.minecraft.world.level.levelgen.presets.WorldPresets.FLAT);
+                state.setWorldType(new WorldCreationUiState.WorldTypeEntry(flat));
+                require(state.getPresetEditor() != null
+                        && !(state.getPresetEditor().createEditScreen(create, state.getSettings()) instanceof SanctuaryWorldOptionsScreen),
+                        "Vanilla flat-world customization must remain available");
+            });
+            Files.writeString(diagnostics.resolve("sanctuary-world-options-client.json"),
+                    new GsonBuilder().setPrettyPrinting().create().toJson(Map.of(
+                            "public_sanctuary_choices", 1, "default_diameter", 724,
+                            "saved_sizes", savedSizes, "cancel_and_escape_preserved", true,
+                            "settings_refresh_preserved", true,
+                            "legacy_editor_guard", true, "vanilla_editor_preserved", true,
+                            "test_settings_directory", testRoot.toString(), "passed", true)) + "\n");
+            SanctuaryMod.LOGGER.info("Sanctuary world options client tests passed: one world type, three saved sizes, Done/Cancel/Escape.");
+        } catch (IOException failure) {
+            throw new AssertionError("Unable to verify the selected world settings on disk", failure);
+        } finally {
+            context.runOnClient(client -> create.onClose());
+        }
+    }
+
+    private static boolean isSanctuary(WorldCreationUiState state) {
+        var preset = state.getWorldType().preset();
+        return preset != null && preset.getRegisteredName().equals("sanctuary:sanctuary");
+    }
+
+    private static int diameter(CreateWorldScreen create) {
+        return ((SanctuaryChunkGenerator) create.getUiState().getSettings().selectedDimensions().overworld()).initialDiameter();
+    }
+
+    private static CycleButton<?> sizeButton(Screen screen) {
+        require(screen instanceof SanctuaryWorldOptionsScreen, "Customize must open the Sanctuary screen");
+        return screen.children().stream().filter(CycleButton.class::isInstance).map(CycleButton.class::cast)
+                .findFirst().orElseThrow();
+    }
+
+    private static void chooseSize(Screen screen, String target) {
+        CycleButton<?> button = sizeButton(screen);
+        int attempts = 3;
+        while (!button.getValue().toString().equals(target) && attempts-- > 0) button.onPress(PRESS);
+        require(button.getValue().toString().equals(target), "Size cycle must expose " + target);
+    }
+
+    private static void require(boolean condition, String message) {
+        if (!condition) throw new AssertionError(message);
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/Alpha10PopulationDensityReference.java

@@ -0,0 +1,70 @@
+// Frozen test oracle from a26b72f PopulationIslandDensity.java.
+// Original SHA-256: fcc5a8a39b7c4d181d74ce4f9183a1ca93646137955ac64bab9d22e6db0752a1
+// Only package/imports/class name differ; do not optimize this reference.
+package fr.koka.sanctuary.gametest;
+
+import fr.koka.sanctuary.worldgen.*;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.concurrent.ConcurrentHashMap;
+import net.minecraft.util.Interval;
+import net.minecraft.world.level.levelgen.densityfunction.*;
+
+/** Capacity changes the envelope; all natural noise is still sampled at world coordinates. */
+public record Alpha10PopulationDensityReference(DensityFunction terrain, DensityFunction distortion,
+        DensityFunction sculpt, DensityFunction detail, DensityFunction underside,
+        DensityFunction riftWarp, DensityFunction riftDetail, IslandCapacity capacity) implements DensityFunction {
+    public static final MapCodec<Alpha10PopulationDensityReference> CODEC = RecordCodecBuilder.mapCodec(instance -> instance.group(
+        DensityFunction.CODEC.fieldOf("terrain").forGetter(Alpha10PopulationDensityReference::terrain),
+        DensityFunction.CODEC.fieldOf("distortion").forGetter(Alpha10PopulationDensityReference::distortion),
+        DensityFunction.CODEC.fieldOf("sculpt").forGetter(Alpha10PopulationDensityReference::sculpt),
+        DensityFunction.CODEC.fieldOf("detail").forGetter(Alpha10PopulationDensityReference::detail),
+        DensityFunction.CODEC.fieldOf("underside").forGetter(Alpha10PopulationDensityReference::underside),
+        DensityFunction.CODEC.fieldOf("rift_warp").forGetter(Alpha10PopulationDensityReference::riftWarp),
+        DensityFunction.CODEC.fieldOf("rift_detail").forGetter(Alpha10PopulationDensityReference::riftDetail),
+        IslandCapacity.CODEC.optionalFieldOf("players", IslandCapacity.TWENTY).forGetter(Alpha10PopulationDensityReference::capacity)
+    ).apply(instance, Alpha10PopulationDensityReference::new));
+
+    @Override public DensitySampler compileSampler(CompileContext context) {
+        var raw = terrain.compileSampler(context); var edge = distortion.compileSampler(context);
+        var coarse = sculpt.compileSampler(context); var fine = detail.compileSampler(context);
+        var bottom = underside.compileSampler(context); var warp = riftWarp.compileSampler(context);
+        var fractureDetail = riftDetail.compileSampler(context);
+        long seed = context.createRandom(SanctuaryMod.id("population_rifts_alpha10")).nextLong();
+        var layouts = new ConcurrentHashMap<IslandCapacity.Region, RiftShape.Layout>();
+        return new DensitySampler() {
+            @Override public float sampleValue(SamplerContext sample, int x, int y, int z) {
+                if (Math.hypot((double) x, z) >= capacity.terrainLimit() || y <= 0 || y >= 384) return -1;
+                int localY = y - 64;
+                float natural = PopulationIslandShape.raisedDensity(x, y, z, raw.sampleValue(sample, x, localY, z),
+                    edge.sampleValue(sample, x, 0, z), coarse.sampleValue(sample, x, localY, z),
+                    fine.sampleValue(sample, x, localY, z), bottom.sampleValue(sample, x, localY, z), 64, 384, capacity);
+                if (natural <= 0) return natural;
+                var region = capacity.regionAt(x, z);
+                var layout = layouts.computeIfAbsent(region, r -> RiftShape.layout(regionSeed(seed, r)));
+                int rx = x - region.originX(), rz = z - region.originZ();
+                if (!RiftShape.mayAffect(layout, rx, rz)) return natural;
+                return RiftShape.density(layout, rx, y, rz, natural,
+                    warp.sampleValue(sample, x, y, z), fractureDetail.sampleValue(sample, x, y, z));
+            }
+            @Override public void sampleVolume(SamplerContext sample, DensityBuffer buffer, DensityVolume volume) {
+                DensitySampler.sampleVolumeNaive(sample, buffer, volume, this);
+            }
+        };
+    }
+    public static long regionSeed(long seed, IslandCapacity.Region region) {
+        long value = seed ^ ((long) region.x() << 32) ^ (region.z() & 0xffffffffL) ^ 0xA10CA7E1L;
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+    @Override public DensityFunction rewriteChildren(DfRewriteRule rule) {
+        return new Alpha10PopulationDensityReference(rule.rewrite(terrain), rule.rewrite(distortion), rule.rewrite(sculpt),
+            rule.rewrite(detail), rule.rewrite(underside), rule.rewrite(riftWarp), rule.rewrite(riftDetail), capacity);
+    }
+    @Override public Interval range() { return Interval.of(-1, 1); }
+    @Override public int domainAxes() { return ALL_AXES; }
+    @Override public MapCodec<Alpha10PopulationDensityReference> codec() { return CODEC; }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/ExpansionCommandChecks.java

@@ -0,0 +1,139 @@
+package fr.koka.sanctuary.gametest;
+
+import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+import fr.koka.sanctuary.expansion.ExpansionIsland;
+import fr.koka.sanctuary.expansion.ExpansionRuntime;
+import java.io.IOException;
+import java.util.ArrayList;
+import net.minecraft.commands.CommandSource;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.network.chat.Component;
+import net.minecraft.network.chat.contents.TranslatableContents;
+import net.minecraft.server.level.ChunkLevel;
+import net.minecraft.server.permissions.LevelBasedPermissionSet;
+import net.minecraft.server.permissions.PermissionLevel;
+import net.minecraft.server.permissions.PermissionSet;
+
+/** Tests real registered command permissions using sources; no real or simulated creative player is created. */
+public final class ExpansionCommandChecks {
+    private ExpansionCommandChecks() { }
+
+    public static void verify(GameTestHelper helper) throws IOException {
+        var level = helper.getLevel();
+        var server = level.getServer();
+        var session = ExpansionRuntime.session(level);
+        var before = session.islands();
+        var dispatcher = server.getCommands().getDispatcher();
+        var console = server.createCommandSourceStack().withLevel(level).withSource(CommandSource.NULL).withSuppressedOutput();
+        var levelZero = console.withPermission(LevelBasedPermissionSet.forLevel(PermissionLevel.ALL));
+        var noPermissions = console.withPermission(PermissionSet.NO_PERMISSIONS);
+        var levelOne = console.withPermission(LevelBasedPermissionSet.MODERATOR);
+        var operatorTwo = console.withPermission(LevelBasedPermissionSet.GAMEMASTER);
+        var admin = console.withPermission(LevelBasedPermissionSet.ADMIN);
+        helper.assertTrue(console.getEntity() == null, "Command permission checks use console-derived sources, not a creative-player simulation");
+        helper.assertTrue(ChunkLevel.RADIUS_AROUND_FULL_CHUNK * 16 <= ExpansionIsland.GENERATION_HALO,
+            "The declared expansion halo must include the exact engine FULL generation dependency radius");
+
+        var sanctuary = dispatcher.getRoot().getChild("sanctuary");
+        helper.assertTrue(sanctuary != null && sanctuary.getChild("expansion") != null,
+            "The production Sanctuary expansion command tree must be registered");
+        helper.assertTrue(!sanctuary.canUse(levelZero) && !sanctuary.canUse(noPermissions) && !sanctuary.canUse(levelOne),
+            "Expansion commands must reject level 0, absent permissions and OP1 regardless of any game-mode assumption");
+        helper.assertTrue(sanctuary.canUse(operatorTwo) && sanctuary.canUse(admin) && sanctuary.canUse(console),
+            "Expansion commands must admit OP2 and higher, including the dedicated server console");
+
+        String create = "sanctuary expansion create command_denied sanctuary north boreal 64 natural";
+        expectDenied(helper, dispatcher, levelZero, create, "level 0");
+        expectDenied(helper, dispatcher, noPermissions, create, "no permissions");
+        expectDenied(helper, dispatcher, levelOne, create, "OP1");
+        helper.assertTrue(session.islands().equals(before), "Denied command sources must not add or change expansion regions");
+
+        String preview = "sanctuary expansion preview command_preview sanctuary north boreal 64 natural";
+        try {
+            var parsed = dispatcher.parse(preview, console);
+            helper.assertTrue(!parsed.getReader().canRead() && parsed.getExceptions().isEmpty(),
+                "The console must parse a complete preview with the known Sanctuary parent");
+            helper.assertTrue(dispatcher.execute(parsed) == 1, "The console preview must execute successfully through the registered dispatcher");
+            helper.assertTrue(dispatcher.execute(preview, operatorTwo) == 1, "OP2 must execute the same read-only preview successfully");
+            helper.assertTrue(session.islands().equals(before), "Preview must not reserve or activate an island");
+
+            var feedback = new ArrayList<Component>();
+            var previewSource = server.createCommandSourceStack().withLevel(level).withPermission(LevelBasedPermissionSet.GAMEMASTER)
+                .withSource(new CommandSource() {
+                    @Override public void sendSystemMessage(Component message) { feedback.add(message); }
+                    @Override public boolean acceptsSuccess() { return true; }
+                    @Override public boolean acceptsFailure() { return true; }
+                    @Override public boolean shouldInformAdmins() { return false; }
+                });
+            var parent = session.island("sanctuary");
+            for (String direction : new String[] {"north", "northeast"}) {
+                feedback.clear();
+                helper.assertTrue(dispatcher.execute("sanctuary expansion preview distance_preview sanctuary " + direction
+                    + " boreal 64 natural 2048", previewSource) == 1, "The optional distance must execute for " + direction);
+                helper.assertTrue(feedback.size() == 1 && feedback.getFirst().getContents() instanceof TranslatableContents,
+                    "A successful distance preview must return its proposed coordinates");
+                var result = (TranslatableContents) feedback.getFirst().getContents();
+                helper.assertTrue(result.getKey().equals("sanctuary.expansion.preview"), "Distance preview must return the production preview response");
+                var args = result.getArgs();
+                int x = ((Number) args[1]).intValue(), z = ((Number) args[2]).intValue();
+                int dx = x - parent.centerX(), dz = z - parent.centerZ();
+                helper.assertTrue(Math.hypot(dx, dz) >= 2048,
+                    "The command distance must be a minimum centre-to-centre distance, including diagonals");
+                helper.assertTrue(dz < 0 && (direction.equals("north") ? dx == 0 : dx == -dz),
+                    "The distance preview must preserve the exact requested direction");
+                helper.assertTrue(session.islands().equals(before), "Distance preview must not reserve or activate an island");
+            }
+            for (String command : new String[] {
+                    "sanctuary expansion quick north",
+                    "sanctuary expansion quick north boreal 64 natural",
+                    "sanctuary expansion quick north boreal 64 natural 2048",
+                    "sanctuary expansion create distance_create sanctuary north boreal 64 natural",
+                    "sanctuary expansion create distance_create sanctuary north boreal 64 natural 2048"}) {
+                var syntax = dispatcher.parse(command, operatorTwo);
+                helper.assertTrue(!syntax.getReader().canRead() && syntax.getExceptions().isEmpty() && syntax.getContext().getCommand() != null,
+                    "Old and distance-aware create/quick syntax must remain executable: " + command);
+            }
+            helper.assertTrue(dispatcher.execute(preview + " 0", operatorTwo) == 1,
+                "An explicit zero distance must preserve automatic positioning");
+
+            for (String distance : new String[] {"-1", "100001"}) {
+                for (String command : new String[] {
+                        preview,
+                        "sanctuary expansion create distance_invalid sanctuary north boreal 64 natural",
+                        "sanctuary expansion quick north boreal 64 natural"}) {
+                    boolean distanceRejected = false;
+                    try { dispatcher.execute(command + " " + distance, operatorTwo); }
+                    catch (CommandSyntaxException expected) { distanceRejected = true; }
+                    helper.assertTrue(distanceRejected && session.islands().equals(before),
+                        "All expansion commands must reject an out-of-range distance without mutation");
+                }
+            }
+
+            // 65 is accepted by Brigadier's numeric bounds, then rejected by the production size contract.
+            int invalid = dispatcher.execute("sanctuary expansion create command_invalid sanctuary east boreal 65 natural", operatorTwo);
+            helper.assertTrue(invalid == 0, "An unsupported nominal diameter must fail in the production command handler");
+            helper.assertTrue(session.islands().equals(before), "Rejecting an unsupported diameter must preserve the registry");
+
+            boolean outsideRangeRejected = false;
+            try { dispatcher.execute("sanctuary expansion create command_out_of_range sanctuary east boreal 513 natural", console); }
+            catch (CommandSyntaxException expected) { outsideRangeRejected = true; }
+            helper.assertTrue(outsideRangeRejected && session.islands().equals(before),
+                "The parser must reject a diameter above 512 before changing the registry");
+        } catch (CommandSyntaxException exception) {
+            throw new IOException("Registered expansion command checks failed", exception);
+        }
+    }
+
+    private static void expectDenied(GameTestHelper helper, CommandDispatcher<CommandSourceStack> dispatcher,
+            CommandSourceStack source, String command, String label) {
+        var parsed = dispatcher.parse(command, source);
+        helper.assertTrue(parsed.getContext().getNodes().isEmpty() && parsed.getReader().canRead(),
+            "The " + label + " source must not parse the restricted expansion command tree");
+        boolean rejected = false;
+        try { dispatcher.execute(parsed); }
+        catch (CommandSyntaxException expected) { rejected = true; }
+        helper.assertTrue(rejected, "The " + label + " source must not execute an expansion command");
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/ExpansionWorldGameTests.java

@@ -0,0 +1,533 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import com.mojang.serialization.JsonOps;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.expansion.ExpansionAdmission;
+import fr.koka.sanctuary.expansion.ExpansionBiomeSource;
+import fr.koka.sanctuary.expansion.ExpansionChunkGenerator;
+import fr.koka.sanctuary.expansion.ExpansionIsland;
+import fr.koka.sanctuary.expansion.ExpansionJournal;
+import fr.koka.sanctuary.expansion.ExpansionRuntime;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.LinkedHashMap;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import net.fabricmc.fabric.api.gametest.v1.GameTest;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.entity.RandomizableContainerBlockEntity;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.structure.StructureStart;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.storage.LevelResource;
+
+/** Opt-in end-to-end exercise on a new laboratory world; never rewrites chunks or a personal world. */
+public final class ExpansionWorldGameTests {
+    private static final boolean OPTIONAL_STRUCTURE_WITNESS = Boolean.getBoolean("sanctuary.test.optionalStructureWitness");
+
+    @GameTest(maxTicks = 6000)
+    public void islandsBranchPersistAndProtectVisitedChunks(GameTestHelper helper) {
+        helper.assertTrue(Boolean.getBoolean("sanctuary.test.expansion"), "Expansion GameTest must be explicitly enabled");
+        helper.assertTrue(helper.getLevel().getChunkSource().getGenerator() instanceof ExpansionChunkGenerator,
+            "Expansion GameTest must load the new laboratory preset");
+        if (Boolean.getBoolean("sanctuary.test.expansionReload")) {
+            verifyProcessReload(helper);
+            return;
+        }
+        new Scenario(helper).advance();
+    }
+
+    private static void verifyProcessReload(GameTestHelper helper) {
+        ServerLevel level = helper.getLevel();
+        var generator = (ExpansionChunkGenerator) level.getChunkSource().getGenerator();
+        var session = ExpansionRuntime.session(level);
+        Map<String, Object> report = new LinkedHashMap<>();
+        report.put("seed", level.getSeed());
+        report.put("process_id", ProcessHandle.current().pid());
+        report.put("optional_native_structure_witness", OPTIONAL_STRUCTURE_WITNESS);
+        report.put("scope", "A second Java process opens the same saved development chunks and expansion journal, and verifies a "
+            + "gold block written and flushed before the first shutdown. GameTestServer reconstructs its world settings from the preset; "
+            + "the prior generator codec is decoded separately here and its base columns are compared. This is not a normal-client "
+            + "world-selection test or a multiplayer/teleportation test.");
+        try {
+            JsonObject previous = JsonParser.parseString(Files.readString(diagnostic(level, false))).getAsJsonObject();
+            helper.assertTrue(previous.get("passed").getAsBoolean(), "Reload requires a successful first integration run");
+            helper.assertTrue(previous.has("restart_snapshot"), "The first process must save a restart witness before shutting down");
+            helper.assertTrue(previous.get("process_id").getAsLong() != ProcessHandle.current().pid(),
+                "The reload proof must run in another Java process");
+            helper.assertTrue(previous.get("seed").getAsLong() == level.getSeed(), "Reload must keep the original world seed");
+            JsonObject saved = previous.getAsJsonObject("restart_snapshot");
+            List<ExpansionIsland> blockers = ExpansionIsland.CODEC.listOf().parse(JsonOps.INSTANCE, saved.get("blocked_sites")).getOrThrow();
+            int savedRefusals = 0;
+            for (var site : blockers) {
+                helper.assertTrue(level.getChunkSource().chunkMap.getUpdatingChunkIfPresent(new ChunkPos(site.centerX() >> 4, site.centerZ() >> 4).pack()) == null,
+                    "Reload collision proof must start with an unloaded saved witness");
+                try { ExpansionAdmission.verify(level, site); }
+                catch (ExpansionAdmission.OccupiedException expected) {
+                    helper.assertTrue(expected.getMessage().contains("saved chunk"), "The reload proof must detect disk occupancy, not just a loaded holder");
+                    savedRefusals++;
+                }
+            }
+            helper.assertTrue(savedRefusals == 8, "All eight first sites must remain unavailable on disk after restart");
+            report.put("saved_only_collision_refusals", savedRefusals);
+            helper.assertTrue(saved.get("world_directory").getAsString().equals(worldDirectory(level)),
+                "Reload must use exactly the same development save directory");
+            helper.assertTrue(session.islands().size() == 3 && session.islands().stream().allMatch(i -> i.status().equals("ready")),
+                "The loaded journal must contain exactly the ready root, alpha and beta");
+            helper.assertTrue(session.island("alpha").parent().equals("sanctuary") && session.island("beta").parent().equals("alpha"),
+                "Reload must preserve the expansion branch");
+            var encodedIslands = ExpansionIsland.CODEC.listOf().encodeStart(JsonOps.INSTANCE, session.islands()).getOrThrow();
+            helper.assertTrue(encodedIslands.equals(saved.get("islands")), "Every persisted region field must survive the process restart");
+            helper.assertTrue(sha256(Files.readString(journalFile(level))).equals(saved.get("journal_sha256").getAsString()),
+                "Loading a ready journal must preserve its exact saved contents");
+            var ops = RegistryOps.create(JsonOps.INSTANCE, level.registryAccess());
+            var liveCodec = ChunkGenerator.CODEC.encodeStart(ops, generator).getOrThrow();
+            helper.assertTrue(liveCodec.equals(saved.get("generator_codec")), "Generator settings and biome holder identities must remain stable");
+            var decoded = ChunkGenerator.CODEC.parse(ops, saved.get("generator_codec")).getOrThrow();
+            helper.assertTrue(decoded instanceof ExpansionChunkGenerator, "The saved generator codec must decode to the laboratory generator");
+            var restored = (ExpansionChunkGenerator) decoded;
+            restored.initialize(level, session.islands());
+
+            BlockPos witness = position(saved.getAsJsonArray("gold_witness"));
+            full(helper, level, witness.getX() >> 4, witness.getZ() >> 4);
+            helper.assertTrue(level.getBlockState(witness).is(Blocks.GOLD_BLOCK),
+                "The first process's saved gold block must exist before the reload test writes anything");
+            List<Map<String, Object>> samples = new ArrayList<>();
+            for (var element : saved.getAsJsonArray("samples")) {
+                JsonObject original = element.getAsJsonObject();
+                var island = session.island(original.get("id").getAsString());
+                BlockPos point = position(original.getAsJsonArray("point"));
+                Map<String, Object> current = sample(helper, generator, island, point);
+                helper.assertTrue(new GsonBuilder().create().toJsonTree(current).equals(original),
+                    "Stored blocks, stored biomes and generated base column must survive restart: " + island.id());
+                helper.assertTrue(new GsonBuilder().create().toJsonTree(sample(helper, restored, island, point)).equals(original),
+                    "Decoding the saved generator codec must reproduce its base column and climate: " + island.id());
+                samples.add(current);
+            }
+            boolean hasNativeStructure = previous.has("native_structure") && !previous.get("native_structure").isJsonNull();
+            if (hasNativeStructure) {
+                helper.assertTrue(!previous.has("native_structure_observed") || previous.get("native_structure_observed").getAsBoolean(),
+                    "Stored native structure evidence must not contradict the observation result");
+                JsonObject nativeStructure = previous.getAsJsonObject("native_structure");
+                BlockPos containerPos = position(nativeStructure.getAsJsonArray("container"));
+                full(helper, level, containerPos.getX() >> 4, containerPos.getZ() >> 4);
+                helper.assertTrue(level.getBlockState(containerPos).toString().equals(nativeStructure.get("placed_block").getAsString()),
+                    "The native structure's placed block state must survive restart");
+                helper.assertTrue(level.getBlockEntity(containerPos) instanceof RandomizableContainerBlockEntity,
+                    "The native structure's placed container must be loaded from the saved chunk");
+                var container = (RandomizableContainerBlockEntity) level.getBlockEntity(containerPos);
+                helper.assertTrue(container.getLootTable() != null && container.getLootTable().identifier().toString()
+                    .equals(nativeStructure.get("loot_table").getAsString()), "The native structure loot table must survive restart unconsumed");
+                report.put("native_container", coordinates(containerPos));
+                report.put("native_structure_observed", true);
+                report.put("native_container_verified", true);
+                report.put("native_structure_status", "placed_block_and_unconsumed_loot_verified_after_restart");
+            } else {
+                helper.assertTrue(OPTIONAL_STRUCTURE_WITNESS
+                        && previous.has("optional_native_structure_witness") && previous.get("optional_native_structure_witness").getAsBoolean()
+                        && previous.has("native_structure_observed") && !previous.get("native_structure_observed").getAsBoolean()
+                        && previous.has("native_structure_search_complete") && previous.get("native_structure_search_complete").getAsBoolean(),
+                    "Missing native structure evidence is allowed only after an explicitly optional, completed first-process search");
+                report.put("native_structure_observed", false);
+                report.put("native_container_verified", false);
+                report.put("native_structure_status", "not_observed_after_complete_first_process_scan; no_native_structure_reload_proof");
+                report.put("native_structure_limitation", "No natural structure with placed vanilla loot was observed in the first process. "
+                    + "This reload verifies chunks, generator settings, the journal and expansion behavior, but supplies no positive structure proof.");
+            }
+            report.put("previous_process_id", previous.get("process_id").getAsLong());
+            report.put("world_directory", worldDirectory(level));
+            report.put("gold_witness", coordinates(witness));
+            report.put("samples", samples);
+            report.put("regions", session.islands().size());
+            report.put("saved_generator_codec_decoded", true);
+            var firstCandidate = session.candidate("after_reload", "sanctuary", "south", "boreal", 64, "natural");
+            var opened = session.create("after_reload", "sanctuary", "south", "boreal", 64, "natural");
+            helper.assertTrue(opened.centerZ() > firstCandidate.centerZ() && opened.centerX() == 0,
+                "Creation must skip the saved occupied first site and preserve the requested southern ray");
+            report.put("after_reload_expansion", List.of(opened.centerX(), opened.centerZ()));
+            awaitReloadExpansion(helper, session, blockers, witness, report);
+        } catch (Exception exception) {
+            report.put("passed", false);
+            report.put("failure", exception.toString());
+            try { writeDiagnostic(level, true, report); } catch (IOException failure) { exception.addSuppressed(failure); }
+            SanctuaryMod.LOGGER.error("Expansion process reload scenario failed", exception);
+            helper.fail(exception.toString());
+        }
+    }
+
+    private static void awaitReloadExpansion(GameTestHelper helper, ExpansionRuntime.Session session,
+            List<ExpansionIsland> blockers, BlockPos gold, Map<String, Object> report) {
+        try {
+            helper.assertTrue(helper.getTick() < 5000, "Reload expansion preparation deadline: " + session.progress());
+            if (!session.island("after_reload").status().equals("ready")) {
+                helper.runAtTickTime(helper.getTick() + 10, () -> awaitReloadExpansion(helper, session, blockers, gold, report));
+                return;
+            }
+            verifyUntouchedVoid(helper, blockers);
+            helper.assertTrue(helper.getLevel().getBlockState(gold).is(Blocks.GOLD_BLOCK), "Opening farther away must preserve the saved player witness");
+            var landing = session.landing("after_reload");
+            helper.assertTrue(ExpansionRuntime.safeLanding(helper.getLevel(), landing), "The new region after restart must reach usable terrain");
+            report.put("after_reload_landing", coordinates(landing));
+            report.put("final_regions", session.islands().size());
+            report.put("passed", true);
+            writeDiagnostic(helper.getLevel(), true, report);
+            helper.succeed();
+        } catch (Exception exception) {
+            report.put("passed", false);
+            report.put("failure", exception.toString());
+            try { writeDiagnostic(helper.getLevel(), true, report); } catch (IOException failure) { exception.addSuppressed(failure); }
+            helper.fail(exception.toString());
+        }
+    }
+
+    private static void verifyUntouchedVoid(GameTestHelper helper, List<ExpansionIsland> blockers) {
+        var generator = (ExpansionChunkGenerator) helper.getLevel().getChunkSource().getGenerator();
+        for (var site : blockers) {
+            var chunk = full(helper, helper.getLevel(), site.centerX() >> 4, site.centerZ() >> 4);
+            helper.assertTrue(generator.islandAt(site.centerX(), site.centerZ()) == null
+                    && Arrays.stream(chunk.getSections()).allMatch(section -> section.hasOnlyAir()),
+                "An occupied saved void chunk must remain unchanged after farther placement: " + site.direction());
+        }
+    }
+
+    private static final class Scenario {
+        private final GameTestHelper helper;
+        private final ServerLevel level;
+        private final ExpansionChunkGenerator generator;
+        private final ExpansionRuntime.Session session;
+        private final Map<String, Object> report = new LinkedHashMap<>();
+        private final List<Map<String, Object>> observedIslands = new ArrayList<>();
+        private final Map<String, BlockPos> samplePoints = new LinkedHashMap<>();
+        private final List<ChunkPos> structureSearch = new ArrayList<>();
+        private final long started = System.nanoTime();
+        private ExpansionIsland alpha;
+        private ExpansionIsland beta;
+        private BlockPos marker;
+        private BlockState previousMarker;
+        private int phase;
+        private int structureIndex;
+        private int validStarts;
+        private final List<ExpansionIsland> blockedSites = new ArrayList<>();
+
+        Scenario(GameTestHelper helper) {
+            this.helper = helper;
+            this.level = helper.getLevel();
+            this.generator = (ExpansionChunkGenerator) level.getChunkSource().getGenerator();
+            this.session = ExpansionRuntime.session(level);
+            report.put("seed", level.getSeed());
+            report.put("process_id", ProcessHandle.current().pid());
+            report.put("generator_version", generator.rootGeneration());
+            report.put("initial_diameter", generator.initialDiameter());
+            report.put("islands", observedIslands);
+            report.put("optional_native_structure_witness", OPTIONAL_STRUCTURE_WITNESS);
+            report.put("native_structure_observed", false);
+            report.put("native_structure_search_complete", false);
+            report.put("native_structure_status", "not_searched");
+            report.put("scope", "Fresh versioned Sanctuary development world; real FULL chunks, a natural native-structure search, asynchronous activation, "
+                + "branching, journal re-read and loaded void admission refusal. Journal re-read is not a process restart. "
+                + "The parent block witness represents a player edit; no player teleport, multiplayer or client rendering is simulated. "
+                + (OPTIONAL_STRUCTURE_WITNESS ? "The native structure witness is explicitly optional; an absent witness is reported as missing evidence, never as a successful structures test."
+                    : "A naturally accepted structure with placed vanilla loot is required."));
+        }
+
+        void advance() {
+            try {
+                helper.assertTrue(helper.getTick() < 5800, "Expansion scenario deadline: " + session.progress());
+                switch (phase) {
+                    case 0 -> start();
+                    case 1 -> {
+                        if (!session.island("alpha").status().equals("ready")) break;
+                        helper.assertTrue(session.island("alpha").equals(alpha.ready()), "Activation must only advance the immutable island state");
+                        observeIsland("alpha", Set.of("jungle", "sparse_jungle", "bamboo_jungle", "mangrove_swamp"));
+                        verifyMarker();
+                        beta = session.create("beta", "alpha", "east", "arid", 64, "natural", 2048);
+                        helper.assertTrue(beta.parent().equals("alpha") && beta.centerX() > alpha.centerX()
+                            && beta.centerZ() == alpha.centerZ(), "A child must branch east from alpha, not from world origin");
+                        helper.assertTrue(beta.centerX() - alpha.centerX() >= 2048, "The requested minimum distance must be honoured from the chosen parent");
+                        verifyJournal();
+                        phase = 2;
+                    }
+                    case 2 -> {
+                        if (!session.island("beta").status().equals("ready")) break;
+                        helper.assertTrue(session.island("beta").equals(beta.ready()), "Branch activation must preserve its planned identity");
+                        observeIsland("beta", Set.of("desert", "badlands", "eroded_badlands", "wooded_badlands"));
+                        verifyMarker();
+                        verifyJournal();
+                        verifyUntouchedVoid(helper, blockedSites);
+                        prepareStructureSearch();
+                        phase = 3;
+                    }
+                    case 3 -> {
+                        if (observeNativeStructure()) {
+                            verifyMarker();
+                            verifyJournal();
+                            level.setBlock(marker, previousMarker, 3);
+                            prepareRestartWitness();
+                            report.put("islands", observedIslands);
+                            report.put("native_structure_starts_seen", validStarts);
+                            report.put("structure_start_chunks_inspected", structureIndex);
+                            report.put("ticks", helper.getTick());
+                            report.put("elapsed_ms", (System.nanoTime() - started) / 1_000_000.0);
+                            report.put("passed", true);
+                            writeReport();
+                            helper.succeed();
+                            return;
+                        }
+                    }
+                    default -> throw new IllegalStateException("Unknown expansion test phase");
+                }
+                if (helper.getTick() % 200 == 0) SanctuaryMod.LOGGER.info("Expansion scenario phase {}: {}", phase, session.progress());
+                helper.runAtTickTime(helper.getTick() + 10, this::advance);
+            } catch (Exception exception) {
+                report.put("passed", false);
+                report.put("failure", exception.toString());
+                report.put("phase", phase);
+                report.put("runtime_progress", session.progress());
+                try { writeReport(); } catch (IOException failure) { exception.addSuppressed(failure); }
+                SanctuaryMod.LOGGER.error("Expansion integration scenario failed", exception);
+                helper.fail(exception.toString());
+            }
+        }
+
+        private void start() throws IOException {
+            helper.assertTrue(session.islands().size() == 1, "The test must start from a new expansion journal");
+            helper.assertTrue(level.structureManager().shouldGenerateStructures(), "The laboratory GameTest must enable actual vanilla structures in WorldOptions");
+            ExpansionCommandChecks.verify(helper);
+            report.put("registered_command_permission_checks", true);
+            helper.assertTrue(generator.source().possibleBiomes().size() >= ExpansionBiomeSource.REQUIRED_BIOMES.size(),
+                "Future biome holders must be declared before the first expansion");
+            BlockPos landing = session.landing("sanctuary");
+            helper.assertTrue(ExpansionRuntime.safeLanding(level, landing), "The initial laboratory island must provide a real safe landing");
+            full(landing.getX() >> 4, landing.getZ() >> 4);
+            marker = landing.above(6);
+            previousMarker = level.getBlockState(marker);
+            helper.assertTrue(level.setBlock(marker, Blocks.DIAMOND_BLOCK.defaultBlockState(), 3), "Place the parent player-edit witness");
+            report.put("parent_witness", coordinates(marker));
+            report.put("root_landing", coordinates(landing));
+            samplePoints.put("sanctuary", landing);
+
+            for (String direction : ExpansionIsland.DIRECTIONS) {
+                var site = session.candidate("blocked_" + direction, "sanctuary", direction, "boreal", 64, "natural");
+                var chunk = full(site.centerX() >> 4, site.centerZ() >> 4);
+                helper.assertTrue(Arrays.stream(chunk.getSections()).allMatch(section -> section.hasOnlyAir()), "The first site must initially contain only real generated void");
+                blockedSites.add(site);
+            }
+            int occupied = 0;
+            for (var site : blockedSites) {
+                try { ExpansionAdmission.verify(level, site); }
+                catch (ExpansionAdmission.OccupiedException expected) { occupied++; }
+            }
+            helper.assertTrue(occupied == 8, "Reproduce the user failure with all eight first directions occupied");
+            report.put("initial_occupied_directions", occupied);
+            var nearestNorth = session.candidate("alpha", "sanctuary", "north", "tropical", 64, "natural");
+
+            alpha = session.create("alpha", "sanctuary", "north", "tropical", 64, "natural");
+            helper.assertTrue(alpha.status().equals("reserved") && alpha.centerZ() < 0 && alpha.centerX() == 0,
+                "North placement and the explicitly chosen tropical climate must remain independent");
+            helper.assertTrue(alpha.centerZ() < nearestNorth.centerZ(), "Automatic placement must skip occupied chunks and continue farther north");
+            helper.assertTrue(alpha.equals(session.create("alpha", "sanctuary", "north", "tropical", 64, "natural"))
+                && session.islands().size() == 2, "Repeating a matching request must not create another region or change its identity");
+            boolean conflict = false;
+            try { session.create("alpha", "sanctuary", "north", "arid", 64, "natural"); }
+            catch (IllegalArgumentException expected) { conflict = expected.getMessage().equals("id_conflict"); }
+            helper.assertTrue(conflict, "A conflicting duplicate island id must be refused");
+            verifyJournal();
+            phase = 1;
+        }
+
+        private void observeIsland(String id, Set<String> expectedSurfaceBiomes) {
+            ExpansionIsland island = session.island(id);
+            BlockPos landing = session.landing(id);
+            helper.assertTrue(island.contains(landing.getX(), landing.getZ()) && ExpansionRuntime.safeLanding(level, landing),
+                "READY must offer actual safe terrain inside " + id);
+            LevelChunk chunk = full(landing.getX() >> 4, landing.getZ() >> 4);
+            helper.assertTrue(Arrays.stream(chunk.getSections()).anyMatch(section -> !section.hasOnlyAir()), "READY cannot be only a registry entry: " + id);
+            // The 240 sample is the stored upper climate in a FULL chunk, independent of which safe ledge was found.
+            String climateBiome = chunk.getNoiseBiome(landing.getX() >> 2, 60, landing.getZ() >> 2).unwrapKey().orElseThrow().identifier().toString();
+            helper.assertTrue(expectedSurfaceBiomes.contains(climateBiome.substring("minecraft:".length())),
+                "The FULL chunk must contain its requested upper climate: " + id + " / " + climateBiome);
+            String landingBiome = level.getBiome(landing).unwrapKey().orElseThrow().identifier().toString();
+            samplePoints.put(id, landing);
+            observedIslands.add(Map.of("id", id, "parent", island.parent(), "climate", island.climate(),
+                "centre", List.of(island.centerX(), island.centerZ()), "diameter", island.diameter(),
+                "landing", coordinates(landing), "landing_biome", landingBiome, "upper_biome", climateBiome));
+        }
+
+        private void verifyMarker() {
+            helper.assertTrue(level.getBlockState(marker).is(Blocks.DIAMOND_BLOCK), "An expansion must preserve the parent player-edit witness");
+        }
+
+        private void verifyJournal() throws IOException {
+            Path directory = level.getServer().getWorldPath(LevelResource.ROOT).resolve("data/" + ((ExpansionChunkGenerator) level.getChunkSource().getGenerator()).journalDirectory());
+            var reloaded = new ExpansionJournal(directory, level.getSeed(), generator.initialDiameter(), generator.rootGeneration());
+            helper.assertTrue(reloaded.islands().equals(session.islands()), "Re-reading the saved journal must preserve all region identities and states");
+            report.put("journal_reloaded_regions", reloaded.islands().size());
+        }
+
+        private void prepareRestartWitness() throws IOException {
+            BlockPos gold = samplePoints.get("beta").above(6);
+            while (!level.getBlockState(gold).isAir() && gold.getY() < level.getMaxY() - 1) gold = gold.above();
+            helper.assertTrue(gold.getY() < level.getMaxY() - 1 && level.getBlockState(gold).isAir(), "The restart witness needs empty space above beta");
+            helper.assertTrue(level.setBlock(gold, Blocks.GOLD_BLOCK.defaultBlockState(), 3), "Write the restart witness in the first process");
+            var snapshot = new LinkedHashMap<String, Object>();
+            snapshot.put("world_directory", worldDirectory(level));
+            snapshot.put("gold_witness", coordinates(gold));
+            snapshot.put("journal_sha256", sha256(Files.readString(journalFile(level))));
+            snapshot.put("islands", ExpansionIsland.CODEC.listOf().encodeStart(JsonOps.INSTANCE, session.islands()).getOrThrow());
+            snapshot.put("generator_codec", ChunkGenerator.CODEC.encodeStart(RegistryOps.create(JsonOps.INSTANCE, level.registryAccess()), generator).getOrThrow());
+            snapshot.put("blocked_sites", ExpansionIsland.CODEC.listOf().encodeStart(JsonOps.INSTANCE, blockedSites).getOrThrow());
+            List<Map<String, Object>> samples = new ArrayList<>();
+            for (var island : session.islands()) samples.add(sample(helper, generator, island, samplePoints.get(island.id())));
+            snapshot.put("samples", samples);
+            helper.assertTrue(level.getServer().saveEverything(true, true, true), "Flush the first process's world and marker before writing restart evidence");
+            snapshot.put("world_flushed_before_shutdown", true);
+            report.put("restart_snapshot", snapshot);
+        }
+
+        private void prepareStructureSearch() {
+            ExpansionIsland root = session.island("sanctuary");
+            int limit = (root.terrainRadius() + 15) / 16;
+            // STARTS only, centre outwards. Only an accepted structure's region is later requested at FULL.
+            for (int ring = 0; ring <= limit; ring++) for (int x = -ring; x <= ring; x++) for (int z = -ring; z <= ring; z++) {
+                if (Math.max(Math.abs(x), Math.abs(z)) == ring && root.contains(x * 16 + 8, z * 16 + 8)) structureSearch.add(new ChunkPos(x, z));
+            }
+            report.put("structure_search_candidate_chunks", structureSearch.size());
+            report.put("native_structure_status", "search_in_progress");
+        }
+
+        private boolean observeNativeStructure() {
+            int end = Math.min(structureSearch.size(), structureIndex + 16);
+            while (structureIndex < end) {
+                ChunkPos position = structureSearch.get(structureIndex++);
+                var chunk = level.getChunkSource().getChunk(position.x(), position.z(), ChunkStatus.STRUCTURE_STARTS, true);
+                helper.assertTrue(chunk != null, "A structure-start request must complete");
+                for (StructureStart start : chunk.getAllStarts().values()) {
+                    if (!start.isValid()) continue;
+                    validStarts++;
+                    String name = level.registryAccess().lookupOrThrow(Registries.STRUCTURE).getKey(start.getStructure()).toString();
+                    if (!name.startsWith("minecraft:")) continue;
+                    Map<String, Object> evidence = materializeAndFindLoot(start, name);
+                    if (!evidence.isEmpty()) {
+                        report.put("native_structure", evidence);
+                        report.put("native_structure_observed", true);
+                        report.put("native_structure_status", "natural_start_with_placed_vanilla_loot_observed");
+                        report.put("native_structure_search_complete", structureIndex == structureSearch.size());
+                        return true;
+                    }
+                }
+            }
+            report.put("native_structure_starts_seen", validStarts);
+            report.put("structure_start_chunks_inspected", structureIndex);
+            if (structureIndex == structureSearch.size()) {
+                report.put("native_structure_search_complete", true);
+                report.put("native_structure_status", "not_observed_after_complete_scan");
+                report.put("native_structure_limitation", "No naturally accepted native structure with placed vanilla loot was observed after "
+                    + structureIndex + " root-island start chunks and " + validStarts + " valid starts. "
+                    + "This is missing engine evidence for structures, not a positive generation or loot result.");
+                if (OPTIONAL_STRUCTURE_WITNESS) return true;
+            }
+            helper.assertTrue(structureIndex < structureSearch.size(), "No naturally accepted native structure with placed vanilla loot was observed; "
+                + validStarts + " valid starts. This is a missing engine proof, not a successful structures test.");
+            return false;
+        }
+
+        private Map<String, Object> materializeAndFindLoot(StructureStart start, String name) {
+            var bounds = start.getBoundingBox();
+            List<LevelChunk> chunks = new ArrayList<>();
+            for (int x = bounds.minX() >> 4; x <= bounds.maxX() >> 4; x++) {
+                for (int z = bounds.minZ() >> 4; z <= bounds.maxZ() >> 4; z++) chunks.add(full(x, z));
+            }
+            for (LevelChunk chunk : chunks) {
+                for (var entry : chunk.getBlockEntities().entrySet()) {
+                    if (!(entry.getValue() instanceof RandomizableContainerBlockEntity container) || container.getLootTable() == null) continue;
+                    BlockPos pos = entry.getKey();
+                    if (start.getPieces().stream().noneMatch(piece -> piece.getBoundingBox().isInside(pos))) continue;
+                    String loot = container.getLootTable().identifier().toString();
+                    if (!loot.startsWith("minecraft:")) continue;
+                    return Map.of("structure", name, "loot_table", loot, "container", coordinates(pos),
+                        "placed_block", level.getBlockState(pos).toString(), "full_chunks", chunks.size(),
+                        "mode", "natural candidate accepted by production ExpansionStructures, native decoration");
+                }
+            }
+            return Map.of();
+        }
+
+        private LevelChunk full(int x, int z) {
+            var chunk = level.getChunkSource().getChunk(x, z, ChunkStatus.FULL, true);
+            helper.assertTrue(chunk instanceof LevelChunk, "Expected real FULL chunk at " + new ChunkPos(x, z));
+            return (LevelChunk) chunk;
+        }
+
+        private void writeReport() throws IOException {
+            writeDiagnostic(level, false, report);
+        }
+    }
+
+    private static Map<String, Object> sample(GameTestHelper helper, ExpansionChunkGenerator generator, ExpansionIsland island, BlockPos point) {
+        ServerLevel level = helper.getLevel();
+        LevelChunk chunk = full(helper, level, point.getX() >> 4, point.getZ() >> 4);
+        var random = generator.randomState(island);
+        var base = generator.getBaseColumn(point.getX(), point.getZ(), level, random);
+        StringBuilder storedBlocks = new StringBuilder(), baseBlocks = new StringBuilder(), biomes = new StringBuilder(), resolvedBiomes = new StringBuilder();
+        var resolver = generator.source().createUncachedResolver(random);
+        for (int y = level.getMinY(); y <= level.getMaxY(); y++) {
+            storedBlocks.append(chunk.getBlockState(new BlockPos(point.getX(), y, point.getZ()))).append('\n');
+            baseBlocks.append(base.getBlock(y)).append('\n');
+            if ((y & 3) == 0) {
+                biomes.append(chunk.getNoiseBiome(point.getX() >> 2, y >> 2, point.getZ() >> 2).getRegisteredName()).append('\n');
+                resolvedBiomes.append(resolver.getNoiseBiome(point.getX() >> 2, y >> 2, point.getZ() >> 2).getRegisteredName()).append('\n');
+            }
+        }
+        return Map.of("id", island.id(), "point", coordinates(point), "stored_column_sha256", sha256(storedBlocks.toString()),
+            "base_column_sha256", sha256(baseBlocks.toString()), "stored_biomes_sha256", sha256(biomes.toString()),
+            "resolved_biomes_sha256", sha256(resolvedBiomes.toString()), "base_height",
+            generator.getBaseHeight(point.getX(), point.getZ(), Heightmap.Types.WORLD_SURFACE_WG, level, random));
+    }
+
+    private static LevelChunk full(GameTestHelper helper, ServerLevel level, int x, int z) {
+        var chunk = level.getChunkSource().getChunk(x, z, ChunkStatus.FULL, true);
+        helper.assertTrue(chunk instanceof LevelChunk, "Expected saved FULL chunk at " + new ChunkPos(x, z));
+        return (LevelChunk) chunk;
+    }
+
+    private static String sha256(String text) {
+        try { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(text.getBytes(StandardCharsets.UTF_8))); }
+        catch (NoSuchAlgorithmException impossible) { throw new IllegalStateException(impossible); }
+    }
+
+    private static Path journalFile(ServerLevel level) {
+        return level.getServer().getWorldPath(LevelResource.ROOT).resolve("data/" + ((ExpansionChunkGenerator) level.getChunkSource().getGenerator()).journalDirectory()).resolve(ExpansionJournal.FILE_NAME);
+    }
+    private static String worldDirectory(ServerLevel level) { return level.getServer().getWorldPath(LevelResource.ROOT).toAbsolutePath().normalize().toString(); }
+    private static Path diagnostic(ServerLevel level, boolean reload) {
+        return Path.of("diagnostics", (Boolean.getBoolean("sanctuary.test.unified") ? "expansion-alpha13-" : "expansion-alpha12-1-") + (reload ? "reload-" : "") + "seed-" + level.getSeed() + ".json");
+    }
+    private static void writeDiagnostic(ServerLevel level, boolean reload, Map<String, Object> report) throws IOException {
+        Path output = diagnostic(level, reload);
+        Files.createDirectories(output.getParent());
+        Files.writeString(output, new GsonBuilder().setPrettyPrinting().create().toJson(report) + "\n");
+    }
+    private static BlockPos position(JsonArray coordinates) { return new BlockPos(coordinates.get(0).getAsInt(), coordinates.get(1).getAsInt(), coordinates.get(2).getAsInt()); }
+    private static List<Integer> coordinates(BlockPos pos) { return List.of(pos.getX(), pos.getY(), pos.getZ()); }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/PopulationDensityEquivalenceDiagnostics.java

@@ -0,0 +1,140 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.ExactInterpolationChecks;
+import fr.koka.sanctuary.worldgen.ExactInterpolationSampler;
+import fr.koka.sanctuary.worldgen.IslandCapacity;
+import fr.koka.sanctuary.worldgen.PopulationIslandDensity;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executors;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.densityfunction.DensityBuffer;
+import net.minecraft.world.level.levelgen.densityfunction.DensitySampler;
+import net.minecraft.world.level.levelgen.densityfunction.DensityVolume;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+
+/** Compares production against the frozen alpha.10 implementation; no chunks are created. */
+final class PopulationDensityEquivalenceDiagnostics {
+    private record Pair(int players, long seed, DensitySampler reference, DensitySampler actual) {}
+
+    static void verify(GameTestHelper helper) throws Exception {
+        Map<String, Object> adversarial = ExactInterpolationChecks.verify();
+        var registries = helper.getLevel().registryAccess();
+        var noises = registries.lookupOrThrow(Registries.NOISE);
+        var densities = registries.lookupOrThrow(Registries.DENSITY_FUNCTION);
+        var settings = registries.lookupOrThrow(Registries.NOISE_SETTINGS);
+        List<Map<String, Object>> reports = new ArrayList<>();
+        List<Pair> pairs = new ArrayList<>();
+        for (int players : new int[]{5, 10, 20, 100}) {
+            var key = SanctuaryMod.id("population_" + players);
+            var registered = densities.getOrThrow(ResourceKey.create(Registries.DENSITY_FUNCTION, key)).value();
+            helper.assertTrue(registered instanceof PopulationIslandDensity, "Compare the real registered Population density");
+            var density = (PopulationIslandDensity) registered;
+            helper.assertTrue(ExactInterpolationSampler.supportsTerrain(density.terrain()),
+                "The shipped coordinate-only terrain must actually use the exact cache, not the fallback");
+            var reference = new Alpha10PopulationDensityReference(density.terrain(), density.distortion(), density.sculpt(),
+                density.detail(), density.underside(), density.riftWarp(), density.riftDetail(), density.capacity());
+            for (long seed : new long[]{0, 42, 8675309}) {
+                var state = RandomState.create(noises, seed,
+                    settings.getOrThrow(ResourceKey.create(Registries.NOISE_SETTINGS, key)).value());
+                var pair = new Pair(players, seed, state.getSampler(reference), state.getSampler(density));
+                pairs.add(pair);
+                SamplerContext context = SamplerContext.builder().enableCaches().build();
+                long comparisons = 0, digest = 0xcbf29ce484222325L;
+                for (var volume : volumes(IslandCapacity.fromPlayers(players))) {
+                    DensityBuffer expected = DensityBuffer.createUnpooled(volume.size());
+                    DensityBuffer actual = DensityBuffer.createUnpooled(volume.size());
+                    pair.reference().sampleVolume(SamplerContext.EMPTY_UNCACHED, expected, volume);
+                    pair.actual().sampleVolume(context, actual, volume);
+                    for (int z = 0; z < volume.sizeZ(); z++) for (int x = 0; x < volume.sizeX(); x++) for (int y = 0; y < volume.sizeY(); y++) {
+                        int index = volume.indexUnchecked(x, y, z);
+                        int wx = volume.blockX(x), wy = volume.blockY(y), wz = volume.blockZ(z);
+                        same(pair, expected.get(index), actual.get(index), wx, wy, wz, "bulk");
+                        same(pair, expected.get(index), pair.actual().sampleValue(context, wx, wy, wz), wx, wy, wz, "scalar after bulk");
+                        comparisons += 2;
+                        digest = (digest ^ Float.floatToRawIntBits(expected.get(index))) * 0x100000001b3L;
+                    }
+                }
+                Random order = new Random(seed ^ players);
+                int limit = density.capacity().terrainLimit();
+                for (int i = 0; i < 512; i++) {
+                    int x = order.nextInt(limit * 2 + 33) - limit - 16;
+                    int y = order.nextInt(400) - 8;
+                    int z = order.nextInt(limit * 2 + 33) - limit - 16;
+                    float expected = pair.reference().sampleValue(SamplerContext.EMPTY_UNCACHED, x, y, z);
+                    same(pair, expected, pair.actual().sampleValue(SamplerContext.EMPTY_UNCACHED, x, y, z), x, y, z, "uncached context");
+                    same(pair, expected, pair.actual().sampleValue(context, x, y, z), x, y, z, "context switch");
+                    comparisons += 2;
+                }
+                reports.add(Map.of("players", players, "seed", seed, "bitwise_comparisons", comparisons,
+                    "reference_density_digest", Long.toUnsignedString(digest, 16), "optimized_path_supported", true));
+                SanctuaryMod.LOGGER.info("Exact density equivalence: players {}, seed {}, {} bitwise comparisons", players, seed, comparisons);
+            }
+        }
+        long concurrentComparisons = 0;
+        try (var executor = Executors.newFixedThreadPool(3)) {
+            List<Callable<Long>> tasks = new ArrayList<>();
+            for (int worker = 0; worker < 3; worker++) {
+                int id = worker;
+                tasks.add(() -> {
+                    long count = 0;
+                    SamplerContext local = SamplerContext.builder().enableCaches().build();
+                    // All workers share the same samplers and alternate worlds/seeds.
+                    // Only their scratch buffers and sampler contexts are thread-local.
+                    for (int round = 0; round < 3; round++) for (var pair : pairs) {
+                        var volume = new DensityVolume(9, 17, 7, -13 + id, 89 + round, -7 - id);
+                        DensityBuffer actual = DensityBuffer.createUnpooled(volume.size());
+                        pair.actual().sampleVolume(local, actual, volume);
+                        for (int z = 0; z < volume.sizeZ(); z++) for (int x = 0; x < volume.sizeX(); x++) for (int y = 0; y < volume.sizeY(); y++) {
+                            int wx = volume.blockX(x), wy = volume.blockY(y), wz = volume.blockZ(z);
+                            same(pair, pair.reference().sampleValue(local, wx, wy, wz),
+                                actual.get(volume.indexUnchecked(x, y, z)), wx, wy, wz, "concurrent bulk");
+                            count++;
+                        }
+                    }
+                    return count;
+                });
+            }
+            for (var result : executor.invokeAll(tasks)) concurrentComparisons += result.get();
+        }
+        Path report = Path.of("diagnostics", "population-alpha10-density-equivalence.json");
+        Files.createDirectories(report.getParent());
+        Files.writeString(report, new GsonBuilder().setPrettyPrinting().create().toJson(Map.of(
+            "reference_commit", "a26b72f", "reference_source_sha256", "fcc5a8a39b7c4d181d74ce4f9183a1ca93646137955ac64bab9d22e6db0752a1",
+            "comparison", "Float.floatToRawIntBits; no tolerance", "profiles", reports, "adversarial", adversarial,
+            "concurrent_comparisons", concurrentComparisons, "concurrent_workers", 3, "passed", true,
+            "scope", "Real compiled scalar/bulk densities, 4 capacities x 3 seeds (5/20/100 compatibility and new10 using the same parameterized algorithm), signed coordinates, region/coast/height boundaries, context switches and concurrency; no block changes")) + "\n");
+    }
+
+    private static List<DensityVolume> volumes(IslandCapacity capacity) {
+        int limit = capacity.terrainLimit(), middle = (int) capacity.radius() / 2;
+        return List.of(
+            new DensityVolume(16, 384, 16, -8, 0, -8),
+            new DensityVolume(19, 11, 17, -263, 61, -259),
+            new DensityVolume(17, 17, 17, 249, 124, 249),
+            new DensityVolume(13, 21, 11, 761, 167, -9),
+            new DensityVolume(13, 21, 11, -775, 103, 503),
+            new DensityVolume(17, 49, 5, limit - 12, 96, -2),
+            new DensityVolume(17, 49, 5, -limit - 4, 96, -2),
+            new DensityVolume(12, 33, 12, middle - 7, 90, -middle / 2 - 5),
+            new DensityVolume(5, 13, 5, -2, -4, -2),
+            new DensityVolume(5, 13, 5, -2, 378, -2),
+            new DensityVolume(9, 13, 7, -257, 61, -9, 3, 5, 2));
+    }
+
+    private static void same(Pair pair, float expected, float actual, int x, int y, int z, String phase) {
+        if (Float.floatToRawIntBits(expected) != Float.floatToRawIntBits(actual))
+            throw new AssertionError("Density changed from alpha10 in " + phase + ": players=" + pair.players() + ", seed=" + pair.seed()
+                + ", position=" + x + "," + y + "," + z + ", expected=" + Float.toHexString(expected) + ", actual=" + Float.toHexString(actual));
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/PopulationDiagnostics.java

@@ -0,0 +1,636 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.*;
+import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.tags.FluidTags;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.MultifaceBlock;
+import net.minecraft.world.level.block.state.properties.BlockStateProperties;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.block.state.BlockState;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+
+/** Bounded engine probes at the centre AND in newly available terrain. No whole-island scan. */
+public final class PopulationDiagnostics {
+    public static int regionsAtInitialSpawn;
+    private static final Direction[] HORIZONTAL = {Direction.NORTH, Direction.SOUTH, Direction.EAST, Direction.WEST};
+    private PopulationDiagnostics() {}
+
+    static void verifyLegacyIsolation(GameTestHelper helper) {
+        var level = helper.getLevel();
+        var binding = binding(level);
+        var generator = binding.generator();
+        var capacity = IslandCapacity.forGenerator(generator);
+        helper.assertTrue(capacity != null && capacity.players() == (level.getChunkSource().getGenerator() instanceof SanctuaryChunkGenerator unified
+                ? unified.capacity().players() : Integer.getInteger("sanctuary.test.players", 10)),
+            "The engine must create the requested production world preset");
+        helper.assertFalse(HydrologyRuntime.enabled(generator) || NaturalHydrologyRuntime.enabled(generator)
+            || LayeredHydrologyRuntime.enabled(generator) || WoodlandHydrologyRuntime.enabled(generator)
+            || RiftHydrologyRuntime.enabled(generator) || CavernHydrologyRuntime.enabled(generator),
+            "Only the population hydrology pipeline may run with the new settings");
+        var settings = level.registryAccess().lookupOrThrow(Registries.NOISE_SETTINGS);
+        for (var key : List.of(SanctuarySpawn.SETTINGS, SanctuarySpawn.RAISED_SETTINGS, SanctuarySpawn.HYDROLOGY_SETTINGS,
+                SanctuarySpawn.NATURAL_SETTINGS, SanctuarySpawn.LAYERED_SETTINGS, SanctuarySpawn.WOODLAND_SETTINGS,
+                SanctuarySpawn.RIFT_SETTINGS, SanctuarySpawn.CAVERN_SETTINGS)) {
+            var old = new NoiseBasedChunkGenerator(generator.getBiomeSource(), settings.getOrThrow(key));
+            helper.assertFalse(PopulationHydrologyRuntime.enabled(old), "A saved settings key must stay isolated: " + key);
+            helper.assertFalse(new PopulationGrovesFeature().place(level, old, RandomSource.create(0), BlockPos.ZERO),
+                "New trees must refuse older saved worlds");
+            helper.assertFalse(new PopulationDecorationsFeature().place(level, old, RandomSource.create(0), BlockPos.ZERO),
+                "New cave decorations must refuse older saved worlds");
+        }
+        if (level.getChunkSource().getGenerator() instanceof SanctuaryChunkGenerator) {
+            helper.assertTrue(generator.getBiomeSource() instanceof SanctuaryBiomeSource
+                    && generator.getBiomeSource().possibleBiomes().size() == 44,
+                "The unified generator must retain Population's ten layers and the 34 native expansion biomes");
+            helper.assertTrue(binding.random() != level.getChunkSource().randomState(),
+                "The unified starter must use its real terrain state, never the expansion host fallback");
+        } else {
+            helper.assertTrue(generator.getBiomeSource() instanceof PopulationIslandBiomeSource,
+                "The biome palette must use the new versioned resource family");
+            helper.assertTrue(generator.getBiomeSource().possibleBiomes().size() == 10
+                    && generator.getBiomeSource().possibleBiomes().stream().allMatch(b -> b.getRegisteredName().startsWith("sanctuary:population_")),
+                "All ten layers of the ecology must remain available at each capacity");
+        }
+    }
+
+    static void verifyDensity(GameTestHelper helper) throws IOException {
+        var level = helper.getLevel();
+        var binding = binding(level);
+        var generator = binding.generator();
+        var capacity = IslandCapacity.forGenerator(generator);
+        var density = level.registryAccess().lookupOrThrow(Registries.DENSITY_FUNCTION).getOrThrow(
+            ResourceKey.create(Registries.DENSITY_FUNCTION, SanctuaryMod.id("population_" + capacity.players()))).value();
+        helper.assertTrue(density instanceof PopulationIslandDensity, "Inspect the actual compiled population density");
+        var island = (PopulationIslandDensity) density;
+        helper.assertTrue(island.capacity() == capacity, "Noise settings and density must agree on saved capacity");
+        var random = binding.random();
+        var replay = RandomState.create(level.registryAccess().lookupOrThrow(Registries.NOISE), random.seed(), generator.generatorSettings().value());
+        int step = Math.max(8, (int) Math.ceil(capacity.terrainLimit() / 32.0));
+        int extent = (int) Math.ceil(capacity.terrainLimit() / (double) step) * step;
+        int solidColumns = 0, outerColumns = 0, emptyColumns = 0;
+        List<int[]> landCoordinates = new ArrayList<>();
+        Set<Integer> bottomHeights = new TreeSet<>();
+        StringBuilder map = new StringBuilder("x,z,bottom_y,top_y\n");
+        for (int x = -extent; x <= extent; x += step) for (int z = -extent; z <= extent; z += step) {
+            int bottom = -1, top = -1;
+            for (int y = 8; y < 384; y += 8) {
+                float value = random.sampleBlockValueUncached(density, x, y, z);
+                float raw = random.sampleBlockValueUncached(island.terrain(), x, y - 64, z);
+                helper.assertTrue(Float.isFinite(value), "Density remains finite at every sampled position");
+                helper.assertTrue(value <= 0 || raw > 0, "Enlarging the envelope must never invent terrain inside natural holes");
+                if (value > 0) { if (bottom < 0) bottom = y; top = y; }
+                if (x % (step * 8) == 0 && z % (step * 8) == 0)
+                    helper.assertTrue(Float.floatToIntBits(value) == Float.floatToIntBits(replay.sampleBlockValueUncached(density, x, y, z)),
+                        "Seed and capacity must replay identically without depending on region request order");
+            }
+            if (top >= 0) {
+                solidColumns++;
+                landCoordinates.add(new int[]{x, z});
+                bottomHeights.add(bottom);
+                if (Math.hypot(x, z) > IslandShape.TERRAIN_LIMIT + 16) outerColumns++;
+                helper.assertTrue(Math.hypot(x, z) < capacity.terrainLimit(), "Terrain stays inside its finite declared boundary");
+            } else emptyColumns++;
+            map.append(x).append(',').append(z).append(',').append(bottom).append(',').append(top).append('\n');
+        }
+        helper.assertTrue(solidColumns > 100 && emptyColumns > 100 && bottomHeights.size() >= 4,
+            "The sampled island must contain natural masses, holes and a varied underside");
+        int additionalColumns = 0;
+        if (capacity == IslandCapacity.TEN) {
+            var small = level.registryAccess().lookupOrThrow(Registries.DENSITY_FUNCTION).getOrThrow(
+                ResourceKey.create(Registries.DENSITY_FUNCTION, SanctuaryMod.id("population_5"))).value();
+            for (int[] coordinate : landCoordinates) {
+                boolean presentInSmall = false;
+                for (int y = 8; y < 384 && !presentInSmall; y += 8)
+                    presentInSmall = random.sampleBlockValueUncached(small, coordinate[0], y, coordinate[1]) > 0;
+                if (!presentInSmall) additionalColumns++;
+            }
+            helper.assertTrue(additionalColumns > 0,
+                "Large must add real land columns compared with Small on the same seed and sample grid");
+        } else helper.assertTrue(capacity.players() == 5 ? outerColumns == 0 : outerColumns > 100,
+            "The historical large capacities must contain land beyond the old island boundary");
+        Path directory = Path.of("diagnostics");
+        Files.createDirectories(directory);
+        String prefix = "population-" + capacity.players() + "-seed-" + level.getSeed();
+        Files.writeString(directory.resolve(prefix + "-density.csv"), map.toString());
+        Files.writeString(directory.resolve(prefix + "-density.json"), json(Map.of("players", capacity.players(),
+            "seed", level.getSeed(), "step", step, "solid_columns", solidColumns, "empty_columns", emptyColumns,
+            "solid_columns_beyond_old_boundary", outerColumns, "underside_heights", bottomHeights,
+            "scope", "sparse actual density samples; no resource extrapolation", "passed", true,
+            "additional_columns_vs_small", capacity == IslandCapacity.TEN ? additionalColumns : -1)));
+        SanctuaryMod.LOGGER.info("Capacity {} density seed {}: {} land columns, {} beyond the old envelope",
+            capacity.players(), level.getSeed(), solidColumns, outerColumns);
+    }
+
+    static void verifyExterior(GameTestHelper helper) {
+        var level = helper.getLevel();
+        var capacity = IslandCapacity.forGenerator(binding(level).generator());
+        int edge = Math.floorDiv(capacity.terrainLimit() + 48, 16) + 1;
+        for (int[] point : new int[][]{{edge,0},{-edge-1,0},{0,edge},{0,-edge-1},{256,0},{-257,0}}) {
+            var chunk = full(helper, level, point[0], point[1]);
+            for (var section : chunk.getSections()) helper.assertTrue(section.hasOnlyAir(),
+                "Completed terrain and decoration must remain void beyond this capacity: " + chunk.getPos());
+        }
+    }
+
+    static void verifyLowerMargin(GameTestHelper helper) {
+        var level = helper.getLevel();
+        for (int[] point : new int[][]{{0,0},{-8,0},{8,0},{0,-8},{0,8}}) {
+            var chunk = full(helper, level, point[0], point[1]);
+            for (int x = 0; x < 16; x++) for (int z = 0; z < 16; z++) for (int y = 0; y < 16; y++) {
+                var pos = new BlockPos(point[0]*16+x, y, point[1]*16+z);
+                var block = chunk.getBlockState(pos);
+                helper.assertTrue(block.isAir() || block.getFluidState().is(FluidTags.WATER) || block.getFluidState().is(FluidTags.LAVA),
+                    "The increased horizontal size must not add a lower floor: " + pos);
+            }
+        }
+    }
+
+    static void start(GameTestHelper helper) throws IOException {
+        var context = new Context(helper);
+        try { context.prepare(); }
+        catch (RuntimeException | Error | IOException e) { context.cleanup(); throw e; }
+        helper.onEachTick(() -> {
+            try { context.tick(); }
+            catch (RuntimeException | Error e) { context.cleanup(); throw e; }
+        });
+    }
+
+    private static final class Context {
+        final GameTestHelper helper;
+        final ServerLevel level;
+        final NoiseBasedChunkGenerator generator;
+        final RandomState random;
+        final IslandCapacity capacity;
+        final List<PopulationHydrologyRuntime.RegionPlan> regions = new ArrayList<>();
+        final Map<Long, LevelChunk> chunks = new TreeMap<>();
+        final Set<Long> forced = new HashSet<>();
+        final Set<BlockPos> expectedWater = new HashSet<>();
+        final Map<BlockPos, PopulationHydrology.Cell> selectedCells = new LinkedHashMap<>();
+        final Map<BlockPos, BlockState> naturalLogs = new HashMap<>();
+        final Set<BlockPos> declaredWater = new HashSet<>();
+        final Set<BlockPos> expectedLava = new HashSet<>();
+        final Set<BlockPos> lavaSupports = new HashSet<>();
+        final List<PopulationLavaDeposit.Cell> pocketCells = new ArrayList<>();
+        final List<PopulationLavaFlows.Fall> lavaFalls = new ArrayList<>();
+        final List<Map<String,Object>> flowReports = new ArrayList<>();
+        int reentryWitnesses;
+        final List<PopulationHydrology.Spring> springs = new ArrayList<>();
+        final List<PopulationHydrology.Spill> spills = new ArrayList<>();
+        final List<Map<String,Object>> regionReports = new ArrayList<>();
+        long startTime;
+        boolean running, closed;
+
+        Context(GameTestHelper helper) {
+            this.helper = helper; level = helper.getLevel();
+            var binding = binding(level);
+            generator = binding.generator();
+            random = binding.random();
+            capacity = IslandCapacity.forGenerator(generator);
+        }
+
+        void prepare() throws IOException {
+            helper.assertTrue(regionsAtInitialSpawn > 0 && regionsAtInitialSpawn <= 4,
+                "Initial spawn must plan only nearby regions, not materialize the large island: " + regionsAtInitialSpawn);
+            List<IslandCapacity.Region> targets = new ArrayList<>();
+            targets.add(new IslandCapacity.Region(0,0));
+            if (capacity.players() == 20) targets.add(new IslandCapacity.Region(1,0));
+            if (capacity.players() == 100) {
+                targets.add(new IslandCapacity.Region(1,1));
+                targets.add(new IslandCapacity.Region(2,0));
+            }
+            Set<Long> requested = new TreeSet<>();
+            for (var target : targets) {
+                SanctuaryMod.LOGGER.info("Capacity {}: inspecting hydrology in region {}", capacity.players(), target);
+                var region = PopulationHydrologyRuntime.regionPlan(generator, random, target);
+                regions.add(region);
+                var plan = region.water();
+                checkOwnership(region);
+                var ids = new HashSet<Long>();
+                plan.features().stream().filter(f -> f.kind() == PopulationHydrology.Kind.LAKE || f.kind() == PopulationHydrology.Kind.POND)
+                    .max(Comparator.comparingInt(PopulationHydrology.Feature::waterCells)).ifPresent(f -> ids.add(f.id()));
+                if (!plan.terraces().isEmpty()) ids.addAll(plan.terraces().getFirst().basinIds());
+                if (ids.isEmpty()) plan.features().stream().findFirst().ifPresent(f -> ids.add(f.id()));
+                for (var cell : plan.cells()) if (ids.contains(cell.featureId())) {
+                    selectedCells.put(new BlockPos(cell.x(), cell.bedY(), cell.z()), cell);
+                    request(requested, cell.x() >> 4, cell.z() >> 4, 1);
+                    if (cell.hasWater()) for (int y = cell.bedY()+1; y <= cell.waterY(); y++) expectedWater.add(new BlockPos(cell.x(),y,cell.z()));
+                }
+                for (var spill : plan.spills()) if (ids.contains(spill.fromFeatureId())) {
+                    spills.add(spill); request(requested, spill.flowBounds());
+                }
+                if (!plan.springs().isEmpty()) {
+                    var spring = plan.springs().getFirst(); springs.add(spring);
+                    request(requested, spring.flowBounds()); expectedWater.add(pos(spring.source()));
+                }
+                // Inspect the finite pocket and at most one volcanic fall per selected region.
+                var lava = region.lava();
+                Set<BlockPos> allFallSources = new HashSet<>(), allFallSupports = new HashSet<>();
+                for (var fall : lava.falls()) {
+                    allFallSources.add(lavaPos(fall.source()));
+                    fall.supports().forEach(p -> allFallSupports.add(lavaPos(p)));
+                }
+                for (var cell : lava.cells()) {
+                    BlockPos p = new BlockPos(cell.x(), cell.y(), cell.z());
+                    if (allFallSources.contains(p)) continue;
+                    pocketCells.add(cell);
+                    request(requested, cell.x() >> 4, cell.z() >> 4, 1);
+                    if (cell.lava()) expectedLava.add(p);
+                }
+                for (var support : lava.supports()) if (!allFallSupports.contains(lavaPos(support))) {
+                    lavaSupports.add(lavaPos(support));
+                    request(requested, support.x() >> 4, support.z() >> 4, 1);
+                }
+                if (!lava.falls().isEmpty()) {
+                    var fall = lava.falls().getFirst(); lavaFalls.add(fall);
+                    request(requested, fall.flowBounds()); expectedLava.add(lavaPos(fall.source()));
+                    fall.supports().forEach(p -> lavaSupports.add(lavaPos(p)));
+                }
+                // A small, independently selected patch proves full ecology beyond the former radius.
+                int ox = target.originX(), oz = target.originZ();
+                int bestX = ox, bestZ = oz; int highest = -1;
+                for (int dx = -144; dx <= 144; dx += 48) for (int dz = -144; dz <= 144; dz += 48) {
+                    int x = ox+dx, z=oz+dz;
+                    int top = generator.getBaseHeight(x,z,net.minecraft.world.level.levelgen.Heightmap.Types.WORLD_SURFACE,
+                        level,random);
+                    if (top > highest) { highest=top; bestX=x; bestZ=z; }
+                }
+                helper.assertTrue(highest > 48, "Every inspected region must contain real natural terrain");
+                request(requested, bestX >> 4, bestZ >> 4, 2);
+                regionReports.add(new LinkedHashMap<>(Map.of("region_x",target.x(),"region_z",target.z(),
+                    "planned_features",plan.features().size(),"planned_cells",plan.cells().size(),
+                    "planned_springs",plan.springs().size(),"planned_terraces",plan.terraces().size(),
+                    "ecology_patch_x",bestX,"ecology_patch_z",bestZ)));
+            }
+            helper.assertTrue(!expectedWater.isEmpty(), "The test must inspect retained production water");
+            if (capacity.players() > 10) helper.assertTrue(regions.stream().skip(1).anyMatch(r -> !r.water().cells().isEmpty()),
+                "Hydrology must occur on newly available terrain, not only around the old central island");
+            SanctuaryMod.LOGGER.info("Capacity {}: preparing {} bounded FULL chunks",capacity.players(),requested.size());
+            for (long packed : requested) {
+                var p=ChunkPos.unpack(packed);
+                if (level.setChunkForced(p.x(),p.z(),true)) forced.add(packed);
+            }
+            for (long packed : requested) {
+                var p=ChunkPos.unpack(packed); chunks.put(packed,full(helper,level,p.x(),p.z()));
+            }
+            for (long packed : requested) level.waitForEntities(ChunkPos.unpack(packed),0);
+            declaredWater.addAll(expectedWater);
+            captureNaturalLogs();
+            captureEcology();
+            export(false,0);
+        }
+
+        void checkOwnership(PopulationHydrologyRuntime.RegionPlan region) {
+            var owner=region.region(); var plan=region.water();
+            Set<Long> ids=new HashSet<>();
+            for(var feature:plan.features()) helper.assertTrue(ids.add(feature.id()),"Feature IDs must be unique within a region");
+            for(var cell:plan.cells()) {
+                helper.assertTrue(cell.x()>=owner.minX() && cell.x()<=owner.maxX() && cell.z()>=owner.minZ() && cell.z()<=owner.maxZ(),
+                    "Hydrology must never be truncated at or written across region ownership: "+cell);
+                helper.assertTrue(ids.contains(cell.featureId()),"Each retained cell needs its complete owning feature");
+                for(int y=cell.bedY()-cell.sedimentDepth()-1;y<=cell.bedY();y++)
+                    helper.assertTrue(random.sampleBlockValueUncached(
+                        generator.generatorSettings().value().noiseRouter().finalDensity(),cell.x(),y,cell.z())>0,
+                        "Regional translation must retain the real natural support below sediment: "+cell);
+            }
+            for(var terrace:plan.terraces()) helper.assertTrue(ids.containsAll(terrace.basinIds()),
+                "Admission must retain or reject a complete group of water terraces");
+            for(var spill:plan.spills()) helper.assertTrue(ids.contains(spill.fromFeatureId())
+                    && (spill.toFeatureId()==-1 || ids.contains(spill.toFeatureId())),
+                "No cascade may refer to a basin removed by region admission");
+            for(var bounds:region.lava().flowBounds()) helper.assertTrue(bounds.minX()>=owner.minX() && bounds.maxX()<=owner.maxX()
+                && bounds.minZ()>=owner.minZ() && bounds.maxZ()<=owner.maxZ(),"Volcanic flows must respect the same ownership");
+        }
+
+        void captureEcology() {
+            for (int i=0;i<regions.size();i++) {
+                var region=regions.get(i).region(); var counts=new TreeMap<String,Long>();
+                long logs=0,ores=0,nonAir=0;
+                for(var chunk:chunks.values()) {
+                    int x=chunk.getPos().getMinBlockX(),z=chunk.getPos().getMinBlockZ();
+                    if (!capacity.regionAt(x,z).equals(region)) continue;
+                    for(var section:chunk.getSections()) section.getStates().count((state,count)->{
+                        if(!state.isAir()) counts.merge(BuiltInRegistries.BLOCK.getKey(state.getBlock()).toString(),(long)count,Long::sum);
+                    });
+                }
+                for(var entry:counts.entrySet()) {
+                    nonAir+=entry.getValue();
+                    if(entry.getKey().endsWith("_log")) logs+=entry.getValue();
+                    if(entry.getKey().endsWith("_ore")) ores+=entry.getValue();
+                }
+                helper.assertTrue(nonAir>1000,"Distant FULL chunks must contain the new island");
+                helper.assertTrue(logs>0,"Trees must decorate each inspected region, including outside the old envelope");
+                helper.assertTrue(ores>0,"Ore features must also decorate the new distant terrain");
+                regionReports.get(i).put("observed_blocks",counts);
+                regionReports.get(i).put("observed_logs",logs);
+                regionReports.get(i).put("observed_ores",ores);
+            }
+        }
+
+        void tick() {
+            if(closed || running || helper.getTick()<20) return;
+            if(!chunks.keySet().stream().allMatch(level::isPositionTickingWithEntitiesLoaded)) {
+                helper.assertTrue(helper.getTick()<800,"All forced inspection chunks must become ready for real fluid ticks");
+                return;
+            }
+            running=true; startTime=level.getGameTime();
+            verifyWater();
+            verifyFinishedShell();
+            verifyLava();
+            helper.runAfterDelay(1800,()->{
+                try {
+                    helper.assertTrue(chunks.keySet().stream().allMatch(level::isPositionTickingWithEntitiesLoaded),
+                        "Chunks must remain scheduler-ready throughout the measured fluid interval");
+                    verifyWater();
+                    verifyFinishedShell();
+                    verifyLava();
+                    for (var spring : springs) verifySpring(spring);
+                    for(var spill:spills) {
+                        Set<BlockPos> destination=null;
+                        if(spill.toFeatureId()!=-1) {
+                            destination=new HashSet<>();
+                            for(var region:regions) for(var cell:region.water().cells()) if(cell.featureId()==spill.toFeatureId() && cell.hasWater())
+                                destination.add(new BlockPos(cell.x(),cell.waterY(),cell.z()));
+                        }
+                        int drop=connectedDescent(pos(spill.source()),pos(spill.outlet()),destination);
+                        helper.assertTrue(drop >= (destination==null?12:4),"Each retained cascade must connect downhill to its basin or fall: "+spill);
+                    }
+                    for (var fall : lavaFalls) {
+                        int descent = connectedDescent(lavaPos(fall.source()), lavaPos(fall.outlet()), null, true);
+                        helper.assertTrue(descent >= 8, "A translated volcanic fall must descend through real lava ticks: " + fall.source());
+                    }
+                    verifyPostProcessingReentry();
+                    export(true,level.getGameTime()-startTime);
+                    helper.succeed();
+                } catch (RuntimeException | Error failure) {
+                    try { export(false, level.getGameTime() - startTime); }
+                    catch (IOException e) { failure.addSuppressed(e); }
+                    throw failure;
+                } catch(IOException e) {throw new IllegalStateException(e);}
+                finally {cleanup();}
+            });
+        }
+
+        PopulationHydrology.Plan waterPlanAt(int x, int z) {
+            var owner = capacity.regionAt(x, z);
+            return regions.stream().filter(r -> r.region().equals(owner)).map(PopulationHydrologyRuntime.RegionPlan::water)
+                .findFirst().orElse(null);
+        }
+
+        PopulationHydrology.Cell cellAt(BlockPos p) {
+            var plan = waterPlanAt(p.getX(), p.getZ());
+            return plan == null ? null : plan.cellAt(p.getX(), p.getY(), p.getZ());
+        }
+
+        float natural(BlockPos p) {
+            return random.sampleBlockValueUncached(
+                generator.generatorSettings().value().noiseRouter().finalDensity(), p.getX(), p.getY(), p.getZ());
+        }
+
+        void captureNaturalLogs() {
+            for (BlockPos p : declaredWater) {
+                BlockState state = level.getBlockState(p);
+                if (state.getFluidState().is(FluidTags.WATER) && state.getFluidState().isSource()) continue;
+                var cell = cellAt(p);
+                boolean horizontal = state.is(BlockTags.LOGS) && state.hasProperty(BlockStateProperties.AXIS)
+                    && state.getValue(BlockStateProperties.AXIS) != Direction.Axis.Y;
+                boolean lowerWater = declaredWater.contains(p.below())
+                    && level.getFluidState(p.below()).is(FluidTags.WATER) && level.getFluidState(p.below()).isSource();
+                boolean bed = cell != null && cell.bedY() == p.getY() - 1
+                    && level.getBlockState(p.below()).isCollisionShapeFullBlock(level, p.below());
+                boolean beside = Arrays.stream(HORIZONTAL).map(p::relative).anyMatch(side -> declaredWater.contains(side)
+                    && level.getFluidState(side).is(FluidTags.WATER) && level.getFluidState(side).isSource());
+                helper.assertTrue(cell != null && horizontal && p.getY() == cell.waterY() && (lowerWater || bed) && beside,
+                    "Only a supported horizontal surface log beside real retained source water may occupy a planned water voxel: " + p + "=" + state);
+                naturalLogs.put(p.immutable(), state); expectedWater.remove(p);
+            }
+            helper.assertTrue(expectedWater.size() + naturalLogs.size() == declaredWater.size(),
+                "Every selected water voxel must have an exact retained source or recorded log");
+        }
+
+        void verifyFinishedShell() {
+            for (var cell : selectedCells.values()) {
+                var plan = waterPlanAt(cell.x(), cell.z());
+                var kind = plan.features().stream().filter(f -> f.id() == cell.featureId()).findFirst().orElseThrow().kind();
+                int cut = !cell.hasWater() ? kind == PopulationHydrology.Kind.RIVER ? PopulationHydrology.MAX_RIVER_BANK_CARVE : 2
+                    : kind == PopulationHydrology.Kind.TERRACE ? PopulationTerraces.MAX_CARVE
+                    : kind == PopulationHydrology.Kind.LAKE ? PopulationHydrology.MAX_LAKE_CARVE : PopulationHydrology.MAX_CARVE;
+                helper.assertTrue(cell.sedimentDepth() >= 3 && cell.sedimentDepth() <= 5 && cell.carveTop() - cell.bedY() <= cut,
+                    "Regional sediment and carving must keep their feature-specific budgets: " + cell);
+                for (int d = 0; d <= cell.sedimentDepth() + 1; d++) {
+                    BlockPos p = new BlockPos(cell.x(), cell.bedY() - d, cell.z());
+                    BlockState actual = level.getBlockState(p);
+                    helper.assertTrue(natural(p) > 0 && actual.isCollisionShapeFullBlock(level, p),
+                        "Every sediment layer and its two natural supports must remain full after generation and ticks: " + p + "=" + actual);
+                    if (d >= cell.sedimentDepth()) continue;
+                    BlockState expected = PopulationMaterials.sedimentBlock(cell, random.seed(), d);
+                    boolean ore = actual.is(Blocks.COAL_ORE) || actual.is(Blocks.DEEPSLATE_COAL_ORE)
+                        || actual.is(Blocks.IRON_ORE) || actual.is(Blocks.DEEPSLATE_IRON_ORE)
+                        || actual.is(Blocks.COPPER_ORE) || actual.is(Blocks.DEEPSLATE_COPPER_ORE)
+                        || actual.is(Blocks.GOLD_ORE) || actual.is(Blocks.DEEPSLATE_GOLD_ORE)
+                        || actual.is(Blocks.REDSTONE_ORE) || actual.is(Blocks.DEEPSLATE_REDSTONE_ORE)
+                        || actual.is(Blocks.LAPIS_ORE) || actual.is(Blocks.DEEPSLATE_LAPIS_ORE)
+                        || actual.is(Blocks.DIAMOND_ORE) || actual.is(Blocks.DEEPSLATE_DIAMOND_ORE)
+                        || actual.is(Blocks.EMERALD_ORE) || actual.is(Blocks.DEEPSLATE_EMERALD_ORE);
+                    helper.assertTrue(actual.equals(expected) || expected.is(BlockTags.BASE_STONE_OVERWORLD) && ore
+                            || expected.is(Blocks.GRASS_BLOCK) && actual.is(Blocks.DIRT),
+                        "The selected regional sediment profile must survive decoration: " + p + " expected=" + expected + " actual=" + actual);
+                }
+                if (!cell.hasWater()) continue;
+                int maxDepth = kind == PopulationHydrology.Kind.TERRACE ? PopulationTerraces.MAX_DEPTH : PopulationHydrology.MAX_DEPTH;
+                helper.assertTrue(cell.waterY() > cell.bedY() && cell.waterY() - cell.bedY() <= maxDepth,
+                    "Retained water must respect its feature depth limit");
+                for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) for (Direction direction : HORIZONTAL) {
+                    BlockPos wall = new BlockPos(cell.x(), y, cell.z()).relative(direction);
+                    var next = cellAt(wall);
+                    boolean plannedWater = next != null && next.hasWater() && y > next.bedY() && y <= next.waterY();
+                    if (plannedWater || plan.isSpillOpening(wall.getX(), wall.getY(), wall.getZ())) continue;
+                    helper.assertTrue(natural(wall) > 0 && level.getBlockState(wall).isCollisionShapeFullBlock(level, wall),
+                        "A retained basin must preserve its actual natural underwater shell, except its declared outlet: " + wall);
+                }
+                if (kind == PopulationHydrology.Kind.TERRACE) {
+                    for (int y = cell.carveTop() + 1; y <= cell.carveTop() + 4; y++)
+                        helper.assertTrue(natural(new BlockPos(cell.x(), y, cell.z())) <= 0, "A cave terrace needs four natural headroom blocks");
+                    boolean roof = false;
+                    for (int y = cell.carveTop() + 5; y < 384 && !roof; y++) roof = natural(new BlockPos(cell.x(), y, cell.z())) > 0;
+                    helper.assertTrue(roof, "A lower terrace must remain below an existing natural roof");
+                } else for (int y = cell.carveTop() + 1; y < 384; y++)
+                    helper.assertTrue(natural(new BlockPos(cell.x(), y, cell.z())) <= 0, "A surface basin must be exposed to the natural sky");
+            }
+        }
+
+        void verifyLava() {
+            for (BlockPos p : expectedLava) helper.assertTrue(natural(p) > 0
+                    && level.getFluidState(p).is(FluidTags.LAVA) && level.getFluidState(p).isSource(),
+                "Every inspected lava source must replace natural rock and survive actual fluid ticks: " + p);
+            for (BlockPos p : lavaSupports) {
+                BlockState block = level.getBlockState(p);
+                helper.assertTrue(natural(p) > 0 && block.isCollisionShapeFullBlock(level, p) && !block.ignitedByLava(),
+                    "A selected volcanic niche must keep its actual nonflammable natural support: " + p);
+            }
+            for (var cell : pocketCells) if (!cell.lava()) {
+                BlockPos p = new BlockPos(cell.x(), cell.y(), cell.z());
+                BlockState block = level.getBlockState(p);
+                // Wall lichen can light the excavated chamber without obstructing its dry access.
+                helper.assertTrue(natural(p) > 0 && (block.isAir() || block.is(Blocks.GLOW_LICHEN))
+                        && block.getCollisionShape(level, p).isEmpty() && block.getFluidState().isEmpty(),
+                    "The lava pocket must keep its excavated two-block approach and chamber accessible: " + p + " = " + block);
+            }
+        }
+
+        void verifySpring(PopulationHydrology.Spring spring) {
+            var plan = waterPlanAt(spring.outlet().x(), spring.outlet().z());
+            var channel = plan == null ? null : plan.cellAt(spring.outlet().x(), spring.outlet().z());
+            if (channel != null && plan.isRiverCell(channel) && spring.outlet().y() > channel.waterY()
+                    && spring.outlet().y() <= channel.carveTop()) {
+                int expectedDrop = spring.source().y() - channel.waterY();
+                helper.assertTrue(expectedDrop >= 5, "A river inlet must start above its retained channel");
+                Set<BlockPos> destination = new HashSet<>();
+                for (var cell : plan.cells()) if (cell.featureId() == channel.featureId() && cell.hasWater())
+                    destination.add(new BlockPos(cell.x(), cell.waterY(), cell.z()));
+                helper.assertTrue(connectedDescent(pos(spring.source()), pos(spring.outlet()), destination) >= expectedDrop,
+                    "The translated inlet must actually connect downhill into its river");
+            } else {
+                int predicted = spring.source().y() - spring.flowPath().stream().mapToInt(PopulationHydrology.Position::y).min().orElse(spring.source().y());
+                helper.assertTrue(connectedDescent(pos(spring.source()), pos(spring.outlet()), null) >= Math.max(8, Math.min(16, predicted)),
+                    "An independent spring must actually descend through vanilla ticks: " + spring.source());
+            }
+        }
+
+        void verifyPostProcessingReentry() {
+            var outlets = new LinkedHashSet<BlockPos>();
+            if (!springs.isEmpty()) outlets.add(pos(springs.getFirst().outlet()));
+            if (!spills.isEmpty()) outlets.add(pos(spills.getFirst().outlet()));
+            if (!lavaFalls.isEmpty()) outlets.add(lavaPos(lavaFalls.getFirst().outlet()));
+            for (BlockPos outlet : outlets) {
+                LevelChunk chunk = chunks.get(ChunkPos.pack(outlet));
+                helper.assertTrue(chunk != null && Arrays.stream(chunk.getPostProcessing()).allMatch(m -> m == null || m.isEmpty()),
+                    "Re-entry uses a finished inspected chunk with consumed generation markers");
+                helper.assertTrue(PopulationSpringOutlets.capturePending(level, chunk).isEmpty(),
+                    "An already generated chunk has no pending population outlet work");
+                BlockState original = level.getBlockState(outlet);
+                BlockState witness = Blocks.GLOW_LICHEN.defaultBlockState().setValue(MultifaceBlock.getFaceProperty(Direction.UP), true);
+                try {
+                    level.setBlock(outlet, witness, 2);
+                    chunk.postProcessGeneration(level);
+                    helper.assertTrue(level.getBlockState(outlet).equals(witness),
+                        "Post-processing re-entry must preserve a later construction at a completed outlet: " + outlet);
+                } finally { level.setBlock(outlet, original, 2); }
+                helper.assertTrue(level.getBlockState(outlet).equals(original), "Restore the development-world witness exactly");
+                reentryWitnesses++;
+            }
+        }
+
+        boolean isFluid(BlockPos p, boolean lava) {
+            return lava ? level.getFluidState(p).is(FluidTags.LAVA) : level.getFluidState(p).is(FluidTags.WATER);
+        }
+
+        void verifyWater() {
+            for (var entry : naturalLogs.entrySet()) {
+                BlockPos p = entry.getKey();
+                helper.assertTrue(level.getBlockState(p).equals(entry.getValue()), "A recorded natural log must retain its exact state");
+                helper.assertTrue(level.getBlockState(p.below()).isCollisionShapeFullBlock(level, p.below())
+                        || level.getFluidState(p.below()).is(FluidTags.WATER) && level.getFluidState(p.below()).isSource(),
+                    "A horizontal log must retain its original bed or source water underneath");
+                helper.assertTrue(Arrays.stream(HORIZONTAL).map(p::relative).anyMatch(side -> expectedWater.contains(side)
+                        && level.getFluidState(side).is(FluidTags.WATER) && level.getFluidState(side).isSource()),
+                    "A horizontal log must remain beside actual retained water");
+            }
+            for(var p:expectedWater) helper.assertTrue(level.getFluidState(p).is(FluidTags.WATER)
+                && level.getFluidState(p).isSource(),"Retained water must survive generation and vanilla fluid ticks: "+p+"="+level.getBlockState(p));
+        }
+
+        int connectedDescent(BlockPos source,BlockPos outlet,Set<BlockPos> destination) {
+            return connectedDescent(source, outlet, destination, false);
+        }
+
+        int connectedDescent(BlockPos source,BlockPos outlet,Set<BlockPos> destination, boolean lava) {
+            helper.assertTrue(source.distManhattan(outlet)==1,"A natural outlet must adjoin its source");
+            helper.assertTrue(isFluid(outlet, lava),"The production post-processing must leave a flowing outlet: "+outlet);
+            var seen=new HashSet<BlockPos>(); var queue=new ArrayDeque<BlockPos>();
+            seen.add(outlet);queue.add(outlet);int drop=0;boolean reached=destination==null;
+            while(!queue.isEmpty() && seen.size()<150000) {
+                var at=queue.removeFirst(); drop=Math.max(drop,source.getY()-at.getY());
+                if(destination!=null && destination.contains(at)) reached=true;
+                for(var direction:new Direction[]{Direction.DOWN,Direction.NORTH,Direction.SOUTH,Direction.EAST,Direction.WEST}) {
+                    var next=at.relative(direction);
+                    if(next.getY()<0 || !chunks.containsKey(ChunkPos.pack(next)) || seen.contains(next))continue;
+                    if(isFluid(next, lava)) {seen.add(next);queue.addLast(next);}
+                }
+            }
+            helper.assertTrue(queue.isEmpty(), "The finite flow inspection must exhaust its search budget");
+            helper.assertTrue(reached,"The actual downhill water component must reach its declared receiving basin");
+            flowReports.add(Map.of("source", source, "outlet", outlet, "fluid", lava ? "lava" : "water",
+                "actual_descending_blocks", seen.size(), "actual_drop", drop, "reaches_destination", reached));
+            return drop;
+        }
+
+        void export(boolean passed,long elapsed) throws IOException {
+            Path output=Path.of("diagnostics","population-"+capacity.players()+"-seed-"+level.getSeed()+"-engine.json");
+            Files.createDirectories(output.getParent());
+            var report=new LinkedHashMap<String,Object>();
+            report.put("players",capacity.players());report.put("seed",level.getSeed());
+            report.put("terrain_seed", random.seed());
+            if (level.getChunkSource().getGenerator() instanceof SanctuaryChunkGenerator unified) {
+                report.put("generation", 13); report.put("diameter", unified.initialDiameter());
+                report.put("rejected_decoration_writes", unified.rejectedDecorationWrites());
+            }
+            report.put("mod_version",FabricLoader.getInstance().getModContainer("sanctuary").orElseThrow().getMetadata().getVersion().getFriendlyString());
+            report.put("settings",generator.generatorSettings().getRegisteredName());
+            report.put("regions_at_initial_spawn",regionsAtInitialSpawn);
+            report.put("regions_cached_after_inspection",PopulationHydrologyRuntime.cachedRegionCount(random));
+            report.put("regions",regionReports);report.put("inspected_full_chunks",chunks.size());
+            report.put("retained_water_blocks",expectedWater.size());report.put("tested_springs",springs.size());
+            report.put("tested_spills",spills.size());report.put("fluid_ticks",elapsed);
+            report.put("selected_sediment_columns", selectedCells.size());
+            report.put("natural_horizontal_logs", naturalLogs.size());
+            report.put("retained_lava_sources", expectedLava.size()); report.put("tested_lava_falls", lavaFalls.size());
+            report.put("flows", flowReports); report.put("postprocessing_reentry_witnesses", reentryWitnesses);
+            report.put("scope","Selected basins, terraces, springs and ecology patches in explicit regions; no whole-island inventory or multiplayer load test");
+            report.put("passed",passed);Files.writeString(output,json(report));
+            if(passed) SanctuaryMod.LOGGER.info("Capacity {} seed {} passed: {} FULL chunks, {} retained water blocks, {} fluid ticks",
+                capacity.players(),level.getSeed(),chunks.size(),expectedWater.size(),elapsed);
+        }
+        void cleanup() {
+            if(closed)return;closed=true;
+            for(long key:forced) {var p=ChunkPos.unpack(key);level.setChunkForced(p.x(),p.z(),false);}
+        }
+    }
+
+    private static PopulationGenerationContext.Binding binding(ServerLevel level) {
+        return Objects.requireNonNull(PopulationGenerationContext.of(level), "This diagnostic requires Population or unified Sanctuary generation");
+    }
+
+    private static String json(Object value) {return new GsonBuilder().setPrettyPrinting().create().toJson(value)+"\n";}
+    private static BlockPos pos(PopulationHydrology.Position p) {return new BlockPos(p.x(),p.y(),p.z());}
+    private static BlockPos lavaPos(PopulationLavaDeposit.Position p) {return new BlockPos(p.x(),p.y(),p.z());}
+    private static LevelChunk full(GameTestHelper helper,ServerLevel level,int x,int z) {
+        var chunk=level.getChunkSource().getChunk(x,z,ChunkStatus.FULL,true);
+        helper.assertTrue(chunk instanceof LevelChunk,"The inspected chunk must be fully generated");return(LevelChunk)chunk;
+    }
+    private static void request(Set<Long> requested,int x,int z,int halo) {
+        for(int dx=-halo;dx<=halo;dx++)for(int dz=-halo;dz<=halo;dz++)requested.add(ChunkPos.pack(x+dx,z+dz));
+    }
+    private static void request(Set<Long> requested,PopulationHydrology.FlowBounds b) {
+        for(int x=(b.minX()>>4)-1;x<=(b.maxX()>>4)+1;x++)for(int z=(b.minZ()>>4)-1;z<=(b.maxZ()>>4)+1;z++)requested.add(ChunkPos.pack(x,z));
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/PopulationPersistenceDiagnostics.java

@@ -0,0 +1,95 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import com.mojang.serialization.JsonOps;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.IslandCapacity;
+import fr.koka.sanctuary.worldgen.PopulationIslandDensity;
+import fr.koka.sanctuary.worldgen.SanctuarySpawn;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.tags.WorldPresetTags;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.WorldDimensions;
+import net.minecraft.world.level.levelgen.WorldGenSettings;
+import net.minecraft.world.level.levelgen.WorldOptions;
+import net.minecraft.world.level.storage.LevelStorageSource;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/** Uses the real 26.3 saved-data writer and reader; never opens the user's saves. */
+final class PopulationPersistenceDiagnostics {
+    static void verify(GameTestHelper helper) throws IOException {
+        var level = helper.getLevel();
+        var access = level.registryAccess();
+        var presets = access.lookupOrThrow(Registries.WORLD_PRESET);
+        var standard = presets.getOrThrow(ResourceKey.create(Registries.WORLD_PRESET,
+            SanctuaryMod.id("sanctuary"))).value();
+        helper.assertTrue(standard.createWorldDimensions().overworld() instanceof fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator unified && unified.initialDiameter() == 724,
+            "The public Sanctuary preset defaults to the unified medium geometry");
+        var visible = presets.getOrThrow(WorldPresetTags.NORMAL).stream().map(holder -> holder.getRegisteredName())
+            .filter(name -> name.startsWith("sanctuary:")).collect(Collectors.toSet());
+        helper.assertTrue(visible.equals(Set.of("sanctuary:sanctuary")),
+            "Only Sanctuary is public; saved historical presets remain registered");
+        helper.assertTrue(presets.getOrThrow(ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id("expansion_lab")))
+                .value().createWorldDimensions().overworld() instanceof fr.koka.sanctuary.expansion.ExpansionChunkGenerator,
+            "The laboratory must use its own codec, without changing the existing presets");
+        var oldDensity = (PopulationIslandDensity) access.lookupOrThrow(Registries.DENSITY_FUNCTION)
+            .getOrThrow(ResourceKey.create(Registries.DENSITY_FUNCTION, SanctuaryMod.id("population_20"))).value();
+        var ops = RegistryOps.create(JsonOps.INSTANCE, access);
+        var serialized = PopulationIslandDensity.CODEC.codec().encodeStart(ops, oldDensity).getOrThrow().getAsJsonObject();
+        serialized.remove("players");
+        helper.assertTrue(PopulationIslandDensity.CODEC.codec().parse(ops, serialized).getOrThrow().capacity() == IslandCapacity.TWENTY,
+            "An omitted alpha10 density field must keep its historical default, independently of the new world selector");
+        List<Map<String, Object>> results = new ArrayList<>();
+        Path testRoot = Path.of("diagnostics", "population-persistence-seed-" + level.getSeed()).toAbsolutePath();
+        Files.createDirectories(testRoot);
+        LevelStorageSource storage = LevelStorageSource.createDefault(testRoot);
+        for (int players : new int[]{5, 10, 20, 100}) {
+            String presetId = "sanctuary_" + players;
+            WorldDimensions dimensions = presets.getOrThrow(ResourceKey.create(Registries.WORLD_PRESET,
+                SanctuaryMod.id(presetId))).value().createWorldDimensions();
+            helper.assertTrue(IslandCapacity.forGenerator(dimensions.overworld()) == IslandCapacity.fromPlayers(players),
+                "The selectable world type must resolve its declared capacity");
+            var original = new WorldGenSettings(new WorldOptions(level.getSeed(), true, false), dimensions);
+            String name = "players-" + players;
+            try (var save = storage.createAccess(name)) {
+                LevelStorageSource.writeWorldGenSettings(access, storage.getLevelPath(name), original);
+                var restored = LevelStorageSource.readExistingSavedData(save, access, WorldGenSettings.TYPE).getOrThrow();
+                var generator = (NoiseBasedChunkGenerator) restored.dimensions().overworld();
+                helper.assertTrue(IslandCapacity.forGenerator(generator) == IslandCapacity.fromPlayers(players),
+                    "Saved generator settings must preserve the chosen capacity after reading the world from disk");
+                helper.assertTrue(generator.generatorSettings().getRegisteredName().equals("sanctuary:population_" + players),
+                    "The saved world must retain its explicit versioned settings key");
+                helper.assertTrue(restored.options().seed() == level.getSeed(), "The seed must survive storage unchanged");
+                results.add(Map.of("players", players, "preset", "sanctuary:" + presetId,
+                    "restored_settings", generator.generatorSettings().getRegisteredName(), "disk_round_trip", true));
+            }
+        }
+        var old = new NoiseBasedChunkGenerator(standard.createWorldDimensions().overworld().getBiomeSource(),
+            access.lookupOrThrow(Registries.NOISE_SETTINGS).getOrThrow(SanctuarySpawn.CAVERN_SETTINGS));
+        var savedOld = new WorldGenSettings(new WorldOptions(level.getSeed(), true, false),
+            standard.createWorldDimensions().replaceOverworldGenerator(access, old));
+        try (var save = storage.createAccess("legacy-alpha9")) {
+            LevelStorageSource.writeWorldGenSettings(access, storage.getLevelPath("legacy-alpha9"), savedOld);
+            var restored = LevelStorageSource.readExistingSavedData(save, access, WorldGenSettings.TYPE).getOrThrow();
+            var generator = (NoiseBasedChunkGenerator) restored.dimensions().overworld();
+            helper.assertTrue(generator.generatorSettings().is(SanctuarySpawn.CAVERN_SETTINGS)
+                && IslandCapacity.forGenerator(generator) == null,
+                "An existing alpha.9 settings reference must not acquire the new default capacity");
+        }
+        Files.writeString(testRoot.resolve("round-trip.json"), new GsonBuilder().setPrettyPrinting().create().toJson(Map.of(
+            "seed", level.getSeed(), "default_players", 10, "profiles", results,
+            "legacy_settings_preserved", "sanctuary:sanctuary_cavern", "visible_presets", visible,
+            "omitted_density_capacity_preserved", 20, "passed", true)) + "\n");
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/ResourceSurveyDiagnostics.java

@@ -4,6 +4,7 @@ import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 import fr.koka.sanctuary.SanctuaryMod;
 import fr.koka.sanctuary.worldgen.IslandShape;
+import fr.koka.sanctuary.worldgen.IslandCapacity;
 import fr.koka.sanctuary.worldgen.SanctuarySpawn;
 import net.fabricmc.loader.api.FabricLoader;
 import net.minecraft.SharedConstants;
@@ -58,7 +59,9 @@ public final class ResourceSurveyDiagnostics {
         long initialGameTime = level.getGameTime();
         int centreX = initialSpawn.pos().getX() >> 4;
         int centreZ = initialSpawn.pos().getZ() >> 4;
-        int envelopeRadius = IslandShape.TERRAIN_LIMIT + DECORATION_MARGIN;
+        IslandCapacity capacity = IslandCapacity.forGenerator(level.getChunkSource().getGenerator());
+        int terrainRadius = capacity == null ? IslandShape.TERRAIN_LIMIT : capacity.terrainLimit();
+        int envelopeRadius = terrainRadius + DECORATION_MARGIN;
         int minimumIslandChunk = Math.floorDiv(-envelopeRadius, 16);
         int maximumIslandChunk = Math.floorDiv(envelopeRadius - 1, 16);
         int minimumX = mode.equals("island") ? minimumIslandChunk : centreX - 1;
@@ -135,7 +138,7 @@ public final class ResourceSurveyDiagnostics {
         report.put("mode", mode);
         report.put("seed", level.getSeed());
         report.put("minecraft_version", SharedConstants.getCurrentVersion().name());
-        report.put("generator", Map.of("preset", "sanctuary:sanctuary", "noise_settings", settingsHolder.getRegisteredName(),
+        report.put("generator", Map.of("preset", capacity == null || capacity.players() == 20 ? "sanctuary:sanctuary" : "sanctuary:sanctuary_" + capacity.players(), "noise_settings", settingsHolder.getRegisteredName(),
             "mod_version", modVersion, "version", "sanctuary@" + modVersion,
             "noise_min_y", settings.noiseSettings().minY(),
             "noise_max_y_exclusive", settings.noiseSettings().minY() + settings.noiseSettings().height()));
@@ -149,7 +152,7 @@ public final class ResourceSurveyDiagnostics {
             "min_y_inclusive", level.getMinY(), "max_y_exclusive", level.getMinY() + level.getHeight(),
             "min_chunk_x_inclusive", minimumX, "max_chunk_x_inclusive", maximumX,
             "min_chunk_z_inclusive", minimumZ, "max_chunk_z_inclusive", maximumZ));
-        report.put("declared_island_envelope", Map.of("terrain_radius_blocks", IslandShape.TERRAIN_LIMIT,
+        report.put("declared_island_envelope", Map.of("terrain_radius_blocks", terrainRadius,
             "decoration_margin_blocks", DECORATION_MARGIN, "bounding_rectangle_radius_blocks", envelopeRadius));
         report.put("completeness", Map.of("requested_chunks", expectedChunks, "inspected_full_chunks", chunks.size(),
             "complete_within_requested_bounds", true, "covers_declared_island_envelope", mode.equals("island"),
@@ -172,7 +175,7 @@ public final class ResourceSurveyDiagnostics {
             "scope", "snapshot after FULL generation; no resource quotas or terrain correction applied"));
         Path directory = Path.of("diagnostics");
         Files.createDirectories(directory);
-        Path output = directory.resolve("resource-survey-seed-" + level.getSeed() + "-" + mode + ".json");
+        Path output = directory.resolve("resource-survey-" + (capacity == null ? "legacy" : "players-" + capacity.players()) + "-seed-" + level.getSeed() + "-" + mode + ".json");
         Files.writeString(output, JSON.toJson(report) + "\n");
         SanctuaryMod.LOGGER.info("Resource survey {} complete: {} FULL chunks, {} non-air blocks; {}",
             mode, chunks.size(), totalCells - air, output.toAbsolutePath());

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/SanctuaryWorldGameTests.java

@@ -1,6 +1,15 @@
 package fr.koka.sanctuary.gametest;
 
 import fr.koka.sanctuary.worldgen.SanctuarySpawn;
+import fr.koka.sanctuary.worldgen.IslandCapacity;
+import fr.koka.sanctuary.worldgen.PopulationHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.NaturalHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.LayeredHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.WoodlandHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.RiftHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.CavernHydrologyRuntime;
+import net.minecraft.tags.FluidTags;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
 import fr.koka.sanctuary.worldgen.IslandShape;
 import fr.koka.sanctuary.worldgen.MainIslandDensity;
 import fr.koka.sanctuary.SanctuaryMod;
@@ -23,14 +32,40 @@ import net.minecraft.world.level.storage.LevelData;
 public final class SanctuaryWorldGameTests {
     public static LevelData.RespawnData initialSpawn;
 
-    @GameTest(maxTicks = 400)
+    @GameTest(maxTicks = 3000)
+    public void optimizedDensityPreservesSavedTerrain(GameTestHelper helper) throws Exception {
+        PopulationDensityEquivalenceDiagnostics.verify(helper);
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 200)
+    public void populationChoiceSurvivesSavingTheWorld(GameTestHelper helper) throws java.io.IOException {
+        PopulationPersistenceDiagnostics.verify(helper);
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 3000)
     public void generatedSurfaceWaterRemainsContained(GameTestHelper helper) throws java.io.IOException {
-        HydrologyDiagnostics.start(helper);
+        var generator = (NoiseBasedChunkGenerator) helper.getLevel().getChunkSource().getGenerator();
+        if (PopulationHydrologyRuntime.enabled(generator)) PopulationDiagnostics.start(helper);
+        else if (CavernHydrologyRuntime.enabled(generator)) CavernDiagnostics.start(helper);
+        else if (RiftHydrologyRuntime.enabled(generator)) RiftDiagnostics.start(helper);
+        else if (WoodlandHydrologyRuntime.enabled(generator)) WoodlandDiagnostics.start(helper);
+        else if (LayeredHydrologyRuntime.enabled(generator)) LayeredHydrologyDiagnostics.start(helper);
+        else if (NaturalHydrologyRuntime.enabled(generator)) NaturalHydrologyDiagnostics.start(helper);
+        else HydrologyDiagnostics.start(helper);
     }
 
     @GameTest(maxTicks = 200)
     public void hydrologyDoesNotActivateForSavedLegacySettings(GameTestHelper helper) {
-        HydrologyDiagnostics.verifyLegacyIsolation(helper);
+        var generator = (NoiseBasedChunkGenerator) helper.getLevel().getChunkSource().getGenerator();
+        if (PopulationHydrologyRuntime.enabled(generator)) PopulationDiagnostics.verifyLegacyIsolation(helper);
+        else if (CavernHydrologyRuntime.enabled(generator)) CavernDiagnostics.verifyLegacyIsolation(helper);
+        else if (RiftHydrologyRuntime.enabled(generator)) RiftDiagnostics.verifyLegacyIsolation(helper);
+        else if (WoodlandHydrologyRuntime.enabled(generator)) WoodlandDiagnostics.verifyLegacyIsolation(helper);
+        else if (LayeredHydrologyRuntime.enabled(generator)) LayeredHydrologyDiagnostics.verifyLegacyIsolation(helper);
+        else if (NaturalHydrologyRuntime.enabled(generator)) NaturalHydrologyDiagnostics.verifyLegacyIsolation(helper);
+        else HydrologyDiagnostics.verifyLegacyIsolation(helper);
         helper.succeed();
     }
 
@@ -42,12 +77,14 @@ public final class SanctuaryWorldGameTests {
 
         helper.assertTrue(initialSpawn != null, "Capture the world's initial spawn before the test grid moves it");
         BlockPos spawn = initialSpawn.pos();
-        helper.assertTrue(Math.hypot((double) spawn.getX(), (double) spawn.getZ()) < IslandShape.TERRAIN_LIMIT,
+        var generator = (NoiseBasedChunkGenerator) level.getChunkSource().getGenerator();
+        IslandCapacity capacity = IslandCapacity.forGenerator(generator);
+        int terrainLimit = capacity == null ? IslandShape.TERRAIN_LIMIT : capacity.terrainLimit();
+        helper.assertTrue(Math.hypot((double) spawn.getX(), (double) spawn.getZ()) < terrainLimit,
             "Shared spawn must lie on the finite natural island: " + spawn);
         helper.assertTrue(spawn.getY() > 1 && spawn.getY() < level.getMaxY() - 1,
             "Shared spawn must be inside the dimension height");
-        var settings = level.registryAccess().lookupOrThrow(Registries.NOISE_SETTINGS)
-            .getOrThrow(SanctuarySpawn.RAISED_SETTINGS).value();
+        var settings = generator.generatorSettings().value();
         float spawnFloorDensity = level.getChunkSource().randomState().sampleBlockValueUncached(
             settings.noiseRouter().finalDensity(), spawn.getX(), spawn.getY() - 1, spawn.getZ());
         helper.assertTrue(spawnFloorDensity > 0.0F,
@@ -73,7 +110,9 @@ public final class SanctuaryWorldGameTests {
 
     @GameTest(maxTicks = 200)
     public void sculptOnlyRemovesTerrain(GameTestHelper helper) throws java.io.IOException {
-        DensityDiagnostics.verifyAndExport(helper, initialSpawn);
+        if (IslandCapacity.forGenerator(helper.getLevel().getChunkSource().getGenerator()) != null)
+            PopulationDiagnostics.verifyDensity(helper);
+        else DensityDiagnostics.verifyAndExport(helper, initialSpawn);
         helper.succeed();
     }
 
@@ -101,11 +140,57 @@ public final class SanctuaryWorldGameTests {
 
     @GameTest(maxTicks = 200)
     public void completedLowerMarginIsVoid(GameTestHelper helper) {
+        if (IslandCapacity.forGenerator(helper.getLevel().getChunkSource().getGenerator()) != null) {
+            PopulationDiagnostics.verifyLowerMargin(helper);
+            helper.succeed();
+            return;
+        }
         for (int[] coordinate : new int[][]{{0, 0}, {-8, 0}, {8, 0}, {0, -8}, {0, 8}}) {
             ChunkAccess chunk = helper.getLevel().getChunkSource().getChunk(
                 coordinate[0], coordinate[1], ChunkStatus.FULL, true);
-            helper.assertTrue(chunk != null && chunk.getSection(0).hasOnlyAir(),
-                "The fully generated island must leave Y0..15 empty, without a floor cut at the dimension bound");
+            helper.assertTrue(chunk != null, "The lower-margin test needs a fully generated chunk");
+            if (chunk.getSection(0).hasOnlyAir()) continue;
+            var generator = (NoiseBasedChunkGenerator) helper.getLevel().getChunkSource().getGenerator();
+            helper.assertTrue(NaturalHydrologyRuntime.enabled(generator) || LayeredHydrologyRuntime.enabled(generator)
+                    || WoodlandHydrologyRuntime.enabled(generator) || RiftHydrologyRuntime.enabled(generator) || CavernHydrologyRuntime.enabled(generator),
+                "The legacy island must leave its lower margin entirely empty");
+            for (int x = chunk.getPos().getMinBlockX(); x <= chunk.getPos().getMaxBlockX(); x++) {
+                for (int z = chunk.getPos().getMinBlockZ(); z <= chunk.getPos().getMaxBlockZ(); z++) {
+                    for (int y = 0; y < 16; y++) {
+                        BlockPos p = new BlockPos(x, y, z);
+                        var state = chunk.getBlockState(p);
+                        if (CavernHydrologyRuntime.enabled(generator)) {
+                            boolean water = state.getFluidState().is(FluidTags.WATER)
+                                && CavernDiagnostics.isWithinSpringInspectionFootprint(CavernHydrologyRuntime.cavernPlan(helper.getLevel()), x, z);
+                            final int bx = x, bz = z;
+                            boolean lava = state.getFluidState().is(FluidTags.LAVA)
+                                && CavernHydrologyRuntime.lavaPlan(helper.getLevel()).flowBounds().stream().anyMatch(b ->
+                                    bx >= (Math.floorDiv(b.minX(),16) - 1) * 16 && bx <= (Math.floorDiv(b.maxX(),16) + 2) * 16 - 1
+                                    && bz >= (Math.floorDiv(b.minZ(),16) - 1) * 16 && bz <= (Math.floorDiv(b.maxZ(),16) + 2) * 16 - 1);
+                            helper.assertTrue(state.isAir() || water || lava, "Lower margin must remain void except declared fluid falls: " + p);
+                            continue;
+                        }
+                        if (RiftHydrologyRuntime.enabled(generator)) {
+                            boolean water = state.getFluidState().is(FluidTags.WATER)
+                                && RiftDiagnostics.isWithinSpringInspectionFootprint(RiftHydrologyRuntime.riftPlan(helper.getLevel()), x, z);
+                            final int bx = x, bz = z;
+                            boolean lava = state.getFluidState().is(FluidTags.LAVA)
+                                && RiftHydrologyRuntime.lavaPlan(helper.getLevel()).flowBounds().stream().anyMatch(b ->
+                                    bx >= (Math.floorDiv(b.minX(),16) - 1) * 16 && bx <= (Math.floorDiv(b.maxX(),16) + 2) * 16 - 1
+                                    && bz >= (Math.floorDiv(b.minZ(),16) - 1) * 16 && bz <= (Math.floorDiv(b.maxZ(),16) + 2) * 16 - 1);
+                            helper.assertTrue(state.isAir() || water || lava, "Lower margin must remain void except declared fluid falls: " + p);
+                            continue;
+                        }
+                        helper.assertTrue(state.isAir() || state.getFluidState().is(FluidTags.WATER)
+                                && (WoodlandHydrologyRuntime.enabled(generator)
+                                    ? WoodlandDiagnostics.isWithinSpringInspectionFootprint(WoodlandHydrologyRuntime.woodlandPlan(helper.getLevel()), x, z)
+                                    : LayeredHydrologyRuntime.enabled(generator)
+                                    ? LayeredHydrologyDiagnostics.isWithinSpringInspectionFootprint(LayeredHydrologyRuntime.layeredPlan(helper.getLevel()), x, z)
+                                    : NaturalHydrologyDiagnostics.isWithinSpringInspectionFootprint(NaturalHydrologyRuntime.naturalPlan(helper.getLevel()), x, z)),
+                            "The lower margin has no artificial floor; water must lie in the finite spring inspection footprint, with provenance checked by the full fluid diagnostic: " + p);
+                    }
+                }
+            }
         }
         helper.succeed();
     }
@@ -118,6 +203,11 @@ public final class SanctuaryWorldGameTests {
 
     @GameTest(maxTicks = 200)
     public void completedExteriorChunksAreVoid(GameTestHelper helper) {
+        if (IslandCapacity.forGenerator(helper.getLevel().getChunkSource().getGenerator()) != null) {
+            PopulationDiagnostics.verifyExterior(helper);
+            helper.succeed();
+            return;
+        }
         ServerLevel level = helper.getLevel();
         // First row is just beyond the declared terrain/decorations envelope. The last
         // samples catch the legacy bug where the infinite archipelago returned farther out.
@@ -141,8 +231,7 @@ public final class SanctuaryWorldGameTests {
     public void compiledWorldDensityUsesTheSeed(GameTestHelper helper) {
         ServerLevel level = helper.getLevel();
         var registries = level.registryAccess();
-        NoiseGeneratorSettings settings = registries.lookupOrThrow(Registries.NOISE_SETTINGS)
-            .getOrThrow(SanctuarySpawn.RAISED_SETTINGS).value();
+        NoiseGeneratorSettings settings = ((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator()).generatorSettings().value();
         var noises = registries.lookupOrThrow(Registries.NOISE);
         RandomState first = RandomState.create(noises, 0L, settings);
         RandomState replay = RandomState.create(noises, 0L, settings);

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/UnifiedWorldGameTests.java

@@ -0,0 +1,322 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import com.mojang.serialization.JsonOps;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.*;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.*;
+import net.fabricmc.fabric.api.gametest.v1.GameTest;
+import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.server.level.GenerationChunkHolder;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.util.StaticCache2D;
+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.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ImposterProtoChunk;
+import net.minecraft.world.level.chunk.status.ChunkPyramid;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+import net.minecraft.world.level.levelgen.densityfunction.DensityFunction;
+
+/** Alpha.13 engine checks use the real starter binding and never reconfigure saved worlds. */
+public final class UnifiedWorldGameTests {
+    private static final List<String> CAVES = List.of("minecraft:lush_caves", "minecraft:dripstone_caves", "minecraft:sulfur_caves");
+    private static final Direction[] SIDES = {Direction.NORTH, Direction.SOUTH, Direction.EAST, Direction.WEST};
+
+    @GameTest(maxTicks = 3000)
+    public void retainedHydrologySurvivesNativeDecoration(GameTestHelper helper) throws IOException {
+        PopulationDiagnostics.start(helper);
+    }
+
+    @GameTest(maxTicks = 200)
+    public void sizeAndPublicChoiceSurviveDiskStorage(GameTestHelper helper) throws IOException {
+        UnifiedWorldSettingsDiagnostics.verify(helper);
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 200)
+    public void legacyPipelinesRemainIsolated(GameTestHelper helper) {
+        PopulationDiagnostics.verifyLegacyIsolation(helper);
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 200)
+    public void populationTerrainAndNaturalSpawnRemainPresent(GameTestHelper helper) throws IOException {
+        PopulationDiagnostics.verifyDensity(helper);
+        var level = helper.getLevel();
+        var binding = binding(level);
+        helper.assertTrue(level.getMinY() == 0 && level.getHeight() == 384, "Unification preserves the complete vertical world extent");
+        var spawn = SanctuaryWorldGameTests.initialSpawn;
+        helper.assertTrue(spawn != null, "Capture the original natural spawn before the GameTest fixtures move it");
+        var at = spawn.pos();
+        helper.assertTrue(level.getBlockState(at.below()).isCollisionShapeFullBlock(level, at.below())
+                && level.getBlockState(at).getCollisionShape(level, at).isEmpty()
+                && level.getBlockState(at.above()).getCollisionShape(level, at.above()).isEmpty(),
+            "The unmodified starter spawn must stand on real usable terrain");
+        helper.assertTrue(natural(binding, at.below()) > 0, "The starter spawn never requires an added platform");
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 200)
+    public void exteriorAndLowerMarginRemainVoid(GameTestHelper helper) {
+        PopulationDiagnostics.verifyExterior(helper);
+        PopulationDiagnostics.verifyLowerMargin(helper);
+        helper.succeed();
+    }
+
+    @GameTest(maxTicks = 200)
+    public void nativeCaveFeaturesExistOnNaturalLayers(GameTestHelper helper) throws IOException {
+        ServerLevel level = helper.getLevel();
+        var binding = binding(level);
+        var generator = unified(level);
+        List<Site> sites = caveSites(binding);
+        Map<Long, LevelChunk> chunks = new TreeMap<>();
+        for (Site site : sites) {
+            int cx = site.x() >> 4, cz = site.z() >> 4;
+            for (int dx = -1; dx <= 1; dx++) for (int dz = -1; dz <= 1; dz++) {
+                long key = ChunkPos.pack(cx + dx, cz + dz);
+                if (!chunks.containsKey(key)) chunks.put(key, full(helper, level, cx + dx, cz + dz));
+            }
+        }
+        helper.assertTrue(chunks.size() <= 27, "Native cave inspection is at most three independent 3x3 FULL patches");
+        Map<String, Map<String, Long>> counts = new TreeMap<>();
+        CAVES.forEach(name -> counts.put(name, new TreeMap<>()));
+        Map<String, Long> allBlocks = new TreeMap<>();
+        Map<String, Long> surfaceBiomes = new TreeMap<>();
+        int largestDripstoneColumn = 0;
+        var density = binding.generator().generatorSettings().value().noiseRouter().finalDensity();
+        for (LevelChunk chunk : chunks.values()) {
+            for (var section : chunk.getSections()) section.getStates().count((state, count) -> {
+                if (!state.isAir()) allBlocks.merge(BuiltInRegistries.BLOCK.getKey(state.getBlock()).toString(), (long) count, Long::sum);
+            });
+            for (int dx = 0; dx < 16; dx++) for (int dz = 0; dz < 16; dz++) {
+                int x = chunk.getPos().getMinBlockX() + dx, z = chunk.getPos().getMinBlockZ() + dz;
+                int run = 0;
+                for (int y = 0; y < 256; y++) {
+                    var pos = new BlockPos(x, y, z);
+                    var state = chunk.getBlockState(pos);
+                    String biome = chunk.getNoiseBiome(x >> 2, y >> 2, z >> 2).getRegisteredName();
+                    var bucket = counts.get(biome);
+                    if (bucket != null && !state.isAir()) bucket.merge(BuiltInRegistries.BLOCK.getKey(state.getBlock()).toString(), 1L, Long::sum);
+                    // Large vanilla pillars add thick dripstone into original cave air. A painted
+                    // floor or the old hand-placed support block cannot satisfy this witness.
+                    if (state.is(Blocks.DRIPSTONE_BLOCK) && biome.equals("minecraft:dripstone_caves")
+                            && binding.random().sampleBlockValueUncached(density, x, y, z) <= 0) run++;
+                    else run = 0;
+                    largestDripstoneColumn = Math.max(largestDripstoneColumn, run);
+                }
+                int top = chunk.getHeight(net.minecraft.world.level.levelgen.Heightmap.Types.WORLD_SURFACE, dx, dz);
+                if (top > 190) surfaceBiomes.merge(chunk.getNoiseBiome(x >> 2, top >> 2, z >> 2).getRegisteredName(), 1L, Long::sum);
+            }
+        }
+        var report = report(level);
+        report.put("sites", sites); report.put("inspected_full_chunks", chunks.size());
+        report.put("native_cave_blocks", counts); report.put("all_observed_blocks", allBlocks);
+        report.put("surface_biomes", surfaceBiomes); report.put("largest_natural_air_dripstone_column", largestDripstoneColumn);
+        report.put("rejected_decoration_writes", generator.rejectedDecorationWrites());
+        Map<String, Object> atmospheres = new TreeMap<>();
+        var ops = RegistryOps.create(JsonOps.INSTANCE, level.registryAccess());
+        for (String name : CAVES) {
+            var biome = level.registryAccess().lookupOrThrow(Registries.BIOME)
+                .getValue(net.minecraft.resources.Identifier.parse(name));
+            var encoded = Biome.DIRECT_CODEC.encodeStart(ops, biome).getOrThrow().getAsJsonObject();
+            atmospheres.put(name, encoded.get("attributes"));
+            helper.assertTrue(encoded.get("attributes").toString().contains("music.overworld." + name.substring("minecraft:".length())),
+                "The native cave's music must remain present in its loaded biome attributes: " + name);
+            if (name.equals("minecraft:sulfur_caves")) helper.assertTrue(encoded.get("attributes").toString().contains("minecraft:visual/fog_color")
+                    && encoded.get("attributes").toString().contains("minecraft:sulfur_cube"),
+                "The sulfur cave retains its distinct fog and native creature table");
+        }
+        report.put("native_attributes", atmospheres);
+        report.put("scope", "Up to 27 FULL chunks selected from real cave density; counts are observed blocks, not island-wide resource estimates or client screenshots");
+        boolean passed = false;
+        Set<String> encountered = new TreeSet<>(); sites.forEach(site -> encountered.add(site.biome()));
+        Set<String> verified = new TreeSet<>();
+        try {
+            helper.assertTrue(!sites.isEmpty(), "The demonstration world must provide at least one real native cave site");
+            if (encountered.contains("minecraft:lush_caves")) {
+                helper.assertTrue(count(counts, "minecraft:lush_caves", "minecraft:moss_block") > 0
+                        && count(counts, "minecraft:lush_caves", "minecraft:cave_vines")
+                            + count(counts, "minecraft:lush_caves", "minecraft:cave_vines_plant") > 0,
+                    "Actual native lush caverns must have moss and harvestable hanging vines");
+                verified.add("minecraft:lush_caves");
+            }
+            if (encountered.contains("minecraft:dripstone_caves")) {
+                helper.assertTrue(count(counts, "minecraft:dripstone_caves", "minecraft:pointed_dripstone") > 0 && largestDripstoneColumn >= 5,
+                    "Actual native dripstone caverns must include points and a substantial pillar in natural cave air");
+                verified.add("minecraft:dripstone_caves");
+            }
+            if (encountered.contains("minecraft:sulfur_caves")) {
+                helper.assertTrue(count(counts, "minecraft:sulfur_caves", "minecraft:sulfur") > 0
+                        && count(counts, "minecraft:sulfur_caves", "minecraft:sulfur_spike") > 0,
+                    "Actual native sulfur caverns must include native rock and spikes");
+                verified.add("minecraft:sulfur_caves");
+            }
+            helper.assertTrue(surfaceBiomes.keySet().stream().anyMatch(name -> name.startsWith("sanctuary:population_")),
+                "The starter surface must retain its Population biome family above these lower cave patches");
+            passed = true; helper.succeed();
+        } finally {
+            report.put("encountered_native_types", encountered); report.put("verified_native_types", verified);
+            report.put("unverified_native_types", CAVES.stream().filter(name -> !verified.contains(name)).toList());
+            report.put("all_three_types_demonstrated_here", verified.containsAll(CAVES));
+            report.put("validation_contract", "Every encountered type must pass its full block evidence; the release also requires cumulative evidence for all three types across its fresh demonstration worlds");
+            report.put("passed", passed); write(level, "native-caves", report);
+        }
+    }
+
+    @GameTest(maxTicks = 200)
+    public void decorationGuardRejectsChangesToHydrology(GameTestHelper helper) throws IOException {
+        var level = helper.getLevel(); var binding = binding(level); var generator = unified(level);
+        var plan = PopulationHydrologyRuntime.regionPlan(binding.generator(), binding.random(), new IslandCapacity.Region(0, 0)).water();
+        LinkedHashSet<BlockPos> witnesses = new LinkedHashSet<>();
+        int shells = 0;
+        for (var cell : plan.cells()) {
+            if (!cell.hasWater()) continue;
+            witnesses.add(new BlockPos(cell.x(), cell.waterY(), cell.z()));
+            witnesses.add(new BlockPos(cell.x(), cell.bedY() - cell.sedimentDepth() - 1, cell.z()));
+            for (Direction side : SIDES) {
+                var wall = new BlockPos(cell.x(), cell.waterY(), cell.z()).relative(side);
+                var next = plan.cellAt(wall.getX(), wall.getY(), wall.getZ());
+                if ((next == null || !next.hasWater()) && natural(binding, wall) > 0) { witnesses.add(wall); shells++; }
+            }
+            if (shells >= 2 && witnesses.size() >= 12) break;
+        }
+        int boundaryWitnesses = 0;
+        for (var cell : plan.cells()) {
+            if (!cell.hasWater()) continue;
+            for (Direction side : SIDES) {
+                var water = new BlockPos(cell.x(), cell.waterY(), cell.z());
+                var wall = water.relative(side);
+                var next = plan.cellAt(wall.getX(), wall.getY(), wall.getZ());
+                if (ChunkPos.pack(water) != ChunkPos.pack(wall) && (next == null || !next.hasWater()) && natural(binding, wall) > 0) {
+                    witnesses.add(wall); boundaryWitnesses++;
+                }
+            }
+            if (boundaryWitnesses >= 4) break;
+        }
+        for (var spring : plan.springs()) { witnesses.add(position(spring.source())); witnesses.add(position(spring.outlet())); }
+        for (var spill : plan.spills()) { witnesses.add(position(spill.source())); witnesses.add(position(spill.outlet())); }
+        helper.assertTrue(!witnesses.isEmpty() && shells > 0, "Inspect real source, bed and natural wall witnesses");
+        Map<Long, SanctuaryDecorationProtection> masks = new HashMap<>();
+        int compared = 0;
+        for (var witness : witnesses) {
+            var mask = masks.computeIfAbsent(ChunkPos.pack(witness), ignored -> SanctuaryDecorationProtection.create(binding, witness.getX() >> 4, witness.getZ() >> 4));
+            helper.assertTrue(mask.protects(witness) && generator.protectsDecoration(witness), "The published decoration mask protects the complete water geometry: " + witness);
+            helper.assertTrue(PopulationHydrologyRuntime.protects(binding.generator(), binding.random(), witness, 1, 1, 1),
+                "The mask must agree with the hydrology protection oracle including one-block clearance at natural walls");
+            compared++;
+        }
+        var witness = witnesses.getFirst();
+        LevelChunk chunk = full(helper, level, witness.getX() >> 4, witness.getZ() >> 4);
+        // FULL holders deliberately expose a read-only ImposterProtoChunk to generation.
+        // Use a test-local writable view; leave the world's real holder and saved status alone.
+        var writable = new ImposterProtoChunk(chunk, true);
+        GenerationChunkHolder testHolder = new GenerationChunkHolder(chunk.getPos()) {
+            @Override protected void addSaveDependency(java.util.concurrent.CompletableFuture<?> dependency) {}
+            @Override public int getTicketLevel() { return 0; }
+            @Override public int getQueueLevel() { return 0; }
+            @Override public ChunkAccess getChunkIfPresentUnchecked(ChunkStatus status) { return writable; }
+        };
+        var holders = StaticCache2D.<GenerationChunkHolder>create(chunk.getPos().x(), chunk.getPos().z(), 0,
+            (x, z) -> testHolder);
+        var worldgen = new WorldGenRegion(level, holders, ChunkPyramid.GENERATION_PYRAMID.getStepTo(ChunkStatus.FEATURES), chunk);
+        var before = chunk.getBlockState(witness);
+        long rejected = generator.rejectedDecorationWrites();
+        try {
+            helper.assertFalse(worldgen.setBlock(witness, Blocks.DIAMOND_BLOCK.defaultBlockState(), 2, 0),
+                "A real WorldGenRegion write must be denied on protected retained water");
+            helper.assertTrue(chunk.getBlockState(witness).equals(before) && generator.rejectedDecorationWrites() == rejected + 1,
+                "The native write path must preserve the original block and record the rejection");
+        } finally { if (!chunk.getBlockState(witness).equals(before)) chunk.setBlockState(witness, before, 0); }
+        BlockPos free = new BlockPos(chunk.getPos().getMinBlockX() + 8, 383, chunk.getPos().getMinBlockZ() + 8);
+        var freeBefore = chunk.getBlockState(free);
+        helper.assertFalse(generator.protectsDecoration(free), "A distant air witness must be outside the hydrology mask");
+        try {
+            helper.assertTrue(worldgen.setBlock(free, Blocks.DIAMOND_BLOCK.defaultBlockState(), 2, 0)
+                    && chunk.getBlockState(free).is(Blocks.DIAMOND_BLOCK),
+                "Decoration outside protected volumes must remain writable");
+        } finally { chunk.setBlockState(free, freeBefore, 0); }
+        write(level, "decoration-guard", Map.of("generation", 13, "seed", level.getSeed(),
+            "diameter", generator.initialDiameter(), "compared_plan_points", compared,
+            "natural_wall_witnesses", shells, "walls_owned_by_adjacent_chunk", boundaryWitnesses, "actual_write_rejected", true, "unprotected_write_allowed", true, "passed", true));
+        helper.succeed();
+    }
+
+    private record Site(String biome, int x, int floorY, int roofY, int z, int score) {}
+
+    private static List<Site> caveSites(PopulationGenerationContext.Binding binding) {
+        var capacity = IslandCapacity.forGenerator(binding.generator());
+        var resolver = binding.generator().getBiomeSource().createUncachedResolver(binding.random());
+        var density = binding.generator().generatorSettings().value().noiseRouter().finalDensity();
+        Map<String, List<Site>> candidates = new TreeMap<>(); CAVES.forEach(name -> candidates.put(name, new ArrayList<>()));
+        int radius = (capacity.terrainLimit() + 15) / 16;
+        for (int cx = -radius; cx <= radius; cx++) for (int cz = -radius; cz <= radius; cz++) {
+            int x = cx * 16 + 8, z = cz * 16 + 8;
+            if (Math.hypot(x, z) >= capacity.radius() - 24) continue;
+            for (int y = 164; y >= 40; y--) {
+                String biome = resolver.getNoiseBiome(x >> 2, (y + 1) >> 2, z >> 2).getRegisteredName();
+                var bucket = candidates.get(biome); if (bucket == null) continue;
+                if (sample(binding, density, x, y, z) <= 0 || sample(binding, density, x, y + 1, z) > 0
+                        || sample(binding, density, x, y + 2, z) > 0 || sample(binding, density, x, y - 1, z) <= 0) continue;
+                int roof = y + 3;
+                while (roof < Math.min(256, y + 96) && sample(binding, density, x, roof, z) <= 0) roof++;
+                if (roof >= Math.min(256, y + 96) || roof - y < 10 || sample(binding, density, x, roof + 1, z) <= 0) continue;
+                int score = Math.min(48, roof - y);
+                for (int dx : new int[]{-4, 0, 4}) for (int dz : new int[]{-4, 0, 4})
+                    if (sample(binding, density, x + dx, y, z + dz) > 0 && sample(binding, density, x + dx, roof, z + dz) > 0) score += 8;
+                bucket.add(new Site(biome, x, y, roof, z, score));
+                break;
+            }
+        }
+        List<Site> sites = new ArrayList<>();
+        for (String cave : CAVES) {
+            var ordered = candidates.get(cave).stream().sorted(Comparator.comparingInt(Site::score).reversed()
+                .thenComparingDouble(s -> Math.hypot(s.x(), s.z())).thenComparingInt(Site::x).thenComparingInt(Site::z)).toList();
+            for (Site candidate : ordered.stream().limit(32).toList()) {
+                var base = new BlockPos(candidate.x(), candidate.floorY() + 1, candidate.z());
+                if (!PopulationHydrologyRuntime.protects(binding.generator(), binding.random(), base, 8,
+                        candidate.roofY() - candidate.floorY(), 3)) { sites.add(candidate); break; }
+            }
+        }
+        return List.copyOf(sites);
+    }
+
+    private static float sample(PopulationGenerationContext.Binding binding, DensityFunction density, int x, int y, int z) {
+        return binding.random().sampleBlockValueUncached(density, x, y, z);
+    }
+    private static float natural(PopulationGenerationContext.Binding binding, BlockPos pos) {
+        return sample(binding, binding.generator().generatorSettings().value().noiseRouter().finalDensity(), pos.getX(), pos.getY(), pos.getZ());
+    }
+    private static long count(Map<String, Map<String, Long>> counts, String biome, String block) { return counts.get(biome).getOrDefault(block, 0L); }
+    private static BlockPos position(PopulationHydrology.Position p) { return new BlockPos(p.x(), p.y(), p.z()); }
+    private static PopulationGenerationContext.Binding binding(ServerLevel level) { return Objects.requireNonNull(PopulationGenerationContext.of(level)); }
+    private static SanctuaryChunkGenerator unified(ServerLevel level) { return (SanctuaryChunkGenerator) level.getChunkSource().getGenerator(); }
+    private static LevelChunk full(GameTestHelper helper, ServerLevel level, int x, int z) {
+        var chunk = level.getChunkSource().getChunk(x, z, ChunkStatus.FULL, true);
+        helper.assertTrue(chunk instanceof LevelChunk, "Inspect only real fully generated chunks"); return (LevelChunk) chunk;
+    }
+    private static Map<String, Object> report(ServerLevel level) {
+        var report = new LinkedHashMap<String, Object>();
+        report.put("generation", 13); report.put("seed", level.getSeed()); report.put("diameter", unified(level).initialDiameter());
+        report.put("mod_version", FabricLoader.getInstance().getModContainer("sanctuary").orElseThrow().getMetadata().getVersion().getFriendlyString());
+        return report;
+    }
+    private static void write(ServerLevel level, String kind, Object report) throws IOException {
+        Path target = Path.of("diagnostics", "unified-" + unified(level).initialDiameter() + "-seed-" + level.getSeed() + "-" + kind + ".json");
+        Files.createDirectories(target.getParent());
+        Files.writeString(target, new GsonBuilder().setPrettyPrinting().create().toJson(report) + "\n");
+        SanctuaryMod.LOGGER.info("Unified {} seed {} wrote {}", unified(level).initialDiameter(), level.getSeed(), target);
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/UnifiedWorldSettingsDiagnostics.java

@@ -0,0 +1,87 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonPrimitive;
+import com.mojang.serialization.JsonOps;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.resources.RegistryOps;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.tags.WorldPresetTags;
+import net.minecraft.world.level.dimension.LevelStem;
+import net.minecraft.world.level.levelgen.WorldGenSettings;
+import net.minecraft.world.level.levelgen.WorldOptions;
+import net.minecraft.world.level.storage.LevelStorageSource;
+
+/** Storage contract shared by the public preset and its three client-selected sizes. */
+final class UnifiedWorldSettingsDiagnostics {
+    static void verify(GameTestHelper helper) throws IOException {
+        var access = helper.getLevel().registryAccess();
+        var presets = access.lookupOrThrow(Registries.WORLD_PRESET);
+        var publicPreset = presets.getOrThrow(ResourceKey.create(Registries.WORLD_PRESET,
+                SanctuaryMod.id("sanctuary"))).value();
+        var standard = publicPreset.createWorldDimensions();
+        helper.assertTrue(standard.overworld() instanceof SanctuaryChunkGenerator,
+                "The sole Sanctuary world type must use the unified generator");
+        var generator = (SanctuaryChunkGenerator) standard.overworld();
+        helper.assertTrue(generator.initialDiameter() == 724, "The public preset defaults to Medium / 724 blocks");
+        for (var tag : List.of(WorldPresetTags.NORMAL, WorldPresetTags.EXTENDED)) {
+            var visible = presets.getOrThrow(tag).stream().map(holder -> holder.getRegisteredName())
+                    .filter(name -> name.startsWith("sanctuary:")).collect(Collectors.toSet());
+            helper.assertTrue(visible.equals(Set.of("sanctuary:sanctuary")),
+                    "Only one Sanctuary choice is present in the normal and extended world-type lists");
+        }
+
+        var ops = RegistryOps.create(JsonOps.INSTANCE, access);
+        var serialized = SanctuaryChunkGenerator.CODEC.codec().encodeStart(ops, generator).getOrThrow().getAsJsonObject();
+        serialized.remove("initial_diameter");
+        helper.assertTrue(SanctuaryChunkGenerator.CODEC.codec().parse(ops, serialized).getOrThrow().initialDiameter() == 724,
+                "An omitted new-generation size defaults to Medium");
+        for (int rejected : new int[]{0, 511, 513, 723, 725, 768, 1023, 1025, 2048}) {
+            helper.assertTrue(SanctuaryChunkGenerator.DIAMETER_CODEC.parse(JsonOps.INSTANCE, new JsonPrimitive(rejected)).error().isPresent(),
+                    "Only the three supported initial diameters are accepted");
+        }
+
+        Path directory = Path.of("diagnostics", "unified-world-settings-seed-" + helper.getLevel().getSeed()).toAbsolutePath();
+        Files.createDirectories(directory);
+        var storage = LevelStorageSource.createDefault(directory);
+        List<Map<String, Object>> results = new ArrayList<>();
+        for (int diameter : new int[]{512, 724, 1024}) {
+            var chosen = generator.withInitialDiameter(diameter);
+            helper.assertTrue(generator.initialDiameter() == 724 && chosen.source() != generator.source(),
+                    "Customizing a new world must copy the generator and its mutable biome source");
+            var dimensions = standard.replaceOverworldGenerator(access, chosen);
+            for (var dimension : List.of(LevelStem.NETHER, LevelStem.END)) {
+                helper.assertTrue(dimensions.get(dimension).equals(standard.get(dimension)),
+                        "Customizing the island preserves the other dimensions");
+            }
+            var original = new WorldGenSettings(new WorldOptions(helper.getLevel().getSeed(), false, true), dimensions);
+            String name = "diameter-" + diameter;
+            try (var save = storage.createAccess(name)) {
+                LevelStorageSource.writeWorldGenSettings(access, storage.getLevelPath(name), original);
+                var restored = LevelStorageSource.readExistingSavedData(save, access, WorldGenSettings.TYPE).getOrThrow();
+                helper.assertTrue(restored.dimensions().overworld() instanceof SanctuaryChunkGenerator reloaded
+                                && reloaded.initialDiameter() == diameter,
+                        "The selected diameter must survive real world-settings storage");
+                helper.assertTrue(WorldGenSettings.CODEC.encodeStart(ops, restored).getOrThrow()
+                                .equals(WorldGenSettings.CODEC.encodeStart(ops, original).getOrThrow()),
+                        "Seed, generation options and all dimensions survive the disk round trip");
+                results.add(Map.of("diameter", diameter, "disk_round_trip", true));
+            }
+        }
+        Files.writeString(directory.resolve("round-trip.json"), new GsonBuilder().setPrettyPrinting().create().toJson(Map.of(
+                "seed", helper.getLevel().getSeed(), "default_diameter", 724,
+                "public_presets", List.of("sanctuary:sanctuary"), "sizes", results,
+                "invalid_diameters_rejected", true, "copied_biome_source", true, "passed", true)) + "\n");
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/WorldgenPerformanceGameTests.java

@@ -0,0 +1,114 @@
+package fr.koka.sanctuary.gametest;
+
+import com.google.gson.GsonBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import fr.koka.sanctuary.worldgen.IslandCapacity;
+import fr.koka.sanctuary.worldgen.PopulationHydrologyRuntime;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import net.fabricmc.fabric.api.gametest.v1.GameTest;
+import net.fabricmc.loader.api.FabricLoader;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.status.ChunkStatus;
+
+/** Opt-in, repeatable server generation workload; it does not measure client rendering or FPS. */
+public final class WorldgenPerformanceGameTests {
+    @GameTest(maxTicks = 3000)
+    public void spawnAreaAndExploration(GameTestHelper helper) throws Exception {
+        ServerLevel level = helper.getLevel();
+        var binding = fr.koka.sanctuary.worldgen.PopulationGenerationContext.of(level);
+        var capacity = IslandCapacity.forGenerator(binding.generator());
+        var spawn = SanctuaryWorldGameTests.initialSpawn.pos();
+        int cx = spawn.getX() >> 4, cz = spawn.getZ() >> 4;
+        var report = new LinkedHashMap<String, Object>();
+        report.put("version", FabricLoader.getInstance().getModContainer("sanctuary").orElseThrow()
+            .getMetadata().getVersion().getFriendlyString());
+        report.put("players", capacity.players()); report.put("seed", level.getSeed());
+        var host = level.getChunkSource().getGenerator();
+        String profile = "players-" + capacity.players();
+        if (host instanceof fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator unified) {
+            report.put("generation", 13); report.put("initial_diameter", unified.initialDiameter());
+            profile = "unified-" + unified.initialDiameter();
+        }
+        report.put("spawn", List.of(spawn.getX(), spawn.getY(), spawn.getZ()));
+        report.put("java", System.getProperty("java.version"));
+        report.put("processors", Runtime.getRuntime().availableProcessors());
+        report.put("max_heap_bytes", Runtime.getRuntime().maxMemory());
+        List<Map<String, Object>> rings = new ArrayList<>();
+        List<Long> chunkTimes = new ArrayList<>();
+        int count = 0, land = 0;
+        long areaStart = System.nanoTime();
+        // Centre outwards, 17x17 FULL chunks: a fixed eight-chunk radius around natural spawn.
+        for (int radius = 0; radius <= 8; radius++) {
+            long start = System.nanoTime();
+            for (int x = -radius; x <= radius; x++) for (int z = -radius; z <= radius; z++) {
+                if (Math.max(Math.abs(x), Math.abs(z)) != radius) continue;
+                long before = System.nanoTime();
+                var chunk = full(helper, level, cx + x, cz + z);
+                chunkTimes.add(System.nanoTime() - before);
+                count++;
+                if (java.util.Arrays.stream(chunk.getSections()).anyMatch(s -> !s.hasOnlyAir())) land++;
+            }
+            long elapsed = System.nanoTime() - start;
+            rings.add(Map.of("radius", radius, "elapsed_ms", millis(elapsed), "cumulative_chunks", count));
+            SanctuaryMod.LOGGER.info("Generation benchmark {} seed {} ring {}: {} FULL chunks, {} ms",
+                capacity.players(), level.getSeed(), radius, count, millis(elapsed));
+        }
+        report.put("spawn_area_ms", millis(System.nanoTime() - areaStart));
+        report.put("spawn_area_full_chunks", count); report.put("spawn_area_nonempty_chunks", land);
+        report.put("rings", rings); report.put("spawn_area_chunk_latency_ms", latency(chunkTimes));
+
+        // Continue east through a regional boundary, with a five-chunk-wide corridor.
+        // This exposes stalls during exploration instead of timing only the initial region.
+        List<Map<String, Object>> steps = new ArrayList<>();
+        chunkTimes.clear();
+        long exploreStart = System.nanoTime();
+        for (int x = 9; x <= 24; x++) {
+            long start = System.nanoTime();
+            for (int z = -2; z <= 2; z++) {
+                long before = System.nanoTime();
+                full(helper, level, cx + x, cz + z);
+                chunkTimes.add(System.nanoTime() - before);
+            }
+            long elapsed = System.nanoTime() - start;
+            steps.add(Map.of("chunk_x", cx + x, "elapsed_ms", millis(elapsed)));
+            SanctuaryMod.LOGGER.info("Generation benchmark {} seed {} exploration column {}: {} ms",
+                capacity.players(), level.getSeed(), cx + x, millis(elapsed));
+        }
+        report.put("exploration_ms", millis(System.nanoTime() - exploreStart));
+        report.put("exploration_full_chunks", 80); report.put("exploration_steps", steps);
+        report.put("exploration_chunk_latency_ms", latency(chunkTimes));
+        report.put("regions_cached", PopulationHydrologyRuntime.cachedRegionCount(binding.random()));
+        report.put("scope", "Fresh development world; 289 FULL chunks around natural spawn, then 80 eastward FULL chunks. "
+            + "Synchronous server requests include dependent generation up to FULL, not guaranteed ticking readiness, client GPU, network, FPS or player load. "
+            + "World creation before the test is timed separately by Minecraft's startup log.");
+        helper.assertTrue(count == 289 && land > 100, "The benchmark must generate actual playable terrain");
+        report.put("passed", true);
+        Path output = Path.of("diagnostics", "generation-performance-" + profile + "-seed-" + level.getSeed() + ".json");
+        Files.createDirectories(output.getParent());
+        Files.writeString(output, new GsonBuilder().setPrettyPrinting().create().toJson(report) + "\n");
+        helper.succeed();
+    }
+
+    private static LevelChunk full(GameTestHelper helper, ServerLevel level, int x, int z) {
+        var chunk = level.getChunkSource().getChunk(x, z, ChunkStatus.FULL, true);
+        helper.assertTrue(chunk instanceof LevelChunk, "Benchmark requires completed chunk " + new ChunkPos(x, z));
+        return (LevelChunk) chunk;
+    }
+
+    private static double millis(long nanos) { return nanos / 1_000_000.0; }
+
+    private static Map<String, Double> latency(List<Long> times) {
+        var sorted = times.stream().sorted().toList();
+        return Map.of("median", millis(sorted.get(sorted.size() / 2)),
+            "p95", millis(sorted.get((int) Math.ceil(sorted.size() * .95) - 1)),
+            "max", millis(sorted.getLast()));
+    }
+}

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/mixin/SanctuaryGameTestServerMixin.java

@@ -17,6 +17,18 @@ import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
 /** Test-only: run the real Sanctuary datapack instead of the framework's flat fixture. */
 @Mixin(GameTestServer.class)
 public abstract class SanctuaryGameTestServerMixin {
+    // The framework otherwise runs thousands of empty ticks per second, exhausting an async
+    // generation test's deadline before its IO/workers can complete. This is test-only pacing.
+    @Inject(method = "waitUntilNextTick", at = @At("RETURN"))
+    private void sanctuary$paceExpansionWorkers(CallbackInfo ci) {
+        if (Boolean.getBoolean("sanctuary.test.expansion")) {
+            long until = System.nanoTime() + 20_000_000L;
+            long remaining;
+            // Worker completion unparks the server; keep the pacing deadline despite those signals.
+            while ((remaining = until - System.nanoTime()) > 0) java.util.concurrent.locks.LockSupport.parkNanos(remaining);
+        }
+    }
+
     @ModifyArg(method = "<clinit>", at = @At(value = "INVOKE", target =
         "Lnet/minecraft/world/level/levelgen/WorldOptions;<init>(JZZ)V"), index = 0)
     private static long sanctuary$testSeed(long original) {
@@ -32,12 +44,39 @@ public abstract class SanctuaryGameTestServerMixin {
     @Redirect(method = "lambda$create$1", at = @At(value = "FIELD", target =
         "Lnet/minecraft/world/level/levelgen/presets/WorldPresets;FLAT_ALL_DIMENSIONS:Lnet/minecraft/resources/ResourceKey;"))
     private static ResourceKey<WorldPreset> sanctuary$selectActualPreset() {
-        return ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id("sanctuary"));
+        if (Boolean.getBoolean("sanctuary.test.unified")) return ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id("sanctuary"));
+        if (Boolean.getBoolean("sanctuary.test.expansion")) return ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id("expansion_lab"));
+        int players = Integer.getInteger("sanctuary.test.players", 10);
+        String preset = switch (players) {
+            case 5 -> "sanctuary_5";
+            case 10 -> "sanctuary_10";
+            case 20 -> "sanctuary_20";
+            case 100 -> "sanctuary_100";
+            default -> throw new IllegalArgumentException("Test geometry must be 5, 10, 20 or 100");
+        };
+        return ResourceKey.create(Registries.WORLD_PRESET, SanctuaryMod.id(preset));
+    }
+
+    @Redirect(method = "lambda$create$1", at = @At(value = "INVOKE", target =
+        "Lnet/minecraft/world/level/levelgen/presets/WorldPreset;createWorldDimensions()Lnet/minecraft/world/level/levelgen/WorldDimensions;"))
+    private static net.minecraft.world.level.levelgen.WorldDimensions sanctuary$customizeSize(WorldPreset preset,
+            net.minecraft.world.level.LevelSettings settings, net.minecraft.server.WorldLoader.DataLoadContext context) {
+        var dimensions = preset.createWorldDimensions();
+        if (Boolean.getBoolean("sanctuary.test.unified")) {
+            var generator = (fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator) dimensions.overworld();
+            return dimensions.replaceOverworldGenerator(context.datapackWorldRegistries(),
+                generator.withInitialDiameter(Integer.getInteger("sanctuary.test.diameter", 724)));
+        }
+        return dimensions;
     }
 
     @Inject(method = "startTests", at = @At("HEAD"))
     private void sanctuary$captureInitialSpawn(ServerLevel level, CallbackInfo ci) {
         // The framework moves its own spawn to a random test grid after this point.
         SanctuaryWorldGameTests.initialSpawn = level.getRespawnData();
+        if (Boolean.getBoolean("sanctuary.test.expansion")) return;
+        var binding = fr.koka.sanctuary.worldgen.PopulationGenerationContext.of(level);
+        fr.koka.sanctuary.gametest.PopulationDiagnostics.regionsAtInitialSpawn = binding == null ? 0 :
+            fr.koka.sanctuary.worldgen.PopulationHydrologyRuntime.cachedRegionCount(binding.random());
     }
 }

mods/sanctuary/src/gametest/java/fr/koka/sanctuary/worldgen/ExactInterpolationChecks.java

@@ -0,0 +1,186 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.concurrent.Callable;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicInteger;
+import net.minecraft.core.Holder;
+import net.minecraft.resources.Identifier;
+import net.minecraft.util.Interval;
+import net.minecraft.util.RandomSource;
+import net.minecraft.util.context.ContextKey;
+import net.minecraft.util.context.ContextMap;
+import net.minecraft.world.level.levelgen.densityfunction.*;
+import net.minecraft.world.level.levelgen.densityfunction.op.InterpolatedFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.UnaryFunction;
+import net.minecraft.world.level.levelgen.synth.Noise;
+import net.minecraft.world.level.levelgen.synth.NormalNoise;
+
+/** Adversarial checks against the actual vanilla scalar implementation, requiring no chunks. */
+public final class ExactInterpolationChecks {
+    private static final ContextKey<Float> SHIFT = ContextKey.vanilla("sanctuary_test_interpolation_shift");
+    private static final ContextKey<float[]> MUTABLE = ContextKey.vanilla("sanctuary_test_mutable_interpolation_shift");
+    private static final float[] NO_MUTATION = {0};
+    private static final DensityFunction.CompileContext COMPILE = new DensityFunction.CompileContext() {
+        @Override public Noise createNoiseSampler(Holder<NormalNoise> noise) { throw new AssertionError("No noise needed"); }
+        @Override public RandomSource createRandom(Identifier id) { throw new AssertionError("No random needed"); }
+        @Override public RandomSource createEndIslandRandom() { throw new AssertionError("No End needed"); }
+    };
+
+    private ExactInterpolationChecks() {}
+
+    public static Map<String, Object> verify() throws Exception {
+        long checked = 0;
+        for (int[] sizes : new int[][]{{8, 4}, {3, 5}, {1, 1}}) {
+            var input = new Probe(31);
+            DensityFunction expression = expression(input, sizes[0], sizes[1]);
+            var reference = expression.compileSampler(COMPILE);
+            var cached = cached(input, sizes[0], sizes[1]);
+            SamplerContext first = context(0), second = context(0.0625f);
+            var points = new ArrayList<int[]>();
+            for (int x = -13; x <= 13; x++) for (int y = -7; y <= 11; y++) for (int z = -9; z <= 9; z++)
+                points.add(new int[]{x, y, z});
+            Collections.shuffle(points, new Random(73));
+            for (var context : List.of(first, second, first)) for (var p : points) {
+                same(reference.sampleValue(context, p[0], p[1], p[2]), cached.sampleValue(context, p[0], p[1], p[2]), "scalar/context");
+                checked++;
+            }
+            var volume = new DensityVolume(13, 17, 11, -19, -9, -17, 3, 2, 5);
+            DensityBuffer actual = DensityBuffer.createUnpooled(volume.size());
+            cached.sampleVolume(first, actual, volume);
+            for (int z = 0; z < volume.sizeZ(); z++) for (int x = 0; x < volume.sizeX(); x++) for (int y = 0; y < volume.sizeY(); y++) {
+                same(reference.sampleValue(first, volume.blockX(x), volume.blockY(y), volume.blockZ(z)),
+                    actual.get(volume.indexUnchecked(x, y, z)), "non-unit volume");
+                checked++;
+            }
+        }
+
+        // A scalar and a bulk input intentionally differ in Probe. This catches accidental
+        // replacement of the aligned scalar branch with one of the cached lattice corners.
+        var counted = new Probe(91);
+        var cached = cached(counted, 8, 4);
+        var stable = context(0);
+        for (int repeat = 0; repeat < 2; repeat++)
+            for (int x = 1; x < 8; x++) for (int y = 1; y < 4; y++) for (int z = 1; z < 8; z++) cached.sampleValue(stable, x, y, z);
+        require(counted.volumeCalls.get() == 1, "A reused cell must sample its eight corners only once");
+        int alignedBefore = counted.scalarCalls.get();
+        cached.sampleValue(stable, 0, 0, 0);
+        require(counted.scalarCalls.get() == alignedBefore + 1, "Aligned nodes retain their separate scalar input path");
+
+        var reference = expression(counted, 8, 4).compileSampler(COMPILE);
+        // More distinct cells than the bounded cache holds; collisions and replacement must
+        // remain invisible to both forward and reverse traversals.
+        for (int direction : new int[]{1, -1}) for (int index = 0; index < 9000; index++) {
+            int i = direction > 0 ? index : 8999 - index;
+            int x = (i % 113 - 56) * 8 + 1, y = ((i / 113) % 97 - 48) * 4 + 1, z = (i % 67 - 33) * 8 + 3;
+            same(reference.sampleValue(stable, x, y, z), cached.sampleValue(stable, x, y, z), "cache replacement");
+            checked++;
+        }
+        var other = cached(new Probe(999), 8, 4);
+        var otherReference = expression(new Probe(999), 8, 4).compileSampler(COMPILE);
+        for (int i = 0; i < 128; i++) {
+            same(reference.sampleValue(stable, i - 67, 21, -3), cached.sampleValue(stable, i - 67, 21, -3), "sampler identity A");
+            same(otherReference.sampleValue(stable, i - 67, 21, -3), other.sampleValue(stable, i - 67, 21, -3), "sampler identity B");
+            checked += 2;
+        }
+        try (var executor = Executors.newFixedThreadPool(3)) {
+            List<Callable<Integer>> tasks = new ArrayList<>();
+            for (int worker = 0; worker < 3; worker++) {
+                final int id = worker;
+                tasks.add(() -> {
+                    var local = context(id * 0.03125f);
+                    for (int i = 0; i < 3000; i++) {
+                        int x = (i * 17 + id) % 251 - 125, y = i % 384, z = (i * 37 - id) % 257 - 128;
+                        same(reference.sampleValue(local, x, y, z), cached.sampleValue(local, x, y, z), "concurrent shared sampler");
+                    }
+                    return 3000;
+                });
+            }
+            for (var result : executor.invokeAll(tasks)) checked += result.get();
+        }
+        var plain = new ProbeFunction(new Probe(42));
+        require(ExactInterpolationSampler.compileTerrain(plain, COMPILE) == plain.probe,
+            "Unrecognized expressions must preserve their original sampler");
+        require(!ExactInterpolationSampler.supportsTerrain(expression(new Probe(42), 8, 4)),
+            "An opaque/contextual input must not be cached merely because its outer expression matches");
+        float[] payload = {0};
+        var mutable = SamplerContext.builder().setUserFields(ContextMap.builder().set(MUTABLE, payload).build()).build();
+        var fallback = ExactInterpolationSampler.compileTerrain(expression(new Probe(42), 8, 4), COMPILE);
+        float before = fallback.sampleValue(mutable, 1, 2, 3);
+        payload[0] = 0.125f;
+        float after = fallback.sampleValue(mutable, 1, 2, 3);
+        require(Float.floatToRawIntBits(before) != Float.floatToRawIntBits(after),
+            "The fallback must observe mutable context payloads even when context identity stays the same");
+
+        var nestedInput = new Probe(817);
+        var nested = cached(nestedInput, 8, 4);
+        var nestedReference = expression(new Probe(817), 8, 4).compileSampler(COMPILE);
+        var outerInput = new Probe(83);
+        outerInput.nested = nested;
+        var outer = cached(outerInput, 8, 4);
+        var outerReference = expression(outerInput, 8, 4).compileSampler(COMPILE);
+        for (int i = 0; i < 128; i++) {
+            int x = i - 65;
+            same(outerReference.sampleValue(stable, x, 23, -7), outer.sampleValue(stable, x, 23, -7), "nested outer request");
+            same(nestedReference.sampleValue(stable, x, 23, -7), nested.sampleValue(stable, x, 23, -7), "nested cache identity");
+            checked += 2;
+        }
+        return Map.of("bitwise_comparisons", checked, "repeated_cell_corner_batches", 1,
+            "concurrent_workers", 3, "aligned_scalar_path_preserved", true, "passed", true);
+    }
+
+    private static DensityFunction expression(Probe probe, int xz, int y) {
+        return new UnaryFunction(UnaryFunction.Type.SQUEEZE, new InterpolatedFunction(new ProbeFunction(probe), xz, y));
+    }
+
+    private static DensitySampler cached(Probe probe, int xz, int y) {
+        return new UnaryFunction.SqueezeSampler(new ExactInterpolationSampler(probe, xz, y));
+    }
+
+    private static SamplerContext context(float shift) {
+        return SamplerContext.builder().setUserFields(ContextMap.builder().set(SHIFT, shift).build()).build();
+    }
+
+    private record ProbeFunction(Probe probe) implements DensityFunction {
+        @Override public DensitySampler compileSampler(CompileContext context) { return probe; }
+        @Override public DensityFunction rewriteChildren(DfRewriteRule rule) { return this; }
+        @Override public Interval range() { return Interval.of(-2, 2); }
+        @Override public int domainAxes() { return ALL_AXES; }
+        @Override public MapCodec<ProbeFunction> codec() { return MapCodec.unit(this); }
+    }
+
+    private static final class Probe implements DensitySampler {
+        final int seed;
+        final AtomicInteger scalarCalls = new AtomicInteger(), volumeCalls = new AtomicInteger();
+        DensitySampler nested;
+        Probe(int seed) { this.seed = seed; }
+        private float value(SamplerContext context, int x, int y, int z) {
+            int hash = (x * 73428767 ^ y * 912931 ^ z * 4382893 ^ seed);
+            hash ^= hash >>> 15;
+            float[] mutable = context.getFieldOrDefault(MUTABLE, NO_MUTATION);
+            return Float.intBitsToFloat(0x3e000000 | (hash & 0x007fffff)) - 0.19f
+                + context.getFieldOrDefault(SHIFT, 0f) + mutable[0];
+        }
+        @Override public float sampleValue(SamplerContext context, int x, int y, int z) {
+            scalarCalls.incrementAndGet();
+            return value(context, x, y, z) + 0.03125f;
+        }
+        @Override public void sampleVolume(SamplerContext context, DensityBuffer buffer, DensityVolume volume) {
+            volumeCalls.incrementAndGet();
+            if (nested != null) nested.sampleValue(context, volume.minBlockX() + 1, volume.minBlockY() + 1, volume.minBlockZ() + 1);
+            for (int z = 0; z < volume.sizeZ(); z++) for (int x = 0; x < volume.sizeX(); x++) for (int y = 0; y < volume.sizeY(); y++)
+                buffer.set(volume.indexUnchecked(x, y, z), value(context, volume.blockX(x), volume.blockY(y), volume.blockZ(z)));
+        }
+    }
+
+    private static void same(float expected, float actual, String label) {
+        if (Float.floatToRawIntBits(expected) != Float.floatToRawIntBits(actual))
+            throw new AssertionError(label + ": expected " + Float.toHexString(expected) + ", actual " + Float.toHexString(actual));
+    }
+    private static void require(boolean condition, String message) { if (!condition) throw new AssertionError(message); }
+}

mods/sanctuary/src/gametest/resources/fabric.mod.json

@@ -6,7 +6,7 @@
   "environment": "*",
   "license": "GPL-3.0-or-later",
   "entrypoints": {
-    "fabric-gametest": ["fr.koka.sanctuary.gametest.SanctuaryWorldGameTests"],
+    "fabric-gametest": ["${gametest_entrypoint}"],
     "fabric-client-gametest": ["fr.koka.sanctuary.gametest.SanctuaryClientRenderTests"]
   },
   "mixins": ["sanctuary-gametest.mixins.json"],

mods/sanctuary/src/main/java/fr/koka/sanctuary/SanctuaryMod.java

@@ -1,6 +1,30 @@
 package fr.koka.sanctuary;
 
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import fr.koka.sanctuary.worldgen.SanctuaryBiomeSource;
+
+import fr.koka.sanctuary.worldgen.CavernIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.PopulationIslandDensity;
+import fr.koka.sanctuary.worldgen.PopulationIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.PopulationGrovesFeature;
+import fr.koka.sanctuary.worldgen.PopulationDecorationsFeature;
+import fr.koka.sanctuary.worldgen.PopulationShoreSugarCaneFeature;
+import fr.koka.sanctuary.worldgen.CavernGrovesFeature;
+import fr.koka.sanctuary.worldgen.CavernDecorationsFeature;
+import fr.koka.sanctuary.worldgen.CavernShoreSugarCaneFeature;
+import fr.koka.sanctuary.worldgen.RiftIslandDensity;
+import fr.koka.sanctuary.worldgen.RiftIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.RiftGrovesFeature;
+import fr.koka.sanctuary.worldgen.RiftShoreSugarCaneFeature;
 import fr.koka.sanctuary.worldgen.MainIslandDensity;
+import fr.koka.sanctuary.worldgen.WoodlandIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.WoodlandShoreSugarCaneFeature;
+import fr.koka.sanctuary.worldgen.WoodlandGrovesFeature;
+import fr.koka.sanctuary.worldgen.NaturalShoreSugarCaneFeature;
+import fr.koka.sanctuary.worldgen.TemperateIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.LayeredIslandBiomeSource;
+import fr.koka.sanctuary.worldgen.LayeredShoreSugarCaneFeature;
+import fr.koka.sanctuary.worldgen.LowerTerraceVegetationFeature;
 import fr.koka.sanctuary.worldgen.ShoreSugarCaneFeature;
 import net.fabricmc.api.ModInitializer;
 import net.minecraft.core.Registry;
@@ -19,8 +43,36 @@ public final class SanctuaryMod implements ModInitializer {
 
     @Override
     public void onInitialize() {
+        Registry.register(BuiltInRegistries.CHUNK_GENERATOR, id("expansion_lab"), fr.koka.sanctuary.expansion.ExpansionChunkGenerator.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("expansion_lab"), fr.koka.sanctuary.expansion.ExpansionBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, id("expansion_island"), fr.koka.sanctuary.expansion.ExpansionDensity.CODEC);
+        fr.koka.sanctuary.expansion.ExpansionRuntime.register();
+        fr.koka.sanctuary.expansion.ExpansionCommands.register();
         Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, id("main_island"), MainIslandDensity.CODEC);
+        Registry.register(BuiltInRegistries.CHUNK_GENERATOR, id("island_v13"), SanctuaryChunkGenerator.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("island_v13"), SanctuaryBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, id("population_island"), PopulationIslandDensity.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("population_island"), PopulationIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("population_groves"), PopulationGrovesFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("population_decorations"), PopulationDecorationsFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("population_shore_sugar_cane"), PopulationShoreSugarCaneFeature.CODEC);
         Registry.register(BuiltInRegistries.FEATURE_TYPE, id("shore_sugar_cane"), ShoreSugarCaneFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("natural_shore_sugar_cane"), NaturalShoreSugarCaneFeature.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("temperate_island"), TemperateIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("layered_shore_sugar_cane"), LayeredShoreSugarCaneFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("lower_terrace_vegetation"), LowerTerraceVegetationFeature.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("layered_island"), LayeredIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("woodland_island"), WoodlandIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("woodland_shore_sugar_cane"), WoodlandShoreSugarCaneFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("woodland_groves"), WoodlandGrovesFeature.CODEC);
+        Registry.register(BuiltInRegistries.DENSITY_FUNCTION_TYPE, id("rift_island"), RiftIslandDensity.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("rift_island"), RiftIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("rift_groves"), RiftGrovesFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("rift_shore_sugar_cane"), RiftShoreSugarCaneFeature.CODEC);
+        Registry.register(BuiltInRegistries.BIOME_SOURCE, id("cavern_island"), CavernIslandBiomeSource.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("cavern_groves"), CavernGrovesFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("cavern_decorations"), CavernDecorationsFeature.CODEC);
+        Registry.register(BuiltInRegistries.FEATURE_TYPE, id("cavern_shore_sugar_cane"), CavernShoreSugarCaneFeature.CODEC);
         LOGGER.info("Sanctuary initialized: the Sanctuary world preset is available.");
     }
 }

mods/sanctuary/src/main/java/fr/koka/sanctuary/client/SanctuaryWorldOptionsScreen.java

@@ -0,0 +1,104 @@
+package fr.koka.sanctuary.client;
+
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import net.minecraft.client.gui.components.Button;
+import net.minecraft.client.gui.components.CycleButton;
+import net.minecraft.client.gui.components.MultiLineTextWidget;
+import net.minecraft.client.gui.layouts.HeaderAndFooterLayout;
+import net.minecraft.client.gui.layouts.LinearLayout;
+import net.minecraft.client.gui.screens.Screen;
+import net.minecraft.client.gui.screens.worldselection.CreateWorldScreen;
+import net.minecraft.client.gui.screens.worldselection.WorldCreationContext;
+import net.minecraft.network.chat.CommonComponents;
+import net.minecraft.network.chat.Component;
+
+/** Edits only the pending new world's island size. Cancel never changes its dimensions. */
+public final class SanctuaryWorldOptionsScreen extends Screen {
+    private final CreateWorldScreen parent;
+    private final SanctuaryChunkGenerator generator;
+    private final HeaderAndFooterLayout layout = new HeaderAndFooterLayout(this);
+    private IslandSize selectedSize;
+    private MultiLineTextWidget diameterHint;
+
+    public SanctuaryWorldOptionsScreen(CreateWorldScreen parent, WorldCreationContext context) {
+        super(Component.translatable("sanctuary.world_options.title"));
+        this.parent = parent;
+        if (!(context.selectedDimensions().overworld() instanceof SanctuaryChunkGenerator sanctuary)) {
+            throw new IllegalArgumentException("Sanctuary options require the unified generator");
+        }
+        generator = sanctuary;
+        selectedSize = IslandSize.fromDiameter(generator.initialDiameter());
+    }
+
+    @Override
+    protected void init() {
+        layout.removeChildren();
+        layout.addTitleHeader(title, font);
+
+        LinearLayout contents = LinearLayout.vertical().spacing(12);
+        contents.defaultCellSetting().alignHorizontallyCenter();
+        contents.addChild(new MultiLineTextWidget(Component.translatable("sanctuary.world_options.description"), font)
+                .setMaxWidth(310).setCentered(true));
+        CycleButton<IslandSize> sizeButton = CycleButton.builder(IslandSize::label, selectedSize)
+                .withValues(IslandSize.values())
+                .create(0, 0, 240, 20, Component.translatable("sanctuary.world_options.size"), (button, size) -> {
+                    selectedSize = size;
+                    diameterHint.setMessage(diameterHint());
+                    layout.arrangeElements();
+                });
+        contents.addChild(sizeButton);
+        diameterHint = contents.addChild(new MultiLineTextWidget(diameterHint(), font)
+                .setMaxWidth(310).setCentered(true));
+        layout.addToContents(contents);
+
+        LinearLayout actions = LinearLayout.horizontal().spacing(8);
+        actions.addChild(Button.builder(CommonComponents.GUI_DONE, button -> applyAndClose()).width(150).build());
+        actions.addChild(Button.builder(CommonComponents.GUI_CANCEL, button -> onClose()).width(150).build());
+        layout.addToFooter(actions);
+        layout.visitWidgets(this::addRenderableWidget);
+        repositionElements();
+    }
+
+    private Component diameterHint() {
+        return Component.translatable("sanctuary.world_options.diameter", selectedSize.diameter);
+    }
+
+    private void applyAndClose() {
+        parent.getUiState().updateDimensions((registries, dimensions) -> dimensions.replaceOverworldGenerator(
+                registries, generator.withInitialDiameter(selectedSize.diameter)));
+        onClose();
+    }
+
+    @Override
+    protected void repositionElements() {
+        layout.arrangeElements();
+    }
+
+    @Override
+    public void onClose() {
+        minecraft.gui.setScreen(parent);
+    }
+
+    private enum IslandSize {
+        SMALL("small", 512), MEDIUM("medium", 724), LARGE("large", 1024);
+
+        private final String id;
+        private final int diameter;
+
+        IslandSize(String id, int diameter) {
+            this.id = id;
+            this.diameter = diameter;
+        }
+
+        Component label() {
+            return Component.translatable("sanctuary.world_options.size." + id);
+        }
+
+        static IslandSize fromDiameter(int diameter) {
+            for (IslandSize size : values()) {
+                if (size.diameter == diameter) return size;
+            }
+            throw new IllegalArgumentException("Unsupported Sanctuary island diameter: " + diameter);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionAdmission.java

@@ -0,0 +1,114 @@
+package fr.koka.sanctuary.expansion;
+
+import fr.koka.sanctuary.mixin.ExpansionChunkMapAccessor;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.server.level.ChunkMap;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.ChunkPos;
+
+/** Conservative admission for fresh regions only; inspecting a position never requests generation. */
+public final class ExpansionAdmission {
+    private static final int MAX_CHUNKS = 4_000;
+    private static final int READ_BATCH = 64;
+    private static final long DEADLINE_NANOS = TimeUnit.SECONDS.toNanos(30);
+
+    private ExpansionAdmission() { }
+
+    public static void verify(ServerLevel level, ExpansionIsland island) throws IOException {
+        verify(level, island, searchDeadline());
+    }
+
+    /** A caller searching several positions must share this deadline across all admission attempts. */
+    public static long searchDeadline() {
+        return System.nanoTime() + DEADLINE_NANOS;
+    }
+
+    public static void verify(ServerLevel level, ExpansionIsland island, long deadlineNanos) throws IOException {
+        checkDeadline(deadlineNanos);
+        List<ChunkPos> positions = positions(level, island);
+        ChunkMap map = level.getChunkSource().chunkMap;
+        verifyHolders(map, positions, deadlineNanos);
+        for (int start = 0; start < positions.size(); start += READ_BATCH) {
+            checkDeadline(deadlineNanos);
+            int end = Math.min(positions.size(), start + READ_BATCH);
+            List<CompletableFuture<Optional<CompoundTag>>> reads = new ArrayList<>();
+            for (int i = start; i < end; i++) reads.add(map.read(positions.get(i)));
+            ChunkPos occupied = null;
+            try {
+                for (int i = 0; i < reads.size(); i++) {
+                    long remaining = deadlineNanos - System.nanoTime();
+                    if (remaining <= 0) throw new TimeoutException("Admission deadline expired");
+                    if (reads.get(i).get(remaining, TimeUnit.NANOSECONDS).isPresent()) {
+                        occupied = positions.get(start + i);
+                    }
+                }
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                throw new IOException("Expansion admission interrupted", e);
+            } catch (TimeoutException e) {
+                throw new IOException("search_timeout", e);
+            } catch (ExecutionException e) {
+                throw new IOException("Expansion could not prove that every reserved chunk is absent", e);
+            }
+            // Drain every submitted read before skipping this occupied region, so a failed read
+            // is never swallowed as an ordinary collision and no next attempt overlaps the batch.
+            checkDeadline(deadlineNanos);
+            if (occupied != null) throw new OccupiedException("Expansion intersects an existing saved chunk: " + occupied);
+        }
+        verifyHolders(map, positions, deadlineNanos);
+        // Caller must commit and publish on this same server turn, without yielding or processing ticks.
+    }
+
+    /** Recheck active requests immediately before commit, after read-only terrain prospecting. */
+    public static void verifyHolders(ServerLevel level, ExpansionIsland island, long deadlineNanos) throws IOException {
+        checkDeadline(deadlineNanos);
+        verifyHolders(level.getChunkSource().chunkMap, positions(level, island), deadlineNanos);
+    }
+
+    private static List<ChunkPos> positions(ServerLevel level, ExpansionIsland island) throws IOException {
+        if (!level.getServer().isSameThread()) throw new IOException("Expansion admission must run on the server thread");
+        if (island.origin()) throw new IOException("The existing Sanctuary region cannot be admitted again");
+        int radius = island.reservedRadius();
+        int minX = Math.floorDiv(island.centerX() - radius, 16), maxX = Math.floorDiv(island.centerX() + radius, 16);
+        int minZ = Math.floorDiv(island.centerZ() - radius, 16), maxZ = Math.floorDiv(island.centerZ() + radius, 16);
+        if ((long) (maxX - minX + 1) * (maxZ - minZ + 1) > MAX_CHUNKS) throw new IOException("Expansion admission exceeds 4000 chunks");
+        ChunkMap map = level.getChunkSource().chunkMap;
+        if (!(map instanceof ExpansionChunkMapAccessor)) throw new IOException("Expansion chunk safety accessor is unavailable");
+        List<ChunkPos> positions = new ArrayList<>();
+        for (int z = minZ; z <= maxZ; z++) for (int x = minX; x <= maxX; x++) positions.add(new ChunkPos(x, z));
+        return positions;
+    }
+
+    private static void verifyHolders(ChunkMap map, List<ChunkPos> positions, long deadlineNanos) throws IOException {
+        for (ChunkPos position : positions) {
+            checkDeadline(deadlineNanos);
+            rejectHolder(map, position);
+        }
+    }
+
+    public static void checkDeadline(long deadlineNanos) throws IOException {
+        if (deadlineNanos - System.nanoTime() <= 0) throw new IOException("search_timeout");
+    }
+
+    private static void rejectHolder(ChunkMap map, ChunkPos position) throws IOException {
+        long key = position.pack();
+        if (map.getUpdatingChunkIfPresent(key) != null || ((ExpansionChunkMapAccessor) map).sanctuary$pendingUnloads().containsKey(key)) {
+            throw new OccupiedException("Expansion intersects a loaded or unloading chunk: " + position);
+        }
+    }
+
+    /** Only proven occupancy may move the search farther along the requested direction. */
+    public static final class OccupiedException extends IOException {
+        public OccupiedException(String message) {
+            super(message);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionBiomeSource.java

@@ -0,0 +1,138 @@
+package fr.koka.sanctuary.expansion;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Stream;
+import net.minecraft.core.Holder;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeResolver;
+import net.minecraft.world.level.biome.BiomeSource;
+import net.minecraft.world.level.biome.Climate;
+import org.jspecify.annotations.Nullable;
+
+/** All future holders are known up front; only the immutable region snapshot changes on activation. */
+public class ExpansionBiomeSource extends BiomeSource {
+    public static final List<String> REQUIRED_BIOMES = Stream.of(
+        "the_void", "forest", "birch_forest", "flower_forest", "plains", "meadow",
+        "taiga", "snowy_taiga", "snowy_plains", "grove", "ice_spikes", "frozen_peaks",
+        "old_growth_spruce_taiga", "dark_forest", "swamp", "pale_garden", "jungle",
+        "sparse_jungle", "bamboo_jungle", "mangrove_swamp", "savanna", "savanna_plateau",
+        "desert", "badlands", "eroded_badlands", "wooded_badlands", "windswept_hills",
+        "windswept_gravelly_hills", "stony_peaks", "dappled_forest", "cherry_grove",
+        "lush_caves", "dripstone_caves", "sulfur_caves"
+    ).map(path -> "minecraft:" + path).toList();
+
+    public static final MapCodec<ExpansionBiomeSource> CODEC = RecordCodecBuilder.mapCodec(i -> i.group(
+        Biome.CODEC.listOf().fieldOf("biomes").forGetter(source -> source.biomes)
+    ).apply(i, ExpansionBiomeSource::new));
+
+    private final List<Holder<Biome>> biomes;
+    private final Map<String, Holder<Biome>> byName;
+    private volatile List<ExpansionIsland> islands = List.of();
+
+    public ExpansionBiomeSource(List<Holder<Biome>> biomes) {
+        this.biomes = List.copyOf(biomes);
+        var names = new HashMap<String, Holder<Biome>>();
+        for (Holder<Biome> biome : biomes) {
+            String name = biome.unwrapKey().orElseThrow(() -> new IllegalArgumentException("Expansion biomes must be registered holders"))
+                .identifier().toString();
+            if (names.put(name, biome) != null) throw new IllegalArgumentException("Duplicate expansion biome: " + name);
+        }
+        for (String required : REQUIRED_BIOMES) {
+            if (!names.containsKey(required)) throw new IllegalArgumentException("Missing expansion biome: " + required);
+        }
+        this.byName = Map.copyOf(names);
+    }
+
+    public void setIslands(List<ExpansionIsland> islands) { this.islands = List.copyOf(islands); }
+    public List<ExpansionIsland> islands() { return islands; }
+
+    public @Nullable ExpansionIsland islandAt(int x, int z) {
+        return islandAt(islands, x, z);
+    }
+
+    private static @Nullable ExpansionIsland islandAt(List<ExpansionIsland> snapshot, int x, int z) {
+        for (ExpansionIsland island : snapshot) if (island.contains(x, z)) return island;
+        return null;
+    }
+
+    @Override protected MapCodec<? extends ExpansionBiomeSource> codec() { return CODEC; }
+    @Override protected Stream<Holder<Biome>> collectPossibleBiomes() { return biomes.stream(); }
+
+    @Override
+    public BiomeResolver createResolver(Climate.Sampler sampler) {
+        // General-purpose resolvers may outlive an activation. Resolve against the current snapshot.
+        return (quartX, quartY, quartZ) -> resolve(islands, quartX * 4, quartY * 4, quartZ * 4);
+    }
+
+    @Override
+    public BiomeResolver createResolverForChunk(Climate.Sampler sampler, int minQuartX, int minQuartY,
+            int minQuartZ, int quartSizeX, int quartSizeY, int quartSizeZ) {
+        List<ExpansionIsland> snapshot = islands;
+        return (quartX, quartY, quartZ) -> resolve(snapshot, quartX * 4, quartY * 4, quartZ * 4);
+    }
+
+    protected Holder<Biome> resolve(List<ExpansionIsland> snapshot, int x, int y, int z) {
+        ExpansionIsland island = islandAt(snapshot, x, z);
+        if (island == null || y < 0 || y >= 384) return biome("the_void");
+        double scale = Math.clamp(island.diameter() / 3.0, 24.0, 144.0);
+        double localX = (x - island.centerX()) / scale, localZ = (z - island.centerZ()) / scale;
+        double variation = noise(island.seed(), localX, localZ);
+        double moisture = noise(island.seed() ^ 0xA12C11A7EL, localX * 0.8, localZ * 0.8);
+        double elevation = y - variation * 14 - moisture * 8;
+
+        // Small pockets preserve the surface profile on exposed lower ledges.
+        if (y < 168 && elevation < 162) {
+            if ((island.relief().equals("volcano") && variation > -0.4)
+                    || (variation > 0.22 && variation < 0.46 && moisture < -0.18)) return biome("sulfur_caves");
+            if (moisture > 0.14 && variation > -0.38) return biome("lush_caves");
+            if (moisture < -0.18 && variation < 0.2) return biome("dripstone_caves");
+        }
+
+        String selected = switch (island.climate()) {
+            case "temperate" -> Math.abs(variation) < 0.13 ? "plains"
+                : variation < -0.33 ? "birch_forest" : moisture > 0.44 ? "flower_forest" : "forest";
+            case "boreal" -> elevation > 244 ? "snowy_taiga" : variation < -0.2 ? "grove" : "taiga";
+            case "glacial" -> elevation > 246 ? "frozen_peaks" : variation > 0.35 ? "ice_spikes" : "snowy_plains";
+            case "cold_humid" -> elevation > 250 ? "grove" : variation < -0.16 ? "taiga" : "old_growth_spruce_taiga";
+            case "humid" -> moisture > 0.4 && variation < 0 ? "pale_garden"
+                : elevation < 222 && variation < 0.14 ? "swamp" : "dark_forest";
+            case "tropical" -> elevation < 218 && moisture > 0.15 ? "mangrove_swamp"
+                : variation > 0.3 ? "bamboo_jungle" : variation < -0.34 ? "sparse_jungle" : "jungle";
+            case "warm" -> elevation > 244 ? "savanna_plateau" : moisture > 0.46 ? "sparse_jungle" : "savanna";
+            case "arid" -> variation < -0.2 ? "desert" : variation > 0.4 ? "eroded_badlands"
+                : moisture > 0.36 ? "wooded_badlands" : "badlands";
+            case "dry" -> elevation > 250 ? "stony_peaks" : variation > 0.28 ? "windswept_hills"
+                : moisture < -0.38 ? "windswept_gravelly_hills" : "plains";
+            case "cold_dry" -> elevation > 250 ? "frozen_peaks" : variation > 0.12 ? "snowy_plains" : "windswept_gravelly_hills";
+            case "autumn" -> Math.abs(variation) < 0.12 ? "meadow" : variation < -0.52 ? "birch_forest" : "dappled_forest";
+            case "cherry" -> elevation > 258 ? "grove" : variation < -0.22 ? "meadow" : "cherry_grove";
+            default -> throw new IllegalStateException("Unvalidated expansion climate: " + island.climate());
+        };
+        return biome(selected);
+    }
+
+    private Holder<Biome> biome(String path) { return byName.get("minecraft:" + path); }
+
+    private static double noise(long seed, double x, double z) {
+        int floorX = (int) Math.floor(x), floorZ = (int) Math.floor(z);
+        double tx = fade(x - floorX), tz = fade(z - floorZ);
+        double north = mix(lattice(seed, floorX, floorZ), lattice(seed, floorX + 1, floorZ), tx);
+        double south = mix(lattice(seed, floorX, floorZ + 1), lattice(seed, floorX + 1, floorZ + 1), tx);
+        return mix(north, south, tz);
+    }
+
+    private static double lattice(long seed, int x, int z) {
+        long value = seed ^ (x * 0x9E3779B97F4A7C15L) ^ (z * 0xC2B2AE3D27D4EB4FL);
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        value ^= value >>> 31;
+        return (value >>> 11) * 0x1.0p-52 - 1.0;
+    }
+
+    private static double fade(double value) { return value * value * (3 - 2 * value); }
+    private static double mix(double start, double end, double amount) { return start + (end - start) * amount; }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionChunkGenerator.java

@@ -0,0 +1,155 @@
+package fr.koka.sanctuary.expansion;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ConcurrentHashMap;
+import net.minecraft.core.BlockPos;
+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.server.level.ServerLevel;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.world.level.Level;
+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.block.Blocks;
+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.chunk.ChunkGeneratorStructureState;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseGeneratorSettings;
+import net.minecraft.world.level.levelgen.NoiseRouter;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.blending.Blender;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.structure.templatesystem.StructureTemplateManager;
+
+/** Laboratory only. Each immutable island has its own vanilla noise generator and seeded RandomState.
+ * The host ChunkMap's empty fallback RandomState is deliberately never used for terrain. */
+public class ExpansionChunkGenerator extends ChunkGenerator {
+    public static final MapCodec<ExpansionChunkGenerator> CODEC = RecordCodecBuilder.mapCodec(i -> i.group(
+        ExpansionBiomeSource.CODEC.fieldOf("biome_source").forGetter(ExpansionChunkGenerator::source),
+        Codec.intRange(512, 724).optionalFieldOf("initial_diameter", 512).forGetter(ExpansionChunkGenerator::initialDiameter)
+    ).apply(i, ExpansionChunkGenerator::new));
+    private final ExpansionBiomeSource source;
+    private final int initialDiameter;
+    protected volatile RegistryAccess registries;
+    private final Map<ExpansionIsland, Context> contexts = new ConcurrentHashMap<>();
+    protected record Context(NoiseBasedChunkGenerator generator, RandomState random) { public Context {} }
+
+    public ExpansionChunkGenerator(ExpansionBiomeSource source, int initialDiameter) {
+        this(source, initialDiameter, false);
+    }
+    protected ExpansionChunkGenerator(ExpansionBiomeSource source, int initialDiameter, boolean unified) {
+        super(source);
+        if (initialDiameter != 512 && initialDiameter != 724 && !(unified && initialDiameter == 1024))
+            throw new IllegalArgumentException("Unsupported Sanctuary diameter");
+        this.source = source;
+        this.initialDiameter = initialDiameter;
+    }
+    public ExpansionBiomeSource source() { return source; }
+    public int initialDiameter() { return initialDiameter; }
+    @Override protected MapCodec<? extends ExpansionChunkGenerator> codec() { return CODEC; }
+    public void initialize(ServerLevel level, List<ExpansionIsland> islands) {
+        registries = level.registryAccess();
+        source.setIslands(islands);
+    }
+    public void setIslands(List<ExpansionIsland> islands) { source.setIslands(islands); }
+    public void discardUnpublishedContext(ExpansionIsland island) {
+        var key = island.ready();
+        if (source.islands().stream().noneMatch(saved -> saved.ready().equals(key))) contexts.remove(key);
+    }
+    public Holder<Biome> structureBiome(Holder<Biome> biome) { return biome; }
+    public ExpansionIsland islandAt(int x, int z) { return source.islandAt(x, z); }
+    public ExpansionIsland islandForChunk(int x, int z) {
+        for (ExpansionIsland island : source.islands()) if (island.ownsChunk(x, z)) return island;
+        return null;
+    }
+    protected Context context(ExpansionIsland island) {
+        if (registries == null) throw new IllegalStateException("Expansion generator used before world attachment");
+        return contexts.computeIfAbsent(island.ready(), ignored -> {
+            String baseKey = island.origin() && island.diameter() == 724 ? "population_10" : "population_5";
+            var settingsRegistry = registries.lookupOrThrow(Registries.NOISE_SETTINGS);
+            var base = settingsRegistry.getValue(Identifier.fromNamespaceAndPath("sanctuary", baseKey));
+            var vanilla = settingsRegistry.getValue(Identifier.withDefaultNamespace("overworld"));
+            if (base == null || vanilla == null) throw new IllegalStateException("Missing laboratory noise settings");
+            var router = base.noiseRouter();
+            var density = new ExpansionDensity(router.finalDensity(), island);
+            var translated = new NoiseRouter(router.temperature(), router.vegetation(), router.continents(), router.erosion(),
+                router.depth(), router.ridges(), router.chunkSurfaceLevel(), density);
+            var settings = new NoiseGeneratorSettings(base.noiseSettings(), base.defaultBlock(), Blocks.AIR.defaultBlockState(),
+                translated, vanilla.materialRule(), List.of(), -64, false, Optional.empty(), base.useLegacyRandomSource(), base.debugFunctions());
+            var delegate = new NoiseBasedChunkGenerator(source, Holder.direct(settings));
+            var random = RandomState.create(registries.lookupOrThrow(Registries.NOISE), island.seed(), settings);
+            return new Context(delegate, random);
+        });
+    }
+    protected void afterTerrain(ExpansionIsland island, ChunkAccess chunk) { ExpansionTerrain.apply(island, chunk); }
+    public String journalDirectory() { return "sanctuary-expansion-v1"; }
+    public int rootGeneration() { return ExpansionIsland.GENERATION; }
+    public RandomState randomState(ExpansionIsland island) { return context(island).random(); }
+    public NoiseBasedChunkGenerator delegate(ExpansionIsland island) { return context(island).generator(); }
+    @Override public CompletableFuture<ChunkAccess> createBiomes(RandomState ignored, Blender blender, StructureManager structures, ChunkAccess chunk) {
+        var island = islandForChunk(chunk.getPos().x(), chunk.getPos().z());
+        if (island == null) return super.createBiomes(ignored, blender, structures, chunk);
+        var context = context(island);
+        return context.generator().createBiomes(context.random(), blender, structures, chunk);
+    }
+    @Override public CompletableFuture<ChunkAccess> buildTerrain(ChunkAccess chunk, Blender blender, RandomState ignored,
+            StructureManager structures, BiomeManager manager, WorldGenRegion region, Set<Holder<Biome>> biomes) {
+        var island = islandForChunk(chunk.getPos().x(), chunk.getPos().z());
+        if (island == null) return CompletableFuture.completedFuture(chunk);
+        var context = context(island);
+        return context.generator().buildTerrain(chunk, blender, context.random(), structures, manager, region, biomes).thenApply(generated -> {
+            afterTerrain(island, generated);
+            return generated;
+        });
+    }
+    @Override public void createStructures(RegistryAccess registries, ChunkGeneratorStructureState state, StructureManager structures,
+            ChunkAccess chunk, StructureTemplateManager templates, ResourceKey<Level> dimension) {
+        ExpansionStructures.generate(this, registries, state, structures, chunk, templates, dimension);
+    }
+    @Override public void spawnOriginalMobs(WorldGenRegion region) {
+        var pos = region.getCenter();
+        var island = islandForChunk(pos.x(), pos.z());
+        if (island != null) context(island).generator().spawnOriginalMobs(region);
+    }
+    @Override public int getGenDepth() { return 384; }
+    @Override public int getMinY() { return 0; }
+    @Override public int getSeaLevel() { return -64; }
+    @Override public int getSpawnHeight(LevelHeightAccessor level) { return 220; }
+    @Override public int getBaseHeight(int x, int z, Heightmap.Types type, LevelHeightAccessor level, RandomState ignored) {
+        var island = islandAt(x, z);
+        if (island == null) return getMinY();
+        var context = context(island);
+        return context.generator().getBaseHeight(x, z, type, level, context.random());
+    }
+    @Override public NoiseColumn getBaseColumn(int x, int z, LevelHeightAccessor level, RandomState ignored) {
+        var island = islandAt(x, z);
+        if (island != null) {
+            var context = context(island);
+            return context.generator().getBaseColumn(x, z, level, context.random());
+        }
+        BlockState[] air = new BlockState[384];
+        java.util.Arrays.fill(air, Blocks.AIR.defaultBlockState());
+        return new NoiseColumn(0, air);
+    }
+    @Override public void addDebugScreenInfo(List<String> text, RandomState ignored, BlockPos pos, SamplerContext context) {
+        var island = islandAt(pos.getX(), pos.getZ());
+        String prefix = "Sanctuary gen " + rootGeneration() + ": ";
+        text.add(island == null ? prefix + "void" : prefix + island.id() + " / " + island.climate() + " / " + island.relief());
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionCommands.java

@@ -0,0 +1,142 @@
+package fr.koka.sanctuary.expansion;
+
+import com.mojang.brigadier.Command;
+import com.mojang.brigadier.arguments.IntegerArgumentType;
+import com.mojang.brigadier.arguments.StringArgumentType;
+import com.mojang.brigadier.builder.LiteralArgumentBuilder;
+import com.mojang.brigadier.context.CommandContext;
+import java.util.List;
+import java.util.Set;
+import net.fabricmc.fabric.api.command.v2.CommandRegistrationCallback;
+import net.minecraft.commands.CommandSourceStack;
+import net.minecraft.commands.Commands;
+import net.minecraft.commands.SharedSuggestionProvider;
+import net.minecraft.network.chat.Component;
+
+/** OP tools for the experimental world, also usable from the dedicated server console. */
+public final class ExpansionCommands {
+    private ExpansionCommands() {}
+    private static final String PREFIX = "sanctuary.expansion.";
+    public static void register() {
+        CommandRegistrationCallback.EVENT.register((dispatcher, registries, environment) -> {
+            var expansion = Commands.literal("expansion").executes(ExpansionCommands::help)
+                .then(Commands.literal("help").executes(ExpansionCommands::help))
+                .then(Commands.literal("list").executes(c -> run(c, () -> {
+                    var session = ExpansionRuntime.session(c.getSource().getLevel());
+                    for (var island : session.islands()) c.getSource().sendSuccess(() -> Component.translatable(PREFIX + "entry", island.id(), island.parent(),
+                        label("direction", island.direction()), label("climate", island.climate()), island.diameter(), label("relief", island.relief()), island.centerX(), island.centerZ(),
+                        Component.translatable(PREFIX + "state." + island.status())), false);
+                    c.getSource().sendSuccess(() -> Component.translatable(PREFIX + "progress", session.progress()), false);
+                    return session.islands().size();
+                })))
+                .then(Commands.literal("visit").then(islandArgument().executes(c -> run(c, () -> {
+                    var player = c.getSource().getPlayerOrException();
+                    if (player.isPassenger()) throw new IllegalArgumentException("dismount_first");
+                    var landing = ExpansionRuntime.session(c.getSource().getLevel()).landing(word(c, "island"));
+                    boolean moved = player.teleportTo(c.getSource().getLevel(), landing.getX() + 0.5, landing.getY(), landing.getZ() + 0.5,
+                        Set.of(), player.getYRot(), player.getXRot(), true);
+                    if (!moved) throw new IllegalArgumentException("teleport_failed");
+                    player.fallDistance = 0;
+                    c.getSource().sendSuccess(() -> Component.translatable(PREFIX + "visited", word(c, "island")), false);
+                    return Command.SINGLE_SUCCESS;
+                }))))
+                .then(Commands.literal("resume").then(islandArgument().executes(c -> run(c, () -> {
+                    ExpansionRuntime.session(c.getSource().getLevel()).resume(word(c, "island"));
+                    c.getSource().sendSuccess(() -> Component.translatable(PREFIX + "resumed", word(c, "island")), false);
+                    return Command.SINGLE_SUCCESS;
+                }))))
+                .then(createTree("create", false)).then(createTree("preview", true))
+                .then(Commands.literal("quick").then(Commands.argument("direction", StringArgumentType.word())
+                    .suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.DIRECTIONS, b))
+                    .executes(c -> quick(c, null, 128, "natural"))
+                    .then(Commands.argument("climate", StringArgumentType.word())
+                        .suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.CLIMATES, b))
+                        .executes(c -> quick(c, word(c, "climate"), 128, "natural"))
+                        .then(Commands.argument("diameter", IntegerArgumentType.integer(64, 512))
+                            .suggests((c, b) -> SharedSuggestionProvider.suggest(List.of("64", "128", "256", "512"), b))
+                            .executes(c -> quick(c, word(c, "climate"), IntegerArgumentType.getInteger(c, "diameter"), "natural"))
+                            .then(Commands.argument("relief", StringArgumentType.word())
+                                .suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.RELIEFS, b))
+                                .executes(c -> quick(c, word(c, "climate"), IntegerArgumentType.getInteger(c, "diameter"), word(c, "relief")))
+                                .then(distanceArgument().executes(c -> quick(c, word(c, "climate"), IntegerArgumentType.getInteger(c, "diameter"),
+                                    word(c, "relief"), IntegerArgumentType.getInteger(c, "distance")))))))));
+            dispatcher.register(Commands.literal("sanctuary").requires(Commands.hasPermission(Commands.LEVEL_GAMEMASTERS)).then(expansion));
+        });
+    }
+    private static com.mojang.brigadier.builder.RequiredArgumentBuilder<CommandSourceStack, String> islandArgument() {
+        return Commands.argument("island", StringArgumentType.word()).suggests((c, b) -> {
+            try { return SharedSuggestionProvider.suggest(ExpansionRuntime.session(c.getSource().getLevel()).islands().stream().map(ExpansionIsland::id), b); }
+            catch (IllegalArgumentException ignored) { return b.buildFuture(); }
+        });
+    }
+    private static LiteralArgumentBuilder<CommandSourceStack> createTree(String name, boolean preview) {
+        return Commands.literal(name).then(Commands.argument("id", StringArgumentType.word())
+            .then(Commands.argument("parent", StringArgumentType.word())
+                .suggests((c, b) -> {
+                    try { return SharedSuggestionProvider.suggest(ExpansionRuntime.session(c.getSource().getLevel()).islands().stream().map(ExpansionIsland::id), b); }
+                    catch (IllegalArgumentException ignored) { return b.buildFuture(); }
+                })
+                .then(Commands.argument("direction", StringArgumentType.word()).suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.DIRECTIONS, b))
+                    .then(Commands.argument("climate", StringArgumentType.word()).suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.CLIMATES, b))
+                        .then(Commands.argument("diameter", IntegerArgumentType.integer(64, 512))
+                            .suggests((c, b) -> SharedSuggestionProvider.suggest(List.of("64", "128", "256", "512"), b))
+                            .then(Commands.argument("relief", StringArgumentType.word()).suggests((c, b) -> SharedSuggestionProvider.suggest(ExpansionIsland.RELIEFS, b))
+                                .executes(c -> create(c, preview, 0))
+                                .then(distanceArgument().executes(c -> create(c, preview, IntegerArgumentType.getInteger(c, "distance"))))))))));
+    }
+    private static com.mojang.brigadier.builder.RequiredArgumentBuilder<CommandSourceStack, Integer> distanceArgument() {
+        return Commands.argument("distance", IntegerArgumentType.integer(0, 100_000))
+            .suggests((c, b) -> SharedSuggestionProvider.suggest(List.of("1024", "2048", "4096"), b));
+    }
+    private static int create(CommandContext<CommandSourceStack> c, boolean preview, int minimumDistance) {
+        return run(c, () -> {
+            var session = ExpansionRuntime.session(c.getSource().getLevel());
+            var island = preview ? session.candidate(word(c, "id"), word(c, "parent"), word(c, "direction"), word(c, "climate"),
+                IntegerArgumentType.getInteger(c, "diameter"), word(c, "relief"), minimumDistance)
+                : session.create(word(c, "id"), word(c, "parent"), word(c, "direction"), word(c, "climate"),
+                IntegerArgumentType.getInteger(c, "diameter"), word(c, "relief"), minimumDistance);
+            describe(c, island, preview);
+            return Command.SINGLE_SUCCESS;
+        });
+    }
+    private static int quick(CommandContext<CommandSourceStack> c, String climate, int diameter, String relief) {
+        return quick(c, climate, diameter, relief, 0);
+    }
+    private static int quick(CommandContext<CommandSourceStack> c, String climate, int diameter, String relief, int minimumDistance) {
+        return run(c, () -> {
+            var session = ExpansionRuntime.session(c.getSource().getLevel());
+            int next = session.islands().size();
+            while (true) {
+                String possible = "island_" + next;
+                if (session.islands().stream().noneMatch(i -> i.id().equals(possible))) break;
+                next++;
+            }
+            String direction = word(c, "direction");
+            if (!ExpansionIsland.DIRECTIONS.contains(direction)) throw new IllegalArgumentException("invalid_direction");
+            var island = session.create("island_" + next, "sanctuary", direction,
+                climate == null ? ExpansionIsland.directionalClimate(direction) : climate, diameter, relief, minimumDistance);
+            describe(c, island, false);
+            return Command.SINGLE_SUCCESS;
+        });
+    }
+    private static void describe(CommandContext<CommandSourceStack> c, ExpansionIsland island, boolean preview) {
+        c.getSource().sendSuccess(() -> Component.translatable(PREFIX + (preview ? "preview" : "created"),
+            island.id(), island.centerX(), island.centerZ(), label("climate", island.climate()), island.diameter(), label("relief", island.relief())), false);
+    }
+    private static int help(CommandContext<CommandSourceStack> context) {
+        context.getSource().sendSuccess(() -> Component.translatable(PREFIX + "help"), false);
+        return Command.SINGLE_SUCCESS;
+    }
+    private static String word(CommandContext<CommandSourceStack> context, String key) { return StringArgumentType.getString(context, key); }
+    private static Component label(String category, String id) { return Component.translatable(PREFIX + category + "." + id); }
+    @FunctionalInterface private interface Action { int run() throws Exception; }
+    private static int run(CommandContext<CommandSourceStack> context, Action action) {
+        try { return action.run(); }
+        catch (Exception exception) {
+            String reason = exception.getMessage() == null ? exception.getClass().getSimpleName() : exception.getMessage();
+            Component detail = reason.matches("[a-z_]+") ? Component.translatable(PREFIX + "error." + reason) : Component.literal(reason);
+            context.getSource().sendFailure(Component.translatable(PREFIX + "error", detail));
+            return 0;
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionDensity.java

@@ -0,0 +1,76 @@
+package fr.koka.sanctuary.expansion;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import java.util.Arrays;
+import net.minecraft.util.Interval;
+import net.minecraft.world.level.levelgen.densityfunction.DensityBuffer;
+import net.minecraft.world.level.levelgen.densityfunction.DensityFunction;
+import net.minecraft.world.level.levelgen.densityfunction.DensitySampler;
+import net.minecraft.world.level.levelgen.densityfunction.DensityVolume;
+import net.minecraft.world.level.levelgen.densityfunction.DfRewriteRule;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+
+/** Versioned alpha.12 wrapper around a complete historical density, sampled in its own island frame. */
+public record ExpansionDensity(DensityFunction source, ExpansionIsland island) implements DensityFunction {
+    public static final MapCodec<ExpansionDensity> CODEC = RecordCodecBuilder.mapCodec(i -> i.group(
+        DensityFunction.CODEC.fieldOf("source").forGetter(ExpansionDensity::source),
+        ExpansionIsland.CODEC.fieldOf("island").forGetter(ExpansionDensity::island)
+    ).apply(i, ExpansionDensity::new));
+
+    // One bounded numeric/descriptor cache per worker. It holds no sampler, context or world.
+    private static final ThreadLocal<ColumnCache> COLUMNS = ThreadLocal.withInitial(ColumnCache::new);
+
+    @Override public DensitySampler compileSampler(CompileContext context) {
+        DensitySampler original = source.compileSampler(context);
+        return new DensitySampler() {
+            @Override public float sampleValue(SamplerContext sample, int x, int y, int z) {
+                if (y <= 0 || y >= 384 || !island.contains(x, z)) return -1.0F;
+                ExpansionRelief.Column column = COLUMNS.get().get(island, x, z);
+                double sy = ExpansionRelief.sourceY(island, column, y);
+                if (sy <= 0 || sy >= 384) return -1.0F;
+                int sx = ExpansionRelief.sourceX(island, x), sz = ExpansionRelief.sourceZ(island, z);
+                int lowerY = (int) Math.floor(sy);
+                float low = original.sampleValue(sample, sx, lowerY, sz);
+                double fraction = sy - lowerY;
+                // Below the root's upper transition this is precisely the old single sample.
+                // Fractional Y elsewhere is interpolated, avoiding one-block terraces from rounding.
+                float density = fraction == 0.0 ? low : (float) (low
+                    + (original.sampleValue(sample, sx, lowerY + 1, sz) - low) * fraction);
+                return ExpansionRelief.sculpt(island, column, y, Math.clamp(density, -1.0F, 1.0F));
+            }
+
+            @Override public void sampleVolume(SamplerContext sample, DensityBuffer buffer, DensityVolume volume) {
+                DensitySampler.sampleVolumeNaive(sample, buffer, volume, this);
+            }
+        };
+    }
+
+    @Override public DensityFunction rewriteChildren(DfRewriteRule rule) {
+        return new ExpansionDensity(rule.rewrite(source), island);
+    }
+    @Override public Interval range() { return Interval.of(-1.0F, 1.0F); }
+    @Override public int domainAxes() { return ALL_AXES; }
+    @Override public MapCodec<ExpansionDensity> codec() { return CODEC; }
+
+    private static final class ColumnCache {
+        private static final int SIZE = 256;
+        private ExpansionIsland selected;
+        private final int[] xs = new int[SIZE], zs = new int[SIZE];
+        private final ExpansionRelief.Column[] columns = new ExpansionRelief.Column[SIZE];
+
+        ExpansionRelief.Column get(ExpansionIsland island, int x, int z) {
+            if (selected != island) {
+                selected = island;
+                Arrays.fill(columns, null);
+            }
+            int hash = x * 0x9e3779b9 ^ Integer.rotateLeft(z * 0x85ebca6b, 13);
+            int slot = (hash ^ (hash >>> 16)) & (SIZE - 1);
+            if (columns[slot] == null || xs[slot] != x || zs[slot] != z) {
+                columns[slot] = ExpansionRelief.column(island, x, z);
+                xs[slot] = x; zs[slot] = z;
+            }
+            return columns[slot];
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionIsland.java

@@ -0,0 +1,78 @@
+package fr.koka.sanctuary.expansion;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import java.util.List;
+
+/** Immutable alpha.12 region contract. Directions place islands; climate remains an explicit choice. */
+public record ExpansionIsland(String id, String parent, String direction, String climate,
+        int diameter, int centerX, int centerZ, long seed, String relief, String status, int generation) {
+    public static final int GENERATION = 12;
+    public static final List<String> DIRECTIONS = List.of("north", "northeast", "east", "southeast", "south", "southwest", "west", "northwest");
+    public static final List<String> CLIMATES = List.of("temperate", "boreal", "glacial", "cold_humid", "humid", "tropical", "warm", "arid", "dry", "cold_dry", "autumn", "cherry");
+    public static final List<String> RELIEFS = List.of("natural", "peaks", "canyon", "volcano");
+    public static final List<Integer> DIAMETERS = List.of(64, 128, 256, 512);
+    public static final int DECORATION_MARGIN = 32;
+    public static final int GENERATION_HALO = 176;
+    public static final Codec<ExpansionIsland> CODEC = RecordCodecBuilder.create(i -> i.group(
+        Codec.STRING.fieldOf("id").forGetter(ExpansionIsland::id),
+        Codec.STRING.fieldOf("parent").forGetter(ExpansionIsland::parent),
+        Codec.STRING.fieldOf("direction").forGetter(ExpansionIsland::direction),
+        Codec.STRING.fieldOf("climate").forGetter(ExpansionIsland::climate),
+        Codec.INT.fieldOf("diameter").forGetter(ExpansionIsland::diameter),
+        Codec.INT.fieldOf("center_x").forGetter(ExpansionIsland::centerX),
+        Codec.INT.fieldOf("center_z").forGetter(ExpansionIsland::centerZ),
+        Codec.LONG.fieldOf("seed").forGetter(ExpansionIsland::seed),
+        Codec.STRING.fieldOf("relief").forGetter(ExpansionIsland::relief),
+        Codec.STRING.fieldOf("status").forGetter(ExpansionIsland::status),
+        Codec.INT.fieldOf("generation").forGetter(ExpansionIsland::generation)
+    ).apply(i, ExpansionIsland::new));
+
+    public ExpansionIsland {
+        if (!id.matches("[a-z][a-z0-9_]{0,31}") || !parent.matches("[a-z][a-z0-9_]{0,31}")) throw new IllegalArgumentException("Invalid island identifier");
+        if (!DIRECTIONS.contains(direction) || !CLIMATES.contains(climate) || !RELIEFS.contains(relief)) throw new IllegalArgumentException("Unknown island profile");
+        if (!(DIAMETERS.contains(diameter) || (id.equals("sanctuary") && (diameter == 724 || generation == 13 && diameter == 1024)))) throw new IllegalArgumentException("Unsupported nominal diameter");
+        if (Math.abs((long) centerX) > 100_000 || Math.abs((long) centerZ) > 100_000 || (centerX & 15) != 0 || (centerZ & 15) != 0) throw new IllegalArgumentException("Invalid island centre");
+        if (!List.of("reserved", "ready").contains(status) || (generation != GENERATION && !(generation == 13 && id.equals("sanctuary")))) throw new IllegalArgumentException("Unsupported island state or generation");
+    }
+
+    public static ExpansionIsland origin(int diameter, long seed) {
+        return origin(diameter, seed, GENERATION);
+    }
+    public static ExpansionIsland origin(int diameter, long seed, int generation) {
+        return new ExpansionIsland("sanctuary", "sanctuary", "north", "temperate", diameter, 0, 0, seed, "natural", "ready", generation);
+    }
+
+    public boolean origin() { return id.equals("sanctuary"); }
+    public double referenceDiameter() { return origin() && diameter == 724 ? Math.sqrt(2) * 512 : 512; }
+    public double horizontalScale() { return origin() ? 1.0 : diameter / referenceDiameter(); }
+    public double radius() { return diameter / 2.0; }
+    public int terrainRadius() { if (generation == 13 && origin()) return diameter == 724 ? 395 : diameter / 2 + 32; return origin() && diameter == 724 ? 395 : (int) Math.ceil(radius() * 1.125); }
+    public int reservedRadius() { return terrainRadius() + DECORATION_MARGIN + GENERATION_HALO; }
+    public boolean contains(int x, int z) { return Math.hypot((double) x - centerX, (double) z - centerZ) < terrainRadius(); }
+    public boolean ownsChunk(int chunkX, int chunkZ) {
+        int x = Math.clamp(centerX, chunkX * 16, chunkX * 16 + 15);
+        int z = Math.clamp(centerZ, chunkZ * 16, chunkZ * 16 + 15);
+        return Math.hypot((double) x - centerX, (double) z - centerZ) <= terrainRadius() + DECORATION_MARGIN;
+    }
+    public boolean conflicts(ExpansionIsland other) {
+        return Math.abs((long) centerX - other.centerX) <= reservedRadius() + other.reservedRadius()
+            && Math.abs((long) centerZ - other.centerZ) <= reservedRadius() + other.reservedRadius();
+    }
+    public ExpansionIsland ready() { return new ExpansionIsland(id, parent, direction, climate, diameter, centerX, centerZ, seed, relief, "ready", generation); }
+    public static String directionalClimate(String direction) {
+        return switch (direction) {
+            case "north" -> "boreal"; case "northeast" -> "cold_humid"; case "east" -> "humid";
+            case "southeast" -> "tropical"; case "south" -> "warm"; case "southwest" -> "arid";
+            case "west" -> "dry"; case "northwest" -> "cold_dry";
+            default -> throw new IllegalArgumentException("Unknown direction");
+        };
+    }
+    public static long deriveSeed(long seed, String id) {
+        long h = seed ^ 0xA12E7A510L;
+        for (int c : id.toCharArray()) h = (h ^ c) * 0x100000001b3L;
+        h = (h ^ (h >>> 30)) * 0xbf58476d1ce4e5b9L;
+        h = (h ^ (h >>> 27)) * 0x94d049bb133111ebL;
+        return h ^ (h >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionJournal.java

@@ -0,0 +1,266 @@
+package fr.koka.sanctuary.expansion;
+
+import com.google.gson.Gson;
+import com.google.gson.GsonBuilder;
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonNull;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonPrimitive;
+import com.google.gson.Strictness;
+import com.google.gson.stream.JsonReader;
+import com.google.gson.stream.JsonToken;
+import java.io.IOException;
+import java.io.StringReader;
+import java.math.BigDecimal;
+import java.nio.ByteBuffer;
+import java.nio.channels.FileChannel;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.LinkOption;
+import java.nio.file.Path;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.StandardOpenOption;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** A failed or missing existing journal is never replaced with a fresh expansion history. */
+public final class ExpansionJournal {
+    public static final String FILE_NAME = "expansions.json";
+    public static final int MAX_ISLANDS = 64;
+    private static final int MAX_BYTES = 131_072;
+    private static final Gson JSON = new GsonBuilder().setPrettyPrinting().create();
+    private static final Set<String> JOURNAL_FIELDS = Set.of("schema", "world_seed", "root_diameter", "islands");
+    private static final Set<String> ISLAND_FIELDS = Set.of("id", "parent", "direction", "climate", "diameter", "center_x", "center_z", "seed", "relief", "status", "generation");
+    private final Path directory;
+    private final Path file;
+    private final long seed;
+    private final int rootDiameter;
+    private final int rootGeneration;
+    private final DirectorySync directorySync;
+    private List<ExpansionIsland> islands;
+    private boolean failed;
+
+    public ExpansionJournal(Path directory, long seed, int rootDiameter) throws IOException {
+        this(directory, seed, rootDiameter, ExpansionIsland.GENERATION);
+    }
+    public ExpansionJournal(Path directory, long seed, int rootDiameter, int rootGeneration) throws IOException {
+        this(directory, seed, rootDiameter, rootGeneration,
+            directorySyncFor(directory.getFileSystem().getSeparator(), ExpansionJournal::forceDirectory));
+    }
+
+    ExpansionJournal(Path directory, long seed, int rootDiameter, int rootGeneration, DirectorySync directorySync) throws IOException {
+        if (rootGeneration != 12 && rootGeneration != 13) throw new IOException("Unsupported root generation");
+        if (rootDiameter != 512 && rootDiameter != 724 && !(rootGeneration == 13 && rootDiameter == 1024))
+            throw new IOException("Unsupported expansion root diameter");
+        this.rootGeneration = rootGeneration;
+        this.directorySync = java.util.Objects.requireNonNull(directorySync);
+        this.directory = directory.toAbsolutePath().normalize();
+        this.file = this.directory.resolve(FILE_NAME);
+        this.seed = seed;
+        this.rootDiameter = rootDiameter;
+        if (Files.exists(this.directory, LinkOption.NOFOLLOW_LINKS)) {
+            if (!Files.isDirectory(this.directory, LinkOption.NOFOLLOW_LINKS)) throw new IOException("Expansion journal path is not a directory");
+            this.islands = read();
+        } else {
+            // Creating the directory is the bootstrap marker. An interrupted bootstrap requires repair.
+            Files.createDirectories(this.directory.getParent());
+            Files.createDirectory(this.directory);
+            this.islands = List.of(ExpansionIsland.origin(rootDiameter, seed, rootGeneration));
+            persist(this.islands);
+        }
+    }
+
+    public synchronized List<ExpansionIsland> islands() { return islands; }
+
+    /** False after uncertain persistence or external damage; only a successful reload can recover. */
+    public synchronized boolean healthy() { return !failed; }
+
+    public synchronized void commit(List<ExpansionIsland> proposed) throws IOException {
+        if (failed) throw new IOException("Expansion journal failed earlier; reload and inspect it before another expansion");
+        List<ExpansionIsland> next = validate(proposed);
+        if (next.size() < islands.size()) throw new IOException("Existing expansion regions cannot be removed");
+        for (int i = 0; i < islands.size(); i++) {
+            ExpansionIsland previous = islands.get(i), replacement = next.get(i);
+            if (!previous.equals(replacement) && !(previous.status().equals("reserved") && previous.ready().equals(replacement))) {
+                throw new IOException("Existing expansion region cannot be changed: " + previous.id());
+            }
+        }
+        for (int i = islands.size(); i < next.size(); i++) {
+            if (!next.get(i).status().equals("reserved")) throw new IOException("New expansion region must first be reserved");
+        }
+        // Detect another writer, a removed file or external damage before overwriting any history.
+        try {
+            if (!read().equals(islands)) throw new IOException("Expansion journal changed outside this instance");
+        } catch (IOException e) {
+            failed = true;
+            throw e;
+        }
+        if (next.equals(islands)) return;
+        persist(next);
+        islands = next;
+    }
+
+    private void persist(List<ExpansionIsland> next) throws IOException {
+        Path temporary = null;
+        try {
+            byte[] bytes = (JSON.toJson(encode(next)) + "\n").getBytes(StandardCharsets.UTF_8);
+            temporary = Files.createTempFile(directory, ".expansions-", ".tmp");
+            try (FileChannel output = FileChannel.open(temporary, StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING)) {
+                ByteBuffer buffer = ByteBuffer.wrap(bytes);
+                while (buffer.hasRemaining()) output.write(buffer);
+                output.force(true);
+            }
+            // No fallback to a non-atomic replacement: failure must remain visible to the caller.
+            Files.move(temporary, file, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING);
+            temporary = null;
+            directorySync.force(directory);
+            if (!read().equals(next)) throw new IOException("Expansion journal verification disagrees with the committed plan");
+        } catch (IOException | RuntimeException e) {
+            failed = true;
+            if (e instanceof IOException io) throw io;
+            throw new IOException("Could not commit expansion journal", e);
+        } finally {
+            if (temporary != null) {
+                try { Files.deleteIfExists(temporary); } catch (IOException ignored) { /* The original failure remains authoritative. */ }
+            }
+        }
+    }
+
+    @FunctionalInterface
+    interface DirectorySync { void force(Path directory) throws IOException; }
+
+    static DirectorySync directorySyncFor(String separator, DirectorySync supportedSync) {
+        // Windows FileChannel cannot open directory handles. Only this additional
+        // directory flush is omitted: file force, atomic replacement and read-back remain mandatory.
+        return "\\".equals(separator) ? directory -> {} : supportedSync;
+    }
+
+    private static void forceDirectory(Path directory) throws IOException {
+        try (FileChannel parent = FileChannel.open(directory, StandardOpenOption.READ)) { parent.force(true); }
+    }
+
+    private List<ExpansionIsland> read() throws IOException {
+        if (!Files.isRegularFile(file, LinkOption.NOFOLLOW_LINKS)) throw new IOException("Existing expansion directory has no regular journal file");
+        if (Files.size(file) > MAX_BYTES) throw new IOException("Expansion journal exceeds its size limit");
+        try (JsonReader reader = new JsonReader(new StringReader(Files.readString(file, StandardCharsets.UTF_8)))) {
+            reader.setStrictness(Strictness.STRICT);
+            JsonObject root = readJson(reader, 0).getAsJsonObject();
+            if (reader.peek() != JsonToken.END_DOCUMENT) throw new IOException("Trailing data in expansion journal");
+            requireFields(root, JOURNAL_FIELDS);
+            if (integer(root, "schema") != 1 || number(root, "world_seed").longValueExact() != seed || integer(root, "root_diameter") != rootDiameter) {
+                throw new IOException("Expansion journal schema, world seed or root diameter does not match");
+            }
+            JsonArray entries = root.getAsJsonArray("islands");
+            List<ExpansionIsland> decoded = new ArrayList<>();
+            for (JsonElement element : entries) {
+                JsonObject entry = element.getAsJsonObject();
+                requireFields(entry, ISLAND_FIELDS);
+                decoded.add(new ExpansionIsland(string(entry, "id"), string(entry, "parent"), string(entry, "direction"), string(entry, "climate"),
+                    integer(entry, "diameter"), integer(entry, "center_x"), integer(entry, "center_z"), number(entry, "seed").longValueExact(),
+                    string(entry, "relief"), string(entry, "status"), integer(entry, "generation")));
+            }
+            return validate(decoded);
+        } catch (RuntimeException e) {
+            throw new IOException("Invalid expansion journal", e);
+        }
+    }
+
+    private List<ExpansionIsland> validate(List<ExpansionIsland> proposed) throws IOException {
+        if (proposed == null || proposed.isEmpty() || proposed.size() > MAX_ISLANDS) throw new IOException("Expansion journal must contain 1 to 64 regions");
+        List<ExpansionIsland> checked;
+        try { checked = List.copyOf(proposed); } catch (RuntimeException e) { throw new IOException("Invalid expansion entries", e); }
+        if (!checked.getFirst().equals(ExpansionIsland.origin(rootDiameter, seed, rootGeneration))) throw new IOException("Sanctuary root region is immutable");
+        Map<String, ExpansionIsland> previous = new HashMap<>();
+        previous.put("sanctuary", checked.getFirst());
+        for (int i = 1; i < checked.size(); i++) {
+            ExpansionIsland island = checked.get(i);
+            if (previous.containsKey(island.id())) throw new IOException("Duplicate expansion identifier: " + island.id());
+            ExpansionIsland parent = previous.get(island.parent());
+            if (parent == null || !parent.status().equals("ready")) throw new IOException("Expansion parent must be an earlier ready region: " + island.parent());
+            if (island.seed() != ExpansionIsland.deriveSeed(seed, island.id())) throw new IOException("Expansion seed differs from its saved identity: " + island.id());
+            long dx = (long) island.centerX() - parent.centerX(), dz = (long) island.centerZ() - parent.centerZ();
+            if (!followsDirection(island.direction(), dx, dz)) throw new IOException("Expansion position does not follow its direction: " + island.id());
+            for (ExpansionIsland other : previous.values()) if (island.conflicts(other)) throw new IOException("Expansion reservations overlap: " + island.id() + " / " + other.id());
+            previous.put(island.id(), island);
+        }
+        return checked;
+    }
+
+    private static boolean followsDirection(String direction, long dx, long dz) {
+        return switch (direction) {
+            case "north" -> dx == 0 && dz < 0;
+            case "northeast" -> dx > 0 && dz == -dx;
+            case "east" -> dx > 0 && dz == 0;
+            case "southeast" -> dx > 0 && dz == dx;
+            case "south" -> dx == 0 && dz > 0;
+            case "southwest" -> dx < 0 && dz == -dx;
+            case "west" -> dx < 0 && dz == 0;
+            case "northwest" -> dx < 0 && dz == dx;
+            default -> false;
+        };
+    }
+
+    private JsonObject encode(List<ExpansionIsland> entries) {
+        JsonObject root = new JsonObject();
+        root.addProperty("schema", 1); root.addProperty("world_seed", seed); root.addProperty("root_diameter", rootDiameter);
+        JsonArray array = new JsonArray();
+        for (ExpansionIsland island : entries) {
+            JsonObject entry = new JsonObject();
+            entry.addProperty("id", island.id()); entry.addProperty("parent", island.parent());
+            entry.addProperty("direction", island.direction()); entry.addProperty("climate", island.climate());
+            entry.addProperty("diameter", island.diameter()); entry.addProperty("center_x", island.centerX()); entry.addProperty("center_z", island.centerZ());
+            entry.addProperty("seed", island.seed()); entry.addProperty("relief", island.relief()); entry.addProperty("status", island.status());
+            entry.addProperty("generation", island.generation()); array.add(entry);
+        }
+        root.add("islands", array);
+        return root;
+    }
+
+    private static JsonElement readJson(JsonReader reader, int depth) throws IOException {
+        if (depth > 4) throw new IOException("Expansion journal nesting exceeds its schema");
+        return switch (reader.peek()) {
+            case BEGIN_OBJECT -> {
+                reader.beginObject(); JsonObject object = new JsonObject();
+                while (reader.hasNext()) {
+                    String name = reader.nextName();
+                    if (object.has(name)) throw new IOException("Duplicate JSON field: " + name);
+                    if (object.size() >= 16) throw new IOException("Too many journal fields");
+                    object.add(name, readJson(reader, depth + 1));
+                }
+                reader.endObject(); yield object;
+            }
+            case BEGIN_ARRAY -> {
+                reader.beginArray(); JsonArray array = new JsonArray();
+                while (reader.hasNext()) {
+                    if (array.size() >= MAX_ISLANDS) throw new IOException("Too many expansion regions");
+                    array.add(readJson(reader, depth + 1));
+                }
+                reader.endArray(); yield array;
+            }
+            case STRING -> new JsonPrimitive(reader.nextString());
+            case NUMBER -> new JsonPrimitive(new BigDecimal(reader.nextString()));
+            case BOOLEAN -> new JsonPrimitive(reader.nextBoolean());
+            case NULL -> { reader.nextNull(); yield JsonNull.INSTANCE; }
+            default -> throw new IOException("Unexpected expansion journal token");
+        };
+    }
+
+    private static void requireFields(JsonObject value, Set<String> fields) throws IOException {
+        if (!value.keySet().equals(fields)) throw new IOException("Missing or unknown expansion journal fields");
+    }
+    private static String string(JsonObject value, String name) throws IOException {
+        JsonPrimitive primitive = value.getAsJsonPrimitive(name);
+        if (!primitive.isString()) throw new IOException("Expected string field: " + name);
+        return primitive.getAsString();
+    }
+    private static BigDecimal number(JsonObject value, String name) throws IOException {
+        JsonPrimitive primitive = value.getAsJsonPrimitive(name);
+        if (!primitive.isNumber()) throw new IOException("Expected numeric field: " + name);
+        return primitive.getAsBigDecimal();
+    }
+    private static int integer(JsonObject value, String name) throws IOException { return number(value, name).intValueExact(); }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionPlacement.java

@@ -0,0 +1,56 @@
+package fr.koka.sanctuary.expansion;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** Pure placement along a chosen ray; no chunk is inspected or generated here. */
+public final class ExpansionPlacement {
+    public static final int MAX_ATTEMPTS = 32;
+    public static final int MAX_DISTANCE = 100_000;
+    private static final int[] DX = {0, 1, 1, 1, 0, -1, -1, -1};
+    private static final int[] DZ = {-1, -1, 0, 1, 1, 1, 0, -1};
+
+    private ExpansionPlacement() { }
+
+    public static List<ExpansionIsland> candidates(long worldSeed, List<ExpansionIsland> islands,
+            String id, String parentId, String direction, String climate, int diameter, String relief,
+            int minimumDistance) {
+        if (id == null || parentId == null || !id.matches("[a-z][a-z0-9_]{0,31}") || !parentId.matches("[a-z][a-z0-9_]{0,31}"))
+            throw new IllegalArgumentException("invalid_id");
+        if (id.equals("sanctuary")) throw new IllegalArgumentException("reserved_id");
+        if (direction == null || !ExpansionIsland.DIRECTIONS.contains(direction)) throw new IllegalArgumentException("invalid_direction");
+        if (climate == null || !ExpansionIsland.CLIMATES.contains(climate)) throw new IllegalArgumentException("invalid_climate");
+        if (!ExpansionIsland.DIAMETERS.contains(diameter)) throw new IllegalArgumentException("invalid_diameter");
+        if (relief == null || !ExpansionIsland.RELIEFS.contains(relief)) throw new IllegalArgumentException("invalid_relief");
+        validateDistance(minimumDistance);
+        var parent = islands.stream().filter(i -> i.id().equals(parentId)).findFirst()
+            .orElseThrow(() -> new IllegalArgumentException("unknown_island"));
+        if (!parent.status().equals("ready")) throw new IllegalArgumentException("parent_not_ready");
+        int ordinal = ExpansionIsland.DIRECTIONS.indexOf(direction);
+        var sample = new ExpansionIsland(id, parentId, direction, climate, diameter, 0, 0,
+            ExpansionIsland.deriveSeed(worldSeed, id), relief, "reserved", ExpansionIsland.GENERATION);
+        int step = ((parent.reservedRadius() + sample.reservedRadius() + 63) / 16) * 16;
+        boolean diagonal = DX[ordinal] != 0 && DZ[ordinal] != 0;
+        int requestedComponent = (int) Math.ceil(minimumDistance / (diagonal ? Math.sqrt(2) : 1.0) / 16) * 16;
+        int start = Math.max(step, requestedComponent);
+        List<ExpansionIsland> candidates = new ArrayList<>();
+        for (int attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+            long component = (long) start + (long) step * attempt;
+            long x = parent.centerX() + DX[ordinal] * component;
+            long z = parent.centerZ() + DZ[ordinal] * component;
+            if (Math.abs(x) > MAX_DISTANCE || Math.abs(z) > MAX_DISTANCE) break;
+            var candidate = new ExpansionIsland(id, parentId, direction, climate, diameter, (int) x, (int) z,
+                sample.seed(), relief, "reserved", ExpansionIsland.GENERATION);
+            if (islands.stream().noneMatch(candidate::conflicts)) candidates.add(candidate);
+        }
+        return List.copyOf(candidates);
+    }
+
+    public static void validateDistance(int minimumDistance) {
+        if (minimumDistance < 0 || minimumDistance > MAX_DISTANCE) throw new IllegalArgumentException("invalid_distance");
+    }
+
+    public static double distanceFromParent(ExpansionIsland island, ExpansionIsland parent) {
+        return Math.hypot((double) island.centerX() - parent.centerX(), (double) island.centerZ() - parent.centerZ());
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionRelief.java

@@ -0,0 +1,136 @@
+package fr.koka.sanctuary.expansion;
+
+/** Pure alpha.12 coordinate deformation. Existing generators and the lower root island are unchanged. */
+public final class ExpansionRelief {
+    public static final double VERTICAL_ANCHOR = 170.0;
+    public static final double UPPER_START = 160.0;
+    public static final double UPPER_TRANSITION = 144.0;
+    public static final double CRATER_FLOOR = 188.0;
+
+    /** Weights describe geography only; no block, liquid or structure is placed here. */
+    public record Column(double uplift, double canyonWeight, double craterWeight) {}
+
+    private ExpansionRelief() {}
+
+    public static double horizontalScale(ExpansionIsland island) {
+        // The public 724 is rounded; the original population_10 frame is already sqrt(2)*512.
+        return island.origin() ? 1.0 : island.horizontalScale();
+    }
+
+    public static double verticalScale(ExpansionIsland island) {
+        return island.origin() ? 1.0 : Math.max(0.4, Math.sqrt(island.horizontalScale()));
+    }
+
+    public static int sourceX(ExpansionIsland island, int x) {
+        return (int) Math.round(((double) x - island.centerX()) / horizontalScale(island));
+    }
+
+    public static int sourceZ(ExpansionIsland island, int z) {
+        return (int) Math.round(((double) z - island.centerZ()) / horizontalScale(island));
+    }
+
+    /** Reference Y before upper deformation; the inverse projects a source altitude into the island. */
+    public static double referenceY(ExpansionIsland island, double y) {
+        return VERTICAL_ANCHOR + (y - VERTICAL_ANCHOR) / verticalScale(island);
+    }
+
+    public static double worldY(ExpansionIsland island, double referenceY) {
+        return VERTICAL_ANCHOR + (referenceY - VERTICAL_ANCHOR) * verticalScale(island);
+    }
+
+    public static double sourceY(ExpansionIsland island, Column column, double y) {
+        double reference = referenceY(island, y);
+        // |uplift| <= 48 and max smoothstep slope = 1.5/144, so this map is strictly
+        // increasing. The whole source field, including its upper envelope, moves together.
+        return reference - column.uplift() * smoothstep((reference - UPPER_START) / UPPER_TRANSITION);
+    }
+
+    /** Additional cuts leave the source void empty, and never produce an unbounded positive density. */
+    public static float sculpt(ExpansionIsland island, Column column, double y, float source) {
+        if (source <= 0) return source;
+        double reference = referenceY(island, y);
+        double canyon = 2.1 * column.canyonWeight() * smoothstep((reference - 120.0) / 34.0);
+        double crater = 2.1 * column.craterWeight() * smoothstep((reference - CRATER_FLOOR) / 14.0);
+        return (float) Math.clamp(source - Math.max(canyon, crater), -1.0, 1.0);
+    }
+
+    /** True only in the inner volcanic bowl; the material pass may use this without guessing from blocks. */
+    public static boolean inCrater(ExpansionIsland island, int x, int z) {
+        return island.relief().equals("volcano") && column(island, x, z).craterWeight() >= 0.95;
+    }
+
+    public static int craterFloorY(ExpansionIsland island) {
+        return (int) Math.floor(worldY(island, CRATER_FLOOR));
+    }
+
+    public static Column column(ExpansionIsland island, int x, int z) {
+        double dx = (double) x - island.centerX(), dz = (double) z - island.centerZ();
+        double radius = island.radius();
+        double radial = Math.hypot(dx, dz) / radius;
+        double edge = 1.0 - smoothstep((radial - 0.70) / 0.30);
+        if (edge <= 0) return new Column(0, 0, 0);
+
+        long seed = island.seed();
+        double wavelength = Math.max(16.0, radius * 0.40);
+        double broad = noise(seed, dx / wavelength, dz / wavelength);
+        double detail = noise(seed ^ 0xA12DE7A1L, dx / (wavelength * 0.43), dz / (wavelength * 0.43));
+        double uplift;
+        double canyon = 0.0, crater = 0.0;
+        switch (island.relief()) {
+            case "natural" -> {
+                double ridge = Math.pow(1.0 - Math.abs(broad), 4.0);
+                uplift = Math.clamp(12.0 * broad + 5.0 * detail + 10.0 * Math.max(0.0, ridge - 0.5), -20.0, 20.0);
+            }
+            case "peaks" -> {
+                double ridge = Math.pow(1.0 - Math.abs(broad), 3.0);
+                uplift = Math.clamp(10.0 * detail + 44.0 * ridge, -16.0, 48.0);
+            }
+            case "canyon" -> {
+                uplift = 8.0 * detail + 16.0 * Math.max(0.0, broad);
+                double angle = unit(seed ^ 0xCA1201L) * Math.PI * 2.0;
+                double along = dx * Math.cos(angle) + dz * Math.sin(angle);
+                double sideways = -dx * Math.sin(angle) + dz * Math.cos(angle);
+                double phase = unit(seed ^ 0xCA1202L) * Math.PI * 2.0;
+                double curve = radius * 0.085 * (Math.sin(along / (radius * 0.36) + phase) - Math.sin(phase));
+                double halfWidth = Math.clamp(radius * 0.035, 2.25, 12.0);
+                canyon = (1.0 - smoothstep((Math.abs(sideways - curve) - halfWidth) / (halfWidth * 0.75)))
+                    * (1.0 - smoothstep((Math.abs(along) / radius - 0.62) / 0.20));
+            }
+            case "volcano" -> {
+                // A raised annulus surrounds a depressed centre; this profile changes the
+                // silhouette and cuts an actual crater, independently of its later palette.
+                double coneRadius = radial + 0.018 * detail;
+                double cone = Math.pow(Math.max(0.0, 1.0 - coneRadius / 0.68), 1.35);
+                double hollow = 1.0 - smoothstep((radial - 0.08) / 0.15);
+                uplift = Math.clamp(48.0 * cone * (1.0 - 0.90 * hollow) + 3.0 * detail, -6.0, 48.0);
+                crater = 1.0 - smoothstep((radial - 0.10) / 0.09);
+            }
+            default -> throw new IllegalArgumentException("Unknown relief " + island.relief());
+        }
+        return new Column(uplift * edge, canyon * edge, crater * edge);
+    }
+
+    /** Smooth coherent value noise: no mutable RNG, global map, chunk boundaries or order dependence. */
+    private static double noise(long seed, double x, double z) {
+        long ix = (long) Math.floor(x), iz = (long) Math.floor(z);
+        double tx = smoothstep(x - ix), tz = smoothstep(z - iz);
+        double a = lattice(seed, ix, iz), b = lattice(seed, ix + 1, iz);
+        double c = lattice(seed, ix, iz + 1), d = lattice(seed, ix + 1, iz + 1);
+        return (a + (b - a) * tx) + ((c + (d - c) * tx) - (a + (b - a) * tx)) * tz;
+    }
+
+    private static double lattice(long seed, long x, long z) {
+        return unit(seed ^ x * 0x9e3779b97f4a7c15L ^ z * 0x632be59bd9b4e019L) * 2.0 - 1.0;
+    }
+
+    private static double unit(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return ((value ^ (value >>> 31)) >>> 11) * 0x1.0p-53;
+    }
+
+    private static double smoothstep(double value) {
+        double t = Math.clamp(value, 0.0, 1.0);
+        return t * t * (3.0 - 2.0 * t);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionRuntime.java

@@ -0,0 +1,270 @@
+package fr.koka.sanctuary.expansion;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.io.IOException;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerLifecycleEvents;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerTickEvents;
+import net.fabricmc.fabric.api.event.lifecycle.v1.ServerLevelEvents;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Registry;
+import net.minecraft.core.registries.BuiltInRegistries;
+import net.minecraft.network.chat.Component;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.server.level.TicketType;
+import net.minecraft.world.level.ChunkPos;
+import net.minecraft.world.level.Level;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.storage.LevelResource;
+
+/** Server-owned append-only admission and bounded preparation queue. No existing chunk is regenerated. */
+public final class ExpansionRuntime {
+    private static final Map<ServerLevel, Session> SESSIONS = new HashMap<>();
+    private static final TicketType PREPARATION = new TicketType(0L, 2 | 8);
+    private ExpansionRuntime() {}
+    public static void register() {
+        Registry.register(BuiltInRegistries.TICKET_TYPE, SanctuaryMod.id("expansion_preparation"), PREPARATION);
+        ServerLevelEvents.LOAD.register((server, level) -> {
+            if (!(level.getChunkSource().getGenerator() instanceof ExpansionChunkGenerator generator)) return;
+            if (level.dimension() != Level.OVERWORLD) throw new IllegalStateException("The expansion laboratory is Overworld only");
+            try {
+                var directory = server.getWorldPath(LevelResource.ROOT).resolve("data/" + generator.journalDirectory());
+                if (server.getWorldData().overworldData().isInitialized()
+                        && !java.nio.file.Files.isDirectory(directory, java.nio.file.LinkOption.NOFOLLOW_LINKS))
+                    throw new IOException("Initialized laboratory world is missing its expansion journal directory");
+                var journal = new ExpansionJournal(directory, level.getSeed(), generator.initialDiameter(), generator.rootGeneration());
+                generator.initialize(level, journal.islands());
+                var session = new Session(level, generator, journal);
+                SESSIONS.put(level, session);
+                for (var island : journal.islands()) if (island.status().equals("reserved")) session.enqueue(island);
+            } catch (IOException e) {
+                throw new IllegalStateException("Cannot safely open the Sanctuary expansion journal", e);
+            }
+        });
+        ServerTickEvents.END_LEVEL_TICK.register(level -> {
+            Session session = SESSIONS.get(level);
+            if (session != null) session.tick();
+        });
+        ServerLevelEvents.UNLOAD.register((server, level) -> {
+            Session session = SESSIONS.remove(level);
+            if (session != null) session.releaseTicket();
+        });
+        ServerLifecycleEvents.SERVER_STOPPED.register(server -> SESSIONS.clear());
+    }
+    public static Session session(ServerLevel level) {
+        Session session = SESSIONS.get(level);
+        if (session == null) throw new IllegalArgumentException("laboratory_required");
+        return session;
+    }
+    public static final class Session {
+        private final ServerLevel level;
+        private final ExpansionChunkGenerator generator;
+        private final ExpansionJournal journal;
+        private final ArrayDeque<Job> jobs = new ArrayDeque<>();
+        private String failure = "";
+        private boolean journalUnavailableNotified;
+        private Session(ServerLevel level, ExpansionChunkGenerator generator, ExpansionJournal journal) {
+            this.level = level; this.generator = generator; this.journal = journal;
+        }
+        public List<ExpansionIsland> islands() { return journal.islands(); }
+        public ExpansionIsland island(String id) {
+            return islands().stream().filter(i -> i.id().equals(id)).findFirst().orElseThrow(() -> new IllegalArgumentException("unknown_island"));
+        }
+        public String progress() {
+            Job job = jobs.peek();
+            return job == null ? (failure.isEmpty() ? "idle" : failure) : job.island.id() + ": " + job.index + "/" + job.chunks.size();
+        }
+        public ExpansionIsland candidate(String id, String parentId, String direction, String climate, int diameter, String relief) {
+            return candidate(id, parentId, direction, climate, diameter, relief, 0);
+        }
+        public ExpansionIsland candidate(String id, String parentId, String direction, String climate, int diameter, String relief,
+                int minimumDistance) {
+            return ExpansionPlacement.candidates(level.getSeed(), islands(), id, parentId, direction, climate, diameter, relief, minimumDistance)
+                .stream().findFirst().orElseThrow(() -> new IllegalArgumentException("no_free_space"));
+        }
+        public ExpansionIsland create(String id, String parent, String direction, String climate, int diameter, String relief) throws IOException {
+            return create(id, parent, direction, climate, diameter, relief, 0);
+        }
+        public ExpansionIsland create(String id, String parent, String direction, String climate, int diameter, String relief,
+                int minimumDistance) throws IOException {
+            long deadline = ExpansionAdmission.searchDeadline();
+            requireHealthyJournal();
+            ExpansionPlacement.validateDistance(minimumDistance);
+            var existing = islands().stream().filter(i -> i.id().equals(id)).findFirst();
+            if (existing.isPresent()) {
+                var value = existing.get();
+                if (!value.parent().equals(parent) || !value.direction().equals(direction) || !value.climate().equals(climate)
+                        || value.diameter() != diameter || !value.relief().equals(relief)
+                        || (minimumDistance > 0 && ExpansionPlacement.distanceFromParent(value, island(parent)) < minimumDistance))
+                    throw new IllegalArgumentException("id_conflict");
+                return value;
+            }
+            if (islands().size() >= 64) throw new IllegalArgumentException("island_limit");
+            var candidates = ExpansionPlacement.candidates(level.getSeed(), islands(), id, parent, direction, climate, diameter, relief, minimumDistance);
+            for (var value : candidates) {
+                ExpansionAdmission.checkDeadline(deadline);
+                try {
+                    // Existing void is preserved: only proven occupation advances along the same ray.
+                    ExpansionAdmission.verify(level, value, deadline);
+                    if (probe(value) == null) throw new IllegalArgumentException("no_ground");
+                    var next = new ArrayList<>(islands());
+                    next.add(value);
+                    ExpansionAdmission.verifyHolders(level, value, deadline);
+                    commitJournal(next); // Durability and re-read come before worldgen sees the island.
+                    generator.setIslands(journal.islands());
+                    failure = "";
+                    enqueue(value);
+                    return value;
+                } catch (ExpansionAdmission.OccupiedException occupied) {
+                    // IO failures, timeouts and unsuitable terrain stop this request without a new draw.
+                } finally {
+                    generator.discardUnpublishedContext(value);
+                }
+            }
+            ExpansionAdmission.checkDeadline(deadline);
+            throw new IllegalArgumentException("no_free_space");
+        }
+        public void resume(String id) {
+            requireHealthyJournal();
+            var island = island(id);
+            if (!island.status().equals("reserved")) return;
+            failure = "";
+            enqueue(island);
+        }
+        private void enqueue(ExpansionIsland island) {
+            if (jobs.stream().noneMatch(j -> j.island.id().equals(island.id()))) jobs.add(new Job(island));
+        }
+        private void requireHealthyJournal() {
+            if (!journal.healthy()) {
+                stopForJournalFailure(null);
+                throw new IllegalStateException("journal_unavailable");
+            }
+        }
+        private void commitJournal(List<ExpansionIsland> next) throws IOException {
+            try {
+                journal.commit(next);
+            } catch (IOException exception) {
+                if (!journal.healthy()) {
+                    stopForJournalFailure(exception);
+                    throw new IllegalStateException("journal_unavailable", exception);
+                }
+                throw exception;
+            }
+        }
+        private void stopForJournalFailure(Throwable cause) {
+            releaseTicket();
+            jobs.clear(); // Saved reservations remain intact and are enqueued only after a verified reload.
+            failure = "journal_unavailable: reload required";
+            if (journalUnavailableNotified) return;
+            journalUnavailableNotified = true;
+            SanctuaryMod.LOGGER.error("Expansion journal unavailable; all preparation stopped and reload is required", cause);
+            for (var player : level.players()) if (player.permissions().hasPermission(net.minecraft.server.permissions.Permissions.COMMANDS_GAMEMASTER))
+                player.sendSystemMessage(Component.translatable("sanctuary.expansion.journal_unavailable"));
+        }
+        /** Base-terrain prospecting is read-only: no chunk requests or writes. */
+        public BlockPos probe(ExpansionIsland island) {
+            var delegate = generator.delegate(island);
+            var random = generator.randomState(island);
+            int stride = Math.max(4, island.diameter() / 32);
+            int limit = Math.max(stride, (int) (island.radius() * 0.75));
+            for (int r = 0; r <= limit; r += stride) for (int x = -r; x <= r; x += stride) for (int z = -r; z <= r; z += stride) {
+                if (Math.max(Math.abs(x), Math.abs(z)) != r) continue;
+                int wx = island.centerX() + x, wz = island.centerZ() + z;
+                int y = delegate.getBaseHeight(wx, wz, Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, level, random);
+                if (y > 24 && y < 365) return new BlockPos(wx, y, wz);
+            }
+            return null;
+        }
+        public BlockPos landing(String id) {
+            var island = island(id);
+            if (!island.status().equals("ready")) throw new IllegalArgumentException("not_ready");
+            int stride = Math.max(4, island.diameter() / 32);
+            int limit = (int) (island.radius() * 0.85);
+            for (int r = 0; r <= limit; r += stride) for (int x = -r; x <= r; x += stride) for (int z = -r; z <= r; z += stride) {
+                if (Math.max(Math.abs(x), Math.abs(z)) != r) continue;
+                int wx = island.centerX() + x, wz = island.centerZ() + z;
+                // Only this already-open island is loaded; no block is changed for teleportation.
+                level.getChunk(wx >> 4, wz >> 4);
+                int top = level.getHeight(Heightmap.Types.MOTION_BLOCKING_NO_LEAVES, wx, wz);
+                for (int y = top; y > 24; y--) {
+                    var pos = new BlockPos(wx, y, wz);
+                    if (safeLanding(level, pos)) return pos;
+                }
+            }
+            throw new IllegalArgumentException("no_landing");
+        }
+        private void releaseTicket() {
+            Job job = jobs.peek();
+            if (job != null && job.ticket != null) {
+                level.getChunkSource().removeTicketWithRadius(PREPARATION, job.ticket, 0);
+                job.ticket = null;
+            }
+        }
+        private void tick() {
+            if (!journal.healthy()) {
+                stopForJournalFailure(null);
+                return;
+            }
+            Job job = jobs.peek();
+            if (job == null) return;
+            try {
+                if (job.pending != null) {
+                    if (!job.pending.isDone()) return;
+                    job.pending.join();
+                    if (level.getChunkSource().getChunkNow(job.ticket.x(), job.ticket.z()) == null) throw new IllegalStateException("Chunk did not reach FULL");
+                    releaseTicket();
+                    job.pending = null;
+                    job.index++;
+                }
+                if (job.index == job.chunks.size()) {
+                    var next = islands().stream().map(i -> i.id().equals(job.island.id()) ? i.ready() : i).toList();
+                    commitJournal(next);
+                    generator.setIslands(journal.islands());
+                    jobs.remove();
+                    SanctuaryMod.LOGGER.info("Expansion {} ready: {} FULL chunks", job.island.id(), job.index);
+                    for (var player : level.players()) if (player.permissions().hasPermission(net.minecraft.server.permissions.Permissions.COMMANDS_GAMEMASTER))
+                        player.sendSystemMessage(Component.translatable("sanctuary.expansion.ready", job.island.id(), job.index, job.island.id()));
+                    return;
+                }
+                job.ticket = job.chunks.get(job.index);
+                job.pending = level.getChunkSource().addTicketAndLoadWithRadius(PREPARATION, job.ticket, 0);
+            } catch (Exception exception) {
+                if (!journal.healthy()) {
+                    stopForJournalFailure(exception);
+                    return;
+                }
+                releaseTicket();
+                failure = job.island.id() + ": " + exception.getMessage();
+                jobs.remove();
+                SanctuaryMod.LOGGER.error("Expansion preparation stopped; reservation retained for resume: {}", job.island.id(), exception);
+            }
+        }
+    }
+    private static final class Job {
+        final ExpansionIsland island;
+        final List<ChunkPos> chunks = new ArrayList<>();
+        int index;
+        ChunkPos ticket;
+        CompletableFuture<?> pending;
+        Job(ExpansionIsland island) {
+            this.island = island;
+            int radius = island.terrainRadius() + ExpansionIsland.DECORATION_MARGIN;
+            for (int x = (island.centerX() - radius) >> 4; x <= (island.centerX() + radius) >> 4; x++)
+                for (int z = (island.centerZ() - radius) >> 4; z <= (island.centerZ() + radius) >> 4; z++) chunks.add(new ChunkPos(x, z));
+        }
+    }
+    public static boolean safeLanding(ServerLevel level, BlockPos feet) {
+        var floor = level.getBlockState(feet.below());
+        return floor.isCollisionShapeFullBlock(level, feet.below())
+            && floor.getFluidState().isEmpty()
+            && !floor.is(net.minecraft.tags.BlockTags.LEAVES)
+            && !floor.is(net.minecraft.world.level.block.Blocks.MAGMA_BLOCK)
+            && !floor.is(net.minecraft.world.level.block.Blocks.CACTUS)
+            && level.getBlockState(feet).isAir() && level.getBlockState(feet.above()).isAir();
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionStructures.java

@@ -0,0 +1,191 @@
+package fr.koka.sanctuary.expansion;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import net.minecraft.core.Holder;
+import net.minecraft.core.BlockPos;
+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.Level;
+import net.minecraft.world.level.NoiseColumn;
+import net.minecraft.world.level.StructureManager;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.chunk.ChunkAccess;
+import net.minecraft.world.level.chunk.ChunkGeneratorStructureState;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+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.templatesystem.StructureTemplateManager;
+
+/** Plan native starts before terrain and references; decoration and structure persistence remain vanilla. */
+public final class ExpansionStructures {
+    private static final boolean DIAGNOSTICS = Boolean.getBoolean("sanctuary.test.expansion")
+        || Boolean.getBoolean("sanctuary.expansion.structureDiagnostics");
+    private static final int CELL_CHUNKS = 8;
+    private static final List<String> VILLAGES = List.of("village_plains", "village_desert", "village_savanna", "village_snowy", "village_taiga");
+    private static final List<String> LANDMARKS = List.of("desert_pyramid", "jungle_pyramid", "swamp_hut");
+    private static final List<String> CAMPS = List.of(
+        "forest", "birch_forest", "old_growth_birch_forest", "old_growth_pine_taiga", "old_growth_spruce_taiga",
+        "pale_garden", "savanna", "dappled_forest", "snowy_taiga", "cherry_grove", "swamp", "sparse_jungle",
+        "meadow", "wooded_badlands", "flower_forest", "windswept_forest", "taiga", "bamboo_jungle"
+    );
+
+    private ExpansionStructures() {}
+
+    public static void generate(ExpansionChunkGenerator generator, RegistryAccess registries,
+            ChunkGeneratorStructureState state, StructureManager manager, ChunkAccess chunk,
+            StructureTemplateManager templates, ResourceKey<Level> level) {
+        if (!manager.shouldGenerateStructures()) return;
+        int blockX = chunk.getPos().getMiddleBlockX(), blockZ = chunk.getPos().getMiddleBlockZ();
+        ExpansionIsland island = generator.islandAt(blockX, blockZ);
+        if (island == null) return;
+        long roll = candidateRoll(island, chunk.getPos().x(), chunk.getPos().z());
+        if (roll == 0 || Long.remainderUnsigned(roll, 100) >= 72) return;
+
+        RandomState randomState = generator.randomState(island);
+        int surfaceY = generator.getBaseHeight(blockX, blockZ, Heightmap.Types.WORLD_SURFACE_WG, chunk, randomState) - 1;
+        if (surfaceY < 48) {
+            diagnostic(island, chunk, "no-surface", "height=" + surfaceY);
+            return;
+        }
+        var sampler = randomState.createClimateSampler(SamplerContext.builder().enableCaches().build());
+        Holder<Biome> biome = generator.structureBiome(generator.getBiomeSource().createResolver(sampler)
+            .getNoiseBiome(blockX >> 2, surfaceY >> 2, blockZ >> 2));
+        var registry = registries.lookupOrThrow(Registries.STRUCTURE);
+        List<Holder<Structure>> villages = new ArrayList<>();
+        // Villages remain optional and are never squeezed into the small formats.
+        if (island.diameter() >= 256 && Long.remainderUnsigned(roll >>> 9, 100) < 36) {
+            for (String name : VILLAGES) addMatching(villages, registry.get(Identifier.fromNamespaceAndPath("minecraft", name)).orElse(null), biome);
+        }
+        List<Holder<Structure>> landmarks = new ArrayList<>();
+        for (String name : LANDMARKS) addMatching(landmarks, registry.get(Identifier.fromNamespaceAndPath("minecraft", name)).orElse(null), biome);
+        for (String suffix : CAMPS) addMatching(landmarks,
+            registry.get(Identifier.fromNamespaceAndPath("minecraft", "abandoned_camp_" + suffix)).orElse(null), biome);
+        if (villages.isEmpty() && landmarks.isEmpty()) {
+            diagnostic(island, chunk, "no-compatible-structure", "biome=" + biome.unwrapKey().orElseThrow().identifier() + " height=" + surfaceY);
+            return;
+        }
+        // An eligible but unsupported village must not suppress a smaller compatible camp.
+        // Both groups keep their original biome and foundation checks; one accepted start ends the site.
+        for (List<Holder<Structure>> candidates : List.of(villages, landmarks)) {
+            if (candidates.isEmpty()) continue;
+            int selectedIndex = (int) Long.remainderUnsigned(roll >>> 19, candidates.size());
+            for (int attempt = 0; attempt < candidates.size(); attempt++) {
+                Holder<Structure> selected = candidates.get((selectedIndex + attempt) % candidates.size());
+                Structure structure = selected.value();
+                StructureStart previous = manager.getStartForStructure(structure, chunk);
+                if (previous != null && previous.isValid()) return;
+                String name = selected.unwrapKey().orElseThrow().identifier().toString();
+                StructureStart start = structure.generate(selected, level, registries, generator, generator.getBiomeSource(),
+                    sampler, randomState, templates, island.seed(), chunk.getPos(), previous == null ? 0 : previous.getReferences(),
+                    chunk, candidateBiome -> structure.biomes().contains(generator.structureBiome(candidateBiome)));
+                if (!start.isValid()) {
+                    diagnostic(island, chunk, "native-rejected", name + " biome=" + biome.unwrapKey().orElseThrow().identifier() + " height=" + surfaceY);
+                    continue;
+                }
+                boolean temple = name.equals("minecraft:desert_pyramid") || name.equals("minecraft:jungle_pyramid");
+                String rejection = supportRejection(generator, island, chunk, randomState, start, temple);
+                if (rejection != null) {
+                    diagnostic(island, chunk, "support-rejected", name + " " + rejection + " bounds=" + start.getBoundingBox());
+                    continue;
+                }
+                manager.setStartForStructure(structure, start, chunk);
+                diagnostic(island, chunk, "accepted", name + " pieces=" + start.getPieces().size() + " bounds=" + start.getBoundingBox());
+                return;
+            }
+        }
+    }
+
+    private static void addMatching(List<Holder<Structure>> candidates, Holder<Structure> structure, Holder<Biome> biome) {
+        if (structure != null && structure.value().biomes().contains(biome)) candidates.add(structure);
+    }
+
+    /** One possible start in each 128-block square, salted by the persisted island seed. */
+    private static long candidateRoll(ExpansionIsland island, int chunkX, int chunkZ) {
+        int localX = chunkX - Math.floorDiv(island.centerX(), 16), localZ = chunkZ - Math.floorDiv(island.centerZ(), 16);
+        int cellX = Math.floorDiv(localX, CELL_CHUNKS), cellZ = Math.floorDiv(localZ, CELL_CHUNKS);
+        long roll = mix(island.seed() ^ 0xA1257A0C7L ^ (cellX * 0x9E3779B97F4A7C15L) ^ (cellZ * 0xC2B2AE3D27D4EB4FL));
+        if (Math.floorMod(localX, CELL_CHUNKS) != (int) Long.remainderUnsigned(roll >>> 3, CELL_CHUNKS)
+                || Math.floorMod(localZ, CELL_CHUNKS) != (int) Long.remainderUnsigned(roll >>> 12, CELL_CHUNKS)) return 0;
+        return roll;
+    }
+
+    private static String supportRejection(ExpansionChunkGenerator generator, ExpansionIsland island, ChunkAccess chunk,
+            RandomState randomState, StructureStart start, boolean temple) {
+        // Native beard adaptation already expands this box by 12 blocks when applicable.
+        BoundingBox total = start.getBoundingBox();
+        if (island.origin() && generator instanceof fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator unified) {
+            var binding = unified.starterContext();
+            int centreX = (total.minX() + total.maxX()) / 2, centreZ = (total.minZ() + total.maxZ()) / 2;
+            int radius = Math.max(total.getXSpan(), total.getZSpan()) / 2 + 3;
+            if (fr.koka.sanctuary.worldgen.PopulationHydrologyRuntime.protects(binding.generator(), binding.random(),
+                    new BlockPos(centreX, total.minY(), centreZ), radius, total.getYSpan() + 16, 26)) return "protected-hydrology";
+        }
+        if (!inside(island, total.minX(), total.minZ(), 4) || !inside(island, total.maxX(), total.minZ(), 4)
+                || !inside(island, total.minX(), total.maxZ(), 4) || !inside(island, total.maxX(), total.maxZ(), 4)) return "outside-island";
+        if (total.minY() < chunk.getMinY() || total.maxY() > chunk.getMaxY() - 4) return "outside-height";
+        Map<Long, Ground> columns = new HashMap<>();
+        int depth = temple ? 24 : 12;
+        int allMin = Integer.MAX_VALUE, allMax = Integer.MIN_VALUE;
+        for (StructurePiece piece : start.getPieces()) {
+            BoundingBox box = piece.getBoundingBox();
+            int low = Integer.MAX_VALUE, high = Integer.MIN_VALUE;
+            for (int z = box.minZ() - 1; z <= box.maxZ() + 1; z++) {
+                for (int x = box.minX() - 1; x <= box.maxX() + 1; x++) {
+                    if (!inside(island, x, z, 4)) return "footprint-outside-island at " + x + "," + z;
+                    long key = ((long) x << 32) ^ (z & 0xffffffffL);
+                    Ground ground = columns.get(key);
+                    if (ground == null) {
+                        ground = ground(generator, chunk, randomState, x, z);
+                        columns.put(key, ground);
+                    }
+                    if (ground.top() < 48 || ground.thickness() < depth)
+                        return "foundation at " + x + "," + z + " top=" + ground.top() + " thickness=" + ground.thickness() + " required=" + depth;
+                    low = Math.min(low, ground.top());
+                    high = Math.max(high, ground.top());
+                    if (high - low > (temple ? 4 : 8)) return "piece-slope=" + (high - low) + " low=" + low + " high=" + high;
+                }
+            }
+            allMin = Math.min(allMin, low);
+            allMax = Math.max(allMax, high);
+            if (allMax - allMin > 20) return "site-slope=" + (allMax - allMin);
+        }
+        return null;
+    }
+
+    private static void diagnostic(ExpansionIsland island, ChunkAccess chunk, String reason, String details) {
+        if (DIAGNOSTICS) SanctuaryMod.LOGGER.info("Expansion structure {} seed {} chunk {},{} {}: {}",
+            island.id(), island.seed(), chunk.getPos().x(), chunk.getPos().z(), reason, details);
+    }
+
+    private static Ground ground(ExpansionChunkGenerator generator, ChunkAccess chunk, RandomState randomState, int x, int z) {
+        NoiseColumn column = generator.getBaseColumn(x, z, chunk, randomState);
+        int y = chunk.getMaxY();
+        while (y >= chunk.getMinY() && column.getBlock(y).isAir()) y--;
+        int top = y;
+        // A wet, unsupported or hollow foundation is rejected before any start is saved.
+        while (y >= chunk.getMinY() && top - y < 24 && column.getBlock(y).isSolid() && column.getBlock(y).getFluidState().isEmpty()) y--;
+        return new Ground(top, top - y);
+    }
+
+    private static boolean inside(ExpansionIsland island, int x, int z, int margin) {
+        return Math.hypot((double) x - island.centerX(), (double) z - island.centerZ()) < island.terrainRadius() - margin;
+    }
+
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+
+    private record Ground(int top, int thickness) {}
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/expansion/ExpansionTerrain.java

@@ -0,0 +1,127 @@
+package fr.koka.sanctuary.expansion;
+
+import java.util.EnumSet;
+import net.minecraft.core.BlockPos;
+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.levelgen.Heightmap;
+
+/** Alpha.12 material pass on fresh terrain only. It never builds a floor, dam or extra island mass. */
+public final class ExpansionTerrain {
+    private ExpansionTerrain() {}
+
+    /** Called once after the delegate finishes terrain and before decoration. No adjacent chunk is read. */
+    public static void apply(ExpansionIsland island, ChunkAccess chunk) {
+        boolean volcanic = island.relief().equals("volcano");
+        boolean wet = !volcanic && (island.origin() || island.climate().equals("humid")
+            || island.climate().equals("tropical") || island.climate().equals("cold_humid"));
+        if (!volcanic && !wet) return;
+
+        // Find against the original stone/deepslate before the volcanic palette replaces it.
+        // This one seed-owned column is the only fluid candidate for the entire island.
+        BlockPos pocket = retainedPocket(island, chunk, volcanic);
+        if (volcanic) volcanicPalette(island, chunk);
+        if (pocket == null) return;
+
+        chunk.setBlockState(pocket, (volcanic ? Blocks.LAVA : Blocks.WATER).defaultBlockState(), 0);
+        chunk.markPosForPostProcessing(pocket);
+        Heightmap.primeHeightmaps(chunk, EnumSet.of(Heightmap.Types.WORLD_SURFACE_WG,
+            Heightmap.Types.OCEAN_FLOOR_WG));
+    }
+
+    /** A diagnostic can inspect this column; it is a candidate, never a promise of fluid. Y is unspecified. */
+    public static BlockPos pocketCandidate(ExpansionIsland island) {
+        long seed = island.seed() ^ 0xA12F101DL;
+        int dx, dz;
+        if (island.relief().equals("volcano")) {
+            // Even a 64-block island keeps (+/-2,+/-2) in the inner bowl. The maximum
+            // offset is eleven, keeping both the candidate and its walls inside a chunk.
+            int maximum = Math.clamp((int) Math.floor(island.radius() * 0.045), 2, 11);
+            dx = (2 + (int) Math.floor(unit(seed) * (maximum - 1))) * (unit(seed + 1) < 0.5 ? -1 : 1);
+            dz = (2 + (int) Math.floor(unit(seed + 2) * (maximum - 1))) * (unit(seed + 3) < 0.5 ? -1 : 1);
+        } else {
+            dx = (int) Math.round(island.radius() * (0.16 + 0.18 * unit(seed))) * (unit(seed + 1) < 0.5 ? -1 : 1);
+            dz = (int) Math.round(island.radius() * (0.16 + 0.18 * unit(seed + 2))) * (unit(seed + 3) < 0.5 ? -1 : 1);
+        }
+        int x = insideChunk(island.centerX() + dx), z = insideChunk(island.centerZ() + dz);
+        return new BlockPos(x, 0, z);
+    }
+
+    private static BlockPos retainedPocket(ExpansionIsland island, ChunkAccess chunk, boolean volcanic) {
+        BlockPos column = pocketCandidate(island);
+        int x = column.getX(), z = column.getZ();
+        if ((x >> 4) != chunk.getPos().x() || (z >> 4) != chunk.getPos().z()
+            || !island.contains(x, z) || (volcanic && !ExpansionRelief.inCrater(island, x, z))) return null;
+
+        int bottom = Math.max(chunk.getMinY() + 1, (int) Math.ceil(ExpansionRelief.worldY(island, volcanic ? 176.0 : 160.0)));
+        BlockPos.MutableBlockPos position = new BlockPos.MutableBlockPos();
+        for (int y = chunk.getMinY() + chunk.getHeight() - 2; y >= bottom; y--) {
+            position.set(x, y, z);
+            BlockState current = chunk.getBlockState(position);
+            if (current.isAir()) continue;
+            // Stop at the first real surface. Do not drill through soil, vegetation,
+            // overhangs or an earlier fluid to reach an otherwise eligible cave below.
+            if (!naturalRock(current) || !chunk.getBlockState(position.above()).isAir()) return null;
+            BlockPos candidate = position.immutable();
+            if (sealedSupport(chunk, candidate.below(), volcanic)
+                && sealedSupport(chunk, candidate.north(), volcanic)
+                && sealedSupport(chunk, candidate.south(), volcanic)
+                && sealedSupport(chunk, candidate.west(), volcanic)
+                && sealedSupport(chunk, candidate.east(), volcanic)) return candidate;
+            return null;
+        }
+        return null;
+    }
+
+    private static boolean sealedSupport(ChunkAccess chunk, BlockPos position, boolean volcanic) {
+        BlockState support = chunk.getBlockState(position);
+        // Full collision alone also accepts sand or ice, whose later falling/melting
+        // would breach a pocket. Restrict all five walls to stable natural rock.
+        boolean rock = naturalRock(support) || support.is(Blocks.ANDESITE) || support.is(Blocks.DIORITE)
+            || support.is(Blocks.GRANITE) || support.is(Blocks.TUFF) || support.is(Blocks.CALCITE)
+            || support.is(Blocks.BASALT) || support.is(Blocks.SMOOTH_BASALT) || support.is(Blocks.BLACKSTONE)
+            || support.is(Blocks.OBSIDIAN) || support.is(Blocks.MAGMA_BLOCK);
+        return rock && support.getFluidState().isEmpty() && (!volcanic || !support.ignitedByLava())
+            && support.isCollisionShapeFullBlock(chunk, position);
+    }
+
+    private static void volcanicPalette(ExpansionIsland island, ChunkAccess chunk) {
+        int minX = chunk.getPos().getMinBlockX(), minZ = chunk.getPos().getMinBlockZ();
+        int minY = Math.max(chunk.getMinY(), (int) Math.floor(ExpansionRelief.worldY(island, 160.0)));
+        int maxY = Math.min(chunk.getMinY() + chunk.getHeight() - 1,
+            (int) Math.ceil(ExpansionRelief.worldY(island, 330.0)));
+        int patchSize = Math.clamp(island.diameter() / 64, 2, 8);
+        BlockPos.MutableBlockPos position = new BlockPos.MutableBlockPos();
+        for (int x = minX; x < minX + 16; x++) for (int z = minZ; z < minZ + 16; z++) {
+            double radial = Math.hypot((double) x - island.centerX(), (double) z - island.centerZ()) / island.radius();
+            if (radial >= 0.62 || !island.contains(x, z)) continue;
+            long column = island.seed() ^ Math.floorDiv(x - island.centerX(), patchSize) * 0x9e3779b97f4a7c15L
+                ^ Math.floorDiv(z - island.centerZ(), patchSize) * 0x632be59bd9b4e019L;
+            for (int y = minY; y <= maxY; y++) {
+                position.set(x, y, z);
+                if (!naturalRock(chunk.getBlockState(position))) continue;
+                double pick = unit(column ^ Math.floorDiv(y, 4) * 0x94d049bb133111ebL);
+                boolean hot = radial < 0.28 && ExpansionRelief.referenceY(island, y) <= 230.0;
+                BlockState replacement = hot && pick < 0.055 ? Blocks.OBSIDIAN.defaultBlockState()
+                    : hot && pick < 0.14 ? Blocks.MAGMA_BLOCK.defaultBlockState()
+                    : pick < 0.44 ? Blocks.BLACKSTONE.defaultBlockState() : Blocks.BASALT.defaultBlockState();
+                chunk.setBlockState(position, replacement, 0);
+            }
+        }
+    }
+
+    private static boolean naturalRock(BlockState state) {
+        return state.is(Blocks.STONE) || state.is(Blocks.DEEPSLATE);
+    }
+
+    private static int insideChunk(int coordinate) {
+        return (coordinate & ~15) + Math.clamp(coordinate & 15, 1, 14);
+    }
+
+    private static double unit(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return ((value ^ (value >>> 31)) >>> 11) * 0x1.0p-53;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/CavernSpringOutletMixin.java

@@ -0,0 +1,37 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.worldgen.CavernSpringOutlets;
+import fr.koka.sanctuary.worldgen.PopulationSpringOutlets;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.chunk.LevelChunk;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
+
+/** Finish only pending generation markers; completed saved chunks are never repaired on reload. */
+@Mixin(LevelChunk.class)
+public abstract class CavernSpringOutletMixin {
+    @Unique
+    private PopulationSpringOutlets.Pending sanctuary$pendingPopulationOutlets = PopulationSpringOutlets.Pending.EMPTY;
+
+    @Unique
+    private CavernSpringOutlets.Pending sanctuary$pendingCavernOutlets = CavernSpringOutlets.Pending.EMPTY;
+
+    @Inject(method = "postProcessGeneration", at = @At("HEAD"))
+    private void sanctuary$captureCavernOutlets(ServerLevel level, CallbackInfo callback) {
+        sanctuary$pendingPopulationOutlets = PopulationSpringOutlets.capturePending(level, (LevelChunk) (Object) this);
+        sanctuary$pendingCavernOutlets = CavernSpringOutlets.capturePending(level, (LevelChunk) (Object) this);
+    }
+
+    @Inject(method = "postProcessGeneration", at = @At("TAIL"))
+    private void sanctuary$finishCavernOutlets(ServerLevel level, CallbackInfo callback) {
+        var population = sanctuary$pendingPopulationOutlets;
+        sanctuary$pendingPopulationOutlets = PopulationSpringOutlets.Pending.EMPTY;
+        PopulationSpringOutlets.finish(level, (LevelChunk) (Object) this, population);
+        var pending = sanctuary$pendingCavernOutlets;
+        sanctuary$pendingCavernOutlets = CavernSpringOutlets.Pending.EMPTY;
+        CavernSpringOutlets.finish(level, (LevelChunk) (Object) this, pending);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/ExpansionCarverMixin.java

@@ -0,0 +1,18 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.expansion.ExpansionBiomeSource;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
+
+/** The laboratory keeps the source island's cavities; vanilla carvers must not remove approved foundations. */
+@Mixin(NoiseBasedChunkGenerator.class)
+public abstract class ExpansionCarverMixin {
+    @Inject(method = "generateCarvers", at = @At("HEAD"), cancellable = true)
+    private void sanctuary$keepExpansionCavities(CallbackInfo callback) {
+        var generator = (NoiseBasedChunkGenerator) (Object) this;
+        if (generator.getBiomeSource() instanceof ExpansionBiomeSource) callback.cancel();
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/ExpansionChunkMapAccessor.java

@@ -0,0 +1,14 @@
+package fr.koka.sanctuary.mixin;
+
+import it.unimi.dsi.fastutil.longs.Long2ObjectLinkedOpenHashMap;
+import net.minecraft.server.level.ChunkHolder;
+import net.minecraft.server.level.ChunkMap;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.gen.Accessor;
+
+/** Admission must also reject chunks removed from the active map but not saved yet. */
+@Mixin(ChunkMap.class)
+public interface ExpansionChunkMapAccessor {
+    @Accessor("pendingUnloads")
+    Long2ObjectLinkedOpenHashMap<ChunkHolder> sanctuary$pendingUnloads();
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/InitialSpawnMixin.java

@@ -15,6 +15,11 @@ public abstract class InitialSpawnMixin {
     @Inject(method = "setInitialSpawn", at = @At("RETURN"))
     private static void sanctuary$initialSpawn(ServerLevel level, ServerLevelData data, boolean bonusChest,
                                                boolean debugWorld, LevelLoadListener listener, CallbackInfo ci) {
+        if (level.getChunkSource().getGenerator() instanceof fr.koka.sanctuary.expansion.ExpansionChunkGenerator) {
+            var pos = fr.koka.sanctuary.expansion.ExpansionRuntime.session(level).landing("sanctuary");
+            level.setRespawnData(net.minecraft.world.level.storage.LevelData.RespawnData.of(net.minecraft.world.level.Level.OVERWORLD, pos, 0, 0));
+            return;
+        }
         SanctuarySpawn.initialize(level);
     }
 }

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/LayeredSpringOutletMixin.java

@@ -0,0 +1,29 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.worldgen.LayeredSpringOutlets;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.chunk.LevelChunk;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
+
+/** Finish only pending generation markers; completed saved chunks are never repaired on reload. */
+@Mixin(LevelChunk.class)
+public abstract class LayeredSpringOutletMixin {
+    @Unique
+    private LayeredSpringOutlets.Pending sanctuary$pendingSpringOutlets = LayeredSpringOutlets.Pending.EMPTY;
+
+    @Inject(method = "postProcessGeneration", at = @At("HEAD"))
+    private void sanctuary$captureSpringOutlets(ServerLevel level, CallbackInfo callback) {
+        sanctuary$pendingSpringOutlets = LayeredSpringOutlets.capturePending(level, (LevelChunk) (Object) this);
+    }
+
+    @Inject(method = "postProcessGeneration", at = @At("TAIL"))
+    private void sanctuary$finishSpringOutlets(ServerLevel level, CallbackInfo callback) {
+        var pending = sanctuary$pendingSpringOutlets;
+        sanctuary$pendingSpringOutlets = LayeredSpringOutlets.Pending.EMPTY;
+        LayeredSpringOutlets.finish(level, (LevelChunk) (Object) this, pending);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/RiftSpringOutletMixin.java

@@ -0,0 +1,29 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.worldgen.RiftSpringOutlets;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.chunk.LevelChunk;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
+
+/** Finish only pending generation markers; completed saved chunks are never repaired on reload. */
+@Mixin(LevelChunk.class)
+public abstract class RiftSpringOutletMixin {
+    @Unique
+    private RiftSpringOutlets.Pending sanctuary$pendingRiftOutlets = RiftSpringOutlets.Pending.EMPTY;
+
+    @Inject(method = "postProcessGeneration", at = @At("HEAD"))
+    private void sanctuary$captureRiftOutlets(ServerLevel level, CallbackInfo callback) {
+        sanctuary$pendingRiftOutlets = RiftSpringOutlets.capturePending(level, (LevelChunk) (Object) this);
+    }
+
+    @Inject(method = "postProcessGeneration", at = @At("TAIL"))
+    private void sanctuary$finishRiftOutlets(ServerLevel level, CallbackInfo callback) {
+        var pending = sanctuary$pendingRiftOutlets;
+        sanctuary$pendingRiftOutlets = RiftSpringOutlets.Pending.EMPTY;
+        RiftSpringOutlets.finish(level, (LevelChunk) (Object) this, pending);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/SurfaceHydrologyMixin.java

@@ -1,6 +1,12 @@
 package fr.koka.sanctuary.mixin;
 
 import fr.koka.sanctuary.worldgen.HydrologyRuntime;
+import fr.koka.sanctuary.worldgen.NaturalHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.LayeredHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.WoodlandHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.RiftHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.CavernHydrologyRuntime;
+import fr.koka.sanctuary.worldgen.PopulationHydrologyRuntime;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import net.minecraft.core.Holder;
@@ -25,7 +31,37 @@ public abstract class SurfaceHydrologyMixin {
             StructureManager structures, BiomeManager biomeManager, WorldGenRegion region,
             Set<Holder<Biome>> biomes, CallbackInfoReturnable<CompletableFuture<ChunkAccess>> callback) {
         var generator = (NoiseBasedChunkGenerator) (Object) this;
-        if (HydrologyRuntime.enabled(generator)) {
+        if (PopulationHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                PopulationHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (CavernHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                CavernHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (RiftHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                RiftHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (WoodlandHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                WoodlandHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (LayeredHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                LayeredHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (NaturalHydrologyRuntime.enabled(generator)) {
+            callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
+                NaturalHydrologyRuntime.apply(generator, randomState, generated);
+                return generated;
+            }));
+        } else if (HydrologyRuntime.enabled(generator)) {
             callback.setReturnValue(callback.getReturnValue().thenApply(generated -> {
                 HydrologyRuntime.apply(generator, randomState, generated);
                 return generated;

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/UnifiedDecorationProtectionMixin.java

@@ -0,0 +1,30 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.WorldGenRegion;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfoReturnable;
+
+/** Only new alpha.13 decoration writes are filtered, never player edits or saved chunk loading. */
+@Mixin(WorldGenRegion.class)
+public abstract class UnifiedDecorationProtectionMixin {
+    @Inject(method = "setBlock", at = @At("HEAD"), cancellable = true)
+    private void sanctuary$keepHydrology(BlockPos pos, BlockState state, int flags, int recursion,
+            CallbackInfoReturnable<Boolean> callback) {
+        var region = (WorldGenRegion) (Object) this;
+        if (!(region.getLevel().getChunkSource().getGenerator() instanceof SanctuaryChunkGenerator generator)) return;
+        // Vanilla rejects writes outside its region before reading the destination chunk.
+        if (!region.isWithinWriteZone(pos)) return;
+        // The dedicated shoreline feature still grows cane on its naturally valid dry banks.
+        if (state.is(Blocks.SUGAR_CANE)) return;
+        if (generator.protectsDecoration(pos) && !region.getBlockState(pos).equals(state)) {
+            generator.rejectedDecorationWrite();
+            callback.setReturnValue(false);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/WoodlandSpringOutletMixin.java

@@ -0,0 +1,29 @@
+package fr.koka.sanctuary.mixin;
+
+import fr.koka.sanctuary.worldgen.WoodlandSpringOutlets;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.chunk.LevelChunk;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
+
+/** Finish only pending generation markers; completed saved chunks are never repaired on reload. */
+@Mixin(LevelChunk.class)
+public abstract class WoodlandSpringOutletMixin {
+    @Unique
+    private WoodlandSpringOutlets.Pending sanctuary$pendingWoodlandOutlets = WoodlandSpringOutlets.Pending.EMPTY;
+
+    @Inject(method = "postProcessGeneration", at = @At("HEAD"))
+    private void sanctuary$captureWoodlandOutlets(ServerLevel level, CallbackInfo callback) {
+        sanctuary$pendingWoodlandOutlets = WoodlandSpringOutlets.capturePending(level, (LevelChunk) (Object) this);
+    }
+
+    @Inject(method = "postProcessGeneration", at = @At("TAIL"))
+    private void sanctuary$finishWoodlandOutlets(ServerLevel level, CallbackInfo callback) {
+        var pending = sanctuary$pendingWoodlandOutlets;
+        sanctuary$pendingWoodlandOutlets = WoodlandSpringOutlets.Pending.EMPTY;
+        WoodlandSpringOutlets.finish(level, (LevelChunk) (Object) this, pending);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/mixin/client/SanctuaryWorldOptionsMixin.java

@@ -0,0 +1,50 @@
+package fr.koka.sanctuary.mixin.client;
+
+import fr.koka.sanctuary.client.SanctuaryWorldOptionsScreen;
+import fr.koka.sanctuary.worldgen.SanctuaryChunkGenerator;
+import java.util.Map;
+import java.util.Optional;
+import net.minecraft.client.gui.screens.worldselection.PresetEditor;
+import net.minecraft.client.gui.screens.worldselection.WorldCreationUiState;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.Identifier;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.levelgen.presets.WorldPreset;
+import org.spongepowered.asm.mixin.Mixin;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Inject;
+import org.spongepowered.asm.mixin.injection.Redirect;
+import org.spongepowered.asm.mixin.injection.callback.CallbackInfoReturnable;
+
+/** Supplies the existing vanilla Customize button without replacing its editor registry. */
+@Mixin(WorldCreationUiState.class)
+public abstract class SanctuaryWorldOptionsMixin {
+    @Unique
+    private static final ResourceKey<WorldPreset> SANCTUARY_PRESET = ResourceKey.create(
+            Registries.WORLD_PRESET, Identifier.fromNamespaceAndPath("sanctuary", "sanctuary"));
+    @Unique
+    private static final PresetEditor SANCTUARY_EDITOR = SanctuaryWorldOptionsScreen::new;
+
+    @Inject(method = "getPresetEditor", at = @At("HEAD"), cancellable = true)
+    private void sanctuary$worldOptions(CallbackInfoReturnable<PresetEditor> callback) {
+        if (sanctuary$hasEditableGenerator()) callback.setReturnValue(SANCTUARY_EDITOR);
+    }
+
+    // Vanilla preserves custom dimensions on registry refresh only when this direct lookup finds an editor.
+    @Redirect(method = "updatePresetLists", at = @At(value = "INVOKE",
+            target = "Ljava/util/Map;get(Ljava/lang/Object;)Ljava/lang/Object;"))
+    private Object sanctuary$preserveCustomSize(Map<?, ?> editors, Object key) {
+        if (Optional.of(SANCTUARY_PRESET).equals(key) && sanctuary$hasEditableGenerator()) return SANCTUARY_EDITOR;
+        return editors.get(key);
+    }
+
+    @Unique
+    private boolean sanctuary$hasEditableGenerator() {
+        WorldCreationUiState state = (WorldCreationUiState) (Object) this;
+        var preset = state.getWorldType().preset();
+        // Recreating an older save may retain the same public preset key with a legacy generator.
+        return preset != null && preset.is(SANCTUARY_PRESET)
+                && state.getSettings().selectedDimensions().overworld() instanceof SanctuaryChunkGenerator;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernBiomePalette.java

@@ -0,0 +1,34 @@
+package fr.koka.sanctuary.worldgen;
+
+/** Alpha.9 keeps the upper woodland climate and specializes sheltered lower layers. */
+public final class CavernBiomePalette {
+    public enum Kind {
+        OAK_FOREST, BIRCH_FOREST, CLEARING, DRY_WOODLAND, ROCKY_HEATH,
+        DARK_GROVE, BAMBOO_GROVE, SULFUR_DEPTHS, LUSH_CAVES, DRIPSTONE_CAVES
+    }
+
+    private CavernBiomePalette() {}
+
+    public static Kind select(int blockY, float variation, float moisture) {
+        double elevation = blockY - Math.clamp(variation, -1.0F, 1.0F) * 16
+            - Math.clamp(moisture, -1.0F, 1.0F) * 10;
+        // Small climate pockets replace alpha.8's broad sulfur province. Neither
+        // mineral pockets nor cave vegetation can take over the upper forest.
+        if (blockY < 176 && elevation < 168 && variation > 0.22F && variation < 0.42F
+                && moisture > -0.42F && moisture < -0.12F) return Kind.SULFUR_DEPTHS;
+        if (variation > 0.48F) return Kind.ROCKY_HEATH;
+        if (blockY < 184 && elevation < 180) {
+            if (moisture > 0.05F && variation > -0.32F) return Kind.LUSH_CAVES;
+            if (moisture < -0.18F && variation < 0.22F) return Kind.DRIPSTONE_CAVES;
+        }
+        if (elevation < 214) {
+            if (variation < -0.45F && moisture > 0.40F) return Kind.BAMBOO_GROVE;
+            double shelteredMoisture = moisture + Math.min(0.55, (214 - elevation) / 160);
+            if (shelteredMoisture > -0.08) return Kind.DARK_GROVE;
+        }
+        if (moisture < -0.55F && variation > -0.25F) return Kind.DRY_WOODLAND;
+        if (Math.abs(variation) < 0.09F && moisture < 0.35F) return Kind.CLEARING;
+        if (variation < -0.33F) return Kind.BIRCH_FOREST;
+        return Kind.OAK_FOREST;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernDecorationsFeature.java

@@ -0,0 +1,296 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.AmethystClusterBlock;
+import net.minecraft.world.level.block.CaveVines;
+import net.minecraft.world.level.block.GrowingPlantHeadBlock;
+import net.minecraft.world.level.block.PotentSulfurBlock;
+import net.minecraft.world.level.block.SpeleothemBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.block.state.properties.PotentSulfurState;
+import net.minecraft.world.level.block.state.properties.SpeleothemThickness;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.feature.Feature;
+import net.minecraft.world.level.levelgen.feature.GeodeFeature;
+
+/** Decorations in existing lower cavities only. All writes belong to the owner's chunk. */
+public final class CavernDecorationsFeature implements Feature {
+    public static final MapCodec<CavernDecorationsFeature> CODEC = MapCodec.unit(CavernDecorationsFeature::new);
+    private static final ResourceKey<Feature> GEODE = ResourceKey.create(Registries.FEATURE, SanctuaryMod.id("cavern_amethyst_geode"));
+    private static final Direction[] SIDES = {Direction.NORTH, Direction.SOUTH, Direction.WEST, Direction.EAST};
+    public enum Kind { LUSH, DRIPSTONE, SULFUR, GEODE }
+    public record Candidate(Kind kind, BlockPos floor, BlockPos ceiling) {
+        public Candidate { floor = floor.immutable(); ceiling = ceiling.immutable(); }
+    }
+
+    @Override public MapCodec<CavernDecorationsFeature> codec() { return CODEC; }
+
+    /** Pure, bounded probes for development diagnostics; no chunk loads or successful-placement promise. */
+    public static List<Candidate> candidates(NoiseBasedChunkGenerator generator, RandomState state, int chunkX, int chunkZ) {
+        if (!CavernHydrologyRuntime.enabled(generator) || Math.abs(chunkX) > 17 || Math.abs(chunkZ) > 17) return List.of();
+        var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        var biomes = generator.getBiomeSource().createUncachedResolver(state);
+        List<Candidate> found = new ArrayList<>();
+        for (int[] offset : new int[][]{{4, 4}, {4, 12}, {12, 4}, {12, 12}, {8, 8}}) {
+            int x = chunkX * 16 + offset[0], z = chunkZ * 16 + offset[1], floors = 0;
+            for (int y = 182; y >= 40; y--) {
+                if (sampler.sample(x, y, z) <= 0 || sampler.sample(x, y + 1, z) > 0
+                        || sampler.sample(x, y + 2, z) > 0 || sampler.sample(x, y - 1, z) <= 0
+                        || sampler.sample(x, y - 2, z) <= 0) continue;
+                int roof = y + 3;
+                while (roof <= Math.min(230, y + 48) && sampler.sample(x, roof, z) <= 0) roof++;
+                if (roof > Math.min(230, y + 48) || roof - y < 6
+                        || sampler.sample(x, roof + 1, z) <= 0) continue;
+                BlockPos floor = new BlockPos(x, y, z), ceiling = new BlockPos(x, roof, z);
+                var biome = biomes.getNoiseBiome(x >> 2, (y + 1) >> 2, z >> 2);
+                if (biome.is(CavernIslandBiomeSource.LUSH_CAVES)) found.add(new Candidate(Kind.LUSH, floor, ceiling));
+                else if (biome.is(CavernIslandBiomeSource.DRIPSTONE_CAVES)) found.add(new Candidate(Kind.DRIPSTONE, floor, ceiling));
+                else if (biome.is(CavernIslandBiomeSource.SULFUR_DEPTHS) && y < 176)
+                    found.add(new Candidate(Kind.SULFUR, floor, ceiling));
+                if (offset[0] == 8 && offset[1] == 8 && Math.floorMod(chunkSeed(state.seed(), chunkX, chunkZ, 0x9501L), 8) == 0)
+                    found.add(new Candidate(Kind.GEODE, floor, ceiling));
+                if (++floors >= 3) break;
+            }
+        }
+        // Geodes keep their entry free before this feature's moss, grass or pointed
+        // dripstone can occupy it. Stable sorting preserves every other candidate order.
+        found.sort(java.util.Comparator.comparingInt(candidate -> candidate.kind() == Kind.GEODE ? 0 : 1));
+        return List.copyOf(found);
+    }
+
+    @Override public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource ignored, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !CavernHydrologyRuntime.enabled(noise)) return false;
+        var state = level.getLevel().getChunkSource().randomState();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        int cx = origin.getX() >> 4, cz = origin.getZ() >> 4;
+        boolean changed = false, geyser = false, geode = false;
+        for (Candidate candidate : candidates(noise, state, cx, cz)) {
+            BlockPos floor = candidate.floor();
+            if (!stable(level, sampler, floor) || !level.getBlockState(floor.above()).isAir()) continue;
+            long seed = WoodlandGroveGeometry.seed(state.seed(), floor.getX(), floor.getY(), floor.getZ(), 0x9502L);
+            switch (candidate.kind()) {
+                case LUSH -> changed |= lush(level, noise, state, sampler, candidate, seed);
+                case DRIPSTONE -> changed |= dripstone(level, noise, state, sampler, candidate, seed);
+                case SULFUR -> {
+                    if (!geyser && Math.floorMod(chunkSeed(state.seed(), cx, cz, 0x9503L), 2) == 0)
+                        changed |= geyser = geyser(level, noise, state, sampler, candidate);
+                }
+                case GEODE -> { if (!geode) changed |= geode = geode(level, noise, state, sampler, candidate, seed); }
+            }
+        }
+        return changed;
+    }
+
+    private boolean lush(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                         WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos floor = site.floor(), roof = site.ceiling();
+        int gap = roof.getY() - floor.getY();
+        if (CavernHydrologyRuntime.protects(noise, state, floor, 3, gap + 2, 3)) return false;
+        boolean changed = false;
+        for (int dx = -2; dx <= 2; dx++) for (int dz = -2; dz <= 2; dz++) {
+            if (dx * dx + dz * dz > 5) continue;
+            BlockPos p = floor.offset(dx, 0, dz);
+            if (!stable(level, sampler, p) || !stable(level, sampler, p.below()) || !stable(level, sampler, p.below(2))
+                    || !level.getBlockState(p.above()).isAir()) continue;
+            setBlock(level, p, Blocks.MOSS_BLOCK.defaultBlockState());
+            long local = WoodlandGroveGeometry.seed(seed, p.getX(), p.getY(), p.getZ(), 0x9504L);
+            BlockState plant = (Math.floorMod(local, 5) == 0 ? Blocks.AZALEA : Math.floorMod(local, 3) == 0
+                ? Blocks.MOSS_CARPET : Blocks.SHORT_GRASS).defaultBlockState();
+            if (plant.canSurvive(level, p.above())) setBlock(level, p.above(), plant);
+            changed = true;
+        }
+        // Real cave-vine heads and bodies remain harvestable and luminous via BERRIES.
+        int length = Math.min(gap - 3, 3 + Math.floorMod(seed, 6));
+        if (stable(level, sampler, roof) && stable(level, sampler, roof.above())) {
+            boolean free = true;
+            for (int d = 1; d <= length; d++) free &= level.getBlockState(roof.below(d)).isAir();
+            if (free) for (int d = 1; d <= length; d++) {
+                BlockPos p = roof.below(d);
+                BlockState vine = (d == length ? Blocks.CAVE_VINES : Blocks.CAVE_VINES_PLANT).defaultBlockState()
+                    .setValue(CaveVines.BERRIES, d == length || Math.floorMod(seed + d, 3) == 0);
+                if (d == length) vine = vine.setValue(GrowingPlantHeadBlock.AGE, 25);
+                if (!vine.canSurvive(level, p)) break;
+                setBlock(level, p, vine); changed = true;
+            }
+        }
+        return changed;
+    }
+
+    private boolean dripstone(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                              WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos floor = site.floor(), roof = site.ceiling();
+        int gap = roof.getY() - floor.getY();
+        if (CavernHydrologyRuntime.protects(noise, state, floor, 1, gap + 2, 3)) return false;
+        int length = Math.min((gap - 3) / 2, 1 + Math.floorMod(seed, 4));
+        boolean changed = spike(level, sampler, floor, Direction.UP, length);
+        changed |= spike(level, sampler, roof, Direction.DOWN, length);
+        return changed;
+    }
+
+    private boolean spike(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, BlockPos support, Direction direction, int length) {
+        if (length < 1 || !stable(level, sampler, support) || !stable(level, sampler, support.relative(direction.getOpposite()))) return false;
+        for (int d = 1; d <= length; d++) {
+            BlockPos p = support.relative(direction, d);
+            if (!level.getBlockState(p).isAir() || sampler.sample(p.getX(), p.getY(), p.getZ()) > 0) return false;
+        }
+        setBlock(level, support, Blocks.DRIPSTONE_BLOCK.defaultBlockState());
+        for (int d = 1; d <= length; d++) {
+            SpeleothemThickness thickness = d == length ? SpeleothemThickness.TIP
+                : d == length - 1 ? SpeleothemThickness.FRUSTUM : d == 1 ? SpeleothemThickness.BASE : SpeleothemThickness.MIDDLE;
+            BlockState pointed = Blocks.POINTED_DRIPSTONE.defaultBlockState().setValue(SpeleothemBlock.TIP_DIRECTION, direction)
+                .setValue(SpeleothemBlock.THICKNESS, thickness);
+            setBlock(level, support.relative(direction, d), pointed);
+        }
+        return true;
+    }
+
+    private boolean geyser(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                           WoodlandGroveGeometry.Sampler sampler, Candidate site) {
+        BlockPos water = site.floor(), potent = water.below(), heat = water.below(2);
+        if (site.ceiling().getY() - water.getY() < 8
+                || CavernHydrologyRuntime.protects(noise, state, water, 2, 8, 5)) return false;
+        for (int d = 0; d <= 4; d++) if (!stable(level, sampler, water.below(d))) return false;
+        for (Direction side : SIDES) for (int d = 0; d <= 2; d++)
+            if (!stable(level, sampler, water.below(d).relative(side))) return false;
+        for (int d = 1; d <= 7; d++) if (!level.getBlockState(water.above(d)).isAir()) return false;
+        // One source, four original rock walls, original deep support. Vanilla's
+        // periodic geyser ticker requires magma below potent sulfur and source water above.
+        setBlock(level, heat, Blocks.MAGMA_BLOCK.defaultBlockState());
+        setBlock(level, water, Blocks.WATER.defaultBlockState());
+        setBlock(level, potent, Blocks.POTENT_SULFUR.defaultBlockState().setValue(PotentSulfurBlock.STATE, PotentSulfurState.DORMANT));
+        level.getChunk(water).markPosForPostProcessing(water);
+        level.getChunk(potent).markPosForPostProcessing(potent);
+        return true;
+    }
+
+    private boolean geode(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                          WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos origin = site.floor().offset(-1, -9, -1);
+        // Include the vanilla write range, its crystal neighbours and the entrance.
+        // This asymmetric envelope is centred explicitly so its positive edge is protected too.
+        if (origin.getY() - 6 < 24 || !level.getBlockState(site.floor().above(2)).isAir()
+                || CavernHydrologyRuntime.protects(noise, state, origin.offset(1, -6, 1), 7, 17, 0)) return false;
+        Map<BlockPos, BlockState> before = new LinkedHashMap<>();
+        for (int dx = -6; dx <= 8; dx++) for (int dz = -6; dz <= 8; dz++) for (int dy = -6; dy <= 11; dy++) {
+            BlockPos p = origin.offset(dx, dy, dz);
+            BlockState original = level.getBlockState(p);
+            // No block-entity data or fluid scheduler state needs to be restored.
+            if (original.hasBlockEntity() || !original.getFluidState().isEmpty()) return false;
+            before.put(p, original);
+        }
+        Feature feature = level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(GEODE).value();
+        if (!(feature instanceof GeodeFeature geode) || geode.minGenOffset() != -5 || geode.maxGenOffset() != 7) return false;
+        boolean accepted = false;
+        try {
+            if (!geode.place(level, noise, RandomSource.create(seed), origin) || !naturalGeodeChanges(level, sampler, before)) return false;
+            var entrance = geodeEntrance(level, sampler, site.floor().above(), origin, before);
+            if (entrance.isEmpty()) return false;
+            for (BlockPos p : entrance) if (!level.getBlockState(p).isAir()) setBlock(level, p, Blocks.AIR.defaultBlockState());
+            if (!naturalGeodeChanges(level, sampler, before)) return false;
+            accepted = true;
+            return true;
+        } finally {
+            if (!accepted) before.forEach((p, original) -> {
+                if (!level.getBlockState(p).equals(original)) setBlock(level, p, original);
+            });
+        }
+    }
+
+    /** Test the actual vanilla mask, not unused bounding-box corners. A geode may
+     * excavate original rock but cannot fill original air or remove earlier decoration. */
+    private static boolean naturalGeodeChanges(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                               Map<BlockPos, BlockState> before) {
+        for (var entry : before.entrySet()) {
+            BlockPos p = entry.getKey();
+            BlockState original = entry.getValue(), current = level.getBlockState(p);
+            if (original.equals(current)) continue;
+            if (!carvableOriginal(level, sampler, p, original)) return false;
+        }
+        return true;
+    }
+
+    private static boolean carvableOriginal(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                            BlockPos p, BlockState original) {
+        return original != null && original.isCollisionShapeFullBlock(level, p)
+            && !original.hasBlockEntity() && original.getFluidState().isEmpty()
+            && !original.is(BlockTags.LOGS) && !original.is(BlockTags.LEAVES)
+            && !original.is(Blocks.BUDDING_AMETHYST) && !original.is(Blocks.MAGMA_BLOCK)
+            && sampler.sample(p.getX(), p.getY(), p.getZ()) > 0;
+    }
+
+    private static List<BlockPos> geodeEntrance(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                                BlockPos start, BlockPos origin, Map<BlockPos, BlockState> before) {
+        var previous = new java.util.HashMap<BlockPos, BlockPos>();
+        var distances = new java.util.HashMap<BlockPos, Integer>();
+        var queue = new java.util.ArrayDeque<BlockPos>();
+        queue.add(start); distances.put(start, 0);
+        BlockPos destination = null;
+        while (!queue.isEmpty()) {
+            BlockPos p = queue.removeFirst();
+            int distance = distances.get(p);
+            boolean adjacentBudding = false;
+            for (Direction direction : Direction.values())
+                adjacentBudding |= level.getBlockState(p.relative(direction)).is(Blocks.BUDDING_AMETHYST)
+                    || level.getBlockState(p.above().relative(direction)).is(Blocks.BUDDING_AMETHYST);
+            if (p.getY() <= start.getY() - 3 && level.getBlockState(p).isAir()
+                    && level.getBlockState(p.above()).isAir() && adjacentBudding) { destination = p; break; }
+            if (distance >= 16) continue;
+            for (Direction direction : Direction.values()) {
+                BlockPos next = p.relative(direction);
+                if (Math.abs(next.getX() - start.getX()) > 6 || Math.abs(next.getZ() - start.getZ()) > 6
+                        || next.getY() < origin.getY() - 5 || next.getY() > start.getY()
+                        || distances.containsKey(next) || !before.containsKey(next) || !before.containsKey(next.above())) continue;
+                if (!entranceBlock(level, sampler, next, before) || !entranceBlock(level, sampler, next.above(), before)) continue;
+                distances.put(next, distance + 1); previous.put(next, p); queue.addLast(next);
+            }
+        }
+        if (destination == null) return List.of();
+        var passage = new java.util.LinkedHashSet<BlockPos>();
+        for (BlockPos p = destination; p != null; p = previous.get(p)) { passage.add(p); passage.add(p.above()); }
+        return List.copyOf(passage);
+    }
+
+    private static boolean entranceBlock(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                          BlockPos p, Map<BlockPos, BlockState> before) {
+        BlockState current = level.getBlockState(p);
+        if (current.isAir()) return true;
+        // Keep every budding block and attached crystal. Search around them instead.
+        if (current.is(Blocks.BUDDING_AMETHYST) || current.is(Blocks.AMETHYST_CLUSTER)
+                || current.is(Blocks.SMALL_AMETHYST_BUD) || current.is(Blocks.MEDIUM_AMETHYST_BUD)
+                || current.is(Blocks.LARGE_AMETHYST_BUD)) return false;
+        for (Direction direction : Direction.values()) {
+            BlockState neighbour = level.getBlockState(p.relative(direction));
+            if (neighbour.getBlock() instanceof AmethystClusterBlock
+                    && neighbour.getValue(AmethystClusterBlock.FACING) == direction) return false;
+        }
+        return carvableOriginal(level, sampler, p, before.get(p));
+    }
+
+    private static boolean stable(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, BlockPos p) {
+        BlockState state = level.getBlockState(p);
+        return sampler.sample(p.getX(), p.getY(), p.getZ()) > 0 && state.isCollisionShapeFullBlock(level, p)
+            && state.getFluidState().isEmpty() && !state.hasBlockEntity() && !state.is(BlockTags.LOGS)
+            && !state.is(BlockTags.LEAVES) && !state.is(Blocks.BUDDING_AMETHYST) && !state.is(Blocks.MAGMA_BLOCK);
+    }
+
+    private static long chunkSeed(long seed, int x, int z, long salt) {
+        return WoodlandGroveGeometry.seed(seed, x * 16, 0, z * 16, salt);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernGrovesFeature.java

@@ -0,0 +1,296 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.Map;
+import java.util.Optional;
+import java.util.WeakHashMap;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.data.worldgen.features.TreeFeatures;
+import net.minecraft.data.worldgen.features.VegetationFeatures;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.VegetationBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.feature.Feature;
+import net.minecraft.world.level.levelgen.feature.AbstractHugeMushroomFeature;
+
+/** Alpha.9: sheltered vanilla mushroom trees and dark oak on natural lower floors,
+ * plus one globally selected remarkable tree.
+ * Placement runs only in new generation. No world journal or mutable placement counter is retained. */
+public final class CavernGrovesFeature implements Feature {
+    public static final MapCodec<CavernGrovesFeature> CODEC = MapCodec.unit(CavernGrovesFeature::new);
+    private static final Map<RandomState, Optional<RemarkableTree>> REMARKABLE =
+        Collections.synchronizedMap(new WeakHashMap<>());
+
+    public record RemarkableTree(BlockPos base, String featureId, int radius, int height) {
+        public RemarkableTree { base = base.immutable(); }
+    }
+    private record Species(ResourceKey<Feature> key, int width, int radius, int height) {}
+    private record Candidate(int x, int z, long rank) {}
+    @FunctionalInterface
+    private interface Protection {
+        boolean intersects(BlockPos base, int radius, int height, int rootDepth);
+    }
+    private static final Species CHERRY = new Species(TreeFeatures.CHERRY, 1, 9, 15);
+    private static final Species[] SPECIES = {CHERRY, CHERRY, CHERRY, CHERRY,
+        new Species(TreeFeatures.SPRUCE, 1, 5, 15), new Species(TreeFeatures.JUNGLE_TREE_NO_VINE, 1, 5, 14),
+        new Species(TreeFeatures.ACACIA, 1, 7, 14), new Species(TreeFeatures.MANGROVE, 1, 10, 20),
+        new Species(TreeFeatures.PALE_OAK_BONEMEAL, 2, 6, 12)};
+
+    @Override public MapCodec<CavernGrovesFeature> codec() { return CODEC; }
+
+    public static Optional<RemarkableTree> remarkablePlan(ServerLevel level) {
+        if (!(level.getChunkSource().getGenerator() instanceof NoiseBasedChunkGenerator noise)) return Optional.empty();
+        return remarkablePlan(noise, level.getChunkSource().randomState());
+    }
+
+    public static Optional<RemarkableTree> remarkablePlan(NoiseBasedChunkGenerator noise, RandomState state) {
+        if (!CavernHydrologyRuntime.enabled(noise)) return Optional.empty();
+        return REMARKABLE.computeIfAbsent(state, ignored -> {
+            var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+            WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+            Protection protection = (base, radius, height, rootDepth) ->
+                CavernHydrologyRuntime.protects(noise, state, base, radius, height, rootDepth);
+            Species species = SPECIES[Math.floorMod(WoodlandGroveGeometry.seed(state.seed(), 0, 0, 0, 0x70EEL), SPECIES.length)];
+            var candidates = new ArrayList<Candidate>();
+            for (int x = -152; x <= 152; x += 16) for (int z = -152; z <= 152; z += 16) {
+                if (Math.hypot(x, z) <= 168) candidates.add(new Candidate(x, z,
+                    WoodlandGroveGeometry.seed(state.seed(), x, 0, z, 0x71AFL)));
+            }
+            candidates.sort(Comparator.comparingLong(Candidate::rank).thenComparingInt(Candidate::x).thenComparingInt(Candidate::z));
+            for (Candidate candidate : candidates) {
+                int bed = WoodlandGroveGeometry.highestSurface(sampler, candidate.x(), candidate.z());
+                if (!WoodlandGroveGeometry.naturalFootprint(sampler, candidate.x(), bed, candidate.z(), species.width())) continue;
+                BlockPos base = new BlockPos(candidate.x(), bed + 1, candidate.z());
+                if (blocked(protection, base, species.radius() + 1, species.height(), rootDepth(species))) continue;
+                if (!WoodlandGroveGeometry.treeRoom(sampler, base.getX(), base.getY(), base.getZ(),
+                    species.width(), species.radius(), species.height())) continue;
+                return Optional.of(new RemarkableTree(base, species.key().identifier().toString(), species.radius(), species.height()));
+            }
+            return Optional.empty();
+        });
+    }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource ignored, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !CavernHydrologyRuntime.enabled(noise)) return false;
+        int minX = (origin.getX() >> 4) * 16, minZ = (origin.getZ() >> 4) * 16;
+        if (Math.abs((long) minX) > 272 || Math.abs((long) minZ) > 272) return false;
+        var state = level.getLevel().getChunkSource().randomState();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        Protection protection = (base, radius, height, rootDepth) ->
+            CavernHydrologyRuntime.protects(noise, state, base, radius, height, rootDepth);
+        boolean changed = false;
+        int[] heights = new int[256];
+        Arrays.fill(heights, Integer.MIN_VALUE);
+        var remarkable = remarkablePlan(noise, state);
+        if (remarkable.isPresent()) {
+            var tree = remarkable.get();
+            BlockPos base = tree.base();
+            if ((base.getX() >> 4) == (minX >> 4) && (base.getZ() >> 4) == (minZ >> 4)) {
+                for (Species species : SPECIES) if (species.key().identifier().toString().equals(tree.featureId())) {
+                    changed |= tree(level, generator, sampler, state.seed(), base, species, protection, 0x723BL);
+                    break;
+                }
+            }
+        }
+        // The scarce tall rooms usually go to dark oak first; one quarter of chunks
+        // give mushroom trees first choice. This changes priority, never attempt budgets
+        // or natural fit requirements, and uses a separate deterministic chunk seed.
+        boolean mushroomsFirst = Math.floorMod(WoodlandGroveGeometry.seed(state.seed(), minX, 0, minZ, 0x8503L), 4) == 0;
+        if (mushroomsFirst) changed |= mushroomTrees(level, generator, sampler, state.seed(), protection, minX, minZ, heights);
+        // Four spaced origins per chunk; the 2x2 trunk and full canopy still have to fit the cave.
+        for (int x = minX + 4; x < minX + 16; x += 8) for (int z = minZ + 4; z < minZ + 16; z += 8) {
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights), placed = 0;
+            for (int bed = highest - 8; bed >= 40; bed--) {
+                BlockPos base = new BlockPos(x, bed + 1, z);
+                if (!ground(level, base.below()) || !level.getBlockState(base).isAir()) continue;
+                var biome = level.getBiome(base);
+                boolean dark = biome.is(CavernIslandBiomeSource.DARK_GROVE);
+                boolean bamboo = biome.is(CavernIslandBiomeSource.BAMBOO_GROVE);
+                if (!dark && !bamboo) continue;
+                long placementSeed = WoodlandGroveGeometry.seed(state.seed(), x, bed, z, 0x730DL);
+                if (dark) {
+                    if (tree(level, generator, sampler, state.seed(), base,
+                        new Species(TreeFeatures.DARK_OAK, 2, 6, 12), protection, 0x730DL)) { changed = true; placed++; }
+                } else if (Math.floorMod(placementSeed, 8) == 0) {
+                    if (tree(level, generator, sampler, state.seed(), base,
+                        new Species(TreeFeatures.JUNGLE_TREE_NO_VINE, 1, 5, 14), protection, 0x735BL)) { changed = true; placed++; }
+                } else if (Math.floorMod(placementSeed, 3) == 0
+                    && WoodlandGroveGeometry.naturalFootprint(sampler, x, bed, z, 1)
+                    && WoodlandGroveGeometry.treeRoom(sampler, x, bed + 1, z, 1, 3, 16)
+                    && !blocked(protection, base, 4, 17) && actualRoom(level, base, 1, 3, 16)) {
+                    setBlock(level, base.below(), Blocks.PODZOL.defaultBlockState());
+                    changed |= level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(VegetationFeatures.BAMBOO_NO_PODZOL)
+                        .value().place(level, generator, RandomSource.create(placementSeed), base);
+                    placed++;
+                }
+                if (placed >= 2) break;
+            }
+        }
+        if (!mushroomsFirst) changed |= mushroomTrees(level, generator, sampler, state.seed(), protection, minX, minZ, heights);
+        // Coherent ground patches: about 40% moss, 40% podzol, 20% mycelium.
+        // Small mushrooms are accents (one opportunity per hundred columns), not the canopy.
+        for (int x = minX; x < minX + 16; x++) for (int z = minZ; z < minZ + 16; z++) {
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights), floors = 0;
+            long detail = WoodlandGroveGeometry.seed(state.seed(), x, 0, z, 0x843EL);
+            boolean smallMushroomPlaced = false;
+            for (int bed = highest - 8; bed >= 32; bed--) {
+                BlockPos floor = new BlockPos(x, bed, z), plant = floor.above();
+                if (!ground(level, floor) || !level.getBlockState(plant).isAir()) continue;
+                var biome = level.getBiome(plant);
+                if (!biome.is(CavernIslandBiomeSource.DARK_GROVE) && !biome.is(CavernIslandBiomeSource.BAMBOO_GROVE)) continue;
+                if (!WoodlandGroveGeometry.naturalFootprint(sampler, x, bed, z, 1) || blocked(protection, plant, 1, 2)) continue;
+                long patch = WoodlandGroveGeometry.seed(state.seed(), Math.floorDiv(x, 7), 0, Math.floorDiv(z, 7), 0x742DL);
+                int soilKind = Math.floorMod(patch, 5);
+                BlockState soil = (soilKind < 2 ? Blocks.MOSS_BLOCK : soilKind < 4 ? Blocks.PODZOL : Blocks.MYCELIUM).defaultBlockState();
+                setBlock(level, floor, soil);
+                if (!smallMushroomPlaced && Math.floorMod(detail, 100) == 0) {
+                    BlockState mushroom = (Math.floorMod(detail >>> 8, 2) == 0 ? Blocks.BROWN_MUSHROOM : Blocks.RED_MUSHROOM).defaultBlockState();
+                    if (mushroom.canSurvive(level, plant)) {
+                        setBlock(level, plant, mushroom);
+                        smallMushroomPlaced = true;
+                    }
+                }
+                changed = true;
+                if (++floors >= 3) break;
+            }
+        }
+        return changed;
+    }
+
+    private boolean mushroomTrees(WorldGenLevel level, ChunkGenerator generator, WoodlandGroveGeometry.Sampler sampler,
+                                  long seed, Protection protection, int minX, int minZ, int[] heights) {
+        boolean changed = false;
+        RandomSource mushroomSites = RandomSource.create(WoodlandGroveGeometry.seed(seed, minX, 0, minZ, 0x8501L));
+        int mushroomAttempts = 1 + mushroomSites.nextInt(3);
+        for (int attempt = 0; attempt < mushroomAttempts; attempt++) {
+            int x = minX + 3 + mushroomSites.nextInt(10), z = minZ + 3 + mushroomSites.nextInt(10);
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights);
+            for (int bed = highest - 8; bed >= 32; bed--) {
+                BlockPos base = new BlockPos(x, bed + 1, z);
+                if (!ground(level, base.below()) || !level.getBlockState(base).isAir()
+                        || !level.getBiome(base).is(CavernIslandBiomeSource.DARK_GROVE)) continue;
+                long mushroomSeed = WoodlandGroveGeometry.seed(seed, x, bed, z, 0x8502L + attempt);
+                var key = Math.floorMod(mushroomSeed, 2) == 0 ? TreeFeatures.HUGE_BROWN_MUSHROOM : TreeFeatures.HUGE_RED_MUSHROOM;
+                Feature feature = level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(key).value();
+                if (!(feature instanceof AbstractHugeMushroomFeature mushroom)) break;
+                int height = mushroom.getTreeHeight(RandomSource.create(mushroomSeed));
+                int radius = mushroom.foliageRadius();
+                if (!mushroomRoom(level, sampler, protection, base, radius, height)) continue;
+                BlockState originalFloor = level.getBlockState(base.below());
+                setBlock(level, base.below(), (Math.floorMod(mushroomSeed, 5) == 0 ? Blocks.MYCELIUM : Blocks.PODZOL).defaultBlockState());
+                // Vanilla consumes its height draw first. Replaying the same random seed
+                // gives precisely the height whose natural envelope was checked above.
+                boolean placed = mushroom.place(level, generator, RandomSource.create(mushroomSeed), base);
+                if (!placed) setBlock(level, base.below(), originalFloor);
+                changed |= placed;
+                break;
+            }
+        }
+        return changed;
+    }
+
+    private boolean tree(WorldGenLevel level, ChunkGenerator generator, WoodlandGroveGeometry.Sampler sampler, long seed,
+                         BlockPos base, Species species, Protection protection, long salt) {
+        if (blocked(protection, base, species.radius() + 1, species.height(), rootDepth(species))
+            || !WoodlandGroveGeometry.naturalFootprint(sampler, base.getX(), base.getY() - 1, base.getZ(), species.width())
+            || !actualRoom(level, base, species.width(), species.radius(), species.height())
+            || !WoodlandGroveGeometry.treeRoom(sampler, base.getX(), base.getY(), base.getZ(), species.width(), species.radius(), species.height())) return false;
+        for (int dx = 0; dx < species.width(); dx++) for (int dz = 0; dz < species.width(); dz++) {
+            BlockPos floor = base.offset(dx, -1, dz);
+            if (!ground(level, floor)) return false;
+        }
+        for (int dx = 0; dx < species.width(); dx++) for (int dz = 0; dz < species.width(); dz++) {
+            setBlock(level, base.offset(dx, -1, dz), Blocks.PODZOL.defaultBlockState());
+        }
+        return level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(species.key()).value()
+            .place(level, generator, RandomSource.create(WoodlandGroveGeometry.seed(seed, base.getX(), base.getY(), base.getZ(), salt)), base);
+    }
+
+    private static boolean actualRoom(WorldGenLevel level, BlockPos base, int width, int radius, int height) {
+        for (int y = 0; y <= height; y++) {
+            int from = y < 3 ? 0 : -radius, to = y < 3 ? width - 1 : radius;
+            for (int dx = from; dx <= to; dx++) for (int dz = from; dz <= to; dz++) {
+                BlockState current = level.getBlockState(base.offset(dx, y, dz));
+                if (!current.getFluidState().isEmpty() || !(current.isAir() || current.is(BlockTags.LEAVES)
+                    || current.getBlock() instanceof VegetationBlock)) return false;
+            }
+        }
+        return true;
+    }
+
+    private static boolean ground(WorldGenLevel level, BlockPos floor) {
+        BlockState state = level.getBlockState(floor);
+        if (state.is(Blocks.DEEPSLATE)) {
+            // Deep humid ledges can support organic soil. Check every tree foot rather
+            // than admitting this rock globally, including for the remarkable tree.
+            var biome = level.getBiome(floor.above());
+            return biome.is(CavernIslandBiomeSource.DARK_GROVE) || biome.is(CavernIslandBiomeSource.BAMBOO_GROVE);
+        }
+        return state.is(Blocks.STONE) || state.is(Blocks.DIRT) || state.is(Blocks.GRASS_BLOCK) || state.is(Blocks.PODZOL)
+            || state.is(Blocks.MYCELIUM) || state.is(Blocks.ROOTED_DIRT) || state.is(Blocks.COARSE_DIRT)
+            || state.is(Blocks.GRANITE) || state.is(Blocks.DIORITE) || state.is(Blocks.ANDESITE) || state.is(Blocks.TUFF)
+            || state.is(Blocks.COBBLESTONE) || state.is(Blocks.MOSSY_COBBLESTONE) || state.is(Blocks.PACKED_MUD);
+    }
+
+    private static int localTop(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, Protection protection,
+                                int minX, int minZ, int x, int z, int[] heights) {
+        int index = (x - minX) * 16 + z - minZ;
+        if (heights[index] != Integer.MIN_VALUE) return heights[index];
+        // In an untouched column the heightmap bounds the original surface cheaply.
+        // A protected water/lava column may have been carved: recover its raw top
+        // without depending on the current hydrology plan's representation.
+        int ceiling = level.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z) - 1;
+        if (protection.intersects(new BlockPos(x, level.getMinY(), z), 0, level.getHeight() - 1, 0))
+            ceiling = level.getMaxY();
+        return heights[index] = WoodlandGroveGeometry.highestSurfaceBelow(sampler, x, z, ceiling);
+    }
+
+    private static boolean mushroomRoom(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, Protection protection,
+                                        BlockPos base, int radius, int height) {
+        if (blocked(protection, base, radius + 1, height + 1, 4)
+                || !WoodlandGroveGeometry.naturalFootprint(sampler, base.getX(), base.getY() - 1, base.getZ(), 1)) return false;
+        for (int depth = 1; depth <= 3; depth++) {
+            BlockPos floor = base.below(depth);
+            if (!level.getBlockState(floor).isCollisionShapeFullBlock(level, floor)) return false;
+        }
+        // A complete conservative column around the cap handles both brown umbrellas
+        // and the lower rounded red cap. Neither natural rock nor existing logs move.
+        for (int y = 0; y <= height + 1; y++) for (int dx = -radius; dx <= radius; dx++) for (int dz = -radius; dz <= radius; dz++) {
+            BlockPos p = base.offset(dx, y, dz);
+            BlockState current = level.getBlockState(p);
+            if (sampler.sample(p.getX(), p.getY(), p.getZ()) > 0 || !current.getFluidState().isEmpty()
+                    || !(current.isAir() || current.is(BlockTags.LEAVES))) return false;
+        }
+        // Being below another surface is not enough: the same column needs an actual
+        // original rock ceiling above the whole mushroom, not an open hillside.
+        for (int y = base.getY() + height + 2; y <= level.getMaxY(); y++)
+            if (sampler.sample(base.getX(), y, base.getZ()) > 0) return true;
+        return false;
+    }
+
+    private static int rootDepth(Species species) { return species.key().equals(TreeFeatures.MANGROVE) ? 16 : 4; }
+
+    private static boolean blocked(Protection protection, BlockPos base, int radius, int height) {
+        return blocked(protection, base, radius, height, 4);
+    }
+
+    private static boolean blocked(Protection protection, BlockPos base, int radius, int height, int rootDepth) {
+        return protection.intersects(base, radius, height, rootDepth);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernHydrology.java

@@ -0,0 +1,966 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.PriorityQueue;
+import java.util.Set;
+
+/** Alpha.9 river catchments, wider basins and rocky wall springs.
+ * This version is separate from NaturalHydrology so previously created worlds keep their original terrain.
+ * Results retain no chunks, sampler, random state or Minecraft objects. */
+public final class CavernHydrology {
+    public static final int RADIUS = 192;
+    public static final int MAX_CARVE = 16;
+    public static final int MAX_DEPTH = 8;
+    public static final int MAX_LAKE_CARVE = 12;
+    public static final int MAX_RIVER_BANK_CARVE = 12;
+    private static final int GRID = 8;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final int[][] NEIGHBORS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}, {1, 1}, {1, -1}, {-1, 1}, {-1, -1}};
+
+    private CavernHydrology() {}
+
+    @FunctionalInterface
+    public interface Sampler { float sample(int x, int y, int z); }
+
+    public enum Kind { POND, LAKE, RIVER, TERRACE }
+    public enum ShoreMaterial { SAND, GRAVEL, CLAY, STONE, GRASS }
+    public record Point(int x, int z) {}
+    public record Bounds(int minX, int minZ, int maxX, int maxZ) {}
+
+    public record Position(int x, int y, int z) {}
+    public record FlowBounds(int minX, int minY, int minZ, int maxX, int maxY, int maxZ) {}
+    public record Spring(long id, Position source, Position outlet, List<Position> flowPath, FlowBounds flowBounds) {
+        public Spring { flowPath = List.copyOf(flowPath); }
+    }
+    public record Terrace(long id, List<Long> basinIds) {
+        public Terrace { basinIds = List.copyOf(basinIds); }
+    }
+    /** A retained upper basin supplies this outlet. toFeatureId=-1 denotes an open terminal fall. */
+    public record Spill(long id, long fromFeatureId, long toFeatureId, Position source, Position outlet,
+                        List<Position> flowPath, FlowBounds flowBounds) {
+        public Spill { flowPath = List.copyOf(flowPath); }
+    }
+
+    /** Replaces existing solids bedY-sedimentDepth+1..bedY, with two intact natural supports below.
+     * Water occupies bedY+1..waterY; everything above it through carveTop is removed. For a dry
+     * terrace waterY=-1, and bedY+1..carveTop is removed (at most two original blocks). */
+    public record Cell(int x, int z, int waterY, int bedY, int carveTop,
+                       ShoreMaterial material, long featureId, int sedimentDepth) {
+        public boolean hasWater() { return waterY >= 0; }
+    }
+
+    public record Feature(long id, Kind kind, int waterY, List<Point> path, int waterCells, Bounds bounds) {
+        public Feature { path = List.copyOf(path); }
+    }
+
+    public static final class Plan {
+        private final Map<Long, Cell> cells;
+        private final List<Cell> allCells;
+        private final Map<Long, List<Cell>> layers;
+        private final Map<Long, List<Cell>> chunks;
+        private final List<Feature> features;
+        private final List<Spring> springs;
+        private final Map<Long, List<Spring>> springChunks;
+        private final Set<Position> springFlow;
+        private final int sampledColumns;
+        private final long densitySamples;
+        private final List<Terrace> terraces;
+        private final List<Spill> spills;
+        private final Set<Position> spillOpenings;
+
+        private Plan(Map<Long, Cell> source, List<Feature> features, List<Spring> springs, Set<Position> springFlow, int columns, long samples) {
+            this(source, features, springs, springFlow, columns, samples, CavernTerraces.Result.EMPTY);
+        }
+
+        private Plan(Map<Long, Cell> source, List<Feature> features, List<Spring> springs, Set<Position> springFlow,
+                     int columns, long samples, CavernTerraces.Result lower) {
+            List<Cell> combined = new ArrayList<>(source.values());
+            combined.addAll(lower.cells());
+            List<Cell> sorted = combined.stream()
+                .sorted(Comparator.comparingInt(Cell::x).thenComparingInt(Cell::z).thenComparingInt(Cell::bedY)).toList();
+            allCells = List.copyOf(sorted);
+            Map<Long, Cell> ordered = new LinkedHashMap<>();
+            Map<Long, List<Cell>> stacked = new HashMap<>();
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : sorted) {
+                ordered.put(key(cell.x(), cell.z()), cell);
+                stacked.computeIfAbsent(key(cell.x(), cell.z()), ignored -> new ArrayList<>()).add(cell);
+                byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4), ignored -> new ArrayList<>()).add(cell);
+            }
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            cells = Collections.unmodifiableMap(ordered);
+            stacked.replaceAll((ignored, values) -> List.copyOf(values));
+            layers = Map.copyOf(stacked);
+            chunks = Map.copyOf(byChunk);
+            List<Feature> allFeatures = new ArrayList<>(features);
+            allFeatures.addAll(lower.features());
+            this.features = List.copyOf(allFeatures);
+            this.springs = List.copyOf(springs);
+            Set<Position> allFlow = new HashSet<>(springFlow);
+            allFlow.addAll(lower.predictedFlow());
+            this.springFlow = Set.copyOf(allFlow);
+            terraces = List.copyOf(lower.terraces());
+            spills = List.copyOf(lower.spills());
+            spillOpenings = spills.stream().map(Spill::outlet).collect(java.util.stream.Collectors.toUnmodifiableSet());
+            Map<Long, List<Spring>> groupedSprings = new HashMap<>();
+            for (Spring spring : springs) groupedSprings.computeIfAbsent(
+                key(spring.source().x() >> 4, spring.source().z() >> 4), ignored -> new ArrayList<>()).add(spring);
+            groupedSprings.replaceAll((ignored, values) -> List.copyOf(values));
+            springChunks = Map.copyOf(groupedSprings);
+            sampledColumns = columns;
+            densitySamples = samples;
+        }
+
+        public Cell cellAt(int x, int z) { return cells.get(key(x, z)); }
+        public List<Cell> cellsAt(int x, int z) { return layers.getOrDefault(key(x, z), List.of()); }
+        /** Return the modified vertical interval, including its two unchanged support layers. */
+        public Cell cellAt(int x, int y, int z) {
+            for (Cell cell : cellsAt(x, z)) if (y >= cell.bedY() - cell.sedimentDepth() - 1
+                    && y <= Math.max(cell.waterY(), cell.carveTop())) return cell;
+            return null;
+        }
+        public Collection<Cell> cells() { return allCells; }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Feature> features() { return features; }
+        public boolean isRiverCell(Cell cell) { return features.stream().anyMatch(f -> f.kind() == Kind.RIVER && f.id() == cell.featureId()); }
+        public boolean isTerraceCell(Cell cell) { return features.stream().anyMatch(f -> f.kind() == Kind.TERRACE && f.id() == cell.featureId()); }
+        public List<Terrace> terraces() { return terraces; }
+        public List<Spill> spills() { return spills; }
+        public boolean isSpillOpening(int x, int y, int z) { return spillOpenings.contains(new Position(x, y, z)); }
+        public List<Spring> springs() { return springs; }
+        public List<Spring> springsInChunk(int x, int z) { return springChunks.getOrDefault(key(x, z), List.of()); }
+        /** Prediction in undecorated density, not a restriction on Minecraft fluid simulation. */
+        public boolean allowsSpringFlow(int x, int y, int z) { return springFlow.contains(new Position(x, y, z)); }
+        public int sampledColumns() { return sampledColumns; }
+        public long densitySamples() { return densitySamples; }
+    }
+
+    public static Plan create(long seed, Sampler sampler) {
+        return new Planner(seed, sampler).build();
+    }
+
+    private record Column(int top, int solidBottom) {}
+    private record Candidate(int x, int z, double score) {}
+    private record Node(int x, int z, double cost) {}
+    private static final Comparator<Node> NODE_ORDER = Comparator.comparingDouble(Node::cost)
+        .thenComparingInt(Node::x).thenComparingInt(Node::z);
+
+    private static final class Planner {
+        private final long seed;
+        private final Sampler sampler;
+        private final Map<Long, Column> columns = new HashMap<>();
+        private final Map<Long, Integer> coarse = new HashMap<>();
+        private final Map<Long, Cell> cells = new HashMap<>();
+        private final List<Feature> features = new ArrayList<>();
+        private final List<Spring> springs = new ArrayList<>();
+        private final Set<Position> springFlow = new HashSet<>();
+        private long samples;
+
+        Planner(long seed, Sampler sampler) { this.seed = seed; this.sampler = sampler; }
+
+        Plan build() {
+            List<Candidate> candidates = candidates();
+            addRiver();
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (features.size() >= 4 || attempts++ >= 96) break;
+                Point center = new Point(candidate.x(), candidate.z());
+                if (nearWater(center.x(), center.z(), 38)) continue;
+                Column column = column(center.x(), center.z());
+                if (column.top() < 64 || column.top() - column.solidBottom() < 7) continue;
+                Kind kind = features.size() < 2 ? Kind.LAKE : Kind.POND;
+                int target = kind == Kind.LAKE ? 700 + (int) (random(seed, center.x(), center.z()) * 400)
+                    : 100 + (int) (random(seed + 1, center.x(), center.z()) * 140);
+                // Prefer an existing low spot; a shallow cut is the fallback on level terrain.
+                for (int level : new int[]{column.top() + 1, column.top(), column.top() - 1, column.top() - 2}) {
+                    Set<Long> footprint = growBasin(center, level, target);
+                    if (footprint == null) continue;
+                    long id = featureId(features.size());
+                    Map<Long, Cell> wet = kind == Kind.LAKE ? lakeCells(footprint, level, id) : waterCells(footprint, level, id);
+                    if (wet == null || !contained(wet)) continue;
+                    addFeature(id, kind, level, List.of(center), wet);
+                    break;
+                }
+            }
+            addRiverSpring();
+            addSedimentSheets();
+            addLowerWallSprings();
+            addSprings();
+            Plan surface = new Plan(cells, features, springs, springFlow, columns.size(), samples);
+            var lower = CavernTerraces.create(seed, sampler, surface);
+            return new Plan(cells, features, springs, springFlow, columns.size(), samples, lower);
+        }
+
+        /** A connected catchment is excavated only in a thick natural plateau. The route is
+         * selected on the actual fissured density, not painted across missing rock. Its two
+         * terminal pools share the same retained waterline; a separate rock spring feeds it. */
+        private void addRiver() {
+            List<Integer> heights = coarse.values().stream().filter(y -> y >= 160).sorted().toList();
+            if (heights.isEmpty()) return;
+            Set<Integer> levels = new java.util.LinkedHashSet<>();
+            for (double quantile : new double[]{.55, .35, .75, .15, .90}) {
+                int top = heights.get(Math.min(heights.size() - 1, (int) (heights.size() * quantile)));
+                for (int cut : new int[]{4, 8, 0}) levels.add(top - cut);
+            }
+            for (int level : levels) {
+                Set<Long> allowed = new HashSet<>();
+                for (int x = -168; x <= 168; x += 4) for (int z = -168; z <= 168; z += 4) {
+                    if (!inside(x, z, 170)) continue;
+                    boolean safe = riverRock(x, z, level);
+                    for (int dx : new int[]{-3, 3}) for (int dz : new int[]{-3, 3}) {
+                        if (safe && !riverRock(x + dx, z + dz, level)) safe = false;
+                    }
+                    if (safe) allowed.add(key(x, z));
+                }
+                for (int attempt = 0; attempt < 4 && allowed.size() > 100; attempt++) {
+                    List<Point> route = longestRoute(allowed, level);
+                    if (route.size() < 36) break;
+                    Point first = route.getFirst(), last = route.getLast();
+                    if (Math.hypot(last.x() - first.x(), last.z() - first.z()) < 100) break;
+                    List<Point> path = smoothRoute(route);
+                    Set<Long> wet = new HashSet<>();
+                    Set<Long> bad = new HashSet<>();
+                    for (Point at : path) {
+                        int radius = field(at.x(), at.z(), 23, 8119) > .52 ? 3 : 2;
+                        for (int dx = -radius - 1; dx <= radius + 1; dx++) for (int dz = -radius - 1; dz <= radius + 1; dz++) {
+                        if (!riverRock(at.x() + dx, at.z() + dz, level)) {
+                            for (int gx = -1; gx <= 1; gx++) for (int gz = -1; gz <= 1; gz++)
+                                bad.add(key(Math.floorDiv(at.x(), 4) * 4 + gx * 4, Math.floorDiv(at.z(), 4) * 4 + gz * 4));
+                        }
+                        if (dx * dx + dz * dz <= radius * radius + 1) wet.add(key(at.x() + dx, at.z() + dz));
+                        }
+                    }
+                    if (!bad.isEmpty()) { allowed.removeAll(bad); continue; }
+                    // Both end pools are required and remain connected to the channel.
+                    boolean pools = true;
+                    for (Point endpoint : List.of(first, last)) {
+                        Set<Long> pool = growRiverPool(endpoint, level);
+                        if (pool.size() < 90) { pools = false; break; }
+                        wet.addAll(pool);
+                    }
+                    if (!pools) { allowed.remove(key(first.x(), first.z())); allowed.remove(key(last.x(), last.z())); continue; }
+                    long id = featureId(features.size());
+                    Map<Long, Cell> river = new HashMap<>();
+                    boolean safe = true;
+                    for (long k : wet) {
+                        Point at = point(k);
+                        Column rock = column(at.x(), at.z());
+                        int depth = 2;
+                        boolean edge = false;
+                        for (int[] d : CARDINALS) edge |= !wet.contains(key(at.x() + d[0], at.z() + d[1]));
+                        if (edge) depth = 1;
+                        int bed = level - depth;
+                        if (rock.top() < bed || rock.top() - bed > MAX_CARVE || rock.solidBottom() > bed - 6) { safe = false; break; }
+                        river.put(k, new Cell(at.x(), at.z(), level, bed, Math.max(level, rock.top()),
+                            wetMaterial(at.x(), at.z(), edge), id, 3));
+                    }
+                    if (!safe || !contained(river)) break;
+                    addFeature(id, Kind.RIVER, level, path, river);
+                    return;
+                }
+            }
+        }
+
+        private Set<Long> growRiverPool(Point center, int level) {
+            Set<Long> result = new HashSet<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            Set<Long> seen = new HashSet<>();
+            queue.add(new Node(center.x(), center.z(), 0));
+            while (!queue.isEmpty() && result.size() < 240) {
+                Node at = queue.remove();
+                if (!seen.add(key(at.x(), at.z())) || Math.hypot(at.x() - center.x(), at.z() - center.z()) > 12
+                    || !riverRock(at.x(), at.z(), level)) continue;
+                boolean retained = true;
+                for (int[] d : CARDINALS) retained &= solid(at.x() + d[0], level, at.z() + d[1]);
+                if (!retained) continue;
+                result.add(key(at.x(), at.z()));
+                for (int[] d : CARDINALS) {
+                    int x = at.x() + d[0], z = at.z() + d[1];
+                    queue.add(new Node(x, z, Math.hypot(x - center.x(), z - center.z())
+                        + field(x, z, 8, 411) * 6 + Math.max(0, column(x,z).top() - level) * .4));
+                }
+            }
+            return result;
+        }
+
+        private boolean riverRock(int x, int z, int level) {
+            Column rock = column(x, z);
+            return rock.top() >= level && rock.top() <= level + 12 && rock.solidBottom() <= level - 8;
+        }
+
+        private List<Point> longestRoute(Set<Long> allowed, int level) {
+            Set<Long> remaining = new HashSet<>(allowed);
+            List<Point> longest = List.of();
+            while (!remaining.isEmpty()) {
+                long start = remaining.stream().min(Long::compare).orElseThrow();
+                Map<Long, Long> first = routeTree(start, allowed);
+                remaining.removeAll(first.keySet());
+                if (first.size() < 36) continue;
+                long far = lastKey(first);
+                Map<Long, Long> second = routeTree(far, first.keySet());
+                long end = lastKey(second);
+                Map<Long, Long> shaped = riverRouteTree(far, end, first.keySet(), level);
+                List<Point> path = new ArrayList<>();
+                for (long at = end; ; at = shaped.get(at)) {
+                    path.add(point(at));
+                    if (at == far) break;
+                }
+                if (path.size() > longest.size()) longest = path;
+            }
+            return longest;
+        }
+
+        private Map<Long, Long> riverRouteTree(long start, long end, Set<Long> allowed, int level) {
+            Map<Long, Long> parent = new HashMap<>();
+            Map<Long, Double> costs = new HashMap<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            Point origin = point(start);
+            parent.put(start, start); costs.put(start, 0.0); queue.add(new Node(origin.x(), origin.z(), 0));
+            while (!queue.isEmpty()) {
+                Node at = queue.remove();
+                long current = key(at.x(), at.z());
+                if (at.cost() > costs.getOrDefault(current, Double.POSITIVE_INFINITY)) continue;
+                if (current == end) break;
+                for (int[] d : NEIGHBORS) {
+                    int x = at.x() + d[0] * 4, z = at.z() + d[1] * 4;
+                    long next = key(x, z);
+                    if (!allowed.contains(next)) continue;
+                    double cost = at.cost() + Math.hypot(d[0], d[1]) * (1 + Math.max(0, column(x,z).top() - level) * .14
+                        + field(x, z, 27, 8113) * 1.8);
+                    if (cost >= costs.getOrDefault(next, Double.POSITIVE_INFINITY)) continue;
+                    parent.put(next, current); costs.put(next, cost); queue.add(new Node(x,z,cost));
+                }
+            }
+            return parent;
+        }
+
+        private List<Point> smoothRoute(List<Point> coarsePath) {
+            record Smooth(double x, double z) {}
+            List<Smooth> values = coarsePath.stream().map(p -> new Smooth(p.x(), p.z())).toList();
+            // Bend over several grid steps rather than rounding each voxel-sized corner.
+            for (int pass = 0; pass < 2; pass++) {
+                List<Smooth> next = new ArrayList<>();
+                for (int i = 0; i < values.size(); i++) {
+                    if (i == 0 || i == values.size() - 1) { next.add(values.get(i)); continue; }
+                    double x = 0, z = 0, sum = 0;
+                    for (int offset = -4; offset <= 4; offset++) {
+                        int weight = 5 - Math.abs(offset);
+                        Smooth p = values.get(Math.clamp(i + offset, 0, values.size() - 1));
+                        x += p.x() * weight; z += p.z() * weight; sum += weight;
+                    }
+                    next.add(new Smooth(x / sum, z / sum));
+                }
+                values = next;
+            }
+            for (int pass = 0; pass < 2; pass++) {
+                List<Smooth> next = new ArrayList<>(); next.add(values.getFirst());
+                for (int i = 1; i < values.size(); i++) {
+                    Smooth a = values.get(i - 1), b = values.get(i);
+                    next.add(new Smooth(a.x() * .75 + b.x() * .25, a.z() * .75 + b.z() * .25));
+                    next.add(new Smooth(a.x() * .25 + b.x() * .75, a.z() * .25 + b.z() * .75));
+                }
+                next.add(values.getLast()); values = next;
+            }
+            List<Point> path = new ArrayList<>();
+            for (int i = 1; i < values.size(); i++) {
+                Smooth a = values.get(i - 1), b = values.get(i);
+                int steps = Math.max(1, (int) Math.ceil(Math.max(Math.abs(b.x() - a.x()), Math.abs(b.z() - a.z()))));
+                for (int step = 0; step <= steps; step++) {
+                    double t = step / (double) steps;
+                    Point p = new Point((int) Math.round(a.x() + (b.x() - a.x()) * t), (int) Math.round(a.z() + (b.z() - a.z()) * t));
+                    if (path.isEmpty() || !path.getLast().equals(p)) path.add(p);
+                }
+            }
+            return path;
+        }
+
+        private Map<Long, Long> routeTree(long start, Set<Long> allowed) {
+            Map<Long, Long> parent = new LinkedHashMap<>();
+            ArrayDeque<Long> queue = new ArrayDeque<>();
+            parent.put(start, start); queue.add(start);
+            while (!queue.isEmpty()) {
+                long current = queue.removeFirst();
+                Point at = point(current);
+                for (int[] d : NEIGHBORS) {
+                    long next = key(at.x() + d[0] * 4, at.z() + d[1] * 4);
+                    if (allowed.contains(next) && !parent.containsKey(next)) { parent.put(next, current); queue.addLast(next); }
+                }
+            }
+            return parent;
+        }
+
+        private long lastKey(Map<Long, Long> values) {
+            long result = 0;
+            for (long key : values.keySet()) result = key;
+            return result;
+        }
+
+        /** A real spring emerges from one of the river's taller rock banks and drops into the
+         * connected retained channel. The source replaces rock; its mouth is the carved valley. */
+        private void addRiverSpring() {
+            Feature river = features.stream().filter(f -> f.kind() == Kind.RIVER).findFirst().orElse(null);
+            if (river == null) return;
+            List<Cell> bank = cells.values().stream().filter(c -> c.featureId() == river.id())
+                .sorted(Comparator.comparingInt(Cell::carveTop).reversed().thenComparingInt(Cell::x).thenComparingInt(Cell::z)).toList();
+            for (Cell wet : bank) for (int[] d : CARDINALS) {
+                int x = wet.x() + d[0], z = wet.z() + d[1];
+                if (cells.containsKey(key(x, z))) continue;
+                for (int height : new int[]{8, 7, 6, 5}) {
+                    int y = wet.waterY() + height;
+                    if (wet.carveTop() < y) continue;
+                    Position source = new Position(x, y, z), outlet = new Position(wet.x(), y, wet.z());
+                    boolean safe = true;
+                    for (int sy = y - 3; sy <= y + 1; sy++) safe &= flowSolid(new Position(x, sy, z), outlet);
+                    for (int[] side : CARDINALS) {
+                        if (side[0] == -d[0] && side[1] == -d[1]) continue;
+                        safe &= flowSolid(new Position(x + side[0], y, z + side[1]), outlet);
+                    }
+                    if (!safe) continue;
+                    Flow flow = traceSpring(source, outlet);
+                    if (flow == null || flow.volume().stream().noneMatch(p -> {
+                        Cell c = cells.get(key(p.x(), p.z()));
+                        return c != null && c.featureId() == river.id() && p.y() <= c.waterY() && p.y() > c.bedY();
+                    })) continue;
+                    long id = mix(seed ^ 0xA81BE2L);
+                    springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                    springFlow.addAll(flow.volume());
+                    return;
+                }
+            }
+        }
+
+        private List<Candidate> candidates() {
+            for (int x = -RADIUS; x <= RADIUS; x += GRID) {
+                for (int z = -RADIUS; z <= RADIUS; z += GRID) {
+                    if (inside(x, z, RADIUS)) coarse.put(key(x, z), coarseTop(x, z));
+                }
+            }
+            List<Candidate> result = new ArrayList<>();
+            for (int x = -RADIUS + GRID; x < RADIUS; x += GRID) {
+                for (int z = -RADIUS + GRID; z < RADIUS; z += GRID) {
+                    int height = coarse.getOrDefault(key(x, z), -1);
+                    if (height < 64 || !inside(x, z, RADIUS - 24)) continue;
+                    double average = 0;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        int neighbor = coarse.getOrDefault(key(x + d[0] * GRID, z + d[1] * GRID), -1);
+                        if (neighbor < 64 || Math.abs(neighbor - height) > 16) safe = false;
+                        average += neighbor * 0.25;
+                    }
+                    if (safe) result.add(new Candidate(x, z,
+                        (average - height) * 2.0 + random(seed + 2, x, z) * 3.0));
+                }
+            }
+            result.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z));
+            return result;
+        }
+
+        private int coarseTop(int x, int z) {
+            for (int y = 383; y >= 32; y -= 4) if (solid(x, y, z)) return y;
+            return -1;
+        }
+
+        private Column column(int x, int z) {
+            long key = key(x, z);
+            Column old = columns.get(key);
+            if (old != null) return old;
+            int top = -1;
+            // Exact scan, including everything above the planned water: a cave roof cannot be
+            // mistaken for a surface. Only candidates and their nearby shore need this refinement.
+            for (int y = 383; y >= 24; y--) {
+                if (solid(x, y, z)) { top = y; break; }
+            }
+            int bottom = top;
+            if (top >= 0) {
+                while (bottom > Math.max(16, top - 40) && solid(x, bottom - 1, z)) bottom--;
+            }
+            Column created = new Column(top, bottom);
+            columns.put(key, created);
+            return created;
+        }
+
+        private boolean eligible(int x, int z, int level) {
+            if (level < 32 || level >= 383 || !inside(x, z, RADIUS - 2)) return false;
+            Cell old = cells.get(key(x, z));
+            if (old != null && old.hasWater() && old.waterY() != level) return false;
+            Column column = column(x, z);
+            return column.top() >= level - 3 && column.top() < level + 6
+                && column.solidBottom() <= Math.min(column.top(), level - 1) - 4;
+        }
+
+        private Set<Long> growBasin(Point center, int level, int target) {
+            if (!eligible(center.x(), center.z(), level)) return null;
+            Set<Long> wet = new HashSet<>();
+            Map<Long, Double> costs = new HashMap<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            queue.add(new Node(center.x(), center.z(), 0));
+            costs.put(key(center.x(), center.z()), 0.0);
+            while (!queue.isEmpty() && wet.size() < target) {
+                Node current = queue.remove();
+                if (current.cost() > costs.getOrDefault(key(current.x(), current.z()), Double.POSITIVE_INFINITY)) continue;
+                if (!eligible(current.x(), current.z(), level)) continue;
+                wet.add(key(current.x(), current.z()));
+                for (int[] d : NEIGHBORS) {
+                    int x = current.x() + d[0], z = current.z() + d[1];
+                    if (Math.hypot(x - center.x(), z - center.z()) > 40 || wet.contains(key(x, z))) continue;
+                    if (!eligible(x, z, level)) continue;
+                    double step = Math.hypot(d[0], d[1]);
+                    double cost = current.cost() + step * (1 + Math.max(0, column(x, z).top() - level) * 0.8
+                        + terrainNoise(x, z) * 4.5 + field(x + 71, z - 93, 21, 107) * 3.5);
+                    if (cost >= costs.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    costs.put(key(x, z), cost);
+                    queue.add(new Node(x, z, cost));
+                }
+            }
+            wet = connectedTo(wet, key(center.x(), center.z()));
+            if (wet.size() < Math.min(target, 30)) return null;
+            // Filling a hollow requires every lower connected outlet to be included. Abort rather
+            // than place a dam if this natural basin runs to a cliff, cave or an oversized catchment.
+            List<Long> work = new ArrayList<>(wet);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    int x = point.x() + d[0], z = point.z() + d[1];
+                    long neighbor = key(x, z);
+                    if (wet.contains(neighbor) || column(x, z).top() >= level) continue;
+                    if (wet.size() >= 1200 || Math.hypot(x - center.x(), z - center.z()) > 48
+                        || !eligible(x, z, level)) return null;
+                    wet.add(neighbor);
+                    work.add(neighbor);
+                }
+            }
+            return wet;
+        }
+
+        private Map<Long, Cell> waterCells(Set<Long> footprint, int level, long id) {
+            Map<Long, Cell> result = new HashMap<>();
+            for (long key : footprint) {
+                Point p = point(key);
+                if (!eligible(p.x(), p.z(), level)) return null;
+                boolean edge = false;
+                for (int[] d : CARDINALS) edge |= !footprint.contains(key(p.x() + d[0], p.z() + d[1]));
+                Column column = column(p.x(), p.z());
+                int depth = Math.max(level - column.top() + 1, edge ? 1 : 2 + (terrainNoise(p.x(), p.z()) > 0.55 ? 1 : 0));
+                depth = Math.min(depth, 8 - Math.max(0, column.top() - level));
+                if (depth < 1 || depth > MAX_DEPTH) return null;
+                int bed = level - depth;
+                if (column.top() < bed || column.solidBottom() > bed - 2) return null;
+                ShoreMaterial material = wetMaterial(p.x(), p.z(), edge);
+                int sedimentDepth = sedimentDepth(p.x(), p.z());
+                if (column.solidBottom() > bed - sedimentDepth - 1) return null;
+                result.put(key, new Cell(p.x(), p.z(), level, bed, Math.max(level, column.top()),
+                    material, id, sedimentDepth));
+            }
+            return result;
+        }
+
+        /** Deepen only sufficiently thick interiors, with one-block shore steps. Natural weak
+         * columns keep a shallower bed instead of receiving a manufactured lake foundation. */
+        private Map<Long, Cell> lakeCells(Set<Long> footprint, int level, long id) {
+            Map<Long, Integer> distance = new HashMap<>();
+            ArrayDeque<Long> queue = new ArrayDeque<>();
+            for (long k : footprint) {
+                Point at = point(k);
+                for (int[] d : CARDINALS) if (!footprint.contains(key(at.x() + d[0], at.z() + d[1]))) {
+                    distance.put(k, 0); queue.addLast(k); break;
+                }
+            }
+            while (!queue.isEmpty()) {
+                long k = queue.removeFirst(); Point at = point(k);
+                for (int[] d : CARDINALS) {
+                    long next = key(at.x() + d[0], at.z() + d[1]);
+                    if (footprint.contains(next) && !distance.containsKey(next)) {
+                        distance.put(next, distance.get(k) + 1); queue.addLast(next);
+                    }
+                }
+            }
+            Map<Long, Cell> result = new HashMap<>();
+            for (long k : footprint) {
+                Point at = point(k);
+                if (!eligible(at.x(), at.z(), level)) return null;
+                Column rock = column(at.x(), at.z());
+                int sediment = sedimentDepth(at.x(), at.z());
+                int wanted = Math.max(level - rock.top() + 1, Math.min(MAX_DEPTH, 1 + distance.get(k)));
+                int depth = Math.min(wanted, Math.min(level - rock.solidBottom() - sediment - 1,
+                    MAX_LAKE_CARVE - Math.max(0, rock.top() - level)));
+                if (depth < 1 || rock.top() < level - depth) return null;
+                int bed = level - depth;
+                result.put(k, new Cell(at.x(), at.z(), level, bed, Math.max(level, rock.top()),
+                    wetMaterial(at.x(), at.z(), distance.get(k) == 0), id, sediment));
+            }
+            return result;
+        }
+
+        private boolean contained(Map<Long, Cell> wet) {
+            for (Cell cell : wet.values()) {
+                for (int y = cell.bedY() - 2; y <= cell.bedY(); y++) {
+                    if (!solid(cell.x(), y, cell.z())) return false;
+                }
+                for (int[] d : CARDINALS) {
+                    int x = cell.x() + d[0], z = cell.z() + d[1];
+                    Cell neighbor = wet.get(key(x, z));
+                    if (neighbor == null) neighbor = cells.get(key(x, z));
+                    for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) {
+                        if (neighbor != null && neighbor.hasWater()) {
+                            if (neighbor.waterY() != cell.waterY()) return false;
+                            if (y > neighbor.bedY()) continue;
+                        }
+                        if (!solid(x, y, z)) return false;
+                    }
+                }
+            }
+            return true;
+        }
+
+        private void addFeature(long id, Kind kind, int level, List<Point> path, Map<Long, Cell> wet) {
+            int minX = Integer.MAX_VALUE, minZ = Integer.MAX_VALUE, maxX = Integer.MIN_VALUE, maxZ = Integer.MIN_VALUE;
+            int count = 0;
+            for (Cell cell : wet.values()) {
+                Cell old = cells.get(key(cell.x(), cell.z()));
+                if (old == null || !old.hasWater()) { cells.put(key(cell.x(), cell.z()), cell); count++; }
+                minX = Math.min(minX, cell.x()); minZ = Math.min(minZ, cell.z());
+                maxX = Math.max(maxX, cell.x()); maxZ = Math.max(maxZ, cell.z());
+            }
+            features.add(new Feature(id, kind, level, path, count, new Bounds(minX, minZ, maxX, maxZ)));
+        }
+
+        private static Set<Long> connectedTo(Set<Long> footprint, long start) {
+            Set<Long> connected = new HashSet<>();
+            List<Long> work = new ArrayList<>();
+            connected.add(start); work.add(start);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    long next = key(point.x() + d[0], point.z() + d[1]);
+                    if (footprint.contains(next) && connected.add(next)) work.add(next);
+                }
+            }
+            return connected;
+        }
+
+        private record ShoreNode(int x, int z, int level, long feature, double cost) {}
+
+        /** Sediment follows shallow topography in broad, discontinuous sheets. A second nearby
+         * pocket can share the same sheet; the result is not a one-block material ring. */
+        private void addSedimentSheets() {
+            Comparator<ShoreNode> order = Comparator.comparingDouble(ShoreNode::cost)
+                .thenComparingInt(ShoreNode::x).thenComparingInt(ShoreNode::z).thenComparingLong(ShoreNode::feature);
+            Set<Long> rivers = features.stream().filter(f -> f.kind() == Kind.RIVER).map(Feature::id)
+                .collect(java.util.stream.Collectors.toSet());
+            PriorityQueue<ShoreNode> queue = new PriorityQueue<>(order);
+            Map<Long, Double> best = new HashMap<>();
+            for (Cell cell : cells.values()) if (cell.hasWater()) {
+                queue.add(new ShoreNode(cell.x(), cell.z(), cell.waterY(), cell.featureId(), 0));
+                best.put(key(cell.x(), cell.z()), 0.0);
+            }
+            while (!queue.isEmpty()) {
+                ShoreNode node = queue.remove();
+                if (node.cost() > best.getOrDefault(key(node.x(), node.z()), Double.POSITIVE_INFINITY)) continue;
+                boolean riverBank = rivers.contains(node.feature());
+                Column column = column(node.x(), node.z());
+                Cell existing = cells.get(key(node.x(), node.z()));
+                if (existing == null) {
+                    boolean springRock = springs.stream().anyMatch(spring ->
+                        Math.abs(spring.source().x() - node.x()) <= 4 && Math.abs(spring.source().z() - node.z()) <= 4);
+                    if (springRock) continue;
+                    double extent = riverBank ? 18 + field(node.x(), node.z(), 25, 131) * 6
+                        : 9 + field(node.x(), node.z(), 25, 131) * 10;
+                    if (node.cost() > extent) continue;
+                    int delta = column.top() - node.level();
+                    if (delta < 0 || delta > (riverBank ? 14 : 5)) continue;
+                    // Low shore: waterline, then one-block steps. Cut at most two existing blocks;
+                    // far deposits keep the original landform and feather back into grass/stone.
+                    int terrace = node.level() + (int) Math.floor(node.cost() / (riverBank ? 2.5 : 4.5));
+                    int cut = riverBank ? MAX_RIVER_BANK_CARVE : 2;
+                    int bed = Math.max(node.level(), Math.max(column.top() - cut, Math.min(column.top(), terrace)));
+                    int depth = sedimentDepth(node.x(), node.z());
+                    if (column.solidBottom() > bed - depth - 1) continue;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        Cell next = cells.get(key(node.x() + d[0], node.z() + d[1]));
+                        if (next != null && next.hasWater() && bed < next.waterY()) safe = false;
+                    }
+                    if (!safe) continue;
+                    ShoreMaterial material = dryMaterial(node.x(), node.z(), node.cost() / extent);
+                    cells.put(key(node.x(), node.z()), new Cell(node.x(), node.z(), -1, bed,
+                        column.top(), material, node.feature(), depth));
+                }
+                for (int[] d : NEIGHBORS) {
+                    int x = node.x() + d[0], z = node.z() + d[1];
+                    if (!inside(x, z, RADIUS - 2)) continue;
+                    Cell water = cells.get(key(x, z));
+                    if (water != null && water.hasWater()) continue;
+                    Column next = column(x, z);
+                    if (next.top() < node.level() || next.top() > node.level() + (riverBank ? 14 : 5)) continue;
+                    double cost = node.cost() + Math.hypot(d[0], d[1])
+                        * (0.7 + Math.abs(next.top() - column.top()) * 0.32 + field(x, z, 12, 211) * 0.6);
+                    if (cost > (riverBank ? 24 : 19) || cost >= best.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    best.put(key(x, z), cost);
+                    queue.add(new ShoreNode(x, z, node.level(), node.feature(), cost));
+                }
+            }
+        }
+
+        private int sedimentDepth(int x, int z) { return 3 + (int) (field(x, z, 15, 319) * 2.999); }
+
+        private ShoreMaterial wetMaterial(int x, int z, boolean edge) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            if (geology < 0.46) return ShoreMaterial.STONE;
+            if (geology < 0.65) return ShoreMaterial.GRAVEL;
+            if (!edge && geology > 0.78) return ShoreMaterial.CLAY;
+            return ShoreMaterial.SAND;
+        }
+
+        private ShoreMaterial dryMaterial(int x, int z, double distance) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            double grass = field(x + 103, z - 137, 19, 521);
+            if (grass > 0.62 || distance > 0.60 + grass * 0.65) return ShoreMaterial.GRASS;
+            if (geology < 0.46) return ShoreMaterial.STONE;
+            if (geology < 0.65) return ShoreMaterial.GRAVEL;
+            return ShoreMaterial.SAND;
+        }
+
+        private record Cliff(int x, int z, int dx, int dz, double score) {}
+        private record FlowNode(Position position, int reach) {}
+        private record Flow(Set<Position> volume, List<Position> path, FlowBounds bounds) {}
+
+        /** Pick rare exposed rock niches at the edges of real upper surfaces. The source replaces
+         * one rock block under an existing roof. Its outlet is already air over an eight-block drop;
+         * no source, shelf, dam, rock column or ocean is ever placed in empty terrain. */
+        private void addSprings() {
+            List<Cliff> cliffs = new ArrayList<>();
+            for (int x = -264; x <= 264; x += GRID) for (int z = -264; z <= 264; z += GRID) {
+                if (!inside(x, z, 264)) continue;
+                int top = coarse.computeIfAbsent(key(x, z), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                if (top < 88) continue;
+                for (int[] d : CARDINALS) {
+                    int nx = x + d[0] * GRID, nz = z + d[1] * GRID;
+                    int lower = coarse.computeIfAbsent(key(nx, nz), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                    if (top - lower < 16) continue;
+                    cliffs.add(new Cliff(x, z, d[0], d[1],
+                        Math.min(64, top - lower) * 0.06 + random(seed + 811, x + d[0], z + d[1]) * 3));
+                }
+            }
+            cliffs.sort(Comparator.comparingDouble(Cliff::score).reversed()
+                .thenComparingInt(Cliff::x).thenComparingInt(Cliff::z)
+                .thenComparingInt(Cliff::dx).thenComparingInt(Cliff::dz));
+            int attempts = 0;
+            for (Cliff cliff : cliffs) {
+                if (springs.size() >= 3 || attempts++ >= 160) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2, -4, 4}) {
+                    for (int along = 0; along < GRID; along++) {
+                        int x = cliff.x() + cliff.dx() * along - cliff.dz() * tangent;
+                        int z = cliff.z() + cliff.dz() * along + cliff.dx() * tangent;
+                        if (!inside(x, z, 266)) continue;
+                        int ox = x + cliff.dx(), oz = z + cliff.dz();
+                        Column rock = column(x, z), outletColumn = column(ox, oz);
+                        if (rock.top() < 80 || rock.top() - outletColumn.top() < 14) continue;
+                        // Five blocks below the highest natural surface is below the soil cap.
+                        int floor = Math.max(64, Math.max(rock.top() - 20, outletColumn.top() + 8));
+                        for (int y = rock.top() - 5; y >= floor; y -= 3) {
+                            Position source = new Position(x, y, z), outlet = new Position(ox, y, oz);
+                            if (!separatedSpring(source) || !springNiche(source, cliff.dx(), cliff.dz()) || nearModifiedGround(source, 32)) continue;
+                            Flow flow = traceSpring(source, outlet);
+                            if (flow == null || flow.bounds().minY() > y - 12) continue;
+                            long id = mix(seed ^ (0x5F81A6L + springs.size() * 0x9E3779B97F4A7C15L));
+                            springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                            springFlow.addAll(flow.volume());
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+        }
+
+        private boolean nearModifiedGround(Position source, int distance) {
+            for (Cell cell : cells.values()) {
+                int dy = Math.max(Math.max(cell.bedY() - cell.sedimentDepth() - source.y(), 0),
+                    source.y() - cell.carveTop());
+                long dx = source.x() - cell.x(), dz = source.z() - cell.z();
+                if (dx * dx + dz * dz + (long) dy * dy < (long) distance * distance) return true;
+            }
+            return false;
+        }
+
+        private boolean separatedSpring(Position source) {
+            for (Spring spring : springs) {
+                double horizontal = Math.hypot(source.x() - spring.source().x(), source.z() - spring.source().z());
+                int dy = Math.abs(source.y() - spring.source().y());
+                if (Math.hypot(horizontal, dy) < 64 || dy < 12) return false;
+            }
+            return true;
+        }
+
+        private record Wall(int x, int y, int z, int dx, int dz, double score) {}
+
+        /** Probe a few exposed faces below the highest surface as well. This finds overhangs and
+         * lower strata that a highest-column heightmap cannot represent, without inventing a ledge. */
+        private void addLowerWallSprings() {
+            List<Wall> candidates = new ArrayList<>();
+            for (int x = -240; x <= 240; x += 16) for (int z = -240; z <= 240; z += 16) {
+                if (!inside(x, z, 240)) continue;
+                int top = coarse.computeIfAbsent(key(x, z), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                for (int y = top - 32; y >= 64; y -= 16) {
+                    if (!solid(x, y, z)) continue;
+                    for (int[] direction : CARDINALS) {
+                        if (solid(x + direction[0] * 4, y, z + direction[1] * 4)) continue;
+                        candidates.add(new Wall(x, y, z, direction[0], direction[1],
+                            random(seed + 1217 + y, x + direction[0], z + direction[1]) * 3
+                                + Math.min(100, top - y) * 0.015));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Wall::score).reversed()
+                .thenComparingInt(Wall::x).thenComparingInt(Wall::z).thenComparingInt(Wall::y)
+                .thenComparingInt(Wall::dx).thenComparingInt(Wall::dz));
+            int attempts = 0;
+            for (Wall candidate : candidates) {
+                if (springs.size() >= 2 || attempts++ >= 96) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2}) {
+                    for (int along = 0; along < 4; along++) {
+                        int x = candidate.x() + candidate.dx() * along - candidate.dz() * tangent;
+                        int z = candidate.z() + candidate.dz() * along + candidate.dx() * tangent;
+                        for (int dy : new int[]{0, 3, -3, 6, -6}) {
+                            int y = candidate.y() + dy;
+                            if (y < 56 || column(x, z).top() - y < 24) continue;
+                            Position source = new Position(x, y, z);
+                            if (!separatedSpring(source) || !springNiche(source, candidate.dx(), candidate.dz())
+                                || nearModifiedGround(source, 32)) continue;
+                            Position outlet = new Position(x + candidate.dx(), y, z + candidate.dz());
+                            Flow flow = traceSpring(source, outlet);
+                            if (flow == null || flow.bounds().minY() > y - 12) continue;
+                            long id = mix(seed ^ (0x5F81A6L + springs.size() * 0x9E3779B97F4A7C15L));
+                            springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                            springFlow.addAll(flow.volume());
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+        }
+
+        private boolean springNiche(Position source, int dx, int dz) {
+            for (int y = source.y() - 3; y <= source.y() + 1; y++) {
+                if (!solid(source.x(), y, source.z())) return false;
+            }
+            for (int[] d : CARDINALS) {
+                if (d[0] == dx && d[1] == dz) continue;
+                if (!solid(source.x() + d[0], source.y(), source.z() + d[1])) return false;
+            }
+            for (int y = source.y(); y >= source.y() - 8; y--) {
+                if (solid(source.x() + dx, y, source.z() + dz)) return false;
+            }
+            return true;
+        }
+
+        /** Predict drainage through undecorated rock to select springs and inspection bounds.
+         * Descend through air first, then explore seven horizontal steps on a shelf. Later trees
+         * can divert the actual fluid: this prediction is not a bound on decorated-world physics.
+         * Integration tests trace actual water back to its source within the inspected chunk halo. */
+        private Flow traceSpring(Position source, Position outlet) {
+            Map<Position, Integer> reach = new HashMap<>();
+            Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<FlowNode> queue = new ArrayDeque<>();
+            reach.put(source, 7);
+            queue.add(new FlowNode(source, 7));
+            Position lowest = source;
+            while (!queue.isEmpty()) {
+                FlowNode node = queue.removeFirst();
+                Position at = node.position();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 24000) return null;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (!flowSolid(below, source)) {
+                    enqueueFlow(below, 7, at, queue, reach, parent);
+                    continue;
+                }
+                if (node.reach() <= 0) continue;
+                for (int[] d : CARDINALS) {
+                    Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+                    if (flowSolid(next, source)) continue;
+                    enqueueFlow(next, node.reach() - 1, at, queue, reach, parent);
+                }
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY;
+            int minZ = source.z(), maxZ = minZ;
+            for (Position position : reach.keySet()) {
+                minX = Math.min(minX, position.x()); maxX = Math.max(maxX, position.x());
+                minY = Math.min(minY, position.y()); maxY = Math.max(maxY, position.y());
+                minZ = Math.min(minZ, position.z()); maxZ = Math.max(maxZ, position.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Flow(Set.copyOf(reach.keySet()), path, new FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Position source) {
+            if (at.equals(source)) return false;
+            Cell cell = cells.get(key(at.x(), at.z()));
+            if (cell != null && at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            return solid(at.x(), at.y(), at.z());
+        }
+
+        private static void enqueueFlow(Position next, int available, Position from, ArrayDeque<FlowNode> queue,
+                                        Map<Position, Integer> reach, Map<Position, Position> parent) {
+            if (available <= reach.getOrDefault(next, -1)) return;
+            if (!reach.containsKey(next)) parent.put(next, from);
+            reach.put(next, available);
+            queue.addLast(new FlowNode(next, available));
+        }
+
+        private boolean nearWater(int x, int z, int distance) {
+            for (Feature feature : features) {
+                Point point = feature.path().getFirst();
+                if (Math.hypot(x - point.x(), z - point.z()) < distance) return true;
+            }
+            return false;
+        }
+
+        private boolean solid(int x, int y, int z) { samples++; return sampler.sample(x, y, z) > 0; }
+        private long featureId(int index) { return mix(seed ^ (0x51A7E7L + index * 0x9E3779B97F4A7C15L)); }
+
+        private double terrainNoise(int x, int z) { return field(x, z, 8, 31); }
+
+        private double field(int x, int z, int scale, long salt) {
+            int gx = Math.floorDiv(x, scale), gz = Math.floorDiv(z, scale);
+            double tx = smooth(Math.floorMod(x, scale) / (double) scale);
+            double tz = smooth(Math.floorMod(z, scale) / (double) scale);
+            double a = random(seed + salt, gx, gz) * (1 - tx) + random(seed + salt, gx + 1, gz) * tx;
+            double b = random(seed + salt, gx, gz + 1) * (1 - tx) + random(seed + salt, gx + 1, gz + 1) * tx;
+            return a * (1 - tz) + b * tz;
+        }
+    }
+
+    private static boolean inside(int x, int z, int radius) { return Math.hypot((double) x, z) < radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static Point point(long key) { return new Point((int) (key >> 32), (int) key); }
+    private static double smooth(double t) { return t * t * (3 - 2 * t); }
+    private static double random(long seed, int x, int z) { return (mix(seed ^ key(x, z)) >>> 11) * 0x1.0p-53; }
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernHydrologyRuntime.java

@@ -0,0 +1,191 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Map;
+import java.util.WeakHashMap;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+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.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+
+/** Alpha.9 only: immutable plans cached by world state, applied to fresh terrain before decoration. */
+public final class CavernHydrologyRuntime {
+    private static final Map<RandomState, CavernHydrology.Plan> PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+    private static final Map<RandomState, CavernLavaDeposit.Plan> LAVA_PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+
+    private CavernHydrologyRuntime() {}
+
+    public static boolean enabled(NoiseBasedChunkGenerator generator) {
+        return generator.generatorSettings().is(SanctuarySpawn.CAVERN_SETTINGS);
+    }
+
+    public static CavernHydrology.Plan cavernPlan(ServerLevel level) {
+        return plan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static CavernHydrology.Plan plan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        if (!enabled(generator)) throw new IllegalArgumentException("Cavern hydrology is not enabled for this generator");
+        return PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var plan = CavernHydrology.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z));
+            SanctuaryMod.LOGGER.info("Sanctuary cavern hydrology: seed {}, {} features, {} columns, {} springs, {} ms",
+                state.seed(), plan.features().size(), plan.cells().size(), plan.springs().size(),
+                (System.nanoTime() - start) / 1_000_000);
+            SanctuaryMod.LOGGER.info("Sanctuary cavern catchments: {}", plan.features().stream().map(f -> f.kind() + " Y" + f.waterY() + " water=" + f.waterCells() + " path=" + f.path().size() + " " + f.bounds()).toList());
+            return plan;
+        });
+    }
+
+    public static CavernLavaDeposit.Plan lavaPlan(ServerLevel level) {
+        return lavaPlan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static CavernLavaDeposit.Plan lavaPlan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        // Acquire the water plan before the lava cache lock; the water planner never acquires it.
+        var water = plan(generator, randomState);
+        return LAVA_PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var lava = CavernLavaDeposit.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z), water);
+            SanctuaryMod.LOGGER.info("Sanctuary starter lava: seed {}, {} sources, access {}, {} ms",
+                state.seed(), lava.lavaCells().size(), lava.access(), (System.nanoTime() - start) / 1_000_000);
+            return lava;
+        });
+    }
+
+    public static void apply(NoiseBasedChunkGenerator generator, RandomState randomState, ChunkAccess chunk) {
+        if (!enabled(generator)) return;
+        var chunkPos = chunk.getPos();
+        if (Math.abs((long) chunkPos.x() * 16) > IslandShape.TERRAIN_LIMIT + 16L
+                || Math.abs((long) chunkPos.z() * 16) > IslandShape.TERRAIN_LIMIT + 16L) return;
+        var plan = plan(generator, randomState);
+        var cells = plan.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var springs = plan.springsInChunk(chunkPos.x(), chunkPos.z());
+        var outlets = new java.util.ArrayList<>(plan.springs().stream().map(CavernHydrology.Spring::outlet)
+            .filter(outlet -> (outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z()).toList());
+        for (var spill : plan.spills()) {
+            var outlet = spill.outlet();
+            if ((outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z()) outlets.add(outlet);
+        }
+        var lava = lavaPlan(generator, randomState);
+        for (var fall : lava.falls()) {
+            var outlet = fall.outlet();
+            if ((outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z())
+                outlets.add(new CavernHydrology.Position(outlet.x(), outlet.y(), outlet.z()));
+        }
+        var lavaCells = lava.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var lavaSupports = lava.supportsInChunk(chunkPos.x(), chunkPos.z());
+        if (cells.isEmpty() && springs.isEmpty() && outlets.isEmpty() && lavaCells.isEmpty() && lavaSupports.isEmpty()) return;
+        BlockPos.MutableBlockPos pos = new BlockPos.MutableBlockPos();
+        // Validate all replacements and two intact support layers before modifying this chunk.
+        for (var cell : cells) {
+            for (int y = cell.bedY() - cell.sedimentDepth() - 1; y <= cell.bedY(); y++) {
+                requireSolid(chunk, pos.set(cell.x(), y, cell.z()), randomState.seed());
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            requireSolid(chunk, pos.set(source.x(), source.y(), source.z()), randomState.seed());
+        }
+        for (var support : lavaSupports) {
+            requireSolid(chunk, pos.set(support.x(), support.y(), support.z()), randomState.seed());
+            if (chunk.getBlockState(pos).ignitedByLava()) {
+                throw new IllegalStateException("Lava pocket requires nonflammable natural support at " + pos);
+            }
+        }
+        for (var cell : lavaCells) {
+            requireSolid(chunk, pos.set(cell.x(), cell.y(), cell.z()), randomState.seed());
+        }
+        for (var cell : cells) {
+            for (int depth = 0; depth < cell.sedimentDepth(); depth++) {
+                pos.set(cell.x(), cell.bedY() - depth, cell.z());
+                BlockState material = CavernMaterials.sedimentBlock(cell, randomState.seed(), depth);
+                chunk.setBlockState(pos, material, 0);
+            }
+            for (int y = cell.bedY() + 1; y <= Math.max(cell.waterY(), cell.carveTop()); y++) {
+                pos.set(cell.x(), y, cell.z());
+                chunk.setBlockState(pos, cell.hasWater() && y <= cell.waterY()
+                    ? Blocks.WATER.defaultBlockState() : Blocks.AIR.defaultBlockState(), 0);
+                if (cell.hasWater() && y <= cell.waterY()) chunk.markPosForPostProcessing(pos);
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            pos.set(source.x(), source.y(), source.z());
+            chunk.setBlockState(pos, Blocks.WATER.defaultBlockState(), 0);
+            // Only the source is generated. Vanilla fluid ticks create the descending waterfall.
+            chunk.markPosForPostProcessing(pos);
+        }
+        for (var cell : lavaCells) {
+            pos.set(cell.x(), cell.y(), cell.z());
+            chunk.setBlockState(pos, (cell.lava() ? Blocks.LAVA : Blocks.AIR).defaultBlockState(), 0);
+            if (cell.lava()) chunk.markPosForPostProcessing(pos);
+        }
+        // This existing vanilla queue is consumed after neighbouring chunks finish decoration.
+        // Mark the outlet in its own chunk, including when its source belongs to a neighbour.
+        for (var outlet : outlets) {
+            pos.set(outlet.x(), outlet.y(), outlet.z());
+            chunk.markPosForPostProcessing(pos);
+        }
+        Heightmap.primeHeightmaps(chunk, EnumSet.of(Heightmap.Types.WORLD_SURFACE_WG,
+            Heightmap.Types.OCEAN_FLOOR_WG));
+    }
+
+    /** Reserve water, sediment and hot-rock volumes before placing vegetation. */
+    public static boolean protects(NoiseBasedChunkGenerator generator, RandomState randomState, BlockPos base,
+                                   int radius, int height, int rootDepth) {
+        var water = plan(generator, randomState);
+        var lava = lavaPlan(generator, randomState);
+        int low = base.getY() - rootDepth, high = base.getY() + height;
+        for (int x = base.getX() - radius; x <= base.getX() + radius; x++) {
+            for (int z = base.getZ() - radius; z <= base.getZ() + radius; z++) {
+                for (var cell : water.cellsAt(x, z))
+                    if (low <= cell.carveTop() && high >= cell.bedY() - cell.sedimentDepth() - 1) return true;
+            }
+        }
+        for (var spring : water.springs()) {
+            var bounds = spring.flowBounds();
+            if (base.getX() + radius >= bounds.minX() - 2 && base.getX() - radius <= bounds.maxX() + 2
+                && base.getZ() + radius >= bounds.minZ() - 2 && base.getZ() - radius <= bounds.maxZ() + 2
+                && low <= bounds.maxY() + 2 && high >= bounds.minY() - 2) return true;
+            var source = spring.source();
+            if (Math.abs(base.getX() - source.x()) <= radius + 3 && Math.abs(base.getZ() - source.z()) <= radius + 3
+                && low <= source.y() + 3 && high >= source.y() - 3) return true;
+        }
+        for (var bounds : lava.flowBounds()) {
+            if (base.getX() + radius >= bounds.minX() - 8 && base.getX() - radius <= bounds.maxX() + 8
+                && base.getZ() + radius >= bounds.minZ() - 8 && base.getZ() - radius <= bounds.maxZ() + 8
+                && low <= bounds.maxY() + 8 && high >= bounds.minY() - 8) return true;
+        }
+        for (var spill : water.spills()) {
+            var bounds = spill.flowBounds();
+            if (base.getX() + radius >= bounds.minX() - 3 && base.getX() - radius <= bounds.maxX() + 3
+                && base.getZ() + radius >= bounds.minZ() - 3 && base.getZ() - radius <= bounds.maxZ() + 3
+                && low <= bounds.maxY() + 3 && high >= bounds.minY() - 3) return true;
+        }
+        for (var cell : lava.cells()) if (Math.abs(base.getX() - cell.x()) <= radius + 2 && Math.abs(base.getZ() - cell.z()) <= radius + 2
+            && low <= cell.y() + 2 && high >= cell.y() - 2) return true;
+        for (var support : lava.supports()) if (Math.abs(base.getX() - support.x()) <= radius + 2 && Math.abs(base.getZ() - support.z()) <= radius + 2
+            && low <= support.y() + 2 && high >= support.y() - 2) return true;
+        return false;
+    }
+
+    private static void requireSolid(ChunkAccess chunk, BlockPos pos, long seed) {
+        if (!chunk.getBlockState(pos).isCollisionShapeFullBlock(chunk, pos)) {
+            throw new IllegalStateException("Cavern hydrology differs from terrain at " + pos + " for seed " + seed);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernIslandBiomeSource.java

@@ -0,0 +1,99 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.stream.Stream;
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeResolver;
+import net.minecraft.world.level.biome.BiomeSource;
+import net.minecraft.world.level.biome.Climate;
+
+/** Seeded alpha.9 rift climate, separate from all saved earlier biome-source codecs. */
+public final class CavernIslandBiomeSource extends BiomeSource {
+    public static final ResourceKey<Biome> OAK_FOREST = key("cavern_oak_forest");
+    public static final ResourceKey<Biome> BIRCH_FOREST = key("cavern_birch_forest");
+    public static final ResourceKey<Biome> CLEARING = key("cavern_clearing");
+    public static final ResourceKey<Biome> DRY_WOODLAND = key("cavern_dry_woodland");
+    public static final ResourceKey<Biome> ROCKY_HEATH = key("cavern_rocky_heath");
+    public static final ResourceKey<Biome> DARK_GROVE = key("cavern_dark_grove");
+    public static final ResourceKey<Biome> BAMBOO_GROVE = key("cavern_bamboo_grove");
+    public static final ResourceKey<Biome> SULFUR_DEPTHS = key("cavern_sulfur_depths");
+    public static final ResourceKey<Biome> LUSH_CAVES = key("cavern_lush_caves");
+    public static final ResourceKey<Biome> DRIPSTONE_CAVES = key("cavern_dripstone_caves");
+
+    public static final MapCodec<CavernIslandBiomeSource> CODEC = RecordCodecBuilder.mapCodec(instance -> instance.group(
+        Biome.CODEC.fieldOf("oak_forest").forGetter(source -> source.oakForest),
+        Biome.CODEC.fieldOf("birch_forest").forGetter(source -> source.birchForest),
+        Biome.CODEC.fieldOf("clearing").forGetter(source -> source.clearing),
+        Biome.CODEC.fieldOf("dry_woodland").forGetter(source -> source.dryWoodland),
+        Biome.CODEC.fieldOf("rocky_heath").forGetter(source -> source.rockyHeath),
+        Biome.CODEC.fieldOf("dark_grove").forGetter(source -> source.darkGrove),
+        Biome.CODEC.fieldOf("bamboo_grove").forGetter(source -> source.bambooGrove),
+        Biome.CODEC.fieldOf("sulfur_depths").forGetter(source -> source.sulfurDepths),
+        Biome.CODEC.fieldOf("lush_caves").forGetter(source -> source.lushCaves),
+        Biome.CODEC.fieldOf("dripstone_caves").forGetter(source -> source.dripstoneCaves)
+    ).apply(instance, CavernIslandBiomeSource::new));
+
+    private final Holder<Biome> oakForest;
+    private final Holder<Biome> birchForest;
+    private final Holder<Biome> clearing;
+    private final Holder<Biome> dryWoodland;
+    private final Holder<Biome> rockyHeath;
+    private final Holder<Biome> darkGrove;
+    private final Holder<Biome> bambooGrove;
+    private final Holder<Biome> sulfurDepths;
+    private final Holder<Biome> lushCaves;
+    private final Holder<Biome> dripstoneCaves;
+
+    public CavernIslandBiomeSource(Holder<Biome> oakForest, Holder<Biome> birchForest, Holder<Biome> clearing,
+            Holder<Biome> dryWoodland, Holder<Biome> rockyHeath, Holder<Biome> darkGrove,
+            Holder<Biome> bambooGrove, Holder<Biome> sulfurDepths, Holder<Biome> lushCaves, Holder<Biome> dripstoneCaves) {
+        this.oakForest = oakForest;
+        this.birchForest = birchForest;
+        this.clearing = clearing;
+        this.dryWoodland = dryWoodland;
+        this.rockyHeath = rockyHeath;
+        this.darkGrove = darkGrove;
+        this.bambooGrove = bambooGrove;
+        this.sulfurDepths = sulfurDepths;
+        this.lushCaves = lushCaves;
+        this.dripstoneCaves = dripstoneCaves;
+    }
+
+    @Override
+    protected MapCodec<CavernIslandBiomeSource> codec() { return CODEC; }
+
+    @Override
+    protected Stream<Holder<Biome>> collectPossibleBiomes() {
+        return Stream.of(oakForest, birchForest, clearing, dryWoodland, rockyHeath, darkGrove, bambooGrove, sulfurDepths, lushCaves, dripstoneCaves);
+    }
+
+    @Override
+    public BiomeResolver createResolver(Climate.Sampler sampler) {
+        return (quartX, quartY, quartZ) -> {
+            int x = quartX * 4, y = quartY * 4, z = quartZ * 4;
+            float variation = sampler.temperature().sampleValue(x, 0, z);
+            float moisture = sampler.humidity().sampleValue(x, 0, z);
+            return switch (CavernBiomePalette.select(y, variation, moisture)) {
+                case OAK_FOREST -> oakForest;
+                case BIRCH_FOREST -> birchForest;
+                case CLEARING -> clearing;
+                case DRY_WOODLAND -> dryWoodland;
+                case ROCKY_HEATH -> rockyHeath;
+                case DARK_GROVE -> darkGrove;
+                case BAMBOO_GROVE -> bambooGrove;
+                case SULFUR_DEPTHS -> sulfurDepths;
+                case LUSH_CAVES -> lushCaves;
+                case DRIPSTONE_CAVES -> dripstoneCaves;
+            };
+        };
+    }
+
+    private static ResourceKey<Biome> key(String path) {
+        return ResourceKey.create(Registries.BIOME, SanctuaryMod.id(path));
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernLavaDeposit.java

@@ -0,0 +1,331 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+/** Alpha.9 lava: an optional covered pocket and up to two deep rock outlets.
+ * All sources replace natural rock; Minecraft alone produces the falling lava. */
+public final class CavernLavaDeposit {
+    public static final int RADIUS = 192;
+    public static final int WATER_CLEARANCE = 32;
+    public static final int LAVA_VOLUME = 18;
+    private static final int ENTRY_DISTANCE = 8;
+    private static final int[][] DIRECTIONS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final Comparator<Position> POSITION_ORDER = Comparator.comparingInt(Position::x)
+        .thenComparingInt(Position::z).thenComparingInt(Position::y);
+    private static final Comparator<Cell> CELL_ORDER = Comparator.comparingInt(Cell::x)
+        .thenComparingInt(Cell::z).thenComparingInt(Cell::y);
+
+    private CavernLavaDeposit() {}
+
+    public record Position(int x, int y, int z) {}
+    /** lava=false removes existing rock to open the two-block-high chamber or approach. */
+    public record Cell(int x, int y, int z, boolean lava) {}
+
+    public static final class Plan {
+        private final List<Cell> cells;
+        private final List<Cell> lavaCells;
+        private final List<Position> supports;
+        private final Optional<Position> access;
+        private final Map<Long, List<Cell>> chunks;
+        private final Map<Long, List<Position>> supportChunks;
+        private final List<CavernLavaFlows.Fall> falls;
+        private final Map<Long, List<CavernLavaFlows.Fall>> fallChunks;
+
+        private Plan(List<Cell> cells, Set<Position> supports, Position access) {
+            this(cells, supports, access, List.of());
+        }
+
+        private Plan(List<Cell> cells, Set<Position> supports, Position access, List<CavernLavaFlows.Fall> falls) {
+            this.falls = List.copyOf(falls);
+            Map<Long, List<CavernLavaFlows.Fall>> groupedFalls = new HashMap<>();
+            for (var fall : falls) groupedFalls.computeIfAbsent(
+                key(fall.source().x() >> 4, fall.source().z() >> 4), ignored -> new ArrayList<>()).add(fall);
+            groupedFalls.replaceAll((ignored, values) -> List.copyOf(values));
+            fallChunks = Map.copyOf(groupedFalls);
+            this.cells = cells.stream().sorted(CELL_ORDER).toList();
+            lavaCells = this.cells.stream().filter(Cell::lava).toList();
+            this.supports = supports.stream().sorted(POSITION_ORDER).toList();
+            this.access = Optional.ofNullable(access);
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : this.cells) byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4),
+                ignored -> new ArrayList<>()).add(cell);
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            chunks = Map.copyOf(byChunk);
+            Map<Long, List<Position>> bySupportChunk = new HashMap<>();
+            for (Position support : this.supports) bySupportChunk.computeIfAbsent(key(support.x() >> 4, support.z() >> 4),
+                ignored -> new ArrayList<>()).add(support);
+            bySupportChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            supportChunks = Map.copyOf(bySupportChunk);
+        }
+
+        public List<Cell> cells() { return cells; }
+        public List<Cell> lavaCells() { return lavaCells; }
+        public List<Position> supports() { return supports; }
+        public List<CavernLavaFlows.Fall> falls() { return falls; }
+        public List<CavernLavaFlows.Fall> fallsInChunk(int x, int z) { return fallChunks.getOrDefault(key(x, z), List.of()); }
+        public List<Position> flowSources() { return falls.stream().map(CavernLavaFlows.Fall::source).toList(); }
+        public List<CavernHydrology.FlowBounds> flowBounds() { return falls.stream().map(CavernLavaFlows.Fall::flowBounds).toList(); }
+        /** Player feet on a natural ledge, with three blocks of headroom below a roof or sky. */
+        public Optional<Position> access() { return access; }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Position> supportsInChunk(int x, int z) { return supportChunks.getOrDefault(key(x, z), List.of()); }
+    }
+
+    public static Plan create(long seed, CavernHydrology.Sampler sampler, CavernHydrology.Plan hydrology) {
+        Plan pocket = new Search(seed, sampler, hydrology).find();
+        List<CavernLavaFlows.Fall> falls = CavernLavaFlows.create(seed, sampler, hydrology, pocket);
+        List<Cell> cells = new ArrayList<>(pocket.cells());
+        Set<Position> supports = new HashSet<>(pocket.supports());
+        for (var fall : falls) {
+            Position source = fall.source();
+            cells.add(new Cell(source.x(), source.y(), source.z(), true));
+            supports.addAll(fall.supports());
+        }
+        return new Plan(cells, supports, pocket.access().orElse(null), falls);
+    }
+
+    private record Candidate(int x, int z, int dx, int dz, double score) {}
+    private record LowerCandidate(int x, int y, int z, int dx, int dz, double score) {}
+
+    private static final class Search {
+        private final long seed;
+        private final CavernHydrology.Sampler sampler;
+        private final CavernHydrology.Plan hydrology;
+        private final Map<Long, Integer> heights = new HashMap<>();
+
+        Search(long seed, CavernHydrology.Sampler sampler, CavernHydrology.Plan hydrology) {
+            this.seed = seed;
+            this.sampler = sampler;
+            this.hydrology = hydrology;
+        }
+
+        Plan find() {
+            Plan lower = findLowerPocket();
+            if (lower != null) return lower;
+            List<Candidate> candidates = new ArrayList<>();
+            for (int x = -184; x <= 184; x += 8) for (int z = -184; z <= 184; z += 8) {
+                if (!inside(x, z, RADIUS - 8)) continue;
+                int ledge = top(x, z);
+                if (ledge < 64 || ledge > 300) continue;
+                for (int[] direction : DIRECTIONS) {
+                    int cx = x - direction[0] * ENTRY_DISTANCE, cz = z - direction[1] * ENTRY_DISTANCE;
+                    if (!inside(cx, cz, RADIUS - 12) || !clearOfWater(cx, cz)) continue;
+                    int rise = top(cx, cz) - ledge;
+                    if (rise < 12) continue;
+                    candidates.add(new Candidate(x, z, direction[0], direction[1],
+                        random(seed, cx, cz) + Math.min(rise, 40) * 0.015));
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)
+                .thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (attempts++ >= 192) break;
+                // Refine the coarse edge, including a ledge lying between two eight-block samples.
+                for (int along = 0; along < 8; along++) for (int tangent : new int[]{0, -3, 3}) {
+                    int x = candidate.x() - candidate.dx() * along - candidate.dz() * tangent;
+                    int z = candidate.z() - candidate.dz() * along + candidate.dx() * tangent;
+                    Plan plan = tryNiche(x, z, candidate.dx(), candidate.dz());
+                    if (plan != null) return plan;
+                }
+            }
+            return new Plan(List.of(), Set.of(), null);
+        }
+
+        /** Prefer a real lower ledge below an overhang. The chamber uses exactly the same rock
+         * shell as the outdoor fallback; only the entrance may now have a natural ceiling. */
+        private Plan findLowerPocket() {
+            List<LowerCandidate> candidates = new ArrayList<>();
+            for (int x = -176; x <= 176; x += 16) for (int z = -176; z <= 176; z += 16) {
+                if (!inside(x, z, RADIUS - 8)) continue;
+                for (int coarseY = 64; coarseY <= 160; coarseY += 8) {
+                    if (!solid(x, coarseY, z) || solid(x, coarseY + 8, z)) continue;
+                    int level = coarseY;
+                    for (int y = coarseY + 7; y > coarseY; y--) {
+                        if (solid(x, y, z)) { level = y; break; }
+                    }
+                    if (level > 160 || top(x, z) < level + 12) continue;
+                    for (int[] direction : DIRECTIONS) {
+                        int inwardX = x - direction[0] * 16, inwardZ = z - direction[1] * 16;
+                        if (!inside(inwardX, inwardZ, RADIUS - 12)
+                            || !solid(inwardX, level + 2, inwardZ) || !solid(inwardX, level + 10, inwardZ)) continue;
+                        candidates.add(new LowerCandidate(x, level, z, direction[0], direction[1],
+                            random(seed + level + 0x108E2L, x - direction[0], z - direction[1])
+                                + (160 - level) * .002));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(LowerCandidate::score).reversed()
+                .thenComparingInt(LowerCandidate::x).thenComparingInt(LowerCandidate::z)
+                .thenComparingInt(LowerCandidate::y).thenComparingInt(LowerCandidate::dx).thenComparingInt(LowerCandidate::dz));
+            int attempts = 0;
+            for (LowerCandidate candidate : candidates) {
+                if (attempts++ >= 128) break;
+                for (int along = 0; along < 16; along++) for (int tangent : new int[]{0, -3, 3}) {
+                    int x = candidate.x() - candidate.dx() * along - candidate.dz() * tangent;
+                    int z = candidate.z() - candidate.dz() * along + candidate.dx() * tangent;
+                    for (int level = Math.min(160, candidate.y() + 5); level >= Math.max(64, candidate.y() - 5); level--) {
+                        // Reject solid cave walls and missing floors before expensive shell probes.
+                        if (!solid(x, level, z) || solid(x, level + 1, z)) continue;
+                        Plan plan = tryNiche(x, z, candidate.dx(), candidate.dz(), level, true);
+                        if (plan != null) return plan;
+                    }
+                }
+            }
+            return null;
+        }
+
+        private Plan tryNiche(int entryX, int entryZ, int dx, int dz) {
+            return tryNiche(entryX, entryZ, dx, dz, top(entryX, entryZ), false);
+        }
+
+        private Plan tryNiche(int entryX, int entryZ, int dx, int dz, int level, boolean underground) {
+            int cx = entryX - dx * ENTRY_DISTANCE, cz = entryZ - dz * ENTRY_DISTANCE;
+            if (!inside(cx, cz, RADIUS - 12) || level < 64 || level > (underground ? 160 : 300)
+                || top(cx, cz) < level + 12) return null;
+            // A lower entrance has genuine overhead island rock, but does not need a sky view.
+            if (underground && top(entryX, entryZ) < level + 12) return null;
+            int airLimit = underground ? level + 3 : 383;
+            for (int y = level + 1; y <= airLimit; y++) if (solid(entryX, y, entryZ)) return null;
+            for (int y = level - 2; y <= level; y++) if (!solid(entryX, y, entryZ)) return null;
+            if (underground ? !clearOfWater(cx, level, cz) : !clearOfWater(cx, cz)) return null;
+
+            List<Cell> cells = new ArrayList<>();
+            Set<Position> changed = new HashSet<>();
+            Set<Position> supports = new HashSet<>();
+            for (int x = cx - 1; x <= cx + 1; x++) for (int z = cz - 1; z <= cz + 1; z++) {
+                for (int y = level - 1; y <= level + 2; y++) {
+                    if (!solid(x, y, z)) return null;
+                    add(cells, changed, x, y, z, y <= level);
+                }
+            }
+            // A dry lip separates the ledge from the pool. Only the air above it is opened.
+            for (int distance = 2; distance < ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level + 1; y <= level + 2; y++) {
+                    if (solid(x, y, z)) add(cells, changed, x, y, z, false);
+                }
+            }
+            // Every carved column must lie under eight continuous natural rock blocks. This
+            // excludes soil-cap excavation at the entrance as well as exposed surface lava.
+            Map<Long, Integer> highest = new HashMap<>();
+            for (Cell cell : cells) highest.merge(key(cell.x(), cell.z()), cell.y(), Math::max);
+            for (var column : highest.entrySet()) {
+                int x = (int) (column.getKey() >> 32), z = (int) (long) column.getKey();
+                for (int y = column.getValue() + 1; y <= column.getValue() + 8; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // Three intact blocks under the pool, two-block-thick side walls, and a solid chamber
+            // surround prevent escape through an adjacent cave. No part of this shell is created.
+            for (int x = cx - 3; x <= cx + 3; x++) for (int z = cz - 3; z <= cz + 3; z++) {
+                for (int y = level - 4; y <= level + 2; y++) {
+                    if (changed.contains(new Position(x, y, z))) continue;
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // The natural roof also covers a conservative envelope around local lava fire spread.
+            // Its thickness keeps later surface vegetation well above the lava chamber.
+            for (int x = cx - 4; x <= cx + 4; x++) for (int z = cz - 4; z <= cz + 4; z++) {
+                for (int y = level + 3; y <= level + 10; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            for (int distance = 2; distance <= ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level - 2; y <= level; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            supports.removeAll(changed);
+            return new Plan(cells, supports, new Position(entryX, level + 1, entryZ));
+        }
+
+        private boolean requireRock(Set<Position> supports, int x, int y, int z) {
+            if (!solid(x, y, z)) return false;
+            supports.add(new Position(x, y, z));
+            return true;
+        }
+
+        private boolean clearOfWater(int x, int z) {
+            // The extra ten blocks include both the entrance and the complete protected shell.
+            int clearance = WATER_CLEARANCE + 10;
+            for (var cell : hydrology.cells()) {
+                long dx = x - cell.x(), dz = z - cell.z();
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            for (var spring : hydrology.springs()) {
+                var bounds = spring.flowBounds();
+                long dx = Math.max(Math.max((long) bounds.minX() - x, 0), (long) x - bounds.maxX());
+                long dz = Math.max(Math.max((long) bounds.minZ() - z, 0), (long) z - bounds.maxZ());
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            for (var spill : hydrology.spills()) {
+                var bounds = spill.flowBounds();
+                long dx = Math.max(Math.max((long) bounds.minX() - x, 0), (long) x - bounds.maxX());
+                long dz = Math.max(Math.max((long) bounds.minZ() - z, 0), (long) z - bounds.maxZ());
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            return true;
+        }
+
+        private boolean clearOfWater(int x, int level, int z) {
+            // This box covers chamber, dry approach, intact shell and roof. A lake far above is
+            // allowed; an actual waterfall crossing this level still excludes the entire pocket.
+            var pocket = new CavernHydrology.FlowBounds(x - 10, level - 4, z - 10, x + 10, level + 10, z + 10);
+            for (var cell : hydrology.cells()) {
+                var ground = new CavernHydrology.FlowBounds(cell.x(), cell.bedY() - cell.sedimentDepth() - 1,
+                    cell.z(), cell.x(), Math.max(cell.carveTop(), cell.waterY()), cell.z());
+                if (distanceSquared(pocket, ground) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spring : hydrology.springs()) {
+                if (distanceSquared(pocket, spring.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spill : hydrology.spills()) {
+                if (distanceSquared(pocket, spill.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            return true;
+        }
+
+        private static long distanceSquared(CavernHydrology.FlowBounds a, CavernHydrology.FlowBounds b) {
+            long dx = Math.max(0, Math.max((long) a.minX() - b.maxX(), (long) b.minX() - a.maxX()));
+            long dy = Math.max(0, Math.max((long) a.minY() - b.maxY(), (long) b.minY() - a.maxY()));
+            long dz = Math.max(0, Math.max((long) a.minZ() - b.maxZ(), (long) b.minZ() - a.maxZ()));
+            return dx * dx + dy * dy + dz * dz;
+        }
+
+        private int top(int x, int z) {
+            return heights.computeIfAbsent(key(x, z), ignored -> {
+                for (int y = 383; y >= 32; y -= 4) {
+                    if (!solid(x, y, z)) continue;
+                    for (int exact = Math.min(383, y + 3); exact > y; exact--) if (solid(x, exact, z)) return exact;
+                    return y;
+                }
+                return -1;
+            });
+        }
+
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+    }
+
+    private static void add(List<Cell> cells, Set<Position> changed, int x, int y, int z, boolean lava) {
+        if (changed.add(new Position(x, y, z))) cells.add(new Cell(x, y, z, lava));
+    }
+
+    private static boolean inside(int x, int z, int radius) { return (long) x * x + (long) z * z < (long) radius * radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static double random(long seed, int x, int z) {
+        long value = seed ^ key(x, z) ^ 0x1A7A5EEDL;
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return ((value ^ (value >>> 31)) >>> 11) * 0x1.0p-53;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernLavaFlows.java

@@ -0,0 +1,241 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.worldgen.CavernLavaDeposit.Position;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** Selects a few volcanic seeps in deep exposed rock. Sources replace rock; their outlets and
+ * entire falling columns are left empty for vanilla lava ticks. No retaining wall is generated. */
+public final class CavernLavaFlows {
+    public static final int MIN_SOURCE_Y = 40;
+    public static final int MAX_SOURCE_Y = 160;
+    public static final int MAX_FALLS = 2;
+    public static final int HORIZONTAL_REACH = 3;
+    public static final int FIRE_CLEARANCE = 8;
+    public static final int WATER_CLEARANCE = 24;
+    private static final int RADIUS = 224;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final Comparator<Position> POSITION_ORDER = Comparator.comparingInt(Position::x)
+        .thenComparingInt(Position::z).thenComparingInt(Position::y);
+
+    private CavernLavaFlows() {}
+
+    /** flowBounds predicts undecorated rock drainage; it does not override Minecraft physics.
+     * supports contains only unchanged natural rock around the source, never the source itself. */
+    public record Fall(long id, Position source, Position outlet, List<Position> flowPath,
+                       CavernHydrology.FlowBounds flowBounds, List<Position> supports) {
+        public Fall { flowPath = List.copyOf(flowPath); supports = List.copyOf(supports); }
+    }
+
+    public static List<Fall> create(long seed, CavernHydrology.Sampler sampler,
+                                    CavernHydrology.Plan water, CavernLavaDeposit.Plan pocket) {
+        return new Search(seed, sampler, water, pocket).find();
+    }
+
+    private record Candidate(int x, int y, int z, int dx, int dz, double score) {}
+    private record Node(Position at, int reach) {}
+    private record Trace(List<Position> path, CavernHydrology.FlowBounds bounds) {}
+
+    private static final class Search {
+        private final long seed;
+        private final CavernHydrology.Sampler sampler;
+        private final CavernHydrology.Plan water;
+        private final CavernLavaDeposit.Plan pocket;
+        private final List<Fall> falls = new ArrayList<>();
+
+        Search(long seed, CavernHydrology.Sampler sampler, CavernHydrology.Plan water, CavernLavaDeposit.Plan pocket) {
+            this.seed = seed; this.sampler = sampler; this.water = water; this.pocket = pocket;
+        }
+
+        List<Fall> find() {
+            List<Candidate> candidates = new ArrayList<>();
+            // Coarse probes below the surface can see a lower overhang that a heightmap hides.
+            for (int x = -216; x <= 216; x += 8) for (int z = -216; z <= 216; z += 8) {
+                if ((long) x * x + (long) z * z >= (long) RADIUS * RADIUS) continue;
+                for (int y = MIN_SOURCE_Y; y <= MAX_SOURCE_Y; y += 8) {
+                    if (!solid(x, y, z)) continue;
+                    for (int[] d : CARDINALS) {
+                        if (solid(x + d[0] * 4, y, z + d[1] * 4)) continue;
+                        double score = random(seed + y, x + d[0], z + d[1])
+                            + (MAX_SOURCE_Y - y) * .002;
+                        candidates.add(new Candidate(x, y, z, d[0], d[1], score));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)
+                .thenComparingInt(Candidate::y).thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (falls.size() >= MAX_FALLS || attempts++ >= 160) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2}) {
+                    for (int along = 0; along < 4; along++) {
+                        int x = candidate.x() + candidate.dx() * along - candidate.dz() * tangent;
+                        int z = candidate.z() + candidate.dz() * along + candidate.dx() * tangent;
+                        for (int dy : new int[]{0, 2, -2, 4, -4}) {
+                            Position source = new Position(x, candidate.y() + dy, z);
+                            if (source.y() < MIN_SOURCE_Y || source.y() > MAX_SOURCE_Y || !separated(source)) continue;
+                            List<Position> supports = niche(source, candidate.dx(), candidate.dz());
+                            if (supports == null) continue;
+                            Position outlet = new Position(x + candidate.dx(), source.y(), z + candidate.dz());
+                            Trace flow = trace(source, outlet);
+                            if (flow == null || flow.bounds().minY() > source.y() - 12 || !clearOfWater(flow.bounds())) continue;
+                            long id = mix(seed ^ (0x1A7AFA11L + falls.size() * 0x9E3779B97F4A7C15L));
+                            falls.add(new Fall(id, source, outlet, flow.path(), flow.bounds(), supports));
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+            return List.copyOf(falls);
+        }
+
+        private boolean separated(Position source) {
+            CavernHydrology.FlowBounds point = bounds(source);
+            if (!clearOfWater(point)) return false;
+            for (Fall fall : falls) {
+                if (distanceSquared(source, fall.source()) < 80L * 80
+                    || distanceSquared(point, fall.flowBounds()) < 40L * 40) return false;
+            }
+            for (var cell : pocket.cells()) {
+                if (distanceSquared(source, new Position(cell.x(), cell.y(), cell.z())) < 32L * 32) return false;
+            }
+            return true;
+        }
+
+        private List<Position> niche(Position source, int dx, int dz) {
+            if (!solid(source)) return null;
+            Set<Position> supports = new HashSet<>();
+            // The source sits in rock, with a short intact roof, floor and three back/side faces.
+            // The spill column needs no floor: its absence is precisely what makes a cascade.
+            for (int dy = -3; dy <= 8; dy++) {
+                if (dy == 0) continue;
+                Position at = new Position(source.x(), source.y() + dy, source.z());
+                if (!solid(at)) return null;
+                supports.add(at);
+            }
+            for (int[] d : CARDINALS) {
+                if (d[0] == dx && d[1] == dz) continue;
+                for (int depth = 1; depth <= 2; depth++) {
+                    Position at = new Position(source.x() + d[0] * depth, source.y(), source.z() + d[1] * depth);
+                    if (!solid(at)) return null;
+                    supports.add(at);
+                }
+            }
+            for (int dy = 0; dy >= -8; dy--) {
+                if (solid(source.x() + dx, source.y() + dy, source.z() + dz)) return null;
+            }
+            return supports.stream().sorted(POSITION_ORDER).toList();
+        }
+
+        private boolean clearOfWater(CavernHydrology.FlowBounds bounds) {
+            for (var cell : water.cells()) {
+                var column = new CavernHydrology.FlowBounds(cell.x(), cell.bedY() - cell.sedimentDepth() - 1,
+                    cell.z(), cell.x(), Math.max(cell.carveTop(), cell.waterY()), cell.z());
+                if (distanceSquared(bounds, column) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spring : water.springs()) {
+                if (distanceSquared(bounds, spring.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spill : water.spills()) {
+                if (distanceSquared(bounds, spill.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            return true;
+        }
+
+        /** Descending lava resets its horizontal reach to three in this non-ultrawarm dimension.
+         * Explore all downhill branches through rock, so selection does not depend on chunk order. */
+        private Trace trace(Position source, Position outlet) {
+            Map<Position, Integer> reach = new HashMap<>();
+            Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<Node> queue = new ArrayDeque<>();
+            reach.put(source, HORIZONTAL_REACH);
+            queue.addLast(new Node(source, HORIZONTAL_REACH));
+            Position lowest = source;
+            while (!queue.isEmpty()) {
+                Node node = queue.removeFirst();
+                Position at = node.at();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 12000 || Math.abs(at.x() - source.x()) > 64 || Math.abs(at.z() - source.z()) > 64) return null;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (!flowSolid(below, source)) {
+                    enqueue(below, HORIZONTAL_REACH, at, reach, parent, queue);
+                    continue;
+                }
+                if (node.reach() <= 0) continue;
+                for (int[] d : CARDINALS) {
+                    Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+                    if (!flowSolid(next, source)) enqueue(next, node.reach() - 1, at, reach, parent, queue);
+                }
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY, minZ = source.z(), maxZ = minZ;
+            for (Position at : reach.keySet()) {
+                minX = Math.min(minX, at.x()); maxX = Math.max(maxX, at.x());
+                minY = Math.min(minY, at.y()); maxY = Math.max(maxY, at.y());
+                minZ = Math.min(minZ, at.z()); maxZ = Math.max(maxZ, at.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Trace(List.copyOf(path), new CavernHydrology.FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Position source) {
+            if (at.equals(source)) return false;
+            var cell = water.cellAt(at.x(), at.y(), at.z());
+            if (cell != null && at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            return solid(at);
+        }
+
+        private boolean solid(Position at) { return solid(at.x(), at.y(), at.z()); }
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+    }
+
+    private static void enqueue(Position next, int available, Position from, Map<Position, Integer> reach,
+                                Map<Position, Position> parent, ArrayDeque<Node> queue) {
+        if (available <= reach.getOrDefault(next, -1)) return;
+        if (!reach.containsKey(next)) parent.put(next, from);
+        reach.put(next, available);
+        queue.addLast(new Node(next, available));
+    }
+
+    private static CavernHydrology.FlowBounds bounds(Position at) {
+        return new CavernHydrology.FlowBounds(at.x(), at.y(), at.z(), at.x(), at.y(), at.z());
+    }
+
+    private static long distanceSquared(Position a, Position b) {
+        long dx = a.x() - b.x(), dy = a.y() - b.y(), dz = a.z() - b.z();
+        return dx * dx + dy * dy + dz * dz;
+    }
+
+    private static long distanceSquared(CavernHydrology.FlowBounds a, CavernHydrology.FlowBounds b) {
+        long dx = Math.max(0, Math.max((long) a.minX() - b.maxX(), (long) b.minX() - a.maxX()));
+        long dy = Math.max(0, Math.max((long) a.minY() - b.maxY(), (long) b.minY() - a.maxY()));
+        long dz = Math.max(0, Math.max((long) a.minZ() - b.maxZ(), (long) b.minZ() - a.maxZ()));
+        return dx * dx + dy * dy + dz * dz;
+    }
+
+    private static double random(long seed, int x, int z) {
+        return (mix(seed ^ ((long) x << 32) ^ (z & 0xffffffffL)) >>> 11) * 0x1.0p-53;
+    }
+
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernMaterials.java

@@ -0,0 +1,44 @@
+package fr.koka.sanctuary.worldgen;
+
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+
+/** Alpha.9 shore deposits: broad continuous patches through the existing sediment thickness. */
+public final class CavernMaterials {
+    private CavernMaterials() {}
+
+    public static BlockState sedimentBlock(CavernHydrology.Cell cell, long seed, int depth) {
+        if (cell.material() == CavernHydrology.ShoreMaterial.GRASS) {
+            return (depth == 0 ? Blocks.GRASS_BLOCK : Blocks.DIRT).defaultBlockState();
+        }
+        if (cell.material() == CavernHydrology.ShoreMaterial.CLAY) return Blocks.CLAY.defaultBlockState();
+        double patch = patch(seed, cell.x(), cell.z(), 32);
+        Block material;
+        if (cell.hasWater() && patch < 0.24) material = Blocks.CLAY;
+        else if (patch < 0.53) material = Blocks.SAND;
+        else if (patch < 0.68) material = Blocks.GRAVEL;
+        else {
+            double rock = patch(seed ^ 0x4c6179657273L, cell.x(), cell.z(), 40);
+            material = rock < 0.28 ? Blocks.GRANITE : rock < 0.45 ? Blocks.DIORITE
+                : rock < 0.65 ? Blocks.ANDESITE : Blocks.STONE;
+        }
+        return material.defaultBlockState();
+    }
+
+    private static double patch(long seed, int x, int z, int scale) {
+        int gx = Math.floorDiv(x, scale), gz = Math.floorDiv(z, scale);
+        double tx = smooth(Math.floorMod(x, scale) / (double) scale);
+        double tz = smooth(Math.floorMod(z, scale) / (double) scale);
+        double near = lerp(value(seed, gx, gz), value(seed, gx + 1, gz), tx);
+        double far = lerp(value(seed, gx, gz + 1), value(seed, gx + 1, gz + 1), tx);
+        return lerp(near, far, tz);
+    }
+
+    private static double value(long seed, int x, int z) {
+        return (WoodlandGroveGeometry.seed(seed, x, 0, z, 0x53484f5245L) >>> 11) * 0x1.0p-53;
+    }
+
+    private static double smooth(double t) { return t * t * (3 - 2 * t); }
+    private static double lerp(double a, double b, double t) { return a + (b - a) * t; }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernShoreSugarCaneFeature.java

@@ -0,0 +1,41 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import net.minecraft.core.BlockPos;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.feature.Feature;
+
+/** A few plants on existing suitable shores, after the forest has been decorated. */
+public final class CavernShoreSugarCaneFeature implements Feature {
+    public static final MapCodec<CavernShoreSugarCaneFeature> CODEC = MapCodec.unit(CavernShoreSugarCaneFeature::new);
+
+    @Override
+    public MapCodec<CavernShoreSugarCaneFeature> codec() {
+        return CODEC;
+    }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource random, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !CavernHydrologyRuntime.enabled(noise)) return false;
+        var plan = CavernHydrologyRuntime.plan(noise, level.getLevel().getChunkSource().randomState());
+        var cane = Blocks.SUGAR_CANE.defaultBlockState();
+        boolean placed = false;
+        for (var cell : plan.cellsInChunk(origin.getX() >> 4, origin.getZ() >> 4)) {
+            if (cell.hasWater() || random.nextInt(7) != 0) continue;
+            BlockPos base = new BlockPos(cell.x(), cell.bedY() + 1, cell.z());
+            if (!level.getBlockState(base).isAir() || !cane.canSurvive(level, base)) continue;
+            int height = 1 + random.nextInt(3);
+            for (int y = 0; y < height; y++) {
+                BlockPos pos = base.above(y);
+                if (!level.getBlockState(pos).isAir() || !cane.canSurvive(level, pos)) break;
+                setBlock(level, pos, cane);
+                placed = true;
+            }
+        }
+        return placed;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernSpringOutlets.java

@@ -0,0 +1,108 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayList;
+import java.util.List;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.VegetationBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.material.Fluids;
+
+/** One-time alpha.9 outlet finishing, using vanilla's persisted and consumed generation queue. */
+public final class CavernSpringOutlets {
+    public record Pending(List<CavernHydrology.Position> sources, List<CavernHydrology.Position> outlets) {
+        public static final Pending EMPTY = new Pending(List.of(), List.of());
+        public Pending { sources = List.copyOf(sources); outlets = List.copyOf(outlets); }
+        public boolean isEmpty() { return sources.isEmpty() && outlets.isEmpty(); }
+    }
+
+    private CavernSpringOutlets() {}
+
+    /** Called before vanilla consumes the queue; a fully processed/reloaded chunk has no work. */
+    public static Pending capturePending(ServerLevel level, LevelChunk chunk) {
+        if (!(level.getChunkSource().getGenerator() instanceof NoiseBasedChunkGenerator noise)
+                || !CavernHydrologyRuntime.enabled(noise)) return Pending.EMPTY;
+        boolean queued = false;
+        for (var section : chunk.getPostProcessing()) if (section != null && !section.isEmpty()) {
+            queued = true;
+            break;
+        }
+        if (!queued) return Pending.EMPTY;
+        var plan = CavernHydrologyRuntime.plan(noise, level.getChunkSource().randomState());
+        List<CavernHydrology.Position> sources = new ArrayList<>(), outlets = new ArrayList<>();
+        for (var spring : plan.springs()) {
+            if (markedHere(chunk, spring.source())) sources.add(spring.source());
+            if (markedHere(chunk, spring.outlet())) outlets.add(spring.outlet());
+        }
+        for (var spill : plan.spills()) {
+            if (markedHere(chunk, spill.source())) sources.add(spill.source());
+            if (markedHere(chunk, spill.outlet())) outlets.add(spill.outlet());
+        }
+        for (var fall : CavernHydrologyRuntime.lavaPlan(noise, level.getChunkSource().randomState()).falls()) {
+            var source = new CavernHydrology.Position(fall.source().x(), fall.source().y(), fall.source().z());
+            var outlet = new CavernHydrology.Position(fall.outlet().x(), fall.outlet().y(), fall.outlet().z());
+            if (markedHere(chunk, source)) sources.add(source);
+            if (markedHere(chunk, outlet)) outlets.add(outlet);
+        }
+        return new Pending(sources, outlets);
+    }
+
+    /** All neighbouring FEATURES have finished before a chunk reaches this stage. */
+    public static void finish(ServerLevel level, LevelChunk chunk, Pending pending) {
+        if (pending.isEmpty() || !(level.getChunkSource().getGenerator() instanceof NoiseBasedChunkGenerator noise)
+                || !CavernHydrologyRuntime.enabled(noise)) return;
+        var random = level.getChunkSource().randomState();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        for (var outlet : pending.outlets()) {
+            if (!owns(chunk, outlet)) throw new IllegalArgumentException("An outlet belongs to another chunk: " + outlet);
+            var modified = CavernHydrologyRuntime.plan(noise, random).cellAt(outlet.x(), outlet.y(), outlet.z());
+            boolean carved = modified != null && outlet.y() > modified.waterY() && outlet.y() > modified.bedY()
+                && outlet.y() <= modified.carveTop();
+            if (!carved && random.sampleBlockValueUncached(density, outlet.x(), outlet.y(), outlet.z()) > 0) {
+                throw new IllegalStateException("A spring outlet must already be natural air: " + outlet);
+            }
+            BlockPos pos = blockPos(outlet);
+            BlockState current = chunk.getBlockState(pos);
+            if (removableDecoration(current)) {
+                // Only this declared air cell is reopened. Neighbour notification wakes the
+                // adjacent source even if its own chunk was post-processed first.
+                level.setBlock(pos, Blocks.AIR.defaultBlockState(), Block.UPDATE_ALL);
+            }
+        }
+        for (var source : pending.sources()) {
+            if (!owns(chunk, source)) throw new IllegalArgumentException("A source belongs to another chunk: " + source);
+            BlockPos pos = blockPos(source);
+            BlockState current = chunk.getBlockState(pos);
+            if (current.getFluidState().isSource()) {
+                if (current.is(Blocks.WATER)) level.scheduleTick(pos, Fluids.WATER, Fluids.WATER.getTickDelay(level));
+                else if (current.is(Blocks.LAVA)) level.scheduleTick(pos, Fluids.LAVA, Fluids.LAVA.getTickDelay(level));
+            }
+        }
+    }
+
+    private static boolean markedHere(LevelChunk chunk, CavernHydrology.Position position) {
+        if (!owns(chunk, position)) return false;
+        var queue = chunk.getPostProcessing()[chunk.getSectionIndex(position.y())];
+        return queue != null && queue.contains(ProtoChunk.packOffsetCoordinates(blockPos(position)));
+    }
+
+    private static boolean owns(LevelChunk chunk, CavernHydrology.Position position) {
+        return (position.x() >> 4) == chunk.getPos().x() && (position.z() >> 4) == chunk.getPos().z();
+    }
+
+    private static BlockPos blockPos(CavernHydrology.Position position) {
+        return new BlockPos(position.x(), position.y(), position.z());
+    }
+
+    private static boolean removableDecoration(BlockState state) {
+        if (state.hasBlockEntity()) return false;
+        return state.is(Blocks.GLOW_LICHEN) || state.is(Blocks.VINE) || state.is(Blocks.MOSS_CARPET)
+            || state.getBlock() instanceof VegetationBlock || state.is(BlockTags.LEAVES) || state.is(BlockTags.LOGS);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/CavernTerraces.java

@@ -0,0 +1,435 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.worldgen.CavernHydrology.*;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.PriorityQueue;
+import java.util.Set;
+import java.util.function.Predicate;
+
+/** Small connected water terraces inside existing cave ledges. Each retained pool is excavated
+ * in rock; one declared edge may overflow. No dam, shelf, cave fill or fluid column is generated. */
+public final class CavernTerraces {
+    public static final int MIN_Y = 56, MAX_Y = 208;
+    public static final int MAX_GROUPS = 2, MAX_DEPTH = 3, MAX_CARVE = 5;
+    private static final int RADIUS = 216, SEDIMENT = 3;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final int[][] NEIGHBORS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}, {1, 1}, {1, -1}, {-1, 1}, {-1, -1}};
+
+    private CavernTerraces() {}
+
+    public record Result(List<Cell> cells, List<Feature> features, List<Terrace> terraces,
+                         List<Spill> spills, Set<Position> predictedFlow) {
+        public static final Result EMPTY = new Result(List.of(), List.of(), List.of(), List.of(), Set.of());
+        public Result {
+            cells = List.copyOf(cells); features = List.copyOf(features); terraces = List.copyOf(terraces);
+            spills = List.copyOf(spills); predictedFlow = Set.copyOf(predictedFlow);
+        }
+    }
+
+    public static Result create(long seed, Sampler sampler, CavernHydrology.Plan surface) {
+        return new Search(seed, sampler, surface).build();
+    }
+
+    private record Candidate(int x, int y, int z, int dx, int dz, double score) {}
+    private record Floor(int top, int bottom, int ceiling) {}
+    private record Node(int x, int z, double cost) {}
+    private record FlowNode(Position at, int reach) {}
+    private record Flow(Set<Position> volume, List<Position> path, FlowBounds bounds) {}
+    private record Pool(Map<Long, Cell> cells, Position source, Position outlet) {}
+    private static final Floor NO_FLOOR = new Floor(-1, -1, -1);
+
+    private static final class Search {
+        private final long seed;
+        private final Sampler sampler;
+        private final CavernHydrology.Plan surface;
+        private final Map<Position, Floor> floors = new HashMap<>();
+        private final List<Cell> acceptedCells = new ArrayList<>();
+        private final List<Feature> features = new ArrayList<>();
+        private final List<Terrace> terraces = new ArrayList<>();
+        private final List<Spill> spills = new ArrayList<>();
+        private final Set<Position> predicted = new HashSet<>();
+
+        Search(long seed, Sampler sampler, CavernHydrology.Plan surface) {
+            this.seed = seed; this.sampler = sampler; this.surface = surface;
+        }
+
+        Result build() {
+            List<Candidate> candidates = new ArrayList<>();
+            for (int x = -208; x <= 208; x += 8) for (int z = -208; z <= 208; z += 8) {
+                if (!inside(x, z)) continue;
+                for (int y = 64; y <= MAX_Y; y += 8) {
+                    if (!solid(x, y, z) || solid(x, y + 8, z)) continue;
+                    int level = y;
+                    for (int exact = y + 7; exact > y; exact--) if (solid(x, exact, z)) { level = exact; break; }
+                    if (level > MAX_Y || floor(x, z, level) == NO_FLOOR) continue;
+                    for (int[] d : CARDINALS) if (!solid(x + d[0] * 4, level, z + d[1] * 4)) {
+                        candidates.add(new Candidate(x, level, z, d[0], d[1], random(seed + level, x + d[0], z + d[1])));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z).thenComparingInt(Candidate::y)
+                .thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (terraces.size() >= MAX_GROUPS || attempts++ >= 160) break;
+                boolean added = false;
+                for (int tangent : new int[]{0, -2, 2}) {
+                    for (int along = 0; along < 4; along++) {
+                        int x = candidate.x() + candidate.dx() * along - candidate.dz() * tangent;
+                        int z = candidate.z() + candidate.dz() * along + candidate.dx() * tangent;
+                        for (int dy : new int[]{0, -1, 1, -2, 2}) {
+                            Position source = new Position(x, candidate.y() + dy, z);
+                            Position outlet = new Position(x + candidate.dx(), source.y(), z + candidate.dz());
+                            if (!mouth(source, outlet) || !separated(source)) continue;
+                            if (addGroup(source, outlet)) { added = true; break; }
+                        }
+                        if (added) break;
+                    }
+                    if (added) break;
+                }
+            }
+            return new Result(acceptedCells, features, terraces, spills, predicted);
+        }
+
+        private boolean addGroup(Position source, Position outlet) {
+            long groupId = mix(seed ^ (0xA9CA7E2L + terraces.size() * 0x9E3779B97F4A7C15L));
+            long upperId = mix(groupId + 1), lowerId = mix(groupId + 2);
+            Pool upper = grow(source, source.y(), source, outlet, upperId);
+            if (upper == null) return false;
+
+            // The first impact on a slope is often a thin lip. Follow natural drainage across
+            // its ledges, then find a supported receiving pool at a genuinely lower level.
+            // The same bounded fluid trace is used before and after carving the receiving pool.
+            Flow drainage = trace(source, outlet, new ArrayList<>(upper.cells().values()));
+            if (drainage == null) return false;
+            List<Position> contacts = new ArrayList<>();
+            for (Position at : drainage.volume()) {
+                int level = at.y() - 1;
+                if (level < MIN_Y || level > source.y() - 4 || !solid(at.x(), level, at.z())) continue;
+                Floor ground = floor(at.x(), at.z(), level);
+                if (ground != NO_FLOOR && ground.bottom() <= level - 7)
+                    contacts.add(new Position(at.x(), level, at.z()));
+            }
+            contacts.sort(Comparator.comparingInt(Position::y).reversed()
+                .thenComparingInt(Position::x).thenComparingInt(Position::z));
+            Pool lower = null;
+            Position landing = null;
+            int attempts = 0;
+            for (Position contact : contacts) {
+                if (attempts++ >= 48) break;
+                lower = grow(contact, contact.y(), null, null, lowerId);
+                if (lower != null) { landing = contact; break; }
+            }
+            if (lower == null) return false;
+            List<Cell> groupCells = new ArrayList<>(upper.cells().values());
+            groupCells.addAll(lower.cells().values());
+            if (overlapping(groupCells)) return false;
+            Flow inlet = trace(source, outlet, groupCells);
+            if (inlet == null || !reaches(inlet, lower)) return false;
+
+            // If the same lower ledge has another natural edge, connect it to an open terminal
+            // fall. Otherwise its second pool stays closed; the first inter-pool cascade remains.
+            Pool drained = terminalPool(landing, lowerId);
+            Flow terminal = null;
+            if (drained != null) {
+                List<Cell> replacement = new ArrayList<>(upper.cells().values());
+                replacement.addAll(drained.cells().values());
+                if (!overlapping(replacement)) {
+                    Flow in = trace(source, outlet, replacement);
+                    Flow out = trace(drained.source(), drained.outlet(), replacement);
+                    if (in != null && reaches(in, drained) && out != null
+                            && out.bounds().minY() <= drained.source().y() - 12) {
+                        lower = drained; inlet = in; terminal = out; groupCells = replacement;
+                    }
+                }
+            }
+            acceptedCells.addAll(groupCells);
+            features.add(feature(upperId, upper, source));
+            features.add(feature(lowerId, lower, landing));
+            terraces.add(new Terrace(groupId, List.of(upperId, lowerId)));
+            spills.add(new Spill(mix(groupId + 3), upperId, lowerId, source, outlet, inlet.path(), inlet.bounds()));
+            predicted.addAll(inlet.volume());
+            if (terminal != null) {
+                spills.add(new Spill(mix(groupId + 4), lowerId, -1, lower.source(), lower.outlet(), terminal.path(), terminal.bounds()));
+                predicted.addAll(terminal.volume());
+            }
+            return true;
+        }
+
+        private Pool terminalPool(Position center, long id) {
+            List<Position> candidates = new ArrayList<>();
+            for (int dx = -12; dx <= 12; dx++) for (int dz = -12; dz <= 12; dz++) {
+                if (dx * dx + dz * dz > 144) continue;
+                candidates.add(new Position(center.x() + dx, center.y(), center.z() + dz));
+            }
+            candidates.sort(Comparator.comparingDouble((Position p) -> Math.hypot(p.x() - center.x(), p.z() - center.z()))
+                .thenComparingInt(Position::x).thenComparingInt(Position::z));
+            int tried = 0;
+            for (Position source : candidates) for (int[] d : CARDINALS) {
+                Position outlet = new Position(source.x() + d[0], source.y(), source.z() + d[1]);
+                if (!mouth(source, outlet)) continue;
+                if (tried++ >= 12) return null;
+                Pool pool = grow(center, center.y(), source, outlet, id);
+                if (pool != null) return pool;
+            }
+            return null;
+        }
+
+        private Pool grow(Position center, int level, Position source, Position outlet, long id) {
+            PriorityQueue<Node> queue = new PriorityQueue<>(Comparator.comparingDouble(Node::cost)
+                .thenComparingInt(Node::x).thenComparingInt(Node::z));
+            Map<Long, Double> costs = new HashMap<>();
+            Set<Long> wet = new HashSet<>();
+            long origin = key(center.x(), center.z());
+            queue.add(new Node(center.x(), center.z(), 0)); costs.put(origin, 0.0);
+            int target = 100 + (int) (random(seed + level, center.x(), center.z()) * 80);
+            while (!queue.isEmpty() && wet.size() < target) {
+                Node node = queue.remove(); long k = key(node.x(), node.z());
+                if (wet.contains(k) || node.cost() > costs.getOrDefault(k, Double.POSITIVE_INFINITY)
+                        || !poolColumn(node.x(), node.z(), level, source, outlet)) continue;
+                wet.add(k);
+                for (int[] d : NEIGHBORS) {
+                    int x = node.x() + d[0], z = node.z() + d[1]; long next = key(x, z);
+                    if (Math.hypot(x - center.x(), z - center.z()) > 16 || wet.contains(next)) continue;
+                    double cost = node.cost() + Math.hypot(d[0], d[1]) * (1 + noise(x, z, 11) * 1.8);
+                    if (cost >= costs.getOrDefault(next, Double.POSITIVE_INFINITY)) continue;
+                    costs.put(next, cost); queue.add(new Node(x, z, cost));
+                }
+            }
+            wet = connected(wet, origin);
+            if (wet.size() < 40 || source != null && !wet.contains(key(source.x(), source.z()))) return null;
+            Map<Long, Cell> cells = new HashMap<>();
+            for (long k : wet) {
+                int x = (int) (k >> 32), z = (int) k;
+                boolean edge = false;
+                for (int[] d : CARDINALS) edge |= !wet.contains(key(x + d[0], z + d[1]));
+                int depth = edge ? 1 : 2 + (noise(x, z, 9) > .6 ? 1 : 0);
+                Floor floor = floor(x, z, level);
+                int bed = level - depth;
+                if (floor == NO_FLOOR || floor.top() - bed > MAX_CARVE || floor.bottom() > bed - SEDIMENT - 1) return null;
+                ShoreMaterial material = noise(x + 101, z - 87, 19) > .42 ? ShoreMaterial.CLAY : ShoreMaterial.STONE;
+                cells.put(k, new Cell(x, z, level, bed, floor.top(), material, id, SEDIMENT));
+            }
+            for (Cell cell : cells.values()) for (int[] d : CARDINALS) {
+                int x = cell.x() + d[0], z = cell.z() + d[1];
+                Cell next = cells.get(key(x, z));
+                for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) {
+                    if (next != null && y > next.bedY()) continue;
+                    if (source != null && cell.x() == source.x() && cell.z() == source.z()
+                        && x == outlet.x() && z == outlet.z() && y == outlet.y()) continue;
+                    if (!solid(x, y, z)) return null;
+                }
+            }
+            return new Pool(Map.copyOf(cells), source, outlet);
+        }
+
+        private boolean poolColumn(int x, int z, int level, Position source, Position outlet) {
+            if (!inside(x, z)) return false;
+            Floor floor = floor(x, z, level);
+            if (floor == NO_FLOOR || floor.bottom() > level - 7 || !available(x, z, level - 8, floor.top())) return false;
+            for (int[] d : CARDINALS) {
+                if (source != null && x == source.x() && z == source.z()
+                    && x + d[0] == outlet.x() && z + d[1] == outlet.z()) continue;
+                if (!solid(x + d[0], level, z + d[1])) return false;
+            }
+            return true;
+        }
+
+        private Floor floor(int x, int z, int level) {
+            return floors.computeIfAbsent(new Position(x, level, z), ignored -> {
+                if (level < MIN_Y || level > MAX_Y) return NO_FLOOR;
+                int top = -1;
+                for (int y = level + 2; y >= level; y--) {
+                    if (solid(x, y, z)) { top = y; break; }
+                }
+                if (top < 0) return NO_FLOOR;
+                for (int y = top + 1; y <= top + 4; y++) if (solid(x, y, z)) return NO_FLOOR;
+                int ceiling = top + 5;
+                while (ceiling < 384 && !solid(x, ceiling, z)) ceiling++;
+                if (ceiling >= 384) return NO_FLOOR;
+                int bottom = top;
+                while (bottom > top - 16 && solid(x, bottom - 1, z)) bottom--;
+                return new Floor(top, bottom, ceiling);
+            });
+        }
+
+        private boolean mouth(Position source, Position outlet) {
+            if (source.y() < MIN_Y || source.y() > MAX_Y || !solid(source.x(), source.y(), source.z())) return false;
+            // An adjacent natural step may receive the water before it descends again. Requiring
+            // a vertical shaft here would discard the gentle ledges that form cave terraces.
+            if (solid(outlet.x(), outlet.y(), outlet.z())) return false;
+            return floor(source.x(), source.z(), source.y()) != NO_FLOOR;
+        }
+
+        private boolean available(int x, int z, int low, int high) {
+            for (Cell cell : surface.cellsAt(x, z)) if (low <= cell.carveTop() + 4
+                && high >= cell.bedY() - cell.sedimentDepth() - 5) return false;
+            for (Cell cell : acceptedCells) if (cell.x() == x && cell.z() == z && low <= cell.carveTop() + 4
+                && high >= cell.bedY() - cell.sedimentDepth() - 5) return false;
+            for (Spring spring : surface.springs()) if (inBounds(x, low, high, z, spring.flowBounds(), 6)) return false;
+            for (Spill spill : spills) if (inBounds(x, low, high, z, spill.flowBounds(), 6)) return false;
+            return true;
+        }
+
+        private boolean separated(Position source) {
+            for (Spill spill : spills) if (Math.hypot(source.x() - spill.source().x(), source.z() - spill.source().z()) < 64) return false;
+            return available(source.x(), source.z(), source.y() - 8, source.y() + 4);
+        }
+
+        private static boolean overlapping(List<Cell> cells) {
+            Map<Long, List<Cell>> columns = new HashMap<>();
+            for (Cell cell : cells) {
+                var existing = columns.computeIfAbsent(key(cell.x(), cell.z()), ignored -> new ArrayList<>());
+                for (Cell old : existing) if (cell.bedY() - cell.sedimentDepth() - 1 <= old.carveTop()
+                    && old.bedY() - old.sedimentDepth() - 1 <= cell.carveTop()) return true;
+                existing.add(cell);
+            }
+            return false;
+        }
+
+        private Flow trace(Position source, Position outlet, List<Cell> group) {
+            Map<Long, List<Cell>> changes = new HashMap<>();
+            Set<Position> retained = new HashSet<>();
+            for (Cell cell : group) {
+                changes.computeIfAbsent(key(cell.x(), cell.z()), ignored -> new ArrayList<>()).add(cell);
+                for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) retained.add(new Position(cell.x(), y, cell.z()));
+            }
+            Map<Position, Boolean> solidCache = new HashMap<>();
+            Predicate<Position> open = at -> !solidCache.computeIfAbsent(at, p -> flowSolid(p, changes));
+            Predicate<Position> canEnter = at -> !retained.contains(at) && open.test(at);
+            Predicate<Position> hole = at -> open.test(new Position(at.x(), at.y() - 1, at.z()));
+            Map<Position, Integer> reach = new HashMap<>(); Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<FlowNode> queue = new ArrayDeque<>();
+            reach.put(source, 7); queue.addLast(new FlowNode(source, 7)); Position lowest = source;
+            while (!queue.isEmpty()) {
+                FlowNode node = queue.removeFirst(); Position at = node.at();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 16000 || Math.abs(at.x() - source.x()) > 64 || Math.abs(at.z() - source.z()) > 64) return null;
+                // Vanilla never replaces an existing source. Record the arriving contact,
+                // but do not manufacture a route through the separately retained basin.
+                if (retained.contains(at) && !at.equals(source)) continue;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (open.test(below)) { enqueue(below, 7, at, reach, parent, queue); continue; }
+                if (node.reach() <= 0) continue;
+                for (Position next : downhillChoices(at, canEnter, hole))
+                    enqueue(next, node.reach() - 1, at, reach, parent, queue);
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY, minZ = source.z(), maxZ = minZ;
+            for (Position at : reach.keySet()) {
+                minX = Math.min(minX, at.x()); maxX = Math.max(maxX, at.x()); minY = Math.min(minY, at.y()); maxY = Math.max(maxY, at.y());
+                minZ = Math.min(minZ, at.z()); maxZ = Math.max(maxZ, at.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Flow(Set.copyOf(reach.keySet()), List.copyOf(path), new FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Map<Long, List<Cell>> changes) {
+            for (Cell cell : changes.getOrDefault(key(at.x(), at.z()), List.of()))
+                if (at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            Cell surfaceCell = surface.cellAt(at.x(), at.y(), at.z());
+            if (surfaceCell != null && at.y() > surfaceCell.bedY() && at.y() <= surfaceCell.carveTop()) return false;
+            return solid(at.x(), at.y(), at.z());
+        }
+
+        private static boolean reaches(Flow flow, Pool pool) {
+            return flow.volume().stream().anyMatch(at -> {
+                Cell cell = pool.cells().get(key(at.x(), at.z()));
+                return cell != null && at.y() > cell.bedY() && at.y() <= cell.waterY();
+            });
+        }
+
+        private static Feature feature(long id, Pool pool, Position center) {
+            int minX = Integer.MAX_VALUE, minZ = minX, maxX = Integer.MIN_VALUE, maxZ = maxX;
+            for (Cell cell : pool.cells().values()) {
+                minX = Math.min(minX, cell.x()); maxX = Math.max(maxX, cell.x()); minZ = Math.min(minZ, cell.z()); maxZ = Math.max(maxZ, cell.z());
+            }
+            return new Feature(id, Kind.TERRACE, center.y(), List.of(new Point(center.x(), center.z())), pool.cells().size(),
+                new Bounds(minX, minZ, maxX, maxZ));
+        }
+
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+        private double noise(int x, int z, int scale) {
+            int gx = Math.floorDiv(x, scale), gz = Math.floorDiv(z, scale);
+            double tx = smooth(Math.floorMod(x, scale) / (double) scale), tz = smooth(Math.floorMod(z, scale) / (double) scale);
+            double a = random(seed, gx, gz) * (1 - tx) + random(seed, gx + 1, gz) * tx;
+            double b = random(seed, gx, gz + 1) * (1 - tx) + random(seed, gx + 1, gz + 1) * tx;
+            return a * (1 - tz) + b * tz;
+        }
+    }
+
+    /** WaterFluid's bare-rock downhill choice: consider holes through four recursive
+     * steps, keep only the nearest directions (including ties), spread everywhere
+     * only when no direction finds a hole. Retained sources cannot be entered. */
+    static List<Position> downhillChoices(Position at, Predicate<Position> canEnter, Predicate<Position> hole) {
+        List<Position> selected = new ArrayList<>();
+        int best = 1000;
+        for (int[] d : CARDINALS) {
+            Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+            if (!canEnter.test(next)) continue;
+            int cost = hole.test(next) ? 0 : slopeDistance(next, 1, -d[0], -d[1], canEnter, hole);
+            if (cost < best) selected.clear();
+            if (cost <= best) { selected.add(next); best = cost; }
+        }
+        return selected;
+    }
+
+    private static int slopeDistance(Position at, int distance, int backX, int backZ,
+                                     Predicate<Position> canEnter, Predicate<Position> hole) {
+        int best = 1000;
+        for (int[] d : CARDINALS) {
+            if (d[0] == backX && d[1] == backZ) continue;
+            Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+            if (!canEnter.test(next)) continue;
+            if (hole.test(next)) return distance;
+            if (distance < 4) best = Math.min(best,
+                slopeDistance(next, distance + 1, -d[0], -d[1], canEnter, hole));
+        }
+        return best;
+    }
+
+    private static void enqueue(Position next, int amount, Position from, Map<Position, Integer> reach,
+                                Map<Position, Position> parent, ArrayDeque<FlowNode> queue) {
+        if (amount <= reach.getOrDefault(next, -1)) return;
+        if (!reach.containsKey(next)) parent.put(next, from);
+        reach.put(next, amount); queue.addLast(new FlowNode(next, amount));
+    }
+    private static Set<Long> connected(Set<Long> footprint, long origin) {
+        if (!footprint.contains(origin)) return Set.of();
+        Set<Long> seen = new HashSet<>(); ArrayDeque<Long> queue = new ArrayDeque<>();
+        seen.add(origin); queue.add(origin);
+        while (!queue.isEmpty()) {
+            long at = queue.removeFirst(); int x = (int) (at >> 32), z = (int) at;
+            for (int[] d : CARDINALS) {
+                long next = key(x + d[0], z + d[1]);
+                if (footprint.contains(next) && seen.add(next)) queue.addLast(next);
+            }
+        }
+        return seen;
+    }
+    private static boolean inBounds(int x, int low, int high, int z, FlowBounds b, int margin) {
+        return x >= b.minX() - margin && x <= b.maxX() + margin && z >= b.minZ() - margin && z <= b.maxZ() + margin
+            && low <= b.maxY() + margin && high >= b.minY() - margin;
+    }
+    private static boolean inside(int x, int z) { return (long) x * x + (long) z * z < (long) RADIUS * RADIUS; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static double smooth(double t) { return t * t * (3 - 2 * t); }
+    private static double random(long seed, int x, int z) { return (mix(seed ^ key(x, z)) >>> 11) * 0x1.0p-53; }
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/ExactInterpolationSampler.java

@@ -0,0 +1,152 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.lang.ref.WeakReference;
+import java.util.Arrays;
+import net.minecraft.util.Mth;
+import net.minecraft.world.level.levelgen.densityfunction.DensityBuffer;
+import net.minecraft.world.level.levelgen.densityfunction.DensityFunction;
+import net.minecraft.world.level.levelgen.densityfunction.DensitySampler;
+import net.minecraft.world.level.levelgen.densityfunction.DensityVolume;
+import net.minecraft.world.level.levelgen.densityfunction.DfRewriteRule;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.densityfunction.generator.ConstantFunction;
+import net.minecraft.world.level.levelgen.densityfunction.generator.GradientFunction;
+import net.minecraft.world.level.levelgen.densityfunction.generator.NoiseFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.BinaryFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.ClampFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.InterpolatedFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.LerpFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.SliceFunction;
+import net.minecraft.world.level.levelgen.densityfunction.op.UnaryFunction;
+import net.minecraft.world.level.levelgen.synth.BlendedNoise;
+
+/** Reuses lattice corners without changing 26.3-pre-2's scalar interpolation arithmetic.
+ * Vanilla's bulk interpolation changes operation order and accumulates Y increments, so it
+ * cannot replace scalar sampling in a generator whose existing worlds must remain exact. */
+public final class ExactInterpolationSampler implements DensitySampler {
+    private static final int CACHE_SIZE = 4096;
+    // One numeric cache per worker, not one cache per world. Both identities are weak:
+    // neither a sampler's captured noise graph nor a context's world fields are retained.
+    private static final ThreadLocal<CornerCache> CORNERS = ThreadLocal.withInitial(CornerCache::new);
+
+    private final DensitySampler input;
+    private final int cellSizeXz;
+    private final int cellSizeY;
+
+    ExactInterpolationSampler(DensitySampler input, int cellSizeXz, int cellSizeY) {
+        this.input = input;
+        this.cellSizeXz = cellSizeXz;
+        this.cellSizeY = cellSizeY;
+    }
+
+    /** Only the known Population terrain expression is optimized. Other data-pack expressions
+     * retain their own sampler, and the squeeze operation remains the actual vanilla class. */
+    public static DensitySampler compileTerrain(DensityFunction terrain, DensityFunction.CompileContext context) {
+        if (supportsTerrain(terrain)) {
+            var interpolated = (InterpolatedFunction) ((UnaryFunction) terrain).input();
+            return new UnaryFunction.SqueezeSampler(new ExactInterpolationSampler(
+                interpolated.input().compileSampler(context), interpolated.cellSizeXz(), interpolated.cellSizeY()));
+        }
+        return terrain.compileSampler(context);
+    }
+
+    /** Also used by the engine equivalence check to prove the shipped graphs take this path. */
+    public static boolean supportsTerrain(DensityFunction terrain) {
+        return terrain instanceof UnaryFunction unary && unary.type() == UnaryFunction.Type.SQUEEZE
+            && unary.input() instanceof InterpolatedFunction interpolated && coordinateOnly(interpolated.input(), 0);
+    }
+
+    private static boolean coordinateOnly(DensityFunction function, int depth) {
+        if (depth > 64) return false;
+        function = DfRewriteRule.INLINE_REFERENCE.rewrite(function);
+        if (function instanceof ConstantFunction || function instanceof GradientFunction || function instanceof BlendedNoise) return true;
+        if (function instanceof NoiseFunction noise) return coordinateOnly(noise.shiftX(), depth + 1)
+            && coordinateOnly(noise.shiftY(), depth + 1) && coordinateOnly(noise.shiftZ(), depth + 1);
+        if (function instanceof BinaryFunction binary) return coordinateOnly(binary.left(), depth + 1)
+            && coordinateOnly(binary.right(), depth + 1);
+        if (function instanceof LerpFunction lerp) return coordinateOnly(lerp.alpha(), depth + 1)
+            && coordinateOnly(lerp.first(), depth + 1) && coordinateOnly(lerp.second(), depth + 1);
+        if (function instanceof UnaryFunction unary) return coordinateOnly(unary.input(), depth + 1);
+        if (function instanceof ClampFunction clamp) return coordinateOnly(clamp.input(), depth + 1);
+        if (function instanceof SliceFunction slice) return coordinateOnly(slice.input(), depth + 1);
+        // Contextual blending, prepared caches and third-party density functions are deliberately
+        // opaque. Identity of a SamplerContext does not prove that its payload cannot mutate.
+        return false;
+    }
+
+    @Override public float sampleValue(SamplerContext context, int x, int y, int z) {
+        int offsetX = Math.floorMod(x, cellSizeXz);
+        int offsetY = Math.floorMod(y, cellSizeY);
+        int offsetZ = Math.floorMod(z, cellSizeXz);
+        // The vanilla aligned path is scalar; a lattice value from sampleVolume is not
+        // assumed to have the same bits as this separate input.sampleValue path.
+        if (offsetX == 0 && offsetY == 0 && offsetZ == 0) return input.sampleValue(context, x, y, z);
+
+        int originX = x - offsetX, originY = y - offsetY, originZ = z - offsetZ;
+        CornerCache cache = CORNERS.get();
+        cache.select(this, context);
+        int slot = cache.slot(originX, originY, originZ);
+        if (!cache.contains(slot, originX, originY, originZ)) {
+            DensityVolume lattice = new DensityVolume(2, 2, 2, originX, originY, originZ,
+                cellSizeXz, cellSizeY, cellSizeXz);
+            try (var buffer = context.acquireBuffer(lattice)) {
+                // Keep the precise 2x2x2 request used by InterpolatedFunction.sampleValue:
+                // batching a larger lattice can change the input noise's rounding too.
+                input.sampleVolume(context, buffer, lattice);
+                // A nested input sampler could itself use this thread's cache. Restore our
+                // identity after it returns, before publishing our corners into the cache.
+                cache.select(this, context);
+                int first = slot * 8;
+                for (int i = 0; i < 8; i++) cache.values[first + i] = buffer.get(i);
+                cache.store(slot, originX, originY, originZ);
+            }
+        }
+        int first = slot * 8;
+        // DensityVolume packs Y fastest, then X, then Z. lerp3 expects the corners in
+        // X, Y, Z order; retain vanilla's float divisions, not reciprocal multiplication.
+        return Mth.lerp3((float) offsetX / cellSizeXz, (float) offsetY / cellSizeY, (float) offsetZ / cellSizeXz,
+            cache.values[first], cache.values[first + 2], cache.values[first + 1], cache.values[first + 3],
+            cache.values[first + 4], cache.values[first + 6], cache.values[first + 5], cache.values[first + 7]);
+    }
+
+    @Override public void sampleVolume(SamplerContext context, DensityBuffer buffer, DensityVolume volume) {
+        DensitySampler.sampleVolumeNaive(context, buffer, volume, this);
+    }
+
+    /** Direct-mapped and bounded: 192 KiB of primitive arrays per participating thread.
+     * A collision only recomputes a cell; it never substitutes a different cell's corners. */
+    private static final class CornerCache {
+        private WeakReference<ExactInterpolationSampler> sampler = new WeakReference<>(null);
+        private WeakReference<SamplerContext> context = new WeakReference<>(null);
+        private final int[] xs = new int[CACHE_SIZE], ys = new int[CACHE_SIZE], zs = new int[CACHE_SIZE];
+        private final int[] generations = new int[CACHE_SIZE];
+        private final float[] values = new float[CACHE_SIZE * 8];
+        private int generation;
+
+        void select(ExactInterpolationSampler selected, SamplerContext selectedContext) {
+            if (sampler.get() == selected && context.get() == selectedContext) return;
+            sampler = new WeakReference<>(selected);
+            context = new WeakReference<>(selectedContext);
+            if (++generation == 0) {
+                Arrays.fill(generations, 0);
+                generation = 1;
+            }
+        }
+
+        int slot(int x, int y, int z) {
+            int hash = x * 0x9e3779b9 ^ Integer.rotateLeft(y * 0x85ebca6b, 11)
+                ^ Integer.rotateLeft(z * 0xc2b2ae35, 22);
+            hash = (hash ^ (hash >>> 16)) * 0x7feb352d;
+            return (hash ^ (hash >>> 15)) & (CACHE_SIZE - 1);
+        }
+
+        boolean contains(int slot, int x, int y, int z) {
+            return generations[slot] == generation && xs[slot] == x && ys[slot] == y && zs[slot] == z;
+        }
+
+        void store(int slot, int x, int y, int z) {
+            xs[slot] = x; ys[slot] = y; zs[slot] = z;
+            generations[slot] = generation;
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/IslandCapacity.java

@@ -0,0 +1,53 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.DataResult;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+
+/** Saved geometry references. Small/large use FIVE/TEN; TWENTY/HUNDRED remain loadable. */
+public enum IslandCapacity {
+    FIVE(5, 256), TEN(10, 256 * Math.sqrt(2)), TWENTY(20, 512), HUNDRED(100, 256 * Math.sqrt(20));
+
+    public static final int REGION_SIZE = 512;
+    public static final Codec<IslandCapacity> CODEC = Codec.INT.comapFlatMap(players -> {
+        for (var capacity : values()) if (capacity.players == players) return DataResult.success(capacity);
+        return DataResult.error(() -> "Unknown saved island size; supported references are 5, 10, 20 and 100");
+    }, IslandCapacity::players);
+    private final int players;
+    private final double radius;
+    IslandCapacity(int players, double radius) { this.players = players; this.radius = radius; }
+    public int players() { return players; }
+    public double radius() { return radius; }
+    public int terrainLimit() { return (int) Math.ceil(radius + 32); }
+    public static IslandCapacity fromPlayers(int players) {
+        for (var capacity : values()) if (capacity.players == players) return capacity;
+        throw new IllegalArgumentException("Unknown saved island size; supported references are 5, 10, 20 and 100");
+    }
+    public static IslandCapacity forGenerator(ChunkGenerator generator) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise)) return null;
+        var settings = noise.generatorSettings();
+        if (settings.is(SanctuarySpawn.POPULATION_5_SETTINGS) || settings.is(fr.koka.sanctuary.SanctuaryMod.id("unified_5"))) return FIVE;
+        if (settings.is(SanctuarySpawn.POPULATION_10_SETTINGS) || settings.is(fr.koka.sanctuary.SanctuaryMod.id("unified_10"))) return TEN;
+        if (settings.is(SanctuarySpawn.POPULATION_20_SETTINGS) || settings.is(fr.koka.sanctuary.SanctuaryMod.id("unified_20"))) return TWENTY;
+        if (settings.is(SanctuarySpawn.POPULATION_100_SETTINGS)) return HUNDRED;
+        return null;
+    }
+    public boolean areaExists(int chunkX, int chunkZ) {
+        double x = Math.max(0, Math.max((long) chunkX * 16, -((long) chunkX * 16 + 15)));
+        double z = Math.max(0, Math.max((long) chunkZ * 16, -((long) chunkZ * 16 + 15)));
+        return Math.hypot(x, z) < terrainLimit();
+    }
+    public Region regionAt(int x, int z) {
+        return new Region((int) Math.floorDiv((long) x + 256, REGION_SIZE),
+            (int) Math.floorDiv((long) z + 256, REGION_SIZE));
+    }
+    public record Region(int x, int z) {
+        public int originX() { return Math.multiplyExact(x, REGION_SIZE); }
+        public int originZ() { return Math.multiplyExact(z, REGION_SIZE); }
+        public int minX() { return originX() - 256; }
+        public int minZ() { return originZ() - 256; }
+        public int maxX() { return originX() + 255; }
+        public int maxZ() { return originZ() + 255; }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredBiomePalette.java

@@ -0,0 +1,20 @@
+package fr.koka.sanctuary.worldgen;
+
+/** Broad, seed-warped vertical bands; none changes terrain density or guarantees a resource. */
+public final class LayeredBiomePalette {
+    public enum Kind { MEADOW, FLOWER_MEADOW, LOWER_GROVE, MOSSY_TERRACES, ROCKY_TERRACES }
+
+    private LayeredBiomePalette() {}
+
+    public static Kind select(int blockY, float variation, float moisture) {
+        double elevation = blockY - Math.clamp(variation, -1.0F, 1.0F) * 28
+            - Math.clamp(moisture, -1.0F, 1.0F) * 12;
+        if (elevation < 154) return moisture < -0.30F ? Kind.ROCKY_TERRACES : Kind.MOSSY_TERRACES;
+        if (elevation < 214) {
+            if (variation > 0.34F) return Kind.ROCKY_TERRACES;
+            return moisture > 0.02F ? Kind.LOWER_GROVE : Kind.MOSSY_TERRACES;
+        }
+        if (variation > 0.22F) return Kind.ROCKY_TERRACES;
+        return moisture > -0.12F ? Kind.FLOWER_MEADOW : Kind.MEADOW;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredHydrology.java

@@ -0,0 +1,633 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.PriorityQueue;
+import java.util.Set;
+
+/** Alpha.6 surface basins, rocky shores and layered wall springs.
+ * This version is separate from NaturalHydrology so previously created worlds keep their original terrain.
+ * Results retain no chunks, sampler, random state or Minecraft objects. */
+public final class LayeredHydrology {
+    public static final int RADIUS = 192;
+    public static final int MAX_CARVE = 4;
+    public static final int MAX_DEPTH = 3;
+    private static final int GRID = 8;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final int[][] NEIGHBORS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}, {1, 1}, {1, -1}, {-1, 1}, {-1, -1}};
+
+    private LayeredHydrology() {}
+
+    @FunctionalInterface
+    public interface Sampler { float sample(int x, int y, int z); }
+
+    public enum Kind { POND, LAKE }
+    public enum ShoreMaterial { SAND, GRAVEL, CLAY, STONE, GRASS }
+    public record Point(int x, int z) {}
+    public record Bounds(int minX, int minZ, int maxX, int maxZ) {}
+
+    public record Position(int x, int y, int z) {}
+    public record FlowBounds(int minX, int minY, int minZ, int maxX, int maxY, int maxZ) {}
+    public record Spring(long id, Position source, Position outlet, List<Position> flowPath, FlowBounds flowBounds) {
+        public Spring { flowPath = List.copyOf(flowPath); }
+    }
+
+    /** Replaces existing solids bedY-sedimentDepth+1..bedY, with two intact natural supports below.
+     * Water occupies bedY+1..waterY; everything above it through carveTop is removed. For a dry
+     * terrace waterY=-1, and bedY+1..carveTop is removed (at most two original blocks). */
+    public record Cell(int x, int z, int waterY, int bedY, int carveTop,
+                       ShoreMaterial material, long featureId, int sedimentDepth) {
+        public boolean hasWater() { return waterY >= 0; }
+    }
+
+    public record Feature(long id, Kind kind, int waterY, List<Point> path, int waterCells, Bounds bounds) {
+        public Feature { path = List.copyOf(path); }
+    }
+
+    public static final class Plan {
+        private final Map<Long, Cell> cells;
+        private final Map<Long, List<Cell>> chunks;
+        private final List<Feature> features;
+        private final List<Spring> springs;
+        private final Map<Long, List<Spring>> springChunks;
+        private final Set<Position> springFlow;
+        private final int sampledColumns;
+        private final long densitySamples;
+
+        private Plan(Map<Long, Cell> source, List<Feature> features, List<Spring> springs, Set<Position> springFlow, int columns, long samples) {
+            List<Cell> sorted = source.values().stream()
+                .sorted(Comparator.comparingInt(Cell::x).thenComparingInt(Cell::z)).toList();
+            Map<Long, Cell> ordered = new LinkedHashMap<>();
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : sorted) {
+                ordered.put(key(cell.x(), cell.z()), cell);
+                byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4), ignored -> new ArrayList<>()).add(cell);
+            }
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            cells = Collections.unmodifiableMap(ordered);
+            chunks = Map.copyOf(byChunk);
+            this.features = List.copyOf(features);
+            this.springs = List.copyOf(springs);
+            this.springFlow = Set.copyOf(springFlow);
+            Map<Long, List<Spring>> groupedSprings = new HashMap<>();
+            for (Spring spring : springs) groupedSprings.computeIfAbsent(
+                key(spring.source().x() >> 4, spring.source().z() >> 4), ignored -> new ArrayList<>()).add(spring);
+            groupedSprings.replaceAll((ignored, values) -> List.copyOf(values));
+            springChunks = Map.copyOf(groupedSprings);
+            sampledColumns = columns;
+            densitySamples = samples;
+        }
+
+        public Cell cellAt(int x, int z) { return cells.get(key(x, z)); }
+        public Collection<Cell> cells() { return cells.values(); }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Feature> features() { return features; }
+        public List<Spring> springs() { return springs; }
+        public List<Spring> springsInChunk(int x, int z) { return springChunks.getOrDefault(key(x, z), List.of()); }
+        /** Prediction in undecorated density, not a restriction on Minecraft fluid simulation. */
+        public boolean allowsSpringFlow(int x, int y, int z) { return springFlow.contains(new Position(x, y, z)); }
+        public int sampledColumns() { return sampledColumns; }
+        public long densitySamples() { return densitySamples; }
+    }
+
+    public static Plan create(long seed, Sampler sampler) {
+        return new Planner(seed, sampler).build();
+    }
+
+    private record Column(int top, int solidBottom) {}
+    private record Candidate(int x, int z, double score) {}
+    private record Node(int x, int z, double cost) {}
+    private static final Comparator<Node> NODE_ORDER = Comparator.comparingDouble(Node::cost)
+        .thenComparingInt(Node::x).thenComparingInt(Node::z);
+
+    private static final class Planner {
+        private final long seed;
+        private final Sampler sampler;
+        private final Map<Long, Column> columns = new HashMap<>();
+        private final Map<Long, Integer> coarse = new HashMap<>();
+        private final Map<Long, Cell> cells = new HashMap<>();
+        private final List<Feature> features = new ArrayList<>();
+        private final List<Spring> springs = new ArrayList<>();
+        private final Set<Position> springFlow = new HashSet<>();
+        private long samples;
+
+        Planner(long seed, Sampler sampler) { this.seed = seed; this.sampler = sampler; }
+
+        Plan build() {
+            List<Candidate> candidates = candidates();
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (features.size() >= 5 || attempts++ >= 96) break;
+                Point center = new Point(candidate.x(), candidate.z());
+                if (nearWater(center.x(), center.z(), 38)) continue;
+                Column column = column(center.x(), center.z());
+                if (column.top() < 64 || column.top() - column.solidBottom() < 7) continue;
+                Kind kind = features.size() < 2 ? Kind.LAKE : Kind.POND;
+                int target = kind == Kind.LAKE ? 190 + (int) (random(seed, center.x(), center.z()) * 130)
+                    : 55 + (int) (random(seed + 1, center.x(), center.z()) * 55);
+                // Prefer an existing low spot; a shallow cut is the fallback on level terrain.
+                for (int level : new int[]{column.top() + 1, column.top(), column.top() - 1}) {
+                    Set<Long> footprint = growBasin(center, level, target);
+                    if (footprint == null) continue;
+                    long id = featureId(features.size());
+                    Map<Long, Cell> wet = waterCells(footprint, level, id);
+                    if (wet == null || !contained(wet)) continue;
+                    addFeature(id, kind, level, List.of(center), wet);
+                    break;
+                }
+            }
+            addSedimentSheets();
+            addLowerWallSprings();
+            addSprings();
+            return new Plan(cells, features, springs, springFlow, columns.size(), samples);
+        }
+
+        private List<Candidate> candidates() {
+            for (int x = -RADIUS; x <= RADIUS; x += GRID) {
+                for (int z = -RADIUS; z <= RADIUS; z += GRID) {
+                    if (inside(x, z, RADIUS)) coarse.put(key(x, z), coarseTop(x, z));
+                }
+            }
+            List<Candidate> result = new ArrayList<>();
+            for (int x = -RADIUS + GRID; x < RADIUS; x += GRID) {
+                for (int z = -RADIUS + GRID; z < RADIUS; z += GRID) {
+                    int height = coarse.getOrDefault(key(x, z), -1);
+                    if (height < 64 || !inside(x, z, RADIUS - 24)) continue;
+                    double average = 0;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        int neighbor = coarse.getOrDefault(key(x + d[0] * GRID, z + d[1] * GRID), -1);
+                        if (neighbor < 64 || Math.abs(neighbor - height) > 16) safe = false;
+                        average += neighbor * 0.25;
+                    }
+                    if (safe) result.add(new Candidate(x, z,
+                        (average - height) * 2.0 + random(seed + 2, x, z) * 3.0));
+                }
+            }
+            result.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z));
+            return result;
+        }
+
+        private int coarseTop(int x, int z) {
+            for (int y = 383; y >= 32; y -= 4) if (solid(x, y, z)) return y;
+            return -1;
+        }
+
+        private Column column(int x, int z) {
+            long key = key(x, z);
+            Column old = columns.get(key);
+            if (old != null) return old;
+            int top = -1;
+            // Exact scan, including everything above the planned water: a cave roof cannot be
+            // mistaken for a surface. Only candidates and their nearby shore need this refinement.
+            for (int y = 383; y >= 24; y--) {
+                if (solid(x, y, z)) { top = y; break; }
+            }
+            int bottom = top;
+            if (top >= 0) {
+                while (bottom > Math.max(16, top - 16) && solid(x, bottom - 1, z)) bottom--;
+            }
+            Column created = new Column(top, bottom);
+            columns.put(key, created);
+            return created;
+        }
+
+        private boolean eligible(int x, int z, int level) {
+            if (level < 32 || level >= 383 || !inside(x, z, RADIUS - 2)) return false;
+            Cell old = cells.get(key(x, z));
+            if (old != null && old.hasWater() && old.waterY() != level) return false;
+            Column column = column(x, z);
+            return column.top() >= level - 3 && column.top() < level + MAX_CARVE
+                && column.solidBottom() <= Math.min(column.top(), level - 1) - 4;
+        }
+
+        private Set<Long> growBasin(Point center, int level, int target) {
+            if (!eligible(center.x(), center.z(), level)) return null;
+            Set<Long> wet = new HashSet<>();
+            Map<Long, Double> costs = new HashMap<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            queue.add(new Node(center.x(), center.z(), 0));
+            costs.put(key(center.x(), center.z()), 0.0);
+            while (!queue.isEmpty() && wet.size() < target) {
+                Node current = queue.remove();
+                if (current.cost() > costs.getOrDefault(key(current.x(), current.z()), Double.POSITIVE_INFINITY)) continue;
+                if (!eligible(current.x(), current.z(), level)) continue;
+                wet.add(key(current.x(), current.z()));
+                for (int[] d : NEIGHBORS) {
+                    int x = current.x() + d[0], z = current.z() + d[1];
+                    if (Math.hypot(x - center.x(), z - center.z()) > 28 || wet.contains(key(x, z))) continue;
+                    if (!eligible(x, z, level)) continue;
+                    double step = Math.hypot(d[0], d[1]);
+                    double cost = current.cost() + step * (1 + Math.max(0, column(x, z).top() - level) * 0.8
+                        + terrainNoise(x, z) * 4.5 + field(x + 71, z - 93, 21, 107) * 3.5);
+                    if (cost >= costs.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    costs.put(key(x, z), cost);
+                    queue.add(new Node(x, z, cost));
+                }
+            }
+            wet = connectedTo(wet, key(center.x(), center.z()));
+            if (wet.size() < Math.min(target, 30)) return null;
+            // Filling a hollow requires every lower connected outlet to be included. Abort rather
+            // than place a dam if this natural basin runs to a cliff, cave or an oversized catchment.
+            List<Long> work = new ArrayList<>(wet);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    int x = point.x() + d[0], z = point.z() + d[1];
+                    long neighbor = key(x, z);
+                    if (wet.contains(neighbor) || column(x, z).top() >= level) continue;
+                    if (wet.size() >= 420 || Math.hypot(x - center.x(), z - center.z()) > 32
+                        || !eligible(x, z, level)) return null;
+                    wet.add(neighbor);
+                    work.add(neighbor);
+                }
+            }
+            return wet;
+        }
+
+        private Map<Long, Cell> waterCells(Set<Long> footprint, int level, long id) {
+            Map<Long, Cell> result = new HashMap<>();
+            for (long key : footprint) {
+                Point p = point(key);
+                if (!eligible(p.x(), p.z(), level)) return null;
+                boolean edge = false;
+                for (int[] d : CARDINALS) edge |= !footprint.contains(key(p.x() + d[0], p.z() + d[1]));
+                Column column = column(p.x(), p.z());
+                int depth = Math.max(level - column.top() + 1, edge ? 1 : 2 + (terrainNoise(p.x(), p.z()) > 0.55 ? 1 : 0));
+                depth = Math.min(depth, MAX_CARVE - Math.max(0, column.top() - level));
+                if (depth < 1 || depth > MAX_DEPTH) return null;
+                int bed = level - depth;
+                if (column.top() < bed || column.solidBottom() > bed - 2) return null;
+                ShoreMaterial material = wetMaterial(p.x(), p.z(), edge);
+                int sedimentDepth = sedimentDepth(p.x(), p.z());
+                if (column.solidBottom() > bed - sedimentDepth - 1) return null;
+                result.put(key, new Cell(p.x(), p.z(), level, bed, Math.max(level, column.top()),
+                    material, id, sedimentDepth));
+            }
+            return result;
+        }
+
+        private boolean contained(Map<Long, Cell> wet) {
+            for (Cell cell : wet.values()) {
+                for (int y = cell.bedY() - 2; y <= cell.bedY(); y++) {
+                    if (!solid(cell.x(), y, cell.z())) return false;
+                }
+                for (int[] d : CARDINALS) {
+                    int x = cell.x() + d[0], z = cell.z() + d[1];
+                    Cell neighbor = wet.get(key(x, z));
+                    if (neighbor == null) neighbor = cells.get(key(x, z));
+                    for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) {
+                        if (neighbor != null && neighbor.hasWater()) {
+                            if (neighbor.waterY() != cell.waterY()) return false;
+                            if (y > neighbor.bedY()) continue;
+                        }
+                        if (!solid(x, y, z)) return false;
+                    }
+                }
+            }
+            return true;
+        }
+
+        private void addFeature(long id, Kind kind, int level, List<Point> path, Map<Long, Cell> wet) {
+            int minX = Integer.MAX_VALUE, minZ = Integer.MAX_VALUE, maxX = Integer.MIN_VALUE, maxZ = Integer.MIN_VALUE;
+            int count = 0;
+            for (Cell cell : wet.values()) {
+                Cell old = cells.get(key(cell.x(), cell.z()));
+                if (old == null || !old.hasWater()) { cells.put(key(cell.x(), cell.z()), cell); count++; }
+                minX = Math.min(minX, cell.x()); minZ = Math.min(minZ, cell.z());
+                maxX = Math.max(maxX, cell.x()); maxZ = Math.max(maxZ, cell.z());
+            }
+            features.add(new Feature(id, kind, level, path, count, new Bounds(minX, minZ, maxX, maxZ)));
+        }
+
+        private static Set<Long> connectedTo(Set<Long> footprint, long start) {
+            Set<Long> connected = new HashSet<>();
+            List<Long> work = new ArrayList<>();
+            connected.add(start); work.add(start);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    long next = key(point.x() + d[0], point.z() + d[1]);
+                    if (footprint.contains(next) && connected.add(next)) work.add(next);
+                }
+            }
+            return connected;
+        }
+
+        private record ShoreNode(int x, int z, int level, long feature, double cost) {}
+
+        /** Sediment follows shallow topography in broad, discontinuous sheets. A second nearby
+         * pocket can share the same sheet; the result is not a one-block material ring. */
+        private void addSedimentSheets() {
+            Comparator<ShoreNode> order = Comparator.comparingDouble(ShoreNode::cost)
+                .thenComparingInt(ShoreNode::x).thenComparingInt(ShoreNode::z).thenComparingLong(ShoreNode::feature);
+            PriorityQueue<ShoreNode> queue = new PriorityQueue<>(order);
+            Map<Long, Double> best = new HashMap<>();
+            for (Cell cell : cells.values()) if (cell.hasWater()) {
+                queue.add(new ShoreNode(cell.x(), cell.z(), cell.waterY(), cell.featureId(), 0));
+                best.put(key(cell.x(), cell.z()), 0.0);
+            }
+            while (!queue.isEmpty()) {
+                ShoreNode node = queue.remove();
+                if (node.cost() > best.getOrDefault(key(node.x(), node.z()), Double.POSITIVE_INFINITY)) continue;
+                Column column = column(node.x(), node.z());
+                Cell existing = cells.get(key(node.x(), node.z()));
+                if (existing == null) {
+                    double extent = 9 + field(node.x(), node.z(), 25, 131) * 10;
+                    if (node.cost() > extent) continue;
+                    int delta = column.top() - node.level();
+                    if (delta < 0 || delta > 5) continue;
+                    // Low shore: waterline, then one-block steps. Cut at most two existing blocks;
+                    // far deposits keep the original landform and feather back into grass/stone.
+                    int terrace = node.level() + (int) Math.floor(node.cost() / 4.5);
+                    int bed = Math.max(node.level(), Math.max(column.top() - 2, Math.min(column.top(), terrace)));
+                    int depth = sedimentDepth(node.x(), node.z());
+                    if (column.solidBottom() > bed - depth - 1) continue;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        Cell next = cells.get(key(node.x() + d[0], node.z() + d[1]));
+                        if (next != null && next.hasWater() && bed < next.waterY()) safe = false;
+                    }
+                    if (!safe) continue;
+                    ShoreMaterial material = dryMaterial(node.x(), node.z(), node.cost() / extent);
+                    cells.put(key(node.x(), node.z()), new Cell(node.x(), node.z(), -1, bed,
+                        column.top(), material, node.feature(), depth));
+                }
+                for (int[] d : NEIGHBORS) {
+                    int x = node.x() + d[0], z = node.z() + d[1];
+                    if (!inside(x, z, RADIUS - 2)) continue;
+                    Cell water = cells.get(key(x, z));
+                    if (water != null && water.hasWater()) continue;
+                    Column next = column(x, z);
+                    if (next.top() < node.level() || next.top() > node.level() + 5) continue;
+                    double cost = node.cost() + Math.hypot(d[0], d[1])
+                        * (0.7 + Math.abs(next.top() - column.top()) * 0.32 + field(x, z, 12, 211) * 0.6);
+                    if (cost > 19 || cost >= best.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    best.put(key(x, z), cost);
+                    queue.add(new ShoreNode(x, z, node.level(), node.feature(), cost));
+                }
+            }
+        }
+
+        private int sedimentDepth(int x, int z) { return 3 + (int) (field(x, z, 15, 319) * 2.999); }
+
+        private ShoreMaterial wetMaterial(int x, int z, boolean edge) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            if (geology < 0.46) return ShoreMaterial.STONE;
+            if (geology < 0.65) return ShoreMaterial.GRAVEL;
+            if (!edge && geology > 0.78) return ShoreMaterial.CLAY;
+            return ShoreMaterial.SAND;
+        }
+
+        private ShoreMaterial dryMaterial(int x, int z, double distance) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            double grass = field(x + 103, z - 137, 19, 521);
+            if (grass > 0.62 || distance > 0.60 + grass * 0.65) return ShoreMaterial.GRASS;
+            if (geology < 0.46) return ShoreMaterial.STONE;
+            if (geology < 0.65) return ShoreMaterial.GRAVEL;
+            return ShoreMaterial.SAND;
+        }
+
+        private record Cliff(int x, int z, int dx, int dz, double score) {}
+        private record FlowNode(Position position, int reach) {}
+        private record Flow(Set<Position> volume, List<Position> path, FlowBounds bounds) {}
+
+        /** Pick rare exposed rock niches at the edges of real upper surfaces. The source replaces
+         * one rock block under an existing roof. Its outlet is already air over an eight-block drop;
+         * no source, shelf, dam, rock column or ocean is ever placed in empty terrain. */
+        private void addSprings() {
+            List<Cliff> cliffs = new ArrayList<>();
+            for (int x = -264; x <= 264; x += GRID) for (int z = -264; z <= 264; z += GRID) {
+                if (!inside(x, z, 264)) continue;
+                int top = coarse.computeIfAbsent(key(x, z), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                if (top < 88) continue;
+                for (int[] d : CARDINALS) {
+                    int nx = x + d[0] * GRID, nz = z + d[1] * GRID;
+                    int lower = coarse.computeIfAbsent(key(nx, nz), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                    if (top - lower < 16) continue;
+                    cliffs.add(new Cliff(x, z, d[0], d[1],
+                        Math.min(64, top - lower) * 0.06 + random(seed + 811, x + d[0], z + d[1]) * 3));
+                }
+            }
+            cliffs.sort(Comparator.comparingDouble(Cliff::score).reversed()
+                .thenComparingInt(Cliff::x).thenComparingInt(Cliff::z)
+                .thenComparingInt(Cliff::dx).thenComparingInt(Cliff::dz));
+            int attempts = 0;
+            for (Cliff cliff : cliffs) {
+                if (springs.size() >= 3 || attempts++ >= 160) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2, -4, 4}) {
+                    for (int along = 0; along < GRID; along++) {
+                        int x = cliff.x() + cliff.dx() * along - cliff.dz() * tangent;
+                        int z = cliff.z() + cliff.dz() * along + cliff.dx() * tangent;
+                        if (!inside(x, z, 266)) continue;
+                        int ox = x + cliff.dx(), oz = z + cliff.dz();
+                        Column rock = column(x, z), outletColumn = column(ox, oz);
+                        if (rock.top() < 80 || rock.top() - outletColumn.top() < 14) continue;
+                        // Five blocks below the highest natural surface is below the soil cap.
+                        int floor = Math.max(64, Math.max(rock.top() - 20, outletColumn.top() + 8));
+                        for (int y = rock.top() - 5; y >= floor; y -= 3) {
+                            Position source = new Position(x, y, z), outlet = new Position(ox, y, oz);
+                            if (nearModifiedGround(source, 32) || !separatedSpring(source) || !springNiche(source, cliff.dx(), cliff.dz())) continue;
+                            Flow flow = traceSpring(source, outlet);
+                            if (flow == null || flow.bounds().minY() > y - 12) continue;
+                            long id = mix(seed ^ (0x5F81A6L + springs.size() * 0x9E3779B97F4A7C15L));
+                            springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                            springFlow.addAll(flow.volume());
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+        }
+
+        private boolean nearModifiedGround(Position source, int distance) {
+            for (Cell cell : cells.values()) {
+                int dy = Math.max(Math.max(cell.bedY() - cell.sedimentDepth() - source.y(), 0),
+                    source.y() - cell.carveTop());
+                double horizontal = Math.hypot(source.x() - cell.x(), source.z() - cell.z());
+                if (Math.hypot(horizontal, dy) < distance) return true;
+            }
+            return false;
+        }
+
+        private boolean separatedSpring(Position source) {
+            for (Spring spring : springs) {
+                double horizontal = Math.hypot(source.x() - spring.source().x(), source.z() - spring.source().z());
+                int dy = Math.abs(source.y() - spring.source().y());
+                if (Math.hypot(horizontal, dy) < 64 || dy < 12) return false;
+            }
+            return true;
+        }
+
+        private record Wall(int x, int y, int z, int dx, int dz, double score) {}
+
+        /** Probe a few exposed faces below the highest surface as well. This finds overhangs and
+         * lower strata that a highest-column heightmap cannot represent, without inventing a ledge. */
+        private void addLowerWallSprings() {
+            List<Wall> candidates = new ArrayList<>();
+            for (int x = -240; x <= 240; x += 16) for (int z = -240; z <= 240; z += 16) {
+                if (!inside(x, z, 240)) continue;
+                int top = coarse.computeIfAbsent(key(x, z), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                for (int y = top - 32; y >= 64; y -= 16) {
+                    if (!solid(x, y, z)) continue;
+                    for (int[] direction : CARDINALS) {
+                        if (solid(x + direction[0] * 4, y, z + direction[1] * 4)) continue;
+                        candidates.add(new Wall(x, y, z, direction[0], direction[1],
+                            random(seed + 1217 + y, x + direction[0], z + direction[1]) * 3
+                                + Math.min(100, top - y) * 0.015));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Wall::score).reversed()
+                .thenComparingInt(Wall::x).thenComparingInt(Wall::z).thenComparingInt(Wall::y)
+                .thenComparingInt(Wall::dx).thenComparingInt(Wall::dz));
+            int attempts = 0;
+            for (Wall candidate : candidates) {
+                if (springs.size() >= 2 || attempts++ >= 96) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2}) {
+                    for (int along = 0; along < 4; along++) {
+                        int x = candidate.x() + candidate.dx() * along - candidate.dz() * tangent;
+                        int z = candidate.z() + candidate.dz() * along + candidate.dx() * tangent;
+                        for (int dy : new int[]{0, 3, -3, 6, -6}) {
+                            int y = candidate.y() + dy;
+                            if (y < 56 || column(x, z).top() - y < 24) continue;
+                            Position source = new Position(x, y, z);
+                            if (nearModifiedGround(source, 32) || !separatedSpring(source)
+                                || !springNiche(source, candidate.dx(), candidate.dz())) continue;
+                            Position outlet = new Position(x + candidate.dx(), y, z + candidate.dz());
+                            Flow flow = traceSpring(source, outlet);
+                            if (flow == null || flow.bounds().minY() > y - 12) continue;
+                            long id = mix(seed ^ (0x5F81A6L + springs.size() * 0x9E3779B97F4A7C15L));
+                            springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                            springFlow.addAll(flow.volume());
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+        }
+
+        private boolean springNiche(Position source, int dx, int dz) {
+            for (int y = source.y() - 3; y <= source.y() + 1; y++) {
+                if (!solid(source.x(), y, source.z())) return false;
+            }
+            for (int[] d : CARDINALS) {
+                if (d[0] == dx && d[1] == dz) continue;
+                if (!solid(source.x() + d[0], source.y(), source.z() + d[1])) return false;
+            }
+            for (int y = source.y(); y >= source.y() - 8; y--) {
+                if (solid(source.x() + dx, y, source.z() + dz)) return false;
+            }
+            return true;
+        }
+
+        /** Predict drainage through undecorated rock to select springs and inspection bounds.
+         * Descend through air first, then explore seven horizontal steps on a shelf. Later trees
+         * can divert the actual fluid: this prediction is not a bound on decorated-world physics.
+         * Integration tests trace actual water back to its source within the inspected chunk halo. */
+        private Flow traceSpring(Position source, Position outlet) {
+            Map<Position, Integer> reach = new HashMap<>();
+            Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<FlowNode> queue = new ArrayDeque<>();
+            reach.put(source, 7);
+            queue.add(new FlowNode(source, 7));
+            Position lowest = source;
+            while (!queue.isEmpty()) {
+                FlowNode node = queue.removeFirst();
+                Position at = node.position();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 24000) return null;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (!flowSolid(below, source)) {
+                    enqueueFlow(below, 7, at, queue, reach, parent);
+                    continue;
+                }
+                if (node.reach() <= 0) continue;
+                for (int[] d : CARDINALS) {
+                    Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+                    if (flowSolid(next, source)) continue;
+                    enqueueFlow(next, node.reach() - 1, at, queue, reach, parent);
+                }
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY;
+            int minZ = source.z(), maxZ = minZ;
+            for (Position position : reach.keySet()) {
+                minX = Math.min(minX, position.x()); maxX = Math.max(maxX, position.x());
+                minY = Math.min(minY, position.y()); maxY = Math.max(maxY, position.y());
+                minZ = Math.min(minZ, position.z()); maxZ = Math.max(maxZ, position.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Flow(Set.copyOf(reach.keySet()), path, new FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Position source) {
+            if (at.equals(source)) return false;
+            Cell cell = cells.get(key(at.x(), at.z()));
+            if (cell != null && at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            return solid(at.x(), at.y(), at.z());
+        }
+
+        private static void enqueueFlow(Position next, int available, Position from, ArrayDeque<FlowNode> queue,
+                                        Map<Position, Integer> reach, Map<Position, Position> parent) {
+            if (available <= reach.getOrDefault(next, -1)) return;
+            if (!reach.containsKey(next)) parent.put(next, from);
+            reach.put(next, available);
+            queue.addLast(new FlowNode(next, available));
+        }
+
+        private boolean nearWater(int x, int z, int distance) {
+            for (Feature feature : features) {
+                Point point = feature.path().getFirst();
+                if (Math.hypot(x - point.x(), z - point.z()) < distance) return true;
+            }
+            return false;
+        }
+
+        private boolean solid(int x, int y, int z) { samples++; return sampler.sample(x, y, z) > 0; }
+        private long featureId(int index) { return mix(seed ^ (0x51A7E7L + index * 0x9E3779B97F4A7C15L)); }
+
+        private double terrainNoise(int x, int z) { return field(x, z, 8, 31); }
+
+        private double field(int x, int z, int scale, long salt) {
+            int gx = Math.floorDiv(x, scale), gz = Math.floorDiv(z, scale);
+            double tx = smooth(Math.floorMod(x, scale) / (double) scale);
+            double tz = smooth(Math.floorMod(z, scale) / (double) scale);
+            double a = random(seed + salt, gx, gz) * (1 - tx) + random(seed + salt, gx + 1, gz) * tx;
+            double b = random(seed + salt, gx, gz + 1) * (1 - tx) + random(seed + salt, gx + 1, gz + 1) * tx;
+            return a * (1 - tz) + b * tz;
+        }
+    }
+
+    private static boolean inside(int x, int z, int radius) { return Math.hypot((double) x, z) < radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static Point point(long key) { return new Point((int) (key >> 32), (int) key); }
+    private static double smooth(double t) { return t * t * (3 - 2 * t); }
+    private static double random(long seed, int x, int z) { return (mix(seed ^ key(x, z)) >>> 11) * 0x1.0p-53; }
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredHydrologyRuntime.java

@@ -0,0 +1,148 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Map;
+import java.util.WeakHashMap;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+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.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+
+/** Alpha.6 only: immutable plans cached by world state, applied to fresh terrain before decoration. */
+public final class LayeredHydrologyRuntime {
+    private static final Map<RandomState, LayeredHydrology.Plan> PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+    private static final Map<RandomState, LayeredLavaDeposit.Plan> LAVA_PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+
+    private LayeredHydrologyRuntime() {}
+
+    public static boolean enabled(NoiseBasedChunkGenerator generator) {
+        return generator.generatorSettings().is(SanctuarySpawn.LAYERED_SETTINGS);
+    }
+
+    public static LayeredHydrology.Plan layeredPlan(ServerLevel level) {
+        return plan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static LayeredHydrology.Plan plan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        if (!enabled(generator)) throw new IllegalArgumentException("Layered hydrology is not enabled for this generator");
+        return PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var plan = LayeredHydrology.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z));
+            SanctuaryMod.LOGGER.info("Sanctuary layered hydrology: seed {}, {} features, {} columns, {} springs, {} ms",
+                state.seed(), plan.features().size(), plan.cells().size(), plan.springs().size(),
+                (System.nanoTime() - start) / 1_000_000);
+            return plan;
+        });
+    }
+
+    public static LayeredLavaDeposit.Plan lavaPlan(ServerLevel level) {
+        return lavaPlan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static LayeredLavaDeposit.Plan lavaPlan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        // Acquire the water plan before the lava cache lock; the water planner never acquires it.
+        var water = plan(generator, randomState);
+        return LAVA_PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var lava = LayeredLavaDeposit.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z), water);
+            SanctuaryMod.LOGGER.info("Sanctuary starter lava: seed {}, {} sources, access {}, {} ms",
+                state.seed(), lava.lavaCells().size(), lava.access(), (System.nanoTime() - start) / 1_000_000);
+            return lava;
+        });
+    }
+
+    public static void apply(NoiseBasedChunkGenerator generator, RandomState randomState, ChunkAccess chunk) {
+        if (!enabled(generator)) return;
+        var chunkPos = chunk.getPos();
+        if (Math.abs((long) chunkPos.x() * 16) > IslandShape.TERRAIN_LIMIT + 16L
+                || Math.abs((long) chunkPos.z() * 16) > IslandShape.TERRAIN_LIMIT + 16L) return;
+        var plan = plan(generator, randomState);
+        var cells = plan.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var springs = plan.springsInChunk(chunkPos.x(), chunkPos.z());
+        var outlets = plan.springs().stream().map(LayeredHydrology.Spring::outlet)
+            .filter(outlet -> (outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z()).toList();
+        var lava = lavaPlan(generator, randomState);
+        var lavaCells = lava.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var lavaSupports = lava.supportsInChunk(chunkPos.x(), chunkPos.z());
+        if (cells.isEmpty() && springs.isEmpty() && outlets.isEmpty() && lavaCells.isEmpty() && lavaSupports.isEmpty()) return;
+        BlockPos.MutableBlockPos pos = new BlockPos.MutableBlockPos();
+        // Validate all replacements and two intact support layers before modifying this chunk.
+        for (var cell : cells) {
+            for (int y = cell.bedY() - cell.sedimentDepth() - 1; y <= cell.bedY(); y++) {
+                requireSolid(chunk, pos.set(cell.x(), y, cell.z()), randomState.seed());
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            requireSolid(chunk, pos.set(source.x(), source.y(), source.z()), randomState.seed());
+        }
+        for (var support : lavaSupports) {
+            requireSolid(chunk, pos.set(support.x(), support.y(), support.z()), randomState.seed());
+            if (chunk.getBlockState(pos).ignitedByLava()) {
+                throw new IllegalStateException("Lava pocket requires nonflammable natural support at " + pos);
+            }
+        }
+        for (var cell : lavaCells) {
+            requireSolid(chunk, pos.set(cell.x(), cell.y(), cell.z()), randomState.seed());
+        }
+        for (var cell : cells) {
+            for (int depth = 0; depth < cell.sedimentDepth(); depth++) {
+                pos.set(cell.x(), cell.bedY() - depth, cell.z());
+                BlockState material = switch (cell.material()) {
+                    case SAND -> Blocks.SAND.defaultBlockState();
+                    case GRAVEL -> Blocks.GRAVEL.defaultBlockState();
+                    case CLAY -> Blocks.CLAY.defaultBlockState();
+                    case STONE -> Blocks.STONE.defaultBlockState();
+                    case GRASS -> (depth == 0 ? Blocks.GRASS_BLOCK : Blocks.DIRT).defaultBlockState();
+                };
+                chunk.setBlockState(pos, material, 0);
+            }
+            for (int y = cell.bedY() + 1; y <= Math.max(cell.waterY(), cell.carveTop()); y++) {
+                pos.set(cell.x(), y, cell.z());
+                chunk.setBlockState(pos, cell.hasWater() && y <= cell.waterY()
+                    ? Blocks.WATER.defaultBlockState() : Blocks.AIR.defaultBlockState(), 0);
+                if (cell.hasWater() && y <= cell.waterY()) chunk.markPosForPostProcessing(pos);
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            pos.set(source.x(), source.y(), source.z());
+            chunk.setBlockState(pos, Blocks.WATER.defaultBlockState(), 0);
+            // Only the source is generated. Vanilla fluid ticks create the descending waterfall.
+            chunk.markPosForPostProcessing(pos);
+        }
+        for (var cell : lavaCells) {
+            pos.set(cell.x(), cell.y(), cell.z());
+            chunk.setBlockState(pos, (cell.lava() ? Blocks.LAVA : Blocks.AIR).defaultBlockState(), 0);
+            if (cell.lava()) chunk.markPosForPostProcessing(pos);
+        }
+        // This existing vanilla queue is consumed after neighbouring chunks finish decoration.
+        // Mark the outlet in its own chunk, including when its source belongs to a neighbour.
+        for (var outlet : outlets) {
+            pos.set(outlet.x(), outlet.y(), outlet.z());
+            chunk.markPosForPostProcessing(pos);
+        }
+        Heightmap.primeHeightmaps(chunk, EnumSet.of(Heightmap.Types.WORLD_SURFACE_WG,
+            Heightmap.Types.OCEAN_FLOOR_WG));
+    }
+
+    private static void requireSolid(ChunkAccess chunk, BlockPos pos, long seed) {
+        if (!chunk.getBlockState(pos).isCollisionShapeFullBlock(chunk, pos)) {
+            throw new IllegalStateException("Layered hydrology differs from terrain at " + pos + " for seed " + seed);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredIslandBiomeSource.java

@@ -0,0 +1,73 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.stream.Stream;
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeResolver;
+import net.minecraft.world.level.biome.BiomeSource;
+import net.minecraft.world.level.biome.Climate;
+
+/** Alpha.6 palette: flowered upper meadows and distinct humid lower terraces. */
+public final class LayeredIslandBiomeSource extends BiomeSource {
+    public static final ResourceKey<Biome> MEADOW = key("layered_meadow");
+    public static final ResourceKey<Biome> FLOWER_MEADOW = key("layered_flower_meadow");
+    public static final ResourceKey<Biome> LOWER_GROVE = key("layered_lower_grove");
+    public static final ResourceKey<Biome> MOSSY_TERRACES = key("layered_mossy_terraces");
+    public static final ResourceKey<Biome> ROCKY_TERRACES = key("layered_rocky_terraces");
+
+    public static final MapCodec<LayeredIslandBiomeSource> CODEC = RecordCodecBuilder.mapCodec(instance -> instance.group(
+        Biome.CODEC.fieldOf("meadow").forGetter(source -> source.meadow),
+        Biome.CODEC.fieldOf("flower_meadow").forGetter(source -> source.flowerMeadow),
+        Biome.CODEC.fieldOf("lower_grove").forGetter(source -> source.lowerGrove),
+        Biome.CODEC.fieldOf("mossy_terraces").forGetter(source -> source.mossyTerraces),
+        Biome.CODEC.fieldOf("rocky_terraces").forGetter(source -> source.rockyTerraces)
+    ).apply(instance, LayeredIslandBiomeSource::new));
+
+    private final Holder<Biome> meadow;
+    private final Holder<Biome> flowerMeadow;
+    private final Holder<Biome> lowerGrove;
+    private final Holder<Biome> mossyTerraces;
+    private final Holder<Biome> rockyTerraces;
+
+    public LayeredIslandBiomeSource(Holder<Biome> meadow, Holder<Biome> flowerMeadow,
+            Holder<Biome> lowerGrove, Holder<Biome> mossyTerraces, Holder<Biome> rockyTerraces) {
+        this.meadow = meadow;
+        this.flowerMeadow = flowerMeadow;
+        this.lowerGrove = lowerGrove;
+        this.mossyTerraces = mossyTerraces;
+        this.rockyTerraces = rockyTerraces;
+    }
+
+    @Override
+    protected MapCodec<LayeredIslandBiomeSource> codec() { return CODEC; }
+
+    @Override
+    protected Stream<Holder<Biome>> collectPossibleBiomes() {
+        return Stream.of(meadow, flowerMeadow, lowerGrove, mossyTerraces, rockyTerraces);
+    }
+
+    @Override
+    public BiomeResolver createResolver(Climate.Sampler sampler) {
+        return (quartX, quartY, quartZ) -> {
+            int x = quartX * 4, y = quartY * 4, z = quartZ * 4;
+            float variation = sampler.temperature().sampleValue(x, 0, z);
+            float moisture = sampler.humidity().sampleValue(x, 0, z);
+            return switch (LayeredBiomePalette.select(y, variation, moisture)) {
+                case MEADOW -> meadow;
+                case FLOWER_MEADOW -> flowerMeadow;
+                case LOWER_GROVE -> lowerGrove;
+                case MOSSY_TERRACES -> mossyTerraces;
+                case ROCKY_TERRACES -> rockyTerraces;
+            };
+        };
+    }
+
+    private static ResourceKey<Biome> key(String path) {
+        return ResourceKey.create(Registries.BIOME, SanctuaryMod.id(path));
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredLavaDeposit.java

@@ -0,0 +1,223 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+/** One small, covered lava pocket in existing rock, reached from an existing outdoor ledge.
+ * No solid blocks are added, and unsuitable seeds are allowed to produce no deposit. */
+public final class LayeredLavaDeposit {
+    public static final int RADIUS = 192;
+    public static final int WATER_CLEARANCE = 32;
+    public static final int LAVA_VOLUME = 18;
+    private static final int ENTRY_DISTANCE = 8;
+    private static final int[][] DIRECTIONS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final Comparator<Position> POSITION_ORDER = Comparator.comparingInt(Position::x)
+        .thenComparingInt(Position::z).thenComparingInt(Position::y);
+    private static final Comparator<Cell> CELL_ORDER = Comparator.comparingInt(Cell::x)
+        .thenComparingInt(Cell::z).thenComparingInt(Cell::y);
+
+    private LayeredLavaDeposit() {}
+
+    public record Position(int x, int y, int z) {}
+    /** lava=false removes existing rock to open the two-block-high chamber or approach. */
+    public record Cell(int x, int y, int z, boolean lava) {}
+
+    public static final class Plan {
+        private final List<Cell> cells;
+        private final List<Cell> lavaCells;
+        private final List<Position> supports;
+        private final Optional<Position> access;
+        private final Map<Long, List<Cell>> chunks;
+        private final Map<Long, List<Position>> supportChunks;
+
+        private Plan(List<Cell> cells, Set<Position> supports, Position access) {
+            this.cells = cells.stream().sorted(CELL_ORDER).toList();
+            lavaCells = this.cells.stream().filter(Cell::lava).toList();
+            this.supports = supports.stream().sorted(POSITION_ORDER).toList();
+            this.access = Optional.ofNullable(access);
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : this.cells) byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4),
+                ignored -> new ArrayList<>()).add(cell);
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            chunks = Map.copyOf(byChunk);
+            Map<Long, List<Position>> bySupportChunk = new HashMap<>();
+            for (Position support : this.supports) bySupportChunk.computeIfAbsent(key(support.x() >> 4, support.z() >> 4),
+                ignored -> new ArrayList<>()).add(support);
+            bySupportChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            supportChunks = Map.copyOf(bySupportChunk);
+        }
+
+        public List<Cell> cells() { return cells; }
+        public List<Cell> lavaCells() { return lavaCells; }
+        public List<Position> supports() { return supports; }
+        /** Player feet on the existing ledge; this column was naturally open to the sky. */
+        public Optional<Position> access() { return access; }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Position> supportsInChunk(int x, int z) { return supportChunks.getOrDefault(key(x, z), List.of()); }
+    }
+
+    public static Plan create(long seed, LayeredHydrology.Sampler sampler, LayeredHydrology.Plan hydrology) {
+        return new Search(seed, sampler, hydrology).find();
+    }
+
+    private record Candidate(int x, int z, int dx, int dz, double score) {}
+
+    private static final class Search {
+        private final long seed;
+        private final LayeredHydrology.Sampler sampler;
+        private final LayeredHydrology.Plan hydrology;
+        private final Map<Long, Integer> heights = new HashMap<>();
+
+        Search(long seed, LayeredHydrology.Sampler sampler, LayeredHydrology.Plan hydrology) {
+            this.seed = seed;
+            this.sampler = sampler;
+            this.hydrology = hydrology;
+        }
+
+        Plan find() {
+            List<Candidate> candidates = new ArrayList<>();
+            for (int x = -184; x <= 184; x += 8) for (int z = -184; z <= 184; z += 8) {
+                if (!inside(x, z, RADIUS - 8)) continue;
+                int ledge = top(x, z);
+                if (ledge < 64 || ledge > 300) continue;
+                for (int[] direction : DIRECTIONS) {
+                    int cx = x - direction[0] * ENTRY_DISTANCE, cz = z - direction[1] * ENTRY_DISTANCE;
+                    if (!inside(cx, cz, RADIUS - 12) || !clearOfWater(cx, cz)) continue;
+                    int rise = top(cx, cz) - ledge;
+                    if (rise < 12) continue;
+                    candidates.add(new Candidate(x, z, direction[0], direction[1],
+                        random(seed, cx, cz) + Math.min(rise, 40) * 0.015));
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)
+                .thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (attempts++ >= 192) break;
+                // Refine the coarse edge, including a ledge lying between two eight-block samples.
+                for (int along = 0; along < 8; along++) for (int tangent : new int[]{0, -3, 3}) {
+                    int x = candidate.x() - candidate.dx() * along - candidate.dz() * tangent;
+                    int z = candidate.z() - candidate.dz() * along + candidate.dx() * tangent;
+                    Plan plan = tryNiche(x, z, candidate.dx(), candidate.dz());
+                    if (plan != null) return plan;
+                }
+            }
+            return new Plan(List.of(), Set.of(), null);
+        }
+
+        private Plan tryNiche(int entryX, int entryZ, int dx, int dz) {
+            int cx = entryX - dx * ENTRY_DISTANCE, cz = entryZ - dz * ENTRY_DISTANCE;
+            if (!inside(cx, cz, RADIUS - 12) || !clearOfWater(cx, cz)) return null;
+            int level = top(entryX, entryZ);
+            if (level < 64 || level > 300 || top(cx, cz) < level + 12) return null;
+            // The player can discover and enter from an actual outdoor ledge, not a sealed cave.
+            for (int y = level + 1; y < 384; y++) if (solid(entryX, y, entryZ)) return null;
+            for (int y = level - 2; y <= level; y++) if (!solid(entryX, y, entryZ)) return null;
+
+            List<Cell> cells = new ArrayList<>();
+            Set<Position> changed = new HashSet<>();
+            Set<Position> supports = new HashSet<>();
+            for (int x = cx - 1; x <= cx + 1; x++) for (int z = cz - 1; z <= cz + 1; z++) {
+                for (int y = level - 1; y <= level + 2; y++) {
+                    if (!solid(x, y, z)) return null;
+                    add(cells, changed, x, y, z, y <= level);
+                }
+            }
+            // A dry lip separates the ledge from the pool. Only the air above it is opened.
+            for (int distance = 2; distance < ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level + 1; y <= level + 2; y++) {
+                    if (solid(x, y, z)) add(cells, changed, x, y, z, false);
+                }
+            }
+            // Every carved column must lie under eight continuous natural rock blocks. This
+            // excludes soil-cap excavation at the entrance as well as exposed surface lava.
+            Map<Long, Integer> highest = new HashMap<>();
+            for (Cell cell : cells) highest.merge(key(cell.x(), cell.z()), cell.y(), Math::max);
+            for (var column : highest.entrySet()) {
+                int x = (int) (column.getKey() >> 32), z = (int) (long) column.getKey();
+                for (int y = column.getValue() + 1; y <= column.getValue() + 8; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // Three intact blocks under the pool, two-block-thick side walls, and a solid chamber
+            // surround prevent escape through an adjacent cave. No part of this shell is created.
+            for (int x = cx - 3; x <= cx + 3; x++) for (int z = cz - 3; z <= cz + 3; z++) {
+                for (int y = level - 4; y <= level + 2; y++) {
+                    if (changed.contains(new Position(x, y, z))) continue;
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // The natural roof also covers a conservative envelope around local lava fire spread.
+            // Its thickness keeps later surface vegetation well above the lava chamber.
+            for (int x = cx - 4; x <= cx + 4; x++) for (int z = cz - 4; z <= cz + 4; z++) {
+                for (int y = level + 3; y <= level + 10; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            for (int distance = 2; distance <= ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level - 2; y <= level; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            supports.removeAll(changed);
+            return new Plan(cells, supports, new Position(entryX, level + 1, entryZ));
+        }
+
+        private boolean requireRock(Set<Position> supports, int x, int y, int z) {
+            if (!solid(x, y, z)) return false;
+            supports.add(new Position(x, y, z));
+            return true;
+        }
+
+        private boolean clearOfWater(int x, int z) {
+            // The extra ten blocks include both the entrance and the complete protected shell.
+            int clearance = WATER_CLEARANCE + 10;
+            for (var cell : hydrology.cells()) {
+                long dx = x - cell.x(), dz = z - cell.z();
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            for (var spring : hydrology.springs()) {
+                var bounds = spring.flowBounds();
+                long dx = Math.max(Math.max((long) bounds.minX() - x, 0), (long) x - bounds.maxX());
+                long dz = Math.max(Math.max((long) bounds.minZ() - z, 0), (long) z - bounds.maxZ());
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            return true;
+        }
+
+        private int top(int x, int z) {
+            return heights.computeIfAbsent(key(x, z), ignored -> {
+                for (int y = 383; y >= 32; y -= 4) {
+                    if (!solid(x, y, z)) continue;
+                    for (int exact = Math.min(383, y + 3); exact > y; exact--) if (solid(x, exact, z)) return exact;
+                    return y;
+                }
+                return -1;
+            });
+        }
+
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+    }
+
+    private static void add(List<Cell> cells, Set<Position> changed, int x, int y, int z, boolean lava) {
+        if (changed.add(new Position(x, y, z))) cells.add(new Cell(x, y, z, lava));
+    }
+
+    private static boolean inside(int x, int z, int radius) { return (long) x * x + (long) z * z < (long) radius * radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static double random(long seed, int x, int z) {
+        long value = seed ^ key(x, z) ^ 0x1A7A5EEDL;
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return ((value ^ (value >>> 31)) >>> 11) * 0x1.0p-53;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredShoreSugarCaneFeature.java

@@ -0,0 +1,41 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import net.minecraft.core.BlockPos;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.feature.Feature;
+
+/** A few plants on existing suitable shores, after the forest has been decorated. */
+public final class LayeredShoreSugarCaneFeature implements Feature {
+    public static final MapCodec<LayeredShoreSugarCaneFeature> CODEC = MapCodec.unit(LayeredShoreSugarCaneFeature::new);
+
+    @Override
+    public MapCodec<LayeredShoreSugarCaneFeature> codec() {
+        return CODEC;
+    }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource random, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !LayeredHydrologyRuntime.enabled(noise)) return false;
+        var plan = LayeredHydrologyRuntime.plan(noise, level.getLevel().getChunkSource().randomState());
+        var cane = Blocks.SUGAR_CANE.defaultBlockState();
+        boolean placed = false;
+        for (var cell : plan.cellsInChunk(origin.getX() >> 4, origin.getZ() >> 4)) {
+            if (cell.hasWater() || random.nextInt(7) != 0) continue;
+            BlockPos base = new BlockPos(cell.x(), cell.bedY() + 1, cell.z());
+            if (!level.getBlockState(base).isAir() || !cane.canSurvive(level, base)) continue;
+            int height = 1 + random.nextInt(3);
+            for (int y = 0; y < height; y++) {
+                BlockPos pos = base.above(y);
+                if (!level.getBlockState(pos).isAir() || !cane.canSurvive(level, pos)) break;
+                setBlock(level, pos, cane);
+                placed = true;
+            }
+        }
+        return placed;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LayeredSpringOutlets.java

@@ -0,0 +1,94 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayList;
+import java.util.List;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.world.level.block.Block;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.VegetationBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.LevelChunk;
+import net.minecraft.world.level.chunk.ProtoChunk;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.material.Fluids;
+
+/** One-time alpha.6 outlet finishing, using vanilla's persisted and consumed generation queue. */
+public final class LayeredSpringOutlets {
+    public record Pending(List<LayeredHydrology.Position> sources, List<LayeredHydrology.Position> outlets) {
+        public static final Pending EMPTY = new Pending(List.of(), List.of());
+        public Pending { sources = List.copyOf(sources); outlets = List.copyOf(outlets); }
+        public boolean isEmpty() { return sources.isEmpty() && outlets.isEmpty(); }
+    }
+
+    private LayeredSpringOutlets() {}
+
+    /** Called before vanilla consumes the queue; a fully processed/reloaded chunk has no work. */
+    public static Pending capturePending(ServerLevel level, LevelChunk chunk) {
+        if (!(level.getChunkSource().getGenerator() instanceof NoiseBasedChunkGenerator noise)
+                || !LayeredHydrologyRuntime.enabled(noise)) return Pending.EMPTY;
+        boolean queued = false;
+        for (var section : chunk.getPostProcessing()) if (section != null && !section.isEmpty()) {
+            queued = true;
+            break;
+        }
+        if (!queued) return Pending.EMPTY;
+        var plan = LayeredHydrologyRuntime.plan(noise, level.getChunkSource().randomState());
+        List<LayeredHydrology.Position> sources = new ArrayList<>(), outlets = new ArrayList<>();
+        for (var spring : plan.springs()) {
+            if (markedHere(chunk, spring.source())) sources.add(spring.source());
+            if (markedHere(chunk, spring.outlet())) outlets.add(spring.outlet());
+        }
+        return new Pending(sources, outlets);
+    }
+
+    /** All neighbouring FEATURES have finished before a chunk reaches this stage. */
+    public static void finish(ServerLevel level, LevelChunk chunk, Pending pending) {
+        if (pending.isEmpty() || !(level.getChunkSource().getGenerator() instanceof NoiseBasedChunkGenerator noise)
+                || !LayeredHydrologyRuntime.enabled(noise)) return;
+        var random = level.getChunkSource().randomState();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        for (var outlet : pending.outlets()) {
+            if (!owns(chunk, outlet)) throw new IllegalArgumentException("An outlet belongs to another chunk: " + outlet);
+            if (random.sampleBlockValueUncached(density, outlet.x(), outlet.y(), outlet.z()) > 0) {
+                throw new IllegalStateException("A spring outlet must already be natural air: " + outlet);
+            }
+            BlockPos pos = blockPos(outlet);
+            BlockState current = chunk.getBlockState(pos);
+            if (removableDecoration(current)) {
+                // Only this declared air cell is reopened. Neighbour notification wakes the
+                // adjacent source even if its own chunk was post-processed first.
+                level.setBlock(pos, Blocks.AIR.defaultBlockState(), Block.UPDATE_ALL);
+            }
+        }
+        for (var source : pending.sources()) {
+            if (!owns(chunk, source)) throw new IllegalArgumentException("A source belongs to another chunk: " + source);
+            BlockPos pos = blockPos(source);
+            BlockState current = chunk.getBlockState(pos);
+            if (current.is(Blocks.WATER) && current.getFluidState().isSource()) {
+                level.scheduleTick(pos, Fluids.WATER, Fluids.WATER.getTickDelay(level));
+            }
+        }
+    }
+
+    private static boolean markedHere(LevelChunk chunk, LayeredHydrology.Position position) {
+        if (!owns(chunk, position)) return false;
+        var queue = chunk.getPostProcessing()[chunk.getSectionIndex(position.y())];
+        return queue != null && queue.contains(ProtoChunk.packOffsetCoordinates(blockPos(position)));
+    }
+
+    private static boolean owns(LevelChunk chunk, LayeredHydrology.Position position) {
+        return (position.x() >> 4) == chunk.getPos().x() && (position.z() >> 4) == chunk.getPos().z();
+    }
+
+    private static BlockPos blockPos(LayeredHydrology.Position position) {
+        return new BlockPos(position.x(), position.y(), position.z());
+    }
+
+    private static boolean removableDecoration(BlockState state) {
+        if (state.hasBlockEntity()) return false;
+        return state.is(Blocks.GLOW_LICHEN) || state.is(Blocks.VINE) || state.is(Blocks.MOSS_CARPET)
+            || state.getBlock() instanceof VegetationBlock || state.is(BlockTags.LEAVES) || state.is(BlockTags.LOGS);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LowerTerraceEcology.java

@@ -0,0 +1,21 @@
+package fr.koka.sanctuary.worldgen;
+
+/** Geometry checks shared by lower-ledge decoration and density diagnostics. */
+public final class LowerTerraceEcology {
+    @FunctionalInterface
+    public interface Sampler { float sample(int x, int y, int z); }
+
+    private LowerTerraceEcology() {}
+
+    public static int highestNaturalSurface(Sampler sampler, int x, int z) {
+        for (int y = 383; y >= 24; y--) if (sampler.sample(x, y, z) > 0) return y;
+        return -1;
+    }
+
+    /** A lower natural floor: three solid blocks, headroom, and real terrain at least eight blocks above. */
+    public static boolean isLowerTerrace(Sampler sampler, int x, int bedY, int z, int highestNaturalSurface) {
+        if (bedY < 32 || bedY > 312 || highestNaturalSurface < bedY + 8) return false;
+        for (int y = bedY - 2; y <= bedY; y++) if (sampler.sample(x, y, z) <= 0) return false;
+        return sampler.sample(x, bedY + 1, z) <= 0 && sampler.sample(x, bedY + 2, z) <= 0;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/LowerTerraceVegetationFeature.java

@@ -0,0 +1,126 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import java.util.HashSet;
+import java.util.Set;
+import net.minecraft.core.BlockPos;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+import net.minecraft.world.level.levelgen.feature.Feature;
+
+/** Decorates actual lower natural floors after the ordinary highest-surface vegetation.
+ * Each chunk owns its columns; planned water, sediments, lava and their supports are excluded. */
+public final class LowerTerraceVegetationFeature implements Feature {
+    public static final MapCodec<LowerTerraceVegetationFeature> CODEC = MapCodec.unit(LowerTerraceVegetationFeature::new);
+
+    @Override
+    public MapCodec<LowerTerraceVegetationFeature> codec() { return CODEC; }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource random, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !LayeredHydrologyRuntime.enabled(noise)) return false;
+        int minX = (origin.getX() >> 4) * 16, minZ = (origin.getZ() >> 4) * 16;
+        if (Math.abs((long) minX) > 288 || Math.abs((long) minZ) > 288) return false;
+        var state = level.getLevel().getChunkSource().randomState();
+        var water = LayeredHydrologyRuntime.plan(noise, state);
+        var lava = LayeredHydrologyRuntime.lavaPlan(noise, state);
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        LowerTerraceEcology.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        var climate = state.createClimateSampler(SamplerContext.EMPTY_UNCACHED);
+        Set<Long> lavaColumns = new HashSet<>();
+        for (var cell : lava.cells()) protectColumn(lavaColumns, cell.x(), cell.z());
+        for (var support : lava.supports()) protectColumn(lavaColumns, support.x(), support.z());
+        boolean changed = false;
+        BlockPos.MutableBlockPos floor = new BlockPos.MutableBlockPos();
+        for (int x = minX; x < minX + 16; x++) for (int z = minZ; z < minZ + 16; z++) {
+            if (blockedColumn(water, lavaColumns, x, z)) continue;
+            // A coherent moisture patch controls coverage, rather than an alternating block grid.
+            float growth = climate.humidity().sampleValue(x + 317, 0, z - 191);
+            if (growth < -0.30F) continue;
+            int highest = -1, terraces = 0;
+            for (int y = 319; y >= 32; y--) {
+                floor.set(x, y, z);
+                BlockState ground = level.getBlockState(floor);
+                if (!replaceableGround(ground)) continue;
+                if (highest < 0) {
+                    if (sampler.sample(x, y, z) > 0) highest = y;
+                    continue;
+                }
+                if (y > highest - 8) continue;
+                BlockPos plantPos = floor.above();
+                if (!level.getBlockState(plantPos).isAir() || !level.getBlockState(plantPos.above()).isAir()) continue;
+                if (!LowerTerraceEcology.isLowerTerrace(sampler, x, y, z, highest)) continue;
+                if (!ground.isCollisionShapeFullBlock(level, floor)
+                        || !level.getBlockState(floor.below()).isCollisionShapeFullBlock(level, floor.below())
+                        || !level.getBlockState(floor.below(2)).isCollisionShapeFullBlock(level, floor.below(2))) continue;
+                var biome = level.getBiome(plantPos);
+                if (biome.is(LayeredIslandBiomeSource.ROCKY_TERRACES)) continue;
+                boolean mossy = biome.is(LayeredIslandBiomeSource.MOSSY_TERRACES);
+                // Moss survives shaded ledges without needing artificial lighting. Existing grass
+                // is retained outside the moss biome; no supporting terrain is added to air.
+                if (mossy || !ground.is(Blocks.GRASS_BLOCK)) {
+                    setBlock(level, floor, Blocks.MOSS_BLOCK.defaultBlockState());
+                    changed = true;
+                }
+                if (random.nextInt(5) < 2) {
+                    BlockState plant = plant(mossy, random.nextInt(10));
+                    if (plant.canSurvive(level, plantPos)) {
+                        setBlock(level, plantPos, plant);
+                        changed = true;
+                    }
+                }
+                if (++terraces >= 4) break;
+            }
+        }
+        return changed;
+    }
+
+    private static BlockState plant(boolean mossy, int choice) {
+        if (mossy) return switch (choice) {
+            case 0 -> Blocks.FLOWERING_AZALEA.defaultBlockState();
+            case 1 -> Blocks.AZALEA.defaultBlockState();
+            case 2, 3 -> Blocks.FERN.defaultBlockState();
+            default -> Blocks.MOSS_CARPET.defaultBlockState();
+        };
+        return switch (choice) {
+            case 0 -> Blocks.OXEYE_DAISY.defaultBlockState();
+            case 1 -> Blocks.CORNFLOWER.defaultBlockState();
+            case 2 -> Blocks.AZURE_BLUET.defaultBlockState();
+            case 3 -> Blocks.DANDELION.defaultBlockState();
+            case 4 -> Blocks.BUSH.defaultBlockState();
+            default -> Blocks.SHORT_GRASS.defaultBlockState();
+        };
+    }
+
+    private static boolean replaceableGround(BlockState state) {
+        return state.is(Blocks.STONE) || state.is(Blocks.GRANITE) || state.is(Blocks.DIORITE)
+            || state.is(Blocks.ANDESITE) || state.is(Blocks.TUFF) || state.is(Blocks.DIRT)
+            || state.is(Blocks.GRASS_BLOCK) || state.is(Blocks.ROOTED_DIRT) || state.is(Blocks.COARSE_DIRT)
+            || state.is(Blocks.MOSS_BLOCK);
+    }
+
+    private static boolean blockedColumn(LayeredHydrology.Plan water, Set<Long> lavaColumns, int x, int z) {
+        if (lavaColumns.contains(key(x, z))) return true;
+        for (int dx = -1; dx <= 1; dx++) for (int dz = -1; dz <= 1; dz++) {
+            if (water.cellAt(x + dx, z + dz) != null) return true;
+        }
+        for (var spring : water.springs()) if (inside(spring.flowBounds(), x, z)) return true;
+        return false;
+    }
+
+    private static boolean inside(LayeredHydrology.FlowBounds bounds, int x, int z) {
+        return x >= bounds.minX() - 2 && x <= bounds.maxX() + 2
+            && z >= bounds.minZ() - 2 && z <= bounds.maxZ() + 2;
+    }
+
+    private static void protectColumn(Set<Long> columns, int x, int z) {
+        for (int dx = -2; dx <= 2; dx++) for (int dz = -2; dz <= 2; dz++) columns.add(key(x + dx, z + dz));
+    }
+
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/NaturalHydrology.java

@@ -0,0 +1,698 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.PriorityQueue;
+import java.util.Set;
+
+/** Alpha.5 surface water, broad natural sediment sheets and occasional exposed rock springs.
+ * This version is separate from SurfaceHydrology so previously created worlds keep alpha.4 terrain.
+ * Results retain no chunks, sampler, random state or Minecraft objects. */
+public final class NaturalHydrology {
+    public static final int RADIUS = 192;
+    public static final int MAX_CARVE = 4;
+    public static final int MAX_DEPTH = 3;
+    private static final int GRID = 8;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final int[][] NEIGHBORS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}, {1, 1}, {1, -1}, {-1, 1}, {-1, -1}};
+
+    private NaturalHydrology() {}
+
+    @FunctionalInterface
+    public interface Sampler { float sample(int x, int y, int z); }
+
+    public enum Kind { POND, LAKE, STREAM }
+    public enum ShoreMaterial { SAND, GRAVEL, CLAY, STONE, GRASS }
+    public record Point(int x, int z) {}
+    public record Bounds(int minX, int minZ, int maxX, int maxZ) {}
+
+    public record Position(int x, int y, int z) {}
+    public record FlowBounds(int minX, int minY, int minZ, int maxX, int maxY, int maxZ) {}
+    public record Spring(long id, Position source, Position outlet, List<Position> flowPath, FlowBounds flowBounds) {
+        public Spring { flowPath = List.copyOf(flowPath); }
+    }
+
+    /** Replaces existing solids bedY-sedimentDepth+1..bedY, with two intact natural supports below.
+     * Water occupies bedY+1..waterY; everything above it through carveTop is removed. For a dry
+     * terrace waterY=-1, and bedY+1..carveTop is removed (at most two original blocks). */
+    public record Cell(int x, int z, int waterY, int bedY, int carveTop,
+                       ShoreMaterial material, long featureId, int sedimentDepth) {
+        public boolean hasWater() { return waterY >= 0; }
+    }
+
+    public record Feature(long id, Kind kind, int waterY, List<Point> path, int waterCells, Bounds bounds) {
+        public Feature { path = List.copyOf(path); }
+    }
+
+    public static final class Plan {
+        private final Map<Long, Cell> cells;
+        private final Map<Long, List<Cell>> chunks;
+        private final List<Feature> features;
+        private final List<Spring> springs;
+        private final Map<Long, List<Spring>> springChunks;
+        private final Set<Position> springFlow;
+        private final int sampledColumns;
+        private final long densitySamples;
+
+        private Plan(Map<Long, Cell> source, List<Feature> features, List<Spring> springs, Set<Position> springFlow, int columns, long samples) {
+            List<Cell> sorted = source.values().stream()
+                .sorted(Comparator.comparingInt(Cell::x).thenComparingInt(Cell::z)).toList();
+            Map<Long, Cell> ordered = new LinkedHashMap<>();
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : sorted) {
+                ordered.put(key(cell.x(), cell.z()), cell);
+                byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4), ignored -> new ArrayList<>()).add(cell);
+            }
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            cells = Collections.unmodifiableMap(ordered);
+            chunks = Map.copyOf(byChunk);
+            this.features = List.copyOf(features);
+            this.springs = List.copyOf(springs);
+            this.springFlow = Set.copyOf(springFlow);
+            Map<Long, List<Spring>> groupedSprings = new HashMap<>();
+            for (Spring spring : springs) groupedSprings.computeIfAbsent(
+                key(spring.source().x() >> 4, spring.source().z() >> 4), ignored -> new ArrayList<>()).add(spring);
+            groupedSprings.replaceAll((ignored, values) -> List.copyOf(values));
+            springChunks = Map.copyOf(groupedSprings);
+            sampledColumns = columns;
+            densitySamples = samples;
+        }
+
+        public Cell cellAt(int x, int z) { return cells.get(key(x, z)); }
+        public Collection<Cell> cells() { return cells.values(); }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Feature> features() { return features; }
+        public List<Spring> springs() { return springs; }
+        public List<Spring> springsInChunk(int x, int z) { return springChunks.getOrDefault(key(x, z), List.of()); }
+        /** Prediction in undecorated density, not a restriction on Minecraft fluid simulation. */
+        public boolean allowsSpringFlow(int x, int y, int z) { return springFlow.contains(new Position(x, y, z)); }
+        public int sampledColumns() { return sampledColumns; }
+        public long densitySamples() { return densitySamples; }
+    }
+
+    public static Plan create(long seed, Sampler sampler) {
+        return new Planner(seed, sampler).build();
+    }
+
+    private record Column(int top, int solidBottom) {}
+    private record Candidate(int x, int z, double score) {}
+    private record Node(int x, int z, double cost) {}
+    private static final Comparator<Node> NODE_ORDER = Comparator.comparingDouble(Node::cost)
+        .thenComparingInt(Node::x).thenComparingInt(Node::z);
+
+    private static final class Planner {
+        private final long seed;
+        private final Sampler sampler;
+        private final Map<Long, Column> columns = new HashMap<>();
+        private final Map<Long, Integer> coarse = new HashMap<>();
+        private final Map<Long, Cell> cells = new HashMap<>();
+        private final List<Feature> features = new ArrayList<>();
+        private final List<Spring> springs = new ArrayList<>();
+        private final Set<Position> springFlow = new HashSet<>();
+        private long samples;
+
+        Planner(long seed, Sampler sampler) { this.seed = seed; this.sampler = sampler; }
+
+        Plan build() {
+            List<Candidate> candidates = candidates();
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (features.size() >= 5 || attempts++ >= 96) break;
+                Point center = new Point(candidate.x(), candidate.z());
+                if (nearWater(center.x(), center.z(), 38)) continue;
+                Column column = column(center.x(), center.z());
+                if (column.top() < 64 || column.top() - column.solidBottom() < 7) continue;
+                Kind kind = features.size() < 2 ? Kind.LAKE : Kind.POND;
+                int target = kind == Kind.LAKE ? 190 + (int) (random(seed, center.x(), center.z()) * 130)
+                    : 55 + (int) (random(seed + 1, center.x(), center.z()) * 55);
+                // Prefer an existing low spot; a shallow cut is the fallback on level terrain.
+                for (int level : new int[]{column.top() + 1, column.top(), column.top() - 1}) {
+                    Set<Long> footprint = growBasin(center, level, target);
+                    if (footprint == null) continue;
+                    long id = featureId(features.size());
+                    Map<Long, Cell> wet = waterCells(footprint, level, id);
+                    if (wet == null || !contained(wet)) continue;
+                    addFeature(id, kind, level, List.of(center), wet);
+                    break;
+                }
+            }
+            // One quiet stream connects a basin to a nearby surface refuge at the same water level.
+            // Its route follows low excavation cost through the relief; it has no falling outlets.
+            boolean stream = false;
+            for (Feature source : List.copyOf(features)) if (addStream(source)) { stream = true; break; }
+            if (!stream) addPlateauStream(candidates);
+            addSedimentSheets();
+            addSprings();
+            return new Plan(cells, features, springs, springFlow, columns.size(), samples);
+        }
+
+        private List<Candidate> candidates() {
+            for (int x = -RADIUS; x <= RADIUS; x += GRID) {
+                for (int z = -RADIUS; z <= RADIUS; z += GRID) {
+                    if (inside(x, z, RADIUS)) coarse.put(key(x, z), coarseTop(x, z));
+                }
+            }
+            List<Candidate> result = new ArrayList<>();
+            for (int x = -RADIUS + GRID; x < RADIUS; x += GRID) {
+                for (int z = -RADIUS + GRID; z < RADIUS; z += GRID) {
+                    int height = coarse.getOrDefault(key(x, z), -1);
+                    if (height < 64 || !inside(x, z, RADIUS - 24)) continue;
+                    double average = 0;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        int neighbor = coarse.getOrDefault(key(x + d[0] * GRID, z + d[1] * GRID), -1);
+                        if (neighbor < 64 || Math.abs(neighbor - height) > 16) safe = false;
+                        average += neighbor * 0.25;
+                    }
+                    if (safe) result.add(new Candidate(x, z,
+                        (average - height) * 2.0 + random(seed + 2, x, z) * 3.0));
+                }
+            }
+            result.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z));
+            return result;
+        }
+
+        private int coarseTop(int x, int z) {
+            for (int y = 383; y >= 32; y -= 4) if (solid(x, y, z)) return y;
+            return -1;
+        }
+
+        private Column column(int x, int z) {
+            long key = key(x, z);
+            Column old = columns.get(key);
+            if (old != null) return old;
+            int top = -1;
+            // Exact scan, including everything above the planned water: a cave roof cannot be
+            // mistaken for a surface. Only candidates and their nearby shore need this refinement.
+            for (int y = 383; y >= 24; y--) {
+                if (solid(x, y, z)) { top = y; break; }
+            }
+            int bottom = top;
+            if (top >= 0) {
+                while (bottom > Math.max(16, top - 16) && solid(x, bottom - 1, z)) bottom--;
+            }
+            Column created = new Column(top, bottom);
+            columns.put(key, created);
+            return created;
+        }
+
+        private boolean eligible(int x, int z, int level) {
+            if (level < 32 || level >= 383 || !inside(x, z, RADIUS - 2)) return false;
+            Cell old = cells.get(key(x, z));
+            if (old != null && old.hasWater() && old.waterY() != level) return false;
+            Column column = column(x, z);
+            return column.top() >= level - 3 && column.top() < level + MAX_CARVE
+                && column.solidBottom() <= Math.min(column.top(), level - 1) - 4;
+        }
+
+        private Set<Long> growBasin(Point center, int level, int target) {
+            if (!eligible(center.x(), center.z(), level)) return null;
+            Set<Long> wet = new HashSet<>();
+            Map<Long, Double> costs = new HashMap<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            queue.add(new Node(center.x(), center.z(), 0));
+            costs.put(key(center.x(), center.z()), 0.0);
+            while (!queue.isEmpty() && wet.size() < target) {
+                Node current = queue.remove();
+                if (current.cost() > costs.getOrDefault(key(current.x(), current.z()), Double.POSITIVE_INFINITY)) continue;
+                if (!eligible(current.x(), current.z(), level)) continue;
+                wet.add(key(current.x(), current.z()));
+                for (int[] d : NEIGHBORS) {
+                    int x = current.x() + d[0], z = current.z() + d[1];
+                    if (Math.hypot(x - center.x(), z - center.z()) > 28 || wet.contains(key(x, z))) continue;
+                    if (!eligible(x, z, level)) continue;
+                    double step = Math.hypot(d[0], d[1]);
+                    double cost = current.cost() + step * (1 + Math.max(0, column(x, z).top() - level) * 0.8
+                        + terrainNoise(x, z) * 4.5 + field(x + 71, z - 93, 21, 107) * 3.5);
+                    if (cost >= costs.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    costs.put(key(x, z), cost);
+                    queue.add(new Node(x, z, cost));
+                }
+            }
+            wet = connectedTo(wet, key(center.x(), center.z()));
+            if (wet.size() < Math.min(target, 30)) return null;
+            // Filling a hollow requires every lower connected outlet to be included. Abort rather
+            // than place a dam if this natural basin runs to a cliff, cave or an oversized catchment.
+            List<Long> work = new ArrayList<>(wet);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    int x = point.x() + d[0], z = point.z() + d[1];
+                    long neighbor = key(x, z);
+                    if (wet.contains(neighbor) || column(x, z).top() >= level) continue;
+                    if (wet.size() >= 420 || Math.hypot(x - center.x(), z - center.z()) > 32
+                        || !eligible(x, z, level)) return null;
+                    wet.add(neighbor);
+                    work.add(neighbor);
+                }
+            }
+            return wet;
+        }
+
+        private Map<Long, Cell> waterCells(Set<Long> footprint, int level, long id) {
+            Map<Long, Cell> result = new HashMap<>();
+            for (long key : footprint) {
+                Point p = point(key);
+                if (!eligible(p.x(), p.z(), level)) return null;
+                boolean edge = false;
+                for (int[] d : CARDINALS) edge |= !footprint.contains(key(p.x() + d[0], p.z() + d[1]));
+                Column column = column(p.x(), p.z());
+                int depth = Math.max(level - column.top() + 1, edge ? 1 : 2 + (terrainNoise(p.x(), p.z()) > 0.55 ? 1 : 0));
+                depth = Math.min(depth, MAX_CARVE - Math.max(0, column.top() - level));
+                if (depth < 1 || depth > MAX_DEPTH) return null;
+                int bed = level - depth;
+                if (column.top() < bed || column.solidBottom() > bed - 2) return null;
+                ShoreMaterial material = wetMaterial(p.x(), p.z(), edge);
+                int sedimentDepth = sedimentDepth(p.x(), p.z());
+                if (column.solidBottom() > bed - sedimentDepth - 1) return null;
+                result.put(key, new Cell(p.x(), p.z(), level, bed, Math.max(level, column.top()),
+                    material, id, sedimentDepth));
+            }
+            return result;
+        }
+
+        private boolean contained(Map<Long, Cell> wet) {
+            for (Cell cell : wet.values()) {
+                for (int y = cell.bedY() - 2; y <= cell.bedY(); y++) {
+                    if (!solid(cell.x(), y, cell.z())) return false;
+                }
+                for (int[] d : CARDINALS) {
+                    int x = cell.x() + d[0], z = cell.z() + d[1];
+                    Cell neighbor = wet.get(key(x, z));
+                    if (neighbor == null) neighbor = cells.get(key(x, z));
+                    for (int y = cell.bedY() + 1; y <= cell.waterY(); y++) {
+                        if (neighbor != null && neighbor.hasWater()) {
+                            if (neighbor.waterY() != cell.waterY()) return false;
+                            if (y > neighbor.bedY()) continue;
+                        }
+                        if (!solid(x, y, z)) return false;
+                    }
+                }
+            }
+            return true;
+        }
+
+        private void addFeature(long id, Kind kind, int level, List<Point> path, Map<Long, Cell> wet) {
+            int minX = Integer.MAX_VALUE, minZ = Integer.MAX_VALUE, maxX = Integer.MIN_VALUE, maxZ = Integer.MIN_VALUE;
+            int count = 0;
+            for (Cell cell : wet.values()) {
+                Cell old = cells.get(key(cell.x(), cell.z()));
+                if (old == null || !old.hasWater()) { cells.put(key(cell.x(), cell.z()), cell); count++; }
+                minX = Math.min(minX, cell.x()); minZ = Math.min(minZ, cell.z());
+                maxX = Math.max(maxX, cell.x()); maxZ = Math.max(maxZ, cell.z());
+            }
+            features.add(new Feature(id, kind, level, path, count, new Bounds(minX, minZ, maxX, maxZ)));
+        }
+
+        private boolean addStream(Feature source) {
+            Point start = source.path().getFirst();
+            int level = source.waterY();
+            Map<Long, Double> costs = new HashMap<>();
+            Map<Long, Long> parent = new HashMap<>();
+            PriorityQueue<Node> queue = new PriorityQueue<>(NODE_ORDER);
+            List<Node> refuges = new ArrayList<>();
+            long startKey = key(start.x(), start.z());
+            costs.put(startKey, 0.0);
+            queue.add(new Node(start.x(), start.z(), 0));
+            int visited = 0;
+            while (!queue.isEmpty() && visited++ < 1200) {
+                Node node = queue.remove();
+                long at = key(node.x(), node.z());
+                if (node.cost() > costs.getOrDefault(at, Double.POSITIVE_INFINITY)) continue;
+                double distance = Math.hypot(node.x() - start.x(), node.z() - start.z());
+                if (distance >= 44 && distance <= 76 && column(node.x(), node.z()).top() <= level + 3) refuges.add(node);
+                for (int[] d : NEIGHBORS) {
+                    int x = node.x() + d[0] * 4, z = node.z() + d[1] * 4;
+                    if (Math.hypot(x - start.x(), z - start.z()) > 88 || !eligible(x, z, level)) continue;
+                    long next = key(x, z);
+                    double cost = node.cost() + Math.hypot(d[0], d[1])
+                        * (4 + Math.abs(column(x, z).top() - level) * 1.4 + terrainNoise(x, z) * 4);
+                    if (cost >= costs.getOrDefault(next, Double.POSITIVE_INFINITY)) continue;
+                    costs.put(next, cost); parent.put(next, at); queue.add(new Node(x, z, cost));
+                }
+            }
+            refuges.sort(Comparator.comparingDouble((Node n) -> n.cost() / Math.hypot(n.x() - start.x(), n.z() - start.z()))
+                .thenComparingInt(Node::x).thenComparingInt(Node::z));
+            int attempts = 0;
+            for (Node refuge : refuges) {
+                if (attempts++ >= 24) break;
+                List<Point> path = new ArrayList<>();
+                long cursor = key(refuge.x(), refuge.z());
+                while (cursor != startKey) { path.add(point(cursor)); cursor = parent.get(cursor); }
+                path.add(start); Collections.reverse(path);
+                Set<Long> corridor = new HashSet<>();
+                for (int i = 1; i < path.size(); i++) {
+                    Point a = path.get(i - 1), b = path.get(i);
+                    int length = Math.max(Math.abs(b.x() - a.x()), Math.abs(b.z() - a.z()));
+                    for (int step = 0; step <= length; step++) {
+                        int x = a.x() + (b.x() - a.x()) * step / length;
+                        int z = a.z() + (b.z() - a.z()) * step / length;
+                        int width = terrainNoise(x + 17, z + 29) > 0.65 ? 2 : 1;
+                        for (int dx = -width; dx <= width; dx++) for (int dz = -width; dz <= width; dz++) {
+                            if (dx * dx + dz * dz <= width * width + 1) corridor.add(key(x + dx, z + dz));
+                        }
+                    }
+                }
+                Set<Long> refugePool = growBasin(new Point(refuge.x(), refuge.z()), level, 36);
+                if (refugePool == null) continue;
+                corridor.addAll(refugePool);
+                if (!closeStreamOutlets(corridor, level)) continue;
+                long id = featureId(features.size());
+                Map<Long, Cell> wet = waterCells(corridor, level, id);
+                if (wet == null || !contained(wet)) continue;
+                addFeature(id, Kind.STREAM, level, path, wet);
+                return true;
+            }
+            return false;
+        }
+
+        /** Low lake floors may be trapped below every nearby plateau. Try a small natural surface
+         * refuge as a source too, retaining it only if a fully contained stream can actually leave it. */
+        private boolean addPlateauStream(List<Candidate> candidates) {
+            List<Candidate> plateaus = candidates.stream().filter(candidate -> flatness(candidate.x(), candidate.z()) <= 6)
+                .sorted(Comparator.comparingDouble((Candidate c) -> flatness(c.x(), c.z())
+                    - random(seed + 91, c.x(), c.z()) * 2).thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)).toList();
+            int attempts = 0;
+            for (Candidate candidate : plateaus) {
+                if (attempts++ >= 20) break;
+                Point center = new Point(candidate.x(), candidate.z());
+                if (nearWater(center.x(), center.z(), 24)) continue;
+                Column column = column(center.x(), center.z());
+                if (column.top() < 64 || column.top() - column.solidBottom() < 7) continue;
+                for (int level : new int[]{column.top(), column.top() - 1}) {
+                    Set<Long> footprint = growBasin(center, level, 40);
+                    if (footprint == null) continue;
+                    long id = featureId(features.size());
+                    Map<Long, Cell> wet = waterCells(footprint, level, id);
+                    if (wet == null || !contained(wet)) continue;
+                    addFeature(id, Kind.POND, level, List.of(center), wet);
+                    if (addStream(features.getLast())) return true;
+                    features.removeLast();
+                    cells.values().removeIf(cell -> cell.featureId() == id);
+                }
+            }
+            return false;
+        }
+
+        private int flatness(int x, int z) {
+            int low = coarse.getOrDefault(key(x, z), -1000), high = low;
+            for (int[] d : CARDINALS) {
+                int value = coarse.getOrDefault(key(x + d[0] * GRID, z + d[1] * GRID), -1000);
+                low = Math.min(low, value); high = Math.max(high, value);
+            }
+            return high - low;
+        }
+
+        /** Include small connected low spots beside a channel; reject large/deep/open outlets.
+         * This adds water to a verified natural hollow, never rock to close a leak. */
+        private boolean closeStreamOutlets(Set<Long> corridor, int level) {
+            int maximum = Math.min(900, corridor.size() + 180);
+            List<Long> work = new ArrayList<>(corridor);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    int x = point.x() + d[0], z = point.z() + d[1];
+                    long next = key(x, z);
+                    Cell old = cells.get(next);
+                    if (corridor.contains(next) || old != null && old.hasWater() && old.waterY() == level
+                        || column(x, z).top() >= level) continue;
+                    if (corridor.size() >= maximum || !eligible(x, z, level)) return false;
+                    corridor.add(next); work.add(next);
+                }
+            }
+            return true;
+        }
+
+        private static Set<Long> connectedTo(Set<Long> footprint, long start) {
+            Set<Long> connected = new HashSet<>();
+            List<Long> work = new ArrayList<>();
+            connected.add(start); work.add(start);
+            for (int i = 0; i < work.size(); i++) {
+                Point point = point(work.get(i));
+                for (int[] d : CARDINALS) {
+                    long next = key(point.x() + d[0], point.z() + d[1]);
+                    if (footprint.contains(next) && connected.add(next)) work.add(next);
+                }
+            }
+            return connected;
+        }
+
+        private record ShoreNode(int x, int z, int level, long feature, double cost) {}
+
+        /** Sediment follows shallow topography in broad, discontinuous sheets. A second nearby
+         * pocket can share the same sheet; the result is not a one-block material ring. */
+        private void addSedimentSheets() {
+            Comparator<ShoreNode> order = Comparator.comparingDouble(ShoreNode::cost)
+                .thenComparingInt(ShoreNode::x).thenComparingInt(ShoreNode::z).thenComparingLong(ShoreNode::feature);
+            PriorityQueue<ShoreNode> queue = new PriorityQueue<>(order);
+            Map<Long, Double> best = new HashMap<>();
+            for (Cell cell : cells.values()) if (cell.hasWater()) {
+                queue.add(new ShoreNode(cell.x(), cell.z(), cell.waterY(), cell.featureId(), 0));
+                best.put(key(cell.x(), cell.z()), 0.0);
+            }
+            while (!queue.isEmpty()) {
+                ShoreNode node = queue.remove();
+                if (node.cost() > best.getOrDefault(key(node.x(), node.z()), Double.POSITIVE_INFINITY)) continue;
+                Column column = column(node.x(), node.z());
+                Cell existing = cells.get(key(node.x(), node.z()));
+                if (existing == null) {
+                    double extent = 9 + field(node.x(), node.z(), 25, 131) * 10;
+                    if (node.cost() > extent) continue;
+                    int delta = column.top() - node.level();
+                    if (delta < 0 || delta > 5) continue;
+                    // Low shore: waterline, then one-block steps. Cut at most two existing blocks;
+                    // far deposits keep the original landform and feather back into grass/stone.
+                    int terrace = node.level() + (int) Math.floor(node.cost() / 4.5);
+                    int bed = Math.max(node.level(), Math.max(column.top() - 2, Math.min(column.top(), terrace)));
+                    int depth = sedimentDepth(node.x(), node.z());
+                    if (column.solidBottom() > bed - depth - 1) continue;
+                    boolean safe = true;
+                    for (int[] d : CARDINALS) {
+                        Cell next = cells.get(key(node.x() + d[0], node.z() + d[1]));
+                        if (next != null && next.hasWater() && bed < next.waterY()) safe = false;
+                    }
+                    if (!safe) continue;
+                    ShoreMaterial material = dryMaterial(node.x(), node.z(), node.cost() / extent);
+                    cells.put(key(node.x(), node.z()), new Cell(node.x(), node.z(), -1, bed,
+                        column.top(), material, node.feature(), depth));
+                }
+                for (int[] d : NEIGHBORS) {
+                    int x = node.x() + d[0], z = node.z() + d[1];
+                    if (!inside(x, z, RADIUS - 2)) continue;
+                    Cell water = cells.get(key(x, z));
+                    if (water != null && water.hasWater()) continue;
+                    Column next = column(x, z);
+                    if (next.top() < node.level() || next.top() > node.level() + 5) continue;
+                    double cost = node.cost() + Math.hypot(d[0], d[1])
+                        * (0.7 + Math.abs(next.top() - column.top()) * 0.32 + field(x, z, 12, 211) * 0.6);
+                    if (cost > 19 || cost >= best.getOrDefault(key(x, z), Double.POSITIVE_INFINITY)) continue;
+                    best.put(key(x, z), cost);
+                    queue.add(new ShoreNode(x, z, node.level(), node.feature(), cost));
+                }
+            }
+        }
+
+        private int sedimentDepth(int x, int z) { return 3 + (int) (field(x, z, 15, 319) * 2.999); }
+
+        private ShoreMaterial wetMaterial(int x, int z, boolean edge) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            if (geology < 0.29) return ShoreMaterial.STONE;
+            if (geology < 0.50) return ShoreMaterial.GRAVEL;
+            if (!edge && geology > 0.78) return ShoreMaterial.CLAY;
+            return ShoreMaterial.SAND;
+        }
+
+        private ShoreMaterial dryMaterial(int x, int z, double distance) {
+            double geology = field(x, z, 24, 503) * 0.75 + field(x, z, 7, 509) * 0.25;
+            double grass = field(x + 103, z - 137, 19, 521);
+            if (grass > 0.68 || distance > 0.60 + grass * 0.65) return ShoreMaterial.GRASS;
+            if (geology < 0.29) return ShoreMaterial.STONE;
+            if (geology < 0.50) return ShoreMaterial.GRAVEL;
+            return ShoreMaterial.SAND;
+        }
+
+        private record Cliff(int x, int z, int dx, int dz, double score) {}
+        private record FlowNode(Position position, int reach) {}
+        private record Flow(Set<Position> volume, List<Position> path, FlowBounds bounds) {}
+
+        /** Pick rare exposed rock niches at the edges of real upper surfaces. The source replaces
+         * one rock block under an existing roof. Its outlet is already air over an eight-block drop;
+         * no source, shelf, dam, rock column or ocean is ever placed in empty terrain. */
+        private void addSprings() {
+            List<Cliff> cliffs = new ArrayList<>();
+            for (int x = -264; x <= 264; x += GRID) for (int z = -264; z <= 264; z += GRID) {
+                if (!inside(x, z, 264)) continue;
+                int top = coarse.computeIfAbsent(key(x, z), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                if (top < 88) continue;
+                for (int[] d : CARDINALS) {
+                    int nx = x + d[0] * GRID, nz = z + d[1] * GRID;
+                    int lower = coarse.computeIfAbsent(key(nx, nz), ignored -> coarseTop(point(ignored).x(), point(ignored).z()));
+                    if (top - lower < 16) continue;
+                    cliffs.add(new Cliff(x, z, d[0], d[1],
+                        Math.min(64, top - lower) * 0.06 + random(seed + 811, x + d[0], z + d[1]) * 3));
+                }
+            }
+            cliffs.sort(Comparator.comparingDouble(Cliff::score).reversed()
+                .thenComparingInt(Cliff::x).thenComparingInt(Cliff::z)
+                .thenComparingInt(Cliff::dx).thenComparingInt(Cliff::dz));
+            int attempts = 0;
+            for (Cliff cliff : cliffs) {
+                if (springs.size() >= 3 || attempts++ >= 160) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2, -4, 4}) {
+                    for (int along = 0; along < GRID; along++) {
+                        int x = cliff.x() + cliff.dx() * along - cliff.dz() * tangent;
+                        int z = cliff.z() + cliff.dz() * along + cliff.dx() * tangent;
+                        if (!inside(x, z, 266) || nearModifiedGround(x, z, 32)) continue;
+                        int ox = x + cliff.dx(), oz = z + cliff.dz();
+                        Column rock = column(x, z), outletColumn = column(ox, oz);
+                        if (rock.top() < 80 || rock.top() - outletColumn.top() < 14) continue;
+                        // Five blocks below the highest natural surface is below the soil cap.
+                        int floor = Math.max(64, Math.max(rock.top() - 20, outletColumn.top() + 8));
+                        for (int y = rock.top() - 5; y >= floor; y -= 3) {
+                            Position source = new Position(x, y, z), outlet = new Position(ox, y, oz);
+                            if (!separatedSpring(source) || !springNiche(source, cliff.dx(), cliff.dz())) continue;
+                            Flow flow = traceSpring(source, outlet);
+                            if (flow == null || flow.bounds().minY() > y - 12) continue;
+                            long id = mix(seed ^ (0x5F81A6L + springs.size() * 0x9E3779B97F4A7C15L));
+                            springs.add(new Spring(id, source, outlet, flow.path(), flow.bounds()));
+                            springFlow.addAll(flow.volume());
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+        }
+
+        private boolean nearModifiedGround(int x, int z, int distance) {
+            for (Cell cell : cells.values()) if (Math.hypot(x - cell.x(), z - cell.z()) < distance) return true;
+            return false;
+        }
+
+        private boolean separatedSpring(Position source) {
+            for (Spring spring : springs) {
+                if (Math.hypot(source.x() - spring.source().x(), source.z() - spring.source().z()) < 64
+                    || Math.abs(source.y() - spring.source().y()) < 12) return false;
+            }
+            return true;
+        }
+
+        private boolean springNiche(Position source, int dx, int dz) {
+            for (int y = source.y() - 3; y <= source.y() + 1; y++) {
+                if (!solid(source.x(), y, source.z())) return false;
+            }
+            for (int[] d : CARDINALS) {
+                if (d[0] == dx && d[1] == dz) continue;
+                if (!solid(source.x() + d[0], source.y(), source.z() + d[1])) return false;
+            }
+            for (int y = source.y(); y >= source.y() - 8; y--) {
+                if (solid(source.x() + dx, y, source.z() + dz)) return false;
+            }
+            return true;
+        }
+
+        /** Predict drainage through undecorated rock to select springs and inspection bounds.
+         * Descend through air first, then explore seven horizontal steps on a shelf. Later trees
+         * can divert the actual fluid: this prediction is not a bound on decorated-world physics.
+         * Integration tests trace actual water back to its source within the inspected chunk halo. */
+        private Flow traceSpring(Position source, Position outlet) {
+            Map<Position, Integer> reach = new HashMap<>();
+            Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<FlowNode> queue = new ArrayDeque<>();
+            reach.put(source, 7);
+            queue.add(new FlowNode(source, 7));
+            Position lowest = source;
+            while (!queue.isEmpty()) {
+                FlowNode node = queue.removeFirst();
+                Position at = node.position();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 24000) return null;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (!flowSolid(below, source)) {
+                    enqueueFlow(below, 7, at, queue, reach, parent);
+                    continue;
+                }
+                if (node.reach() <= 0) continue;
+                for (int[] d : CARDINALS) {
+                    Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+                    if (flowSolid(next, source)) continue;
+                    enqueueFlow(next, node.reach() - 1, at, queue, reach, parent);
+                }
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY;
+            int minZ = source.z(), maxZ = minZ;
+            for (Position position : reach.keySet()) {
+                minX = Math.min(minX, position.x()); maxX = Math.max(maxX, position.x());
+                minY = Math.min(minY, position.y()); maxY = Math.max(maxY, position.y());
+                minZ = Math.min(minZ, position.z()); maxZ = Math.max(maxZ, position.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Flow(Set.copyOf(reach.keySet()), path, new FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Position source) {
+            if (at.equals(source)) return false;
+            Cell cell = cells.get(key(at.x(), at.z()));
+            if (cell != null && at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            return solid(at.x(), at.y(), at.z());
+        }
+
+        private static void enqueueFlow(Position next, int available, Position from, ArrayDeque<FlowNode> queue,
+                                        Map<Position, Integer> reach, Map<Position, Position> parent) {
+            if (available <= reach.getOrDefault(next, -1)) return;
+            if (!reach.containsKey(next)) parent.put(next, from);
+            reach.put(next, available);
+            queue.addLast(new FlowNode(next, available));
+        }
+
+        private boolean nearWater(int x, int z, int distance) {
+            for (Feature feature : features) {
+                Point point = feature.path().getFirst();
+                if (Math.hypot(x - point.x(), z - point.z()) < distance) return true;
+            }
+            return false;
+        }
+
+        private boolean solid(int x, int y, int z) { samples++; return sampler.sample(x, y, z) > 0; }
+        private long featureId(int index) { return mix(seed ^ (0x51A7E7L + index * 0x9E3779B97F4A7C15L)); }
+
+        private double terrainNoise(int x, int z) { return field(x, z, 8, 31); }
+
+        private double field(int x, int z, int scale, long salt) {
+            int gx = Math.floorDiv(x, scale), gz = Math.floorDiv(z, scale);
+            double tx = smooth(Math.floorMod(x, scale) / (double) scale);
+            double tz = smooth(Math.floorMod(z, scale) / (double) scale);
+            double a = random(seed + salt, gx, gz) * (1 - tx) + random(seed + salt, gx + 1, gz) * tx;
+            double b = random(seed + salt, gx, gz + 1) * (1 - tx) + random(seed + salt, gx + 1, gz + 1) * tx;
+            return a * (1 - tz) + b * tz;
+        }
+    }
+
+    private static boolean inside(int x, int z, int radius) { return Math.hypot((double) x, z) < radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static Point point(long key) { return new Point((int) (key >> 32), (int) key); }
+    private static double smooth(double t) { return t * t * (3 - 2 * t); }
+    private static double random(long seed, int x, int z) { return (mix(seed ^ key(x, z)) >>> 11) * 0x1.0p-53; }
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/NaturalHydrologyRuntime.java

@@ -0,0 +1,140 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Map;
+import java.util.WeakHashMap;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+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.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+
+/** Alpha.5 only: immutable plans cached by world state, applied to fresh terrain before decoration. */
+public final class NaturalHydrologyRuntime {
+    private static final Map<RandomState, NaturalHydrology.Plan> PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+    private static final Map<RandomState, StarterLavaDeposit.Plan> LAVA_PLANS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+
+    private NaturalHydrologyRuntime() {}
+
+    public static boolean enabled(NoiseBasedChunkGenerator generator) {
+        return generator.generatorSettings().is(SanctuarySpawn.NATURAL_SETTINGS);
+    }
+
+    public static NaturalHydrology.Plan naturalPlan(ServerLevel level) {
+        return plan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static NaturalHydrology.Plan plan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        if (!enabled(generator)) throw new IllegalArgumentException("Natural hydrology is not enabled for this generator");
+        return PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var plan = NaturalHydrology.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z));
+            SanctuaryMod.LOGGER.info("Sanctuary natural hydrology: seed {}, {} features, {} columns, {} springs, {} ms",
+                state.seed(), plan.features().size(), plan.cells().size(), plan.springs().size(),
+                (System.nanoTime() - start) / 1_000_000);
+            return plan;
+        });
+    }
+
+    public static StarterLavaDeposit.Plan lavaPlan(ServerLevel level) {
+        return lavaPlan((NoiseBasedChunkGenerator) level.getChunkSource().getGenerator(),
+            level.getChunkSource().randomState());
+    }
+
+    public static StarterLavaDeposit.Plan lavaPlan(NoiseBasedChunkGenerator generator, RandomState randomState) {
+        // Acquire the water plan before the lava cache lock; the water planner never acquires it.
+        var water = plan(generator, randomState);
+        return LAVA_PLANS.computeIfAbsent(randomState, state -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var lava = StarterLavaDeposit.create(state.seed(),
+                (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z), water);
+            SanctuaryMod.LOGGER.info("Sanctuary starter lava: seed {}, {} sources, access {}, {} ms",
+                state.seed(), lava.lavaCells().size(), lava.access(), (System.nanoTime() - start) / 1_000_000);
+            return lava;
+        });
+    }
+
+    public static void apply(NoiseBasedChunkGenerator generator, RandomState randomState, ChunkAccess chunk) {
+        if (!enabled(generator)) return;
+        var chunkPos = chunk.getPos();
+        if (Math.abs((long) chunkPos.x() * 16) > IslandShape.TERRAIN_LIMIT + 16L
+                || Math.abs((long) chunkPos.z() * 16) > IslandShape.TERRAIN_LIMIT + 16L) return;
+        var plan = plan(generator, randomState);
+        var cells = plan.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var springs = plan.springsInChunk(chunkPos.x(), chunkPos.z());
+        var lava = lavaPlan(generator, randomState);
+        var lavaCells = lava.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var lavaSupports = lava.supportsInChunk(chunkPos.x(), chunkPos.z());
+        if (cells.isEmpty() && springs.isEmpty() && lavaCells.isEmpty() && lavaSupports.isEmpty()) return;
+        BlockPos.MutableBlockPos pos = new BlockPos.MutableBlockPos();
+        // Validate all replacements and two intact support layers before modifying this chunk.
+        for (var cell : cells) {
+            for (int y = cell.bedY() - cell.sedimentDepth() - 1; y <= cell.bedY(); y++) {
+                requireSolid(chunk, pos.set(cell.x(), y, cell.z()), randomState.seed());
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            requireSolid(chunk, pos.set(source.x(), source.y(), source.z()), randomState.seed());
+        }
+        for (var support : lavaSupports) {
+            requireSolid(chunk, pos.set(support.x(), support.y(), support.z()), randomState.seed());
+            if (chunk.getBlockState(pos).ignitedByLava()) {
+                throw new IllegalStateException("Lava pocket requires nonflammable natural support at " + pos);
+            }
+        }
+        for (var cell : lavaCells) {
+            requireSolid(chunk, pos.set(cell.x(), cell.y(), cell.z()), randomState.seed());
+        }
+        for (var cell : cells) {
+            for (int depth = 0; depth < cell.sedimentDepth(); depth++) {
+                pos.set(cell.x(), cell.bedY() - depth, cell.z());
+                BlockState material = switch (cell.material()) {
+                    case SAND -> Blocks.SAND.defaultBlockState();
+                    case GRAVEL -> Blocks.GRAVEL.defaultBlockState();
+                    case CLAY -> Blocks.CLAY.defaultBlockState();
+                    case STONE -> Blocks.STONE.defaultBlockState();
+                    case GRASS -> (depth == 0 ? Blocks.GRASS_BLOCK : Blocks.DIRT).defaultBlockState();
+                };
+                chunk.setBlockState(pos, material, 0);
+            }
+            for (int y = cell.bedY() + 1; y <= Math.max(cell.waterY(), cell.carveTop()); y++) {
+                pos.set(cell.x(), y, cell.z());
+                chunk.setBlockState(pos, cell.hasWater() && y <= cell.waterY()
+                    ? Blocks.WATER.defaultBlockState() : Blocks.AIR.defaultBlockState(), 0);
+                if (cell.hasWater() && y <= cell.waterY()) chunk.markPosForPostProcessing(pos);
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            pos.set(source.x(), source.y(), source.z());
+            chunk.setBlockState(pos, Blocks.WATER.defaultBlockState(), 0);
+            // Only the source is generated. Vanilla fluid ticks create the descending waterfall.
+            chunk.markPosForPostProcessing(pos);
+        }
+        for (var cell : lavaCells) {
+            pos.set(cell.x(), cell.y(), cell.z());
+            chunk.setBlockState(pos, (cell.lava() ? Blocks.LAVA : Blocks.AIR).defaultBlockState(), 0);
+            if (cell.lava()) chunk.markPosForPostProcessing(pos);
+        }
+        Heightmap.primeHeightmaps(chunk, EnumSet.of(Heightmap.Types.WORLD_SURFACE_WG,
+            Heightmap.Types.OCEAN_FLOOR_WG));
+    }
+
+    private static void requireSolid(ChunkAccess chunk, BlockPos pos, long seed) {
+        if (!chunk.getBlockState(pos).isCollisionShapeFullBlock(chunk, pos)) {
+            throw new IllegalStateException("Natural hydrology differs from terrain at " + pos + " for seed " + seed);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/NaturalShoreSugarCaneFeature.java

@@ -0,0 +1,41 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import net.minecraft.core.BlockPos;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.feature.Feature;
+
+/** A few plants on existing suitable shores, after the forest has been decorated. */
+public final class NaturalShoreSugarCaneFeature implements Feature {
+    public static final MapCodec<NaturalShoreSugarCaneFeature> CODEC = MapCodec.unit(NaturalShoreSugarCaneFeature::new);
+
+    @Override
+    public MapCodec<NaturalShoreSugarCaneFeature> codec() {
+        return CODEC;
+    }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource random, BlockPos origin) {
+        if (!(generator instanceof NoiseBasedChunkGenerator noise) || !NaturalHydrologyRuntime.enabled(noise)) return false;
+        var plan = NaturalHydrologyRuntime.plan(noise, level.getLevel().getChunkSource().randomState());
+        var cane = Blocks.SUGAR_CANE.defaultBlockState();
+        boolean placed = false;
+        for (var cell : plan.cellsInChunk(origin.getX() >> 4, origin.getZ() >> 4)) {
+            if (cell.hasWater() || random.nextInt(7) != 0) continue;
+            BlockPos base = new BlockPos(cell.x(), cell.bedY() + 1, cell.z());
+            if (!level.getBlockState(base).isAir() || !cane.canSurvive(level, base)) continue;
+            int height = 1 + random.nextInt(3);
+            for (int y = 0; y < height; y++) {
+                BlockPos pos = base.above(y);
+                if (!level.getBlockState(pos).isAir() || !cane.canSurvive(level, pos)) break;
+                setBlock(level, pos, cane);
+                placed = true;
+            }
+        }
+        return placed;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationBiomePalette.java

@@ -0,0 +1,34 @@
+package fr.koka.sanctuary.worldgen;
+
+/** Alpha.10 keeps the upper woodland climate and specializes sheltered lower layers. */
+public final class PopulationBiomePalette {
+    public enum Kind {
+        OAK_FOREST, BIRCH_FOREST, CLEARING, DRY_WOODLAND, ROCKY_HEATH,
+        DARK_GROVE, BAMBOO_GROVE, SULFUR_DEPTHS, LUSH_CAVES, DRIPSTONE_CAVES
+    }
+
+    private PopulationBiomePalette() {}
+
+    public static Kind select(int blockY, float variation, float moisture) {
+        double elevation = blockY - Math.clamp(variation, -1.0F, 1.0F) * 16
+            - Math.clamp(moisture, -1.0F, 1.0F) * 10;
+        // Small climate pockets replace alpha.8's broad sulfur province. Neither
+        // mineral pockets nor cave vegetation can take over the upper forest.
+        if (blockY < 176 && elevation < 168 && variation > 0.22F && variation < 0.42F
+                && moisture > -0.42F && moisture < -0.12F) return Kind.SULFUR_DEPTHS;
+        if (variation > 0.48F) return Kind.ROCKY_HEATH;
+        if (blockY < 184 && elevation < 180) {
+            if (moisture > 0.05F && variation > -0.32F) return Kind.LUSH_CAVES;
+            if (moisture < -0.18F && variation < 0.22F) return Kind.DRIPSTONE_CAVES;
+        }
+        if (elevation < 214) {
+            if (variation < -0.45F && moisture > 0.40F) return Kind.BAMBOO_GROVE;
+            double shelteredMoisture = moisture + Math.min(0.55, (214 - elevation) / 160);
+            if (shelteredMoisture > -0.08) return Kind.DARK_GROVE;
+        }
+        if (moisture < -0.55F && variation > -0.25F) return Kind.DRY_WOODLAND;
+        if (Math.abs(variation) < 0.09F && moisture < 0.35F) return Kind.CLEARING;
+        if (variation < -0.33F) return Kind.BIRCH_FOREST;
+        return Kind.OAK_FOREST;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationDecorationsFeature.java

@@ -0,0 +1,299 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.Direction;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.AmethystClusterBlock;
+import net.minecraft.world.level.block.CaveVines;
+import net.minecraft.world.level.block.GrowingPlantHeadBlock;
+import net.minecraft.world.level.block.PotentSulfurBlock;
+import net.minecraft.world.level.block.SpeleothemBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.block.state.properties.PotentSulfurState;
+import net.minecraft.world.level.block.state.properties.SpeleothemThickness;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.feature.Feature;
+import net.minecraft.world.level.levelgen.feature.GeodeFeature;
+
+/** Decorations in existing lower cavities only. All writes belong to the owner's chunk. */
+public final class PopulationDecorationsFeature implements Feature {
+    public static final MapCodec<PopulationDecorationsFeature> CODEC = MapCodec.unit(PopulationDecorationsFeature::new);
+    private static final ResourceKey<Feature> GEODE = ResourceKey.create(Registries.FEATURE, SanctuaryMod.id("population_amethyst_geode"));
+    private static final Direction[] SIDES = {Direction.NORTH, Direction.SOUTH, Direction.WEST, Direction.EAST};
+    public enum Kind { LUSH, DRIPSTONE, SULFUR, GEODE }
+    public record Candidate(Kind kind, BlockPos floor, BlockPos ceiling) {
+        public Candidate { floor = floor.immutable(); ceiling = ceiling.immutable(); }
+    }
+
+    @Override public MapCodec<PopulationDecorationsFeature> codec() { return CODEC; }
+
+    /** Pure, bounded probes for development diagnostics; no chunk loads or successful-placement promise. */
+    public static List<Candidate> candidates(NoiseBasedChunkGenerator generator, RandomState state, int chunkX, int chunkZ) {
+        if (!PopulationHydrologyRuntime.enabled(generator)
+                || !PopulationHydrologyRuntime.capacity(generator).areaExists(chunkX, chunkZ)) return List.of();
+        var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        var biomes = generator.getBiomeSource().createUncachedResolver(state);
+        List<Candidate> found = new ArrayList<>();
+        for (int[] offset : new int[][]{{4, 4}, {4, 12}, {12, 4}, {12, 12}, {8, 8}}) {
+            int x = chunkX * 16 + offset[0], z = chunkZ * 16 + offset[1], floors = 0;
+            for (int y = 182; y >= 40; y--) {
+                if (sampler.sample(x, y, z) <= 0 || sampler.sample(x, y + 1, z) > 0
+                        || sampler.sample(x, y + 2, z) > 0 || sampler.sample(x, y - 1, z) <= 0
+                        || sampler.sample(x, y - 2, z) <= 0) continue;
+                int roof = y + 3;
+                while (roof <= Math.min(230, y + 48) && sampler.sample(x, roof, z) <= 0) roof++;
+                if (roof > Math.min(230, y + 48) || roof - y < 6
+                        || sampler.sample(x, roof + 1, z) <= 0) continue;
+                BlockPos floor = new BlockPos(x, y, z), ceiling = new BlockPos(x, roof, z);
+                var biome = biomes.getNoiseBiome(x >> 2, (y + 1) >> 2, z >> 2);
+                if (biome.is(PopulationIslandBiomeSource.LUSH_CAVES)) found.add(new Candidate(Kind.LUSH, floor, ceiling));
+                else if (biome.is(PopulationIslandBiomeSource.DRIPSTONE_CAVES)) found.add(new Candidate(Kind.DRIPSTONE, floor, ceiling));
+                else if (biome.is(PopulationIslandBiomeSource.SULFUR_DEPTHS) && y < 176)
+                    found.add(new Candidate(Kind.SULFUR, floor, ceiling));
+                if (offset[0] == 8 && offset[1] == 8 && Math.floorMod(chunkSeed(state.seed(), chunkX, chunkZ, 0x9501L), 8) == 0)
+                    found.add(new Candidate(Kind.GEODE, floor, ceiling));
+                if (++floors >= 3) break;
+            }
+        }
+        // Geodes keep their entry free before this feature's moss, grass or pointed
+        // dripstone can occupy it. Stable sorting preserves every other candidate order.
+        found.sort(java.util.Comparator.comparingInt(candidate -> candidate.kind() == Kind.GEODE ? 0 : 1));
+        return List.copyOf(found);
+    }
+
+    @Override public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource ignored, BlockPos origin) {
+        var binding = PopulationGenerationContext.of(generator, level.getLevel());
+        if (binding == null) return false;
+        var noise = binding.generator();
+        var state = binding.random();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        int cx = origin.getX() >> 4, cz = origin.getZ() >> 4;
+        boolean changed = false, geyser = false, geode = false;
+        for (Candidate candidate : candidates(noise, state, cx, cz)) {
+            BlockPos floor = candidate.floor();
+            if (!stable(level, sampler, floor) || !level.getBlockState(floor.above()).isAir()) continue;
+            long seed = WoodlandGroveGeometry.seed(state.seed(), floor.getX(), floor.getY(), floor.getZ(), 0x9502L);
+            switch (candidate.kind()) {
+                case LUSH -> changed |= lush(level, noise, state, sampler, candidate, seed);
+                case DRIPSTONE -> changed |= dripstone(level, noise, state, sampler, candidate, seed);
+                case SULFUR -> {
+                    if (!geyser && Math.floorMod(chunkSeed(state.seed(), cx, cz, 0x9503L), 2) == 0)
+                        changed |= geyser = geyser(level, noise, state, sampler, candidate);
+                }
+                case GEODE -> { if (!geode) changed |= geode = geode(level, noise, state, sampler, candidate, seed); }
+            }
+        }
+        return changed;
+    }
+
+    private boolean lush(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                         WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos floor = site.floor(), roof = site.ceiling();
+        int gap = roof.getY() - floor.getY();
+        if (PopulationHydrologyRuntime.protects(noise, state, floor, 3, gap + 2, 3)) return false;
+        boolean changed = false;
+        for (int dx = -2; dx <= 2; dx++) for (int dz = -2; dz <= 2; dz++) {
+            if (dx * dx + dz * dz > 5) continue;
+            BlockPos p = floor.offset(dx, 0, dz);
+            if (!stable(level, sampler, p) || !stable(level, sampler, p.below()) || !stable(level, sampler, p.below(2))
+                    || !level.getBlockState(p.above()).isAir()) continue;
+            setBlock(level, p, Blocks.MOSS_BLOCK.defaultBlockState());
+            long local = WoodlandGroveGeometry.seed(seed, p.getX(), p.getY(), p.getZ(), 0x9504L);
+            BlockState plant = (Math.floorMod(local, 5) == 0 ? Blocks.AZALEA : Math.floorMod(local, 3) == 0
+                ? Blocks.MOSS_CARPET : Blocks.SHORT_GRASS).defaultBlockState();
+            if (plant.canSurvive(level, p.above())) setBlock(level, p.above(), plant);
+            changed = true;
+        }
+        // Real cave-vine heads and bodies remain harvestable and luminous via BERRIES.
+        int length = Math.min(gap - 3, 3 + Math.floorMod(seed, 6));
+        if (stable(level, sampler, roof) && stable(level, sampler, roof.above())) {
+            boolean free = true;
+            for (int d = 1; d <= length; d++) free &= level.getBlockState(roof.below(d)).isAir();
+            if (free) for (int d = 1; d <= length; d++) {
+                BlockPos p = roof.below(d);
+                BlockState vine = (d == length ? Blocks.CAVE_VINES : Blocks.CAVE_VINES_PLANT).defaultBlockState()
+                    .setValue(CaveVines.BERRIES, d == length || Math.floorMod(seed + d, 3) == 0);
+                if (d == length) vine = vine.setValue(GrowingPlantHeadBlock.AGE, 25);
+                if (!vine.canSurvive(level, p)) break;
+                setBlock(level, p, vine); changed = true;
+            }
+        }
+        return changed;
+    }
+
+    private boolean dripstone(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                              WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos floor = site.floor(), roof = site.ceiling();
+        int gap = roof.getY() - floor.getY();
+        if (PopulationHydrologyRuntime.protects(noise, state, floor, 1, gap + 2, 3)) return false;
+        int length = Math.min((gap - 3) / 2, 1 + Math.floorMod(seed, 4));
+        boolean changed = spike(level, sampler, floor, Direction.UP, length);
+        changed |= spike(level, sampler, roof, Direction.DOWN, length);
+        return changed;
+    }
+
+    private boolean spike(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, BlockPos support, Direction direction, int length) {
+        if (length < 1 || !stable(level, sampler, support) || !stable(level, sampler, support.relative(direction.getOpposite()))) return false;
+        for (int d = 1; d <= length; d++) {
+            BlockPos p = support.relative(direction, d);
+            if (!level.getBlockState(p).isAir() || sampler.sample(p.getX(), p.getY(), p.getZ()) > 0) return false;
+        }
+        setBlock(level, support, Blocks.DRIPSTONE_BLOCK.defaultBlockState());
+        for (int d = 1; d <= length; d++) {
+            SpeleothemThickness thickness = d == length ? SpeleothemThickness.TIP
+                : d == length - 1 ? SpeleothemThickness.FRUSTUM : d == 1 ? SpeleothemThickness.BASE : SpeleothemThickness.MIDDLE;
+            BlockState pointed = Blocks.POINTED_DRIPSTONE.defaultBlockState().setValue(SpeleothemBlock.TIP_DIRECTION, direction)
+                .setValue(SpeleothemBlock.THICKNESS, thickness);
+            setBlock(level, support.relative(direction, d), pointed);
+        }
+        return true;
+    }
+
+    private boolean geyser(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                           WoodlandGroveGeometry.Sampler sampler, Candidate site) {
+        BlockPos water = site.floor(), potent = water.below(), heat = water.below(2);
+        if (site.ceiling().getY() - water.getY() < 8
+                || PopulationHydrologyRuntime.protects(noise, state, water, 2, 8, 5)) return false;
+        for (int d = 0; d <= 4; d++) if (!stable(level, sampler, water.below(d))) return false;
+        for (Direction side : SIDES) for (int d = 0; d <= 2; d++)
+            if (!stable(level, sampler, water.below(d).relative(side))) return false;
+        for (int d = 1; d <= 7; d++) if (!level.getBlockState(water.above(d)).isAir()) return false;
+        // One source, four original rock walls, original deep support. Vanilla's
+        // periodic geyser ticker requires magma below potent sulfur and source water above.
+        setBlock(level, heat, Blocks.MAGMA_BLOCK.defaultBlockState());
+        setBlock(level, water, Blocks.WATER.defaultBlockState());
+        setBlock(level, potent, Blocks.POTENT_SULFUR.defaultBlockState().setValue(PotentSulfurBlock.STATE, PotentSulfurState.DORMANT));
+        level.getChunk(water).markPosForPostProcessing(water);
+        level.getChunk(potent).markPosForPostProcessing(potent);
+        return true;
+    }
+
+    private boolean geode(WorldGenLevel level, NoiseBasedChunkGenerator noise, RandomState state,
+                          WoodlandGroveGeometry.Sampler sampler, Candidate site, long seed) {
+        BlockPos origin = site.floor().offset(-1, -9, -1);
+        // Include the vanilla write range, its crystal neighbours and the entrance.
+        // This asymmetric envelope is centred explicitly so its positive edge is protected too.
+        if (origin.getY() - 6 < 24 || !level.getBlockState(site.floor().above(2)).isAir()
+                || PopulationHydrologyRuntime.protects(noise, state, origin.offset(1, -6, 1), 7, 17, 0)) return false;
+        Map<BlockPos, BlockState> before = new LinkedHashMap<>();
+        for (int dx = -6; dx <= 8; dx++) for (int dz = -6; dz <= 8; dz++) for (int dy = -6; dy <= 11; dy++) {
+            BlockPos p = origin.offset(dx, dy, dz);
+            BlockState original = level.getBlockState(p);
+            // No block-entity data or fluid scheduler state needs to be restored.
+            if (original.hasBlockEntity() || !original.getFluidState().isEmpty()) return false;
+            before.put(p, original);
+        }
+        Feature feature = level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(GEODE).value();
+        if (!(feature instanceof GeodeFeature geode) || geode.minGenOffset() != -5 || geode.maxGenOffset() != 7) return false;
+        boolean accepted = false;
+        try {
+            if (!geode.place(level, noise, RandomSource.create(seed), origin) || !naturalGeodeChanges(level, sampler, before)) return false;
+            var entrance = geodeEntrance(level, sampler, site.floor().above(), origin, before);
+            if (entrance.isEmpty()) return false;
+            for (BlockPos p : entrance) if (!level.getBlockState(p).isAir()) setBlock(level, p, Blocks.AIR.defaultBlockState());
+            if (!naturalGeodeChanges(level, sampler, before)) return false;
+            accepted = true;
+            return true;
+        } finally {
+            if (!accepted) before.forEach((p, original) -> {
+                if (!level.getBlockState(p).equals(original)) setBlock(level, p, original);
+            });
+        }
+    }
+
+    /** Test the actual vanilla mask, not unused bounding-box corners. A geode may
+     * excavate original rock but cannot fill original air or remove earlier decoration. */
+    private static boolean naturalGeodeChanges(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                               Map<BlockPos, BlockState> before) {
+        for (var entry : before.entrySet()) {
+            BlockPos p = entry.getKey();
+            BlockState original = entry.getValue(), current = level.getBlockState(p);
+            if (original.equals(current)) continue;
+            if (!carvableOriginal(level, sampler, p, original)) return false;
+        }
+        return true;
+    }
+
+    private static boolean carvableOriginal(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                            BlockPos p, BlockState original) {
+        return original != null && original.isCollisionShapeFullBlock(level, p)
+            && !original.hasBlockEntity() && original.getFluidState().isEmpty()
+            && !original.is(BlockTags.LOGS) && !original.is(BlockTags.LEAVES)
+            && !original.is(Blocks.BUDDING_AMETHYST) && !original.is(Blocks.MAGMA_BLOCK)
+            && sampler.sample(p.getX(), p.getY(), p.getZ()) > 0;
+    }
+
+    private static List<BlockPos> geodeEntrance(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                                BlockPos start, BlockPos origin, Map<BlockPos, BlockState> before) {
+        var previous = new java.util.HashMap<BlockPos, BlockPos>();
+        var distances = new java.util.HashMap<BlockPos, Integer>();
+        var queue = new java.util.ArrayDeque<BlockPos>();
+        queue.add(start); distances.put(start, 0);
+        BlockPos destination = null;
+        while (!queue.isEmpty()) {
+            BlockPos p = queue.removeFirst();
+            int distance = distances.get(p);
+            boolean adjacentBudding = false;
+            for (Direction direction : Direction.values())
+                adjacentBudding |= level.getBlockState(p.relative(direction)).is(Blocks.BUDDING_AMETHYST)
+                    || level.getBlockState(p.above().relative(direction)).is(Blocks.BUDDING_AMETHYST);
+            if (p.getY() <= start.getY() - 3 && level.getBlockState(p).isAir()
+                    && level.getBlockState(p.above()).isAir() && adjacentBudding) { destination = p; break; }
+            if (distance >= 16) continue;
+            for (Direction direction : Direction.values()) {
+                BlockPos next = p.relative(direction);
+                if (Math.abs(next.getX() - start.getX()) > 6 || Math.abs(next.getZ() - start.getZ()) > 6
+                        || next.getY() < origin.getY() - 5 || next.getY() > start.getY()
+                        || distances.containsKey(next) || !before.containsKey(next) || !before.containsKey(next.above())) continue;
+                if (!entranceBlock(level, sampler, next, before) || !entranceBlock(level, sampler, next.above(), before)) continue;
+                distances.put(next, distance + 1); previous.put(next, p); queue.addLast(next);
+            }
+        }
+        if (destination == null) return List.of();
+        var passage = new java.util.LinkedHashSet<BlockPos>();
+        for (BlockPos p = destination; p != null; p = previous.get(p)) { passage.add(p); passage.add(p.above()); }
+        return List.copyOf(passage);
+    }
+
+    private static boolean entranceBlock(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler,
+                                          BlockPos p, Map<BlockPos, BlockState> before) {
+        BlockState current = level.getBlockState(p);
+        if (current.isAir()) return true;
+        // Keep every budding block and attached crystal. Search around them instead.
+        if (current.is(Blocks.BUDDING_AMETHYST) || current.is(Blocks.AMETHYST_CLUSTER)
+                || current.is(Blocks.SMALL_AMETHYST_BUD) || current.is(Blocks.MEDIUM_AMETHYST_BUD)
+                || current.is(Blocks.LARGE_AMETHYST_BUD)) return false;
+        for (Direction direction : Direction.values()) {
+            BlockState neighbour = level.getBlockState(p.relative(direction));
+            if (neighbour.getBlock() instanceof AmethystClusterBlock
+                    && neighbour.getValue(AmethystClusterBlock.FACING) == direction) return false;
+        }
+        return carvableOriginal(level, sampler, p, before.get(p));
+    }
+
+    private static boolean stable(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, BlockPos p) {
+        BlockState state = level.getBlockState(p);
+        return sampler.sample(p.getX(), p.getY(), p.getZ()) > 0 && state.isCollisionShapeFullBlock(level, p)
+            && state.getFluidState().isEmpty() && !state.hasBlockEntity() && !state.is(BlockTags.LOGS)
+            && !state.is(BlockTags.LEAVES) && !state.is(Blocks.BUDDING_AMETHYST) && !state.is(Blocks.MAGMA_BLOCK);
+    }
+
+    private static long chunkSeed(long seed, int x, int z, long salt) {
+        return WoodlandGroveGeometry.seed(seed, x * 16, 0, z * 16, salt);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationGenerationContext.java

@@ -0,0 +1,22 @@
+package fr.koka.sanctuary.worldgen;
+
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+import org.jspecify.annotations.Nullable;
+
+/** Resolves the actual starter noise state; an expansion host's fallback state has no terrain. */
+public final class PopulationGenerationContext {
+    public record Binding(NoiseBasedChunkGenerator generator, RandomState random) {}
+    private PopulationGenerationContext() {}
+    public static @Nullable Binding of(ServerLevel level) {
+        return of(level.getChunkSource().getGenerator(), level);
+    }
+    public static @Nullable Binding of(ChunkGenerator generator, ServerLevel level) {
+        if (generator instanceof SanctuaryChunkGenerator unified) return unified.starterContext();
+        if (generator instanceof NoiseBasedChunkGenerator noise && PopulationHydrologyRuntime.enabled(noise))
+            return new Binding(noise, level.getChunkSource().randomState());
+        return null;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationGrovesFeature.java

@@ -0,0 +1,299 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.Map;
+import java.util.Optional;
+import java.util.WeakHashMap;
+import net.minecraft.core.BlockPos;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.data.worldgen.features.TreeFeatures;
+import net.minecraft.data.worldgen.features.VegetationFeatures;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.server.level.ServerLevel;
+import net.minecraft.tags.BlockTags;
+import net.minecraft.util.RandomSource;
+import net.minecraft.world.level.WorldGenLevel;
+import net.minecraft.world.level.block.Blocks;
+import net.minecraft.world.level.block.VegetationBlock;
+import net.minecraft.world.level.block.state.BlockState;
+import net.minecraft.world.level.chunk.ChunkGenerator;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.feature.Feature;
+import net.minecraft.world.level.levelgen.feature.AbstractHugeMushroomFeature;
+
+/** Alpha.10: sheltered vanilla mushroom trees and dark oak on natural lower floors,
+ * plus one globally selected remarkable tree.
+ * Placement runs only in new generation. No world journal or mutable placement counter is retained. */
+public final class PopulationGrovesFeature implements Feature {
+    public static final MapCodec<PopulationGrovesFeature> CODEC = MapCodec.unit(PopulationGrovesFeature::new);
+    private static final Map<RandomState, Optional<RemarkableTree>> REMARKABLE =
+        Collections.synchronizedMap(new WeakHashMap<>());
+
+    public record RemarkableTree(BlockPos base, String featureId, int radius, int height) {
+        public RemarkableTree { base = base.immutable(); }
+    }
+    private record Species(ResourceKey<Feature> key, int width, int radius, int height) {}
+    private record Candidate(int x, int z, long rank) {}
+    @FunctionalInterface
+    private interface Protection {
+        boolean intersects(BlockPos base, int radius, int height, int rootDepth);
+    }
+    private static final Species CHERRY = new Species(TreeFeatures.CHERRY, 1, 9, 15);
+    private static final Species[] SPECIES = {CHERRY, CHERRY, CHERRY, CHERRY,
+        new Species(TreeFeatures.SPRUCE, 1, 5, 15), new Species(TreeFeatures.JUNGLE_TREE_NO_VINE, 1, 5, 14),
+        new Species(TreeFeatures.ACACIA, 1, 7, 14), new Species(TreeFeatures.MANGROVE, 1, 10, 20),
+        new Species(TreeFeatures.PALE_OAK_BONEMEAL, 2, 6, 12)};
+
+    @Override public MapCodec<PopulationGrovesFeature> codec() { return CODEC; }
+
+    public static Optional<RemarkableTree> remarkablePlan(ServerLevel level) {
+        var binding = PopulationGenerationContext.of(level);
+        return binding == null ? Optional.empty() : remarkablePlan(binding.generator(), binding.random());
+    }
+
+    public static Optional<RemarkableTree> remarkablePlan(NoiseBasedChunkGenerator noise, RandomState state) {
+        if (!PopulationHydrologyRuntime.enabled(noise)) return Optional.empty();
+        return REMARKABLE.computeIfAbsent(state, ignored -> {
+            var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+            WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+            Protection protection = (base, radius, height, rootDepth) ->
+                PopulationHydrologyRuntime.protects(noise, state, base, radius, height, rootDepth);
+            Species species = SPECIES[Math.floorMod(WoodlandGroveGeometry.seed(state.seed(), 0, 0, 0, 0x70EEL), SPECIES.length)];
+            var candidates = new ArrayList<Candidate>();
+            // One global candidate stays in the starter centre; ordinary groves use the full capacity.
+            for (int x = -152; x <= 152; x += 16) for (int z = -152; z <= 152; z += 16) {
+                if (Math.hypot(x, z) <= 168) candidates.add(new Candidate(x, z,
+                    WoodlandGroveGeometry.seed(state.seed(), x, 0, z, 0x71AFL)));
+            }
+            candidates.sort(Comparator.comparingLong(Candidate::rank).thenComparingInt(Candidate::x).thenComparingInt(Candidate::z));
+            for (Candidate candidate : candidates) {
+                int bed = WoodlandGroveGeometry.highestSurface(sampler, candidate.x(), candidate.z());
+                if (!WoodlandGroveGeometry.naturalFootprint(sampler, candidate.x(), bed, candidate.z(), species.width())) continue;
+                BlockPos base = new BlockPos(candidate.x(), bed + 1, candidate.z());
+                if (blocked(protection, base, species.radius() + 1, species.height(), rootDepth(species))) continue;
+                if (!WoodlandGroveGeometry.treeRoom(sampler, base.getX(), base.getY(), base.getZ(),
+                    species.width(), species.radius(), species.height())) continue;
+                return Optional.of(new RemarkableTree(base, species.key().identifier().toString(), species.radius(), species.height()));
+            }
+            return Optional.empty();
+        });
+    }
+
+    @Override
+    public boolean place(WorldGenLevel level, ChunkGenerator generator, RandomSource ignored, BlockPos origin) {
+        var binding = PopulationGenerationContext.of(generator, level.getLevel());
+        if (binding == null) return false;
+        var noise = binding.generator();
+        int minX = (origin.getX() >> 4) * 16, minZ = (origin.getZ() >> 4) * 16;
+        if (!PopulationHydrologyRuntime.capacity(noise).areaExists(minX >> 4, minZ >> 4)) return false;
+        var state = binding.random();
+        var density = noise.generatorSettings().value().noiseRouter().finalDensity();
+        WoodlandGroveGeometry.Sampler sampler = (x, y, z) -> state.sampleBlockValueUncached(density, x, y, z);
+        Protection protection = (base, radius, height, rootDepth) ->
+            PopulationHydrologyRuntime.protects(noise, state, base, radius, height, rootDepth);
+        boolean changed = false;
+        int[] heights = new int[256];
+        Arrays.fill(heights, Integer.MIN_VALUE);
+        var remarkable = remarkablePlan(noise, state);
+        if (remarkable.isPresent()) {
+            var tree = remarkable.get();
+            BlockPos base = tree.base();
+            if ((base.getX() >> 4) == (minX >> 4) && (base.getZ() >> 4) == (minZ >> 4)) {
+                for (Species species : SPECIES) if (species.key().identifier().toString().equals(tree.featureId())) {
+                    changed |= tree(level, generator, sampler, state.seed(), base, species, protection, 0x723BL);
+                    break;
+                }
+            }
+        }
+        // The scarce tall rooms usually go to dark oak first; one quarter of chunks
+        // give mushroom trees first choice. This changes priority, never attempt budgets
+        // or natural fit requirements, and uses a separate deterministic chunk seed.
+        boolean mushroomsFirst = Math.floorMod(WoodlandGroveGeometry.seed(state.seed(), minX, 0, minZ, 0x8503L), 4) == 0;
+        if (mushroomsFirst) changed |= mushroomTrees(level, generator, sampler, state.seed(), protection, minX, minZ, heights);
+        // Four spaced origins per chunk; the 2x2 trunk and full canopy still have to fit the cave.
+        for (int x = minX + 4; x < minX + 16; x += 8) for (int z = minZ + 4; z < minZ + 16; z += 8) {
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights), placed = 0;
+            for (int bed = highest - 8; bed >= 40; bed--) {
+                BlockPos base = new BlockPos(x, bed + 1, z);
+                if (!ground(level, base.below()) || !level.getBlockState(base).isAir()) continue;
+                var biome = level.getBiome(base);
+                boolean dark = biome.is(PopulationIslandBiomeSource.DARK_GROVE);
+                boolean bamboo = biome.is(PopulationIslandBiomeSource.BAMBOO_GROVE);
+                if (!dark && !bamboo) continue;
+                long placementSeed = WoodlandGroveGeometry.seed(state.seed(), x, bed, z, 0x730DL);
+                if (dark) {
+                    if (tree(level, generator, sampler, state.seed(), base,
+                        new Species(TreeFeatures.DARK_OAK, 2, 6, 12), protection, 0x730DL)) { changed = true; placed++; }
+                } else if (Math.floorMod(placementSeed, 8) == 0) {
+                    if (tree(level, generator, sampler, state.seed(), base,
+                        new Species(TreeFeatures.JUNGLE_TREE_NO_VINE, 1, 5, 14), protection, 0x735BL)) { changed = true; placed++; }
+                } else if (Math.floorMod(placementSeed, 3) == 0
+                    && WoodlandGroveGeometry.naturalFootprint(sampler, x, bed, z, 1)
+                    && WoodlandGroveGeometry.treeRoom(sampler, x, bed + 1, z, 1, 3, 16)
+                    && !blocked(protection, base, 4, 17) && actualRoom(level, base, 1, 3, 16)) {
+                    setBlock(level, base.below(), Blocks.PODZOL.defaultBlockState());
+                    changed |= level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(VegetationFeatures.BAMBOO_NO_PODZOL)
+                        .value().place(level, generator, RandomSource.create(placementSeed), base);
+                    placed++;
+                }
+                if (placed >= 2) break;
+            }
+        }
+        if (!mushroomsFirst) changed |= mushroomTrees(level, generator, sampler, state.seed(), protection, minX, minZ, heights);
+        // Coherent ground patches: about 40% moss, 40% podzol, 20% mycelium.
+        // Small mushrooms are accents (one opportunity per hundred columns), not the canopy.
+        for (int x = minX; x < minX + 16; x++) for (int z = minZ; z < minZ + 16; z++) {
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights), floors = 0;
+            long detail = WoodlandGroveGeometry.seed(state.seed(), x, 0, z, 0x843EL);
+            boolean smallMushroomPlaced = false;
+            for (int bed = highest - 8; bed >= 32; bed--) {
+                BlockPos floor = new BlockPos(x, bed, z), plant = floor.above();
+                if (!ground(level, floor) || !level.getBlockState(plant).isAir()) continue;
+                var biome = level.getBiome(plant);
+                if (!biome.is(PopulationIslandBiomeSource.DARK_GROVE) && !biome.is(PopulationIslandBiomeSource.BAMBOO_GROVE)) continue;
+                if (!WoodlandGroveGeometry.naturalFootprint(sampler, x, bed, z, 1) || blocked(protection, plant, 1, 2)) continue;
+                long patch = WoodlandGroveGeometry.seed(state.seed(), Math.floorDiv(x, 7), 0, Math.floorDiv(z, 7), 0x742DL);
+                int soilKind = Math.floorMod(patch, 5);
+                BlockState soil = (soilKind < 2 ? Blocks.MOSS_BLOCK : soilKind < 4 ? Blocks.PODZOL : Blocks.MYCELIUM).defaultBlockState();
+                setBlock(level, floor, soil);
+                if (!smallMushroomPlaced && Math.floorMod(detail, 100) == 0) {
+                    BlockState mushroom = (Math.floorMod(detail >>> 8, 2) == 0 ? Blocks.BROWN_MUSHROOM : Blocks.RED_MUSHROOM).defaultBlockState();
+                    if (mushroom.canSurvive(level, plant)) {
+                        setBlock(level, plant, mushroom);
+                        smallMushroomPlaced = true;
+                    }
+                }
+                changed = true;
+                if (++floors >= 3) break;
+            }
+        }
+        return changed;
+    }
+
+    private boolean mushroomTrees(WorldGenLevel level, ChunkGenerator generator, WoodlandGroveGeometry.Sampler sampler,
+                                  long seed, Protection protection, int minX, int minZ, int[] heights) {
+        boolean changed = false;
+        RandomSource mushroomSites = RandomSource.create(WoodlandGroveGeometry.seed(seed, minX, 0, minZ, 0x8501L));
+        int mushroomAttempts = 1 + mushroomSites.nextInt(3);
+        for (int attempt = 0; attempt < mushroomAttempts; attempt++) {
+            int x = minX + 3 + mushroomSites.nextInt(10), z = minZ + 3 + mushroomSites.nextInt(10);
+            int highest = localTop(level, sampler, protection, minX, minZ, x, z, heights);
+            for (int bed = highest - 8; bed >= 32; bed--) {
+                BlockPos base = new BlockPos(x, bed + 1, z);
+                if (!ground(level, base.below()) || !level.getBlockState(base).isAir()
+                        || !level.getBiome(base).is(PopulationIslandBiomeSource.DARK_GROVE)) continue;
+                long mushroomSeed = WoodlandGroveGeometry.seed(seed, x, bed, z, 0x8502L + attempt);
+                var key = Math.floorMod(mushroomSeed, 2) == 0 ? TreeFeatures.HUGE_BROWN_MUSHROOM : TreeFeatures.HUGE_RED_MUSHROOM;
+                Feature feature = level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(key).value();
+                if (!(feature instanceof AbstractHugeMushroomFeature mushroom)) break;
+                int height = mushroom.getTreeHeight(RandomSource.create(mushroomSeed));
+                int radius = mushroom.foliageRadius();
+                if (!mushroomRoom(level, sampler, protection, base, radius, height)) continue;
+                BlockState originalFloor = level.getBlockState(base.below());
+                setBlock(level, base.below(), (Math.floorMod(mushroomSeed, 5) == 0 ? Blocks.MYCELIUM : Blocks.PODZOL).defaultBlockState());
+                // Vanilla consumes its height draw first. Replaying the same random seed
+                // gives precisely the height whose natural envelope was checked above.
+                boolean placed = mushroom.place(level, generator, RandomSource.create(mushroomSeed), base);
+                if (!placed) setBlock(level, base.below(), originalFloor);
+                changed |= placed;
+                break;
+            }
+        }
+        return changed;
+    }
+
+    private boolean tree(WorldGenLevel level, ChunkGenerator generator, WoodlandGroveGeometry.Sampler sampler, long seed,
+                         BlockPos base, Species species, Protection protection, long salt) {
+        if (blocked(protection, base, species.radius() + 1, species.height(), rootDepth(species))
+            || !WoodlandGroveGeometry.naturalFootprint(sampler, base.getX(), base.getY() - 1, base.getZ(), species.width())
+            || !actualRoom(level, base, species.width(), species.radius(), species.height())
+            || !WoodlandGroveGeometry.treeRoom(sampler, base.getX(), base.getY(), base.getZ(), species.width(), species.radius(), species.height())) return false;
+        for (int dx = 0; dx < species.width(); dx++) for (int dz = 0; dz < species.width(); dz++) {
+            BlockPos floor = base.offset(dx, -1, dz);
+            if (!ground(level, floor)) return false;
+        }
+        for (int dx = 0; dx < species.width(); dx++) for (int dz = 0; dz < species.width(); dz++) {
+            setBlock(level, base.offset(dx, -1, dz), Blocks.PODZOL.defaultBlockState());
+        }
+        return level.registryAccess().lookupOrThrow(Registries.FEATURE).getOrThrow(species.key()).value()
+            .place(level, generator, RandomSource.create(WoodlandGroveGeometry.seed(seed, base.getX(), base.getY(), base.getZ(), salt)), base);
+    }
+
+    private static boolean actualRoom(WorldGenLevel level, BlockPos base, int width, int radius, int height) {
+        for (int y = 0; y <= height; y++) {
+            int from = y < 3 ? 0 : -radius, to = y < 3 ? width - 1 : radius;
+            for (int dx = from; dx <= to; dx++) for (int dz = from; dz <= to; dz++) {
+                BlockState current = level.getBlockState(base.offset(dx, y, dz));
+                if (!current.getFluidState().isEmpty() || !(current.isAir() || current.is(BlockTags.LEAVES)
+                    || current.getBlock() instanceof VegetationBlock)) return false;
+            }
+        }
+        return true;
+    }
+
+    private static boolean ground(WorldGenLevel level, BlockPos floor) {
+        BlockState state = level.getBlockState(floor);
+        if (state.is(Blocks.DEEPSLATE)) {
+            // Deep humid ledges can support organic soil. Check every tree foot rather
+            // than admitting this rock globally, including for the remarkable tree.
+            var biome = level.getBiome(floor.above());
+            return biome.is(PopulationIslandBiomeSource.DARK_GROVE) || biome.is(PopulationIslandBiomeSource.BAMBOO_GROVE);
+        }
+        return state.is(Blocks.STONE) || state.is(Blocks.DIRT) || state.is(Blocks.GRASS_BLOCK) || state.is(Blocks.PODZOL)
+            || state.is(Blocks.MYCELIUM) || state.is(Blocks.ROOTED_DIRT) || state.is(Blocks.COARSE_DIRT)
+            || state.is(Blocks.GRANITE) || state.is(Blocks.DIORITE) || state.is(Blocks.ANDESITE) || state.is(Blocks.TUFF)
+            || state.is(Blocks.COBBLESTONE) || state.is(Blocks.MOSSY_COBBLESTONE) || state.is(Blocks.PACKED_MUD);
+    }
+
+    private static int localTop(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, Protection protection,
+                                int minX, int minZ, int x, int z, int[] heights) {
+        int index = (x - minX) * 16 + z - minZ;
+        if (heights[index] != Integer.MIN_VALUE) return heights[index];
+        // In an untouched column the heightmap bounds the original surface cheaply.
+        // A protected water/lava column may have been carved: recover its raw top
+        // without depending on the current hydrology plan's representation.
+        int ceiling = level.getHeight(Heightmap.Types.WORLD_SURFACE_WG, x, z) - 1;
+        if (protection.intersects(new BlockPos(x, level.getMinY(), z), 0, level.getHeight() - 1, 0))
+            ceiling = level.getMaxY();
+        return heights[index] = WoodlandGroveGeometry.highestSurfaceBelow(sampler, x, z, ceiling);
+    }
+
+    private static boolean mushroomRoom(WorldGenLevel level, WoodlandGroveGeometry.Sampler sampler, Protection protection,
+                                        BlockPos base, int radius, int height) {
+        if (blocked(protection, base, radius + 1, height + 1, 4)
+                || !WoodlandGroveGeometry.naturalFootprint(sampler, base.getX(), base.getY() - 1, base.getZ(), 1)) return false;
+        for (int depth = 1; depth <= 3; depth++) {
+            BlockPos floor = base.below(depth);
+            if (!level.getBlockState(floor).isCollisionShapeFullBlock(level, floor)) return false;
+        }
+        // A complete conservative column around the cap handles both brown umbrellas
+        // and the lower rounded red cap. Neither natural rock nor existing logs move.
+        for (int y = 0; y <= height + 1; y++) for (int dx = -radius; dx <= radius; dx++) for (int dz = -radius; dz <= radius; dz++) {
+            BlockPos p = base.offset(dx, y, dz);
+            BlockState current = level.getBlockState(p);
+            if (sampler.sample(p.getX(), p.getY(), p.getZ()) > 0 || !current.getFluidState().isEmpty()
+                    || !(current.isAir() || current.is(BlockTags.LEAVES))) return false;
+        }
+        // Being below another surface is not enough: the same column needs an actual
+        // original rock ceiling above the whole mushroom, not an open hillside.
+        for (int y = base.getY() + height + 2; y <= level.getMaxY(); y++)
+            if (sampler.sample(base.getX(), y, base.getZ()) > 0) return true;
+        return false;
+    }
+
+    private static int rootDepth(Species species) { return species.key().equals(TreeFeatures.MANGROVE) ? 16 : 4; }
+
+    private static boolean blocked(Protection protection, BlockPos base, int radius, int height) {
+        return blocked(protection, base, radius, height, 4);
+    }
+
+    private static boolean blocked(Protection protection, BlockPos base, int radius, int height, int rootDepth) {
+        return protection.intersects(base, radius, height, rootDepth);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationHydrologyRuntime.java

@@ -0,0 +1,240 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.*;
+import net.minecraft.core.BlockPos;
+import net.minecraft.server.level.ServerLevel;
+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.levelgen.Heightmap;
+import net.minecraft.world.level.levelgen.NoiseBasedChunkGenerator;
+import net.minecraft.world.level.levelgen.RandomState;
+import net.minecraft.world.level.levelgen.densityfunction.SamplerContext;
+
+/** Alpha.10 plans only regions touched by generation or a requested protection volume. */
+public final class PopulationHydrologyRuntime {
+    public record RegionPlan(IslandCapacity.Region region, PopulationHydrology.Plan water, PopulationLavaDeposit.Plan lava) {}
+    private static final Map<RandomState, PopulationPlanCache<IslandCapacity.Region, RegionPlan>> WORLDS =
+        Collections.synchronizedMap(new WeakHashMap<>());
+    private PopulationHydrologyRuntime() {}
+    public static boolean enabled(NoiseBasedChunkGenerator generator) { return IslandCapacity.forGenerator(generator) != null; }
+    public static IslandCapacity capacity(NoiseBasedChunkGenerator generator) {
+        return Objects.requireNonNull(IslandCapacity.forGenerator(generator), "Population generation is not enabled");
+    }
+    private static PopulationPlanCache<IslandCapacity.Region, RegionPlan> regions(RandomState state) {
+        synchronized (WORLDS) { return WORLDS.computeIfAbsent(state, ignored -> new PopulationPlanCache<>()); }
+    }
+    public static int cachedRegionCount(RandomState state) {
+        PopulationPlanCache<IslandCapacity.Region, RegionPlan> regions;
+        synchronized (WORLDS) { regions = WORLDS.get(state); }
+        if (regions == null) return 0;
+        return regions.size();
+    }
+    public static RegionPlan regionPlan(NoiseBasedChunkGenerator generator, RandomState state, IslandCapacity.Region region) {
+        var capacity = capacity(generator);
+        var regions = regions(state);
+        // Only cache misses wait for the bounded planner. Completed regions stay readable
+        // while another region is being computed; no neighbouring plan is built recursively.
+        return regions.getOrCreate(region, () -> {
+            long start = System.nanoTime();
+            var density = generator.generatorSettings().value().noiseRouter().finalDensity();
+            var sampler = state.getSampler(density);
+            var memo = new SignMemo((x, y, z) -> {
+                long wx = (long) x + region.originX(), wz = (long) z + region.originZ();
+                if (Math.hypot((double) wx, wz) >= capacity.terrainLimit()) return -1;
+                return sampler.sampleValue(SamplerContext.EMPTY_UNCACHED, (int) wx, y, (int) wz);
+            });
+            long seed = PopulationIslandDensity.regionSeed(state.seed(), region);
+            var water = PopulationHydrology.create(seed, memo).admitted();
+            var lava = PopulationLavaDeposit.create(seed, memo, water).admitted();
+            var result = new RegionPlan(region, water.translated(region.originX(), region.originZ()),
+                lava.translated(region.originX(), region.originZ()));
+            SanctuaryMod.LOGGER.info("Population {} seed {} region {},{}: {} features, {} water columns, {} lava sources, {} density probes, {} ms",
+                capacity.players(), state.seed(), region.x(), region.z(), water.features().size(), water.cells().size(),
+                lava.lavaCells().size(), memo.samples, (System.nanoTime() - start) / 1_000_000);
+            return result;
+        });
+    }
+    public static RegionPlan regionPlan(ServerLevel level, IslandCapacity.Region region) {
+        var binding = Objects.requireNonNull(PopulationGenerationContext.of(level), "Population world required");
+        return regionPlan(binding.generator(), binding.random(), region);
+    }
+    public static List<RegionPlan> plansIntersecting(NoiseBasedChunkGenerator generator, RandomState state,
+                                                    int minX, int minZ, int maxX, int maxZ) {
+        var capacity = capacity(generator);
+        var first = capacity.regionAt(minX, minZ); var last = capacity.regionAt(maxX, maxZ);
+        List<RegionPlan> plans = new ArrayList<>();
+        for (int x = first.x(); x <= last.x(); x++) for (int z = first.z(); z <= last.z(); z++) {
+            var region = new IslandCapacity.Region(x, z);
+            double nearestX = Math.max(0, Math.max(region.minX(), -region.maxX()));
+            double nearestZ = Math.max(0, Math.max(region.minZ(), -region.maxZ()));
+            if (Math.hypot(nearestX, nearestZ) < capacity.terrainLimit()) plans.add(regionPlan(generator, state, region));
+        }
+        return List.copyOf(plans);
+    }
+    public static List<PopulationHydrology.Cell> cellsInChunk(NoiseBasedChunkGenerator generator, RandomState state, int cx, int cz) {
+        if (!capacity(generator).areaExists(cx, cz)) return List.of();
+        return regionPlan(generator, state, capacity(generator).regionAt(cx * 16, cz * 16)).water().cellsInChunk(cx, cz);
+    }
+    public static List<PopulationHydrology.Cell> cellsAt(NoiseBasedChunkGenerator generator, RandomState state, int x, int z) {
+        if (Math.hypot((double) x, z) >= capacity(generator).terrainLimit()) return List.of();
+        return regionPlan(generator, state, capacity(generator).regionAt(x, z)).water().cellsAt(x, z);
+    }
+    public static PopulationHydrology.Cell cellAt(NoiseBasedChunkGenerator generator, RandomState state, int x, int y, int z) {
+        for (var cell : cellsAt(generator, state, x, z)) if (y >= cell.bedY() - cell.sedimentDepth() - 1
+                && y <= Math.max(cell.waterY(), cell.carveTop())) return cell;
+        return null;
+    }
+    /** Only the sign is observed by all local planners. The two bit masks are populated lazily
+     * and released after one region; there is no dense whole-island height-volume scan. */
+    private static final class SignMemo implements PopulationHydrology.Sampler {
+        final PopulationHydrology.Sampler original;
+        final Map<Long, long[]> columns = new HashMap<>();
+        long samples;
+        SignMemo(PopulationHydrology.Sampler original) { this.original = original; }
+        @Override public float sample(int x, int y, int z) {
+            if (y < 0 || y >= 384) return -1;
+            long key = ((long) x << 32) | (z & 0xffffffffL);
+            long[] bits = columns.computeIfAbsent(key, ignored -> new long[12]);
+            int word = y >>> 6; long mask = 1L << (y & 63);
+            if ((bits[word] & mask) == 0) {
+                samples++;
+                if (original.sample(x, y, z) > 0) bits[word + 6] |= mask;
+                bits[word] |= mask;
+            }
+            return (bits[word + 6] & mask) != 0 ? 1 : -1;
+        }
+    }
+
+    public static void apply(NoiseBasedChunkGenerator generator, RandomState randomState, ChunkAccess chunk) {
+        if (!enabled(generator)) return;
+        var chunkPos = chunk.getPos();
+        if (!capacity(generator).areaExists(chunkPos.x(), chunkPos.z())) return;
+        var region = regionPlan(generator, randomState, capacity(generator).regionAt(chunkPos.getMinBlockX(), chunkPos.getMinBlockZ()));
+        var plan = region.water();
+        var cells = plan.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var springs = plan.springsInChunk(chunkPos.x(), chunkPos.z());
+        var outlets = new java.util.ArrayList<>(plan.springs().stream().map(PopulationHydrology.Spring::outlet)
+            .filter(outlet -> (outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z()).toList());
+        for (var spill : plan.spills()) {
+            var outlet = spill.outlet();
+            if ((outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z()) outlets.add(outlet);
+        }
+        var lava = region.lava();
+        for (var fall : lava.falls()) {
+            var outlet = fall.outlet();
+            if ((outlet.x() >> 4) == chunkPos.x() && (outlet.z() >> 4) == chunkPos.z())
+                outlets.add(new PopulationHydrology.Position(outlet.x(), outlet.y(), outlet.z()));
+        }
+        var lavaCells = lava.cellsInChunk(chunkPos.x(), chunkPos.z());
+        var lavaSupports = lava.supportsInChunk(chunkPos.x(), chunkPos.z());
+        if (cells.isEmpty() && springs.isEmpty() && outlets.isEmpty() && lavaCells.isEmpty() && lavaSupports.isEmpty()) return;
+        BlockPos.MutableBlockPos pos = new BlockPos.MutableBlockPos();
+        // Validate all replacements and two intact support layers before modifying this chunk.
+        for (var cell : cells) {
+            for (int y = cell.bedY() - cell.sedimentDepth() - 1; y <= cell.bedY(); y++) {
+                requireSolid(chunk, pos.set(cell.x(), y, cell.z()), randomState.seed());
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            requireSolid(chunk, pos.set(source.x(), source.y(), source.z()), randomState.seed());
+        }
+        for (var support : lavaSupports) {
+            requireSolid(chunk, pos.set(support.x(), support.y(), support.z()), randomState.seed());
+            if (chunk.getBlockState(pos).ignitedByLava()) {
+                throw new IllegalStateException("Lava pocket requires nonflammable natural support at " + pos);
+            }
+        }
+        for (var cell : lavaCells) {
+            requireSolid(chunk, pos.set(cell.x(), cell.y(), cell.z()), randomState.seed());
+        }
+        for (var cell : cells) {
+            for (int depth = 0; depth < cell.sedimentDepth(); depth++) {
+                pos.set(cell.x(), cell.bedY() - depth, cell.z());
+                BlockState material = PopulationMaterials.sedimentBlock(cell, randomState.seed(), depth);
+                chunk.setBlockState(pos, material, 0);
+            }
+            for (int y = cell.bedY() + 1; y <= Math.max(cell.waterY(), cell.carveTop()); y++) {
+                pos.set(cell.x(), y, cell.z());
+                chunk.setBlockState(pos, cell.hasWater() && y <= cell.waterY()
+                    ? Blocks.WATER.defaultBlockState() : Blocks.AIR.defaultBlockState(), 0);
+                if (cell.hasWater() && y <= cell.waterY()) chunk.markPosForPostProcessing(pos);
+            }
+        }
+        for (var spring : springs) {
+            var source = spring.source();
+            pos.set(source.x(), source.y(), source.z());
+            chunk.setBlockState(pos, Blocks.WATER.defaultBlockState(), 0);
+            // Only the source is generated. Vanilla fluid ticks create the descending waterfall.
+            chunk.markPosForPostProcessing(pos);
+        }
+        for (var cell : lavaCells) {
+            pos.set(cell.x(), cell.y(), cell.z());
+            chunk.setBlockState(pos, (cell.lava() ? Blocks.LAVA : Blocks.AIR).defaultBlockState(), 0);
+            if (cell.lava()) chunk.markPosForPostProcessing(pos);
+        }
+        // This existing vanilla queue is consumed after neighbouring chunks finish decoration.
+        // Mark the outlet in its own chunk, including when its source belongs to a neighbour.
+        for (var outlet : outlets) {
+            pos.set(outlet.x(), outlet.y(), outlet.z());
+            chunk.markPosForPostProcessing(pos);
+        }
+        Heightmap.primeHeightmaps(chunk, EnumSet.of(Heightmap.Types.WORLD_SURFACE_WG,
+            Heightmap.Types.OCEAN_FLOOR_WG));
+    }
+
+    /** Reserve water, sediment and hot-rock volumes before placing vegetation. */
+    public static boolean protects(NoiseBasedChunkGenerator generator, RandomState randomState, BlockPos base,
+                                   int radius, int height, int rootDepth) {
+        for (RegionPlan region : plansIntersecting(generator, randomState, base.getX() - radius, base.getZ() - radius,
+                base.getX() + radius, base.getZ() + radius)) {
+            if (protects(region, base, radius, height, rootDepth)) return true;
+        }
+        return false;
+    }
+
+    private static boolean protects(RegionPlan region, BlockPos base, int radius, int height, int rootDepth) {
+        var water = region.water();
+        var lava = region.lava();
+        int low = base.getY() - rootDepth, high = base.getY() + height;
+        for (int x = base.getX() - radius; x <= base.getX() + radius; x++) {
+            for (int z = base.getZ() - radius; z <= base.getZ() + radius; z++) {
+                for (var cell : water.cellsAt(x, z))
+                    if (low <= cell.carveTop() && high >= cell.bedY() - cell.sedimentDepth() - 1) return true;
+            }
+        }
+        for (var spring : water.springs()) {
+            var bounds = spring.flowBounds();
+            if (base.getX() + radius >= bounds.minX() - 2 && base.getX() - radius <= bounds.maxX() + 2
+                && base.getZ() + radius >= bounds.minZ() - 2 && base.getZ() - radius <= bounds.maxZ() + 2
+                && low <= bounds.maxY() + 2 && high >= bounds.minY() - 2) return true;
+            var source = spring.source();
+            if (Math.abs(base.getX() - source.x()) <= radius + 3 && Math.abs(base.getZ() - source.z()) <= radius + 3
+                && low <= source.y() + 3 && high >= source.y() - 3) return true;
+        }
+        for (var bounds : lava.flowBounds()) {
+            if (base.getX() + radius >= bounds.minX() - 8 && base.getX() - radius <= bounds.maxX() + 8
+                && base.getZ() + radius >= bounds.minZ() - 8 && base.getZ() - radius <= bounds.maxZ() + 8
+                && low <= bounds.maxY() + 8 && high >= bounds.minY() - 8) return true;
+        }
+        for (var spill : water.spills()) {
+            var bounds = spill.flowBounds();
+            if (base.getX() + radius >= bounds.minX() - 3 && base.getX() - radius <= bounds.maxX() + 3
+                && base.getZ() + radius >= bounds.minZ() - 3 && base.getZ() - radius <= bounds.maxZ() + 3
+                && low <= bounds.maxY() + 3 && high >= bounds.minY() - 3) return true;
+        }
+        for (var cell : lava.cells()) if (Math.abs(base.getX() - cell.x()) <= radius + 2 && Math.abs(base.getZ() - cell.z()) <= radius + 2
+            && low <= cell.y() + 2 && high >= cell.y() - 2) return true;
+        for (var support : lava.supports()) if (Math.abs(base.getX() - support.x()) <= radius + 2 && Math.abs(base.getZ() - support.z()) <= radius + 2
+            && low <= support.y() + 2 && high >= support.y() - 2) return true;
+        return false;
+    }
+
+    private static void requireSolid(ChunkAccess chunk, BlockPos pos, long seed) {
+        if (!chunk.getBlockState(pos).isCollisionShapeFullBlock(chunk, pos)) {
+            throw new IllegalStateException("Population hydrology differs from terrain at " + pos + " for seed " + seed);
+        }
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationIslandBiomeSource.java

@@ -0,0 +1,99 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.stream.Stream;
+import net.minecraft.core.Holder;
+import net.minecraft.core.registries.Registries;
+import net.minecraft.resources.ResourceKey;
+import net.minecraft.world.level.biome.Biome;
+import net.minecraft.world.level.biome.BiomeResolver;
+import net.minecraft.world.level.biome.BiomeSource;
+import net.minecraft.world.level.biome.Climate;
+
+/** Seeded alpha.10 rift climate, separate from all saved earlier biome-source codecs. */
+public final class PopulationIslandBiomeSource extends BiomeSource {
+    public static final ResourceKey<Biome> OAK_FOREST = key("population_oak_forest");
+    public static final ResourceKey<Biome> BIRCH_FOREST = key("population_birch_forest");
+    public static final ResourceKey<Biome> CLEARING = key("population_clearing");
+    public static final ResourceKey<Biome> DRY_WOODLAND = key("population_dry_woodland");
+    public static final ResourceKey<Biome> ROCKY_HEATH = key("population_rocky_heath");
+    public static final ResourceKey<Biome> DARK_GROVE = key("population_dark_grove");
+    public static final ResourceKey<Biome> BAMBOO_GROVE = key("population_bamboo_grove");
+    public static final ResourceKey<Biome> SULFUR_DEPTHS = key("population_sulfur_depths");
+    public static final ResourceKey<Biome> LUSH_CAVES = key("population_lush_caves");
+    public static final ResourceKey<Biome> DRIPSTONE_CAVES = key("population_dripstone_caves");
+
+    public static final MapCodec<PopulationIslandBiomeSource> CODEC = RecordCodecBuilder.mapCodec(instance -> instance.group(
+        Biome.CODEC.fieldOf("oak_forest").forGetter(source -> source.oakForest),
+        Biome.CODEC.fieldOf("birch_forest").forGetter(source -> source.birchForest),
+        Biome.CODEC.fieldOf("clearing").forGetter(source -> source.clearing),
+        Biome.CODEC.fieldOf("dry_woodland").forGetter(source -> source.dryWoodland),
+        Biome.CODEC.fieldOf("rocky_heath").forGetter(source -> source.rockyHeath),
+        Biome.CODEC.fieldOf("dark_grove").forGetter(source -> source.darkGrove),
+        Biome.CODEC.fieldOf("bamboo_grove").forGetter(source -> source.bambooGrove),
+        Biome.CODEC.fieldOf("sulfur_depths").forGetter(source -> source.sulfurDepths),
+        Biome.CODEC.fieldOf("lush_caves").forGetter(source -> source.lushCaves),
+        Biome.CODEC.fieldOf("dripstone_caves").forGetter(source -> source.dripstoneCaves)
+    ).apply(instance, PopulationIslandBiomeSource::new));
+
+    private final Holder<Biome> oakForest;
+    private final Holder<Biome> birchForest;
+    private final Holder<Biome> clearing;
+    private final Holder<Biome> dryWoodland;
+    private final Holder<Biome> rockyHeath;
+    private final Holder<Biome> darkGrove;
+    private final Holder<Biome> bambooGrove;
+    private final Holder<Biome> sulfurDepths;
+    private final Holder<Biome> lushCaves;
+    private final Holder<Biome> dripstoneCaves;
+
+    public PopulationIslandBiomeSource(Holder<Biome> oakForest, Holder<Biome> birchForest, Holder<Biome> clearing,
+            Holder<Biome> dryWoodland, Holder<Biome> rockyHeath, Holder<Biome> darkGrove,
+            Holder<Biome> bambooGrove, Holder<Biome> sulfurDepths, Holder<Biome> lushCaves, Holder<Biome> dripstoneCaves) {
+        this.oakForest = oakForest;
+        this.birchForest = birchForest;
+        this.clearing = clearing;
+        this.dryWoodland = dryWoodland;
+        this.rockyHeath = rockyHeath;
+        this.darkGrove = darkGrove;
+        this.bambooGrove = bambooGrove;
+        this.sulfurDepths = sulfurDepths;
+        this.lushCaves = lushCaves;
+        this.dripstoneCaves = dripstoneCaves;
+    }
+
+    @Override
+    protected MapCodec<PopulationIslandBiomeSource> codec() { return CODEC; }
+
+    @Override
+    protected Stream<Holder<Biome>> collectPossibleBiomes() {
+        return Stream.of(oakForest, birchForest, clearing, dryWoodland, rockyHeath, darkGrove, bambooGrove, sulfurDepths, lushCaves, dripstoneCaves);
+    }
+
+    @Override
+    public BiomeResolver createResolver(Climate.Sampler sampler) {
+        return (quartX, quartY, quartZ) -> {
+            int x = quartX * 4, y = quartY * 4, z = quartZ * 4;
+            float variation = sampler.temperature().sampleValue(x, 0, z);
+            float moisture = sampler.humidity().sampleValue(x, 0, z);
+            return switch (PopulationBiomePalette.select(y, variation, moisture)) {
+                case OAK_FOREST -> oakForest;
+                case BIRCH_FOREST -> birchForest;
+                case CLEARING -> clearing;
+                case DRY_WOODLAND -> dryWoodland;
+                case ROCKY_HEATH -> rockyHeath;
+                case DARK_GROVE -> darkGrove;
+                case BAMBOO_GROVE -> bambooGrove;
+                case SULFUR_DEPTHS -> sulfurDepths;
+                case LUSH_CAVES -> lushCaves;
+                case DRIPSTONE_CAVES -> dripstoneCaves;
+            };
+        };
+    }
+
+    private static ResourceKey<Biome> key(String path) {
+        return ResourceKey.create(Registries.BIOME, SanctuaryMod.id(path));
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationIslandDensity.java

@@ -0,0 +1,65 @@
+package fr.koka.sanctuary.worldgen;
+
+import com.mojang.serialization.MapCodec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+import fr.koka.sanctuary.SanctuaryMod;
+import java.util.concurrent.ConcurrentHashMap;
+import net.minecraft.util.Interval;
+import net.minecraft.world.level.levelgen.densityfunction.*;
+
+/** Capacity changes the envelope; all natural noise is still sampled at world coordinates. */
+public record PopulationIslandDensity(DensityFunction terrain, DensityFunction distortion,
+        DensityFunction sculpt, DensityFunction detail, DensityFunction underside,
+        DensityFunction riftWarp, DensityFunction riftDetail, IslandCapacity capacity) implements DensityFunction {
+    public static final MapCodec<PopulationIslandDensity> CODEC = RecordCodecBuilder.mapCodec(instance -> instance.group(
+        DensityFunction.CODEC.fieldOf("terrain").forGetter(PopulationIslandDensity::terrain),
+        DensityFunction.CODEC.fieldOf("distortion").forGetter(PopulationIslandDensity::distortion),
+        DensityFunction.CODEC.fieldOf("sculpt").forGetter(PopulationIslandDensity::sculpt),
+        DensityFunction.CODEC.fieldOf("detail").forGetter(PopulationIslandDensity::detail),
+        DensityFunction.CODEC.fieldOf("underside").forGetter(PopulationIslandDensity::underside),
+        DensityFunction.CODEC.fieldOf("rift_warp").forGetter(PopulationIslandDensity::riftWarp),
+        DensityFunction.CODEC.fieldOf("rift_detail").forGetter(PopulationIslandDensity::riftDetail),
+        IslandCapacity.CODEC.optionalFieldOf("players", IslandCapacity.TWENTY).forGetter(PopulationIslandDensity::capacity)
+    ).apply(instance, PopulationIslandDensity::new));
+
+    @Override public DensitySampler compileSampler(CompileContext context) {
+        var raw = ExactInterpolationSampler.compileTerrain(terrain, context); var edge = distortion.compileSampler(context);
+        var coarse = sculpt.compileSampler(context); var fine = detail.compileSampler(context);
+        var bottom = underside.compileSampler(context); var warp = riftWarp.compileSampler(context);
+        var fractureDetail = riftDetail.compileSampler(context);
+        long seed = context.createRandom(SanctuaryMod.id("population_rifts_alpha10")).nextLong();
+        var layouts = new ConcurrentHashMap<IslandCapacity.Region, RiftShape.Layout>();
+        return new DensitySampler() {
+            @Override public float sampleValue(SamplerContext sample, int x, int y, int z) {
+                if (Math.hypot((double) x, z) >= capacity.terrainLimit() || y <= 0 || y >= 384) return -1;
+                int localY = y - 64;
+                float natural = PopulationIslandShape.raisedDensity(x, y, z, raw.sampleValue(sample, x, localY, z),
+                    edge.sampleValue(sample, x, 0, z), coarse.sampleValue(sample, x, localY, z),
+                    fine.sampleValue(sample, x, localY, z), bottom.sampleValue(sample, x, localY, z), 64, 384, capacity);
+                if (natural <= 0) return natural;
+                var region = capacity.regionAt(x, z);
+                var layout = layouts.computeIfAbsent(region, r -> RiftShape.layout(regionSeed(seed, r)));
+                int rx = x - region.originX(), rz = z - region.originZ();
+                if (!RiftShape.mayAffect(layout, rx, rz)) return natural;
+                return RiftShape.density(layout, rx, y, rz, natural,
+                    warp.sampleValue(sample, x, y, z), fractureDetail.sampleValue(sample, x, y, z));
+            }
+            @Override public void sampleVolume(SamplerContext sample, DensityBuffer buffer, DensityVolume volume) {
+                DensitySampler.sampleVolumeNaive(sample, buffer, volume, this);
+            }
+        };
+    }
+    public static long regionSeed(long seed, IslandCapacity.Region region) {
+        long value = seed ^ ((long) region.x() << 32) ^ (region.z() & 0xffffffffL) ^ 0xA10CA7E1L;
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+    @Override public DensityFunction rewriteChildren(DfRewriteRule rule) {
+        return new PopulationIslandDensity(rule.rewrite(terrain), rule.rewrite(distortion), rule.rewrite(sculpt),
+            rule.rewrite(detail), rule.rewrite(underside), rule.rewrite(riftWarp), rule.rewrite(riftDetail), capacity);
+    }
+    @Override public Interval range() { return Interval.of(-1, 1); }
+    @Override public int domainAxes() { return ALL_AXES; }
+    @Override public MapCodec<PopulationIslandDensity> codec() { return CODEC; }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationIslandShape.java

@@ -0,0 +1,66 @@
+package fr.koka.sanctuary.worldgen;
+
+/** Alpha.10 keeps local erosion scales while expanding only the outer envelope. */
+public final class PopulationIslandShape {
+    private PopulationIslandShape() {}
+
+    /** Generation v3. The natural field and lateral sculpture are sampled in their original frame. */
+    public static float raisedDensity(int x, int y, int z, float terrain, float distortion,
+                                      float sculpt, float detail, float underside, int offset, int height, IslandCapacity capacity) {
+        double distance = Math.hypot((double) x, (double) z);
+        if (distance >= capacity.terrainLimit() || y <= 0 || y >= height) return -1.0F;
+        double localY = (double) y - offset;
+        double erosion = rimErosion(distance, localY, distortion, sculpt, detail, capacity);
+
+        // The former uniform lower gradient is absent from the new natural field. Let its seeded
+        // lobes continue downwards, then sculpt them over a broad, spatially varying transition.
+        // The extra margin below the translated island must not merely reveal the same flat cut.
+        double bottom = -24.0 + Math.clamp(underside, -1.0F, 1.0F) * 16.0
+            + Math.clamp(sculpt, -1.0F, 1.0F) * 8.0 + Math.clamp(detail, -1.0F, 1.0F) * 4.0;
+        double lower = Math.clamp((bottom + 72.0 - localY) / 72.0, 0.0, 1.0);
+        erosion += 2.0 * lower * lower * lower * lower;
+        // Upper silhouette is exactly the old one translated by offset. Absolute-world fades are
+        // safety margins, outside the normal terrain, rather than the island's visible underside.
+        erosion += 2.0 * smoothstep((localY - 224.0) / 32.0);
+        erosion += 2.0 * smoothstep((24.0 - y) / 24.0);
+        erosion += 2.0 * smoothstep((y - (height - 24.0)) / 24.0);
+        return bounded(terrain, erosion);
+    }
+
+    private static double rimErosion(double distance, double y, float distortion, float sculpt, float detail, IslandCapacity capacity) {
+        double coast = Math.clamp(distortion, -1.0F, 1.0F);
+        double coarse = Math.clamp(sculpt, -1.0F, 1.0F);
+        double fine = Math.clamp(detail, -1.0F, 1.0F);
+
+        // Pass 1: a broad outline bends through the island's height with two truly 3D noises.
+        // Keep the central field untouched even when a deeply recessed rim approaches it.
+        double rimEnd = Math.min(capacity.terrainLimit(), capacity.radius() + coast * 16.0 + coarse * 28.0 + fine * 8.0);
+        double rim = Math.clamp((distance - (capacity.radius() - 128)) / (rimEnd - (capacity.radius() - 128)), 0.0, 1.0);
+        // Raising the density threshold gradually shrinks each natural lobe from all sides. Unlike
+        // min(terrain, distance-to-edge), this never shears every altitude at one vertical contour.
+        double erosion = 2.0 * rim * rim * rim * rim;
+
+        // A saturated natural lobe has almost no density gradient through its middle. Merely
+        // raising its threshold can still leave a tall near-vertical wall. Retreat its upper and
+        // lower rim faces as well, with a curved profile that disappears entirely at the interior.
+        // This is an outer-rim cut, never an ellipsoid combined with (or added to) the natural field.
+        double vertical = (y - (104.0 + coarse * 20.0)) / 88.0;
+        erosion += 8.0 * rim * rim * vertical * vertical;
+
+        // Passes 2 and 3: broad recesses and smaller surface erosion, fading into the untouched
+        // interior. Both subtract material; holes stay empty and detached fragments are never joined.
+        double sculptWeight = smoothstep(rim);
+        erosion += sculptWeight * (0.10 * (coarse + 1.0) * 0.5 + 0.04 * (fine + 1.0) * 0.5);
+
+        return erosion;
+    }
+
+    private static float bounded(float terrain, double erosion) {
+        return (float) Math.clamp(Math.clamp(terrain, -1.0F, 1.0F) - erosion, -1.0, 1.0);
+    }
+
+    private static double smoothstep(double value) {
+        double t = Math.clamp(value, 0.0, 1.0);
+        return t * t * (3.0 - 2.0 * t);
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationLavaDeposit.java

@@ -0,0 +1,377 @@
+package fr.koka.sanctuary.worldgen;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
+
+/** Alpha.10 lava: an optional covered pocket and up to two deep rock outlets.
+ * All sources replace natural rock; Minecraft alone produces the falling lava. */
+public final class PopulationLavaDeposit {
+    public static final int RADIUS = 192;
+    public static final int WATER_CLEARANCE = 32;
+    public static final int LAVA_VOLUME = 18;
+    private static final int ENTRY_DISTANCE = 8;
+    private static final int[][] DIRECTIONS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final Comparator<Position> POSITION_ORDER = Comparator.comparingInt(Position::x)
+        .thenComparingInt(Position::z).thenComparingInt(Position::y);
+    private static final Comparator<Cell> CELL_ORDER = Comparator.comparingInt(Cell::x)
+        .thenComparingInt(Cell::z).thenComparingInt(Cell::y);
+
+    private PopulationLavaDeposit() {}
+
+    public record Position(int x, int y, int z) {}
+    /** lava=false removes existing rock to open the two-block-high chamber or approach. */
+    public record Cell(int x, int y, int z, boolean lava) {}
+
+    public static final class Plan {
+        private final List<Cell> cells;
+        private final List<Cell> lavaCells;
+        private final List<Position> supports;
+        private final Optional<Position> access;
+        private final Map<Long, List<Cell>> chunks;
+        private final Map<Long, List<Position>> supportChunks;
+        private final List<PopulationLavaFlows.Fall> falls;
+        private final Map<Long, List<PopulationLavaFlows.Fall>> fallChunks;
+        private final List<Cell> pocketCells;
+        private final Set<Position> pocketSupports;
+
+        private Plan(List<Cell> cells, Set<Position> supports, Position access) {
+            this(cells, supports, access, List.of(), cells, supports);
+        }
+
+        private Plan(List<Cell> cells, Set<Position> supports, Position access, List<PopulationLavaFlows.Fall> falls,
+                     List<Cell> pocketCells, Set<Position> pocketSupports) {
+            this.pocketCells = pocketCells.stream().sorted(CELL_ORDER).toList();
+            this.pocketSupports = Set.copyOf(pocketSupports);
+            this.falls = List.copyOf(falls);
+            Map<Long, List<PopulationLavaFlows.Fall>> groupedFalls = new HashMap<>();
+            for (var fall : falls) groupedFalls.computeIfAbsent(
+                key(fall.source().x() >> 4, fall.source().z() >> 4), ignored -> new ArrayList<>()).add(fall);
+            groupedFalls.replaceAll((ignored, values) -> List.copyOf(values));
+            fallChunks = Map.copyOf(groupedFalls);
+            this.cells = cells.stream().sorted(CELL_ORDER).toList();
+            lavaCells = this.cells.stream().filter(Cell::lava).toList();
+            this.supports = supports.stream().sorted(POSITION_ORDER).toList();
+            this.access = Optional.ofNullable(access);
+            Map<Long, List<Cell>> byChunk = new HashMap<>();
+            for (Cell cell : this.cells) byChunk.computeIfAbsent(key(cell.x() >> 4, cell.z() >> 4),
+                ignored -> new ArrayList<>()).add(cell);
+            byChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            chunks = Map.copyOf(byChunk);
+            Map<Long, List<Position>> bySupportChunk = new HashMap<>();
+            for (Position support : this.supports) bySupportChunk.computeIfAbsent(key(support.x() >> 4, support.z() >> 4),
+                ignored -> new ArrayList<>()).add(support);
+            bySupportChunk.replaceAll((ignored, values) -> List.copyOf(values));
+            supportChunks = Map.copyOf(bySupportChunk);
+        }
+
+        public List<Cell> cells() { return cells; }
+        public List<Cell> lavaCells() { return lavaCells; }
+        public List<Position> supports() { return supports; }
+        public List<PopulationLavaFlows.Fall> falls() { return falls; }
+        public List<PopulationLavaFlows.Fall> fallsInChunk(int x, int z) { return fallChunks.getOrDefault(key(x, z), List.of()); }
+        public List<Position> flowSources() { return falls.stream().map(PopulationLavaFlows.Fall::source).toList(); }
+        public List<PopulationHydrology.FlowBounds> flowBounds() { return falls.stream().map(PopulationLavaFlows.Fall::flowBounds).toList(); }
+        /** Player feet on a natural ledge, with three blocks of headroom below a roof or sky. */
+        public Optional<Position> access() { return access; }
+        public List<Cell> cellsInChunk(int x, int z) { return chunks.getOrDefault(key(x, z), List.of()); }
+        public List<Position> supportsInChunk(int x, int z) { return supportChunks.getOrDefault(key(x, z), List.of()); }
+
+        /** Keep a complete pocket or complete falls, with a 32-block regional safety margin. */
+        public Plan admitted() {
+            boolean keepPocket = pocketCells.stream().allMatch(c -> owned(c.x(), c.z()))
+                && pocketSupports.stream().allMatch(Plan::owned) && access.map(Plan::owned).orElse(true);
+            List<PopulationLavaFlows.Fall> keptFalls = falls.stream().filter(f -> owned(f.source()) && owned(f.outlet())
+                && owned(f.flowBounds()) && f.supports().stream().allMatch(Plan::owned)
+                && f.flowPath().stream().allMatch(Plan::owned)).toList();
+            return compose(keepPocket ? pocketCells : List.of(), keepPocket ? pocketSupports : Set.of(),
+                keepPocket ? access.orElse(null) : null, keptFalls);
+        }
+
+        /** IDs stay region-seeded; every position, flow envelope and chunk index moves together. */
+        public Plan translated(int dx, int dz) {
+            List<Cell> movedPocket = pocketCells.stream().map(c -> new Cell(Math.addExact(c.x(), dx), c.y(),
+                Math.addExact(c.z(), dz), c.lava())).toList();
+            Set<Position> movedSupports = pocketSupports.stream().map(p -> move(p, dx, dz))
+                .collect(java.util.stream.Collectors.toUnmodifiableSet());
+            List<PopulationLavaFlows.Fall> movedFalls = falls.stream().map(f -> new PopulationLavaFlows.Fall(f.id(),
+                move(f.source(), dx, dz), move(f.outlet(), dx, dz), f.flowPath().stream().map(p -> move(p, dx, dz)).toList(),
+                move(f.flowBounds(), dx, dz), f.supports().stream().map(p -> move(p, dx, dz)).toList())).toList();
+            return compose(movedPocket, movedSupports, access.map(p -> move(p, dx, dz)).orElse(null), movedFalls);
+        }
+
+        private static Plan compose(List<Cell> pocket, Set<Position> support, Position access,
+                                    List<PopulationLavaFlows.Fall> selectedFalls) {
+            List<Cell> combined = new ArrayList<>(pocket);
+            Set<Position> combinedSupports = new HashSet<>(support);
+            for (var fall : selectedFalls) {
+                var source = fall.source();
+                combined.add(new Cell(source.x(), source.y(), source.z(), true));
+                combinedSupports.addAll(fall.supports());
+            }
+            return new Plan(combined, combinedSupports, access, selectedFalls, pocket, support);
+        }
+
+        private static boolean owned(int x, int z) { return PopulationOwnership.contains(x, z, 32); }
+        private static boolean owned(Position p) { return owned(p.x(), p.z()); }
+        private static boolean owned(PopulationHydrology.FlowBounds b) {
+            return PopulationOwnership.contains(b.minX(), b.minZ(), b.maxX(), b.maxZ(), 32);
+        }
+        private static Position move(Position p, int dx, int dz) {
+            return new Position(Math.addExact(p.x(), dx), p.y(), Math.addExact(p.z(), dz));
+        }
+        private static PopulationHydrology.FlowBounds move(PopulationHydrology.FlowBounds b, int dx, int dz) {
+            return new PopulationHydrology.FlowBounds(Math.addExact(b.minX(), dx), b.minY(), Math.addExact(b.minZ(), dz),
+                Math.addExact(b.maxX(), dx), b.maxY(), Math.addExact(b.maxZ(), dz));
+        }
+    }
+
+    public static Plan create(long seed, PopulationHydrology.Sampler sampler, PopulationHydrology.Plan hydrology) {
+        Plan pocket = new Search(seed, sampler, hydrology).find();
+        List<PopulationLavaFlows.Fall> falls = PopulationLavaFlows.create(seed, sampler, hydrology, pocket);
+        return Plan.compose(pocket.pocketCells, pocket.pocketSupports, pocket.access().orElse(null), falls);
+    }
+
+    private record Candidate(int x, int z, int dx, int dz, double score) {}
+    private record LowerCandidate(int x, int y, int z, int dx, int dz, double score) {}
+
+    private static final class Search {
+        private final long seed;
+        private final PopulationHydrology.Sampler sampler;
+        private final PopulationHydrology.Plan hydrology;
+        private final Map<Long, Integer> heights = new HashMap<>();
+
+        Search(long seed, PopulationHydrology.Sampler sampler, PopulationHydrology.Plan hydrology) {
+            this.seed = seed;
+            this.sampler = sampler;
+            this.hydrology = hydrology;
+        }
+
+        Plan find() {
+            Plan lower = findLowerPocket();
+            if (lower != null) return lower;
+            List<Candidate> candidates = new ArrayList<>();
+            for (int x = -184; x <= 184; x += 8) for (int z = -184; z <= 184; z += 8) {
+                if (!inside(x, z, RADIUS - 8)) continue;
+                int ledge = top(x, z);
+                if (ledge < 64 || ledge > 300) continue;
+                for (int[] direction : DIRECTIONS) {
+                    int cx = x - direction[0] * ENTRY_DISTANCE, cz = z - direction[1] * ENTRY_DISTANCE;
+                    if (!inside(cx, cz, RADIUS - 12) || !clearOfWater(cx, cz)) continue;
+                    int rise = top(cx, cz) - ledge;
+                    if (rise < 12) continue;
+                    candidates.add(new Candidate(x, z, direction[0], direction[1],
+                        random(seed, cx, cz) + Math.min(rise, 40) * 0.015));
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)
+                .thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (attempts++ >= 192) break;
+                // Refine the coarse edge, including a ledge lying between two eight-block samples.
+                for (int along = 0; along < 8; along++) for (int tangent : new int[]{0, -3, 3}) {
+                    int x = candidate.x() - candidate.dx() * along - candidate.dz() * tangent;
+                    int z = candidate.z() - candidate.dz() * along + candidate.dx() * tangent;
+                    Plan plan = tryNiche(x, z, candidate.dx(), candidate.dz());
+                    if (plan != null) return plan;
+                }
+            }
+            return new Plan(List.of(), Set.of(), null);
+        }
+
+        /** Prefer a real lower ledge below an overhang. The chamber uses exactly the same rock
+         * shell as the outdoor fallback; only the entrance may now have a natural ceiling. */
+        private Plan findLowerPocket() {
+            List<LowerCandidate> candidates = new ArrayList<>();
+            for (int x = -176; x <= 176; x += 16) for (int z = -176; z <= 176; z += 16) {
+                if (!inside(x, z, RADIUS - 8)) continue;
+                for (int coarseY = 64; coarseY <= 160; coarseY += 8) {
+                    if (!solid(x, coarseY, z) || solid(x, coarseY + 8, z)) continue;
+                    int level = coarseY;
+                    for (int y = coarseY + 7; y > coarseY; y--) {
+                        if (solid(x, y, z)) { level = y; break; }
+                    }
+                    if (level > 160 || top(x, z) < level + 12) continue;
+                    for (int[] direction : DIRECTIONS) {
+                        int inwardX = x - direction[0] * 16, inwardZ = z - direction[1] * 16;
+                        if (!inside(inwardX, inwardZ, RADIUS - 12)
+                            || !solid(inwardX, level + 2, inwardZ) || !solid(inwardX, level + 10, inwardZ)) continue;
+                        candidates.add(new LowerCandidate(x, level, z, direction[0], direction[1],
+                            random(seed + level + 0x108E2L, x - direction[0], z - direction[1])
+                                + (160 - level) * .002));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(LowerCandidate::score).reversed()
+                .thenComparingInt(LowerCandidate::x).thenComparingInt(LowerCandidate::z)
+                .thenComparingInt(LowerCandidate::y).thenComparingInt(LowerCandidate::dx).thenComparingInt(LowerCandidate::dz));
+            int attempts = 0;
+            for (LowerCandidate candidate : candidates) {
+                if (attempts++ >= 128) break;
+                for (int along = 0; along < 16; along++) for (int tangent : new int[]{0, -3, 3}) {
+                    int x = candidate.x() - candidate.dx() * along - candidate.dz() * tangent;
+                    int z = candidate.z() - candidate.dz() * along + candidate.dx() * tangent;
+                    for (int level = Math.min(160, candidate.y() + 5); level >= Math.max(64, candidate.y() - 5); level--) {
+                        // Reject solid cave walls and missing floors before expensive shell probes.
+                        if (!solid(x, level, z) || solid(x, level + 1, z)) continue;
+                        Plan plan = tryNiche(x, z, candidate.dx(), candidate.dz(), level, true);
+                        if (plan != null) return plan;
+                    }
+                }
+            }
+            return null;
+        }
+
+        private Plan tryNiche(int entryX, int entryZ, int dx, int dz) {
+            return tryNiche(entryX, entryZ, dx, dz, top(entryX, entryZ), false);
+        }
+
+        private Plan tryNiche(int entryX, int entryZ, int dx, int dz, int level, boolean underground) {
+            int cx = entryX - dx * ENTRY_DISTANCE, cz = entryZ - dz * ENTRY_DISTANCE;
+            if (!inside(cx, cz, RADIUS - 12) || level < 64 || level > (underground ? 160 : 300)
+                || top(cx, cz) < level + 12) return null;
+            // A lower entrance has genuine overhead island rock, but does not need a sky view.
+            if (underground && top(entryX, entryZ) < level + 12) return null;
+            int airLimit = underground ? level + 3 : 383;
+            for (int y = level + 1; y <= airLimit; y++) if (solid(entryX, y, entryZ)) return null;
+            for (int y = level - 2; y <= level; y++) if (!solid(entryX, y, entryZ)) return null;
+            if (underground ? !clearOfWater(cx, level, cz) : !clearOfWater(cx, cz)) return null;
+
+            List<Cell> cells = new ArrayList<>();
+            Set<Position> changed = new HashSet<>();
+            Set<Position> supports = new HashSet<>();
+            for (int x = cx - 1; x <= cx + 1; x++) for (int z = cz - 1; z <= cz + 1; z++) {
+                for (int y = level - 1; y <= level + 2; y++) {
+                    if (!solid(x, y, z)) return null;
+                    add(cells, changed, x, y, z, y <= level);
+                }
+            }
+            // A dry lip separates the ledge from the pool. Only the air above it is opened.
+            for (int distance = 2; distance < ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level + 1; y <= level + 2; y++) {
+                    if (solid(x, y, z)) add(cells, changed, x, y, z, false);
+                }
+            }
+            // Every carved column must lie under eight continuous natural rock blocks. This
+            // excludes soil-cap excavation at the entrance as well as exposed surface lava.
+            Map<Long, Integer> highest = new HashMap<>();
+            for (Cell cell : cells) highest.merge(key(cell.x(), cell.z()), cell.y(), Math::max);
+            for (var column : highest.entrySet()) {
+                int x = (int) (column.getKey() >> 32), z = (int) (long) column.getKey();
+                for (int y = column.getValue() + 1; y <= column.getValue() + 8; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // Three intact blocks under the pool, two-block-thick side walls, and a solid chamber
+            // surround prevent escape through an adjacent cave. No part of this shell is created.
+            for (int x = cx - 3; x <= cx + 3; x++) for (int z = cz - 3; z <= cz + 3; z++) {
+                for (int y = level - 4; y <= level + 2; y++) {
+                    if (changed.contains(new Position(x, y, z))) continue;
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            // The natural roof also covers a conservative envelope around local lava fire spread.
+            // Its thickness keeps later surface vegetation well above the lava chamber.
+            for (int x = cx - 4; x <= cx + 4; x++) for (int z = cz - 4; z <= cz + 4; z++) {
+                for (int y = level + 3; y <= level + 10; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            for (int distance = 2; distance <= ENTRY_DISTANCE; distance++) {
+                int x = cx + dx * distance, z = cz + dz * distance;
+                for (int y = level - 2; y <= level; y++) {
+                    if (!requireRock(supports, x, y, z)) return null;
+                }
+            }
+            supports.removeAll(changed);
+            return new Plan(cells, supports, new Position(entryX, level + 1, entryZ));
+        }
+
+        private boolean requireRock(Set<Position> supports, int x, int y, int z) {
+            if (!solid(x, y, z)) return false;
+            supports.add(new Position(x, y, z));
+            return true;
+        }
+
+        private boolean clearOfWater(int x, int z) {
+            // The extra ten blocks include both the entrance and the complete protected shell.
+            int clearance = WATER_CLEARANCE + 10;
+            for (var cell : hydrology.cells()) {
+                long dx = x - cell.x(), dz = z - cell.z();
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            for (var spring : hydrology.springs()) {
+                var bounds = spring.flowBounds();
+                long dx = Math.max(Math.max((long) bounds.minX() - x, 0), (long) x - bounds.maxX());
+                long dz = Math.max(Math.max((long) bounds.minZ() - z, 0), (long) z - bounds.maxZ());
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            for (var spill : hydrology.spills()) {
+                var bounds = spill.flowBounds();
+                long dx = Math.max(Math.max((long) bounds.minX() - x, 0), (long) x - bounds.maxX());
+                long dz = Math.max(Math.max((long) bounds.minZ() - z, 0), (long) z - bounds.maxZ());
+                if (dx * dx + dz * dz < (long) clearance * clearance) return false;
+            }
+            return true;
+        }
+
+        private boolean clearOfWater(int x, int level, int z) {
+            // This box covers chamber, dry approach, intact shell and roof. A lake far above is
+            // allowed; an actual waterfall crossing this level still excludes the entire pocket.
+            var pocket = new PopulationHydrology.FlowBounds(x - 10, level - 4, z - 10, x + 10, level + 10, z + 10);
+            for (var cell : hydrology.cells()) {
+                var ground = new PopulationHydrology.FlowBounds(cell.x(), cell.bedY() - cell.sedimentDepth() - 1,
+                    cell.z(), cell.x(), Math.max(cell.carveTop(), cell.waterY()), cell.z());
+                if (distanceSquared(pocket, ground) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spring : hydrology.springs()) {
+                if (distanceSquared(pocket, spring.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spill : hydrology.spills()) {
+                if (distanceSquared(pocket, spill.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            return true;
+        }
+
+        private static long distanceSquared(PopulationHydrology.FlowBounds a, PopulationHydrology.FlowBounds b) {
+            long dx = Math.max(0, Math.max((long) a.minX() - b.maxX(), (long) b.minX() - a.maxX()));
+            long dy = Math.max(0, Math.max((long) a.minY() - b.maxY(), (long) b.minY() - a.maxY()));
+            long dz = Math.max(0, Math.max((long) a.minZ() - b.maxZ(), (long) b.minZ() - a.maxZ()));
+            return dx * dx + dy * dy + dz * dz;
+        }
+
+        private int top(int x, int z) {
+            return heights.computeIfAbsent(key(x, z), ignored -> {
+                for (int y = 383; y >= 32; y -= 4) {
+                    if (!solid(x, y, z)) continue;
+                    for (int exact = Math.min(383, y + 3); exact > y; exact--) if (solid(x, exact, z)) return exact;
+                    return y;
+                }
+                return -1;
+            });
+        }
+
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+    }
+
+    private static void add(List<Cell> cells, Set<Position> changed, int x, int y, int z, boolean lava) {
+        if (changed.add(new Position(x, y, z))) cells.add(new Cell(x, y, z, lava));
+    }
+
+    private static boolean inside(int x, int z, int radius) { return (long) x * x + (long) z * z < (long) radius * radius; }
+    private static long key(int x, int z) { return ((long) x << 32) | (z & 0xffffffffL); }
+    private static double random(long seed, int x, int z) {
+        long value = seed ^ key(x, z) ^ 0x1A7A5EEDL;
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return ((value ^ (value >>> 31)) >>> 11) * 0x1.0p-53;
+    }
+}

mods/sanctuary/src/main/java/fr/koka/sanctuary/worldgen/PopulationLavaFlows.java

@@ -0,0 +1,241 @@
+package fr.koka.sanctuary.worldgen;
+
+import fr.koka.sanctuary.worldgen.PopulationLavaDeposit.Position;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** Selects a few volcanic seeps in deep exposed rock. Sources replace rock; their outlets and
+ * entire falling columns are left empty for vanilla lava ticks. No retaining wall is generated. */
+public final class PopulationLavaFlows {
+    public static final int MIN_SOURCE_Y = 40;
+    public static final int MAX_SOURCE_Y = 160;
+    public static final int MAX_FALLS = 2;
+    public static final int HORIZONTAL_REACH = 3;
+    public static final int FIRE_CLEARANCE = 8;
+    public static final int WATER_CLEARANCE = 24;
+    private static final int RADIUS = 224;
+    private static final int[][] CARDINALS = {{1, 0}, {-1, 0}, {0, 1}, {0, -1}};
+    private static final Comparator<Position> POSITION_ORDER = Comparator.comparingInt(Position::x)
+        .thenComparingInt(Position::z).thenComparingInt(Position::y);
+
+    private PopulationLavaFlows() {}
+
+    /** flowBounds predicts undecorated rock drainage; it does not override Minecraft physics.
+     * supports contains only unchanged natural rock around the source, never the source itself. */
+    public record Fall(long id, Position source, Position outlet, List<Position> flowPath,
+                       PopulationHydrology.FlowBounds flowBounds, List<Position> supports) {
+        public Fall { flowPath = List.copyOf(flowPath); supports = List.copyOf(supports); }
+    }
+
+    public static List<Fall> create(long seed, PopulationHydrology.Sampler sampler,
+                                    PopulationHydrology.Plan water, PopulationLavaDeposit.Plan pocket) {
+        return new Search(seed, sampler, water, pocket).find();
+    }
+
+    private record Candidate(int x, int y, int z, int dx, int dz, double score) {}
+    private record Node(Position at, int reach) {}
+    private record Trace(List<Position> path, PopulationHydrology.FlowBounds bounds) {}
+
+    private static final class Search {
+        private final long seed;
+        private final PopulationHydrology.Sampler sampler;
+        private final PopulationHydrology.Plan water;
+        private final PopulationLavaDeposit.Plan pocket;
+        private final List<Fall> falls = new ArrayList<>();
+
+        Search(long seed, PopulationHydrology.Sampler sampler, PopulationHydrology.Plan water, PopulationLavaDeposit.Plan pocket) {
+            this.seed = seed; this.sampler = sampler; this.water = water; this.pocket = pocket;
+        }
+
+        List<Fall> find() {
+            List<Candidate> candidates = new ArrayList<>();
+            // Coarse probes below the surface can see a lower overhang that a heightmap hides.
+            for (int x = -216; x <= 216; x += 8) for (int z = -216; z <= 216; z += 8) {
+                if ((long) x * x + (long) z * z >= (long) RADIUS * RADIUS) continue;
+                for (int y = MIN_SOURCE_Y; y <= MAX_SOURCE_Y; y += 8) {
+                    if (!solid(x, y, z)) continue;
+                    for (int[] d : CARDINALS) {
+                        if (solid(x + d[0] * 4, y, z + d[1] * 4)) continue;
+                        double score = random(seed + y, x + d[0], z + d[1])
+                            + (MAX_SOURCE_Y - y) * .002;
+                        candidates.add(new Candidate(x, y, z, d[0], d[1], score));
+                    }
+                }
+            }
+            candidates.sort(Comparator.comparingDouble(Candidate::score).reversed()
+                .thenComparingInt(Candidate::x).thenComparingInt(Candidate::z)
+                .thenComparingInt(Candidate::y).thenComparingInt(Candidate::dx).thenComparingInt(Candidate::dz));
+            int attempts = 0;
+            for (Candidate candidate : candidates) {
+                if (falls.size() >= MAX_FALLS || attempts++ >= 160) break;
+                boolean placed = false;
+                for (int tangent : new int[]{0, -2, 2}) {
+                    for (int along = 0; along < 4; along++) {
+                        int x = candidate.x() + candidate.dx() * along - candidate.dz() * tangent;
+                        int z = candidate.z() + candidate.dz() * along + candidate.dx() * tangent;
+                        for (int dy : new int[]{0, 2, -2, 4, -4}) {
+                            Position source = new Position(x, candidate.y() + dy, z);
+                            if (source.y() < MIN_SOURCE_Y || source.y() > MAX_SOURCE_Y || !separated(source)) continue;
+                            List<Position> supports = niche(source, candidate.dx(), candidate.dz());
+                            if (supports == null) continue;
+                            Position outlet = new Position(x + candidate.dx(), source.y(), z + candidate.dz());
+                            Trace flow = trace(source, outlet);
+                            if (flow == null || flow.bounds().minY() > source.y() - 12 || !clearOfWater(flow.bounds())) continue;
+                            long id = mix(seed ^ (0x1A7AFA11L + falls.size() * 0x9E3779B97F4A7C15L));
+                            falls.add(new Fall(id, source, outlet, flow.path(), flow.bounds(), supports));
+                            placed = true;
+                            break;
+                        }
+                        if (placed) break;
+                    }
+                    if (placed) break;
+                }
+            }
+            return List.copyOf(falls);
+        }
+
+        private boolean separated(Position source) {
+            PopulationHydrology.FlowBounds point = bounds(source);
+            if (!clearOfWater(point)) return false;
+            for (Fall fall : falls) {
+                if (distanceSquared(source, fall.source()) < 80L * 80
+                    || distanceSquared(point, fall.flowBounds()) < 40L * 40) return false;
+            }
+            for (var cell : pocket.cells()) {
+                if (distanceSquared(source, new Position(cell.x(), cell.y(), cell.z())) < 32L * 32) return false;
+            }
+            return true;
+        }
+
+        private List<Position> niche(Position source, int dx, int dz) {
+            if (!solid(source)) return null;
+            Set<Position> supports = new HashSet<>();
+            // The source sits in rock, with a short intact roof, floor and three back/side faces.
+            // The spill column needs no floor: its absence is precisely what makes a cascade.
+            for (int dy = -3; dy <= 8; dy++) {
+                if (dy == 0) continue;
+                Position at = new Position(source.x(), source.y() + dy, source.z());
+                if (!solid(at)) return null;
+                supports.add(at);
+            }
+            for (int[] d : CARDINALS) {
+                if (d[0] == dx && d[1] == dz) continue;
+                for (int depth = 1; depth <= 2; depth++) {
+                    Position at = new Position(source.x() + d[0] * depth, source.y(), source.z() + d[1] * depth);
+                    if (!solid(at)) return null;
+                    supports.add(at);
+                }
+            }
+            for (int dy = 0; dy >= -8; dy--) {
+                if (solid(source.x() + dx, source.y() + dy, source.z() + dz)) return null;
+            }
+            return supports.stream().sorted(POSITION_ORDER).toList();
+        }
+
+        private boolean clearOfWater(PopulationHydrology.FlowBounds bounds) {
+            for (var cell : water.cells()) {
+                var column = new PopulationHydrology.FlowBounds(cell.x(), cell.bedY() - cell.sedimentDepth() - 1,
+                    cell.z(), cell.x(), Math.max(cell.carveTop(), cell.waterY()), cell.z());
+                if (distanceSquared(bounds, column) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spring : water.springs()) {
+                if (distanceSquared(bounds, spring.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            for (var spill : water.spills()) {
+                if (distanceSquared(bounds, spill.flowBounds()) < (long) WATER_CLEARANCE * WATER_CLEARANCE) return false;
+            }
+            return true;
+        }
+
+        /** Descending lava resets its horizontal reach to three in this non-ultrawarm dimension.
+         * Explore all downhill branches through rock, so selection does not depend on chunk order. */
+        private Trace trace(Position source, Position outlet) {
+            Map<Position, Integer> reach = new HashMap<>();
+            Map<Position, Position> parent = new HashMap<>();
+            ArrayDeque<Node> queue = new ArrayDeque<>();
+            reach.put(source, HORIZONTAL_REACH);
+            queue.addLast(new Node(source, HORIZONTAL_REACH));
+            Position lowest = source;
+            while (!queue.isEmpty()) {
+                Node node = queue.removeFirst();
+                Position at = node.at();
+                if (node.reach() < reach.getOrDefault(at, -1)) continue;
+                if (at.y() < lowest.y()) lowest = at;
+                if (reach.size() > 12000 || Math.abs(at.x() - source.x()) > 64 || Math.abs(at.z() - source.z()) > 64) return null;
+                if (at.y() <= 0) continue;
+                Position below = new Position(at.x(), at.y() - 1, at.z());
+                if (!flowSolid(below, source)) {
+                    enqueue(below, HORIZONTAL_REACH, at, reach, parent, queue);
+                    continue;
+                }
+                if (node.reach() <= 0) continue;
+                for (int[] d : CARDINALS) {
+                    Position next = new Position(at.x() + d[0], at.y(), at.z() + d[1]);
+                    if (!flowSolid(next, source)) enqueue(next, node.reach() - 1, at, reach, parent, queue);
+                }
+            }
+            if (!reach.containsKey(outlet)) return null;
+            int minX = source.x(), maxX = minX, minY = source.y(), maxY = minY, minZ = source.z(), maxZ = minZ;
+            for (Position at : reach.keySet()) {
+                minX = Math.min(minX, at.x()); maxX = Math.max(maxX, at.x());
+                minY = Math.min(minY, at.y()); maxY = Math.max(maxY, at.y());
+                minZ = Math.min(minZ, at.z()); maxZ = Math.max(maxZ, at.z());
+            }
+            List<Position> path = new ArrayList<>();
+            for (Position at = lowest; at != null; at = parent.get(at)) path.add(at);
+            Collections.reverse(path);
+            return new Trace(List.copyOf(path), new PopulationHydrology.FlowBounds(minX, minY, minZ, maxX, maxY, maxZ));
+        }
+
+        private boolean flowSolid(Position at, Position source) {
+            if (at.equals(source)) return false;
+            var cell = water.cellAt(at.x(), at.y(), at.z());
+            if (cell != null && at.y() > cell.bedY() && at.y() <= cell.carveTop()) return false;
+            return solid(at);
+        }
+
+        private boolean solid(Position at) { return solid(at.x(), at.y(), at.z()); }
+        private boolean solid(int x, int y, int z) { return sampler.sample(x, y, z) > 0; }
+    }
+
+    private static void enqueue(Position next, int available, Position from, Map<Position, Integer> reach,
+                                Map<Position, Position> parent, ArrayDeque<Node> queue) {
+        if (available <= reach.getOrDefault(next, -1)) return;
+        if (!reach.containsKey(next)) parent.put(next, from);
+        reach.put(next, available);
+        queue.addLast(new Node(next, available));
+    }
+
+    private static PopulationHydrology.FlowBounds bounds(Position at) {
+        return new PopulationHydrology.FlowBounds(at.x(), at.y(), at.z(), at.x(), at.y(), at.z());
+    }
+
+    private static long distanceSquared(Position a, Position b) {
+        long dx = a.x() - b.x(), dy = a.y() - b.y(), dz = a.z() - b.z();
+        return dx * dx + dy * dy + dz * dz;
+    }
+
+    private static long distanceSquared(PopulationHydrology.FlowBounds a, PopulationHydrology.FlowBounds b) {
+        long dx = Math.max(0, Math.max((long) a.minX() - b.maxX(), (long) b.minX() - a.maxX()));
+        long dy = Math.max(0, Math.max((long) a.minY() - b.maxY(), (long) b.minY() - a.maxY()));
+        long dz = Math.max(0, Math.max((long) a.minZ() - b.maxZ(), (long) b.minZ() - a.maxZ()));
+        return dx * dx + dy * dy + dz * dz;
+    }
+
+    private static double random(long seed, int x, int z) {
+        return (mix(seed ^ ((long) x << 32) ^ (z & 0xffffffffL)) >>> 11) * 0x1.0p-53;
+    }
+
+    private static long mix(long value) {
+        value = (value ^ (value >>> 30)) * 0xbf58476d1ce4e5b9L;
+        value = (value ^ (value >>> 27)) * 0x94d049bb133111ebL;
+        return value ^ (value >>> 31);
+    }
+}