v0.2.7-pre.007-fix.001

deltas/0.2.7/pre.007-fix.001.md

@@ -0,0 +1,139 @@
+<!-- file: deltas/0.2.7/pre.007-fix.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.7-pre.007-fix.001` — représentation reconnect compacte + canari oversized aligné
+
+## 1. Base requise
+
+```text
+0.2.7-pre.007 appliqué
+workspace.package.version = 0.2.7-pre.7
+```
+
+Le checkpoint opérateur de `pre.007` a établi :
+
+```text
+cargo fmt --all                           exécuté
+python3 scripts/audit_rust_workspace_rules.py   clean
+cargo check --workspace                  réussi
+cargo clippy --workspace --all-targets   réussi avec 2 warnings large_enum_variant
+cargo test -p ksp-onchain-transport-lib  282 réussis, 1 échoué
+cargo test --workspace                   échoue sur le même canari Transport
+```
+
+Le seul test en échec est :
+
+```text
+websocket_oversized_inbound_frame_fails_before_json_decode
+```
+
+## 2. Diagnostic du canari oversized
+
+Le canari provenait de `pre.005`, où une erreur de frame WebSocket conduisait directement la session physique à l'état terminal `Failed`.
+
+`pre.007` a volontairement changé ce contrat : une erreur physique, I/O, TLS, WebSocket ou protocolaire structurelle entre désormais dans le budget de reconnect. Une frame entrante dépassant `max_frame_size` est donc toujours rejetée par Tungstenite avant le décodage JSON, mais l'actor doit ensuite tenter la reconnexion au lieu de devenir immédiatement terminal.
+
+L'ancienne assertion :
+
+```text
+oversized frame -> Failed
+```
+
+était devenue incompatible avec la politique runtime acquise par `pre.007`.
+
+## 3. Correctif du canari oversized
+
+Le fixture local accepte désormais deux connexions physiques :
+
+1. la connexion initiale envoie une frame texte de 512 octets alors que `max_frame_size = 64` ;
+2. l'actor détecte la rupture provoquée par la limite Tungstenite et entre en reconnect ;
+3. le serveur accepte la connexion de remplacement ;
+4. le caller attend `continuity_gap_count == 1` et le retour à `WsSessionState::Active` ;
+5. la session récupérée est fermée explicitement avec `WsSession::close()`.
+
+Le canari est renommé :
+
+```text
+websocket_oversized_inbound_frame_triggers_reconnect_before_json_decode
+```
+
+Il vérifie ainsi simultanément que la limite est appliquée avant le parse JSON et que le nouveau lifecycle reconnect de `pre.007` est respecté.
+
+## 4. Warnings `large_enum_variant`
+
+Clippy signalait deux enums internes dont la variante `Connected` embarquait directement le type lourd `WsPhysicalStream` :
+
+```text
+WsReconnectOutcome
+WsConnectAttemptOutcome
+```
+
+Le socket est désormais stocké derrière `Box<WsPhysicalStream>` uniquement dans ces objets de résultat transitoires, puis immédiatement déboxé lorsque l'actor reprend la propriété de la connexion.
+
+Ce changement :
+
+- réduit fortement la taille des enums ;
+- supprime les warnings `clippy::large_enum_variant` ;
+- ne change ni la propriété du socket, ni la cardinalité des sessions, ni la sémantique reconnect ;
+- n'ajoute aucune allocation persistante autour du socket une fois celui-ci réinstallé dans l'actor.
+
+## 5. Signal technique
+
+Le fix modifie du Rust et des tests. Conformément aux règles KSP :
+
+```text
+livraison                 = 0.2.7-pre.007-fix.001
+workspace.package.version = 0.2.7-pre.7.fix.1
+commit                    = v0.2.7-pre.007-fix.001
+```
+
+Aucun tag prerelease.
+
+## 6. Fichiers modifiés
+
+```text
+Cargo.toml
+crates/ksp-onchain-transport-lib/src/ws_session.rs
+crates/ksp-onchain-transport-lib/unit_tests/ws_session.rs
+```
+
+## 7. Fichier ajouté
+
+```text
+deltas/0.2.7/pre.007-fix.001.md
+```
+
+## 8. Fichiers supprimés
+
+Aucun.
+
+## 9. Invariants préservés
+
+Le fix ne change pas :
+
+- les APIs publiques `WsSession` et `WsSubscription<T>` ;
+- les IDs locaux et remote ;
+- le mapping remote vers local ;
+- la politique `ActiveSubscriptions` ou `Never` ;
+- le budget, le calcul ou le reset du reconnect ;
+- l'ordre déterministe des resubscriptions ;
+- la priorité de l'unsubscribe local ;
+- la sémantique des continuity gaps ;
+- les frontières de dépendances ;
+- la façade de logging KSP ;
+- le scope de `pre.008` et des wrappers publics ultérieurs.
+
+## 10. Validation sandbox
+
+Le sandbox ne permet pas de revendiquer les gates Cargo opérateur. Les contrôles statiques disponibles sont exécutés sur le workspace reconstruit avec ce fix.
+
+## 11. Validation opérateur attendue
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-onchain-transport-lib
+cargo test --workspace
+```