khadhroony-bot3/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md

# 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`
   - `RULES_GENERAL.md`
   - `RULES_RUST.md`
   - `RULES_SPECIFIC_KHADHROONY.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.

---


### État `pre.060` des outils de replay

- plafond temporaire des listes SQL : `100000`;
- vraie pagination SQL/IPC reportée mais obligatoire avant les volumes massifs;
- export CSV ancré sur `<workspace>/data/exports_csv`;
- Program ID de Decode replay libre avec autocomplétion issue de `kb-program-ids`.

## 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.

---


### État validé après `0.1.0-pre.058`

- `cargo test -p kb-app-demo-desktop` : 115 tests réussis ;
- `cargo check --workspace` : réussi ;
- audit Rust : propre ;
- fenêtres Configuration, HTTP, WebSocket, Backfill et SQL validées visuellement ;
- persistance WebSocket, limitation UI et encodage Base64 automatique validés ;
- `autoInitializeSchema` reste volontairement à `false` pour `mainnet_research` ;
- le câblage statique de System transfer, Memo, SPL Token, ATA et Token-2022 vers `kb-pipeline-demo-scenarios` est confirmé ;
- `execute_devnet_spl_token_lifecycle` reste à raccorder ou à documenter comme scénario non exposé.

### Tranche Tauri en cours

- les ouvertures de fenêtres doivent utiliser un helper privé commun strictement Tauri ;
- les commandes Extraction core doivent déléguer à `demo_core_extraction.rs` ;
- poursuivre ensuite avec Decode replay, Backfill, SQL replay et Exécution ;
- les helpers de `tauri.rs` sont autorisés uniquement pour l’adaptation Tauri mutualisée et ne portent aucune logique métier.

## 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.