Plan de l'étape 0a.3 : moteur embarqué et engine-cli

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/feuille-de-route.md

@@ -15,7 +15,7 @@ Acquis : socle du dépôt, organisation (ADR 0001, 0003, 0006), source du moteur
 | Sous-étape | Contenu | État | Plan |
 | --- | --- | --- | --- |
 | 0a.2 | Image Docker GNU Backgammon de bureau (compilé depuis le commit 14b6798), 30+ positions de référence dans `tests/reference/` | ⏳ | |
-| 0a.3 | Interface C `engine/include/moteur.h` et `engine-cli` (JSON) | ⏳ | |
+| 0a.3 | Interface C `engine/include/moteur.h` et `engine-cli` (JSON) | 🔄 | `plans/2026-11-02-moteur-embarque.md` |
 | 0a.4 | `make test` compare `engine-cli` aux références | ⏳ | |
 | 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | ⏳ | |
 | Mesures | Pierre relève les mesures sur le Fairphone 4 | ⏳ | |

docs/plans/2026-11-02-moteur-embarque.md

@@ -0,0 +1,86 @@
+# Moteur embarqué : extraction du cœur de gnubg, `moteur.h` et `engine-cli`
+
+- **Date** : 2026-11-02
+- **Étape** : 0a.3
+- **Statut** : en cours
+- **Exécutant** : sous-agent general-purpose, dans un worktree isolé
+
+## Objectif
+
+Le cœur de GNU Backgammon (commit 14b67984737ded0f6de43d63dcb789f729d9b06b,
+ADR 0005) compile comme bibliothèque C autonome, sans GLib ni interface
+graphique, derrière l'interface `engine/include/moteur.h`, et un programme
+`engine-cli` l'interroge en ligne de commande avec une sortie JSON.
+
+## Consignes
+
+1. **Sources** : copie figée des seuls fichiers nécessaires de gnubg dans
+   `engine/gnubg/` (liste de départ et plan d'isolement : ADR 0005), avec un
+   `engine/gnubg/PROVENANCE.md` (commit exact, liste des fichiers, toute
+   modification apportée à un fichier d'origine, signalée aussi en commentaire
+   dans le fichier). Garder les en-têtes de copyright. Modifier les fichiers
+   d'origine le moins possible : préférer un `config.h`, un shim `glib.h` et un
+   en-tête réduit propres à Ustagammon dans `engine/compat/`.
+2. **Données** : `gnubg.weights` et les tables d'équité de match nécessaires
+   (`Kazaross-XG2` par défaut) copiées dans `engine/data/`. Les fichiers
+   générés (`gnubg.wd`, bases `gnubg_os0.bd`, `gnubg_ts0.bd`) sont produits par
+   le build avec les outils officiels (`makeweights`, `makebearoff`) compilés
+   pour l'hôte, dans `build/`, jamais commités. Paramètres de génération
+   identiques à ceux du build officiel de gnubg (`Makefile.am`).
+3. **Interface `engine/include/moteur.h`**, en C, documentée en français,
+   positions au format Position ID + Match ID, sans exposer de type gnubg :
+   - initialisation (chemin des données) et libération ;
+   - coups légaux pour une position et des dés ;
+   - classement des coups avec équités et probabilités, pour un niveau donné
+     (au minimum 0-ply et 2-ply, réglages prédéfinis de gnubg, sans bruit) ;
+   - décision de videau (équités sans double, double/prend, double/passe, et
+     décision), en match et en partie libre (Crawford, Jacoby) ;
+   - évaluation d'une position (5 probabilités et équité) ;
+   - erreurs signalées par code de retour, jamais par `exit`.
+4. **`engine-cli/`** : `engine-cli bestmove <position_id> <match_id> <dés>`
+   (ex. `31`), `engine-cli moves …`, `engine-cli cube <position_id> <match_id>`,
+   `engine-cli eval <position_id> <match_id>`, option de niveau
+   (`--ply 0|2`), sortie JSON sur la sortie standard, erreurs en JSON avec un
+   code de sortie non nul.
+5. **Build** : compilation dans Docker (image `docker/build-c/Dockerfile` sur
+   `debian:trixie`, déjà présente), jamais avec les outils de l'hôte.
+   `make engine` produit `build/engine-cli` et les données ; `make build`
+   l'appelle. Dépendances make correctes : rien n'est recompilé si rien n'a
+   changé (le vérifier : un second `make engine` ne recompile rien). `-j2`
+   maximum. `make clean` supprime `build/`. Les nouvelles cibles apparaissent
+   dans `make help`.
+6. **Tests** (`tests/test_engine.sh`, lancé par `make test`, qui suppose
+   `make engine` déjà fait ou le lance) : position de départ (Position ID
+   `4HPwATDgc/ABMA`) avec plusieurs jets d'ouverture dont le meilleur coup est
+   connu sans ambiguïté (ex. 31 : 8/5 6/5), nombre de coups légaux d'une
+   position connue, symétrie et bornes des probabilités, gestion d'un
+   identifiant invalide, décision de videau d'une position manifestement
+   « pas de double ». La comparaison systématique au gnubg de bureau est
+   l'étape suivante (0a.4), pas celle-ci.
+7. **Mesure** : temps de `bestmove` à 0-ply et 2-ply sur la position de départ,
+   rapporté (pas de seuil à tenir sur le PC).
+
+Contraintes :
+- respecter `CLAUDE.md` (français, `-j2`, aucune installation hors Docker) ;
+- pas de threads (USE_MULTITHREAD désactivé) ; C générique sur x86 pour
+  commencer (pas de SSE/AVX obligatoire), en gardant le chemin NEON possible ;
+- ne pas copier de code de CBG ; s'en inspirer est permis (clone en lecture
+  seule indiqué dans la consigne de l'agent), en le citant ;
+- `make lint` et `make test` doivent passer ; commits petits, en français ;
+- ne pas pousser ni créer de merge request ;
+- ne rien simuler : un échec est rapporté avec sa cause.
+
+Rapport attendu : ce qui a été fait, fichiers repris et modifiés, commandes de
+vérification, temps de compilation, tailles des données générées, temps de
+calcul mesurés, difficultés, écarts au plan.
+
+## Critères de réussite
+
+- `make engine && ./build/engine-cli bestmove 4HPwATDgc/ABMA cAkAAAAAAAAA 31`
+  affiche le meilleur coup en JSON (8/5 6/5).
+- Un second `make engine` ne recompile rien.
+- `make lint` et `make test` passent.
+
+## Résultat
+
+À remplir à la clôture.