khadhroony-solana-project/prompts/013-V0_2_8_START_PROMPT.md

<!-- file: prompts/013-V0_2_8_START_PROMPT.md -->
<!-- version: 2 -->

# Prompt de démarrage `0.2.8` — Helius LaserStream WebSocket

## 1. Identité de la release et base exacte requise

La release à ouvrir est :

```text
0.2.8 — Helius LaserStream WebSocket
```

Elle doit démarrer **uniquement après publication stable de `0.2.7`**.

Base Git attendue :

```text
v0.2.7
```

La base stable doit contenir au minimum :

```text
deltas/0.2.7/rel.001.md
prompts/013-V0_2_8_START_PROMPT.md
```

Si une archive complète du workspace `v0.2.7` est fournie au démarrage de session, **cette archive est autoritaire** par rapport aux souvenirs, snippets, copies de prereleases ou artefacts antérieurs. Vérifier l'état réel avant toute modification.

Ne pas ouvrir `0.2.8` depuis :

```text
0.2.7-pre.*
0.2.7-pre.*-fix.*
un ZIP intermédiaire
une reconstruction depuis mémoire de conversation
une ancienne copie du prompt 0.2.8
```

Signal Cargo initial attendu :

```text
workspace.package.version = "0.2.7"
```

La première livraison de la release sera :

```text
0.2.8-pre.001
Cargo = 0.2.8-pre.1
```

Aucun code fonctionnel lourd ne doit être commencé avant la sortie positive du gate `pre.001` décrit plus bas.

---

## 2. Mission et résultat attendu

`0.2.8` doit étendre le moteur WebSocket déjà stabilisé dans `ksp-onchain-transport-lib` avec la **surface Helius LaserStream WebSocket réellement documentée et supportée au moment de l'audit**, sans dupliquer le client/session actor standard et sans transformer Transport en SDK Helius généraliste.

Le résultat attendu est une extension provider-specific qui :

```text
réutilise le moteur physique WsSession acquis en 0.2.7
préserve les wrappers Solana standard existants
ajoute uniquement les capacités Helius WebSocket réellement auditées
conserve les paramètres/filtres/options Helius utiles sans perte
modélise explicitement les méthodes standard non supportées par Helius
respecte les limites/reconnect/backpressure/shutdown KSP existants
ne fuite jamais api-key, URL complète, query credentials ou payload massif
reste compatible avec Config -> Transport sans dépendance inverse
ne crée aucune dépendance Store/Program/Wallet dans Transport
ne confond jamais LaserStream WebSocket et LaserStream gRPC
```

Le nom produit Helius a évolué : les anciennes « Enhanced WebSockets » sont désormais présentées dans la documentation Helius comme faisant partie de **LaserStream WebSocket**. La session doit donc réauditer la terminologie actuelle au lieu de reprendre mécaniquement les anciens noms.

---

## 3. Sources de vérité internes obligatoires — ordre de lecture

### 3.1 Entrées et règles globales

Lire d'abord, dans cet ordre :

```text
RULES.md
docs/000-README.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md
```

Ne pas reconstituer ces règles depuis la mémoire de conversation. Le contenu présent dans la base stable est normatif.

### 3.2 Architecture à préserver

Lire ensuite :

```text
docs/architecture/000-README.md
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
docs/architecture/003-COMPONENT_CONTRACTS.md
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
```

Points d'attention :

```text
Transport possède le réseau et ses settings runtime
Config adapte vers Transport, jamais l'inverse
Store/RAW persistence n'appartient pas à Transport
Program decode/materialization n'appartient pas à Transport
un provider WebSocket ne doit pas créer un second moteur session/subscription
les smokes cross-crates ne doivent pas être déplacés opportunistement dans Config
```

### 3.3 Séquence fonctionnelle et héritage Transport

Lire :

```text
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md

docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md
docs/validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
```

`docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` porte la numérotation courante. Les anciens plans restent historiques et ne doivent pas réintroduire une numérotation dépassée.

`KSP-TRANSPORT-007` reste applicable : une extension provider ciblée ne compte comme complète que si toutes les possibilités supportées retenues par l'audit sont représentées sans perte injustifiée.

### 3.4 Contrats publics réels à réauditer

Inspecter directement :

