8.2 KiB
Delta 0.2.8-pre.001-fix.001 — séparation des façades WebSocket et forecast visible
1. Base requise
Ce correctif s'applique exclusivement après :
0.2.8-pre.001
workspace.package.version = 0.2.8-pre.1
Il corrige le plan et la matrice de validation de pre.001 avant toute implémentation de pre.002.
Le correctif est documentaire uniquement. Conformément à VER-ID-008 :
livraison = 0.2.8-pre.001-fix.001
workspace.package.version = 0.2.8-pre.1 # inchangé
commit attendu = v0.2.8-pre.001-fix.001
2. Motif du fix
Le plan initial faisait porter à un WsSession public commun toute la surface WebSocket, puis utilisait une capability matrix pour rejeter avant I/O les méthodes standard non supportées par Helius.
Après revue du code réel v0.2.7, cette forme est jugée trop permissive au niveau API : les neuf wrappers standard sont directement implémentés sur WsSession. Un endpoint Helius aurait donc pu être représenté par un type exposant publiquement block_subscribe, slots_updates_subscribe et vote_subscribe, même si ces appels étaient ensuite rejetés.
Décision corrigée :
séparer les façades publiques par protocole
partager intégralement le moteur physique/lifecycle
rendre les méthodes provider non supportées absentes de la façade Helius
conserver une validation interne defense-in-depth
3. Architecture corrigée
Cible :
WsSession
moteur physique partagé
actor/socket/reconnect/queues
│
┌────────────┴────────────┐
▼ ▼
SolanaStandardWsSession HeliusLaserStreamWsSession
9 familles 6 standard communes
+ transaction
+ heartbeat policy
Surface standard
Account
Block
Logs
Program
Root
Signature
Slot
SlotsUpdates
Vote
Surface Helius
Account
Logs
Program
Root
Signature
Slot
HeliusTransaction
Absents de la façade Helius :
Block
SlotsUpdates
Vote
Les DTOs standard réellement identiques restent partagés. Les DTOs Helius sont créés uniquement pour les contrats provider-specific (transactionSubscribe, tokenAccounts, notification transaction, etc.).
WsSession reste compatible avec la surface standard publiée en 0.2.7. La façade Helius ne doit fournir aucun escape hatch public (inner/into_inner) qui permettrait de récupérer un handle générique et de contourner sa surface.
4. Capability matrix — rôle corrigé
La capability matrix n'est plus la première barrière publique. Elle devient une protection interne :
API/façade correcte
-> méthodes impossibles absentes
-> validation descriptor/constructor avant I/O
-> actor commun
Matrice interne conservée :
SolanaStandard:
Account Block Logs Program Root Signature Slot SlotsUpdates Vote -> allowed
HeliusTransaction -> rejected
HeliusLaserStream:
Account Logs Program Root Signature Slot HeliusTransaction -> allowed
Block SlotsUpdates Vote -> rejected
5. Gate Cargo désormais fermé
Les commandes manquantes de pre.001 ont été fournies par l'opérateur :
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
Résolution observée :
futures-util 0.3.34
tokio 1.53.1
tokio-tungstenite 0.30.0
reqwest 0.13.4
new Helius SDK aucun
Doublons ciblés :
syn 2.0.119 / 3.0.3
webpki-roots 0.26.11 / 1.0.9
Ils sont transitifs dans le graphe actuel et ne bloquent pas le gate.
Verdict : gate pre.001 positif après ce fix documentaire.
6. Forecast souple recalibré
Le forecast revient à pre.001 -> pre.011 parce que la séparation de façade mérite une tranche propre et que les six wrappers standard supportés par Helius doivent être validés séparément de la mécanique de connexion commune.
pre.001 audit/sizing/matrice/dependencies
pre.001-fix.001 architecture de façades + gate Cargo + forecast visible
pre.002 socle protocolaire : protocol kind + façades + connexion physique partagée
pre.003 6 familles standard Helius + absence typée Block/SlotsUpdates/Vote
pre.004 Config V2 helius_laserstream + secret strategy
pre.005 transactionSubscribe/unsubscribe request/filter/options/tokenAccounts
pre.006 transactionNotification + reconnect/resubscribe/unsubscribe races
pre.007 heartbeat/idle lifecycle
pre.008 adversarial provider/security/backpressure
pre.009 compliance + standard WS 18/18 + HTTP 52/14 + Config/API canaries
pre.010 live smoke opt-in si sûr + README/USAGE + dependency audit
pre.011 workspace final + fermeture docs/matrix/indexes + prompt 0.2.9
rel.001 stable
Chaque tranche vise nominalement 15–20 minutes. Le plan contient désormais un tableau immédiatement visible avec objectif, preuves, budget et critères de split pour chaque tranche.
pre.011 n'est pas une deadline ; pre.012+ ou des fixes sont ajoutés si nécessaire.
7. Fichiers ajoutés
deltas/0.2.8/pre.001-fix.001.md
8. Fichiers modifiés
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
9. Fichiers volontairement inchangés
Cargo.toml
ROADMAP.md
CHANGELOG.md
.env.example
config/**
crates/**
docs/000-README.md
docs/plans/000-README.md
docs/validation/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
deltas/0.2.8/pre.001.md
Le delta pre.001 publié reste immutable ; ce fix ne le réécrit pas.
10. Validations et preuves
Réellement fournies par l'opérateur avant ce fix
baseline v0.2.7 : fmt/audit/check/clippy/test workspace = OK
cargo tree transport = exécuté
cargo tree transport --duplicates = exécuté
Réellement exécutées dans l'environnement de préparation du fix
inspection du code public WsSession/WsSubscriptionKind/WsSessionSnapshot = OK
lecture VERSION_WORKFLOW.md pour VER-ID-008 = OK
contrôle overlay documentaire = OK
L'audit Rust workspace est réexécuté sur le workspace reconstitué après application de l'overlay lorsque le script est disponible.
Non exécutées pour ce fix documentaire
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
Motif : aucun code/build/runtime/config n'est modifié par ce correctif et l'environnement de préparation ne fournit pas Cargo.
11. Décisions prises
façades publiques séparées par protocole
moteur WsSession actor unique partagé
SolanaStandardWsSession = 9 familles standard
HeliusLaserStreamWsSession = 6 familles standard + transaction
Block/SlotsUpdates/Vote absents de la façade Helius
capability matrix conservée defense-in-depth
DTOs communs réutilisés si wire identique
DTOs Helius dédiés seulement aux divergences
pas d'escape hatch Helius vers raw WsSession
forecast visible et recalibré jusqu'à pre.011
Cargo pre.1 inchangé car fix documentaire
12. Questions ouvertes laissées à pre.002+
forme interne minimale pour partager la connexion physique sans dupliquer l'actor
forme exacte des constructeurs des deux façades
extension minimale de WsSubscriptionKind/snapshot pour HeliusTransaction
forme typed des différents transactionDetails insuffisamment documentés
wire éventuel futur de enhanced/filtered accountSubscribe
Ces questions ne remettent pas en cause la frontière décidée : surface publique séparée, moteur physique partagé.
13. Prochaine tranche
0.2.8-pre.002
Mission : matérialiser uniquement le socle protocolaire et les façades/constructeurs autour du moteur WsSession existant. Ne pas commencer transactionSubscribe ni Config Helius dans cette tranche.