diff --git a/Cargo.toml b/Cargo.toml index 3440f8c..f48976e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 39 +# version: 40 [workspace] resolver = "3" members = ["crates/ksp-core-lib", "crates/ksp-logging-lib"] [workspace.package] -version = "0.1.2" +version = "0.1.3-pre.1" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index f082b76..b4bded8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -33,7 +33,7 @@ Regrouper les releases consacrées aux fondations N1. Chaque release concrète e - [X] `0.1.1` — Stabiliser `ksp-core-lib` : `Error`/`Result`, Program IDs fondamentaux et primitives réellement N1. - [X] `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.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. diff --git a/deltas/0.1.3/pre.001.md b/deltas/0.1.3/pre.001.md new file mode 100644 index 0000000..7e531c6 --- /dev/null +++ b/deltas/0.1.3/pre.001.md @@ -0,0 +1,333 @@ + + + +# Delta 0.1.3-pre.001 + +## Base requise + +Release stable/taguée attendue : + +```text +v0.1.2 +``` + +L'archive fournie `khadhroony-solana-project-v0.1.2.zip` contient bien : + +- `workspace.package.version = "0.1.2"` ; +- `ksp-core-lib` ; +- `ksp-logging-lib` ; +- `deltas/0.1.2/rel.001.md` ; +- `prompts/003-V0_1_3_START_PROMPT.md` ; +- le plan Logging clôturé `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`. + +## Objectif + +Ouvrir `0.1.3` par la tranche obligatoire de brainstorming, audit et planification sans commencer une implémentation large de Config. + +Le détail des décisions est consigné dans : + +```text +docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md +``` + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.1.2 +``` + +à : + +```text +0.1.3-pre.1 +``` + +L'identifiant Cargo respecte SemVer sans zéro initial ; l'identifiant de livraison reste `0.1.3-pre.001`. + +Aucune dépendance Config n'est ajoutée dans cette tranche de planification. + +## Audit du workspace stable + +État de la base : + +```text +workspace members +├── crates/ksp-core-lib +└── crates/ksp-logging-lib +``` + +Aucun `ksp-config-lib` et aucun répertoire runtime `config/` n'existent encore. + +Core expose déjà : + +```text +Error +ErrorCode +ErrorContext +Result +``` + +Logging expose déjà les types/lifecycles que Config devra consommer : + +```text +LoggingSettings +LoggingGuard +initialize(...) +reinitialize(...) +``` + +La direction retenue est : + +```text +ksp-config-lib -> ksp-core-lib +ksp-config-lib -> ksp-logging-lib +ksp-core-lib -X-> ksp-config-lib +ksp-logging-lib -X-> ksp-config-lib +``` + +## Référence historique bot3 + +L'archive bot3 fournie a été auditée comme référence uniquement. + +Sont conservés comme principes : + +- documents spécialisés ; +- globals hors profils ; +- `default_profile` autonome ; +- compositions propres aux binaires ; +- overrides de profils spécialisés ; +- schémas séparés ; +- classification de sensibilité ; +- séparation source/runtime/public/diagnostic ; +- DTO Tauri possédés par l'application. + +Ne sont pas repris : + +- `AppConfig/ProfileConfig` monolithique/transitoire ; +- les documents de composants non encore développés ; +- l'interpolation générique `${VAR}` dans les chaînes JSON ; +- la mutation globale de l'environnement du processus ; +- la sérialisation d'un runtime secret suivie d'un camouflage a posteriori. + +## Décisions principales + +### Première surface de documents + +Runtime réel prévu : + +```text +config/logging.config.json +config/environment.env +``` + +Schémas : + +```text +config/schemas/logging.config.schema.json +config/schemas/composition.config.schema.json +``` + +Exemples : + +```text +config/examples/example.logging.config.json +config/examples/example.composition.config.json +config/examples/example.environment.env +``` + +Aucun document Transport/Wallet/Store/Execution n'est créé prématurément. + +### Composition + +Nomenclature future : + +```text +config/.default.config.json +``` + +Le composite possède `owner_namespace = ksp|kspb`, son propre `default_profile`, des sources de documents par identifiant et des overrides de profils documentaires. + +Le champ historique `active_profile` n'est pas retenu comme état persisté : le profil effectivement actif est un résultat de résolution runtime. + +Aucune composition runtime concrète n'est créée en `0.1.3`, faute d'exécutable consommateur ; le contrat sera testé par schema/exemple/fixtures avant `ksp-app-config-desk`. + +### Résolution + +Ordre fixé : + +```text +locator +-> document source +-> schema/source validation +-> composition +-> composition profile +-> document profile +-> globals + profile +-> env bindings +-> effective validation +-> component runtime contract +``` + +Pour les overrides de valeurs : + +```text +process environment +> config/environment.env +> document/profile +``` + +### Environnement + +Namespaces : + +```text +KSP_SECRET_* / KSP_PUBLIC_* / KSP_* +KSPB_SECRET_* / KSPB_PUBLIC_* / KSPB_* +``` + +Les overrides sont déclarés explicitement par binding clé Config -> variable. Aucun mapping automatique par transformation de chemin JSON et aucune interpolation générique ne sont retenus. + +Le fichier géré prévu est : + +```text +config/environment.env +``` + +Il utilise une grammaire KSP v1 stricte (`# ksp-env-format: 1`), sans expansion `$VAR`/`${VAR}`, sans syntaxe shell et avec refus des doublons/noms non enregistrés. L'audit a conduit à **ne pas retenir `dotenvy`**, car son parser 0.15.7 effectue des substitutions même via l'iterator. + +Les contrôles initiaux sont `KSP_ENV_FILE` (process-only), `KSP_CONFIG_PROFILE` et le futur `KSPB_CONFIG_PROFILE`. + +En Rust 2024, `std::env::set_var/remove_var` sont `unsafe`. Comme KSP interdit `unsafe`, `ksp-config-lib` ne modifie jamais l'environnement global du processus. La future surface management modifie le fichier d'environnement géré et signale lorsqu'une valeur du processus continue à la shadow. + +### Sensibilité + +Classes : + +```text +Public +Internal +Secret +``` + +Un secret peut être lu par un consumer runtime qui en a réellement besoin ou par une surface de management explicitement privilégiée. Il n'est pas exposé dans les logs, diagnostics ordinaires ou DTO publics génériques. + +Cette séparation est une barrière d'API et de non-divulgation ; l'authentification d'un utilisateur final appartient à l'application. + +### Mutation/persistence + +`0.1.3` conserve la mutation dans son périmètre, mais uniquement pour les sources Config connues. + +La persistence doit être atomique : ancien fichier complet ou nouveau fichier complet, jamais un fichier destination partiel. Les sources gérées sont bornées par un `ConfigRoot` explicite ; une composition ne peut pas référencer un chemin absolu ou sortir de cette racine. Une destination writable qui est un symlink est refusée initialement afin de ne pas remplacer le lien ni suivre implicitement une cible hors frontière Config. + +`atomic-write-file` est retenue comme dépendance candidate à auditer au moment de l'introduction réelle. + +Le résultat d'une mutation doit distinguer source souhaitée et valeur effective, notamment en présence d'un override process. + +### Logging + +Config produit : + +```text +ResolvedLoggingConfig -> ksp_logging_lib::LoggingSettings +``` + +L'orchestration possède `LoggingGuard` et décide d'appeler `initialize` ou `reinitialize`. Dans `0.1.3`, le harness d’intégration possède localement guard + session Config ; dans `0.1.4`, ce sera l’état backend de `ksp-app-config-desk`. Config ne possède jamais le guard et n'introduit pas de singleton global. + +## Dépendances candidates auditées + +Aucune dépendance ajoutée dans `pre.001`. + +Générations candidates à revérifier au moment de l'ajout : + +```text +serde ^1.0 +serde_json ^1.0 +jsonschema ^0.49 default-features = false +atomic-write-file ^0.3 +``` + +Le plan rejette initialement toute dépendance Config à Tokio, Tauri, TS-RS, watcher filesystem, `anyhow` ou `thiserror`. + +## Découpage prévu + +```text +pre.001 audit + brainstorming + plan +pre.002 crate foundation + erreurs + modèles source +pre.003 schemas + logging.config.json +pre.004 composition + profils +pre.005 environnement + sensibilité +pre.006 adapter Logging + lifecycle integration +pre.007 management + persistence atomique +pre.008 ownership audits + robustesse +pre.009 validation finale + docs/cleanup + prompt 0.1.4 +``` + +Le découpage reste souple. + +## Fichiers ajoutés + +- `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md` +- `deltas/0.1.3/pre.001.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `ROADMAP.md` +- `docs/plans/000-README.md` +- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` + +## Fichiers supprimés + +Aucun. + +## Hors scope confirmé + +- application desktop Config ; +- Tauri/TS-RS dans Config ; +- Wallet ; +- Store/PostgreSQL ; +- RPC/WS/provider ; +- Program/decoder/execution ; +- workers/jobs/pipelines ; +- watcher filesystem ; +- service distribué Config ; +- secrets manager distant ; +- configuration de composants inexistants. + +## Validations de livraison + +Ce delta ne modifie aucun source Rust mais modifie la version Cargo. + +Les quatre validations Cargo applicables ont été tentées dans l'environnement de préparation : + +```bash +cargo fmt --all +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test --workspace +``` + +Résultat : **non exécutées**, car cet environnement ne fournit pas l'exécutable `cargo` (`cargo: command not found`). Aucune de ces commandes n'est déclarée réussie. Elles restent à exécuter sur le workspace utilisateur avant validation/commit du delta. + +Les commandes suivantes ne sont pas applicables au `pre.001`, car la crate `ksp-config-lib` n'est volontairement pas encore créée : + +```bash +cargo tree -p ksp-config-lib +cargo tree -p ksp-config-lib -d +cargo tree -p ksp-config-lib -e features +``` + +Contrôles statiques réellement exécutés : + +- liens Markdown locaux des fichiers modifiés/ajoutés : résolus ; +- fences Markdown du plan et du delta : équilibrées ; +- diff `[workspace.dependencies]` contre `v0.1.2` : aucun changement ; +- `Cargo.lock` : absent ; +- `target/` : absent ; +- `crates/ksp-config-lib/` : absent, conformément au scope `pre.001` ; +- `config/` runtime : absent, conformément au scope `pre.001` ; +- répertoire/script d'audit dans la base fournie : aucun trouvé au niveau workspace. + +Le scan statique de la base confirme également que les usages `tracing*` existants restent dans `ksp-logging-lib`; le seul `std::env` relevé dans la base Rust stable auditée est un `temp_dir()` de test Logging, pas une lecture de variable applicative. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index ab39ff2..1fb4e73 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,5 @@ - + # Plans KSP @@ -13,6 +13,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou - [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence active de référence des premières releases fonctionnelles ; - [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.1`, établi par `0.1.1-pre.001` puis consolidé jusqu'à `0.1.1-rel.001`. - [`004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](004-V0_1_2_LOGGING_FOUNDATION_PLAN.md) — plan historique clôturé de la release stable `0.1.2`, établi par `0.1.2-pre.001` puis consolidé jusqu'à `0.1.2-rel.001`. +- [`005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](005-V0_1_3_CONFIG_FOUNDATION_PLAN.md) — plan actif de `0.1.3 — Configuration foundation`, établi par `0.1.3-pre.001` avant développement fonctionnel de `ksp-config-lib`. Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index e3cc178..ea62efb 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # Séquence des releases fonctionnelles KSP @@ -167,7 +167,9 @@ ksp-config-lib Introduire la configuration générale KSP. -Périmètre candidat à revalider dans son `pre.001` : +Le `0.1.3-pre.001` a revalidé ce périmètre et décidé qu'il tient dans une seule release à condition de limiter le premier cycle au socle générique, au document Logging, à la composition, à l'environnement KSP/KSPB, aux surfaces d'accès et à la persistence autorisée. Le plan normatif détaillé est `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`. + +Périmètre retenu : - documents spécialisés ; - profils ; @@ -184,15 +186,15 @@ Périmètre candidat à revalider dans son `pre.001` : - ownership exclusif de `ksp-config-lib` sur lecture/résolution/validation/mutation des fichiers Config et variables d'environnement ; - accès explicite aux secrets pour les surfaces de management autorisées. -### Règle de scission +### Décision 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`. +Le `pre.001` ne scinde pas Config : `0.1.3` reste une release unique et `0.1.4` reste réservée à `ksp-app-config-desk`. -Aucun sous-périmètre n'est compressé artificiellement pour préserver le numéro `0.1.4` de l'application desktop. +Cette décision repose sur l'absence volontaire de documents Transport/Wallet/Store/Execution et de watcher générique dans le premier cycle. Si une tranche ultérieure révèle une contrainte technique majeure réellement non bornable, la séquence peut encore être corrigée par un delta explicite plutôt que de comprimer artificiellement le périmètre. ## `0.1.4` — Config desktop par défaut -Sous réserve d'absence de scission de Config. +La décision `0.1.3-pre.001` conserve cette release comme étape suivante par défaut. Mission :