Ransom-s-wake/docs/adr/0008-composition-owned-service-lifetimes.md

# 0008 — Services possédés et injectés par la composition

- Statut : accepté
- Date : 2026-08-10
- Remplace : aucun

## Contexte

Les réglages, l'accès aux sauvegardes, l'audio et une campagne chargée doivent
survivre à plusieurs changements d'écran. Godot permet de résoudre ce besoin
avec des autoloads, des singletons statiques ou un bus de signaux global. Ces
solutions rendent toutefois les dépendances accessibles depuis n'importe quel
script, masquent leur durée de vie et compliquent l'isolation des tests.

La verticale possède déjà une couche `composition`, seule autorisée à connaître
les implémentations concrètes de toutes les autres couches. Elle peut donc
maintenir les objets de longue durée sans les transformer en état global.

## Décision

### Aucun accès global de gameplay

Aucun autoload personnalisé, singleton statique, registre global, service
locator ou bus de signaux global n'est introduit pour le gameplay de la
verticale. Une longue durée de vie ne suffit pas à justifier un accès global.

Les singletons fournis par Godot restent des détails de plateforme. Seuls les
adaptateurs autorisés les utilisent ; le domaine et les cas d'usage ne lisent
pas directement `Input`, `SceneTree`, `AudioServer`, les fichiers ou l'horloge.

### Racine persistante

`vertical_slice_root.tscn` est la racine de composition persistante de la
verticale. Elle crée les implémentations concrètes, les relie à leurs ports et
possède un emplacement destiné à l'écran ou au monde actif. Une transition
remplace ce contenu enfant sans remplacer la racine et sans demander aux scènes
de rechercher des services dans l'arbre.

La composition est responsable de :

- construire les adaptateurs d'infrastructure et les cas d'usage ;
- charger ou créer l'état de campagne ;
- injecter les contrats requis avant d'activer une scène ;
- connecter les sorties d'une scène aux commandes applicatives appropriées ;
- déconnecter et libérer les dépendances de portée courte lors d'une
  transition ;
- choisir l'écran suivant à partir d'un résultat applicatif explicite.

Une scène ne parcourt pas ses parents, `/root`, un groupe global ou un chemin
absolu afin de découvrir une dépendance. Elle expose une méthode de
configuration, des propriétés typées ou un constructeur de composition
explicite. L'absence d'une dépendance requise échoue immédiatement en
développement et dans les tests de chargement.

### Durées de vie

Trois portées sont distinguées :

1. **Application** : réglages, localisation, adaptateurs d'entrée et d'audio,
   horloge de plateforme, accès au stockage et liste des sauvegardes. Ils vivent
   tant que la racine existe.
2. **Campagne** : `CampaignState`, progression de mission et cas d'usage liés à
   une partie. Ils sont créés lors d'une nouvelle partie ou d'un chargement et
   détruits lors de sa fermeture ou de son remplacement.
3. **Plongée** : `ResolvedDiveRules`, `DiveSession`, acteurs, adaptateurs
   physiques et service sonar courant. Ils sont créés au départ d'une plongée
   et détruits après production de son résultat immuable.

Un objet de portée longue peut fournir un port à une portée plus courte. Il ne
conserve pas en retour une référence implicite vers un acteur ou une scène déjà
détruite. Les connexions de signaux suivent la même propriété et sont retirées
avec leur portée.

Les services d'infrastructure ne deviennent pas propriétaires des règles. Par
exemple, le dépôt de sauvegarde écrit un document demandé par un cas d'usage ;
il ne décide pas quand une mission progresse ou combien d'argent est gagné.

### Navigation et communications

La présentation traduit une interaction en commande ou appel de cas d'usage.
Elle consomme ensuite un résultat, un snapshot ou un événement typé. Elle ne
modifie jamais directement l'état de campagne ou un acteur du monde.

Les événements locaux peuvent utiliser les signaux Godot entre objets déjà
reliés par la composition. Un signal décrit un fait passé et ne sert pas de
canal global anonyme. Une intention reste une commande nommée.

Chaque écran et composition de plongée peut être instancié dans un test avec de
faux ports, sans charger une campagne réelle, le stockage de la machine ou tous
les autres écrans.

### Évolution

Tout nouvel autoload, accès statique global ou exception durable à cette
politique exige un ADR qui précise son propriétaire, sa durée de vie, son API,
sa stratégie de réinitialisation et son isolation en test.

## Conséquences

- Les dépendances et leur durée de vie sont visibles à l'endroit où les scènes
  sont assemblées.
- Un changement d'écran ne détruit pas les services applicatifs nécessaires à
  la session.
- Une nouvelle campagne peut remplacer proprement la précédente sans conserver
  ses signaux, caches ou acteurs.
- Les écrans sont testables avec des doubles légers et ne dépendent pas d'un
  ordre d'initialisation d'autoloads.
- La composition contient davantage de code d'assemblage explicite et doit
  rester distincte des règles de gameplay.
- Les transitions doivent libérer leurs objets de portée courte et seront
  couvertes par des tests d'intégration et de fuite de nœuds.
- Les fonctionnalités transversales passent par des ports nommés plutôt que par
  une commodité globale.

## Alternatives considérées

- **Un autoload par service** : rejeté, car sauvegarde, campagne, audio et
  navigation deviendraient accessibles et mutables depuis toutes les couches.
- **Un unique `GameManager` autoload** : rejeté, car il concentrerait
  assemblage, navigation et règles dans un propriétaire générique.
- **Un bus d'événements global** : rejeté, car producteurs et consommateurs
  seraient reliés par des noms implicites et des durées de vie difficiles à
  vérifier.
- **Remplacer toute la scène courante à chaque écran** : rejeté comme
  navigation principale, car les services persistants devraient alors être
  globaux ou reconstruits avec un état dupliqué.
- **Rechercher les services dans les parents ou par groupe Godot** : rejeté,
  car la dépendance resterait cachée et dépendrait de la forme de l'arbre.