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

<!-- file: deltas/0.1.3/pre.001.md -->
<!-- version: 1 -->

# Delta 0.1.3-pre.001

## Base requise

Release stable/taguée attendue :

```text
v0.1.2
```

L'archive fournie `khadhroony-solana-project-v0.1.2.zip` contient bien :

- `workspace.package.version = "0.1.2"` ;
- `ksp-core-lib` ;
- `ksp-logging-lib` ;
- `deltas/0.1.2/rel.001.md` ;
- `prompts/003-V0_1_3_START_PROMPT.md` ;
- le plan Logging clôturé `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`.

## Objectif

Ouvrir `0.1.3` par la tranche obligatoire de brainstorming, audit et planification sans commencer une implémentation large de Config.

Le détail des décisions est consigné dans :

```text
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
```

## Version Cargo

`workspace.package.version` passe de :

```text
0.1.2
```

à :

```text
0.1.3-pre.1
```

L'identifiant Cargo respecte SemVer sans zéro initial ; l'identifiant de livraison reste `0.1.3-pre.001`.

Aucune dépendance Config n'est ajoutée dans cette tranche de planification.

## Audit du workspace stable

État de la base :

```text
workspace members
├── crates/ksp-core-lib
└── crates/ksp-logging-lib
```

Aucun `ksp-config-lib` et aucun répertoire runtime `config/` n'existent encore.

Core expose déjà :

```text
Error
ErrorCode
ErrorContext
Result<T>
```

Logging expose déjà les types/lifecycles que Config devra consommer :

```text
LoggingSettings
LoggingGuard
initialize(...)
reinitialize(...)
```

La direction retenue est :

```text
ksp-config-lib  -> ksp-core-lib
ksp-config-lib  -> ksp-logging-lib
ksp-core-lib    -X-> ksp-config-lib
ksp-logging-lib -X-> ksp-config-lib
```

## Référence historique bot3

L'archive bot3 fournie a été auditée comme référence uniquement.

Sont conservés comme principes :

- documents spécialisés ;
- globals hors profils ;
- `default_profile` autonome ;
- compositions propres aux binaires ;
- overrides de profils spécialisés ;
- schémas séparés ;
- classification de sensibilité ;
- séparation source/runtime/public/diagnostic ;
- DTO Tauri possédés par l'application.

Ne sont pas repris :

- `AppConfig/ProfileConfig` monolithique/transitoire ;
- les documents de composants non encore développés ;
- l'interpolation générique `${VAR}` dans les chaînes JSON ;
- la mutation globale de l'environnement du processus ;
- la sérialisation d'un runtime secret suivie d'un camouflage a posteriori.

## Décisions principales

### Première surface de documents

Runtime réel prévu :

```text
config/logging.config.json
config/environment.env
```

Schémas :

```text
config/schemas/logging.config.schema.json
config/schemas/composition.config.schema.json
```

Exemples :

```text
config/examples/example.logging.config.json
config/examples/example.composition.config.json
config/examples/example.environment.env
```

Aucun document Transport/Wallet/Store/Execution n'est créé prématurément.

### Composition

Nomenclature future :

```text
config/<executable>.default.config.json
```

Le composite possède `owner_namespace = ksp|kspb`, son propre `default_profile`, des sources de documents par identifiant et des overrides de profils documentaires.

Le champ historique `active_profile` n'est pas retenu comme état persisté : le profil effectivement actif est un résultat de résolution runtime.

Aucune composition runtime concrète n'est créée en `0.1.3`, faute d'exécutable consommateur ; le contrat sera testé par schema/exemple/fixtures avant `ksp-app-config-desk`.

### Résolution

Ordre fixé :

```text
locator
-> document source
-> schema/source validation
-> composition
-> composition profile
-> document profile
-> globals + profile
-> env bindings
-> effective validation
-> component runtime contract
```

Pour les overrides de valeurs :

```text
process environment
> config/environment.env
> document/profile
```

### Environnement

Namespaces :

```text
KSP_SECRET_* / KSP_PUBLIC_* / KSP_*
KSPB_SECRET_* / KSPB_PUBLIC_* / KSPB_*
```

Les overrides sont déclarés explicitement par binding clé Config -> variable. Aucun mapping automatique par transformation de chemin JSON et aucune interpolation générique ne sont retenus.

Le fichier géré prévu est :

```text
config/environment.env
```

Il utilise une grammaire KSP v1 stricte (`# ksp-env-format: 1`), sans expansion `$VAR`/`${VAR}`, sans syntaxe shell et avec refus des doublons/noms non enregistrés. L'audit a conduit à **ne pas retenir `dotenvy`**, car son parser 0.15.7 effectue des substitutions même via l'iterator.

Les contrôles initiaux sont `KSP_ENV_FILE` (process-only), `KSP_CONFIG_PROFILE` et le futur `KSPB_CONFIG_PROFILE`.

