v0.1.0-pre.067

docs/architecture/STORAGE_ARCHITECTURE.md

@@ -0,0 +1,64 @@
+<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# 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 exacts de tables et APIs publiques seront 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.
+
+## 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.