v0.0.3-pre.008

docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md

@@ -0,0 +1,543 @@
+<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
+<!-- version: 1 -->
+
+# Applications, services, scenarios et control plane
+
+## Objet
+
+Ce document constitue la sortie principale de `0.0.3-pre.008`.
+
+Il précise la couche supérieure de KSP sans créer prématurément une application globale ni une infrastructure IPC générique.
+
+Les décisions portent sur :
+
+- applications spécialisées ;
+- séparation interface / logique réutilisable ;
+- workers comme services autonomes ;
+- packaging lib + binaire des workers ;
+- `ksp-worker-control-lib` ;
+- séparation data plane / control plane ;
+- scenarios dans des crates `ksp-scenario-<domain>-lib` ;
+- applications desktop demo comme simples interfaces des scenarios ;
+- futur IPC ;
+- futur orchestrateur/global app uniquement comme idées à conserver.
+
+# Principe général des applications
+
+Une application KSP est une interface et une couche de composition.
+
+Elle peut :
+
+- afficher/éditer des données ;
+- collecter des inputs utilisateur ;
+- convertir ses DTO UI ;
+- appeler les bibliothèques/services KSP ;
+- présenter status, health, progression et résultats ;
+- réaliser les adaptations strictement imposées par son framework.
+
+Elle ne doit pas réimplémenter :
+
+- wire/protocol ;
+- décodage Program ;
+- préparation d'exécution ;
+- materialization ;
+- persistence SQL ;
+- wallet internals ;
+- logique de scenario ;
+- lifecycle interne d'un worker/job ;
+- logique de pipeline réutilisable.
+
+# Priorité aux applications spécialisées
+
+KSP ne planifie pas actuellement de cockpit desktop global.
+
+La stratégie retenue est :
+
+```text
+capability/lib/service
+        |
+        v
+specialized app/demo
+        |
+        v
+validation réelle de la capacité
+```
+
+avant toute application globale.
+
+Exemples de familles spécialisées :
+
+```text
+ksp-app-config-desk
+ksp-app-wallet-desk
+ksp-app-store-desk
+ksp-app-worker-<role>-desk
+ksp-app-scenario-<domain>-<environment>-desk-demo
+```
+
+Les noms exacts des managers workers seront décidés avec les premières applications.
+
+Une future application globale de contrôle/exploitation est considérée comme un produit futur attendu, mais elle n'est pas un livrable du roadmap actuel et ne doit pas influencer prématurément les contrats.
+
+# Applications spécialisées et dépendances directes
+
+Une application spécialisée peut dépendre directement de la bibliothèque KSP correspondant à sa responsabilité.
+
+Exemples :
+
+```text
+ksp-app-config-desk
+    -> ksp-config-lib
+
+ksp-app-wallet-desk
+    -> ksp-wallet-lib
+
+ksp-app-store-desk
+    -> ksp-store-api
+    -> ksp-store-lib
+```
+
+Les couches N1–N4 expriment des responsabilités et une direction de dépendances ; elles n'imposent pas de traverser toutes les couches intermédiaires.
+
+# Tauri
+
+Les applications desktop Tauri restent des adapters/interfaces.
+
+Les commands Tauri :
+
+```text
+UI DTO
+   |
+   v
+Tauri command
+   |
+   v
+KSP lib/service/control contract
+```
+
+TS-RS reste principalement une frontière applicative pour les DTO exposés à Tauri.
+
+Une application Tauri peut devoir intégrer un plugin/framework de tracing, mais `ksp-logging-lib` reste la façade/politique de logging KSP.
+
+# Workers comme services indépendants
+
+Les workers KSP doivent pouvoir fonctionner comme **services/processus indépendants**.
+
+Objectif opérationnel :
+
+```text
+worker A update/restart
+        |
+        +-- no required shutdown of worker B/C/D
+```
+
+Les workers ne forment pas un pipeline process-to-process couplé.
+
+Ils synchronisent leur data plane via les niveaux durables du Store.
+
+## Packaging préféré
+
+Pour éviter de séparer artificiellement logique réutilisable et executable dans deux packages lorsqu'il n'y a pas encore de besoin, la direction préférée est :
+
+```text
+package ksp-worker-<role>
+├── library target
+│   └── service/runtime worker réutilisable
+└── binary target
+    └── bootstrap/config/logging/control endpoint/shutdown
+```
+
+Exemples conceptuels :
+
+```text
+ksp-worker-raw-retriever
+ksp-worker-core-processor
+ksp-worker-generic-materializer
+ksp-worker-domain-projector
+```
+
+Le binaire doit rester mince.
+
+Il ne duplique pas le pipeline ni la logique de worker contenue dans la cible bibliothèque du même package.
+
+Une séparation future en packages distincts `*-lib` / executable n'est introduite que si un besoin concret le justifie.
+
+# Responsabilité du binaire worker
+
+Le binaire autonome peut notamment :
+
+- charger/résoudre sa configuration ;
+- initialiser `ksp-logging-lib` ;
+- ouvrir les ressources externes nécessaires via les bibliothèques KSP ;
+- construire l'instance worker ;
+- exposer le futur endpoint de control plane ;
+- gérer les signaux de shutdown ;
+- attendre le lifecycle du service ;
+- traduire le résultat final en exit code/log approprié.
+
+Il ne contient pas de logique de processing qui ne serait pas réutilisable depuis la bibliothèque worker.
+
+# Indépendance des workers
+
+Aucun worker ne dépend directement d'un autre worker concret.
+
+Interdictions conceptuelles :
+
+```text
+raw-retriever -X-> core-processor
+core-processor -X-> generic-materializer
+generic-materializer -X-> domain-projector
+```
+
+Le data plane reste :
+
+```text
+W1 -> D1
+      |
+      v
+     W2 -> D2
+            |
+            v
+           W3 -> D3
+                  |
+                  v
+                 W4 -> D4
+```
+
+Les notifications accélèrent le réveil mais ne créent pas une connexion fonctionnelle worker-to-worker.
+
+Cette indépendance permet arrêt, restart ou mise à jour d'un worker sans arrêter volontairement les autres.
+
+# Ordre global de démarrage
+
+Aucun ordre global strict de démarrage n'est figé dans cette prerelease.
+
+La robustesse recherchée est :
+
+- un worker peut être running mais idle si son backlog est vide ;
+- l'absence temporaire d'upstream ne doit pas casser le worker downstream ;
+- le Store reste le point de synchronisation durable.
+
+Un futur manager/orchestrateur pourra choisir un ordre pratique de démarrage/arrêt, mais cette policy n'est pas inscrite dans les contrats worker.
+
+# Data plane et control plane
+
+KSP distingue explicitement deux plans.
+
+## Data plane
+
+Le data plane transporte/persiste les données Solana et les résultats de processing :
+
+```text
+ksp-onchain-transport-lib
+        |
+        v
+D1 -> D2 -> D3 -> D4
+```
+
+avec notifications de données persistées comme wake-up.
+
+Les workers ne s'échangent pas leurs payloads via le control plane.
+
+## Control plane
+
+Le control plane sert à :
+
+- start/stop/shutdown ;
+- status ;
+- health ;
+- reconfiguration lorsqu'elle est supportée ;
+- suivi de lifecycle ;
+- commandes opérationnelles futures.
+
+Il s'appuie sur :
+
+```text
+ksp-worker-api
+ksp-worker-control-lib
+ksp-job-api
+future IPC adapter
+future manager/orchestrator
+```
+
+Le control plane n'est pas le data plane.
+
+# `ksp-worker-control-lib`
+
+`ksp-worker-control-lib` reste la bibliothèque de gouvernance réutilisable au-dessus de `ksp-worker-api`.
+
+Responsabilités candidates :
+
+- registry de workers contrôlables ;
+- lookup ;
+- start/stop/shutdown dispatch ;
+- status/health aggregation ;
+- reconfiguration si capability supportée ;
+- adaptation local/remote lorsque les premiers transports de control apparaissent.
+
+Elle ne connaît pas :
+
+- la logique raw/Core/materialization ;
+- PostgreSQL internals ;
+- Solana RPC ;
+- Tauri ;
+- les types propriétaires d'un worker concret au-delà des contrats publics nécessaires.
+
+# Worker local et worker distant
+
+La sémantique de `ksp-worker-api` ne doit pas dépendre du fait qu'un worker soit appelé :
+
+```text
+in-process
+```
+
+ou :
+
+```text
+through IPC to an independent process
+```
+
+Conceptuellement :
+
+```text
+             ksp-worker-api semantics
+                     ^
+             +-------+-------+
+             |               |
+        local handle      remote proxy
+```
+
+Le type exact de proxy/transport n'est pas défini maintenant.
+
+# IPC
+
+Le besoin d'IPC existe naturellement dès qu'une app manager doit piloter un worker autonome.
+
+Cependant KSP ne crée pas encore :
+
+```text
+ksp-ipc-api
+ksp-control-api
+```
+
+génériques.
+
+Le contrat sémantique reste `ksp-worker-api`.
+
+Le premier manager/service réel devra choisir un mécanisme IPC adapté et pourra :
+
+- l'intégrer dans `ksp-worker-control-lib` si la surface reste petite ;
+- ou justifier une bibliothèque spécialisée de transport/control si la réutilisation le demande.
+
+Le choix du mécanisme exact est reporté à la release fonctionnelle concernée.
+
+# Jobs
+
+Les jobs restent distincts des workers.
+
+Une app spécialisée peut déclencher/suivre un job concret via `ksp-job-api` et la composition adaptée.
+
+Aucune `ksp-job-control-lib` générique n'est introduite.
+
+Le fait qu'un worker soit un process/service indépendant ne force pas les jobs à adopter exactement le même modèle de déploiement.
+
+Le packaging/exécution des jobs sera déterminé avec les premiers jobs réels.
+
+# Scenarios : logique dans la bibliothèque
+
+La source de vérité d'un scenario est toujours :
+
+```text
+ksp-scenario-<domain>-lib
+```
+
+et jamais l'application desktop demo.
+
+Exemples :
+
+```text
+ksp-scenario-memo-lib
+ksp-scenario-token-lib
+ksp-scenario-ata-lib
+ksp-scenario-token-2022-lib
+ksp-scenario-metadata-lib
+ksp-scenario-spm-lib
+```
+
+La bibliothèque scenario possède la préparation et l'enchaînement fonctionnel du scenario.
+
+Elle peut être consommée par :
+
+- application desktop demo ;
+- tests ;
+- futur CLI/tool ;
+- CI/integration environment lorsque pertinent.
+
+# Pas de `ksp-scenario-api` actuellement
+
+Aucun trait universel de scenario n'est imposé.
+
+Les premières implementations utilisent une norme documentaire commune définie dans `docs/rules/SCENARIO_CONVENTION.md`.
+
+Une API commune ne sera créée que si plusieurs scenarios réels révèlent un contrat réutilisable qui apporte plus que des conventions.
+
+# Applications desktop demo de scenarios
+
+Convention retenue :
+
+```text
+ksp-app-scenario-<domain>-<environment>-desk-demo
+```
+
+Exemples :
+
+```text
+ksp-app-scenario-token-devnet-desk-demo
+ksp-app-scenario-token-2022-devnet-desk-demo
+ksp-app-scenario-metadata-devnet-desk-demo
+ksp-app-scenario-spm-devnet-desk-demo
+```
+
+Flux :
+
+```text
+desktop UI
+    |
+    v
+Tauri adapter/DTO
+    |
+    v
+ksp-scenario-<domain>-lib
+    |
+    v
+KSP capabilities
+```
+
+L'app ne construit pas un scenario parallèle.
+
+# Scenarios et execution policy
+
+Une crate scenario peut fournir une implémentation de `ksp-execution-policy-api` adaptée à son environnement.
+
+Exemple Devnet :
+
+- réseau Devnet imposé ;
+- wallet temporaire autorisé/requis selon le scenario ;
+- simulation obligatoire ;
+- opérations expérimentales éventuellement autorisées ;
+- confirmation UI non requise si le scenario le décide explicitement.
+
+Cette policy appartient au scenario, pas à `ksp-program-lib`.
+
+# Applications worker spécialisées
+
+Une application spécialisée de worker peut être créée lorsqu'elle est utile pour développer/tester/exploiter ce service.
+
+Elle doit passer par le control plane et non modifier directement l'état interne du worker dans PostgreSQL.
+
+Conceptuellement :
+
+```text
+ksp-app-worker-<role>-desk
+        |
+        v
+ksp-worker-control-lib
+        |
+        v
+worker-api / remote proxy
+        |
+        v
+independent worker service
+```
+
+La nomenclature précise des apps sera fixée à la première implémentation pour éviter de multiplier prématurément les packages.
+
+# Configuration desired vs effective
+
+La configuration persistée/résolue et la configuration effectivement appliquée sont deux faits distincts.
+
+```text
+ksp-config-lib
+    -> desired configuration
+
+worker/control
+    -> apply/reconfigure
+
+worker status
+    -> effective configuration/generation
+```
+
+Une app spécialisée peut éditer une configuration puis demander son application, mais ne doit pas considérer l'écriture du document comme la preuve que le worker l'a appliquée.
+
+# Future orchestrator
+
+Un orchestrateur global pourra devenir utile lorsque plusieurs services/managers/jobs devront être coordonnés.
+
+Le concept est conservé, mais aucune crate `ksp-orchestrator-lib` n'est retenue comme livrable actuel.
+
+Sa responsabilité éventuelle devra rester control plane :
+
+- coordination ;
+- topology ;
+- health global ;
+- restart/shutdown policy ;
+- déclenchement de jobs.
+
+Il ne doit jamais devenir un nouveau propriétaire de Program, Store, transport ou materialization.
+
+# Future global application
+
+Une application globale d'exploitation/contrôle est attendue à terme.
+
+Elle reste **une idée future**, pas une tâche de développement actuelle.
+
+Avant elle, KSP doit disposer d'applications spécialisées et demos permettant de valider réellement :
+
+- config ;
+- wallet ;
+- Store ;
+- Program/execution ;
+- scenarios ;
+- workers ;
+- jobs/replays ;
+- autres domaines à venir.
+
+Son nom et son scope ne sont pas définis.
+
+# Graphe synthétique
+
+```text
+specialized desktop app
+        |
+        v
+control/application adapters
+        |
+        +--> ksp-worker-control-lib --> ksp-worker-api --> worker service
+        |
+        +--> ksp-job-api -----------> concrete job
+        |
+        +--> ksp-scenario-<domain>-lib
+```
+
+Data plane séparé :
+
+```text
+transport -> D1 -> D2 -> D3 -> D4
+```
+
+Aucun payload de processing n'a besoin de transiter via l'UI/control plane.
+
+# Questions laissées ouvertes
+
+Les premières implementations concernées devront fixer :
+
+- mécanisme IPC ;
+- protocole/framing/authentication local éventuels ;
+- packaging final des jobs ;
+- naming exact des apps worker manager ;
+- stratégie de découverte des services workers ;
+- représentation remote proxy de `ksp-worker-api` ;
+- graceful service update/restart ;
+- éventuel ordre de démarrage pratique ;
+- éventuel orchestrateur global ;
+- scope et nom de la future application globale.