khadhroony-bot3/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md

Checklist détaillée de clôture de la migration khadhroony-bot3

Base et principe de validation

• Base de travail : khadhroony-bot3_v0.1.0-pre.055-full.zip.
• Références fonctionnelles : Bot2 v0.4.6 puis Bot2 v0.4.7-pre.035-tofix07.
• Prompt actif : prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md.
• Une case n’est cochée qu’après preuve explicite : audit, compilation, test, requête SQL, contrôle runtime ou comparaison documentée.
• L’ordre est obligatoire : règles, contrôles rapides, retour au niveau 0.4.6, Metaplex 0.4.7, Clippy/Tauri, documentation, versionnement.

0. Revalidation des règles et des archives

• Inventorier l’archive Bot3 pre.055.
• Inventorier l’archive Bot2 0.4.6 issue de Git.
• Inventorier l’archive Bot2 0.4.7-pre.035-tofix07.
• Vérifier la présence de l’IDL Metaplex local dans Bot3.
• Constater que Bot3 utilisait encore RULES.md et RUST_RULES.md.
• Créer RULES_GENERAL.md.
• Créer RULES_RUST.md.
• Créer RULES_SPECIFIC_KHADHROONY.md.
• Transformer RULES.md en index normatif.
• Corriger docs/DELTA_WORKFLOW.md pour Bot3, -delta, delta-fix-XXX, exclusion de Cargo.lock et absence de SHA256.
• Adapter le script d’audit aux nouveaux fichiers de règles.
• Relire intégralement les quatre fichiers de règles après application du delta.
• Comparer ligne par ligne les règles Bot2 encore applicables avec les règles Bot3.
• Documenter chaque règle Bot2 écartée et sa justification.
• Vérifier l’absence de contradiction sur les imports, réexports, façades, Tauri, TS-RS, logging, versionnement et archives.
• Exécuter cargo fmt --all.
• Exécuter python3 scripts/audit_rust_workspace_rules.py.

0.1 Classification des matrices de contrat

• Inventorier les fichiers JSON machine auparavant placés sous docs/.
• Créer test-fixtures/contract-matrices/ pour les matrices de contrat partagées.
• Déplacer les dix matrices JSON hors de docs/.
• Mettre à jour les dix-sept fichiers Rust contenant les include_str! concernés.
• Conserver le déplacement et les mises à jour de chemins dans une même livraison atomique.
• Lister chaque ancien fichier avec une commande rm -- dans delta.md.
• Exécuter les tests des crates consommatrices dans le workspace réel (kb-lib, kb-onchain-transport, kb-pipeline-demo-scenarios).
• Vérifier qu’aucune référence résiduelle ne pointe vers les anciens chemins docs/*.json.

1. Contrôles rapides avant code fonctionnel

1.1 TS-RS

• Rechercher export_to uniquement dans les fichiers .rs de kb-config, kb-lib et kb-app-demo-desktop.
• Vérifier les sorties kb_config.
• Vérifier les sorties kb_lib dans kb-lib/frontend/ts/bindings/kb_lib.
• Vérifier les sorties kb_app_demo_desktop.
• Supprimer les chemins historiques kb_executor_*.
• Supprimer les chemins historiques kb_decoder_*.
• Supprimer les chemins historiques kb_materializer_*.
• Supprimer les chemins historiques kb_model.
• Supprimer les chemins historiques kb_store_pg et kb_store_core.
• Régénérer les bindings via les tests TS-RS exécutés pendant les tests complets des crates.
• Vérifier que les fichiers générés correspondent aux chemins déclarés pour kb_config, kb_lib et kb_app_demo_desktop.

1.2 Anciens chemins et nomenclature

• Auditer kb-app-demo-desktop/**/*.rs pour les anciens noms Bot2.
• Auditer tout le workspace pour token_2022 interne.
• Justifier séparément chaque contrat externe TOKEN_2022_* conservé.
• Vérifier que kb-lib et kb-store sont les seules façades consolidées concernées.
• Vérifier qu’aucune ancienne crate n’a été recréée.

1.3 Frontend et menu

