0.1.0

migration/khadhroony-bot2-reference/prompts/.gitignore

@@ -0,0 +1,3 @@
+# file: prompts/.gitignore
+# version: 1
+

migration/khadhroony-bot2-reference/prompts/001_version_session_template.md

@@ -0,0 +1,60 @@
+<!-- file: prompts/001_version_session_template.md -->
+<!-- version: 1 -->
+
+# Template de prompt de session
+
+## Contexte
+
+Tu travailles sur le workspace `khadhroony-bot2`. Le workspace utilise une architecture modulaire Rust avec séparation stricte entre modèles, RPC, stockage, pipeline, décodeurs, matérialisateurs, exécuteurs, applications et worker.
+
+## Règles obligatoires
+
+- Lire `RULES.md` avant toute proposition de modification.
+- Ne pas modifier `CHANGELOG.md` avant validation explicite de version.
+- Mettre les changements futurs dans `ROADMAP.md`.
+- Ne pas utiliser `use` dans le code Rust sauf pour les traits nécessaires.
+- Utiliser `crate::` pour les chemins internes à la crate courante.
+- Utiliser le chemin complet de crate pour les dépendances externes du workspace.
+- Préserver les en-têtes `file:` et `version:`.
+- Garder la documentation de code en anglais et la documentation Markdown en français.
+- Fournir uniquement un zip delta après le squelette initial.
+
+## Format de livraison attendu
+
+- Si le delta modifie la racine du workspace ou plusieurs modules : `khadhroony-bot2_vX.Y.Z-pre.abc.zip`.
+- Si le delta modifie un seul module Rust : `kb_modulename_vX.Y.Z-pre.abc.zip`.
+- Le zip doit contenir un `delta.md` non versionné.
+- `delta.md` doit lister les fichiers ajoutés, modifiés, à supprimer manuellement, et les validations exécutées ou non exécutées.
+- Le zip ne doit contenir que les fichiers ajoutés ou modifiés, plus `delta.md`.
+
+## Objectif de la session
+
+Décrire ici la version ciblée, le périmètre technique et les résultats attendus.
+
+## Fichiers à lire en priorité
+
+- `README.md`
+- `RULES.md`
+- `ROADMAP.md`
+- `docs/ARCHITECTURE.md`
+- `docs/DATABASE.md`
+- `docs/NOMENCLATURE.md`
+- `docs/DECODER_SURFACE_AUDIT.md`
+- `docs/DELTA_WORKFLOW.md`
+
+## Travail demandé
+
+Décrire ici les fichiers ou crates à modifier, créer ou supprimer.
+
+## Validations attendues
+
+- `cargo build`
+- `cargo test --workspace`
+- `cargo clippy --workspace --all-targets`
+- contrôles SQL si une migration ou une table est modifiée.
+
+## Interdictions
+
+- Ne pas ajouter de logiques métier dans les crates applicatifs.
+- Ne pas fusionner decode et materialize.
+- Ne pas promouvoir un décodeur réservé sans `program_id`, corpus et validation locale.

migration/khadhroony-bot2-reference/prompts/002_program_registry_and_naming_audit.md

@@ -0,0 +1,23 @@
+<!-- file: prompts/002_program_registry_and_naming_audit.md -->
+<!-- version: 1 -->
+
+# Prompt de session : audit du registre des programmes
+
+Objectif : contrôler les `program_id`, les noms sources, les aliases et les crates cibles avant tout renommage physique de dossiers.
+
+## Instructions
+
+- Utiliser `registry/program_registry_seed.toml` comme source de départ.
+- Vérifier les doublons exacts de `program_id`.
+- Vérifier les surfaces qui ont plusieurs noms historiques.
+- Ne pas supprimer de crate tant que le `program_id` et la surface ne sont pas confirmés.
+- Produire uniquement un delta après validation.
+- Respecter la convention `kb_decoder_<function_code>_<family_code>_<identifier_code>[_vN]`.
+
+## Résultat attendu
+
+- Une liste de renommages sûrs.
+- Une liste de crates aliases à conserver temporairement.
+- Une liste de surfaces réservées mais non prioritaires.
+- Une mise à jour du registre et de la roadmap.
+

migration/khadhroony-bot2-reference/prompts/003_v0_1_logging_config_profiles.md

@@ -0,0 +1,39 @@
+<!-- file: prompts/003_v0_1_logging_config_profiles.md -->
+<!-- version: 1 -->
+
+# Prompt v0.1.x — logging, configuration et profils
+
+Objectif : finaliser `kb_logging` et `kb_config` avant SQL/RPC/wallet.
+
+## Phasage cible
+
+- `0.1.0` : `kb_logging` réel.
+- `0.1.1` : `kb_config`, parsing JSON et validation des profils.
+- `0.1.2` : liaison `kb_logging` depuis le profil actif.
+- `0.1.3` : rôles d'endpoints HTTP/WS et limites par rôle.
+- `0.1.4` : démo Tauri configuration/logging.
+
+## Contraintes
+
+- Conserver plusieurs profils de configuration avec un seul profil actif.
+- Ne pas ajouter `api_key_env_var` : les placeholders de clés restent dans les URLs.
+- Couvrir seulement HTTP JSON-RPC et WebSocket Solana standard avant `v1.x`.
+- Ne pas implémenter gRPC, Helius enhanced WebSocket, Helius gRPC ou LaserStream dans cette version.
+- Router les logs par target, niveau et sortie : console, fichier humain, fichier JSON, fichier erreurs.
+- Router les endpoints par rôle et par type de requête.
+- Conserver les règles Rust : pas de `use` sauf traits, `crate::` en interne, pas de `?` production, pas de `unwrap`.
+
+## Format de livraison attendu
+
+- Fournir un zip delta uniquement.
+- Utiliser `khadhroony-bot2_v0.1.X-pre.abc.zip` si le delta touche plusieurs modules ou la racine.
+- Utiliser `kb_logging_v0.1.X-pre.abc.zip` ou `kb_config_v0.1.X-pre.abc.zip` si le delta touche un seul module.
+- Inclure `delta.md` non versionné dans le zip.
+
+## Livrables attendus
+
+- `kb_logging` fonctionnel.
+- `kb_config` typé et validé.
+- Exemple `config/example.config.json` complet.
+- Démo Tauri de chargement de configuration.
+- Tests unitaires de parsing/sérialisation.

migration/khadhroony-bot2-reference/prompts/004_v0_2_sql_storage_materialization.md

@@ -0,0 +1,242 @@
+<!-- file: prompts/004_v0_2_sql_storage_materialization.md -->
+<!-- version: 3 -->
+
+# Prompt v0.2.x — conventions SQL, stockage PostgreSQL et contrats DB
+
+Objectif : ouvrir la phase `0.2.x` de `khadhroony-bot2` en cadrant d'abord les conventions de stockage avant d'implémenter les migrations, repositories et diagnostics DB.
+
+## État de départ attendu
+
+- `0.1.0` validée : `kb_logging` réel.
+- `0.1.1` validée : `kb_config` typé, schéma JSON et profils.
+- `0.1.2` validée : liaison `kb_logging` / `kb_config` / `kb_app_demo`.
+- `0.1.3` validée : clients HTTP/WS Solana standard, rôles, pools et démos RPC.
+- Le commit `v0.1.3` doit être considéré comme base propre.
+
+## Objectif de `0.2.0`
+
+`0.2.0` doit d'abord verrouiller les conventions DB. Ne pas commencer directement par un grand schéma SQL.
+
+Livrables attendus :
+
+- conventions de nommage PostgreSQL ;
+- conventions de tables Solana ;
+- conventions `entities/`, `dtos/`, `queries/`, `repositories/` ;
+- rôle exact de `kb_store_core` et `kb_store_pg` ;
+- premières tables candidates documentées ;
+- prompt ou README de suite pour `0.2.1`.
+
+## Convention PostgreSQL obligatoire
+
+Ne pas créer de schemas PostgreSQL applicatifs explicites comme `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`.
+
+PostgreSQL doit utiliser le schema courant/default du profil, généralement `public`.
+
+La séparation logique se fait dans le nom de table.
+
+## Convention de nommage des tables
+
+Format obligatoire :
+
+```text
+kb_sol_<domain>_<name>
+```
+
+Domaines autorisés au départ :
+
+```text
+raw
+core
+obs
+decode
+mat
+catalog
+agg
+ops
+wallet
+```
+
+Exemples de tables candidates :
+
+```text
+kb_sol_raw_rpc_transactions
+kb_sol_raw_ws_notifications
+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_obs_program_observations
+kb_sol_obs_instruction_observations
+kb_sol_decode_decoded_events
+kb_sol_mat_trade_events
+kb_sol_catalog_tokens
+kb_sol_catalog_pools
+kb_sol_catalog_pairs
+kb_sol_ops_processing_ledger
+```
+
+Interdictions, écrites avec `DOT` pour que les audits textuels simples ne confondent pas documentation et usage réel :
+
+```text
+raw DOT kb_sol_rpc_transactions
+core DOT kb_sol_transactions
+obs DOT kb_sol_program_observations
+decode DOT kb_sol_decoded_events
+mat DOT kb_sol_trade_events
+catalog DOT kb_sol_tokens
+ops DOT kb_sol_processing_ledger
+```
+
+## Règles SQL générales
+
+- `id` : clé primaire technique.
+- `created_at` : timestamp d'insertion.
+- `updated_at` : timestamp de dernière modification si la table est mutable.
+- `slot` : `BIGINT` côté SQL, converti explicitement côté Rust si nécessaire.
+- `signature` : texte non vide.
+- `program_id` : texte non vide quand applicable.
+- `raw_json` : JSONB pour payload brut immuable.
+- `payload_json` : JSONB pour payload décodé ou matérialisé.
+- Index minimaux : signature, slot, program id, created_at selon table.
+- Ne pas inventer de contraintes métier trop tôt : commencer strict mais réversible.
+
+## Layout Rust obligatoire
+
+Dans `kb_store_core` :
+
+```text
+src/
+  lib.rs
+  pagination.rs
+  health.rs
+  db_error.rs
+  dtos/
+  entities/
+  repositories/
+```
+
+Dans `kb_store_pg` :
+
+```text
+src/
+  lib.rs
+  pg_store.rs
+  migrations.rs
+  queries/
+  repositories/
+```
+
+Règles :
+
+- `entities/` contient les représentations proches des lignes SQL.
+- `dtos/` contient les contrats applicatifs, Tauri ou repository.
+- `queries/` contient uniquement SQL, bind et exécution.
+- `repositories/` contient les APIs de stockage.
+- Ne pas placer de struct métier ou DB dans `queries/`.
+
+## Crates à auditer avant modification
+
+- `kb_core`
+- `kb_config`
+- `kb_store_core`
+- `kb_store_pg`
+- `kb_app_demo`
+- `kb_rpc` seulement si le stockage raw RPC exige un type partagé.
+
+## Phasage recommandé
+
+### `0.2.0`
+
+- conventions storage ;
+- conventions tables ;
+- conventions Rust store ;
+- README des crates store ;
+- aucun gros schéma SQL.
+
+### `0.2.1`
+
+- contrats `kb_store_core` ;
+- types communs ;
+- DTO/entities minimaux ;
+- traits repository offline.
+
+### `0.2.2`
+
+- connexion PostgreSQL dans `kb_store_pg` ;
+- pool ;
+- healthcheck ;
+- stratégie de migrations ;
+- tests offline autant que possible.
+
+### `0.2.3`
+
+- raw store Solana minimal :
+  - `kb_sol_raw_rpc_transactions` ;
+  - `kb_sol_raw_ws_notifications`.
+
+### `0.2.4`
+
+- core store Solana minimal :
+  - transactions ;
+  - account keys ;
+  - instructions ;
+  - inner instructions ;
+  - logs ;
+  - balance changes ;
+  - observations ;
+  - processing ledger.
+
+### `0.2.5`
+
+- fenêtre Tauri diagnostic DB :
+  - profil actif ;
+  - backend ;
+  - DSN masqué ;
+  - schema courant ;
+  - tables détectées ;
+  - migrations ;
+  - healthcheck.
+
+## Contraintes Rust à conserver
+
+- Rust 2024.
+- `#![warn(missing_docs)]`.
+- `#![deny(unreachable_pub)]`.
+- `#![forbid(unsafe_code)]`.
+- Pas de `use` sauf traits.
+- `crate::` en interne.
+- Pas de `?` en production.
+- Pas de `unwrap`.
+- Pas de `expect`.
+- Pas de `anyhow`.
+- Pas de `thiserror`.
+- Erreurs via `kb_core::Error` et `kb_core::Result`.
+
+## Contraintes de livraison
+
+- Fournir un zip delta uniquement.
+- Si plusieurs crates ou la racine sont touchées, utiliser :
+  - `khadhroony-bot2_v0.2.X-pre.abc.zip`
+- Si une seule crate est touchée, utiliser :
+  - `kb_store_core_v0.2.X-pre.abc.zip`
+  - ou `kb_store_pg_v0.2.X-pre.abc.zip`
+- Inclure `delta.md` non versionné dans le zip.
+- Ne pas modifier `CHANGELOG.md` avant validation locale du jalon.
+
+## Validations attendues
+
+À adapter selon le delta :
+
+```bash
+cargo test -p kb_store_core
+cargo test -p kb_store_pg
+cargo test -p kb_config
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Si aucun code n'est modifié, documenter explicitement que le delta est documentaire.
+

migration/khadhroony-bot2-reference/prompts/005_v0_2_2_pg_connection_migrations.md

@@ -0,0 +1,58 @@
+<!-- file: prompts/005_v0_2_2_pg_connection_migrations.md -->
+<!-- version: 2 -->
+
+# Prompt de suite — `0.2.2` connexion PostgreSQL et migrations
+
+Objectif : ouvrir `0.2.2` après validation de `0.2.1`, en ajoutant l'infrastructure PostgreSQL minimale dans `kb_store_pg`, sans créer encore le grand schéma Solana.
+
+## Base attendue
+
+- `0.2.0` validée et commitée : conventions PostgreSQL et nommage `kb_sol_<domain>_<name>`.
+- `0.2.1` validée et commitée : contrats `kb_store_core`, DTOs, entities, repositories abstraits, cycle de vie raw, replay par instruction et replay input contextualisé avec account keys, logs et balance changes.
+
+## Périmètre `0.2.2`
+
+Ajouter uniquement l'infrastructure PostgreSQL :
+
+- lecture de la configuration PostgreSQL depuis `kb_config` ;
+- création d'un pool PostgreSQL dans `kb_store_pg` ;
+- healthcheck minimal ;
+- stratégie de migrations ;
+- diagnostic du schema courant ;
+- tests offline autant que possible.
+
+Ne pas créer encore les tables Solana finales. Les premières tables réelles restent prévues pour `0.2.3` et `0.2.4`. Les migrations doivent cependant rester compatibles avec les contrats `CoreInstructionReplayInput`, `CoreLogInsert`, `CoreAccountKeyInsert` et `CoreBalanceChangeInsert`.
+
+## Règle PostgreSQL obligatoire
+
+Ne pas créer de schemas applicatifs explicites comme `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`.
+
+Le store utilise le schema courant du profil PostgreSQL, généralement `public`.
+
+La séparation logique reste dans le nom de table :
+
+```text
+kb_sol_<domain>_<name>
+```
+
+## Points à respecter
+
+- `kb_store_core` reste backend-agnostique.
+- `kb_store_pg` contient les implémentations PostgreSQL.
+- `queries/` contient SQL, bind et exécution.
+- `repositories/` contient les repositories concrets.
+- Aucune struct métier ou DB ne doit être placée dans `queries/`.
+- Pas de `unwrap`, pas de `expect`, pas de `?` en production.
+- Erreurs via `kb_core::Error` et `kb_core::Result`.
+- `CHANGELOG.md` ne doit être modifié qu'après validation locale.
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_core
+cargo test -p kb_store_pg
+cargo test -p kb_config
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+```
+

migration/khadhroony-bot2-reference/prompts/005_v0_3_rpc_ingestion_ws.md

@@ -0,0 +1,40 @@
+<!-- file: prompts/005_v0_3_rpc_ingestion_ws.md -->
+<!-- version: 7 -->
+
+# Prompt historique — ancien périmètre RPC ingestion déplacé vers v0.4.x
+
+Objectif historique : ce périmètre est désormais remplacé par le phasage transaction canonique de `0.3.x`. Pour poursuivre la série active, utiliser `prompts/016_v0_3_2_canonical_transaction_contract.md`.
+
+## À faire
+
+- Implémenter pool HTTP par rôle.
+- Implémenter pool WebSocket standard par rôle.
+- Ajouter ingestion par signature.
+- Stocker `kb_sol_raw_rpc_transactions`.
+- Extraire comptes résolus, instructions, inner instructions, logs et deltas de balances.
+- Construire `kb_sol_obs_program_observations`.
+- Ajouter listeners `logsSubscribe`, `programSubscribe`, `accountSubscribe`, `slotSubscribe`, `rootSubscribe`.
+- Produire des observations brutes sans exécuter d'achat/revente.
+- Ajouter une page Tauri de diagnostic des endpoints et listeners.
+
+
+## Rappel DB
+
+- Ne pas utiliser de schémas PostgreSQL applicatifs explicites.
+- Ne pas revenir aux anciennes formes qualifiées écrites ici avec `DOT` : `raw DOT sol_transactions` ou `obs DOT program_observations`.
+- Les tables Solana doivent rester au format `kb_sol_<domain>_<name>`.
+
+## Hors scope
+
+- gRPC.
+- Helius gRPC.
+- LaserStream.
+- Matérialisation DEX détaillée.
+- Exécution d'achat ou de revente.
+
+## Format de livraison attendu
+
+- Fournir un zip delta uniquement.
+- Utiliser `khadhroony-bot2_v0.4.X-pre.abc.zip` si plusieurs modules ou fichiers racine sont touchés lorsque ce périmètre sera repris.
+- Utiliser `kb_rpc_v0.4.X-pre.abc.zip` si seul `kb_rpc` est touché lorsque ce périmètre sera repris.
+- Inclure `delta.md` non versionné dans le zip.

migration/khadhroony-bot2-reference/prompts/006_v0_4_wallet_execution_demo.md

@@ -0,0 +1,25 @@
+<!-- file: prompts/006_v0_4_wallet_execution_demo.md -->
+<!-- version: 4 -->
+
+# Prompt historique — wallet, exécution core et démos devnet déplacés vers v0.5
+
+Ce prompt utilisait l’ancien phasage `0.4.x`. Le phasage actuel reporte ce périmètre wallet et sécurité à `0.11.x`, après les décodeurs prioritaires et la validation des sources live.
+## Objectif
+
+Rendre `kb_wallet`, `kb_execution_api`, `kb_execution_safety` et les exécuteurs Solana/SPL testables sur devnet depuis `kb_app_demo`.
+
+## Travail demandé
+
+- Charger un wallet local chiffré.
+- Afficher l'adresse et les soldes SOL/SPL.
+- Simuler un transfert SOL.
+- Envoyer un transfert SOL devnet avec confirmation opérateur.
+- Préparer un transfert SPL avec ATA contrôlé.
+- Bloquer toute exécution mainnet tant que les garde-fous ne sont pas validés.
+
+## Validations attendues
+
+- `cargo build`
+- démo Tauri wallet
+- démo Tauri transfert SOL devnet
+- logs de simulation et confirmation

migration/khadhroony-bot2-reference/prompts/007_v0_5_core_decoders_listeners.md

@@ -0,0 +1,23 @@
+<!-- file: prompts/007_v0_5_core_decoders_listeners.md -->
+<!-- version: 4 -->
+
+# Prompt historique — décodeurs core et premiers listeners déplacés vers v0.6
+
+Ce prompt utilisait l’ancien phasage `0.5.x`. Le phasage actuel sépare ce périmètre : décodeurs Core/SPL en `0.4.x`, listeners et trading assisté en `0.12.x`.
+## Objectif
+
+Décoder les programmes Solana/SPL de base et préparer les listeners nécessaires au trading assisté.
+
+## Travail demandé
+
+- Décoder system, compute budget, memo, address lookup table.
+- Décoder SPL Token, Token-2022, ATA et stake pool si applicable.
+- Matérialiser les transferts, mint, burn, close account et ATA.
+- Ajouter listeners WebSocket par `program_id` prioritaire.
+- Notifier créations de pools, migrations, liquidité et swaps quand les surfaces sont prêtes.
+
+## Validations attendues
+
+- `cargo build`
+- replay de signatures contenant SPL Token et ATA
+- notifications Tauri sur events core

migration/khadhroony-bot2-reference/prompts/008_v0_6_priority_dex_router_surfaces.md

@@ -0,0 +1,48 @@
+<!-- file: prompts/008_v0_6_priority_dex_router_surfaces.md -->
+<!-- version: 4 -->
+
+# Prompt historique — surfaces DEX/router prioritaires déplacées vers v0.8
+
+Ce prompt utilisait l’ancien phasage `0.6.x`. Le phasage actuel répartit les surfaces prioritaires de `0.5.x` à `0.9.x` : Pump, Meteora, Raydium, Orca, puis Jupiter et routeurs.
+## Objectif
+
+Développer les premières surfaces prioritaires pour le trading assisté : Pump, Bags Fee Share, Raydium, Meteora, Orca et routers.
+
+## Travail demandé
+
+Pour chaque surface :
+
+- corpus de signatures ;
+- décodeur minimal ;
+- matérialisation minimale ;
+- listener si utile ;
+- exécuteur si la surface est appelable ;
+- simulation ;
+- démo Tauri ;
+- validation post-transaction ;
+- SQL anti-régression.
+
+## Surfaces prioritaires
+
+- `amm_pump_swap`
+- `launchpad_pump_fun`
+- `admin_pump_fees`
+- `fees_bags_fee_share_v1`
+- `fees_bags_fee_share_v2`
+- `amm_raydium_lp_v4`
+- `cpmm_raydium`
+- `clmm_raydium`
+- `launchpad_raydium_launchlab`
+- `launchpad_meteora_dbc`
+- `dlmm_meteora`
+- `amm_meteora_damm_v1`
+- `amm_meteora_damm_v2`
+- `clmm_orca_whirlpool`
+- `router_jupiter_aggregator_v6`
+- `router_okx_labs_v2`
+
+## Validations attendues
+
+- démo Tauri par surface terminée ;
+- matérialisation et validation post-transaction ;
+- aucun envoi mainnet sans confirmation opérateur et limites actives.

migration/khadhroony-bot2-reference/prompts/009_v0_2_1_store_core_contracts.md

