khadhroony-bot3/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md

Khadhroony Bot3 — Checklist de clôture de la migration

Périmètre : clôturer la migration de khadhroony-bot2 vers khadhroony-bot3, stabiliser kb-app-demo-desktop et valider l’intégration des crates consolidées.

Base de suivi : 0.1.0-pre.055 et correctifs suivants.

Règle d’utilisation : cocher chaque case uniquement après validation locale explicite. Les sous-cases constituent les critères d’acceptation de la tâche parente.

---

0. État validé à ce jour

• Les fenêtres historiques principales ont été portées dans kb-app-demo-desktop.
• Les décodeurs, modèles, matérialiseurs et exécuteurs sont consommés depuis kb-lib.
• kb-store-core et kb-store-pg ont été fusionnés dans kb-store.
• kb-program-ids est une dépendance explicite du desktop.
• kb-pipeline-demo-scenarios est une dépendance explicite du desktop.
• Le pool WebSocket n’est plus initialisé au démarrage de l’application.
• Le pool WebSocket est créé paresseusement à l’ouverture/utilisation de demo_ws.
• La session WebSocket survit à la fermeture de la fenêtre demo_ws.
• La réouverture de demo_ws récupère l’état de la session existante.
• La clé HELIUS_API_KEY chargée depuis .env permet une connexion Helius réelle.
• Les fenêtres dynamiques sont déclarées dans vite.config.ts et capabilities/default.json, sans être ajoutées à tauri.conf.json.
• La permission de logging est attribuée aux fenêtres dynamiques.
• Les balises HTML mal imbriquées qui rechargeaient main.html ont été corrigées.
• Les routes de fichiers de logs consolidées produisent une arborescence cohérente.
• L’audit Rust global est propre sur la base testée :
  • General Rust rule audit: clean
  • Rust export completeness audit: 0 candidate(s)
  • Khadhroony workspace rule audit: clean

---

1. Corriger immédiatement les deux afficheurs non JSON

1.1 Fenêtre HTTP JSON-RPC

• Remplacer le @andypf/json-viewer du bloc Résultat par un <textarea readonly>.
• Conserver le résultat RPC sous sa forme textuelle exacte, sans supposer qu’il s’agit toujours de JSON.
• Ajouter exactement un bouton Copier utilisant le presse-papiers.
• Ajouter exactement un bouton Effacer.
• S’assurer que l’effacement vide également le buffer TypeScript interne.
• Donner au textarea une hauteur fixe et un scroll interne.
• Tester successivement :
  • réponse JSON structurée ;
  • valeur scalaire ;
  • chaîne simple ;
  • erreur RPC ;
  • résultat vide.

1.2 Fenêtre WebSocket

• Remplacer le @andypf/json-viewer du bloc Messages par un <textarea readonly>.
• Conserver les messages sous forme de journal texte append-only.
• Ajouter exactement un bouton Copier.
• Ajouter exactement un bouton Effacer.
• S’assurer que l’effacement vide le buffer en mémoire et le contenu visible.
• Donner au textarea une hauteur fixe et un scroll interne.
• Vérifier que la réouverture de la fenêtre restaure :
  • l’état de connexion ;
  • les abonnements actifs ;
  • le statut de session ;
  • le journal conservé, si cette conservation est voulue.

---

2. Audit global des composants Copier / Effacer

• Rechercher tous les boutons statiques et boutons injectés dynamiquement :

find kb-app-demo-desktop/frontend \
  -type f \( -name '*.html' -o -name '*.ts' \) -print0 |
xargs -0 grep -nE 'Copier|Effacer|clipboard|app-log-clear|attach.*controls'

• Pour chaque bloc de journal ou résultat textuel, garantir une seule paire Copier/Effacer.
• Interdire la coexistence de boutons HTML statiques et de boutons ajoutés par frontend_log.ts sur le même composant.
• Vérifier au minimum :
  • demo_backfill ;
  • demo_core_extraction ;
  • demo_http ;
  • demo_ws ;
  • demo_decode_replay ;
  • demo_execution_solana_core ;
  • demo_execution_spl ;
  • fenêtres SQL ;
  • configuration.
