0.5.1-pre.005

docs/guides/CONFIGURATION.md

@@ -1,85 +1,95 @@
 <!-- file: docs/guides/CONFIGURATION.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Guide de configuration
 
 ## Objectif
 
-Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste `ks-config/USAGE.md`.
+Ce guide décrit le chargement des documents de configuration après leur séparation. La référence d’API générale reste `ks-config/USAGE.md` et la configuration logging appartient à `ks-logging`.
 
 ## Fichiers actifs
 
-- `config/example.config.json` : exemple utilisateur complet ;
-- `config/schema.config.json` : contrat JSON formel ;
+- `config/app.config.json` : configuration générale chargée par défaut ;
+- `config/logging.config.json` : configuration logging chargée par défaut ;
+- `config/example.app.config.json` et `config/example.logging.config.json` : exemples minimaux conformes ;
+- `config/schemas/app.config.schema.json` : schéma général ;
+- `config/schemas/logging.config.schema.json` : schéma logging ;
 - `.env`, ou le fichier sélectionné par `KS_ENV_FILE` : valeurs d’environnement non versionnées ;
-- `.env.example` : noms de variables attendues sans secrets.
+- `.env.example` : noms de variables attendues sans secrets réels.
 
-Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.
+`KS_CONFIG_PATH` et `KS_LOGGING_CONFIG_PATH` permettent de remplacer indépendamment les deux chemins par défaut.
 
-## Séquence de chargement
+## Configuration générale
 
-L’API recommandée est `read_config_json_file_with_environment`. Elle :
+L’API recommandée reste `ks_config::read_config_json_file_with_environment`. Elle :
 
-1. charge `.env`, ou le fichier explicitement sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
-2. lit le JSON ;
-3. résout les placeholders namespacés `${KS_*}` / `${KB_*}` et les fallbacks éventuels ;
-4. valide le schéma JSON ;
-5. désérialise les types de configuration et applique les invariants métier ;
-6. laisse ensuite `active_profile` sélectionner le profil actif.
-
-## Exemple opérateur
+1. charge `.env`, ou le fichier sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
+2. lit le JSON général ;
+3. résout les placeholders `${KS_*}` / `${KB_*}` ;
+4. valide `config/schemas/app.config.schema.json` ;
+5. désérialise `AppConfig` et applique les invariants métier ;
+6. laisse `active_profile` sélectionner le profil applicatif actif.
 
 ```rust
 let config = match ks_config::read_config_json_file_with_environment(
-    std::path::Path::new("config/example.config.json"),
+    std::path::Path::new("config/app.config.json"),
     std::path::Path::new("."),
 ) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
-
 let profile = match ks_config::active_profile(&config) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
-
-println!("active profile={}", profile.name);
 ```
 
+Le profil général ne contient plus de bloc `logging`.
+
+## Configuration logging
+
+`ks_logging::read_logging_json_file_with_environment` charge séparément le document logging et `ks_logging::active_logging_profile` sélectionne son profil actif.
+
+```rust
+let logging = match ks_logging::read_logging_json_file_with_environment(
+    std::path::Path::new("config/logging.config.json"),
+    std::path::Path::new("."),
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+let logging_profile = match ks_logging::active_logging_profile(&logging) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.
+
 ## Invariants
 
-- aucun secret ne doit être ajouté à l’exemple versionné ;
-- les placeholders non résolus doivent provoquer un diagnostic explicite ;
-- le schéma embarqué et `config/schema.config.json` doivent rester identiques ;
-- tant que `0.5.1-pre.006` n’a pas introduit les DTO publics sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle ;
-- les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
-
-## Quotas HTTP cumulés
-
-Les limites HTTP sont déclarées par rôle, mais les quotas d’un endpoint public s’appliquent généralement à l’endpoint ou à l’adresse IP entière. Pour un endpoint unique, il faut donc considérer au minimum :
-
-- la somme des `requests_per_second` de tous les rôles actifs ;
-- la somme des bursts pouvant partir dans la même fenêtre ;
-- la limite propre à une méthode RPC répétée ;
-- les autres processus utilisant la même IP ou le même fournisseur.
-
-Le profil public Devnet de l’exemple utilise `3 r/s` pour `http_queries` et `1 r/s` pour `http_transactions`. Un profil privé ou payant peut utiliser d’autres valeurs, mais elles doivent suivre le contrat réel du fournisseur.
+- aucun secret réel ne doit être ajouté aux fichiers versionnés ;
+- les placeholders non résolus doivent rester détectables ;
+- chaque schéma embarqué doit rester identique au fichier sous `config/schemas/` ;
+- les profils applicatifs et logging sont validés indépendamment ;
+- `ks-config` ne possède plus de types logging ;
+- tant que `0.5.1-pre.006` n’a pas introduit les DTO sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle.
 
 ## Diagnostic
 
 Pour isoler une erreur :
 
-1. afficher la liste des fichiers d’environnement chargés ;
-2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
-3. valider le schéma ;
-4. valider le modèle typé ;
-5. vérifier le profil actif ;
-6. vérifier les rôles HTTP, WebSocket, stockage et logging.
+1. vérifier le fichier d’environnement chargé ;
+2. vérifier séparément les chemins app et logging ;
+3. valider chaque document contre son schéma ;
+4. vérifier son `active_profile` ;
+5. vérifier ensuite les rôles HTTP/WebSocket, stockage ou routes logging concernés.
+
+Ne jamais écrire dans les logs le JSON résolu complet s’il contient une valeur issue de `KS_SECRET_*` ou `KB_SECRET_*`.
 
 ## Références
 
-- `ks-config/README.md` ;
-- `ks-config/USAGE.md` ;
-- `ks-config/TODO.md` ;
+- `ks-config/README.md` et `ks-config/USAGE.md` ;
+- `ks-logging/README.md` et `ks-logging/USAGE.md` ;
 - `config/README.md` ;
-- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.
+- `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`.