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

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