4.7 KiB
Delta 0.3.1-pre.005 — capabilities backend extensibles
Base requise
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
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
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
aucun
Version
workspace.package.version = 0.3.1-pre.5
Surface ajoutée
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 :
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 :
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 :
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 :
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
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 :
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é
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.