0.2.0-0-pre.2-fix.1

docs/rules/RULES_DOCUMENTATION.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_DOCUMENTATION.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Règles de documentation
 
@@ -12,6 +12,9 @@
 - **DOC-005** — Les documents de validation résident sous `docs/validation/`.
 - **DOC-006** — Les documents internes sont en français ; code, symboles et extraits techniques conservent leur langue naturelle.
 - **DOC-007** — Les tableaux Markdown suivent le format contrôlé par `scripts/audit_markdown_tables.py`.
+- **DOC-009** — La ligne séparatrice d'un tableau explicite l'alignement sémantique de chaque colonne : `:---` pour le texte aligné à gauche, `---:` pour les valeurs numériques alignées à droite et `:---:` pour une valeur courte dont le centrage est réellement pertinent.
+- **DOC-010** — Une colonne textuelle n'est pas centrée uniquement pour des raisons esthétiques ; les matrices documentaires utilisent par défaut l'alignement gauche explicite.
+- **DOC-011** — Les tableaux d'un même document conservent une convention d'alignement cohérente par type de donnée.
 - **DOC-008** — Deux lignes blanches consécutives sont interdites hors blocs de code.
 
 ## Catégories documentaires

docs/studies/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/000-README.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Études
 
@@ -23,5 +23,6 @@ Les études conservent les alternatives et raisons utiles à la compréhension f
 - [`003-PLATFORM_CAPABILITY_STUDY.md`](003-PLATFORM_CAPABILITY_STUDY.md) — axes plateforme/device/host/backend et disponibilité des capacités.
 - [`004-GAME_ARCHETYPE_PRESSURE_TEST.md`](004-GAME_ARCHETYPE_PRESSURE_TEST.md) — vérification du modèle par plusieurs familles de jeux.
 - [`005-DEPENDENCY_AND_COMPOSITION_STUDY.md`](005-DEPENDENCY_AND_COMPOSITION_STUDY.md) — dépendances autorisées et composition statique envisagée.
+- [`006-REALTIME_MULTIPLAYER_SERVER_STUDY.md`](006-REALTIME_MULTIPLAYER_SERVER_STUDY.md) — transport, session, synchronisation, autorité, resync et scaling du multijoueur temps réel.
 
 Ces études sont des propositions à relire. Elles ne deviennent pas automatiquement des décisions d'architecture.

docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/001-FUNCTIONAL_CAPABILITY_INVENTORY.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Inventaire fonctionnel initial
 
@@ -331,21 +331,96 @@ Aucun provider ne doit remonter dans le kernel.
 
 ## Server services candidates
 
+### Services Web non temps réel
+
 Besoins identifiés :
 
 - auth/identity ;
 - profile ;
 - save/progression cloud ;
 - leaderboard ;
-- match/lobby ;
-- realtime authoritative session ;
-- chat éventuel ;
+- inventory/economy authoritative lorsqu'une valeur partagée existe ;
+- configuration/rulesets distants ;
 - asset metadata/CDN orchestration ;
 - administration/modération selon besoins ;
-- anti-cheat/validation serveur pour compétitif ;
-- économie/reward authority pour tout jeu avec valeur monétaire ou crypto.
+- anti-cheat/validation de résultats ;
+- reward authority pour tout jeu avec valeur monétaire ou crypto.
 
