Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 12:51:24 +02:00
parent 6964b71955
commit 2dada316c1
10 changed files with 840 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/IDEAS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/IDEAS.md -->
<!-- version: 12 -->
<!-- version: 13 -->
# Idées à explorer
@@ -303,3 +303,13 @@ Aucune crate `ksp-orchestrator-lib` n'est retenue actuellement.
Les workers sont des services autonomes. Une app manager devra donc disposer d'un transport de control.
Ne pas créer de `ksp-ipc-api` générique avant de connaître les contraintes réelles du premier manager : plateforme, framing, discovery, authentication locale et lifecycle.
## Séquencement des releases futures
### Numérotation fine après `0.1.x`
**Status :** À décider à l'approche de chaque série
`0.1.1` et `0.1.2` sont fixées ; `0.1.3` / `0.1.4` constituent la séquence par défaut sous réserve d'une éventuelle scission de Config.
Pour `0.2.x+`, ne pas attribuer prématurément un numéro précis à chaque composant. L'ordre candidat est documenté dans `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` et sera converti en releases concrètes lorsque les dépendances et premiers cas d'usage de la série seront connus.

11
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Inventaire initial des composants KSP
@@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`.
Il répond principalement à la question : **quel composant possède quelle responsabilité ?**
Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `pre.007` l'exploitation workers/jobs/pipelines, puis `pre.008` Apps/Services/Scenarios/Control dans [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md). Les détails de types Rust restent révisables avec les premières implémentations.
Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `pre.007` l'exploitation workers/jobs/pipelines, `pre.008` Apps/Services/Scenarios/Control, puis `pre.009` le séquencement des premières releases fonctionnelles. La séquence détaillée est dans `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`. Les détails de types Rust restent révisables avec les premières implémentations.
## Statuts
@@ -23,9 +23,10 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|----------------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.1` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.3` par défaut | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.2` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
| Config desktop | `ksp-app-config-desk` | app | N4 | Retenu | `0.1.4` par défaut | app spécialisée Tauri validant chargement, profils, édition, sauvegarde, validation et diagnostics Config |
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |

