v0.3.10-pre.008

docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Data, Materialization et Store
 
@@ -10,19 +10,21 @@ Ce document définit la chaîne durable KSP, la responsabilité du Store et les
 La nomenclature canonique est désormais :
 
 ```text
-RAW -> CORE -> DECODE -> SPECIALIZED
+RAW -> STRUCTURAL -> DECODED -> DOMAIN
 ```
 
 Les aliases D1–D4 restent utilisés pour les niveaux persistés :
 
 ```text
 D1 = RAW
-D2 = CORE
-D3 = DECODE / matérialisation générique décodée
-D4 = SPECIALIZED
+D2 = STRUCTURAL
+D3 = DECODED / matérialisation générique décodée
+D4 = DOMAIN
 ```
 
-Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et CORE sont indépendants de tout decoder Program.**
+Le nom de couche historique `CORE` est abandonné pour D2 parce qu'il confondait la fondation commune `ksp-core-lib` avec une opération de décomposition structurelle du Store. `Core` reste inchangé lorsqu'il désigne la crate fondamentale ou un nom propre comme « Solana Core Programs ».
+
+Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et STRUCTURAL sont indépendants de tout decoder Program.**
 
 ## Principes structurants
 
@@ -36,7 +38,7 @@ Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait dé
 
 ### 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.
+RAW conserve l'acquisition suffisamment fidèlement pour reconstruire STRUCTURAL sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
 
 Le transport peut normaliser plusieurs providers vers un modèle KSP homogène, mais D1 doit rester lossless pour les besoins de replay couverts.
 
@@ -77,15 +79,15 @@ Selon la catégorie, D1 doit pouvoir conserver notamment :
 - identité/hash d'idempotence ;
 - cursor/page/range/checkpoint lorsque pertinent.
 
-## D2 — CORE
+## D2 — STRUCTURAL
 
 ### Mission
 
-CORE est une **normalisation canonique générique de la blockchain Solana**.
+STRUCTURAL est une **normalisation canonique générique de la blockchain Solana**.
 
 Cette couche doit fonctionner même si `ksp-program-api` et `ksp-program-lib` ne sont pas encore capables de décoder le moindre programme métier.
 
-Exemples de faits CORE candidats :
+Exemples de faits STRUCTURAL candidats :
 
 - slots ;
 - blocks et block metadata ;
@@ -102,9 +104,9 @@ Exemples de faits CORE candidats :
 - return data brute ;
 - relations structurelles transaction/message/instruction/account.
 
-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.
+Un fait STRUCTURAL 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 -> STRUCTURAL
 
 ```text
 D1 RAW
@@ -113,39 +115,39 @@ D1 RAW
 normalisation Solana générique
    |
    v
-D2 CORE
+D2 STRUCTURAL
 ```
 
 Interdictions :
 
 ```text
-RAW -> CORE -X-> ksp-program-api
-RAW -> CORE -X-> ksp-program-lib
-RAW -> CORE -X-> ksp-materializer-api
+RAW -> STRUCTURAL -X-> ksp-program-api
+RAW -> STRUCTURAL -X-> ksp-program-lib
+RAW -> STRUCTURAL -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 STRUCTURAL
 
 D2 doit pouvoir relier chaque résultat à :
 
 - son input D1 ;
-- l'identité/version du normalizer CORE ;
+- l'identité/version du normalizer STRUCTURAL ;
 - un hash logique d'input ;
 - l'instant de processing/persistence ;
 - son état de processing durable lorsque nécessaire.
 
-## D3 — DECODE / matérialisation générique
+## D3 — DECODED / matérialisation générique
 
 ### 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.
+DECODED commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
 
 La progression logique d'un groupe est :
 
 ```text
-CORE
+STRUCTURAL
   |
   v
 decoder Program
@@ -157,7 +159,7 @@ decoded facts
 materialisation générique / journal durable
   |
   v
