35 KiB
Prompt de démarrage 0.2.8 — Helius LaserStream WebSocket
1. Identité de la release et base exacte requise
La release à ouvrir est :
0.2.8 — Helius LaserStream WebSocket
Elle doit démarrer uniquement après publication stable de 0.2.7.
Base Git attendue :
v0.2.7
La base stable doit contenir au minimum :
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 :
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 :
workspace.package.version = "0.2.7"
La première livraison de la release sera :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
WsProtocolKind
WsEndpointSettings
WsTransportSettings
WsSessionSettings
WsSession
WsSubscription<T>
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 :
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 :
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 :
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 :
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 :
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 :
account
block
logs
program
root
signature
slot
slotsUpdates
vote
soit :
9 subscribe + 9 unsubscribe = 18 opérations standard
Partition stable/unstable héritée :
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 :
1 WsEndpointSettings
-> 0..N sessions physiques explicitement créées
-> 0..N logical subscriptions
Identités :
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 :
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 :
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 :
URL complète
query api-key
authorization secret
headers sensibles
remote subscription id
raw notification arbitraire
payload massif
5.6 Config V2
Contrat stable :
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 :
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 :
ksp-config-lib -> ksp-onchain-transport-lib
Interdictions durables :
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
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 :
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 :
- une matrice normative Helius WebSocket actuelle et sourcée ;
- un inventaire explicite standard supporté / standard non supporté / extension Helius ;
- le choix d'extension de
WsProtocolKindet du Config V2 ; - la réutilisation du
WsSessionactor existant ; transactionSubscribe/unsubscribe si toujours supportés et documentés ;- les filtres/options Helius réellement utiles et documentés ;
- les extensions Helius de
accountSubscribe/programSubscribesi toujours présentes ; - une politique provider capability sans contamination de la surface standard ;
- heartbeat/idle handling si réellement requis ;
- fixtures locales déterministes de toutes les extensions ;
- tests de reconnect/resubscribe/unsubscribe/backpressure sur les nouvelles familles ;
- redaction credentials Helius et erreurs sûres ;
- adaptation Config -> Transport correspondante ;
- canaries de non-régression 18/18 standard + 52/14 HTTP ;
- documentation README/USAGE durable et version-neutral ;
- stratégie de smoke live opt-in compatible avec les règles Config/secret ;
- audit final des dépendances et prompt
0.2.9.
Créer normalement :
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
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 :
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 :
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 :
une capability provider-specific
un setting explicite
un comportement automatique borné
ou une responsabilité caller
Toute solution automatique doit :
ê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 :
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
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 :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Puis inspecter au minimum :
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 :
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 :
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 :
WsProtocolKind
WsEndpointSettings
WsSessionSettings
WsSubscriptionKind
subscribe_typed interne
registry/remapping remote/local
reconnect/resubscribe
Config V2 kind
Décider quelles parties sont :
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 :
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 :
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 :
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 :
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
deltas/0.2.8/pre.001.md
Règles de granularité :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
v0.2.8-pre.001
v0.2.8-pre.001-fix.001
...
v0.2.8-rel.001
Archives d'échange usuelles :
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 :
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 :
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 :
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 :
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 :
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-config-lib
À la fermeture d'une tranche technique importante et de la release :
cargo test --workspace
Lorsque le graphe de dépendances change ou constitue un gate :
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 :
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 :
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 :
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 :
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 :
- vérifier que la base est réellement
v0.2.7ou l'archive stable autoritaire fournie ; - vérifier
workspace.package.version = 0.2.7et la présence dedeltas/0.2.7/rel.001.md; - lire les sources internes obligatoires dans l'ordre indiqué ;
- relire le plan, la matrice finale WebSocket standard,
KSP-TRANSPORT-007et les différés pertinents ; - inspecter le code public/réel de
WsSession,WsSubscription,WsProtocolKindet Config V2 ; - exécuter/enregistrer la baseline disponible avant modification ;
- réauditer immédiatement la documentation officielle Helius LaserStream WebSocket du jour ;
- produire la matrice standard/supporté/extension/non-supporté ;
- brainstormer provider credentials, heartbeat, capabilities, reconnect et tests ;
- dimensionner la release par tranches d'environ 15–20 minutes et recalibrer explicitement la prévision souple de la section 12 ;
- écrire le plan, la matrice et
deltas/0.2.8/pre.001.mdavec ce forecast recalibré ; - exécuter les validations de gate disponibles ;
- 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.