# 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. # Applications de validation par couche KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou CORE lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri. À partir des vertical slices Program, les applications restent attachées aux besoins réels : demos de scenarios pour l'exécution et Market Desk pour les projections de marché. # 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 future CORE worker future group-specific DECODE/SPECIALIZED workers when justified ``` RAW et CORE reçoivent leurs workers à la fin de leur couche respective. Les workers DECODE/SPECIALIZED ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program. 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 durable reste : ```text transport / acquisition | v D1 RAW | v D2 CORE | v D3 DECODE | v D4 SPECIALIZED ``` Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODE, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe. 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 RAW -> CORE -> DECODE -> SPECIALIZED ``` 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. # Market Desk progressive Après les groupes Meteora/Raydium/Pump/Orca, KSP prévoit une première application spécialisée candidate `ksp-app-market-desk`. V1 peut afficher tokens, pools/markets, liquidité, trades/swaps, prix, volumes, OHLC et activité live/récente à partir des projections SPECIALIZED et des contrats KSP. Elle ne dépend pas directement des SDK/protocoles DEX pour reconstruire leurs modèles dans l'UI. Après Jupiter/OKX, la même application est enrichie avec routes, legs, DEX impliqués, fees/slippage et comparaison quote/execution lorsqu'elle existe. Les OHLC sont matérialisés dans SPECIALIZED et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu. # 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 -> RAW -> CORE -> DECODE -> SPECIALIZED ``` 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.