# Comparer le moteur embarqué aux références de gnubg de bureau

- **Date** : 2026-11-02
- **Étape** : 0a.4
- **Statut** : terminé
- **Exécutant** : sous-agent general-purpose, dans un worktree isolé

## Objectif

`make test` vérifie automatiquement que le moteur embarqué (`build/engine-cli`)
retrouve les résultats de gnubg de bureau sur les 32 positions de
`tests/reference/`, aux niveaux 0 et 2 plis, avec une tolérance mesurée et
justifiée.

## Consignes

1. **Sortie d'`engine-cli` alignée sur le contrat** de
   `tests/reference/README.md` : une sous-commande (par exemple
   `engine-cli reference <position_id> <match_id> [dés]`, ou une option) produit,
   pour une position et un niveau, un objet de même structure que la partie
   `plies["<n>"]` d'un fichier de résultat (`evaluation`, `moves` ou `cube`).
   Le classement des coups suit exactement la méthode de la commande `hint` de
   gnubg (documentée dans le README du format) : nombre de coups, notation,
   pli réel de chaque coup. Garder `engine-cli` simple : réutiliser les
   fonctions d'`engine.h`, compléter `engine.h` si nécessaire.
2. **Comparateur** : un script lisible (Python 3 ou shell avec `jq`) qui, pour
   chaque position et chaque niveau, appelle `engine-cli`, compare au résultat
   de référence et affiche un rapport clair (position, niveau, champ, valeur
   attendue, valeur obtenue, écart). Il tourne **dans Docker** (ajouter ce qu'il
   faut à `docker/build-c/Dockerfile` et changer l'étiquette de l'image dans le
   `Makefile`), jamais avec les outils du PC (ADR 0004).
3. **Critères de concordance** :
   - même nombre de coups légaux ;
   - même meilleur coup, sauf si gnubg lui-même sépare les deux premiers coups
     de moins que la tolérance (cas d'égalité : le dire dans le rapport) ;
   - même pli réel du meilleur coup ;
   - équités et probabilités à la tolérance près, pour les coups communs ;
   - même décision de videau, et équités du videau à la tolérance près.
4. **Tolérance mesurée, pas devinée** : mesurer l'écart maximal observé sur
   les 32 positions, l'expliquer (gnubg de bureau en SSE2 avec `-ffast-math`,
   moteur embarqué en C générique), et mesurer aussi l'écart d'un build du
   moteur sans `-ffast-math`. Fixer la tolérance avec une marge raisonnable et
   la justifier dans `tests/reference/README.md`.
5. **`tests/test_engine_reference.sh`**, lancé par `make test` : lance
   `make engine` si nécessaire puis le comparateur ; échoue avec le rapport si
   un critère n'est pas tenu.
6. **`tests/test_reference.sh`** n'utilise plus `jq` sur le PC : passer par
   l'image Docker de la chaîne C (ADR 0004), et mettre `CREDITS.md` à jour.

Contraintes :
- respecter `CLAUDE.md` et les ADR 0004, 0005 et 0007 : simplicité, identifiants
  en anglais, commentaires en français, aucune installation hors Docker,
  `-j2` ;
- ne pas modifier les références (`tests/reference/results/`) ni les fichiers
  de `engine/gnubg/` ; si une divergence vient d'un vrai défaut du moteur
  embarqué, corriger dans `engine/compat/` ou `engine/src`, et le dire ;
- ne rien masquer : si une position ne concorde pas, le rapport doit le
  montrer, avec la cause trouvée ou les hypothèses ;
- `make lint` et `make test` doivent passer ; commits petits, en français, avec
  la ligne `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>` ;
- ne pas pousser ni créer de merge request.

Rapport attendu : ce qui a été fait, la tolérance retenue et sa justification
(écarts mesurés avec et sans `-ffast-math`), les éventuelles divergences et
leur cause, les commandes de vérification.

## Critères de réussite

- `make test` compare les 32 positions aux deux niveaux et passe.
- La tolérance est documentée et justifiée par des mesures.
- Une divergence volontairement introduite (par exemple une référence
  modifiée dans une copie) fait échouer le test avec un rapport lisible.

## Résultat

Terminé le 2026-11-02, branche `comparaison-travail`. `make lint` et
`make test` passent (7/7) ; les 32 positions concordent aux deux niveaux
avec la tolérance retenue, sans aucune égalité de meilleur coup à signaler.

**Fait.**

- `engine-cli --ply N reference POSITION_ID MATCH_ID [DÉS]` produit un niveau
  au format de `tests/reference/` (`evaluation`, puis `moves` ou `cube`).
  Nombres écrits avec 9 chiffres significatifs (float32 exact).
- `tests/reference/compare.py` (Python 3) et `tests/test_engine_reference.sh`
  (lancé par `make test`) : comparaison dans l'image `ustagammon/build-c:2`,
  qui reçoit Python 3 et jq. `tests/test_reference.sh` se relance dans cette
  image : plus de jq sur le PC. `CREDITS.md` à jour.
- Critères, tolérance et mesures documentés dans `tests/reference/README.md`.

**Défauts du moteur embarqué trouvés et corrigés** (`engine/engine.c`) :

- en match, l'équité des coups classés était convertie deux fois par
  `mwc2eq` (`ScoreMove` la convertit déjà) ;
- `engine_best_moves` n'appliquait pas tout `hint` : `fAnalyse` était faux
  et `RefreshMoveList` absent (classement par niveau d'évaluation, puis
  départage des égalités).

Changements d'interface : `engine_cube` gagne `optimal` et `decision_text` ;
`decision` prend le nom de l'énumération de gnubg (`DOUBLE_TAKE`…), comme
les références (`tests/test_engine.sh` adapté).

**Tolérance : 0,002**, sur probabilités et équités. Mesures sur 2 598
nombres : écart maximal 9,5e-4 et 99 % des écarts sous 1,6e-4, que le moteur
soit compilé avec ou sans `-ffast-math` (les deux builds diffèrent entre eux
de 1,1e-6 au plus). La cause est la sigmoïde de gnubg de bureau en SSE2 avec
`-ffast-math`, qui calcule `1/x` par `_mm_rcp_ps` (environ 12 bits) ; preuve :
le moteur compilé en SSE2 pour l'essai redonne les références au bit près.
L'écart maximal vient d'un seul coup (`opening-64-match`, 2 plis, `8/2 6/2`),
où l'écart de 1e-4 fait basculer un choix discret de la recherche.

**Critère de divergence vérifié** : sur une copie de `results/` avec une
équité décalée de 0,01, un nombre de coups légaux, une décision de videau et
un meilleur coup modifiés, `compare.py --results <copie>` échoue avec un
tableau de 10 écarts lisibles.

**Suites possibles** : mesurer de même sur téléphone (NEON, autre
approximation de la division) ; envisager un build SSE2 d'`engine-cli` sur PC
si l'on veut une concordance au bit près (non retenu : le moteur de
l'application tournera en C générique ou en NEON).