Ustagammon/docs/plans/2026-11-03-moteur-analyse.md

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).