0.1.0

docs/DEVELOPMENT_ORDER.md

@@ -0,0 +1,91 @@
+<!-- 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`.