v0.3.6-pre.012

docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->
 
 # Acquisition, workers, jobs et pipelines spécialisés
 
@@ -78,12 +78,17 @@ D1 RAW
 
 Le job :
 
-- utilise `ksp-job-api` pour son lifecycle ;
-- gère scope/range/pagination/checkpoint ;
-- porte explicitement le réseau logique du Store dans le scope et dans l'identité de chaque transaction candidate ;
-- traite rôle HTTP, provider, endpoint et protocole comme sélection/provenance d'acquisition, jamais comme identité transactionnelle ;
-- n'effectue aucun décodage Program ;
-- n'écrit pas directement des faits CORE/DECODE/SPECIALIZED.
+- utilise `ksp-job-api` pour identité, lifecycle, annulation abstraite et observation latest-value ;
+- expose `LatestAddress`, `BeforeAddress`, `AfterAddress` et `ExplicitSignatures` avec bornes explicites de pages/candidats/concurrence ;
+- porte explicitement le réseau logique du Store dans le scope et dans l'identité `(network, signature)` de chaque transaction candidate ;
+- exclut rôle HTTP, provider, endpoint et protocole du fingerprint sémantique et de l'identité transactionnelle ;
+- hydrate uniquement via la voie observée `getTransaction`, afin de conserver la provenance du provider/endpoint réellement gagnant ;
+- produit un RAW v1 canonique déterministe puis persiste transaction + observation atomiquement via `ksp-store-lib` en mode normal ;
+- respecte les tombstones `Purged`, distingue missing/conflit/idempotence et ne pré-lit pas le Store avant hydratation ;
+- limite les hydrations concurrentes, avance seulement une frontier contiguë durable et retourne un checkpoint opaque caller-owned ;
+- arrête coopérativement les nouvelles admissions lors d'une annulation et draine une persistence Store déjà soumise ;
+- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
+- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
 
 ### Worker RAW live
 
@@ -240,31 +245,27 @@ Une capability comme `reconfigure` n'est pas imposée à tous les workers.
 
 ## Job API
 
-`ksp-job-api` reste distinct de Worker API.
+`ksp-job-api` reste distinct de Worker API et volontairement runtime-neutral.
 
-Concepts candidats :
+Contrats communs actuels :
 
 ```text
 JobId
-JobDescriptor
+JobKindCode
 JobState
-JobProgress
-JobOutcome
-JobCapabilities
+JobCompletion
+JobLifecycle
+JobCancellationToken
+JobNotificationSequence
+JobNotification<Snapshot>
+JobSnapshotSource
 ```
 
-Un job est borné/terminable et peut exposer selon besoin :
+Le lifecycle commun est borné aux transitions explicitement validées entre `Created`, `Running`, `Cancelling` et les états terminaux `Completed(Complete|Partial)`, `Cancelled`, `Failed`. Il ne définit ni `pause`, ni `resume`, ni scheduler, ni runtime d'exécution générique.
 
-```text
-start
-pause
-resume
-cancel
-status
-progress
-```
+`JobSnapshotSource` suit une sémantique latest-value : un listener lit une valeur complète courante puis peut attendre une séquence plus récente ; les valeurs intermédiaires peuvent être coalescées. Le snapshot métier reste possédé par le job concret.
 
-Les types exacts sont décidés à `0.3.6` avec le premier vrai backfill, après clôture des trois slices Store/PostgreSQL `0.3.2`–`0.3.4` et de la tranche Interface `0.3.5`.
+L'annulation commune est une intention coopérative. Le job concret décide quelles attentes peuvent être interrompues et quelles opérations engagées doivent être drainées.
 
 Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
 
@@ -309,15 +310,11 @@ Les états exacts seront définis avec le premier processor durable, mais doiven
 
 ## Reprise après crash
 
-Un worker/job doit reconstruire son état depuis :
+Un worker/job qui promet une reprise après crash doit reconstruire son état depuis des données durables : inputs persistés, claims/leases/outcomes lorsqu'ils existent, cursors/checkpoints et versions de processor.
 
-- inputs persistés ;
-- claims/leases ;
-- outcomes ;
-- cursors/checkpoints ;
-- versions de processor.
+Le premier backfill RAW retourne un `BackfillCheckpoint` caller-owned lié au `JobId` et au fingerprint de scope. La crate ne persiste pas ce checkpoint elle-même : tant qu'un caller ne l'enregistre pas durablement, il s'agit d'une primitive de reprise contrôlée, pas d'une promesse crash-safe automatique.
 
-La mémoire du processus ne constitue jamais l'unique source de reprise.
+La mémoire du processus ne constitue jamais l'unique source d'une garantie de reprise durable.
 
 ## Logging
 
@@ -346,7 +343,9 @@ ksp-job-backfill-lib
     -> ksp-core-lib
     -> ksp-logging-lib
     -> ksp-onchain-transport-lib
-    -> ksp-store-lib       # façade Store ; aucun backend imposé par la crate Job
+    -> ksp-store-lib       # façade Store ; default-features=false côté Job
+    -> futures-util/tokio  # runtime privé de Backfill
+    -> serde_json/sha2     # RAW v1 canonique + digest
 ```
 
 ### RAW worker
@@ -393,8 +392,7 @@ selon les capacités réellement introduites.
 
 - nom final de la crate pipeline RAW si la réutilisation justifie une crate dédiée ;
 - nom final du worker RAW ;
-- contrat exact de `ksp-job-api` ;
-- modèle de claim/lease PostgreSQL ;
+- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
 - taille de batch et stratégie backpressure ;
 - découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
 - mécanisme IPC des applications de contrôle futures.