0.1.0-pre.004

kb-store/README.md

@@ -0,0 +1,126 @@
+<!-- file: kb-store/README.md -->
+<!-- version: 1 -->
+
+# `kb-store`
+
+`kb-store` regroupe les contrats de persistance neutres et l’adaptateur PostgreSQL de production de Khadhroony Bot3.
+
+La crate remplace l’ancienne séparation physique entre contrats et PostgreSQL, sans mélanger leurs responsabilités. Tous les modules restent privés et l’API stable est réexportée depuis `src/lib.rs`.
+
+## Architecture
+
+```text
+src/
+├── lib.rs
+├── constants.rs
+├── contracts.rs
+├── contracts/
+│   ├── dto.rs
+│   ├── dto/
+│   ├── entity.rs
+│   ├── entity/
+│   ├── error.rs
+│   ├── health.rs
+│   ├── pagination.rs
+│   └── repository.rs
+├── postgres.rs
+└── postgres/
+    ├── migrations.rs
+    ├── query.rs
+    ├── query/
+    ├── replay_candidates.rs
+    ├── repository.rs
+    ├── repository/
+    ├── store.rs
+    └── test_serial.rs
+```
+
+`contracts` ne dépend d’aucun backend. `postgres` implémente ces contrats avec `sqlx`. `lib.rs` ne contient aucune logique métier.
+
+## Direction des dépendances
+
+```text
+kb-core
+   ↑
+kb-lib ← kb-store
+```
+
+`CoreInstructionReplayInput` et sa version de contrat appartiennent à `kb-lib`, car ils sont partagés avec les décodeurs. `kb-store` les consomme et les réexporte. `kb-lib` ne dépend jamais de `kb-store`.
+
+`kb-store` ne dépend pas de `kb-config`. L’application résout sa configuration, puis construit explicitement `PostgresStoreOptions`. Cette séparation évite de coupler la persistance à la forme évolutive des profils.
+
+## Contrats publics
+
+Les familles principales sont :
+
+- transactions raw et observations d’acquisition ;
+- graphe core Solana : transaction, comptes, instructions, inner instructions, logs et balances ;
+- sélection et lifecycle de replay ;
+- extraction core atomique ;
+- décodage, couverture et matérialisation atomiques ;
+- ledger de traitement versionné ;
+- santé, migrations et pagination bornée.
+
+Les traits publics sont :
+
+- `StoreHealthStore` ;
+- `RawTransactionStore` ;
+- `CoreTransactionStore` ;
+- `CoreExtractionStore` ;
+- `DecodePipelineStore` ;
+- `ProgramObservationStore` ;
+- `DecodedEventStore` ;
+- `MaterializedEventStore` ;
+- `ProcessingLedgerStore`.
+
+## PostgreSQL
+
+`PostgresStore` fournit :
+
+- connexion depuis `PostgresStoreOptions` validées ;
+- création depuis un `sqlx::PgPool` existant ;
+- initialisation idempotente des tables raw, core, decode, materialization et ledger ;
+- diagnostics de backend, migrations et tables ;
+- sélections bornées de candidats de replay ;
+- implémentations des traits store-neutral.
+
+Les transactions raw sont immuables. Les écritures core, decode et materialization conservent leur lineage et utilisent le ledger pour le skip version/hash, le force replay et l’idempotence.
+
+Exemple :
+
+```rust
+let options = match kb_store::PostgresStoreOptions::new(
+    database_url,
+    8,
+    5_000,
+    true,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+let store = match kb_store::PostgresStore::connect(options).await {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+return std::result::Result::Ok(store);
+```
+
+## Validation
+
+```bash
+cargo fmt --all
+cargo check -p kb-store
+cargo test -p kb-store
+cargo clippy -p kb-store --all-targets
+KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
+  cargo test -p kb-store -- --nocapture
+```
+
+La validation complète du jalon ajoute :
+
+```bash
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets
+```
+