v0.0.3-pre.008

docs/rules/RULES_DEPENDENCIES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_DEPENDENCIES.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Règles des dépendances KSP
 
@@ -98,6 +98,21 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
 - **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
 - **DEP-JOB-003** — Les jobs de replay réutilisent les pipelines des workers correspondants au lieu de dupliquer la logique D1 -> D2, D2 -> D3 ou D3 -> D4.
 
+## Services, applications et control plane
+
+- **DEP-SERVICE-001** — Chaque worker concret doit pouvoir fonctionner comme service/processus indépendant.
+- **DEP-SERVICE-002** — La direction de packaging préférée est un package `ksp-worker-<role>` contenant une cible bibliothèque réutilisable et une cible binaire autonome mince.
+- **DEP-SERVICE-003** — Un worker concret ne dépend pas d'un autre worker concret ; les données transitent par les niveaux durables Store.
+- **DEP-SERVICE-004** — Le binaire worker compose/initialise le service mais ne duplique pas le pipeline ou la logique métier de sa cible bibliothèque.
+- **DEP-CONTROL-001** — `ksp-worker-api` définit la sémantique de lifecycle indépendamment du transport local/IPC.
+- **DEP-CONTROL-002** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et peut plus tard adapter des handles locaux ou proxies distants.
+- **DEP-CONTROL-003** — Le control plane ne transporte pas les payloads D1/D2/D3/D4 entre workers.
+- **DEP-CONTROL-004** — Aucun `ksp-ipc-api` générique n'est introduit avant le premier besoin concret de transport de control.
+- **DEP-APP-001** — Les applications spécialisées sont privilégiées avant une future application globale.
+- **DEP-APP-002** — Une app manager worker pilote le service via les contrats de control et ne modifie pas directement son état interne de processing dans PostgreSQL.
+- **DEP-SCENARIO-001** — Une app scenario dépend de `ksp-scenario-<domain>-lib` ; le workflow du scenario ne réside pas dans l'application.
+- **DEP-SCENARIO-002** — Une crate scenario ne dépend pas de Tauri et doit pouvoir être appelée depuis d'autres interfaces/tests.
+
 ## Propriété des dépendances Solana
 
 - **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir un composant KSP propriétaire précis.

docs/rules/RULES_KSP.md

@@ -1,5 +1,5 @@
 <!-- file: docs/rules/RULES_KSP.md -->
-<!-- version: 11 -->
+<!-- version: 12 -->
 
 # Règles spécifiques à KSP
 
@@ -110,7 +110,7 @@
 - **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job.
 - **KSP-WORKER-002** — Les contrats communs des workers appartiennent à `ksp-worker-api` et ne contiennent aucun contrat propre aux jobs.
 - **KSP-WORKER-003** — `ksp-worker-api` est principalement une lifecycle API de services continus : identité, état, health, démarrage/arrêt et événements communs ; les capacités optionnelles ne deviennent universelles que si plusieurs workers les partagent réellement.
-- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable par managers desktop, future application globale et orchestrateur ; les apps ne réimplémentent pas cette gouvernance.
+- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable d'abord par les apps manager spécialisées, puis éventuellement par un futur orchestrateur/application globale ; les apps ne réimplémentent pas cette gouvernance.
 - **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
 - **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
 - **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
@@ -119,6 +119,10 @@
 - **KSP-WORKER-010** — `ksp-worker-raw-retriever` distingue une configuration desired et une configuration effective lors des reconfigurations à chaud.
 - **KSP-WORKER-011** — Un cursor de scan est une optimisation ; les processing outcomes durables constituent la preuve qu'un input a été traité pour un processor/version/capability.
 - **KSP-WORKER-012** — La concurrence de processing utilise une sémantique de claim/lease récupérable après expiration/crash.
+- **KSP-WORKER-013** — Chaque worker doit pouvoir fonctionner comme service/processus indépendant afin d'être arrêté/redémarré/mis à jour sans imposer l'arrêt volontaire des autres workers.
+- **KSP-WORKER-014** — La direction de packaging préférée est un package worker avec cible bibliothèque réutilisable et binaire autonome mince.
+- **KSP-WORKER-015** — Les workers ne dépendent pas directement les uns des autres ; D1–D4 constituent leur data plane partagé.
+- **KSP-WORKER-016** — Aucun ordre global strict de démarrage des workers n'est figé actuellement.
 
 ## Jobs
 
@@ -164,6 +168,8 @@
 - **KSP-SCENARIO-004** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
 - **KSP-SCENARIO-005** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
 - **KSP-SCENARIO-006** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
+- **KSP-SCENARIO-007** — La logique fonctionnelle d'un scenario s'exécute dans `ksp-scenario-<domain>-lib` et reste appelable hors desktop.
+- **KSP-SCENARIO-008** — Les scenarios suivent `docs/rules/SCENARIO_CONVENTION.md` tant qu'aucun contrat Rust commun suffisamment utile ne justifie `ksp-scenario-api`.
 
 ## Applications
 
@@ -171,3 +177,14 @@
 - **KSP-APP-002** — Les applications/demos ne dépendent pas directement de crates Solana/protocoles externes.
 - **KSP-APP-003** — Les applications/demos peuvent réaliser les opérations strictement liées à l'interface, mais pas la logique métier/protocolaire réutilisable.
 - **KSP-APP-004** — Une demo scenario desktop consomme la crate `ksp-scenario-<domain>-lib` correspondante ; elle suit la convention `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
+- **KSP-APP-005** — Les applications spécialisées précèdent toute future application globale ; aucune app globale n'est un livrable actuel.
+- **KSP-APP-006** — Une app manager worker utilise le control plane et ne modifie pas directement l'état interne de processing du worker en base.
+- **KSP-APP-007** — Une future application globale est conservée comme idée produit et sera cadrée seulement après validation suffisante des apps spécialisées/demos.
+
+## Data plane / control plane
+
+- **KSP-CONTROL-001** — Le data plane des workers passe par transport + D1/D2/D3/D4 et notifications de données persistées.
+- **KSP-CONTROL-002** — Le control plane porte lifecycle, status, health et reconfiguration ; il ne transporte pas les payloads de processing entre workers.
+- **KSP-CONTROL-003** — La sémantique de `ksp-worker-api` doit rester utilisable avec un handle local ou un futur proxy IPC.
+- **KSP-CONTROL-004** — Aucun `ksp-ipc-api` générique n'est prévu actuellement ; le premier manager/service concret doit d'abord démontrer le transport nécessaire.
+- **KSP-CONTROL-005** — `ksp-orchestrator-lib` est seulement un concept futur et n'est pas une crate retenue dans le plan actuel.

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.