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

v0.3.15-pre.017

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-19 08:36:52 +02:00
parent 5f19786ce9
commit cd5c79c253
15 changed files with 282 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 73 -->
<!-- version: 74 -->
# Documentation KSP
@@ -67,7 +67,14 @@ docs/
│ ├── 027-V0_3_6_JOB_API_BACKFILL_PLAN.md
│ ├── 028-V0_3_7_BACKFILL_DESK_PLAN.md
│ ├── 029-V0_3_8_STORE_DESK_PLAN.md
│ └── 030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
│ ├── 030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
│ ├── 031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
│ ├── 032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md
│ ├── 033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
│ ├── 034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
│ ├── 035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md
│ ├── 036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md
│ └── 037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md
├── validation/
│ ├── 000-README.md
│ ├── 001-V0_1_4_CONFIG_DESKTOP.md
@@ -95,7 +102,13 @@ docs/
│ ├── 023-V0_3_6_JOB_API_BACKFILL.md
│ ├── 024-V0_3_7_BACKFILL_DESK.md
│ ├── 025-V0_3_8_STORE_DESK.md
│ └── 026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
│ ├── 026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
│ ├── 027-V0_3_10_RAW_TRANSACTION_INGEST.md
│ ├── 028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md
│ ├── 029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
│ ├── 030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
│ ├── 031-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING.md
│ └── 032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md
└── rules/
├── FILE_CONTRACTS.md
├── PROMPT_STRUCTURE.md
@@ -120,6 +133,8 @@ Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/
La candidate `0.3.9 — Worker API générique + audit RAW Transaction` est réconciliée dans [`plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md`](plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md) avec [`validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md`](validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md). `ksp-worker-api` reste Core-only et runtime-neutral pour les services continus ; l'architecture RAW place Store/`RawTransaction` au centre et sépare strictement le Job Backfill historique paramétré du futur Worker Ingest continu start/stop. [`../crates/ksp-worker-api/README.md`](../crates/ksp-worker-api/README.md), [`../crates/ksp-worker-api/USAGE.md`](../crates/ksp-worker-api/USAGE.md), [`architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) et [`architecture/011-RAW_TRANSACTION_ACQUISITION.md`](architecture/011-RAW_TRANSACTION_ACQUISITION.md) constituent les références durables avant la lane de publication.
Les candidates `0.3.10` à `0.3.15` prolongent cette trajectoire RAW dans [`plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md`](plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md), [`plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md`](plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md), [`plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md`](plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md), [`plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md`](plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md), [`plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md`](plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md) et [`plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md`](plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md), avec leurs matrices [`validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md`](validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md) à [`validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md`](validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md). Cette séquence matérialise le Common RAW partagé, la fondation Worker, Yellowstone live, cinq familles multi-source, la continuité/gap repair puis le Desk multi-route ; `0.3.15` ferme en plus les anomalies Mainnet observées de convergence `logMessages`, backpressure Yellowstone soutenue et shutdown post-half-close. Le handoff [`plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md`](plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md) réserve explicitement à `0.3.16` les variantes RAW durables, la résolution des conflits, les retries Store/Transport et les vues correspondantes de Store Desk ; `0.3.17` et `0.3.18` portent ensuite le Backfill multi-route et son Desk adapté.
## Spécifications de formats
Les formats durables, interopérables et destinés à être réimplémentables hors de KSP sont indexés depuis [`formats/000-README.md`](formats/000-README.md). [`.kspwallet` V1](formats/KSPWALLET_V1.md) reste le format JSON historique stable publié par `0.2.5`. [`.kspwallet` V2](formats/KSPWALLET_V2.md), publié stable avec `0.2.6`, ajoute le wire binaire canonique KSP, le runtime multi-version/default V2 et la migration explicite OWNER-authentifiée V1 -> V2.

