132 lines
9.9 KiB
Markdown
132 lines
9.9 KiB
Markdown
<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# 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 :
|
|
|
|
```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_*` 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.
|