0.7.36

ROADMAP.md

@@ -846,24 +846,33 @@ Réalisé :
 - 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` — Transactions inconnues et protocol candidates
+### 6.064. Version `0.7.32` — Sémantique des diagnostics et compteurs de validation
 Réalisé :
 
-- consolider `k_sol_transaction_classifications`, déjà présente, avec les catégories utiles au suivi DEX,
-- consolider `k_sol_protocol_candidates`, déjà présente, pour prioriser les programmes inconnus ou partiellement reconnus,
-- classifier les transactions résolues en catégories : known supported, known partial, known non-trade, unknown program, unknown protocol candidate, unknown event kind, failed transaction, non-actionable trade,
-- conserver les `program_id`, comptes, signatures, préfixes de `data`, logs et indices d’instructions utiles à l’analyse,
-- créer des requêtes de diagnostic pour repérer les programmes inconnus fréquents,
-- permettre de promouvoir plus tard un protocol candidate vers un vrai DEX/surface sans perdre l’historique,
-- garantir que ces tables n’alimentent jamais directement les trades/candles.
+- 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`.
 
-### 6.065. Version `0.7.33` — Pair trading readiness et routes de cotation
+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é :
 
-- classifier les paires `direct_wsol_quote`, `direct_stable_quote`, `inverse_wsol_base`, `inverse_stable_base`, `cross_quote_requires_router` et `non_trade_materialized` ;
-- exposer `quoteAssetClass` et `tradingRouteRequired` dans les diagnostics ;
-- éviter de bloquer la validation sur des paires seulement listées ou détectées sans trade matérialisé ;
-- préparer la future sélection des paires directement tradables versus paires nécessitant un router.
+- 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é :
@@ -875,13 +884,11 @@ Réalisé :
 - 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.
-- première tranche DLMM : reconnaître et persister `meteora_dlmm.add_liquidity`, `meteora_dlmm.remove_liquidity`, `meteora_dlmm.initialize_position` et `meteora_dlmm.initialize_bin_array` comme événements non-trade utiles ;
-- intégrer la matérialisation non-trade dans les backfills ciblés token/pool, pas uniquement dans le replay local, afin que les diagnostics reflètent immédiatement les événements DLMM non-trade décodés ;
-- distinguer `PositionOpen` et `PositionClose` dans `LiquidityEventKind` au lieu de rabattre les positions CLMM/DLMM sur `Add`/`Remove` ;
-- conserver `meteora_damm_v1` manquant comme warning non bloquant lorsque le corpus de backfill local ne contient pas ce DEX.
 
 ### 6.067. Version `0.7.35` — Événements non-trade v2 : fees, rewards et administration
-Réalisé :
+Objectif : conserver les événements utiles au risque, au scoring, à l’économie du pool et à la traçabilité opérationnelle.
+
+À faire :
 
 - ajouter `k_sol_fee_events`,
 - ajouter `k_sol_reward_events`,
@@ -893,20 +900,34 @@ Réalisé :
 - documenter clairement que ces événements ne sont ni des trades ni des candles.
 
 ### 6.068. Version `0.7.36` — Meteora : DBC / DAMM v1 / DAMM v2 / DLMM
-Objectif : consolider Meteora comme famille multi-programmes au lieu de traiter chaque variante comme un cas isolé incomplet.
+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.
 
 À faire :
 
-- vérifier les programmes et discriminants réellement utilisés pour `Meteora DBC`, `Meteora DAMM v1`, `Meteora DAMM v2` et `Meteora DLMM`,
-- ajouter `meteora_dlmm` à la couverture cible seulement après corpus fiable,
-- constituer un corpus local par variante,
-- décoder les créations de pool, swaps, liquidités et événements lifecycle exploitables,
-- identifier les cas où `DBC` sert de launch origin avant migration vers un AMM,
-- alimenter `k_sol_dex_decoded_events`, les tables pool/pair/listing, les origins et les tables non-trade,
-- vérifier l’idempotence du replay local sur un corpus Meteora mixte,
-- documenter les limites connues des variantes insuffisamment couvertes.
+- ajouter ou consolider un registre local des mints connus et stables : `SOL`, `WSOL`, `USDC`, `USDT`, puis autres mints seulement si vérifiés ;
+- améliorer le backfill metadata pour traiter les tokens déjà présents dans `k_sol_tokens` sans nécessiter un nouveau backfill transactionnel ;
+- enrichir les tokens depuis les sources disponibles : registre local, payloads DEX, comptes Token-2022, Metaplex, transactions déjà persistées ;
+- rafraîchir les `pair_symbol` après mise à jour des metadata de tokens ;
+- exposer des diagnostics précis : `tokenMetadataMissingCount` par `dexCode`, `quoteAssetClass`, mint connu/inconnu et origine de découverte ;
+- ajouter ou clarifier une commande UI dans `kb_demo_app` pour lancer le backfill metadata et rafraîchir le catalogue ;
+- garantir l’idempotence : relancer l’enrichissement metadata ne doit pas recréer tokens, pools, paires, trades, candles ou origins ;
+- conserver l’invariant de validation : le manque de metadata n’est pas un diagnostic bloquant tant que les trades/candles actionnables sont sains ;
+- ajouter le profil de validation `0.7.37_token_metadata_catalog_enrichment`.
 
