khadhroony-solana-project/deltas/0.0.3/pre.005.md

Delta 0.0.3-pre.005

Base requise

v0.0.3-pre.004.

Objectif

Détailler ksp-execution-policy-api et ksp-execution-lib, fixer la séparation entre préparation Program, décision policy, wallet, transport et orchestration transactionnelle, puis formaliser ksp-logging-lib comme façade logging/tracing commune du runtime KSP.

Version Cargo

workspace.package.version passe de :

0.0.3-pre.4

à :

0.0.3-pre.5

Le header de Cargo.toml passe de version 10 à 11.

Fichiers ajoutés

• docs/architecture/007-EXECUTION_AND_POLICY.md
• deltas/0.0.3/pre.005.md

Fichiers modifiés

• Cargo.toml
• docs/architecture/000-README.md
• docs/architecture/002-LAYERS_AND_DEPENDENCIES.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

Policy

• ksp-execution-policy-api est obligatoire explicitement pour toute exécution réelle via ksp-execution-lib.
• Aucun fallback permissif implicite n'est prévu.
• Une policy peut être consultée à plusieurs checkpoints lorsque des informations supplémentaires, notamment simulation, deviennent disponibles.
• Une policy décide/refuse/contraint et peut produire des requirements ; elle ne signe, ne simule, n'appelle le réseau ou l'UI elle-même.
• Une policy peut demander une approbation externe ; le cycle doit pouvoir être suspendu/repris sans dépendance vers Tauri/UI.

Execution

ksp-execution-lib consomme fondamentalement PreparedProgramExecution et ne dépend pas de ksp-program-lib.

Il orchestre :

• policy checkpoints ;
• assemblage message/transaction ;
• simulation via transport ;
• signature via wallet ;
• submission ;
• confirmation ;
• retry de lifecycle ;
• suspension/reprise sur requirement externe.

Wallet/signers et provider/transport sont sélectionnés/fournis par la composition supérieure.

Contraintes

Trois sources sont distinguées :

1. contraintes techniques Program, non négociables ;
2. options/contexte du caller ;
3. contraintes supplémentaires de policy.

Retry

• retry technique d'un appel réseau identique -> transport ;
• retry qui nécessite reconstruction/resimulation/resignature/resubmission -> execution.

Store

ksp-execution-lib ne dépend ni de ksp-store-api ni de ksp-store-lib et ne persiste pas automatiquement ExecutionOutcome.

Logging

ksp-logging-lib est la façade commune de logging/tracing KSP.

Elle importe directement et possède l'initialisation/configuration de :

tracing
tracing-appender
tracing-subscriber

Elle peut dépendre de ksp-core-lib pour Error / Result.

ksp-core-lib n'a pas de dépendance logging requise.

Les crates runtime KSP peuvent dépendre directement de ksp-logging-lib et utilisent sa façade pour :

error
warn
info
debug
trace

avec target/domain/champs structurés selon l'API finale.

Les crates *-api purement déclaratives ne dépendent pas du logging par défaut.

Une intégration Tauri peut exceptionnellement avoir besoin d'un plugin/d'une dépendance tracing au niveau framework, sans créer une seconde policy logging parallèle.

La forme exacte de la façade (fonctions, macros ou combinaison) est reportée à l'implémentation de ksp-logging-lib.

Idées reportées

• composition générique de plusieurs policies spécialisées ;
• mécanisme exact de reprise après approbation externe ;
• types Rust exacts des checkpoints/decisions/outcomes ;
• crates Solana précises pour message/transaction à sélectionner au moment de l'implémentation.

Suite

pre.006 peut maintenant traiter Data / Materializer / Store / Acquisition sans rouvrir les responsabilités Execution/Policy.

Validations

• headers file: / version: vérifiés ;
• Cargo.toml parsé et version 0.0.3-pre.5 vérifiée ;
• présence de 007-EXECUTION_AND_POLICY.md et de ses références vérifiée ;
• dépendances/interdictions Execution/Policy/Logging vérifiées dans le graphe et les règles ;
• aucune commande Cargo de build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel.