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