khadhroony-solana-project/prompts/014-V0_2_9_START_PROMPT.md

<!-- file: prompts/014-V0_2_9_START_PROMPT.md -->
<!-- version: 1 -->

# Prompt de démarrage `0.2.9` — Yellowstone gRPC standard/provider-neutral

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

La base attendue est **exclusivement** la release stable :

```text
v0.2.8
```

Ne pas ouvrir `0.2.9` depuis `0.2.8-pre.*`, depuis une archive intermédiaire, depuis un ancien ZIP de travail ou depuis un souvenir de session.

Si une archive opérateur de `v0.2.8` est fournie au démarrage, **cette archive réelle devient la première autorité** devant les snippets, prompts historiques, anciens ZIP et mémoire de conversation. Une divergence entre cette base et le présent prompt déclenche un audit explicite ; elle ne se résout jamais par supposition.

La release à ouvrir est :

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

La première tranche est :

```text
0.2.9-pre.001
```

`pre.001` est obligatoirement une tranche **lecture + audit + brainstorming + threat model + dépendances/licences + sizing + planification**. Elle ne doit pas commencer par l'implémentation lourde d'un client gRPC ou par l'ajout opportuniste de crates Yellowstone/Tonic.

À l'ouverture, vérifier au minimum :

```text
git describe / tag stable si metadata Git disponible
workspace.package.version = 0.2.8
deltas/0.2.8/rel.001.md présent
prompts/014-V0_2_9_START_PROMPT.md présent
```

État fonctionnel attendu depuis `v0.2.8` :

```text
HTTP Solana                    52/52 current typed
HTTP historiques              14/14 Deprecated/Removed conservées
KSP-TRANSPORT-007             appliqué

WebSocket Solana standard     9 familles / 18 subscribe-unsubscribe
stable WS                     account/logs/program/root/signature/slot
unstable WS                   block/slotsUpdates/vote

Helius LaserStream WebSocket  account/logs/program/root/signature/slot/slotsUpdates
Helius provider-specific      transactionSubscribe / transactionUnsubscribe
Helius absent                 block/vote
Helius heartbeat              WebSocket Ping control frame, 60 s, actor-owned

Config Transport              V1 HTTP backward-readable + V2 WS
Config -> Transport           autorisé
Transport -> Config           interdit
LaserStream gRPC              toujours distinct du namespace WebSocket
```

---

## 2. Mission et résultat attendu

`0.2.9` introduit dans `ksp-onchain-transport-lib` une **première fondation Yellowstone gRPC standard et provider-neutral**.

La release ne doit pas devenir un SDK Helius, Triton, ERPC, Chainstack, Shyft ou autre fournisseur commercial. Un provider peut servir à une validation réseau si nécessaire, mais il reste un **environnement d'exécution**, jamais le propriétaire du contrat public KSP.

Résultat attendu à la clôture :

```text
un backend gRPC Yellowstone explicitement distinct de HTTP et WebSocket
une surface publique KSP bornée et provider-neutral
connexion/TLS/auth metadata générique sans secret exposé
contrats typed pour la surface normative effectivement retenue
stream/subscription lifecycle borné
filtres et updates wire utiles préservés sans perte arbitraire
reconnect/continuity semantics explicites, sans promesse lossless implicite
Config -> Transport seulement si la shape est validée par le gate
README/USAGE et matrice de compliance synchronisés
non-régressions HTTP + WebSocket standard + Helius
aucune dépendance provider-specific dans les exécutables
```

Le terme **foundation** est important : `pre.001` doit d'abord déterminer quelle part de la surface Yellowstone actuelle peut raisonnablement être livrée dans une release concrète clôturable dans la session. Si la surface normative s'est élargie au point de rendre `0.2.9` surdimensionnée, elle est **scindée avant implémentation lourde**.

---

## 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
```

Le présent prompt est autonome mais ne remplace pas les règles normatives.

Rappels qui conditionnent directement cette session :

```text
Rust 2024
unsafe / unwrap / expect / panic interdits en production
? interdit en production
retours explicites ; clippy::implicit_return deny
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]

