v0.1.3-pre.010

docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md

@@ -1,11 +1,11 @@
 <!-- file: docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
 # Plan `0.1.3` — Configuration foundation
 
 ## 1. Statut et objectif
 
-Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, `pre.004` les contrats publics multi-output de Logging, `pre.005` le runtime multi-sink sur niveau/target/formats, `pre.006` le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema, `pre.008` la résolution des globals/profils/`default_profile` et `pre.009` les compositions génériques par `file_id`. La prochaine tranche est `pre.010` pour `.env`, process env et le resolver `${...}`.
+Ce plan a été établi par `0.1.3-pre.001`, corrigé par `0.1.3-pre.001-fix.001/.002/.003`, puis exécuté par petites tranches. `pre.002` a livré le bootstrap Config, `pre.003` le registre `file_id`, `pre.004` les contrats publics multi-output de Logging, `pre.005` le runtime multi-sink sur niveau/target/formats, `pre.006` le routing structuré `domain`, `pre.007` le moteur JSON/JSON Schema, `pre.008` la résolution des globals/profils/`default_profile`, `pre.009` les compositions génériques par `file_id` et `pre.010` le snapshot process + `.env` et le resolver `${...}`. La prochaine tranche est `pre.011` pour sensibilité, valeur réelle/sûre et provenance enrichie.
 
 La base auditée reste la release stable `v0.1.2`.
 
@@ -163,6 +163,7 @@ KSP conserve :
 - composition propre à un exécutable/application ;
 - sélection d'un profil spécialisé depuis la composition ;
 - `.env` séparé des documents JSON ;
+- `.env.example` versionné et maintenu au fil de l'apparition des variables runtime ;
 - priorité de l'environnement réel du processus sur `.env` ;
 - fallback déclaré au point d'usage via `${NAME:-fallback}` ;
 - classification nominale des variables ;
@@ -1779,16 +1780,27 @@ Tranche livrée :
 - `ConfigDocumentEngine::load_resolved_composite(file_id, requested_profile)` est prêt pour les futurs descriptors `cfg.composite.<consumer>` ;
 - les tests utilisent un descriptor composite privé à la crate pointant vers l’exemple versionné afin de valider la résolution complète sans créer un composite runtime fictif.
 
+La validation utilisateur de `pre.009-fix.001` est acquise : `fmt/check/clippy/test` passent, les 39 tests unitaires Config et 7 tests publics passent, et le graphe de dépendances reste conforme avec le seul doublon transitif `syn 2`/`syn 3` déjà connu via `jsonschema`.
+
 ### `0.1.3-pre.010` — `.env` + process env + resolver `${...}`
 
-- lecture process env ;
-- lecture `.env` sans écrasement process ;
-- priorité process > `.env` > fallback ;
-- `${NAME}` / `${NAME:-fallback}` ;
-- fallback appliqué seulement si la variable est absente ;
-- missing diagnostics + warning ;
-- namespaces KSP/KSPB ;
-- tests d'isolation process env.
+Tranche livrée :
+
+- `ConfigEnvironment::load()` capture les variables KSP/KSPB du processus puis lit `./.env` sans modifier l'environnement externe ;
+- l'absence de `.env` est valide et équivaut à une source locale vide ; les autres erreurs de lecture sont distinctes ;
+- priorité effective process > `.env` > fallback, y compris le cas d'une chaîne vide explicitement définie ;
+- `ConfigEnvironmentValue` expose la valeur réelle et sa source `Process` / `DotEnv` / `Fallback` sans implémentation `Debug` afin de ne pas créer une fuite accidentelle avant le contrat de redaction de `pre.011` ;
+- `${NAME}` et `${NAME:-fallback}` sont résolus dans les strings, maps et valeurs JSON récursives ; plusieurs placeholders sont supportés ;
+- le fallback reste littéral et n'est pas récursivement interprété dans cette tranche ;
+- une variable manquante sans fallback retourne `config.environment_variable_missing` et émet un warning via `ksp-logging-lib` avec target `ksp-config-lib`, sans valeur dans le diagnostic ;
+- seuls les namespaces `KSP_*` et `KSPB_*` sont acceptés par l'API Config ;
+- le parser `.env` supporte commentaires, `export`, valeurs non quotées/simplement/doublement quotées et refuse les doublons KSP ambigus ;
+- les tests de priorité process utilisent des sources injectées/itérateurs synthétiques : ils ne mutent jamais le vrai environnement du processus, ce qui évite `unsafe` en Rust 2024 ;
+- `ResolvedConfigProfile::resolve_effective_environment()` résout la vue effective sans modifier le profil source ni sa provenance Global/Profile ;
+- `ksp-config-lib` dépend désormais réellement de `ksp-logging-lib` pour ses warnings Config ; la dépendance inverse reste interdite ;
+- `.env.example` est créé à la racine avec `KSP_LOGS_DIRECTORY`, seule variable runtime actuellement utilisée ;
+- la règle durable impose désormais d'ajouter toute nouvelle variable runtime KSP/KSPB à `.env.example`, avec commentaire d'usage, dans le même delta que sa première utilisation ;
+- `.gitignore` possédait déjà la règle correcte `.env`, `.env.*`, `!.env.example`; aucun changement n'est nécessaire.
 
 ### `0.1.3-pre.011` — sensibilité + valeurs real/safe/provenance