Instance Director

Instance-record store. In-memory default here; the cluster twin persists records in the shared store with ids from a shared INCR (per-node counters collide — the lobby-id lesson). Kept deliberately small so a twin is a drop-in.

• void CollectAll(List<InstanceRecord> results)

  Snapshots every live record into results (cleared first) — the sweep scan.

• long NextId()

  Atomically returns the next instance id (starts at 1).

• bool Remove(long instanceId)

  Removes the record and its account index entries. Returns false if absent.

• void Save(InstanceRecord record)

  Creates or updates the record (and its roster→account index).

• bool TryGet(long instanceId, out InstanceRecord record)
• bool TryGetByAccount(long accountId, out InstanceRecord record)

  The instance whose roster contains this account (status re-fetch), if any.

Single-use join-token store. In-memory default here; the cluster twin keys {prefix}:director:join:{token} with atomic GETDEL consume, so a token minted on the allocating node validates on the destination node. Tokens are bearer secrets: never logged.

• void InvalidateInstance(long instanceId)

  Teardown sweep: unconsumed tokens for this instance are invalidated.

• void Store(string token, long accountId, long instanceId, int ttlSeconds)

  Stores a freshly minted token with its arrival deadline.

• bool TryConsume(string token, out long accountId, out long instanceId)

  Single-use, atomic: a token validates exactly once; expired or unknown fails.

Placement SPI. SameNode (default) and LeastLoaded complete inline; an external adapter completes later — the Director holds the instance in Allocating and drains completions on its tick (single poll thread, no cross-thread handler execution: completions may be REPORTED from any thread, they are only ACTED on from the tick).

• void Place(InstanceSpec spec, long instanceId, IPlacementCompletion completion)

  Choose (or begin choosing) a host node for this spec.

The Director: allocate an instance for a roster, push each member an InstanceAssignment (endpoint + single-use join token when a hop is needed), validate arrivals, run the lifecycle, return players to the hub. Genre-agnostic — a card table, an FPS round, and an RTS match all ride the same contract. How a game uses it. Resolve IInstanceDirector from DI. When a group is ready (a formed match, a lobby start, a party entering a dungeon), call Allocate with an InstanceSpec; the piece places the instance, mints per-member join tokens, and pushes each player an InstanceAssignment — you write no networking. Subscribe to MemberArrived to fold each player into your round as they actually arrive, and to Ended to release game state / an external fleet server when the instance tears down.

• long Allocate(InstanceSpec spec)

  Allocate an instance for this roster. Returns the instance id immediately (phase Allocating or Ready), or 0 when refused (empty roster / no realizer for Kind). Assignments are pushed to every roster member once placement resolves and tokens are minted; on placement failure the roster gets notification 4204 and Ended fires with AllocationFailed.

• event Action<InstanceInfo, byte> Ended

  (info, reason) — reason is an InstanceEndReason. Fires synchronously at the teardown (a terminal signal — cleanup is idempotent and safe re-entrant).

• event Action<long, long> MemberArrived

  (instanceId, accountId) — a rostered member was ADMITTED (an inline same-node admit at allocation, or a token-validated hop arrival). Fired once per admit. Like PhaseChanged it is DEFERRED to the Director tick (never re-entrant inside Allocate or a join handler), so a game folds each player into its round as they actually arrive — including cross-node members that had no session at formation (the LocalSession==null gap). Resolve the session by account (IAccountDirectory) — on the admitting node it is local.

