# Prompt de démarrage `0.2.7` — WebSocket Solana standard ## 1. Identité de la release et base exacte La base attendue est **exclusivement** la release stable : ```text v0.2.6 ``` Ne pas ouvrir `0.2.7` depuis une prerelease `0.2.6-pre.*`, depuis un ancien ZIP intermédiaire ou depuis un souvenir de session. Si une archive opérateur de `v0.2.6` est fournie au démarrage, **cette archive réelle est la première autorité** devant les snippets, anciennes archives, anciens prompts et mémoire de conversation. La release à ouvrir est : ```text 0.2.7 — WebSocket Solana standard ``` La première tranche est : ```text 0.2.7-pre.001 ``` `pre.001` est obligatoirement une tranche de **lecture, audit interne/externe, brainstorming, threat-model, inventaire exhaustif et sizing**. Elle ne doit pas se transformer automatiquement en implémentation WebSocket lourde. `0.2.6` a stabilisé avant cette reprise : ```text ksp-app-wallet-desk .kspwallet V1 historique + V2 binaire par défaut APIs Wallet génériques/versionnées V1/V2 migration V1 -> V2 explicite et OWNER-authentifiée runtime packagé commun aux Desks sans dépendance au checkout source transport HTTP Solana stable hérité de 0.2.1–0.2.4 ``` Le chantier `.kspwallet` V2 ayant été ramené dans `0.2.6`, `0.2.7` revient à la séquence Transport prévue : **WebSocket Solana standard**, avant les extensions provider-specific. ## 2. Mission et résultat attendu Étendre `ksp-onchain-transport-lib` avec une surface WebSocket Solana **standard, async, provider-neutral, typée et observable**, sans casser ni dupliquer la foundation HTTP acquise. La release doit aboutir à une base réutilisable par bibliothèques, applications, jobs et futurs workers, avec au minimum : ```text settings runtime WebSocket publics possédés par Transport connexion physique WebSocket explicite plusieurs sessions physiques possibles sur une même URL plusieurs subscriptions par session subscribe / unsubscribe standards ciblés notifications typées et wire-lossless lorsque nécessaire lifecycle explicite des sessions et subscriptions reconnexion bornée resubscribe déterministe selon policy retenue backpressure bornée cancellation et shutdown propres observabilité sûre via ksp-logging-lib adapter Config -> settings WebSocket si requis par le contrat retenu fixtures/tests déterministes smoke live opt-in lorsque raisonnablement accessible matrice de compliance WebSocket durable README / USAGE complets ``` La release ne doit pas introduire un deuxième transport on-chain concurrent : HTTP, WebSocket puis les futurs backends restent des responsabilités de `ksp-onchain-transport-lib`. ## 3. Sources de vérité internes obligatoires — ordre de lecture La nouvelle session doit être autonome : **ne pas reconstruire les règles de mémoire et ne pas commencer par coder**. Lire avant toute modification, dans cet ordre. ### 3.1 Entrées et règles globales ```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/PROMPT_STRUCTURE.md docs/rules/VERSION_WORKFLOW.md docs/rules/FILE_CONTRACTS.md ``` ### 3.2 Architecture à préserver ```text 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 ``` `009-ACQUISITION_WORKERS_AND_JOBS.md` est à relire pour éviter de déplacer par anticipation orchestration, persistence ou logique worker dans Transport. ### 3.3 Séquence, plans et compliance Transport ```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/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 ``` Important : `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` porte la **numérotation courante**. `007-V0_2_0_SERIES_PLANNING.md` reste une source historique utile pour l'intention Transport, mais certaines anciennes numérotations y ont été dépassées par les redécoupages `0.2.x` ; ne pas la traiter comme autorité supérieure au plan fonctionnel courant. ### 3.4 Contrats publics actuels à réauditer ```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 config/std.transport.json config/schemas/std.transport.schema.json ``` Lire aussi les contrats réellement consommés de : ```text crates/ksp-core-lib crates/ksp-logging-lib ``` Ne jamais supposer une API à partir d'une ancienne session : **les sources réellement présentes dans `v0.2.6` priment**. ### 3.5 Clôture `0.2.6` Si le delta stable a déjà été matérialisé dans la base fournie, relire : ```text deltas/0.2.6/rel.001.md docs/plans/013-V0_2_6_WALLET_DESK_PLAN.md docs/validation/009-V0_2_6_WALLET_DESK_COMPLIANCE.md ``` Le but n'est pas de continuer Wallet Desk, mais de connaître exactement le checkpoint stable dont `0.2.7` hérite. ## 4. Référence historique bot3 Si la dernière archive `khadhroony-bot3` est disponible dans la nouvelle session, auditer son transport WebSocket comme **référence fonctionnelle et historique uniquement**. Chercher au minimum dans `ks-onchain-transport` les modules/fichiers relatifs à : ```text websocket / ws session subscription / unsubscribe notifications reconnect / retry standard Solana WS Helius / LaserStream éventuel settings / provider / endpoint ``` Comparer aussi les consumers bot3 qui utilisaient réellement ces flux. Reprendre les besoins et invariants utiles ; ne pas recopier automatiquement : ```text dépendance Transport -> Config modèles Store/Program dans Transport tracing direct scheduler de sessions complexe non démontré provider-specific mélangé au standard ancienne crate WebSocket uniquement parce qu'elle existait anciens choix de versions/features sans réaudit actuel ``` Bot3 n'est jamais une source normative supérieure aux règles et contrats KSP actuels. ## 5. Sources externes normatives à réauditer en `pre.001` La surface WebSocket et les crates externes peuvent évoluer. Au début de `pre.001`, consulter les **sources officielles actuelles**, pas une liste mémorisée. Auditer au minimum : ```text documentation officielle Solana RPC WebSocket actuelle index officiel des subscriptions WebSocket pages officielles de chaque subscribe / unsubscribe formes de notifications associées statuts deprecated / unstable / experimental lorsque documentés source Agave/RPC uniquement lorsque la documentation publique est ambiguë ou incomplète spécification/projet officiel de la crate WebSocket Rust candidate ``` Pour chaque opération standard documentée, relever au minimum : ```text nom subscribe nom unsubscribe associé paramètres obligatoires config / commitment / encoding / filters forme du résultat de souscription forme exacte de notification nullable / optional / champs conditionnels limites ou préconditions documentées statut stable | deprecated | unstable écarts provider observés source normative stratégie de test ``` **Ne figer aucun nombre de subscriptions dans ce prompt.** `pre.001` doit refaire l'inventaire officiel du jour et produire le compte réel. Auditer également la version stable courante des dépendances Rust candidates et leurs features réellement nécessaires. Ne pas ajouter une dépendance parce qu'elle est connue ou parce que bot3 l'utilisait. ## 6. État validé et frontières à préserver Le transport HTTP acquis reste un contrat stable de référence : ```text 52/52 méthodes HTTP courantes typées 14/14 méthodes historiques Deprecated conservées pour compliance KSP-TRANSPORT-007 appliqué à la surface HTTP retry/no-resend write submissions déjà centralisé Config -> Transport autorisé Transport -X-> Config ``` Les frontières durables restent : ```text ksp-onchain-transport-lib -> ksp-core-lib -> ksp-logging-lib -> crates réseau externes strictement nécessaires ksp-config-lib -> ksp-onchain-transport-lib # adapter autorisé 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 ``` `ksp-logging-lib` reste l'unique façade d'émission runtime KSP. Une donnée WebSocket Transport reste une donnée de transport/wire. `0.2.7` ne doit pas introduire de décodage Program, materialization, persistence Store ou politique d'exécution. ## 7. Décisions acquises et questions ouvertes ### 7.1 Décisions déjà acquises — ne pas les redébattre sans contradiction réelle ```text une même URL peut porter plusieurs sessions physiques une session physique peut porter plusieurs subscriptions le public contract doit permettre cette cardinalité dès la foundation aucun scheduler/pool automatique sophistiqué de sessions sans besoin démontré les extensions Helius ne définissent pas le moteur standard les URLs/credentials provider ne doivent jamais fuiter via Debug/logs/snapshots les opérations standard ciblées doivent être couvertes exhaustivement les paramètres/options/variantes de réponse utiles doivent être conservés sans perte les smokes live restent opt-in ; les fixtures déterministes sont les gates reproductibles ``` ### 7.2 Questions réellement ouvertes à trancher en `pre.001` Le gate doit décider, avec justification : ```text crate(s) WebSocket Rust retenue(s) et features minimales forme des WsTransportSettings / WsEndpointSettings / WsSessionSettings réutilisation ou séparation des metadata provider/cluster/roles HTTP forme du Config standard : extension de std.transport ou autre shape justifié API de création/fermeture d'une session physique modèle public de WsSubscription / handle / subscription id state machine session + subscription ownership des tâches async et stratégie de cancellation reconnexion : déclencheurs, budget, backoff, jitter éventuel, reset resubscribe : automatique ou policy explicite, ordre et état observable comportement lorsqu'une reconnexion crée une fenêtre de notifications potentiellement manquées backpressure : queues bornées, overflow policy, observabilité limites de frame/message/JSON et défense contre allocations non bornées ping/pong/keepalive/idle timeout réellement nécessaires mapping des erreurs transport/protocole/RPC vers KspError API générique éventuelle pour extensions provider sans remplacer les wrappers typés standards réutilisation des DTOs HTTP communs vs types WebSocket dédiés snapshot runtime sûr : session state, subscription counts, reconnect state, jamais URL secrète stratégie de tests local mock server et smoke live ``` Une question ouverte peut rester différée si elle n'est pas nécessaire à `0.2.7`, mais la décision de différer doit être écrite dans le plan. ## 8. Objectifs/livrables de `0.2.7` Le plan détaillé créé en `pre.001` doit au minimum prévoir : 1. une **matrice WebSocket normative** exhaustive et sourcée ; 2. les settings publics WebSocket Transport ; 3. le lifecycle d'une session physique ; 4. un registre de subscriptions attaché à une session ; 5. les subscribe/unsubscribe standards retenus ; 6. les notifications typées associées ; 7. reconnexion/resubscribe selon le contrat décidé ; 8. backpressure/cancellation/shutdown bornés ; 9. logs/snapshots sûrs ; 10. adapter Config -> Transport lorsque nécessaire ; 11. fixtures et serveur de test local déterministe ou équivalent ; 12. tests adversariaux/lifecycle/reconnect ; 13. smoke live opt-in ; 14. README/USAGE et validation finale de compliance. Créer normalement : ```text docs/plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md docs/validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md ``` Si la base stable contient déjà ces numéros pour une autre raison, choisir les prochains numéros disponibles et mettre à jour les index correspondants ; ne jamais écraser un document existant. ## 9. Hors périmètre explicite ```text Helius LaserStream WebSocket -> 0.2.8 Yellowstone gRPC standard -> 0.2.9 providers Yellowstone commerciaux spécifiques -> plus tard shred/deshred/pre-execution feeds -> plus tard ksp-offchain-transport-lib / prix -> 0.2.10 Wallet / 2FA / nouveau .kspwallet -> hors 0.2.7 Store / RAW persistence -> série 0.3.x Program decode / materialization -> plus tard frontend réseau direct -> interdit scheduler/pool automatique complexe de sessions -> IDEAS jusqu'à besoin démontré ``` `0.2.7` peut préparer des points d'extension nécessaires à `0.2.8`, mais ne doit pas implémenter des paramètres Helius sous couvert de généricité. ## 10. Contraintes sécurité, lifecycle et API ### 10.1 Secrets et observabilité Ne jamais exposer dans `Debug`, `Display`, erreurs ou logs : ```text URL complète contenant credentials/query token Authorization metadata éventuelle headers sensibles payloads massifs contenu brut arbitraire des notifications ``` Les logs peuvent contenir des identités logiques sûres : endpoint name, provider label, cluster, session id KSP, subscription kind, compteurs, état lifecycle et causes d'erreur qualifiées sans secret. ### 10.2 Bornes de ressources La surface WebSocket doit être explicitement bornée contre : ```text frames/messages surdimensionnés JSON non borné queues de notifications illimitées reconnect loop sans budget spawn/task leaks subscriptions orphelines shutdown bloqué resubscribe stale après unsubscribe croissance non bornée d'état par IDs serveur ``` Ne pas transformer une option de provider particulier en limite universelle Solana sans source normative. ### 10.3 State machines Le plan doit rendre observables des états suffisamment précis pour raisonner sur : ```text session disconnected / connecting / active / reconnecting / closing / closed subscription requested / active / resubscribing / cancelling / closed / failed ``` Les noms exacts ne sont pas imposés par ce prompt. L'objectif est d'éviter qu'un simple booléen masque des transitions concurrentes importantes. ### 10.4 Notifications et losslessness Les DTOs Transport doivent préserver les variantes wire utiles et les distinctions `omitted/null/value` lorsqu'elles ont une sémantique. Ne pas convertir les notifications en modèles métier Program/SPL. ## 11. Première mission `0.2.7-pre.001` — gate obligatoire Ordre de travail : ```text 1. vérifier que la base réelle correspond à v0.2.6 stable 2. relire toutes les sources internes obligatoires dans l'ordre indiqué 3. exécuter le baseline Rust avant modification 4. inventorier l'état réel de ksp-onchain-transport-lib et de l'adapter Config 5. auditer bot3 si sa dernière archive est disponible 6. auditer les docs officielles Solana WebSocket actuelles 7. produire la matrice subscribe/unsubscribe/notification exhaustive 8. auditer les dépendances Rust candidates et leurs versions/features actuelles 9. dessiner le modèle session/subscription et les state machines 10. faire le threat-model reconnect/backpressure/cancellation/shutdown/secrets 11. décider le shape Config minimal et la frontière HTTP/WS 12. produire le plan détaillé + matrice de compliance initiale 13. dimensionner chaque prerelease (~15–20 min nominales maximum par tranche intermédiaire) 14. recalibrer la prévision souple 15. seulement après ce gate, ouvrir l'implémentation technique suivante ``` Baseline de début de session : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Si la base stable est supposée propre mais qu'un de ces gates échoue, diagnostiquer l'écart avant d'ajouter la surface WebSocket. ### Critères de sortie de `pre.001` `pre.001` peut être clôturé lorsque : ```text la base v0.2.6 est vérifiée les règles/documents obligatoires ont été relus l'inventaire WebSocket officiel est sourcé et compté les statuts stable/deprecated/unstable sont identifiés les dépendances candidates sont auditées le modèle session/subscription est suffisamment précis reconnect/resubscribe/backpressure/cancellation ont une policy proposée les frontières Config/Transport sont confirmées les risques principaux sont recensés le plan détaillé et la compliance initiale existent le sizing indique que 0.2.7 est clôturable dans la session, sinon la release est redécoupée avant développement lourd ``` Aucune surface lourde ne doit être considérée acquise simplement parce qu'un prototype compile pendant ce gate. ## 12. Prévision souple initiale des prereleases Point de départ proposé, **à recalibrer par `pre.001`** : ```text pre.001 lectures + audit officiel + matrice WS + threat-model + dépendances + sizing pre.002 settings/contracts WS + Config adapter minimal + types lifecycle pre.003 session physique + connect/read/write + cancellation/shutdown + tests locaux pre.004 registre subscriptions + subscribe/unsubscribe génériques + reconnect/resubscribe/backpressure pre.005 premier lot de wrappers standard + notifications typées pre.006 reste de la surface standard + unstable/deprecated + KSP-TRANSPORT-007 WS pre.007 adversarial/lifecycle/reconnect + composition Config + smoke live opt-in + compliance pre.008 README/USAGE + graphes dépendances + validation finale + prompt 0.2.8 rel.001 publication stable 0.2.7 ``` Cette séquence est un **forecast**, pas une obligation de finir à `pre.008`. Règles de sizing : - scinder une tranche intermédiaire qui paraît dépasser environ 15–20 minutes de travail effectif nominal ; - insérer `pre.NNN` ou `fix.NNN` plutôt que comprimer une surface incomplète ; - si l'inventaire officiel est plus large ou plus complexe que prévu, redécouper avant implémentation lourde ; - plusieurs petits lots de wrappers sont préférables à une prerelease monolithique ; - le numéro de prerelease n'a jamais priorité sur la complétude du contrat. ## 13. Versionnement, deltas, commits et documentation de progression À l'ouverture : ```text workspace.package.version = 0.2.7-pre.1 livraison = 0.2.7-pre.001 commit = v0.2.7-pre.001 ``` Pour un correctif : ```text livraison = 0.2.7-pre.NNN-fix.MMM Cargo = 0.2.7-pre.N.fix.M si code/build/runtime/config/migration change ``` Règles à préserver : ```text deltas/0.2.7/pre.NNN.md pour chaque tranche deltas/0.2.7/pre.NNN-fix.MMM.md pour les fixes aucun tag prerelease tag stable seulement v0.2.7 après rel.001 CHANGELOG.md principalement à la clôture ROADMAP.md seulement au niveau global progression détaillée dans le plan + deltas, pas dans ROADMAP pas de Cargo.lock / package-lock.json versionné ``` Toute dépendance tierce commune est déclarée dans `[workspace.dependencies]`; les member crates utilisent `.workspace = true`. Une nouvelle prerelease non-fix synchronise `workspace.package.version` même si son contenu final est surtout documentaire, conformément à `VERSION_WORKFLOW.md`. ## 14. Validation opérateur pendant la release Après toute modification Rust : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Pendant le développement : ```bash cargo test -p ksp-onchain-transport-lib ``` Si Config est modifié : ```bash cargo test -p ksp-config-lib ``` Aux checkpoints de clôture technique et à la fin de la release : ```bash cargo test --workspace ``` Lorsque le graphe de dépendances WebSocket change, inspecter au minimum : ```bash cargo tree -p ksp-onchain-transport-lib --depth 1 cargo tree -p ksp-onchain-transport-lib -d ``` Les doublons transitifs ne sont pas automatiquement un défaut : documenter ceux imposés par des chaînes externes compatibles plutôt que forcer une unification artificielle. ### Tests WebSocket attendus Privilégier un serveur local déterministe/fixture pour : ```text handshake et fermeture subscribe -> notification -> unsubscribe plusieurs subscriptions sur une session plusieurs sessions sur la même URL réponse RPC erreur notification malformée message oversized connexion interrompue reconnect borné resubscribe unsubscribe pendant reconnect shutdown avec subscriptions actives backpressure/overflow selon policy absence de fuite URL/credentials dans Debug/logs ``` Prévoir un smoke Solana live `#[ignore]` uniquement après stabilisation de la surface. Un problème de provider public/rate-limit externe n'est pas automatiquement une régression locale. Aucune application Tauri ne doit être modifiée pour « tester » WebSocket si un test Transport ou une surface d'intégration adaptée suffit. `cargo tauri build` n'est pas un gate normal de `0.2.7` tant qu'aucune application Tauri n'est réellement modifiée. Ne jamais déclarer une commande réussie si elle n'a pas réellement été exécutée. ## 15. Critères de clôture de `0.2.7` La release n'est clôturable que si : ```text la matrice officielle du jour est exhaustive et sourcée toutes les subscriptions standards retenues ont leur API KSP promise tous les unsubscribe associés sont couverts les notifications associées sont typées/lossless selon besoin les statuts deprecated/unstable sont centralisés et observables la cardinalité URL -> N sessions -> N subscriptions est réellement supportée reconnect/resubscribe ont un comportement borné et testé backpressure/cancellation/shutdown sont explicites et testés les URLs/credentials ne fuient pas Config -> Transport reste la seule direction d'adaptation HTTP ne régresse pas aucune logique Store/Program/worker n'a glissé dans Transport fixtures/tests déterministes sont verts le smoke live retenu est documenté et opt-in README/USAGE/compliance sont à jour graphes Cargo ont été inspectés si dépendances changées cargo test --workspace est vert le prompt 0.2.8 est préparé au niveau normatif KSP ``` Si une méthode officielle ne peut pas être supportée, l'impossibilité doit être documentée explicitement dans la matrice de compliance et validée ; elle ne peut pas être simplement oubliée. ## 16. Release suivante envisagée Après publication stable de `v0.2.7`, la release prévue est : ```text 0.2.8 — Helius LaserStream WebSocket ``` Elle doit étendre le moteur/session standard acquis sans dupliquer le client ni contaminer le contrat Solana standard avec des paramètres provider-only. Le prompt `0.2.8` sera préparé pendant la dernière prerelease de `0.2.7`, après audit des capacités Helius réellement actuelles. ## 17. Instruction d'ouverture de la prochaine session Au démarrage de la session `0.2.7` : > **Commencer par vérifier la base stable `v0.2.6`, lire les sources internes obligatoires dans l'ordre, exécuter le baseline Rust, puis faire l'audit officiel WebSocket + dependency audit + threat-model + sizing. Ne pas commencer par ajouter une crate WebSocket, écrire un client/session ou implémenter des wrappers tant que le gate `pre.001` n'a pas établi la surface normative, les state machines, les frontières et un découpage clôturable.** La première sortie attendue de la session est donc un **audit argumenté + brainstorming + plan détaillé souple**, pas un bloc d'implémentation opportuniste.