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

<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
<!-- version: 7 -->

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

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

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-<role>
├── 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-<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.

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