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 à :

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 :

RawTransactionIngestWorker::start(settings, Arc<Store>)
    -> 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 :

vérifié contre le réseau attendu ;
canonicalisé exclusivement par ksp-raw-transaction-lib ;
associé à une observation key déterministe sous le domaine ksp.raw_transaction_ingest.observation.v1 ;
assemblé en acquisition RAW commune ;
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 :

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 :

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 :

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 :

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 — utilisation de la façade publique actuelle ;
../ksp-worker-api/README.md — contrats Worker génériques ;
../ksp-raw-transaction-lib/README.md — canonicalisation RAW commune ;
../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md — séparation Worker/Job ;
../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md — architecture d'acquisition RawTransaction.