pas de pub mod
pub/pub(crate) consommés crate-wide via reexports crate-root
private testé depuis unit_tests via super::Item
visibilité jamais élargie seulement pour tester
unit tests sous unit_tests/
integration tests sous tests/

ksp-logging-lib = propriétaire tracing KSP
Config = propriétaire config/env/secrets
Transport ne lit jamais std::env pour les secrets runtime
```

Après toute modification Rust :

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

Une commande non exécutée n'est jamais déclarée réussie.

### 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éjà acquis :

```text
ksp-onchain-transport-lib possède HTTP + WS + Yellowstone gRPC
aucune crate ksp-onchain-transport-api séparée
Transport -X-> Config / Store / Program
Config -> Transport autorisé
providers Yellowstone spécifiques = extensions futures
contrat Yellowstone initial = standard/provider-neutral
pool/scheduler automatique de sessions = seulement si besoin démontré
```

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

Lire :

```text
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/007-V0_2_0_SERIES_PLANNING.md

docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_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/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md

deltas/0.2.8/rel.001.md
```

L'objectif est de réutiliser les règles éprouvées de Transport sans forcer HTTP, WebSocket et gRPC dans une abstraction commune artificielle.

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

Inspecter le code réel de la base stable, au minimum :

```text
Cargo.toml
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/lib.rs
crates/ksp-onchain-transport-lib/src/constants.rs
crates/ksp-onchain-transport-lib/src/settings.rs
crates/ksp-onchain-transport-lib/src/ws_settings.rs
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
crates/ksp-onchain-transport-lib/src/ws_session.rs
crates/ksp-onchain-transport-lib/src/ws_lifecycle.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs

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
```

Ne pas décider une API gRPC à partir d'un ancien prompt si le code stable a déjà évolué.

### 3.5 Références historiques utiles

Relire au moins les prompts :

```text
prompts/006-V0_2_1_START_PROMPT.md
prompts/012-V0_2_7_START_PROMPT.md
prompts/013-V0_2_8_START_PROMPT.md
```

Le premier rappelle le gate de sizing Transport, le second le lifecycle streaming standard et le troisième les contraintes provider/secrets/forecast récentes.

---

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

La fraîcheur est obligatoire. Les versions, RPCs et messages Yellowstone changent activement.

Sources primaires à relire depuis leur état courant :

```text
https://github.com/rpcpool/yellowstone-grpc
https://github.com/rpcpool/yellowstone-grpc/blob/master/README.md
https://github.com/rpcpool/yellowstone-grpc/blob/master/CHANGELOG.md
https://github.com/rpcpool/yellowstone-grpc/releases
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/geyser.proto
https://github.com/rpcpool/yellowstone-grpc/blob/master/yellowstone-grpc-proto/proto/solana-storage.proto
https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-client
https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/rust
https://crates.io/crates/yellowstone-grpc-client
https://crates.io/crates/yellowstone-grpc-proto
```

Puis vérifier les crates génériques réellement nécessaires si cette stratégie est retenue :

```text
tonic
prost
prost-types
tokio-stream
futures / futures-util
bytes
```

Ne jamais traiter les versions historiques du présent prompt comme des pins.

### Snapshot informatif au 2026-08-23 — à ne pas figer

Au moment où ce prompt est préparé, le `geyser.proto` upstream observé expose notamment :

```text
Subscribe
SubscribeDeshred
SubscribeReplayInfo
Ping
GetLatestBlockhash
GetBlockHeight
GetSlot
IsBlockhashValid
GetVersion
```

Le `SubscribeRequest` observé contient notamment :

```text
accounts
slots
transactions
transactions_status
blocks
blocks_meta
entry
commitment
accounts_data_slice
ping
from_slot
```

L'upstream courant contient aussi des évolutions telles que :

```text
CuckooFilter / filtres account/block compressés
TokenAccountExpansionControlFlag
SubscribeDeshred / deshred transactions
reconnect/replay évolué côté client upstream
```

**Ces éléments ne sont pas automatiquement dans le scope `0.2.9`.** `pre.001` doit déterminer leur statut : standard upstream, extension Triton, capacité nouvelle, expérimental, hors fondation ou report explicite.

Le `Cargo.toml` master observé le 2026-08-23 montre notamment :

```text
workspace license                    AGPL-3.0
yellowstone-grpc-client (workspace)  13.3.0
yellowstone-grpc-proto (workspace)   12.6.0
tonic / prost / prost-types          0.14
release GitHub observée              v14.2.2+solana.4.1.0 (2026-07-27)
```

Ce snapshot est **informatif uniquement** : les numéros du workspace `master`, des crates publiées et des releases GitHub ne suivent pas nécessairement le même rythme. La licence du repository/proto doit en outre être traitée comme un **gate explicite** avant toute copie, génération vendored ou incorporation de source/proto dans KSP MIT ; ne pas déduire la licence d'une crate publiée uniquement de la licence du repository.

Vérifier séparément au démarrage de `pre.001` :

```text
release GitHub réellement courante
crate crates.io réellement courante et sa licence publiée
version proto compatible
licence du proto/source réellement utilisé
MSRV / Rust requis
features activées
build dependencies / protoc éventuel
```

### Sources provider — secondaires pour `0.2.9`

Les docs Helius/Triton/ERPC/Chainstack/Shyft peuvent servir à comprendre interop, headers, quotas et smokes, mais **elles ne définissent pas à elles seules le contrat standard KSP**.

Toute divergence `upstream proto/release` vs `provider documentation` doit être enregistrée explicitement.

---

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

### 5.1 HTTP

Ne pas régresser :

```text
52 méthodes courantes typed
14 historiques Deprecated/Removed
KSP-TRANSPORT-007
no-resend après dispatch ambigu pour WriteSubmission
pool/rôles/capabilities/limites/retry existants
```

Aucun refactor gRPC ne justifie de casser le contrat HTTP.

### 5.2 WebSocket Solana standard

Conserver :

```text
9 familles / 18 opérations
sessions physiques explicites
subscriptions logiques typées
local IDs stables
remote IDs internes/remappables
reconnect/resubscribe/backpressure/shutdown bornés
continuity_gap_count
signature one-shot
Config V2 solana_standard
```

Le gRPC ne doit pas être représenté comme un nouveau `WsProtocolKind`.

### 5.3 Helius LaserStream WebSocket

Conserver :

```text
HeliusLaserStreamWsSession
7 familles standard supportées
transactionSubscribe/unsubscribe typed
block/vote absents
slotsUpdates unstable
heartbeat Helius-only Ping 60 s
credentials Helius Config-owned/redacted
```

Helius LaserStream **gRPC** reste conceptuellement un provider Yellowstone futur, pas une extension de cette façade WebSocket.

### 5.4 Config et ownership

Conserver :

```text
ksp-config-lib = propriétaire documents/env/secrets
Config -> Transport
Transport -X-> Config
Transport -X-> std::env KSP_*
.env.example = inventaire canonique des variables runtime
```

Une éventuelle extension `std.transport` pour gRPC doit être décidée par audit. Ne pas supposer automatiquement `format_version = 3` ni réutiliser `ws_endpoints`.

### 5.5 Logging et erreurs

Conserver :

```text
ksp-core-lib = Error/Result commun
ksp-logging-lib = façade tracing
Transport n'utilise pas tracing directement
secrets/payloads provider absents de Debug/Display/context/logs
```

Les erreurs Tonic/HTTP2/TLS/metadata devront être mappées dans le domaine KSP sans rendre de token ou payload arbitraire.

---

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

### 6.1 Propriétaire

`ksp-onchain-transport-lib` reste propriétaire de Yellowstone gRPC.

Ne pas créer sans preuve :

```text
ksp-yellowstone-lib
ksp-grpc-lib
ksp-onchain-transport-api
```

### 6.2 Provider-neutral obligatoire

Le contrat public initial ne doit pas s'appeler :

```text
HeliusGrpc...
TritonGrpc...
ERPC...
Chainstack...
Shyft...
```

Le provider peut apparaître dans des settings descriptifs ou tests, mais les types protocole/filtres/updates doivent représenter Yellowstone standard lorsque c'est réellement leur sémantique.

### 6.3 Séparation des transports

Ne pas réutiliser artificiellement :

```text
WsProtocolKind
WsEndpointSettings
WsSession
WsSubscription
HeliusLaserStreamWsSession
```

pour représenter gRPC.

Le gRPC peut partager des DTOs Solana déjà publics **uniquement lorsque leur sémantique et leur wire sont réellement compatibles**. Une duplication claire et bornée vaut mieux qu'une abstraction fausse.

### 6.4 Firewall des exécutables

Les applications/workers/jobs ne doivent pas dépendre directement de :

```text
yellowstone-grpc-client
yellowstone-grpc-proto
tonic/prost pour un besoin protocolaire Yellowstone
```

Ils consomment l'API KSP propriétaire.

### 6.5 Dépendances Cargo

Toute nouvelle dépendance externe :

```text
déclarée une fois au workspace root
consommée .workspace = true
features activées localement et minimalement
version caret normalisée
cargo tree inspecté
```

Les doublons de générations `prost/tonic/http/tower/bytes/rustls` sont particulièrement à surveiller.

---

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

### 7.1 Décisions acquises — ne pas redébattre sans contradiction réelle

```text
0.2.9 cible Yellowstone gRPC standard/provider-neutral
la surface vit dans ksp-onchain-transport-lib
aucun provider commercial ne devient propriétaire du contrat
Helius/Triton/ERPC/Chainstack/Shyft adapters = futur
shred/deshred/pré-exécution = hors scope initial sauf reclassification normative explicite
Transport ne dépend pas de Config
Config peut adapter vers Transport
WebSocket et gRPC restent des backends distincts
pre.001 = audit/sizing obligatoire
une release surdimensionnée est scindée avant implémentation lourde
```

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

#### Dépendances / génération wire

Comparer au minimum :

```text
A. yellowstone-grpc-client + yellowstone-grpc-proto
B. yellowstone-grpc-proto + client KSP autour de tonic
C. proto/génération KSP minimale bornée
D. autre composition démontrée par l'audit
```

Critères :

```text
licence
compatibilité MIT KSP
MSRV
versions tonic/prost
poids transitif
features
exposition de types upstream dans l'API publique
stabilité/breaking cadence
besoin réel de code generation/build.rs/protoc
facilité de contrôle redaction/lifecycle/backpressure
```

**Ne pas copier des fichiers source/proto upstream sous licence sans audit licence explicite.**

#### Surface RPC exacte

Décider si `0.2.9` couvre dans cette release :

```text
Subscribe
SubscribeReplayInfo
Ping
GetLatestBlockhash
GetBlockHeight
GetSlot
IsBlockhashValid
GetVersion
```

et classifier explicitement :

```text
SubscribeDeshred
extensions provider/Triton
méthodes nouvelles apparues depuis ce prompt
```

#### Subscribe filters

Auditer :

```text
accounts
slots
transactions
transactions_status
blocks
blocks_meta
entry
commitment
accounts_data_slice
ping
from_slot
account memcmp/dataSize/token state/lamports filters
compressed/Cuckoo filters si encore standards
TokenAccountExpansionControlFlag si encore standard
```

#### Updates

Auditer toutes les variantes réellement présentes :

```text
account
slot
transaction
transaction_status
block
block_meta
entry
ping
pong
```

ainsi que les champs/oneofs/optional actuels.

#### Lifecycle

Décider :

```text
un stream bidirectionnel par session ?
plusieurs logical filter groups dans un SubscribeRequest ?
modification dynamique des subscriptions sur le même stream ?
close/drop semantics
reconnect automatique ou explicite
resubscribe déterministe
from_slot/replay ownership
continuity gap / duplicate observability
backpressure et bounded queues
```

#### Auth metadata

Décider une shape provider-neutral :

```text
aucun header commercial hardcodé dans le contrat standard sans nécessité
secrets jamais dans Debug/Display
metadata sensible séparée des metadata publiques
Config propriétaire des valeurs de secret
```

#### Config

Décider seulement après audit :

```text
nouveau grpc_endpoints ?
nouveau kind/descriptor ?
version de document à incrémenter ou non ?
TLS/timeout/message-size/reconnect defaults ?
références de secrets par placeholders Config ?
```

#### Smoke réseau

Déterminer si un endpoint provider accessible permet un smoke sans introduire :

```text
secret versionné
provider-specific API dans Transport
Transport -> Config
test cross-crates placé dans Config par facilité
```

Si aucune surface d'intégration KSP dédiée n'existe encore, documenter la limite au lieu de violer l'architecture.

---

## 8. Objectifs et livrables de `0.2.9`

Sous réserve du sizing `pre.001`, la release vise :

```text
1. plan Yellowstone gRPC dédié
2. matrice protocolaire/compliance dédiée
3. stratégie dépendances/licence documentée
4. settings gRPC runtime bornés et redacted
5. endpoint/session/client gRPC provider-neutral
6. typed requests/filters/updates pour la surface retenue
7. unary RPCs retenus dans la matrice
8. stream lifecycle borné
9. reconnect/continuity semantics explicites
10. erreurs et observabilité KSP
11. Config adapter si scope confirmé
12. tests déterministes et adversariaux
13. smoke live opt-in si architecture-safe
14. README/USAGE
15. non-régressions HTTP/WS/Helius
16. cargo tree final
17. prompt 0.2.10
```

Les documents de release attendus à l'ouverture sont normalement :

```text
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
deltas/0.2.9/pre.001.md
```

Le numéro exact peut être ajusté seulement si la base stable contient déjà un nouveau document occupant ces indices.

---

## 9. Hors périmètre explicite

Sauf décision de split/reclassification documentée à `pre.001` :

```text
Helius LaserStream gRPC adapter spécifique
Triton-specific adapter/auth/capabilities
ERPC-specific adapter
Chainstack-specific adapter
Shyft-specific adapter
shred delivery
SubscribeDeshred / pré-exécution provider extension
RabbitStream ou équivalent
serveur Geyser/plugin validator
Store/persistence
workers/jobs d'acquisition
backfill historique
replay lossless garanti
scheduler/pool automatique complexe de sessions gRPC
refonte HTTP
refonte WebSocket
prix offchain
Wallet/Wallet Desk
Program/Interface
```

`0.2.10 — off-chain price transport` ne doit pas être anticipée ici.

---

## 10. Contraintes sécurité, ressources, lifecycle et API

### 10.1 Credentials / metadata

Threat model minimal :

```text
token/header provider dans metadata gRPC
endpoint potentiellement sensible
message d'erreur TLS/tonic contenant metadata ou URI
Debug automatique d'un request contenant filtres/adresses
provider Status avec message/details arbitraires
```

Exigences :

```text
aucun secret dans Debug/Display/KspError/log/snapshot
aucune metadata secrète dans DTO public safe
Config reste propriétaire des valeurs issues de KSP_SECRET_*
Transport reçoit un contrat résolu/opaque
```

### 10.2 Bornes de ressources

Auditer et borner :

```text
connect timeout
request timeout si unary
max inbound message size
max outbound message size
stream channel capacity
logical subscription/filter count
nombre de noms de filters
longueur des filter names
nombre d'accounts/owners/include/exclude/required
nombre de memcmp/data slices
payload account/block/transaction
reconnect attempts/backoff
```

Ne pas recopier aveuglément un quota provider dans le contrat standard KSP.

### 10.3 Backpressure

Le stream doit avoir une politique explicite :

```text
pas de queue non bornée
pas de blocage global silencieux
pas de drop silencieux présenté comme lossless
état terminal/overflow observable
```

### 10.4 Reconnect, replay et continuité

Ne pas promettre :

```text
exactly-once
lossless
historical replay complet
ordre global sans gap
```

sans preuve protocolaire.

`from_slot`, `SubscribeReplayInfo` et toute feature client upstream de replay/reconnect doivent être audités séparément : leur présence ne signifie pas automatiquement que KSP peut garantir une continuité parfaite entre providers/nodes.

### 10.5 API publique

Favoriser :

```text
types KSP stables
façade crate-root explicite
raw upstream types cachés si leur stabilité est insuffisante
#[non_exhaustive] lorsque l'évolution wire le justifie
Unknown/bounded fallback seulement si compatible avec KSP-TRANSPORT-007
```

Ne pas exposer un client Tonic brut permettant de contourner les capabilities ou l'observabilité KSP sans justification.

---

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

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

Avant changement significatif :

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
cargo tree -p ksp-onchain-transport-lib
cargo tree -p ksp-onchain-transport-lib --duplicates
```

