khadhroony-bot3/docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md

Politique de namespace Khadhroony Solana

1. Statut

Cette décision est adoptée pendant la clôture de 0.5.0 et devient la cible normative des migrations de fondation 0.5.1 à 0.5.3.

À partir de 0.5.1-pre.002, les dix crates Solana généralistes sont physiquement nommées ks-* et leurs identifiants Rust ks_*. 0.5.1-pre.003 migre également les identités techniques kb-lib.* vers ks-lib-*. 0.5.1-pre.004 migre les variables possédées par Khadhroony Solana vers KS_* et réserve explicitement KB_* aux composants réellement possédés par Khadhroony Bot. Le namespace SQL kb_sol_* reste temporairement présent jusqu'à 0.5.3.

Le renommage des bibliothèques internes ne renomme pas le workspace, le dépôt ni le répertoire racine : ils restent khadhroony-bot3 pendant toute la série pré-1.0. Un éventuel renommage du workspace racine est explicitement hors périmètre de 0.5.x et ne doit intervenir qu'en 1.0 ou ultérieurement sur décision dédiée.

2. Positionnement des projets

khadhroony-project est une umbrella de projets liés au trading et/ou aux technologies crypto. Elle n'est pas limitée à Solana ni même à la crypto. Des projets futurs pourront par exemple viser XTB ou MetaTrader indépendamment des composants Solana.

khadhroony-solana est le domaine des bibliothèques généralistes dédiées à Solana. Ces bibliothèques doivent pouvoir être réutilisées par plusieurs applications sans dépendre du futur robot de trading Khadhroony Bot.

khadhroony-bot / khadhroony-bot3 est le domaine applicatif du futur robot de trading. Après stabilisation de la fondation et avant/après 1.0 selon le ROADMAP, il doit pouvoir consommer les composants khadhroony-solana, fournir des capacités d'analyse et de création de stratégies puis un exécutable de trading automatique.

kb-app-demo-desktop reste une application du workspace Bot. Elle sert actuellement surtout à tester et valider les composants Solana généralistes, mais elle pourra aussi recevoir des démonstrations spécifiques au bot. Son nom n'est donc pas inclus dans la migration ks-*.

3. Crates Solana généralistes

La migration 0.5.1-pre.002 renomme les dix crates généralistes suivantes :

Nom 0.5.0	Nom cible
kb-core	ks-core
kb-config	ks-config
kb-lib	ks-lib
kb-logging	ks-logging
kb-program-ids	ks-program-ids
kb-pipeline	ks-pipeline
kb-pipeline-demo-scenarios	ks-pipeline-demo-scenarios
kb-onchain-transport	ks-onchain-transport
kb-store	ks-store
kb-wallet	ks-wallet

Les identifiants Rust correspondants migrent dans le même delta vers ks_* : par exemple kb_config devient ks_config et kb_pipeline_demo_scenarios devient ks_pipeline_demo_scenarios.

La migration doit couvrir les manifests, chemins de workspace, imports, exports, tests d'API externe, scripts, documentation, targets de build et bindings générés à la source. Les artefacts générés restent régénérés localement selon les règles du workspace et ne sont pas livrés sans nécessité explicite.

4. Variables d'environnement

Le namespace d'une variable est déterminé par la responsabilité qui possède le contrat, et non par l'exécutable qui la lit.

• les crates et contrats généralistes Khadhroony Solana utilisent KS_* ;
• kb-app-demo-desktop et les futures crates réellement spécifiques au Bot utilisent KB_* pour leurs propres contrats ;
• une variable d'un scénario Solana réutilisable reste donc KS_* même lorsqu'elle est consommée par kb-app-demo-desktop ;
• les variables standard du système, de Cargo, de Rust ou d'un outil externe ne sont pas renommées artificiellement tant qu'elles ne deviennent pas un contrat de configuration du workspace.

Chaque domaine possède les trois mêmes classes :

• KS_SECRET_* / KB_SECRET_* : secret absolu ; la valeur peut être utilisée côté backend mais ne doit jamais être loggée, sérialisée vers une surface publique, renvoyée par Tauri ni affichée en diagnostic, même en mode debug ;
• KS_PUBLIC_* / KB_PUBLIC_* : valeur explicitement classée comme publiable ; le préfixe ne suffit pas à lui seul à autoriser une exposition, qui doit rester définie par un DTO ou une surface publique explicite ;
• KS_* / KB_* hors sous-préfixes précédents : valeur interne ; elle n'est pas exposée en fonctionnement normal mais peut être incluse dans un diagnostic explicitement demandé si sa sémantique n'est pas sensible.

Une variable appartenant à un contrat ks-* qui utilise KB_*, ou l'inverse pour un contrat réellement spécifique kb-*, est non conforme. 0.5.1-pre.004 n’avait encore identifié aucun contrat d’environnement propre au desktop. Depuis l’introduction des compositions par binaire, KB_APP_DEMO_DESKTOP_CONFIG_PATH est le premier contrat réellement possédé par kb-app-demo-desktop; les variables des composants et scénarios Solana qu’il consomme restent KS_*.

