Struct VersionedKeyValueStore 

pub struct VersionedKeyValueStore { /* private fields */ }

A provider-independent session with pinned reads and conditional atomic publication. Common storage resolves typed index changes before physical admission; SQL isolation and tuple locks remain above this byte-record contract.

Implementations

impl VersionedKeyValueStore

pub fn new_sequence_value_session( &self, cancellation: &CancellationToken, ) -> Self

Select autonomous sequence publication only while its consuming transaction remains open. Unsupported providers and calls without an active completion owner retain synchronous behavior.

pub fn require_sequence_value_durability(&self) -> StorageBackendResult<()>

Sequence values can outlive transaction and savepoint undo; retain their original consumer’s completion obligation, including through a retained reader.

impl VersionedKeyValueStore

pub fn with_versioned_record_mutation<T>( &self, operation: impl FnOnce(StorageMutationOrigin, MergedRecordSnapshot, &mut dyn KeyValueBatch) -> StorageBackendResult<T>, ) -> StorageBackendResult<T>

Evaluate one provider mutation against the same fixed native record view as its batch. The callback must not reenter this session or complete its batch. Common MVCC owns autocommit, failed-evaluation cleanup and receipt retry; callbacks are never replayed.

pub fn reclaim_versions(&self) -> StorageBackendResult<u64>

Reclaim committed history without changing an active transaction or its retained readers. The persistence owner supplies atomic snapshot admission and physical deletion.

pub fn identifier_watermark( &self, namespace: &[u8], ) -> StorageBackendResult<Option<u64>>

Autonomous watermark visibility follows physical reservations, including reservations made after this session pinned its record snapshot. No write capability is required and no logical transaction is started or finished.

pub fn allocate_identifiers( &self, namespace: &[u8], request: IdentifierRequest, ) -> StorageBackendResult<IdentifierAllocation>

Reserve identities without publishing this session’s private records. Read-only sessions and unresolved sealed commits cannot allocate; rollback never reclaims a successful reservation.

pub fn observe_identifier( &self, namespace: &[u8], value: u64, ) -> StorageBackendResult<ObservedIdentifier>

Raise the watermark of namespace to at least value without reporting it. An allocation reports the current watermark and so is always physical; this answers from a watermark the session has already read when that covers value. The admission of an allocation applies either way.

pub fn new( persistence: Arc<dyn VersionedPersistence>, identity: Option<PersistentStorageIdentity>, options: VersionedSessionOptions, ) -> Self

pub fn new_with_cancellation( persistence: Arc<dyn VersionedPersistence>, identity: Option<PersistentStorageIdentity>, options: VersionedSessionOptions, write_cancellation: CancellationToken, ) -> Self

Share the invoking execution’s cancellation during autonomous allocation and publication. Retained reads and rollback cleanup keep their independent control, so cancelling a statement cannot prevent its undo.

pub fn new_session(&self) -> Self

Create an independent logical session with the same persistence and retention limit.

pub fn new_session_with_cancellation( &self, cancellation: &CancellationToken, ) -> Self

Keep a separate transaction context and retention budget while inheriting the invoking writer’s cancellation.

pub fn new_controlled_session(&self, control: &StorageReadControl) -> Self

Keep an independent writer while sharing the invoking operation’s memory allowance. Read/rollback cancellation stays independent so cleanup remains possible after write cancellation.

