0.7.26

ROADMAP.md

@@ -699,34 +699,150 @@ Réalisé :
 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.
+  - 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.
+  - 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.
+  - 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` — Validation multi-DEX et non-régression du pipeline
-Objectif : vérifier que les connecteurs déjà branchés restent cohérents avant d’ouvrir la phase d’analyse `0.8.x`.
+### 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 `kb_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`.
 
 À faire :
 
 - rejouer des bases neuves de test pour `pump_fun`, `pump_swap`, `raydium_cpmm` et `raydium_clmm`,
+- ne pas ajouter de nouveau DEX dans cette version ; cette version sert uniquement à valider les connecteurs déjà branchés,
 - vérifier pour chaque DEX le triptyque `decoded_event_count / trade_event_count / pair_candle_count`,
+- vérifier que les compteurs `diagnosticsClean`, `blockingIssueCount`, `actionableMissingTradeEventCount`, `duplicateDecodedEventTradeCount` et `duplicateCandleBucketCount` restent cohérents après replay,
 - garantir que les événements non pricés ou non candle ne produisent pas de trade event invalide,
 - conserver l’enrichissement `eventCategory`, `tradeCandidate`, `candleCandidate`, `liquidityCandidate`, `feeCandidate`, `rewardCandidate`, `adminCandidate` et `poolLifecycleCandidate` dans `payload_json`,
-- documenter les familles d’événements utilisées pour les candles et celles conservées seulement pour l’analyse ou la traçabilité,
-- ajouter ou compléter les tests unitaires sur `dex_decode`, `dex_detect`, `trade_aggregation`, `pair_candle_aggregation` et `pair_analytic_signal`,
-- ajouter des requêtes SQL de diagnostic de référence pour contrôler rapidement les tables clés après backfill,
-- conserver la tolérance aux événements DEX partiels tout en refusant les trades sans montant ou prix exploitable.
+- documenter les familles d’événements utilisées pour les candles et celles conservées seulement pour l’analyse, la liquidité, les frais, les rewards, l’administration ou la traçabilité,
+- ajouter ou compléter les tests unitaires sur `dex_decode`, `dex_detect`, `trade_aggregation`, `pair_candle_aggregation`, `pair_analytic_signal`, `local_pipeline_replay` et `local_pipeline_diagnostics`,
+- ajouter des requêtes SQL de diagnostic de référence pour contrôler rapidement les tables clés après backfill ou replay local,
+- conserver la tolérance aux événements DEX partiels tout en refusant les trades sans montant ou prix exploitable,
+- valider que les transactions échouées restent traçables dans les événements décodés sans produire de `kb_trade_events`.
 
-### 6.059. Version `0.7.27` — Raydium AMM v4 legacy : corpus et validation ciblée
-Objectif : isoler correctement le vrai Raydium AMM v4 historique et le distinguer de `raydium_cpmm` et `raydium_clmm`.
+### 6.060. Version `0.7.28` — Matérialisation des événements liquidité et cycle de vie pool
+Objectif : exploiter les événements non buy/sell utiles à l’analyse et au trading semi-automatique sans les mélanger avec les trades/candles.
+
+À faire :
+
+- stabiliser ou ajouter la table `kb_liquidity_events`,
+- stabiliser ou ajouter la table `kb_pool_lifecycle_events`,
+- matérialiser les événements de type `increase_liquidity`, `decrease_liquidity`, `add_liquidity`, `remove_liquidity`, `open_position`, `close_position`, `initialize`, `create_pool`, `migrate` et assimilés,
+- rattacher chaque événement métier à `dex_id`, `pool_id`, `pair_id`, `transaction_id`, `decoded_event_id`, `signature` et `slot`,
+- conserver le `payload_json` source pour audit et extension future,
+- alimenter les diagnostics locaux avec les compteurs liquidité et cycle de vie,
+- garantir qu’un événement de liquidité ou de cycle de vie ne produit jamais de candle directement,
+- préparer les signaux futurs liés à la liquidité initiale, à l’ajout/retrait brutal de liquidité, aux migrations et aux changements de statut de pool.
+
+### 6.061. Version `0.7.29` — Matérialisation des événements fees, rewards et administration
+Objectif : conserver les événements non price-action utiles au risque, à l’analyse économique et à la traçabilité opérationnelle des pools.
+
+À faire :
+
+- ajouter ou stabiliser `kb_fee_events`,
+- ajouter ou stabiliser `kb_reward_events`,
+- ajouter ou stabiliser `kb_pool_admin_events`,
+- matérialiser les événements `collect_protocol_fee`, `collect_fund_fee`, `collect_creator_fee`, `collect_fee` et assimilés,
+- matérialiser les événements `set_reward_params`, `initialize_reward`, `collect_reward`, `update_reward_infos` et assimilés,
+- matérialiser les événements `set_config`, `update_config`, `set_authority`, `set_fee_rate`, `pause`, `resume` et assimilés,
+- rattacher chaque événement à la transaction, au decoded event, au pool, à la paire et aux wallets observés lorsque les comptes sont disponibles,
+- documenter clairement que ces événements sont utiles à l’analyse et au scoring mais ne sont ni des trades ni des candles.
+
+### 6.062. Version `0.7.30` — Meteora : DBC / DAMM v1 / DAMM v2
+Objectif : ajouter ou stabiliser les connecteurs Meteora avec une séparation claire entre swaps, liquidité, fees, rewards et événements pool.
+
+À faire :
+
+- vérifier les programmes et discriminants réellement utilisés pour `Meteora DBC`, `Meteora DAMM v1` et `Meteora DAMM v2`,
+- constituer un petit corpus local de pools et signatures fiables pour chaque variante,
+- décoder les créations de pool, swaps et événements de liquidité exploitables,
+- alimenter `kb_dex_decoded_events`, les tables métier pool/pair/listing et les nouvelles tables d’événements non-trade,
+- vérifier l’idempotence du replay local sur un corpus mixte Meteora,
+- documenter les limites connues des variantes insuffisamment couvertes par le corpus.
+
+### 6.063. Version `0.7.31` — Launch DEX : LaunchLab / Fun Launch / Bags / Moonit
+Objectif : couvrir les surfaces de lancement et de migration de tokens sans confondre origine de lancement et protocole DEX final.
+
+À faire :
+
+- ajouter ou stabiliser les mappings `LaunchLab`, `Fun Launch`, `Bags` et `Moonit`,
+- distinguer clairement launch origin, pool origin et DEX effectif,
+- détecter les créations de token, pools initiaux, migrations et listings dérivés,
+- rattacher les launch origins aux pools et paires lorsque les comptes permettent un matching fiable,
+- enrichir les diagnostics pour exposer les objets détectés par surface de lancement,
+- éviter les heuristiques trop larges lorsqu’un suffixe de mint ou un label externe ne suffit pas à prouver l’origine.
+
+### 6.064. Version `0.7.32` — Orca / FluxBeam / DexLab : corpus et validation ciblée
+Objectif : ajouter les connecteurs restants à partir de corpus locaux vérifiables et garder les décodeurs heuristiques isolés tant qu’ils ne sont pas prouvés.
+
+À faire :
+
+- constituer des corpus locaux pour `Orca Whirlpools`, `FluxBeam` et `DexLab`,
+- vérifier les `program_id`, comptes, préfixes `data_json` et familles d’instructions utiles,
+- stabiliser les événements `create_pool`, `swap` et liquidité réellement observés,
+- alimenter les mêmes tables métier et diagnostics que les connecteurs déjà validés,
+- marquer explicitement les variantes partiellement supportées ou heuristiques,
+- rejouer les corpus plusieurs fois pour vérifier l’idempotence et l’absence de trades/candles invalides.
+
+### 6.065. Version `0.7.33` — Validation DEX v1 consolidée
+Objectif : rejouer tous les DEX supportés et valider les invariants du pipeline complet avant de traiter Raydium AMM v4 legacy séparément.
+
+À faire :
+
+- rejouer des bases neuves couvrant tous les connecteurs DEX supportés hors `raydium_amm_v4` legacy,
+- vérifier les compteurs globaux et par DEX : decoded events, trade events, liquidity events, lifecycle events, fee events, reward events, admin events, 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,
+- conserver une matrice de support par DEX, variante, instruction et type d’événement.
+
+### 6.066. Version `0.7.34` — Raydium AMM v4 legacy : corpus et validation ciblée
+Objectif : traiter le vrai Raydium AMM v4 historique après les autres DEX, afin de l’isoler correctement de `raydium_cpmm`, `raydium_clmm` et des labels Raydium génériques.
 
 À faire :
 
@@ -738,7 +854,7 @@ Objectif : isoler correctement le vrai Raydium AMM v4 historique et le distingue
 - renommer et stabiliser les fonctions internes autour de `raydium_amm_v4` afin d’éviter l’ambiguïté avec `raydium_cpmm` et `raydium_clmm`,
 - documenter les limites connues si le corpus AMM v4 reste trop faible.
 
-### 6.060. Version `0.7.28` — `kb_app` : overlays analytiques
+### 6.067. Version `0.7.35` — `kb_app` : overlays analytiques
 Objectif : rendre visibles les signaux analytiques directement sur les graphes et vues de marché.
 
 À faire :
@@ -749,7 +865,7 @@ Objectif : rendre visibles les signaux analytiques directement sur les graphes e
 - afficher un panneau latéral listant les signaux liés à une paire et à un timeframe,
 - préparer l’extension future vers des indicateurs Ichimoku, Kumo, projections ABCD et égalités temps/prix sans les mélanger au pipeline de décodage DEX.
 
-### 6.061. Version `0.7.29` — `kb_app` : vues consolidées token / pair / pool
+### 6.068. Version `0.7.36` — `kb_app` : vues consolidées token / pair / pool
 Objectif : fournir une lecture métier plus confortable du modèle `0.7.x`.
 
 À faire :
@@ -757,11 +873,11 @@ Objectif : fournir une lecture métier plus confortable du modèle `0.7.x`.
 - ajouter une fiche token avec mint, programme token, metadata, pools, paires et historique de découverte,
 - ajouter une fiche paire avec base/quote, DEX, pool, métriques, candles, signaux et derniers trades,
 - ajouter une fiche pool avec composition, vaults, origine, première signature vue, programme DEX et statut de décodage,
-- relier dans l’UI les launch origins, pool origins, wallets observés, holdings observés, candles et analytic signals,
+- relier dans l’UI les launch origins, pool origins, wallets observés, holdings observés, événements de liquidité, événements lifecycle, fees, rewards, admin, candles et analytic signals,
 - préparer une navigation transversale entre objets techniques et objets métier,
-- rendre explicites les cas `tradeCount = null`, `lastPriceQuotePerBase = null` et tokens non enrichis.
+- rendre explicites les cas `tradeCount = null`, `lastPriceQuotePerBase = null`, tokens non enrichis et événements conservés uniquement pour analyse.
 
-### 6.062. Version `0.7.30` — Finition UI `0.7.x`
+### 6.069. Version `0.7.37` — Finition UI `0.7.x`
 Objectif : stabiliser la couche desktop de validation avant l’ouverture de `0.8.x`.
 
 À faire :
@@ -772,25 +888,25 @@ Objectif : stabiliser la couche desktop de validation avant l’ouverture de `0.
 - préparer une base UI suffisamment stable pour la future phase d’analyse et filtrage `0.8.x`,
 - vérifier que les commandes Tauri restent de simples façades vers `kb_lib` et ne récupèrent pas de logique métier.
 
