v0.3.12-pre.012

docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
 # 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 cible de **remplir continuellement Store à partir du moment où il est démarré**. Sa fondation source-neutral matérialise déjà le runtime, l'admission, la canonicalisation Common RAW, la persistence et les snapshots, mais aucune source réseau productive n'est encore branchée.
+`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`.
 
 Son contrôle métier V1 est volontairement court :
 
@@ -161,43 +161,49 @@ 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`.
 
-La fondation actuelle, lorsqu'elle démarre sans adapter source productif, publie son lifecycle/snapshot puis reste contrôlable jusqu'au stop. Dès qu'une source interne est matérialisée, le pipeline cible devient :
+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 :
 
 ```text
-acquiert les nouvelles transactions disponibles
-hydrate les signaux live incomplets si nécessaire
-normalise puis persiste RawTransaction + observations
-publie ses snapshots latest-value indépendamment de leurs lecteurs
-continue jusqu'à stop ou fault
+Yellowstone Transaction / TransactionStatus / Block
+    -> signaux transactionnels source-neutral
+    -> coalescence bornée (network, signature, commitment)
+    -> HTTP getTransaction observed
+    -> Common RAW
+    -> admission centrale
+    -> Store
+
+Yellowstone BlockMeta / Slot
+    -> continuité run-local uniquement
 ```
 
-Le Worker peut ensuite utiliser **WS, Yellowstone gRPC, HTTP, block polling, provider streams ou sources EARLY** si ces capacités servent l'acquisition live. Ces sources restent internes au Worker ; le caller ne pousse pas directement des ingress dans sa queue privée.
+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.
 
 Il ne lance pas de campagne historique arbitraire.
 
 ### 3.3 Continuité Worker ≠ Backfill
 
-Le Worker peut utiliser un replay ou HTTP pour **réparer une perte de continuité apparue pendant son acquisition active** :
+La continuité du Worker reste limitée au run courant. Le moteur Yellowstone de Transport possède le reconnect et peut réémettre une demande `from_slot` à partir de son high-watermark observé ; le Worker ne choisit pas lui-même ce slot et ne traite pas directement `SubscribeReplayInfo`.
+
+Les notions restent séparées :
 
 ```text
-stream actif
-    -> gap détecté
-    -> replay from_slot / HTTP hydration / block recovery
-    -> frontier live restauré
-    -> reprise du flux
+Transport last_observed_slot       = high-watermark du stream observé
+Worker processing_frontier_slot   = travail source observé et non bloqué par un pending plus ancien
+Store durable                     = persistence des acquisitions admises
+blockchain completeness           = non prouvée par les métriques ci-dessus
 ```
 
-Cette réparation reste liée au frontier du Worker et ne transforme pas le Worker en moteur historique.
+Une tentative de replay ne prouve ni succès ni continuité parfaite. Si Transport prouve qu'un slot demandé est antérieur à `first_available`, son compteur de continuity gap augmente ; le Worker projette ce gap puis termine avec un fault `source_failed`.
 
-Inversement :
+Il n'existe pas de délégation automatique vers Backfill :
 
 ```text
-« récupère les transactions du programme X depuis le slot Y »
-« récupère les 100 000 dernières signatures de cette adresse »
-« rejoue cette plage d'archive »
+gap de rétention prouvé
+    -> Worker fault/stop
+    -> aucun lancement de campagne historique
 ```
 
-sont des campagnes Job Backfill.
+Inversement, une demande telle que « récupère les transactions du programme X depuis le slot Y » reste une campagne `ksp-job-backfill-lib`.
 
 ### 3.4 Absence de relation Job ↔ Worker
 
@@ -657,13 +663,13 @@ ksp-worker-raw-transaction-ingest-lib ---> ksp-raw-transaction-lib ----> ksp-sto
 ksp-job-backfill-lib --------------------> ksp-store-lib
 ksp-worker-raw-transaction-ingest-lib ---> ksp-store-lib
 ksp-job-backfill-lib --------------------> ksp-onchain-transport-lib
-ksp-worker-raw-transaction-ingest-lib -X-> ksp-onchain-transport-lib   # aucun adapter live productif encore
+ksp-worker-raw-transaction-ingest-lib ---> ksp-onchain-transport-lib   # Yellowstone + HTTP hydration
 
 aucun edge Job <-> Worker
 aucun edge Transport <-> ksp-raw-transaction-lib
 ```
 
