v0.3.13-pre.004

crates/ksp-worker-raw-transaction-ingest-lib/README.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-worker-raw-transaction-ingest-lib/README.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # ksp-worker-raw-transaction-ingest-lib
 
@@ -13,8 +13,8 @@ RawTransactionIngestWorker::start
 
 RawTransactionIngestWorker::start_with_runtime_resources
     -> même runtime + une source productive supervisée
-       Yellowstone ou WS standard logsSubscribe
-       + hydration HTTP getTransaction
+       Yellowstone, WS standard logsSubscribe ou WS standard blockSubscribe
+       + hydration HTTP getTransaction lorsque la source produit une référence
 ```
 
 Le Worker reste indépendant de Config et de tout backend Store physique. Le caller compose les ressources Transport et Store, puis les remet à la crate par ses façades publiques.
@@ -31,10 +31,15 @@ Yellowstone standard subscribe
 Solana standard WS logsSubscribe
     -> context.slot + signature
     -> signal source-neutral (network, signature, slot, commitment, provenance sûre)
-
-les deux chemins
     -> coalescence bornée par (network, signature, commitment)
     -> HTTP getTransaction observed, Base64, maxSupportedTransactionVersion=1
+
+Solana standard WS blockSubscribe
+    -> Full + Base64 + maxSupportedTransactionVersion=1 + showRewards=false
+    -> qualification explicite Legacy / V0 / V1
+    -> matériau Common RAW direct par transaction du bloc
+
+les chemins productifs
     -> ksp-raw-transaction-lib
     -> admission centrale bornée
     -> ksp-store-lib
@@ -65,7 +70,7 @@ La construction est sans I/O et refuse notamment :
 - une provenance provider/endpoint non représentable ;
 - l'absence d'une route HTTP compatible pour `getTransaction` sur le même réseau.
 
-Le runtime-resource aggregate public accepte une collection validée de 1 à 32 sources logiques. `pre.003` sait exécuter une source unique Yellowstone ou une source unique Standard Logs ; une activation simultanée de plusieurs sources reste rejetée avant spawn jusqu'au supervisor dédié. La collection interne, les `source_key`, les URLs, les filtres et les clients inférieurs ne sont pas exposés.
+Le runtime-resource aggregate public accepte une collection validée de 1 à 32 sources logiques. `pre.004` sait exécuter une source unique Yellowstone, Standard Logs ou Standard Block ; une activation simultanée de plusieurs sources reste rejetée avant spawn jusqu'au supervisor dédié. La collection interne, les `source_key`, les URLs, les filtres et les clients inférieurs ne sont pas exposés.
 
 ## Contrat de source Standard Logs + HTTP
 
@@ -83,6 +88,22 @@ La construction est sans I/O. Elle refuse un endpoint WS invalide ou non standar
 
 Au runtime, le Worker ouvre `SolanaStandardWsSession::connect`, puis `logs_subscribe`. Les lignes de logs et `err` restent dans Transport et ne sont jamais stockées dans le signal Worker. Seuls `context.slot` et `signature` sont projetés vers l'hydration commune. Reconnect, resubscribe et backpressure de la subscription restent possédés par Transport.
 
+## Contrat de source Standard Block direct RAW
+
+`RawTransactionIngestStandardBlockSource::new` reçoit :
+
+```text
+WsEndpointSettings kind solana_standard
+SolanaBlockSubscribeFilter
+SolanaCommitment Confirmed ou Finalized
+```
+
+Le runtime ouvre la `SolanaStandardWsSession` existante et demande exactement `Base64`, `Full`, `maxSupportedTransactionVersion = 1` et `showRewards = false`. Aucun `HttpTransportPool` n'est attaché à cette source : les transactions dont la version est explicitement `Legacy`, `0` ou `1` sont transformées directement en `RawTransactionMaterial` à partir du wire Base64 du bloc, avec signature embarquée, slot, block time, meta, version et index de transaction.
+
+La qualification est fermée : une version omise/nulle ou supérieure à `1`, une transaction non Base64, `block: null`, une erreur distante de notification, un slot de contexte incohérent ou un champ transactions absent/nul termine la source par une erreur sûre. Aucun de ces cas n'est converti en bloc vide, en succès silencieux ou en progression artificielle de frontier.
+
+Pour un bloc multi-transaction, le slot n'est projeté settled qu'après l'admission réussie de toutes ses transactions. Cette voie RAW-direct n'incrémente pas `hydration_pending`; un stop ou une erreur au milieu du bloc ne produit aucune progression artificielle. Reconnect, resubscribe et backpressure WebSocket restent possédés par Transport.
+
 ## Runtime et lifecycle
 
 Le Worker s'exécute sur le runtime Tokio courant du caller. Il ne crée pas de runtime global et n'expose aucun `JoinHandle` public.
@@ -100,7 +121,7 @@ Le shutdown est borné par `shutdown_drain_timeout`. Les tâches source, hydrati
 
 La queue centrale est un `tokio::sync::mpsc` privé borné par `admission_queue_capacity`. Les sources internes subissent la backpressure ; aucune queue non bornée ni silent drop n'est autorisé.
 
-Le Worker possède un coordinateur d'hydration source-neutral borné, réutilisé par Yellowstone et Standard Logs :
+Le Worker possède un coordinateur d'hydration source-neutral borné, réutilisé par Yellowstone et Standard Logs. Standard Block n'entre pas dans ce coordinateur lorsqu'une transaction est direct-qualified :
 
 ```text
 in-flight hydration <= persistence_concurrency