v0.5.3-pre.002

docs/architecture/STORAGE_ARCHITECTURE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
-<!-- version: 5 -->
+<!-- version: 7 -->
 
 # Architecture du stockage
 
@@ -7,30 +7,38 @@
 
 `ks-store` réunit :
 
+- la façade publique backend-agnostique `Store` et ses options d'ouverture ;
 - les contrats store-neutral ;
 - les DTO et entités persistées ;
-- la pagination et les rapports de santé ;
+- la pagination, le replay et les rapports de santé ;
 - les traits de repositories ;
-- l’implémentation PostgreSQL ;
-- les migrations, requêtes et mécanismes de replay associés.
+- les résumés runtime/init sanitisés ;
+- l’implémentation PostgreSQL privée ;
+- les migrations et requêtes appartenant au backend actif.
 
-La consolidation remplace l’ancien découpage entre plusieurs crates de stockage sans supprimer la séparation interne entre contrats et adaptateur PostgreSQL.
+Depuis `0.5.3-pre.002`, les consommateurs ne construisent plus un backend concret. `ks-store` possède la connexion et le dispatch interne ; `PostgresStore`, `PgPool` et SQLx ne traversent plus sa frontière publique.
 
 ## 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.
+Les contrats ne dépendent pas des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages, diagnostics et erreurs nécessaires aux consommateurs. `StoreOpenOptions` transporte un code backend et un objet d'options opaque ; seul `ks-store` interprète le moteur sélectionné.
+
+Le résumé runtime expose des modèles logiques et des compteurs d'objets par catégorie sans publier les noms physiques. PostgreSQL peut ainsi exposer des compteurs `table`/`index`, tandis qu'un futur backend peut utiliser d'autres catégories sans modifier le desktop.
 
 ### 2.2 Adaptateur PostgreSQL
 
 Le module PostgreSQL possède :
 
+- la validation de ses options ;
 - 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.
+- les diagnostics physiques ;
+- les opérations de replay et de sélection de candidats ;
+- le target de tracing canonique `ks-store`, enrichi des champs `backend="postgres"`, `domain="ks-store.pg"` et `action` pour les opérations PostgreSQL.
+
+Les détails physiques restent privés. Les erreurs et résumés traversant la façade ne doivent pas divulguer de DSN, password ou option sensible.
 
 ### 2.3 Modèles partagés
 
@@ -38,14 +46,14 @@ Les modèles métier communs restent dans `ks-lib` lorsqu’ils dépassent la se
 
 ## 3. Catégories de données
 
-Le stockage couvre plusieurs niveaux :
+Le stockage distingue quatre niveaux durables :
 
-- 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é.
+- **N1** — acquisition et raw canonique ;
+- **N2** — Core Solana canonique ;
+- **N3** — decode/materialization générique et journaux versionnés ;
+- **N4** — projections spécialisées/queryables additives.
+
+N1/N2/N3 constituent la fondation fortement gelée après `0.5.3`, sous réserve d'une urgence ou d'une omission structurelle majeure. N4 reste plus évolutif. Les replays N1 -> N2, N2 -> N3 et N3 -> N4 doivent pouvoir être exécutés indépendamment et de manière idempotente.
 
 Les noms de tables, contrats de replay et APIs publiques sont documentés dans `ks-store/USAGE.md` à partir des exports et migrations actuels.