diff --git a/CHANGELOG.md b/CHANGELOG.md index e1f3730..6a06bdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,22 @@ - + # Changelog KSP +## 0.3.12 — Yellowstone + hydration HTTP + continuité de run du Worker RawTransaction — 2026-09-09 + +`0.3.12` ouvre la première source réseau productive de `ksp-worker-raw-transaction-ingest-lib` sans remettre en cause la fondation source-neutral de `0.3.11`. Le Worker dépend désormais de la façade `ksp-onchain-transport-lib` mais reste sans Config, Job Backfill, backend Store physique, `reqwest`, `tonic` ou proto provider direct. `RawTransactionIngestRuntimeResources` reçoit une source Yellowstone caller-composed et un pool HTTP cohérent ; `start` conserve la fondation sans source, tandis que `start_with_runtime_resources` lance la verticale live supervisée. + +Les updates Yellowstone `Transaction`, `TransactionStatus` et les transactions incluses dans `Block` sont projetées vers des signaux source-neutral, coalescées de manière bornée par `(network, signature, commitment)`, hydratées via `getTransaction` observed puis converties par `ksp-raw-transaction-lib` avant admission/persistence Store. `BlockMeta` et `Slot` restent continuity-only. La provenance composite conserve les identités logiques sûres de la source et de la route d’hydration, sans URL, secret ni payload distant. Les gardes réseau/signature/slot/index/commitment empêchent les croisements de matériau avant admission. + +La release matérialise une processing frontier strictement run-local : le Worker distingue travail pending/settled, n’avance jamais au travers d’un pending plus ancien et compacte ses états sans revendiquer une preuve de complétude durable. Le reconnect/replay reste Transport-owned : `from_slot` et `SubscribeReplayInfo` ne sont pas pilotés par le Worker. Le Worker projette un état source-neutral `Active/Reconnecting/Closing/Closed/Failed`, compte reconnect/replay-attempt/continuity-gap et fault avec `source_failed` lorsqu’une hausse du gap Transport prouve que la rétention ne permet plus la reprise demandée. Aucun Backfill ou repair automatique n’est déclenché. + +Le hardening final ferme les duplicate storms, saturation/coalescence, Store lent/fautif, stop/fault pendant hydration/reconnect, overflow de compteurs, abandon des pending sans faux `settled`, abort/join des tâches privées et absence de retry HTTP possédé par le Worker. `pre.010` ajoute les canaris cross-layer Transport -> Worker -> Common RAW -> Store et verrouille les dependency firewalls, fixtures Legacy/V0, redaction et inventaires publics. + +Le gate déterministe `pre.011` passe rustfmt check, audits Rust/Markdown, `cargo check --workspace`, Clippy strict, `cargo test --workspace --all-targets --all-features`, les suites ciblées et les trois inspections Cargo demandées. Les smokes live keyless HTTP Devnet et WebSocket Devnet sont exécutés séparément et passent ; les smokes Yellowstone token-gated et le Worker end-to-end Yellowstone + HTTP + Store restent explicitement non exécutés faute de ressources fournies, sans faux PASS. `pre.012` réconcilie ensuite README/USAGE et les architectures concernées avec cette verticale réellement matérialisée. + +La suite reste découpée : `0.3.13` ajoute WS standard, Helius `transactionSubscribe`, HTTP live polling et la convergence multi-source ; `0.3.14` ferme le gap repair/hardening multi-source. `prompts/032-V0_3_13_START_PROMPT.md` ouvre `0.3.13` uniquement depuis le tag stable `v0.3.12` et impose un `pre.001` d’audit/sizing avant toute extension productive. + ## 0.3.11 — Fondation runtime source-neutral du Worker RawTransaction ingest — 2026-09-08 `0.3.11` introduit `ksp-worker-raw-transaction-ingest-lib` comme premier Worker concret KSP pour l’acquisition continue de `RawTransaction`, tout en fermant volontairement la release **sans source réseau productive**. La crate consomme `ksp-worker-api`, `ksp-raw-transaction-lib` et la seule façade `ksp-store-lib`; elle ne dépend ni de Config, ni d’un Job, ni d’un backend Store physique, ni encore de `ksp-onchain-transport-lib`. Son identité stable est `raw_transaction_ingest`, ses settings bornent la capacité d’admission, la concurrence de persistence et la deadline de drain, et son `start` utilise exclusivement le runtime Tokio actif fourni par le caller. diff --git a/Cargo.toml b/Cargo.toml index 3225680..1053134 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 537 +# version: 538 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api", "crates/ksp-worker-raw-transaction-ingest-lib"] [workspace.package] -version = "0.3.12-pre.12" +version = "0.3.12-pre.13" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 510e21e..e1ccadf 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -104,7 +104,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN - [X] `0.3.9` — `ksp-worker-api` stable comme API générique et volontairement courte pour services continus : identité/kind bornés, lifecycle explicite, health/activity sûrs, stop token partagé, séquence/snapshot latest-value et `WorkerSnapshotSource` object-safe, avec dépendance Core-only et sans runtime/start-stop universel, Solana, Transport, Store, Config ou Tauri. Après freeze Worker API, l'audit `RawTransaction` a été consolidé dans une synthèse Store-centrique exhaustive séparant possibilités/support/preuve et classant HTTP, WS standard/provider, Yellowstone gRPC, blocs/slots, discovery + hydration, replay de continuité, archives et sources EARLY. Le Job Backfill historique paramétré et le Worker Ingest live start/stop sont deux producteurs indépendants du même Store ; `mainnet` est désormais l'identité KSP canonique et `mainnet-beta` un alias legacy/externe. Le handoff retient `ksp-raw-transaction-lib` comme lower-layer commune de canonicalisation RAW v1 pour `0.3.10`, sans edge Job ↔ Worker. - [X] `0.3.10` — Lower-layer RAW Transaction commune stabilisée : `ksp-raw-transaction-lib` possède la canonicalisation RAW v1 source-neutral partagée, le Backfill est migré sans changement des golden bytes/hash, Transport expose `get_block_observed`, le wire Solana Legacy/V0/V1 est matérialisé et les canaris HTTP/WS standard/Helius/Yellowstone qualifient précisément les voies directes ou nécessitant hydration. La release se ferme sans runtime Worker concret ; celui-ci commence en `0.3.11` selon le redécoupage `0.3.11`–`0.3.14`. - [X] `0.3.11` — Fondation runtime de `ksp-worker-raw-transaction-ingest-lib` livrée : crate/dependency firewall, settings source-neutral, handle/start-stop, lifecycle, snapshots, supervisor, admission bornée, canonicalisation Common RAW, persistence/déduplication Store déterministe, backpressure et shutdown/fault hardening. La release se ferme volontairement sans source réseau productive ; Yellowstone + hydration HTTP commencent en `0.3.12`. -- [ ] `0.3.12` — Ajouter au Worker la voie **Yellowstone + hydration HTTP** : transactions/blocks/status, projection vers la common RAW, provenance sûre, `from_slot`, replay info, frontier de run et continuité propre au run, avec fixtures déterministes et smokes accessibles sans prétendre à un RAW-direct lorsque les métadonnées restent incomplètes. +- [X] `0.3.12` — Première source live productive du Worker livrée : Yellowstone `Transaction`/`TransactionStatus`/`Block` vers signaux source-neutral, coalescence bornée puis hydration HTTP `getTransaction` observed avant Common RAW/Store ; `BlockMeta`/`Slot` restent continuity-only. Processing frontier run-local, reconnect/from_slot/ReplayInfo Transport-owned, compteurs source-neutral et fault sur gap de rétention prouvé sans Backfill automatique. Hardening duplicate/backpressure/stop/fault et canaris cross-layer fermés ; gate workspace complet vert, smokes live HTTP Devnet + WebSocket Devnet verts, Yellowstone token-gated/Worker end-to-end laissés explicitement non exécutés. - [ ] `0.3.13` — Ajouter les voies **WS standard / Helius / HTTP live** et leur convergence multi-source : `logsSubscribe + getTransaction`, `blockSubscribe`, `transactionSubscribe + hydration`, polling blocs HTTP, observations multiples, content conflict explicite, coalescence et backpressure sans second actor Transport. - [ ] `0.3.14` — Fermer le Worker par le **gap repair/hardening multi-source** : replay natif, source redondante, scan HTTP blocs, hydration de réparation, unresolved gaps visibles, politiques degraded/unhealthy/faulted, shutdown pendant repair, smokes provider accessibles et adapter EARLY seulement si réellement prouvé. - [ ] `0.3.15` — Introduire `ksp-app-raw-transaction-ingest-desk`, Desk Tauri KSP spécialisée qui choisit et supervise une ou plusieurs sources/méthodes réellement admises par le Worker finalisé : lifecycle, health, rates, backpressure, reconnect/recovery, gap state et compteurs sûrs. La Desk ne réimplémente ni discovery, hydration, déduplication, reprise ni persistence. diff --git a/deltas/0.3.12/pre.013.md b/deltas/0.3.12/pre.013.md new file mode 100644 index 0000000..419a3e4 --- /dev/null +++ b/deltas/0.3.12/pre.013.md @@ -0,0 +1,174 @@ + + + +# Delta `0.3.12-pre.013` — préparation de publication + +## 1. Base requise + +```text +0.3.12-pre.012 +``` + +Le gate opérateur de `pre.012` est vert sur rustfmt check, audits Rust/Markdown, `cargo check --workspace`, Clippy strict, 66 tests Worker et toutes les suites Worker boundary/hardening/public API/completeness. + +Le gate technique `pre.011` précédent est déjà qualifié : workspace all-targets/all-features, suites ciblées, graphes Cargo/duplicates et smokes live keyless HTTP Devnet + WebSocket Devnet PASS. + +## 2. Objectif + +`pre.013` est la dernière prerelease de préparation de publication de `0.3.12`. + +Conformément à `VER-LIFECYCLE-003` et `PROMPT_STRUCTURE.md`, elle modifie fonctionnellement uniquement : + +```text +prompt de démarrage 0.3.13 +CHANGELOG.md +ROADMAP.md +``` + +Les seuls fichiers mécaniques supplémentaires sont : + +```text +Cargo.toml racine +delta pre.013 +``` + +Aucun README, USAGE, plan, validation, architecture, code, test, Config ou manifest de crate n'est rouvert. + +## 3. Version workspace + +```text +0.3.12-pre.12 +-> +0.3.12-pre.13 +``` + +## 4. Prompt suivant + +Le nouveau prompt : + +```text +prompts/032-V0_3_13_START_PROMPT.md +``` + +ouvre `0.3.13` exclusivement depuis le futur stable : + +```text +v0.3.12 +``` + +Sa mission est bornée à : + +```text +WS standard logsSubscribe + hydration +WS standard blockSubscribe +Helius transactionSubscribe + hydration +HTTP live block polling +convergence simultanée multi-source +observations multiples/coalescence/content conflict/backpressure +``` + +Le gap repair/hardening multi-source final reste explicitement `0.3.14`. + +Le `pre.001` du prompt interdit tout codage lourd avant : audit de la base stable, réaudit courant Solana/Helius, matrice de matériau/hydration, architecture runtime resources multi-source, threat model, smokes accessibles, graphes, sizing et création du plan `034` + validation `030`. + +## 5. CHANGELOG + +`CHANGELOG.md` reçoit l'entrée `0.3.12` synthétisant : + +```text +première source productive Yellowstone +hydration HTTP getTransaction observed +Common RAW + Store inchangés dans leurs rôles +processing frontier run-local +reconnect/from_slot/ReplayInfo Transport-owned +fault sur gap prouvé sans Backfill automatique +hardening duplicate/backpressure/shutdown +canaris cross-layer +workspace gate final PASS +smokes HTTP Devnet + WS Devnet PASS +smokes Yellowstone/Worker E2E non exécutés explicitement +handoff 0.3.13 / 0.3.14 +prompt 032 +``` + +## 6. ROADMAP + +L'entrée `0.3.12` passe de `[ ]` à `[X]` et décrit l'état réellement livré. Les entrées `0.3.13` et `0.3.14` restent ouvertes et conservent leur séparation : convergence multi-source d'abord, repair multi-source ensuite. + +## 7. Fichiers ajoutés + +```text +prompts/032-V0_3_13_START_PROMPT.md +deltas/0.3.12/pre.013.md +``` + +## 8. Fichiers modifiés + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +``` + +## 9. Fichiers supprimés + +```text +aucun +``` + +## 10. Surfaces explicitement inchangées + +```text +README.md +docs/** +crates/** +config/** +tests/** +``` + +Hormis le nouveau prompt sous `prompts/`, aucun prompt existant n'est modifié. + +## 11. Validations exécutées pendant l'assemblage + +Sur l'état exact destiné à l'archive : + +```text +General Rust rule audit: clean +Rust export completeness audit: 0 candidate(s) +KSP workspace Rust rule audit: clean +Markdown table audit: clean (340 table(s), 824 file(s)) + +diff exact : 3 fichiers modifiés + 2 ajoutés, 0 supprimé +headers/version workspace : PASS +prompt 032 : 16 sections normatives présentes +``` + +Les contrôles d'archive (`unzip -t`, archive safety et reproduction byte-à-byte sur `pre.012`) sont exécutés après construction du ZIP et doivent être verts avant livraison. + +L'environnement d'assemblage ne revendique aucun Cargo PASS qui n'y a pas réellement été exécuté. + +## 12. Gate opérateur minimum + +Comme aucun code/test/dépendance/feature n'est modifié : + +```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 +``` + +Un Clippy/test workspace supplémentaire peut être exécuté par l'opérateur, mais `pre.013` ne doit pas réinterpréter le gate technique `pre.011` déjà validé. + +## 13. Décisions prises + +- `0.3.12` est prêt pour une publication stable mécanique après validation de `pre.013` ; +- `0.3.13` ne commence qu'après `0.3.12-rel.001` et le tag stable `v0.3.12` ; +- le prompt suivant maintient Worker -> Config interdit et impose la composition caller-owned des ressources live ; +- aucune correction d'un couloir technique/documentaire antérieur n'est absorbée dans cette tranche de publication. + +## 14. Questions ouvertes + +```text +aucune question bloquante pour la préparation de publication 0.3.12 +``` diff --git a/prompts/032-V0_3_13_START_PROMPT.md b/prompts/032-V0_3_13_START_PROMPT.md new file mode 100644 index 0000000..bae9179 --- /dev/null +++ b/prompts/032-V0_3_13_START_PROMPT.md @@ -0,0 +1,638 @@ + + + +# 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 à maintenir/auditer : + +```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.