v0.3.1-pre.003

docs/plans/022-V0_3_1_STORE_RAW_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/022-V0_3_1_STORE_RAW_PLAN.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Plan `0.3.1` — Store API RAW foundation
 
@@ -553,6 +553,46 @@ hashable/idempotent
 
 Le Store ne prétend pas que des bytes arbitraires sans format connu sont replayables.
 
+### 7.3 Contrat matérialisé par `pre.003`
+
+La première surface concrète reste indépendante de tout codec et de tout backend :
+
+```text
+RawPayload
+    RawFormatId
+    format_version: u32 non nul
+    bytes: Box<[u8]> non vide
+    RawContentHash: [u8; 32]
+
+RawTransactionReference
+    RawNetworkId
+    RawTransactionSignature: [u8; 64]
+
+RawTransaction
+    reference
+    slot: u64
+    block_time: Option<RawTimestamp>
+    payload
+
+RawTransactionObservation
+    RawObservationKey: [u8; 32]
+    transaction reference
+    RawAcquisitionProvenance
+```
+
+Les bornes initiales sont des **admission guards Store**, jamais des affirmations sur les maxima du protocole Solana :
+
+```text
+logical code UTF-8       <= 128 bytes
+canonical RAW payload    <= 16 MiB
+source payload size meta <= 64 MiB
+Unix timestamp           <= 9999-12-31T23:59:59.999Z
+```
+
+`RawPayload` ne calcule pas lui-même le digest et ne vérifie pas le contenu du format. Le producer/converter propriétaire du format KSP doit fournir des bytes déjà canoniques et leur digest déterministe. Cette séparation permet de conserver `ksp-store-api -> ksp-core-lib` uniquement.
+
+Le payload et `RawTransaction` ne sont volontairement pas `Clone` dans cette foundation afin de ne pas encourager des copies implicites d'un document RAW potentiellement volumineux. Les références, signatures, digests, timestamps et observations compactes restent clonables/copiables lorsqu'approprié.
+
 ## 8. Future décomposition N1 -> niveau STRUCTURAL
 
 Le nom de travail de N2 devient **STRUCTURAL**. `CORE` est abandonné dans le nouveau plan parce qu'il décrivait mal une opération qui consiste principalement à décomposer des données Solana brutes en sous-composants génériques.
@@ -627,6 +667,10 @@ payload source complet par simple diagnostic
 
 Les codes provider/protocol/method restent ouverts et bornés ; aucun enum provider fermé n'est introduit dans Store API.
 
+`pre.003` matérialise cette politique avec `RawProvenanceCode`, réutilisé pour les codes logiques provider/protocol/method/endpoint/commitment/session/filter. Les valeurs sont non vides, bornées et limitées à un alphabet logique sûr ; une URL contenant `/`, des contrôles ou des espaces ne peut donc pas être stockée accidentellement dans ces champs. Cette validation n'autorise pas le caller à y placer un secret alphanumérique : le contrat reste explicitement « logical code only ».
+
+`RawAcquisitionProvenance::new(...)` ne prend que les champs obligatoires ; les informations optionnelles sont ajoutées par builders dédiés. `observed_at`, lorsqu'il existe, ne peut pas être postérieur à `received_at`, et le payload source n'est jamais conservé, seulement sa taille bornée et/ou un digest optionnel.
+
 ## 10. Identité et idempotence
 
 ### 10.1 Principes

docs/validation/018-V0_3_1_STORE_RAW.md

@@ -1,5 +1,5 @@
 <!-- file: docs/validation/018-V0_3_1_STORE_RAW.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # Validation `0.3.1` — Store API RAW foundation
 
@@ -190,6 +190,43 @@ crate/test backend externe
 | force rehydrate implicite        | interdit                                        | `pre.006`      |
 | N2/N3/N4 creep                   | aucune surface                                  | `pre.007`      |
 
+### 8.1 Matérialisation `pre.003`
+
+La tranche implémente et couvre localement par canaris source/audit :
+
+```text
+RawNetworkId
+RawTransactionSignature [u8; 64]
+RawTransactionReference
+RawFormatId
+RawContentHash [u8; 32]
+RawObservationKey [u8; 32]
+RawTimestamp
+RawAcquisitionOrigin
+RawProvenanceCode
+RawAcquisitionProvenance
+RawPayload
+RawTransaction
+RawTransactionObservation
+```
+
+Gates matérialisés :
+
+```text
+Core-only dependency firewall conservé
+payload KSP source-independent, non vide, version > 0
+payload maximum Store = 16 MiB
+source payload metadata maximum = 64 MiB
+Debug RawPayload ne rend jamais les bytes
+signature/observation key/hash ne dépendent d'aucune PK backend
+provenance sans URL/source payload
+observed_at <= received_at
+logs transactionnels restent dans le payload RawTransaction
+aucun RawLog/N2 STRUCTURAL/backend/runtime ajouté
+```
+
+La complétude sémantique d'une source HTTP/WS/gRPC vers le format canonique n'est pas simulée dans Store API : elle reste le gate d'admission/conversion de `pre.004`. `pre.003` exige seulement qu'un `RawTransaction` reçoive un `RawPayload` déjà canonique complet selon son format KSP déclaré.
+
 ## 9. Gates de fermeture prévus
 
 ### Gate technique final `pre.008`