En Rust 2024, `std::env::set_var/remove_var` sont `unsafe`. Comme KSP interdit `unsafe`, `ksp-config-lib` ne modifie jamais l'environnement global du processus. La future surface management modifie le fichier d'environnement géré et signale lorsqu'une valeur du processus continue à la shadow.

### Sensibilité

Classes :

```text
Public
Internal
Secret
```

Un secret peut être lu par un consumer runtime qui en a réellement besoin ou par une surface de management explicitement privilégiée. Il n'est pas exposé dans les logs, diagnostics ordinaires ou DTO publics génériques.

Cette séparation est une barrière d'API et de non-divulgation ; l'authentification d'un utilisateur final appartient à l'application.

### Mutation/persistence

`0.1.3` conserve la mutation dans son périmètre, mais uniquement pour les sources Config connues.

La persistence doit être atomique : ancien fichier complet ou nouveau fichier complet, jamais un fichier destination partiel. Les sources gérées sont bornées par un `ConfigRoot` explicite ; une composition ne peut pas référencer un chemin absolu ou sortir de cette racine. Une destination writable qui est un symlink est refusée initialement afin de ne pas remplacer le lien ni suivre implicitement une cible hors frontière Config.

`atomic-write-file` est retenue comme dépendance candidate à auditer au moment de l'introduction réelle.

Le résultat d'une mutation doit distinguer source souhaitée et valeur effective, notamment en présence d'un override process.

### Logging

Config produit :

```text
ResolvedLoggingConfig -> ksp_logging_lib::LoggingSettings
```

L'orchestration possède `LoggingGuard` et décide d'appeler `initialize` ou `reinitialize`. Dans `0.1.3`, le harness d’intégration possède localement guard + session Config ; dans `0.1.4`, ce sera l’état backend de `ksp-app-config-desk`. Config ne possède jamais le guard et n'introduit pas de singleton global.

## Dépendances candidates auditées

Aucune dépendance ajoutée dans `pre.001`.

Générations candidates à revérifier au moment de l'ajout :

```text
serde              ^1.0
serde_json         ^1.0
jsonschema         ^0.49   default-features = false
atomic-write-file  ^0.3
```

Le plan rejette initialement toute dépendance Config à Tokio, Tauri, TS-RS, watcher filesystem, `anyhow` ou `thiserror`.

## Découpage prévu

```text
pre.001  audit + brainstorming + plan
pre.002  crate foundation + erreurs + modèles source
pre.003  schemas + logging.config.json
pre.004  composition + profils
pre.005  environnement + sensibilité
pre.006  adapter Logging + lifecycle integration
pre.007  management + persistence atomique
pre.008  ownership audits + robustesse
pre.009  validation finale + docs/cleanup + prompt 0.1.4
```

Le découpage reste souple.

## Fichiers ajoutés

- `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`
- `deltas/0.1.3/pre.001.md`

## Fichiers modifiés

- `Cargo.toml`
- `ROADMAP.md`
- `docs/plans/000-README.md`
- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`

## Fichiers supprimés

Aucun.

## Hors scope confirmé

- application desktop Config ;
- Tauri/TS-RS dans Config ;
- Wallet ;
- Store/PostgreSQL ;
- RPC/WS/provider ;
- Program/decoder/execution ;
- workers/jobs/pipelines ;
- watcher filesystem ;
- service distribué Config ;
- secrets manager distant ;
- configuration de composants inexistants.

## Validations de livraison

Ce delta ne modifie aucun source Rust mais modifie la version Cargo.

Les quatre validations Cargo applicables ont été tentées dans l'environnement de préparation :

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
```

Résultat : **non exécutées**, car cet environnement ne fournit pas l'exécutable `cargo` (`cargo: command not found`). Aucune de ces commandes n'est déclarée réussie. Elles restent à exécuter sur le workspace utilisateur avant validation/commit du delta.

Les commandes suivantes ne sont pas applicables au `pre.001`, car la crate `ksp-config-lib` n'est volontairement pas encore créée :

```bash
cargo tree -p ksp-config-lib
cargo tree -p ksp-config-lib -d
cargo tree -p ksp-config-lib -e features
```

Contrôles statiques réellement exécutés :

- liens Markdown locaux des fichiers modifiés/ajoutés : résolus ;
- fences Markdown du plan et du delta : équilibrées ;
- diff `[workspace.dependencies]` contre `v0.1.2` : aucun changement ;
- `Cargo.lock` : absent ;
- `target/` : absent ;
- `crates/ksp-config-lib/` : absent, conformément au scope `pre.001` ;
- `config/` runtime : absent, conformément au scope `pre.001` ;
- répertoire/script d'audit dans la base fournie : aucun trouvé au niveau workspace.

Le scan statique de la base confirme également que les usages `tracing*` existants restent dans `ksp-logging-lib`; le seul `std::env` relevé dans la base Rust stable auditée est un `temp_dir()` de test Logging, pas une lecture de variable applicative.