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

v0.3.10-pre.006-fix.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-07 23:56:48 +02:00
parent f7c57f21c5
commit 919b4ed46d
13 changed files with 319 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 34 -->
<!-- version: 35 -->
# Inventaire initial des composants KSP
@@ -41,12 +41,12 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4` | façade backend-neutral et conformance RAW 10/10 |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4` | backend référence : fondation, RawTransaction et RawAccountState |
| 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.12` | première verticale HTTP puis extension multi-source/historique sans changer l’identité RAW |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.12` | contrôle du backfill RAW ; sélection des stratégies/sources ajoutée après le worker live |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.16` | première verticale HTTP puis extension multi-source/historique sans changer l’identité RAW |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.16` | contrôle du backfill RAW ; sélection des stratégies/sources ajoutée après le worker live |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8` | inspection RAW read-only Transaction/Account/Observation via façade Store |
| Worker lifecycle | `ksp-worker-api` | API | Retenu | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Retenu | `0.3.10` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.11` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Retenu | `0.3.11`–`0.3.14` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
| 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 |
| CORE processor | nom à fixer | processor/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE |
| CORE worker | nom à fixer | worker | Retenu | fin couche CORE | backlog RAW -> CORE continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 23 -->
<!-- version: 24 -->
# Graphe de dépendances KSP
@@ -402,7 +402,7 @@ ksp-worker-control-lib
-> 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. Son premier consumer concret est prévu en `0.3.10` avec `ksp-worker-raw-transaction-ingest-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. Son premier consumer concret est prévu en `0.3.11` avec `ksp-worker-raw-transaction-ingest-lib`, puis ses sources live sont complétées jusqu’en `0.3.14`.
Le worker RAW Transaction n'est pas défini comme « un worker WebSocket » ou « un worker gRPC ». Il reçoit une ou plusieurs stratégies d'acquisition construites au-dessus des façades KSP réellement disponibles ; celles-ci peuvent être alternatives, complémentaires (discovery + hydration), redondantes entre providers ou spécialisées live/catch-up/gap-repair. La transaction canonique reste identifiée indépendamment de la source et chaque acquisition utile conserve sa propre observation/provenance Store.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 14 -->
<!-- version: 15 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -90,7 +90,7 @@ Le job :
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.12` doit réauditer `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.16` doit réauditer `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`.
### Worker RAW Transaction live
@@ -163,25 +163,25 @@ La présence d'une voie dans l'architecture signifie qu'elle doit pouvoir être
Pour chaque voie, l'audit couvre au minimum :
| Dimension | Question à trancher |
|----------------------|-----------------------------------------------------------------------|
| transport/protocole | HTTP, WS standard, extension provider, Yellowstone ou autre ? |
| réseau | Mainnet, Devnet, Testnet réellement disponibles et utiles ? |
| disponibilité | gratuite/payante/provider-dependent ; limites actuelles à réauditer ? |
| temporalité | live, catch-up, historique, replay récent ? |
| discovery | comment la transaction est-elle découverte ? |
| transaction complète | reçue directement ou hydration nécessaire ? |
| filtres | programmes/comptes/signatures/slots/status et bornes ? |
| ordering/duplicates | quelles garanties existent et quelles duplications sont normales ? |
| reconnect/replay | que se passe-t-il après coupure ? |
| gap recovery | quelle autre stratégie répare les trous ? |
| backpressure | quelles limites et comportements si le consumer ralentit ? |
| commitment/finality | quels niveaux sont disponibles et comment les interpréter ? |
| provenance | quelles métadonnées sûres alimentent `RawTransactionObservation` ? |
| limites/quota | RPS, connexions, subscriptions, credits ou autres limites actuelles ? |
| gap KSP Transport | surface déjà disponible ou adaptation nécessaire en `0.3.10` ? |
| gap KSP Config | profil/secret/capability déjà disponible ou adaptation nécessaire ? |
| usage | continuous ingest, gap repair, historical backfill ou combinaison ? |
| Dimension | Question à trancher |
|----------------------|-----------------------------------------------------------------------------|
| transport/protocole | HTTP, WS standard, extension provider, Yellowstone ou autre ? |
| réseau | Mainnet, Devnet, Testnet réellement disponibles et utiles ? |
| disponibilité | gratuite/payante/provider-dependent ; limites actuelles à réauditer ? |
| temporalité | live, catch-up, historique, replay récent ? |
| discovery | comment la transaction est-elle découverte ? |
| transaction complète | reçue directement ou hydration nécessaire ? |
| filtres | programmes/comptes/signatures/slots/status et bornes ? |
| ordering/duplicates | quelles garanties existent et quelles duplications sont normales ? |
| reconnect/replay | que se passe-t-il après coupure ? |
| gap recovery | quelle autre stratégie répare les trous ? |
| backpressure | quelles limites et comportements si le consumer ralentit ? |
| commitment/finality | quels niveaux sont disponibles et comment les interpréter ? |
| provenance | quelles métadonnées sûres alimentent `RawTransactionObservation` ? |
| limites/quota | RPS, connexions, subscriptions, credits ou autres limites actuelles ? |
| gap KSP Transport | surface déjà disponible ou adaptation nécessaire dans `0.3.10` à `0.3.14` ? |
| gap KSP Config | profil/secret/capability déjà disponible ou adaptation nécessaire ? |
| usage | continuous ingest, gap repair, historical backfill ou combinaison ? |
#### Helius et Config
@@ -192,7 +192,7 @@ Décisions déjà acquises :
```text
KSP_SECRET_HELIUS_API_KEY existe déjà côté environnement KSP
Helius HTTP et WS Mainnet/Devnet doivent être considérés comme futures sources candidates
les profils/endpoints réellement nécessaires sont ajoutés seulement en 0.3.10
les profils/endpoints réellement nécessaires sont ajoutés seulement dans la release Worker qui les consomme, principalement 0.3.13/0.3.14
aucune URL Helius nouvelle n'est ajoutée pendant 0.3.8
Config reste l'unique propriétaire des secrets et de leur résolution
les fonctionnalités standard et advanced/enhanced sont capability-gated, jamais supposées par le seul nom du provider
@@ -226,7 +226,7 @@ La déduplication ne doit donc pas supprimer la provenance utile sous prétexte
La Desk prévue après le worker choisit et supervise les **source(s)/méthode(s)** offertes par la composition réellement disponible. Elle ne possède pas la logique de discovery, hydration, déduplication, replay ou persistance.
Elle doit pouvoir représenter selon les capacités finales de `0.3.10` :
Elle doit pouvoir représenter selon les capacités finales du Worker après `0.3.14` :
```text
une source unique

