khadhroony-bot3/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md

<!-- file: KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md -->
<!-- version: 9 -->

# 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

- [x] Inventorier l’archive Bot3 `pre.055`.
- [x] Inventorier l’archive Bot2 `0.4.6` issue de Git.
- [x] Inventorier l’archive Bot2 `0.4.7-pre.035-tofix07`.
- [x] Vérifier la présence de l’IDL Metaplex local dans Bot3.
- [x] Constater que Bot3 utilisait encore `RULES.md` et `RUST_RULES.md`.
- [x] Créer `RULES_GENERAL.md`.
- [x] Créer `RULES_RUST.md`.
- [x] Créer `RULES_SPECIFIC_KHADHROONY.md`.
- [x] Transformer `RULES.md` en index normatif.
- [x] Corriger `docs/DELTA_WORKFLOW.md` pour Bot3, `-delta`, `delta-fix-XXX`, exclusion de `Cargo.lock` et absence de SHA256.
- [x] Adapter le script d’audit aux nouveaux fichiers de règles.
- [x] 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.
- [x] Exécuter `cargo fmt --all`.
- [x] Exécuter `python3 scripts/audit_rust_workspace_rules.py`.

## 0.1 Classification des matrices de contrat

- [x] Inventorier les fichiers JSON machine auparavant placés sous `docs/`.
- [x] Créer `test-fixtures/contract-matrices/` pour les matrices de contrat partagées.
- [x] Déplacer les dix matrices JSON hors de `docs/`.
- [x] Mettre à jour les dix-sept fichiers Rust contenant les `include_str!` concernés.
- [x] Conserver le déplacement et les mises à jour de chemins dans une même livraison atomique.
- [x] Lister chaque ancien fichier avec une commande `rm --` dans `delta.md`.
- [x] Exécuter les tests des crates consommatrices dans le workspace réel (`kb-lib`, `kb-onchain-transport`, `kb-pipeline-demo-scenarios`).
- [x] 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

- [x] Rechercher `export_to` uniquement dans les fichiers `.rs` de `kb-config`, `kb-lib` et `kb-app-demo-desktop`.
- [x] Vérifier les sorties `kb_config`.
- [x] Vérifier les sorties `kb_lib` dans `kb-lib/frontend/ts/bindings/kb_lib`.
- [x] 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`.
- [x] Régénérer les bindings via les tests TS-RS exécutés pendant les tests complets des crates.
- [x] 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

- [x] Auditer les occurrences `Copier` et `Effacer` dans tous les HTML et TypeScript.
- [ ] Garantir une seule paire de contrôles par sortie.
- [x] 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.
- [x] 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

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

### 2.2 WebSocket

- [x] Afficher les messages dans un composant texte/log.
- [x] Fixer la hauteur et le scroll interne.
- [x] Garantir une seule paire Copier/Effacer pour la sortie Messages.
- [x] Borner le débit et la taille des notifications envoyées à l’UI pour éviter les freezes.
- [x] Conserver le payload complet sous forme JSON compacte dans les logs de debug avant formatage et troncage UI.
- [x] Conserver les messages pendant la session active.
- [x] Restaurer l’affichage après fermeture/réouverture de la fenêtre.
- [x] Restaurer le gabarit desktop à deux colonnes : souscription à gauche, statut/endpoints/messages à droite.
- [x] 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

- [x] Garder Program ID librement éditable.
- [x] Ajouter un autocomplétion non bloquant depuis le registre public `kb-program-ids`.
- [ ] Ajouter le même autocomplétion Program ID au filtre « programme déjà indexé » d’Extraction core.
- [ ] 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

- [x] Vérifier Backfill HTTP en runtime.
- [x] Vérifier Extraction core en runtime après correction du gabarit pleine largeur.
- [ ] Vérifier Exécution Solana Core.
- [ ] Vérifier Exécution SPL.
- [x] Vérifier Decode replay en runtime et conserver les échecs Loader/Metaplex comme anomalies fonctionnelles à corriger.
- [x] Vérifier HTTP en runtime.
- [x] Vérifier WebSocket en runtime.
- [x] Placer les paramètres d’Extraction core dans les accordéons.
- [x] Placer les journaux et résultats globaux d’Extraction core sous les accordéons.
- [ ] Réserver le viewer JSON au JSON structuré.
- [ ] Utiliser des textareas pour texte brut, logs et diagnostics concaténés.
- [x] Fixer la hauteur du viewer JSON d’Extraction core.
- [ ] Étendre la vérification des journaux/viewers aux fenêtres Exécution Solana Core, Exécution SPL et Decode replay.

### 2.5 Fenêtres SQL

- [x] Relever temporairement le plafond de résultats de 5 000 à 100 000 pour les campagnes de migration.
- [ ] Ajouter ultérieurement une pagination SQL/IPC serveur avant les volumes massifs.
- [x] Écrire les CSV dans `<workspace>/data/exports_csv`, indépendamment du répertoire courant Tauri.
- [ ] Corriger la valeur de repli TypeScript `maximumReplayCandidateLimit = 5_000` vers `100_000`.
- [x] Valider qu’un export produit `data/exports_csv/replay_transactions.csv`.

- [ ] 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

- [x] Déplacer la logique complète de `splash_frontend_ready` dans `splash.rs` et conserver un wrapper privé mince dans `tauri.rs`.
- [x] Inventorier toutes les fonctions `#[tauri::command]` de `tauri.rs` et mesurer les blocs de 20 lignes ou plus.
- [x] Déplacer options, exécution et annulation d’Extraction core dans `demo_core_extraction.rs`.
- [x] Mutualiser les ouvertures de fenêtres via un helper privé strictement Tauri dans `tauri.rs`.
- [ ] Déplacer progressivement la logique Decode replay, Backfill, SQL replay et Exécution hors de `tauri.rs`.
- [x] Vérifier les wrappers Extraction core et Splash.
- [ ] Vérifier les autres wrappers Tauri après leur migration progressive.
- [ ] Ajouter ou conserver les tests unitaires dans les modules fonctionnels, pas dans les wrappers.

