git:20260730.8ef07d0 to git:20260820.cd23820

- description: Design, implement, debug, review, or verify remote turn-based multiplayer games on Cloudflare Durable Objects. Use for room URLs and invites, reconnectable player identity, WebSocket hibernation, server-authoritative turns, revision conflicts, idempotent actions, concurrent move races, presence, lobby/start failures, deterministic bots, local Wrangler testing, cross-browser playthroughs, or production verification of a Durable Object game room.

- Build each room as one server-authoritative state machine. Treat the room URL,

- resume credential, WebSocket connection, player seat, game revision, action

- acknowledgement, deployment, and browser-visible outcome as separate facts.

-

- Use this skill together with the adjacent `cloudflare-production-builder` skill

- when the work includes provisioning, migrations, deployment, observability,

- cost, or live release verification.

-

- ## Start with the authority sentence

-

- Write this before changing code:

-

- > The Durable Object owns ____. The room is addressed by ____. A device resumes

- > with ____. Mutations serialize by ____. Every action is identified by ____ and

- > fenced by revision ____. Clients recover from uncertainty by ____.

-

- Stop and resolve ambiguity if the URL, local storage, client reducer, and

- Durable Object can select different rooms or disagree about canonical state.

-

- ## Inspect the full path

-

- Trace these surfaces before designing:

-

- 1. room creation and `getByName()` routing;

- 2. public and private invitation URL generation;

- 3. local credential storage and resume behavior;

- 4. join, resume, and WebSocket upgrade routes;

- 5. Durable Object class export, binding, migration, storage schema, and

- generated deployment config;

- 6. WebSocket attachment, tags, presence, and hibernation;

- 7. client action submission, acknowledgement, retry, and error UI;

- 8. deterministic reducer, validation, scoring, bots, and turn advancement;

- 9. local Wrangler bindings, browser tests, and release path.

- Do not infer a working Durable Object from a frontend-only dev server. Exercise

- the real Worker entry point with the actual local DO binding.

- Keep the deterministic room coordinator/reducer independent of Cloudflare

- transport so authority, migrations, and adversarial concurrency can be tested

- without Wrangler.

- ## Enforce the room and identity contract

- - Make the explicit room code in the URL the sole room selector.

- - Store resume credentials by room code, never as one global “last room.”

- - Let a public room URL resume only credentials for that exact room.

- - Force a private seat invite through the join path even if another credential

- exists.

- - Strip private seat and invite tokens from the visible URL after successful

- exchange for a device resume token.

- - Treat a room code as routing information, not authentication.

- - Model a device as owning one or more seats; do not assume one token equals one

- player. Re-authorize ownership against current room state on every message.

- - Add an authenticated resume preflight. Return `200` for a valid device,

- `401` for an invalid credential, and `404` for a missing room.

- - On `401` or `404`, remove only that room’s credential and show a recoverable

- join screen. Do not reconnect forever.

- - Make leaving one room preserve credentials for other rooms.

- - Do not silently resume a saved room from a bare online landing route.

- when designing URLs, identity storage, message schemas, or recovery behavior.

-

- ## Serialize every authoritative mutation

- Durable Objects provide a single logical owner, but WebSocket handlers can

- interleave at `await` boundaries. A read-modify-write sequence is not safe

- merely because it runs in one object.

- - Put create, join, seat changes, game actions, and bot transitions through one

- mutation gate when they can touch the same room state.

- - Re-read room state and re-authorize the device inside the gate.

- - Use an immutable `actionId` as the idempotency key.

- - Check duplicate `actionId` before `expectedRevision`, so a retry of an already

- committed action with its old revision remains idempotently accepted.

- - Validate `expectedRevision` against fresh state for nonduplicates.

- - Persist accepted state before acknowledging or broadcasting it.

- - Acknowledge duplicates as accepted with the canonical snapshot, but do not

- apply, persist, broadcast activity, or trigger bots twice.

- - Reject a stale or illegal action with its `actionId`, reason, and canonical

- snapshot.

- - Keep deterministic rule validation, scoring, turn order, and bot state

- authoritative on the server. The client proposes actions; it does not submit

- trusted outcomes.

- ## Make acknowledgement explicit

- Use a correlated result for every syntactically valid game action:

- ```ts

- type ActionResult = {

- type: "action.result";

- actionId: string;

- accepted: boolean;

- reason?: string;

- snapshot: RoomSnapshot;

- };

- ```

- - Allow one in-flight game action per client unless a more sophisticated

- optimistic protocol is deliberately implemented.

- - Disable mutation controls while awaiting the result and expose syncing state.

- - Apply snapshots monotonically by revision; ignore older arrivals.

- - Clear a local draft only after acceptance. Keep it on rejection so the player

- can repair the move.

- - On acknowledgement timeout, treat the result as unknown: reconnect, install

- the canonical snapshot, then let the player decide whether to retry.

- - Never blindly resend an uncertain mutation with a new action ID.

- ## Keep transport and lifecycle safe

- - Hash long-lived device tokens at rest and compare them without early exit.

- - Put only stable device or seat identifiers in WebSocket attachments.

- - Derive presence from live tagged sockets; do not make presence authoritative

- game state.

- - Version stored room state and normalize older versions on read.

- - Validate cross-field invariants after normalization: one host, correct seat

- count/order, unique seat ownership, bidirectional device-seat links, and

- mode-specific bot/invite/local fields.

- - Include scheduled bot/alarm transitions in the same mutation discipline.

- - Close every tagged socket for a device immediately when host action revokes

- that device.

- - When proxying request bodies from a Worker to a Durable Object, consume or

- clone the body deliberately before constructing the forwarded request.

- Reusing a request stream after sending a response can fail under Wrangler.

- - Bound message sizes, text lengths, activity frequency, chat rate, recent

- action IDs, and retained activity.

- - Parse explicit message allowlists in both directions. Never cast arbitrary

- decoded JSON into a protocol union.

- - Return room, join, and resume responses with `Cache-Control: no-store`.

- ## Verify adversarially

- At minimum, prove:

- 1. stored room A plus URL room B opens B, never A;

- 2. A and B credentials coexist, and leaving A preserves B;

- 3. private invites force joining and secrets disappear from the URL;

- 4. invalid resume credentials return to join without an infinite loop;

- 5. two same-revision concurrent actions result in exactly one state mutation;

- 6. a duplicate action returns the same canonical state without duplicate work;

- 7. rapid local transforms followed by commit submit the latest transform;

- 8. two remote humans join, start, complete one turn each, and agree on round,

- active player, scores, and board;

- 9. four players join, start, complete a full round, and agree on the next turn;

- 10. disconnect and resume preserve seat ownership and canonical state.

- Use actual browsers where compatibility matters. Keep each player in an

- isolated browser profile or context. Capture the room code, player names,

- revision/round, active player, and scores as evidence.

- before diagnosing a reported lobby/start failure or declaring multiplayer

- ready.

-

- ## Completion language

-

- Report these separately:

-

- - `implemented locally`

- - `focused protocol tests pass`

- - `local Durable Object browser flow passed`

- - `cross-browser playthrough passed`

- - `committed`

- - `pushed`

- - `Worker deployed`

- - `custom-domain multiplayer verified`

-

- Never call a create/join smoke test a turn-playthrough, or a successful build a

- multiplayer verification.