Enregistrer :

```text
version Cargo stable
versions directes Transport
principaux doublons transitifs
état tests
état docs/plan/validation 0.2.8
```

### 11.2 Audit normatif Yellowstone actuel

Produire une matrice exhaustive avec, pour chaque RPC/message/capacité :

```text
nom
source normative
présence release stable / master
statut standard vs extension
request fields
response/update variants
optional/oneof semantics
limites documentées
provider-neutral oui/non
cible 0.2.9 oui/non/report
raison du report
preuve/test prévu
```

Inventorier explicitement le service `Geyser` courant et les messages `SubscribeRequest` / `SubscribeUpdate`.

### 11.3 Audit dépendances et licences

Avant d'ajouter quoi que ce soit :

```text
version stable yellowstone-grpc-client
version stable yellowstone-grpc-proto
versions tonic/prost nécessaires
MSRV
features par défaut
build dependencies/protoc
licences de chaque crate et du repo/proto
compatibilité avec la distribution MIT de KSP
transitifs Solana/Agave imposés ou non
```

Comparer les stratégies A/B/C de la section 7.

Produire les `cargo tree` hypothétiques ou réels nécessaires avant de valider la stratégie.

### 11.4 Audit architecture KSP

Décider et documenter :

```text
noms des settings/types gRPC
séparation HTTP/WS/gRPC
ownership du client/session
shape public vs wire interne
metadata/auth contract
Config shape éventuelle
error mapping
logging target
lifecycle/reconnect/backpressure
smoke ownership
```

