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