166 lines
4.7 KiB
Markdown
166 lines
4.7 KiB
Markdown
<!-- file: deltas/0.3.1/pre.005.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.1-pre.005` — capabilities backend extensibles
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.1-pre.4
|
|
```
|
|
|
|
Le gate opérateur de `pre.004` est vert : audits Rust/Markdown, `cargo check --workspace`, `cargo clippy --workspace --all-targets` et `cargo test -p ksp-store-api` passent.
|
|
|
|
## Objectif
|
|
|
|
Matérialiser les premiers contracts d'opérations backend-agnostic de `ksp-store-api` sans introduire la façade runtime `ksp-store-lib`, un backend concret ou une dépendance async supplémentaire.
|
|
|
|
La tranche doit démontrer qu'un backend externe peut implémenter séparément les capabilities réellement supportées et être utilisé derrière des trait objects.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
crates/ksp-store-api/src/capability/raw_account.rs
|
|
crates/ksp-store-api/src/capability/raw_transaction.rs
|
|
crates/ksp-store-api/tests/external_backend.rs
|
|
deltas/0.3.1/pre.005.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-store-api/src/capability.rs
|
|
crates/ksp-store-api/src/lib.rs
|
|
crates/ksp-store-api/tests/dependency_boundary.rs
|
|
crates/ksp-store-api/tests/public_api.rs
|
|
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
|
docs/validation/018-V0_3_1_STORE_RAW.md
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## Version
|
|
|
|
```text
|
|
workspace.package.version = 0.3.1-pre.5
|
|
```
|
|
|
|
## Surface ajoutée
|
|
|
|
```text
|
|
StoreApiFuture<'a, T>
|
|
|
|
RawTransactionRead
|
|
RawTransactionWrite
|
|
RawTransactionObservationRead
|
|
RawTransactionObservationWrite
|
|
|
|
RawAccountStateRead
|
|
RawAccountStateWrite
|
|
RawAccountObservationRead
|
|
RawAccountObservationWrite
|
|
```
|
|
|
|
Aucun trait global `StoreBackend` n'est ajouté. Les backends peuvent implémenter une combinaison de capabilities sans prétendre supporter toutes les familles N1.
|
|
|
|
## Contrat async/object-safe
|
|
|
|
`StoreApiFuture<'a, T>` est un alias KSP utilisant uniquement la bibliothèque standard :
|
|
|
|
```text
|
|
Pin<Box<dyn Future<Output = T> + Send + 'a>>
|
|
```
|
|
|
|
Les capabilities sont `Send + Sync`, dyn-compatible et n'ajoutent aucune dépendance `async-trait`, `tokio` ou `futures-util` à `ksp-store-api`.
|
|
|
|
## Contrats d'écriture
|
|
|
|
Les opérations suivantes sont atomiques au niveau métier :
|
|
|
|
```text
|
|
persist_raw_transaction_acquisition(transaction, observation)
|
|
persist_raw_account_acquisition(state, observation)
|
|
```
|
|
|
|
Le backend doit persister le RAW et son observation ensemble ou ne laisser aucun des deux durable.
|
|
|
|
Les opérations :
|
|
|
|
```text
|
|
record_raw_transaction_observation(observation)
|
|
record_raw_account_observation(observation)
|
|
```
|
|
|
|
servent aux acquisitions supplémentaires d'un RAW déjà présent et évitent de retransmettre le payload transactionnel ou les bytes de compte.
|
|
|
|
`pre.005` retourne uniquement `Result<()>` sur les écritures. `pre.006` remplace/finalise cette surface avec les outcomes d'idempotence/conflit, les queries et le lifecycle RAW avant stabilisation de la release.
|
|
|
|
## Canari backend externe
|
|
|
|
`tests/external_backend.rs` définit un backend mémoire externe à l'implémentation Store officielle et implémente les huit capabilities uniquement via la façade crate-root de `ksp-store-api`.
|
|
|
|
Le canari vérifie notamment :
|
|
|
|
```text
|
|
impl externe sans ksp-store-lib
|
|
impl externe sans ksp-store-postgres-lib
|
|
aucun SQL/PostgreSQL
|
|
aucun async runtime requis pour implémenter les signatures
|
|
conversion en &dyn capability possible
|
|
```
|
|
|
|
## Validations exécutées dans l'environnement de génération
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
General Rust rule audit: clean
|
|
Rust export completeness audit: 0 candidate(s)
|
|
KSP workspace Rust rule audit: clean
|
|
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
|
|
Markdown table audit: clean (186 table(s), 129 file(s))
|
|
```
|
|
|
|
## 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
|
|
façade runtime ksp-store-lib
|
|
trait StoreBackend monolithique
|
|
ksp-store-postgres-lib
|
|
PostgreSQL/tokio-postgres
|
|
Config/std.store
|
|
queries/list/pagination
|
|
outcomes d'idempotence/conflit finaux
|
|
retention/tombstone
|
|
health runtime
|
|
TransactionStatusObservation commun
|
|
models event-only logs/slot/vote
|
|
RawBlock persistence
|
|
Yellowstone Entry persistence
|
|
N2 STRUCTURAL
|
|
N3 DECODED
|
|
N4 DOMAIN
|
|
```
|
|
|
|
## Suite
|
|
|
|
`0.3.1-pre.006` finalise les queries/pages bornées, outcomes d'écriture/idempotence, contrat de backlog utile, lifecycle `RawRetentionState`, tombstone minimal et sémantiques normal-skip/force-rehydrate sans implémenter de compression/archive physique.
|