khadhroony-bot3/docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md

<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
<!-- version: 3 -->

# 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_*`. Les namespaces historiques `KB_*`, `kb-lib.*` et `kb_sol_*` restent temporairement présents jusqu'aux prereleases dédiées ; leur présence pendant cette migration bornée ne remet pas en cause la cible ci-dessous.

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

Toutes les variables d'environnement appartenant aux contrats Khadhroony Solana/Bot doivent utiliser le namespace `KS_` après la migration `0.5.1`.

Trois classes sont retenues :

- `KS_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_*` : 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_*` 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 au workspace qui ne commence pas par `KS_` est non conforme après migration. Les variables standard du système ou de dépendances externes ne sont pas reclassées artificiellement comme variables de configuration Khadhroony.

La classification d'une valeur sensible doit survivre à la substitution. Une chaîne composée contenant une valeur issue de `KS_SECRET_*` reste sensible dans son ensemble et ne doit pas redevenir une simple valeur publiable après résolution.

## 5. Configuration source, runtime et publique

La restructuration `0.5.1` doit séparer au minimum :

- la configuration généraliste dans son propre document et son propre schéma ;
- la configuration logging dans un document et un schéma indépendants, avec des profils logging sélectionnables indépendamment des profils réseau/applicatifs.

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.

La conception doit distinguer :

1. la représentation source, qui peut contenir des références `${KS_*}` ;
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.

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. Les identités techniques actuellement préfixées par `kb-lib` doivent être migrées vers le domaine Khadhroony Solana lorsqu'elles identifient des composants généralistes.

La convention cible retenue comprend notamment :

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

`0.5.1-pre.001` doit produire l'inventaire exhaustif des targets de tracing, `processor_name`, identités de replay/idempotence, codes persistés et autres chaînes techniques concernées avant modification. Les anciennes identités ne doivent pas être conservées par inertie puisque la fondation et la base peuvent encore être migrées avant `0.6.x`.

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 :

```text
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 :

```text
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_*`, 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.