Struct Store 

pub struct Store { /* private fields */ }

Ordered key/value store shared by every node: admission, deterministic expansion, group-commit publication, multi-version reads, and retention.

Implementations

impl Store

pub fn vector_cache_budget(&self) -> Option<ByteBudget>

The vector adapter’s cache budget (vector_cache_bytes).

pub fn sql_phase_budget(&self) -> Option<ByteBudget>

The SQL adapter’s named child of Store::phase_budget.

pub fn graph_phase_budget(&self) -> Option<ByteBudget>

The native graph/query adapter’s named child of Store::phase_budget

impl Store

pub fn expand_against_overlay<P>( &self, ci: u64, batch: &CommitBatch, payload: &P, overlay: Arc<OverlayView>, ) -> Result<Vec<Op>, StorageError>

where P: Serialize,

Sequencer expansion primitive: the deterministic ordered op-set for batch at commit index ci computed against overlay — a committed base plus lower-index pending ops — instead of the live committed state. Deterministic and side-effect free: takes no admission, shard or publish lock, and publishes nothing.

When overlay carries the expanded output of commits < ci, the result is byte-identical to the serialized forward path publishing those commits first (sequencer_tests asserts the equivalence). The sequencer calls this to expand without holding the shard lock across durability.

Errors

Returns the same errors as forward expansion: a base read error, or StorageError::CorruptLog/StorageError::Builder when no expander is installed or expansion fails.

pub fn commit<P, F>( &self, commit_key: Uuid, build: F, ) -> Result<CommitOutcome<P>, StorageError>

