<!-- file: docs/guides/CONFIGURATION.md -->
<!-- version: 4 -->

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

## Fichiers actifs

- `config/example.config.json` : exemple utilisateur complet ;
- `config/schema.config.json` : contrat JSON formel ;
- `.env`, ou le fichier sélectionné par `KS_ENV_FILE` : valeurs d’environnement non versionnées ;
- `.env.example` : noms de variables attendues sans secrets.

Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.

## Séquence de chargement

L’API recommandée est `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

```rust
let config = match ks_config::read_config_json_file_with_environment(
    std::path::Path::new("config/example.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);
```

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

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

## Références

- `ks-config/README.md` ;
- `ks-config/USAGE.md` ;
- `ks-config/TODO.md` ;
- `config/README.md` ;
- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.