• Ajouter un test frontend ou une vérification statique qui échoue lorsqu’un conteneur reçoit plusieurs groupes de contrôles.

---

3. Uniformiser la position des journaux généraux

• Le journal du Backfill HTTP est placé hors de l’accordéon.
• Le journal d’Extraction core est placé hors de l’accordéon.
• Vérifier que tous les journaux généraux restent visibles lorsque les sections de paramètres sont repliées.
• Déplacer hors des accordéons tout journal général encore imbriqué dans une section de paramètres.
• Conserver dans les accordéons uniquement les sorties strictement liées à une opération ou à un sous-panneau particulier.
• Documenter une règle UI :
  • paramètres et formulaires dans les accordéons ;
  • journal global et résultat principal sous l’accordéon ;
  • hauteur fixe avec scroll ;
  • une seule paire Copier/Effacer.

---

4. Politique JSON commune

• Utiliser @andypf/json-viewer uniquement lorsque la valeur affichée est garantie comme JSON.
• Utiliser un textarea readonly pour :
  • journaux ;
  • flux de messages ;
  • texte brut ;
  • réponses dont le format varie ;
  • erreurs non structurées.
• Centraliser la création et la mise à jour des viewers JSON dans un helper TypeScript commun.
• Appliquer une hauteur fixe à tous les viewers JSON.
• Appliquer un scroll interne au-delà de la hauteur maximale.
• Éviter qu’un collapse contenant du JSON agrandisse indéfiniment .card-body.
• Vérifier tous les viewers présents dans :
  • Configuration ;
  • SQL diagnostics ;
  • Decode replay ;
  • exécutions ;
  • autres vues structurées.
• Prévoir une règle pour les valeurs JSON invalides : fallback texte, sans crash de la fenêtre.

---

5. Stabiliser les fenêtres SQL

5.1 Layout

• Restaurer une disposition pleine largeur pour :
  • SQL diagnostics ;
  • PostgreSQL raw ;
  • PostgreSQL core.
• Ne pas splitter les tableaux principaux en deux colonnes.
• Réserver les colonnes uniquement aux petits panneaux synthétiques si nécessaire.
• Supprimer le scroll horizontal global de la page.
• Autoriser un scroll horizontal local uniquement dans .table-responsive lorsque réellement nécessaire.
• Vérifier que le listing des tables utilise toute la largeur disponible.
• Comparer le rendu avec Bot2 pour éviter une régression fonctionnelle ou ergonomique.

5.2 Navigation et IPC

• Les balises de navbar mal fermées ont été corrigées.
• Vérifier chaque bouton et chaque onglet des quatre fenêtres SQL.
• Confirmer qu’aucune action ne recharge main.html.
• Confirmer qu’aucun clic ne déclenche une navigation implicite via un <a> parent.
• Vérifier les formulaires et boutons sans type="button" susceptibles de soumettre un formulaire.
• Revalider les appels IPC lors de rechargements Vite, sans considérer l’ancien défaut comme actif s’il n’est plus reproductible.

5.3 Initialisation PostgreSQL

• Décider définitivement quand exécuter initialize_postgres_schema_for_startup :
  • au démarrage avec compte rendu dans le splash ; ou
  • à la première ouverture d’une fenêtre SQL.
• Supprimer le code mort si l’initialisation de démarrage est abandonnée.
• Sinon, brancher réellement :
  • initialize_postgres_schema_for_startup ;
  • emit_sql_startup_table_report ;
  • emit_sql_startup_error ;
  • emit_sql_startup_splash.
• Ne pas conserver durablement des helpers publics ou pub(crate) inutilisés.
• Ajouter des tests de schéma présent, incomplet et inaccessible.

---

6. Corriger les échecs Metaplex Token Metadata

6.1 Constat issu des logs pre.055

• Le pipeline sélectionne correctement le décodeur metadata_metaplex_token_metadata.
• Le programme canonique est reconnu :

metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s

