Struct CrdtState 

pub struct CrdtState { /* private fields */ }

A CRDT state for a single tenant/namespace.

Implementations

impl CrdtState

pub fn upsert_versioned( &self, collection: &str, row_id: &str, fields: &[(&str, LoroValue)], ) -> Result<()>

Upsert a row with prior-version archiving for bitemporal collections. When a row with row_id already exists and carries a finite _ts_system, its field map is copied into the bitemporal history sibling before the new fields overwrite the live row. Non-bitemporal callers should stay on CrdtState::upsert — the archive has a non-trivial doc-size cost and is only meaningful when the collection participates in AS OF / audit queries.

pub fn read_row_as_of( &self, collection: &str, row_id: &str, asof_ms: i64, ) -> Option<LoroValue>

Read the row as it was at asof_ms (system-time). Scans the archive for the highest sys_ms <= asof_ms; falls back to the current row when its _ts_system <= asof_ms; returns None when no version existed at or before the requested time.

pub fn archive_version_count(&self, collection: &str, row_id: &str) -> usize

Count archived versions for a row (live row excluded). Primarily for tests and operational introspection.

pub fn purge_history_before( &self, collection: &str, cutoff_ms: i64, ) -> Result<usize>

Drop archived versions with sys_ms < cutoff_ms for the given collection. Returns the number of archive entries deleted. The live row is never touched — retention only reclaims history, so the current state of every logical row remains readable even when the entire archive is pruned.

impl CrdtState

pub fn new(peer_id: u64) -> Result<Self>

Create a new empty state for the given peer.

pub fn register_array_surrogate(&mut self, id: String)

Register an array-engine surrogate ID as a valid referent for FK checks.

Call this before running constraint validation whenever the referent collection is backed by the array engine rather than the document/graph engines. The ID must be the string form of the surrogate (e.g., the decimal representation of the Surrogate value or the composite key used by the array catalog).

pub fn upsert( &self, collection: &str, row_id: &str, fields: &[(&str, LoroValue)], ) -> Result<()>

Insert or update a row in a collection.

pub fn delete(&self, collection: &str, row_id: &str) -> Result<()>

Delete a row from a collection.

pub fn clear_collection(&self, collection: &str) -> Result<usize>

Delete all rows in a collection. Returns the number of rows deleted.

pub fn read_row(&self, collection: &str, row_id: &str) -> Option<LoroValue>

Read a single row’s fields as a LoroValue::Map.

Navigates via LoroMap::get() to avoid the expensive recursive get_deep_value() clone on the entire row container.

pub fn read_field( &self, collection: &str, row_id: &str, field: &str, ) -> Option<LoroValue>

Read a single field from a row without cloning the entire row.

This is the fast path for KV-style access where only one field is needed. Avoids allocating a full Map for single-field reads.

Shares the same doc.get_map(collection).get(row_id) lookup pattern as read_row, but returns a single field value instead of the whole row map — different return granularity, intentionally kept separate.

pub fn row_exists(&self, collection: &str, row_id: &str) -> bool

Check if a row exists in a collection.

Checks the Loro-backed document/graph collections first. If not found there, falls back to the registered array surrogate set so that BiTemporalFK and ForeignKey constraints can reference array-engine cells as valid referents without requiring a full cross-engine query.

pub fn collection_names(&self) -> Vec<String>

List all collection names (top-level map keys in the Loro doc).

pub fn row_ids(&self, collection: &str) -> Vec<String>

Get all row IDs in a collection.

pub fn field_value_exists( &self, collection: &str, field: &str, value: &LoroValue, ) -> bool

Check if a value exists for the given field across all rows in a collection. Used for UNIQUE constraint checking.

pub fn field_value_exists_live( &self, collection: &str, field: &str, value: &LoroValue, ) -> bool

Bitemporal variant of [field_value_exists]: only considers rows whose _ts_valid_until is open (absent or i64::MAX).

A UNIQUE collision between a superseded version and a new live row is not a violation — both may share the same value because they represent the same logical entity at different valid-times.

pub fn live_row_ids(&self, collection: &str) -> Vec<String>

Return row IDs currently “live” in a bitemporal collection (rows whose _ts_valid_until is open). For non-bitemporal collections every row is returned.

pub fn doc(&self) -> &LoroDoc

Get the underlying LoroDoc for advanced operations.

pub fn peer_id(&self) -> u64

Peer ID of this state.

impl CrdtState

pub fn oplog_version_vector(&self) -> VersionVector

Get the current oplog version vector.

pub fn read_at_version( &self, collection: &str, row_id: &str, version: &VersionVector, ) -> Result<Option<LoroValue>>

Read the document state at a historical version.

Uses fork_at to create a lightweight copy at the target version and reads the specified row. Returns None if the row didn’t exist.

Cost: O(oplog_size) for the fork — not for hot-path queries.

pub fn export_updates_since( &self, from_version: &VersionVector, ) -> Result<Vec<u8>>

Export the oplog delta from a version to the current state.

Returns the operations that transform from_version into current state. Used for DIFF rendering and delta sync.

pub fn compact_at_version(&mut self, version: &VersionVector) -> Result<()>

Compact history at a specific version (not just current frontiers).

Discards oplog entries before the target version. Current state and all versions after the target are preserved.

pub fn restore_to_version( &self, collection: &str, row_id: &str, version: &VersionVector, ) -> Result<Vec<u8>>

Restore a document to a historical version by creating a forward delta.

Reads the state at the target version, then generates a new mutation that sets the current state to match the historical state. History is preserved — this is a forward operation, not a rollback.

Returns the delta bytes to be applied through the normal write path.

impl CrdtState

pub fn export_snapshot(&self) -> Result<Vec<u8>>

Export the current state as bytes for sync.

pub fn import(&self, data: &[u8]) -> Result<()>

Import remote updates.

pub fn compact_history(&mut self) -> Result<()>

Compact the CRDT history by replacing the internal LoroDoc with a shallow snapshot.

A shallow snapshot contains the current state but discards the full operation history. This is the CRDT equivalent of WAL truncation after checkpoint.

After compaction:

• All current state is preserved (reads return same values).
• New deltas can still be applied and merged.
• Historical operations before the snapshot point are gone.
• Peers that sync after compaction receive a full snapshot instead of incremental deltas (acceptable for long-offline peers).

Call this periodically (e.g., every 30 minutes or when memory pressure exceeds threshold) to prevent unbounded history growth.

pub fn estimated_memory_bytes(&self) -> usize

Estimated memory usage of the CRDT state (bytes).

Includes operation history, current state, and internal caches. Use this to decide when to trigger compact_history().