• Auditer les occurrences Copier et Effacer dans tous les HTML et TypeScript.
• Garantir une seule paire de contrôles par sortie.
• Vérifier et corriger l’ordre du menu : Configuration, Transport et collecte, Pipeline, SQL, Exécution.
• Vérifier les séparateurs.
• Supprimer les entrées mortes.
• Identifier les modules SPL backend comme composants de la fenêtre consolidée demo_execution_spl, et non comme fenêtres autonomes oubliées.

2. Corrections UI rapides

2.1 HTTP JSON-RPC

• Remplacer le viewer JSON du résultat par un textarea readonly.
• Fixer la hauteur.
• Activer le scroll interne.
• Garantir exactement un bouton Copier pour la sortie principale.
• Garantir exactement un bouton Effacer pour la sortie principale.
• Vider le buffer TypeScript lors de l’effacement.
• Tester JSON, scalaire, texte, erreur et résultat vide.
• Restaurer le gabarit desktop à deux colonnes : requête à gauche, endpoints et résultat à droite.

2.2 WebSocket

• Afficher les messages dans un composant texte/log.
• Fixer la hauteur et le scroll interne.
• Garantir une seule paire Copier/Effacer pour la sortie Messages.
• Borner le débit et la taille des notifications envoyées à l’UI pour éviter les freezes.
• Conserver le payload complet sous forme JSON compacte dans les logs de debug avant formatage et troncage UI.
• Conserver les messages pendant la session active.
• Restaurer l’affichage après fermeture/réouverture de la fenêtre.
• Restaurer le gabarit desktop à deux colonnes : souscription à gauche, statut/endpoints/messages à droite.
• Appliquer base64 par défaut aux souscriptions accountSubscribe et programSubscribe lorsque l’encodage est absent, sans écraser un encodage explicite.
• Décider après test runtime si Statut et Endpoints WebSocket restent textuels ou deviennent des viewers JSON structurés ; supprimer alors tout bouton Copier redondant fourni par le viewer.

2.3 Backfill et autocomplétion

• Garder Program ID librement éditable.
• Ajouter un autocomplétion non bloquant depuis le registre public kb-program-ids.
• Ajouter ultérieurement les autocomplétions Token et Pool lorsque leurs tables de référence existeront.

2.4 Journaux généraux et viewers

• Vérifier Backfill HTTP.
• Vérifier Extraction core.
• Vérifier Exécution Solana Core.
• Vérifier Exécution SPL.
• Vérifier Decode replay.
• Vérifier HTTP.
• Vérifier WebSocket.
• Placer les paramètres dans les accordéons.
• Placer les journaux et résultats globaux sous les accordéons.
• Réserver le viewer JSON au JSON structuré.
• Utiliser des textareas pour texte brut, logs et diagnostics concaténés.
• Fixer la hauteur de tous les viewers JSON.

2.5 Fenêtres SQL

• Mettre toutes les fenêtres SQL, sauf Replay Candidates, sur une seule colonne pleine largeur.
• Mettre les tables sur toute la largeur.
• Limiter le scroll horizontal au wrapper de table.
• Vérifier toutes les balises HTML.
• Vérifier boutons, onglets et liens.

3. Configuration et environnement

• Confirmer que seul kb-config charge .env.
• Confirmer la priorité environnement du processus.
• Confirmer KB_ENV_FILE.
• Confirmer le .env racine par défaut.
• Confirmer ${VAR}.
• Confirmer ${VAR:-fallback}.
• Confirmer l’absence non fatale pour les services optionnels.
• Vérifier que les diagnostics ne révèlent aucun secret.
• Vérifier que kb-pipeline-demo-scenarios ne dépend pas directement de dotenvy.
• Valider réellement HELIUS_API_KEY depuis .env.
• Garder la résolution de chemin de base kb-store dans le backlog documenté.

4. Logging

• Maintenir la console active pour local_devnet.
• Maintenir la console active pour mainnet_research.
• Maintenir la console active pour mainnet.
• Supprimer les routes Bot2 obsolètes.
• Vérifier les cibles kb-lib.decoder.*.
• Vérifier les cibles kb-lib.executor.*.
• Vérifier les cibles kb-lib.materializer.*.
• Vérifier kb-store, kb-config, kb-logging, kb-onchain-transport, kb-pipeline, kb-wallet et kb-app-demo-desktop.
• Vérifier qu’aucun ancien répertoire de logs de crate supprimée n’est recréé.