## 5.2 Câblage des scénarios Devnet

- [x] Confirmer que `kb-app-demo-desktop` appelle `kb-pipeline-demo-scenarios` pour System transfer.
- [x] Confirmer le câblage Memo.
- [x] Confirmer le câblage SPL Token classique.
- [x] Confirmer le câblage SPL ATA.
- [x] Confirmer le câblage SPL Token-2022.
- [x] Confirmer que ces workflows ne sont pas dupliqués dans `kb-pipeline`.
- [ ] Vérifier que chaque option HTML correspond à un scénario backend accessible.
- [ ] Vérifier simulation, envoi, progression, résumé et diagnostics en runtime Devnet.
- [ ] Vérifier le replay post-exécution et la matérialisation pour chaque famille.
- [ ] Raccorder ou documenter le workflow `execute_devnet_spl_token_lifecycle`, présent dans la crate mais non exposé par l’application desktop.

## 6. Cycle de vie WebSocket

- [x] Vérifier qu’aucun pool WebSocket n’est créé au démarrage.
- [x] Vérifier la création paresseuse au premier accès.
- [x] Vérifier le stockage du pool dans `AppState`.
- [x] Vérifier la survie de la session après fermeture de `demo_ws`.
- [x] 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.
- [x] Vérifier que la fermeture de la fenêtre n’appelle jamais la déconnexion globale.

## 7. Initialisation PostgreSQL et splash

