v0.5.1-pre.009
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
<!-- file: prompts/001.README.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Prompts actifs
|
||||
|
||||
Ce répertoire contient uniquement les prompts nécessaires aux prochaines versions fonctionnelles. Les prompts clôturés sont archivés sous `olddocs/archivekbot3/prompts/`.
|
||||
|
||||
- [`030_v0_5_1_khadhroony_solana_namespace_and_config.md`](030_v0_5_1_khadhroony_solana_namespace_and_config.md) : migration des bibliothèques généralistes vers `ks-*` / `ks_*`, namespace `KS_*`, identités `ks-lib-*` et restructuration sûre de la configuration/logging.
|
||||
- [`031_v0_5_2_ks_wallet_restructuring.md`](031_v0_5_2_ks_wallet_restructuring.md) : restructuration de `ks-wallet`, format persistant versionné, séparation identité/secret/signature, migration legacy et sécurité des futurs consommateurs.
|
||||
|
||||
@@ -1,468 +0,0 @@
|
||||
<!-- file: prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# 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
|
||||
```
|
||||
291
prompts/031_v0_5_2_ks_wallet_restructuring.md
Normal file
291
prompts/031_v0_5_2_ks_wallet_restructuring.md
Normal file
@@ -0,0 +1,291 @@
|
||||
<!-- file: prompts/031_v0_5_2_ks_wallet_restructuring.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Khadhroony Bot3 — `0.5.2` — restructuration de `ks-wallet`
|
||||
|
||||
## Mission
|
||||
|
||||
Reprendre `khadhroony-bot3` après la clôture validée de `0.5.1` et restructurer `ks-wallet` comme composant Solana généraliste réutilisable par les futurs exécuteurs, workers et applications.
|
||||
|
||||
`0.5.2` doit stabiliser les frontières entre :
|
||||
|
||||
1. identité publique d’un wallet ;
|
||||
2. matériau secret persistant ;
|
||||
3. état verrouillé/déverrouillé ;
|
||||
4. capacité de signature ;
|
||||
5. sélection/configuration d’un wallet par les consommateurs ;
|
||||
6. migration du format legacy déjà utilisé par le workspace.
|
||||
|
||||
Cette version est un chantier wallet/sécurité. Elle ne doit pas ouvrir `0.5.3` sur `ks-store`, `0.5.4` sur les scénarios/exécuteurs, ni une nouvelle couverture Anchor/DEX.
|
||||
|
||||
## Base validée héritée de `0.5.1`
|
||||
|
||||
La base attendue possède notamment :
|
||||
|
||||
- les dix crates Solana généralistes sous `ks-*` / `ks_*` ;
|
||||
- `kb-app-demo-desktop` dans le domaine Bot ;
|
||||
- variables Solana sous `KS_*` et contrats applicatifs Bot sous `KB_*` ;
|
||||
- documents spécialisés `logging.config.json`, `transport.config.json`, `listeners.config.json`, `store.config.json`, `wallet.config.json` et `execution.config.json` ;
|
||||
- exemples conformes sous `config/exemples/` et schémas sous `config/schemas/` ;
|
||||
- composition propre au desktop via `config/kb-app-demo-desktop.default.config.json` ;
|
||||
- classification `Secret > Internal > Public` ;
|
||||
- contrats source/runtime sensibles backend-only ;
|
||||
- TS-RS absent de `ks-config` et `ks-lib`, avec DTO Tauri possédés par les applications ;
|
||||
- URLs résolues retirées des snapshots transport et des surfaces Tauri.
|
||||
|
||||
Ne pas réintroduire un type `ks-wallet` directement sérialisable vers le frontend par commodité.
|
||||
|
||||
## Invariants de namespace
|
||||
|
||||
Le workspace, le dépôt et le répertoire racine restent `khadhroony-bot3`.
|
||||
|
||||
`ks-wallet` appartient au domaine Khadhroony Solana. Ses variables utilisent donc `KS_*`. Une future application Bot peut utiliser `KB_*` uniquement pour ses propres choix applicatifs, jamais pour renommer artificiellement un contrat wallet généraliste.
|
||||
|
||||
Les secrets wallet ne doivent jamais être placés dans :
|
||||
|
||||
- un fichier de configuration source ;
|
||||
- `KS_PUBLIC_*` ou `KB_PUBLIC_*` ;
|
||||
- un payload Tauri ;
|
||||
- un diagnostic normal ;
|
||||
- un log ou une erreur ;
|
||||
- un `Debug` automatique ;
|
||||
- un binding TS-RS générique.
|
||||
|
||||
## Première prerelease obligatoire : plan et caractérisation
|
||||
|
||||
`0.5.2-pre.001` doit être un plan/brainstorm/inventaire. Ne pas commencer par introduire un nouveau format chiffré.
|
||||
|
||||
La première prerelease doit au minimum :
|
||||
|
||||
- relire `ks-wallet/README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md` et tout son code ;
|
||||
- inventorier tous les consommateurs de `ks-wallet` dans le workspace ;
|
||||
- inventorier les chemins de configuration wallet et variables d’environnement ;
|
||||
- caractériser exactement le format legacy `<alias>.json` actuellement utilisé ;
|
||||
- caractériser les permissions de fichier et comportements Unix actuels ;
|
||||
- inventorier création temporaire, persistance, lecture, validation, signature et erreurs ;
|
||||
- relever toutes les dérivations `Clone`, `Debug`, `Serialize`, conversions ou getters pouvant copier/afficher du matériau sensible ;
|
||||
- inventorier les usages directs de `solana_keypair`, `solana_signer::Signer`, `Arc<dyn Signer>` ou équivalents ;
|
||||
- définir les besoins réels multi-wallets et multi-profils sans inventer une UI non demandée ;
|
||||
- définir un contrat de migration et de rollback avant toute écriture du nouveau format ;
|
||||
- proposer un découpage borné des prereleases de `0.5.2` ;
|
||||
- créer un plan temporaire `0.5.2` sous `docs/plans/`, qui sera archivé dans la dernière prerelease.
|
||||
|
||||
Le plan doit être validé avant la première migration de format.
|
||||
|
||||
## Format legacy à préserver comme entrée de migration
|
||||
|
||||
Le workspace possède actuellement un format persistant legacy basé sur le tableau JSON standard d’octets du keypair Solana.
|
||||
|
||||
Avant de le remplacer :
|
||||
|
||||
- écrire des tests de caractérisation à partir d’une fixture synthétique ;
|
||||
- vérifier le nommage `<alias>.json` et les contraintes d’alias ;
|
||||
- vérifier les permissions de fichier existantes ;
|
||||
- vérifier le comportement en cas de fichier absent, corrompu, incomplet ou déjà présent ;
|
||||
- vérifier que la clé publique obtenue après import correspond exactement à l’ancienne ;
|
||||
- interdire toute réécriture destructive sans preuve que la migration est complète.
|
||||
|
||||
Ne jamais utiliser une vraie clé privée de l’opérateur comme fixture.
|
||||
|
||||
## Cible conceptuelle du nouveau contrat
|
||||
|
||||
La solution exacte doit être décidée après audit, mais les frontières suivantes doivent être explicites.
|
||||
|
||||
### Identité publique
|
||||
|
||||
Une identité publique peut contenir par exemple :
|
||||
|
||||
- alias logique ;
|
||||
- clé publique ;
|
||||
- type/source de wallet ;
|
||||
- état disponible/verrouillé ;
|
||||
- métadonnées non sensibles strictement nécessaires.
|
||||
|
||||
Elle ne contient jamais les octets secrets.
|
||||
|
||||
### Matériau secret
|
||||
|
||||
Le matériau secret :
|
||||
|
||||
- reste encapsulé ;
|
||||
- n’implémente pas `Debug` en clair ;
|
||||
- n’est pas sérialisé arbitrairement ;
|
||||
- doit pouvoir être zéroïsé lorsque le type et les dépendances le permettent ;
|
||||
- n’est jamais exposé par getter de bytes public sans justification explicite.
|
||||
|
||||
### Capacité de signature
|
||||
|
||||
Les consommateurs doivent dépendre d’une capacité de signature bornée plutôt que d’un accès aux octets privés.
|
||||
|
||||
Évaluer notamment :
|
||||
|
||||
- trait propre à `ks-wallet` ou adaptation stricte à `solana_signer::Signer` ;
|
||||
- ownership et thread-safety ;
|
||||
- passage vers les exécuteurs sans rendre le secret clonable ;
|
||||
- session déverrouillée de durée bornée si un chiffrement persistant est introduit.
|
||||
|
||||
### État verrouillé/déverrouillé
|
||||
|
||||
Si le stockage chiffré est retenu, définir explicitement :
|
||||
|
||||
- état verrouillé ;
|
||||
- opération de déverrouillage ;
|
||||
- durée ou portée de la session ;
|
||||
- invalidation/lock ;
|
||||
- changement de secret ;
|
||||
- comportement après erreur ;
|
||||
- absence de secret dans les erreurs et logs.
|
||||
|
||||
Ne pas faire du booléen `is_unlocked` une preuve suffisante si la capacité de signature peut être désynchronisée.
|
||||
|
||||
## Chiffrement persistant
|
||||
|
||||
Ne choisir l’algorithme, le KDF, le nonce et le format de conteneur qu’après inventaire des dépendances déjà présentes et vérification des exigences de sécurité.
|
||||
|
||||
Le workspace possède déjà notamment `argon2`, `chacha20poly1305` et `zeroize` dans ses dépendances. Cela ne signifie pas qu’ils doivent être utilisés aveuglément ni avec des paramètres arbitraires.
|
||||
|
||||
Le format persistant, s’il change, doit être :
|
||||
|
||||
- versionné ;
|
||||
- auto-identifiable ;
|
||||
- strictement validé ;
|
||||
- extensible sans ambiguïté ;
|
||||
- écrit atomiquement ;
|
||||
- compatible avec une stratégie de migration/rollback ;
|
||||
- documenté avant d’être considéré stable.
|
||||
|
||||
Ne pas stocker le secret de chiffrement dans `wallet.config.json` ni dans un fichier versionné.
|
||||
|
||||
## Import, export, backup et restore
|
||||
|
||||
Ces capacités ne sont pas automatiquement obligatoires dans la première tranche de code. Leur besoin et leur surface doivent être décidés dans le plan.
|
||||
|
||||
Si elles sont retenues :
|
||||
|
||||
- distinguer import legacy, import du nouveau conteneur et export public ;
|
||||
- éviter toute exportation privée implicite ;
|
||||
- définir les permissions de fichiers et écriture atomique ;
|
||||
- refuser l’écrasement silencieux ;
|
||||
- définir les collisions d’alias et de pubkey ;
|
||||
- tester rollback et corruption ;
|
||||
- ne jamais écrire de keypair secret dans les logs ou diagnostics.
|
||||
|
||||
## Multi-wallets et profils
|
||||
|
||||
`wallet.config.json` possède déjà une racine globale et des profils.
|
||||
|
||||
`0.5.2` doit décider proprement :
|
||||
|
||||
- si un profil sélectionne un alias unique ou un ensemble de wallets ;
|
||||
- comment un futur worker choisit son wallet sans dépendre de `kb-app-demo-desktop` ;
|
||||
- comment un exécuteur demande un signer sans connaître le stockage ;
|
||||
- comment plusieurs wallets sont listés et sélectionnés sans exposer leur matériau secret ;
|
||||
- comment les wallets temporaires et persistants coexistent.
|
||||
|
||||
Ne pas transformer `ks-config` en gestionnaire de secrets. `ks-config` peut sélectionner des identités/aliases publics ou internes, mais le matériau secret appartient à `ks-wallet` et/ou à la source de secret dédiée retenue.
|
||||
|
||||
## Tauri et surfaces publiques
|
||||
|
||||
`ks-wallet` ne doit pas reprendre TS-RS simplement parce que le desktop souhaite afficher une liste de wallets.
|
||||
|
||||
Si le desktop a besoin d’une surface UI :
|
||||
|
||||
```text
|
||||
ks-wallet runtime
|
||||
-> wrapper/DTO kb-app-demo-desktop
|
||||
-> TS-RS
|
||||
-> frontend
|
||||
```
|
||||
|
||||
Les DTO applicatifs peuvent exposer uniquement les informations explicitement sûres, par exemple alias, pubkey et état logique.
|
||||
|
||||
Prévoir des canaris de non-divulgation semblables à ceux de `0.5.1`.
|
||||
|
||||
## Erreurs, logs et diagnostics
|
||||
|
||||
Toute nouvelle erreur liée au wallet doit être conçue pour être utile sans révéler :
|
||||
|
||||
- octets de secret ;
|
||||
- phrase/password ;
|
||||
- contenu chiffré ;
|
||||
- chemin local complet si ce chemin n’est pas explicitement un diagnostic interne ;
|
||||
- valeur d’une variable `KS_SECRET_*` ;
|
||||
- représentation `Debug` d’un keypair/signer.
|
||||
|
||||
Les logs peuvent identifier une opération et un alias/public key lorsque cette donnée est autorisée, mais ne doivent pas concaténer les structures runtime sensibles.
|
||||
|
||||
## Tests minimums à prévoir
|
||||
|
||||
Le plan `pre.001` doit définir précisément les tranches, mais `0.5.2` devra couvrir au minimum :
|
||||
|
||||
- caractérisation du format legacy ;
|
||||
- import legacy préservant la pubkey ;
|
||||
- corruption/troncature/version inconnue ;
|
||||
- permissions privées ;
|
||||
- écriture atomique et refus d’écrasement ;
|
||||
- collisions d’alias/pubkey ;
|
||||
- persistance et réouverture ;
|
||||
- état verrouillé/déverrouillé si applicable ;
|
||||
- signature correcte sans exposition des bytes ;
|
||||
- absence de secret dans `Debug`, `Display`, erreurs, logs et DTO ;
|
||||
- concurrence/thread-safety des signers réellement utilisés ;
|
||||
- API externe crate-root de `ks-wallet` ;
|
||||
- intégration avec `ks-config` sans dépendance inverse vers une application.
|
||||
|
||||
Les tests avec fichiers doivent utiliser des répertoires temporaires et des clés synthétiques. Aucun secret réel ne doit être requis.
|
||||
|
||||
## Découpage indicatif à confirmer par `pre.001`
|
||||
|
||||
Le numéro exact peut évoluer après inventaire, mais l’ordre conceptuel attendu est :
|
||||
|
||||
1. `pre.001` — plan, caractérisation legacy, threat model et inventaire des consommateurs ;
|
||||
2. tranche de contrats publics/identité/signature avant modification du stockage ;
|
||||
3. tranche de conteneur persistant versionné et migration legacy ;
|
||||
4. tranche chiffrement/verrouillage si retenue après validation du format ;
|
||||
5. tranche multi-wallet/import-export/backup uniquement si confirmée par le plan ;
|
||||
6. intégration `ks-config` / consommateurs / desktop via DTO sûrs ;
|
||||
7. dernière prerelease — documentation, audits, TODO, archivage du plan/prompt et préparation de `0.5.3`.
|
||||
|
||||
Un correctif `fix-XXX` conserve le numéro de prerelease et sa numérotation recommence à `fix-001` pour chaque prerelease.
|
||||
|
||||
## Hors périmètre de `0.5.2`
|
||||
|
||||
- migration SQL `kb_sol_*` -> `k_sol_*` ;
|
||||
- refonte temporelle/provenance de `ks-store` ;
|
||||
- centralisation générale des scénarios `0.5.4` ;
|
||||
- ajout de protocoles Anchor/DEX ;
|
||||
- stockage d’un secret wallet dans PostgreSQL sans décision architecturale dédiée ;
|
||||
- hardware wallets, remote signers, KMS/HSM ou Ledger tant qu’ils ne sont pas explicitement priorisés ;
|
||||
- mécanisme universel de secret manager pour toutes les crates.
|
||||
|
||||
## Validation de référence
|
||||
|
||||
Après chaque delta Rust ou contractuel :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --all-targets
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Lorsque le desktop est modifié :
|
||||
|
||||
```bash
|
||||
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
|
||||
```
|
||||
|
||||
Les scripts npm de build/dev ne sont jamais lancés directement.
|
||||
|
||||
## Dernière prerelease de `0.5.2`
|
||||
|
||||
La dernière prerelease doit :
|
||||
|
||||
- réconcilier tous les contrats wallet et consommateurs ;
|
||||
- finaliser README/USAGE/TODO/changelogs/guides ;
|
||||
- supprimer les TODO réellement fermés et reporter les autres vers une version identifiée ;
|
||||
- exécuter les validations finales ;
|
||||
- reprendre les décisions durables dans le ROADMAP et les documents normatifs ;
|
||||
- archiver le plan `0.5.2` et ce prompt sous `olddocs/archivekbot3/` ;
|
||||
- préparer le prompt de `0.5.3` pour l’audit/normalisation de `ks-store`.
|
||||
Reference in New Issue
Block a user