84
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 42 -->
<!-- version: 43 -->
# Inventaire initial des composants KSP
@@ -18,46 +18,46 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
## Inventaire synthétique
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|-----------------------------------------|-------------|--------------|---------------------------------|--------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire |
| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite |
| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability |
| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
| Store API | `ksp-store-api` | API | Stable | `0.3.1`, extension `0.3.16` | RAW transaction/account, observations ; variantes/conflits/résolutions ajoutés sans backend leak |
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | façade backend-neutral ; convergence, retry et résolution RAW partagés entre producteurs |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | backend référence ; variantes conflictuelles et historique de résolution atomiques en `0.3.16` |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.17` | première verticale HTTP puis extension multi-route/historique sur convergence Store partagée |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.18` | contrôle du backfill RAW ; sélection/supervision multi-route adaptée au Job `0.3.17` |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8`, extension `0.3.16` | inspection RAW + vues conflits/variantes/historique et résolution manuelle réversible |
| RAW transaction common | `ksp-raw-transaction-lib` | lib | Implémenté | `0.3.10` | canonicalisation/wire RAW Transaction v1 source-neutral partagé entre producteurs |
| Worker lifecycle | `ksp-worker-api` | API | Implémenté | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`–`0.3.16` | live multi-route ; `0.3.16` sépare défaut transport et conflits RAW locaux durablement gérés |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.15` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML |
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|-----------------------------------------|-------------|--------------|----------------------------------|------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire |
| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite |
| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability |
| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
| Store API | `ksp-store-api` | API | Stable | `0.3.1`, extension `0.3.16` | RAW transaction/account, observations ; variantes/conflits/résolutions ajoutés sans backend leak |
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | façade backend-neutral ; convergence, retry et résolution RAW partagés entre producteurs |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | backend référence ; variantes conflictuelles et historique de résolution atomiques en `0.3.16` |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.17` | première verticale HTTP puis extension multi-route/historique sur convergence Store partagée |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.18` | contrôle du backfill RAW ; sélection/supervision multi-route adaptée au Job `0.3.17` |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8`, extension `0.3.16` | inspection RAW + vues conflits/variantes/historique et résolution manuelle réversible |
| RAW transaction common | `ksp-raw-transaction-lib` | lib | Implémenté | `0.3.10` | canonicalisation/wire RAW Transaction v1 source-neutral partagé entre producteurs |
| Worker lifecycle | `ksp-worker-api` | API | Implémenté | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`–`0.3.15`, ext. `0.3.16` | live cinq familles, continuité/repair et backpressure bornée ; conflits durables étendus en `0.3.16` |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Implémenté | `0.3.15` | composition réseau-centrique et supervision simultanée de plusieurs routes live |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML |
## Contrats séparés retenus
@@ -90,7 +90,7 @@ La Config standard Transport appartient à `ksp-config-lib`, qui adapte vers les
Les WebSockets supportent plusieurs sessions pour un même endpoint URL, mais un pool/scheduler automatique n'est créé qu'après besoin démontré.
Les providers Yellowstone spécifiques restent des extensions futures ; le contrat standard est provider-neutral.
Le contrat Yellowstone standard/provider-neutral est implémenté. PublicNode et OrbitFlare restent des compositions Config/credentials autour de ce même contrat ; toute extension provider-specific future doit conserver cette frontière au lieu de créer un second moteur Yellowstone.
`ksp-offchain-transport-lib` ouvre en `0.2.11` une première surface SOL/USD multi-provider. La crate possède les adapters `reqwest`, les capacités/rate limits, l’état runtime et le refresh individuel/multiple. Elle ne dépend pas de Config et n’expose aucun wire provider comme contrat de l’application. `ksp-app-solprices-desk`, prévu en `0.2.12`, consomme exclusivement cette surface générique et reste une HID sans connaissance provider.

8
docs/architecture/005-DEPENDENCY_GRAPH.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 30 -->
<!-- version: 31 -->
# Graphe de dépendances KSP
@@ -433,9 +433,9 @@ ksp-worker-control-lib # composant retenu, non matérialis
-> ksp-core-lib
```
`ksp-worker-api` est ouvert en `0.3.9` comme contrat générique de services continus et ne connaît ni Solana, ni Transport, ni Store, ni Tauri. `ksp-worker-raw-transaction-ingest-lib` est son premier consumer concret : sa fondation `0.3.11` possède admission/persistence/snapshots/shutdown ; `0.3.12` ouvre la première verticale Yellowstone + hydration HTTP ; `0.3.13` matérialise la composition live multi-source ; `0.3.14` ferme la continuité run-local par gaps bornés, preuves de coverage, repair conservatif, health gap-aware et shutdown/fairness durcis. Config et le backend physique restent hors du Worker.
`ksp-worker-api` est ouvert en `0.3.9` comme contrat générique de services continus et ne connaît ni Solana, ni Transport, ni Store, ni Tauri. `ksp-worker-raw-transaction-ingest-lib` est son premier consumer concret : sa fondation `0.3.11` possède admission/persistence/snapshots/shutdown ; `0.3.12` ouvre la première verticale Yellowstone + hydration HTTP ; `0.3.13` matérialise la composition live multi-source ; `0.3.14` ferme la continuité run-local par gaps bornés, preuves de coverage, repair conservatif, health gap-aware et shutdown/fairness durcis ; `0.3.15` ferme le chemin d'exploitation Desk et les défauts Mainnet observés de convergence tronquée, saturation Yellowstone et fermeture coopérative. Config et le backend physique restent hors du Worker.
La verticale actuelle n'est ni « un worker WebSocket » ni un moteur historique : `RawTransactionIngestRuntimeResources` contient de `1` à `32` sources logiques validées d'un même réseau parmi cinq familles — Yellowstone, Standard WS `logsSubscribe`, Standard WS `blockSubscribe`, Helius `transactionSubscribe` et HTTP live block polling. Yellowstone, Standard Logs et Helius convergent vers une registry globale d'hydration HTTP `getTransaction`; Standard Block et HTTP Block Polling qualifient directement le wire Base64 Legacy/V0/V1 vers Common RAW. Toutes les acquisitions rejoignent la même admission/persistence, la convergence canonique `(network, signature)` et des observations distinctes par provenance. Reconnect, `from_slot`, replay natif et retries réseau restent propriétaires de Transport. Le Worker observe leurs preuves sûres, maintient processing/continuity frontiers distinctes, réconcilie uniquement des gaps du run courant avec coverage explicite et mécanismes bornés, et n'appelle jamais le Job Backfill. Une source perdue ne peut rester absente que si sa perte passée est réconciliée et si les sources restantes prouvent encore tout le `TargetCoverage` futur.
La verticale actuelle n'est ni « un worker WebSocket » ni un moteur historique : `RawTransactionIngestRuntimeResources` contient de `1` à `32` sources logiques validées d'un même réseau parmi cinq familles — Yellowstone, Standard WS `logsSubscribe`, Standard WS `blockSubscribe`, Helius `transactionSubscribe` et HTTP live block polling. Les signaux Yellowstone Transaction/TransactionStatus, Standard Logs et Helius convergent vers une registry globale d'hydration HTTP `getTransaction`. Un mode Yellowstone Block pur utilise le bloc gRPC comme trigger de slot puis exécute un `getBlock` HTTP borné/concurrent ; Standard Block et HTTP Block Polling qualifient directement le wire Base64 Legacy/V0/V1 vers Common RAW. Toutes les acquisitions rejoignent la même admission/persistence, la convergence canonique `(network, signature)` et des observations distinctes par provenance. Reconnect, `from_slot`, replay natif, retry réseau et backpressure du stream restent propriétaires de Transport. Le Worker observe leurs preuves sûres, maintient processing/continuity frontiers distinctes, réconcilie uniquement des gaps du run courant avec coverage explicite et mécanismes bornés, et n'appelle jamais le Job Backfill. Une source perdue ne peut rester absente que si sa perte passée est réconciliée et si les sources restantes prouvent encore tout le `TargetCoverage` futur.
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> STRUCTURAL borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODED/DOMAIN sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
@@ -493,7 +493,7 @@ ksp-app-raw-transaction-ingest-desk
-> ksp-store-lib
```
La Desk sélectionne et supervise les stratégies d'acquisition exposées par le worker et par la composition Config/Transport. Elle peut activer plusieurs sources lorsqu'elles sont compatibles, mais ne reconstruit ni discovery, ni hydration, ni déduplication, ni provenance dans Tauri/TypeScript. Les endpoints, credentials, capacités provider et handles Transport/Store restent Rust-owned.
La Desk sélectionne et supervise les stratégies d'acquisition exposées par le Worker et par la composition Config/Transport. Plusieurs routes d'un même réseau peuvent tourner simultanément avec des Workers indépendants sur un Store partagé ; le dernier terminal ferme ce Store. Le frontend ne reconstruit ni discovery, ni hydration, ni déduplication, ni provenance et ne reçoit que des projections latest-value sûres. Les endpoints, credentials, capacités provider et handles Transport/Store restent Rust-owned.
### Store Desk

33
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 21 -->
<!-- version: 22 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -451,7 +451,7 @@ Les événements utiles comprennent notamment :
### RAW backfill
État actuel avant extraction de la normalisation commune :
État matérialisé après extraction de la normalisation commune :
```text
ksp-job-backfill-lib
@@ -459,24 +459,17 @@ ksp-job-backfill-lib
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> ksp-raw-transaction-lib
-> ksp-store-lib # façade Store ; default-features=false côté Job
-> futures-util/tokio # runtime privé de Backfill
-> serde_json/sha2 # RAW v1 canonique + digest actuellement locaux
-> serde_json/sha2 # discovery/checkpoint/observation propres au Job
```
Cible après matérialisation de la lower-layer commune :
```text
ksp-job-backfill-lib
-> ksp-raw-transaction-lib
-> ksp-store-lib
```
Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle.
Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle. La canonicalisation transactionnelle partagée appartient désormais à `ksp-raw-transaction-lib`; `0.3.17` étendra les stratégies historiques sans déplacer ce rôle.
### RAW worker
Fondation source-neutral matérialisée :
Fondation et acquisition live matérialisées :
```text
ksp-worker-raw-transaction-ingest-lib
@@ -485,24 +478,18 @@ ksp-worker-raw-transaction-ingest-lib
-> ksp-raw-transaction-lib
-> ksp-store-lib # façade Store ; default-features=false ; aucun backend physique direct
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> sha2 / tokio # observation key + runtime privé
```
Extension live ultérieure :
```text
ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib # seulement lorsque les adapters sources productifs sont matérialisés
-> ksp-interface-lib # seulement si un fait passif partagé aide réellement la composition live
composition supérieure / future Desk
ksp-app-raw-transaction-ingest-desk
-> ksp-config-lib
-> ksp-worker-api
-> ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
```
Le Worker conserve seul son runtime continu, ses sources actives lorsqu'elles existent, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill. La fondation n'expose aucun ingress public : les sources internes futures alimentent la queue bornée et subissent sa backpressure.
Le Worker conserve seul son runtime continu, ses sources actives, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill et n'expose aucun ingress public : ses sources internes validées alimentent les queues bornées et subissent leur backpressure. Le Desk possède uniquement la composition et la supervision ; plusieurs routes d'un même réseau peuvent avoir des Workers indépendants sur le Store partagé sans déplacer acquisition ou persistance vers Tauri/TypeScript.
Les événements Interface peuvent servir de signal provider-neutral à la composition live, mais ne constituent jamais le backlog durable. Après crash ou perte d'un événement, la reprise s'appuie sur Store et sur les primitives de replay/hydratation appropriées.

22
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 17 -->
<!-- version: 18 -->
# Acquisition et alimentation `RawTransaction`
@@ -833,6 +833,11 @@ coverage exacte/superset conservative avec epochs prouvés
repair borné réutilisant Transport/Common RAW/admission/Store existants
source-loss continuation uniquement sous TargetCoverage prouvée
snapshots gap/repair source-neutral et health gap-aware
Desk réseau-centrique multi-route avec Store partagé et Workers indépendants
Yellowstone Block Mainnet : trigger gRPC + HTTP getBlock Full/Base64 borné/concurrent
backpressure Yellowstone soutenue propagée au stream gRPC au lieu d'un overflow local
Stop Yellowstone post-half-close : status distant tardif classé Closed, status actif toujours fautif/reconnectable
compatibilité étroite : canonique complet + incoming logMessages avec marqueur exact Log truncated
```
Reste hors de cette verticale et nécessite une tranche dédiée :
@@ -840,7 +845,9 @@ Reste hors de cette verticale et nécessite une tranche dédiée :
```text
sources EARLY / pre-execution
campagne historique multi-source ou caller-paramétrable
Worker multi-source -> Store live E2E avec environnement complet provisionné
variantes RAW durables et résolution générale des conflits
promotion canonique d'une représentation moins complète vers une plus complète
retry Store et reconnexion Transport configurables au niveau prévu par 0.3.16
```
### 14.3 Gaps Transport Worker
@@ -869,6 +876,12 @@ settings techniques nécessaires
Elle peut activer plusieurs providers/endpoints simultanément. Les secrets restent Config-owned, avec réutilisation unique de `KSP_SECRET_HELIUS_API_KEY` pour les surfaces Helius concernées.
### 14.4.1 Politique de convergence effectivement livrée en `0.3.15`
La règle générale reste fail-closed : une divergence canonique non reconnue produit `content_conflict`; le Worker ne choisit ni majorité ni provider préféré. Une seule exception de qualité a été démontrée et livrée avant la généralisation `0.3.16` : si le RAW déjà stocké est complet, que l'entrant possède la même référence/slot/block time/format, la même transaction/version/index et le même `meta` hors `logMessages`, que le canonique ne contient aucun marqueur exact `Log truncated` et que l'entrant en contient exactement un après un préfixe identique, l'entrant est traité comme observation compatible moins complète. Le canonique n'est pas réécrit et aucun `content_conflict` n'est produit.
Le sens inverse reste volontairement non résolu en `0.3.15` : un canonique tronqué suivi d'une représentation complète n'est pas promu automatiquement. Deux contenus complets divergents, un préfixe incompatible, une différence hors `logMessages` ou toute relation de troncature non prouvée restent des conflits. Cette asymétrie est précisément le point d'entrée du modèle de variantes/promotion/résolution de `0.3.16`.
## 14.5 Handoff `0.3.16` : résilience RAW et conflits durables
`0.3.16` doit déplacer la résolution des divergences RAW dans le contrat Store partagé, afin que Worker live et futurs Jobs historiques convergent avec la même politique. Une divergence de contenu n'est plus assimilée automatiquement à une panne d'acquisition.
@@ -923,7 +936,10 @@ Ordre conseillé :
0.3.13 P0 : WS logs + hydration, blockSubscribe, Helius transactionSubscribe, HTTP live polling
0.3.13 P1 : multi-source convergence, dedup, provenance, content conflict, backpressure/fairness
0.3.13 P2 : health source-neutral, shutdown/races, completeness/security et gate live keyless
0.3.14 : trajectoire suivante définie par son prompt dédié ; ne pas réintroduire implicitement un scope reporté
0.3.14 P0 : gaps run-local, coverage prouvée, repair borné, source-loss et shutdown/fairness cross-layer
0.3.15 P0 : Raw Transaction Ingest Desk multi-route + stabilité Mainnet Yellowstone/getBlock/polling
0.3.15 P1 : diagnostic/convergence logMessages tronqués + backpressure gRPC soutenue + Stop post-half-close
0.3.16 P0 : variantes/conflits RAW durables, promotions/résolutions, retries et Store Desk conflicts
0.3.17 P0 : block scan historique
0.3.17 P0 : replay Yellowstone borné
0.3.17 P1 : provider history/archive