@@ -0,0 +1,119 @@
+<!-- file: prompts/009_v0_2_1_store_core_contracts.md -->
+<!-- version: 1 -->
+
+# Prompt v0.2.1 — contrats `kb_store_core`, DTOs, entities et repositories offline
+
+Objectif : ouvrir `0.2.1` après le cadrage `0.2.0` et implémenter les premiers contrats backend-agnostiques de stockage sans écrire de SQL PostgreSQL.
+
+## État de départ attendu
+
+- `0.1.3` validée et commitée comme base propre.
+- `0.2.0` appliquée : conventions PostgreSQL et table naming verrouillées.
+- `CHANGELOG.md` ne doit pas être modifié tant que le jalon courant n'est pas validé localement.
+
+## Rappels obligatoires
+
+- Ne pas créer de schémas PostgreSQL applicatifs explicites.
+- Utiliser le format de table `kb_sol_<domain>_<name>`.
+- Ne pas créer de grand schéma SQL en `0.2.1`.
+- Ne pas implémenter de pool PostgreSQL en `0.2.1`.
+- Ne pas placer de struct métier ou DB dans `queries/`.
+- Les types communs et traits repository vivent dans `kb_store_core`.
+- Les implémentations PostgreSQL restent hors scope jusqu'à `0.2.2` ou `0.2.3` selon le cas.
+
+## Layout cible `kb_store_core`
+
+```text
+src/
+  lib.rs
+  pagination.rs
+  health.rs
+  db_error.rs
+  dtos/
+  entities/
+  repositories/
+```
+
+## Travail demandé
+
+### Pagination et limites
+
+- Définir les types de pagination backend-agnostiques.
+- Définir les limites minimales et maximales.
+- Ajouter des validations offline sans `unwrap`, sans `expect` et sans `?` en production.
+
+### Healthcheck
+
+- Stabiliser le contrat de healthcheck store.
+- Prévoir les champs nécessaires pour la future page Tauri DB : backend, statut, message, schema courant, migrations détectées.
+- Garder les détails PostgreSQL concrets hors de `kb_store_core`.
+
+### Erreurs DB
+
+- Ajouter les helpers ou enums nécessaires autour de `kb_core::Error` et `kb_core::Result`.
+- Ne pas ajouter `anyhow` ni `thiserror`.
+
+### DTOs et entities minimaux
+
+Créer les premiers types pour :
+
+- `kb_sol_raw_rpc_transactions` ;
+- `kb_sol_raw_ws_notifications` ;
+- `kb_sol_core_transactions` ;
+- `kb_sol_core_instructions` ;
+- `kb_sol_ops_processing_ledger`.
+
+Conventions de nommage attendues :
+
+```text
+RawRpcTransactionEntity
+RawWsNotificationEntity
+CoreTransactionEntity
+CoreInstructionEntity
+ProcessingLedgerEntity
+InsertRawRpcTransactionDto
+UpsertRawRpcTransactionDto
+InsertRawWsNotificationDto
+RepositoryPageDto
+StoreHealthDto
+```
+
+### Traits repository offline
+
+Créer ou stabiliser les traits pour :
+
+- raw RPC transaction ;
+- raw WS notification ;
+- core transaction read/write minimal ;
+- core instruction read/write minimal ;
+- processing ledger.
+
+Les traits ne doivent pas dépendre de PostgreSQL.
+
+## Crates à auditer avant modification
+
+- `kb_core`
+- `kb_model`
+- `kb_store_core`
+- `kb_rpc` seulement si un type RPC doit être partagé
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_core
+cargo clippy -p kb_store_core --all-targets
+```
+
+Si `kb_model` est modifié :
+
+```bash
+cargo test -p kb_model
+cargo clippy -p kb_model --all-targets
+```
+
+## Format de livraison attendu
+
+- Si seul `kb_store_core` est touché : `kb_store_core_v0.2.1-pre.abc.zip`.
+- Si plusieurs crates ou fichiers racine sont touchés : `khadhroony-bot2_v0.2.1-pre.abc.zip`.
+- Inclure `delta.md` non versionné dans le zip.
+- Ne fournir que les fichiers ajoutés ou modifiés.

migration/khadhroony-bot2-reference/prompts/010_v0_2_2_postgres_connection_health_migrations.md

@@ -0,0 +1,52 @@
+<!-- file: prompts/010_v0_2_2_postgres_connection_health_migrations.md -->
+<!-- version: 1 -->
+
+# Prompt `0.2.2` — connexion PostgreSQL, pool, healthcheck et stratégie migrations
+
+Objectif : ouvrir `0.2.2` après validation locale de `0.2.1`, en implémentant uniquement la frontière PostgreSQL minimale dans `kb_store_pg`.
+
+## Base attendue
+
+- `0.2.0` validée : conventions DB verrouillées.
+- `0.2.1` validée : contrats `kb_store_core`, DTOs, entities et traits repository offline.
+- `CHANGELOG.md` ne doit être modifié qu'après validation locale.
+
+## Contraintes PostgreSQL
+
+- Ne pas créer de schemas applicatifs PostgreSQL.
+- Utiliser le schema courant/default du profil, généralement `public`.
+- Les tables futures gardent le format `kb_sol_<domain>_<name>`.
+- Ne pas implémenter le gros schéma raw/core dans `0.2.2`.
+
+## Livrables attendus
+
+- lecture du DSN PostgreSQL depuis le profil actif si le contrat de configuration existe déjà ;
+- masquage du DSN pour diagnostics ;
+- création d'un handle/pool PostgreSQL minimal dans `kb_store_pg` ;
+- healthcheck PostgreSQL minimal ;
+- inspection du schema courant ;
+- stratégie de migrations documentée et scaffoldée ;
+- tests offline pour masquage DSN, assemblage de configuration, noms de migrations et diagnostics ;
+- README `kb_store_pg` mis à jour ;
+- prompt de suite pour `0.2.3` raw store minimal.
+
+## Hors périmètre de `0.2.2`
+
+- tables raw concrètes ;
+- tables core concrètes ;
+- repositories SQL complets ;
+- fenêtre Tauri DB ;
+- tests d'intégration nécessitant un serveur PostgreSQL local obligatoire.
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_core
+cargo test -p kb_store_pg
+cargo test -p kb_config
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+```
+
+Si un serveur PostgreSQL local est disponible, ajouter une validation optionnelle documentée séparément, sans rendre le test obligatoire pour le jalon.
+

migration/khadhroony-bot2-reference/prompts/011_v0_2_3_raw_store_minimal.md

@@ -0,0 +1,167 @@
+<!-- file: prompts/011_v0_2_3_raw_store_minimal.md -->
+<!-- version: 1 -->
+
+# Prompt `0.2.3` — raw store Solana minimal
+
+Objectif : ouvrir `0.2.3` après validation locale de `0.2.2`, en créant uniquement les premières tables raw PostgreSQL et leurs repositories minimaux.
+
+## Base attendue
+
+- `0.2.0` validée : conventions PostgreSQL et noms `kb_sol_<domain>_<name>`.
+- `0.2.1` validée : contrats `kb_store_core`, raw lifecycle, replay instruction-level et contexte extrait.
+- `0.2.2` validée : `PostgresStore`, pool PostgreSQL, healthcheck, schéma courant, DSN masqué et stratégie migrations non destructive.
+- `CHANGELOG.md` ne doit être modifié qu'après validation locale du jalon.
+
+## Objectif strict
+
+Créer le raw store minimal :
+
+```text
+kb_sol_raw_rpc_transactions
+kb_sol_raw_ws_notifications
+```
+
+Ne pas créer les tables `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet` dans ce jalon.
+
+## Convention PostgreSQL obligatoire
+
+- Ne pas créer de schémas applicatifs PostgreSQL.
+- Utiliser le schéma courant/default du profil, généralement `public`.
+- Créer des tables non qualifiées.
+- Ne jamais utiliser `raw DOT ...`, `core DOT ...`, etc.
+
+## Table `kb_sol_raw_rpc_transactions`
+
+Objectif : stocker le résultat brut canonique des appels RPC transaction par signature.
+
+Champs candidats :
+
+```text
+id
+signature
+slot
+provider
+endpoint_name
+rpc_method
+commitment
+encoding
+raw_json
+raw_json_hash
+retention_state
+processing_state
+linked_core_transaction_id
+created_at
+updated_at
+```
+
+Contraintes minimales :
+
+- `signature` non vide ;
+- `slot` en `BIGINT` ;
+- `raw_json` en `JSONB`, nullable uniquement si la ligne est compactée ou purgée ;
+- `retention_state` et `processing_state` en texte contrôlé côté Rust au départ ;
+- unique index sur `signature` pour la transaction canonique.
+
+Index minimaux :
+
+```text
+signature
+slot
+provider
+endpoint_name
+created_at
+processing_state
+retention_state
+```
+
+## Table `kb_sol_raw_ws_notifications`
+
+Objectif : stocker les notifications WebSocket brutes utiles, dédupliquées par clé stable.
+
+Champs candidats :
+
+```text
+id
+notification_key
+subscription_kind
+provider
+endpoint_name
+slot
+signature
+program_id
+account_key
+raw_json
+raw_json_hash
+retention_state
+processing_state
+linked_raw_rpc_transaction_id
+created_at
+updated_at
+```
+
+Contraintes minimales :
+
+- `notification_key` non vide ;
+- `signature` optionnelle ;
+- `program_id` optionnel ;
+- `account_key` optionnel ;
+- `slot` optionnel au départ selon type de notification ;
+- `raw_json` en `JSONB`, nullable uniquement si la ligne est compactée ou purgée ;
+- unique index sur `notification_key`.
+
+Index minimaux :
+
+```text
+notification_key
+signature
+slot
+program_id
+account_key
+provider
+endpoint_name
+created_at
+processing_state
+retention_state
+```
+
+## Repositories attendus
+
+Implémenter dans `kb_store_pg` les méthodes de `RawTransactionStore` :
+
+```text
+has_raw_rpc_signature
+has_raw_ws_notification_key
+insert_raw_rpc_transaction
+insert_raw_ws_notification
+mark_raw_payload_lifecycle
+```
+
+Les queries doivent rester dans `kb_store_pg/src/queries/`.
+
+Les implémentations repositories doivent rester dans `kb_store_pg/src/repositories/`.
+
+Ne pas créer de struct métier ou DB dans `queries/`.
+
+## Politique de rétention
+
+Prévoir sans activer agressivement :
+
+- `Full` : raw JSON conservé ;
+- `Compacted` : raw JSON supprimable après hash et extraction core ;
+- `Archived` : raw déplacé hors hot store plus tard ;
+- `Purged` : raw supprimé, hash et lifecycle conservés.
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_pg
+cargo test -p kb_store_core
+cargo clippy --all-targets
+```
+
+Si PostgreSQL local est disponible, ajouter une validation manuelle optionnelle :
+
+```bash
+# créer une base de test dédiée puis lancer les migrations raw
+# vérifier \dt kb_sol_raw_*
+```

migration/khadhroony-bot2-reference/prompts/012_v0_2_4_core_store_minimal.md

@@ -0,0 +1,92 @@
+<!-- file: prompts/012_v0_2_4_core_store_minimal.md -->
+<!-- version: 1 -->
+
+# Prompt de session — `0.2.4` core Solana normalisé minimal
+
+Objectif : ouvrir `0.2.4` après validation et commit de `0.2.3`.
+
+## État de départ attendu
+
+- `0.2.0` validée : conventions PostgreSQL et nommage `kb_sol_<domain>_<name>`.
+- `0.2.1` validée : contrats `kb_store_core`, DTOs/entities/repositories et replay instruction-level contextualisé.
+- `0.2.2` validée : infrastructure PostgreSQL minimale, pool, healthcheck et diagnostics.
+- `0.2.3` validée : raw store minimal PostgreSQL avec :
+  - `kb_sol_raw_rpc_transactions` ;
+  - `kb_sol_raw_ws_notifications` ;
+  - repositories raw PostgreSQL ;
+  - initialisation idempotente du schéma raw.
+
+## Objectif de `0.2.4`
+
+Créer le store `core` minimal permettant d'extraire les composants Solana normalisés depuis le raw sans encore développer le pipeline complet d'extraction.
+
+## Tables candidates
+
+Créer uniquement les tables nécessaires au core minimal :
+
+```text
+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
+```
+
+Ne pas encore créer les tables `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`, sauf nécessité explicitement justifiée.
+
+## Principes obligatoires
+
+- Le replay doit sélectionner des instructions normalisées, pas des transactions entières.
+- Les décodeurs doivent recevoir une instruction avec contexte : account keys, inner instructions, logs et balance changes.
+- Les tables core doivent référencer la signature et le slot.
+- Les instructions doivent avoir un `instruction_path` stable.
+- Les inner instructions doivent conserver leur relation parent/enfant.
+- Les logs doivent conserver l'ordre original.
+- Les balance changes doivent rester suffisamment génériques pour native lamports et SPL tokens.
+- Les états de traitement instruction-level doivent permettre : pending, decoded, materialized, ignored, failed, replay_requested.
+
+## Hors périmètre
+
+- Ne pas décoder les protocoles DEX.
+- Ne pas matérialiser les trades ou liquidités.
+- Ne pas supprimer physiquement le raw.
+- Ne pas créer de fenêtre Tauri DB.
+- Ne pas créer de grand schéma monolithique.
+
+## Contraintes Rust
+
+- Rust 2024.
+- `#![warn(missing_docs)]`.
+- `#![deny(unreachable_pub)]`.
+- `#![forbid(unsafe_code)]`.
+- Pas de `use` sauf traits.
+- `crate::` en interne.
+- Pas de `?` en production.
+- Pas de `unwrap`.
+- Pas de `expect`.
+- Pas de `anyhow`.
+- Pas de `thiserror`.
+- Erreurs via `kb_core::Error` et `kb_core::Result`.
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_pg
+cargo test -p kb_store_core
+cargo test -p kb_config
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+```
+
+Test PostgreSQL optionnel à prévoir si une base locale existe :
+
+```bash
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana' cargo test -p kb_store_pg optional_postgres_core_store_roundtrip_from_env -- --nocapture
+```
+
+## Livraison
+
+- Fournir un zip delta uniquement.
+- Ne pas modifier `CHANGELOG.md` avant validation locale.
+- Inclure `delta.md` non versionné dans le zip.

migration/khadhroony-bot2-reference/prompts/013_v0_2_5_db_diagnostics_tauri.md

@@ -0,0 +1,50 @@
+<!-- file: prompts/013_v0_2_5_db_diagnostics_tauri.md -->
+<!-- version: 1 -->
+
+# Prompt `0.2.5` — diagnostic DB Tauri
+
+Objectif : ouvrir `0.2.5` après validation et commit de `0.2.4`, en ajoutant une fenêtre Tauri de diagnostic PostgreSQL sans modifier le schéma métier.
+
+## État attendu
+
+- `0.2.0` validée : conventions SQL et noms `kb_sol_<domain>_<name>`.
+- `0.2.1` validée : contrats `kb_store_core`, replay instruction-level contextualisé.
+- `0.2.2` validée : infrastructure PostgreSQL minimale, pool et healthcheck.
+- `0.2.3` validée : raw store minimal.
+- `0.2.4` validée : core store minimal avec transactions, account keys, instructions, inner instructions, logs et balance changes.
+
+## Objectif de `0.2.5`
+
+Ajouter une fenêtre `demo_db` ou `diagnostic_db` dans `kb_app_demo` affichant :
+
+- profil actif ;
+- backend DB actif ;
+- DSN masqué ;
+- schema courant PostgreSQL ;
+- version PostgreSQL ;
+- healthcheck ;
+- statut migrations ;
+- tables `kb_sol_*` détectées ;
+- présence des tables raw/core attendues ;
+- compte rapide optionnel des tables raw/core si cela reste léger.
+
+## Contraintes
+
+- Ne pas créer de nouvelles tables métier.
+- Ne pas exposer le mot de passe PostgreSQL côté UI.
+- Utiliser `kb_store_pg::PostgresStoreOptions::from_active_app_config`.
+- Garder les commandes Tauri typées et exportées TS-rs.
+- Garder les tests offline autant que possible.
+- Prévoir un test PostgreSQL optionnel via `KB_POSTGRES_TEST_URL` seulement si nécessaire.
+
+## Validations attendues
+
+```bash
+cargo test -p kb_store_pg
+cargo test -p kb_store_core
+cargo test -p kb_config
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+

migration/khadhroony-bot2-reference/prompts/014_v0_3_0_agave_local_research.md

@@ -0,0 +1,210 @@
+<!-- file: prompts/014_v0_3_0_agave_local_research.md -->
+<!-- version: 3 -->
+
+# Prompt historique v0.3.0 — expérimentation Agave local et sources temps réel
+
+Ce prompt correspond au jalon historique `0.3.0`, validé puis abandonné comme axe actif après les mesures matérielles. Il ne doit plus être utilisé pour ouvrir une nouvelle session.
+
+Objectif historique : ouvrir la nouvelle phase `0.3.x` de `khadhroony-bot2` en testant un nœud Agave local non votant comme source temps réel potentielle avant de développer l'ingestion, le backfill et l'extracteur raw vers core.
+
+## État de départ attendu
+
+- `0.2.5` validée : diagnostics SQL PostgreSQL dans `kb_app_demo`.
+- Tables raw/core PostgreSQL minimales disponibles.
+- `demo_ws` existe déjà et peut servir de base pour tester les subscriptions.
+- Le profil `agave_local_research` existe dans `config/example.config.json` mais n'est pas actif par défaut.
+- L'ancien périmètre ingestion/backfill/extraction est reporté à `0.4.x`.
+
+## Objectif de `0.3.0`
+
+`0.3.0` ne doit pas lancer l'ingestion de production.
+
+Le jalon doit préparer l'expérimentation :
+
+- documentation Agave local ;
+- profil dédié ;
+- correction des rôles de listeners du profil Agave local ;
+- stratégie des sources temps réel ;
+- probes à ajouter dans `demo_ws` ou dans une nouvelle démo dédiée ;
+- mesures à collecter ;
+- règles de fallback ;
+- critères de décision pour `0.4.x`.
+
+## Hypothèse à tester
+
+Un nœud local Agave non votant, avec ledger limité par shreds, pourrait permettre :
+
+- `blockSubscribe` local avec transactions complètes ;
+- moins de `getTransaction` temps réel ;
+- moins de listeners par programme ;
+- filtrage local par program id, logs, instructions, balances et discriminators ;
+- usage des providers externes surtout pour backfill historique, réparation et `sendTransaction`.
+
+Cette hypothèse doit être mesurée, pas supposée vraie.
+
+## Commande de départ à documenter/tester
+
+```bash
+agave-validator \
+  --no-voting \
+  --full-rpc-api \
+  --enable-rpc-transaction-history \
+  --rpc-pubsub-enable-block-subscription \
+  --limit-ledger-size <N_SHREDS> \
+  --ledger ./data/agave-ledger \
+  --accounts ./data/agave-accounts \
+  --rpc-port 8899 \
+  --dynamic-port-range 8000-8020
+```
+
+La commande peut être ajustée selon la version Agave installée. Ne pas masquer les échecs : documenter les erreurs de snapshots, ledger, ports, ressources et retard.
+
+## Probes attendus
+
+`0.3.0` doit documenter ces probes. L'implémentation automatique peut commencer en `0.3.2`.
+
+Tester au minimum :
+
+```text
+getVersion
+getHealth
+getSlot
+getBlockHeight
+getMaxShredInsertSlot
+blockSubscribe transactionDetails=none
+slotSubscribe
+slotsUpdatesSubscribe
+rootSubscribe
+logsSubscribe mentions
+programSubscribe
+accountSubscribe
+```
+
+Pour `blockSubscribe`, le probe minimal doit :
+
+```text
+subscribe avec transactionDetails=none
+attendre subscription id ou erreur
+désabonner immédiatement
+classer supported / unsupported / timeout / error
+```
+
+Paramètres manuels de départ dans `demo_ws` :
+
+```text
+role: block_stream
+method: blockSubscribe
+filterJson: "all"
+configJson: {"commitment":"confirmed","encoding":"json","transactionDetails":"none","showRewards":false}
+```
+
+## Mesures attendues
+
+- taille ledger ;
+- taille accounts ;
+- CPU ;
+- RAM ;
+- réseau RX/TX ;
+- slot local ;
+- slot externe de référence ;
+- lag slots ;
+- lag secondes ;
+- débit WebSocket ;
+- taille moyenne des notifications ;
+- reconnects ;
+- erreurs provider ou Agave.
+
+## Phasage recommandé
+
+### `0.3.0`
+
+- docs Agave local ;
+- profil `agave_local_research` ;
+- stratégie live source ;
+- prompt et roadmap mis à jour.
+
+### `0.3.1`
+
+- script ou runbook de lancement Agave local ;
+- mesures initiales ledger/shreds/ressources.
+
+### `0.3.2`
+
+- probes RPC/WS dans `demo_ws` ou nouvelle démo.
+
+### `0.3.3`
+
+- mesures de retard et stabilité avec plusieurs valeurs `--limit-ledger-size`.
+
+### `0.3.4`
+
+- test `blockSubscribe` complet : `none`, `signatures`, `full`.
+
+### `0.3.5`
+
+- test listeners multiples : logs/program/account/slot/root.
+
+### `0.3.6`
+
+- décision d'architecture live source et préparation `0.4.x`.
+
+## Hors périmètre strict
+
+- pas d'ingestion de production ;
+- pas d'extracteur raw RPC vers core ;
+- pas de décodage DEX ;
+- pas de matérialisation ;
+- pas de backfill historique ;
+- pas d'achat/revente ;
+- pas de dépendance obligatoire à Agave local.
+
+## Fichiers à lire/modifier en priorité
+
+- `ROADMAP.md`
+- `config/example.config.json`
+- `config/README.md`
+- `docs/AGAVE_LOCAL_NODE.md`
+- `docs/LIVE_SOURCE_STRATEGY.md`
+- `docs/WS_LISTENERS.md`
+- `docs/RPC_ENDPOINT_ROLES.md`
+- `kb_app_demo/src/demo_ws.rs`
+- `kb_app_demo/frontend/demo_ws.html`
+- `kb_app_demo/frontend/ts/demo_ws.ts`
+- `kb_rpc/` si des probes doivent être factorisés côté RPC.
+
+Pour `0.3.0`, privilégier les documents et la configuration. Ne modifier `demo_ws` ou `kb_rpc` que si le delta reste strictement préparatoire et sans ingestion.
+
+## Contraintes
+
+- Conserver Rust 2024.
+- Conserver `#![warn(missing_docs)]`, `#![deny(unreachable_pub)]`, `#![forbid(unsafe_code)]`.
+- Pas de `unwrap`, `expect`, `anyhow`, `thiserror`.
+- Pas de `?` en production.
+- Pas de `use` sauf traits.
+- `crate::` en interne.
+- Documentation Rust/TypeScript/SQL en anglais.
+- Markdown projet en français.
+- Ne pas modifier `CHANGELOG.md` avant validation locale du jalon.
+
+## Format de livraison attendu
+
+- Fournir un zip delta uniquement.
+- Utiliser `khadhroony-bot2_v0.3.0-pre.abc.zip` si plusieurs modules ou la racine sont touchés.
+- Utiliser `kb_rpc_v0.3.0-pre.abc.zip` ou `kb_app_demo_v0.3.0-pre.abc.zip` si un seul module est touché.
+- Inclure `delta.md` non versionné dans le zip.
+- Documenter les validations exécutées et celles non exécutées.
+
+## Validations attendues
+
+Selon le delta :
+
+```bash
+cargo test -p kb_config
+cargo test -p kb_rpc
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Les tests Agave réels peuvent rester manuels au début, mais les probes doivent reporter clairement les erreurs et timeouts.
+

migration/khadhroony-bot2-reference/prompts/015_v0_3_1_canonical_store_migration.md

@@ -0,0 +1,48 @@
+<!-- file: prompts/015_v0_3_1_canonical_store_migration.md -->
+<!-- version: 2 -->
+
+# Prompt historique v0.3.1 — transaction canonique et observations
+
+Ce prompt décrit le jalon `0.3.1` désormais validé. Il est conservé pour expliquer la transition, mais ne doit plus être utilisé comme prompt actif.
+
+## Résultat validé
+
+Le stockage actif repose sur :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+kb_sol_core_transactions.raw_transaction_id
+```
+
+La transaction canonique contient le document rejouable source-indépendant. Les observations contiennent uniquement les informations de provenance, protocole, méthode, session, filtre, timestamps, taille, statut et erreur. Aucun payload complet WebSocket ou Protobuf n’est dupliqué dans les observations.
+
+## Transition historique
+
+La base PostgreSQL `0.2.x` a été convertie et contrôlée manuellement :
+
+- les anciennes tables RPC/WS sont absentes ;
+- les tables canoniques sont présentes ;
+- les colonnes `canonical_json`, `canonical_json_hash`, `canonical_format_version` et `raw_transaction_id` sont présentes ;
+- les fixtures de test ont été nettoyées après validation.
+
+Après ce contrôle, le dossier `kb_store_pg/migrations/` a été consolidé en :
+
+```text
+0001_canonical_transaction_store.sql
+0002_core_store.sql
+```
+
+Les fichiers SQL actifs ne contiennent plus les anciennes définitions. Le DDL runtime conserve temporairement un chemin de compatibilité idempotent pour les workspaces encore issus de `pre.001`. L’historique reste dans `CHANGELOG.md` et la documentation.
+
+## Validations réalisées
+
+```text
+cargo test -p kb_app_demo                                      32 tests
+cargo test -p kb_store_core                                    30 tests
+KB_POSTGRES_TEST_URL=... cargo test -p kb_store_pg -- --nocapture 32 tests
+cargo clippy --all-targets                                     OK
+cargo tauri dev -c kb_app_demo/tauri.conf.json                 OK
+```
+
+Le prompt actif suivant est `016_v0_3_2_canonical_transaction_contract.md`.

migration/khadhroony-bot2-reference/prompts/016_v0_3_2_canonical_transaction_contract.md

