v0.5.1-pre.009

2026-08-10 11:44:47 +02:00
parent 0e05c660c6
commit bae7f0b9d8
21 changed files with 521 additions and 65 deletions
--- a/olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md
+++ b/olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md
@@ -0,0 +1,468 @@
+<!-- file: olddocs/archivekbot3/prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md -->
+<!-- version: 7 -->
+
+# Khadhroony Bot3 — `0.5.1` — migration Khadhroony Solana et configuration sûre
+
+## Mission
+
+Reprendre `khadhroony-bot3` après la clôture validée de `0.5.0` et exécuter la première migration structurelle de la fondation `0.5.x`.
+
+`0.5.1` doit accomplir deux objectifs liés :
+
+1. séparer explicitement le domaine des bibliothèques Solana généralistes du domaine applicatif Khadhroony Bot en migrant les bibliothèques vers les namespaces `ks-*` / `ks_*` ;
+2. restructurer la configuration sur cette nouvelle fondation, avec `KS_*` pour les contrats Solana, `KB_*` réservé aux contrats Bot, séparation du logging et politique stricte de non-divulgation des secrets.
+
+Cette version est une migration de fondation. Elle ne doit pas ouvrir de nouveau programme Anchor/DEX et ne doit pas absorber prématurément les chantiers `ks-wallet`, `ks-store` ou de complétude des scénarios réservés respectivement à `0.5.2`, `0.5.3` et `0.5.4`.
+
+## Base validée à préserver
+
+La release `0.5.0` est une version de cadrage sans restructuration runtime majeure. Elle a établi :
+
+- la séparation de domaine entre `khadhroony-solana` et `khadhroony-bot` ;
+- l'inventaire des frontières de configuration, logging, wallet, store, scénarios et desktop ;
+- la cible de renommage des dix crates Solana généralistes ;
+- la convention d'environnement par ownership : `KS_*` pour Khadhroony Solana et `KB_*` pour les futurs contrats spécifiques au Bot ;
+- le split obligatoire de la configuration généraliste et de la configuration logging ;
+- la nécessité de séparer configuration source, runtime résolue et surfaces publiques/diagnostiques ;
+- la migration future des identités techniques `kb-lib.*` vers le domaine `ks-lib-*` ;
+- la migration SQL `kb_sol_*` → `k_sol_*` réservée à `0.5.3` ;
+- le maintien de `kb-app-demo-desktop` côté Bot ;
+- le maintien de l'exception ElGamal dans son statut synthétique actuel tant qu'aucune nouvelle preuve réseau n'est disponible.
+
+La politique normative est :
+
+```text
+docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md
+```
+
+Elle doit être lue avant toute proposition de code.
+
+## Positionnement des projets à conserver
+
+`khadhroony-project` est une umbrella de projets de trading et/ou de crypto. Elle n'est pas limitée à Solana ni même à la crypto. Des projets futurs pourront par exemple viser XTB ou MetaTrader sans dépendre de Solana.
+
+`khadhroony-solana` regroupe les bibliothèques généralistes dédiées à Solana.
+
+`khadhroony-bot` / bot3 est le domaine applicatif du futur robot de trading consommant les composants Khadhroony Solana, avec à terme analyse/création de stratégies et exécution de trading automatique.
+
+`kb-app-demo-desktop` reste dans le domaine Bot. Il sert actuellement surtout de banc de validation des composants Solana généralistes, mais pourra aussi accueillir des démonstrations spécifiques au bot.
+
+Le workspace, le dépôt et le répertoire racine restent nommés `khadhroony-bot3` pendant toute la migration `0.5.1` et plus généralement jusqu'à `1.0` ou une version ultérieure explicitement dédiée. Renommer des crates vers `ks-*` ne doit jamais être interprété comme une autorisation de renommer le workspace racine.
+
+## Lectures obligatoires avant toute proposition
+
+1. `README.md`, `ROADMAP.md`, `CHANGELOG.md`, `RULES.md` et ce prompt ;
+2. `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md` ;
+3. toutes les règles actives sous `docs/rules/`, en particulier :
+   - `RULES_GENERAL.md` ;
+   - `RULES_RUST.md` ;
+   - `RULES_SPECIFIC_KHADHROONY.md` ;
+   - `CRATE_DOCUMENTATION_RULES.md` ;
+   - `VERSION_DEVELOPMENT_LIFECYCLE.md` ;
+4. `docs/architecture/PROJECT_OBJECTIVES.md`, `CRATE_MAP.md`, `ARCHITECTURE.md`, `PIPELINE_ARCHITECTURE.md`, `STORAGE_ARCHITECTURE.md` et `SURFACE_CRATE_MATRIX.md` ;
+5. `README.md`, `USAGE.md`, `TODO.md` et `CHANGELOG.md` des dix crates à renommer et de `kb-app-demo-desktop` ;
+6. les compositions `config/<binary>.default.config.json`, les documents partagés `logging.config.json`, `transport.config.json`, `listeners.config.json`, leurs schémas sous `config/schemas/`, `.env.example` et les fixtures runtime sous `test-fixtures/config/` ;
+7. les tests d'API externe, tests TS-RS, scripts d'audit et références de noms de crates/targets/identités ;
+8. les documents archivés `0.5.0` uniquement comme historique, jamais comme source prioritaire face à la politique active et au code courant.
+
+Avant de modifier un nom public, rechercher son usage réel dans les onze crates, les tests, scripts, fixtures, documentation et contrats persistés.
+
+## Première prerelease obligatoire de `0.5.1`
+
+La première prerelease de `0.5.1` est consacrée au plan détaillé de migration. Elle ne doit pas commencer par renommer des répertoires à l'aveugle.
+
+Elle doit produire au minimum :
+
+- la table exhaustive des dix crates et identifiants Rust à migrer ;
+- la table des dépendances workspace et ordre de renommage ;
+- l'inventaire des noms de packages, bins, libs, imports, exports, tests externes, scripts et documentation concernés ;
+- l'inventaire exhaustif des variables d'environnement actuellement utilisées, leur propriétaire `KS` ou `KB` et leur nom canonique ;
+- la classification de chaque variable en `*_SECRET_*`, `*_PUBLIC_*` ou interne dans le namespace de son propriétaire ;
+- l'inventaire des identités runtime/persistées et targets techniques à migrer ;
+- l'inventaire des payloads Tauri/TS-RS pouvant actuellement transporter de la configuration résolue ;
+- l'inventaire des structures dupliquées entre configuration et logging ;
+- la stratégie de migration des fichiers de configuration et schémas ;
+- les tests de caractérisation nécessaires avant changement ;
+- un plan temporaire `0.5.1` sous `docs/plans/`, à archiver à la dernière prerelease de la version.
+
+Le plan doit être validé avant le premier renommage massif.
+
+## Migration obligatoire des crates vers `ks-*`
+
+Les dix crates généralistes doivent migrer ainsi :
+
+```text
+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 de `kb_*` vers `ks_*`.
+
+`kb-app-demo-desktop` conserve son nom.
+
+La migration doit couvrir de manière cohérente :
+
+- noms de répertoires ;
+- `Cargo.toml` workspace et manifests des crates ;
+- noms de package, library et binary lorsqu'ils appartiennent au domaine Solana généraliste ;
+- dépendances workspace ;
+- chemins Rust ;
+- imports et réexports ;
+- tests d'API externe ;
+- scripts Python ;
+- fixtures et matrices lorsque le nom fait partie d'un contrat actif ;
+- documentation active ;
+- configuration Tauri uniquement là où elle référence les crates renommées ;
+- TS-RS à la source, sans livrer artificiellement les bindings générés.
+
+La migration ne doit pas créer de dépendance d'une crate `ks-*` vers `kb-app-demo-desktop` ou une future application Bot.
+
+## Identités runtime, tracing et persistance
+
+La migration de namespace inclut les identités techniques généralistes actuellement préfixées par `kb-lib`.
+
+La cible comprend notamment :
+
+```text
+kb-lib.decoder.*       -> ks-lib-decoder.*
+kb-lib.materializer.*  -> ks-lib-materializer.*
+kb-lib.executor.*      -> ks-lib-executor.*
+```
+
+Avant remplacement, établir une matrice exhaustive des catégories concernées :
+
+- tracing targets ;
+- `processor_name` ;
+- identités de replay ;
+- identités d'idempotence ;
+- clés de provenance ;
+- valeurs persistées dans les tests/fixtures ;
+- diagnostics et matrices contractuelles ;
+- tout autre identifiant stable contenant un préfixe historique `kb-*` ou `kb-lib.*`.
+
+La base peut encore être reconstruite ou migrée avant `0.6.x`. Il est donc acceptable de casser proprement une identité historique si elle appartient réellement à Khadhroony Solana, à condition que la migration soit explicite, testée et documentée.
+
+Ne pas renommer arbitrairement les segments métier `solana`, `spl`, protocoles, surfaces ou opérations lorsqu'ils expriment déjà une sémantique stable.
+
+## Tables SQL : ne pas anticiper `0.5.3`
+
+La cible durable des tables Solana est :
+
+```text
+kb_sol_* -> k_sol_*
+```
+
+et les éventuelles tables réellement spécifiques au domaine Bot utiliseront :
+
+```text
+kb_*
+```
+
+Cependant, le renommage physique des tables et la normalisation des migrations appartiennent à `0.5.3` avec `ks-store`, car ce chantier doit être traité avec `block_time`, provenance, idempotence, index et contrats de replay.
+
+`0.5.1` peut mettre à jour les identités techniques persistées `ks-lib-*`, mais ne doit pas transformer la migration SQL en chantier secondaire dispersé.
+
+## Namespace obligatoire des variables d'environnement
+
+Le namespace suit le propriétaire fonctionnel du contrat :
+
+```text
+Khadhroony Solana / ks-* : KS_SECRET_* / KS_PUBLIC_* / KS_*
+Khadhroony Bot / kb-*    : KB_SECRET_* / KB_PUBLIC_* / KB_*
+```
+
+Une variable de scénario ou de configuration Solana reste `KS_*` même si `kb-app-demo-desktop` la consomme. `KB_*` est réservé aux besoins réellement propres au desktop ou aux futures crates du Bot. Les variables standard de l'OS, de Cargo ou d'outils tiers ne sont pas renommées artificiellement.
+
+Les classes ont la même sémantique dans les deux namespaces :
+
+- `*_SECRET_*` : secret absolu, jamais exposé ni loggé ;
+- `*_PUBLIC_*` : candidate explicite à une surface publique, sans autorisation automatique d'exposition ;
+- autres `KS_*` / `KB_*` : internes, absentes des payloads normaux.
+
+La migration des noms et la fermeture des alias legacy appartiennent à `pre.004`. La propagation de sensibilité dans les valeurs composées, le camouflage et les DTO publics sûrs sont réalisés après le split config/logging.
+
+## Split obligatoire de la configuration
+
+`0.5.1` doit extraire la configuration logging du document généraliste.
+
+La cible minimale est conceptuellement :
+
+```text
+configuration générale + schéma général
+configuration logging  + schéma logging
+```
+
+Les profils généralistes et logging sont indépendants. Il ne doit plus être nécessaire de recopier un bloc logging complet dans chaque profil réseau/applicatif.
+
+D'autres documents spécialisés sont autorisés seulement si l'audit démontre qu'ils réduisent réellement le couplage et possèdent une responsabilité ou validation indépendante.
+
+Ne pas découper arbitrairement la configuration en un fichier par sous-structure.
+
+## Propriété des contrats de logging
+
+`0.5.0` a constaté une duplication des structures `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig` entre la configuration et le runtime logging.
+
+`0.5.1` doit définir un propriétaire clair du contrat source de logging sans créer de cycle de dépendances.
+
+La solution retenue doit :
+
+- éviter une duplication de DTO identiques ;
+- éviter que `ks-config` dépende du runtime `ks-logging` uniquement pour réutiliser un type ;
+- éviter une nouvelle crate de contrat si elle n'a pas de responsabilité autonome suffisante ;
+- supprimer les conversions manuelles du desktop lorsque la nouvelle frontière le permet.
+
+## Configuration source, runtime et publique
+
+La restructuration doit empêcher qu'une configuration résolue complète puisse être envoyée au frontend par commodité.
+
+Distinguer au minimum :
+
+1. représentation source : fichiers, placeholders et références `${KS_*}` / `${KB_*}` ;
+2. représentation runtime : valeurs validées et résolues nécessaires au backend ;
+3. représentation publique/diagnostique : DTO explicitement construits pour l'UI, les diagnostics ou une API externe.
+
+Une valeur runtime contenant un secret ne doit pas redevenir une `String` publique sans classification ni contrôle.
+
+Éviter le modèle :
+
+```text
+runtime complet -> sérialisation -> suppression/redaction après coup
+```
+
+Préférer :
+
+```text
+runtime -> construction explicite d'un DTO public sûr
+```
+
+## Résolution d'environnement et `.env`
+
+Auditer et tester :
+
+- `${NAME}` ;
+- `${NAME:-fallback}` ;
+- erreurs de variable absente ;
+- valeurs vides ;
+- substitutions multiples ;
+- valeurs composées ;
+- détection et propagation de la sensibilité ;
+- priorité environnement / `.env` / valeur par défaut selon le contrat actuel ;
+- absence de fuite dans les messages d'erreur ;
+- comportement des profils.
+
+Le mécanisme final doit accepter uniquement les noms de variables conformes au nouveau contrat lorsqu'ils appartiennent au workspace.
+
+## Payloads Tauri et TS-RS
+
+Le risque prioritaire identifié en `0.5.0` est l'exposition de `AppConfig` / `ProfileConfig` résolus au frontend.
+
+`0.5.1` doit supprimer cette possibilité par construction.
+
+Les commandes Tauri restent des adaptateurs minces :
+
+- aucune logique métier nouvelle dans `tauri.rs` ;
+- aucun `?` ni unwrap dans les commandes Tauri ;
+- DTO publics dédiés ;
+- aucun secret résolu dans les bindings ou réponses ;
+- diagnostics séparés des payloads normaux ;
+- tests négatifs avec valeurs sentinelles secrètes.
+
+## Tests de sécurité obligatoires
+
+Ajouter des tests prouvant notamment que :
+
+- une sentinelle issue de `KS_SECRET_*` ou `KB_SECRET_*` n'apparaît dans aucune sérialisation publique ;
+- elle n'apparaît pas dans les erreurs publiques ;
+- elle n'apparaît pas dans les diagnostics debug ;
+- une URL ou DSN composée avec un secret est entièrement traitée comme sensible ;
+- `KS_PUBLIC_*` / `KB_PUBLIC_*` n'est exposé que par une surface explicitement autorisée ;
+- une variable interne `KS_*` / `KB_*` n'apparaît pas dans le payload normal ;
+- les anciens noms d'environnement sont absents après migration ;
+- les schémas JSON général et logging valident leurs documents respectifs ;
+- le choix d'un profil logging est indépendant du profil général ;
+- les tests d'API externe compilent avec les nouveaux noms `ks_*`.
+
+Ne pas figer par test un comportement `0.5.0` connu comme dangereux uniquement pour préserver la compatibilité.
+
+## Ordre approximatif des prereleases
+
+Le détail doit être confirmé par `0.5.1-pre.001`, mais la trajectoire cible est :
+
+### `0.5.1-pre.001` — plan de migration
+
+- inventaires exhaustifs ;
+- table de renommage ;
+- matrice d'identités ;
+- matrice des variables d'environnement ;
+- stratégie config/logging ;
+- tests de caractérisation ;
+- plan temporaire.
+
+### `0.5.1-pre.002` — migration mécanique `ks-*` / `ks_*`
+
+- renommer les dix crates ;
+- manifests, imports, exports, scripts et tests ;
+- maintenir un workspace compilable et auditable ;
+- conserver `kb-app-demo-desktop`.
+
+### `0.5.1-pre.003` — identités techniques `ks-lib-*`
+
+- migrer les targets et identités runtime/persistables généralistes ;
+- synchroniser matrices, tracing, diagnostics et provenance/replay ;
+- conserver encore les variables d'environnement pour la prerelease suivante.
+
+### `0.5.1-pre.004` — environnement et classification nominale
+
+- migrer les contrats Solana vers `KS_*` et réserver `KB_*` aux futurs contrats Bot ;
+- classer les secrets en `*_SECRET_*`, les valeurs explicitement publiques en `*_PUBLIC_*` et le reste en interne ;
+- consolider les alias historiques Token-2022 ;
+- mettre à jour `.env.example`, configuration, fixtures, scénarios, store, desktop et guides ;
+- ne pas encore implémenter le camouflage ou la propagation de sensibilité.
+
+### `0.5.1-pre.005` — split configuration/logging
+
+- extraire le logging dans son document et son schéma indépendants ;
+- rendre les profils logging indépendants ;
+- transférer la propriété des contrats logging à `ks-logging`.
+
+### `0.5.1-pre.006` — composition binaire + transport + listeners
+
+- remplacer le rôle du document monolithique par des compositions `<binary>.default.config.json` ;
+- fournir une composition dédiée au desktop et une composition dédiée aux scénarios ;
+- extraire transport et listeners dans des documents/schémas indépendants ;
+- conserver `AppConfig/ProfileConfig` comme contrat runtime résolu transitoire ;
+- permettre aux transports de consommer directement `TransportProfileConfig`.
+
+### `0.5.1-pre.007` — store + wallet + execution + configuration dédiée des binaires
+
+- extraire database vers store, `logs_directory` vers logging et les chemins de wallets vers wallet selon leur ownership réel ;
+- déplacer les permissions `*_send_enabled` du wallet vers execution ;
+- sortir la configuration spécifique au desktop du domaine `ks-config` ;
+- réduire les compositions à des références vers profils spécialisés et configuration dédiée ;
+- vérifier qu'un futur worker peut ajouter sa propre composition sans enregistrer son identité dans `ks-config`.
+
+### `0.5.1-pre.008` — runtime/public, camouflage et Tauri sûr
+
+- **réalisé** : rendre les contrats `ks-config` source/runtime sensibles backend-only, sans `Serialize`/`Debug` ;
+- **réalisé** : rendre `application` opaque pour `ks-config` et valider le fragment desktop avec son schéma propriétaire ;
+- **réalisé** : remplacer l'exposition `AppConfig/ProfileConfig` par des DTO public/diagnostic construits explicitement ;
+- **réalisé** : propager `Secret > Internal > Public` aux chaînes composées et supprimer l'écho de valeurs rejetées dans les erreurs de validation ;
+- **réalisé** : retirer TS-RS et les bindings générés de `ks-config`/`ks-lib`, avec audit empêchant leur réintroduction implicite ;
+- **réalisé** : ajouter les canaris de non-divulgation et le test d'API externe de sensibilité.
+
+### `0.5.1-pre.009` — réconciliation et clôture
+
+- audit exhaustif des anciens préfixes et anciens documents ;
+- documentation finale ;
+- TODO/changelogs ;
+- validations workspace ;
+- archivage du plan/prompt ;
+- préparation de `0.5.2`.
+
+Ce découpage reste borné : aucun chantier SQL `k_sol_*`, wallet ou DEX n'est absorbé dans `0.5.1`.
+
+## Règles de développement à conserver
+
+- Rust 2024 ;
+- aucune utilisation de `unsafe`, `unwrap`, `expect` ou `panic` dans le code de production ;
+- imports réservés aux traits nécessaires, chemins explicites pour les autres symboles ;
+- respect des en-têtes `file:` / `version:` et incrément des versions locales des fichiers modifiés ;
+- documentation Rust en anglais, documentation Markdown en français ;
+- aucune ligne vide interne artificielle dans les fonctions Rust et exactement une newline en fin de fichier ;
+- aucune logique métier nouvelle dans `kb-app-demo-desktop` lorsqu'elle peut résider dans une crate `ks-*` réutilisable ;
+- les commandes Tauri restent des adaptateurs minces et n'utilisent ni `?` ni unwrap ;
+- les archives sous `olddocs/` ne sont jamais réécrites hors opération d'archivage explicitement demandée.
+
+## Règle frontend/Tauri obligatoire
+
+Ne jamais lancer directement :
+
+```text
+npm run dev
+npm run build
+npm --prefix kb-app-demo-desktop run build
+```
+
+Les commandes npm manuelles sont limitées à l'installation explicite de dépendances nécessaires, notamment `npm i` et `npm i -D`.
+
+Le développement desktop est piloté par :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+Le build de release est piloté par :
+
+```bash
+cargo tauri build -c kb-app-demo-desktop/tauri.conf.json
+```
+
+Tauri déclenche lui-même les scripts frontend configurés.
+
+## Discipline des scénarios et validations
+
+Le renommage de `kb-pipeline-demo-scenarios` vers `ks-pipeline-demo-scenarios` ne change pas son rôle : les scénarios sont des validations réutilisables des composants Solana, pas de la logique spécifique au bot.
+
+Les campagnes déjà qualifiées ne doivent pas être rejouées automatiquement uniquement parce qu'une crate ou un identifiant a changé de nom. Les tests contractuels, compilations et chemins de preuve doivent être vérifiés ; un rerun réseau n'est requis que si une frontière réellement couverte par la preuve a changé.
+
+ElGamal reste une exception connue et ne doit pas devenir une tâche implicite de `0.5.1`.
+
+## Documentation et deltas
+
+À chaque prerelease ou correctif :
+
+- mettre à jour uniquement les documents rendus faux ou incomplets ;
+- conserver les README/USAGE généralistes ;
+- utiliser les changelogs pour la chronologie ;
+- supprimer les TODO terminés ;
+- maintenir le plan temporaire ;
+- livrer uniquement un ZIP delta avec `delta.md` ;
+- ne jamais livrer `Cargo.lock`, les lockfiles frontend, `node_modules`, `dist`, `target` ou les bindings générés sans nécessité explicite ;
+- ne jamais fournir de SHA/checksum dans la réponse de livraison ;
+- recommencer la numérotation `fix-001` à chaque nouvelle prerelease.
+
+Un renommage mécanique massif doit rester traçable dans `delta.md` et ne doit pas masquer des changements fonctionnels sans rapport.
+
+## Dernière prerelease obligatoire
+
+La dernière prerelease de `0.5.1` devra :
+
+- exécuter les validations finales ;
+- vérifier qu'aucun ancien nom de crate ou variable projet interdit ne subsiste hors archives/historique explicitement autorisé ;
+- vérifier les identités runtime/persistées migrées ;
+- vérifier la non-divulgation des secrets ;
+- finaliser README, ROADMAP, changelogs, TODO, règles, guides et schémas concernés ;
+- transférer les décisions durables du plan vers les documents normatifs ;
+- archiver le plan et le prompt de session terminés sous `olddocs/archivekbot3/` ;
+- préparer le prompt `0.5.2` consacré à `ks-wallet` ;
+- préparer la release finale sans introduire un nouveau chantier structurel majeur.
+
+## Contrôles de référence
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test --workspace
+```
+
+Lorsque le desktop doit être validé :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+Pour une validation de release desktop :
+
+```bash
+cargo tauri build -c kb-app-demo-desktop/tauri.conf.json
+```