# ksp-job-backfill-lib `ksp-job-backfill-lib` implémente le premier job historique concret de KSP : un backfill borné de transactions Solana vers la couche RAW durable. La crate compose les contrats Job, Transport observé, common RAW et Store backend-neutral sans posséder leurs politiques internes. Elle couvre l'admission, la découverte historique, l'hydratation `getTransaction`, l'adaptation vers `ksp-raw-transaction-lib`, la persistance atomique, la concurrence bornée, la frontier contiguë, le checkpoint caller-owned, l'annulation coopérative et les snapshots latest-value. ## Identité L'identité logique d'une transaction reste : ```text (RawNetworkId, RawTransactionSignature) ``` Le rôle HTTP, le provider, l'endpoint et le protocole ne font pas partie de cette identité. Ils décrivent la sélection et/ou la provenance d'acquisition. Le fingerprint d'un scope est déterministe sur sa sémantique de découverte et son réseau ; il n'intègre pas `JobId`, provider, endpoint, protocole ou rôle Transport. ## Scopes Quatre scopes sont exposés : ```text LatestAddress BeforeAddress AfterAddress ExplicitSignatures ``` La requête borne explicitement page size, nombre de pages, nombre de candidats et concurrence d'hydratation. Les signatures explicites sont dédupliquées de façon stable à la première occurrence. ## Hydratation et RAW v1 L'hydratation passe uniquement par la voie observée de `ksp-onchain-transport-lib`. Un résultat disponible produit en mémoire : - un `RawTransaction` canonique ; - une `RawTransactionObservation` liée à la même référence logique ; - une provenance contenant le provider et l'endpoint réellement gagnants ; - un payload JSON canonique `ksp.solana.raw_transaction`, version `1` ; - un digest SHA-256 des bytes canoniques. Un `getTransaction = null` devient `BackfillHydrationOutcome::Missing` et ne fabrique ni payload ni provenance. ## Persistance La persistance utilise exclusivement `ksp-store-lib` avec `default-features = false` côté dépendance de crate : ```text ksp-job-backfill-lib -> ksp-store-lib -X-> backend imposé par le job ``` Le chemin d'écriture est l'acquisition atomique `RawTransaction + RawTransactionObservation` en mode normal. La crate distingue insertion, déjà présent, tombstone purgé, observation nouvelle/existante, missing et conflit. Un conflit de contenu n'est jamais converti en succès idempotent. ## Concurrence et checkpoint L'exécution maintient au plus `hydration_concurrency` candidats actifs. Les terminaisons hors ordre sont réconciliées par index stable ; le checkpoint n'avance que sur un préfixe **contigu** d'outcomes durablement sûrs. `BackfillCheckpoint` est opaque et caller-owned. Il lie : ```text JobId scope fingerprint completed contiguous prefix private Before resume cursor ``` La crate ne persiste pas elle-même ce checkpoint. Une reprise crash-safe durable nécessite donc que le caller choisisse explicitement où conserver le checkpoint retourné. ## Runtime et annulation `BackfillJobRuntime` est un coordinator single-run. `BackfillJobHandle` peut être cloné pour : - demander une annulation coopérative ; - lire l'état de cette demande ; - obtenir une source latest-value indépendante. L'annulation arrête l'admission de nouveau travail et peut interrompre certaines attentes pré-Store. Une persistance Store déjà soumise est toujours drainée avant publication terminale. Les snapshots exposent uniquement des compteurs, phases, boundary, checkpoint et code d'échec sûrs ; ils ne contiennent ni payload RAW, ni URL/credential Transport. ## Dépendances Les dépendances normales sont : ```text ksp-core-lib ksp-job-api ksp-logging-lib ksp-onchain-transport-lib ksp-raw-transaction-lib ksp-store-lib (default-features = false) futures-util serde_json sha2 tokio (macros + sync, détail runtime privé) ``` La crate ne dépend pas de Config, `ksp-store-api` directement, `ksp-store-postgres-lib` ni d'un SDK provider. ## Hors périmètre La crate ne possède pas : - application desktop ou CLI ; - Worker API / worker live ; - retry, pacing ou sélection d'endpoint Transport ; - backend Store concret ; - decoding Program ou matérialisation CORE/DECODE/SPECIALIZED ; - table dédiée de checkpoint ; - control plane Job générique. ## Documentation - [`USAGE.md`](USAGE.md) — construction des scopes/requêtes, runtime, snapshots et reprise ; - [`../ksp-job-api/README.md`](../ksp-job-api/README.md) — contrats Job runtime-neutral ; - [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) — architecture durable acquisition/jobs ; - [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — frontière RAW/Store.