grafos_collections/

vec.rs

//! Growable arrays backed by leased fabric memory.
//!
//! This module provides two array types:
//!
//! - [`FabricVec<T>`] stores elements in fixed-size slots within a single
//!   memory lease. When the lease is full, [`grow()`](FabricVec::grow)
//!   acquires additional leases and chains them together. The
//!   [`push()`](FabricVec::push) method calls `grow()` automatically.
//!
//! - [`VarFabricVec<T>`] stores variable-size elements using an index+heap
//!   layout. The index region holds fixed-size `(offset, len)` entries that
//!   point into a heap region where the actual serialized data lives. This
//!   avoids wasting space when element sizes vary widely.
//!
//! # FabricVec memory layout
//!
//! ```text
//! Offset 0:  [header]  len: u64 (8 bytes) | capacity: u64 (8 bytes) | stride: u64 (8 bytes)
//! Offset 24: [data]    element 0 (stride bytes) | element 1 | ...
//! ```
//!
//! Each element slot is `stride` bytes wide, determined at construction time.
//! Within each slot, the first 4 bytes store the serialized element length
//! as a little-endian `u32`, followed by the postcard-serialized bytes.
//! Variable-size types must fit within `stride - 4` serialized bytes;
//! exceeding it returns [`FabricError::CapacityExceeded`].
//!
//! When a `FabricVec` grows, additional leases are acquired and stored in
//! an overflow chain. Elements in overflow regions are addressed by
//! computing which region contains the target index.
//!
//! # VarFabricVec memory layout
//!
//! ```text
//! Offset 0:  [header]       len: u64 (8) | index_cap: u64 (8) | heap_size: u64 (8) | heap_used: u64 (8)
//! Offset 32: [index region] entry 0 (12 bytes: offset u64 + len u32) | entry 1 | ...
//! After index: [heap region] variable-length serialized data packed contiguously
//! ```
//!
//! # Examples
//!
//! ```rust
//! use grafos_collections::vec::FabricVec;
//! use grafos_std::mem::MemBuilder;
//!
//! # grafos_std::host::reset_mock();
//! # grafos_std::host::mock_set_fbmu_arena_size(65536);
//! let lease = MemBuilder::new().min_bytes(4096).acquire()?;
//! let mut v: FabricVec<u32> = FabricVec::new(lease, 16)?;
//!
//! v.push(&10)?;
//! v.push(&20)?;
//! assert_eq!(v.get(0)?, 10);
//! assert_eq!(v.pop()?, Some(20));
//! # Ok::<(), grafos_std::FabricError>(())
//! ```

extern crate alloc;
use alloc::vec;
use alloc::vec::Vec;

use grafos_std::error::{FabricError, Result};
use grafos_std::mem::{MemBuilder, MemLease};

use serde::{de::DeserializeOwned, Serialize};

const HEADER_SIZE: u64 = 24; // len(8) + capacity(8) + stride(8)

/// A growable array stored in leased fabric memory.
///
/// Elements are serialized via postcard into fixed-size slots within the
/// arena. The collection owns the underlying [`MemLease`] and releases it
/// when dropped.
///
/// # Type parameters
///
/// `T` must implement `Serialize + DeserializeOwned`. The serialized form
/// of each element must fit within `stride - 4` bytes (4 bytes are used
/// for the length prefix).
///
/// # Example
///
/// ```rust
/// use grafos_collections::vec::FabricVec;
/// use grafos_std::mem::MemBuilder;
///
/// # grafos_std::host::reset_mock();
/// # grafos_std::host::mock_set_fbmu_arena_size(65536);
/// let mut v: FabricVec<u32> = FabricVec::with_capacity(100, 16)?;
/// v.push(&42)?;
/// v.push(&99)?;
///
/// for item in v.iter() {
///     println!("{}", item?);
/// }
/// # Ok::<(), grafos_std::FabricError>(())
/// ```
pub struct FabricVec<T> {
    lease: MemLease,
    len: u64,
    capacity: u64,
    stride: u64,
    overflow: Vec<OverflowRegion>,
    _marker: core::marker::PhantomData<T>,
}

/// An additional memory region chained after the primary lease is full.
struct OverflowRegion {
    lease: MemLease,
    capacity: u64,
}

impl<T: Serialize + DeserializeOwned> FabricVec<T> {
    /// Create a new `FabricVec` that takes ownership of the given lease.
    ///
    /// `stride` is the slot width in bytes. Each slot stores a 4-byte
    /// length prefix plus the postcard-serialized element, so the maximum
    /// serialized element size is `stride - 4`.
    ///
    /// Capacity is computed as `(arena_size - 24) / stride`.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if the arena is too small
    /// to hold even the 24-byte header.
    pub fn new(lease: MemLease, stride: usize) -> Result<Self> {
        let arena = lease.mem().arena_size()?;
        if arena < HEADER_SIZE {
            return Err(FabricError::CapacityExceeded);
        }
        let stride = stride as u64;
        let capacity = (arena - HEADER_SIZE) / stride;
        let v = FabricVec {
            lease,
            len: 0,
            capacity,
            stride,
            overflow: Vec::new(),
            _marker: core::marker::PhantomData,
        };
        v.write_header()?;
        Ok(v)
    }

