Struct ShardBalancer 

pub struct ShardBalancer { /* private fields */ }

Tracks which peers own which HNSW-layer shards and computes load balance metrics used to drive migration decisions.

Implementations

impl ShardBalancer

pub fn new(config: ShardBalancerConfig) -> Self

Create a new ShardBalancer with the given configuration.

pub fn record_vector_assignment(&mut self, peer_id: &str, cid: &str)

Record that peer_id has indexed the vector identified by cid.

Increments the peer’s load counter and updates the CID ownership list. If the resulting load fraction breaches rebalance_threshold the peer is added to overloaded_peers.

pub fn suggest_peers_for_vector(&self, count: usize) -> Vec<String>

Return the count least-loaded peers, suitable for assigning a new vector. Peers are sorted by ascending load; if fewer than count peers are known the full list is returned.

pub fn is_overloaded(&self, peer_id: &str) -> bool

Return true when peer_id’s load fraction exceeds rebalance_threshold.

pub fn load_distribution(&self) -> HashMap<String, f32>

Return a map of peer_id → load_fraction (0.0–1.0), where the denominator is max_vectors_per_peer.

pub fn vectors_to_migrate(&self) -> Vec<(String, String)>

Identify (cid, from_peer) pairs that should be migrated away from hot-spot peers.

For every overloaded peer, walks its assigned CIDs and collects up to ceil(excess) migration candidates, preferring CIDs that have enough existing owners so redundancy is preserved after migration.

pub fn balance_score(&self) -> f32

Compute a balance score in [0.0, 1.0].

A score of 1.0 means all peers carry the same load; 0.0 means the load is completely concentrated on a single peer.

Uses the complement of the coefficient of variation (CV) clamped to [0, 1] so that it is easily interpretable.

pub fn assign_vector(&self, vector: &[f32], n_replicas: usize) -> Vec<String>

Assign a vector to the n_replicas best peers using consistent hashing on the vector’s hash fingerprint.

Peer selection is deterministic given the same vector content: the vector is hashed via a stable fingerprint (sum of floats cast to bits), then peers are sorted by (hash XOR peer_hash) % capacity, and the n_replicas with the smallest distance are returned.

When fewer than n_replicas peers are tracked, all known peers are returned (no padding).

pub fn imbalance_score(&self) -> f64

Compute the load imbalance score.

Returns 0.0 for a perfectly balanced cluster and 1.0 when the entire load is concentrated on a single peer. Uses the normalised standard deviation (coefficient of variation), clamped to [0.0, 1.0].

pub fn migration_plan(&self, limit: usize) -> Vec<(String, String)>

Return up to limit (vector_id, target_peer) pairs to migrate for better balance.

Candidates are chosen from the most overloaded peer(s) and the target is the least-loaded peer that does not already own the vector.

pub fn update_peer_capacity(&mut self, peer: &str, capacity: usize)

Update the capacity ceiling for a peer.

This updates max_vectors_per_peer in the configuration to the supplied value and re-evaluates overload status for peer. Only the single peer’s overload flag is updated; a full sweep is not performed.

pub fn remove_peer(&mut self, peer: &str) -> Vec<String>

Remove peer from the balancer and return the list of vector IDs it was responsible for. The caller is expected to trigger migration of the returned CIDs to other peers.

pub fn record_migration(&mut self, cid: &str, from_peer: &str, to_peer: &str)

Update internal bookkeeping after cid has been migrated from from_peer to to_peer.

Decrements from_peer’s counter, increments to_peer’s counter, updates the ownership list, and refreshes overload status.