-### 6.069. Version `0.7.37` — Launch surfaces : LaunchLab, LetsBonk, Bags, Moonshot/Moonit, Boop.fun, Believe
+### 6.070. Version `0.7.38` — Launch surfaces : LaunchLab, LetsBonk, Bags, Moonshot/Moonit, Boop.fun, Believe
 Objectif : détecter la première source de mint/lancement des tokens même lorsque le swap final se fait ailleurs.
 
 À faire :
@@ -921,7 +942,7 @@ Objectif : détecter la première source de mint/lancement des tokens même lors
 - rattacher les launch origins aux pools et paires lorsque les comptes permettent un matching fiable,
 - exposer les origins dans les diagnostics et l’UI d’inspection.
 
-### 6.070. Version `0.7.38` — Heaven : corpus, launch et AMM
+### 6.071. Version `0.7.39` — Heaven : corpus, launch et AMM
 Objectif : ajouter Heaven sans le classer trop tôt comme simple DEX ou simple launchpad.
 
 À faire :
@@ -933,7 +954,7 @@ Objectif : ajouter Heaven sans le classer trop tôt comme simple DEX ou simple l
 - documenter les limites si le corpus ne permet pas encore de matérialiser tous les événements,
 - vérifier que Heaven ne crée pas de candles invalides en cas d’événement de launch non pricé.
 
-### 6.071. Version `0.7.39` — Orca / FluxBeam / DexLab : corpus et validation ciblée
+### 6.072. Version `0.7.40` — Orca / FluxBeam / DexLab : corpus et validation ciblée
 Objectif : consolider les connecteurs déjà présents à partir de corpus locaux vérifiables.
 
 À faire :
@@ -945,7 +966,7 @@ Objectif : consolider les connecteurs déjà présents à partir de corpus locau
 - 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.072. Version `0.7.40` — Raydium AMM v4 legacy : corpus et validation ciblée
+### 6.073. Version `0.7.41` — Raydium AMM v4 legacy : corpus et validation ciblée
 Objectif : traiter le vrai Raydium AMM v4 historique après les autres Raydium, afin de l’isoler de `raydium_cpmm`, `raydium_clmm` et des labels Raydium génériques.
 
 À faire :
@@ -958,7 +979,7 @@ Objectif : traiter le vrai Raydium AMM v4 historique après les autres Raydium,
 - renommer/stabiliser les fonctions internes autour de `raydium_amm_v4` pour éviter l’ambiguïté avec `raydium_cpmm` et `raydium_clmm`,
 - documenter les limites connues si le corpus AMM v4 reste faible.
 
-### 6.073. Version `0.7.41` — Validation DEX v1 consolidée
+### 6.074. Version `0.7.42` — Validation DEX v1 consolidée
 Objectif : rejouer tous les DEX et launch surfaces supportés et valider les invariants du pipeline complet.
 
 À faire :
@@ -971,7 +992,7 @@ Objectif : rejouer tous les DEX et launch surfaces supportés et valider les inv
 - 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.074. Version `0.7.42` — `kb_demo_app` : overlays analytiques
+### 6.075. Version `0.7.43` — `kb_demo_app` : overlays analytiques
 Objectif : rendre visibles les signaux analytiques directement sur les graphes et vues de marché.
 
 À faire :
@@ -982,7 +1003,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 Ichimoku, Kumo, projections ABCD et égalités temps/prix sans les mélanger au pipeline de décodage DEX.
 
-### 6.075. Version `0.7.43` — `kb_demo_app` : vues consolidées token / pair / pool
+### 6.076. Version `0.7.44` — `kb_demo_app` : vues consolidées token / pair / pool
 Objectif : fournir une lecture métier plus confortable du modèle `0.7.x`.
 
 À faire :
@@ -994,7 +1015,7 @@ Objectif : fournir une lecture métier plus confortable du modèle `0.7.x`.
 - préparer une navigation transversale entre objets techniques et objets métier,
 - rendre explicites les cas `tradeCount = null`, `lastPriceQuotePerBase = null`, tokens non enrichis et événements conservés uniquement pour analyse.
 
-### 6.076. Version `0.7.44` — Finition UI `0.7.x`
+### 6.077. Version `0.7.45` — Finition UI `0.7.x`
 Objectif : stabiliser la couche desktop de validation avant l’ouverture de `0.8.x`.
 
 À faire :