@@ -0,0 +1,112 @@
+<!-- file: prompts/016_v0_3_2_canonical_transaction_contract.md -->
+<!-- version: 2 -->
+
+# Prompt v0.3.2 — contrat de transaction canonique et adaptateur HTTP
+
+## Contexte validé
+
+`0.3.1` a remplacé les responsabilités historiques RPC/WS par :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+RawTransactionInsert
+TransactionObservationInsert
+```
+
+Les observations ne contiennent aucun payload transactionnel complet. Les détails de fournisseur restent hors de la transaction canonique. La baseline SQL active est consolidée dans `0001_canonical_transaction_store.sql` et `0002_core_store.sql`; ne pas réintroduire les anciennes tables RPC/WS ni une logique de migration historique dans le DDL runtime.
+
+## Objectif
+
+Définir dans `kb_model` la représentation canonique complète d’une transaction Solana, puis ajouter dans `kb_rpc` l’adaptateur HTTP `getTransaction` qui produit exactement cette représentation.
+
+## Contrat canonique
+
+Couvrir au minimum :
+
+- transaction legacy et version 0 ;
+- signatures ;
+- message header ;
+- static account keys ;
+- address table lookups ;
+- loaded writable et readonly addresses ;
+- recent blockhash ;
+- instructions externes ;
+- inner instructions ;
+- logs ;
+- statut et erreur ;
+- fee et compute units ;
+- balances SOL pré/post ;
+- balances SPL pré/post ;
+- rewards ;
+- return data ;
+- block time quand disponible.
+
+Les signatures et public keys restent en base58. Les payloads binaires d’instruction restent en base64. Les nombres on-chain doivent être conservés sans perte.
+
+## Sérialisation et hash
+
+- définir `canonical_format_version = 1` ;
+- garantir une sérialisation déterministe ;
+- calculer `canonical_json_hash` sur la représentation canonique ;
+- exclure du hash tout champ de fournisseur, endpoint, timestamp local ou protocole de transport ;
+- tester qu’une même transaction représentée par deux fixtures compatibles produit le même hash.
+
+## Adaptateur HTTP dans `kb_rpc`
+
+Ajouter la conversion explicite :
+
+```text
+getTransaction JSON-RPC
+  -> validation de la réponse
+  -> modèle canonique kb_model
+  -> RawTransactionInsert
+  -> TransactionObservationInsert
+```
+
+Ne pas créer de crate séparée. Les futurs adaptateurs Helius `transactionSubscribe` et Yellowstone gRPC resteront des modules internes de `kb_rpc` et devront cibler le même modèle.
+
+## Fixtures offline
+
+Ajouter des fixtures pour :
+
+- legacy succès ;
+- legacy échec ;
+- version 0 avec ALT ;
+- CPI et inner instructions ;
+- SPL Token ;
+- Token-2022 ;
+- transaction avec return data ;
+- transaction sans block time ;
+- champs optionnels absents.
+
+## Fichiers à lire en priorité
+
+- `kb_model/` ;
+- `kb_rpc/` ;
+- `kb_store_core/src/dtos/raw_dtos.rs` ;
+- `kb_store_pg/src/queries/raw_queries.rs` ;
+- `docs/TRANSACTION_ACQUISITION_MODEL.md` ;
+- `docs/RAW_STORE.md` ;
+- `ROADMAP.md`.
+
+## Hors périmètre
+
+- pas de modification du schéma PostgreSQL `0.3.1` ;
+- pas de compte Helius Developer ;
+- pas de Yellowstone gRPC réel ;
+- pas de backfill paginé ;
+- pas d’extraction vers les tables core ;
+- pas de décodeur protocolaire.
+
+## Validation attendue
+
+```bash
+cargo test -p kb_model
+cargo test -p kb_rpc
+cargo test -p kb_store_core
+cargo test -p kb_store_pg
+cargo clippy --all-targets
+```
+
+Vérifier également l’absence de tout nom de provider dans le JSON canonique et la stabilité du hash entre fixtures équivalentes.

migration/khadhroony-bot2-reference/prompts/017_v0_3_3_http_backfill_free_tier.md

@@ -0,0 +1,186 @@
+<!-- file: prompts/017_v0_3_3_http_backfill_free_tier.md -->
+<!-- version: 6 -->
+
+# Prompt historique v0.3.3 — backfill HTTP paginé sur comptes gratuits
+
+## État final validé
+
+Ce prompt est conservé comme historique. Le jalon `0.3.3` est clôturé avec `demo_backfill`, la pagination `before` / `until`, la sélection directe des signatures postérieures à l’ancre, la persistance canonique et l’arrêt coopératif borné.
+
+Validations finales :
+
+```text
+cargo test -p kb_rpc: 54 tests passés
+cargo test -p kb_pipeline: 10 tests passés
+cargo test -p kb_store_core: 31 tests passés
+cargo test -p kb_store_pg: 32 tests passés
+cargo test -p kb_app_demo: 38 tests passés
+cargo clippy --all-targets: validé
+```
+
+## Contexte validé attendu
+
+`0.3.2` est validée et clôturée. La baseline confirmée fournit :
+
+```text
+kb_model::CanonicalTransaction
+kb_rpc::GetTransactionConfig
+kb_rpc::GetTransactionAdapter
+kb_rpc::CanonicalTransactionAdapter
+kb_store_core::RawTransactionInsert::from_canonical
+```
+
+Validations de référence :
+
+```text
+cargo test -p kb_model: 23 tests passés
+cargo test -p kb_rpc: 48 tests passés
+cargo test -p kb_store_core: 31 tests passés
+cargo test -p kb_store_pg avec PostgreSQL réel: 32 tests passés
+cargo clippy --all-targets: validé
+```
+
+Le store actif reste :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+```
+
+Ne pas modifier le schéma PostgreSQL `0.3.1` sans nécessité démontrée.
+
+## Objectif
+
+Ajouter un backfill HTTP réutilisable avec les comptes gratuits des fournisseurs RPC :
+
+```text
+getSignaturesForAddress paginé
+  -> signatures candidates
+  -> getTransaction
+  -> CanonicalTransaction
+  -> RawTransactionInsert
+  -> TransactionObservationInsert
+```
+
+## Périmètre fonctionnel
+
+- pagination `getSignaturesForAddress` avec `before`, `until`, limite et ordre explicite ;
+- le mode `after` doit transmettre l’ancre via `until`, paginer avec `before` et utiliser des pages de 1000 signatures ;
+- le mode `after` ne doit pas rechercher manuellement l’ancre depuis la tête sans borne RPC ;
+- ne conserver que les `X` signatures plus récentes les plus proches de l’ancre ;
+- backfill d’une signature explicite ;
+- backfill d’un groupe de signatures ;
+- backfill avant/après une signature d’ancrage pour un program id ;
+- backfill avant/après une signature d’ancrage pour un mint de token ;
+- backfill avant/après une signature d’ancrage pour une adresse de pool ;
+- reprise après interruption avec curseur persistant ou exportable ;
+- sélection d’endpoint via les pools et rôles existants ;
+- rate limits, concurrency, timeout, retries et pause après 429 depuis `kb_config` ;
+- idempotence par signature dans `kb_sol_raw_transactions` ;
+- une observation par tentative et par source ;
+- conservation des statuts `missing` et `failed` sans créer de transaction canonique vide ;
+- arrêt propre et résumé de campagne ;
+- file d’exécution bornée : ne jamais instancier une future par candidat sélectionné ;
+- compteurs distincts pour candidats sélectionnés, démarrés, terminés, annulés et non démarrés ;
+- curseur de reprise calculé depuis le dernier préfixe contigu réellement terminé.
+
+## Observations HTTP
+
+Chaque tentative doit produire une observation légère avec au minimum :
+
+```text
+provider
+endpoint_code
+protocol = solana_http_json_rpc
+acquisition_method = getTransaction
+origin = backfill
+commitment
+capture_session_id
+received_at
+normalized_at
+payload_size_bytes si disponible
+source_payload_hash si disponible
+status
+error_code
+error_message
+```
+
+Le payload HTTP complet ne doit pas être dupliqué dans la table d’observations.
+
+## UI et orchestration
+
+Ajouter une page Tauri de démonstration permettant :
+
+- une liste de signatures dans un textarea, séparées par des retours à la ligne ;
+- un program id avec limite, direction `before`/`after` et signature d’ancrage ;
+- un mint de token avec limite, direction `before`/`after` et signature d’ancrage ;
+- une adresse de pool avec limite, direction `before`/`after` et signature d’ancrage ;
+- les paramètres communs de rôle, commitment, page size, max pages, concurrence et retries ;
+- le suivi des compteurs reçus, normalisés, persistés, ignorés, manquants et échoués ;
+- un journal UI borné et un résumé JSON ;
+- l’arrêt explicite et coopératif de la campagne ;
+- un regroupement des sections dans des accordéons Bootstrap 5 en réutilisant le template global.
+
+La page ne doit pas contenir la logique de backfill profonde : elle appelle les APIs de `kb_pipeline`.
+
+## Corpus initial
+
+Préparer les premiers corpus dans cet ordre :
+
+1. Solana Core et SPL ;
+2. Pump Fun, Pump Swap et Pump Fees ;
+3. Meteora ;
+4. Raydium ;
+5. Orca.
+
+Jupiter peut apparaître dans les transactions routées, mais aucun flux temps réel payant n’est introduit dans cette tranche.
+
+## Hors périmètre
+
+- Helius Developer ;
+- `transactionSubscribe` ;
+- Yellowstone gRPC ;
+- `logsSubscribe("all")` ;
+- extraction vers les tables core ;
+- décodeurs protocolaires ;
+- matérialisation ;
+- trading.
+
+## Fichiers à lire en priorité
+
+- `kb_rpc/src/get_transaction.rs` ;
+- `kb_rpc/src/http_pool.rs` ;
+- `kb_pipeline/` ;
+- `kb_store_core/src/dtos/raw_dtos.rs` ;
+- `kb_store_core/src/repositories/` ;
+- `kb_store_pg/src/repositories/` ;
+- `kb_app_demo/src/` ;
+- `kb_app_demo/frontend/ts/` ;
+- `docs/TRANSACTION_ACQUISITION_MODEL.md` ;
+- `docs/RAW_STORE.md` ;
+- `docs/BACKFILL_HTTP.md` ;
+- `ROADMAP.md`.
+
+## Validation attendue
+
+```bash
+cargo test -p kb_rpc
+cargo test -p kb_pipeline
+cargo test -p kb_store_core
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' cargo test -p kb_store_pg -- --nocapture
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Utiliser de préférence une base PostgreSQL dédiée aux tests. Si la base de développement est utilisée volontairement, identifier puis supprimer explicitement les fixtures de roundtrip après la campagne. Aucun test ne doit effacer des données non créées par sa propre exécution.
+
+## Livraison
+
+Produire un zip delta :
+
+```text
+khadhroony-bot2_v0.3.3-pre.004.zip
+```
+
+Le delta doit contenir `delta.md`, les fichiers ajoutés ou modifiés et la liste explicite des éventuelles suppressions manuelles. Ne pas modifier `CHANGELOG.md` avant validation complète de la tranche.

migration/khadhroony-bot2-reference/prompts/018_v0_3_4_canonical_to_core_extraction.md

@@ -0,0 +1,335 @@
+<!-- file: prompts/018_v0_3_4_canonical_to_core_extraction.md -->
+<!-- version: 5 -->
+
+# Prompt v0.3.4 — extraction transaction canonique vers core
+
+## Statut
+
+Jalon validé et clôturé le 7 juillet 2026. Ce prompt est conservé comme contrat historique ; ne plus l’utiliser comme prompt actif.
+
+Résultats finaux : `kb_pipeline` 24 tests, `kb_store_pg` 39 tests avec rollback PostgreSQL réel, `kb_app_demo` 60 tests, `kb_program_ids` 2 tests, Clippy sans avertissement, 70 transactions core et 84 tentatives ledger après force replay.
+
+## État de clôture
+
+Le périmètre fonctionnel a été livré jusqu’à `0.3.4-pre.011`, puis validé localement. Les contrôles couvrent 70 transactions core, les requêtes d’intégrité, l’écriture CSV native, le skip et le force replay sur 14 signatures, le rollback PostgreSQL intermédiaire et l’annulation des futures RPC, du pacer et des pauses de retry/429.
+
+L’ancien jalon `0.3.5` est absorbé dans `0.3.4`. `CHANGELOG.md` et `ROADMAP.md` enregistrent la clôture de `0.3.x`; la suite active est directement `0.4.0`.
+
+## Contexte validé attendu
+
+`0.3.3` est validée et clôturée. La baseline fournit :
+
+```text
+kb_model::CanonicalTransaction
+kb_rpc::getTransaction
+kb_pipeline::backfill
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+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
+```
+
+Validations de référence :
+
+```text
+cargo test -p kb_rpc: 54 tests passés
+cargo test -p kb_pipeline: 10 tests passés
+cargo test -p kb_store_core: 31 tests passés
+cargo test -p kb_store_pg: 32 tests passés
+cargo test -p kb_app_demo: 38 tests passés
+cargo clippy --all-targets: validé
+```
+
+Les backfills réels ont produit des transactions canoniques et des observations PostgreSQL. Les tables core sont encore vides par conception.
+
+## Objectif
+
+Ajouter un extracteur réutilisable et versionné :
+
+```text
+kb_sol_raw_transactions.canonical_json
+  -> kb_model::CanonicalTransaction
+    -> validation
+      -> extraction transactionnelle
+        -> 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
+```
+
+L’extracteur prépare les futurs décodeurs sans effectuer de décodage protocolaire ni de matérialisation métier.
+
+## Périmètre fonctionnel
+
+### Lecture et sélection
+
+- ajouter les contrats backend-agnostiques nécessaires dans `kb_store_core` ;
+- lire les transactions canoniques par signature, plage de slots, état de traitement ou lot borné ;
+- ne jamais relire le payload fournisseur depuis les observations ;
+- refuser un `canonical_json` absent, invalide ou incompatible avec `canonical_format_version` ;
+- conserver une erreur explicite et rejouable pour chaque échec d’extraction.
+
+### Extraction transactionnelle
+
+- traiter une transaction canonique dans une transaction PostgreSQL unique ;
+- ne laisser aucune ligne core partielle en cas d’échec ;
+- relier `kb_sol_core_transactions.raw_transaction_id` à la ligne canonique ;
+- rendre l’extraction idempotente par signature, index stable et instruction path ;
+- permettre un replay forcé d’une signature en supprimant puis recréant ses lignes filles dans la même transaction, sans toucher aux autres signatures ;
+- ne marquer le traitement comme réussi qu’après commit PostgreSQL.
+
+### Account keys
+
+Construire un espace d’index canonique unique dans cet ordre :
+
+```text
+static account keys
+loaded writable addresses
+loaded readonly addresses
+```
+
+Pour chaque compte, extraire :
+
+- `account_index` stable ;
+- public key ;
+- source `static`, `loaded_writable` ou `loaded_readonly` ;
+- signer ;
+- writable ;
+- executable uniquement lorsque l’information est réellement disponible, sinon `NULL`.
+
+Les flags des comptes statiques doivent être calculés strictement depuis le message header Solana. Les loaded writable ne sont pas signers ; les loaded readonly ne sont ni signers ni writable.
+
+### Instructions
+
+- résoudre `program_id_index` dans l’espace complet des comptes ;
+- résoudre chaque index de compte de l’instruction vers sa public key ;
+- conserver dans `accounts_json` au minimum les indices et les clés résolues dans l’ordre original ;
+- conserver le payload canonique base64 dans une forme JSON stable ;
+- produire des chemins top-level `0`, `1`, `2`, etc. ;
+- produire des chemins inner `0/0`, `0/1`, `2/0`, etc. ;
+- rattacher chaque inner instruction au chemin top-level parent ;
+- refuser les indices hors limites au lieu de produire un programme ou un compte vide.
+
+### Logs
+
+- conserver l’ordre global via `log_index` ;
+- conserver le texte original et un hash stable ;
+- ne rattacher `program_id` ou `instruction_path` que lorsque la pile d’invocation est reconstruite sans ambiguïté ;
+- laisser ces champs à `NULL` lorsque le lien n’est pas fiable ;
+- tester les séquences `invoke`, `success` et `failed` avec profondeur CPI.
+
+### Balances
+
+- extraire les changements natifs en lamports avec précision entière ;
+- extraire les changements SPL/Token-2022 sans utiliser les valeurs UI comme source de vérité ;
+- conserver pre, post et delta dans des JSON numériques déterministes ;
+- conserver `account_index`, `account_key`, `mint` et `owner` lorsque disponibles ;
+- gérer les comptes présents uniquement avant ou uniquement après la transaction ;
+- garantir un `balance_change_index` déterministe.
+
+### Ledger de traitement
+
+Ajouter `kb_sol_ops_processing_ledger` et son implémentation PostgreSQL avec au minimum :
+
+```text
+stage
+processor_name
+processor_version
+input_key
+input_hash
+status
+attempt_count
+started_at
+finished_at
+error_code
+error_message
+created_at
+updated_at
+```
+
+Pour l’extracteur :
+
+```text
+stage = core_extraction
+processor_name = canonical_to_core
+input_key = signature
+input_hash = canonical_json_hash
+```
+
+Le ledger doit permettre :
+
+- skip d’une extraction déjà réussie avec même version et même hash ;
+- replay après changement de version ou de hash ;
+- retry explicite des statuts failed ;
+- diagnostics sans ambiguïté.
+
+Créer une migration active dédiée sans réintroduire les anciennes tables `0.2.x`. Ne pas qualifier les tables par un schéma PostgreSQL applicatif explicite.
+
+## Orchestration `kb_pipeline`
+
+Ajouter un module distinct, par exemple `core_extraction.rs`, exposant :
+
+- extraction d’une signature ;
+- extraction d’un lot borné ;
+- filtre par plage de slots ;
+- filtre par program id lorsque les comptes/instructions core existent déjà ;
+- mode normal et mode force replay ;
+- résumé avec selected, skipped, extracted, failed et cancelled ;
+- arrêt coopératif et concurrence bornée selon les mêmes principes que le backfill.
+
+La logique profonde reste dans `kb_pipeline`; Tauri ne fait qu’appeler cette API.
+
+## Démo Tauri
+
+Ajouter ou étendre une fenêtre de démonstration permettant :
+
+- extraction par liste de signatures ;
+- extraction d’un lot pending ;
+- extraction par plage de slots ;
+- force replay ;
+- version d’extracteur visible ;
+- journal borné ;
+- résumé JSON ;
+- arrêt coopératif ;
+- rafraîchissement des diagnostics raw/core.
+
+Réutiliser le template global et les accordéons Bootstrap 5. Ne pas mélanger la fenêtre avec le décodage DEX.
+
+### Sélecteur SQL de candidats replay
+
+Ajouter une fenêtre read-only distincte `demo_sql_replay_candidates` afin de préparer les corpus sans pgAdmin ou DBeaver :
+
+- tableau des transactions/signatures avec filtres raw, ledger, slots, programme et entité ;
+- tableau agrégé des programmes outer, inner et logs reliés ;
+- tableaux distincts des mints, owners et account keys ;
+- DataTables avec intégration Bootstrap 5, sélection par checkbox et pagination à 10 lignes ;
+- reset des filtres et copie individuelle ou multiligne dans le presse-papiers ;
+- affichage tronqué des identifiants longs avec tooltip et valeur intégrale pour tri, recherche, copie et export ;
+- export CSV diagnostique écrit par Rust dans `data/exports_csv/` ;
+- requêtes PostgreSQL statiques, paramétrées et limitées ;
+- aucune exécution de SQL libre et aucune écriture en base.
+
+La fenêtre doit être accessible depuis le menu principal et depuis `demo_core_extraction`.
+
+## Tests offline obligatoires
+
+Couvrir au minimum :
+
+1. transaction legacy simple ;
+2. transaction v0 avec ALT et loaded addresses ;
+3. transaction échouée avec `err_json` ;
+4. outer instructions multiples ;
+5. inner instructions et CPI imbriqués ;
+6. logs avec invoke/success/failed ;
+7. balances SOL positives, négatives et nulles ;
+8. balances SPL et Token-2022 ;
+9. compte token créé ou fermé pendant la transaction ;
+10. indice de programme hors limites ;
+11. indice de compte hors limites ;
+12. idempotence sur double extraction ;
+13. replay forcé sans doublon ;
+14. rollback complet après erreur intermédiaire ;
+15. changement de version d’extracteur ;
+16. changement de hash canonique ;
+17. arrêt coopératif d’un lot.
+
+Les fixtures ne doivent effectuer aucun appel réseau.
+
+## Hors périmètre
+
+- décodeurs Solana Core/SPL ;
+- décodeurs DEX ;
+- matérialisation métier ;
+- sources Helius `transactionSubscribe` ;
+- Yellowstone gRPC ;
+- Solscan ou `kb_external_sources` ;
+- compaction ou purge du canonical JSON ;
+- trading et wallet.
+
+## Fichiers à lire en priorité
+
+- `kb_model/src/canonical_transaction.rs` ;
+- `kb_pipeline/src/backfill.rs` ;
+- `kb_pipeline/src/lib.rs` ;
+- `kb_store_core/src/dtos/core_dtos.rs` ;
+- `kb_store_core/src/dtos/ledger_dtos.rs` ;
+- `kb_store_core/src/entities/core_entities.rs` ;
+- `kb_store_core/src/entities/ledger_entities.rs` ;
+- `kb_store_core/src/repositories/storage_repositories.rs` ;
+- `kb_store_pg/src/queries/core_queries.rs` ;
+- `kb_store_pg/src/repositories/core_transaction_repository.rs` ;
+- `kb_store_pg/migrations/0002_core_store.sql` ;
+- `docs/CORE_EXTRACTION_CONTRACTS.md` ;
+- `docs/CORE_STORE.md` ;
+- `docs/INSTRUCTION_REPLAY_CONTRACTS.md` ;
+- `ROADMAP.md` ;
+- `RULES.md`.
+
+## 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` et version incrémentée à chaque modification ;
+- aucune ligne vide dans les corps de fonctions ou structures ;
+- une ligne vide finale dans chaque fichier ;
+- TS-rs pour les types exposés à Tauri ;
+- ne pas modifier `CHANGELOG.md` avant validation locale complète.
+
+## Validation attendue
+
+```bash
+cargo test -p kb_model
+cargo test -p kb_store_core
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana' cargo test -p kb_store_pg -- --nocapture
+cargo test -p kb_pipeline
+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
+```
+
+Ajouter des requêtes SQL de contrôle pour vérifier :
+
+- aucune transaction core sans raw lineage lorsque la source raw existe ;
+- aucun compte, instruction, inner instruction, log ou balance change orphelin ;
+- aucune duplication des clés uniques ;
+- égalité entre les comptes résolus et le contrat canonique ;
+- stabilité des instruction paths ;
+- cohérence du ledger avec les lignes core créées.
+
+## Livraison historique
+
+La dernière préversion technique a été livrée sous :
+
+```text
+khadhroony-bot2_v0.3.4-pre.011-delta.zip
+```
+
+Le delta final documentaire enregistre ensuite la version validée dans `CHANGELOG.md` et active `0.4.0`.
+
+## Clôture finale
+
+Les validations finales ont été exécutées avec succès :
+
+```text
+cargo test -p kb_pipeline: 24 passed
+KB_POSTGRES_TEST_URL=... cargo test -p kb_store_pg -- --nocapture: 39 passed
+cargo clippy --all-targets: aucun avertissement
+```
+
+`0.3.4` est reportée dans `CHANGELOG.md`, l’ancien jalon `0.3.5` est absorbé et le prompt actif devient `prompts/019_v0_4_0_decoder_infrastructure.md`.

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

