v0.3.1-pre.003

deltas/0.3.1/pre.003.md

@@ -0,0 +1,204 @@
+<!-- file: deltas/0.3.1/pre.003.md -->
+<!-- version: 1 -->
+
+# Delta `0.3.1-pre.003`
+
+## Base requise
+
+```text
+0.3.1-pre.002
+```
+
+Le gate opérateur de `pre.002` est fourni vert : audits Rust/Markdown, `cargo check --workspace`, Clippy workspace et `cargo test -p ksp-store-api` passent.
+
+## Objectif
+
+Matérialiser les primitives N1 RAW backend-agnostic puis le premier modèle persistant réel `RawTransaction` avec observation d'acquisition séparée, sans introduire encore les matrices HTTP/WS/gRPC de `pre.004`, les capabilities de `pre.005` ni aucun backend/runtime Store.
+
+## Version
+
+Le workspace passe à :
+
+```text
+0.3.1-pre.3
+```
+
+## Surface ajoutée
+
+Primitives communes :
+
+```text
+RawNetworkId
+RawTransactionSignature
+RawTransactionReference
+RawFormatId
+RawContentHash
+RawObservationKey
+RawTimestamp
+RawAcquisitionOrigin
+RawProvenanceCode
+RawAcquisitionProvenance
+RawPayload
+```
+
+Première famille N1 :
+
+```text
+RawTransaction
+RawTransactionObservation
+```
+
+Codes d'erreur :
+
+```text
+store_api.raw_model_invalid
+store_api.raw_payload_invalid
+store_api.raw_provenance_invalid
+```
+
+## Invariants RAW
+
+`RawPayload` contient uniquement un format de persistence KSP déjà source-independent :
+
+```text
+format_id
+format_version > 0
+bytes non vides
+content_hash [u8; 32]
+```
+
+Le Store API ne choisit ni codec ni algorithme de conversion Transport. Le producer/converter du futur format canonique doit fournir des bytes complets et leur digest déterministe.
+
+Bornes Store-owned :
+
+```text
+code logique              <= 128 bytes
+payload RAW canonique     <= 16 MiB
+source payload size meta  <= 64 MiB
+Unix timestamp            <= 9999-12-31T23:59:59.999Z
+```
+
+Ces valeurs sont des admission guards internes et ne prétendent pas définir des maxima Solana.
+
+`RawPayload` et `RawTransaction` ne sont volontairement pas `Clone`, afin d'éviter de rendre triviale la copie de gros documents RAW.
+
+## Identité transactionnelle
+
+La référence durable est :
+
+```text
+RawTransactionReference
+    network
+    signature [u8; 64]
+```
+
+Aucune PK SQL/backend ne traverse l'API. `RawTransaction` ajoute :
+
+```text
+slot: u64
+block_time: Option<RawTimestamp>
+RawPayload
+```
+
+Les logs contenus dans la transaction restent à l'intérieur du payload canonique N1. Aucun modèle `RawLog` persistant ni type STRUCTURAL n'est créé.
+
+## Observation et provenance
+
+Une observation réussie reste distincte du RAW :
+
+```text
+RawTransactionObservation
+    observation_key [u8; 32]
+    transaction reference
+    provenance
+```
+
+La provenance peut représenter avec des logical codes sûrs :
+
+```text
+provider
+protocol
+acquisition method
+origin live/backfill/import/replay/repair
+endpoint id optionnel
+commitment optionnel
+capture/session id optionnel
+filter id optionnel
+observed_at optionnel
+received_at
+source payload size/hash optionnels
+```
+
+Elle n'accepte aucun payload source et ses logical codes refusent notamment les espaces, contrôles et formes URL contenant `/`. Le contrat reste explicitement non-secret : un caller ne doit jamais placer une credential dans un logical code.
+
+`observed_at`, lorsqu'il existe, ne peut pas être postérieur à `received_at`.
+
+## Tests
+
+Tests unitaires ajoutés :
+
+- bornes/validation des codes ;
+- borne de timestamp ;
+- payload non vide/versionné/borné ;
+- `Debug` du payload sans bytes ;
+- provenance et ordre temporel ;
+- identité `network + signature` ;
+- séparation `RawTransaction` / `RawTransactionObservation`.
+
+Canaris d'intégration mis à jour :
+
+- surface crate-root des nouveaux modèles ;
+- dépendance runtime exacte `ksp-core-lib` ;
+- absence de backend, SQL, serde, codec, async runtime, Transport et Program ;
+- absence de `RawLog` et de type STRUCTURAL dans la production `pre.003`.
+
+## Documentation mise à jour
+
+```text
+docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
+docs/validation/018-V0_3_1_STORE_RAW.md
+```
+
+Ils figent les primitives et bornes réellement matérialisées par cette tranche sans avancer les matrices cross-source de `pre.004`.
+
+## Validations exécutées dans l'environnement de génération
+
+```text
+python3 scripts/audit_rust_workspace_rules.py
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
+```
+
+## Validations non exécutées dans l'environnement de génération
+
+`cargo`, `rustc` et `rustfmt` ne sont pas installés dans l'environnement de génération. L'opérateur doit donc exécuter :
+
+```text
+cargo fmt --all
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-store-api
+```
+
+Une commande non exécutée n'est pas déclarée PASS.
+
+## Hors scope confirmé
+
+```text
+conversion HTTP/WS/gRPC -> RawTransaction canonique
+RawAccountState
+TransactionStatusObservation
+events logs/slot/vote
+capabilities read/write
+queries/outcomes
+retention/tombstone concret
+ksp-store-lib
+ksp-store-postgres-lib
+PostgreSQL/tokio-postgres
+Config std.store
+N2 STRUCTURAL
+N3/N4
+```
+
+## Suite
+
+`0.3.1-pre.004` audite les formes HTTP/WS/gRPC réelles afin de figer la matrice d'admission cross-source et d'introduire seulement les familles N1 supplémentaires dont la sémantique commune est effectivement démontrée, en priorité `RawAccountState`/observation et `TransactionStatusObservation`.