<!-- file: ROADMAP.md -->

# khadhroony-bobobot — Roadmap

## 1. Objet du projet

`khadhroony-bobobot` est un workspace Rust destiné à la détection, l’observation, l’analyse de patterns et, à terme, à l’exécution semi-automatisée d’achats/ventes de tokens sur la blockchain Solana.

Le projet vise en priorité :

- la détection de création de tokens et de paires sur différents DEX,
- la réception et le tri des événements on-chain et RPC,
- la collecte de métriques utiles au filtrage,
- l’analyse statistique et comportementale des patterns,
- la préparation d’une couche wallet puis swap/trading.

## 2. Principes d’architecture

### 2.1. Structure générale

Le workspace est organisé autour de deux sous-crates principales :

- `kb_lib` : bibliothèque métier, réseau, config, tracing, stockage, analyse et logique applicative.
- `kb_demo_app` : application Demo Tauri V2 avec frontend TypeScript, chargée de l’interface et de la délégation vers `kb_lib`.

### 2.2. Contraintes de code

Le socle du projet doit respecter les contraintes suivantes :

- Rust 2024.
- Aucun fichier `mod.rs`.
- Exposition centralisée à la racine des crates via `lib.rs` ou `main.rs`.
- Pas d’usage de `anyhow` ni `thiserror`.
- Pas d’usage de `?`, `unwrap`, `expect` dans le code applicatif.
- Utilisation de `match`, `if let Err`, `let Err = ... else`.
- Documentation Rust obligatoire sur les éléments publics.
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]` activés et respectés.
- Pas de `use` pour les types/fonctions externes, sauf pour les traits.
- Tests unitaires importants et maintenus à chaque étape.

### 2.3. Règles de responsabilité

- `kb_demo_app` ne doit pas embarquer la logique métier réseau ou Solana.
- `kb_demo_app` doit seulement orchestrer l’UI, les commandes Tauri et les appels vers `kb_lib`.
- `kb_lib` doit porter les clients réseau, la config, le tracing, les types partagés, les registres et la logique métier.

## 3. Vision fonctionnelle

Le projet doit pouvoir évoluer progressivement vers les capacités suivantes :

1. Connexion à plusieurs endpoints HTTP / WS RPC Solana.
2. Répartition des rôles par endpoint.
3. Réception des notifications de slots, comptes, programmes, logs, signatures, blocs.
4. Détection de créations de tokens, pools et paires sur plusieurs DEX.
5. Collecte de métriques : liquidité, market cap, volume, prix, activité.
6. Persistance locale dans SQLite, puis évolution possible vers PostgreSQL.
7. Analyse de patterns et filtrage des tokens non tradables.
8. Gestion de wallets Solana.
9. Préparation puis exécution semi-automatisée de swaps/trading.
10. Intégration future de gRPC Yellowstone.

## 4. Configuration cible

La configuration applicative est stockée dans un fichier `config.json`.

### 4.1. Points à couvrir dans la configuration

Le fichier doit permettre de configurer :

- les endpoints HTTP,
- les endpoints WebSocket,
- un nom logique par endpoint,
- le rôle ou les tâches affectées à chaque endpoint,
- les limites de débit par endpoint,
- les options spécifiques aux providers publics ou privés,
- les chemins de stockage local,
- le répertoire des wallets Solana,
- le tracing et ses formats,
- la stratégie de reconnexion,
- les paramètres de base de données,
- les options d’UI persistées plus tard.

### 4.2. Exemple de catégories attendues

- `app`
- `logging`
- `database`
- `wallets`
- `network`
- `solana`
- `http_endpoints`
- `ws_endpoints`

### 4.3. Exigences particulières

Chaque endpoint doit pouvoir porter sa propre configuration, par exemple :

- nom logique,
- URL,
- provider,
- présence ou non d’une clé API,
- variable d’environnement pour clé API,
- plafond de requêtes,
- burst,
- timeout,
- usages autorisés,
- rôle principal.

Exemples de rôles futurs :

- `slot_notifications`
- `program_subscriptions`
- `account_subscriptions`
- `logs_subscriptions`
- `http_queries`
- `fallback`

## 5. Tracing cible

Le tracing est centralisé dans `kb_lib`.

### 5.1. Exigences initiales

- sortie console paramétrable,
- sortie fichier paramétrable,
- niveau de log configurable,
- format du message configurable,
- format du temps configurable,
- ANSI console activable/désactivable,
- fonctionnement compatible tests,
- séparation claire entre initialisation et usage.

### 5.2. Objectifs complémentaires

- pouvoir distinguer les logs du transport WS,
- distinguer les logs HTTP,
- distinguer les logs Tauri/UI,
- distinguer les logs DB,
- préparer une traçabilité par endpoint et par client.

## 6. Phasage par versions

### 6.001. Version `0.0.2` — Socle conforme
Objectif : corriger le squelette et poser la base de travail.

Réalisé :

- correction de `kb_lib/src/lib.rs`,
- création de `kb_lib::Error`,
- création de `kb_lib::Config`,
- création de `kb_lib::init_tracing`,
- création des constantes Solana officielles,
- préparation des modules `ws_client` et `http_client`,
- remise de `kb_demo_app/src/lib.rs` en conformité,
- documentation de `kb_demo_app/src/splash.rs`,
- UI Tauri minimale.

### 6.002. Version `0.1.x` — Transport WebSocket générique
Objectif : construire un vrai `WsClient` asynchrone clonable.

Réalisé :

- `connect`, `disconnect`, `connection_state`,
- flux de lecture séparé du flux d’écriture,
- identifiant incrémental interne par client,
- canal sortant borné,
- émission d’événements internes,
- support de l’arrêt propre,
- fermeture avec timeout,
- tests offline avec serveur mock.

### 6.003. Version `0.1.1` — Intégration Tauri minimale du `WsClient`
Objectif : valider le transport via l’application desktop.

Réalisé :

- intégration minimale de `WsClient` dans `kb_demo_app`,
- boutons start/stop,
- zone de logs,
- validation du flux `frontend -> tauri -> kb_lib -> frontend`.

### 6.004. Version `0.2.0` — Couche JSON-RPC WS Solana
Objectif : séparer clairement transport, réponses RPC et notifications.

Réalisé :

- enveloppes JSON-RPC 2.0,
- gestion des `request_id`,
- parsing des réponses et erreurs,
- parsing des notifications,
- premiers helpers JSON-RPC sur `WsClient`.

### 6.005. Version `0.3.0` — Registre subscriptions / notifications
Objectif : fiabiliser la gestion des subscriptions.

Réalisé :

- stockage des subscriptions actives,
- mapping entre requête de subscribe et `subscription_id` serveur,
- unsubscribe propre avant fermeture,
- timeout d’attente sur unsubscribe,
- purge locale si nécessaire,
- routage séparé des notifications.

### 6.006. Version `0.3.1` — Helpers subscribe/unsubscribe WebSocket
Objectif : ajouter les helpers haut niveau correspondant aux principales méthodes PubSub Solana.

Réalisé :

- helpers pour `account`, `block`, `logs`, `program`, `root`, `signature`, `slot`, `slotsUpdates`, `vote`,
- helpers d’unsubscribe correspondants,
- premiers tests de validation des noms de méthodes.

### 6.007. Version `0.3.2` — Helpers typed et notifications typed
Objectif : s’appuyer principalement sur `solana-rpc-client-api` pour typer les subscribe et les notifications.

Réalisé :

- helpers typed pour `account`, `block`, `logs`, `program`, `signature`,
- parsing typed des notifications,
- base de travail pour réduire l’usage direct de `serde_json::Value`.

### 6.008. Version `0.3.3` — Distinction API typed / raw
Objectif : clarifier l’API publique de `WsClient`.

Réalisé :

- suffixe `_raw` sur les helpers raw,
- conservation des helpers typed comme interface plus propre,
- préparation d’une hiérarchie API plus explicite.

### 6.009. Version `0.3.4` — Fenêtre `Demo Ws` dans `kb_demo_app`
Objectif : tester manuellement les souscriptions live dans une fenêtre dédiée.

Réalisé :

- fenêtre séparée `demo_ws`,
- ouverture depuis la fenêtre principale,
- connexion/déconnexion d’un client de démo,
- test de souscriptions live,
- affichage des événements raw et typed,
- premiers tests réels sur `wss://api.mainnet.solana.com`.

### 6.010. Version `0.3.5` — Stabilisation de `Demo Ws`
Objectif : rendre la fenêtre de démonstration robuste sous flux élevé et cohérente avec la configuration.

Réalisé :

- lire correctement les endpoints activés depuis la config et refléter les URLs résolues avec `api_key_env_var`,
- améliorer la sélection réelle des endpoints affichés et utilisables,
- ajouter du throttling / rate limiting de l’affichage UI sous fort débit,
- limiter ou résumer les événements affichés côté fenêtre,
- conserver l’intégralité des traces côté `tracing`,
- éviter le gel de la fenêtre sur `logsSubscribe` et `programSubscribe`,
- conserver des compteurs et états UI exploitables,
- mieux gérer les fermetures/ralentissements d’endpoints publics.

### 6.011. Version `0.4.x` — Transport HTTP générique et helpers RPC

Objectif : construire un `HttpClient` clonable, limité et extensible, puis ajouter les premiers helpers HTTP Solana.

### 6.012. Version `0.4.0` — Socle `HttpClient`
Réalisé :

- client `reqwest` asynchrone clonable,
- résolution d’URL avec support de `api_key_env_var`,
- limiteur local req/sec,
- burst configurable,
- délais configurables,
- profils par endpoint,
- abstraction JSON-RPC HTTP générique,
- premiers appels de validation Solana.

Livrables :

- `HttpClient`,
- enveloppes JSON-RPC HTTP,
- premiers appels :
  - `getHealth`
  - `getVersion`
  - `getSlot`

### 6.013. Version `0.4.1` — Helpers HTTP Solana
Réalisé :

- ajouter des helpers HTTP haut niveau comme pour le client WS,
- distinguer helpers raw et helpers typed quand cela est pertinent,
- couvrir les premières méthodes utiles du RPC HTTP Solana,
- conserver `HttpClient` comme couche générique réutilisable.

### 6.014. Version `0.4.2` — Politique HTTP avancée
Réalisé :