pub fn new_retained_read_session( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<Self>

Open an independently owned read-only session at this exact committed/private view. Its original participant, snapshot leases and retention allowance remain shared, while read cancellation stays independent. Completing this reader never completes the originating transaction.

pub fn committed_data_revision(&self) -> Option<CommittedDataRevision>

Native providers certify definition preservation using effects already observed during the physical commit.

pub fn options(&self) -> VersionedSessionOptions

pub fn record_snapshot(&self) -> VersionResult<MergedRecordSnapshot>

Retain the current committed and private boundaries for a compound provider read. Later session mutations, rollback and commit do not advance this view.

pub fn refresh_transaction_snapshot( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<()>

Advance an active transaction to the current committed boundary while retaining and rebasing its evaluated private changes. Retained readers keep their previous boundary; savepoint undo restores its matching private changes and committed base. SQL chooses when its isolation level allows this transition. A sealed commit cannot advance, and failed preparation leaves the active view unchanged.

pub fn retention_control(&self) -> StorageReadControl

Share this session’s retention allowance with provider codecs and retained record readers. Creating a control clone does not create another allowance.

pub fn session_affinity(&self) -> StorageSessionAffinity

pub fn pending_commit(&self) -> Option<StorageTransactionId>

Identify a sealed attempt after a failed commit. Retrying commit_transaction resubmits only the identical evaluated batch, and never reevaluates application code.

pub fn pending_transaction_completion(&self) -> Option<TransactionOutcomeId>

Identify a retained physical attempt or uncertain logical completion, including an empty/read-only SSI transaction without a write receipt. Completion retries never replay evaluated application work.

pub fn establish_serializable_snapshot( &self, ) -> StorageBackendResult<SerializableReadContext>

Establish the original SSI participant and fixed record boundary before this transaction’s first logical access. SQL must call this at its first snapshot-bearing statement, then supply logical observations for every participating access path. Capability presence alone does not enable SQL SSI or fence legacy publishers.

pub fn observe_serializable_write( &self, predicate: SerializablePredicate<'_>, ) -> StorageBackendResult<()>

Register a logical write before staging its records. SQL statement/savepoint ownership must encompass both this observation and the evaluated mutation. Retained record readers expose only read observation capability.

Trait Implementations

impl Drop for VersionedKeyValueStore

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl IdentifierAllocator for VersionedKeyValueStore

fn identifier_watermark( &self, namespace: &[u8], ) -> StorageBackendResult<Option<u64>>

Read the current autonomous watermark without reserving an identity or creating a namespace. This read is independent of the logical record snapshot and remains available to read-only sessions.

fn allocate_identifiers( &self, namespace: &[u8], request: IdentifierRequest, ) -> StorageBackendResult<IdentifierAllocation>

fn observe_identifier( &self, namespace: &[u8], value: u64, ) -> StorageBackendResult<ObservedIdentifier>

Raise the watermark to at least value without reporting it. A session that has already read a watermark at or above value answers without a physical allocation, which an Observe allocation cannot do because it reports the current watermark. Forwarding wrappers forward this as well, or every such observation stays physical.

impl KeyValueStore for VersionedKeyValueStore

fn resource_leases(&self) -> Option<&dyn ResourceLeaseProvider>

Physical resource ownership for retained builds and recovery. Versioned wrappers must forward this capability.

fn retention_control(&self) -> Option<StorageReadControl>

Shared session allowance, including resources retained by readers after their producer finishes. Versioned wrappers must forward this capability.

fn notification_publications(&self) -> Option<&dyn NotificationPublicationStore>

Atomic auxiliary notification publication and fresh committed recovery. Session wrappers must forward this capability.

fn serializable_session(&self) -> Option<&dyn SerializableSession>

Original participant admission and logical observations. Wrappers must forward this capability, including original attribution on retained read-only sessions; capability presence does not establish complete SQL SSI support.

fn reclaim_obsolete(&self) -> StorageBackendResult<()>

Reclaim obsolete records and committed history without a whole-file rewrite. Versioned wrappers must forward maintenance; serialized stores that eagerly remove obsolete values may keep the default.

fn write_cancellation(&self) -> Option<CancellationToken>

Token shared with the execution that owns this session’s writes. Cancellation must not prevent rollback cleanup or diagnostic reads. Versioned wrappers must forward this capability.

fn open_controlled_session( &self, control: &StorageReadControl, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Open an independent writer sharing the invoking maintenance operation’s allowance and write cancellation. Retained reads and cleanup keep independent cancellation. Capable wrappers must forward this without granting another memory limit.

fn open_session_with_cancellation( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Create a transaction-isolated session with the caller’s write cancellation and a fresh retention budget.

fn open_retained_read_session( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Retain this exact committed/private view in a separate read-only session, including its original logical reader attribution. The returned session cannot publish records or complete the source transaction. Versioned wrappers must forward this capability; opening a newer independent snapshot is not equivalent.

fn transaction_model(&self) -> StorageTransactionModel

Whether writes remain private while independent sessions read and write. Versioned stores must provide command refresh, retained reads, savepoint undo and conditional publication under one reported affinity.

fn refresh_transaction_snapshot( &self, cancellation: &CancellationToken, ) -> StorageBackendResult<()>

Advance an active logical transaction’s committed view while preserving its private writes and retained readers. The caller chooses command boundaries allowed by SQL isolation. Stores without this capability must reject the request; ending or replaying the caller’s transaction is not a valid fallback.

fn identifier_allocator(&self) -> Option<&dyn IdentifierAllocator>

Durable reservations outside private record undo. Serialized custom stores may omit this capability; wrappers over a capable store must forward it.

fn with_read_view( &self, operation: &mut KeyValueReadScope<'_>, ) -> StorageBackendResult<()>

Evaluate a compound read once against one fixed committed/private view. The callback must use the supplied reader and must not reenter this session. Stores without this capability reject it explicitly.

fn with_mutation( &self, operation: &mut KeyValueMutation<'_>, ) -> StorageBackendResult<()>

Evaluate once against the same view that supplies write preconditions, then atomically stage the batch. Errors and unwinds discard that batch; failed publication retains the evaluated attempt. The callback must not reenter this session or perform transaction control.

fn with_mutation_revision( &self, prefixes: &[&[u8]], operation: &mut KeyValueMutation<'_>, ) -> StorageBackendResult<Option<KeyValueReadRevision>>

Stage once and optionally certify the resulting prefix identity before another mutation can intervene. The identity may name private state before a later commit. A provider without this capability performs the ordinary mutation and returns no certificate; opening a later read view cannot certify this mutation’s result.

fn with_versioned_mutation( &self, operation: &mut KeyValueVersionedMutation<'_>, ) -> StorageBackendResult<()>

Evaluate and stage once with the actual durable writer and a non-reused mutation revision. Origins may be persisted alongside canonical values, but do not prove publication or visibility. The callback has the same non-reentrancy rules as with_mutation; capable wrappers must preserve the original origin and atomic batch.

fn transaction_affinity(&self) -> Option<StorageSessionAffinity>

Identity of the transaction context shared by this store’s catalog and data handles. Independent sessions must report different identities, even over the same file.

fn storage_identity( &self, ) -> StorageBackendResult<Option<PersistentStorageIdentity>>

fn open_session(&self) -> StorageBackendResult<Arc<dyn KeyValueStore>>

Open an independent transaction session over the same logical store. The default keeps simple test/custom stores source-compatible while making the missing MVCC capability explicit when a persistent engine needs a committed reader alongside a pinned statement snapshot.

fn get(&self, key: &[u8]) -> StorageBackendResult<Option<Vec<u8>>>

fn contains_key(&self, key: &[u8]) -> StorageBackendResult<bool>

fn contains_prefix_budgeted( &self, prefix: &[u8], control: &StorageReadControl, ) -> StorageBackendResult<bool>

Test prefix existence under the read allowance. Providers that materialize values should implement a key-only probe.

fn visit_value( &self, key: &[u8], control: &StorageReadControl, visit: &mut ValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit one borrowed value under the retained read. Providers reserve any temporary encoded payload before fetching it; callbacks must not reenter the store.

fn visit_value_bounded( &self, key: &[u8], max_bytes: usize, control: &StorageReadControl, visit: &mut ValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit one value with an encoded-size cap checked before provider materialization. This is distinct from the shared workspace allowance; unsupported stores must not fetch an unbounded value as a fallback.

fn visit_prefix_after( &self, prefix: &[u8], after: Option<&[u8]>, limit: usize, control: &StorageReadControl, visit: &mut KeyValueReadVisitor<'_>, ) -> StorageBackendResult<()>

Visit at most limit entries in key order, strictly after after when supplied. Encoded values remain borrowed from their provider owner and callbacks must not reenter the store.

fn put(&self, key: &[u8], value: &[u8]) -> StorageBackendResult<()>

fn delete(&self, key: &[u8]) -> StorageBackendResult<()>

fn scan_prefix( &self, prefix: &[u8], ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>>

fn scan_prefix_after( &self, prefix: &[u8], after: Option<&[u8]>, limit: usize, ) -> StorageBackendResult<Vec<(Vec<u8>, Vec<u8>)>>

Return at most limit key/value pairs in key order, strictly after after when supplied. This is the bounded value cursor used by large format migrations and other paged consumers.

fn scan_prefix_keys_after( &self, prefix: &[u8], after: Option<&[u8]>, limit: usize, ) -> StorageBackendResult<Vec<Vec<u8>>>

Return at most limit keys in key order, strictly after after when it is present. Backends should override this method with a key-only, bounded range scan so cursor consumers neither materialize the entire prefix nor read values they do not need on every page.

fn first_prefix_after( &self, prefix: &[u8], after: Option<&[u8]>, ) -> StorageBackendResult<Option<(Vec<u8>, Vec<u8>)>>

fn delete_prefix(&self, prefix: &[u8]) -> StorageBackendResult<usize>

fn batch(&self) -> Box<dyn KeyValueBatch + '_>

fn begin_transaction(&self) -> StorageBackendResult<()>

fn begin_read_transaction(&self) -> StorageBackendResult<()>

fn begin_upgradeable_transaction(&self) -> StorageBackendResult<()>

fn in_transaction(&self) -> bool

fn transaction_has_written(&self) -> StorageBackendResult<bool>

Report ordinary record and derived-index writes, excluding typed auxiliary notification effects. Ordinary writes remain forbidden in read-only transactions.

fn change_version(&self) -> StorageBackendResult<Option<u64>>

fn read_view_revision( &self, ) -> StorageBackendResult<Option<KeyValueReadRevision>>

Complete committed/private visibility identity, including savepoint undo. None requires consumers to use their existing refresh path. Tokens are process-local and do not replace transaction isolation or logical read observations.

fn completed_commit(&self) -> Option<CommitReceipt>

Receipt of this session’s last successfully completed write transaction. This is not the latest database commit. A new transaction, rollback or read-only completion clears it; unsupported stores return None.

fn commit_transaction(&self) -> StorageBackendResult<()>

fn rollback_transaction(&self) -> StorageBackendResult<()>

fn savepoint(&self, name: &str) -> StorageBackendResult<()>

fn release_savepoint(&self, name: &str) -> StorageBackendResult<()>

fn rollback_to_savepoint(&self, name: &str) -> StorageBackendResult<()>

fn auxiliary_encryption_key(&self) -> Option<StorageEncryptionKey>

Credential for database-owned auxiliary files. Wrappers over an encrypted store must forward it; None permits unencrypted auxiliary storage.

fn vacuum(&self) -> StorageBackendResult<()>

Reclaim obsolete records and compact physical storage where supported, outside this session’s transaction.

fn change_version_monitor_is_nonblocking(&self) -> StorageBackendResult<bool>

fn pin_transaction_snapshot(&self) -> StorageBackendResult<()>

impl NotificationPublicationStore for VersionedKeyValueStore

fn stage_notification_publication( &self, publication: &NotificationPublication, ) -> StorageBackendResult<()>

fn visit_notification_publication( &self, control: &StorageReadControl, visit: &mut dyn FnMut(Option<NotificationPublicationView<'_>>) -> StorageBackendResult<()>, ) -> StorageBackendResult<()>

fn acknowledge_notification_publication( &self, fingerprint: [u8; 32], control: &StorageReadControl, ) -> StorageBackendResult<()>

Clear only the acknowledged fingerprint through autonomous committed state. The caller must serialize queue acknowledgement and new publication and supply uncancelled completion control.

fn stage_notification_publication_after( &self, publication: &NotificationPublication, acknowledged: Option<[u8; 32]>, ) -> StorageBackendResult<()>

Replace a previous slot only when the registry has already committed that exact acknowledgement. Serialized physical writers may need to carry this cleanup in their own atomic data transaction; the default requires autonomous cleanup first.

fn try_acknowledge_notification_publication( &self, fingerprint: [u8; 32], control: &StorageReadControl, ) -> StorageBackendResult<bool>

Return false when an existing physical writer prevents autonomous cleanup. The registry acknowledgement remains authoritative, and a later publisher may replace only that acknowledged fingerprint.

impl SerializableSession for VersionedKeyValueStore

fn establish_serializable_snapshot( &self, ) -> StorageBackendResult<SerializableReadContext>

fn establish_serializable_snapshot_with( &self, options: SerializableSnapshotOptions, capture: &mut SerializableSnapshotCapture<'_>, ) -> StorageBackendResult<SerializableReadContext>

Select the first snapshot using logical characteristics and a caller-scoped capture. Existing participants retain their original classification without another capture. Only read-only deferrable admission waits for a proven safe snapshot.

fn serializable_read_context( &self, ) -> StorageBackendResult<Option<SerializableReadContext>>

fn observe_serializable_write( &self, predicate: SerializablePredicate<'_>, ) -> StorageBackendResult<()>