-### 6.063. Version `0.7.x` — Couverture DEX v1
+### 6.070. Version `0.7.x` — Couverture DEX v1
 Objectif : structurer les connecteurs DEX autour d’un pipeline complet de résolution, décodage et normalisation métier.
 
 Protocoles cibles :
 
+- Pump.fun
+- PumpSwap
+- Raydium CPMM
+- Raydium CLMM
 - Meteora DBC
 - Meteora DAMM v2
 - Meteora DAMM v1
 - LaunchLab / Fun Launch
-- Pump.fun
-- PumpSwap
-- Raydium AMM v4 legacy
-- Raydium CPMM
-- Raydium CLMM
-- Orca
 - Bags
+- Moonit
+- Orca
 - FluxBeam
 - DexLab
-- Moonit
+- Raydium AMM v4 legacy
 
 Résultat attendu :
 
@@ -799,11 +915,12 @@ Résultat attendu :
 - décodage des transactions utiles,
 - création d’objets métier riches pour tokens, pools, paires, listings, participants et holdings observés,
 - enrichissement metadata des tokens découverts,
-- séparation claire entre événements candle/trade et événements utiles seulement à l’analyse, aux frais, à la liquidité, aux rewards ou à l’administration,
+- séparation claire entre événements candle/trade et événements utiles seulement à l’analyse, aux frais, à la liquidité, aux rewards, à l’administration ou au cycle de vie des pools,
+- matérialisation progressive des événements non-trade dans des tables métier dédiées,
 - préparation d’une détection temps réel hybride et d’un backfill ciblé compatible avec les mêmes objets métier,
 - préparation d’agrégats DEX plus riches, de candles / OHLCV et d’une UI d’inspection du pipeline `0.7.x`.
 
