khadhroony-solana-project/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md

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.

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 :

capability/lib/service
        |
        v
specialized app/demo
        |
        v
validation réelle de la capacité

avant toute application globale.

Exemples de familles spécialisées :

ksp-app-config-desk
ksp-app-wallet-desk
ksp-app-solprices-desk
ksp-app-backfill-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 :

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-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.

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 :

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 :

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 :

package ksp-worker-<role>
├── library target
│   └── service/runtime worker réutilisable
└── binary target
    └── bootstrap/config/logging/control endpoint/shutdown

Exemples conceptuels :

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 :

raw-retriever -X-> core-processor
core-processor -X-> generic-materializer
generic-materializer -X-> domain-projector

Le data plane durable reste :

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 :

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 :

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é :

in-process

ou :

through IPC to an independent process

Conceptuellement :

             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 :

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 :

ksp-scenario-<domain>-lib

et jamais l'application desktop demo.

Exemples :

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 :

ksp-app-scenario-<domain>-<environment>-desk-demo

Exemples :

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 :

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 :

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.

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

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-<domain>-lib

Data plane séparé :

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.