- préparer un état de pause avant envoi pour un endpoint HTTP,
- préparer plusieurs quotas par famille de méthodes,
- distinguer quota RPC général et quota `sendTransaction`,
- préparer un futur pool d’endpoints HTTP et l’arbitrage entre eux.

### 6.015. Version `0.4.3` — Pool d’endpoints HTTP
Réalisé :

- ajouter un pool d’`HttpClient`,
- sélectionner un endpoint selon le rôle demandé,
- ignorer les endpoints `Paused` ou `Disabled`,
- préparer une rotation simple entre endpoints actifs,
- prendre en compte la classe de méthode HTTP,
- préparer le routage multi-RPC et la limitation de concurrence par endpoint.

### 6.016. Version `0.4.4` — Démo HTTP dans `kb_demo_app`
Réalisé :

- ajout d’une fenêtre `Demo Http`,
- ouverture depuis la fenêtre principale,
- exécution manuelle de méthodes HTTP via le pool d’endpoints,
- affichage des réponses JSON-RPC HTTP et des erreurs associées,
- affichage de l’état du pool HTTP et des statuts des endpoints,
- alignement visuel de la fenêtre sur le gabarit `Demo Ws`,
- amélioration des presets UI, copie de réponse et bascule pretty/raw.

### 6.017. Version `0.5.x` — Base de données SQLite
Objectif : poser la persistance locale avec une organisation préparée dès le départ à une future évolution vers PostgreSQL ou un autre backend.

### 6.018. Version `0.5.0` — Socle SQLite
Réalisé :

- configuration DB dans `config.json`,
- ouverture/validation SQLite,
- façade `kb_lib::Database`,
- premier schéma technique,
- table `k_sol_db_metadata`,
- séparation `db/entities`, `db/dtos`, `db/queries`, `db/types`.

### 6.019. Version `0.5.1` — Premières tables métier de stockage local
Réalisé :

- ajout des tables de référence pour les endpoints connus HTTP/WS,
- ajout des tables techniques pour les événements runtime locaux,
- mise en place des `entities`, `dtos`, `queries` et `types` associés,
- préparation du stockage local des endpoints HTTP/WS connus et de leur état utile.

### 6.020. Version `0.5.2` — Stockage des tokens observés
Réalisé :

- ajout de la table `k_sol_observed_tokens`,
- stockage minimal des mints, symboles, noms, statuts et dates d’observation,
- ajout du `token_program`,
- préparation des relations futures avec pools, paires et événements on-chain,
- conservation d’unicité locale par mint sans duplication par endpoint.

### 6.021. Version `0.5.3` — Événements et signaux locaux
Réalisé :

- conservation des événements runtime techniques via `k_sol_db_runtime_events`,
- ajout des observations on-chain brutes via `k_sol_onchain_observations`,
- ajout des signaux d’analyse via `k_sol_analysis_signals`,
- distinction explicite entre événements runtime, observations on-chain et événements métier,
- préparation de la traçabilité de provenance par type de source et endpoint, sans remettre en cause l’unicité locale d’un token par mint.

### 6.022. Version `0.5.4` — Modèle métier normalisé initial
Réalisé :

- ajouter les tables de référence métier pour les DEX, tokens, pools et paires,
- distinguer clairement objets de référence et événements d’activité,
- préparer les relations entre tokens, pools, paires et listings,
- éviter que la détection technique `0.6.x` écrive directement dans des tables trop brutes ou ambiguës.

### 6.023. Version `0.5.5` — Activité métier normalisée
Réalisé :

- ajout des tables de swaps,
- ajout des événements de liquidité,
- ajout des événements de mint et burn utiles au suivi des tokens,
- préparation de l’historique métier nécessaire avant l’arrivée des connecteurs DEX complets.

### 6.024. Version `0.5.6` — Consolidation de la couche stockage
Objectif : stabiliser le schéma avant la détection technique réelle.

À faire :

- conserver l’abstraction du backend dès le départ,
- limiter la dépendance directe au SQL concret aux modules `queries`,
- garder les conversions explicites entre entités DB et DTOs applicatifs,
- durcir les relations, contraintes et index utiles,
- préparer une future compatibilité PostgreSQL sans casser l’organisation générale.

### 6.025. Version `0.6.0` — Pipeline de détection technique
Objectif : relier les connecteurs RPC à la couche de stockage technique et métier.

À faire :

- ajouter une façade de persistance pour les observations et signaux issus des connecteurs,
- préparer l’enregistrement des candidats tokens détectés depuis les sources RPC,
- éviter que les futurs watchers RPC écrivent directement dans la DB sans couche intermédiaire,
- préparer les prochaines étapes de détection technique on-chain / RPC.

### 6.026. Version `0.6.1` — Détection technique RPC
Réalisé :

- ajout d’un bridge `Solana WS notification -> pipeline de détection`,
- persistance des notifications WS utiles comme observations on-chain normalisées,
- génération d’un candidat token quand une `programNotification` expose un mint SPL / Token-2022 en JSON parsé,
- préparation du branchement futur des watchers et règles RPC réelles sur une façade de détection unique.

### 6.027. Version `0.6.2` — Branchement `WsClient` vers la détection
Réalisé :

- ajouter un relais interne de notifications WS vers la couche de détection,
- permettre à `WsClient` de forwarder les `JsonRpcWsNotification` vers un worker dédié,
- conserver le découplage entre transport WS et logique de détection,
- éviter de bloquer la boucle de lecture WS si la détection est lente.

### 6.028. Version `0.6.3` — Enrichissement des notifications WS utiles
Réalisé :

- enrichir `accountNotification`, `logsNotification` et `signatureNotification`,
- mieux extraire slot, pubkey, signature, owner, parsed account type et clés pertinentes,
- produire des observations plus précises et plus homogènes,
- préparer les règles de détection techniques réelles.

### 6.029. Version `0.6.4` — Premières règles de détection technique
Réalisé :

- détection des premiers candidats pools/listings techniques depuis `programNotification`,
- appui sur les DEX connus en base via `program_id` / `router_program_id`,
- enregistrement des pools candidats et de leur listing initial sans parsing DEX complet,
- alimentation conjointe des observations techniques, signaux d’analyse et tables métier normalisées,
- maintien d’une logique encore indépendante des connecteurs DEX `0.7.x`.

### 6.030. Version `0.6.5` — Orchestration multi-clients WebSocket
Réalisé :

- introduction d’une abstraction `ws_manager.rs` pour piloter plusieurs `WsClient`,
- construction des clients WS activés depuis la configuration d’endpoints,
- démarrage et arrêt centralisés par endpoint ou globalement,
- republication d’un flux unifié de `WsEvent` pour l’ensemble des clients gérés,
- branchement optionnel du relais de détection WS sur tous les clients orchestrés,
- préparation des futures politiques de répartition, supervision et reconnexion.

### 6.031. Version `0.6.6` — Démo légère `WsManager` dans `kb_demo_app`
Réalisé :

- ajout d’une fenêtre `Demo Ws Manager` dans `kb_demo_app`,
- ouverture depuis la fenêtre principale,
- affichage du snapshot consolidé du `WsManager`,
- pilotage des endpoints WS gérés via `start/stop all` et `start/stop role`,
- visualisation du flux unifié de `WsEvent`,
- validation UI du branchement centralisé du relais de détection,
- amélioration des messages de log UI pour les actions idempotentes déjà démarrées ou déjà arrêtées.

### 6.032. Version `0.7.0` — Résolution transactionnelle orientée DEX
Réalisé :

- introduction d’une file de résolution transactionnelle alimentée par les signatures issues des flux WS utiles,
- corrélation initiale des `logsNotification` et `signatureNotification` avec des appels `getTransaction`,
- utilisation du pool HTTP existant pour enrichir les signaux détectés côté WS,
- persistance des résolutions transactionnelles dans `k_sol_onchain_observations` et `k_sol_analysis_signals`,
- préparation du futur modèle transactionnel enrichi sans bloquer les flux temps réel.

### 6.033. Version `0.7.1` — Modèle transactionnel Solana enrichi
Réalisé :

- ajout des tables techniques `k_sol_chain_slots`, `k_sol_chain_transactions` et `k_sol_chain_instructions`,
- distinction claire entre slot, transaction résolue et instructions normalisées,
- support des instructions principales et inner instructions,
- ajout des entités, DTOs et requêtes associées,
- ajout d’un service de projection pour transformer une transaction JSON-RPC résolue en modèle transactionnel interne,
- ajout des tests de roundtrip et de projection.

### 6.034. Version `0.7.2` — Décodeurs DEX spécifiques par programme et version
Réalisé :

- ajout d’un premier décodeur transactionnel spécifique Raydium AmmV4 / initialize2,
- lecture combinée du `transaction_json` et des instructions projetées,
- extraction des comptes utiles à l’initialisation du pool,
- persistance des événements DEX décodés dans une table dédiée,
- émission d’observations et de signaux dérivés du décodage DEX,
- branchement automatique du décodage DEX depuis le pipeline de résolution transactionnelle,
- préparation de la future détection métier pool / pair / listing.

### 6.035. Version `0.7.3` — Détection des nouveaux pools et paires via logs + transaction
Réalisé :

- transformation des événements DEX décodés en objets métier pool / pair / listing,
- alimentation de `k_sol_pools`, `k_sol_pairs`, `k_sol_pool_tokens` et `k_sol_pool_listings`,
- première détection métier pour Raydium AmmV4 / initialize2,
- branchement automatique de la détection métier après résolution, projection et décodage DEX,
- émission de signaux dédiés pour `new_pool`, `new_pair` et `first_listing_seen`,
- garantie d’idempotence sur une même transaction déjà traitée.

### 6.036. Version `0.7.4` — Connecteurs DEX v1, vague 1
Réalisé :

- ajout du décodeur `Pump.fun` pour les créations `create_v2`,
- ajout du décodeur `PumpSwap` pour les trades `buy / sell`,
- intégration des nouveaux décodeurs dans le pipeline générique `dex_decode`,
- ajout de la détection métier `Pump.fun` vers `token / pool / pair / listing`,
- maintien de `PumpSwap` au niveau décodage en attendant un mapping transactionnel plus riche,
- préparation de l’extension vers `Meteora`, `Meteora DBC` et `LaunchLab`.

### 6.037. Version `0.7.5` — Connecteurs DEX v1, vague 2
Réalisé :