-### 6.064. Version `0.8.x` — Analyse et filtrage
+### 6.071. Version `0.8.x` — Analyse et filtrage
 Objectif : transformer les événements bruts en signaux exploitables.
 
 À faire :
@@ -818,7 +935,7 @@ Objectif : transformer les événements bruts en signaux exploitables.
 - 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.065. Version `1.x.y` — Wallets et swap préparatoire
+### 6.072. Version `1.x.y` — Wallets et swap préparatoire
 Objectif : préparer la couche d’action.
 
 À faire :
@@ -829,7 +946,7 @@ Objectif : préparer la couche d’action.
 - préparation d’ordres et de swaps,
 - simulation et garde-fous.
 
-### 6.066. Version `2.x.y` — Trading semi-automatisé
+### 6.073. Version `2.x.y` — Trading semi-automatisé
 Objectif : brancher l’analyse à l’action tout en gardant des garde-fous explicites.
 
 À faire :
@@ -840,7 +957,7 @@ Objectif : brancher l’analyse à l’action tout en gardant des garde-fous exp
 - confirmations explicites ou semi-automatiques,
 - journaux d’exécution.
 
-### 6.067. Version `3.x.y` — Yellowstone gRPC
+### 6.074. Version `3.x.y` — Yellowstone gRPC
 Objectif : ajouter le connecteur gRPC dédié.
 
 À faire :
