games/prompts/005-V0_3_4_START_PROMPT.md

Prompt de démarrage 0.3.4 — transport realtime et baseline WebSocket

1. Base exacte et cible

Partir uniquement de la version stable/taggée :

v0.3.3

Si ce prompt est lu avant la publication effective de 0.3.3, terminer d'abord la RC puis la release stable 0.3.3.

Version cible active :

0.3.4

Première tranche attendue après migration de gouvernance :

0.3.4-alpha.1

alpha.1 remplace à partir de cette session l'ancien rôle obligatoire de 0-pre.1 : audit, requirements, sizing, risques, validation et création/révision du plan actif avant développement lourd.

2. Migration de nomenclature — première action de la session

La décision est acquise depuis la fin de 0.3.3. La nouvelle convention canonique devient :

X.Y.Z-alpha.N
X.Y.Z-alpha.N.fix.M
X.Y.Z-beta.N
X.Y.Z-beta.N.fix.M
X.Y.Z-rc.N
X.Y.Z-rc.N.fix.M
X.Y.Z

Supprimer pour les nouvelles versions les préfixes numériques historiques 0-, 1-, 2-, 3- ainsi que la phase pre. alpha.1 porte désormais le cadrage obligatoire.

Avant de créer le premier delta 0.3.4-alpha.1, mettre à jour au minimum les règles et contrôles actifs concernés :

RULES.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/RULES_SESSION_PLANNING.md
docs/rules/PROMPT_STRUCTURE.md
docs/rules/RULES_DOCUMENTATION.md
scripts/audit_project_workspace_rules.py

Chercher également les références normatives/courantes à l'ancienne convention sous docs/rules/, scripts/ et les README actifs, puis les réconcilier lorsque leur sens est prospectif.

Immutabilité historique absolue

Ne jamais renommer, déplacer ou réécrire pour cette migration les anciens jalons déjà livrés, notamment :

deltas/0.1.0/ ... deltas/0.3.3/
history/0.1.0/ ... history/0.3.3/
anciennes entrées CHANGELOG décrivant ces versions
anciens prompts qui documentent leur workflow réel

Ces fichiers restent des preuves historiques avec leurs identifiants 0-pre, 1-alpha, 2-beta, 3-rc. Les audits doivent accepter cet historique tout en imposant la nouvelle convention aux versions futures.

Les archives delta futures suivent naturellement :

games-sasedev-X.Y.Z-alpha.N-delta.zip
games-sasedev-X.Y.Z-alpha.N.fix.M-delta.zip
games-sasedev-X.Y.Z-beta.N-delta.zip
games-sasedev-X.Y.Z-rc.N-delta.zip

3. Sources de vérité

Lire intégralement, dans cet ordre :

RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md

Puis au minimum :

docs/rules/RULES_GENERAL.md
docs/rules/RULES_RUST.md
docs/rules/RULES_PROJECT.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/RULES_COMMANDS.md
docs/rules/RULES_VALIDATION_MATRIX.md
docs/rules/RULES_SESSION_PLANNING.md
docs/rules/PROMPT_STRUCTURE.md

Transmission architecture/réseau :

docs/architecture/012-MODULAR_LAYERING_AND_OWNERSHIP.md
docs/architecture/013-NETWORK_AND_SERVER_ARCHITECTURE.md
docs/architecture/015-PLATFORM_POC_ARCHITECTURE.md
docs/studies/006-REALTIME_MULTIPLAYER_SERVER_STUDY.md
docs/studies/009-PLATFORM_POC_CANDIDATES.md
docs/studies/011-PLATFORM_POC_VALIDATION_MATRIX.md
docs/studies/012-PLATFORM_POC_SEQUENCE.md
history/0.3.3/
deltas/0.3.3/

Auditer ensuite les crates réelles susceptibles de porter les contrats transport/client/serveur. Ne créer aucune abstraction ou crate uniquement parce que ce prompt mentionne un nom possible : alpha.1 doit déterminer l'ownership physique à partir de l'architecture actuelle.

4. État hérité attendu de 0.3.3

La stable 0.3.3 doit laisser :

• gameplay/moteur Rust partagé inchangé ;
• Desktop SDL3, Web/WASM et POC Tauri existants ;
• voie Android productive SDL3 natif/Java/JNI ;
• build Android possédé par Gradle/Cargo sans orchestrateur Python ;
• APK Debug universal et AAB Release pour arm64-v8a, armeabi-v7a, x86_64, x86 ;
• minSdk 21 réellement fumé sur x86 ;
• compatibilité 16 KB 64 bits réellement fumée ;
• Gradle système >= 9.6.0 et JDK courant de l'environnement ;
• aucune dépendance réseau realtime imposée au moteur de rendu ou au gameplay.

Ne pas rouvrir le pipeline Android dans 0.3.4 sauf régression directement provoquée par le nouveau scope.

