khadhroony-bobobot/NEXT_SESSION_PROMPT_0.7.47_UPSTREAM_REGISTRY.md

# Prompt de reprise — khadhroony-bobobot `0.7.47`

Reprise du projet `khadhroony-bobobot`.

## Contexte

Le workspace contient principalement :

- `kb_lib` : logique métier Solana/DEX, clients HTTP/WS, décodage, détection, SQLite, replay, validation, diagnostics, metadata, candles, signaux ;
- `kb_demo_app` : application Tauri V2 de démo/inspection. Elle doit rester une façade UI et ne pas contenir de logique métier DEX profonde.

La version `0.7.46` est clôturée sur `meteora_damm_v1`.

## État validé à la fin de `0.7.46`

- `cargo test -p kb_lib` : vert.
- `cargo clippy -p kb_lib --all-targets -- -D warnings` : vert.
- Demo2 et Demo3 fonctionnent bien pour backfill et discovery.
- Demo3 supporte :
  - multi-target ;
  - multi-source ;
  - pagination `before` / `until` ;
  - `max_pages` ;
  - `newest_first` / `oldest_first`.
- Le replay local supporte le ledger de décodage/replay et les options `skipDexDecode` / `forceDexDecode`.
- `meteora_damm_v1` couvre les surfaces observées localement :
  - `swap` ;
  - `claim_fee` ;
  - `create_lock_escrow` ;
  - `lock_liquidity` ;
  - `remove_liquidity` ;
  - `add_liquidity` ;
  - `create_pool`.
- Les statuts/payloads ne doivent plus utiliser une terminologie spécifique à un dépôt externe particulier.
- Les statuts génériques attendus sont :
  - `upstream_git_unverified` ;
  - `upstream_git_mapped_unverified` ;
  - `upstream_git_local_corpus_observed` ;
  - `upstream_git_local_corpus_materialized` ;
  - `upstream_git_layout_unverified` si le layout est connu depuis une source Git mais pas encore validé localement.

## Décision base de données pour `0.7.47`

La version `0.7.46` est considérée finalisée. Ne pas demander ni proposer de replay forcé de l’ancienne base `0.7.46` pour clôturer cette version, sauf demande explicite.

Pour `0.7.47`, le développement et la validation doivent se faire de préférence sur une **nouvelle base SQLite dédiée**. Cette base servira à constituer un corpus propre avec Demo3 et Demo2 sur plusieurs paires, pools ou programmes de DEX différents.

Règles pratiques :

- l’ancienne base `0.7.46` peut servir de référence historique ou de comparaison, mais elle ne doit pas être migrée ou redécodée automatiquement ;
- si une validation DB est nécessaire en `0.7.47`, elle doit cibler la nouvelle base de travail `0.7.47` ;
- les backfills `0.7.47` doivent être construits à partir de Demo3 discovery puis Demo2 signature/pool backfill ;
- le replay local reste utile, mais seulement après constitution du corpus `0.7.47`, pas comme étape de finalisation de `0.7.46` ;
- les entrées du registre upstream Git restent des indices tant qu’elles ne sont pas observées sur cette nouvelle base ou sur un corpus explicitement indiqué.

## Objectif de `0.7.47`

`0.7.47` est dédiée à :

```text
Upstream Git Registry / DEX discovery preparation
```

L’objectif n’est pas de valider directement un DEX unique. L’objectif est de créer un registre générique permettant d’indexer les `program_id`, discriminants d’instructions, discriminants d’events, noms d’instructions, familles de programmes et types de surfaces issus de dépôts Git externes de decoders Solana.

Ces entrées sont des **indices de découverte**, pas des preuves métier. Elles doivent rester non vérifiées tant qu’elles ne sont pas confirmées par :

1. Demo3 discovery ;
2. backfill signature/pool via Demo2 ;
3. replay local sur la base de travail `0.7.47` ;
4. requêtes SQL de validation sur cette même base ;
5. invariants métier : pas de faux trade, pas de fausse candle, pas de promotion de `program_id` sans corpus.

## Noms recommandés

Modules possibles :

```text
kb_lib/src/upstream_registry.rs
kb_lib/src/upstream_registry_types.rs
kb_lib/src/upstream_registry_match.rs
kb_lib/src/upstream_registry_generated.rs
```

