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

<!-- 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`.