khadhroony-bot3/migration/khadhroony-bot2-reference/prompts/019_v0_4_0_decoder_infrastructure.md

Prompt v0.4.0 — infrastructure commune de décodage et matérialisation

Statut

Prompt actif depuis la clôture de 0.3.4 le 7 juillet 2026.

Précondition satisfaite

0.3.4 est validée et inscrite dans CHANGELOG.md. Les validations finales ont confirmé kb_pipeline avec 24 tests, kb_store_pg avec 39 tests incluant le rollback PostgreSQL réel et cargo clippy --all-targets sans avertissement.

La fondation disponible est :

kb_sol_raw_transactions
  -> kb_sol_core_transactions
  -> kb_sol_core_account_keys
  -> kb_sol_core_instructions
  -> kb_sol_core_inner_instructions
  -> kb_sol_core_logs
  -> kb_sol_core_balance_changes
  -> kb_sol_ops_processing_ledger

Les campagnes core disposent déjà de la sélection par signatures, pending, slots et programme, du skip version/hash, du force replay, de la concurrence bornée, de l’arrêt coopératif et de demo_sql_replay_candidates.

Objectif

Construire l’infrastructure générique permettant aux futurs décodeurs Solana Core, SPL et protocolaires de recevoir un input core contextualisé, de produire des observations décodées versionnées, puis de déclencher des matérialisations explicitement autorisées.

0.4.0 ne doit pas encore devenir une version de décodage maximal d’un protocole précis. Elle stabilise les contrats, le dispatch, le ledger, les stores, la couverture et le replay communs.

Principes obligatoires

Indépendance

• un décodeur ne dépend pas de PostgreSQL, Tauri ou d’un fournisseur RPC ;
• kb_decoder_api dépend uniquement des modèles et contrats backend-agnostiques nécessaires ;
• kb_materializer_api reçoit des événements décodés stables et leur contexte ;
• kb_pipeline orchestre sélection, dispatch, persistance, replay et arrêt ;
• kb_store_pg implémente les repositories concrets.

Input contextualisé

Le contrat de décodage doit fournir au minimum :

• signature, slot et statut on-chain de la transaction ;
• err_json lorsque la transaction a échoué ;
• instruction path stable ;
• program ID ;
• comptes résolus dans l’ordre original ;
• payload brut déterministe et son hash ;
• inner instructions descendantes utiles ;
• logs reliés prudemment ;
• changements de balances pertinents ;
• version du contrat core.

Réutiliser ou faire évoluer MdCoreInstructionReplayInput au lieu de recréer un modèle parallèle par décodeur.

Transactions échouées

Les transactions on-chain échouées doivent être décodées lorsqu’un input structurel existe.

Un événement décodé doit conserver explicitement :

transaction_failed
transaction_error
observation_committed = false lorsque la mutation a été annulée

Une transaction échouée peut produire :

• une observation d’instruction tentée ;
• une observation d’événement loggé avant l’erreur ;
• une classification de l’échec ;
• des métriques de compute et de surface appelée.

Elle ne doit pas produire automatiquement :

• un trade réussi ;
• une modification de liquidité réussie ;
• un changement de catalogue considéré comme confirmé ;
• une candle normale issue d’un swap annulé.

Le matérialiseur doit appliquer une politique explicite par famille d’événement, et non une simple hypothèse basée sur la présence d’un log.

Contrats de décodeur

Stabiliser dans kb_decoder_api :

• identité du décodeur ;
• version ;
• programmes et surfaces supportés ;
• capacité à reconnaître un input ;
• résultat decoded, ignored, unsupported ou failed ;
• confiance et preuve de décodage ;
• événements décodés typés ;
• diagnostics sans anyhow ni thiserror ;
• couverture déclarée des instructions, événements et discriminants.

Le dispatch doit être déterministe par :

program_id
surface_code éventuel
instruction_path
payload/discriminator
contexte inner/logs

Aucun dispatch ne doit reposer sur le nom d’une crate ou sur un ordre implicite non documenté.

Contrats de matérialisation

Stabiliser dans kb_materializer_api :

• identité et version du matérialiseur ;
• familles d’événements acceptées ;
• politique pour transaction réussie/échouée ;
• sortie métier typée ;
• idempotence et clés stables ;
• résultat inséré, remplacé, ignoré ou refusé.

Le matérialiseur ne doit jamais modifier directement les tables core.

Persistance et ledger

Définir les tables actives nécessaires avec le nommage :

kb_sol_decode_*
kb_sol_mat_*
kb_sol_ops_processing_ledger

Ne pas créer de schema PostgreSQL applicatif explicite.

Le ledger doit distinguer au minimum :

stage = instruction_decode
stage = event_materialization
processor_name
processor_version
input_key
input_hash
status
attempt_count
error_code
error_message

