Ustagammon/docs/adr/0005-moteur-gnubg-officiel.md

0005. Source du moteur : GNU Backgammon officiel, commit 14b6798

• Statut : accepté
• Date : 2026-11-02
• Décideurs : Pierre, sur recommandation de Claude Code

Contexte

L'étape 0a commence par choisir le code source à partir duquel embarquer le moteur, derrière une interface C moteur.h qui doit offrir cinq fonctions : initialisation, coups légaux, classement des coups par niveau, décision de videau en match, évaluation. Positions au format GNU Position ID et Match ID. Les résultats doivent concorder avec le GNU Backgammon de bureau, qui sert de référence aux tests.

Trois candidats ont été étudiés par un sous-agent, sur clones superficiels lus sans rien compiler ni exécuter (MR !1 sur git.sans.pub) :

Source	Commit étudié	Date
gnubg officiel	14b67984737ded0f6de43d63dcb789f729d9b06b (1.08.003)	2026-10-23
gnubg-nn	595a9e8f1fe094ee22db5a736bc05027643756df	2025-09-07
CBG (github.com/clavierhaus/gnubg-android)	62028573d7564275a7c9363f0ef5d4b63d8d0f26 (moteur gnubg b1b2772c)	2026-10-26

Critère	gnubg	gnubg-nn	CBG
Activité	Active (corrections régulières)	Quasi arrêtée (outil d'entraînement des réseaux)	Très active ; un mainteneur, code très majoritairement écrit par IA
Licence	GPLv3 ou ultérieure	48 fichiers en GPLv2 seule : incompatible	GPLv3 ou ultérieure ; noms « CBG » et « Clavierhaus » revendiqués comme marques
Fonctions	Les cinq, avec tables d'équité, Crawford, Jacoby, Position ID et Match ID	Partiel : pas de Match ID, videau réimplémenté en C++	Les cinq, mais interface pensée pour une partie en cours
Dépendances	GLib dans tout le cœur, remplaçable par un shim d'environ 30 fonctions, sauf GMarkup (tables d'équité) et g_mapped_file ; SSE, AVX, NEON et repli en C générique ; threads désactivables	C++14, Python 2, SSE seul	GLib, GObject et libintl compilés en entier pour Android
Isolement	Faisable : environ 24 400 lignes ; état global partout ; backgammon.h à réduire	Évaluation isolée, le reste à réécrire	41 fichiers et 681 lignes de bouchons : pas une bibliothèque minimale
Données	gnubg.weights (1 097 796 octets) ; gnubg.wd, gnubg_os0.bd, gnubg_ts0.bd générés au build ; tables d'équité XML (Kazaross-XG2.xml par défaut)	Pas de poids fournis	Mêmes poids, identiques octet pour octet ; aucune base .bd fournie
Portabilité	NEON présent ; pas de SIMD WebAssembly (C générique) ; un portage Emscripten tiers existe (hwatheod/gnubg-web, 2019)	Mauvais point de départ	Build CMake/NDK fonctionnel, pas de WebAssembly
Concordance	Mêmes sources et poids que le bureau ; écart flottant car configure.ac force -ffast-math	Non, pour le videau	Écarts de 1e-4 à 3e-3 selon leur documentation, non vérifié

Points recoupés directement dans les sources par la session principale : les 48 en-têtes GPLv2 de gnubg-nn (ex. gnubg-nn/gnubg/eval.c l. 7) ; la licence GPLv3+ de gnubg/eval.c ; -ffast-math ajouté par gnubg/configure.ac:595 ; le code NEON dans lib/simd.h et lib/neuralnetsse.c ; l'identité des poids entre gnubg et CBG ; trois usages de g_markup dans matchequity.c ; makebearoff dans Makefile.am.

Décision

Le moteur d'Ustagammon est construit à partir de GNU Backgammon officiel, figé au commit 14b67984737ded0f6de43d63dcb789f729d9b06b, dont on n'extrait que le cœur, derrière moteur.h.

Fichiers à reprendre (liste issue des #include et des symboles, à confirmer à la première édition des liens) :

• Évaluation : eval.c/h, movefilters.inc, lib/neuralnet.c/h, lib/neuralnetsse.c, lib/inputs.c, lib/simd.h, lib/sigmoid.h, lib/cache.c/h, lib/gnubg-types.h, lib/isaac.c/h, lib/isaacs.h, lib/md5.c/h.
• Fin de partie : bearoff.c/h, bearoffgammon.c/h.
• Identifiants : positionid.c/h, matchid.c/h.
• Équité de match : matchequity.c/h, mec.c/h, lib/list.c/h.
• En-têtes à réduire : backgammon.h, common.h, multithread.h, util.h.
• Données : gnubg.weights, met/*.xml ; outils hôte makeweights.c et makebearoff.c.

Plan d'isolement :

1. Copie figée dans engine/, config.h écrit à la main (sans threads ; NEON sur arm64 ; rien en WebAssembly).
2. Shim glib.h minimal ; mmap ou fread à la place de g_mapped_file.
3. Tables d'équité converties en tableaux C au build, ou table Zadeh intégrée pour commencer.
4. En-tête réduit à la place de backgammon.h, variables globales aux valeurs par défaut de gnubg.c, en s'inspirant de jni-bridge/src/stubs.c de CBG.
5. Façade moteur.h sur GenerateMoves, FindnSaveBestMoves, GeneralCubeDecisionE et FindCubeDecision, PositionFromID, MatchFromID.
6. gnubg.wd et bases .bd générées sur l'hôte avec les outils officiels.
7. Tests de concordance avec tolérance, en mesurant l'écart avec et sans -ffast-math.

Alternatives écartées

• gnubg-nn : 48 fichiers sous GPLv2 seule, incompatibles avec la GPLv3 du projet ; videau réimplémenté, donc sans concordance possible avec gnubg de bureau.
• CBG : même moteur, mais avec GLib complète et toute la logique de partie ; interface orientée partie en cours ; pas de bases de fin de partie. Gardé comme référence de lecture, sans reprise de code ni de ses noms.

Conséquences

• Le gnubg de bureau de référence est compilé dans Docker depuis le même commit, et non pris dans un paquet Debian d'une autre version.
• Concordance au bit près impossible entre x86 avec -ffast-math et ARM ou WebAssembly : les tests ont une tolérance, et prévoient le cas où le meilleur coup change entre deux coups presque équivalents.
• L'état global de gnubg impose une seule instance du moteur et des appels sérialisés.
• Les mises à jour de gnubg sont reportées à la main sur la copie figée.
• Les tailles des bases .bd restent à mesurer.
• Attention aux noms de niveaux : gnubg compte les plis à partir de 0 (0-ply = évaluation statique).