0.3.5-alpha.10

docs/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/000-README.md -->
-<!-- version: 35 -->
+<!-- version: 36 -->
 
 # Documentation games.sasedev
 
@@ -12,6 +12,7 @@
 - [`ideas/000-README.md`](ideas/000-README.md) — rôle des idées non engagées et règles de maturation.
 - [`studies/000-README.md`](studies/000-README.md) — rôle des études comparatives non normatives.
 - [`studies/026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md`](studies/026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md) — audit `0.3.5` des stacks WebTransport/QUIC, du contrat transport, de TLS et des plateformes.
+- [`studies/027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md`](studies/027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md) — méthode `0.3.5-alpha.10` de caractérisation loopback WebSocket/WebTransport fiable et datagram séparé.
 
 ## Plans
 

docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md

@@ -1,11 +1,11 @@
 <!-- file: docs/plans/005-V0_3_5_WEBTRANSPORT_QUIC_POC_PLAN.md -->
-<!-- version: 15 -->
+<!-- version: 16 -->
 
 # Plan 0.3.5 — POC WebTransport/QUIC et fallback WebSocket
 
 ## Statut
 
-Plan actif créé pendant `0.3.5-alpha.1` à partir de l'archive taggée `v0.3.4`, puis réconcilié pour l'implémentation native de `0.3.5-alpha.2`, son correctif de validation `0.3.5-alpha.2.fix.1`, le chemin fiable validé de `0.3.5-alpha.3`, la robustesse validée par `0.3.5-alpha.4.fix.1`, le smoke natif validé de `0.3.5-alpha.5`, le chemin client WASM validé de `0.3.5-alpha.6`, le smoke navigateur validé par `0.3.5-alpha.7.fix.2`, la composition/fallback WebSocket validée par `0.3.5-alpha.8.fix.1` et le POC datagram backend-spécifique de `0.3.5-alpha.9`, corrigé par `0.3.5-alpha.9.fix.1` après la gate Clippy.
+Plan actif créé pendant `0.3.5-alpha.1` à partir de l'archive taggée `v0.3.4`, puis réconcilié pour l'implémentation native de `0.3.5-alpha.2`, son correctif de validation `0.3.5-alpha.2.fix.1`, le chemin fiable validé de `0.3.5-alpha.3`, la robustesse validée par `0.3.5-alpha.4.fix.1`, le smoke natif validé de `0.3.5-alpha.5`, le chemin client WASM validé de `0.3.5-alpha.6`, le smoke navigateur validé par `0.3.5-alpha.7.fix.2`, la composition/fallback WebSocket validée par `0.3.5-alpha.8.fix.1`, le POC datagram backend-spécifique validé par `0.3.5-alpha.9.fix.1`, puis la caractérisation comparative bornée de `0.3.5-alpha.10`.
 
 Le cadrage détaillé et la comparaison des stacks actuelles sont conservés dans `docs/studies/026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md`. Le présent document porte les décisions opérationnelles, le scope, les gates et le forecast vivant de la version.
 
@@ -555,12 +555,20 @@ Correctif `0.3.5-alpha.9.fix.1` : la gate utilisateur de `alpha.9` confirme fmt/
 
 ### `0.3.5-alpha.10` — mesures comparatives bornées
 
