games/docs/studies/023-V0_3_0_PLATFORM_POC_AUDIT.md

0.3.0 — audit de baseline et cadrage du premier POC plateforme

Statut

Étude de cadrage pour 0.3.0-0-pre.1.

Elle décrit l'état observé de la stable 0.2.0, les requirements réellement nécessaires à Snake, le premier POC retenu et le sizing corrigé. Elle ne transforme pas encore les extractions candidates en architecture durable.

Base inspectée

Base déclarée : tag stable v0.2.0, fourni sous forme d'archive games-v0.2.0.zip.

L'intégrité ZIP est propre. L'archive est fournie explicitement comme téléchargement du tag stable v0.2.0 et constitue donc la baseline autoritaire de ce tag conformément à CMD-GIT-003. L'absence de .git dans une archive de tag est normale et ne constitue pas une validation manquante ; les contrôles Git locaux ne s'appliquent que lorsqu'un checkout Git est effectivement fourni.

La version workspace observée avant modification est 0.2.0.

Audits officiels exécutés sur la baseline

Les audits en lecture seule suivants passent sur la baseline telle que livrée :

General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
games.sasedev workspace audit: clean
Markdown table audit: clean (4 table(s), 158 file(s))
Distribution layout audit: clean (19 required path(s), 1 forbidden path(s) absent)

Ces résultats valident uniquement les contrôles mécaniques réellement couverts par les scripts. La revue manuelle des règles a détecté des écarts supplémentaires.

Écarts de baseline détectés

README de version obsolète

README.md annonce encore 0.1.0 comme stable et 0.2.0 comme candidate alors que l'archive est la stable 0.2.0.

Correction dans 0-pre.1 : afficher 0.2.0 comme stable de référence et 0.3.0-0-pre.1 comme version de développement.

ROADMAP stable non fermé

ROADMAP.md conserve quatre lignes ( ) sous 0.2.0. Cela contredit DOC-RMAP-010, qui interdit du scope encore planifié sous une version stable clôturée.

La revue du contenu 0.2.0 montre que :

• layering et dépendances ont été couverts par les études puis l'architecture consolidée ;
• matrice plateforme et pressure tests ont été produits ;
• la composition Rust statique a été retenue ;
• le manifest produit/jeu et l'architecture physique définitive des crates ne sont volontairement pas figés ;
• la trajectoire 0.3.x puis 0.4.x a été définie.

Correction dans 0-pre.1 : fermer les lignes réellement livrées et marquer explicitement le manifest/shape physique définitif comme reporté.

Effet de bord de la gate d'audit Python

Le ZIP v0.2.0 ne contient aucun __pycache__ ni fichier .pyc. En revanche, l'exécution de scripts/audit_rust_workspace_rules.py sur la baseline crée scripts/__pycache__/audit_rust_general_rules.cpython-313.pyc : audit_rust_export_completeness.py importe audit_rust_general_rules.py dans un sous-processus Python standard.

Cela contredit l'intention de CMD-GEN-006, selon laquelle les audits sont des contrôles en lecture seule. Correction dans 0-pre.1 : le wrapper exécute désormais ses trois sous-audits avec l'interpréteur courant et -B, ce qui supprime cet effet de bord sans modifier les audits eux-mêmes. Une réexécution complète confirme qu'aucun cache Python n'est créé.

Règle RC encore spécifique à 0.1.0

CMD-RC-001 parle encore du gel fonctionnel de 0.1.0. La règle est générale et doit viser la version courante.

Correction dans 0-pre.1 : formulation générique.

Build Python historique et cohérence normative

La revue des règles révèle une contradiction dans 0.2.0 : CMD-BUILD-002 interdisait globalement qu’un script Python pilote un build, tandis que CMD-BUILD-004 demandait précisément aux POC 0.3.x de remplacer les orchestrateurs Python encore présents. La baseline conserve effectivement deux chemins historiques qui les utilisent.

Deux scripts historiques pilotent encore des builds :

• scripts/build_reflex_tauri_wasm.py ;
• scripts/build_android_rust.py.

Le premier est encore appelé par les hooks Tauri Reflex. Le second orchestre cargo ndk, l'extraction SDL3 depuis l'AAR et le staging jniLibs.

Ils appartiennent à la baseline validée 0.1.0, mais un POC 0.3.x ne doit pas les reprendre comme mécanisme de build. CMD-BUILD-002 est rendue cohérente avec cette migration : les deux orchestrateurs sont explicitement tolérés uniquement comme baseline gelée jusqu’à la réactivation du chemin concerné. CMD-WEB-003 qualifie également le script Tauri/WASM comme historique. Les remplacements sont réalisés lorsque le chemin concerné devient actif : Web direct en 0.3.0, Tauri Android/Desktop dans les versions correspondantes et Android natif multi-ABI dans sa tranche dédiée.

Contraintes de l'environnement courant

L'environnement d'inspection dispose de :

Python 3.13.5
Node.js v22.16.0
npm 10.9.2
OpenJDK 21

