Module seam 

Trait seam for distributed vector algorithms.

VectorShardSeam defines the cross-shard exchange surface that advanced distributed vector search algorithms require. The current production implementation uses flat scatter-gather (VectorScatterGather), which corresponds to select_shards returning all shards and the other methods being no-ops. The trait reserves the shape so future algorithms can be added by implementing a concrete type without a protocol break.

Algorithm mapping

Compass (coarse-code multi-stage routing)

Compass performs a global coarse-code lookup before the fine search to select only the most relevant shards. The coordinator calls select_shards with the query to obtain a pruned shard subset (instead of fanning out to every shard), then issues a standard k-NN scatter against that subset. The wire messages VectorCoarseRouteRequest and VectorCoarseRouteResponse carry the per-shard coarse descriptor used by select_shards to make the pruning decision.

Methods used: select_shards. Default behaviour: all shards selected (equivalent to current scatter-gather).

SPIRE (Shared Per-shard Inverted Residual Encoding)

SPIRE requires each shard to share its IVF centroid table with peers at index-build time so queries can leverage cross-shard centroid knowledge. This exchange is initiated shard-to-shard (not coordinator-mediated) and happens once per build, not per query. build_time_exchange is the hook for this; direct_message is the transport primitive it calls.

Methods used: build_time_exchange, direct_message. Default behaviour: no-op build exchange; direct_message routes through the coordinator if a ShardRpcDispatch is available, otherwise returns Err(VectorSeamError::DirectMessagingUnsupported).

CoTra-RDMA (Cooperative Traversal over RDMA)

CoTra-RDMA performs one-sided RDMA READs directly into a remote shard’s HNSW graph without involving the remote CPU. The reading shard first calls exposed_region on the remote shard descriptor to obtain the registered memory region (address + rkey); it then issues one-sided reads at the hardware level. When RDMA is unavailable, exposed_region returns None and the algorithm falls back to standard scatter-gather.

Methods used: exposed_region. Default behaviour: None — RDMA direct reads not supported by this impl.

Structs

MemoryRegion

A registered memory region exposed for one-sided (RDMA) reads.

ShardMessage

Opaque payload exchanged between shards for algorithm-specific messages.

ShardMessageReply

Reply to a direct_message call.

ShardRef

A reference to a peer shard used as a target for seam calls.

Enums

ShardMessageKind

Discriminant for ShardMessage payloads.

ShardSubset

Subset of shards selected for a query phase.

VectorSeamError

Errors specific to VectorShardSeam operations.

Traits

VectorShardSeam

Cross-shard exchange seam for distributed vector search algorithms.