pierre/Ustagammon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

Décision : moteur gnubg officiel ; travail par merge requests #1

Manually merged
pierre merged 0 commits from decision-moteur into main 2026-11-02 18:01:41 +00:00
Conversation 0 Commits - Files Changed -
pierre commented 2026-11-02 12:19:53 +00:00
Owner
Copy Link
Copy Source

Pourquoi

L'étape 0a du prototype commence par un choix qui engage tout le reste du projet : de quel code source partir pour embarquer le moteur GNU Backgammon dans Ustagammon. Le cadrage laissait trois candidats ouverts (question « reprendre CBG ou repartir de gnubg-nn ? ») : le GNU Backgammon officiel, gnubg-nn (la bibliothèque d'évaluation qui sert à entraîner les réseaux) et CBG, un portage Android récent. Un mauvais choix se paierait tard : licence incompatible découverte avant publication, ou moteur dont les résultats ne concordent jamais avec la référence de bureau, ce qui casserait les tests qui sont notre filet de sécurité.

Cette MR consigne aussi une seconde décision prise en cours de route : à partir de maintenant, tout changement passe par une merge request comme celle-ci, au lieu d'être poussé directement sur main.

Quoi

Aucun code applicatif ne change. La MR met à jour la documentation de suivi :

  • docs/plans/2026-11-02-choix-source-moteur.md : l'étude comparative complète (versions exactes étudiées, tableau sur huit critères, fichiers à reprendre, plan d'isolement, risques), statut « validé ».
  • docs/decisions.md : deux décisions, « moteur gnubg officiel au commit 14b6798 » et « merge requests systématiques, fusionnées par Claude Code ».
  • docs/organisation.md et CLAUDE.md : la nouvelle règle de travail (branche, MR décrite en détail, fusion après make lint et make test).
  • docs/feuille-de-route.md et docs/journal.md : 0a.1 terminée ; 0a.2 précisée.

Comment

L'étude a été déléguée à un sous-agent, qui a cloné les trois dépôts hors du projet et les a lus sans rien compiler ni exécuter. La session principale a ensuite recoupé directement les affirmations décisives dans les sources :

  • gnubg-nn : 48 fichiers portent un en-tête « version 2 » de la GPL sans « or later » (grep sur *.c, *.cc, *.h), par exemple gnubg-nn/gnubg/eval.c ligne 7. C'est de la GPLv2 seule, incompatible avec la GPLv3 du projet.
  • gnubg/eval.c est en GPLv3 « or any later version ».
  • gnubg/configure.ac:595 ajoute toujours -ffast-math avec gcc.
  • Le code NEON (processeurs ARM, donc le Fairphone) existe déjà : lib/simd.h, lib/neuralnetsse.c.
  • Le fichier des poids gnubg.weights (1 097 796 octets) est identique octet pour octet dans gnubg et dans CBG.
  • Les tables d'équité de match sont lues par l'analyseur XML de GLib (g_markup, 3 usages dans matchequity.c).
  • Les bases de fin de partie (gnubg_os0.bd, gnubg_ts0.bd) sont générées au build par makebearoff, pas fournies.

Versions étudiées : gnubg 14b67984737ded0f6de43d63dcb789f729d9b06b (1.08.003, 23 octobre 2026), gnubg-nn 595a9e8, CBG 6202857.

Choix et compromis

gnubg officiel retenu : licence propre, seule source qui couvre les cinq fonctions prévues dans moteur.h avec la logique de référence (videau, équités de match, Crawford, Jacoby, Match ID), code ARM déjà présent, et une seule version à suivre, la même que la référence de bureau.

gnubg-nn écarté pour la licence, et parce que son videau est une réimplémentation séparée en C++ : ses résultats ne pourraient pas concorder avec gnubg de bureau.

CBG écarté comme source, gardé comme lecture : c'est le même moteur, mais avec GLib, GObject et libintl compilés en entier, toute la logique de partie (play.c, SGF…), et une interface qui pilote une partie en cours alors qu'Ustagammon veut évaluer des positions isolées. Il ne fournit pas les bases de fin de partie. Son fichier stubs.c reste une liste précieuse des dépendances cachées de gnubg.

