games/prompts/006-V0_3_5_START_PROMPT.md

Prompt de démarrage 0.3.5 — POC WebTransport/QUIC et fallback WebSocket

1. Base exacte et cible

Partir uniquement de la version stable/taggée :

v0.3.4

Ce prompt est destiné à être utilisé depuis la stable taggée v0.3.4. Une archive annoncée comme téléchargement ZIP du tag Gitea est autoritaire conformément à CMD-GIT-003 et CMD-GIT-004 ; l'absence de .git n'est pas un défaut.

Version cible :

0.3.5

Première tranche attendue :

0.3.5-alpha.1

alpha.1 est obligatoirement le gate de cadrage : audit de la stable, recherche des stacks WebTransport/QUIC actuelles, requirements, sizing, risques, matrice plateforme, validations et création du plan actif avant développement lourd.

2. 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 réseau et plateforme :

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
docs/plans/004-V0_3_4_REALTIME_TRANSPORT_WEBSOCKET_PLAN.md
history/0.3.4/
deltas/0.3.4/
crates/common/game-realtime-transport-lib/README.md
crates/common/game-realtime-websocket-lib/README.md
crates/common/game-realtime-websocket-lib/USAGE.md

Le plan 0.3.4 est historique une fois la stable publiée ; 0.3.5-alpha.1 crée docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md, qui devient alors l'autorité prévisionnelle active.

3. État hérité attendu de 0.3.4

La stable 0.3.4 doit laisser une frontière realtime déjà testée :

transport-neutral contract
    ↓
WebSocket backend
    ↓
future wire/session layers

État attendu :

• game-realtime-transport-lib sans Tokio, WebSocket, QUIC, HTTP ou TLS ;
• payload binaire opaque TransportMessage ;
• split RealtimeConnection -> Sender + Receiver ;
• fermeture distante propre distinguée des erreurs ;
• catégories d'erreur transport-neutral ;
• game-realtime-websocket-lib comme backend de référence Tokio/tokio-tungstenite ;
• client ws://, listener serveur, close propre, limites, deadlines et tracing ;
• aucun runtime Tokio privé ni task backend détachée ;
• aucun moteur ou gameplay dépendant du backend WebSocket ;
• game-realtime-websocket-smoke comme preuve runtime localhost hors harness #[test] ;
• aucune politique TLS directe, aucun wire codec final, aucune session joueur/room et aucune simulation authoritative.

La stable 0.3.4 hérite des validations réellement obtenues pendant beta.1 et rc.1 : workspace complet validé en beta, gates de publication realtime ciblées validées en RC, smoke runtime PASS et frontière de dépendances confirmée. Relire history/0.3.4/ et deltas/0.3.4/rel.001.md comme preuves détaillées au lieu d'inventer ou d'extrapoler des validations supplémentaires.

4. Mission 0.3.5

Évaluer puis prototyper WebTransport/QUIC comme second transport realtime en conservant WebSocket comme baseline/fallback de référence.

Le résultat recherché n'est pas « remplacer WebSocket parce que QUIC est plus moderne ». 0.3.5 doit répondre avec des preuves :

• un backend WebTransport/QUIC est-il viable sur les plateformes réellement visées ?
• peut-il consommer la frontière game-realtime-transport-lib sans la déformer artificiellement ?
• quelles différences de sémantique existent entre WebSocket et WebTransport : streams, datagrams, ordering, reliability, fermeture, backpressure ?
• le bénéfice mesuré justifie-t-il la complexité TLS/HTTP3/QUIC et les contraintes navigateur/infrastructure ?
• quel fallback WebSocket est réellement nécessaire et à quel niveau doit-il être choisi ?

La frontière conceptuelle reste :

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

0.3.5 reste concentrée sur le transport et la comparaison. Elle ne doit pas profiter du POC QUIC pour concevoir prématurément les couches supérieures.

5. Recherche alpha.1 obligatoire

Avant de choisir une crate ou d'écrire un backend, vérifier sur les sources actuelles :