4
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
<!-- version: 11 -->
<!-- version: 12 -->
# Applications, services, scenarios et control plane
@@ -493,7 +493,7 @@ Elle ne modifie jamais directement l'état interne du worker dans PostgreSQL. El
Le premier déploiement peut piloter `ksp-worker-raw-transaction-ingest-lib` in-process si cela reste le choix le plus simple et le plus sûr. La sémantique de `ksp-worker-api` doit néanmoins rester compatible avec un futur proxy vers un worker autonome ; l'IPC/remote control ne doit pas être anticipé artificiellement avant besoin réel.
La Desk RAW Transaction doit laisser choisir **une ou plusieurs sources/méthodes** parmi les capabilities effectivement configurées/admissibles par `0.3.10`, et superviser leur état sans dupliquer discovery/hydration/déduplication/recovery dans Tauri. Store Desk reste la surface d'inspection détaillée des RAW persistés.
La Desk RAW Transaction doit laisser choisir **une ou plusieurs sources/méthodes** parmi les capabilities effectivement configurées/admissibles par le Worker finalisé en `0.3.14`, et superviser leur état sans dupliquer discovery/hydration/déduplication/recovery dans Tauri. Store Desk reste la surface d'inspection détaillée des RAW persistés.
## Configuration desired vs effective

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Acquisition et alimentation `RawTransaction`
@@ -711,9 +711,9 @@ Yellowstone Transaction/Block -> signal structuré + transaction wire fidèle
RAW v1 complet -> hydration HTTP avant persistence
```
Aucun adapter productif n'est ajouté en `pre.006`. Conformément à `TR-C2`, l'adapter `Transport DTO -> common` demeure réservé au Worker de `pre.007`.
Aucun adapter productif n'est ajouté en `pre.006`. Conformément à `TR-C2`, l'adapter `Transport DTO -> common` demeure réservé au Worker concret, désormais ouvert en `0.3.11`.
## 14. Handoff `0.3.10` : Worker live
## 14. Handoff Worker live `0.3.11` à `0.3.14`
### 14.1 Contrat fonctionnel
@@ -783,7 +783,7 @@ 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.
## 15. Handoff `0.3.12` : Job Backfill multi-stratégie
## 15. Handoff `0.3.16` : Job Backfill multi-stratégie
Le Job doit conserver son vertical slice existant puis ajouter des stratégies historiques choisies selon requête + capabilities + configuration.
@@ -808,18 +808,17 @@ L'exhaustivité de l'architecture ne signifie pas que chaque intégration vendor
Ordre conseillé :
```text
0.3.10 P0 : normalisation RAW commune
0.3.10 P0 : observed getBlock + adapters source-neutral
0.3.10 P0 : Yellowstone transactions/blocks live
0.3.10 P0 : WS logs + hydration, blockSubscribe, Helius transactionSubscribe
0.3.10 P0 : HTTP live block polling/hydration
0.3.10 P1 : multi-source concurrency, dedup, provenance, continuity repair
0.3.10 P1 : smokes gratuits Mainnet/Devnet/Testnet
0.3.10 P2 : EARLY adapters accessibles
0.3.12 P0 : block scan historique
0.3.12 P0 : replay Yellowstone borné
0.3.12 P1 : provider history/archive
0.3.12 P1 : Old Faithful
0.3.10 P0 : normalisation RAW commune + observed getBlock + preuves cross-source
0.3.11 P0 : Worker foundation/runtime + persistence déterministe
0.3.12 P0 : Yellowstone transactions/blocks/status + hydration + replay continuity
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
0.3.14 P0 : continuity repair complet + hardening + smokes gratuits accessibles
0.3.14 P2 : EARLY adapters accessibles seulement si prouvés
0.3.16 P0 : block scan historique
0.3.16 P0 : replay Yellowstone borné
0.3.16 P1 : provider history/archive
0.3.16 P1 : Old Faithful
plus tard : substrats directs et sources vendor-specific sans accès actuel
```
@@ -936,9 +935,10 @@ network identity = mainnet canonique ; mainnet-beta alias legacy/ext
RAW canonicalisation = lower-layer commune, sans edge Job <-> Worker
Transaction V1 = wire source-neutral Legacy/V0/V1 dans common ; activation cluster non supposée
Yellowstone pre.006 = transaction wire V1 qualifié ; RAW complet via hydration HTTP
TR-C2 = adapter productif Transport DTO -> common réservé au Worker pre.007
0.3.10 = Worker live multi-source + adaptations communes nécessaires
0.3.12 = Job Backfill multi-stratégie historique
TR-C2 = adapter productif Transport DTO -> common réservé au Worker concret
0.3.10 = common RAW + preuves cross-source
0.3.11 à 0.3.14 = Worker live multi-source par responsabilités bornées
0.3.16 = Job Backfill multi-stratégie historique
```
`0.3.9` n'implémente aucune nouvelle stratégie d'acquisition. Il ferme l'architecture et l'inventaire nécessaires aux releases suivantes.