- enrichissement du décodeur `PumpSwap` avec extraction des mints et du `pool_v2`,
- persistance des événements `PumpSwap` enrichis dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `PumpSwap` vers `pool / pair / listing`,
- émission des signaux dédiés `new_pool`, `new_pair` et `first_listing_seen`,
- garantie d’idempotence sur une même transaction déjà traitée,
- préparation du lot suivant pour `Meteora`, `Meteora DBC` et `LaunchLab`.

### 6.038. Version `0.7.6` — Connecteurs DEX v1, vague 3
Réalisé :

- ajout du premier décodeur `Meteora DBC`,
- prise en charge initiale des événements `create_pool` et `swap`,
- persistance des événements `Meteora DBC` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `Meteora DBC` vers `pool / pair / listing`,
- émission des signaux dédiés `new_pool`, `new_pair` et `first_listing_seen`,
- préparation du lot suivant pour `Meteora DAMM v2`, `Meteora DAMM v1` et `LaunchLab / Fun Launch`.

### 6.039. Version `0.7.7` — Meteora DAMM v2
Réalisé :

- ajout du premier décodeur `Meteora DAMM v2`,
- prise en charge initiale des événements de création de pool via `initialize_pool`, `initialize_pool_with_dynamic_config` et `initialize_customizable_pool`,
- prise en charge initiale des swaps via `swap` et `swap2`,
- persistance des événements `Meteora DAMM v2` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `Meteora DAMM v2` vers `pool / pair / listing`,
- préparation du rattachement futur entre `Meteora DBC` et `Meteora DAMM v2`.

### 6.040. Version `0.7.8` — Meteora DAMM v1
Réalisé :

- ajout du premier décodeur `Meteora DAMM v1`,
- prise en charge initiale des événements de création de pool via `initialize_pool` et `initialize_pool_with_config`,
- prise en charge initiale des swaps via `swap`,
- persistance des événements `Meteora DAMM v1` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `Meteora DAMM v1` vers `pool / pair / listing`,
- préparation du rattachement futur entre `Meteora DBC` et `Meteora DAMM v1`.

### 6.041. Version `0.7.9` — Launch origins / Fun Launch
Réalisé :

- ajout d’un registre des surfaces de lancement,
- ajout d’un registre de clés observables par surface de lancement,
- ajout d’une attribution entre événements/pools détectés et surfaces connues,
- premier support de `Meteora Fun Launch` comme surface d’origine au-dessus de `Meteora DBC`,
- branchement automatique de l’attribution depuis le pipeline de résolution transactionnelle,
- conservation d’une séparation stricte entre protocole on-chain et origine de lancement.

### 6.042. Version `0.7.10` — Orca / Whirlpools
Réalisé :

- ajout du premier décodeur `Orca Whirlpools`,
- prise en charge initiale des événements de création de pool via `initialize_pool` et `initialize_pool_v2`,
- prise en charge initiale des swaps via `swap` et `swap_v2`,
- persistance des événements `Orca Whirlpools` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `Orca Whirlpools` vers `pool / pair / listing`,
- utilisation de `PoolKind::Clmm` pour refléter la nature concentrée de `Whirlpools`.

### 6.043. Version `0.7.11` — FluxBeam
Réalisé :

- ajout du premier décodeur `FluxBeam`,
- prise en charge initiale des événements de création de pool via un premier décodage `create_pool / initialize_pool`,
- prise en charge initiale des swaps via `swap`,
- persistance des événements `FluxBeam` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `FluxBeam` vers `pool / pair / listing`,
- conservation d’un premier décodage heuristique à raffiner ultérieurement avec des transactions FluxBeam réelles.

### 6.044. Version `0.7.12` — DexLab
Réalisé :

- ajout du premier décodeur `DexLab Swap/Pool`,
- prise en charge initiale des événements de création de pool via un premier décodage `create_pool / initialize_pool`,
- prise en charge initiale des swaps via `swap`,
- persistance des événements `DexLab` dans `k_sol_dex_decoded_events`,
- ajout de la détection métier `DexLab` vers `pool / pair / listing`,
- conservation d’une séparation entre pool DexLab natif et éventuel `OpenBook Market ID` créé ensuite.

### 6.045. Version `0.7.13` — Bags / Moonit comme origines de lancement
Réalisé :

- extension de la couche `launch origins` à `Bags` et `Moonit`,
- ajout d’un enregistrement programmatique des mappings `Bags` à partir des champs `tokenMint`, `dbcConfigKey`, `dbcPoolKey` et `dammV2PoolKey`,
- prise en charge de l’attribution `Bags` par matching exact sur `config_account`, `pool_account` et `token_mint`,
- prise en charge de l’attribution `Moonit` par détection automatique des token mints se terminant par `moon`,
- conservation d’une séparation stricte entre origine de lancement et protocole on-chain.

### 6.046. Version `0.7.14` — Consolidation multi-DEX
Réalisé :

- ajout d’une couche commune `pool origins` pour enregistrer la première signature vue par le modèle pour chaque pool détecté,
- rattachement d’un pool à son `decoded_event`, à son `pair`, à son `pool_listing` et à son éventuelle `launch_attribution`,
- amélioration de la traçabilité inter-protocoles sans modifier les connecteurs DEX déjà validés,
- conservation d’une logique idempotente avec mise à jour douce des liens `pair / listing / launch attribution`,
- préparation de la future couche analytique sur une base multi-DEX plus cohérente.

### 6.047. Version `0.7.15` — Wallets, holdings et participants observés
Réalisé :

- ajout d’une première couche `wallets` pour les adresses observées dans le pipeline,
- ajout d’une première couche `wallet participations` pour rattacher une adresse à une transaction, un decoded event, un pool et un pair,
- extraction des rôles observés depuis les payloads décodés (`creator`, `payer`, `owner`, `user`),
- branchement automatique depuis le pipeline de résolution transactionnelle,
- report des holdings à l’étape suivante afin de conserver une séparation nette entre acteurs observés et balances observées.

### 6.048. Version `0.7.16` — Séries de prix, volumes et agrégats DEX
Réalisé :

- ajout d’une première table `trade events` pour normaliser les swaps observés,
- ajout d’une première table `pair metrics` pour agréger les swaps par paire,
- prise en charge des compteurs `trade_count`, `buy_count`, `sell_count`,
- prise en charge optionnelle des volumes bruts `base` / `quote` et du dernier prix dérivé `quote_per_base`,
- branchement automatique dans le pipeline de résolution transactionnelle,
- conservation d’un modèle simple et idempotent en préparation de futures candles / séries temporelles.

### 6.049. Version `0.7.17` — Renforcement temps réel WS hybride
Réalisé :

- conservation de `logsSubscribe` comme source canonique de signatures candidates,
- ajout d’une collecte de cibles `programSubscribe` à partir des DEX actifs connus,
- ajout d’une collecte de cibles `accountSubscribe` à partir des pools actifs connus,
- ajout d’une couche d’observations techniques WS hybrides pour `logs / program / account`,
- ajout d’une première déduplication en mémoire des notifications techniques reçues en parallèle,
- ajout d’une façade runtime pour exposer ce comportement au branchement `ws_manager`.

### 6.050. Version `0.7.18` — Backfill historique ciblé par token
Réalisé :

- ajout d’un premier service de backfill ciblé par `token_mint`,
- récupération des signatures historiques via `getSignaturesForAddress`,
- résolution des transactions pertinentes via `getTransaction`,
- relecture du pipeline interne pour reconstruire transactions, décodage DEX, détection métier, origins, wallets et trade metrics,
- ajout d’une seconde passe sur les pools découverts pour le token afin de récupérer des signatures supplémentaires liées à l’activité du pool,
- conservation d’un périmètre ciblé sur des tokens encore actifs au lieu d’un scan exhaustif de la blockchain.

### 6.051. Version `0.7.19` — Holdings observés
Réalisé :

- ajout d’une première table `wallet holdings` pour agréger les couples `wallet/token` observés,
- rattachement des holdings observés à la dernière transaction, au dernier decoded event, au dernier pool et au dernier pair connus,
- conservation d’un champ `balance_raw` optionnel sans prétendre encore reconstruire un portefeuille complet,
- alimentation automatique à partir des événements DEX déjà décodés et des wallets déjà observés,
- branchement automatique dans le pipeline de résolution transactionnelle.

### 6.052. Version `0.7.20` — Candles / OHLCV
Réalisé :

- ajout d’une première table `pair candles` pour matérialiser les agrégats OHLCV par paire,
- stockage en base des timeframes usuels (`1m`, `5m`, `15m`, `1h`),
- conservation de `trade events` comme source brute de vérité,
- ajout d’un service de régénération à la demande pour un timeframe arbitraire,
- possibilité de choisir dynamiquement le timeframe lors d’une requête analytique,
- branchement automatique dans le pipeline de résolution transactionnelle pour maintenir les candles matérialisées à jour.

### 6.053. Version `0.7.21` — Signaux analytiques plus riches
Réalisé :

- ajout d’une première table `pair analytic signals` dédiée aux signaux dérivés par paire,
- prise en charge initiale des signaux `first_trade_seen`, `trade_burst_60s`, `buy_sell_imbalance_60s`, `price_jump_up_60s`, `price_jump_down_60s` et `volume_spike_60s`,
- calcul des signaux à partir des `pair metrics`, `pair candles` et `trade events`,
- persistance idempotente des signaux par paire et par bucket,
- branchement automatique dans le pipeline de résolution transactionnelle.

### 6.054. Version `0.7.22` — `kb_demo_app` : inspection et tests du pipeline `0.7.x`
Réalisé :

- ajout d’une fenêtre dédiée `Demo Pipeline` dans `kb_demo_app`,
- inspection du pipeline persistant par `signature`,
- inspection du pipeline persistant par `token mint`,
- inspection du pipeline persistant par `pair id`,
- inspection du pipeline persistant par `pool address`,
- affichage structuré des transactions résolues, événements DEX décodés, pools, paires, listings, launch origins, pool origins, wallets observés, holdings observés, trade events, pair metrics, candles et signaux analytiques,
- possibilité d’utiliser un timeframe custom pour régénérer à la demande les candles non matérialisées,
- conservation d’une instance partagée de `Database` dans `kb_demo_app` afin d’éviter la réouverture de la base et la réinitialisation du schéma à chaque commande UI,
- validation pratique de l’inspection du pipeline `0.7.x` sans dépendre uniquement des logs bruts ou de la consultation manuelle de SQLite.

### 6.055. Version `0.7.23` — `kb_demo_app` : backfill token ciblé
Réalisé :

