208 lines
5.3 KiB
Markdown
208 lines
5.3 KiB
Markdown
<!-- 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.
|