Ransom-s-wake/docs/adr/0009-player-knowledge-driven-progression.md

# 0009 — Progression pilotée par les connaissances et actions du joueur

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

## Contexte

L'entreprise qui engage le joueur sait qu'elle poursuit un trésor, mais présente
la première mission comme la récupération du travail du précédent opérateur.
Le monde possède donc une vérité, le commanditaire possède des intentions et le
joueur ne dispose au départ que d'une version partielle ou mensongère.

Une épave peut être localisée, identifiée, examinée, ouverte et revisitée sans
que son objectif principal ait été sécurisé. Débloquer la suite dès la
découverte du navire rendrait la récupération de l'objet ou de l'indice
facultative et contredirait la boucle de campagne. À l'inverse, utiliser les
secrets du contenu pour colorer une icône ou construire un objectif visible
révélerait indirectement une information que le joueur n'a pas encore obtenue.

## Décision

### Trois niveaux d'information

Le modèle sépare explicitement :

1. **La vérité du contenu** : identité réelle d'une épave, objets présents,
   chronologie, motivations et liens narratifs. Elle réside dans les définitions
   de contenu et n'est jamais envoyée telle quelle à la présentation.
2. **Les termes visibles du contrat** : `ContractTerms` contient uniquement le
   commanditaire affiché, les informations communiquées au joueur, l'objectif
   officiel, le paiement et les prérequis annoncés.
3. **Les connaissances du joueur** : `MissionProgress` contient uniquement les
   faits observés, révélations acquises, objectifs connus, épaves localisées,
   identités établies et activités découvertes.

Les intentions cachées de l'entreprise et les véritables étapes de progression
sont décrites dans des `CampaignObjectiveDefinition` distinctes de
`ContractTerms`. Une définition peut rester invisible, devenir connue après une
révélation ou n'exister que comme règle interne reliant des faits.

La sauvegarde persiste les identifiants et états nécessaires à la progression,
mais l'application expose à chaque écran une projection filtrée par les
connaissances du joueur. Le fait qu'une donnée existe dans le contenu ou le
format de sauvegarde ne l'autorise pas à traverser le contrat de présentation.

### Faits, objectifs et révélations

Un fait est un événement métier idempotent déjà établi, par exemple :

- une zone d'écho a été obtenue ;
- une épave a été localisée ;
- une preuve a été observée ;
- une identité a été établie ;
- un accès a été ouvert ;
- un objet se trouve sur le site, dans le panier, dans la cale ou a été remis ;
- des données récupérées ont été analysées.

Une révélation est une nouvelle connaissance produite par une commande validée
et ses prérequis, pas un texte déclenché par l'interface. Elle peut rendre
visible un objectif, une activité, une identité ou une nouvelle zone probable.

Un `CampaignObjectiveDefinition` exprime des prérequis typés et un effet. La
progression les évalue après les commandes applicatives. Elle ne dépend ni de
la scène ouverte, ni d'un libellé, ni d'une comparaison effectuée dans le HUD.
Les mêmes faits ne produisent une révélation qu'une seule fois.

Une hypothèse de joueur, telle que la cible présumée dans le dossier, reste
révisable et n'est pas un fait d'identification. Elle ne valide ni le contrat,
ni une étape cachée.

### Localisation distincte de l'accomplissement

Localiser ou identifier une épave ne satisfait pas automatiquement l'objectif
qui y conduit. Chaque étape requiert le dernier fait métier prévu par sa
définition : récupération, sécurisation dans la cale, analyse, lecture, remise
ou autre action explicitement nommée.

Pour la première mission de la verticale :

1. le contrat visible demande de retrouver le navire de prospection et son
   module de cartographie ;
2. la localisation rend l'épave revisitable, sans révéler la piste suivante ;
3. l'identification confirme le navire, sans terminer la mission ;
4. les objets placés dans le panier restent provisoires ;
5. le treuillage puis `EmptyBasket` sécurisent le module et ses données dans la
   cale ;
6. `AnalyzeRecoveredData` révèle la zone probable du U-Boot ;
7. la remise physique du module et le paiement restent des actions séparées.

La copie analysable des données demeure acquise après son transfert, même si le
module physique est remis ensuite. Les intentions réelles de l'entreprise ne
deviennent visibles que par une révélation narrative prévue, pas par le simple
accomplissement technique d'un objectif caché.

### Projection de la carte

La carte globale reçoit une projection de `MissionProgress` et applique les
états suivants :

- une vérité de contenu non localisée n'est pas affichée comme épave ;
- une zone d'écho connue reste une zone approximative ;
- une épave localisée sans identité établie est nommée
  `Épave non identifiée` ;
- une épave identifiée utilise le nom du navire ;
- l'icône est colorée lorsqu'au moins une activité connue et réalisable reste à
  accomplir ;
- l'icône devient monochrome lorsque toutes les activités connues sont
  terminées et qu'aucun objectif connu n'y demande une action.

Une activité cachée ne colore pas l'icône : cela divulguerait son existence.
Lorsqu'une révélation la rend connue, la projection peut redevenir colorée.
Cette couleur est une information de présentation dérivée d'un état métier
filtré ; elle n'est pas sauvegardée comme vérité indépendante.

### Responsabilités

Le domaine possède faits, prérequis, états d'objets et transitions de
progression. L'application exécute les commandes, publie les révélations et
construit les projections autorisées. Le monde produit uniquement des
observations et interactions. La présentation affiche les projections et émet
des commandes ; elle ne lit jamais directement les définitions cachées.

Les tests de contenu vérifient au minimum :

- que le contrat visible ne référence pas une révélation prématurée ;
- que chaque objectif de campagne possède une suite de prérequis atteignable ;
- que la campagne reste terminable sans le pack d'archives facultatif ;
- que localiser ou identifier seul la première épave ne révèle pas le U-Boot ;
- que l'analyse des données sécurisées le révèle une seule fois ;
- que chaque leurre possède des faits cohérents et une contradiction
  découvrable ;
- qu'aucune projection ne contient un fait ou une activité encore caché.

## Conséquences

- L'entreprise peut mentir sans dupliquer une seconde mission ou risquer que
  l'interface expose son véritable objectif.
- Une épave découverte reste facile à retrouver, mais sa découverte ne court-
  circuite pas la récupération et l'analyse.
- La carte peut revenir sur une épave lorsqu'une nouvelle activité y est
  révélée, sans modifier son historique d'exploration.
- Ajouter une révélation exige des prérequis typés et un test de contenu, ce qui
  augmente le travail d'auteur mais réduit les blocages narratifs.
- Les écrans reçoivent des projections dédiées plutôt que les ressources de
  contenu complètes.
- Les états de couleur et les libellés de carte restent dérivés et ne créent
  pas une source de vérité concurrente.

## Alternatives considérées

- **Mettre objectifs visibles et cachés dans `ContractTerms`** : rejeté, car un
  écran ou un export de contrat pourrait révéler les intentions de l'entreprise.
- **Utiliser des booléens globaux sans propriétaire** : rejeté, car leur origine,
  leur ordre et leurs prérequis seraient implicites.
- **Débloquer la suite à l'identification de l'épave** : rejeté, car l'objet ou
  l'indice demandé deviendrait facultatif.
- **Laisser l'UI déduire l'objectif suivant** : rejeté, car la présentation
  calculerait une règle de campagne.
- **Colorer une épave tant qu'elle contient un secret quelconque** : rejeté,
  car la carte divulguerait les activités inconnues du joueur.
- **Valider immédiatement la cible présumée** : rejeté, car l'hypothèse doit
  rester révisable et la déduction ne doit pas devenir un quiz d'interface.