v0.5.3-pre.005-fix010

ks-store/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: ks-store/USAGE.md -->
-<!-- version: 7 -->
+<!-- version: 10 -->
 
 # Utilisation de ks-store
 
@@ -27,13 +27,15 @@ let store = match ks_store::Store::open(options).await {
 };
 ```
 
-`Store::open` interprète les options du backend actif, crée la connexion, exécute l'auto-initialisation lorsqu'elle est configurée et capture un résumé d'initialisation sanitisé. PostgreSQL reste le seul backend opérationnel exigé en `0.5.3`; un code backend inconnu est refusé proprement.
+`Store::open` interprète les options du backend actif, crée la connexion, valide d'abord les définitions déjà présentes et n'exécute l'auto-initialisation que pour compléter des ressources gérées absentes lorsque l'option l'autorise. Il capture ensuite un résumé d'initialisation sanitisé. PostgreSQL reste le seul backend opérationnel exigé en `0.5.3`; un code backend inconnu est refusé proprement.
 
 Avec PostgreSQL, l'auto-initialisation utilise un **seul orchestrateur transactionnel global**. Il ne faut pas initialiser séparément raw/Core/decode : la cohérence du baseline est vérifiée comme un contrat unique.
 
 ## Baseline PostgreSQL actif
 
-`0.5.3-pre.003` utilise directement le namespace `k_sol_*` et un baseline candidat au gel de 16 tables N1-N3. Une base contenant encore des objets `kb_sol_*` est refusée ; elle doit être supprimée/reconstruite explicitement.
+`0.5.3-pre.003` utilise directement le namespace `k_sol_*` et un baseline candidat au gel de 16 tables N1-N3. `ks-store` ne possède que ses ressources `k_sol_*` courantes : les tables étrangères ou historiques, y compris `kb_sol_*`, sont ignorées tant qu'elles ne sont pas référencées par le contrat actif.
+
+`auto_initialize_schema` applique uniquement des évolutions additives. Si une table, colonne, PK/FK ou index géré manque, `false` provoque une erreur ; avec `true`, `ks-store` tente de créer uniquement les ressources absentes puis revalide le contrat complet. Une colonne existante avec un type, une nullabilité, une précision numérique ou un défaut incompatible provoque toujours une erreur : l'auto-initialisation n'exécute aucun `DROP COLUMN`, `ALTER COLUMN` ni renommage. Le même principe s'applique aux clés et index existants dont la définition ne correspond pas au contrat.
 
 Les ressources actives sont sous :
 
@@ -117,11 +119,13 @@ Les instructions top-level et CPI restent deux tables physiques, mais la lecture
 
 ## Matérialisation N3
 
-Le journal générique est `k_sol_mat_outputs`. L'API publique utilise désormais :
+Le journal générique est `k_sol_mat_outputs`. L'API publique conserve la lecture bornée de processing et ajoute une lecture de consultation comptée :
 
-- `MaterializedOutputFilter` ;
-- `MaterializedOutputQueryRow` ;
-- `DecodePipelineStore::list_materialized_outputs`.
+- `MaterializedOutputFilter` + `DecodePipelineStore::list_materialized_outputs` pour les workflows bornés existants ;
+- `MaterializedOutputPageFilter` + `Store::materialized_output_page` pour les listings cursorisés ;
+- `MaterializedOutputQueryRow` comme ligne générique commune.
+
+`MaterializedOutputPageFilter` peut transporter des groupes bornés de contraintes structurelles sur le payload JSON : tous les groupes doivent correspondre, mais une seule alternative par groupe suffit. Le backend PostgreSQL applique exactement ces mêmes contraintes au `COUNT` et à la page ; le Store reste donc générique et ne connaît ni mint, ni ATA, ni opération SPL.
 
 `k_sol_mat_outputs` reste obligatoire même lorsque des projections N4 spécialisées existeront.
 
@@ -169,12 +173,14 @@ Les bundles `AccountStatePersistenceBundle`, `CoreExtractionBundle`, `DecodePers
 
 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.004`, les validations PostgreSQL à exécuter après compilation sont particulièrement importantes :
+Pour le baseline `0.5.3`, les validations PostgreSQL à exécuter après compilation sont particulièrement importantes :
 
-- init sur base vide ;
+- présence des 16 tables ;
+- compatibilité des 248 colonnes actuellement gérées : type, nullabilité, précision numérique et défaut requis ;
+- compatibilité des 25 clés primaires/étrangères attendues et des 79 index physiques attendus, pas seulement leur nombre ;
+- acceptation des tables étrangères/historiques et des colonnes additives compatibles ;
+- refus d'une dérive structurelle d'une ressource gérée qui casserait les lectures ou écritures courantes ;
 - réouverture idempotente ;
-- présence des 16 tables et 79 index attendus ;
-- refus d'un schéma historique `kb_sol_*` ;
 - roundtrip raw/Core/decode/materialization ;
 - roundtrip account observation -> account state, y compris nouvelle version de normalizer et force replay ;
 - replay top-level + CPI paginé sur plusieurs pages ;
@@ -188,3 +194,9 @@ Pour `pre.004`, les validations PostgreSQL à exécuter après compilation sont
 - 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`.
+
+## Pagination des listings Store
+
+Les lectures interactives restent bornées à 500 lignes par bloc. Les filtres fonctionnels ne portent pas d’offset : le consumer transmet un `PageRequest { limit, cursor }` et reçoit une page stable. Les Replay Candidates et les listings cursorisés de matérialisations utilisent `CountedPageSlice<T>` afin de retourner en plus `total_rows`; le desktop peut ainsi afficher `Bloc N / total` tout en conservant un curseur opaque.
+
+Le comptage est rafraîchi à chaque chargement de bloc. Un changement de filtre doit invalider l’historique de curseurs et repartir du premier bloc. La pagination DataTables du desktop est locale aux 500 lignes déjà chargées et ne modifie jamais la pagination repository.