khadhroony-bot3/docs/guides/CONFIGURATION.md

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

# Guide de configuration

## Objectif

La configuration sépare les responsabilités Solana partagées des choix propres aux binaires. Les documents spécialisés sont autonomes grâce à leurs valeurs globales et à leur `default_profile`; une composition de binaire ne fournit que les overrides nécessaires.

## Documents actifs

Composition actuelle :

- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop.

Documents partagés :

- `config/logging.config.json` ;
- `config/transport.config.json` ;
- `config/listeners.config.json` ;
- `config/store.config.json` ;
- `config/wallet.config.json` ;
- `config/execution.config.json`.

Chaque document possède un exemple sous `config/exemples/` avec un nom `example.*.config.json`. Les schémas correspondants résident sous `config/schemas/`.

`.env`, ou le fichier sélectionné par `KS_ENV_FILE`, fournit les valeurs non versionnées.

## Defaults partagés

Chaque document spécialisé définit un `default_profile`. Lorsqu'aucune composition n'est fournie, `ks-config` combine les defaults propres à transport, listeners, store, wallet et execution ; les noms de ces profils n'ont pas besoin d'être identiques. Une composition sélectionne des sources et profils, mais ne duplique pas des paramètres arbitraires : les overrides fins restent dans le schéma propriétaire et les globals explicitement configurables passent par leur variable d'environnement dédiée.

Cette règle permet à une bibliothèque, un scénario ou un futur worker d'utiliser une configuration cohérente sans créer un fichier de composition uniquement pour répéter les choix par défaut.

## Composition d'un binaire

Une composition définit :

1. son `active_profile` applicatif ;
2. les chemins des documents partagés ;
3. les éventuels overrides de profils spécialisés ;
4. les paramètres propres au binaire qui ne relèvent pas d'un document partagé.

Exemple conceptuel :

```text
kb-app-demo-desktop.default.config.json
    sources.logging   -> config/logging.config.json
    sources.transport -> config/transport.config.json
    sources.listeners -> config/listeners.config.json
    sources.store     -> config/store.config.json
    sources.wallet    -> config/wallet.config.json
    sources.execution -> config/execution.config.json

    profile local_devnet
        aucun override -> defaults des documents partagés

    profile mainnet_research
        logging_profile   -> mainnet_research
        transport_profile -> mainnet_research
        listeners_profile -> mainnet_research
        store_profile     -> mainnet_research
        wallet_profile    -> mainnet_research
        execution_profile -> mainnet_research
```

`ks-config` charge les fichiers référencés, valide leurs schémas/types et refuse une composition qui référence un profil inexistant.

## Desktop

Le chemin de composition du desktop peut être remplacé par :

```text
KB_APP_DEMO_DESKTOP_CONFIG_PATH
```

Le logging conserve aussi l'override opérationnel :

```text
KS_LOGGING_CONFIG_PATH
```

## Scénarios Devnet

Par défaut, `ks-pipeline-demo-scenarios` utilise directement les defaults des documents partagés. Il n'existe plus de `config/ks-pipeline-demo-scenarios.default.config.json` obligatoire.

Les overrides opérateur restent :

```text
KS_DEVNET_CONFIG_PATH   # composition explicite facultative
KS_DEVNET_PROFILE       # sélection d'un profil runtime compatible Devnet
```

## Valeurs hors profils

Les paramètres globaux ne doivent pas être dupliqués dans chaque profil.

### Logging

```text
logs_directory = ${KS_LOGS_DIRECTORY:-logs}
```

Les chemins de fichiers des targets sont relatifs à cette racine lorsqu'ils ne sont pas absolus.

### Wallet

```text
wallets_directory = ${KS_WALLETS_DIRECTORY:-wallets}
```

Chaque profil wallet ne contient plus qu'un chemin relatif et ses paramètres d'identité/persistance.

## Transport WebSocket

Les paramètres communs d'un type d'endpoint WebSocket sont définis dans `ws_endpoint_defaults`. Chaque endpoint choisit une classe de defaults et peut écraser individuellement :