@@ -0,0 +1,288 @@
+<!-- file: prompts/019_v0_4_0_decoder_infrastructure.md -->
+<!-- version: 2 -->
+
+# 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 :
+
+```text
+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 `CoreInstructionReplayInput` 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 :
+
+```text
+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 :
+
+```text
+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 :
+
+```text
+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 :
+
+```text
+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
+
+```bash
+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 :
+
+```text
+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.

migration/khadhroony-bot2-reference/prompts/020_v0_4_1_native_solana_programs.md

@@ -0,0 +1,691 @@
+<!-- file: prompts/020_v0_4_1_native_solana_programs.md -->
+<!-- version: 5 -->
+
+# Prompt de session — `0.4.1` programmes Solana natifs, loaders et précompiles
+
+## 1. Mission
+
+Poursuivre `khadhroony-bot2` depuis la version validée `0.4.0` et réaliser `0.4.1`.
+
+Le but est de transformer le classifieur natif introduit en `0.4.0` en un décodeur maximal, vérifiable et rejouable pour les programmes Solana natifs/runtime, les programmes historiques, les loaders et les précompiles. La version doit décoder toutes les variantes connues et officiellement vérifiables, y compris celles qui ne sont pas directement liées au trading.
+
+Le travail doit rester dans l’architecture existante :
+
+```text
+canonical transaction
+  -> core extraction
+    -> contextual instruction replay
+      -> kb_decoder_solana_core
+        -> decoded native events
+          -> optional generic materialization
+            -> coverage + processing ledger
+```
+
+Ne pas commencer SPL Token, Token-2022, Pump, Meteora, Raydium, Orca, Jupiter, wallet, exécution ou ingestion live dans cette version.
+
+## 2. Base de travail et règle de livraison
+
+La base attendue est la dernière archive complète ou le dernier workspace utilisateur contenant les correctifs validés jusqu’à `0.4.0-pre.011`.
+
+Avant toute modification :
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md` et `CHANGELOG.md` ;
+2. lire `prompts/019_v0_4_0_decoder_infrastructure.md` ;
+3. auditer les crates et fichiers réellement présents ;
+4. vérifier les versions de headers `file:` / `version:` ;
+5. ne pas supposer qu’un fichier ou une API existe sans l’avoir inspecté.
+
+Après l’archive complète initiale, livrer uniquement des ZIP delta. Le delta racine doit suivre une nomenclature du type :
+
+```text
+khadhroony-bot2_v0.4.1-pre.001-delta.zip
+```
+
+Chaque delta doit contenir :
+
+- uniquement les fichiers ajoutés ou modifiés ;
+- `delta.md` non versionné ;
+- `manifest.json` avec chemins, tailles et SHA-256 ;
+- la liste explicite des suppressions manuelles, normalement vide.
+
+Ne fournir une archive complète que sur demande explicite.
+
+## 3. État validé à préserver
+
+`0.4.0` est validée avec :
+
+- `kb_config` : 36 tests ;
+- `kb_pipeline` : 41 tests ;
+- `kb_store_pg` : 44 tests, PostgreSQL réel compris ;
+- `kb_app_demo` : 75 tests ;
+- `cargo clippy --all-targets` propre ;
+- replay contextualisé borné par programmes compatibles ;
+- skip processor/version/hash ;
+- force replay ciblé par signatures ;
+- autorisation explicite « toutes les signatures » avec limite ;
+- matérialisation refusée sans matérialiseur ;
+- persistance atomique ledger/decode/mat/couverture ;
+- `campaign_id` corrélé entre application, pipeline, store et décodeur ;
+- arrêt coopératif avec :
+  - `started + not_started = selected` ;
+  - `completed = started` ;
+- validation réelle finale :
+  - 382 inputs Compute Budget sélectionnés ;
+  - 45 démarrés et terminés ;
+  - 337 non démarrés ;
+  - aucun unmatched ;
+  - aucun échec ;
+  - 45 dispatchs `unsupported` ;
+  - `errors.jsonl` vide ;
+- couverture actuelle :
+  - 18 déclarations natives alors exposées ; `pre.008` a corrigé Stake Config et le registre exécutable en contient désormais 17 ;
+  - 382 observations Compute Budget reconnues ;
+  - 94 observations System reconnues ;
+  - aucun faux événement décodé ou matérialisé.
+
+Ces comportements ne doivent pas régresser.
+
+## 4. Contraintes normatives du workspace
+
+Respecter strictement `RULES.md`, notamment :
+
+- Rust 2024 ;
+- async-first lorsqu’un I/O est impliqué ;
+- `kb_core::Error` et `kb_core::Result` ;
+- pas de `anyhow` ni `thiserror` ;
+- pas de `unwrap`, `expect`, panic volontaire ou `unsafe` en production ;
+- pas d’opérateur `?` dans les commandes Tauri si les règles locales l’interdisent ;
+- retours explicites selon les lints du workspace ;
+- `warn(missing_docs)`, `deny(unreachable_pub)`, `forbid(unsafe)` ;
+- imports uniquement pour les traits lorsque possible ;
+- chemins pleinement qualifiés et `crate::` pour l’intra-crate ;
+- noms de fichiers et dossiers ASCII anglais ;
+- documentation de code en anglais ;
+- Markdown projet en français ;
+- header obligatoire `file:` puis `version:` dans chaque fichier modifié ;
+- incrémenter exactement une fois la version d’un fichier modifié ;
+- aucune ligne vide inutile à l’intérieur des corps selon les conventions du projet ;
+- une ligne vide finale ;
+- exports TS-rs obligatoires pour les payloads Tauri partagés ;
+- aucune logique métier lourde dans `kb_app_demo` ;
+- aucun SQL libre exposé dans l’interface ;
+- ne pas modifier `CHANGELOG.md` avant validation complète du jalon ;
+- utiliser une interface officielle Solana/SPL étroite lorsqu’elle expose le contrat nécessaire ;
+- préférer `wincode`, puis Borsh, et conserver un parser local borné lorsque l’interface officielle n’expose que `bincode` ;
+- ne jamais ajouter de dépendance directe à `bincode` ;
+- toute crate opérationnelle utilise un target `tracing` canonique égal au package Cargo ;
+- tout statut decode `failed`/`unsupported`, input unmatched, matérialisation `failed` ou erreur de persistance doit produire un événement `error` structuré ;
+- une transaction on-chain échouée mais correctement décodée et un refus de politique conforme ne sont pas des erreurs logicielles.
+
+## 5. Sources de vérité
+
+La précision des formats binaires est bloquante.
+
+### Ordre de priorité
+
+1. code et contrats du workspace ;
+2. sources officielles actuelles Agave/Solana SDK ;
+3. crates officielles d’interface Solana correspondant au programme, avec leurs features de sérialisation réellement activées ;
+4. tests, encodeurs et fixtures officiels ;
+5. documentation officielle ;
+6. transactions mainnet réelles déjà présentes ou acquises par le workspace.
+
+Ne pas utiliser un blog, un parser tiers ou un souvenir comme source normative lorsqu’une source officielle existe.
+
+### Règles de recherche
+
+Pour chaque programme :
+
+- identifier le program ID depuis `kb_program_ids` ;
+- identifier la définition officielle actuelle et les variantes historiques ;
+- relever le format de sérialisation exact ;
+- relever l’ordre exact des comptes, flags signer/writable et règles optionnelles ;
+- relever les variantes ajoutées ou supprimées selon les versions ;
+- documenter la source et, lorsque possible, le commit/tag consulté ;
+- créer une fixture à partir d’un encodeur officiel ou d’une transaction réelle vérifiée ;
+- vérifier d’abord si l’interface expose `wincode` ou Borsh ; ne pas activer une feature `bincode` uniquement pour éviter un parser local ;
+- ajouter la dépendance officielle uniquement à la crate qui consomme réellement ses types ;
+- ne jamais deviner un discriminant, un tag, un offset, une taille ou une sémantique.
+
+Si deux sources officielles divergent, conserver les deux variantes lorsque les transactions historiques peuvent encore les contenir et documenter la règle de dispatch.
+
+## 6. Périmètre exact des programmes
+
+### 6.1 Runtime natif principal
+
+Décoder maximalement :
+
+- `11111111111111111111111111111111` — System Program ;
+- `Vote111111111111111111111111111111111111111` — Vote Program ;
+- `Stake11111111111111111111111111111111111111` — Stake Program ;
+- `Config1111111111111111111111111111111111111` — Config Program ;
+- `ComputeBudget111111111111111111111111111111` — Compute Budget Program ;
+- `AddressLookupTab1e1111111111111111111111111` — Address Lookup Table Program ;
+- `ZkE1Gama1Proof11111111111111111111111111111` — ZK ElGamal Proof Program.
+
+### 6.2 Programmes historiques encore observables
+
+Décoder/classifier correctement :
+
+- `Feature111111111111111111111111111111111111` — Feature Program ;
+- `ZkTokenProof1111111111111111111111111111111` — ancien ZK Token Proof Program.
+
+### 6.3 Compte natif historique non exécutable
+
+- `StakeConfig11111111111111111111111111111111` — compte de configuration Stake historique déprécié.
+
+Cette adresse doit rester dans `native_well_known_account_ids()` et ne doit produire aucune surface de décodage, aucun dispatch et aucun plan d’exécution. L’alias historique `STAKE_CONFIG_PROGRAM_ID` reste uniquement déprécié au profit de `STAKE_CONFIG_ACCOUNT_ID`.
+
+### 6.4 Loaders
+
+Décoder maximalement :
+
+- `NativeLoader1111111111111111111111111111111` ;
+- `BPFLoader1111111111111111111111111111111111` ;
+- `BPFLoader2111111111111111111111111111111111` ;
+- `BPFLoaderUpgradeab1e11111111111111111111111` ;
+- `LoaderV411111111111111111111111111111111111`.
+
+### 6.5 Précompiles
+
+Décoder :
+
+- `Ed25519SigVerify111111111111111111111111111` ;
+- `KeccakSecp256k11111111111111111111111111111` ;
+- `Secp256r1SigVerify1111111111111111111111111`.
+
+Les précompiles n’utilisent pas nécessairement une enum sérialisée classique. Leur parser doit valider les compteurs, tables d’offsets, références à d’autres instructions, tailles et bornes avant toute lecture.
+
+### 6.6 Exclusion explicite
+
+`MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr` et `Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo` ne font pas partie de `0.4.1`. Memo appartient aux programmes SPL et sera traité dans la série correspondante.
+
+## 7. Couverture fonctionnelle minimale attendue
+
+La liste suivante est un guide de couverture, pas une autorisation à coder depuis la mémoire. Les noms et formats définitifs doivent être confirmés dans les sources officielles.
+
+### 7.1 System Program
+
+Couvrir au minimum toutes les variantes officielles observables, notamment :
+
+- create account ;
+- assign ;
+- transfer ;
+- create account with seed ;
+- advance nonce account ;
+- withdraw nonce account ;
+- initialize nonce account ;
+- authorize nonce account ;
+- allocate ;
+- allocate with seed ;
+- assign with seed ;
+- transfer with seed ;
+- upgrade nonce account ;
+- toute variante historique ou checked officiellement définie.
+
+Produire des événements structurés avec :
+
+- lamports ;
+- space ;
+- owner ;
+- base/seed lorsque présents ;
+- autorités ;
+- comptes source/destination/nonce ;
+- état on-chain succès/échec.
+
+### 7.2 Compute Budget
+
+Couvrir toutes les variantes officielles, y compris les formes historiques encore décodables, par exemple :
+
+- request units deprecated ;
+- request heap frame ;
+- set compute unit limit ;
+- set compute unit price ;
+- set loaded accounts data size limit ;
+- toute nouvelle variante réellement présente dans la source officielle utilisée.
+
+Les paramètres doivent rester numériques sans perte. Le décodeur doit reproduire le comportement réel du runtime : lorsqu’Agave utilise une désérialisation unchecked qui accepte des octets suffixes, décoder la valeur officielle minimale et conserver le suffixe par taille, préfixe borné et SHA-256 au lieu de le rejeter ou de l’ignorer silencieusement.
+
+### 7.3 Address Lookup Table
+
+Couvrir :
+
+- create lookup table ;
+- freeze lookup table ;
+- extend lookup table ;
+- deactivate lookup table ;
+- close lookup table.
+
+Conserver slot récent, bump seed, autorité, adresses ajoutées et comptes concernés lorsque présents.
+
+### 7.4 Vote
+
+Couvrir toutes les instructions officielles actuelles et historiques observables :
+
+- initialize account ;
+- authorize et authorize checked ;
+- vote et variantes compactes ;
+- vote/state update ;
+- tower sync lorsqu’officiel ;
+- withdraw ;
+- update validator identity ;
+- update commission ;
+- seed/checked variants ;
+- toute variante ajoutée dans les interfaces officielles.
+
+Ne pas matérialiser une mise à jour de vote comme mutation réussie lorsque la transaction on-chain a échoué.
+
+### 7.5 Stake
+
+Couvrir toutes les instructions officielles actuelles et historiques observables :
+
+- initialize et initialize checked ;
+- authorize, authorize with seed et variantes checked ;
+- delegate stake ;
+- split ;
+- merge ;
+- withdraw ;
+- deactivate ;
+- set lockup et checked ;
+- get minimum delegation ;
+- deactivate delinquent ;
+- redelegate ;
+- move stake / move lamports lorsqu’officiels ;
+- toute variante historique encore sérialisable.
+
+Conserver autorités, vote account, custodian, lockup, lamports, seeds et relations de comptes.
+
+### 7.6 Config et Feature
+
+Décoder le format exact de leurs mises à jour et données de configuration. Stake Config reste explicitement exclu, car il s’agit d’un compte et non d’une surface d’instruction. Lorsque le programme ne fournit pas une sémantique métier plus fine, produire un événement générique explicite avec :
+
+- type d’opération officiel ;
+- clés signataires/configurées ;
+- payload borné ou hashé selon la taille ;
+- statut de décodage ;
+- aucune interprétation inventée.
+
+### 7.7 ZK proofs
+
+Pour `zk_elgamal_proof` et `zk_token_proof` :
+
+- couvrir chaque type de preuve officiellement déclaré ;
+- valider tailles et tags ;
+- éviter de recopier inutilement de gros blobs ;
+- conserver le type de preuve, tailles, références et hashes nécessaires à l’audit ;
+- distinguer preuve reconnue, preuve complètement décodée et payload invalide.
+
+### 7.8 Loaders
+
+Couvrir les variantes officielles de chaque loader, notamment selon le loader concerné :
+
+- write ;
+- finalize ;
+- initialize buffer ;
+- deploy/deploy with max data length ;
+- upgrade ;
+- set authority et checked ;
+- close ;
+- extend program ;
+- truncate ;
+- retract ;
+- transfer authority ;
+- finalize ;
+- migration éventuelle si officiellement définie.
+
+Conserver les offsets, longueurs, autorités, program/programdata/buffer accounts et paramètres de déploiement.
+
+### 7.9 Précompiles
+
+Pour chaque signature décrite :
+
+- valider le nombre d’entrées ;
+- décoder les offsets et instruction indexes ;
+- résoudre les références à l’instruction courante ou à une autre instruction du même message ;
+- borner toutes les slices ;
+- conserver l’algorithme, la clé/adresse, la signature, le message ou son hash selon la taille ;
+- conserver le résultat on-chain de la transaction, sans prétendre revalider cryptographiquement si le décodeur ne le fait pas ;
+- tester les offsets invalides, références hors bornes, tailles tronquées et compteurs incohérents.
+
+## 8. Modèle d’événements
+
+### 8.1 Principes
+
+Les événements doivent être :
+
+- versionnés ;
+- déterministes ;
+- sérialisables sans perte ;
+- indépendants de PostgreSQL ;
+- indépendants de Tauri ;
+- stables pour le replay ;
+- explicites sur le programme et la variante ;
+- reliés à la signature, au slot, au chemin d’instruction et au contexte outer/inner ;
+- explicites sur `transaction_succeeded` ou équivalent ;
+- capables de conserver les comptes résolus et rôles utiles.
+
+Ne pas créer un type unique rempli de champs optionnels incohérents si des enums typées par famille sont plus sûres.
+
+### 8.2 Statuts
+
+Conserver les distinctions :
+
+- `recognized` : programme/surface reconnue ;
+- `decoded` : format complet validé et événement produit ;
+- `ignored` : variante volontairement non matérialisée mais comprise ;
+- `unsupported` : variante officielle pas encore supportée ;
+- `failed` : payload invalide, tronqué ou incohérent ;
+- `unmatched` : aucun processor compatible, normalement zéro dans une sélection bornée correctement.
+
+Une reconnaissance du program ID sans décodage du payload ne doit pas incrémenter `decoded`.
+
+### 8.3 Inconnus
+
+Pour un discriminant/tag inconnu :
+
+- ne pas paniquer ;
+- produire un diagnostic borné ;
+- enregistrer la couverture inconnue ;
+- conserver le tag et un hash du payload ;
+- ne pas inventer un nom d’instruction ;
+- permettre un futur replay après changement de version du décodeur.
+
+## 9. Matérialisation
+
+### 9.1 Principe
+
+La version vise d’abord le décodage maximal. Ajouter une matérialisation uniquement lorsqu’elle apporte une projection générique stable qui n’est pas déjà représentée proprement dans core.
+
+Candidats autorisés après justification :
+
+- transferts SOL ;
+- création/initialisation/autorisation/withdraw/upgrade de nonce accounts ;
+- changements d’autorité stake/vote/config/loader ;
+- lifecycle des Address Lookup Tables ;
+- lifecycle des programmes/buffers/programdata upgradeables ;
+- paramètres Compute Budget demandés par transaction ;
+- opérations administratives natives utiles au risque/audit.
+
+### 9.2 Interdictions
+
+- ne pas matérialiser une mutation réussie depuis une transaction échouée ;
+- ne pas dupliquer sans raison les account keys, balances ou instructions core ;
+- ne pas créer une table par instruction ;
+- ne pas introduire de schéma PostgreSQL explicite ;
+- conserver la convention `kb_sol_<domain>_<name>` ;
+- documenter chaque clé d’idempotence et règle de replacement par version ;
+- ne pas ajouter un matérialiseur vide uniquement pour activer le bouton de démo.
+
+Si aucune projection n’est suffisamment stable dans un premier delta, conserver la matérialisation désactivée et documenter ce choix.
+
+## 10. Stockage, ledger et couverture
+
+Préserver les invariants `0.4.0` :
+
+- persistance atomique ;
+- skip exact par processor/version/input hash ;
+- force replay ciblé ou global explicitement autorisé ;
+- remplacement versionné sans duplication ;
+- couverture déclarée synchronisée ;
+- couverture observée par programme/surface/entry ;
+- séparation succès/échec on-chain ;
+- `campaign_id` propagé ;
+- aucune réapplication DDL par commande Tauri ;
+- rollback complet en cas d’erreur intermédiaire.
+
+Une migration SQL n’est autorisée que si les types actuels ne peuvent réellement pas représenter les événements ou matérialisations. Préférer les tables génériques versionnées existantes lorsque leur contrat est suffisant.
+
+## 11. Corpus et fixtures
+
+### 11.1 Corpus existant
+
+La base validée contient au moins :
+
+- 382 observations Compute Budget ;
+- 94 observations System ;
+- 170 transactions core au moment des validations précédentes ;
+- des transactions réussies et échouées ;
+- des instructions outer et inner.
+
+Commencer par System et Compute Budget pour valider rapidement le passage de `unsupported` à `decoded`.
+
+### 11.2 Acquisition de nouveaux corpus
+
+Utiliser les outils existants :
+
+1. `demo_sql_replay_candidates` pour détecter les programmes présents ;
+2. `demo_backfill` pour acquérir des signatures réelles ;
+3. `demo_core_extraction` pour créer les inputs core ;
+4. `demo_decode_replay` pour décoder/rejouer ;
+5. diagnostics decode/ledger/couverture pour vérifier les compteurs.
+
+Pour les programmes rares, utiliser des fixtures synthétiques dérivées des encodeurs officiels. Ne pas bloquer tout le jalon sur l’absence immédiate d’un corpus mainnet, mais distinguer clairement :
+
+- couvert par fixture officielle ;
+- observé dans une transaction réelle ;
+- décodé et rejoué sur PostgreSQL réel.
+
+### 11.3 Fichiers de corpus
+
+Conserver les fixtures dans les crates concernées ou dans un dossier de fixtures déjà normalisé par le workspace. Ne pas ajouter de payload massif dupliqué. Pour chaque fixture, documenter :
+
+- programme ;
+- variante ;
+- succès/échec ;
+- outer/inner ;
+- source ;
+- attendu ;
+- raison de la fixture.
+
+## 12. Tests obligatoires
+
+### 12.1 Tests unitaires par décodeur
+
+Pour chaque variante :
+
+- payload valide ;
+- payload tronqué ;
+- tag inconnu ;
+- champs numériques limites ;
+- comptes manquants ou index invalides ;
+- transaction réussie ;
+- transaction échouée ;
+- sérialisation déterministe ;
+- stabilité de l’event kind ;
+- input hash stable.
+
+### 12.2 Précompiles
+
+Ajouter des tests spécifiques :
+
+- zéro entrée si autorisé/interdit par le format ;
+- plusieurs signatures ;
+- références à l’instruction courante ;
+- références à une autre instruction ;
+- index hors bornes ;
+- offset hors bornes ;
+- chevauchement/troncature ;
+- message vide ;
+- message volumineux borné/hashé.
+
+### 12.3 Pipeline
+
+Préserver et compléter :
+
+- dispatch exact ;
+- skip même version/hash ;
+- replay après changement de version ;
+- force replay ciblé ;
+- replay global autorisé et limité ;
+- annulation avant admission ;
+- annulation partielle avec `completed = started` ;
+- couverture declared/observed/decoded/error ;
+- transaction échouée ;
+- matérialisation refusée si aucune implémentation active.
+
+### 12.4 PostgreSQL réel
+
+Ajouter ou étendre les tests optionnels contrôlés par `KB_POSTGRES_TEST_URL` :
+
+- persistance d’événements natifs ;
+- idempotence ;
+- skip ;
+- force replay ;
+- remplacement de version ;
+- rollback atomique ;
+- couverture ;
+- aucune matérialisation réussie depuis une transaction échouée.
+
+## 13. Démo Tauri
+
+Réutiliser `demo_decode_replay`.
+
+N’ajouter des champs que s’ils sont nécessaires à l’inspection des événements natifs. Ne pas introduire de SQL libre.
+
+Le résumé doit continuer à afficher :
+
+- `campaignId` ;
+- selected/started/completed/notStarted ;
+- unmatched/failed/cancelled ;
+- compteurs par processor ;
+- decoded/ignored/unsupported/failed ;
+- matérialisations.
+
+Les diagnostics doivent permettre de vérifier :
+
+- tables decode/mat/ledger ;
+- couverture par programme/surface/entry ;
+- événements décodés récents ;
+- sorties matérialisées récentes si elles existent.
+
+Conserver les validations frontend du backfill et la désactivation de la matérialisation lorsque la liste de matérialiseurs est vide.
+
+## 14. Phasage recommandé
+
+### Phase A — audit et modèle
+
+- auditer l’existant ;
+- établir la matrice officielle programmes/variantes/sources ;
+- stabiliser les enums d’événements et erreurs de parsing ;
+- ajouter les utilitaires de lecture bornée nécessaires.
+
+### Phase B — System et Compute Budget
+
+- implémenter les deux surfaces déjà présentes dans le corpus ;
+- replay réel ;
+- vérifier `decoded > 0`, `unsupported` en baisse, `failed = 0` sur les variantes connues ;
+- valider skip et force replay.
+
+### Phase C — Address Lookup Table et loaders
+
+- ajouter ALT ;
+- ajouter loaders deprecated/v2/upgradeable/v4/native ;
+- fixtures officielles et corpus réel lorsque disponible ;
+- matérialisation lifecycle si justifiée.
+
+### Phase D — Vote, Stake, Config et programmes historiques
+
+- couvrir les enums complètes ;
+- traiter les variantes checked/seed/historiques ;
+- ajouter corpus et tests de transactions échouées.
+
+### Phase E — Précompiles et ZK
+
+- implémenter les parsers à offsets bornés ;
+- ajouter tests adversariaux ;
+- vérifier absence de panic et erreurs explicites.
+
+### Phase F — matérialisation, diagnostics et clôture
+
+- ajouter uniquement les projections justifiées ;
+- replay global du corpus ;
+- contrôler couverture et ledger ;
+- vérifier absence de régression ;
+- mettre à jour README/ROADMAP/docs ;
+- mettre à jour CHANGELOG uniquement après validation utilisateur.
+
+Chaque phase peut produire un delta `pre.xxx`. Ne pas attendre la fin complète pour livrer une correction bloquante, mais conserver une base cohérente à chaque delta.
+
+## 15. Validations de clôture
+
+Adapter les comptes de tests au résultat réel, sans les inventer.
+
+Exécuter au minimum :
+
+```bash
+cargo test -p kb_program_ids
+cargo test -p kb_decoder_api
+cargo test -p kb_decoder_solana_core
+cargo test -p kb_materializer_api
+cargo test -p kb_pipeline
+cargo test -p kb_store_core
+
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb_store_pg -- --nocapture
+
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+
+(cd kb_app_demo && npm run build)
+
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Selon les crates réellement modifiées, ajouter leurs tests spécifiques.
+
+### Scénarios Tauri obligatoires
+
+1. replay System/Compute Budget sur signatures explicites ;
+2. second replay sans force : tous les inputs courants doivent être skipped ;
+3. force replay ciblé : aucun skip ;
+4. replay global avec petite limite : limite strictement respectée ;
+5. transaction on-chain échouée : événement décodé d’intention/échec, aucune mutation matérialisée réussie ;
+6. tag inconnu ou fixture invalide : `failed`/unknown correctement compté sans panic ;
+7. annulation : `completed = started` et `started + not_started = selected` ;
+8. nouvelle campagne après annulation ;
+9. même `campaign_id` dans app/pipeline/store/décodeur ;
+10. `error.jsonl` global et les `error.jsonl` par crate vides hors erreurs volontairement injectées et contrôlées ;
+11. diagnostics de couverture cohérents ;
+12. absence de duplication après replay/force replay.
+
+## 16. Documentation à maintenir
+
+Mettre à jour au fil des deltas :
+
+- `README.md` ;
+- `ROADMAP.md` ;
+- README des crates touchées ;
+- `docs/NATIVE_SOLANA_PROGRAMS.md` ;
+- `docs/DECODER_MATERIALIZATION_CONTRACTS.md` si le contrat change ;
+- `docs/TRACING_CONTRACT.md`, `docs/LOGGING.md` et `docs/SOLANA_INTERFACE_DEPENDENCIES.md` si leur matrice change ;
+- document de matrice/couverture si distinct ;
+- exemples ou procédures de corpus.
+
+Ne modifier `CHANGELOG.md` qu’après validation complète et explicite de l’utilisateur.
+
+## 17. Critères de sortie de `0.4.1`
+
+Le jalon est clôturable uniquement si :
+
+- chaque program ID du périmètre possède une déclaration de couverture ;
+- toutes les variantes officiellement identifiées sont décodées ou explicitement documentées comme non observables/non supportables avec justification ;
+- aucun discriminant n’est inventé ;
+- les payloads invalides ne paniquent pas ;
+- System et Compute Budget sont validés sur corpus réel ;
+- les autres familles sont couvertes au minimum par fixtures officielles vérifiables ;
+- le ledger skip/force/version fonctionne ;
+- les transactions échouées respectent la politique de non-mutation ;
+- la couverture et les diagnostics sont cohérents ;
+- les tests PostgreSQL réels passent ;
+- le build frontend passe ;
+- clippy est propre ;
+- les scénarios Tauri passent ;
+- aucune régression `0.4.0` n’est constatée ;
+- la documentation est alignée ;
+- l’utilisateur a explicitement validé la clôture.
+
+## 18. Règle de conduite pendant la session
+
+Ne pas demander confirmation pour chaque détail mineur. Inspecter d’abord le workspace et faire le meilleur choix compatible avec les règles et l’architecture. Signaler rapidement toute incohérence détectée, livrer des deltas minimaux et réutilisables, et ne jamais masquer une validation non exécutée.
+
+Ne pas modifier ou supprimer des données PostgreSQL utilisateur sans commande explicite. Les scripts destructifs doivent rester manuels, documentés et hors exécution automatique.

migration/khadhroony-bot2-reference/prompts/021_v0_4_2_executor_solana_core.md

@@ -0,0 +1,281 @@
+<!-- file: prompts/021_v0_4_2_executor_solana_core.md -->
+<!-- version: 2 -->
+
+# Prompt de session — `0.4.2` infrastructure d’exécution et `kb_executor_solana_core`
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.1` et démarrer `0.4.2`.
+
+Le but de `0.4.2` est de transformer les exécuteurs réservés en une infrastructure d’exécution sûre, testable et explicitement bornée, puis de couvrir progressivement toutes les instructions natives officiellement appelables dans `kb_executor_solana_core`.
+
+Les crates produites doivent rester universelles et réutilisables par des CLI, workers, applications Tauri, outils d’administration ou futurs exécutables non liés au trading. Une opération dangereuse doit être implémentée et testée avec une politique renforcée ; elle peut rester non exposée dans `kb_app_demo`.
+
+`0.4.2` ne doit pas commencer les décodeurs SPL, Pump, Meteora, Raydium, Orca, Jupiter ou DEX. Le jalon porte sur l’exécution native Solana Core uniquement.
+
+## 2. Base de travail
+
+La base attendue est le workspace complet après application et validation de :
+
+```text
+khadhroony-bot2_v0.4.1-pre.022-full.zip
+khadhroony-bot2_v0.4.1-pre.023-delta.zip
+```
+
+Avant modification :
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md` et `CHANGELOG.md` ;
+2. lire `docs/EXECUTION_MODEL.md` ;
+3. lire `docs/NATIVE_SOLANA_CLOSURE_AUDIT.md` ;
+4. lire `docs/NATIVE_SOLANA_MATERIALIZATION_AUDIT.md` ;
+5. lire `prompts/020_v0_4_1_native_solana_programs.md` pour comprendre les surfaces décodées ;
+6. auditer les crates `kb_executor_solana_core`, `kb_wallet`, `kb_rpc`, `kb_pipeline`, `kb_app_demo`, `kb_decoder_solana_core` et les crates de matérialisation natives ;
+7. ne pas supposer qu’un type, builder, fonction ou dépendance existe sans l’avoir inspecté.
+
+Après l’archive complète initiale, livrer uniquement des ZIP delta.
+
+## 3. État validé à préserver
+
+`0.4.1` est validée avec :
+
+```text
+kb_program_ids                         5 tests
+kb_decoder_solana_core               114 tests
+kb_materializer_lifecycle             16 tests
+kb_materializer_admin                  7 tests
+kb_materializer_compliance_audit       7 tests
+kb_materializer_staking                8 tests
+kb_config                             36 tests
+kb_pipeline                           45 tests
+kb_store_pg                           45 tests avec PostgreSQL réel
+kb_app_demo                           78 tests
+cargo clippy --all-targets             propre
+```
+
+Les replays mainnet de clôture rapportent notamment :
+
+```text
+System          817 decoded, 258 outputs, 52 expected refusals
+Config           96 decoded,  96 outputs
+Stake           448 decoded, 447 outputs, 1 expected refusal
+Vote            600 decoded, 600 outputs
+ComputeBudget  2746 decoded, 1603 transaction profiles
+ZkElGamal       151 decoded, 139 context outputs
+ALT             104 decoded, 104 lifecycle outputs
+```
+
+Les transactions échouées restent décodées comme intentions ou diagnostics. Les matérialiseurs mutables ne produisent pas de mutation réussie pour une transaction non commitée.
+
+## 4. Contraintes normatives
+
+Respecter strictement les règles du workspace :
+
+- Rust 2024 ;
+- async-first pour l’I/O ;
+- `kb_core::Error` et `kb_core::Result` ;
+- pas de `anyhow` ni `thiserror` ;
+- pas de `unwrap`, `expect`, `unsafe` ou panic de production ;
+- retours explicites ;
+- `warn(missing_docs)`, `deny(unreachable_pub)`, `forbid(unsafe_code)` ;
+- imports seulement pour les traits lorsque possible ;
+- chemins pleinement qualifiés et `crate::` en intra-crate ;
+- documentation de code en anglais ;
+- Markdown projet en français ;
+- header `file:` puis `version:` dans chaque fichier modifié ;
+- version de fichier incrémentée exactement une fois ;
+- aucun `bincode` direct ;
+- aucune logique métier lourde dans `kb_app_demo` ;
+- aucun SQL libre exposé dans l’interface ;
+- `CHANGELOG.md` inchangé jusqu’à validation complète du jalon ;
+- toute crate opérationnelle utilise un target `tracing` canonique égal au package Cargo.
+
+## 5. Principes d’exécution
+
+Un décodeur lit une transaction passée. Un exécuteur prépare une opération future.
+
+L’exécution doit être découpée en étapes explicites :
+
+```text
+intent
+  -> execution plan
+    -> policy checks
+      -> transaction build
+        -> simulation / dry-run
+          -> signature
+            -> send
+              -> confirmation
+                -> post-execution decode replay validation
+```
+
+Ne jamais mélanger construction, signature, envoi et validation dans une seule fonction opaque.
+
+Par défaut :
+
+- dry-run activé ;
+- simulation obligatoire ;
+- mainnet désactivé ou exigeant une confirmation explicite ;
+- plafond de lamports/frais obligatoire pour les opérations dépensières ;
+- cluster attendu vérifié ;
+- signataires requis listés avant signature ;
+- blockhash ou nonce durable contrôlé ;
+- post-validation possible via replay decode/materialization.
+
+## 6. Objectifs `0.4.2`
+
+### 6.1 API d’exécution
+
+Stabiliser ou créer les contrats nécessaires dans `kb_execution_api` et `kb_execution_safety` si ces crates existent déjà, ou les créer uniquement si le ROADMAP et le workspace les attendent réellement.
+
+Contrats attendus :
+
+- intent typé ;
+- plan d’exécution ;
+- instruction planifiée ;
+- comptes et signataires requis ;
+- politique de cluster ;
+- politique de simulation ;
+- coût/plafond ;
+- résultat de simulation ;
+- résultat d’envoi ;
+- diagnostic post-exécution.
+
+Si les crates n’existent pas encore, privilégier un delta minimal et cohérent plutôt qu’un design trop large.
+
+### 6.2 `kb_executor_solana_core`
+
+Remplacer tout support générique `Maybe` par des capacités exactes :
+
+```text
+Supported(operation)
+Unsupported(reason)
+```
+
+Premières opérations candidates :
+
+- System transfer SOL ;
+- System create account contrôlé ;
+- System allocate ;
+- System assign ;
+- durable nonce initialize/advance/authorize/withdraw, seulement si la politique de sécurité est claire ;
+- Compute Budget set compute unit limit ;
+- Compute Budget set compute unit price.
+
+Après les premières opérations, étendre la bibliothèque à :
+
+- toutes les variantes System et durable nonce officiellement constructibles ;
+- Address Lookup Table ;
+- Stake et Vote avec politiques d’autorité dédiées ;
+- loaders et changements d’autorité ;
+- Config, Feature, ZK et Slashing ;
+- précompiles lorsqu’un constructeur officiel ou un layout runtime vérifiable existe.
+
+`Unsupported(reason)` doit rester temporaire et justifié. La dangerosité impose une politique, des confirmations et des tests cluster ; elle ne constitue pas une raison de supprimer définitivement le builder.
+
+### 6.3 Builders officiels
+
+Chaque instruction construite doit être comparée à un builder officiel ou à un layout officiel vérifiable. Ne pas inventer de layout.
+
+Pour les opérations supportées :
+
+- tester le program ID ;
+- tester le nom d’opération ;
+- tester les comptes ;
+- tester le payload ;
+- tester les signataires ;
+- tester les limites et erreurs de politique ;
+- tester le refus sur cluster ou contexte interdit.
+
+### 6.4 Wallet temporaire
+
+Ajouter dans `kb_wallet` un signer de laboratoire universel avant l’orchestration d’envoi :
+
+- génération en mémoire ;
+- persistance optionnelle sous `wallets/` avec alias validé ;
+- création sans écrasement ;
+- format keypair Solana standard ;
+- permissions privées et exclusion Git ;
+- aucune clé privée dans les logs, TS-rs, Tauri ou PostgreSQL ;
+- profils mainnet fournis sans wallet temporaire actif.
+
+Le wallet temporaire persistant sert à conserver la même adresse entre les sessions devnet. Les backends chiffrés, coffre système et hardware wallet restent prévus pour la couche wallet de production.
+
+### 6.5 Démo Tauri
+
+Ajouter ou étendre une démo uniquement si nécessaire, sans logique métier lourde :
+
+- visualiser un plan ;
+- afficher les signataires requis ;
+- lancer une simulation ;
+- ne pas envoyer réellement sur mainnet sans confirmation explicite ;
+- ne pas exposer de SQL libre.
+
+Si l’UI n’est pas indispensable dans un premier delta, valider d’abord les crates d’API et d’exécution par tests unitaires.
+
+## 7. Matérialisations et validation post-exécution
+
+Une exécution réussie doit pouvoir être validée après coup par le pipeline existant :
+
+```text
+signature envoyée
+  -> backfill / canonical insert
+    -> core extraction
+      -> decode replay
+        -> materialization
+```
+
+Ne pas faire dépendre l’exécuteur du décodeur. La validation post-exécution peut être orchestrée par `kb_pipeline` ou `kb_app_demo`, mais le builder d’instruction doit rester indépendant.
+
+## 8. Interdictions dans `0.4.2`
+
+Ne pas :
+
+- commencer SPL Memo, SPL Token ou Token-2022 ;
+- ajouter Pump/Meteora/Raydium/Orca/Jupiter ;
+- activer un exécuteur mainnet par défaut ;
+- envoyer une transaction sans simulation explicite ;
+- cacher les signataires requis ;
+- créer une abstraction « supporté peut-être » ;
+- exposer dans `kb_app_demo` une opération dangereuse sans besoin opérateur explicite, politique dédiée et validation cluster ;
+- utiliser `bincode` directement ;
+- déplacer de logique métier dans `kb_app_demo`.
+
+## 9. Validations attendues
+
+Selon les fichiers touchés, exécuter au minimum :
+
+```bash
+cargo test -p kb_executor_solana_core
+cargo test -p kb_pipeline
+cargo test -p kb_app_demo
+cargo test -p kb_config
+cargo clippy --all-targets
+```
+
+Si `kb_store_pg` ou l’orchestration post-exécution est touchée :
+
+```bash
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb_store_pg -- --nocapture
+```
+
+Si Tauri est touché :
+
+```bash
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+## 10. Livraison
+
+Livrer des deltas incrémentaux nommés :
+
+```text
+khadhroony-bot2_v0.4.2-pre.NNN-delta.zip
+```
+
+Le ZIP doit contenir :
+
+- uniquement les fichiers ajoutés ou modifiés ;
+- `delta.md` ;
+- `manifest.json` ;
+- aucune archive complète sauf demande explicite ;
+- aucune modification de `CHANGELOG.md` avant validation finale du jalon.