```text
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/
crates/ksp-onchain-transport-lib/tests/

crates/ksp-config-lib/Cargo.toml
crates/ksp-config-lib/src/transport.rs
crates/ksp-config-lib/unit_tests/transport.rs
config/std.transport.json
config/schemas/std.transport.schema.json
.env.example
```

En particulier, vérifier les contrats réels de :

```text
WsProtocolKind
WsEndpointSettings
WsTransportSettings
WsSessionSettings
WsSession
WsSubscription<T>
WsSubscriptionKind
WsSessionSnapshot / WsSubscriptionSnapshot
```

Ne jamais supposer qu'une API imaginée pendant `0.2.7-pre.001` est celle finalement publiée : **le code stable `v0.2.7` prime**.

### 3.5 Clôture `0.2.7`

Lire obligatoirement :

```text
deltas/0.2.7/rel.001.md
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md
docs/IDEAS.md
```

Le but est de reprendre exactement le moteur final, les limitations documentées et les preuves de clôture, pas de rouvrir les décisions standard déjà validées.

`docs/IDEAS.md` est lu uniquement pour éviter de réintroduire dans `0.2.8` des travaux explicitement différés, notamment le metering/provider billing.

---

## 4. Sources externes normatives à réauditer en `pre.001`

La documentation Helius est une surface vivante. **Toutes les informations de cette section sont des pointeurs d'audit, pas des versions figées.** Les pages officielles courantes doivent être relues au début de `pre.001`.

Auditer au minimum les sources Helius officielles suivantes ou leurs remplaçantes actuelles :

```text
https://www.helius.dev/docs/rpc/websocket
https://www.helius.dev/docs/api-reference/rpc/websocket-methods
https://www.helius.dev/docs/api-reference/rpc/websocket/transactionsubscribe
https://www.helius.dev/docs/rpc/websocket/transaction-subscribe
https://www.helius.dev/docs/api-reference/rpc/websocket/accountsubscribe
https://www.helius.dev/docs/rpc/websocket/account-subscribe
https://www.helius.dev/docs/api-reference/rpc/websocket/programsubscribe
https://www.helius.dev/docs/faqs/websockets
https://www.helius.dev/docs/llms.txt
```

Utiliser l'index `llms.txt` et la navigation officielle pour retrouver les pages unsubscribe et toute extension/filter provider-specific encore documenté (`notifyOn`, `tokenAccounts` ou remplaçant actuel). Une URL déplacée n'annule pas le gate : retrouver la page officielle remplaçante et enregistrer la source effective dans le plan/matrice `0.2.8`.

Snapshot documentaire connu lors de la préparation de ce prompt, **à réauditer** :

```text
les endpoints WebSocket standard et Helius extensions sont unifiés par réseau
le produit anciennement appelé Enhanced WebSockets est désormais présenté dans la famille LaserStream WebSocket
transactionSubscribe est une extension Helius avec filtres riches
la référence transactionSubscribe documente transactionUnsubscribe, tandis que l'index méthodes ne l'énumère pas séparément
les méthodes standard block/slotsUpdates/vote sont actuellement annoncées non supportées par Helius
la FAQ annonce un idle timeout de 10 minutes et recommande des pings périodiques
les documents d'indexing distinguent WebSocket sans garantie de replay historique du produit LaserStream gRPC
notifyOn et tokenAccounts ont été observés dans des références Helius pendant la préparation ; leur présence, leur portée et leur forme exactes doivent être reconfirmées au gate
```

Le gate doit relever la **surface exacte du jour** : méthodes, unsubscribe associés, paramètres, limites, notifications, statuts et divergences entre index, guides et références.

Si deux pages Helius se contredisent, ne pas choisir arbitrairement : documenter la divergence, rechercher une source Helius plus primaire/récente, puis tester localement ou contre Helius uniquement si cela peut être fait sans violer les règles de secrets/configuration.

Réauditer aussi les versions courantes des dépendances externes concernées. La résolution observée à la fin de `0.2.7-pre.013` était notamment :

```text
futures-util       0.3.34
tokio              1.53.1
tokio-tungstenite  0.30.0
reqwest             0.13.4
```

Ces versions sont un **snapshot sans lockfile versionné**, pas une contrainte à recopier si Cargo résout plus récent au démarrage de `0.2.8`.

---

## 5. État validé à préserver depuis `v0.2.7`

### 5.1 HTTP

La surface HTTP reste un contrat stable :

