0.1.0

docs/POSTGRES_STORE.md

@@ -0,0 +1,91 @@
+<!-- file: docs/POSTGRES_STORE.md -->
+<!-- version: 10 -->
+
+# Store PostgreSQL canonique
+
+## Baseline active
+
+PostgreSQL reste le backend principal. Le store utilise le schéma courant du profil, généralement `public`, et ne qualifie pas les tables par un schéma applicatif explicite.
+
+La baseline active contient :
+
+```text
+kb_sol_raw_transactions
+kb_sol_obs_transaction_observations
+kb_sol_core_transactions
+kb_sol_core_account_keys
+kb_sol_core_instructions
+kb_sol_core_inner_instructions
+kb_sol_core_logs
+kb_sol_core_balance_changes
+kb_sol_ops_processing_ledger
+kb_sol_decode_events
+kb_sol_decode_coverage_declarations
+kb_sol_decode_coverage_observations
+kb_sol_mat_events
+```
+
+## Initialisation
+
+Le projet utilise encore des DDL idempotents gérés par `kb_store_pg`. `_sqlx_migrations` n’est pas requis pour démarrer l’application.
+
+Les fichiers SQL actifs sont conservés comme représentation lisible de la baseline :
+
+```text
+0001_canonical_transaction_store.sql
+0002_core_store.sql
+0003_processing_ledger.sql
+0004_decode_materialization_store.sql
+```
+
+Au démarrage Tauri, `initialize_store_schema()` applique une seule fois, dans l’ordre, les DDL raw, core puis decode/mat. Les connexions ouvertes ensuite par les commandes de démo désactivent `auto_initialize_schema` et ne relancent plus les migrations. Les méthodes spécialisées restent disponibles pour les tests et outils qui demandent explicitement l’initialisation d’un sous-ensemble dépendant.
+
+## Extraction canonique vers core
+
+`CoreExtractionStore` sélectionne les lignes raw, vérifie le ledger puis persiste un `CoreExtractionBundle` dans une transaction PostgreSQL unique.
+
+Le mode normal skippe la combinaison déjà réussie :
+
+```text
+processor version + signature + canonical hash
+```
+
+Le replay forcé remplace uniquement le graphe de la signature ciblée. Les autres signatures ne sont pas modifiées.
+
+## Tests PostgreSQL
+
+Les tests qui utilisent `KB_POSTGRES_TEST_URL` doivent être lancés sur une base dédiée ou suivis d’un nettoyage explicite.
+
+Depuis `0.4.1-pre.021`, les tests optionnels qui partagent une base PostgreSQL réelle acquièrent un verrou process-local test-only. Ce verrou évite les interblocages intermittents entre campagnes de tests parallèles sans changer le code runtime ni le schéma SQL.
+
+Les tests optionnels couvrent notamment le rollback atomique core/decode, la persistance réelle du ledger et la sémantique exacte des déclarations de couverture. `optional_postgres_core_extraction_rolls_back_partial_graph_from_env` :
+
+1. insère une ligne raw isolée ;
+2. tente de persister un bundle contenant deux account keys avec le même index ;
+3. attend une violation de l’index unique après le début de la transaction ;
+4. vérifie qu’aucune transaction core, account key ou entrée ledger n’a été conservée et que le raw reste `received` ;
+5. rejoue un bundle corrigé ;
+6. vérifie le passage à `core_extracted` et le ledger `succeeded` ;
+7. nettoie ses lignes de test.
+
+Commande de clôture :
+
+```bash
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb_store_pg -- --nocapture
+```
+
+Les contrôles réels déjà effectués sur la base principale ont confirmé :
+
+- 70 transactions raw et core ;
+- 70 entrées ledger `succeeded` ;
+- 84 tentatives après un force replay de 14 signatures ;
+- aucune duplication ni ligne fille orpheline ;
+- cardinalité core inchangée après remplacement forcé.
+
+
+## Couverture et skip decode
+
+`persist_decode_coverage_declarations()` synchronise le snapshot déclaré d’un processor/version et retourne des compteurs exacts : insertion réelle, modification/suppression du snapshot ou déclaration inchangée.
+
+Le test PostgreSQL `optional_postgres_same_version_and_hash_is_current_from_env` persiste un résultat `unsupported` puis vérifie que le même stage, processor, version, input key et input hash est reconnu comme courant par le ledger.