@pylonsync/realtime 0.16.1 → 0.17.0

package/dist/connection.d.ts

@@ -23,9 +23,10 @@ export interface ShardConnectOptions {
      * authorization hooks.
      *
      * Tickets expire. Pass a function to get a new one for each connection
-     * attempt, so a reconnect after the expiry still gets in.
+     * attempt, so a reconnect after the expiry still gets in. It receives the
+     * shard the client is connecting to, which changes after a transfer.
      */
-    ticket?: string | (() => string | Promise<string>);
+    ticket?: string | ((shardId: string) => string | Promise<string>);
     /** Host (and port) of the Pylon server. Defaults to `window.location.host`. */
     baseUrl?: string;
     /**
@@ -33,7 +34,10 @@ export interface ShardConnectOptions {
      * port (the dedicated port is the HTTP port + 3, e.g. 4324).
      */
     wsPort?: number;
-    /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
+    /**
+     * Explicit WebSocket URL. Overrides baseUrl/wsPort. After a transfer its
+     * `shard` query parameter is replaced with the new shard.
+     */
     wsUrl?: string;
     /** Reconnect on unexpected close (default: true). */
     autoReconnect?: boolean;
@@ -54,6 +58,16 @@ export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
     onSnapshot: (fn: (snapshot: TSnapshot, tick: number, ack: number) => void) => void;
     /** Called when the shard refuses an input (see `ShardInputRejection.code`). */
     onInputRejected: (fn: (rejection: ShardInputRejection) => void) => void;
+    /**
+     * Called when the server moved this subscriber to another shard (a zone
+     * line, a dungeon). The client reconnects there on its own, with the
+     * ticket the server sent; `shardId` changes before the handlers run.
+     * When the shard itself moves to another machine (a deploy), the client
+     * reconnects the same way, and these handlers are not called.
+     */
+    onTransfer: (fn: (shardId: string, from: string) => void) => void;
+    /** The shard the client is connected (or connecting) to. */
+    readonly shardId: string;
     /**
      * For a shard that replicates entities: called after each frame is
      * applied to `entities`, with what it changed.
@@ -88,6 +102,12 @@ export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
     close: () => void;
     readonly connected: boolean;
 }
+/**
+ * True when a shard ticket (`v1.<payload>.<signature>`, the payload
+ * base64url JSON with `exp` in Unix seconds) expires within `marginSecs`.
+ * A ticket that does not parse counts as not expired: the server decides.
+ */
+export declare function ticketExpired(ticket: string, nowMs?: number, marginSecs?: number): boolean;
 /**
  * Connect to a shard without React. Returns a client you can wire into any
  * framework or render loop.

package/dist/game.d.ts

@@ -71,6 +71,8 @@ export interface ShardGame<TInput = unknown> {
     predict<S>(step: (state: S, input: TInput) => S, options?: PredictorOptions): Predictor<S, TInput>;
     onReplication(fn: (entities: EntityTable, summary: ReplicationSummary, tick: number, ack: number) => void): void;
     onInputRejected(fn: (rejection: ShardInputRejection) => void): void;
+    /** The server moved this player to another shard; see `ShardClient.onTransfer`. */
+    onTransfer(fn: (shardId: string, from: string) => void): void;
     onOpen(fn: () => void): void;
     onClose(fn: () => void): void;
     onError(fn: (err: Error) => void): void;

package/dist/wire.d.ts

@@ -4,7 +4,8 @@
  * A client asks for it with `?v=2` on the shard WebSocket URL. Each server
  * message is a binary frame with an 18-byte header:
  *
- *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication
+ *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication,
+ *            4 transfer (JSON `{ shard, ticket }`: the last frame; reconnect there)
  *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom, 4 replication
  *   2   8  tick (u64 big-endian)
  *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
@@ -20,7 +21,17 @@ export declare const ShardFrameKind: {
     readonly InputRejected: 2;
     /** An entity replication frame: apply it to an `EntityTable`. */
     readonly Replication: 3;
+    /**
+     * The subscriber moved to another shard (`ShardTransferNotice`, JSON). The
+     * last frame on the connection.
+     */
+    readonly Transfer: 4;
 };
+/** Where the subscriber went: connect to `shard` with `ticket`. */
+export interface ShardTransferNotice {
+    shard: string;
+    ticket: string;
+}
 export declare const ShardCodec: {
     readonly Json: 0;
     readonly MessagePack: 1;
@@ -39,7 +50,10 @@ export interface ShardFrame {
 /** Why an input did not take effect. */
 export interface ShardInputRejection {
     clientSeq: number | null;
-    /** `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`, or `apply_failed`. */
+    /**
+     * `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`,
+     * `transferring`, or `apply_failed`.
+     */
     code: string;
     message: string;
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Pylon realtime shard client pieces with no framework: the wire protocol, codecs, and the entity replication decoder and table.",
   "type": "module",
   "main": "./src/index.ts",

package/src/connection.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, expect, test } from "bun:test";
 
-import { connectShard } from "./connection";
+import { connectShard, ticketExpired } from "./connection";
 
 const sockets: FakeWebSocket[] = [];
 class FakeWebSocket {
@@ -78,3 +78,217 @@ test("send returns 0 and sends nothing while the socket is not open", () => {
   expect(errors[0]).toContain("not open");
   client.close();
 });
+
+/** A version 2 frame with a JSON payload. */
+function jsonFrame(kind: number, tick: number, body: unknown): ArrayBuffer {
+  const payload = new TextEncoder().encode(JSON.stringify(body));
+  const out = new Uint8Array(18 + payload.length);
+  const view = new DataView(out.buffer);
+  view.setUint8(0, kind);
+  view.setUint8(1, 0);
+  view.setUint32(6, tick);
+  out.set(payload, 18);
+  return out.buffer;
+}
+
+test("a transfer frame moves the client to the new shard with the ticket it carries", async () => {
+  const asked: string[] = [];
+  const client = connectShard<{ zone: string }>("west", {
+    subscriberId: "p1",
+    baseUrl: "h",
+    ticket: (shard) => {
+      asked.push(shard);
+      return `own-${shard}`;
+    },
+  });
+  const moves: Array<[string, string]> = [];
+  const snaps: string[] = [];
+  client.onTransfer((to, from) => moves.push([to, from]));
+  client.onSnapshot((s) => snaps.push(s.zone));
+  await settle();
+  const first = sockets[sockets.length - 1];
+  expect(first.url).toContain("shard=west");
+  expect(first.protocols).toEqual(["ticket.own-west"]);
+  first.readyState = 1;
+  first.onopen?.();
+  first.onmessage?.({ data: jsonFrame(1, 500, { zone: "west" }) });
+  expect(client.tick).toBe(500);
+
+  // The server moves the player, then closes.
+  first.onmessage?.({ data: jsonFrame(4, 501, { shard: "east", ticket: "from-server" }) });
+  expect(client.shardId).toBe("east");
+  expect(moves).toEqual([["east", "west"]]);
+  expect(client.tick).toBe(-1);
+  first.close();
+  await settle();
+
+  // At once, to the new shard, with the ticket from the frame.
+  const second = sockets[sockets.length - 1];
+  expect(second).not.toBe(first);
+  expect(second.url).toContain("shard=east");
+  expect(second.protocols).toEqual(["ticket.from-server"]);
+  expect(delays[delays.length - 1]).toBe(0);
+  second.readyState = 1;
+  second.onopen?.();
+  // The new shard's ticks start low; the client takes them.
+  second.onmessage?.({ data: jsonFrame(1, 3, { zone: "east" }) });
+  expect(client.tick).toBe(3);
+  expect(snaps).toEqual(["west", "east"]);
+
+  // A later reconnect asks the ticket function for the new shard.
+  second.close();
+  await settle();
+  expect(asked).toEqual(["west", "east"]);
+  expect(sockets[sockets.length - 1].protocols).toEqual(["ticket.own-east"]);
+  client.close();
+});
+
+test("an explicit wsUrl follows a transfer", async () => {
+  const client = connectShard("west", {
+    subscriberId: "p1",
+    wsUrl: "ws://h/shard?shard=west&sid=p1&v=2",
+  });
+  await settle();
+  const first = sockets[sockets.length - 1];
+  first.readyState = 1;
+  first.onopen?.();
+  first.onmessage?.({ data: jsonFrame(4, 9, { shard: "east", ticket: "t" }) });
+  first.close();
+  await settle();
+  expect(sockets[sockets.length - 1].url).toBe("ws://h/shard?shard=east&sid=p1&v=2");
+  client.close();
+});
+
+test("after a transfer, retries keep the transfer ticket until the new shard sends a frame", async () => {
+  const client = connectShard("west", {
+    subscriberId: "p1",
+    baseUrl: "h",
+    ticket: (shard) => `own-${shard}`,
+  });
+  await settle();
+  const first = sockets[sockets.length - 1];
+  first.readyState = 1;
+  first.onopen?.();
+  first.onmessage?.({ data: jsonFrame(4, 1, { shard: "east", ticket: "from-server" }) });
+  first.close();
+  await settle();
+  // The first attempt at east fails before opening: the retry still uses
+  // the server's ticket.
+  const failed = sockets[sockets.length - 1];
+  expect(failed.protocols).toEqual(["ticket.from-server"]);
+  failed.close();
+  await settle();
+  // Opened, then closed before any frame (the shard refused the ticket, say):
+  // still the server's ticket.
+  const opened = sockets[sockets.length - 1];
+  expect(opened.protocols).toEqual(["ticket.from-server"]);
+  opened.readyState = 1;
+  opened.onopen?.();
+  opened.close();
+  await settle();
+  const answered = sockets[sockets.length - 1];
+  expect(answered.protocols).toEqual(["ticket.from-server"]);
+  // A frame from the new shard: the ticket function takes over.
+  answered.readyState = 1;
+  answered.onopen?.();
+  answered.onmessage?.({ data: jsonFrame(1, 2, { zone: "east" }) });
+  answered.close();
+  await settle();
+  expect(sockets[sockets.length - 1].protocols).toEqual(["ticket.own-east"]);
+  client.close();
+});
+
+test("a fixed ticket names the first shard and is not sent after a transfer", async () => {
+  const client = connectShard("west", { subscriberId: "p1", baseUrl: "h", ticket: "for-west" });
+  await settle();
+  const first = sockets[sockets.length - 1];
+  expect(first.protocols).toEqual(["ticket.for-west"]);
+  first.readyState = 1;
+  first.onopen?.();
+  first.onmessage?.({ data: jsonFrame(4, 1, { shard: "east", ticket: "for-east" }) });
+  first.close();
+  await settle();
+  const second = sockets[sockets.length - 1];
+  second.readyState = 1;
+  second.onopen?.();
+  second.close();
+  await settle();
+  expect(sockets[sockets.length - 1].protocols).toEqual(["ticket.for-east"]);
+  client.close();
+});
+
+/** A ticket shaped like the server's, expiring at `exp` (Unix seconds). */
+function ticketWithExp(exp: number): string {
+  const payload = btoa(JSON.stringify({ shard: "east", sid: "p1", exp }))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `v1.${payload}.sig`;
+}
+
+test("ticketExpired reads the ticket's exp", () => {
+  const now = 1_000_000_000_000;
+  expect(ticketExpired(ticketWithExp(now / 1000 + 600), now)).toBe(false);
+  expect(ticketExpired(ticketWithExp(now / 1000 - 1), now)).toBe(true);
+  // Within the margin counts as expired.
+  expect(ticketExpired(ticketWithExp(now / 1000 + 2), now)).toBe(true);
+  expect(ticketExpired("not-a-ticket", now)).toBe(false);
+});
+
+test("an expired transfer ticket gives way to the ticket function", async () => {
+  const client = connectShard("west", {
+    subscriberId: "p1",
+    baseUrl: "h",
+    ticket: (shard) => `own-${shard}`,
+  });
+  await settle();
+  const first = sockets[sockets.length - 1];
+  first.readyState = 1;
+  first.onopen?.();
+  const stale = ticketWithExp(Math.floor(Date.now() / 1000) - 60);
+  first.onmessage?.({ data: jsonFrame(4, 1, { shard: "east", ticket: stale }) });
+  first.close();
+  await settle();
+  expect(sockets[sockets.length - 1].protocols).toEqual(["ticket.own-east"]);
+  client.close();
+});
+
+test("an expired transfer ticket with a fixed ticket for another shard stops with an error", async () => {
+  const client = connectShard("west", { subscriberId: "p1", baseUrl: "h", ticket: "for-west" });
+  const errors: string[] = [];
+  client.onError((e) => errors.push(e.message));
+  await settle();
+  const first = sockets[sockets.length - 1];
+  first.readyState = 1;
+  first.onopen?.();
+  const stale = ticketWithExp(Math.floor(Date.now() / 1000) - 60);
+  first.onmessage?.({ data: jsonFrame(4, 1, { shard: "east", ticket: stale }) });
+  const before = sockets.length;
+  first.close();
+  await settle();
+  expect(sockets.length).toBe(before);
+  expect(errors).toEqual([
+    "the ticket for shard east expired before the client reconnected; pass a ticket function to get new ones",
+  ]);
+  client.close();
+});
+
+test("the same shard on another machine: reconnect at once, no transfer reported", async () => {
+  const client = connectShard("west", { subscriberId: "p1", baseUrl: "h", ticket: "for-west" });
+  const moves: string[] = [];
+  client.onTransfer((to) => moves.push(to));
+  await settle();
+  const first = sockets[sockets.length - 1];
+  first.readyState = 1;
+  first.onopen?.();
+  first.onmessage?.({ data: jsonFrame(4, 7, { shard: "west", ticket: "fresh-west" }) });
+  first.close();
+  await settle();
+  const second = sockets[sockets.length - 1];
+  expect(second.url).toContain("shard=west");
+  expect(second.protocols).toEqual(["ticket.fresh-west"]);
+  expect(delays[delays.length - 1]).toBe(0);
+  expect(moves).toEqual([]);
+  expect(client.shardId).toBe("west");
+  client.close();
+});

package/src/connection.ts

@@ -16,6 +16,7 @@ import {
   parseShardFrame,
   type ShardInputRejection,
   type ShardPayloadDecoder,
+  type ShardTransferNotice,
 } from "./wire";
 
 export interface ShardConnectOptions {
@@ -34,9 +35,10 @@ export interface ShardConnectOptions {
    * authorization hooks.
    *
    * Tickets expire. Pass a function to get a new one for each connection
-   * attempt, so a reconnect after the expiry still gets in.
+   * attempt, so a reconnect after the expiry still gets in. It receives the
+   * shard the client is connecting to, which changes after a transfer.
    */
-  ticket?: string | (() => string | Promise<string>);
+  ticket?: string | ((shardId: string) => string | Promise<string>);
   /** Host (and port) of the Pylon server. Defaults to `window.location.host`. */
   baseUrl?: string;
   /**
@@ -44,7 +46,10 @@ export interface ShardConnectOptions {
    * port (the dedicated port is the HTTP port + 3, e.g. 4324).
    */
   wsPort?: number;
-  /** Explicit WebSocket URL. Overrides baseUrl/wsPort. */
+  /**
+   * Explicit WebSocket URL. Overrides baseUrl/wsPort. After a transfer its
+   * `shard` query parameter is replaced with the new shard.
+   */
   wsUrl?: string;
   /** Reconnect on unexpected close (default: true). */
   autoReconnect?: boolean;
@@ -66,6 +71,16 @@ export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
   onSnapshot: (fn: (snapshot: TSnapshot, tick: number, ack: number) => void) => void;
   /** Called when the shard refuses an input (see `ShardInputRejection.code`). */
   onInputRejected: (fn: (rejection: ShardInputRejection) => void) => void;
+  /**
+   * Called when the server moved this subscriber to another shard (a zone
+   * line, a dungeon). The client reconnects there on its own, with the
+   * ticket the server sent; `shardId` changes before the handlers run.
+   * When the shard itself moves to another machine (a deploy), the client
+   * reconnects the same way, and these handlers are not called.
+   */
+  onTransfer: (fn: (shardId: string, from: string) => void) => void;
+  /** The shard the client is connected (or connecting) to. */
+  readonly shardId: string;
   /**
    * For a shard that replicates entities: called after each frame is
    * applied to `entities`, with what it changed.
@@ -103,6 +118,25 @@ export interface ShardClient<TSnapshot = unknown, TInput = unknown> {
   readonly connected: boolean;
 }
 
+/**
+ * True when a shard ticket (`v1.<payload>.<signature>`, the payload
+ * base64url JSON with `exp` in Unix seconds) expires within `marginSecs`.
+ * A ticket that does not parse counts as not expired: the server decides.
+ */
+export function ticketExpired(ticket: string, nowMs = Date.now(), marginSecs = 5): boolean {
+  const payload = ticket.split(".")[1];
+  if (!payload) return false;
+  try {
+    const b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const json = JSON.parse(atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "="))) as {
+      exp?: unknown;
+    };
+    return typeof json.exp === "number" && json.exp * 1000 <= nowMs + marginSecs * 1000;
+  } catch {
+    return false;
+  }
+}
+
 /** Input send times kept for the round-trip estimate. */
 const MAX_TIMED = 256;
 
@@ -115,11 +149,17 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
   options: ShardConnectOptions,
 ): ShardClient<TSnapshot, TInput> {
   const now = options.now ?? (() => performance.now());
+  let currentShard = shardId;
+  // The ticket a transfer frame carried. Used until the new shard sends a
+  // frame (then a ticket function takes over), and for good with a fixed
+  // `ticket`, which names the old shard.
+  let transferTicket: string | null = null;
   let ws: WebSocket | null = null;
   let clientSeq = 0;
   let closed = false;
   let connected = false;
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let transferring = false;
   let backoff = options.reconnectBackoffMs ?? 500;
   // The shard's codec, learned from the first frame. Until then inputs go
   // as JSON text, which every shard accepts.
@@ -133,6 +173,7 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
 
   const snapshotHandlers: Array<(s: TSnapshot, t: number, ack: number) => void> = [];
   const rejectionHandlers: Array<(r: ShardInputRejection) => void> = [];
+  const transferHandlers: Array<(shard: string, from: string) => void> = [];
   const replicationHandlers: Array<
     (entities: EntityTable, summary: ReplicationSummary, tick: number, ack: number) => void
   > = [];
@@ -146,13 +187,18 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
   };
 
   const buildWsUrl = (): string => {
-    if (options.wsUrl) return options.wsUrl;
+    if (options.wsUrl) {
+      if (currentShard === shardId) return options.wsUrl;
+      const url = new URL(options.wsUrl);
+      url.searchParams.set("shard", currentShard);
+      return url.toString();
+    }
     const proto =
       typeof window !== "undefined" && window.location.protocol === "https:" ? "wss" : "ws";
     // Only shard id + subscriber id land in the URL: routing metadata, not
     // credentials.
     const params = new URLSearchParams({
-      shard: shardId,
+      shard: currentShard,
       sid: options.subscriberId,
       v: String(SHARD_PROTOCOL_VERSION),
     });
@@ -188,13 +234,32 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
   const connect = () => {
     if (closed) return;
     const source = options.ticket;
+    // A transfer's ticket that expired before the client got through: a
+    // ticket function gives a new one; a fixed ticket still works for the
+    // shard it names.
+    if (transferTicket !== null && ticketExpired(transferTicket)) {
+      transferTicket = null;
+      if (typeof source !== "function" && currentShard !== shardId) {
+        dispatchError(
+          new Error(
+            `the ticket for shard ${currentShard} expired before the client reconnected; pass a ticket function to get new ones`,
+          ),
+        );
+        closed = true;
+        return;
+      }
+    }
+    if (transferTicket !== null) {
+      open(transferTicket);
+      return;
+    }
     if (typeof source !== "function") {
       open(source);
       return;
     }
     let ticket: string | Promise<string>;
     try {
-      ticket = source();
+      ticket = source(currentShard);
     } catch (e) {
       dispatchError(e instanceof Error ? e : new Error(String(e)));
       scheduleReconnect();
@@ -243,6 +308,30 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
       const at = now();
       try {
         const frame = parseShardFrame(event.data);
+        if (frame.kind === ShardFrameKind.Transfer) {
+          const notice = decodeShardPayload(frame.codec, frame.payload) as ShardTransferNotice;
+          const from = currentShard;
+          currentShard = notice.shard;
+          transferTicket = notice.ticket;
+          // A new shard, or this one started on another machine (a deploy):
+          // its ticks, acks, and entities start over.
+          clock.reset();
+          entities.clear();
+          lastTick = -1;
+          lastAck = 0;
+          sentAt.clear();
+          codec = null;
+          backoff = options.reconnectBackoffMs ?? 500;
+          // The same shard on another machine is not a move for the app.
+          if (currentShard !== from) {
+            for (const h of transferHandlers) h(currentShard, from);
+          }
+          // The server closes this connection; reconnect at once.
+          transferring = true;
+          return;
+        }
+        // The new shard answered: a ticket function gives the next tickets.
+        if (typeof options.ticket === "function") transferTicket = null;
         if (frame.kind === ShardFrameKind.Replication || frame.kind === ShardFrameKind.Snapshot) {
           // Only the per-tick frames: a rejection can go out before its
           // tick's frame is built, and would make the clock run early.
@@ -287,12 +376,17 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     };
 
     ws.onerror = () => {
-      dispatchError(new Error(`WebSocket error connecting to shard ${shardId}`));
+      dispatchError(new Error(`WebSocket error connecting to shard ${currentShard}`));
     };
 
     ws.onclose = () => {
       connected = false;
       for (const h of closeHandlers) h();
+      if (transferring && !closed) {
+        transferring = false;
+        reconnectTimer = setTimeout(connect, 0);
+        return;
+      }
       scheduleReconnect();
     };
   };
@@ -303,6 +397,9 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     get connected() {
       return connected;
     },
+    get shardId() {
+      return currentShard;
+    },
     get entities() {
       return entities;
     },
@@ -324,6 +421,9 @@ export function connectShard<TSnapshot = unknown, TInput = unknown>(
     onInputRejected(fn) {
       rejectionHandlers.push(fn);
     },
+    onTransfer(fn) {
+      transferHandlers.push(fn);
+    },
     onReplication(fn) {
       replicationHandlers.push(fn);
     },

package/src/game.ts

@@ -80,6 +80,8 @@ export interface ShardGame<TInput = unknown> {
     fn: (entities: EntityTable, summary: ReplicationSummary, tick: number, ack: number) => void,
   ): void;
   onInputRejected(fn: (rejection: ShardInputRejection) => void): void;
+  /** The server moved this player to another shard; see `ShardClient.onTransfer`. */
+  onTransfer(fn: (shardId: string, from: string) => void): void;
   onOpen(fn: () => void): void;
   onClose(fn: () => void): void;
   onError(fn: (err: Error) => void): void;
@@ -104,6 +106,8 @@ export function connectShardGame<TInput = unknown>(
   connection.onOpen(() => {
     for (const p of predictors) p.reset();
   });
+  // Another shard: its entities and ticks start over.
+  connection.onTransfer(() => interpolator.clear());
 
   return {
     connection,
@@ -153,6 +157,7 @@ export function connectShardGame<TInput = unknown>(
     },
     onReplication: (fn) => connection.onReplication(fn),
     onInputRejected: (fn) => connection.onInputRejected(fn),
+    onTransfer: (fn) => connection.onTransfer(fn),
     onOpen: (fn) => connection.onOpen(fn),
     onClose: (fn) => connection.onClose(fn),
     onError: (fn) => connection.onError(fn),

package/src/shard-data.e2e.test.ts

@@ -0,0 +1,331 @@
+// End-to-end: shards and the app's data (examples/shard-arena's zone, on
+// `pylon start` processes that share one Postgres).
+//
+// - A zone loads a player's character when the player joins, grants an item
+//   through a mutation that runs once per key, and writes x back.
+// - A mutation's `ctx.shards.send` reaches the zone after the commit, and
+//   not at all when it rolls back.
+// - A machine is killed while a grant runs, and another right after a grant
+//   commits. Another machine starts the zone from its saved state, the zone
+//   sends the grant again under the same key, and the item exists once.
+//
+// Runs only when PYLON_SHARD_DATA_E2E is "<host:port of A>[,<host:port of
+// F>,<host:port of G>]" and PYLON_SHARD_ADMIN_TOKEN is the machines' admin
+// token. The kill test also needs F and G and PYLON_SHARD_DATA_KILL, "<pid
+// of F>,<pid of G>"; machines F and G have PYLON_REPLICA_ID f and g.
+// tools/smoke-shard-cluster.sh runs both tests on Postgres, and
+// tools/smoke-wasm-shard.sh the first on SQLite.
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./connection";
+
+const [hostA, hostF, hostG] = (process.env.PYLON_SHARD_DATA_E2E ?? "").split(
+  ",",
+);
+const [pidF, pidG] = (process.env.PYLON_SHARD_DATA_KILL ?? "")
+  .split(",")
+  .map(Number);
+const adminToken = process.env.PYLON_SHARD_ADMIN_TOKEN ?? "";
+const oneMachine = Boolean(hostA && adminToken);
+const killable = Boolean(oneMachine && hostF && hostG && pidF && pidG);
+
+interface Player {
+  x: number;
+  hp: number;
+  loaded: boolean;
+  character: string;
+  /** Item names by row id. */
+  items: Record<string, string>;
+}
+
+interface Zone {
+  zone: string;
+  players: Record<string, Player>;
+  /** Grant results applied to grants restored from a save. */
+  replayed: number;
+}
+
+type Joined = { subscriberId: string; ticket: string; machine?: string };
+
+async function guest(host: string): Promise<string> {
+  const res = await fetch(`http://${host}/api/auth/guest`, { method: "POST" });
+  expect(res.ok).toBe(true);
+  return ((await res.json()) as { token: string }).token;
+}
+
+async function call<T>(
+  host: string,
+  token: string,
+  fn: string,
+  args: unknown,
+): Promise<T> {
+  const res = await fetch(`http://${host}/api/fn/${fn}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(args),
+  });
+  const text = await res.text();
+  if (res.status !== 200)
+    throw new Error(`${fn} on ${host}: ${res.status} ${text}`);
+  return JSON.parse(text) as T;
+}
+
+/** Rows of `entity`, read with the admin token. */
+async function rows(entity: string): Promise<Record<string, unknown>[]> {
+  const res = await fetch(`http://${hostA}/api/entities/${entity}?limit=1000`, {
+    headers: { authorization: `Bearer ${adminToken}` },
+  });
+  const text = await res.text();
+  if (res.status !== 200)
+    throw new Error(`list ${entity}: ${res.status} ${text}`);
+  const body = JSON.parse(text) as
+    Record<string, unknown>[] | { data: Record<string, unknown>[] };
+  return Array.isArray(body) ? body : body.data;
+}
+
+async function itemsOf(character: string): Promise<string[]> {
+  return (await rows("Item"))
+    .filter((i) => i.characterId === character)
+    .map((i) => String(i.name));
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check every `every` ms until `check` gives a value. A check that calls
+ * the server uses [`HTTP_POLL_MS`]: at 50 ms, one client reaches the
+ * function rate limit, and every later check is refused.
+ */
+async function waitFor<T>(
+  what: string,
+  check: () => Promise<T | undefined> | T | undefined,
+  ms: number,
+  every = 50,
+): Promise<T> {
+  const start = Date.now();
+  for (;;) {
+    const v = await check();
+    if (v !== undefined) return v;
+    if (Date.now() - start > ms)
+      throw new Error(`timed out waiting for ${what}`);
+    await sleep(every);
+  }
+}
+
+const HTTP_POLL_MS = 500;
+
+/** Join zone `zone` through `host` as a new guest and wait for the character. */
+async function joinPlayer(host: string, zone: string, machine?: string, params?: object) {
+  const token = await guest(host);
+  const joined = await call<Joined>(host, token, "joinZone", { zone, machine, params });
+  let snapshot: Zone | undefined;
+  const client = connectShard<Zone, unknown>(zone, {
+    subscriberId: joined.subscriberId,
+    baseUrl: host,
+    ticket: async (shard) =>
+      (await call<Joined>(host, token, "joinZone", { zone: shard })).ticket,
+  });
+  client.onSnapshot((s) => (snapshot = s));
+  await waitFor(
+    "the first snapshot",
+    () => (snapshot ? true : undefined),
+    10_000,
+  );
+  client.send("join");
+  const me = () => snapshot?.players[joined.subscriberId];
+  await waitFor(
+    "the character to load",
+    () => (me()?.loaded ? true : undefined),
+    10_000,
+  );
+  return {
+    token,
+    sid: joined.subscriberId,
+    client,
+    me,
+    machine: joined.machine,
+  };
+}
+
+/** The machine the directory places `zone` on (joinZone reads it, and
+ *  starts nothing for a zone that has a placement). */
+async function machineOf(token: string, zone: string): Promise<string | undefined> {
+  // While the dead machine still holds the placement, the call fails.
+  return call<Joined>(hostA, token, "joinZone", { zone }).then(
+    (j) => j.machine,
+    () => undefined,
+  );
+}
+
+test.skipIf(!oneMachine)(
+  "a zone loads a character, grants an item once, writes x back, and takes a GM's heal after the commit",
+  async () => {
+    const zone = `data-${Math.random().toString(36).slice(2, 8)}`;
+    const p = await joinPlayer(hostA, zone);
+    const character = p.me()!.character;
+    expect(character).toMatch(/^[0-9a-f]{40}$/);
+
+    p.client.send({ loot: { item: "sword" } });
+    await waitFor(
+      "the sword",
+      () => (Object.values(p.me()?.items ?? {}).includes("sword") ? true : undefined),
+      10_000,
+    );
+    expect(await itemsOf(character)).toEqual(["sword"]);
+
+    // x is written back within the flush interval (2 s).
+    p.client.send({ move: { dx: 5 } });
+    await waitFor(
+      "x in the Character row",
+      async () =>
+        (await rows("Character")).find((c) => c.id === character)?.x === 5
+          ? true
+          : undefined,
+      10_000,
+      HTTP_POLL_MS,
+    );
+
+    // A player cannot heal; the zone refuses a heal input from a player too.
+    const refused = await call(hostA, p.token, "gmHeal", {
+      zone,
+      userId: p.sid,
+      hp: 50,
+    }).catch((e) => e);
+    expect(String(refused)).toMatch(/AUTH_REQUIRED|FORBIDDEN/);
+    p.client.send({ heal: { who: p.sid, hp: 50 } });
+
+    await call(hostA, adminToken, "gmHeal", { zone, userId: p.sid, hp: 7 });
+    await waitFor(
+      "the heal",
+      () => (p.me()?.hp === 107 ? true : undefined),
+      10_000,
+    );
+
+    // Rolled back: the zone never gets it, and its log row is gone too.
+    const rolledBack = await call(hostA, adminToken, "gmHeal", {
+      zone,
+      userId: p.sid,
+      hp: 1000,
+      fail: true,
+    }).catch((e) => e);
+    expect(String(rolledBack)).toMatch(/GM_TEST_ROLLBACK/);
+    await sleep(1000);
+    expect(p.me()?.hp).toBe(107);
+    expect(
+      (await rows("GmAction")).filter((g) => g.zone === zone),
+    ).toHaveLength(1);
+    p.client.close();
+  },
+  60_000,
+);
+
+test.skipIf(!killable)(
+  "a machine killed during a grant, or right after its commit: the item exists once",
+  async () => {
+    const run = Math.random().toString(36).slice(2, 8);
+
+    // During: the mutation holds its transaction open for 4 s, and F dies
+    // in the middle (after the zone saved the grant, every 1 s).
+    const during = `grant-during-${run}`;
+    const pf = await joinPlayer(hostF, during, "f");
+    expect(pf.machine).toBe("f");
+    const cf = pf.me()!.character;
+    pf.client.send({ loot: { item: "relic", delay_ms: 4000 } });
+    await sleep(2000);
+    expect(await itemsOf(cf)).toEqual([]);
+    process.kill(pidF, "SIGKILL");
+
+    // After: the grant commits, and G dies after a save that still holds
+    // the grant as sent (the zone keeps grant results until `release`), so
+    // the zone that starts elsewhere must replay the stored result.
+    const after = `grant-after-${run}`;
+    const pg = await joinPlayer(hostG, after, "g", { hold_results: true });
+    expect(pg.machine).toBe("g");
+    const cg = pg.me()!.character;
+    pg.client.send({ loot: { item: "crown" } });
+    await waitFor(
+      "the crown's row",
+      async () => ((await itemsOf(cg)).length > 0 ? true : undefined),
+      10_000,
+      HTTP_POLL_MS,
+    );
+    // Saves every 1 s: at least one after the commit, with the grant.
+    await sleep(2500);
+    process.kill(pidG, "SIGKILL");
+
+    const watcherToken = await guest(hostA);
+    for (const [zone, character, item] of [
+      [during, cf, "relic"],
+      [after, cg, "crown"],
+    ]) {
+      await waitFor(
+        `${zone} on another machine`,
+        async () => {
+          const m = await machineOf(watcherToken, zone);
+          return m && m !== "f" && m !== "g" ? m : undefined;
+        },
+        60_000,
+        HTTP_POLL_MS,
+      );
+      await waitFor(
+        `the ${item}'s row`,
+        async () => ((await itemsOf(character)).length > 0 ? true : undefined),
+        20_000,
+        HTTP_POLL_MS,
+      );
+      // Time for any second grant to land.
+      await sleep(3000);
+      expect(await itemsOf(character)).toEqual([item]);
+    }
+    pf.client.close();
+    pg.client.close();
+
+    // The restarted zones show each item once, after the grant's result;
+    // the second one replayed the stored result of its committed grant.
+    await expectShown(during, pf.sid, "relic", false);
+    await expectShown(after, pg.sid, "crown", true);
+  },
+  180_000,
+);
+
+/**
+ * Watch `zone` as a new guest until player `sid` shows `item`, once. With
+ * `replay`, release the zone's held grant results until one restored from
+ * its save was applied.
+ */
+async function expectShown(zone: string, sid: string, item: string, replay: boolean) {
+  const token = await guest(hostA);
+  const t = await call<Joined>(hostA, token, "joinZone", { zone });
+  let snapshot: Zone | undefined;
+  const watcher = connectShard<Zone, unknown>(zone, {
+    subscriberId: t.subscriberId,
+    baseUrl: hostA,
+    ticket: async (shard) =>
+      (await call<Joined>(hostA, token, "joinZone", { zone: shard })).ticket,
+  });
+  watcher.onSnapshot((s) => (snapshot = s));
+  await waitFor(
+    `the ${item} in ${zone}`,
+    () => (Object.values(snapshot?.players[sid]?.items ?? {}).includes(item) ? true : undefined),
+    20_000,
+  );
+  if (replay) {
+    await waitFor(
+      `the replayed grant in ${zone}`,
+      () => {
+        if (snapshot?.replayed === 1) return true;
+        watcher.send("release");
+        return undefined;
+      },
+      20_000,
+    );
+  }
+  expect(Object.values(snapshot!.players[sid].items)).toEqual([item]);
+  watcher.close();
+}

package/src/shard-drain.e2e.test.ts

@@ -0,0 +1,127 @@
+// End-to-end: a deploy does not disconnect players (issue #34). A zone runs
+// on machine D; a player there has hit points, a buff, and a position. D
+// gets SIGTERM, as in a rolling deploy: it hands the zone to another
+// machine with its state and tells the client, which reconnects at once.
+// The player sees no error and no transfer, and its state is the same.
+//
+// Runs only when PYLON_SHARD_DRAIN_E2E is "<host:port of A>,<host:port of
+// D>" and PYLON_SHARD_DRAIN_PID is D's pid (tools/smoke-shard-cluster.sh
+// sets both). Machine D has PYLON_REPLICA_ID d and saves shards only when
+// it stops (PYLON_SHARD_SAVE_SECS=3600).
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./connection";
+
+const [hostA, hostD] = (process.env.PYLON_SHARD_DRAIN_E2E ?? "").split(",");
+const pidD = Number(process.env.PYLON_SHARD_DRAIN_PID ?? "");
+
+interface Player {
+  x: number;
+  hp: number;
+  loaded: boolean;
+  buffs: Array<{ name: string; remaining_ms: number }>;
+}
+
+interface Zone {
+  zone: string;
+  players: Record<string, Player>;
+}
+
+type Joined = { subscriberId: string; ticket: string; machine?: string };
+
+async function guest(host: string): Promise<string> {
+  const res = await fetch(`http://${host}/api/auth/guest`, { method: "POST" });
+  expect(res.ok).toBe(true);
+  return ((await res.json()) as { token: string }).token;
+}
+
+async function call<T>(host: string, token: string, fn: string, args: unknown): Promise<T> {
+  const res = await fetch(`http://${host}/api/fn/${fn}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify(args),
+  });
+  const text = await res.text();
+  if (res.status !== 200) throw new Error(`${fn} on ${host}: ${res.status} ${text}`);
+  return JSON.parse(text) as T;
+}
+
+async function waitFor<T>(what: string, check: () => T | undefined, ms: number): Promise<T> {
+  const start = Date.now();
+  for (;;) {
+    const v = check();
+    if (v !== undefined) return v;
+    if (Date.now() - start > ms) throw new Error(`timed out waiting for ${what}`);
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+test.skipIf(!hostA || !hostD || !pidD)(
+  "a machine that shuts down hands its zone to another with the player's state, and the client follows with no error",
+  async () => {
+    const zone = `drain-${Math.random().toString(36).slice(2, 8)}`;
+    const token = await guest(hostA);
+    const joined = await call<Joined>(hostA, token, "joinZone", { zone, machine: "d" });
+    expect(joined.machine).toBe("d");
+    const me = joined.subscriberId;
+
+    let latest: Zone | undefined;
+    let opens = 0;
+    const errors: Error[] = [];
+    const transfers: string[] = [];
+    const client = connectShard<Zone, unknown>(zone, {
+      subscriberId: me,
+      baseUrl: hostA,
+      ticket: async (shard) => (await call<Joined>(hostA, token, "joinZone", { zone: shard })).ticket,
+    });
+    client.onSnapshot((s) => (latest = s));
+    client.onOpen(() => (opens += 1));
+    // A snapshot from before a reconnect says nothing about the new one.
+    client.onClose(() => (latest = undefined));
+    client.onError((e) => errors.push(e));
+    client.onTransfer((to) => transfers.push(to));
+    const mine = () => latest?.players[me];
+
+    await waitFor("the zone's first snapshot", () => latest, 10_000);
+    client.send("join");
+    await waitFor("the character to load", () => (mine()?.loaded ? true : undefined), 10_000);
+    client.send({ buff: { name: "haste", ms: 600_000 } });
+    client.send({ hit: { damage: 30 } });
+    client.send({ move: { dx: 3 } });
+    await waitFor(
+      "the player's state",
+      () => (mine()?.hp === 70 && mine()?.x === 3 && mine()?.buffs.length ? true : undefined),
+      10_000,
+    );
+    // D saves only at shutdown (PYLON_SHARD_SAVE_SECS is an hour there):
+    // the final save is what carries this state.
+
+    const openedBefore = opens;
+    const killedAt = Date.now();
+    process.kill(pidD, "SIGTERM");
+
+    // The client reconnects, to the zone on another machine.
+    await waitFor("the reconnect", () => (opens > openedBefore ? true : undefined), 15_000);
+    const after = await waitFor(
+      "the player in the moved zone",
+      () => (opens > openedBefore && mine()?.loaded ? mine() : undefined),
+      15_000,
+    );
+    expect(Date.now() - killedAt).toBeLessThan(10_000);
+    expect(after.hp).toBe(70);
+    expect(after.x).toBe(3);
+    expect(after.buffs.map((b) => b.name)).toEqual(["haste"]);
+    expect(errors).toEqual([]);
+    expect(transfers).toEqual([]);
+    expect(client.shardId).toBe(zone);
+    const now = await call<Joined>(hostA, token, "joinZone", { zone });
+    expect(now.machine).not.toBe("d");
+
+    // Inputs work on the new machine.
+    client.send({ hit: { damage: 1 } });
+    await waitFor("an input on the new machine", () => (mine()?.hp === 69 ? true : undefined), 10_000);
+    client.close();
+  },
+  60_000,
+);

package/src/shard-messages.e2e.test.ts

@@ -0,0 +1,116 @@
+// End-to-end: a message from a shard on one machine reaches a shard on
+// another (examples/shard-arena, two `pylon start` processes on one
+// Postgres, no cluster bus: the machines call each other).
+//
+// Runs only when PYLON_SHARD_MESSAGES_E2E is "<host:port of A>,<host:port of
+// B>" and PYLON_SHARD_ADMIN_TOKEN is the machines' admin token
+// (tools/smoke-shard-cluster.sh sets both).
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./connection";
+
+const [hostA, hostB] = (process.env.PYLON_SHARD_MESSAGES_E2E ?? "").split(",");
+const adminToken = process.env.PYLON_SHARD_ADMIN_TOKEN ?? "";
+
+interface Zone {
+  zone: string;
+  heard: string[];
+}
+
+async function guest(host: string): Promise<string> {
+  const res = await fetch(`http://${host}/api/auth/guest`, { method: "POST" });
+  expect(res.ok).toBe(true);
+  return ((await res.json()) as { token: string }).token;
+}
+
+async function call<T>(host: string, token: string, fn: string, args: unknown): Promise<T> {
+  const res = await fetch(`http://${host}/api/fn/${fn}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify(args),
+  });
+  const text = await res.text();
+  if (res.status !== 200) throw new Error(`${fn} on ${host}: ${res.status} ${text}`);
+  return JSON.parse(text) as T;
+}
+
+function waitFor<T>(what: string, check: () => T | undefined, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const timer = setInterval(() => {
+      const v = check();
+      if (v !== undefined) {
+        clearInterval(timer);
+        resolve(v);
+      } else if (Date.now() - start > ms) {
+        clearInterval(timer);
+        reject(new Error(`timed out waiting for ${what}`));
+      }
+    }, 25);
+  });
+}
+
+test.skipIf(!hostA || !hostB || !adminToken)(
+  "a message from a shard on one machine reaches a shard on another",
+  async () => {
+    const run = Math.random().toString(36).slice(2, 8);
+    const [west, east] = [`msg-west-${run}`, `msg-east-${run}`];
+    type Joined = { subscriberId: string; ticket: string; machine?: string };
+    const shouter = await guest(hostA);
+    const watcher = await guest(hostB);
+    const w = await call<Joined>(hostA, shouter, "joinZone", { zone: west, machine: "a" });
+    expect(w.machine).toBe("a");
+    const e = await call<Joined>(hostB, watcher, "joinZone", {
+      zone: east,
+      machine: "b",
+      params: { group: `realm-${run}` },
+    });
+    expect(e.machine).toBe("b");
+
+    let heard: string[] = [];
+    const eastClient = connectShard<Zone, unknown>(east, {
+      subscriberId: e.subscriberId,
+      baseUrl: hostB,
+      ticket: async (shard) => (await call<Joined>(hostB, watcher, "joinZone", { zone: shard })).ticket,
+    });
+    eastClient.onSnapshot((s) => (heard = s.heard));
+    await waitFor("east's first snapshot", () => (eastClient.tick >= 0 ? true : undefined), 10_000);
+
+    let westTick = -1;
+    const westClient = connectShard<Zone, unknown>(west, {
+      subscriberId: w.subscriberId,
+      baseUrl: hostA,
+      ticket: async (shard) => (await call<Joined>(hostA, shouter, "joinZone", { zone: shard })).ticket,
+    });
+    westClient.onSnapshot((_, tick) => (westTick = tick));
+    await waitFor("west's first snapshot", () => (westTick >= 0 ? true : undefined), 10_000);
+    westClient.send("join");
+    // To all zones, and to east's group.
+    westClient.send({ shout: { text: "the relic is taken" } });
+    westClient.send({ shout: { text: "to the realm", to: `group:realm-${run}` } });
+    const from = `${west}> ${w.subscriberId}`;
+    await waitFor(
+      "east hears both",
+      () =>
+        heard.includes(`${from}: the relic is taken`) && heard.includes(`${from}: to the realm`)
+          ? true
+          : undefined,
+      10_000,
+    );
+
+    // A server function on A announces to all: east, on B, hears it. A
+    // player (here a guest) may not announce.
+    const refused = await call(hostA, shouter, "announce", { text: "fake" }).catch((e) => e);
+    expect(String(refused)).toMatch(/AUTH_REQUIRED|FORBIDDEN/);
+    await call(hostA, adminToken, "announce", { text: "keep under attack" });
+    await waitFor(
+      "east hears the announcement",
+      () => (heard.includes(`> "keep under attack"`) ? true : undefined),
+      10_000,
+    );
+    westClient.close();
+    eastClient.close();
+  },
+  60_000,
+);

package/src/shard-transfer.e2e.test.ts

@@ -0,0 +1,163 @@
+// End-to-end: a player moves between shards on two machines
+// (examples/shard-arena, two `pylon start` processes on one Postgres), with
+// its hit points, buffs, and cooldowns. A move the target refuses leaves the
+// player in the source.
+//
+// Runs only when PYLON_SHARD_TRANSFER_E2E is "<host:port of A>,<host:port of
+// B>" (tools/smoke-shard-cluster.sh sets it).
+
+import { expect, test } from "bun:test";
+
+import { connectShard } from "./connection";
+import type { ShardInputRejection } from "./wire";
+
+const [hostA, hostB] = (process.env.PYLON_SHARD_TRANSFER_E2E ?? "").split(",");
+
+interface Player {
+  x: number;
+  hp: number;
+  buffs: Array<{ name: string; remaining_ms: number }>;
+  cooldowns: Record<string, number>;
+  loaded: boolean;
+}
+interface Zone {
+  zone: string;
+  players: Record<string, Player>;
+}
+
+async function guest(host: string): Promise<string> {
+  const res = await fetch(`http://${host}/api/auth/guest`, { method: "POST" });
+  expect(res.ok).toBe(true);
+  return ((await res.json()) as { token: string }).token;
+}
+
+async function call<T>(host: string, token: string, fn: string, args: unknown): Promise<T> {
+  const res = await fetch(`http://${host}/api/fn/${fn}`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+    body: JSON.stringify(args),
+  });
+  const text = await res.text();
+  if (res.status !== 200) {
+    const err = new Error(`${fn} on ${host}: ${res.status} ${text}`) as Error & { code?: string };
+    try {
+      err.code = (JSON.parse(text) as { error?: { code?: string } }).error?.code;
+    } catch {}
+    throw err;
+  }
+  return JSON.parse(text) as T;
+}
+
+function waitFor<T>(what: string, check: () => T | undefined, ms: number): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const timer = setInterval(() => {
+      const v = check();
+      if (v !== undefined) {
+        clearInterval(timer);
+        resolve(v);
+      } else if (Date.now() - start > ms) {
+        clearInterval(timer);
+        reject(new Error(`timed out waiting for ${what}`));
+      }
+    }, 25);
+  });
+}
+
+test.skipIf(!hostA || !hostB)(
+  "a player moves to a shard on another machine with its state, and a refused move leaves it",
+  async () => {
+    const run = Math.random().toString(36).slice(2, 8);
+    const [west, east, shut] = [`west-${run}`, `east-${run}`, `shut-${run}`];
+    const token = await guest(hostA);
+    type Joined = { subscriberId: string; ticket: string; machine?: string };
+    const first = await call<Joined>(hostA, token, "joinZone", { zone: west, machine: "a" });
+    expect(first.machine).toBe("a");
+    expect((await call<Joined>(hostA, token, "joinZone", { zone: east, machine: "b" })).machine).toBe("b");
+    const closed = { zone: shut, machine: "b", params: { closed: true } };
+    expect((await call<Joined>(hostA, token, "joinZone", closed)).machine).toBe("b");
+    const me = first.subscriberId;
+
+    let latest: Zone | undefined;
+    const moves: string[] = [];
+    const rejections: ShardInputRejection[] = [];
+    const client = connectShard<Zone, unknown>(west, {
+      subscriberId: me,
+      baseUrl: hostA,
+      reconnectBackoffMs: 250,
+      ticket: async (shard) => (await call<Joined>(hostA, token, "joinZone", { zone: shard })).ticket,
+    });
+    client.onSnapshot((snap) => (latest = snap));
+    client.onTransfer((to) => moves.push(to));
+    client.onInputRejected((r) => rejections.push(r));
+
+    await waitFor("a snapshot of the west zone", () => latest, 10_000);
+    client.send("join");
+    client.send({ buff: { name: "haste", ms: 120_000 } });
+    client.send({ cast: { ability: "fireball", cooldown_ms: 120_000 } });
+    client.send({ hit: { damage: 30 } });
+    const mine = () => latest?.players[me];
+    // x comes from the character row: the zone refuses a move before it loads.
+    await waitFor("the character to load", () => (mine()?.loaded ? true : undefined), 10_000);
+    client.send({ move: { dx: 2 } });
+    const before = await waitFor(
+      "the player's state in west",
+      () => (mine()?.hp === 70 && mine()?.x === 2 && mine()?.buffs.length ? mine() : undefined),
+      10_000,
+    );
+
+    // The closed zone refuses: the player stays in west, still connected.
+    const refused = await call(hostA, token, "moveZone", { from: west, to: shut }).catch((e) => e);
+    expect((refused as { code?: string }).code).toBe("SHARD_TRANSFER_REFUSED");
+    expect(client.shardId).toBe(west);
+    client.send({ hit: { damage: 1 } });
+    await waitFor("west still has the player", () => (mine()?.hp === 69 ? true : undefined), 10_000);
+
+    // Moved to east, on machine B: the client follows the transfer frame.
+    const done = await call<{ shard: string }>(hostA, token, "moveZone", { from: west, to: east });
+    expect(done.shard).toBe(east);
+    await waitFor("the transfer frame", () => (moves.length ? true : undefined), 10_000);
+    expect(moves).toEqual([east]);
+    expect(client.shardId).toBe(east);
+    const after = await waitFor(
+      "the player in east",
+      () => (latest?.zone === east ? mine() : undefined),
+      10_000,
+    );
+    expect(after.hp).toBe(69);
+    expect(after.x).toBe(2);
+    expect(after.buffs.map((b) => b.name)).toEqual(["haste"]);
+    const haste = (p: Player) => p.buffs[0].remaining_ms;
+    expect(haste(after)).toBeLessThanOrEqual(haste(before));
+    expect(haste(after)).toBeGreaterThan(haste(before) - 10_000);
+    expect(after.cooldowns.fireball).toBeLessThanOrEqual(before.cooldowns.fireball);
+    expect(after.cooldowns.fireball).toBeGreaterThan(before.cooldowns.fireball - 10_000);
+
+    // The cooldown came along: east refuses the cast.
+    client.send({ cast: { ability: "fireball", cooldown_ms: 1 } });
+    await waitFor(
+      "the cooldown refusal",
+      () => (rejections.some((r) => r.message.includes("cooling down")) ? true : undefined),
+      10_000,
+    );
+    // West no longer has the player: an observer there sees no entity for
+    // it, in the running zone.
+    const observerToken = await guest(hostA);
+    const observer = await call<Joined>(hostA, observerToken, "joinZone", { zone: west });
+    expect(observer.machine).toBe("a");
+    let westView: Zone | undefined;
+    const watcher = connectShard<Zone, unknown>(west, {
+      subscriberId: observer.subscriberId,
+      baseUrl: hostA,
+      ticket: async (shard) =>
+        (await call<Joined>(hostA, observerToken, "joinZone", { zone: shard })).ticket,
+    });
+    watcher.onSnapshot((snap) => (westView = snap));
+    await waitFor("a snapshot of west", () => westView, 10_000);
+    expect(westView!.zone).toBe(west);
+    expect(westView!.players[me]).toBeUndefined();
+    watcher.close();
+    client.close();
+  },
+  60_000,
+);

package/src/wire.ts

@@ -4,7 +4,8 @@
  * A client asks for it with `?v=2` on the shard WebSocket URL. Each server
  * message is a binary frame with an 18-byte header:
  *
- *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication
+ *   0   1  frame kind: 1 snapshot, 2 input rejected, 3 entity replication,
+ *            4 transfer (JSON `{ shard, ticket }`: the last frame; reconnect there)
  *   1   1  codec: 0 JSON, 1 MessagePack, 2 bincode, 3 custom, 4 replication
  *   2   8  tick (u64 big-endian)
  *   10  8  ack: highest client_seq the shard processed for this subscriber (0 = none)
@@ -24,8 +25,19 @@ export const ShardFrameKind = {
   InputRejected: 2,
   /** An entity replication frame: apply it to an `EntityTable`. */
   Replication: 3,
+  /**
+   * The subscriber moved to another shard (`ShardTransferNotice`, JSON). The
+   * last frame on the connection.
+   */
+  Transfer: 4,
 } as const;
 
+/** Where the subscriber went: connect to `shard` with `ticket`. */
+export interface ShardTransferNotice {
+  shard: string;
+  ticket: string;
+}
+
 export const ShardCodec = {
   Json: 0,
   MessagePack: 1,
@@ -46,7 +58,10 @@ export interface ShardFrame {
 /** Why an input did not take effect. */
 export interface ShardInputRejection {
   clientSeq: number | null;
-  /** `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`, or `apply_failed`. */
+  /**
+   * `unauthorized`, `rate_limited`, `queue_full`, `invalid`, `stopped`,
+   * `transferring`, or `apply_failed`.
+   */
   code: string;
   message: string;
 }