# 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.