@flayerlabs/gamemode-gate 0.1.0

package/src/server.ts

@@ -0,0 +1,833 @@
+import Fastify, { type FastifyInstance, type FastifyReply, type FastifyRequest } from 'fastify';
+import websocket from '@fastify/websocket';
+import cors from '@fastify/cors';
+import type { Pool } from 'pg';
+import type { Command, GameModule, PlayerId } from '@flayerlabs/gamemode-spec';
+import { isRefusal } from '@flayerlabs/gamemode-spec';
+import type { PresenceState } from '@flayerlabs/gamemode-spec/live';
+import { isReactionId, LIVE_PROTOCOL_VERSION } from '@flayerlabs/gamemode-spec/live';
+import { Room } from './room.js';
+import { CLAIM_AUTHORIZATION_TTL_MS, Claims, isClaimAmount, isClaimRequestId } from './claims.js';
+import { NotSignedIn, Sessions } from './sessions.js';
+import type { Discovery, Launch, PoolKey } from './chain/discover.js';
+import type { Settlement } from './settlement.js';
+import { resolveEconomy } from './economy.js';
+import { encodeHookData } from './chain/signer.js';
+
+/**
+ * The gate's door.
+ *
+ * Deliberately small. Everything interesting already lives behind it — the room decides, the
+ * ledger and signer authorise — so this file is transport and nothing else. Any rule that appears
+ * here is a rule in the wrong place.
+ *
+ * Views are sent whole rather than as deltas. Whole snapshots stop being sensible somewhere in the
+ * low thousands of players in one room; deltas are the fix, and adding them before there is a room
+ * that size would be guessing at the shape of a problem nobody has.
+ */
+
+interface GateBaseOptions<Config, State, Event, Action, PublicView, PlayerView> {
+  pool: Pool;
+  game: GameModule<Config, State, Event, Action, PublicView, PlayerView>;
+  sessions: Sessions;
+  claims: Claims;
+  /** How many points a dollar buys. The only economic number anyone sets by hand. */
+  pointsPerDollar: number;
+  usdPerEth: number;
+  /** Verifies from the chain that a coin really is a game launch. */
+  discovery?: Discovery;
+  /** Keeps the ledger's view of spending level with the chain's. */
+  settlement?: Settlement;
+  /** How long charts and final spend reconciliation remain live after gameplay closes. */
+  settlementTailMs?: number;
+  /** Origins allowed to call this gate: the game's own, and nothing else. */
+  allowedOrigins: string[];
+  /**
+   * Decide whether a caller may open a session or spend a request, or refuse them.
+   *
+   * One optional seam rather than a bot layer, because the pieces of a bot layer are not
+   * game-neutral and this library is self-hosted. A human-verification vendor needs keys only the
+   * operator has; a request budget needs a cadence only the game knows — a quiz taking one answer
+   * every ten seconds and a shooter taking thirty a second cannot share a number; and a false
+   * refusal on a claim costs a player a purchase inside a window that will not come back.
+   *
+   * So the policy belongs to whoever runs the gate. What belongs here is the place to put it, and
+   * the guarantee it is consulted before a session is issued and before allowance is committed.
+   *
+   * Omitted, everything is admitted, which is what a laptop and a test want.
+   */
+  admit?: Admit;
+  /** The only cosmetic reaction IDs this game may broadcast. Omitted disables reactions. */
+  reactionIds?: readonly string[];
+}
+
+/** Resolve one immutable rules config after the launch has been verified. */
+export type VerifiedLaunch = Readonly<Omit<Launch, 'poolKey'>> & { readonly poolKey: Readonly<PoolKey> };
+export type ConfigForLaunch<Config> = (launch: VerifiedLaunch) => Promise<Config>;
+
+export type GateOptions<Config, State, Event, Action, PublicView, PlayerView> = GateBaseOptions<
+  Config,
+  State,
+  Event,
+  Action,
+  PublicView,
+  PlayerView
+> & {
+  /** A static serialisable config, or a factory resolved once after each launch is verified. */
+  config: Config | ConfigForLaunch<Config>;
+};
+
+/** Where an admission check is being made. Enough to tell a sign-in from a spend. */
+export interface AdmissionRequest {
+  /** `session` on sign-in, `action` on gameplay, `claim` when allowance is about to be committed. */
+  at: 'session' | 'action' | 'claim';
+  /** Null at `session`, because nobody has proved who they are yet. */
+  player: PlayerId | null;
+  roundId: string | null;
+  /** Straight from the socket, so a limiter can key on it. Absent behind some proxies. */
+  ip: string | null;
+  /** Opaque and operator-defined: a captcha solution, a device token, whatever was sent. */
+  evidence: unknown;
+}
+
+/**
+ * Allow, or refuse with a reason a player can be shown.
+ *
+ * The reason reaches the player, so write it for them: "too many tries, wait a minute", not a rule
+ * name or a score.
+ */
+export type Admission = { ok: true } | { ok: false; reason: string };
+
+export type Admit = (request: AdmissionRequest) => Admission | Promise<Admission>;
+
+const ADMIT_ALL: Admit = () => ({ ok: true });
+
+/** What the socket says, which is only the truth when nothing is proxying in front of the gate. */
+const ipOf = (request: FastifyRequest): string | null => request.ip || null;
+
+/** How often each open room is nudged so a deadline nobody is watching still fires. */
+const TICK_MS = 250;
+
+/**
+ * How often the chain is asked what has actually been spent.
+ *
+ * Far slower than the tick, because it is one read per player per pass. At the tick rate a busy
+ * round would start a new sweep every quarter second while the previous one was still running, and
+ * they would pile up until the endpoint rate-limited us.
+ */
+const RECONCILE_MS = 15_000;
+
+/** Promise queues bound application work; these limits bound bytes already handed to `ws`. */
+const MAX_QUEUED_COSMETIC_FRAMES = 64;
+const MAX_COSMETIC_BUFFERED_BYTES = 256 * 1_024;
+const MAX_AUTHORITATIVE_BUFFERED_BYTES = 1_024 * 1_024;
+/** A final snapshot is best effort. A stuck balance read must never keep a dead room connected. */
+const TERMINAL_DRAIN_DEADLINE_MS = 1_000;
+/** Reactions are also bounded across a whole room, not only per sending socket. */
+const MAX_ROOM_REACTIONS_PER_SECOND = 20;
+export const DEFAULT_SETTLEMENT_TAIL_MS = CLAIM_AUTHORIZATION_TTL_MS;
+
+type AdoptionResult<Config, State, Event, Action, PublicView, PlayerView> =
+  | { ok: true; room: Room<Config, State, Event, Action, PublicView, PlayerView>; created: boolean }
+  | { ok: false; status: 409 | 503; message: string };
+
+export function createGate<Config, State, Event, Action, PublicView, PlayerView>(
+  options: GateOptions<Config, State, Event, Action, PublicView, PlayerView>,
+): FastifyInstance {
+  const { pool, game, sessions, claims, discovery, settlement } = options;
+  const admit = options.admit ?? ADMIT_ALL;
+  // Rules config is persisted as JSON, so a function here can only be the documented factory.
+  const configIsFactory = typeof options.config === 'function';
+  const allowedReactions = new Set(options.reactionIds ?? []);
+  if ([...allowedReactions].some((id) => !isReactionId(id))) {
+    throw new RangeError('reactionIds must contain only valid reaction identifiers');
+  }
+  const settlementTailMs = options.settlementTailMs ?? DEFAULT_SETTLEMENT_TAIL_MS;
+  if (!Number.isSafeInteger(settlementTailMs) || settlementTailMs < CLAIM_AUTHORIZATION_TTL_MS) {
+    throw new RangeError(`settlementTailMs must be at least ${CLAIM_AUTHORIZATION_TTL_MS}`);
+  }
+  // A body limit costs nothing and is the cheapest protection against an endpoint that parses.
+  const app = Fastify({ logger: process.env.GATE_LOG === '1', bodyLimit: 64 * 1024 });
+  const rooms = new Map<string, Room<Config, State, Event, Action, PublicView, PlayerView>>();
+  type Watcher = {
+    viewer: PlayerId | null;
+    snapshot(): void;
+    frame(value: unknown): void;
+    close(code: number, reason: string, drain?: boolean): void;
+  };
+  const watchers = new Map<string, Set<Watcher>>();
+  const activePlayerSockets = new Map<string, Watcher>();
+  const cachedPresence = new Map<string, PresenceState>();
+  const roomReactionTimes = new Map<string, number[]>();
+  const adoptions = new Map<
+    string,
+    Promise<AdoptionResult<Config, State, Event, Action, PublicView, PlayerView>>
+  >();
+
+  const playerSocketKey = (id: string, player: PlayerId): string => `${id}:${player}`;
+
+  void app.register(cors, { origin: options.allowedOrigins });
+  void app.register(websocket, { options: { maxPayload: 1_024 } });
+
+  /** One Room per round in this process — the optimistic lock assumes a single writer. */
+  async function roomFor(id: string) {
+    const existing = rooms.get(id);
+    if (existing) return existing;
+    const loaded = await Room.load(pool, game, id);
+    // A durable row is history after its books close, not permission to resurrect an active
+    // ticker and market stream every time somebody refreshes an old coin page. It still gets one
+    // bounded catch-up through closesAt: a restart spanning the whole tail must not strand final
+    // wakes or awards merely because no process was alive to serve them.
+    if (loaded && Date.now() <= loaded.launch.booksCloseAt) {
+      rooms.set(id, loaded);
+    } else if (loaded) {
+      if (loaded.nextWakeAt() !== null) await loaded.tick(loaded.window.closesAt);
+      return null;
+    }
+    return loaded;
+  }
+
+  async function createAdoptedRoom(
+    launch: Launch,
+  ): Promise<AdoptionResult<Config, State, Event, Action, PublicView, PlayerView>> {
+    const existing = await roomFor(launch.poolId);
+    if (existing) return { ok: true, room: existing, created: false };
+
+    if (Date.now() >= launch.closesAt) {
+      return { ok: false, status: 409, message: 'this game has already ended' };
+    }
+
+    let config: Config;
+    try {
+      const verifiedLaunch: VerifiedLaunch = Object.freeze({
+        ...launch,
+        poolKey: Object.freeze({ ...launch.poolKey }),
+      });
+      config = configIsFactory
+        ? await (options.config as ConfigForLaunch<Config>)(verifiedLaunch)
+        : (options.config as Config);
+    } catch (error) {
+      app.log.error(error);
+      return { ok: false, status: 503, message: 'this game is still being prepared' };
+    }
+
+    // Config generation is allowed to take time, but it must not create a round whose on-chain
+    // permission has expired while the factory was working.
+    if (Date.now() >= launch.closesAt) {
+      return { ok: false, status: 409, message: 'this game has already ended' };
+    }
+
+    let maxPointsPerPlayer: number;
+    try {
+      maxPointsPerPlayer = game.rewardBounds(config).maxPointsPerPlayer;
+    } catch (error) {
+      app.log.error(error);
+      return { ok: false, status: 503, message: 'this game is still being prepared' };
+    }
+    const economy = resolveEconomy({
+      maxPointsPerPlayer,
+      walletCapWei: launch.walletCapWei,
+      pointsPerDollar: options.pointsPerDollar,
+      usdPerEth: options.usdPerEth,
+    });
+    if (!economy.ok) {
+      app.log.error(
+        `${launch.coinAddress}: ${economy.problem} (try ${economy.suggestedPointsPerDollar} points per dollar)`,
+      );
+      return { ok: false, status: 409, message: 'this game is not set up correctly yet' };
+    }
+
+    let room: Room<Config, State, Event, Action, PublicView, PlayerView>;
+    try {
+      room = await Room.create(pool, game, {
+        id: launch.poolId,
+        config,
+        seed: Number(BigInt(launch.poolId) % 2147483647n),
+        window: { opensAt: launch.opensAt, closesAt: launch.closesAt },
+        weiPerPoint: economy.economy.weiPerPoint,
+        walletCapWei: launch.walletCapWei,
+        poolId: launch.poolId,
+        booksCloseAt: launch.closesAt + settlementTailMs,
+        launch: {
+          coinAddress: launch.coinAddress,
+          name: launch.name,
+          symbol: launch.symbol,
+          imageUrl: launch.imageUrl ?? null,
+        },
+      });
+    } catch (error) {
+      app.log.error(error);
+      return { ok: false, status: 503, message: 'this game is still being prepared' };
+    }
+    rooms.set(launch.poolId, room);
+    return { ok: true, room, created: true };
+  }
+
+  function announce(id: string): void {
+    for (const watcher of watchers.get(id) ?? []) watcher.snapshot();
+  }
+
+  function announcePlayer(id: string, player: PlayerId): void {
+    for (const watcher of watchers.get(id) ?? []) {
+      if (watcher.viewer === player) watcher.snapshot();
+    }
+  }
+
+  function calculatePresence(id: string): PresenceState {
+    const connected = new Set(
+      [...(watchers.get(id) ?? [])].flatMap((watcher) =>
+        watcher.viewer && activePlayerSockets.get(playerSocketKey(id, watcher.viewer)) === watcher
+          ? [watcher.viewer]
+          : [],
+      ),
+    );
+    return { connectedCount: connected.size };
+  }
+
+  function presence(id: string): PresenceState {
+    const existing = cachedPresence.get(id);
+    if (existing) return existing;
+    const calculated = calculatePresence(id);
+    cachedPresence.set(id, calculated);
+    return calculated;
+  }
+
+  const invalidatePresence = (id: string): void => {
+    cachedPresence.delete(id);
+  };
+
+  /** The same for everyone, so it is built once rather than per socket. */
+  function announcePresence(id: string): void {
+    const frame = { v: LIVE_PROTOCOL_VERSION, type: 'presence', presence: presence(id) };
+    for (const watcher of watchers.get(id) ?? []) watcher.frame(frame);
+  }
+
+  const player = (request: FastifyRequest): PlayerId =>
+    sessions.verify((request.headers.authorization ?? '').replace(/^Bearer /, ''));
+
+  app.setErrorHandler((error, _request, reply: FastifyReply) => {
+    // Players see plain sentences. Codes and stack traces are for us, and a refusal that explains
+    // its own threshold is a refusal a cheater can calibrate against.
+    if (error instanceof NotSignedIn) return reply.code(401).send({ message: error.message });
+    app.log.error(error);
+    return reply.code(500).send({ message: 'something went wrong at our end, please try again' });
+  });
+
+  app.after(() => {
+  app.get('/health', () => ({ ok: true }));
+
+  app.post('/session/challenge', async (request) => {
+    const { address } = request.body as { address?: string };
+    if (typeof address !== 'string') throw new NotSignedIn('a wallet address is required');
+    return sessions.challenge(address);
+  });
+
+  app.post('/session', async (request, reply) => {
+    const { address, signature, nonce, evidence } = request.body as Record<string, string>;
+    if (!address || !signature || !nonce) throw new NotSignedIn('sign-in is missing something');
+
+    // Before the token exists, because a session is the thing worth rationing — everything after it
+    // is bounded by what the ledger will authorise.
+    const admission = await admit({ at: 'session', player: null, roundId: null, ip: ipOf(request), evidence });
+    if (!admission.ok) return reply.code(403).send({ message: admission.reason });
+
+    return { token: await sessions.signIn(address, signature as `0x${string}`, nonce) };
+  });
+
+  /**
+   * Open a room for a coin, if the chain says it qualifies.
+   *
+   * Unauthenticated on purpose. The permission is already on chain — a launch that wants a game
+   * names this gate's signer in its own parameters, which is public state the creator paid to write
+   * and nobody else can forge. So anyone may ask; the chain decides. An API key here would add a
+   * gate in front of a gate.
+   */
+  app.post('/rounds/adopt', async (request, reply) => {
+    if (!discovery) return reply.code(503).send({ message: 'this game is not open for new rounds' });
+
+    const { coin } = request.body as { coin?: string };
+    if (typeof coin !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(coin)) {
+      return reply.code(400).send({ message: 'that is not a coin address' });
+    }
+
+    const launch = await discovery.verify(coin.toLowerCase() as `0x${string}`);
+    if (!launch.ok) {
+      // Retryable and permanent are different answers and must reach the caller as different
+      // answers. Told "no" for a chain that had not caught up, a coin page caches it and shows a
+      // player nothing for the whole window.
+      return reply
+        .code(launch.retryable ? 503 : 404)
+        .send({ message: launch.retryable ? 'that game is still starting up' : 'that coin has no game' });
+    }
+
+    // A room per pool, so asking twice returns the same room rather than making a second one.
+    // Discovery caches its verdicts for as long as a window is open, so a coin page that reloads
+    // costs one map lookup rather than five chain reads.
+    const id = launch.poolId;
+    const existingFlight = adoptions.get(id);
+    const createdByThisRequest = existingFlight === undefined;
+    const flight = existingFlight ?? createAdoptedRoom(launch);
+    if (createdByThisRequest) {
+      adoptions.set(id, flight);
+      void flight.then(
+        () => adoptions.delete(id),
+        () => adoptions.delete(id),
+      );
+    }
+    const adopted = await flight;
+    if (!adopted.ok) return reply.code(adopted.status).send({ message: adopted.message });
+    return reply
+      .code(createdByThisRequest && adopted.created ? 201 : 200)
+      .send(adopted.room.launch);
+  });
+
+  app.get('/rounds/:id', async (request, reply) => {
+    const id = (request.params as { id: string }).id;
+    const room = await roomFor(id);
+    if (!room) return reply.code(404).send({ message: 'that game is not running' });
+    const before = room.sequence();
+    await room.tick(Date.now());
+    if (room.sequence() !== before) announce(id);
+    return { sequence: room.sequence(), view: room.publicView(), launch: room.launch };
+  });
+
+  app.post('/rounds/:id/join', async (request, reply) => {
+    const room = await roomFor((request.params as { id: string }).id);
+    if (!room) return reply.code(404).send({ message: 'that game is not running' });
+
+    const id = (request.params as { id: string }).id;
+    const before = room.sequence();
+    const result = await room.apply({
+      kind: 'join',
+      player: player(request),
+      // The platform supplies the randomness so a game never has to reach for any.
+      seed: Math.floor(Math.random() * 0x7fffffff),
+      at: Date.now(),
+    });
+    if (room.sequence() !== before) announce(id);
+    return isRefusal(result) ? reply.code(409).send({ message: 'you cannot join right now' }) : { joined: true };
+  });
+
+  app.post('/rounds/:id/actions', async (request, reply) => {
+    const id = (request.params as { id: string }).id;
+    const room = await roomFor(id);
+    if (!room) return reply.code(404).send({ message: 'that game is not running' });
+
+    // Identity first: parsing is the game's code, and running a stranger's parser for an
+    // unauthenticated caller is work anyone can ask for.
+    const who = player(request);
+    const admission = await admit({ at: 'action', player: who, roundId: id, ip: ipOf(request), evidence: undefined });
+    if (!admission.ok) return reply.code(403).send({ message: admission.reason });
+
+    const action = game.parseAction((request.body as { action?: unknown })?.action);
+    if (action === null) return reply.code(400).send({ message: 'that move was not understood' });
+
+    const before = room.sequence();
+    const result = await room.apply({ kind: 'action', player: who, action, at: Date.now() });
+    if (room.sequence() !== before) announce(id);
+    // The code goes to our logs; the player gets a sentence the client chooses.
+    return isRefusal(result) ? reply.code(409).send({ refuse: result.refuse }) : { accepted: true };
+  });
+
+  app.post('/rounds/:id/claim', async (request, reply) => {
+    const id = (request.params as { id: string }).id;
+    const who = player(request);
+    const { maxSpendWei, requestId } = request.body as { maxSpendWei?: string; requestId?: unknown };
+    let upTo: bigint;
+    try {
+      upTo = BigInt(maxSpendWei ?? '0');
+    } catch {
+      return reply.code(400).send({ message: 'that amount was not understood' });
+    }
+    if (!isClaimAmount(upTo)) return reply.code(400).send({ message: 'that amount was not understood' });
+    // Required, not defaulted. Minting an id here for a caller that omitted one makes every retry a
+    // fresh claim, which is precisely the double-hold idempotency exists to prevent — and it fails
+    // silently, for the one caller that needed it most. Nothing is live, so there is no old client
+    // to keep working.
+    if (!isClaimRequestId(requestId)) {
+      return reply.code(400).send({ message: 'that request was not understood' });
+    }
+
+    const admission = await admit({ at: 'claim', player: who, roundId: id, ip: ipOf(request), evidence: undefined });
+    if (!admission.ok) return reply.code(403).send({ message: admission.reason });
+
+    const authorised = await claims.authorise(id, who, upTo, requestId);
+    if (!authorised.ok) return reply.code(409).send({ refuse: authorised.refuse });
+
+    const { payload } = authorised;
+    if (rooms.has(id)) announcePlayer(id, who);
+    return {
+      // Strings, because these do not survive JSON as numbers.
+      buyer: payload.buyer,
+      poolId: payload.poolId,
+      deadline: payload.deadline.toString(),
+      maxSpendWei: payload.maxSpendWei.toString(),
+      nonce: payload.nonce.toString(),
+      signature: payload.signature,
+      signer: payload.signer,
+      // The embed passes this opaque value to the Flaunch buy call. Game code never reconstructs
+      // the ABI and therefore cannot accidentally sign or submit a different transaction shape.
+      hookData: encodeHookData(payload),
+    };
+  });
+
+  app.get('/rounds/:id/live', { websocket: true }, async (socket, request) => {
+    const id = (request.params as { id: string }).id;
+    const room = await roomFor(id);
+    if (!room) return socket.close(4404, 'that game is not running');
+
+    let viewer: PlayerId | null = null;
+    try {
+      // A browser cannot set headers on a WebSocket, so the token rides the query string here and
+      // ONLY here — on an ordinary request it would end up in every access log along the way.
+      viewer = sessions.verify((request.query as { token?: string })?.token);
+    } catch {
+      // Watching without signing in is allowed. Playing is not — actions go over HTTP, which
+      // requires a token, so a spectator socket can only ever receive.
+    }
+
+    let outbound = Promise.resolve();
+    let accepting = true;
+    let sendable = true;
+    let snapshotQueued = false;
+    let snapshotDirty = false;
+    let queuedCosmeticFrames = 0;
+    let terminalDrainTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const terminateSocket = (): void => {
+      accepting = false;
+      sendable = false;
+      if (socket.readyState !== socket.CLOSED) socket.terminate();
+    };
+
+    const write = (value: unknown, authoritative: boolean): void => {
+      if (!sendable || socket.readyState !== socket.OPEN) return;
+      const encoded = JSON.stringify(value);
+      const encodedBytes = Buffer.byteLength(encoded);
+      if (authoritative) {
+        // An authoritative frame cannot safely be dropped: reconnecting is how the client obtains
+        // a fresh whole snapshot after it falls too far behind. A snapshot larger than the entire
+        // allowance is unservable too, so terminate rather than allocate an unbounded transport
+        // queue; reconnect may recover once the game's whole view becomes smaller.
+        if (socket.bufferedAmount + encodedBytes > MAX_AUTHORITATIVE_BUFFERED_BYTES) {
+          terminateSocket();
+          return;
+        }
+      } else if (socket.bufferedAmount >= MAX_COSMETIC_BUFFERED_BYTES) {
+        return;
+      }
+
+      if (
+        !authoritative &&
+        socket.bufferedAmount + encodedBytes > MAX_COSMETIC_BUFFERED_BYTES
+      ) {
+        return;
+      }
+      socket.send(encoded);
+    };
+
+    const queue = (
+      make: () => unknown | Promise<unknown>,
+      authoritative: boolean,
+      settled?: () => void,
+      failed?: () => void,
+    ): boolean => {
+      if (!accepting) return false;
+      outbound = outbound
+        .then(async () => {
+          try {
+            if (!sendable) return;
+            const value = await make();
+            write(value, authoritative);
+          } finally {
+            settled?.();
+          }
+        })
+        .catch((error) => {
+          app.log.error(error);
+          failed?.();
+        });
+      return true;
+    };
+    const makeSnapshot = async () => {
+      // `now` is what every countdown in every game is drawn through, so a player with a wrong
+      // clock still sees the same round as everyone else.
+      // An authenticated read failure is not a zero balance. Let this snapshot fail so an already
+      // connected client retains its last authoritative value, and a first-time client gets a
+      // connection failure instead of being told its earned allowance vanished.
+      const balance = viewer
+        ? await claims.economyBalance(id, viewer)
+        : {
+            weiPerPoint: room.weiPerPoint,
+            earnedWei: 0n,
+            heldWei: 0n,
+            spentWei: 0n,
+            availableWei: 0n,
+            holdExpiresAt: null,
+          };
+      const economy = {
+        weiPerPoint: balance.weiPerPoint.toString(),
+        earnedWei: balance.earnedWei.toString(),
+        heldWei: balance.heldWei.toString(),
+        spentWei: balance.spentWei.toString(),
+        availableWei: balance.availableWei.toString(),
+        holdExpiresAt: balance.holdExpiresAt,
+      };
+      return {
+        v: LIVE_PROTOCOL_VERSION,
+        type: 'snapshot',
+        sequence: room.sequence(),
+        now: Date.now(),
+        view: room.publicView(),
+        you: viewer ? room.playerView(viewer) : null,
+        economy,
+        launch: room.launch,
+        presence: presence(id),
+      };
+    };
+    const watcher: Watcher = {
+      viewer,
+      frame: (value) => {
+        if (
+          !accepting ||
+          socket.bufferedAmount >= MAX_COSMETIC_BUFFERED_BYTES ||
+          queuedCosmeticFrames >= MAX_QUEUED_COSMETIC_FRAMES
+        ) {
+          return;
+        }
+        queuedCosmeticFrames += 1;
+        if (
+          !queue(
+            () => value,
+            false,
+            () => {
+              queuedCosmeticFrames -= 1;
+            },
+          )
+        ) {
+          queuedCosmeticFrames -= 1;
+        }
+      },
+      snapshot: () => {
+        if (!accepting) return;
+        if (snapshotQueued) {
+          snapshotDirty = true;
+          return;
+        }
+        snapshotQueued = true;
+        queue(
+          async () => {
+            try {
+              return await makeSnapshot();
+            } finally {
+              snapshotQueued = false;
+              if (snapshotDirty && accepting) {
+                snapshotDirty = false;
+                watcher.snapshot();
+              }
+            }
+          },
+          true,
+          undefined,
+          terminateSocket,
+        );
+      },
+      close: (code, reason, drain = false) => {
+        if (!accepting) return;
+        accepting = false;
+        if (!drain) {
+          sendable = false;
+          if (socket.readyState === socket.OPEN) socket.close(code, reason);
+          return;
+        }
+
+        // Do not put the deadline behind `outbound`: either an earlier snapshot or this final
+        // balance read may never settle. The timer owns eventual transport and map cleanup.
+        terminalDrainTimer = setTimeout(terminateSocket, TERMINAL_DRAIN_DEADLINE_MS);
+        terminalDrainTimer.unref();
+        outbound = outbound
+          .then(async () => {
+            try {
+              if (!sendable) return;
+              const value = await makeSnapshot();
+              write(value, true);
+            } catch (error) {
+              // A final balance read can fail during shutdown. Closing the socket is still
+              // mandatory: otherwise clients wait forever on a room the ticker has already ended.
+              app.log.error(error);
+            } finally {
+              if (sendable && socket.readyState === socket.OPEN) socket.close(code, reason);
+            }
+          })
+          .catch((error) => app.log.error(error));
+      },
+    };
+
+    const playerSocket = viewer ? playerSocketKey(id, viewer) : null;
+    if (playerSocket) {
+      const earlier = activePlayerSockets.get(playerSocket);
+      activePlayerSockets.set(playerSocket, watcher);
+      earlier?.close(4409, 'superseded');
+    }
+
+    const watching = watchers.get(id) ?? new Set<Watcher>();
+    watching.add(watcher);
+    watchers.set(id, watching);
+    if (viewer) invalidatePresence(id);
+
+    // Immediately, so a client renders from its first frame rather than waiting for something to
+    // happen — and this doubles as reconnect: a returning socket gets the whole current state.
+    watcher.snapshot();
+    // Spectators are deliberately absent from presence counts, so their churn must not fan a
+    // redundant frame out to every authenticated player in the room.
+    if (viewer) announcePresence(id);
+
+    const messageTimes: number[] = [];
+    const reactionTimes: number[] = [];
+    socket.on('message', (raw) => {
+      const text = String(raw);
+      if (!viewer) return socket.close(4401, 'sign in to interact');
+      // A superseded transport may remain physically open briefly. It no longer represents this
+      // player and cannot restore readiness or emit reactions while its close handshake finishes.
+      if (!playerSocket || activePlayerSockets.get(playerSocket) !== watcher) return;
+
+      const now = Date.now();
+      while (messageTimes[0] !== undefined && messageTimes[0] <= now - 1_000) messageTimes.shift();
+      if (messageTimes.length >= 20) return;
+      messageTimes.push(now);
+
+      let frame: { v?: unknown; type?: unknown; id?: unknown };
+      try {
+        frame = JSON.parse(text) as typeof frame;
+      } catch {
+        return;
+      }
+      if (frame.v !== LIVE_PROTOCOL_VERSION) return;
+
+      if (
+        frame.type === 'reaction' &&
+        typeof frame.id === 'string' &&
+        isReactionId(frame.id) &&
+        allowedReactions.has(frame.id)
+      ) {
+        while (reactionTimes[0] !== undefined && reactionTimes[0] <= now - 1_000) reactionTimes.shift();
+        const acrossRoom = roomReactionTimes.get(id) ?? [];
+        while (acrossRoom[0] !== undefined && acrossRoom[0] <= now - 1_000) acrossRoom.shift();
+        if (reactionTimes.length >= 5 || acrossRoom.length >= MAX_ROOM_REACTIONS_PER_SECOND) return;
+        reactionTimes.push(now);
+        acrossRoom.push(now);
+        roomReactionTimes.set(id, acrossRoom);
+        for (const watchingPlayer of watching) {
+          watchingPlayer.frame({
+            v: LIVE_PROTOCOL_VERSION,
+            type: 'reaction',
+            reaction: { player: viewer, id: frame.id },
+          });
+        }
+      }
+    });
+
+    socket.on('close', () => {
+      if (terminalDrainTimer) clearTimeout(terminalDrainTimer);
+      accepting = false;
+      sendable = false;
+      watching.delete(watcher);
+      if (watching.size === 0) {
+        watchers.delete(id);
+        cachedPresence.delete(id);
+        roomReactionTimes.delete(id);
+      }
+      // Only the socket currently representing this player changes the count. A superseded socket
+      // closing later must not decrement a player who is still here on their replacement.
+      if (viewer && playerSocket && activePlayerSockets.get(playerSocket) === watcher) {
+        activePlayerSockets.delete(playerSocket);
+        invalidatePresence(id);
+        if (watchers.has(id)) announcePresence(id);
+      }
+    });
+  });
+
+  });
+
+  // One whole pass at a time. Slow database or chain reads must not stack ticker work forever.
+  let ticking = false;
+  let reconciledAt = 0;
+
+  const ticker = setInterval(() => {
+    if (ticking) return;
+    ticking = true;
+    void (async () => {
+      try {
+        const now = Date.now();
+        const sweeping = Boolean(settlement && now - reconciledAt >= RECONCILE_MS);
+        // Authorisations nobody spent come back to the player who earned them.
+        const released = await claims.releaseExpired().catch((error) => {
+          app.log.error(error);
+          return [];
+        });
+        for (const balance of released) announcePlayer(balance.roundId, balance.player);
+
+        for (const [id, room] of rooms) {
+          // Gameplay is over, but a buzzer-time authorisation and the chart remain honourable through
+          // the independent books tail. A process can wake for the first time after this tail (for
+          // example after a stall or restart), so persist every due game wake before deleting it.
+          if (now > room.launch.booksCloseAt) {
+            try {
+              if (room.nextWakeAt() !== null) await room.tick(Math.min(now, room.window.closesAt));
+            } catch (error) {
+              // Retain the room and retry: deleting after a failed final wake would make earned
+              // awards disappear permanently from an otherwise healthy durable round.
+              app.log.error(error);
+              continue;
+            }
+            if (settlement) {
+              const final = await settlement.reconcile(id).catch(() => ({ read: 0, failed: 1, changed: [] }));
+              if (final.failed > 0) app.log.error(`${id}: ${final.failed} final spend reads failed`);
+            }
+            for (const watcher of watchers.get(id) ?? []) {
+              if (
+                watcher.viewer &&
+                activePlayerSockets.get(playerSocketKey(id, watcher.viewer)) === watcher
+              ) {
+                activePlayerSockets.delete(playerSocketKey(id, watcher.viewer));
+              }
+              watcher.close(4410, 'ended', true);
+            }
+            watchers.delete(id);
+            cachedPresence.delete(id);
+            roomReactionTimes.delete(id);
+            rooms.delete(id);
+            continue;
+          }
+          // What the chain says was spent, which is the only figure that is actually true.
+          if (sweeping) {
+            const swept = await settlement!.reconcile(id).catch(() => ({ read: 0, failed: 0, changed: [] }));
+            if (swept.failed > 0) app.log.error(`${id}: ${swept.failed} spend reads failed`);
+            for (const player of swept.changed) announcePlayer(id, player);
+          }
+          const before = room.sequence();
+          // A delayed process may first wake well after the old one-tick grace. Honour every game
+          // wake through the immutable close, but never advance gameplay into the settlement tail.
+          try {
+            if (room.nextWakeAt() !== null) {
+              await room.tick(Math.min(now, room.window.closesAt));
+            }
+          } catch (error) {
+            app.log.error(error);
+          }
+          if (room.sequence() !== before) announce(id);
+        }
+
+        if (sweeping) reconciledAt = Date.now();
+      } finally {
+        ticking = false;
+      }
+    })();
+  }, TICK_MS);
+
+  app.addHook('onClose', async () => clearInterval(ticker));
+  return app;
+}
+
+export { Room, Claims, Sessions };
+export type { Command };