120 lines
8.2 KiB
Markdown
120 lines
8.2 KiB
Markdown
<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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`.
|
|
|
|
Le workspace `0.5.0` conserve encore physiquement les noms `kb-*`, `kb_*`, `KB_*`, `kb-lib.*` et `kb_sol_*` là où ils existent. Leur présence avant migration 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` doit renommer 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 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.
|