    /// Create a new `FabricVec` by acquiring a lease sized for `cap` elements
    /// of `stride` bytes each.
    ///
    /// This is a convenience constructor that calls `MemBuilder::new().min_bytes(...).acquire()`
    /// and then `FabricVec::new()`.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if the host cannot provide
    /// an arena large enough for `cap * stride + 24` bytes.
    pub fn with_capacity(cap: usize, stride: usize) -> Result<Self> {
        let needed = HEADER_SIZE + (cap as u64) * (stride as u64);
        let lease = MemBuilder::new().min_bytes(needed).acquire()?;
        Self::new(lease, stride)
    }

    /// Push an element onto the end of the vector.
    ///
    /// If the vector is full, `grow()` is called to acquire a new memory
    /// lease and chain it. Returns [`FabricError::CapacityExceeded`] only
    /// if `grow()` fails (the host cannot allocate more memory).
    pub fn push(&mut self, item: &T) -> Result<()> {
        if self.len >= self.capacity {
            self.grow()?;
        }
        let bytes = postcard::to_allocvec(item).map_err(|_| FabricError::IoError(-1))?;
        if bytes.len() as u64 > self.stride {
            return Err(FabricError::CapacityExceeded);
        }
        let (mem, offset) = self.resolve_slot(self.len);
        let mut slot = vec![0u8; self.stride as usize];
        let len_bytes = (bytes.len() as u32).to_le_bytes();
        slot[..4].copy_from_slice(&len_bytes);
        slot[4..4 + bytes.len()].copy_from_slice(&bytes);
        mem.write(offset, &slot)?;
        self.len += 1;
        self.write_header()?;
        Ok(())
    }

    /// Acquire a new memory lease and chain it to this vector, increasing
    /// total capacity.
    ///
    /// The new region has the same stride and approximately the same
    /// capacity as the primary region.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if the host cannot
    /// allocate more memory.
    pub fn grow(&mut self) -> Result<()> {
        let primary_cap = (self.lease.mem().arena_size()? - HEADER_SIZE) / self.stride;
        let needed = HEADER_SIZE + primary_cap * self.stride;
        let new_lease = MemBuilder::new().min_bytes(needed).acquire()?;
        let arena = new_lease.mem().arena_size()?;
        let new_cap = (arena - HEADER_SIZE) / self.stride;
        self.capacity += new_cap;
        self.overflow.push(OverflowRegion {
            lease: new_lease,
            capacity: new_cap,
        });
        self.write_header()?;
        Ok(())
    }

    /// Remove and return the last element, or `None` if the vector is empty.
    pub fn pop(&mut self) -> Result<Option<T>> {
        if self.len == 0 {
            return Ok(None);
        }
        let item = self.get(self.len as usize - 1)?;
        self.len -= 1;
        self.write_header()?;
        Ok(Some(item))
    }

    /// Read the element at `index`.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if `index >= len`.
    pub fn get(&self, index: usize) -> Result<T> {
        if index as u64 >= self.len {
            return Err(FabricError::CapacityExceeded);
        }
        let (mem, offset) = self.resolve_slot(index as u64);
        let raw = mem.read(offset, self.stride as u32)?;
        let ser_len = u32::from_le_bytes([raw[0], raw[1], raw[2], raw[3]]) as usize;
        postcard::from_bytes(&raw[4..4 + ser_len]).map_err(|_| FabricError::IoError(-1))
    }

    /// Overwrite the element at `index`.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if `index >= len`.
    pub fn set(&mut self, index: usize, item: &T) -> Result<()> {
        if index as u64 >= self.len {
            return Err(FabricError::CapacityExceeded);
        }
        let bytes = postcard::to_allocvec(item).map_err(|_| FabricError::IoError(-1))?;
        if bytes.len() as u64 > self.stride {
            return Err(FabricError::CapacityExceeded);
        }
        let (mem, offset) = self.resolve_slot(index as u64);
        let mut slot = vec![0u8; self.stride as usize];
        let len_bytes = (bytes.len() as u32).to_le_bytes();
        slot[..4].copy_from_slice(&len_bytes);
        slot[4..4 + bytes.len()].copy_from_slice(&bytes);
        mem.write(offset, &slot)?;
        Ok(())
    }

    /// Returns the number of elements in the vector.
    pub fn len(&self) -> usize {
        self.len as usize
    }

    /// Returns `true` if the vector contains no elements.
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Returns the maximum number of elements the vector can hold.
    pub fn capacity(&self) -> usize {
        self.capacity as usize
    }

    /// Clear the vector, setting len to 0.
    pub fn clear(&mut self) -> Result<()> {
        self.len = 0;
        self.write_header()
    }

