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 :

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

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 :

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 :

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 :

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 — construction des scopes/requêtes, runtime, snapshots et reprise ;
../ksp-job-api/README.md — contrats Job runtime-neutral ;
../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md — architecture durable acquisition/jobs ;
../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md — frontière RAW/Store.