v0.0.3-pre.007

docs/rules/RULES_DEPENDENCIES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_DEPENDENCIES.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Règles des dépendances KSP
 
@@ -78,11 +78,25 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
 - **DEP-TRANSPORT-003** — Les modèles de transport ne réalisent pas de décodage métier/protocolaire et doivent rester facilement convertibles en DTO raw persistants.
 - **DEP-TRANSPORT-004** — Aucun `ksp-onchain-transport-api` ou `ksp-offchain-transport-api` global n'est créé dans l'architecture actuelle.
 
+## Pipelines spécialisés
+
+- **DEP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
+- **DEP-PIPE-002** — Les pipelines spécialisés retenus pour les frontières durables sont `ksp-pipeline-raw-ingestion-lib`, `ksp-pipeline-core-processing-lib`, `ksp-pipeline-generic-materialization-lib` et `ksp-pipeline-domain-projection-lib`.
+- **DEP-PIPE-003** — Un pipeline de processing dépend des APIs nécessaires à sa frontière et non des implémentations officielles correspondantes lorsque l'API permet l'injection/composition.
+- **DEP-PIPE-004** — Les pipelines spécialisés ne dépendent pas de `ksp-worker-api` ou `ksp-job-api`; worker et job possèdent le lifecycle.
+- **DEP-PIPE-005** — Worker live et job de replay/backfill réutilisent le même pipeline pour une même frontière durable afin d'éviter la duplication de logique.
+- **DEP-PIPE-006** — Le pipeline raw ingestion peut dépendre des modèles homogènes de `ksp-onchain-transport-lib` et de `ksp-store-api`, mais pas de `ksp-store-lib`.
+- **DEP-PIPE-007** — Le pipeline Core processing dépend de `ksp-program-api` et non de `ksp-program-lib`.
+- **DEP-PIPE-008** — Les pipelines de matérialisation/projection dépendent de `ksp-materializer-api` et non de `ksp-materializer-lib`.
+
 ## Worker / Job lifecycle
 
 - **DEP-WORKER-001** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et ne dépend pas de `ksp-job-api`.
+- **DEP-WORKER-002** — Les workers de processing reconstruisent leur backlog depuis `ksp-store-api`/Store ; une notification ne suffit pas à prouver qu'un input a été traité.
+- **DEP-WORKER-003** — Les workers concrets peuvent dépendre de `ksp-store-lib` et des implémentations officielles Program/Materializer nécessaires à la composition.
 - **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`.
 - **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
+- **DEP-JOB-003** — Les jobs de replay réutilisent les pipelines des workers correspondants au lieu de dupliquer la logique D1 -> D2, D2 -> D3 ou D3 -> D4.
 
 ## Propriété des dépendances Solana
 

docs/rules/RULES_KSP.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_KSP.md -->
-<!-- version: 10 -->
+<!-- version: 11 -->
 
 # Règles spécifiques à KSP
 
@@ -14,6 +14,7 @@
 - **KSP-NAME-007** — Une démonstration se termine par `-demo`.
 - **KSP-NAME-008** — Les crates Rust sont placées directement sous `crates/`.
 - **KSP-NAME-009** — Une application desktop de scénario spécialisée suit la forme `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
+- **KSP-NAME-010** — Un pipeline spécialisé réutilisable se nomme `ksp-pipeline-<role>-lib`; aucun `ksp-pipeline-lib` générique n'est créé.
 
 ## Architecture et APIs
 
@@ -83,6 +84,18 @@
 - **KSP-MAT-003** — Une extension externe de materializer doit pouvoir produire du D3 générique sans migration PostgreSQL spécialisée.
 - **KSP-MAT-004** — Une nouvelle projection relationnelle D4 exige explicitement un contrat Store/migration/backend correspondant ; cette responsabilité n'est pas cachée dans `ksp-materializer-api`.
 
