0.1.0

docs/CORE_STORE.md

@@ -0,0 +1,73 @@
+<!-- file: docs/CORE_STORE.md -->
+<!-- version: 3 -->
+
+# Store core Solana
+
+## Évolution `0.3.4`
+
+Le store core historique devient alimenté par un extracteur transactionnel à partir de `kb_sol_raw_transactions.canonical_json`.
+
+| Table                            | Rôle                                                       |
+|----------------------------------|------------------------------------------------------------|
+| `kb_sol_core_transactions`       | Transaction normalisée, statut et lien vers la ligne raw.  |
+| `kb_sol_core_account_keys`       | Espace résolu statique + ALT avec flags Solana.            |
+| `kb_sol_core_instructions`       | Instructions top-level et payload canonique hashé.         |
+| `kb_sol_core_inner_instructions` | Inner instructions rattachées à un chemin parent.          |
+| `kb_sol_core_logs`               | Logs ordonnés, texte hashé et lien d’invocation optionnel. |
+| `kb_sol_core_balance_changes`    | Deltas natifs, SPL Token et Token-2022.                    |
+| `kb_sol_ops_processing_ledger`   | Version, hash, statut et tentatives du processor.          |
+
+## Écriture atomique
+
+Une extraction réussie exécute dans la même transaction PostgreSQL :
+
+1. validation du bundle ;
+2. recherche d’un graphe core existant ;
+3. suppression en cascade de ce graphe pour la signature ;
+4. insertion de la transaction et de toutes ses lignes filles ;
+5. passage de la ligne raw à `core_extracted` ;
+6. upsert du ledger en `succeeded` ;
+7. commit.
+
+Une erreur déclenche le rollback implicite de la transaction. L’enregistrement terminal d’un échec utilise une transaction dédiée et marque la ligne raw `failed` avec un diagnostic rejouable.
+
+## Clés d’idempotence
+
+Les contraintes actives restent :
+
+```text
+core transaction        : signature
+account key              : signature + account_index
+instruction top-level    : signature + instruction_path
+inner instruction        : signature + instruction_path
+log                      : signature + log_index
+balance change           : signature + balance_change_index
+ledger                   : stage + processor_name + processor_version + input_key
+```
+
+Le ledger ajoute `input_hash` à la décision de skip sans l’ajouter à la clé unique. Un nouvel hash met à jour la même identité de processor et augmente `attempt_count`.
+
+## Sélection raw
+
+Le contrat `CoreExtractionSelectionFilter` permet :
+
+- une liste de signatures ;
+- une plage inclusive de slots ;
+- un état raw ;
+- un program id déjà indexé dans les instructions core ;
+- une limite stricte.
+
+Le filtre par program id est un mode de replay. Il ne peut pas découvrir un programme dans une transaction qui n’a jamais encore été extraite.
+
+## Repositories
+
+`CoreExtractionStore` isole le pipeline du backend :
+
+```text
+list_raw_transactions_for_core_extraction
+is_core_extraction_current
+persist_core_extraction
+mark_core_extraction_failed
+```
+
+Les repositories historiques d’insertion unitaire restent disponibles, mais le worker `0.3.4` utilise exclusivement l’écriture atomique du bundle.