Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
460671e19debcd2bcbbc66ac1fbe4378515b3122
khadhroony-bot3/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md
SinuS Von SifriduS f40fb78817 v0.1.0-pre.061
2026-07-28 18:41:30 +02:00

21 KiB
Raw Blame History

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 :
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 :

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 :

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 :

metadata_metaplex_token_metadata

Program ID :

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 :

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

Chemins attendus :

../frontend/ts/bindings/kb_config/...
../frontend/ts/bindings/kb_lib/...
../frontend/ts/bindings/kb_app_demo_desktop/...

Supprimer les chemins historiques :

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

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

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 :

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 :

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 :

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 :

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 à :

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

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 :

cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json

Clippy en dernier :

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.

État ajouté par pre.061

  • La reconstruction propre a extrait 4 574 transactions raw sur 4 574 puis dispatché 11 880 instructions.
  • Les 76 faux échecs Loader provenaient de transactions déjà échouées avec payloads réellement courts ou comptes insuffisants. Ils doivent devenir des observations Decoded non engagées malformed_loader_instruction; les quatre tags Loader v4 u32 inconnus restent Unsupported.
  • Les six faux échecs Metaplex provenaient d'une comparaison exacte des flags globaux de transaction avec les metas attendues de l'instruction CPI. La validation exige désormais uniquement les privilèges requis et accepte les privilèges supplémentaires.
  • Ne pas commencer Pump.fun, Raydium, Meteora, Jupiter, autres AMM ou launchpads avant clôture de Solana Core, SPL, Metaplex et Anchor.
  • Relancer après application un replay forcé limité aux 82 entrées en échec, puis le replay complet si le résultat est propre.

Validation v0.1.0-pre.061 et correctif attendu

  • Replay ciblé après pre.061 : 123 entrées, 123 terminées, 0 échec.
  • Metaplex : 6/6 décodées (create_metadata_account_v3 x5, transfer x1).
  • Loader : 84 décodées et 4 tags Loader v4 inconnus conservés Unsupported, 0 échec.
  • kb-store : 84 tests réussis.
  • kb-app-demo-desktop : 116 tests réussis après appels explicites ProgramIdEntry::code() et program_id().
  • cargo check --workspace et cargo clippy --all-targets réussissent.
  • Le test Metaplex collection_size_variants_reject_truncated_wire_invalid_flags_and_suffixes doit tester l'absence d'un privilège requis, et non un privilège supplémentaire désormais accepté pour les CPI.
  • L'audit RUST021 exige un rustdoc adjacent au réexport DemoDecodeReplayProgramOption.
  • La première correction de cette prerelease doit être nommée khadhroony-bot3_v0.1.0-pre.061-delta-fix-001.zip.
Reference in New Issue View Git Blame Copy Permalink