205 lines
5.1 KiB
Markdown
205 lines
5.1 KiB
Markdown
<!-- 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`.
|