-Les tranches live suivantes peuvent matérialiser l'edge Worker -> Transport lorsqu'un adapter source productif le nécessite ; cet edge n'appartient pas à la fondation source-neutral.
+L'edge Worker -> Transport est désormais productif, mais reste strictement contenu dans le Worker concret. `ksp-worker-api`, Common RAW et Store API ne gagnent aucune connaissance Transport/provider.
 
 La migration doit préserver exactement les golden bytes/hash RAW v1 déjà prouvés. Aucun RAW v2 n'est justifié.
 
@@ -713,13 +719,13 @@ Yellowstone Transaction/Block -> signal structuré + transaction wire fidèle
 RAW v1 complet                -> hydration HTTP avant persistence
 ```
 
-Aucun adapter productif n'est ajouté par la qualification cross-source. Conformément à `TR-C2`, l'adapter `Transport DTO -> common` demeure réservé au Worker concret. La fondation `0.3.11` est désormais matérialisée sans Transport ; le premier adapter productif reste donc une responsabilité des tranches live suivantes.
+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. Handoff fondation Worker `0.3.11` vers live `0.3.12` à `0.3.14`
+## 14. État du Worker live après `0.3.12`
 
-### 14.0 État fermé par la fondation source-neutral
+### 14.0 Verticale matérialisée
 
-La fondation du Worker est matérialisée avec :
+La verticale productive possède :
 
 ```text
 consumer de ksp-worker-api
@@ -727,26 +733,33 @@ settings réseau/Worker bornés
 start/stop sur runtime Tokio caller-owned
 supervision privée des tâches
 mpsc central borné + backpressure
+une source Yellowstone standard caller-composed
+Transaction / TransactionStatus / Block -> signaux transactionnels
+BlockMeta / Slot -> continuity-only
+coalescence bornée par network/signature/commitment
+HTTP getTransaction observed pour hydration
 canonicalisation et assembly via ksp-raw-transaction-lib
-observation key déterministe
 persistence atomique via ksp-store-lib en mode Normal
-concurrence Store bornée
-snapshots concrete + projection WorkerSnapshotSource
-faults Store/content/source/counter classifiés
+processing frontier run-local bornée
+projection source Active/Reconnecting/Closing/Closed/Failed
+observation des compteurs reconnect/replay/gap Transport
+fault sur gap de rétention prouvé
 shutdown deadline + abort/join sans tâche orpheline
 ```
 
-Elle ne possède encore :
+Elle conserve explicitement les frontières suivantes :
 
 ```text
-aucun adapter HTTP/WS/Yellowstone productif
-aucun edge ksp-onchain-transport-lib
-aucune lecture Config
+aucune lecture Config dans le Worker
+aucun backend Store physique
 aucune API publique d'enqueue/source registration
-aucun replay/gap-repair live
+aucun checkpoint persistant de processing frontier
+aucun appel Worker -> ksp-job-backfill-lib
+aucune campagne historique automatique sur continuity gap
+aucun client reqwest/tonic/proto direct hors façade Transport
 ```
 
-Cette frontière est volontaire : les tranches live ajoutent des sources au supervisor existant au lieu d'introduire un second runtime ou une API d'admission publique.
+Le replay reconnect est Transport-owned. La processing frontier ne constitue pas une preuve de complétude durable ou blockchain.
 
 ### 14.1 Contrat fonctionnel
 
@@ -755,12 +768,12 @@ Cette frontière est volontaire : les tranches live ajoutent des sources au supe
 ```text
 être un consumer de ksp-worker-api
 être démarré/arrêté sans requête historique métier
-ouvrir les sources activées par Config
+recevoir des ressources déjà composées par la couche supérieure
 acquérir à partir du démarrage
-supporter plusieurs sources simultanées
 normaliser et persister RawTransaction + observations
 publier snapshots/notifications concrètes Worker
-réparer seulement ses propres pertes de continuité live
+laisser reconnect/from_slot/replay au Transport
+fault proprement lorsqu'un gap de rétention est prouvé
 ```
 
 Il ne doit pas :