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