diff --git a/Cargo.toml b/Cargo.toml index 69ad1a7..1fb41bb 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 13 +# version: 14 [workspace] resolver = "3" members = ["crates/ksp-core-lib"] [workspace.package] -version = "0.0.3-pre.7" +version = "0.0.3-pre.8" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 157075d..24e0b1b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -86,10 +86,10 @@ Regrouper les releases consacrées aux fondations N1. La série n'est pas destin - [ ] Introduire `ksp-worker-generic-materializer` pour D2 Core -> D3 journal de matérialisation générique. - [ ] Introduire `ksp-worker-domain-projector` pour D3 -> D4 projections spécialisées ; nom révisable. - [ ] Exploiter les mêmes pipelines spécialisés pour les workers live et les jobs de replay afin d'éviter la duplication des frontières de processing. -- [ ] Étendre `ksp-worker-control-lib` à la gouvernance de plusieurs workers. +- [ ] Étendre `ksp-worker-control-lib` à la gouvernance de plusieurs workers autonomes. +- [ ] Fournir pour chaque worker un mode service autonome, avec logique réutilisable séparée du binaire d'enveloppe. +- [ ] Construire d'abord les applications spécialisées nécessaires au développement, test et exploitation de chaque capacité. - [ ] Garder jobs et workers sous des lifecycle APIs séparées. -- [ ] Introduire un orchestrateur global lorsqu'il existe plusieurs managers/workers à coordonner. -- [ ] Introduire l'application globale de supervision/contrôle. ## 0.7.x — Trading Intelligence diff --git a/deltas/0.0.3/pre.008.md b/deltas/0.0.3/pre.008.md new file mode 100644 index 0000000..ca27378 --- /dev/null +++ b/deltas/0.0.3/pre.008.md @@ -0,0 +1,186 @@ + + + +# Delta 0.0.3-pre.008 + +## Base requise + +`v0.0.3-pre.007`. + +## Objectif + +Formaliser applications spécialisées, workers autonomes, control plane et convention des scenarios sans créer prématurément une application globale ou une infrastructure IPC générique. + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.0.3-pre.7 +``` + +à : + +```text +0.0.3-pre.8 +``` + +Le header de `Cargo.toml` passe de version 13 à 14. + +## Fichiers ajoutés + +- `docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md` +- `docs/rules/SCENARIO_CONVENTION.md` +- `deltas/0.0.3/pre.008.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `ROADMAP.md` +- `docs/architecture/000-README.md` +- `docs/architecture/003-COMPONENT_CONTRACTS.md` +- `docs/architecture/004-COMPONENT_INVENTORY.md` +- `docs/architecture/005-DEPENDENCY_GRAPH.md` +- `docs/rules/RULES_DEPENDENCIES.md` +- `docs/rules/RULES_KSP.md` +- `docs/IDEAS.md` +- `docs/plans/001-V0_0_3_PLAN.md` +- `prompts/001-V0_1_X_START_PROMPT.md` + +## Fichiers supprimés + +Aucun. + +## Décisions principales + +### Applications spécialisées d'abord + +KSP ne planifie pas actuellement d'application globale de contrôle. + +Les applications spécialisées et demos doivent d'abord permettre de développer, tester et valider chaque capacité. + +La future application globale est conservée dans `docs/IDEAS.md` comme produit attendu mais non planifié. + +### Workers services indépendants + +Chaque worker doit pouvoir fonctionner comme service/processus autonome afin de pouvoir être arrêté, redémarré ou mis à jour sans imposer l'arrêt des autres. + +Direction de packaging préférée : + +```text +package ksp-worker- +├── library target +└── binary target +``` + +La bibliothèque porte le runtime/logique du worker ; le binaire reste un bootstrap/service wrapper mince. + +### Pas de dépendance worker-to-worker + +Les workers se synchronisent via Store D1–D4 et notifications de wake-up. + +Ils ne transportent pas les données directement entre processus. + +### Pas d'ordre global strict figé + +Aucun ordre obligatoire de démarrage des workers n'est inscrit dans les contrats. + +Un futur manager/orchestrateur pourra adopter un ordre pratique, mais les workers restent conçus pour tolérer un upstream temporairement absent. + +### Data plane / control plane + +Data plane : + +```text +transport -> D1 -> D2 -> D3 -> D4 +``` + +Control plane : + +```text +worker-api +worker-control-lib +job-api +future IPC +future managers/orchestrator +``` + +Les payloads de processing ne transitent pas dans le control plane. + +### `ksp-worker-control-lib` + +Il reste la gouvernance commune des workers et doit pouvoir, à terme, travailler avec un handle local ou un proxy distant conforme aux mêmes contrats Worker. + +### IPC + +Le besoin d'IPC est reconnu pour piloter les services autonomes. + +Aucun `ksp-ipc-api` générique n'est créé maintenant. + +Le premier manager/service réel déterminera le mécanisme et dira s'il faut un adapter interne à `ksp-worker-control-lib` ou une bibliothèque spécialisée. + +### Scenarios + +La logique du scenario appartient exclusivement à : + +```text +ksp-scenario--lib +``` + +L'app desktop demo appelle cette bibliothèque et ne recrée pas le workflow. + +La même crate scenario doit pouvoir être appelée depuis test, futur CLI/tool ou CI lorsque pertinent. + +### Convention scenario + +`docs/rules/SCENARIO_CONVENTION.md` remplace pour l'instant le besoin d'un `ksp-scenario-api`. + +Elle définit notamment : + +- indépendance de Tauri ; +- environnement explicite ; +- utilisation des capacités KSP ; +- execution policy explicite ; +- résultat exploitable par le caller ; +- validation/evidence dans la crate scenario ; +- logging via `ksp-logging-lib`. + +### Future orchestration + +`ksp-orchestrator-lib` reste un concept futur seulement. + +La future application globale reste également une idée future seulement. + +## Roadmap + +La tâche « application globale de supervision/contrôle » est retirée du roadmap concret. + +Le roadmap conserve les applications spécialisées et le mode service autonome des workers. + +## Plan restant + +- `pre.009` — découpage des premières releases fonctionnelles concrètes ; +- `pre.010` — clôture fondatrice et prompt final. + +## Questions reportées + +- mécanisme IPC concret ; +- discovery/authentication/framing du control plane ; +- nom exact des apps worker manager ; +- packaging/exécution des jobs ; +- graceful service update/restart ; +- éventuel ordre pratique de démarrage ; +- futur orchestrateur ; +- nom/scope/release de l'application globale. + +## Validations + +- headers `file:` / `version:` vérifiés ; +- `Cargo.toml` parsé et version `0.0.3-pre.8` vérifiée ; +- référence vers `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md` vérifiée ; +- `SCENARIO_CONVENTION.md` ajouté ; +- application globale retirée des tâches roadmap et conservée dans IDEAS ; +- packaging lib + bin des workers documenté ; +- absence d'un ordre global strict documentée ; +- plan conservé jusqu'à `pre.010` ; +- aucune commande Cargo build/test exécutée : ce delta reste documentaire. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index 3980476..89ad980 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # Idées à explorer @@ -275,3 +275,31 @@ Checkpoint/restart est nécessaire pour backfill/replay. Déterminer si pause/re **Status :** À explorer Backlog count, oldest pending age, processing rate et failure rate doivent être observables. Décider plus tard si health/status + logging suffisent ou si une API/metrics exporter dédiée devient nécessaire. + +## Applications et orchestration futures + +### Application globale de contrôle/exploitation + +**Status :** Future certaine, non planifiée actuellement + +Une application globale de contrôle/exploitation est attendue à terme. + +Elle ne doit pas être construite avant les applications spécialisées et demos nécessaires pour valider séparément config, wallet, Store, Program/execution, scenarios, workers/jobs et futurs domaines. + +Son nom, son périmètre et sa release ne sont pas fixés. + +### Orchestrateur global + +**Status :** À réévaluer plus tard + +Un orchestrateur pourra devenir utile pour coordonner plusieurs services, policies de restart/shutdown et déclenchements de jobs. + +Aucune crate `ksp-orchestrator-lib` n'est retenue actuellement. + +### IPC worker control + +**Status :** À explorer au premier manager/service réel + +Les workers sont des services autonomes. Une app manager devra donc disposer d'un transport de control. + +Ne pas créer de `ksp-ipc-api` générique avant de connaître les contraintes réelles du premier manager : plateforme, framing, discovery, authentication locale et lifecycle. diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index 61f9482..1abc940 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # Architecture KSP @@ -25,6 +25,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas. 6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe ; 7. [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md) — policy multi-checkpoints, orchestration transactionnelle, wallet/transport, retry, approval externe et résultat d'exécution ; 8. [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) — niveaux durables D1–D4, Materialization, Store PostgreSQL de référence, provenance, idempotence, replay et notifications de données persistées ; -9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence. +9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence ; +10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration. `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires. diff --git a/docs/architecture/003-COMPONENT_CONTRACTS.md b/docs/architecture/003-COMPONENT_CONTRACTS.md index 8ef1d82..f0e6cba 100644 --- a/docs/architecture/003-COMPONENT_CONTRACTS.md +++ b/docs/architecture/003-COMPONENT_CONTRACTS.md @@ -1,5 +1,5 @@ - + # Contrats initiaux des composants KSP @@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît. -L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md), Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md), Data/Materialization/Store dans [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) et Acquisition/Workers/Jobs dans [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md). +L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md), Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md), Data/Materialization/Store dans [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) Acquisition/Workers/Jobs dans [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) et Apps/Services/Scenarios/Control dans [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md). ## Convention API / implémentation @@ -134,7 +134,7 @@ Le contrat de notification est distinct de son transport concret. `ksp-worker-api` est une lifecycle API pour services continus/live. -`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance pouvant être consommée par les applications manager desktop, une future application globale ou un orchestrateur. +`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance pouvant être consommée d'abord par les applications manager spécialisées, puis éventuellement par un futur orchestrateur ou une future application globale. Workers retenus : @@ -147,6 +147,8 @@ ksp-worker-domain-projector Le dernier nom reste provisoire. +Chaque worker doit pouvoir fonctionner comme service/processus indépendant afin d'être arrêté, redémarré ou mis à jour sans imposer l'arrêt des autres. La direction de packaging préférée est un package `ksp-worker-*` avec cible bibliothèque réutilisable et binaire autonome mince. + Les workers de processing utilisent le Store comme source de vérité du backlog, peuvent être réveillés par notification, et doivent pouvoir reprendre après crash. Le raw retriever possède en plus une capacité de hot reconfiguration de sa sélection d'acquisition. ## Jobs @@ -170,7 +172,7 @@ Aucune `ksp-job-control-lib` n'est prévue actuellement. D'autres jobs pourront Les scénarios restent dans des crates spécialisées `ksp-scenario--lib`. -`ksp-scenario-api` n'est pas retenu actuellement : une norme de structure/comportement commune est préférée à un trait Rust obligatoire tant qu'un vrai contrat commun n'a pas émergé. +`ksp-scenario-api` n'est pas retenu actuellement : `docs/rules/SCENARIO_CONVENTION.md` porte la norme commune tant qu'un vrai contrat Rust réutilisable n'a pas émergé. Les demos desktop de scénario suivent provisoirement la forme : @@ -180,6 +182,18 @@ ksp-app-scenario---desk-demo et réutilisent la crate de scénario correspondante. +## Applications, services et control plane + +Les applications spécialisées sont développées avant toute application globale. + +Les apps restent des interfaces/compositions et ne réimplémentent pas les workflows des bibliothèques/services sous-jacents. + +Les workers sont des services autonomes et ne communiquent pas directement leurs données entre eux. D1–D4 constituent le data plane ; `ksp-worker-api`, `ksp-worker-control-lib`, `ksp-job-api` et le futur IPC constituent le control plane. + +Aucun `ksp-ipc-api` générique ni `ksp-orchestrator-lib` n'est retenu comme crate actuelle. + +Une future application globale est conservée comme idée produit, pas comme tâche du roadmap présent. + ## Pipelines Aucun `ksp-pipeline-lib` monolithique. diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 860ea2c..2e8e72e 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`. Il répond principalement à la question : **quel composant possède quelle responsabilité ?** -Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store dans [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md), puis `pre.007` l'exploitation workers/jobs/pipelines dans [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md). Les détails de types Rust restent révisables avec les premières implémentations. +Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `pre.007` l'exploitation workers/jobs/pipelines, puis `pre.008` Apps/Services/Scenarios/Control dans [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md). Les détails de types Rust restent révisables avec les premières implémentations. ## Statuts @@ -40,7 +40,7 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé | Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées | | Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries, backlog/replay et notification backend | | Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus | -| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur | +| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable de services workers autonomes pour apps spécialisées puis futurs managers/orchestrateurs | | Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data | | Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique | | Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core | @@ -171,6 +171,22 @@ Elle doit pouvoir être consommée par : Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique. +### Packaging des workers + +Chaque package `ksp-worker-` doit pouvoir fournir : + +```text +library target + -> logique/runtime service réutilisable + +binary target + -> bootstrap autonome mince +``` + +Cette direction permet de tester/réutiliser la logique sans perdre la propriété « service indépendant ». + +Le binaire autonome n'est pas une seconde implémentation du worker. + ### Workers de processing Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites : @@ -239,7 +255,7 @@ ksp-scenario-spm-lib ... ``` -`ksp-scenario-api` n'est pas retenu actuellement. Une **norme de structure/comportement** commune est préférée à un trait Rust susceptible de limiter des scénarios dont les besoins sont différents. Cette décision pourra être revue si les premières implémentations montrent un vrai contrat commun utile. +`ksp-scenario-api` n'est pas retenu actuellement. La norme commune est documentée dans `docs/rules/SCENARIO_CONVENTION.md` et peut évoluer avec les premières implémentations. Les applications de démonstration correspondantes suivent la forme : @@ -255,7 +271,19 @@ ksp-app-scenario-token-2022-devnet-desk-demo ksp-app-scenario-metadata-devnet-desk-demo ``` -Chaque application appelle la crate `ksp-scenario--lib` correspondante et ne duplique pas son scénario. +Chaque application appelle la crate `ksp-scenario--lib` correspondante et ne duplique pas son scénario. La crate scenario doit également pouvoir être appelée hors desktop. + +## Applications spécialisées et control plane + +Les applications spécialisées sont prioritaires sur une future application globale. + +Une app worker spécialisée passe par `ksp-worker-control-lib` / `ksp-worker-api` et ne manipule pas directement l'état interne du worker dans le Store. + +Le data plane est D1–D4. Le control plane porte start/stop/status/health/reconfigure et reste séparé des payloads de processing. + +Les workers doivent être exploitables comme services autonomes. Le mécanisme IPC exact reste à définir à la première implémentation manager/service ; aucun `ksp-ipc-api` générique n'est créé maintenant. + +Une future application globale est conservée dans `docs/IDEAS.md` seulement. ## Pipelines @@ -311,4 +339,5 @@ Le graphe confirme les principes suivants : - `pre.004` : types publics précis de `ksp-program-api` et policy ; - `pre.005` : types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ; - `pre.005` : modèles materializer/store, notifications, replay et provenance ; -- `pre.008` : managers/apps/processus/IPC, norme des scenarios et orchestrateur futur. +- première implémentation manager/service : mécanisme IPC et proxy distant Worker ; +- futur : orchestrateur/application globale seulement lorsqu'un besoin opérationnel concret le justifie. diff --git a/docs/architecture/005-DEPENDENCY_GRAPH.md b/docs/architecture/005-DEPENDENCY_GRAPH.md index 2a87fd2..2e1430d 100644 --- a/docs/architecture/005-DEPENDENCY_GRAPH.md +++ b/docs/architecture/005-DEPENDENCY_GRAPH.md @@ -1,5 +1,5 @@ - + # Graphe de dépendances KSP @@ -684,8 +684,77 @@ La notification ne remplace jamais le Store. --- +# Graphe applications / services / control plane + +## Worker service autonome + +```text +package ksp-worker- + +library target + -> ksp-worker-api + -> pipeline spécialisé + -> implémentations KSP nécessaires + +binary target + -> library target du même package + -> ksp-config-lib + -> ksp-logging-lib + -> bootstrap/service control adapter +``` + +Le binaire ne contient pas une seconde logique de processing. + +## App worker spécialisée + +```text +ksp-app-worker--desk + -> ksp-worker-control-lib + -> ksp-worker-api + -> future remote proxy / IPC adapter +``` + +L'app ne dépend pas du worker concret pour réimplémenter son lifecycle interne. + +## Data plane + +```text +transport -> D1 -> D2 -> D3 -> D4 +``` + +## Control plane + +```text +specialized app/tool + | + v +ksp-worker-control-lib + | + v +ksp-worker-api + | + v +local handle / future remote proxy +``` + +Jobs restent parallèlement sous `ksp-job-api`. + +Interdictions : + +```text +worker A -X-> worker B +control plane -X-> payload transfer D1/D2/D3/D4 +scenario demo app -X-> duplicate scenario workflow +``` + +Aucun `ksp-ipc-api` générique n'est retenu maintenant. + +--- + # Scenarios et applications demo +La logique du scénario s'exécute dans la crate scenario elle-même et reste appelable sans desktop. + Une crate scénario peut composer les capacités nécessaires à son domaine : ```text @@ -710,13 +779,15 @@ ksp-app-scenario--devnet-desk-demo -> ksp-scenario--lib ``` +Le scenario ne réside jamais dans l'application. + Elle peut dépendre de bibliothèques KSP d'interface/configuration strictement nécessaires à son UI, mais ne réimplémente ni scénario ni policy métier. --- -# Orchestrateur futur +# Orchestrateur futur — concept uniquement -Le futur orchestrateur est au-dessus des contrôles spécialisés. +Un futur orchestrateur pourra être au-dessus des contrôles spécialisés, mais aucune crate n'est retenue comme livrable actuel. Conceptuellement : diff --git a/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md new file mode 100644 index 0000000..9709372 --- /dev/null +++ b/docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md @@ -0,0 +1,543 @@ + + + +# 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. diff --git a/docs/plans/001-V0_0_3_PLAN.md b/docs/plans/001-V0_0_3_PLAN.md index 63c58d5..c454e21 100644 --- a/docs/plans/001-V0_0_3_PLAN.md +++ b/docs/plans/001-V0_0_3_PLAN.md @@ -1,5 +1,5 @@ - + # Plan KSP 0.0.3 @@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su - `pre.002` — inventaire initial des composants ; - `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition. -Les tranches `pre.004` (Wire/Program), `pre.005` (Execution/Policy), `pre.006` (Data/Materialization/Store) et `pre.007` (Acquisition/Workers/Jobs) sont maintenant livrées séparément afin de conserver des prereleases de planification bornées. +Les tranches `pre.004` (Wire/Program), `pre.005` (Execution/Policy), `pre.006` (Data/Materialization/Store), `pre.007` (Acquisition/Workers/Jobs) et `pre.008` (Apps/Services/Scenarios/Control) sont maintenant livrées séparément afin de conserver des prereleases de planification bornées. ## Décisions structurantes actuelles @@ -119,15 +119,24 @@ Livré : - PostgreSQL LISTEN/NOTIFY comme wake-up initial de référence + periodic polling ; - batching/concurrence bornés et principe de backpressure observable mais non automatique. -### `pre.008` — Applications, managers, scenarios et orchestration +### `pre.008` — Applications, services, scenarios et control plane -- formaliser les apps spécialisées ; -- détailler `ksp-worker-control-lib` ; -- définir la norme des crates scenario et leurs apps demo ; -- traiter les processus/IPC/managers ; -- cadrer l'orchestrateur futur ; -- déterminer comment apps/managers pilotent workers et jobs sans fusionner leurs lifecycle APIs ; -- inventorier les autres pipelines spécialisés seulement si un besoin concret apparaît. +Livré : + +- applications spécialisées prioritaires sur toute future application globale ; +- future application globale conservée comme idée uniquement ; +- workers confirmés comme services/processus indépendants ; +- direction de packaging : package worker avec cible bibliothèque réutilisable + binaire autonome mince ; +- aucun worker concret ne dépend directement d'un autre worker ; +- data plane D1–D4 séparé du control plane ; +- `ksp-worker-control-lib` comme gouvernance réutilisable ; +- sémantique Worker indépendante du transport local/IPC ; +- aucun `ksp-ipc-api` générique créé prématurément ; +- aucun ordre global strict de démarrage figé ; +- scenarios exécutés dans `ksp-scenario--lib`, jamais dans l'app desktop ; +- `docs/rules/SCENARIO_CONVENTION.md` comme norme souple ; +- applications scenario demo minces et appelables via la crate scenario ; +- `ksp-orchestrator-lib` conservé uniquement comme concept futur. ### `pre.009` — Plan des premières releases fonctionnelles @@ -135,7 +144,8 @@ Livré : - dimensionner chaque release concrète ; - choisir la première release `0.1.N` ; - vérifier l'ordre réel core/logging/config/interface/program/store/transport/workers sans introduire de dépendances circulaires ; -- transformer le brouillon de prompt en prompt quasi-final de cette release concrète. +- positionner explicitement les apps spécialisées/demos avant toute future app globale ; +- transformer le brouillon de prompt en prompt quasi-final de cette première release concrète. ### `pre.010` — Clôture fondatrice diff --git a/docs/rules/RULES_DEPENDENCIES.md b/docs/rules/RULES_DEPENDENCIES.md index 1a15a47..0c19c60 100644 --- a/docs/rules/RULES_DEPENDENCIES.md +++ b/docs/rules/RULES_DEPENDENCIES.md @@ -1,5 +1,5 @@ - + # Règles des dépendances KSP @@ -98,6 +98,21 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur - **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun. - **DEP-JOB-003** — Les jobs de replay réutilisent les pipelines des workers correspondants au lieu de dupliquer la logique D1 -> D2, D2 -> D3 ou D3 -> D4. +## Services, applications et control plane + +- **DEP-SERVICE-001** — Chaque worker concret doit pouvoir fonctionner comme service/processus indépendant. +- **DEP-SERVICE-002** — La direction de packaging préférée est un package `ksp-worker-` contenant une cible bibliothèque réutilisable et une cible binaire autonome mince. +- **DEP-SERVICE-003** — Un worker concret ne dépend pas d'un autre worker concret ; les données transitent par les niveaux durables Store. +- **DEP-SERVICE-004** — Le binaire worker compose/initialise le service mais ne duplique pas le pipeline ou la logique métier de sa cible bibliothèque. +- **DEP-CONTROL-001** — `ksp-worker-api` définit la sémantique de lifecycle indépendamment du transport local/IPC. +- **DEP-CONTROL-002** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et peut plus tard adapter des handles locaux ou proxies distants. +- **DEP-CONTROL-003** — Le control plane ne transporte pas les payloads D1/D2/D3/D4 entre workers. +- **DEP-CONTROL-004** — Aucun `ksp-ipc-api` générique n'est introduit avant le premier besoin concret de transport de control. +- **DEP-APP-001** — Les applications spécialisées sont privilégiées avant une future application globale. +- **DEP-APP-002** — Une app manager worker pilote le service via les contrats de control et ne modifie pas directement son état interne de processing dans PostgreSQL. +- **DEP-SCENARIO-001** — Une app scenario dépend de `ksp-scenario--lib` ; le workflow du scenario ne réside pas dans l'application. +- **DEP-SCENARIO-002** — Une crate scenario ne dépend pas de Tauri et doit pouvoir être appelée depuis d'autres interfaces/tests. + ## Propriété des dépendances Solana - **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir un composant KSP propriétaire précis. diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 00d2213..26e751b 100644 --- a/docs/rules/RULES_KSP.md +++ b/docs/rules/RULES_KSP.md @@ -1,5 +1,5 @@ - + # Règles spécifiques à KSP @@ -110,7 +110,7 @@ - **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job. - **KSP-WORKER-002** — Les contrats communs des workers appartiennent à `ksp-worker-api` et ne contiennent aucun contrat propre aux jobs. - **KSP-WORKER-003** — `ksp-worker-api` est principalement une lifecycle API de services continus : identité, état, health, démarrage/arrêt et événements communs ; les capacités optionnelles ne deviennent universelles que si plusieurs workers les partagent réellement. -- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable par managers desktop, future application globale et orchestrateur ; les apps ne réimplémentent pas cette gouvernance. +- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable d'abord par les apps manager spécialisées, puis éventuellement par un futur orchestrateur/application globale ; les apps ne réimplémentent pas cette gouvernance. - **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique. - **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés. - **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke. @@ -119,6 +119,10 @@ - **KSP-WORKER-010** — `ksp-worker-raw-retriever` distingue une configuration desired et une configuration effective lors des reconfigurations à chaud. - **KSP-WORKER-011** — Un cursor de scan est une optimisation ; les processing outcomes durables constituent la preuve qu'un input a été traité pour un processor/version/capability. - **KSP-WORKER-012** — La concurrence de processing utilise une sémantique de claim/lease récupérable après expiration/crash. +- **KSP-WORKER-013** — Chaque worker doit pouvoir fonctionner comme service/processus indépendant afin d'être arrêté/redémarré/mis à jour sans imposer l'arrêt volontaire des autres workers. +- **KSP-WORKER-014** — La direction de packaging préférée est un package worker avec cible bibliothèque réutilisable et binaire autonome mince. +- **KSP-WORKER-015** — Les workers ne dépendent pas directement les uns des autres ; D1–D4 constituent leur data plane partagé. +- **KSP-WORKER-016** — Aucun ordre global strict de démarrage des workers n'est figé actuellement. ## Jobs @@ -164,6 +168,8 @@ - **KSP-SCENARIO-004** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés. - **KSP-SCENARIO-005** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé. - **KSP-SCENARIO-006** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow. +- **KSP-SCENARIO-007** — La logique fonctionnelle d'un scenario s'exécute dans `ksp-scenario--lib` et reste appelable hors desktop. +- **KSP-SCENARIO-008** — Les scenarios suivent `docs/rules/SCENARIO_CONVENTION.md` tant qu'aucun contrat Rust commun suffisamment utile ne justifie `ksp-scenario-api`. ## Applications @@ -171,3 +177,14 @@ - **KSP-APP-002** — Les applications/demos ne dépendent pas directement de crates Solana/protocoles externes. - **KSP-APP-003** — Les applications/demos peuvent réaliser les opérations strictement liées à l'interface, mais pas la logique métier/protocolaire réutilisable. - **KSP-APP-004** — Une demo scenario desktop consomme la crate `ksp-scenario--lib` correspondante ; elle suit la convention `ksp-app-scenario---desk-demo` lorsque l'environnement est imposé. +- **KSP-APP-005** — Les applications spécialisées précèdent toute future application globale ; aucune app globale n'est un livrable actuel. +- **KSP-APP-006** — Une app manager worker utilise le control plane et ne modifie pas directement l'état interne de processing du worker en base. +- **KSP-APP-007** — Une future application globale est conservée comme idée produit et sera cadrée seulement après validation suffisante des apps spécialisées/demos. + +## Data plane / control plane + +- **KSP-CONTROL-001** — Le data plane des workers passe par transport + D1/D2/D3/D4 et notifications de données persistées. +- **KSP-CONTROL-002** — Le control plane porte lifecycle, status, health et reconfiguration ; il ne transporte pas les payloads de processing entre workers. +- **KSP-CONTROL-003** — La sémantique de `ksp-worker-api` doit rester utilisable avec un handle local ou un futur proxy IPC. +- **KSP-CONTROL-004** — Aucun `ksp-ipc-api` générique n'est prévu actuellement ; le premier manager/service concret doit d'abord démontrer le transport nécessaire. +- **KSP-CONTROL-005** — `ksp-orchestrator-lib` est seulement un concept futur et n'est pas une crate retenue dans le plan actuel. diff --git a/docs/rules/SCENARIO_CONVENTION.md b/docs/rules/SCENARIO_CONVENTION.md new file mode 100644 index 0000000..8d74f49 --- /dev/null +++ b/docs/rules/SCENARIO_CONVENTION.md @@ -0,0 +1,111 @@ + + + +# Convention des scenarios KSP + +## Objet + +KSP n'impose pas actuellement de `ksp-scenario-api`. + +Ce document définit les conventions minimales permettant aux crates `ksp-scenario--lib` de rester cohérentes sans les enfermer dans un trait Rust universel. + +## Source de vérité + +La logique fonctionnelle du scenario appartient à : + +```text +ksp-scenario--lib +``` + +Une application desktop demo, un CLI, un test ou une CI appelle cette bibliothèque et ne recrée pas le workflow. + +## Indépendance de l'interface + +Une crate scenario : + +- ne dépend pas de Tauri ; +- ne contient pas de DTO TS-RS spécifiques à une UI ; +- ne suppose pas qu'une fenêtre desktop existe ; +- reste appelable depuis un test ou autre interface. + +## Environnement + +Un scenario indique explicitement l'environnement/réseau attendu lorsqu'il est contraint. + +Une app demo dont l'environnement est imposé suit la nomenclature : + +```text +ksp-app-scenario---desk-demo +``` + +## Configuration et ressources + +Le scenario utilise les bibliothèques KSP propriétaires de : + +- configuration ; +- wallet ; +- transport ; +- Program ; +- execution ; +- Store lorsque le scenario en a réellement besoin. + +Il ne contourne pas ces frontières avec des dépendances protocolaires/Solana externes directes. + +Les endpoints, wallets et autres ressources utilisées doivent être résolus explicitement ; ils ne sont pas cachés dans l'UI. + +## Execution policy + +Lorsqu'un scenario exécute une opération réelle, il fournit une policy explicite conforme à `ksp-execution-policy-api`. + +Une policy Devnet peut être propre à la crate scenario. + +La policy ne fuit pas dans `ksp-program-lib`. + +## Résultat + +Un scenario doit produire un résultat exploitable par son caller. + +Le résultat devrait permettre selon le besoin de distinguer : + +- succès/échec fonctionnel ; +- étapes exécutées ; +- identités blockchain utiles ; +- validations/evidence ; +- warnings ; +- données de diagnostic non sensibles. + +Le type exact reste spécifique au domaine tant qu'un vrai contrat commun ne justifie pas `ksp-scenario-api`. + +## Validation + +Le scenario contient la logique de validation fonctionnelle nécessaire pour déterminer si son objectif a été atteint. + +L'application demo affiche cette validation mais ne la réimplémente pas. + +## Logging + +La crate scenario utilise `ksp-logging-lib`. + +Les logs peuvent couvrir `error`, `warn`, `info`, `debug` et `trace` selon pertinence. + +Aucun secret, seed, clé privée ou donnée sensible ne doit être loggé. + +## Réutilisation + +Une même crate scenario doit pouvoir être utilisée par plusieurs callers sans duplication : + +```text +desktop demo +test +future CLI/tool +CI/integration + | + v +ksp-scenario--lib +``` + +## Evolution + +Une convention peut être enrichie au fil des scenarios réels. + +`ksp-scenario-api` ne sera introduit que si plusieurs implementations démontrent un contrat commun stable et utile. diff --git a/prompts/001-V0_1_X_START_PROMPT.md b/prompts/001-V0_1_X_START_PROMPT.md index 3390c26..543f9bc 100644 --- a/prompts/001-V0_1_X_START_PROMPT.md +++ b/prompts/001-V0_1_X_START_PROMPT.md @@ -1,5 +1,5 @@ - + # Prompt de démarrage KSP 0.1.x @@ -33,7 +33,7 @@ Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`. ## 5. Sources de vérité -Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `009`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. +Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `010`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. ## 6. Décisions acquises pertinentes