diff --git a/deltas/0.2.6/pre.018-fix.002.md b/deltas/0.2.6/pre.018-fix.002.md new file mode 100644 index 0000000..01b8fd0 --- /dev/null +++ b/deltas/0.2.6/pre.018-fix.002.md @@ -0,0 +1,110 @@ + + + +# Delta `0.2.6-pre.018-fix.002` — renforcement du prompt de reprise `0.2.7` + +## Nature du fix + +Ce correctif est **strictement documentaire**. + +Le gate opérateur de `0.2.6-pre.018-fix.001` est vert : `cargo fmt`, audit Rust KSP, `cargo check`, `cargo clippy`, tests ciblés, `cargo test --workspace` et le `cargo tauri build` final Wallet Desk ont été exécutés avec succès. + +Aucun code, build, runtime, Config exécutable ou migration n'est modifié ici. Conformément à `VER-ID-008`, le signal technique reste donc : + +```text +workspace.package.version = 0.2.6-pre.18.fix.1 +package/Tauri Desks = 0.2.6-pre.18.fix.1 +livraison documentaire = 0.2.6-pre.018-fix.002 +commit attendu = v0.2.6-pre.018-fix.002 +``` + +Aucun nouveau build n'est requis par ce fix documentaire et le build final déjà validé n'est pas invalidé. + +## Problème corrigé + +Le prompt `prompts/012-V0_2_7_START_PROMPT.md` préparé pendant `pre.018` annonçait correctement la mission WebSocket, mais restait trop court par rapport au contrat normatif de `docs/rules/PROMPT_STRUCTURE.md`. + +Il ne rendait pas assez explicites : + +```text +les sources internes obligatoires et leur ordre de lecture +les règles KSP à relire avant modification +la distinction sources courantes / plan historique +les contrats Transport/Config réellement à réauditer +la référence bot3 et son statut non normatif +les décisions acquises et questions encore ouvertes +les contraintes sécurité/lifecycle/backpressure +le gate de sortie précis de pre.001 +la prévision souple détaillée des prereleases +le workflow version/delta/commit/tag +les validations ciblées et réseau +les critères de clôture +l'instruction d'ouverture interdisant le code lourd avant sizing +``` + +## Prompt `0.2.7` renforcé + +Le prompt est réécrit comme contrat autonome de reprise pour une session démarrant sur le tag stable `v0.2.6`. + +Il impose maintenant la lecture ordonnée de : + +```text +RULES.md + docs/000-README.md +règles générales/KSP/Rust/dépendances/prompt/version/files +architecture et dependency graph +séquence fonctionnelle courante +plans/compliance HTTP Transport +contrats réels ksp-onchain-transport-lib + ksp-config-lib +clôture stable 0.2.6 lorsqu'elle est présente +``` + +Le document explicite que `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` porte la numérotation courante alors que `007-V0_2_0_SERIES_PLANNING.md` reste une source historique dont certaines anciennes numérotations ont été dépassées. + +## `pre.001` rehaussé au niveau KSP attendu + +Le gate `0.2.7-pre.001` exige désormais : + +```text +baseline stable v0.2.6 +lectures obligatoires +audit officiel Solana WebSocket actuel +inventaire exhaustif subscribe/unsubscribe/notifications +réaudit des dépendances Rust candidates +référence bot3 si disponible +state machines session/subscription +threat-model reconnect/resubscribe/backpressure/cancellation/shutdown +shape Config minimal +matrice de compliance initiale +plan détaillé +sizing de chaque tranche +``` + +Aucune implémentation WebSocket lourde ne doit commencer avant ce gate. + +## Prévision souple ajoutée + +Le forecast initial devient : + +```text +pre.001 audit/matrice/threat-model/dépendances/sizing +pre.002 settings/contracts WS + adapter Config + lifecycle types +pre.003 session physique + cancellation/shutdown + tests locaux +pre.004 subscriptions génériques + reconnect/resubscribe/backpressure +pre.005 premier lot wrappers/notifications standard +pre.006 reste surface standard + deprecated/unstable + compliance +pre.007 adversarial/reconnect + Config + smoke live opt-in +pre.008 README/USAGE + graphes + validation finale + prompt 0.2.8 +rel.001 +``` + +Ce forecast reste explicitement révisable par `pre.001`; il ne force pas la clôture à `pre.008`. + +## Fichiers modifiés + +```text +prompts/012-V0_2_7_START_PROMPT.md +prompts/000-README.md +deltas/0.2.6/pre.018-fix.002.md +``` + +Aucun autre fichier n'est modifié. diff --git a/prompts/000-README.md b/prompts/000-README.md index 272dbb8..e2cf418 100644 --- a/prompts/000-README.md +++ b/prompts/000-README.md @@ -1,5 +1,5 @@ - + # Prompts KSP @@ -32,4 +32,4 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par - [`009-V0_2_4_START_PROMPT.md`](009-V0_2_4_START_PROMPT.md) — prompt préparé par `0.2.3-pre.009`, destiné à ouvrir `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale` après publication stable de `0.2.3`; il cible les 15 wrappers restants et impose `KSP-TRANSPORT-007` ainsi qu'un nouvel audit/sizing à `pre.001`. - [`010-V0_2_5_START_PROMPT.md`](010-V0_2_5_START_PROMPT.md) — prompt préparé par `0.2.4-pre.009` puis finalisé en version 2 par `pre.009-fix.001`, destiné à ouvrir `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`; il impose audit/threat-model/sizing avant choix cryptographiques et cadre `.kspwallet` interopérable, capacités indépendantes VIEW/OWNER, metadata protégées, key slots/rotations, signature, persistence atomique et import/export extensible sans `WalletPolicy`. - [`011-V0_2_6_START_PROMPT.md`](011-V0_2_6_START_PROMPT.md) — prompt préparé par `0.2.5-pre.010` puis renforcé pendant `pre.010-fix.001`–`fix.003`, destiné à ouvrir `0.2.6 — Wallet Desk` après le tag stable `v0.2.5`; il impose une première tranche audit/sizing, rappelle les règles Rust/audit structurel, cadre Config composite + Wallet + HTTP `getBalance`, lifecycle VIEW/OWNER, sécurité password/export, validation frontend/Tauri et conserve le TODO `0.2.12` d’intégration des prix offchain dans Wallet Desk après validation de la Price Desk spécialisée. -- [`012-V0_2_7_START_PROMPT.md`](012-V0_2_7_START_PROMPT.md) — prompt réaligné par `0.2.6-pre.015` pour ouvrir `0.2.7 — WebSocket Solana standard`; le chantier `.kspwallet` V2 ayant été ramené dans `0.2.6`, il rétablit la séquence Transport et impose audit officiel/sizing avant implémentation. +- [`012-V0_2_7_START_PROMPT.md`](012-V0_2_7_START_PROMPT.md) — prompt réaligné par `0.2.6-pre.015` puis renforcé en contrat de reprise autonome par `0.2.6-pre.018-fix.002`; il ouvre `0.2.7 — WebSocket Solana standard` depuis `v0.2.6`, impose les lectures/règles ordonnées, l’audit officiel et historique, le threat-model session/subscription/reconnect/backpressure, la matrice de compliance, un gate `pre.001` strict et une prévision souple de prereleases avant toute implémentation lourde. diff --git a/prompts/012-V0_2_7_START_PROMPT.md b/prompts/012-V0_2_7_START_PROMPT.md index 753f571..17dc744 100644 --- a/prompts/012-V0_2_7_START_PROMPT.md +++ b/prompts/012-V0_2_7_START_PROMPT.md @@ -1,13 +1,17 @@ - + # Prompt de démarrage `0.2.7` — WebSocket Solana standard -## 1. Contexte de reprise +## 1. Identité de la release et base exacte -Base attendue : tag stable `v0.2.6`. +La base attendue est **exclusivement** la release stable : -`0.2.6` a validé Wallet Desk puis intégré le wire binaire `.kspwallet` V2, les APIs Wallet génériques/versionnées, la compatibilité V1/V2, les migrations explicites et le runtime packagé commun des Desks sans dépendance au checkout source. `0.2.7` revient donc à la séquence Transport prévue avant l'intercalation temporaire du chantier binaire. +```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 : @@ -15,68 +19,605 @@ La release à ouvrir est : 0.2.7 — WebSocket Solana standard ``` -`0.2.7-pre.001` commence obligatoirement par audit officiel actuel + inventory exhaustif des subscriptions/unsubscriptions/notifications + threat-model/reconnexion + sizing avant implémentation lourde. - -## 2. Mission - -Étendre `ksp-onchain-transport-lib` à la surface WebSocket Solana standard retenue, sans déplacer Config dans Transport et sans introduire encore Helius LaserStream. - -Contrat de sessions : +La première tranche est : ```text -une même URL peut porter plusieurs sessions physiques -une session peut porter plusieurs subscriptions -pas de pool/scheduler automatique complexe sans besoin démontré -reconnexion bornée et états de subscription explicites -notifications typées sans fuite d'URL/secrets dans Debug/logs +0.2.7-pre.001 ``` -## 3. Frontières +`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. -Conserver : +`0.2.6` a stabilisé avant cette reprise : ```text -Transport -X-> Config -Transport -X-> Wallet -Transport -X-> Store -Transport -X-> tracing direct -Config -> Transport autorisé -ksp-logging-lib seul propriétaire des émissions applicatives +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 ``` -## 4. Audit pre.001 +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 : -- documentation Solana/Agave actuelle ; -- méthodes subscribe/unsubscribe courantes, deprecated/unstable et notifications associées ; -- formes de paramètres/options et réponses ; -- reconnexion, resubscribe, backpressure, cancellation et shutdown ; -- plusieurs sessions pour une même URL ; -- limites provider utiles sans les figer comme règles Solana universelles ; -- dépendances WebSocket Rust actuelles et leur graphe ; -- sizing « une release = une session ». - -## 5. Hors périmètre - ```text -Helius LaserStream WebSocket -> 0.2.8 -Yellowstone gRPC -Store/materialization -Wallet/2FA -pool automatique sophistiqué de sessions WebSocket -frontend réseau direct +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 ``` -## 6. Validation +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 ``` -Prévoir des fixtures déterministes et un smoke réseau opt-in seulement lorsqu'une composition réelle le justifie. +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.