- `connect_timeout_ms` ;
- `request_timeout_ms` ;
- `unsubscribe_timeout_ms` ;
- `write_channel_capacity` ;
- `event_channel_capacity` ;
- `auto_reconnect`.

Les classes actuelles couvrent le RPC WS standard et le RPC WS à capacité plus élevée. Une future surface Helius avancée devra avoir son propre contrat/default lorsqu'elle sera réellement implémentée.

## Store

`store.config.json` porte les paramètres PostgreSQL/SQLite. Ce déplacement ne change aucune table ni migration SQL ; la normalisation SQL reste réservée à `0.5.3`.

## Wallet et politique d'exécution

Les propriétés de stockage/identité du wallet appartiennent à `wallet.config.json`. Un profil peut définir le champ optionnel `wallet_alias` pour sélectionner un wallet natif persistant par alias. Son omission ou `null` signifie qu’aucun wallet persistant n’est sélectionné. Le champ est non sensible et ne contient jamais de mot de passe, de keypair ou de chemin de fichier individuel.

Les autorisations :

```text
localnet_send_enabled
devnet_send_enabled
testnet_send_enabled
mainnet_send_enabled
```

appartiennent à `execution.config.json`, avec les limites de dépense, frais, simulation et confirmation. Un wallet sait signer ; la politique d'exécution décide si une soumission est autorisée.

## Contrat runtime transitoire

`ks-config` reconstruit encore `AppConfig/ProfileConfig` comme projection runtime transitoire afin de préserver les consommateurs backend existants. Il s'agit d'une projection runtime, pas d'un document source ni d'une surface de sortie. Depuis `0.5.1`, ces contrats et les documents spécialisés susceptibles de contenir des valeurs résolues ne dérivent ni `serde::Serialize` ni `Debug`.

Les fixtures de compatibilité sont sous `test-fixtures/config/`. Elles ne doivent pas être chargées en production.

## Frontière publique et diagnostic

Une application ne transmet jamais `AppConfig/ProfileConfig` directement. Elle construit :

- une projection publique explicitement typée, limitée aux champs autorisés ;
- un diagnostic borné contenant au plus des états tels que `configured`/`missing` pour les URLs, DSN et chemins sensibles ;
- aucune projection construite par sérialisation du runtime suivie d'un masquage a posteriori.

La sensibilité suit `Secret > Internal > Public`. Une valeur composée hérite de la sensibilité la plus forte des placeholders qu'elle contient ; une URL incorporant `${KS_SECRET_HELIUS_API_KEY}` est donc secrète même si son champ final est simplement `url`.

La section `application` d'une composition est opaque à `ks-config`. Le desktop la valide avec son schéma `config/schemas/kb-app-demo-desktop.application.config.schema.json`; un futur worker pourra posséder son propre schéma sans modifier `ks-config`.

## Frontière TS-RS

Depuis `0.5.1`, `ks-config` et `ks-lib` ne dépendent plus de TS-RS et ne possèdent plus de bindings TypeScript générés. Les DTO traversant Tauri appartiennent à `kb-app-demo-desktop` ou à la future application concernée. Une exception dans une crate `ks-*` exige un contrat TypeScript générique indépendant de Tauri explicitement justifié et audité.

## Étape suivante

`0.5.1` clôt cette architecture de configuration. Les changements fonctionnels de wallet appartiennent à `0.5.2`, la normalisation SQL à `0.5.3` et l’audit final des scénarios/exécuteurs à `0.5.4`.

## Invariants

- aucun secret réel dans les fichiers versionnés ;
- tous les schémas actifs sous `config/schemas/` ;
- aucun retour au fichier monolithique `app.config.json` ;
- les valeurs globales restent hors profils ;
- une composition appartient à son binaire ;
- un document spécialisé reste indépendant des binaires qui le consomment ;
- `ks-config` valide les références mais ne maintient pas une liste fermée de futurs workers/applications.