khadhroony-bot3/KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md

Clôture de la migration khadhroony-bot3

Ce fichier est temporaire. Il doit disparaître lorsque la migration est close, que la documentation active décrit uniquement khadhroony-bot3, et que la version du workspace est alignée sur 0.4.7.

Principes de clôture

• Une case n’est cochée qu’après preuve par recherche, compilation, test, audit, requête SQL ou validation runtime.
• Les noms, modules et documents actifs doivent décrire Bot3 comme le produit courant, sans récit permanent de migration depuis Bot2.
• Les protocoles applicatifs Pump.fun, Raydium, Meteora, Jupiter, autres AMM et launchpads restent hors périmètre tant que Solana Core, SPL, Metaplex Token Metadata et Anchor ne sont pas clôturés.
• Les rappels d’amélioration non bloquants doivent être déplacés vers docs/IDEA_REMINDERS.md, pas conservés dans cette checklist.
• La documentation finale décrit l’état courant. Elle ne doit pas accumuler un journal de changements par version dans les README.

État validé de 0.1.0-pre.061

• Suite ciblée complète : toutes les crates principales réussissent leurs tests.
• kb-app-demo-desktop : 116 tests réussis.
• kb-config : 45 tests réussis.
• kb-core : 2 tests réussis.
• kb-lib : 625 tests réussis.
• kb-onchain-transport : 113 tests réussis.
• kb-pipeline : 89 tests réussis.
• kb-pipeline-demo-scenarios : 35 tests réussis.
• kb-store : 84 tests réussis.
• cargo check --workspace réussi.
• Audit général Rust propre.
• Audit des exports Rust propre.
• Audit spécifique Khadhroony propre.
• cargo clippy --all-targets propre.
• Démarrage Tauri, splash, PostgreSQL et fenêtres principales validés.
• Extraction Core complète de 4 574 transactions raw : 4 574 extraites, 0 échec.
• Replay complet de 11 880 instructions exécuté.
• Les 6 faux échecs Metaplex ont été corrigés et rejoués avec succès.
• Les 76 tentatives Loader malformées de transactions échouées sont désormais décodées comme observations non engagées.
• Les 4 tags Loader v4 inconnus restent correctement classés Unsupported.
• Aucune erreur de matérialisation observée pendant la campagne propre.
• Les trois erreurs supplémentaires du replay ont été identifiées comme timeouts transitoires du pool PostgreSQL, distincts des échecs fonctionnels de décodage.
• Revalider les suites après les correctifs pre.061-delta-fix-004 et pre.061-delta-fix-005 : 116 tests desktop, 625 tests kb-lib, suites consolidées et replay propre.

1. Nettoyage structurel et nomenclature

1.1 Règles

• Reprendre dans les règles Bot3 toutes les règles Bot2 encore applicables.
• Remplacer les anciens fichiers de règles par RULES_GENERAL.md, RULES_RUST.md, RULES_SPECIFIC_KHADHROONY.md et un index RULES.md.
• Adapter le workflow des deltas à Bot3.
• Effectuer une dernière lecture croisée des règles portant sur imports, réexports, façades, Tauri, TS-RS, logging, versionnement et archives.
• Supprimer de cette checklist toute demande de justification historique sans valeur normative.

1.2 Anciennes crates, imports et chemins

• Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates kb_executor_*.
• Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates kb_decoder_*.
• Confirmer l’absence d’import, réexport ou dépendance active vers les anciennes crates kb_materializer_*.
• Confirmer l’absence d’import, réexport ou dépendance active vers l’ancienne crate kb_model.
• Confirmer l’absence de dépendance ou de crate kb_store_pg.
• Confirmer l’absence de dépendance ou de crate kb_store_core.
• Confirmer qu’aucune ancienne crate supprimée n’a été recréée sous un autre chemin.
• Auditer kb-app-demo-desktop/**/*.rs pour les anciens chemins structurels actifs.
• Vérifier les bindings TS-RS générés : aucun ancien chemin de crate actif n’est exporté.
• Classer les anciennes chaînes runtime et les remplacer par les identités consolidées kb-lib.decoder.*, kb-lib.executor.* et kb-lib.materializer.*.
• Réécrire lors de la refonte documentaire finale les commentaires et documents qui racontent encore la consolidation depuis les anciennes crates.