• event Action<InstanceInfo, byte> PhaseChanged

  (info, phase) — the instance advanced to a new InstancePhase (Ready once placed, Live on the first admit). Lets a co-located game learn the instance filled/came alive without POLLING occupancy. Unlike Ended, this is DEFERRED to the Director tick — never fired re-entrantly inside Allocate — so a game may create its round in the same call that allocates and still receive the arc afterward (the ordering hazard: today's inline admits fire before the allocating call returns). Terminal phases stay on Ended (richer reason); this covers the coming-to-life arc only.

• bool Release(long instanceId, byte reason = 0)

  Explicit teardown: evict remaining players (return-to-hub assignments), destroy the container, release the record. Idempotent. reason is the InstanceEndReason reported by Ended — the non-default value a cluster reaper passes is NodeLost (owner node died; no local container work is attempted for a container this node never realized).

• bool TryGet(long instanceId, out InstanceInfo info)

  Snapshots one instance's current state.

How a placement strategy reports its verdict (thread-safe to call).

• void Failed(long instanceId, ushort reasonCode)

  The roster gets notification 4204 (AllocationFailed).

• void Placed(long instanceId, in Placement placement)

Director tuning (defaults here, never inline — rule 4). Bound from Crossplay:Director by the composition layer.

• double AbandonSeconds { get; set; }

  Live → empty grace before the abandoned teardown (the Dungeons default).

• string AdvertisedEndpoint { get; set; }

  This node's public host:port, handed to players on other nodes when an instance is placed here ("" = single-node, never needed). The composition layer defaults it from the World advertised endpoint when present.

• double AllocatorTimeoutSeconds { get; set; }

  External-allocator (Placement = "External") request deadline. A fleet call that does not answer within this window fails the allocation (roster gets 4204) rather than stranding the instance in Allocating; keep it under PendingSeconds so a hung allocator fails before the never-arrived sweep. Ignored by SameNode/LeastLoaded — they resolve inline.

• string ContainerPrefix { get; set; }

  Container-name prefix (container = "prefix:id").

• int JoinTokenTtlSeconds { get; set; }

  Join-token arrival deadline (not a session lifetime).

• double PendingSeconds { get; set; }

  Ready → never-arrived teardown window.

• string Placement { get; set; }

  Placement strategy: "SameNode" (default) | "LeastLoaded" | "External". The composition layer maps this to the registered IPlacementStrategy; the piece alone always has SameNode.

• string Region { get; set; }

  This node's region (e.g. "us-east"), published on the cluster load beacon so Placement = "Region" can co-locate an instance with the region its players prefer (Region). "" = unspecified — the node still serves as a GLOBAL least-loaded fallback candidate, it just never matches a region PREFERENCE. Additive and back-compat: an unset region publishes an empty beacon field. Bound from Crossplay:Node:Region by the composition layer (a node concept, not a Director-tuning one — but it rides DirectorOptions so a card-game node with no World still carries it).

• string ReturnZone { get; set; }

  Zone kind: where return-to-hub lands ("" = the world default — the Matches/Dungeons convention). Rides return-to-hub assignments as the ContainerId.

• bool RouteLobbies { get; set; }

  Opt-in composition bridge: route lobby starts into the Director. Default off.

• bool RouteMatchmaking { get; set; }

  Opt-in composition bridge: route formed matches into the Director. Default off — with the piece absent or this false, Matchmaking behaves byte-identically to today.

• double SweepSeconds { get; set; }

  Sweep cadence for the teardown triggers.

• int WarmPoolRefillPerTick { get; set; }

  Upper bound on how many warm instances the Director creates OR tears down per tick while reconciling each kind's pool toward WarmPoolSize — the refill/shrink is spread across ticks so a large pool never bursts container creation in one frame (rule 11). Ignored when WarmPoolSize is 0.

• int WarmPoolSize { get; set; }

  Warm instance pool: pre-created idle, Ready-but-empty instances kept per realizer kind so a match can start with NO allocation latency. 0 (default) = OFF — bit-for-bit today's behavior (nothing pre-created, every Allocate runs placement + container creation). When > 0, the Director keeps this many warm instances of each kind; an Allocate CLAIMS a warm instance instantly (O(1) — skips placement and container creation, giving it the real roster + tokens + assignments as normal) and the pool refills in the background on the tick. Pool empty ⇒ falls back to a normal allocate. Trade-off: a warm instance is always LOCAL (pre-created before any roster/region is known), so warm-claimed instances ignore Placement region/least-loaded selection in exchange for zero start latency — set 0 where strict placement must win.

The Director piece, client side: consume InstanceAssignment pushes and execute the node hop they describe — the generalized transfer World's NodeRedirect was waiting for (docs/INSTANCE-DIRECTOR.md §8). Presentation-agnostic and genre-agnostic: an assignment is ids + an endpoint + an opaque payload; a text-only client prints "table 12 ready on 10.0.0.7:7778" and calls TransferAsync.

• event Action<InstanceAssignmentView> AssignmentReceived

  Raised for every assignment push (and for a ReturnToHubAsync replay), after Current updates. A game with a "Match found — Accept?" UI subscribes here, turns DirectorClientOptions.AutoTransfer off, and calls TransferAsync itself.

• event Action<TransferPhase, string> TransferPhaseChanged

  The transfer state machine, live: (phase, human-readable detail). Detail strings never contain the join token.

• InstanceAssignmentView? Current

  The most recent assignment, or null before any arrived.

• TransferPhase Phase

  The most recent transfer phase (Idle before any transfer).

• bool HasReturnAssignment

  True when a server-issued return-to-hub assignment is held and can be replayed by ReturnToHubAsync.

• UniTask<bool> TransferAsync(CancellationToken ct = default)

  Executes Current's hop: capture the previous endpoint → deliberate disconnect + dial (IServerConnection.ConnectTo) → resume the session → present the join token → await the verdict. An empty Endpoint short-circuits (the server already moved this session — no reconnect, no token). On failure the client redials the captured previous endpoint and resumes there (best effort), then reports Failed. Returns true when the transfer ended Inside.

• UniTask<bool> TravelAsync(string endpoint, CancellationToken ct = default)

  The join-less node hop (dial + resume, no InstanceJoinRequest): the World redirect convergence (RFC §8.3) and any game-driven server move ride this. endpoint is host:port. Same phase events, same previous-endpoint fallback as TransferAsync.

• UniTask<bool> ReturnToHubAsync(CancellationToken ct = default)

  Dev/demo return-to-hub. HONEST SCOPE: the Director wire (4101–4105) has NO client→server "send me home" request — returns are server-initiated (teardown pushes an assignment with InstanceId = 0 carrying the return endpoint). This method REPLAYS the most recent such assignment through the normal transfer flow (useful when AutoTransfer is off, or to retry a failed return). Returns false — refusing honestly — when no return assignment has ever been received.

• UniTask<InstanceStatusView> RefreshStatusAsync(CancellationToken ct = default)

  Reconnect-safe assignment refetch (InstanceStatusRequest, wire 4104): a client that resumed can re-ask instead of relying on a push it may have missed. A timeout returns a default view (HasInstance false).

Narrow contract the presenter drives. Render calls in (plain strings/flags — the presenter owns all wire→text mapping), user intents out. No wire types, no ids the UI must interpret.