Struct ProllyEngine 

pub struct ProllyEngine<S: AsyncStore> { /* private fields */ }

Canonical runtime owner for async prolly algorithms.

Implementations

impl<S> ProllyEngine<S>

where S: AsyncStore, S::Error: Send + Sync,

pub fn new(store: S, config: Config) -> Self

Create an async-first engine with bounded default execution limits.

pub fn with_execution_config( store: S, config: Config, execution: ExecutionConfig, ) -> Self

Create an async-first engine with explicit execution limits.

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

Read one key using the input tree’s persisted format.

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

Read keys in input order, preserving duplicates and missing positions.

impl<S> ProllyEngine<S>

where S: AsyncStore, S::Error: Send + Sync,

pub async fn prove_key( &self, tree: &Tree, key: &[u8], ) -> Result<KeyProof, Error>

Build a root-to-leaf proof for key.

The returned proof is self-contained and can be verified without access to this store. A valid proof may prove either key presence or absence.

pub async fn prove_keys<K: AsRef<[u8]>>( &self, tree: &Tree, keys: &[K], ) -> Result<MultiKeyProof, Error>

Build one shared proof for multiple keys.

The returned proof de-duplicates shared path nodes while preserving the input key order. A valid proof may prove a mix of key presence and absence.

pub async fn prove_range( &self, tree: &Tree, start: &[u8], end: Option<&[u8]>, ) -> Result<RangeProof, Error>

Build a complete proof for every entry in [start, end).

The returned proof contains all overlapping child subtrees needed to verify range completeness without access to this store.

pub async fn prove_prefix( &self, tree: &Tree, prefix: &[u8], ) -> Result<RangeProof, Error>

Build a complete proof for every entry whose key starts with prefix.

pub async fn prove_range_page( &self, tree: &Tree, cursor: &RangeCursor, end: Option<&[u8]>, limit: usize, ) -> Result<ProvedRangePage, Error>

Read a bounded range page and build a proof for exactly that page window.

pub async fn prove_diff_page( &self, base: &Tree, other: &Tree, cursor: &RangeCursor, end: Option<&[u8]>, limit: usize, ) -> Result<ProvedDiffPage, Error>

Read a bounded diff page through the async store and build a proof for exactly that page.

impl<S> ProllyEngine<S>

where S: AsyncStore, S::Error: Send + Sync,

pub async fn read<'manager, 'tree>( &'manager self, tree: &'tree Tree, ) -> Result<AsyncReadSession<'manager, 'tree, S>, Error>

Open a reusable borrowed async read session over an immutable tree.

pub async fn len(&self, tree: &Tree) -> Result<u64, Error>

Return the number of logical key/value entries in a tree.

pub async fn rank(&self, tree: &Tree, key: &[u8]) -> Result<u64, Error>

Return the number of keys strictly less than key.

pub async fn select( &self, tree: &Tree, ordinal: u64, ) -> Result<Option<KeyValue>, Error>

Return the zero-based entry at ordinal, or None when out of range.

pub async fn select_with<R>( &self, tree: &Tree, ordinal: u64, read: impl for<'entry> FnOnce(EntryRef<'entry>) -> R, ) -> Result<Option<R>, Error>

pub async fn first_entry(&self, tree: &Tree) -> Result<Option<KeyValue>, Error>

Return the first key/value entry in key order.

pub async fn first_entry_with<R>( &self, tree: &Tree, read: impl for<'entry> FnOnce(EntryRef<'entry>) -> R, ) -> Result<Option<R>, Error>

pub async fn last_entry(&self, tree: &Tree) -> Result<Option<KeyValue>, Error>

Return the last key/value entry in key order.

pub async fn last_entry_with<R>( &self, tree: &Tree, read: impl for<'entry> FnOnce(EntryRef<'entry>) -> R, ) -> Result<Option<R>, Error>

pub async fn lower_bound( &self, tree: &Tree, key: &[u8], ) -> Result<Option<KeyValue>, Error>

Return the first entry whose key is greater than or equal to key.

pub async fn lower_bound_with<R>( &self, tree: &Tree, key: &[u8], read: impl for<'entry> FnOnce(EntryRef<'entry>) -> R, ) -> Result<Option<R>, Error>

pub async fn upper_bound( &self, tree: &Tree, key: &[u8], ) -> Result<Option<KeyValue>, Error>

Return the first entry whose key is strictly greater than key.