- ajout d’un pilotage UI du backfill historique ciblé par `token mint` dans `kb_demo_app`,
- sélection du `token mint`, du rôle HTTP et des limites de signatures `mint / pool`,
- exécution de `TokenBackfillService` depuis une commande Tauri dédiée,
- affichage du résumé de backfill dans `Demo Pipeline`,
- réinspection automatique du token après backfill lorsque des objets persistés exploitables sont effectivement reconstruits,
- gestion explicite du cas où le backfill réussit sans matérialiser de token exploitable dans la base locale.

### 6.056. Version `0.7.24` — `kb_demo_app` : visualisation candles / OHLCV
Réalisé :

- ajout d’un affichage graphique des candles / OHLCV dans `kb_demo_app` via `echarts`,
- sélection dynamique de la paire inspectée,
- sélection dynamique du timeframe disponible,
- affichage conjoint des chandeliers OHLC et du volume,
- prise en charge des candles matérialisées et des candles régénérées à la demande pour un timeframe custom,
- intégration du rendu graphique directement dans `Demo Pipeline`.

### 6.057. Version `0.7.25` — Enrichissement metadata des tokens
Réalisé :

- Ajout :
  - relecture locale du pipeline à partir des transactions brutes persistantes de la chaîne,
  - actualisation optionnelle des métadonnées de jetons manquantes lors de la relecture locale,
  - reconstruction des symboles de paires à partir des métadonnées des jetons,
  - commandes d’interface utilisateur dans le pipeline de démonstration 2 pour la relecture locale,
  - flux de travail d’actualisation du catalogue de jetons/paires piloté par les métadonnées.
- Modifications :
  - les symboles de paires sont désormais dérivés comme `BASE/QUOTE` lorsque les deux symboles de jetons sont disponibles,
  - l’actualisation des métadonnées évite de nécessiter un remplissage complet de la blockchain lorsque les données de transaction brutes existent déjà localement.
- Corrections :
  - suppression des cycles complets de suppression/remplissage répétés pour les métadonnées et les entités locales dérivées,
  - conservation de l’accès SQL dans les modules de requêtes de base de données au lieu du SQL brut au niveau du service.

### 6.058. Version `0.7.26` — Diagnostics locaux, replay et extraction instruction-scoped
Réalisé :

- Ajout du diagnostic local complet du pipeline persisté :
  - transactions OK / échouées,
  - événements décodés,
  - trade candidates,
  - trade events,
  - candles,
  - tokens,
  - pools,
  - pairs,
  - diagnostics par DEX,
  - diagnostics par paire,
  - samples d’événements manquants ou multi-trades.
- Ajout des compteurs de santé du pipeline :
  - `diagnosticsClean`,
  - `blockingIssueCount`,
  - `actionableMissingTradeEventCount`,
  - `ignoredFailedTransactionTradeCandidateCount`,
  - `duplicateDecodedEventTradeCount`,
  - `multiTradeSignaturePairCount`,
  - `duplicateCandleBucketCount`.
- Correction de l’agrégation des trades Raydium via extraction instruction-scoped des transferts SPL Token depuis `meta.innerInstructions`.
- Correction des cas CPMM contenant plusieurs swaps dans une même transaction, sans mélange des montants entre instructions.
- Conservation des transactions échouées comme événements décodés traçables, sans génération de `k_sol_trade_events`.
- Clarification des compteurs de replay :
  - `pairCandleUpsertCount`,
  - `analyticSignalUpsertCount`.
- Validation :
  - aucun trade candidate issu d’une transaction OK n’est perdu,
  - aucun trade event invalide n’est persisté,
  - aucun doublon réel par `decoded_event_id`,
  - aucune candle dupliquée par bucket,
  - aucune paire sans trade ni candle après replay,
  - seuls les trade candidates issus de transactions échouées restent ignorés.

### 6.059. Version `0.7.27` — Validation multi-DEX des connecteurs déjà branchés
Objectif : verrouiller la non-régression du pipeline actuel avant d’ajouter de nouveaux DEX ou d’ouvrir la phase d’analyse `0.8.x`.

Réalisé / validé :

- replay local et bases neuves de test utilisés pour stabiliser `pump_fun`, `pump_swap`, `raydium_cpmm` et `raydium_clmm` ;
- aucun nouveau DEX ajouté dans cette étape : la version a bien servi de verrou de non-régression ;
- vérification du triptyque `decoded_event_count / trade_event_count / pair_candle_count` par DEX ;
- garde-fous maintenus sur `diagnosticsClean`, `blockingIssueCount`, `actionableMissingTradeEventCount`, `duplicateDecodedEventTradeCount` et `duplicateCandleBucketCount` ;
- refus des trades sans montant ou prix exploitable ;
- conservation des transactions échouées comme decoded events traçables sans produire de `k_sol_trade_events` ;
- maintien des champs d’enrichissement dans `payload_json` : `eventCategory`, `tradeCandidate`, `candleCandidate`, `liquidityCandidate`, `feeCandidate`, `rewardCandidate`, `adminCandidate`, `poolLifecycleCandidate` ;
- couverture testée dans les zones critiques : `dex_decode`, `dex_detect`, `trade_aggregation`, `pair_candle_aggregation`, `pair_analytic_signal`, `local_pipeline_replay`, `local_pipeline_diagnostics` ;
- requêtes SQL de diagnostic conservées comme contrôle manuel après backfill ou replay local.

### 6.060. Version `0.7.28` — Refactor DEX commun et préparation extension
Réalisé :

- ne pas toucher à `ws_client.rs`, `ws_manager.rs`, `http_client.rs`, `http_pool.rs` ni aux couches JSON-RPC déjà stabilisées,
- extraire depuis `dex_decode.rs` les catégories communes d’événements : trade, candle candidate, liquidity candidate, fee candidate, reward candidate, admin candidate, pool lifecycle candidate,
- créer une représentation interne documentée pour les familles d’événements DEX afin d’éviter les chaînes dispersées dans plusieurs fichiers,
- clarifier la différence entre événement décodé, événement actionnable, trade candidate, candle candidate et événement conservé seulement pour analyse,
- simplifier `dex_decode.rs` en gardant son rôle de service de persistance-orchestration,
- simplifier `dex_detect.rs` en extrayant les helpers communs pool/pair/listing/origin/wallet quand cela réduit la duplication,
- homogénéiser les contrats des modules `kb_lib/src/dex/*.rs` sans imposer trop tôt un trait générique lourd,
- vérifier la rustdoc publique : utile, courte, orientée responsabilité ; supprimer la documentation redondante ou trop chargée,
- conserver les tests verts et ajouter des tests de non-régression sur les catégories d’événements existantes.

Contraintes :

- refactor agressif autorisé si le résultat est plus propre,
- chaque changement doit rester rejouable et testable,
- aucun changement de comportement métier volontaire dans cette version,
- aucun événement non price-action ne doit devenir un trade ou une candle.

### 6.061. Version `0.7.29` — Matrice DEX commune et validation baseline
Réalisé :

- ajouter `kb_lib/src/dex_support_matrix.rs` comme source commune de metadata DEX/surfaces ;
- exposer pour chaque entrée : code interne, famille, version, type de surface, program id connu ou à vérifier, support actuel, statut, confiance, raisons de skip et activation catalogue ;
- raccorder `dex_catalog`, `transaction_classification` et `protocol_candidate_recording` à cette matrice ;
- ajouter le profil `0.7.29_multi_dex_matrix_baseline` ;
- exposer la matrice dans le rapport de validation local ;
- conserver explicitement le comportement `0.7.28` : transactions failed traçables mais non actionnables, et `meteora_damm_v1.swap` sans payload montant/prix non candidat trade/candle.

Matrice cible initiale :

| Code cible | Type | Statut `0.7.29` | Objectif immédiat |
|---|---:|---|---|
| `pump_fun` | launch + bonding curve | partiel | rattacher mint initial, bonding curve et migration |
| `pump_swap` | AMM / swap | supporté | conserver trades/candles |
| `raydium_cpmm` | AMM | supporté | conserver trades/candles |
| `raydium_clmm` | CLMM | supporté | conserver trades/candles |
| `raydium_launchlab` | launch surface | planifié, program id local connu | ajouter decoder/materialization dédiée |
| `raydium_launchpad` | launch surface | à vérifier | ne pas inventer de program id |
| `raydium_amm_v4` | AMM legacy | partiel | corpus dédié après autres Raydium |
| `raydium_router` | router | partiel | ne pas matérialiser en trade direct avant preuve |
| `raydium_stable_swap` | AMM legacy | planifié | traiter seulement si corpus pertinent |
| `meteora_dlmm` | DLMM | supporté | verrouiller corpus et non-régression |
| `meteora_damm_v1` | AMM legacy | partiel | garder skip explicite sans payload montant/prix |
| `meteora_damm_v2` | AMM | partiel | corpus et séparation events |
| `meteora_dbc` | launch / bonding curve | partiel | lifecycle, migration, swaps utiles |
| `meteora_dlc` | à vérifier | à vérifier | confirmer surface/program id avant intégration |
| `orca_whirlpools` | CLMM | partiel | validation par corpus |
| `fluxbeam` | AMM | partiel | validation par corpus |
| `dexlab` | AMM | partiel | validation par corpus |
| `bags` | launch surface | planifié | attribution fiable, migration si prouvée |
| `letsbonk` / `bonk` | launch surface | planifié | origine mint/lancement, sans supposer un AMM autonome |
| `okx_dex` | aggregator/router | planifié | classifier sans trade direct avant preuve |
| `boop_fun` | launch surface | planifié | origine mint/lancement/migration |
| `moonshot` / `moonit` | launch surface | planifié | corpus, éviter heuristique faible |
| `believe` | launch surface | planifié | confirmer comptes et migrations |
| `heaven` | launch + AMM candidat | planifié | corpus et séparation launch/swap |
| `zora` | à vérifier | à vérifier | hors phasage actif avant preuve Solana |

### 6.062. Version `0.7.30` — Classification fine des événements DEX décodés
Réalisé :

