2.7 KiB
Architecture du stockage
1. Responsabilité de kb-store
kb-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 kb-lib lorsqu’ils dépassent la seule persistance. kb-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 kb-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 réauditera cette fondation avant l’arrivée des protocoles trading. Cet audit doit notamment distinguer les timestamps observés sur la blockchain des timestamps d’insertion et de mise à jour locaux, normaliser la structure interne de kb-store, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans casser les contrats de replay existants.
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.