where P: Serialize + DeserializeOwned, F: FnOnce(u64, &mut Txn<'_>) -> Result<(CommitBatch, P), String>,

Autocommit path: admission builds and validates a canonical CommitBatch inside build, storage publishes everything atomically. Retrying with the same commit key discovers the durable outcome.

Errors

Returns StorageError if the publisher has failed, a precondition is violated, expansion fails, or durable publication fails.

pub fn commit_for_tenant<P, F>( &self, tenant: &TenantId, commit_key: Uuid, build: F, ) -> Result<CommitOutcome<P>, StorageError>

where P: Serialize + DeserializeOwned, F: FnOnce(u64, &mut Txn<'_>) -> Result<(CommitBatch, P), String>,

Tenant-aware autocommit. Outer shards preserve per-tenant replication ordering; the local logical writer serializes planning and expansion.

Errors

Returns StorageError if the publisher has failed, a precondition is violated, expansion fails, or durable publication fails.

pub fn commit_for_tenant_since<P, F>( &self, tenant: &TenantId, commit_key: Uuid, snapshot_ci: u64, deps: &DependencySet, build: F, ) -> Result<CommitOutcome<P>, StorageError>

where P: Serialize + DeserializeOwned, F: FnOnce(u64, &mut Txn<'_>) -> Result<(CommitBatch, P), String>,

Tenant-aware autocommit of a batch planned at an earlier snapshot: it commits only if no commit after snapshot_ci wrote a key deps covers (published or still in flight); otherwise it is CommitOutcome::Conflicted with a serializable_conflict reason.

Errors

As Store::commit_for_tenant, plus StorageError::ConflictHistoryUnavailable when the conflict window no longer holds a commit the check needs (retryable).

pub fn commit_serializable<P, F>( &self, commit_key: Uuid, snapshot_ci: u64, deps: DependencySet, build: F, ) -> Result<CommitOutcome<P>, StorageError>

where P: Serialize + DeserializeOwned, F: FnOnce(&mut Txn<'_>) -> Result<(CommitBatch, P), String>,

Serializable-optimistic entry point (document 07): deps records point/range reads performed at snapshot_ci; validation rejects if any committed mutation between then and now writes into a recorded range. Runs while the publish lock is held so validation and publication are atomic; a loser records its terminal-aborted outcome.

Errors

Returns StorageError if the publisher has failed, a precondition is violated, a conflict summary is missing, the snapshot is in the future, or publication fails. A poisoned admission, publish, or data lock permanently fences the store and returns StorageError::Unhealthy.

Panics

Panics only if batch fails to serialize (never, for a well-formed CommitBatch).

pub fn tx_apply<P, F>( &self, tx: &mut TxAccumulator, commit_key: Uuid, build: F, ) -> Result<P, StorageError>

where P: Serialize + DeserializeOwned, F: FnOnce(u64, &mut Txn<'_>) -> Result<(CommitBatch, P), String>,

Run one statement’s planning + expansion against a transaction’s accumulated overlay (read-your-writes), appending the produced writes to the transaction. Nothing is committed or visible outside the tx.

Errors

Returns StorageError if the publisher has failed, no expander is installed, or the supplied build/expansion closure fails.

Lock poisoning fences the store until reopen.

pub fn tx_read<P, F>( &self, tx: &mut TxAccumulator, f: F, ) -> Result<P, StorageError>

where F: FnOnce(&mut Txn<'_>) -> Result<P, String>,

Run a read inside a transaction: the closure sees committed state merged with the transaction’s overlay (read-your-writes) and records its reads into the transaction’s dependency set. Use get_tracked/range-tracked reads so the conflict check at commit covers what this read observed.

Errors

Returns StorageError if a backend read fails or the closure returns an error.

Lock poisoning fences the store until reopen.

pub fn tx_apply_batch( &self, tx: &mut TxAccumulator, commit_key: Uuid, batch: &CommitBatch, ) -> Result<(), StorageError>

Stage a pre-built commit batch (e.g. a statement-language mutation delta) into a transaction: the batch’s writes expand against the transaction’s overlay and append to its accumulated mutations. Nothing is committed or visible outside the tx.

Errors

Returns StorageError if the publisher has failed, no expander is installed, or expansion fails.

Lock poisoning fences the store until reopen.

pub fn tx_commit( &self, commit_key: Uuid, tx: &TxAccumulator, ) -> Result<u64, StorageError>

Atomically commit a transaction’s accumulated writes. Conflict rule: any committed mutation since base_ci that wrote a key the transaction read (public read-set) or writes (write-set, including counters) aborts it — this catches read-write anomalies and ordinal/counter clashes without the planner tracking its internal reads. Success publishes the writes as one atomic commit; conflict aborts the transaction, which may retry or roll back.

Errors

Returns StorageError if the publisher has failed, the base snapshot is in the future, a precondition fails, a conflict is detected, or publication fails.

pub fn tx_commit_revalidated( &self, commit_key: Uuid, tx: &TxAccumulator, revalidate: impl FnOnce(&dyn Fn(&[u8]) -> Result<Option<Vec<u8>>, StorageError>) -> Result<(), String> + 'static, ) -> Result<u64, StorageError>

Commit a cross-request transaction with an optional revalidator that runs inside the publish lock (atomic with conflict detection), reading keys via the injected reader — never by opening a new store view, which would nest view locks under the publish lock — and returning Err to abort the commit and record a terminal outcome.

Errors

Returns StorageError if the publisher has failed, the base snapshot is in the future, a precondition fails, the revalidator rejects, a conflict is detected, or publication fails.

impl Store

pub fn set_deriver(&self, deriver: Arc<dyn Deriver>)

Install the apply-time deriver. Install it before any commit or replay that must produce derived rows (see Store::open_with_deriver).

Lock poisoning fences the store until reopen.

impl Store

pub fn log_bytes(&self) -> Vec<Vec<u8>>

Durable-log export for tests/tools/backups.

pub fn take_log_for_crash(&self) -> Vec<Vec<u8>>

Export the decoded commit-batch payloads of the committed command log, ordered by LSN.

Lock poisoning fences the store until reopen.

pub fn try_take_log_for_crash(&self) -> Result<Vec<Vec<u8>>, StorageError>

Fallible crash-log export for recovery and archive callers. Unlike Store::take_log_for_crash, this path never converts a scan, framing, or WAL decode failure into an empty/partial log.

A durable store derives this from the WAL’s embedded-command envelope ; an in-memory store has no WAL file and keeps the row-based journal ([log_key], test mode only).

Errors

Returns StorageError::CorruptLog for malformed WAL rows and the underlying storage error for failed backend scans.

Lock poisoning fences the store until reopen.

pub fn try_log_commands_from( &self, from_lsn: u64, ) -> Result<Vec<(u64, Vec<u8>)>, StorageError>

Durable-log export of commit-batch payloads from from_lsn onward (each paired with its LSN), for a streaming-replication follower to replay via Store::apply_replicated_batch_with_payload. Empty for a non-durable store. Takes the same publish_lock as Store::try_take_log_for_crash (briefly contends with commits — poll at a bounded interval, not a tight loop).

Errors

Returns StorageError::CorruptLog for a malformed WAL record and the underlying storage error for a failed WAL read.

impl Store

pub fn compact(&self) -> Result<u64, StorageError>

Reclaim historical versions and ask redb to compact its copy-on-write pages. In-memory stores only perform logical MVCC reclamation.

Errors

Returns StorageError::ReadersActive when protected read views are open, or another StorageError if reclamation or compaction fails.

pub fn begin_shutdown(&self)

Signal a shutdown: in-flight maintenance scans stop within a batch so the store can be dropped (and redb closed cleanly) promptly.

pub fn maintenance_aborted(&self) -> bool

Whether Self::begin_shutdown has been called.

pub fn checkpoint(&self) -> Result<(), StorageError>

Make every shard’s materialization durable (one redb Immediate commit with quick-repair state) without changing logical state. Under log-first, per-commit durability is the WAL fsync; redb commits are Durability::None until this checkpoint, which is also what lets WAL segments at or below the checkpointed LSN be truncated. A no-op for in-memory stores.

Errors

Returns StorageError if a shard’s checkpoint fails.

pub fn with_quiescent_files<T>( &self, copy: impl FnOnce(u64) -> Result<T, String>, ) -> Result<Result<T, String>, StorageError>

Run copy with every store file quiescent at a durable commit: publication is held, every published commit is checkpointed durably, and no backend commits (maintenance included) until copy returns. Readers continue; commits wait. copy receives that commit index, exactly what the copied files hold (a plain Self::checkpoint records committed_version, which can run ahead of what was applied).

Errors

Returns StorageError if the checkpoint or a backend pause fails; copy’s own error is returned inside the Ok.

pub fn compact_if_idle(&self) -> Result<Option<u64>, StorageError>

Like Store::compact, but a store with protected read views returns Ok(None) (“not now”) instead of an error, so a background compactor can simply retry on the next tick. redb itself refuses to compact while any read transaction is live (TransactionInProgress); such a refusal surfaces as Err and is equally retryable by the caller.

Errors

Returns StorageError if reclamation or compaction fails.

Lock poisoning fences the store until reopen.

pub fn compact_if_needed( &self, quiesce: Duration, growth_percent: u32, ) -> Result<CompactOutcome, StorageError>

Idle compaction gated by quiescence and a growth ratio. This is what the background worker uses; its ticker is the rate limit (a cooldown here, stamped when a compaction finished, refused every other tick: effective period 2× the interval, measured 2026-10-10). It never rewrites the file while commits are flowing (quiescence), and only once the file has grown by growth_percent since the last compaction or at least [PURGED_KEYS_TO_COMPACT] keys were purged (a tenant purge frees space without growing the file). Returns why it deferred, or the commit index it compacted at.

Errors

Returns StorageError if reclamation or compaction fails.

Lock poisoning fences the store until reopen.

pub fn storage_file_bytes(&self) -> Option<u64>

Apparent size of the primary durable file, if this store is disk-backed. Operator metric only; not a durability or capacity input.

Lock poisoning fences the store until reopen.

pub fn storage_stats(&self) -> Result<StorageStatistics, StorageError>

Durable byte accounting by key family (see StorageStatistics). Aggregates every shard. Scans the key space once, so callers should sample it on a maintenance schedule, not per request.

Errors

Returns StorageError::Durability if a shard cannot be read.

Lock poisoning fences the store until reopen.

pub fn log_byte_floor(&self, max_bytes: u64) -> Result<u64, StorageError>

Lowest LSN that a byte-target retention policy must retire (via Self::retire_commit_metadata_before, which advances the retention cursor) so the WAL’s own retained bytes can shrink to max_bytes once Self::truncate_log next runs. 0 means “nothing to do” (disabled, non-durable, or already within budget).

Segment-granular: a whole sealed WAL segment is dropped at a time (the log’s actual reclamation unit), never a row — the WAL has no row-level accounting to scan. The always-open active segment is never counted as droppable.

Errors

Returns StorageError if the WAL cannot be read.

pub fn retained_log_bytes(&self) -> Result<u64, StorageError>

Total bytes retained by the segmented WAL: the sum of every segment’s valid bytes, including the active segment. 0 for a non-durable store (no WAL file).

Errors

Returns StorageError if a storage lock is poisoned.

pub fn maintenance_counters(&self) -> (u64, u64, u64)

Retention counters: (commits retired, receipts swept, compactions).

pub fn group_commit_count(&self) -> u64

Number of group-commit redb write transactions persisted (one fsync each under Local). With a linger configured, concurrent commits coalesce into fewer transactions.

pub fn retire_commit_metadata( &self, keep_commits: u64, max_keys: usize, ) -> Result<usize, StorageError>

Bounded, resumable retention step: advance the durable retention cursor (which clamps WAL truncation at the next checkpoint) by at most max_keys commits towards committed - keep_commits. Per-commit response bodies are no longer kept here: they live in retry receipts, which expire by time (Self::sweep_receipts).

No-op for in-memory stores (no WAL). Returns the number of commits retired this call; callers loop until it returns 0.

Errors

Returns StorageError if the publisher has failed or the cursor cannot be read or written.

pub fn retire_commit_metadata_before( &self, floor: u64, max_keys: usize, ) -> Result<usize, StorageError>

Self::retire_commit_metadata with an explicit floor LSN, so a retention policy (keep_all / keep_none / N commits) can drive it.

Errors

Returns StorageError if the publisher has failed or the cursor cannot be read or written.

Lock poisoning fences the store until reopen.

pub fn sweep_expired_receipts( &self, batch: usize, budget: Duration, ) -> Result<usize, StorageError>

Delete expired retry receipts in batches of batch until none are left or budget has elapsed, so the sweep keeps up with any commit rate instead of removing a fixed number per maintenance tick. The publish lock is released between batches, so commits interleave. Returns the number of receipts removed.

Errors

See Self::sweep_receipts.

pub fn sweep_receipts(&self, max_keys: usize) -> Result<usize, StorageError>

Delete at most max_keys retry receipts older than the idempotency window, oldest first through the expiry index. Each call is one bounded write; callers loop (or wait for the next tick) until it returns 0. Returns the number of receipts removed.

Errors

Returns StorageError if the store is unhealthy, the index cannot be read, a receipt row is malformed, or the erase fails.

Lock poisoning fences the store until reopen.

impl Store

pub fn set_commit_observer(&self, observer: Arc<CommitObserver>)

Install the callback that receives every timed commit phase.

Lock poisoning fences the store until reopen.

pub fn backend_lock_times(&self) -> BackendLockTimes

Backend lock timings summed over all shards (live, no scan).

pub fn writer_holds(&self) -> Vec<(WriterHolder, WriterHolds)>

Writer holds by holder, summed over every shard (live, no scan).

pub fn copy_on_write(&self) -> Option<CopyOnWrite>

Copy-on-write state of a durable store’s data files, recorded when it opened; None in memory.

pub fn data_dir(&self) -> Option<PathBuf>

Directory holding a durable store’s files, or None in memory.

pub fn conflict_window_bytes(&self) -> usize

Bytes currently retained by the in-memory conflict window.

impl Store

pub fn read_view(&self) -> Result<ReadView, StorageError>

Open a pinned read view of the latest committed state.

Errors

Returns StorageError if the publisher has failed, the native backend read fails, or the default read limits are invalid.

pub fn read_view_for_tenant( &self, tenant: &TenantId, ) -> Result<ReadView, StorageError>

Open a pinned read view restricted to the physical shard that owns tenant. This avoids opening every shard for tenant-scoped engine requests while preserving the same snapshot and lease semantics.

Errors

Returns the same errors as Store::read_view.

pub fn read_with_limits( &self, requested: Option<u64>, limits: ReadLimits, ) -> Result<ReadView, StorageError>

Open a pinned read view with explicit limits, optionally at a requested commit index.

Errors

Returns StorageError::InvalidRead for zero limits, StorageError::FutureSnapshot when requested is newer than the visible commit, StorageError::SnapshotExpired when it predates the GC floor, or a backend error if the native view cannot be opened.

Lock poisoning fences the store until reopen.

impl Store

pub fn resolve_tenant( &self, scope: &TenantScope, ) -> Result<Option<TenantId>, StorageError>

The active ordinal registered for scope, if any. Reads through a bounded cache; a miss reads the committed directory row.

Errors

Returns StorageError if the directory row cannot be read or is malformed.

pub fn tenant_scope( &self, tenant: TenantId, ) -> Result<Option<(TenantScope, TenantState)>, StorageError>

The scope digest registered for an ordinal, with its state.

Errors

Returns StorageError if the directory row cannot be read or is malformed.

pub fn active_tenants( &self, ) -> Result<Vec<(TenantId, TenantScope)>, StorageError>

Every active registered tenant, in ordinal order (O(tenants)).

Errors

Returns StorageError if the directory cannot be read or a row is malformed.

pub fn forget_tenant(&self, scope: &TenantScope)

Drop a scope from the resolution cache (after it is retired).

Lock poisoning fences the store until reopen.

impl Store

pub fn export_wal_segments<W: Write>( &self, writer: &mut W, from_lsn: u64, to_lsn: u64, ) -> Result<u64, StorageError>

Export the committed WAL as a checksummed segment stream (manifest + framed op-set records), bounded to the inclusive LSN range [from_lsn, to_lsn]. This is the CDC / PITR / incremental-backup cursor . Records come from the segmented WAL, which is the durable truth.

Errors

Returns StorageError::Durability if the WAL cannot be read or the segment cannot be written.

Lock poisoning fences the store until reopen.

pub fn replay_wal_segments<R: Read>( &self, reader: &mut R, ) -> Result<u64, StorageError>

Replay a WAL segment stream produced by Store::export_wal_segments onto this store (V2 PITR). The store must already hold the state at the segment’s base commit (a physical checkpoint, or an equivalent store); each decoded op-set is applied directly in LSN order. Returns the final commit index.

Errors

Returns StorageError if the segment is truncated/corrupt or an op-set cannot be applied.

pub fn replay_wal_segments_to<R: Read>( &self, reader: &mut R, from_lsn: Option<u64>, to_lsn: Option<u64>, ) -> Result<u64, StorageError>

Store::replay_wal_segments bounded to (from_lsn, to_lsn]: records at or below from_lsn are already in the base and are skipped, and records past to_lsn stop replay. Reads consecutive segments from reader until clean EOF.

Errors

Returns StorageError if a segment is truncated/corrupt or an op-set cannot be applied.

impl Store

pub fn new_in_memory() -> Self

Create an in-memory store with default resource budgets.

Panics

Panics if the default storage resources are invalid, which is a compile-time constant and cannot happen at runtime.

pub fn new_with_resources( config: StorageResources, ) -> Result<Self, StorageError>

Create an in-memory store with an explicit resource configuration.

Errors

Returns StorageError::InvalidConfiguration when config fails validation, or StorageError::ResourceExhausted when a byte budget cannot be created.

pub fn resource_budget(&self) -> ByteBudget

The store’s managed-byte budget.

pub fn resource_config(&self) -> StorageResources

The configuration this store was opened with.

pub fn transaction_budget(&self) -> ByteBudget

The byte budget charged for transaction staging.

pub fn approximate_map_bytes(&self) -> (u64, u64)

Approximate bytes resident in the writer’s current-value and history maps. This is the transitional RAM mirror P04 removes; the baseline harness records it so the “no full RAM mirror” milestone is measurable and comparable across revisions.

Lock poisoning fences the store until reopen.

pub fn open(path: &Path) -> Result<Self, StorageError>

Open a crash-safe redb-backed store. The materialized keyspace and MVCC metadata are restored before the store is returned.

Errors

Returns StorageError if the resource configuration is invalid, the backend cannot be opened, or its durable watermark cannot be read.

pub fn open_with_resources( path: &Path, config: StorageResources, ) -> Result<Self, StorageError>

Open a redb-backed store with an explicit resource configuration.

Errors

Returns StorageError if config is invalid, the shard backends cannot be opened, or their durable watermarks cannot be read.

pub fn open_with_deriver( path: &Path, config: StorageResources, deriver: Option<Arc<dyn Deriver>>, ) -> Result<Self, StorageError>

Open a redb-backed store with the apply-time deriver installed before WAL recovery, so replayed commits derive the same rows live publication would have.

Errors

Returns StorageError if config is invalid, the shard backends cannot be opened, their watermarks cannot be read, or replay fails.

pub fn planner_stats(&self) -> &PlannerStats

The planner-statistics cache: idle eviction and metrics.

pub fn cache_budget(&self) -> Option<ByteBudget>

The persistent shared byte budget for logical caches, or None when resources.logical-cache-bytes is 0. Every retained cache/cursor reservation from this store contends on this same child.

pub fn phase_budget(&self) -> Option<ByteBudget>

Shared byte budget for active query/adapter phases: one persistent child of the resource tree, so concurrent requests share one cap.

pub fn publisher_failure(&self) -> Option<String>

Return the terminal publisher failure, if durable publication has been fenced. Readiness callers use this to avoid routing traffic to a store whose later commits cannot become durable.

Lock poisoning fences the store until reopen.

pub fn set_expander(&self, expander: Arc<ExpandFn>)

Install the deterministic expander used to derive canonical and derived keys for every committed batch.

Lock poisoning fences the store until reopen.

pub fn is_durable(&self) -> bool

Whether this store persists to a durable backend. A construction property (was a file opened?), not a property of the map contents.

pub fn set_replicator(&self, replicator: Option<Arc<dyn Replicator>>)

Install a replication seam (e.g. an OpenRaft leader). When set, local commits route through the leader instead of publishing locally.

Lock poisoning fences the store until reopen.

pub fn replication_acknowledged_commit(&self) -> Option<u64>

Return the replication watermark when the configured replicator can expose one. A missing watermark is deliberately fail-closed for retention: history is retained until coverage is observable.

pub fn committed_version(&self) -> u64

Last durably persisted and applied commit index.

pub fn committed_index_for(&self, commit_key: Uuid) -> Option<u64>

Public idempotency probe: durable commit index for a commit key.

pub fn outcome_for(&self, commit_key: Uuid) -> Option<OutcomeKind>

Public outcome probe for transaction coordinators: distinguishes a durable committed index from a durable aborted outcome.

pub fn record_aborted_outcome( &self, commit_key: Uuid, ) -> Result<(), StorageError>

Durably record an aborted outcome under a commit key (used by rollback so a later commit attempt discovers aborted, never false success). No data is published.

Errors

Returns StorageError if the durable outcome write fails.

Lock poisoning fences the store until reopen.

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

Fallible latest-state point probe. Multi-read consumers must instead hold a ReadView. Write admission uses this under the logical writer.

Errors

Returns StorageError if the publisher has failed or the native backend read fails.

Lock poisoning fences the store until reopen.

pub fn try_outcome_for( &self, commit_key: Uuid, ) -> Result<Option<OutcomeKind>, StorageError>

Fallible outcome probe that distinguishes committed from aborted and surfaces corrupt durable state.

Errors

Returns StorageError::CorruptLog if the stored outcome row is malformed, or a backend error if the read fails.

pub fn try_get_u64(&self, k: &[u8]) -> Result<Option<u64>, StorageError>

Fallible exact-width u64 read for engine callers.

Errors

Returns StorageError::CorruptLog when a present value is not exactly eight bytes, or when the durable read fails.

Lock poisoning fences the store until reopen.

pub fn try_range_prefix( &self, prefix: &[u8], ) -> Result<Vec<(Vec<u8>, Vec<u8>)>, StorageError>

Fallible historical prefix scan for engine callers.

Errors

Returns backend or read-limit failures.

Lock poisoning fences the store until reopen.

pub fn try_get_at( &self, k: &[u8], snap: u64, ) -> Result<Option<Vec<u8>>, StorageError>

Fallible historical point read for engine callers.

Errors

Returns backend or read-limit failures.

Lock poisoning fences the store until reopen.

pub fn try_range_prefix_at( &self, prefix: &[u8], snap: u64, ) -> Result<Vec<(Vec<u8>, Vec<u8>)>, StorageError>

Fallible historical prefix scan for engine callers.

Errors

Returns backend or read-limit failures.

Lock poisoning fences the store until reopen.

pub fn retire_before(&self, watermark: u64) -> Result<usize, StorageError>

Advances retention: superseded versions covered before the watermark are reclaimed; versions still needed by any newer snapshot stay.

Errors

Returns StorageError if the durable reclamation fails.

Lock poisoning fences the store until reopen.

pub fn retire_before_batch( &self, watermark: u64, cursor: Option<Vec<u8>>, max_keys: usize, ) -> Result<Option<Vec<u8>>, StorageError>

Bounded, resumable GC: reclaim history superseded before watermark for at most max_keys per shard in this call. Returns the next key to resume from (or None when every shard finished the walk). A background driver calls this repeatedly; it never performs one monolithic redb txn.

Errors

Returns StorageError if the publisher has failed or a shard’s durable reclamation fails.

Panics

Panics if the read-pin mutex or history RwLock is poisoned by a previous panic.

pub fn gc_tick(&self, max_keys: usize) -> Result<bool, StorageError>

One tick of the background GC loop: reclaim a bounded batch toward the current committed watermark. Returns true when the whole history table was swept this tick (a full GC pass completed and a checkpoint was published per shard), false when the sweep is mid-walk and the caller should tick again. Safe to call concurrently: each tick is a small redb write transaction.

Errors

Returns StorageError if the publisher has failed or a shard’s durable reclamation fails.

Lock poisoning fences the store until reopen.

pub fn gc_tick_for( &self, max_keys: usize, budget: Duration, ) -> Result<bool, StorageError>

Self::gc_tick in batches of max_keys until the history sweep completes or budget has elapsed, so reclamation keeps up with the write rate instead of retiring a fixed number of keys per maintenance tick (SOAK-1: 512 keys per 5 s fell behind ~750 rewrites/s and history grew without bound). Returns whether the sweep completed.

Errors

See Self::gc_tick.

pub fn gc_watermark(&self) -> u64

Oldest supported logical commit index, inclusive. New historical views below this floor fail, even if an individual key still has older bytes.

pub fn expire_read_pins(&self, max_age_ms: u64) -> usize

Expire retained read leases older than max_age_ms (P06: reader age limits with safe cancellation-before-release). An abandoned reader that never drops its view cannot block history advancement forever; the GC worker calls this so the floor can move. Returns the count of leases released (CI entries whose remaining pin count reached zero).

Lock poisoning fences the store until reopen.

pub fn retention_summary(&self) -> (Option<u64>, usize)

Observability: the oldest active pin (inclusive CI floor) and how many distinct CIs are retained. Lets operators see long-reader retention and confirm it releases after handles close.

Lock poisoning fences the store until reopen.

pub fn sequencer_inflight_keys(&self) -> usize

Number of keys in the sequencer’s assigned-but-unpublished overlay. Observability for the single-writer in-flight window; returns 0 when the admission lock is poisoned rather than panicking a scrape.

pub fn gc(&self, watermark: u64) -> Result<usize, StorageError>

Reclaim versions superseded at or before the requested watermark, clamped by protected read views and the committed CI. Legacy unpinned readers must still coordinate their own retention. Returns reclaimed version count; canonical current data and command logs are unchanged.

Errors

Returns StorageError if the durable reclamation fails.

pub fn try_replay(&self, log: &[Vec<u8>]) -> Result<(), StorageError>

Rebuilds state by replaying the full serialized command log through the registered deterministic expander.

Errors

Returns StorageError::CorruptLog for malformed input or missing expansion support, and StorageError::Builder when deterministic expansion rejects an entry. No replayed state is published on decode or expansion failure.

Panics

Panics only if an internal lock is poisoned by a previous panic.

pub fn apply_replicated_batch( &self, batch: &CommitBatch, ) -> Result<u64, StorageError>

Apply a command batch already committed by OpenRaft. This bypasses admission-time planning but uses exactly the same deterministic expander and durable publication path as a local commit.

Errors

Returns StorageError if the publisher has failed, the batch has a terminal aborted outcome, or expansion/publication fails.

pub fn apply_replicated_batch_with_payload( &self, batch: &CommitBatch, payload: Option<&[u8]>, ) -> Result<u64, StorageError>

Apply a replicated batch and durably store its serialized payload with the outcome so idempotent retries on the leader reproduce the original caller response.

Errors

Returns StorageError if the publisher has failed, no expander is installed, the batch has a terminal aborted outcome, or publication fails.

Panics

Panics only if batch fails to serialize (never, for a well-formed CommitBatch). Lock poisoning fences the store until reopen.

Trait Implementations

impl Default for Store

fn default() -> Self

Returns the “default value” for a type.