Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.12-pre.013

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-10 00:00:12 +02:00
parent 79e278064d
commit e7e8960fec
5 changed files with 831 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
CHANGELOG.md
View File

@@ -1,8 +1,22 @@
<!-- file: CHANGELOG.md -->
<!-- version: 31 -->
<!-- version: 32 -->
# 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.

4
Cargo.toml
View File

@@ -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"

4
ROADMAP.md
View File

@@ -1,5 +1,5 @@
<!-- file: ROADMAP.md -->
<!-- version: 109 -->
<!-- version: 110 -->
# 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.

174
deltas/0.3.12/pre.013.md Normal file
View File

@@ -0,0 +1,174 @@
<!-- file: deltas/0.3.12/pre.013.md -->
<!-- version: 1 -->
# 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
```

638
prompts/032-V0_3_13_START_PROMPT.md Normal file
View File

@@ -0,0 +1,638 @@
<!-- file: prompts/032-V0_3_13_START_PROMPT.md -->
<!-- version: 1 -->
# 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.