v0.1.0-pre.055

2026-07-26 13:58:14 +02:00
parent 068eb9ece5
commit a3ce8d733f
44 changed files with 7507 additions and 8271 deletions
--- a/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md
+++ b/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md
@@ -0,0 +1,761 @@
+# Prompt de reprise — clôture migration `khadhroony-bot3`
+
+## 1. Mission
+
+Poursuivre et clôturer la migration de `khadhroony-bot2` vers `khadhroony-bot3`.
+
+Objectif fonctionnel intermédiaire :
+
+- revenir d’abord à un niveau de couverture équivalent à `0.4.6` de Bot2 ;
+- terminer ensuite le travail Metaplex Token Metadata commencé mais non achevé dans `0.4.7` de Bot2 ;
+- seulement après cela, finaliser Clippy/Tauri, la documentation et le passage de Bot3 à `0.4.7`.
+
+Ne pas déclarer la migration terminée avant validation complète des critères de clôture.
+
+---
+
+## 2. Revalidation initiale obligatoire des règles
+
+Avant toute modification de code :
+
+1. relire intégralement :
+   - `RULES.md`
+   - `RUST_RULES.md`
+   - `README.md`
+   - `ROADMAP.md`
+   - `CHANGELOG.md`
+   - le présent prompt ;
+2. comparer les règles Bot2 encore applicables avec les règles Bot3 ;
+3. vérifier qu’aucune règle de migration récente n’est absente ou contradictoire ;
+4. vérifier en particulier :
+   - conventions de noms ;
+   - façades `kb-lib` et `kb-store` ;
+   - ordre des imports et réexports ;
+   - interdiction de `unsafe`, `unwrap`, `expect`, `panic`, `anyhow`, `thiserror` ;
+   - règles Tauri ;
+   - conventions TS-RS ;
+   - conventions de logging ;
+   - règles d’archives delta ;
+   - politique de versionnement ;
+5. corriger les documents de règles avant le code si une divergence est détectée ;
+6. lancer immédiatement :
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+```
+
+L’objectif est d’éviter de refaire plusieurs fois les mêmes corrections structurelles plus tard.
+
+---
+
+## 3. Architecture consolidée
+
+Crates principales :
+
+```text
+kb-config
+kb-core
+kb-lib
+kb-logging
+kb-onchain-transport
+kb-pipeline
+kb-pipeline-demo-scenarios
+kb-program-ids
+kb-store
+kb-wallet
+kb-app-demo-desktop
+```
+
+Règles :
+
+- `kb-store` remplace `kb_store_core` et `kb_store_pg`.
+- Modèles, décodeurs, matérialiseurs et exécuteurs sont sous `kb-lib`.
+- Les modules Rust Token-2022 utilisent `token2022`, jamais `token_2022`.
+- Les variables externes historiques comme `TOKEN_2022_*` peuvent rester si elles constituent un contrat opératoire.
+- Les fenêtres dynamiques vont dans `capabilities/default.json` et `vite.config.ts`.
+- Elles ne vont pas dans `tauri.conf.json`, sauf `splash` et `main`.
+- Toutes les fenêtres doivent avoir la permission de logging/tracing.
+- Livrer des ZIP delta, sans `Cargo.lock` ni SHA256.
+- Les correctifs utilisent `delta-fix-XXX`, avec reprise à `fix-001` pour chaque prerelease.
+
+---
+
+## 4. État déjà atteint
+
+Fenêtres migrées / non testées completement :
+
+- splash ;
+- main ;
+- configuration ;
+- HTTP JSON-RPC ;
+- WebSocket ;
+- backfill HTTP ;
+- SQL diagnostics ;
+- PostgreSQL raw ;
+- PostgreSQL core ;
+- SQL replay candidates ;
+- extraction core ;
+- decode replay / matérialisation ;
+- exécution Solana Core ;
+- exécution SPL ;
+- SPL ATA ;
+- SPL Token classique ;
+- SPL Token-2022.
+
+Dépendances déjà présentes :
+
+```text
+kb-lib
+kb-program-ids
+kb-pipeline-demo-scenarios
+kb-store
+kb-wallet
+```
+
+Le `.env` est désormais chargé par `kb-config`.
+
+Ordre de résolution attendu :
+
+1. environnement du processus ;
+2. fichier indiqué par `KB_ENV_FILE` ;
+3. sinon `.env` à la racine du workspace ;
+4. fallback `${VARIABLE:-valeur}` ;
+5. absence non fatale pour les services optionnels jusqu’à leur utilisation.
+
+`HELIUS_API_KEY` fonctionne depuis `.env`.
+
+Décodeur Metaplex enregistré sous :
+
+```text
+metadata_metaplex_token_metadata
+```
+
+Program ID :
+
+```text
+metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
+```
+
+L’IDL Metaplex Token Metadata est déjà présent dans `idl`. Ne pas le retélécharger.
+
+---
+
+## 5. Contrôles rapides et prise en main du code
+
+### 5.1 Audit TS-RS
+
+Auditer uniquement les `.rs` :
+
+```bash
+find kb-config kb-lib kb-app-demo-desktop   -type f -name '*.rs' -print0 |
+xargs -0 grep -n 'export_to'
+```
+
+Chemins attendus :
+
+```text
+../frontend/ts/bindings/kb_config/...
+../frontend/ts/bindings/kb_lib/...
+../frontend/ts/bindings/kb_app_demo_desktop/...
+```
+
+Supprimer les chemins historiques :
+
+```text
+kb_executor_*
+kb_decoder_*
+kb_materializer_*
+kb_model
+kb_store_pg
+kb_store_core
+kb_lib_executor_*
+kb_executor_spl_token_2022
+```
+
+Vérifier que les tests TS-RS régénèrent les fichiers attendus.
+
+### 5.2 Audit des anciens chemins Bot2
+
+```bash
+find kb-app-demo-desktop   -type f -name '*.rs' -print0 |
+xargs -0 grep -nE   'kb_store_pg|kb_store_core|kb_model|kb_decoder_|kb_materializer_|kb_executor_|token_2022'
+```
+
+Toute occurrence doit être justifiée ou supprimée.
+
+### 5.3 Audit rapide HTML Copier/Effacer
+
+```bash
+find kb-app-demo-desktop/frontend   -type f -name '*.html' -print0 |
+xargs -0 grep -nE 'Copier|Effacer'
+```
+
+Vérifier :
+
+- exactement un bouton Copier ;
+- exactement un bouton Effacer ;
+- aucun doublon entre HTML statique et helper TypeScript ;
+- journaux globaux hors accordéon.
+
+### 5.4 Menu principal
+
+Ordre attendu :
+
+1. Configuration
+2. Transport et collecte
+3. Pipeline
+4. SQL
+5. Exécution
+
+Vérifier labels, séparateurs, entrées mortes et fenêtres oubliées.
+
+---
+
+## 6. Corrections UI rapides
+
+### `demo_http`
+
+Le bloc `Résultat` ne doit pas utiliser `@andypf/json-viewer`.
+
+À faire :
+
+- remettre un `<textarea readonly>` ;
+- hauteur fixe ;
+- scroll interne ;
+- exactement un bouton Copier ;
+- exactement un bouton Effacer ;
+- l’effacement doit vider aussi le buffer TypeScript.
+
+### `demo_ws`
+
+Le bloc `Messages` doit être un affichage texte/log.
+
+À faire :
+
+- utiliser un `<textarea>` ou composant log ;
+- hauteur fixe et scroll interne ;
+- exactement une paire Copier/Effacer ;
+- conserver les messages si la fenêtre est fermée puis rouverte tant que la session reste active.
+
+### Journaux généraux
+
+Vérifier au minimum :
+
+- Backfill HTTP ;
+- Extraction core ;
+- Exécution Solana Core ;
+- Exécution SPL ;
+- Decode replay ;
+- HTTP ;
+- WebSocket.
+
+Règle générale :
+
+- paramètres dans les accordéons ;
+- journaux et résultats globaux sous les accordéons ;
+- hauteur fixe ;
+- scroll interne ;
+- boutons toujours accessibles.
+
+### JSON viewers
+
+- `@andypf/json-viewer` uniquement pour du JSON structuré ;
+- `<textarea>` pour texte brut, logs, messages, sorties non JSON et diagnostics concaténés ;
+- hauteur fixe et scroll interne pour tous les viewers JSON.
+
+### Fenêtres SQL
+
+Sauf Replay Candidates :
+
+- contenu sur toute la largeur ;
+- pas de split en deux colonnes ;
+- table sur toute la largeur ;
+- éviter le scroll horizontal global ;
+- wrapper responsive uniquement autour de la table ;
+- vérifier les balises HTML ;
+- vérifier boutons, tabs et liens.
+
+---
+
+## 7. `.env` et configuration
+
+`kb-config` doit rester seul responsable de :
+
+- recherche du `.env` ;
+- chargement sans écraser l’environnement du processus ;
+- `${VAR}` ;
+- `${VAR:-fallback}` ;
+- diagnostics sans secrets ;
+- tests ;
+- documentation publique.
+
+Les crates métier ne doivent pas charger `.env`.
+
+`kb-pipeline-demo-scenarios` peut appeler un point d’initialisation commun, mais ne doit pas dépendre directement de `dotenvy`.
+
+Backlog futur :
+
+- étudier la résolution du chemin/URL de base de données côté `kb-store`.
+
+---
+
+## 8. Logging
+
+La console doit rester active pour :
+
+- `local_devnet` ;
+- `mainnet_research` ;
+- `mainnet`.
+
+Supprimer les routes Bot2 obsolètes.
+
+Cibles consolidées attendues :
+
+```text
+kb-lib.decoder.*
+kb-lib.executor.*
+kb-lib.materializer.*
+kb-store
+kb-config
+kb-logging
+kb-onchain-transport
+kb-pipeline
+kb-wallet
+kb-app-demo-desktop
+```
+
+Ne pas recréer les anciens dossiers de crates supprimées.
+
+Backlog non bloquant :
+
+- séparer ultérieurement les logs `kb-store` entre `core` et `postgres`.
+
+---
+
+## 9. Options SPL et variables Token-2022
+
+Auditer :
+
+```text
+kb-app-demo-desktop/frontend/demo_execution_spl.html
+kb-app-demo-desktop/src/tauri.rs
+```
+
+Vérifier que chaque option HTML correspond à un scénario réellement supporté.
+
+Éliminer les valeurs internes `token_2022` au profit de `token2022`, sauf contrat externe explicite.
+
+Pour chaque variable `TOKEN_2022_*`, décider :
+
+- compatibilité externe à conserver ;
+- déplacement éventuel vers configuration ;
+- remplacement futur par structure typée ;
+- usage limité aux scénarios de démonstration.
+
+Documenter la décision.
+
+---
+
+## 10. WebSocket
+
+Comportement obligatoire :
+
+- aucun pool WebSocket au démarrage ;
+- création paresseuse au premier accès à `demo_ws` ;
+- pool conservé dans `AppState` ;
+- session conservée si la fenêtre est fermée ;
+- état récupéré à la réouverture ;
+- fermeture seulement par :
+  - commande explicite ;
+  - timeout ;
+  - arrêt global de l’application.
+
+La fermeture de `demo_ws` ne doit pas appeler la déconnexion globale.
+
+---
+
+## 11. Initialisation PostgreSQL au lancement
+
+L’initialisation PostgreSQL doit être faite au lancement de `kb-app-demo-desktop`, comme dans Bot2.
+
+Ordre attendu :
+
+1. environnement ;
+2. configuration ;
+3. logging ;
+4. pool HTTP ;
+5. connexion PostgreSQL ;
+6. vérification/initialisation du schéma ;
+7. rapport des tables ;
+8. ouverture de `main` ;
+9. destruction du splash.
+
+Fonctions existantes à raccorder :
+
+```text
+initialize_postgres_schema_for_startup
+emit_sql_startup_table_report
+emit_sql_startup_error
+emit_sql_startup_splash
+```
+
+### Splashscreen
+
+Problème observé : seuls les messages du haut sont visibles.
+
+À corriger :
+
+- zone de messages scrollable ;
+- hauteur adaptée ;
+- dernier message visible ;
+- progression lisible ;
+- ne pas afficher d’initialisation WebSocket ;
+- afficher :
+  - connexion PostgreSQL ;
+  - schéma vérifié ou initialisé ;
+  - nombre de tables ;
+  - tables manquantes éventuelles ;
+  - statut final.
+
+---
+
+## 12. PostgreSQL — purge des données dérivées
+
+Objectif : conserver uniquement les données raw, puis tout reconstruire par replay.
+
+Ne pas supprimer :
+
+- transactions raw ;
+- signatures raw ;
+- payloads RPC raw ;
+- données nécessaires à l’extraction et au replay.
+
+Purger les tables dérivées liées notamment à :
+
+- core extraction ;
+- decoded events ;
+- observations ;
+- coverage ;
+- diagnostics ;
+- replay state dérivé ;
+- annotations ;
+- materialized events ;
+- token accounts ;
+- lifecycle ;
+- admin ;
+- fees ;
+- risk ;
+- compliance ;
+- staking ;
+- autres projections générées.
+
+Avant purge :
+
+1. inventorier les tables via `kb-store` ;
+2. distinguer précisément raw et dérivé ;
+3. préparer un script SQL versionné et idempotent ;
+4. documenter les tables conservées ;
+5. exécuter dans une transaction ;
+6. prévoir des vérifications avant/après ;
+7. ne rien supprimer si le périmètre est ambigu.
+
+Après purge :
+
+1. extraction core ;
+2. replay de tous les décodeurs ;
+3. matérialisation ;
+4. validation des compteurs ;
+5. validation des erreurs ;
+6. contrôle de reconstruction des tables.
+
+---
+
+## 13. Retour au niveau fonctionnel `0.4.6`
+
+Avant de poursuivre Metaplex, valider que Bot3 couvre correctement tout ce qui était fonctionnel dans Bot2 `0.4.6` :
+
+- Solana Core ;
+- SPL Memo ;
+- SPL Token classique ;
+- SPL ATA ;
+- SPL Token-2022 ;
+- ElGamal Registry ;
+- backfill ;
+- extraction core ;
+- replay ;
+- matérialisation ;
+- exécution supportée ;
+- validations devnet déjà existantes ;
+- transport HTTP et WebSocket ;
+- PostgreSQL ;
+- logging ;
+- configuration.
+
+Cette étape doit être explicitement considérée comme un jalon de migration.
+
+---
+
+## 14. Inventaire des IDL
+
+Créer :
+
+```text
+docs/IDL_SOURCES.md
+```
+
+Pour chaque IDL :
+
+- protocole ;
+- program ID ;
+- lien officiel ;
+- version ou commit ;
+- chemin local ;
+- statut ;
+- usage ;
+- notes de compatibilité.
+
+Ne pas inventer d’IDL lorsqu’il n’en existe pas.
+
+L’IDL Metaplex Token Metadata existe déjà localement : le référencer, ne pas le retélécharger.
+
+---
+
+## 15. Metaplex Token Metadata — décodage
+
+Ce bloc vient après le retour au niveau fonctionnel `0.4.6`.
+
+Des échecs réels ont été observés après backfill Metaplex.
+
+Cas signalés :
+
+- `create_metadata_account_v3` ;
+- `transfer`.
+
+Cause probable : attentes incorrectes sur les flags signer/writable des metas.
+
+Travail :
+
+1. extraire toutes les erreurs Metaplex ;
+2. regrouper par instruction ;
+3. comparer runtime, IDL local, builders et interface officielle ;
+4. corriger la matrice de comptes ;
+5. distinguer instructions valides, transactions échouées, payloads tronqués, variantes inconnues, comptes optionnels et legacy ;
+6. ajouter des tests depuis les transactions réelles ;
+7. relancer le replay ;
+8. obtenir zéro faux échec de metas.
+
+---
+
+## 16. Exécuteur Metaplex et démos devnet
+
+Le passage à `0.4.7` exige que l’exécuteur Metaplex Token Metadata soit terminé.
+
+À compléter :
+
+- intents typés ;
+- builders ;
+- comptes ordonnés ;
+- signers ;
+- writable flags ;
+- variantes supportées ;
+- politiques de sécurité ;
+- simulation-first ;
+- estimation des coûts ;
+- validation post-exécution ;
+- tests unitaires ;
+- comparaison avec builders officiels ;
+- matrice de couverture.
+
+Ajouter des scénarios devnet bornés dans `kb-app-demo-desktop` et/ou `kb-pipeline-demo-scenarios`.
+
+Ils doivent :
+
+- utiliser uniquement un profil devnet explicite ;
+- ne jamais exécuter par défaut sur mainnet ;
+- simuler avant envoi ;
+- afficher le plan ;
+- afficher les signers ;
+- afficher le résultat ;
+- effectuer un replay post-exécution ;
+- vérifier décodage et matérialisation ;
+- afficher les diagnostics.
+
+---
+
+## 17. Clippy et Tauri
+
+Les erreurs `clippy::question_mark_used` issues des macros async Tauri sont à traiter après tout le fonctionnel, y compris Metaplex.
+
+Ne pas bloquer le débogage dessus.
+
+À la fin :
+
+1. solution locale cohérente ;
+2. éviter un `allow` global ;
+3. documenter la contradiction macro/règle ;
+4. obtenir un Clippy propre ou un écart précisément borné.
+
+---
+
+## 18. Refonte documentaire après migration
+
+Ne pas commencer la refonte complète avant validation fonctionnelle, y compris Metaplex.
+
+### Versionnement
+
+Passer à :
+
+```text
+0.4.7
+```
+
+uniquement si :
+
+- niveau fonctionnel `0.4.6` restauré et validé ;
+- migration validée ;
+- bugs majeurs corrigés ;
+- exécuteur Metaplex terminé ;
+- démos devnet Metaplex présentes ;
+- replay et matérialisation validés ;
+- documentation refondue.
+
+### README
+
+Les README doivent devenir génériques.
+
+Ils ne doivent pas :
+
+- servir de changelog ;
+- contenir des numéros de version ;
+- raconter Bot2 → Bot3 ;
+- décrire les prereleases.
+
+Ils doivent présenter :
+
+- objectif ;
+- rôle architectural ;
+- dépendances ;
+- aperçu minimal ;
+- liens vers la documentation détaillée.
+
+### `USAGES.md`
+
+Créer un `USAGES.md` pour chaque crate publique.
+
+Contenu :
+
+- APIs publiques ;
+- types ;
+- traits ;
+- fonctions ;
+- builders ;
+- exemples ;
+- invariants ;
+- erreurs ;
+- limites ;
+- intégrations.
+
+### Roadmap par crate
+
+Ajouter un roadmap par crate seulement si utile.
+
+### Continuité du projet
+
+Après refonte, on ne doit presque plus sentir la transition Bot2 → Bot3.
+
+Seule une courte note historique éventuelle est acceptable.
+
+---
+
+## 19. Commandes de validation
+
+```bash
+cargo fmt --all
+
+cargo check -p kb-config
+cargo test -p kb-config
+
+cargo check -p kb-pipeline-demo-scenarios
+cargo test -p kb-pipeline-demo-scenarios
+
+cargo check -p kb-store
+cargo test -p kb-store
+
+cargo check -p kb-lib
+cargo test -p kb-lib
+
+cargo check -p kb-app-demo-desktop
+cargo test -p kb-app-demo-desktop
+
+cargo check --workspace
+cargo test --workspace
+
+python3 scripts/audit_rust_workspace_rules.py
+```
+
+Runtime :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+Clippy en dernier :
+
+```bash
+cargo clippy --all-targets
+```
+
+---
+
+## 20. Critères de clôture
+
+- [ ] règles relues et revalidées ;
+- [ ] toutes les crates compilent ;
+- [ ] tous les tests workspace passent ;
+- [ ] audit Rust propre ;
+- [ ] aucun chemin Bot2 supprimé ;
+- [ ] audit TS-RS propre ;
+- [ ] toutes les fenêtres fonctionnent ;
+- [ ] WebSocket persistant après fermeture de `demo_ws` ;
+- [ ] `.env` chargé par `kb-config` avec priorité correcte ;
+- [ ] Helius réellement validé ;
+- [ ] PostgreSQL initialisé au démarrage ;
+- [ ] splash PostgreSQL lisible ;
+- [ ] données dérivées purgées ;
+- [ ] données dérivées reconstruites par replay ;
+- [ ] niveau fonctionnel `0.4.6` restauré ;
+- [ ] bons composants pour JSON et texte ;
+- [ ] aucun bouton Copier/Effacer dupliqué ;
+- [ ] journaux généraux hors accordéon ;
+- [ ] fenêtres SQL correctement dimensionnées ;
+- [ ] routes de logs obsolètes supprimées ;
+- [ ] console active ;
+- [ ] inventaire IDL documenté ;
+- [ ] aucun faux échec Metaplex sur les metas ;
+- [ ] exécuteur Metaplex terminé ;
+- [ ] démos devnet Metaplex validées ;
+- [ ] Clippy/Tauri finalisés ;
+- [ ] refonte documentaire terminée ;
+- [ ] `USAGES.md` présent pour chaque crate publique ;
+- [ ] passage à `0.4.7` justifié.
+
+---
+
+## 21. Mode de travail
+
+- Commencer chaque session par la relecture des règles.
+- Traiter d’abord les contrôles rapides.
+- Conserver un ordre logique de dépendances.
+- Revenir au niveau fonctionnel `0.4.6` avant de terminer Metaplex.
+- Traiter Metaplex avant Clippy/Tauri et la documentation.
+- Travailler par deltas courts.
+- Ne jamais réintroduire les anciennes crates Bot2.
+- Vérifier les APIs réelles avant de porter du code.
+- Utiliser `kb-store` et `kb-lib`.
+- Corriger immédiatement les erreurs locales remontées.
+- Ne pas masquer les erreurs métier par des `allow`.
+- Maintenir `delta.md`, changelog et documentation de session.
+- Fournir une archive delta à chaque tranche.
+- Utiliser `delta-fix-XXX` pour les correctifs.
+- Ne pas livrer d’archive complète sauf demande explicite.