• L’archive analysée contient 10 échecs explicites de validation de comptes :
  • 8 create_metadata_account_v3 account 1 has invalid signer/writable flags ;
  • 2 transfer account 1 has invalid signer/writable flags.

6.2 Diagnostic à effectuer

• Extraire pour chaque transaction échouée :
  • signature ;
  • slot ;
  • chemin d’instruction ;
  • instruction outer/inner ;
  • données brutes ;
  • liste ordonnée des comptes ;
  • flags signer/writable réellement reconstruits.
• Vérifier si account 1 désigne :
  • l’index dans les comptes de l’instruction ;
  • l’index global du message ;
  • un index décalé par le program ID ;
  • un compte issu d’une Address Lookup Table.
• Vérifier la reconstruction des flags pour :
  • comptes statiques ;
  • comptes chargés par ALT ;
  • instructions internes ;
  • comptes dupliqués ;
  • invocation CPI.
• Comparer les contrats du décodeur avec :
  • l’IDL officiel token_metadata.json ;
  • les builders/generated instructions Metaplex ;
  • des transactions mainnet réelles.
• Vérifier si les contraintes imposées sont trop strictes pour les CPI, notamment lorsqu’un programme appelant transmet un compte avec des privilèges supérieurs ou différents.
• Distinguer clairement :
  • compte absent ;
  • nombre de comptes invalide ;
  • signer manquant ;
  • writable manquant ;
  • privilège supplémentaire acceptable ;
  • privilège incompatible.

6.3 Correctif et tests

• Corriger la matrice de comptes de create_metadata_account_v3.
• Corriger la matrice de comptes de transfer.
• Ajouter les transactions réelles de l’archive comme fixtures bornées ou vecteurs synthétiques équivalents.
• Ajouter un test de CPI pour chaque instruction concernée.
• Ajouter un test avec Address Lookup Table si applicable.
• Ajouter un test où un compte possède un privilège supérieur acceptable.
• Ajouter un test qui refuse réellement un signer/writable manquant.
• Rejouer les signatures échouées avec forceReplay=true.
• Obtenir failed=0 pour les cas désormais supportés.
• Classer en Unsupported plutôt qu’en Failed toute variante volontairement hors périmètre mais valide sur chaîne.
• Vérifier la matérialisation après correction du décodage.

6.4 Observabilité du décodeur

• Enrichir le diagnostic avec :
  • nom du rôle attendu ;
  • index du compte ;
  • pubkey ;
  • flags attendus ;
  • flags observés ;
  • contexte outer/inner.
• Afficher ces diagnostics dans la fenêtre Decode replay.
• Ajouter un bouton Copier pour les diagnostics détaillés.
• Ne pas exposer de données sensibles dans les logs.

---

7. IDL Metaplex Token Metadata

• Placer le snapshot officiel dans le workspace :

idls/metaplex_token_metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.json

• Conserver le fichier source/provenance associé.
• Documenter :
  • URL officielle ;
  • commit ou SHA du blob ;
  • version IDL 1.14.0 ;
  • program ID canonique.
• Ajouter un script de rafraîchissement déterministe.
• Ajouter un test vérifiant que l’IDL est du JSON valide.
• Ajouter un test comparant les discriminants couverts par le décodeur avec l’IDL.
• Ne pas utiliser l’IDL comme seule source normative lorsque le programme ou les generated builders divergent.

---

8. Configuration .env et ordre de résolution

8.1 kb-config

• dotenvy appartient à kb-config, pas au desktop.
• Vérifier l’API publique finale et ses noms.
• Appliquer et tester l’ordre :
  1. environnement déjà présent dans le processus ;
  2. fichier explicitement indiqué par KB_ENV_FILE ;
  3. .env à la racine du workspace ;
  4. fallback ${VAR:-fallback} ;
  5. variable non résolue conservée ou erreur selon le contrat du champ.
• Garantir qu’un .env ne remplace jamais une variable déjà injectée par le shell, systemd, Docker, CI ou IDE.
• Définir le comportement si KB_ENV_FILE pointe vers un fichier absent.
• Définir le comportement si .env est absent.
• Définir le comportement des lignes invalides.
• Interdire l’impression de valeurs secrètes dans les diagnostics.
• Ajouter des tests isolés et sérialisés pour éviter les collisions d’environnement global entre tests.

