@@ -63,19 +63,25 @@ La classification d'une valeur sensible doit survivre à la substitution. Une ch
## 5. Configuration source, runtime et publique
La restructuration `0.5.1`doit séparer au minimum :
La restructuration `0.5.1`utilise des compositions propres aux binaires et des documents spécialisés partagés :
-la configuration généraliste dans `config/app.config.json`, avec son schéma sous `config/schemas/app.config.schema.json` ;
-la configuration logging dans `config/logging.config.json`, avec son schéma sous `config/schemas/logging.config.schema.json` et des profils logging sélectionnables indépendamment des profils réseau/applicatifs ;
-des exemples conformes mais non chargés par défaut sous `config/example.app.config.json` et `config/example.logging.config.json`.
-`config/kb-app-demo-desktop.default.config.json` compose les besoins du desktop ;
-`config/ks-pipeline-demo-scenarios.default.config.json` compose les besoins du CLI/scénarios ;
-`config/logging.config.json` appartient à `ks-logging` ;
-`config/transport.config.json` contient les profils HTTP/WebSocket partagés ;
-`config/listeners.config.json` contient les profils de subscriptions Solana partagés ;
- tous les schémas actifs résident sous `config/schemas/`.
D'autres documents spécialisés ne sont créés que si l'audit démontre une responsabilité, un cycle de vie ou une validation réellement indépendants.
Le fichier de composition sélectionne explicitement les profils spécialisés. Un nouveau worker ou binaire doit pouvoir fournir son propre `<binary>.default.config.json` et une configuration dédiée sans modifier `ks-config` pour enregistrer son existence.
`AppConfig/ProfileConfig` reste temporairement un contrat runtime résolu afin de préserver les consommateurs pendant la migration. Il n'est plus un document source chargé directement ; son schéma de compatibilité est `config/schemas/resolved.app.config.schema.json` et ses fixtures sont sous `test-fixtures/config/`.
La conception doit distinguer :
1. la représentation source, qui peut contenir des références `${KS_*}` ou `${KB_*}` selon le propriétaire du contrat ;
2. la représentation runtime résolue, qui peut porter des secrets ;
3. la représentation publique/diagnostique, construite explicitement et incapable d'exposer une valeur secrète résolue.
1. la représentation source, composée de documents indépendants pouvant contenir des références `${KS_*}` ou `${KB_*}` selon le propriétaire du contrat ;
2. la composition propre au binaire, qui choisit les documents et profils ;
3. la représentation runtime résolue, qui peut porter des secrets ;
4. la représentation publique/diagnostique, construite explicitement et incapable d'exposer une valeur secrète résolue.
Une configuration runtime complète ne doit jamais être sérialisée puis « nettoyée » après coup pour produire un payload public.
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`.
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
-`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/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
```
Le profil général ne contient plus de bloc `logging`.
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.
## Configuration logging
## Desktop
`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.
Le chemin de composition du desktop peut être remplacé par :
Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.
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 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. 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` et `ks-config/USAGE.md` ;
-`ks-logging/README.md` et `ks-logging/USAGE.md` ;
@@ -33,7 +33,7 @@ let guard = match ks_logging::init_logging(config) {
};
```
Le profil logging est sélectionné indépendamment du profil général de `app.config.json`.
Le document logging reste indépendant de la composition binaire. Une composition `<binary>.default.config.json` sélectionne explicitement le profil logging qu’elle veut utiliser ; le `active_profile` propre à `logging.config.json` reste disponible pour les consommateurs autonomes.
`kb-app-demo-desktop` est adapté en dernier, mais garde son package, son répertoire et ses identifiants applicatifs.
@@ -58,18 +58,18 @@ bin : kb-pipeline-demo-scenarios-cli -> ks-pipeline-demo-scenarios-cli
Les valeurs suivantes sont des métriques d'orientation sur les fichiers actifs, hors archives et artefacts générés. Elles montrent qu'un renommage massif en une seule opération serait difficile à diagnostiquer.
La cible `KB_APP_DEMO_DESKTOP_CONFIG_PATH` remplace la transition `KS_CONFIG_PATH` de `pre.004` : une composition appartient au binaire qui la charge, alors que les documents qu’elle référence restent possédés par les crates `ks-*`.
## 8. Décomposition des documents de configuration
L'audit `0.5.0` a confirmé une duplication importante : chaque profil généraliste transporte un bloc logging volumineux. La cible minimale devient :
Le split `pre.005` a d'abord extrait le logging. L'audit suivant a confirmé que le document applicatif restant mélangeait encore des responsabilités ayant des cycles de vie et des consommateurs distincts. La cible devient donc une composition propre à chaque binaire, complétée par des documents spécialisés partageables.
La convention de composition est :
```text
config/app.config.json
config/logging.config.json
config/example.app.config.json
config/example.logging.config.json
config/schemas/app.config.schema.json
config/schemas/logging.config.schema.json
config/<binary>.default.config.json
```
Les profils applicatifs/réseau et les profils logging sont sélectionnables indépendamment. Un profil `devnet` n'impose donc pas un profil logging `debug`, et `mainnet` n'impose pas mécaniquement un profil logging `release`.
Les premières compositions sont :
Le code duplique actuellement dans `ks-config` et `ks-logging` les concepts :
La migration `pre.005` ferme cette dette : `ks-config` ne définit plus de type logging, `ks-logging` possède le document, le schéma et les types runtime, et le desktop charge les deux fichiers indépendamment. `ks-logging` réutilise uniquement les helpers génériques d’environnement de `ks-config`, sans créer de dépendance inverse.
```text
config/logging.config.json
config/transport.config.json
config/listeners.config.json
```
Aucun troisième document spécialisé n'est créé dans `0.5.1` sans bénéfice de découplage démontré.
avec exemples sous `config/` et schémas source sous `config/schemas/`. Chaque composition sélectionne explicitement les profils logging, transport et listeners qu'elle consomme. Les `active_profile` propres aux documents spécialisés restent des valeurs de repli pour les consommateurs autonomes, mais ne couplent pas les sélections d'un binaire.
`AppConfig/ProfileConfig` demeure provisoirement un **contrat runtime résolu**, reconstruit par `ks-config`, afin de préserver les consommateurs pendant la migration. Son schéma est `config/schemas/resolved.app.config.schema.json` et ses fixtures de test sont sous `test-fixtures/config/`; il ne correspond plus à un document source chargé au démarrage.
`pre.007` doit poursuivre la décomposition de `database/data`, wallet, execution et de la configuration réellement spécifique au desktop. À son terme, une composition doit principalement référencer des documents/profils spécialisés et une configuration dédiée au binaire, sans obliger `ks-config` à enregistrer la liste des futurs workers ou exécutables.
Cette décomposition doit être terminée avant de figer les surfaces `public`/`diagnostic` et la propagation de sensibilité en `pre.008`.
## 9. Source, runtime, public et diagnostic
@@ -630,7 +640,8 @@ Avant chaque changement structurel correspondant, conserver ou ajouter des tests
- l'interdiction des variables de configuration possédées par le workspace hors namespace d'ownership `KS_*` ou `KB_*` ;
- la propagation de sensibilité depuis `KS_SECRET_*` vers les valeurs composées ;
- l'impossibilité pour une sentinelle secrète d'apparaître dans `Debug`, logs, erreurs, payloads Tauri, sérialisation publique ou diagnostic ;
- la validation indépendante de `config/schemas/app.config.schema.json` et `config/schemas/logging.config.schema.json` ;
- la validation indépendante des schémas source de composition, logging, transport et listeners sous `config/schemas/` ;
- la validation du schéma `resolved.app.config.schema.json` uniquement comme contrat runtime transitoire ;
- l'indépendance des profils généralistes et logging ;
- l'absence de duplication structurelle des types logging entre `ks-config` et `ks-logging` ;
- le maintien des contrats publics réellement nécessaires après remplacement des types de configuration exposés.
@@ -670,27 +681,52 @@ Les tests ne doivent pas figer comme comportement légitime la fuite actuelle de
- reporter la propagation de sensibilité et le camouflage effectif après le split config/logging ;
- supprimer les anciens noms une fois la migration vérifiée ;
- étendre l’audit workspace pour refuser la réintroduction de variables applicatives hors `KS_*` / `KB_*` dans le code, `.env.example`, la configuration exemple et le guide opérateur ;
- ne pas encore modifier les DTO publics ni implémenter le camouflage, qui appartiennent à `pre.006`.
- ne pas encore modifier les DTO publics ni implémenter le camouflage, qui appartiennent désormais à `pre.008` après la fin du split des documents.
### `0.5.1-pre.005` — split config/logging
- **implémenté** : `config/app.config.json` et `config/logging.config.json` deviennent les deux documents chargés par défaut ;
- **implémenté** : les schémas sont centralisés sous `config/schemas/app.config.schema.json` et `config/schemas/logging.config.schema.json` ;
- **implémenté** : `example.app.config.json` et `example.logging.config.json` fournissent des exemples minimaux conformes ;
- **implémenté** : les profils logging et généralistes possèdent chacun leur propre `active_profile` ;
- **implémenté** : extraction initiale du logging hors de l’ancien document applicatif monolithique ;
- **implémenté** : centralisation des schémas sous `config/schemas/` ;
- **implémenté** : profils logging indépendants ;
- **implémenté** : `ks-logging` devient propriétaire unique du contrat logging et de sa validation ;
- **implémenté** : le desktop supprime la conversion `ks_config::LoggingConfig` -> `ks_logging::LoggingConfig`.
- **implémenté** : suppression de la conversion `ks_config::LoggingConfig` -> `ks_logging::LoggingConfig`.
### `0.5.1-pre.006` — surfaces publiques sûres
### `0.5.1-pre.006` — composition binaire + transport + listeners
- **implémenté** : remplacement du rôle de `app.config.json` par des compositions `<binary>.default.config.json` ;
- **implémenté** : création de `kb-app-demo-desktop.default.config.json` et d’une composition propre à `ks-pipeline-demo-scenarios` ;
- **implémenté** : extraction des endpoints HTTP/WebSocket vers `transport.config.json` avec schéma et exemple dédiés ;
- **implémenté** : extraction des listeners vers `listeners.config.json` avec schéma et exemple dédiés ;
- **implémenté** : sélection explicite des profils logging/transport/listeners par chaque composition ;
- **implémenté** : maintien temporaire de `AppConfig/ProfileConfig` comme contrat runtime résolu afin de ne pas casser tous les consommateurs pendant la migration ;
- **implémenté** : consommation directe de `TransportProfileConfig` par `ks-onchain-transport` ;
- **implémenté** : suppression des anciens fichiers source `app.config.json`, `example.app.config.json` et de leur schéma source historique ;
- ne pas encore modifier les DTO publics ni la politique de camouflage.
### `0.5.1-pre.007` — store + wallet + execution + configuration dédiée des binaires
- extraire `database` vers un document store cohérent avec les frontières de `ks-store` ;
- supprimer `DataConfig` en réaffectant `logs_directory` au document logging et `wallets_directory` au document wallet selon leur ownership réel ;
- auditer la redondance entre `data.wallets_directory` et `wallet.wallet_dir`, puis définir un répertoire racine wallet global et des chemins/alias de profils sans duplication ;
- sortir les paramètres identité/stockage temporaire du wallet vers un document wallet et préparer le contrat `0.5.2` ;
- déplacer `localnet_send_enabled`, `devnet_send_enabled`, `testnet_send_enabled` et `mainnet_send_enabled` hors du wallet vers la politique d'exécution ;
- extraire les politiques d'exécution vers un document indépendant ;
- décider si `app.auto_reconnect_default`, actuellement conservé pour compatibilité, appartient au transport ou doit être supprimé avec migration explicite ;
- sortir `demo` de `ks-config` vers une configuration réellement possédée par `kb-app-demo-desktop` ;
- réduire les compositions à des références vers profils spécialisés et configuration dédiée du binaire ;
- vérifier qu'un nouveau worker peut ajouter son fichier de composition/dédié sans modifier `ks-config` pour enregistrer son existence.
### `0.5.1-pre.008` — surfaces publiques sûres et camouflage
- propager la classification secret/public/internal lors de la résolution des placeholders et valeurs composées ;
- retirer `AppConfig`/`ProfileConfig` résolus du payload Tauri public ;
- borner les DTO TS-RS et diagnostics ;
- valider qu'aucun secret ne traverse logs/UI/erreurs/sérialisation.
### `0.5.1-pre.007` — clôture
### `0.5.1-pre.009` — clôture
- réconciliation complète des namespaces et docs ;
- réconciliation complète des namespaces, compositions, schémas et docs ;
- audits finaux ;
- suppression des TODO terminés ;
- archivage de ce plan et du prompt `030` ;
@@ -730,7 +766,8 @@ Le desktop n'est lancé avec `cargo tauri dev` que lorsqu'une frontière runtime
- le workspace racine s'appelle toujours `khadhroony-bot3` ;
- les variables Solana ont migré vers `KS_*` avec classification nominale sûre et `KB_*` reste réservé aux futurs contrats Bot ;
- les identités techniques `kb-lib.*` ciblées ont disparu au profit de `ks-lib-*` ;
- la configuration généraliste et logging sont séparées et validées indépendamment ;
- les binaires utilisent leurs compositions dédiées et les documents logging/transport/listeners sont séparés, partageables et validés indépendamment ;
- database, les répertoires logging/wallet, wallet, execution et les réglages propres au desktop ont quitté la composition avant la construction des surfaces publiques ;
- aucune configuration runtime résolue complète ne traverse Tauri ;
- aucun secret canari n'apparaît dans les surfaces publiques ou diagnostiques ;
- les tests d'API externe, audits et tests workspace sont propres ;
@@ -237,10 +237,14 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
## Règles de configuration
- La configuration applicative commune doit passer par `ks-config`.
- Les fichiers runtime chargés par défaut sont `config/app.config.json` pour la configuration générale et `config/logging.config.json` pour le logging ; leurs sélections de profils sont indépendantes.
-Les schémas JSON de configuration actifs sont conservés sous `config/schemas/`, notamment `app.config.schema.json` et `logging.config.schema.json`.
- Les exemples conformes sont conservés sous `config/` avec des noms distincts des fichiers runtime, notamment `example.app.config.json` et `example.logging.config.json`.
- La configuration commune Khadhroony Solana passe par `ks-config`, mais chaque binaire possède son fichier de composition et peut ajouter sa configuration dédiée sans rendre `ks-config` dépendant de ce binaire.
- Le nom par défaut d'une composition binaire suit `<binary>.default.config.json`. Le desktop utilise `config/kb-app-demo-desktop.default.config.json` ; le CLI des scénarios utilise `config/ks-pipeline-demo-scenarios.default.config.json`.
-Une composition référence les documents spécialisés et sélectionne explicitement les profils qu'elle consomme. Elle ne doit pas recopier les blocs transport, listeners ou logging.
- Les documents partagés actuels sont `config/logging.config.json`, `config/transport.config.json` et `config/listeners.config.json`. Ils conservent chacun des profils nommés et peuvent être consommés indépendamment d'une composition.
- Les schémas JSON actifs sont conservés exclusivement sous `config/schemas/`. `composition.config.schema.json`, `logging.config.schema.json`, `transport.config.schema.json` et `listeners.config.schema.json` décrivent les documents source ; `resolved.app.config.schema.json` décrit uniquement le contrat runtime transitoire reconstruit par `ks-config`.
- Les exemples conformes restent sous `config/` avec un nom distinct des fichiers runtime. Les fixtures d'un contrat runtime résolu appartiennent à `test-fixtures/` et ne doivent pas être chargées en production.
- Les fichiers historiques `config/app.config.json`, `config/example.app.config.json`, `config/schemas/app.config.schema.json`, `config/example.config.json` et `config/schema.config.json` sont interdits dans l'état courant.
- Le chemin de composition desktop peut être remplacé par `KB_APP_DEMO_DESKTOP_CONFIG_PATH`. `KS_DEVNET_CONFIG_PATH` sélectionne une composition pour les scénarios Devnet opt-in. `KS_LOGGING_CONFIG_PATH` reste un override explicite du document logging ; sans override, la composition fournit son chemin.
- Les fichiers JSON de configuration ne doivent pas contenir de commentaires.
- Les secrets ne doivent pas être écrits en clair dans le dépôt.
- Les valeurs sensibles doivent utiliser des variables d'environnement ou un stockage chiffré dédié.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
