khadhroony-solana-project/deltas/0.1.3/pre.010.md

Delta 0.1.3-pre.010

Base requise

Livraison précédente validée :

0.1.3-pre.009-fix.001

Version technique de cette base :

workspace.package.version = "0.1.3-pre.9.fix.1"
Cargo.toml header version = 51

Validations utilisateur exécutées le 2026-08-15 :

cargo fmt --all                          OK
cargo check --workspace                 OK
cargo clippy --workspace --all-targets  OK
cargo test --workspace                  OK
cargo tree -p ksp-config-lib            OK
cargo tree -p ksp-config-lib -d         OK, doublon transitif syn 2/3 déjà connu
cargo tree -p ksp-config-lib -e features OK

cargo test --workspace confirme notamment 39 tests unitaires + 7 tests publics pour ksp-config-lib.

Objet de pre.010

Introduire la première résolution environnementale Config réellement consommable :

process environment
        >
      ./.env
        >
placeholder/API fallback
        ->
ConfigEnvironmentValue
        ->
${NAME} / ${NAME:-fallback}
        ->
JSON effective values

La sensibilité et les représentations sûres restent volontairement réservées à pre.011.

Propriété et sources

ConfigEnvironment est le snapshot possédé par ksp-config-lib.

ConfigEnvironment::load() :

1. capture les variables supportées héritées par le processus ;
2. lit ./.env s'il existe ;
3. ne modifie jamais l'environnement du processus, du shell, de systemd ou du parent ;
4. considère l'absence de .env comme une source locale vide.

Une erreur de lecture réelle de .env reste distincte de son absence.

Les seuls namespaces applicatifs acceptés sont :

KSP_*
KSPB_*

ce qui couvre naturellement :

KSP_PUBLIC_*
KSP_SECRET_*
KSPB_PUBLIC_*
KSPB_SECRET_*

Priorité et chaîne vide

ConfigEnvironment::resolve_variable(name, fallback) applique :

process > .env > fallback > missing

Une chaîne vide explicitement présente dans le processus ou .env reste une valeur définie. Elle ne déclenche pas le fallback.

ConfigEnvironmentValue expose :

variable_name
value réelle
source = Process | DotEnv | Fallback

Le type n'implémente volontairement pas Debug afin de ne pas créer une voie de fuite accidentelle avant l'introduction de la sensibilité/redaction en pre.011.

Resolver ${...}

Config supporte :

${KSP_VAR}
${KSP_VAR:-fallback}

Règles :

• plusieurs placeholders peuvent apparaître dans une même string ;
• le fallback n'est utilisé que si la variable est absente ;
• le fallback est littéral dans cette tranche et n'est pas récursivement interprété ;
• les placeholders imbriqués/malformés sont refusés ;
• les clés JSON ne sont pas interpolées ; seules les valeurs string le sont ;
• objets et tableaux JSON sont parcourus récursivement.

APIs principales :

ConfigEnvironment::resolve_variable(...)
ConfigEnvironment::resolve_text(...)
ConfigEnvironment::resolve_json(...)
ConfigEnvironment::resolve_map(...)
ResolvedConfigProfile::resolve_effective_environment(...)

La résolution d'environnement d'un profil produit une nouvelle map effective et ne modifie pas la source, le profile_id, la provenance Global/Profile ni la sélection du profil déjà résolu.

Variable manquante

Une référence sans valeur process, sans valeur .env et sans fallback retourne :

config.environment_variable_missing

Config émet également un warning via la façade KSP :

target = ksp-config-lib
domain = config.environment

Le warning et l'erreur contiennent le nom de la variable mais jamais sa valeur.

ksp-config-lib dépend donc maintenant réellement de ksp-logging-lib. La dépendance inverse Logging -> Config reste interdite.

.env

Le parser Config de cette tranche accepte un sous-ensemble déterministe adapté au fichier KSP géré :

• lignes vides et commentaires # ;
• préfixe optionnel export ;
• NAME=value ;
• valeur non quotée ;
• valeur entre quotes simples ;
• valeur entre quotes doubles avec escapes bornés \\, \", \n, \r, \t ;
• commentaire inline d'une valeur non quotée lorsqu'il commence par # ;
• chaîne vide ;
• clés étrangères valides ignorées par Config ;
• doublon d'une clé KSP/KSPB refusé pour éviter une résolution locale ambiguë.

