# 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..json` et `composite..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= 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..json config/composite..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..json` / `composite..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`.