v0.0.3-pre.008

2026-08-14 12:32:08 +02:00
parent 3b5d1a8f7a
commit 6964b71955
14 changed files with 1063 additions and 38 deletions
--- a/docs/rules/SCENARIO_CONVENTION.md
+++ b/docs/rules/SCENARIO_CONVENTION.md
@@ -0,0 +1,111 @@
+<!-- file: docs/rules/SCENARIO_CONVENTION.md -->
+<!-- version: 1 -->
+
+# Convention des scenarios KSP
+
+## Objet
+
+KSP n'impose pas actuellement de `ksp-scenario-api`.
+
+Ce document définit les conventions minimales permettant aux crates `ksp-scenario-<domain>-lib` de rester cohérentes sans les enfermer dans un trait Rust universel.
+
+## Source de vérité
+
+La logique fonctionnelle du scenario appartient à :
+
+```text
+ksp-scenario-<domain>-lib
+```
+
+Une application desktop demo, un CLI, un test ou une CI appelle cette bibliothèque et ne recrée pas le workflow.
+
+## Indépendance de l'interface
+
+Une crate scenario :
+
+- ne dépend pas de Tauri ;
+- ne contient pas de DTO TS-RS spécifiques à une UI ;
+- ne suppose pas qu'une fenêtre desktop existe ;
+- reste appelable depuis un test ou autre interface.
+
+## Environnement
+
+Un scenario indique explicitement l'environnement/réseau attendu lorsqu'il est contraint.
+
+Une app demo dont l'environnement est imposé suit la nomenclature :
+
+```text
+ksp-app-scenario-<domain>-<environment>-desk-demo
+```
+
+## Configuration et ressources
+
+Le scenario utilise les bibliothèques KSP propriétaires de :
+
+- configuration ;
+- wallet ;
+- transport ;
+- Program ;
+- execution ;
+- Store lorsque le scenario en a réellement besoin.
+
+Il ne contourne pas ces frontières avec des dépendances protocolaires/Solana externes directes.
+
+Les endpoints, wallets et autres ressources utilisées doivent être résolus explicitement ; ils ne sont pas cachés dans l'UI.
+
+## Execution policy
+
+Lorsqu'un scenario exécute une opération réelle, il fournit une policy explicite conforme à `ksp-execution-policy-api`.
+
+Une policy Devnet peut être propre à la crate scenario.
+
+La policy ne fuit pas dans `ksp-program-lib`.
+
+## Résultat
+
+Un scenario doit produire un résultat exploitable par son caller.
+
+Le résultat devrait permettre selon le besoin de distinguer :
+
+- succès/échec fonctionnel ;
+- étapes exécutées ;
+- identités blockchain utiles ;
+- validations/evidence ;
+- warnings ;
+- données de diagnostic non sensibles.
+
+Le type exact reste spécifique au domaine tant qu'un vrai contrat commun ne justifie pas `ksp-scenario-api`.
+
+## Validation
+
+Le scenario contient la logique de validation fonctionnelle nécessaire pour déterminer si son objectif a été atteint.
+
+L'application demo affiche cette validation mais ne la réimplémente pas.
+
+## Logging
+
+La crate scenario utilise `ksp-logging-lib`.
+
+Les logs peuvent couvrir `error`, `warn`, `info`, `debug` et `trace` selon pertinence.
+
+Aucun secret, seed, clé privée ou donnée sensible ne doit être loggé.
+
+## Réutilisation
+
+Une même crate scenario doit pouvoir être utilisée par plusieurs callers sans duplication :
+
+```text
+desktop demo
+test
+future CLI/tool
+CI/integration
+        |
+        v
+ksp-scenario-<domain>-lib
+```
+
+## Evolution
+
+Une convention peut être enrichie au fil des scenarios réels.
+
+`ksp-scenario-api` ne sera introduit que si plusieurs implementations démontrent un contrat commun stable et utile.