pub async fn upper_bound_with<R>( &self, tree: &Tree, key: &[u8], read: impl for<'entry> FnOnce(EntryRef<'entry>) -> R, ) -> Result<Option<R>, Error>

pub async fn get_with<R>( &self, tree: &Tree, key: &[u8], read: impl FnOnce(&[u8]) -> R, ) -> Result<Option<R>, Error>

Read one async-store value without allocating an owned result.

pub async fn get_value_ref_with<R>( &self, tree: &Tree, key: &[u8], read: impl for<'value> FnOnce(ValueRefView<'value>) -> R, ) -> Result<Option<R>, Error>

Inspect a stored large-value envelope without copying inline bytes.

pub async fn get_many_with<K, F>( &self, tree: &Tree, keys: &[K], visit: F, ) -> Result<(), Error>

where K: AsRef<[u8]>, F: for<'value> FnMut(usize, &[u8], Option<&'value [u8]>),

Visit async point-read results exactly once per input position.

pub async fn scan_range( &self, tree: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'entry> FnMut(EntryRef<'entry>), ) -> Result<u64, Error>

Visit an async half-open range without allocating entries.

pub async fn scan_range_until<B>( &self, tree: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'entry> FnMut(EntryRef<'entry>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

pub async fn scan_prefix( &self, tree: &Tree, prefix: &[u8], visit: impl for<'entry> FnMut(EntryRef<'entry>), ) -> Result<u64, Error>

Visit an async prefix without allocating entries.

pub async fn scan_prefix_until<B>( &self, tree: &Tree, prefix: &[u8], visit: impl for<'entry> FnMut(EntryRef<'entry>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

pub async fn scan_range_reverse( &self, tree: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'entry> FnMut(EntryRef<'entry>), ) -> Result<u64, Error>

pub async fn scan_range_reverse_until<B>( &self, tree: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'entry> FnMut(EntryRef<'entry>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

pub async fn scan_prefix_reverse( &self, tree: &Tree, prefix: &[u8], visit: impl for<'entry> FnMut(EntryRef<'entry>), ) -> Result<u64, Error>

pub async fn scan_prefix_reverse_until<B>( &self, tree: &Tree, prefix: &[u8], visit: impl for<'entry> FnMut(EntryRef<'entry>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

impl<S> ProllyEngine<S>

where S: AsyncStore + AsyncManifestStore + AsyncTransactionalStore, <S as AsyncStore>::Error: Send + Sync, <S as AsyncManifestStore>::Error: Send + Sync,

pub fn begin_transaction(&self) -> Result<AsyncProllyTransaction<'_, S>, Error>

Start a strict optimistic async transaction.

pub fn begin_owned_transaction( &self, ) -> Result<OwnedAsyncProllyTransaction<S>, Error>

where S: Clone,

Start a strict optimistic async transaction that owns a cloned store handle and can therefore outlive a borrow of this manager.

pub async fn transaction<T, F>(&self, f: F) -> Result<T, Error>

where F: for<'tx> FnOnce(&'tx mut AsyncProllyTransaction<'_, S>) -> Pin<Box<dyn Future<Output = Result<T, Error>> + 'tx>>,

Run a boxed future in a transaction, committing on success and rolling back automatically when the future returns an error or commit validation fails.

impl<S: AsyncStore> ProllyEngine<S>

pub fn versioned_map(&self, id: impl AsRef<[u8]>) -> AsyncVersionedMap<'_, S>

Open an async managed map.

impl<S> ProllyEngine<S>

where S: AsyncStore, S::Error: Send + Sync,

pub async fn scan_diff( &self, base: &Tree, other: &Tree, visit: impl for<'diff> FnMut(DiffRef<'diff>), ) -> Result<u64, Error>

Visit async structural differences without owned diff records.

pub async fn scan_diff_until<B>( &self, base: &Tree, other: &Tree, visit: impl for<'diff> FnMut(DiffRef<'diff>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

Visit async structural differences with early termination.

pub async fn scan_range_diff( &self, base: &Tree, other: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'diff> FnMut(DiffRef<'diff>), ) -> Result<u64, Error>

Visit async differences in [start, end) without owned records.

