v0.0.3-pre.007

deltas/0.0.3/pre.007.md

@@ -0,0 +1,207 @@
+<!-- file: deltas/0.0.3/pre.007.md -->
+<!-- version: 1 -->
+
+# Delta 0.0.3-pre.007
+
+## Base requise
+
+`v0.0.3-pre.006`.
+
+## Objectif
+
+Formaliser le modèle opérationnel des acquisitions et traitements continus/ponctuels au-dessus des niveaux durables D1–D4, sans encore ouvrir les apps/managers/IPC.
+
+## Version Cargo
+
+`workspace.package.version` passe de :
+
+```text
+0.0.3-pre.6
+```
+
+à :
+
+```text
+0.0.3-pre.7
+```
+
+Le header de `Cargo.toml` passe de version 12 à 13.
+
+## Fichiers ajoutés
+
+- `docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`
+- `deltas/0.0.3/pre.007.md`
+
+## Fichiers modifiés
+
+- `Cargo.toml`
+- `ROADMAP.md`
+- `docs/architecture/000-README.md`
+- `docs/architecture/003-COMPONENT_CONTRACTS.md`
+- `docs/architecture/004-COMPONENT_INVENTORY.md`
+- `docs/architecture/005-DEPENDENCY_GRAPH.md`
+- `docs/rules/RULES_DEPENDENCIES.md`
+- `docs/rules/RULES_KSP.md`
+- `docs/IDEAS.md`
+- `docs/plans/001-V0_0_3_PLAN.md`
+- `prompts/001-V0_1_X_START_PROMPT.md`
+
+## Fichiers supprimés
+
+Aucun.
+
+## Décisions principales
+
+### Pipelines spécialisés
+
+Le besoin concret de mutualiser exactement la même frontière entre worker live et job justifie quatre crates :
+
+```text
+ksp-pipeline-raw-ingestion-lib
+ksp-pipeline-core-processing-lib
+ksp-pipeline-generic-materialization-lib
+ksp-pipeline-domain-projection-lib
+```
+
+Aucun `ksp-pipeline-lib` monolithique n'est introduit.
+
+Les pipelines dépendent des APIs nécessaires, pas des implémentations officielles lorsqu'une injection est possible :
+
+```text
+raw ingestion        -> onchain transport models + store-api
+core processing      -> program-api + store-api
+generic materialize  -> materializer-api + store-api
+domain projection    -> materializer-api + store-api
+```
+
+Workers/jobs composent ensuite `ksp-store-lib`, `ksp-program-lib`, `ksp-materializer-lib` ou des implémentations externes compatibles.
+
+### Workers
+
+Workers retenus :
+
+```text
+ksp-worker-raw-retriever
+ksp-worker-core-processor
+ksp-worker-generic-materializer
+ksp-worker-domain-projector
+```
+
+`ksp-worker-api` reste une lifecycle API continue.
+
+Le raw retriever supporte la hot reconfiguration et distingue configuration desired/effective.
+
+### Jobs
+
+Jobs de données retenus :
+
+```text
+ksp-job-backfill
+ksp-job-replay-core
+ksp-job-replay-generic-materialization
+ksp-job-replay-domain-projection
+```
+
+`ksp-job-api` reste séparé de Worker et aucune `ksp-job-control-lib` n'est créée.
+
+### Backlog et outcomes
+
+L'absence d'output ne signifie pas qu'un input est pending.
+
+Le backlog est relatif à :
+
+```text
+input
+processor identity
+processor version
+capability/materializer/projector
+```
+
+Chaque traitement possède un outcome durable, y compris pour NoOutput/NotApplicable/Unsupported selon les types finaux.
+
+Une nouvelle version de processor peut créer un nouveau travail pour un input déjà terminal sous l'ancienne version.
+
+### Claim / lease
+
+La concurrence multi-instance utilise une ownership temporaire par claim/lease.
+
+Une lease expirée après crash rend l'input de nouveau claimable.
+
+Le détail SQL est reporté à l'implémentation PostgreSQL.
+
+### At-least-once
+
+Sémantique retenue :
+
+```text
+at-least-once processing
++
+idempotent durable persistence
++
+durable processing outcomes
+```
+
+Aucune promesse exactly-once distribuée n'est recherchée.
+
+### Atomicité
+
+Outputs obligatoires et processing outcome d'une même unité logique doivent être cohérents/atomiques du point de vue durable.
+
+### Reprise
+
+Après restart, worker/job recharge configuration/scope, laisse expirer/récupère les claims, requête le backlog Store et reprend.
+
+Un cursor est une optimisation, pas la preuve de completion.
+
+### Replay
+
+Replay normal/reprise et force replay sont distincts.
+
+Un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.
+
+### Notifications
+
+PostgreSQL `LISTEN/NOTIFY` est retenu comme mécanisme initial de référence de wake-up, sans garantie de backlog.
+
+Chaque consumer combine :
+
+```text
+notification wake-up
++
+periodic polling
+```
+
+Le Store reste la source de vérité.
+
+### Batching / backpressure
+
+Batch size, concurrence, poll interval, retry/backoff et lease duration sont des paramètres spécialisés, pas nécessairement des propriétés universelles de Worker/Job API.
+
+Un backlog downstream croissant est observable mais ne ralentit pas automatiquement l'acquisition D1.
+
+## Plan
+
+- `pre.008` — apps/managers/scenarios/processus/IPC/orchestration ;
+- `pre.009` — releases fonctionnelles concrètes ;
+- `pre.010` — clôture fondatrice.
+
+## Questions reportées
+
+- schéma SQL de claim/lease ;
+- durée/renouvellement de lease ;
+- types exacts des processing outcomes ;
+- contexte stateful des projectors ;
+- graceful shutdown d'un batch ;
+- pause/resume générique ou capability de job ;
+- télémétrie/metrics au-delà des logs et health.
+
+## Validations
+
+- headers `file:` / `version:` vérifiés ;
+- `Cargo.toml` parsé et version `0.0.3-pre.7` vérifiée ;
+- référence vers `009-ACQUISITION_WORKERS_AND_JOBS.md` vérifiée ;
+- quatre pipelines spécialisés présents dans inventaire/règles ;
+- quatre workers et quatre jobs de données présents dans l'architecture ;
+- aucune dépendance pipeline vers `ksp-store-lib`, `ksp-program-lib` ou `ksp-materializer-lib` dans le graphe de pipeline ;
+- plan conservé jusqu'à `pre.010` ;
+- aucune commande Cargo build/test exécutée : ce delta reste documentaire.