@nice-code/action 0.17.0 → 0.18.0

package/README.md

@@ -1,582 +1,637 @@
-# @nice-code/action
-
-Typed, transport-agnostic action system for calling functions across client/server boundaries with full TypeScript inference.
-
-## Install
-
-```bash
-bun add @nice-code/action
-```
-
-Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schema/standard-schema) library), `@tanstack/react-query` (for `@nice-code/action/react-query`).
-
-## Core concepts
-
-- **ActionDomain** — a named group of typed actions (like an API surface)
-- **ActionSchema** — input/output schema + declared error types for one action
-- **ActionRuntime** — one per client; processes incoming requests and dispatches them to handlers. Wire each backend it talks to with `runtime.connectTo(...)`
-- **ActionLocalHandler** — executes actions in the current process
-- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket to another client
-- **ActionServerHandler** — server-side handler for backends accepting many client connections over one open channel; ferries results back and can push/broadcast server-initiated actions to clients
-- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…) and is how actions are routed
-
-> **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime` identifying it across every peer it talks to — not one per feature or per backend. Register your local handlers on it, then call `runtime.connectTo(peerCoordinate, { transports, domains })` once per peer to wire the outbound channels. This keeps one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
-
----
-
-## Defining actions
-
-### 1. Create a root domain (shared between client and server)
-
-```ts
-import { createActionRootDomain, actionSchema } from "@nice-code/action";
-import * as v from "valibot";
-
-// Root domain — no actions, just a namespace anchor
-export const appRoot = createActionRootDomain({ domain: "app_root" });
-
-// Child domain with actions
-export const userDomain = appRoot.createChildDomain({
-  domain: "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"]),  // from @nice-code/error
-
-    updateName: actionSchema()
-      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
-      .output({ schema: v.object({ success: v.boolean() }) }),
-  },
-});
-```
-
-### 2. Serialization for non-JSON-native types
-
-```ts
-createAt: actionSchema()
-  .output(
-    { schema: v.object({ createdAt: v.date() }) },
-    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }),  // serialize
-    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),       // deserialize
-  ),
-```
-
-### 3. Declare thrown errors
-
-```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 },
-    }),
-  },
-} as const);
-
-// Attach to an action schema
-actionSchema()
-  .throws(err_user)                        // any id from err_user
-  .throws(err_user, ["not_found"])          // only specific ids
-```
-
----
-
-## Setting up runtimes
-
-### Server (local handler)
-
-```ts
-import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
-
-// Identify this environment
-export const serverCoord = RuntimeCoordinate.env("backend");
-
-// Implement the actions
-const userHandler = createLocalHandler()
-  .forDomain(userDomain, async (request) => {
-    if (request.id === "getUser") {
-      const user = await db.users.find(request.input.userId);
-      if (!user) throw err_user.fromId("not_found", { userId: request.input.userId });
-      return user;
-    }
-  });
-
-// Or use the map syntax (preferred)
-const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
-  getUser: async (req) => {
-    const user = await db.users.find(req.input.userId);
-    if (!user) throw err_user.fromId("not_found", { userId: req.input.userId });
-    return user;
-  },
-  updateName: async (req) => {
-    await db.users.update(req.input.userId, { name: req.input.name });
-    return { success: true };
-  },
-});
-
-// Or wrap an object directly
-const userHandler = userDomain.wrapAsLocalHandler({
-  getUser: async ({ userId }) => { /* ... */ },
-  updateName: async ({ userId, name }) => { /* ... */ },
-});
-
-// Wire up the runtime
-export const serverRuntime = new ActionRuntime(serverCoord)
-  .addHandlers([userHandler])
-  .apply();
-```
-
-### Handling incoming requests (HTTP endpoint)
-
-```ts
-// Hono example
-app.post("/resolve_action", async (c) => {
-  const wire = await c.req.json();
-  const runningAction = await serverRuntime.handleActionPayloadWire(wire);
-  const result = await runningAction.waitForResultPayload();
-  return c.json(result.toJsonObject());
-});
-```
-
-Or fold the whole endpoint (CORS + preflight, the `/action` POST, an optional WebSocket upgrade, and a
-404 fallback) into one web-standard `fetch` handler with `createActionFetchHandler`:
-
-```ts
-import { createActionFetchHandler } from "@nice-code/action";
-
-// Works anywhere Request/Response exist (Workers, Durable Objects, Bun, …).
-const fetchHandler = createActionFetchHandler(serverRuntime, {
-  // Omit for an HTTP-only endpoint. For a Durable Object:
-  onWebSocketUpgrade: () => {
-    const pair = new WebSocketPair();
-    ctx.acceptWebSocket(pair[1]);
-    return new Response(null, { status: 101, webSocket: pair[0] });
-  },
-});
-
-// async fetch(request) { return fetchHandler(request); }
-```
-
-By default a `POST` whose path ends in `/action` carries an action wire, and an `Upgrade: websocket`
-request whose path ends in `/ws` is upgraded; override with `isActionPath` / `isWebSocketPath`.
-
-### Client (connecting to a backend)
-
-A client has one runtime. Call `connectTo` once per backend it talks to: it builds the
-`ActionExternalClientHandler`, routes the listed `domains`/`actions` to it, registers it, and applies —
-all in one call.
-
-```ts
-import { ActionRuntime, RuntimeCoordinate, HttpTransport } from "@nice-code/action";
-
-export const clientCoord = RuntimeCoordinate.env("frontend");
-export const serverCoord = RuntimeCoordinate.env("backend");
-
-// The single runtime that identifies this client everywhere.
-export const clientRuntime = new ActionRuntime(clientCoord);
-
-// Transport definitions are plain, reusable objects you construct once.
-const serverHttp = HttpTransport.create({
-  createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
-});
-
-// Wire the backend — route the userDomain's actions over this transport.
-clientRuntime.connectTo(serverCoord, {
-  transports: [serverHttp],
-  domains: [userDomain],
-});
-
-// Connect to more backends on the same runtime as needed:
-// clientRuntime.connectTo(authCoord, { transports: [authWs], domains: [authDomain] });
-```
-
-`connectTo(peerCoordinate, options)` accepts:
-
-- `transports` — one or more transports, tried in declared order (first = preferred, e.g. a WebSocket; later = fallback, e.g. HTTP)
-- `domains` / `actions` — which domains (or individual actions) route to this peer
-- `localHandlers` — handlers that run *locally* on this same channel, e.g. to answer **server→client pushes** (see [Bi-directional communication](#bi-directional-communication-server--client))
-- `defaultTimeout` — default per-action timeout
-
-It returns the `ActionExternalClientHandler` so you can later `handler.clearTransportCache()` (which also
-closes any live sockets) on teardown.
-
-<details>
-<summary>What <code>connectTo</code> desugars to</summary>
-
-```ts
-const serverHandler = new ActionExternalClientHandler({
-  runtimeCoordinate: serverCoord,
-  transports: [serverHttp],
-}).forDomain(userDomain);
-
-clientRuntime.addHandlers([serverHandler]).apply();
-```
-</details>
-
----
-
-## Calling actions
-
-```ts
-// Create a request payload
-const request = userDomain.action.getUser.request({ userId: "u_123" });
-
-// Run it — returns a RunningAction
-const runningAction = await userDomain.runAction(request);
-
-// Wait for the result
-const result = await runningAction.waitForResultPayload();
-console.log(result.output); // { id: "u_123", name: "Alice" }
-
-// Or run and get the output directly (throws on error)
-const output = await userDomain.action.getUser
-  .request({ userId: "u_123" })
-  .runToOutput();
-```
-
----
-
-## Bi-directional communication (server ⇆ client)
-
-Actions flow both ways. The frontend calls the backend the way shown above; the **backend can call the
-frontend** over the *same* open connection — no second channel, no polling. This needs a duplex transport
-(a WebSocket), so both ends share one channel.
-
-The shape:
-
-- **Define the client-facing actions in their own domain**, shared by both ends (same as any other domain).
-- **On the client**, register a *local handler* for those actions and route them as `localHandlers` on the
-  `connectTo` channel — so when the server pushes a request, the client executes it locally and the result
-  is sent straight back over the same socket.
-- **On the server**, use an `ActionServerHandler` (one per connection-accepting channel). It ferries
-  results back to the originating socket automatically, and gives you `pushToClient` / `broadcast` to
-  initiate actions toward connected clients.
-
-### Shared domains
-
-```ts
-// Client implements these — the server pushes them.
-export const clientPushDomain = appRoot.createChildDomain({
-  domain: "client_push",
-  actions: {
-    notify: actionSchema()
-      .input({ schema: v.object({ text: v.string() }) })
-      .output({ schema: v.object({ seen: v.boolean() }) }),
-  },
-});
-
-// Server implements these — the client calls them (normal direction).
-export const gameDomain = appRoot.createChildDomain({
-  domain: "game",
-  actions: {
-    join: actionSchema()
-      .input({ schema: v.object({ roomId: v.string() }) })
-      .output({ schema: v.object({ ok: v.boolean() }) }),
-  },
-});
-```
-
-### Server side
-
-```ts
-import {
-  ActionRuntime,
-  RuntimeCoordinate,
-  createServerHandler,
-} from "@nice-code/action";
-
-const backendCoord = RuntimeCoordinate.env("backend");
-const clientEnv = RuntimeCoordinate.env("frontend"); // the env of connecting clients
-
-const serverRuntime = new ActionRuntime(backendCoord);
-
-// Handles inbound client→server actions locally.
-const gameHandler = gameDomain.wrapAsLocalHandler({
-  join: async ({ roomId }) => ({ ok: true }),
-});
-
-// Accepts many client connections over one channel; you tell it how to send a frame.
-const serverHandler = createServerHandler<WebSocket>({
-  clientEnv,
-  formatMessage: adapter, // e.g. createBinaryWireAdapter([gameDomain, clientPushDomain])
-  send: (ws, frame) => ws.send(frame),
-  runtime: serverRuntime, // lets broadcast() find the runtime without threading it through
-});
-
-serverRuntime.addHandlers([gameHandler, serverHandler]).apply();
-
-// Per inbound socket message (e.g. a Durable Object's webSocketMessage):
-//   serverHandler.receive(ws, message);
-// On close/error:
-//   serverHandler.dropConnection(ws);
-```
-
-Push a server-initiated action to a specific client (await its reply just like any action), or fan one
-out to everyone:
-
-```ts
-// One client — pass the connection token or the client's RuntimeCoordinate.
-const running = serverHandler.pushToClient(
-  serverRuntime,
-  ws,
-  clientPushDomain.action.notify.request({ text: "hi" }),
-);
-const result = await running.waitForResultPayload();
-console.log(result.output); // { seen: true }
-
-// Everyone currently connected (fire-and-forget); skip the origin, or filter with `where`.
-serverHandler.broadcast(() => clientPushDomain.action.notify.request({ text: "room update" }), {
-  except: originWs,
-  where: (ws) => ws.deserializeAttachment()?.role === "player",
-});
-```
-
-When an inbound client action needs the originating socket (to reply on it, register it in a room, etc.),
-use `forConnectionDomainCases` — each case receives the request *and* that client's live connection,
-saving the manual `getConnectionForClient(action.context.originClient)` lookup:
-
-```ts
-const gameCases = serverHandler.forConnectionDomainCases(gameDomain, {
-  join: ({ input }, conn) => {
-    if (conn != null) rooms.add(input.roomId, conn);
-    return { ok: conn != null };
-  },
-});
-
-serverRuntime.addHandlers([gameCases, serverHandler]).apply();
-```
-
-### Client side
-
-The client registers a local handler for the pushed actions and hands it to `connectTo` as a
-`localHandler` on the WebSocket channel. Results route back over the same socket automatically.
-
-```ts
-const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
-
-// Execute server→client pushes locally.
-const pushHandler = clientPushDomain.wrapAsLocalHandler({
-  notify: async ({ text }) => {
-    showToast(text);
-    return { seen: true };
-  },
-});
-
-clientRuntime.connectTo(backendCoord, {
-  transports: [gameWs], // a WebSocketTransport (duplex)
-  domains: [gameDomain], // client→server actions routed out over this socket
-  localHandlers: [pushHandler], // server→client pushes handled locally on the same socket
-});
-```
-
-### Durable Objects / hibernation
-
-For transports whose sockets outlive process eviction (e.g. a Durable Object's hibernatable
-WebSockets), pair the server handler with `createHibernatableWsServerAdapter`. It owns persistence:
-it stores each connection's binding on bind and replays them on construction, so results and pushes
-still route to the right socket after the object wakes.
-
-```ts
-import { createHibernatableWsServerAdapter } from "@nice-code/action";
-
-const wsServer = createHibernatableWsServerAdapter({
-  handler: serverHandler,
-  getConnections: () => ctx.getWebSockets(),
-  getAttachment: (ws) => ws.deserializeAttachment(),
-  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
-});
-
-// webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
-// webSocketClose/Error(ws) => wsServer.drop(ws);
-```
-
----
-
-## React Query integration
-
-```ts
-import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";
-
-// Query
-function UserProfile({ userId }: { userId: string }) {
-  const { data } = useActionQuery(
-    userDomain.action.getUser,
-    { userId },
-    { queryKey: ["user", userId] },
-  );
-  return <div>{data?.name}</div>;
-}
-
-// Mutation
-function RenameUser() {
-  const { mutate } = useActionMutation(userDomain.action.updateName);
-  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
-}
-```
-
----
-
-## Devtools
-
-### Browser panel — `@nice-code/action/devtools/browser`
-
-A dockable in-app panel showing every action run: status, timing, input/output, routing, errors, and call stacks. Renders only when `NODE_ENV === "development"` (or with `forceEnable`).
-
-```tsx
-import { ActionDevtoolsCore, NiceActionDevtools } from "@nice-code/action/devtools/browser";
-
-const devtoolsCore = new ActionDevtoolsCore();
-devtoolsCore.attachToDomain(appRoot);
-
-function App() {
-  return (
-    <>
-      <MyApp />
-      <NiceActionDevtools core={devtoolsCore} position="dock-bottom" />
-    </>
-  );
-}
-```
-
-### Server logger — `@nice-code/action/devtools/server`
-
-Logs action lifecycle (started / progress / success / error) with timings — pretty lines or newline-delimited JSON.
-
-```ts
-import { ActionServerDevtools } from "@nice-code/action/devtools/server";
-
-const devtools = new ActionServerDevtools({ format: "json", logPayloads: false });
-devtools.attachToDomain(appRoot);
-```
-
----
-
-## WebSocket transport
-
-```ts
-import { ActionRuntime, WebSocketTransport, HttpTransport } from "@nice-code/action";
-
-const serverWs = WebSocketTransport.create({
-  createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
-  getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
-});
-
-// One channel, WebSocket preferred with HTTP as fallback.
-clientRuntime.connectTo(serverCoord, {
-  transports: [serverWs, serverHttp],
-  domains: [userDomain],
-});
-```
-
-The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
-transports can be registered; the runtime picks the best available one (WebSocket preferred for lower
-latency, HTTP as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
-
-Each transport takes a single creation function so you decide how simple or complex it should be —
-derive the request per action straight from the params (e.g.
-`HttpTransport.create({ createRequest: (input) => ({ url: \`/api/${input.action.id}\` }) })`). For full
-control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
-offer `.createAdvanced({ getTransport })`.
-
-A WebSocket is duplex, so it's also the channel the server pushes back over — see
-[Bi-directional communication](#bi-directional-communication-server--client).
-
-### Secure WebSocket channel
-
-For an authenticated (and optionally end-to-end encrypted) socket, define the channel once in shared
-code and hand it to both ends — the binary codec and wire-dictionary version can never drift apart. The
-client identifies itself with its runtime coordinate + a persisted crypto identity; the server pins
-client keys trust-on-first-use.
-
-```ts
-// shared.ts — both ends import this
-import { defineSecureWsChannel } from "@nice-code/action";
-
-// Domains in a stable order (the binary wire dictionary is positional — add new ones to the end).
-export const channel = defineSecureWsChannel({ domains: [userDomain, clientPushDomain] });
-```
-
-```ts
-// client.ts
-import { createSecureWebSocketTransport, ESecurityLevel } from "@nice-code/action";
-
-const secureWs = createSecureWebSocketTransport({
-  channel,
-  runtime: clientRuntime, // its coordinate is the authenticated identity in the handshake
-  storageAdapter, // persists this client's verify key across reloads (@nice-code/util)
-  securityLevel: ESecurityLevel.encrypted, // none | authenticated | encrypted
-  url: "wss://api.example.com/meta/ws",
-});
-
-clientRuntime.connectTo(serverCoord, {
-  transports: [secureWs, serverHttp], // secure WS preferred, HTTP fallback
-  domains: [userDomain],
-  localHandlers: [pushHandler], // server pushes ride the same secure socket
-});
-```
-
-```ts
-// server.ts (e.g. inside a Durable Object)
-import {
-  createSecureActionServerHandler,
-  createHibernatableWsServerAdapter,
-} from "@nice-code/action";
-
-const serverHandler = createSecureActionServerHandler<WebSocket>({
-  channel, // same shared channel
-  clientEnv, // env of the connecting clients
-  runtime: serverRuntime, // its coordinate is the server identity in the handshake
-  storageAdapter, // backs BOTH the server's identity and its TOFU key pins — use persistent storage
-  send: (ws, frame) => ws.send(frame),
-  // securityLevel defaults to negotiating any of none / authenticated / encrypted per connection
-});
-
-const wsServer = createHibernatableWsServerAdapter({
-  handler: serverHandler,
-  getConnections: () => ctx.getWebSockets(),
-  getAttachment: (ws) => ws.deserializeAttachment(),
-  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
-});
-```
-
-Security levels: `none` (self-asserted identity, fine for dev/trusted networks), `authenticated`
-(handshake-verified identity), `encrypted` (authenticated + per-connection AES-GCM payload encryption).
-A server can accept a negotiable set so a single endpoint serves all three. Persisting the channel's
-binding (via the hibernatable adapter) lets an `authenticated`/`encrypted` connection resume after the
-server is evicted without re-handshaking.
-
----
-
-## RuntimeCoordinate
-
-Identifies a runtime environment and is used to route actions to the right handler.
-
-```ts
-RuntimeCoordinate.env("backend")                   // named env
-RuntimeCoordinate.env("backend").specify({ perId: "worker-1" }) // env + instance
-RuntimeCoordinate.unknown                           // unspecified
-```
-
----
-
-## Error handling in actions
-
-Actions declared with `.throws(domain, ids?)` surface typed errors at the call site:
-
-```ts
-import { castNiceError } from "@nice-code/error";
-
-try {
-  const output = await userDomain.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);
-  }
-}
-```
+# @nice-code/action
+
+Typed, transport-agnostic action system for calling functions across runtime boundaries (client/server,
+worker/worker, peer/peer) with full TypeScript inference — including **bi-directional** calls where the
+acceptor pushes actions back over the same connection.
+
+## Install
+
+```bash
+bun add @nice-code/action
+```
+
+Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schema/standard-schema) library), `@tanstack/react-query` (for `@nice-code/action/react-query`).
+
+---
+
+## Mental model
+
+One sentence: **a `runtime` links to a `peer` over a `carrier`, and the routing between them is declared
+once as a `channel`.** Identity, auth, and encryption work the same regardless of carrier — the only
+distinctions that survive every carrier are:
+
+- **role** — who dials (**connector**) vs who accepts and can push back (**acceptor**).
+- **shape** — **duplex** (a WebSocket / WebRTC channel: push-capable, the return path for results and
+  server pushes) vs **exchange** (HTTP: one request, one reply).
+
+The pieces:
+
+| Concept | What it is |
+| --- | --- |
+| **ActionDomain** | A named group of typed actions (your API surface) |
+| **ActionSchema** | Input/output schema + declared error types for one action |
+| **ActionRuntime** | One per runtime; identifies it and dispatches actions to handlers |
+| **Channel** | The transport-agnostic routing contract between two runtimes, declared *by role* (`toAcceptor` / `toConnector`) — `defineChannel` (plain) or `defineSecureChannel` (binary + encryption) |
+| **Carrier** | How bytes actually move: `wsCarrier` / `httpCarrier` / `inMemoryCarrier` / `rtcCarrier` (connector side), `wsAcceptorCarrier` / `httpAcceptorCarrier` (acceptor side) |
+| **Transport** | A carrier wrapped with a security policy: `secureTransport` (handshake + optional encryption) or `plainTransport` |
+| **RuntimeCoordinate** | Identifies an environment (frontend, backend, worker…) and is how actions are routed |
+
+> **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime`
+> identifying it across every peer it talks to — not one per feature or per backend. Register your local
+> handlers on it, then `connectChannel(...)` once per peer (or `serveChannel(...)` to accept). This keeps
+> one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
+
+The high-level entry points — `connectChannel` (dial out) and `serveChannel` (accept) — are what you
+reach for 95% of the time. The lower-level handler/carrier/transport objects they desugar to are
+documented at the end under [Lower-level building blocks](#lower-level-building-blocks).
+
+---
+
+## Defining actions
+
+### 1. Create a root domain (shared between both ends)
+
+```ts
+import { createActionRootDomain, actionSchema } from "@nice-code/action";
+import * as v from "valibot";
+
+// Root domain — no actions, just a namespace anchor
+export const appRoot = createActionRootDomain({ domain: "app_root" });
+
+// Child domain with actions
+export const userDomain = appRoot.createChildDomain({
+  domain: "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"]),  // from @nice-code/error
+
+    updateName: actionSchema()
+      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
+      .output({ schema: v.object({ success: v.boolean() }) }),
+  },
+});
+```
+
+### 2. Serialization for non-JSON-native types
+
+```ts
+createAt: actionSchema()
+  .output(
+    { schema: v.object({ createdAt: v.date() }) },
+    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }),  // serialize
+    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),       // deserialize
+  ),
+```
+
+### 3. Declare thrown errors
+
+```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 },
+    }),
+  },
+} as const);
+
+// Attach to an action schema
+actionSchema()
+  .throws(err_user)                        // any id from err_user
+  .throws(err_user, ["not_found"])          // only specific ids
+```
+
+---
+
+## Channels — the routing contract
+
+A **channel** declares what flows in each direction between two runtimes, *by role*, so both ends derive
+their routing from one shared definition instead of restating domain lists:
+
+- **`toAcceptor`** — domains the connector *sends to* the acceptor (the classic "request").
+- **`toConnector`** — domains the acceptor *pushes back to* the connector (the classic "push"). A domain
+  can appear in both lists if it's bidirectional.
+
+Define it once in code shared by both ends:
+
+```ts
+// shared.ts — both ends import this
+import { defineChannel } from "@nice-code/action";
+
+export const appChannel = defineChannel({
+  toAcceptor: [userDomain],   // client → server requests
+  toConnector: [],            // server → client pushes (none here)
+});
+```
+
+For an authenticated/encrypted binary WebSocket, use **`defineSecureChannel`** instead — same role-based
+shape, plus it bakes in the positional binary wire dictionary and a version derived from the domains, so
+the codec and version can never drift between the two ends:
+
+```ts
+import { defineSecureChannel } from "@nice-code/action";
+
+export const appChannel = defineSecureChannel({
+  toAcceptor: [userDomain, lobbyDomain],  // requests
+  toConnector: [lobbyDomain],             // pushes (lobbyDomain is bidirectional)
+});
+```
+
+> The lists are **positional** for the binary wire dictionary — **add new domains to the end** of their
+> list. Reordering shifts the version, and a stale peer is then cleanly rejected by the handshake instead
+> of silently misrouting a frame.
+
+A secure channel is still an ordinary channel, so it works anywhere a channel is expected.
+
+---
+
+## Runtimes & handlers
+
+### Local execution (the acceptor's actual work)
+
+A **local handler** runs actions in the current process. Build one and register it on the runtime; this
+is what answers incoming requests.
+
+```ts
+import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
+
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+// Map syntax (preferred)
+const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
+  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 };
+  },
+});
+
+// Or one action at a time
+const userHandler2 = createLocalHandler()
+  .forAction(userDomain.action.getUser, async ({ input }) => db.users.find(input.userId));
+
+// Or wrap an object directly off the domain
+const userHandler3 = userDomain.wrapAsLocalHandler({
+  getUser: async ({ userId }) => { /* ... */ },
+  updateName: async ({ userId, name }) => { /* ... */ },
+});
+```
+
+`wrapAsPartialLocalHandler` is the same but lets you implement only *some* of a domain's actions (useful
+for local-first clients that resolve a few actions themselves and forward the rest).
+
+### Accepting connections — `serveChannel`
+
+`serveChannel` is the one call that stands up an acceptor: it builds the crypto identity **once**, fans it
+across every carrier, registers your handlers, wires hibernation, and returns a server object whose
+`fetch` / `duplex` / `pushToClient` you forward straight to the host.
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  serveChannel,
+  wsAcceptorCarrier,
+  httpAcceptorCarrier,
+} from "@nice-code/action";
+
+const runtime = new ActionRuntime(serverCoord);
+
+const server = serveChannel(runtime, appChannel, {
+  clientEnv: RuntimeCoordinate.env("frontend"), // env of the connecting clients
+  storage: storageAdapter,                       // backs identity + TOFU key pins (persistent)
+  handlers: [userHandler],                        // your local execution
+  carriers: [
+    wsAcceptorCarrier({ send: (ws, frame) => ws.send(frame), /* upgrade, hibernation */ }),
+    httpAcceptorCarrier(),                         // HTTP fallback (same channel)
+  ],
+});
+
+// Wire the host's events to the server:
+//   fetch(req)                     => server.fetch(req)
+//   webSocketMessage(ws, msg)      => server.duplex?.receive(ws, msg)
+//   webSocketClose/Error(ws)       => server.duplex?.drop(ws)
+```
+
+`serveChannel(runtime, channel, options)` returns `{ handlers, fetch, duplex?, pushToClient }`:
+
+- **`fetch`** — a web-standard handler that does the WS upgrade, the (secure or plain) HTTP action POST,
+  CORS preflight, and a `404` fallback. Forward the host's `fetch` straight to it.
+- **`duplex`** — the `{ receive, drop }` lifecycle for the *sole* duplex carrier (a shortcut for the
+  common single-WebSocket case; `undefined` when there are zero or several — then feed each carrier
+  handle directly).
+- **`pushToClient(target, request, opts?)`** — push a server-initiated action to one connected client
+  (see [Bi-directional](#bi-directional-communication-acceptor--connector)).
+- **`handlers`** — the acceptor handlers it built, one per duplex carrier (reach for these for per-handler
+  `broadcast`).
+
+Key options: `clientEnv` (required), `storage` (required only when a carrier is secure — the default),
+`carriers`, `handlers`, plus `securityLevel` / `link` / `verifyKeyResolver` / `defaultTimeout`.
+
+> On Cloudflare, [`@nice-code/action/platform/cloudflare`](#cloudflare-durable-objects) collapses the
+> Durable Object carrier + storage boilerplate to one-liners.
+
+### Connecting — `connectChannel`
+
+The connector has one runtime and `connectChannel`s to each acceptor it talks to. It routes the channel's
+`toAcceptor` domains out over the transports (first = preferred, rest = fallback) and registers local
+handlers for the `toConnector` pushes from `onPush` — all derived from the channel, no restated lists.
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  ESecurityLevel,
+  connectChannel,
+  secureTransport,
+  plainTransport,
+  wsCarrier,
+  httpCarrier,
+} from "@nice-code/action";
+
+export const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
+
+// A carrier wrapped in a security policy = a transport.
+const wsTransport = secureTransport({
+  channel: appChannel,
+  runtime: clientRuntime,        // its coordinate is the authenticated identity in the handshake
+  storageAdapter,                // persists this client's crypto identity across reloads
+  securityLevel: ESecurityLevel.encrypted,
+  carrier: wsCarrier("wss://api.example.com/resolve_action/ws"),
+});
+const httpTransport = plainTransport({
+  carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })),
+});
+
+connectChannel(clientRuntime, serverCoord, {
+  channel: appChannel,
+  transports: [wsTransport, httpTransport], // secure WS preferred, HTTP fallback
+  // onPush: { ... }  // handlers for the channel's toConnector pushes (see below)
+});
+```
+
+`connectChannel(runtime, acceptorCoordinate, options)` returns the `ConnectorHandler` so you can later
+`handler.clearTransportCache()` (which also closes any live sockets) on teardown. Options:
+
+- **`channel`** — the shared channel; its `toAcceptor`/`toConnector` drive all routing.
+- **`transports`** — to the acceptor, in preference order; all carry the same `toAcceptor` domains and the
+  manager falls through on failure.
+- **`onPush`** — handlers for the channel's `toConnector` pushes (optional; omit for send-only).
+- **`defaultTimeout`** — default per-action timeout.
+
+---
+
+## Calling actions
+
+Once a runtime is wired, calling an action looks the same regardless of where it resolves (locally or
+over a carrier):
+
+```ts
+// Run and get the output directly (throws on a declared/transport error)
+const output = await userDomain.action.getUser
+  .request({ userId: "u_123" })
+  .runToOutput();
+console.log(output); // { id: "u_123", name: "Alice" }
+
+// Or keep the RunningAction handle for progress/abort, then await the full result payload
+const running = await userDomain.runAction(userDomain.action.getUser.request({ userId: "u_123" }));
+const result = await running.waitForResultPayload();
+console.log(result.output);
+```
+
+---
+
+## Bi-directional communication (acceptor ⇆ connector)
+
+Over a **duplex** carrier (a WebSocket) the acceptor can call the connector back on the *same* open
+connection — no second channel, no polling. The shape:
+
+1. **Declare the push domain in the channel's `toConnector`** (shared by both ends).
+2. **On the connector**, handle those pushes with `connectChannel`'s `onPush` — keyed by action id,
+   typed from the channel. The reply routes straight back over the same socket.
+3. **On the acceptor**, use `server.pushToClient(...)` (one client) or a handler's `broadcast(...)`
+   (everyone). The originating client is available on any inbound action as
+   `action.context.originClient`.
+
+### Shared channel
+
+```ts
+// Bidirectional: client sends `start_feed`; server pushes `position_update` back.
+export const lobbyDomain = appRoot.createChildDomain({
+  domain: "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 = defineSecureChannel({
+  toAcceptor: [userDomain, lobbyDomain],  // start_feed flows here
+  toConnector: [lobbyDomain],             // position_update pushes back here
+});
+```
+
+### Connector side — handle pushes with `onPush`
+
+```ts
+connectChannel(clientRuntime, serverCoord, {
+  channel: appChannel,
+  transports: [wsTransport, httpTransport],
+  onPush: {
+    // Keyed by the toConnector action id; input + output typed from the channel.
+    position_update: async ({ player, x, y }) => {
+      renderPlayer(player, x, y);
+      return { acknowledged: true };
+    },
+  },
+});
+```
+
+### Acceptor side — push back
+
+The local handler reads `action.context.originClient` to know who asked, then pushes to them:
+
+```ts
+const lobbyHandler = createLocalHandler().forDomainActionCases(lobbyDomain, {
+  start_feed: async (action) => {
+    let delivered = 0;
+    for (let seq = 0; seq < action.input.count; seq++) {
+      const running = server.pushToClient(
+        action.context.originClient,                // the requesting client's coordinate
+        lobbyDomain.action.position_update.request({ player: "alice", x: 1, y: 2 }),
+      );
+      await running.waitForResultPayload(); // await the client's ack like any action
+      delivered++;
+    }
+    return { delivered };
+  },
+});
+```
+
+Fan one out to everyone on a carrier with a handler's `broadcast` (fire-and-forget; skip the origin or
+filter by connection):
+
+```ts
+server.handlers[0].broadcast(
+  () => lobbyDomain.action.position_update.request({ player: "system", x: 0, y: 0 }),
+  { except: originWs, where: (ws) => ws.deserializeAttachment()?.role === "player" },
+);
+```
+
+> **When a handler needs the originating connection itself** (to register it in a room, etc.) rather than
+> just the client coordinate, build connection-aware cases with `acceptChannelConnections(handler,
+> channel, { ... })` — each case receives the request *and* that client's live connection. See
+> [Lower-level building blocks](#lower-level-building-blocks).
+
+---
+
+## Cloudflare Durable Objects
+
+`@nice-code/action/platform/cloudflare` collapses the DO boilerplate (the `WebSocketPair` upgrade, the
+hibernation attachment wiring, and the DO-storage adapter) into one-liners you hand to `serveChannel`.
+The core library stays platform-agnostic — nothing here is reachable from the main entry.
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { ActionRuntime, serveChannel, httpAcceptorCarrier } from "@nice-code/action";
+import {
+  durableObjectWsCarrier,
+  durableObjectStorage,
+  type TDurableObjectChannelServer,
+} from "@nice-code/action/platform/cloudflare";
+
+export class MyDurableObject extends DurableObject {
+  private _server: TDurableObjectChannelServer | null = null;
+
+  private getServer(): TDurableObjectChannelServer {
+    if (this._server != null) return this._server;
+    const runtime = new ActionRuntime(serverCoord);
+
+    // One WS carrier (duplex — pushes + hibernation persistence) + a secure HTTP fallback (exchange),
+    // both sharing one crypto identity built from this DO's storage, surviving eviction.
+    this._server = serveChannel(runtime, appChannel, {
+      clientEnv: RuntimeCoordinate.env("frontend"),
+      storage: durableObjectStorage(this.ctx, { keyPrefix: "ws:" }),
+      handlers: [userHandler],
+      carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier()],
+    });
+    return this._server;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    return this.getServer().fetch(request);
+  }
+  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
+    this.getServer().duplex?.receive(ws, msg);
+  }
+  async webSocketClose(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
+  async webSocketError(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
+}
+```
+
+- **`durableObjectWsCarrier(ctx, { secure? })`** — a hibernatable-WebSocket acceptor carrier with `send`,
+  the `WebSocketPair` upgrade, and the hibernation hooks all derived from the DO's `ctx`. Pass
+  `secure: false` for a plain WS endpoint (then no `storage` is needed for it).
+- **`durableObjectStorage(ctx, { keyPrefix? })`** — wraps the DO's storage as a `StorageAdapter` for
+  `serveChannel`'s `storage`.
+
+Because the WS carrier persists each connection's binding on bind and replays it on construction, results
+and pushes still route to the right socket after the object wakes from eviction.
+
+---
+
+## Security levels
+
+`ESecurityLevel` (used by `secureTransport` and `serveChannel`):
+
+- **`none`** — identity self-asserted, no handshake. Fastest; fine for dev/trusted networks.
+- **`authenticated`** — the handshake verifies identity (sign/verify + trust-on-first-use key pin);
+  frames are unencrypted.
+- **`encrypted`** — authenticated *plus* every frame AES-GCM encrypted with the handshake-derived key.
+
+The connector picks its level; an acceptor by default **negotiates any of the three per connection**, so
+one endpoint serves all three. The client identifies itself with its runtime coordinate + a persisted
+crypto identity; the server pins client keys trust-on-first-use. Persisting the server's binding (via the
+hibernatable carrier) lets an `authenticated`/`encrypted` connection resume after eviction without
+re-handshaking.
+
+The whole thing rides one channel: the same `secureTransport({ carrier: wsCarrier(...) })` works at any
+level, and `httpCarrier` runs the *same* secure session over HTTP (handshake → token → encrypted frames),
+with the request/reply correlation provided for free by the HTTP transaction. Pair a secure WS with a
+plain HTTP fallback by giving the acceptor a `httpAcceptorCarrier({ secure: false })`.
+
+---
+
+## Multiple carriers on one runtime
+
+`serveChannel` accepts **any number of duplex carriers** (e.g. WebSocket + WebRTC) plus at most one
+exchange carrier. They all share one crypto identity and one runtime, and each result/push routes back
+over the carrier its client actually connected on (connection-aware return routing). With several duplex
+carriers, `server.duplex` is `undefined` — feed each carrier handle's own `receive`/`drop` directly.
+
+```ts
+const ws  = wsAcceptorCarrier({ send: wsSend, upgrade, hibernation });
+const rtc = rtcCarrier(/* ... */);
+const server = serveChannel(runtime, appChannel, {
+  clientEnv, storage,
+  carriers: [ws, rtc, httpAcceptorCarrier()],
+  handlers: [appHandler],
+});
+// route each host's events to the matching handle:
+//   onWsMessage(c, m)  => ws.receive(c, m)
+//   onRtcMessage(c, m) => rtc.receive(c, m)
+```
+
+On the connector side, list several transports in `connectChannel`'s `transports` (preference order) to
+get automatic fallback across carriers (e.g. secure WS, then plain HTTP).
+
+---
+
+## React Query integration
+
+```ts
+import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";
+
+// Query
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useActionQuery(
+    userDomain.action.getUser,
+    { userId },
+    { queryKey: ["user", userId] },
+  );
+  return <div>{data?.name}</div>;
+}
+
+// Mutation
+function RenameUser() {
+  const { mutate } = useActionMutation(userDomain.action.updateName);
+  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
+}
+```
+
+---
+
+## Devtools
+
+### Browser panel — `@nice-code/action/devtools/browser`
+
+A dockable in-app panel showing every action run: status, timing, input/output, routing, errors, and call stacks. Renders only when `NODE_ENV === "development"` (or with `forceEnable`).
+
+```tsx
+import { ActionDevtoolsCore, NiceActionDevtools } from "@nice-code/action/devtools/browser";
+
+const devtoolsCore = new ActionDevtoolsCore();
+devtoolsCore.attachToDomain(appRoot);
+
+function App() {
+  return (
+    <>
+      <MyApp />
+      <NiceActionDevtools core={devtoolsCore} position="dock-bottom" />
+    </>
+  );
+}
+```
+
+### Server logger — `@nice-code/action/devtools/server`
+
+Logs action lifecycle (started / progress / success / error) with timings — pretty lines or newline-delimited JSON.
+
+```ts
+import { ActionServerDevtools } from "@nice-code/action/devtools/server";
+
+const devtools = new ActionServerDevtools({ format: "json", logPayloads: false });
+devtools.attachToDomain(appRoot);
+```
+
+---
+
+## RuntimeCoordinate
+
+Identifies a runtime environment and is used to route actions to the right handler.
+
+```ts
+RuntimeCoordinate.env("backend")                                // named env
+RuntimeCoordinate.env("backend").specify({ perId: "worker-1" }) // env + instance
+RuntimeCoordinate.env("backend").withPersistentId(id.toString()) // env + persistent instance id
+RuntimeCoordinate.unknown                                        // unspecified
+```
+
+---
+
+## Error handling in actions
+
+Actions declared with `.throws(domain, ids?)` surface typed errors at the call site:
+
+```ts
+import { castNiceError } from "@nice-code/error";
+
+try {
+  const output = await userDomain.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);
+  }
+}
+```
+
+---
+
+## Lower-level building blocks
+
+`connectChannel` and `serveChannel` are sugar; reach for these when you need finer control.
+
+- **`ActionRuntime.connectTo(coordinate, { transports, domains, actions, localHandlers, defaultTimeout })`**
+  — what `connectChannel` desugars to: build a `ConnectorHandler` for a peer, route domains/actions to
+  it, register it (plus any local push handlers), and apply — in one call. Use it directly when your
+  routing isn't expressed as a single channel.
+
+- **Carriers vs transports.** A *carrier* (`wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`) is
+  raw byte movement; a *transport* (`secureTransport`, `plainTransport`) wraps one with a security policy.
+  `connectTo` takes transports; `serveChannel` takes acceptor carriers (`wsAcceptorCarrier`,
+  `httpAcceptorCarrier`) and applies the security policy itself.
+
+- **`acceptChannel(runtime, channel, { clientEnv, storageAdapter, send, ... })`** — build the secure
+  `AcceptorHandler` for a channel by hand (the accept-in counterpart to a single transport), when you're
+  not using `serveChannel`. Pair it with **`acceptChannelConnections(handler, channel, cases)`** to
+  register connection-aware execution — each case receives the request *and* the originating connection:
+
+  ```ts
+  const acceptor = acceptChannel(runtime, appChannel, { clientEnv, storageAdapter, send });
+  const cases = acceptChannelConnections(acceptor, appChannel, {
+    join: ({ input }, conn) => { if (conn != null) rooms.add(input.roomId, conn); return { ok: true }; },
+  });
+  runtime.addHandlers([cases, acceptor]).apply();
+  ```
+
+- **`createActionFetchHandler(runtime, options)`** — the web-standard `fetch` handler (CORS, action POST,
+  optional WS upgrade, 404) on its own, when you want the HTTP entry without `serveChannel`.
+
+- **`createHibernatableWsServerAdapter({ handler, getConnections, getAttachment, setAttachment })`** —
+  the hibernation persistence layer `serveChannel` wires automatically; use it directly with a hand-built
+  `AcceptorHandler`.
+
+- **`createBinaryWireAdapter(domains)`** / **`createBinaryWireSessionFactory(domains)`** — the positional
+  binary codecs `defineSecureChannel` builds for you; useful for custom carriers.
+
+- **`createInMemoryChannelPair()` / `inMemoryCarrier`** — wire two runtimes together in-process (tests,
+  same-process peers) with no network.
+
+- **Custom carriers** — for any channel nice-action doesn't model natively, implement an
+  `IDuplexCarrierSource` / `IExchangeCarrierSource` and hand it to `secureTransport` / `plainTransport`
+  (connector) or build an acceptor carrier for `serveChannel`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "main": "./build/index.cjs",
   "module": "./build/index.mjs",
   "types": "./build/index.d.cts",
@@ -86,9 +86,9 @@
   },
   "type": "module",
   "dependencies": {
-    "@nice-code/common-errors": "0.17.0",
-    "@nice-code/error": "0.17.0",
-    "@nice-code/util": "0.17.0",
+    "@nice-code/common-errors": "0.18.0",
+    "@nice-code/error": "0.18.0",
+    "@nice-code/util": "0.18.0",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",