8
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 101 -->
<!-- version: 102 -->
# Séquence des releases fonctionnelles KSP
@@ -585,14 +585,14 @@ La séquence effective a évolué par sizing et validation réels. La référenc
0.3.11 fondation source-neutral ksp-worker-raw-transaction-ingest-lib
0.3.12 première verticale live Yellowstone + hydration/replay continuity
0.3.13 cinq familles live + convergence multi-source/fairness/health/hardening
0.3.14 tranche suivante de la trajectoire RAW selon prompt dédié
0.3.15 ksp-app-raw-transaction-ingest-desk
0.3.14 gaps run-local + coverage/repair + shutdown/fairness/completeness cross-layer
0.3.15 ksp-app-raw-transaction-ingest-desk + composition multi-route + fermeture Mainnet
0.3.16 RAW resilience / conflict variants / Store Desk conflict management
0.3.17 ksp-job-backfill-lib multi-route / multi-stratégie
0.3.18 ksp-app-backfill-desk adapté au Backfill multi-route
```
Cette série ferme la couche RAW et ses outils d'exploitation avant l'ouverture fonctionnelle de STRUCTURAL. Le Worker live RAW reste distinct des jobs historiques et ne constitue pas encore une transformation RAW -> STRUCTURAL.
Cette série ferme la couche RAW et ses outils d'exploitation avant l'ouverture fonctionnelle de STRUCTURAL. `0.3.15` ajoute le Desk réseau-centrique multi-route, stabilise la route Mainnet Yellowstone Block + HTTP `getBlock`, conserve la backpressure bornée jusqu'au stream gRPC et accepte uniquement la divergence de `logMessages` explicitement tronquée déjà démontrée lorsque le canonique complet existe. La généralisation des variantes/résolutions reste réservée à `0.3.16`. Le Worker live RAW reste distinct des jobs historiques et ne constitue pas encore une transformation RAW -> STRUCTURAL.
Aucune release RAW ne crée par anticipation la persistence DECODED/DOMAIN.

16
docs/plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md -->
<!-- version: 25 -->
<!-- version: 26 -->
# Plan v0.3.15 — Raw Transaction Ingest Desk
@@ -863,6 +863,8 @@ La tranche ne normalise ni n'ignore `logMessages`. Elle ajoute un diagnostic de
Le live doit comparer les fingerprints au slot du conflit. Fingerprints différents au même slot indiquent deux vues de bloc/fork différentes au commitment observé ; fingerprint identique avec `logMessages` divergents indique une divergence de réponse/recording RPC entre providers pour le même bloc. Ce diagnostic précède toute décision de canonicalisation durable.
`pre.014-fix.001` ferme ensuite uniquement le cas démontré : canonique complet déjà présent + entrant identique hors `logMessages` avec un marqueur exact `Log truncated` après préfixe identique. L'observation entrante est conservée, le canonique n'est pas réécrit et le Worker ne fault pas. La promotion inverse et les variantes conflictuelles générales restent réservées à `0.3.16`.
Les canaris de clôture continuent de vérifier dependency firewalls, API publique, redaction et absence de seconde pipeline ou d'orchestration Backfill.
Budget cible : une tranche de convergence/completeness cross-layer, sans modification de la politique fail-closed.
@@ -881,17 +883,17 @@ Budget consommé : correction Transport/acquisition sans croissance d'API publiq
### `pre.016` — gate technique/live final
**État : ouvert.** Aucun nouveau comportement métier ou runtime n'est introduit. La preuve live de `pre.015-fix.001` est la baseline autoritaire puisque `pre.016` ne modifie ni source, ni test fonctionnel, ni Config, ni manifest de crate, ni frontend.
**État : fermé / PASS opérateur.** Aucun nouveau comportement métier ou runtime n'a été introduit. La preuve live de `pre.015-fix.001` reste la baseline autoritaire puisque `pre.016` n'a modifié ni source, ni test fonctionnel, ni Config, ni manifest de crate, ni frontend.
Le gate final rejoue : format, audits, `cargo check`, Clippy strict, suites ciblées Store/Transport/Worker/Desk, workspace all-targets/all-features, graphes Cargo des trois composants critiques, duplicates et `cargo tauri build` de la Desk. Les smokes live déjà fournis restent valides tant qu'aucun fichier runtime n'est modifié dans cette tranche.
Le gate final a rejoué avec succès : format, audits, `cargo check`, Clippy strict, suites ciblées Store/Transport/Worker/Desk et workspace all-targets/all-features. Les graphes Cargo des trois composants critiques et `cargo tree --duplicates` ont été rejoués, puis `cargo tauri build` a produit les trois bundles Linux `.deb`, `.rpm` et `.AppImage` en version `0.3.15-pre.16`. Aucun `test result: FAILED`, `error[E...]`, `could not compile` ou panic n'apparaît dans le retour opérateur fourni.
Tout défaut découvert ici ouvre `pre.016-fix.NNN`. Toute anomalie appartenant à un couloir antérieur ouvre une nouvelle prerelease dédiée conformément à `VER-LIFECYCLE-010`, puis les couloirs de clôture sont rejoués.
Budget cible : une tranche technique de clôture uniquement.
Budget consommé : une tranche technique de clôture uniquement.
### `pre.017` — réconciliation documentaire finale
Réconcilier plan, validation, README/USAGE et documents durables réellement affectés. Ne pas modifier CHANGELOG, ROADMAP ni le prompt suivant.
**État : matérialisé dans cette tranche.** Le plan, la validation, les README/USAGE Worker/Desk et les documents architecturaux durables sont réconciliés sur l'état effectivement livré : cinq familles live, Yellowstone Block + HTTP `getBlock`, multi-route Desk, convergence `logMessages` tronqués étroite, backpressure gRPC soutenue et Stop post-half-close. Aucun runtime, test, Config, schema, migration ou dépendance n'est modifié.
Conformément à `VER-LIFECYCLE-006`, `CHANGELOG.md`, `ROADMAP.md` et le prompt `0.3.16` restent strictement réservés à `pre.018`.
Budget cible : une tranche documentaire.

45
docs/validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md -->
<!-- version: 34 -->
<!-- version: 35 -->
# Validation v0.3.15 — Raw Transaction Ingest Desk
@@ -1128,3 +1128,46 @@ cargo tree --duplicates
```
Aucun nouveau live n'est requis par cette archive tant que ce scope reste strictement mécanique/documentaire : la base immédiatement précédente possède déjà le run long requis et `pre.016` ne change aucun fichier consommé par le runtime. Une modification runtime découverte nécessaire pendant le gate invaliderait cette non-claim et devrait être portée par un fix ou une nouvelle prerelease conforme au lifecycle.
### `pre.016` — clôture du gate opérateur
Le rejeu opérateur de `0.3.15-pre.016` ferme le gate technique final. Les audits annoncent :
```text
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (318 tables, 229 files)
```
`cargo check --workspace` et Clippy strict terminent sans erreur. Les suites ciblées confirment notamment Store PostgreSQL `75/75` unitaires, Transport `396/396` unitaires et `49/49` release completeness, Worker `161/161` unitaires avec ses suites cross-layer/dependency/hardening/public/release, et Raw Transaction Ingest Desk `50/50` unitaires avec ses suites desktop/dependency/public/release. Le rejeu `cargo test --workspace --all-targets --all-features` ne contient aucun `test result: FAILED`, aucune erreur de compilation Rust et aucun panic dans le log fourni.
Les graphes demandés ont été produits pour Transport, Worker et Raw Transaction Ingest Desk, ainsi que `cargo tree --duplicates`. Enfin, `cargo tauri build` termine le profil release et produit les trois bundles Linux :
```text
KSP Raw Transaction Ingest Desk_0.3.15-pre.16_amd64.deb
KSP Raw Transaction Ingest Desk-0.3.15-pre.16-1.x86_64.rpm
KSP Raw Transaction Ingest Desk_0.3.15-pre.16_amd64.AppImage
```
Aucun nouveau live n'était nécessaire : `pre.016` n'a modifié aucun artefact runtime et la preuve longue immédiatement précédente reste applicable.
### `pre.017` — réconciliation documentaire finale
Cette tranche réconcilie uniquement les documents durables et le numéro de prerelease workspace imposé par `VER-ID-009`. Elle ne modifie aucun fichier `src`, `tests`, `unit_tests`, frontend, Config, schema, migration, manifest de crate ou dépendance. Elle fixe notamment dans la documentation active :
```text
Yellowstone Block Mainnet -> trigger gRPC + HTTP getBlock Full/Base64
backpressure queue Yellowstone -> attente bornée/asynchrone vers le stream, pas d'overflow local
Stop Yellowstone -> status post-half-close coopératif ; status actif toujours fautif/reconnectable
canonique complet + incoming Log truncated compatible -> observation acceptée, canonique conservé
reverse promotion et variantes/résolutions générales -> 0.3.16
Raw Transaction Ingest Desk -> multi-route same-network, Workers indépendants, Store partagé
0.3.17 -> Backfill multi-route / multi-stratégie
0.3.18 -> Backfill Desk adapté
```
Non-claims : `pre.017` ne transforme pas encore un vrai `content_conflict` en quarantaine durable, ne promeut pas un canonique tronqué vers une version complète, n'ajoute aucune politique Store retry/Transport reconnect configurable de `0.3.16`, et ne modifie ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt suivant. Ces trois derniers artefacts appartiennent à `pre.018` conformément à `VER-LIFECYCLE-003` et `VER-LIFECYCLE-006`.
Gate documentaire attendu : audits Rust/Markdown, `cargo fmt --all -- --check` et `cargo check --workspace` suffisent à confirmer que le bump workspace `0.3.15-pre.17` et les documents restent cohérents avec la candidate déjà techniquement validée. Aucun nouveau live n'est requis tant que le différentiel reste strictement documentaire hors `Cargo.toml` racine.