<!-- file: docs/prompts/PROMPT_0_7_59_demo4_program_surface_discovery.md -->

# Prompt — 0.7.59 Demo4 Program Surface Discovery

## Contexte

Nous reprenons le workspace Rust `khadhroony-bobobot` après :

```text
0.7.57 -> meteora_dlmm clos
0.7.58 -> sqlite_db_transaction_merger + validation anti-régression cross-DEX
```

Décision de planification : `demo4_program_surface_discovery` est déplacé de `0.7.58` vers `0.7.59` afin de permettre d’abord la création d’une base consolidée `final.db`.

Cette base consolidée doit permettre à Demo4 d’explorer :

```text
program_id inconnus
program_id connus avec discriminants non mappés
Anchor logs Instruction non mappés
Program data events non mappés
upstream fallbacks
layouts répétitifs d’accounts/data
success/failed split
```

## Objectif principal

Ajouter une fenêtre `Demo4` dans `kb_demo_app` et les requêtes `kb_lib` associées pour afficher les surfaces non prises en compte sans les promouvoir automatiquement.

Demo4 est un outil d’observation, de tri et de préparation de futures tranches de decoder. Il ne doit pas créer de trade, candle, pool, pair, fee, reward, admin ou lifecycle métier.

## Règles strictes

Demo4 doit être read-only par défaut.

Interdictions :

- ne pas matérialiser automatiquement ;
- ne pas ajouter automatiquement de coverage comme supportée ;
- ne pas marquer automatiquement un `program_id` comme connu ;
- ne pas générer de decoder métier ;
- ne pas promouvoir un upstream fallback vers un decoder local sans intervention humaine ;
- ne pas masquer les failed transactions ;
- ne pas supprimer les observations existantes.

Actions autorisées :

- lister ;
- grouper ;
- scorer ;
- exporter Markdown/CSV/JSON ;
- marquer manuellement un candidat comme `reviewed`, `ignored`, `accepted_for_future_decoder`, si table de statut ajoutée ;
- ouvrir une signature dans Demo Pipeline 2 ou Demo3.

## Sources de données prioritaires

Demo4 doit exploiter la base consolidée construite par `0.7.58`, par exemple :

```text
final.db
final.next.db
```

Cette base est issue de merges raw-corpus de bases dédiées :

```text
pump_swap.db
pump_fun.db
pump_fees.db
raydium_*.db
meteora_*.db
```

Le bénéfice attendu : détecter les surfaces inconnues et les régressions qui n’apparaissent pas dans une base DEX isolée.

## Surfaces à afficher

### 1. Program IDs non routés

Afficher les `program_id` présents dans `k_sol_chain_instructions` qui ne correspondent pas à une surface supportée ou connue.

Colonnes utiles :

```text
program_id
instruction_count
tx_count
success_count
failed_count
first_slot
last_slot
sample_signature
sample_data_prefix
sample_account_count
```

### 2. Discriminators non mappés sur program id connu

Pour un `program_id` déjà supporté, afficher les discriminants inconnus ou encore en `instruction_audit`.

Colonnes utiles :

```text
protocol_guess
program_id
discriminator_hex
data_prefix
instruction_count
tx_count
success_count
failed_count
sample_signature
known_anchor_log_name si disponible
upstream_match_status si disponible
```

### 3. Anchor logs `Instruction: ...`

Extraire depuis `meta_json.logMessages` :

```text
Program log: Instruction: <Name>
```

Normaliser le nom :

```text
InitializePresetParameterV2 -> initialize_preset_parameter_v2
```

Calculer si possible :

```text
sha256("global:<snake_case_name>")[0..8]
```

Comparer au discriminator observé.

### 4. Program data / Anchor events non mappés

Lister les `Program data:` ou events Anchor observés mais non classés localement.

Colonnes utiles :

```text
program_id
anchor_event_discriminator_hex
payload_size
tx_count
success_count
failed_count
sample_signature
possible_event_name
upstream_match_status
```

### 5. Upstream fallbacks

Afficher les événements qui viennent encore de :

