khadhroony-solana-project/prompts/012-V0_2_7_START_PROMPT.md

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 :

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 :

0.2.7 — WebSocket Solana standard

La première tranche est :

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 :

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 :

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

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

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

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

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 :

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 :

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 à :

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 :

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 :

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 :

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 :

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 :

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

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 :

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 :

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

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

workspace.package.version = 0.2.7-pre.1
livraison                 = 0.2.7-pre.001
commit                    = v0.2.7-pre.001

Pour un correctif :

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 :

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 :

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

Pendant le développement :

cargo test -p ksp-onchain-transport-lib

Si Config est modifié :

cargo test -p ksp-config-lib

Aux checkpoints de clôture technique et à la fin de la release :

cargo test --workspace

Lorsque le graphe de dépendances WebSocket change, inspecter au minimum :

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 :

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 :

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 :

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.