    /// Returns an iterator over the elements.
    pub fn iter(&self) -> FabricVecIter<'_, T> {
        FabricVecIter {
            vec: self,
            index: 0,
        }
    }

    /// Returns the lease ID of the primary memory lease for external
    /// renewal management (e.g. via [`grafos_leasekit::RenewalManager`]).
    pub fn lease_id(&self) -> u128 {
        self.lease.lease_id()
    }

    /// Returns the expiry time (unix seconds) of the primary memory lease
    /// for external renewal management.
    pub fn expires_at_unix_secs(&self) -> u64 {
        self.lease.expires_at_unix_secs()
    }

    /// Resolve an element index to the (FabricMem, byte-offset) pair for
    /// the slot, traversing into overflow regions when necessary.
    fn resolve_slot(&self, index: u64) -> (&grafos_std::mem::FabricMem, u64) {
        let primary_cap = self.primary_capacity();
        if index < primary_cap {
            return (self.lease.mem(), HEADER_SIZE + index * self.stride);
        }
        let mut remaining = index - primary_cap;
        for region in &self.overflow {
            if remaining < region.capacity {
                let offset = HEADER_SIZE + remaining * self.stride;
                return (region.lease.mem(), offset);
            }
            remaining -= region.capacity;
        }
        // Should never reach here if len/capacity invariants hold.
        // Return primary lease at offset 0 as a fallback -- the subsequent
        // read/write will likely return an error.
        (self.lease.mem(), 0)
    }

    /// Capacity of just the primary lease (excluding overflow).
    fn primary_capacity(&self) -> u64 {
        let arena = self.lease.mem().arena_size().unwrap_or(HEADER_SIZE);
        (arena - HEADER_SIZE) / self.stride
    }

    fn write_header(&self) -> Result<()> {
        let mut hdr = [0u8; HEADER_SIZE as usize];
        hdr[0..8].copy_from_slice(&self.len.to_le_bytes());
        hdr[8..16].copy_from_slice(&self.capacity.to_le_bytes());
        hdr[16..24].copy_from_slice(&self.stride.to_le_bytes());
        self.lease.mem().write(0, &hdr)
    }
}

/// Iterator over elements of a [`FabricVec`].
///
/// Each call to `next()` performs a remote read to fetch and deserialize
/// one element. There is no prefetching or batching.
///
/// Yields `Result<T>` -- a read or deserialization failure produces an
/// `Err` item rather than panicking.
pub struct FabricVecIter<'a, T> {
    vec: &'a FabricVec<T>,
    index: usize,
}

impl<'a, T: Serialize + DeserializeOwned> Iterator for FabricVecIter<'a, T> {
    type Item = Result<T>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index >= self.vec.len() {
            return None;
        }
        let result = self.vec.get(self.index);
        self.index += 1;
        Some(result)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.vec.len() - self.index;
        (remaining, Some(remaining))
    }
}

// ---------------------------------------------------------------------------
// VarFabricVec — variable-size element vector
// ---------------------------------------------------------------------------

const VAR_HEADER_SIZE: u64 = 32; // len(8) + index_cap(8) + heap_size(8) + heap_used(8)
const INDEX_ENTRY_SIZE: u64 = 12; // offset(8) + len(4)

/// A vector that stores variable-size elements in leased fabric memory.
///
/// Unlike [`FabricVec`] which uses fixed-stride slots, `VarFabricVec` uses
/// an index+heap layout. The index region holds fixed-size 12-byte entries
/// `(offset: u64, len: u32)` that point into a heap region where the actual
/// postcard-serialized data is packed contiguously. This avoids wasting
/// space when serialized element sizes vary widely (e.g. `String`,
/// `Vec<u8>`).
///
/// # Trade-offs
///
/// - Better space efficiency for variable-size types.
/// - Two remote reads per `get()` (index entry + heap data) instead of one.
/// - No in-place `set()` if the new element is larger than the old one
///   (the old heap space is not reclaimed; a compacting GC is not provided).
///
/// # Example
///
/// ```rust
/// use grafos_collections::vec::VarFabricVec;
/// use grafos_std::mem::MemBuilder;
///
/// # grafos_std::host::reset_mock();
/// # grafos_std::host::mock_set_fbmu_arena_size(65536);
/// let lease = MemBuilder::new().min_bytes(8192).acquire()?;
/// let mut v: VarFabricVec<String> = VarFabricVec::new(lease, 128)?;
///
/// v.push(&"hello".into())?;
/// v.push(&"world, this is a longer string".into())?;
/// assert_eq!(v.get(0)?, "hello".to_string());
/// assert_eq!(v.len(), 2);
/// # Ok::<(), grafos_std::FabricError>(())
/// ```
pub struct VarFabricVec<T> {
    lease: MemLease,
    len: u64,
    index_cap: u64,
    heap_start: u64,
    heap_size: u64,
    heap_used: u64,
    _marker: core::marker::PhantomData<T>,
}