### 11.5 Threat model

Brainstormer au minimum :

```text
credential metadata leak
URI leak
provider Status message/details leak
malicious oversized message
stream flood/backpressure
filter explosion
filter-name collision/untrusted names
unknown enum/oneof value
server half-close
client half-close
reconnect loop
reconnect to different node with divergent slot history
duplicate/gap after replay/from_slot
late updates after local subscription mutation
TLS/certificate failures
unary call timeout
```

### 11.6 Sizing et prévision souple obligatoire

Avant implémentation lourde, produire :

```text
surface exacte retenue
surface explicitement reportée
stratégie dependencies/license
nombre prévisionnel de prereleases
objectif précis de chaque tranche
fichiers/contrats principaux attendus
preuves/tests/gates par tranche
budget nominal <= environ 15–20 min par tranche
risques et critères de split
```

La prévision de la section 12 est un **forecast initial**, pas une obligation.

Si l'audit démontre que `Subscribe + toutes variantes + unary + replay + Config + lifecycle` ne tient pas raisonnablement dans la release, **scinder avant d'ajouter le client lourd**. Exemple acceptable : conserver `0.2.9` comme foundation connexion + subset canonique et reporter une extension Yellowstone suivante explicitement dans la séquence.

### 11.7 Documents de sortie du gate

