solid-objects 0.17.5 → 0.17.7

package/docs/guides/offline-first.md

@@ -0,0 +1,283 @@
+# Offline-first state in the browser with SQLite WASM
+
+The Solid Objects browser runtime keeps each identity's state in SQLite WASM in the origin private file system (OPFS). Tabs share that state. The runtime queues each write for the server in the same transaction as the local change. The queue sends writes in order when the network returns, and the server applies each write once. The runtime does not replicate server changes to the browser or merge concurrent edits like a CRDT. Nothing runs while the browser is closed.
+
+## The failure: an outbox in page memory
+
+An inspector records findings on a tablet without a network. Each inspection has an identity, and each finding has an ID and a note. The tablet must keep each finding until the server receives it.
+
+```javascript
+let pending = []
+
+export function queueFinding(finding) {
+  pending = [...pending, finding]
+}
+
+export function pendingFindings() {
+  return pending.length
+}
+
+export async function flushFindings({ send }) {
+  while (pending.length > 0) {
+    await send(pending[0])
+    pending = pending.slice(1)
+  }
+}
+```
+
+This example keeps the outbox in an array in page memory. The `queueFinding` function adds a finding, and `flushFindings` sends each finding before it removes it. A reload or a tab close loses every queued edit. The browser test queues two findings, reloads the page, and finds no queued finding.
+
+A page can close after `flushFindings` sends an edit but before it removes that edit. If the app retries that edit, it sends the edit again. The server needs a key to ignore the repeated edit. A queue must preserve both the edit and its key across attempts.
+
+## The native fix
+
+A durable outbox in IndexedDB preserves queued edits across reloads. The client gives each edit an ID and keeps that ID with the edit. A server table records each ID that the server applies. The server ignores an ID that the table already contains.
+
+With several tabs, one tab at a time must flush the outbox. The Web Locks API can coordinate this work across tabs of the same origin. A tab holds a lock while it sends queued edits. Other tabs wait for the same lock. [MDN describes this use of Web Locks.](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API)
+
+The Background Synchronization API can retry a send from a service worker after the network returns. It needs a service worker and a secure context. MDN marks it "Limited availability" because it does not work in some widely used browsers. [MDN lists these requirements and limits.](https://developer.mozilla.org/en-US/docs/Web/API/Background_Synchronization_API)
+
+This is a good design when the app needs only a queue. Solid Objects becomes relevant when each identity also has local state, rules, and an order that the server must replay.
+
+## One actor per inspection, in a module worker
+
+```javascript
+import { NonRetryableError } from "solid-objects/core"
+import { Actor, configure, registerTransmit, sharedSqliteWasm } from "solid-objects/browser/host"
+
+class Inspection extends Actor {
+  static actorType = "Inspection"
+
+  findings = []
+
+  record({ findingId, note }) {
+    if (this.findings.some((finding) => finding.findingId === findingId)) {
+      return this.findings.length
+    }
+    this.findings = [...this.findings, { findingId, note }]
+    this.transmit().record({ findingId, note })
+    return this.findings.length
+  }
+}
+
+const allowInspections = ({ actorType }) => actorType === "Inspection"
+
+const runtime = configure({
+  database: sharedSqliteWasm({ path: "inspections.db" }),
+  authorizeMessage: allowInspections,
+  authorizeQuery: allowInspections,
+  maxAttempts: 1_000,
+  retryDelayMilliseconds: (attempt) => Math.min(2 ** (attempt - 1), 30) * 1_000,
+  processAliveThresholdMilliseconds: 750,
+  leaseDurationMilliseconds: 750,
+  leaseRenewalIntervalMilliseconds: 250,
+})
+
+registerTransmit({
+  runtime,
+  deliver: async (envelope) => {
+    const response = await fetch("/inspections/sync", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(envelope),
+    })
+    if (response.status === 422) {
+      throw new NonRetryableError(`The server rejected effect ${envelope.effectId}`)
+    }
+    if (!response.ok) throw new Error(`Sync failed with HTTP ${response.status}`)
+  },
+})
+runtime.register(Inspection)
+const installed = runtime.install()
+installed.then(() => runtime.run(new AbortController().signal))
+
+self.onmessage = async (event) => {
+  const { requestId, actorId, operation, argumentsValue } = event.data
+  try {
+    await installed
+    const value = await Inspection.ref(actorId)[operation](argumentsValue)
+    postMessage({ requestId, ok: true, value })
+  } catch (error) {
+    postMessage({ requestId, ok: false, message: String(error?.message ?? error) })
+  }
+}
+```
+
+The runtime runs in a module worker and imports its APIs from `solid-objects/browser/host`. Each inspection has one `Inspection` actor identity. Its `findings` field holds the local state.
+
+The `sharedSqliteWasm` adapter stores that state in OPFS and shares one database between tabs. One tab holds the database. Other tabs send their SQL to that tab. Another tab takes over when the holder tab closes.
+
+The `record` operation checks the `findingId` before it changes the state. If the finding already exists, the operation returns the count without another change. Otherwise, it adds the finding and calls `this.transmit().record(...)`.
+
+The runtime commits the local change and the write for the server in the same transaction. Thus, a local commit cannot omit its queued write for the server. A retryable failure rolls back the local change and the queued write together.
+
+The `registerTransmit` function gives each queued write to `deliver`. This callback sends the envelope to `/inspections/sync`. The envelope identifies the effect, actor, operation, and arguments. The callback decides whether delivery succeeds or fails.
+
+A network failure throws an `Error`. The effect tries again later with the delay from `retryDelayMilliseconds`. This example increases the delay after each attempt, up to 30 seconds. An HTTP response other than success or 422 also causes an `Error`.
+
+An HTTP 422 response causes `deliver` to throw `NonRetryableError`, from `solid-objects/core`. The runtime moves that effect to dead letters and does not retry it. A normal return marks the write as delivered. The runtime does not inspect the HTTP response itself.
+
+The example sets `maxAttempts` to 1,000 because a long offline period can use many attempts. The default is 5. A high value extends the retry period, but it does not provide unlimited retries.
+
+The short lease settings let another tab take over quickly after a tab closes. The example uses 750 milliseconds for `processAliveThresholdMilliseconds` and `leaseDurationMilliseconds`. It uses 250 milliseconds for `leaseRenewalIntervalMilliseconds`.
+
+The policy permits messages and queries only for the `Inspection` actor type. A browser policy limits what your own page can call. It is not a security boundary because the user controls the page.
+
+```javascript
+const worker = new Worker(new URL("./inspection-worker.js", import.meta.url), { type: "module" })
+const pending = new Map()
+let nextRequestId = 0
+let workerFailure
+
+worker.onmessage = (event) => {
+  const { requestId, ok, value, message } = event.data
+  const request = pending.get(requestId)
+  pending.delete(requestId)
+  if (ok) {
+    request.resolve(value)
+    return
+  }
+  request.reject(new Error(message))
+}
+
+worker.onerror = (event) => {
+  workerFailure = new Error(`The actor worker failed: ${event.message || "it did not load"}`)
+  for (const request of pending.values()) request.reject(workerFailure)
+  pending.clear()
+}
+
+export function callActor({ actorId, operation, argumentsValue }) {
+  if (workerFailure) return Promise.reject(workerFailure)
+  const requestId = nextRequestId++
+  return new Promise((resolve, reject) => {
+    pending.set(requestId, { resolve, reject })
+    worker.postMessage({ requestId, actorId, operation, argumentsValue })
+  })
+}
+```
+
+The page starts a module worker and sends messages through `callActor`. The page holds no actor reference. A request ID connects each response to its call.
+
+If the worker fails to load, the page rejects every call that awaits a response. The page also rejects each later call with the stored error. The map in the page tracks call responses; the database holds the actor state and outbox.
+
+## The server applies each write once
+
+```typescript
+import { Actor } from "solid-objects"
+
+type Finding = { findingId: string; note: string }
+
+export class Inspection extends Actor {
+  static override readonly actorType = "Inspection"
+
+  findings: Finding[] = []
+
+  record({ findingId, note }: Finding): number {
+    if (this.findings.some((finding) => finding.findingId === findingId)) {
+      return this.findings.length
+    }
+    this.findings = [...this.findings, { findingId, note }]
+    return this.findings.length
+  }
+}
+```
+
+The server defines an actor with the same actor type, `Inspection`. Its `record` operation adds a finding only if its `findingId` does not already exist. The server operation does not transmit the write again.
+
+```typescript
+import {
+  IdempotencyConflict,
+  InvalidPayload,
+  receiveTransmitEnvelope,
+  UnknownActorType,
+  UnknownOperation,
+  type SolidObjectsRuntime,
+  type TransmitEnvelope,
+} from "solid-objects"
+
+export async function handleInspectionSync({
+  request,
+  runtime,
+  canWrite,
+}: {
+  request: Request
+  runtime: SolidObjectsRuntime
+  canWrite: (options: { request: Request; envelope: TransmitEnvelope }) => Promise<boolean>
+}): Promise<Response> {
+  const envelope = (await request.json()) as TransmitEnvelope
+  if (!(await canWrite({ request, envelope }))) return new Response("Forbidden", { status: 403 })
+
+  try {
+    await receiveTransmitEnvelope({ runtime, envelope })
+    return Response.json({})
+  } catch (error) {
+    if (
+      error instanceof InvalidPayload ||
+      error instanceof IdempotencyConflict ||
+      error instanceof UnknownActorType ||
+      error instanceof UnknownOperation
+    ) {
+      return new Response(null, { status: 422 })
+    }
+    throw error
+  }
+}
+```
+
+The `receiveTransmitEnvelope` function enqueues the write with the effect ID as the idempotency key. This key identifies repeated delivery of the same write. A repeated envelope therefore applies once, even if the browser sends it more than once.
+
+Delivery through `receiveTransmitEnvelope` skips `authorizeMessage`. The route must authenticate the device before it calls this function. It must also check that the device can write the actor in the envelope.
+
+The example gives those checks to `canWrite`. If that callback denies the request, the route answers 403 and does not enqueue the write. The browser policy cannot replace these server checks.
+
+The route answers 422 for `InvalidPayload`, `IdempotencyConflict`, `UnknownActorType`, and `UnknownOperation`. The last two occur when a device queued a write for an actor type or an operation that a later server deploy removed. The browser converts that response to `NonRetryableError` and stops retries for that write. This response prevents repeated attempts for an envelope that cannot apply.
+
+A Rails server can receive the same envelopes with `SolidObjects::Transmission.receive`. That method also skips message authorization. Authenticate the device before the call. Check its permission to write the actor.
+
+## Several tabs
+
+Each tab starts its own worker. The workers share the database through `sharedSqliteWasm`. Writes from two tabs to one inspection apply in the local order.
+
+The browser test records two findings in one tab and one finding in a second tab while offline. The server has no findings before the network returns. After the network returns, the server receives all three findings and applies each once, in order.
+
+Run one effect worker for each local runtime to preserve the order of writes for each actor. [The transmit section of the public API](../api.md#solid-objectstransmit) states this requirement. This order belongs to each actor identity; it does not define one order across all inspections.
+
+## What this does not do
+
+- It does not replicate server changes to the browser. Fetch the server state. Alternatively, subscribe with the WebSocket client in `solid-objects/browser`.
+- It does not merge concurrent edits from different devices. The server applies writes in the order it receives them for each identity. The application defines the conflict rules. CRDT libraries such as [Yjs](https://yjs.dev) and [Automerge](https://automerge.org) support automatic merges of concurrent edits.
+- Nothing runs while the browser is closed. Reminders and the outbox run only while a tab runs the worker. Queued writes wait in OPFS and send when a tab opens again.
+
+## Limits
+
+- CI tests the browser runtime in Chromium only. Safari 16.4 and Firefox 111 added the OPFS API that persistent storage needs. Test each engine that you support.
+- Persistent storage needs a secure context and a dedicated worker. An embedded WebView can lack OPFS even when the device browser supports it. Test the WebView itself.
+- The browser can clear the storage of an origin. Call `navigator.storage.persist()` to ask the browser to keep it.
+- All authorization callbacks deny by default, also in the browser. The example explicitly permits messages and queries for `Inspection`.
+- Delivery is at least once. The server must stay idempotent: a repeated write must not cause another state change.
+
+[Step 12 of the agent guide](../agents.md#12-use-the-browser-runtime) explains browser setup and policies. [Correctness and delivery semantics](../correctness.md) defines the guarantees and limits. [Virtual actors in TypeScript and Node.js](../virtual-actors.md) explains the actor model.
+
+## What the tests prove
+
+The [browser tests](../../test/browser/offline-first.browser.ts) check these cases:
+
+- Two tabs record three findings while offline. After the network returns, the server state contains each finding once, in the same order.
+- A finding in the local actor state survives a page reload.
+- Two findings in the outbox in page memory disappear after a page reload.
+
+The [route tests](../../test/guide-offline-first.test.ts) check these cases:
+
+- A request without device authorization receives 403 and adds no finding.
+- An authorized request receives 200 and adds the expected finding.
+- A repeated envelope receives 200 and leaves one finding.
+- An envelope with an empty operation receives 422.
+- An envelope for an actor type or an operation that the server removed receives 422.
+
+These tests do not check every browser engine or every interruption during delivery. They also do not test `IdempotencyConflict` or the browser response to 422.
+
+## Sources
+
+- MDN, [Background Synchronization API](https://developer.mozilla.org/en-US/docs/Web/API/Background_Synchronization_API), checked October 9, 2026.
+- MDN, [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API), checked October 9, 2026.
+- [Yjs](https://yjs.dev), and [Automerge](https://automerge.org), checked October 9, 2026.

package/docs/guides/persistent-rooms.md

@@ -0,0 +1,392 @@
+# Keep turn-based room state through restarts in Node.js
+
+A room in process memory loses its state and its turn timer when the process restarts. Store the room in SQL. Arm the turn timer from durable data. One actor per room gives you ordered moves, a durable turn timer, and the current state after a restart. This guide uses `solid-objects` for turn-based games, lobbies, and shared boards in Node.js.
+
+## The failure: state and timers in process memory
+
+```typescript
+type MemoryRoom = { players: string[]; turnNumber: number; started: boolean }
+
+export function createMemoryRooms({ turnMilliseconds }: { turnMilliseconds: number }) {
+  const rooms = new Map<string, MemoryRoom>()
+  const timers = new Map<string, ReturnType<typeof setTimeout>>()
+
+  function armTurnTimer(roomId: string): void {
+    clearTimeout(timers.get(roomId))
+    timers.set(
+      roomId,
+      setTimeout(() => skipTurn(roomId), turnMilliseconds),
+    )
+  }
+
+  function skipTurn(roomId: string): void {
+    const room = rooms.get(roomId)
+    if (!room) return
+    rooms.set(roomId, { ...room, turnNumber: room.turnNumber + 1 })
+    armTurnTimer(roomId)
+  }
+
+  return {
+    join({ roomId, playerId }: { roomId: string; playerId: string }): void {
+      const room = rooms.get(roomId) ?? { players: [], turnNumber: 0, started: false }
+      rooms.set(roomId, { ...room, players: [...room.players, playerId] })
+    },
+    start({ roomId }: { roomId: string }): void {
+      const room = rooms.get(roomId)
+      if (!room) return
+      rooms.set(roomId, { ...room, started: true })
+      armTurnTimer(roomId)
+    },
+    room({ roomId }: { roomId: string }): MemoryRoom | undefined {
+      return rooms.get(roomId)
+    },
+    pendingTimers(): number {
+      return timers.size
+    },
+    close(): void {
+      for (const timer of timers.values()) clearTimeout(timer)
+      timers.clear()
+    },
+  }
+}
+```
+
+The `Map` holds the room state in one process. The `setTimeout` holds the turn timer in that process. Neither survives a process restart. A deploy or a crash loses both. A second process has its own memory and cannot read the first process's room or timer.
+
+The test models a restart with two instances of `createMemoryRooms`. It starts a game with two players and checks that one timer exists. It then calls `close` and creates a new instance. The new instance has no room and no timer. The test uses new instances in the same process.
+
+## The native fix: a row with a version and a deadline
+
+```typescript
+import { DatabaseSync } from "node:sqlite"
+
+export type RoomState = { players: string[]; turnNumber: number }
+
+export function openRoomStore({ path }: { path: string }): DatabaseSync {
+  const database = new DatabaseSync(path)
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS rooms (
+      room_id TEXT PRIMARY KEY,
+      state TEXT NOT NULL,
+      version INTEGER NOT NULL,
+      turn_deadline INTEGER
+    )
+  `)
+  return database
+}
+
+export function saveRoom({
+  database,
+  roomId,
+  state,
+  expectedVersion,
+  turnDeadline,
+}: {
+  database: DatabaseSync
+  roomId: string
+  state: RoomState
+  expectedVersion: number
+  turnDeadline: number | null
+}): { saved: boolean } {
+  if (expectedVersion === 0) {
+    const inserted = database
+      .prepare(
+        "INSERT OR IGNORE INTO rooms (room_id, state, version, turn_deadline) VALUES (?, ?, 1, ?)",
+      )
+      .run(roomId, JSON.stringify(state), turnDeadline)
+    return { saved: inserted.changes === 1 }
+  }
+  const updated = database
+    .prepare(
+      "UPDATE rooms SET state = ?, version = version + 1, turn_deadline = ? WHERE room_id = ? AND version = ?",
+    )
+    .run(JSON.stringify(state), turnDeadline, roomId, expectedVersion)
+  return { saved: updated.changes === 1 }
+}
+
+export function loadRoom({
+  database,
+  roomId,
+}: {
+  database: DatabaseSync
+  roomId: string
+}): { state: RoomState; version: number } | undefined {
+  const row = database.prepare("SELECT state, version FROM rooms WHERE room_id = ?").get(roomId) as
+    { state: string; version: number } | undefined
+  if (!row) return undefined
+  const state: unknown = JSON.parse(row.state)
+  if (!isRoomState(state)) throw new Error(`stored room ${roomId} has an unexpected shape`)
+  return { state, version: row.version }
+}
+
+export function dueTurnDeadlines({
+  database,
+  now,
+}: {
+  database: DatabaseSync
+  now: number
+}): string[] {
+  const rows = database
+    .prepare("SELECT room_id FROM rooms WHERE turn_deadline <= ? ORDER BY turn_deadline")
+    .all(now) as { room_id: string }[]
+  return rows.map((row) => row.room_id)
+}
+
+function isRoomState(value: unknown): value is RoomState {
+  if (typeof value !== "object" || value === null) return false
+  if (!("players" in value) || !Array.isArray(value.players)) return false
+  if (!value.players.every((player) => typeof player === "string")) return false
+  return "turnNumber" in value && Number.isSafeInteger(value.turnNumber)
+}
+```
+
+The SQL design stores each room as JSON in a row with a `version` column and a turn deadline. `loadRoom` returns the state and its version. It checks the stored JSON against `RoomState` and throws when the shape is unexpected, so the caller never uses unchecked data. The caller passes that version to `saveRoom` as `expectedVersion`.
+
+`saveRoom` updates a row only when its version still matches. A successful update also increases the version. A write from an old version returns `{ saved: false }`. The caller then reloads the room and tries again. An old copy of the state cannot replace a newer copy.
+
+The row also stores `turn_deadline`. Call `dueTurnDeadlines` at startup and on an interval. It finds rooms whose deadline equals or precedes `now`. The deadline survives because SQL stores it with the state. The query finds due rooms; it does not apply their timeouts.
+
+The application still owns these parts:
+
+- A retry loop for version conflicts.
+- A sweep process that checks deadlines.
+- A rule that permits only one process to apply each timeout.
+
+The test closes the database and opens the same database again. The room survives. A write with the current version succeeds, and a write with the old version fails. The sweep then finds the due room.
+
+## One actor per room
+
+```typescript
+import { Actor } from "solid-objects"
+
+export const TURN_MILLISECONDS = 60_000
+
+const MAXIMUM_PLAYERS = 4
+
+type Move = { playerId: string; move: string; turnNumber: number }
+
+export class TurnRoom extends Actor {
+  static override readonly actorType = "TurnRoom"
+
+  players: string[] = []
+  started = false
+  turnNumber = 0
+  moves: Move[] = []
+  skippedTurns: number[] = []
+  revision = 0
+
+  get currentPlayer(): string | null {
+    if (!this.started) return null
+    return this.players[this.turnNumber % this.players.length] ?? null
+  }
+
+  join({ playerId }: { playerId: string }): { players: string[] } {
+    if (this.players.includes(playerId)) return { players: this.players }
+    if (this.started) this.reject("game_started", { message: "The game already started" })
+    if (this.players.length === MAXIMUM_PLAYERS) {
+      this.reject("room_full", { message: "The room is full" })
+    }
+    this.players = [...this.players, playerId]
+    this.revision += 1
+    return { players: this.players }
+  }
+
+  start({ playerId }: { playerId: string }): { turnNumber: number } {
+    if (this.started) return { turnNumber: this.turnNumber }
+    if (!this.players.includes(playerId)) {
+      this.reject("not_in_room", { message: "Only a player in the room can start the game" })
+    }
+    if (this.players.length < 2) {
+      this.reject("not_enough_players", { message: "The game needs two players" })
+    }
+    this.started = true
+    this.revision += 1
+    this.#armTurnTimer()
+    return { turnNumber: this.turnNumber }
+  }
+
+  play({ playerId, move, turnNumber }: { playerId: string; move: string; turnNumber: number }): {
+    turnNumber: number
+  } {
+    if (!this.started) this.reject("game_not_started", { message: "The game has not started" })
+    if (turnNumber !== this.turnNumber) {
+      this.reject("stale_turn", {
+        message: "That turn already ended",
+        details: { turnNumber: this.turnNumber },
+      })
+    }
+    if (playerId !== this.currentPlayer) {
+      this.reject("not_your_turn", { message: "It is not your turn" })
+    }
+    this.moves = [...this.moves, { playerId, move, turnNumber }]
+    this.#advanceTurn()
+    return { turnNumber: this.turnNumber }
+  }
+
+  turnTimeout({ turnNumber }: { turnNumber: number }): { skipped: boolean } {
+    if (turnNumber !== this.turnNumber) return { skipped: false }
+    this.skippedTurns = [...this.skippedTurns, turnNumber]
+    this.#advanceTurn()
+    return { skipped: true }
+  }
+
+  #advanceTurn(): void {
+    this.turnNumber += 1
+    this.revision += 1
+    this.#armTurnTimer()
+  }
+
+  #armTurnTimer(): void {
+    this.schedule({ at: new Date(Date.now() + TURN_MILLISECONDS) }).turnTimeout({
+      turnNumber: this.turnNumber,
+    })
+  }
+}
+```
+
+Each room has one `TurnRoom` actor identity. Moves for that room run one at a time, in order, across processes. The actor stores the players, moves, turn number, skipped turns, and revision. Other rooms have separate identities.
+
+`play` takes the `turnNumber` that the client saw. The actor compares that value with its current turn number before it accepts the move. Two tabs can submit different moves for the same turn. The first accepted move advances the turn. The second submission then rejects with `stale_turn`.
+
+The actor also checks the player. A move from the wrong player rejects with `not_your_turn`. The getter `currentPlayer` identifies the player for the current turn. Before the game starts, it returns `null`. A getter is a read-only query.
+
+Each turn arms `schedule({ at }).turnTimeout({ turnNumber })`. The reminder stores the turn number that it applies to. A reminder with the same operation and no key moves the same alarm. It does not add a second alarm. Thus, a move sets a new deadline for the next turn.
+
+`turnTimeout` compares its argument with the current turn number. It does nothing when that turn already ended. A late or repeated timer cannot skip a later turn. A valid timeout records the skipped turn and advances to the next turn.
+
+`revision` increases on every change to the room. A client compares revisions to detect missed changes. A repeated `join` for the same player returns the players without a change. It does not increase `revision`.
+
+## Authorize players
+
+```typescript
+import { createRuntime, type SolidObjectsRuntime } from "solid-objects"
+import { sqlite } from "solid-objects/database/sqlite"
+import { TurnRoom } from "./turn-room.js"
+
+export type RoomCaller = { playerId: string }
+
+const PLAYER_OPERATIONS = new Set(["join", "start", "play"])
+
+export function authorizeRoomMessage({
+  actorType,
+  operation,
+  arguments: argumentsValue,
+  authorizationContext,
+}: {
+  actorType: string
+  operation: string
+  arguments: Record<string, unknown>
+  authorizationContext: unknown
+}): boolean {
+  if (actorType !== TurnRoom.actorType) return false
+  if (!PLAYER_OPERATIONS.has(operation)) return false
+  if (!isRoomCaller(authorizationContext)) return false
+  return argumentsValue.playerId === authorizationContext.playerId
+}
+
+export function authorizeRoomQuery({
+  actorType,
+  authorizationContext,
+}: {
+  actorType: string
+  authorizationContext: unknown
+}): boolean {
+  return actorType === TurnRoom.actorType && isRoomCaller(authorizationContext)
+}
+
+export function roomRuntime({ path }: { path: string }): SolidObjectsRuntime {
+  const runtime = createRuntime({
+    database: sqlite({ path }),
+    authorizeMessage: authorizeRoomMessage,
+    authorizeQuery: authorizeRoomQuery,
+  })
+  runtime.register(TurnRoom)
+  return runtime
+}
+
+function isRoomCaller(value: unknown): value is RoomCaller {
+  if (typeof value !== "object" || value === null) return false
+  return "playerId" in value && typeof value.playerId === "string"
+}
+```
+
+All authorization callbacks deny by default. The application supplies a policy for messages and queries. The message policy permits only `join`, `start`, and `play` for `TurnRoom`.
+
+The policy binds the `playerId` argument to the authenticated player in `authorizationContext`. One player cannot submit a move for another player. The application authenticates the WebSocket or HTTP request and passes the player as `authorizationContext`. A player identifier from an untrusted request does not establish that identity.
+
+No caller can run `turnTimeout` directly through this policy. Only the runtime runs it from the reminder. The query policy checks the actor type and the player context. The reconnect function below also checks room membership before it returns the room.
+
+## Reconnect: send the current room
+
+```typescript
+import type { ActorSnapshot, SolidObjectsRuntime } from "solid-objects"
+import { TurnRoom } from "./turn-room.js"
+
+export async function resumeRoom({
+  runtime,
+  roomId,
+  playerId,
+  lastSeenRevision,
+}: {
+  runtime: SolidObjectsRuntime
+  roomId: string
+  playerId: string
+  lastSeenRevision: number
+}): Promise<{ room: ActorSnapshot<TurnRoom>; changed: boolean } | null> {
+  const room = await runtime.ref(TurnRoom, roomId).snapshot({ authorizationContext: { playerId } })
+  if (!room.players.includes(playerId)) return null
+  return { room, changed: room.revision !== lastSeenRevision }
+}
+```
+
+After a reconnect or a server restart, the server reads the room with the player's authorization and sends it. `resumeRoom` reads a snapshot with `authorizationContext`. It returns `null` to a player who is not in the room. Keep this membership check on the path that sends room state to the client.
+
+For a room member, `resumeRoom` returns the room and `changed`. It compares `revision` with `lastSeenRevision` to calculate `changed`. The client compares the current revision with the last revision it saw. A difference shows that the client missed a change.
+
+Socket.IO connection state recovery restores the socket id, rooms, and `data` when recovery succeeds. The server must enable this feature. It also sends events that the client missed during a temporary disconnection. The documentation says recovery “will not always be successful”, so the application must still synchronize client and server state. [Socket.IO documentation](https://socket.io/docs/v4/connection-state-recovery).
+
+Adapter support also matters:
+
+- The in-memory adapter supports recovery.
+- The Redis adapter does not support recovery.
+- The Redis Streams adapter supports recovery.
+- The MongoDB adapter supports recovery.
+
+The [Socket.IO adapter table](https://socket.io/docs/v4/connection-state-recovery#compatibility-with-existing-adapters) lists this support. Socket.IO recovery and this pattern work together. Socket.IO restores the connection, and the actor restores the authorized room state.
+
+## Run the runtime process
+
+The turn timer is a reminder. In normal operation, reminders run only while a process calls `runtime.run(signal)`. The `roomRuntime` function registers `TurnRoom` before the runtime starts. The process must know the actor class to execute its operations.
+
+Run the background roles as described in [step 7 of the agent guide](../agents.md#7-run-the-background-roles). When no process runs, the due reminder waits in SQL. It runs when a process starts. The runtime needs a process to execute each timeout.
+
+In tests, `runtime.testing.runDueReminders({ now })` finds due reminders at the supplied time. Then `runtime.testing.drain({ roles: ["actors"] })` runs the actor work. These calls test due timers without a wait for the real deadline.
+
+## What the tests prove
+
+The [tests for persistent rooms](../../test/guide-persistent-rooms.test.ts) check these cases in this order:
+
+1. A new instance of the memory design has no room and no timer after a simulated restart.
+2. The SQL room survives a database reopen. A write from an old version fails, and the sweep finds the due room. A stored room with an unexpected shape fails to load.
+3. Two submissions for one turn produce one accepted move and one `stale_turn` rejection.
+4. A move from the wrong player rejects with `not_your_turn`.
+5. A caller cannot submit a move for another player.
+6. After a runtime restart, a due reminder skips turn zero and makes the second player current.
+7. After a move, a sweep before the next deadline leaves the turn unchanged and records no skipped turn.
+8. A caller cannot invoke `turnTimeout` directly.
+9. After a restart, a room member receives the current room, its move, and `changed: true`.
+10. A player outside the room receives `null` from `resumeRoom`.
+
+The seventh test does not inject a late or repeated timer. The turn number check in `turnTimeout` handles that case.
+
+## Limits
+
+Delivery is at least once. Write each operation so that it can run again. One room runs one write at a time. This fits turn-based play, not a high-frequency game loop or fast real-time physics.
+
+The application owns the WebSocket server, authentication, and the display of the room. There are no transactions across two rooms. The package requires Node.js 24.4 or newer and ESM only. The package is pre-1.0.
+
+See [Correctness and delivery semantics](../correctness.md) and [Virtual actors in TypeScript and Node.js](../virtual-actors.md).
+
+## Sources
+
+Socket.IO, [Connection state recovery](https://socket.io/docs/v4/connection-state-recovery), checked October 9, 2026.