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

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.