# 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 STRUCTURAL 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-solprices-desk ksp-app-backfill-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-config-lib -> ksp-wallet-lib -> ksp-onchain-transport-lib -> ksp-offchain-transport-lib ksp-app-solprices-desk -> ksp-config-lib -> ksp-offchain-transport-lib ksp-app-backfill-desk -> ksp-core-lib -> ksp-config-lib -> ksp-job-api -> ksp-job-backfill-lib -> ksp-logging-lib -> ksp-onchain-transport-lib -> ksp-store-lib ksp-app-store-desk -> ksp-config-lib -> ksp-core-lib -> ksp-logging-lib -> ksp-store-lib ksp-app-raw-transaction-ingest-desk -> ksp-config-lib -> ksp-core-lib -> ksp-logging-lib -> ksp-worker-api -> ksp-worker-raw-transaction-ingest-lib -> ksp-onchain-transport-lib -> ksp-store-lib ``` `ksp-store-lib` réexporte la surface Store commune nécessaire aux applications ; une app ne dépend pas directement de `ksp-store-api` uniquement pour atteindre les modèles/capabilities, et ne dépend jamais d'une crate backend concrète. Backfill Desk suit exactement cette règle : elle ouvre Store via `ksp-store-lib`, construit le pool HTTP via `ksp-onchain-transport-lib`, puis remet ces ressources à `ksp-job-backfill-lib`. Start/Cancel/Resume restent des opérations applicatives de composition ; le checkpoint de reprise et les ressources physiques ne deviennent jamais des DTOs Tauri. Store Desk suit la même frontière sans Transport : Config sélectionne Logging + Store, `ksp-store-lib` fournit health, reads et inspection backend-neutral, et le Store ouvert reste côté Rust. Les DataTables frontend consomment des summaries server-side et counts exacts ; les détails chargent une seule entité avec preview bornée. Aucun command d'écriture, SQL, cursor opaque, backend physique ou secret Store n'est exposé à Tauri/TypeScript. Raw Transaction Ingest Desk est la surface spécialisée de contrôle prévue après la fondation du premier worker concret. Cette fondation expose déjà lifecycle, stop et snapshots source-neutral ; la Desk ne doit cependant sélectionner des sources ou afficher reconnect/recovery qu'après matérialisation des adapters live correspondants. La sélection d'une source ne déplace ni discovery, ni hydration, ni déduplication, ni provenance dans l'application. Les endpoints/credentials restent Config/Transport-owned et le détail des entités persistées reste Store Desk-owned. 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. En distribution, une application Tauri KSP ne dépend pas du checkout source ni du CWD du launcher. Les resources Config/Schemas nécessaires sont embarquées dans le bundle ; Tauri résout leur racine immutable et `ksp-config-lib` prépare une racine KSP user-writable commune avant le bootstrap applicatif. Les Config utilisateur existantes sont conservées, les schemas package-owned sont resynchronisés et `.env` reste une ressource locale writable jamais embarquée. Cette adaptation de packaging ne transfère ni ownership Config ni accès filesystem au frontend. ## 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-transaction-ingest-lib # premier runtime worker réutilisable retenu future autonomous raw-ingest binary # seulement si un besoin de service séparé le justifie future STRUCTURAL worker future group-specific DECODED/DOMAIN workers when justified ``` Le premier worker RAW est volontairement prévu comme bibliothèque réutilisable afin qu'une Desk ou un futur host puisse le construire sans dupliquer sa logique. Un binaire autonome n'est pas créé par convention seule ; s'il apparaît, il reste un host mince au-dessus de la même bibliothèque et de `ksp-worker-api`. RAW reçoit son worker d’ingestion à la fin de sa couche ; STRUCTURAL reçoit ensuite son STRUCTURAL worker lorsque sa persistence/backlog sont disponibles. Les workers DECODED/DOMAIN ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program. Le binaire, lorsqu'il existe, 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 STRUCTURAL | v D3 DECODED | v D4 DOMAIN ``` Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et STRUCTURAL peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODED, 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 -> STRUCTURAL -> DECODED -> DOMAIN ``` 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. `ksp-job-api` fournit les contrats runtime-neutral communs ; le premier job concret `ksp-job-backfill-lib` est une bibliothèque single-run, pas un service worker autonome. Une app spécialisée peut construire les ressources Config/Transport/Store, créer un `BackfillJobRuntime`, conserver son `BackfillJobHandle`, observer les snapshots latest-value et demander une annulation coopérative. Elle ne réimplémente ni découverte/hydratation, ni frontier/checkpoint, ni persistance RAW. Aucune `ksp-job-control-lib` générique n'est introduite. Le handle concret suffit tant qu'aucune duplication entre plusieurs jobs ne justifie une couche de gouvernance commune. 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 des futurs jobs reste décidé par leur besoin réel ; le premier backfill prouve qu'un runtime de bibliothèque composable est suffisant pour un job déclenché par une application. ## 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. La première application retenue est : ```text ksp-app-raw-transaction-ingest-desk ``` Elle ne modifie jamais directement l'état interne du worker dans PostgreSQL. Elle passe par les contrats Worker et par la composition Rust propriétaire des ressources. Le premier déploiement peut piloter `ksp-worker-raw-transaction-ingest-lib` in-process si cela reste le choix le plus simple et le plus sûr. La sémantique de `ksp-worker-api` doit néanmoins rester compatible avec un futur proxy vers un worker autonome ; l'IPC/remote control ne doit pas être anticipé artificiellement avant besoin réel. La Desk RAW Transaction doit laisser choisir **une ou plusieurs sources/méthodes** parmi les capabilities effectivement configurées/admissibles par le Worker finalisé en `0.3.14`, et superviser leur état sans dupliquer discovery/hydration/déduplication/recovery dans Tauri. Store Desk reste la surface d'inspection détaillée des RAW persistés. ## 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 DOMAIN 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 DOMAIN 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 -----------> ksp-job-backfill-lib / concrete jobs | +--> ksp-scenario--lib ``` Data plane séparé : ```text transport -> RAW -> STRUCTURAL -> DECODED -> DOMAIN ``` 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.