v0.3.4-pre.012

crates/ksp-store-postgres-lib/README.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-store-postgres-lib/README.md -->
-<!-- version: 10 -->
+<!-- version: 11 -->
 
 # ksp-store-postgres-lib
 
@@ -18,7 +18,7 @@ La crate possède seule pour PostgreSQL :
 - le bootstrap et le moteur de migrations privé KSP ;
 - la table metadata `ksp_store_schema_migrations` ;
 - l'advisory transaction lock borné des migrations ;
-- le schéma physique et les statements privés `RawTransaction` ;
+- les schémas physiques et statements privés `RawTransaction` et `RawAccountState` ;
 - les snapshots runtime/health sûrs destinés au bridge de façade ;
 - la fermeture explicite du pool et son fallback `Drop` best-effort ;
 - la classification d'erreurs backend sans conserver le texte d'erreur PostgreSQL.
@@ -63,7 +63,7 @@ VerifyFull
 
 Le moteur de migrations embarqué vérifie version logique, nom et checksum SHA-256, sérialise les runners par advisory transaction lock et refuse une history divergente ou plus récente que le runtime.
 
-Le bootstrap metadata est conservé comme migration V000. La migration logique V001 matérialise le schéma `RawTransaction` en ressources séparées `tables/`, `constraints/` et `indexes/` afin que le backend puisse vérifier leur compatibilité effective sans transformer les fichiers SQL en parser généraliste.
+Le bootstrap metadata est conservé comme migration V000. La migration logique V001 matérialise le schéma `RawTransaction` et V002 le schéma `RawAccountState`, chacune en ressources séparées `tables/`, `constraints/` et `indexes/` afin que le backend puisse vérifier leur compatibilité effective sans transformer les fichiers SQL en parser généraliste.
 
 La base est liée à un seul `RawNetworkId` via `ksp_store_identity`. Une migration enregistrée mais physiquement divergente est un mismatch ; les réparations additives sûres dépendent de `schema_autoupdate`.
 
@@ -130,11 +130,43 @@ Le backend verrouille la ligne canonique avec `FOR UPDATE`, compare l'état cour
 
 Toute transition impliquant `Compacted` est rejetée avec `RetentionCompactionUnsupported` tant qu'aucune représentation compactée réelle n'est implémentée.
 
+## Lectures RAW account
+
+Le backend expose :
+
+```text
+get_raw_account_state
+get_raw_account_observation
+```
+
+`get_raw_account_state` reconstruit l'état complet à partir de `(pubkey, slot, state_hash)` sans narrowing du domaine `u64`. Les bytes `pubkey`, `owner` et `state_hash` sont revalidés à leur largeur exacte et `data` reste un `BYTEA` complet, vide autorisé, borné par le contrat Store API.
+
+`get_raw_account_observation` reconstruit la provenance commune et les métadonnées account optionnelles, notamment `is_startup`, `transaction_signature` et `write_version`. La signature est une metadata fixed-width et ne crée aucune FK vers la famille transaction.
+
+## Écritures RAW account
+
+Le backend expose :
+
+```text
+persist_raw_account_acquisition
+record_raw_account_observation
+```
+
+L'acquisition état+observation est transactionnelle. Les inserts utilisent `ON CONFLICT ... DO NOTHING`, puis verrouillent et comparent le contenu gagnant avant de conclure `AlreadyPresent` ou `Conflict`; aucun `DO UPDATE` n'est utilisé. Une collision divergente d'observation fait échouer toute l'acquisition et rollback un éventuel nouvel état.
+
+L'ajout d'une observation vérifie que l'état référencé existe déjà et ne crée jamais implicitement cet état.
+
+## Pagination RAW account
+
+`list_raw_account_states` parcourt les références selon l'ordre total `(slot, pubkey, state_hash)`, en ASC ou DESC, avec filtre pubkey optionnel. La continuation est keyset, sans `OFFSET`.
+
+Le cursor `KSPA` est opaque et lié au réseau, au filtre pubkey, à la direction, aux bornes de slots et à la dernière clé complète. Il est distinct du cursor transaction `KSPT`.
+
 ## Hors périmètre
 
 La crate ne contient :
 
-- aucune implémentation PostgreSQL des capabilities `RawAccount*` ;
+- aucune rétention, archive, purge, suppression ou compaction account ;
 - aucune orchestration worker/job ;
 - aucun transport d'acquisition ou decoder Program ;
 - aucune policy autonome de batch, priorité ou rétention.
@@ -147,4 +179,6 @@ La crate ne contient :
 - [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — décisions pool/TLS/migrations ;
 - [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — validation de fondation ;
 - [`../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) — design `RawTransaction` ;
-- [`../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction`.
+- [`../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction` ;
+- [`../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](../../docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) — design `RawAccountState` et complétude RAW ;
+- [`../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](../../docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) — validation `RawAccountState` et conformance RAW.