migration/khadhroony-bot2-reference/prompts/022_v0_4_3_spl_memo.md

@@ -0,0 +1,401 @@
+<!-- file: prompts/022_v0_4_3_spl_memo.md -->
+<!-- version: 1 -->
+
+# Prompt de session — `0.4.3` SPL Memo v1, v3 et v4
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.2` et démarrer `0.4.3`.
+
+Le jalon doit traiter **complètement** la surface SPL Memo avant de commencer SPL Token :
+
+```text
+program IDs v1 / v3 / v4
+  -> décodage maximal
+  -> projection métier explicite
+  -> exécuteur typé pour les générations réellement constructibles
+  -> simulation et validation post-exécution
+```
+
+L'objectif n'est pas seulement de reconnaître une chaîne UTF-8. Il faut produire un contrat stable pour l'audit, la recherche, la corrélation de paiements, les annotations de transaction et les futures contraintes Token-2022 MemoTransfer.
+
+Le worker d'acquisition historique décrit dans `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md` reste différé et hors périmètre. Ne créer aucune crate historique et ne consommer aucun temps du jalon sur Explorer, Solscan, BigQuery ou Old Faithful.
+
+## 2. Base de travail
+
+La base attendue est le commit Git qui clôture `0.4.2` et contient notamment :
+
+- `ROADMAP.md` avec `0.4.3 — SPL Memo v1, v3 et v4` ;
+- `RULES.md` avec la règle de livraison `delta-fix-NNN` ;
+- `prompts/022_v0_4_3_spl_memo.md` ;
+- `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md` hors ROADMAP actif.
+
+Avant toute modification :
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md` et `CHANGELOG.md` ;
+2. lire `prompts/020_v0_4_1_native_solana_programs.md` et `prompts/021_v0_4_2_executor_solana_core.md` pour préserver les contrats de décodage, matérialisation et exécution ;
+3. lire `docs/EXECUTION_MODEL.md`, `docs/SOLANA_INTERFACE_DEPENDENCIES.md` et les audits de clôture `0.4.1`/`0.4.2` ;
+4. auditer `kb_decoder_spl_memo`, `kb_executor_spl_memo`, `kb_program_ids`, `kb_decoder_api`, `kb_materializer_api`, les matérialiseurs existants, `kb_execution_api`, `kb_execution_safety`, `kb_execution_solana`, `kb_pipeline`, `kb_rpc`, `kb_store_core`, `kb_store_pg` et `kb_app_demo` ;
+5. inspecter les types et conventions réellement présents ; ne pas supposer qu'un helper ou schéma existe ;
+6. vérifier la version exacte de `spl-memo-interface` résolue par Cargo et les sources officielles/historiques des trois générations avant d'écrire le wire.
+
+## 3. État validé à préserver
+
+La clôture `0.4.2` a été validée avec :
+
+```text
+kb_program_ids                         5 tests
+kb_decoder_solana_core               116 tests
+kb_executor_solana_core               88 tests
+kb_execution_api                      22 tests
+kb_execution_safety                   15 tests
+kb_execution_solana                   12 tests
+kb_rpc                               113 tests
+kb_pipeline                           56 tests
+kb_config                             41 tests
+kb_app_demo                           88 tests
+kb_store_pg                           45 tests avec PostgreSQL réel
+cargo clippy --all-targets             propre
+cargo tauri dev                        validé avec Vite
+```
+
+Le parcours Devnet réel System transfer a été validé avec simulation, signature, envoi, confirmation, insertion canonique, extraction core et decode replay. Les 52 méthodes HTTP et neuf paires WS standards restent couvertes ; les méthodes WS instables restent activables par endpoint et désactivables automatiquement après rejet du nœud.
+
+Aucune régression de ces invariants n'est acceptable.
+
+## 4. Sources normatives
+
+Utiliser en priorité :
+
+- le registre local `kb_program_ids` pour les trois IDs déjà vérifiés ;
+- le dépôt officiel Memo : <https://github.com/solana-program/memo> ;
+- la crate `spl-memo-interface` déjà cataloguée dans le workspace ;
+- les tags et sources historiques officiels pour v1 et v3 ;
+- le code runtime officiel pour la validation UTF-8 et les comptes signataires ;
+- des transactions réelles et des fixtures synthétiques contrôlées.
+
+Le dépôt officiel publie actuellement une interface `2.1.x` et une génération de programme v4. Ne pas mettre à jour automatiquement une dépendance ou considérer les trois générations identiques sans audit. Si l'interface officielle ne construit que l'ID courant, les instructions historiques ne peuvent être reproduites manuellement qu'après preuve que leur layout exact est le même.
+
+## 5. Program IDs
+
+Le jalon couvre exactement :
+
+```text
+SPL_MEMO_V1_PROGRAM_ID = Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo
+SPL_MEMO_V3_PROGRAM_ID = MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr
+SPL_MEMO_V4_PROGRAM_ID = Memo4c2pN8afCj432Lb7RMVKi9PbQnnW7ewFFaV3oAH
+```
+
+`MEMO_PROGRAM_ID` reste l'alias historique déjà défini dans `kb_program_ids`; ne pas l'utiliser lorsqu'une génération exacte est nécessaire.
+
+## 6. Contraintes normatives du workspace
+
+Respecter strictement :
+
+- Rust 2024 ;
+- async-first pour l'I/O ;
+- `kb_core::Error` et `kb_core::Result` ;
+- aucun `anyhow`, `thiserror`, `unwrap`, `expect`, `unsafe`, panic de production ou opérateur `?` dans les nouveaux chemins de production ;
+- `warn(missing_docs)`, `deny(unreachable_pub)`, `forbid(unsafe_code)` ;
+- imports de traits uniquement lorsque possible, chemins pleinement qualifiés et `crate::` en intra-crate ;
+- commentaires/docstrings Rust en anglais, Markdown projet en français ;
+- header `file:` puis `version:` avec un seul incrément par fichier modifié ;
+- aucun `bincode` direct ;
+- aucune logique métier lourde dans `kb_app_demo` ;
+- `CHANGELOG.md` inchangé avant validation complète du jalon ;
+- `TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
+- aucune valeur JSON Tauri exportée en `bigint` lorsqu'elle traverse `invoke`, `emit` ou `JSON.stringify`.
+
+## 7. Audit préalable obligatoire
+
+Avant d'implémenter, produire un tableau de vérité pour v1, v3 et v4 :
+
+- ID et statut actuel/historique ;
+- format exact de l'instruction ;
+- validation UTF-8 ;
+- comportement du payload vide ;
+- traitement des comptes ;
+- obligation `is_signer` ;
+- prise en compte de l'ordre et des doublons ;
+- logs runtime ;
+- différences de limites ou coûts ;
+- disponibilité d'un builder officiel ;
+- invocabilité actuelle sur Localnet/Devnet/Mainnet ;
+- corpus réel disponible.
+
+Toute différence entre générations doit apparaître explicitement dans les types, la matrice de couverture et les tests. Ne pas fusionner v1/v3/v4 sous un comportement supposé commun.
+
+## 8. `kb_decoder_spl_memo`
+
+### 8.1 Remplacement du scaffold
+
+- remplacer `DecoderSupport::Maybe` par `Yes` pour les trois IDs exacts et `No` pour les autres ;
+- déplacer la cible tracing legacy vers `src/constants.rs` avec la valeur exacte `kb_decoder_spl_memo` ;
+- ajouter `tracing` uniquement si des événements runtime réels sont émis ;
+- ne produire aucun événement pour une observation hors surface.
+
+### 8.2 Événement décodé
+
+Définir un contrat stable qui conserve au minimum :
+
+- génération Memo v1/v3/v4 ;
+- Program ID exact ;
+- texte lorsque le payload est UTF-8 valide ;
+- longueur exacte en octets ;
+- SHA-256 du payload ;
+- préfixe hex borné pour diagnostic/replay ;
+- liste ordonnée des comptes fournis ;
+- pour chaque compte : pubkey, signer, writable et position ;
+- liste des signataires exigés/observés selon le contrat de la génération ;
+- chemin outer/inner et index stable ;
+- succès/échec de la transaction ;
+- `committed` ou intention non commitée ;
+- statut de validation UTF-8 et de validation des signataires ;
+- diagnostic borné pour une tentative invalide.
+
+Le texte complet peut être conservé si sa taille est intrinsèquement bornée par la transaction Solana et par une limite explicite du décodeur. La limite et la stratégie de troncature éventuelle doivent être testées et documentées.
+
+### 8.3 Transactions échouées
+
+Une transaction échouée doit pouvoir produire une intention structurée lorsque le payload et les comptes sont suffisamment lisibles, sans prétendre que le runtime a validé UTF-8, vérifié les signataires ou commit l'annotation.
+
+Distinguer clairement :
+
+- payload valide et transaction réussie ;
+- payload valide mais transaction échouée ;
+- payload UTF-8 invalide ;
+- compte requis non signer ;
+- observation tronquée ou mal formée ;
+- génération/ID inconnu.
+
+### 8.4 Couverture et corpus
+
+Créer une matrice machine-readable dédiée, par exemple :
+
+```text
+docs/SPL_MEMO_MATRIX.json
+```
+
+Elle doit être vérifiée par un test Rust et couvrir les trois program IDs, les cas de succès, les erreurs et les différences de génération.
+
+Corpus minimal :
+
+- payload vide ;
+- ASCII ;
+- Unicode multi-octets ;
+- taille proche de la limite pratique ;
+- octets UTF-8 invalides ;
+- zéro, un et plusieurs signataires ;
+- compte non signer ;
+- comptes supplémentaires ou dupliqués si acceptés par le runtime ;
+- outer instruction ;
+- inner/CPI ;
+- transaction réussie ;
+- transaction échouée ;
+- au moins une signature réelle par génération lorsque disponible.
+
+## 9. Matérialisation
+
+Le décodage maximal doit être stabilisé avant la projection.
+
+Le domaine attendu est une **annotation de transaction** consultable. Ne pas détourner arbitrairement `metadata`, `admin`, `lifecycle` ou `trades`.
+
+Après audit des contrats existants :
+
+1. utiliser un matérialiseur existant seulement si son domaine couvre explicitement les annotations de transaction ;
+2. sinon créer une crate dédiée, par exemple `kb_materializer_transaction_annotations`, avec un contrat réutilisable au-delà de Memo ;
+3. garder les faits de vérification/audit séparables du texte si plusieurs consommateurs sont nécessaires.
+
+Projection minimale :
+
+- signature et instruction path ;
+- génération et Program ID ;
+- texte ou représentation bornée ;
+- longueur et hash ;
+- signataires vérifiés ;
+- état committed ;
+- provenance du processor et version ;
+- clé d'idempotence déterministe.
+
+Règles :
+
+- aucune projection réussie mutable pour une transaction non commitée ;
+- replay identique = skip/idempotence ;
+- changement de version = remplacement déterministe selon le ledger ;
+- ne pas dupliquer les logs ou données core déjà stockés ;
+- documenter explicitement toute donnée laissée uniquement dans l'événement décodé.
+
+## 10. `kb_executor_spl_memo`
+
+### 10.1 Contrat typé
+
+Remplacer le plan réservé par une voie typée fondée sur `kb_execution_api`.
+
+Types candidats :
+
+```text
+SplMemoGeneration
+SplMemoOperation::AddMemo
+SplMemoExecutionIntent
+SplMemoSigner
+```
+
+Le contrat doit permettre :
+
+- choix explicite de la génération ;
+- payload UTF-8 validé avant plan ;
+- signataires ordonnés et déclarés ;
+- absence de compte writable inventé ;
+- limites de taille explicites ;
+- coût de dépense nul hors frais réseau ;
+- `Supported`/`Unsupported(reason)` exact par génération.
+
+### 10.2 Builders et wire
+
+- utiliser `spl-memo-interface` lorsque son builder et son Program ID correspondent exactement à la génération demandée ;
+- comparer les instructions produites aux builders officiels ;
+- pour une génération historique sans builder courant, construire manuellement uniquement après validation du layout depuis les sources officielles ;
+- le payload Memo est constitué des octets exacts du message, sans préfixe, discriminator, Borsh ou `bincode` inventé ;
+- chaque compte signer doit apparaître avec les flags officiels exacts ;
+- rejeter les doublons ou formes anormales seulement si le contrat officiel les rejette réellement.
+
+### 10.3 Politiques
+
+- simulation obligatoire ;
+- dry-run par défaut ;
+- aucune activation Mainnet par défaut ;
+- signataires visibles avant signature ;
+- fee payer déclaré ;
+- plafond de frais appliqué par l'infrastructure commune ;
+- aucune clé privée dans les logs, Tauri ou les payloads JSON ;
+- post-validation par hydratation, core extraction et decode replay Memo.
+
+Les générations historiques peuvent rester `Unsupported(reason)` côté exécuteur si leur invocabilité actuelle ou leur builder ne peut pas être prouvé. Elles restent néanmoins obligatoires côté décodeur.
+
+## 11. Pipeline, store et démo
+
+- enregistrer le décodeur et le matérialiseur dans le replay commun ;
+- ajouter les déclarations de couverture et tests de sélection ;
+- toucher `kb_store_pg` uniquement si une nouvelle projection nécessite réellement un contrat de persistance ;
+- conserver les écritures atomiques avec le ledger decode/materialize ;
+- utiliser `demo_decode_replay` pour les corpus et résumés ;
+- ne créer une nouvelle fenêtre Tauri que si l'exécution Memo Devnet ne peut pas être validée avec les surfaces existantes ;
+- une démo d'exécution peut rester backend/test opt-in si l'UI n'apporte pas de valeur supplémentaire.
+
+## 12. Validation Devnet
+
+Ajouter un test opt-in ou un petit parcours opérateur qui :
+
+1. charge le wallet temporaire Devnet existant ;
+2. construit un Memo de la génération courante validée ;
+3. simule ;
+4. signe et envoie seulement avec autorisation explicite ;
+5. confirme ;
+6. appelle `getTransaction` ;
+7. insère la transaction canonique ;
+8. exécute core extraction ;
+9. exécute decode replay Memo ;
+10. vérifie la projection et l'idempotence.
+
+Ne pas exiger l'envoi des générations historiques si elles ne sont plus officiellement déployées ou supportées sur Devnet.
+
+## 13. Documentation attendue
+
+Mettre à jour au minimum :
+
+```text
+kb_decoder_spl_memo/README.md
+kb_executor_spl_memo/README.md
+README.md
+ROADMAP.md
+docs/SOLANA_INTERFACE_DEPENDENCIES.md
+docs/SPL_MEMO_MATRIX.json
+```
+
+Ajouter le README du matérialiseur créé ou modifié. Documenter :
+
+- différences v1/v3/v4 ;
+- types d'événements ;
+- projection choisie ;
+- opérations exécutables ;
+- limites et refus ;
+- corpus et signatures réelles utilisées ;
+- résultats Localnet/Devnet ;
+- absence volontaire de projection ou d'exécution, le cas échéant.
+
+`CHANGELOG.md` ne doit être modifié qu'après validation complète de `0.4.3`.
+
+## 14. Interdictions
+
+Ne pas :
+
+- commencer SPL Token, ATA, Token-2022, Stake Pool, Pump, Meteora, Raydium, Orca ou Jupiter ;
+- créer ou commencer W2/historical acquisition ;
+- fusionner Memo dans `kb_decoder_solana_core` ;
+- considérer les trois IDs comme identiques sans preuve ;
+- utiliser les logs RPC comme seule source du texte lorsque l'instruction est disponible ;
+- inventer un discriminator ou une structure sérialisée ;
+- exposer un envoi Mainnet par défaut ;
+- produire une projection committed pour une transaction échouée ;
+- ajouter du SQL libre à l'UI ;
+- générer des bindings TypeScript contenant des `bigint` dans les frontières Tauri JSON.
+
+## 15. Validations minimales
+
+Selon les fichiers touchés :
+
+```bash
+cargo test -p kb_program_ids
+cargo test -p kb_decoder_spl_memo
+cargo test -p kb_materializer_transaction_annotations   # si créée
+cargo test -p kb_executor_spl_memo
+cargo test -p kb_execution_api
+cargo test -p kb_execution_safety
+cargo test -p kb_execution_solana
+cargo test -p kb_pipeline
+cargo test -p kb_rpc
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+```
+
+Si le store ou la projection est touché :
+
+```bash
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb_store_pg -- --nocapture
+```
+
+Si Tauri est touché :
+
+```bash
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Le serveur Vite lancé par Tauri constitue la validation frontend normale ; ne pas imposer un `npm run build` séparé sans besoin particulier.
+
+## 16. Livraison
+
+Livrer des tranches fonctionnelles sous la forme :
+
+```text
+khadhroony-bot2_v0.4.3-pre.NNN-delta.zip
+```
+
+Après la livraison d'un delta `pre.NNN`, tout correctif conserve le même numéro :
+
+```text
+khadhroony-bot2_v0.4.3-pre.NNN-delta-fix-001.zip
+khadhroony-bot2_v0.4.3-pre.NNN-delta-fix-002.zip
+```
+
+Ne pas incrémenter `NNN` pour réparer une archive déjà livrée. Le numéro suivant est réservé à une nouvelle tranche fonctionnelle.
+
+Chaque archive doit contenir :
+
+- uniquement les fichiers ajoutés ou modifiés ;
+- `delta.md` non versionné ;
+- `manifest.json` ;
+- les suppressions manuelles explicitement listées ;
+- les validations exécutées et non exécutées ;
+- aucune archive complète sauf demande explicite ;
+- aucune modification de `CHANGELOG.md` avant validation finale du jalon.