Contrôles exécutés : aucune correspondance structurelle ancienne_crate::, aucune dépendance Cargo correspondante et aucun répertoire de crate supprimée.

1.3 Convention Token-2022

Convention arrêtée :

• symboles, modules, fichiers, fonctions et variables internes : token_2022 / TOKEN_2022 ;

• types et variantes Rust en PascalCase : Token2022 ;

• valeurs JSON/TS explicitement concernées : token_2022 avec attributs Serde et TS-RS ;

• codes persistés : spl_token_2022 ;

• noms officiels externes : conserver leur orthographe publiée ;

• exceptions contractuelles Metaplex conservées : token2022EmbeddedMetadata et token2022_embedded_metadata.

• Inventorier les occurrences actives token2022, TOKEN2022, token_2022, TOKEN_2022.

• Classer les occurrences entre symboles internes, contrats externes, valeurs persistées, API, tests, IDL et documentation historique.

• Renommer les symboles et modules internes vers token_2022 / TOKEN_2022.

• Conserver Token2022 pour les types et variantes Rust.

• Aligner Serde et TS-RS sur token_2022 lorsque cette valeur appartient au contrat applicatif.

• Renommer les identités persistées et runtime vers spl_token_2022 et kb-lib.*.token_2022.

• Purger les données dérivées puis reconstruire Core, Decode et Materialize depuis les 4 574 raws.

• Valider 55 instructions Token-2022 décodées, 0 échec fonctionnel.

• Vérifier les matrices actives ; corriger la dernière commande historique dans SPL_TOKEN_2022_MATRIX.json.

• Découpler les assertions structurelles des matrices des compteurs globaux et volatils de cargo test.

• Réauditer progressivement chaque matrice active lors de la reprise de sa surface ; les preuves opérateur restent informatives et les invariants doivent être dérivés des lignes de matrice et des registres compilés.

• Refaire l’audit Python de nomenclature lors de la stabilisation finale des helpers de migration.

2. Frontend et application desktop

2.1 Menu, contrôles et HTML

• Ordre principal du menu corrigé : Configuration, Transport et collecte, Pipeline, SQL, Exécution.
• Vérifier une dernière fois les séparateurs du menu.
• Supprimer les entrées de menu, boutons, onglets et liens sans backend accessible.
• Vérifier qu’une sortie ne possède qu’une seule paire de contrôles Copier/Effacer.
• Vérifier toutes les balises HTML après les derniers remaniements ; les quatre conteneurs finaux manquants ont été refermés et le parseur HTML local ne signale plus de déséquilibre.
• Vérifier que chaque option HTML correspond à une commande Tauri et à un scénario backend réellement accessible.

2.2 Viewers et journaux

• HTTP utilise un composant texte borné pour le résultat brut.
• WebSocket utilise un composant texte/log borné et persistant pendant la session.
• Extraction Core place paramètres, journaux et résultats dans une structure cohérente.
• Réserver les viewers JSON au JSON structuré nécessitant exploration ou formatage ; HTTP endpoints/résultat et WebSocket statut/endpoints utilisent désormais @andypf/json-viewer.
• Utiliser des textareas pour texte brut, logs et diagnostics concaténés ; les messages WebSocket restent textuels avec Copier/Effacer.
• Vérifier ce contrat dans Decode replay, Exécution Solana Core et Exécution SPL.
• Convertir Statut et Endpoints WebSocket en viewers JSON structurés après contrôle runtime.

2.3 Fenêtres SQL

