khadhroony-solana-project/deltas/0.1.3/pre.001-fix.001.md

Delta 0.1.3-pre.001-fix.001

Base requise

Livraison précédente :

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 :

config/environment.env

est annulée.

La source persistante locale par défaut devient :

.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 :

process environment
> .env
> fallback déclaré au point d'usage
> missing

Exemple :

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 :

${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 :

clé Config -> nom de variable

n'est plus retenue.

Une référence comme :

"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 :

https://mainnet.helius-rpc.com/?api-key=${KSP_SECRET_HELIUS_API_KEY}

doit conserver conceptuellement :

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 :

config/std.logging.json
config/schemas/std.logging.schema.json

Nomenclature future :

config/std.<domain>.json
config/composite.<consumer>.json

Exemple futur :

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 :

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é

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 :

0.1.3-pre.1

L'identifiant de livraison est :

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.