feat(worldgen): add persistent aerial Sanctuary sites for alpha.24

docs/testing-alpha24.md

@@ -0,0 +1,262 @@
+# Vérifications alpha.24
+
+Branche `codex/aerial-sanctuary-alpha24`, base alpha.23.1 `fbefb2e`.
+Minecraft 26.3-pre-2, Fabric Loader 0.19.5, Fabric API 0.160.0+26.3,
+Java 25 ; mod et pack `0.1.0-alpha.24`.
+
+**Matrice de génération réussie le 11 septembre 2026.** Les quatorze scénarios
+passent : neuf créations, deux réouvertures, deux options OFF et l’ordre inverse
+de chargement. Les tests purs, deux admissions réelles d’expansion et la
+cascade native jusqu’à Y8 réussissent également. Les 24 GameTests généraux passent également.
+`check build assemblePack` passe en 3 min 56 s (83 tâches), avec les 24
+GameTests natifs également réussis dans ce build. JAR, MRpack, index packwiz
+et bootstrap officiel sont vérifiés. La publication et la synchronisation
+restent en préparation.
+Le [contrat de génération](generation-alpha24.md) décrit le périmètre.
+
+## Environnement et preuves
+
+Les essais utilisent un serveur Fabric GameTest sans interface graphique sur
+Mac. Les mondes jetables restent dans `mods/sanctuary/build/run/gameTest/` ;
+aucune sauvegarde personnelle n’est ouverte ou modifiée. Aucun essai Windows
+natif ni contrôle graphique du client avec shaders n’a été exécuté.
+
+Les résultats retenus figurent dans `build/alpha24-evidence/matrix.json`,
+avec les rapports `<phase>-<graine>-<diamètre>.json` et leurs journaux `.log`.
+Un résultat n’est retenu qu’après sortie réussie du processus et
+`passed: true` dans le rapport. Ces fichiers de développement sont ignorés par
+Git. Les essais précédant la végétation sont conservés séparément dans
+`build/alpha24-evidence-before-vegetation/` et ne valident pas les formes finales.
+Ceux précédant la correction du rivage sont dans
+`build/alpha24-evidence-before-shore-fix/` ; ils attestent les contrôles déjà
+réussis, mais pas les nouveaux emplacements recherchés par le filtre corrigé.
+
+Le journal `build/alpha24-shore-smoke.log` atteste les tests purs finaux.
+Les images `balloon.png`, `merchant_*.png` et `mineral_islet_*.png` sont des
+projections de contrôle calculées depuis l’export des blocs du renderer :
+ce ne sont pas des captures d’écran Minecraft. Le test FULL vérifie séparément
+que les matériaux prévus existent dans le monde natif.
+
+## Résultats exécutés
+
+| Essai | Résultat | Preuve |
+| --- | --- | --- |
+| Placement pur : 3 tailles × graines 0, 42, 2026 ; rotations, emprises, conflits et rivage obstrué | Réussi après correction | `alpha24-shore-smoke.log`, `Aerial24Smoke` |
+| Manifeste avant journal, relecture stricte, corruption, absence, conflits, plan vide et historique23 | Réussi | Même journal, `AerialPersistence24Smoke` |
+| Neuf créations de la matrice après correction du rivage | 9 sur 9 réussies | Tableau ci-dessous |
+| Moyen 724, graine 0, première réouverture | Réussi, 54,85 s | `reload1-0-724.json` |
+| Même monde, seconde réouverture | Réussi, 54,50 s | `reload2-0-724.json` |
+| Option expérimentale OFF, en serveur natif | Réussi, 52,93 s | `create-0-724-experimental-off.json` |
+| Structures globales OFF, en serveur natif | Réussi, 27,19 s | `create-0-724-global-off.json` |
+| Génération des chunks dans l’ordre inverse | Réussi, 81,58 s ; sept champs strictement identiques | `create-0-724-reverse.json`, `reverse-comparison.json` |
+| Cascade jusqu’à Y8 et deux admissions réelles entre les emprises | Réussi, 2 min 39 s | `flow-admission-0-724.json`, `alpha24-flow-admission.log` |
+| Comparaison du témoin historique23 avec l’alpha.23.1 | Réussie sur le code24 avant la passe végétale | `legacy23-comparison.json` |
+| GameTests généraux : Blocodex, options, population et hydrologie | 24 sur 24 réussis, JVM 2 min 2 s ; suite 54,47 s | `build/alpha24-general-gametest.log` |
+| `check build assemblePack`, contrôle des artefacts | Réussi ; 83 tâches, suite native 24/24 | `build/alpha24-check-build-pack.log`, `build/alpha24-artifacts.json` |
+
+| Graine | Petit 512 | Moyen 724 | Grand 1 024 |
+| --- | --- | --- | --- |
+| 0 | Réussi, 62,64 s ; 57 chunks FULL | Réussi, 80,96 s ; 61 chunks FULL | Réussi, 128,84 s ; 48 chunks FULL |
+| 42 | Réussi, 58,25 s ; 61 chunks FULL | Réussi, 72,91 s ; 57 chunks FULL | Réussi, 92,08 s ; 58 chunks FULL |
+| 2026 | Réussi, 59,43 s ; 44 chunks FULL | Réussi, 80,77 s ; 37 chunks FULL | Réussi, 115,93 s ; 48 chunks FULL |
+
+Chaque création active retrouve les cinq sites, leurs cinq coffres, deux
+marchands et une source de cascade. Les emprises réservées vont de 31 à 55
+chunks selon le monde. Les deux cas OFF retrouvent un plan vide, aucune
+réservation aérienne et aucun site aérien annoncé dans le registre.
+
+L’ordre inverse, exécuté sur un nouveau Moyen, graine 0, conserve exactement
+la géométrie, le codec, les départs NBT, les blocs avant et après usage,
+les mutations du test et la végétation. `reverse-comparison.json` consigne
+l’égalité stricte de ces sept champs ; les durées et états transitoires de
+chargement ne sont pas comparés comme s’ils devaient être identiques.
+
+Les durées incluent Gradle, le lancement du serveur, la préparation du monde,
+les chunks FULL demandés et les assertions. Ce ne sont ni des temps de rendu
+client, ni une mesure Windows, ni le délai nécessaire pour générer toute l’île.
+
+### Correction du point de vue de rivage
+
+La première matrice végétalisée avait échoué sur le Petit, graine 42 : le
+sanctuaire minéral construisait sa voûte jusqu’à Y187 au-dessus d’un point
+calculé sur le terrain brut à Y174. Le planner prépare désormais les plans
+racine avant le manifeste aérien, puis refuse leurs volumes au niveau du
+support, du point de vue et de la ligne de visée. Les assertions FULL restent
+strictes ; le cas fautif passe dans la nouvelle série. Deux tests purs
+vérifient une obstruction au rivage et au milieu du segment de vue.
+
+Cette correction peut changer le candidat retenu pour un nouveau monde24.
+Un plan déjà sauvegardé reste relu tel quel : aucun recalcul implicite et
+aucune modification des anciens mondes23.
+
+### Ce que le témoin Moyen vérifie
+
+Les cinq sites réservent **55 chunks**, sans réserver un anneau entier. Le test
+charge **61 chunks FULL**, comprenant ces emprises, leurs points de rivage et
+le chunk qui reçoit les villageois extraits. Il vérifie notamment :
+
+- Les cinq vrais départs de structures natifs, leurs pièces, leurs coordonnées,
+  la sérialisation NBT et les états d’occupation conservés.
+- Cinq coffres réellement placés, leurs tables vanilla et un butin non vide,
+  puis leur maintien à vide après deux redémarrages.
+- Deux villageois présents, un par navire, puis déplacés dans le chunk de test.
+  Leur position reste conservée et aucun remplaçant n’apparaît dans les navires.
+- Des blocs de minerai et un élément de nacelle retirés restent absents après
+  les deux réouvertures. Cette manipulation est limitée au monde de développement.
+- Des accès et intérieurs avec un sol et deux blocs libres, ainsi que les trois
+  couches de couverture des coffres enterrés lors de la création.
+- Les points de rivage reposent sur le terrain FULL et ne sont pas enfouis.
+  Les colonnes extérieures échantillonnées restent vides de construction.
+- Le registre passe de `PLANNED` à `GENERATED`, les recherches utilisent les
+  vrais départs et le journal d’expansion reste inchangé pendant ces visites.
+
+La source d’eau est présente et conservée ; l’essai séparé ci-dessous vérifie
+sa descente par les ticks de fluide jusqu’à Y8.
+
+La création et les deux réouvertures contrôlent aussi la végétation réelle. Sur l’îlot avec
+cascade, **596 des 783 colonnes de surface intactes portent de l’herbe**
+(76,1 %), avec deux arbres et 27 blocs de hauteur rocheuse. Sur l’îlot sec,
+ce sont **1 506 sur 1 788** (84,2 %), quatre arbres et 21 blocs de roche.
+Chaque enveloppe ajoute huit blocs pour les couronnes. Les troncs ont un appui
+en terre, les couronnes restent dans l’emprise et les feuilles utilisent les
+propriétés natives de distance, sans persistance forcée.
+`persistence-comparison.json` confirme également l’égalité de la géométrie,
+du codec, des départs natifs, des blocs après usage, des mutations et des
+mesures de végétation dans les deux relectures.
+
+### Admission réelle et écoulement natif
+
+`flow-admission-0-724.json` et `build/alpha24-flow-admission.log` attestent le
+test dans un autre monde jetable Moyen, graine 0. Il appelle le véritable
+`ExpansionRuntime.Session.create` avant que les satellites soient visités.
+
+| Expansion de test, diamètre 128 | Premier centre envisagé X Z | Centre réellement réservé X Z | Appel de réservation | Résultat |
+| --- | --- | --- | ---: | --- |
+| `aerial_collision_0_southeast` | `496 336`, chevauche un satellite | `368 496` | 114 ms | `READY`, un départ vanilla valide |
+| `aerial_interval_0_northeast` | `400 -432`, passage libre | `400 -432` | 54 ms | `READY`, un départ vanilla valide |
+
+La première demande filtre le candidat en conflit, puis poursuit les
+vérifications d’adaptation avant sa réservation définitive. La seconde
+montre que la bande entre les satellites reste utilisable. Les deux
+réservations sont idempotentes, respectent leurs emprises et atteignent
+`READY` avec une structure native adaptée. Ces durées d’appels ne représentent
+pas la préparation complète, comprise dans le test de 2 min 39 s.
+
+Après chargement et activation des ticks des chunks concernés, l’unique
+source prévue produit de l’eau sous l’îlot à `399 194 312`, puis à
+`399 8 312`, après **1 180 ticks d’attente contrôlée**. À Y8, le fluide
+est de l’eau courante, pas une source artificiellement posée. Aucun chemin
+vertical de blocs sources n’est fabriqué par le renderer. Cet essai valide
+ce trajet réel ; il ne garantit pas la forme de l’écoulement après des
+constructions ou excavations effectuées par les joueurs.
+
+### Chargement des habitants dans le test Grand
+
+Le premier essai Grand, graine 0, a rencontré un délai de visibilité des
+entités : les marchands existaient sur disque mais n’étaient pas encore
+exposés au test. Le protocole de lecture charge désormais les navires entiers,
+vérifie la disponibilité native des entités et attend au plus 600 ticks.
+L’exigence reste de deux marchands distincts, sans création ou remplacement
+par le test. Les trois Grands passent ensuite : le témoin graine0 attend
+250 ticks et celui de graine2026, 323 ticks, avant de voir les deux habitants.
+Cela confirme que l’ancienne limite de 200 ticks du fixture était trop courte.
+Le premier essai interrompu n’est pas compté dans les réussites de la matrice.
+
+## Repères de visite — Moyen 724, graine 0
+
+Créer un **nouveau monde Sanctuary de génération24**, taille Moyen, graine `0`,
+avec **Générer les structures** et **Structures expérimentales** activés.
+Les coordonnées proviennent de `create-0-724.json`, champ `look_views`.
+Le nouveau rapport après correction du rivage confirme ces mêmes coordonnées.
+Les repères de rivage désignent un point de vue deux blocs au-dessus du témoin
+enregistré ; ils ne constituent pas des téléportations de survie exécutées.
+
+| Lieu | Entrée X Y Z | Point de vue au rivage X Y Z | Distance horizontale entrée–rivage |
+| --- | --- | --- | ---: |
+| Montgolfière | `-492 288 110` | `-251 219 55` | 247,2 blocs |
+| Navire de vivres | `-35 186 -503` | `-19 176 -282` | 221,6 blocs |
+| Navire de matériel | `463 186 -204` | `229 159 -102` | 255,3 blocs |
+| Îlot avec cascade | `399 237 333` | `195 161 163` | 265,5 blocs |
+| Îlot sec | `-277 256 456` | `-125 227 207` | 291,7 blocs |
+
+Pour un repérage de développement, `/locate structure sanctuary:aerial_balloon`,
+`sanctuary:aerial_merchant_ship` et `sanctuary:aerial_mineral_islet` utilisent
+les types natifs. `/sanctuary census structures aerial` distingue les cinq
+sites. Aucun pont ou véhicule n’est ajouté pour les atteindre. La limite de
+512 blocs depuis un rivage ne force pas les réglages de rendu du client ou
+du serveur, ni la visibilité à travers les feuillages.
+
+## Historique23
+
+Le rapport `legacy23-0-724.json`, produit sur un monde de génération23 avec le
+code24 avant l’ajout de végétation aérienne, a été comparé à
+`build/alpha231-evidence/final-medium.json`. Tous les champs sont identiques,
+à l’exception attendue de `process_id` : codec, plans, départs natifs,
+géométrie, rails et traversées contrôlés dans **85 chunks FULL**.
+`legacy23-comparison.json` consigne cette égalité.
+
+Cette preuve porte sur ce témoin précis, pas sur toutes les graines ni toutes
+les dimensions. Les tests de persistance conservent aussi les octets du journal23
+et refusent une conversion implicite vers24. Aucun monde existant ne reçoit
+automatiquement les satellites24 ; le nouveau manifeste appartient uniquement
+aux nouveaux mondes24.
+
+## Reproduction
+
+Depuis la racine du dépôt, exécuter les commandes **séquentiellement**.
+`runGameTest` recrée son monde de développement par défaut. Pour les phases
+de réouverture, garder le même dossier et ajouter impérativement
+`sanctuaryExpansionReload=true`.
+
+```sh
+./gradlew :sanctuary:aerial24Smoke :sanctuary:aerialPersistence24Smoke
+
+./gradlew :sanctuary:runGameTest \
+  -PsanctuaryAerial24Tests=true \
+  -PsanctuaryTestDiameter=724 -PsanctuaryTestSeed=0 \
+  -PsanctuaryAerial24Phase=create -PsanctuaryDensityMaps=false
+
+./gradlew :sanctuary:runGameTest \
+  -PsanctuaryAerial24Tests=true \
+  -PsanctuaryTestDiameter=724 -PsanctuaryTestSeed=0 \
+  -PsanctuaryAerial24Phase=reload1 -PsanctuaryExpansionReload=true \
+  -PsanctuaryDensityMaps=false
+
+./gradlew :sanctuary:runGameTest \
+  -PsanctuaryAerial24Tests=true \
+  -PsanctuaryTestDiameter=724 -PsanctuaryTestSeed=0 \
+  -PsanctuaryAerial24Phase=reload2 -PsanctuaryExpansionReload=true \
+  -PsanctuaryDensityMaps=false
+```
+
+La matrice de créations reprend les diamètres `512`, `724`, `1024` et les
+graines `0`, `42`, `2026`. Les variantes du Moyen, graine0, ajoutent séparément
+`-PsanctuaryExperimentalStructures=false`,
+`-PsanctuaryGenerateStructures=false` ou
+`-PsanctuaryAerial24ReverseChunks=true` à la commande de création.
+L’essai d’admission et d’eau utilise un nouveau monde :
+
+```sh
+./gradlew :sanctuary:runGameTest \
+  -PsanctuaryAerial24FlowAdmission=true \
+  -PsanctuaryTestGeneration=24 -PsanctuaryTestDiameter=724 \
+  -PsanctuaryTestSeed=0 -PsanctuaryDensityMaps=false
+```
+
+Cette dernière commande reproduit l’essai d’admission et d’écoulement réussi.
+Les assertions sont dans
+[Aerial24WorldGameTests](../mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/Aerial24WorldGameTests.java)
+et [Aerial24FlowAdmissionGameTests](../mods/sanctuary/src/gametest/java/fr/koka/sanctuary/gametest/Aerial24FlowAdmissionGameTests.java).
+
+## Limites et distribution
+
+Les essais ne valident pas encore le ressenti en vol, la lisibilité dans le
+client, l’équilibrage économique des filons, les performances multijoueurs ou
+les incidents Windows rapportés sur cette préversion Minecraft. Le test pur
+des neuf plans emploie un terrain synthétique ; seule la matrice FULL valide
+leur adaptation au relief réel des graines retenues.
+
+L’accès Gitea est rétabli, avec la permission de pousser. La distribution
+est en préparation ; la publication et la synchronisation Prism ne sont pas
+encore effectuées. L’état final des artefacts et du canal sera consigné après
+les contrôles de livraison.