# 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--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--desk ksp-app-scenario---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- ├── 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--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---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--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--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--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.