<!-- file: docs/guides/POSTGRES_STORAGE.md -->
<!-- version: 1 -->

# Guide PostgreSQL et contrats de stockage

## Objectif

`kb-store` consolide les contrats de stockage Core, raw, decode et PostgreSQL de bot2 dans une crate unique.

## Connexion

```rust
let options = match kb_store::PostgresStoreOptions::new(
    database_url,
    10,
    10_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),
};
```

Toujours utiliser `masked_dsn()` dans les diagnostics.

## Domaines

- raw : acquisitions et observations ;
- Core : transactions, instructions, comptes et contexte normalisés ;
- decode : ledger, observations décodées et matérialisations ;
- replay : candidats et résumés bornés.

## Migrations

Les migrations sont idempotentes et ordonnées. Une nouvelle migration ne doit pas modifier rétroactivement une migration déjà publiée.

## Repositories

Les traits publics séparent le contrat de l’implémentation PostgreSQL. Les opérations de lecture utilisent des filtres et paginations bornés.

## Diagnostics

- health snapshot ;
- migration snapshot ;
- backend diagnostics ;
- diagnostics des tables raw, Core et decode ;
- validation des noms de tables.

## Invariants

- aucune donnée canonique ne doit être dupliquée sans justification ;
- les écritures rejouables doivent être idempotentes ;
- la progression de campagne doit rester cohérente avec les lignes effectivement traitées ;
- les requêtes dynamiques n’acceptent que des identifiants validés ;
- les erreurs PostgreSQL restent distinctes des erreurs de contrat.

## Références

- `docs/architecture/STORAGE_ARCHITECTURE.md` ;
- `kb-store/USAGE.md` ;
- `kb-store/README.md`.