-Le déploiement peut commencer comme modular monolith sans imposer le découpage physique initial.
+Ces services peuvent être exposés en HTTP(S) et ne doivent pas être placés dans la boucle temps réel uniquement parce qu'un jeu possède aussi un mode multijoueur.
+
+### Lobby / matchmaking / session control
+
+Besoins identifiés :
+
+- création et découverte de partie ;
+- invitation/join/leave ;
+- matchmaking ;
+- allocation d'une room/session ;
+- roster de joueurs ;
+- ready/start/end ;
+- reprise de session ;
+- spectator policy éventuelle ;
+- routing vers l'instance realtime responsable.
+
+Le control plane d'une partie peut être séparé du data plane temps réel.
+
+### Realtime multiplayer server
+
+Capacités à étudier explicitement :
+
+- endpoint/gateway WebSocket ou transport realtime équivalent ;
+- authentification et attachement d'une connexion à une session ;
+- ingestion d'inputs/commands client plutôt que confiance dans un état client arbitraire ;
+- tick ou cadence serveur ;
+- simulation/état authoritative lorsque le jeu l'exige ;
+- ordre des messages, sequence numbers et déduplication ;
+- acknowledgement lorsque nécessaire ;
+- snapshots complets ;
+- deltas/patches entre snapshots ;
+- version/revision de l'état ;
+- interest management pour ne diffuser qu'un sous-ensemble pertinent du monde ;
+- broadcast/multicast par room ;
+- backpressure et limites de file ;
+- détection de timeout/heartbeat ;
+- disconnect/reconnect ;
+- reprise et resynchronisation après trou de messages ;
+- late join ;
+- spectator éventuel ;
+- historique court/replay buffer lorsque nécessaire ;
+- validation anti-cheat des inputs/actions ;
+- séparation entre données persistantes et état éphémère de session ;
+- métriques, logs, traces et health du service temps réel ;
+- horizontal scaling, room placement et transfert/rehydration éventuel d'une session.
+
+### Synchronisation client associée
+
+Les capacités client correspondantes peuvent inclure :
+
+- buffer d'inputs ;
+- interpolation ;
+- extrapolation limitée ;
+- client-side prediction ;
+- reconciliation ;
+- rollback pour les genres qui le justifient ;
+- clock/tick synchronization ;
+- snapshot application ;
+- delta application ;
+- reconnect/resync state machine.
+
+Toutes ne sont pas nécessaires pour tous les jeux. Par exemple Snake à faible fréquence, racing et fighting n'ont pas les mêmes exigences de latence ni la même stratégie de synchronisation.
+
+### Chat et présence
+
+À séparer du gameplay realtime :
+
+- présence online/offline ;
+- chat lobby ;
+- chat de partie ;
+- modération ;
+- rate limiting ;
+- historique selon produit.
+
+Le déploiement peut commencer comme modular monolith, mais les responsabilités doivent rester séparables afin que le service realtime puisse évoluer indépendamment du Web/API classique.
 
 ## Tooling candidates
 

docs/studies/003-PLATFORM_CAPABILITY_STUDY.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/003-PLATFORM_CAPABILITY_STUDY.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Étude plateforme et disponibilité des capacités
 
@@ -55,7 +55,7 @@ Le backend n'est pas l'identité du jeu.
 ## Cibles connues
 
 | Cible | OS/environnement | Device | Execution | Host | Backend principal |
-| --- | --- | --- | --- | --- | --- |
+| :--- | :--- | :--- | :--- | :--- | :--- |
 | Desktop SDL Linux | Linux | Desktop | Native | Native | SDL3 |
 | Desktop SDL Windows | Windows | Desktop | Native | Native | SDL3 |
 | Desktop SDL macOS | macOS | Desktop | Native | Native | SDL3, réservé |
@@ -117,6 +117,19 @@ HTTP/WebSocket sont plausibles sur toutes les grandes cibles mais leur implémen
 
 Le protocole métier reste indépendant du transport.
 
+Pour le multijoueur temps réel, le support d'un WebSocket côté plateforme ne suffit pas à définir la synchronisation. Le client doit pouvoir se connecter à une session distante qui possède ses propres contrats de tick, sequencing, snapshots/deltas, reconnexion et resynchronisation.
+
+Les contraintes navigateur/mobile/desktop peuvent modifier :
+
+- la durée de vie d'une connexion ;
+- la suspension en arrière-plan ;
+- les timeouts ;
+- les politiques de reconnexion ;
+- la disponibilité de threads/timers ;
+- les stratégies de buffering.
+
+Ces différences appartiennent aux adapters/runtime et ne doivent pas modifier le protocole de gameplay lui-même.
+
 ## Politique de disponibilité candidate
 
 Une capability produit peut être :

docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/004-GAME_ARCHETYPE_PRESSURE_TEST.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Pressure test par archétypes de jeux
 
@@ -97,7 +97,11 @@ Besoins :
 - matchmaking/lobby ;
 - session realtime ;
 - serveur authoritative pour compétition ;
-- reconnect/spectator éventuellement ;
+- tick serveur et sequencing des inputs ;
+- snapshots/deltas ;
+- interpolation et éventuellement prediction/reconciliation ;
+- reconnect/resync ;
+- spectator éventuellement ;
 - leaderboard.
 
 Conclusion provisoire :
@@ -114,6 +118,9 @@ Besoins :
 - health ;
 - move/state machine ;
 - rollback ou autre stratégie réseau si online compétitif ;
+- tick/frames synchronisés ;
+- input delay ou prediction selon modèle retenu ;
+- reconnect policy spécifique au match ;
 - matchmaking.
 
 Conclusion provisoire :
@@ -144,7 +151,10 @@ Besoins potentiels :
 - monde persistant ;
 - inventory/economy ;
 - serveur authoritative ;
+- gateway/session routing ;
 - zones/instances ;
+- interest management ;
+- snapshots/deltas et resynchronisation ;
 - chat ;
 - parties/guildes éventuelles ;
 - patch/assets distants ;

docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/005-DEPENDENCY_AND_COMPOSITION_STUDY.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Étude des dépendances et de la composition
 
@@ -156,6 +156,37 @@ crates/
 
 Cette arborescence est une hypothèse d'étude. Elle n'est pas encore un contrat de fichiers.
 
+
+## Realtime : séparation des responsabilités
+
+Le temps réel ne doit pas être représenté par une seule capability `websocket`.
+
+Découpage candidat :
+
+```text
+transport
+    ↓
+wire protocol / message codec
+    ↓
+session protocol
+    ↓
+synchronization strategy
+    ↓
+game-specific authoritative simulation
+```
+
+Responsabilités :
+
+- **transport** — connexion, frames, timeout, reconnexion bas niveau ;
+- **wire protocol** — envelope, version, message ids, serialization ;
+- **session protocol** — join/leave/start/end, identity/session ids, heartbeat ;
+- **synchronization strategy** — tick, input stream, snapshots, deltas, acknowledgement, resync ;
+- **game-specific simulation** — validation des inputs et évolution authoritative du monde selon les règles du jeu.
+
+Le framework peut fournir les couches techniques réutilisables sans imposer une simulation générique identique à Snake, Racing ou Fighting.
+
+Le serveur Web/API classique peut partager des types/protocoles avec le service realtime, mais il ne doit pas obligatoirement partager le même process ni la même cadence d'exécution.
+
 ## Online/offline
 
 La composition doit pouvoir exprimer :

docs/studies/006-REALTIME_MULTIPLAYER_SERVER_STUDY.md

