270 lines
8.2 KiB
Markdown
270 lines
8.2 KiB
Markdown
<!-- file: deltas/0.2.8/pre.001-fix.001.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# 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 :
|
||
|
||
```text
|
||
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` :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
WsSession
|
||
moteur physique partagé
|
||
actor/socket/reconnect/queues
|
||
│
|
||
┌────────────┴────────────┐
|
||
▼ ▼
|
||
SolanaStandardWsSession HeliusLaserStreamWsSession
|
||
9 familles 6 standard communes
|
||
+ transaction
|
||
+ heartbeat policy
|
||
```
|
||
|
||
### Surface standard
|
||
|
||
```text
|
||
Account
|
||
Block
|
||
Logs
|
||
Program
|
||
Root
|
||
Signature
|
||
Slot
|
||
SlotsUpdates
|
||
Vote
|
||
```
|
||
|
||
### Surface Helius
|
||
|
||
```text
|
||
Account
|
||
Logs
|
||
Program
|
||
Root
|
||
Signature
|
||
Slot
|
||
HeliusTransaction
|
||
```
|
||
|
||
Absents de la façade Helius :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
API/façade correcte
|
||
-> méthodes impossibles absentes
|
||
-> validation descriptor/constructor avant I/O
|
||
-> actor commun
|
||
```
|
||
|
||
Matrice interne conservée :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```bash
|
||
cargo tree -p ksp-onchain-transport-lib
|
||
cargo tree -p ksp-onchain-transport-lib --duplicates
|
||
```
|
||
|
||
Résolution observée :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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.
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
deltas/0.2.8/pre.001-fix.001.md
|
||
```
|
||
|
||
## 8. Fichiers modifiés
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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+`
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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.
|