Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
626385f9b631c472fea00cf624b7f473e746ae2d
khadhroony-bot3/prompts/KHADHROONY_BOT3_MIGRATION_CONTINUATION_PROMPT_REORDERED.md
SinuS Von SifriduS 626385f9b6 v0.1.0-pre.059
2026-07-27 10:02:26 +02:00

18 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.

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.
Reference in New Issue View Git Blame Copy Permalink