@@ -873,6 +990,11 @@ Modules cibles à court terme :
 - `pair_candle_aggregation.rs`
 - `pair_analytic_signal.rs`
 - `token_metadata.rs`
+- `local_pipeline_replay.rs`
+- `local_pipeline_diagnostics.rs`
+- `db/entities/*`
+- `db/dtos/*`
+- `db/queries/*`
 
 ### 7.2. `kb_app`
 Responsabilités cibles :
@@ -934,12 +1056,16 @@ Le projet doit maintenir au minimum :
 
 La priorité immédiate est désormais la suivante :
 
-1. ajouter l’enrichissement metadata des tokens afin que le catalogue affiche au minimum les symboles/noms résolus, sans hardcoder de mints hors SOL / WSOL,
-2. rejouer une campagne de validation multi-DEX sur bases neuves pour `pump_fun`, `pump_swap`, `raydium_cpmm` et `raydium_clmm`,
-3. constituer un corpus ciblé pour `raydium_amm_v4` legacy au lieu de s’appuyer sur des labels Raydium trop génériques,
-4. conserver les événements non-candle enrichis en payload pour l’analyse future, sans créer de trades invalides,
-5. ajouter les overlays des signaux analytiques sur les candles,
-6. consolider les vues métier `token / pair / pool` dans `kb_app`,
-7. stabiliser l’ergonomie, les filtres et la navigation de l’UI d’inspection,
-8. préparer ensuite l’ouverture de `0.8.x` pour l’analyse, les filtres, les patterns et les projections graphiques,
-9. préparer enfin Yellowstone gRPC comme extension de capacité, et non comme remplacement du socle HTTP / WS existant.
+1. terminer la validation `0.7.27` sur les connecteurs déjà branchés : `pump_fun`, `pump_swap`, `raydium_cpmm` et `raydium_clmm`, sans ajouter de nouveau DEX dans cette étape,
+2. vérifier sur bases neuves et après replay local les invariants bloquants du pipeline : `diagnosticsClean = true`, `blockingIssueCount = 0`, aucun trade candidate exploitable perdu, aucun trade event invalide, aucun doublon réel par `decoded_event_id`, aucune candle dupliquée par bucket,
+3. documenter les requêtes SQL de diagnostic de référence et les résultats attendus pour les tables clés du pipeline,
+4. matérialiser ensuite les événements non buy/sell utiles au trading et à l’analyse : liquidité, cycle de vie des pools, fees, rewards et administration,
+5. garantir que ces événements non-trade restent séparés des `kb_trade_events` et des candles tout en restant rattachés aux transactions, decoded events, pools, pairs et wallets observés,
+6. ajouter ou stabiliser les autres DEX par lots vérifiables : Meteora, surfaces de lancement, Orca, FluxBeam et DexLab,
+7. traiter `raydium_amm_v4` legacy seulement après les autres DEX, avec un corpus dédié prouvant le programme `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`,
+8. effectuer une validation DEX v1 consolidée sur tous les connecteurs supportés avant de considérer la couche DEX `0.7.x` comme stable,
+9. ajouter ensuite les overlays des signaux analytiques sur les candles,
+10. consolider les vues métier `token / pair / pool` dans `kb_app`, y compris les événements liquidité, lifecycle, fees, rewards et admin,
+11. stabiliser l’ergonomie, les filtres, la pagination et la navigation de l’UI d’inspection,
+12. préparer ensuite l’ouverture de `0.8.x` pour l’analyse, les filtres, les patterns et les projections graphiques,
+13. préparer enfin Yellowstone gRPC comme extension de capacité, et non comme remplacement du socle HTTP / WS existant.