v0.3.13-pre.014

2026-09-10 23:25:05 +02:00
parent cabbfed730
commit 71bc754feb
8 changed files with 315 additions and 52 deletions
--- a/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
+++ b/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->

 # Acquisition et alimentation `RawTransaction`

@@ -149,7 +149,7 @@ Il peut utiliser **HTTP, WS, Yellowstone gRPC, replay provider ou archive** si c

 ### 3.2 Worker Raw Transaction Ingest : acquisition continue start/stop

-`ksp-worker-raw-transaction-ingest-lib` a pour rôle de **remplir continuellement Store à partir du moment où il est démarré**. Sa fondation runtime, l'admission, la canonicalisation Common RAW, la persistence et les snapshots sont complétés par une première source productive Yellowstone standard + hydration HTTP `getTransaction`.
+`ksp-worker-raw-transaction-ingest-lib` a pour rôle de **remplir continuellement Store à partir du moment où il est démarré**. Sa fondation runtime, l'admission, la canonicalisation Common RAW, la persistence et les snapshots supportent désormais une composition live multi-source bornée de `1` à `32` sources logiques sur un même réseau.

 Son contrôle métier V1 est volontairement court :

@@ -161,22 +161,33 @@ snapshot / notifications

 Le caller ne lui fournit pas une signature, un `program_id`, une plage historique, une limite de campagne ou une requête de backfill. Les endpoints, réseaux, sources activées, capabilities et secrets proviennent de Config/composition, pas d'un payload métier de `start`.

-Deux entrées publiques coexistent : `start` conserve la fondation sans source productive, tandis que `start_with_runtime_resources` lance une source Yellowstone supervisée. Le pipeline productif actuel est :
+Deux entrées publiques coexistent : `start` conserve la fondation sans source productive, tandis que `start_with_runtime_resources` lance la collection de ressources live validée. Les cinq familles productives matérialisées sont :

 ```text
 Yellowstone Transaction / TransactionStatus / Block
+Standard WS logsSubscribe
+Helius transactionSubscribe
    -> signaux transactionnels source-neutral
-    -> coalescence bornée (network, signature, commitment)
+    -> registry globale d'hydration bornée (network, signature, commitment)
    -> HTTP getTransaction observed
    -> Common RAW
-    -> admission centrale
+
+Standard WS blockSubscribe Full/Base64 Legacy|V0|V1
+HTTP live block polling getSlot -> getBlocksWithLimit -> getBlock observed
+    -> qualification RAW directe Legacy|V0|V1
+    -> Common RAW
+
+Toutes les voies
+    -> admission centrale bornée
+    -> convergence canonique (network, signature)
+    -> RawTransaction + observations de provenance distinctes
    -> Store

 Yellowstone BlockMeta / Slot
    -> continuité run-local uniquement
 ```

-La source est caller-composed : le Worker ne lit pas Config et ne reçoit pas de secret. `RawTransactionIngestRuntimeResources` contient actuellement exactement une source Yellowstone validée, pas encore une collection multi-source.
+La composition est caller-owned : le Worker ne lit pas Config et ne reçoit pas de secret. `RawTransactionIngestRuntimeResources` accepte de `1` à `32` sources logiques d'un même réseau, refuse les identités source dupliquées et supervise toutes les sources simultanément. Une faute source reste terminale pour le Worker faute d'équivalence de coverage prouvée.

 Il ne lance pas de campagne historique arbitraire.

@@ -253,7 +264,7 @@ Une source concrète peut fournir plusieurs capabilities. Une capability peut ê
 | HTTP `getSlot` / `getFirstAvailableBlock` / `minimumLedgerSlot` | bornes de ledger                      | non                          | oui, continuité                                            | oui, admission d'une campagne               | aucune transaction directe                                 |
 | WS `logsSubscribe`                                              | signature + logs                      | non                          | oui, discovery live + hydration                            | non pour historique pur                     | `mentions` standard limité à un pubkey                     |
 | WS `signatureSubscribe`                                         | statut d'une signature connue         | non                          | oui, confirmation ciblée interne                           | possible pour une requête ciblée en attente | one-shot                                                   |
