Module node_group 

Node-group sharding for edge topology.

Each edge direction is partitioned by bound-endpoint interval: group = vid >> group_bits, local = vid & (group_size - 1). Every group owns one CsrVariant holding only the rows of its interval, plus insert/delete/column-update dirt markers driving incremental checkpoints. Neighbor keys keep global endpoint values; only row addressing is local.

Inside a group, fixed row windows form leaf regions carrying their own three-kind dirt. Group dirt is the OR over its regions; reclaim passes decide per region so unchanged regions are skipped, while checkpoints skip clean groups at group granularity. Whole-group and whole-table ratios stay observability only.

Groups are sparse: only existing groups are materialized, the manifest records existing group ids rather than a contiguous count, missing groups read as empty and writes create them on demand, and no files are written for missing groups. Endpoints are expected dense; sparse large endpoints must be densified offline via vertex remapping before bulk load, otherwise the group span stays wide while only existing groups consume memory and files. The address width is locked at table creation; the only adjustment outlet is the offline reshard tool, there is no online width-change branch.

Timestamps and properties are sharded on disk by owner group and fall with the same dirt as their group: small writes rewrite only dirty groups’ timestamp and property shards, never the whole table. The in-memory visibility authority stays global by edge id; sharding changes only the flush unit.

Each group additionally holds a committed append log: the write-through delta (inserts plus tombstone markers) since the last base rewrite. Insert-only groups checkpoint by persisting the append log alone; groups with delete dirt rewrite the base and discard the log. Append row indexes are dropped after the flush that persists them.

Concurrency: this container adds no locking of its own and follows the canonical contract in super::mutable_csr. All mutation takes &mut self; the route cache is the only shared mutable state and stays correct under relaxed atomics because removals invalidate before they unlink.

Layout by responsibility (node_group/ subdirectory):

• address holds group/region address arithmetic and density calibration.
• dirt holds the region/group dirt model and checkpoint classification.
• manifest holds the per-table existing-group layout record.
• append_log holds the per-group write-through delta and its codec.
• core holds construction, group materialization, routing and bulk insert.
• freeze holds explicit group freeze and unfreeze between mutable and packed forms.
• read holds routed physical read helpers.
• iter holds the cross-group scan iterator.
• compaction holds region observation, merge-scope selection and tombstone compaction passes.
• stats holds observability views summed across groups.
• trait_impl adapts the set to the CSR traits.

Structs

CsrShardSet

Sharded topology container for one edge direction.

GroupDirty

Write-path dirt of one group: the OR over its leaf regions. Cleared for groups a checkpoint persisted.

NodeGroupStats

Observability view of one group.

RegionDirty

Write-path dirt of one leaf region. Cleared for regions a checkpoint persisted. Topology checkpoints rewrite or append-persist a region exactly when inserted or deleted is set; column_updated traces property-only writes for observability without forcing topology work.

ShardCsrIterator

Iterator chaining every existing group in group order, translating local rows to global vertex ids. Missing groups are absent and never visited.

TableShardManifest

Per-table group layout shared by both directions.

Enums

EdgeCheckpointKind

Checkpoint class derived from group dirt before it is cleared.

FreezeBlockReason

Why one group cannot freeze right now.

FreezeFeasibility

Read-only freeze outcome for one group.

RegionMergeScope

Merge scope selected for a dirty region. The trigger is always the per-row reclaimable count; density only widens the scope. Larger scopes require higher density so sparse spans never drag clean rows along.

Constants

DEFAULT_NODE_GROUP_BITS

Default address bits per node group: 12 bits cover 4096 rows.

GROUP_MERGE_MIN_DENSITY

Group density at or above which a multi-region dirty span merges at group scope. Below it merges stay region-scoped.

LEAF_HIGH_CSR_DENSITY

Leaf-level density ceiling of the packed-CSR calibrator tree: leaf regions may pack full, higher levels grade down toward the packed target.

LEAF_REGION_ROWS

Rows per leaf region inside a group. A default group holds 16 regions; region dirt and density merges operate at this granularity.

REGION_MERGE_MIN_DENSITY

Region density at or above which a dirty region merges as a whole. Below it only rows holding reclaimable entries are visited.

Functions

calibrator_max_density

Density ceiling for one calibrator-tree level: full at the leaf level, grading linearly down to the packed row target at the top. Levels above the top clamp to the packed target.

calibrator_tree_height

Height of the density calibrator tree for one address width: group rows halve down to leaf regions, so the height is the group-bits minus the leaf-region-rows log2.

group_base

First global vertex id covered by a group.

group_id_for

Group index for a global vertex id.

group_size

Rows covered by one group.

local_vid

Row address inside its group.

region_id_for_local

Leaf region owning a group-local row.

region_local_range

Group-local [start, end) row window of one leaf region.

region_tail_gap

Reserved tail gap for a region holding live entries at the packed density target. Empty regions hold no gap; gaps live at the region tail, never inside rows.

regions_per_group

Leaf regions covering one group of group_size rows.

validate_group_bits

Validate the configured address width.