# ksp-worker-raw-transaction-ingest-lib `ksp-worker-raw-transaction-ingest-lib` est le premier Worker concret de KSP pour l'alimentation continue de la couche RAW Transaction. La crate fournit la fondation runtime **source-neutral** du Worker : identité et settings bornés, lifecycle Start/Stop, admission privée bornée, canonicalisation via `ksp-raw-transaction-lib`, persistance backend-neutral via `ksp-store-lib`, supervision des tâches, shutdown borné et snapshots latest-value projetables sur `ksp-worker-api`. La fondation ne contient volontairement encore **aucune source réseau productive**. Elle ne dépend pas de `ksp-onchain-transport-lib` et n'expose pas d'API publique permettant au caller d'injecter directement des transactions dans la queue interne. Les adapters live/catch-up sont des responsabilités ultérieures du même Worker, pas de son API de fondation. ## Identité et réseau Une exécution est liée à : ```text RawNetworkId WorkerId Worker kind = raw_transaction_ingest ``` Le réseau logique doit être identique à celui du `Store` remis au démarrage. La transaction canonique conserve l'identité durable définie par la couche RAW commune ; le Worker n'ajoute ni provider, ni endpoint, ni protocole à cette identité. ## Runtime Le point d'entrée public est : ```text RawTransactionIngestWorker::start(settings, Arc) -> RawTransactionIngestHandle ``` Le démarrage est synchrone mais nécessite qu'un runtime Tokio courant appartienne déjà au caller. Le Worker ne crée pas de runtime global et n'expose aucun `JoinHandle` public. `RawTransactionIngestHandle` permet de : - demander un stop coopératif et idempotent ; - obtenir une source de snapshots concrets latest-value ; - utiliser cette même source via `WorkerSnapshotSource` ; - attendre le terminal après drain/abort+join des tâches possédées. La destruction du dernier handle de contrôle ferme aussi la voie de contrôle privée ; le runtime termine alors selon les mêmes règles de shutdown. ## Admission et Common RAW La queue centrale est un `tokio::sync::mpsc` privé borné par `admission_queue_capacity`. Les sources internes doivent subir la backpressure du channel ; aucune queue non bornée ni silent drop n'est autorisé. Chaque ingress admis est : 1. vérifié contre le réseau attendu ; 2. canonicalisé exclusivement par `ksp-raw-transaction-lib` ; 3. associé à une observation key déterministe sous le domaine `ksp.raw_transaction_ingest.observation.v1` ; 4. assemblé en acquisition RAW commune ; 5. remis à la persistence Store. La crate ne possède pas un second format RAW et ne duplique pas le canonicaliseur commun. ## Persistence Store La persistance passe uniquement par `ksp-store-lib` avec `default-features = false` dans la crate Worker. Aucun backend physique n'est imposé ou importé directement. L'écriture utilise le mode normal d'acquisition atomique `RawTransaction + RawTransactionObservation`. Les outcomes distingués sont notamment : ```text entity inserted entity already present entity skipped purged observation inserted observation already present observation not recorded for purged entity content conflict store failure ``` `persistence_concurrency` borne le nombre d'écritures Store simultanées. Un conflit de contenu est terminal et n'est jamais converti en succès idempotent. ## Shutdown et faults Le shutdown possède une deadline bornée par `shutdown_drain_timeout`. Avant publication terminale, le supervisor : - arrête les nouvelles admissions ; - signale le stop aux sources privées ; - draine le travail déjà admis tant que la deadline le permet ; - récolte les persistences et sources possédées ; - en cas de timeout, abort les tâches restantes puis les rejoint avant le terminal. Les codes d'erreur publics du Worker sont : ```text worker_raw_transaction_ingest.settings_invalid worker_raw_transaction_ingest.runtime_invalid worker_raw_transaction_ingest.store_failed worker_raw_transaction_ingest.content_conflict worker_raw_transaction_ingest.counter_exhausted worker_raw_transaction_ingest.source_failed worker_raw_transaction_ingest.drain_timeout ``` Les diagnostics ne recopient pas de payload RAW, URL, credential, signature hostile ou texte backend/provider arbitraire. ## Snapshots `RawTransactionIngestSnapshotSource` est latest-value. Les listeners peuvent rater des états intermédiaires mais obtiennent toujours une valeur complète et monotone par `WorkerSnapshotSequence`. Le snapshot concret expose notamment : ```text lifecycle / health / activity admission_queue_capacity / admission_queue_depth persistence_concurrency / in_flight_persistence admitted_total / canonicalized_total / persisted_total entity_inserted_total / entity_already_present_total / entity_skipped_purged_total observation_inserted_total / observation_already_present_total content_conflict_total / store_failure_total / source_failure_total backpressure_wait_total ``` Les compteurs ne wrapent jamais silencieusement. ## Dépendances Les dépendances normales sont exactement : ```text ksp-core-lib ksp-logging-lib ksp-raw-transaction-lib ksp-store-lib (default-features = false) ksp-worker-api sha2 tokio (macros, rt, sync, time) ``` La crate ne dépend pas de Config, Job, `ksp-store-api` directement, backend Store concret, Transport, Tauri ou SDK provider. ## Hors périmètre de la fondation source-neutral Cette surface ne possède pas encore : - adapter HTTP/WS/Yellowstone productif ; - sélection Config de sources/endpoints/credentials ; - discovery/hydration/replay de continuité live ; - hot reconfiguration de listeners/sources ; - application Desk ou process autonome ; - campagne historique/backfill ; - décodage STRUCTURAL/DECODED/DOMAIN. Ces extensions doivent conserver la séparation avec `ksp-job-backfill-lib` et réutiliser les mêmes contrats RAW/Store. ## Documentation - [`USAGE.md`](USAGE.md) — utilisation de la façade publique actuelle ; - [`../ksp-worker-api/README.md`](../ksp-worker-api/README.md) — contrats Worker génériques ; - [`../ksp-raw-transaction-lib/README.md`](../ksp-raw-transaction-lib/README.md) — canonicalisation RAW commune ; - [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) — séparation Worker/Job ; - [`../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`](../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md) — architecture d'acquisition RawTransaction.