v0.2.6-rel.001

docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Data, Materialization et Store
 
@@ -32,9 +32,9 @@ Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait dé
 - les couches dérivées ne rendent jamais obligatoire une nouvelle acquisition réseau lorsque l'input durable nécessaire existe déjà ;
 - D4 privilégie les faits métier génériques lorsqu'une normalisation inter-protocoles est pertinente.
 
-# D1 — RAW
+## D1 — RAW
 
-## Mission
+### Mission
 
 RAW conserve l'acquisition suffisamment fidèlement pour reconstruire CORE sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
 
@@ -42,7 +42,7 @@ Le transport peut normaliser plusieurs providers vers un modèle KSP homogène,
 
 D1 ne décode aucun programme Solana/SPL/Metaplex/DEX.
 
-## Frontière Transport -> RAW
+### Frontière Transport -> RAW
 
 ```text
 HTTP / WS / gRPC / provider
@@ -62,7 +62,7 @@ ksp-store-lib
 
 `ksp-onchain-transport-lib` ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`.
 
-## Provenance RAW
+### Provenance RAW
 
 Selon la catégorie, D1 doit pouvoir conserver notamment :
 
@@ -77,9 +77,9 @@ Selon la catégorie, D1 doit pouvoir conserver notamment :
 - identité/hash d'idempotence ;
 - cursor/page/range/checkpoint lorsque pertinent.
 
-# D2 — CORE
+## D2 — CORE
 
-## Mission
+### Mission
 
 CORE est une **normalisation canonique générique de la blockchain Solana**.
 
@@ -104,7 +104,7 @@ Exemples de faits CORE candidats :
 
 Un fait CORE peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
 
-## Frontière RAW -> CORE
+### Frontière RAW -> CORE
 
 ```text
 D1 RAW
@@ -126,7 +126,7 @@ RAW -> CORE -X-> ksp-materializer-api
 
 Les codecs/wires génériques nécessaires à la structure Solana peuvent provenir de `ksp-interface-lib` lorsqu'ils appartiennent à la façade wire officielle, sans transformer cette étape en décodage Program.
 
-## Provenance CORE
+### Provenance CORE
 
 D2 doit pouvoir relier chaque résultat à :
 
@@ -136,9 +136,9 @@ D2 doit pouvoir relier chaque résultat à :
 - l'instant de processing/persistence ;
 - son état de processing durable lorsque nécessaire.
 
-# D3 — DECODE / matérialisation générique
+## D3 — DECODE / matérialisation générique
 
-## Mission
+### Mission
 
 DECODE commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
 
@@ -179,7 +179,7 @@ quel état/superseded/failed/replay ?
 
 Les types exacts de decoded facts et du journal sont décidés lorsque les premiers vertical slices Program existent.
 
-## Frontière CORE -> DECODE
+### Frontière CORE -> DECODE
 
 ```text
 D2 CORE
@@ -201,9 +201,9 @@ Les implémentations officielles pourront provenir de `ksp-program-lib` et `ksp-
 
 Program et Materializer ne dépendent pas du backend Store.
 
-# D4 — SPECIALIZED
+## D4 — SPECIALIZED
 
-## Mission
+### Mission
 
 SPECIALIZED expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
 
@@ -222,7 +222,7 @@ Exemples :
 - faits trading-adjacent ;
 - projections d'autres domaines futurs.
 
-## Faits métier génériques
+### Faits métier génériques
 
 Les projections de trading ne sont pas séparées automatiquement par protocole.
 
@@ -249,20 +249,20 @@ pump_trades
 
 Les champs réellement protocol-specific peuvent être conservés dans une extension ou une projection dédiée uniquement lorsqu'un besoin de requête/invariant le justifie.
 
-## Metadata
+### Metadata
 
 La direction reste :
 
 - projection canonique commune pour metadata d'assets/tokens alimentée par Metaplex Token Metadata et Token-2022 Metadata ;
 - SPM reste distinct et sera redéveloppé plus tard avec le décodage généraliste.
 
-## OHLC
+### OHLC
 
 Les candles sont des projections SPECIALIZED calculées à partir des trades/price observations persistés.
 
 Une application marché lit les OHLC matérialisés ; elle ne reparcourt pas toutes les transactions pour reconstruire les candles à chaque affichage.
 
-# Vertical slices Program
+## Vertical slices Program
 
 RAW et CORE sont développés horizontalement.
 
@@ -283,7 +283,7 @@ Un groupe doit atteindre une cohérence verticale suffisante avant que le groupe
 
 Les composants satellites nécessaires à un protocole appartiennent à son groupe : Pump fees avec Pump, Meteora vaults avec Meteora, etc.
 
-# `ksp-store-api`
+## `ksp-store-api`
 
 `ksp-store-api` est backend-agnostic et porte les contrats nécessaires aux consommateurs.
 
@@ -291,7 +291,7 @@ La première implementation `0.3.1` est volontairement **RAW-only** : elle ne cr
 
 Les surfaces CORE/DECODE/SPECIALIZED sont ajoutées quand leurs couches sont réellement ouvertes.
 
-# `ksp-store-lib`
+## `ksp-store-lib`
 
 `ksp-store-lib` fournit PostgreSQL comme backend officiel de référence derrière `ksp-store-api`.
 
@@ -312,7 +312,7 @@ Il ne possède pas :
 - materializer ;
 - orchestration de worker/job.
 
-# `ksp-materializer-api` et `ksp-materializer-lib`
+## `ksp-materializer-api` et `ksp-materializer-lib`
 
 Ils sont introduits seulement lorsque le premier groupe DECODE démontre le contrat réel.
 
@@ -320,7 +320,7 @@ Ils sont introduits seulement lorsque le premier groupe DECODE démontre le cont
 
 Une projection très locale/spécifique peut rester dans son groupe si la création d'une implémentation commune séparée n'apporte pas de réutilisation réelle.
 
-# Replay
+## Replay
 
 Les frontières durables restent replayables indépendamment :
 
@@ -332,7 +332,7 @@ DECODE -> SPECIALIZED
 
 Un replay d'une couche dérivée ne doit pas refaire arbitrairement les couches précédentes.
 
-# Notifications persistées
+## Notifications persistées
 
 Le Store reste source de vérité du backlog.
 
@@ -348,7 +348,7 @@ notify
 
 Le consumer reconstruit toujours son backlog depuis le Store avec les versions de processor et les marqueurs d'idempotence.
 
-# Acquisition live et backfill
+## Acquisition live et backfill
 
 Live et backfill alimentent la même frontière RAW :
 
@@ -360,7 +360,7 @@ backfill job ----/
 
 Ils ne dupliquent pas le contrat durable.
 
-# Stabilité
+## Stabilité
 
 La stabilité cible est différente selon la couche :
 
@@ -369,7 +369,7 @@ La stabilité cible est différente selon la couche :
 - DECODE : extensible par nouveaux Program/versions ;
 - SPECIALIZED : plus évolutif selon les besoins de query, trading et analytics.
 
-# Questions laissées ouvertes
+## Questions laissées ouvertes
 
 - schémas SQL exacts RAW puis CORE ;
 - représentation persistable exacte d'un decoded output ;