v0.5.3-pre.004

ks-store/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: ks-store/USAGE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Utilisation de ks-store
 
@@ -50,7 +50,7 @@ ks-store/migrations/postgres/
 
 Chaque fichier contient une seule instruction SQL. Les fonctions privées du backend l'embarquent par `include_str!`; le DDL n'est pas dupliqué dans des chaînes Rust.
 
-Le baseline courant compte 236 ressources SQL atomiques et 75 index attendus.
+Le baseline conserve 16 tables et compte désormais 240 ressources SQL atomiques et 79 index attendus après la revue des chemins de replay `pre.004`.
 
 ## Résumés sûrs
 
@@ -93,12 +93,13 @@ Les traits publics effectivement implémentés sont :
 - `StoreHealthStore` ;
 - `RawTransactionStore` ;
 - `CoreTransactionStore` ;
+- `AccountStateStore` ;
 - `CoreExtractionStore` ;
 - `DecodePipelineStore`.
 
 `Store` implémente ces traits et délègue au backend privé.
 
-Le schéma `pre.003` réserve aussi les contrats génériques d'observation/état de comptes nécessaires au gel N1/N2. Leur ingestion/replay opérationnel est raccordé dans la tranche repositories/replay suivante ; leur présence dans le baseline évite une modification structurelle ultérieure pour un futur décodeur de comptes.
+Le couple générique observation/état de compte est opérationnel en `pre.004` : `RawTransactionStore` persiste les observations N1, puis `AccountStateStore` sélectionne et normalise de manière versionnée/idempotente vers N2. Une nouvelle version du normalizer n’est pas masquée par la présence d’un ancien état Core : le processing ledger porte l’identité/version/hash du traitement.
 
 ## Core et replay N2 -> N3
 
@@ -112,7 +113,7 @@ Le replay d'instruction Core transporte désormais :
 
 Le contrat de replay Core est en version 3. Les anciens constructeurs restent utilisables pour les tests/sources synthétiques ; `ks-store` enrichit les inputs issus du Core persistant avec le contexte disponible.
 
-Les instructions top-level et CPI restent deux tables physiques. La sélection logique commune et le replay autonome des CPI sont finalisés dans la tranche repositories/replay.
+Les instructions top-level et CPI restent deux tables physiques, mais la lecture/replay utilise une union logique commune. `CoreInstructionScope` distingue explicitement `TopLevel` et `Inner`, et le lifecycle est mis à jour dans la table physique correspondant au chemin sélectionné.
 
 ## Matérialisation N3
 
@@ -147,7 +148,10 @@ Les contrats publics utilisent `ReplayTransaction*`, `ReplayProgram*` et `Replay
 
 ```rust
 let first_page = ks_store::PageRequest::first_page();
-let next_page = match ks_store::PageRequest::new(250, 250) {
+let next_page = match ks_store::PageRequest::after(
+    250,
+    cursor,
+) {
     Ok(value) => value,
     Err(error) => return Err(error),
 };
@@ -155,30 +159,32 @@ assert_eq!(first_page.limit, ks_store::DEFAULT_PAGE_SIZE);
 assert!(next_page.limit <= ks_store::MAX_PAGE_SIZE);
 ```
 
-La refonte cursorisée et la suppression des gros offsets comme contrat durable appartiennent à la tranche repositories/replay.
+`PageRequest` n’expose plus d’offset durable. Pour le replay Core, le curseur encode la clé stable `(slot, signature, scope, instruction_path)` ; la requête demande `limit + 1` afin de produire `PageSlice.next_cursor` sans doublon ni saut sur un dataset figé. Les lectures interactives sont bornées à 500 lignes. Les batches de processing Core/decode/account-state utilisent leurs propres limites, plafonnées à 1 000.
 
 ## 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 SQL isolées.
+Les bundles `AccountStatePersistenceBundle`, `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 SQL isolées.
 
 ## Tests PostgreSQL réels
 
 Les tests opt-in utilisent `KS_SECRET_POSTGRES_TEST_URL`. Aucun credential réel ne doit être enregistré dans les fixtures ou logs. Les erreurs d'ouverture de connexion sont volontairement sanitisées.
 
-Pour `pre.003`, les validations PostgreSQL à exécuter après compilation sont particulièrement importantes :
+Pour `pre.004`, les validations PostgreSQL à exécuter après compilation sont particulièrement importantes :
 
 - init sur base vide ;
 - réouverture idempotente ;
-- présence des 16 tables et 75 index attendus ;
+- présence des 16 tables et 79 index attendus ;
 - refus d'un schéma historique `kb_sol_*` ;
 - roundtrip raw/Core/decode/materialization ;
-- rollback transactionnel Core/decode.
+- roundtrip account observation -> account state, y compris nouvelle version de normalizer et force replay ;
+- replay top-level + CPI paginé sur plusieurs pages ;
+- invalidation descendante lors d’un remplacement Core/decode ;
+- rollback transactionnel account-state/Core/decode.
 
-## Travaux encore ouverts après `pre.003`
+## Travaux encore ouverts après `pre.004`
 
-- sélection/replay autonome des CPI et lecture logique top-level+CPI ;
-- invalidation descendante N1 -> N2 -> N3 -> N4 ;
-- replay opérationnel du nouveau flux d'observations/états de comptes ;
-- pagination cursorisée et revue finale des index par plans réels ;
-- snapshot machine-readable et gel formel en tranche de réconciliation technique ;
-- refonte desktop fonctionnelle finale autour du nouveau baseline.
+- validation PostgreSQL réelle des nouveaux chemins account-state, CPI, invalidation et pagination sur dataset représentatif ;
+- revue finale des plans `EXPLAIN` avant de considérer les 79 index comme suffisants ;
+- snapshot machine-readable et gel formel N1/N2/N3 dans la tranche de réconciliation technique ;
+- refonte desktop fonctionnelle finale autour du nouveau baseline en `pre.005` ;
+- projections N4 spécialisées, hors `0.5.3`.