@@ -1005,7 +1026,7 @@ 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`.
 
-### 6.077. Version `0.7.x` — Couverture DEX v1
+### 6.078. Version `0.7.x` — Couverture DEX v1
 Objectif : structurer les connecteurs DEX autour d’un pipeline complet de résolution, décodage, normalisation métier et classification des événements non-trade.
 
 Protocoles et surfaces cibles :
@@ -1048,7 +1069,7 @@ Résultat attendu :
 - 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.078. Version `0.8.x` — Analyse et filtrage
+### 6.079. Version `0.8.x` — Analyse et filtrage
 Objectif : transformer les événements bruts en signaux exploitables.
 
 À faire :
@@ -1063,7 +1084,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.079. Version `1.x.y` — Wallets et swap préparatoire
+### 6.080. Version `1.x.y` — Wallets et swap préparatoire
 Objectif : préparer la couche d’action.
 
 À faire :
@@ -1074,7 +1095,7 @@ Objectif : préparer la couche d’action.
 - préparation d’ordres et de swaps,
 - simulation et garde-fous.
 
-### 6.080. Version `2.x.y` — Trading semi-automatisé
+### 6.081. Version `2.x.y` — Trading semi-automatisé
 Objectif : brancher l’analyse à l’action tout en gardant des garde-fous explicites.
 
 À faire :
@@ -1085,7 +1106,7 @@ Objectif : brancher l’analyse à l’action tout en gardant des garde-fous exp
 - confirmations explicites ou semi-automatiques,
 - journaux d’exécution.
 
-### 6.081. Version `3.x.y` — Yellowstone gRPC
+### 6.082. Version `3.x.y` — Yellowstone gRPC
 Objectif : ajouter le connecteur gRPC dédié.
 
 À faire :
@@ -1215,20 +1236,17 @@ Le projet doit maintenir au minimum :
 
 ## 12. Priorité immédiate
 
-La priorité immédiate est désormais la suivante :
+La priorité immédiate est désormais `0.7.37_token_metadata_catalog_enrichment`.
 
-1. conserver la validation acquise `0.7.31` : transactions failed traçables mais exclues des `trade_events`, metrics et candles, aucun trade/candle candidate sans payload montant/prix exploitable, aucun diagnostic bloquant masqué,
-2. utiliser la matrice `0.7.29` (`kb_lib/src/dex_support_matrix.rs`) comme source commune pour le catalogue DEX, les mappings program id -> protocole, la classification transactionnelle et les protocol candidates,
-3. garder les clients HTTP/WS et managers réseau hors du refactor DEX tant qu’ils ne bloquent pas le pipeline,
-4. consolider les événements non-trade sans les confondre avec les trades/candles : lifecycle de pool, liquidité, fees, rewards, admin/config, migration et launch/mint,
-5. rattacher les launch surfaces aux tokens et aux pools migrés : Raydium LaunchLab/Launchpad, LetsBonk/Bonk.fun, Boop.fun, Moonshot/Moonit, Believe, Bags et Heaven,
-6. consolider Meteora avec corpus fiable : `meteora_dlmm`, `meteora_damm_v1`, `meteora_damm_v2`, `meteora_dbc` et `meteora_dlc` si le programme est confirmé,
-7. consolider Orca, FluxBeam et DexLab sur corpus,
-8. traiter `raydium_amm_v4` legacy seulement après les autres Raydium, avec corpus dédié prouvant le programme `675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8`,
-9. ajouter une matérialisation dédiée des transactions inconnues ou partiellement décodées pour analyser les DEX manquants sans polluer les trades/candles,
-10. 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,
-11. ajouter ensuite les overlays des signaux analytiques sur les candles,
-12. consolider les vues métier `token / pair / pool` dans `kb_demo_app`, y compris les événements liquidité, lifecycle, fees, rewards et admin,
-13. stabiliser l’ergonomie, les filtres, la pagination et la navigation de l’UI d’inspection,
-14. préparer ensuite l’ouverture de `0.8.x` pour l’analyse, les filtres, les patterns et les projections graphiques,
-15. préparer enfin Yellowstone gRPC comme extension de capacité, et non comme remplacement du socle HTTP / WS existant.
+Ordre de travail recommandé :
+
+1. conserver la validation acquise `0.7.36` : Meteora consolidé, transactions failed traçables mais non actionnables, swaps sans amounts classés `non_actionable_trade`, aucun diagnostic bloquant masqué ;
+2. améliorer le catalogue local : metadata de tokens, symboles, noms, asset classes et `pair_symbol` lisibles ;
+3. ajouter un registre local des mints connus et stables : `SOL`, `WSOL`, `USDC`, `USDT`, puis autres mints seulement après vérification ;
+4. permettre un backfill metadata idempotent sur les tokens déjà présents sans relancer un backfill transactionnel complet ;
+5. exposer les compteurs de metadata manquantes par DEX, asset class, quote asset et origine de découverte ;
+6. ajouter ou clarifier la commande UI permettant de relancer le backfill metadata et le refresh du catalogue ;
+7. vérifier que l’enrichissement metadata ne modifie pas les invariants DEX : pas de faux trades, pas de fausses candles, pas de recréation de pools/paires ;
+8. déplacer ensuite les launch surfaces vers `0.7.38` : Raydium LaunchLab/Launchpad, LetsBonk/Bonk.fun, Boop.fun, Moonshot/Moonit, Believe et Bags ;
+9. traiter Heaven en `0.7.39`, puis Orca/FluxBeam/DexLab, puis Raydium AMM v4 legacy ;
+10. effectuer une validation DEX v1 consolidée avant d’ouvrir réellement `0.8.x` pour l’analyse, les filtres, les patterns et les projections graphiques.