@@ -0,0 +1,321 @@
+<!-- file: docs/studies/006-REALTIME_MULTIPLAYER_SERVER_STUDY.md -->
+<!-- version: 1 -->
+
+# Étude serveur multijoueur temps réel
+
+## Statut
+
+Étude non normative pour `0.2.0-0-pre.2.fix.1`.
+
+Ce document complète l'inventaire initial. Il ne choisit pas encore une stack serveur, un crate WebSocket ou une fréquence de tick unique.
+
+## Objectif
+
+Séparer clairement :
+
+- transport réseau ;
+- protocole de session ;
+- synchronisation d'état ;
+- simulation authoritative ;
+- services Web persistants.
+
+Un WebSocket fournit un canal bidirectionnel ; il ne résout pas à lui seul la synchronisation multijoueur.
+
+## Plan de contrôle et plan de données
+
+### Control plane
+
+Responsabilités plausibles :
+
+- authentification ;
+- matchmaking ;
+- création/allocation de partie ;
+- roster ;
+- invitation/join/leave ;
+- ready/start/end ;
+- sélection d'une instance realtime ;
+- reprise de session.
+
+Ces opérations peuvent passer par HTTP(S), WebSocket ou une combinaison, sans être exécutées dans la boucle de simulation.
+
+### Realtime data plane
+
+Responsabilités plausibles :
+
+- accepter les connexions de joueurs ;
+- associer connexion, joueur et session ;
+- recevoir les inputs/commands ;
+- sequencer les messages ;
+- maintenir le tick/cycle de simulation ;
+- faire évoluer l'état authoritative ;
+- diffuser snapshots et deltas ;
+- détecter pertes/timeouts ;
+- gérer reconnexion et resynchronisation ;
+- appliquer backpressure/rate limits ;
+- produire observability et health.
+
+## Modèles de synchronisation
+
+Aucun modèle unique ne convient à tous les jeux.
+
+### Input authoritative
+
+Le client envoie principalement ses inputs.
+
+Le serveur :
+
+1. valide l'input ;
+2. l'applique à la simulation ;
+3. avance l'état ;
+4. publie l'état ou son delta.
+
+Approprié à de nombreux jeux compétitifs.
+
+### State replication
+
+Le serveur publie :
+
+- snapshots périodiques ;
+- deltas entre snapshots ;
+- revision/tick associé ;
+- éventuellement ack/last-applied revision.
+
+Le client reconstruit un état local de présentation.
+
+### Prediction / reconciliation
+
+Pour réduire la latence perçue :
+
+- le client prédit localement ;
+- conserve les inputs non confirmés ;
+- reçoit l'état serveur ;
+- corrige/rejoue si nécessaire.
+
+À réserver aux jeux qui en ont besoin.
+
+### Rollback
+
+Particulièrement pertinent pour certains jeux de combat :
+
+- historique court d'états ;
+- inputs retardés ou prédits ;
+- rollback/re-simulation.
+
+Ce modèle ne doit pas contaminer le runtime de tous les jeux.
+
+## Contrats techniques candidats
+
+### Envelope réseau
+
+Champs conceptuels possibles :
+
+- protocol version ;
+- message type ;
+- session id ;
+- player id/connection id si nécessaire ;
+- sequence ;
+- server tick ;
+- client tick/time ;
+- payload.
+
+Le format exact n'est pas encore décidé.
+
+### Snapshot
+
+Doit permettre :
+
+- état complet cohérent ;
+- revision/tick ;
+- application atomique côté client ;
+- point de reprise après resync.
+
+### Delta
+
+Doit préciser :
+
+- base revision ;
+- target revision ;
+- mutations ;
+- comportement si la base manque.
+
+Un delta manquant doit conduire à une resynchronisation contrôlée, pas à une divergence silencieuse.
+
+## Reconnexion et resynchronisation
+
+Cas à traiter :
+
+- coupure courte ;
+- suspension mobile ;
+- changement de réseau ;
+- client trop en retard ;
+- trou dans les séquences ;
+- restart d'une instance serveur.
+
+États conceptuels possibles :
+
+```text
+Disconnected
+Connecting
+Joining
+Synchronized
+Resynchronizing
+Leaving
+```
+
+Le jeu ne doit pas confondre « socket ouvert » et « état de gameplay synchronisé ».
+
+## Rooms, instances et scaling
+
+Pour plusieurs parties simultanées :
+
+- une room/session possède une autorité unique à un instant donné ;
+- les connexions sont routées vers l'instance responsable ;
+- l'instance peut héberger plusieurs rooms selon charge ;
+- la distribution des rooms peut évoluer indépendamment du protocole client ;
+- les données persistantes ne doivent pas être écrites dans la DB à chaque tick sans nécessité.
+
+À plus grande échelle, il faudra étudier :
+
+- session placement ;
+- shard/region ;
+- sticky routing ;
+- handoff/migration ;
+- recovery après crash ;
+- autoscaling ;
+- limites par instance.
+
+## Interest management
+
+Pour un petit Snake 2 joueurs, diffuser tout l'état peut être acceptable.
+
+Pour une map plus grande/MMORPG, il faut pouvoir limiter les données à :
+
+- zone visible ;
+- proximité ;
+- équipe ;
+- objets pertinents ;
+- fréquence adaptée au type d'entité.
+
+L'interest management appartient au service realtime/game server, pas au renderer client.
+
+## Persistence
+
+Séparer :
+
+### État éphémère
+
+- positions ;
+- velocities ;
+- animation/state machine ;
+- projectiles ;
+- tick courant.
+
+### État durable
+
+- compte ;
+- progression ;
+- inventory ;
+- résultat de match ;
+- rewards ;
+- classement.
+
+Le durable est persisté à des frontières métier appropriées, pas mécaniquement à chaque frame.
+
+## Sécurité / anti-cheat
+
+Principes candidats :
+
+- ne pas faire confiance à une position envoyée directement par un client compétitif ;
+- valider les actions et contraintes de jeu côté serveur ;
+- rate limit ;
+- protéger join/session tokens ;
+- empêcher replay/double-submit d'actions sensibles ;
+- enregistrer suffisamment de données pour diagnostiquer une divergence ou fraude.
+
+## Observability
+
+Le realtime nécessite au minimum des dimensions dédiées :
+
+- connexions actives ;
+- rooms actives ;
+- joueurs/session ;
+- tick duration ;
+- tick lag ;
+- queue/backpressure ;
+- messages/s ;
+- bytes/s ;
+- reconnects ;
+- resyncs ;
+- dropped/invalid inputs ;
+- snapshot/delta sizes ;
+- errors par protocole/version.
+
+Le logging par domaines devra pouvoir distinguer transport, session, sync et simulation.
+
+## Technologies
+
+Le choix exact reste volontairement ouvert.
+
+Candidats à étudier ultérieurement selon le POC serveur :
+
+- HTTP(S) pour control plane/API ;
+- WebSocket pour data plane bidirectionnel ;
+- gRPC pour backend-to-backend ou services structurés ;
+- WebRTC uniquement si un besoin P2P/media le justifie.
+
+Le framework ne doit pas imposer une technologie unique à tous les services.
+
+## Pressure test rapide
+
+### Snake 2 joueurs
+
+Peut probablement fonctionner avec :
+
+- tick modéré ;
+- inputs directionnels ;
+- état authoritative ;
+- snapshot/delta simple ;
+- interpolation limitée ;
+- reconnect/resync.
+
+### Racing
+
+Exigera potentiellement :
+
+- tick plus fréquent ;
+- prediction/reconciliation ;
+- interpolation ;
+- lag compensation selon gameplay ;
+- snapshots/deltas optimisés.
+
+### Fighting 1v1
+
+Peut nécessiter :
+
+- input synchronization très stricte ;
+- rollback netcode ou stratégie équivalente ;
+- historique court déterministe.
+
+### MMORPG
+
+Exigera potentiellement :
+
+- zones/shards ;
+- interest management ;
+- sessions longues ;
+- persistence structurée ;
+- chat/presence ;
+- recovery/scaling.
+
+## Questions ouvertes pour le futur POC serveur
+
+- Axum + Tokio + WebSocket suffit-il pour le premier service realtime ?
+- Une room est-elle une task, un actor, un shard ou une structure pilotée par scheduler ?
+- Quelle cadence de tick pour chaque genre ?
+- Quel codec : JSON de debug, bincode/postcard/protobuf/autre en production ?
+- Quelle frontière entre types de protocole partagés et logique serveur ?
+- Comment versionner le protocole sans coupler toutes les apps ?
+- Comment tester déterminisme, perte de paquets logique, reconnexion et resync ?
+- Quand introduire Redis/NATS/Kafka ou autre coordination, si jamais nécessaire ?
+
+Ces choix appartiennent à la future planification/POC, pas à cette étude de réservation.