-| WS `blockSubscribe` full/base64, legacy-v0                      | bloc + transactions                   | oui, parité RAW v1 prouvée   | oui, direct pour le sous-ensemble qualifié                 | non sans mécanisme de replay historique     | méthode standard instable ; capability validator-dependent |
+| WS `blockSubscribe` full/base64, Legacy/V0/V1                   | bloc + transactions                   | oui, Legacy/V0/V1 qualifiés  | oui, direct pour le sous-ensemble qualifié                 | non sans mécanisme de replay historique     | méthode standard instable ; capability validator-dependent |
 | Helius `transactionSubscribe` full/base64                       | transaction + meta + signature/index  | non sans hydration           | oui, signal riche puis hydration HTTP                      | non comme source historique                 | absence de blockTime/version dans l’enveloppe qualifiée    |
 | Yellowstone `transactions`                                      | transaction exécutée + meta           | oui                          | oui                                                        | oui si replay borné demandé/disponible      | filters server-side                                        |
 | Yellowstone `blocks` avec transactions                          | bloc + transactions                   | oui                          | oui                                                        | oui si replay borné demandé/disponible      | utile au live et au backfill                               |
@@ -274,15 +285,17 @@ Cette matrice est intentionnellement **usage-first**. HTTP n'est pas « Backfill

 ### 6.1 Acquisition directe

-Sources capables de produire directement un matériau transactionnel complet :
+Sources capables de produire directement un matériau transactionnel complet dans l'architecture générale :

 ```text
-Yellowstone transactions
-Yellowstone blocks avec transactions
-WS blockSubscribe full/base64 legacy-v0 qualifié
+Yellowstone transactions/blocks lorsque l'adapter choisi qualifie directement leur wire
+WS blockSubscribe full/base64 Legacy/V0/V1 qualifié
+HTTP getBlock full/base64 Legacy/V0/V1
 provider stream compatible full transaction après parité prouvée
 ```

+Dans le Worker V1 actuel, Yellowstone reste volontairement traité comme signal puis hydraté par HTTP `getTransaction` afin de conserver un seul chemin de canonicalisation productif pour cette famille. Les voies directes effectivement matérialisées dans le Worker sont Standard Block et HTTP Block Polling.
+
 Chemin logique :

 ```text
@@ -567,7 +580,7 @@ Helius transactionSubscribe

 Le runtime WS possède des queues bornées et une logique de reconnect/resubscribe. Un reconnect ne constitue toutefois pas un replay adressable.

-La qualification `pre.005` ferme deux cas distincts : `blockSubscribe` standard en `full/base64` avec `maxSupportedTransactionVersion = 0` produit, sur fixture identique, les mêmes bytes/hash RAW v1 que `getBlock`; Helius `transactionSubscribe` full/base64 conserve l’identité, le slot, le transaction wire, la meta et l’index mais ne transporte pas `blockTime` ni `version` dans l’enveloppe qualifiée. Helius reste donc un signal live riche à hydrater par HTTP avant persistence RAW directe.
+La qualification actuelle ferme deux cas distincts : `blockSubscribe` standard en `full/base64` avec `maxSupportedTransactionVersion = 1` qualifie explicitement Legacy/V0/V1 et produit le matériau Common RAW directement ; Helius `transactionSubscribe` full/base64 conserve l’identité, le slot, le transaction wire, la meta et l’index mais ne transporte pas `blockTime` ni `version` dans l’enveloppe qualifiée. Helius reste donc un signal live riche à hydrater par HTTP avant persistence RAW.

 ### 12.3 Yellowstone gRPC

@@ -721,7 +734,7 @@ RAW v1 complet                -> hydration HTTP avant persistence

 Cette qualification cross-source a préparé le contrat sans créer d'edge Common RAW -> Transport. L'extension Worker live utilise désormais cette décision conservative : Yellowstone produit des signaux structurés dans le Worker concret, puis HTTP `getTransaction` fournit le matériau RAW complet avant canonicalisation. Common RAW reste entièrement Transport-neutral.

-## 14. État du Worker live après `0.3.12`
+## 14. État du Worker live après `0.3.13`

 ### 14.0 Verticale matérialisée

@@ -731,20 +744,24 @@ La verticale productive possède :
 consumer de ksp-worker-api
 settings réseau/Worker bornés
 start/stop sur runtime Tokio caller-owned
-supervision privée des tâches
+supervision privée de 1..32 sources logiques sur un même réseau
+cinq familles live : Yellowstone / Standard Logs / Standard Block / Helius Transaction / HTTP Block Polling
 mpsc central borné + backpressure
-une source Yellowstone standard caller-composed
-Transaction / TransactionStatus / Block -> signaux transactionnels
-BlockMeta / Slot -> continuity-only
+registry globale d'hydration pour Yellowstone / Standard Logs / Helius
+qualification RAW directe pour Standard Block / HTTP Block Polling
 coalescence bornée par network/signature/commitment
 HTTP getTransaction observed pour hydration
 canonicalisation et assembly via ksp-raw-transaction-lib
-persistence atomique via ksp-store-lib en mode Normal
-processing frontier run-local bornée
-projection source Active/Reconnecting/Closing/Closed/Failed
+convergence canonique par (network, signature) + disagreement explicite
+persistence atomique via ksp-store-lib en mode Normal + observations supplémentaires idempotentes
+quotas pending/in-flight par source et bornes globales exactes
+fairness minimale / anti-starvation sous duplicate storm
+processing frontier run-local multi-source conservative
+projection source-neutral Active/Reconnecting/Closing/Closed/Failed + gauges source_total/active/reconnecting/failed
 observation des compteurs reconnect/replay/gap Transport
+health conservative Healthy/Degraded/Unhealthy
 fault sur gap de rétention prouvé
-shutdown deadline + abort/join sans tâche orpheline
+shutdown deadline + abort/join sans tâche orpheline ni late persistence
 ```

 Elle conserve explicitement les frontières suivantes :
