v0.0.3-pre.001
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 5
|
||||
# version: 7
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-core-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.0.2-pre.1.fix.3"
|
||||
version = "0.0.3-pre.1"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
56
README.md
56
README.md
@@ -1,47 +1,57 @@
|
||||
<!-- file: README.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Khadhroony Solana Project
|
||||
|
||||
`khadhroony-solana-project` (KSP) est un workspace Rust consacré à la construction d'un ensemble cohérent de bibliothèques, workers, outils et applications autour de la blockchain Solana.
|
||||
`khadhroony-solana-project` (KSP) est un umbrella project consacré à la blockchain Solana. Il regroupe des bibliothèques, APIs de contrats, workers, jobs, outils et applications construits autour de contrats KSP communs.
|
||||
|
||||
## Finalité
|
||||
|
||||
KSP doit fournir des composants réutilisables permettant de comprendre, manipuler, acquérir, traiter, construire et exploiter les données et opérations Solana sans enfermer le projet dans une seule application ou un seul domaine fonctionnel.
|
||||
KSP doit fournir des bibliothèques réutilisables, interconnectables mais également exploitables indépendamment, permettant de lire, décoder, interpréter, construire, signer, exécuter, acquérir, stocker, reconstruire et matérialiser des données et opérations Solana.
|
||||
|
||||
Le projet vise notamment à fournir des fondations pour :
|
||||
Les applications, workers et jobs sont construits au-dessus des contrats et bibliothèques KSP. La connaissance bas niveau de Solana et des protocoles doit rester dans les composants KSP qui en sont propriétaires, et ne doit pas être dupliquée dans les interfaces utilisateur ou les exécutables.
|
||||
|
||||
- les types et contrats Solana communs ;
|
||||
- les interfaces on-chain et représentations wire des programmes ;
|
||||
- le décodage des transactions, instructions, comptes et autres données Solana ;
|
||||
- la construction et, selon les frontières qui seront retenues, l'exécution contrôlée d'opérations on-chain ;
|
||||
- la matérialisation de données décodées vers des faits et modèles canoniques ;
|
||||
- l'acquisition réseau et les transports nécessaires aux usages temps réel, historiques et de replay ;
|
||||
- le stockage, la provenance, l'idempotence et la reconstruction des données dérivées ;
|
||||
- la gestion des wallets, de la configuration et des autres services transversaux ;
|
||||
- des applications, workers et démonstrations spécialisés consommant les bibliothèques KSP ;
|
||||
- des couches d'analyse et d'automatisation pouvant être construites au-dessus de ces fondations.
|
||||
## Objectifs produits
|
||||
|
||||
L'architecture détaillée et les frontières définitives entre ces responsabilités sont définies progressivement par les règles, décisions et plans du projet.
|
||||
À court terme, KSP doit fournir les fondations nécessaires à une future application de trading Solana monoposte s'appuyant sur les mêmes bibliothèques générales que le reste du projet.
|
||||
|
||||
Avant cette application, KSP doit construire progressivement les données, statistiques, signaux et capacités de Trading Intelligence nécessaires pour évaluer correctement les décisions de trading.
|
||||
|
||||
À moyen et long terme, KSP doit permettre de construire notamment :
|
||||
|
||||
- un explorer Solana comparable dans son domaine à `explorer.solana.com` ou Solscan, tout en s'appuyant sur les contrats et données KSP ;
|
||||
- une application d'exploration et d'analyse DEX comparable dans son principe à DexScreener, avec une couverture Solana/DEX plus complète ;
|
||||
- d'autres applications spécialisées réutilisant les mêmes capacités sans réimplémenter la compréhension de Solana.
|
||||
|
||||
Les besoins du trading constituent une priorité produit à court terme mais ne doivent pas rendre les bibliothèques fondamentales spécifiques au trading.
|
||||
|
||||
## Principes structurants
|
||||
|
||||
- Les bibliothèques réutilisables utilisent le préfixe `ksp-` et le suffixe `-lib`.
|
||||
- Les bibliothèques d'implémentation réutilisables utilisent le préfixe `ksp-` et le suffixe `-lib`.
|
||||
- Les crates de contrats/API publics extensibles utilisent la forme `ksp-<domain>-api` et ne portent volontairement pas le suffixe `-lib`, même si elles sont techniquement des bibliothèques Rust.
|
||||
- Une crate `*-api` expose des contrats/types/traits et n'est pas un exécutable directement utilisable sans implémentation appropriée.
|
||||
- Les applications utilisent le préfixe `ksp-app-`.
|
||||
- Les workers utilisent le préfixe `ksp-worker-`.
|
||||
- Les jobs utilisent le préfixe `ksp-job-`.
|
||||
- Une application ou un outil de démonstration se termine par `-demo`.
|
||||
- Les crates Rust sont placées directement sous `crates/`, sans sous-répertoires de catégories.
|
||||
- Les applications sont placées sous `apps/` lorsqu'elles sont introduites.
|
||||
- Les composants réutilisables restent séparés de leurs applications de manipulation ou de démonstration.
|
||||
- Les applications et demos restent des interfaces/compositions ; les opérations réutilisables appartiennent aux composants KSP de niveau approprié.
|
||||
- Les exécutables KSP ne dépendent pas directement de crates externes relatives à Solana ou à un protocole Solana.
|
||||
- Les contrats publics réutilisables doivent pouvoir être implémentés par des crates séparées lorsque cela apporte de la valeur.
|
||||
- Les contrats communs des workers et ceux des jobs restent séparés.
|
||||
- Les notifications de données utilisent un format canonique indépendant du fait que la donnée ait été produite par un worker, un job ou une autre source.
|
||||
- Les dépendances sont maintenues aussi récentes que possible ; les contraintes nécessaires sont documentées explicitement.
|
||||
- Les lockfiles de dépendances ne sont pas versionnés.
|
||||
- Aucun `rust-toolchain.toml` n'est utilisé.
|
||||
- Les composants réutilisables restent séparés de leurs applications de manipulation ou de démonstration.
|
||||
- Les environnements et contraintes des démonstrations doivent être visibles dans leur nomenclature lorsqu'ils ne sont pas sélectionnables.
|
||||
|
||||
## Organisation documentaire
|
||||
## Points d'entrée
|
||||
|
||||
Le point d'entrée des règles est [`RULES.md`](RULES.md).
|
||||
|
||||
Le point d'entrée de la documentation est [`docs/000-README.md`](docs/000-README.md).
|
||||
|
||||
Les livraisons détaillées et leurs validations sont tracées sous [`deltas/`](deltas/).
|
||||
- [`RULES.md`](RULES.md) — index des règles normatives ;
|
||||
- [`ROADMAP.md`](ROADMAP.md) — trajectoire globale du projet ;
|
||||
- [`docs/000-README.md`](docs/000-README.md) — point d'entrée de la documentation ;
|
||||
- [`docs/IDEAS.md`](docs/IDEAS.md) — idées et sujets à explorer ;
|
||||
- [`prompts/000-README.md`](prompts/000-README.md) — prompts de reprise ;
|
||||
- [`deltas/`](deltas/) — historique détaillé des livraisons.
|
||||
|
||||
173
ROADMAP.md
173
ROADMAP.md
@@ -1,5 +1,5 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
@@ -24,9 +24,176 @@ Définir l'identité, les règles, les conventions, l'architecture initiale et l
|
||||
### Étapes
|
||||
|
||||
- [X] `0.0.1` — Initialiser le dépôt avec le `.gitignore` de base.
|
||||
- [/] `0.0.2` — Installer le squelette minimal, les règles initiales et les documents de cadrage nécessaires.
|
||||
- [ ] `0.0.3+` — Poursuivre le brainstorming, la planification architecturale, la nomenclature et le plan global jusqu'à préparation de `0.1.x`.
|
||||
- [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.
|
||||
- [/] 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`.
|
||||
|
||||
### Status
|
||||
|
||||
En cours.
|
||||
|
||||
## 0.1.x — Fondations KSP
|
||||
|
||||
### 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.
|
||||
|
||||
### Étapes
|
||||
|
||||
- [ ] Stabiliser les premiers contrats de `ksp-core-lib`, dont le type d'erreur commun et les 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é.
|
||||
|
||||
## 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`.
|
||||
- [ ] 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é.
|
||||
|
||||
## 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-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é.
|
||||
|
||||
## 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é.
|
||||
|
||||
## 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.
|
||||
- [ ] 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é.
|
||||
|
||||
## 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é.
|
||||
|
||||
## 0.7.x — Trading Intelligence
|
||||
|
||||
### Objectifs
|
||||
|
||||
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.
|
||||
|
||||
### É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.
|
||||
- [ ] Étendre l'automatisation de trading.
|
||||
- [ ] Construire progressivement l'explorer Solana.
|
||||
- [ ] Construire progressivement l'explorer/analyse DEX.
|
||||
- [ ] Étendre Trading Intelligence et les modèles disponibles.
|
||||
|
||||
### Status
|
||||
|
||||
Planifié.
|
||||
|
||||
14
RULES.md
14
RULES.md
@@ -1,5 +1,5 @@
|
||||
<!-- file: RULES.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Index normatif KSP
|
||||
|
||||
@@ -11,10 +11,12 @@ Les règles détaillées sont maintenues sous `docs/rules/` et sont cumulatives
|
||||
|
||||
1. [`docs/rules/RULES_GENERAL.md`](docs/rules/RULES_GENERAL.md) — règles universelles du dépôt et hiérarchie normative ;
|
||||
2. [`docs/rules/RULES_RUST.md`](docs/rules/RULES_RUST.md) — règles applicables aux sources et crates Rust ;
|
||||
3. [`docs/rules/RULES_KSP.md`](docs/rules/RULES_KSP.md) — conventions et frontières spécifiques à KSP ;
|
||||
4. [`docs/rules/RULES_DOCUMENTATION.md`](docs/rules/RULES_DOCUMENTATION.md) — règles des documents Markdown et de leur cycle de vie ;
|
||||
5. [`docs/rules/FILE_CONTRACTS.md`](docs/rules/FILE_CONTRACTS.md) — rôle et mode de modification des principales familles de fichiers ;
|
||||
6. [`docs/rules/VERSION_WORKFLOW.md`](docs/rules/VERSION_WORKFLOW.md) — versions, prereleases, correctifs, deltas, sessions et livraisons.
|
||||
3. [`docs/rules/RULES_KSP.md`](docs/rules/RULES_KSP.md) — conventions, responsabilités et frontières spécifiques à KSP ;
|
||||
4. [`docs/rules/RULES_DEPENDENCIES.md`](docs/rules/RULES_DEPENDENCIES.md) — politique des dépendances externes, notamment Solana et protocoles ;
|
||||
5. [`docs/rules/RULES_DOCUMENTATION.md`](docs/rules/RULES_DOCUMENTATION.md) — règles des documents Markdown et de leur cycle de vie ;
|
||||
6. [`docs/rules/PROMPT_STRUCTURE.md`](docs/rules/PROMPT_STRUCTURE.md) — structure, cycle de vie et dimensionnement des prompts/sessions KSP ;
|
||||
7. [`docs/rules/FILE_CONTRACTS.md`](docs/rules/FILE_CONTRACTS.md) — rôle et mode de modification des principales familles de fichiers ;
|
||||
8. [`docs/rules/VERSION_WORKFLOW.md`](docs/rules/VERSION_WORKFLOW.md) — versions, prereleases, correctifs, deltas, sessions et livraisons.
|
||||
|
||||
## Hiérarchie
|
||||
|
||||
@@ -22,6 +24,6 @@ Une règle possède une portée explicite. Les règles plus spécifiques peuvent
|
||||
|
||||
Toute exception doit être explicite, locale, bornée, justifiée et documentée dans le delta qui l'introduit. Une exception durable devra être reportée dans un document normatif dédié avant clôture de la session concernée.
|
||||
|
||||
Une règle non encore décidée ne doit pas être inventée pour combler un vide : elle reste une question ouverte dans le delta ou le document de planification actif.
|
||||
Une règle non encore décidée ne doit pas être inventée pour combler un vide : elle reste une question ouverte dans le delta, `docs/IDEAS.md` ou le document de planification actif.
|
||||
|
||||
Une validation n'est déclarée réussie que si elle a réellement été exécutée.
|
||||
|
||||
116
deltas/0.0.3/pre.001-fix.001.md
Normal file
116
deltas/0.0.3/pre.001-fix.001.md
Normal file
@@ -0,0 +1,116 @@
|
||||
<!-- file: deltas/0.0.3/pre.001-fix.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.001-fix.001
|
||||
|
||||
## Base requise
|
||||
|
||||
`0.0.3-pre.001`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Corriger et préciser le premier plan `0.0.3` à partir du brainstorming suivant :
|
||||
|
||||
- confirmer `ksp-interface-lib` comme façade wire KSP ;
|
||||
- confirmer `ksp-core-lib` comme propriétaire du type d'erreur commun et des Program IDs ;
|
||||
- retenir le nom `ksp-program-lib` ;
|
||||
- corriger la politique decoder/executor : le decoder ne déprécie pas les formats historiques décodables, tandis que l'executor peut conserver des opérations obsolètes marquées `deprecated` ;
|
||||
- confirmer que la sécurité d'exécution appartient à un niveau supérieur ;
|
||||
- borner W1 à l'acquisition raw live/quasi-live, avec adaptation à chaud et notification ;
|
||||
- préciser la granularité des demos/scénarios ;
|
||||
- confirmer la trajectoire managers spécialisés -> orchestrateur ;
|
||||
- définir `ksp-offchain-transport-lib` comme transport externe général ;
|
||||
- introduire explicitement un principe contract-first pour les futures couches ;
|
||||
- affiner la ligne directrice `0.1.x` à `0.7.x`.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Aucune modification de `Cargo.toml`.
|
||||
|
||||
Ce correctif est exclusivement documentaire. Conformément aux règles KSP, `workspace.package.version` reste donc :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
||||
- `deltas/0.0.3/pre.001-fix.001.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `docs/architecture/000-README.md`
|
||||
- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
- `docs/IDEAS.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Décisions précisées
|
||||
|
||||
### Erreurs
|
||||
|
||||
La direction reste un type d'erreur public commun dans `ksp-core-lib`. La représentation interne doit éviter de rendre N1 dépendant conceptuellement de chaque futur domaine supérieur.
|
||||
|
||||
### Interfaces
|
||||
|
||||
`ksp-interface-lib` possède la façade wire KSP : réexports contrôlés des interfaces officielles jugées suffisamment stables et réimplémentations compatibles lorsque KSP ne veut pas importer une crate protocolaire runtime.
|
||||
|
||||
### Programmes
|
||||
|
||||
Le nom `ksp-program-lib` est retenu.
|
||||
|
||||
Le decoder vise toute surface décodable connue. Le statut `deprecated` ne retire pas le décodage d'une surface historique distinguable.
|
||||
|
||||
L'executor peut conserver une opération obsolète encore techniquement exécutable en la marquant `deprecated`.
|
||||
|
||||
La politique de sécurité d'exécution appartient à une couche supérieure.
|
||||
|
||||
### W1
|
||||
|
||||
W1 :
|
||||
|
||||
- utilise les contrats KSP de configuration, transport et stockage nécessaires ;
|
||||
- ne travaille que sur du live/quasi-live ;
|
||||
- persiste du raw ;
|
||||
- notifie l'arrivée de nouvelles données ;
|
||||
- peut faire évoluer à chaud ce qu'il écoute/rapatrie/stocke ;
|
||||
- ne décode pas ;
|
||||
- ne matérialise pas ;
|
||||
- ne fait pas de replay.
|
||||
|
||||
### Demos/scénarios
|
||||
|
||||
Memo, SPL Token classique, ATA et Token-2022 restent dans des demos/scénarios séparés.
|
||||
|
||||
Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata.
|
||||
|
||||
Solana Program Metadata reste séparé.
|
||||
|
||||
### Contrats précoces
|
||||
|
||||
Les grandes interfaces/traits sont définis tôt pour empêcher les premières implémentations de créer des couplages ad hoc. Leur implémentation complète peut rester différée jusqu'au premier besoin concret.
|
||||
|
||||
## Ligne directrice confirmée
|
||||
|
||||
- `0.1.x` — core/logging/config + application config ;
|
||||
- `0.2.x` — transport on-chain, wallet, interface wire, program framework ;
|
||||
- `0.3.x` — materializer/store/W1 + manager ;
|
||||
- `0.4.x` — premiers Core/SPL/metadata + matérialisations + demos/scénarios ;
|
||||
- `0.5.x` — Anchor puis protocoles trading par releases bornées ;
|
||||
- `0.6.x` — W2 + managers/orchestrateur + application globale ;
|
||||
- `0.7.x` — Trading Intelligence incluant statistiques, features, risque, backtests et ML/XGBoost.
|
||||
|
||||
La ligne directrice est stable, tandis que les numéros de releases et le contenu exact restent révisables selon les dépendances et besoins découverts.
|
||||
|
||||
## Validations
|
||||
|
||||
Correctif documentaire uniquement :
|
||||
|
||||
- structure et présence des fichiers vérifiées lors de la génération ;
|
||||
- aucune commande Cargo requise par le contenu de ce fix ;
|
||||
- aucune modification fonctionnelle ou runtime.
|
||||
103
deltas/0.0.3/pre.001-fix.002.md
Normal file
103
deltas/0.0.3/pre.001-fix.002.md
Normal file
@@ -0,0 +1,103 @@
|
||||
<!-- file: deltas/0.0.3/pre.001-fix.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.001-fix.002
|
||||
|
||||
## Base requise
|
||||
|
||||
`0.0.3-pre.001-fix.001`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Compléter le premier plan `0.0.3` avec :
|
||||
|
||||
- la règle d'extensibilité publique des contrats communs ;
|
||||
- la séparation stricte entre W1 live/quasi-live et le backfill historique ;
|
||||
- la mise à jour du roadmap fonctionnel `0.1.x+` ;
|
||||
- l'introduction d'une structure durable de prompts ;
|
||||
- le démarrage du brouillon vivant du prompt `0.1.x`.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Aucune modification de `Cargo.toml`.
|
||||
|
||||
Ce correctif est exclusivement documentaire. `workspace.package.version` reste :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `prompts/000-README.md`
|
||||
- `prompts/001-PROMPT_STRUCTURE.md`
|
||||
- `prompts/002-V0_1_X_START_PROMPT.md`
|
||||
- `deltas/0.0.3/pre.001-fix.002.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `README.md`
|
||||
- `ROADMAP.md`
|
||||
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
- `docs/rules/FILE_CONTRACTS.md`
|
||||
- `docs/IDEAS.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Décisions ajoutées
|
||||
|
||||
### Contrats publics extensibles
|
||||
|
||||
Les traits/APIs communs tels que `decoder_api`, `executor_api` et `materializer_api` doivent être exposés publiquement et conçus pour pouvoir être implémentés dans des crates séparées.
|
||||
|
||||
Cette extensibilité doit permettre de développer/tester des Program IDs ou matérialisations externes avant décision d'intégration dans les crates officielles KSP.
|
||||
|
||||
### Backfill historique
|
||||
|
||||
Le backfill historique est séparé de W1.
|
||||
|
||||
W1 reste exclusivement live/quasi-live.
|
||||
|
||||
Le backfill possède sa propre pagination, progression, checkpoint/reprise et gouvernance. Son nom/formalisme exact sera décidé pendant l'inventaire des domaines/crates.
|
||||
|
||||
### Roadmap
|
||||
|
||||
Le `ROADMAP.md` décrit désormais la trajectoire actuelle :
|
||||
|
||||
- `0.1.x` — fondations ;
|
||||
- `0.2.x` — accès Solana et fondation programmes ;
|
||||
- `0.3.x` — données, stockage, W1 et backfill ;
|
||||
- `0.4.x` — baseline Solana/SPL/metadata ;
|
||||
- `0.5.x` — Anchor et protocoles trading ;
|
||||
- `0.6.x` — processing autonome/orchestration ;
|
||||
- `0.7.x` — Trading Intelligence ;
|
||||
- `0.8.x+` — extension continue.
|
||||
|
||||
Le plan détaillé reste volontairement souple et peut faire évoluer le contenu exact des releases sans changer la ligne directrice du court terme.
|
||||
|
||||
### Prompts
|
||||
|
||||
Un répertoire racine `prompts/` est introduit.
|
||||
|
||||
Le prompt `0.1.x` commence maintenant sous forme de brouillon vivant. Il sera mis à jour au fil des prereleases `0.0.3` et finalisé pendant la phase documentaire de clôture avant ouverture du développement fonctionnel.
|
||||
|
||||
## Questions restant ouvertes
|
||||
|
||||
- nom et forme exacte du composant de backfill historique ;
|
||||
- nomenclature détaillée des futures APIs publiques ;
|
||||
- règles d'arborescence/réexports à définir avec les premières APIs réelles ;
|
||||
- représentation interne du type `ksp_core_lib::Error` ;
|
||||
- liste complète des crates candidates et graphe de dépendances ;
|
||||
- contenu exact du plan `0.1.x`.
|
||||
|
||||
## Validations
|
||||
|
||||
Correctif documentaire uniquement :
|
||||
|
||||
- structure et présence des fichiers vérifiées lors de la génération ;
|
||||
- aucune commande Cargo requise par le contenu de ce fix ;
|
||||
- aucune modification fonctionnelle ou runtime.
|
||||
118
deltas/0.0.3/pre.001-fix.003.md
Normal file
118
deltas/0.0.3/pre.001-fix.003.md
Normal file
@@ -0,0 +1,118 @@
|
||||
<!-- file: deltas/0.0.3/pre.001-fix.003.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.001-fix.003
|
||||
|
||||
## Base requise
|
||||
|
||||
`0.0.3-pre.001-fix.002`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Finaliser le cadrage de `pre.001` concernant les prompts et le dimensionnement des futures phases :
|
||||
|
||||
- déplacer la convention des prompts sous la documentation normative ;
|
||||
- conserver `prompts/` uniquement pour les prompts eux-mêmes ;
|
||||
- ajouter l'état validé à préserver et les sources externes normatives ;
|
||||
- définir un budget de complexité pour les prereleases intermédiaires ;
|
||||
- imposer le découpage d'une session/version lorsque le prompt prévu devient trop lourd ;
|
||||
- renuméroter le brouillon `0.1.x` après déplacement de la convention.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Aucune modification de `Cargo.toml`.
|
||||
|
||||
Ce correctif est exclusivement documentaire. `workspace.package.version` reste :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/rules/PROMPT_STRUCTURE.md`
|
||||
- `prompts/001-V0_1_X_START_PROMPT.md`
|
||||
- `deltas/0.0.3/pre.001-fix.003.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `RULES.md`
|
||||
- `docs/000-README.md`
|
||||
- `docs/rules/FILE_CONTRACTS.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
- `prompts/000-README.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
- `prompts/001-PROMPT_STRUCTURE.md`
|
||||
- `prompts/002-V0_1_X_START_PROMPT.md`
|
||||
|
||||
Le contenu du premier est déplacé et renforcé sous `docs/rules/PROMPT_STRUCTURE.md`.
|
||||
|
||||
Le second est renommé en `prompts/001-V0_1_X_START_PROMPT.md` et mis à jour.
|
||||
|
||||
## Décisions ajoutées
|
||||
|
||||
### Emplacement des conventions de prompt
|
||||
|
||||
Les règles/conventions de rédaction des prompts sont normatives et appartiennent à `docs/rules/PROMPT_STRUCTURE.md`.
|
||||
|
||||
Le répertoire `prompts/` contient uniquement l'index pratique et les prompts de reprise.
|
||||
|
||||
### Première et dernière prerelease
|
||||
|
||||
Par défaut :
|
||||
|
||||
- `pre.001` = brainstorming/audit si nécessaire + planification + découpage ;
|
||||
- dernière prerelease = validations finales + documentation + nettoyage/archivage + prompt suivant.
|
||||
|
||||
### Budget des prereleases
|
||||
|
||||
Lors de la planification, chaque prerelease intermédiaire après `pre.001` doit viser une charge bornée.
|
||||
|
||||
Une tranche estimée à plus d'environ 15–20 minutes de travail effectif doit être scindée avant développement.
|
||||
|
||||
Cette durée est un budget de planification, pas une promesse d'exécution.
|
||||
|
||||
### Contrôle anti-saturation
|
||||
|
||||
Avant finalisation d'un prompt de session suivante, la charge totale de la session prévue doit être évaluée.
|
||||
|
||||
Si elle paraît trop importante pour conserver un contexte fiable et une qualité de travail correcte, le plan est réparti sur :
|
||||
|
||||
- plusieurs sessions ;
|
||||
- et/ou plusieurs versions lorsque la frontière fonctionnelle le justifie.
|
||||
|
||||
Le roadmap conserve sa ligne directrice même si son découpage initial évolue.
|
||||
|
||||
### Qualité des prompts
|
||||
|
||||
La structure KSP inclut désormais explicitement :
|
||||
|
||||
- base requise ;
|
||||
- état validé à préserver ;
|
||||
- sources de vérité internes ;
|
||||
- sources externes normatives lorsqu'elles existent ;
|
||||
- décisions acquises ;
|
||||
- objectifs/hors périmètre ;
|
||||
- plan souple ;
|
||||
- validations ;
|
||||
- critères de sortie ;
|
||||
- préparation de la suite.
|
||||
|
||||
Cette structure reprend les qualités utiles observées dans les prompts historiques tout en évitant de recopier les règles et l'architecture déjà normalisées dans le dépôt.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Aucune nouvelle question bloquante pour `pre.001`.
|
||||
|
||||
Les questions architecturales restantes sont poursuivies dans `pre.002+`.
|
||||
|
||||
## Validations
|
||||
|
||||
Correctif documentaire uniquement :
|
||||
|
||||
- présence des en-têtes `file:` / `version:` vérifiée sur les fichiers livrés ;
|
||||
- cohérence des chemins `prompts/` / `docs/rules/` vérifiée dans cette livraison ;
|
||||
- aucune commande Cargo requise ;
|
||||
- aucune modification fonctionnelle ou runtime.
|
||||
124
deltas/0.0.3/pre.001-fix.004.md
Normal file
124
deltas/0.0.3/pre.001-fix.004.md
Normal file
@@ -0,0 +1,124 @@
|
||||
<!-- file: deltas/0.0.3/pre.001-fix.004.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.001-fix.004
|
||||
|
||||
## Base requise
|
||||
|
||||
`0.0.3-pre.001-fix.003`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Formaliser les dernières décisions de nomenclature et d'extensibilité :
|
||||
|
||||
- utiliser `ksp-<domain>-api` plutôt que `ksp-<domain>-api-lib` ;
|
||||
- séparer contrats publics et implémentations officielles ;
|
||||
- séparer strictement APIs workers et jobs ;
|
||||
- retenir `ksp-job-backfill` pour l'acquisition historique à la demande ;
|
||||
- normaliser les notifications de données indépendamment du producteur ;
|
||||
- confirmer PostgreSQL comme implémentation de référence dans `ksp-store-lib` ;
|
||||
- confirmer l'absence de pipeline/scenario monolithique ;
|
||||
- confirmer Trading Intelligence avant la couche/application de trading opérationnelle.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Aucune modification de `Cargo.toml`.
|
||||
|
||||
Ce correctif est exclusivement documentaire. `workspace.package.version` reste :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `deltas/0.0.3/pre.001-fix.004.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `README.md`
|
||||
- `ROADMAP.md`
|
||||
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
- `docs/IDEAS.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
- `prompts/001-V0_1_X_START_PROMPT.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Décisions ajoutées
|
||||
|
||||
### Nomenclature des APIs
|
||||
|
||||
Les crates de contrats publics extensibles utilisent :
|
||||
|
||||
```text
|
||||
ksp-<domain>-api
|
||||
```
|
||||
|
||||
Elles restent techniquement des bibliothèques Rust mais n'utilisent pas le suffixe `-lib`, réservé par défaut aux bibliothèques d'implémentation.
|
||||
|
||||
Premiers couples :
|
||||
|
||||
```text
|
||||
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é.
|
||||
|
||||
### Store
|
||||
|
||||
`ksp-store-api` porte les contrats backend-agnostic.
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence.
|
||||
|
||||
### Workers et jobs
|
||||
|
||||
Les contrats communs sont strictement séparés :
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
ksp-job-api
|
||||
```
|
||||
|
||||
Aucune API universelle worker+job n'est prévue.
|
||||
|
||||
`ksp-worker-control-lib` reste candidat pour l'implémentation de contrôle des workers uniquement.
|
||||
|
||||
`ksp-job-backfill` est retenu comme candidat du backfill historique à la demande.
|
||||
|
||||
D'autres jobs pourront apparaître pour metadata, quotes ou autres travaux ponctuels.
|
||||
|
||||
### 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 utilise le même contrat de notification qu'il provienne d'un worker, d'un job ou d'une autre source.
|
||||
|
||||
`ksp-store-api` est le propriétaire candidat de ces contrats lorsque la notification concerne une donnée persistée.
|
||||
|
||||
Le contrat de notification reste séparé du mécanisme de transport.
|
||||
|
||||
### Pipelines
|
||||
|
||||
Pas de `ksp-pipeline-lib` monolithique. Les pipelines sont introduits séparément à la demande avec un périmètre concret.
|
||||
|
||||
### Scénarios
|
||||
|
||||
Pas de `ksp-scenarios-lib` monolithique. Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib`.
|
||||
|
||||
### Trading
|
||||
|
||||
Trading Intelligence est introduit avant la couche/application de trading opérationnelle.
|
||||
|
||||
## Validations
|
||||
|
||||
Correctif documentaire uniquement :
|
||||
|
||||
- présence des en-têtes `file:` / `version:` vérifiée lors de la génération ;
|
||||
- aucune commande Cargo requise ;
|
||||
- aucune modification fonctionnelle ou runtime.
|
||||
95
deltas/0.0.3/pre.001.md
Normal file
95
deltas/0.0.3/pre.001.md
Normal file
@@ -0,0 +1,95 @@
|
||||
<!-- file: deltas/0.0.3/pre.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.001
|
||||
|
||||
## Base requise
|
||||
|
||||
Release `v0.0.2`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Ouvrir la phase de brainstorming/planification `0.0.3` sans développement fonctionnel.
|
||||
|
||||
Cette tranche formalise les objectifs produits déjà discutés, le premier modèle de couches, les règles de dépendances externes, les responsabilités des applications/demos/workers et une prévision souple des prereleases nécessaires pour terminer la fondation avant `0.1.x`.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe à :
|
||||
|
||||
```text
|
||||
0.0.3-pre.1
|
||||
```
|
||||
|
||||
Cette synchronisation est obligatoire pour toute nouvelle prerelease non-fix, même lorsque la tranche est essentiellement documentaire.
|
||||
|
||||
Le fichier livré utilise `# version: 7`, en supposant que la publication finale `v0.0.2` a synchronisé le `Cargo.toml` de la base vers la version fichier 6 conformément aux règles. Si la base locale ne correspond pas à cette hypothèse, la version de fichier doit être réconciliée avant commit sans changer l'identifiant fonctionnel `0.0.3-pre.1`.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/architecture/000-README.md`
|
||||
- `docs/architecture/001-PROJECT_OBJECTIVES.md`
|
||||
- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md`
|
||||
- `docs/plans/000-README.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
- `docs/rules/RULES_DEPENDENCIES.md`
|
||||
- `deltas/0.0.3/pre.001.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `README.md`
|
||||
- `RULES.md`
|
||||
- `ROADMAP.md`
|
||||
- `docs/000-README.md`
|
||||
- `docs/IDEAS.md`
|
||||
- `docs/rules/FILE_CONTRACTS.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Décisions enregistrées
|
||||
|
||||
- `ksp-config-lib` et `ksp-logging-lib` sont positionnés en N1 avec `ksp-core-lib` et la future crate d'interface/wire.
|
||||
- Les niveaux servent à déterminer responsabilité et sens des dépendances ; ils ne forcent pas un passage par toutes les couches.
|
||||
- Une application spécialisée peut dépendre directement de la bibliothèque KSP qu'elle manipule.
|
||||
- Les applications et demos sont des interfaces/compositions et ne réimplémentent pas les opérations réutilisables.
|
||||
- Une demo réutilise une bibliothèque de scénarios lorsqu'un scénario correspondant existe.
|
||||
- Les workers peuvent posséder l'orchestration runtime nécessaire mais ne contournent pas les bibliothèques KSP.
|
||||
- Applications, demos et workers ne dépendent pas directement de crates externes liées à Solana ou à un protocole Solana.
|
||||
- Les dépendances Solana externes sont confinées aux bibliothèques KSP propriétaires appropriées.
|
||||
- `solana-pubkey`, `solana-keypair`, `solana-signer`, `solana-hash` et `solana-nonce` sont retenues comme primitives fondamentales autorisées dans les bibliothèques appropriées.
|
||||
- `mpl-token-metadata`, `spl-elgamal-registry-interface` et les crates protocolaires analogues sont interdites par défaut comme dépendances runtime ; KSP préfère posséder les contrats wire nécessaires.
|
||||
- L'objectif court terme est une application de trading monoposte ; les objectifs moyen/long terme incluent un explorer Solana et une application d'exploration/analyse DEX plus complète.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
- nom définitif et périmètre exact de `ksp-interface-lib` ;
|
||||
- découpage decoder / construction / exécution ;
|
||||
- liste candidate et responsabilité précise des crates N2/N3 ;
|
||||
- position exacte de wallet, transport, store, pipeline, replay et scénarios ;
|
||||
- méthode de conformité wire contre les projets externes ;
|
||||
- éventuel usage de crates protocolaires externes uniquement comme dépendances de test ;
|
||||
- nomenclature finale de toutes les applications et workers ;
|
||||
- plan exact des versions fonctionnelles `0.1.x+`.
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
- vérification statique de la syntaxe TOML du `Cargo.toml` livré ;
|
||||
- vérification de présence des en-têtes `file:` et `version:` des fichiers Markdown/TOML livrés ;
|
||||
- vérification de l'arborescence et de l'identifiant du delta.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
Les commandes Cargo doivent être exécutées sur le dépôt cible après application :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Aucun code fonctionnel n'est ajouté dans cette tranche.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/000-README.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Documentation KSP
|
||||
|
||||
@@ -13,14 +13,24 @@ Le répertoire contient la documentation durable du projet : règles détaillée
|
||||
|
||||
Les documents temporaires d'une livraison ne sont pas stockés sous `docs/`. Ils sont enregistrés sous `deltas/` afin de conserver un seul historique de livraison pour l'ensemble du dépôt.
|
||||
|
||||
## Organisation initiale
|
||||
## Organisation
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── 000-README.md
|
||||
├── IDEAS.md
|
||||
├── architecture/
|
||||
│ ├── 000-README.md
|
||||
│ ├── 001-PROJECT_OBJECTIVES.md
|
||||
│ ├── 002-LAYERS_AND_DEPENDENCIES.md
|
||||
│ └── 003-COMPONENT_CONTRACTS.md
|
||||
├── plans/
|
||||
│ ├── 000-README.md
|
||||
│ └── 001-V0_0_3_PLAN.md
|
||||
└── rules/
|
||||
├── FILE_CONTRACTS.md
|
||||
├── PROMPT_STRUCTURE.md
|
||||
├── RULES_DEPENDENCIES.md
|
||||
├── RULES_DOCUMENTATION.md
|
||||
├── RULES_GENERAL.md
|
||||
├── RULES_KSP.md
|
||||
@@ -28,10 +38,20 @@ docs/
|
||||
└── VERSION_WORKFLOW.md
|
||||
```
|
||||
|
||||
`IDEAS.md` conserve les pistes et questions à explorer qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.
|
||||
D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura été décidé, notamment pour les références, décisions, guides et validations.
|
||||
|
||||
D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura été décidé, notamment pour l'architecture, les références, les décisions, les plans et les validations.
|
||||
## Documents actifs de planification
|
||||
|
||||
Le plan actif de la phase fondatrice est [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md).
|
||||
|
||||
`IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.
|
||||
|
||||
## Prompts
|
||||
|
||||
Les prompts de reprise eux-mêmes sont conservés sous [`../prompts/`](../prompts/).
|
||||
|
||||
Leur contrat de rédaction, de dimensionnement et de cycle de vie est défini dans [`rules/PROMPT_STRUCTURE.md`](rules/PROMPT_STRUCTURE.md).
|
||||
|
||||
## Documents normatifs
|
||||
|
||||
Les règles sont indexées depuis [`../RULES.md`](../RULES.md). Aucun document de brainstorming ou de delta ne devient normatif uniquement parce qu'il existe dans le dépôt.
|
||||
Les règles sont indexées depuis [`../RULES.md`](../RULES.md). Aucun document de brainstorming, plan ou delta ne devient normatif uniquement parce qu'il existe dans le dépôt.
|
||||
|
||||
126
docs/IDEAS.md
126
docs/IDEAS.md
@@ -1,41 +1,127 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# 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.
|
||||
## APIs et extensibilité
|
||||
|
||||
Une idée peut évoluer vers un plan, une règle, une décision architecturale ou une entrée du `ROADMAP.md`. Lorsqu'elle est transférée, le document conserve une trace concise de son issue afin de ne pas perdre l'historique de la réflexion.
|
||||
### Nomenclature `*-api`
|
||||
|
||||
## Statuts
|
||||
**Status :** Retenue
|
||||
|
||||
Les statuts recommandés sont :
|
||||
Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
|
||||
- `À explorer` ;
|
||||
- `En exploration` ;
|
||||
- `Retenue` ;
|
||||
- `Rejetée` ;
|
||||
- `Transférée au roadmap` ;
|
||||
- `Transférée vers une décision/règle`.
|
||||
Premiers couples retenus :
|
||||
|
||||
## Architecture des interfaces Solana
|
||||
```text
|
||||
ksp-program-api / ksp-program-lib
|
||||
ksp-materializer-api / ksp-materializer-lib
|
||||
ksp-store-api / ksp-store-lib
|
||||
```
|
||||
|
||||
### Nom et périmètre de la crate commune d'interfaces/wire
|
||||
Éviter un unique `ksp-api-lib` monolithique.
|
||||
|
||||
### APIs workers et jobs
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Les workers et jobs ont des modèles de lifecycle différents et ne doivent pas partager une API universelle commune.
|
||||
|
||||
Prévoir séparément :
|
||||
|
||||
```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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Nommage des items publics
|
||||
|
||||
**Status :** À explorer
|
||||
|
||||
Déterminer le nom définitif et le périmètre exact de la crate commune actuellement envisagée sous un nom tel que `ksp-interface-lib`. Elle doit permettre de centraliser les contrats wire/on-chain partagés sans absorber les responsabilités de transport, matérialisation ou stockage.
|
||||
Définir avec les premières APIs réelles les conventions de nommage des traits, structs, enums, aliases, constantes et autres items exportés publiquement.
|
||||
|
||||
### Regroupement decoder / construction / executor
|
||||
### Arborescence et réexports
|
||||
|
||||
**Status :** À explorer
|
||||
|
||||
Déterminer si le décodage et la construction d'instructions doivent rester dans une même crate ou être séparés, et distinguer cette question de l'exécution réseau proprement dite : signature, simulation, soumission et confirmation.
|
||||
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.
|
||||
|
||||
## Applications et environnements
|
||||
## Données et notifications
|
||||
|
||||
### Nomenclature complète des environnements de démonstration
|
||||
### Notifications normalisées de données
|
||||
|
||||
**Status :** À explorer
|
||||
**Status :** Retenue
|
||||
|
||||
Formaliser la nomenclature des applications et demos lorsque l'environnement est imposé (`mainnet`, `devnet`, `testnet`, `local-validator`, `synthetic`) ou sélectionnable. Une application dont le nom impose un environnement doit forcer les profils, endpoints, bases et autres ressources cohérents avec cet environnement.
|
||||
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-store-api` est le propriétaire candidat de ces contrats lorsque la notification signifie qu'une donnée persistée est disponible.
|
||||
|
||||
Le transport concret de notification reste indépendant du contrat.
|
||||
|
||||
### Backend PostgreSQL
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation de référence de `ksp-store-api`.
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
### W1
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
W1 reste strictement un worker raw live/quasi-live avec reconfiguration à chaud, persistance raw et notification. Aucun replay/backfill.
|
||||
|
||||
### Backfill historique
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Le backfill historique est un job distinct, candidat `ksp-job-backfill`.
|
||||
|
||||
### Autres jobs
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Des jobs séparés pourront apparaître pour metadata, quotes ou autres traitements ponctuels lorsqu'un besoin réel existe.
|
||||
|
||||
### Orchestrateur
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
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.
|
||||
|
||||
## Pipelines
|
||||
|
||||
### Pas de pipeline monolithique
|
||||
|
||||
**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é.
|
||||
|
||||
## Trading
|
||||
|
||||
### Trading Intelligence avant application de trading
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Construire d'abord statistiques, features, signaux, risque, backtests, détection de patterns/anomalies et intégrations ML telles que XGBoost. La couche/application de trading opérationnelle est construite ensuite.
|
||||
|
||||
24
docs/architecture/000-README.md
Normal file
24
docs/architecture/000-README.md
Normal file
@@ -0,0 +1,24 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
Ce répertoire contient les documents d'architecture et de périmètre durable de Khadhroony Solana Project.
|
||||
|
||||
Les documents d'architecture distinguent explicitement :
|
||||
|
||||
- les décisions déjà retenues ;
|
||||
- les directions fortes encore à valider par l'implémentation ;
|
||||
- les hypothèses de travail ;
|
||||
- les questions ouvertes ;
|
||||
- les conséquences attendues sur les futurs composants.
|
||||
|
||||
Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
|
||||
|
||||
## Ordre initial
|
||||
|
||||
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.
|
||||
|
||||
Les futurs documents prioritaires peuvent continuer avec `004-`, `005-`, etc. lorsqu'un ordre de lecture explicite apporte une valeur réelle.
|
||||
68
docs/architecture/001-PROJECT_OBJECTIVES.md
Normal file
68
docs/architecture/001-PROJECT_OBJECTIVES.md
Normal file
@@ -0,0 +1,68 @@
|
||||
<!-- file: docs/architecture/001-PROJECT_OBJECTIVES.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Objectifs de Khadhroony Solana Project
|
||||
|
||||
## Positionnement
|
||||
|
||||
Khadhroony Solana Project est un umbrella project consacré à la blockchain Solana.
|
||||
|
||||
Sa fonction n'est pas de construire une seule application monolithique, mais de fournir des bibliothèques KSP cohérentes, réutilisables, interconnectables et, lorsque leur contrat le permet, utilisables indépendamment.
|
||||
|
||||
## Capacités générales visées
|
||||
|
||||
KSP doit progressivement fournir des capacités permettant notamment de :
|
||||
|
||||
- représenter les primitives et contrats KSP/Solana communs ;
|
||||
- posséder les interfaces wire nécessaires aux programmes on-chain pris en charge ;
|
||||
- acquérir des données Solana en temps réel ou historiquement ;
|
||||
- décoder transactions, instructions, comptes, événements et autres formats pertinents ;
|
||||
- construire des opérations compatibles avec les programmes supportés ;
|
||||
- signer, simuler, soumettre et suivre des opérations lorsque les frontières correspondantes auront été définies ;
|
||||
- gérer les wallets et signers nécessaires aux usages KSP ;
|
||||
- matérialiser les données décodées vers des faits canoniques ;
|
||||
- stocker, rejouer, reconstruire et interroger les données ;
|
||||
- composer ces capacités dans des applications, workers et demos spécialisés.
|
||||
|
||||
## Objectif court terme
|
||||
|
||||
L'objectif produit prioritaire est une application de trading Solana monoposte.
|
||||
|
||||
Cette priorité ne transforme pas les bibliothèques fondamentales en bibliothèques spécifiques au trading. Les données, interfaces, transports, décodages et modèles généraux doivent rester réutilisables par les autres produits KSP.
|
||||
|
||||
## Objectifs moyen et long terme
|
||||
|
||||
KSP doit permettre de construire notamment :
|
||||
|
||||
### Explorer Solana
|
||||
|
||||
Une application générale comparable dans son domaine à `explorer.solana.com` ou Solscan, capable d'exploiter les données et contrats KSP sans créer une seconde pile de décodage/stockage.
|
||||
|
||||
### Explorer et analyse DEX
|
||||
|
||||
Une application comparable dans son principe à DexScreener, avec une couverture plus complète des DEX et des modèles de marché Solana lorsque les données KSP le permettent.
|
||||
|
||||
## Non-objectifs architecturaux
|
||||
|
||||
KSP ne doit pas :
|
||||
|
||||
- devenir un monolithe centré sur une seule application ;
|
||||
- dupliquer la même connaissance Solana dans plusieurs produits ;
|
||||
- transformer les applications/demos en propriétaires de logique bas niveau ou protocolaire ;
|
||||
- utiliser automatiquement une crate externe de protocole simplement parce qu'elle fournit les structures wire nécessaires ;
|
||||
- forcer chaque application à dépendre de toutes les couches KSP ;
|
||||
- créer des bibliothèques spécifiques à un produit lorsque la responsabilité est générale à Solana ou à KSP.
|
||||
|
||||
## Conséquence structurante
|
||||
|
||||
Les produits finaux doivent partager les mêmes bibliothèques fondamentales :
|
||||
|
||||
```text
|
||||
bibliothèques KSP
|
||||
├── application de trading
|
||||
├── explorer Solana
|
||||
├── explorer/analyse DEX
|
||||
└── autres applications spécialisées
|
||||
```
|
||||
|
||||
La première utilisation d'une capacité dans un produit ne détermine donc pas automatiquement son propriétaire architectural.
|
||||
196
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
Normal file
196
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
Normal file
@@ -0,0 +1,196 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
## Rôle des niveaux
|
||||
|
||||
Les niveaux N1 à N4 servent à raisonner sur les responsabilités, la stabilité et le sens des dépendances. Ils ne constituent pas une chaîne d'appels obligatoire.
|
||||
|
||||
Une couche supérieure peut dépendre directement d'une bibliothèque KSP plus basse lorsque cette bibliothèque est exactement la propriétaire de la capacité recherchée.
|
||||
|
||||
## N1 — Fondations
|
||||
|
||||
N1 contient les contrats et services transversaux qui doivent rester bas dans le graphe de dépendances.
|
||||
|
||||
Positionnement actuellement retenu :
|
||||
|
||||
- `ksp-core-lib` — primitives et contrats fondamentaux réellement transversaux, type d'erreur commun KSP et responsabilité autrefois séparée des identifiants de programmes ;
|
||||
- `ksp-interface-lib` — façade KSP des interfaces/wire on-chain nécessaires aux autres bibliothèques ;
|
||||
- `ksp-config-lib` — contrats, chargement/résolution et manipulation autorisée de la configuration et des profils ;
|
||||
- `ksp-logging-lib` — fondations communes de logging/tracing.
|
||||
|
||||
Une bibliothèque N1 ne doit pas dépendre d'une fonctionnalité métier située dans une couche supérieure.
|
||||
|
||||
## N2 — Capacités Solana
|
||||
|
||||
N2 regroupe les capacités réutilisables opérant sur Solana au-dessus des fondations.
|
||||
|
||||
Le nom `ksp-program-lib` est retenu pour la future bibliothèque propriétaire du traitement des programmes : décodage et opérations techniquement constructibles/exécutables. Elle doit s'appuyer sur `ksp-interface-lib` plutôt que faire porter les contrats wire aux applications.
|
||||
|
||||
Les autres responsabilités N2 candidates comprennent notamment :
|
||||
|
||||
- `ksp-onchain-transport-lib` ;
|
||||
- `ksp-offchain-transport-lib` lorsqu'un premier besoin réel justifiera son implémentation ;
|
||||
- `ksp-wallet-lib`.
|
||||
|
||||
Le transport off-chain est général : il ne se limite pas aux metadata et pourra servir à des ressources telles que metadata externes, prix de référence, services de routage ou autres données hors blockchain.
|
||||
|
||||
## N3 — Données et orchestration réutilisable
|
||||
|
||||
N3 doit accueillir les responsabilités qui interprètent, persistent ou orchestrent des capacités inférieures, notamment :
|
||||
|
||||
- matérialisation ;
|
||||
- stockage ;
|
||||
- replay/reconstruction ;
|
||||
- pipelines ;
|
||||
- scénarios réutilisables ;
|
||||
- contrôle/orchestration de workers lorsqu'il sera introduit.
|
||||
|
||||
### W1
|
||||
|
||||
W1 est un worker d'acquisition live/quasi-live uniquement.
|
||||
|
||||
Il consomme au minimum les contrats de configuration, transport on-chain et stockage nécessaires pour :
|
||||
|
||||
1. écouter les sources configurées ;
|
||||
2. rapatrier les données ;
|
||||
3. les persister sous forme raw ;
|
||||
4. notifier qu'une nouvelle information raw est disponible.
|
||||
|
||||
W1 :
|
||||
|
||||
- ne décode pas ;
|
||||
- ne matérialise pas ;
|
||||
- ne réalise pas de replay ;
|
||||
- ne décide pas de l'utilisation métier des données collectées ;
|
||||
- doit pouvoir faire évoluer à chaud ce qu'il écoute, rapatrie ou stocke selon les mécanismes de configuration/commande qui seront définis.
|
||||
|
||||
Les consommateurs des notifications W1 décident eux-mêmes s'ils doivent décoder, matérialiser ou effectuer un autre traitement.
|
||||
|
||||
### W2
|
||||
|
||||
W2 est réservé à une phase ultérieure de processing. Son contrat précis sera défini après stabilisation du décodage, de la matérialisation et du store. Il ne doit pas être confondu avec W1.
|
||||
|
||||
## N4 — Exécutables
|
||||
|
||||
N4 contient les applications, demos et workers.
|
||||
|
||||
### Dépendances directes autorisées
|
||||
|
||||
N4 n'est pas obligé de traverser N3 puis N2 pour atteindre N1.
|
||||
|
||||
Exemples valides :
|
||||
|
||||
```text
|
||||
ksp-app-config-desk
|
||||
└── ksp-config-lib
|
||||
|
||||
ksp-app-store-desk
|
||||
├── ksp-store-lib
|
||||
└── ksp-config-lib
|
||||
```
|
||||
|
||||
Une application de configuration n'a aucune raison de dépendre de couches Solana qui ne participent pas à sa fonction.
|
||||
|
||||
Une application de store peut utiliser `ksp-config-lib` pour sélectionner/résoudre un profil et `ksp-store-lib` pour valider, initialiser ou reconstruire le stockage. Elle ne doit pas réimplémenter ces opérations ni appeler directement le backend propriétaire.
|
||||
|
||||
## Applications et demos
|
||||
|
||||
Une application ou demo :
|
||||
|
||||
- recueille et présente les données ;
|
||||
- effectue les conversions/validations strictement liées à son interface ;
|
||||
- sélectionne les options, profils et scénarios autorisés ;
|
||||
- appelle les bibliothèques KSP propriétaires ;
|
||||
- affiche ou exporte les résultats.
|
||||
|
||||
Elle ne doit pas réécrire :
|
||||
|
||||
- le décodage ;
|
||||
- la logique protocolaire ;
|
||||
- les PDA et layouts ;
|
||||
- la construction d'instructions ;
|
||||
- la matérialisation ;
|
||||
- les opérations de stockage ;
|
||||
- les scénarios réutilisables ;
|
||||
- les autres opérations appartenant à une bibliothèque inférieure.
|
||||
|
||||
Lorsqu'une bibliothèque de scénarios possède déjà un workflow de démonstration, l'application demo doit l'appeler.
|
||||
|
||||
Les demos/scénarios doivent rester séparés par responsabilité fonctionnelle cohérente. Un regroupement n'est autorisé que lorsque plusieurs interfaces représentent réellement le même domaine fonctionnel.
|
||||
|
||||
Exemples actuellement retenus :
|
||||
|
||||
- Memo : demo/scénarios séparés ;
|
||||
- SPL Token classique : demo/scénarios séparés ;
|
||||
- Associated Token Account : demo/scénarios séparés ;
|
||||
- Token-2022 : demo/scénarios séparés ;
|
||||
- metadata d'assets/tokens : Metaplex Token Metadata et Token-2022 Metadata peuvent partager une même famille de demo/scénarios ;
|
||||
- Solana Program Metadata (SPM) reste séparé car il n'appartient pas à la même catégorie fonctionnelle.
|
||||
|
||||
## Workers
|
||||
|
||||
Les workers sont différents des interfaces utilisateur. Ils peuvent contenir l'orchestration runtime strictement nécessaire à leur responsabilité.
|
||||
|
||||
Un worker doit néanmoins consommer les bibliothèques KSP propriétaires des contrats Solana et ne doit pas dépendre directement de crates Solana/protocoles externes.
|
||||
|
||||
Les premiers managers de workers peuvent être spécialisés et séparés. Un orchestrateur global sera introduit ultérieurement lorsque plusieurs workers/managers justifieront réellement cette abstraction.
|
||||
|
||||
## Firewall des dépendances externes
|
||||
|
||||
Les exécutables KSP dépendent des bibliothèques KSP pour les capacités Solana.
|
||||
|
||||
```text
|
||||
application / demo / worker
|
||||
│
|
||||
▼
|
||||
bibliothèques KSP
|
||||
│
|
||||
▼
|
||||
primitives externes explicitement autorisées
|
||||
│
|
||||
▼
|
||||
Solana
|
||||
```
|
||||
|
||||
Une dépendance externe Solana ou protocolaire doit être possédée par la bibliothèque KSP la plus basse et la plus cohérente avec sa responsabilité.
|
||||
|
||||
## Sens des dépendances
|
||||
|
||||
Le principe recherché est :
|
||||
|
||||
```text
|
||||
N4 ───────► N3 / N2 / N1
|
||||
N3 ───────► N2 / N1
|
||||
N2 ───────► N1
|
||||
N1 ───────► fondations externes explicitement autorisées
|
||||
```
|
||||
|
||||
Il n'est pas permis d'introduire une dépendance vers une couche supérieure pour résoudre localement un problème. Si cela semble nécessaire, le classement des responsabilités doit être réexaminé.
|
||||
|
||||
## Principe contract-first
|
||||
|
||||
Les contrats minimaux entre couches doivent être définis suffisamment tôt pour que les composants futurs puissent se construire contre une frontière KSP stable, même lorsque l'implémentation complète arrive dans une version ultérieure.
|
||||
|
||||
Ce principe s'applique notamment aux futurs :
|
||||
|
||||
- decoders ;
|
||||
- executors/constructeurs d'opérations ;
|
||||
- materializers ;
|
||||
- store/repositories ;
|
||||
- transports ;
|
||||
- scénarios ;
|
||||
- notifications et contrôle des workers ;
|
||||
- orchestrateur.
|
||||
|
||||
Il ne signifie pas qu'il faut implémenter prématurément toutes les fonctionnalités. Les interfaces/traits peuvent évoluer légèrement lorsque l'expérience révèle un besoin réel, mais une dépendance entre couches ne doit pas être remplacée par un couplage ad hoc sous prétexte que le contrat final n'existe pas encore.
|
||||
|
||||
## Questions encore ouvertes
|
||||
|
||||
- représentation interne exacte du type d'erreur commun KSP ;
|
||||
- découpage interne précis de `ksp-program-lib` ;
|
||||
- politique de sécurité/exécution située au-dessus de `ksp-program-lib` ;
|
||||
- position précise du pipeline et du futur orchestrateur ;
|
||||
- méthode de conformité wire contre les projets externes ;
|
||||
- graphe de dépendances précis crate par crate.
|
||||
127
docs/architecture/003-COMPONENT_CONTRACTS.md
Normal file
127
docs/architecture/003-COMPONENT_CONTRACTS.md
Normal file
@@ -0,0 +1,127 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
## Convention API / implémentation
|
||||
|
||||
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare :
|
||||
|
||||
```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>-lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe.
|
||||
|
||||
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.
|
||||
|
||||
Premiers couples retenus :
|
||||
|
||||
- `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 à :
|
||||
|
||||
```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.
|
||||
|
||||
Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
|
||||
Premier candidat retenu :
|
||||
|
||||
```text
|
||||
ksp-job-backfill
|
||||
```
|
||||
|
||||
D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe.
|
||||
|
||||
Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires.
|
||||
|
||||
## 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é.
|
||||
|
||||
## 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é.
|
||||
14
docs/plans/000-README.md
Normal file
14
docs/plans/000-README.md
Normal file
@@ -0,0 +1,14 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
Ce répertoire contient les plans actifs ou historiques des versions et phases de travail KSP.
|
||||
|
||||
Un plan décrit le périmètre, les décisions déjà acquises, les questions ouvertes, les validations attendues et la prévision souple des prereleases. Il ne remplace pas le `ROADMAP.md`, qui reste global, ni les deltas qui enregistrent le travail réellement livré.
|
||||
|
||||
## Plan actif
|
||||
|
||||
- [`001-V0_0_3_PLAN.md`](001-V0_0_3_PLAN.md) — plan de la phase de brainstorming et planification `0.0.3`.
|
||||
|
||||
Le préfixe numérique sert ici à maintenir le plan actif prioritaire après `000-README.md`. Lorsqu'un autre ordre devient préférable, la convention documentaire permet de le réorganiser explicitement.
|
||||
101
docs/plans/001-V0_0_3_PLAN.md
Normal file
101
docs/plans/001-V0_0_3_PLAN.md
Normal file
@@ -0,0 +1,101 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# 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`.
|
||||
|
||||
## Décisions structurantes acquises
|
||||
|
||||
- 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.
|
||||
|
||||
## Ligne directrice du développement fonctionnel
|
||||
|
||||
- `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.
|
||||
|
||||
## Prévision souple des prereleases 0.0.3
|
||||
|
||||
### `pre.001` — Base de planification
|
||||
|
||||
Considérée stabilisée après les fixes de cadrage.
|
||||
|
||||
### `pre.002` — Domaines et crates candidates
|
||||
|
||||
- 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
|
||||
|
||||
- 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, décodage et exécution
|
||||
|
||||
- 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, storage et acquisitions
|
||||
|
||||
- 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, demos et scénarios
|
||||
|
||||
- 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 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.
|
||||
|
||||
### `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`.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/FILE_CONTRACTS.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 8 -->
|
||||
|
||||
# Contrats des fichiers
|
||||
|
||||
@@ -23,15 +23,25 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
|
||||
|
||||
## Répertoire `docs/`
|
||||
|
||||
| Fichier/famille | Responsabilité | Règle de modification |
|
||||
|---------------------------------|----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `docs/000-README.md` | Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers. | Modifier lorsque l'organisation durable de `docs/` change ; `000-README.md` reste prioritaire lorsqu'un ordre numérique existe. |
|
||||
| `docs/rules/*.md` | Définir les règles normatives par portée. | Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu. |
|
||||
| `docs/IDEAS.md` | Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap. | Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée vers un plan, le roadmap, une règle ou une décision. |
|
||||
| futurs documents d'architecture | Décrire l'architecture courante décidée. | Ne pas utiliser comme journal de livraison ; reporter les décisions depuis les deltas/plans. |
|
||||
| futurs documents de référence | Définir vocabulaire, identifiants et références canoniques. | Mettre à jour quand la référence canonique évolue. |
|
||||
| futurs plans | Organiser une phase ou version complexe. | Ils peuvent évoluer pendant la phase ; leur statut normatif doit être explicite. |
|
||||
| futures validations | Conserver des résultats réellement exécutés. | Ne jamais enregistrer une validation supposée comme réussie. |
|
||||
| Fichier/famille | Responsabilité | Règle de modification |
|
||||
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `docs/000-README.md` | Indexer et expliquer la documentation tout en restant en tête des listings et arbres de fichiers. | Modifier lorsque l'organisation durable de `docs/` change ; `000-README.md` reste prioritaire lorsqu'un ordre numérique existe. |
|
||||
| `docs/rules/*.md` | Définir les règles normatives par portée. | Modifier uniquement pour une décision normative ; incrémenter la version du fichier à chaque enregistrement modifiant son contenu. |
|
||||
| `docs/rules/PROMPT_STRUCTURE.md` | Définir la structure, le cycle de vie et le dimensionnement des prompts/sessions KSP. | Modifier lorsque le contrat des prompts ou les règles de découpage de sessions/prereleases changent. |
|
||||
| `docs/architecture/000-README.md` | Indexer les documents décrivant l'architecture KSP décidée ou en cours de cadrage explicite. | Modifier lorsque la structure documentaire d'architecture change. |
|
||||
| `docs/architecture/*.md` | Décrire les objectifs, frontières, responsabilités et architecture courante ou explicitement proposée. | Ne pas utiliser comme journal de livraison ; distinguer clairement les décisions validées des hypothèses encore ouvertes. |
|
||||
| `docs/plans/000-README.md` | Indexer les plans de versions/phases. | Modifier lorsque l'organisation des plans change. |
|
||||
| `docs/plans/*.md` | Organiser une version ou phase complexe et, pour `pre.001`, détailler la prévision souple de ses prereleases. | Faire évoluer le plan lorsque la planification change ; prévoir des tranches intermédiaires bornées et redécouper toute tranche estimée trop lourde. |
|
||||
| `docs/IDEAS.md` | Conserver les idées, pistes, questions et alternatives à explorer qui ne sont pas encore des engagements du roadmap. | Ajouter une idée dès qu'elle mérite d'être conservée ; mettre à jour son statut lorsqu'elle est explorée, retenue, rejetée ou transférée. |
|
||||
| futurs documents de référence | Définir vocabulaire, identifiants et références canoniques. | Mettre à jour quand la référence canonique évolue. |
|
||||
| futures validations | Conserver des résultats réellement exécutés. | Ne jamais enregistrer une validation supposée comme réussie. |
|
||||
|
||||
## Répertoire `prompts/`
|
||||
|
||||
| Fichier/famille | Responsabilité | Règle de modification |
|
||||
|-----------------------------|----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `prompts/000-README.md` | Point d'entrée des prompts et de leur cycle de vie. | Modifier lorsque l'organisation pratique des prompts change ; les règles normatives restent sous `docs/rules/PROMPT_STRUCTURE.md`. |
|
||||
| `prompts/*START_PROMPT*.md` | Conserver un prompt de reprise versionné et réutilisable pour ouvrir une phase/version de travail. | Le créer tôt sous forme de brouillon lorsque la trajectoire devient assez claire, le mettre à jour au fil des décisions, puis le finaliser pendant la phase documentaire de clôture avant son utilisation. |
|
||||
|
||||
## Répertoire `deltas/`
|
||||
|
||||
@@ -54,4 +64,4 @@ Les règles `FILE-*` définissent la responsabilité et le mode de modification
|
||||
|
||||
- **FILE-GEN-001** — Un fichier généré n'est jamais modifié manuellement lorsque sa source de vérité est un générateur.
|
||||
- **FILE-GEN-002** — Le choix de versionner ou ignorer une famille générée est décidé explicitement lorsqu'elle apparaît.
|
||||
- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP en `0.0.2-pre.001-fix.001`.
|
||||
- **FILE-GEN-003** — Les futurs artefacts Tauri `bindings/` et `gen/` ne sont pas encore une convention KSP ; ils seront traités lorsqu'ils apparaîtront.
|
||||
|
||||
203
docs/rules/PROMPT_STRUCTURE.md
Normal file
203
docs/rules/PROMPT_STRUCTURE.md
Normal file
@@ -0,0 +1,203 @@
|
||||
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# 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.
|
||||
|
||||
Les prompts eux-mêmes sont conservés sous `prompts/`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
|
||||
|
||||
- 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 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
|
||||
|
||||
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`.
|
||||
|
||||
## 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 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, 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 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 session ou d'une version
|
||||
|
||||
Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
|
||||
|
||||
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é :
|
||||
|
||||
- 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
39
docs/rules/RULES_DEPENDENCIES.md
Normal file
39
docs/rules/RULES_DEPENDENCIES.md
Normal file
@@ -0,0 +1,39 @@
|
||||
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Règles des dépendances KSP
|
||||
|
||||
## Portée
|
||||
|
||||
Les règles `DEP-*` définissent quelles dépendances externes peuvent traverser les frontières KSP et quelles couches en sont propriétaires.
|
||||
|
||||
Elles complètent les règles Rust générales. Elles sont particulièrement strictes pour les crates liées à Solana et aux protocoles on-chain.
|
||||
|
||||
## Firewall des exécutables
|
||||
|
||||
- **DEP-EXEC-001** — Les applications, demos et workers KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les bibliothèques KSP propriétaires de ces contrats.
|
||||
- **DEP-EXEC-002** — Une application peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, par exemple UI, sérialisation, Base64 ou Base58, à condition que ces dépendances ne portent pas une opération métier/protocolaire appartenant à KSP.
|
||||
- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, la bibliothèque KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié ; l'exécutable ne contourne pas cette frontière en ajoutant lui-même la crate Solana.
|
||||
|
||||
## Propriété des dépendances Solana
|
||||
|
||||
- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir une bibliothèque KSP propriétaire précise. Elle n'est pas ajoutée dans plusieurs couches uniquement parce qu'elle est pratique à utiliser.
|
||||
- **DEP-SOL-002** — Les bibliothèques KSP de haut niveau qui n'ont pas besoin d'un contrat externe bas niveau ne dépendent pas directement de ce contrat.
|
||||
- **DEP-SOL-003** — Les primitives Solana/Anza suffisamment fondamentales et stables peuvent être utilisées dans les bibliothèques KSP de bas niveau qui en sont propriétaires.
|
||||
- **DEP-SOL-004** — La liste initialement acceptée de primitives fondamentales comprend `solana-pubkey`, `solana-keypair`, `solana-signer`, `solana-hash` et `solana-nonce`.
|
||||
- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API ; l'appartenance au dépôt Solana/Anza ne constitue pas à elle seule une autorisation automatique.
|
||||
- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP ; l'exécutable consommateur dépend alors de KSP, pas directement de la crate externe.
|
||||
|
||||
## Crates de protocoles et interfaces wire
|
||||
|
||||
- **DEP-PROTO-001** — Les crates d'interface/protocole externes telles que `mpl-token-metadata` ou `spl-elgamal-registry-interface` sont interdites par défaut comme dépendances runtime KSP.
|
||||
- **DEP-PROTO-002** — KSP préfère posséder ses représentations compatibles nécessaires : Program IDs, discriminants, layouts, enums, structures wire, règles de PDA, sérialisation/désérialisation et autres contrats effectivement requis.
|
||||
- **DEP-PROTO-003** — Une réimplémentation KSP vise le contrat nécessaire et ne consiste pas à copier mécaniquement l'architecture ou l'intégralité d'une crate externe.
|
||||
- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire, l'usage éventuel de dépendances externes uniquement en tests de conformité et les contraintes de licence/source de vérité restent à définir avant la première implémentation de protocole concernée.
|
||||
- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée, confinée à la bibliothèque propriétaire la plus basse possible et documentée avec sa version, sa raison et sa condition de suppression ou réévaluation.
|
||||
|
||||
## Versions
|
||||
|
||||
- **DEP-VER-001** — KSP privilégie les versions récentes compatibles des dépendances.
|
||||
- **DEP-VER-002** — Une version volontairement ancienne, bornée ou incompatible avec la politique générale est documentée avec la raison, le propriétaire et la condition permettant de lever la contrainte.
|
||||
- **DEP-VER-003** — Les lockfiles ne servent pas à figer silencieusement une version de dépendance ; les contraintes nécessaires appartiennent aux manifests et à la documentation.
|
||||
@@ -1,47 +1,73 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
## Portée
|
||||
## Nomenclature
|
||||
|
||||
Les règles `KSP-*` s'appliquent à l'architecture, la nomenclature et l'organisation propres à `khadhroony-solana-project`.
|
||||
- **KSP-NAME-001** — Une bibliothèque Rust d'implémentation réutilisable se nomme `ksp-<role>-lib`, sauf famille explicitement définie par une règle plus spécifique.
|
||||
- **KSP-NAME-002** — Une crate publique de contrats extensibles se nomme `ksp-<domain>-api`. Elle est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`.
|
||||
- **KSP-NAME-003** — Une crate `ksp-<domain>-api` expose principalement les types/traits/contrats nécessaires aux implémentations ; elle n'est pas une implémentation fonctionnelle directement destinée aux exécutables.
|
||||
- **KSP-NAME-004** — Une application se nomme `ksp-app-<role>-<interface>` lorsque l'interface doit être indiquée.
|
||||
- **KSP-NAME-005** — Un worker continu se nomme `ksp-worker-<role>`.
|
||||
- **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/`.
|
||||
|
||||
## Succession des projets précédents
|
||||
## Architecture et APIs
|
||||
|
||||
- **KSP-LINEAGE-001** — KSP succède aux projets Khadhroony Solana précédents mais ne les duplique pas mécaniquement.
|
||||
- **KSP-LINEAGE-002** — Une reprise de code, structure, dépendance ou documentation historique doit être justifiée par un besoin KSP actuel.
|
||||
- **KSP-LINEAGE-003** — Une architecture historique n'est jamais considérée comme normative uniquement parce qu'elle a fonctionné dans `khadhroony-bot3` ou un prédécesseur.
|
||||
- **KSP-API-001** — Un domaine extensible peut séparer `ksp-<domain>-api` et `ksp-<domain>-lib`.
|
||||
- **KSP-API-002** — Les premiers couples retenus sont `ksp-program-api` / `ksp-program-lib`, `ksp-materializer-api` / `ksp-materializer-lib` et `ksp-store-api` / `ksp-store-lib`.
|
||||
- **KSP-API-003** — KSP ne crée pas de `ksp-api-lib` monolithique regroupant les contrats de domaines indépendants.
|
||||
- **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`.
|
||||
|
||||
## Nomenclature des crates et exécutables
|
||||
## Programmes
|
||||
|
||||
- **KSP-NAME-001** — Une bibliothèque Rust réutilisable se nomme `ksp-<role>-lib`.
|
||||
- **KSP-NAME-002** — Une application se nomme `ksp-app-<role>-<interface>` lorsque l'interface doit être indiquée.
|
||||
- **KSP-NAME-003** — Un worker se nomme `ksp-worker-<role>`.
|
||||
- **KSP-NAME-004** — Une démonstration se termine par `-demo`.
|
||||
- **KSP-NAME-005** — Les interfaces d'application utilisent des tokens courts et stables, notamment `cli` pour une interface en ligne de commande et `desk` pour une application desktop.
|
||||
- **KSP-NAME-006** — Les crates Rust sont placées directement sous `crates/` ; aucun sous-répertoire de catégories n'est utilisé pour les regrouper.
|
||||
- **KSP-NAME-007** — Les applications sont placées sous `apps/` lorsqu'elles sont introduites.
|
||||
- **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.
|
||||
- **KSP-PROGRAM-003** — Le statut `deprecated` concerne la capacité d'exécution, pas la capacité de décodage.
|
||||
- **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.
|
||||
|
||||
## Environnements des démonstrations
|
||||
## Workers
|
||||
|
||||
- **KSP-DEMO-001** — Une demo limitée à un environnement encode explicitement cet environnement dans son nom avant le token d'interface et avant `-demo`.
|
||||
- **KSP-DEMO-002** — Les tokens d'environnement initiaux sont `mainnet`, `devnet`, `testnet`, `local-validator` et `synthetic`.
|
||||
- **KSP-DEMO-003** — Une demo sans token d'environnement est conçue pour permettre le choix de l'environnement parmi ceux qu'elle supporte ; l'absence de token ne signifie pas implicitement `mainnet`.
|
||||
- **KSP-DEMO-004** — Exemples de forme : `ksp-app-<role>-devnet-cli-demo`, `ksp-app-<role>-local-validator-desk-demo`, `ksp-app-<role>-synthetic-cli-demo` et `ksp-app-<role>-desk-demo` pour une demo à environnement sélectionnable.
|
||||
- **KSP-DEMO-005** — Une demo ne doit pas agréger plusieurs responsabilités indépendantes uniquement pour constituer une application de démonstration universelle.
|
||||
- **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.
|
||||
|
||||
## Frontières architecturales déjà décidées
|
||||
## Jobs
|
||||
|
||||
- **KSP-ARCH-001** — `ksp-core-lib` regroupe les fondations réellement transversales, y compris la responsabilité autrefois séparée des identifiants de programmes ; il ne doit pas devenir un conteneur générique de tout code partagé.
|
||||
- **KSP-ARCH-002** — Une bibliothèque commune dédiée aux interfaces/wire on-chain doit exister ; son nom de travail est `ksp-interface-lib` jusqu'à validation définitive.
|
||||
- **KSP-ARCH-003** — La matérialisation constitue une responsabilité distincte des interfaces/wire et du traitement des programmes.
|
||||
- **KSP-ARCH-004** — Le regroupement ou la séparation définitive du decoder, de la construction d'instructions et de l'exécution réseau reste une décision d'architecture ouverte ; aucune structure historique ne doit être recopiée avant cette décision.
|
||||
- **KSP-ARCH-005** — Une bibliothèque comme le wallet reste indépendante de son interface utilisateur ; les applications et demos qui la manipulent consomment la bibliothèque au lieu d'y être intégrées.
|
||||
- **KSP-ARCH-006** — La configuration doit disposer d'une bibliothèque propriétaire de ses contrats et pourra disposer d'une application dédiée à l'inspection et la modification des profils et valeurs autorisées.
|
||||
- **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.
|
||||
|
||||
## Dépendances et outils
|
||||
## Notifications de données
|
||||
|
||||
- **KSP-TOOL-001** — Aucun `rust-toolchain.toml` n'est utilisé dans KSP.
|
||||
- **KSP-TOOL-002** — Les lockfiles de dépendances sont ignorés et non livrés.
|
||||
- **KSP-TOOL-003** — Les répertoires et fichiers générés ne sont ajoutés au `.gitignore` qu'après apparition d'un besoin réel et décision explicite ; les futurs `bindings/` et `gen/` Tauri seront traités à ce moment.
|
||||
- **KSP-DATA-001** — Une notification de donnée décrit la donnée disponible et non le worker/job qui l'a produite.
|
||||
- **KSP-DATA-002** — Le même type de donnée utilise le même contrat de notification quelle que soit son origine : worker, job, import ou autre source.
|
||||
- **KSP-DATA-003** — `ksp-store-api` est le propriétaire candidat des références/notifications canoniques de données persistées lorsque ces contrats appartiennent naturellement à la frontière store.
|
||||
- **KSP-DATA-004** — Le contrat de notification est séparé de son mécanisme de transport concret.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
|
||||
24
prompts/000-README.md
Normal file
24
prompts/000-README.md
Normal file
@@ -0,0 +1,24 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
Ce répertoire contient les prompts de reprise structurés permettant d'ouvrir une nouvelle version ou une nouvelle session sans perdre les décisions, règles, contraintes et objectifs déjà établis.
|
||||
|
||||
Le préfixe `000-` maintient ce point d'entrée en première position dans les listings.
|
||||
|
||||
## Rôle
|
||||
|
||||
`prompts/` contient uniquement les prompts eux-mêmes et leur index pratique.
|
||||
|
||||
La structure normative, le cycle de vie et les règles de dimensionnement des prompts sont définis dans [`../docs/rules/PROMPT_STRUCTURE.md`](../docs/rules/PROMPT_STRUCTURE.md).
|
||||
|
||||
## Cycle pratique
|
||||
|
||||
Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire, puis maintenu comme brouillon vivant jusqu'à la clôture de la phase courante.
|
||||
|
||||
Le prompt `0.1.x` est commencé pendant `0.0.3`, mis à jour au fil des décisions, puis finalisé avant l'ouverture du développement fonctionnel.
|
||||
|
||||
## Documents
|
||||
|
||||
- [`001-V0_1_X_START_PROMPT.md`](001-V0_1_X_START_PROMPT.md) — brouillon vivant du prompt ouvrant le développement fonctionnel `0.1.x`.
|
||||
70
prompts/001-V0_1_X_START_PROMPT.md
Normal file
70
prompts/001-V0_1_X_START_PROMPT.md
Normal file
@@ -0,0 +1,70 @@
|
||||
<!-- file: prompts/001-V0_1_X_START_PROMPT.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# 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.**
|
||||
|
||||
## Mission provisoire
|
||||
|
||||
Commencer le développement fonctionnel KSP sur les fondations N1 nécessaires au reste du projet, principalement :
|
||||
|
||||
- `ksp-core-lib` ;
|
||||
- `ksp-logging-lib` ;
|
||||
- `ksp-config-lib` ;
|
||||
- `ksp-app-config-desk`.
|
||||
|
||||
## Décisions déjà acquises
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
## Objectifs provisoires
|
||||
|
||||
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.
|
||||
|
||||
## Hors périmètre provisoire
|
||||
|
||||
- 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.
|
||||
|
||||
## Validations attendues
|
||||
|
||||
Au minimum, lorsque du code Rust est introduit :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Aucune validation non exécutée ne doit être déclarée réussie.
|
||||
Reference in New Issue
Block a user