-- launcher/outil minimal de mesure ;
-- WebSocket vs WebTransport fiable ;
-- établissement, RTT, throughput, messages en vol ;
-- datagram seulement s'il existe réellement ;
-- résultats et limites de méthode documentés ;
-- conclusion technique provisoire `retain/defer/reject`.
+La tranche ajoute `game-realtime-transport-measure`, un outil localhost déterministe qui ne modifie aucun backend et ne publie aucune API commune nouvelle. La méthode est figée ainsi :
+
+- 8 établissements complets par backend ; WebTransport inclut la session QUIC/HTTP3 et l'ouverture du stream primaire, WebSocket inclut le handshake ;
+- RTT fiable : 16 warmups puis 128 ping/pong de 32 octets ;
+- throughput fiable : 128 messages de 64 KiB, soit 8 MiB utiles, avec ACK final après drainage côté serveur ;
+- fenêtre applicative sans ACK intermédiaire : 64 messages de 1 KiB ;
+- datagram WebTransport séparé : 64 envois de taille `min(256, max_datagram_size client, max_datagram_size serveur)`, nombre reçu observé sous deadline locale ;
+- sortie textuelle stable `MEASURE ...` suivie de `game-realtime-transport-measure: PASS`.
+
+Les métriques fiables utilisent strictement `RealtimeConnection`; le chemin datagram reste sur `WebTransportSession`. Les chiffres sont une caractérisation loopback de la machine qui exécute la gate, pas un benchmark Internet/mobile ni une preuve de supériorité d'un protocole. Aucun seuil arbitraire de victoire n'est introduit.
+
+La conclusion technique provisoire est **`retain`** : conserver WebTransport comme second backend à côté de WebSocket pour la suite du projet, compte tenu du chemin natif+navigateur validé, du fallback classifié et de la capacité datagram optionnelle. Cette conclusion ne signifie pas « WebTransport est plus rapide » ; les mesures de la gate utilisateur seront enregistrées dans l'historique après exécution.
+
+La méthode, le format des résultats et leurs limites sont détaillés dans `docs/studies/027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md`.
 
 ### `0.3.5-beta.1` — validation large
 

docs/studies/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/studies/000-README.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
 # Études
 
@@ -69,3 +69,4 @@ Ces documents étudient les POC à réaliser ; ils ne lancent encore aucune impl
 ## Étude de cadrage 0.3.5
 
 - [`026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md`](026-V0_3_5_WEBTRANSPORT_QUIC_STACK_AUDIT.md) — audit de la stable `0.3.4`, comparaison des stacks WebTransport/QUIC actuelles, compatibilité du contrat realtime, TLS, navigateurs et sizing de `0.3.5`.
+- [`027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md`](027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md) — méthode bornée de mesure loopback WebSocket/WebTransport de `alpha.10`, datagrams séparés et limites d’interprétation.

docs/studies/027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md