migration/khadhroony-bot2-reference/prompts/023_v0_4_4_spl_token.md

@@ -0,0 +1,447 @@
+<!-- file: prompts/023_v0_4_4_spl_token.md -->
+<!-- version: 1 -->
+
+# Prompt de session — `0.4.4` SPL Token
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.3` et démarrer `0.4.4`.
+
+Le jalon couvre exclusivement le programme SPL Token classique :
+
+```text
+TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
+  -> audit du wire historique et courant
+  -> décodage maximal des instructions outer et inner
+  -> projections métier explicites et idempotentes
+  -> exécuteur typé pour toutes les opérations officiellement constructibles
+  -> simulation, politiques d’autorité/multisig et validation post-exécution
+```
+
+Le décodeur doit comprendre les instructions anciennes, actuelles et officiellement publiées même lorsqu’une opération récente n’est pas encore déployée sur tous les clusters. L’exécuteur est une bibliothèque universelle : il ne doit pas interdire artificiellement un cluster. La disponibilité du programme et d’une instruction est prouvée par l’audit de déploiement et la simulation ; les applications et politiques communes décident ensuite si un envoi est autorisé.
+
+Ne pas commencer SPL Associated Token Account, Token-2022, ses extensions, Transfer Hook, MemoTransfer, Stake Pool ou une surface DEX. Le worker décrit dans `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md` reste différé et hors périmètre.
+
+## 2. Base de travail
+
+La base attendue est le commit Git qui clôture `0.4.3` et contient notamment :
+
+- `ROADMAP.md` avec `0.4.3` coché et `0.4.4 — SPL Token` actif ;
+- `CHANGELOG.md` avec l’entrée validée `0.4.3` ;
+- `prompts/022_v0_4_3_spl_memo.md` conservé comme historique ;
+- `prompts/023_v0_4_4_spl_token.md` comme contrat actif ;
+- `docs/HISTORICAL_DATA_ACQUISITION_PLAN.md` hors ROADMAP actif.
+
+Avant toute modification :
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md` et `CHANGELOG.md` ;
+2. lire `prompts/020_v0_4_1_native_solana_programs.md`, `prompts/021_v0_4_2_executor_solana_core.md` et `prompts/022_v0_4_3_spl_memo.md` pour préserver les contrats de décodage, matérialisation, exécution et validation post-exécution ;
+3. lire `docs/EXECUTION_MODEL.md`, `docs/SOLANA_INTERFACE_DEPENDENCIES.md`, `docs/SPL_MEMO_MATRIX.json` et les audits de clôture `0.4.1`/`0.4.2` ;
+4. auditer `kb_decoder_spl_token`, `kb_executor_spl_token`, `kb_program_ids`, `kb_decoder_api`, `kb_materializer_api`, `kb_materializer_token_accounts`, `kb_materializer_admin`, `kb_materializer_fees`, `kb_materializer_risk`, `kb_execution_api`, `kb_execution_safety`, `kb_execution_solana`, `kb_pipeline`, `kb_rpc`, `kb_store_core`, `kb_store_pg` et `kb_app_demo` ;
+5. inspecter les types réellement présents et les événements core déjà extraits, notamment les balances SPL, sans supposer qu’un helper, snapshot de compte ou schéma métier existe ;
+6. vérifier avec Cargo la version exacte de `spl-token-interface` résolue depuis la contrainte workspace `^3.0`, ses features effectives et ses sources locales avant d’écrire le wire ;
+7. comparer cette version à la version réellement déployée du programme sur Localnet, Devnet et Mainnet, instruction par instruction.
+
+État de départ connu : `kb_decoder_spl_token` et `kb_executor_spl_token` sont encore des scaffolds `Maybe`; `kb_materializer_token_accounts`, `kb_materializer_fees` et `kb_materializer_risk` sont des scaffolds inactifs ; `kb_materializer_admin` est déjà réel et ne doit pas régresser.
+
+## 3. État validé à préserver
+
+La clôture `0.4.3` a été validée avec :
+
+```text
+kb_program_ids                              5 tests
+kb_decoder_spl_memo                        9 tests
+kb_materializer_transaction_annotations    7 tests
+kb_executor_spl_memo                      15 tests
+kb_execution_api                          22 tests
+kb_execution_safety                       15 tests
+kb_execution_solana                       12 tests
+kb_pipeline                               61 tests
+kb_rpc                                   113 tests
+kb_app_demo                               96 tests
+kb_store_pg                               46 tests avec PostgreSQL réel
+cargo clippy --all-targets                  propre
+```
+
+Le parcours Memo v4 Devnet réel a validé simulation, signature, envoi, confirmation, insertion canonique, extraction core, decode replay, annotation et second replay idempotent. Les trois générations Memo restent décodables et exécutables par la bibliothèque. Les 52 méthodes HTTP et neuf paires WS standard restent couvertes.
+
+Aucune régression de ces invariants n’est acceptable.
+
+## 4. Sources normatives
+
+Utiliser en priorité :
+
+- `kb_program_ids::SPL_TOKEN_PROGRAM_ID` pour l’ID exact ;
+- le dépôt officiel SPL Token : <https://github.com/solana-program/token> ;
+- le tag exact correspondant à la crate `spl-token-interface` résolue ;
+- `interface/src/instruction.rs`, les builders officiels et le processor runtime officiel ;
+- les layouts officiels `state::Mint`, `state::Account` et `state::Multisig` lorsque leur lecture est nécessaire ;
+- la documentation officielle Solana Token ;
+- des transactions Mainnet réelles et des fixtures synthétiques contrôlées ;
+- des scénarios Localnet/Devnet pour les opérations stateful et les instructions nouvellement publiées.
+
+Au 15 juillet 2026, le catalogue workspace déclare `spl-token-interface = ^3.0` sans feature. La publication officielle `3.0.0` ajoute notamment `UnwrapLamports` au tag `45` et `Batch` au tag `255`. Ne pas conclure qu’elles sont déployées partout, ni les ignorer parce qu’elles sont récentes. Auditer séparément :
+
+- le layout publié par l’interface ;
+- le processor et le binaire déployé par cluster ;
+- la constructibilité du builder ;
+- le résultat de simulation ;
+- le corpus réel disponible.
+
+Ne pas activer `bincode`. Utiliser l’unpack officiel lorsqu’il correspond exactement au runtime audité ou reproduire localement un wire borné avec tests différentiels.
+
+## 5. Program ID et frontières
+
+Le jalon couvre exactement :
+
+```text
+SPL_TOKEN_PROGRAM_ID = TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
+```
+
+Le Native Mint `So11111111111111111111111111111111111111112` est un compte mint spécial du programme SPL Token, pas un autre programme. Il doit être pris en compte pour `SyncNative`, `CloseAccount`, retraits de lamports et transferts wrapped SOL, sans être enregistré comme décodeur distinct.
+
+Sont hors surface de dispatch `0.4.4` :
+
+- `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb` et toutes les extensions Token-2022 ;
+- `ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL` ;
+- Metaplex Token Metadata ;
+- Token Group, Token Metadata Interface et Transfer Hook tiers ;
+- les programmes DEX qui invoquent SPL Token par CPI.
+
+Une instruction SPL Token en CPI reste toutefois décodée par `kb_decoder_spl_token` grâce à son Program ID exact et à son chemin inner stable.
+
+## 6. Contraintes normatives du workspace
+
+Respecter strictement :
+
+- Rust 2024 ;
+- async-first pour l’I/O ;
+- `kb_core::Error` et `kb_core::Result` ;
+- aucun `anyhow`, `thiserror`, `unwrap`, `expect`, `unsafe`, panic de production ou opérateur `?` dans les nouveaux chemins de production ;
+- `warn(missing_docs)`, `deny(unreachable_pub)`, `forbid(unsafe_code)` ;
+- imports de traits uniquement lorsque possible, chemins pleinement qualifiés et `crate::` en intra-crate ;
+- commentaires/docstrings Rust en anglais, Markdown projet en français ;
+- header `file:` puis `version:` avec un seul incrément par fichier modifié ;
+- aucun `bincode` direct ;
+- aucune logique métier lourde dans `kb_app_demo` ;
+- `CHANGELOG.md` inchangé avant validation complète de `0.4.4` ;
+- `TRACING_TARGET` canonique dans `src/constants.rs` pour toute crate opérationnelle ;
+- aucune valeur JSON Tauri exportée en `bigint` lorsqu’elle traverse `invoke`, `emit` ou `JSON.stringify` ;
+- montants on-chain bruts sérialisés sans perte, sous forme de chaîne à la frontière Tauri si nécessaire.
+
+## 7. Audit préalable obligatoire
+
+Créer une matrice machine-readable dédiée, par exemple :
+
+```text
+docs/SPL_TOKEN_MATRIX.json
+```
+
+Elle doit être vérifiée par un test Rust et contenir au minimum, pour chaque instruction officielle :
+
+- nom canonique et tag wire ;
+- statut historique, courant, récent ou réservé ;
+- layout exact et tailles autorisées ;
+- comptes requis, ordre, writable et signer ;
+- forme autorité simple et forme multisig ;
+- champs décodés et limites ;
+- événement produit ;
+- projection(s) autorisée(s) ;
+- builder officiel disponible ;
+- support exécuteur exact avec éventuel motif `Unsupported` ;
+- statut observé Localnet/Devnet/Mainnet ;
+- fixtures synthétiques et signatures réelles.
+
+L’audit doit couvrir l’ensemble de `TokenInstruction` de la version résolue, y compris :
+
+- initialisation mint/account/multisig et variantes sans Rent ;
+- `Transfer`, `Approve`, `Revoke`, `SetAuthority`, `MintTo`, `Burn` ;
+- `CloseAccount`, `FreezeAccount`, `ThawAccount` ;
+- les variantes `Checked` ;
+- `SyncNative` ;
+- `GetAccountDataSize`, `InitializeImmutableOwner`, conversions amount/UI amount ;
+- `WithdrawExcessLamports` ;
+- `UnwrapLamports` si présent dans la version résolue ;
+- `Batch` si présent, avec parsing récursif borné et interdiction des batchs imbriqués selon le runtime officiel ;
+- tout autre tag publié dans la version effectivement résolue.
+
+Ne pas recopier une ancienne liste supposée de 25 instructions. L’égalité entre la matrice, l’interface résolue, les déclarations de couverture et les opérations compilées doit être testée.
+
+## 8. `kb_decoder_spl_token`
+
+### 8.1 Remplacement du scaffold
+
+- remplacer `DecoderSupport::Maybe` par `Yes` uniquement pour l’ID SPL Token classique exact et `No` pour les autres ;
+- déplacer le target tracing legacy vers `src/constants.rs` avec la valeur exacte `kb_decoder_spl_token` ;
+- ajouter `tracing` seulement si des événements runtime réels sont émis ;
+- ne produire aucun événement pour une observation hors surface.
+
+### 8.2 Contrat décodé commun
+
+Chaque observation lisible doit conserver au minimum :
+
+- Program ID exact ;
+- instruction et tag wire ;
+- chemin outer/inner et index stable ;
+- succès/échec de la transaction et état `committed` ;
+- comptes ordonnés avec position, pubkey, signer et writable ;
+- rôles de comptes résolus sans inventer un rôle absent ;
+- forme d’autorité simple ou multisig ;
+- autorité déclarée, signataires fournis et validation structurelle ;
+- montants bruts exacts, decimals lorsqu’ils sont dans le wire et aucune valeur UI inventée ;
+- mint explicite lorsqu’il est fourni ;
+- diagnostic borné et préfixe hex/hash pour un wire invalide ou inconnu ;
+- source de toute inférence issue du contexte core.
+
+Les transactions échouées doivent produire des intentions structurées lorsque le wire et les comptes restent lisibles, sans prétendre que l’état Token a muté.
+
+### 8.3 Sémantique et inférences
+
+- Un `Transfer` non checked ne porte pas le mint ni les decimals dans son wire. Ne pas les inventer. Une corrélation via les token balance changes core peut être exposée avec provenance et confiance explicites ; une lecture RPC n’appartient pas au décodeur.
+- Les variantes checked portent le mint et les decimals attendus, mais une transaction échouée ne prouve pas qu’ils ont été validés par le runtime.
+- Distinguer owner, delegate, mint authority, freeze authority, close authority et multisig authority.
+- Conserver l’ordre et les doublons des comptes réellement fournis. Valider `MIN_SIGNERS`, `MAX_SIGNERS`, `M` et `N` selon le runtime, sans confondre comptes membres du multisig et signataires effectifs de l’instruction.
+- `InitializeImmutableOwner` est un no-op de compatibilité sur SPL Token classique si le runtime audité le confirme ; le représenter explicitement sans inventer une extension Token-2022.
+- Les instructions de return data doivent conserver l’intention et, si la donnée de retour est disponible dans la transaction canonique, la valider sans dépendre des logs texte.
+- `Batch` doit conserver ses sous-instructions, slices de comptes, ordre et diagnostics. Imposer des bornes de profondeur, compteur, longueur et comptes ; ne jamais accepter silencieusement un suffixe mal formé.
+
+### 8.4 Corpus minimal
+
+Le corpus synthétique et réel doit couvrir :
+
+- chaque tag officiel de la version résolue ;
+- autorité simple et multisig `1..11`, seuils valides et invalides ;
+- montants `0`, `1`, `u64::MAX` et valeurs intermédiaires ;
+- decimals `0`, `9`, maximum wire et mismatch runtime ;
+- authorities présentes, révoquées et `COption::None` ;
+- comptes manquants, supplémentaires, dupliqués et flags incorrects ;
+- outer instruction et CPI inner ;
+- transaction réussie et échouée ;
+- wrapped SOL et comptes non natifs ;
+- payload vide, tag inconnu, taille tronquée, suffixe et UTF-8 invalide pour `UiAmountToAmount` ;
+- batch vide, plusieurs sous-instructions, longueurs invalides et batch imbriqué ;
+- transactions Mainnet réelles représentatives, avec signatures documentées.
+
+## 9. Matérialisation
+
+Stabiliser le décodage maximal avant les projections. Auditer d’abord les contrats existants ; ne pas conserver les sorties simplistes des scaffolds.
+
+### 9.1 `kb_materializer_token_accounts`
+
+Projeter les faits métier commités utiles concernant comptes et mints, par exemple :
+
+- initialisation de mint, compte et multisig ;
+- transfert, mint et burn comme mutation instructionnelle ;
+- freeze/thaw ;
+- close et wrapped SOL sync/unwrap ;
+- état de délégation lorsqu’il relève explicitement du compte token.
+
+Ne pas dupliquer les balance changes core. Les projections instructionnelles doivent référencer signature, path, comptes, mint connu ou inconnu, montant brut, provenance et clé d’idempotence. Elles ne doivent pas prétendre reconstruire un snapshot final de compte sans lecture stateful prouvée.
+
+### 9.2 `kb_materializer_admin`
+
+Étendre le matérialiseur réel uniquement pour les changements d’autorité Token et la configuration multisig qui appartiennent clairement au domaine admin. Préserver ses surfaces natives existantes et ses tests.
+
+### 9.3 `kb_materializer_risk`
+
+Activer une projection seulement pour des faits de risque stables et explicitement justifiés, par exemple délégation/allowance, freeze/thaw, autorité révoquée ou configuration multisig faible. Séparer constat on-chain et interprétation de risque ; ne pas produire un score arbitraire.
+
+### 9.4 `kb_materializer_fees`
+
+SPL Token classique ne possède pas les transfer fees de Token-2022. Ne pas fabriquer de frais à partir d’un transfert, ni dupliquer les frais réseau core. Si aucune instruction du runtime audité ne justifie une projection `fee`, documenter explicitement `no projection` et laisser le scaffold inactif jusqu’à un futur consommateur légitime.
+
+### 9.5 Règles communes
+
+- aucune projection mutable réussie pour une transaction non commitée ;
+- replay identique = skip/idempotence ;
+- changement de version = remplacement déterministe selon le ledger ;
+- une sous-instruction `Batch` produit des identités stables dérivées du path parent et de sa position ;
+- ne pas dupliquer logs, account keys, balances ou données core ;
+- documenter les faits conservés uniquement dans le decode ;
+- réutiliser `kb_sol_mat_events` sauf preuve qu’un contrat de persistance spécialisé est indispensable.
+
+## 10. `kb_executor_spl_token`
+
+### 10.1 Contrat typé
+
+Remplacer le plan réservé par des intents explicites couvrant les opérations officiellement constructibles. Le contrat doit exposer :
+
+- opération exacte ;
+- Program ID exact ;
+- comptes et rôles ordonnés ;
+- mint, compte source/destination et authority selon l’opération ;
+- montant brut et decimals séparés ;
+- autorité simple ou multisig avec signataires ordonnés ;
+- création ou initialisation stateful clairement séparée ;
+- politique de simulation obligatoire, dry-run par défaut et plafond de frais ;
+- coût token/SOL déclaré sans confondre montant transféré, rent et frais réseau ;
+- `Supported` ou `Unsupported(reason)` exact par opération.
+
+### 10.2 Builders et wire
+
+- utiliser les builders `spl-token-interface` lorsqu’ils correspondent exactement à l’opération et au Program ID ;
+- comparer chaque instruction produite au builder officiel et aux fixtures wire ;
+- ne pas inventer de discriminator, Borsh ou sérialisation ;
+- préserver strictement l’ordre, writable et signer des metas ;
+- valider les formes multisig et dédupliquer seulement les signataires transactionnels requis, pas les metas si le contrat officiel les conserve ;
+- construire les opérations publiées récentes, y compris `UnwrapLamports` ou `Batch`, seulement après preuve exacte du layout et du builder ;
+- classer séparément constructibilité, déploiement et autorisation d’envoi.
+
+La bibliothèque ne doit pas être limitée à Devnet. Mainnet reste gouverné par `kb_execution_safety`, les profils applicatifs et la confirmation explicite. Une instruction future/test peut être constructible et simulable sur un cluster qui la déploie même si Mainnet ne la supporte pas encore.
+
+### 10.3 Préflight stateful
+
+Définir dans `kb_pipeline`, lorsque nécessaire, des lectures préflight bornées pour :
+
+- owner du compte et Program ID ;
+- mint, decimals et état initialisé ;
+- solde token et native reserve ;
+- delegate et allowance ;
+- authority/freeze authority ;
+- multisig `M/N` et membres ;
+- rent exemption et état de comptes à initialiser ;
+- cohérence source/destination/mint ;
+- préconditions close, freeze/thaw, mint, burn, sync et unwrap.
+
+Le décodeur reste sans RPC. L’exécuteur reste sans wallet/RPC. L’orchestrateur possède les lectures stateful, la simulation, la signature, l’envoi et la validation.
+
+## 11. Pipeline, store et démo
+
+- enregistrer le décodeur et les matérialiseurs Token validés dans le replay commun ;
+- ajouter les déclarations de couverture et tests de sélection exacts ;
+- conserver les écritures atomiques avec le ledger decode/materialize ;
+- toucher `kb_store_pg` seulement si un nouveau contrat de requête ou persistance est réellement nécessaire ;
+- utiliser `demo_backfill`, `demo_core_extraction`, `demo_sql_replay_candidates` et `demo_decode_replay` pour le corpus Mainnet ;
+- étendre le navigateur de matérialisations seulement avec des filtres bornés et des DTOs typés, sans SQL libre ;
+- réutiliser la fenêtre d’exécution Devnet existante si une validation opérateur Token apporte une valeur claire ;
+- ne pas créer une WebView par opération.
+
+Pour la visualisation, afficher les mutations Token comme journal métier filtrable par signature, mint, compte, famille et opération. Les OHLC restent réservées aux futurs trades agrégés ; elles ne sont pas une représentation de SPL Token brut.
+
+## 12. Validation cluster
+
+Ajouter des tests opt-in et un parcours opérateur représentatif qui :
+
+1. utilise Localnet ou Devnet selon le déploiement de l’instruction ;
+2. prépare des comptes temporaires sans dépendre de l’ATA pour la logique du jalon ;
+3. construit et simule l’opération exacte ;
+4. signe et envoie seulement avec autorisation explicite ;
+5. confirme ;
+6. appelle `getTransaction` ;
+7. insère la transaction canonique ;
+8. exécute core extraction ;
+9. exécute decode replay SPL Token ;
+10. vérifie les projections attendues et l’idempotence.
+
+Le scénario minimal Devnet devrait couvrir au moins initialisation contrôlée, mint, transfer checked, approve/revoke, burn et close, avec autorité simple. Ajouter un scénario multisig si le financement et la complexité restent raisonnables. Tester les instructions récentes sur Localnet lorsque le binaire Devnet ne les expose pas.
+
+Ne pas utiliser le programme ATA pour masquer l’initialisation de comptes Token dans la couverture `0.4.4`; ATA sera traité en `0.4.5`.
+
+## 13. Documentation attendue
+
+Mettre à jour au minimum :
+
+```text
+kb_decoder_spl_token/README.md
+kb_executor_spl_token/README.md
+kb_materializer_token_accounts/README.md
+README.md
+ROADMAP.md
+docs/SOLANA_INTERFACE_DEPENDENCIES.md
+docs/SPL_TOKEN_MATRIX.json
+```
+
+Mettre aussi à jour les README des matérialiseurs réellement modifiés. Documenter :
+
+- version résolue de l’interface et différences avec le programme déployé ;
+- inventaire exact des instructions et tags ;
+- événements et diagnostics ;
+- projections par famille et absences volontaires ;
+- opérations exécutables et `Unsupported(reason)` ;
+- règles simple authority/multisig ;
+- corpus et signatures réelles ;
+- résultats Localnet/Devnet/Mainnet ;
+- limites et non-revendications.
+
+`CHANGELOG.md` ne doit être modifié qu’après validation complète de `0.4.4`.
+
+## 14. Interdictions
+
+Ne pas :
+
+- commencer ATA ou Token-2022 ;
+- absorber les extensions Token-2022 dans le décodeur SPL Token classique ;
+- créer ou commencer l’acquisition historique différée ;
+- fusionner Token dans `kb_decoder_solana_core` ;
+- déduire silencieusement un mint absent d’un `Transfer` non checked ;
+- utiliser les logs RPC comme source principale lorsque l’instruction est disponible ;
+- inventer des fees, snapshots finaux, balances ou autorités validées ;
+- produire une projection committed pour une transaction échouée ;
+- considérer les membres d’un multisig comme tous signataires de chaque instruction ;
+- désactiver une opération dans la bibliothèque uniquement parce qu’elle n’est pas encore déployée sur Mainnet ;
+- exposer un envoi Mainnet par défaut dans la démo ;
+- ajouter du SQL libre à l’UI ;
+- générer des bindings TypeScript contenant des `bigint` dans les frontières Tauri JSON.
+
+## 15. Validations minimales
+
+Selon les fichiers touchés :
+
+```bash
+cargo test -p kb_program_ids
+cargo test -p kb_decoder_spl_token
+cargo test -p kb_materializer_token_accounts
+cargo test -p kb_materializer_admin
+cargo test -p kb_materializer_fees
+cargo test -p kb_materializer_risk
+cargo test -p kb_executor_spl_token
+cargo test -p kb_execution_api
+cargo test -p kb_execution_safety
+cargo test -p kb_execution_solana
+cargo test -p kb_pipeline
+cargo test -p kb_rpc
+cargo test -p kb_app_demo
+cargo clippy --all-targets
+```
+
+Si le store ou une projection est touché :
+
+```bash
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb_store_pg -- --nocapture
+```
+
+Si Tauri est touché :
+
+```bash
+cargo tauri dev -c kb_app_demo/tauri.conf.json
+```
+
+Le serveur Vite lancé par Tauri constitue la validation frontend normale ; ne pas imposer un `npm run build` séparé sans besoin particulier.
+
+## 16. Livraison
+
+Livrer des tranches fonctionnelles sous la forme :
+
+```text
+khadhroony-bot2_v0.4.4-pre.NNN-delta.zip
+```
+
+Après la livraison d’un delta `pre.NNN`, tout correctif conserve le même numéro :
+
+```text
+khadhroony-bot2_v0.4.4-pre.NNN-delta-fix-001.zip
+khadhroony-bot2_v0.4.4-pre.NNN-delta-fix-002.zip
+```
+
+Ne pas incrémenter `NNN` pour réparer une archive déjà livrée. Le numéro suivant est réservé à une nouvelle tranche fonctionnelle.
+
+Chaque archive doit contenir :
+
+- uniquement les fichiers ajoutés ou modifiés ;
+- `delta.md` non versionné ;
+- `manifest.json` ;
+- les suppressions manuelles explicitement listées ;
+- les validations exécutées et non exécutées ;
+- aucune archive complète sauf demande explicite ;
+- aucune modification de `CHANGELOG.md` avant validation finale du jalon.

