<!-- file: docs/DEVELOPMENT_ORDER.md -->
<!-- version: 9 -->

# Ordre de développement

## Principe

La priorité est de rendre chaque transaction exploitable avant de payer un flux temps réel enrichi. Le développement suit donc l’ordre : acquisition gratuite, transaction canonique, extraction core, décodeurs, matérialisations, puis sources live payantes.

## Ordre cible après `0.2.x`

- [x] `0.1.x` : logging, configuration, clients HTTP/WS standard, rôles et démos RPC.
- [x] `0.2.0` à `0.2.5` : conventions PostgreSQL, stores raw/core historiques et diagnostics SQL.
- [x] `0.3.0` : cadrage Agave local historique, ensuite abandonné comme axe actif après mesures réelles.
- [x] `0.3.1` : transaction canonique, observations légères, validation PostgreSQL réelle et consolidation de la baseline SQL.
- [x] `0.3.2` : modèle canonique et adaptateur HTTP `getTransaction`.
- [x] `0.3.3` : backfill gratuit par signatures, programme, token et pool, avec parcours avant/après et arrêt coopératif borné.
- [~] `0.3.4` : extraction core, navigateur de candidats, intégrité et replay validés ; derniers tests automatisés de rollback/annulation à exécuter.
- [ ] `0.4.0` : infrastructure commune de décodage et de matérialisation.
- [ ] `0.4.1+` : décodeurs et matérialisations Solana Core/SPL.
- [ ] `0.5.x` : Pump.
- [ ] `0.6.x` : Meteora.
- [ ] `0.7.x` : Raydium.
- [ ] `0.8.x` : Orca.
- [ ] `0.9.x` : Jupiter, routeurs et surfaces complémentaires.
- [ ] `0.10.x` : Helius `transactionSubscribe`, Yellowstone gRPC, fallback standard et comparaison fournisseur.
- [ ] `0.11.x` : wallet, sécurité et démos devnet.
- [ ] `0.12.x` : listeners métier et trading assisté.

## Ordre technique de stockage

1. Maintenir une baseline SQL courante ne contenant que les tables actives.
2. Normaliser chaque source vers un contrat canonique dans `kb_model`.
3. Écrire une transaction unique dans `kb_sol_raw_transactions`.
4. Écrire une observation légère dans `kb_sol_obs_transaction_observations`.
5. Extraire les tables `kb_sol_core_*` depuis la transaction canonique.
6. Ajouter les observations programme/instruction nécessaires aux décodeurs.
7. Ajouter les tables `kb_sol_decode_*` et `kb_sol_mat_*` par surface.
8. Ajouter les sources live payantes seulement lorsque les décodeurs peuvent exploiter immédiatement le flux.

## Séquence par surface

```text
program ids
  -> corpus de signatures
    -> backfill gratuit
      -> decodeur maximal
        -> événements stables
          -> matérialisation complète
            -> replay et anti-régression
              -> listener live
```

## Démos

`kb_app_demo` reste le shell unique pour :

- diagnostics DB ;
- backfills ;
- inspection canonique/core ;
- couverture des décodeurs ;
- comparaison future des sources live ;
- wallet et sécurité.

## Contraintes permanentes

- Ne pas créer de schémas PostgreSQL applicatifs explicites.
- Utiliser le format `kb_sol_<domain>_<name>`.
- Ne pas placer de structures Rust dans `queries/`.
- Ne pas faire dépendre les décodeurs du store concret.
- Ne pas faire dépendre les décodeurs du fournisseur d’acquisition.
- Intégrer Helius et Yellowstone dans `kb_rpc`, sans crate provider séparée.
- Ne pas modifier `CHANGELOG.md` avant validation locale du jalon.

## État de clôture `0.3.4-pre.011`

L’ordre technique est concrétisé jusqu’à l’écriture core et aux outils de replay :

```text
backfill HTTP
-> transaction canonique
-> sélection raw bornée
-> extraction core pure
-> commit PostgreSQL atomique
-> ledger version/hash
-> sélection et export de corpus
```

Les validations réelles couvrent 70 transactions core, l’intégrité SQL, l’écriture CSV, le skip et le force replay sur 14 signatures. `pre.011` automatise le dernier contrôle de rollback PostgreSQL et rend les attentes réseau/retry annulables.

L’ancien jalon `0.3.5` est supprimé. Après validation de `pre.011` et mise à jour du changelog, la prochaine version active est directement `0.4.0`.