Aucune interpolation interne du fichier .env n'est ajoutée dans cette tranche.

.env.example — nouvelle règle durable

Le dépôt possède désormais à la racine :

.env.example

Ce fichier est versionné et sert d'inventaire canonique des variables runtime KSP/KSPB utilisées par les fichiers Config ou le code opérationnel.

Règles enregistrées :

• toute nouvelle variable runtime KSP/KSPB est ajoutée à .env.example dans le même delta que sa première utilisation ;
• chaque variable est précédée d'un commentaire expliquant son usage/utilité ;
• une entrée peut être active avec une valeur par défaut sûre, porter une valeur générique non secrète ou être commentée ;
• aucun vrai secret n'y est stocké ;
• le fichier local .env reste non versionné et non échangé ;
• l'objectif est de pouvoir créer .env depuis .env.example et repérer localement les nouvelles clés par diff.

La première entrée est :

KSP_LOGS_DIRECTORY=logs

car config/std.logging.json est actuellement le seul fichier runtime utilisant une variable d'environnement.

.gitignore possédait déjà :

.env
.env.*
!.env.example

et n'a donc pas besoin d'être modifié.

Tests

Les nouveaux tests couvrent notamment :

• priorité process > .env > fallback ;
• chaîne vide process et .env considérée comme définie ;
• variable manquante sans fallback ;
• namespaces KSP/KSPB ;
• résolution de plusieurs placeholders ;
• placeholder malformé/imbriqué ;
• résolution récursive object/array JSON ;
• parsing .env avec commentaires, export et quotes ;
• refus des doublons KSP dans .env ;
• collecte process synthétique sans mutation du vrai environnement ;
• résolution du fallback ${KSP_LOGS_DIRECTORY:-logs} du document Logging commité ;
• présence commentée de KSP_LOGS_DIRECTORY dans .env.example ;
• disponibilité de la surface environment depuis le crate-root.

Les tests n'appellent pas std::env::set_var / remove_var; aucune mutation unsafe de l'environnement n'est nécessaire en Rust 2024.

Dépendances

Aucune nouvelle dépendance externe n'est ajoutée.

Dépendance KSP désormais utilisée :

ksp-config-lib -> ksp-logging-lib

pour les warnings/diagnostics runtime Config.

Les dépendances externes serde, serde_json et jsonschema restent inchangées.

Version technique

La prerelease devient :

workspace.package.version = "0.1.3-pre.10"
Cargo.toml header version = 52

Fichiers ajoutés

.env.example
crates/ksp-config-lib/src/environment.rs
crates/ksp-config-lib/unit_tests/environment.rs
deltas/0.1.3/pre.010.md

Fichiers modifiés

Cargo.toml
crates/ksp-config-lib/Cargo.toml
crates/ksp-config-lib/src/error.rs
crates/ksp-config-lib/src/lib.rs
crates/ksp-config-lib/src/profile.rs
crates/ksp-config-lib/tests/public_api.rs
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/plans/000-README.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
docs/rules/FILE_CONTRACTS.md
docs/rules/RULES_KSP.md

Fichiers supprimés

Aucun.

Contrôles exécutés dans l'environnement de génération

• parsing TOML du manifest racine et de ksp-config-lib ;
• audit statique des accès std::env::* : seul crates/ksp-config-lib/src/environment.rs lit l'environnement applicatif ;
• audit statique des variables runtime exactes dans crates/*/src + config/ : KSP_LOGS_DIRECTORY est la seule clé actuelle et elle est présente dans .env.example ;
• absence de unsafe, unwrap, expect, panic! et ? dans le nouveau code de production Config ;
• contrôle des headers/version et des lignes Rust ajoutées/modifiées ;
• comparaison du delta avec la base pre.009-fix.001 ;
• aucun Cargo.lock ajouté.

Le toolchain Rust n'est pas disponible dans l'environnement de génération. cargo fmt/check/clippy/test doivent donc être exécutés par l'utilisateur.

Étape suivante

Après validation utilisateur :

0.1.3-pre.011 — sensibilité Public/Internal/Secret + real/safe/provenance + redaction par segment