Limites assumées : la concordance au bit près avec gnubg de bureau est impossible, puisque celui-ci est compilé avec -ffast-math et que le calcul diffère sur ARM et en WebAssembly. Les tests auront une tolérance, à mesurer à l'étape 0a.4. La liste des fichiers à reprendre vient de la lecture des #include et des symboles ; elle sera confirmée à la première édition des liens.

Pour les merge requests, la fusion par commit de fusion (et non par squash) garde l'historique détaillé de chaque branche.

Risques et déploiement

Aucun risque d'exécution : seule la documentation change. Le risque est dans la suite :

  • isoler le cœur demande de remplacer GLib par une petite couche d'environ 30 fonctions, et de convertir les tables d'équité XML ;
  • l'état global de gnubg impose une seule instance du moteur et des calculs l'un après l'autre ;
  • les mises à jour futures de gnubg devront être reportées à la main sur la copie figée.

Conséquence directe pour l'étape 0a.2 : le gnubg de bureau de référence doit être compilé dans Docker depuis le même commit, et non installé depuis le paquet Debian, qui est d'une autre version.

Retour arrière : annuler le commit de fusion. Rien d'autre n'en dépend encore.

Comment vérifier

git fetch && git switch main && git pull
make lint && make test
less docs/plans/2026-11-02-choix-source-moteur.md
less docs/decisions.md

Pour refaire la vérification de licence de gnubg-nn :

git clone --depth 1 https://git.savannah.gnu.org/git/gnubg/gnubg-nn.git /tmp/gnubg-nn
grep -rlE "version 2" /tmp/gnubg-nn --include=*.c --include=*.cc --include=*.h | xargs grep -L "any later version" | wc -l   # 48

Hors périmètre

  • Le portage WebAssembly tiers hwatheod/gnubg-web (2019) a été repéré mais pas lu ; il servira de précédent à l'étape 0b.
  • Les tailles réelles des bases de fin de partie ne sont pas mesurées : elles le seront quand on les générera, à l'étape 0a.2.
  • Les noms « CBG » et « Clavierhaus » sont revendiqués comme marques par leur auteur. Ils ne sont pas repris, et aucun code de CBG n'est copié à ce stade.

Generated with Claude Code

