Cross Shard Handoff

Cross-Shard Handoff

Audience: Engine Developer Status: ✍️ Draft

Moving a zone (and the players in it) from one world server to another with zero dropped messages and exactly-once semantics. The handoff protocol is the backbone of scaling in/ out, upgrades, and rebalancing.

Intended contents

• The handoff protocol (api/proto/telosmud/handoff/v1, rpc Prepare/Commit/Abort/AdoptZone): the two-phase move of a zone between shards
• The exactly-once substrate: fencing, DurableEvent.Seq watermark, idempotent adoption; the neither-own and double-Prepare/CAS-conflict windows and how they're handled
• Fenced drain: BeginDrain/SIGTERM → HandoverZone → lease-into-shard; zero-drop guarantee
• Signed handoff: trust tier and session carried on the signed handoff (keyless-handoff refuse)
• Interaction with placement/leases (director) and session routing (gate)
• Classes/algorithms/APIs: handoff coordinator, prepare/commit state machine, fence tokens
• Mermaid: Prepare→Commit two-phase handoff sequence with fencing; failure/abort paths
• Cross-links: Distributed Systems Model, Orchestration & Directors, Zone Runtime & Actor Model

---

Scaffold page — full content pending the wiki build-out.