Créer/mettre à jour au minimum :

```text
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
deltas/0.2.9/pre.001.md
```

ainsi que les index concernés.

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

Gate positif seulement si :

```text
base stable v0.2.8 confirmée
baseline opérateur enregistrée
sources upstream actuelles relues
surface service/proto exhaustive inventoriée
standard vs provider-extension classifié
SubscribeDeshred explicitement classifié
unary RPCs explicitement classifiés
replay/from_slot semantics audités
strategy dependency choisie ou reportée avec raison
licence auditée avant ajout de crate/proto
MSRV/features/transitifs audités
architecture gRPC distincte de WS décidée
metadata/auth strategy provider-neutral décidée
Config shape décidée ou explicitement reportée
resource/backpressure bounds décidées
smoke ownership décidé
release dimensionnée
forecast recalibré
critères de split écrits
aucune implémentation lourde non justifiée déjà introduite
```

---

## 12. Prévision souple initiale des prereleases

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

```text
pre.001  audit Yellowstone actuel + service/proto matrix + licences/dependencies + architecture + threat model + sizing
         preuve : plan + validation matrix + dependency decision + forecast recalibré ; pas de client lourd avant gate

pre.002  stratégie proto/client matérialisée + settings/errors gRPC runtime + façade provider-neutral minimale
         preuve : Cargo/features justifiés + API/settings tests + redaction ; aucun Config coupling

pre.003  connexion/TLS/metadata générique + lifecycle session minimal + unary canaries retenus
         preuve : serveur gRPC local/fixture + timeout/TLS/error mapping + metadata secret-safe

pre.004  SubscribeRequest foundation : filter maps + commitment + ping/from_slot + validation/bounds communs
         preuve : wire exact + omitted/empty semantics + bounds avant I/O + Debug safe

pre.005  Accounts + Slots : filtres, data slices et updates typed retenus
         preuve : account/slot fixtures exactes + malformed/unknown/adversarial cases

pre.006  Transactions + transaction_status : filtres et updates typed retenus
         preuve : account include/exclude/required + vote/failed/signature + status/meta lossless utile

pre.007  Blocks + block_meta + entry et autres variantes standard retenues
         preuve : fixtures exactes + optional/oneof + payload bounds ; split si tranche trop large

pre.008  stream bidirectionnel : mutation request, Ping/Pong, close/half-close, backpressure et shutdown bornés
         preuve : actor/session tests locaux + bounded queues + cleanup déterministe

pre.009  reconnect/resubscribe + from_slot/replay semantics + gaps/duplicates + adversarial lifecycle
         preuve : reconnect local déterministe + continuité explicitement non-lossless si non prouvée

pre.010  Config Transport gRPC si retenue + schema/fixtures + mapping Config -> Transport + secret provenance
         preuve : backward Config + no Transport -> Config + redaction + profile/provider-neutral

pre.011  compliance Yellowstone + non-régressions HTTP 52/14 + Standard WS 18/18 + Helius + API/firewall/security
         preuve : release-completeness + dependency boundaries + workspace ciblé

pre.012  smoke live opt-in si stratégie architecture-safe + README/USAGE + cargo tree direct/duplicates final
         preuve : aucune credential versionnée + provider test-only + docs version-neutral

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

rel.001  publication stable stricte
```