- ajouter `DexEventLifecycleKind` pour distinguer `trade_swap`, `pool_creation`, `pair_creation`, `liquidity_add`, `liquidity_remove`, `position_open`, `position_close`, `migration`, `launch`, `mint`, `burn`, `fee_collection`, `reward`, `admin_config` et `unknown`,
- ajouter `DexEventActionability` pour distinguer `trade_candidate`, `non_actionable_trade`, `non_trade_useful`, `failed_transaction`, `informational` et `unknown`,
- enrichir les payloads décodés avec `eventLifecycleKind`, `eventActionability` et `nonTradeUseful`,
- exposer les compteurs diagnostics `decodedNonTradeUsefulEventCount`, `decodedNonActionableTradeEventCount` et `decodedUnknownEventCount`,
- ajouter un résumé diagnostic par catégorie / lifecycle / actionability,
- ajouter le profil `0.7.30_non_trade_event_classification`,
- ne pas matérialiser encore les événements non-trade dans leurs tables dédiées.

### 6.063. Version `0.7.31` — Politique de matérialisation des failed transactions
Réalisé :

- empêcher `TradeAggregationService` de matérialiser une transaction dont `err_json` est renseigné ;
- conserver les événements DEX décodés des failed transactions pour audit et diagnostic ;
- réinitialiser les tables dérivées de marché pendant le replay local : `k_sol_trade_events`, `k_sol_pair_metrics`, `k_sol_pair_candles`, `k_sol_pair_analytic_signals` ;
- reconstruire ensuite les trades/candles uniquement à partir des événements `tradeCandidate=true` et de transactions OK ;
- exposer `resetMarketMaterializationDeletedCount` dans le résultat de replay UI ;
- conserver la validation multi-DEX et la matrice DEX comme garde-fous avant d’ajouter les surfaces restantes.

### 6.064. Version `0.7.32` — Sémantique des diagnostics et compteurs de validation
Réalisé :

- conserver la politique `0.7.31` : transactions failed traçables mais exclues des `trade_events`, metrics et candles ;
- clarifier que `pairWithoutTradeCount` et `pairWithoutCandleCount` sont des compteurs de gaps bloquants/actionnables, pas des compteurs littéraux sur tout le catalogue ;
- ajouter `literalPairWithoutTradeCount` et `literalPairWithoutCandleCount` pour les paires de catalogue sans trade/candle matérialisé ;
- ajouter `blockingPairWithoutTradeCount` et `blockingPairWithoutCandleCount` comme noms explicites des anciens compteurs bloquants ;
- ajouter les compteurs de matérialisation par paire : `tradeMaterializedPairCount`, `candleMaterializedPairCount`, `actionablePairCount`, `candleBucketTimeframeCount` et `candlesAreBucketed` ;
- ajouter `pairActionabilitySummaries` pour distinguer les paires matérialisées, actionnables sans matérialisation, candidates failed, non-actionables, décodées sans trade candidate et catalog-only ;
- ajouter le profil `0.7.32_validation_report_semantics` ;
- ajouter des garde-fous de validation sur la matrice DEX : entrées `supported` entièrement matérialisées, entrées `partial` avec `skipReason`, entrées `planned/to_verify` non activées au catalogue ;
- ne pas modifier la logique de replay, trade aggregation ou candle aggregation validée en `0.7.31`.

Repoussé après cette clarification : consolider les transactions inconnues et protocol candidates sans polluer les trades/candles.

### 6.065. Version `0.7.33` — Readiness trading des paires
Réalisé :

- ajouter une classification diagnostique `pairTradingReadiness` pour chaque paire inspectée localement ;
- distinguer `direct_wsol_quote`, `direct_stable_quote`, `inverse_wsol_base`, `inverse_stable_base`, `cross_quote_requires_router`, `unknown_quote` et `non_trade_materialized` ;
- exposer `quoteAssetClass` et `tradingRouteRequired` dans les diagnostics par paire ;
- ajouter `pairTradingReadinessSummaries` dans le résumé local du pipeline ;
- ajouter le profil `0.7.33_pair_trading_readiness` ;
- valider que les résumés de readiness couvrent toutes les paires et restent cohérents avec les compteurs `tradeMaterializedPairCount`, `tradeEventCount` et `pairCandleCount` ;
- ne pas modifier la logique de replay, `trade_events`, metrics ou candles.

Objectif : préparer la future couche d’achat/vente en distinguant les paires immédiatement exploitables contre WSOL/stable des paires qui nécessitent inversion de lecture ou routeur/aggregator.

### 6.066. Version `0.7.34` — Événements non-trade v1 : liquidité et cycle de vie pool
Réalisé :

- stabiliser et étendre `k_sol_liquidity_events` au lieu de la recréer inutilement,
- ajouter `k_sol_pool_lifecycle_events`,
- matérialiser les événements `initialize`, `create_pool`, `migrate`, `open_position`, `close_position`, `increase_liquidity`, `decrease_liquidity`, `add_liquidity`, `remove_liquidity` et assimilés,
- rattacher chaque événement à `dex_id`, `pool_id`, `pair_id`, `transaction_id`, `decoded_event_id`, `signature` et `slot` lorsque les informations existent,
- conserver le `payload_json` source pour audit,
- alimenter les diagnostics locaux avec les compteurs liquidité/lifecycle,
- garantir qu’un événement de liquidité ou de cycle de vie ne produit jamais de candle directement.

### 6.067. Version `0.7.35` — Événements non-trade v2 : fees, rewards et administration
Objectif : conserver les événements utiles au risque, au scoring, à l’économie du pool et à la traçabilité opérationnelle.

Réalisé :

- ajout des tables `k_sol_fee_events`, `k_sol_reward_events` et `k_sol_pool_admin_events` ;
- ajout des DTO, entities, requêtes, index et re-exports associés ;
- matérialisation contrôlée des événements fees/rewards/admin lorsque la classification et les comptes le permettent ;
- rattachement aux transactions, decoded events, pools et paires lorsque les données disponibles sont fiables ;
- raccordement aux diagnostics locaux via `feeEventCount`, `rewardEventCount` et `poolAdminEventCount` ;
- ajout du profil `0.7.35_non_trade_fee_reward_admin` ;
- invariant maintenu : aucun fee/reward/admin ne produit de trade, metric ou candle.

Limite connue : le corpus local `0.7.38` ne contient pas encore d’événements fee/reward/admin matérialisés ; les compteurs peuvent donc rester à zéro sans bloquer la validation.

### 6.068. Version `0.7.36` — Meteora : DBC / DAMM v1 / DAMM v2 / DLMM
Réalisé :

- consolidation de Meteora comme famille multi-programmes au lieu de traiter `DBC`, `DAMM v1`, `DAMM v2` et `DLMM` comme des cas isolés ;
- ajout/correction des discriminants et classifications utiles pour `meteora_damm_v2`, `meteora_dbc`, `meteora_damm_v1` et `meteora_dlmm` ;
- correction du cas `meteora_damm_v2` où la classification de data était appelée depuis le mauvais scope ;
- ajout de garde-fous sur les fixtures et les instructions internes afin d’éviter les faux positifs ;
- validation du profil `0.7.36_meteora_family_consolidation` sur corpus local mixte ;
- conservation de `meteora_damm_v2.swap` et `meteora_dbc.swap` sans payload montant/prix fiable comme `non_actionable_trade` ;
- suppression des faux diagnostics bloquants liés aux swaps Meteora sans amounts : `missingTradeEventCount = 0`, `decodedTradeCandidateWithoutTradeEventCount = 0`, `decodedTradeCandidateWithoutAmountPayloadCount = 0` ;
- maintien de l’invariant : aucun événement sans montant/prix exploitable ne peut alimenter `trade_events`, `pair_metrics` ou `pair_candles` ;
- documentation de la limite connue : `meteora_damm_v2` et `meteora_dbc` peuvent être observés et décodés sans être encore matérialisables en trades/candles.

### 6.069. Version `0.7.37` — Token metadata et catalogue local
Objectif : rendre le catalogue local exploitable et lisible avant d’ajouter davantage de launch surfaces.

Réalisé :

- ajout du profil `0.7.37_token_metadata_catalog_enrichment` ;
- exposition des compteurs metadata/catalog dans les diagnostics et le rapport de validation : `tokenCount`, `tokenMetadataMissingCount`, `tradableTokenMetadataMissingCount`, `quoteTokenMetadataMissingCount`, `pairSymbolFallbackCount`, `pairSymbolResolvedCount`, `wsolQuotePairCount`, `stableQuotePairCount` ;
- raccordement UI Demo Pipeline 2 au profil `0.7.37` puis au profil `0.7.38` ;
- maintien volontaire du caractère non bloquant des metadata manquantes ;
- backfill metadata des tokens déjà présents dans `k_sol_tokens` sans nécessiter un nouveau backfill transactionnel ;
- enrichissement depuis les sources disponibles : registre local, payloads Pump.fun, comptes SPL/Token-2022, Metaplex lorsque le service dispose d’un `HttpEndpointPool` ;
- rafraîchissement des `pair_symbol` après enrichissement des tokens ;
- commande UI disponible via `Demo Pipeline 2 > Replay local > Refresh missing token metadata` avec limite dédiée ;
- idempotence attendue : le backfill metadata met à jour tokens et symboles de paires sans recréer pools, paires, trades, candles ou origins ;
- registre local minimal consolidé : `SOL`, `WSOL`, `USDC`, `USDT`.

Limite non bloquante : les diagnostics détaillés par origine de découverte restent une amélioration de confort ; l’étape `0.7.38` fournit déjà une liste priorisée exploitable via `tokenMetadataGapSamples`.

### 6.070. Version `0.7.38` — Priorisation des metadata manquantes
Objectif : transformer les compteurs metadata/catalog de `0.7.37` en liste d’action priorisée sans rendre les metadata manquantes bloquantes.

Réalisé :

- ajout du profil `0.7.38_token_metadata_gap_prioritization` ;
- exposition de `tokenMetadataGapSamples` dans les diagnostics locaux, la validation et les bindings Demo Pipeline 2 ;
- priorisation des tokens manquants par usage : `tradable_quote_missing_metadata`, `tradable_token_missing_metadata`, `quote_token_missing_metadata`, puis `catalog_token_missing_metadata` ;
- raccordement Demo Pipeline 2 au nouveau profil par défaut ;
- conservation de l’invariant : les metadata manquantes ne créent pas de blocking issue tant que les trades/candles actionnables restent sains ;
- validation locale confirmée avec `validationPassed = true`, `blockingIssueCount = 0`, `missingTradeEventCount = 0`, `decodedTradeCandidateWithoutTradeEventCount = 0` ;
- les samples permettent de sélectionner les prochains mints à enrichir via registre local, payloads DEX, Token-2022, Metaplex ou backfill HTTP.

