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

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

# Delta 0.1.3-pre.003

## Base requise

Livraison précédente validée :

```text
0.1.3-pre.002-fix.001
```

Version technique de cette base :

```text
workspace.package.version = "0.1.3-pre.2.fix.1"
Cargo.toml header version = 42
```

Les validations utilisateur de cette base sont propres : formatage, check, Clippy sans warning, tests workspace et vues `cargo tree` de `ksp-config-lib`.

## Objet de pre.003

Cette tranche introduit uniquement le registre logique des fichiers possédés par Config et le remplacement bootstrap de leurs noms physiques.

Elle ajoute :

- `ConfigFileId` ;
- `ConfigFileKind` ;
- `ConfigFileDescriptor` ;
- `ConfigFileRegistry` ;
- les mappings par défaut actuellement connus ;
- `--filemap=<file_id>=<filename>` répétable ;
- l'override programmatique équivalent ;
- la résolution d'un `file_id` sous `cfgpath` ou `schemapath` ;
- les validations d'identité, d'unicité, de kind et de filename relatif ;
- les erreurs Config et tests strictement nécessaires à cette surface.

Elle n'ajoute pas encore :

- `serde`, `serde_json` ou `jsonschema` ;
- lecture ou écriture JSON ;
- fichiers runtime `config/` ;
- validation de schema ;
- profils ou composites ;
- `.env` ou environnement du processus ;
- interpolation `${...}` ;
- secrets ;
- persistence ;
- modification de `ksp-logging-lib`.

## Identité logique et mappings par défaut

Les deux seuls fichiers que Config connaît actuellement sont :

```text
cfg.std.logging       -> std.logging.json
schema.std.logging    -> std.logging.schema.json
```

Les fichiers physiques ne sont pas encore créés ni lus dans cette tranche. Leur identité logique est introduite maintenant afin que les futurs consumers et composites ne dépendent jamais directement de leur filename.

Les constantes publiques associées sont :

```text
FILE_ID_STD_LOGGING
FILE_ID_SCHEMA_STD_LOGGING
DEFAULT_STD_LOGGING_FILENAME
DEFAULT_STD_LOGGING_SCHEMA_FILENAME
```

## `ConfigFileId`

`ConfigFileId` est une valeur typée possédée par Config.

La syntaxe initiale accepte uniquement :

- ASCII minuscule ;
- chiffres ;
- `_` et `-` dans les segments ;
- `.` comme séparateur de segments ;
- aucun segment vide.

Exemples valides :

```text
cfg.std.logging
schema.std.logging
cfg.composite.ksp-app-wallet-desk
```

Exemples refusés :

```text
CFG.std.logging
cfg..logging
cfg/logging
.cfg.logging
```

## Kind et racines

`ConfigFileKind` distingue :

```text
Config -> ConfigBootstrapOptions::cfg_path()
Schema -> ConfigBootstrapOptions::schema_path()
```

Un descriptor `Config` doit appartenir au namespace `cfg.*` et un descriptor `Schema` au namespace `schema.*`.

Cette relation est fixée au registre ; un override de filename ne peut jamais changer le kind ni déplacer un schema sous `cfgpath` ou un document Config sous `schemapath`.

## Override CLI `--filemap`

Le contrat initial est volontairement atomique :

```text
--filemap=<file_id>=<filename>
```

Exemples :

```text
--filemap=cfg.std.logging=my.logging.json
--filemap=schema.std.logging=my.logging.schema.json
```

L'argument est répétable. Lorsque le même `file_id` est fourni plusieurs fois, le dernier filename gagne.

Les arguments étrangers sont ignorés, comme pour le bootstrap des roots.

La forme séparée suivante n'est pas supportée :

```text
--filemap cfg.std.logging=my.logging.json
```

Un `--filemap` sans valeur inline est donc une erreur de mapping plutôt qu'un argument ignoré.

Un override ne peut pas enregistrer un nouveau `file_id`. Le `file_id` doit déjà appartenir au registre KSP ; seul son filename physique est remplaçable.

## Filenames et confinement lexical

Un filename mappé :

- doit être non vide ;
- doit être relatif ;
- ne peut contenir ni `.` ni `..` comme composants ;
- ne peut contenir de root/prefix absolu ;
- peut contenir des sous-répertoires relatifs normaux.

