Implement production vertical slice foundation

docs/adr/0006-sonar-contract-and-acquisition-gate.md

@@ -0,0 +1,149 @@
+# 0006 — Contrat sonar commun et porte de sélection de l'acquisition
+
+- Statut : accepté
+- Date : 2026-08-10
+- Remplace : aucun
+
+## Contexte
+
+Le POC B a validé une représentation bathymétrique continue, révélée
+progressivement, qui rend le relief navigable. Son acquisition principale
+utilise toutefois des sondes verticales disposées devant le véhicule et peut
+montrer le dessus de surfaces qu'un faisceau frontal ne verrait pas. Une passe
+frontale distincte détecte les anomalies métalliques. Cette combinaison est
+lisible, mais elle n'est ni une simulation acoustique fidèle, ni une
+implémentation de production.
+
+Une acquisition entièrement frontale serait plus cohérente avec la position du
+capteur, mais risque de produire des trous, de perdre la continuité du relief ou
+de rendre le sonar à nouveau difficile à interpréter. Le comportement validé du
+POC doit donc rester la référence pendant l'expérience, sans importer son code
+jetable dans la production.
+
+L'acquisition, la reconstruction et la présentation doivent pouvoir évoluer
+séparément. Sinon, comparer deux méthodes imposerait aussi de réécrire le
+renderer et rendrait leurs résultats impossibles à évaluer équitablement.
+
+## Décision
+
+### Contrat commun
+
+Toutes les acquisitions candidates produisent le même `SonarScan`. Celui-ci
+contient au minimum :
+
+- un identifiant de scan et l'identifiant de la session ;
+- le transform du capteur figé à l'émission ;
+- la portée, les ouvertures et la durée de révélation ;
+- les dimensions logiques de la grille ;
+- un `SonarSampleBuffer` immuable ;
+- des `SonarContact` distincts ;
+- l'échelle de couleur et les valeurs réelles minimales et maximales ;
+- l'état prêt, capture, révélation ou récupération.
+
+Le repère du scan est figé au déclenchement, avec son origine au capteur, +X à
+tribord, +Y vers le haut et +Z vers l'avant, en mètres. L'adaptateur du monde
+convertit le -Z avant de Godot vers ce contrat. Aucun consommateur ne déduit ou
+réinterprète cette convention.
+
+`SonarSampleBuffer` encapsule des tableaux parallèles compacts de positions,
+normales, intensités, élévations réelles, matériaux et statuts d'observation.
+Un même index décrit un échantillon ; la ligne et la colonne sont dérivées des
+dimensions de grille. Un accesseur typé comme `sample_at(row, column)` masque la
+représentation interne et vérifie les bornes. Le buffer devient immuable avant
+sa publication.
+
+Les contacts ne sont pas obtenus en moyennant tous les retours d'un matériau.
+Un clustering spatial déterministe produit plusieurs `SonarContact`, chacun
+avec une identité, un matériau, un centre, des limites, une intensité maximale
+et un nombre d'échantillons.
+
+### Acquisition, reconstruction et présentation
+
+L'adaptateur sonar du monde possède l'acquisition physique. Le service
+applicatif valide et structure les échantillons ainsi que les contacts. La
+présentation reconstruit et affiche le relief à partir du scan publié ; elle ne
+fait ni classification métier, ni détection de mission.
+
+La palette d'altitude reste relative au scan pour préserver le contraste, mais
+les élévations réelles en mètres sont conservées et une légende chiffrée indique
+l'échelle employée. Noir représente l'inconnu, pas une profondeur arbitraire.
+
+Un seul scan courant et un seul scan précédent en fondu existent au maximum.
+La vue compacte et la vue agrandie affichent la même texture produite par un
+renderer unique. Elles ne reconstruisent pas deux maillages indépendants.
+
+La révélation de référence dure 2,5 secondes, puis la récupération 0,35 seconde.
+Une nouvelle demande n'est pas mise en file pendant cette séquence. Ces valeurs
+restent configurables et testées, mais leur temporalité appartient au service
+sonar, pas au HUD.
+
+### Porte de sélection
+
+Deux acquisitions sont réécrites derrière ce contrat uniquement pendant une
+calibration bornée :
+
+1. la méthode de référence inspirée du POC B, combinant une grille
+   bathymétrique lisible et une détection frontale des anomalies ;
+2. une méthode par faisceau frontal, reconstruite dans le même buffer.
+
+La comparaison utilise les mêmes poses de capteur, scènes, portées, dimensions
+de sortie et cas de test : pente, chenal, rupture de relief, épave, ouverture,
+zones masquées et plusieurs contacts métalliques séparés. Elle mesure au
+minimum :
+
+- la compréhension du relief et d'un passage par des testeurs ;
+- la détection de l'épave et de plusieurs anomalies sans fusion incorrecte ;
+- la stabilité face aux trous et aux rotations du véhicule ;
+- le coût CPU moyen et maximal, les allocations et le coût de reconstruction ;
+- la conservation de l'effet de révélation validé.
+
+Le faisceau frontal n'est retenu que s'il atteint une lisibilité et une
+stabilité au moins équivalentes à la réécriture de référence dans les budgets
+de la verticale. Dans le cas contraire, la méthode inspirée du POC devient
+l'acquisition de production. La fidélité acoustique ne prime pas sur la
+capacité du joueur à lire le relief et à naviguer.
+
+La porte produit un compte rendu et un ADR de sélection. Après cette décision,
+une seule acquisition reste autoritaire dans `game/`. L'autre implémentation
+n'est pas maintenue comme chemin de secours ; les scènes, données de calibration
+et résultats comparatifs peuvent être conservés pour prévenir les régressions.
+
+### Persistance
+
+Ni les échantillons bruts, ni le buffer, ni le maillage, ni les couleurs d'un
+scan sous-marin ne sont sauvegardés. La campagne persiste seulement les faits
+sémantiques sécurisés : zones d'écho de surface, épaves localisées, identités et
+observations. Une sauvegarde ne tente jamais de reconstruire une image sonar en
+cours de révélation.
+
+## Conséquences
+
+- Le comportement apprécié dans le POC reste disponible comme référence et
+  issue sûre sans promouvoir son code.
+- Une acquisition peut être remplacée sans modifier le renderer, le HUD ou les
+  règles de mission.
+- Le buffer compact limite les allocations, mais demande un accesseur typé et
+  des tests d'alignement de tous les tableaux.
+- Les conversions de coordonnées sont explicites et testables.
+- Plusieurs anomalies restent distinctes, contrairement à la moyenne globale
+  provisoire du POC.
+- Le rendu sonar possède une seule reconstruction et une seule texture, ce qui
+  réduit les divergences entre les deux tailles d'affichage.
+- La calibration ajoute un coût court à la tranche sonar, borné par une porte
+  de décision et supprimant ensuite le chemin perdant.
+
+## Alternatives considérées
+
+- **Copier le sonar du POC B dans la production** : rejeté, car cela
+  introduirait ses dépendances, sa reconstruction complète et ses contrats
+  implicites dans `game/`.
+- **Choisir immédiatement le faisceau frontal** : rejeté, car sa vraisemblance
+  ne garantit pas la lisibilité déjà difficile à obtenir.
+- **Conserver durablement les deux acquisitions** : rejeté, car deux
+  implémentations autoritaires doubleraient réglages, tests et risques de
+  régression.
+- **Publier directement des nœuds, maillages ou dictionnaires depuis le monde** :
+  rejeté, car acquisition et présentation resteraient couplées.
+- **Sauvegarder la carte sonar brute** : rejeté, car elle représente une vue
+  temporaire dérivée du monde et alourdirait le format sans bénéfice de
+  progression.