Il ne dispose pas de :

cargo
rustc
rustup
gradle
wasm-bindgen
cargo-ndk
Tauri CLI

L'archive ne contient pas de Gradle Wrapper et ne vend pas l'AAR SDL3, conformément à la baseline Android actuelle.

Conséquence : seuls les audits statiques et inspections de fichiers sont exécutables ici. Les builds, tests et smokes restent à exécuter par l'utilisateur conformément à CMD-BUILD-005.

Inventaire Snake et hosts existants

Gameplay Snake

game-snake-poc possède déjà :

• un état déterministe indépendant de SDL, Android, Tauri et Web ;
• des directions sémantiques Left/Right/Up/Down via InputState ;
• une cadence de déplacement interne ;
• collision mur/corps ;
• score et nourriture ;
• rendu sous forme de EngineScene normalisée.

Le jeu ne consomme aucun symbole de engine-v1-platform-api, bien que cette dépendance soit encore déclarée dans son manifest. La même déclaration inutilisée existe dans game-reflex-poc. Cette dette est à nettoyer avant le premier adapter Web.

Desktop SDL3

engine-v1-sdl fournit déjà :

• fenêtre redimensionnable ;
• clavier directionnel ;
• pointeur normalisé ;
• swipe tactile/souris ;
• quit par fermeture, Escape et Back plateforme ;
• rendu de rectangles normalisés ;
• boucle fixed-step de 16 ms utilisée par les runners.

Le runner Snake Desktop compose correctement gameplay, SDL, logging et capacité plateforme désactivée. Il reste la baseline de non-régression pour 0.3.0.

Android SDL3 / Java / JNI

La baseline possède :

• SaseGameActivity commune dérivée de SDLActivity ;
• un bridge JNI versionné ;
• un cdylib Rust commun sélectionnant Reflex ou Snake par feature ;
• tactile transporté par SDL3 ;
• observation Back Android 16 non consommatrice ;
• staging Gradle des assets ;
• configuration NDK centralisée.

Le chemin build Rust Android reste toutefois orchestré par Python et n'est pas réutilisé par le premier POC 0.3.0.

Référence Tauri/WASM Reflex

La référence Reflex valide déjà plusieurs conventions utiles :

• crate WASM distincte de la crate Tauri ;
• lib.rs Tauri limité à la façade/réexport ;
• tauri.rs propriétaire de l'assemblage et des commandes ;
• frontend Vite/TypeScript dans la crate Tauri ;
• tracing frontend relayé vers Rust ;
• canvas redimensionné selon le viewport et le device pixel ratio.

Les APIs WASM et le frontend restent cependant Reflex-specific. Elles sont des références à adapter, pas du code générique à copier aveuglément.

Graphe de dépendances local observé

engine-v1-common

engine-v1-platform-api

engine-v1-sdl
    -> engine-v1-common

game-snake-poc
    -> engine-v1-common
    -> engine-v1-platform-api    [déclarée, non utilisée]

game-reflex-poc
    -> engine-v1-common
    -> engine-v1-platform-api    [déclarée, non utilisée]

game-snake-poc-desktop
    -> game-snake-poc
    -> engine-v1-common
    -> engine-v1-platform-api
    -> engine-v1-sdl
    -> game-logging-lib

game-android-entrypoint
    -> engine-v1-common
    -> engine-v1-sdl
    -> game-logging-lib
    -> game-snake-poc / game-reflex-poc via features

game-reflex-poc-wasm
    -> engine-v1-common
    -> game-reflex-poc

game-reflex-poc-tauri Rust
    -> engine-v1-platform-api
    -> game-logging-lib

frontend Reflex Tauri
    -> bindings générés game-reflex-poc-wasm

game-assets-lib
    -> aucun consommateur runtime actuel

Le graphe confirme que gameplay Snake et host peuvent être séparés sans créer un nouveau moteur.

Requirements du premier POC Snake

Besoin	Baseline réelle	Décision 0.3.0
Input clavier	SDL oui ; Web Snake absent	adapter clavier Web vers GameAction
Boutons directionnels tactiles	absent	quatre contrôles virtuels Web vers GameAction
Viewport / resize	SDL oui ; Reflex Web oui	réutiliser le principe canvas responsive sans coupler Snake à Tauri
Lifecycle	quit minimal ; pas de lifecycle Web générique	pause des ticks sur visibilitychange, reprise contrôlée, sortie/navigation host-specific
Runtime provenance	type présent mais non consommé	instancier une provenance Browser/WASM et refléter le profil d'input réellement utilisé
Assets	sources + resolver/staging présents ; aucun runtime ne charge actuellement les JSON	valider le packaging/chargement de common et game dans le POC Web
Logging	tracing natif ; bridge Tauri Reflex	logging Web local distinct de Tauri, sans dupliquer la logique gameplay
WASM bridge	Reflex-specific	créer un adapter Snake dédié ; n'extraire un bridge générique qu'après duplication réellement observée
Tauri bridge	Reflex Desktop uniquement	hors scope 0.3.0
Android packaging	SDL/Java/JNI existant	hors scope 0.3.0
Multi-ABI	script historique supportant plusieurs ABI	hors scope 0.3.0, remplacement natif prévu plus tard