## Pourquoi L'étape 0a du prototype commence par un choix qui engage tout le reste du projet : de quel code source partir pour embarquer le moteur GNU Backgammon dans Ustagammon. Le cadrage laissait trois candidats ouverts (question « reprendre CBG ou repartir de gnubg-nn ? ») : le GNU Backgammon officiel, gnubg-nn (la bibliothèque d'évaluation qui sert à entraîner les réseaux) et CBG, un portage Android récent. Un mauvais choix se paierait tard : licence incompatible découverte avant publication, ou moteur dont les résultats ne concordent jamais avec la référence de bureau, ce qui casserait les tests qui sont notre filet de sécurité. Cette MR consigne aussi une seconde décision prise en cours de route : à partir de maintenant, tout changement passe par une merge request comme celle-ci, au lieu d'être poussé directement sur `main`. ## Quoi Aucun code applicatif ne change. La MR met à jour la documentation de suivi : - `docs/plans/2026-11-02-choix-source-moteur.md` : l'étude comparative complète (versions exactes étudiées, tableau sur huit critères, fichiers à reprendre, plan d'isolement, risques), statut « validé ». - `docs/decisions.md` : deux décisions, « moteur gnubg officiel au commit `14b6798` » et « merge requests systématiques, fusionnées par Claude Code ». - `docs/organisation.md` et `CLAUDE.md` : la nouvelle règle de travail (branche, MR décrite en détail, fusion après `make lint` et `make test`). - `docs/feuille-de-route.md` et `docs/journal.md` : 0a.1 terminée ; 0a.2 précisée. ## Comment L'étude a été déléguée à un sous-agent, qui a cloné les trois dépôts hors du projet et les a lus sans rien compiler ni exécuter. La session principale a ensuite recoupé directement les affirmations décisives dans les sources : - `gnubg-nn` : 48 fichiers portent un en-tête « version 2 » de la GPL sans « or later » (`grep` sur `*.c`, `*.cc`, `*.h`), par exemple `gnubg-nn/gnubg/eval.c` ligne 7. C'est de la GPLv2 seule, incompatible avec la GPLv3 du projet. - `gnubg/eval.c` est en GPLv3 « or any later version ». - `gnubg/configure.ac:595` ajoute toujours `-ffast-math` avec gcc. - Le code NEON (processeurs ARM, donc le Fairphone) existe déjà : `lib/simd.h`, `lib/neuralnetsse.c`. - Le fichier des poids `gnubg.weights` (1 097 796 octets) est identique octet pour octet dans gnubg et dans CBG. - Les tables d'équité de match sont lues par l'analyseur XML de GLib (`g_markup`, 3 usages dans `matchequity.c`). - Les bases de fin de partie (`gnubg_os0.bd`, `gnubg_ts0.bd`) sont générées au build par `makebearoff`, pas fournies. Versions étudiées : gnubg `14b67984737ded0f6de43d63dcb789f729d9b06b` (1.08.003, 23 octobre 2026), gnubg-nn `595a9e8`, CBG `6202857`. ## Choix et compromis **gnubg officiel retenu** : licence propre, seule source qui couvre les cinq fonctions prévues dans `moteur.h` avec la logique de référence (videau, équités de match, Crawford, Jacoby, Match ID), code ARM déjà présent, et une seule version à suivre, la même que la référence de bureau. **gnubg-nn écarté** pour la licence, et parce que son videau est une réimplémentation séparée en C++ : ses résultats ne pourraient pas concorder avec gnubg de bureau. **CBG écarté comme source, gardé comme lecture** : c'est le même moteur, mais avec GLib, GObject et libintl compilés en entier, toute la logique de partie (`play.c`, SGF…), et une interface qui pilote une partie en cours alors qu'Ustagammon veut évaluer des positions isolées. Il ne fournit pas les bases de fin de partie. Son fichier `stubs.c` reste une liste précieuse des dépendances cachées de gnubg. **Limites assumées** : la concordance au bit près avec gnubg de bureau est impossible, puisque celui-ci est compilé avec `-ffast-math` et que le calcul diffère sur ARM et en WebAssembly. Les tests auront une tolérance, à mesurer à l'étape 0a.4. La liste des fichiers à reprendre vient de la lecture des `#include` et des symboles ; elle sera confirmée à la première édition des liens. Pour les merge requests, la fusion par commit de fusion (et non par squash) garde l'historique détaillé de chaque branche. ## Risques et déploiement Aucun risque d'exécution : seule la documentation change. Le risque est dans la suite : - isoler le cœur demande de remplacer GLib par une petite couche d'environ 30 fonctions, et de convertir les tables d'équité XML ; - l'état global de gnubg impose une seule instance du moteur et des calculs l'un après l'autre ; - les mises à jour futures de gnubg devront être reportées à la main sur la copie figée. Conséquence directe pour l'étape 0a.2 : le gnubg de bureau de référence doit être compilé dans Docker depuis le même commit, et non installé depuis le paquet Debian, qui est d'une autre version. Retour arrière : annuler le commit de fusion. Rien d'autre n'en dépend encore. ## Comment vérifier ``` git fetch && git switch main && git pull make lint && make test less docs/plans/2026-11-02-choix-source-moteur.md less docs/decisions.md ``` Pour refaire la vérification de licence de gnubg-nn : ``` git clone --depth 1 https://git.savannah.gnu.org/git/gnubg/gnubg-nn.git /tmp/gnubg-nn grep -rlE "version 2" /tmp/gnubg-nn --include=*.c --include=*.cc --include=*.h | xargs grep -L "any later version" | wc -l # 48 ``` ## Hors périmètre - Le portage WebAssembly tiers `hwatheod/gnubg-web` (2019) a été repéré mais pas lu ; il servira de précédent à l'étape 0b. - Les tailles réelles des bases de fin de partie ne sont pas mesurées : elles le seront quand on les générera, à l'étape 0a.2. - Les noms « CBG » et « Clavierhaus » sont revendiqués comme marques par leur auteur. Ils ne sont pas repris, et aucun code de CBG n'est copié à ce stade. Generated with [Claude Code](https://claude.com/claude-code)
pierre added 2 commits 2026-11-02 12:19:53 +00:00
Étude des sources du moteur : recommandation gnubg officiel cbde02bc90 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Décision : moteur gnubg officiel ; travail par merge requests 9b6534cd43 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pierre manually merged commit 6958accec2 into main 2026-11-02 18:01:41 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
pierre (Pierre Martin)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: pierre/Ustagammon#1