Ainsi :

```text
std.logging.json
profiles/my.logging.json
```

sont acceptés, tandis que :

```text
../std.logging.json
./std.logging.json
/opt/ksp/std.logging.json
```

sont refusés.

Cette tranche garantit le confinement **lexical** sous `cfgpath`/`schemapath`. Les garanties filesystem/canonicalisation/symlink nécessaires à la lecture et à la persistence seront ajoutées avec les opérations I/O correspondantes, pas simulées avant leur existence.

## API publique

La surface publique ajoute notamment :

```text
ConfigFileId::new(...)
ConfigFileId::as_str()

ConfigFileRegistry::defaults()
ConfigFileRegistry::from_args(...)
ConfigFileRegistry::descriptor(...)
ConfigFileRegistry::resolve_path(...)
ConfigFileRegistry::with_filename_override(...)
```

`resolve_path(...)` ne lit rien : il sélectionne simplement la bonne root bootstrap selon le kind et y joint le filename validé.

## Erreurs Config ajoutées

Les codes restent possédés par `ksp-config-lib` :

```text
config.file_id_invalid
config.file_id_unknown
config.file_id_duplicate
config.file_mapping_invalid
```

Ils réutilisent toujours `ksp_core_lib::Error`, `ErrorCode` et `Result<T>` sans introduire de connaissance Config dans Core.

## Dépendances

Aucune dépendance ajoutée ou modifiée.

`ksp-config-lib` dépend toujours directement uniquement de :

```text
ksp-core-lib
```

## Tests ajoutés

Les tests unitaires couvrent notamment :

- les deux mappings par défaut ;
- la séparation `cfgpath` / `schemapath` par kind ;
- l'override CLI ;
- la règle du dernier override ;
- l'override programmatique ;
- la conservation du `file_id` et du kind ;
- le refus d'un ID inconnu ;
- la syntaxe des IDs ;
- le refus des paths absolus et traversants ;
- le refus des arguments `--filemap` mal formés ;
- le refus des IDs dupliqués ;
- la cohérence namespace/kind.

Le test d'intégration public vérifie également que le registre, les deux IDs Logging, les overrides de document/schema et leur résolution sont consommables depuis le crate-root.

## Version technique

La prerelease devient :

```text
workspace.package.version = "0.1.3-pre.3"
```

Le manifest racine devient :

```text
# version: 43
```

Le plan Config devient :

```text
<!-- version: 6 -->
```

## Fichiers ajoutés

```text
crates/ksp-config-lib/src/registry.rs
crates/ksp-config-lib/unit_tests/registry.rs
deltas/0.1.3/pre.003.md
```

## Fichiers modifiés

```text
Cargo.toml
crates/ksp-config-lib/src/error.rs
crates/ksp-config-lib/src/lib.rs
crates/ksp-config-lib/tests/public_api.rs
docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
```

## Fichiers supprimés

Aucun.

## Validations utilisateur attendues

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
cargo tree -p ksp-config-lib
cargo tree -p ksp-config-lib -d
cargo tree -p ksp-config-lib -e features
```

Exécuter également tout script d'audit réellement présent dans le dépôt utilisateur.

## Validations exécutées avant livraison

L'environnement de génération ne fournit pas `cargo`, `rustc` ou `rustfmt`; aucune validation Cargo n'est donc déclarée réussie sur `pre.003` avant les tests utilisateur.

Les contrôles statiques de préparation vérifient :

- headers `file:` / `version:` ;
- version Cargo `0.1.3-pre.3` ;
- aucune ligne Rust supérieure à 160 colonnes avant formatage ;
- aucun `unsafe`, `unwrap`, `expect`, `panic!` ou opérateur `?` dans le nouveau code ;
- aucune lecture de variable applicative ;
- aucune dépendance externe nouvelle ;
- aucune surface JSON/schema I/O, `.env` ou Logging ouverte ;
- delta limité aux fichiers ajoutés/modifiés de cette tranche.

## Suite après validation

Si `pre.003` est validée, la tranche suivante reste :

```text
0.1.3-pre.004 — ksp-logging-lib : modèle public multi-output
```

Elle modifiera les contrats/settings Logging avant que `std.logging.schema.json` ne soit figé en `pre.006`.