38
docs/plans/001-V0_0_3_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
<!-- version: 12 -->
<!-- version: 13 -->
# Plan KSP 0.0.3
@@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su
- `pre.002` — inventaire initial des composants ;
- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition.
Les tranches `pre.004` (Wire/Program), `pre.005` (Execution/Policy), `pre.006` (Data/Materialization/Store), `pre.007` (Acquisition/Workers/Jobs) et `pre.008` (Apps/Services/Scenarios/Control) sont maintenant livrées séparément afin de conserver des prereleases de planification bornées.
Les tranches `pre.004` (Wire/Program), `pre.005` (Execution/Policy), `pre.006` (Data/Materialization/Store), `pre.007` (Acquisition/Workers/Jobs), `pre.008` (Apps/Services/Scenarios/Control) et `pre.009` (Functional Release Sequence) sont maintenant livrées séparément afin de conserver des prereleases de planification bornées.
## Décisions structurantes actuelles
@@ -140,18 +140,30 @@ Livré :
### `pre.009` — Plan des premières releases fonctionnelles
- transformer les séries `0.1.x+` en premières releases concrètes ;
- dimensionner chaque release concrète ;
- choisir la première release `0.1.N` ;
- vérifier l'ordre réel core/logging/config/interface/program/store/transport/workers sans introduire de dépendances circulaires ;
- positionner explicitement les apps spécialisées/demos avant toute future app globale ;
- transformer le brouillon de prompt en prompt quasi-final de cette première release concrète.
Livré :
- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` ;
- `0.1.1` sélectionnée comme première release fonctionnelle ;
- `0.1.1` = `ksp-core-lib` ;
- `0.1.2` = `ksp-logging-lib` ;
- `0.1.3` = `ksp-config-lib` par défaut ;
- `0.1.4` = `ksp-app-config-desk` par défaut ;
- règle de scission de Config si son `pre.001` démontre une charge excessive ;
- ordre candidat, volontairement non numéroté finement, pour `0.2.x` et `0.3.x` ;
- lifecycle standard des releases fonctionnelles ;
- chaque delta commité à partir de `0.1.x` ;
- seul le commit stable reçoit le tag `vX.Y.Z` ;
- brouillon générique `V0_1_X` remplacé par le prompt quasi-final `V0_1_1`.
### `pre.010` — Clôture fondatrice
- validations finales de cohérence ;
- documentation/nettoyage/archivage ;
- synchronisation du changelog si applicable ;
- finalisation du prompt de la première release fonctionnelle.
- relire les règles, architecture, roadmap, plans et IDEAS pour détecter les contradictions restantes ;
- vérifier que la documentation racine/indexée disponible est cohérente ;
- vérifier les versions de fichiers et le versionnement Cargo ;
- effectuer les validations workspace applicables à la fondation ;
- mettre à jour/nettoyer/archiver ce qui doit l'être ;
- synchroniser le changelog si le fichier existe dans la base de travail ;
- finaliser `prompts/001-V0_1_1_START_PROMPT.md` ;
- produire le delta/release stable `0.0.3` et préparer le démarrage de `0.1.1`.
Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une frontière supplémentaire doit être étudiée.
`pre.010` n'est pas une nouvelle tranche de brainstorming architectural. Une évolution de fond n'y est ouverte qu'en cas d'incohérence critique détectée pendant l'audit final.

342
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md Normal file
View File

@@ -0,0 +1,342 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 1 -->
# Séquence des releases fonctionnelles KSP
## Objet
Ce document formalise la sortie principale de `0.0.3-pre.009`.
Il transforme les séries fonctionnelles du roadmap en une première séquence de développement concrète sans prétendre connaître trop tôt tous les numéros des séries futures.
Principes :
- une série `X.Y.x` est une famille fonctionnelle ;
- une release concrète `X.Y.Z` est une unité de travail/session dimensionnée ;
- chaque release concrète possède ses propres prereleases ;
- une release trop grosse est scindée au lieu d'être forcée dans une session ;
- les numéros futurs sont confirmés lorsque leur série approche et que les dépendances réelles sont connues.
# Première série fonctionnelle : `0.1.x`
La série `0.1.x` construit les fondations N1 dans l'ordre de dépendances réel.
Séquence par défaut :
```text
0.1.1 ksp-core-lib
|
v
0.1.2 ksp-logging-lib
|
v
0.1.3 ksp-config-lib
|
v
0.1.4 ksp-app-config-desk
```
`0.1.1` et `0.1.2` sont fixées.
`0.1.3` et `0.1.4` sont la séquence par défaut. Si le `pre.001` de Config démontre qu'une seule release ne permet pas un développement propre, Config est scindé et les numéros suivants sont décalés.
## `0.1.1` — Core foundation
### Mission
Stabiliser `ksp-core-lib` comme fondation N1 minimale et durable.
Le Core possède uniquement les contrats réellement transversaux nécessaires aux couches supérieures.
### Périmètre initial
À auditer précisément dans `0.1.1-pre.001`, avec comme candidats acquis :
- type public commun `ksp_core_lib::Error` ;
- alias public commun `Result<T>` ou forme équivalente validée ;
- architecture d'erreur permettant aux domaines supérieurs d'ajouter du contexte sans faire connaître tous les futurs domaines à Core ;
- Program IDs fondamentaux appartenant à KSP Core ;
- primitives/identités réellement communes et déjà justifiées ;
- conventions de version/provenance N1 uniquement si un besoin concret existe ;
- exports crate-root et documentation publique ;
- tests unitaires/integration appropriés ;
- respect complet des règles Rust/workspace.
### Dépendances
Core ne dépend pas de `ksp-logging-lib`, Config, Wallet, Store, Transport, Program ou Materializer.
Une primitive Solana/Anza officiellement stable peut être ajoutée seulement lorsqu'un item Core concret en a besoin.
`solana-pubkey` est un candidat naturel pour les Program IDs ; les autres primitives autorisées ne sont pas ajoutées par anticipation.
### Hors scope
- logging ;
- configuration ;
- Tauri ;
- wallet/signing ;
- codecs wire ;
- decoders/Program registry ;
- transaction execution ;
- transport ;
- Store ;
- Materializer ;
- workers/jobs ;
- scenarios.
### Lifecycle de la release
Le nombre de prereleases n'est pas figé avant `pre.001`.
Trajectoire candidate :
```text
pre.001 brainstorming + audit + plan détaillé
pre.002 Error/Result + fondation API
pre.003 primitives/Program IDs réellement retenus
pre.004 compléments/tests/audits
pre.005 validation finale/docs/cleanup/prompt 0.1.2
```
Cette séquence est indicative. `pre.001` peut la modifier.
## `0.1.2` — Logging foundation
### Dépendances
```text
ksp-logging-lib
-> ksp-core-lib
-> tracing
-> tracing-appender
-> tracing-subscriber
```
### Mission
Faire de `ksp-logging-lib` la façade KSP unique de logging/tracing pour les composants runtime.
### Périmètre candidat
- initialisation ;
- settings runtime propres au logging ;
- `error`, `warn`, `info`, `debug`, `trace` ;
- target/domain/component/champs structurés selon API validée ;
- fonctions, macros ou combinaison permettant de préserver correctement les callsites ;
- console/fichiers ;
- filtering ;
- appender/rotation selon besoin concret ;
- tests ;
- protection contre logging de secrets.
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`.
Config pourra plus tard convertir ses documents résolus en settings de Logging.
## `0.1.3` — Configuration foundation
### Dépendances candidates
```text
ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
```
### Mission
Introduire la configuration générale KSP.
Périmètre candidat à revalider dans son `pre.001` :
- documents spécialisés ;
- profils ;
- `default_profile` autonome ;
- valeurs globales hors profils lorsqu'elles ne varient pas ;
- résolution ;
- validation ;
- modification/sauvegarde ;
- variables d'environnement `KS_*` / `KB_*` ;
- secret/public/debug exposure policy ;
- `logging.config.json` séparé ;
- schemas sous `config/schemas/` ;
- examples sous `config/`.
### Règle de scission
Si le plan détaillé démontre que validation/schemas, résolution/profiles et mutation/persistence dépassent une release raisonnable, Config est réparti sur deux releases de `0.1.x`.
Aucun sous-périmètre n'est compressé artificiellement pour préserver le numéro `0.1.4` de l'application desktop.
## `0.1.4` — Config desktop par défaut
Sous réserve d'absence de scission de Config.
Mission :
```text
ksp-app-config-desk
-> ksp-config-lib
-> ksp-logging-lib
```
L'application doit valider réellement :
- lecture de documents ;
- profils/default profile ;
- résolution ;
- validation ;
- édition/sauvegarde ;
- env overrides exposables ;
- diagnostics/errors ;
- intégration logging ;
- conventions Tauri/DTO/TS-RS.
La logique Config reste dans `ksp-config-lib`.
# Règle Git à partir de `0.1.x`
À partir de la première release fonctionnelle, **chaque delta est commité**.
Exemples :
```text
0.1.1-pre.001
0.1.1-pre.002
0.1.1-pre.002-fix.001
...
0.1.1
```
Une étape intermédiaire erronée n'est pas supprimée de l'historique pour reconstruire artificiellement un développement parfait. Elle est corrigée par un delta/commit suivant.
Seul le commit de release stable reçoit le tag :
```text
v0.1.1
```
# Lifecycle standard d'une release fonctionnelle
## Première prerelease
Par défaut :
- relire la base validée ;
- brainstorming ;
- audit des besoins ;
- vérification des dépendances externes actuelles depuis les sources officielles lorsque concernées ;
- plan détaillé ;
- inventaire des fichiers/API touchés ;
- dimensionnement des prereleases ;
- décision explicite sur les hors-scope.
La première prerelease ne doit pas se transformer automatiquement en une grosse phase d'implémentation.
## Prereleases intermédiaires
Chaque prerelease porte un objectif borné et cohérent.
Une tranche de travail de planification/développement manifestement trop grosse est scindée.
## Dernière prerelease
Par défaut :
- validations complètes ;
- tests de conformité/audits ;
- documentation finale ;
- nettoyage/archivage ;
- changelog ;
- prompt de la release suivante ;
- vérification de cohérence des versions.
# Série `0.2.x` — ordre candidat uniquement
`0.2.x` ouvre les capacités Solana N2.
L'ordre exact des numéros n'est **pas figé** en `0.0.3`.
Ordre candidat à réévaluer à l'approche de la série :
```text
wallet foundation
-> wallet specialized app
on-chain transport foundation
-> specialized transport/demo validation
interface/wire foundation
-> first concrete Program surface
program-api / program-lib
-> first real decoder + ProgramExecutionPreparer + registry validation
execution-policy-api / execution-lib
-> first real execution cycle
scenario/demo validating the complete path
```
Wallet, Transport et Interface sont en grande partie indépendants ; leur ordre précis peut donc être réordonné selon le premier cas fonctionnel choisi.
`ksp-offchain-transport-lib` reste need-driven.
# Série `0.3.x` — ordre candidat uniquement
Direction :
```text
store-api + PostgreSQL store foundation
|
v
D1 raw persistence
|
v
specialized Store app
|
v
worker-api / job-api
|
v
raw-ingestion pipeline
|
+--> raw-retriever service
|
+--> backfill job
```
Les contrats Materializer et les frontières D2/D3/D4 sont introduits lorsque les sorties Program/Core réelles nécessaires existent.
Store/D1/acquisition peuvent donc être validés avant une matérialisation complète.
# Séries suivantes
Les directions restent celles du roadmap :
```text
0.4.x Core/SPL/metadata + scenarios/demos
0.5.x Anchor + protocoles trading
0.6.x processing autonome D1 -> D4
0.7.x Trading Intelligence
0.8.x+ trading opérationnel + explorers + expansion produits
```
Ces séries sont des objectifs fonctionnels, pas un calendrier contractuel.
# Sélection de la première release
La première release fonctionnelle est :
```text
0.1.1 — Core foundation
```
Le prompt de démarrage associé est :
```text
prompts/001-V0_1_1_START_PROMPT.md
```
`0.0.3-pre.010` doit seulement effectuer la clôture fondatrice, confirmer ce prompt et la base stable `0.0.3`, sans rouvrir le découpage architectural sauf incohérence critique.

