3.1 KiB
Architecture du stockage
1. Responsabilité de ks-store
ks-store réunit :
- les contrats store-neutral ;
- les DTO et entités persistées ;
- la pagination et les rapports de santé ;
- les traits de repositories ;
- l’implémentation PostgreSQL ;
- les migrations, requêtes et mécanismes de replay associés.
La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL.
2. Frontières
2.1 Contrats store-neutral
Les contrats ne doivent pas dépendre des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages et erreurs nécessaires aux consommateurs.
2.2 Adaptateur PostgreSQL
Le module PostgreSQL possède :
- la connexion et l’initialisation ;
- l’application idempotente des migrations ;
- les requêtes typées ;
- les diagnostics ;
- les opérations de replay et de sélection de candidats.
2.3 Modèles partagés
Les modèles métier communs restent dans ks-lib lorsqu’ils dépassent la seule persistance. ks-store ne doit pas créer une seconde définition concurrente d’un contrat partagé.
3. Catégories de données
Le stockage couvre plusieurs niveaux :
- données brutes acquises ;
- transactions et instructions canoniques ;
- événements de décodage et diagnostics ;
- matérialisations ;
- états de campagne et candidats de replay ;
- informations opérationnelles et de santé.
Les noms de tables, contrats de replay et APIs publiques sont documentés dans ks-store/USAGE.md à partir des exports et migrations actuels.
4. Propriétés attendues
- initialisation idempotente ;
- pagination bornée ;
- traçabilité des campagnes ;
- absence de double effet lors des replays ;
- validation stricte des entrées ;
- erreurs explicites ;
- séparation entre données brutes, résultats de décodage et matérialisations.
La série 0.5.3 normalisera cette fondation avant l’arrivée des protocoles trading. Elle doit notamment distinguer slot, block_time et les timestamps d’acquisition/persistance, normaliser la structure interne de ks-store, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans perdre les contrats de provenance et d’idempotence.
La même migration remplace le préfixe historique des tables Solana kb_sol_* par k_sol_*. La base peut encore être reconstruite ou migrée proprement avant 0.6.x, il n’est donc pas nécessaire de conserver indéfiniment l’ancien préfixe. Le préfixe kb_* est réservé aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot, pas aux faits Solana simplement consommés par le bot.
5. Données de test
Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous test-fixtures/contract-matrices/ lorsqu’elles sont nécessaires aux tests.