Struct VersionedMap 

pub struct VersionedMap<'a, S: Store> { /* private fields */ }

Built-in versioned map facade over a Prolly engine.

Index names are hex-encoded before being placed in the named-root namespace, so arbitrary application bytes cannot collide with another index’s roots.

Implementations

impl<'a, S: Store> VersionedMap<'a, S>

pub fn new(prolly: &'a Prolly<S>, id: impl AsRef<[u8]>) -> Self

Create a handle for id using an existing engine.

pub fn id(&self) -> &[u8]

Application-provided index identifier.

pub fn head_name(&self) -> &[u8]

Full durable named-root key used for the current head.

pub fn versions_prefix(&self) -> &[u8]

Prefix containing the immutable version roots.

pub fn typed<K, V, KC, VC>( &self, key_codec: KC, value_codec: VC, ) -> TypedVersionedMap<'a, S, K, V, KC, VC>

Add typed, schema-aware key and value codecs to this managed map.

pub fn retention_policy(&self) -> NamedRootRetention

Retention policy that keeps this index’s head and complete version catalog.

pub fn snapshot(&self) -> Result<Option<MapSnapshot<'a, S>>, Error>

where S: ManifestStore,

Pin the current head to an immutable request-scoped snapshot.

pub fn snapshot_at( &self, id: &MapVersionId, ) -> Result<Option<MapSnapshot<'a, S>>, Error>

where S: ManifestStore,

Pin one cataloged historical version to an immutable snapshot.

pub fn compare( &self, base: &MapVersionId, target: &MapVersionId, ) -> Result<MapComparison<'a, S>, Error>

where S: ManifestStore,

Pin two cataloged versions for repeatable comparison operations.

pub fn compare_to_head( &self, base: &MapVersionId, ) -> Result<MapComparison<'a, S>, Error>

where S: ManifestStore,

Pin one historical version and the current head for comparison.

pub fn prepare_merge( &self, base: &MapVersionId, candidate: &MapVersionId, ) -> Result<MapMerge<'a, S>, Error>

where S: ManifestStore,

Pin a three-way merge between base, current head, and candidate.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore,

pub fn subscribe(&self) -> Result<MapChangeSubscription<'_, S>, Error>

Start observing future head transitions from the current head.

pub fn subscribe_from( &self, last_seen: Option<MapVersionId>, ) -> MapChangeSubscription<'_, S>

Resume observing head transitions from a previously persisted version.

pub fn is_initialized(&self) -> Result<bool, Error>

Whether this managed map has a published head.

pub fn head_id(&self) -> Result<Option<MapVersionId>, Error>

Load only the current content-derived version identifier.

pub fn head(&self) -> Result<Option<MapVersion>, Error>

Load the current version, or None when the index has not been initialized.

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

Read a key from the current version. An absent index behaves like an empty map.

pub fn get_large_value<B: BlobStore>( &self, blob_store: &B, key: &[u8], ) -> Result<Option<Vec<u8>>, Error>

Read one value from head and resolve offloaded blob content.

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

Check whether a key exists in the current version.

pub fn get_many<K: AsRef<[u8]>>( &self, keys: &[K], ) -> Result<Vec<Option<Vec<u8>>>, Error>

Read several keys from one resolved current snapshot.

Results preserve caller order and duplicate keys.

pub fn range<'a>( &'a self, start: &[u8], end: Option<&[u8]>, ) -> Result<RangeIter<'a, S>, Error>

Iterate over a range in the current version.

An absent index behaves like an empty map. The iterator remains pinned to the resolved immutable snapshot even if another writer advances head.

pub fn prefix<'a>(&'a self, prefix: &[u8]) -> Result<RangeIter<'a, S>, Error>

Iterate over keys with prefix in the current version.

pub fn range_page( &self, cursor: &RangeCursor, end: Option<&[u8]>, limit: usize, ) -> Result<RangePage, Error>

Read a cursor page from the current version.

The caller should keep using the same map version while consuming a cursor. Use VersionedMap::range_page_at when the head may advance between requests and repeatable pagination is required.

pub fn prefix_page( &self, prefix: &[u8], cursor: &RangeCursor, limit: usize, ) -> Result<RangePage, Error>

Read a prefix-bounded cursor page from the current version.

pub fn version(&self, id: &MapVersionId) -> Result<Option<MapVersion>, Error>

Load a version by its stable identifier.

pub fn get_at( &self, id: &MapVersionId, key: &[u8], ) -> Result<Option<Vec<u8>>, Error>

Read a key from a specific version.

