Enum CsrVariant 

pub enum CsrVariant {
    Multiple(Box<MutableCsr>),
    Single(SingleMutableCsr),
    Pure(Box<PureTopologyCsr>),
    Bundled(Box<BundledCsr>),
    Frozen(Box<ImmutableCsr>),
    None {
        vertex_capacity: usize,
    },
}

Polymorphic CSR wrapper supporting multiple implementation strategies.

Combines mutable CSR implementations into a single enum for runtime selection without generic monomorphization.

The enum dispatch via CsrVariant keeps one implementation per trait method; callers use the trait interface so behavior stays in one place.

Cross-layer traversal contract: row positions (EdgePosition chunk/slot pairs, primary-block offsets, overflow indices) are variant-local and never cross a layer boundary. Every handoff between layers (read to write, scan to point lookup, live table to migration) re-resolves the target through the edge-id key first; a position obtained from one variant is never interpreted by another.

Row-view and ordering contract

All variants promise one shared row-view semantic: a row walk yields the physically stored entries of one vertex, each exactly once, as assembled Nbr records. Gap sentinels are excluded by every walk; tombstones are included so reclaim and audit paths observe them. Visibility is decided by the version authority above, never by these walks. Three access shapes serve it with unified naming: the borrowed Self::visit_physical walk (no allocation, preferred for inline forms and hot scans), the zero-alloc Self::fill_physical_into caller-buffer fill (preferred for batch scans), and the allocating physical_edges_of accessor (test and offline use only). No new traversal dialect may be added per variant; new needs go through these three.

Ordering is promised per form, never globally: mutable, single, pure and bundled rows are insertion-ordered and promise no order; frozen rows are packed sorted by (endpoint, rank, edge_id) and promise that order plus key-interval bisection. Freeze, compaction, compression and snapshot rebuilds may change the order; the query layer must never depend on an unpromised order. Plan selection uses should_use_bisection, combining the per-form promise with the memory-only sorted observation that is rebuilt on load and never cached across restarts.

Variants

Multiple(Box<MutableCsr>)

Multi-edge mutable CSR: each vertex can have multiple outgoing edges

Single(SingleMutableCsr)

Single-edge mutable CSR: each vertex has at most one outgoing edge

Pure(Box<PureTopologyCsr>)

Pure topology CSR: 12 bytes/edge, no rank, no timestamps

Bundled(Box<BundledCsr>)

Bundled CSR: 20 bytes/edge, inline single scalar value column

Frozen(Box<ImmutableCsr>)

Frozen packed CSR: read-only until explicitly unfrozen

None

No-edge placeholder: vertices exist but have no outgoing edges

Fields

vertex_capacity: usize

Implementations

impl CsrVariant

pub fn from_strategy_with_overflow( strategy: EdgeStrategy, vertex_capacity: usize, edge_capacity: usize, overflow_chunk_edges: usize, ) -> Result<CsrVariant, StorageError>

pub fn clear(&mut self)

Clear all edges.

pub fn set_tombstone_reuse_cutoff(&mut self, cutoff: u64)

Refresh the hot-path tombstone reuse cutoff. Only the multi-edge store reuses primary tombstones; single-slot rows overwrite in place already and hold no overflow, so other variants ignore the hint.

Freshness follows the single contract on MutableCsr::set_tombstone_reuse_cutoff: only watermark-derived bounds refresh, the sentinel disables, and a stale value only narrows reuse.

Non-multi-edge variants ignore the hint; the ignored call is observed at debug level so silent drops stay diagnosable.

pub fn refresh_tombstone_reuse_cutoff(&mut self, fresh: u64)

Fresh watermark refresh allowing widening. Only call with a freshly captured global watermark bound.

pub fn clear_tombstone_reuse_cutoff(&mut self)

Drop the reuse hint back to the disabled sentinel on every group.

Stale path of the same contract: no fresh watermark means no reuse.

pub fn tombstone_reuse_cutoff(&self) -> u64

Current reuse cutoff for observability and tests. Non-multi-edge variants never reuse, so they report the disabled sentinel.

pub fn variant_name(&self) -> &'static str

Stable variant name for observability (logs and diagnostics).

pub fn supports_timestamp_reclaim(&self) -> bool

