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:

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

flowchart LR
  R1["Region A Squid"] -->|"border"| Mig["Session migrate<br/>handoff + tunnel switch"]
  Mig --> R2["Region B Squid"]
  Java[Java client] -->|"reconnect localhost"| R2

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

1.4 KiB Raw Blame History