137 lines
11 KiB
Markdown
137 lines
11 KiB
Markdown
<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
|
||
<!-- version: 9 -->
|
||
|
||
# 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 historique `kb_sol_*` est remplacé par `k_sol_*` dans le baseline PostgreSQL de `0.5.3-pre.003`.
|
||
|
||
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`.
|
||
|
||
Depuis `0.5.3-pre.003`, le baseline PostgreSQL actif des faits Solana utilise :
|
||
|
||
```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 reconstruction `kb_sol_*` → `k_sol_*` de `0.5.3-pre.003` est traitée avec les contrats temporels, de provenance, d'idempotence, d'index et de replay ; l'ancien namespace reste uniquement un marqueur détecté/refusé et une référence historique.
|
||
|
||
## 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.
|