5. Options SPL et Token-2022

• Comparer chaque option de demo_execution_spl.html aux scénarios réellement supportés.
• Comparer les options aux branches de tauri.rs.
• Supprimer les options mortes.
• Remplacer les valeurs internes token_2022 par token2022.
• Inventorier chaque variable TOKEN_2022_*.
• Marquer les variables conservées pour compatibilité externe.
• Marquer les variables limitées aux scénarios de démonstration.
• Documenter les futurs remplacements par configuration ou structure typée.

5.1 Wrappers Tauri

• Déplacer la logique complète de splash_frontend_ready dans splash.rs et conserver un wrapper privé mince dans tauri.rs.
• Inventorier toutes les fonctions #[tauri::command] de tauri.rs.
• Déplacer progressivement toute logique métier restante dans son module fonctionnel pub(crate).
• Vérifier que chaque wrapper Tauri ne fait que l’adaptation des arguments et la délégation.
• Ajouter ou conserver les tests unitaires dans les modules fonctionnels, pas dans les wrappers.

6. Cycle de vie WebSocket

• Vérifier qu’aucun pool WebSocket n’est créé au démarrage.
• Vérifier la création paresseuse au premier accès.
• Vérifier le stockage du pool dans AppState.
• Vérifier la survie de la session après fermeture de demo_ws.
• Vérifier la récupération de l’état à la réouverture.
• Vérifier la fermeture explicite.
• Vérifier le timeout.
• Vérifier l’arrêt global de l’application.
• Vérifier que la fermeture de la fenêtre n’appelle jamais la déconnexion globale.

7. Initialisation PostgreSQL et splash

• Charger l’environnement.
• Charger et valider la configuration.
• Initialiser le logging.
• Initialiser le pool HTTP.
• Se connecter à PostgreSQL.
• Appeler initialize_postgres_schema_for_startup après disponibilité du frontend splash.
• Appeler emit_sql_startup_table_report.
• Relier emit_sql_startup_error.
• Relier emit_sql_startup_splash.
• Ouvrir main seulement après le rapport PostgreSQL et le fade-out.
• Fermer le splash après le statut final.
• Ne pas initialiser WebSocket dans cette séquence.
• Rendre les zones du splash scrollables sans afficher leurs barres de défilement.
• Garder automatiquement le dernier log et le dernier message visibles.
• Afficher connexion, schéma, nombre de tables, tables manquantes et statut final.
• Valider visuellement le fade-in, les messages intermédiaires, le fade-out et l’ouverture de main sur le workspace réel.

8. Purge contrôlée des données dérivées

• Inventorier les tables via kb-store.
• Classer chaque table en raw, nécessaire au replay, dérivée ou ambiguë.
• Bloquer la purge tant qu’une table reste ambiguë.
• Créer un script SQL versionné et idempotent.
• Conserver transactions, signatures et payloads RPC raw.
• Conserver toutes les données nécessaires à l’extraction et au replay.
• Purger core dérivé, décodage, observations, coverage, diagnostics et états de replay dérivés.
• Purger annotations, événements matérialisés, token accounts, lifecycle, admin, fees, risk, compliance et staking dérivés.
• Exécuter la purge dans une transaction.
• Ajouter des vérifications avant/après.
• Documenter précisément les tables conservées.
• Relancer l’extraction core.
• Relancer tous les décodeurs.
• Relancer la matérialisation.
• Valider les compteurs et erreurs.
• Contrôler la reconstruction de chaque projection attendue.

9. Jalon fonctionnel Bot2 0.4.6

• Solana Core équivalent et validé.
• SPL Memo équivalent et validé.
• SPL Token classique équivalent et validé.
• SPL ATA équivalent et validé.
• SPL Token-2022 équivalent et validé.
• ElGamal Registry équivalent et validé.
• Backfill équivalent et validé.
• Extraction core équivalente et validée.
• Replay équivalent et validé.
• Matérialisation équivalente et validée.
• Exécution supportée équivalente et validée.
• Scénarios devnet historiques validés.
• HTTP et WebSocket validés.
• PostgreSQL validé.
• Logging validé.
• Configuration validée.
• Produire un rapport explicite de parité 0.4.6 avant toute clôture Metaplex.