+
+## Backlog, claims et reprise
+
+- **KSP-PROC-001** — Le backlog est défini relativement à l'identité/version/capability du processor et non par simple absence d'une row de sortie.
+- **KSP-PROC-002** — Une nouvelle version de processor peut rendre de nouveau candidat un input déjà terminal pour une version précédente.
+- **KSP-PROC-003** — Un input peut avoir plusieurs outcomes indépendants lorsqu'il est candidat pour plusieurs materializers/projectors.
+- **KSP-PROC-004** — Les claims sont temporaires ; une lease expirée après crash rend le candidat de nouveau traitable.
+- **KSP-PROC-005** — Les erreurs transitoires utilisent retry/backoff borné ; les failures déterministes doivent pouvoir devenir un état durable afin d'éviter une boucle infinie.
+- **KSP-PROC-006** — Unsupported/NotApplicable ne sont pas nécessairement des erreurs et constituent des outcomes terminaux pour la version/capability concernée.
+- **KSP-PROC-007** — Les consumers combinent wake-up par notification et polling périodique du backlog.
+- **KSP-PROC-008** — Un backlog downstream croissant n'entraîne pas automatiquement le ralentissement du raw retriever ; une éventuelle backpressure globale appartient à une policy/configuration/orchestration supérieure.
+
 ## Notifications de données persistées
 
 - **KSP-NOTIFY-001** — `ksp-store-api` possède le format canonique d'une notification signalant qu'une donnée persistée est disponible.
@@ -102,6 +115,10 @@
 - **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
 - **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
 - **KSP-WORKER-008** — Les workers de processing actuellement retenus sont `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`; le dernier nom reste provisoire.
+- **KSP-WORKER-009** — Les workers de processing utilisent notification comme wake-up mais reconstruisent leur backlog depuis le Store.
+- **KSP-WORKER-010** — `ksp-worker-raw-retriever` distingue une configuration desired et une configuration effective lors des reconfigurations à chaud.
+- **KSP-WORKER-011** — Un cursor de scan est une optimisation ; les processing outcomes durables constituent la preuve qu'un input a été traité pour un processor/version/capability.
+- **KSP-WORKER-012** — La concurrence de processing utilise une sémantique de claim/lease récupérable après expiration/crash.
 
 ## Jobs
 
@@ -113,6 +130,10 @@
 - **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
 - **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
 - **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
+- **KSP-JOB-009** — Les jobs de replay retenus sont `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`.
+- **KSP-JOB-010** — Les jobs de replay réutilisent exactement le pipeline spécialisé de la frontière correspondante.
+- **KSP-JOB-011** — Le backfill conserve un checkpoint de progression dans la source historique en plus des outcomes de persistence D1.
+- **KSP-JOB-012** — Replay normal/reprise et force replay sont deux intentions distinctes ; un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.
 
 ## Matérialisation et persistence
 
@@ -130,7 +151,13 @@
 
 ## Pipelines et scénarios
 
-- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique. Les pipelines sont introduits séparément à la demande selon leur responsabilité réelle.
+- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
+- **KSP-PIPE-002** — Les quatre pipelines spécialisés retenus pour les frontières durables sont raw ingestion, Core processing, generic materialization et domain projection.
+- **KSP-PIPE-003** — Un pipeline spécialisé contient la logique réutilisable d'une frontière mais aucun lifecycle worker/job.
+- **KSP-PIPE-004** — Les pipelines utilisent les APIs Program/Materializer/Store lorsque ces frontières doivent être injectables ; les implémentations officielles sont composées par workers/jobs.
+- **KSP-PIPE-005** — Le traitement est at-least-once avec persistence idempotente et outcomes durables, plutôt qu'une promesse exactly-once distribuée.
+- **KSP-PIPE-006** — Un traitement valide produisant zéro output possède malgré tout un outcome terminal explicite tel que NoOutput/NotApplicable/Unsupported selon la sémantique finale.
+- **KSP-PIPE-007** — Outputs obligatoires et processing outcome d'une unité logique sont atomiques du point de vue durable.
 - **KSP-SCENARIO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
 - **KSP-SCENARIO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
 - **KSP-SCENARIO-003** — `ksp-scenario-api` n'est pas retenu actuellement ; KSP privilégie d'abord une norme documentaire/structurelle commune qui ne limite pas les contrats spécifiques des scénarios.