• état et versions des crates Rust candidates WebTransport/QUIC ;
• maintenance, MSRV, Tokio/runtime, licence et dépendances ;
• support client et serveur natif ;
• possibilité réelle côté navigateur/WASM et relation éventuelle avec l'API WebTransport du navigateur ;
• support Android natif pertinent pour la trajectoire du projet ;
• exigences TLS/certificats et contraintes de développement localhost ;
• HTTP/3/QUIC sous-jacent et besoins UDP ;
• compatibilité Debian Stable pour un serveur auto-hébergé ;
• interaction avec reverse proxy/edge lorsqu'elle est réellement nécessaire ;
• support des streams bidirectionnels/unidirectionnels et des datagrams ;
• comportement de backpressure, limites, fermeture et cancellation ;
• maturité des APIs de test loopback/local ;
• disponibilité et stabilité des APIs navigateur sur les cibles réellement testables.

Ne pas figer dans ce prompt un nom de crate WebTransport/QUIC : alpha.1 doit comparer l'état actuel de l'écosystème au moment du développement.

6. Question centrale : compatibilité du contrat 0.3.4

Le contrat game-realtime-transport-lib a été volontairement minimal et orienté « messages binaires fiables/ordonnés » parce que WebSocket était le premier backend.

alpha.1 doit déterminer si :

1. WebTransport peut implémenter ce contrat proprement via un stream fiable sans perte significative ;
2. les datagrams WebTransport apportent une capability réellement utile qui ne rentre pas dans ce contrat ;
3. une capability supplémentaire doit être séparée au lieu d'élargir RealtimeConnection ;
4. le POC doit garder deux chemins distincts afin de comparer avant toute extraction commune.

Interdiction de modifier game-realtime-transport-lib uniquement pour rendre les APIs WebSocket et QUIC esthétiquement identiques. Toute évolution du contrat commun doit être motivée par au moins deux consommateurs réels et un besoin sémantique partagé.

7. Scope inclus

Le scope candidat comprend :

• audit/recherche WebTransport/QUIC ;
• plan 0.3.5 et matrice de preuves ;
• second backend transport si la stack retenue est suffisamment viable ;
• preuve client/serveur locale ou équivalent reproductible ;
• payload binaire opaque réutilisant le contrat commun lorsque cela est sémantiquement correct ;
• fermeture/cancellation, limites, timeouts et erreurs du nouveau backend ;
• tracing séparé ;
• preuve du fallback WebSocket ou d'un choix de transport au niveau approprié, uniquement si le POC le justifie ;
• comparaison mesurée WebSocket vs WebTransport/QUIC ;
• documentation des contraintes plateforme/TLS/infrastructure ;
• smoke runtime distinct du harness de test si nécessaire pour prouver le nouveau chemin.

8. Hors scope

Sauf nécessité strictement démontrée par le POC transport, ne pas introduire :

• Uroburas Mode 3 ;
• matchmaking ;
• auth complète ;
• protocole session joueur/room ;
• codec wire définitif ;
• snapshot/delta gameplay ;
• prediction/reconciliation ou rollback ;
• simulation authoritative ;
• persistence gameplay ;
• Redis/NATS/Kafka ;
• sharding/regions ;
• CDN/edge complexe ;
• orchestration Kubernetes ;
• remplacement de la stack Web/API Actix ;
• framework générique multi-transport massif.

9. Mesures et comparaison

Le POC doit définir avant mesure les métriques réellement utiles. Candidats :

• temps d'établissement ;
• latence aller-retour de petits payloads ;
• débit sur payloads bornés ;
• overhead observable ;
• comportement sous plusieurs messages en vol ;
• coût CPU/mémoire si la mesure est suffisamment reproductible ;
• différence fiable/ordonnée vs datagram lorsque ce dernier est réellement disponible ;
• complexité opérationnelle : certificats, UDP, ports, reverse proxy et debugging.

Un benchmark loopback ne suffit pas à conclure sur Internet/mobile. Il sert à vérifier l'implémentation et à comparer des overheads locaux contrôlés. Toute conclusion produit doit distinguer mesure locale, comportement protocolaire connu et test réseau externe réellement effectué.

