flying-jib/agent/ADRs/0008-border-session-migration.md

ADR-0008: Border strategy — session migration / portals

• Status: Accepted
• Date: 2026-07-30

Context

A single global authoritative Minecraft simulation across many peers is unrealistic at scale (tick rate, redstone, entity AI, bandwidth). Full chunk CRDTs are also impractical for real-time play.

Decision

Coordinate-space federation with session migration:

1. Each peer owns a region with bounds/offset.
2. Near border: plugin triggers portal or auto-migrate.
3. Serialize player state; Protomux flying-jib/migrate handoff.
4. Guest switches HyperDHT tunnel to neighbor worldKey and reconnects Java to localhost.
5. Spawn at mapped coordinates.

Not in v1: streaming foreign chunks into the local Squid world or dual-sim entity forwarding.

Later phases may add interest-based border sync without abandoning local authority.

Consequences

Positive

• Feasible engineering path
• Clear failure mode when neighbor offline
• Preserves Squid as sole authority per region

Negative / tradeoffs

• Reconnect hitch at borders
• Inventory race risks (must two-phase commit — Q6)
• Not perfectly seamless vanilla continuous terrain

Follow-ups

• Phase 4 plugins + migrate state machine
• Resolve Q6 with tests