Add contained surface hydrology to Sanctuary Island

docs/testing.md

@@ -27,6 +27,12 @@ sculpture du bord, limite extérieure, hauteur et stabilité de la fonction
 géométrique. Elle complète les tests en jeu ; elle ne charge pas à elle
 seule les ressources de génération de Minecraft.
 
+La tâche `:sanctuary:hydrologySmoke`, également incluse dans `check`, vérifie
+le planificateur sur des reliefs contrôlés : reproductibilité, variation de la
+graine, limites de profondeur et d’excavation, support naturel, parois, ruisseau
+sur plateau compatible et partition indépendante de l’ordre des chunks. Les
+scénarios vides, percés ou trop minces ne reçoivent aucun bassin de secours.
+
 ## Tests dans le moteur Minecraft
 
 `runGameTest` démarre le serveur de test headless officiel de Fabric dans
@@ -52,7 +58,7 @@ Le framework déplace aussi le spawn vers une grille de tests située loin du ce
 Le test capture donc le spawn juste avant ce déplacement, après l'initialisation
 normale du monde, et examine les coordonnées absolues de l'île.
 
-Les sept tests Sanctuary vérifient :
+Les neuf tests Sanctuary vérifient :
 
 1. Le vrai générateur Sanctuary est chargé et le spawn collectif repose sur une
    surface déjà présente dans la densité naturelle, avec un sol plein de 3×3
@@ -72,6 +78,12 @@ Les sept tests Sanctuary vérifient :
 7. Le relevé après génération compte exactement tous les états des blocs des
    chunks demandés, avec des totaux cohérents et une complétude explicite.
    Voir [Expansion et ressources](expansion.md) pour le mode complet facultatif.
+8. Le plan hydrologique se retrouve dans les vrais chunks après décoration :
+   eau retenue, fonds naturels sur trois blocs, parois continues, ouverture au
+   ciel, raccords entre chunks et canne à sucre pouvant survivre. Après des
+   mises à jour réelles de fluides, chaque bloc d’eau doit rester dans ce plan.
+9. Les paramètres et le biome des anciennes sauvegardes n’activent ni le
+   traitement hydrologique ni la nouvelle décoration des berges.
 
 La recherche de spawn parcourt l'île finie, par anneaux de quatre blocs jusqu'à
 288 blocs du centre. Elle examine d'abord la hauteur brute pour éviter de