5. Mission 0.3.4

Introduire une API de transport realtime et une baseline WebSocket fondée sur Tokio + tokio-tungstenite, sans implémenter encore le serveur Uroburas Mode 3 ni figer prématurément tout le protocole multijoueur.

La frontière durable reste conceptuellement :

transport
    ↓
wire codec
    ↓
session protocol
    ↓
synchronization
    ↓
authoritative simulation

0.3.4 se concentre sur le premier étage et les contrats minimaux nécessaires pour le tester proprement. Une socket ouverte ne doit jamais être confondue avec une session gameplay synchronisée.

6. Scope inclus

alpha.1 doit inventorier et décider au minimum :

• emplacement de l'API de transport realtime et sens des dépendances ;
• séparation client/server et éventuels types communs réellement nécessaires ;
• connexion, fermeture, send/receive, erreurs et cancellation async ;
• ownership Tokio/runtime sans le propager inutilement dans le gameplay ;
• baseline tokio-tungstenite WebSocket ;
• stratégie de codec initiale suffisamment simple pour le POC sans figer le protocole final ;
• timeouts, backpressure et limites élémentaires ;
• test loopback/local déterministe ;
• logging/tracing transport séparé des futurs domaines session/sync/simulation ;
• compatibilité future avec un autre transport, notamment le POC WebTransport/QUIC de 0.3.5, sans abstraction spéculative excessive.

7. Hors scope

Ne pas transformer 0.3.4 en serveur de jeu complet. Sont notamment hors scope sauf nécessité démontrée par le POC transport :

• Uroburas Mode 3 ;
• matchmaking complet ;
• simulation authoritative de jeu ;
• snapshots/deltas métier définitifs ;
• prediction/reconciliation ou rollback ;
• Redis/NATS/Kafka ;
• persistence gameplay ;
• auth complète ;
• scaling/sharding/regions ;
• WebTransport/QUIC de production, réservé au POC comparatif suivant ;
• Actix Web comme dépendance obligatoire du data plane realtime.

8. Contraintes architecturales

Préserver :

• async-first pour les nouvelles API réseau ;
• aucune dépendance transport dans les crates gameplay ;
• distinction stricte transport/session/sync/simulation ;
• façade lib.rs et ownership modulaire conformes aux règles Rust du dépôt ;
• tracing pour les diagnostics ;
• erreurs explicites, cancellation et fermeture propres ;
• pas de framework générique massif avant deux consommateurs réels ;
• WebSocket baseline remplaçable/comparable par le futur POC WebTransport sans réécrire le gameplay.

9. Cadrage alpha.1 obligatoire

Avant développement lourd :

1. effectuer la migration de nomenclature décrite plus haut ;
2. auditer la stable 0.3.3 et les règles après migration ;
3. réévaluer les études réseau existantes ;
4. vérifier les versions actuelles et contraintes des dépendances réellement envisagées ;
5. décider l'ownership physique des crates/modules ;
6. définir le contrat API minimal et les erreurs ;
7. définir les tests loopback et les gates ;
8. évaluer le besoin éventuel d'un petit demo/CLI uniquement s'il apporte une preuve utile ;
9. créer docs/plans/004-V0_3_4_REALTIME_TRANSPORT_WEBSOCKET_PLAN.md ;
10. produire un forecast souple jusqu'à stable, avec beta de validation large, RC gelée et release mécanique.

Si le scope dépasse raisonnablement une seule session/version, le scinder dès alpha.1.

10. Validation et responsabilité

Les audits statiques peuvent être exécutés par le générateur. Les builds, tests et smokes finaux restent côté utilisateur et ne sont jamais déclarés réussis sans sortie réelle.

Dès qu'un fichier Rust/Cargo change :

cargo fmt --all
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings

Les tests restent ciblés par défaut ; cargo test --workspace --all-targets --all-features est réservé aux jalons larges/finalisation planifiés.

Toute commande nécessitant un changement de répertoire utilise un sous-shell (cd ... && ...).

11. Deltas, historique et changelog

À partir de 0.3.4, les nouveaux fichiers utilisent uniquement la nouvelle nomenclature :

deltas/0.3.4/alpha.1.md
history/0.3.4/alpha.1.md   # créé seulement après validation, par le jalon suivant

Un échec de alpha.1 produit alpha.1.fix.1, pas un retour vers l'ancienne convention.

CHANGELOG.md reste normalement silencieux avant RC. ROADMAP.md reste macroscopique. Aucun ancien delta/history n'est renommé pour homogénéiser l'apparence.

12. Forecast initial non contraignant

Ce forecast est une hypothèse de travail initiale, pas un contrat de numérotation. Il doit être relu et réécrit dans le plan 0.3.4 pendant alpha.1 à partir des constats réels de la baseline, des dépendances actuelles, des tests possibles et du sizing obtenu.