Nom fonctionnel :

```text
Upstream Git Registry
```

Ne pas utiliser de nom de dépôt externe spécifique dans les noms publics, les statuts, les tables ou les payloads métier.

## Première tranche attendue

Créer une première version statique du registre dans `kb_lib`, sans modifier la DB si ce n’est pas nécessaire.

Chaque entrée de registre devrait contenir au minimum :

```text
source_repo
source_path
decoder_code
program_id
program_family
surface_kind
entry_kind = instruction | event | account | program
entry_name
discriminator_hex
discriminator_len
proof_status
notes
```

Les entrées de registre doivent être exposées à `kb_demo_app` via une commande Demo3 ou une commande dédiée, mais la logique reste dans `kb_lib`.

## Familles à indexer en priorité

DEX / AMM / CLMM / orderbook :

```text
meteora_damm_v2
meteora_dbc
meteora_dlmm
meteora_vault
raydium_amm_v4
raydium_clmm
raydium_cpmm
raydium_launchpad
raydium_liquidity_locking
raydium_stable_swap
orca_whirlpools
fluxbeam
lifinity_v2
phoenix_v1
openbook_v2
stabble_stable_swap
stabble_weighted_swap
bonkswap
boop
moonshot
heaven
okx_dex
pancake_swap
vertigo
virtuals
wavebreak
onchain_labs_dex_v1
onchain_labs_dex_v2
```

Agrégateurs / ordres / perps / lending :

```text
jupiter_swap
jupiter_dca
jupiter_limit_order
jupiter_limit_order_2
jupiter_perpetuals
jupiter_lend
kamino_lending
kamino_vault
kamino_farms
kamino_limit_order
drift_v2
marginfi_v2
dflow_aggregator_v4
zeta
```

Contexte transactionnel non DEX :

```text
system_program
token_program
token_2022
associated_token_account
address_lookup_table
memo_program
stake_program
mpl_token_metadata
mpl_core
bubblegum
name_service
marinade_finance
solayer_restaking_program
swig
sharky
circle_message_transmitter_v2
circle_token_messenger_v2
```

## Règles de validation

- Une entrée upstream Git reste `upstream_git_unverified` tant qu’elle n’a pas été vue localement.
- Une entrée branchée dans un decoder mais jamais vue localement reste `upstream_git_mapped_unverified`.
- Une entrée vue après Demo3/backfill/replay peut devenir `upstream_git_local_corpus_observed`.
- Une entrée qui alimente correctement une table métier dédiée peut devenir `upstream_git_local_corpus_materialized`.
- Aucun `program_id`, event ou discriminator ne doit être déclaré vérifié uniquement parce qu’il existe dans un dépôt Git externe.
- Aucun event non-trade ne doit produire trade, metric ou candle.

## Contraintes de code

- Rust 2024.
- Pas de `mod.rs`.
- Fichiers Rust avec entête `// file: ...`.
- Fichiers `.toml` avec entête `# file: ...`.
- Exposition centralisée via `lib.rs`.
- `#![deny(unreachable_pub)]` et `#![warn(missing_docs)]`.
- Pas de `anyhow`.
- Pas de `thiserror`.
- Pas de `?`, `unwrap`, `expect` dans le code applicatif.
- Utiliser `match`, `if let Err`, `let Err = ... else`.
- Tests verts à chaque étape.
- Si une requête DB est ajoutée/modifiée, mettre à jour les re-exports dans `kb_lib/src/db.rs`, puis `kb_lib/src/lib.rs` si nécessaire.

## Format de livraison attendu

Pour chaque tranche :

1. expliquer brièvement les fichiers touchés ;
2. fournir une archive des fichiers ajoutés/modifiés seulement, avec l’arborescence du projet ;
3. indiquer les commandes de test à lancer ;
4. indiquer les requêtes SQL utiles si validation DB nécessaire ;
5. ne jamais prétendre qu’un `program_id` ou un event est vérifié sans preuve/corpus.


dexlab
bags / letsbonk / bonk_fun
believe
moonit
launchbeam
metadao / metaDAO
printr
zora
aldrin
aldrin_v2
crema
cropper
cropper_legacy
guacswap
invariant
lifinity_v1
openbook_v1 / serum-style legacy
orca_v1
orca_v2
saber
saros
serum_v3
token_swap