impl<T: Serialize + DeserializeOwned> VarFabricVec<T> {
    /// Create a new `VarFabricVec` over the given lease.
    ///
    /// `max_elements` determines the number of index entries reserved.
    /// The remaining arena space after the header and index region is
    /// used as the heap for element data.
    ///
    /// # Errors
    ///
    /// Returns [`FabricError::CapacityExceeded`] if the arena is too small
    /// for the header, index region, and at least 1 byte of heap.
    pub fn new(lease: MemLease, max_elements: usize) -> Result<Self> {
        let arena = lease.mem().arena_size()?;
        let index_cap = max_elements as u64;
        let heap_start = VAR_HEADER_SIZE + index_cap * INDEX_ENTRY_SIZE;
        if arena <= heap_start {
            return Err(FabricError::CapacityExceeded);
        }
        let heap_size = arena - heap_start;
        let v = VarFabricVec {
            lease,
            len: 0,
            index_cap,
            heap_start,
            heap_size,
            heap_used: 0,
            _marker: core::marker::PhantomData,
        };
        v.write_header()?;
        Ok(v)
    }

    /// Create a new `VarFabricVec` by acquiring a lease.
    ///
    /// `max_elements` is the index capacity. `avg_element_bytes` is a hint
    /// for sizing the heap region. The actual arena requested is:
    /// `header + index + max_elements * avg_element_bytes`.
    pub fn with_capacity(max_elements: usize, avg_element_bytes: usize) -> Result<Self> {
        let needed = VAR_HEADER_SIZE
            + (max_elements as u64) * INDEX_ENTRY_SIZE
            + (max_elements as u64) * (avg_element_bytes as u64);
        let lease = MemBuilder::new().min_bytes(needed).acquire()?;
        Self::new(lease, max_elements)
    }

    /// Push an element onto the end of the vector.
    ///
    /// Serializes the element and appends it to the heap region.
    ///
    /// # Errors
    ///
    /// - [`FabricError::CapacityExceeded`] if the index region is full or
    ///   the heap cannot fit the serialized element.
    pub fn push(&mut self, item: &T) -> Result<()> {
        if self.len >= self.index_cap {
            return Err(FabricError::CapacityExceeded);
        }
        let bytes = postcard::to_allocvec(item).map_err(|_| FabricError::IoError(-1))?;
        if self.heap_used + bytes.len() as u64 > self.heap_size {
            return Err(FabricError::CapacityExceeded);
        }
        // Write data to heap
        let data_offset = self.heap_start + self.heap_used;
        self.lease.mem().write(data_offset, &bytes)?;
        // Write index entry
        let idx_offset = VAR_HEADER_SIZE + self.len * INDEX_ENTRY_SIZE;
        let mut entry = [0u8; INDEX_ENTRY_SIZE as usize];
        entry[0..8].copy_from_slice(&self.heap_used.to_le_bytes());
        entry[8..12].copy_from_slice(&(bytes.len() as u32).to_le_bytes());
        self.lease.mem().write(idx_offset, &entry)?;

        self.heap_used += bytes.len() as u64;
        self.len += 1;
        self.write_header()?;
        Ok(())
    }

    /// Remove and return the last element, or `None` if empty.
    ///
    /// The heap space used by the popped element is reclaimed only if it
    /// was the last item appended (heap_used is rewound).
    pub fn pop(&mut self) -> Result<Option<T>> {
        if self.len == 0 {
            return Ok(None);
        }
        let item = self.get(self.len as usize - 1)?;
        // Read the index entry to reclaim heap space
        let idx_offset = VAR_HEADER_SIZE + (self.len - 1) * INDEX_ENTRY_SIZE;
        let entry = self.lease.mem().read(idx_offset, INDEX_ENTRY_SIZE as u32)?;
        let heap_offset = u64::from_le_bytes([
            entry[0], entry[1], entry[2], entry[3], entry[4], entry[5], entry[6], entry[7],
        ]);
        let data_len = u32::from_le_bytes([entry[8], entry[9], entry[10], entry[11]]) as u64;
        // Reclaim if this was at the end of the heap
        if heap_offset + data_len == self.heap_used {
            self.heap_used = heap_offset;
        }
        self.len -= 1;
        self.write_header()?;
        Ok(Some(item))
    }

    /// Read the element at `index`.
    ///
    /// Performs two remote reads: one for the index entry and one for the
    /// heap data.
    pub fn get(&self, index: usize) -> Result<T> {
        if index as u64 >= self.len {
            return Err(FabricError::CapacityExceeded);
        }
        let idx_offset = VAR_HEADER_SIZE + (index as u64) * INDEX_ENTRY_SIZE;
        let entry = self.lease.mem().read(idx_offset, INDEX_ENTRY_SIZE as u32)?;
        let heap_offset = u64::from_le_bytes([
            entry[0], entry[1], entry[2], entry[3], entry[4], entry[5], entry[6], entry[7],
        ]);
        let data_len = u32::from_le_bytes([entry[8], entry[9], entry[10], entry[11]]);
        let data = self
            .lease
            .mem()
            .read(self.heap_start + heap_offset, data_len)?;
        postcard::from_bytes(&data).map_err(|_| FabricError::IoError(-1))
    }

