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.