0.5.0-pre.004
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
<!-- file: prompts/001.README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# 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/`.
|
||||
|
||||
- [`029_v0_5_0_foundation_restructuring_plan.md`](029_v0_5_0_foundation_restructuring_plan.md) : cadrage de la fondation `0.5.x`, planification des restructurations configuration, wallet, store et scénarios.
|
||||
- [`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.
|
||||
|
||||
@@ -1,234 +0,0 @@
|
||||
<!-- file: prompts/029_v0_5_0_foundation_restructuring_plan.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de session — 0.5.0 cadrage de la fondation `0.5.x`
|
||||
|
||||
## Mission
|
||||
|
||||
Reprendre `khadhroony-bot3` après la clôture validée de `0.4.8` et préparer la série `0.5.x` consacrée à la fondation du workspace avant l’ouverture des grands programmes Anchor/DEX.
|
||||
|
||||
`0.5.0` doit commencer par un audit et un plan complet. Il ne faut pas lancer immédiatement une restructuration de `kb-config`, `kb-wallet` ou `kb-store` sans avoir vérifié les frontières actuelles, les contrats publics, les schémas, les tests et les dépendances du workspace.
|
||||
|
||||
La trajectoire cible est :
|
||||
|
||||
- `0.5.1` : restructuration de `kb-config` et contrats de configuration ;
|
||||
- `0.5.2` : restructuration de `kb-wallet` ;
|
||||
- `0.5.3` : audit et normalisation de `kb-store` en préparation des matérialisations trading/routing ;
|
||||
- `0.5.4` : centralisation des scénarios dans `kb-pipeline-demo-scenarios` et audit des exécuteurs/validations manquants.
|
||||
|
||||
La première prerelease de `0.5.0` doit produire le plan temporaire de la version et le découpage détaillé des prereleases avant tout changement structurel important.
|
||||
|
||||
## Base validée à préserver
|
||||
|
||||
La release `0.4.8` ferme :
|
||||
|
||||
- Solana Program Metadata comme surface indépendante, avec neuf opérations confirmées sur Devnet ;
|
||||
- les cinq opérations Token-2022 Token Metadata confirmées sur Devnet ;
|
||||
- la matrice courante Metaplex Token Metadata à 15 `confirmed`, 5 `unavailable`, 0 `not_run` ;
|
||||
- les scénarios Metadata réutilisables dans `kb-pipeline-demo-scenarios` et leur intégration desktop ;
|
||||
- la réconciliation des matrices, exports, registres runtime, IDL, stockage générique et documentation Metadata ;
|
||||
- la validation finale du workspace par formatage, check, Clippy, audit et `cargo test --workspace` ;
|
||||
- le build desktop de release par `cargo tauri build`, produisant les bundles Linux prévus.
|
||||
|
||||
Le registre ElGamal reste une exception connue : implémenté et validé synthétiquement, sans preuve réseau réelle disponible. Ne pas convertir cette exception en tâche implicite de `0.5.0` sans nouvelle possibilité de validation.
|
||||
|
||||
## Lectures obligatoires avant toute proposition
|
||||
|
||||
1. `README.md`, `ROADMAP.md`, `CHANGELOG.md`, `RULES.md` et ce prompt ;
|
||||
2. 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` ;
|
||||
3. `README.md`, `USAGE.md`, `TODO.md` et `CHANGELOG.md` de chaque crate directement concernée ;
|
||||
4. les documents d’architecture et de stockage actifs ;
|
||||
5. les schémas, exemples de configuration, migrations SQL, matrices contractuelles et tests existants ;
|
||||
6. les prompts archivés `027` et `028` uniquement comme références de méthode et d’historique, jamais comme source prioritaire sur le code actuel.
|
||||
|
||||
Avant de modifier un contrat public, vérifier son usage réel dans les onze crates et les tests d’API externe.
|
||||
|
||||
## 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 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. Le `dist` Vite et `frontendDist` Tauri doivent continuer à désigner le même répertoire de sortie du workspace.
|
||||
|
||||
## Première prerelease obligatoire de `0.5.0`
|
||||
|
||||
La première prerelease est exclusivement consacrée au plan et au brainstorming. Elle doit :
|
||||
|
||||
- inventorier les responsabilités et couplages de `kb-config`, `kb-logging`, `kb-wallet`, `kb-store`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
|
||||
- identifier les contrats publics et formats persistés qui ne peuvent pas être modifiés sans migration ;
|
||||
- comparer le code aux README/USAGE/TODO/changelogs et supprimer les hypothèses obsolètes du plan ;
|
||||
- établir les problèmes réels et les priorités ;
|
||||
- proposer un découpage de prereleases bornées pour atteindre les objectifs de `0.5.0` ;
|
||||
- préciser ce qui appartient réellement à `0.5.0` et ce qui doit rester réservé à `0.5.1` à `0.5.4` ;
|
||||
- définir les tests, audits, migrations et validations nécessaires avant code ;
|
||||
- créer un plan temporaire sous `docs/plans/`, à archiver lors de la dernière prerelease de `0.5.0`.
|
||||
|
||||
La planification doit être validée avant toute restructuration importante.
|
||||
|
||||
## Axe `0.5.1` — `kb-config`
|
||||
|
||||
Le plan doit préparer une version dédiée qui :
|
||||
|
||||
- restructure `kb-config` par responsabilités cohérentes ;
|
||||
- sépare au minimum le schéma de configuration générale du schéma de logging si l’audit confirme cette frontière ;
|
||||
- autorise d’autres schémas spécialisés uniquement lorsqu’ils réduisent réellement le couplage ;
|
||||
- audite les profils, valeurs par défaut, validations croisées et erreurs ;
|
||||
- audite la résolution des variables d’environnement et `.env` ;
|
||||
- introduit un camouflage systématique des secrets dans logs, diagnostics, UI, sérialisation et erreurs ;
|
||||
- interdit qu’un secret résolu soit renvoyé en clair par un payload de configuration ;
|
||||
- garde les exemples, schémas JSON, TS-RS et documentation alignés.
|
||||
|
||||
## Axe `0.5.2` — `kb-wallet`
|
||||
|
||||
Préparer :
|
||||
|
||||
- l’audit des types de wallets et signers existants ;
|
||||
- la séparation identité / secret / déverrouillage / signature ;
|
||||
- les besoins multi-wallets et multi-profils ;
|
||||
- import/export, chiffrement, sauvegarde/restauration et verrouillage lorsque ces capacités sont retenues ;
|
||||
- des frontières strictes empêchant la fuite de secrets vers config, logs ou Tauri ;
|
||||
- des scénarios réutilisables lorsque des validations opérateur sont nécessaires.
|
||||
|
||||
## Axe `0.5.3` — `kb-store`
|
||||
|
||||
Préparer un audit de fond avant migration :
|
||||
|
||||
- contrats DTO, entités, repositories, migrations, index et requêtes ;
|
||||
- timestamps on-chain et timestamps de persistance séparés explicitement ;
|
||||
- distinction entre slot, block time ou temps de transaction et temps d’insertion/mise à jour en base ;
|
||||
- provenance et idempotence ;
|
||||
- normalisation de la structure du store ;
|
||||
- champs et index nécessaires aux futures matérialisations trading/routing/multi-pools ;
|
||||
- interrogation efficace de la création de pools, actifs, liquidité, réserves, prix observés, swaps et séries temporelles ;
|
||||
- possibilité d’analyser plusieurs pools et routes sans couplage prématuré à Meteora, Raydium, Pump, Orca ou Jupiter.
|
||||
|
||||
Aucune table trading spécifique ne doit être inventée avant d’avoir défini les faits stables produits par les matérialisateurs futurs.
|
||||
|
||||
## Axe `0.5.4` — scénarios et complétude des exécuteurs
|
||||
|
||||
Préparer un audit transversal qui :
|
||||
|
||||
- détecte les scénarios encore assemblés directement dans `kb-app-demo-desktop` ;
|
||||
- déplace leur logique réutilisable vers `kb-pipeline-demo-scenarios` ;
|
||||
- laisse le desktop comme adaptateur UI/Tauri uniquement ;
|
||||
- compare les décodeurs aux exécuteurs disponibles ;
|
||||
- identifie les exécuteurs manquants réellement justifiés ;
|
||||
- compare les exécuteurs aux scénarios et validations réseau existants ;
|
||||
- identifie les capacités présentes dans le desktop sans scénario réutilisable ;
|
||||
- classe chaque manque comme à implémenter, decode-only, deprecated, unavailable, non applicable ou reporté.
|
||||
|
||||
## Suite du ROADMAP à respecter
|
||||
|
||||
Après `0.5.x` :
|
||||
|
||||
- `0.6.x` : infrastructure Anchor générique et seulement les programmes SPL apportant une valeur directe aux DEX suivants ;
|
||||
- `0.7.x` : Meteora avec alternance decode/materialize puis executor/scénarios ;
|
||||
- `0.8.x` : Raydium selon la même discipline ;
|
||||
- `0.9.x` : Pump ;
|
||||
- `0.10.x` : Orca ;
|
||||
- `0.11.x` : Jupiter ;
|
||||
- `0.12.x` : autres routers/protocoles prioritaires ;
|
||||
- `0.13.x` : transports temps réel ;
|
||||
- `0.14.x` : workers et applications consommatrices ;
|
||||
- `0.15.x` : programmes SPL et Metaplex complémentaires reportés ;
|
||||
- `0.16.x+` : extensions futures et éventuel `kb-offchain-transport`.
|
||||
|
||||
Ne pas réintroduire en `0.6.x` une couverture exhaustive des programmes SPL ou Metaplex qui a été explicitement reportée.
|
||||
|
||||
## Discipline des scénarios et validations
|
||||
|
||||
Pour toute nouvelle capacité exécutable :
|
||||
|
||||
1. tests contractuels et synthétiques ;
|
||||
2. logique de scénario réutilisable dans `kb-pipeline-demo-scenarios` ;
|
||||
3. simulation RPC exacte ;
|
||||
4. soumission Devnet/Testnet lorsque sûre et disponible ;
|
||||
5. postconditions et matérialisation observables ;
|
||||
6. panneau desktop seulement comme adaptateur opérateur ;
|
||||
7. statut de qualification explicite et jamais promu depuis une preuve synthétique seule.
|
||||
|
||||
Les scénarios déjà qualifiés ne doivent pas être rejoués automatiquement à chaque refactor si aucune frontière qu’ils couvrent n’a changé.
|
||||
|
||||
## 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 de la version ;
|
||||
- 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.
|
||||
|
||||
## Dernière prerelease obligatoire
|
||||
|
||||
La dernière prerelease de `0.5.0` devra :
|
||||
|
||||
- exécuter les validations finales ;
|
||||
- corriger les écarts résiduels ;
|
||||
- finaliser README, ROADMAP, changelogs, TODO et guides 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 de la session suivante ;
|
||||
- préparer la release finale sans introduire une nouvelle fonctionnalité structurelle majeure.
|
||||
|
||||
## 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
|
||||
```
|
||||
466
prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md
Normal file
466
prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md
Normal file
@@ -0,0 +1,466 @@
|
||||
<!-- file: prompts/030_v0_5_1_khadhroony_solana_namespace_and_config.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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 namespace d'environnement `KS_*`, 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 `KS_*` ;
|
||||
- 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.
|
||||
|
||||
## 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. `config/example.config.json`, `config/schema.config.json`, `.env.example` et tous les exemples/configurations de test ;
|
||||
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 et leur nouveau nom `KS_*` ;
|
||||
- la classification de chaque variable en `KS_SECRET_*`, `KS_PUBLIC_*` ou `KS_*` interne ;
|
||||
- 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
|
||||
|
||||
Après migration, toute variable d'environnement appartenant au workspace doit commencer par `KS_`.
|
||||
|
||||
La convention retenue est :
|
||||
|
||||
```text
|
||||
KS_SECRET_* secret absolu
|
||||
KS_PUBLIC_* valeur explicitement candidate à une surface publique
|
||||
KS_* valeur interne/diagnostique
|
||||
```
|
||||
|
||||
Une ancienne variable `KB_*` ou une variable projet sans préfixe `KS_` ne doit pas subsister dans le code, les exemples, tests ou documentation après fermeture de la migration.
|
||||
|
||||
Les variables du système d'exploitation ou de dépendances tierces ne sont pas renommées artificiellement si elles ne constituent pas un contrat de configuration Khadhroony.
|
||||
|
||||
### `KS_SECRET_*`
|
||||
|
||||
Une valeur issue de `KS_SECRET_*` :
|
||||
|
||||
- peut être utilisée côté backend lorsque nécessaire ;
|
||||
- ne doit jamais apparaître dans les logs ;
|
||||
- ne doit jamais apparaître dans une erreur publique ;
|
||||
- ne doit jamais être sérialisée vers Tauri ;
|
||||
- ne doit jamais être exposée dans un diagnostic, même debug ;
|
||||
- ne doit jamais être exportée par TS-RS comme valeur résolue ;
|
||||
- doit rester secrète lorsqu'elle est incorporée dans une URL, DSN ou autre valeur composée.
|
||||
|
||||
Un diagnostic peut indiquer qu'un secret est configuré ou absent sans exposer sa valeur.
|
||||
|
||||
### `KS_PUBLIC_*`
|
||||
|
||||
Le préfixe `KS_PUBLIC_*` classe la variable comme publiable, mais ne constitue pas une autorisation automatique de parcourir l'environnement et de l'envoyer au frontend.
|
||||
|
||||
L'exposition doit être explicitement définie par un DTO ou une API publique.
|
||||
|
||||
### autres `KS_*`
|
||||
|
||||
Les autres variables `KS_*` sont internes. Elles ne sont pas exposées par les payloads normaux. Elles peuvent apparaître dans un diagnostic explicitement demandé lorsque leur sémantique n'est pas sensible.
|
||||
|
||||
Le simple fait de compiler en mode debug ne doit pas automatiquement exposer toutes les valeurs internes.
|
||||
|
||||
## 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_*}` ;
|
||||
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_*` 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_*` n'est exposé que par une surface explicitement autorisée ;
|
||||
- une variable `KS_*` interne 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 et environnement `KS_*`
|
||||
|
||||
- migrer les targets/processor identities généralistes ;
|
||||
- migrer les variables d'environnement ;
|
||||
- mettre en place la classification Secret/Public/Internal ;
|
||||
- mettre à jour exemples et tests sans encore réinventer le store SQL.
|
||||
|
||||
### `0.5.1-pre.004` — split configuration/logging
|
||||
|
||||
- documents et schémas indépendants ;
|
||||
- profils logging indépendants ;
|
||||
- propriété unique des contrats logging ;
|
||||
- migration/compatibilité explicite des fichiers `0.5.0`.
|
||||
|
||||
### `0.5.1-pre.005` — runtime/public et Tauri sûr
|
||||
|
||||
- séparer source/runtime/public ;
|
||||
- supprimer les payloads de config complète ;
|
||||
- diagnostics sûrs ;
|
||||
- tests de non-divulgation ;
|
||||
- TS-RS aligné.
|
||||
|
||||
### `0.5.1-pre.006` — réconciliation et clôture
|
||||
|
||||
- audit exhaustif des anciens préfixes ;
|
||||
- documentation finale ;
|
||||
- TODO/changelogs ;
|
||||
- validations workspace ;
|
||||
- archivage du plan/prompt ;
|
||||
- préparation de `0.5.2`.
|
||||
|
||||
Ce découpage peut évoluer si `pre.001` démontre qu'une étape doit être scindée pour garder chaque prerelease compilable et bornée.
|
||||
|
||||
## 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
|
||||
```
|
||||
Reference in New Issue
Block a user