13
docs/rules/RULES_KSP.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_KSP.md -->
<!-- version: 12 -->
<!-- version: 13 -->
# Règles spécifiques à KSP
@@ -188,3 +188,14 @@
- **KSP-CONTROL-003** — La sémantique de `ksp-worker-api` doit rester utilisable avec un handle local ou un futur proxy IPC.
- **KSP-CONTROL-004** — Aucun `ksp-ipc-api` générique n'est prévu actuellement ; le premier manager/service concret doit d'abord démontrer le transport nécessaire.
- **KSP-CONTROL-005** — `ksp-orchestrator-lib` est seulement un concept futur et n'est pas une crate retenue dans le plan actuel.
## Releases fonctionnelles
- **KSP-REL-001** — Une série `X.Y.x` est une famille fonctionnelle ; chaque release concrète `X.Y.Z` est dimensionnée séparément.
- **KSP-REL-002** — À partir de `0.1.x`, chaque delta/prerelease/fix est commité afin de préserver l'historique réel du développement.
- **KSP-REL-003** — Une erreur intermédiaire est corrigée par un delta/commit suivant ; l'historique n'est pas réécrit pour supprimer artificiellement l'étape erronée.
- **KSP-REL-004** — Seul le commit d'une release stable reçoit le tag `vX.Y.Z`.
- **KSP-REL-005** — Le premier `pre.001` d'une release fonctionnelle commence par brainstorming, audit, vérification des dépendances actuelles lorsque concernées, plan détaillé et dimensionnement.
- **KSP-REL-006** — Une release ou prerelease trop grosse est scindée plutôt que compressée pour respecter un numéro prévu.
- **KSP-REL-007** — La dernière prerelease d'une release fonctionnelle réalise par défaut validations finales, documentation, nettoyage/archivage, changelog et prompt de la release suivante.
- **KSP-REL-008** — La première release fonctionnelle sélectionnée est `0.1.1`, dédiée à la stabilisation de `ksp-core-lib`.