-D3 DECODE
+D3 DECODED
 ```
 
 D3 conserve l'équivalent conceptuel obligatoire du journal générique de matérialisation de bot3 (`k_sol_mat_outputs`), sans imposer son ancien schéma ou son nom physique.
@@ -165,7 +167,7 @@ D3 conserve l'équivalent conceptuel obligatoire du journal générique de maté
 Le journal doit pouvoir répondre au minimum :
 
 ```text
-quel input CORE ?
+quel input STRUCTURAL ?
 quel program/decoder ?
 quelle version ?
 quel materializer ?
@@ -179,10 +181,10 @@ 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 STRUCTURAL -> DECODED
 
 ```text
-D2 CORE
+D2 STRUCTURAL
    |
    v
 ksp-program-api implementation
@@ -201,11 +203,11 @@ 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 — DOMAIN
 
 ### Mission
 
-SPECIALIZED expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
+DOMAIN expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
 
 Exemples :
 
@@ -258,15 +260,15 @@ La direction reste :
 
 ### OHLC
 
-Les candles sont des projections SPECIALIZED calculées à partir des trades/price observations persistés.
+Les candles sont des projections DOMAIN 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
 
-RAW et CORE sont développés horizontalement.
+RAW et STRUCTURAL sont développés horizontalement.
 
-À partir de DECODE, la progression est verticale par groupe :
+À partir de DECODED, la progression est verticale par groupe :
 
 ```text
 wire
@@ -289,7 +291,7 @@ Les composants satellites nécessaires à un protocole appartiennent à son grou
 
 La première implementation `0.3.1` est volontairement **RAW-only** : elle ne crée pas prématurément les contrats physiques D2/D3/D4.
 
-Les surfaces CORE/DECODE/SPECIALIZED sont ajoutées quand leurs couches sont réellement ouvertes.
+Les surfaces STRUCTURAL/DECODED/DOMAIN sont ajoutées quand leurs couches sont réellement ouvertes.
 
 ## `ksp-store-lib` et backends physiques
 
@@ -342,7 +344,7 @@ La voie `RawInspectionPageRequest` est backend-neutral mais conçue pour une ins
 
 ## `ksp-materializer-api` et `ksp-materializer-lib`
 
-Ils sont introduits seulement lorsque le premier groupe DECODE démontre le contrat réel.
+Ils sont introduits seulement lorsque le premier groupe DECODED démontre le contrat réel.
 
 `ksp-materializer-api` porte les contrats extensibles ; `ksp-materializer-lib` contient les implementations officielles communes.
 
@@ -353,9 +355,9 @@ Une projection très locale/spécifique peut rester dans son groupe si la créat
 Les frontières durables restent replayables indépendamment :
 
 ```text
-RAW -> CORE
-CORE -> DECODE
-DECODE -> SPECIALIZED
+RAW -> STRUCTURAL
+STRUCTURAL -> DECODED
+DECODED -> DOMAIN
 ```
 
 Un replay d'une couche dérivée ne doit pas refaire arbitrairement les couches précédentes.
@@ -393,16 +395,16 @@ Ils ne dupliquent pas le contrat durable.
 La stabilité cible est différente selon la couche :
 
 - RAW : fortement stable après mise en production ;
-- CORE : fortement stable après validation de la normalisation Solana générique ;
-- DECODE : extensible par nouveaux Program/versions ;
-- SPECIALIZED : plus évolutif selon les besoins de query, trading et analytics.
+- STRUCTURAL : fortement stable après validation de la normalisation Solana générique ;
+- DECODED : extensible par nouveaux Program/versions ;
+- DOMAIN : plus évolutif selon les besoins de query, trading et analytics.
 
 ## Questions laissées ouvertes
 
-- schémas SQL exacts RAW puis CORE ;
+- schémas SQL exacts RAW puis STRUCTURAL ;
 - représentation persistable exacte d'un decoded output ;
 - contrat exact du journal D3 ;
-- granularité des projectors SPECIALIZED ;
+- granularité des projectors DOMAIN ;
 - politique de supersession/versioning des outputs ;
 - fenêtres OHLC initiales ;
 - mécanisme de contexte pour les projections stateful.