# nice-code — full documentation

Transport-agnostic typed actions, serializable errors, and reactive state for TypeScript.
This file concatenates every page of https://nicecode.io so you can feed the library's entire
API surface into a local AI coding assistant for accurate context.

Using only one package? Point your agent at the per-module file instead:
  - /llms-action.txt — @nice-code/action
  - /llms-realm.txt — @nice-code/realm
  - /llms-error.txt — @nice-code/error
  - /llms-state.txt — @nice-code/state
  - /llms-util.txt — @nice-code/util
  - /llms-common-errors.txt — @nice-code/common-errors

Generated from src/content/docs — do not edit by hand.

---
# Validation & Hono

Source: /common-errors/overview
Description: Shared Standard Schema validation errors and drop-in Hono middleware.

`@nice-code/common-errors` gives you a ready-made error domain for [Standard Schema](https://github.com/standard-schema/standard-schema) validation failures, plus Hono middleware that throws it for you.

```bash
bun add @nice-code/common-errors
```

Peer deps: `valibot` (or any Standard Schema library), `hono` (for the `/hono` subpath).

## The validation error domain

`err_validation` is a [`@nice-code/error`](/nice-error/domains/) domain. Import it to match or inspect validation errors by domain. It exposes one id — `EValidator.standard_schema` — with context `{ issues }`.

```ts
import { err_validation, EValidator } from "@nice-code/common-errors";

if (err_validation.isExact(caught)) {
  const hydrated = err_validation.hydrate(caught);
  const { issues } = hydrated.getContext(EValidator.standard_schema);
  // issues: readonly StandardSchemaV1.Issue[]
}
```

## Hono middleware

Import from the `/hono` subpath.

### `niceSValidator(target, schema)`

A drop-in replacement for `@hono/standard-validator`'s `sValidator`. When validation fails it throws a `NiceError` instead of returning a 400 — so all your error handling goes through one place.

```ts
import { niceSValidator } from "@nice-code/common-errors/hono";
import * as v from "valibot";

const CreateUserSchema = v.object({
  name: v.string(),
  email: v.pipe(v.string(), v.email()),
});

app.post("/users", niceSValidator("json", CreateUserSchema), async (c) => {
  const body = c.req.valid("json"); // fully typed
  // ...
});
```

Convert the thrown error to a response in Hono's `onError`:

```ts
import { castNiceError } from "@nice-code/error";
import type { ContentfulStatusCode } from "hono/utils/http-status";

app.onError((err, c) => {
  const niceError = castNiceError(err);
  // `httpStatusCode` is a plain `number`; Hono's `c.json` only accepts its restricted
  // status-code union, so the cast bridges the two. The value is a real HTTP code at runtime.
  return c.json(niceError.toJsonObject(), niceError.httpStatusCode as ContentfulStatusCode);
});
```

If something that *isn't* a `NiceError` crashes the request — a dropped DB connection, a thrown string, a bug deep in a dependency — you don't need a separate 500 branch. `castNiceError` wraps any non-`NiceError` value in a generic `NiceError` flagged `isUnhandled: true`, with a default `httpStatusCode` of `500`. So the single `onError` above already returns a well-formed JSON error with a sensible status for *every* failure path; the `isUnhandled` flag is what lets you tell a declared, expected error apart from an unexpected crash (e.g. to log it differently or hide its message in production).

### `niceCatchSValidation()`

Catches the raw responses `@hono/standard-validator` sends back (its default `{ success: false, error: [...] }` shape) and turns them into `NiceError` JSON responses — useful when you can't swap `sValidator` out yourself.

```ts
import { niceCatchSValidation } from "@nice-code/common-errors/hono";

app.use(niceCatchSValidation());
// Existing sValidator usage is now intercepted automatically
app.post("/data", sValidator("json", MySchema), handler);
```

## Full example

```ts
import { Hono } from "hono";
import type { ContentfulStatusCode } from "hono/utils/http-status";
import { niceSValidator } from "@nice-code/common-errors/hono";
import { castNiceError } from "@nice-code/error";
import * as v from "valibot";

const app = new Hono();

app.onError((err, c) => {
  const niceError = castNiceError(err);
  return c.json(niceError.toJsonObject(), niceError.httpStatusCode as ContentfulStatusCode);
});

const BodySchema = v.object({ message: v.string() });

app.post("/echo", niceSValidator("json", BodySchema), async (c) => {
  const { message } = c.req.valid("json");
  return c.json({ echo: message });
});
```

---

# Observing Backends

Source: /devtools/backends
Description: Attach the devtools window to a server — including a Cloudflare Durable Object — and read per-client wire traffic: which client costs what, in true billable bytes.

A frontend's devtools tell you what your app sent. They cannot tell you what your **server** paid for it. This page is about the other end of the wire: getting a backend into the devtools window, and reading its traffic *per connected client*, because that is the unit your bill is denominated in.

## Two lenses, and why they disagree

A backend reports the same traffic twice, measured at different layers. Both are correct. They are labelled in the UI so the difference never reads as a bug.

| Lens | Where it measures | What it counts |
| --- | --- | --- |
| **wire · post-encryption bytes** (Traffic sidebar) | the carrier | Every frame on every lane (`handshake`, `keepalive`, `action`, `realm`, `http`), sized *after* encryption — what the platform transmits and bills. |
| **engine · decoded payload** (Server view, per realm) | inside the realm engine | The realm lane only, sized *before* the crypto envelope — plus egress in **messages** (the per-message billing unit) vs frames, and the coalesce ratio batching won you. |

The wire lens is always larger: it carries the envelope the engine never sees. If you are optimizing *cost*, read egress messages from the engine lens and egress bytes from the wire lens.

## Per-client attribution

Every tapped frame carries a `linkId` — the coordinate of whoever is on the other end. On a server that is the connected client; on a client it is the backend it dialed. So the same **clients** table appears on both sides of a wire, answering the same question from each end:

```
CLIENTS · LAST 5M
client                       in    in bytes   out   out bytes
envId[web_app]…insId[i1]    412      21.1 KB   418     44.9 KB
envId[web_app]…insId[k9]     91       4.8 KB    94      9.7 KB
(handshaking)                 8       3.2 KB     8      2.6 KB
total                       511      29.1 KB   520     57.2 KB
```

Two reserved rows keep the arithmetic honest, so the table always sums to the headline totals:

- **`(handshaking)`** — frames tapped before a peer identity existed. A server cannot know *who* is connecting until the handshake binds them, so those bytes are real but unattributable. (A client stamps its handshake, because it knows its peer before it sends the first byte.)
- **`(other links)`** — links past `maxLinks` (default 200), folded together. A public server must not grow one counter per socket it has ever seen.

Nothing here captures payload contents. Sizes and counts only, by design.

## Identity, derived

Every producer stamps an identity envelope on its frames. All of it comes off the runtime coordinate you already hand over, and none of it is worth restating:

| Envelope field | Where it comes from | Why |
| --- | --- | --- |
| `coordEnvId` | `runtime.coordinate.envId` | The identity a client names as its `peer`. The topology joins each frontend's realm wire to the backend advertising it — a realm-id join alone is ambiguous when two backends host the same realm. |
| `clientId` | **frontend**: `insId` · **server**: `envId::perId` · **DO**: `do_<perId>` | Frontends key by *instance* (two tabs are two clients). Backends key by *identity*, so a restarted dev server **replaces** its entry rather than leaving a ghost beside a fresh one. A DO's persistent id survives hibernation wakes. |
| `label` | `envId`, plus an elided `perId` | The switcher and the topology band read like the coordinates do. Override with `name`. |
| `stage` → `env` | you, explicitly | Deployment stage is *where it runs*; `envId` is *which runtime it is*. They change for different reasons, so neither can be derived from the other. |

That asymmetry between `insId` and `perId` is not a devtools invention — it is the distinction `RuntimeCoordinate` already draws, reused rather than re-stated.

## Which backends can serve several topologies

| Producer | How it reaches a window | Topologies |
| --- | --- | --- |
| Web app | `BroadcastChannel` + a relay room | **Exactly one.** A frontend *is* one app. |
| Long-lived server | dials **out**, one relay room per socket | **Many** — pass `topologyId: [...]`. |
| Durable Object | the window dials **in** | **Many, with zero configuration.** It has no `topologyId`; whoever dials in observes it. |

## Attaching a backend

### A long-lived server (Bun, Node, …)

It dials the relay itself and appears in the switcher as its own client. There is nothing to configure: the relay lives on a well-known port, and a backend simply looks there.

```ts title="backend/devtools.ts"
import { createNiceServerDevtools } from "@nice-code/devtools/server";
import { DEVTOOLS_TOPOLOGY } from "my-app-shared";

export const devtools = createNiceServerDevtools({
  topologyId: DEVTOOLS_TOPOLOGY,   // the relay room — the same id your frontend passes
  runtime,                         // identity: label, clientId and coordEnvId all derived
  realms: { match: engine },       // one scope per realm engine
  domains: [act_root],             // the ROOT action domains to observe
});

serveChannel(runtime, channel, { storage, carriers, wireTap: devtools.wireTap });
```

That is the whole setup: one call, the exact mirror of the frontend's `createNiceDevtools()`, and the same three seams behind it.

:::note[What you no longer pass]
`coordEnvId` — the identity a client names as its `peer`, which the topology joins each realm's wire against — **is** `runtime.coordinate.envId`. So is the label, and so is the `clientId`. Handing the runtime over once is enough; see [Identity, derived](#identity-derived) below.
:::

The `relay` sink defaults to `ws://localhost:5199` — where [`niceDevtools()`](/devtools/window/#crossing-browser-partitions) starts a relay, and where `bunx @nice-code/devtools-relay` listens. A backend usually boots *before* anyone opens devtools, so its first dials are refused; it keeps retrying quietly on a backoff and joins the moment a relay appears, with no restart and no line in your log.

Pass `relayPort` when the relay is on another port, or `relayUrl` when it is on another machine. A **deployed** backend must always name its own relay — `localhost` means nothing there — though the whole thing is inert under `NODE_ENV === "production"` regardless.

`createServerDevtoolsHost` from `@nice-code/devtools-core` is the seam underneath, if you need to compose scopes the two records don't cover.

### One backend, several apps

A service shared by a web app and an admin console belongs to **both** devtools topologies. Name them all:

```ts
createNiceServerDevtools({ topologyId: ["web-app", "admin-app"], runtime, /* … */ });
```

It joins both relay rooms and appears in both windows. The two apps' *frontends* stay invisible to each other — a backend is a room member, not a router — and a `clear` issued from one window is addressed to one client, so it cannot disturb the other. Costs one WebSocket per topology, to the same local relay.

### A Cloudflare Durable Object

A DO is different, and the difference is not cosmetic. **Its entire cost model is hibernation.** A dial-out relay sink would hold an outbound socket open, pinning the DO awake — billing you for the privilege of measuring its idle cost, and reporting numbers from a DO that never sleeps.

So the direction is inverted: **the window dials in** — a plain wire connection to the DO's **ordinary WebSocket endpoint** (the same one its clients use), where devtools rides the wire mux as its own token-gated protocol. No separate dev route, no socket tagging: the DO's forwards stay exactly as they were, and a hibernation wake needs no re-adoption (the protocol re-admits a surviving socket lazily, on its next frame).

```ts title="MatchDO.ts"
import { createNiceDurableObjectDevtools } from "@nice-code/devtools/server";
import { serveDurableObject } from "@nice-code/action/platform/cloudflare";

constructor(ctx: DurableObjectState) {
  super(ctx, env);

  const devtools = createNiceDurableObjectDevtools(ctx, {
    runtime,                          // identity: label, clientId and coordEnvId all derived
    stage: "development",             // required — see below
    token: env.DEVTOOLS_TOKEN,        // unset ⇒ inert. No token, no protocol, no bridge, no cost.
    realms: { match: () => this.engine },  // a getter: resolved when a window attaches
    persistCounters: true,            // optional: lifetime totals survive an eviction
  });

  // Wires the wire tap and registers the devtools protocol beside the app's own.
  this.server = serveDurableObject(ctx, channel, { runtime, devtools });
}
```

A realm-only DO does the same on the wire host — `serveWireDurableObject(ctx, { identity, protocols, devtools })`, with `runtime: { coordinate: identity }` (the coordinate source is structural; no `ActionRuntime` needed).

Note there is **no `topologyId`**, and no `token ? … : undefined` conditional. An absent token means *inert*, which is still fail-closed: an unset token can only ever close the door. And because the window dials *in*, any number of apps' windows may observe one shared DO with no configuration at all.

`realms` takes a getter because a DO routinely wires its devtools before its engines exist. It is resolved on window attach, long after the constructor returned, so either construction order is correct.

Point the window at the DO's WebSocket endpoint — from the **dev server**, which is the only place that can hold the token without publishing it:

```ts title="vite.config.ts"
import { niceDevtools } from "@nice-code/devtools-vite";

export default defineConfig(({ mode }) => {
  // Empty prefix, so an un-prefixed name is visible here. A `VITE_`-prefixed token would be inlined
  // into the app's bundle, and a devtools endpoint that fails open is a data leak, not a dev tool.
  const env = loadEnv(mode, import.meta.dirname, "");
  return {
    plugins: [
      react(),
      niceDevtools({
        backends: [{ url: "ws://localhost:8787/match/ws", token: env.DEVTOOLS_DO_TOKEN }],
      }),
    ],
  };
});
```

The plugin injects it into the **devtools window page it serves**, and nowhere else. An app tab never receives it, and a production build never sees it — the plugin is `apply: "serve"`.

A backend with no token is skipped rather than dialed. Without one the DO registers no devtools protocol at all, so a dial could never be admitted; staying away leaves it an honest "not reporting" node in the topology. The window's dial is owned by the wire client — reconnection is its keep-alive ladder, and every link-up (first attach, redial, or a re-admission after the DO wakes) triggers an immediate `hello`, so a rewoken backend re-attaches at once instead of waiting out the heartbeat.

### The hibernation caveat, stated plainly

While a devtools window is attached, the bridge holds a heartbeat timer and the window's own heartbeat re-wakes an evicted DO. **Attached window ≈ DO awake.** That is inherent to observing a thing that only exists when observed, and it is why this is a dev tool.

Detached, it costs exactly nothing: no timers, no sockets, no projection work. A started-but-unattached bridge arms **zero** intervals — a single pending timer would prevent hibernation forever.

### Counters across an eviction

A DO's in-memory counters die with it. Two honest options:

- **Default:** they restart, and the MAX view says so — `⟳ counters reset (host woke)`. Nothing pretends to be a lifetime total.
- **`persistCounters: true`:** a compact rollup (lifetime totals + per-client totals, not the 1-second ring) is flushed when the last observer detaches and restored on wake. The rolling windows and the graph still restart — only the all-time numbers continue. Off by default: it is a storage write on a path that otherwise costs nothing, and traffic between the last detach and an eviction is not captured.

## Safety

A server scope can be observed over a socket, so the defaults assume it will be:

- **`stage` is required, and `"production"` disables everything.** workerd has no `NODE_ENV` to infer from, and a devtools endpoint that fails *open* is not a devtools endpoint. (An absent `token` is *also* fail-closed: it can only ever close the route, never open it — which is why the wrapper treats it as "devtools off" rather than a crash.)
- **The token is compared in constant time**, and a missing token is a construction error, not a warning.
- **Payload contents never leave the process by default.** `actionDomainScope` streams action id, domain, status, timings and error *shape* — not `input`, `output`, or error payloads. Pass `logPayloads: true` deliberately, in dev, when you need the values.

This is a **localhost / `wrangler dev`** feature. Exposing it to a deployed environment needs short-lived authenticated sessions and a build-time strip, neither of which exists yet.

## Reading the topology

Backends and clients are joined on the **peer** each client dials, not on a shared realm id — two backends may serve the same realm (a durable board on a DO beside an ephemeral one on a plain server), and guessing draws the traffic on the wrong wire.

A backend this window is not hearing from appears as a **dashed placeholder node**. It is not a ghost: the flow animating beside its wire is measured at the client, so those bytes are real. Click it and it tells you which of two things is true — the badge says so too:

- **`backend · not reporting`** — never heard from. Either no devtools host is attached to it, or it is a **per-instance** Durable Object (one per game, match, room) whose endpoint this window was never told to dial, because only the instances named in `backends` are dialed. Attach a host, or dial the instance, and it becomes a selectable backend with its own Server view.
- **`backend · went quiet`** — it *was* reporting and stopped. Either the backend went down, or the devtools window sat in the background long enough for its bridge to detach. The second case heals itself: bring the window to the front and the backend returns within a second.

That second state is worth understanding, because it is normal and it is not a bug. A producer's bridge stops projecting after 45s without a `hello` from any window — that detachment is exactly what lets a Durable Object hibernate instead of billing you to watch itself idle. A window whose page is hidden has its timers throttled by the browser to roughly once a minute, so its heartbeat cannot hold the bridge open, and after 30s of silence the window forgets the producer. Neither side is wrong. Recovery is an **event**, not a timeout: the window re-`hello`s the instant its page becomes visible again, and every bridge re-attaches and replays over the socket it never closed.

Flow lanes run *beside* each wire — green marching toward the backend is the client's egress, blue coming back is its ingress — with width, opacity and speed scaling logarithmically with the rate, so a keepalive trickle and a cursor storm both read honestly.

---

# The Devtools Window

Source: /devtools/window
Description: Pop the nice-code devtools out of your app into their own window — one window, many clients, a live topology of frontends and backends, wire traffic, and an event log that navigates.

Docked panels fight your app for screen space and vanish on reload, so nice-code has none. Instead, your app **produces** a devtools stream, and a separate page **consumes** it.

That one change buys a lot. The window survives app reloads. It mirrors **several clients at once** — two tabs, a private window, a phone on your LAN, and your *backend* — instead of one page's panels. And because the backend is just another client, the window can draw the **topology**: which frontends are talking to which servers, over which realms.

```
┌─ topology ────────────────────────────────────────────────────────┐
│  CLIENTS                                        SERVERS            │
│  ● web_app · a3f9·b1  ──────── realm ─────────▶ 🖥 match-api        │
│  ◐ web_app · c2e1·d4  ──────── realm ─────────▶    demo_board · 3   │
└───────────────────────────────────────────────────────────────────┘
┌────┬──────────────────────────────────┬───────────────────────────┐
│ ⚡ │                                  │  traffic · all wire       │
│ 🧩 │        the selected tool         │───────────────────────────│
│ 🌐 │                                  │  event log                │
│ 🖥 │                                  │                           │
└────┴──────────────────────────────────┴───────────────────────────┘
```

## Setup, in one call

Install the devtools and the Vite plugin:

```sh
bun add @nice-code/devtools
bun add -d @nice-code/devtools-vite
```

Add the plugin to your Vite config. It serves the devtools window page and runs the relay:

```ts title="vite.config.ts"
import { niceDevtools } from "@nice-code/devtools-vite";

export default defineConfig({ plugins: [react(), niceDevtools()] });
```

Then wire your app's devtools in one place:

```ts title="src/devtools.ts"
import { createNiceDevtools } from "@nice-code/devtools";

export const devtools = createNiceDevtools({
  topologyId: "my-app",        // names the devtools topology this app belongs to
  runtime: getRuntime,         // an ActionRuntime, or a getter for one
  domains: [act_root],         // the ROOT action domains to observe
  stores: { UserStore },       // the stores the State panel lists
});
```

That call builds the four cores — actions, state, realms, wire traffic — starts the bridge that streams them, and hands back the three seams your code plugs into:

```tsx
connectChannel(runtime, channel, { wireTap: devtools.wireTap });   // per connection
connectRealm(gameRealm, { devtools: devtools.realm("game") });      // per realm
<devtools.LauncherButton />                                          // once, anywhere
```

That is the whole setup. There is no `devtools.html` to commit, no window entry module, no second `rollupOptions.input`.

:::note[What `createNiceDevtools` does in production]
Nothing. `enabled` is `false`, no core is constructed, `wireTap` and `realm()` return `undefined`, and the launcher renders `null`. Passing `undefined` is what makes `connectRealm` and `connectChannel` skip the observation work entirely rather than measure frames into a sink.
:::

## The two halves

**The producer** is your app. One host composes each module's neutral scope and streams them. `createNiceDevtools` assembles it for you; reach for the seam underneath only to contribute a scope the four cores don't cover:

```ts
import { createClientDevtoolsHost, createBroadcastChannelTransport, trafficSampleScope } from "@nice-code/devtools-core";
import { actionBridgeScope } from "@nice-code/action/devtools/browser";
import { realmBridgeScope } from "@nice-code/realm/devtools/browser";
import { stateBridgeScope } from "@nice-code/state/devtools/browser";

createClientDevtoolsHost({
  transport: createBroadcastChannelTransport("my-app"),
  clientId: runtime.coordinate.insId ?? "my-app",   // a fresh id per page-load distinguishes tabs
  getLabel: () => runtime.coordinate.stringId,      // read live: `perId` fills in after the handshake
})
  .contribute(actionBridgeScope(actionDevtools))
  .contribute(stateBridgeScope(stateDevtools))
  .contribute(realmBridgeScope(realmDevtools).snapshot)
  .contributeSample(trafficSampleScope("traffic", trafficDevtools))
  .start();
```

It is dev-gated, and **idle until a window attaches**: with nothing listening, the bridge subscribes to no scope and projects nothing. That matters more than it sounds — a realm's projected view is a structured clone per patch tick, and paying for it with no reader is exactly the cost this design refuses.

**The consumer** is a second page on your app's origin — same origin is what lets its `BroadcastChannel` pair with your bridge — which never boots your app runtime. It builds the same transport, tracks every producer it hears, and renders the unchanged panels. The `niceDevtools()` plugin serves it at `/__nice_devtools/window`, and the launcher opens it with your topology id in the query string. That is how one plugin serves any number of apps, and why the page needs no per-app build step.

If you are not using Vite, host the page yourself. It is one line, and the app points at it with `windowUrl`:

```ts title="devtools.html → devtools.ts"
import { mountDevtoolsWindow } from "@nice-code/devtools/window";

mountDevtoolsWindow();   // reads the topology id from its own URL
```

## Many clients, one window

Every message a producer sends carries an identity envelope: `clientId`, a live `label` derived from its runtime coordinate, its `env`, and its `kind` (`frontend` / `backend`). The window lists each producer separately, and a command (`clear`, `pause`) is **addressed** to one client — so clearing one tab's action log leaves the other alone.

Producers announce themselves on a heartbeat. A silent one greys out, then drops.

Pick a client from the topology band (or the fallback `<select>`) and the rail, the tool, and the sidebar all scope to it.

### Comparing side by side

The center is a flexible canvas, not a single slot. Two directions open it up, and they are deliberately exclusive — you get *many tools, one client* **or** *many clients, one tool*, never a grid of both:

- **Split** — click a second rail tool to open it *beside* the current one (Actions ‖ Realms, say), for one client — no modifier needed; clicking it again closes it. Drag the divider to resize; each combination remembers its own column widths. Press `1`–`9` to jump back to a single tool.
- **Lanes** — click the **`+`** on a second topology node (or add one from the `+ lane…` switcher) to show both clients as side-by-side **lanes** sharing one tool — two tabs' realm views next to each other, or a frontend beside its backend. The rail then switches the tool for every lane at once, and each lane carries a header with its own live in/out rate. The lanes float as distinct cards on a darker board so they never blend together, and each laned client wears a bright accent colour — on its node outline, its header chip, its lane's top edge, **and its own in-page connected chip** (see below) — so you can tell a lane, and the tab it belongs to, apart at a glance.

In lanes mode the meta sidebar aggregates: **traffic · N clients** sums the wire across the lanes, and the event log **merges** every lane's feed with a client tag on each row. A `sync selection` toggle (on by default) mirrors your selection across lanes — click an action in one and every lane selects its own latest matching call; turn it off to compare different entries.

## The layout

- **Topology band** — nodes and edges, and the selection surface. Click a card to focus that client; click its **`+`** to add it as a lane (**`−`** to remove). See below.
- **Icon rail** — ⚡ Actions · 🧩 State · 🌐 Realms · 🖥 Server. With one client, a click toggles the tool in/out of a side-by-side split; with several lanes, a click makes it the tool every lane shows. Press `1`–`9` to focus a single tool. The Server tool appears **only** for a client that advertises `server:*` scopes, so a frontend never shows an empty tab. Inactive tools stay mounted-hidden, so selection and scroll survive switching.
- **Meta sidebar** — collapsible (its chevron, a double-click on the resize handle, or `[`). Collapsed, it shrinks to a slim rail with a live rate ticker and an activity dot; expanded, scoped to the selection:
  - **traffic · all wire** (top): the [wire tap](/nice-realm/devtools/#decoded-payload-vs-true-wire-cost) — true post-encryption bytes, per lane (`action`, `realm`, `handshake`, `keepalive`, `http`) **and per client** (which connected client, or which backend, those bytes belong to — see [Observing Backends](/devtools/backends/)), defaulting to MAX (everything since the client connected) with the graph as a bounded 30-minute lens on it.
  - **event log** (bottom): a terse, grouped feed of *what caused that traffic* — an action settling, a realm write confirming, a link redialing, `keepalive × 12` collapsed into one row. Each entry is a jump-link: click it and the window switches to the causing tool **and selects the entry inside it**.

The panels' own Traffic tabs are dropped in window mode — the sidebar owns traffic, so there is no split-brain between "the action panel's traffic" and "the sidebar's traffic".

## Topology: who talks to whom

Nodes come from the identity envelope already on every frame; no extra protocol. Edges are **derived**, not declared: each realm a frontend holds reports the **peer** it dialed (its backend's coordinate `envId`), and that joins to the backend advertising the same `coordEnvId`.

Joining on the realm id alone would be ambiguous — two backends can serve one realm (a durable board on a Durable Object beside an ephemeral one on a plain server), and the traffic would be drawn on the wrong wire. So a backend should always pass `coordEnvId: runtime.coordinate.envId` to its devtools host.

A peer this window is not hearing from becomes a dashed placeholder node. It is real and it is carrying traffic — the flow beside its wire is measured at the *client* — it simply is not being heard. The badge distinguishes the two reasons: **"not reporting"** (never heard from: no devtools host attached, or a per-instance Durable Object nobody dialed) from **"went quiet"** (it was reporting and stopped — often just this window sitting in the background, which resolves the moment you bring it to the front). Click the node and it explains itself; see [Observing Backends](/devtools/backends/).

Flow lanes run beside each wire: green marching toward the backend is the client's egress, blue returning is its ingress, scaled logarithmically so a keepalive trickle and a cursor storm both read honestly. The trunk between them lights up neutral white when either end is selected, so selection never mimics or hides the flow.

Clicking a backend node switches to its [Server view](/devtools/backends/#two-lenses-and-why-they-disagree): per realm engine, ingress frames/bytes and egress **messages** (the Durable Object billing unit) vs frames, with the coalesce ratio; per action domain, what it recently ran.

For a backend to appear at all it must be a producer: a long-lived server dials the relay below, while a **Durable Object** is dialed *into* by the window — see [Observing Backends](/devtools/backends/).

## The window is the only surface

There is no in-page dock. Panels render in the window and nowhere else, so nothing competes with your app for screen space, and no hidden panel keeps re-rendering a realm tree behind the window for nobody. Your app mounts one affordance — `<devtools.LauncherButton />` — and streams its cores through the bridge.

That affordance has two faces. Detached, it is a **devtools** button. Once a window is attached there is nothing left to launch, so it becomes a **connected chip showing this client's label** — the same label the window's client switcher and topology band show for it. With three tabs open that match is the only thing that tells you which row in the window is the tab you are looking at. The chip still focuses the window on click, because a status readout that swallowed the click would strand anyone whose devtools window is buried.

When you compare several clients as lanes, the window sends each one the accent colour of its lane, and the connected chip **wears that colour** — border, dot, and label — so the chip in the corner of a tab matches its lane in the window. It falls back to its default green whenever the window shows this client alone.

`useDevtoolsWindowAttached()` reports whether a window is listening, read straight off the bridge's attach state (`host.isAttached()` / `host.onAttachedChange(…)`) rather than guessed from whether someone clicked a button. Use it to skip work that only a window would consume. `useDevtoolsClientIdentity()` gives you the `clientId` and live `label` behind the chip, and `useDevtoolsClientAccent()` gives you the lane hue (or `null`) if you want to tint an affordance of your own.

**One window per app.** The launcher routes through a single open-or-focus call. Before opening, it pings the same-origin control channel; if a window (opened from *any* tab) answers, it is brought forward instead of a second one being spawned. The window is already multi-client, so a second one would only split your view.

## Crossing browser partitions

`BroadcastChannel` reaches other tabs of the same origin *in the same browser profile*. A private window, a second profile, a different browser, or a phone on your LAN is a different storage partition and cannot be reached that way — which is also exactly why those environments show up as distinct, interesting clients.

Reaching them needs a **relay**, and the `niceDevtools()` plugin you already added runs one.

The first devtools click starts it, and every local client of that app discovers it and joins the window that is already open. Nothing to run in a second terminal, no URL to configure, and — because a client only dials once it knows a relay exists — no console noise in the many dev sessions that never open devtools at all.

Two dev servers (two apps) converge on the **same** relay rather than each hosting their own, which would re-partition clients by whichever port their app is served from. The relay lives inside whichever dev server started it and dies with it; survivors ask their own dev server to stand a new one up.

It binds `127.0.0.1` by default. For a phone on your LAN, `niceDevtools({ host: "0.0.0.0" })`.

### Without Vite

Run the relay yourself and name it explicitly. An explicit `relayUrl` always wins: the client dials it directly and asks nobody. This is the path for React Native, a non-Vite dev server, an `https` dev server (a page on `https:` may not open a `ws:` socket), or a relay on another machine.

```sh
bunx @nice-code/devtools-relay          # port 5199
```

```ts title="src/devtools.ts"
export const devtools = createNiceDevtools({
  topologyId: "my-app",
  relayUrl: "ws://localhost:5199",
  // No plugin to serve the window, so host the page yourself and say where it is.
  windowUrl: "/devtools.html",
  // …
});
```

```ts
import { createFanoutTransport, createWebSocketTransport } from "@nice-code/devtools-core";

const transport = createFanoutTransport([
  createBroadcastChannelTransport("my-app"),
  createWebSocketTransport("ws://localhost:5199?key=my-app"),
]);
```

The fanout dedups, so a same-profile peer reachable both ways still arrives once.

A **long-lived backend** joins the same room in one call. It is not a Vite client, so it cannot discover anything — but it does not need to: it dials the same well-known port, retrying quietly until a relay is there.

```ts
import { createNiceServerDevtools } from "@nice-code/devtools/server";

createNiceServerDevtools({
  topologyId: DEVTOOLS_TOPOLOGY,   // the room — the same id the frontend passes
  runtime,                         // label, clientId and coordEnvId all derived from it
  realms: { match: engine },
  // relayPort / relayUrl only when the relay isn't the local one on 5199
});
```

Pass an **array** of ids for one backend serving several apps; it joins every room. See [Observing Backends](/devtools/backends/).

`?key=` rooms unrelated apps on one relay. A **Durable Object** never dials out — see [Observing Backends](/devtools/backends/).

## Devtools in production

Devtools are a **development** tool, built to refuse production and fail **closed** — shipping a build
with devtools wired costs nothing:

- The browser handle and the server host default to enabled only when `NODE_ENV !== "production"`; in a
  production build the handles are inert and no stream is produced.
- On a Durable Object there is no `NODE_ENV` to infer from, so `createNiceDurableObjectDevtools` takes a
  **required `stage`** — `stage: "production"` (or no stage, or no token) returns an inert handle with
  **no protocol registered and nothing observable**. A devtools endpoint that failed *open* would be a
  data leak, not a devtools endpoint.
- **The token lives on the dev server, never in the app bundle.** The devtools window (which holds the
  token) is served by the `niceDevtools()` Vite plugin from dev-server config — a token in a
  `VITE_`-prefixed variable would be compiled into every client. Never do that.

## Security and gating

- **Nothing streams in a production build.** The bridge sits behind `isDevtoolsEnabled()`; `createServerDevtoolsHost` is an inert stub when `NODE_ENV === "production"`. A feature that isn't running can't be attacked.
- **Same-origin by default.** `BroadcastChannel` cannot cross an origin, so the default configuration has no network surface at all.
- **The relay is unauthenticated and ephemeral** — local/dev only. It keeps no history and logs no content. The Vite plugin only exists on the dev server and binds the relay to `127.0.0.1` unless you ask otherwise; a production build neither discovers nor dials a relay. If you name one explicitly instead, gate it behind an env var (`VITE_DEVTOOLS_RELAY_URL` / `DEVTOOLS_RELAY_URL`).
- **A port answering is not a relay answering.** Discovery checks a service marker on `/health` before it connects, so an unrelated dev server squatting `5199` produces a loud warning rather than devtools that silently never connect.
- **Sizes, not contents, on the wire lane.** The traffic layer records byte counts and frame kinds, never payload bytes. State and realm *contents* do cross the same-origin channel — the app already has them — so treat a relay pointed at anything but your own machine accordingly.

---

# What Are You Building?

Source: /getting-started/choosing
Description: A few common project shapes, and the exact nice-code packages each one needs — so you install what you'll use and start on the right page.

nice-code is a set of libraries you adopt as you need them, not a framework you buy into whole. Two
**planes** carry the work — [actions](/nice-action/mental-model/) (call functions) and
[realms](/nice-realm/mental-model/) (live shared state) — both over one secure
[connection](/nice-wire/connection/); four supporting packages fit around them. Find the row closest to
what you're building, install that set, and start where it points.

## Project shapes

| You're building… | Install | Start here | See it |
| --- | --- | --- | --- |
| **A multiplayer game / collaborative app** — presence, positions, a shared document | `@nice-code/realm` `@nice-code/wire` | [Realm quick start](/getting-started/quick-start/#live-shared-state-in-three-minutes) → [Realm Mental Model](/nice-realm/mental-model/) | [Tank Shooter](https://demo-tank-shooter.nicecode.io) |
| **A live dashboard / feed** — many viewers, server-driven updates | `@nice-code/realm` `@nice-code/wire` | [Presence Realms](/nice-realm/presence/) | [Pixel Plaza](https://demo-pixel-plaza.nicecode.io) |
| **A typed API / RPC layer** — the client calls the server, fully typed | `@nice-code/action` `@nice-code/error` + a validator | [Action quick start](/getting-started/quick-start/#a-typed-api-in-five-minutes) | [Playground](https://nice-code-demo.nicecode.io) |
| **A React app with server push** — API calls *and* the server pushing back | `@nice-code/action` `@nice-code/error` + a validator | [Bi-directional](/nice-action/bidirectional/) | [Playground](https://nice-code-demo.nicecode.io) |
| **Both — an app with an API *and* live state** | `@nice-code/action` `@nice-code/realm` `@nice-code/error` | [Both planes on one connection](/nice-realm/connecting/) | [Playground](https://nice-code-demo.nicecode.io) |
| **A React Native / Expo app** — any of the above, on-device | your set above **+** two polyfills | [React Native / Expo](/getting-started/react-native/) | — |
| **Just better errors** anywhere in TypeScript | `@nice-code/error` | [Error Domains](/nice-error/domains/) | — |
| **Just a reactive store** for local UI state | `@nice-code/state` `immer` | [Stores](/nice-state/stores/) | — |

## The supporting cast

Whichever planes you pick, these fit around them — and each stands alone if that's all you need:

- **[`@nice-code/error`](/nice-error/domains/)** — typed, serializable errors. Actions declare what
  they throw; realm rules reject with them; both ends catch the same `NiceError`. The one error
  vocabulary the whole stack speaks.
- **[`@nice-code/state`](/nice-state/stores/)** — a small Immer-backed store with fine-grained
  selectors. A realm's `store` *is* one of these, so synced and local state read identically.
- **[`@nice-code/util`](/nice-util/storage/)** — typed storage adapters (browser, Durable Object,
  memory) and the crypto that authenticates every secure connection.
- **[`@nice-code/common-errors`](/common-errors/overview/)** — ready-made validation errors + Hono
  middleware, so a bad request comes back as a typed error, not a bare 400.
- **[`@nice-code/devtools`](/devtools/window/)** — one call in dev opens a window over every action,
  realm, store, and wire frame. Inert in production.

## Hosting

Deploying to the edge? [Hosting on Cloudflare](/getting-started/cloudflare/) covers the three Durable
Object shapes (actions, realm-only, or both on one socket). Everything runs on Bun, Node, and Workers
too — the serving pages show the wiring.

---

# Hosting on Cloudflare

Source: /getting-started/cloudflare
Description: Three Durable Object shapes — actions, realm-only, or both on one socket — and which serve call each one uses.

nice-code is built for the edge, and a Cloudflare **Durable Object** is its natural home: one
addressable object per match / room / document, with hibernatable WebSockets, SQLite, and alarms. One
`serve…` call folds the whole transport stack — the secure socket, the DO-storage crypto identity + TOFU
pins, hibernation rehydrate, and the keepalive — into a call your DO's four socket events forward to.

There are **three shapes**, depending on which planes your object hosts. Pick the row that matches, and
follow the link for the complete Durable Object.

| Your DO hosts… | Serve with | Guide |
| --- | --- | --- |
| **Actions only** (typed RPC, server push) | `serveDurableObject` — `@nice-code/action/platform/cloudflare` | [Action → Cloudflare](/nice-action/cloudflare/) |
| **A realm only** (shared state, no actions) | `serveWireDurableObject` — `@nice-code/wire/platform/cloudflare`, with `hostRealm` registered on it | [Serving a Realm](/nice-realm/serving/) |
| **Both, on one socket** | `serveDurableObject` with `protocols: [realms.protocol]` | [Serving a Realm → both planes](/nice-realm/serving/) |

The realm-only shape is the leanest: a DO that imports `@nice-code/wire` + `@nice-code/realm` and
nothing else — no `ActionRuntime`, no channel — mirroring a `createWireClient` browser client exactly.
Add actions later by switching the serve call to the action host and registering the same
`realms.protocol` on it; nothing about the realm changes.

## What comes free

Whichever shape you pick, the platform integration gives you the same guarantees, none of which you
write:

- **Hibernation that's invisible.** The socket survives the DO sleeping; on wake the handshake and any
  realm resume by patch replay, not a re-download. A realm's `status` stays `live` through a wake.
- **Persistence by default** (for a durable realm). Every commit lands in the DO's SQLite patch log;
  snapshots are written on a cadence; a cold start is snapshot + tail replay. A changed schema hash
  **refuses to boot** unless you pass a `migrate` hook.
- **Identity + TOFU pins in DO storage**, so they survive hibernation — see
  [Identity & Trust](/nice-wire/identity/#on-cloudflare-persist-the-pins).

## Beyond Cloudflare

None of this is Cloudflare-locked. `createRealmServerEngine` + `createRealmAcceptor` (realm) and
`serveChannel` (actions) are host-agnostic — anything that can register a WebSocket serves them. See
[Serving a Realm → outside Cloudflare](/nice-realm/serving/#serving-outside-cloudflare) and
[Serving & Connecting](/nice-action/serving-connecting/) for Bun / Node / Hono.

---

# Introduction

Source: /getting-started/introduction
Description: What nice-code is — typed actions and live realms over one secure connection, plus the libraries they build on.

**nice-code** is a set of TypeScript libraries with one shared goal: your types stay correct everywhere your program goes — across the network, into a worker, down to storage, and inside a `catch` block. You write a type once and it follows your data the whole way.

:::tip[See it live]
Three demos are deployed on Cloudflare right now — open one in two tabs and watch the same state from both sides: [Tank Shooter](https://demo-tank-shooter.nicecode.io) (multiplayer arena), [Pixel Plaza](https://demo-pixel-plaza.nicecode.io) (shared pixel world), and [the playground](https://nice-code-demo.nicecode.io) (every feature in one app). Not sure which packages you need? [**What are you building?**](/getting-started/choosing/)
:::

## The packages

| Package | What it does |
|---|---|
| [`@nice-code/wire`](/nice-wire/connection/) | The secure connection everything rides — one self-healing, authenticated link that actions and realms multiplex over. |
| [`@nice-code/action`](/nice-action/mental-model/) | Call a function on another machine as if it were local — fully typed. |
| [`@nice-code/realm`](/nice-realm/mental-model/) | Live, authoritative shared state — many clients watch and optimistically write one server-owned tree. |
| [`@nice-code/error`](/nice-error/domains/) | Errors you can type, send over the network, and match on by name. |
| [`@nice-code/state`](/nice-state/stores/) | A small state store (built on Immer) that only re-renders the parts that changed. |
| [`@nice-code/common-errors`](/common-errors/overview/) | Ready-made validation errors + Hono middleware. |
| [`@nice-code/util`](/nice-util/storage/) | Typed storage helpers and crypto helpers. |

**Two planes, one connection.** [`@nice-code/action`](/nice-action/mental-model/) (call functions) and [`@nice-code/realm`](/nice-realm/mental-model/) (sync state) are the two things you build with — equal siblings, not a main package and an add-on. Both ride a single secure connection from [`@nice-code/wire`](/nice-wire/connection/), so an app that uses both multiplexes them over one socket. Use one plane or both: an actions app opens the connection with `connectChannel`, and a realm-only app opens it with `createWireClient` and [needs no actions at all](/nice-realm/connecting/#realm-only-apps--createwireclient). The rest fit around them — actions describe their errors with error domains, secure connections use the crypto helper from util, and validation failures come back as common-errors.

## How they fit together

The example below shows the core idea. An action is a single shared definition — imported by **both** the client and the server — that describes one function's input, its output, and the errors it can throw:

```ts
// Both the client and the server import this exact definition.
export const act_user = act_app.createChildDomain({
  domain: "act_user",
  actions: {
    getUser: actionSchema()
      .input({ schema: v.object({ userId: v.string() }) })
      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
      .throws(err_user, ["not_found"]),   // ← an error domain from @nice-code/error
  },
});

// Call it from anywhere. The output is typed, and so are the errors you can catch.
const user = await act_user.action.getUser
  .request({ userId: "u_1" })
  .runToOutput();
```

## What nice-code is not

- **Not a validator.** Bring your own — [Valibot](https://valibot.dev), Zod, or any [Standard Schema](https://github.com/standard-schema/standard-schema) library — to check data at the edges.
- **Not an HTTP framework.** Actions can travel over WebSocket, HTTP, in-memory, or WebRTC, and they plug into Hono, Workers, Node, Bun, and Durable Objects.
- **Not magic.** Each library is small, easy to read, and has very few dependencies.

## Feeding the docs to an AI assistant

The whole documentation site is also published as a single plain-text file at [`/llms.txt`](/llms.txt) — every page concatenated, frontmatter stripped, each section labelled with its route. Point a local AI coding assistant at it (or paste it into a chat) to give the model the library's entire API surface as context in one shot, so its suggestions match how nice-code actually works. It's regenerated on every docs build, so it never drifts from the pages you're reading.

If you're only using one package, there's a smaller, focused file per module — point your agent at just the one you need:

| Package | File |
|---|---|
| [`@nice-code/wire`](/nice-wire/connection/) | [`/llms-wire.txt`](/llms-wire.txt) |
| [`@nice-code/action`](/nice-action/mental-model/) | [`/llms-action.txt`](/llms-action.txt) |
| [`@nice-code/realm`](/nice-realm/mental-model/) | [`/llms-realm.txt`](/llms-realm.txt) |
| [`@nice-code/error`](/nice-error/domains/) | [`/llms-error.txt`](/llms-error.txt) |
| [`@nice-code/state`](/nice-state/stores/) | [`/llms-state.txt`](/llms-state.txt) |
| [`@nice-code/util`](/nice-util/storage/) | [`/llms-util.txt`](/llms-util.txt) |
| [`@nice-code/common-errors`](/common-errors/overview/) | [`/llms-common-errors.txt`](/llms-common-errors.txt) |

---

# Quick start

Source: /getting-started/quick-start
Description: Install nice-code, define a typed error domain, and wire up your first action.

## Pick your first win

nice-code gives you **two typed planes over one connection**, and you can start with either:

- **A typed API** — call server functions from the client with full inference and typed errors.
  That's [`@nice-code/action`](#a-typed-api-in-five-minutes), below. Start here for RPC, forms, CRUD,
  server push.
- **Live shared state** — many clients watch and optimistically write one server-owned tree. That's
  [`@nice-code/realm`](#live-shared-state-in-three-minutes), and it needs **no actions at all**. Start
  here for multiplayer, presence, collaborative docs, live dashboards.

Not sure? [**What are you building?**](/getting-started/choosing/) maps a few project shapes to the
modules they need. Either track below is a complete, runnable round trip.

## Install

```bash
# a typed API (actions) — build on errors + a Standard Schema library
bun add @nice-code/action @nice-code/error valibot

# live shared state (a realm-only app) — wire opens the connection, realm rides it
bun add @nice-code/realm @nice-code/wire

# both planes on one connection
bun add @nice-code/action @nice-code/realm @nice-code/error valibot

# the extras, as you reach for them
bun add @nice-code/state immer        # a reactive store
bun add @nice-code/error              # typed errors on their own
```

## A typed API in five minutes

`@nice-code/action` gives you typed calls across the network. A typical app is just three files:

- **`shared.ts`** — imported by both sides. Describes your actions, how they're routed, and the runtime coordinates that label each side.
- **`server.ts`** — the side that **listens** for calls (the *acceptor*).
- **`client.ts`** — the side that **dials in** and makes calls (the *connector*).

Each action says which errors it can throw. The `err_user` used below is defined in
[the error section further down](#nice-codeerror-in-two-minutes).

### 1. Shared — your actions, routing, and coordinates

```ts title="shared.ts"
import { createActionRootDomain, actionSchema, defineChannel, RuntimeCoordinate } from "@nice-code/action";
import * as v from "valibot";
import { err_user } from "./errors";

// Runtime coordinates label each side. They live in shared code so BOTH sides
// reference the exact same values — in a larger app, give them their own
// `runtimeCoordinates.ts` (they're independent of how you channel your actions).
export const serverCoord = RuntimeCoordinate.env("backend");
export const frontendCoord = RuntimeCoordinate.env("frontend");

// A root domain is just a top-level namespace to hang your actions off of.
export const act_app = createActionRootDomain({ domain: "act_app" });

// Group related actions into a domain. Both sides import this.
export const act_user = act_app.createChildDomain({
  domain: "act_user",
  actions: {
    getUser: actionSchema()
      .input({ schema: v.object({ userId: v.string() }) })
      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
      .throws(err_user, ["not_found"]),
  },
});

// A channel lists which actions travel in each direction.
export const appChannel = defineChannel({
  toAcceptor: [act_user],   // calls the client sends to the server
  toConnector: [],          // calls the server pushes to the client (none yet)
});
```

### 2. Server — write the code that runs, then start listening

```ts title="server.ts"
import { ActionRuntime, serveChannel, httpAcceptorCarrier } from "@nice-code/action";
import { createMemoryStorageAdapter_json } from "@nice-code/util";
import { appChannel, act_user, serverCoord } from "./shared";
import { err_user } from "./errors";

const serverRuntime = new ActionRuntime(serverCoord);

// Fill in the actual implementation for each action in the domain.
const userHandler = act_user.wrapAsLocalHandler({
  getUser: async ({ userId }) => {
    const user = await db.users.find(userId);
    if (!user) throw err_user.fromId("not_found", { userId });
    return user;
  },
});

// Start listening. One HTTP carrier is the whole backend — `server.fetch` is a standard
// web fetch handler, so Bun / Deno / Workers serve a default `{ fetch }` export directly.
const server = serveChannel(serverRuntime, appChannel, {
  storage: createMemoryStorageAdapter_json(),   // holds the server identity + trusted-client key pins —
                                                // in-memory is fine for dev; use persistent storage in
                                                // production or a restart forgets both
  handlers: [userHandler],
  carriers: [httpAcceptorCarrier()],
});

export default { fetch: server.fetch };          // run it: `bun run server.ts`
```

> Want a live socket and server-to-client push? Add a `wsAcceptorCarrier` alongside the HTTP one
> — see [Serving & Connecting → WebSockets](/nice-action/serving-connecting/#websockets--adding-server-push)
> for the Bun and Hono wiring.

> **Note for Edge/Serverless:** This example builds the runtime and calls `serveChannel` in module/global
> scope, which is fine for a long-lived Node or Bun process. Edge runtimes like Cloudflare Workers and
> Durable Objects forbid I/O and random ID generation (e.g. `crypto.randomUUID()`) at the top level — code
> there only runs inside a request or inside the object's lifecycle. In those environments, build the
> runtime and call `serveChannel` **lazily**, on the first request or in the Durable Object's constructor,
> not in global scope. See [Cloudflare Durable Objects →](/nice-action/cloudflare/) for the exact shape.

### 3. Client — connect once, then call from anywhere

```ts title="client.ts"
import { ActionRuntime, connectChannel, wsCarrier, httpCarrier } from "@nice-code/action";
import { createWebLocalStorageAdapter } from "@nice-code/util";
import { appChannel, act_user, serverCoord, frontendCoord } from "./shared";

const clientRuntime = new ActionRuntime(frontendCoord);

// Holds this client's crypto identity and the server keys it has met (see Security levels).
// Must be a *durable* store — the server pins this client's verify key on first contact, so an
// identity that regenerates every page load is rejected after the first reload. Memory adapters
// are for tests only.
const storage = createWebLocalStorageAdapter({ localStorage, keyPrefix: "client:" });

// Connect to the server. Try WebSocket first, fall back to HTTP.
connectChannel(clientRuntime, appChannel, {
  peer: serverCoord,
  storage,
  transports: [
    { carrier: wsCarrier(() => ({ url: "wss://api.example.com/ws" })) },
    { carrier: httpCarrier(() => ({ url: "https://api.example.com/action" })) },
  ],
});

// Call the action. You get back a typed `user`.
const user = await act_user.action.getUser
  .request({ userId: "u_1" })
  .runToOutput();
```

That's the whole round trip. If you'd rather get a return value than a thrown error (check a result
instead of writing `try`/`catch`), see [Error Handling →](/nice-action/error-handling/).

## @nice-code/error in two minutes

This is the error domain the action above throws from. You describe each error once — its name, its extra
data, and its HTTP status — and from then on it's fully typed both where you throw it and where you catch it.

### Define a domain

```ts title="errors.ts"
import { defineNiceError, err } from "@nice-code/error";

export const err_user = defineNiceError({
  domain: "err_user",
  schema: {
    not_found: err<{ userId: string }>({
      message: ({ userId }) => `User not found: ${userId}`,
      httpStatusCode: 404,
      context: { required: true },
    }),
    account_locked: err({
      message: "Account is locked",
      httpStatusCode: 403,
    }),
  },
});
```

### Throw, catch, narrow

```ts
import { castNiceError } from "@nice-code/error";

throw err_user.fromId("not_found", { userId: "u_1" });

// On the receiving side — castNiceError always returns a NiceError
const caught = castNiceError(e);
if (err_user.isExact(caught) && caught.hasId("not_found")) {
  const { userId } = caught.getContext("not_found"); // typed
}
```

## Live shared state in three minutes

Actions are for *things that happen*; a **realm** is for *state that many parties watch* — one
server-owned tree that clients observe live and write optimistically, with the server enforcing the
rules. A realm needs **no actions**: `@nice-code/wire` opens the connection, `@nice-code/realm` rides
it. You attach as an **avatar** — your identity inside the realm.

### 1. Define the realm — imported by client and server

```ts title="shared/gameRealm.ts"
import { defineRealm, t } from "@nice-code/realm";
import { err_game } from "./errors";   // a typed domain, defined exactly like err_user below

export const gameRealm = defineRealm({
  id: "game_realm",
  avatars: { player: { persistentId: t.string() } },
  state: {
    players: t.record(t.id("playerId"), t.object({ x: t.number(), y: t.number() })),
  },
  rules: (r) => [
    r.path("players.$playerId.{x,y}")
      .view(r.everyone)                                   // everyone sees every player
      .alter(({ avatar, params }) =>                      // only you may move yours
        avatar.persistentId === params.playerId || err_game.fromId("not_yours")),
  ],
});
```

### 2. Client — open the connection, attach, write

```ts title="client.ts"
import { createWireClient, wsCarrier } from "@nice-code/wire";
import { connectRealm, realmConnection } from "@nice-code/realm";
import { createWebLocalStorageAdapter } from "@nice-code/util";
import { gameRealm, serverCoord, frontendCoord } from "./shared";

// One secure connection — no ActionRuntime, no channel. `storage` must be durable (see below).
const client = createWireClient({
  identity: frontendCoord,
  peer: serverCoord,
  storage: createWebLocalStorageAdapter({ localStorage, keyPrefix: "game:" }),
  transports: [{ carrier: wsCarrier(() => ({ url: "wss://api.example.com/realm/ws" })) }],
});

const realm = connectRealm(gameRealm, {
  avatar: { type: "player" },                    // identity defaults from the secure handshake
  connection: realmConnection(client),           // ← the wire client above; no actions needed
});

// `myId` is your avatar's persistentId (from the authenticated identity). The rule lets you write
// only your own entry — instant locally, confirmed (or rolled back) by the server.
realm.update((draft) => { draft.players[myId].x = 412; });
```

Every other connected client sees that write land live. **With actions too?** Open the connection with
`connectChannel` instead and pass its connector to `realmConnection(...)` — the realm shares that one
socket. Everything else is identical.

### 3. Server — host the realm

On Cloudflare, one call serves the sockets and hosts the realm — persistence and hibernation come free:

```ts title="GameDO.ts"
import { serveWireDurableObject } from "@nice-code/wire/platform/cloudflare";
import { hostRealm, serveRealmDurableObject } from "@nice-code/realm/platform/cloudflare";
import { gameRealm, serverCoord } from "./shared";

// inside your Durable Object:
const realms = serveRealmDurableObject(this.ctx, {
  realms: { game_realm: hostRealm(gameRealm, { avatarType: "player" }) },
});
const server = serveWireDurableObject(this.ctx, {
  identity: serverCoord.specify({ insId: this.ctx.id.toString() }),
  protocols: [realms.protocol],
});
// forward: fetch → server.fetch · webSocketMessage → server.receive · close/error → server.drop
```

That's the whole loop. [Serving a Realm →](/nice-realm/serving/) covers hosting (including outside
Cloudflare), and [Realm Mental Model →](/nice-realm/mental-model/) takes the concepts from here.

## See it running

Everything above is deployed live on Cloudflare — real Durable Objects, real hibernation, real
reconnects. Open one in two tabs and watch the same realm from both sides:

- **[Tank Shooter](https://demo-tank-shooter.nicecode.io)** — a real-time multiplayer arena on one
  realm; reload mid-match and it drops you straight back in.
- **[Pixel Plaza](https://demo-pixel-plaza.nicecode.io)** — a shared pixel world with live presence.
- **[The playground](https://nice-code-demo.nicecode.io)** — every feature in one place: actions over
  HTTP and WebSocket at three security levels, live realm boards, stores, and typed errors.

---

# React Native / Expo

Source: /getting-started/react-native
Description: Run the whole stack on React Native (Hermes) — actions and realms both — with two standard polyfills the connection layer needs.

Everything in nice-code runs on React Native. The libraries use only **standard** web interfaces —
never browser-only APIs — so the same code that runs in the browser, Node, and Cloudflare Workers runs
on Hermes too. Because the connection layer is shared, unblocking it unblocks **both planes**: typed
[actions](/nice-action/mental-model/) and live [realms](/nice-realm/mental-model/) work identically
on-device.

Hermes is missing two standard interfaces the secure connection relies on. You polyfill them once —
there's nothing nice-code-specific to install.

## What's missing on Hermes

- **WebCrypto** (`crypto.subtle`) — the handshake and encryption need Ed25519 / X25519 / HKDF /
  AES-GCM.
- **`URL`** — Hermes' built-in `URL` is incomplete; carriers use it to build WebSocket / HTTP urls.

## Setup

Install the two polyfill packages:

```bash
bun add react-native-quick-crypto react-native-url-polyfill
```

Run them as the **very first** side-effect of your app entry — before any connection, `ActionRuntime`,
or realm is constructed (so `global.crypto` and `URL` already exist by the time the library touches
them):

```ts title="polyfills.ts"
// `URL` is incomplete in Hermes — fix it first.
import "react-native-url-polyfill/auto";

import { install } from "react-native-quick-crypto";

// Patches `global.crypto` with OpenSSL-backed WebCrypto (SubtleCrypto).
install();
```

```ts title="index.js"
// Import the polyfills before anything else (e.g. before "expo-router/entry").
import "./polyfills";
import "expo-router/entry";
```

`react-native-quick-crypto` compiles OpenSSL through Nitro / JSI, so it needs the **new architecture**
enabled and a recent deployment target (iOS 16.4+, Android `minSdkVersion` 24+). Configure that via
`expo-build-properties` if you're on Expo.

That's the whole requirement. The crypto identity, secure WebSocket, HTTP exchange, **and realms** all
work from there exactly as they do on every other platform.

:::tip[Working reference — actions *and* realms]
The `demo-expo-frontend` package in the repo is a complete, runnable Expo app wired this way
(`src/polyfills.ts` + `index.js`). It exercises the WebSocket, HTTP carrier, encrypted security level,
backend push, **and a live realm board** on-device — the nice-realm tab connects a durable realm over
`createWireClient` and syncs presence + notes in real time.
:::

## Storage on React Native

The crypto identity is persisted through a `StorageAdapter` — and on a secure connection this store
**must be durable**, or the pinned identity is rejected after the first launch (see
[Identity & Trust](/nice-wire/identity/#your-storage-must-be-durable--the-mistake-that-bites)). On the
web that's `localStorage`; on React Native, back it with
[`@react-native-async-storage/async-storage`](https://github.com/react-native-async-storage/async-storage):

```ts title="async_storage.ts"
import { EStorageAdapterType, type IStorageAdapterMethods_String } from "@nice-code/util";
import AsyncStorage from "@react-native-async-storage/async-storage";

export const asyncStorageMethods: IStorageAdapterMethods_String = {
  type: EStorageAdapterType.string,
  setItem: (key, value) => AsyncStorage.setItem(key, value),
  getItem: (key) => AsyncStorage.getItem(key),
  removeItem: (key) => AsyncStorage.removeItem(key),
};
```

Wrap it in a `StorageAdapter` and pass it as the `storage` on `createWireClient` (realm-only) or
`connectChannel` (with actions) — the same way the web demo passes a `localStorage`-backed adapter.

:::caution[Hermes codegen gotcha]
Never inline an `await`ed call as an object-literal property inside a ternary branch on Hermes — it can
silently evaluate to `undefined` at runtime (it type-checks and bundles fine). Hoist the `await` to a
`const` first. This is a Hermes quirk, not a nice-code one, but it broke the secure handshake once —
worth knowing if you touch the connection setup.
:::

---

# nice-code

Source: /
Description: One secure connection, two typed planes — call functions with actions, share live state with realms, and keep every type true from throw to catch.

import Landing from "../../components/Landing.astro";

<Landing />

---

# Bi-directional

Source: /nice-action/bidirectional
Description: Push actions from the acceptor back to the connector over the same socket.

Over a **duplex** connection (like a WebSocket), the listening side can call the dialing side back on the _same_ open connection — no second connection, and no polling for updates.

## How it works

1. **Put the push domain in the channel's `toConnector`** (in shared code, so both sides agree).
2. **On the dialing side**, answer those pushes with `connectChannel`'s `onPush` — one entry per action, fully typed from the channel. Your reply goes straight back over the same connection.
3. **On the listening side**, call `server.pushToClient(...)` to reach one client, or a handler's `broadcast(...)` to reach everyone. To know who originally called you, read `action.context.originClient`.

## Shared channel

```ts title="shared.ts"
export const act_lobby = act_app.createChildDomain({
  domain: "act_lobby",
  actions: {
    start_feed: actionSchema()
      .input({ schema: v.object({ count: v.number() }) })
      .output({ schema: v.object({ delivered: v.number() }) }),
    position_update: actionSchema()
      .input({ schema: v.object({ player: v.string(), x: v.number(), y: v.number() }) })
      .output({ schema: v.object({ acknowledged: v.boolean() }) }),
  },
});

export const appChannel = defineChannel({
  toAcceptor: [act_user, act_lobby],  // start_feed goes this way (client → server)
  toConnector: [act_lobby],           // position_update pushes back this way (server → client)
});
```

## Dialing side — answer the pushes

```ts title="client.ts"
connectChannel(clientRuntime, appChannel, {
  peer: serverCoord,
  storage,
  transports: [{ carrier: wsCarrier(() => ({ url: wsUrl })) }],
  onPush: {
    position_update: async ({ player, x, y }) => {
      renderPlayer(player, x, y);
      return { acknowledged: true };
    },
  },
});
```

## Listening side — push back

A handler reads `action.context.originClient` to find out who called, then pushes to them:

```ts title="server.ts"
const lobbyHandler = createLocalHandler().forDomainActionCases(act_lobby, {
  start_feed: async (action) => {
    let delivered = 0;
    for (let seq = 0; seq < action.input.count; seq++) {
      const running = server.pushToClient(
        action.context.originClient,
        act_lobby.action.position_update.request({ player: "alice", x: 1, y: 2 }),
      );
      await running.waitForResultPayload(); // wait for the client's reply, just like any action
      delivered++;
    }
    return { delivered };
  },
});
```

## Sending to everyone at once

Use `server.broadcast` to push to every connected client (fire-and-forget). You can skip the original sender, or only target some connections:

```ts
server.broadcast(
  () => act_lobby.action.position_update.request({ player: "system", x: 0, y: 0 }),
  { except: originWs, where: (ws) => server.connections.get(ws)?.role === "player" },
);
```

> **Pushes are best-effort — even for `.reliable()` actions.** [Reliable delivery](/nice-action/reliable-delivery/)
> engages on the *dialing* side's sends, not on server pushes: `pushToClient` and `broadcast` make one
> attempt over the live socket, and a client that's offline simply isn't reached. For a single push that
> needs confirmation, await `waitForResultPayload()` and retry; for a push stream that must all arrive, see
> [the direction note](/nice-action/reliable-delivery/#one-direction--pushes-are-best-effort) for the
> persisted-log pattern.

## When a handler needs the connection itself

Sometimes a handler needs the actual **connection** — to add it to a room, or to remember some per-connection state. For that, pass `channelCases` to `serveChannel` / `serveDurableObject`. Each case gets the request **and** an `IConnectionContext`:

```ts
channelCases: {
  join: (action, conn) => {
    conn.setState(action.input);                           // remember typed state for this connection
    conn.broadcast(() => act_lobby.action.player_joined.request(action.input), { exceptSelf: true });
    return { players: roster() };
  },
}
```

`conn` gives you `state` / `setState` / `clearState`, `broadcast({ exceptSelf })`, `pushBack(request)`, and `connection` (the raw socket — it's `null` on the HTTP path, which has no live connection).

## Advanced — `clientEnv` (most apps never set this)

`serveChannel` takes an optional `clientEnv`. It's easy to misread it, so here's exactly what it is and isn't.

**It is not a filter.** Setting `clientEnv` does **not** restrict who may connect, and it does **not** make the acceptor "belong to" one kind of client. One `serveChannel` always accepts every kind of client, whether you set `clientEnv` or not.

**It does not reach disconnected clients.** Pushing to a client that has no live connection simply fails — there's no queue and no store-and-forward. So `clientEnv` can't "deliver to an offline client"; nothing can.

Concretely, the failure surfaces on the push's running action, not as a silent no-op. `await running.waitForResultPayload()` **rejects**: the promise throws a `NiceError`. Because the failure happens below the action layer (the socket is gone, there's no declared error for it), it comes back as an *unhandled* error — `error.isUnhandled === true` — rather than one of the action's `.throws()` errors. Guard it like any other transport failure:

```ts title="server.ts"
import { castNiceError } from "@nice-code/error";

const running = server.pushToClient(originClient, act_lobby.action.position_update.request(pos));
try {
  await running.waitForResultPayload();
} catch (e) {
  const err = castNiceError(e);
  if (err.isUnhandled) {
    // client was offline / the connection dropped — nothing was delivered
  }
}
```

**What it actually does:** every reply and every push to a *connected* client travels back over the very connection that client is on — automatically, with nothing to configure. `clientEnv` only comes into play in one narrow setup: when a **single runtime runs more than one acceptor** (say a WebSocket acceptor *and* a WebRTC acceptor side by side) and the runtime has to decide *which* of those sibling acceptors a return should go through. `clientEnv` labels each acceptor with the kind of client it's meant for, so that choice is deterministic instead of arbitrary.

**So, the rule of thumb:**

- One acceptor on the runtime → leave `clientEnv` unset. It changes nothing.
- Multiple acceptors on one runtime, serving different kinds of client → set `clientEnv` on each, matching the client env it serves, to pin return routing.

```ts
// Only meaningful when several acceptors share one runtime:
const server = serveChannel(runtime, appChannel, {
  storage: storageAdapter,
  handlers: [userHandler],
  clientEnv: RuntimeCoordinate.env("frontend"), // this acceptor serves "frontend" clients
  carriers: [wsAcceptorCarrier({ send: (ws, frame) => ws.send(frame) })],
});
```

---

# Calling Actions

Source: /nice-action/calling
Description: Run actions and read their output — the same on any side of the connection.

Once your runtime is set up, calling an action looks the same on **any** side — client or server — and it doesn't matter whether the action runs right here or over on a peer. You call it the same way either way.

## Just get the result

The everyday case: run the action and get its output back. It throws if the action fails — whether that's a declared error or a connection problem.

```ts
const output = await act_user.action.getUser
  .request({ userId: "u_123" })
  .runToOutput();

console.log(output); // { id: "u_123", name: "Alice" }
```

## Keep a handle on the running call

If you want to track progress or be able to cancel, hold onto the `RunningAction` and wait for its full result:

```ts
const running = await act_user.runAction(
  act_user.action.getUser.request({ userId: "u_123" }),
);

const result = await running.waitForResultPayload();
console.log(result.output);
```

## Handling errors where you call

Any error you listed with `.throws(domain, ids?)` comes back fully typed. Use `castNiceError` and the domain's checks to narrow down which one it is:

```ts
import { castNiceError } from "@nice-code/error";

try {
  const output = await act_user.action.getUser.request({ userId }).runToOutput();
} catch (e) {
  const error = castNiceError(e);
  if (err_user.isExact(error) && error.hasId("not_found")) {
    console.log("User not found:", error.getContext("not_found").userId);
  }
}
```

This `request(...).runToOutput()` shape is the same whether the action runs locally (a handler in this runtime) or remotely (over a connection to a peer) — the runtime figures out where it needs to go.

## Getting a result back instead of a throw

`runToResult()` hands you the outcome as a value instead of throwing. You check `expected` (did this action
say it could throw this error?) rather than wrapping every call in `try`/`catch`:

```ts
const result = await act_user.action.getUser.request({ userId }).runToResult();
if (result.ok) use(result.output);
else if (result.expected) handleDeclared(result.error);
else report(result.error); // an error this action didn't declare, or an unexpected crash
```

This is the recommended path — see [Error Handling →](/nice-action/error-handling/) for the full model
(`expected` vs `isUnhandled`, the typed `isExpectedError` guard, and how it surfaces in devtools).

> Actions defined with [`.reliable()`](/nice-action/reliable-delivery/) call exactly the same way — the only
> differences are *when* the promise settles (it retries across reconnects instead of failing fast) and an
> optional per-call `streamKey` on `.run()` / `.runToOutput()` to keep independent streams (one per room,
> per entity) separately ordered.

---

# Channels

Source: /nice-action/channels
Description: Declare what flows in each direction between two runtimes — once.

A **channel** lists which actions flow in each direction between two apps. You write it once in shared code, and both sides use that same list — so neither side has to repeat itself or risk getting out of sync.

- **`toAcceptor`** — actions the connector **sends to** the acceptor (a normal request: client asks, server answers).
- **`toConnector`** — actions the acceptor **pushes to** the connector (the server calling the client). A domain can be in both lists if calls go both ways.

```ts title="shared.ts"
import { defineChannel } from "@nice-code/action";

export const appChannel = defineChannel({
  toAcceptor: [act_user, act_lobby],  // client → server requests
  toConnector: [act_lobby],           // server → client pushes (act_lobby goes both ways)
});
```

## The channel keeps both sides in sync

A channel holds two things: **the routing** (the `toAcceptor` / `toConnector` lists) and a compact **binary format** it uses to send actions over the wire, plus a version number worked out from your domains. Because both sides build all of this from the exact same definition, they can never disagree about the format or the version.

A channel only describes the actions and their format — never how a connection is secured. The same channel definition works whether the connection is plain or locked down, so you never have to think about that here. (When you're ready, [Security Levels](/nice-wire/security/) shows how the same channel gains authenticated or encrypted connections.)

Both lists are optional. `defineChannel({})` is a **connection-only channel**: no actions in either direction, but the connection it establishes is real — identity, security, and any frame protocols riding it. (A purely realm-only app doesn't need even that: it opens the same connection with [`createWireClient`](/nice-realm/connecting/#realm-only-apps--createwireclient), no channel at all — the two handshakes are interchangeable.)

## Order matters in the lists

The order of domains in each list is what builds that compact binary format, so the position of each one matters.

> **Always add new domains to the end** of a list. If you reorder them, the version changes — and an out-of-date peer is cleanly rejected during the handshake instead of quietly sending things to the wrong place.

That's the one rule to remember: add to the end, never reorder.

---

# Cloudflare Durable Objects

Source: /nice-action/cloudflare
Description: Collapse the entire DO transport stack into one serveDurableObject call.

`@nice-code/action/platform/cloudflare` wraps up _everything_ a Durable Object needs into one `serveDurableObject` call — the secure WebSocket (that survives the DO sleeping and waking), an HTTP fallback, the crypto identity stored in DO storage, and the `ping`/`pong` keepalive. Your DO just forwards its four socket events. The core library itself stays platform-neutral.

## A complete Durable Object

```ts
import { DurableObject } from "cloudflare:workers";
import { ActionRuntime } from "@nice-code/action";
import { serveDurableObject, type TDurableObjectChannelServer } from "@nice-code/action/platform/cloudflare";
import { appChannel, serverCoord } from "./shared"; // coordinates live in shared code

export class MyDurableObject extends DurableObject {
  private _server: TDurableObjectChannelServer | null = null;

  private getServer(): TDurableObjectChannelServer {
    if (this._server != null) return this._server;
    const serverRuntime = new ActionRuntime(serverCoord);

    this._server = serveDurableObject(this.ctx, appChannel, {
      runtime: serverRuntime,
      keyPrefix: "ws:",
      handlers: [userHandler],
    });
    return this._server;
  }

  async fetch(request: Request): Promise<Response> {
    return this.getServer().fetch(request);
  }
  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
    this.getServer().receive(ws, msg);
  }
  async webSocketClose(ws: WebSocket) { this.getServer().drop(ws); }
  async webSocketError(ws: WebSocket) { this.getServer().drop(ws); }
}
```

> Build the server **on the first request** (and remember it), not at the top level of the file. The Workers runtime won't let you generate random ids or do I/O in the global scope.

## Options

`serveDurableObject(ctx, channel, options)` accepts everything `serveChannel` does (`handlers`, `channelCases`, `connectionState`, `logger`, …) plus a few host-specific knobs:

- **`runtime`** — this DO's runtime.
- **`keyPrefix`** — a prefix for the crypto-identity keys stored in DO storage, so they don't clash with your other keys.
- **`httpFallback`** — `"plain"` (default), `"secure"` (a handshake-protected fallback that shares the WebSocket's identity), or `false` (WebSocket only).
- **`secure`** — whether the WebSocket itself runs the handshake (default `true`). Trusted-client verify-key pins ([trust-on-first-use](/nice-wire/identity/#trust-on-first-use-tofu)) default to **DO-storage-backed**, so they survive eviction and restarts with no configuration; pass `verifyKeyResolver` only to replace the trust policy itself.
- **`reliableStore`** — pass `cloudflareReliableLog(this.ctx)` so [`.reliable({ persist: true })`](/nice-action/reliable-delivery/#surviving-a-server-restart) streams keep their dedup state in the DO's SQLite and survive eviction. (On the lower-level acceptor surface this same store is the `persistedReceiver` option — one store, two entry points.)
- **`protocols`** — frame protocols to ride the same sockets. This is how a [realm](/nice-realm/serving/) shares the DO's connections with the channel's actions: `protocols: [realms.protocol]`. (A DO that serves *only* a realm doesn't need a channel or this package at all — it hosts on `serveWireDurableObject` from `@nice-code/wire/platform/cloudflare` instead; see [Serving a Realm](/nice-realm/serving/).)

## A plain Worker endpoint (no Durable Object)

If a channel can be served by a plain Worker — no Durable Object, because secure HTTP needs no shared memory
between requests — use `serveWorker`, the Worker version of `serveDurableObject`. It bundles in the
crypto-identity link (created once up front to handle KV's eventual consistency), the default
trust-on-first-use store, the HTTP carrier, and the build-on-first-request pattern the Workers global scope
forces on you — all over a `StorageAdapter` you pass in:

```ts
import { serveWorker, kvStorageAdapter } from "@nice-code/action/platform/cloudflare";

const serveCreate = serveWorker(bridgeCreateChannel, {
  runtime: () => new ActionRuntime(bridgeCreatorCoord),   // a factory — built lazily on first request
  storage: kvStorageAdapter({ kvNamespace: env.KV, keyPrefix: "bridge-create-identity:" }),
  handlers: () => [bridgeCreateHandler()],   // a factory — built lazily, never at module scope
});
// route it from any framework: honoApi.on(["POST", "OPTIONS"], "/create/*", (c) => serveCreate.fetch(c.req.raw));
```

To serve several channels from one Worker endpoint, use `serveWorkers([a, b], …)` (the Worker version of
`serveChannels`). It works out the right version for each connection from whichever channels that client
actually uses — so a client that connects to just one of them (via `connectChannel`) is still accepted; on
the connecting side, the matching helper is `connectChannels`. (Don't do
`serveWorker(combineChannels([a, b]), …)` instead — that locks in a single version for the whole set and
rejects every client that only uses one channel, because the versions won't match.)

## Sending HTTP to the right DO instance

Often each DO instance _is_ one thing — a single bridge, room, or game — and the Worker has to pick the right one for each request. Route by the **URL**: the body of a secure request is unreadable to the Worker anyway, so security stays end-to-end between the client and the DO. `forwardToDurableObject` picks the right DO, hands off the request, and answers the CORS `OPTIONS` preflight _right at the edge_ — so a specific DO never has to wake up just to reply to a preflight. It returns a `{ fetch }`, so it fits into the optional `actionRouter` or any framework:

```ts
import { actionRouter } from "@nice-code/action";
import { forwardToDurableObject } from "@nice-code/action/platform/cloudflare";

const router = actionRouter()
  .route("/bridge/:id/*", forwardToDurableObject(({ params }) =>
     env.BRIDGE.get(env.BRIDGE.idFromString(params.id))))   // per-id, E2E client ↔ DO
  .route("/app/*", forwardToDurableObject(() =>
     env.APP.get(env.APP.idFromName("main"))));              // singleton

export default { fetch: (request: Request) => router.fetch(request) };
```

`forwardToDurableObject` is just a Cloudflare-flavoured shortcut for the platform-neutral `forwardTo(pickTarget)`,
which forwards to **any** `{ fetch }` — a DO, a service binding, or `(req) => fetch(upstream, req)` for an
outside server. Inside the DO, make the HTTP fallback secure so the whole path is handshake-protected:

```ts
this._server = serveDurableObject(this.ctx, bridgeChannel, { runtime, httpFallback: "secure" });
```

## Remembering who's on each connection + broadcasting

A presence or room DO that tracks who's on each socket adds two options: `connectionState` (typed state for each connection, saved alongside the routing info so both survive the DO sleeping and waking) and `channelCases`:

```ts
const server = serveDurableObject(this.ctx, lobbyChannel, {
  runtime,
  keyPrefix: "lobby-ws:",
  connectionState: { schema: vs_player },
  channelCases: {
    join: (action, conn) => {
      conn.setState(action.input);
      conn.broadcast(() => act_lobby.action.player_joined.request(action.input), { exceptSelf: true });
      return { players: roster() };
    },
    move: (action, conn) => {
      const player = conn.state;        // this connection's typed state (or null)
      if (!player) return;
      conn.broadcast(() => act_lobby.action.player_moved.request({ id: player.id, ...action.input }), { exceptSelf: true });
    },
  },
});

// After waking, rebuild your in-memory state from the sockets that are still open
// (the routing info is replayed for you automatically):
for (const [, player] of server.connections.entries()) players.set(player.id, player);
```

The WebSocket carrier saves each connection's routing info when it's set, and replays it when the DO is rebuilt — so even after the object wakes from sleeping, replies and pushes still reach the right socket.

---

# Defining Actions

Source: /nice-action/defining-actions
Description: Root domains, child domains, action schemas, serialization, and thrown errors.

## Root and child domains

First make a **root domain** — an empty top-level namespace with no actions of its own. Then hang **child domains** off it, and put your actions in those. Both sides import all of this from shared code.

We prefix action domains with `act_` (so `act_user`, `act_lobby`) the same way error domains use `err_`. It keeps names predictable and makes it obvious at a glance what kind of thing you're looking at.

```ts title="shared.ts"
import { createActionRootDomain, actionSchema } from "@nice-code/action";
import * as v from "valibot";

export const act_app = createActionRootDomain({ domain: "act_app" });

export const act_user = act_app.createChildDomain({
  domain: "act_user",
  actions: {
    getUser: actionSchema()
      .input({ schema: v.object({ userId: v.string() }) })
      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
      .throws(err_user, ["not_found"]),

    updateName: actionSchema()
      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
      .output({ schema: v.object({ success: v.boolean() }) }),
  },
});
```

You can write the schemas with any [Standard Schema](https://github.com/standard-schema/standard-schema) library — Valibot, Zod, and so on.

## Sending values that aren't plain JSON

Some values don't survive a trip over the network on their own — a `Date` or a `Map`, for example. For those, pass a pair of functions (one to pack the value for sending, one to unpack it on arrival) as the 2nd and 3rd arguments:

```ts
createdAt: actionSchema()
  .output(
    { schema: v.object({ createdAt: v.date() }) },
    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }), // pack for sending
    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),      // unpack on arrival
  ),
```

Your handler and your caller always see the real value (a `Date` here) — never the packed string that actually travels over the wire.

> **Note:** The schema always describes your **local, real value** (the `Date` object), not the packed wire form. The library runs standard schema validation **after** unpacking on the way in, and **before** packing on the way out — so validation only ever sees the real value, and your pack/unpack functions only ever deal with the wire form.

## Saying which errors an action can throw

Use `.throws()` to attach `@nice-code/error` domains. Whoever calls the action then gets those errors fully typed, so they can check for them by name.

```ts
import { defineNiceError, err } from "@nice-code/error";

const err_user = defineNiceError({
  domain: "err_user",
  schema: {
    not_found: err<{ userId: string }>({
      message: ({ userId }) => `User not found: ${userId}`,
      httpStatusCode: 404,
      context: { required: true },
    }),
  },
});

actionSchema()
  .throws(err_user)              // can throw any error from err_user
  .throws(err_user, ["not_found"]); // can throw only "not_found"
```

## Streams that must not drop updates — `.reliable()`

By default an action is best-effort — perfect for request/response calls you'd just retry. For a **stream
of updates that must all arrive, in order, without duplicates** (game moves, a chat feed, incremental
sync), chain `.reliable()` onto the schema:

```ts
host_move: actionSchema()
  .input({ schema: v.object({ n: v.number() }) })
  .reliable(), // ordered + deduped + resent across reconnects
```

That one call is the whole opt-in — see [Reliable Delivery](/nice-action/reliable-delivery/) for what it
guarantees, the `persist` option for surviving server restarts, and independent streams per room/entity.

---

# Error Handling

Source: /nice-action/error-handling
Description: Every action resolves to a deterministic outcome — branch on expected vs unhandled.

Every action always finishes with a **clear, predictable outcome** — it never just rejects with a raw throw.
Your handler can throw anything it likes (a declared `NiceError`, an undeclared one, or a plain `Error`);
the runtime turns all of them into one typed result, so the place you call from always has the same shape to
check against.

## Two questions: `expected` and `isUnhandled`

When an action fails, there are two separate things you might want to know:

| Question | Where to look | Meaning |
|---|---|---|
| Did **this action** say it could throw this? | `result.expected` (on the result) | You listed it with `.throws()`, so it's a known, planned-for error. |
| Was this an **unexpected crash**? | `error.isUnhandled` (on the error) | Something threw that wasn't a `NiceError` at all — a bug or infrastructure failure. |

`expected` depends on *which action* you called: the very same `NiceError` can be expected for one action
(which declared it) and unexpected for another (which didn't). `isUnhandled` is a property of the error
itself — it's `true` only for the generic wrapper `castNiceError` puts around a non-`NiceError` throw, and it
stays `true` even after the error travels over the network.

## The recommended way — `runToResult()`

Get the outcome as a value and check it. No `try`/`catch`.

```ts
import { matchFirst } from "@nice-code/error";

const result = await act_user.action.getUser.request({ userId }).runToResult();

if (result.ok) {
  use(result.output);
} else if (result.expected) {
  // result.error is fully typed — it can only be one of this action's declared errors.
  matchFirst(result.error, {
    not_found: ({ userId }) => show404(userId),
    forbidden: () => showForbidden(),
  });
} else {
  // This action didn't declare this one. Check the error's own flag if you care which kind it is:
  if (result.error.isUnhandled) alertOncall(result.error); // an unexpected crash / bug / infra issue
  else report(result.error);                                // a real NiceError you just didn't .throws()
}
```

The outcome is one of three shapes:

```ts
type TActionResultOutcome<OUT, DECLARED> =
  | { ok: true; output: OUT }
  | { ok: false; expected: true; error: DECLARED }            // one of the errors this action declared
  | { ok: false; expected: false; error: NiceError };          // anything else
```

`expected` is always worked out fresh against the **receiver's own** definition — it's never trusted from
the wire. So an error that arrived over the network is sorted exactly the same way as one thrown locally.

## Throw style, with a typed check

If you prefer `runToOutput()` (which throws on failure), use the action's `isExpectedError` check to narrow a
caught error:

```ts
import { castNiceError, matchFirst } from "@nice-code/error";

try {
  const output = await act_user.action.getUser.request({ userId }).runToOutput();
} catch (e) {
  if (act_user.action.getUser.isExpectedError(e)) {
    // e is now narrowed to this action's declared errors
    matchFirst(e, { not_found: ({ userId }) => show404(userId), forbidden: () => showForbidden() });
  } else {
    report(castNiceError(e).toStructuredLog());
  }
}
```

## Devtools

The [browser devtools panel](/nice-action/integrations/) sorts each failed run by these same two questions.
Based on `result.expected`, an error is labelled either **Expected Error (declared)** or **Unexpected Error
(undeclared / unhandled)**; and based on `error.isUnhandled`, an unexpected crash gets an extra **`unhandled`**
badge. So the same distinction you check in code is the one you see in the timeline.

---

# Handlers

Source: /nice-action/handlers
Description: Build local handlers that run actions in the current process.

A **handler** is the actual code that runs when an action is called. You write one, register it on the runtime, and it answers incoming calls. There are three ways to write one — use whichever reads best for you.

## Map style (recommended)

```ts title="server.ts"
import { createLocalHandler } from "@nice-code/action";

const userHandler = createLocalHandler().forDomainActionCases(act_user, {
  getUser: async (action) => {
    const user = await db.users.find(action.input.userId);
    if (!user) throw err_user.fromId("not_found", { userId: action.input.userId });
    return user;
  },
  updateName: async (action) => {
    await db.users.update(action.input.userId, { name: action.input.name });
    return { success: true };
  },
});
```

Each handler gets the whole `action`: `action.input` is typed, and `action.context` carries routing details like `originClient` — who made the call (see [Bi-directional](/nice-action/bidirectional/)).

## One action at a time

```ts
const userHandler = createLocalHandler()
  .forAction(act_user.action.getUser, async ({ input }) => db.users.find(input.userId));
```

## Straight from the domain

```ts
const userHandler = act_user.wrapAsLocalHandler({
  getUser: async ({ userId }) => { /* ... */ },
  updateName: async ({ userId, name }) => { /* ... */ },
});
```

Here each handler gets the **input** directly (already destructured) instead of the full `action` object — the shortest form, for when you don't need `action.context`.

## Handling only some actions

`wrapAsPartialLocalHandler` works like `wrapAsLocalHandler`, but you only implement **some** of a domain's actions. This is handy for a client that answers a few calls itself and lets the rest travel on to the server.

```ts
const partial = act_user.wrapAsPartialLocalHandler({
  getUser: async ({ userId }) => cache.get(userId), // the rest are forwarded over the connection
});
```

Once you've written a handler, pass it to [`serveChannel`](/nice-action/serving-connecting/) on the listening side, or — to answer `toConnector` pushes on the dialing side — to `connectChannel`'s `onPush`.

---

# React Query & Building Blocks

Source: /nice-action/integrations
Description: TanStack Query hooks for your actions, a one-line devtools pointer, and the lower-level pieces connectChannel is built from — for the rare routing a single channel can't describe.

## React Query integration

Import from `@nice-code/action/react-query` (peer dep: `@tanstack/react-query`).

```tsx
import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";

function UserProfile({ userId }: { userId: string }) {
  const { data } = useActionQuery(
    act_user.action.getUser,
    { userId },
    { queryKey: ["user", userId] },
  );
  return <div>{data?.name}</div>;
}

function RenameUser() {
  const { mutate } = useActionMutation(act_user.action.updateName);
  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
}
```

The input, output, and errors all come straight from the action schema — you don't write a query function or any types by hand.

## Devtools

Actions surface in the [devtools window](/devtools/window/) with one call — `createNiceDevtools({ runtime, domains: [act_app] })` names the **root** domains to observe (an action whose root isn't listed never surfaces), and on the server `createNiceServerDevtools({ runtime, domains: [act_app] })` does the same for a backend. Failed runs are sorted by the same question you check in code (see [Error Handling](/nice-action/error-handling/)): an error is labelled **Expected (declared)** or **Unexpected (undeclared / unhandled)** based on `result.expected`. The whole window, the server host, and its options are documented in the [Devtools section](/devtools/window/); [Observing Backends](/devtools/backends/) covers attaching a server or a Durable Object.

## Lower-level building blocks

`connectChannel` / `serveChannel` are the entry points you should normally use. For the rare case where your routing isn't a single channel, the pieces they're built from are also exported — most under the `@nice-code/action/advanced` subpath:

- **`acceptChannel`** / **`acceptChannelConnections`** — build a secure listening side by hand, with access to each connection.
- **`createActionFetchHandler`** — the standard `fetch` handler on its own.
- **`createInMemoryChannelPair` / `inMemoryCarrier`** — connect two runtimes in the same process (for tests or same-process peers) with no network involved. `inMemoryCarrier()` hands back two cross-wired ends: a `carrier` for the connector side and a `serverEndpoint` for the acceptor side. Frames cross on a microtask, so each side observes the other asynchronously — exactly like a real socket, but with no socket to spin up. That lets a unit test exercise your full channel, handlers, routing, and types end to end:

  ```ts
  import { describe, it, expect } from "vitest";
  import { ActionRuntime, connectChannel, acceptChannelConnections, inMemoryCarrier } from "@nice-code/action";
  import { createSecureChannelAcceptor } from "@nice-code/action/advanced";
  import { StorageAdapter, createMemoryStorageMethods_json } from "@nice-code/util";
  import { appChannel, act_user, serverCoord, frontendCoord } from "./shared";

  // A throwaway in-memory crypto-identity store, fresh per test.
  const memStorage = () => new StorageAdapter({ methods: createMemoryStorageMethods_json(new Map()) });

  describe("getUser", () => {
    it("routes a call through the channel with full types, no sockets", async () => {
      const { carrier, serverEndpoint } = inMemoryCarrier();

      // Acceptor: wire the in-memory end into an acceptor, register your cases.
      const serverRuntime = new ActionRuntime(serverCoord);
      const conn = { id: "test-conn" };
      const acceptor = createSecureChannelAcceptor<typeof conn>({
        channel: appChannel,
        runtime: serverRuntime,
        storage: memStorage(),
        send: (_c, frame) => serverEndpoint.send(frame),
      });
      serverRuntime.addHandlers([
        acceptChannelConnections(acceptor, appChannel, {
          getUser: ({ input }) => ({ id: input.userId, name: "Test User" }),
        }),
        acceptor,
      ]);
      serverEndpoint.onMessage((frame) => acceptor.receive(conn, frame));

      // Connector: dial the in-memory carrier instead of a real WebSocket.
      const clientRuntime = new ActionRuntime(frontendCoord);
      connectChannel(clientRuntime, appChannel, {
        peer: serverCoord,
        storage: memStorage(),
        transports: [{ carrier }],
      });

      const user = await act_user.action.getUser.request({ userId: "u_1" }).runToOutput();
      expect(user).toEqual({ id: "u_1", name: "Test User" }); // typed both sides
    });
  });
  ```

  You're mocking the edge network topology locally with full type safety — flip `inMemoryCarrier` out for `wsCarrier` and the exact same test shape runs over a real socket.
- **`createBinaryWireAdapter`** — the binary format `defineChannel` builds for you, exposed for custom carriers.

Only reach for these when a single channel can't describe the routing you need.

---

# Mental Model

Source: /nice-action/mental-model
Description: Runtimes, peers, carriers, and channels — the four ideas behind nice-action.

`@nice-code/action` lets you call a function that lives somewhere else — on a server, in a worker, on another peer — as if it were a normal local function, with all the types intact. It doesn't care *how* the two sides are connected. It even works **both ways**: over a live connection, the side that's listening can call back to the side that connected.

## In one sentence

> A **runtime** connects to a **peer** over a **carrier**, and a **channel** describes — once — which calls flow in each direction.

The interesting part: it all behaves the same no matter which carrier you use. Only two things ever really differ:

- **Who started the connection** — the **connector** dials in; the **acceptor** listens, and can call back.
- **The shape of the connection** — **duplex** (a two-way line like a WebSocket, so either side can speak at any time) vs **exchange** (one request, one reply, like a normal HTTP call).

## The pieces

| Concept | What it is |
|---|---|
| **ActionDomain** | A named group of related actions — think of it as one section of your API. |
| **ActionSchema** | One action's input type, output type, and the errors it can throw. |
| **ActionRuntime** | One per app. It's your app's identity, and it routes incoming calls to your code. |
| **Channel** | Lists which actions go from connector to acceptor (`toAcceptor`) and back (`toConnector`). Both sides build it from the same definition, so they always agree. |
| **Carrier** | The actual way bytes travel. On the dialing side: `wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`. On the listening side: `wsAcceptorCarrier`, `httpAcceptorCarrier`. |
| **Transport** | A carrier with its connection settings. You never build one by hand — `connectChannel` / `serveChannel` do it for you. |
| **RuntimeCoordinate** | A label for an environment (frontend, backend, worker…). It's how calls find the right destination. |

## The Network Flow

A call leaves your code as a typed request and arrives on the other side as a typed handler argument. In between, everything is plumbing the channel set up for you:

```text
  CONNECTOR  (client.ts)                         ACCEPTOR  (server.ts)
  ┌────────────────────┐                         ┌────────────────────┐
  │   ActionRuntime    │                         │   ActionRuntime    │
  │  act_user.getUser  │                         │   getUser handler  │
  │     .request()     │                         │   (your code)      │
  └─────────┬──────────┘                         └─────────▲──────────┘
            │                                              │
            ▼                                              │
  ┌────────────────────┐  ── same definition, both sides ──┌──────────┐
  │  Channel (Schema)  │ ········· the type boundary ······│ Channel  │
  │ validate + encode  │                                   │ decode + │
  └─────────┬──────────┘                                   │ validate │
            │                                              └────▲─────┘
            ▼                                                   │
  ┌────────────────────┐                              ┌─────────┴──────────┐
  │ Handshake/Security │  identity + (optional) crypto │ Handshake/Security │
  │  none/auth/encrypt │ ◄───────────────────────────► │  none/auth/encrypt │
  └─────────┬──────────┘                              └─────────▲──────────┘
            │                                                   │
            ▼                                                   │
  ┌────────────────────┐        bytes on the wire       ┌──────┴───────────┐
  │  Carrier (WS/HTTP) │ ─────────────────────────────► │ Carrier (WS/HTTP)│
  │  wsCarrier / http  │ ◄───────────────────────────── │ wsAcceptorCarrier│
  └────────────────────┘                                └──────────────────┘
```

The **channel is the boundary**. It's the one definition both sides import, so the shape that gets encoded on the connector is exactly the shape that's decoded and validated on the acceptor — there's no second copy of the types to drift out of sync. Everything below the channel (handshake, security level, which carrier) can change without touching a single action call: swap a WebSocket for HTTP, or turn on encryption, and the request/handler signatures stay identical.

## One runtime per app

Each app — a frontend, a backend, a worker — has **one** `ActionRuntime` that represents it to everyone it talks to. Not one per feature, not one per server you connect to. Register your handlers on it, then call `connectChannel(...)` once for each peer you dial (or `serveChannel(...)` to listen). One runtime means one identity, and no confusion about where a call should go.

## The two functions you'll use most

`connectChannel` (dial out) and `serveChannel` (listen) cover almost everything you'll do. They take your channel and runtime and wire up all the lower-level carrier and transport plumbing for you.

## The three-file shape

A typical app is exactly three files:

- **`shared.ts`** — imported by both sides: the domains, the channel, and the runtime coordinates that name each side.
- **`server.ts`** — the listening side: your handlers + `serveChannel`.
- **`client.ts`** — the dialing side: `connectChannel` + your action calls.

The pages that follow label each code block with the file it belongs in.

> **Coordinates are shared facts.** A `RuntimeCoordinate` like `RuntimeCoordinate.env("backend")` always belongs in shared code — its own `runtimeCoordinates.ts` is the natural home, since it's orthogonal to how you channel your actions — never in `server.ts`: the client needs the *same* coordinate to name the server it's dialing, and it can't import that from server-only code. Define each side's coordinate once, in shared, and import it on both sides.

---

# Reliable Delivery

Source: /nice-action/reliable-delivery
Description: Opt an action into ordered, deduplicated, resend-on-reconnect delivery with .reliable().

By default an action is **best-effort**: it rides one transport attempt, and a dropped frame or a
mid-flight disconnect surfaces as an error for you to handle. That's the right default for a
request/response call you'll just retry.

Some actions aren't like that. A **stream of updates that must all arrive, in order, without duplicates** —
game moves, a chat feed, incremental sync — shouldn't lose an update to a flaky network or deliver it twice
after a reconnect. For those, opt the action into the reliable tier:

```ts title="shared.ts"
export const act_session = act_app.createChildDomain({
  domain: "act_session",
  actions: {
    // Ordered, at-least-once, deduped for the life of a (resumable) connection.
    host_move: actionSchema().input({ schema: v.object({ n: v.number() }) }).reliable(),

    // Same, but the dedup state is *persisted* server-side, so it also survives
    // a server eviction/restart (a Durable Object waking, a redeploy).
    host_event: actionSchema().input({ schema: v.object({ n: v.number() }) }).reliable({ persist: true }),
  },
});
```

That's the entire configuration surface: `.reliable()` is the only delivery knob, and `persist` its only
parameter. There is no per-message policy to tune. Both sides read the tier from the shared action
definition, so nothing extra travels on the wire beyond a small per-frame sequence number (and a cumulative
acknowledgement coming back). Actions that don't opt in are completely unaffected.

> **Transport:** reliable delivery works over **duplex** carriers (WebSocket / WebRTC / in-memory — a
> persistent connection). Over an HTTP exchange there's no standing connection to resend on, so
> `.reliable()` there is simply best-effort. Point a reliable stream at a WebSocket carrier.

> **Direction:** reliable delivery engages when the **dialing side sends to the listening side**
> (connector → acceptor). A server push (`pushToClient` / `broadcast`) of a reliable-declared action is
> still **best-effort** — see [the direction note](#one-direction-pushes-are-best-effort) below.

## What you get — and the one thing you owe

- **Ordered** — your handler never sees frames out of order; an early arrival waits until the gap before it
  fills.
- **At-least-once** — an unacknowledged frame is resent when the transport reconnects, so a drop never
  loses an update.
- **Deduped** — a resent frame the server already received is acknowledged but not re-delivered to your
  handler (for a `fireAndForget().reliable()` stream), or is re-run so its reply regenerates (for an action
  with an `.output()` — the caller may still be waiting on that reply).

The one thing you owe in return is the flip side of *at-least-once*: **reliable handlers must be
idempotent**. In rare windows (a reply lost right at a disconnect, a delivery deadline that fired just as
the frame landed) the same update can reach your handler twice. Make handling it twice a no-op — upsert by
an id, ignore an already-applied move — and every path is safe.

## When the promise settles

Opting in changes *when* a reliable action's promise settles, because the whole point is to keep retrying
instead of failing fast:

- An action **with an output** resolves when its reply arrives — same as best-effort, except a transport
  drop no longer rejects it; the frame is resent and the promise resolves after the reconnect.
- A **fire-and-forget** action (`.fireAndForget().reliable()`) resolves **on send** — delivery continues in
  the background across reconnects.
- Either way, every reliable send has a **delivery deadline** (`reliableActionTimeout` on `connectChannel`,
  default 60s). If the peer hasn't acknowledged the frame by then — say it's simply unreachable — the frame
  is **abandoned**: a still-pending action rejects with a `reliable_delivery_abandoned` error, and an
  already-settled fire-and-forget send surfaces through a one-time console warning. So a reliable call
  always terminates, and background delivery never retries forever.

```ts title="client.ts"
connectChannel(clientRuntime, appChannel, {
  peer: serverCoord,
  storage,
  transports: [{ carrier: wsCarrier(() => ({ url: wsUrl })) }],
  reliableActionTimeout: 30_000, // optional — how long an unacknowledged frame retries (default 60s)
});
```

### Abandoned frames don't wedge the stream

An abandoned frame (deadline expired, or you called `running.abort()` while it was unacknowledged) can't
block everything behind it. The sender drops it — along with any *older* frames still unacknowledged, each
failing loudly the same way — and tells the receiver to skip past those sequence numbers. The receiver
advances, delivers anything it was holding behind the gap, and the stream **continues**: later sends
deliver normally. Ordering among *delivered* frames is always preserved; an abandoned frame is a surfaced
failure, never a silent hole.

## Observing delivery — `waitForAck` and stream events

A fire-and-forget reliable send resolves **on send**, so its promise can't tell you what became of the
frame. Two surfaces do:

**Per send** — hold the `RunningAction` and await its delivery settlement:

```ts
const running = act_session.action.host_move.request(move).run({ streamKey: runId });
await running.waitForAck(); // resolves when the peer's cumulative ack covers this frame;
                            // rejects with the abandon reason (deadline / abort / sweep / stream close)
```

For a best-effort action `waitForAck()` simply mirrors the action itself (resolves on success, rejects on
failure), so generic code composes without branching on the tier. Observers can also watch
`runningAction.addUpdateListeners` for the `reliability` update, which fires when `reliability.acked`
flips — the devtools chip's `✓` rides this.

**Per connection** — no handles, for app-level monitoring:

```ts
connectChannel(runtime, channel, {
  ...,
  onReliableEvent: (event) => {
    if (event.type === "abandoned") {
      // frames event.fromSeq..event.toSeq of (event.domain/event.actionId [#event.streamKey])
      // were dropped undelivered — re-push from your own records, or show "receiver may be behind".
    }
    if (event.type === "overflow") { /* a send hit the unacked-window cap — coalesce/shed */ }
  },
});
```

### Which failures surface where

For a **fire-and-forget** reliable send, the failure classes are deliberately split:

| What happened | When it surfaces | How |
|---|---|---|
| Stream at its unacked cap | **at the call** | the send's promise rejects with `reliable_outbox_overflow` (+ the `overflow` event) |
| Peer unreachable right now | not an error | background retry with backoff, until the deadline |
| Delivery deadline expired | **after** the promise resolved | `waitForAck()` rejects, the `abandoned` event fires, one console warning per route |
| Explicit `abort()` / stream close | after the promise resolved | same as deadline, with the abort/close reason |

A reply-carrying reliable send is simpler: everything above that would be "silent" instead rejects its
still-pending promise loudly.

Note the at-least-once caveat both ways: a *rejected* settlement means the sender stopped trying — the ack
itself may have been lost after delivery, so an "abandoned" frame may still have arrived (idempotent
handlers make that harmless).

### Backpressure

Unacknowledged frames are held until the peer confirms them, and that can't grow without bound: each stream
caps at 1024 unacknowledged sends. Past the cap, new sends on that stream fail with a
`reliable_outbox_overflow` error — surface it as "connection lost, please retry" rather than silently
dropping updates.

You don't have to wait for the cliff: the connector exposes read-only pressure stats, so a high-frequency
sender can coalesce batches or shed cosmetic traffic *before* overflowing:

```ts
const connector = connectChannel(runtime, channel, { ... });
connector.reliablePending();                                    // total unacked sends, all streams
const p = connector.reliablePending(act_session.action.host_events, runId);
// p.unackedCount / p.oldestUnackedAgeMs / p.maxUnackedPerStream — headroom = max - count
```

## Surviving a server restart

**A socket drop + reconnect to a still-running server** is the everyday case and needs nothing from you:
the client resends what wasn't acknowledged, the server's dedup state is intact, and each update is
delivered exactly once.

**A server restart mid-stream** (a redeploy, a Durable Object evicted with its memory gone) is the harder
case, and the two tiers answer it differently:

- **`.reliable()` (the session tier)** self-heals the *in-flight* part: the fresh server notices it has no
  state for a mid-stream frame and asks the client to re-sync; the client renumbers its unacknowledged
  frames and resends, and the stream continues in order instead of stalling. What this can't recover is
  frames the old server had already confirmed — those were delivered before the restart, and the fresh
  server doesn't remember them, so a handler may see them again on replay (idempotency covers it).
- **`.reliable({ persist: true })` (the persisted tier)** persists the dedup state itself, so the stream
  survives the restart *outright* — a replayed frame is recognised and skipped, even across an eviction.

The persisted tier needs somewhere to keep that state. On Cloudflare it's one line — back it with the
Durable Object's SQLite:

```ts title="server.ts (Durable Object)"
import { serveDurableObject, cloudflareReliableLog } from "@nice-code/action/platform/cloudflare";

const server = serveDurableObject(this.ctx, appChannel, {
  runtime,
  reliableStore: cloudflareReliableLog(this.ctx), // persisted-tier streams survive eviction
  channelCases: { /* … */ },
});
```

`cloudflareReliableLog` needs a SQLite-backed DO class (enable it in `wrangler`). If you omit
`reliableStore`, `persist: true` actions gracefully behave like the session tier. On other backends,
implement the small `IReliableLogStore` port and pass `new ReliableLog(store)` — both exported from
`@nice-code/action/advanced`. Storage stays bounded: out-of-order frames are only persisted within a window
(`maxGapWindow`, default 1024), and you can opt into compaction of delivered history with
`cloudflareReliableLog(ctx, name, { keepDelivered: 256 })`.

## Independent streams of one action — `streamKey`

By default a reliable action is **one** ordered stream per peer: every frame shares one sequence. That's
right when the action *is* the stream. But when one connection multiplexes several *independent* logical
streams through the same action — one per game room, per entity, per chat channel — you don't want a gap in
one room holding back the others. Pass a **`streamKey`** and each key gets its own ordered, deduped,
independently-resending stream:

```ts title="client.ts"
// One connection, many rooms, one action — each room id is its own stream.
function sendRoomEvent(roomId: string, event: TRoomEvent) {
  return act_room.action.host_event.request(event).runToOutput({ streamKey: roomId });
}

sendRoomEvent("alpha", a); // stream #alpha — its own sequence
sendRoomEvent("beta", b);  // stream #beta — fully isolated from alpha
```

`streamKey` is a per-call option on `.run()` / `.runToOutput()` — the key is usually only known at runtime
(a room id), which is why it isn't part of the action's schema. Omitting it gives you exactly the single
default stream. A gap, an abandonment, or backpressure in one key never affects another.

Because keys are chosen by the client, the server caps how many distinct keyed streams one client can open
(`maxKeyedStreamsPerClient` on `serveChannel`, default 256). What counts against the cap: distinct keys per
bound client per action route, on the accepting side. A key stops counting when its stream is **closed**
(below); an idle-but-unclosed key keeps counting. Client-side, each used key holds a small seq-counter
entry for the life of the tab — `closeReliableStream` reclaims it.

> Keyed frames use a slightly extended wire format, so **both ends** need a library version that supports
> `streamKey`. Against an older peer you get a one-time dev warning and the keyed frames are not delivered.

### Closing a stream — `closeReliableStream`

Keyed streams are created implicitly on first use; when a stream's real-world subject is *over* (the game
run ended, the room was left), close it explicitly:

```ts
const connector = connectChannel(runtime, channel, { ... });
// at run teardown:
connector.closeReliableStream(act_session.action.host_events, runId);
```

One call: every still-unacknowledged send on the stream is abandoned (pending actions reject with
`reliable_stream_closed`; settled fire-and-forget sends stop resending; the `abandoned` event fires with
the swept range), the receiver is told to skip past them, and **both sides release the stream's state** —
including the key's slot in the `maxKeyedStreamsPerClient` quota.

It is **synchronous on the sender's state**: after it returns, nothing from that stream can resend. That
ordering is the point — see [multiplexed peers](#multiplexed-peers-many-server-instances-behind-one-coordinate)
below. Closing a stream you never sent on is a no-op, and a closed key can be reused safely (the library
self-heals the seq bookkeeping in every crash/race interleaving).

## Multiplexed peers — many server instances behind one coordinate

> **The one sharp edge to know about.** A reliable stream is identified by
> `(peer coordinate + action route [+ streamKey])`, but frames are *delivered* over whatever transport
> currently dials that coordinate. On Cloudflare the natural shape is many Durable Object instances behind
> **one** peer coordinate, selected by a mutable dial URL (`/session/ws?runId=X` → `idFromName(X)`). If
> your dial state changes while unacknowledged frames are still in the outbox, **the retries follow the
> connection — into a different physical instance**: run A's unacked tail can be redelivered into run B's
> DO after you switch runs.

Two lines close the window entirely:

1. **Close the stream at teardown, *before* changing the dial state** —
   `connector.closeReliableStream(action, runId)` is synchronous on the sender's state, so once it returns
   nothing from the old run can resend.
2. **Defense-in-depth: stamp the payload and guard server-side** — carry the entity id (`runId`) in every
   reliable payload and have the instance drop payloads that aren't its own
   (`input.runId !== ctx.id.name` for an `idFromName` DO). Dropping is safe *and terminal*, because of the
   contract below.

**Acknowledgement is a receipt contract, not an outcome contract.** The receiver acknowledges a frame when
its inbox *accepts* it — ordering/dedup bookkeeping — regardless of what your handler then does with it. A
handler that inspects a frame and discards it still settles that frame: it will not retry. This is
guaranteed behavior (the server-side-guard pattern above depends on it), and it's also why "acked" never
means "the handler liked it" — only "it arrived, in order, once".

## What reliability spans — and what it doesn't

Reliable delivery spans **drops and reconnects, not reloads**. The outbox holding unacknowledged sends is
memory: a page reload or tab close discards it (nothing is ever redelivered *cross-run* by a reload — the
outbox dies with the tab — but nothing is delivered later either). For a send that **must** survive a
reload (an end-of-run submission racing a tab close), persist the input yourself and replay it through a
normal reliable send on next launch — replayed sends get fresh seqs, and your idempotent handler (the
contract you already signed up for) makes the replay safe end-to-end.

Relatedly, reliable streams are scoped **per runtime boot**: the `ActionRuntime` generates a fresh
per-instance id (`insId`) at construction when you don't set one, so a reloaded app is a *new* stream
identity rather than a collision with the server's retained bookkeeping for the old one. Only set `insId`
yourself if it is genuinely unique per process boot.

## One direction — pushes are best-effort

Reliable delivery engages on the **dialing side's sends** (connector → acceptor): the dialing side keeps
the resend state, and its process lifetime is the natural bound for it. A server push
([`pushToClient` / `broadcast`](/nice-action/bidirectional/)) of a reliable-declared action does **not**
get an outbox or a sequence — it's delivered best-effort, exactly like any other push (with a one-time dev
warning per route, so the direction downgrade is never silent).

That's deliberate. A push's receiver is a browser tab or a phone that routinely disappears for longer than
any resend window could cover — so a push stream that *truly* must all arrive needs durable catch-up on the
server, not a live-socket resend. Build it from the persisted log: append each push to a per-client
`ReliableLog`, replay `contiguousPrefix()` when the client reconnects, and prune once the client confirms.
(The building blocks — `ReliableLog`, `ReliableInbox`, and the stores — are exported from
`@nice-code/action/advanced`.) For a single push that needs confirmation, awaiting
`pushToClient(...).waitForResultPayload()` and retrying already gives you at-least-once.

Two backends that each dial the other (worker ↔ worker) get reliable delivery in both directions today —
reliability follows the dialer.

## Seeing it work

The [devtools panel](/nice-action/integrations/) tags every reliable action's row with a chip —
`reliable · 3` (the frame's sequence number), gaining a `✓` once the peer confirms delivery, or
`persisted · 3` for the persisted tier. On the serving side, the
[request logger](/nice-action/serving-connecting/#logging-served-requests) tags each reliable request with
its sequence, the cumulative acknowledgement, and whether it was a deduplicated redelivery:

```
▶ act_session/host_move  via ws  from envId[frontend]…  reliable seq=3 ack=3
▶ act_session/host_move  via ws  from envId[frontend]…  reliable seq=3 ack=3 (redelivered)
```

## What reliable delivery deliberately does *not* do

To keep the guarantee knob-free and the library maintainable, these are **out of scope by design**. That
list reads as *scoped*, not as dead-ends — every item has a worked recipe in the next section:

- **No message priorities** → [priority lanes](#1-priority-lanes).
- **No per-message TTLs or deadlines** → [TTL classes](#2-per-message-ttl-classes).
- **No exactly-once *effects*** → [the free idempotency key](#3-exactly-once-effects).
- **No ordering across different actions** → [the envelope action](#4-ordering-across-event-types--the-envelope).
- **No reliable broadcast / reliable push** → [the persisted-log recipe](#5-reliable-serverclient-push).

## Building on top — the recipes

### 1. Priority lanes

Ordering is per stream, so make a stream per priority class: `streamKey: "critical"` and
`streamKey: "bulk"` are independently ordered, independently backpressured lanes of one action — a slow
bulk lane never head-of-line-blocks the critical one (cross-lane ordering is intentionally absent; that's
what a priority scheme wants). A scheduler reads pressure per lane with
`connector.reliablePending(action, "bulk")` and sheds or coalesces the cheap lane first.

### 2. Per-message TTL classes

There is no per-call deadline knob — compose one from the two levers that exist. Set the **connection**
deadline to your *longest* class, then abort the short-lived class down with a timer:

```ts
// host_end is precious (let it retry ~10 minutes); host_events batches are stale after ~15s.
connectChannel(runtime, channel, { ..., reliableActionTimeout: 10 * 60_000 });

let lastBatch: RunningAction<any, any> | undefined;
function sendBatch(events: TEvent[]) {
  lastBatch = act_session.action.host_events.request({ runId, events }).run({ streamKey: runId });
  const running = lastBatch;
  const ttl = setTimeout(() => running.abort(), 15_000);       // the per-class deadline
  running.waitForAck().then(() => clearTimeout(ttl), () => clearTimeout(ttl));
}
```

Two facts make this correct: an abort **sweeps older unacknowledged frames on the same stream with it**
(they could no longer deliver in order anyway) — so give differing TTL classes their own `streamKey` lane —
and different *actions* are different streams, so `host_events` aborts never touch `host_end`. Note the
`lastBatch` variable is also your teardown handle: aborting only the most recent send abandons the whole
unacked tail (or just call `closeReliableStream`).

For the precious class, remember [the lifetime boundary](#what-reliability-spans--and-what-it-doesnt): a
10-minute retry still dies with the tab. A must-arrive payload wants the persist-and-replay pattern too.

### 3. Exactly-once effects

The wire dedups *delivery*; your handler owns the *effect*. The library hands the handler a free
idempotency key for it — the receiver-side facts of the frame being handled:

```ts
// In a Durable Object case: effect + dedup in ONE transaction, keyed by the library's own (stream, seq).
host_move: (action, conn) => {
  const rel = action.context.reliability; // { seq, streamKey?, redelivered } — undefined for best-effort
  this.ctx.storage.sql.exec(
    `INSERT OR IGNORE INTO effects (stream_key, seq, payload) VALUES (?, ?, ?)`,
    rel?.streamKey ?? "", rel?.seq, JSON.stringify(action.input),
  );
},
```

Tier nuance: for a **fire-and-forget** reliable stream, a duplicate never reaches your handler at all (the
receiver suppresses it before dispatch) — `redelivered: true` appears only on **reply-carrying** re-runs,
where the re-run regenerates the reply; use it to return a memoized reply instead of re-running an
expensive body. The one duplicate window no flag can cover is a session-tier server reset replay — that's
exactly what the `(stream, seq)`-keyed transaction above absorbs.

### 4. Ordering across event types — the envelope

If several kinds of update must stay in **one** order — `start`, then `events`×N, then `end`, all for one
entity — do not send them as three actions and re-derive tolerance server-side. Send **one** action whose
input is a discriminated union, keyed per entity:

```ts
host_record: actionSchema()
  .input({ schema: v.variant("kind", [vStart, vEvents, vEnd]) })
  .fireAndForget()
  .reliable(),
// every send: .run({ streamKey: runId }) — one run = one totally-ordered stream
```

One action, one stream per run: `start` → `events` → `end` arrive in exactly that order with **zero**
app-level reordering tolerance, and the handler is a `switch (input.kind)`. (This is the shape a
migration from a legacy multi-action protocol should collapse to — if you're carrying "arrival-order
tolerance" code, you're holding the shape wrong.)

### 5. Reliable server→client push

Reliability engages connector→acceptor ([direction](#one-direction-pushes-are-best-effort)); a push stream
that must all arrive needs durable catch-up, which subsumes what a live-socket resend could give:

```ts
// Server: append each push to a per-client log — `append` assigns the seq, carry it in the payload.
const log = cloudflareReliableLog(this.ctx, "push");
const { seq } = log.append(`push::${clientId}`, update);
server.pushToClient(client, act_feed.action.entry.request({ seq, update })); // live path, best-effort

// Client: dedup/order with its own inbox (from `@nice-code/action/advanced`), ack via a normal action.
const inbox = new ReliableInbox<TUpdate>();
onPush: { entry: ({ seq, update }) => {
  for (const u of inbox.receive("feed", seq, update).deliver) apply(u);
  act_feed.action.ack.request({ upTo: inbox.contiguousSeq("feed") }).runToOutput();
}}

// Server, on reconnect: replay the gap-free prefix; prune what the client confirmed.
for (const update of log.contiguousPrefix(`push::${clientId}`)) resend(update);
// on ack: store.deleteThrough(`push::${clientId}`, upTo) — or set `keepDelivered` retention instead.
```

For a *single* push that needs confirmation, skip all of this: await
`pushToClient(...).waitForResultPayload()` and retry.

### 6. Stream teardown with multiplexed peers

The worked shape of the [multiplexed-peers warning](#multiplexed-peers-many-server-instances-behind-one-coordinate):

```ts
async function endRun(runId: string) {
  // 1. Close the run's streams FIRST — synchronous; nothing from run A can resend after this.
  connector.closeReliableStream(act_session.action.host_events, runId);
  // 2. Only then flip the dial state the WS carrier derives its URL from.
  activeRun.set(nextRunId);
}
```

Keep the payload stamp + server-side guard as defense-in-depth — the guard is terminal because
[acks are receipt, not outcome](#multiplexed-peers-many-server-instances-behind-one-coordinate).

---

# Serving & Connecting

Source: /nice-action/serving-connecting
Description: Stand up an acceptor with serveChannel and dial it with connectChannel.

`serveChannel` (listen) and `connectChannel` (dial) are the two functions you'll reach for. Each one takes the shared facts — your channel and your runtime — and applies them to every connection, so you only state them once.

## Listening — `serveChannel`

`serveChannel` registers your handlers, builds the crypto identity, sets up sleep/wake (hibernation), and hands back a `server` object. You export its web `fetch` — and, once you add a socket, forward your host's connection events — straight to your host.

### The simplest server — HTTP only

The smallest possible backend serves over a single HTTP carrier. `server.fetch` is a standard web `fetch` handler, so Bun, Deno, and Cloudflare Workers run a default `{ fetch }` export with nothing else to wire:

```ts title="server.ts"
import { ActionRuntime, serveChannel, httpAcceptorCarrier, createDefaultServeLogger } from "@nice-code/action";
import { createMemoryStorageAdapter_json } from "@nice-code/util";
import { appChannel, act_user, serverCoord } from "./shared"; // coordinates live in shared code

const serverRuntime = new ActionRuntime(serverCoord);

const userHandler = act_user.wrapAsLocalHandler({
  getUser: async ({ userId }) => ({ id: userId, name: "Ada Lovelace" }),
});

const server = serveChannel(serverRuntime, appChannel, {
  storage: createMemoryStorageAdapter_json(),   // swap for persistent storage in production
  carriers: [httpAcceptorCarrier()],            // HTTP only — no socket wiring
  handlers: [userHandler],
  logger: createDefaultServeLogger(),           // optional: one log line per request + outcome
});

// Bun / Deno / Cloudflare Workers serve a default `{ fetch }` export directly:
export default { fetch: server.fetch };
```

Run it with `bun run server.ts` (or `deno serve server.ts`, or deploy the module to a Worker). On Node, wrap `server.fetch` with a fetch-style adapter such as `@hono/node-server`. That's a complete, secure backend — clients dial it over the matching `httpCarrier` (see [Dialing](#dialing--connectchannel)).

> The in-memory store gets you running. Back it with persistent storage so the server's crypto identity and its trusted-client pins survive a restart — see [Storage](/nice-util/storage/).

### The `server` object

Whatever carriers you pass, `serveChannel` returns `{ acceptors, fetch, receive, drop, pushToClient, broadcast }`:

- **`fetch`** — the standard web handler above. It does the WebSocket upgrade, the action POST, the CORS preflight, and a 404 for anything else. Export it, or forward your host's `fetch` to it.
- **`receive(conn, frame)` / `drop(conn)`** — the live-connection lifecycle, needed once you add a WebSocket carrier (below). Forward your host's "message" event to `receive`, and its "close"/"error" events to `drop`.
- **`pushToClient` / `broadcast`** — for the server calling clients (see [Bi-directional](/nice-action/bidirectional/)).
- **`acceptors`** — the accept-side connection objects, one per duplex carrier. You rarely touch these; with several socket carriers, push/broadcast over a specific `acceptors[i]`.

## WebSockets — adding server push

HTTP alone is request/reply. To hold a live socket open and let the server **push** to a connected client, add a `wsAcceptorCarrier` alongside the HTTP one. The carrier needs just one thing from your host — how to **send** a frame to a socket (`send: (ws, frame) => ws.send(frame)`) — and you forward the host's socket events to `server.receive` / `server.drop`. The host performs the upgrade itself, so the carrier's `upgrade` is omitted and the socket is fed in "out of band". The secure handshake rides the same socket as ordinary messages, so the connection is authenticated by default with no extra steps.

> On Cloudflare Durable Objects all of this — the upgrade, the hibernation-safe attachment, and the keepalive — is folded into one `serveDurableObject` call. See [Cloudflare](/nice-action/cloudflare/).

### Bun

`Bun.serve` owns the upgrade, so let it perform the upgrade and feed its `websocket` events straight to the server:

```ts title="server.ts"
import type { ServerWebSocket } from "bun";
import { ActionRuntime, serveChannel, wsAcceptorCarrier, httpAcceptorCarrier } from "@nice-code/action";
import { createMemoryStorageAdapter_json } from "@nice-code/util";
import { appChannel, serverCoord } from "./shared";

const serverRuntime = new ActionRuntime(serverCoord);

const server = serveChannel(serverRuntime, appChannel, {
  storage: createMemoryStorageAdapter_json(),
  handlers: [userHandler],
  carriers: [
    wsAcceptorCarrier<ServerWebSocket>({ send: (ws, frame) => ws.send(frame) }),
    httpAcceptorCarrier(),   // HTTP fallback on the same channel
  ],
});

Bun.serve({
  port: 3000,
  fetch(request, bun) {
    // Hand the socket to Bun on an upgrade; everything else is an action POST / CORS / 404.
    if (request.headers.get("Upgrade") === "websocket") {
      return bun.upgrade(request) ? undefined : new Response("upgrade failed", { status: 400 });
    }
    return server.fetch(request);
  },
  websocket: {
    message: (ws, msg) => server.receive(ws, msg),
    close: (ws) => server.drop(ws),
  },
});
```

### Hono

Hono's WebSocket helper gives you the same hooks. The underlying socket is on `ws.raw` — that's what you hand to `server.receive` / `server.drop`, and what the carrier's `send` writes back to:

```ts title="server.ts"
import { Hono } from "hono";
import { createBunWebSocket } from "hono/bun";
import type { ServerWebSocket } from "bun";
import { ActionRuntime, serveChannel, wsAcceptorCarrier, httpAcceptorCarrier } from "@nice-code/action";
import { createMemoryStorageAdapter_json } from "@nice-code/util";
import { appChannel, serverCoord } from "./shared";

const { upgradeWebSocket, websocket } = createBunWebSocket<ServerWebSocket>();
const serverRuntime = new ActionRuntime(serverCoord);

const server = serveChannel(serverRuntime, appChannel, {
  storage: createMemoryStorageAdapter_json(),
  handlers: [userHandler],
  carriers: [
    wsAcceptorCarrier<ServerWebSocket>({ send: (ws, frame) => ws.send(frame) }),
    httpAcceptorCarrier(),
  ],
});

const app = new Hono();

app.get("/ws", upgradeWebSocket(() => ({
  onMessage: (event, ws) => { if (ws.raw) server.receive(ws.raw, event.data); },
  onClose: (_event, ws) => { if (ws.raw) server.drop(ws.raw); },
})));

// Action POST + CORS + 404 for every other route:
app.all("*", (c) => server.fetch(c.req.raw));

export default { fetch: app.fetch, websocket };
```

> `createBunWebSocket` is the Bun adapter; on Node swap in `@hono/node-ws`'s `createNodeWebSocket`, which exposes the same `upgradeWebSocket`. The send/receive wiring is identical — only the import changes.

## Dialing — `connectChannel`

The dialing side has one runtime and calls `connectChannel` once per server it wants to reach. It sends the channel's `toAcceptor` actions out over the transports (the first is preferred, the rest are fallbacks), and uses `onPush` to answer any `toConnector` pushes the server sends back.

```ts title="client.ts"
import { ActionRuntime, connectChannel, wsCarrier, httpCarrier } from "@nice-code/action";
import { appChannel, serverCoord, frontendCoord } from "./shared"; // same coordinates the server uses

export const clientRuntime = new ActionRuntime(frontendCoord);

connectChannel(clientRuntime, appChannel, {
  peer: serverCoord,                        // the server's coordinate, straight from shared
  storage,                                  // persistent storage for this runtime
  transports: [
    { carrier: wsCarrier(() => ({ url: "wss://api.example.com/ws" })) },          // preferred
    { carrier: httpCarrier(() => ({ url: "https://api.example.com/action" })) },  // fallback
  ],
  // onPush: { ... }   // your handlers for the server's pushes
});
```

The main options: `peer` (which server you're calling), `transports` (your carriers in preference order — it falls back automatically), `storage`, `onPush`, and `defaultTimeout` (plus `reliableActionTimeout` for [reliable actions](/nice-action/reliable-delivery/)). It returns the connection itself (a `ChannelConnector`) — keep it as `connector` when you need it later: `connector.clearTransportCache()` on teardown, or `realmConnection(connector)` to ride a [realm](/nice-realm/connecting/) on the same socket.

> **The client's `storage` must be durable too.** It holds this client's crypto identity, and the server pins that identity's verify key the first time they meet — so a store that forgets across page loads (a memory adapter) gets the client rejected from its second load on. In a browser, `createWebLocalStorageAdapter({ localStorage })`; the full story is on [Identity & Trust](/nice-wire/identity/#your-storage-must-be-durable--the-mistake-that-bites).

> **Your connections are already protected.** By default `serveChannel` and `connectChannel` set up an authenticated connection for you — there's nothing extra to wire up here. When you want to choose between authenticated and encrypted, or turn it off for local dev, see [Security Levels](/nice-wire/security/).

## Logging served requests

For a "host and forget" backend you often just want to see what's coming in. Pass a `logger` to `serveChannel` and it logs every accepted request and its outcome — one line when the request arrives, one when its result goes back (with the elapsed time). `createDefaultServeLogger()` is a ready-made console logger you can drop straight in:

```ts title="server.ts"
import { serveChannel, createDefaultServeLogger } from "@nice-code/action";

const server = serveChannel(serverRuntime, appChannel, {
  storage: storageAdapter,
  carriers: [httpAcceptorCarrier()],
  handlers: [userHandler],
  logger: createDefaultServeLogger(),
});

// ▶ act_user/getUser  via http  from envId[frontend]…  [encrypted]
// ✓ act_user/getUser  ok  via http  12ms
```

Every line is tagged with the carrier that handled the request (`http`, `ws`, …), so the logger spans all your carriers at once. A failed request logs the error's id and message and goes to `console.error`.

The default logger takes a few options:

- **`logInputs`** — also print each action's input. **Off by default**, since inputs can carry sensitive data — opt in only when you want it.
- **`showSecurityLevel`** — show the negotiated level (`[encrypted]`, …) on the request line (default `true`).
- **`tag`** — the prefix on every line, for grepping (default `"[nice-action]"`).
- **`sink`** — where lines are written (anything with `log` / `error`; defaults to `console`).

```ts
logger: createDefaultServeLogger({ logInputs: true, tag: "[api]" }),
```

To forward into your own stack (pino, a metrics sink, …) instead of the console, implement `IActionServeLogger` directly — its `onRequest(info)` fires when a request is accepted and returns a reporter the server calls with the outcome, so one logger call spans the whole request → response and you can pair the two lines (and time the gap) however you like. Returning `undefined` from `onRequest` skips the result line (handy for sampling or muting a noisy action).

> This lightweight per-request logger is distinct from the richer [server devtools host](/devtools/backends/) (`createNiceServerDevtools` / `actionDomainScope`), which attaches to a domain and reports each action's full lifecycle. Use the `logger` option for a quick request/response trace on the serving side; reach for the devtools host when you want lifecycle stages, payload inspection, or a live stream into a devtools window. The same `logger` flows through `serveDurableObject` / `serveWorker` on Cloudflare.

## Traffic instrumentation — `wireTap`

Beside the per-request `logger`, both `serveChannel` and `connectChannel` take a **`wireTap`** — a
per-*frame* hook that sees every frame in and out of every carrier, tagged by its **lane** (`action`,
a protocol id like `realm`, `handshake`, `keepalive`, `http`) and its byte size. Off by default (omit
it), zero overhead when absent.

It is the seam the devtools **Traffic** view rides: feed it a `TrafficMetricsCore` and contribute
that to a devtools host (see [React Query & Devtools](/nice-action/integrations/)), or pass your own
function to route byte counts straight into your telemetry. One hook spans every carrier at once, so
it is the place to measure real egress — the Cloudflare per-message billing lens included.

```ts
// doc-check: skip — illustrative wiring; the devtools host lives in @nice-code/devtools-core
const traffic = new TrafficMetricsCore();
serveChannel(runtime, channel, { storage, carriers, wireTap: traffic.wireTap });
```

## A realm (or any protocol) needs a duplex carrier

You ride a [realm](/nice-realm/connecting/) — or any prefixed mux protocol — on a connection with
`realmConnection(connector)`. That needs a **duplex** carrier (a WebSocket): a mux protocol pushes
unsolicited frames, which an exchange-only (request/reply HTTP) connection cannot carry. Register one
on an exchange-only connection and it throws `protocol_on_exchange_only` **at bring-up** — when the
connection is constructed, not later at connect time — deliberately, so a missing socket is a loud
construction error rather than a silent mid-session surprise. Keep an `httpCarrier` in the chain as a
*fallback* for the action lane; the realm simply rides the socket when one is up.

A client that dials before its server is up does **not** fail permanently — the first failed dial arms the same keep-alive backoff ladder a mid-session drop would. See [the first connect](/nice-realm/resilient-client/#the-first-connect--when-the-server-isnt-up-yet) for what that looks like and how to bound it.

---

# Creating & Reading

Source: /nice-error/creating-reading
Description: Create single- and multi-id errors, then read and narrow them by id.

## Creating errors

```ts
// Single id — context required per schema
const err1 = err_auth.fromId("invalid_credentials", { username: "alice" });

// Multi-id in one error — several things went wrong at once
const err2 = err_auth.fromContext({
  invalid_credentials: { username: "bob" },
  rate_limited: { retryAfter: 30 },
});

// Chain additional ids after construction
const err3 = err_auth.fromId("account_locked").addId("rate_limited");
```

A single `NiceError` can carry **multiple active ids**. This models real situations — a request that is both unauthenticated _and_ rate-limited — without forcing you to pick one.

## Reading and narrowing

```ts
// Check and narrow — inside the guard, getContext is fully typed
if (err1.hasId("invalid_credentials")) {
  const { username } = err1.getContext("invalid_credentials");
}

// Check several ids at once — narrows to that subset
if (err2.hasOneOfIds(["invalid_credentials", "rate_limited"])) {
  // ...
}

// All active ids
err2.getIds(); // ["invalid_credentials", "rate_limited"]
```

## Pattern matching

`matchFirst` runs the first handler whose id is active and returns its result. Provide `_` as a fallback.

```ts
import { matchFirst } from "@nice-code/error";

const message = matchFirst(err1, {
  invalid_credentials: ({ username }) => `Wrong password for ${username}`,
  account_locked: () => "Account locked",
  _: () => "Unknown auth error",
});
```

## Instance properties

```ts
const e = err_auth.fromId("invalid_credentials", { username: "alice" });

e.domain;          // "err_auth"
e.message;         // "Invalid credentials for: alice"
e.httpStatusCode;  // 401
e.getIds();        // ["invalid_credentials"]
```

---

# Error Domains

Source: /nice-error/domains
Description: Declare typed error schemas with defineNiceError and the err() helper.

An **error domain** is a named group of related errors. Each entry in its **schema** ties an error id to a message, an HTTP status, and (optionally) some typed extra data called **context**.

## The words we use

- **Domain** — a named group of related errors (`err_auth`, `err_payment`).
- **Schema** — the list that maps each error id to its message, HTTP status, and optional context.
- **Error id** — a short name for what went wrong. One error can have several ids active at once.
- **Context** — extra data attached to an id (e.g. `{ username: string }`).
- **Hydration** — when an error has travelled as JSON, hydration turns its context back into the real typed values it started as.

## Defining a domain

```ts
import { defineNiceError, err } from "@nice-code/error";

export const err_auth = defineNiceError({
  domain: "err_auth",
  schema: {
    // No context — second arg to fromId is not accepted
    account_locked: err({
      message: "Account is locked",
      httpStatusCode: 403,
    }),

    // Required context — second arg to fromId is required
    invalid_credentials: err<{ username: string }>({
      message: ({ username }) => `Invalid credentials for: ${username}`,
      httpStatusCode: 401,
      context: { required: true },
    }),

    // Optional context
    rate_limited: err<{ retryAfter: number }>({
      message: (ctx) => (ctx ? `Retry after ${ctx.retryAfter}s` : "Rate limited"),
      httpStatusCode: 429,
      context: {},
    }),
  },
});
```

## The `err()` helper

`err()` describes one error in the schema. How you call it decides whether context is allowed — or required — when you later create the error:

| How you declare it | `fromId("id")` | `fromId("id", ctx)` |
|---|---|---|
| `err()` / `err({ message, httpStatusCode })` — no context | ✓ | ✗ |
| `err<C>({ context: {} })` — optional context | ✓ optional | ✓ optional |
| `err<C>({ context: { required: true } })` — required context | ✗ | ✓ required |

`message` and `httpStatusCode` can each be a fixed value, or a function that builds the value from the context.

## Sending context that isn't plain JSON

If a context value isn't something JSON can carry on its own (an `Error`, a `Date`, a `Map`), give it a pair of functions — one to pack it, one to unpack it — so it survives the trip:

```ts
fs_error: err<{ cause: NodeJS.ErrnoException }>({
  message: ({ cause }) => `FS error: ${cause.message}`,
  context: {
    required: true,
    serialization: {
      toJsonSerializable: ({ cause }) => ({ code: cause.code, message: cause.message }),
      fromJsonSerializable: (obj) => ({ cause: Object.assign(new Error(obj.message), obj) }),
    },
  },
}),
```

The packed form is what travels over the network; [hydration](/nice-error/serialization/) unpacks it back into the real value on the other side.

## Utility types

```ts
import type { InferNiceError, InferNiceErrorHydrated } from "@nice-code/error";

type TAuthError = InferNiceError<typeof err_auth>;
type TAuthErrorHydrated = InferNiceErrorHydrated<typeof err_auth>;
```

---

# Handling Errors

Source: /nice-error/handling
Description: Route errors with composable handlers or a reusable handler class.

nice-code offers two handling styles: a composable functional API, and a reusable class.

## Functional style

Build a list of cases with `forId`, `forIds`, and `forDomain`. `handleWithSync` runs the first matching case and returns whether anything handled it.

```ts
import { forDomain, forId, forIds } from "@nice-code/error";

const handled = error.handleWithSync([
  forId(err_auth, "invalid_credentials", (h) => {
    const { username } = h.getContext("invalid_credentials");
    return res.status(401).json({ error: `Bad credentials for ${username}` });
  }),
  forIds(err_auth, ["account_locked", "rate_limited"], (h) => {
    return res.status(h.httpStatusCode).json({ error: h.message });
  }),
  forDomain(err_payment, (h) => {
    return res.status(500).json({ error: "Payment failed" });
  }),
]);
```

The handler argument (`h`) is narrowed to the matched id(s), so `getContext` is typed inside each case.

### Async handlers

```ts
await error.handleWithAsync([
  forDomain(err_payment, async (h) => {
    await db.logFailure(h.message);
    await notify(h.toJsonObject());
  }),
]);
```

## Class-based style

`NiceErrorHandler` is a reusable handler you configure once and apply to many errors — ideal for a central error boundary.

```ts
import { NiceErrorHandler } from "@nice-code/error";

const handler = new NiceErrorHandler()
  .forId(err_auth, "invalid_credentials", (h) => "unauthorized")
  .forDomain(err_payment, (h) => "payment_error")
  .setDefaultHandler((e) => "unknown_error");

handler.handleErrorWithPromiseInspection(error);
```

## Choosing a style

- **Functional** — local, one-off routing inside a single catch block.
- **Class-based** — a shared, reusable policy you register once (server middleware, a global boundary).

---

# Domain Hierarchies

Source: /nice-error/hierarchy
Description: Compose domains into parent/child trees and match across ancestry.

Domains can nest. A child domain inherits its place in the tree, so a handler can match a broad parent without enumerating every child's ids.

## Creating child domains

```ts
const err_app = defineNiceError({ domain: "err_app", schema: {} });

const err_auth = err_app.createChildDomain({
  domain: "err_auth",
  schema: { /* ... */ },
});

const err_auth_registration = err_auth.createChildDomain({
  domain: "err_auth_registration",
  schema: { /* ... */ },
});
```

## Ancestry checks

```ts
err_app.isParentOf(err_auth_registration);   // true
err_auth.isParentOf(err_auth_registration);  // true
err_auth_registration.isParentOf(err_auth);  // false
```

## Type guards

```ts
// Exact domain match only
err_auth.isExact(someError);        // true only for the err_auth domain

// This domain OR any descendant
err_auth.isThisOrChild(someError);  // true for err_auth and all its children
```

Use `isExact` when you want to handle exactly one domain's errors; use `isThisOrChild` to catch a whole subtree — e.g. "any auth-related error" regardless of which specific child domain produced it.

## When to nest

- Group errors by bounded context: `err_app` → `err_auth` → `err_auth_registration`.
- Let middleware match broadly (`err_auth.isThisOrChild`) while leaf code matches precisely (`err_auth_registration.isExact`).
- Keep domain strings stable — they're part of the serialized identity.

---

# Packing

Source: /nice-error/packing
Description: Smuggle a full error through transports that only preserve message or cause.

Some layers — certain RPC systems, the boundary into a Cloudflare Durable Object, job queues — only pass along an error's `message` (or `cause`) and throw away every other property. **Packing** tucks the whole error into one of those fields that *do* survive, so you can rebuild it on the other side.

## Packing

```ts
import { EErrorPackType } from "@nice-code/error";

// `pack` MUTATES the error in place — it rewrites the chosen field (message/cause) on
// THIS instance and returns the same object (not a clone). The original value is stashed
// internally so `unpack` can restore it.
error.pack(EErrorPackType.msg_pack);   // embeds the JSON into error.message
error.pack(EErrorPackType.cause_pack); // embeds the JSON into error.cause
```

Throw the packed error across the boundary just like any normal `Error`.

## Unpacking

```ts
error.unpack(); // restore the original NiceError
```

In practice you rarely call `unpack` yourself — [`castNiceError`](/nice-error/serialization/) notices a packed error and unpacks it for you:

```ts
import { castNiceError } from "@nice-code/error";

const restored = castNiceError(caught); // unpacks if it was packed
```

## When to reach for it

- A **Durable Object** only re-throws `message` when you call into it — pack with `msg_pack` before throwing inside the DO.
- A job queue only keeps the error's message — pack before adding the job, then `castNiceError` after pulling it off.
- Any layer where you don't control how things are serialized and only the standard `Error` fields make it through.

For boundaries you _do_ control (your own HTTP responses), just use [`toJsonObject()` + `castNiceError`](/nice-error/serialization/) instead — packing is only for the ones you don't.

---

# Results & Observability

Source: /nice-error/results-observability
Description: Turn throwing code into typed results, and tap every NiceError for logging.

Two things that work well together: a result type for running code that might fail without `try`/`catch`, and
a single place to hook into so every `NiceError` can be sent to your logger or telemetry.

## Running code that might fail — `niceTry`

`niceTry` / `niceTryAsync` run a function that might throw and hand you back a typed result. If it fails, the
error is **always** a `NiceError`.

```ts
import { niceTry, niceTryAsync, type TNiceResult } from "@nice-code/error";

const r = niceTry(() => JSON.parse(input));
if (!r.ok) report(r.error); // r.error is a NiceError (isUnhandled === true for a raw throw)
else use(r.output);

const r2 = await niceTryAsync(() => fetchUser(id)); // accepts a sync or async fn
```

Behind the scenes the `catch` runs through [`castNiceError`](/nice-error/serialization/): a thrown domain
error comes through as-is, while anything else is wrapped into an `isUnhandled` error.

### `TNiceResult` and its builders

```ts
type TNiceResult<OUT, ERR extends NiceError = NiceError> =
  | { ok: true; output: OUT }
  | { ok: false; error: ERR };
```

Build results by hand with `niceOk` / `niceErr` when a function returns a `TNiceResult` directly:

```ts
import { niceOk, niceErr } from "@nice-code/error";

function parsePort(raw: string): TNiceResult<number> {
  const n = Number(raw);
  return Number.isInteger(n) ? niceOk(n) : niceErr(err_config.fromId("bad_port", { raw }));
}
```

> `@nice-code/action`'s action outcome is just a `TNiceResult` with one extra field (`expected`), so the two
> fit together neatly — see [Error Handling](/nice-action/error-handling/).

## Watching every error

`onNiceError` runs every time a `NiceError` is created — send those to Sentry, OpenTelemetry, or your devtools.

```ts
import { onNiceError, setNiceErrorLogger } from "@nice-code/error";

const off = onNiceError((error) => report(error.toStructuredLog()));
// ...later
off(); // remove the tap
```

`error.toStructuredLog()` returns a flat, log-friendly object distinct from `toJsonObject()` (the wire
form):

```ts
{ domain, ids, message, httpStatusCode, isUnhandled, timeCreated, originError? }
```

### Routing the library's own diagnostics

The library's internal warnings default to `console`. Redirect them through your own logger:

```ts
setNiceErrorLogger({ warn: myLogger.warn, debug: myLogger.debug, error: myLogger.error });
```

## Internal subpath

The main `@nice-code/error` surface is all most apps need. The lower-level helpers — inspecting the wire
format, the `err_cast_not_nice` fallback domain, `isNiceErrorObject`, context-state types — sit behind a
separate subpath, meant for libraries built on top of `nice-error`:

```ts
import { isNiceErrorObject, err_cast_not_nice } from "@nice-code/error/internal";
```

---

# Serialization & Transport

Source: /nice-error/serialization
Description: Send typed errors across HTTP and reconstruct them with full types.

A `NiceError` turns into plain JSON, travels over the network, and is rebuilt on the other side — with its ids, context, and HTTP status all intact.

## Serializing

```ts
const json = error.toJsonObject();    // plain JSON object — safe over HTTP
const str = error.toJsonString();     // JSON string
const response = error.toHttpResponse(); // a Response with the correct HTTP status
```

## Receiving — `castNiceError`

On the receiving side, `castNiceError` turns _any_ caught value into a `NiceError`:

```ts
import { castNiceError } from "@nice-code/error";

const caught = castNiceError(unknownValue); // always returns a NiceError

if (err_auth.isExact(caught)) {
  const hydrated = err_auth.hydrate(caught); // deserialize context
  const { username } = hydrated.getContext("invalid_credentials");
}
```

`castNiceError` copes with anything you hand it — a `NiceError`, a JSON object, a plain `Error`, an error-like object, `null`/`undefined`, even a primitive — and it never throws.

## One-step — `castAndHydrate`

When you have a specific domain in mind, `castAndHydrate` casts, checks the domain, and hydrates in a single call:

```ts
import { castAndHydrate, matchFirst } from "@nice-code/error";

const error = castAndHydrate(unknownValue, err_auth);
// → a hydrated NiceError when it belongs to err_auth, otherwise the raw cast NiceError

if (err_auth.isExact(error)) {
  const message = matchFirst(error, {
    invalid_credentials: ({ username }) => `Wrong password for ${username}`,
    account_locked: () => "Account locked",
  });
}
```

## Why hydration matters

Only JSON travels over the network. So if an id's context held a `Date`, an `Error`, or anything with a [custom pack/unpack pair](/nice-error/domains/#sending-context-that-isnt-plain-json), **hydration** is the step that turns the JSON form back into the real typed value. Always `hydrate` (or `castAndHydrate`) before reading context that just came in from somewhere else.

## A full round trip

```ts
// Server
return error.toHttpResponse();

// Client
const caught = castNiceError(await res.json());
if (err_auth.isExact(caught)) {
  const hydrated = err_auth.hydrate(caught);
  // hydrated.getContext(...) is now fully typed and real
}
```

---

# Connecting & React

Source: /nice-realm/connecting
Description: The client handle — connectRealm over your app's connection, status and liveness, the staleness probe, the patch feed, replicas, and the React hooks.

A realm attaches to your app's **connection** — one secure socket, one handshake, one authenticated identity. The connection is a `@nice-code/wire` concern; a realm rides it, actions ride it, both can share one. Open it with **`createWireClient`** when the realm is the only traffic (no `@nice-code/action` at all — see [Realm-only apps](#realm-only-apps--createwireclient) below), or with **`connectChannel`** when the app also has actions and both planes share the one socket:

```ts title="client.ts"
import { connectChannel } from "@nice-code/action";
import { connectRealm, realmConnection } from "@nice-code/realm";

// The app's connection — the realm rides it (alongside actions, or alone).
const connector = connectChannel(runtime, gameChannel, { peer, storage, transports });

const realm = connectRealm(gameRealm, {
  avatar: { type: "player" },     // persistentId defaults from the authenticated coordinate
  connection: realmConnection(connector),
  onMutationRejected: ({ error, rolledBackPaths }) => toastRollback(error, rolledBackPaths),
});

realm.store                                                 // @nice-code/state Store
realm.update((draft) => { draft.players[me].x = 412; });    // optimistic; returns a settle handle
realm.intents.purchase({ purchaseId: newId(), itemId });    // settle-only server mutation
realm.pending                                               // { count, has(prefix), subscribe }
```

`realm.store` is a regular [`@nice-code/state` Store](/nice-state/stores/) holding the projected view — read it, subscribe to it, and bind it to React exactly like any other store. The projection starts empty and fills on hydrate. (`connectChannel` itself — the peer coordinate, storage, and transports — is covered in [Serving & Connecting](/nice-action/serving-connecting/); the realm-only sample below shows a complete call.)

The `avatar.type` is always explicit (it's realm-specific); `persistentId`/`instanceId` default from the connection's **authenticated coordinate** when it has one — pass them explicitly only for tests and replicas. If the server resolves your identity differently than the client believes (a resolver mismatch), the client warns loudly once — the symptom would otherwise be "prediction passes locally, server rejects every time".

### Realm-only apps — `createWireClient`

A realm-only app has no actions, so it needs **no `@nice-code/action` at all** — no `ActionRuntime`, no channel. Open the connection directly with `createWireClient` from `@nice-code/wire` and bind the realm onto it. It takes the same facts every secure connection needs — who you are (`identity`), who you're dialing (`peer`), how you prove it (`storage`), and how you reach it (`transports`):

```ts title="client.ts"
import { connectRealm, realmConnection } from "@nice-code/realm";
import { createWireClient, wsCarrier } from "@nice-code/wire";

const client = createWireClient({
  identity: myCoordinate,                          // this client's authenticated coordinate
  peer: serverCoordinate,                          // the acceptor it dials
  storage,                                         // persists the crypto identity (TOFU)
  transports: [{ carrier: wsCarrier(() => ({ url })) }],
});

const realm = connectRealm(gameRealm, {
  avatar: { type: "player" },                      // persistentId defaults from `identity`
  connection: realmConnection(client),
});
await client.connect();   // dial + secure handshake; the realm hello follows on the same pipe
```

`createWireClient` returns the same connection surface `connectChannel` does — `realmConnection` binds to either structurally, so `connectRealm` doesn't know or care which opened the socket. Everything on this page below the connection — keepalive, link events, the redial ladder, the staleness probe — is identical for both, because it all lives on the wire connection, not the plane riding it. (`connectChannel` is the action-side twin: same `peer`/`storage`/`transports`, plus a channel and `onPush`. See [Serving & Connecting](/nice-action/serving-connecting/).)

With actions in play the first action call dials implicitly; a realm-only app calls `client.connect()` itself.

## Status & liveness

```ts
await realm.whenLive();               // resolves on first hydrate; rejects on attach failure/timeout
realm.status;                         // "connecting" | "live" | "detached"
realm.version;                        // the confirmed authoritative version
realm.subscribeStatus((status) => …); // fires on EVERY transition, incl. quiet link drops
realm.detach();                       // leave: sends detach, expires pending writes
```

An attach the server refuses (schema-hash mismatch, unknown realm, unresolvable identity) surfaces on `realm.attachError` and rejects `whenLive()`.

**Write after `whenLive()`**, not before: the projection is `{}` until the first hydrate, and a `realm.update()` in that window settles as a guided `write_before_hydrate` rejection (a draft that throws re-throws with the same hint). State that must exist *whenever you're attached* doesn't need to race that at all — declare it once:

### `assertOnAttach` — state you must own while attached

```ts
const realm = connectRealm(lobbyRealm, {
  avatar: { type: "player" },
  connection: realmConnection(connector),
  // Runs after EVERY full hydrate: the first attach, an out-of-log-window resume,
  // and an epoch change (a wiped or ephemeral server that cold-started).
  assertOnAttach: (draft) => { draft.players[me] = currentEntry(); },
});
```

It is an ordinary optimistic write — rules apply, rejections surface once via `onMutationRejected` — that the library re-runs exactly when your entry could have been lost, and never on an incremental patch-replay resume (your entry is still confirmed state there). It resolves before `whenLive()` continuations run, so "await whenLive, read my entry" always sees it. This one option replaces the hand-rolled join/rejoin/re-assert stacks presence apps build; the [Presence Realms](/nice-realm/presence/) guide is built around it.

## Reconnects & durability

What actually happens to your writes when the link drops — nothing here needs app code:

1. **Pending writes resend automatically.** Every unconfirmed optimistic frame survives a disconnect and is rebuilt against the fresh basis and resent on reattach — whether the server answers the re-hello with a patch replay or a full hydrate. A flaky socket does not lose writes; you do not need to re-issue anything on reconnect.
2. **`pendingExpiryMs` (default 10 s) is the only loss window** — and it's an *optimistic-settle* dial, not a delivery deadline: past it, the write's UI effect rolls back and `onMutationRejected` fires with the rolled-back paths. It is per-handle: a producer whose screen renders from local truth (a game host drawing from its own simulation) can raise it freely — the usual cost of a long window, stale UI that snaps back, doesn't apply there. **A `frame_too_stale` rejection is an _unknown_ outcome, not a definite "no":** the write may have committed on the server while the ack was lost. Don't blindly re-issue a **non-idempotent intent** on it — re-read state (it converges on the next replay/hydrate) and decide. A *rules* rejection, by contrast, carries the rule's own error and is a definite reject.
3. **`durability: "reassert"` removes the window entirely** for regions the client authoritatively produces (append-only logs): those frames resend across reconnects — and across epoch changes — until the server confirms or rejects them. See [Durable writes](/nice-realm/writes-intents/#durable-writes-durability-reassert).
4. **`assertOnAttach` covers the *confirmed-then-lost* case** — state the server once had but lost to a wipe/ephemeral cold start. Durability covers *never-confirmed* writes; the assert hook covers confirmed ones. A presence realm typically wants only the hook; a producer wants only the tier.
5. **The staleness probe is a *read* self-heal, not a redelivery mechanism** — it re-syncs what you *see* (below), and never rescues an expired write. Write durability is points 2–4.

And the boundary that stays: a durable exchange that needs a **data response** (submitting a score, anything with an ack payload the app must act on) is the action plane — [reliable delivery](/nice-action/reliable-delivery/), with its own 10-minute-class redelivery deadline.

### Who re-dials the link — nothing here needs app code either

A realm is push-driven, so a permanently dead socket is never the right steady state. The connection **owns its own reconnection**: when a realm rides a wire link (from `createWireClient` or `connectChannel`), an unexpected drop auto-redials with exponential backoff + jitter (≈1 s → 30 s), and on success the mux re-attaches and every realm re-hellos and resumes. You don't dispatch anything or call `connect()` again. Opt out with `keepLinkAlive: false` when your app manages its own connection lifecycle; an explicit `.clearTransportCache()` or `.dispose()` on the client/connector always stops it. (A pure-action connection is unchanged — it keeps its dispatch-driven reconnect.)

The realm's own **staleness probe** (below) is the other half: it escalates a *half-open* socket — one that looks open but silently swallows sends — by asking the connection to re-dial. Together they mean a game client recovers from both a clean drop and a network blip without app-level plumbing.

### The staleness probe

On by default (`staleProbeAfterMs: 25_000`; `0` disables): a `live` handle that hears **no realm frame** for the window quietly re-hellos with its last-known version and log **epoch**. The probe is idempotent by design:

- a **current** client gets an ~10 B empty replay (which itself re-arms the timer);
- a **stale** client gets exactly the missed patches;
- a **wiped or re-created** server forces a clean full hydrate — the epoch names the history, so version numbers from a different past never replay as a diff.

Lost wake broadcasts, missed frames, suspended tabs — every "silently stale forever" failure mode converges on *quiet too long → probe → resync*. The probe never flips `status`, so an idle-but-healthy connection shows no UI flap.

**Escalation (`probeReplyTimeoutMs`, default 10 s; `0` disables).** A half-open socket answers the probe's re-hello with silence. If no frame arrives within this window after a probe, the link is presumed dead: `status` flips to `"connecting"`, a `probe_escalated` diagnostic fires, and the connection is asked to re-dial (the reconnect-ownership above). So the worst-case time to notice a dead-but-open socket is roughly `staleProbeAfterMs + probeReplyTimeoutMs` (≈35 s by default) — tune both down for a twitchier game.

### Observing sync health — `onDiagnostic`

Wire it in production; a healthy realm emits nothing. It reports automatic recoveries so you can alarm on a *rate* of them rather than discover a bad link from user reports:

```ts
connectRealm(gameRealm, {
  connection: realmConnection(connector),
  onDiagnostic: (event) => metrics.count(`realm.${event.type}`), // resync | gap_dropped | frame_error | probe_escalated
});
```

- `resync` — a lost/misapplied frame was detected (a version gap or a decode/apply failure) and healed by an automatic re-hello.
- `gap_dropped` — a non-continuous frame that crossed an in-flight recovery was dropped (expected during a resync; benign).
- `frame_error` — an inbound frame failed to decode/apply and triggered a resync (should be ~never — investigate if it recurs).
- `probe_escalated` — a probe went unanswered and the link was re-dialed (above).

**Unwired, the library still leaves a floor:** the first occurrence of each diagnostic type logs one `console.warn`, and a rolled-back optimistic write with **no `onMutationRejected` handler** warns once too — so a "my move silently vanished" bug is never fully invisible. Wire both handlers to replace the warnings with real telemetry.

### Limits are advertised and livable

The hydrate advertises the server's ingress limits. An over-limit coalesced flush **splits** into consecutive ≤`maxPatchesPerFrame` frames (each part server-atomic; all handles settle with the last part, so read-your-writes holds), and `limits_exceeded` rejects **retry** — re-split against a halved ceiling, or a ~1 s backoff for rate breaches — instead of settling fatally. A well-behaved client stays attached under load without you tuning anything.

## The patch feed (imperative renderers)

React re-renders from the store — but a canvas, a typed array, a WebGL scene wants **deltas**, not snapshots:

```ts
realm.listenToPatches((patches) => board.applyPatches(patches));
```

The feed emits the projected-store delta per flush, in name-space [immer patch](/nice-state/patches/) shape:

- a confirmed-only flush with no optimistic overlay emits the authoritative patches **verbatim**;
- a rebase flush emits a **structural diff**, identity-pruned via immer's structural sharing (unchanged subtrees skip in O(1));
- a hydrate — or any full rebuild — emits exactly `[{ op: "replace", path: [], value }]`, the "rebuild everything" signal.

Listeners fire after the store flush, so the store already reflects the values. Apply the patches to your render target instead of re-diffing the whole state per flush.

## React hooks

`@nice-code/realm/react` is a thin layer over the handle:

| Hook | What it gives you |
|---|---|
| `useRealm(realm)` | The whole projected view (re-renders on any change — prefer `useRealmValue`). |
| `useRealmValue(realm, (v) => slice)` | A derived slice; re-renders only when the slice changes. |
| `useRealmStatus(realm)` | `{ status, version, pendingCount }` — connection UI. |
| `useRealmPending(realm, "players.p1")` | `true` while writes under the prefix are unconfirmed — the "saving…" affordance. |
| `useRealmIntent(realm, "purchase")` | `{ run, status, error }` — classic submit → spinner → done, zero rollback risk when the intent has no predictor. |

### Reading before hydrate: selectors must return a stable reference

"Write after `whenLive()`" has a **reads** counterpart, and it's easy to miss because the types hide it. Before the first hydrate, `realm.store.state` is genuinely `{}` — no keys at all — *regardless of what `TView` declares*. A mounted component reads the store on every render, so a direct page load renders your selectors against that empty `{}` at least once, before any network round-trip. `TView` says `presence` is always there; the runtime value in that window says otherwise.

That collides with a `useSyncExternalStore` rule `useRealmValue` inherits: **a selector must return the same reference when nothing changed.** A selector that fills a default for a possibly-absent field with an inline literal —

```ts
// ✗ allocates a fresh {} every call while state is still empty → infinite render loop
const presence = useRealmValue(realm, (v) => v.presence ?? {});
```

— returns a *new* object on every `getSnapshot`, so the hook sees "changed" every time and React trips its own guard: **"The result of getSnapshot should be cached to avoid an infinite loop"**, then "Maximum update depth exceeded". The fix is a stable fallback reference (a module constant, `useRef`, or `useMemo`) —

```ts
const EMPTY_PRESENCE: TView["presence"] = {};
// ✓ same reference every call → the hook's strict-equality fast path holds
const presence = useRealmValue(realm, (v) => v.presence ?? EMPTY_PRESENCE);
```

— or a non-strict comparator as the third argument, `useRealmValue(realm, sel, deepEqual)`, when the slice is genuinely recomputed each call. The same footgun applies to any narrow selector that *builds* a value (`.filter`, `.map`, an object literal) rather than returning a state branch as-is.

## Performance: pointer/cursor-frequency direct writes

Every `realm.update()` call — even one that's about to coalesce with others — synchronously commits to `realm.store` and notifies every subscriber before returning (`coalesceMs` only delays the *wire* send, never the local commit). Wire that straight to a native event that can fire dozens of times a second (`pointermove`, `drag`, a paint stroke) and you drive your renderer at native input frequency — often well above what the display can show, and well above what a *remote* peer's copy of the same path does (theirs arrives already coalesced by their sender's window plus network latency, in sparser jumps).

The result is a real, counter-intuitive symptom: **your own cursor can look laggier than a peer's**, even though it's always working from the freshest possible value. Remote motion looks smooth because it's sparse — a CSS transition (or any interpolation) fills the gaps nicely. Local motion re-renders, and restarts any transition, every single frame, which reads as trailing rather than live.

Two changes fix it, and a hot direct-write path generally wants both:

1. **Render off a narrow subscription, not the whole view.** `useRealmValue(realm, (v) => v.presence)` (or `realm.store.subscribe` / `listenToPatches` for a canvas/WebGL target) re-renders only what actually watches that slice — put it in its own component (or render target) so a cursor move doesn't also re-render a notes list, a HUD, or anything else sharing the page.
2. **Batch the writes to the render cadence** — typically one `requestAnimationFrame`: buffer the latest value in a ref and flush it as a single `realm.update()` call at most once per frame, instead of once per native event. There's no benefit to writing, or re-rendering, faster than the screen refreshes.

Apply any interpolation (CSS transitions, a lerp) only to *remote* entities. Your own value already updates every frame; smoothing it just adds a fixed visual lag with nothing to hide.

### Worried about network volume, not render cost? That's `coalesceMs`

The two fixes above are **render-side** — they don't change how much goes over the wire. Wire volume is a separate, already-solved axis: `connectRealm(realm, { coalesceMs })`. Every `update()` inside the window merges into one pending frame, collapsed **last-write-wins per path** (twenty `presence.p1.x` writes become one patch), and that frame ships once when the window closes. Sends cap at `1000 / coalesceMs` per second no matter how often you call `update()` — so `coalesceMs: 40` is ~25 frames/sec/client, whether the writes arrive at raw `pointermove` rate or already rAF-batched.

It's a **fixed-window throttle, not a resetting debounce**: the window doesn't restart on each new write, so a continuously-moving cursor keeps flushing every window — it never goes silent until motion stops (which is what a debounce would do, and exactly wrong for live presence). Reach for it on any pointer-frequency direct-write path; the render fixes above and this one are independent and a hot path usually wants all of them.

## Replicas

A Worker (or any process) that wants a live **read copy** — a matchmaker reading lobby state, an analytics tap — connects as a replica: a plain object plus a patches callback, no Store/React stack, no special authority. Its powers are whatever its avatar type's [rules](/nice-realm/rules/#replicas-are-an-avatar-rule) grant:

```ts
import { connectRealmReplica } from "@nice-code/realm";

const replica = connectRealmReplica(lobbyRealm, {
  avatar: { type: "replica", persistentId: "matchmaker" },
  connection: realmConnection(connector),
  onPatches: (patches, { version }) => index.apply(patches),
});

replica.state;      // the confirmed slice (plain object, replaced per batch)
replica.update(…);  // non-optimistic write — settles on the server verdict
replica.intents.kick({ playerId });  // typed intents — the same mapped object as the client handle
```

Intents are compile-typed on the replica handle exactly as on the client handle — a misspelled intent is a compile error, not a runtime `intent_unknown`. For dynamic names there is an untyped `replica.intent(name, input)` fallback; prefer the mapped object.

Replicas get the same `subscribeStatus`, staleness probe (with `probeReplyTimeoutMs` escalation), `onDiagnostic`, and reconnect ownership as full clients — they live longer, so silent staleness matters more, not less. A replica's `update`/`intent` is non-optimistic, but its handle is still bounded: an unacked write is resent on every recovery and rejects `frame_too_stale` after `pendingExpiryMs` (default 10 s) rather than hanging forever — so `await replica.update(...)` always settles.

---

# Defining a Realm

Source: /nice-realm/defining-realms
Description: The defineRealm block — state schema via the t builder, avatar types, server context, and the schema hash.

A realm is declared once, in shared code, with `defineRealm`. Both the client and the server import this exact definition — it is the type boundary, the wire vocabulary, and the rulebook, all derived from one block:

```ts title="shared/marketRealm.ts"
import { defineRealm, t } from "@nice-code/realm";

export const marketRealm = defineRealm({
  id: "market_realm",
  serverContext: t.serverContext<{ db: MarketDb }>(),
  avatars: {
    vendor:   { persistentId: t.string() },
    consumer: { persistentId: t.string() },
  },
  state: {
    config: t.object({ open: t.boolean(), taxRate: t.number() }),
    inventory: t.record(
      t.id("vendorId"),
      t.record(t.id("produceId"), t.object({ pricePerKg: t.number(), stockKg: t.number() })),
    ),
    presence: t.record(t.id("avatarId"), t.object({ cursorX: t.number(), cursorY: t.number() })),
  },
  rules: (r) => [ /* next page */ ],
  intents: (i) => ({ /* the writes-and-intents page */ }),
});
```

> **This module ships to clients.** Never close over secrets in a realm definition. Server-only data enters at serve time via `createRealmServerEngine(realm, { ctx })` — declare its *type* here with `serverContext: t.serverContext<MyCtx>()`, and it becomes reachable only inside `r.serverChecked(...)` rules and intent `apply` bodies. Nothing in the definition module itself ever holds a secret.

## The `t` schema builder

The `state` shape is declared with `t.*` nodes. From this single declaration the library derives the TypeScript state type, the compact wire token map (keys travel as small integers, not strings), the schema hash, and the server-side value validator.

| Builder | What it declares |
|---|---|
| `t.string()` / `t.number()` / `t.boolean()` | Primitive leaves. |
| `t.literal(value)` | An exact value (`t.literal("open")`). |
| `t.union(a, b, …)` / `t.union([a, b, …])` | One of several nodes (spread or a single array). |
| `t.optional(inner)` | May be absent (deletable). |
| `t.object({ … })` | Fixed keys, each its own node. |
| `t.record(t.id("varName"), value)` | A dynamic keyed collection. The `t.id` name binds `$varName` in rule paths. |
| `t.array(item)` | An array — **an atomic leaf on the wire** (replaced whole). Prefer keyed records. |
| `t.schema(valibotSchema)` | Embed any Standard Schema validator at a leaf. |
| `t.serverContext<TCtx>()` | Declares the server-only context *type* (not part of state). |

Three of these deserve emphasis:

- **Prefer `t.record` over `t.array`.** Records are keyed collections — each entry is its own wire path, so two clients editing different entries never conflict, and rules can address entries by key (`inventory.$vendorId.…`). Arrays have leaf-replace semantics: the whole array travels on every change. Two consequences of being a wire-leaf:
  - **Rule an array with its exact path.** Patches and visibility for `terrain: t.array(t.number())` are decided at exactly `terrain`, so the rule is `r.path("terrain")` — `r.path("terrain.**")` could never match anything (wildcards need at least one further segment), and `defineRealm` throws on such dead patterns.
  - **Replace, don't mutate, in intents.** In-draft element writes (`state.terrain[i] = v`) commit as a whole-array replace either way — write `state.terrain = next` so the code says what the wire does.
- **`t.schema(...)` is invisible to the schema hash.** Embedding a Valibot/Zod validator gives you rich value validation at a leaf, but editing the embedded schema does **not** change the realm's `schemaHash` — treat embedded-validator changes as value-rule changes, not shape changes.
- **Record keys are strings on the wire.** Writing `d.log[ev.seq] = ev` with a numeric `seq` works (JS coerces), but hydrated keys come back as strings. When entry *order* matters — an event log keyed by sequence number — sort numerically on read rather than trusting key type or iteration order.

## Avatar types

An **avatar** is the identity a connection presents to a realm — the thing rules judge and views are sliced for. It is deliberately *not* called a "client": the network client (the app that dials in) and the avatar are different ideas — one connecting process can present different avatars to different realms, and a server-side Worker can hold an avatar too (that's what a [replica](/nice-realm/connecting/#replicas) is).

`avatars` names the kinds your realm admits — `player`, `spectator`, `vendor`, an internal `replica` — and rules are written against those types. Every connection resolves to an **avatar ref**:

```ts
{ type: "vendor", persistentId: "v_42", instanceId: "tab_1" }
```

- `type` — which avatar kind, from your `avatars` block.
- `persistentId` — the stable identity ("who"). On a secure connection this defaults from the **authenticated** handshake coordinate.
- `instanceId` — one of possibly several live connections for that identity (tabs, devices).

Rules receive this ref (`{ avatar, params }`), which is how "owner-only" patterns work: compare `avatar.persistentId` against the `$param` bound by the path.

## The schema hash

`defineRealm` computes a canonical hash of the state shape. It's used in two places:

- **Attach**: a client whose definition hash differs from the server's is refused at hello — the two sides are running different shapes, and letting them talk would corrupt the projection silently.
- **Persistence**: the Durable Object host stores the hash with each snapshot. A server booting on a changed schema **refuses to start** unless you provide a `migrate` hook ([Serving a Realm](/nice-realm/serving/#schema-evolution)) — persisted state is never silently reinterpreted.

The practical consequence: ship client and server together when the state shape changes, exactly as you already do for action schemas.

## Requiring a security level

A realm inherits its connection's security, and can declare the **minimum** it will accept — `security: "authenticated"` (the default) or `"encrypted"`:

```ts
export const marketRealm = defineRealm({
  id: "market_realm",
  security: "encrypted",   // refuse anything below encrypted, on both ends
  // …
});
```

There is deliberately no `"none"` — a realm always requires at least an identity-bound connection. The floor is a policy declaration (enforced fail-closed: the server refuses to hydrate, the client refuses to send) and is **not** part of the schema hash, so changing it never forces a migration. See [Security](/nice-realm/security/) for the whole model — effective minimums, per-connection/per-host overrides, and the at-rest and wire-visibility caveats.

---

# Devtools & Traffic

Source: /nice-realm/devtools
Description: Observing a realm: the browser realm panel, what its decoded traffic means versus the true wire cost, and the egress-message count that maps to your Durable Object bill.

A realm exposes two things worth watching in dev — its **projected state + sync health**, and its
**traffic** (the number that becomes your Durable Object bill). This page is the realm-specific wiring
for both. The window that renders them, the server host, the topology band, and the relay are the same
across every plane and live in the [Devtools section](/devtools/window/) — this page links there rather
than repeating it.

## The realm panel

`createNiceDevtools()` builds the shared devtools cores and streams them; instrument each `connectRealm`
with the tap it hands back. The panel that renders it lives in the [devtools window](/devtools/window/),
never in your page.

```ts title="src/devtools.ts"
import { createNiceDevtools } from "@nice-code/devtools";

export const devtools = createNiceDevtools({ topologyId: "my-app", runtime });
```

```ts title="gameClient.ts"
const realm = connectRealm(gameRealm, {
  avatar: { type: "player" },
  connection: realmConnection(connector),
  devtools: devtools.realm("game"), // ← the observation seam (one null-check when omitted)
});
```

The panel shows one tab per instrumented realm (status dot, confirmed version, pending-write badge)
with three views:

- **View** — the live projected store, plus status / version / pending / avatar identity.
- **Timeline** — every mutation with its outcome (`created → confirmed / rejected`, with reject ids and
  rolled-back paths), every sync-health diagnostic (`resync`, `probe_escalated`, `link_redialed`,
  `reown_missing`, …), and status flips.
- **Traffic** — decoded realm frames per kind (`hydrate`, `patches`, `write`, `ack`, `batch`, …),
  counts + bytes over rolling windows.

Construct the underlying `RealmDevtoolsCore` (`@nice-code/realm/devtools/browser`) yourself only if you
aren't using `createNiceDevtools`. `subscribeDiagnostics(listener)` on the handle is the post-hoc,
multi-listener complement of the `onDiagnostic` connect option — handy for tests and ad-hoc telemetry
(and one subscriber satisfies the unwired-diagnostics console floor).

## Decoded payload vs. true wire cost

The realm panel's Traffic tab shows *decoded realm payloads*. The **true wire cost** — encrypted
frames, envelopes, handshakes, keepalives — is measured one layer down, at the carrier, with `wireTap`:

```ts title="client.ts"
const connector = connectChannel(runtime, channel, {
  // …transports, storage…
  wireTap: devtools.wireTap, // ← every carrier frame, true post-encryption byte sizes
});
```

`devtools.wireTap` is one traffic core for the whole app, already streamed to the window (its per-lane,
per-client breakdown, sparklines, and largest-frame list are documented on
[Devtools & Traffic in the window](/devtools/window/)). The realm-specific reading:

- **`egressMessages` is your billing unit.** Each outgoing WebSocket *message* is a Cloudflare
  request-count unit; the byte totals are your bandwidth.
- **The `realm` lane vs. the panel's decoded totals** is the transport overhead (encryption + framing +
  batch envelope) per payload byte.
- **`egressCoalesceRatio` (`coalesce ×N`)** is "how many realm frames rode each billable message" — the
  number to watch when tuning `broadcastCoalesceMs` and confirming the batch envelope is working.

## Reading the engine directly

With no devtools wired at all, the realm engine exposes its own counters — scrape them from a dev-gated
route:

```ts title="MatchDO.ts"
if (url.pathname === "/debug/traffic" && env.STAGE !== "production") {
  return Response.json(this.engine.getTrafficSnapshot());
  // { ingressFrames, ingressBytes, egressMessages ← billing unit, egressFrames ← pre-coalescing,
  //   egressBytes, egressCoalesceRatio ← the batch-envelope win, connections: [...] }
}
```

To contribute that same data to a **server devtools host** (console summaries or a live window feed),
the realm scopes are `realmEngineScope(engine, "demo_board")` (traffic totals) and
`serverWireTrafficScope(engine)` (per-frame samples). The host itself — its options, sinks, and how it
streams to a window alongside your action domains — is documented in
[Observing Backends](/devtools/backends/):

```ts title="server.ts"
import { createServerDevtoolsHost } from "@nice-code/devtools-core";
import { realmEngineScope, serverWireTrafficScope } from "@nice-code/realm/devtools/server";

createServerDevtoolsHost({ name: "match-api" })
  .contribute(realmEngineScope(engine, "demo_board"))
  .contributeSample(serverWireTrafficScope(engine))
  .start();
```

## Inside a Durable Object

A DO can't dial *out* to a devtools window (an open outbound socket pins it awake) and can't run the
console sink's timer across hibernation — so the **window dials in** instead, riding the DO's ordinary
WebSocket as a token-gated protocol via `createNiceDurableObjectDevtools`. The full setup, safety model,
and the honest hibernation caveat are in [Observing Backends → a Cloudflare Durable Object](/devtools/backends/#a-cloudflare-durable-object).

---

# Limits & Production

Source: /nice-realm/limits
Description: What the realm engine bounds for you per connection, the one limit your app must bound itself (state cardinality), and how to keep a realm cheap and safe under load.

A realm host is a shared resource — one Durable Object, many clients, some of them buggy or hostile.
So the engine **bounds every connection for you**, and hands you the one lever it can't guess: the
total size of your state tree. This page is both of those, in one place.

## What the engine bounds for you

Every realm host enforces per-connection ingress limits. A breach rejects the offending write
(surfaced as `limits_exceeded`) and counts against the connection; **`maxBreachesBeforeDetach`
breaches force a detach** — a hostile or buggy client cannot hold the host hostage. The client-side
coalescer reads `maxPatchesPerFrame` / `maxFrameBytes` / `writeRatePerSecond` off the hydrate and
**splits over-limit flushes automatically**, so a well-behaved app rarely sees a breach at all.

| Limit | Default | Bounds |
| --- | --- | --- |
| `maxPatchesPerFrame` | `64` | Patch ops in one write frame. |
| `maxFrameBytes` | `64 KB` | Encoded bytes of one inbound realm frame. |
| `maxRecordKeyLength` | `128` | Dynamic record-key length (also protects the intern dictionary). |
| `maxExpandedLeaves` | `256` | Leaves one subtree write may expand to. |
| `writeRatePerSecond` | `100` | Sustained write/intent rate per connection (token bucket). |
| `writeRateBurst` | `200` | Bucket depth — the burst a connection may spend at once. |
| `maxBreachesBeforeDetach` | `10` | Limit breaches on one connection before it is forcibly detached. |

Override any of them in the [serve engine options](/nice-realm/serving/); the effective values ride
the hydrate, so the client splits against the same numbers you set. A bare `limits_exceeded` that
reaches your `onMutationRejected` (rather than being split away) means a genuinely oversized write —
back off, don't hammer.

## What your app must bound: state cardinality

The engine bounds each *frame* and each *write*, but not the **total size of a realm's state** — that
is application-shaped, so it stays your call. A realm whose state is a record that grows one entry per
client (a presence roster, a chat log, a leaderboard) grows without limit unless you cap it. Cap it
**with a rule** — the same place you already authorize writes:

```ts
// doc-check: skip — illustrative rule shape; see nice-realm/rules
rules: (r) => [
  r.on("roster.*").alter((ctx) =>
    Object.keys(ctx.state.roster).length < 500 || err_game.fromId("roster_full"),
  ),
]
```

A `maxStateBytes` engine knob may arrive later; until then the cardinality rule **is** the recipe, and
it's strictly more expressive — you cap by the dimension that actually matters (entries per record),
not by an opaque byte ceiling. For anything attacker-influenced (a key space a client can grow), a cap
like this is not optional.

## Keep it cheap: transient and ephemeral

Two hosting choices keep a realm small and inexpensive to run — both covered in full on
[Serving a Realm](/nice-realm/serving/), flagged here because they're the load-and-cost levers:

- **Transient regions** (`transient: ["presence", ...]`) — a branch that never persists and reloads
  empty on a hibernation wake. Presence, cursors, "who's typing" — anything you'd re-assert on attach
  rather than store. See [Presence Realms](/nice-realm/presence/).
- **Ephemeral hosting** (`persistence: "ephemeral"`) — the whole realm lives only in memory and
  cold-starts from genesis; nothing is written to disk. Pair it with
  [`assertOnAttach`](/nice-realm/connecting/#assertonattach--state-you-must-own-while-attached) so
  each client re-owns its entries on a wake.

## Where this sits in production

Bounding state is one line of your [pre-flight checklist](/production/posture/). The rest — the trust
model, payload exposure, devtools in production — is stack-level and lives there and on
[Identity & Trust](/nice-wire/identity/). Next in the realm arc: [Presence Realms](/nice-realm/presence/).

---

# Mental Model

Source: /nice-realm/mental-model
Description: Realms are the state plane — one server-owned state tree that many clients watch and optimistically write, over your app's secure connection.

`@nice-code/realm` is a schema-defined, **authoritative shared-state engine**: many clients continuously observe (and optimistically write) one server-owned state tree, over a binary patch protocol riding your app's secure connection. If the app also uses `@nice-code/action`, both share that one connection; a realm works just as well [with no actions at all](/nice-realm/connecting/#realm-only-apps--createwireclient).

## In one sentence

> **Realm is the state plane; actions are the action plane** — realm for state that many parties watch, actions for things that happen.

One-shot commands with results, reliability tiers, offline outboxes, progress streaming — those stay [actions](/nice-action/mental-model/). Live positions, presence, inventory, lobby state, a shared cursor — that's a realm.

| You want… | Use |
|---|---|
| "What is the state of the world right now, kept live?" | **realm** |
| "Do this thing and tell me the result." | **action** |

## The loop

The server owns the state. Clients hold a **projection** of it — the confirmed authoritative state with their own unconfirmed (optimistic) writes layered on top:

```text
  CLIENT                                             SERVER
  ┌───────────────────────────┐                      ┌──────────────────────────┐
  │ projected view            │   write frame        │ authoritative state      │
  │ = confirmed + optimistic  │ ───────────────────► │ rules checked, applied   │
  │   overlay                 │                      │ in arrival order         │
  │                           │   patches + ack      │                          │
  │ rebase: drop the          │ ◄─────────────────── │ broadcast, sliced per    │
  │ confirmed part of the     │                      │ client's view rules      │
  │ overlay, keep the rest    │                      │                          │
  └───────────────────────────┘                      └──────────────────────────┘
```

- A `realm.update()` applies **instantly** to the local projection and is sent to the server.
- The server validates it against the realm's **rules**, applies it, and broadcasts the resulting patches — **sliced per avatar**, so state an avatar isn't allowed to view never leaves the server.
- When the client's own write comes back confirmed (or rejected), the optimistic overlay is rebased: confirmed parts drop out, rejected parts roll back, everything else stays.

Every write returns a **settle handle** — a lazy thenable that's safe to ignore (fire-and-forget cursor moves produce zero unhandled rejections), with a read-your-writes guarantee: after `await handle`, the store already reflects the authoritative outcome.

## One definition, both sides

Everything derives from a single `defineRealm` block that both the client and the server import — the state schema, the avatar types, the rules, the intents. An **avatar** is the identity a connection presents to the realm — "who you are in this world" — and it's what the rules judge: `avatars` names the kinds a realm admits (`player`, `spectator`, …), and every rule sees the acting avatar's ref. From this one declaration the library derives the TypeScript types, the compact wire token map, a **schema hash** (so a server never silently reinterprets persisted state written under a different shape), and the client-side prediction bundle.

```ts title="shared/gameRealm.ts"
import { defineRealm, t } from "@nice-code/realm";

export const gameRealm = defineRealm({
  id: "game_realm",
  avatars: {
    player:    { persistentId: t.string() },
    spectator: { persistentId: t.string() },
  },
  state: {
    config: t.object({ roundActive: t.boolean() }),
    players: t.record(t.id("playerId"), t.object({ x: t.number(), y: t.number() })),
  },
  rules: (r) => [
    r.path("config.*").view(r.everyone).alter(r.serverOnly),
    r.path("players.$playerId.{x,y}")
      .view(r.everyone)
      .alter(({ avatar, params }) => avatar.persistentId === params.playerId || myErr.fromId("not_yours")),
  ],
});
```

Because the same rules run on the client (prediction) and the server (authority), a write you aren't allowed to make **rejects locally, instantly** — it never even reaches the wire. Only checks that need server-side facts (`r.serverChecked`) can differ, and that's exactly the slice of optimism that can roll back.

## One connection, two planes

A realm attaches to your app's secure **connection** — it registers as a **frame protocol** on the wire connection, and if you also use actions they share it: one socket, one handshake, one authenticated identity, two planes. Actions are optional; a realm-only app opens the same connection with [`createWireClient`](/nice-realm/connecting/#realm-only-apps--createwireclient) — `@nice-code/wire` and `@nice-code/realm`, nothing else.

- On the server: pass the realm host's `protocol` to [`serveWireDurableObject`](/nice-realm/serving/) (realm-only), or to [`serveDurableObject`](/nice-action/cloudflare/) when the DO also serves actions.
- On the client: `connectRealm(realm, { connection: realmConnection(client) })` where `client` is the connection returned by `createWireClient` (or `connectChannel`, with actions).

The avatar identity defaults from the **authenticated coordinate** of that connection — the identity the secure handshake established — so realm rules like "only you may move your own player" are enforced against a cryptographically-bound identity, not a self-declared one.

## The two write shapes

This distinction matters enough that [it has its own page](/nice-realm/writes-intents/), but in short:

- **Direct writes** (`realm.update`) are last-writer-wins with **absolute-set semantics**: "cursor is at 412". High-frequency, coalesced, optimistic.
- **Intents** are named, atomic, server-side mutations: "purchase item X". Read-modify-write, counters, multi-path invariants — anything where composing the new value locally would race.

## The pages that follow

- [Defining a Realm](/nice-realm/defining-realms/) — the schema builder, avatar types, and server context.
- [Rules & Visibility](/nice-realm/rules/) — who can see what, who can write what.
- [Writes & Intents](/nice-realm/writes-intents/) — the write contract (read this one).
- [Serving a Realm](/nice-realm/serving/) — the engine, the Cloudflare Durable Object host, persistence.
- [Connecting & React](/nice-realm/connecting/) — the client handle, liveness, the patch feed, hooks.
- [Testing Realms](/nice-realm/testing/) — the deterministic in-memory world.

---

# Presence Realms

Source: /nice-realm/presence
Description: The textbook first realm — a lobby/roster of \"who is here, and what are they doing\", built from assertOnAttach, last-detach pruning, and ephemeral hosting.

Presence — a lobby roster, cursors on a canvas, "who is watching" — is the textbook first realm: pure shared state, everyone sees everyone, each avatar owns exactly its own entry. It is also where hand-rolled sync stacks grow the most belts (reconcile polls, re-assert-on-reconnect, last-socket scans, stale-entry sweeps). A presence realm needs **none of them** — this page is the whole pattern, end to end.

## The definition

One record, keyed by the avatar's persistent id; the owner writes their entry, the server owns membership:

```ts title="shared/lobbyRealm.ts"
import { defineRealm, t } from "@nice-code/realm";

export const lobbyRealm = defineRealm({
  id: "lobby_realm",
  avatars: { player: { persistentId: t.string() } },
  state: {
    players: t.record(
      t.id("playerId"),
      t.object({
        name: t.string(),
        position: t.object({ x: t.number(), y: t.number() }),
        facing: t.union(t.literal(1), t.literal(-1)),
        activityId: t.optional(t.string()),   // "watch me" pointers, status, …
      }),
    ),
  },
  rules: (r) => [
    // Everyone sees the roster; only the owner writes their own entry.
    r.path("players.$playerId.**")
      .view(r.everyone)
      .alter(({ avatar, params }) =>
        avatar.persistentId === params.playerId || err_lobby.fromId("not_your_entry"),
      ),
  ],
});
```

## The client — `assertOnAttach` is the join

There is no "join" action. Your entry is state you must own *whenever you are attached*, and that is exactly what [`assertOnAttach`](/nice-realm/connecting/#assertonattach--state-you-must-own-while-attached) declares:

```ts title="client.ts"
const realm = connectRealm(lobbyRealm, {
  avatar: { type: "player" },                // persistentId from the authenticated coordinate
  connection: realmConnection(connector),
  assertOnAttach: (draft) => { draft.players[me] = initialEntry(); },
});

// Everything else is plain optimistic writes — coalesced, deduped, rate-shaped:
realm.update((d) => { Object.assign(d.players[me].position, target); });
realm.update((d) => { d.players[me].activityId = runId; });
```

The hook re-runs on every **full hydrate** — first attach, an out-of-log-window resume, an epoch change after a server wipe — which is precisely the set of moments your entry could have been lost. It does *not* re-run on an ordinary patch-replay reconnect (your entry is still confirmed there), and within `pendingExpiryMs` any in-flight writes [resend on their own](/nice-realm/connecting/#reconnects--durability). The re-assert belts a hand-rolled lobby carries — "re-join after reconnect", "re-announce my status after the socket blips", "recover after a server restart" — are this one option.

For pointer-frequency fields (cursor, walk target), set `coalesceMs` on the connect options instead of hand-throttling — see [coalescing](/nice-realm/writes-intents/#coalescing--dont-hand-roll-a-throttle).

### Write cadence is a network cadence, not a render cadence

The instinct for a cursor is to write inside `requestAnimationFrame`. That bounds writes to the **display refresh rate** — which is a rendering budget (60 Hz, or 120–144 Hz on a high-refresh monitor), not a networking one. Every write you emit is one authoritative commit fanned out to *every* other attached avatar, and on a Durable Object every one of those is a billed inbound message. A room of `N` cursors all writing at 144 Hz is `N × 144` messages/second arriving at each participant — the cost scales with the crowd, so pick the cadence deliberately:

```ts
const realm = connectRealm(lobbyRealm, {
  // …
  coalesceMs: 40,   // ~25 cursor frames/sec is smooth; the newest value per path wins the window
});
```

Set `coalesceMs` to your real network cadence (30–50 ms is imperceptible for cursors) and let the coalescer collapse the rAF stream into it — deduped per path, so only the latest position in each window travels. Smooth the *remote* dots with a short CSS transition rather than by writing faster: sparse network updates plus interpolation look better than a flood, and cost a fraction of the messages. (The server side of this fan-out — batching and tick-rate broadcast — is the library's job, tracked in the realm message-overload plan; `coalesceMs` is the half you own.)

## The server — pruning is one line

`onAvatarDetach` fires **once per avatar identity when its last connection drops** — multi-tab and multi-device are counted by the engine, so the prune handler is genuinely this:

```ts title="LobbyDO.ts"
const realms = serveRealmDurableObject(this.ctx, {
  realms: {
    lobby_realm: hostRealm(lobbyRealm, {
      avatarType: "player",
      persistence: "ephemeral",   // presence has no history worth persisting
      engine: {
        ctx: {},
        initialState: { players: {} },
        onAvatarDetach: (avatar) => {
          realms.engines.lobby_realm.update((d) => { delete d.players[avatar.persistentId]; });
        },
      },
    }),
  },
});
```

No socket scanning, no "is this their last tab" bookkeeping, no departure races. Hibernation is covered too: avatars whose sockets vanished while the DO slept get a **synthesized detach** on wake, so the roster never keeps ghosts.

### `avatarDetachGraceMs` — don't flap on a blip

With the connection's [auto-redial](/nice-realm/connecting/#who-re-dials-the-link--nothing-here-needs-app-code-either), a transient drop heals in ~1–2 s — but a bare `onAvatarDetach` still fires the instant the socket closes, and `onAvatarAttach` a second later. Every presence consumer ends up hand-rolling a departure debounce (and inheriting a real footgun: a raw `setTimeout` in a Durable Object is **not hibernation-safe**). Declare the debounce instead:

```ts
engine: {
  // Fire onAvatarDetach only if the avatar hasn't re-attached within the window.
  // A re-attach inside it swallows BOTH hooks — the avatar never left.
  avatarDetachGraceMs: 8_000,
  onAvatarDetach: (avatar, reason, ctx, detail) => {
    // detail.via: "grace-expired" (window elapsed, detail.deferredMs tells how late)
    //          or "immediate"     (no grace / a revocation via detachAvatar)
    realms.engines.lobby_realm.update((d) => { delete d.players[avatar.persistentId]; });
  },
},
```

On the DO host the deferred detach is backed by the **alarm mux + persisted pending rows**, so it fires even if the DO hibernates mid-window — the guarantee a consumer `setTimeout` cannot give. Wake losses run the same funnel: a player whose socket died while the DO slept gets the grace too, so their prompt redial swallows the detach instead of flapping the roster. `detachAvatar()` (revocation) always bypasses the grace — kicking someone is not a blip.

### Why `persistence: "ephemeral"` is right here

Presence is attach/detach churn — persisting its patch log buys nothing. [Ephemeral hosting](/nice-realm/serving/#ephemeral-realms-presence) skips SQLite entirely: every cold start boots the empty roster on a fresh epoch, surviving clients full-rehydrate, and `assertOnAttach` re-fills the roster within a round-trip. The two features are a pair: **ephemeral hosting is only safe because the assert hook exists** (and the docs will keep saying so). Schema changes stop mattering as well — presence never needs a `migrate`; if you keep the realm durable for other reasons, `migrate: "wipe"` declares the same disposability.

## Mixed realms: mark presence `transient` instead

`persistence: "ephemeral"` is all-or-nothing — it makes the *whole realm* disposable. The common case is **mixed**: a board that keeps notes and a click counter (durable) but also carries live cursors (throwaway). Hosting that whole realm as ephemeral would lose the notes; hosting it as durable makes every 60 Hz cursor write pay the full persistence cost — a SQLite log row per commit and a slice of every snapshot — for state worthless a second later.

Declare the hot region **`transient`** on the definition instead:

```ts title="shared/boardRealm.ts"
export const boardRealm = defineRealm({
  id: "board",
  state: {
    notes: t.record(/* … durable … */),
    board: t.object({ totalClicks: t.number() }),
    presence: t.record(t.id("visitorId"), t.object({ x: t.number(), y: t.number() })),
  },
  transient: ["presence"],   // cursor writes: broadcast, but never logged / snapshotted / CAS-tracked
  rules: (r) => [ /* … */ ],
});
```

A transient write still broadcasts (peers see the cursor) and still obeys its `view`/`alter` rules — it just isn't persisted: no log row, no snapshot bytes, no `touchedSince` history. On a cold start (or an out-of-window resume) the region comes back **empty** and each client re-owns its entry via `assertOnAttach`; a resuming client's [staleness probe](/nice-realm/connecting/#the-staleness-probe) refreshes it for free. v1 `transient` paths are concrete, wildcard-free subtree roots (`["presence"]`), validated at `defineRealm` time.

### Which durability tier does my state belong in?

| Tier | Declare it with | Persisted? | Rolled back on link loss? | Use for |
|---|---|---|---|---|
| **Durable** (default) | nothing | yes (log + snapshots) | no | Notes, scores, anything with history |
| **Transient region** | `transient: ["presence"]` | **no** | no | Cursors, "who's looking", live position — hot, throwaway, on a realm that *also* has durable state |
| **Ephemeral realm** | `persistence: "ephemeral"` | no (whole realm) | no | A pure-presence realm with *nothing* worth persisting |
| **Durable client write** | `realm.update(fn, { durability: "reassert" })` | (client-side) | **no — resent until confirmed** | A client that is the sole *producer* of a region (an input log) — see [durable writes](/nice-realm/writes-intents/#durable-writes-durability-reassert) |

### Transient regions survive a wake

Transient and `assertOnAttach` are a pair, exactly like ephemeral hosting: the region is disposable *because* every client re-asserts its own entry on resume. This matters most on a **durable** realm: transient regions are stripped from every snapshot, so a same-epoch DO hibernation wake reloads them **empty** while your socket stays attached — and a resume answers by patch replay, not a full hydrate. The library therefore re-runs `assertOnAttach` after *every* resume for a transient-bearing realm (reconnect and live probe/rehello alike, including the idle staleness probe), not only on a full hydrate — so your entry is re-created across wakes, and your cursor's leaf writes never land on a vanished parent (which would reject `write_target_missing`).

**Ordering guarantee:** on a resume, the re-own reaches the server **before** any resent write or intent. So an intent whose server logic reads your transient entry — a `fire` that reads your `aim` — runs against the re-owned entry, never the momentarily-empty region. You don't sequence this; the library rides the recovery hello with the re-own on an internal lane. (If it didn't, a resent `fire` that outran the re-own would reject "you haven't joined" for a perfectly legitimate action.)

Do **not** use CAS (`touchedSince`) under a transient region — it keeps no touch history, so the check would silently always pass (the engine throws if you try). `durability: "reassert"` is the opposite pairing and perfectly fine: a producer re-asserting its own transient region across reconnects is the intended shape.

## What presence deliberately does not need

| Belt from the hand-rolled version | Replaced by |
|---|---|
| Roster reconcile poll ("a dropped push can't leave the list wrong forever") | Hydrate + versioned patches + the [staleness probe](/nice-realm/connecting/#the-staleness-probe) — convergence is the library's contract |
| Re-assert status after every reconnect | `assertOnAttach` + automatic pending-write resend |
| Authoritative lookup at read time ("don't trust the cached broadcast") | Reading confirmed state *is* the authoritative lookup, staleness-bounded |
| Last-socket scan before announcing a departure | `onAvatarDetach` last-drop semantics |
| Departure debounce timers ("don't flap the roster on a blip") | [`avatarDetachGraceMs`](#avatardetachgracems--dont-flap-on-a-blip) — hibernation-safe, both hooks swallowed on a prompt return |
| Local store patch-ups when a related feature misses an event | The roster converges on its own; delete the belt |
| `migrate` hooks / durable writes / intents | Presence is default-tier owner-writes over disposable state — none of them apply |

When an entry needs *more* than owner-writes — a matchmaking claim, a seat count — that specific mutation becomes an [intent](/nice-realm/writes-intents/#intents-named-atomic-server-side); the rest of the roster stays exactly as above.

---

# A Resilient Browser Client

Source: /nice-realm/resilient-client
Description: The canonical wiring for a client that survives flaky links — keep-alive, half-open detection, truthful reconnect UX, unknown-outcome intents, teardown order, and chaos-testing your own app.

Every piece of link resilience is individually documented; this page is the **assembly** — the wiring a production browser client (a game, a live board, anything realtime) should ship, and what each part is for. It exists because consumers otherwise re-derive it from library source, one incident at a time.

## The canonical wiring

```ts title="client.ts"
import { connectChannel, wsCarrier } from "@nice-code/action";
import { connectRealm, realmConnection, isUnknownOutcomeRejection } from "@nice-code/realm";

let session: { matchId: string } | undefined; // your mutable dial context

const connector = connectChannel(runtime, matchChannel, {
  peer,
  storage,
  transports: [
    {
      // Return null when there's no valid endpoint (torn-down session): the redial
      // loop PARKS instead of dialing garbage — teardown order stops mattering.
      carrier: wsCarrier(() =>
        session == null ? null : { url: `${WS_BASE}?matchId=${session.matchId}` },
      ),
    },
  ],

  // Auto-redial on unexpected drops (backoff + jitter). Default: already on for a
  // realm-carrying link — shown here for the guide.
  keepLinkAlive: true,

  // Half-open detection (browser offline, NAT death: the socket LOOKS open, frames
  // vanish). Idle ⇒ wire ping; no reply ⇒ local close ⇒ the ordinary redial. Also on
  // by default with keepLinkAlive; the knobs are the point (≈ idleMs + pongTimeoutMs
  // worst-case detection, default 15s + 5s).
  linkKeepalive: { idleMs: 15_000, pongTimeoutMs: 5_000 },

  // The observation surface: truthful reconnect UX + flaky-link telemetry.
  onLinkEvent: (e) => {
    if (e.type === "link_down") hud.linkDown();
    if (e.type === "redial_scheduled") hud.retrying(e.attempt, e.delayMs);
    if (e.type === "link_up") hud.linkUp(e.downForMs); // undefined on the first connect
  },
});

const realm = connectRealm(matchRealm, {
  avatar: { type: "player" },
  connection: realmConnection(connector),
  onMutationRejected: (rejection) => toast.rejected(rejection),
  onDiagnostic: (e) => telemetry.count(`realm_${e.type}`), // see "who sees what" below
});
```

## The first connect — when the server isn't up yet

The classic dev-loop race: you restart both processes, the frontend reloads in 200 ms, the backend takes two seconds, and the app's very first dial hits a closed port. This is **not** a special case. A failed dial arms the same keep-alive backoff ladder that a mid-session drop does — *including the first one, before any link has ever come up* — so the app heals on its own with no reload:

```
redial_scheduled (attempt 1, in 758 ms)
redial_scheduled (attempt 2, in 1613 ms)
link_up                                    ← the backend finished booting
```

What the library does for you, and what it leaves to you:

- **It retries indefinitely.** Each rung doubles — 1 s, 2 s, 4 s … capped at 30 s — and the actual wait is jittered into the top half of its rung, so a whole fleet doesn't reconnect in lockstep. A server can always come back, so nothing gives up on its own: see [deciding to stop](#deciding-to-stop-trying).
- **`connect()` still rejects** on that first failure. The rejection is the truthful answer to *"am I connected right now?"*; the retries continue behind it. If you `await connector.connect()` at startup, catch it and render "connecting…" rather than treating it as fatal.
- **A pre-open dial failure is silent on the console.** It is a failed *dial*, not an outage, and logging it would spam a line per backoff rung while a peer boots. Observe it through `onLinkEvent`, never `console.error`. (A failure *after* the socket opened still warns.)
- **`createRequest` returning `null` parks instead.** No endpoint means there is nothing to dial, so the ladder waits for a real one rather than churning — the teardown-order guarantee from the wiring above.
- **A permanently-rejected identity parks too.** If the server rejects the handshake because this client's verify key doesn't match the one pinned for its identity (trust-on-first-use), retrying can never succeed — so the ladder parks instead of re-running a doomed handshake forever. The rejection is **typed**: `connect()` rejects with `identity_pin_mismatch` (branch on it with `err_wire_connect.isExact(e) && e.hasId("identity_pin_mismatch")`; see [recovering from a pin mismatch](/nice-wire/identity/#recovering-from-a-pin-mismatch) for what causes it and how to recover).
- **`keepLinkAlive: false`** opts out of all of this: the link is dialed on dispatch only.

## Joining vs reconnecting — one latched boolean

`status === "connecting"` covers two very different UX moments. `hasBeenLive` (latched on the first `live`, never reset for the handle's lifetime) tells them apart:

```ts
realm.subscribeStatus((status, { hasBeenLive }) => {
  if (status === "live") hud.live();
  else if (status === "connecting" && hasBeenLive) hud.reconnecting(); // warning banner
  else if (status === "connecting") hud.joining();                     // first-join spinner
  else hud.left();
});
```

A "retry now" button belongs on the reconnect banner — bind it to the connector, which resolves when the fresh link's handshake lands:

```ts
retryButton.onclick = () => void connector.reconnectLink();
```

### Status flips only on evidence of an outage

A serverless host (a Cloudflare Durable Object) **hibernates on every gameplay lull** and wakes on the next frame. The wake heals in one round-trip on a socket that never dropped — so it must be **invisible**. It is: the wake re-hello is *probe-flavored* and keeps `status === "live"` throughout, exactly like the idle staleness probe. `status` moves to `"connecting"` only on **evidence** — a link the transport reported down, or a probe/re-hello that goes **unanswered** past `probeReplyTimeoutMs` (then `probe_escalated` fires and the connection re-dials). It never flips for a protocol chore. So folding `status` into a "reconnecting…" banner does **not** flap it on every wake — a real outage is the only thing that lights it.

What a wake looks like on the wire now: `hello → (re-own) → answer → your rebased writes`. Your in-flight writes **park** for that one round-trip instead of streaming at a momentarily-empty server (no reject burst), and any transient region you own is re-created *before* your resent intents run — see [presence](/nice-realm/presence/#transient-regions-survive-a-wake).

## Deciding to stop trying

The library never gives up on an outage, because it cannot know whether your server is rebooting or decommissioned. (The two *non*-outages above — no endpoint to dial, a pin-rejected identity — park by themselves; retrying can't fix those.) A **bounded** policy — "after N attempts, tell the user we're offline and stop burning battery" — is the app's to own, and `redial_scheduled` carries the counter to build it from:

```ts
const connector = connectChannel(runtime, matchChannel, {
  // …transports, storage…
  onLinkEvent: (e) => {
    if (e.type === "link_up") hud.online();
    if (e.type === "redial_scheduled") {
      hud.retrying(e.attempt, e.delayMs); // "reconnecting… (attempt 3, in 4.1 s)"
      if (e.attempt >= 8) {
        connector.releaseLink(); // stop for good — no phantom `link_down`
        hud.offline();           // the button below revives it
      }
    }
  },
});

reconnectButton.onclick = () => void connector.connect();
```

| Lever | Effect |
|---|---|
| `connector.reconnectLink()` | **Retry now** — tears down and re-dials immediately, skipping the remaining backoff wait. Awaitable; rejects if that dial fails (the ladder carries on). |
| `connector.releaseLink()` | **Stop trying.** Suppresses the redial and releases the socket. An app-initiated release is not an outage, so it emits no `link_down`. Not terminal — a later `connect()` revives the connector. |
| `keepLinkAlive: false` | Never auto-redial at all; dial on dispatch only. |
| `connector.dispose()` | Permanent teardown of the connector. |

Bound the *attempts*, not the elapsed time: with the 30 s cap, eight attempts is roughly a minute and a half of patient retrying — long enough to ride out a deploy, short enough that a laptop that closed its lid doesn't retry until the battery dies.

## Who sees what: `onLinkEvent` vs `onDiagnostic`

A drop that heals by redial is **silent at the sync layer** — no sync was lost, so `onDiagnostic` correctly reports nothing. The division of labor:

| Event | Where | Meaning |
|---|---|---|
| `link_down` / `redial_scheduled` / `link_up` | connector `onLinkEvent` | Transport churn — reconnect UX, "how flaky are my users" telemetry |
| `link_redialed` (with `downForMs`) | realm `onDiagnostic` | The ONE transport event forwarded to realm telemetry — count churn without a second wiring point |
| `resync`, `gap_dropped`, `frame_error`, `probe_escalated`, `late_reject`, `reown_missing` | realm `onDiagnostic` | Sync-layer health — a healthy realm emits **none**, whatever the transport does |

A `resync` with `reason: "write_target_missing"` is the self-heal for a *structural divergence*: the server rejected a write whose target it no longer had (a delete/reset broadcast that never reached this client). The client re-reads and re-owns in one round-trip instead of looping on doomed writes — so a single such `resync` is recovery working, not a problem; a *stream* of them means a broadcast is being lost upstream. A `late_reject` (a reject for a frame already settled) is harmless but is the fingerprint of a divergence window worth logging.

A `reown_missing { path }` is the tripwire behind that self-heal: it fires only when a recovery ran but did **not** re-create a transient entry you own — your `assertOnAttach` produced no write for `path` (there is none, or the parent is genuinely gone). The library escalates once automatically (a forced full-hydrate, the in-place equivalent of a page reload); a *second* `reown_missing` for the same `path` means even that did not bring it back, so treat the entry as permanently gone (a pruned record, a removed peer) and reflect that in your UI rather than retrying. If you silence `write_target_missing` in `onMutationRejected` (recommended — it is benign wake noise once recovery is wired), `reown_missing` is your one trustworthy "this one did not heal" signal, so wire it.

## Owning transient state across a wake: `assertOnAttach`

A **transient region** (`transient: ["aim"]`) is never logged or snapshotted, so a same-epoch Durable Object hibernation wake reloads it **empty**. Anything you own there — a cursor row, an aim reticle, "my side of the record" — must be re-declared on recovery. `assertOnAttach` is that hook: the library runs it after every hydrate **and** every replay resume on a transient-bearing realm (reconnect, wake rehello, and the periodic staleness probe all heal), and rides the re-own to the server *ahead of* any resent write or intent — so a `fire` that reads your `aim` runs against the re-owned entry, never the wiped region.

Write it as a **guard** — re-own only if the entry is actually gone:

```ts
connectRealm(matchRealm, {
  avatar: { type: "player" },
  connection: realmConnection(handler),
  // Re-own my aim entry on recovery, preserving my real values from my own store.
  assertOnAttach: (draft) => {
    const me = identity.id;
    if (draft.players[me] == null || draft.aim[me] != null) return; // already present — nothing to do
    draft.aim[me] = { angle: myStore.angle, power: myStore.power, item: myStore.item };
  },
  onDiagnostic: (e) => { if (e.type === "reown_missing") forceHardReload(); }, // belt-and-suspenders
});
```

The draft the library hands you on a resume reflects the **authoritative post-recovery state** (the region refresh has already landed), so the guard observes a wake-wiped entry as genuinely missing and re-creates it, and a healthy resume observes it present and enqueues nothing — cheaper than an unconditional rewrite and equally correct. Read the values you re-own from your **own** source-of-truth store (above), not from `draft`: after a wipe the draft's authoritative value is absent, so `draft.aim[me]?.power ?? 0` would re-own at defaults.

### When each event fires

| Event | Fires | Not |
|---|---|---|
| `link_down` | At the **moment of close**, for any real outage — network, server close, `connector.debug.dropLink()`. Independent of how long the socket's own close callback takes (a real WebSocket's `onclose` can lag by seconds). | Never for an app-initiated teardown (`releaseLink()` / `clearTransportCache()` / `dispose()`) — that is not an outage. Never coupled to the redial. |
| `redial_scheduled` | When keep-alive actually arms attempt N. A `debug.dropLink({ suppressRedialMs })` window suppresses **only this** — never the `link_down` above. | When keep-alive is off, parked (`dial_unavailable`), or suppressed. |
| `link_up { downForMs }` | On re-establishment. `downForMs` measures the **full outage** (from `link_down` at close), not the redial duration. | `downForMs` is `undefined` only on the first-ever connect. |

## Non-idempotent intents: the unknown-outcome catch

A `frame_too_stale` rejection means the outcome is **unknown** — the intent may have committed while the ack was lost. Never blindly re-issue; re-read state (it converges on the next replay/hydrate) and decide:

```ts
try {
  await realm.intents.fireShot({ angle, power });
} catch (e) {
  if (isUnknownOutcomeRejection(e)) {
    // The shot may have landed — re-read state, don't re-fire.
    await refreshFromRealmState();
  } else {
    showRejection(e); // a definite "no": a rules rejection (or transport failure)
  }
}
```

## Teardown: leaving a session without a 3 a.m. bug

Two levers, and with the `null`-returning `createRequest` above the ordering between them stops mattering:

```ts
function leaveMatch() {
  realm.detach();            // leave the realm (slot released, pending writes expired)
  session = undefined;       // the dial context is gone — createRequest now returns null
  connector.releaseLink();   // stop the auto-redial and release the socket
}
```

`releaseLink()` is not terminal — the next `connect()`/dispatch revives the connector for a new session. (`clearTransportCache()` does the same suppression under a cache-flavored name; `dispose()` is the permanent teardown.)

## Detection windows, and how the knobs compose

| Detector | Knob(s) | Worst-case notice | Covers |
|---|---|---|---|
| Clean close → auto-redial | `keepLinkAlive` | ~1 s (first backoff rung) | Any real socket close |
| Wire keepalive (half-open) | `linkKeepalive: { idleMs, pongTimeoutMs }` | ≈ `idleMs + pongTimeoutMs` (default ~20 s) | Every protocol on the link |
| Realm staleness probe + escalation | `staleProbeAfterMs` + `probeReplyTimeoutMs` | ≈ 35 s at defaults | Realm-layer belt-and-braces (also catches an unhealthy-but-open session) |
| Server presence grace | [`avatarDetachGraceMs`](/nice-realm/presence/#avatardetachgracems--dont-flap-on-a-blip) | — | The *server's* side of a blip: no roster flap while the client heals |

The wire keepalive is the primary half-open detector; keep the probe knobs at their defaults as the sync-layer backstop rather than tightening them to do transport work.

**Close semantics — the heal is not coupled to the platform's close event.** A *deliberate local* close — a teardown (`clearCache`), the half-open keepalive detector, or `debug.dropLink()` — notifies the disconnect fan-out (the auto-redial trigger) immediately, so the heal runs on the fast ladder (~1 s). It does **not** wait for the carrier's own platform close event, which a real WebSocket can deliver seconds late against a dead peer. The eventual platform event is deduped confirmation, so `link_down` fires once and `link_up.downForMs` measures the full outage. Practical upshot: a bare `debug.dropLink({})` is a faithful *fast-blip* simulator (heals in ~1 s, like a real transient blip) — reach for `{ suppressRedialMs }` only when you specifically want to hold a *sustained* outage open.

## Chaos-testing your own app

Outage simulation from *outside* the library doesn't work — a browser's offline mode never closes the socket, and page-level `WebSocket` patching can't gate the keep-alive redial (it heals straight through, as it should). Use the built-in seams:

```ts
// 1. Manual QA / e2e: the airplane-mode button — a REAL close (the server sees it),
//    with the redial suppressed for the window.
await connector.debug.dropLink({ suppressRedialMs: 10_000 });

// 2. Integration tests: the library's own chaos transport.
import { chaosLink } from "@nice-code/action/testing-transport";
const link = chaosLink();
// wire link.onConnection(...) to your acceptor; pass link.carrier to connectChannel
link.chaos.hold();        // half-open: isOpen() true, frames vanish (browser-offline shape)
link.chaos.releaseHeld(); // the network comes back, in order
link.chaos.dropHeld();    // ...or lossy: the parked frames never arrive
link.chaos.closeLink();   // a real drop; chaos.dialCount counts the redials
link.chaos.refuseDials(true); // and keep the "server" unreachable

// 3. Unit-level WS control: inject the socket itself.
wsCarrier(() => ({ url }), { createWebSocket: (url) => new MyControllableSocket(url) });
```

`@nice-code/realm/testing` covers the *rules/intents* side; this transport surface is its link-layer counterpart.

---

# Rules & Visibility

Source: /nice-realm/rules
Description: View and alter rules — path patterns, owner gating, serverChecked conditions, and how visibility slicing keeps hidden state on the server.

Every path in a realm's state answers two questions, decided by rules: **who may see it** (`view`) and **who may change it directly** (`alter`). Rules are declared in the definition, so they run identically as client-side prediction and as server-side authority.

```ts title="shared/marketRealm.ts"
rules: (r) => [
  // Everyone sees config; only server code writes it.
  r.path("config.*").view(r.everyone).alter(r.serverOnly),

  // Presence: everyone sees all cursors; you may only move your own.
  r.path("presence.$avatarId.{cursorX,cursorY}")
    .view(r.everyone)
    .alter(({ avatar, params }) =>
      avatar.persistentId === params.avatarId || err_market.fromId("not_yours")),

  // Vendor fast lane: a vendor sets their own prices directly,
  // with a server-checked floor.
  r.path("inventory.$vendorId.$produceId.pricePerKg")
    .view(r.everyone)
    .alter(r.all(
      ({ avatar, params }) => avatar.persistentId === params.vendorId
        || err_market.fromId("not_your_stall"),
      r.serverChecked(({ next, ctx }) =>
        next >= ctx.priceFloor || err_market.fromId("below_floor")),
    )),
],
```

## Path patterns

A pattern addresses a set of leaves in the state shape. Patterns are resolved against the schema **at the type level**, so the rule functions get precise `params`, `prev` and `next` types.

| Pattern piece | Matches |
|---|---|
| `config.open` | One exact leaf. |
| `config.*` | Every child under `config`. |
| `presence.$avatarId` | Each entry of a `t.record` — binds the key as `params.avatarId`. |
| `players.$playerId.{x,y}` | A brace set: just `x` and `y` under each player. |

When several rules could match a leaf, the **most specific pattern wins** — and anything no rule matches is **default-deny**, for both viewing and writing. You opt paths *in*, never out.

Wildcards (`*`, `**`) need at least one further segment, so they never match the node they hang off — a **wire-leaf** (a primitive, a `t.array`, a `t.schema`) is addressed by its *exact* path: `r.path("terrain")`, not `r.path("terrain.**")`. `defineRealm` throws on patterns that could never match a schema path (a typo'd key, or a wildcard descending into a wire-leaf), so a dead rule fails at definition time instead of silently default-denying its branch.

## View conditions

`view` decides which avatars receive a path's values (and its changes). View conditions are **coordinate-only** — they see `{ avatar, params }`, never state — because they're evaluated per leaf when slicing broadcasts:

- `r.everyone` — all avatar types (including replica-class avatars).
- `r.avatarTypes("vendor", "auditor")` — listed types only.
- A plain function `({ avatar, params }) => boolean` — e.g. owner-only: `avatar.persistentId === params.avatarId`.

**A view rule's `avatar` is `type` + `persistentId` only — never `instanceId`** (reading it is a compile error). Broadcasts are sliced and cached per *view signature* `(type, persistentId)`, so one avatar's tabs and devices share one encoded payload; a view branching on `instanceId` would be silently mis-sliced across them. Per-instance visibility isn't representable by design. (Alter rules run per write and *do* see the full identity including `instanceId`.)

**A hidden branch's bytes never leave the server.** Broadcasts are sliced per view signature and encoded once per audience group — clients don't "receive and ignore" hidden state; they never receive it.

### Owner visibility is a state-shaping pattern

Want each consumer to see only *their own* orders while vendors see the orders *for their stall*? Don't reach for clever conditions — shape the state so the coordinate is in the path, and denormalise per audience inside the intent that writes both:

```ts
state: {
  // keyed by the viewing coordinate — the view rule is then just an owner check
  ordersByConsumer: t.record(t.id("consumerId"), /* … */),
  ordersByVendor:   t.record(t.id("vendorId"),   /* … */),
}
```

## Alter conditions

`alter` decides who may **directly write** a path with `realm.update()` (intents bypass alter rules — they're trusted server code gated by their own `allow` list):

- `r.serverOnly` — only `engine.update()` (server code) writes here.
- A plain function `({ avatar, params, prev, next, state, basisVersion }) => true | NiceError` — runs on the client as prediction *and* on the server as authority. Return `true` to allow, or a [NiceError](/nice-error/domains/) to reject with a typed reason.
- `r.serverChecked(fn)` — a check that needs server-only facts: the injected `ctx`, or the log-backed CAS helper `touchedSince(basisVersion)`. **Client prediction auto-passes it** — this is exactly the slice of optimism that can roll back.
- `r.all(...conds)` — compose: all must pass, the first NiceError rejects.

Because plain alter functions run in prediction, a disallowed write **rejects locally and instantly** — the rejection surfaces on the settle handle and in `onMutationRejected`, and nothing hits the wire.

### Compare-and-set with `touchedSince`

For the rare direct write that must not clobber a concurrent edit, a `serverChecked` condition can consult the patch log:

```ts
r.serverChecked(({ basisVersion, touchedSince }) =>
  !touchedSince(basisVersion) || err_market.fromId("concurrent_edit"))
```

`basisVersion` is the confirmed version the writer composed against; `touchedSince` asks "was this path modified after that?" If routinely you need this, the mutation probably wants to be an [intent](/nice-realm/writes-intents/) instead.

## Replicas are an avatar rule

A Worker (or any server-side process) holding a live read copy of a realm is **just another avatar type** — one whose view rules say "everything" (or a partial slice), connected with `connectRealmReplica`. No special authority, no second code path; the same rules decide what it sees. See [Connecting & React](/nice-realm/connecting/#replicas).

---

# Security

Source: /nice-realm/security
Description: A realm inherits its connection's security level and can require a minimum — declared once, enforced on both ends. Plus the caveats that matter- at-rest storage, wire-visible rejections, replay, and TOFU.

A realm carries **avatar data** — identities, positions, presence, whatever your state tree holds — and it moves that data over your app's connection. So a realm's confidentiality and authenticity are exactly the connection's: the realm rides the same secured socket the action plane uses, negotiated **once** at the handshake. There is no separate realm crypto to configure.

That means everything in [Security Levels](/nice-wire/security/) applies verbatim — the three levels (`none` / `authenticated` / `encrypted`) — as does [Identity & Trust](/nice-wire/identity/): how `authenticated` proves identity with a signed challenge, and the trust-on-first-use key pinning. Read those first; this one is only what the realm layer adds on top.

## Declare a minimum: `security`

A realm can **require** a floor. The connection is where the level is chosen, but a realm shouldn't have to trust that every caller chose well — so it declares the least it will accept, and both ends enforce it:

```ts title="shared/gameRealm.ts"
export const gameRealm = defineRealm({
  id: "game_realm",
  security: "encrypted",      // "authenticated" (default) | "encrypted"
  avatars: { /* … */ },
  state:   { /* … */ },
  rules:   (r) => [ /* … */ ],
});
```

Two members, no `"none"`: a realm always requires at least an **identity-bound** (`authenticated`) connection — an unauthenticated realm has no idea who is writing, which no rule could survive. `authenticated` is the default, so a realm that says nothing already refuses a plain connection.

The declaration is **not** part of the schema hash — it's a policy floor, not a wire-compat fact, so raising or lowering it never forces a client migration.

### Enforced on both ends, fail-closed

The floor is checked twice, independently:

- **The server rejects an under-secured attach.** A `hello` arriving on a connection below the floor is answered with an `insufficient_security` rejection and **no hydrate** — no avatar data leaves the server for a connection that can't carry it at the required level. This holds across a hibernation wake too: the reconstructed host re-reads the connection's negotiated level from the persisted socket attachment and enforces the floor identically.
- **The client refuses to send.** Because the server "rejecting" still means the client already *sent* its `hello` (identity, and then its writes), a misconfigured client is stopped locally *before the first frame*: `connectRealm` / `connectRealmReplica` fail the attach — `whenLive()` rejects, `attachError` carries `insufficient_security`, and **not one realm frame is emitted onto the wire**. This is what keeps avatar data from leaving the device as app-layer plaintext when someone points an `encrypted` realm at an `authenticated` connection by mistake.

### Overrides only raise, never lower

You can tighten the floor for a particular deployment or connection without editing the definition:

```ts
// Server: raise the floor this host enforces (e.g. a PII deployment of a shared realm).
hostRealm(gameRealm, { security: "encrypted", resolveAvatar, engine });

// Client: raise the bar this connection asserts before its first hello.
connectRealm(gameRealm, { avatar, connection, security: "encrypted" });
```

Both are clamped to **≥** the definition's declared level — an override can only *raise* the requirement, never weaken it. The two sides are enforced independently: a `hostRealm` floor above what a client checked still rejects at the server (a client validating only the realm's declared minimum would have sent), so the server's floor is a real backstop, not advice.

### One connection, many realms — take the max

Several realms can share one connector (one handshake, one identity). A connection's security level is fixed at the handshake and **cannot be upgraded while live**, so establish the connection at the **maximum** of every realm's minimum it will carry. A realm whose floor exceeds the connection's negotiated level is a hard `connectRealm` / `connectRealmReplica` failure — never a silent downgrade or a renegotiation.

### Prefer `encrypted` for replicas

A [replica](/nice-realm/connecting/#replicas) is the highest-value connection in the system: its avatar type's rules typically grant it a broad — often "everything" — view, so its socket carries the most state. Treat it accordingly and require `encrypted` for replica connections handling anything sensitive, even when your client realm runs `authenticated`.

## Caveats worth internalizing

### Transport security is not at-rest encryption

`encrypted` seals every frame **in flight**. It says nothing about storage. A realm served on a Cloudflare Durable Object keeps its authoritative state in the DO's SQLite, which is **cleartext at rest**. For state that must not persist in the clear:

- prefer [`persistence: "ephemeral"`](/nice-realm/serving/) — nothing is written to disk; the realm lives only in memory and cold-starts from genesis (pair it with [`assertOnAttach`](/nice-realm/connecting/#assertonattach--state-you-must-own-while-attached) so clients re-assert their entries on a wake);
- or `migrate: "wipe"` plus a short `expireAfterIdleMs`, so an idle realm's storage is reclaimed quickly rather than lingering.

The principle: minimize what sensitive data is persisted and for how long. Field-level encryption of specific values (before they enter the state tree) is an app concern — the library encrypts the pipe, not your columns.

### Rejections are wire-visible — never put secrets in an error

A rule or intent rejection is sent to the client as the error's public JSON (`toJsonObject()` — its id, **message, and context**). The engine never serializes your `serverContext`, but it faithfully sends whatever *you* put in the error. So a rule error's message and context — and, like any `@nice-code/error`, its stack — are readable by the client. Treat them like the client bundle: don't embed server secrets, internal ids, or `ctx` values you wouldn't hand to the user in a rejection.

### `authenticated` is trust-on-first-use, not a CA

Identity pinning happens the **first** time two peers meet and is enforced on every subsequent connection — strong against an outsider who never held the key, but it is not certificate-authority-grade PKI. If first contact happens over a hostile network, the pin is of whoever answered. This is the same TOFU model [Identity & Trust](/nice-wire/identity/#trust-on-first-use-tofu) describes; it's called out here because a realm's whole authority model rests on the avatar identity that pin establishes.

### Replay is neutralized — but keep intents idempotent

The engine guards against replayed and duplicated frames: a resent `write` (same client sequence) is **re-acknowledged, not re-applied**, and that guard survives reconnects and hibernation wakes. You don't implement replay protection.

You *should* still make intents naturally idempotent, because at-least-once delivery means a **retry after a lost ack** can legitimately re-present an intent the server already applied. The pattern is a client-generated id the apply keys on:

```ts
// Client mints the id; a retry re-sends the SAME id.
realm.intents.purchase({ purchaseId: newId(), itemId });
```

```ts
// Server apply: already applied ⇒ commit as a no-op (no double-spend).
apply: ({ state, avatar, input }) => {
  if (state.orders[avatar.persistentId]?.[input.purchaseId] != null) return true;
  // …charge, decrement stock, write the order under input.purchaseId…
},
```

An intent that isn't idempotent turns a dropped ack into a double effect — a correctness *and* security problem (double-charge, double-grant). See [Writes & Intents](/nice-realm/writes-intents/).

### Record keys and state size

Two more the engine handles or delegates:

- **Prototype-pollution keys** (`__proto__`, `constructor`, `prototype`) can never be dynamic record keys — the engine rejects a frame (or an intent) that tries, on both apply and client projection. Nothing to do.
- **State size is bounded per frame, not cumulatively.** Ingress limits cap any single write; they do not cap how large the authoritative tree grows across many legitimate writes. Bounding writable-record **cardinality** — a ceiling on entries per record — is an app rule today (there is no `maxStateBytes` engine knob). If a record's key space is attacker-influenced, cap it in a rule.

## The short version

- A realm inherits its connection's level; declare a **minimum** with `security` (default `authenticated`; no `none`).
- The floor is enforced **both ends, fail-closed** — the server refuses to hydrate, the client refuses to send. Overrides only raise it.
- One connection carries realms at the **max** of their minimums; a shortfall is a hard failure, not a downgrade.
- `encrypted` is in-flight only — mind **at-rest** storage (ephemeral/wipe for sensitive state), keep secrets **out of rejections**, and make intents **idempotent**.

---

# Serving a Realm

Source: /nice-realm/serving
Description: The authoritative engine, the Cloudflare Durable Object host, persistence, hibernation, schema migration, and ingress limits.

The server side of a realm is two pieces: an **engine** (the authoritative state, rules enforcement, patch log, broadcast slicing) and an **acceptor** (the frame-protocol adapter that plugs engines into a wire connection). On Cloudflare, `serveRealmDurableObject` assembles both plus persistence in one call — start there.

## Cloudflare Durable Objects

The Durable Object serves **connections** — hibernatable secure sockets — and the realm registers on them as a protocol. A realm-only DO hosts them with `serveWireDurableObject` from [`@nice-code/wire`](/nice-wire/connection/) — the server counterpart of [`createWireClient`](/nice-realm/connecting/#realm-only-apps--createwireclient) — with **no `@nice-code/action` import, no `ActionRuntime`, and no channel**:

```ts title="MyRealmDurableObject.ts"
import { serveWireDurableObject } from "@nice-code/wire/platform/cloudflare";
import { hostRealm, serveRealmDurableObject } from "@nice-code/realm/platform/cloudflare";

const realms = serveRealmDurableObject(this.ctx, {
  realms: {
    game_realm: hostRealm(gameRealm, {
      avatarType: "player",         // identity defaults from the authenticated socket
      engine: {
        ctx: serverCtx,
        initialState: (info) => makeGenesis(info.instanceId),
        onAvatarDetach: (avatar) => pruneEphemeral(avatar),  // e.g. delete presence rows
      },
    }),
  },
});

const server = serveWireDurableObject(this.ctx, {
  identity: backendCoord.specify({ insId: this.ctx.id.toString() }),  // the handshake identity
  keyPrefix: "realm-ws:",           // DO-storage namespace for the crypto identity + TOFU pins
  protocols: [realms.protocol],     // ← the whole integration
});
// fetch(req)               => server.fetch(req)
// webSocketMessage(ws, m)  => server.receive(ws, m)
// webSocketClose/Error(ws) => server.drop(ws)
// alarm()                  => this.realms.alarms?.alarm()
```

A DO that **also serves actions** registers the same protocol on `@nice-code/action`'s `serveDurableObject` instead — both planes then share the sockets (the action host rides the same wire acceptor underneath):

```ts title="MyGameDurableObject.ts"
import { serveDurableObject } from "@nice-code/action/platform/cloudflare";

const server = serveDurableObject(this.ctx, gameChannel, {
  runtime, clientEnv,
  protocols: [realms.protocol],
  channelCases: { /* the channel's actions */ },
});
```

What you get automatically:

- **Persistence**: every commit lands in the DO's SQLite patch log; snapshots are written on a cadence (`snapshotEveryVersions`, default 64); a cold start is snapshot + tail replay. The Durable Object class needs SQLite storage enabled in wrangler.
- **Hibernation**: the socket is hibernatable. On wake, presence is reconciled — clients whose sockets vanished during hibernation get a synthesized detach — and surviving clients resume via **patch replay**, not a re-download.
- **Identity**: with `avatarType`, each connection's avatar defaults from the coordinate the server persisted on the socket attachment — on a secure socket, the *authenticated* handshake identity. Provide `resolveAvatar: (ws) => ref` only when you need custom mapping (it must also work at DO wake, from the attachment alone).
- **Security floor**: the host enforces the realm's declared `security` minimum fail-closed — a connection below it is refused at attach (`insufficient_security`, no hydrate), on the first hello and on every post-wake re-hello. Pass `hostRealm(realm, { security: "encrypted", … })` to *raise* the floor for this deployment (it can only raise, never lower). See [Security](/nice-realm/security/).
- **Multi-tab / multi-device is already counted.** `onAvatarDetach` fires **once per avatar identity** (`type` + `persistentId`) when its *last* connection drops — a second tab or device never reaches the hook, and the same identity reconnecting elsewhere never fires a false departure. The presence prune above really is the whole handler: `(avatar) => engine.update((d) => { delete d.players[avatar.persistentId]; })` — no socket scanning, no instance bookkeeping.
- **A reconnect is not a departure.** A client's own staleness-probe re-hello, a hibernation-wake resume, or any same-avatar re-attach on a live socket swaps the connection in place **without firing `onAvatarDetach`/`onAvatarAttach`** — so a prune-on-detach handler never deletes an idle-but-present player's state. The hooks fire only on a genuine first-arrival / last-departure; a hello that resolves a *different* identity on the same socket runs the old avatar's detach first (reason `"identity-changed"`).

### Boot-time validation

Misconfigurations that used to surface as production cold-start failures are construction-time errors instead: a `realms` key that doesn't match its definition `id` throws, and a snapshot cadence that outruns the replayable log throws with the corrective message (`snapshotEveryVersions` must be ≤ half the engine's `logWindow` — otherwise a crash between snapshots can leave the log compacted past the last snapshot).

### Schema evolution

A changed schema hash **refuses to boot** rather than silently reinterpreting persisted state. To evolve the shape, pass a `migrate` hook on the realm entry:

```ts
hostRealm(gameRealm, {
  avatarType: "player",
  engine: { /* … */ },
  migrate: (oldStateBlob, oldHash) => upgradeState(decode(oldStateBlob), oldHash),
});
```

On migrate, the old patch log is discarded (its ops are in the old shape), a fresh snapshot is written immediately, and the realm starts a **new log epoch** — connected clients holding old version numbers cleanly full-hydrate instead of replaying a foreign history.

State that never needs migrating — presence, cursors, anything clients re-assert themselves — declares that instead: `migrate: "wipe"` discards the old snapshot + log on a hash mismatch and boots `initialState` on a fresh epoch. Pair it with [`assertOnAttach`](/nice-realm/connecting/#assertonattach--state-you-must-own-while-attached) on the client and a schema change costs a blink, not a migration.

### Ephemeral realms (presence)

Why persist a patch log for cursor positions? A presence-shaped realm can skip storage entirely:

```ts
hostRealm(lobbyRealm, {
  avatarType: "player",
  persistence: "ephemeral",     // no snapshots, no persisted patch log
  engine: { ctx, initialState: emptyLobby, onAvatarDetach: prune },
});
```

Every cold start — including a hibernation eviction — boots `initialState` on a fresh epoch; surviving sockets full-rehydrate (near-)empty state. **This mode assumes clients assert their own entries** via [`assertOnAttach`](/nice-realm/connecting/#assertonattach--state-you-must-own-while-attached) — without it, an eviction silently empties the roster with everyone still connected. Ephemeral realms need no `migrate` (there is never a snapshot to migrate; passing one is a construction error) and don't take `expireAfterIdleMs` (nothing to GC).

### Idle-TTL storage GC (per-entity realms)

One realm per match / run / document (`idFromName(matchId)`) orphans SQLite snapshots and patch logs forever once the entity is over. The host GCs them for you:

```ts
const realms = serveRealmDurableObject(this.ctx, {
  realms: { match_realm: hostRealm(matchRealm, { /* … */ }) },
  expireAfterIdleMs: 24 * 60 * 60 * 1000,
  onExpire: (realmId, engine) => {
    if (isStillInteresting(engine.state)) return false;  // veto — one more period
    // also the place to drop app-owned storage that dies with the realm
  },
});
// A Durable Object has exactly ONE alarm — forward it (the host exposes its mux):
//   async alarm() { await this.realms.alarms?.alarm(); }
```

The deadline arms on the last detach (and at boot when nothing is attached), disarms on any attach, and on firing drops the realm's snapshot, patch log, and attached rows — the name simply boots genesis if it is ever addressed again.

**The app's own DO deadlines ride the same mux.** A Durable Object has exactly one alarm and `ctx.storage.setAlarm` is last-write-wins, so a second scheduler on the same DO would silently clobber the host's deadlines. `host.alarms` is always there on an alarm-capable DO — whether or not `expireAfterIdleMs` / a durable grace is set — so registering an app deadline is one call, no second mux to build:

```ts
this.realms.alarms?.register("my-cleanup", (now) => { /* fires via the DO's single alarm */ });
```

(If the app already built its own `createDurableObjectAlarmMux`, pass it as `alarms` and the host rides *that* instead.)

#### Upgrading from ≤ 0.49

Before 0.50 you only got a mux if you asked for one (or set `expireAfterIdleMs` / a durable `avatarDetachGraceMs`). From 0.50 the host builds one on **every** alarm-capable DO. If your DO class calls `ctx.storage.setAlarm()` directly alongside the realm host, move those deadlines onto `host.alarms.register(...)` — once the mux holds a deadline of its own, the two schedulers are back to last-write-wins on the DO's single alarm slot.

The mux never touches the alarm slot until it has a deadline to arm, so an un-migrated app alarm is left alone rather than clobbered. That is a grace period, not a supported configuration: migrate.

#### When a deadline's handler fails

A registrant's deadline is deleted only **after** its handler resolves. A handler that throws is logged and its deadline pushed out on a bounded exponential backoff (2 s, 4 s, 8 s … capped at 5 min), so it retries until it succeeds or you `cancel()` it. A handler evicted mid-`await` keeps its row and re-dispatches when the DO next wakes and reconstructs the mux.

Two consequences worth designing for:

- **Dispatch is at-least-once.** An eviction between your handler resolving and its row being deleted re-runs it. Handlers should be idempotent.
- **`alarms.alarm()` does not throw on a registrant's behalf.** An uncaught exception out of a real DO's `alarm()` aborts the object — in-memory state gone, sockets torn — and [Cloudflare abandons the alarm after 6 retries](https://developers.cloudflare.com/durable-objects/api/alarms/). One registrant's bad handler must not do that to a DO shared with everyone else's, so the mux catches, logs, and owns the retry. Watch your logs for `[alarmMux] deadline "…" threw`.

## The engine

`createRealmServerEngine(realm, options)` is the authoritative core, host-agnostic. The Durable Object host builds it for you from the `engine` block above; outside Cloudflare you construct it directly. The options:

| Option | What it does |
|---|---|
| `ctx` | The server-only context (secrets live here — never in the definition). Reaches `serverChecked` rules and intent `apply` bodies. |
| `initialState` | Genesis — a value or `(info) => state`, run exactly once per instance, before the first attach. |
| `onAvatarAttach` / `onAvatarDetach` | An avatar's first live connection / last connection dropped. Dispatch is deferred a microtask, so the hooks **may freely call `engine.update()`** (presence rows, prune-on-leave). Attach can re-fire for hibernation survivors without a paired detach — keep it idempotent. |
| `onMutation` | Fires **synchronously** after every commit with the canonical patches — persist/report/throttle here. **Observe-only**: calling `engine.update()` from it is unbounded recursion, not re-entrancy. |
| `limits` | Ingress limits (below). |
| `logWindow` | Versions kept replayable behind the head (default 512); older reconnects fall back to full hydrate. |

Server code mutates through `engine.update((draft) => { … })` — the `r.serverOnly` write path for ticks, fulfilment, and anything the server drives itself.

## Serving outside Cloudflare

`createRealmAcceptor({ realms })` produces a wire frame protocol from any set of engines — anything that can register a frame protocol on a `@nice-code/wire` connection can serve a realm. You own persistence in that case: feed `restore: { state, version, epoch }` to the engine at boot and persist from `onMutation`.

### Resolving avatar identity off a live connection

The Cloudflare host's `avatarType` shortcut reads identity from the coordinate persisted on a socket's **attachment** (it has to survive hibernation). A plain server has no attachment concept, so it reads the same authenticated coordinate off the **live** connection instead — `server.acceptors[i].wireAcceptor.clientForConnection(connection)`, the live-connection counterpart of the DO host's attachment lookup, both public API:

```ts title="realm_ws_server.ts"
// Set right after `serveChannel` returns — the resolver only runs on an inbound hello,
// so this just breaks the type-checker's "server referenced in its own initializer".
let clientForConnection: ((ws) => RuntimeCoordinate | undefined) | undefined;

const server = serveChannel(runtime, channel, {
  // …carriers, storage…
  protocols: [
    createRealmAcceptor({
      realms: {
        game_realm: {
          engine,
          resolveAvatar: (ws) => {
            const client = clientForConnection?.(ws);   // the authenticated handshake identity
            if (client?.perId == null) return undefined; // no identity yet → refuse the attach
            return { type: "player", persistentId: client.perId, instanceId: client.insId ?? "default" };
          },
        },
      },
    }),
  ],
});
clientForConnection = (ws) => server.acceptors[0]?.wireAcceptor.clientForConnection(ws);
```

Returning `undefined` from `resolveAvatar` refuses the attach — the realm never serves a connection whose identity it can't resolve.

### The security floor is never `"none"` — `allowPlain` can't open a realm

A realm's declared `security` minimum is `"authenticated"` or `"encrypted"` — there is deliberately **no** `"none"` tier (`TRealmSecurityLevel` has no such member). So a realm can't be served over an unauthenticated connection, and the acceptor-level `allowPlain` escape hatch — which does let *other* protocols run at `ESecurityLevel.none` — cannot make one work: `connectRealm` enforces the floor **client-side, before it sends the first `hello`**, so a client connected at `none` sets `attachError` and stays `detached` no matter what the server allows. Serve realms over the real authenticated handshake, exactly like the Cloudflare host does (the sample above already does — `clientForConnection` only returns a coordinate for an authenticated connection). See [Security](/nice-realm/security/).

## Ingress limits

Every connection is guarded by per-realm limits (defaults shown); breaches reject with `limits_exceeded`, and a connection exceeding `maxBreachesBeforeDetach` is forcibly detached:

| Limit | Default | Guards |
|---|---|---|
| `maxPatchesPerFrame` | 64 | Ops in one write frame. |
| `maxFrameBytes` | 64 KiB | Encoded size of one inbound frame. |
| `maxRecordKeyLength` | 128 | Dynamic record-key length (also protects the intern dictionary). |
| `maxExpandedLeaves` | 256 | Leaves one subtree write may expand to. |
| `writeRatePerSecond` / `writeRateBurst` | 100 / 200 | Token-bucket write rate per connection. |
| `maxBreachesBeforeDetach` | 10 | Strikes before forcible detach. |

The client-relevant limits are **advertised to clients in the hydrate**, and well-behaved clients never breach them: over-limit flushes split automatically, and rate breaches back off and retry — see [Connecting & React](/nice-realm/connecting/#limits-are-advertised-and-livable).

---

# Testing Realms

Source: /nice-realm/testing
Description: createTestRealm — a deterministic in-memory world for testing rules, intents, predictors, and rollback UX with no network and no Cloudflare.

`@nice-code/realm/testing` runs the whole loop — engine, acceptor, any number of clients and replicas — over a zero-network loopback, deterministically. Your rules, intents, predictors, and rollback UX get real tests with no sockets and no Cloudflare:

```ts title="marketRealm.test.ts"
import { createTestRealm } from "@nice-code/realm/testing";

const world = createTestRealm(marketRealm, { ctx, initialState });
const alice = world.asAvatar({ type: "consumer", persistentId: "alice" });

alice.realm.update((draft) => { draft.presence.alice = { cursorX: 1, cursorY: 1 }; });
await world.settleAll();

expect(world.engine.state.presence.alice).toBeDefined();
expect(alice.realm.store.state).toEqual(world.serverSlice(alice.avatar));
```

## The world

`createTestRealm(realm, options)` takes `ctx`, `initialState`, and optionally `limits`, `logWindow`, and `pendingExpiryMs` (handy for making expiry tests fast). It returns:

| Member | What it does |
|---|---|
| `world.engine` | The real `RealmServerEngine` — assert on `engine.state` directly. |
| `world.asAvatar({ type, persistentId }, connectOptions?)` | A connected avatar handle: `{ realm, avatar, rejections, … }`. The second argument passes per-avatar connect options through (`assertOnAttach`, `coalesceMs`, `pendingExpiryMs`, `staleProbeAfterMs`) — so presence asserts and durability scenarios test exactly as they ship. |
| `world.asReplica({ type, persistentId })` | A connected replica handle. |
| `world.update(fn)` | Server-authored mutation (`r.serverOnly` paths) — sugar for `engine.update`. |
| `world.settleAll()` | Drain the coalescing microtask + settle the round-trips. |
| `world.serverSlice(avatar)` | **The oracle**: the server's current sliced view for an avatar. |

That last one is the assertion that matters most — after any sequence of writes settles, every client's projection should equal its `serverSlice`:

```ts
expect(alice.realm.store.state).toEqual(world.serverSlice(alice.avatar));
```

If those two ever diverge after `settleAll()`, something is wrong — in your rules, your predictor, or (tell us!) the library.

## Observing the optimistic window

Delivery is normally synchronous-ish (writes flush on a microtask). To *see* the pending state, park the server's replies:

```ts
alice.holdServerFrames();                    // server → client frames queue up
const h = alice.realm.update((d) => { d.presence.alice.cursorX = 5; });
expect(h.status).toBe("pending");            // optimistic: applied locally, unconfirmed
expect(alice.realm.pending.count).toBe(1);

alice.pump();                                // deliver everything parked
await h;                                     // read-your-writes: store is authoritative now
expect(h.status).toBe("confirmed");
```

## Rejections and rollback

Each test client collects its rejections, so predictor-vs-authority tests are one array assertion:

```ts
const mallory = world.asAvatar({ type: "consumer", persistentId: "mallory" });
mallory.realm.update((d) => { d.presence.alice.cursorX = 99; });  // not hers
await world.settleAll();

expect(mallory.rejections).toHaveLength(1);
expect(mallory.rejections[0].rolledBackPaths).toContain("presence.alice.cursorX");
// and the rollback held:
expect(mallory.realm.store.state).toEqual(world.serverSlice(mallory.avatar));
```

(With a plain — non-`serverChecked` — alter rule this rejects **locally** before any frame is sent; the shape of the test is the same either way.)

## Scripting the reconnect matrix

`disconnect()` / `reconnect()` drop and restore a client's link — frames in flight are lost, exactly like the real thing:

```ts
alice.disconnect();
world.update((d) => { d.config.open = false; });   // happens while she's away
alice.reconnect();
await world.settleAll();

// she resumed via patch replay and converged:
expect(alice.realm.store.state).toEqual(world.serverSlice(alice.avatar));
```

This is the harness the library's own suite is built on — reconnect/replay, rule enforcement, intent idempotency, pending-expiry, and rollback behavior are all expressible in a few lines each.

---

# Writes & Intents

Source: /nice-realm/writes-intents
Description: The realm write contract — LWW direct writes vs atomic server-side intents, settle handles, and choosing between them.

This is the one page to internalise before shipping a realm. There are exactly two ways state changes from a client, and picking the wrong one is the classic way to lose a decrement.

## Direct writes: absolute-set, last-writer-wins

`realm.update()` is an optimistic direct write with **absolute-set semantics**: the server applies your literal values in arrival order.

```ts
realm.update((draft) => { draft.presence[me].cursorX = 412; });
```

"Cursor is at 412" is a perfect direct write — the newest value is simply the truth. But **read-modify-write composed locally races**:

```ts
// ❌ WRONG — two clients doing this concurrently lose one decrement, silently.
realm.update((draft) => { draft.stock[itemId] -= 1; });
```

Both clients read `5`, both send "stock is 4", the server applies both — stock is `4`, not `3`. No error, no warning: each write was individually legal. Anything read-modify-write, multi-path atomic, or dependent on hidden state is an **intent**.

### Coalescing — don't hand-roll a throttle

Direct writes **coalesce**: successive updates inside the same microtask merge into one wire frame, deduped per path — pointer-frequency writing is cheap by default. For hover/cursor-grade streams, widen the window with the `coalesceMs` connect option instead of writing your own throttle timer:

```ts
connectRealm(gameRealm, {
  // …
  coalesceMs: 120,   // pointer-frequency writes batch into one frame per 120 ms
});
```

`realm.update((d) => { d.hover = pos; })` on every pointermove is then already rate-shaped — the library dedupes per path inside the window, so only the newest value travels.

### Durable writes: `durability: "reassert"`

The default optimistic contract expires an unanswered write after `pendingExpiryMs` and rolls it back — right for presence and cursors, wrong for a client that is the **authoritative producer** of a region (a game host streaming an append-only input log: the data exists nowhere else, so "roll it back" means "lose it"). That role gets the durable tier:

```ts
realm.update((d) => { for (const ev of batch) d.log[ev.seq] = ev; }, { durability: "reassert" });
```

A reassert write never expires: it is rebuilt and resent on every reattach — including across a full rehydrate or a server epoch change — until the server confirms it. **Authority still wins**: a rules rejection settles it immediately, durable or not; durability is about *link* failures, never about overriding the server. Two usage rules:

- **One tier per path region.** Reassert frames only coalesce with other reassert frames — keep the producer's paths (the log) durable and everything else default, and never write one path with both tiers.
- **The backlog is bounded.** Past ~256 unconfirmed reassert frames (an outage measured in minutes), further reassert writes reject with `durable_backlog_overflow` — the cue to fall back to re-syncing from your own source of truth after reconnecting, instead of queueing more.

Intents have no durable tier by design: a durable, data-answering exchange is the **action plane** — that's [reliable delivery](/nice-action/reliable-delivery/). See [Reconnects & durability](/nice-realm/connecting/#reconnects--durability) for the full reconnect lifecycle.

## Intents: named, atomic, server-side

An intent is a named mutation whose `apply` body runs **on the server, atomically, against the full authoritative state**:

```ts title="shared/marketRealm.ts"
intents: (i) => ({
  purchase: i.define({
    allow: ["consumer"],
    input: t.object({ purchaseId: t.string(), itemId: t.string() }),
    // Optional client-side prediction on the caller's own view.
    optimistic: ({ view, avatar, input }) => { /* … */ },
    apply: ({ state, avatar, input, ctx }) => {
      // Idempotent retry: already applied ⇒ commit as a no-op.
      if (state.purchases[avatar.persistentId]?.[input.purchaseId] != null) return true;
      if (state.stock[input.itemId] < 1) return err_market.fromId("sold_out");
      state.stock[input.itemId] -= 1;        // authoritative read-modify-write
      state.purchases[avatar.persistentId][input.purchaseId] = { itemId: input.itemId };
      return true;                            // or a NiceError — draft discarded entirely
    },
  }),
}),
```

```ts title="client.ts"
const handle = realm.intents.purchase({ purchaseId: newId(), itemId });
await handle; // then read the store at your client-supplied key
```

The pieces:

- **`allow`** — the avatar types that may call it. Together with the `input` schema, this is the security boundary; the `apply` body itself is trusted code and bypasses view/alter rules.
- **`input`** — a `t.*` schema, validated on the way in. Give entities **client-supplied ids** (`purchaseId: newId()`) so retries are idempotent and the client knows where to read the outcome.
- **`optimistic`** *(optional)* — a prediction run on the caller's own view; its patches join the pending overlay like a write. A predictor that throws is treated as absent — prediction must never break the write.
- **`apply`** — an [Immer](https://immerjs.github.io/immer/) draft of the full authoritative state. Return `true` to commit, or a NiceError to reject — the draft is then **discarded entirely, never partially applied**.

Intents are **settle-only**: no data result comes back. Outcomes live in state — `await` the handle, then read the store at the keys you supplied. If you need a data *response*, that's a [nice-action action](/nice-action/defining-actions/).

### Presentation lags authority

Because an intent commits atomically, everything it touched lands in **one client flush**. That is what you want for consistency — and exactly what will spoil an animation: a shot that ends the match delivers the replay payload (`lastShot`) *and* `meta.status = "finished"` together, so a component that renders status directly announces the outcome before the scene has animated the cause. Gate outcome UI (winner overlays, end-of-round screens) on your presentation layer's own progress — an `animating` flag, a scene event — not straight on the authoritative field. The state plane says what is *true*; your scene decides when to *show* it.

## Settle handles

Every write API returns an `IRealmWriteHandle` — a **lazy thenable**:

- Safe to ignore: a fire-and-forget cursor write produces zero unhandled-rejection noise.
- `handle.status` (`"pending" | "confirmed" | "rejected"`) and `handle.error` for imperative checks.
- **Read-your-writes**: after `await handle`, the store already reflects the authoritative outcome — confirmed values are in, rejected values are rolled back.

Rejections also fan into the handle-level `onMutationRejected` callback with the rolled-back paths — the "toast + highlight what snapped back" hook:

```ts
connectRealm(gameRealm, {
  // …
  onMutationRejected: ({ error, kind, rolledBackPaths }) => toastRollback(error, rolledBackPaths),
});
```

A pending write that the server never answers (link trouble) expires after `pendingExpiryMs` (default 10 s) and rolls back — the optimistic overlay can't get stuck. The dial is per-handle: raise it freely on a handle whose UI doesn't render from realm state (a game host drawing from its local sim), or skip expiry entirely for producer regions with [`durability: "reassert"`](#durable-writes-durability-reassert). (This is a different dial from nice-action's `reliableActionTimeout`, which is a redelivery deadline for at-least-once actions.) Within the window, a disconnect does **not** expire anything — pending writes resend automatically on reattach; see [Reconnects & durability](/nice-realm/connecting/#reconnects--durability).

### Split flushes

If a coalesced flush exceeds the server-advertised `maxPatchesPerFrame`, the client **splits** it into consecutive frames. Each part stays atomic on the server and all handles settle with the last part — read-your-writes holds — but a split flush is no longer atomic *as a whole*. If a group of paths must change together atomically, put them in one intent.

## Choosing, at a glance

| Situation | Use |
| --- | --- |
| High-frequency absolute-set values (cursor, position, a toggle you own) | `realm.update` |
| Read-modify-write, counters, balances, multi-path invariants | intent |
| An append-only region you alone produce (event/input logs) | `realm.update(fn, { durability: "reassert" })` |
| "My entry must exist while I'm attached" (presence) | [`assertOnAttach`](/nice-realm/presence/) |
| Needs a data response back | a [nice-action](/nice-action/defining-actions/) action |
| Rare single-path write that must not clobber concurrent edits | `realm.update` + `touchedSince` CAS in a [`serverChecked` rule](/nice-realm/rules/#compare-and-set-with-touchedsince) |
| High-stakes / low-confidence mutation | intent **without** `optimistic` — await the handle (spinner UX, zero rollback risk) |
| Server-driven mutation (ticks, fulfilment) | `engine.update()` on the [server](/nice-realm/serving/) |

---

# Patches & Devtools

Source: /nice-state/patches
Description: Immer patch streams for undo/redo and sync, plus the state inspector panel.

## Patches

Every update can produce [Immer patches](https://immerjs.github.io/immer/patches/) — a small description of exactly what changed. Patches power undo/redo, syncing, and the devtools. They're only built when something is actually listening for them, so you pay nothing for them the rest of the time.

```ts
import { applyPatchesToStore } from "@nice-code/state";

// Listen to patches for every update
const stop = store.listenToPatches((patches, inversePatches) => {
  sendToServer(patches);
});

// Or collect patches for a single update
store.update((s) => { s.count += 1; }, (patches, inverse) => {
  undoStack.push(inverse);
});

// Apply patches (received from elsewhere, or to undo)
store.applyPatches(patches);
```

Inverse patches are how undo works: keep a stack of them, and `applyPatches` the top one to undo the last change.

## Devtools

An inspector for your stores that needs no setup — a timeline of changes, before/after diffs, a live view of your state you can edit directly, and one-click undo using patches. Name the stores you want to observe; nothing renders inside your app.

```ts
// devtools.ts
import { createNiceDevtools } from "@nice-code/devtools";
import { counterStore } from "./counterStore";

export const devtools = createNiceDevtools({
  topologyId: "my-app",
  stores: { counterStore },   // the key is the label the panel shows
});
```

Underneath that is a `StateDevtoolsCore` (`registerStore("counterStore", counterStore)`) streamed through `stateBridgeScope`, both from `@nice-code/state/devtools/browser`. A store created later joins with `devtools.registerStore(…)`.

The panel — rendered in [the devtools window](/devtools/window/) — lets you filter by store, inspect and edit live state, view per-change diffs and patches, pause the timeline, and revert a change via its inverse patches.

> Registering a store attaches a patch listener (a negligible dev-time cost). Keep devtools setup out of production bundles.

## Exports

| Entry | Contents |
|---|---|
| `@nice-code/state` | `Store`, `update`, `applyPatchesToStore`, core types |
| `@nice-code/state/react` | `useStoreState`, `useLocalStore`, `InjectStoreState` |
| `@nice-code/state/devtools/browser` | `StateDevtoolsCore`, `NiceStateDevtools` |

---

# React Adapter

Source: /nice-state/react
Description: Subscribe components to stores with useStoreState and friends — no provider.

Import from `@nice-code/state/react`. No provider needed — pass the store directly. `react >= 19` is an optional peer dependency.

## useStoreState

```tsx
import { useStoreState } from "@nice-code/state/react";

function Counter() {
  // Select a slice — re-renders only when `count` changes.
  const count = useStoreState(counterStore, (s) => s.count);

  return (
    <button onClick={() => counterStore.update((s) => { s.count += 1; })}>
      {count}
    </button>
  );
}
```

```tsx
// No selector → subscribe to the whole state.
const state = useStoreState(counterStore);
```

## Selecting computed values

A selector's result is checked by reference (`===`) first — the fast path, and exactly right for slices of your state, because Immer reuses the objects that didn't change. When the reference *does* differ, the result falls through to an equality function that **defaults to `deepEqual`**, so a selector that builds a **brand-new** object or array every call (a `.filter`, a `.map`, an object literal) doesn't cause a needless re-render when the value is structurally the same:

```tsx
import { useStoreState } from "@nice-code/state/react";

// Rebuilds a new array each call, but only re-renders when the filtered result
// actually changes — the deepEqual default absorbs the new-but-equal case.
const activeTodos = useStoreState(store, (s) => s.todos.filter((t) => !t.done));
```

This matches `store.watch()`'s equality behavior, so both ways of subscribing treat a recomputed-but-equal value the same. The deep comparison only runs on a genuine reference change and is bounded by the size of the selected slice. If a selector returns a very large slice on a hot path and you'd rather skip the traversal, pass a strict comparator to opt back into reference-only checks:

```tsx
const bigSlice = useStoreState(store, (s) => s.hugeThing, (a, b) => a === b);
```

## Stores that live inside one component

`useLocalStore` makes a store that belongs to a single component instance and sticks around across renders. Pass a `deps` array to rebuild it (with fresh initial state) whenever those dependencies change.

```tsx
import { useLocalStore, useStoreState } from "@nice-code/state/react";

function Editor({ docId }: { docId: string }) {
  const store = useLocalStore(() => ({ draft: "" }), [docId]);
  const draft = useStoreState(store, (s) => s.draft);
  // ...
}
```

## Render-prop binding

`InjectStoreState` subscribes inline without writing a hook:

```tsx
import { InjectStoreState } from "@nice-code/state/react";

<InjectStoreState store={counterStore} on={(s) => s.count}>
  {(count) => <span>{count}</span>}
</InjectStoreState>
```

---

# Reactions & Watch

Source: /nice-state/reactions
Description: Derive state from state, and run side-effects outside React.

## Reactions — build state from other state

A reaction watches one slice of state and, when it changes, runs a function (inside Immer) to update other fields on the **same** store. Reactions run before any subscribers are notified, so these derived fields are always up to date within a single render.

```ts
interface IState {
  count: number;
  doubled: number;   // derived — never written by hand
  history: number[]; // derived
}

const store = new Store<IState>({ count: 0, doubled: 0, history: [] });

store.createReaction(
  (s) => s.count,                  // watch
  (count, draft) => {              // derive
    draft.doubled = count * 2;
    draft.history = [...draft.history, count].slice(-12);
  },
  { runNow: true },                // run once immediately to seed derived state
);
```

`createReaction` returns a disposer to remove the reaction.

## Watch — side-effects outside React

`watch` follows a slice of state and runs your callback only when that slice actually changes. Great for logging, saving to storage, or keeping non-React code in sync.

```ts
const unsubscribe = store.watch(
  (s) => s.count,
  (count, allState, previousCount) => {
    console.log(`count: ${previousCount} → ${count}`);
  },
);
```

The low-level `store.subscribe(() => { ... })` runs on every update (no slice, no arguments) — it's the basic building block the React adapter is built on.

## Reaction vs watch vs subscribe

| API | Runs when | Use it for |
|---|---|---|
| `createReaction` | a watched slice changes | building more state _onto the same store_ |
| `watch` | a watched slice actually changes | side-effects (logging, saving, syncing) |
| `subscribe` | every update | the low-level building block; for writing adapters |

---

# Stores

Source: /nice-state/stores
Description: Create an Immer-backed store and mutate it through drafts.

`@nice-code/state` is a small state store that works with any framework (built on Immer). It lets components subscribe to just the slice of state they care about, derive state from other state, stream changes as patches, and — if you use React — comes with a React adapter.

```bash
bun add @nice-code/state immer
```

## Why use it

- **One store, updated the easy way** — write normal mutations (`s.count += 1`) and Immer turns them into a new immutable state for you, reusing the parts that didn't change.
- **Updates that change nothing cost nothing** — subscribers are only notified when the state actually changes.
- **Subscribe to a slice, not the whole thing** — a component or side-effect only re-runs when the specific slice it watches changes.
- **Plays nicely with React** — built on `useSyncExternalStore`, with no provider or context to set up.

## Create a store

Pass an initial value, or a function that builds one (handy for SSR and resetting).

```ts
import { Store } from "@nice-code/state";

interface ICounterState {
  count: number;
  step: number;
}

export const counterStore = new Store<ICounterState>({ count: 0, step: 1 });
```

## Update state

Updates run through Immer — change the `draft` however you like, and the store saves a new immutable state from it.

```ts
// Single update
counterStore.update((s) => {
  s.count += s.step;
});

// Batched — applied in order, committed as one change
counterStore.update([
  (s) => { s.count += 1; },
  (s) => { s.count += 1; },
]);
// Subscribers and React components (`useStoreState`) are notified only ONCE, at the end of
// the batch — never on the intermediate state — which avoids extra/tearing renders.

// Replace the whole state
counterStore.replace({ count: 0, step: 1 });

// Replace by mapping from current state
counterStore.replaceFromCurrent((s) => ({ ...s, count: 0 }));
```

An updater's second argument is a read-only snapshot of the state from *before* this update:

```ts
counterStore.update((draft, original) => {
  draft.count = original.count * 2;
});
```

## Read state

```ts
const { count } = counterStore.state;
```

The `state` getter returns the current state, frozen for read safety — writes must go through `update`/`replace`.

> Only read `store.state` in plain logic. In components use [`useStoreState`](/nice-state/react/); for side-effects use [`watch`](/nice-state/reactions/).

## SSR

On the server, `useStoreState` just reads the store's current value (it doesn't subscribe). Build your stores with a function (`new Store(() => initialState())`) so each request can start with its own fresh state.

---

# Crypto

Source: /nice-util/crypto
Description: WebCrypto helpers — Ed25519 signing, X25519 exchange, AES-GCM, and a client link.

Crypto helpers built on WebCrypto, so they run the same in browsers, Workers / Durable Objects, Bun, and Node. When a key is turned into a string, that string carries its own description (`<algo>::<format>::<data>`) — so wherever you store or send a key, it always knows how to load itself back in.

> Crypto helpers require the `@scure/base` peer dependency.

## Ed25519 — sign & verify

```ts
import {
  generateEd25519KeyPair,
  importEd25519Key,
  serializeEd25519Key_Raw,
  signTextDataWithKeyEd25519,
  verifyWithKeyEd25519,
} from "@nice-code/util";
import { base64 } from "@scure/base";

const keyPair = await generateEd25519KeyPair();

// Sign
const signature = await signTextDataWithKeyEd25519("challenge-text", keyPair.privateKey);
const signatureBase64 = base64.encode(signature);

// Serialize the public key for transport — "ed25519::raw_base64::<data>"
const { prefixed } = await serializeEd25519Key_Raw(keyPair.publicKey);

// Other side: import + verify
const publicKey = await importEd25519Key.public.fromFormattedString.extractable(prefixed);
const isValid = await verifyWithKeyEd25519({
  challenge: "challenge-text",
  signatureBase64,
  publicKey,
});
```

## X25519 + AES-GCM — shared-key encryption

Derive a shared AES-GCM key from two X25519 key pairs (ECDH + HKDF), then encrypt/decrypt:

```ts
import {
  generateX25519KeyPair,
  createAesGcmKeyFromX25519Keys,
  encryptTextDataWithAesGcmKey,
  decryptTextDataWithAesGcmKey,
} from "@nice-code/util";

const alice = await generateX25519KeyPair();
const bob = await generateX25519KeyPair();

// Both sides derive the same key from their private + the other's public key
const aliceKey = await createAesGcmKeyFromX25519Keys({
  internalX25519PrivateKey: alice.privateKey,
  externalX25519PublicKey: bob.publicKey,
  saltString: "optional-session-salt",
  infoString: "optional-context",
});

const payload = await encryptTextDataWithAesGcmKey({
  aesGcmKey: aliceKey,
  dataToEncrypt: "secret message",
}); // { nonce, ciphertext } — both base64

const plaintext = await decryptTextDataWithAesGcmKey({
  aesGcmKey: bobKey,
  dataToDecrypt: payload,
});
```

## ClientCryptoKeyLink — full client-to-client crypto

A high-level class that holds your local identity (an Ed25519 sign/verify pair plus an X25519 exchange pair) and the links to other clients. It can optionally save all of this through any `StorageAdapter`.

```ts
import { ClientCryptoKeyLink, createMemoryStorageAdapter_json } from "@nice-code/util";

const link = new ClientCryptoKeyLink({
  storageAdapter: createMemoryStorageAdapter_json(), // optional — omit for in-memory only
});
await link.initialize();

// Share these with the other side (serialized prefixed strings)
const { verifyPublicKey, exchangePublicKey } = await link.getLocalPublicKeys();

// Register the other side's keys
await link.linkClient({
  linkedClientId: "client::partner-1",
  verifyPublicKey: theirVerifyKey,
  exchangePublicKey: theirExchangeKey,
  bindVerifyKeysIntoDerivation: true, // a tampered relayed key makes the first decryption fail
});

// Sign + encrypt for the linked client (shared key derived & cached automatically)
const { encryptedData, signatureBase64 } = await link.signAndEncryptDataForLinkedClient({
  linkedClientId: "client::partner-1",
  dataToEncrypt: "hello",
});

// Other side: decrypt + verify in one call
const { data, isValid } = await otherLink.decryptAndVerifyDataFromLinkedClient({
  linkedClientId: "client::me",
  dataToDecrypt: encryptedData,
  signatureBase64,
});
```

This is the same `ClientCryptoKeyLink` used across the stack to back the crypto identity of secure connections — including the `identityMode: "required"` provisioning described under [Security Levels](/nice-wire/security/#secure-http-needs-no-shared-memory-between-requests).

## TypeScript utilities

```ts
import type { StringKeys } from "@nice-code/util";

type Keys = StringKeys<{ a: string; b: number; 0: boolean }>;
// → "a" | "b"
```

---

# Typed Storage

Source: /nice-util/storage
Description: Fully typed, async, key-prefixed storage over any backend.

`@nice-code/util` is the quiet foundation the rest of the stack stands on: one typed storage interface over any backend (browser, Durable Object, memory), plus the WebCrypto that authenticates every secure connection. You rarely import it directly — but a realm's identity persists through it, and a secure handshake is built on it. This page is the storage half; [Crypto](/nice-util/crypto/) is the other.

```bash
bun add @nice-code/util
```

## ITypedStorage

`ITypedStorage<T>` is a typed key/value store you can put on top of any backend. Every key and value is typed, every method is async, and all your keys get a shared prefix so they don't collide with anything else.

```ts
import { createTypedWebLocalStorage } from "@nice-code/util";

interface IAppStorage {
  user_id: string;
  theme: "light" | "dark";
  recent_searches: string[];
}

const storage = createTypedWebLocalStorage<IAppStorage>({
  localStorage,
  keyPrefix: "app:",
});

// All keys autocomplete; values are typed
await storage.setJson("theme", "dark");
const theme = await storage.getJson("theme");                 // "light" | "dark" | undefined
const userId = await storage.getJsonOrDef("user_id", "guest"); // string

// Read-modify-write in one call
await storage.updateJsonWithDef("recent_searches", [], (cur) => [...cur, "query"]);

await storage.removeItem("theme");
await storage.clearAll(); // removes only keys this storage has written
```

## Adapters

```ts
import {
  createTypedWebLocalStorage,
  createTypedWebSessionStorage,
  createDurableObjectTypedStorage,
  createTypedMemoryStorage_string,
  createTypedMemoryStorage_json,
} from "@nice-code/util";

// Browser
const local = createTypedWebLocalStorage<IAppStorage>({ localStorage, keyPrefix: "app:" });
const session = createTypedWebSessionStorage<IAppStorage>({ sessionStorage });

// Cloudflare Durable Objects (inside a DO class)
const doStorage = createDurableObjectTypedStorage<IDOStorage>({
  durableObjectStorage: ctx.storage,
  keyPrefix: "do:",
});

// In-memory (testing / SSR) — string-serialized or JSON-native
const mem = createTypedMemoryStorage_string<IAppStorage>();
const memJson = createTypedMemoryStorage_json<IAppStorage>();

// Share state between instances by passing the same Map
const shared = new Map<string, string>();
const a = createTypedMemoryStorage_string<IAppStorage>({ memoryStorageMap: shared });
const b = createTypedMemoryStorage_string<IAppStorage>({ memoryStorageMap: shared });
```

## The interface

```ts
interface ITypedStorage<T extends Record<string, any>> {
  getJson<K>(key: K): Promise<T[K] | undefined>;
  getJsonOrDef<K>(key: K, defVal: T[K]): Promise<T[K]>;
  setJson<K>(key: K, val: T[K]): Promise<void>;
  updateJson<K>(key: K, updater: (cur: T[K] | undefined) => T[K]): Promise<void>;
  updateJsonWithDef<K>(key: K, defVal: T[K], updater: (cur: T[K]) => T[K]): Promise<void>;
  removeItem<K>(key: K): Promise<void>;
  clearAll(): Promise<void>;
}
```

## Wrapping your own backend

Fill in the methods interface to put typed storage on top of any backend (Redis, KV, …):

```ts
import {
  createTypedStorage,
  EStorageAdapterType,
  StorageAdapter,
  type IStorageAdapterMethods_String,
} from "@nice-code/util";

const redisMethods: IStorageAdapterMethods_String = {
  type: EStorageAdapterType.string,
  getItem: async (key) => redis.get(key),
  setItem: async (key, value) => { await redis.set(key, value); },
  removeItem: async (key) => { await redis.del(key); },
};

const storage = createTypedStorage<IMySchema>({
  storageAdapter: new StorageAdapter({ methods: redisMethods, keyPrefix: "app:" }),
});
```

You can also use the lower-level `StorageAdapter` directly (with untyped keys), including `createJsonGetterSetter<T>(key)` to get a simple `{ get, set }` pair for one key.

---

# The Connection

Source: /nice-wire/connection
Description: createWireClient — the one secure connection substrate that action, realm, and devtools all ride: identity, transports and fallback, TOFU, and the self-healing link lifecycle.

Everything in `@nice-code` that talks to another process talks over **one kind of connection**: a single secure socket with one handshake and one authenticated identity. `@nice-code/action` runs its request/response lane over it, `@nice-code/realm` rides it as a frame protocol, devtools observes it — but the connection itself is a `@nice-code/wire` concern, and `createWireClient` is how you open one directly.

You reach for `createWireClient` when a realm (or any protocol) is the only thing on the socket — a realm-only app needs `@nice-code/wire` + `@nice-code/realm` and nothing else. When the app *also* has actions, `connectChannel` opens the same connection with an action channel bound on; both are the same substrate, so a realm's `realmConnection(...)` binds to either without knowing which.

## Opening a connection

```ts title="client.ts"
import { createWireClient, wsCarrier } from "@nice-code/wire";

const client = createWireClient({
  identity: myCoordinate,        // who this client authenticates as
  peer: serverCoordinate,        // the acceptor it dials
  storage,                       // durable backing for the crypto identity (see TOFU below)
  transports: [{ carrier: wsCarrier(() => ({ url })) }],
});

await client.connect();          // dial + secure handshake — resolves when the link is live
```

`createWireClient` returns a **client handle**, not an open socket: it builds the transport chain and the crypto identity up front, and `connect()` performs the dial + handshake. It's idempotent (concurrent/repeat calls share one attempt) and rejects with `connect_exhausted` when the whole transport chain fails — a realm-only app awaits it; an app that keeps a protocol on the mux can also let the keep-alive ladder heal a first-attempt failure in the background.

The four facts every connection needs:

| Option | What it is |
|---|---|
| `identity` | This client's `RuntimeCoordinate` — its authenticated name to the peer. A realm defaults its avatar's `persistentId`/`instanceId` from it. |
| `peer` | The acceptor's coordinate — who you're dialing. |
| `storage` | A durable `StorageAdapter` backing the crypto keypair. Required for a secure connection (the default). |
| `transports` | The carriers to try, in preference order (below). |

## Transports and the fallback chain

A transport is a **carrier** plus whether it runs the secure handshake — `{ carrier, secure? }`. Carriers come from `@nice-code/wire`: `wsCarrier` (WebSocket), `rtcCarrier` (WebRTC), `inMemoryCarrier` (loopback, for tests and single-process). List several in preference order and the client prefers the first that's ready, falling through on failure:

```ts
import { createWireClient, wsCarrier } from "@nice-code/wire";

createWireClient({
  identity: myCoordinate,
  peer: serverCoordinate,
  storage,
  transports: [
    { carrier: wsCarrier(() => ({ url: primaryUrl })) },   // preferred
    { carrier: wsCarrier(() => ({ url: fallbackUrl })) },   // used only if the first is exhausted
  ],
});
```

The carrier's `createRequest` closure runs per dial, so a **dynamic endpoint** (a realm that hops lobby → match) is just a closure that reads the current target: `wsCarrier(() => ({ url: urlFor(activeMatchId) }))`. Returning `null` from it means "no valid endpoint right now" — the keep-alive ladder parks instead of dialing garbage, so tearing the target down needs no careful ordering.

A `createWireClient` connection needs a **duplex** carrier — a realm (or any mux protocol) is push-driven, and an exchange (request/reply, e.g. HTTP) carrier can't push. Exchange carriers are an action-lane concern; use them through `connectChannel`.

## Identity, storage, and security

A secure connection authenticates with a crypto identity your `storage` holds, and the peer pins it on first contact (trust-on-first-use). The one rule to internalize *here*: **`storage` must be durable** — a memory/session store regenerates the keypair each reload, so every load after the first is rejected `identity_pin_mismatch`, forever. Coordinates, the crypto handshake, the pinning rules, and how to recover a mismatch are all on **[Identity & Trust](/nice-wire/identity/)** — the page that owns them.

A **per-session** identity is fine as long as the id is minted fresh too — declare it with `ephemeralIdentity: true` to acknowledge the pairing and silence the durability warning.

Pick `authenticated` (the default) or `encrypted` with `securityLevel`; a realm reads the negotiated level off the connection and refuses to attach below its own floor. See **[Security Levels](/nice-wire/security/)**.

## The link lifecycle

Once a protocol rides the connection, the link **owns its own reconnection** — you don't re-dial on a drop:

- **Keep-alive.** An unexpected drop auto-redials with exponential backoff + jitter (≈1 s → 30 s). Default: on when the mux carries a protocol (a realm), off for a bare/plain link. `keepLinkAlive: false` opts out.
- **Half-open detection** (`linkKeepalive`). After an idle window the link sends a wire ping; no answer closes it locally, converting a silently-dead socket into the ordinary redial.
- **Link events** (`onLinkEvent`, or `client.addLinkEventListener`). `link_down`, `redial_scheduled` (attempt + delay — a truthful "reconnecting in N s"), `link_up` (with `downForMs`). A clean heal is silent at a realm's sync layer; this is where transport churn is visible.
- **Teardown.** `client.releaseLink()` stops the keep-alive and drops the link (reusable after); `client.dispose()` is the permanent stop. `client.reconnectLink()` forces an immediate re-dial (bind it to a "retry now" button).

```ts
const client = createWireClient({
  identity: myCoordinate,
  peer: serverCoordinate,
  storage,
  transports: [{ carrier: wsCarrier(() => ({ url })) }],
  keepLinkAlive: true,
  onLinkEvent: (event) => metrics.count(`link.${event.type}`),
});
```

## One substrate, three planes

The reason the connection is its own layer: **action, realm, and devtools are all protocols over the one socket**, so the resilience story — handshake, secure session, keep-alive, half-open detection, link events — is written once and every plane inherits it.

- **Realm** rides the connection as a frame protocol — `connectRealm(realm, { connection: realmConnection(client) })`. See [Connecting & React](/nice-realm/connecting/).
- **Actions** ride it as the request/response lane — `connectChannel` *is* `createWireClient` with an action channel bound on. See [Serving & Connecting](/nice-action/serving-connecting/).
- Both can share one connection: an app with actions *and* a realm opens a single `connectChannel` socket and binds the realm onto it.

## The server twin

The accepting end is the same substrate: on Cloudflare, **`serveWireDurableObject`** (from `@nice-code/wire/platform/cloudflare`) serves these connections from a Durable Object — the handshake, the DO-storage crypto identity + TOFU pins, hibernation rehydrate, and keepalive folded into one call, with protocols (a realm) registered on it directly. A realm-only DO imports wire + realm and nothing else, mirroring the client exactly. See [Serving a Realm](/nice-realm/serving/).

---

# Identity & Trust

Source: /nice-wire/identity
Description: RuntimeCoordinate names each side of a connection; a crypto identity over durable storage proves it; trust-on-first-use pins the key. The one identity model both planes gate on.

Every secure connection has two ends, and each end has a **name** and a **proof**. The name is a
`RuntimeCoordinate`; the proof is a crypto identity backed by your `storage`; and **trust-on-first-use**
(TOFU) is what ties a name to a key so the second connection can tell it's really the same peer. This
is the one identity model the whole stack rests on — action routing, realm avatars, and devtools
admission all read it.

## Coordinates — the network label

A `RuntimeCoordinate` labels a runtime environment and routes traffic to the right side. It's exported
from `@nice-code/wire` (and re-exported by `@nice-code/action`), and it lives in your shared module so
both ends reference the exact same value:

```ts
RuntimeCoordinate.env("backend");                                 // a named environment
RuntimeCoordinate.env("backend").specify({ perId: "worker-1" });  // env + a per-instance id
RuntimeCoordinate.env("backend").withPersistentId(id.toString()); // env + a persistent instance id
RuntimeCoordinate.unknown;                                        // unspecified
```

The `identity` you pass to `createWireClient` (or that an `ActionRuntime` is built from) is a
coordinate; the `peer` you dial is the other side's coordinate. A realm defaults its avatar's
`persistentId` / `instanceId` from the connection's authenticated coordinate — so "who is this
avatar?" is answered by the same handshake that authenticated the socket.

## The crypto identity lives in your storage

A secure connection authenticates with an Ed25519 keypair — a `ClientCryptoKeyLink` that
`createWireClient` builds over the `storage` you give it. That storage holds this runtime's signing
keys **and** the verify keys of peers it has met. It's why a secure connection needs `storage` and a
fully `none` connection doesn't.

The handshake runs once, before any protocol frame: each side sends its coordinate and public key, then
proves it holds the matching private key by signing a fresh, single-use challenge that binds both
nonces, both identities, the wire-dictionary version, the security level, and every key exchanged. A
replayed or tampered handshake produces a different challenge and fails. After that one exchange, every
message rides inside the already-authenticated session — no per-message crypto. (Which level of
protection that session gives — identity only, or identity + encrypted frames — is
[Security Levels](/nice-wire/security/).)

## Trust-on-first-use (TOFU)

The first time a peer sees a given identity — keyed by the coordinate's `envId` + its **persistent id**
(falling back to the per-boot instance id when none is set) — it **pins** that identity's verify key. A
later handshake presenting a *different* key for the *same* identity is rejected with
`identity_pin_mismatch`. That is what stops a third party who merely knows your id from impersonating
you: they can't produce the pinned key's signature.

`withPersistentId` is therefore a **trust decision, not just a routing name** — it tells the peer
"remember my key under this id, forever."

### Your storage must be durable — the mistake that bites

The verify key lives in `storage`. If that store is memory- or session-backed, the keypair regenerates
on every reload while the pinned id stays the same — so the **first** load works and **every load after
it is rejected**, permanently, for that identity. In a browser use `createWebLocalStorageAdapter`; on
React Native back it with AsyncStorage (see [React Native / Expo](/getting-started/react-native/));
memory adapters are for tests. `createWireClient` / `connectChannel` warn at construction when they see
a persistent id paired with a known-ephemeral store.

A **per-session** identity is perfectly fine — as long as the id is minted fresh too (a startup
`crypto.randomUUID()` as the coordinate's `perId`, with memory storage). Declare it with
`ephemeralIdentity: true` to acknowledge the pairing and silence the warning.

### Recovering from a pin mismatch

A pin mismatch is **permanent** for that identity+key pair — the keep-alive redial ladder *parks* on it
rather than retrying a handshake that can never succeed. Two things that do **not** recover it, and two
that do:

- **Does not work:** clearing only the client's *crypto* storage. A fresh key under the same persistent
  id is exactly what the pin rejects.
- **Works:** connect under a **new persistent id** (a fresh identity), *or* remove the peer-side pin via
  the verify-key resolver's storage.

A rejected handshake surfaces where `connect()` (or the first dispatch) rejects — **don't
fire-and-forget that promise.** The mismatch is typed, so an app can branch on it:

```ts
import { err_wire_connect } from "@nice-code/wire";

try {
  await client.connect();
} catch (e) {
  if (err_wire_connect.isExact(e) && e.hasId("identity_pin_mismatch")) {
    // Permanent for this identity+key pair — recover under a new persistent id,
    // or clear the peer-side pin. Retrying the same pair never succeeds.
  }
}
```

## On Cloudflare: persist the pins

A Durable Object host keeps its identity and its trusted-peer pins in DO storage (the default in
`serveWireDurableObject`). A pin that lived only in memory would re-TOFU on every hibernation wake and
defeat the protection — so on Cloudflare, persistence isn't optional. See
[Serving a Realm](/nice-realm/serving/).

## What rests on this

TOFU is not certificate-authority PKI: it's strong against an outsider who never held the key, but if
first contact happens over a hostile network, the pin is of whoever answered. That matters most for a
**realm**, whose entire authority model — every `alter` rule — rests on the avatar identity this pin
establishes. See [Realm Security](/nice-realm/security/) for the realm-layer consequences, and the
[Error Reference](/production/errors/) for branching on `identity_pin_mismatch` and its neighbours.

---

# Security Levels

Source: /nice-wire/security
Description: From self-asserted identity to fully encrypted frames — one level, picked where the connection is opened, used by both ends. The same channel works at every level.

Security is a **connection** property, chosen once where you open the link — `createWireClient` or
`connectChannel` — and used by both ends. You don't touch your channel, your realm, your handlers, or
your calls: one `ESecurityLevel`, and everything riding the socket inherits it.

There are three levels:

- **`none`** — each side just claims who it is; no verification. Fastest; fine for local dev or a
  trusted network.
- **`authenticated`** (the default) — both sides prove who they are during a handshake (sign/verify,
  plus pinning each other's key the first time they meet). Messages travel in the clear.
- **`encrypted`** — everything `authenticated` does, **plus** every message is sealed (AES-GCM) with a
  key worked out during the handshake.

```ts
createWireClient({ identity, peer, storage, securityLevel: ESecurityLevel.encrypted, transports });
// …the identical option on connectChannel / serveChannel / serveWireDurableObject.
```

## Why `authenticated` is safe even in the clear

A natural worry: if `authenticated` messages travel in the clear, what stops someone spoofing them?
Identity is proven **once, up front, in the handshake** — not per message. The client signs a fresh,
single-use challenge with its private key; the server verifies against the key it pinned for that
client on first contact (trust-on-first-use). Every later message rides inside that already-proven
session, so it's cheap (no per-message crypto) yet unspoofable by an outsider who never held the key.

The full handshake mechanics, the crypto identity your `storage` holds, and the TOFU pinning rules
(including the durable-storage requirement and how to recover an `identity_pin_mismatch`) live on
**[Identity & Trust](/nice-wire/identity/)** — the one page that owns them. What `authenticated`
deliberately does *not* give you is confidentiality: payloads are readable on the wire (you lean on TLS
for transport encryption, or step up to `encrypted` to seal each frame).

## How the level gets chosen

The dialing side picks the level it wants. By default the listening side **accepts any of the three,
per connection** — so one endpoint can serve all three. If the server persists what it learns about a
connection (a carrier that supports sleep/wake), an `authenticated` or `encrypted` connection can pick
up again after the server hibernates without redoing the handshake.

A **realm** reads the negotiated level off the connection and refuses to attach below its own required
floor — see [Realm Security](/nice-realm/security/).

## One channel works at every level

The same secure `{ carrier: wsCarrier(...) }` transport works at any level. And `httpCarrier` runs that
*same* secure session over plain HTTP (handshake → token → encrypted messages) — matching each reply to
its request comes for free, since that's how an HTTP request/response already works.

To offer a secure WebSocket with a plain HTTP fallback, give the listening side an
`httpAcceptorCarrier({ secure: false })`:

```ts title="client.ts"
connectChannel(clientRuntime, appChannel, {
  peer: serverCoord,
  storage,
  securityLevel: ESecurityLevel.encrypted,
  transports: [
    { carrier: wsCarrier(() => ({ url: wsUrl })) },                    // secure (default)
    { carrier: httpCarrier(() => ({ url: httpUrl })), secure: false }, // plain fallback
  ],
});
```

## Secure HTTP needs no shared memory between requests

Secure HTTP is **stateless**: the handshake and session details are carried inside sealed tokens
(sealed with the server's own crypto identity), so any server instance can handle any request. You
don't need a Durable Object just to keep the two POSTs of a handshake on the same instance:

```ts title="server.ts"
const server = serveChannel(runtime, appChannel, {
  storage,                          // only stores the server's crypto identity — never the sessions
  carriers: [httpAcceptorCarrier()],
  handlers: [appHandler],
});
// app.post("/action", (req) => server.fetch(req))
```

If your storage is **eventually consistent** (like Cloudflare KV, where a fresh write isn't always
readable immediately), create the identity once up front so a momentary read-miss can't accidentally
mint a second identity:

```ts
import { ClientCryptoKeyLink } from "@nice-code/util";

const link = new ClientCryptoKeyLink({ storageAdapter: storage, identityMode: "required" });
await link.provisionIdentity();   // once, out-of-band (a deploy step / first boot)

serveChannel(runtime, appChannel, { storage, link, carriers: [httpAcceptorCarrier()], handlers: [appHandler] });
```

---

# Error Reference

Source: /production/errors
Description: Every public reject/error id the library can raise — what emits it, and what to do about it.

Error ids are **API**. Every id below is stable from v1 and safe to branch on; you program against
the id, never the message string (messages are for humans and may be reworded). An error arrives as
a `NiceError` — branch on it with `err.hasId("...")`, or narrow to a domain first with
`err_domain.isExact(err)`:

```ts
// doc-check: skip — illustrative branching against ids documented below
if (err_realm.isExact(e) && e.hasId("insufficient_security")) {
  // handle the specific case
}
```

Realm rejections arrive on `onMutationRejected` (their `.error` is a `NiceError`); connection
failures reject `connect()`/dispatch; validation failures come back as a typed action result. The
tables group ids by the package that raises them.

## Realm — `err_nice_realm`

Raised by the realm engine on attach and on each write/intent. A rejection here rolled back the
optimistic effect (surfaced via `onMutationRejected`) or refused the attach (`whenLive()` rejects,
`realm.attachError` is set).

| Id | What emits it | What to do |
| --- | --- | --- |
| `schema_mismatch` | Client and server built from different realm definitions (hash mismatch). | Redeploy so both ends share one definition — this is a build-skew bug, never retried. |
| `realm_unknown` | The server hosts no realm with that id. | Fix the realm id, or serve that realm on the DO. |
| `unauthorized_avatar_type` | The avatar's `type` isn't in the realm's permitted set. | Connect as a permitted avatar type. |
| `avatar_unresolved` | The connection's identity mapped to no avatar (`resolveAvatar` returned nothing). | Ensure the connection carries an authenticated coordinate, or set `avatarType`. |
| `insufficient_security` | The connection's negotiated wire level is below the realm's minimum. | Raise the connection's `securityLevel` (e.g. `encrypted`). Fail-closed by design. |
| `unauthorized_coordinate` | A write targets a path this avatar's rules forbid. | Expected on a rules violation — reflect it in UI; don't retry blindly. |
| `value_invalid` | A written value doesn't match the schema. | Fix the value shape; this is a program error. |
| `limits_exceeded` | An ingress limit was hit (frame bytes / patches / write rate). | The client coalescer usually splits automatically; a bare breach means back off. |
| `intent_unknown` | An intent name the realm doesn't define. | Fix the intent name (it's part of the schema hash). |
| `version_gap_unrecoverable` | The client's version is behind the replayable window. | Automatic — the client full-rehydrates; no app action. |
| `write_before_hydrate` | `realm.update()` ran before the first hydrate (store still `{}`). | `await realm.whenLive()` first, or use `assertOnAttach` for state that must exist on attach. |
| `frame_too_stale` | An optimistic frame expired before an authoritative answer — an **unknown** outcome. | **Re-read state; do not blindly re-issue a non-idempotent intent** (it may have committed). Detect with `isUnknownOutcomeRejection`. |
| `durable_backlog_overflow` | Too many unconfirmed `durability: "reassert"` frames (a long outage). | Re-sync from your own source of truth after reconnecting. |
| `frame_invalid` | A malformed/hostile realm frame (fuzz gate). | Not app-actionable — the codec dropped it. Investigate a buggy/hostile peer. |
| `write_target_missing` | A well-formed write whose target's parent no longer exists (a pruned entry / a transient region reset by a wake). | Re-read state; an `assertOnAttach` re-creates a pruned own-entry. Distinct from `frame_invalid`. |

## Connection — `err_nice_wire_connect`

Raised while opening or maintaining a wire connection (`createWireClient` / `connectChannel`).

| Id | What emits it | What to do |
| --- | --- | --- |
| `connect_exhausted` | Every transport in the preference chain failed. | Check the endpoints/network; the keep-alive ladder retries a duplex link. |
| `connect_closed` | `connect()` on a client already `close()`d — terminal. | Build a new client; a closed one never reconnects. |
| `dial_failed` | One transport's dial or handshake failed (a chain-item detail inside `connect_exhausted`). | Read `reason`; usually a bad URL or an unreachable host. |
| `dial_unavailable` | The carrier has **no valid endpoint right now** (`createRequest` returned `null`). | A policy signal, not a failure — the keep-alive loop **parks** until the next explicit `connect()`/dispatch. |
| `protocol_unsupported` | A protocol frame sent on a connection whose peer never advertised it. | Register the protocol before the handshake (dial with the realm/devtools mux attached). |
| `protocol_on_exchange_only` | A prefixed protocol registered on an exchange-only (request/reply) connection. | Thrown at **bring-up**, not connect — a protocol needs a duplex carrier (a realm can't ride HTTP-exchange alone). |
| `protocol_security_blocked` | A protocol frame on a non-authenticated connection that didn't opt into `allowPlain`. | Raise the connection's security level, or the protocol must opt in (devtools does). |
| `binding_version_mismatch` | A rehydrated hibernation binding has an unknown schema version. | Automatic — the socket is treated as fresh and re-handshakes. |
| `identity_pin_mismatch` | The peer rejected the handshake: this client's verify key ≠ the one pinned for its identity (TOFU). | **Permanent** for this identity+key pair — the redial loop **parks**. Recover under a new persistent id, or clear the peer-side pin. Branch with `err.hasId("identity_pin_mismatch")`. |

## Actions — `err_nice_action`, `err_nice_transport`, `err_nice_transport_ws`

Raised by the action runtime and its transport. Most are program errors (wiring/registration); the
validation + reliability ids are the ones a consumer branches on.

**`err_nice_action`** — runtime & registration: `not_implemented`, `action_id_not_in_domain`,
`domain_already_exists_in_hierarchy`, `domain_no_handler`, `hydration_domain_mismatch`,
`hydration_action_state_mismatch`, `hydration_action_id_not_found`, `no_action_execution_handler`,
`wire_action_not_payload`, `wire_not_action_data`, `client_runtime_already_registered`,
`client_runtime_not_registered`, `runtime_reset`, `no_client_runtimes_registered`. The four you'll
branch on: **`action_input_validation_failed`** / **`action_output_validation_failed`** (a schema
check failed — HTTP 400/500; fix the payload) and their `*_promise` variants (a validator returned a
promise, which isn't supported — make it synchronous).

**`err_nice_transport`** — dispatch & reliable delivery: `timeout`, `not_found`, `unsupported`,
`initialization_failed`, `send_failed`, `invalid_action_response`, and the reliable-tier trio you
branch on — **`reliable_outbox_overflow`** (the peer isn't acknowledging; the send was rejected to
bound memory — reconnect/re-sync), **`reliable_delivery_abandoned`** (not acked within its deadline;
the stream skipped past it), **`reliable_stream_closed`** (the stream was closed while a send was
unacked).

**`err_nice_transport_ws`** — WebSocket carrier: `ws_disconnected`, `ws_create_failed`, `ws_error`
(transport-level, usually surfaced through the connection's reconnect handling).

## Validation — `err_validation` (`@nice-code/common-errors`)

| Id | What emits it | What to do |
| --- | --- | --- |
| `standard_schema` | A Standard-Schema validation failed (the `/hono` adapter, action input/output). | HTTP 400 — the message carries the field issues; fix the payload. |

## Branching helpers

- `err.hasId("id")` — the primary check; true when the error carries that id anywhere in its domain
  chain.
- `err_domain.isExact(err)` — narrow to a domain (`err_realm`, `err_wire_connect`, …) before reading
  its ids, re-exported from the owning package (`err_realm` + `isUnknownOutcomeRejection` from
  `@nice-code/realm`).
- `isUnknownOutcomeRejection(rejection)` — the realm helper for the one case that is genuinely
  ambiguous (`frame_too_stale`): treat it as "outcome unknown, re-read", never as a definite reject.

---

# Production Posture

Source: /production/posture
Description: A one-screen pre-flight checklist for shipping — each item one line, linked to the module page that owns the detail.

A short pre-flight before you ship. Each item is one line and a link to the page that owns the full
story — this page is the map, not the manual.

## Connection & identity

- **Use a durable `storage` on every secure connection.** A memory-backed store re-mints the crypto
  identity each load and gets pinned-out after the first — permanently. → [Identity & Trust](/nice-wire/identity/#your-storage-must-be-durable--the-mistake-that-bites)
- **Know how to recover an `identity_pin_mismatch`.** It's permanent for that id+key pair; recover under
  a new persistent id or clear the peer-side pin. → [Identity & Trust](/nice-wire/identity/#recovering-from-a-pin-mismatch)
- **On Cloudflare, persist the TOFU pins** (the `serveWireDurableObject` default) so a hibernation wake
  doesn't re-TOFU. → [Identity & Trust](/nice-wire/identity/#on-cloudflare-persist-the-pins)
- **Pick a security level deliberately.** `authenticated` is the floor; use `encrypted` for anything
  sensitive on the wire. → [Security Levels](/nice-wire/security/)

## Realm state

- **Bound your state cardinality.** The engine caps each frame and write, not the total tree — cap
  growing records (rosters, logs) with a rule. → [Limits & Production](/nice-realm/limits/)
- **Prefer transient / ephemeral for presence-shaped state**, so it never persists and cold-starts
  empty. → [Limits & Production](/nice-realm/limits/#keep-it-cheap-transient-and-ephemeral)
- **Mind at-rest storage.** `encrypted` seals the wire, not the DO's SQLite — keep secrets out of
  persisted state, and out of rejection errors. → [Realm Security](/nice-realm/security/#caveats-worth-internalizing)

## Observation & exposure

- **The library logs no payload content by default.** Nothing about a write's values, an action's
  input, or a realm's state leaves the process on its own. Any observation you turn on can surface user
  data — scope `wireTap` to an allow-list, not whole frames.
- **Devtools are inert in production, fail-closed.** The handles disable when `NODE_ENV === "production"`
  (or `stage: "production"` on a DO), the token never lives in the app bundle, and no endpoint is
  registered — shipping a build with devtools wired costs nothing. → [The Devtools Window → in production](/devtools/window/#devtools-in-production)

## Versioning & errors

- **Upgrade every `@nice-code/*` package in lockstep**, and lean on the wire-format skew promise to
  deploy without a flag-day. → [Stability & Versioning](/production/stability/)
- **Program against error *ids*, never messages.** Every id the stack can raise, with what to do about
  it. → [Error Reference](/production/errors/)

---

# Stability & Versioning

Source: /production/stability
Description: What versioning guarantees this library gives your app today, the wire-format skew promise across deploys, and the capabilities that are deliberately out of scope by design.

This page is the contract between the library and your app: how versions move, what stays stable
while we are pre-1.0, how a deployed server and older clients keep working across an upgrade, and
which capabilities are deliberately *not* here.

## Where this release sits

The public surface — the connection model, the realm and action APIs, the error vocabulary, the five
wire formats — is the **intended final form**. It is what every guide on this site is written
against.

We are still on the **`0.x` line**, on purpose. The shape is settled, but staying pre-1.0 keeps the
freedom to refine a rough edge in a minor release before committing to the stricter `1.0` guarantee
below. Read `0.x` as *"stable enough to build on, not yet frozen."*

## Versioning

Every `@nice-code/*` package releases **in lockstep at one version** — `@nice-code/wire`,
`@nice-code/realm`, `@nice-code/action` and the rest always share a version number. **Upgrade them
together;** mixing versions across the set is unsupported.

We follow [semver](https://semver.org/), read against where we are:

**While `0.x` (now):**

- **`0.MINOR.0`** may contain a breaking change. When it does, it ships with a changelog entry and a
  migration note — a breaking change is never silent.
- **`0.x.PATCH`** is fixes only, no surface change.

**From `1.0.0` onward** (a later, separate release):

- Breaking changes only in a **major**, always with migration docs.
- **Minors are additive; patches are fixes** — the ordinary semver promise.

The move to `1.0.0` will be its own announcement, made once the `0.x` surface has soaked with real
consumers. Nothing on this page changes silently underneath you before then.

## The wire-format skew promise

Realms and actions run over five wire formats (the handshake, the mux, control frames, the HTTP
exchange, and the per-domain codecs). **A deployed server and the clients already in the field are
rarely on the same version** — a browser tab left open for a week, a mobile app a user hasn't
updated. That skew is designed for, and the promise holds **now, at `0.x`**, not only from `1.0`:

- Every format **grows additively** — a new realm frame *kind*, a new capability token negotiated in
  the handshake, a new optional field — never by changing the meaning of an existing byte.
- A peer that meets something it doesn't recognise **drops it and carries on**; an unknown addition
  is never fatal.
- So a client and a server **a release apart interoperate**: the newer side's additions are invisible
  to the older side, and the older side keeps working.

In practice: **you can deploy your server and let old clients reconnect without a coordinated
flag-day.** Newer features simply light up as clients catch up.

## Upgrading, in practice

1. Bump every `@nice-code/*` dependency to the new version together.
2. Read the changelog for that minor — in a `0.x` minor, a breaking change (if any) is called out
   there with its migration note.
3. Deploy the server and the client independently; the skew promise above covers the window where
   they differ.

## Deliberately out of scope

Some capabilities are **not** in this release **by design**, not by omission. Each is a boundary held
on purpose — folding it into the core would tax every consumer for a need most don't have:

- **Per-message priorities and TTLs** in the core send path.
- **Exactly-once *effects*** baked into the core. (The primitives to build idempotent handling are
  there — the delivery guides show the pattern — but the core does not silently promise
  effect-once for you.)
- **Causal ordering across independent actions.**
- **Reliable `broadcast`** as a core guarantee.
- **Per-message delivery knobs** on the core API.

Where a real need for one of these appears, it lands through an **additive** seam — a new option, a
caps-gated protocol addition — that doesn't break the code you write today. That is the whole point
of the skew promise above: the library can grow into these without a breaking release.