Règles :

```text
chaque tranche vise nominalement 15–20 min de travail effectif
pre.001 peut fusionner/scinder/déplacer/ajouter des prereleases
un fix peut être inséré après n'importe quelle tranche
pre.013 n'est pas une deadline
le numéro final n'est jamais un critère de clôture
une extension normative découverte tardivement peut créer pre.014+
une release trop large doit être scindée avant implémentation lourde
```

Le forecast détaillé vit dans le plan de release. `ROADMAP.md` reste global et `CHANGELOG.md` reste principalement réservé à la clôture stable.

---

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

Convention :

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

Une prerelease non-fix synchronise toujours `workspace.package.version`, même si elle est surtout documentaire.

Un fix purement documentaire suit `VERSION_WORKFLOW.md` et ne force pas une version Cargo si aucun artefact code/build/runtime/config/migration n'est modifié.

Deltas :

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

Commits :

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

Archives :

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

Les archives delta contiennent uniquement les fichiers ajoutés/modifiés, avec leurs chemins workspace.

Aucun tag Git prerelease. Le tag stable attendu est seulement :

```text
v0.2.9
```

Les deltas déjà publiés sont immuables ; un correctif crée un nouveau `fix.MMM`.

---

## 14. Validation opérateur et application

Après application d'une tranche 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 :

