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

Delta 0.1.3-pre.003

Base requise

Livraison précédente validée :

0.1.3-pre.002-fix.001

Version technique de cette base :

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 :

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 :

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 :

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

Exemples refusés :

CFG.std.logging
cfg..logging
cfg/logging
.cfg.logging

Kind et racines

ConfigFileKind distingue :

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 :

--filemap=<file_id>=<filename>

Exemples :

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

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

std.logging.json
profiles/my.logging.json

sont acceptés, tandis que :

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

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 :

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 :

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 :

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

Le manifest racine devient :

# version: 43

Le plan Config devient :

<!-- version: 6 -->

Fichiers ajoutés

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

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

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 :

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.