10. Inventaire IDL

• Créer docs/IDL_SOURCES.md.
• Inventorier chaque IDL local.
• Indiquer protocole et program ID.
• Indiquer source officielle.
• Indiquer version ou commit lorsqu’ils sont connus.
• Indiquer chemin local, statut et usage.
• Documenter les notes de compatibilité.
• Ne pas inventer d’IDL absent.
• Référencer l’IDL Metaplex existant sans le retélécharger.

11. Metaplex Token Metadata — décodeur

• Extraire toutes les erreurs Metaplex réelles.
• Regrouper par instruction et type d’échec.
• Isoler create_metadata_account_v3.
• Isoler transfer.
• Comparer runtime, IDL local, builders et interface officielle.
• Corriger signer et writable flags.
• Gérer comptes optionnels et variantes legacy.
• Distinguer transactions échouées, payloads tronqués et variantes inconnues.
• Ajouter des fixtures issues de transactions réelles.
• Relancer le replay complet Metaplex.
• Obtenir zéro faux échec de metas.

12. Metaplex Token Metadata — exécuteur et devnet

• Compléter les intents typés.
• Compléter les builders.
• Valider l’ordre des comptes.
• Valider signers et writable flags.
• Borner explicitement les variantes supportées.
• Ajouter les politiques de sécurité.
• Imposer simulation-first.
• Ajouter l’estimation des coûts.
• Ajouter la validation post-exécution.
• Ajouter les tests unitaires.
• Comparer aux builders officiels.
• Compléter la matrice de couverture.
• Ajouter des scénarios devnet explicites.
• Interdire l’exécution par défaut sur mainnet.
• Afficher plan, signers, simulation et résultat.
• Effectuer un replay post-exécution.
• Vérifier décodage et matérialisation.
• Afficher les diagnostics.

13. Clippy et Tauri

• Traiter Clippy seulement après le fonctionnel Metaplex.
• Identifier précisément les expansions de macros Tauri concernées par question_mark_used.
• Éviter un allow global.
• Documenter toute exception locale et sa portée.
• Obtenir un Clippy propre ou un écart borné et reproductible.

14. Documentation finale et versionnement

• Rendre les README génériques et indépendants de la migration.
• Retirer les numéros de version des README.
• Retirer le récit Bot2 vers Bot3 des README actifs.
• Créer USAGES.md pour chaque crate publique.
• Documenter API, types, traits, fonctions, builders, exemples, invariants, erreurs, limites et intégrations.
• Ajouter des roadmaps par crate uniquement lorsqu’elles apportent une valeur réelle.
• Conserver au plus une courte note historique.
• Ne passer à 0.4.7 qu’après parité 0.4.6, Metaplex complet, replay validé et documentation terminée.
• Mettre à jour CHANGELOG.md uniquement lors de cette validation explicite.

15. Validation finale

• cargo fmt --all.
• cargo check -p kb-config.
• cargo test -p kb-config (44/45 passaient ; contrat de route groupée kb-pipeline corrigé dans la prochaine prerelease).
• 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 (112/113 passaient ; contrat d’ordre de décodeurs corrigé, relance requise).
• cargo check --workspace.
• cargo test --workspace.
• python3 scripts/audit_rust_workspace_rules.py.
• cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json.
• cargo clippy --all-targets en dernier.

16. Critères de clôture

• Toutes les crates compilent.
• Tous les tests workspace passent.
• Audit Rust propre.
• Audit TS-RS propre.
• Aucun chemin Bot2 supprimé encore actif.
• Toutes les fenêtres fonctionnent.
• WebSocket persistant validé.
• .env et Helius validés.
• PostgreSQL et splash validés.
• Données dérivées purgées et reconstruites.
• Niveau 0.4.6 restauré.
• UI JSON/texte cohérente.
• Aucun contrôle Copier/Effacer dupliqué.
• Journaux hors accordéon.
• Fenêtres SQL dimensionnées.
• Routes de logs obsolètes supprimées.
• Console active.
• Inventaire IDL terminé.
• Zéro faux échec Metaplex de metas.
• Exécuteur et démos Metaplex validés.
• Clippy/Tauri finalisés.
• Documentation et USAGES.md terminés.
• Passage à 0.4.7 justifié.