pub async fn scan_range_diff_until<B>( &self, base: &Tree, other: &Tree, start: &[u8], end: Option<&[u8]>, visit: impl for<'diff> FnMut(DiffRef<'diff>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

Visit async range differences with early termination.

pub async fn scan_conflicts( &self, base: &Tree, left: &Tree, right: &Tree, visit: impl for<'conflict> FnMut(ConflictRef<'conflict>), ) -> Result<u64, Error>

Visit async three-way conflicts through a callback-scoped view.

The current async iterator retains one owned conflict at a time so no borrowed node data crosses an await. The callback API is stable for a future retained-node-handle implementation and never accumulates all conflicts in memory.

pub async fn scan_conflicts_until<B>( &self, base: &Tree, left: &Tree, right: &Tree, visit: impl for<'conflict> FnMut(ConflictRef<'conflict>) -> ControlFlow<B>, ) -> Result<ScanOutcome<B>, Error>

Visit async conflicts with callback-controlled early termination.

pub async fn merge_with( &self, base: &Tree, left: &Tree, right: &Tree, resolver: Option<&dyn BorrowedMergeResolver>, ) -> Result<Tree, Error>

Async merge with a callback-scoped symbolic conflict resolver.

pub async fn merge_range_with( &self, base: &Tree, left: &Tree, right: &Tree, start: &[u8], end: Option<&[u8]>, resolver: Option<&dyn BorrowedMergeResolver>, ) -> Result<Tree, Error>

Async range merge with a borrowed conflict resolver.

pub async fn merge_prefix_with( &self, base: &Tree, left: &Tree, right: &Tree, prefix: &[u8], resolver: Option<&dyn BorrowedMergeResolver>, ) -> Result<Tree, Error>

Async prefix merge with a borrowed conflict resolver.

impl<S> ProllyEngine<S>

where S: AsyncStore, S::Error: Send + Sync,

pub fn create(&self) -> Tree

Create a new empty tree.

pub async fn build_from_entries( &self, entries: Vec<(Vec<u8>, Vec<u8>)>, ) -> Result<Tree, Error>

Build a tree from an owned collection of key/value entries.

Input may be unsorted. The canonical mutation planner sorts it and applies duplicate keys with last-write-wins semantics.

pub async fn build_from_sorted_entries( &self, entries: Vec<(Vec<u8>, Vec<u8>)>, ) -> Result<Tree, Error>

Build a tree from entries that are already sorted by key.

Duplicate keys are allowed and retain the last value. Decreasing input is rejected before any storage write occurs.

pub fn store(&self) -> &S

Borrow the underlying async store.

pub fn config(&self) -> &Config

Borrow this manager’s tree configuration.

pub async fn get_value_ref( &self, tree: &Tree, key: &[u8], ) -> Result<Option<ValueRef>, Error>

Get a stored large-value reference by key.

Non-envelope values are returned as blob::ValueRef::Inline, so this can inspect trees that mix ordinary raw values and offloaded blob references.

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

where B: AsyncBlobStore, B::Error: Send + Sync,

Get a value by key, resolving offloaded async blob references when present.

pub async fn put( &self, tree: &Tree, key: Vec<u8>, val: Vec<u8>, ) -> Result<Tree, Error>

Insert or update a key-value pair in the tree.

This is the async counterpart to Prolly::put. It rewrites only the affected path, publishes rewritten nodes through AsyncStore::publish_nodes, and returns a new immutable tree handle.

pub async fn put_large_value<B>( &self, blob_store: &B, tree: &Tree, key: Vec<u8>, value: Vec<u8>, config: LargeValueConfig, ) -> Result<Tree, Error>

where B: AsyncBlobStore, B::Error: Send + Sync,

Insert or update a value, offloading large payloads to an async blob store.

Values larger than config.inline_threshold are written to blob_store and represented in the tree by a compact content-addressed reference.

pub async fn delete(&self, tree: &Tree, key: &[u8]) -> Result<Tree, Error>

Delete a key from the tree.

Missing keys are idempotent and return the original tree unchanged.

pub async fn delete_range( &self, tree: &Tree, start: &[u8], end: &[u8], ) -> Result<Tree, Error>

Delete all existing keys in the half-open range [start, end).

The range is first collected through the async iterator, then applied as one async batch so the resulting node writes remain atomic.

pub async fn delete_range_with_stats( &self, tree: &Tree, start: &[u8], end: &[u8], ) -> Result<(Tree, WriteStats), Error>

Delete all existing keys in [start, end) and return manager-observed write statistics.

pub async fn batch( &self, tree: &Tree, mutations: Vec<Mutation>, ) -> Result<Tree, Error>

