khadhroony-solana-project/deltas/0.3.1/pre.003.md

Delta 0.3.1-pre.003

Base requise

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 à :

0.3.1-pre.3

Surface ajoutée

Primitives communes :

RawNetworkId
RawTransactionSignature
RawTransactionReference
RawFormatId
RawContentHash
RawObservationKey
RawTimestamp
RawAcquisitionOrigin
RawProvenanceCode
RawAcquisitionProvenance
RawPayload

Première famille N1 :

RawTransaction
RawTransactionObservation

Codes d'erreur :

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 :

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 :

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 :

RawTransactionReference
    network
    signature [u8; 64]

Aucune PK SQL/backend ne traverse l'API. RawTransaction ajoute :

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 :

RawTransactionObservation
    observation_key [u8; 32]
    transaction reference
    provenance

La provenance peut représenter avec des logical codes sûrs :

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

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

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 :

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é

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.