```text
52/52 méthodes HTTP courantes typées
14/14 méthodes historiques Deprecated/Removed conservées
KSP-TRANSPORT-007 appliqué à toute la surface typed
retry/no-resend write submissions déjà centralisé
```

`0.2.8` ne doit pas régresser cette surface.

### 5.2 WebSocket Solana standard

La release `0.2.7` publie exactement neuf familles standard :

```text
account
block
logs
program
root
signature
slot
slotsUpdates
vote
```

soit :

```text
9 subscribe + 9 unsubscribe = 18 opérations standard
```

Partition stable/unstable héritée :

```text
stable   : account, logs, program, root, signature, slot
unstable : block, slotsUpdates, vote
```

Les trois familles unstable ont un warning KSP centralisé dans le moteur standard.

### 5.3 Session, subscriptions et cardinalité

Contrat acquis :

```text
1 WsEndpointSettings
 -> 0..N sessions physiques explicitement créées
   -> 0..N logical subscriptions
```

Identités :

```text
WsSessionId      = local et stable
WsSubscriptionId = local et stable pendant reconnect/resubscribe
remote subscription id = interne, transitoire, remappable
```

Aucun pool/scheduler automatique de sessions n'est imposé.

### 5.4 Lifecycle/reconnect/backpressure

Préserver les invariants suivants :

```text
actor unique propriétaire du socket
command queue bornée
pending JSON-RPC borné + timeout
notification queue bornée par subscription
max active subscriptions borné
reconnect fini + backoff exponentiel borné
budget reconnect reset après retour complet à Active
resubscribe ActiveSubscriptions déterministe par local id
remote IDs invalidés après reconnect
continuity_gap_count observable
unsubscribe local gagne les races reconnect/late ack
overflow d'une subscription ne tue pas les autres
shutdown explicite borné via WsSession::close().await
Drop best-effort seulement
```

`signatureSubscribe` reste one-shot après notification terminale et ne doit pas être resubscribed après fermeture normale.

### 5.5 Sécurité/observabilité

Safe metadata autorisée :

```text
endpoint logical name
provider
cluster
protocol kind
local session/subscription ids
subscription kind
states
counts
reconnect attempt
continuity gaps
overflow count
safe error codes
```

Interdit dans logs/Debug/Display/snapshots :

```text
URL complète
query api-key
authorization secret
headers sensibles
remote subscription id
raw notification arbitraire
payload massif
```

### 5.6 Config V2

Contrat stable :

```text
format_version = 2
retry
ws_defaults
default_profile
profiles[]
  endpoints[]
  ws_endpoints[]
    kind
```

À la fin de `0.2.7`, la seule valeur WebSocket Config supportée est :

```text
solana_standard
```

Le type Transport correspondant est `WsProtocolKind`, `#[non_exhaustive]`, précisément pour permettre une extension future sans remplacer le conteneur commun.

---

## 6. Frontières architecturales et règles de dépendances

Direction autorisée :

```text
ksp-config-lib -> ksp-onchain-transport-lib
```

Interdictions durables :

```text
ksp-onchain-transport-lib -X-> ksp-config-lib
ksp-onchain-transport-lib -X-> ksp-wallet-lib
ksp-onchain-transport-lib -X-> ksp-store-api
ksp-onchain-transport-lib -X-> ksp-store-lib
ksp-onchain-transport-lib -X-> ksp-program-api
ksp-onchain-transport-lib -X-> ksp-program-lib
ksp-onchain-transport-lib -X-> tracing direct
```

Transport peut dépendre seulement des crates KSP basses autorisées et des crates réseau/serde/async strictement nécessaires.

Toutes les dépendances tierces restent déclarées dans le `[workspace.dependencies]` racine et consommées par les members avec `.workspace = true`.

Aucun client Helius SDK n'est ajouté par défaut. Une nouvelle dépendance doit démontrer un besoin que le moteur `tokio-tungstenite` existant ne satisfait pas.

---

## 7. Décisions acquises et questions réellement ouvertes

### 7.1 Décisions déjà acquises — ne pas les redébattre sans contradiction réelle