Décision : `0.7.38` est clos. La clôture `0.7.38-B` conserve la logique de stable quotes limitée à `USDC`/`USDT` et ajoute un registre metadata local pour `JUP`, `RAY` et `BONK` sans les classer automatiquement comme quotes. La suite de développement commence à `0.7.39` avec une priorité DEX-first : consolider les DEX effectifs de swap avant de revenir aux launch surfaces.

### 6.071. Version `0.7.39` — Réorientation DEX-first et inventaire des DEX effectifs
Objectif : remplacer la priorité précédemment donnée aux launch surfaces par une consolidation des vrais DEX sur lesquels les swaps et événements de marché sont exécutés.

Réalisé :

- modification de la matrice DEX pour distinguer explicitement les rôles de surface : `dex_effective`, `aggregator_router`, `launch_surface`, `to_verify` ;
- suppression de l’alias ambigu `raydium` comme code DEX autonome ; `raydium` reste uniquement une famille, avec `raydium_amm_v4` comme surface legacy explicite ;
- ajout de `metaDAO` et `Printr` comme entrées `to_verify` sans `program_id` inventé ;
- conservation des DEX de swap principaux déjà connus dans la matrice : `pump_swap`, `raydium_cpmm`, `raydium_clmm`, `raydium_amm_v4`, `raydium_stable_swap`, `meteora_dlmm`, `meteora_damm_v1`, `meteora_damm_v2`, `meteora_dbc`, `orca_whirlpools`, `fluxbeam`, `dexlab` ;
- maintien des launch surfaces comme surfaces reportées et non prioritaires ;
- ajout du profil `0.7.39_dex_first_effective_swap_surfaces` ;
- validation locale confirmée avec `validationPassed = true`, `blockingIssueCount = 0`, `actionableMissingTradeEventCount = 0` et `missingTradeEventCount = 0` ;
- confirmation par corpus local initial que Raydium CLMM est observé, tandis que Raydium AMM v4 et Stable Swap ne sont pas encore exploitables sans constitution de corpus dédiée.

Décision : `0.7.39` est clos. La suite immédiate ne doit pas commencer par un décodeur Raydium AMM v4 sans corpus. Il faut d’abord ajouter les outils de découverte on-chain et de backfill ciblé afin d’obtenir des signatures, pools/state accounts, token mints et instructions exploitables.

### 6.072. Version `0.7.40` — Demo3 on-chain discovery et backfill par signature
Objectif : ajouter les outils de constitution de corpus nécessaires avant de consolider les décodeurs DEX incomplets.

Réalisé :

- ajout de `Demo3` dans `kb_demo_app` pour rechercher on-chain à partir d’un `dex_code` et/ou d’un `program_id` ;
- utilisation de la chaîne `getSignaturesForAddress(program_id)` puis `getTransaction(signature)` pour récupérer des transactions récentes liées à un programme DEX ;
- extraction générique, indépendante des décodeurs DEX existants, de preuves on-chain : `observedTokenMints`, `tokenBalanceDeltas`, `candidatePoolAccounts`, `candidateTokenVaultAccounts` et `candidateProgramAccounts` ;
- distinction explicite entre `verifiedPoolAddress` et comptes candidats : un compte candidat n’est pas promu en pool vérifié sans décodage/layout/corpus fiable ;
- conservation de `metaDAO` et `Printr` comme surfaces à vérifier sans `program_id` ;
- ajout du backfill par signature dans Demo Pipeline 2, en complément du backfill par token mint et pool address ;
- réutilisation du pipeline existant pour le backfill signature : résolution transactionnelle, projection `k_sol_chain_transactions` / `k_sol_chain_instructions`, décodage DEX existant, détection, matérialisation non-trade, trades, candles et classification ;
- validation pratique sur `raydium_amm_v4` : les signatures et inner instructions associées au programme `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8` sont maintenant persistées et inspectables ;
- observation de patterns Raydium AMM v4 récurrents dans les instructions projetées : `accounts_json[1]` comme candidat pool/state, `accounts_json[2]` comme autorité Raydium AMM, `accounts_json[3]` et `accounts_json[4]` comme vaults candidats, avec les comptes utilisateur en fin d’instruction ;
- maintien des invariants : aucune transaction failed ne produit `trade_events`, metrics ou candles ; aucun candidat sans montants exploitables ne devient trade/candle ; aucun `program_id` n’est inventé.

Décision : `0.7.40` est clos. `Demo3` et Demo Pipeline 2 suffisent pour constituer le corpus nécessaire à la suite immédiate. `Demo4` est décalée à une version ultérieure, car la priorité est maintenant d’utiliser le corpus on-chain local pour consolider `raydium_amm_v4`.

### 6.073. Version `0.7.41` — Raydium AMM v4 swap decoder v1
Objectif : ajouter un premier décodeur fiable pour les swaps Raydium AMM v4 observés dans le corpus constitué avec Demo3 et Demo Pipeline 2.

Réalisé :

- ajout du décodeur `raydium_amm_v4.swap` pour les instructions de swap AMM v4 ;
- prise en charge des inner instructions dont `program_id = 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`, notamment lorsqu’elles sont appelées via Jupiter ou un autre routeur top-level ;
- conservation dans le payload décodé des informations de routage utiles : `routeSource`, programme parent, `innerInstruction`, `instructionIndex`, `innerInstructionIndex` et comptes complets ;
- extraction des comptes selon les layouts observés : token program, pool/state, authority, vault A, vault B, comptes intermédiaires et comptes utilisateur lorsque disponibles ;
- dérivation des mints et montants via deltas SPL Token et transferts instruction-scoped, avec refus des cas sans payload exploitable ;
- production de `eventActionability = trade_candidate` uniquement lorsque les mints et montants sont exploitables ;
- matérialisation des pools, paires, listings, `trade_events`, metrics et candles uniquement pour les transactions OK ;
- maintien des transactions failed comme traçables mais sans `trade_events`, metrics ni candles ;
- ajout du profil `0.7.41_raydium_amm_v4_swap_decoder` dans la validation locale et dans Demo Pipeline 2 ;
- mise à jour de la matrice DEX : `raydium_amm_v4` passe en `observed = true`, `status = supported`, `confidence = high`, sans `skipReason` ;
- validation locale confirmée avec `validationPassed = true`, `blockingIssueCount = 0`, `warningCount = 0`, `actionableMissingTradeEventCount = 0`, `missingTradeEventCount = 0`, `decodedTradeCandidateWithoutAmountPayloadCount = 0` et `invalidTradeEventCount = 0`.

Résultat de corpus validé : `raydium_amm_v4` produit 58 decoded events, 58 trade candidates, 58 trade events, 11 pools/paires et 147 candles sur la base de test Raydium AMM v4. Les routes Jupiter ou routeurs top-level restent annotées comme sources de route, tandis que le decoded event métier est attribué au DEX effectif `raydium_amm_v4`.

Décision : `0.7.41` est clos. La suite immédiate est `0.7.42_raydium_family_consolidation` afin de verrouiller ensemble `raydium_cpmm`, `raydium_clmm`, `raydium_amm_v4` et les surfaces Raydium non encore matérialisées.

### 6.074. Version `0.7.42` — Raydium family consolidation
Objectif : verrouiller ensemble `raydium_cpmm`, `raydium_clmm` et `raydium_amm_v4` comme surfaces Raydium effectives supportées, avec swaps et premiers non-swaps prouvés.

Réalisé :

- ajout du profil `0.7.42_raydium_family_event_coverage` ;
- conservation audit des instructions Raydium non décodées en `raydium_*.instruction_audit`, non-actionnables, sans trade/candle ;
- enrichissement des audits avec comptes, data base58, discriminator hex, `instructionIndex`, `innerInstructionIndex`, programme parent et statut de transaction ;
- décodage du legacy CLMM `raydium_clmm.swap` en plus de `raydium_clmm.swap_v2` ;
- cleanup des audits remplacés : un audit d’instruction est supprimé lorsqu’un vrai événement est maintenant décodé pour la même instruction ;
- adaptation du backfill historique : `getTransaction` classé en requête HTTP lourde, retry/backoff et poursuite du backfill en cas d’erreur transitoire ;
- mapping des discriminators CLMM prouvés : `decrease_liquidity_v2`, `increase_liquidity_v2`, `open_position_with_token22_nft`, `close_position` ;
- mapping des discriminators CPMM prouvés : `initialize`, `withdraw`, `collect_creator_fee` ;
- matérialisation des événements non-trade Raydium prouvés dans les tables dédiées : `k_sol_liquidity_events`, `k_sol_pool_lifecycle_events`, `k_sol_fee_events` ;
- validation manuelle par SQL du corpus Raydium : swaps AMM v4/CLMM/CPMM matérialisés, `25` liquidity events, `1` lifecycle event, `2` fee events, aucune instruction Raydium orpheline ;
- conservation des non-swaps AMM v4 legacy en audit informatif : les discriminators AMM v4 restants ne sont pas promus sans preuve suffisante ;
- correction de validation rapide pour grosses bases SQLite afin d’éviter de charger les diagnostics détaillés par paire pendant la validation.

Limite connue non-Raydium : un corpus local peut encore contenir des événements `orca_whirlpools.swap` partiels. Orca Whirlpools est explicitement reporté à `0.7.44`; cela ne remet pas en cause la clôture Raydium `0.7.42`.

Décision : `0.7.42` est clos côté Raydium. Le lot `0.7.43` ouvert pour Meteora n’est pas considéré comme clos : il devient le point de reprise `0.7.43-E5C`, puis la suite est découpée en étapes plus petites pour éviter les lots multi-DEX trop larges.

### 6.075. Version `0.7.43` — Point de reprise, normalisation DEX-first et documentation
Objectif : figer le point de reprise après saturation de session, clarifier l’état réel du corpus et empêcher la roadmap de regrouper plusieurs DEX/versions dans une seule tranche de validation.

À faire / acté :

