v0.5.3-pre.004

docs/architecture/STORAGE_ARCHITECTURE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
-<!-- version: 8 -->
+<!-- version: 9 -->
 
 # Architecture du stockage
 
@@ -148,9 +148,31 @@ Principes :
 - `DROP`/`TRUNCATE` séparés de l'auto-init ;
 - refus explicite d'un schéma contenant encore des objets `kb_sol_*`.
 
-Le baseline `pre.003` contient **236 ressources SQL atomiques** et **75 index attendus**. Ces nombres décrivent l'implémentation PostgreSQL actuelle, pas une API publique gelée.
+Après la revue repositories/index de `pre.004`, le baseline contient **240 ressources SQL atomiques** et **79 index attendus** (63 explicites + 16 index de clés primaires). Ces nombres décrivent l'implémentation PostgreSQL actuelle, pas une API publique gelée.
 
-## 7. Propriétés attendues
+## 7. Replay, invalidation et pagination (`pre.004`)
+
+`pre.004` ne modifie pas les 16 tables ; il ferme les chemins de repository au-dessus d’elles.
+
+### 7.1 Instructions top-level et CPI
+
+Les deux catégories restent physiquement séparées. La lecture de replay construit une union logique avec un scope explicite et un ordre stable `(slot, signature, scope_rank, instruction_path)`. Le curseur de page reprend cette clé ; aucun `OFFSET` n’appartient au contrat durable.
+
+### 7.2 Invalidation descendante
+
+Un remplacement N2 Core d’une signature invalide dans la même transaction ses descendants N3 decode/coverage/materialization et les ledgers concernés. Un remplacement decode invalide ses sorties de matérialisation pour l’identité exacte decoder name/version/input. Les préfixes de ledger sont comparés littéralement, sans `LIKE`, afin que `_` ne puisse pas agir comme wildcard.
+
+Le lifecycle instructionnel est ensuite recomposé depuis les descendants réellement courants. Une ancienne matérialisation produite par une version antérieure du decoder ne suffit pas à déclarer le nouvel input matérialisé.
+
+### 7.3 Account observation -> Core account state
+
+Le flux N1 -> N2 réservé en `pre.003` devient opérationnel. La sélection est bornée et version-aware ; la présence d’un ancien Core state ne masque pas une nouvelle version du normalizer. `lamports` et `rent_epoch` conservent tout le domaine `u64` via `NUMERIC(20,0)` et les conversions vers `BIGINT` échouent explicitement hors domaine signé.
+
+### 7.4 Bornes et instrumentation
+
+Les lectures interactives publiques sont plafonnées à 500 lignes. Les campagnes de processing Core/decode/account-state utilisent des batches distincts plafonnés à 1 000. Les opérations PostgreSQL réécrites tracent `action`, durée, lignes et outcome sous `ks-store`/`ks-store.pg`, sans SQL brut ni valeur bindée.
+
+## 8. Propriétés attendues
 
 - initialisation idempotente ;
 - pagination bornée ;
@@ -164,6 +186,6 @@ Le baseline `pre.003` contient **236 ressources SQL atomiques** et **75 index at
 
 Les index non uniques restent des optimisations physiques évolutives. Les noms/colonnes/types/nullabilités/PK/FK/uniques/checks/sémantiques du baseline N1-N3 seront figés séparément lors de la tranche de gel.
 
-## 8. Données de test
+## 9. Données de test
 
 Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous `test-fixtures/contract-matrices/` lorsqu'elles sont nécessaires aux tests.

docs/guides/POSTGRES_STORAGE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/guides/POSTGRES_STORAGE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Guide PostgreSQL et contrats de stockage
 
@@ -79,12 +79,27 @@ Le corpus `pre.003` contient actuellement :
 - 59 créations d'index explicites ;
 - 16 ressources `TRUNCATE` ;
 - 16 ressources `DROP` ;
-- soit **236 ressources SQL**.
+- quatre index supplémentaires justifiés par le replay/invalidation `pre.004` ;
+- soit **240 ressources SQL**.
 
-PostgreSQL attend **75 index** au total dans son diagnostic : 59 index explicites plus les 16 index de clé primaire créés par PostgreSQL.
+PostgreSQL attend désormais **79 index** au total dans son diagnostic : 63 index explicites plus les 16 index de clé primaire créés par PostgreSQL.
 
 Les index non uniques restent des optimisations physiques et ne font pas partie du gel logique N1-N3.
 