```text
Helius WebSocket réutilise le moteur/session actor de 0.2.7
pas de second client WebSocket provider-specific
les wrappers Solana standard restent valides pour la surface standard
aucune API raw provider-extension publique par défaut
pas de LaserStream gRPC dans 0.2.8
pas de Yellowstone gRPC dans 0.2.8
pas de Store/RAW persistence dans 0.2.8
pas de Program decode/materialization dans 0.2.8
pas de metering/billing provider dans 0.2.8
pas de promesse lossless/historical replay pour WebSocket
credentials Helius = Secret Config, jamais loggés
fixtures déterministes = gate principal ; réseau réel = opt-in uniquement
```

La piste de metering/observabilité réseau est suivie séparément dans `docs/IDEAS.md`; elle ne doit pas être introduite opportunistement dans cette release.

### 7.2 Questions ouvertes à trancher pendant `pre.001`

Le gate doit décider, avec preuves :

```text
nom/public descriptor exact du nouveau WsProtocolKind éventuel
Helius endpoint = SolanaStandard + provider helius, HeliusLaserStream, ou combinaison explicitement justifiée
surface Helius exacte du jour
transactionSubscribe + transactionUnsubscribe : existence, noms et wire exacts
notification transaction exacte et réutilisation possible des DTOs HTTP/WS existants
filtres transaction exacts et limites courantes
extension tokenAccounts : valeurs, cardinalité, interactions
notifyOn account/program : valeurs et comportement serveur
autres extensions Helius actuellement documentées éventuelles
méthodes Solana standard supportées/non supportées sur Helius
comportement KSP pour block/slotsUpdates/vote sur endpoint Helius
capability validation avant I/O vs erreur RPC provider
heartbeat/ping provider : nécessaire, cadence, ownership et interaction avec control frames existants
idle timeout Helius et stratégie de reconnect
interaction entre heartbeat et shutdown/reconnect/backpressure
Config : discriminateur, provider metadata, endpoint/auth shape
faut-il de nouveaux settings provider-specific distincts de WsSessionSettings commun
comment éviter d'injecter notifyOn/tokenAccounts dans les DTOs Solana standard
warning/info provider-specific éventuel et metadata sûre
stratégie de smoke Helius nécessitant une api-key sans lecture directe d'environnement par Transport
besoin réel ou non d'une nouvelle dépendance Rust
```

Une décision peut être de **ne pas exposer** une capacité Helius insuffisamment documentée. Elle doit alors être explicitement reportée, pas silencieusement oubliée.

---

## 8. Objectifs et livrables de `0.2.8`

Le plan créé par `pre.001` doit au minimum prévoir :

1. une matrice normative Helius WebSocket actuelle et sourcée ;
2. un inventaire explicite standard supporté / standard non supporté / extension Helius ;
3. le choix d'extension de `WsProtocolKind` et du Config V2 ;
4. la réutilisation du `WsSession` actor existant ;
5. `transactionSubscribe`/unsubscribe si toujours supportés et documentés ;
6. les filtres/options Helius réellement utiles et documentés ;
7. les extensions Helius de `accountSubscribe`/`programSubscribe` si toujours présentes ;
8. une politique provider capability sans contamination de la surface standard ;
9. heartbeat/idle handling si réellement requis ;
10. fixtures locales déterministes de toutes les extensions ;
11. tests de reconnect/resubscribe/unsubscribe/backpressure sur les nouvelles familles ;
12. redaction credentials Helius et erreurs sûres ;
13. adaptation Config -> Transport correspondante ;
14. canaries de non-régression 18/18 standard + 52/14 HTTP ;
15. documentation README/USAGE durable et version-neutral ;
16. stratégie de smoke live opt-in compatible avec les règles Config/secret ;
17. audit final des dépendances et prompt `0.2.9`.

Créer normalement :

```text
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
```

Si ces numéros sont déjà occupés dans la base réellement fournie, prendre les prochains numéros disponibles et mettre à jour les index correspondants.

---

## 9. Hors périmètre explicite

```text
LaserStream gRPC / helius-laserstream SDK         -> hors 0.2.8
Yellowstone gRPC standard                         -> 0.2.9
providers Yellowstone commerciaux spécifiques    -> après foundation 0.2.9 selon sizing
Gatekeeper beta                                   -> hors scope sauf décision explicite après audit
Shred Delivery / shreds UDP                       -> plus tard
preconfirmations / Sender                         -> autres surfaces futures
HTTP Helius provider extensions non WebSocket     -> hors 0.2.8
ksp-offchain-transport-lib / prix                 -> 0.2.10
Price Desk / Wallet Desk price integration        -> 0.2.11
Store / RAW persistence                           -> série 0.3.x
Program decode / materialization                  -> plus tard
metering / coût / billing provider                -> IDEAS/future crate dédiée
pool/scheduler automatique complexe de WsSession  -> différé sans besoin démontré
historical replay WebSocket inventé               -> interdit
```