- documenter que `0.7.43` n’est pas une clôture Meteora complète ;
- conserver les résultats locaux observés : `2956` transactions, `7159` decoded events, `2738` trade events, `0` liquidity events sur le corpus courant, `1` lifecycle event, `0` fee/reward/admin events ;
- acter que les nombreux `instruction_audit` Meteora sont une dette de décodage, pas une preuve d’événements non-trade matérialisés ;
- imposer un ordre de travail : vrais DEX effectifs, puis launch surfaces, puis DEX historiques/legacy ;
- imposer une validation séparée par DEX/version : `meteora_dlmm`, `meteora_damm_v1`, `meteora_damm_v2`, `meteora_dbc`, etc. ;
- distinguer les statuts `known`, `observed`, `decoded`, `materialized`, `verified_by_corpus` ;
- maintenir la règle : aucun `program_id` n’est vérifié sans signature/corpus/requête de validation.

### 6.076. Version `0.7.44` — Ledger de décodage/replay et skip sûr
Objectif : empêcher le replay local de rescanner inutilement les transactions dont le décodage DEX est déjà certifié pour la même version logique de decoder, tout en laissant les tables dérivées se reconstruire normalement.

Statut : implémenté en première tranche transaction-level.

Fait :

- ajout de `k_sol_dex_decode_replay_ledger` dans `kb_lib/src/db/schema.rs` ;
- stockage de `transaction_id`, `signature`, `decoder_scope`, `decoder_version`, `decode_status`, `certainty`, `event_count`, `distinct_token_mint_count`, `force_replay_required`, reason et timestamps ;
- ajout des entities/dtos/queries associées ;
- mise à jour des re-exports dans `kb_lib/src/db.rs` puis `kb_lib/src/lib.rs` ;
- intégration dans `local_pipeline_replay.rs` sans changer la sémantique trade/candle : le skip ne concerne que `DexDecodeService`, pas la détection, la matérialisation non-trade, les trades, candles, signaux analytiques ou classifications ;
- ajout de `skip_certified_dex_decode` et `force_decode_replay` dans `LocalPipelineReplayConfig` ;
- marquage `unsafe` des transactions multi-event ou avec plus de deux mints distincts dans les events décodés ;
- version logique initiale `dex_decode.v0.7.44.ledger1`, à incrémenter lorsqu’un decoder change de comportement.

Reste à faire plus tard :

- descendre le ledger au niveau instruction/program lorsque nécessaire ;
- ajouter un hash d’entrée transaction/instruction pour détecter les mutations de payload ;
- exposer l’option `force_decode_replay` dans l’UI si besoin ;
- ajouter des diagnostics dédiés dans `local_pipeline_diagnostics`.

### 6.077. Version `0.7.45` — `meteora_dlmm` séparé
Objectif : consolider `meteora_dlmm` comme DEX effectif séparé, avec corpus dédié et events utiles au trading.

À faire :

- vérifier le ou les `program_id` par corpus local, pas seulement par constante ;
- consolider swaps exploitables, add/remove liquidity, positions, lifecycle et audits restants ;
- matérialiser uniquement les events prouvés dans les tables dédiées ;
- conserver tout event incomplet en `instruction_audit` ou non-actionnable ;
- ajouter les compteurs diagnostics par event kind.

### 6.078. Version `0.7.46` — `meteora_damm_v1` séparé
Objectif : reprendre `meteora_damm_v1` sans le mélanger à DAMM v2, DBC ou DLMM.

À faire :

- valider les swaps exploitables et les cas sans amounts ;
- rechercher create/init pool, liquidity, fee/admin/config et autres events utiles ;
- maintenir la règle : pas de trade/candle si base/quote amount ou prix ne sont pas fiables ;
- produire un corpus SQL minimal pour chaque event promu.

### 6.079. Version `0.7.47` — `meteora_damm_v2` séparé
Objectif : reprendre `meteora_damm_v2` comme DEX effectif séparé, avec traitement spécifique des nombreux `instruction_audit`.

À faire :

- vérifier `cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG` dans le corpus local avant de le marquer `verified_by_corpus` ;
- consolider `create_pool`, swaps exploitables, configs dynamiques, fees/admin et events lifecycle ;
- conserver les swaps sans payload montant/prix fiables comme `non_actionable_trade` ;
- ne promouvoir aucun event depuis `instruction_audit` sans signature de validation.

### 6.080. Version `0.7.48` — `meteora_dbc` séparé
Objectif : séparer proprement bonding/launch, swap effectif, migration et attribution d’origine dans `meteora_dbc`.

À faire :

- distinguer les events de bonding curve / launch des events de DEX effectif ;
- vérifier swaps exploitables, migration, lifecycle, mint/burn éventuels et launch attribution ;
- éviter toute candle artificielle sur events de bonding/launch non pricés ;
- documenter les signatures/corpus avant toute promotion.

### 6.081. Version `0.7.49` — `orca_whirlpools` séparé
Objectif : revalider Orca Whirlpools par corpus dédié avant toute promotion au même niveau que Raydium/Meteora.

À faire :

- revalider create_pool, swap, liquidité, positions, mints et montants fiables ;
- traiter les swaps Orca partiels comme non-actionnables tant que les montants ne sont pas reconstruits ;
- matérialiser uniquement les events prouvés ;
- ajouter des diagnostics par event kind.

### 6.082. Version `0.7.50` — `fluxbeam` séparé
Objectif : vérifier FluxBeam comme DEX effectif distinct.

À faire :

- constituer un corpus local ;
- vérifier `program_id`, comptes, préfixes `data_json` et familles d’instructions utiles ;
- valider swaps, pools, liquidity et events non-trade prouvés ;
- marquer explicitement les parties heuristiques ou non-actionnables.

### 6.083. Version `0.7.51` — `dexlab` séparé
Objectif : vérifier DexLab comme DEX effectif distinct, sans le confondre avec OpenBook ou une autre couche de marché.

À faire :

- constituer un corpus local ;
- vérifier `program_id`, comptes, préfixes `data_json` et familles d’instructions utiles ;
- valider swaps, pools et éventuels liens de market/pool ;
- conserver les cas partiels en audit.

### 6.084. Version `0.7.52` — `metaDAO` candidat DEX
Objectif : rechercher et vérifier metaDAO sans inventer de `program_id`.

À faire :

- rechercher les signatures/corpus via Demo3, DEX Screener ou sources externes de découverte ;
- ne considérer une source externe que comme indice ;
- promouvoir uniquement après preuve on-chain locale ;
- documenter chaque programme, event et limite.

### 6.085. Version `0.7.53` — `printr` candidat DEX
Objectif : rechercher et vérifier Printr sans inventer de `program_id`.

À faire :

- rechercher les signatures/corpus via Demo3, DEX Screener ou sources externes de découverte ;
- ne considérer une source externe que comme indice ;
- promouvoir uniquement après preuve on-chain locale ;
- documenter chaque programme, event et limite.

### 6.086. Version `0.7.54` — Couverture événementielle DEX consolidée
Objectif : s’assurer que chaque DEX effectif supporté expose les événements utiles au scoring et au risque sans polluer les trades/candles.

À faire :

- vérifier par DEX la couverture `swap` / `tradeCandidate` / `candleCandidate` ;
- vérifier par DEX la couverture liquidité : add/remove/increase/decrease/open/close position ;
- vérifier par DEX les événements lifecycle : create/init/migrate/pause/resume/close ;
- vérifier par DEX les fees, rewards, creator fees, protocol fees et admin/config ;
- vérifier les burns/mints utiles au suivi token/pool sans les transformer en price-action ;
- matérialiser uniquement les événements prouvés dans les tables dédiées ;
- ajouter des compteurs et samples diagnostics par DEX et par type d’événement ;
- conserver l’invariant : aucun fee/reward/admin/liquidity/lifecycle/burn non price-action ne produit de trade, metric ou candle.

### 6.087. Version `0.7.55` — `kb_demo_app` Demo4 : DEX Screener et sources externes de découverte
Objectif : utiliser des sources externes comme aides à la découverte de corpus sans les traiter comme vérité métier.

À faire :

- ajouter une `Demo4` pour interroger DEX Screener ou une source équivalente ;
- rechercher des paires par token mint, chain, DEX name, pool address ou program id lorsque disponible ;
- comparer les résultats externes avec les objets locaux : tokens, pools, pairs, listings, decoded events et protocol candidates ;
- afficher les écarts : paire externe absente localement, pool local sans source externe, DEX label ambigu, program id manquant ;
- permettre de copier les signatures/adresses candidates pour backfill ;
- ne jamais promouvoir automatiquement un DEX, un `program_id` ou une paire sur la seule base d’une réponse externe.

### 6.088. Version `0.7.56` — Démos spécialisées launch surfaces après DEX effectifs
Objectif : préparer des vues spécialisées pour les launch surfaces, mais seulement après stabilisation des DEX effectifs.

À faire plus tard :

- ajouter des démos dédiées à `pump_fun`, `raydium_launchpad` / `raydium_launchlab`, `believe`, `bags`, `moonshot` / `moonit`, `boop_fun`, `letsbonk` / `bonk_fun`, `heaven` ;
- distinguer `launch_origin`, `pool_origin`, `dex_effective` et `migration_target` ;
- rattacher les launch origins aux pools et paires uniquement lorsque les comptes permettent un matching fiable ;
- exposer les origins dans les diagnostics et l’UI d’inspection ;
- maintenir l’interdiction de faux program ids, faux trades et fausses candles.

### 6.089. Version `0.7.57` — `kb_demo_app` Demo10 : watcher WebSocket live DEX
Objectif : valider le passage du replay/backfill vers l’observation temps réel contrôlée.

À faire :

- ajouter une démo temps réel type `Demo10` avec bouton `start` / `stop` ;
- permettre de sélectionner les endpoints WS/HTTP et les DEX/program ids à souscrire ;
- lancer le client WebSocket existant sans refactorer inutilement `ws_client.rs` / `ws_manager.rs` ;
- effectuer les `logsSubscribe`, `programSubscribe` ou `accountSubscribe` nécessaires selon le DEX ;
- détecter en temps réel mints, swaps, liquidités et autres événements utiles ;
- écrire en base via le pipeline existant : observations, transactions résolues, decoded events, pools/pairs/listings, trade events, candles et non-trade events ;
- afficher les compteurs live, erreurs, subscriptions actives et derniers objets persistés ;
- prévoir un arrêt propre avec unsubscribe avant close.

### 6.090. Version `0.7.58` — Validation DEX v1 consolidée
Objectif : rejouer tous les DEX effectifs supportés et valider les invariants du pipeline complet avant de revenir aux launch surfaces ou à l’analyse `0.8.x`.

À faire :