+## Repositories `pre.004`
+
+La tranche `pre.004` conserve les 16 tables et ferme les comportements suivants :
+
+- replay logique commun top-level/CPI avec scope explicite et pagination keyset ;
+- lifecycle symétrique top-level/CPI ;
+- invalidation N2 Core -> N3 lors d’un remplacement de signature ;
+- invalidation decode -> matérialisation pour l’identité decoder exacte ;
+- normalisation versionnée `k_sol_obs_account_observations` -> `k_sol_core_account_states` ;
+- limites interactives à 500 et batches de processing à 1 000 ;
+- traces fonctionnelles `TRACE ks-store` avec durée/lignes/outcome, sans bind values.
+
+Les quatre nouveaux index couvrent l’ordre de replay CPI et les recherches d’invalidation/descendants dans coverage/materialization. Leur utilité finale doit encore être confirmée par des plans PostgreSQL réels avant le gel ; les index non uniques restent une optimisation physique.
+
 ## Statut du schéma
 
 La façade n'utilise plus `_sqlx_migrations` comme preuve du baseline actuel. Le statut est dérivé du contrat réellement observé :

docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md -->
-<!-- version: 8 -->
+<!-- version: 9 -->
 
 # Plan `0.5.3` — audit et normalisation de `ks-store`
 
@@ -1609,3 +1609,73 @@ Les autres metadata transactionnelles auditées (`fee`, rewards, compute units,
 - les projections N4 metadata/trading.
 
 Ces points restent dans les tranches suivantes et peuvent décaler le premier candidat de clôture au-delà de `pre.007`.
+
+## 34. État réalisé de `0.5.3-pre.004`
+
+`pre.004` ferme la tranche repositories/replay sans ajouter de table et sans déclarer encore le gel formel N1/N2/N3.
+
+### 34.1 Replay top-level + CPI
+
+Les instructions top-level et CPI restent dans leurs deux tables physiques. Les repositories construisent désormais une lecture logique commune avec `CoreInstructionScope::{TopLevel, Inner}`. Le replay contextuel N2 -> N3 fonctionne sur les deux scopes ; le lifecycle est mis à jour dans la table physique correspondant au chemin d’instruction.
+
+L’ordre de page durable est :
+
+```text
+(slot, signature, scope_rank, instruction_path)
+```
+
+`PageRequest` abandonne `offset` et utilise un curseur borné. Les lectures interactives sont plafonnées à 500 lignes.
+
+### 34.2 Batches de processing
+
+Les campagnes Core extraction, decode et account-state utilisent des limites propres, plafonnées à 1 000 entrées par batch. Elles ne réutilisent pas la limite interactive de 500 et aucune surface publique ne conserve l’ancien plafond 100 000.
+
+### 34.3 Invalidation descendante
+
+Le remplacement d’un graphe Core invalide, dans la même transaction, les descendants decode/coverage/materialization et les ledgers de la signature avant reconstruction N2.
+
+Le remplacement d’un résultat decode invalide les matérialisations appartenant à l’identité exacte `(decoder_name, decoder_version, decode_input_key)`. Les clés de ledger sont comparées par préfixe littéral avec `LEFT(...)=prefix`, jamais avec `LIKE`.
+
+Après persistence, le lifecycle instructionnel est recalculé depuis les descendants courants. Une sortie produite par une ancienne version du decoder ne peut donc pas faire apparaître la nouvelle version comme matérialisée.
+
+### 34.4 Account observation -> account state
+
+Le couple réservé en `pre.003` devient opérationnel :
+
+```text
+k_sol_obs_account_observations
+        -> account_state_normalization ledger
+        -> k_sol_core_account_states
+```
+
+La sélection transporte le nom/version du normalizer ; une nouvelle version peut rejouer les observations même si un Core state d’une version précédente existe. Le hash d’input assure l’idempotence de la version courante. Les valeurs `lamports`/`rent_epoch` conservent le domaine `u64` complet via `NUMERIC(20,0)`.
+
+### 34.5 Index et ressources SQL
+
+Aucune table ni contrainte logique n’est ajoutée. Quatre index non uniques sont ajoutés pour les nouveaux chemins :
+
+- ordre de replay des CPI par slot/signature/path ;
+- lookup coverage par signature/path ;
+- descendants materialized outputs par decode input ;
+- descendants materialized outputs par signature/input.
+
+Le corpus passe de 236 à **240 ressources SQL**, avec **63 index explicites / 79 index attendus** en comptant les 16 clés primaires. Les index restent ajustables avant gel sur la base des plans `EXPLAIN`.
+
+### 34.6 Instrumentation PostgreSQL
+
+Les opérations de repository réécrites émettent des événements `TRACE` sous le target canonique `ks-store` avec :
+
+```text
+backend="postgres"
+domain="ks-store.pg"
+action
+elapsed_ms
+rows
+outcome
+```
+
+Le statement logging automatique SQLx reste désactivé. Les traces normales ne publient ni SQL brut, ni valeurs bindées, ni secret de connexion.
+
+### 34.7 Reste avant gel
+
+La validation PostgreSQL réelle des nouveaux chemins, les plans `EXPLAIN`, la présentation desktop finale et le snapshot machine-readable restent dans les tranches suivantes. `pre.004` stabilise les repositories candidats ; il ne déclare pas encore N1/N2/N3 frozen.