Whether whole-table timestamp reclaim applies to this variant.

Only forms carrying timestamps reclaim here. Pure and bundled rows hold no timestamps so their holes compact through the per-row entry instead. Production frozen reclaim uses the batched rows entry instead of one call per row.

pub fn has_reserved_capacity(&self) -> bool

Whether this variant holds reserved row capacity reported as fragmentation.

Covers the multi-edge store plus the pure-topology and bundled forms sharing its primary-plus-overflow layout. Single slots carry no reserved gaps beyond their tombstone, frozen rows are packed without gaps, and the placeholder holds no edges.

pub fn fragmentation_ratio(&self) -> f32

Get fragmentation ratio for diagnostics

Covers every variant holding reserved row capacity: the multi-edge store plus the pure-topology and bundled forms sharing its primary-plus-overflow layout. Single-slot, frozen and empty forms report zero: single slots carry no reserved gaps beyond their tombstone, frozen rows are packed without gaps, and the placeholder holds no edges.

pub fn wasted_bytes_estimate(&self) -> usize

Estimate wasted bytes due to fragmentation.

Same coverage as the ratio above; other variants report zero.

pub fn fragmentation_stats(&self) -> Option<FragmentationStats>

Get fragmentation statistics for this CSR variant.

Returns Some(stats) for variants holding reserved row capacity, None for the remaining forms.

pub fn bytes_per_edge(&self) -> usize

Average bytes per edge based on actual memory usage.

Computed as used_memory_size() / edge_count() with no fallback. Empty tables report zero; a degenerate zero measurement on a non-empty table reports zero with a debug line. Callers handle zero explicitly instead of relying on a structural estimate.

pub fn is_writable(&self) -> bool

Whether this variant accepts topology writes without unfreezing.

Single source of truth for the writable set. Read-only and placeholder forms report false here and refuse result-returning writes with an error; counting deletes on those forms report zero at their own entries.

pub fn is_read_only(&self) -> bool

Whether this variant is a read-only packed view.

Frozen groups need an explicit unfreeze first. Table write paths check the group frozen state before reaching the row so counting deletes never read as a plain miss.

pub fn is_empty_placeholder(&self) -> bool

Whether this variant is the empty placeholder.

pub fn supports_positions(&self) -> bool

Whether positional row addressing is supported.

Positions are variant-local. Forms without positional addressing refuse positional writes instead of falling back to an id scan.

pub fn supports_vertex_compact(&self) -> bool

Whether per-row reclaim with reporting is supported.

Per-row defragmentation support: writable forms compact their own holes in place. Frozen single-row reclaim stays rejected and uses the batched frozen entry. Whole-table timestamp reclaim is a separate entry with its own exemptions for forms carrying no timestamps.

pub fn promises_key_order(&self) -> bool

Whether rows promise key order and may use bisection.

Only single-slot and frozen rows promise order. Other forms expose a memory-only observation through row sorted state that must never be cached across restarts.

pub fn should_use_bisection(&self, src_vid: u32) -> bool

Whether a range scan should bisect this row.

Central plan selection combining the order promise with the live sorted observation. Planning state stays memory-only and is rebuilt on load.

impl CsrVariant