8.2 kb-app-demo-desktop

• Retirer toute lecture ou tout chargement .env résiduel du desktop.
• Ne conserver que l’appel à l’API de chargement de kb-config.
• Afficher dans la fenêtre Configuration la provenance des sources sans afficher les secrets :
  • environnement processus ;
  • fichier .env chargé ;
  • fallback ;
  • non résolu.
• Vérifier que l’application démarre sans clé Helius.
• Vérifier que l’utilisation d’un endpoint Helius sans clé produit une erreur ciblée.
• Vérifier qu’une clé valide dans .env permet HTTP et WebSocket Helius.

8.3 kb-pipeline-demo-scenarios

• Ne pas dépendre directement de dotenvy.
• Centraliser l’initialisation par kb-config lorsque les scénarios sont lancés directement.
• Réduire progressivement les appels directs std::env::var.
• Introduire des structures typées pour :
  • SPL Token classique ;
  • ATA ;
  • Token-2022 ;
  • ElGamal Registry ;
  • scénarios Solana Core.
• Permettre l’injection des valeurs dans les tests sans modifier l’environnement global.
• Vérifier que les variables externes historiques TOKEN_2022_* peuvent rester nommées ainsi, tout en utilisant token2022 dans les modules Rust internes.

8.4 Tâche ultérieure kb-store

• À reporter : décider si les chemins/URLs de base sont entièrement résolus par kb-config avant construction de kb-store.
• Ne pas faire charger .env directement par kb-store.
• Prévoir une configuration typée déjà résolue pour PostgreSQL et les futures bases.
• Étudier la séparation future des targets de logs kb-store.core et kb-store.postgres.

---

9. Cycle de vie WebSocket

• Aucun pool WebSocket au démarrage général.
• Création paresseuse lors du premier accès.
• Pool conservé dans AppState.
• Fermeture de demo_ws sans fermeture de la session.
• Récupération du statut à la réouverture.
• Utiliser disconnect_demo_ws_app_state lors de la fermeture globale de l’application.
• Ne pas l’appeler lors de la simple destruction de demo_ws.
• Tester la fermeture explicite depuis la fenêtre.
• Tester le timeout de session.
• Tester la fermeture de l’application avec session et abonnements actifs.
• Vérifier qu’aucune tâche Tokio ni relay ne reste suspendu après arrêt.
• Éliminer le warning dead_code de façon fonctionnelle, sans supprimer le hook requis.

---

10. Menu principal et cohérence visuelle

• Réordonner définitivement le dropdown des fenêtres selon les groupes suivants :
  1. Configuration ;
  2. Transport : HTTP, WebSocket, Backfill ;
  3. Pipeline : Extraction core, Decode replay ;
  4. SQL : diagnostics, raw, core, replay ;
  5. Exécution : Solana Core, SPL.
• Ajouter des séparateurs ou titres de groupes non cliquables.
• Vérifier que chaque fenêtre possède le logo non cliquable.
• Vérifier particulièrement demo_execution_solana_core.
• Garder les descriptions longues dans le contenu principal et non dans la navbar.
• Vérifier les deux textes :
  • « System Program uniquement — simulation-first et replay post-exécution » ;
  • « Memo, SPL Token classique, Token-2022 et ATA — simulation-first et replay post-exécution ».
• Uniformiser titres, sous-titres, marges et hauteurs de navbar.

---

11. Vérifier les options de la fenêtre Exécution SPL

• Auditer toutes les valeurs de demo_execution_spl.html.
• Vérifier leur correspondance exacte avec les parsers et enums Rust.
• Remplacer les valeurs internes historiques token_2022 par token2022 lorsqu’elles ne constituent pas un contrat externe.
• Conserver uniquement les variables d’environnement externes TOKEN_2022_* si elles sont déjà documentées et utilisées.
• Vérifier chaque scénario :
  • Memo v4 ;
  • SPL Token classique ;
  • Token-2022 ;
  • ATA.
