v0.0.3-pre.002
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 7
|
||||
# version: 8
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-core-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.0.3-pre.1"
|
||||
version = "0.0.3-pre.2"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
203
ROADMAP.md
203
ROADMAP.md
@@ -1,9 +1,9 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues pour y parvenir. Il ne remplace ni les plans détaillés de version ni les deltas de livraison.
|
||||
Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues pour y parvenir. Une série `X.Y.x` regroupe une famille fonctionnelle de travaux ; elle peut contenir plusieurs releases concrètes et plusieurs sessions.
|
||||
|
||||
## Légende
|
||||
|
||||
@@ -11,189 +11,92 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues po
|
||||
- `[/]` — en cours ;
|
||||
- `[X]` — réalisé et validé ;
|
||||
- `[C]` — annulé ;
|
||||
- `[R]` — reporté vers une autre phase ou version.
|
||||
- `[R]` — reporté.
|
||||
|
||||
Une case `[X]` signifie que l'étape est considérée terminée selon ses critères de validation, et pas seulement qu'une modification a été écrite.
|
||||
## 0.0.x — Fondation
|
||||
|
||||
## 0.0.x — Fondation de Khadhroony Solana Project
|
||||
|
||||
### Objectifs
|
||||
|
||||
Définir l'identité, les règles, les conventions, l'architecture initiale et le mode de travail de KSP avant le début du développement fonctionnel. La phase doit aboutir à un workspace initial cohérent, à un plan global suffisamment précis pour guider les premières versions de développement et à un prompt de reprise permettant d'ouvrir `0.1.x` sans réinventer les décisions fondatrices.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [X] `0.0.1` — Initialiser le dépôt avec le `.gitignore` de base.
|
||||
- [X] `0.0.2` — Installer le squelette minimal, les règles initiales et les documents de cadrage nécessaires.
|
||||
- [/] `0.0.3` — Définir les objectifs produits, domaines fonctionnels, couches, responsabilités, dépendances, contrats publics, applications/workers/jobs/demos et plan global de développement.
|
||||
- [X] `0.0.1` — Initialiser le dépôt.
|
||||
- [X] `0.0.2` — Installer le squelette minimal et les règles initiales.
|
||||
- [/] `0.0.3` — Définir domaines, composants, dépendances, contrats, workers/jobs/scénarios/apps et plan global.
|
||||
- [/] Construire progressivement le prompt de démarrage `0.1.x`.
|
||||
- [ ] Clôturer la phase fondatrice avec les documents finaux, le squelette nécessaire et le prompt final permettant d'ouvrir `0.1.x`.
|
||||
- [ ] Clôturer la fondation avec documentation, validations et prompt final.
|
||||
|
||||
### Status
|
||||
|
||||
En cours.
|
||||
|
||||
## 0.1.x — Fondations KSP
|
||||
## 0.1.x — Fondations N1
|
||||
|
||||
### Objectifs
|
||||
|
||||
Construire les premières fondations réellement transversales et valider le principe selon lequel une application spécialisée reste une interface au-dessus de la bibliothèque qu'elle manipule.
|
||||
Regrouper les releases consacrées aux fondations N1. La série n'est pas destinée à tenir dans une seule session : chaque release concrète (`0.1.1`, `0.1.2`, etc.) sera dimensionnée séparément.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Stabiliser les premiers contrats de `ksp-core-lib`, dont le type d'erreur commun et les Program IDs.
|
||||
- [ ] Stabiliser `ksp-core-lib`, dont `Error` et Program IDs.
|
||||
- [ ] Introduire `ksp-logging-lib`.
|
||||
- [ ] Introduire `ksp-config-lib`.
|
||||
- [ ] Introduire `ksp-app-config-desk` comme interface de lecture/modification des paramètres autorisés.
|
||||
- [ ] Définir suffisamment tôt les premiers contrats publics nécessaires aux couches suivantes sans implémenter prématurément leurs fonctionnalités.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Introduire `ksp-app-config-desk`.
|
||||
- [ ] Définir au besoin les premiers contrats publics requis par les couches suivantes sans anticiper leur implémentation complète.
|
||||
|
||||
## 0.2.x — Accès Solana et fondation programmes
|
||||
|
||||
### Objectifs
|
||||
|
||||
Fournir les transports et identités nécessaires pour interagir avec Solana, établir la façade wire KSP et exposer les premiers contrats publics extensibles de décodage/exécution.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Introduire `ksp-onchain-transport-lib`.
|
||||
- [ ] Introduire `ksp-wallet-lib`.
|
||||
- [ ] Introduire `ksp-app-wallet-desk`.
|
||||
- [ ] Introduire `ksp-onchain-transport-lib` avec des modèles de transport homogènes indépendants du store.
|
||||
- [ ] Introduire `ksp-wallet-lib` et `ksp-app-wallet-desk`.
|
||||
- [ ] Développer la première surface utile de `ksp-interface-lib`.
|
||||
- [ ] Introduire `ksp-program-api` comme contrat public extensible des decoders/executors.
|
||||
- [ ] Introduire `ksp-program-lib` comme implémentation officielle intégrée des programmes supportés.
|
||||
- [ ] Garantir que les contrats `ksp-program-api` puissent être implémentés et testés depuis des crates séparées sans dépendre de `ksp-program-lib`.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` seulement si un besoin concret apparaît pendant cette phase.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Introduire `ksp-program-api` puis `ksp-program-lib`.
|
||||
- [ ] Étudier/introduire `ksp-execution-policy-api` et `ksp-execution-lib` selon le graphe validé.
|
||||
- [ ] Ne pas créer `ksp-onchain-transport-api` ni `ksp-wallet-api` sans nouveau besoin concret.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` seulement au premier besoin réel.
|
||||
|
||||
## 0.3.x — Données, stockage et acquisition raw
|
||||
|
||||
### Objectifs
|
||||
|
||||
Mettre en place les contrats de matérialisation et de stockage, l'acquisition raw live/quasi-live et des jobs historiques/ponctuels séparés des workers continus.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Introduire `ksp-materializer-api` comme contrat public/extensible de matérialisation.
|
||||
- [ ] Introduire `ksp-materializer-lib` comme implémentation officielle des materializers KSP.
|
||||
- [ ] Introduire `ksp-store-api` comme frontière backend-agnostic et propriétaire des contrats canoniques de notification de données persistées.
|
||||
- [ ] Introduire `ksp-store-lib` avec PostgreSQL comme implémentation de référence.
|
||||
- [ ] Introduire `ksp-materializer-api` / `ksp-materializer-lib`.
|
||||
- [ ] Introduire `ksp-store-api` / `ksp-store-lib` avec PostgreSQL de référence.
|
||||
- [ ] Introduire `ksp-app-store-desk`.
|
||||
- [ ] Introduire W1 pour l'acquisition raw live/quasi-live uniquement.
|
||||
- [ ] Permettre à W1 de modifier à chaud ce qu'il écoute/rapatrie/stocke.
|
||||
- [ ] Introduire `ksp-worker-api` pour les contrats communs des workers sans y inclure les jobs.
|
||||
- [ ] Introduire les premières capacités de contrôle/manager de W1, avec `ksp-worker-control-lib` comme candidat d'implémentation lorsque nécessaire.
|
||||
- [ ] Introduire `ksp-job-api` pour les contrats communs des jobs, séparément des workers.
|
||||
- [ ] Introduire `ksp-job-backfill` comme job historique à la demande, avec checkpoint/reprise et gouvernance propres.
|
||||
- [ ] Utiliser les mêmes contrats de notification de données pour une même donnée, qu'elle provienne de W1, d'un backfill ou d'une autre source.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Introduire `ksp-worker-api` et `ksp-worker-raw-retriever`.
|
||||
- [ ] Introduire `ksp-worker-control-lib` lorsque le manager W1 crée le premier besoin concret.
|
||||
- [ ] Introduire `ksp-job-api` et `ksp-job-backfill`.
|
||||
- [ ] Normaliser les notifications de données persistées indépendamment de leur producteur.
|
||||
|
||||
## 0.4.x — Baseline Solana, SPL et metadata
|
||||
|
||||
### Objectifs
|
||||
|
||||
Commencer la couverture fonctionnelle des programmes nécessaires à l'objectif trading court terme et aux couches suivantes, en validant décodage, exécution technique, matérialisation et scénarios spécialisés.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Ajouter les premiers decoders/executors Solana Core utiles.
|
||||
- [ ] Ajouter les premières surfaces SPL utiles : Token, Token-2022, ATA et autres besoins identifiés.
|
||||
- [ ] Ajouter les metadata d'assets/tokens nécessaires.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` au plus tard au premier besoin réel externe.
|
||||
- [ ] Ajouter les materializers correspondants.
|
||||
- [ ] Ajouter les jobs ponctuels nécessaires, par exemple metadata/off-chain, uniquement lorsqu'un besoin concret le justifie.
|
||||
- [ ] Ajouter les tools/scénarios de validation spécialisés dans des crates séparées par domaine cohérent.
|
||||
- [ ] Maintenir les demos/scénarios Memo, Token, ATA et Token-2022 séparés.
|
||||
- [ ] Permettre une famille metadata commune pour Metaplex Token Metadata + Token-2022 Metadata.
|
||||
- [ ] Maintenir Solana Program Metadata dans une famille distincte.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Ajouter progressivement les decoders/executors Core/SPL nécessaires.
|
||||
- [ ] Ajouter Token, Token-2022, ATA et metadata utiles.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` au plus tard au premier besoin externe.
|
||||
- [ ] Ajouter materializers et jobs ponctuels nécessaires.
|
||||
- [ ] Ajouter les crates `ksp-scenario-<domain>-lib` spécialisées.
|
||||
- [ ] Ajouter les demos `ksp-app-scenario-<domain>-<environment>-desk-demo` correspondantes.
|
||||
- [ ] Garder Memo, Token, ATA, Token-2022 séparés ; regrouper uniquement Metaplex Token Metadata + Token-2022 Metadata dans la famille metadata ; garder SPM séparé.
|
||||
|
||||
## 0.5.x — Anchor et protocoles trading
|
||||
|
||||
### Objectifs
|
||||
|
||||
Étendre progressivement KSP vers Anchor et les protocoles/infrastructures nécessaires à l'analyse et au trading Solana, une surface cohérente et bornée par release.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Introduire la fondation Anchor.
|
||||
- [ ] Étendre progressivement Meteora par surfaces distinctes.
|
||||
- [ ] Étendre progressivement Raydium par surfaces distinctes.
|
||||
- [ ] Introduire Anchor.
|
||||
- [ ] Étendre Meteora par surfaces bornées.
|
||||
- [ ] Étendre Raydium par surfaces bornées.
|
||||
- [ ] Ajouter progressivement Pump, Orca, Jupiter, OKX et autres intégrations utiles.
|
||||
- [ ] Ajouter pour chaque surface les interfaces, decoders/executors, materializers, jobs éventuels, scénarios et validations nécessaires.
|
||||
- [ ] Maintenir l'ordre précis des releases adaptable aux dépendances découvertes et aux priorités du trading court terme.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Ajouter interfaces, program implementations, materializers, jobs/scénarios/demos nécessaires pour chaque surface.
|
||||
|
||||
## 0.6.x — Processing autonome et orchestration
|
||||
|
||||
### Objectifs
|
||||
|
||||
Introduire le processing continu des données acquises, la gouvernance de plusieurs workers et une application globale de supervision sans déplacer leur logique dans l'interface.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Introduire W2 pour les traitements live de décodage/matérialisation selon les contrats alors stabilisés.
|
||||
- [ ] Réutiliser `ksp-worker-api` pour les contrats communs des workers.
|
||||
- [ ] Introduire/étendre `ksp-worker-control-lib` lorsque plusieurs workers justifient un contrôle commun.
|
||||
- [ ] Garder les contrats et contrôles des jobs séparés de ceux des workers.
|
||||
- [ ] Introduire un orchestrateur commun lorsque plusieurs managers/workers le justifient.
|
||||
- [ ] Introduire une application globale de supervision et contrôle.
|
||||
- [ ] Exposer les états, health, backlog, erreurs, reprises et commandes nécessaires sans dupliquer la logique des workers/jobs.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Introduire `ksp-worker-core-processor` pour raw -> Core canonique.
|
||||
- [ ] Introduire `ksp-worker-generic-materializer` pour Core -> matérialisation générique.
|
||||
- [ ] Introduire `ksp-worker-domain-projector` pour les projections spécialisées ; nom révisable.
|
||||
- [ ] Étendre `ksp-worker-control-lib` à la gouvernance de plusieurs workers.
|
||||
- [ ] 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
|
||||
|
||||
### Objectifs
|
||||
- [ ] Statistiques et métriques.
|
||||
- [ ] Features et datasets historiques.
|
||||
- [ ] Signaux et risque.
|
||||
- [ ] Replay analytique/backtests.
|
||||
- [ ] Patterns/anomalies.
|
||||
- [ ] XGBoost puis autres modèles lorsque les contrats sont stables.
|
||||
|
||||
Construire la couche d'analyse statistique et d'intelligence nécessaire aux futures automatisations de trading, avant de stabiliser l'application de trading proprement dite.
|
||||
## 0.8.x et suivantes — Trading opérationnel et expansion produits
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Définir statistiques et métriques utiles.
|
||||
- [ ] Définir les features et datasets historiques.
|
||||
- [ ] Définir les contrats de signal et risque.
|
||||
- [ ] Introduire replay analytique et backtests.
|
||||
- [ ] Détecter patterns et anomalies.
|
||||
- [ ] Intégrer XGBoost lorsque les contrats d'entrée/sortie sont suffisamment stables.
|
||||
- [ ] Préparer l'intégration d'autres modèles et les futures couches de décision/automatisation.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
|
||||
## 0.8.x et suivantes — Extension continue et applications trading
|
||||
|
||||
### Objectifs
|
||||
|
||||
Poursuivre la couverture Solana, exploiter Trading Intelligence dans des couches de trading opérationnelles puis faire évoluer les autres produits au-dessus des mêmes contrats KSP.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Étendre continuellement les Program IDs, interfaces, decoders/executors et materializers utiles.
|
||||
- [ ] Construire progressivement les couches de trading opérationnelles et l'application de trading monoposte.
|
||||
- [ ] Construire les couches puis l'application de trading monoposte au-dessus de Trading Intelligence.
|
||||
- [ ] Étendre l'automatisation de trading.
|
||||
- [ ] Étendre continuellement Program IDs, decoders/executors/materializers.
|
||||
- [ ] Construire progressivement l'explorer Solana.
|
||||
- [ ] Construire progressivement l'explorer/analyse DEX.
|
||||
- [ ] Étendre Trading Intelligence et les modèles disponibles.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
- [ ] Étudier plus tard d'autres applications utilisant `ksp-wallet-lib`, notamment mobile, extensions navigateur et web.
|
||||
|
||||
139
deltas/0.0.3/pre.002.md
Normal file
139
deltas/0.0.3/pre.002.md
Normal file
@@ -0,0 +1,139 @@
|
||||
<!-- file: deltas/0.0.3/pre.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.002
|
||||
|
||||
## Base requise
|
||||
|
||||
`v0.0.3-pre.001` incluant les corrections `pre.001-fix.001` à `pre.001-fix.004`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Produire le premier inventaire formel des composants KSP et enregistrer les dernières frontières décidées avant l'étude du graphe de dépendances.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe de :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
à :
|
||||
|
||||
```text
|
||||
0.0.3-pre.2
|
||||
```
|
||||
|
||||
Le header de `Cargo.toml` passe de version 7 à 8.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/architecture/004-COMPONENT_INVENTORY.md`
|
||||
- `deltas/0.0.3/pre.002.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `ROADMAP.md`
|
||||
- `docs/architecture/000-README.md`
|
||||
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
- `docs/rules/PROMPT_STRUCTURE.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
|
||||
|
||||
### Séries et releases
|
||||
|
||||
`0.1.x`, `0.2.x`, etc. sont des séries fonctionnelles et peuvent couvrir plusieurs releases/sessions.
|
||||
|
||||
Le contrôle de charge porte sur chaque release concrète (`0.1.1`, `0.1.2`, etc.) et ses prereleases, pas sur toute la série.
|
||||
|
||||
### Workers
|
||||
|
||||
Noms retenus :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
ksp-worker-core-processor
|
||||
ksp-worker-generic-materializer
|
||||
ksp-worker-domain-projector
|
||||
```
|
||||
|
||||
Le nom du dernier reste révisable.
|
||||
|
||||
Le processing futur n'est donc plus modélisé comme un unique W2 monolithique.
|
||||
|
||||
### Execution policy / orchestration
|
||||
|
||||
`ksp-execution-policy-api` devient un candidat fort pour permettre des policies différentes selon le contexte.
|
||||
|
||||
`ksp-execution-lib` devient un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport.
|
||||
|
||||
Le graphe exact est explicitement reporté à `pre.003`.
|
||||
|
||||
### Transport
|
||||
|
||||
Aucune `ksp-onchain-transport-api` ni `ksp-offchain-transport-api`.
|
||||
|
||||
`ksp-onchain-transport-lib` ne dépend pas du store mais doit exposer des modèles homogènes facilement convertibles vers les modèles raw de `ksp-store-api`.
|
||||
|
||||
`ksp-offchain-transport-lib` reste volontairement hétérogène.
|
||||
|
||||
### Wallet
|
||||
|
||||
Aucune `ksp-wallet-api`.
|
||||
|
||||
Des applications wallet futures sont ajoutées aux idées : Android, extensions Firefox/Chrome et wallet web.
|
||||
|
||||
### Worker/job lifecycle
|
||||
|
||||
`ksp-worker-api` et `ksp-job-api` sont confirmées comme lifecycle APIs séparées.
|
||||
|
||||
`ksp-worker-control-lib` est destiné à être réutilisé par les managers/apps/orchestrateur.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement.
|
||||
|
||||
### Notifications de données
|
||||
|
||||
Les notifications restent normalisées selon la donnée persistée et non selon le producteur. `ksp-store-api` reste leur propriétaire candidat.
|
||||
|
||||
### Scénarios
|
||||
|
||||
`ksp-scenario-api` n'est pas retenu actuellement. Une norme souple de scénarios spécialisés est préférée.
|
||||
|
||||
Les apps desktop de démonstration utilisent la forme :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
```
|
||||
|
||||
et réutilisent `ksp-scenario-<domain>-lib`.
|
||||
|
||||
### Pipelines
|
||||
|
||||
Toujours aucun `ksp-pipeline-lib` monolithique. Des pipelines spécialisés sont créés uniquement à la demande.
|
||||
|
||||
## Questions reportées à pre.003
|
||||
|
||||
- graphe exact program/execution/policy/wallet/transport ;
|
||||
- choix `ksp-program-api` vs `ksp-program-lib` comme dépendance de l'orchestration ;
|
||||
- frontières des modèles d'exécution préparée ;
|
||||
- modèles de transport homogènes et conversion vers store raw ;
|
||||
- dépendances materializer/store/notifications ;
|
||||
- prévention des cycles ;
|
||||
- corrections éventuelles de l'inventaire `pre.002`.
|
||||
|
||||
## Validations
|
||||
|
||||
- en-têtes `file:` / `version:` vérifiés sur les fichiers Markdown livrés ;
|
||||
- `Cargo.toml` vérifié syntaxiquement et versionné `0.0.3-pre.2` ;
|
||||
- cohérence des références vers `004-COMPONENT_INVENTORY.md` vérifiée ;
|
||||
- aucune commande Cargo exécutée sur l'archive delta seule, qui ne contient pas le workspace complet.
|
||||
129
docs/IDEAS.md
129
docs/IDEAS.md
@@ -1,8 +1,19 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
Ce document conserve les idées, pistes, questions et alternatives qui méritent d'être étudiées sans constituer encore un engagement de développement ou une décision architecturale.
|
||||
|
||||
## Statuts
|
||||
|
||||
- `À explorer`
|
||||
- `En exploration`
|
||||
- `Retenue`
|
||||
- `Rejetée`
|
||||
- `Transférée au roadmap`
|
||||
- `Transférée vers une décision/règle`
|
||||
|
||||
## APIs et extensibilité
|
||||
|
||||
### Nomenclature `*-api`
|
||||
@@ -11,38 +22,41 @@
|
||||
|
||||
Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
|
||||
Premiers couples retenus :
|
||||
Premiers couples retenus : program, materializer et store. Les APIs worker/job sont des lifecycle APIs distinctes.
|
||||
|
||||
```text
|
||||
ksp-program-api / ksp-program-lib
|
||||
ksp-materializer-api / ksp-materializer-lib
|
||||
ksp-store-api / ksp-store-lib
|
||||
```
|
||||
### Execution policy API
|
||||
|
||||
Éviter un unique `ksp-api-lib` monolithique.
|
||||
**Status :** En exploration — candidat fort
|
||||
|
||||
### APIs workers et jobs
|
||||
Étudier `ksp-execution-policy-api` comme contrat commun d'autorisation/safety/policy d'une exécution.
|
||||
|
||||
Le contrat doit permettre des implémentations différentes selon le contexte, par exemple scenario Devnet, application générale ou futur produit trading.
|
||||
|
||||
L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas devenir propriétaire d'une politique complexe.
|
||||
|
||||
### Execution orchestration
|
||||
|
||||
**Status :** En exploration — candidat fort
|
||||
|
||||
Étudier `ksp-execution-lib` comme orchestration spécialisée entre programme, policy, wallet et transport, plutôt qu'une dépendance directe de `ksp-program-lib` vers wallet/transport.
|
||||
|
||||
Le graphe exact est reporté à `0.0.3-pre.003`.
|
||||
|
||||
### Scenarios : norme avant API
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Les workers et jobs ont des modèles de lifecycle différents et ne doivent pas partager une API universelle commune.
|
||||
Ne pas créer `ksp-scenario-api` pour l'instant.
|
||||
|
||||
Prévoir séparément :
|
||||
Définir d'abord une norme souple de structure, métadonnées, exécution et résultat des crates `ksp-scenario-<domain>-lib`, sans imposer un trait Rust qui limiterait des scénarios hétérogènes.
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
ksp-job-api
|
||||
```
|
||||
|
||||
`ksp-worker-control-lib` reste un candidat d'implémentation de contrôle des workers uniquement.
|
||||
|
||||
Le besoin éventuel d'une implémentation commune de contrôle des jobs sera évalué séparément.
|
||||
Réévaluer seulement si les premières implémentations révèlent un vrai contrat commun.
|
||||
|
||||
### Type d'erreur KSP unique
|
||||
|
||||
**Status :** En exploration
|
||||
|
||||
La direction retenue est un seul type public `ksp_core_lib::Error` consommable par le workspace, sans obliger `ksp-core-lib` à connaître chaque domaine supérieur.
|
||||
La direction retenue est un seul type public `ksp_core_lib::Error` consommable par le workspace sans obliger `ksp-core-lib` à connaître chaque domaine supérieur.
|
||||
|
||||
### Nommage des items publics
|
||||
|
||||
@@ -54,51 +68,74 @@ Définir avec les premières APIs réelles les conventions de nommage des traits
|
||||
|
||||
**Status :** À explorer
|
||||
|
||||
Définir avec les premières crates fonctionnelles les conventions d'arborescence des modules/fichiers, façades `lib.rs`, modules API et réexports publics.
|
||||
Définir avec les premières crates fonctionnelles les conventions d'arborescence, façades `lib.rs`, modules API et réexports publics.
|
||||
|
||||
## Données et notifications
|
||||
## Transport
|
||||
|
||||
### Notifications normalisées de données
|
||||
### Modèles homogènes on-chain
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Une notification de donnée doit avoir la même représentation canonique pour le même type de donnée quelle que soit son origine.
|
||||
`ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`, mais ses différents providers doivent exposer des modèles homogènes par catégorie de données afin que `ksp-worker-raw-retriever` puisse les convertir simplement vers les modèles raw persistants du store.
|
||||
|
||||
`ksp-store-api` est le propriétaire candidat de ces contrats lorsque la notification signifie qu'une donnée persistée est disponible.
|
||||
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
||||
|
||||
Le transport concret de notification reste indépendant du contrat.
|
||||
|
||||
### Backend PostgreSQL
|
||||
### Off-chain volontairement hétérogène
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation de référence de `ksp-store-api`.
|
||||
`ksp-offchain-transport-lib` regroupe metadata, prix, quotes, routage et autres accès externes afin d'éviter une explosion de crates. Il n'est pas nécessaire de leur inventer une API métier commune.
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
### W1
|
||||
### Workers de processing
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
W1 reste strictement un worker raw live/quasi-live avec reconfiguration à chaud, persistance raw et notification. Aucun replay/backfill.
|
||||
Après `ksp-worker-raw-retriever`, les responsabilités de processing actuellement prévues sont séparées :
|
||||
|
||||
### Backfill historique
|
||||
- `ksp-worker-core-processor` ;
|
||||
- `ksp-worker-generic-materializer` ;
|
||||
- `ksp-worker-domain-projector` (nom provisoire).
|
||||
|
||||
**Status :** Retenue
|
||||
### Worker control
|
||||
|
||||
Le backfill historique est un job distinct, candidat `ksp-job-backfill`.
|
||||
**Status :** Retenue comme direction
|
||||
|
||||
### Autres jobs
|
||||
`ksp-worker-control-lib` doit être une implémentation réutilisable de gouvernance consommable par des applications desktop manager, une future application globale et l'orchestrateur.
|
||||
|
||||
**Status :** Retenue
|
||||
### Job control
|
||||
|
||||
Des jobs séparés pourront apparaître pour metadata, quotes ou autres traitements ponctuels lorsqu'un besoin réel existe.
|
||||
**Status :** Rejetée pour l'instant
|
||||
|
||||
### Orchestrateur
|
||||
Ne pas créer `ksp-job-control-lib` sans duplication concrète entre plusieurs jobs. `ksp-job-api` suffit comme lifecycle API commune tant que chaque job peut être gouverné directement via son implémentation.
|
||||
|
||||
**Status :** Retenue
|
||||
## Wallet : applications futures
|
||||
|
||||
Commencer par des managers séparés. Introduire un orchestrateur global lorsque plusieurs workers/managers le justifient. Les jobs restent gouvernés par leurs contrats propres.
|
||||
### Wallet Android
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Une application Android native utilisant `ksp-wallet-lib` est envisagée. Nom exact à définir plus tard, candidat : `ksp-app-wallet-android`.
|
||||
|
||||
### Extensions navigateur
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Prévoir potentiellement des extensions Firefox et Chrome consommant les capacités KSP appropriées. Noms candidats non normatifs :
|
||||
|
||||
```text
|
||||
ksp-app-wallet-firefox-extension
|
||||
ksp-app-wallet-chrome-extension
|
||||
```
|
||||
|
||||
Le modèle de sécurité, la frontière Rust/WebAssembly/native et le stockage des secrets devront être étudiés avant toute décision.
|
||||
|
||||
### Wallet web
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Un wallet web/online utilisant les contrats KSP est envisagé. La gestion des secrets et le modèle de confiance devront être traités comme une question architecturale majeure avant développement.
|
||||
|
||||
## Pipelines
|
||||
|
||||
@@ -106,17 +143,7 @@ Commencer par des managers séparés. Introduire un orchestrateur global lorsque
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément à la demande avec un périmètre borné.
|
||||
|
||||
## Scénarios
|
||||
|
||||
### Crates spécialisées
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Ne pas créer de `ksp-scenarios-lib` monolithique. Utiliser des crates spécialisées `ksp-scenario-<domain>-lib`.
|
||||
|
||||
Memo, Token classique, ATA et Token-2022 restent séparés. Metaplex Token Metadata et Token-2022 Metadata peuvent partager une famille metadata ; Solana Program Metadata reste séparé.
|
||||
Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément à la demande avec un périmètre concret.
|
||||
|
||||
## Trading
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
@@ -19,6 +19,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
|
||||
|
||||
1. [`001-PROJECT_OBJECTIVES.md`](001-PROJECT_OBJECTIVES.md) — finalité, objectifs produits et non-objectifs architecturaux ;
|
||||
2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ;
|
||||
3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants, contrats à définir tôt et responsabilités déjà acquises.
|
||||
3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ;
|
||||
4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — premier inventaire des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates.
|
||||
|
||||
Les futurs documents prioritaires peuvent continuer avec `004-`, `005-`, etc. lorsqu'un ordre de lecture explicite apporte une valeur réelle.
|
||||
L'inventaire `004` est volontairement révisable pendant `0.0.3-pre.003` lorsque le graphe de dépendances révélera des frontières à corriger.
|
||||
|
||||
@@ -1,127 +1,144 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
## Objet
|
||||
|
||||
Ce document enregistre les frontières déjà suffisamment claires pour guider la planification. Il ne définit pas encore les API Rust finales.
|
||||
|
||||
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).
|
||||
|
||||
## Convention API / implémentation
|
||||
|
||||
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare :
|
||||
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP peut séparer :
|
||||
|
||||
```text
|
||||
ksp-<domain>-api
|
||||
ksp-<domain>-lib
|
||||
```
|
||||
|
||||
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`. Elle expose principalement des traits, types, enums et contrats publics ; elle peut être consommée par plusieurs implémentations et n'est pas, à elle seule, une implémentation fonctionnelle destinée aux exécutables.
|
||||
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`.
|
||||
|
||||
La crate `ksp-<domain>-lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe.
|
||||
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
|
||||
|
||||
Cette séparation n'est pas automatique pour tous les domaines. Elle est utilisée lorsqu'une vraie frontière d'extension ou de backend justifie une API indépendante.
|
||||
Couples retenus :
|
||||
|
||||
Premiers couples retenus :
|
||||
```text
|
||||
ksp-program-api / ksp-program-lib
|
||||
ksp-materializer-api / ksp-materializer-lib
|
||||
ksp-store-api / ksp-store-lib
|
||||
```
|
||||
|
||||
- `ksp-program-api` + `ksp-program-lib` ;
|
||||
- `ksp-materializer-api` + `ksp-materializer-lib` ;
|
||||
- `ksp-store-api` + `ksp-store-lib`.
|
||||
|
||||
Un unique `ksp-api-lib` monolithique est rejeté.
|
||||
|
||||
## `ksp-program-api` / `ksp-program-lib`
|
||||
|
||||
`ksp-program-api` possède les contrats publics communs de décodage/exécution. Une crate séparée doit pouvoir implémenter et tester ces contrats sans dépendre de `ksp-program-lib`.
|
||||
|
||||
`ksp-program-lib` contient les implémentations officielles intégrées des Program IDs supportés.
|
||||
|
||||
Le decoder vise toute surface techniquement décodable dont la définition est connue. Le statut `deprecated` concerne l'exécution, pas le décodage. Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
|
||||
|
||||
L'executor expose les opérations techniquement exécutables connues ; une opération obsolète mais encore identifiable/exécutable peut rester implémentée et être marquée `deprecated`. La politique de sécurité appartient à une couche supérieure.
|
||||
|
||||
## `ksp-materializer-api` / `ksp-materializer-lib`
|
||||
|
||||
`ksp-materializer-api` possède les contrats publics/extensibles de matérialisation. Une crate externe doit pouvoir implémenter un materializer contre cette API sans dépendre de `ksp-materializer-lib`.
|
||||
|
||||
`ksp-materializer-lib` contient les materializers officiels intégrés KSP.
|
||||
|
||||
## `ksp-store-api` / `ksp-store-lib`
|
||||
|
||||
`ksp-store-api` possède les contrats backend-agnostic de persistance et d'accès aux données KSP.
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence : configuration/connexion, migrations, repositories, queries et mécanismes backend nécessaires.
|
||||
|
||||
Les applications, workers, jobs et materializers consomment les contrats KSP et ne contournent pas le store pour accéder directement au backend.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
Une notification de donnée décrit la donnée disponible, pas son producteur.
|
||||
|
||||
Le même type de donnée doit utiliser le même contrat de notification qu'elle provienne :
|
||||
|
||||
- de W1 ;
|
||||
- d'un job de backfill ;
|
||||
- d'un import ;
|
||||
- d'une autre source future.
|
||||
|
||||
`ksp-store-api` est le propriétaire candidat des références/événements canoniques indiquant qu'une donnée persistée est disponible, par exemple conceptuellement `RawDataRef` / `RawDataAvailable`.
|
||||
|
||||
Le contrat de notification reste distinct du mécanisme de transport concret : channel in-process, PostgreSQL LISTEN/NOTIFY, IPC, broker ou autre mécanisme futur.
|
||||
|
||||
## Workers
|
||||
|
||||
Les workers sont des services continus/live. Leurs contrats communs appartiennent à :
|
||||
APIs lifecycle retenues :
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
```
|
||||
|
||||
Cette API ne contient aucun contrat de job.
|
||||
|
||||
Une future implémentation commune de gouvernance/contrôle des workers peut vivre dans :
|
||||
|
||||
```text
|
||||
ksp-worker-control-lib
|
||||
```
|
||||
|
||||
W1 reste un worker d'acquisition raw live/quasi-live : configuration, transport, persistance raw, reconfiguration à chaud et notification de disponibilité. Il ne décode pas, ne matérialise pas et ne réalise aucun replay/backfill historique.
|
||||
|
||||
## Jobs
|
||||
|
||||
Les jobs sont des travaux déclenchés à la demande, suivables et terminables. Leurs contrats communs appartiennent à :
|
||||
|
||||
```text
|
||||
ksp-job-api
|
||||
```
|
||||
|
||||
Cette API ne contient aucun contrat de worker.
|
||||
Aucune API commune worker+job n'est prévue.
|
||||
|
||||
Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
## Execution policy
|
||||
|
||||
Premier candidat retenu :
|
||||
`ksp-program-lib` ne possède pas la politique de sécurité/autorisation d'un produit.
|
||||
|
||||
La direction retenue pour étude est un contrat public séparé :
|
||||
|
||||
```text
|
||||
ksp-job-backfill
|
||||
ksp-execution-policy-api
|
||||
```
|
||||
|
||||
D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe.
|
||||
Il doit permettre à différents contextes de fournir leurs propres décisions de policy sans modifier `ksp-program-lib` : scenario Devnet, application générale, futur produit trading, etc.
|
||||
|
||||
Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires.
|
||||
Les applications UI sélectionnent/injectent une implémentation réutilisable appropriée ; elles ne doivent pas enfouir une politique complexe directement dans la couche d'interface.
|
||||
|
||||
## Execution orchestration
|
||||
|
||||
`ksp-execution-lib` devient un candidat fort de pipeline/orchestrateur spécialisé pour relier :
|
||||
|
||||
- la préparation/sémantique programme ;
|
||||
- une implémentation de `ksp-execution-policy-api` ;
|
||||
- `ksp-wallet-lib` ;
|
||||
- `ksp-onchain-transport-lib`.
|
||||
|
||||
Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature.
|
||||
|
||||
Le graphe exact reste à valider dans `pre.003`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
||||
|
||||
`ksp-onchain-transport-lib` regroupe les transports/providers on-chain et expose des modèles de sortie homogènes par catégorie de données.
|
||||
|
||||
Il ne dépend pas de `ksp-store-api`.
|
||||
|
||||
Les modèles de transport doivent cependant être conçus pour une conversion explicite et simple vers les modèles raw persistants du store, sans décodage protocolaire.
|
||||
|
||||
## Transport off-chain
|
||||
|
||||
Aucune `ksp-offchain-transport-api` commune n'est prévue.
|
||||
|
||||
La crate est volontairement hétérogène : metadata, prix, quotes, routage et autres ressources externes peuvent avoir des modules/APIs distincts à l'intérieur d'une seule crate afin d'éviter une prolifération de crates artificielles.
|
||||
|
||||
## Wallet
|
||||
|
||||
Aucune `ksp-wallet-api` n'est prévue.
|
||||
|
||||
`ksp-wallet-lib` possède le format wallet KSP et les capacités de lecture/protection/import/export/pubkey/secret/signature nécessaires à ses consommateurs.
|
||||
|
||||
## Store et notifications de données
|
||||
|
||||
`ksp-store-api` reste la frontière backend-agnostic. `ksp-store-lib` contient PostgreSQL comme implémentation de référence.
|
||||
|
||||
Les notifications de données persistées sont normalisées indépendamment de leur producteur. W1, un job de backfill ou un import utilisent le même contrat pour signaler le même type de donnée.
|
||||
|
||||
Le contrat de notification est distinct de son transport concret.
|
||||
|
||||
## Workers
|
||||
|
||||
`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.
|
||||
|
||||
Workers actuellement retenus :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
ksp-worker-core-processor
|
||||
ksp-worker-generic-materializer
|
||||
ksp-worker-domain-projector
|
||||
```
|
||||
|
||||
Le dernier nom reste provisoire.
|
||||
|
||||
## Jobs
|
||||
|
||||
`ksp-job-api` est une lifecycle API distincte pour travaux déclenchés et terminables.
|
||||
|
||||
`ksp-job-backfill` est retenu pour le backfill historique.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement. D'autres jobs pourront apparaître pour metadata, quotes ou autres besoins ponctuels.
|
||||
|
||||
## Scénarios
|
||||
|
||||
Les scénarios restent dans des crates spécialisées `ksp-scenario-<domain>-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é.
|
||||
|
||||
Les demos desktop de scénario suivent provisoirement la forme :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
```
|
||||
|
||||
et réutilisent la crate de scénario correspondante.
|
||||
|
||||
## Pipelines
|
||||
|
||||
KSP ne prévoit pas de `ksp-pipeline-lib` monolithique. Lorsqu'un pipeline réutilisable devient nécessaire, il est introduit séparément avec un périmètre concret et borné.
|
||||
Aucun `ksp-pipeline-lib` monolithique.
|
||||
|
||||
## Demos et scénarios
|
||||
|
||||
Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
|
||||
Les scénarios sont organisés en crates spécialisées par domaine cohérent, par exemple :
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata. Solana Program Metadata reste séparé.
|
||||
Des pipelines spécialisés peuvent être ajoutés à la demande. `ksp-execution-lib` est justement étudié comme un pipeline/orchestrateur spécialisé, pas comme une infrastructure universelle.
|
||||
|
||||
271
docs/architecture/004-COMPONENT_INVENTORY.md
Normal file
271
docs/architecture/004-COMPONENT_INVENTORY.md
Normal file
@@ -0,0 +1,271 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
## Objet
|
||||
|
||||
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é ?**
|
||||
|
||||
Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit explicitement pouvoir corriger cet inventaire lorsque l'étude des dépendances montre qu'une API, une bibliothèque ou une frontière doit être déplacée, séparée ou supprimée.
|
||||
|
||||
## Statuts
|
||||
|
||||
- **Retenu** — composant ou responsabilité considérée nécessaire dans la trajectoire actuelle ;
|
||||
- **Candidat fort** — composant très probable mais dont la frontière exacte doit encore être validée ;
|
||||
- **Futur retenu** — responsabilité acquise mais implémentation différée ;
|
||||
- **À la demande** — ne doit être créé que lorsqu'un premier besoin concret le justifie ;
|
||||
- **Non retenu actuellement** — idée volontairement non créée ; elle peut être réévaluée si l'usage réel change.
|
||||
|
||||
## Inventaire synthétique
|
||||
|
||||
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|
||||
|-------------------------|---------------------------------------------|---------------|-------------------|-----------------------------------|----------------------------|-------------------------------------------------------------------------------------------|
|
||||
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
|
||||
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
|
||||
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun |
|
||||
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
|
||||
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics decoder/executor et types associés |
|
||||
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
|
||||
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Candidat fort | `0.2.x–0.4.x` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
|
||||
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Candidat fort | `0.2.x–0.4.x` | orchestration spécialisée entre opération préparée, policy, wallet et transport |
|
||||
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
|
||||
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
|
||||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||||
| 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 |
|
||||
| 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 | Candidat fort | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
|
||||
| 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 |
|
||||
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
|
||||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||||
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
|
||||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||||
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
|
||||
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||||
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
|
||||
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
|
||||
|
||||
## APIs séparées retenues
|
||||
|
||||
Les couples suivants ont une justification d'extensibilité suffisante :
|
||||
|
||||
```text
|
||||
ksp-program-api -> ksp-program-lib
|
||||
ksp-materializer-api -> ksp-materializer-lib
|
||||
ksp-store-api -> ksp-store-lib
|
||||
```
|
||||
|
||||
Les APIs lifecycle sont également séparées :
|
||||
|
||||
```text
|
||||
ksp-worker-api -> workers continus
|
||||
ksp-job-api -> jobs terminables
|
||||
```
|
||||
|
||||
Aucune API commune worker+job n'est prévue.
|
||||
|
||||
## Execution policy et orchestration
|
||||
|
||||
### Direction retenue pour étude en `pre.003`
|
||||
|
||||
La direction privilégiée est une orchestration supérieure plutôt qu'une dépendance directe de `ksp-program-lib` vers le wallet et le transport :
|
||||
|
||||
```text
|
||||
policy implementation
|
||||
^
|
||||
|
|
||||
ksp-execution-policy-api
|
||||
^
|
||||
|
|
||||
ksp-execution-lib
|
||||
/ | \
|
||||
/ | \
|
||||
program side wallet onchain transport
|
||||
```
|
||||
|
||||
`ksp-program-lib` doit rester propriétaire de la sémantique technique des programmes et de la préparation des opérations, sans posséder la politique de sécurité d'un produit ni le cycle réseau complet.
|
||||
|
||||
`ksp-execution-policy-api` permettrait plusieurs politiques incompatibles mais conformes au même contrat, par exemple :
|
||||
|
||||
- politique permissive et bornée d'un scénario Devnet ;
|
||||
- politique plus stricte d'une future application générale ;
|
||||
- politique spécialisée d'un futur produit de trading.
|
||||
|
||||
Une application UI ne doit pas enfouir cette logique dans ses commandes ou composants. Elle sélectionne/injecte une implémentation réutilisable située dans la crate de scénario ou de domaine appropriée.
|
||||
|
||||
Aucune `ksp-execution-policy-lib` générique n'est retenue actuellement. Des implémentations réutilisables pourront être créées plus tard si plusieurs consommateurs partagent réellement la même politique.
|
||||
|
||||
Le graphe exact `ksp-execution-lib -> ksp-program-api` ou `ksp-program-lib`, ainsi que la forme des plans/opérations préparées, est explicitement reporté à `pre.003/pre.004`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
Aucune crate `ksp-onchain-transport-api` n'est prévue.
|
||||
|
||||
`ksp-onchain-transport-lib` peut contenir plusieurs familles hétérogènes :
|
||||
|
||||
- HTTP RPC ;
|
||||
- WebSocket RPC ;
|
||||
- Helius avancé ;
|
||||
- Yellowstone ;
|
||||
- autres providers/transports futurs.
|
||||
|
||||
Les adapters providers doivent toutefois faire sortir de la crate des **modèles de transport homogènes par catégorie de donnée**, afin que les consommateurs n'aient pas à comprendre chaque réponse propriétaire.
|
||||
|
||||
Ces modèles :
|
||||
|
||||
- restent indépendants de `ksp-store-api` ;
|
||||
- conservent les informations raw/provenance nécessaires ;
|
||||
- ne réalisent aucun décodage métier/protocolaire ;
|
||||
- doivent être facilement et explicitement convertibles par `ksp-worker-raw-retriever` vers les modèles raw persistants de `ksp-store-api`.
|
||||
|
||||
Le détail de cette frontière de conversion est reporté à `pre.003/pre.005`.
|
||||
|
||||
## Transport off-chain
|
||||
|
||||
Aucune crate `ksp-offchain-transport-api` ni trait global `OffchainTransport` n'est prévu.
|
||||
|
||||
`ksp-offchain-transport-lib` regroupe volontairement des accès hétérogènes afin d'éviter une explosion de petites crates. Metadata externes, quotes, prix hors blockchain ou routage peuvent conserver des APIs/modules spécialisés à l'intérieur de cette crate sans prétendre partager une abstraction métier commune.
|
||||
|
||||
## Wallet
|
||||
|
||||
Aucune crate `ksp-wallet-api` n'est prévue.
|
||||
|
||||
`ksp-wallet-lib` est propriétaire du format wallet KSP, des opérations de protection/import/export et de l'accès contrôlé aux capacités pubkey/secret/signature nécessaires aux couches supérieures.
|
||||
|
||||
Les applications futures utilisant ce wallet restent des consommateurs de `ksp-wallet-lib`, pas des implémentations alternatives du contrat wallet.
|
||||
|
||||
## Workers
|
||||
|
||||
### `ksp-worker-api`
|
||||
|
||||
`ksp-worker-api` est une **lifecycle API de services continus**.
|
||||
|
||||
Elle pourra porter des contrats communs comme identité, état, health, start/stop/shutdown et événements de lifecycle. Une capacité optionnelle comme la reconfiguration à chaud ne doit devenir universelle que si plusieurs workers la partagent réellement.
|
||||
|
||||
Elle ne contient aucun concept de progression/checkpoint terminal propre aux jobs.
|
||||
|
||||
### `ksp-worker-control-lib`
|
||||
|
||||
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance au-dessus de `ksp-worker-api`.
|
||||
|
||||
Elle doit pouvoir être consommée par :
|
||||
|
||||
- une application desktop manager spécialisée ;
|
||||
- une future application globale ;
|
||||
- un futur orchestrateur ;
|
||||
- des tools/tests lorsque pertinent.
|
||||
|
||||
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.
|
||||
|
||||
### Workers de processing
|
||||
|
||||
Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites :
|
||||
|
||||
```text
|
||||
raw persisted
|
||||
|
|
||||
v
|
||||
ksp-worker-core-processor
|
||||
|
|
||||
v
|
||||
canonical Core
|
||||
|
|
||||
v
|
||||
ksp-worker-generic-materializer
|
||||
|
|
||||
v
|
||||
generic materialization/journal
|
||||
|
|
||||
v
|
||||
ksp-worker-domain-projector
|
||||
|
|
||||
v
|
||||
domain projections
|
||||
```
|
||||
|
||||
Le nom `ksp-worker-domain-projector` est explicitement provisoire jusqu'à ce que les contrats de matérialisation spécialisée soient définis.
|
||||
|
||||
## Jobs
|
||||
|
||||
`ksp-job-api` est une **lifecycle API de travaux déclenchés et terminables**.
|
||||
|
||||
Elle peut porter identité, état, progression, cancel, résultat et, lorsque pertinent, pause/resume/checkpoint.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement. Le fait que plusieurs jobs implémentent `ksp-job-api` suffit tant qu'aucune duplication concrète de gouvernance ne justifie une bibliothèque commune.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
Les notifications de données restent indépendantes du lifecycle des workers et des jobs.
|
||||
|
||||
Le même type de donnée persistée doit produire le même contrat de notification quelle que soit son origine :
|
||||
|
||||
```text
|
||||
worker live -----\
|
||||
job backfill -----+--> même notification de donnée
|
||||
import -----------/
|
||||
```
|
||||
|
||||
`ksp-store-api` reste le propriétaire candidat de ces références/notifications lorsqu'elles signifient qu'une donnée persistée est disponible.
|
||||
|
||||
Le transport de notification reste distinct du contrat de donnée.
|
||||
|
||||
## Scénarios et demos
|
||||
|
||||
Aucune crate monolithique de scénarios n'est prévue.
|
||||
|
||||
Les scénarios vivent dans des crates spécialisées :
|
||||
|
||||
```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
|
||||
...
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
Les applications de démonstration correspondantes suivent la forme :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
```
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-memo-devnet-desk-demo
|
||||
ksp-app-scenario-token-2022-devnet-desk-demo
|
||||
ksp-app-scenario-metadata-devnet-desk-demo
|
||||
```
|
||||
|
||||
Chaque application appelle la crate `ksp-scenario-<domain>-lib` correspondante et ne duplique pas son scénario.
|
||||
|
||||
## Pipelines
|
||||
|
||||
`ksp-pipeline-lib` reste rejeté.
|
||||
|
||||
Des pipelines spécialisés peuvent être créés à la demande lorsqu'un flux concret possède assez de logique réutilisable pour justifier sa propre frontière. Leur forme n'est pas nécessairement une bibliothèque : certains pourront être workers, jobs ou composants spécialisés.
|
||||
|
||||
## Questions explicitement reportées à `pre.003`
|
||||
|
||||
- dépendance exacte de `ksp-execution-lib` vers `ksp-program-api` et/ou `ksp-program-lib` ;
|
||||
- forme du contrat entre program preparation, execution policy, wallet et transport ;
|
||||
- emplacement exact des modèles communs nécessaires à l'exécution ;
|
||||
- types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
|
||||
- dépendances autorisées de `ksp-materializer-api` et `ksp-store-api` ;
|
||||
- risque de cycles entre program, materializer, store, execution et control ;
|
||||
- position exacte des notifications de données dans le graphe.
|
||||
@@ -1,101 +1,87 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Plan KSP 0.0.3
|
||||
|
||||
## Mission
|
||||
|
||||
Poursuivre la phase fondatrice sans développement fonctionnel afin de transformer le brainstorming KSP en architecture, règles, nomenclature et plan de développement suffisamment précis pour ouvrir `0.1.x`.
|
||||
Transformer le brainstorming KSP en architecture, règles, inventaire et plan suffisamment précis pour ouvrir la première série fonctionnelle `0.1.x` sans développement fonctionnel prématuré.
|
||||
|
||||
## Décisions structurantes acquises
|
||||
## État courant
|
||||
|
||||
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib`.
|
||||
- Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
- Éviter un `ksp-api-lib` monolithique.
|
||||
- Couples API/implémentation retenus : program, materializer, store.
|
||||
- `ksp-store-lib` contient PostgreSQL comme implémentation de référence de `ksp-store-api`.
|
||||
- Les workers continus utilisent `ksp-worker-api`.
|
||||
- Les jobs à la demande utilisent `ksp-job-api`.
|
||||
- Workers et jobs ne partagent pas une abstraction de lifecycle commune.
|
||||
- W1 est strictement raw live/quasi-live et ne fait pas de backfill.
|
||||
- Le backfill historique est un job séparé, candidat `ksp-job-backfill`.
|
||||
- D'autres jobs pourront exister pour metadata, quotes et autres tâches ponctuelles.
|
||||
- Les notifications de données sont normalisées indépendamment de leur producteur ; `ksp-store-api` est le propriétaire candidat des notifications de données persistées.
|
||||
- `ksp-worker-control-lib` est le candidat pour une implémentation commune de contrôle des workers uniquement.
|
||||
- Aucun `ksp-pipeline-lib` monolithique ; pipelines séparés à la demande.
|
||||
- Aucun `ksp-scenarios-lib` monolithique ; scénarios séparés par crates de domaine.
|
||||
- Trading Intelligence précède la couche/application de trading opérationnelle.
|
||||
`pre.001` est considérée stabilisée et commitée comme `v0.0.3-pre.001`.
|
||||
|
||||
## Ligne directrice du développement fonctionnel
|
||||
`pre.002` produit le premier inventaire des composants et responsabilités. Cet inventaire est volontairement révisable dans `pre.003` lorsque le graphe de dépendances sera étudié.
|
||||
|
||||
- `0.1.x` — `ksp-core-lib`, `ksp-logging-lib`, `ksp-config-lib`, `ksp-app-config-desk`.
|
||||
- `0.2.x` — `ksp-onchain-transport-lib`, wallet, `ksp-interface-lib`, `ksp-program-api`, `ksp-program-lib`.
|
||||
- `0.3.x` — `ksp-materializer-api`, `ksp-materializer-lib`, `ksp-store-api`, `ksp-store-lib`, W1, `ksp-worker-api`, `ksp-job-api`, backfill.
|
||||
- `0.4.x` — premières surfaces Core/SPL/metadata, matérialisations, off-chain transport selon besoin, jobs/scénarios/demos spécialisés.
|
||||
- `0.5.x` — Anchor puis protocoles trading par releases bornées.
|
||||
- `0.6.x` — W2, contrôle workers, managers, orchestrateur et application globale.
|
||||
- `0.7.x` — Trading Intelligence.
|
||||
- `0.8.x+` — couche/application trading, extension continue, explorer Solana et explorer/analyse DEX.
|
||||
## Décisions structurantes actuelles
|
||||
|
||||
## Prévision souple des prereleases 0.0.3
|
||||
- `0.1.x`, `0.2.x`, etc. sont des **séries fonctionnelles**, pas des unités de session.
|
||||
- Chaque release concrète d'une série doit être dimensionnée séparément pour une session raisonnable.
|
||||
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib` ; les contrats publics extensibles utilisent `ksp-<domain>-api`.
|
||||
- Program, materializer et store ont un couple API/implémentation séparé.
|
||||
- Workers et jobs ont des lifecycle APIs distinctes.
|
||||
- `ksp-worker-raw-retriever` réalise uniquement l'acquisition live/quasi-live raw.
|
||||
- Le processing futur est séparé en `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` (nom du dernier provisoire).
|
||||
- `ksp-job-backfill` réalise l'acquisition historique à la demande.
|
||||
- `ksp-worker-control-lib` est destiné à être réutilisé par managers/apps/orchestrateur ; aucune `ksp-job-control-lib` n'est prévue sans besoin concret.
|
||||
- `ksp-execution-policy-api` et `ksp-execution-lib` sont des candidats forts pour séparer policy et orchestration d'exécution de `ksp-program-lib`.
|
||||
- Pas de `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` dans l'architecture actuelle.
|
||||
- `ksp-onchain-transport-lib` expose des modèles de transport homogènes mais indépendants du store.
|
||||
- Pas de `ksp-scenario-api` pour l'instant : privilégier une norme souple de scénarios spécialisés.
|
||||
- Pas de `ksp-pipeline-lib` monolithique ; pipelines spécialisés uniquement à la demande.
|
||||
|
||||
### `pre.001` — Base de planification
|
||||
## Prévision souple des prereleases restantes
|
||||
|
||||
Considérée stabilisée après les fixes de cadrage.
|
||||
### `pre.002` — Inventaire initial des composants
|
||||
|
||||
### `pre.002` — Domaines et crates candidates
|
||||
- créer `docs/architecture/004-COMPONENT_INVENTORY.md` ;
|
||||
- fixer les responsabilités et statuts initiaux des composants ;
|
||||
- enregistrer les workers/jobs/scénarios/apps actuellement prévus ;
|
||||
- documenter les candidats `ksp-execution-policy-api` et `ksp-execution-lib` ;
|
||||
- corriger la règle de charge série/release/session ;
|
||||
- préparer explicitement les questions à résoudre dans `pre.003`.
|
||||
|
||||
- inventorier les domaines fonctionnels ;
|
||||
- fixer les couples `*-api` / `*-lib` réellement justifiés ;
|
||||
- définir workers vs jobs ;
|
||||
- définir les responsabilités des notifications de données ;
|
||||
- inventorier les scénarios/pipelines spécialisés ;
|
||||
- définir pour chaque crate candidate responsabilité, niveau, entrées/sorties et consommateurs ;
|
||||
- mettre à jour le brouillon de prompt `0.1.x`.
|
||||
### `pre.003` — Graphe de dépendances et correction de l'inventaire
|
||||
|
||||
### `pre.003` — Graphe de dépendances
|
||||
- construire le graphe autorisé/interdit ;
|
||||
- décider si `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-program-lib` ou reçoit des implémentations injectées ;
|
||||
- définir la frontière program -> execution plan -> policy -> wallet/transport ;
|
||||
- vérifier que transport ne dépend pas du store tout en gardant une conversion simple des modèles ;
|
||||
- positionner materializer/store/notifications ;
|
||||
- rechercher et supprimer les cycles ;
|
||||
- corriger `004-COMPONENT_INVENTORY.md` si nécessaire.
|
||||
|
||||
- construire le graphe de dépendances autorisées/interdites ;
|
||||
- identifier les propriétaires des dépendances Solana externes ;
|
||||
- vérifier les risques de cycles ;
|
||||
- positionner précisément les crates `*-api` ;
|
||||
- préciser les dépendances autorisées de `ksp-program-api`, `ksp-materializer-api`, `ksp-store-api`, `ksp-worker-api` et `ksp-job-api`.
|
||||
### `pre.004` — Programmes, wire et exécution
|
||||
|
||||
### `pre.004` — Programmes, décodage et exécution
|
||||
- détailler `ksp-interface-lib`, `ksp-program-api`, `ksp-program-lib` ;
|
||||
- détailler l'execution policy/orchestration si validées ;
|
||||
- cadrer conformité wire, historique/deprecated et sécurité supérieure.
|
||||
|
||||
- détailler `ksp-program-api` et `ksp-program-lib` ;
|
||||
- définir les interfaces wire et leur source de vérité ;
|
||||
- cadrer les tests de conformité ;
|
||||
- définir le niveau supérieur propriétaire de la sécurité d'exécution ;
|
||||
- traiter Metaplex/ElGamal comme exemples architecturaux sans développement fonctionnel.
|
||||
### `pre.005` — Données, store et acquisitions
|
||||
|
||||
### `pre.005` — Données, storage et acquisitions
|
||||
- détailler materializer/store ;
|
||||
- finaliser les modèles raw et notifications ;
|
||||
- détailler W1 et backfill ;
|
||||
- cadrer les trois workers de processing futurs ;
|
||||
- revisiter les niveaux durables/replay.
|
||||
|
||||
- détailler `ksp-materializer-api` / `ksp-materializer-lib` ;
|
||||
- détailler `ksp-store-api` / `ksp-store-lib` ;
|
||||
- finaliser W1, `ksp-worker-api` et ses notifications de données ;
|
||||
- détailler `ksp-job-api` et le backfill ;
|
||||
- cadrer W2 sans l'implémenter ;
|
||||
- définir les frontières backend et replay/reconstruction.
|
||||
### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés
|
||||
|
||||
### `pre.006` — Applications, workers, jobs, demos et scénarios
|
||||
- formaliser les apps spécialisées ;
|
||||
- détailler `ksp-worker-control-lib` ;
|
||||
- définir la norme des crates scénario et leurs apps demo ;
|
||||
- inventorier les pipelines spécialisés réellement nécessaires.
|
||||
|
||||
- formaliser config/store/wallet apps ;
|
||||
- finaliser la nomenclature réseau/environnement ;
|
||||
- détailler les crates de scénarios spécialisées ;
|
||||
- détailler managers workers/jobs et trajectoire vers l'orchestrateur ;
|
||||
- inventorier les pipelines spécialisés nécessaires sans crate pipeline monolithique.
|
||||
### `pre.007` — Plan des premières releases fonctionnelles
|
||||
|
||||
### `pre.007` — Plan de développement et contrôle de charge
|
||||
|
||||
- affiner le roadmap fonctionnel `0.1.x+` ;
|
||||
- détailler le premier plan `0.1.x` ;
|
||||
- transformer le brouillon de prompt en quasi-version finale ;
|
||||
- vérifier et redécouper la charge de la session suivante si nécessaire.
|
||||
- transformer les séries `0.1.x+` en premières releases concrètes ;
|
||||
- dimensionner chaque release concrète plutôt que toute la série ;
|
||||
- préparer le prompt de la première release `0.1.x` réellement choisie.
|
||||
|
||||
### `pre.008` — Clôture fondatrice
|
||||
|
||||
- vérifier la cohérence règles/architecture/plans ;
|
||||
- mettre à jour la documentation finale ;
|
||||
- nettoyer/archiver les éléments temporaires ;
|
||||
- finaliser le prompt de reprise `0.1.x`.
|
||||
- validations finales de cohérence ;
|
||||
- documentation/nettoyage/archivage ;
|
||||
- finalisation du prompt de la première release fonctionnelle.
|
||||
|
||||
Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une nouvelle frontière apparaît.
|
||||
|
||||
@@ -1,203 +1,70 @@
|
||||
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Structure des prompts KSP
|
||||
|
||||
## Portée
|
||||
|
||||
Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des sessions/prereleases qu'ils préparent.
|
||||
Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des releases/sessions qu'ils préparent.
|
||||
|
||||
Les prompts eux-mêmes sont conservés sous `prompts/`.
|
||||
## Série, release concrète et session
|
||||
|
||||
## Objectif
|
||||
Une notation de série telle que `0.1.x` regroupe des fonctionnalités apparentées. Elle n'est pas une unité de session et n'a pas à être réalisable en une seule session.
|
||||
|
||||
Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
|
||||
Exemple : `0.1.x` peut regrouper plusieurs releases concrètes comme `0.1.1`, `0.1.2`, `0.1.3`, chacune avec son propre cycle de prereleases et, en principe, sa propre session de travail principale.
|
||||
|
||||
- la mission de la phase ;
|
||||
- la base Git/version ;
|
||||
- l'état validé à préserver ;
|
||||
- les règles applicables ;
|
||||
- l'architecture déjà décidée ;
|
||||
- les questions encore ouvertes ;
|
||||
- les sources externes normatives lorsqu'elles existent ;
|
||||
- le plan souple ;
|
||||
- le mode de livraison ;
|
||||
- les validations et critères de sortie.
|
||||
Le contrôle de charge s'applique donc d'abord à **la release concrète préparée** et à ses prereleases, pas à toute la série fonctionnelle.
|
||||
|
||||
Le prompt ne remplace jamais les sources de vérité du dépôt.
|
||||
|
||||
## Cycle de vie
|
||||
|
||||
Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire.
|
||||
|
||||
Il passe par trois états conceptuels :
|
||||
|
||||
1. **Brouillon** — créé tôt et volontairement incomplet ;
|
||||
2. **Quasi-final** — mis à jour lorsque les frontières, crates, dépendances et objectifs sont suffisamment stabilisés ;
|
||||
3. **Final** — vérifié pendant la phase documentaire de clôture et prêt à être utilisé comme point de départ de la session/version suivante.
|
||||
|
||||
Le prompt de la phase suivante doit être maintenu pendant la phase courante lorsque de nouvelles décisions changent matériellement son futur démarrage.
|
||||
|
||||
## Première et dernière prerelease d'une version
|
||||
## Cycle d'une release concrète
|
||||
|
||||
Sauf raison explicitement documentée :
|
||||
|
||||
- la première prerelease (`pre.001`) est consacrée au brainstorming, à l'audit lorsque nécessaire, à la planification, aux décisions de périmètre et au découpage souple des prereleases suivantes ;
|
||||
- la dernière prerelease est consacrée à la validation finale, à la documentation, au nettoyage/archivage nécessaire, à la synchronisation des documents de release et à la finalisation du prompt de la session/version suivante.
|
||||
|
||||
Le développement fonctionnel significatif ne doit pas précéder le cadrage suffisant de `pre.001`.
|
||||
- `pre.001` = brainstorming/audit si nécessaire + planification + découpage de la release ;
|
||||
- les prereleases intermédiaires = tranches bornées de développement/validation ;
|
||||
- la dernière prerelease = validation finale + documentation + nettoyage/archivage + préparation du prompt/release suivante.
|
||||
|
||||
## Dimensionnement des prereleases
|
||||
|
||||
Pendant l'élaboration du plan de `pre.001`, les prereleases de travail situées après `pre.001` et avant la prerelease finale de clôture doivent être conçues comme des tranches bornées.
|
||||
Lors de `pre.001`, une prerelease intermédiaire estimée à plus d'environ **15 à 20 minutes de travail effectif de session** doit être scindée.
|
||||
|
||||
Lors de la planification, une tranche dont la charge estimée paraît dépasser approximativement **15 à 20 minutes de travail effectif de session** doit être scindée en plusieurs prereleases ou sous-objectifs livrables séparément.
|
||||
Cette durée est un budget de planification et non une promesse d'exécution.
|
||||
|
||||
Cette durée est un budget de planification, pas une promesse de temps d'exécution. Elle sert à empêcher les tranches trop larges, difficiles à valider ou à corriger.
|
||||
Si la complexité réelle augmente, la tranche est redécoupée plutôt que surchargée.
|
||||
|
||||
Si la complexité réelle découverte en cours de travail dépasse l'estimation, la tranche doit être redécoupée plutôt que surchargée.
|
||||
## Dimensionnement d'une release/session
|
||||
|
||||
## Dimensionnement d'une session ou d'une version
|
||||
Avant de finaliser le prompt d'une release concrète, vérifier que son plan complet est compatible avec une session de qualité.
|
||||
|
||||
Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
|
||||
Si une release concrète paraît trop lourde, la scinder en plusieurs releases de la même série lorsque les fonctions restent du même groupe, ou changer de série si une frontière fonctionnelle différente le justifie.
|
||||
|
||||
Si un prompt risque de générer trop de prereleases, trop de fichiers, trop de décisions ou un contexte trop lourd pour une seule session de qualité, le périmètre doit être découpé :
|
||||
Exemple : si `0.1.1` devient trop large, créer `0.1.2` plutôt que forcer tout `0.1.x` dans une seule session.
|
||||
|
||||
- en plusieurs sessions conservant éventuellement la même série/version lorsque la continuité fonctionnelle le justifie ;
|
||||
- et/ou en plusieurs versions lorsque la séparation correspond à une frontière fonctionnelle plus propre.
|
||||
|
||||
Exemple : si une version prévue pour introduire decoder + executor devient manifestement trop lourde après planification, la continuité du roadmap est conservée mais le travail peut être réparti sur plusieurs sessions ou versions.
|
||||
|
||||
La qualité du contexte, la testabilité et la cohérence architecturale priment sur le maintien artificiel d'un découpage de versions imaginé plus tôt.
|
||||
Une série complète peut naturellement s'étendre sur de nombreuses sessions.
|
||||
|
||||
## Structure recommandée d'un prompt
|
||||
|
||||
### 1. Identité de la phase
|
||||
|
||||
Indiquer :
|
||||
|
||||
- version ou série visée ;
|
||||
- titre court ;
|
||||
- nature de la session : brainstorming, planification, développement, audit, validation, clôture, etc.
|
||||
|
||||
### 2. Mission
|
||||
|
||||
Décrire l'état concret à atteindre pendant la phase.
|
||||
|
||||
La mission ne doit pas être une simple liste de fichiers à modifier.
|
||||
|
||||
### 3. Base requise
|
||||
|
||||
Indiquer :
|
||||
|
||||
- version/tag/commit de départ ;
|
||||
- état attendu du workspace ;
|
||||
- fichiers/documents fondamentaux déjà présents.
|
||||
|
||||
### 4. État validé à préserver
|
||||
|
||||
Lister les éléments déjà validés qui ne doivent pas régresser pendant la nouvelle phase, par exemple :
|
||||
|
||||
- APIs déjà stabilisées ;
|
||||
- comportements fonctionnels validés ;
|
||||
- tests/scénarios connus comme passants ;
|
||||
- décisions gelées ou fortement contraintes ;
|
||||
- problèmes explicitement reportés qui ne doivent pas être rouverts sans raison.
|
||||
|
||||
Cette section est distincte de la simple base Git/version.
|
||||
|
||||
### 5. Sources de vérité internes à relire
|
||||
|
||||
Lister explicitement les documents nécessaires, en priorité :
|
||||
|
||||
- `RULES.md` et règles spécialisées pertinentes ;
|
||||
- `ROADMAP.md` ;
|
||||
- plan de version actif ;
|
||||
- architecture concernée ;
|
||||
- `docs/IDEAS.md` lorsqu'une question ouverte est pertinente ;
|
||||
- dernier delta/release utile.
|
||||
|
||||
Le prompt doit renvoyer aux sources de vérité au lieu de les recopier intégralement.
|
||||
|
||||
### 6. Sources externes normatives
|
||||
|
||||
Lorsqu'une phase concerne un protocole, programme, standard ou API externe, lister les sources qui font autorité :
|
||||
|
||||
- dépôt upstream officiel ;
|
||||
- documentation officielle ;
|
||||
- IDL/schema officiel ;
|
||||
- Program ID ;
|
||||
- format wire ;
|
||||
- spécification normative ;
|
||||
- autre source externe explicitement retenue.
|
||||
|
||||
Une copie historique locale ne doit pas être traitée comme source de vérité actuelle lorsque la phase exige une vérification upstream.
|
||||
|
||||
### 7. Décisions acquises
|
||||
|
||||
Résumer uniquement les décisions indispensables pour éviter une mauvaise direction au démarrage.
|
||||
|
||||
### 8. Objectifs et livrables
|
||||
|
||||
Lister les objectifs principaux et les artefacts attendus.
|
||||
|
||||
### 9. Hors périmètre
|
||||
|
||||
Indiquer ce qui ne doit explicitement pas être ouvert pendant la phase.
|
||||
|
||||
### 10. Méthode de travail
|
||||
|
||||
Rappeler la séquence KSP applicable :
|
||||
|
||||
1. brainstorming ;
|
||||
2. planification ;
|
||||
3. développement lorsque la phase est fonctionnelle ;
|
||||
4. tests/validations ;
|
||||
5. documentation finale ;
|
||||
6. mise à jour/préparation du prompt suivant.
|
||||
|
||||
Une phase fondatrice/documentaire adapte la partie développement à son objet.
|
||||
|
||||
### 11. Versionnement et deltas
|
||||
|
||||
Rappeler :
|
||||
|
||||
- version Cargo attendue ;
|
||||
- format du delta ;
|
||||
- règle des fixes techniques/documentaires ;
|
||||
- politique de commits de la phase ;
|
||||
- règle de découpage des livraisons trop volumineuses.
|
||||
|
||||
### 12. Contraintes techniques spécifiques
|
||||
|
||||
Lister uniquement les contraintes importantes pour cette phase : dépendances, environnements, sécurité, API publique, stockage, transport, etc.
|
||||
|
||||
### 13. Plan initial souple
|
||||
|
||||
Pour un `pre.001`, fournir la prévision souple des prereleases ou étapes principales.
|
||||
|
||||
Chaque tranche intermédiaire doit respecter le budget de complexité défini plus haut et être redécoupée si nécessaire.
|
||||
|
||||
### 14. Validations attendues
|
||||
|
||||
Indiquer les commandes/tests/audits pertinents et interdire de déclarer une validation non exécutée.
|
||||
|
||||
### 15. Critères de sortie
|
||||
|
||||
Décrire les conditions nécessaires pour considérer la phase terminée.
|
||||
|
||||
### 16. Préparation de la suite
|
||||
|
||||
Indiquer quel document/prompt doit être produit ou mis à jour avant la clôture.
|
||||
|
||||
Avant finalisation de ce prompt suivant, appliquer obligatoirement le contrôle de dimensionnement de session/version.
|
||||
1. Identité de la série et de la release concrète visée ;
|
||||
2. Mission ;
|
||||
3. Base requise ;
|
||||
4. État validé à préserver ;
|
||||
5. Sources de vérité internes ;
|
||||
6. Sources externes normatives ;
|
||||
7. Décisions acquises ;
|
||||
8. Objectifs et livrables ;
|
||||
9. Hors périmètre ;
|
||||
10. Méthode de travail ;
|
||||
11. Versionnement/deltas/commits ;
|
||||
12. Contraintes techniques spécifiques ;
|
||||
13. Plan initial souple et prereleases bornées ;
|
||||
14. Validations attendues ;
|
||||
15. Critères de sortie ;
|
||||
16. Préparation de la release/session suivante.
|
||||
|
||||
## Règles de rédaction
|
||||
|
||||
- Le prompt est précis mais évite de dupliquer plusieurs pages déjà présentes dans les documents canoniques.
|
||||
- Une règle normative appartient d'abord à `docs/rules/`, pas seulement au prompt.
|
||||
- Une décision architecturale durable appartient à `docs/architecture/`, pas seulement au prompt.
|
||||
- Le prompt référence les sources canoniques au lieu de recopier inutilement leur contenu.
|
||||
- Une règle normative appartient à `docs/rules/`.
|
||||
- Une décision durable appartient à `docs/architecture/`.
|
||||
- Une idée non décidée appartient à `docs/IDEAS.md`.
|
||||
- Le prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
|
||||
- Les chemins et versions mentionnés doivent être cohérents avec le dépôt au moment de la finalisation.
|
||||
- Un prompt final ne doit pas préparer une session manifestement surdimensionnée.
|
||||
- Un prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
|
||||
- Une release concrète manifestement surdimensionnée doit être redécoupée avant ouverture de sa session principale.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
- **KSP-NAME-006** — Un job ponctuel/historique/terminable se nomme `ksp-job-<role>`.
|
||||
- **KSP-NAME-007** — Une démonstration se termine par `-demo`.
|
||||
- **KSP-NAME-008** — Les crates Rust sont placées directement sous `crates/`.
|
||||
- **KSP-NAME-009** — Une application desktop de scénario spécialisée suit la forme `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
|
||||
|
||||
## Architecture et APIs
|
||||
|
||||
@@ -22,8 +23,9 @@
|
||||
- **KSP-API-004** — Un contrat public extensible doit pouvoir être implémenté depuis une crate séparée du workspace principal lorsque cela est techniquement pertinent.
|
||||
- **KSP-API-005** — Les signatures des contrats publics utilisent en priorité des types publics KSP et les primitives externes explicitement admises ; elles ne doivent pas imposer des détails internes instables.
|
||||
- **KSP-API-006** — `ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence derrière `ksp-store-api`.
|
||||
- **KSP-API-007** — Une crate `*-api` n'est créée que lorsqu'un vrai besoin d'extension, backend ou lifecycle le justifie ; la symétrie de nommage n'est jamais une justification suffisante.
|
||||
|
||||
## Programmes
|
||||
## Programmes et exécution
|
||||
|
||||
- **KSP-PROGRAM-001** — Les contrats decoder/executor appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`.
|
||||
- **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
|
||||
@@ -31,24 +33,43 @@
|
||||
- **KSP-PROGRAM-004** — Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
|
||||
- **KSP-PROGRAM-005** — Une opération devenue obsolète mais toujours identifiable/exécutable peut rester implémentée dans l'executor et être marquée `deprecated`.
|
||||
- **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
|
||||
- **KSP-EXEC-001** — La direction retenue est une API de policy d'exécution séparée, candidate `ksp-execution-policy-api`, afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
|
||||
- **KSP-EXEC-002** — Une application UI sélectionne/injecte une implémentation de policy réutilisable ; elle ne doit pas enfouir une politique d'exécution complexe dans sa couche d'interface.
|
||||
- **KSP-EXEC-003** — `ksp-execution-lib` est un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport. Son graphe exact est reporté à l'étude des dépendances.
|
||||
|
||||
## Transports
|
||||
|
||||
- **KSP-TRANSPORT-001** — KSP ne crée pas de `ksp-onchain-transport-api` séparée dans l'architecture actuelle.
|
||||
- **KSP-TRANSPORT-002** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`.
|
||||
- **KSP-TRANSPORT-003** — Les providers on-chain normalisent leurs sorties dans des modèles de transport homogènes par catégorie de données avant exposition aux consommateurs.
|
||||
- **KSP-TRANSPORT-004** — Les modèles de transport restent sans décodage métier/protocolaire et doivent être explicitement/facilement convertibles vers les modèles raw persistants de `ksp-store-api` par la couche d'acquisition.
|
||||
- **KSP-TRANSPORT-005** — KSP ne crée pas de `ksp-offchain-transport-api` globale ni de trait universel artificiel pour des domaines off-chain hétérogènes.
|
||||
|
||||
## Wallet
|
||||
|
||||
- **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature.
|
||||
|
||||
## Workers
|
||||
|
||||
- **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-control-lib` est le candidat d'implémentation commune de gouvernance/contrôle des workers lorsque plusieurs consommateurs le justifient.
|
||||
- **KSP-WORKER-004** — W1 est un 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-005** — W1 persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
|
||||
- **KSP-WORKER-006** — W1 doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
|
||||
- **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-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.
|
||||
- **KSP-WORKER-008** — Les workers de processing actuellement retenus sont `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`; le dernier nom reste provisoire.
|
||||
|
||||
## Jobs
|
||||
|
||||
- **KSP-JOB-001** — Un job représente un travail déclenché à la demande, suivable et terminable ; il est distinct d'un worker continu.
|
||||
- **KSP-JOB-002** — Les contrats communs des jobs appartiennent à `ksp-job-api` et ne contiennent aucun contrat propre aux workers.
|
||||
- **KSP-JOB-003** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
- **KSP-JOB-004** — `ksp-job-backfill` est le candidat retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode W1.
|
||||
- **KSP-JOB-005** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
|
||||
- **KSP-JOB-006** — Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers.
|
||||
- **KSP-JOB-003** — `ksp-job-api` est principalement une lifecycle API de travaux terminables : identité, état, progression, annulation, résultat et capacités de reprise lorsqu'elles sont pertinentes.
|
||||
- **KSP-JOB-004** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
- **KSP-JOB-005** — `ksp-job-backfill` est retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode du worker raw.
|
||||
- **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
|
||||
- **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
|
||||
- **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
@@ -60,14 +81,16 @@
|
||||
## Pipelines et scénarios
|
||||
|
||||
- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique. Les pipelines sont introduits séparément à la demande selon leur responsabilité réelle.
|
||||
- **KSP-DEMO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
- **KSP-DEMO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
|
||||
- **KSP-DEMO-003** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
|
||||
- **KSP-DEMO-004** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
|
||||
- **KSP-DEMO-005** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
|
||||
- **KSP-SCENARIO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
- **KSP-SCENARIO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
|
||||
- **KSP-SCENARIO-003** — `ksp-scenario-api` n'est pas retenu actuellement ; KSP privilégie d'abord une norme documentaire/structurelle commune qui ne limite pas les contrats spécifiques des scénarios.
|
||||
- **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.
|
||||
|
||||
## Applications
|
||||
|
||||
- **KSP-APP-001** — Une application KSP est une interface et une couche de composition. Elle ne réimplémente pas une opération appartenant conceptuellement à un composant KSP réutilisable inférieur.
|
||||
- **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-<domain>-lib` correspondante ; elle suit la convention `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
|
||||
|
||||
@@ -1,64 +1,70 @@
|
||||
<!-- file: prompts/001-V0_1_X_START_PROMPT.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Prompt de démarrage KSP 0.1.x
|
||||
|
||||
**Status : Brouillon vivant — ne pas utiliser comme prompt final tant que `0.0.3` n'est pas clôturée.**
|
||||
**Status : Brouillon vivant — prompt de démarrage de la série N1, à finaliser avec la première release concrète avant clôture de `0.0.3`.**
|
||||
|
||||
## Mission provisoire
|
||||
## 1. Identité
|
||||
|
||||
Commencer le développement fonctionnel KSP sur les fondations N1 nécessaires au reste du projet, principalement :
|
||||
Série fonctionnelle : `0.1.x` — fondations N1.
|
||||
|
||||
`0.1.x` ne représente pas une seule session. La planification finale doit choisir la première release concrète (`0.1.1` ou autre) et lui donner un périmètre compatible avec une session de qualité.
|
||||
|
||||
## 2. Mission de la série
|
||||
|
||||
Construire progressivement :
|
||||
|
||||
- `ksp-core-lib` ;
|
||||
- `ksp-logging-lib` ;
|
||||
- `ksp-config-lib` ;
|
||||
- `ksp-app-config-desk`.
|
||||
- `ksp-app-config-desk` ;
|
||||
- uniquement les contrats précoces strictement nécessaires aux étapes suivantes.
|
||||
|
||||
## Décisions déjà acquises
|
||||
Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`.
|
||||
|
||||
- Le développement fonctionnel commence en `0.1.x`.
|
||||
- Chaque delta est commité à partir de cette série.
|
||||
- Les bibliothèques d'implémentation réutilisables utilisent `ksp-<role>-lib`.
|
||||
- Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
- Une crate `*-api` n'est pas une implémentation directement destinée à être appelée par un exécutable.
|
||||
- Éviter un `ksp-api-lib` monolithique ; les APIs restent séparées par domaine.
|
||||
- `ksp-program-api`, `ksp-materializer-api` et `ksp-store-api` sont les premiers contrats d'extension prévus.
|
||||
- Les workers et jobs possèdent des APIs communes séparées : `ksp-worker-api` et `ksp-job-api`.
|
||||
- Les notifications de données restent indépendantes du worker/job producteur ; `ksp-store-api` est le propriétaire candidat des notifications de données persistées.
|
||||
- `ksp-store-lib` contient PostgreSQL comme implémentation de référence.
|
||||
- Les applications restent des interfaces/compositions au-dessus des composants KSP.
|
||||
## 3. Base requise
|
||||
|
||||
À finaliser à la clôture de `0.0.3`.
|
||||
|
||||
## 4. État validé à préserver
|
||||
|
||||
À compléter à la clôture de `0.0.3`.
|
||||
|
||||
## 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` à `004`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`.
|
||||
|
||||
## 6. Décisions acquises pertinentes
|
||||
|
||||
- Chaque delta est commité à partir de `0.1.x`.
|
||||
- Une série `0.1.x` peut contenir plusieurs releases/sessions.
|
||||
- Chaque release concrète commence par `pre.001` de brainstorming/planification.
|
||||
- Une prerelease intermédiaire estimée au-delà d'environ 15–20 minutes doit être scindée.
|
||||
- Une release concrète trop grosse doit être répartie sur plusieurs releases de la même série plutôt que forcer toute la série dans une session.
|
||||
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib` ; les APIs extensibles utilisent `ksp-<domain>-api` uniquement lorsqu'un besoin réel le justifie.
|
||||
- Les applications restent des interfaces/compositions.
|
||||
- Les exécutables ne dépendent pas directement de crates Solana/protocoles externes.
|
||||
- `ksp-core-lib`, `ksp-config-lib`, `ksp-logging-lib` et `ksp-interface-lib` sont des fondations N1.
|
||||
- `ksp-core-lib` doit posséder les Program IDs fondamentaux et un type d'erreur public commun.
|
||||
- Les règles fines de nommage des items publics/arborescence seront définies à partir des premières APIs réelles.
|
||||
- Les prereleases intermédiaires sont planifiées comme des tranches bornées d'environ 15–20 minutes maximum de travail effectif estimé.
|
||||
- Si le plan complet de `0.1.x` risque de saturer une seule session, il doit être réparti sur plusieurs sessions et/ou versions avant développement.
|
||||
- `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun.
|
||||
- Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles.
|
||||
|
||||
## Objectifs provisoires
|
||||
## 7. Hors périmètre de la série N1
|
||||
|
||||
1. Stabiliser le premier contrat utile de `ksp-core-lib`.
|
||||
2. Définir le modèle commun `Error` sans rendre N1 dépendant des domaines supérieurs.
|
||||
3. Intégrer les Program IDs fondamentaux dans `ksp-core-lib`.
|
||||
4. Créer `ksp-logging-lib`.
|
||||
5. Créer `ksp-config-lib`.
|
||||
6. Créer `ksp-app-config-desk` comme interface de manipulation de la configuration.
|
||||
7. Ajouter les règles API/naming/arborescence rendues nécessaires par les premiers vrais contrats.
|
||||
8. Préparer uniquement les contrats minimaux requis pour `0.2.x` lorsque leur définition précoce est utile.
|
||||
Sauf contrat minimal nécessaire au futur : program implementations, wallet, transport, materializers/store, workers/jobs, protocoles trading et Trading Intelligence.
|
||||
|
||||
## Hors périmètre provisoire
|
||||
## 8. Travail à effectuer avant démarrage
|
||||
|
||||
- implémentation réelle de `ksp-program-api` / `ksp-program-lib` au-delà des contrats strictement nécessaires ;
|
||||
- implémentation complète de `ksp-interface-lib` ;
|
||||
- wallet ;
|
||||
- transport on-chain ;
|
||||
- storage/materializers ;
|
||||
- workers/jobs ;
|
||||
- protocoles trading ;
|
||||
- Trading Intelligence.
|
||||
Pendant `0.0.3-pre.007/pre.008` :
|
||||
|
||||
## Validations attendues
|
||||
1. choisir la première release concrète de `0.1.x` ;
|
||||
2. lui donner une mission unique/cohérente ;
|
||||
3. produire son plan `pre.001` ;
|
||||
4. vérifier sa charge ;
|
||||
5. compléter ce prompt avec la version, l'état validé, les sources et validations exactes.
|
||||
|
||||
Au minimum, lorsque du code Rust est introduit :
|
||||
## 9. Validations générales attendues
|
||||
|
||||
Lorsque du code Rust est introduit :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
|
||||
Reference in New Issue
Block a user