v0.1.3-pre.001-fix.001

deltas/0.1.3/pre.001-fix.001.md

@@ -0,0 +1,273 @@
+<!-- file: deltas/0.1.3/pre.001-fix.001.md -->
+<!-- version: 1 -->
+
+# Delta 0.1.3-pre.001-fix.001
+
+## Base requise
+
+Livraison précédente :
+
+```text
+0.1.3-pre.001
+```
+
+Ce correctif reste documentaire. Il corrige le plan de `pre.001` avant tout développement fonctionnel de `ksp-config-lib` et ne réécrit pas le delta historique `pre.001.md`.
+
+## Objectif
+
+Aligner le plan Config sur le contrat fonctionnel validé après `pre.001` :
+
+- `ksp-config-lib` devient l'unique propriétaire KSP de la lecture/résolution/validation/mutation de la configuration applicative ;
+- les variables applicatives sont résolues par Config depuis l'environnement réel du processus et un `.env` conventionnel ;
+- la priorité est `process env > .env > fallback` ;
+- les fallbacks sont déclarés au point d'usage par `${NAME:-fallback}` ;
+- les références `${KSP_*}` / `${KSPB_*}` dans les documents JSON sont elles-mêmes les déclarations d'usage, sans table de bindings centrale ;
+- les valeurs dérivées de `*_SECRET_*` conservent une valeur runtime réelle et une représentation sûre/redacted ;
+- les variables absentes sans fallback produisent diagnostic + warning et empêchent une résolution runtime complète ;
+- Config peut créer/modifier/supprimer les entrées du `.env` ;
+- la première surface réelle est renommée `config/std.logging.json` ;
+- les futurs documents et composites suivent `std.<domain>.json` et `composite.<consumer>.json`.
+
+Aucune implémentation `pre.002` ne doit commencer avant validation utilisateur du plan corrigé.
+
+## Corrections apportées au plan
+
+### `.env` conventionnel
+
+La décision initiale :
+
+```text
+config/environment.env
+```
+
+est annulée.
+
+La source persistante locale par défaut devient :
+
+```text
+.env
+```
+
+à la racine runtime/workspace fournie à Config.
+
+Le fichier reste ignoré par Git et peut être manipulé exclusivement via `ksp-config-lib` dans l'écosystème KSP.
+
+### Priorité des variables
+
+Pour une variable utilisée :
+
+```text
+process environment
+> .env
+> fallback déclaré au point d'usage
+> missing
+```
+
+Exemple :
+
+```text
+export KSP_PUBLIC_FOO=console
+.env: KSP_PUBLIC_FOO=dotenv
+JSON: ${KSP_PUBLIC_FOO:-fallback}
+```
+
+La valeur effective est `console`.
+
+Une chaîne vide explicitement définie est considérée comme définie et ne déclenche pas le fallback.
+
+### Placeholders Config
+
+Le rejet initial de l'interpolation `${...}` est annulé.
+
+Les syntaxes initiales sont :
+
+```text
+${KSP_VAR}
+${KSP_VAR:-fallback}
+```
+
+et leurs équivalents `KSPB_*`.
+
+Le resolver appartient à Config et conserve provenance/sensibilité. Il n'est pas délégué à un consumer ni à une expansion dotenv opaque.
+
+### Suppression des bindings statiques
+
+La table prédéfinie :
+
+```text
+clé Config -> nom de variable
+```
+
+n'est plus retenue.
+
+Une référence comme :
+
+```json
+"logs_directory": "${KSP_LOGS_DIRECTORY:-logs}"
+```
+
+constitue directement la déclaration d'usage de `KSP_LOGS_DIRECTORY`.
+
+Config peut aussi exposer une requête directe nom + fallback optionnel pour les rares variables utilisées hors document JSON, toujours sans accès `std::env` direct dans les consumers.
+
+### Missing sans fallback
+
+Lorsqu'une référence `${KSP_VAR}` n'est définie ni dans le process ni dans `.env` :
+
+- Config produit un diagnostic structuré ;
+- Config émet un warning sous le target `ksp-config-lib` lorsque Logging est disponible ;
+- le diagnostic indique nom/document/path mais aucune valeur secrète ;
+- la construction d'un runtime complet échoue tant que la référence reste non résolue ;
+- une application de management peut néanmoins charger le document source pour le corriger.
+
+### Secrets et valeurs composées
+
+Une chaîne telle que :
+
+```text
+https://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY}
+```
+
+doit conserver conceptuellement :
+
+```text
+real = https://mainnet.helius-rpc.com/?api-key=<real-secret>
+safe = https://mainnet.helius-rpc.com/?api-key=********
+sensitivity = Secret
+provenance = variable + source effective
+```
+
+Le runtime légitime peut utiliser `real`; les logs/diagnostics utilisent `safe`.
+
+Une application de management Config peut explicitement révéler/modifier un secret. Cette exception de visualisation n'autorise jamais le secret dans les logs.
+
+### Nomenclature des documents
+
+La première surface réelle devient :
+
+```text
+config/std.logging.json
+config/schemas/std.logging.schema.json
+```
+
+Nomenclature future :
+
+```text
+config/std.<domain>.json
+config/composite.<consumer>.json
+```
+
+Exemple futur :
+
+```text
+config/composite.ksp-app-wallet-desk.json
+```
+
+Les autres documents spécialisés ne sont pas créés avant leurs composants.
+
+### Globals, profils et composites
+
+Le contrat maintient :
+
+```text
+paramètres globaux
++ default_profile
++ profiles
+```
+
+Une composition assemble les documents spécialisés et choisit éventuellement leurs profils sans recopier leur contenu. Les globals du document restent automatiquement partie de la configuration effective.
+
+### Mutation de l'environnement
+
+Le contrat distingue :
+
+- environnement réel du processus : source read-only et prioritaire ;
+- `.env` : source persistante read/write possédée par Config.
+
+Config peut créer/modifier/supprimer des entrées `.env` et doit signaler si une valeur process continue à shadow la valeur persistée.
+
+Il ne prétend pas modifier le shell parent, systemd, Docker ou un autre processus.
+
+## Découpage prerelease corrigé
+
+```text
+pre.002  fondation crate + contrats source
+pre.003  JSON Schema + config/std.logging.json
+pre.004  profils + composition
+pre.005  .env + resolver ${...} + fallback + warnings missing
+pre.006  sensibilité + real/safe + Logging adapter
+pre.007  management + persistence JSON/.env
+pre.008  ownership audits + robustesse
+pre.009  clôture
+```
+
+Le périmètre `0.1.3` reste une release unique et `0.1.4` reste `ksp-app-config-desk`.
+
+## Fichiers ajoutés
+
+- `deltas/0.1.3/pre.001-fix.001.md`
+
+## Fichiers modifiés
+
+- `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`
+- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`
+- `docs/plans/000-README.md`
+
+## Fichiers supprimés
+
+Aucun.
+
+## Version Cargo
+
+Aucune modification de `Cargo.toml`.
+
+Ce fix est uniquement documentaire et respecte `VER-ID-008`. La version workspace reste :
+
+```text
+0.1.3-pre.1
+```
+
+L'identifiant de livraison est :
+
+```text
+0.1.3-pre.001-fix.001
+```
+
+## Dépendances
+
+Aucune dépendance ajoutée ou modifiée.
+
+Le plan ne choisit pas encore de bibliothèque dotenv. Le choix sera audité au delta qui implémente réellement `.env`.
+
+## Validations exécutées
+
+- comparaison de la livraison `0.1.3-pre.001` avec la base `v0.1.2` ;
+- relecture de `docs/rules/VERSION_WORKFLOW.md`, notamment `VER-ID-008` et `VER-ARCHIVE-004` ;
+- réaudit ciblé de la référence bot3 pour `.env`, `${NAME:-fallback}`, secrets composés et composition ;
+- contrôle des headers `file:` / `version:` des fichiers modifiés/ajoutés ;
+- recherche des anciennes décisions `environment.env`, interdiction d'interpolation et bindings statiques dans le plan corrigé ;
+- contrôle de la nomenclature `std.logging.json` / `std.<domain>.json` / `composite.<consumer>.json` ;
+- contrôle que le correctif ne modifie aucun code Rust, aucun manifest Cargo et aucun fichier runtime Config ;
+- contrôle du contenu de l'archive delta selon `VER-ARCHIVE-004`.
+
+## Validations non exécutées
+
+Aucune validation Cargo n'est déclarée réussie dans ce correctif documentaire.
+
+Aucun code Config n'existe encore et aucun manifest/code Rust n'est modifié par le fix. Les validations Cargo de `0.1.3` commenceront avec les tranches de développement applicables.
+
+## Questions ouvertes avant `pre.002`
+
+Le plan corrigé est soumis à validation utilisateur.
+
+Les détails volontairement différés à l'implémentation sont :
+
+- bibliothèque dotenv éventuelle ou parser borné possédé par Config ;
+- grammaire précise des quotes/escapes du `.env` ;
+- type Rust exact de la valeur `real/safe/provenance/sensitivity` ;
+- primitive exacte d'écriture atomique ;
+- noms finaux des APIs runtime/diagnostic/management.
+
+Ces choix ne doivent pas modifier les invariants fonctionnels fixés par le plan.
+
+Après validation de ce fix, la prochaine tranche est `0.1.3-pre.002`.

docs/plans/000-README.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/000-README.md -->
-<!-- version: 8 -->
+<!-- version: 9 -->
 
 # Plans KSP
 
@@ -13,7 +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`.
+- [`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` puis corrigé par `pre.001-fix.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.
 

docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Séquence des releases fonctionnelles KSP
 
@@ -167,7 +167,7 @@ ksp-config-lib
 
 Introduire la configuration générale KSP.
 
-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`.
+Le `0.1.3-pre.001`, corrigé par `pre.001-fix.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 :
 
@@ -178,9 +178,11 @@ Périmètre retenu :
 - résolution ;
 - validation ;
 - modification/sauvegarde ;
-- variables d'environnement `KSP_*` / `KSPB_*` ;
+- variables d'environnement `KSP_*` / `KSPB_*`, résolues exclusivement par Config ;
+- priorité process env > `.env` > fallback `${NAME:-fallback}` ;
+- propagation de la sensibilité et représentation sûre/redacted des valeurs dérivées de `*_SECRET_*` ;
 - secret/public/debug exposure policy ;
-- `logging.config.json` séparé ;
+- premier document spécialisé concret `config/std.logging.json` ;
 - vrais fichiers runtime sous `config/`, schemas sous `config/schemas/` et exemples sous `config/examples/` ;
 - documents unitaires spécialisés + fichiers composites par application/exécutable ;
 - ownership exclusif de `ksp-config-lib` sur lecture/résolution/validation/mutation des fichiers Config et variables d'environnement ;