@@ -109,6 +121,40 @@ Référence du workflow : [tests automatiques Fabric](https://docs.fabricmc.net/
 Les signatures propres à `26.3-pre-2` ont été vérifiées dans les dépendances locales,
 car la documentation publiée vise actuellement `26.2`.
 
+## Diagnostic hydrologique
+
+Les essais hydrologiques demandent les chunks contenant tous les sites du plan
+et un halo d’un chunk. Ils inspectent des chunks `FULL`, avec minerais, arbres
+et plantes déjà générés, et comparent tous les blocs d’eau observés au volume
+annoncé. Leur carte montre les vrais blocs de surface ; le feuillage et les
+troncs sont masqués pour lire les berges. Il ne s’agit pas d’une capture du jeu.
+
+Les chunks de l’île sont maintenus actifs pendant le test. Chaque position
+d’eau doit être dans un chunk où les blocs sont effectivement simulés. Un petit
+témoin d’eau temporaire, enfermé en hauteur dans un de ces mêmes chunks, doit
+réellement couler ; il est ensuite entièrement retiré. Les sources des sites
+reçoivent elles aussi des ticks, puis la rétention est revérifiée au tick 200.
+Attendre près de la grille éloignée du framework ne remplacerait pas ce contrôle.
+
+Les fichiers `surface-hydrology-seed-<graine>-generated.json/.png` et
+`surface-hydrology-seed-<graine>-after-200-ticks.json/.png` sont écrits dans
+`mods/sanctuary/build/run/gameTest/diagnostics/`. Ils décrivent les sites et leur
+nature, leurs coordonnées, le volume d’eau réel, la canne à sucre, les raccords
+entre chunks, les berges et les bornes inspectées. Le nombre de blocs d’eau
+n’est pas une mesure de débit. Un résultat sans site `STREAM` ne valide pas
+une rivière, même s’il contient des lacs.
+
+Pour itérer sur l’eau sans recalculer les trois grandes cartes de densité :
+
+```sh
+./gradlew :sanctuary:runGameTest -PsanctuaryDensityMaps=false -PsanctuaryResourceSurvey=off --console=plain
+```
+
+Ces options désactivent seulement les exports de densité et le relevé de
+ressources. Elles gardent les assertions de densité et tous les tests de
+comportement, y compris les cartes et contrôles hydrologiques. Le parcours
+standard conserve les exports complets de densité pour la graine 0.
+
 ## Vérification client facultative
 
 ```sh
@@ -127,6 +173,56 @@ Pour cet essai visuel en monde de développement créatif, comparer la même vue
 Y=63 ni assombrissement d'altitude au passage de Y=32. Les brouillards de l'eau,
 de la météo et des effets d'aveuglement ou d'obscurité doivent rester présents.
 
+## Validation alpha.4 — 8 septembre 2026
+
+Les tests serveur utilisent le preset de production et des mondes neufs. Sur
+la graine `0`, le scénario exige un véritable site `STREAM` ; les autres graines
+vérifient la continuité de chaque cours d’eau qu’elles produisent, sans exiger
+qu’une graine arbitraire soit artificiellement complétée.
+
+| Graine | Spawn naturel | Eau après 200 ticks | Canne à sucre | Chunks FULL inspectés | Raccords d’eau aux frontières |
+| --- | --- | ---: | ---: | ---: | ---: |
+| `0` | `(0, 251, -4)` | 1 938 | 15 | 94 | 253 |
+| `42` | `(-4, 249, -4)` | 1 501 | 24 | 94 | 213 |
+| `8675309` | `(0, 247, 0)` | 1 551 | 12 | 90 | 190 |
+
+Pour la graine `0`, le cours d’eau est à **Y=250**, de **X=−48, Z=48** à
+**X=−20, Z=−20**. Son chemin suit 18 points et relie deux petites poches d’eau.
+Deux petits lacs et quatre étangs sont également présents, en comptant la poche
+de départ du cours d’eau. La graine `42` produit elle aussi un cours d’eau, à
+Y=221, de `(−72, 24)` à `(−60, −40)` en X/Z. Ce sont des observations de ces
+graines, pas un minimum promis pour toutes les îles.
+
+**10/10 tests requis réussissent sur chacune des trois graines**, avec un cours
+d’eau observé sur chacune. Les contrôles comparent chaque bloc d’eau avant et après une simulation réelle
+confirmée par un témoin d’écoulement et l’activité de tous les chunks concernés.
+Les quantités d’eau restent identiques. Les cartes des vrais blocs ont été
+inspectées : les lacs sont arrondis et les chenaux restent continus. Le tracé
+des cours d’eau comporte encore des segments géométriques ; l’appréciation du
+relief, des berges et de leur aspect dans le client reste à faire par le joueur.
+Les cartes masquent la canopée et ne remplacent pas une vue en jeu.
+
+Le plan initial prend **12 060 ms** pour la graine `0` et **8 743 ms** pour `42`
+et **9 755 ms** pour `8675309`, sur le poste Apple M1 à 8 Go utilisé pendant ces
+essais. Il est calculé une seule
+fois par état aléatoire de monde, sans charger les chunks voisins. La préparation
+des 94 chunks FULL de chaque diagnostic est distincte du calcul du plan et
+ne représente pas le travail requis à chaque lancement de partie.
+
+Les trois exécutions serveur réussies ont été suivies de
+`./gradlew check build assemblePack -x :sanctuary:runGameTest` : le serveur déjà
+validé séparément n’est pas relancé à l’identique. Les tests de forme et
+d’hydrologie pure, la compilation et l’assemblage du pack réussissent en 2 s.
+Le JAR ne contient aucune classe de test, et le `.mrpack` contient exactement
+ce même JAR, avec les versions Minecraft et Fabric attendues.
+
+Journaux : `build/alpha4-hydrology-v2-seed0.log` et
+`build/alpha4-validation-seed42.log`, `build/alpha4-validation-seed8675309.log`
+et `build/alpha4-build.log`. Les exports correspondants sont dans
+le dossier `diagnostics` décrit plus haut. Les cartes de densité, inchangées
+par l’hydrologie, ont été exportées lors des premières exécutions de ce ticket ;
+les assertions de densité restent actives pendant chaque validation.
+
 ## Validation alpha.3 — 8 septembre 2026
 
 Sur Java 25 / Minecraft 26.3-pre-2 / Fabric Loader 0.19.5 :