    /// Returns the number of elements.
    pub fn len(&self) -> usize {
        self.len as usize
    }

    /// Returns `true` if the vector is empty.
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    /// Returns the maximum number of index entries.
    pub fn index_capacity(&self) -> usize {
        self.index_cap as usize
    }

    /// Returns the total heap space in bytes.
    pub fn heap_size(&self) -> u64 {
        self.heap_size
    }

    /// Returns the heap space used so far in bytes.
    pub fn heap_used(&self) -> u64 {
        self.heap_used
    }

    /// Clear the vector, resetting len and heap_used to 0.
    pub fn clear(&mut self) -> Result<()> {
        self.len = 0;
        self.heap_used = 0;
        self.write_header()
    }

    /// Returns the lease ID of the memory lease for external renewal
    /// management (e.g. via [`grafos_leasekit::RenewalManager`]).
    pub fn lease_id(&self) -> u128 {
        self.lease.lease_id()
    }

    /// Returns the expiry time (unix seconds) of the memory lease for
    /// external renewal management.
    pub fn expires_at_unix_secs(&self) -> u64 {
        self.lease.expires_at_unix_secs()
    }

    /// Returns an iterator over the elements.
    pub fn iter(&self) -> VarFabricVecIter<'_, T> {
        VarFabricVecIter {
            vec: self,
            index: 0,
        }
    }

    fn write_header(&self) -> Result<()> {
        let mut hdr = [0u8; VAR_HEADER_SIZE as usize];
        hdr[0..8].copy_from_slice(&self.len.to_le_bytes());
        hdr[8..16].copy_from_slice(&self.index_cap.to_le_bytes());
        hdr[16..24].copy_from_slice(&self.heap_size.to_le_bytes());
        hdr[24..32].copy_from_slice(&self.heap_used.to_le_bytes());
        self.lease.mem().write(0, &hdr)
    }
}

/// Iterator over elements of a [`VarFabricVec`].
pub struct VarFabricVecIter<'a, T> {
    vec: &'a VarFabricVec<T>,
    index: usize,
}

impl<'a, T: Serialize + DeserializeOwned> Iterator for VarFabricVecIter<'a, T> {
    type Item = Result<T>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.index >= self.vec.len() {
            return None;
        }
        let result = self.vec.get(self.index);
        self.index += 1;
        Some(result)
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.vec.len() - self.index;
        (remaining, Some(remaining))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use grafos_std::host;
    use serde::{Deserialize, Serialize};

    fn setup(arena_size: u64) -> MemLease {
        host::reset_mock();
        host::mock_set_fbmu_arena_size(arena_size);
        MemBuilder::new().acquire().expect("acquire")
    }

    #[test]
    fn push_pop_roundtrip() {
        let lease = setup(4096);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert!(v.is_empty());

        v.push(&10).expect("push 10");
        v.push(&20).expect("push 20");
        v.push(&30).expect("push 30");
        assert_eq!(v.len(), 3);

        assert_eq!(v.pop().expect("pop"), Some(30));
        assert_eq!(v.pop().expect("pop"), Some(20));
        assert_eq!(v.pop().expect("pop"), Some(10));
        assert_eq!(v.pop().expect("pop"), None);
        assert!(v.is_empty());
    }

    #[test]
    fn get_set() {
        let lease = setup(4096);
        let mut v: FabricVec<u64> = FabricVec::new(lease, 16).expect("new");

        v.push(&100).expect("push");
        v.push(&200).expect("push");
        v.push(&300).expect("push");

        assert_eq!(v.get(0).expect("get"), 100);
        assert_eq!(v.get(1).expect("get"), 200);
        assert_eq!(v.get(2).expect("get"), 300);

        v.set(1, &999).expect("set");
        assert_eq!(v.get(1).expect("get"), 999);
    }

    #[test]
    fn get_out_of_bounds() {
        let lease = setup(4096);
        let v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_eq!(v.get(0).unwrap_err(), FabricError::CapacityExceeded);
    }

    #[test]
    fn iter_elements() {
        let lease = setup(4096);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        for i in 0..5u32 {
            v.push(&i).expect("push");
        }
        let collected: alloc::vec::Vec<u32> = v.iter().map(|r| r.expect("iter")).collect();
        assert_eq!(collected, alloc::vec![0, 1, 2, 3, 4]);
    }

    #[test]
    fn vec_lease_accessors() {
        let lease = setup(4096);
        let v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_ne!(v.lease_id(), 0);
        assert!(v.expires_at_unix_secs() > 0);
    }

    #[test]
    fn clear_resets_len() {
        let lease = setup(4096);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        v.push(&1).expect("push");
        v.push(&2).expect("push");
        assert_eq!(v.len(), 2);
        v.clear().expect("clear");
        assert_eq!(v.len(), 0);
        assert!(v.is_empty());
    }