Ne pas importer dans `0.2.8` les capacités gRPC de LaserStream sous prétexte qu'elles portent le même nom produit.

---

## 10. Contraintes sécurité, provider et API

### 10.1 Credentials Helius

Une api-key Helius est un Secret.

Elle ne doit jamais apparaître dans :

```text
Debug
Display
KspError context arbitraire
logs
panic output volontaire
snapshots runtime
nom d'endpoint
fixtures versionnées
commandes documentées avec vraie valeur
```

Les URLs contenant `?api-key=...` doivent rester derrière `WsEndpointUrl` et ses garanties de redaction.

### 10.2 Provider-specific sans pollution standard

Une option Helius ne doit pas être ajoutée à un DTO standard Solana simplement parce qu'elle réutilise le même nom JSON-RPC.

Le design doit distinguer explicitement :

```text
contrat Solana standard
extension Helius du même method name
nouvelle méthode Helius
```

Les wrappers standards de `0.2.7` ne doivent pas changer de wire lorsqu'ils sont utilisés avec `WsProtocolKind::SolanaStandard`.

### 10.3 Heartbeat

`0.2.7` n'impose aucun heartbeat applicatif périodique : il répond correctement aux control frames WebSocket reçues.

Si Helius exige/recommande un ping périodique pour éviter son inactivity timeout, `pre.001` doit décider si cela devient :

```text
une capability provider-specific
un setting explicite
un comportement automatique borné
ou une responsabilité caller
```

Toute solution automatique doit :

```text
être annulable au shutdown
ne pas masquer un socket réellement mort
ne pas créer une boucle de reconnexion infinie
ne pas bloquer l'actor
ne pas logguer de secret
être couverte par test temporel déterministe local
```

### 10.4 Continuité

Même si Helius annonce une infrastructure de failover, WebSocket ne doit pas être documenté comme lossless.

Le contrat KSP reste :

```text
reconnect possible
resubscribe possible
continuity_gap_count observable
aucun backfill automatique dans Transport
aucune garantie de replay historique WebSocket
```

---

## 11. Première mission `0.2.8-pre.001` — gate obligatoire

La première tranche est **audit + brainstorming + sizing**, pas une tranche d'implémentation lourde.

Elle doit exécuter dans l'ordre :

### 11.1 Reprise de la base et baseline avant modification

```text
vérifier base/tag v0.2.7 ou archive stable autoritaire
vérifier Cargo = 0.2.7
lire les règles obligatoires
lire plan + validation + rel.001 de 0.2.7
inventorier le code WsSession/WsSubscription/Config réellement publié
vérifier l'état Cargo et le graphe actuel
```