• Replay Candidates accepte temporairement jusqu’à 100 000 résultats.
• Les CSV sont écrits dans <workspace>/data/exports_csv.
• Export replay_transactions.csv validé.
• Mettre les autres fenêtres SQL sur une seule colonne pleine largeur lorsque ce n’est pas déjà le cas.
• Rendre le journal des annotations responsive avec DataTables, pagination, recherche et scroll horizontal borné au wrapper.
• Limiter le scroll horizontal au wrapper de table.

2.4 Rappels non bloquants

• Déplacer les autocomplétions futures, la pagination SQL/IPC et la résolution configurable du chemin kb-store vers docs/IDEA_REMINDERS.md.

3. Configuration, environnement et secrets

Préparation engagée avant la campagne Devnet 0.1.0-pre.062; la validation runtime complète reste à effectuer pendant cette campagne.

• Conserver HELIUS_API_KEY comme variable Helius canonique déjà utilisée par la configuration.

• Séparer les bases runtime avec KB_POSTGRES_MAINNET_URL et KB_POSTGRES_DEVNET_URL.

• Conserver KB_POSTGRES_TEST_URL comme contrat existant des tests d’intégration PostgreSQL.

• Faire de .env.example l’unique modèle dotenv versionné et ignorer tous les .env* réels.

• Faire pointer local_devnet vers la variable Devnet et les deux profils Mainnet vers la variable Mainnet.

• Confirmer que seul kb-config charge .env.

• Confirmer l’ordre de priorité des variables du processus, de KB_ENV_FILE, du .env racine et des valeurs de configuration.

• Confirmer le comportement de ${VAR}.

• Confirmer le comportement de ${VAR:-fallback}.

• Confirmer que l’absence de secrets pour les services optionnels reste non fatale.

• Vérifier que les diagnostics et logs ne révèlent aucun secret.

• Confirmer que kb-pipeline-demo-scenarios ne dépend pas directement de dotenvy.

• Valider réellement la résolution de HELIUS_API_KEY depuis .env.

4. Logging

• Console runtime observée sur le profil mainnet_research.
• Confirmer la console active pour local_devnet.
• Confirmer la console active pour mainnet.
• Vérifier l’absence de routes Bot2 réellement obsolètes.
• Vérifier les targets kb-lib.decoder.*.
• Vérifier les targets kb-lib.executor.*.
• Vérifier les targets kb-lib.materializer.*.
• Vérifier qu’aucun ancien répertoire de logs correspondant à une crate supprimée n’est recréé.

5. Tauri et séparation des responsabilités

• Les principales commandes Tauri ont été déplacées vers leurs modules fonctionnels.
• Auditer tauri.rs et vérifier qu’il ne conserve que l’enregistrement et des wrappers minces.
• Déplacer toute logique Decode replay, Backfill, SQL replay ou Exécution encore substantielle hors de tauri.rs.
• Vérifier les wrappers restants après ce dernier déplacement.
• Garantir que les tests unitaires résident dans les modules fonctionnels, pas dans les wrappers Tauri.
• Fermeture explicite et Clippy propres sur l’état pre.061.
• Revalider timeout HTTP et arrêt global de l’application lors de la campagne finale runtime.

6. PostgreSQL et reconstruction

• Tables raw et dérivées classées.
• Script reset_derived_store_keep_raw.sql corrigé avec TRUNCATE ... RESTART IDENTITY.
• kb_sol_raw_transactions conservée.
• kb_sol_obs_transaction_observations classée comme acquisition à conserver lors des futurs resets.
• La perte des anciennes observations de la base de démonstration actuelle est acceptée ; aucune restauration n’est requise.
• Extraction Core complète des 4 574 raws validée.
• Replay complet des décodeurs enregistrés validé.
• Matérialisation sans erreur de ledger validée.
• Compteurs et anomalies du replay analysés.
• Créer kb-store/maintenance/README.md.
• Documenter précisément les tables conservées, les tables dérivées et l’ordre de reconstruction.
• Documenter le contrôle des index et contraintes après recréation du schéma.
• Documenter la future transition vers une nouvelle base alimentée en temps réel par worker, complétée par backfills ciblés ou automatisés.