- rejouer des bases neuves couvrant tous les connecteurs DEX supportés ;
- vérifier les compteurs globaux et par DEX : decoded events, trade events, liquidity events, lifecycle events, fee events, reward events, admin events, burns/mints utiles, candles et analytic signals ;
- contrôler que chaque famille d’événements alimente uniquement les tables métier prévues ;
- vérifier les diagnostics bloquants et les samples d’anomalie ;
- documenter les corpus utilisés pour chaque DEX/surface ;
- conserver une matrice de support par DEX, variante, instruction et type d’événement ;
- verrouiller les invariants avant d’ouvrir l’analyse `0.8.x`.

### 6.091. Version `0.8.x` — Analyse et filtrage
Objectif : transformer les événements bruts en signaux exploitables.

À faire :

- agrégation des métriques ;
- règles de filtrage ;
- exclusions des tokens non tradables ;
- statistiques de comportement ;
- premiers patterns ;
- enrichissement des signaux analytiques préparés en fin de `0.7.x` ;
- indicateurs graphiques optionnels comme Ichimoku / Kumo ;
- outils de sélection manuelle de points ABC et projection d’un point D selon des règles temps/prix explicites ;
- séparation stricte entre signaux analytiques observés, projections hypothétiques et décisions de trading.

### 6.083. Version `1.x.y` — Wallets, comptes et transferts
Objectif : préparer la couche d’action sans encore brancher l’achat/vente automatique.

À faire :

- gestion du répertoire wallets ;
- création de wallet/keypair ;
- chargement sécurisé des keypairs ;
- inspection des informations wallet ;
- transfert de fonds depuis cette wallet vers un autre account ;
- garde-fous d’affichage, confirmation et simulation ;
- préparation d’ordres et de swaps seulement après stabilisation des transferts de base.

### 6.084. Version `2.x.y` — Trading semi-automatisé
Objectif : brancher l’analyse à l’action tout en gardant des garde-fous explicites.

À faire :

- scénarios d’achat/vente ;
- règles d’entrée/sortie ;
- limites de risque ;
- confirmations explicites ou semi-automatiques ;
- journaux d’exécution.

### 6.085. Version `3.x.y` — Yellowstone gRPC
Objectif : ajouter le connecteur gRPC dédié.

À faire :

- `GrpcClient` basé sur `yellowstone-grpc-client` ;
- adaptation du pipeline d’événements ;
- coexistence HTTP / WS / gRPC ;
- politique de répartition par source.

## 7. Organisation des modules ciblés

### 7.1. `kb_lib`
Modules stables à ne pas remanier dans la phase immédiate :

- `ws_client.rs`
- `ws_manager.rs`
- `http_client.rs`
- `http_pool.rs`
- `json_rpc_ws.rs`
- `solana_pubsub_ws.rs`

Modules ciblés par le refactor et la consolidation DEX :

- `dex.rs`
- `dex/*.rs`
- `dex_decode.rs`
- `dex_detect.rs`
- `trade_aggregation.rs`
- `pair_candle_aggregation.rs`
- `pair_analytic_signal.rs`
- `launch_origin.rs`
- `pool_origin.rs`
- `wallet_observation.rs`
- `wallet_holding_observation.rs`
- `token_metadata.rs`
- `local_pipeline_replay.rs`
- `local_pipeline_validation.rs`
- `local_pipeline_diagnostics.rs`

`local_pipeline_diagnostics.rs` est volontairement conservé comme outil temporaire de validation. Il pourra devenir obsolète ou être remplacé lorsque les tests DEX seront stabilisés. Il n’est pas prioritaire de le refactorer maintenant.

### 7.2. Base de données

Organisation de la couche DB à conserver :

- `db/schema.rs` : création des tables et index uniquement ; chaque table ou index reste dans une fonction dédiée,
- `db/entities/*` : entités proches des lignes persistées,
- `db/dtos/*` : DTOs applicatifs,
- `db/queries/*` : requêtes SQL regroupées par table ou usage,
- `db/queries/local_pipeline_diagnostics.rs` : requêtes de diagnostic local, utiles pendant la validation DEX.

`schema.rs` peut rester long tant qu’il reste strictement un fichier de schéma. Le split prioritaire concerne plutôt les responsabilités métier dans `dex_decode.rs`, `dex_detect.rs` et `trade_aggregation.rs`.

### 7.3. `kb_demo_app`
Responsabilités cibles :

- lancement Tauri,
- commandes UI,
- affichage des états et messages,
- réception des événements venant de `kb_lib`,
- fenêtres de démonstration / diagnostic isolées,
- inspection du pipeline persisté,
- `Demo3` pour la recherche de paires/pools par DEX ou `program_id`,
- `Demo4` pour les requêtes DEX Screener et la comparaison avec la base locale,
- `Demo10` pour le watcher WebSocket live DEX avec start/stop,
- affichage candles et futurs overlays analytiques.

`kb_demo_app` ne doit pas contenir de logique métier DEX profonde.

## 8. Ligne de conduite sur le `WsClient`
Le `WsClient` doit être conçu en plusieurs couches :

1. transport brut WebSocket,
2. encodage/décodage JSON texte,
3. couche JSON-RPC 2.0,
4. couche Solana subscribe/unsubscribe/notification,
5. couche métier pour la répartition des messages.

Cette séparation évite de mélanger :

- les réponses à requêtes simples,
- les réponses de subscribe,
- les réponses de unsubscribe,
- les notifications push.

## 9. Politique initiale de reconnexion
Au départ :

- pas de reconnexion automatique,
- pas de resubscribe automatique,
- comportement explicite contrôlé par l’appelant.

Plus tard, ce comportement pourra devenir configurable dans `config.json` et pilotable depuis l’application.

## 10. Politique initiale de fermeture
À la fermeture d’un `WsClient` :

1. marquer le client en arrêt,
2. tenter les `unsubscribe` actifs,
3. attendre les réponses dans une fenêtre bornée,
4. forcer la purge locale si nécessaire,
5. fermer proprement le flux d’écriture,
6. laisser se terminer le flux de lecture,
7. journaliser clairement les cas dégradés.

## 10.5. Jalons `0.7.29`

Réalisé / à maintenir :

- matrice DEX commune dans `kb_lib/src/dex_support_matrix.rs` ;
- raccordement minimal du catalogue DEX à cette matrice ;
- raccordement des mappings program id -> protocole utilisés par la classification transactionnelle et les protocol candidates ;
- profil `0.7.29_multi_dex_matrix_baseline` ;
- exposition de la matrice dans le rapport de validation local ;
- aucune modification volontaire du comportement trade/candle validé en `0.7.28`.

Validé en `0.7.30` : classification fine des événements décodés via `eventLifecycleKind`, `eventActionability` et `nonTradeUseful`, avec diagnostics associés et sans changement volontaire sur les trades/candles.

À poursuivre après `0.7.31` : transactions inconnues/protocol candidates, puis matérialisation contrôlée des événements non-trade utiles, sans alimenter les trades/candles actionnables.

## 11. Documentation et livrables de référence
Le projet doit maintenir au minimum :

- un `README.md` global,
- un `ROADMAP.md` global,
- un `CHANGELOG.md` global,
- des `README.md` et `TODO.md` par crate à mesure de l’évolution,
- des tests unitaires robustes,
- les bindings TS générés via `cargo test export_bindings` lorsque les types partagés évoluent.

## 12. Priorité immédiate

La priorité immédiate après le point de reprise `0.7.43-E5C` n’est plus de terminer Meteora en un seul bloc. Le lot Meteora groupé a montré ses limites : les events, les audits, les surfaces bonding/launch et les variantes de DEX doivent être traités séparément.

Préconditions considérées acquises avant cette reprise :

1. validation `0.7.36` acquise : Meteora consolidé au niveau baseline, transactions failed traçables mais non actionnables, swaps sans amounts classés `non_actionable_trade`, aucun diagnostic bloquant masqué ;
2. validation `0.7.37` acquise : compteurs metadata/catalog exposés, backfill metadata idempotent, `pair_symbol` rafraîchissables, metadata manquantes non bloquantes ;
3. validation `0.7.38` acquise : `tokenMetadataGapSamples` priorisés, Demo Pipeline 2 raccordé, registre local `WSOL`/`USDC`/`USDT`/`JUP`/`RAY`/`BONK` disponible ;
4. `0.7.39` acquis : matrice DEX-first, suppression de l’alias `raydium`, `metaDAO` et `Printr` en `to_verify`, aucun `program_id` fictif ;
5. `0.7.40` acquis : `Demo3` découvre on-chain des signatures, mints, deltas et comptes candidats ; Demo Pipeline 2 peut backfiller une signature précise ;
6. `0.7.41` acquis : `raydium_amm_v4.swap` décode les inner instructions `675kPX...`, produit des trades/candles lorsque les montants sont exploitables, et conserve les transactions failed sans matérialisation marché ;
7. `0.7.42` acquis côté Raydium : CLMM/CPMM couvrent swaps et premiers non-swaps prouvés ; AMM v4 couvre les swaps et conserve les non-swaps legacy en audit ;
8. `0.7.43-E5C` est le point de reprise documentaire et technique, avec Clippy `kb_lib` validé localement après correction.

Ordre de travail recommandé pour la suite :

1. `0.7.44` : ledger de décodage/replay et skip sûr ;
2. `0.7.45` : `meteora_dlmm` ;
3. `0.7.46` : `meteora_damm_v1` ;
4. `0.7.47` : `meteora_damm_v2` ;
5. `0.7.48` : `meteora_dbc` ;
6. `0.7.49` : `orca_whirlpools` ;
7. `0.7.50` : `fluxbeam` ;
8. `0.7.51` : `dexlab` ;
9. `0.7.52` : `metaDAO` candidat DEX ;
10. `0.7.53` : `printr` candidat DEX ;
11. `0.7.54` : couverture événementielle DEX consolidée ;
12. `0.7.55+` : sources externes de découverte, launch surfaces, watcher live et validation consolidée.

Garde-fous constants :

- pas de faux trade ;
- pas de fausse candle ;
- pas de `program_id` fictif ;
- pas de promotion d’un DEX sans corpus transactionnel ;
- pas de logique métier DEX profonde dans `kb_demo_app` ;
- pas de metadata manquante bloquante ;
- pas de refactor réseau inutile tant que les clients HTTP/WS existants suffisent ;
- pas de skip replay sur transaction/instruction ambiguë, multi-token ou multi-event sans preuve ledger.