• Vérifier que Memo v1 et v3 restent non exécutables.
• Vérifier les scénarios publics Token-2022 réellement supportés par l’exécuteur.
• Retirer ou désactiver toute option UI sans implémentation réelle.
• Ajouter un test qui compare la liste HTML/TypeScript avec l’inventaire Rust exposé.

---

12. Façades consolidées et nomenclature

• Exécuter une recherche uniquement sur les fichiers Rust :

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|_2022'

• Aucun ancien crate Bot2 ne doit subsister.
• Tous les modèles, décodeurs, matérialiseurs et exécuteurs doivent passer par kb-lib.
• Tout le stockage doit passer par kb-store.
• Les modules Rust internes utilisent token2022, jamais token_2022.
• Les constantes utilisent SPL_TOKEN2022_* selon la nomenclature de kb-program-ids.
• Les variables d’environnement externes TOKEN_2022_* peuvent rester.
• Vérifier tous les export_to uniquement dans les .rs :

find kb-config kb-lib kb-app-demo-desktop \
  -type f -name '*.rs' -print0 |
xargs -0 grep -n 'export_to'

• Corriger les chemins TS-RS résiduels qui imitent des anciens noms de crates.
• Supprimer les fichiers de bindings orphelins générés par les anciens chemins.

---

13. Logging

• La sortie console compacte est de nouveau active.
• Les routes consolidées produisent une arborescence cohérente.
• Vérifier la console pour chaque profil configuré.
• Vérifier qu’aucune route n’utilise un ancien target Bot2.
• Vérifier l’absence de dossiers vides créés pour des targets inexistants.
• Ajouter un test de complétude des routes par rapport aux targets publics actuels.
• Vérifier la cohérence tiret/underscore entre target et répertoire.
• Décider ultérieurement si kb-store doit produire :
  • kb-store/core ;
  • kb-store/postgres.
• Ne pas traiter cette séparation comme bloquante pour la clôture de la migration.

---

14. Nettoyage des warnings Rust

• Résoudre le warning DemoDecodeReplayProgressPayload inutilisé par un usage réel ou un ajustement de visibilité justifié.
• Résoudre le warning initialize_postgres_schema_for_startup inutilisé après décision sur l’initialisation SQL.
• Résoudre le warning disconnect_demo_ws_app_state inutilisé en le branchant sur l’arrêt global.
• Résoudre les helpers SQL privés inutilisés en les utilisant ou en les supprimant si le flux est abandonné.
• Ne pas supprimer une fonction prévue uniquement pour faire taire un warning sans décision architecturale.
• Obtenir cargo test -p kb-app-demo-desktop sans warning propre au code applicatif.

---

15. Clippy et macros Tauri

• Traiter en dernier les erreurs clippy::question_mark_used provenant des expansions #[tauri::command] async.
• Confirmer qu’aucun ? interdit n’existe dans le code source métier.
• Choisir une solution localisée et documentée :
  • allowance au niveau du module adaptateur Tauri ; ou
  • configuration ciblée pour le code généré ; ou
  • exception d’audit explicite pour les macros externes.
• Ne pas rendre les commandes synchrones uniquement pour satisfaire Clippy.
• Ne pas désactiver le lint à l’échelle du workspace.
• Ajouter une note dans RUST_RULES.md expliquant l’exception du code généré Tauri.
• Obtenir finalement :

cargo clippy --all-targets

sans erreur.

---

16. Validation fonctionnelle de chaque fenêtre

• Splash : affiche uniquement les composants réellement initialisés au démarrage, puis est détruit.
• Main : menu ordonné, tous les liens fonctionnels.
• Configuration : viewers JSON bornés, provenance de configuration lisible, secrets masqués.
• HTTP : méthodes, paramètres, résultat texte, Copier/Effacer.
• WebSocket : connexion, abonnements multiples, restauration, messages texte, déconnexion.
• Backfill : anciens/nouveaux historiques, annulation, journal permanent, résultat.
• SQL diagnostics : pleine largeur, refresh, erreurs.
• SQL raw : pleine largeur, tables et compteurs.
• SQL core : pleine largeur, tables et compteurs.
• SQL replay : filtres, DataTables, CSV, onglets.
• Extraction core : campagne, annulation, journal permanent.
• Decode replay : 7 décodeurs, matérialiseurs, diagnostics, annotations.
• Exécution Solana Core : simulation, envoi contrôlé, replay post-exécution.
• Exécution SPL : Memo v4, Token, Token-2022, ATA.
• Fermeture et réouverture répétées de toutes les fenêtres dynamiques.
• Vérification qu’aucune fenêtre dynamique ne démarre automatiquement.