Règles de lecture du forecast :

• les jalons ci-dessous donnent un ordre logique probable, pas une obligation de produire exactement ce nombre de prereleases ;
• une tranche peut être fusionnée avec la suivante si son contenu devient trivial et reste validable comme une unité cohérente ;
• une tranche doit être scindée si elle dépasse le budget habituel de 15–30 minutes, mélange plusieurs responsabilités indépendantes ou nécessite des validations hétérogènes ;
• tout défaut découvert après livraison d'un jalon reste dans <jalon>.fix.N tant que son objectif fonctionnel n'est pas rouvert ;
• aucune tranche ne doit être créée uniquement pour respecter la séquence ci-dessous ;
• si l'audit alpha.1 montre qu'une partie relève plutôt de 0.3.5 ou d'une nouvelle version, la reporter avant développement lourd ;
• le plan actif sous docs/plans/ devient l'autorité prévisionnelle après alpha.1 et peut diverger de ce forecast sans réécrire ce prompt historique.

0.3.4-alpha.1 — migration de gouvernance + audit + contrat transport

Objectif probable : fermer tout le cadrage avant de figer une API réseau.

Travail attendu :

• appliquer la nouvelle nomenclature aux règles prospectives uniquement ;
• adapter les audits qui reconnaissent les prereleases sans modifier l'historique 0.1.x–0.3.3 ;
• vérifier que la baseline stable 0.3.3 est propre ;
• relire les études réseau et confronter leurs hypothèses au code actuel ;
• vérifier les versions actuelles de Tokio, tokio-tungstenite, tungstenite, TLS éventuel et autres dépendances réellement nécessaires ;
• décider si l'API durable vit dans une crate dédiée, une crate existante ou plusieurs crates ;
• définir les responsabilités client/server communes sans créer un framework abstrait prématuré ;
• définir le modèle d'erreur, fermeture, cancellation, timeout, backpressure et limites ;
• décider le codec de preuve initial sans le présenter comme protocole gameplay final ;
• définir la matrice de tests et les gates de chaque tranche ;
• créer docs/plans/004-V0_3_4_REALTIME_TRANSPORT_WEBSOCKET_PLAN.md avec un forecast révisé jusqu'à stable.

Livrables probables : gouvernance migrée, étude/résultats d'audit si nécessaire, plan actif, ownership décidé, premier contrat API suffisamment précis pour démarrer l'implémentation suivante.

Gate de sortie : aucune ambiguïté majeure sur l'ownership ou le sens des dépendances ; scope 0.3.4 dimensionné pour tenir dans la session ; validations futures identifiées ; aucune dépendance réseau introduite dans les crates gameplay.

0.3.4-alpha.2 — API de transport async minimale

Objectif probable : introduire la frontière transport indépendamment de WebSocket.

Travail candidat :

• types de connexion/endpoint strictement nécessaires ;
• contrat async send/receive ou équivalent retenu par l'audit ;
• fermeture locale/distante explicite ;
• cancellation propre ;
• erreurs typées ;
• taille/limites élémentaires des messages ;
• tests unitaires du contrat sans réseau réel lorsque possible ;
• façade lib.rs et documentation publique conformes aux règles du dépôt.

À éviter : codec métier complet, session gameplay, heartbeat produit définitif, simulation authoritative ou abstraction multi-transport sophistiquée.

Gate de sortie : API consommable par un backend WebSocket futur et testable indépendamment de celui-ci ; aucun couplage direct au gameplay.

0.3.4-alpha.3 — backend WebSocket tokio-tungstenite

Objectif probable : fournir la première implémentation concrète de la frontière transport.

Travail candidat :

• connect/listen WebSocket selon l'ownership retenu ;
• mapping frames ↔ messages du transport ;
• fermeture WebSocket propre ;
• propagation des erreurs ;
• timeouts/cancellation minimum nécessaires ;
• tracing du domaine transport ;
• test loopback localhost déterministe client ↔ serveur ;
• absence de dépendance à Axum si elle n'apporte rien à la preuve transport.

Gate de sortie : round-trip local reproductible, fermeture des deux côtés vérifiée, aucune tâche async orpheline connue, erreurs observables.

0.3.4-alpha.4 — robustesse : limites, backpressure et lifecycle

Cette tranche est conditionnelle : la fusion avec alpha.3 est préférable si les mécanismes restent petits et cohérents.

Travail candidat :

• bornes de taille et files internes ;
• comportement explicite en cas de consommateur lent ;
• timeout de connexion/lecture/écriture uniquement là où il est justifié ;
• comportement sur fermeture distante, connexion interrompue et cancellation ;
• vérification qu'aucune boucle ne spin ou ne masque une erreur ;
• tests négatifs ciblés ;
• métriques/tracing minimaux permettant de diagnostiquer le transport sans mélanger session/sync/simulation.