Apply multiple mutations using one async batch write.

Mutations are sorted and deduplicated with last-write-wins semantics. The async batch planner routes those mutations to affected leaves using ordered async node loads, applies each touched leaf once, rebuilds only touched ancestors, and flushes all rewritten nodes through a single AsyncStore::publish_nodes call.

pub async fn batch_with_lineage( &self, tree: &Tree, mutations: Arc<Vec<Mutation>>, ) -> Result<Tree, Error>

Apply a sorted, unique mutation batch and retain its direct ancestry for a later same-engine three-way merge.

pub async fn batch_with_write_stats( &self, tree: &Tree, mutations: Vec<Mutation>, ) -> Result<(Tree, WriteStats), Error>

Apply multiple mutations through the canonical writer and return its store-neutral work counters.

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

Create an async range iterator over key-value pairs.

The iterator yields keys in lexicographic order from start inclusive to end exclusive. It is lazy: each call to AsyncRangeIter::next reads only the nodes needed to advance, while stores that prefer batch reads can prefetch nearby child nodes.

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

Create an async range iterator over all keys that start with prefix.

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

Read a bounded page from an async prefix scan.

pub async fn range_after<'a>( &'a self, tree: &Tree, after_key: &[u8], end: Option<&[u8]>, ) -> Result<AsyncRangeIter<'a, S>, Error>

Create an async range iterator that resumes strictly after after_key.

This is useful for checkpointed background jobs: persist the last key successfully processed, then resume with this method to avoid yielding that key again.

pub async fn range_from_cursor<'a>( &'a self, tree: &Tree, cursor: &RangeCursor, end: Option<&[u8]>, ) -> Result<AsyncRangeIter<'a, S>, Error>

Create an async range iterator from a stable range cursor.

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

Read a bounded page from an async range scan.

cursor is either RangeCursor::start or a cursor returned by a previous page. end is still exclusive. When limit is zero this returns an empty page with the original cursor so callers can treat zero-sized requests as no-ops.

pub async fn cursor_window( &self, tree: &Tree, key: &[u8], end: Option<&[u8]>, limit: usize, ) -> Result<CursorWindow, Error>

Seek to key and return a bounded forward window using engine-native order statistics and range traversal.

pub async fn reverse_page( &self, tree: &Tree, cursor: &ReverseCursor, start: &[u8], limit: usize, ) -> Result<AsyncReversePage, Error>

Read a bounded page in descending key order through the async store.

start is an inclusive lower bound. A start cursor scans from the end of the range; a resumed cursor scans keys strictly before its stored key.

pub async fn prefix_reverse_page( &self, tree: &Tree, prefix: &[u8], cursor: &ReverseCursor, limit: usize, ) -> Result<AsyncReversePage, Error>

Read a bounded async page over keys that start with prefix in descending key order.

pub async fn reverse_range_page( &self, tree: &Tree, cursor: &ReverseCursor, start: &[u8], end: Option<&[u8]>, limit: usize, ) -> Result<AsyncReversePage, Error>

Read a bounded async descending page over [start, end).

pub async fn diff(&self, base: &Tree, other: &Tree) -> Result<Vec<Diff>, Error>

Compute the difference between two trees through the async store.

This mirrors Prolly::diff and preserves structural subtree pruning: identical CIDs are skipped, aligned internal nodes are compared by child CID, and stores that prefer batch reads hydrate sibling frontiers through ordered async batch reads.

pub async fn range_diff( &self, base: &Tree, other: &Tree, start: &[u8], end: Option<&[u8]>, ) -> Result<Vec<Diff>, Error>

Compute the difference between two trees within a half-open key range.

Returns only changes whose key is in [start, end). This mirrors Prolly::range_diff but loads nodes through AsyncStore.

pub async fn diff_from_cursor( &self, base: &Tree, other: &Tree, cursor: &RangeCursor, end: Option<&[u8]>, ) -> Result<Vec<Diff>, Error>

Compute diffs from a stable cursor through the async store.

This resumes strictly after the cursor key, so callers can persist the last processed diff key and avoid re-processing it on the next scan.

pub async fn diff_page( &self, base: &Tree, other: &Tree, cursor: &RangeCursor, end: Option<&[u8]>, limit: usize, ) -> Result<DiffPage, Error>

Read a bounded page of diffs through the async store.

