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

# Guide de configuration

## Objectif

La configuration est organisée autour de compositions propres aux binaires et de documents spécialisés réutilisables. Un binaire choisit les fichiers partagés et les profils dont il a besoin au lieu de recopier une configuration monolithique.

## Fichiers actifs

Compositions :

- `config/kb-app-demo-desktop.default.config.json` : composition par défaut du desktop ;
- `config/ks-pipeline-demo-scenarios.default.config.json` : composition par défaut du CLI/scénarios.

Documents partagés :

- `config/logging.config.json` ;
- `config/transport.config.json` ;
- `config/listeners.config.json`.

Exemples :

- `config/example.kb-app-demo-desktop.default.config.json` ;
- `config/example.logging.config.json` ;
- `config/example.transport.config.json` ;
- `config/example.listeners.config.json`.

Schémas :

- `config/schemas/composition.config.schema.json` ;
- `config/schemas/logging.config.schema.json` ;
- `config/schemas/transport.config.schema.json` ;
- `config/schemas/listeners.config.schema.json` ;
- `config/schemas/resolved.app.config.schema.json` pour le contrat runtime reconstruit.

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

## Composition d'un binaire

Une composition définit :

1. son `active_profile` ;
2. les chemins des documents partagés ;
3. pour chaque profil, le `logging_profile`, `transport_profile` et `listeners_profile` à sélectionner ;
4. temporairement, les sections qui n'ont pas encore leur document spécialisé.

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

    profile mainnet_research
        logging_profile   -> mainnet_research
        transport_profile -> mainnet_research
        listeners_profile -> mainnet_research
```

Les `active_profile` propres aux documents partagés restent utiles lorsqu'ils sont chargés seuls. Dans une composition, la référence explicite du binaire prime.

## Desktop

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

```text
KB_APP_DEMO_DESKTOP_CONFIG_PATH
```

Le logging conserve l'override opérationnel :

```text
KS_LOGGING_CONFIG_PATH
```

Sans cet override, le desktop utilise le chemin logging déclaré par sa composition.

## Scénarios Devnet

Les scénarios opt-in utilisent :

```text
KS_DEVNET_CONFIG_PATH
KS_DEVNET_PROFILE
```

`KS_DEVNET_CONFIG_PATH` désigne désormais un fichier de composition. Sans override, les scénarios utilisent `config/ks-pipeline-demo-scenarios.default.config.json`.

## Transport

`transport.config.json` possède les endpoints HTTP et WebSocket ainsi que leurs rôles et limites. Le profil transport peut être consommé directement par `ks-onchain-transport` sans dépendre d'un profil applicatif complet.

Cela prépare les futurs workers : un worker de capture pourra sélectionner un profil transport différent du desktop tout en partageant le même document.

## Listeners

`listeners.config.json` contient les déclarations de subscriptions par logs, programme et compte. Un profil listeners peut être associé à n'importe quel profil transport compatible par le fichier de composition du consommateur.

La séparation évite de recopier les listes de `program_id` et les filtres lorsque plusieurs binaires observent la même surface Solana.

## Logging

`logging.config.json` appartient à `ks-logging`. Une composition référence son fichier et son profil, mais les types et validations logging ne reviennent pas dans `ks-config`.

## Contrat runtime résolu

Pendant la migration `0.5.1`, `ks-config` reconstruit encore un `AppConfig/ProfileConfig` contenant les sections nécessaires aux consommateurs existants. Ce contrat est une projection runtime, pas une configuration source.

Les tests de compatibilité utilisent les fixtures sous `test-fixtures/config/`. Aucun binaire ne doit charger ces fixtures en production.

## Étapes suivantes

Le prochain split doit extraire :

- database vers le document store ;
- `logs_directory` vers logging ;
- `wallets_directory`, le stockage wallet et les paramètres de wallet vers un document wallet ;
- les permissions `*_send_enabled` du wallet vers la politique execution ;
- execution ;
- configuration spécifique au desktop.

Après cette étape seulement, les DTO publics, diagnostics et règles de camouflage seront construits sur les nouvelles frontières.

## 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` ;
- un fichier de composition appartient à son binaire ;
- un document spécialisé reste indépendant des binaires qui le consomment ;
- `ks-config` fournit les mécanismes partagés sans enregistrer une liste fermée de workers/applications.