```text
upstream_git.instruction_match
upstream_git.event_match
instruction_audit
```

Demo4 doit aider à décider si l’entrée doit devenir :

```text
local decoder
coverage 0/0 conservée
decoded-only justifié
materialized admin/lifecycle/fee/reward/liquidity/orderbook
ignored
```

## UI attendue

Fichiers probables :

```text
kb_demo_app/src/demo4.html
kb_demo_app/src/demo4.ts
kb_demo_app/src/main.ts
kb_demo_app/src/shared/api.ts
kb_demo_app/src/shared/types.ts
```

Ajouter une fenêtre Tauri si nécessaire dans :

```text
kb_demo_app/src-tauri/src/main.rs
kb_demo_app/tauri.conf.json
```

Organisation UI suggérée :

```text
Filters:
  - program_id
  - protocol_guess
  - success/failed/all
  - minimum tx_count
  - known/unknown program
  - audit/upstream/unknown discriminator
  - date/slot range si disponible

Tabs:
  1. Unknown programs
  2. Known program unknown discriminators
  3. Anchor instruction logs
  4. Program data events
  5. Upstream fallbacks
  6. Regression suspects
```

## API / services kb_lib suggérés

Créer des DTOs sous :

```text
kb_lib/src/db/dtos/program_surface_candidate_summary.rs
kb_lib/src/db/dtos/program_surface_candidate_sample.rs
```

Créer des requêtes sous :

```text
kb_lib/src/db/queries/program_surface_discovery.rs
```

Créer éventuellement une façade :

```text
kb_lib/src/program_surface_discovery.rs
```

Rappel : si des requêtes DB sont ajoutées, mettre à jour les re-exports dans :

```text
kb_lib/src/db.rs
kb_lib/src/lib.rs
```

## Table de statut optionnelle

Si utile, ajouter :

```text
k_sol_program_surface_candidates
```

Statuts possibles :

```text
new
reviewed
accepted_for_future_decoder
ignored
promoted_manually
rejected
```

Ne jamais passer automatiquement à `promoted_manually`.

## Intégration avec 0.7.58

Demo4 doit intégrer explicitement la notion de source DB/merge si les tables `k_sol_db_merge_*` existent.

Exemples d’affichages utiles :

```text
candidate observed in sources: pump_swap.db, pump_fees.db
candidate observed only after final.db merge
candidate correlated with replay decode failure
candidate appears in transaction with multiple DEX protocols
```

Objectif : rendre visibles les régressions cross-surface comme le cas PumpSwap/PumpFees.

## SQL de validation Demo4

Ajouter :

```text
validation_sql/SQL_VALIDATION_DEMO4_PROGRAM_SURFACE_DISCOVERY_0_7_59.sql
```

Checks :

```sql
-- Demo4 queries should not create decoded/materialized rows
SELECT COUNT(*) FROM k_sol_dex_decoded_events;
SELECT COUNT(*) FROM k_sol_trade_events;

-- candidate status table should not auto-promote anything
SELECT status, COUNT(*)
FROM k_sol_program_surface_candidates
GROUP BY status;
```

Adapter selon schéma réel.

## Tests attendus

- requêtes unknown program sur fixture minimale ;
- discriminants inconnus sur program connu ;
- extraction Anchor `Instruction: Name` ;
- hash Anchor discriminator ;
- split success/failed ;
- no write en mode read-only ;
- export Markdown/CSV stable ;
- table statut manuelle si implémentée.

## Critères de clôture 0.7.59

- `cargo test -p kb_lib` OK ;
- `cargo test` UI/Tauri si existant OK ;
- clippy `-D warnings` OK ;
- Demo4 affiche les surfaces inconnues depuis `final.db` ;
- aucun auto-decode métier ;
- aucune auto-materialization ;
- export exploitable pour préparer `0.7.60 meteora_damm_v1` ou une tranche future ;
- README/ROADMAP/CHANGELOG mis à jour.

## Note finale

Demo4 ne remplace pas les prompts DEX. Il prépare les prochaines tranches en rendant les surfaces observées lisibles, priorisées et reproductibles.