---

17. Tests de scénarios hors Tauri

• Déplacer ou dupliquer les scénarios métier importants dans kb-pipeline-demo-scenarios.
• Couvrir Solana Core.
• Couvrir Memo v4.
• Couvrir SPL Token classique.
• Couvrir ATA.
• Couvrir Token-2022.
• Couvrir ElGamal Registry lorsque validable.
• Couvrir Metaplex Token Metadata.
• Tester sans démarrer Tauri.
• Tester avec configurations injectées plutôt qu’avec environnement global lorsque possible.

---

18. Sécurité des secrets et fichiers locaux

• Vérifier que .env est ignoré par Git.
• Conserver .env.example versionné sans secret.
• Vérifier l’historique Git pour s’assurer qu’aucune clé Helius réelle n’a été ajoutée.
• Masquer les valeurs sensibles dans les logs et dans la fenêtre Configuration.
• Ne jamais inclure .env dans les archives delta.
• Ajouter une validation de démarrage qui signale la présence/absence d’une clé sans l’afficher.

---

19. Validation technique finale

• 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-app-demo-desktop
• cargo test -p kb-app-demo-desktop
• cargo check --workspace
• cargo test --workspace
• python3 scripts/audit_rust_workspace_rules.py
• cargo clippy --all-targets après traitement de l’exception Tauri.
• cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
• Vérification manuelle de toutes les fenêtres.
• Vérification réelle HTTP Helius.
• Vérification réelle WebSocket Helius.
• Rejeu Metaplex avec failed=0 sur les cas corrigés.

---

20. Documentation et clôture

• Mettre à jour README.md avec l’architecture Bot3 finale.
• Mettre à jour ROADMAP.md avec les points réellement clôturés et les reports.
• Mettre à jour CHANGELOG.md avec toutes les prereleases et fixes.
• Documenter la politique .env et l’ordre de résolution.
• Documenter le cycle de vie HTTP/WebSocket.
• Documenter les fenêtres dynamiques, Vite et capabilities.
• Documenter les conventions de viewers JSON et de journaux texte.
• Documenter l’IDL Metaplex et sa provenance.
• Documenter les tâches reportées :
  • résolution de configuration de base dans kb-store ;
  • séparation des logs kb-store.core / kb-store.postgres ;
  • améliorations non bloquantes.
• Préparer le prompt complet de la session suivante.
• Livrer le dernier delta de migration.
• Effectuer le commit Git de clôture.
• Taguer la prerelease ou version de clôture selon la convention retenue.

---

21. Critères de clôture obligatoires

La migration ne peut être déclarée terminée que lorsque toutes les conditions suivantes sont satisfaites :

• Toutes les fenêtres historiques requises sont présentes et fonctionnelles.
• Aucun ancien crate Bot2 n’est référencé.
• Aucune erreur de compilation ou de test.
• Audits Rust et workspace propres.
• Aucun warning applicatif non justifié.
• .env est centralisé dans kb-config et sa priorité est testée.
• HTTP et WebSocket Helius fonctionnent avec une clé locale non versionnée.
• Les erreurs Metaplex observées sont corrigées ou classées explicitement et correctement.
• Les fenêtres SQL n’ont ni navigation involontaire ni layout régressif.
• Chaque journal/résultat texte possède une seule paire Copier/Effacer.
• Les viewers JSON sont bornés en hauteur et réservés au JSON réel.
• Le cycle de vie WebSocket est validé jusqu’à l’arrêt global.
• La documentation de clôture et le prompt suivant sont livrés.