pub async fn structural_diff_page( &self, base: &Tree, other: &Tree, cursor: Option<&StructuralDiffCursor>, limit: usize, ) -> Result<StructuralDiffPage, Error>

Read a bounded page from the async structural diff traversal.

This is the async counterpart to Prolly::structural_diff_page. Pass None to start, then pass the returned cursor until next_cursor is None.

pub fn stream_diff<'a>( &'a self, base: &Tree, other: &Tree, ) -> AsyncDiffIter<'a, S>

Create an async streaming diff iterator between two trees.

This is the async counterpart to Prolly::stream_diff. The iterator preserves structural subtree pruning and yields one diff at a time through AsyncDiffIter::next, so callers can stop early without materializing every change.

pub fn stream_conflicts<'a>( &'a self, base: &Tree, left: &'a Tree, right: &Tree, ) -> AsyncConflictIter<'a, S>

Create an async streaming merge-conflict iterator for a three-way merge.

This is the async counterpart to Prolly::stream_conflicts. It walks the async structural diff path, skips non-conflicting right-side changes, and yields delete-aware Conflict values through AsyncConflictIter::next.

pub async fn merge( &self, base: &Tree, left: &Tree, right: &Tree, resolver: Option<Resolver>, ) -> Result<Tree, Error>

Merge two trees using async three-way merge.

This mirrors Prolly::merge: base is the common ancestor, changes from right are applied to left, and conflicting edits are passed to the optional delete-aware resolver. The implementation loads changed keys through AsyncStore and writes the merged tree through the async batch path.

pub async fn merge_explain( &self, base: &Tree, left: &Tree, right: &Tree, resolver: Option<Resolver>, ) -> MergeExplanation

Perform an async three-way merge and return structured diagnostic trace events.

This is the async diagnostics-oriented counterpart to AsyncProlly::merge. The returned crate::MergeExplanation keeps its trace even when the merge result is an error, which is useful for remote sync jobs, object-store backends, and custom resolver debugging.

pub async fn merge_range( &self, base: &Tree, left: &Tree, right: &Tree, start: &[u8], end: Option<&[u8]>, resolver: Option<Resolver>, ) -> Result<Tree, Error>

Merge only right-side changes whose keys are in [start, end) through the async store.

Keys outside the range are left exactly as they are in left. Conflict detection and resolver behavior match AsyncProlly::merge, but only for keys inside the requested range.

pub async fn merge_prefix( &self, base: &Tree, left: &Tree, right: &Tree, prefix: &[u8], resolver: Option<Resolver>, ) -> Result<Tree, Error>

Merge only right-side changes whose keys start with prefix through the async store.

pub async fn crdt_merge( &self, base: &Tree, left: &Tree, right: &Tree, config: &CrdtConfig, ) -> Result<Tree, Error>

Merge two trees with async CRDT-style conflict-free resolution.

This mirrors Prolly::crdt_merge. Built-in and custom CRDT strategies always choose a value or delete for conflicts, so this method never returns Error::Conflict unless a lower layer violates the merge contract.

pub async fn crdt_merge_explain( &self, base: &Tree, left: &Tree, right: &Tree, config: &CrdtConfig, ) -> MergeExplanation

Async CRDT merge with structured diagnostics.

pub async fn collect_stats(&self, tree: &Tree) -> Result<TreeStats, Error>

Collect comprehensive statistics about a tree through the async store.

This mirrors Prolly::collect_stats, traversing the tree level-by-level and hydrating each child frontier through ordered async batch reads.

pub async fn debug_tree(&self, tree: &Tree) -> Result<TreeDebugView, Error>

Return a deterministic debug view of the tree through the async store.

This mirrors Prolly::debug_tree and loads each child frontier through ordered async batch reads.

pub async fn debug_compare_trees( &self, left: &Tree, right: &Tree, ) -> Result<TreeDebugComparison, Error>

Compare two trees by CID sharing and rewritten subtrees through the async store.

This mirrors Prolly::debug_compare_trees. Shared nodes are counted once; side-only nodes show which subtrees were rewritten, added, or removed.

pub async fn stats_diff( &self, before: &Tree, after: &Tree, ) -> Result<StatsComparison, Error>

Compare structural statistics between two trees through the async store.

Deltas are computed as after - before, matching Prolly::stats_diff.

pub async fn mark_reachable( &self, roots: &[Tree], ) -> Result<GcReachability, Error>