    #[test]
    fn capacity_exceeded_when_grow_fails() {
        // Arena = header(24) + 2 * stride(16) = 56 bytes
        let lease = setup(56);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_eq!(v.capacity(), 2);

        v.push(&1).expect("push 1");
        v.push(&2).expect("push 2");
        // Shrink mock arena so grow() cannot allocate
        host::mock_set_fbmu_arena_size(0);
        assert_eq!(v.push(&3).unwrap_err(), FabricError::CapacityExceeded);
    }

    #[test]
    fn with_capacity_creates_appropriately_sized_vec() {
        host::reset_mock();
        host::mock_set_fbmu_arena_size(65536);

        let v: FabricVec<u64> = FabricVec::with_capacity(100, 16).expect("with_capacity");
        assert!(v.capacity() >= 100);
    }

    #[derive(Debug, PartialEq, Serialize, Deserialize)]
    struct TestStruct {
        name: alloc::string::String,
        value: u64,
    }

    #[test]
    fn variable_size_elements() {
        let lease = setup(8192);
        let mut v: FabricVec<TestStruct> = FabricVec::new(lease, 64).expect("new");

        let a = TestStruct {
            name: alloc::string::String::from("alpha"),
            value: 42,
        };
        let b = TestStruct {
            name: alloc::string::String::from("beta"),
            value: 99,
        };

        v.push(&a).expect("push a");
        v.push(&b).expect("push b");

        assert_eq!(v.get(0).expect("get 0"), a);
        assert_eq!(v.get(1).expect("get 1"), b);
    }

    #[test]
    fn variable_size_elements_different_serialized_lengths() {
        // Verify that elements with very different serialized sizes coexist
        // correctly in the same FabricVec, as long as each fits in stride.
        let lease = setup(8192);
        let mut v: FabricVec<TestStruct> = FabricVec::new(lease, 128).expect("new");

        let short = TestStruct {
            name: alloc::string::String::from("x"),
            value: 1,
        };
        let long = TestStruct {
            name: alloc::string::String::from("a]relatively_long_name_for_testing_purposes"),
            value: u64::MAX,
        };
        let empty = TestStruct {
            name: alloc::string::String::new(),
            value: 0,
        };

        v.push(&short).expect("push short");
        v.push(&long).expect("push long");
        v.push(&empty).expect("push empty");

        assert_eq!(v.get(0).expect("get 0"), short);
        assert_eq!(v.get(1).expect("get 1"), long);
        assert_eq!(v.get(2).expect("get 2"), empty);

        // Overwrite a short element with a longer one at the same index
        v.set(0, &long).expect("set 0 to long");
        assert_eq!(v.get(0).expect("get 0 after set"), long);
    }

    #[test]
    fn variable_size_element_exceeds_stride_returns_error() {
        // stride=16, length prefix uses 4 bytes, so max serialized size is
        // stride (the check is bytes.len() > stride). A string whose postcard
        // serialization exceeds stride should be rejected.
        let lease = setup(4096);
        let mut v: FabricVec<alloc::string::String> = FabricVec::new(lease, 16).expect("new");

        // A 20-byte string will serialize to >16 bytes (1-byte varint length + 20 chars)
        let big = alloc::string::String::from("12345678901234567890");
        assert_eq!(v.push(&big).unwrap_err(), FabricError::CapacityExceeded);
        assert!(v.is_empty());
    }

    #[test]
    fn capacity_boundary_fill_then_pop_then_refill() {
        // Arena exactly fits header(24) + 4 * stride(16) = 88 bytes → capacity 4.
        // Fill completely, pop all, then refill to verify reuse.
        let lease = setup(88);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_eq!(v.capacity(), 4);

        // Fill to capacity
        for i in 0..4u32 {
            v.push(&(i * 10)).expect("push");
        }
        assert_eq!(v.len(), 4);
        // Prevent grow so push fails
        host::mock_set_fbmu_arena_size(0);
        assert_eq!(v.push(&99).unwrap_err(), FabricError::CapacityExceeded);
        // Restore arena for later allocations
        host::mock_set_fbmu_arena_size(88);

        // Drain fully
        for i in (0..4u32).rev() {
            assert_eq!(v.pop().expect("pop"), Some(i * 10));
        }
        assert!(v.is_empty());

        // Refill with different values (len was reset, so primary region is reused)
        for i in 100..104u32 {
            v.push(&i).expect("re-push");
        }
        assert_eq!(v.len(), 4);
        for (idx, expected) in (100..104u32).enumerate() {
            assert_eq!(v.get(idx).expect("get"), expected);
        }
    }

    #[test]
    fn arena_too_small_for_header() {
        // Arena smaller than HEADER_SIZE (24 bytes) should fail construction.
        let lease = setup(16);
        let result: core::result::Result<FabricVec<u32>, _> = FabricVec::new(lease, 16);
        match result {
            Err(FabricError::CapacityExceeded) => {}
            other => panic!("expected CapacityExceeded, got {:?}", other.err()),
        }
    }