Le skip doit dépendre de la version du processor et d’un hash déterministe de l’input pertinent. Le force replay doit remplacer uniquement les sorties appartenant au processor et à l’input ciblés.

Couverture

Ajouter une matrice machine-readable permettant de comparer :

• entrées déclarées par le décodeur ;
• entrées observées dans le corpus ;
• entrées reconnues ;
• entrées décodées ;
• événements matérialisés ;
• erreurs et inconnues ;
• transactions réussies et échouées.

Ne pas considérer une surface clôturée tant que toutes les instructions et événements connus, y compris historiques et non directement liés au trading, ne sont pas classifiés.

Orchestration kb_pipeline

Ajouter un pipeline versionné avec :

• sélection bornée des instructions core pending, failed ou replay_requested ;
• sélection explicite par signatures, slots, program IDs et instruction paths ;
• dispatch vers zéro, un ou plusieurs décodeurs compatibles selon la politique déclarée ;
• concurrence bornée ;
• arrêt coopératif ;
• skip version/hash ;
• force replay ;
• résumé par processor et statut ;
• persistance atomique des événements décodés et du ledger ;
• appel optionnel des matérialiseurs après succès de persistance du décodage.

Démo Tauri

Ajouter une fenêtre distincte, par exemple demo_decode_replay, sans surcharger demo_core_extraction.

Fonctions minimales :

• sélection de signatures copiées depuis demo_sql_replay_candidates ;
• filtre program ID et instruction state ;
• choix des décodeurs disponibles ;
• version visible ;
• force replay ;
• journal et résumé ;
• arrêt ;
• liens vers diagnostics core, decode, ledger et couverture.

Aucun SQL libre.

Tests obligatoires

Couvrir au minimum :

1. dispatch exact par program ID ;
2. instruction inconnue classée sans faux décodage ;
3. décodage réussi avec hash stable ;
4. skip même version/hash ;
5. replay après changement de version ;
6. force replay sans duplication ;
7. rollback des événements décodés et du ledger ;
8. transaction échouée décodée comme observation non commitée ;
9. refus de matérialiser un trade réussi depuis une transaction échouée ;
10. arrêt coopératif et candidats non démarrés ;
11. couverture déclarée contre couverture observée ;
12. tests PostgreSQL optionnels sous KB_POSTGRES_TEST_URL.

Les tests unitaires doivent être offline.

Hors périmètre

• décodage maximal System/SPL, prévu dans 0.4.1+ ;
• Pump, Meteora, Raydium, Orca et autres protocoles ;
• Helius transactionSubscribe ;
• Yellowstone gRPC ;
• wallet et trading ;
• pools/paires déduits par heuristique depuis de simples account keys.

Fichiers à lire en priorité

• ROADMAP.md ;
• RULES.md ;
• docs/CORE_EXTRACTION_CONTRACTS.md ;
• docs/CORE_EXTRACTION_SELECTION_AND_REPLAY.md ;
• docs/INSTRUCTION_REPLAY_CONTRACTS.md ;
• kb_decoder_api/ ;
• kb_materializer_api/ ;
• kb_store_core/src/dtos/core_dtos.rs ;
• kb_store_core/src/repositories/storage_repositories.rs ;
• kb_pipeline/src/core_extraction.rs ;
• kb_store_pg/src/queries/core_extraction_queries.rs ;
• kb_app_demo/src/demo_core_extraction.rs ;
• kb_program_ids/src/lib.rs.

Règles de réalisation

• Rust 2024 ;
• async-first ;
• tracing obligatoire ;
• erreurs explicites ;
• aucun ?, unwrap, expect, anyhow ou thiserror dans le code de production ;
• aucun use sauf pour les traits ;
• appels locaux via crate:: ;
• #![warn(missing_docs)], #![deny(unreachable_pub)] et #![forbid(unsafe_code)] ;
• documentation du code en anglais ;
• documentation Markdown en français ;
• headers file / version incrémentés à chaque modification ;
• aucune ligne vide dans les corps de fonctions ou structures ;
• TS-rs pour les types Tauri ;
• ne pas modifier CHANGELOG.md avant validation complète.

Validation attendue

cargo test -p kb_decoder_api
cargo test -p kb_materializer_api
cargo test -p kb_store_core
cargo test -p kb_pipeline
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
  cargo test -p kb_store_pg -- --nocapture
cargo test -p kb_app_demo
(cd kb_app_demo && npm run build)
cargo clippy --all-targets
cargo tauri dev -c kb_app_demo/tauri.conf.json

Livraison

Produire uniquement un zip delta :

khadhroony-bot2_v0.4.0-pre.001-delta.zip

Le delta doit contenir delta.md, les fichiers ajoutés ou modifiés et la liste explicite des suppressions manuelles. Ne pas produire d’archive complète sauf demande explicite.