pub fn compact_with_ts_reporting( &mut self, cutoff: u64, reserve_ratio: f32, on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Compact with per-edge removal reporting.

Whole-table timestamp reclaim: the capability query owns the exemption list, the match below only serves the supported forms. Pure and bundled rows hold no timestamps so they report zero; their holes still compact through the per-row entry. Production frozen reclaim uses the batched rows entry below instead of one call per row.

pub fn compact_frozen_rows_batched( &mut self, vids: &[u32], cutoff: u64, on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Reclaim a listed row set of a frozen group in one linear pass.

Production replacement for repeated per-row frozen compactions: one table-proportional pass instead of one trailing memmove per row. Only the frozen variant compacts; every other variant reports zero so callers keep their existing per-row path for mutable groups.

pub fn sort_row(&mut self, src_vid: u32) -> bool

Sort one primary row into key order on the maintenance path.

Same invalidation as the underlying stores: positions go stale and the caller relocates through the edge-id key. Frozen, single-slot and empty forms are already ordered and report false.

impl CsrVariant

pub fn dump_into_with_scratch( &self, out: &mut Vec<u8>, scratch: &mut CsrDumpScratch, )

Borrow-based dump reusing caller-owned column buffers.

Same bytes as dump_into through the base trait. A checkpoint over many groups pays one allocation per column instead of one per group.

impl CsrVariant

pub fn iter_edges_of(&self, src_vid: u32, ts: u64) -> Option<CsrRowIter<'_>>

Iterate edges of a vertex without allocating, for every strategy.

Test-only row-stamp filtered iterator; production scans go through the version authority. Missing groups and the None strategy yield no iterator. Bundled rows yield topology only: pair each item with the value accessors instead of reading values from this walk.

pub fn iter_all(&self) -> CsrIterator<'_>

Iterate over all physically present entries, including tombstoned ones.

Used when rebuilding the CSR (e.g. vertex ID remapping) so entries marked as deleted survive the rebuild. Pure and bundled holes carry the unassignable sentinel instead of an edge, so they are skipped: no rebuild may resurrect a hole as a live edge. Bundled values are not yielded here; migration paths resolve them through the paired value entry.

pub fn visit_physical<F>(&self, src_vid: u32, f: F)

where F: FnMut(Nbr) -> bool,

Visit every physically stored entry of one vertex without allocating.

Bundled rows visit topology only; use visit_physical_with_values when the inline value is needed.

pub fn visit_hot<F>(&self, src_vid: u32, f: F)

where F: FnMut(HotNbr) -> bool,

Visit every physically stored hot half of one vertex without allocating and without touching the stamp lines.

Hot-only counterpart of Self::visit_physical for traversals that resolve visibility through the version authority by edge_id.

pub fn fill_physical_into(&self, src_vid: u32, out: &mut Vec<Nbr>)

Fill a caller buffer with every physically stored entry of one vertex.

Same content as the allocating trait accessor, without the per-vertex allocation. Batch scans reuse one buffer across vertices. Behavior is uniform across variants: the buffer is cleared first, then the row is appended in the variant’s promised order (insertion order for mutable forms, sorted order for frozen forms; see the enum-level contract). Bundled rows fill topology only; pair with the value accessors.

pub fn is_row_sorted(&self, src_vid: u32) -> bool

Whether the live entries of one row arrive in key order.

Only frozen and single-slot rows promise order and may use bisection. All other forms report an observation that callers must not cache across restarts: the flag is memory-only, rebuilt on load, and query planning falls back to a linear walk unless the promise holds for the row’s current variant.

pub fn visit_threshold<F>( &self, src_vid: u32, lower: Option<(u32, i64)>, upper: Option<(u32, i64)>, f: F, )

where F: FnMut(Nbr) -> bool,

Visit live entries whose (endpoint, rank) key falls in the inclusive [lower, upper] range. Pure and bundled rows carry no rank, so the rank halves of the bounds are explicitly ignored there: callers pass endpoint intervals, and reusing one binary interval across forms scans the wider endpoint range on these forms by contract rather than by silent widening.

Bisection planning stays with Self::should_use_bisection: promised forms bisect whole rows, other forms bisect only a sorted primary prefix through their memory-only flag and scan the rest linearly. This entry only forwards; it never re-decides the plan.

pub fn fill_threshold_into( &self, src_vid: u32, lower: Option<(u32, i64)>, upper: Option<(u32, i64)>, out: &mut Vec<Nbr>, )

Fill a caller buffer with the same range content as visit_threshold.

Same explicit rank-half rule as visit_threshold on pure and bundled rows.

pub fn visit_threshold_endpoint_only<F>( &self, src_vid: u32, lower: Option<u32>, upper: Option<u32>, f: F, )

where F: FnMut(Nbr) -> bool,

Visit entries whose endpoint falls in the inclusive endpoint range.

Endpoint-only counterpart of visit_threshold for callers sharing one interval across forms. Pure and bundled rows ignore rank halves by contract; other forms widen the rank halves to the full range so the same endpoint interval scans the same endpoints everywhere.

pub fn fill_threshold_endpoint_only_into( &self, src_vid: u32, lower: Option<u32>, upper: Option<u32>, out: &mut Vec<Nbr>, )

Fill a caller buffer with the same endpoint-range content.

impl CsrVariant

pub fn is_bundled(&self) -> bool

Whether this group stores its single scalar inline.

pub fn insert_edge_with_value( &mut self, src_vid: u32, dst: VertexId, edge_id: EdgeId, value: Option<u64>, ) -> Result<(), StorageError>

Insert one edge carrying its inline value.

Only the bundled form accepts a value; every other form rejects the call instead of silently dropping the property.

pub fn bundled_value_by_edge_id( &self, src_vid: u32, edge_id: EdgeId, ) -> Option<(u64, bool)>

Read one edge’s inline value within its source row.

Paired value half of a bundled topology walk: resolve the edge id from the topology walk first, then read its value here. Frozen groups packed from a valued bundled group serve their carried values; other forms and unvalued packs report no value.

pub fn bundled_set_value_by_edge_id( &mut self, src_vid: u32, edge_id: EdgeId, value: Option<u64>, ) -> bool

Overwrite one edge’s inline value within its source row.

pub fn bundled_value_by_endpoint( &self, src_vid: u32, endpoint: u32, ) -> Option<(u64, bool)>

Read the inline value of the live edge for one endpoint.

pub fn bundled_set_value_by_endpoint( &mut self, src_vid: u32, endpoint: u32, value: Option<u64>, ) -> bool

Overwrite the inline value of the live edge for one endpoint.

pub fn bundled_revert_with_value( &mut self, src_vid: u32, position: EdgePosition, expected: EdgeId, ts: u64, value: Option<u64>, ) -> bool

Revert a deletion restoring the caller’s value alongside the topology.

pub fn visit_physical_with_values<F>(&self, src_vid: u32, f: F)

where F: FnMut(Nbr, Option<u64>) -> bool,

Visit every physically stored entry of one vertex with its inline value (None for NULL slots). Non-bundled forms visit with None.

Paired topology-plus-value walk for bundled rows: this is the only bundled traversal yielding values. Topology-only walks (visit_physical, fill_physical_into, row iterators) never yield values and must not be paired ad hoc elsewhere. Frozen groups walk their carried value columns the same way.

pub fn bundled_has_valid_values(&self) -> bool

Whether any slot holds a valid inline value.

pub fn fill_physical_with_values_into( &self, src_vid: u32, out: &mut Vec<(Nbr, Option<u64>)>, )

Fill a caller buffer with paired topology plus inline values.

Batched counterpart of the paired walk above for scans reusing one buffer across vertices. Non-bundled forms fill with None values.

Trait Implementations

impl Clone for CsrVariant

fn clone(&self) -> CsrVariant

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CsrBase for CsrVariant

fn vertex_capacity(&self) -> usize

Concurrency contract: row stores carry no internal locks. Concurrent reads are safe while no writer holds exclusive access, but any concurrent mutation requires caller-side mutual exclusion. The Send + Sync bounds express single-writer transfer across threads, not lock-free concurrent writes. Multi-core scaling comes from shard-level parallelism over NodeGroup shards above this trait; the CSR lock model itself stays single-writer with no row locks.

fn edge_count(&self) -> u64

fn dump(&self) -> Vec<u8>

fn dump_into(&self, out: &mut Vec<u8>)

Append the same bytes as dump into out without an intermediate owned buffer, so checkpoint writes borrow the live topology instead of cloning it for serialization.

fn load(&mut self, data: &[u8]) -> Result<(), StorageError>

impl Debug for CsrVariant

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

Formats the value using the given formatter.

impl MutableCsrTrait for CsrVariant

fn insert_edge( &mut self, src_vid: u32, dst: VertexId, edge_id: EdgeId, ts: u64, ) -> Result<(), StorageError>

Insert an edge.

fn delete_edge( &mut self, src_vid: u32, edge_id: EdgeId, ts: u64, ) -> Result<bool, StorageError>

Delete an edge by edge_id.

fn delete_edge_by_dst(&mut self, src_vid: u32, dst: VertexId, ts: u64) -> usize

Delete all edges matching (src, dst) with full-match semantics.

fn delete_edge_by_dst_reporting( &mut self, src_vid: u32, dst: VertexId, ts: u64, on_deleted: &mut dyn FnMut(EdgeId), ) -> usize

Delete all edges matching (src, dst), reporting every stamped id.

fn delete_edge_by_dst_reporting_positioned( &mut self, src_vid: u32, dst: VertexId, ts: u64, on_deleted: &mut dyn FnMut(EdgeId, Option<EdgePosition>), ) -> usize

Delete all edges matching (src, dst), reporting each stamped id with its row position.

fn locate_edge( &self, src_vid: u32, edge_id: EdgeId, ) -> Option<(EdgePosition, Nbr)>

Locate one stored edge, returning its row position and copy.

fn delete_edge_at_position( &mut self, src_vid: u32, position: EdgePosition, expected: EdgeId, ts: u64, ) -> Result<bool, StorageError>

Delete the edge at position when it still holds expected id.

fn revert_delete_at_position( &mut self, src_vid: u32, position: EdgePosition, expected: EdgeId, ts: u64, ) -> bool

Revert the deletion at position when it still holds expected id.

fn delete_edge_by_offset( &mut self, src_vid: u32, offset: i32, ts: u64, ) -> Result<bool, StorageError>

Delete an edge by its offset position in the primary block.

fn revert_delete_by_offset( &mut self, src_vid: u32, offset: i32, ts: u64, ) -> bool

Revert a deleted edge by its offset position.

fn nbr_at_offset(&self, src_vid: u32, offset: i32) -> Option<Nbr>

Read-only view of one primary slot for offset identity checks.

fn get_edge_physical(&self, src_vid: u32, dst: VertexId) -> Option<Nbr>

Locate the first live edge by endpoint without consulting snapshots.

fn physical_edges_of(&self, src_vid: u32) -> Vec<Nbr>

Every physically stored entry of one vertex without timestamp filtering.

fn fill_physical_into(&self, src_vid: u32, out: &mut Vec<Nbr>)

Fill a caller buffer with every physically stored entry of one vertex.

fn has_physical_entries(&self, vid: u32) -> bool

Whether one vertex holds any physically stored entry.

fn primary_contains(&self, src_vid: u32, edge_id: EdgeId) -> bool

Whether the primary row of one vertex holds edge_id.

fn rollback_insert(&mut self, src_vid: u32, edge_id: EdgeId) -> bool

Erase one just-inserted edge for insert rollback (no tombstone trace).

fn revert_delete_by_edge_id( &mut self, src_vid: u32, edge_id: EdgeId, ts: u64, ) -> bool

Revert a deletion by edge id if it happened at or before ts.

fn get_edge(&self, src_vid: u32, dst: VertexId, ts: u64) -> Option<Nbr>

Get a specific edge by source and destination. Test-only row-stamp filter; production reads go through the version authority.

fn edges_of(&self, src_vid: u32, ts: u64) -> Vec<Nbr>

Get all valid edges of a vertex at the given timestamp. Test-only row-stamp filter; production reads go through the version authority. Test and offline use; production traversals use the visitor or caller-buffer fill paths instead of this allocating accessor.

fn compact_vertex_with_reporting( &mut self, vid: u32, cutoff: u64, on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Reclaim one vertex in place, dropping entries eligible for collection at cutoff and tightening live entries without touching other rows.

fn reclaimable_count(&self, vid: u32, cutoff: u64) -> usize

Count entries of one vertex that are reclaimable at cutoff.

fn vertex_needs_compact(&self, vid: u32, cutoff: u64) -> bool

Whether one vertex holds anything reclaimable at cutoff.

fn vertex_census(&self, vid: u32) -> (usize, usize, usize)

Physical entry census of one vertex: (live, dead, capacity).

fn vertex_reclaim_probe(&self, vid: u32, cutoff: u64) -> (usize, usize)

Single-walk reclaim probe of one vertex: (dead, reclaimable).

fn row_gap(&self, vid: u32) -> usize

Reserved primary slots minus live primary entries of one row.

fn row_density(&self, vid: u32) -> f32

Live primary entries per unit of reserved primary capacity.

fn rebalance_row(&mut self, vid: u32) -> bool

Rebalance one row in place, pulling overflow entries into primary gaps and repacking leftover overflow. Returns true when the row no longer holds overflow. Strategies without rows report true.

fn used_memory_size(&self) -> usize

Return the approximate memory usage in bytes.