    #[test]
    fn set_out_of_bounds() {
        let lease = setup(4096);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        v.push(&42).expect("push");
        // index 1 is out of bounds (len == 1)
        assert_eq!(v.set(1, &99).unwrap_err(), FabricError::CapacityExceeded);
        // index 0 is still valid
        assert_eq!(v.get(0).expect("get"), 42);
    }

    #[test]
    fn iter_size_hint() {
        let lease = setup(4096);
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        for i in 0..5u32 {
            v.push(&i).expect("push");
        }
        let mut iter = v.iter();
        assert_eq!(iter.size_hint(), (5, Some(5)));
        iter.next();
        assert_eq!(iter.size_hint(), (4, Some(4)));
    }

    // --- FabricVec capacity growth tests ---

    #[test]
    fn grow_chains_new_lease() {
        // Create a tiny arena that can hold 2 elements, then grow.
        host::reset_mock();
        host::mock_set_fbmu_arena_size(56); // header(24) + 2*stride(16) = 56
        let lease = MemBuilder::new().acquire().expect("acquire");
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_eq!(v.capacity(), 2);

        v.push(&10).expect("push 10");
        v.push(&20).expect("push 20");

        // Now bump the mock arena so the next alloc succeeds
        host::mock_set_fbmu_arena_size(56);
        v.push(&30).expect("push 30 (triggers grow)");
        assert!(v.capacity() >= 3);
        assert_eq!(v.len(), 3);

        assert_eq!(v.get(0).expect("get 0"), 10);
        assert_eq!(v.get(1).expect("get 1"), 20);
        assert_eq!(v.get(2).expect("get 2"), 30);
    }

    #[test]
    fn grow_multiple_overflow_regions() {
        host::reset_mock();
        // Each region holds 2 elements (header=24 + 2*16=56)
        host::mock_set_fbmu_arena_size(56);
        let lease = MemBuilder::new().acquire().expect("acquire");
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");
        assert_eq!(v.capacity(), 2);

        // Push 6 elements across 3 regions
        for i in 0..6u32 {
            v.push(&(i * 10)).expect("push");
        }
        assert_eq!(v.len(), 6);
        assert!(v.capacity() >= 6);

        // Verify all elements readable
        for i in 0..6u32 {
            assert_eq!(v.get(i as usize).expect("get"), i * 10);
        }

        // Pop all in reverse
        for i in (0..6u32).rev() {
            assert_eq!(v.pop().expect("pop"), Some(i * 10));
        }
        assert!(v.is_empty());
    }

    #[test]
    fn grow_iter_spans_regions() {
        host::reset_mock();
        host::mock_set_fbmu_arena_size(56); // 2 elements per region
        let lease = MemBuilder::new().acquire().expect("acquire");
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");

        for i in 0..5u32 {
            v.push(&i).expect("push");
        }
        let collected: alloc::vec::Vec<u32> = v.iter().map(|r| r.expect("iter")).collect();
        assert_eq!(collected, alloc::vec![0, 1, 2, 3, 4]);
    }

    #[test]
    fn grow_set_in_overflow_region() {
        host::reset_mock();
        host::mock_set_fbmu_arena_size(56); // 2 per region
        let lease = MemBuilder::new().acquire().expect("acquire");
        let mut v: FabricVec<u32> = FabricVec::new(lease, 16).expect("new");

        v.push(&1).expect("push");
        v.push(&2).expect("push");
        v.push(&3).expect("push"); // in overflow region

        v.set(2, &99).expect("set in overflow");
        assert_eq!(v.get(2).expect("get"), 99);
    }

    // --- FabricVec with String and Vec<u8> elements ---

    #[test]
    fn fabric_vec_string_elements() {
        let lease = setup(8192);
        let mut v: FabricVec<alloc::string::String> = FabricVec::new(lease, 64).expect("new");

        let strings = alloc::vec![
            alloc::string::String::from("hello"),
            alloc::string::String::from("world"),
            alloc::string::String::from(""),
            alloc::string::String::from("a longer string with more characters"),
        ];
        for s in &strings {
            v.push(s).expect("push");
        }
        for (i, s) in strings.iter().enumerate() {
            assert_eq!(&v.get(i).expect("get"), s);
        }
    }

    #[test]
    fn fabric_vec_vec_u8_elements() {
        let lease = setup(8192);
        let mut v: FabricVec<alloc::vec::Vec<u8>> = FabricVec::new(lease, 64).expect("new");

        let items: alloc::vec::Vec<alloc::vec::Vec<u8>> =
            alloc::vec![alloc::vec![1, 2, 3], alloc::vec![], alloc::vec![255; 50],];
        for item in &items {
            v.push(item).expect("push");
        }
        for (i, item) in items.iter().enumerate() {
            assert_eq!(&v.get(i).expect("get"), item);
        }
    }

    // --- VarFabricVec tests ---