```bash
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-config-lib          # si Config modifiée
```

À la fermeture d'une prerelease technique :

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

Quand le graphe gRPC est ajouté/modifié :

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

Inspecter explicitement :

```text
yellowstone-grpc-* directes éventuelles
tonic/prost/prost-types
tower/http/hyper/bytes
rustls/tokio-rustls
Solana/Agave transitifs inattendus
versions dupliquées
features activées
```

Un doublon transitif peut être accepté s'il est inévitable et documenté. Ne pas dégrader une dépendance moderne uniquement pour forcer une unification artificielle.

### Tests gRPC attendus

Selon le scope final :

```text
settings validation
endpoint/TLS validation
metadata redaction
connection errors safe
unary request/response exact
Subscribe request wire
filter validation/bounds
update oneof decode
unknown enum/oneof behavior
stream open/send/receive/close
server half-close
client close
Ping/Pong
backpressure
oversized inbound/outbound
provider Status safe mapping
reconnect budget
resubscribe ordering
from_slot/replay semantics
duplicate/gap observability
shutdown during reconnect
public API crate-root
release completeness
```

### Smoke live

Le smoke live est **opt-in**.

Il ne peut pas justifier :

```text
secret versionné
std::env lu dans Transport
provider API publique hardcodée
nouveau smoke cross-crates ajouté à Config par facilité
```

