Synchronize verified Sanctuary beta.092 sources and release documentation

docs/loading-cache-beta064.md

@@ -0,0 +1,138 @@
+# beta.064 — cache des plans et préchargement natif
+
+Branche `codex/loading-cache-beta064`. Reprend l'audit beta.063 et conserve les
+travaux préexistants (HUD du resource pack et documentation des capes inclus).
+
+## Contrat du cache dérivé
+
+Le cache est facultatif et reconstructible dans `cache/sanctuary-plans-v1/`
+sous le dossier du monde. Il ne change aucun chunk, aucun journal d'expansion,
+aucune donnée d'habitant ni les paramètres du générateur. Un ancien monde sans
+cache suit exactement le calcul existant et remplit le cache ; supprimer ce
+répertoire rétablit le même calcul. Pas de migration de sauvegarde nécessaire.
+
+Les clés comprennent la graine, le générateur et ses paramètres, l'option
+structures, les versions des mods et toutes les couches de ressources de
+génération (`worldgen`, `structure`, `tags`, `dimension`, `dimension_type`) et
+les modèles NBT locaux de `generated/`. Les
+plans structurels incluent aussi la liste des îles concernées. Un changement
+invalide le cache ; une entrée illisible, incomplète ou dont l'empreinte diffère
+est ignorée puis recalculée. Écriture temporaire, synchronisation et renommage
+atomique. Aucun objet Minecraft vivant, monde, chunk ou état RNG n'est sérialisé.
+Les index dérivés sont reconstruits à partir des géométries validées.
+
+Le cache couvre l'hydrologie régionale (eau, terrasses, écoulements et lave),
+les traversées, salles souterraines, sanctuaire minier, ruines et patrimoine de
+la racine, ainsi que les pièces natives du village, des mines, des temples et
+des ruines asséchées. Ces dernières utilisent le NBT natif de Minecraft, dont
+la lecture doit restituer exactement la même écriture ; sinon elles sont
+recalculées. Les pièces restaurées appartiennent au nouveau serveur, sans
+réutiliser les objets du serveur précédent. Le lecteur vanilla des pièces jigsaw
+recalcule leurs limites à partir du modèle et perd les extensions réservées aux
+jonctions : le cache réapplique ces limites enregistrées, puis exige une égalité
+NBT complète. Cette correction reste locale au lecteur du cache, sans mixin de
+chargement des chunks ni modification des structures sauvegardées.
+
+Les plans aériens conservent leur journal persistant existant, qui fait
+également autorité. Les anciennes générations et les villes des expansions
+conservent leurs planificateurs actuels ; la livraison cible les plans de
+l'île Sanctuary actuelle (`generation24`, terrain alpha.30.7).
+
+## Préchargement
+
+Texte et étapes issus du travail réel du serveur intégré, fond uni et graphisme
+Minecraft. Aucun portail du Nether dans cette préparation. L'introduction,
+Hello World, sa durée, sa musique et le flash restent inchangés. Les étapes de
+calcul n'affichent pas de pourcentage inventé ; Minecraft fournit sa progression
+réelle des chunks dès qu'elle est disponible. La préparation locale affiche
+les étapes publiées par le serveur intégré avant même l'admission réseau.
+Un client distant ne reçoit pas de faux état d'un serveur qui n'a pas encore
+ouvert sa connexion : il conserve les étapes natives du téléchargement.
+Le transport dimensionnel par portail reste un écran Minecraft distinct.
+
+Les libellés FR/EN suivent le travail : vérification/lecture du cache, eau et
+lave, traversées, salles, sanctuaire minier, ruines, patrimoine, îlots aériens,
+village, mines, temples, enregistrement et point d'arrivée. Deux lignes
+centrées sur fond uni remplacent l'attente générique ; aucune texture ajoutée.
+La progression native des chunks et ses conditions de fermeture restent gérées
+par Minecraft. Aucun nouveau bouton d'annulation ne force un arrêt au milieu
+d'un calcul ou d'une écriture.
+
+## Vérification reproductible
+
+Client natif 26.3-pre-2, serveur intégré uniquement, monde de développement
+neuf : graine `42`, île moyenne de diamètre `724`, structures actives,
+distances de rendu et simulation de `8`. Première arrivée avec les 29,5 secondes
+d’introduction complètes. Ensuite réouverture du même monde, puis remplacement
+d’une seule entrée de cache par un contenu tronqué et nouvelle réouverture.
+
+Le contrôle compare les géométries des plans, l’eau et la lave, les index par
+colonne et par chunk, les écritures de blocs et de butin des renderers et une
+grille de points de protection. La lecture des pièces natives exige une égalité
+NBT complète après restauration. Les essais de fichiers couvrent l’absence,
+le changement de clé, une copie sous une mauvaise identité, un checksum faux,
+une validation refusée et un gzip tronqué. Chaque refus retombe sur le calcul.
+
+L’écran est rendu par Minecraft en FR/EN pour inspection visuelle. Les phases
+observées pendant le véritable démarrage sont enregistrées indépendamment des
+ticks du client, qui ne tournent pas pendant sa première boucle de chargement.
+Mesure locale du 15 septembre 2026, même scénario que l’audit beta.063 :
+
+| Parcours | Durée jusqu’au jeu |
+|---|---:|
+| Première création, cache vide, introduction complète | 122,255 s |
+| Réouverture avec cache | 2,126 s |
+| Entrée structurelle corrompue, recalcul automatique | 39,177 s |
+| Référence beta.063, réouverture sans cache | 58,701 s |
+
+Il s’agit d’une mesure sur cette machine et cette graine, pas d’une garantie de
+durée. Le cache accélère surtout les réouvertures ; un monde neuf doit toujours
+calculer ses plans et préparer ses chunks. Les mises à jour de version ou de
+ressources invalident volontairement les anciennes entrées. La première
+réouverture d’un ancien monde sans cache sert à le remplir.
+
+Réouverture : **3 lectures réussies, 0 échec, 0 écriture**. Récupération :
+**3 lectures réussies, 1 échec attendu, 1 remplacement**. Comparaison identique
+des **217 053 écritures de blocs/butin** et de 93 150 points de protection,
+ainsi que des plans et des index fluides. Les 17 étapes utiles du scénario ont
+été observées ; les libellés FR/EN et les captures natives sont vérifiés.
+Preuves locales : `build/loading064-client.log`,
+`build/loading064-evidence/timings.json` et captures dans le même dossier.
+
+
+```sh
+JAVA_HOME=/Users/koka/Library/Java/JavaVirtualMachines/temurin-25.jdk/Contents/Home \
+./gradlew :sanctuary:runClientGameTest -x :sanctuary:runGameTest \
+  -PsanctuaryClientTests=true -PsanctuaryLoading064ClientTests=true \
+  -PsanctuaryQuickTests=true -PsanctuaryClientNoVsync=true
+```
+
+Le drapeau de test rapide facilite l’automatisation ; ce scénario réactive
+explicitement l’introduction longue avant la validation de Hello World.
+Aucun serveur dédié lancé, aucune EULA acceptée, aucun monde personnel modifié.
+
+
+## Livraison locale
+
+`./gradlew check build assemblePack assembleTestPack` réussi en **2 min 21 s**,
+**122 tâches**, avec `-x :sanctuary:runGameTest -PsanctuaryClientTests=true
+-PsanctuaryQuickTests=true`. Le parcours natif plat/classique, avec Sanctuary
+activé/désactivé puis réouverture, passe ses **8 ouvertures** en 53 s
+(`build/gameplay064-client.log`). Les tests dédiés exclus restent remplacés ici
+par les essais du serveur intégré, conformément au refus d’accepter leur EULA.
+
+Archives comparées à beta.063 : **1 645 classes conformes à la compilation**,
+ressources FR/EN, mixins, métadonnées, dépendances exactes et absence de tests
+dans le mod. Les classes de Hello World, de l’introduction, les sons, les
+textures, les données de génération et JEI sont inchangés. Les variantes
+normal/Test diffèrent uniquement par le module de test rapide et leur nom.
+Les anciens MRpacks beta.063 conservent leurs empreintes originales.
+
+- [Pack normal beta.064](../build/Sanctuary-beta.064.mrpack), 5720330 octets.
+  SHA-256 : `c05b78e2caf27d52cb318979ee66e19e5bca9c90673f8868ae50f85f0e2ff2c0`.
+- [Monde plat rapide beta.064](../build/Sanctuary-Test-beta.064.mrpack), 5739264 octets.
+  SHA-256 : `962800291875ab5bebda1abaedc798e7cf110ba0ef13ac168a0b85b3b2c19d24`.
+
+Reçu : `build/loading064-artifact.json`. Aucun canal publié ni instance Prism
+modifié. Les optimisations de sondages partagés et de parallélisation de la
+première création proposées dans l’audit restent des tickets ultérieurs.