Avant toute modification, exécuter lorsque l'environnement le permet :

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
```

Puis inspecter au minimum :

```bash
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
```

Ne jamais déclarer une commande réussie si elle n'a pas réellement été exécutée. Si l'environnement de préparation ne fournit pas Cargo/rustfmt, enregistrer explicitement cette impossibilité dans le plan/delta et laisser le gate compilé à l'opérateur.

### 11.2 Audit Helius officiel actuel

Construire une matrice contenant au minimum :

```text
method
subscribe/unsubscribe pair
standard ou Helius extension
support Helius actuel
params obligatoires
options
filters
limits/cardinality
notification method
notification wire
nullable/optional states
idle/heartbeat requirement
credential requirement
source officielle
strategy de test
```

Le gate doit spécialement résoudre :

```text
transactionUnsubscribe exact
notifyOn exact
programSubscribe + notifyOn exact
tokenAccounts exact
autres filtres transaction actuels
liste des méthodes unstable explicitement non supportées
endpoints mainnet/devnet réellement courants
ancien atlas-* vs endpoints unifiés actuels
nom actuel Enhanced WebSockets vs LaserStream WebSocket
```

### 11.3 Audit architecture KSP

Comparer la matrice Helius avec :

```text
WsProtocolKind
WsEndpointSettings
WsSessionSettings
WsSubscriptionKind
subscribe_typed interne
registry/remapping remote/local
reconnect/resubscribe
Config V2 kind
```

Décider quelles parties sont :

```text
réutilisées telles quelles
étendues provider-specific
interdites avant I/O
laissées à l'erreur provider
reportées
```

### 11.4 Audit dépendances

Exécuter au minimum :

```bash
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
```

Vérifier les versions stables courantes des crates réseau utilisées. Ne pas ajouter un SDK Helius sans justification mesurable.

### 11.5 Threat model provider

Brainstormer au minimum :

```text
api-key dans query URL
endpoint redaction
provider idle timeout
heartbeat concurrent avec reconnect/close
rate/capability errors
subscription ids et late notifications
in-flight notifications après unsubscribe
provider-specific unknown fields
payload volumineux transactionSubscribe
50k-address style filters et coût mémoire/serialization
data gaps après reconnect
mismatch standard method support
```

### 11.6 Sizing et prévision souple obligatoire

Produire avant implémentation lourde :

```text
liste exacte des capacités à implémenter
questions reportées
nombre estimé de prereleases
ordre des tranches
objectif précis de chaque tranche
principaux contrats/fichiers touchés attendus
preuves/tests/gates attendus pour chaque tranche
budget nominal de chaque tranche <= environ 15–20 minutes de travail effectif
risques et critères de split
```

La prévision initiale de la section 12 est **un forecast de départ**, pas un engagement. `pre.001` doit la recalibrer à partir de l'audit réel et recopier le forecast recalibré dans :

```text
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
deltas/0.2.8/pre.001.md
```

Règles de granularité :

```text
une tranche ne doit pas masquer plusieurs sous-problèmes indépendants
une tranche estimée > 15–20 min doit normalement être scindée
une nouvelle ambiguïté normative peut créer une tranche supplémentaire
un fix peut être inséré après n'importe quelle prerelease
le dernier numéro de prerelease prévu n'est jamais une deadline
la release ne doit jamais être fermée artificiellement pour respecter le forecast initial
```

Si la surface Helius actuelle est plus large que prévu et menace la règle « une release concrète clôturable dans une session », **scinder fonctionnellement la release avant implémentation lourde**.

### 11.7 Documents de sortie du gate

`pre.001` doit créer/mettre à jour au minimum :

```text
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
deltas/0.2.8/pre.001.md
```

ainsi que les index documentaires concernés.

### Critères de sortie de `pre.001`

Le gate est positif seulement si :

```text
base stable confirmée
baseline avant modification enregistrée
sources Helius actuelles réauditées
surface exacte inventoriée
terminologie provider clarifiée
frontières standard/provider décidées
heartbeat/idle ownership décidé ou explicitement reporté
Config shape décidée
strategy de credentials sûre
strategy de tests/smoke décidée
aucune nouvelle dépendance non justifiée
release dimensionnée
forecast initial recalibré avec budget/gates par tranche
risques de split explicitement documentés
```

---

## 12. Prévision souple initiale des prereleases

Prévision de départ, **obligatoirement recalibrée après `pre.001`** :

```text
pre.001  audit Helius actuel + matrice + architecture + threat model + dependencies + sizing
         preuve : plan initial + matrice compliance + forecast recalibré ; aucun runtime provider lourd

pre.002  descriptor/protocol/provider settings + capability model + secrets/redaction contracts
         preuve : settings/API canaries + tests de validation/redaction ; pas encore de Config provider persistée

pre.003  extension Config V2 provider-specific + mapping Config -> Transport + fixtures/schema
         preuve : backward V1/V2 + fixtures provider + rejection unknown/invalid + aucune dépendance inverse

pre.004  transactionSubscribe/unsubscribe : paramètres, filtres, options et serialization exacts
         preuve : fixtures request/ack/error + limites déterministes avant I/O + API typed

pre.005  transaction notifications typed + unsubscribe/reconnect/resubscribe/races
         preuve : notification wire + late notification + remapping remote/local + backpressure ciblée

pre.006  extensions account/program Helius retenues : notifyOn/tokenAccounts/autres capacités auditées
         preuve : wire exact + cardinalités + isolation stricte des DTOs Solana standard

pre.007  heartbeat/idle provider + timers + interaction reconnect/control frames/shutdown
         preuve : tests temporels locaux déterministes + cancellation bornée + aucun secret/log payload