La classification d'une valeur sensible doit survivre à la substitution. Une chaîne composée contenant une valeur issue de KS_SECRET_* ou KB_SECRET_* reste sensible dans son ensemble et ne doit pas redevenir une simple valeur publiable après résolution. Cette propagation et le camouflage effectif sont implémentés après le split config/logging, pas dans la prerelease de renommage.

5. Configuration source, runtime et publique

La restructuration 0.5.1 utilise des documents spécialisés Khadhroony Solana et, uniquement lorsque nécessaire, une composition propre au binaire :

• config/kb-app-demo-desktop.default.config.json compose les overrides du desktop ;
• config/logging.config.json appartient à ks-logging et porte notamment logs_directory hors profils ;
• config/transport.config.json contient les profils HTTP/WebSocket et les classes de defaults WebSocket ;
• config/listeners.config.json contient les profils de subscriptions Solana ;
• config/store.config.json contient les profils de stockage ;
• config/wallet.config.json contient la racine wallet globale et les profils wallet ;
• config/execution.config.json contient les politiques de simulation, soumission et limites ;
• tous les schémas actifs résident sous config/schemas/.

Chaque document partagé possède un default_profile. Un consommateur qui accepte les defaults n'a pas besoin de composition dédiée. C'est notamment le cas de ks-pipeline-demo-scenarios; KS_DEVNET_CONFIG_PATH reste uniquement un override facultatif vers une composition explicite.

Lorsqu'un binaire possède une composition, celle-ci peut remplacer indépendamment les profils spécialisés. ks-config doit prouver l'existence des fichiers et des profils référencés avant de produire le contrat runtime.

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 distingue :

1. les documents source indépendants, pouvant contenir des références ${KS_*} ou ${KB_*} selon le propriétaire ;
2. leurs valeurs globales et default_profile ;
3. l'éventuelle composition propre au binaire, qui fournit des overrides ;
4. la représentation runtime résolue, qui peut porter des secrets ;
5. 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. Les bindings TypeScript des crates généralistes suivent la même frontière : ils ne sont conservés que lorsqu'un contrat générique indépendant d'une application Tauri le justifie.

6. Identités runtime et persistées

La migration de namespace ne se limite pas au nom des crates. Depuis 0.5.1-pre.003, les identités techniques généralistes anciennement préfixées par kb-lib utilisent le domaine Khadhroony Solana.

Le mapping de migration retenu et appliqué comprend :

• kb-lib.decoder.* → ks-lib-decoder.* ;
• kb-lib.materializer.* → ks-lib-materializer.* ;
• kb-lib.executor.* → ks-lib-executor.*.

0.5.1-pre.001 a produit l'inventaire initial, puis pre.003 l'a vérifié contre le corpus actif avant migration : 255 identités uniques ont été confirmées, soit 118 décodeurs, 112 exécuteurs et 25 matérialiseurs. Les anciennes identités ne sont conservées que dans les documents de traçabilité de migration ; elles ne doivent plus être produites par le runtime, les matrices ou les routes de logging actives.

Les segments métier internes (solana, spl, protocoles, surfaces et opérations) conservent leurs règles propres ; la migration de préfixe ne doit pas altérer arbitrairement leur sémantique.

7. Namespace SQL

La normalisation SQL appartient à 0.5.3 avec ks-store.

Les tables génériques représentant des faits Solana doivent migrer du préfixe actuel kb_sol_* vers :

k_sol_*

La base Mainnet/Devnet peut être reconstruite ou migrée proprement avant l'ouverture de 0.6.x. Il n'est donc pas nécessaire de préserver indéfiniment un préfixe historique incohérent uniquement pour compatibilité.

Si des tables réellement spécifiques au robot de trading sont introduites ultérieurement, elles utilisent le préfixe :

kb_*

Une table ne reçoit pas kb_* simplement parce qu'elle est consommée par le bot. Elle doit contenir des données dont la responsabilité appartient réellement au domaine applicatif Bot et non à la blockchain ou aux bibliothèques Solana généralistes.

La migration kb_sol_* → k_sol_* doit être traitée avec les contrats temporels, de provenance, d'idempotence, d'index et de replay de 0.5.3, et non comme un remplacement textuel isolé.

8. Ordre des migrations

• 0.5.1 : crates ks-*, identifiants Rust ks_*, variables KS_* pour Solana avec KB_* réservé aux contrats Bot, identités runtime/persistées Khadhroony Solana et restructuration sûre de la configuration/logging ;
• 0.5.2 : restructuration de ks-wallet sur la nouvelle fondation de configuration ;
• 0.5.3 : normalisation de ks-store, y compris migration du préfixe SQL vers k_sol_* et contrats temporels/provenance ;
• 0.5.4 : centralisation finale des scénarios dans ks-pipeline-demo-scenarios et audit de complétude des exécuteurs/validations.

Aucune de ces migrations ne doit réintroduire une dépendance du domaine Solana généraliste vers une application spécifique au bot.