khadhroony-solana-project/deltas/0.2.7/pre.007-fix.001.md

Delta 0.2.7-pre.007-fix.001 — représentation reconnect compacte + canari oversized aligné

1. Base requise

0.2.7-pre.007 appliqué
workspace.package.version = 0.2.7-pre.7

Le checkpoint opérateur de pre.007 a établi :

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 :

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 :

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é :

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 :

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 :

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

Cargo.toml
crates/ksp-onchain-transport-lib/src/ws_session.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_session.rs

7. Fichier ajouté

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

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