7. Parité fonctionnelle avant Metaplex Executor

L’objectif n’est pas de produire un rapport historique Bot2 permanent. Il faut confirmer que le périmètre requis est présent et utilisable dans Bot3.

7.1 Décodage et matérialisation

• Solana Core : replay réel validé sur la base de démonstration.
• SPL Memo : replay réel validé.
• SPL Token classique : replay réel validé.
• SPL ATA : replay réel validé.
• SPL Token-2022 : replay réel validé.
• ElGamal Registry : obtenir une fixture ou campagne réelle de décodage d’instruction et d’état.
• Extraction Core : campagne complète validée.
• Replay : campagne complète validée.
• Matérialisation : aucune erreur de matérialiseur observée.
• PostgreSQL : reconstruction et persistance validées.
• Identifier les 3 erreurs de campagne résiduelles comme timeouts transitoires du pool PostgreSQL, sans échec final de décodeur persisté.
• Séparer dans le résumé failedInputs des erreurs d’orchestration ou de stockage via processingErrorInputs.
• Dimensionner le pool et ajouter un retry borné pour les timeouts transitoires avant la campagne finale.

7.2 Transport et infrastructure

• Backfill HTTP validé en runtime.
• HTTP JSON-RPC validé en runtime.
• WebSocket validé en runtime.
• Logging validé sur mainnet_research.
• Configuration principale chargée et utilisée en runtime.
• Valider les profils local_devnet et mainnet lors de la campagne finale.

7.2.1 Stabilisation frontend avant 0.1.0-pre.062

• Corriger les quatre conteneurs HTML finaux signalés par RustRover.
• Remplacer les favicons absentes par imgs/logo.png.
• Valider visuellement les fenêtres Config, HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL.
• Séparer les JSON viewers des sorties textuelles et conserver Copier/Effacer sur les sorties sans viewer selon leur volatilité.
• Rendre le journal des annotations responsive et paginé avec DataTables.
• Étendre DataTables aux tableaux de diagnostic SQL.
• Corriger les avertissements frontend connus : API Rollup names, exception locale, initialiseur redondant et sélecteur de custom element.
• Revalider le frontend en runtime après application du dernier correctif.

7.3 Exécution

• Vérifier Exécution Solana Core via la fenêtre desktop et les scénarios Devnet.
• Vérifier Exécution SPL via la fenêtre desktop et les scénarios Devnet.
• Comparer les options de demo_execution_spl.html aux scénarios réellement supportés.
• Supprimer les options mortes.
• Raccorder ou documenter execute_devnet_spl_token_lifecycle s’il reste non exposé par l’application.
• Vérifier simulation, envoi, progression, résumé et diagnostics.
• Vérifier replay post-exécution et matérialisation pour chaque famille supportée.

8. Guide Devnet des exécuteurs

Créer une documentation dédiée, distincte des README généraux :

• Créer la première version de docs/DEVNET_EXECUTION_GUIDE.md avant les tests ; la compléter et la corriger pendant les campagnes Devnet.
• Documenter la création en ligne de commande d’un wallet de démonstration.
• Documenter la récupération de la pubkey.
• Imposer l’utilisation d’un faucet Web pour financer le wallet Devnet ; ne pas dépendre de solana airdrop, non fonctionnel dans l’environnement de validation.
• Documenter les champs à saisir dans l’interface desktop.
• Documenter chaque scénario Solana Core étape par étape.
• Documenter chaque scénario SPL étape par étape.
• Documenter les préconditions, comptes, signers, frais estimés et résultats attendus.
• Documenter le replay et les projections à vérifier après chaque exécution.
• Ajouter ensuite les scénarios Metaplex Token Metadata.

8.1 Convention et admission des IDL

