v0.0.3-pre.006

docs/architecture/005-DEPENDENCY_GRAPH.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Graphe de dépendances KSP
 
@@ -349,11 +349,23 @@ ksp-materializer-lib
     -> ksp-core-lib
 ```
 
-`ksp-interface-lib` peut être consommée par `ksp-materializer-lib` lorsqu'une matérialisation a réellement besoin d'un contrat wire déjà possédé par KSP, mais ne doit pas devenir une dépendance obligatoire de toute matérialisation.
+`ksp-interface-lib` peut être consommée par une implémentation de materializer lorsqu'un contrat wire officiel est réellement requis, sans devenir une dépendance obligatoire de l'API.
 
-## Décision importante
+## Capacités
 
-Ni `ksp-materializer-api` ni `ksp-materializer-lib` ne dépendent du store.
+`ksp-materializer-api` doit permettre de distinguer conceptuellement :
+
+```text
+GenericMaterializer
+    D2 runtime/Core -> output générique D3
+
+DomainProjector
+    D3/canonical inputs -> output spécialisé D4
+```
+
+Les noms exacts ne sont pas figés.
+
+## Indépendance du Store
 
 ```text
 ksp-materializer-api -X-> ksp-store-api
@@ -361,9 +373,9 @@ ksp-materializer-lib -X-> ksp-store-api
 ksp-materializer-lib -X-> ksp-store-lib
 ```
 
-Une matérialisation transforme des données ; le worker/job/pipeline spécialisé persiste le résultat.
+Un materializer transforme ; un worker/job/pipeline spécialisé convertit son output vers le DTO Store et le persiste.
 
-Cette séparation permet également de tester un materializer externe sans PostgreSQL.
+Une implémentation externe peut produire un output générique D3 sans migration PostgreSQL spécialisée.
 
 ---
 
@@ -376,13 +388,24 @@ ksp-store-api
 ksp-store-lib
     -> ksp-store-api
     -> ksp-core-lib
+    -> ksp-config-lib
+    -> ksp-logging-lib
 ```
 
-`ksp-store-lib` peut dépendre de config/logging et contient PostgreSQL comme implémentation de référence.
+PostgreSQL est l'implémentation de référence.
 
-## Indépendance du store
+## Niveaux durables
 
-Le store ne dépend pas des implémentations Program/Materializer/Transport :
+```text
+D1 Raw
+D2 Core canonique
+D3 journal de matérialisation générique
+D4 projections spécialisées
+```
+
+`ksp-store-api` possède les contrats persistants de ces niveaux sans dépendre des modèles runtime de Program/Materializer/Transport.
+
+Interdictions :
 
 ```text
 ksp-store-api -X-> ksp-program-api
@@ -394,33 +417,46 @@ ksp-store-lib -X-> ksp-materializer-lib
 ksp-store-lib -X-> ksp-onchain-transport-lib
 ```
 
-`ksp-store-api` définit les DTO/contrats persistants nécessaires aux niveaux durables sans imposer les modèles runtime des processors.
+Les composants de composition réalisent les conversions explicites.
 
-## Notifications de données persistées
+## Replay
 
-`ksp-store-api` est retenu comme propriétaire du contrat canonique de notification lorsqu'il signifie :
+Les frontières de replay restent indépendantes :
 
-> une donnée persistée de telle catégorie est disponible.
+```text
+D1 -> D2
+D2 -> D3
+D3 -> D4
+```
 
-Le même contrat est utilisé quelle que soit l'origine :
+Les jobs de replay consomment le Store et les processors appropriés ; ils ne sont pas des modes des workers live.
+
+## Notifications persistées
+
+`ksp-store-api` possède le contrat canonique de notification lorsqu'une donnée durable est disponible.
 
 ```text
 live worker ----\
-backfill job ----+--> persisted data notification
+backfill job ----+--> PersistedDataAvailable (nom conceptuel)
 import ----------/
+replay ----------/
 ```
 
-Le mécanisme de diffusion reste hors du contrat :
+La notification est un signal de réveil et peut être perdue ou dupliquée.
+
+Le consumer reconstruit toujours son backlog via le Store, les versions de processor et les marqueurs d'idempotence.
+
+L'ordre est :
 
 ```text
-channel
-LISTEN/NOTIFY
-IPC
-broker
-...
+persist
+commit
+notify
 ```
 
-Le mode de transport concret sera détaillé en `pre.005`.
+Le payload privilégie une référence durable compacte.
+
+Le mécanisme concret peut être channel, PostgreSQL LISTEN/NOTIFY, IPC ou broker. Le choix détaillé est reporté à `pre.007`.
 
 ---
 
@@ -474,7 +510,7 @@ Un futur orchestrateur peut utiliser workers et jobs séparément sans créer de
 
 Les dépendances ci-dessous décrivent la composition attendue. Les détails de processus/IPC seront approfondis plus tard.
 
-## `ksp-worker-raw-retriever`
+## `ksp-worker-raw-retriever` — transport -> D1
 
 ```text
 ksp-worker-raw-retriever
@@ -509,9 +545,9 @@ ksp-job-backfill
     -> ksp-logging-lib
 ```
 
-Il utilise la même famille de DTO raw persistants et la même notification de données persistées que W1.
+Il produit exactement la même famille de DTO D1 persistants et la même notification de données persistées que le worker live.
 
-## `ksp-worker-core-processor`
+## `ksp-worker-core-processor` — D1 -> D2
 
 ```text
 ksp-worker-core-processor
@@ -541,7 +577,7 @@ store Core DTO
 
 `ksp-program-lib` ne connaît donc pas le store.
 
-## `ksp-worker-generic-materializer`
+## `ksp-worker-generic-materializer` — D2 -> D3
 
 ```text
 ksp-worker-generic-materializer
@@ -554,9 +590,9 @@ ksp-worker-generic-materializer
     -> ksp-logging-lib
 ```
 
-La frontière exacte des entrées/sorties génériques sera détaillée en `pre.005`.
+Il consomme le backlog D2, appelle la capacité de matérialisation générique puis persiste le journal D3. La notification éventuelle accélère le traitement mais ne remplace pas la query de backlog.
 
-## `ksp-worker-domain-projector`
+## `ksp-worker-domain-projector` — D3 -> D4
 
 ```text
 ksp-worker-domain-projector
@@ -571,7 +607,7 @@ ksp-worker-domain-projector
 
 Son nom reste provisoire.
 
-Il est propriétaire de la composition entre résultats de matérialisation spécialisée et projections persistantes par domaine ; `ksp-materializer-lib` reste indépendant du backend.
+Il est propriétaire de la composition entre D3, la projection/materialisation spécialisée et les DTO D4 persistants ; `ksp-materializer-lib` reste indépendant du backend. D4 est organisé par faits canoniques plutôt que par familles de tables propres aux protocoles.
 
 ---