Struct DeltaBuffer 

pub struct DeltaBuffer { /* private fields */ }

Buffer for storing deltas during snapshot sync.

Implements Invariant I6: Deltas received during state-based sync MUST be preserved and applied after sync completes.

When the buffer is full, the oldest delta is evicted (FIFO eviction policy) and the drops counter is incremented. Drops MUST be observable via metrics.

Deduplication

The buffer tracks seen delta IDs to prevent duplicate deltas from being buffered. This protects against replay attacks where an adversary might flood the buffer with duplicate deltas to cause eviction of legitimate deltas.

Implementations

impl DeltaBuffer

pub fn new(capacity: usize, sync_start_hlc: u64) -> Self

Create a new delta buffer with specified capacity.

Capacity Warning

If capacity is below MIN_RECOMMENDED_CAPACITY, callers should log a warning at startup. Zero capacity is valid but will drop ALL deltas.

pub fn is_capacity_below_recommended(&self) -> bool

Check if capacity is below recommended minimum.

Callers should log a warning at session start if this returns true.

pub fn push(&mut self, delta: BufferedDelta) -> PushResult

Add a delta to the buffer.

Returns a PushResult indicating what happened:

• Added: Delta was added successfully
• Duplicate: Delta ID was already in buffer (no action taken)
• Evicted(id): Delta was added but oldest delta was evicted
• DroppedZeroCapacity(id): Delta was dropped (zero capacity buffer)

Deduplication

If a delta with the same ID is already in the buffer, it is not added again and PushResult::Duplicate is returned. This prevents replay attacks.

Edge case: zero capacity

If capacity is 0, the incoming delta is immediately dropped (not added) and PushResult::DroppedZeroCapacity is returned with the dropped delta’s ID.

pub fn drain(&mut self) -> Vec<BufferedDelta>

Get all buffered deltas for replay, clearing the buffer.

Returns deltas in FIFO order (oldest first), preserving causality. Also clears the deduplication set.

pub fn contains(&self, id: &[u8; 32]) -> bool

Check if a delta ID is already in the buffer.

This is O(1) due to the internal HashSet tracking.

pub fn len(&self) -> usize

Number of buffered deltas.

pub fn is_empty(&self) -> bool

Check if buffer is empty.

pub fn sync_start_hlc(&self) -> u64

Get the sync start HLC.

pub fn drops(&self) -> u64

Get the number of deltas dropped due to buffer overflow.

This metric MUST be observable per Invariant I6 delivery contract.

pub fn capacity(&self) -> usize

Get the buffer capacity.

Trait Implementations

impl Debug for DeltaBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.