• Documenter la convention <PROGRAM_ID>.<protocol_type>.<protocol_code>[.<version>].json dans idls/001.README.md.
• Renommer l’IDL active Metaplex Token Metadata avec le segment metadata.
• Conserver le contenu JSON des IDL strictement inchangé.
• Décider que la classification et le renommage des autres IDL seront effectués au moment où leur décodeur ou exécuteur devient actif.
• Maintenir progressivement un inventaire des sources, versions ou commits des IDL actives.

8.1 Ordre metadata après validation des exécuteurs existants

• Créer le pipeline metadata général et la fenêtre desktop spécialisée demo_execution_metadata.
• Traiter d’abord SPL Token Metadata incorporé à Token-2022.
• Traiter ensuite le programme Metaplex Token Metadata et son exécuteur.
• Décider ensuite de la création de kb-offchain-transport comme transport off-chain général : metadata HTTP(S)/IPFS/Arweave, prix et taux, APIs Jupiter et autres fournisseurs ; évaluer séparément les opérations off-chain mutables.

9. Metaplex Token Metadata — décodeur

• IDL JSON local présent et renommé selon <PROGRAM_ID>.<protocol_type>.<protocol_code>.json.
• Six erreurs réelles isolées : 5 create_metadata_account_v3, 1 transfer.
• Cause des faux échecs identifiée : comparaison stricte incorrecte des privilèges globaux avec les metas CPI.
• Validation corrigée pour exiger les privilèges nécessaires sans refuser les privilèges supplémentaires.
• Replay ciblé : 6 décodées, 0 échec.
• Loader : transactions échouées, payloads tronqués et variantes inconnues distingués.
• Comparer systématiquement runtime, IDL local, builders et interface officielle pour les variantes couvertes.
• Vérifier les comptes optionnels et variantes legacy.
• Ajouter des fixtures issues des six transactions réelles sans dépendre de la base runtime.
• Étendre le replay Metaplex à un corpus plus large que les six signatures de correction.
• Vérifier les comptes Metaplex et leurs rôles sur instructions externes et CPI.
• Fermer explicitement la matrice du décodeur Metaplex avant de commencer son exécuteur.

10. Metaplex Token Metadata — exécuteur et Devnet

Étape fonctionnelle suivante.

• Définir les opérations exécutables et celles restant decode-only.
• Compléter les intents typés.
• Compléter les builders.
• Comparer chaque builder aux builders officiels.
• Valider l’ordre exact des comptes.
• Valider signer et writable flags.
• Gérer les comptes optionnels et variantes supportées.
• Ajouter les politiques de sécurité.
• Imposer simulation-first.
• Interdire l’envoi mainnet par défaut.
• Ajouter limites de coût, estimation des frais et plafond de dépense.
• Ajouter validation post-exécution.
• Ajouter tests unitaires et matrice de couverture.
• Ajouter scénarios Devnet explicites dans kb-pipeline-demo-scenarios.
• Exposer les scénarios supportés dans l’application desktop.
• Afficher plan, signers, simulation, envoi et résultat.
• Effectuer le replay post-exécution.
• Vérifier décodage et matérialisation.
• Afficher des diagnostics bornés.

11. Anchor

À traiter après clôture complète de Metaplex Token Metadata et avant les protocoles applicatifs.

• Définir la stratégie d’exploitation des IDL Anchor locaux.
• Définir les contrats génériques de discriminants, comptes et événements.
• Définir les limites entre décodage générique Anchor et décodeurs spécialisés par protocole.
• Ajouter tests et documentation avant intégration de Pump.fun, Raydium, Meteora, Jupiter ou autres protocoles Anchor.

12. Documentation finale

Cette section ne commence qu’après validation des exécuteurs actuels et clôture fonctionnelle Metaplex.

12.1 README