Mark all content-addressed nodes reachable from retained tree roots.

This mirrors Prolly::mark_reachable while loading changed frontiers through AsyncStore::batch_get_ordered_unique.

pub async fn plan_missing_nodes<D>( &self, tree: &Tree, destination: &D, ) -> Result<MissingNodePlan, Error>

where D: AsyncStore, D::Error: Send + Sync,

Plan which content-addressed nodes an async destination store is missing.

This is the async equivalent of Prolly::plan_missing_nodes. The destination and source are read through ordered async batch APIs so remote stores can overlap fetches internally.

pub async fn copy_missing_nodes<D>( &self, tree: &Tree, destination: &D, ) -> Result<MissingNodeCopy, Error>

where D: AsyncStore, D::Error: Send + Sync,

Copy all async-destination-missing nodes required by tree.

Source and destination node bytes are verified against their CIDs before the copy succeeds.

pub async fn export_snapshot( &self, tree: &Tree, ) -> Result<SnapshotBundle, Error>

Export one tree and its reachable nodes as a verified portable bundle.

pub async fn import_snapshot( &self, bundle: &SnapshotBundle, ) -> Result<Tree, Error>

Validate and import a portable tree snapshot into the async node store.

pub async fn plan_gc<I, C>( &self, roots: &[Tree], candidates: I, ) -> Result<GcPlan, Error>

where I: IntoIterator<Item = C>, C: Borrow<Cid>,

Build a dry-run node garbage-collection plan from retained roots and candidates.

pub async fn sweep_gc<I, C>( &self, roots: &[Tree], candidates: I, ) -> Result<GcSweep, Error>

where I: IntoIterator<Item = C>, C: Borrow<Cid>,

Delete exactly the unreachable nodes selected by Self::plan_gc.

pub async fn mark_reachable_blobs( &self, roots: &[Tree], ) -> Result<BlobGcReachability, Error>

Mark all offloaded blobs reachable from retained tree roots through the async node store.

pub async fn plan_blob_gc<B, I, C>( &self, blob_store: &B, roots: &[Tree], candidates: I, ) -> Result<BlobGcPlan, Error>

where B: AsyncBlobStore, B::Error: Send + Sync, I: IntoIterator<Item = C>, C: Borrow<BlobRef>,

Build a dry-run garbage-collection plan for offloaded blobs through an async blob store.

pub async fn sweep_blob_gc<B, I, C>( &self, blob_store: &B, roots: &[Tree], candidates: I, ) -> Result<BlobGcSweep, Error>

where B: AsyncBlobStore, B::Error: Send + Sync, I: IntoIterator<Item = C>, C: Borrow<BlobRef>,

Delete unreachable candidate blobs from an async blob store.

pub fn clear_cache(&self)

Clear in-process async manager caches.

pub fn clear_unpinned_cache(&self)

Clear decoded cache entries except roots or paths explicitly pinned by the caller. Recent-leaf and right-edge traversal state is still reset.

pub fn cache_len(&self) -> usize

Return the current node-cache entry count.

pub fn cache_bytes_len(&self) -> usize

Return the serialized-node byte weight retained by this async manager cache.

pub fn cache_pinned_len(&self) -> usize

Return the number of pinned nodes currently retained by this async manager.

Pinned nodes are a cache hint only. They may temporarily keep the cache above configured node or byte limits, and cache misses still fall back to the backing store.

pub fn cache_pinned_bytes_len(&self) -> usize

Return the serialized-node byte weight of pinned async cache entries.

pub async fn pin_tree_root(&self, tree: &Tree) -> Result<usize, Error>

Pin the root node of a tree in this async manager’s node cache.

This is useful for hot snapshots where repeated reads are expected to start from the same root. Empty trees pin nothing. The return value is the number of nodes that became newly pinned.

pub async fn pin_tree_path( &self, tree: &Tree, key: &[u8], ) -> Result<usize, Error>

Pin the root-to-leaf lookup path for key in this async manager’s cache.

The path is the same traversal that a lookup or point mutation would use for the key, including the would-be leaf for missing keys. Empty trees pin nothing. The return value is the number of nodes that became newly pinned.

pub async fn publish_prefix_path_hint( &self, tree: &Tree, prefix: &[u8], ) -> Result<bool, Error>

Persist a correctness-optional root-to-leaf path hint for a hot prefix.

