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 ne laisse actuellement aucun contrat d'environnement propre au desktop : les variables qu'il consomme appartiennent toutes aux composants ou scénarios Solana et utilisent donc 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 compositions propres aux binaires et des documents spécialisés partagés :

• 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/.

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

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.