<!-- file: kb-store/USAGE.md -->
<!-- version: 3 -->

# Utilisation de kb-store

## Connexion PostgreSQL

```rust
let options = match kb_store::PostgresStoreOptions::new(
    database_url,
    10,
    10_000,
    true,
) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("postgres endpoint: {}", options.masked_dsn());

let store = match kb_store::PostgresStore::connect(options).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};
```

`PostgresStoreOptions::new` valide le DSN, le nombre de connexions et le timeout. Lorsque `auto_initialize_schema` vaut `true`, la connexion applique les schémas idempotents. Utiliser `masked_dsn` ou `mask_postgres_dsn` dans les logs ; ne jamais journaliser le DSN brut.

## Diagnostics

```rust
let health = store.health_snapshot().await;
let migrations = store.migration_snapshot().await;
let backend = store.backend_diagnostics().await;

println!("health={:?}", health.status);
println!("migration={:?}", migrations.status);
println!("backend={:?}", backend.descriptor.backend);
```

Les diagnostics de tables raw, Core et decode/materialization sont également disponibles par les méthodes `*_table_diagnostics`.

```rust
let raw_tables = match store.raw_table_diagnostics().await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

for table in raw_tables {
    println!(
        "table={} domain={} exists={}",
        table.table_name,
        table.domain,
        table.exists
    );
}
```

## Pagination bornée

```rust
let first_page = kb_store::PageRequest::first_page();

let next_page = match kb_store::PageRequest::new(250, 250) {
    Ok(value) => value,
    Err(error) => return Err(error),
};

assert_eq!(first_page.limit, kb_store::DEFAULT_PAGE_SIZE);
assert!(next_page.limit <= kb_store::MAX_PAGE_SIZE);
```

## Contrats de repositories

Les traits publics principaux sont :

- `StoreHealthStore` ;
- `RawTransactionStore` ;
- `CoreTransactionStore` ;
- `CoreExtractionStore` ;
- `DecodePipelineStore` ;
- `ProgramObservationStore` ;
- `DecodedEventStore` ;
- `MaterializedEventStore` ;
- `ProcessingLedgerStore`.

Ils permettent au pipeline de dépendre d’un contrat async plutôt que d’une requête SQL directe.

## Replay et requêtes bornées

```rust
let candidates = match store.replay_transaction_candidates(filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

for candidate in candidates {
    println!(
        "signature={} slot={}",
        candidate.signature,
        candidate.slot
    );
}
```

```rust
let programs = match store.replay_program_summaries(program_filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

let entities = match store.replay_entity_summaries(entity_filter).await {
    Ok(value) => value,
    Err(error) => return Err(error),
};

println!("programs={}, entities={}", programs.len(), entities.len());
```

Les filtres refusent les limites nulles ou supérieures aux bornes publiques. `PageRequest` impose également `DEFAULT_PAGE_SIZE` et `MAX_PAGE_SIZE`.

## Transactions atomiques

Les bundles `CoreExtractionBundle`, `DecodePersistenceBundle` et `MaterializationPersistenceBundle` regroupent les écritures qui doivent réussir ou être annulées ensemble. Les consommateurs ne doivent pas reproduire manuellement ces transactions avec des écritures isolées.

## Validation des noms de tables

```rust
if let Err(error) = kb_store::validate_raw_store_table_names() {
    return Err(error);
}
if let Err(error) = kb_store::validate_core_store_table_names() {
    return Err(error);
}
if let Err(error) = kb_store::validate_decode_store_table_names() {
    return Err(error);
}

assert!(kb_store::is_valid_solana_table_name(
    kb_store::CORE_TRANSACTIONS_TABLE_NAME
));
```

## Schéma et tables

Les constantes `RAW_STORE_TABLE_NAMES`, `CORE_STORE_TABLE_NAMES` et `DECODE_STORE_TABLE_NAMES` exposent les noms canoniques. Les fonctions `validate_*_table_names` et `is_valid_solana_table_name` servent aux audits et outils d’administration.

## Erreurs et invariants

Toutes les APIs utilisent `kb_core::Result`. Les DTO valident notamment les signatures, chemins, Program IDs, clés, montants, états de traitement et identités de ledger. Les erreurs de contrat peuvent être construites avec `storage_contract_error`.

## Tests instructifs

- les tests `*_rejects_*` documentent les invariants des DTO et filtres ;
- `decoded_events_and_ledger_roll_back_together` vérifie l’atomicité ;
- `optional_postgres_*_from_env` couvre les parcours réels lorsque l’environnement PostgreSQL est configuré ;
- les tests de schéma vérifient les noms, index, contraintes et migrations.

## Limites

- backend actif : PostgreSQL ;
- les tests réels sont optionnels sans DSN de test ;
- la crate ne prend aucune décision de décodage ou de matérialisation.