pub async fn hydrate_prefix_path_hint( &self, tree: &Tree, prefix: &[u8], ) -> Result<bool, Error>

Hydrate the validated node cache from a correctness-optional prefix hint.

pub async fn publish_changed_spans_hint<I>( &self, base: &Tree, changed: &Tree, spans: I, ) -> Result<bool, Error>

where I: IntoIterator<Item = ChangedSpan>,

Persist normalized changed spans for a root transition.

pub async fn load_changed_spans_hint( &self, base: &Tree, changed: &Tree, ) -> Result<Option<ChangedSpanHint>, Error>

Load normalized changed spans for an exact root transition.

pub fn unpin_all_cache_nodes(&self) -> usize

Unpin all pinned node-cache entries for this async manager.

After unpinning, normal cache eviction runs immediately. Returns the number of entries that were pinned before this call.

pub fn metrics(&self) -> ProllyMetricsSnapshot

Return cumulative cache and node I/O metrics for this async manager.

pub fn reset_metrics(&self)

Reset cumulative async manager metrics to zero.

This does not clear the node cache; call AsyncProlly::clear_cache when you want the next operation to run from a cold manager cache.

pub async fn load_named_root(&self, name: &[u8]) -> Result<Option<Tree>, Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Load a named root as a Tree through the underlying async manifest store.

Missing names return Ok(None).

pub async fn load_named_roots<I, N>( &self, names: I, ) -> Result<NamedRootSelection, Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync, I: IntoIterator<Item = N>, N: AsRef<[u8]>,

Load explicit named roots and report names that were absent.

Duplicate names are ignored after their first occurrence. Missing names are reported in NamedRootSelection::missing_names instead of being silently dropped so callers can decide whether to continue.

pub async fn list_named_root_manifests( &self, ) -> Result<Vec<NamedRootManifest>, Error>

where S: AsyncManifestStoreScan, <S as AsyncManifestStore>::Error: Send + Sync,

List every named root manifest in the async manifest store.

Results are sorted by raw name bytes when the backing store implements the AsyncManifestStoreScan contract.

pub async fn list_named_roots(&self) -> Result<Vec<NamedRoot>, Error>

where S: AsyncManifestStoreScan, <S as AsyncManifestStore>::Error: Send + Sync,

List every named root in the async manifest store.

Results are sorted by raw name bytes when the backing store implements the AsyncManifestStoreScan contract.

pub async fn load_retained_named_roots( &self, retention: &NamedRootRetention, ) -> Result<NamedRootSelection, Error>

where S: AsyncManifestStoreScan, <S as AsyncManifestStore>::Error: Send + Sync,

Select named roots according to a retention policy.

Prefix and newest-by-name policies use manifest scanning. Exact policies load the requested names and report absent names explicitly.

pub async fn publish_named_root( &self, name: &[u8], tree: &Tree, ) -> Result<(), Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Publish a tree handle under a durable name through the async manifest store.

This unconditionally replaces the existing named root. Use AsyncProlly::compare_and_swap_named_root when coordinating concurrent writers.

pub async fn publish_named_root_at_millis( &self, name: &[u8], tree: &Tree, timestamp_millis: u64, ) -> Result<(), Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Publish a tree handle under a durable name with explicit timestamp metadata.

created_at_millis is preserved from the existing manifest when present; otherwise it is initialized to timestamp_millis. updated_at_millis is always set to timestamp_millis.

pub async fn delete_named_root(&self, name: &[u8]) -> Result<(), Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Delete a durable named root.

Deleting a missing name is not an error. This removes the mutable name only; it does not garbage-collect content-addressed nodes.

pub async fn compare_and_swap_named_root( &self, name: &[u8], expected: Option<&Tree>, new: Option<&Tree>, ) -> Result<NamedRootUpdate, Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Atomically update a named root when the current tree matches expected.

expected == None means the name must be absent. new == None deletes the name after a successful compare.

pub async fn compare_and_swap_named_root_at_millis( &self, name: &[u8], expected: Option<&Tree>, new: Option<&Tree>, timestamp_millis: u64, ) -> Result<NamedRootUpdate, Error>

where S: AsyncManifestStore, <S as AsyncManifestStore>::Error: Send + Sync,

Atomically update a named root with explicit timestamp metadata.

Tree-level compare-and-swap compares expected against the current tree handle, then performs the backend CAS against the exact current manifest. This keeps tree CAS stable even as manifests gain metadata fields.