migration/khadhroony-bot2-reference/prompts/024_v0_4_5_spl_associated_token_account.md

@@ -0,0 +1,244 @@
+<!-- file: prompts/024_v0_4_5_spl_associated_token_account.md -->
+<!-- version: 1 -->
+
+# Prompt de session — `0.4.5` SPL Associated Token Account
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.4` et développer exclusivement la
+surface SPL Associated Token Account :
+
+```text
+ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL
+  -> audit exact de l'interface et du processor résolus
+  -> décodage maximal de Create, CreateIdempotent et RecoverNested
+  -> dérivation et validation explicites des adresses associées
+  -> lifecycle ATA matérialisé sans duplication SPL Token
+  -> exécuteur typé simulation-first après validation du décodeur et des projections
+```
+
+Le jalon couvre les ATA ciblant le programme SPL Token classique et le programme Token-2022, car le
+Program ID Token cible fait partie du contrat ATA. Il ne commence toutefois pas le décodage général
+des instructions ou extensions Token-2022, réservé à `0.4.6`.
+
+## 2. Base de travail
+
+La base attendue clôt `0.4.4` et contient :
+
+- `CHANGELOG.md` avec l'entrée validée SPL Token ;
+- `ROADMAP.md` avec `0.4.4` entièrement coché et `0.4.5` actif ;
+- `docs/SPL_TOKEN_MATRIX.json` et les preuves Mainnet/Devnet conservées ;
+- `kb_decoder_spl_token`, ses matérialiseurs, son exécuteur et son orchestration validés ;
+- `kb_decoder_spl_associated_token_account` et
+  `kb_executor_spl_associated_token_account` encore à l'état de scaffolds ;
+- la dépendance workspace `spl-associated-token-account-interface = ^2.0` avec feature `borsh`.
+
+Avant toute modification :
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md`, `CHANGELOG.md` et ce prompt ;
+2. relire `prompts/023_v0_4_4_spl_token.md`, `docs/EXECUTION_MODEL.md` et
+   `docs/SOLANA_INTERFACE_DEPENDENCIES.md` ;
+3. inspecter la version réellement résolue de l'interface ATA et ses sources locales avec Cargo ;
+4. comparer instruction enum, layouts Borsh, builders, dérivation PDA et processor officiels ;
+5. auditer les transactions réelles outer et CPI pour Token classique et Token-2022 ;
+6. ne pas supposer qu'un helper, un matérialiseur ou un préflight ATA existe déjà.
+
+## 3. Invariants `0.4.4` à préserver
+
+- décodage exact des 28 tags SPL Token classique ;
+- montants bruts et decimals sans perte ;
+- aucune invention de mint sur les instructions qui ne le transportent pas ;
+- projections `token_account`, `admin` et `risk` instructionnelles et idempotentes ;
+- 24 opérations exécuteur Token, préflight stateful et garde-fous communs ;
+- simulation obligatoire, signature après autorisation seulement et replay post-exécution exact ;
+- journal Tauri borné et aucune logique métier lourde dans la WebView ;
+- aucune régression Memo, RPC standard, PostgreSQL ou exécution Solana.
+
+État final de référence communiqué :
+
+```text
+kb_program_ids                               5 tests
+kb_decoder_spl_token                         8 tests
+kb_executor_spl_token                       15 tests
+kb_decoder_spl_memo                          9 tests
+kb_materializer_transaction_annotations      7 tests
+kb_execution_api                            22 tests
+kb_execution_safety                         15 tests
+kb_execution_solana                         12 tests
+kb_pipeline                                 81 tests
+kb_rpc                                     113 tests
+kb_config                                   41 tests
+kb_app_demo                                102 tests
+kb_store_pg                                 46 tests avec PostgreSQL réel
+cargo clippy --all-targets                    propre
+```
+
+## 4. Frontières strictes
+
+Dans le périmètre :
+
+- Program ID ATA exact ;
+- les variantes réellement publiées par l'interface résolue ;
+- ATA destinés à SPL Token classique et Token-2022 ;
+- dérivation canonique à partir du wallet, du Token Program ID et du mint ;
+- création, création idempotente, récupération nested et échecs lisibles ;
+- instructions outer et inner/CPI ;
+- simulation et scénarios Localnet/Devnet bornés.
+
+Hors périmètre :
+
+- décodage général de `TokenInstruction` Token-2022 et de ses extensions ;
+- Transfer Hook, Confidential Transfer, Token Group et Metadata Interface ;
+- Metaplex Token Metadata ;
+- fermeture ou transfert générique de comptes Token déjà couverts par `0.4.4` ;
+- nouveaux DEX, stratégies, trading automatisé ou acquisition historique différée ;
+- migration vers une table SQL dédiée sans preuve qu'elle est nécessaire.
+
+## 5. Matrice machine-readable obligatoire
+
+Créer `docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json`, vérifiée par un test Rust. Pour chaque
+variante publiée, enregistrer :
+
+- discriminant et encodage exact ;
+- comptes requis, ordre, signer et writable ;
+- Program IDs système, Token et ATA attendus ;
+- seeds PDA et adresse dérivée attendue ;
+- différences Token classique/Token-2022 ;
+- règles de création normale, idempotente et nested recovery ;
+- événements décodés et projections autorisées ;
+- support exécuteur et motif stable si decode-only ;
+- preuves synthétiques, Localnet, Devnet et corpus réel ;
+- limites de ce qui est prouvé et non testé.
+
+Imposer par test l'égalité entre matrice, surfaces compilées, déclarations de couverture et capacités
+de l'exécuteur. Ne pas recopier une ancienne enum supposée sans vérifier la version résolue.
+
+## 6. Décodeur
+
+Remplacer `DecoderSupport::Maybe` par un dispatch exact. Le décodeur doit conserver :
+
+- Program ID, instruction path outer/inner et statut committed ;
+- comptes ordonnés, doublons et flags observés ;
+- funding account, ATA, wallet owner, mint, System Program et Token Program ;
+- adresse ATA attendue, adresse observée et résultat de validation ;
+- type de Token Program cible sans prétendre décoder ses extensions ;
+- pour RecoverNested, owner ATA, nested ATA, owner mint et nested mint sans inverser les rôles ;
+- transaction échouée comme intention structurée lorsque le wire reste lisible ;
+- diagnostic borné pour données inconnues, tronquées ou comptes incomplets.
+
+La dérivation PDA doit être canonique et testée différentiellement contre les helpers officiels. Une
+adresse observée incorrecte doit rester décodable avec un diagnostic explicite, jamais être corrigée
+silencieusement.
+
+Déplacer le target tracing legacy vers `src/constants.rs` avec la valeur exacte du nom Cargo. Ne pas
+émettre de faux événement pour un autre Program ID.
+
+## 7. Matérialisation
+
+Auditer en priorité `kb_materializer_token_accounts`, `kb_materializer_lifecycle`,
+`kb_materializer_admin` et `kb_materializer_risk` avant d'ajouter une nouvelle projection.
+
+Le résultat doit :
+
+- matérialiser le lifecycle ATA créé/réutilisé/récupéré avec provenance et idempotence ;
+- distinguer création normale et idempotente ;
+- conserver wallet, mint, ATA et Token Program cible ;
+- ne pas dupliquer les mutations SPL Token déjà produites par les CPI internes ;
+- ne pas prétendre reconstruire un solde Token ou un snapshot final ;
+- refuser les sorties mutables pour les transactions échouées/non commitées ;
+- conserver les faits de tentative et diagnostics détaillés dans le decode lorsque nécessaire.
+
+Tester explicitement une transaction ATA dont les CPI Token sont également décodées : une seule
+projection doit posséder chaque fait métier.
+
+## 8. Exécuteur et préflight
+
+Après validation du décodeur et des projections, remplacer le scaffold exécuteur par des intents
+typés pour toutes les variantes officiellement constructibles. Utiliser les builders officiels
+lorsqu'ils correspondent exactement à l'interface auditée.
+
+Le plan doit exposer :
+
+- payer, wallet owner, mint, ATA dérivé et Token Program cible ;
+- comptes exacts dans l'ordre officiel ;
+- signataires uniques sans modifier l'ordre des metas ;
+- coût SOL maximal correspondant au rent et aux frais ;
+- simulation obligatoire et dry-run par défaut ;
+- validation post-exécution adaptée à la création ou à l'idempotence.
+
+Le préflight stateful Localnet/Devnet doit au minimum vérifier :
+
+- cluster et Program IDs ;
+- existence et owner du mint ;
+- dérivation exacte de l'ATA ;
+- absence du compte pour Create, ou état compatible pour CreateIdempotent ;
+- owner, mint et Token Program du compte existant ;
+- conditions exactes de RecoverNested ;
+- rent et plafonds de dépense ;
+- disponibilité de tous les signataires requis.
+
+La bibliothèque exécuteur reste universelle. Les politiques de cluster, wallet, confirmation et
+Mainnet restent dans les couches communes.
+
+## 9. Corpus et scénarios cluster
+
+Prévoir un corpus offline couvrant au minimum :
+
+- les trois variantes publiées si confirmées par l'interface résolue ;
+- Token classique et Token-2022 comme programmes cibles ;
+- création réussie, compte déjà existant, idempotence réussie et conflits ;
+- ATA attendu correct et adresse incorrecte ;
+- wallet/mint/Token Program erronés ;
+- comptes absents, supplémentaires, dupliqués et flags incorrects ;
+- outer et CPI inner ;
+- transaction réussie et échouée ;
+- RecoverNested valide et formes structurellement invalides.
+
+Ajouter ensuite des tests opt-in Localnet/Devnet. Toute dépense réelle exige des comptes contrôlés,
+un plafond explicite et une confirmation. Les endpoints publics peuvent retourner `429` : conserver
+les signatures déjà confirmées et prévoir une reprise bornée plutôt que recréer aveuglément les
+comptes.
+
+## 10. Tauri
+
+Réutiliser la fenêtre d'exécution Solana existante. Ne pas créer une WebView par opération.
+
+Le panneau ATA représentatif doit montrer :
+
+- profil Devnet ;
+- Token Program cible ;
+- payer/wallet, mint et ATA dérivé readonly ;
+- mode Create ou CreateIdempotent ;
+- préflight, simulation, coût/rent et garde-fou de confirmation ;
+- confirmation, extraction, decode, matérialisation et idempotence après envoi ;
+- journal lifecycle filtrable sans exposer de clé privée.
+
+`RecoverNested` peut rester hors UI si son scénario contrôlé est mieux couvert par un test opt-in,
+mais il ne doit pas être absent du décodeur ni de l'exécuteur si l'interface le publie.
+
+## 11. Contraintes du workspace
+
+Respecter Rust 2024, async-first, `kb_core::Error`/`Result`, les lints workspace et les headers de
+version. Aucun `anyhow`, `thiserror`, `unsafe`, `unwrap`, `expect`, panic de production, opérateur `?`
+dans les nouveaux chemins de production, `bincode` direct ou logique métier lourde dans Tauri.
+Commentaires Rust en anglais, Markdown projet en français. Les montants et lamports traversant Tauri
+restent JSON-safe et sans perte.
+
+Mettre `ROADMAP.md` à jour à chaque tranche. Conserver `CHANGELOG.md` inchangé jusqu'à la validation
+complète de `0.4.5`.
+
+## 12. Critères de clôture
+
+`0.4.5` ne peut être clôturé qu'après :
+
+- matrice et égalité compilée validées ;
+- corpus offline complet ;
+- non-duplication avec SPL Token démontrée ;
+- préflight et exécuteur simulation-first validés ;
+- scénario cluster contrôlé et reprise documentée si nécessaire ;
+- PostgreSQL réel, second replay idempotent et journal Tauri validés ;
+- régression `0.4.4`, RPC, configuration, application et Clippy propres ;
+- README, ROADMAP et CHANGELOG synchronisés seulement après validation finale.
+
+Commencer par l'audit de l'interface réellement résolue et de son processor. Ne pas écrire le wire,
+les événements ou l'exécuteur avant d'avoir publié la première version de la matrice ATA.

migration/khadhroony-bot2-reference/prompts/025_v0_4_6_spl_token_2022.md