@@ -786,21 +803,27 @@ attendre un Job pour continuer
 hardcoder un provider unique
 ```

-### 14.2 Sources Worker V1 à représenter
+### 14.2 Sources Worker V1 matérialisées et reports

-À implémenter autant que possible, même si certaines preuves live restent bloquées par tier :
+Matérialisé dans `0.3.13` :

 ```text
-Yellowstone transactions
-Yellowstone blocks
-Yellowstone status + hydration
+Yellowstone transactions / blocks / status + HTTP hydration
 WS logsSubscribe + HTTP getTransaction
-WS blockSubscribe full/base64 legacy-v0 direct qualifié
-Helius transactionSubscribe full/base64 + HTTP hydration
-HTTP live block polling
-HTTP hydration
-replay Yellowstone pour continuité du run
-sources EARLY via adapter extensible
+WS blockSubscribe Full/Base64 Legacy/V0/V1 direct qualifié
+Helius transactionSubscribe Full + HTTP hydration
+HTTP live block polling getSlot/getBlocksWithLimit/getBlock observed
+HTTP hydration partagée et coalescée cross-source
+replay Yellowstone conservé propriétaire de Transport pour continuité du run
+```
+
+Reste hors de cette verticale et nécessite une tranche dédiée :
+
+```text
+sources EARLY / pre-execution
+coverage-equivalence ou failover non-terminal entre sources
+repair historique multi-source
+Worker multi-source -> Store live E2E avec environnement complet provisionné
 ```

 ### 14.3 Gaps Transport Worker
@@ -858,9 +881,9 @@ Ordre conseillé :
 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.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.16 P0 : block scan historique
 0.3.16 P0 : replay Yellowstone borné
 0.3.16 P1 : provider history/archive
@@ -984,7 +1007,8 @@ Yellowstone pre.006          = transaction wire V1 qualifié ; RAW complet via h
 TR-C2                        = adapter productif Transport DTO -> common réservé au Worker concret
 0.3.10                       = common RAW + preuves cross-source
 0.3.11                       = fondation Worker source-neutral, persistence et observabilité
-0.3.12 à 0.3.14              = sources live multi-source, continuité et hardening par responsabilités bornées
+0.3.12                       = première verticale Yellowstone + hydration/replay continuity
+0.3.13                       = cinq familles live + convergence/fairness/health/shutdown/completeness
 0.3.16                       = Job Backfill multi-stratégie historique
 ```