# Execution et Policy ## Objet Ce document constitue la sortie principale de `0.0.3-pre.005`. Il précise la frontière entre : - `ProgramExecutionPreparer` et `PreparedProgramExecution` ; - `ksp-execution-policy-api` ; - `ksp-execution-lib` ; - `ksp-wallet-lib` ; - `ksp-onchain-transport-lib` ; - l'interface/application qui fournit le contexte et les approbations externes. Les types Rust exacts restent volontairement à définir avec la première implémentation réelle. ## Chaîne générale ```text ProgramExecutionRequest | v ProgramExecutionPreparer | v PreparedProgramExecution | v ksp-execution-lib | +--> policy checkpoints +--> transaction/message assembly +--> simulation si requise +--> signature +--> submission +--> confirmation | v ExecutionOutcome / pending requirement / error ``` `ksp-program-lib` prépare la sémantique protocolaire. `ksp-execution-lib` orchestre le cycle transactionnel. Ces responsabilités ne sont pas fusionnées. ## Entrée fondamentale de `ksp-execution-lib` L'entrée fondamentale de `ksp-execution-lib` est une opération déjà préparée conformément à `ksp-program-api`, conceptuellement `PreparedProgramExecution`. `ksp-execution-lib` ne dépend pas de `ksp-program-lib` et ne reçoit pas des requêtes spécifiques à Token, Meteora, Raydium ou autre protocole. Un helper de composition `prepare + execute` pourra être ajouté plus tard s'il apporte une valeur réelle, mais il ne remplace pas la frontière fondamentale. ## `ksp-execution-policy-api` `ksp-execution-policy-api` est un contrat public de décision. Il ne fournit pas une policy générique KSP. Une implémentation de policy appartient au contexte qui en a besoin, par exemple : - une crate `ksp-scenario--lib` pour une demo Devnet ; - une future bibliothèque d'application générale ; - une future bibliothèque spécialisée Trading Intelligence / trading opérationnel. Aucune `ksp-execution-policy-lib` commune n'est créée sans policy réellement commune. ## Policy obligatoire pour une exécution réelle Une exécution réelle via `ksp-execution-lib` doit recevoir explicitement une implémentation de `ksp-execution-policy-api`. Il n'existe pas de fallback implicite « allow all » pour la production. Les tests peuvent utiliser une policy explicitement permissive lorsqu'ils ont besoin de tester le cycle d'exécution indépendamment de règles produit. ## Policy multi-checkpoints Une policy n'est pas nécessairement évaluée une seule fois au début. Certaines décisions ont besoin d'informations qui n'existent qu'après une étape technique, en particulier la simulation. Direction conceptuelle : ```text Prepared | v preflight policy | v simulation éventuelle | v post-simulation policy | v signature | v pre-submission policy | v submission / confirmation ``` Les noms et le nombre exact de checkpoints seront définis avec l'API réelle. Le contrat doit rester extensible sans imposer des callbacks inutiles à toutes les policies. ## Une policy décide, elle n'exécute pas Une policy peut conceptuellement : - autoriser ; - refuser ; - ajouter/resserrer des exigences ; - exiger une simulation ; - exiger une approbation externe ; - imposer un niveau minimum de confirmation ; - imposer des limites de retry/exécution. Une policy ne : - signe pas ; - sélectionne pas un secret wallet ; - appelle pas RPC ; - n'envoie pas une transaction ; - n'ouvre pas une fenêtre Tauri ; - ne bloque pas en attente d'une interaction UI. ## Trois sources de contraintes L'orchestration distingue trois origines de contraintes. ### Contraintes Program Produites par `ProgramExecutionPreparer` dans `PreparedProgramExecution` : - comptes requis ; - signers/authorities requis ; - ordre et contenu des instructions ; - PDA ; - invariants/contraintes protocolaires. Elles sont techniques et non négociables par une policy. ### Options/contexte du consommateur Le niveau supérieur fournit le contexte d'exécution : - réseau/profil choisi ; - wallet/signers sélectionnés ; - commitment/timeout souhaités ; - options de simulation ; - autres choix exposés par l'application/scénario. ### Contraintes Policy La policy peut refuser ou resserrer les options du consommateur, mais ne peut pas violer les contraintes techniques Program. ## Wallet `ksp-execution-lib` utilise `ksp-wallet-lib` pour les capacités de signature mais ne choisit pas arbitrairement un wallet. Le contexte supérieur fournit les signers/wallet handles sélectionnés ; l'orchestration vérifie qu'ils satisfont les authorities/signers requis par `PreparedProgramExecution`. Les secrets ne sont jamais transportés dans `PreparedProgramExecution`. ## Transport on-chain `ksp-execution-lib` utilise `ksp-onchain-transport-lib` pour les primitives réseau nécessaires, notamment selon le besoin : - récupération des données réseau nécessaires à la construction finale ; - simulation ; - submission ; - status/confirmation. `ksp-execution-lib` ne choisit pas arbitrairement Helius, RPC public, WS ou autre provider. Le contexte/configuration supérieur fournit la cible/transport approprié. Le choix du provider est distinct de la policy d'exécution. ## Simulation La primitive réseau de simulation appartient à `ksp-onchain-transport-lib`. L'orchestration de la simulation appartient à `ksp-execution-lib` : elle décide quand appeler la primitive selon `PreparedProgramExecution`, options et exigences de policy. La policy peut rendre la simulation obligatoire et peut évaluer son résultat, mais n'effectue pas elle-même l'appel réseau. ## Signature `ksp-execution-lib` assemble le message/transaction selon les contrats techniques retenus, résout les signers requis depuis le contexte puis appelle `ksp-wallet-lib` pour les signatures. Les crates Solana précises nécessaires aux messages/transactions seront évaluées au moment de l'implémentation selon la même politique de dépendances modernes que les autres interfaces KSP. ## Submission et confirmation Les primitives réseau de submission/status appartiennent à `ksp-onchain-transport-lib`. Le lifecycle : ```text submitted -> processed / confirmed / finalized -> timeout / failure ``` est orchestré par `ksp-execution-lib`. Une policy peut imposer un minimum de confirmation mais n'implémente pas la boucle de confirmation. ## Retry transport vs retry d'exécution Deux catégories sont distinguées. ### Retry transport Retry technique d'un appel réseau identique, par exemple erreur transitoire de connexion/rate-limit. Il appartient au transport selon ses règles propres. ### Retry d'exécution Un retry qui modifie le lifecycle de l'opération, par exemple : - blockhash expiré ; - reconstruction ; - nouvelle simulation ; - nouvelle signature ; - nouvelle submission. Il appartient à `ksp-execution-lib` et peut être limité/refusé par la policy. ## Approbation externe et suspension Une policy peut demander une approbation externe sans connaître l'UI. `ksp-execution-lib` doit pouvoir exposer un état/requirement suspendu conceptuel permettant au caller : 1. de recevoir la demande ; 2. d'obtenir l'approbation via son interface propre ; 3. de reprendre l'exécution de manière contrôlée. Le mécanisme exact de token/resume sera défini avec le premier besoin réel. Une application Tauri affiche éventuellement le dialogue ; ni la policy ni `ksp-execution-lib` ne dépendent de Tauri pour cela. ## Résultat d'exécution Le résultat doit pouvoir exposer conceptuellement : - identité de l'opération préparée ; - identité/signature transactionnelle lorsqu'elle existe ; - résultat de simulation lorsqu'elle a eu lieu ; - résultat de submission ; - état de confirmation ; - warnings ; - informations de décisions/requirements utiles au caller ; - erreur/état final ou suspendu. `ksp-execution-lib` ne persiste pas automatiquement ce résultat et ne dépend pas du store. La persistence éventuelle appartient à un composant supérieur de composition. ## Logging transversal `ksp-logging-lib` est la façade commune de logging/tracing KSP. Elle possède directement les dépendances techniques de logging, notamment : ```text tracing tracing-appender tracing-subscriber ``` et peut dépendre de `ksp-core-lib` pour `Error` / `Result`. Elle possède l'initialisation/configuration du système de logging et expose une façade KSP paramétrable (target/domain/champs structurés et niveaux selon l'API finale). Les crates runtime KSP ne dépendent normalement pas directement de `tracing`; elles utilisent `ksp-logging-lib` pour produire des événements : ```text error warn info debug trace ``` L'API exacte peut utiliser fonctions, macros ou une combinaison des deux afin de préserver les propriétés utiles de `tracing`; ce détail est reporté à l'implémentation de `ksp-logging-lib`. Les applications Tauri constituent une exception technique possible lorsqu'un plugin tel que `tauri-plugin-tracing` impose une intégration directe au framework. Cette adaptation ne doit pas créer une seconde politique de logging parallèle : `ksp-logging-lib` reste la façade/propriétaire KSP. `ksp-core-lib` n'a pas besoin de dépendre de `ksp-logging-lib` dans l'architecture actuelle. Les crates `*-api` purement déclaratives ne dépendent pas du logging par défaut. ## Composition de policies La composition de plusieurs policies spécialisées (réseau, montants, risque, deprecated operation, approval utilisateur, etc.) reste une idée à évaluer. Elle n'est pas imposée par `ksp-execution-policy-api` tant que les premières policies réelles n'ont pas démontré un contrat de composition utile. ## Dépendances interdites ```text ksp-execution-policy-api -X-> ksp-wallet-lib ksp-execution-policy-api -X-> ksp-onchain-transport-lib ksp-execution-policy-api -X-> ksp-store-api ksp-execution-policy-api -X-> UI/Tauri ksp-execution-lib -X-> ksp-program-lib ksp-execution-lib -X-> ksp-store-api ksp-execution-lib -X-> ksp-store-lib ``` ## Questions laissées à l'implémentation - types Rust exacts des checkpoints et décisions de policy ; - représentation précise de `ExecutionContext` ; - mécanisme d'approbation suspendue/reprise ; - forme exacte de `ExecutionOutcome` ; - limites/retry defaults ; - crates Solana actuelles pour message/transaction/versioned transaction ; - API fonctions/macros exacte de `ksp-logging-lib` ; - éventuelle composition de policies.