mars docs

Topology

How shards are organized, split, and merged.

Affinity

Shards group entries by topological affinity — entities that resolve together belong together. Affinity is computed from:

  • Namespace (entries in the same did:oas:<ns>:* cluster).
  • Lineage (descendants of the same HMR cluster).
  • Co-resolution patterns (entries frequently fetched together).

Geographic latitude is a secondary signal, not the primary axis.

Split

When a shard exceeds ~10M entries:

  1. The shard operator runs an online split — a new shard is provisioned from a freshly-derived ENR scope.
  2. Entries are streamed to the new shard in background, with no read downtime.
  3. Once streaming is complete, the GAL updates the affinity routing table.
  4. The original shard discards its half.

Merge

When two shards drop below ~3M entries:

  1. The smaller shard's primary requests merge into the larger.
  2. Streaming reverses the split process.
  3. Affinity routing collapses two entries into one.

Splits and merges are operational, not protocol-level — clients see consistent resolution throughout.