    #[test]
    fn var_vec_push_pop_roundtrip() {
        let lease = setup(8192);
        let mut v: VarFabricVec<alloc::string::String> =
            VarFabricVec::new(lease, 100).expect("new");

        v.push(&alloc::string::String::from("short")).expect("push");
        v.push(&alloc::string::String::from(
            "a much longer string that takes more heap space",
        ))
        .expect("push");
        v.push(&alloc::string::String::from("")).expect("push");
        assert_eq!(v.len(), 3);

        assert_eq!(
            v.get(0).expect("get 0"),
            alloc::string::String::from("short")
        );
        assert_eq!(
            v.get(1).expect("get 1"),
            alloc::string::String::from("a much longer string that takes more heap space")
        );
        assert_eq!(v.get(2).expect("get 2"), alloc::string::String::from(""));

        assert_eq!(v.pop().expect("pop"), Some(alloc::string::String::from("")));
        assert_eq!(v.len(), 2);
    }

    #[test]
    fn var_vec_mixed_sizes_efficient() {
        let lease = setup(8192);
        let mut v: VarFabricVec<alloc::vec::Vec<u8>> = VarFabricVec::new(lease, 100).expect("new");

        // Push items of very different sizes
        v.push(&alloc::vec![42u8]).expect("push tiny");
        v.push(&alloc::vec![0u8; 100]).expect("push medium");
        v.push(&alloc::vec![255u8; 500]).expect("push large");

        assert_eq!(v.len(), 3);
        assert_eq!(v.get(0).expect("get 0"), alloc::vec![42u8]);
        assert_eq!(v.get(1).expect("get 1"), alloc::vec![0u8; 100]);
        assert_eq!(v.get(2).expect("get 2"), alloc::vec![255u8; 500]);

        // Heap usage should be roughly the sum of serialized sizes, not
        // 3 * max_stride.
        assert!(v.heap_used() < 1000);
    }

    #[test]
    fn var_vec_with_capacity() {
        host::reset_mock();
        host::mock_set_fbmu_arena_size(65536);
        let v: VarFabricVec<alloc::string::String> =
            VarFabricVec::with_capacity(50, 32).expect("with_capacity");
        assert_eq!(v.index_capacity(), 50);
        assert!(v.heap_size() > 0);
    }

    #[test]
    fn var_vec_clear() {
        let lease = setup(8192);
        let mut v: VarFabricVec<u32> = VarFabricVec::new(lease, 100).expect("new");
        v.push(&1).expect("push");
        v.push(&2).expect("push");
        v.clear().expect("clear");
        assert!(v.is_empty());
        assert_eq!(v.heap_used(), 0);
    }

    #[test]
    fn var_vec_iter() {
        let lease = setup(8192);
        let mut v: VarFabricVec<u32> = VarFabricVec::new(lease, 100).expect("new");
        for i in 0..5u32 {
            v.push(&(i * 10)).expect("push");
        }
        let collected: alloc::vec::Vec<u32> = v.iter().map(|r| r.expect("iter")).collect();
        assert_eq!(collected, alloc::vec![0, 10, 20, 30, 40]);
    }

    #[test]
    fn var_vec_heap_full_returns_error() {
        // Create a small arena where the heap fills up before the index.
        // header(32) + 10 * index_entry(12) = 152 bytes for index
        // With a 256-byte arena, heap = 256 - 152 = 104 bytes
        let lease = setup(256);
        let mut v: VarFabricVec<alloc::vec::Vec<u8>> = VarFabricVec::new(lease, 10).expect("new");
        // Each Vec<u8> of 60 bytes serializes to ~62 bytes (varint len prefix + data)
        v.push(&alloc::vec![0u8; 60]).expect("push 1");
        // Second push should fail — not enough heap
        let result = v.push(&alloc::vec![0u8; 60]);
        assert_eq!(result.unwrap_err(), FabricError::CapacityExceeded);
        assert_eq!(v.len(), 1);
    }

    #[test]
    fn var_vec_index_full_returns_error() {
        // header(32) + 2 * index_entry(12) = 56, plus heap. With a small
        // index_cap=2, the third push should fail.
        let lease = setup(4096);
        let mut v: VarFabricVec<u32> = VarFabricVec::new(lease, 2).expect("new");
        v.push(&1).expect("push 1");
        v.push(&2).expect("push 2");
        assert_eq!(v.push(&3).unwrap_err(), FabricError::CapacityExceeded);
    }

    #[test]
    fn var_vec_pop_reclaims_heap() {
        let lease = setup(8192);
        let mut v: VarFabricVec<alloc::string::String> =
            VarFabricVec::new(lease, 100).expect("new");
        v.push(&alloc::string::String::from("first")).expect("push");
        let after_first = v.heap_used();
        v.push(&alloc::string::String::from("second"))
            .expect("push");
        let after_second = v.heap_used();
        assert!(after_second > after_first);

        // Pop reclaims the last element's heap
        v.pop().expect("pop");
        assert_eq!(v.heap_used(), after_first);
    }
}