pub fn get_many_at<K: AsRef<[u8]>>( &self, id: &MapVersionId, keys: &[K], ) -> Result<Vec<Option<Vec<u8>>>, Error>

Read several keys from a specific immutable version.

pub fn range_at<'a>( &'a self, id: &MapVersionId, start: &[u8], end: Option<&[u8]>, ) -> Result<RangeIter<'a, S>, Error>

Iterate over a range in a specific cataloged version.

pub fn prefix_at<'a>( &'a self, id: &MapVersionId, prefix: &[u8], ) -> Result<RangeIter<'a, S>, Error>

Iterate over keys with prefix in a specific immutable version.

pub fn range_page_at( &self, id: &MapVersionId, cursor: &RangeCursor, end: Option<&[u8]>, limit: usize, ) -> Result<RangePage, Error>

Read a cursor page from a specific immutable version.

pub fn prefix_page_at( &self, id: &MapVersionId, prefix: &[u8], cursor: &RangeCursor, limit: usize, ) -> Result<RangePage, Error>

Read a prefix-bounded cursor page from a specific immutable version.

pub fn diff( &self, base: &MapVersionId, target: &MapVersionId, ) -> Result<Vec<Diff>, Error>

Diff two cataloged versions.

pub fn changes_since(&self, base: &MapVersionId) -> Result<Vec<Diff>, Error>

Diff a cataloged version against the current head.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + ManifestStoreScan,

pub fn versions(&self) -> Result<Vec<MapVersion>, Error>

List cataloged versions newest first.

pub fn backup(&self) -> Result<VersionedMapBackup, Error>

Export every cataloged version and the current head as one portable backup.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + TransactionalStore,

pub fn initialize(&self) -> Result<MapVersion, Error>

Initialize an empty index, or return its existing head.

pub fn import_as_head( &self, bundle: &SnapshotBundle, ) -> Result<MapVersion, Error>

Import one verified portable snapshot and atomically make it head.

pub fn import_as_head_at_millis( &self, bundle: &SnapshotBundle, timestamp_millis: u64, ) -> Result<MapVersion, Error>

Import one verified portable snapshot with an explicit catalog timestamp.

pub fn restore_backup( &self, backup: &VersionedMapBackup, ) -> Result<MapVersion, Error>

Restore a complete portable catalog into an uninitialized managed map.

pub fn apply(&self, mutations: Vec<Mutation>) -> Result<MapVersion, Error>

Apply a mutation batch atomically, retrying optimistic conflicts.

pub fn apply_at_millis( &self, mutations: Vec<Mutation>, timestamp_millis: u64, ) -> Result<MapVersion, Error>

Apply a mutation batch with an explicit timestamp.

pub fn apply_if( &self, expected: Option<&MapVersionId>, mutations: Vec<Mutation>, ) -> Result<VersionedMapUpdate, Error>

Apply mutations only when expected still identifies the current head.

pub fn apply_if_at_millis( &self, expected: Option<&MapVersionId>, mutations: Vec<Mutation>, timestamp_millis: u64, ) -> Result<VersionedMapUpdate, Error>

Apply a conditional mutation batch with an explicit timestamp.

pub fn put_if( &self, expected: Option<&MapVersionId>, key: impl Into<Vec<u8>>, value: impl Into<Vec<u8>>, ) -> Result<VersionedMapUpdate, Error>

Conditionally insert or replace one key.

pub fn delete_if( &self, expected: Option<&MapVersionId>, key: impl Into<Vec<u8>>, ) -> Result<VersionedMapUpdate, Error>

Conditionally delete one key.

pub fn edit_if( &self, expected: Option<&MapVersionId>, edit: impl FnOnce(&mut VersionedMapEditor), ) -> Result<VersionedMapUpdate, Error>

Collect several mutations and apply them only when expected is current.

pub fn put( &self, key: impl Into<Vec<u8>>, value: impl Into<Vec<u8>>, ) -> Result<MapVersion, Error>

Insert or replace one key and return the new current version.

pub fn put_large_value<B: BlobStore>( &self, blob_store: &B, key: impl Into<Vec<u8>>, value: impl Into<Vec<u8>>, config: LargeValueConfig, ) -> Result<MapVersion, Error>

Insert one value, offloading large bytes, and retry head conflicts.

pub fn put_large_value_if<B: BlobStore>( &self, blob_store: &B, expected: Option<&MapVersionId>, key: impl Into<Vec<u8>>, value: impl Into<Vec<u8>>, config: LargeValueConfig, ) -> Result<VersionedMapUpdate, Error>

