v0.0.3-pre.005

docs/architecture/005-DEPENDENCY_GRAPH.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Graphe de dépendances KSP
 
@@ -74,16 +74,37 @@ Un orchestrateur futur peut consommer les deux familles séparément sans les fu
 ```text
 ksp-core-lib
 
-ksp-config-lib    -> ksp-core-lib
 ksp-logging-lib   -> ksp-core-lib
+ksp-config-lib    -> ksp-core-lib
+ksp-config-lib    -> ksp-logging-lib        # lorsque du runtime logging est nécessaire
 ksp-interface-lib -> ksp-core-lib
+ksp-interface-lib -> ksp-logging-lib        # lorsque du runtime logging est nécessaire
 ```
 
 `ksp-core-lib` ne dépend d'aucun composant KSP supérieur.
 
 `ksp-interface-lib` est propriétaire de la façade wire et peut dépendre des crates externes Solana/interface explicitement autorisées par `RULES_DEPENDENCIES.md`.
 
-`ksp-config-lib` et `ksp-logging-lib` sont transversaux. Les composants supérieurs peuvent les consommer lorsqu'un besoin réel existe ; cette possibilité ne doit pas être transformée en dépendance obligatoire universelle.
+`ksp-logging-lib` est la façade logging/tracing KSP et peut dépendre de `ksp-core-lib` pour `Error` / `Result`. `ksp-core-lib` n'a pas de dépendance inverse vers le logging. Les composants comportant du runtime peuvent dépendre directement de `ksp-logging-lib`; cette permission n'oblige pas les crates purement déclaratives à le faire.
+
+---
+
+# Graphe Logging
+
+```text
+ksp-logging-lib
+    -> ksp-core-lib
+    -> tracing / tracing-appender / tracing-subscriber
+
+runtime crate
+    -> ksp-logging-lib
+```
+
+`ksp-logging-lib` est la seule façade KSP propriétaire de l'initialisation/configuration tracing. Une crate runtime ne dépend normalement pas directement de `tracing`.
+
+Exception technique possible : une application/framework, notamment Tauri, peut devoir intégrer un plugin tracing. Cette adaptation ne crée pas une seconde politique de logging parallèle.
+
+`ksp-core-lib` et les crates `*-api` purement déclaratives n'ont pas de dépendance logging obligatoire.
 
 ---
 
@@ -170,8 +191,6 @@ Le runtime peut composer registry officiel + registry/implémentations externes
 
 # Graphe Execution / Policy
 
-`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants.
-
 ```text
 ksp-execution-policy-api
     -> ksp-program-api
@@ -182,48 +201,56 @@ ksp-execution-lib
     -> ksp-execution-policy-api
     -> ksp-wallet-lib
     -> ksp-onchain-transport-lib
+    -> ksp-logging-lib
     -> ksp-core-lib
 ```
 
-## Décision importante
+`ksp-execution-lib` ne dépend pas de `ksp-program-lib` et reçoit fondamentalement une opération déjà préparée conforme à `ksp-program-api`.
 
-`ksp-execution-lib` **ne dépend pas de `ksp-program-lib`**.
+## Policy obligatoire et multi-checkpoints
 
-Il consomme le contrat public de `ksp-program-api` et reçoit :
+Toute exécution réelle reçoit explicitement une implémentation de `ksp-execution-policy-api`.
 
-- soit une opération préparée conforme à ce contrat ;
-- soit une implémentation injectée du contrat public lorsque l'API finale le justifie.
+La policy peut être consultée à plusieurs checkpoints (préflight, après simulation, avant submission ou autres points réellement justifiés). Le contrat exact ne doit pas imposer plus de callbacks que nécessaire.
 
-La forme exacte sera décidée en `pre.004`.
+La policy peut autoriser/refuser/ajouter des requirements, mais n'appelle ni wallet, ni transport, ni UI.
 
-Cette règle permet :
+## Composition supérieure
+
+Le caller fournit notamment :
+
+- réseau/provider/transport sélectionné ;
+- wallet/signers sélectionnés ;
+- options d'exécution.
+
+`ksp-execution-lib` vérifie/compose ces éléments avec les contraintes techniques de `PreparedProgramExecution` et les contraintes supplémentaires de policy.
+
+## Simulation / signature / submission / confirmation
+
+- primitive simulation/submission/status -> `ksp-onchain-transport-lib` ;
+- orchestration de ces étapes -> `ksp-execution-lib` ;
+- primitive signature -> `ksp-wallet-lib` ;
+- résolution/coordination des signers -> `ksp-execution-lib`.
+
+## Retry
+
+Retry technique d'un appel réseau identique -> transport.
+
+Retry qui change le lifecycle (nouveau blockhash, reconstruction, resimulation, resignature, resubmission) -> execution, éventuellement limité par policy.
+
+## Approbation externe
+
+Une policy peut produire un requirement d'approbation externe. `ksp-execution-lib` peut retourner un état suspendu/reprenable ; l'UI obtient l'approbation sans être appelée directement par la policy ou l'execution lib.
+
+## Store
 
 ```text
-ksp-program-lib ------------------\
-external-program-implementation ---+--> ksp-program-api --> execution
-other-compatible-implementation ---/
+ksp-execution-policy-api -X-> ksp-store-api
+ksp-execution-lib        -X-> ksp-store-api
+ksp-execution-lib        -X-> ksp-store-lib
 ```
 
-sans rendre l'orchestration dépendante de l'implémentation officielle.
-
-## Policy
-
-`ksp-execution-policy-api` définit le contrat d'évaluation, pas la policy d'un produit.
-
-Une implémentation peut appartenir à :
-
-- `ksp-scenario-<domain>-lib` pour une demo/scenario Devnet ;
-- une future bibliothèque de domaine pour une application générale ;
-- une future bibliothèque trading spécialisée.
-
-Aucune `ksp-execution-policy-lib` générique n'est prévue tant qu'une policy commune réelle n'existe pas.
-
-Une policy :
-
-- autorise/refuse/contraint une exécution ;
-- ne signe pas ;
-- ne choisit pas le backend réseau ;
-- n'envoie pas elle-même une transaction.
+La persistence d'un `ExecutionOutcome` est une composition supérieure.
 
 ---