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

Delta 0.1.3-pre.001

Base requise

Release stable/taguée attendue :

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 :

docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md

Version Cargo

workspace.package.version passe de :

0.1.2

à :

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 :

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

Error
ErrorCode
ErrorContext
Result<T>

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

LoggingSettings
LoggingGuard
initialize(...)
reinitialize(...)

La direction retenue est :

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 :

config/logging.config.json
config/environment.env

Schémas :

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

Exemples :

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 :

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

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 :

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

Environnement

Namespaces :

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 :

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 :

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 :

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 :

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

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 :

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 :

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.