Struct ShardOwnershipCatalog 

pub struct ShardOwnershipCatalog { /* private fields */ }

The global shard ownership catalog held by every data member.

This single type plays both roles in ADR 0037’s model: it is the authoritative state the Cluster Supervisor leader writes through, and it is the replica each data member holds and routes against. Both write through apply_update, so the stale-version rejection that makes leader writes versioned is the same rule that makes replica application order-independent. Nothing here needs user-data sharding to find an entry: ranges are addressed directly by (collection, range_id), and routing (route) is a local scan of the replica.

Implementations

impl ShardOwnershipCatalog

pub fn plan_write_transaction( &self, targets: &[KeyTarget], ) -> Result<WriteTransactionPlan, WriteTransactionReject>

Plan a write transaction over targets in the first multi-writer cut (issue #1002).

Resolves every targeted key to its owning range and groups by writer:

• all targets owned by one writer → WriteTransactionPlan (the transaction commits atomically on that owner, even across several of its own ranges);
• targets span ranges of different writers → WriteTransactionReject::CrossRange naming every writer — this cut has no atomic cross-writer commit;
• a target routes nowhere → WriteTransactionReject::Unroutable.

Pure: it reads the catalog and returns intent. Each admitted write still passes admit_public_write at the owner’s current epoch, so a stale plan cannot smuggle a write past fencing.

pub fn plan_read_fanout( &self, targets: &[KeyTarget], ) -> Result<ReadFanout, ReadFanoutReject>

Plan a simple, best-effort cross-range read fanout over targets (issue #1002).

Collects the resolved targets into one ReadLeg per owner so the caller can scatter the read across every range owner and gather the results. This is not a consistent snapshot — see ReadFanout. Err only when the read is empty or a target routes nowhere; spanning many owners is the expected, successful case.

pub fn plan_consistent_read( &self, targets: &[KeyTarget], snapshot: Option<&GlobalReadWatermark>, ) -> Result<ConsistentReadPlan, ConsistentReadReject>

Plan a globally consistent cross-range read over targets, pinned to snapshot (issue #1002).

A consistent read must pin every range it touches to a single safe point:

• snapshot is None → ConsistentReadReject::NoSafeSnapshot; the caller must obtain a global watermark first;
• a targeted range is absent from snapshot → ConsistentReadReject::WatermarkGap;
• a target routes nowhere → ConsistentReadReject::Unroutable;
• otherwise → a ConsistentReadPlan with each leg pinned to its range’s watermark.

This is the explicit safe-snapshot path: without it a cross-range read may only be served as a best-effort ReadFanout, never as a consistent one.

impl ShardOwnershipCatalog

pub fn new() -> ShardOwnershipCatalog

An empty catalog — a cluster with no collections placed yet.

pub fn declare_collection( &mut self, collection: CollectionId, mode: ShardKeyMode, ) -> Result<(), CatalogError>

Declare a collection’s shard key mode up front. Hash is the default, so this is mainly how an operator opts a collection into Ordered mode before any range exists. Declaring the same mode twice is idempotent; redeclaring a different mode for a collection that already has a mode is a ShardKeyModeMismatch.

pub fn shard_key_mode(&self, collection: &CollectionId) -> Option<ShardKeyMode>

The declared shard key mode of collection, if it has any ranges or was explicitly declared.

pub fn apply_update( &mut self, entry: RangeOwnership, ) -> Result<UpdateOutcome, CatalogError>

Apply a versioned ownership update — the single write path for both leader writes and replica application.

Creation (the range does not yet exist) auto-declares the collection’s mode from the entry and checks the new range does not overlap a sibling. Updating an existing range requires the entry’s version to strictly advance the current version; anything else is a StaleVersion rejection that leaves the catalog untouched. Either way the entry’s mode must match the collection’s declared mode.

pub fn range( &self, collection: &CollectionId, range_id: RangeId, ) -> Option<&RangeOwnership>

The current ownership of one range, addressed directly by identity — no routing required, because the catalog is what routing is built on.

pub fn ranges_for<'a>( &'a self, collection: &CollectionId, ) -> impl Iterator<Item = &'a RangeOwnership>

Every range of collection, in range-id order.

pub fn route( &self, collection: &CollectionId, key: &[u8], ) -> Option<&RangeOwnership>

Route a normalized range key to the range that owns it — the catalog read every routing decision makes. Returns the owning RangeOwnership (whose owner, epoch, and replicas the caller uses to send and fence the write), or None if no range covers the key yet.

pub fn route_shard_key( &self, collection: &CollectionId, shard_key: &[u8], ) -> Option<&RangeOwnership>

Route a logical shard key according to the collection’s declared mode.

Ordered collections route the shard key bytes directly. Hash collections first map the shard key into a stable hash slot and route that slot’s range key through the same collection -> range catalog.

pub fn role_at( &self, node: &NodeIdentity, collection: &CollectionId, range_id: RangeId, ) -> Option<RangeRole>

This node’s RangeRole for a directly-addressed range (issue #990). Returns None when no such range exists in the catalog — distinct from NoCopy, which means the range exists but this node holds no copy of it.

pub fn admit_public_write( &self, node: &NodeIdentity, collection: &CollectionId, key: &[u8], expected_epoch: OwnershipEpoch, ) -> Result<&RangeOwnership, RangeWriteReject>

Ownership-aware gate for a public write (issue #990, PRD #987).

Routes key to its range, then admits the write only when node is the range’s current Owner and expected_epoch matches the range’s current ownership epoch. On success returns the owned RangeOwnership (so the caller can proceed with the write against the authoritative epoch); otherwise a RangeWriteReject explaining why.

This is the public surface’s gate — the counterpart of the instance-wide WriteGate for multi-writer, per-range ownership. The internal replica-apply path does not consult it: replicated changes flow into a replica through the privileged apply path (fenced by issue #991’s range-authority watermark), so a node that rejects a public write here can still legitimately apply the owner’s replicated changes for the very same range.

pub fn range_count(&self) -> usize

Total number of owned ranges across all collections.

pub fn entries(&self) -> impl Iterator<Item = &RangeOwnership>

All ranges, in (collection, range_id) order — the full catalog content a joining member adopts as its starting replica (see ControlPlaneSnapshot).

impl ShardOwnershipCatalog

pub fn plan_route( &self, local: &NodeIdentity, request: &RoutedRequest, policy: &RoutingPolicy, ) -> RouteDecision

Plan how local should handle request under policy — the any-node routing decision (issue #993).

Resolves the target range from the catalog, then:

• owner of the range → Local;
• non-owner, forwarding enabled, safe point op within budget → Forward to the owner;
• non-owner but the op is unsafe to forward / oversized / forwarding disabled → Redirect with the owner+epoch hint;
• no range covers the key → Unroutable.

The decision is pure: it reads the catalog and returns intent. Fencing is still enforced below routing — a forwarded or locally-executed write lands on admit_public_write at the owner’s current epoch, so a stale routing decision cannot smuggle a write past ownership.

impl ShardOwnershipCatalog

pub fn topology_snapshot(&self) -> TopologySnapshot

Project the catalog into a driver-facing TopologySnapshot — the payload a topology poll serves (issue #994).

The snapshot carries every range’s bounds, owner, replicas, ownership epoch, and catalog version, and stamps a generation (version) drivers use to tell a newer snapshot from a stale one.

Trait Implementations

impl Clone for ShardOwnershipCatalog

fn clone(&self) -> ShardOwnershipCatalog

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ShardOwnershipCatalog

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

Formats the value using the given formatter.

impl Default for ShardOwnershipCatalog

fn default() -> ShardOwnershipCatalog

Returns the “default value” for a type.