From d0f44b689b3cbd4572691a8183d89e2492276a69 Mon Sep 17 00:00:00 2001 From: Pierre MARTIN Date: Mon, 2 Nov 2026 13:33:41 +0100 Subject: [PATCH] =?UTF-8?q?Plan=20de=20l'=C3=A9tape=200a.3=20:=20moteur=20?= =?UTF-8?q?embarqu=C3=A9=20et=20engine-cli?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- .gitignore | 3 + docs/feuille-de-route.md | 2 +- docs/plans/2026-11-02-moteur-embarque.md | 86 ++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-11-02-moteur-embarque.md diff --git a/.gitignore b/.gitignore index a5e92f5..69d538b 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,6 @@ local.properties # Web (pour plus tard) node_modules/ + +# Espaces de travail de Claude Code (worktrees des sous-agents) +/.claude/ diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index db7db74..f2e14ce 100644 --- a/docs/feuille-de-route.md +++ b/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 | ⏳ | | diff --git a/docs/plans/2026-11-02-moteur-embarque.md b/docs/plans/2026-11-02-moteur-embarque.md new file mode 100644 index 0000000..6accc9d --- /dev/null +++ b/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 ` + (ex. `31`), `engine-cli moves …`, `engine-cli cube `, + `engine-cli eval `, 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.