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`.

docs/guides/LOGGING.md

@@ -1,34 +1,43 @@
 <!-- file: docs/guides/LOGGING.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Guide de logging et tracing
 
 ## Objectif
 
-`ks-logging` initialise les routes de tracing définies par la configuration et conserve les guards nécessaires à leur durée de vie.
+`ks-logging` possède désormais le contrat logging, son document de profils, son schéma JSON et l’initialisation runtime `tracing`.
 
 ## Flux de démarrage
 
-1. charger et valider la configuration avec `ks-config` ;
-2. construire `LoggingConfig` ;
+1. charger `config/logging.config.json` avec `ks_logging::read_logging_json_file_with_environment` ;
+2. sélectionner le profil avec `ks_logging::active_logging_profile` ;
 3. appeler `ks_logging::init_logging` une seule fois ;
 4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
 5. émettre les événements avec des targets canoniques.
 
 ```rust
-let guard = match ks_logging::init_logging(&config.logging) {
+let document = 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 config = match ks_logging::active_logging_profile(&document) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+let guard = match ks_logging::init_logging(config) {
     std::result::Result::Ok(value) => value,
     std::result::Result::Err(error) => return std::result::Result::Err(error),
 };
-
-tracing::info!(
-    target: ks_logging::tracing_target(),
-    routes = guard.route_count(),
-    "logging initialized"
-);
 ```
 
-## Routes
+Le profil logging est sélectionné indépendamment du profil général de `app.config.json`.
+
+## Contrat JSON
+
+Le schéma est `config/schemas/logging.config.schema.json`. Les exemples sont `config/logging.config.json` pour la configuration runtime de référence et `config/example.logging.config.json` pour un exemple minimal.
 
 Une route définit notamment :
 
@@ -52,28 +61,28 @@ ks-onchain-transport.http
 ks-lib-executor.spl.token-2022
 ks-lib-materializer.compliance.audit
 ks-lib-materializer.token.accounts
-ks-lib-materializer.transaction.annotations
 ```
 
-Pour un matérialisateur, la target de tracing est l’identité runtime `ks-lib-materializer.<domain>[.<subsystem>]`. Elle reste distincte du `processorName` persisté `materializer.<domain>[.<subsystem>]`, qui ne doit pas être utilisé comme target de logs.
-
-Une nouvelle target doit être ajoutée selon `docs/OPERATION_NAMING_CONVENTION.md` et les règles Khadhroony.
+Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.
 
 ## Frontend desktop
 
-Les fenêtres Tauri utilisent la permission tracing prévue par leurs capabilities. Les logs frontend sont adaptés vers le backend sans permettre au frontend de choisir arbitrairement une target sensible.
+Le desktop charge les documents app et logging séparément. Il ne convertit plus un type `ks_config::LoggingConfig` vers `ks_logging::LoggingConfig` : le type runtime est possédé directement par `ks-logging`.
+
+La surface publique de diagnostic/configuration reste volontairement inchangée jusqu’à `0.5.1-pre.006`, qui supprimera l’exposition des configurations résolues complètes.
 
 ## Diagnostic
 
-- vérifier les routes actives via `route_names()` ;
+- vérifier `KS_LOGGING_CONFIG_PATH` si le fichier par défaut n’est pas utilisé ;
+- vérifier le profil logging actif indépendamment du profil app ;
+- valider le document contre son schéma ;
 - confirmer le niveau global et les filtres spécifiques ;
-- vérifier le chemin et les permissions d’une route fichier ;
-- vérifier que le guard n’est pas détruit prématurément ;
+- vérifier les chemins et permissions des routes fichier ;
 - ne pas réinitialiser le subscriber global pendant l’exécution.
 
 ## Références
 
 - `ks-logging/README.md` ;
 - `ks-logging/USAGE.md` ;
-- `ks-config/USAGE.md` ;
-- `docs/architecture/ARCHITECTURE.md`.
+- `config/README.md` ;
+- `docs/OPERATION_NAMING_CONVENTION.md`.