AttachmentDirectory

Who is a game's players talking through right now — the attachment directory.

In a federation, three servers form a fully-meshed core and a game's players each connect to whichever server is nearest them: Alice through S1, Bob through S2, Carol through S3. To hand a message meant only for Bob to the one server Bob is behind, every server needs the same little lookup table: Bob → S2. That table is this directory.

It is deliberately not the durable record of who is in the game — that lives in consensus and can never be lost. The directory carries only the cheap, fast-changing fact of which server a player's packets are flowing through this moment, which changes every time they reconnect. So it is kept as a replicated map that servers gossip to each other rather than a consensus-committed fact: each server writes its own local players into the map, the map spreads across the core over the inter-server link, and every server ends up with the same picture a moment later.

How it maps onto kuilt primitives

The map is an LWWMap, PeerId> — client → server, last writer wins. LWW is the exact fit for "latest attachment wins": a fresh attach (a newer-tagged LWWMap.set) supersedes an older one, and a detach is an LWWMap.remove tombstone that competes under the same tag order, so a player who leaves disappears from the table and a player who moves is routed to their new server once the newer write wins. (ORMap/ORSet model add-wins sets of things; a register-per-key last-writer table is what this is.) A Quilter runs the map live over the inter-server Seam, driving the delta-exchange and anti-entropy that make every server converge.

Eventual, and safe to be

Replication is eventually consistent: for a brief window after a player moves, a lagging server may still hold the stale server for them. That is safe by construction — a stale entry misroutes a single unicast to one wrong server, which simply drops it (a message is never fanned to extra recipients), and the sender resends once the map converges. Correctness is never at risk, only a few milliseconds of routing latency.

Feeding the topology

twoTier hands the live lookup to a TwoTier topology policy as its attachment function, so the two-tier overlay floods each player's broadcasts through exactly the server they are attached to — reading the directory live on every view recomputation.

Construct one per server via attachmentDirectory. Not thread-confined: the underlying Quilter guards its own state with a lock, and the per-write timestamp source here is an atomic counter, so attach/detach/lookup are safe to call from any coroutine on any dispatcher.

See also