From 2dada316c1184efac4e428fbbeb5b310fe991336 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 14 Aug 2026 12:51:24 +0200 Subject: [PATCH] v0.0.3-pre.009 --- Cargo.toml | 4 +- ROADMAP.md | 21 +- deltas/0.0.3/pre.009.md | 166 +++++++++ docs/IDEAS.md | 12 +- docs/architecture/004-COMPONENT_INVENTORY.md | 11 +- docs/plans/001-V0_0_3_PLAN.md | 38 +- docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md | 342 ++++++++++++++++++ docs/rules/RULES_KSP.md | 13 +- prompts/001-V0_1_1_START_PROMPT.md | 264 ++++++++++++++ prompts/001-V0_1_X_START_PROMPT.md | 79 ---- 10 files changed, 840 insertions(+), 110 deletions(-) create mode 100644 deltas/0.0.3/pre.009.md create mode 100644 docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md create mode 100644 prompts/001-V0_1_1_START_PROMPT.md delete mode 100644 prompts/001-V0_1_X_START_PROMPT.md diff --git a/Cargo.toml b/Cargo.toml index 1fb41bb..ded9cf8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 14 +# version: 15 [workspace] resolver = "3" members = ["crates/ksp-core-lib"] [workspace.package] -version = "0.0.3-pre.8" +version = "0.0.3-pre.9" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 24e0b1b..e6145eb 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -20,22 +20,25 @@ Les décisions architecturales négatives ou de prudence n'apparaissent pas comm - [X] `0.0.1` — Initialiser le dépôt. - [X] `0.0.2` — Installer le squelette minimal et les règles initiales. - [/] `0.0.3` — Définir domaines, composants, dépendances, contrats, workers/jobs/scénarios/apps et plan global. -- [/] Construire progressivement le prompt de démarrage `0.1.x`. +- [X] Sélectionner `0.1.1` comme première release fonctionnelle et produire son prompt quasi-final. - [ ] Clôturer la fondation avec documentation, validations et prompt final. ## 0.1.x — Fondations N1 ### Objectifs -Regrouper les releases consacrées aux fondations N1. La série n'est pas destinée à tenir dans une seule session : chaque release concrète (`0.1.1`, `0.1.2`, etc.) sera dimensionnée séparément. +Regrouper les releases consacrées aux fondations N1. Chaque release concrète est une unité de développement/session distincte et commence par son propre `pre.001` de brainstorming/audit/planification. -### Étapes +### Releases concrètes -- [ ] Stabiliser `ksp-core-lib`, dont `Error` et Program IDs. -- [ ] Introduire `ksp-logging-lib`. -- [ ] Introduire `ksp-config-lib`. -- [ ] Introduire `ksp-app-config-desk`. -- [ ] Définir au besoin les premiers contrats publics requis par les couches suivantes sans anticiper leur implémentation complète. +- [ ] `0.1.1` — Stabiliser `ksp-core-lib` : `Error`/`Result`, Program IDs fondamentaux et primitives réellement N1. +- [ ] `0.1.2` — Introduire `ksp-logging-lib` comme façade KSP de `tracing`, `tracing-appender` et `tracing-subscriber`. +- [ ] `0.1.3` — Introduire `ksp-config-lib` : documents, profils, résolution, validation et modifications autorisées. +- [ ] `0.1.4` — Introduire `ksp-app-config-desk` pour valider réellement Config et la frontière Tauri. + +`0.1.1` et `0.1.2` sont fixées. `0.1.3` / `0.1.4` constituent la séquence par défaut : si le `pre.001` de Config démontre que son périmètre doit être scindé, une release supplémentaire est insérée et les numéros suivants sont décalés plutôt que de surcharger une release. + +Les contrats publics supplémentaires ne sont introduits que lorsqu'une release concrète en démontre le besoin. ## 0.2.x — Accès Solana et fondation programmes diff --git a/deltas/0.0.3/pre.009.md b/deltas/0.0.3/pre.009.md new file mode 100644 index 0000000..27d74a0 --- /dev/null +++ b/deltas/0.0.3/pre.009.md @@ -0,0 +1,166 @@ + + + +# Delta 0.0.3-pre.009 + +## Base requise + +`v0.0.3-pre.008`. + +## Objectif + +Transformer le roadmap fonctionnel en une première séquence de releases concrètes, sélectionner `0.1.1` et produire son prompt quasi-final sans sur-numéroter prématurément les séries futures. + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.0.3-pre.8 +``` + +à : + +```text +0.0.3-pre.9 +``` + +Le header de `Cargo.toml` passe de version 14 à 15. + +## Fichiers ajoutés + +- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` +- `prompts/001-V0_1_1_START_PROMPT.md` +- `deltas/0.0.3/pre.009.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `ROADMAP.md` +- `docs/architecture/004-COMPONENT_INVENTORY.md` +- `docs/plans/001-V0_0_3_PLAN.md` +- `docs/rules/RULES_KSP.md` +- `docs/IDEAS.md` + +## Fichiers supprimés + +- `prompts/001-V0_1_X_START_PROMPT.md` + +La suppression est explicite dans ce delta : le nouveau prompt `V0_1_1` remplace le brouillon générique. + +## Décisions principales + +### Première release + +La première release fonctionnelle est fixée : + +```text +0.1.1 — ksp-core-lib +``` + +Mission : stabiliser le contrat Core N1 sans ouvrir les couches supérieures. + +### `0.1.x` + +Séquence par défaut : + +```text +0.1.1 Core +0.1.2 Logging +0.1.3 Config +0.1.4 Config desktop +``` + +`0.1.1` et `0.1.2` sont fixées. + +Si `0.1.3-pre.001` démontre que Config doit être scindé, une release est insérée et l'app Config est décalée. + +### `0.1.1` + +Périmètre candidat : + +- `ksp_core_lib::Error` ; +- `Result` ou équivalent ; +- Program IDs fondamentaux ; +- primitives N1 réellement nécessaires ; +- API/reexports/tests/docs. + +`ksp-core-lib` ne dépend pas de Logging/Config ni des couches Solana supérieures. + +### `0.1.2` + +`ksp-logging-lib` dépend de Core et possède directement : + +- `tracing` ; +- `tracing-appender` ; +- `tracing-subscriber`. + +Il expose sa façade/settings sans dépendre de Config. + +### `0.1.3` / `0.1.4` + +Config puis son app desktop spécialisée constituent la séquence par défaut. + +L'app sert de validation réelle de Config et de la frontière Tauri. + +### Séries futures + +`0.2.x+` reste ordonné fonctionnellement mais n'est pas numéroté finement. + +Cette politique évite de figer des numéros qui seront probablement modifiés par les dépendances réelles découvertes pendant les premières releases. + +### Git + +À partir de `0.1.x`, chaque delta est commité. + +Une étape erronée reste dans l'historique et est corrigée par un delta suivant. + +Seul le commit stable reçoit le tag `vX.Y.Z`. + +### Lifecycle + +Le premier `pre.001` d'une release fonctionnelle est une phase de brainstorming/audit/plan détaillé/dimensionnement. + +La dernière prerelease réalise validations finales, documentation, nettoyage/archivage, changelog et prompt de la release suivante. + +### Prompt + +Le brouillon : + +```text +prompts/001-V0_1_X_START_PROMPT.md +``` + +est remplacé par : + +```text +prompts/001-V0_1_1_START_PROMPT.md +``` + +Le nouveau prompt est quasi-final et sera seulement confirmé/corrigé en clôture `pre.010`. + +## Plan restant + +### `pre.010` + +- audit global final ; +- cohérence docs/règles/architecture/roadmap/plans ; +- validations workspace applicables ; +- nettoyage/archivage ; +- changelog si disponible dans la base ; +- finalisation du prompt `0.1.1` ; +- préparation de la release stable `0.0.3`. + +`pre.010` ne doit pas rouvrir une tranche de brainstorming architectural sauf incohérence critique. + +## Validations + +- headers `file:` / `version:` vérifiés ; +- `Cargo.toml` parsé et version `0.0.3-pre.9` vérifiée ; +- `ROADMAP.md` contient les releases concrètes `0.1.1`–`0.1.4` par défaut ; +- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` ajouté ; +- prompt `V0_1_1` ajouté et ancien prompt `V0_1_X` déclaré supprimé ; +- première release `0.1.1` cohérente avec la dépendance `ksp-logging-lib -> ksp-core-lib` ; +- numérotation fine `0.2.x+` laissée volontairement ouverte ; +- plan `pre.010` limité à la clôture ; +- aucune commande Cargo build/test exécutée : ce delta reste documentaire. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index 89ad980..64ba772 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 2e8e72e..3c177c3 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`. Il répond principalement à la question : **quel composant possède quelle responsabilité ?** -Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md), `pre.005` Execution/Policy, `pre.006` les niveaux durables/Materialization/Store, `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é | diff --git a/docs/plans/001-V0_0_3_PLAN.md b/docs/plans/001-V0_0_3_PLAN.md index c454e21..18c1292 100644 --- a/docs/plans/001-V0_0_3_PLAN.md +++ b/docs/plans/001-V0_0_3_PLAN.md @@ -1,5 +1,5 @@ - + # Plan KSP 0.0.3 @@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su - `pre.002` — inventaire initial des composants ; - `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition. -Les tranches `pre.004` (Wire/Program), `pre.005` (Execution/Policy), `pre.006` (Data/Materialization/Store), `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. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md new file mode 100644 index 0000000..800dfc3 --- /dev/null +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -0,0 +1,342 @@ + + + +# 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` 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. diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 26e751b..6a0dbef 100644 --- a/docs/rules/RULES_KSP.md +++ b/docs/rules/RULES_KSP.md @@ -1,5 +1,5 @@ - + # 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`. diff --git a/prompts/001-V0_1_1_START_PROMPT.md b/prompts/001-V0_1_1_START_PROMPT.md new file mode 100644 index 0000000..3a0701b --- /dev/null +++ b/prompts/001-V0_1_1_START_PROMPT.md @@ -0,0 +1,264 @@ + + + +# Prompt de démarrage KSP 0.1.1 + +**Status : Quasi-final — à confirmer pendant la clôture `0.0.3-pre.010`.** + +## 1. Identité + +Release fonctionnelle : + +```text +0.1.1 — Core foundation +``` + +Première release fonctionnelle de Khadhroony Solana Project. + +## 2. Mission + +Implémenter et stabiliser `ksp-core-lib` comme fondation N1 minimale, générale et durable. + +Cette release doit fournir uniquement les contrats réellement transversaux requis par les couches suivantes, en particulier le contrat commun d'erreur et les Program IDs fondamentaux. + +Elle ne doit pas ouvrir prématurément Logging, Config, Wallet, Transport, Program decoding/execution, Store ou les autres couches supérieures. + +## 3. Base requise + +Base attendue : + +```text +0.0.3 stable +``` + +Avant tout travail : + +- vérifier que la fondation `0.0.3` est validée ; +- vérifier le working tree Git ; +- relire le delta final `0.0.3` et le prompt présent ; +- vérifier que la version workspace est passée à la version/prerelease `0.1.1` appropriée au premier delta. + +`0.0.3-pre.010` doit confirmer les références exactes de clôture. + +## 4. Sources de vérité + +Relire en priorité les fichiers réellement présents dans la base, notamment : + +- `ROADMAP.md` ; +- `docs/plans/001-V0_0_3_PLAN.md` ; +- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` ; +- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md` ; +- `docs/architecture/003-COMPONENT_CONTRACTS.md` ; +- `docs/architecture/004-COMPONENT_INVENTORY.md` ; +- `docs/architecture/005-DEPENDENCY_GRAPH.md` ; +- `docs/rules/RULES_DEPENDENCIES.md` ; +- `docs/rules/RULES_KSP.md` ; +- `docs/IDEAS.md`. + +Relire également les règles/index racine supplémentaires présents dans le dépôt au moment de la session. + +Ne jamais inventer un document absent de la base de travail. + +## 5. Première prerelease obligatoire : `0.1.1-pre.001` + +`pre.001` est d'abord une prerelease de **brainstorming, audit et planification**. + +Elle doit : + +1. inventorier le contenu réel actuel de `ksp-core-lib` ; +2. identifier les contrats N1 réellement nécessaires à `0.1.1` ; +3. concevoir le contrat `Error` / `Result` commun sans faire connaître à Core tous les futurs domaines ; +4. inventorier les Program IDs fondamentaux qui appartiennent réellement à Core ; +5. identifier les primitives communes justifiées maintenant ; +6. vérifier depuis les sources officielles actuelles les crates Solana/Anza nécessaires avant toute sélection de version ; +7. éviter d'ajouter une dépendance simplement parce qu'elle est autorisée architecturalement ; +8. proposer l'API publique et les crate-root reexports ; +9. proposer la stratégie de tests ; +10. dimensionner les prereleases suivantes ; +11. confirmer explicitement les hors-scope. + +Ne pas transformer `pre.001` en une grosse phase de développement avant que ce plan soit validé. + +## 6. Périmètre fonctionnel candidat + +### `Error` / `Result` + +La direction acquise est un type public commun : + +```text +ksp_core_lib::Error +``` + +et un alias `Result` ou forme équivalente à confirmer. + +Le design doit : + +- être utilisable par les crates KSP supérieures ; +- permettre catégorie/code/contexte ou autre extension propre ; +- éviter que Core possède une enum fermée de toutes les erreurs futures du projet ; +- conserver des conversions/causes utiles sans créer de dépendances vers les domaines supérieurs ; +- respecter les règles `no unwrap`, `no expect`, `no panic` production et `no ?`. + +Le modèle exact doit être décidé pendant `pre.001`, pas supposé par ce prompt. + +### Program IDs fondamentaux + +Les Program IDs fondamentaux sont une responsabilité de `ksp-core-lib`. + +Le `pre.001` doit définir lesquels sont réellement nécessaires dans la première surface Core et comment ils sont exposés. + +La représentation doit privilégier les primitives officielles Solana/Anza actuelles lorsque leur stabilité et leur API sont appropriées. + +### Primitives communes + +N'ajouter que les primitives dont un usage concret existe dans Core. + +Ne pas faire de `ksp-core-lib` un fourre-tout pour : + +- wallet/signing ; +- codecs wire ; +- RPC ; +- persistence ; +- Program decoding ; +- materialization ; +- configuration ; +- logging. + +## 7. Dépendances + +Core reste en bas du graphe KSP. + +Interdictions pour `0.1.1` : + +```text +ksp-core-lib -X-> ksp-logging-lib +ksp-core-lib -X-> ksp-config-lib +ksp-core-lib -X-> ksp-wallet-lib +ksp-core-lib -X-> ksp-interface-lib +ksp-core-lib -X-> ksp-program-api +ksp-core-lib -X-> ksp-store-api +ksp-core-lib -X-> transport/workers/jobs/apps +``` + +Les primitives officielles Solana/Anza autorisées architecturalement ne sont ajoutées que si un item Core réel les nécessite. + +`solana-pubkey` est un candidat naturel si les Program IDs sont représentés avec `Pubkey`, mais sa version et son usage doivent être vérifiés dans `pre.001`. + +## 8. Hors scope strict de `0.1.1` + +- `ksp-logging-lib` ; +- `ksp-config-lib` ; +- toute application Tauri ; +- wallet/keypair/signer management ; +- wire codecs Borsh/Wincode ; +- `ksp-interface-lib` ; +- Program decoder/registry/`ProgramExecutionPreparer` ; +- execution policy/orchestration ; +- RPC/WS/Helius/Yellowstone ; +- Store/PostgreSQL ; +- materializers ; +- workers/jobs/pipelines ; +- scenarios ; +- trading/ML. + +Un contrat minimal appartenant réellement à Core peut être ajouté si le `pre.001` démontre qu'il est nécessaire, mais il ne doit pas servir de prétexte pour ouvrir un domaine supérieur. + +## 9. Règles Rust importantes + +Préserver notamment : + +- Rust 2024 ; +- async-first pour les I/O futures, sans inventer de async lorsqu'aucune I/O n'existe ; +- `unsafe` interdit ; +- `unwrap` / `expect` interdits ; +- `panic` interdit en production ; +- opérateur `?` interdit ; +- returns explicites selon les règles workspace ; +- `unreachable_pub = deny` ; +- `missing_docs = warn` ; +- imports de traits seulement lorsque nécessaire, sinon chemins pleinement qualifiés selon les règles du projet ; +- API publique via réexports crate-root explicites ; +- pas de `mod.rs` ; +- pas de `pub(super)` / `pub(in ...)` ; +- documentation code/Rustdoc en anglais ; +- règles de format/EOF du projet. + +Les tests unitaires doivent suivre la convention de fichiers externes au `src` lorsqu'elle est applicable dans la base réelle. + +## 10. Dépendances externes + +Avant d'ajouter ou modifier une crate Solana/Anza : + +- consulter les sources officielles actuelles ; +- privilégier les générations récentes compatibles ; +- vérifier le graphe de dépendances pertinent ; +- ne pas conserver une génération ancienne pour compatibilité avec une crate protocolaire remplaçable. + +`0.1.1` n'introduit aucun codec wire par anticipation. + +## 11. Git et deltas + +À partir de `0.1.x`, **chaque delta est commité**. + +Cela inclut : + +- `pre.NNN` ; +- `pre.NNN-fix.NNN` ; +- autres deltas intermédiaires. + +Une étape erronée est corrigée par un commit/delta suivant ; ne pas réécrire l'historique pour la faire disparaître. + +Seul le commit stable final reçoit le tag : + +```text +v0.1.1 +``` + +## 12. Dimensionnement indicatif + +Le nombre réel de prereleases est décidé dans `pre.001`. + +Trajectoire candidate uniquement : + +```text +pre.001 audit + brainstorming + plan +pre.002 Error/Result et fondation API +pre.003 Program IDs/primitives retenues +pre.004 compléments/tests/audits +pre.005 validation finale/docs/cleanup/prompt 0.1.2 +``` + +Scinder une prerelease si son périmètre devient trop large. + +## 13. Validations attendues + +Lorsque le code concerné existe et que les commandes sont applicables : + +```bash +cargo fmt --all +cargo check --workspace +cargo test --workspace +cargo clippy --workspace --all-targets +``` + +Exécuter aussi les audits/scripts du dépôt réellement présents et applicables. + +Aucune validation non exécutée ne doit être déclarée réussie. + +## 14. Clôture de `0.1.1` + +La dernière prerelease doit : + +- exécuter les validations finales ; +- corriger documentation et règles devenues obsolètes ; +- nettoyer/archiver les éléments temporaires ; +- mettre à jour le changelog selon les conventions du dépôt ; +- produire le prompt de démarrage `0.1.2` ; +- confirmer la version stable ; +- préparer le commit/tag `v0.1.1`. + +La release suivante prévue est : + +```text +0.1.2 — ksp-logging-lib +``` diff --git a/prompts/001-V0_1_X_START_PROMPT.md b/prompts/001-V0_1_X_START_PROMPT.md deleted file mode 100644 index 543f9bc..0000000 --- a/prompts/001-V0_1_X_START_PROMPT.md +++ /dev/null @@ -1,79 +0,0 @@ - - - -# Prompt de démarrage KSP 0.1.x - -**Status : Brouillon vivant — prompt de démarrage de la série N1, à finaliser avec la première release concrète avant clôture de `0.0.3`.** - -## 1. Identité - -Série fonctionnelle : `0.1.x` — fondations N1. - -`0.1.x` ne représente pas une seule session. La planification finale doit choisir la première release concrète (`0.1.1` ou autre) et lui donner un périmètre compatible avec une session de qualité. - -## 2. Mission de la série - -Construire progressivement : - -- `ksp-core-lib` ; -- `ksp-logging-lib` ; -- `ksp-config-lib` ; -- `ksp-app-config-desk` ; -- uniquement les contrats précoces strictement nécessaires aux étapes suivantes. - -Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`. - -## 3. Base requise - -À finaliser à la clôture de `0.0.3`. - -## 4. État validé à préserver - -À compléter à la clôture de `0.0.3`. - -## 5. Sources de vérité - -Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `010`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. - -## 6. Décisions acquises pertinentes - -- Chaque delta est commité à partir de `0.1.x`. -- Une série `0.1.x` peut contenir plusieurs releases/sessions. -- Chaque release concrète commence par `pre.001` de brainstorming/planification. -- Une prerelease intermédiaire estimée au-delà d'environ 15–20 minutes doit être scindée. -- Une release concrète trop grosse doit être répartie sur plusieurs releases de la même série plutôt que forcer toute la série dans une session. -- Les bibliothèques d'implémentation utilisent `ksp--lib` ; les APIs extensibles utilisent `ksp--api` uniquement lorsqu'un besoin réel le justifie. -- Les applications restent des interfaces/compositions. -- Les exécutables ne dépendent pas directement de crates Solana/protocoles externes. -- `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun. -- `ksp-logging-lib` est la façade KSP propriétaire de `tracing`, `tracing-appender` et `tracing-subscriber`; elle peut dépendre de Core pour `Error` / `Result`, tandis que Core n'a pas de dépendance logging requise. -- Les dépendances basses suivent le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md` ; N1 ne doit pas dépendre de ses consommateurs supérieurs. -- KSP évite les générations anciennes/dupliquées évitables de dépendances fondamentales ; toute contrainte de version non actuelle doit être motivée par un besoin réel. -- Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles. - -## 7. Hors périmètre de la série N1 - -Sauf contrat minimal nécessaire au futur : program implementations, wallet, transport, materializers/store, workers/jobs, protocoles trading et Trading Intelligence. - -## 8. Travail à effectuer avant démarrage - -Pendant `0.0.3-pre.007/pre.008` : - -1. choisir la première release concrète de `0.1.x` ; -2. lui donner une mission unique/cohérente ; -3. produire son plan `pre.001` ; -4. vérifier sa charge ; -5. compléter ce prompt avec la version, l'état validé, les sources et validations exactes. - -## 9. Validations générales attendues - -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.