# Moteur pour l'analyse et les niveaux (1a)

- **Date** : 2026-11-03
- **Étape** : 1a (`docs/etape-1.md`)
- **Statut** : en cours
- **Exécutant** : sous-agent general-purpose, dans un worktree

## Objectif

Donner au domaine tout ce dont l'étape 1 a besoin du moteur : niveaux de jeu de
l'ordinateur, analyse d'un coup joué et d'une décision de videau, chance d'un
jet. Tout vient de GNU Backgammon, comparé à gnubg de bureau.

## Consignes

ADR 0005, 0007 et la méthode de comparaison de `tests/reference/` (README).
Ne pas modifier `engine/gnubg/` (copie fidèle). Pas de nouvelle dépendance.

1. **Niveaux de jeu** : les niveaux de GNU Backgammon (débutant, amateur,
   intermédiaire, avancé, expert, champion du monde…), avec leurs plis, filtres
   et bruit, repris des réglages prédéfinis de gnubg (pas inventés). Le bruit
   doit être déterministe (option « deterministic » de gnubg) pour que les
   tests soient reproductibles. API C (`engine.h`), `engine-cli`, adaptateur
   WebAssembly et interface `Engine` du domaine (ajout seulement : ne pas
   toucher au reste de `app/src/domain/game/`, qu'un autre agent modifie).
2. **Analyse d'un coup joué** : pour une position, un jet et un coup joué,
   l'équité du coup joué, celle du meilleur coup, l'écart, et le rang du coup
   joué, au niveau d'analyse demandé (comme l'analyse de partie de gnubg).
3. **Analyse d'une décision de videau** : équités sans double, double/prend,
   double/passe, et l'écart de la décision prise (double, pas de double,
   prendre, passer), comme gnubg.
4. **Chance d'un jet** : la chance (luck) d'un jet au sens de gnubg, et son
   classement (très chanceux… très malchanceux) avec les seuils de gnubg.
5. **Seuils d'appréciation** : exposer les seuils de gnubg (douteux, mauvais,
   très mauvais) comme constantes documentées ; l'interface les traduira.
6. **Références** : ajouter des positions de référence évaluées par gnubg de
   bureau (Docker existant, `make reference`) pour l'analyse d'un coup, d'une
   décision de videau et la chance, comparées par `make test` (natif et
   WebAssembly) avec la tolérance existante. Les niveaux avec bruit : vérifier
   au moins que le coup choisi est reproductible et identique à celui de gnubg
   de bureau sur quelques positions.
7. Glossaire : fiches pour les nouveaux termes (niveau, chance, appréciation,
   équité si absente…), reliées au code.
8. Mesurer sous Node (`make bench` ou équivalent) le temps d'une analyse de
   coup au niveau prévu pour le conseil du maître (2 plis), pour vérifier
   qu'elle tient en arrière-plan sur le téléphone (repère : ADR 0009).

Machine ancienne : `-j2`, ne recompiler le moteur que si nécessaire.
`make lint` et `make test` doivent passer. Commits fréquents ; `git add` avec
chemins explicites ; ne pas pousser, pas de MR.

## Critères de réussite

- `engine-cli` répond aux nouvelles commandes en JSON.
- Les nouvelles références concordent avec gnubg de bureau, natif et WebAssembly.
- `make lint` et `make test` passent.

## Résultat

Réalisé le 2026-11-03, branche `moteur-analyse`. Critères tenus : nouvelles
commandes d'`engine-cli` en JSON, références concordantes en natif et en
WebAssembly, `make lint` et `make test` au vert.

- **Niveaux** : les neuf réglages prédéfinis de gnubg 1.08 (`aecSettings`) :
  `beginner`, `casual`, `intermediate`, `advanced` (0 pli, bruit 0,06 / 0,05 /
  0,04 / 0,015, déterministe), puis `0ply` à `4ply` sans bruit (anciens noms
  gnubg : « expert » = 0 pli, « world class » = 2 plis). Coup choisi comme
  l'ordinateur de gnubg (`ComputerTurn` : sans analyse, puis
  `RefreshMoveList`). `engine.h` (`engine_level_*`), `engine-cli --level` et
  `levels`, `Engine.levelMove` et `levelCubeDecision`.
- **Analyses** : `engine_analyse_move` (comme `AnalyzeMove` : coup joué
  évalué au niveau le plus profond, rang, perte, appréciation),
  `engine_analyse_cube` (pas de double, double, prendre, passer ; pertes de
  `AnalyzeMove`), `engine_luck_of` (portage de `LuckNormal` et `LuckFirst`
  d'`analysis.c`, fichier non repris dans `engine/gnubg/`). Commandes
  `analysemove`, `analysecube`, `luck` ; `Engine.analyseMove`, `analyseCube`,
  `luck`.
- **Seuils** : ceux de gnubg, `gnubg.c` : appréciation 0,03 / 0,06 / 0,12
  (et non 0,04 / 0,08 / 0,16 comme proposé dans `docs/etape-1.md`) ; chance
  0,3 / 0,6. Constantes dans `engine.h` et `SKILL_THRESHOLDS`,
  `LUCK_THRESHOLDS` dans `engine.ts`, vérifiées égales par un test.
- **Références** : `tests/reference/analyses.json` (16 coups joués, 14
  décisions de videau, 7 cas de niveaux), résultats dans `analysis/`, produits
  par l'analyse de partie de gnubg de bureau (« analyse game ») ; comparés par
  `compare.py`. Écart maximal 1,64e-3 (`move-jacoby`, 2 plis), tolérance
  inchangée (0,002).
- **Écart au plan, décision à valider** : le moteur vide le cache
  d'évaluation de gnubg à chaque calcul. Une recherche à 2 plis avec élagage
  y laisse des évaluations à 0 pli des réseaux d'élagage, que les calculs à
  0 pli suivants reprennent (même défaut dans gnubg de bureau : jusqu'à
  2,5e-2 d'écart sur la chance). Coût : environ 3 ms par appel sur le PC.
- **Mesure** (`make bench`, Node 18, i5-2450M) : analyse du coup joué à
  2 plis, médiane 76 ms, maximum 451 ms (`opening-21`) ; seuil 3 s. Aussi
  dans `bench.html` pour le téléphone.
- **Glossaire** : Niveau de jeu (`Level`), Appréciation (`Skill`), Chance
  (`Luck`).