pre.008  capability failures + provider errors + limites/backpressure/adversarial lifecycle
         preuve : mismatch standard/provider + payload oversized + queue overflow + session isolation

pre.009  compliance Helius finale + non-régressions Solana standard 18/18 + HTTP 52/14 + Config/API canaries
         preuve : matrice rapprochée + release-completeness + tests Transport/Config ciblés

pre.010  smoke Helius live opt-in si stratégie sûre + audit dependency graph/duplicates + README/USAGE
         preuve : smoke sans secret versionné + cargo tree analysé + documentation durable version-neutral

pre.011  validation workspace finale + fermeture plan/matrice/indexes + prompt 0.2.9
         preuve : workspace final vert + docs cohérentes + prompt suivant autonome

rel.001  publication stable stricte
```

Cette prévision est **souple** :

```text
chaque tranche vise environ 15–20 minutes de travail effectif
pre.001 peut fusionner, scinder, déplacer ou ajouter des tranches selon l'audit réel
des fixes peuvent être insérés à tout moment
pre.011 n'est pas une deadline
aucun numéro de prerelease ne vaut critère de clôture
seuls les gates de la section 15 autorisent rel.001
```

Le plan `0.2.8` doit conserver le forecast recalibré courant. Les deltas décrivent la progression détaillée ; `ROADMAP.md` ne sert pas de changelog de prereleases.

---

## 13. Versionnement, deltas, commits, archives et tags

Convention de livraison :

```text
0.2.8-pre.001         -> Cargo 0.2.8-pre.1
0.2.8-pre.002         -> Cargo 0.2.8-pre.2
0.2.8-pre.NNN-fix.MMM -> Cargo 0.2.8-pre.N.fix.M seulement si code/build/runtime/config/migration change
0.2.8-rel.001         -> Cargo 0.2.8
```

Une prerelease non-fix synchronise toujours `workspace.package.version`, même si son contenu final est principalement documentaire. Un fix purement documentaire/de référence non consommée par le runtime conserve la version Cargo de sa base directe, conformément à `VERSION_WORKFLOW.md`.

Deltas :

```text
deltas/0.2.8/pre.001.md
deltas/0.2.8/pre.002.md
...
deltas/0.2.8/pre.NNN-fix.MMM.md
deltas/0.2.8/rel.001.md
```

Commits :

```text
v0.2.8-pre.001
v0.2.8-pre.001-fix.001
...
v0.2.8-rel.001
```

Archives d'échange usuelles :

```text
ksp-general-0.2.8-pre.001.zip
ksp-general-0.2.8-pre.NNN-fix.MMM.zip
ksp-general-0.2.8-rel.001.zip
```

Une archive delta doit contenir uniquement les fichiers ajoutés/modifiés de la livraison et conserver leurs chemins depuis la racine du workspace.

Aucun tag Git pour les prereleases.

Après validation de `rel.001` :

```text
tag stable = v0.2.8
```

Une livraison publiée est immutable. Une correction produit un nouveau `fix`; elle ne remplace jamais l'archive précédente.

Pendant les prereleases :

```text
ROADMAP.md = statut global seulement
CHANGELOG.md = principalement clôture stable
progression détaillée = plan + validation + deltas
pas de Cargo.lock / package-lock.json versionné
```

Tout fichier modifié incrémente son header `version:` selon les règles KSP.

---

## 14. Application et validation opérateur

L'assistant prépare normalement un overlay minimal ne contenant que les fichiers ajoutés/modifiés de la livraison.

Chaque delta doit distinguer :

```text
validations réellement exécutées
validations impossibles dans l'environnement de préparation
validations opérateur requises
```

Après application d'une prerelease Rust :

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
```

Puis tests ciblés pertinents, par exemple :

```bash
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-config-lib
```

À la fermeture d'une tranche technique importante et de la release :

```bash
cargo test --workspace
```

Lorsque le graphe de dépendances change ou constitue un gate :

```bash
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
cargo tree --duplicates
```

Ne jamais déclarer une commande réussie si elle n'a pas été exécutée. L'environnement de préparation peut ne pas disposer de Cargo/rustfmt ; dans ce cas, le delta doit le dire explicitement et l'opérateur exécute les gates.

### Tests provider attendus

Les preuves déterministes doivent couvrir au minimum, selon la surface retenue :