Les benchmarks doivent rester bornés, reproductibles et ne pas devenir une infrastructure de performance disproportionnée pour un POC.

10. Fallback WebSocket

WebSocket reste la baseline fonctionnelle jusqu'à preuve contraire.

Le fallback ne doit pas être codé dans le gameplay. alpha.1 doit décider l'ownership du choix de transport parmi :

• composition/application ;
• client/platform adapter ;
• petit sélecteur technique dédié si deux backends réels le justifient.

Ne pas créer un TransportManager, registry dynamique ou système de plugins uniquement pour choisir entre deux transports POC.

11. Plateformes à challenger

Le plan alpha.1 doit expliciter ce qui est réellement testable dans la session :

• Linux natif : client/server local de référence ;
• navigateur/WASM : important pour WebTransport, mais seulement avec une chaîne de test réaliste ;
• Android : vérifier la trajectoire et la compatibilité, sans rouvrir le pipeline multi-ABI 0.3.3 si aucun code Android n'est touché ;
• iOS/macOS : documenter les contraintes connues mais ne pas bloquer la version en l'absence d'environnement Apple.

Une plateforme non testée ne doit pas être présentée comme validée.

12. TLS, certificats et sécurité transport

Contrairement à la baseline locale ws://, WebTransport navigateur peut imposer des contraintes de sécurité/certificats. alpha.1 doit vérifier les exigences actuelles au lieu de les supposer.

La version peut introduire uniquement la politique minimale nécessaire au POC. Ne pas transformer 0.3.5 en projet PKI complet. Les certificats de développement, s'ils sont nécessaires, restent hors secrets du dépôt et leur génération/installation doit être documentée de façon reproductible.

Aucune désactivation dangereuse de validation TLS ne devient un chemin produit permanent uniquement pour simplifier un smoke.

13. Documentation README/USAGE

Appliquer DOC-CRATE-* à tout nouveau composant :

• backend WebTransport/QUIC durable : README probable ;
• configuration/workflow/certificats non triviaux : USAGE probablement utile ;
• launcher de benchmark/smoke très petit : documentation locale seulement si le plan central ne couvre pas suffisamment son rôle ;
• ne jamais créer des fichiers vides ou redondants par cérémonie.

La documentation propre à la fonctionnalité évolue avec la tranche qui l'introduit ; la RC ne doit pas être utilisée pour reporter toute documentation à la fin.

14. Validation et responsabilité

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

Dès qu'un fichier Rust ou 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 pendant l'implémentation. cargo test --workspace --all-targets --all-features est réservé aux jalons larges planifiés ou lorsqu'une évolution transverse le justifie.

cargo tree est utilisé lorsque les dépendances changent ou lorsqu'une frontière doit être prouvée, pas comme cérémonie à chaque tranche.

Toute commande nécessitant un cd doit être englobée dans un sous-shell (cd ... && ...).

15. Deltas, history, changelog et roadmap

À partir de 0.3.5, conserver la nomenclature :

0.3.5-alpha.N
0.3.5-alpha.N.fix.M
0.3.5-beta.N
0.3.5-beta.N.fix.M
0.3.5-rc.N
0.3.5-rc.N.fix.M
0.3.5

Chaque delta indique sa base, son scope, les fichiers touchés et les validations attendues.

history/0.3.5/<jalon>.md est créé uniquement par la tranche suivante ou son fix après validation réelle du jalon précédent.

CHANGELOG.md reste normalement silencieux avant la RC. ROADMAP.md reste macroscopique et ne change que si le scope, l'ordre ou le statut évolue réellement.

Un échec fermé d'une tranche produit <jalon>.fix.N. Une validation propre permet de poursuivre automatiquement vers la tranche planifiée suivante. Une session doit fermer au minimum une version concrète jusqu'à sa stable ; ne pas s'arrêter volontairement sur une prerelease.

16. Cadrage alpha.1 obligatoire

Avant développement lourd :