@@ -0,0 +1,338 @@
+<!-- file: prompts/025_v0_4_6_spl_token_2022.md -->
+<!-- version: 2 -->
+
+# Prompt de session — `0.4.6` Token-2022, extensions et registre ElGamal
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.5` et développer exclusivement la
+surface Token-2022 et les interfaces qui font réellement partie de son contrat audité :
+
+```text
+TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
+  -> audit exact des interfaces, versions Cargo et processors résolus
+  -> décodage maximal des instructions de base et des extensions identifiables
+  -> lecture exacte des TLV Mint/Account/Multisig sans perte ni invention
+  -> matérialisation maximale avec un propriétaire unique par fait métier
+  -> exécuteur extension par extension après validation du decode et des projections
+
+regVY... registre ElGamal
+  -> programme distinct du ZK ElGamal Proof natif
+  -> Program ID exact à confirmer depuis les sources réellement résolues
+  -> décodage, matérialisation et politique d'exécution propres
+```
+
+La règle du jalon est exhaustive : tout ce qui est officiellement identifiable doit être décodé,
+qu'il soit historique, courant ou expérimental ; tout fait stable et prouvé doit être matérialisé
+sans doublon ; toute opération actuelle officiellement constructible doit être exécutable après
+préflight, sauf preuve explicite qu'elle est historique, obsolète, désactivée ou non déployée.
+
+### Décision de périmètre Token-2022 / registre ElGamal
+
+Token-2022 et le registre ElGamal restent initialement dans le même jalon parce que le registre est
+fonctionnellement lié aux extensions confidentielles. Le reporter sans audit pourrait conduire à
+déclarer à tort une couverture Token-2022 maximale alors qu'une dépendance directe du parcours
+confidentiel resterait inconnue.
+
+Cette proximité fonctionnelle n'autorise aucune fusion technique. Les deux surfaces doivent garder :
+
+- des Program IDs, dispatchs et déclarations de couverture séparés ;
+- des matrices machine-readable séparées ;
+- des événements, diagnostics et propriétaires de matérialisation explicites ;
+- des corpus synthétiques et réels ainsi que des preuves cluster séparés ;
+- des capacités d'exécution et des critères d'activation indépendants ;
+- une distinction stricte avec le programme natif ZK ElGamal Proof déjà couvert.
+
+Le jalon doit progresser dans cet ordre :
+
+1. audit complet Token-2022 et publication de sa première matrice ;
+2. décodeur Token-2022 de base, puis extensions par groupes cohérents ;
+3. audit dédié du registre ElGamal et publication de sa matrice propre ;
+4. matérialisations Token-2022 et ElGamal avec preuve de non-duplication ;
+5. exécution Token-2022 extension par extension après validation stateful ;
+6. exécution du registre uniquement pour ses opérations actuelles, constructibles et validées.
+
+La taille de `0.4.6` ne justifie jamais une réduction de couverture ou de qualité. Si l'audit prouve
+que le registre ElGamal est autonome, sensiblement plus volumineux que prévu ou qu'il exige un
+cycle de preuves indépendant, il peut être reporté vers un jalon séparé. Ce report doit être une
+décision documentée issue de la première matrice et de l'audit des sources résolues, avec mise à
+jour explicite du ROADMAP et des critères de clôture ; il ne doit pas être décidé par commodité
+avant l'audit.
+
+## 2. Base de travail validée
+
+La base attendue clôt `0.4.5` et contient :
+
+- le décodeur SPL Token classique couvrant ses 28 tags et son exécuteur de 24 opérations ;
+- le décodeur ATA couvrant `Create`, `CreateIdempotent`, `RecoverNested` et `Create` vide ;
+- la dérivation ATA dépendant explicitement du Token Program cible ;
+- les matérialisations ATA lifecycle/risk sans duplication des CPI Token ;
+- l'exécuteur ATA des trois variantes, son préflight stateful et son orchestration Devnet ;
+- les preuves Devnet classiques, Token-2022 ATA et RecoverNested ;
+- PostgreSQL réel, second replay idempotent, Tauri/Vite et Clippy validés ;
+- toutes les versions workspace, npm et Tauri synchronisées en `0.4.5`.
+
+État final de référence communiqué :
+
+```text
+kb_program_ids                                      5 tests
+kb_decoder_spl_token                                8 tests
+kb_executor_spl_token                              15 tests
+kb_decoder_spl_associated_token_account            10 tests
+kb_executor_spl_associated_token_account           10 tests
+kb_decoder_spl_memo                                 9 tests
+kb_materializer_transaction_annotations             7 tests
+kb_materializer_token_accounts                      9 tests
+kb_materializer_risk                                6 tests
+kb_materializer_lifecycle                          17 tests
+kb_materializer_admin                               9 tests
+kb_materializer_fees                                3 tests
+kb_execution_api                                   22 tests
+kb_execution_safety                                15 tests
+kb_execution_solana                                12 tests
+kb_pipeline                                        90 tests
+kb_rpc                                            113 tests
+kb_config                                          41 tests
+kb_app_demo                                       111 tests
+kb_store_pg                                        46 tests avec PostgreSQL réel
+cargo clippy --all-targets                           propre
+```
+
+## 3. Lecture et audit obligatoires avant modification
+
+1. lire `RULES.md`, `README.md`, `ROADMAP.md`, `CHANGELOG.md` et ce prompt ;
+2. relire `prompts/023_v0_4_4_spl_token.md`,
+   `prompts/024_v0_4_5_spl_associated_token_account.md`,
+   `docs/SPL_TOKEN_MATRIX.json`, `docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json`,
+   `docs/EXECUTION_MODEL.md` et `docs/SOLANA_INTERFACE_DEPENDENCIES.md` ;
+3. inspecter `Cargo.toml`, `Cargo.lock`, `cargo tree`, `cargo metadata` et les sources Cargo locales
+   pour connaître les versions réellement résolues des interfaces Token-2022 et extensions ;
+4. comparer enum d'instruction, unpack/pack, TLV, builders, validation d'état et processors officiels ;
+5. distinguer strictement ce que publie une interface, ce qu'implémente le processor, ce qui est
+   déployé sur chaque cluster et ce qu'un corpus réel prouve ;
+6. auditer les crates décodeur, exécuteur et matérialiseurs existants avant tout remaniement ;
+7. publier la première matrice machine-readable avant d'écrire le wire, les événements ou
+   l'exécuteur.
+
+Ne recopier aucune ancienne enum, liste d'extensions, taille de compte ou règle TLV supposée. Une
+version ou feature mentionnée dans le catalogue workspace n'est pas une preuve de résolution ni de
+consommation par une crate feuille.
+
+## 4. Frontières strictes
+
+Dans le périmètre :
+
+- Program ID Token-2022 exact ;
+- instructions de base héritées de SPL Token et variantes propres à Token-2022 ;
+- extensions Mint et Account officiellement identifiables, y compris leurs instructions
+  d'initialisation, mise à jour, lecture et lifecycle lorsqu'elles existent ;
+- TLV, préfixes de base Mint/Account/Multisig, longueurs, padding, types et autorités ;
+- Transfer Fee, Interest Bearing, NonTransferable, Permanent Delegate, CPI Guard,
+  Immutable Owner, Default Account State, Memo Transfer, Reallocate, pausable/confidential et
+  autres extensions uniquement selon les sources réellement résolues ;
+- Transfer Hook, Token Group et Token Metadata Interface comme interfaces séparées pouvant être
+  implémentées par des Program IDs tiers ;
+- registre ElGamal comme programme distinct ;
+- instructions outer et inner/CPI, transactions réussies et échouées ;
+- corpus offline, corpus réel et scénarios Localnet/Devnet bornés ;
+- exécution des opérations actuelles constructibles après audit, matérialisation et préflight.
+
+Hors périmètre :
+
+- Metaplex Token Metadata ;
+- programmes tiers implémentant une interface tant que leur Program ID n'est pas explicitement
+  audité et inclus ;
+- preuve cryptographique locale ou déchiffrement de données confidentielles ;
+- invention d'un solde, d'un withheld amount final, d'intérêts courus ou d'un état de compte final
+  depuis la seule instruction ;
+- migration SQL dédiée sans preuve de cardinalité ou de requêtage qui la rende nécessaire ;
+- nouveaux DEX, stratégies, trading automatisé ou acquisition historique différée.
+
+## 5. Matrices machine-readable obligatoires
+
+Créer au minimum `docs/SPL_TOKEN_2022_MATRIX.json`, vérifiée par des tests Rust. Créer une matrice
+séparée pour le registre ElGamal ou les interfaces externes si leur contrat ne peut pas être décrit
+sans mélanger des Program IDs et processors distincts.
+
+Pour chaque instruction et extension, enregistrer :
+
+- discriminant, sous-discriminant, encodage, taille minimale/exacte et règle de suffixe ;
+- état historique, courant, expérimental, désactivé ou obsolète avec preuve ;
+- comptes requis dans l'ordre, signer/writable et comptes optionnels ;
+- type d'état ciblé : Mint, Account, Multisig, TLV ou compte de programme externe ;
+- type TLV, layout, longueur, padding, répétition permise et incompatibilités ;
+- autorités, montants bruts, decimals, epochs, timestamps et clés publiques sans perte ;
+- événements décodés et projections autorisées avec propriétaire unique ;
+- support exécuteur, builder officiel ou miroir justifié, et motif stable si decode-only ;
+- support outer/inner, succès/échec et diagnostics attendus ;
+- preuves synthétiques, Localnet, Devnet, Mainnet et corpus réel ;
+- limites explicites de ce qui n'est pas prouvé.
+
+Imposer l'égalité entre matrice, surfaces compilées, déclarations de couverture, propriétaires de
+matérialisation et capacités exécuteur. Une extension publiée mais non implémentée ne peut pas
+disparaître : elle doit être classée avec une raison stable.
+
+## 6. Décodeur maximal
+
+Remplacer le scaffold `kb_decoder_spl_token_2022` par un dispatch exact du seul Program ID
+Token-2022. Le décodeur doit :
+
+- conserver Program ID, instruction path outer/inner, accounts ordonnés, doublons, flags, statut
+  committed et erreur transactionnelle ;
+- décoder maximalement les instructions de base et extension selon le processor résolu ;
+- préserver montants `u64`, decimals, epochs et timestamps sans conversion flottante ;
+- ne jamais inventer un mint lorsqu'il n'est pas dans le wire ou le contrat de comptes ;
+- distinguer données d'instruction, état de compte observé et état final non disponible ;
+- parser les TLV de façon bornée, conserver ordre/type/longueur, détecter types dupliqués,
+  tronqués, inconnus, padding invalide et incompatibilités ;
+- conserver une extension inconnue comme fait opaque borné lorsque sa structure externe reste
+  lisible, sans prétendre connaître sa sémantique ;
+- décoder les transactions échouées comme intentions structurées lorsque le wire reste lisible ;
+- refuser tout faux événement pour SPL Token classique, ATA, programme de hook, groupe, metadata,
+  registre ElGamal ou programme ZK natif ;
+- borner instructions, comptes, vecteurs, strings, TLV, données opaques et diagnostics.
+
+Les tests différentiels doivent utiliser les unpackers/builders officiels lorsqu'ils existent. Les
+miroirs locaux ne sont acceptables qu'après audit prouvant qu'une feature interdite ou l'absence de
+helper empêche l'usage direct, avec layout documenté et fixtures officielles comparées.
+
+## 7. Interfaces externes et registre ElGamal
+
+Transfer Hook, Token Group et Token Metadata Interface ne doivent pas être absorbés automatiquement
+dans le décodeur Token-2022. Auditer leurs Program IDs, discriminants et mécanismes d'interface :
+
+- une instruction exécutée par Token-2022 appartient au décodeur Token-2022 ;
+- une CPI vers un programme implémentant une interface appartient au décodeur de ce Program ID ;
+- les données TLV pointant vers un programme externe restent un lien, pas un décodage de ce
+  programme ;
+- un même fait métier ne doit pas être matérialisé à la fois depuis le parent Token-2022 et la CPI.
+
+Le registre ElGamal doit avoir un Program ID exact confirmé, un dispatch et une matrice propres. Ne
+pas le confondre avec `ZkE1Gama1Proof11111111111111111111111111111`, déjà traité comme programme
+natif de preuve. Aucun vérificateur cryptographique local n'est requis : conserver les clés,
+handles, comptes, hashes, tailles et résultats runtime prouvés.
+
+Sa présence dans la même version que Token-2022 exprime uniquement la nécessité d'auditer le lien
+fonctionnel avec les extensions confidentielles. Elle ne permet pas de partager artificiellement
+une enum, un décodeur, une matrice, un événement ou une capacité exécuteur entre les deux Program
+IDs.
+
+## 8. Matérialisation maximale sans doublon
+
+Auditer au minimum `kb_materializer_token_accounts`, `kb_materializer_admin`,
+`kb_materializer_fees`, `kb_materializer_compliance_audit`, `kb_materializer_risk`,
+`kb_materializer_lifecycle` et les matérialiseurs metadata existants avant d'en créer un nouveau.
+
+Attribuer chaque fait stable à un seul propriétaire, par exemple :
+
+- lifecycle et mutations de comptes/mints dans `token_accounts` ;
+- autorités et configuration dans `admin` ;
+- paramètres et prélèvements de transfer fee prouvés dans `fees` ;
+- garde-fous, exigences memo, hooks et opérations confidentielles dans `compliance_audit` ou
+  `risk` selon la nature factuelle ;
+- metadata/group uniquement si le wire et le Program ID audités le prouvent.
+
+Chaque projection doit être instructionnelle, commitée, idempotente et explicite sur ses limites.
+Elle ne doit pas reconstruire un snapshot, un solde, un rendement, un montant withheld global ou un
+état confidentiel final. Tester les transactions contenant parent Token-2022 et CPI externes afin
+qu'une seule projection possède chaque fait métier.
+
+## 9. Exécuteur et préflight
+
+Ne commencer `kb_executor_spl_token_2022` qu'après validation du décodeur, de la matrice et des
+projections. Développer par tranches cohérentes d'extensions, mais maintenir dans la matrice la
+surface exhaustive.
+
+Pour chaque opération actuelle officiellement constructible :
+
+- utiliser le builder officiel lorsqu'il correspond exactement à l'interface auditée ;
+- exposer intent typé, comptes exacts, ordre des metas, signataires uniques et Program IDs ;
+- conserver montants, decimals, epochs et coûts en représentations JSON sans perte ;
+- calculer le coût SOL maximal pour rent, reallocate et frais réseau ;
+- imposer simulation et dry-run par défaut ;
+- fournir une validation post-exécution adaptée à l'opération ;
+- classer decode-only toute opération historique/obsolète/désactivée avec preuve et motif stable.
+
+Le préflight stateful Localnet/Devnet doit contrôler cluster, Program IDs, owner des comptes,
+préfixe de base, TLV existants, espace requis, rent, compatibilités d'extensions, autorités,
+signataires, mint/account relations, soldes nécessaires et plafonds. Les extensions confidentielles
+ou à hook doivent vérifier tous les comptes additionnels connus sans exécuter de cryptographie ni
+faire confiance à une liste fournie par la WebView.
+
+La bibliothèque exécuteur reste universelle. Les politiques de cluster, wallet, confirmation et
+Mainnet restent dans les couches communes.
+
+## 10. Corpus et scénarios cluster
+
+Le corpus offline doit couvrir chaque instruction/extension publiée, ses formes minimales et
+limites, inconnus/tronqués/suffixés, comptes manquants/supplémentaires/dupliqués, flags invalides,
+outer/inner, succès/échec et incompatibilités TLV. Ajouter des fixtures de comptes Mint et Account
+avec zéro, une et plusieurs extensions, ordre différent, padding et types inconnus.
+
+Auditer ensuite un corpus réel Mainnet/Devnet. Les preuves doivent séparer :
+
+- interface publiée ;
+- processor source ;
+- builder constructible ;
+- programme déployé ;
+- transaction observée ;
+- simulation réussie ;
+- soumission contrôlée et postconditions.
+
+Toute dépense réelle exige comptes contrôlés, plafond explicite, confirmation et reprise bornée.
+Après `429` ou interruption, conserver les signatures déjà confirmées, vérifier leurs postconditions
+et reprendre depuis le dernier jalon exact plutôt que recréer comptes ou extensions.
+
+## 11. Tauri
+
+Réutiliser la fenêtre d'exécution Solana existante et son journal borné. Ne pas créer une WebView
+par extension. Ajouter seulement un parcours représentatif Devnet lorsque backend, préflight et
+post-validation sont déjà validés.
+
+Le panneau doit montrer profil, Token Program, mint/account, extensions sélectionnées, espace
+requis, rent, signataires, préflight, simulation, confirmation et postconditions. Les secrets,
+proof data non nécessaires et clés privées restent côté Rust. Les montants et lamports traversent
+Tauri sous forme JSON-safe sans perte. Les extensions non exposées dans l'UI restent obligatoires
+dans le décodeur et dans la bibliothèque exécuteur lorsqu'elles sont actuelles et constructibles.
+
+## 12. Contraintes du workspace
+
+Respecter Rust 2024, async-first, `kb_core::Error`/`Result`, lints workspace et headers de version.
+Aucun `anyhow`, `thiserror`, `unsafe`, `unwrap`, `expect`, panic de production, opérateur `?` dans
+les nouveaux chemins de production, `bincode` direct ou logique métier lourde dans Tauri.
+Commentaires Rust en anglais, Markdown projet en français.
+
+Conserver le style d'organisation des crates existantes. Un remaniement est autorisé seulement
+lorsqu'il est nécessaire pour le contrat Token-2022, avec justification, périmètre borné et tests
+de non-régression. Mettre `ROADMAP.md` à jour à chaque tranche et conserver `CHANGELOG.md` inchangé
+jusqu'à la validation complète de `0.4.6`.
+
+Livrer uniquement des deltas :
+
+```text
+khadhroony-bot2_v0.4.6-pre.001-delta.zip
+khadhroony-bot2_v0.4.6-pre.001-delta-fix-001.zip
+```
+
+Chaque archive contient `delta.md` non versionné avec fichiers ajoutés/modifiés, suppressions
+manuelles, dépendance aux deltas précédents et validations exécutées ou non exécutées.
+
+## 13. Critères de clôture
+
+`0.4.6` ne peut être clôturé qu'après :
+
+- matrices exhaustives et égalités compilées validées ;
+- corpus offline complet et corpus réel documenté ;
+- décodage maximal des instructions, extensions et programmes distincts inclus ;
+- matérialisation maximale sans doublon parent/CPI ni snapshot inventé ;
+- exécuteur couvrant toutes les opérations actuelles constructibles et motifs decode-only stables ;
+- préflight, simulation-first et postconditions validés ;
+- scénarios cluster contrôlés et reprise documentée ;
+- PostgreSQL réel, second replay idempotent et journal Tauri validés ;
+- régressions `0.4.5`, RPC, configuration, application et Clippy propres ;
+- versions Cargo/npm/Tauri et dépendances consommées auditées ;
+- README, ROADMAP et CHANGELOG synchronisés seulement après validation finale.
+
+Commencer par l'audit des versions réellement résolues, des sources locales et des processors.
+Publier la première matrice Token-2022 avant toute implémentation du wire, des événements ou de
+l'exécuteur.

migration/khadhroony-bot2-reference/prompts/026_v0_4_7_metaplex_token_metadata.md

@@ -0,0 +1,155 @@
+<!-- file: prompts/026_v0_4_7_metaplex_token_metadata.md -->
+<!-- version: 1 -->
+
+# Prompt de session — `0.4.7` Metaplex Token Metadata
+
+## 1. Mission
+
+Reprendre `khadhroony-bot2` après la clôture validée de `0.4.6` et implémenter la couverture maximale et strictement bornée de Metaplex Token Metadata.
+
+Metaplex Token Metadata est un programme indépendant de la Metaplex Foundation. Il complète les mints SPL Token classique et Token-2022 par des metadata externes, des éditions, collections, standards de token et configurations programmables. Il ne doit être absorbé ni par `kb_decoder_spl_token`, ni par `kb_decoder_spl_token_2022`, ni confondu avec les metadata incorporées de Token-2022 ou avec Metaplex Core.
+
+Program ID canonique à vérifier depuis les sources officielles avant code :
+
+```text
+metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
+```
+
+## 2. Base validée
+
+La base `0.4.6` comprend :
+
+- Solana Core, loaders et précompiles ;
+- SPL Memo, SPL Token classique, ATA et Token-2022 ;
+- registre ElGamal séparé du programme ZK ElGamal Proof ;
+- replay contextualisé avec `incomplete_signatures` ;
+- PostgreSQL idempotent sans doublon decode/mat ;
+- `kb_store_core` 41/41 ;
+- `kb_store_pg` 46/46 avec PostgreSQL réel ;
+- `kb_pipeline` 124/124 ;
+- `kb_app_demo` 118/118 ;
+- `cargo clippy --all-targets` propre.
+
+Lire `docs/V0_4_6_VALIDATION.md` avant toute modification.
+
+## 3. Lectures obligatoires
+
+1. `RULES.md`, `README.md`, `ROADMAP.md`, `CHANGELOG.md` et ce prompt ;
+2. `docs/DECODER_MATERIALIZATION_CONTRACTS.md`, `docs/EXECUTION_MODEL.md`, `docs/REPLAY_PIPELINE.md`, `docs/INSTRUCTION_REPLAY_CONTRACTS.md` et `docs/SOLANA_INTERFACE_DEPENDENCIES.md` ;
+3. `docs/SPL_TOKEN_MATRIX.json`, `docs/SPL_TOKEN_2022_MATRIX.json` et les contrats metadata existants ;
+4. `kb_decoder_api`, `kb_store_core`, `kb_store_pg`, `kb_pipeline`, `kb_materializer_metadata`, `kb_materializer_admin`, `kb_materializer_lifecycle`, `kb_materializer_risk` et le registre runtime de `kb_app_demo` ;
+5. les sources officielles Metaplex réellement résolues dans Cargo et les IDL/layouts publiés, sans supposer qu’un fichier local est actuel ou authentique.
+
+## 4. Audit avant code
+
+Établir d’abord une matrice machine-readable couvrant au minimum :
+
+- toutes les instructions actuellement publiées et les variantes historiques encore observables ;
+- comptes ordonnés, signer/writable, formes optionnelles et autorités ;
+- discriminateurs, arguments Borsh, suffixes et limites ;
+- PDA `metadata`, `edition`, `master edition`, `collection authority record`, `use authority record`, `token record`, `metadata delegate record` et autres comptes réellement officiels ;
+- versions de `Metadata`, `MasterEdition`, `Edition`, `EditionMarker`, `TokenRecord` et comptes auxiliaires ;
+- `TokenStandard`, créateurs, collection, uses, programmable config, authorization rules et délégations ;
+- différences entre metadata externes Metaplex, metadata Token-2022 incorporées et Metaplex Core ;
+- builders/interfaces officiels disponibles et surfaces sans builder stable.
+
+Ne commencer le décodage maximal qu’après validation de cette matrice contre les sources officielles et un corpus synthétique.
+
+## 5. Architecture attendue
+
+Créer une frontière dédiée, typiquement `kb_decoder_metaplex_token_metadata`, avec :
+
+- compatibilité `Yes` uniquement pour le Program ID Metaplex vérifié ;
+- provenance exacte du programme, de la version de layout et de l’instruction ;
+- outer/CPI, chemin d’instruction, comptes ordonnés et statut de transaction ;
+- diagnostics stables pour troncature, discriminant inconnu, comptes invalides, suffixes et variantes futures ;
+- aucune interprétation par simple ressemblance de PDA ou de discriminant sous un autre Program ID.
+
+Réutiliser les API communes existantes. Ne pas créer une infrastructure Anchor dans ce jalon : Metaplex Token Metadata n’en dépend pas. Anchor reste planifié en `0.4.18`, juste avant Meteora.
+
+## 6. Décodage instructionnel maximal
+
+Couvrir les générations actuelles et historiques réellement publiées, notamment les familles :
+
+- création/mise à jour de metadata ;
+- création d’édition et master edition ;
+- mint d’éditions ;
+- vérification/dé-vérification de créateurs et collections ;
+- collection size et collection details ;
+- uses ;
+- délégations/revocations metadata, collection, use, sale, transfer, utility, staking et programmable ;
+- burn, lock, unlock, transfer et autres opérations programmables ;
+- migration/versionnement lorsqu’officiellement défini.
+
+Chaque variante doit préserver les données brutes significatives, les autorités, les comptes et la provenance sans inventer de valeur absente du wire.
+
+## 7. Comptes et PDA
+
+Pour chaque compte :
+
+- vérifier owner/program ID avant layout ;
+- vérifier PDA et ordre exact des seeds lorsqu’une dérivation canonique existe ;
+- borner chaînes, vecteurs, options, créateurs et enums ;
+- distinguer tailles minimales, tailles exactes et comptes extensibles ;
+- conserver les variantes futures en `Unsupported` plutôt que produire une projection partielle trompeuse ;
+- corréler mint, edition, collection, token account et rule set uniquement lorsque les identités sont prouvées.
+
+## 8. Matérialisation
+
+Attribuer un propriétaire unique à chaque fait stable :
+
+- `metadata` : nom, symbole, URI, seller fee, créateurs, collection, uses, token standard, mutabilité, programmable config et provenance ;
+- `admin` : update authority, collection authority, delegates et changements d’autorité ;
+- `lifecycle` : création, mise à jour, vérification, édition, burn, lock/unlock et transitions prouvées ;
+- `risk/compliance` : royalties, mutabilité, créateurs non vérifiés, rule sets et délégations sensibles, sans dupliquer les faits metadata.
+
+Conserver simultanément metadata Metaplex externe et metadata Token-2022 incorporée. Ne jamais les fusionner silencieusement ; exposer source, autorité, slot et éventuels conflits.
+
+## 9. JSON externe référencé par URI
+
+Le fetch HTTP/IPFS/Arweave doit rester optionnel, borné et séparé du replay canonique on-chain :
+
+- timeout, taille maximale, content type et redirections bornés ;
+- cache/provenance/hash explicites ;
+- aucune dépendance du statut de décodage on-chain à la disponibilité du contenu externe ;
+- aucune confiance implicite dans le JSON distant ;
+- pas de SSRF ni d’accès arbitraire aux réseaux locaux.
+
+Une première version peut documenter et réserver ce contrat sans activer le fetch si son isolation n’est pas suffisamment prouvée.
+
+## 10. Exécution
+
+N’ajouter des builders/exécuteurs qu’après validation exacte des interfaces officielles, comptes, autorités, coûts et préconditions. Toute opération doit rester simulation-first, dry-run par défaut, signataires exacts et plafond de dépense explicite.
+
+Les opérations destructives ou sensibles — burn, update authority, verify/unverify, delegate/revoke, lock/unlock — exigent une confirmation opérateur dédiée et des postconditions stateful.
+
+## 11. Corpus et validations
+
+Ajouter au minimum :
+
+- corpus synthétique pour chaque famille d’instruction et de compte ;
+- fixtures réelles Mainnet avec tokens fongibles, NFT, SFT, collections et programmable NFT ;
+- outer et CPI ;
+- transactions réussies et échouées ;
+- mauvais Program ID, mauvais owner, mauvais PDA, comptes manquants/dupliqués, payloads tronqués, suffixes et discriminants inconnus ;
+- conflits entre metadata Metaplex externe et Token-2022 incorporée ;
+- replay PostgreSQL idempotent, absence de doublons decode/mat et validation de `incomplete_signatures` ;
+- démo `kb_app_demo` pour consulter les observations et projections pertinentes.
+
+## 12. Documentation et clôture
+
+Mettre à jour :
+
+- `README.md` ;
+- `ROADMAP.md` ;
+- `CHANGELOG.md` seulement après validation ;
+- `docs/SOLANA_INTERFACE_DEPENDENCIES.md` ;
+- une matrice Metaplex Token Metadata dédiée ;
+- les README des crates modifiées ;
+- le prompt de la session suivante `0.4.8 — Metaplex Core`.
+
+La clôture exige les tests ciblés, PostgreSQL réel, replay idempotent, tests Tauri si l’UI est modifiée et `cargo clippy --all-targets` propre.
+
+## 13. Livraisons
+
+Après la base initiale, livrer uniquement des ZIP delta avec `delta.md` et `manifest.sha256`. Les correctifs d’une même préversion conservent son numéro et utilisent `-delta-fix-XXX.zip`, avec une numérotation recommençant à `fix-001` pour chaque nouvelle préversion.

migration/khadhroony-bot2-reference/prompts/README.md

@@ -0,0 +1,51 @@
+<!-- file: prompts/README.md -->
+<!-- version: 19 -->
+
+# Prompts de session
+
+Ce dossier contient les prompts utilisés pour ouvrir ou reprendre des sessions d'assistance par version.
+
+## Règles
+
+- Les noms de fichiers doivent être en anglais, sans espaces, accents ni caractères spéciaux inutiles.
+- Les fichiers restent en Markdown et sont rédigés en français.
+- Un prompt doit décrire le contexte, les règles applicables, les objectifs, les fichiers à lire, les interdictions et les validations attendues.
+- Les prompts ne remplacent pas `ROADMAP.md` et ne doivent pas modifier `CHANGELOG.md` avant validation.
+- Les prompts doivent rappeler le format du zip delta attendu.
+
+## Format de livraison attendu
+
+- Workspace ou plusieurs modules : `khadhroony-bot2_vX.Y.Z-pre.abc-delta.zip`.
+- Un seul module Rust : `kb_modulename_vX.Y.Z-pre.abc-delta.zip`.
+- Correctif d'un delta déjà livré : conserver `pre.abc` et utiliser `-delta-fix-001.zip`, puis `-fix-002.zip`; ne pas incrémenter `abc` pour une réparation.
+- Chaque zip delta ou correctif doit contenir `delta.md` non versionné.
+- `delta.md` doit lister les fichiers ajoutés, modifiés, à supprimer manuellement, les dépendances d'application du correctif, et les validations exécutées ou non exécutées.
+
+## Prompts actuels
+
+- `001_version_session_template.md` : modèle générique.
+- `002_program_registry_and_naming_audit.md` : audit des noms, aliases et registres.
+- `003_v0_1_logging_config_profiles.md` : logging et configuration multi-profils.
+- `004_v0_2_sql_storage_materialization.md` : conventions storage, PostgreSQL et contrats DB historiques.
+- `005_v0_3_rpc_ingestion_ws.md` : ancien prompt d’ingestion, conservé uniquement comme historique.
+- `006_v0_4_wallet_execution_demo.md` : ancien phasage wallet, désormais reporté à `0.11.x`.
+- `007_v0_5_core_decoders_listeners.md` : ancien phasage décodeurs, désormais remplacé par `0.4.x` à `0.10.x`.
+- `008_v0_6_priority_dex_router_surfaces.md` : ancien phasage surfaces, conservé comme source historique.
+- `009_v0_2_1_store_core_contracts.md` : contrats backend-agnostiques `kb_store_core` pour `0.2.1`.
+- `010_v0_2_2_postgres_connection_health_migrations.md` : connexion PostgreSQL, pool, healthcheck et stratégie migrations.
+- `011_v0_2_3_raw_store_minimal.md` : premières tables raw historiques.
+- `012_v0_2_4_core_store_minimal.md` : tables core Solana minimales et repositories historiques.
+- `013_v0_2_5_db_diagnostics_tauri.md` : diagnostics DB PostgreSQL dans `kb_app_demo`.
+- `014_v0_3_0_agave_local_research.md` : prompt historique du cadrage Agave local validé puis abandonné comme axe actif.
+- `015_v0_3_1_canonical_store_migration.md` : prompt historique de la transition vers la transaction canonique et les observations légères.
+- `016_v0_3_2_canonical_transaction_contract.md` : prompt historique de l’implémentation du contrat canonique et de l’adaptateur HTTP.
+- `017_v0_3_3_http_backfill_free_tier.md` : prompt historique du backfill HTTP paginé et de `demo_backfill`, validé et clôturé.
+- `018_v0_3_4_canonical_to_core_extraction.md` : prompt historique validé et clôturé pour l’extraction transactionnelle, le replay core et la fondation `0.3.x`.
+- `019_v0_4_0_decoder_infrastructure.md` : prompt historique validé pour les contrats, le dispatch, le ledger et le replay communs aux décodeurs et matérialiseurs.
+- `020_v0_4_1_native_solana_programs.md` : prompt historique validé pour le décodage et les matérialisations natives Solana.
+- `021_v0_4_2_executor_solana_core.md` : prompt historique validé pour l’infrastructure d’exécution et `kb_executor_solana_core`.
+- `022_v0_4_3_spl_memo.md` : prompt historique validé pour le décodeur, la matérialisation et l’exécuteur SPL Memo v1/v3/v4.
+- `023_v0_4_4_spl_token.md` : prompt historique validé pour le décodeur maximal, les matérialisations et l’exécuteur SPL Token classique.
+- `024_v0_4_5_spl_associated_token_account.md` : prompt historique validé pour le décodeur, les matérialisations et l'exécuteur SPL Associated Token Account.
+- `025_v0_4_6_spl_token_2022.md` : prompt historique validé pour Token-2022, ses extensions, ses interfaces externes et le registre ElGamal distinct.
+- `026_v0_4_7_metaplex_token_metadata.md` : prompt actif pour Metaplex Token Metadata, ses comptes, PDA, NFT/collections, metadata externes et provenance.