diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index 1f359d6..ca23cbc 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -12,12 +12,12 @@ LĂ©gende : 🔄 en cours · ⏳ Ă  venir · ⏞ conditionnel Acquis : socle du dĂ©pĂŽt, organisation (ADR 0001, 0003, 0006), source du moteur (ADR 0005 : gnubg officiel, commit 14b6798), gnubg de rĂ©fĂ©rence et 32 positions de rĂ©fĂ©rence (0a.2), moteur embarquĂ© et `engine-cli` (0a.3), comparaison -automatique aux rĂ©fĂ©rences, tolĂ©rance 0,002 (0a.4). +automatique aux rĂ©fĂ©rences, tolĂ©rance 0,002 (0a.4), moteur en WebAssembly avec +page de test, page de mesure et guide de test (0b). | Sous-Ă©tape | Contenu | État | Plan | | --- | --- | --- | --- | -| 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | 🔄 | `plans/2026-11-02-moteur-webassembly.md` | -| Mesures | Pierre relĂšve les mesures sur le Fairphone 4 | ⏳ | | +| Mesures | Pierre relĂšve les mesures sur le Fairphone 4, en suivant `docs/guide-test-etape-0.md` | 🔄 | | | DĂ©cision | Socle PWA ou Android natif, consignĂ© dans un ADR — validation de Pierre | ⏳ | | | 0c | Android natif (NDK, Gradle en ligne de commande, `make deploy` via adb) | ⏞ si 0b Ă©choue | | | 0d | Plateau minimal jouable sur le socle retenu ; vĂ©rifiĂ© avec Pierre en suivant `docs/scenarios/jouer-une-partie.feature` | ⏳ | | diff --git a/docs/journal.md b/docs/journal.md index 1705b57..fb871c5 100644 --- a/docs/journal.md +++ b/docs/journal.md @@ -38,14 +38,29 @@ Une entrĂ©e datĂ©e par session : ce qui a Ă©tĂ© fait, dĂ©cidĂ©, et la suite. - Les hash de commit s'Ă©crivent sans backticks, pour les liens automatiques de Gitea (demande de Pierre). -**Incident ouvert** -- La MR !1 a bien Ă©tĂ© fusionnĂ©e cĂŽtĂ© git (commit de fusion 6958acc sur `main`), - mais Gitea l'affiche toujours « open ». Cause non Ă©tablie ; la base de - donnĂ©es du serveur refuse dĂ©jĂ  les Ă©mojis (erreur MySQL 1366), piste Ă  - vĂ©rifier dans les journaux de Gitea. +**Incident (clos)** +- Les MR fusionnĂ©es restaient « open » dans Gitea : les hooks git du serveur ne + s'exĂ©cutaient plus, sur toute l'instance (diagnostic par un sous-agent, en + lecture seule ; brief transmis Ă  Pierre). Pierre a rĂ©parĂ© les hooks et + marquĂ© les MR !1 Ă  !8 comme fusionnĂ©es. Les branches fusionnĂ©es ont Ă©tĂ© + supprimĂ©es du serveur. + +**Suite de la session (aprĂšs-midi)** +- ADR 0007 (architecture et conventions de code) et ADR 0008 (glossaire et + scĂ©narios, source unique), puis amendements : scĂ©narios en Gherkin standard + validĂ©s par l'analyseur officiel, ADR amendables (0001). +- Étape 0a terminĂ©e, par sous-agents : gnubg de rĂ©fĂ©rence et 32 positions + (0a.2, MR !6) ; moteur embarquĂ©, `engine.h` et `engine-cli` (0a.3, MR !7) ; + comparaison automatique aux rĂ©fĂ©rences, tolĂ©rance 0,002, deux dĂ©fauts du + moteur corrigĂ©s (0a.4, MR !8). +- Outils de compilation et de test validĂ©s par Pierre (amendement de + l'ADR 0004). +- Étape 0b : moteur en WebAssembly, mĂȘme suite de contrat (Ă©cart maximal + 9,5e-4), 7,3 Mo compressĂ©s, page de test et de mesure, `make deploy-web`, + guide de test `docs/guide-test-etape-0.md`. **Reste Ă  faire** -- Étape 0a.2 : image Docker de gnubg de bureau compilĂ© depuis le mĂȘme commit, - et 30 positions de rĂ©fĂ©rence ou plus. +- Mesures sur le Fairphone 4 avec Pierre, puis dĂ©cision du socle (ADR). +- Étape 0d : plateau minimal jouable sur le socle retenu. - `adb` n'est pas installĂ© sur le PC : `sudo apt install adb` avant les tests sur le tĂ©lĂ©phone. diff --git a/docs/plans/2026-11-02-moteur-webassembly.md b/docs/plans/2026-11-02-moteur-webassembly.md deleted file mode 100644 index a135849..0000000 --- a/docs/plans/2026-11-02-moteur-webassembly.md +++ /dev/null @@ -1,157 +0,0 @@ -# Moteur en WebAssembly : page de test, contrat et mesures - -- **Date** : 2026-11-02 -- **Étape** : 0b -- **Statut** : en cours -- **ExĂ©cutant** : sous-agent general-purpose, dans un worktree isolĂ© - -## Objectif - -Le mĂȘme moteur (`engine/`, `engine.h`) compilĂ© en WebAssembly tourne dans un -Web Worker d'une page web minimale servie sur le rĂ©seau local. Il donne les -mĂȘmes rĂ©sultats que le moteur natif sur les 32 positions de rĂ©fĂ©rence, et une -page de mesure produit les chiffres qui permettront de trancher entre PWA et -Android natif (`docs/etape-0.md`, section 0b). - -## Consignes - -1. **Compilation** : `make engine-wasm` compile le moteur avec Emscripten, dans - l'image `emscripten/emsdk:3.1.64` (dĂ©jĂ  tĂ©lĂ©chargĂ©e ; version figĂ©e), - en C gĂ©nĂ©rique (pas de SIMD), sans threads, `-j2`. Sorties dans - `build/wasm/`. Les donnĂ©es (`gnubg.weights` ou `gnubg.wd`, bases `.bd`, - table d'Ă©quitĂ©) viennent de `build/data/` produit par `make engine`, et sont - chargĂ©es une fois (systĂšme de fichiers virtuel d'Emscripten ou Ă©quivalent - simple). Recompilation minimale si rien n'a changĂ©. Cible visible dans - `make help`. -2. **Interface JavaScript minimale** au-dessus d'`engine.h` (par exemple - `bestMoves`, `cubeDecision`, `evaluate`, `reference`), qui renvoie les mĂȘmes - objets JSON que `engine-cli`. RĂ©utiliser le code de mise en JSON - d'`engine-cli` plutĂŽt que de le rĂ©Ă©crire, si c'est simple. -3. **MĂȘme suite de contrat** (ADR 0007, point 7) : rejouer les 32 positions de - rĂ©fĂ©rence aux niveaux 0 et 2 plis avec le build WebAssembly, sous Node (dans - l'image Emscripten, qui contient Node, ou une image Node figĂ©e), avec le - mĂȘme comparateur `tests/reference/compare.py` et la mĂȘme tolĂ©rance. Le plus - simple : un petit programme Node qui imite l'interface en ligne de commande - d'`engine-cli`, et une option du comparateur pour choisir le programme - interrogĂ©. Test lancĂ© par `make test` (`tests/test_wasm_reference.sh`). -4. **Page de test `web/`** (HTML, CSS et JavaScript sans framework ni Ă©tape de - build) : moteur chargĂ© dans un Web Worker, jamais sur le fil d'affichage ; - saisie d'un Position ID, d'un Match ID et des dĂ©s ; bouton « Meilleur coup » ; - affichage du rĂ©sultat et du temps de calcul. Textes en français, identifiants - en anglais. -5. **Page de mesure** (dans `web/`) : sur une sĂ©rie de positions de rĂ©fĂ©rence, - temps du meilleur coup Ă  0 et 2 plis et de la dĂ©cision de videau Ă  2 plis - (mĂ©diane et maximum), temps de chargement du moteur, taille totale - tĂ©lĂ©chargĂ©e (non compressĂ©e et compressĂ©e gzip), mĂ©moire WebAssembly - utilisĂ©e. Un bouton « Copier les rĂ©sultats » met un rapport texte dans le - presse-papiers, que Pierre collera dans la conversation. La page compare - elle-mĂȘme aux seuils de `docs/etape-0.md`. -6. **`make deploy-web`** sert `web/` et `build/wasm/` sur le rĂ©seau local - (serveur dans Docker, rien sur le PC ; types MIME corrects dont - `application/wasm`), et affiche l'adresse exacte Ă  ouvrir depuis le - tĂ©lĂ©phone (IP du PC sur le rĂ©seau local). Le serveur s'arrĂȘte par Ctrl+C. - Mettre Ă  jour la cible `deploy` si pertinent. -7. **`make bench`** : la mĂȘme mesure que la page, sous Node, sur le PC, pour un - premier ordre de grandeur (le chiffre qui compte reste celui du tĂ©lĂ©phone). -8. **Guide de test** pour Pierre : `docs/guide-test-etape-0.md` (document - temporaire de l'Ă©tape 0), pas Ă  pas : prĂ©parer le PC, lancer - `make deploy-web`, ouvrir l'adresse sur le Fairphone 4 (mĂȘme Wi-Fi), faire un - essai de meilleur coup, lancer la page de mesure, copier le rapport et le - coller dans la conversation. Phrases courtes, aucune connaissance technique - supposĂ©e, que faire si la page ne s'ouvre pas (pare-feu, rĂ©seau). - -Contraintes : -- respecter `CLAUDE.md` et les ADR 0004, 0005, 0007 : simplicitĂ©, pas de - framework, identifiants en anglais, commentaires et textes en français, tout - outil dans Docker ; -- ne pas modifier `engine/gnubg/` ni les rĂ©fĂ©rences ; toute adaptation du - moteur passe par `engine/compat/` ou le code d'Ustagammon ; -- signaler chaque nouvelle dĂ©pendance et sa licence dans `CREDITS.md` - (Emscripten : MIT/NCSA) ; -- `make lint` et `make test` doivent passer ; commits petits, en français, avec - la ligne `Co-Authored-By: Claude Opus 5.5 ` ; -- ne pas pousser ni crĂ©er de merge request ; -- ne rien simuler : les mesures viennent d'exĂ©cutions rĂ©elles. - -Rapport attendu : ce qui a Ă©tĂ© fait, commandes de vĂ©rification, taille des -fichiers tĂ©lĂ©chargĂ©s, mesures `make bench` sur le PC, rĂ©sultat de la suite de -contrat en WebAssembly (Ă©cart maximal), difficultĂ©s, Ă©carts au plan. - -## CritĂšres de rĂ©ussite - -- `make engine-wasm` puis `make test` : les 32 positions concordent en - WebAssembly avec la mĂȘme tolĂ©rance qu'en natif. -- `make deploy-web` affiche une adresse ; la page donne le meilleur coup d'une - position de rĂ©fĂ©rence avec son temps de calcul (vĂ©rifiĂ© dans un navigateur - sans interface si possible, sinon par une requĂȘte HTTP sur les fichiers). -- `make bench` produit un rapport. -- `make lint` et `make test` passent. - -## RĂ©sultat - -**Statut : terminĂ©** (2026-11-02, branche `wasm-travail`). Tous les critĂšres -de rĂ©ussite sont tenus ; reste la mesure sur le Fairphone 4 par Pierre -(`docs/guide-test-etape-0.md`). - -Ce qui a Ă©tĂ© fait : - -- `make engine-wasm` (`engine-wasm/wasm.mk`) compile dans - `emscripten/emsdk:3.1.64` les mĂȘmes sources que le natif (liste commune - `engine/sources.mk`), plus `engine-cli/main.c`, en C gĂ©nĂ©rique, sans - threads, `-O3 -ffast-math`. Les donnĂ©es de `build/data/` sont embarquĂ©es - dans `engine.data` (`--preload-file`, systĂšme de fichiers virtuel, `/data`). - Recompilation nulle si rien n'a changĂ©. -- Interface JavaScript (`web/engine-wasm.mjs`) : le module appelle - `engine_init` une fois, puis `main` d'engine-cli pour chaque commande - (`callMain`) ; la sortie est exactement le JSON d'engine-cli, sans code de - mise en JSON dupliquĂ©. Seule modification du C : `main` n'appelle pas - `engine_shutdown` sous Emscripten. Fonctions `bestMove`, `cubeDecision`, - `evaluate`, `reference`. -- Suite de contrat : `tests/test_wasm_reference.sh` (lancĂ© par `make test`) - rejoue les 32 positions Ă  0 et 2 plis sous Node avec - `engine-wasm/engine-cli.mjs`, qui imite engine-cli ; `compare.py --cli` - accepte dĂ©sormais une commande avec arguments. RĂ©sultat : **2 598 nombres - comparĂ©s, Ă©cart maximal 9,53e-4** (le mĂȘme cas `opening-64-match` qu'en - natif), tolĂ©rance 2e-3. ComparĂ© directement au natif : mĂȘmes classements, - mĂȘmes dĂ©cisions, Ă©cart maximal 2,3e-6. -- `web/` : page de test (`index.html`), page de mesure (`bench.html`), - Worker en module ES (`engine-worker.mjs`), client (`engine-client.mjs`), - mesure partagĂ©e avec Node (`benchmark.mjs`). Aucun framework, aucune Ă©tape - de build. -- `make deploy-web` : serveur HTTP de Python dans l'image `build-c` (aucune - nouvelle image), adresse LAN affichĂ©e (route par dĂ©faut), Ctrl+C l'arrĂȘte - (vĂ©rifiĂ©). `make deploy` renvoie vers `make deploy-web`. `make bench` : - mĂȘme mesure sous Node. - -VĂ©rification de la page : Chromium 130 et Firefox 131 sans interface (image -`mcr.microsoft.com/playwright:v1.48.2-noble`, utilisĂ©e une fois, hors du -dĂ©pĂŽt), ouverts sur l'adresse LAN `http://192.168.1.21:8080/` (contexte non -sĂ©curisĂ©, comme le tĂ©lĂ©phone) : meilleur coup de `middlegame-1` Ă  2 plis -(`24/14`, 305 ms Chromium, 2 433 ms Firefox), mesure complĂšte, bouton de copie -fonctionnel. Types MIME vĂ©rifiĂ©s par curl : `application/wasm`, -`text/javascript` pour les `.mjs`. - -Mesures sur le PC (i5-2450M, 2011) : - -| Mesure (max sur les positions) | Node 18 | Chromium 130 | Firefox 131 | Seuil | -| --- | --- | --- | --- | --- | -| Meilleur coup 0 pli | 2 ms | 5 ms | 14 ms | 300 ms | -| Meilleur coup 2 plis (mĂ©diane / max) | 107 / 454 ms | 87 / 316 ms | 693 / 2 341 ms | 3 000 ms | -| Videau 2 plis (mĂ©diane / max) | 27 / 109 ms | 21 / 103 ms | 158 / 902 ms | 3 000 ms | -| Chargement du moteur | 82 ms | 178 ms | 204 ms | | -| MĂ©moire WebAssembly | 51,9 Mo | 51,9 Mo | 51,9 Mo | | - -Taille tĂ©lĂ©chargĂ©e : 9,0 Mo non compressĂ©e, **7,3 Mo compressĂ©e gzip** (seuil -40 Mo), dont `engine.data` 8,7 Mo (7,2 Mo gzip), `engine.wasm` 180 Ko -(78 Ko gzip), `engine.mjs` 73 Ko (20 Ko gzip). - -Points d'attention : Firefox sans interface est environ 7 fois plus lent que -Chromium sur le mĂȘme PC, Ă  vĂ©rifier sur le tĂ©lĂ©phone (le guide demande les -deux navigateurs). La mĂ©moire de 52 Mo vient surtout des bases de fin de -partie copiĂ©es en mĂ©moire et du cache d'Ă©valuation de gnubg ; les donnĂ©es -existent en plus une fois cĂŽtĂ© JavaScript (systĂšme de fichiers virtuel). - -Écarts au plan : aucun sur le fond. Fichiers en `.mjs` (modules ES partagĂ©s -entre navigateur et Node sans `package.json`) ; seuils jugĂ©s sur le maximum, -la mĂ©diane Ă©tant donnĂ©e en plus ; la taille compressĂ©e est calculĂ©e par la page -(CompressionStream) car le serveur de test ne compresse pas.