1. auditer la stable v0.3.4 et vérifier ses gates/historique ;
2. relire le contrat transport et le backend WebSocket réellement livrés ;
3. rechercher l'écosystème WebTransport/QUIC actuel ;
4. établir une matrice plateforme/runtime/TLS ;
5. comparer les stacks candidates et justifier le choix ;
6. décider si le contrat transport-neutral reste inchangé ;
7. décider ownership physique des nouvelles crates/outils ;
8. définir les preuves locales, navigateur éventuel, benchmarks et smokes ;
9. définir précisément ce que signifie « fallback WebSocket » dans ce POC ;
10. créer docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md ;
11. produire un forecast révisé jusqu'à stable et redécouper la version si le scope excède une session raisonnable.

17. Forecast initial non contraignant

Le forecast ci-dessous est une hypothèse de départ. alpha.1 doit le réviser à partir des résultats réels et le plan actif devient ensuite l'autorité prévisionnelle.

0.3.5-alpha.1 — audit WebTransport/QUIC et design du POC

• audit stable 0.3.4 ;
• recherche des stacks actuelles ;
• matrice plateforme/TLS/runtime ;
• challenge du contrat commun ;
• stratégie fallback ;
• métriques et gates ;
• plan actif.

Aucun backend lourd n'est créé avant fermeture de ces décisions.

0.3.5-alpha.2 — backend minimal et loopback

Si alpha.1 confirme la viabilité :

• créer le backend retenu avec dépendances minimales ;
• établir client/server local ;
• transporter un payload binaire ;
• close/cancellation et erreurs de base ;
• tests loopback déterministes ;
• tracing dédié.

Si le contrat commun ne convient pas, documenter le besoin avant de le modifier.

0.3.5-alpha.3 — plateforme/fallback réel

Selon les résultats :

• preuve navigateur/WASM si elle est techniquement et opérationnellement réalisable ;
• ou preuve native plus complète si le navigateur exige une infrastructure disproportionnée à cette tranche ;
• fallback WebSocket au niveau d'ownership retenu ;
• tests des deux chemins sans couplage au gameplay.

Cette tranche peut être fusionnée ou scindée selon TLS/certificats et tooling réellement nécessaires.

0.3.5-alpha.4 — mesures et robustesse conditionnelles

Si nécessaire :

• mesures WebSocket vs WebTransport/QUIC ;
• streams vs datagrams lorsque réellement supportés ;
• limites, timeouts, backpressure et peer drop ;
• smoke runtime/benchmark borné ;
• décision documentée sur la valeur réelle du second transport.

Ne pas créer cette tranche si alpha.2/alpha.3 ferment déjà ces preuves proprement.

0.3.5-beta.1 — validation large

• workspace complet ;
• smokes réellement retenus ;
• graphes de dépendances ;
• vérification qu'aucun gameplay/engine ne dépend d'un backend concret ;
• comparaison et limitations documentées.

Un défaut fermé produit beta.1.fix.N. Une capacité majeure manquante réouvre une alpha.

0.3.5-rc.1 — candidate gelée

• aucun nouveau comportement volontaire ;
• consolidation durable ;
• CHANGELOG.md ;
• ROADMAP.md si statut macro à réconcilier ;
• historique beta ;
• prompt 0.3.6 préparant la consolidation des POC plateforme/réseau ;
• gates de publication proportionnelles aux changements depuis beta.

0.3.5 — stable

Promotion autant que possible mécanique : version stable, historique RC, changelog stable, clôture du plan, roadmap, delta final et ajustement mécanique du prompt 0.3.6.

18. Critère de réussite produit de 0.3.5

La version est réussie même si la conclusion est de ne pas adopter WebTransport immédiatement, à condition que le POC fournisse une réponse technique solide et reproductible.

La décision finale doit pouvoir distinguer clairement :

• WebTransport/QUIC retenu comme second backend utile ;
• viable mais reporté faute de bénéfice suffisant ou de contraintes plateforme/infrastructure ;
• non viable pour la trajectoire actuelle ;
• besoin d'une étude complémentaire explicitement reportée.

Le résultat ne doit jamais être forcé pour justifier le temps investi dans le POC.