- [x] Charger l’environnement.
- [x] Charger et valider la configuration.
- [x] Initialiser le logging.
- [x] Initialiser le pool HTTP.
- [x] Se connecter à PostgreSQL et confirmer la disponibilité du profil `mainnet_research`.
- [x] Appeler `initialize_postgres_schema_for_startup` après disponibilité du frontend splash.
- [x] Appeler `emit_sql_startup_table_report`.
- [x] Relier `emit_sql_startup_error`.
- [x] Relier `emit_sql_startup_splash`.
- [x] Ouvrir `main` seulement après le rapport PostgreSQL et le fade-out.
- [x] Fermer le splash après le statut final.
- [x] Ne pas initialiser WebSocket dans cette séquence.
- [x] Rendre les zones du splash scrollables sans afficher leurs barres de défilement.
- [x] Garder automatiquement le dernier log et le dernier message visibles.
- [x] Afficher connexion, schéma, nombre de tables, tables manquantes et statut final.
- [ ] Supprimer l’écrasement artificiel de `auto_initialize_schema` à `false` dans le chemin du splash et respecter la valeur du profil actif.
- [x] Valider visuellement les messages intermédiaires, l’ouverture de `main`, l’absence de scrollbar visible et l’auto-scroll ; conserver le fade CSS Tauri/Linux comme limitation visuelle non bloquante.

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

- [x] Inventorier les tables via les migrations `kb-store` 0001 à 0004.
- [x] Classer `kb_sol_raw_transactions` et `kb_sol_obs_transaction_observations` comme acquisition raw ; classer core, ledger, decode, coverage et matérialisation comme dérivés reconstructibles.
- [x] Confirmer qu’aucune table actuellement définie par `kb-store` ne reste ambiguë pour cette reconstruction.
- [x] Confirmer que le schéma courant est initialisé par les listes SQL idempotentes de `kb-store` et non par une table `_sqlx_migrations` active.
- [ ] Corriger `kb-store/maintenance/reset_derived_store_keep_raw.sql` pour conserver explicitement les deux tables d’acquisition et utiliser une stratégie `TRUNCATE ... RESTART IDENTITY` pour les tables dérivées.
- [x] Conserver `kb_sol_raw_transactions` avec 4 574 transactions et remettre tous les `processing_state` à `received`.
- [ ] Restaurer ou accepter explicitement la perte des anciennes lignes de `kb_sol_obs_transaction_observations` supprimées pendant la reconstruction manuelle.
- [x] Recréer manuellement toutes les tables manquantes depuis les scripts SQL de `kb-store`.
- [x] Vérifier avant reprise que toutes les tables Core contiennent zéro ligne.
- [x] Vérifier avant reprise que `kb_sol_ops_processing_ledger` est vide.
- [x] Vérifier avant reprise que les 4 574 raws sont sélectionnables avec l’état `received`.
- [x] Purger les tables core, ledger, decode, coverage et matérialisation dérivées.
- [x] Encadrer la reconstruction manuelle par une démarche contrôlée sans toucher aux transactions raw.
- [x] Ajouter des vérifications avant reprise : compteurs raw, Core et ledger.
- [ ] Documenter précisément les tables conservées et la politique de reconstruction dans `kb-store/maintenance/README.md`.
- [ ] Relancer l’extraction core sur les 4 574 raws.
- [ ] Relancer tous les décodeurs.
- [ ] Relancer la matérialisation.
- [ ] Valider les compteurs et erreurs.
- [ ] Contrôler la reconstruction de chaque projection attendue.

### 8.1 Anomalies observées avant reconstruction

- [ ] Auditer les instructions Loader immuables/v4 d’un octet qui échouent actuellement comme `*_tag_truncated`, notamment lorsque la transaction porte `UnsupportedProgramId`.
- [ ] Décider, signature réelle à l’appui, si ces formes doivent être `Unsupported`/`Ignored` plutôt que `Failed`.
- [ ] Auditer les flags signer/writable Metaplex réels avant d’assouplir les contrats de comptes.
- [ ] Comparer les signatures Metaplex en échec avec Bot2 `0.4.7-pre.035` et le contrat officiel.

## 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`.
- [x] `cargo check -p kb-app-demo-desktop`.
- [x] `cargo test -p kb-app-demo-desktop` : 115 tests réussis.
- [x] `cargo check --workspace`.
- [ ] `cargo test --workspace`.
- [x] `python3 scripts/audit_rust_workspace_rules.py` après `pre.058-fix-002`.
- [x] `cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json` : démarrage, splash, PostgreSQL, fenêtres et export CSV validés.
- [ ] `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é.