@@ -0,0 +1,191 @@
+<!-- file: docs/studies/027-V0_3_5_REALTIME_TRANSPORT_MEASUREMENT.md -->
+<!-- version: 1 -->
+
+# Étude 0.3.5 — caractérisation bornée WebSocket / WebTransport
+
+## Objet
+
+Cette étude définit la méthode de `0.3.5-alpha.10`. Elle ne cherche pas à produire un benchmark général de WebSocket contre WebTransport, mais à caractériser les deux implémentations **dans games.sasedev**, sur loopback, avec le même contrat fiable et des charges bornées.
+
+Les valeurs dépendent de la machine, du kernel, du scheduler, du profil Cargo et de l'état local du système. Elles ne doivent pas être extrapolées à un réseau mobile, à Internet, à un navigateur distant ou à une charge serveur multi-utilisateur.
+
+## Outil
+
+Le launcher technique est :
+
+```text
+crates/apps/game-realtime-transport-measure
+```
+
+Exécution de référence :
+
+```bash
+cargo run --release -p game-realtime-transport-measure
+```
+
+Le profil `--release` est recommandé pour réduire le poids du code de mesure lui-même. La gate peut aussi exécuter le profil debug pour vérifier le fonctionnement, mais les chiffres debug ne doivent pas être comparés à des chiffres release.
+
+## Préparation commune
+
+Les deux chemins fiables utilisent leurs configurations produit par défaut et le contrat `RealtimeConnection`.
+
+WebSocket :
+
+```text
+TCP loopback
+ws://127.0.0.1:<port>/measure
+Tokio + tokio-tungstenite
+```
+
+WebTransport :
+
+```text
+UDP loopback
+https://127.0.0.1:<port>/measure
+QUIC + HTTP/3
+certificat P-256 loopback en mémoire
+pin SHA-256 exact
+stream bidirectionnel primaire
+```
+
+L'outil ne configure ni loss artificiel, ni jitter, ni bandwidth shaping.
+
+## Établissement
+
+Pour chaque backend :
+
+```text
+samples = 8
+```
+
+WebSocket mesure du début du connect/accept jusqu'à la connexion établie après handshake.
+
+WebTransport mesure jusqu'au chemin fiable utilisable : session WebTransport établie **et** stream bidirectionnel primaire ouvert/accepté.
+
+Le rapport fournit :
+
+```text
+min_us
+median_us
+p95_us
+max_us
+```
+
+Les premières connexions peuvent inclure des coûts froids ; aucun échantillon d'établissement n'est supprimé.
+
+## RTT fiable
+
+Charge :
+
+```text
+warmup = 16
+samples = 128
+payload = 32 octets
+```
+
+Le client envoie un message et attend l'écho exact avant d'envoyer le suivant. Seuls les 128 échantillons post-warmup entrent dans le résumé.
+
+Le résultat mesure donc le RTT applicatif du contrat `RealtimeConnection`, pas le RTT brut TCP/QUIC.
+
+## Throughput fiable
+
+Charge :
+
+```text
+messages = 128
+payload = 64 KiB
+volume utile = 8 MiB
+```
+
+Le client envoie les messages sans ACK applicatif intermédiaire. Le serveur draine exactement les 128 messages puis renvoie un ACK final. Le chronomètre client s'arrête à réception de cet ACK.
+
+Le résultat fournit :
+
+```text
+elapsed_us
+mib_per_s
+messages_per_s
+```
+
+Il inclut le framing du backend, les copies/allocation du POC et la backpressure réellement appliquée par les wrappers.
+
+## Fenêtre de messages en vol
+
+Charge :
+
+```text
+messages = 64
+payload = 1 KiB
+```
+
+Le client émet 64 messages sans ACK applicatif intermédiaire, puis attend un ACK unique après drainage côté serveur.
+
+Cette mesure ne prétend pas connaître le nombre exact de paquets réseau simultanément en vol. Elle valide une **fenêtre applicative bornée de 64 messages non acquittés individuellement** et rapporte son temps de complétion.
+
+## Datagram WebTransport
+
+Le datagram est mesuré séparément du contrat fiable :
+
+```text
+attempted = 64
+payload = min(256, client_max_datagram_size, server_max_datagram_size)
+```
+
+Le client émet les 64 datagrams puis le serveur les reçoit jusqu'à atteindre 64 ou jusqu'à une attente locale de 250 ms sans nouveau datagram.
+
+Le rapport fournit :
+
+```text
+attempted
+received
+receive_ratio
+payload_bytes
+client_max
+server_max
+elapsed_us
+```
+
+`receive_ratio = 1.0` sur loopback ne transforme pas les datagrams en transport fiable. Une perte observée n'est pas automatiquement un défaut de protocole : elle doit être interprétée avec la sémantique non fiable de WebTransport.
+
+## Format de sortie
+
+Chaque mesure utilise une ligne stable :
+
+```text
+MEASURE transport=<...> metric=<...> ...
+```
+
+La fin normale est :
+
+```text
+CONCLUSION webtransport=retain scope=second-backend reason=reliable-browser-fallback-datagram-capabilities
+game-realtime-transport-measure: PASS
+```
+
+## Lecture des résultats
+
+Aucun seuil automatique « gagnant/perdant » n'est défini. Une différence loopback de quelques microsecondes ou quelques pourcents n'a pas de valeur produit suffisante à elle seule.
+
+Les dimensions utiles sont :
+
+- absence d'échec ou de timeout inattendu ;
+- ordre de grandeur de l'établissement ;
+- stabilité médiane/p95 du RTT ;
+- absence d'effondrement évident du throughput fiable ;
+- capacité à soutenir la fenêtre applicative bornée ;
+- observation distincte de la capacité datagram.
+
+## Conclusion technique provisoire
+
+Décision `alpha.10` : **retain**.
+
+Cela signifie : conserver WebTransport comme second backend realtime expérimental/évolutif à côté de WebSocket. Cette décision repose sur l'ensemble des preuves `0.3.5` déjà acquises :
+
+- backend natif fiable ;
+- client navigateur/WASM ;
+- smoke navigateur réel ;
+- robustesse et deadlines ;
+- fallback WebSocket strictement classifié ;
+- datagrams optionnels backend-spécifiques.
+
+Cette conclusion **ne signifie pas** que WebTransport est déclaré plus rapide que WebSocket. Les chiffres de `alpha.10` servent à détecter des écarts grossiers et à documenter la baseline locale avant la validation large `beta.1`.