# 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 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`.