Conditionally insert one inline/blob-backed value.

pub fn delete(&self, key: impl Into<Vec<u8>>) -> Result<MapVersion, Error>

Delete one key and return the new current version.

pub fn edit( &self, edit: impl FnOnce(&mut VersionedMapEditor), ) -> Result<MapVersion, Error>

Collect several mutations in a compact closure and commit them once.

pub fn append(&self, mutations: Vec<Mutation>) -> Result<MapVersion, Error>

Apply append-oriented mutations using the engine’s right-edge fast path.

pub fn parallel_apply( &self, mutations: Vec<Mutation>, config: &ParallelConfig, ) -> Result<VersionedMapBatchResult, Error>

Apply a route-planned parallel mutation batch and publish its statistics.

pub fn rollback_to(&self, id: &MapVersionId) -> Result<MapVersion, Error>

Move the head to an existing version without deleting newer snapshots.

Versions identify unique tree states rather than update events, so a rollback moves the head but does not create a duplicate catalog entry.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + ManifestStoreScan + TransactionalStore,

pub fn prune_versions( &self, keep_latest: usize, ) -> Result<VersionPruneResult, Error>

Keep the newest keep_latest cataloged versions plus the current head.

The head is always retained, even after rollback when it is older than the newest catalog entries. keep_latest == 0 therefore keeps exactly the current head. This operation removes immutable version root names in one strict transaction; it does not delete content-addressed nodes.

pub fn keep_last(&self, count: usize) -> Result<VersionPruneResult, Error>

Retain the newest count versions plus the current head.

pub fn keep_for(&self, max_age: Duration) -> Result<VersionPruneResult, Error>

Retain versions newer than max_age plus the current head.

pub fn keep_for_at( &self, now_millis: u64, max_age: Duration, ) -> Result<VersionPruneResult, Error>

Deterministic form of VersionedMap::keep_for with an explicit clock.

pub fn keep_versions<I, V>(&self, ids: I) -> Result<VersionPruneResult, Error>

where I: IntoIterator<Item = V>, V: Borrow<MapVersionId>,

Retain an explicit version set plus the current head.

Missing requested IDs are rejected so a typo cannot silently discard more history than intended.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + TransactionalStore + Clone + Send + Sync,

pub fn initialize_sorted<I, K, V>( &self, entries: I, ) -> Result<VersionedMapUpdate, Error>

where I: IntoIterator<Item = (K, V)>, K: Into<Vec<u8>>, V: Into<Vec<u8>>,

Build sorted input with the streaming builder and initialize an absent map.

pub fn rebuild_sorted_if<I, K, V>( &self, expected: Option<&MapVersionId>, entries: I, ) -> Result<VersionedMapUpdate, Error>

where I: IntoIterator<Item = (K, V)>, K: Into<Vec<u8>>, V: Into<Vec<u8>>,

Stream sorted input into a candidate tree, then CAS-replace head.

pub fn rebuild_from_iter_if<I, K, V>( &self, expected: Option<&MapVersionId>, entries: I, ) -> Result<VersionedMapUpdate, Error>

where I: IntoIterator<Item = (K, V)>, K: Into<Vec<u8>>, V: Into<Vec<u8>>,

Build arbitrary iterator input in parallel, then CAS-replace head.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + ManifestStoreScan,

pub fn verify_catalog(&self) -> Result<MapCatalogVerification, Error>

Verify root names, version IDs, head membership, and every reachable node.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + ManifestStoreScan + NodeStoreScan,

pub fn plan_gc(&self) -> Result<GcPlan, Error>

Dry-run node GC after applying this map’s retention policy.

Node storage is shared and content-addressed, so the safety boundary is necessarily store-wide: every remaining named root is retained. This prevents maintenance on one map from deleting another map’s nodes.

pub fn sweep_gc(&self) -> Result<GcSweep, Error>

Sweep store-wide nodes unreachable from every remaining named root.

impl<S> VersionedMap<'_, S>

where S: Store + ManifestStore + ManifestStoreScan,

pub fn plan_blob_gc<B: BlobStoreScan>( &self, blob_store: &B, ) -> Result<BlobGcPlan, Error>

Plan blob GC while retaining blobs from every remaining named root.

Blob stores are commonly shared by several maps, so limiting reachability to this map would make a per-map maintenance call unsafe for its peers.

pub fn sweep_blob_gc<B: BlobStoreScan>( &self, blob_store: &B, ) -> Result<BlobGcSweep, Error>

Sweep blobs unreachable from every remaining named root in the store.