Gate de sortie : les principaux modes d'échec du transport sont déterministes, bornés et testés.

0.3.4-alpha.5 — intégration consommateur/démo minimale, si utile

Cette tranche n'existe que si une preuve supplémentaire apporte une valeur réelle après alpha.3/alpha.4.

Candidats acceptables :

• petit demo/CLI client-server ;
• intégration à un launcher de POC sans logique gameplay réseau ;
• harness de test permettant de mesurer connexion, échange et fermeture.

Ne pas créer d'application ou de crate uniquement pour « montrer » l'API si les tests loopback prouvent déjà tout le contrat utile.

Gate de sortie : preuve reproductible du chemin public du transport, sans introduire la session gameplay.

0.3.4-alpha.N — consolidation de développement

Avant beta, réserver explicitement une tranche de consolidation si les alpha précédentes ont réellement introduit plusieurs composants.

Cette tranche peut couvrir :

• réconciliation docs/API/README/USAGE réellement nécessaires ;
• suppression de duplication ou dette née pendant les alpha, uniquement si bornée ;
• audit du graphe de dépendances ;
• vérification que transport -> wire codec -> session -> sync -> simulation reste respecté ;
• confirmation de ce qui est volontairement reporté à 0.3.5 ou 0.4.x ;
• préparation d'une gate beta large et reproductible.

Elle peut être fusionnée avec la dernière alpha fonctionnelle si aucune consolidation autonome n'est nécessaire.

0.3.4-beta.1 — validation large

Objectif probable : valider le produit de 0.3.4 comme baseline transport complète, pas ajouter des fonctionnalités.

Gate candidate :

• audits dépôt applicables ;
• format/check/Clippy workspace ;
• tests ciblés des nouvelles crates/modules ;
• test workspace complet si le plan le confirme ;
• tests loopback client/server ;
• tests de fermeture/cancellation/backpressure retenus ;
• éventuel demo/CLI reproductible si créé ;
• vérification du graphe de dépendances ;
• confirmation qu'aucune crate gameplay ne dépend du backend WebSocket ;
• documentation opérateur/API cohérente avec le comportement réel.

Un défaut trouvé ici produit beta.1.fix.N tant que le périmètre reste fermé. Une capacité réseau manquante importante impose de revenir à une alpha suivante au lieu de maquiller une nouvelle fonctionnalité en fix beta.

0.3.4-rc.1 — candidate gelée

Objectif probable : candidate de publication sans nouveau comportement.

Travail attendu :

• scope fonctionnel gelé ;
• revalidation des gates importantes de beta ;
• consolidation CHANGELOG.md ;
• état macro ROADMAP.md cohérent ;
• historique applicable ;
• documentation finale de l'API transport et de la baseline WebSocket ;
• préparation/vérification du prompt 0.3.5 WebTransport/QUIC avec transmission précise de la baseline WebSocket à comparer ;
• aucune optimisation ou abstraction nouvelle sans défaut de release démontré.

Les correctifs strictement nécessaires restent sous rc.1.fix.N. Toute réouverture fonctionnelle revient à une phase adaptée avant une nouvelle RC.

0.3.4 — promotion stable mécanique

La stable doit normalement se limiter à :

• version stable ;
• historique RC ;
• changelog stable ;
• clôture du plan ;
• statut roadmap si requis ;
• delta/release final ;
• ajustements strictement mécaniques du prompt suivant si une référence de baseline devient certaine.

Aucune nouvelle API, dépendance ou décision architecturale ne doit apparaître pour la première fois dans la stable.

Branches de redécoupage explicitement admises

Le forecast initial doit être révisé sans hésitation dans les cas suivants :

API transport + backend WebSocket restent très petits
    -> fusion possible alpha.2 + alpha.3

backpressure/lifecycle nécessitent un travail autonome
    -> conserver alpha.4 ou la scinder

le demo n'apporte aucune preuve supplémentaire
    -> supprimer alpha.5

un vrai wire codec réutilisable devient indispensable
    -> décider en alpha.1 s'il appartient encore à 0.3.4
       ou s'il mérite une version distincte

l'abstraction WebTransport exige déjà des choix QUIC
    -> reporter à 0.3.5 ; ne pas polluer 0.3.4

le serveur de jeu/session protocol commence à apparaître
    -> arrêter et reporter au scope Uroburas approprié

Le critère n'est donc pas « suivre tous les numéros », mais obtenir à la fin de 0.3.4 une frontière de transport claire, un backend WebSocket reproductible et suffisamment robuste pour devenir la baseline comparative de 0.3.5.

13. Condition de fin de session

La session ne vise pas une simple prerelease : elle doit mener 0.3.4 jusqu'à une stable concrète, sauf découverte imposant explicitement un redécoupage de scope vers une version suivante.