Duplications et extractions candidates

Duplications déjà visibles :

• runners Desktop Reflex/Snake très proches ;
• activities Android spécifiques volontairement minimales ;
• future exposition de EngineScene en WASM susceptible de répéter l'adapter Reflex ;
• shell frontend Canvas/input susceptible d'être commun au Web direct et à Tauri.

Décision : ne pas extraire un runner générique, un bridge WASM générique ou un shell Web commun dans pre.1. Le premier second consommateur réel décide de l'extraction.

Choix du premier POC

Le premier POC de 0.3.0 est :

Web navigateur direct + Snake

Le choix initial Tauri Android est reporté au second host, actuellement 0.3.1.

Raisons :

• le Web direct exerce déjà WASM, keyboard/touch, resize, lifecycle, assets et provenance ;
• la référence Reflex fournit un précédent WASM/Canvas sans imposer Tauri ;
• Tauri Android ajouterait simultanément un nouveau gameplay WASM, un nouveau host mobile Tauri, le lifecycle mobile, le packaging Android Tauri et les plugins ;
• la baseline Web obtenue devient ensuite un point de comparaison et de réutilisation pour Tauri Android ;
• ce découpage réduit le risque de créer trop tôt une abstraction Tauri/Web commune sur la seule base de Reflex.

Scope corrigé de 0.3.0

Inclus :

• correction des écarts de baseline détectés en pre.1 ;
• nettoyage host-neutral de Snake ;
• maintien du runner Desktop SDL3 ;
• adapter WASM Snake dédié ;
• frontend Web direct Vite/TypeScript minimal ;
• clavier + boutons directionnels tactiles ;
• canvas responsive ;
• lifecycle navigateur minimal ;
• logging Web ;
• chargement d'assets de preuve ;
• provenance Browser/WASM ;
• build Web avec outils natifs ;
• audit de duplication et décisions d'extraction après POC.

Exclus :

• Tauri Android ;
• Tauri Desktop Snake ;
• remplacement du build Android natif multi-ABI ;
• publicité, billing, auth ou leaderboard ;
• réseau realtime ;
• WebTransport/QUIC ;
• logique Uroburas ;
• ECS, physique ou nouveau moteur.

Sizing corrigé

Le forecast initial est réduit et réordonné afin que 0.3.0 reste une version de session unique.

0-pre.1 — audit, règles, requirements et sizing

• audit complet de la baseline ;
• correction des incohérences documentaires/règles détectées ;
• choix Web direct ;
• forecast corrigé ;
• aucune implémentation gameplay/host lourde.

0-pre.2 — Snake portability baseline

• supprimer les dépendances de plateforme inutiles des crates jeu concernées ;
• confirmer les actions sémantiques nécessaires à Snake ;
• conserver Desktop SDL3 comme non-régression ;
• préciser le contrat minimal attendu par l'adapter WASM.

0-pre.3 — adapter Snake WASM + build natif Web

• crate WASM Snake dédiée ;
• exposition input/update/scene strictement nécessaire ;
• procédure Cargo + wasm-bindgen reproductible sans Python ;
• tests ciblés de l'adapter lorsqu'ils sont possibles hors navigateur.

0-pre.4 — POC navigateur direct de bout en bout

• frontend Vite/TypeScript ;
• rendu Canvas ;
• clavier ;
• boutons tactiles ;
• resize ;
• visibility lifecycle ;
• logging ;
• assets ;
• provenance ;
• build et smoke navigateur réels côté utilisateur.

0-pre.5 — uniquement si le POC révèle un défaut réel

Cette tranche n'est pas créée artificiellement. Elle corrige une frontière, une duplication ou un bug observé.

2-beta.1 — validation large du scope retenu

Alpha n'est pas planifiée par défaut. Si pre.4 est fonctionnellement complet, la beta valide le workspace affecté, le build Web de production et le smoke du POC.

3-rc.1 — candidate gelée

Documentation durable, commandes reproductibles, décisions d'extraction/report, ROADMAP et préparation de la version suivante. Aucun nouveau scope.

0.3.0 — promotion mécanique

Aucune nouvelle fonctionnalité.

Critères de sortie de 0.3.0

0.3.0 peut être clôturée lorsque :

• Snake Desktop SDL3 reste fonctionnel ;
• Snake fonctionne réellement dans un navigateur direct ;
• clavier et boutons tactiles produisent les mêmes actions sémantiques ;
• resize et visibility lifecycle ont été exercés ;
• assets et provenance sont observables ;
• le chemin Web ne dépend d'aucun script Python de build ;
• les duplications avec Reflex/Tauri sont documentées ;
• seules les abstractions prouvées nécessaires ont été extraites ;
• les validations applicables ont été exécutées par l'utilisateur ;
• aucune logique Uroburas ni réseau realtime n'a été introduite.