# Prompt de démarrage `0.3.13` — WS standard / Helius / HTTP live + convergence multi-source du Worker `RawTransaction` ## 1. Identité de la release et base exacte requise Ouvrir **uniquement** `0.3.13` depuis la release stable/taggée : ```text v0.3.12 ``` La base de travail fournie par l'opérateur est autoritaire sur les souvenirs, snippets, anciennes archives et deltas intermédiaires. Avant toute modification, vérifier au minimum : ```text workspace.package.version = 0.3.12 deltas/0.3.12/rel.001.md présent crates/ksp-worker-raw-transaction-ingest-lib présent avec source Yellowstone productive ksp-worker-raw-transaction-ingest-lib -> ksp-onchain-transport-lib matérialisé ksp-worker-raw-transaction-ingest-lib sans dépendance Config/Job/backend Store direct ksp-raw-transaction-lib présent comme Common RAW source-neutral ksp-store-lib reste la seule façade Store du Worker moteur WS standard/Helius existant dans ksp-onchain-transport-lib getTransaction/getBlock observed existants dans ksp-onchain-transport-lib ``` Release ouverte : ```text 0.3.13 ``` Première livraison attendue : ```text 0.3.13-pre.001 ``` `pre.001` est obligatoirement un gate de **lecture + audit interne/externe + brainstorming + sizing + planification**. Il ne commence pas directement les sources WS/Helius/HTTP polling ni la transformation de `RawTransactionIngestRuntimeResources` en collection multi-source. Si le périmètre réel n'est pas clôturable dans une seule session ou si une tranche paraît dépasser environ 15–20 minutes de travail effectif, rescinder avant l'implémentation lourde. ## 2. Mission et résultat attendu ### 2.1 Mission de `0.3.13` Étendre la verticale `0.3.12` avec les voies live complémentaires déjà qualifiées par l'architecture : ```text WS standard logsSubscribe + hydration HTTP WS standard blockSubscribe Helius transactionSubscribe + hydration HTTP HTTP live polling par slots/blocs convergence simultanée multi-source vers le pipeline central existant observations multiples pour une même RawTransaction coalescence/déduplication bornée avant hydration/admission content conflict explicite si une même identité produit un contenu canonique divergent backpressure et source health sous concurrence multi-source ``` Le résultat visé est un Worker capable de superviser plusieurs sources live indépendantes **sans second actor Transport**, sans lire Config lui-même et sans transformer la convergence en stratégie `first-provider-wins` silencieuse. ### 2.2 Pipeline durable à préserver Toutes les sources convergent vers le même cœur : ```text source live -> signal ou matériau source/protocole -> hydration si le RAW complet n'est pas prouvé -> ksp-raw-transaction-lib -> RawTransaction + RawTransactionObservation -> admission centrale Worker -> ksp-store-lib ``` Décisions déjà acquises : ```text logsSubscribe -> discovery/signature -> getTransaction hydration Helius transactionSubscribe -> matériau riche mais hydration tant que blockTime/version manquent blockSubscribe full/base64 -> RAW-direct uniquement sur le sous-ensemble déjà prouvé par fixtures HTTP polling -> getSlot/bornes -> getBlock observed -> transactions -> Common RAW même identité + même contenu -> idempotence + observations distinctes utiles même identité + contenu divergent -> content conflict explicite ``` Aucune source ne doit contourner Common RAW ou la façade Store. ## 3. Sources de vérité internes obligatoires — ordre de lecture ### 3.1 Gouvernance générale Lire intégralement, dans cet ordre : ```text RULES.md ROADMAP.md CHANGELOG.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 ``` Le prompt complète ces règles ; il ne les remplace pas. Rappels Rust bloquants : ```text Rust 2024 unsafe interdit unwrap / expect / panic interdits selon les règles KSP ? interdit en production retours explicites ; clippy::implicit_return deny #![warn(missing_docs)] #![deny(unreachable_pub)] #![forbid(unsafe_code)] pas de pub mod pub/pub(crate) partagés reexportés jusqu'à la crate root accès partagés via crate::Item, y compris intra-crate item strictement module-local => private unit tests sous unit_tests/ integration tests sous tests/ ``` Après toute modification Rust : ```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py cargo check --workspace cargo clippy --workspace --all-targets ``` Pour tout Markdown touché : ```bash python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas ``` Une commande non exécutée n'est jamais déclarée PASS. ### 3.2 Handoff stable `0.3.12` Lire intégralement : ```text docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml crates/ksp-worker-raw-transaction-ingest-lib/README.md crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md crates/ksp-worker-raw-transaction-ingest-lib/src/ crates/ksp-worker-raw-transaction-ingest-lib/tests/ crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/ ``` La verticale Yellowstone/hydration/frontier est une base à préserver, pas un prototype à remplacer. ### 3.3 Architecture RAW et convergence Lire intégralement : ```text docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md crates/ksp-raw-transaction-lib/README.md crates/ksp-raw-transaction-lib/USAGE.md crates/ksp-store-api/src/ crates/ksp-store-lib/src/ ``` Porter une attention particulière à : ```text observations multiples ≠ identité RawTransaction même identité + contenu divergent = conflit explicite capabilities orthogonales aux producteurs WS logsSubscribe WS blockSubscribe Helius transactionSubscribe HTTP getSlot/getBlock live polling provenance observed reconnect WS != replay adressable continuité multi-source finale encore reportée à 0.3.14 ``` ### 3.4 Transport WS / HTTP / Helius existant Lire au minimum : ```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/ws_*.rs crates/ksp-onchain-transport-lib/src/rpc_transactions.rs crates/ksp-onchain-transport-lib/src/rpc_blocks.rs crates/ksp-onchain-transport-lib/src/http_*.rs crates/ksp-onchain-transport-lib/tests/ ``` Réutiliser les sessions/actors Transport existants. Il est interdit de recréer dans le Worker : ```text nouveau socket WebSocket bas niveau client Helius parallèle client reqwest direct reconnect/resubscribe actor concurrent SDK provider ``` ### 3.5 Config et secrets Lire : ```text crates/ksp-config-lib/src/transport.rs config/transport*.json config/schema/*transport*.json .env.example ``` Config reste le seul propriétaire des endpoints, profils, capabilities et secrets. En particulier, si Helius est activé pour cette release, réutiliser exclusivement le secret Config déjà défini pour Helius ; le Worker ne lit jamais l'environnement et ne reçoit jamais une clé API comme payload métier. ## 4. Sources externes normatives et fraîcheur à réauditer Au début de `pre.001`, réauditer les surfaces courantes à partir des sources primaires réellement actuelles : ```text Solana RPC/WebSocket documentation logsSubscribe blockSubscribe getSlot / getBlocks / getBlocksWithLimit / getBlock commitment et maxSupportedTransactionVersion Helius documentation officielle transactionSubscribe filtres/options réellement supportés Mainnet/Devnet disponibles tier/quota/rate limits actuels champs blockTime/version réellement présents ou absents crates/projets primaires réellement concernés versions stables courantes features nécessaires ``` Ne pas figer dans le plan une limite provider historique sans la revalider. Une différence entre documentation externe actuelle et surface KSP existante devient un point d'audit explicite, pas une permission de contourner Transport. ## 5. État validé à préserver `0.3.12` fournit déjà : ```text Worker concret start/stop + supervisor admission centrale mpsc bornée persistence Store atomique/idempotente Common RAW Legacy/V0/V1 une source Yellowstone caller-composed Transaction / TransactionStatus / Block -> hydration transactionnelle BlockMeta / Slot -> continuity-only coalescence bornée network/signature/commitment getTransaction observed processing frontier run-local source state Active/Reconnecting/Closing/Closed/Failed compteurs reconnect/replay-attempt/continuity-gap fault sur gap de rétention prouvé shutdown borné + abort/join cross-layer dependency/security canaries ``` Frontières non négociables : ```text Worker -> Config interdit Worker -> Job Backfill interdit Worker -> backend Store physique interdit Transport -> Common RAW interdit Common RAW -> Transport interdit pas d'URL/token/provider payload dans snapshot/debug/error pas de checkpoint persistant de processing frontier pas de campagne historique arbitraire dans le Worker ``` Le gate `0.3.12` a aussi prouvé live HTTP Devnet et WebSocket Devnet keyless ; il n'a pas prouvé live Yellowstone ni un Worker end-to-end avec Store. Ne pas transformer ces non-preuves en hypothèses acquises. ## 6. Décisions acquises et questions réellement ouvertes ### 6.1 Décisions acquises ```text une RawTransaction est identifiée par (network, signature) la provenance appartient aux observations, pas à l'identité canonique plusieurs sources peuvent produire plusieurs observations du même RAW content conflict reste terminal/explicite, jamais first-provider-wins silencieux logsSubscribe nécessite hydration Helius transactionSubscribe nécessite hydration tant que son enveloppe reste incomplète pour RAW v1 blockSubscribe direct reste limité au sous-ensemble réellement qualifié HTTP polling est une source live valide s'il suit uniquement le frontier du run courant WS reconnect/resubscribe n'est pas un replay adressable repair de gap multi-source final appartient à 0.3.14 ``` ### 6.2 Questions à fermer par `pre.001` ```text forme exacte de RawTransactionIngestRuntimeResources multi-source identité/source key interne commune aux sources live activation simultanée vs priorités/fallback : sémantique exacte coalescence cross-source avant ou après hydration selon matériau disponible comment conserver plusieurs observations sans dupliquer la canonicalisation blockSubscribe : sous-ensembles Legacy/V0/V1 réellement directs aujourd'hui HTTP polling : borne initiale, cadence, slot skip et ownership du timer source health individuel vs agrégation Worker publique limites exactes de pending/coalescence par source et globales Helius : profils/tier réellement testables avec les comptes opérateur disponibles ``` Aucune de ces questions ne doit être tranchée par un ajout opportuniste pendant le codage. ## 7. Objectifs/livrables et hors périmètre ### 7.1 Livrables cibles Sous réserve du sizing `pre.001` : ```text contrat runtime resources réellement multi-source et borné source WS logsSubscribe productive + hydration source WS blockSubscribe productive source Helius transactionSubscribe productive + hydration source HTTP live block polling productive convergence vers la même admission/persistence centrale coalescence et observation semantics cross-source source health/backpressure/faults cohérents fixtures déterministes cross-source smokes live uniquement lorsqu'ils sont réellement accessibles README/USAGE/architecture réconciliés à la fin ``` ### 7.2 Hors périmètre `0.3.13` ```text gap repair multi-source complet replay historique arbitraire appel automatique au Backfill checkpoint durable Worker source archive/historical provider EARLY/pre-execution/shreds nouveau SDK provider nouveau backend Store ou migration Store nouvelle Desk d'ingestion extension du Job Backfill ``` Ces éléments appartiennent à `0.3.14+` ou `0.3.16` selon la roadmap. ## 8. Contraintes sécurité/API/architecture spécifiques La convergence multi-source doit rester bornée : ```text aucune Vec/Map de pending non bornée aucun task spawn non détenu aucun retry loop Worker redondant avec Transport aucune queue par provider sans borne explicite aucun drop silencieux sous saturation aucun changement de source qui efface une provenance déjà acquise ``` La sémantique de conflit reste : ```text même identité + même canonical RAW -> idempotence -> observation supplémentaire si sa clé est distincte même identité + canonical RAW divergent -> content conflict explicite -> arrêt/fault selon contrat Worker existant ``` Le tracing ne doit jamais inclure : ```text signature brute transaction/meta bytes logs provider URL endpoint API key/x-token filtres Helius sensibles remote error text non borné ``` Toute surface publique ajoutée doit être justifiée par un consumer réel. Préférer les types privés/crate-private et les snapshots source-neutral aux DTO provider-specific publics. ## 9. Première mission `pre.001` — audit/sizing obligatoire `pre.001` doit produire avant toute implémentation lourde : 1. vérification exacte de la base stable `v0.3.12` et de `deltas/0.3.12/rel.001.md` ; 2. lecture complète des sources internes listées ci-dessus ; 3. inventaire exact des acteurs/sessions/facades WS standard, Helius et HTTP existants ; 4. audit externe courant Solana/Helius et versions de crates réellement concernées ; 5. matrice par source : signal/material, RAW-direct ou hydration, provenance, reconnect, network, tier/preuve live ; 6. architecture cible de `RawTransactionIngestRuntimeResources` multi-source sans Worker -> Config ; 7. stratégie de source identity, source lifecycle et agrégation health ; 8. stratégie de coalescence cross-source et de production d'observations multiples ; 9. stratégie HTTP polling live bornée depuis le démarrage du run, sans campagne historique ; 10. threat model : duplicate storms, source skew, provider disagreement, hydration fanout, reconnect storms, polling drift, slow Store, stop/fault concurrent ; 11. inventaire des smokes réellement accessibles avec les ressources opérateur ; 12. graphes Cargo/features cibles et éventuels changements Config strictement nécessaires ; 13. sizing de chaque tranche sous le budget 15–20 minutes ; 14. décision explicite : maintien de `0.3.13` ou rescission avant codage ; 15. création du plan et de la validation de release. Documents attendus : ```text docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md ``` Critère de sortie : chaque source retenue et la convergence doivent avoir un contrat d'entrée/sortie, des bornes, une stratégie de preuve et un propriétaire de retry/reconnect clairement identifiés avant `pre.002`. ## 10. Prévision souple initiale des prereleases Cette prévision est un point de départ à recalibrer par `pre.001`. ### `pre.001` — audit / brainstorming / sizing Base stable, audit WS/Helius/HTTP courant, matrice de matériau/hydration, architecture multi-source, threat model, smokes, graphes, plan/validation et décision de maintien/rescission. ### `pre.002` — contrat runtime resources multi-source Généraliser la composition caller-owned vers plusieurs sources bornées, avec identité interne/source lifecycle minimale, sans brancher encore toutes les voies live. ### `pre.003` — WS standard `logsSubscribe` + hydration Brancher la discovery signature/logs via la façade Transport existante et fermer `logs -> getTransaction observed -> Common RAW` sans recopier l'actor WS. ### `pre.004` — WS standard `blockSubscribe` Brancher les blocs full/base64 et utiliser RAW-direct uniquement pour les versions réellement qualifiées ; hydration/fault explicite ailleurs. ### `pre.005` — Helius `transactionSubscribe` Réutiliser la surface Transport Helius existante, appliquer l'hydration nécessaire et les profils Config réellement justifiés sans SDK ni secret dans le Worker. ### `pre.006` — HTTP live block polling Suivre le réseau depuis une borne de run explicite, récupérer les blocs observed et projeter leurs transactions vers le pipeline central avec cadence/bornes/stop déterministes. ### `pre.007` — supervision/source inventory multi-source Faire coexister plusieurs sources dans le supervisor, avec ownership clair des tasks, stop/fault et source health sans modifier la sémantique Worker globale arbitrairement. ### `pre.008` — convergence et observations multiples Fermer la déduplication/coalescence cross-source et la conservation de provenances/observations distinctes pour une même identité canonique. ### `pre.009` — conflits, backpressure et fairness Durcir disagreement cross-source, content conflict, saturation globale/par source, fairness minimale et absence de fanout d'hydration non borné. ### `pre.010` — snapshots/health multi-source Projeter uniquement les dimensions source-neutral réellement utiles : activité, source failures, backpressure et état agrégé sans exposer provider material. ### `pre.011` — races/shutdown hardening Stop/fault pendant connect/resubscribe/hydration/polling/persistence, sources lentes, tasks orphelines, counters et ordre terminal. ### `pre.012` — completeness/security cross-layer Canaris Transport -> Worker -> Common RAW -> Store, inventaires API/dépendances, redaction, Legacy/V0/V1 et non-régression Yellowstone. ### `pre.013` — gate technique/live Workspace complet, Clippy strict, suites ciblées, graphes/duplicates et smokes réellement accessibles. Aucun nouveau scope. ### `pre.014` — réconciliation documentaire README/USAGE, plan, validation et architectures/références réellement affectées. Pas de CHANGELOG/ROADMAP/prompt suivant. ### `pre.015` — préparation publication Prompt `0.3.14`, CHANGELOG, ROADMAP et fichiers mécaniques uniquement. ### `rel.001` Publication stable mécanique après gate validé. Le forecast peut être allongé par des fixes/tranches dédiées ; il ne doit jamais être compressé en mélangeant les responsabilités de fermeture. ## 11. Versionnement, deltas, commits et tags Règles obligatoires : ```text livraison prerelease : 0.3.13-pre.NNN Cargo : 0.3.13-pre.N fix : 0.3.13-pre.N.fix.M delta : deltas/0.3.13/pre.NNN.md ou pre.NNN-fix.NNN.md commit : v0.3.13-pre.NNN[-fix.NNN] tag prerelease : aucun tag stable final : v0.3.13 seulement après rel.001 validée ``` Toute prerelease non-fix synchronise `workspace.package.version`, même documentaire. Une correction strictement doc-only portée par un fix ne bump pas la version Cargo racine. Tout fichier modifié incrémente son header de version selon les règles du dépôt. Les archives d'échange restent des deltas minimaux. ## 12. Procédure d'application et validation opérateur Après application d'un delta technique : ```bash cargo fmt --all -- --check python3 scripts/audit_rust_workspace_rules.py python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas cargo check --workspace cargo clippy --workspace --all-targets --all-features -- -D warnings ``` Puis exécuter les tests ciblés de la tranche. Si un gate devient rouge, produire un fix strictement rattaché à la responsabilité fautive avant d'avancer. Aucune commande non exécutée ne peut être déclarée PASS. ## 13. Validations Rust / Transport / Config / live / graphes pertinentes Selon les couches modifiées : ```bash cargo test -p ksp-worker-raw-transaction-ingest-lib cargo test -p ksp-onchain-transport-lib cargo test -p ksp-raw-transaction-lib cargo test -p ksp-store-api cargo test -p ksp-store-lib --no-default-features ``` Si Config/profils Helius sont modifiés : ```bash cargo test -p ksp-config-lib ``` Graphes à auditer uniquement si le graphe de dépendances/features change, ou à la fermeture technique : ```bash cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features cargo tree --duplicates ``` À la fermeture technique : ```bash cargo test --workspace --all-targets --all-features ``` Smokes live possibles, uniquement après audit `pre.001` et lorsqu'ils sont réellement configurés : ```text Solana HTTP Devnet Solana WS Devnet Helius transactionSubscribe si credential/tier disponible provider WS/blockSubscribe réellement accessible HTTP polling live sur réseau de test approprié ``` Un smoke indisponible est `NON EXÉCUTÉ`, pas PASS. Aucun secret n'est écrit dans une commande persistée, un log, un delta ou un fichier source. ## 14. Critères de clôture de `0.3.13` La release peut se fermer lorsque : ```text base Yellowstone 0.3.12 non régressée runtime resources supporte les sources retenues de manière bornée logsSubscribe + hydration productif blockSubscribe productif sur les versions réellement qualifiées Helius transactionSubscribe productif si retenu/accessible par pre.001 HTTP live polling productif et run-local sources simultanées convergent vers la même admission/persistence observations multiples conservées sans dupliquer l'identité RawTransaction content conflict reste explicite coalescence/hydration fanout/backpressure bornés aucun second actor/client Transport dans le Worker aucun Worker -> Config/Job/backend physique retry/reconnect restent possédés par la couche appropriée shutdown/fault multi-source sans tâches orphelines diagnostics redacted fixtures/canaris cross-layer verts smokes accessibles exécutés ou impossibilité qualifiée gates workspace/clippy/tests/trees verts documentation réconciliée prompt 0.3.14 produit dans la dernière prerelease ``` ## 15. Release suivante envisagée `0.3.14` doit reprendre uniquement après publication stable de `0.3.13` et fermer le **gap repair/hardening multi-source** : ```text replay natif lorsqu'il est réellement adressable source redondante comme preuve/couverture de gap scan HTTP blocs pour réparation hydration des références manquantes unresolved gaps explicitement observables politiques degraded/unhealthy/faulted shutdown pendant repair smokes provider accessibles EARLY uniquement si réellement prouvé et encore justifié ``` `0.3.14` ne doit toujours pas transformer le Worker en moteur de campagne historique paramétrée ; le Backfill reste indépendant. ## 16. Instruction d'ouverture Au début de la prochaine session : 1. vérifier que la base correspond exactement au tag stable `v0.3.12` et que `deltas/0.3.12/rel.001.md` est présent ; 2. lire les règles, le handoff `0.3.12`, l'architecture RAW acquisition et les sources Worker/Transport/Common/Store/Config avant toute modification ; 3. réauditer les surfaces Solana WS, Helius et HTTP actuelles ainsi que les tiers/versions réellement concernés ; 4. produire `0.3.13-pre.001` avec matrice source/material/hydration, architecture multi-source, threat model, sizing, plan `034` et validation `030` ; 5. **ne pas généraliser runtime resources, ne pas brancher `logsSubscribe`/`blockSubscribe`/Helius, ne pas ajouter de polling et ne pas modifier Config avant fermeture de ce gate** ; 6. rescinder `0.3.13` immédiatement si le périmètre réel n'est pas clôturable dans une seule session.