v0.0.3-pre.005

docs/architecture/003-COMPONENT_CONTRACTS.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Contrats initiaux des composants KSP
 
@@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l
 
 Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît.
 
-L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) et les contrats Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md).
+L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md), Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) et Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md).
 
 ## Convention API / implémentation
 
@@ -43,30 +43,48 @@ Aucune API commune worker+job n'est prévue.
 
 ## Execution policy
 
-`ksp-program-lib` ne possède pas la politique de sécurité/autorisation d'un produit.
+`ksp-execution-policy-api` est un contrat public de décision séparé de `ksp-program-lib`, du wallet, du transport et de l'UI.
 
-Le contrat public séparé suivant est retenu :
+Une exécution réelle via `ksp-execution-lib` reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
 
-```text
-ksp-execution-policy-api
-```
+La policy peut être évaluée à plusieurs checkpoints afin d'intégrer des informations obtenues pendant le cycle, notamment le résultat de simulation.
 
-Il doit permettre à différents contextes de fournir leurs propres décisions de policy sans modifier `ksp-program-lib` : scenario Devnet, application générale, futur produit trading, etc.
+Une policy peut autoriser, refuser ou imposer des requirements ; elle ne réalise pas elle-même la simulation, la signature, le réseau ou une interaction Tauri.
 
-Les applications UI sélectionnent/injectent une implémentation réutilisable appropriée ; elles ne doivent pas enfouir une politique complexe directement dans la couche d'interface.
+Les implémentations appartiennent aux crates de contexte appropriées : scenario Devnet, future bibliothèque d'application générale, future policy trading, etc.
+
+Aucune `ksp-execution-policy-lib` générique n'est prévue sans logique réellement commune.
 
 ## Execution orchestration
 
-`ksp-execution-lib` est retenu comme pipeline/orchestrateur spécialisé pour relier :
+`ksp-execution-lib` consomme fondamentalement `PreparedProgramExecution` conforme à `ksp-program-api` et ne dépend pas de `ksp-program-lib`.
 
-- la préparation/sémantique programme ;
-- une implémentation de `ksp-execution-policy-api` ;
-- `ksp-wallet-lib` ;
-- `ksp-onchain-transport-lib`.
+Il orchestre :
 
-Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature.
+- policy checkpoints ;
+- assemblage message/transaction ;
+- simulation via `ksp-onchain-transport-lib` ;
+- résolution des signers et signature via `ksp-wallet-lib` ;
+- submission ;
+- confirmation ;
+- retry d'exécution lorsque celui-ci change le lifecycle ;
+- suspension/reprise lorsqu'une approbation externe est requise.
 
-`ksp-execution-lib` dépend de `ksp-program-api` mais pas de `ksp-program-lib` ; il reçoit une opération préparée ou une implémentation conforme au contrat public. Le graphe détaillé est fixé dans `005-DEPENDENCY_GRAPH.md` et les types exacts seront définis en `pre.004`.
+Le wallet et le provider/réseau sont sélectionnés/fournis par la composition supérieure ; `ksp-execution-lib` les utilise sans définir une policy de sélection implicite.
+
+Le retry d'un appel réseau identique reste une responsabilité transport, distincte du retry d'exécution nécessitant reconstruction/resimulation/resignature.
+
+`ksp-execution-lib` ne persiste pas automatiquement son résultat et ne dépend pas du store.
+
+## Logging
+
+`ksp-logging-lib` est la façade KSP unique pour le logging/tracing runtime. Elle importe/initialise directement `tracing`, `tracing-appender` et `tracing-subscriber` et peut dépendre de `ksp-core-lib` pour `Error` / `Result`.
+
+Les crates comportementales KSP peuvent dépendre directement de `ksp-logging-lib` et utilisent sa façade pour `error`, `warn`, `info`, `debug` et `trace` avec target/domain/champs structurés selon l'API finale.
+
+`ksp-core-lib` n'a pas de dépendance logging requise. Les crates `*-api` purement déclaratives restent sans logging par défaut.
+
+Une application Tauri peut exceptionnellement avoir une dépendance/framework tracing imposée par un plugin, sans définir une politique parallèle à `ksp-logging-lib`.
 
 ## Frontière materializer / store