• Réécrire le README racine pour décrire uniquement Bot3 et son architecture actuelle.
• Réécrire le README de chaque crate pour expliquer son rôle, ses responsabilités et ses limites.
• Ajouter des liens vers les documents spécialisés pertinents.
• Retirer le récit de migration Bot2 → Bot3 des documents actifs.
• Retirer les listes d’évolution par version des README.
• Lorsqu’une fonctionnalité évolue, modifier le paragraphe fonctionnel correspondant au lieu d’ajouter une entrée chronologique.

12.2 Usage des APIs et binaires

• Créer un USAGE.md dans chaque crate publique ou binaire pertinent.
• Lister les APIs publiques réellement destinées aux consommateurs.
• Fournir des exemples Rust compilables ou quasi compilables.
• Documenter les types, traits, fonctions, builders, erreurs, invariants et limites.
• Documenter les commandes et options des binaires.
• Documenter les workflows d’intégration entre crates.
• Éviter de recopier mécaniquement toute l’API interne.

12.3 Documentation issue de Bot2

• Inventorier les documents Bot2 encore fonctionnellement pertinents.
• Réécrire leur contenu pour l’architecture, les noms et les règles Bot3.
• Ne conserver aucune formulation laissant penser que Bot3 dépend conceptuellement de Bot2.
• Supprimer les documents de migration devenus inutiles, dont cette checklist.

12.4 IDL

L’ancien bloc docs/IDL_SOURCES.md n’est pas un prérequis autonome puisque les IDL sont déjà stockés localement.

• Ajouter dans la documentation technique existante un inventaire léger des IDL réellement présents sous idls/.
• Pour chaque IDL utilisé, indiquer protocole, Program ID, source, version/commit connu, chemin local et usage.
• Ne pas inventer de source ou de version absente.

13. Versionnement final

• Clôturer toutes les tâches fonctionnelles de cette checklist.
• Terminer la documentation finale.
• Vérifier qu’aucun document actif ne présente Bot2 comme dépendance historique nécessaire.
• Aligner les versions du workspace Bot3 sur 0.4.7.
• Mettre à jour CHANGELOG.md avec l’état fonctionnel final, sans dupliquer les README.
• Produire l’archive finale selon docs/DELTA_WORKFLOW.md.
• Supprimer KHADHROONY_BOT3_MIGRATION_CLOSURE_TODO.md après validation explicite de la clôture.

14. Validation finale

• cargo fmt --all.
• cargo test --workspace.
• cargo check --workspace.
• cargo clippy --all-targets.
• python3 scripts/audit_rust_workspace_rules.py.
• Vérifier les bindings TS-RS régénérés.
• Vérifier l’absence de secrets dans l’archive.
• Vérifier l’absence de target, node_modules, dist, logs, bases, .env, Cargo.lock, package-lock.json et bindings générés exclus par les règles de livraison.
• Valider toutes les fenêtres desktop.
• Valider HTTP, WebSocket, Backfill, Core extraction, Decode replay et SQL.
• Valider Exécution Solana Core et Exécution SPL sur Devnet.
• Valider Metaplex Executor et replay post-exécution sur Devnet.
• Valider configuration, logging et PostgreSQL sur les profils requis.
• Vérifier que les protocoles applicatifs différés sont documentés hors de cette checklist.

15. Critères de clôture

• Aucun import ou chemin d’ancienne crate ne subsiste.
• Convention Token-2022 définitivement appliquée et, si nécessaire, données dérivées migrées ou rejouées.
• Tauri ne contient plus de logique métier substantielle.
• UI sans contrôle mort ou dupliqué.
• Configuration et secrets validés.
• Logging propre sur tous les profils requis.
• Reconstruction PostgreSQL documentée et reproductible.
• Solana Core, SPL, Metaplex Token Metadata et Anchor au niveau requis avant protocoles applicatifs.
• Exécuteurs supportés validés sur Devnet.
• Documentation active entièrement réécrite pour Bot3.
• USAGE.md disponibles pour les surfaces publiques et binaires.
• Workspace aligné sur 0.4.7.
• Cette checklist est supprimée.