Si une future surface d'intégration/orchestration KSP n'existe toujours pas, documenter la stratégie opérateur au lieu de casser les frontières.

### Frontend/Tauri

Aucun build Tauri n'est requis par défaut pour une release Transport pure si aucune application n'est modifiée.

---

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

La release ne peut devenir stable que si :

```text
surface Yellowstone actuelle réauditée
standard vs extension provider explicitement classifié
scope final documenté sans dette silencieuse
strategy licence/dependencies justifiée
backend gRPC distinct de HTTP/WS
provider-neutral public API
secrets/metadata redacted
resource bounds explicites
stream lifecycle borné
backpressure/shutdown testés
reconnect/replay semantics documentés honnêtement
aucune promesse lossless non prouvée
Config -> Transport seulement
aucun Transport -> Config/Store/Program
aucun tracing direct dans Transport
aucun provider commercial propriétaire du contrat
HTTP 52 current + 14 historical non régressé
Standard WebSocket 18/18 non régressé
Helius WebSocket non régressé
public API canaries verts
release-completeness vert
workspace complet vert
cargo tree final inspecté
README/USAGE synchronisés
matrice Yellowstone fermée
forecast réalisé ou recalibré explicitement
prompt 0.2.10 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.013`, continuer avec `pre.014+` ou des fixes.

`CHANGELOG.md` et le statut stable du `ROADMAP.md` sont finalisés à `rel.001`, pas artificiellement avant.

---

## 16. Release/session suivante envisagée

La release suivante prévue est :

```text
0.2.10 — off-chain price transport
```

Mission pressentie :

```text
introduire ksp-offchain-transport-lib
premier besoin réel = prix
au minimum SOL/USD et SOL/EUR
provider interchangeable derrière un contrat KSP
erreurs/timeouts/observabilité
```

Ne pas anticiper `0.2.10` dans Yellowstone en ajoutant des dépendances prix ou une abstraction réseau globale commune on-chain/off-chain.

`0.2.11` reste la Price Desk + intégration prix dans Wallet Desk, après validation du composant off-chain spécialisé.

---

## 17. Instruction d'ouverture

Au début de la session `0.2.9` :

1. confirmer la base stable `v0.2.8` ou l'archive stable autoritaire ;
2. vérifier `workspace.package.version = 0.2.8` et `deltas/0.2.8/rel.001.md` ;
3. lire les sources internes obligatoires dans l'ordre de la section 3 ;
4. relire les plans/validations HTTP, WebSocket standard et Helius ;
5. inspecter le code réel de Transport/Config avant de proposer les types gRPC ;
6. exécuter et enregistrer la baseline avant modification ;
7. réauditer **immédiatement** l'upstream Yellowstone courant : release, changelog, `geyser.proto`, `solana-storage.proto`, client/proto crates ;
8. dresser la matrice exacte des RPCs, filtres, updates, replay et extensions ;
9. séparer standard Yellowstone, extensions Triton/provider et pré-exécution/deshred ;
10. auditer licences, MSRV, versions `yellowstone-grpc-*`, `tonic` et `prost` avant toute dépendance ;
11. comparer les stratégies client/proto A/B/C ;
12. brainstormer credentials, message bounds, backpressure, reconnect, replay/gaps et smoke ownership ;
13. dimensionner chaque tranche à environ 15–20 minutes et **recalibrer explicitement la prévision souple de la section 12** ;
14. créer le plan, la validation et `deltas/0.2.9/pre.001.md` avec le forecast recalibré ;
15. exécuter les validations de gate disponibles ;
16. **ne pas ajouter `yellowstone-grpc-client`, `yellowstone-grpc-proto`, `tonic`, `prost`, un `grpc_endpoint` Config ou un client gRPC de production avant que le gate dependencies/licence/architecture/sizing soit cohérent**.

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