153
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
View File

@@ -1,17 +1,24 @@
<!-- file: docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Plan v0.3.10 — RAW Transaction commune + Worker d’ingestion multi-source
# Plan v0.3.10 — RAW Transaction commune + qualification cross-source
## 1. But de la version
La version `0.3.10` doit matérialiser deux responsabilités successives et indépendantes du Job historique :
La mission d'ouverture associait initialement la lower-layer RAW commune et le premier Worker concret. Après `pre.006`, ce périmètre est recalibré : les six premières tranches ont déjà matérialisé la common RAW, migré Backfill et fermé les principaux gates de parité HTTP/WS/Helius/Yellowstone, tandis que le runtime Worker n'a pas encore commencé. Conserver les deux moitiés dans une même release rend désormais incertaine la clôture dans une seule session et laisse plusieurs futures prereleases au-dessus du budget de 15–20 minutes.
`0.3.10` ferme donc uniquement la fondation commune et ses preuves cross-source :
```text
1. extraire la canonicalisation RAW Transaction v1 dans ksp-raw-transaction-lib ;
2. construire ksp-worker-raw-transaction-ingest-lib comme Worker continu multi-source.
1. canonicalisation RAW Transaction v1 dans ksp-raw-transaction-lib ;
2. migration Backfill sans changement de comportement ;
3. matériau/wire source-neutral + provenance observée nécessaires aux futurs producteurs ;
4. qualification déterministe HTTP / WS / Helius / Yellowstone ;
5. handoff détaillé vers les releases Worker 0.3.11 à 0.3.14.
```
Le runtime Worker, ses sources live et son gap repair quittent les critères de sortie de `0.3.10` avant toute implémentation lourde.
Le centre du système reste Store :
```text
@@ -493,7 +500,7 @@ Transaction V1 / champ config : proto >= 12.6 nécessaire, donc 12.7 courant est
Alchemy reste volontairement `À REVALIDER` sur la profondeur replay : sa page dédiée Historical Replay annonce environ `432000` slots / `48 h`, tandis que son overview/SubscribeRequest mentionne encore `6000` slots. KSP ne doit encoder **aucune** constante Alchemy ; le runtime se fie à une capability/replay info observée ou à un paramètre configuré/prouvé.
## 8. Surface publique minimale du Worker concret
## 8. Handoff `0.3.11` — surface publique minimale du Worker concret
La V1 cible la surface suivante, sans paramètre historique métier :
@@ -547,7 +554,7 @@ BackfillCheckpoint
JobId
```
## 9. Ownership runtime et supervision
## 9. Handoff `0.3.11` — ownership runtime et supervision
### 9.1 Executor et tâches
@@ -632,7 +639,7 @@ Unhealthy = garantie requise non satisfaite mais policy de recovery encore activ
Faulted = décision terminale après budget/policy ou conflit d’intégrité
```
## 10. Multi-source concurrency et backpressure
## 10. Handoff `0.3.11`/`0.3.13` — multi-source concurrency et backpressure
### 10.1 Pipeline interne
@@ -695,7 +702,7 @@ publier Faulted(ERROR_CODE_RAW_TRANSACTION_INGEST_CONTENT_CONFLICT)
Le payload/signature/hash divergent ne doit pas apparaître dans logs/snapshots publics.
## 11. Continuité et gap repair
## 11. Handoff `0.3.12`/`0.3.14` — continuité et gap repair
### 11.1 Frontier de run
@@ -754,7 +761,7 @@ Yellowstone reconnect avec from_slot prouvé
-> continuity PROVEN seulement après rattrapage/validation
```
## 12. Snapshots et notifications concrètes
## 12. Handoff `0.3.11` — snapshots et notifications concrètes
`ksp-worker-api` reste inchangé. Le Worker concret publie deux projections latest-value :
@@ -798,7 +805,7 @@ Pour les rates, la V1 publie des compteurs monotones et des timestamps/sequence
Le publisher est latest-value/coalescent : lecteur lent ou absent n’influence jamais le lifecycle.
## 13. Décision Config/composition
## 13. Handoff `0.3.13`/`0.3.14` — décision Config/composition
### 13.1 Aucun edge Worker -> Config
@@ -823,7 +830,7 @@ WS protocol kind + session settings
gRPC protocol + metadata publique/secrète + session settings
```
Cela suffit pour matérialiser et tester la bibliothèque Worker programmatiquement. `0.3.10` n’ajoute pas par défaut un `std.raw_transaction_ingest` qui forcerait `ksp-config-lib` à dépendre du Worker concret.
Cela suffit comme handoff pour matérialiser et tester la bibliothèque Worker programmatiquement à partir de `0.3.11`. Aucune release Worker n’ajoute par défaut un `std.raw_transaction_ingest` qui forcerait `ksp-config-lib` à dépendre du Worker concret.
Le choix utilisateur/composition de « quelles sources activer » appartient naturellement au futur `ksp-app-raw-transaction-ingest-desk` `0.3.11`. Si `0.3.10` découvre un manque **Transport** indispensable (par exemple un profil Helius de preuve ou un rôle HTTP live), l’adaptation Config reste limitée au standard Transport et ne crée pas de dépendance inversée.
@@ -839,7 +846,7 @@ source snapshot n’expose que source_id/capability/health
`KSP_SECRET_HELIUS_API_KEY` reste l’unique secret Helius lorsqu’un profil Helius est ajouté ; ne pas multiplier des secrets par méthode.
## 14. Threat model `0.3.10`
## 14. Threat model commun et handoff Worker
| Risque | Impact | Garde prévue |
|:--------------------------------------------|:------------------------------------|:------------------------------------------------------------------------------|
@@ -1024,121 +1031,55 @@ ksp-worker-raw-transaction-ingest-lib
`ksp-interface-lib` reste absent sauf nécessité passive démontrée.
## 17. Sizing et trajectoire recalibrée
## 17. Sizing et trajectoire recalibrée après `pre.006`
La prévision initiale du prompt est trop dense pour certaines tranches si chacune doit rester autour de 15–20 minutes effectives. Le plan retenu sépare canonicalisation, parité, runtime et sources :
Le gate opérateur de `pre.006` confirme que le problème n'est pas seulement un correctif ponctuel : la seconde moitié du plan concentrait dans chaque tranche plusieurs responsabilités runtime distinctes. Selon `PROMPT_STRUCTURE.md`, une prerelease estimée au-delà d'environ 15–20 minutes doit être scindée et une release concrète dont la clôture dans une seule session devient incertaine doit être redécoupée avant l'implémentation lourde.
### `pre.001` — audit/sizing/plan
La frontière naturelle est déjà matérialisée : la common RAW et les preuves cross-source existent, alors que `ksp-worker-raw-transaction-ingest-lib` n'existe pas encore. `0.3.10` est donc fermée autour de la première moitié, puis le Worker est réparti sur quatre releases concrètes cohérentes. Chaque nouvelle release recommencera par sa propre `pre.001` de sizing et scindera toute tranche dépassant le budget.
Présente tranche : archive/règles, common extraction, capability matrix, fraîcheur, runtime, continuity, threat model, preuves et graphe. Aucune implémentation lourde.
### `pre.001` à `pre.006` — fondation RAW et parités
### `pre.002` — common RAW foundation
Statut : réalisés, avec fixes déjà tracés et `pre.006-fix.001` requis pour les erreurs Rust révélées par le premier gate opérateur de `pre.006`.
**Statut : réalisé.**
### `pre.007` — gate technique final `0.3.10`
`ksp-raw-transaction-lib` matérialise les types source-neutral minimaux, le parser Base58 strict vers 64 octets, la canonicalisation JSON RAW v1, SHA-256 et l’assemblage transaction + observation producer-owned. Le golden `112` bytes / `220792...a7c3` est verrouillé par test. Aucun Worker ni migration Backfill n’est ouvert.
Budget cible : **15–20 min**. Rejouer le workspace complet, Clippy strict, suites common/Transport/Backfill, arbres normal/dev/features pertinents et duplicate tree. Aucun nouveau scope fonctionnel ; tout défaut découvert appartient à une tranche corrective dédiée avant de poursuivre la fermeture.
La matérialisation a révélé une correction normative du sizing `pre.001` : `DEP-PIPE-006` impose `ksp-store-api` au pipeline RAW et interdit `ksp-store-lib`. Le graphe et la section 5.4 sont donc corrigés dans cette tranche sans changer le contrat fonctionnel RAW.
### `pre.008` — réconciliation documentaire `0.3.10`
La validation opérateur du 2026-09-06 a d’abord révélé un échec Clippy limité aux tests d’intégration. `pre.002-fix.001` a corrigé ces canaris sans toucher au contrat RAW. Le rejeu opérateur suivant est intégralement vert : audits, `cargo check --workspace`, Clippy `--all-targets --all-features -- -D warnings`, tests de `ksp-raw-transaction-lib`, arbre normal et arbre de features. La fondation common est donc fermée.
Budget cible : **10–15 min**. Réconcilier plan, validation, README/USAGE de la common si nécessaire et architecture durable avec le périmètre effectivement livré. Aucun runtime Worker, smoke nouveau, CHANGELOG, ROADMAP ou prompt suivant.
### `pre.003` — migration Backfill vers common
### `pre.009` — préparation de publication `0.3.10`
**Statut : réalisé.**
Budget cible : **5–10 min**. Préparer le prompt `0.3.11`, CHANGELOG, ROADMAP et fichiers mécaniques de version/delta uniquement.
La canonicalisation privée du Backfill est supprimée au profit de `ksp-raw-transaction-lib`. Le Job conserve uniquement l’adaptation Transport vers `RawTransactionMaterial`, le remapping de ses erreurs publiques, la provenance/campagne et sa `RawObservationKey` producer-owned. Le parser Base58 common, `canonicalize_raw_transaction(...)` et `assemble_raw_transaction_acquisition(...)` sont désormais les chemins uniques pour la signature, RAW v1 et l’assemblage.
### `rel.001` — publication stable `0.3.10`
Les invariants historiques restent gelés : `ksp.solana.raw_transaction` v1, golden `112` octets, SHA-256 `220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3`, origin `Backfill`, provider/endpoint/commitment/capture-session, observation key de campagne et sémantique `Missing`. Les erreurs common sont remappées sur `ERROR_CODE_BACKFILL_RAW_CONVERSION_INVALID` afin de ne pas modifier le contrat externe du Job.
Publication mécanique de la fondation RAW commune et de ses preuves cross-source, sans rattrapage code/doc.
Le rejeu opérateur du 2026-09-06 ferme `pre.003` : audits statiques propres, `cargo check --workspace` PASS, Clippy strict PASS, `cargo test -p ksp-raw-transaction-lib` PASS, `cargo test -p ksp-job-backfill-lib` PASS avec 51 tests unitaires et 20 tests d’intégration, et arbres normal/features conformes.
### `0.3.11` — Worker foundation/runtime
### `pre.004` — HTTP observed block + block material
Nouvelle release/session : crate, dependency firewall, settings source-neutral, handle/start-stop, lifecycle, snapshots, supervisor, bounded channels et pipeline déterministe de persistence/déduplication. Pas de source live complexe comme critère de sortie.
**Statut : réalisé.**
### `0.3.12` — Yellowstone + hydration + continuity
`HttpTransportPool::get_block_observed(...)` complète la provenance HTTP observée sans exposer URL/header/body et conserve le provider/endpoint du winner réel après retry/reroute. La common RAW ajoute l’extraction bornée de la première signature depuis un transaction wire Base64 complet et `RawTransactionMaterial::binary_base64_with_embedded_signature(...)` pour préserver slot, block time, meta, version et transaction index.
Nouvelle release/session : transactions/blocks/status, hydration HTTP, source health, `from_slot`, replay info, run frontier et continuité Yellowstone propre au run.
Conformément à `TR-C2`, aucun adapter productif Transport DTO -> `RawTransactionMaterial` n’est placé dans Transport : une preuve cross-layer test-only démontre `get_block_observed -> N SolanaBlockTransaction -> RawTransactionMaterial -> RAW v1` sur deux transactions distinctes avec index 0/1, tandis que l’adapter productif reste réservé au futur Worker. Aucun Worker live complet n’est ouvert.
### `0.3.13` — WS/Helius/HTTP live + convergence multi-source
Le premier rejeu opérateur de `pre.004` a validé les audits, `cargo check`, les tests common, les 387 tests Transport et le canari cross-layer, mais Clippy strict a rejeté sept `expect()` placés dans deux helpers de fixture hors du corps `#[tokio::test]`. `pre.004-fix.001` corrige uniquement ces helpers en retournant explicitement des `Result`; aucun code de production, contrat RAW, surface Transport, golden ou dépendance n’est modifié.
Nouvelle release/session : logs + hydration, blockSubscribe, Helius transactionSubscribe + hydration, HTTP live block polling, observations multiples, content conflicts, coalescence et backpressure.
Le rejeu opérateur du fix le 2026-09-06 est intégralement vert : audits statiques, `cargo check --workspace`, Clippy strict, tests common, 387 tests Transport avec suites publiques/release/doctests, et suite complète `ksp-job-backfill-lib`. Les arbres n’ont pas été rejoués car `pre.004-fix.001` n’a modifié aucune dépendance ni feature.
### `0.3.14` — gap repair/hardening + smokes
### `pre.005` — parité WS/Helius full
Nouvelle release/session : replay natif, source redondante, scan HTTP blocs, hydration de repair, unresolved gaps, politiques degraded/unhealthy/faulted, shutdown pendant repair, smokes provider accessibles et EARLY seulement si prouvé.
**Statut : réalisé.**
### `0.3.15` — Desk d'ingestion
Deux canaris cross-layer test-only ferment la qualification sans ajouter de code de production. `blockSubscribe` standard en `confirmed/full/base64`, `maxSupportedTransactionVersion = 0`, `showRewards = false` reproduit le même `SolanaConfirmedBlock` que `getBlock` puis les mêmes référence, slot, block time, bytes RAW v1 et content hash pour une transaction legacy. Ce sous-ensemble legacy/v0 est donc qualifié direct ; Transaction V1 reste explicitement au gate `pre.006`.
Ancienne cible `0.3.11`, décalée après finalisation complète du Worker.
Helius `transactionSubscribe` full/base64 conserve la signature, le slot, le transaction wire, la meta et `transactionIndex`, mais la notification qualifiée ne fournit ni `blockTime` ni `version`. Le canari construit la meilleure projection possible puis prouve qu’elle diverge de l’hydration HTTP sur block time, bytes RAW v1 et content hash malgré une identité/slot identiques. Helius est donc verrouillé comme signal live riche + hydration HTTP, jamais comme producteur RAW-direct dans ce contrat.
### `0.3.16` — Backfill multi-source/multi-stratégie
`tokio-tungstenite` est ajouté uniquement en `dev-dependencies` du Backfill pour les serveurs WebSocket locaux déterministes ; un canari de dependency boundary interdit sa migration vers les dépendances de production. `TR-C2` reste Worker-owned.
Le premier rejeu opérateur de `pre.005` le 2026-09-06 valide les audits statiques, `cargo check --workspace`, la common RAW, les 387 tests Transport et les arbres normal/dev/features, mais `cargo clippy --workspace --all-targets --all-features -- -D warnings` ainsi que `cargo test -p ksp-job-backfill-lib` s’arrêtent sur une unique erreur de compilation du nouveau canari : `RawTransaction::block_time().unix_millis()` retourne `u64`, tandis que `FIXTURE_BLOCK_TIME * 1_000` était inféré en `i64`. `pre.005-fix.001` corrige uniquement cette constante de comparaison en millisecondes `u64`; aucun code de production, golden, contrat RAW/WS ni dépendance n’est modifié.
Le second rejeu opérateur de `pre.005-fix.001` révèle ensuite deux gardes de test supplémentaires : Clippy strict refuse 25 usages de l’opérateur `?` dans les helpers/canaris de `ws_raw_parity.rs`, et le canari historique `pre_010_manifest_dependency_surface_is_exact_and_backend_neutral` attend encore uniquement `tokio` dans les dev-dependencies alors que `pre.005` a ajouté `tokio-tungstenite` en dev-only. `pre.005-fix.002` remplace les `?` par des `match`/`if let Err` explicites et recalibre uniquement le set dev attendu vers `tokio` + `tokio-tungstenite`. Aucun code de production, dépendance, feature, golden ou décision de qualification WS/Helius n’est modifié.
### `pre.006` — parité Yellowstone transactions/blocks
**Statut : réalisé, en attente du gate opérateur Rust.**
La common RAW gagne un modèle transaction wire source-neutral Legacy/V0/V1 et des serializers exacts bytes/Base64. Les goldens couvrent Legacy, V0, V1 avec configuration complète et V1 avec configuration présente mais vide. L'extracteur de première signature Base64 traite désormais le layout V1 `0x81` à signatures terminales et conserve le chemin signatures-first Legacy/V0.
Le modèle V1 verrouille les contraintes SIMD-0385 utiles à l'ingestion : 4096 octets maximum, 12 signatures, 64 adresses, 64 instructions, indexes bornés, aucune ALT, configuration inline et absence de trailing bytes après les signatures. La common reste Transport/Config/Job/Worker/runtime-free.
Un canari `yellowstone_raw_parity.rs` monte un Geyser Tonic local et utilise le vrai chemin public Transport `YellowstoneGrpcChannel -> open_standard_subscribe -> YellowstoneSubscribeUpdate`. Une `Transaction` V1 puis un `Block` V1 portant la même transaction sont projetés test-only vers la common et doivent sérialiser exactement le même wire V1. Le canari vérifie aussi slot, transaction index et `block_time` côté Block.
La qualification RAW-direct complète est refusée : l'update Transaction n'a pas `block_time`, et la meta Yellowstone protobuf n'est pas prouvée byte-identical avec la meta JSON HTTP du RAW v1 actuel. Le futur Worker doit donc utiliser Yellowstone comme signal live/transaction-wire riche puis hydrater par HTTP avant persistence RAW, tant qu'un gate ultérieur ne prouve pas `TR-C4`.
`tonic` et `yellowstone-grpc-proto` sont ajoutés uniquement en `dev-dependencies` du Backfill pour le serveur déterministe ; les canaris dependency/hardening verrouillent leur absence du graphe productif. Aucun adapter productif n'est placé en Backfill ou Transport : `TR-C2` reste réservé au Worker `pre.007`.
La fraicheur upstream a été revalidée le 7 septembre 2026 : SIMD-0385 décrit encore V1 comme `Review`/pre-release et les exemples Solana signalent une activation cluster feature-gated. KSP implémente donc le décodage/canonicalisation sans supposer l'activation Mainnet.
### `pre.007` — Worker foundation/runtime
Créer la crate Worker concrète, settings, handle, lifecycle, supervisor, source abstraction interne, bounded channel, common/concrete snapshots et shutdown sans source live complexe.
### `pre.008` — Yellowstone live + continuity
Brancher transactions/blocks/status, source health, from_slot/replay info, run frontier et tests déterministes de replay/duplicates.
### `pre.009` — WS/HTTP live
Brancher logs+hydration, blockSubscribe, HTTP live block polling/hydration et Helius transactionSubscribe selon capability/access.
### `pre.010` — multi-source persistence/dedup/hardening
Convergence Store, observations multiples, content conflicts, coalescence bornée, backpressure, source failure isolation et adversarial tests.
### `pre.011` — gap repair complet
Replay natif, redondance, HTTP block scan, hydration, unresolved gaps, policy degraded/unhealthy/faulted et shutdown pendant repair.
### `pre.012` — Config/profiles + provider smokes accessibles
Ajouter seulement les profils/roles Transport réellement nécessaires, exécuter les smokes gratuits/credentials disponibles et documenter clairement les tiers bloqués. Pas d’edge Worker -> Config.
### `pre.013` — EARLY si prouvé, sinon consolidation
N’ajouter un adapter EARLY que si protocole, accès et rôle RAW sont prouvés. Sinon consacrer la tranche aux dettes/hardening découvertes ; ne pas créer de faux support.
### `pre.014` — gate technique/live final
Workspace complet, all-targets/all-features, cargo trees, duplicate tree, smokes pertinents, continuity repair et Store proof.
### `pre.015` — réconciliation documentaire finale
README/USAGE/architecture/plan/validation uniquement ; aucun rattrapage fonctionnel.
### `pre.016` — préparation de publication
Prompt `0.3.11`, CHANGELOG, ROADMAP et fichiers mécaniques de version/delta uniquement.
### `rel.001` — publication stable
Publication mécanique `v0.3.10` sans rattrapage code/doc.
Cette trajectoire reste souple : une tranche réellement petite peut être fusionnée, mais aucune tranche > environ 20 minutes ne doit être artificiellement conservée monolithique.
Ancienne cible `0.3.12`, décalée sans changer la frontière Job historique paramétré / Worker live.
## 18. Gates Cargo futurs obligatoires
@@ -1182,8 +1123,8 @@ Les smokes live restent séparés et opt-in.
## 20. Hors périmètre confirmé
```text
ksp-app-raw-transaction-ingest-desk # 0.3.11
nouvelles stratégies historiques Backfill # 0.3.12
ksp-app-raw-transaction-ingest-desk # 0.3.15
nouvelles stratégies historiques Backfill # 0.3.16
paramètres métier historiques dans Worker
Backfill checkpoint dans Worker
RawAccountState ingest worker

32
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
View File

@@ -1,11 +1,11 @@
<!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Validation v0.3.10 — RAW Transaction commune + Worker d’ingestion
# Validation v0.3.10 — RAW Transaction commune + qualification cross-source
## 1. Rôle du document
Ce document suit les preuves de la release `0.3.10` : extraction de la canonicalisation RAW v1 vers `ksp-raw-transaction-lib`, migration Backfill puis matérialisation du Worker continu multi-source `ksp-worker-raw-transaction-ingest-lib`.
Ce document suit les preuves de la release `0.3.10` : extraction de la canonicalisation RAW v1 vers `ksp-raw-transaction-lib`, migration Backfill, matériau/wire source-neutral et qualification cross-source HTTP/WS/Helius/Yellowstone. Après le recalibrage de `pre.006-fix.001`, la matérialisation du Worker continu est transférée vers `0.3.11` à `0.3.14` avant toute implémentation lourde.
Il distingue toujours :
@@ -175,7 +175,7 @@ HTTP roles/priorities/limits déjà supportés
WS protocol/session déjà supportés
```
Décision : pas d’edge Worker -> Config et pas de nouveau document métier Worker imposé dans `0.3.10`. Une adaptation Config n’est admise que pour un manque Transport concret découvert pendant l’implémentation.
Décision de handoff : pas d’edge Worker -> Config et pas de nouveau document métier Worker imposé par la common RAW. Une adaptation Config future n’est admise que pour un manque Transport concret découvert dans les releases Worker concernées.
## 4. Fraîcheur externe `pre.001`
@@ -244,7 +244,9 @@ pas de content normalization ad hoc non documentée
source utilisée comme discovery + hydration HTTP jusqu’à résolution
```
## 6. Gates Worker à fermer pendant la release
## 6. Gates Worker transférés aux releases `0.3.11`–`0.3.14`
Ces gates faisaient partie du plan `pre.001` initial. Ils restent des exigences de handoff, mais **ne sont plus des critères de sortie de `0.3.10`** depuis le redécoupage de `pre.006-fix.001`. Leur conservation ici évite de perdre le threat model et les preuves prévues ; leur exécution appartient aux nouveaux documents de validation Worker.
### 6.1 Lifecycle/runtime
@@ -365,17 +367,17 @@ pre.003 Backfill migration parity
pre.004 observed block
pre.005 WS/Helius parity
pre.006 Yellowstone parity
pre.007 Worker runtime foundation
pre.008 Yellowstone live/replay
pre.009 WS/HTTP live
pre.010 multi-source Store/hardening
pre.011 gap repair
pre.012 Config/profiles + provider smokes
pre.013 EARLY ou consolidation
pre.014 final technical/live gate
pre.015 final docs reconciliation
pre.016 publication preparation
pre.006-fix.001 corrections Rust + recalibrage du sizing
pre.007 final technical gate 0.3.10
pre.008 final docs reconciliation 0.3.10
pre.009 publication preparation 0.3.10
rel.001 stable publication
0.3.11 Worker foundation/runtime
0.3.12 Yellowstone live + hydration + continuity
0.3.13 WS/Helius/HTTP live + convergence multi-source
0.3.14 gap repair/hardening + smokes
0.3.15 Desk d'ingestion
0.3.16 Backfill multi-source
```
## 11. Gate `pre.002` — common RAW foundation