```text
subscribe/unsubscribe exacts
notification method exact
transaction filters/options complets
cardinalités/limites avant I/O lorsqu'elles sont déterministes
notifyOn/tokenAccounts ou extensions retenues
standard vs provider capability mismatch
provider RPC errors sans session failure injustifiée
late notification après unsubscribe
reconnect/resubscribe
heartbeat timer borné si ajouté
shutdown pendant heartbeat/reconnect
message/frame oversized
queue overflow d'une subscription
secret URL redaction
public API canaries
Config -> Transport mapping
HTTP 52+14 non régressé
Solana standard 18/18 non régressé
```

### Smoke live Helius

Un smoke live Helius ne doit **jamais** justifier :

```text
std::env direct dans Transport
api-key hardcodée
secret dans fixture
secret dans commande/delta/log
nouvelle dépendance Transport -> Config
```

`pre.001` doit décider une stratégie compatible avec l'architecture. Si aucune surface d'intégration sûre n'existe encore, il est acceptable de garder la compliance provider principalement déterministe et de documenter un smoke opérateur séparé au lieu de violer les frontières KSP.

---

## 15. Critères de clôture de `0.2.8`

La release ne peut passer stable que si :

```text
surface Helius WebSocket actuelle auditée et rapprochée
chaque capacité ciblée a un statut explicite
aucune méthode/options Helius retenue n'est perdue
standard Solana 18/18 non régressé
HTTP 52 current + 14 historical non régressé
moteur WsSession unique réutilisé
aucun second client WebSocket provider-specific
Config -> Transport reste la seule direction d'adaptation
credentials Helius redacted partout
heartbeat/idle behavior audité et testé si implémenté
reconnect/resubscribe/backpressure/shutdown restent bornés
aucune fausse promesse lossless/replay WebSocket
aucune dépendance Store/Program/Wallet/Config/tracing direct dans Transport
dépendances directes et doublons transitifs inspectés
fixtures déterministes vertes
workspace complet vert
README/USAGE synchronisés et version-neutral
matrice finale de validation fermée
forecast réalisé ou explicitement recalibré sans dette silencieuse
prompt 0.2.9 préparé
```

Le numéro de la dernière prerelease n'est jamais un critère de clôture. Si les gates ne sont pas verts à `pre.011`, continuer avec `pre.012+` ou des fixes.

`CHANGELOG.md` et le statut stable du ROADMAP ne sont finalisés qu'à la publication `rel.001`.

---

## 16. Release/session suivante envisagée

La release suivante prévue est :

```text
0.2.9 — Yellowstone gRPC standard/provider-neutral
```

Elle doit partir du moteur Transport stabilisé mais **ne doit pas être anticipée dans `0.2.8`** par l'ajout de dépendances gRPC, de protobufs Yellowstone ou du SDK LaserStream gRPC.

Le prompt `0.2.9` devra imposer un nouvel audit normatif de la surface Yellowstone actuelle et un sizing complet avant implémentation.

---

## 17. Instruction d'ouverture

Au début de la nouvelle session `0.2.8` :

1. vérifier que la base est réellement `v0.2.7` ou l'archive stable autoritaire fournie ;
2. vérifier `workspace.package.version = 0.2.7` et la présence de `deltas/0.2.7/rel.001.md` ;
3. lire les sources internes obligatoires dans l'ordre indiqué ;
4. relire le plan, la matrice finale WebSocket standard, `KSP-TRANSPORT-007` et les différés pertinents ;
5. inspecter le code public/réel de `WsSession`, `WsSubscription`, `WsProtocolKind` et Config V2 ;
6. exécuter/enregistrer la baseline disponible avant modification ;
7. réauditer immédiatement la documentation officielle Helius LaserStream WebSocket du jour ;
8. produire la matrice standard/supporté/extension/non-supporté ;
9. brainstormer provider credentials, heartbeat, capabilities, reconnect et tests ;
10. dimensionner la release par tranches d'environ 15–20 minutes et **recalibrer explicitement la prévision souple de la section 12** ;
11. écrire le plan, la matrice et `deltas/0.2.8/pre.001.md` avec ce forecast recalibré ;
12. exécuter les validations de gate disponibles ;
13. **ne pas commencer `transactionSubscribe`, modifier Config ou ajouter une dépendance avant que ce gate soit cohérent**.

La première réponse de travail doit donc être un **audit/sizing `0.2.8-pre.001` avec forecast recalibré**, pas une implémentation prématurée.